@linzumi/cli 1.0.17 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "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": {
@@ -18,7 +18,15 @@
     "codex:history-table": "node scripts/codex_history_table.mjs",
     "test": "vitest run --config vitest.config.mjs",
     "prepack": "node scripts/build.mjs",
-    "pack:dry-run": "npm pack --dry-run"
+    "pack:dry-run": "npm pack --dry-run",
+    "record:agent-fixtures": "tsx scripts/record-agent-replay-fixtures.ts",
+    "normalize:agent-fixture": "tsx scripts/normalize-agent-replay-fixture.ts",
+    "vendor:codex-app-server-protocol": "tsx scripts/vendor-codex-app-server-protocol.ts",
+    "replay:agent-fixture": "tsx scripts/replay-agent-fixture.ts",
+    "replay:agent-backend": "tsx scripts/replay-agent-backend.ts",
+    "vendor:codex-app-server-protocol:check": "tsx scripts/vendor-codex-app-server-protocol.ts --check",
+    "replay:agent-backend-browser": "tsx scripts/replay-agent-backend-browser.ts",
+    "promote:gstack-claude-smoke-fixture": "tsx scripts/promote-gstack-claude-smoke-fixture.ts"
   },
   "keywords": [
     "linzumi",
@@ -50,6 +58,7 @@
     "esbuild": "^0.27.2",
     "fast-check": "^3.23.2",
     "tsx": "^4.21.0",
-    "vitest": "^1.6.1"
+    "vitest": "^1.6.1",
+    "typescript": "^5.9.3"
   }
 }

