@linzumi/cli 1.0.102 → 1.0.104

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.102 --version
+npx -y @linzumi/cli@1.0.104 --version
 linzumi --version
 ```
 

package/dist/index.js

@@ -1471,7 +1471,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;uSe(n,{recursive:!0}),m(u)+L>i&&f(),_(L);let D=w()?`
 `:"";return sSe(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=lSe(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=ISe(Z.parsed);return fe===void 0||fe>=L});if(q.length===0){y(D,"empty_or_expired");continue}let E=oP(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{h9(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 ySe,xSe,_Se,bSe,wSe,g9,SSe,kSe,x9=F(()=>{"use strict";Xy();ySe=32*1024*1024,xSe=10080*60*1e3,_Se=4*1024*1024,bSe=1024*1024,wSe="spool.jsonl",g9=/^batch-(\d{1,16})-[0-9a-f-]+\.jsonl$/;SSe=/\b([A-Z][A-Z0-9_]{1,})=("[^"\n]*"|'[^'\n]*'|[^\s"'`;,)\]}]+)/g,kSe=/(?:\/(?:[A-Za-z0-9._@~+-]|%[0-9A-Fa-f]{2})+){2,}/g});var jt,sP,ea=F(()=>{"use strict";jt="1.0.102",sP=`linzumi ${jt}`});import{closeSync as b9,existsSync as dP,mkdirSync as RSe,openSync as w9,readFileSync as v9,renameSync as ESe,unlinkSync as gd,writeFileSync as DSe,writeSync as S9}from"node:fs";import{dirname as k9,join as MSe}from"node:path";function uP(e){return e instanceof hs||e instanceof Error&&e.name===T9&&"lockPath"in e&&"heldBy"in e}function cP(e,n=Wn(),t){let r=t===void 0?encodeURIComponent(e):dd(t);return MSe(k9(n),"runners",`${r}.lock`)}function u0(e){let n=cP(e.machineId,e.configPath,e.linzumiUrl),t=e.isPidAlive??A9,r=e.now??(()=>new Date),o=e.killPid??KSe,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:qn(e.linzumiUrl)},...e.launchSource===void 0?{}:{launchSource:e.launchSource},startedAt:i,heartbeatAt:i,cliVersion:e.cliVersion??jt,...e.gracefulUpdateDrain===!0?{gracefulUpdateDrain:!0}:{}};LSe(e.machineId,e.configPath,e.linzumiUrl,t,r,o,e.onTakeover),jSe(n,s,t,r,o,e.onTakeover,e.beforeReadExistingLock,e.beforeReplaceStaleLock);let a=()=>P9(n,s,r),d=setInterval(a,C9);return d.unref(),{path:n,record:s,heartbeat:a,release:()=>{clearInterval(d),D9(n,s)}}}function P9(e,n,t){try{let r=l0(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`;DSe(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{h9(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 ySe,xSe,_Se,bSe,wSe,g9,SSe,kSe,x9=F(()=>{"use strict";Xy();ySe=32*1024*1024,xSe=10080*60*1e3,_Se=4*1024*1024,bSe=1024*1024,wSe="spool.jsonl",g9=/^batch-(\d{1,16})-[0-9a-f-]+\.jsonl$/;SSe=/\b([A-Z][A-Z0-9_]{1,})=("[^"\n]*"|'[^'\n]*'|[^\s"'`;,)\]}]+)/g,kSe=/(?:\/(?:[A-Za-z0-9._@~+-]|%[0-9A-Fa-f]{2})+){2,}/g});var jt,sP,ea=F(()=>{"use strict";jt="1.0.104",sP=`linzumi ${jt}`});import{closeSync as b9,existsSync as dP,mkdirSync as RSe,openSync as w9,readFileSync as v9,renameSync as ESe,unlinkSync as gd,writeFileSync as DSe,writeSync as S9}from"node:fs";import{dirname as k9,join as MSe}from"node:path";function uP(e){return e instanceof hs||e instanceof Error&&e.name===T9&&"lockPath"in e&&"heldBy"in e}function cP(e,n=Wn(),t){let r=t===void 0?encodeURIComponent(e):dd(t);return MSe(k9(n),"runners",`${r}.lock`)}function u0(e){let n=cP(e.machineId,e.configPath,e.linzumiUrl),t=e.isPidAlive??A9,r=e.now??(()=>new Date),o=e.killPid??KSe,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:qn(e.linzumiUrl)},...e.launchSource===void 0?{}:{launchSource:e.launchSource},startedAt:i,heartbeatAt:i,cliVersion:e.cliVersion??jt,...e.gracefulUpdateDrain===!0?{gracefulUpdateDrain:!0}:{}};LSe(e.machineId,e.configPath,e.linzumiUrl,t,r,o,e.onTakeover),jSe(n,s,t,r,o,e.onTakeover,e.beforeReadExistingLock,e.beforeReplaceStaleLock);let a=()=>P9(n,s,r),d=setInterval(a,C9);return d.unref(),{path:n,record:s,heartbeat:a,release:()=>{clearInterval(d),D9(n,s)}}}function P9(e,n,t){try{let r=l0(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`;DSe(i,`${JSON.stringify(o,null,2)}
 `,"utf8"),ESe(i,e)}catch{}}function yd(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>ASe?{state:"wedged",reason:e.heartbeatAt===void 0?"missing_heartbeat":"stale_heartbeat"}:{state:"live"}}function I9(e,n,t,r){return t!==c0||e.launchSource!==c0?!1:r.state!=="live"?!0:$Se(n,e.cliVersion)>0}function $Se(e,n){let t=_9(e),r=_9(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:OSe(t.prerelease,r.prerelease)}function _9(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=[aP(i[0]),aP(i[1]),aP(i[2])],a=o===""?[]:o.split(".").filter(d=>d!=="");return{core:s,prerelease:a}}function aP(e){let n=Number.parseInt(e??"",10);return Number.isInteger(n)&&n>=0?n:0}function OSe(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 R9(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 LSe(e,n,t,r,o,i,s){if(t===void 0||yr(t)!==yr(Bt))return;let a=cP(e,n),d=l0(a);if(d!==void 0){if(yd(d,r,o).state==="live")throw new hs(a,d);E9(a,r,()=>{let u=dP(a)?lP(a):void 0;if(u===void 0)return;let c=yd(u,r,o);if(c.state==="live")throw new hs(a,u);c.state==="wedged"&&R9(a,u,c.reason,i,s),gd(a)})}}function jSe(e,n,t,r,o,i,s,a){if(d0(e,n))return;s?.();let d=l0(e);if(d===void 0){if(d0(e,n))return;throw new Error(`another Linzumi runner lock appeared while starting: ${e}`)}if(yd(d,t,r).state==="live")throw new hs(e,d);a?.(),E9(e,t,()=>{let u=dP(e)?lP(e):void 0;if(u!==void 0){let c=yd(u,t,r);if(c.state==="live")throw new hs(e,u);c.state==="wedged"&&R9(e,u,c.reason,o,i),gd(e)}if(!d0(e,n))throw new Error(`another Linzumi runner lock appeared while starting: ${e}`)})}function d0(e,n){RSe(k9(e),{recursive:!0});try{let t=w9(e,"wx");try{S9(t,`${JSON.stringify(n,null,2)}
 `)}finally{b9(t)}return!0}catch(t){if(Bc(t,"EEXIST"))return!1;throw t}}function E9(e,n,t){let r=`${e}.replace`;for(;;)try{let o=w9(r,"wx");try{S9(o,`${process.pid}
 `),t()}finally{b9(o),gd(r)}return}catch(o){if(Bc(o,"EEXIST")){let i=FSe(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.102",
+  "version": "1.0.104",
   "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-session-registry-parity-oracle.mjs

@@ -0,0 +1,569 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 6, session-registry/leases).
+// Relationship: Builds the TS-side PARITY ORACLE for the session-registry/
+// leases cluster of the ReScript commander port, the sibling of
+// build-queue-parity-oracle.mjs (cluster 5). The oracle bundles the REAL
+// TS session/lease modules (runnerThreadSessionRegistry.ts,
+// codexSessionOwnership.ts, leaseEpochGuard.ts, threadReconcilerLock.ts,
+// the pin-registry/disposition slice of generationOverlap.ts, and the
+// exported liveness classifiers from runner.ts - threadRunnerEntryLiveness
+// + processIsAlive) behind the cluster 1/2 one-shot batch driver: a JSON
+// array of cases on stdin, a JSON array of results on stdout. The ReScript
+// package's RegistryParityConformance drives the SAME scripted inputs
+// through the ported modules in its own scratch directories and asserts
+// per-action outcome equivalence AND byte-identical registry files - the
+// cross-impl round-trip contract that lets both commanders share
+// ~/.linzumi through M4.
+//
+// Determinism: clocks are pinned per case (updatedAtMs/nowMs ride the
+// inputs; the registry store takes nowMs on rebind), scripted lock
+// sections use millisecond-scale sleeps sized so outcomes (not timings)
+// are deterministic, timing NUMBERS inside diagnostics are normalized on
+// both sides, and scratch paths are normalized through the "$DIR"
+// placeholder in both directions. Worker-liveness pid probes use the
+// driver's own live pid and a genuinely-dead child pid so the REAL
+// process.kill(pid, 0) probe is exercised identically by both impls.
+//
+// SECRETS: the oracle only ever sees the conformance suite's synthetic
+// payloads; nothing here logs case contents.
+//
+// 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 { 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 { spawnSync } from 'node:child_process';
+import {
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import {
+  createRunnerThreadSessionRegistryStore,
+  defaultThreadSessionRehydrationMaxAgeMs,
+  reannounceThreadSessionCap,
+  reannounceableThreadSessions,
+  rehydrateThreadSessions,
+  runnerThreadSessionRegistryDir,
+  runnerThreadSessionRegistryPath,
+} from './src/runnerThreadSessionRegistry';
+import {
+  CodexSessionOwnershipConflictError,
+  findCodexSessionOwnerConflict,
+  sanitizeCodexSessionOwnership,
+} from './src/codexSessionOwnership';
+import {
+  createLeaseEpochRegistry,
+  isFencedClaim,
+  leaseEpochEnvelope,
+  readLeaseEpoch,
+} from './src/leaseEpochGuard';
+import {
+  ReconcilerLockQueuedTimeoutError,
+  ReconcilerLockTimeoutError,
+  createThreadReconcilerLock,
+} from './src/threadReconcilerLock';
+import {
+  createGenerationPinRegistry,
+  generationControlDisposition,
+} from './src/generationOverlap';
+import { processIsAlive, threadRunnerEntryLiveness } from './src/runner';
+
+// --- Placeholder + snapshot plumbing ----------------------------------------------
+
+const dirPlaceholder = '$DIR';
+
+function scratch() {
+  // realpath so macOS /var -> /private/var never splits the two impls'
+  // placeholder substitution.
+  return realpathSync(mkdtempSync(join(tmpdir(), 'linzumi-registry-oracle-')));
+}
+
+function substitute(value, from, to) {
+  if (typeof value === 'string') {
+    return value.split(from).join(to);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => substitute(entry, from, to));
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        substitute(key, from, to),
+        substitute(entry, from, to),
+      ])
+    );
+  }
+  return value;
+}
+
+function snapshotFiles(dir) {
+  const files = {};
+  const walk = (current) => {
+    for (const name of readdirSync(current).sort()) {
+      const full = join(current, name);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else {
+        files[relative(dir, full)] = readFileSync(full, 'utf8');
+      }
+    }
+  };
+  walk(dir);
+  return files;
+}
+
+function outcome(run) {
+  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),
+    };
+  }
+}
+
+function collectingLog(events, dir) {
+  return (event, payload) => {
+    events.push({ event, payload: substitute(payload, dir, dirPlaceholder) });
+  };
+}
+
+// --- Ownership pure transforms -----------------------------------------------------
+
+function handleOwnership(testCase) {
+  switch (testCase.fn) {
+    case 'conflictMessage': {
+      const error = new CodexSessionOwnershipConflictError({
+        codexThreadId: testCase.codexThreadId,
+        ownerKandanThreadId: testCase.ownerThreadId,
+        requestingKandanThreadId: testCase.requestingThreadId,
+      });
+      return { message: error.message, name: error.name };
+    }
+    case 'findConflict':
+      return outcome(() =>
+        findCodexSessionOwnerConflict(testCase.records, testCase.bind)
+      );
+    case 'sanitize':
+      return outcome(() => sanitizeCodexSessionOwnership(testCase.records));
+    default:
+      return { threw: true, message: 'unknown ownership fn ' + String(testCase.fn) };
+  }
+}
+
+// --- Lease epoch registry -----------------------------------------------------------
+
+function handleLease(testCase) {
+  switch (testCase.fn) {
+    case 'readLeaseEpoch':
+      return outcome(() => readLeaseEpoch(testCase.value));
+    case 'envelope':
+      return outcome(() => leaseEpochEnvelope(testCase.held ?? undefined));
+    case 'isFenced':
+      return outcome(() =>
+        isFencedClaim(testCase.held ?? undefined, testCase.control ?? undefined)
+      );
+    case 'scenario': {
+      const registry = createLeaseEpochRegistry();
+      const results = (testCase.actions ?? []).map((action) => {
+        switch (action.fn) {
+          case 'adopt':
+            return outcome(() => registry.adopt(action.threadId, action.epoch));
+          case 'current':
+            return outcome(() => registry.current(action.threadId));
+          case 'release':
+            return outcome(() => registry.release(action.threadId));
+          case 'snapshot':
+            return outcome(() => registry.snapshot());
+          default:
+            return { threw: true, message: 'unknown lease fn ' + String(action.fn) };
+        }
+      });
+      return { results };
+    }
+    default:
+      return { threw: true, message: 'unknown lease fn ' + String(testCase.fn) };
+  }
+}
+
+// --- Registry store paths + scripted lifecycles --------------------------------------
+
+function handleRegistryPaths(testCase) {
+  process.env.LINZUMI_SESSION_REGISTRY_DIR = testCase.envDir ?? '';
+  const result = {
+    dir: outcome(() => runnerThreadSessionRegistryDir()),
+    path: outcome(() => runnerThreadSessionRegistryPath(testCase.runnerId)),
+  };
+  delete process.env.LINZUMI_SESSION_REGISTRY_DIR;
+  return result;
+}
+
+function handleRegistryScenario(testCase) {
+  const dir = scratch();
+  const path = join(dir, 'registry.json');
+  if (testCase.initialContents !== undefined) {
+    writeFileSync(path, testCase.initialContents, 'utf8');
+  }
+  const events = [];
+  const log = collectingLog(events, dir);
+  let store = createRunnerThreadSessionRegistryStore(path, log);
+  const results = (testCase.actions ?? []).map((action) => {
+    switch (action.fn) {
+      case 'upsert':
+        return outcome(() => store.upsert(action.record));
+      case 'remove':
+        return outcome(() => store.remove(action.threadId));
+      case 'rebind':
+        return outcome(() =>
+          store.rebindCodexThread(
+            action.threadId,
+            action.newHarnessSessionId,
+            action.nowMs ?? undefined
+          )
+        );
+      case 'list':
+        return outcome(() => store.list());
+      case 'reload': {
+        // Simulated restart: a fresh store re-reads (and re-sanitizes) the file.
+        store = createRunnerThreadSessionRegistryStore(path, log);
+        return { defined: false };
+      }
+      default:
+        return { threw: true, message: 'unknown registry fn ' + String(action.fn) };
+    }
+  });
+  return substitute(
+    { results, events, files: snapshotFiles(dir) },
+    dir,
+    dirPlaceholder
+  );
+}
+
+// --- Rehydration orchestrator ---------------------------------------------------------
+
+async function handleRehydrate(testCase) {
+  const events = [];
+  const log = collectingLog(events, '\\u0000never');
+  const retired = [];
+  const attachCalls = [];
+  const attachScript = testCase.attach ?? {};
+  const unfinishedScript = testCase.unfinished ?? {};
+  const summary = await rehydrateThreadSessions({
+    records: testCase.records,
+    nowMs: testCase.nowMs,
+    maxAgeMs: testCase.maxAgeMs ?? defaultThreadSessionRehydrationMaxAgeMs,
+    pendingDurableRowCount: (record) =>
+      (testCase.pendingRows ?? {})[record.kandanThreadId] ?? 0,
+    ...(testCase.useUnfinished === true
+      ? {
+          hasUnfinishedWork: (record) => {
+            const value = unfinishedScript[record.kandanThreadId];
+            if (value === 'throw') {
+              throw new Error('scripted unfinished probe failure');
+            }
+            return value === true;
+          },
+        }
+      : {}),
+    attach: async (record) => {
+      attachCalls.push(record.kandanThreadId);
+      const value = attachScript[record.kandanThreadId] ?? 'failed';
+      if (value === 'throw') {
+        throw new Error('scripted attach failure');
+      }
+      return value;
+    },
+    retire: (record) => {
+      retired.push(record.kandanThreadId);
+    },
+    log,
+  });
+  return { summary, retired, attachCalls, events };
+}
+
+// --- Re-announce selection --------------------------------------------------------------
+
+function handleReannounce(testCase) {
+  const input = testCase.records.map((record) => ({ ...record }));
+  const entries = reannounceableThreadSessions(
+    input,
+    testCase.nowMs,
+    testCase.maxAgeMs ?? defaultThreadSessionRehydrationMaxAgeMs,
+    testCase.cap ?? reannounceThreadSessionCap
+  );
+  return {
+    entries,
+    // The input must never be mutated (the filter-copies contract).
+    inputUnchanged:
+      JSON.stringify(input) === JSON.stringify(testCase.records),
+    defaults: {
+      maxAgeMs: defaultThreadSessionRehydrationMaxAgeMs,
+      cap: reannounceThreadSessionCap,
+    },
+  };
+}
+
+// --- Reconciler lock -----------------------------------------------------------------
+
+function handleLockMessages(testCase) {
+  const running = new ReconcilerLockTimeoutError(
+    testCase.threadId,
+    testCase.timeoutMs
+  );
+  const queued = new ReconcilerLockQueuedTimeoutError({
+    threadId: testCase.threadId,
+    timeoutMs: testCase.timeoutMs,
+    queuedForMs: testCase.queuedForMs,
+    blockedSectionAgeMs: testCase.blockedSectionAgeMs ?? undefined,
+  });
+  return {
+    running: { name: running.name, message: running.message },
+    queued: {
+      name: queued.name,
+      message: queued.message,
+      // The subclass relationship existing catches rely on.
+      isTimeoutSubclass: queued instanceof ReconcilerLockTimeoutError,
+    },
+  };
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function handleLockScenario(testCase) {
+  const lock = createThreadReconcilerLock();
+  const started = [];
+  const settledOrder = [];
+  const callers = (testCase.sections ?? []).map((section) => {
+    const caller = lock
+      .runExclusive(
+        section.threadId,
+        async () => {
+          started.push(section.id);
+          if (section.sleepMs !== undefined) {
+            await sleep(section.sleepMs);
+          }
+          if (section.fail === true) {
+            throw new Error('scripted section failure ' + section.id);
+          }
+          return section.id;
+        },
+        section.deadlineMs ?? undefined
+      )
+      .then(
+        (value) => ({ id: section.id, outcome: 'completed', value }),
+        (error) => ({
+          id: section.id,
+          outcome:
+            error instanceof ReconcilerLockQueuedTimeoutError
+              ? 'queued_timeout'
+              : error instanceof ReconcilerLockTimeoutError
+                ? 'section_timeout'
+                : 'failed',
+          message:
+            error instanceof ReconcilerLockQueuedTimeoutError ||
+            error instanceof ReconcilerLockTimeoutError
+              ? undefined
+              : error.message,
+        })
+      )
+      .then((result) => {
+        settledOrder.push(result.id);
+        return result;
+      });
+    return caller;
+  });
+  const results = await Promise.all(callers);
+  // Let any background sections settle so zombie runs (there must be none)
+  // are observable.
+  await sleep(testCase.settleMs ?? 150);
+  return {
+    results,
+    started,
+    settledOrder,
+    busyAfter: (testCase.sections ?? []).some((section) =>
+      lock.isBusy(section.threadId)
+    ),
+    activeThreadCountAfter: lock.activeThreadCount(),
+  };
+}
+
+// --- Generation pins -------------------------------------------------------------------
+
+function handlePins(testCase) {
+  if (testCase.fn === 'disposition') {
+    const pinned = new Set(testCase.pinned ?? []);
+    return outcome(() =>
+      generationControlDisposition({
+        role: testCase.role,
+        threadId: testCase.threadId ?? undefined,
+        isPinned: (threadId) => pinned.has(threadId),
+      })
+    );
+  }
+  const registry = createGenerationPinRegistry();
+  const results = (testCase.actions ?? []).map((action) => {
+    switch (action.fn) {
+      case 'pin':
+        return outcome(() => registry.pin(action.threadId));
+      case 'release':
+        return outcome(() => registry.release(action.threadId));
+      case 'isPinned':
+        return outcome(() => registry.isPinned(action.threadId));
+      case 'replaceAll':
+        return outcome(() => registry.replaceAll(action.threadIds));
+      case 'clear':
+        return outcome(() => registry.clear());
+      case 'snapshot':
+        return outcome(() => registry.snapshot());
+      case 'size':
+        return outcome(() => registry.size());
+      default:
+        return { threw: true, message: 'unknown pins fn ' + String(action.fn) };
+    }
+  });
+  return { results };
+}
+
+// --- Thread-worker liveness ---------------------------------------------------------------
+
+// A genuinely-dead pid: spawnSync returns only after the child exits, so
+// the pid no longer maps to a live process (the TS unit tests' technique).
+let cachedDeadPid;
+function deadPid() {
+  if (cachedDeadPid === undefined) {
+    const result = spawnSync(process.execPath, ['-e', '0']);
+    cachedDeadPid = result.pid;
+  }
+  return cachedDeadPid;
+}
+
+function resolvePid(spec) {
+  if (spec === 'live') return process.pid;
+  if (spec === 'dead') return deadPid();
+  return undefined;
+}
+
+function fakeCodexClient(isClosed) {
+  return {
+    request: async () => ({ jsonrpc: '2.0', id: 1, result: {} }),
+    notify: () => undefined,
+    onNotification: () => undefined,
+    onRequest: () => undefined,
+    onClose: () => undefined,
+    isClosed: () => isClosed === true,
+    close: () => undefined,
+  };
+}
+
+function handleWorkerLiveness(testCase) {
+  if (testCase.fn === 'processIsAlive') {
+    return outcome(() => processIsAlive(resolvePid(testCase.pid)));
+  }
+  const entry =
+    testCase.entry.kind === 'starting'
+      ? { kind: 'starting', promise: new Promise(() => undefined) }
+      : {
+          kind: 'running',
+          handle: {
+            kandanThreadId: testCase.entry.threadId ?? 'thread-1',
+            codex: fakeCodexClient(testCase.entry.ipcClosed),
+            close: async () => undefined,
+            ...(testCase.entry.sessionClosed === undefined
+              ? {}
+              : { sessionClosed: () => testCase.entry.sessionClosed === true }),
+            ...(testCase.entry.pid === undefined
+              ? {}
+              : { processPid: resolvePid(testCase.entry.pid) }),
+          },
+        };
+  return outcome(() => threadRunnerEntryLiveness(entry));
+}
+
+// --- Dispatch --------------------------------------------------------------------------
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'ownership':
+      return handleOwnership(testCase);
+    case 'lease':
+      return handleLease(testCase);
+    case 'registryPaths':
+      return handleRegistryPaths(testCase);
+    case 'registryScenario':
+      return handleRegistryScenario(testCase);
+    case 'rehydrate':
+      return await handleRehydrate(testCase);
+    case 'reannounce':
+      return handleReannounce(testCase);
+    case 'lockMessages':
+      return handleLockMessages(testCase);
+    case 'lockScenario':
+      return await handleLockScenario(testCase);
+    case 'pins':
+      return handlePins(testCase);
+    case 'workerLiveness':
+      return handleWorkerLiveness(testCase);
+    default:
+      return { threw: true, message: 'unknown op ' + String(testCase.op) };
+  }
+}
+
+let stdin = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) {
+  stdin += chunk;
+}
+const cases = JSON.parse(stdin);
+const results = [];
+for (const testCase of cases) {
+  results.push(await handle(testCase));
+}
+process.stdout.write(JSON.stringify(results), () => {
+  process.exit(0);
+});
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+// runner.ts's graph resolves assets/ relative to the bundle at import time
+// (the hello-project scaffold's inlined logo), so the asset must sit next
+// to the emitted oracle - the build-auth-parity-oracle precedent.
+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: 'session-registry-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(
+    packageRoot,
+    '.differential/session-registry-parity-oracle.mjs'
+  ),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});

package/scripts/bump-cli-version.mjs

@@ -12,7 +12,7 @@
 //      publishes @linzumi/cli@<new-version> to npm.
 //
 // The package version is pinned in several places (package.json,
-// src/version.ts, README.md, and version-pinning tests). This script rewrites
+// src/version.ts, README.md, the public alias manifest, and version-pinning tests). This script rewrites
 // every known site, FAILS LOUDLY if any expected pattern is missing, and then
 // scans package.json/src/README/test/scripts/bin for any leftover
 // old-version string - so a future, not-yet-listed pin site cannot silently
@@ -71,6 +71,7 @@ if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$/.test(newVersion)) {
 
 const packageRoot =
   explicitRoot ?? dirname(dirname(fileURLToPath(import.meta.url)));
+const aliasPackageRoot = join(dirname(packageRoot), 'linzumi');
 
 let manifest;
 
@@ -96,6 +97,24 @@ if (oldVersion === newVersion) {
 // the bump aborts; add new entries here when a new pin site appears (the
 // leftover scan below is what tells you one appeared).
 const knownSites = [
+  {
+    file: '../linzumi/package.json',
+    description: 'public alias manifest version',
+    pattern: `"version": "${oldVersion}"`,
+    replacement: `"version": "${newVersion}"`,
+  },
+  {
+    file: '../linzumi/package.json',
+    description: 'public alias exact canonical dependency',
+    pattern: `"@linzumi/cli": "${oldVersion}"`,
+    replacement: `"@linzumi/cli": "${newVersion}"`,
+  },
+  {
+    file: '../../pnpm-lock.yaml',
+    description: 'public alias lockfile dependency specifier',
+    pattern: `specifier: ${oldVersion}\n        version: link:../linzumi-cli`,
+    replacement: `specifier: ${newVersion}\n        version: link:../linzumi-cli`,
+  },
   {
     file: 'package.json',
     description: 'npm package manifest version',
@@ -209,6 +228,11 @@ function scanTargets() {
   const roots = ['src', 'test', 'scripts', 'bin'];
   const files = ['package.json', 'README.md'];
 
+  // Spec: plans/2026-07-12-linzumi-unscoped-npm-package-spec.md
+  // The alias version and canonical dependency are one release invariant.
+  files.push(relative(packageRoot, join(aliasPackageRoot, 'package.json')));
+  files.push('../../pnpm-lock.yaml');
+
   for (const root of roots) {
     const rootPath = join(packageRoot, root);
     let entries;