@linzumi/cli 1.0.112 → 1.0.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "1.0.112",
+  "version": "1.0.113",
   "description": "Linzumi CLI \u2014 point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {

package/scripts/build-core-fate-ladder-parity-oracle.mjs

@@ -31,8 +31,13 @@ const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const driverSource = `
 import {
   appendFateLadderEntry,
+  commitFateLadderFailoverOutcome,
   commitFateLadderHoldDispatch,
   createFateLadderRun,
+  crossHarnessFailoverDetail,
+  crossHarnessFailoverEnabled,
+  crossHarnessFailoverReason,
+  crossHarnessFailoverRungSlot,
   decideFateLadderStep,
   defaultFateLadderBudgets,
   fateLadderBudgets,
@@ -66,6 +71,22 @@ function runJson(run) {
       atMs: entry.atMs,
       detail: entry.detail === undefined ? null : entry.detail,
       resetAtMs: entry.resetAtMs === undefined ? null : entry.resetAtMs,
+      failover:
+        entry.failover === undefined
+          ? null
+          : {
+              sourceHarness: entry.failover.sourceHarness,
+              targetHarness: entry.failover.targetHarness,
+              model: entry.failover.model === undefined ? null : entry.failover.model,
+              transpiledItemCount:
+                entry.failover.transpiledItemCount === undefined
+                  ? null
+                  : entry.failover.transpiledItemCount,
+              redactedReasoningCount:
+                entry.failover.redactedReasoningCount === undefined
+                  ? null
+                  : entry.failover.redactedReasoningCount,
+            },
     })),
   };
 }
@@ -131,8 +152,17 @@ function runScheduleCase(caseInput) {
           inPlaceResume: op.grants?.inPlaceResume === true,
           redispatch: op.grants?.redispatch === true,
           workerRebuild: op.grants?.workerRebuild === true,
+          crossHarnessFailover: op.grants?.crossHarnessFailover === true,
         },
         rateLimitResetAtMs: op.resetAtMs ?? undefined,
+        failover:
+          op.failover === undefined || op.failover === null
+            ? undefined
+            : {
+                sourceHarness: op.failover.sourceHarness,
+                targetHarness: op.failover.targetHarness,
+                model: op.failover.model ?? undefined,
+              },
       });
       if (decision.kind !== 'stand') {
         current = decision.run;
@@ -145,6 +175,24 @@ function runScheduleCase(caseInput) {
         current = commitFateLadderHoldDispatch(current, op.nowMs);
         steps.push({ run: runJson(current) });
       }
+    } else if (op.op === 'commitFailover') {
+      if (current === undefined) {
+        steps.push({ skipped: true });
+      } else {
+        current = commitFateLadderFailoverOutcome(current, {
+          outcome: op.outcome,
+          atMs: op.nowMs,
+          failover: {
+            sourceHarness: op.failover.sourceHarness,
+            targetHarness: op.failover.targetHarness,
+            model: op.failover.model ?? undefined,
+            transpiledItemCount: op.failover.transpiledItemCount ?? undefined,
+            redactedReasoningCount: op.failover.redactedReasoningCount ?? undefined,
+          },
+          detail: op.detail ?? undefined,
+        });
+        steps.push({ run: runJson(current) });
+      }
     } else if (op.op === 'append') {
       if (current === undefined) {
         steps.push({ skipped: true });
@@ -187,7 +235,25 @@ function runCase(input) {
         redispatchAfterLocalFailureReason,
         workerRebuildRetryReason,
         rateLimitHoldReasonPrefix,
+        crossHarnessFailoverRungSlot,
+        crossHarnessFailoverReason,
+        crossHarnessFailoverDetailSamples: [
+          crossHarnessFailoverDetail({
+            sourceHarness: 'codex',
+            targetHarness: 'claude_code',
+            model: 'parity-model-slug',
+            transpiledItemCount: 12,
+            redactedReasoningCount: 3,
+          }),
+          crossHarnessFailoverDetail({
+            sourceHarness: 'codex',
+            targetHarness: 'claude_code',
+            model: undefined,
+          }),
+        ],
       };
+    case 'failoverFlag':
+      return crossHarnessFailoverEnabled(input.env ?? {});
     case 'budgets':
       return fateLadderBudgets(input.env ?? {});
     case 'holdReason':

package/scripts/build-cross-harness-failover-oracle.mjs

@@ -0,0 +1,349 @@
+// F5 (compute-nodes program, Workstream F; plan kandan/plans/
+// 2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md).
+// Relationship: Builds the CROSS-HARNESS FAILOVER ORACLE - the in-process
+// driver of the REAL rung path for the F5 differential-harness acceptance
+// (packages/commander-harness/src/conformance/CrossHarnessFailoverConformance.res).
+//
+// The driver exercises the SHIPPED machinery end to end in one process:
+// the REAL channelSession (attachChannelSession: the fate-ladder consult,
+// the backend-dead trigger, the commit-then-advance receipts, the visible
+// I382 rung state) against a scripted dead-able codex client, with the
+// runner-shaped failover executor wired to the REAL transpilation bridge
+// (src/crossHarnessFailover.mjs: T.2 HarnessCodexTranspiler.exportPage ->
+// T.4 HarnessClaudeRehydration -> the claude session-store seeding into an
+// isolated F5_ORACLE_HOME). The conformance suite then completes the
+// resume leg on the seeded store through the REAL HarnessClaudeAdapter
+// against the scripted SDK double (the T.4 Direction-A mechanism) - the
+// spawned-commander environment cannot host a live claude harness, so the
+// in-process oracle is the honest home for the full "the coding job
+// resumes on the other harness" walk (the cluster-8/T.4 posture).
+//
+// Env knobs (set by the conformance suite):
+//   F5_ORACLE_HOME     - the isolated claude-store root the bridge seeds
+//   F5_ORACLE_CWD      - the thread's working directory (store keying)
+//   F5_ORACLE_EXECUTOR - 'bridge' (the REAL transpile+seed) | 'fail'
+//                        (a scripted executor failure: the honest-red leg)
+//
+// Output: ONE JSON report line on stdout:
+//   { ladderSteps, failoverLogs, visibleReasons, messageStates,
+//     seeded: { targetSessionId, sessionFile, transpiledItemCount,
+//               redactedReasoningCount } | null,
+//     executorRequest: { model, journalTurnIds, journalItemCount } | null }
+//
+// Determinism: scripted data + milestone polls only; no wall-clock rows.
+// The output is a local test artifact (.differential/ is gitignored).
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const driverSource = `
+import { attachChannelSession } from './src/channelSession';
+import type { HarnessActivityJournal } from './src/channelSession';
+import type { CodexAppServerClient } from './src/codexAppServer';
+import type { JsonObject, JsonRpcResponse, JsonValue } from './src/protocol';
+import type { PhoenixClient } from './src/phoenix';
+// The REAL transpilation bridge (T.2 export -> T.4 rehydration -> store
+// seeding) - the exact module the runner's production executor loads.
+import { transpileAndSeedClaudeSession } from './src/crossHarnessFailover.mjs';
+
+const oracleHome = process.env.F5_ORACLE_HOME;
+const oracleCwd = process.env.F5_ORACLE_CWD;
+const executorKind = process.env.F5_ORACLE_EXECUTOR ?? 'bridge';
+if (!oracleHome || !oracleCwd) {
+  throw new Error('F5_ORACLE_HOME and F5_ORACLE_CWD are required');
+}
+
+// The rung ships flag-gated; the oracle exercises the flag-ON path.
+process.env.LINZUMI_CROSS_HARNESS_FAILOVER = '1';
+
+const ladderSteps: Array<Record<string, unknown>> = [];
+const failoverLogs: Array<{ event: string; payload: Record<string, unknown> }> = [];
+const visibleReasons: string[] = [];
+const messageStates: Array<Record<string, unknown>> = [];
+let executorRequest: Record<string, unknown> | null = null;
+let seeded: Record<string, unknown> | null = null;
+let executorSettled = false;
+
+function okResponse(result: JsonValue): JsonRpcResponse {
+  return { jsonrpc: '2.0', id: 1, result };
+}
+
+// --- The scripted kandan side (minimal PhoenixClient double) ---------------
+const eventCallbacks = new Set<
+  (topic: string, event: string, payload: JsonValue) => void
+>();
+const kandan = {
+  join: async () => ({ cursor: 0 }),
+  unregisterJoin: () => undefined,
+  push: async (_topic: string, event: string, payload: JsonObject) => {
+    if (event === 'message_state') {
+      messageStates.push(payload as Record<string, unknown>);
+      if (typeof payload.reason === 'string') {
+        visibleReasons.push(payload.reason);
+      }
+    }
+    if (event === 'session:announce') {
+      return { status: 'ok', response: { seq: 10 } };
+    }
+    return { status: 'ok', response: {} };
+  },
+  pushIfConnected: async (_topic: string, event: string, payload: JsonObject) =>
+    kandan.push(_topic, event, payload),
+  onControl: () => undefined,
+  onEvent: (
+    callback: (topic: string, event: string, payload: JsonValue) => void
+  ) => {
+    eventCallbacks.add(callback);
+  },
+  onReconnect: () => undefined,
+  close: () => undefined,
+} as unknown as PhoenixClient;
+const emit = (topic: string, event: string, payload: JsonValue) => {
+  for (const callback of eventCallbacks) callback(topic, event, payload);
+};
+
+// --- The scripted dead-able codex backend ----------------------------------
+let turnStartCount = 0;
+const workerState = { closed: false };
+const codex: CodexAppServerClient = {
+  request: async (method) => {
+    if (workerState.closed) {
+      throw new Error('thread Codex worker IPC client is closed');
+    }
+    switch (method) {
+      case 'thread/start':
+      case 'thread/resume':
+        return okResponse({ thread: { id: 'oracle-codex-thread-1' } });
+      case 'turn/start':
+        turnStartCount += 1;
+        return okResponse({ turn: { id: 'oracle-turn-1' } });
+      case 'thread/read':
+        return okResponse({ thread: { turns: [] } });
+      default:
+        throw new Error('unexpected oracle codex request ' + method);
+    }
+  },
+  notify: () => undefined,
+  onNotification: () => undefined,
+  onRequest: () => undefined,
+  isClosed: () => workerState.closed,
+  close: () => {
+    workerState.closed = true;
+  },
+};
+
+async function waitFor(predicate: () => boolean, label: string): Promise<void> {
+  const deadline = Date.now() + 30_000;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error('timed out waiting for ' + label);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+async function run(): Promise<void> {
+  const token =
+    'fake.' +
+    Buffer.from(
+      JSON.stringify({ actor_id: 7, actor_username: 'oracle-owner' })
+    ).toString('base64url') +
+    '.sig';
+
+  const runtime = await attachChannelSession({
+    kandan,
+    codex,
+    topic: 'local_runner:oracle-f5-failover',
+    instanceId: 'instance-oracle-f5',
+    options: {
+      token,
+      runnerId: 'oracle-runner-1',
+      cwd: oracleCwd,
+      codexBin: 'node',
+      launchTui: false,
+      channelSession: {
+        workspaceSlug: 'oracle-workspace',
+        channelSlug: 'oracle-channel',
+        listenUser: 'oracle-owner',
+        kandanThreadId: 'oracle-kandan-thread-1',
+        rootSeq: 60,
+        codexThreadId: 'oracle-codex-thread-1',
+        // D39: the turn/session spec's model slug, asserted byte-equal on
+        // the receipts by the conformance suite.
+        model: 'oracle-model-slug',
+        streamFlushMs: 0,
+      },
+      crossHarnessFailover: {
+        targetHarness: 'claude_code',
+        execute: async (request) => {
+          executorRequest = {
+            kandanThreadId: request.kandanThreadId,
+            codexThreadId: request.codexThreadId ?? null,
+            queuedSeq: request.queuedSeq,
+            messageBody: request.message.body,
+            model: request.model ?? null,
+            journalTurnIds: request.activity.turns.map((turn) => turn.turnId),
+            journalItemCount: request.activity.itemCount,
+          };
+          try {
+            if (executorKind === 'fail') {
+              return { ok: false as const, failure: 'scripted executor failure' };
+            }
+            const result = await transpileAndSeedClaudeSession({
+              activity: request.activity as HarnessActivityJournal,
+              codexThreadId: request.codexThreadId ?? 'unknown-codex-session',
+              kandanThreadId: request.kandanThreadId,
+              cwd: oracleCwd,
+              home: oracleHome,
+            });
+            if (!result.ok) {
+              return { ok: false as const, failure: result.failure };
+            }
+            seeded = {
+              targetSessionId: result.targetSessionId,
+              sessionFile: result.sessionFile,
+              transpiledItemCount: result.transpiledItemCount,
+              redactedReasoningCount: result.redactedReasoningCount,
+            };
+            return {
+              ok: true as const,
+              transpiledItemCount: result.transpiledItemCount,
+              redactedReasoningCount: result.redactedReasoningCount,
+              targetSessionId: result.targetSessionId,
+            };
+          } finally {
+            executorSettled = true;
+          }
+        },
+      },
+    },
+    log: (event: string, payload: Record<string, unknown>) => {
+      if (event === 'codex.fate_ladder_step') {
+        ladderSteps.push(payload);
+      }
+      if (event.startsWith('codex.fate_ladder_cross_harness_failover')) {
+        failoverLogs.push({ event, payload });
+      }
+    },
+  });
+
+  // The user's coding-job message -> the turn dispatches on codex.
+  emit('chat:oracle-workspace:oracle-channel', 'event', {
+    seq: 61,
+    type: 'thread.message',
+    actor: { kind: 'human', slug: 'oracle-owner' },
+    actor_user_id: 7,
+    body: 'keep working on the migration',
+    payload: { thread_id: 'oracle-kandan-thread-1', reply_to_seq: 60 },
+  });
+  await waitFor(() => turnStartCount >= 1, 'the codex dispatch');
+
+  // The recorded activity the failover exports: a realistic little session
+  // walk INCLUDING a reasoning item (so redaction accounting is exercised).
+  runtime.handleCodexNotification('turn/started', {
+    threadId: 'oracle-codex-thread-1',
+    turn: { id: 'oracle-turn-1' },
+  });
+  const items: JsonObject[] = [
+    {
+      id: 'oracle-item-1',
+      type: 'userMessage',
+      content: [{ type: 'text', text: 'keep working on the migration' }],
+    },
+    { id: 'oracle-item-2', type: 'reasoning', summary: [] },
+    {
+      id: 'oracle-item-3',
+      type: 'agentMessage',
+      text: 'renamed the column and updated 3 call sites so far',
+    },
+  ];
+  for (const item of items) {
+    runtime.handleCodexNotification('item/completed', {
+      threadId: 'oracle-codex-thread-1',
+      turnId: 'oracle-turn-1',
+      item,
+      completedAtMs: 1_784_000_000_000,
+    });
+  }
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  // THE BACKEND DIES (the precise F5 trigger: the worker/IPC client is
+  // gone), then the infra-kill terminal lands with fate transient_local.
+  workerState.closed = true;
+  runtime.handleCodexNotification('turn/failed', {
+    threadId: 'oracle-codex-thread-1',
+    turnId: 'oracle-turn-1',
+    reason: 'thread Codex worker exited',
+    retryable: true,
+    fate: 'transient_local',
+  });
+
+  await waitFor(() => executorSettled, 'the failover executor');
+  if (executorKind === 'fail') {
+    await waitFor(
+      () =>
+        messageStates.some(
+          (state) =>
+            state.status === 'failed' &&
+            typeof state.reason === 'string' &&
+            (state.reason as string).includes('cross-harness failover')
+        ),
+      'the honest failover_failed red'
+    );
+  }
+  // Let the post-executor bookkeeping settle.
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  await runtime.close();
+
+  process.stdout.write(
+    JSON.stringify({
+      ladderSteps,
+      failoverLogs,
+      visibleReasons,
+      messageStates,
+      seeded,
+      executorRequest,
+      turnStartCount,
+    }) + '\\n'
+  );
+}
+
+run().then(
+  () => process.exit(0),
+  (error) => {
+    process.stderr.write(
+      String(error && error.stack ? error.stack : error) + '\\n'
+    );
+    process.exit(1);
+  }
+);
+`;
+
+const outDir = join(packageRoot, '.differential');
+const outPath = join(outDir, 'cross-harness-failover-oracle.mjs');
+
+await mkdir(outDir, { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'cross-harness-failover-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: outPath,
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  logLevel: 'silent',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});
+
+process.stdout.write(outPath + '\n');

package/scripts/build-differential-entry.mjs

@@ -133,7 +133,8 @@ const outfile =
     ? join(packageRoot, '.differential/impl-ts.mjs')
     : join(packageRoot, `.differential/impl-ts.mutant-${mutation.name}.mjs`);
 
-const mutationHooks = mutation === undefined ? undefined : mutationPlugin(mutation);
+const mutationHooks =
+  mutation === undefined ? undefined : mutationPlugin(mutation);
 
 await build({
   entryPoints: [join(packageRoot, 'src/differentialCommanderEntry.ts')],
@@ -158,3 +159,22 @@ await copyFile(
   join(packageRoot, 'src/assets/linzumi-logo.svg'),
   join(packageRoot, '.differential/assets/linzumi-logo.svg')
 );
+
+// F5: the cross-harness failover bridge rides next to the bundle exactly as
+// it does in dist/ (the runner dynamic-imports ./crossHarnessFailover.mjs
+// relative to import.meta.url), bundled with the compiled ReScript
+// transpiler artifacts resolved at build time. Unlike the dist build there
+// is NO stub fallback here: the differential harness must exercise the REAL
+// transpile leg, so missing artifacts fail this build loudly.
+await build({
+  entryPoints: [join(packageRoot, 'src/crossHarnessFailover.mjs')],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/crossHarnessFailover.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  banner,
+});

package/scripts/build.mjs

@@ -1,6 +1,6 @@
 // Spec: plans/2026-05-17-linzumi-cli-node-toolchain-note.md
 // Relationship: Builds the published CLI package with Node-hosted tooling.
-import { copyFile, mkdir, rm } from 'node:fs/promises';
+import { copyFile, mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
@@ -84,6 +84,45 @@ await build({
   banner,
 });
 
+// F5 cross-harness failover bridge (Workstream F task F5): the runner
+// dynamic-imports ./crossHarnessFailover.mjs relative to its own bundle, so
+// dist ships a self-contained sibling bundle with the compiled ReScript
+// transpiler artifacts (packages/linzumi-cli-rescript, built by `rescript`)
+// resolved at build time. When the artifacts are not built in this checkout
+// the publish must not silently ship a broken rung: emit an HONEST stub
+// whose import succeeds but whose executor refuses loudly - the ladder then
+// terminates red-with-receipts exactly as F2 (the flag's rollback posture) -
+// and warn in the build log.
+try {
+  await build({
+    entryPoints: [join(packageRoot, 'src/crossHarnessFailover.mjs')],
+    bundle: true,
+    platform: 'node',
+    target: 'node20',
+    format: 'esm',
+    outfile: join(packageRoot, 'dist/crossHarnessFailover.mjs'),
+    minify: true,
+    sourcemap: false,
+    legalComments: 'none',
+    banner,
+  });
+} catch (error) {
+  console.warn(
+    '[build] cross-harness failover bridge could not be bundled (are the ' +
+      'linzumi-cli-rescript artifacts built?); shipping the honest refusal ' +
+      `stub instead: ${error instanceof Error ? error.message : String(error)}`
+  );
+  await writeFile(
+    join(packageRoot, 'dist/crossHarnessFailover.mjs'),
+    'export async function transpileAndSeedClaudeSession() {\n' +
+      '  return {\n' +
+      '    ok: false,\n' +
+      "    failure: 'the cross-harness failover transpiler bridge was not bundled into this build',\n" +
+      '  };\n' +
+      '}\n'
+  );
+}
+
 await mkdir(join(packageRoot, 'dist/assets'), { recursive: true });
 await copyFile(
   join(packageRoot, 'src/assets/linzumi-logo.svg'),