@linzumi/cli 1.0.99 → 1.0.100

package/README.md

@@ -58,7 +58,7 @@ Install the CLI or run it with `npx`:
 ```bash
 npm install -g @linzumi/cli@latest
 npx -y @linzumi/cli@latest signup
-npx -y @linzumi/cli@1.0.99 --version
+npx -y @linzumi/cli@1.0.100 --version
 linzumi --version
 ```
 

package/dist/index.js

@@ -1470,7 +1470,7 @@ To kick the agent off:
 `,L=Buffer.byteLength(P,"utf8");if(L>s)return l("runner_diagnostics.spool_entry_dropped",{reason:"entry_too_large",entry_bytes:L,max_entry_bytes:s}),!1;Xve(n,{recursive:!0}),m(u)+L>i&&f(),_(L);let D=w()?`
 `:"";return Gve(u,`${D}${P}`,"utf8"),!0}catch(R){return l("runner_diagnostics.spool_failed",{error:R instanceof Error?R.message:String(R)}),!1}},v=k=>{let R=[],P=eSe(k,"utf8");for(let L of P.split(`
 `))if(L.trim()!=="")try{let D=JSON.parse(L);D!==null&&typeof D=="object"&&R.push({parsed:D,raw:L})}catch{}return R};return{append:S,drain:async k=>{if(c)return{uploadedBatches:0,uploadedEntries:0,remainingBatches:p().length,skipped:!0};c=!0;let R=0,P=0;try{f(),_(0);let L=a()-o;for(let D of p()){let j;try{j=v(D)}catch(Z){l("runner_diagnostics.spool_batch_unreadable",{file:D,error:Z instanceof Error?Z.message:String(Z)}),y(D,"unreadable");continue}let q=j.filter(Z=>{let fe=ySe(Z.parsed);return fe===void 0||fe>=L});if(q.length===0){y(D,"empty_or_expired");continue}let E=XT(D,".jsonl"),B=q.map(Z=>Z.raw).join(`
