@linzumi/cli 1.0.98 → 1.0.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "1.0.98",
+  "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'],
+});