package/scripts/analyze_enter_to_typing_latency.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Enter->typing latency analyzer for a runner log (the measurement infra
+// behind the 2026-07-02 follow-up-latency RCA; see
+// test/enterToTypingHeadOfLine.test.ts for the fix it motivated).
+//
+// For every real-thread follow-up dispatch it pairs `kandan.message_queued`
+// with the next `codex.turn_starting` on the same thread and classifies the
+// window:
+//   - silent           : NO other runner activity for the thread in between.
+//                        Pre-fix this was the head-of-line block on the
+//                        `queued` message_state server ack; post-fix it
+//                        should be ~0ms.
+//   - drain_blocked/*  : a logged `kandan.queue_drain_blocked` gate
+//                        (turn_not_idle = user sent mid-turn, etc.). These
+//                        are legitimate waits, not latency bugs.
+//   - cold_spawn       : a `runner.thread_process_starting` fired in the
+//                        window (worker cold respawn).
+//
+// Usage:
+//   node scripts/analyze_enter_to_typing_latency.mjs [path-to-runner-log]
+// Default log path: ~/.linzumi/logs/linzumi-runner.log
+//
+// Ran against a production runner log on 2026-07-02 this reported, over
+// 5439 follow-up dispatches (UUID-threaded; includes local vitest threads
+// with synthetic UUIDs, which are all in the fast bucket): 204 slower than
+// 500ms, of which 158 were `silent` (p50 1343ms / p90 3119ms / p99 11928ms),
+// 46 were drain_blocked/turn_not_idle, and 0 were cold spawns - the evidence
+// that the dominant Enter->typing latency was the awaited status-paint ack,
+// not worker respawn.
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const logPath =
+  process.argv[2] ??
+  path.join(homedir(), '.linzumi', 'logs', 'linzumi-runner.log');
+const slowThresholdMs = Number(process.env.SLOW_THRESHOLD_MS ?? 500);
+
+// Real Linzumi thread ids are UUIDs; test threads use readable slugs.
+const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function percentile(sorted, q) {
+  if (sorted.length === 0) {
+    return null;
+  }
+  return sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))];
+}
+
+const threads = new Map();
+const rows = [];
+
+const rl = createInterface({
+  input: createReadStream(logPath),
+  crlfDelay: Infinity,
+});
+
+for await (const line of rl) {
+  if (line.length > 20_000) {
+    continue;
+  }
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    continue;
+  }
+  const threadId =
+    entry.thread_id ??
+    entry.kandanThreadId ??
+    entry.linzumi_thread_id ??
+    entry.threadId ??
+    entry.kandan_thread_id;
+  if (typeof threadId !== 'string' || !uuidRe.test(threadId)) {
+    continue;
+  }
+  const atMs = Date.parse(entry.ts);
+  if (Number.isNaN(atMs)) {
+    // A malformed/absent timestamp would otherwise mint a NaN-latency row
+    // that silently falls out of both the slow and fast buckets, making the
+    // printed totals diverge from the dispatch count.
+    continue;
+  }
+  let state = threads.get(threadId);
+  if (state === undefined) {
+    state = { pending: null };
+    threads.set(threadId, state);
+  }
+  const event = entry.event;
+  if (event === 'kandan.message_queued') {
+    state.pending = { atMs, seq: entry.seq, blocked: [], spawn: false };
+  } else if (state.pending !== null) {
+    if (event === 'codex.turn_starting') {
+      rows.push({
+        threadId,
+        ts: entry.ts,
+        ms: atMs - state.pending.atMs,
+        blocked: state.pending.blocked,
+        spawn: state.pending.spawn,
+      });
+      state.pending = null;
+    } else if (event === 'kandan.queue_drain_blocked') {
+      state.pending.blocked.push(entry.reason);
+    } else if (event === 'runner.thread_process_starting') {
+      state.pending.spawn = true;
+    }
+  }
+}
+
+const slow = rows.filter((row) => row.ms > slowThresholdMs);
+const silent = slow.filter((row) => row.blocked.length === 0 && !row.spawn);
+const spawns = slow.filter((row) => row.spawn);
+const blockedCounts = new Map();
+for (const row of slow) {
+  for (const reason of new Set(row.blocked)) {
+    blockedCounts.set(reason, (blockedCounts.get(reason) ?? 0) + 1);
+  }
+}
+
+const silentSorted = silent.map((row) => row.ms).sort((a, b) => a - b);
+const fast = rows.filter((row) => row.ms <= slowThresholdMs);
+const fastSorted = fast.map((row) => row.ms).sort((a, b) => a - b);
+
+console.log(`log: ${logPath}`);
+console.log(
+  `follow-up dispatches=${rows.length} slow(>${slowThresholdMs}ms)=${slow.length}`
+);
+console.log(
+  `  silent (head-of-line on paint ack pre-fix)=${silent.length}` +
+    (silentSorted.length > 0
+      ? ` p50=${percentile(silentSorted, 0.5)}ms p90=${percentile(silentSorted, 0.9)}ms p99=${percentile(silentSorted, 0.99)}ms max=${silentSorted[silentSorted.length - 1]}ms`
+      : '')
+);
+for (const [reason, count] of blockedCounts) {
+  console.log(`  drain_blocked/${reason}=${count}`);
+}
+console.log(`  cold_spawn=${spawns.length}`);
+console.log(
+  `fast(<=${slowThresholdMs}ms)=${fast.length}` +
+    (fastSorted.length > 0 ? ` p50=${percentile(fastSorted, 0.5)}ms` : '')
+);
+if (silent.length > 0) {
+  console.log('\nslowest silent windows:');
+  for (const row of [...silent].sort((a, b) => b.ms - a.ms).slice(0, 10)) {
+    console.log(`  ${row.ts} thread=${row.threadId.slice(0, 8)} ${row.ms}ms`);
+  }
+}

package/scripts/normalize-agent-replay-fixture.ts