-`),z=q.map(Z=>Z.parsed.spooled_at).filter(Z=>typeof Z=="string"),W={bundle_name:"runner-diagnostics-spool",exported_at:new Date(a()).toISOString(),idempotency_key:E,diagnostics:{kind:"runner_diagnostic_log",spool_batch:!0,idempotency_key:E,entry_count:q.length,...z.length===0?{}:{first_spooled_at:z[0],last_spooled_at:z[z.length-1]}},telemetry_ndjson:B};try{await k(W)}catch(Z){l("runner_diagnostics.spool_upload_failed",{file:D,remaining_batches:p().length,error:Z instanceof Error?Z.message:String(Z)});break}R+=1,P+=q.length;try{s9(D)}catch(Z){l("runner_diagnostics.spool_delete_failed",{file:D,error:Z instanceof Error?Z.message:String(Z)})}}}catch(L){l("runner_diagnostics.spool_drain_failed",{error:L instanceof Error?L.message:String(L)})}finally{c=!1}return{uploadedBatches:R,uploadedEntries:P,remainingBatches:p().length,skipped:!1}},pendingBatchFiles:p}}var sSe,aSe,dSe,uSe,cSe,a9,pSe,fSe,u9=F(()=>{"use strict";Zy();sSe=32*1024*1024,aSe=10080*60*1e3,dSe=4*1024*1024,uSe=1024*1024,cSe="spool.jsonl",a9=/^batch-(\d{1,16})-[0-9a-f-]+\.jsonl$/;pSe=/\b([A-Z][A-Z0-9_]{1,})=("[^"\n]*"|'[^'\n]*'|[^\s"'`;,)\]}]+)/g,fSe=/(?:\/(?:[A-Za-z0-9._@~+-]|%[0-9A-Fa-f]{2})+){2,}/g});var jt,eP,ea=F(()=>{"use strict";jt="1.0.99",eP=`linzumi ${jt}`});import{closeSync as l9,existsSync as tP,mkdirSync as xSe,openSync as p9,readFileSync as f9,renameSync as _Se,unlinkSync as md,writeFileSync as bSe,writeSync as m9}from"node:fs";import{dirname as h9,join as wSe}from"node:path";function rP(e){return e instanceof hs||e instanceof Error&&e.name===y9&&"lockPath"in e&&"heldBy"in e}function oP(e,n=Vn(),t){let r=t===void 0?encodeURIComponent(e):ad(t);return wSe(h9(n),"runners",`${r}.lock`)}function s0(e){let n=oP(e.machineId,e.configPath,e.linzumiUrl),t=e.isPidAlive??k9,r=e.now??(()=>new Date),o=e.killPid??OSe,i=r().toISOString(),s={version:1,machineId:e.machineId,runnerId:e.runnerId,pid:e.pid??process.pid,cwd:e.cwd,workspace:e.workspace,...e.linzumiUrl===void 0?{}:{linzumiUrl:Fn(e.linzumiUrl)},...e.launchSource===void 0?{}:{launchSource:e.launchSource},startedAt:i,heartbeatAt:i,cliVersion:e.cliVersion??jt,...e.gracefulUpdateDrain===!0?{gracefulUpdateDrain:!0}:{}};CSe(e.machineId,e.configPath,e.linzumiUrl,t,r,o,e.onTakeover),TSe(n,s,t,r,o,e.onTakeover,e.beforeReadExistingLock,e.beforeReplaceStaleLock);let a=()=>x9(n,s,r),d=setInterval(a,g9);return d.unref(),{path:n,record:s,heartbeat:a,release:()=>{clearInterval(d),v9(n,s)}}}function x9(e,n,t){try{let r=d0(e);if(r===void 0||r.machineId!==n.machineId||r.runnerId!==n.runnerId||r.pid!==n.pid||r.startedAt!==n.startedAt)return;let o={...r,heartbeatAt:t().toISOString()},i=`${e}.tmp`;bSe(i,`${JSON.stringify(o,null,2)}
+`),z=q.map(Z=>Z.parsed.spooled_at).filter(Z=>typeof Z=="string"),W={bundle_name:"runner-diagnostics-spool",exported_at:new Date(a()).toISOString(),idempotency_key:E,diagnostics:{kind:"runner_diagnostic_log",spool_batch:!0,idempotency_key:E,entry_count:q.length,...z.length===0?{}:{first_spooled_at:z[0],last_spooled_at:z[z.length-1]}},telemetry_ndjson:B};try{await k(W)}catch(Z){l("runner_diagnostics.spool_upload_failed",{file:D,remaining_batches:p().length,error:Z instanceof Error?Z.message:String(Z)});break}R+=1,P+=q.length;try{s9(D)}catch(Z){l("runner_diagnostics.spool_delete_failed",{file:D,error:Z instanceof Error?Z.message:String(Z)})}}}catch(L){l("runner_diagnostics.spool_drain_failed",{error:L instanceof Error?L.message:String(L)})}finally{c=!1}return{uploadedBatches:R,uploadedEntries:P,remainingBatches:p().length,skipped:!1}},pendingBatchFiles:p}}var sSe,aSe,dSe,uSe,cSe,a9,pSe,fSe,u9=F(()=>{"use strict";Zy();sSe=32*1024*1024,aSe=10080*60*1e3,dSe=4*1024*1024,uSe=1024*1024,cSe="spool.jsonl",a9=/^batch-(\d{1,16})-[0-9a-f-]+\.jsonl$/;pSe=/\b([A-Z][A-Z0-9_]{1,})=("[^"\n]*"|'[^'\n]*'|[^\s"'`;,)\]}]+)/g,fSe=/(?:\/(?:[A-Za-z0-9._@~+-]|%[0-9A-Fa-f]{2})+){2,}/g});var jt,eP,ea=F(()=>{"use strict";jt="1.0.100",eP=`linzumi ${jt}`});import{closeSync as l9,existsSync as tP,mkdirSync as xSe,openSync as p9,readFileSync as f9,renameSync as _Se,unlinkSync as md,writeFileSync as bSe,writeSync as m9}from"node:fs";import{dirname as h9,join as wSe}from"node:path";function rP(e){return e instanceof hs||e instanceof Error&&e.name===y9&&"lockPath"in e&&"heldBy"in e}function oP(e,n=Vn(),t){let r=t===void 0?encodeURIComponent(e):ad(t);return wSe(h9(n),"runners",`${r}.lock`)}function s0(e){let n=oP(e.machineId,e.configPath,e.linzumiUrl),t=e.isPidAlive??k9,r=e.now??(()=>new Date),o=e.killPid??OSe,i=r().toISOString(),s={version:1,machineId:e.machineId,runnerId:e.runnerId,pid:e.pid??process.pid,cwd:e.cwd,workspace:e.workspace,...e.linzumiUrl===void 0?{}:{linzumiUrl:Fn(e.linzumiUrl)},...e.launchSource===void 0?{}:{launchSource:e.launchSource},startedAt:i,heartbeatAt:i,cliVersion:e.cliVersion??jt,...e.gracefulUpdateDrain===!0?{gracefulUpdateDrain:!0}:{}};CSe(e.machineId,e.configPath,e.linzumiUrl,t,r,o,e.onTakeover),TSe(n,s,t,r,o,e.onTakeover,e.beforeReadExistingLock,e.beforeReplaceStaleLock);let a=()=>x9(n,s,r),d=setInterval(a,g9);return d.unref(),{path:n,record:s,heartbeat:a,release:()=>{clearInterval(d),v9(n,s)}}}function x9(e,n,t){try{let r=d0(e);if(r===void 0||r.machineId!==n.machineId||r.runnerId!==n.runnerId||r.pid!==n.pid||r.startedAt!==n.startedAt)return;let o={...r,heartbeatAt:t().toISOString()},i=`${e}.tmp`;bSe(i,`${JSON.stringify(o,null,2)}
 `,"utf8"),_Se(i,e)}catch{}}function hd(e,n,t){if(!n(e.pid))return{state:"dead"};let r=e.heartbeatAt??e.startedAt,o=Date.parse(r);return Number.isNaN(o)||t().getTime()-o>vSe?{state:"wedged",reason:e.heartbeatAt===void 0?"missing_heartbeat":"stale_heartbeat"}:{state:"live"}}function _9(e,n,t,r){return t!==a0||e.launchSource!==a0?!1:r.state!=="live"?!0:SSe(n,e.cliVersion)>0}function SSe(e,n){let t=c9(e),r=c9(n);for(let o=0;o<3;o++){let i=t.core[o],s=r.core[o];if(i===void 0||s===void 0)throw new Error(`compareCliVersions: unexpected undefined at core index ${o}`);if(i!==s)return i>s?1:-1}return t.prerelease.length===0&&r.prerelease.length===0?0:t.prerelease.length===0?1:r.prerelease.length===0?-1:kSe(t.prerelease,r.prerelease)}function c9(e){let n=e.trim().replace(/^v/i,"").split("+",1)[0]??"",t=n.indexOf("-"),r=t===-1?n:n.slice(0,t),o=t===-1?"":n.slice(t+1),i=r.split("."),s=[nP(i[0]),nP(i[1]),nP(i[2])],a=o===""?[]:o.split(".").filter(d=>d!=="");return{core:s,prerelease:a}}function nP(e){let n=Number.parseInt(e??"",10);return Number.isInteger(n)&&n>=0?n:0}function kSe(e,n){let t=Math.max(e.length,n.length);for(let r=0;r<t;r++){let o=e[r],i=n[r];if(o===void 0)return-1;if(i===void 0)return 1;let s=Number.parseInt(o,10),a=Number.parseInt(i,10),d=s.toString()===o,u=a.toString()===i;if(d&&u){if(s!==a)return s>a?1:-1}else{if(d!==u)return d?-1:1;if(o!==i)return o>i?1:-1}}return 0}function b9(e,n,t,r,o){try{r(n.pid)}catch(i){let s=i!==null&&typeof i=="object"&&"code"in i?i.code:void 0;if(s!=="ESRCH")throw s==="EPERM"||s==="EACCES"?new Error(`Cannot take over the runner lock at ${e}: its holder process (pid ${n.pid}) is owned by another user and cannot be stopped. Stop that process, or remove the lock file, then retry.`):i}o?.({lockPath:e,holderPid:n.pid,holderRunnerId:n.runnerId,reason:t})}function CSe(e,n,t,r,o,i,s){if(t===void 0||yr(t)!==yr(Bt))return;let a=oP(e,n),d=d0(a);if(d!==void 0){if(hd(d,r,o).state==="live")throw new hs(a,d);w9(a,r,()=>{let u=tP(a)?iP(a):void 0;if(u===void 0)return;let c=hd(u,r,o);if(c.state==="live")throw new hs(a,u);c.state==="wedged"&&b9(a,u,c.reason,i,s),md(a)})}}function TSe(e,n,t,r,o,i,s,a){if(i0(e,n))return;s?.();let d=d0(e);if(d===void 0){if(i0(e,n))return;throw new Error(`another Linzumi runner lock appeared while starting: ${e}`)}if(hd(d,t,r).state==="live")throw new hs(e,d);a?.(),w9(e,t,()=>{let u=tP(e)?iP(e):void 0;if(u!==void 0){let c=hd(u,t,r);if(c.state==="live")throw new hs(e,u);c.state==="wedged"&&b9(e,u,c.reason,o,i),md(e)}if(!i0(e,n))throw new Error(`another Linzumi runner lock appeared while starting: ${e}`)})}function i0(e,n){xSe(h9(e),{recursive:!0});try{let t=p9(e,"wx");try{m9(t,`${JSON.stringify(n,null,2)}
 `)}finally{l9(t)}return!0}catch(t){if(zc(t,"EEXIST"))return!1;throw t}}function w9(e,n,t){let r=`${e}.replace`;for(;;)try{let o=p9(r,"wx");try{m9(o,`${process.pid}
 `),t()}finally{l9(o),md(r)}return}catch(o){if(zc(o,"EEXIST")){let i=PSe(r);if(i===void 0)continue;if(n(i))throw new Error(["another Linzumi runner is already replacing a stale runner lock",`lock: ${e}`,"Wait for that startup to finish, then retry."].join(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "1.0.99",
+  "version": "1.0.100",
   "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-transport-parity-oracle.mjs

@@ -0,0 +1,688 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 4, transport-phoenix).
+// Relationship: Builds the TS-side PARITY ORACLE for the transport cluster
+// of the ReScript commander port, the sibling of
+// build-protocol-parity-oracle.mjs (cluster 1) /
+// build-config-identity-parity-oracle.mjs (cluster 2) /
+// build-auth-parity-oracle.mjs (cluster 3). Two modes in one bundle:
+//
+//   BATCH (default): a JSON array of pure-transform cases on stdin, a JSON
+//   array of results on stdout - phoenixWebsocketUrl / protocols, the
+//   frame codec, the typed push-error factory table with its
+//   connection-lost/wait classification, the exported reconnect-backoff
+//   config, and redactForCliLog (the structured log redactor the ported
+//   transport's audit snippet mirrors).
+//
+//   FLOW (--flow): a long-lived JSON-lines scenario driver around the REAL
+//   connectPhoenixClient (phoenix.ts) - the TS leg of the transport
+//   differential. Commands arrive one JSON object per stdin line; the
+//   driver emits {"obs": ...} observation lines (controls dispatched, push
+//   outcomes with phase/reason, disconnect/reconnect firings, operator
+//   notices, cursor/epoch store calls) in the client's own event order and
+//   {"id", ...} completion lines per command. The commander-harness
+//   conformance suite (TransportPhoenixParityConformance.res) runs the
+//   SAME command list against the ReScript transport in-process and
+//   asserts byte-identical normalized transcripts - the transport-seam
+//   differential against the M2.2 scripted kandan server.
+//
+// Cursor stores in flow mode are the REAL runner.ts file stores
+// (createControlCursorFileStore / createRunnerControlEpochStore), so the
+// cross-impl cursor-file legs compare the exact bytes the TS commander
+// would write and read.
+//
+// Determinism: wall-clock-shaped values never enter observations verbatim
+// (session durations become presence flags; timeout-budget digits are
+// normalized by the harness on both legs). The oracle only ever sees the
+// conformance suite's synthetic tokens.
+//
+// The output is a local test artifact (.differential/ is gitignored, never
+// published) and stays unminified for debuggability.
+import { copyFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const driverSource = `
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import {
+  connectPhoenixClient,
+  decodeFrame,
+  encodeFrame,
+  isPhoenixConnectionLostError,
+  isPhoenixConnectionWaitError,
+  isPhoenixPushError,
+  phoenixPushErrors,
+  phoenixReconnectBackoffConfig,
+  phoenixWebsocketProtocols,
+  phoenixWebsocketUrl,
+  type PhoenixClient,
+  type PhoenixControlCursorStore,
+  type PhoenixControlEpochStore,
+  type PhoenixPushErrorPhase,
+} from './src/phoenix';
+import {
+  createControlCursorFileStore,
+  createRunnerControlEpochStore,
+} from './src/runner';
+import { redactForCliLog } from './src/runnerLogger';
+import type { JsonObject, JsonValue } from './src/protocol';
+
+// --- Shared helpers -------------------------------------------------------------
+
+function outcome(run: () => unknown): unknown {
+  try {
+    const value = run();
+    return value === undefined ? { defined: false } : { defined: true, value };
+  } catch (error) {
+    return {
+      threw: true,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+// --- BATCH mode ------------------------------------------------------------------
+
+type PushErrorRow = {
+  readonly name: string;
+  readonly phase: string;
+  readonly reason: string;
+  readonly message: string;
+  readonly isPushError: boolean;
+  readonly isLost: boolean;
+  readonly isWait: boolean;
+};
+
+function pushErrorTable(): PushErrorRow[] {
+  const entries: ReadonlyArray<readonly [string, Error]> = [
+    ['socketClosed', phoenixPushErrors.socketClosed()],
+    ['reconnectFailed', phoenixPushErrors.reconnectFailed()],
+    ['socketNotOpen', phoenixPushErrors.socketNotOpen()],
+    ['clientClosedWait', phoenixPushErrors.clientClosed('wait_for_connection')],
+    ['clientClosedReply', phoenixPushErrors.clientClosed('reply')],
+    ['notConnected', phoenixPushErrors.notConnected()],
+    [
+      'connectionWaitTimeout',
+      phoenixPushErrors.connectionWaitTimeout(1234, 'scripted_event'),
+    ],
+    ['replyTimeout', phoenixPushErrors.replyTimeout(1234, 'scripted_event')],
+  ];
+  return entries.map(([name, error]) => {
+    const typed = error as Error & { phase: string; reason: string };
+    return {
+      name,
+      phase: typed.phase,
+      reason: typed.reason,
+      message: typed.message,
+      isPushError: isPhoenixPushError(error),
+      isLost: isPhoenixConnectionLostError(error),
+      isWait: isPhoenixConnectionWaitError(error),
+    };
+  });
+}
+
+function handleBatchCase(testCase: {
+  readonly op: string;
+  readonly baseUrl?: string;
+  readonly token?: string;
+  readonly text?: string;
+  readonly frame?: JsonValue;
+  readonly payload?: JsonObject;
+}): unknown {
+  switch (testCase.op) {
+    case 'websocketUrl':
+      return outcome(() => phoenixWebsocketUrl(testCase.baseUrl ?? ''));
+    case 'websocketProtocols':
+      return outcome(() => phoenixWebsocketProtocols(testCase.token ?? ''));
+    case 'decodeFrame':
+      return outcome(() => decodeFrame(testCase.text ?? ''));
+    case 'encodeFrame':
+      return outcome(() =>
+        encodeFrame(testCase.frame as Parameters<typeof encodeFrame>[0])
+      );
+    case 'pushErrorTable':
+      return pushErrorTable();
+    case 'backoffConfig':
+      return phoenixReconnectBackoffConfig;
+    case 'redact':
+      return outcome(() => redactForCliLog(testCase.payload ?? {}));
+    default:
+      return { threw: true, message: 'unknown op ' + String(testCase.op) };
+  }
+}
+
+async function runBatch(): Promise<void> {
+  let stdin = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    stdin += chunk;
+  }
+  const cases = JSON.parse(stdin) as unknown[];
+  process.stdout.write(
+    JSON.stringify(cases.map((testCase) => handleBatchCase(testCase as never)))
+  );
+}
+
+// --- FLOW mode --------------------------------------------------------------------
+
+type Obs = Record<string, unknown>;
+
+const observations: Obs[] = [];
+const waiters: Array<() => void> = [];
+let controlCount = 0;
+let reconnectCount = 0;
+let disconnectCount = 0;
+let noticeCount = 0;
+
+function emit(client: string, obs: Obs): void {
+  const entry = { client, ...obs };
+  observations.push(entry);
+  process.stdout.write(JSON.stringify({ obs: entry }) + '\\n');
+  for (const waiter of [...waiters]) {
+    waiter();
+  }
+}
+
+function reply(id: number, payload: Obs): void {
+  process.stdout.write(JSON.stringify({ id, ...payload }) + '\\n');
+}
+
+function awaitCondition(check: () => boolean): Promise<void> {
+  return new Promise((resolve) => {
+    const settle = () => {
+      if (check()) {
+        const index = waiters.indexOf(settle);
+        if (index !== -1) {
+          waiters.splice(index, 1);
+        }
+        resolve();
+      }
+    };
+    waiters.push(settle);
+    settle();
+  });
+}
+
+function pushFailureObs(error: unknown): Obs {
+  if (isPhoenixPushError(error)) {
+    const typed = error as Error & { phase: string; reason: string };
+    return {
+      class: 'transport',
+      phase: typed.phase,
+      reason: typed.reason,
+      message: typed.message,
+      lost: isPhoenixConnectionLostError(error),
+      wait: isPhoenixConnectionWaitError(error),
+    };
+  }
+  return {
+    class: 'failed',
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+type FlowConnectCommand = {
+  readonly id: number;
+  readonly op: 'connect';
+  readonly client?: string;
+  readonly url: string;
+  readonly token: string;
+  readonly pushTimeoutMs?: number;
+  readonly cursorStore?:
+    | { readonly kind: 'memory'; readonly initial?: Record<string, number> }
+    | { readonly kind: 'file'; readonly path: string };
+  readonly epochStore?:
+    | { readonly kind: 'memory'; readonly epoch?: string }
+    | {
+        readonly kind: 'file';
+        readonly cursorPath: string;
+        readonly startTurnPath: string;
+      };
+  readonly consumerThrowsOn?: string;
+  readonly ackMode?: 'immediate' | 'never';
+};
+
+const clients = new Map<string, PhoenixClient>();
+const manualAcks = new Map<string, () => void>();
+
+function clientName(command: { readonly client?: unknown }): string {
+  return typeof command.client === 'string' ? command.client : 'main';
+}
+
+function clientOf(command: { readonly client?: unknown }): PhoenixClient {
+  const named = clients.get(clientName(command));
+  if (named === undefined) {
+    throw new Error('flow client not connected: ' + clientName(command));
+  }
+  return named;
+}
+
+function instrumentCursorStore(
+  name: string,
+  store: PhoenixControlCursorStore & { reset?: (topic: string, seq: number) => void }
+): PhoenixControlCursorStore {
+  return {
+    initial: (topic) => {
+      const value = store.initial(topic);
+      emit(name, { kind: 'store', op: 'initial', topic, value: value ?? null });
+      return value;
+    },
+    onAdvance: (topic, seq) => {
+      emit(name, { kind: 'store', op: 'onAdvance', topic, seq });
+      store.onAdvance(topic, seq);
+    },
+    reset: (topic, seq) => {
+      emit(name, { kind: 'store', op: 'reset', topic, seq });
+      store.reset?.(topic, seq);
+    },
+  };
+}
+
+function instrumentEpochStore(
+  name: string,
+  store: PhoenixControlEpochStore
+): PhoenixControlEpochStore {
+  return {
+    current: (topic) => {
+      const value = store.current(topic);
+      emit(name, { kind: 'epoch', op: 'current', topic, value: value ?? null });
+      return value;
+    },
+    adopt: (topic, epoch) => {
+      const changed = store.adopt(topic, epoch);
+      emit(name, { kind: 'epoch', op: 'adopt', topic, epoch, changed });
+      return changed;
+    },
+  };
+}
+
+const flowFileStores: Array<{ flush: () => void }> = [];
+
+async function handleConnect(command: FlowConnectCommand): Promise<void> {
+  const name = clientName(command);
+  let cursorStore: PhoenixControlCursorStore | undefined;
+  if (command.cursorStore?.kind === 'memory') {
+    const cursors = new Map<string, number>(
+      Object.entries(command.cursorStore.initial ?? {})
+    );
+    cursorStore = instrumentCursorStore(name, {
+      initial: (topic) => cursors.get(topic),
+      onAdvance: (topic, seq) => {
+        const existing = cursors.get(topic);
+        if (existing === undefined || seq > existing) {
+          cursors.set(topic, seq);
+        }
+      },
+      reset: (topic, seq) => {
+        cursors.set(topic, seq);
+      },
+    });
+  } else if (command.cursorStore?.kind === 'file') {
+    const fileStore = createControlCursorFileStore(
+      command.cursorStore.path,
+      (event: string) => {
+        emit(name, { kind: 'storelog', event });
+      }
+    );
+    flowFileStores.push(fileStore);
+    cursorStore = instrumentCursorStore(name, fileStore);
+  }
+
+  let epochStore: PhoenixControlEpochStore | undefined;
+  if (command.epochStore?.kind === 'memory') {
+    let epoch = command.epochStore.epoch;
+    epochStore = instrumentEpochStore(name, {
+      current: () => epoch,
+      adopt: (_topic, next) => {
+        const changed = epoch !== undefined && epoch !== next;
+        epoch = next;
+        return changed;
+      },
+    });
+  } else if (command.epochStore?.kind === 'file') {
+    const log = (event: string) => {
+      emit(name, { kind: 'storelog', event });
+    };
+    const cursorFileStore = createControlCursorFileStore(
+      command.epochStore.cursorPath,
+      log
+    );
+    const startTurnFileStore = createControlCursorFileStore(
+      command.epochStore.startTurnPath,
+      log,
+      { discardSeqsOnFirstEpochAdoption: true }
+    );
+    flowFileStores.push(cursorFileStore, startTurnFileStore);
+    cursorStore = instrumentCursorStore(name, cursorFileStore);
+    epochStore = instrumentEpochStore(
+      name,
+      createRunnerControlEpochStore(cursorFileStore, startTurnFileStore, log, {
+        runnerId: 'scripted-transport',
+        kandanUrl: command.url,
+      })
+    );
+  }
+
+  let client: PhoenixClient;
+  try {
+    client = await connectPhoenixClient(command.url, command.token, undefined, {
+      ...(command.pushTimeoutMs === undefined
+        ? {}
+        : { pushTimeoutMs: command.pushTimeoutMs }),
+      ...(cursorStore === undefined ? {} : { controlCursorStore: cursorStore }),
+      ...(epochStore === undefined ? {} : { controlEpochStore: epochStore }),
+      onOperatorNotice: (message) => {
+        noticeCount += 1;
+        emit(name, { kind: 'notice', message });
+      },
+    });
+  } catch (error) {
+    emit(name, { kind: 'connect_error', ...pushFailureObs(error) });
+    reply(command.id, { ok: false });
+    return;
+  }
+  clients.set(name, client);
+
+  client.onControl((control, ack) => {
+    controlCount += 1;
+    emit(name, { kind: 'control', payload: control });
+    if (
+      command.consumerThrowsOn !== undefined &&
+      control.type === command.consumerThrowsOn
+    ) {
+      throw new Error('scripted consumer failure: ' + String(control.type));
+    }
+    if (command.ackMode === 'never') {
+      const seq = control.control_seq;
+      if (typeof seq === 'number') {
+        manualAcks.set(name + ':' + String(seq), ack);
+      }
+      return;
+    }
+    ack();
+  });
+  client.onEvent((topic, event, payload) => {
+    emit(name, { kind: 'event', topic, event, payload });
+  });
+  client.onReconnect((rejoinReplies) => {
+    reconnectCount += 1;
+    const replies: Record<string, unknown> = {};
+    for (const [topic, response] of rejoinReplies) {
+      replies[topic] = response;
+    }
+    emit(name, { kind: 'reconnect', replies });
+  });
+  client.onDisconnect?.((info) => {
+    disconnectCount += 1;
+    emit(name, {
+      kind: 'disconnect',
+      closeCode: info.closeCode ?? null,
+      closeReason: info.closeReason ?? null,
+      hadDuration: info.previousSessionDurationMs !== undefined,
+      reconnectCount: info.reconnectCount,
+    });
+  });
+  emit(name, { kind: 'connect_ok' });
+  reply(command.id, { ok: true });
+}
+
+type FlowCommand = FlowConnectCommand | (Record<string, unknown> & { id: number; op: string });
+
+async function handleFlowCommand(command: FlowCommand): Promise<void> {
+  switch (command.op) {
+    case 'connect':
+      await handleConnect(command as FlowConnectCommand);
+      return;
+    case 'join': {
+      const name = clientName(command);
+      const topic = String(command.topic);
+      const payload = command.payload as JsonObject;
+      const rejoin = command.rejoin as JsonObject | undefined;
+      const registrationId = command.registrationId as string | undefined;
+      try {
+        const response = await clientOf(command).join(topic, payload, {
+          ...(rejoin === undefined ? {} : { rejoinPayload: () => rejoin }),
+          ...(registrationId === undefined ? {} : { registrationId }),
+        });
+        emit(name, { kind: 'join_ok', topic, response });
+      } catch (error) {
+        emit(name, { kind: 'join_error', topic, ...pushFailureObs(error) });
+      }
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'push': {
+      const name = clientName(command);
+      try {
+        const result = await clientOf(command).push(
+          String(command.topic),
+          String(command.event),
+          command.payload as JsonObject
+        );
+        emit(name, { kind: 'push_ok', event: command.event, reply: result });
+      } catch (error) {
+        emit(name, { kind: 'push_error', event: command.event, ...pushFailureObs(error) });
+      }
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'pushDetached': {
+      // Fire without awaiting: the outcome lands as an observation whenever
+      // it settles (the queued-push-across-outage legs).
+      const name = clientName(command);
+      void clientOf(command)
+        .push(
+          String(command.topic),
+          String(command.event),
+          command.payload as JsonObject
+        )
+        .then(
+          (result) => {
+            emit(name, { kind: 'push_ok', event: command.event, reply: result });
+          },
+          (error: unknown) => {
+            emit(name, { kind: 'push_error', event: command.event, ...pushFailureObs(error) });
+          }
+        );
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'pushIfConnected': {
+      const name = clientName(command);
+      try {
+        const result = await clientOf(command).pushIfConnected(
+          String(command.topic),
+          String(command.event),
+          command.payload as JsonObject
+        );
+        emit(name, { kind: 'push_ok', event: command.event, reply: result });
+      } catch (error) {
+        emit(name, { kind: 'push_error', event: command.event, ...pushFailureObs(error) });
+      }
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'unregisterJoin':
+      clientOf(command).unregisterJoin?.(
+        String(command.topic),
+        String(command.registrationId)
+      );
+      reply(command.id, { done: true });
+      return;
+    case 'ackControl': {
+      const name = clientName(command);
+      const seq = Number(command.seq);
+      const ack = manualAcks.get(name + ':' + String(seq));
+      manualAcks.delete(name + ':' + String(seq));
+      ack?.();
+      emit(name, { kind: 'manual_ack', seq });
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'forceReconnect': {
+      const name = clientName(command);
+      const initiated = clientOf(command).forceReconnect?.(
+        command.reason as string | undefined
+      );
+      emit(name, { kind: 'force_reconnect_result', initiated: initiated ?? false });
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'hardReset': {
+      const name = clientName(command);
+      const initiated = clientOf(command).hardReset?.(
+        command.reason as string | undefined
+      );
+      emit(name, { kind: 'hard_reset_result', initiated: initiated ?? false });
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'awaitControls':
+      await awaitCondition(() => controlCount >= Number(command.count));
+      reply(command.id, { done: true });
+      return;
+    case 'awaitReconnects':
+      await awaitCondition(() => reconnectCount >= Number(command.count));
+      reply(command.id, { done: true });
+      return;
+    case 'awaitDisconnects':
+      await awaitCondition(() => disconnectCount >= Number(command.count));
+      reply(command.id, { done: true });
+      return;
+    case 'awaitNotices':
+      await awaitCondition(() => noticeCount >= Number(command.count));
+      reply(command.id, { done: true });
+      return;
+    case 'awaitAudits': {
+      // Audit events land in the LINZUMI_CLI_AUDIT_LOG file (phoenix.ts
+      // writes writeCliAuditEvent directly); poll its line count so
+      // choreography can sequence on the drain-progress contract.
+      const auditFile = process.env.LINZUMI_CLI_AUDIT_LOG ?? '';
+      const target = Number(command.count);
+      const countLines = () => {
+        try {
+          return readFileSync(auditFile, 'utf8')
+            .split('\\n')
+            .filter((line) => line !== '').length;
+        } catch {
+          return 0;
+        }
+      };
+      while (countLines() < target) {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'awaitObs': {
+      const kind = String(command.kind);
+      const count = Number(command.count);
+      await awaitCondition(
+        () => observations.filter((entry) => entry.kind === kind).length >= count
+      );
+      reply(command.id, { done: true });
+      return;
+    }
+    case 'close':
+      clients.get(clientName(command))?.close();
+      reply(command.id, { done: true });
+      return;
+    case 'finish': {
+      for (const store of flowFileStores) {
+        store.flush();
+      }
+      const auditFile = process.env.LINZUMI_CLI_AUDIT_LOG;
+      let audit: unknown[] = [];
+      if (auditFile !== undefined && auditFile !== '') {
+        try {
+          audit = readFileSync(auditFile, 'utf8')
+            .split('\\n')
+            .filter((line) => line !== '')
+            .map((line) => {
+              const parsed = JSON.parse(line) as Record<string, unknown>;
+              // Drop wall-clock + impl-varying members (ts, stack); keep the
+              // stable identity of each audit event.
+              delete parsed.ts;
+              delete parsed.stack;
+              return parsed;
+            });
+        } catch {
+          audit = [];
+        }
+      }
+      reply(command.id, { done: true, audit });
+      process.exit(0);
+      return;
+    }
+    default:
+      reply(command.id, { error: 'unknown op ' + String(command.op) });
+  }
+}
+
+async function runFlow(): Promise<void> {
+  const lines = createInterface({ input: process.stdin, terminal: false });
+  // Commands run strictly sequentially: each line's handler completes
+  // (including its await conditions) before the next line is consumed -
+  // the same milestone-sequenced choreography the differential runner uses.
+  const queue: string[] = [];
+  let draining = false;
+  const drain = async () => {
+    if (draining) {
+      return;
+    }
+    draining = true;
+    while (queue.length > 0) {
+      const line = queue.shift()!;
+      if (line.trim() === '') {
+        continue;
+      }
+      const command = JSON.parse(line) as FlowCommand;
+      await handleFlowCommand(command);
+    }
+    draining = false;
+  };
+  lines.on('line', (line) => {
+    queue.push(line);
+    void drain();
+  });
+}
+
+if (process.argv.includes('--flow')) {
+  void runFlow();
+} else {
+  void runBatch();
+}
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+// runner.ts's graph resolves assets/ relative to the bundle at import time
+// (same requirement as build-differential-entry.mjs).
+await mkdir(join(packageRoot, '.differential/assets'), { recursive: true });
+await copyFile(
+  join(packageRoot, 'src/assets/linzumi-logo.svg'),
+  join(packageRoot, '.differential/assets/linzumi-logo.svg')
+);
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'transport-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/transport-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  // runner.ts pulls the wider commander graph; the same runtime externals
+  // as the differential entry build stay external.
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});