cli-relay 1.0.1 → 1.0.3

package/README.md

@@ -6,6 +6,23 @@ Resume-by-reference delegation across codex, agy, claude-code (command-code: fre
 Built 2026-08-16/17, inspired by DeepSeek Harness's subagent architecture but deliberately
 smaller — see design history below before re-deriving any of this from scratch.
 
+## Built for your agent to drive, not just for you to type
+
+cli-relay is designed to be called *by your own coding agent* as a tool, not only typed by
+hand. Every `fresh`/`resume` call returns one structured JSON object on stdout — a native
+session id, the model's answer, exit code, timing/signal info — specifically so an agent can
+parse the result and decide what to do next without guessing at free-form text. Exit codes are
+deliberate and stable (0 success, 1 general error — including `doctor` when no backend at
+all is usable, 2 usage error, 3 "ran but produced no usable answer" — see Exit
+codes below) so an agent's own control flow can branch on them directly.
+
+In practice that means: point your daily-driver agent (Claude Code, Codex, whatever you're
+already using) at this README and ask it to use `cli-relay` to delegate a task to a different
+backend, or to resume a thread from three days ago — it has everything it needs in this file
+and in `cli-relay doctor`'s output to do that itself, without you hand-holding it through the
+CLI's own flags. Nothing about this requires an agent, though — every command works exactly the
+same typed directly into a terminal by hand.
+
 ## Installation
 
 Requires Node.js 18.17 or newer.
@@ -44,9 +61,16 @@ cli-relay pins <thread>
 Backends: `codex`, `agy`, `claude-code`, `command-code` (command-code is fresh-only —
 its resume showed a reproducible seed-turn bug live, see file header).
 
-`cli-relay doctor` checks that every backend's binary is actually resolvable on PATH —
+`cli-relay doctor` checks that each backend's binary is actually resolvable on PATH —
 useful after a fresh machine setup or when a backend call fails and you're not sure whether
-it's cli-relay or the backend itself. `--dry-run` / `--print-command` prints the exact argv
+it's cli-relay or the backend itself. It exits 1 only when *no* backend at all is usable
+(zero of the built-in codex/agy/claude-code/command-code binaries resolve) — a genuinely
+broken install with nothing working. A partial install (1-3 of the four present) is the
+documented normal setup (see Prerequisites: "you don't need all four") and exits 0, so the
+gate catches "nothing works here" without punishing "not everything installed". Custom user
+adapters are reported in its output but don't affect the exit code (they're optional by
+definition). `--dry-run` /
+`--print-command` prints the exact argv
 that would be spawned (prompt fully assembled, pins injected) without spawning anything or
 touching the session map at all — it enforces the same refusals a real run would (e.g. won't
 preview a `resume` on an unconfirmed thread, won't preview against a thread with a run
@@ -84,8 +108,11 @@ their configured base values.
 
 Built-in adapters live in `src/adapters/` and are discovered at runtime. Additional `.mjs`,
 `.js`, or `.cjs` adapters can be placed in `~/.cli-relay/adapters/`; an adapter with the same
-`name` as a built-in replaces it. Each adapter provides `fresh`, optional `resume`, `env`,
-`parse`, optional `checkCompaction`, and optional `binaryCandidates` (an ordered list of
+`name` as a built-in replaces it. Note that `.js` files load as CommonJS unless a
+`~/.cli-relay/package.json` sets `"type": "module"` — write ESM adapters as `.mjs` (an
+ESM-syntax `.js` file fails to load and is skipped with a warning). Each adapter provides
+`fresh`, optional `resume`, `env`, `parse`, optional `checkCompaction`, and optional
+`binaryCandidates` (an ordered list of
 binary names `doctor` tries — most adapters only need one, but a backend that ships under
 more than one binary name can list several). Housekeeping commands are dispatched before
 adapter discovery, so they remain available if an adapter cannot be loaded. A malformed
@@ -137,9 +164,13 @@ Backs up and restores your actual `~/.cli-relay/sessions.json` around the run, s
 time. Covers: list/reset, fresh→resume context retention (agy), the circuit breaker's actual
 3-strikes trip (live-fired against codex with a bad id, not just traced), SIGINT mid-run
 cleanup, and SIGINT while genuinely pre-spawn (lock held elsewhere — must abort immediately
-without spawning). 32/32 passing as of the last run. Does not exercise `claude-code` (real
-billing per call) or `command-code` resume (disabled). Also does not yet cover `doctor` or
-`--dry-run` — both are verified manually against the real backends whenever they change (see
+without spawning). 56/56 passing as of the last run. Since the 2026-09-02 GLM-5.3 fixes the
+tail sections also cover, hermetically (a fake `agy` shimmed onto PATH, direct lock-module
+harnesses, and PATH-stubbed binaries — no live backend needed): the reset-then-recreate
+refusal, the cancelled-resume circuit-breaker behavior, lock release ownership /
+exclusive holder write / pid reuse / stale reclaim, and `doctor`'s exit-code gate. Does not
+exercise `claude-code` (real billing per call) or `command-code` resume (disabled);
+`--dry-run` is still verified manually against the real backends whenever it changes (see
 the 2026-09-01 Review history entries below for what that's caught), not by an automated
 case in this file yet.
 
@@ -238,6 +269,45 @@ correctly flagged its own uncertainty (its sandbox blocked `git` access) rather
 asserting it, which is why it was checked rather than trusted or dismissed outright. Full
 brief in `docs/cli-continues-cherrypick-brief.md`.
 
+**GLM-5.3 adversarial audit fixes (2026-09-02).** A fresh GLM-5.3 session audited the
+merged result against `main` at 1.0.2 (full brief in `docs/glm53-fix-brief.md`); every
+finding was re-verified against the actual source before fixing, in this project's
+usual audit → fix → adversarial re-check rhythm. Three must-fix races: (1)
+`reset`-then-recreate mid-run corrupted the session map — if thread A was mid-run and
+someone ran `cli-relay reset t` then a quick recreate that completed first, A's critical
+section 2 would find the *replacement* session and unconditionally overwrite its
+`native_session_id`, cross-wiring a codex id onto an agy-backend thread (or vice versa),
+or silently discarding the newer id for an older one — CS2 and the fresh-failure branch
+now verify the map entry is still the *same session instance* CS1 snapshotted (backend +
+pre-run native id + CS1's run-start timestamp) and warn-and-refuse on mismatch, the same
+pattern the thread-deleted race already used; (2) lock release never verified the
+releaser still owned the lock — a holder suspended past `LOCK_STALE_MS` (laptop sleep,
+VM pause) could wake and `rm` its *successor's* lock directory, admitting a third
+entrant — release now mirrors `reclaim()`'s rename-verify-restore pattern; (3) the
+`mkdir` → `holder.json` write gap wasn't safely closed — a suspension longer than
+`LOCK_TIMEOUT_MS` between the two calls let the original holder's plain write clobber
+the successor's `holder.json`, producing two holders — the write is now an exclusive
+(`'wx'`) create whose EEXIST falls back to the waiter path, with the mkdir-EEXIST and
+write-EEXIST error paths split. Lower severity: a Ctrl-C'd (or timeout-killed) resume no
+longer counts toward the 3-strikes circuit breaker — a cancelled run is neither success
+nor failure, so the counter is left untouched (three interrupted resumes on a healthy
+thread previously auto-unconfirmed it); a stale holder record bearing the *next
+invocation's own reused pid* is now reclaimed instead of being waited on until the lock
+times out (pid reuse by an unrelated process still self-heals via the timestamp path);
+`tests/smoke.sh`'s `rm -f` on the lock directory — a silent no-op on directories — is
+now `rm -rf`; `doctor` exits 1 only when no backend at all is usable (a partial install —
+the README-documented normal setup — still exits 0) so it works as a CI gate; and pin
+text containing the literal `[END PINNED FACTS]` or a carriage return is rejected, so a
+pin can no longer forge the pinned-block boundary.
+Deliberately left as-is, with reasoning: the documented `--dry-run` token-stripping
+limitation (any fix changes flag-position CLI parsing behavior, and the audience is
+agents, not free-text discussion of flags); `.js` user adapters still load, now
+explicitly documented as CommonJS unless a `~/.cli-relay/package.json` says otherwise
+(chosen over dropping `.js` support — less disruptive for existing working CommonJS
+adapters); and the Windows process-group-kill gap is now a documented known gap rather
+than a guess-fix. The smoke suite grew hermetic fake-backend, lock-module, and doctor
+harness sections alongside the live-backend cases.
+
 ## Field notes from real use
 
 First real-world use (2026-08-17, an audit task run across all three model lanes in
@@ -360,6 +430,13 @@ guessing at intent, the same trap this whole project has avoided everywhere else
   finished), so the thread doesn't self-heal via lock staleness — it stays stuck until
   `LOCK_STALE_MS` (~21 min) passes on the *next* invocation against that thread. Narrow
   window, real gap; not closed here.
+- **Windows process-group cleanup is POSIX-only (documented 2026-09-02, not fixed).**
+  `package.json` declares no `os` restriction, but the wrapper's child termination —
+  `process.kill(-pgid, ...)` for Ctrl-C and the spawn timeout — no-ops on Windows, so a
+  backend child there would survive a router-initiated kill. A real fix needs
+  `taskkill /T /F` and a Windows box to verify against; this repo's test, dev, and
+  publish history is entirely macOS/Linux, so it's flagged here rather than
+  guess-fixed.
 - `doctor`'s `which`/`where` child processes aren't tracked by the SIGINT handler — a Ctrl-C
   during `doctor` reports "nothing spawned yet" even though those children are briefly alive.
   Low severity (`which` exits in milliseconds).

package/cli-relay.mjs

@@ -13,7 +13,8 @@
  *
  * Exit codes:
  *   0  success
- *   1  general error or backend spawn failure
+ *   1  general error or backend spawn failure (also `doctor`, when no backend at
+ *      all is usable — a partial install is the normal setup and still exits 0)
  *   2  usage error
  *   3  backend produced an id/exit-0-shaped result but no usable answer
  */
@@ -200,6 +201,20 @@ function assertNotInFlight(session, thread) {
   );
 }
 
+// CS1 snapshots the exact session instance it marks running. CS2 (and the fresh-failure
+// branch below) must verify the map entry is still that same instance before recording
+// an outcome: a `reset` mid-run followed by a recreate on the same thread name leaves a
+// *different* session under that name, and recording onto it would cross-wire a native
+// session id across backends (a codex id on an agy-backend thread, or vice versa) or
+// silently discard the replacement's newer id (found in the GLM-5.3 audit). Backend plus
+// the pre-run native id plus CS1's own run-start timestamp identify the instance; on
+// mismatch, warn and refuse to record — the same pattern the thread-deleted case uses.
+function isSameSessionInstance(session, record) {
+  return session.backend === record.backend &&
+    session.native_session_id === record.native_session_id &&
+    session.run_started_iso === record.run_started_iso;
+}
+
 async function main() {
   const cliArgs = process.argv.slice(2);
 
@@ -210,8 +225,8 @@ async function main() {
   const { loadAdapters } = await import('./src/adapter-loader.mjs');
   const adapters = await loadAdapters();
   if (cliArgs[0] === 'doctor') {
-    await cmdDoctor(adapters);
-    process.exit(0);
+    const anyBackendUsable = await cmdDoctor(adapters);
+    process.exit(anyBackendUsable ? 0 : 1);
   }
 
   const dryRun = cliArgs.includes('--dry-run') || cliArgs.includes('--print-command');
@@ -331,6 +346,17 @@ async function main() {
         );
         return;
       }
+      if (!isSameSessionInstance(session, record)) {
+        // Reset-then-recreate mid-run: the map entry is now a different session
+        // instance (possibly on a different backend). Don't cross-wire this run's
+        // outcome onto it.
+        console.error(
+          `warning: thread "${thread}" in ${MAP_PATH} is no longer the session this run ` +
+          `started from (it was reset or replaced while this run was in flight) — ` +
+          'outcome not recorded.',
+        );
+        return;
+      }
       session.status = 'ready';
       session.last_run_iso = new Date().toISOString();
       session.last_exit_code = code;
@@ -369,22 +395,40 @@ async function main() {
       );
       return;
     }
+    if (!isSameSessionInstance(session, record)) {
+      // Reset-then-recreate mid-run: the map entry is now a different session
+      // instance (possibly on a different backend). Don't cross-wire this run's
+      // native id onto it or discard its newer id in favor of this run's.
+      console.error(
+        `warning: thread "${thread}" in ${MAP_PATH} is no longer the session this run ` +
+        `started from (it was reset or replaced while this run was in flight) — outcome` +
+        `${newId ? ` (including native id ${newId})` : ''} not recorded.`,
+      );
+      return;
+    }
     if (newId) {
       session.native_session_id = newId;
       session.confirmed = true;
       session.consecutive_resume_failures = 0;
     }
     if (mode === 'resume') {
-      if (parsed.answer) {
-        session.consecutive_resume_failures = 0;
-      } else {
-        session.consecutive_resume_failures = (session.consecutive_resume_failures ?? 0) + 1;
-        if (session.confirmed &&
-            session.consecutive_resume_failures >= RESUME_FAILURE_THRESHOLD) {
-          session.confirmed = false;
-          autoUnconfirmed = true;
+      if (!cancelled) {
+        if (parsed.answer) {
+          session.consecutive_resume_failures = 0;
+        } else {
+          session.consecutive_resume_failures = (session.consecutive_resume_failures ?? 0) + 1;
+          if (session.confirmed &&
+              session.consecutive_resume_failures >= RESUME_FAILURE_THRESHOLD) {
+            session.confirmed = false;
+            autoUnconfirmed = true;
+          }
         }
       }
+      // A run the wrapper cancelled (Ctrl-C, SIGTERM, or the spawn timeout) says
+      // nothing about the backend's resume health — neither success nor failure.
+      // The failure counter is deliberately left untouched: three interrupted
+      // resumes on a perfectly healthy thread must not auto-unconfirm it (found
+      // in the GLM-5.3 audit).
       resumeFailureCount = session.consecutive_resume_failures;
     }
     session.status = 'ready';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-relay",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Persistent CLI router for resuming named sessions across AI coding-agent backends.",
   "type": "module",
   "bin": {

package/src/commands/doctor.mjs

@@ -1,4 +1,7 @@
 import { spawn } from 'node:child_process';
+import { EXPECTED_BACKENDS } from '../adapter-loader.mjs';
+
+const REQUIRED_BACKEND_SET = new Set(EXPECTED_BACKENDS);
 
 export function realWhichCheck(binary) {
   return new Promise((resolve) => {
@@ -36,9 +39,11 @@ export async function cmdDoctor(adapters, isAvailable = realWhichCheck) {
     return resolved;
   }));
 
+  let requiredAvailable = 0;
   for (let index = 0; index < results.length; index += 1) {
     const result = results[index];
     const check = checks[index];
+    const isRequired = REQUIRED_BACKEND_SET.has(check.adapter.name);
     const tried = check.attempted.join(', ') || 'none';
     if (result.status === 'rejected') {
       console.log(
@@ -52,9 +57,17 @@ export async function cmdDoctor(adapters, isAvailable = realWhichCheck) {
       console.log(
         `${check.adapter.name}: available (found; tried: ${tried}; resolved: ${resolved})`,
       );
+      if (isRequired) requiredAvailable += 1;
     } else {
       const hint = check.adapter.installHint ? ` — install: ${check.adapter.installHint}` : '';
       console.log(`${check.adapter.name}: unavailable (not found; tried: ${tried})${hint}`);
     }
   }
+
+  // doctor doubles as a machine-setup gate: the caller (main) exits 1 only when NO backend
+  // at all is usable — a genuinely broken install with nothing working. A partial install
+  // (1-3 of the four built-in backends present) is the documented normal setup (README,
+  // Prerequisites: "you don't need all four") and passes the gate. Custom user adapters are
+  // reported in the output above but never affect it — they're optional by definition.
+  return requiredAvailable > 0;
 }

package/src/core/lock.mjs

@@ -75,49 +75,129 @@ function reclaim(expectedHolderRaw) {
 
 export async function withLock(fn) {
   const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let myHolderRaw = null;
   for (;;) {
     try {
       mkdirSync(LOCK_PATH);
-      writeFileSync(
-        join(LOCK_PATH, LOCK_HOLDER_FILE),
-        JSON.stringify({ pid: process.pid, ts: Date.now() }),
-      );
-      break;
     } catch (error) {
       if (error.code !== 'EEXIST') throw error;
-      const holderRaw = readHolderRaw();
-      let eligible = false;
-      if (holderRaw !== null) {
-        try {
-          const holder = JSON.parse(holderRaw);
-          eligible = Date.now() - holder.ts > LOCK_STALE_MS || !isPidAlive(holder.pid);
-        } catch {
-          eligible = true; // holder.json exists but isn't valid JSON — not a state any live holder writes
-        }
-      } else {
-        // Missing holder.json while the lock dir exists: either mid-write (a real holder's
-        // mkdir+writeFileSync are back-to-back synchronous, resolving in microseconds) or
-        // the holder died in that exact window and never will. Use the lock directory's own
-        // mtime — an objective fact any process can check on the same physical directory —
-        // rather than this waiter's own elapsed wait time, which can't tell "the original
-        // holder died" apart from "a brand-new holder's mkdir just landed."
-        try {
-          eligible = Date.now() - statSync(LOCK_PATH).mtimeMs > LOCK_TIMEOUT_MS;
-        } catch {
-          eligible = false; // the directory itself vanished already — nothing here to reclaim
-        }
-      }
-      if (eligible && reclaim(holderRaw)) continue;
-      if (Date.now() > deadline) {
-        throw new Error(`another cli-relay invocation holds the lock (${LOCK_PATH}) — not waiting forever`);
-      }
-      await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+      // Someone else's lock directory exists — evaluate it as a waiter below.
+      await waitForLockSlot(deadline);
+      continue;
     }
+
+    // The directory is ours and empty. Write holder.json with an EXCLUSIVE create
+    // ('wx'): if a waiter reclaimed this still-empty directory while we were
+    // suspended between mkdir and this write (a suspension longer than
+    // LOCK_TIMEOUT_MS — laptop sleep, VM pause), the successor's holder.json
+    // already exists and a plain write would silently clobber it — two holders at
+    // once (found in the GLM-5.3 audit). EEXIST throws loudly instead, and the
+    // loser falls back to the waiter path below: the successor is the rightful
+    // holder now.
+    myHolderRaw = JSON.stringify({ pid: process.pid, ts: Date.now() });
+    try {
+      writeFileSync(join(LOCK_PATH, LOCK_HOLDER_FILE), myHolderRaw, { flag: 'wx' });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      // Our just-created directory was reclaimed mid-gap and now holds a
+      // successor's holder.json — evaluate the lock as a waiter, same as the
+      // mkdir-EEXIST case, but for a distinct reason (we briefly held the
+      // directory; the EEXIST came from the write, not the mkdir).
+      await waitForLockSlot(deadline);
+      continue;
+    }
+    break;
   }
 
   try {
     return await fn();
   } finally {
-    try { rmSync(LOCK_PATH, { recursive: true, force: true }); } catch {}
+    releaseLock(myHolderRaw);
+  }
+}
+
+// The waiter half of acquisition, shared by both EEXIST paths above: the lock
+// directory exists but isn't ours — either created by someone else, or created by
+// us and then legitimately reclaimed out from under our suspended holder.json
+// write. Judge the current holder, reclaim it if eligible, and otherwise sleep
+// until the deadline.
+async function waitForLockSlot(deadline) {
+  const holderRaw = readHolderRaw();
+  let eligible = false;
+  if (holderRaw !== null) {
+    try {
+      const holder = JSON.parse(holderRaw);
+      // A holder record bearing this process's own pid cannot be a lock we hold:
+      // this path only runs before this call acquires, and an earlier withLock in
+      // this process has always released first (cli-relay never overlaps them). It
+      // is either an abandoned leftover of our own failed release or — the case
+      // that matters — a dead holder whose pid was reused by this very invocation,
+      // which would otherwise see *itself* as a live holder and fail spuriously
+      // after LOCK_TIMEOUT_MS (found in the GLM-5.3 audit; the mirror-image
+      // false-positive, pid reuse by an unrelated process, still self-heals via
+      // the timestamp path above).
+      eligible = Date.now() - holder.ts > LOCK_STALE_MS ||
+        !isPidAlive(holder.pid) ||
+        holder.pid === process.pid;
+    } catch {
+      eligible = true; // holder.json exists but isn't valid JSON — not a state any live holder writes
+    }
+  } else {
+    // Missing holder.json while the lock dir exists: either mid-write (a real
+    // holder's mkdir+writeFileSync are back-to-back synchronous, resolving in
+    // microseconds, and the exclusive write now fails loudly rather than
+    // clobbering) or the holder died in that exact window and never will. Use the
+    // lock directory's own mtime — an objective fact any process can check on the
+    // same physical directory — rather than this waiter's own elapsed wait time,
+    // which can't tell "the original holder died" apart from "a brand-new
+    // holder's mkdir just landed."
+    try {
+      eligible = Date.now() - statSync(LOCK_PATH).mtimeMs > LOCK_TIMEOUT_MS;
+    } catch {
+      eligible = false; // the directory itself vanished already — nothing here to reclaim
+    }
+  }
+  if (eligible && reclaim(holderRaw)) return;
+  if (Date.now() > deadline) {
+    throw new Error(`another cli-relay invocation holds the lock (${LOCK_PATH}) — not waiting forever`);
+  }
+  await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+}
+
+// Releasing by unconditionally rmSync-ing LOCK_PATH never verifies the releaser
+// still owns the lock. If a holder is suspended past LOCK_STALE_MS (laptop sleep,
+// VM pause, or a clock adjustment that makes its timestamp look stale), a waiter
+// legitimately reclaims and becomes the new holder; when the original holder wakes
+// and finishes, an unconditional delete destroys its successor's lock and admits a
+// third entrant (found in the GLM-5.3 audit). Mirror reclaim()'s own pattern:
+// rename to a private path first (atomic — at most one renamer of a given source
+// path can win), verify the captured holder.json is still this process's own
+// write, and only then rm; if it isn't ours, put it back for the rightful holder
+// rather than destroying it.
+function releaseLock(myHolderRaw) {
+  const claim = `${LOCK_PATH}.release.${process.pid}.${Date.now()}`;
+  try {
+    renameSync(LOCK_PATH, claim);
+  } catch {
+    return; // nothing at LOCK_PATH (or a real error) — nothing to either verify or destroy
+  }
+  let capturedHolderRaw;
+  try {
+    capturedHolderRaw = readFileSync(join(claim, LOCK_HOLDER_FILE), 'utf8');
+  } catch {
+    capturedHolderRaw = null;
+  }
+  if (capturedHolderRaw === myHolderRaw) {
+    rmSync(claim, { recursive: true, force: true });
+  } else {
+    // Not our write anymore — a waiter reclaimed while we were suspended and this
+    // is its lock. Restore it; if LOCK_PATH was recreated in the meantime by yet
+    // another party there is nowhere safe to put it back — drop it rather than
+    // loop forever, the same compounding-race reasoning as reclaim().
+    try {
+      renameSync(claim, LOCK_PATH);
+    } catch {
+      rmSync(claim, { recursive: true, force: true });
+    }
   }
 }

package/src/core/pins.mjs

@@ -2,9 +2,13 @@ import { MAX_PIN_LENGTH } from '../config.mjs';
 
 export function validatePinText(factText) {
   if (!factText || !factText.trim()) return 'fact text must not be empty or whitespace-only';
-  if (factText.includes('\n')) {
+  if (factText.includes('\n') || factText.includes('\r')) {
     return 'fact text must be a single line — multiline facts risk breaking the pinned-block delimiter';
   }
+  if (factText.includes('[END PINNED FACTS]')) {
+    return 'fact text must not contain the literal "[END PINNED FACTS]" — a pin must not ' +
+      'be able to forge the pinned-block boundary (found in the GLM-5.3 audit)';
+  }
   if (factText.length > MAX_PIN_LENGTH) {
     return `fact text is ${factText.length} chars, over the ${MAX_PIN_LENGTH}-char limit — ` +
       'keep pins short and curated, not a transcript';