@@ -0,0 +1,281 @@
+/*
+- Date: 2026-06-29
+  Spec: plans/2026-06-29-claude-code-raw-replay-harness-plan.md
+  Relationship: Promotion-time normalizer for real raw agent replay captures.
+  Capture files stay exact in /tmp; this script produces deterministic fixtures
+  by normalizing machine-local paths and volatile run/session identifiers.
+*/
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+
+export type AgentReplayNormalizeOptions = {
+  readonly normalizeProviderIds: boolean;
+};
+
+type NormalizerState = {
+  readonly options: AgentReplayNormalizeOptions;
+  readonly mappings: Map<string, string>;
+  nextRunId: number;
+  nextSessionId: number;
+  nextMessageId: number;
+};
+
+type CliOptions =
+  | {
+      readonly type: 'single';
+      readonly input: string;
+      readonly output: string;
+      readonly normalizeProviderIds: boolean;
+    }
+  | {
+      readonly type: 'directory';
+      readonly inputDir: string;
+      readonly outputDir: string;
+      readonly normalizeProviderIds: boolean;
+    };
+
+const defaultOptions: AgentReplayNormalizeOptions = {
+  normalizeProviderIds: true,
+};
+
+const homePathPattern = /\/home\/([A-Za-z0-9._-]+)/gu;
+const tmpRunPathPattern =
+  /\/tmp\/linzumi-(codex|claude)-fixture-[A-Za-z0-9]+/gu;
+const tmpReplayPathPattern = /\/tmp\/linzumi-agent-replay-[A-Za-z0-9._-]+/gu;
+const codexSessionFilePattern =
+  /rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-[0-9a-f-]{36}\.jsonl/giu;
+const uuidPattern =
+  /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/giu;
+const codexMessageIdPattern = /\bmsg_[A-Za-z0-9_-]{16,}\b/gu;
+const claudeSignaturePattern = /("signature"\s*:\s*")[^"]+(")/gu;
+
+export function normalizeAgentReplayText(
+  text: string,
+  options: AgentReplayNormalizeOptions = defaultOptions
+): string {
+  const state: NormalizerState = {
+    options,
+    mappings: new Map(),
+    nextRunId: 1,
+    nextSessionId: 1,
+    nextMessageId: 1,
+  };
+
+  return text
+    .split(/\r?\n/u)
+    .map((line) => normalizeNdjsonLine(line, state))
+    .join('\n');
+}
+
+function normalizeNdjsonLine(line: string, state: NormalizerState): string {
+  if (line.trim() === '') {
+    return line;
+  }
+
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    return JSON.stringify(normalizeJsonValue(parsed, state));
+  } catch (_error) {
+    return normalizeString(line, state);
+  }
+}
+
+function normalizeJsonValue(value: unknown, state: NormalizerState): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeJsonValue(item, state));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const normalizedEntries = Object.entries(value).map(([key, child]) => {
+      if (key === 'rawText' && typeof child === 'string') {
+        return [key, normalizeRawText(child, state)] as const;
+      }
+
+      if (key === 'signature' && typeof child === 'string') {
+        return [key, '[fixture-signature]'] as const;
+      }
+
+      return [key, normalizeJsonValue(child, state)] as const;
+    });
+
+    return Object.fromEntries(normalizedEntries);
+  }
+
+  return typeof value === 'string' ? normalizeString(value, state) : value;
+}
+
+function normalizeRawText(value: string, state: NormalizerState): string {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return JSON.stringify(normalizeJsonValue(parsed, state));
+  } catch (_error) {
+    return normalizeString(value, state);
+  }
+}
+
+function normalizeString(value: string, state: NormalizerState): string {
+  let normalized = value
+    .replace(tmpRunPathPattern, (_match, provider: string) =>
+      mappedValue(
+        state,
+        _match,
+        () => `/tmp/linzumi-agent-fixture/${provider}-run-${state.nextRunId++}`
+      )
+    )
+    .replace(tmpReplayPathPattern, '/tmp/linzumi-agent-replay')
+    .replace(homePathPattern, '/home/fixture-user')
+    .replace(codexSessionFilePattern, (match) =>
+      mappedValue(
+        state,
+        match,
+        () =>
+          `rollout-2026-06-29T00-00-00-fixture-session-${state.nextSessionId++}.jsonl`
+      )
+    )
+    .replace(claudeSignaturePattern, '$1[fixture-signature]$2');
+
+  switch (state.options.normalizeProviderIds) {
+    case true:
+      normalized = normalized
+        .replace(uuidPattern, (match) =>
+          mappedValue(
+            state,
+            match,
+            () =>
+              `00000000-0000-4000-8000-${String(state.nextSessionId++).padStart(12, '0')}`
+          )
+        )
+        .replace(codexMessageIdPattern, (match) =>
+          mappedValue(
+            state,
+            match,
+            () =>
+              `msg_fixture_${String(state.nextMessageId++).padStart(4, '0')}`
+          )
+        );
+      break;
+    case false:
+      break;
+  }
+
+  return normalized;
+}
+
+function mappedValue(
+  state: NormalizerState,
+  input: string,
+  create: () => string
+): string {
+  const existing = state.mappings.get(input);
+
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const next = create();
+  state.mappings.set(input, next);
+  return next;
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  const options = parseCliOptions(args);
+
+  switch (options.type) {
+    case 'single':
+      await normalizeFile(options.input, options.output, {
+        normalizeProviderIds: options.normalizeProviderIds,
+      });
+      process.stdout.write(`wrote ${options.output}\n`);
+      break;
+    case 'directory': {
+      await mkdir(options.outputDir, { recursive: true });
+      const entries = await readdir(options.inputDir, { withFileTypes: true });
+      const ndjsonFiles = entries.filter(
+        (entry) => entry.isFile() && extname(entry.name) === '.ndjson'
+      );
+
+      for (const entry of ndjsonFiles) {
+        const input = join(options.inputDir, entry.name);
+        const output = join(options.outputDir, entry.name);
+        await normalizeFile(input, output, {
+          normalizeProviderIds: options.normalizeProviderIds,
+        });
+        process.stdout.write(`wrote ${output}\n`);
+      }
+      break;
+    }
+  }
+}
+
+async function normalizeFile(
+  input: string,
+  output: string,
+  options: AgentReplayNormalizeOptions
+): Promise<void> {
+  const source = await readFile(input, 'utf8');
+  const normalized = normalizeAgentReplayText(source, options);
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, normalized, 'utf8');
+}
+
+function parseCliOptions(args: readonly string[]): CliOptions {
+  const normalizeProviderIds = !args.includes('--keep-provider-ids');
+  const input = argValue(args, '--input');
+  const output = argValue(args, '--output');
+  const inputDir = argValue(args, '--input-dir');
+  const outputDir = argValue(args, '--output-dir');
+
+  if (input !== undefined && output !== undefined) {
+    return {
+      type: 'single',
+      input: resolve(input),
+      output: resolve(output),
+      normalizeProviderIds,
+    };
+  }
+
+  if (inputDir !== undefined && outputDir !== undefined) {
+    return {
+      type: 'directory',
+      inputDir: resolve(inputDir),
+      outputDir: resolve(outputDir),
+      normalizeProviderIds,
+    };
+  }
+
+  throw new Error(
+    'provide either --input/--output or --input-dir/--output-dir'
+  );
+}
+
+function argValue(args: readonly string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+
+  if (index === -1) {
+    return undefined;
+  }
+
+  return args[index + 1];
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    `Usage: pnpm run normalize:agent-fixture -- [options]\n\nOptions:\n  --input <file> --output <file>          Normalize one NDJSON fixture\n  --input-dir <dir> --output-dir <dir>    Normalize every .ndjson file in a directory\n  --keep-provider-ids                     Preserve provider session/message ids\n\nExamples:\n  pnpm run normalize:agent-fixture -- --input-dir /tmp/linzumi-agent-replay-probe --output-dir test/fixtures/agent-raw-replay/promoted\n`
+  );
+}
+
+if (basename(process.argv[1] ?? '') === 'normalize-agent-replay-fixture.ts') {
+  main().catch((error) => {
+    process.stderr.write(
+      `${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`
+    );
+    process.exitCode = 1;
+  });
+}