fix: address code review findings on update lifecycle and token caps

- Centralize the remaining-context-window clamp in computeCompletionBudgetCap
  so every provider benefits, and pass usedContextTokens from compaction —
  the near-full request the cap exists for. Remove the per-provider
  MaxCompletionTokensOptions duplication from kosong.
- Clear the pending update record once the activation failure limit is
  reached so startup and /update stop reporting a dead update forever.
- Keep lastFailure across a successful prepare so invalid-artifact
  activations accumulate toward the failure threshold.
- Retain a verified pending update while a newer preparation runs.
- Scope failure-attempt increments by operation; record install failures
  with operation: 'install'.
- Return whether background prepare/install actually started and map a
  refused start to 'in-progress' instead of claiming 'started'.
- Make writeJsonFile fsync opt-in ({ durable: true }, install.json only).
- Dedupe formatErrorMessage into cli/update/format-error.ts; normalize
  appendLog chunks instead of duplicated branches; z.uuid(); source-neutral
  update-preference wording; align pythinker upgrade docs; skip the
  POSIX-only detached-helper test on Windows; exact helper spawn asserts.

Author: elkaix

apps/pythinker-code/src/cli/update/activation.ts

@@ -6,6 +6,7 @@ import {
   activateHomebrewUpdate,
   PreparedHomebrewUpdateInvalidError,
 } from './homebrew';
+import { formatErrorMessage } from './format-error';
 import { tryAcquireUpdateInstallLock, type UpdateInstallLockHandle } from './install-lock';
 import { readUpdateInstallState, writeUpdateInstallState } from './install-state';
 import { detectInstallSource } from './source';
@@ -52,10 +53,6 @@ function activationAttempts(state: UpdateInstallState, version: string): number
   return failure?.version === version && failure.operation === 'activate' ? failure.attempts : 0;
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function isRunningPreparedVersion(currentVersion: string, preparedVersion: string): boolean {
   return (
     valid(currentVersion) !== null &&
@@ -77,6 +74,11 @@ export async function activatePendingUpdate(
     return { status: 'none' as const };
   }
 
+  if (await deps.detectSource() !== pending.source) {
+    await deps.writeState({ ...state, active: null, pending: null });
+    return { status: 'invalidated' as const, version: pending.version };
+  }
+
   if (isRunningPreparedVersion(currentVersion, pending.version)) {
     const installedAt = deps.now().toISOString();
     await deps.writeState({
@@ -92,12 +94,10 @@ export async function activatePendingUpdate(
     return { status: 'finalized' as const, version: currentVersion };
   }
 
-  if (await deps.detectSource() !== pending.source) {
-    await deps.writeState({ ...state, active: null, pending: null });
-    return { status: 'invalidated' as const, version: pending.version };
-  }
-
   if (activationAttempts(state, pending.version) >= ACTIVATION_FAILURE_LIMIT) {
+    // Terminal: drop the pending record (keeping lastFailure for preflight)
+    // so later launches stop retrying and reporting an in-progress update.
+    await deps.writeState({ ...state, pending: null });
     return {
       status: 'failed' as const,
       version: pending.version,
@@ -116,7 +116,7 @@ export async function activatePendingUpdate(
       ...state,
       active: {
         version: pending.version,
-        source: 'homebrew',
+        source: pending.source,
         operation: 'activate',
         jobId: pending.jobId,
         startedAt,
@@ -127,22 +127,34 @@ export async function activatePendingUpdate(
 
     try {
       const activated = await deps.activateHomebrew(pending);
+      await deps.writeState({
+        ...activatingState,
+        active: null,
+        lastFailure: null,
+      });
       return {
         status: 'activated' as const,
         version: activated.version,
         executable: activated.executable,
       };
     } catch (error) {
-      const message = errorMessage(error);
+      const message = formatErrorMessage(error);
       if (error instanceof PreparedHomebrewUpdateInvalidError) {
+        // Carry the cumulative prepare-failure count so repeated invalid
+        // artifacts can reach the auto-install failure threshold.
+        const priorFailure = activatingState.lastFailure;
+        const prepareAttempts =
+          priorFailure?.version === pending.version && priorFailure.operation === 'prepare'
+            ? priorFailure.attempts + 1
+            : 1;
         await deps.writeState({
           ...activatingState,
           active: null,
           pending: null,
           lastFailure: {
             version: pending.version,
             failedAt: deps.now().toISOString(),
-            attempts: 1,
+            attempts: prepareAttempts,
             operation: 'prepare',
             message,
           },

apps/pythinker-code/src/cli/update/format-error.ts

@@ -0,0 +1,4 @@
+/** Shared failure-message formatter for update install/prepare/activate state. */
+export function formatErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

apps/pythinker-code/src/cli/update/homebrew.ts

@@ -107,10 +107,12 @@ export async function runHomebrewCommand(
   let logWrites = Promise.resolve();
   const appendLog = (chunk: string | Uint8Array): void => {
     if (logFile === undefined) return;
+    // Normalize to bytes: FileHandle.write has separate string/buffer
+    // overloads that reject the union type.
+    const data = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
     logWrites = logWrites
       .then(async () => {
-        if (typeof chunk === 'string') await logFile.write(chunk);
-        else await logFile.write(chunk);
+        await logFile.write(data);
       })
       .catch(() => {});
   };

apps/pythinker-code/src/cli/update/install-state.ts

@@ -27,13 +27,13 @@ const UpdateInstallStateSchema: z.ZodType<UpdateInstallState> = z
         startedAt: z.string().min(1),
         pid: z.number().int().positive().optional(),
         operation: UpdateInstallOperationSchema.optional(),
-        jobId: z.string().uuid().optional(),
+        jobId: z.uuid().optional(),
       })
       .strict()
       .nullable(),
     pending: z
       .object({
-        jobId: z.string().uuid(),
+        jobId: z.uuid(),
         source: z.literal('homebrew'),
         version: z.string().min(1),
         preparedAt: z.string().min(1),
@@ -84,5 +84,5 @@ export async function writeUpdateInstallState(
   value: UpdateInstallState,
   filePath: string = getUpdateInstallStateFile(),
 ): Promise<void> {
-  await writeJsonFile(filePath, UpdateInstallStateSchema, value);
+  await writeJsonFile(filePath, UpdateInstallStateSchema, value, { durable: true });
 }