amicus 4.8.1 → 4.9.0

package/src/utils/engine-skew-records.js

@@ -0,0 +1,146 @@
+/**
+ * @module utils/engine-skew-records
+ * Server identity and the bounded store of standing engine-skew records.
+ *
+ * EXTRACTED from src/utils/engine-skew.js (v4.9 W10 round 2), which owns the
+ * comparison, the announcement and the remedy text and had reached the 300-line
+ * gate. Everything here answers one question instead — WHICH SERVER is this,
+ * and what was last observed about it — and that is where the round-2 findings
+ * on identity collapse (A3), the shared unknown bucket (B3) and unbounded growth
+ * (B7) all landed. `engine-skew.js` re-exports the public half, so callers and
+ * tests keep one import site.
+ *
+ * BEST-EFFORT, like its parent: an identity read on a diagnostic path must not
+ * be able to fail a session create, so nothing here throws.
+ */
+
+'use strict';
+
+/**
+ * The standing skew records: server identity -> `{server, installed}`, holding
+ * the LAST comparison observed for that server (see noteSessionVersion). Not a
+ * single process-wide slot (W10 round-1 review A3+B3): one slot stamped the
+ * first skew ever seen onto every later failure, including failures of an
+ * unrelated server and failures after the skew was fixed mid-run.
+ */
+const _skewByServer = new Map();
+
+/** The key used when the client cannot name its server. Distinct from every
+ *  real base URL, so an unidentified server borrows no one else's record. */
+const UNKNOWN_SERVER_KEY = '<unknown server>';
+
+/**
+ * How many servers the map remembers (round-2 review B7). This is
+ * process-lifetime state on a path that runs once per session create — every
+ * fanout leg, every council seat, for as long as an MCP server stays up — and
+ * its key is a server URL, which an operator controls. 32 is far past any real
+ * topology (production talks to ONE spawned server per process) while still
+ * being a bound rather than a hope.
+ */
+const MAX_SKEW_SERVERS = 32;
+
+/**
+ * The identity of the server this client talks to — its base URL, normalized to
+ * an origin AND path.
+ *
+ * MEASURED 2026-08-25 against this checkout's `@opencode-ai/sdk`, not read off
+ * the types: `createOpencodeClient({ baseUrl })` returns an object whose only
+ * non-namespace key is `_client`, and `client._client.getConfig()` answers
+ * `{bodySerializer, headers, parseAs, querySerializer, baseUrl, fetch}` — the
+ * `baseUrl` being exactly the string passed in, and `undefined` when none was.
+ * That is the SMALLEST honest key available at session-create time: no round
+ * trip, no new SDK call, and in production `startServer` always builds the
+ * client from one spawned server's own `sdkServer.url`, so distinct servers get
+ * distinct ports and distinct keys. It is an identity, not proof of identity —
+ * two amicus processes that spawn servers on the same port at different times
+ * would collide — which is why every record is also refreshed on each create.
+ *
+ * THE PATH IS PART OF THE KEY (round-2 review A3). `new URL(raw).origin` alone
+ * collapses two distinct servers onto one record whenever they share an origin
+ * — a reverse proxy at `…:8080/engine-a` and `…:8080/engine-b`, and MEASURED
+ * 2026-08-26, EVERY opaque-origin URL: `new URL('unix:///tmp/a.sock').origin`
+ * and its `b.sock` twin are both the literal string `"null"`. A shared record
+ * is precisely what per-server keying exists to prevent. Amicus's own topology
+ * cannot reach it today — `startServer` is the only production client builder
+ * and always passes one spawned server's `http://127.0.0.1:<port>` — but the
+ * external/shared-server case in engine-skew.js's SCOPE paragraph can, and
+ * keeping the path costs one expression.
+ *
+ * `_client` is the SDK's own internal handle and the ONLY route to that value
+ * (measured: the client's other keys are all resource namespaces). If a future
+ * SDK renames it, this returns UNKNOWN_SERVER_KEY and every server shares one
+ * bucket again. That bucket is genuinely degraded, not merely coarser: under it
+ * a record can be attributed to the wrong server AND cleared by the wrong one.
+ * `noteSessionVersion` clears from it anyway, on purpose — its docblock records
+ * the measurement behind that ruling.
+ *
+ * @param {object} [client] - the SDK client, or nothing
+ * @returns {string} origin + path, the raw value if it will not parse, else
+ *   UNKNOWN_SERVER_KEY. Never throws: an identity read on a diagnostic path
+ *   must not be able to fail a session create.
+ */
+function serverKeyForClient(client) {
+  let raw;
+  try {
+    raw = client && client._client && typeof client._client.getConfig === 'function'
+      ? client._client.getConfig().baseUrl
+      : undefined;
+  } catch (_e) {
+    return UNKNOWN_SERVER_KEY;
+  }
+  if (typeof raw !== 'string' || !raw.trim()) { return UNKNOWN_SERVER_KEY; }
+  try {
+    const url = new URL(raw);
+    return `${url.origin}${url.pathname}`.replace(/\/+$/, '') || url.origin;
+  } catch (_e) { return raw.trim(); }
+}
+
+/** The record standing against one KEY, or undefined. */
+function skewForKey(key) {
+  return _skewByServer.get(key);
+}
+
+/** Record a skew as the most RECENTLY seen, evicting the least recent past the
+ *  bound. Re-inserting on every observation is what makes "recent" mean last
+ *  observed rather than first seen. */
+function rememberSkew(key, skew) {
+  _skewByServer.delete(key);
+  _skewByServer.set(key, skew);
+  while (_skewByServer.size > MAX_SKEW_SERVERS) {
+    _skewByServer.delete(_skewByServer.keys().next().value);
+  }
+}
+
+/** Drop one server's record — a retraction, or "an older engine answers here
+ *  now". Safe on a key that was never recorded. */
+function forgetSkew(key) {
+  _skewByServer.delete(key);
+}
+
+/**
+ * The standing skew record for ONE server, or null.
+ *
+ * A caller with no client gets the UNKNOWN key's record — never another
+ * server's. Reading is defensive but cannot meaningfully throw.
+ * @param {object} [client] - the SDK client whose server is being asked about
+ * @returns {{server: string, installed: string}|null}
+ */
+function currentEngineSkew(client) {
+  try { return _skewByServer.get(serverKeyForClient(client)) || null; } catch (_e) { return null; }
+}
+
+/** Test-only: forget every standing record. */
+function _resetSkewRecords() {
+  _skewByServer.clear();
+}
+
+module.exports = {
+  serverKeyForClient,
+  currentEngineSkew,
+  skewForKey,
+  rememberSkew,
+  forgetSkew,
+  UNKNOWN_SERVER_KEY,
+  MAX_SKEW_SERVERS,
+  _resetSkewRecords,
+};

package/src/utils/engine-skew.js

@@ -0,0 +1,300 @@
+/**
+ * @module utils/engine-skew
+ * Runtime detection of an opencode ENGINE version skew: server vs installed.
+ *
+ * The version the server we are actually talking to reports, against the engine
+ * sitting in THIS install's node_modules.
+ *
+ * WHY (#133, piece 3). The outage was one engine version (npx cache, 1.17.3)
+ * serving every MCP session while another (global install, 1.18.15) served the
+ * CLI, both writing one shared SQLite file — so every MCP prompt died before a
+ * model was ever called. `amicus doctor` printed ZERO errors throughout: its
+ * skew check (`doctor-engine-check.js`) compares npx-cache copies against the
+ * GLOBAL install and says nothing about the copy the running process actually
+ * loaded. MEASURED here 2026-08-25: that baseline sees global 1.18.15 vs npx
+ * 1.18.15 and reports clean, while the running checkout loads engine **1.2.20**
+ * — a live instance of #133's own class, invisible to the check built for it.
+ * Hence a RUNTIME comparison with no global baseline.
+ *
+ * SCOPE, stated honestly (W10 review F2): this handshake fires when the server
+ * answering this process was started by a DIFFERENT install (shared or external
+ * server, PATH-hoisted binary). In #133's literal recorded topology the npx copy
+ * spawned its OWN engine — server and installed versions were EQUAL on that
+ * side, the skew being against a global install neither loads — so THIS check
+ * stays silent there; the engine-log excerpt (piece 2) names that case instead,
+ * by quoting the SQLiteError itself.
+ *
+ * MEASURED, not reasoned from types (2026-08-25, against a locally spawned
+ * engine): `client.session.create({})` returns `data = {directory,id,projectID,
+ * slug,time,title,version}` and `data.version` was `"1.2.20"` — byte-identical
+ * to this checkout's `node_modules/opencode-ai/package.json`. `Session.version`
+ * IS the engine's own version, so the two sides are directly comparable.
+ *
+ * SHAPE. `src/opencode-client.js :: createSession` pushes the observed version
+ * here together with its client (it discarded both before); this module owns
+ * the comparison, the announcement and the remedy text, while
+ * `./engine-skew-records.js` owns the server identity and the standing record —
+ * one per SERVER, refreshed on every create — that `src/headless.js` appends to
+ * a leg's death report. That keeps the client's return type a plain session-id
+ * string (measured: all three production callers — `headless.js`,
+ * `mcp-server.js`, `sidecar/interactive.js` — assign it straight to one).
+ *
+ * EVERYTHING HERE IS BEST-EFFORT: a diagnosis must never become the failure it
+ * reports on. Every path returns null/undefined rather than throwing.
+ */
+
+'use strict';
+
+const path = require('path');
+const {
+  serverKeyForClient, currentEngineSkew, skewForKey, rememberSkew, forgetSkew,
+  UNKNOWN_SERVER_KEY, MAX_SKEW_SERVERS, _resetSkewRecords,
+} = require('./engine-skew-records');
+// The SAME sanitizer the log excerpt uses (round-3 reviews B1+C2). A server's
+// reported version is third-party text on its way to a terminal and to MCP,
+// exactly like an engine log line; one implementation, one dialect.
+const { collapseExcerpt } = require('./text-sanitize');
+
+/** How much of a server-reported version is ever rendered. Real versions are
+ *  semver-shaped; past this it is not a version, it is a payload. */
+const MAX_VERSION_CHARS = 32;
+
+/** One version string, safe to paste into a one-line notice or an error message:
+ *  no ANSI, no control bytes, no bidi reordering, no newline that could forge a
+ *  second `[amicus] ` line, never longer than the cap. */
+const safeVersion = (value) => collapseExcerpt(value, MAX_VERSION_CHARS);
+
+/** Memo for the installed-version disk read (see installedEngineVersion). */
+let _installedRead = false;
+let _installedCache;
+/** Whether the "cannot name this server" notice has already been printed. */
+let _identityNoticeSent = false;
+
+/** Test-only: clear the standing records, the read memo and the notice latch. */
+function _resetEngineSkew() {
+  _resetSkewRecords();
+  _installedRead = false;
+  _installedCache = undefined;
+  _identityNoticeSent = false;
+}
+
+/**
+ * Read the engine version out of the RUNNING install's node_modules.
+ *
+ * Roots come from `path-setup.js :: opencodeRoots()` with no argument — the same
+ * resolver `engine-ensure`/`hasOpencodeBinary` use to decide whether THIS
+ * process's engine binary exists, so "the engine we would run" and "the engine
+ * we version-check" are the same by construction.
+ *
+ * Reading `opencode-ai`'s own package.json (rather than anything next to the
+ * binary) mirrors `engine-install-scan.js :: defaultReadEngineVersion`, whose
+ * docblock records why: a faithful proxy, because opencode-ai exact-pins all 12
+ * platform sub-packages and the binary's own directory has no package.json on
+ * POSIX at all.
+ * @param {object} [deps]
+ * @param {object} [deps.fs] - fs module seam (readFileSync)
+ * @param {string[]} [deps.roots] - node_modules roots seam
+ * @returns {string|undefined} undefined on every miss path
+ */
+function defaultReadInstalledEngineVersion(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const roots = deps.roots || require('./path-setup').opencodeRoots();
+  for (const root of roots) {
+    try {
+      const raw = fs.readFileSync(path.join(root, 'opencode-ai', 'package.json'), 'utf-8');
+      const v = JSON.parse(raw).version;
+      if (v) { return String(v); }
+    } catch (_e) { /* try the next root */ }
+  }
+  return undefined;
+}
+
+/**
+ * The installed engine version, read at most ONCE per process.
+ *
+ * node_modules cannot change under a live process, and this is consulted on
+ * every session create (every fanout leg, every council seat) — a per-session
+ * stat of two roots would be pure waste. The memo is cleared only by
+ * `_resetEngineSkew()`, so a test that swaps seams must reset between cases;
+ * production has exactly one call path and never does.
+ * @param {object} [deps] - defaultReadInstalledEngineVersion seams, plus:
+ * @param {() => (string|undefined)} [deps.readInstalledVersion] - reader seam
+ * @returns {string|undefined}
+ */
+function installedEngineVersion(deps = {}) {
+  if (!_installedRead) {
+    _installedRead = true;
+    try {
+      _installedCache = deps.readInstalledVersion
+        ? deps.readInstalledVersion()
+        : defaultReadInstalledEngineVersion(deps);
+    } catch (_e) {
+      _installedCache = undefined;
+    }
+  }
+  return _installedCache;
+}
+
+/**
+ * The default sink for BOTH one-time notices here — skew, and identity loss.
+ * Written to stderr, NOT through `logger.warn`.
+ *
+ * MEASURED: `utils/logger.js :: getCurrentLevel` defaults `LOG_LEVEL` to
+ * `'error'`, so `logger.warn` is filtered out on every default install — a
+ * self-diagnosis routed there would be silent exactly where it matters. stderr
+ * with an `[amicus] ` prefix is the house pattern for notices the user must see
+ * (`mcp-server.js`'s update notice, `engine-ensure.js`'s self-heal) and is safe
+ * under MCP stdio, where stdout carries the protocol.
+ * @param {string} msg
+ */
+function defaultNotify(msg) {
+  try { process.stderr.write(`[amicus] ${msg}\n`); } catch (_e) { /* EPIPE at shutdown */ }
+}
+
+/**
+ * The announcement text. Names both versions (the whole point — #133 cost 30
+ * minutes because nothing printed the two numbers side by side) and then the
+ * action that ends it: make the two copies the same version.
+ *
+ * It deliberately does NOT say "see amicus doctor" (W10 round-1 review B1).
+ * Doctor's skew check is structurally blind to THIS skew — the module docblock
+ * above records the measurement — so pointing there would spend the user's next
+ * five minutes on a check that reports clean by construction.
+ *
+ * BOTH VERSIONS ARE SANITIZED (round-3 reviews B1+C2). `server` is whatever the
+ * server chose to say, and it landed verbatim on stderr: an escape sequence, a
+ * bidi override or a newline could recolour the terminal, reverse the sentence,
+ * or forge a second `[amicus] ` line under our prefix. `installed` goes through
+ * it too — also file content, and one rule beats two.
+ * @param {{server: string, installed: string}} skew
+ * @returns {string} one line
+ */
+function formatSkewWarning({ server, installed }) {
+  return `engine version skew: server ${safeVersion(server)} ≠ installed ${safeVersion(installed)} — `
+    + 'MCP and CLI may be running different engines; update whichever copy is behind '
+    + '(`npm i -g amicus`, or re-run the failing surface\'s installer). '
+    + '`amicus doctor` cannot see this skew: its baseline compares npx against global, '
+    + 'not the server actually answering.';
+}
+
+/**
+ * The clause appended to an enriched failure message. EMPTY when there is no
+ * standing skew, so every message that would not have carried it is
+ * byte-identical to what it was before this module existed.
+ *
+ * Sanitized on the same terms as the notice, and for a sharper reason: this
+ * clause rides out through MCP into whatever renders a leg's death report.
+ * @param {{server: string, installed: string}|null} [skew]
+ * @returns {string}
+ */
+function formatSkewSuffix(skew) {
+  if (!skew) { return ''; }
+  return ` (engine skew: server ${safeVersion(skew.server)} ≠ installed ${safeVersion(skew.installed)})`;
+}
+
+/**
+ * Say so, ONCE, when a client was handed to us and we could not name its server.
+ *
+ * Round-3 review C1(a). `serverKeyForClient` reads `client._client.getConfig()`,
+ * a PRIVATE SDK handle and the only route to the base URL. If a future SDK
+ * renames it, that read returns UNKNOWN_SERVER_KEY, every server in the process
+ * silently shares one degraded bucket — where a record can be attributed to the
+ * wrong server AND cleared by the wrong one — and nothing says so. That is the
+ * correct-but-silent degrade the product principle rates as bad as a crash.
+ *
+ * A CLIENT WAS PROVIDED is the whole trigger: the caller had a server to name
+ * and we could not name it. No client at all is not a shape change — it is a
+ * caller that never claimed to have one — so `currentEngineSkew`, whose callers
+ * legitimately ask "any skew here?" with nothing in hand, does not raise it.
+ * Once per process: this runs on every create, and a wave of dead legs must not
+ * each print it. (b) is the other half — a CI shape pin over a REAL SDK client,
+ * in tests/utils/engine-skew.test.js.
+ */
+function noteIdentityLoss(key, deps) {
+  if (_identityNoticeSent || !deps.client || key !== UNKNOWN_SERVER_KEY) { return; }
+  _identityNoticeSent = true;
+  const notify = deps.notify || defaultNotify;
+  try {
+    notify('server identity unavailable — skew attribution is process-wide; '
+      + 'SDK shape may have changed');
+  } catch (_e) { /* best-effort, exactly like the skew notice */ }
+}
+
+/**
+ * Record a server-reported session version as the LAST comparison for that
+ * server, announcing a mismatch the first time that server shows it.
+ *
+ * REFRESHED ON EVERY CREATE, not written once (W10 round-1 review A3+B3): a
+ * matching version RETRACTS a standing skew for that server, so a mid-run fix
+ * stops being reported; a different mismatch REPLACES it, the newer observation
+ * being the true one. Records are per server identity, so a skewed server's
+ * clause never rides out on an unrelated server's death report.
+ *
+ * A version-less create CLEARS that server's record (round-2 review B4).
+ * Absence of the field means an older SDK or engine is answering — not evidence
+ * of SKEW, but evidence that what the record describes is no longer what is on
+ * that URL. Unknown beats stale: it announces nothing and returns null, exactly
+ * like a match. An unreadable INSTALLED version is different — with one side of
+ * the comparison missing there is no observation at all, so it touches nothing.
+ *
+ * BOTH CLEARS APPLY UNDER `UNKNOWN_SERVER_KEY` TOO, deliberately (round-2
+ * review B3, which proposed the opposite). Under that shared bucket a clear can
+ * be wrong — server B's healthy create can delete server A's real skew — so the
+ * rule was re-derived against "never attribute a skew to a server that does not
+ * have it" and MEASURED over A skewed, B healthy, A fixed, A regresses:
+ *   retract       → B dies clean, A-after-fix dies clean, A's regression is
+ *                   re-recorded on its very next create
+ *   never retract → B wears A's skew, A wears its own stale skew after the fix,
+ *                   and NOTHING can ever clear either
+ * Retraction's error is self-healing (this runs on EVERY create); the other is a
+ * wrong attribution no later observation can undo. The bucket stays genuinely
+ * degraded — see `noteIdentityLoss` above, which now says so out loud.
+ *
+ * The notice repeats only when the record CHANGES: the skewed leg of a 20-seat
+ * wave must not print 20 identical lines.
+ * @param {string|undefined} serverVersion - `Session.version` from the create response
+ * @param {object} [deps] - installedEngineVersion seams, plus:
+ * @param {object} [deps.client] - the SDK client, for the server identity
+ * @param {(msg: string) => void} [deps.notify] - notice sink seam
+ * @returns {{server: string, installed: string}|null} that server's record
+ */
+function noteSessionVersion(serverVersion, deps = {}) {
+  const key = serverKeyForClient(deps.client);
+  noteIdentityLoss(key, deps);
+  if (typeof serverVersion !== 'string' || !serverVersion) {
+    forgetSkew(key); // an older engine answers here NOW — unknown beats stale
+    return null;
+  }
+  const installed = installedEngineVersion(deps);
+  if (typeof installed !== 'string' || !installed) { return null; }
+  if (serverVersion === installed) {
+    forgetSkew(key); // the two agree NOW — any older mismatch is stale
+    return null;
+  }
+
+  const prior = skewForKey(key);
+  const skew = { server: serverVersion, installed };
+  // Record BEFORE announcing: a notifier that throws must not cost us the
+  // enrichment clause too.
+  rememberSkew(key, skew);
+  if (prior && prior.server === skew.server && prior.installed === skew.installed) { return skew; }
+  const notify = deps.notify || defaultNotify;
+  try { notify(formatSkewWarning(skew)); } catch (_e) { /* best-effort */ }
+  return skew;
+}
+
+// Ordered so the FUNCTIONS this module is used for come first: the generated
+// `Key Exports` cell in CLAUDE.md keeps five names and renders each as `name()`,
+// so a constant in that window reads as a function it is not (round-2 B8).
+module.exports = {
+  noteSessionVersion,
+  currentEngineSkew,
+  serverKeyForClient,
+  formatSkewWarning,
+  formatSkewSuffix,
+  installedEngineVersion,
+  defaultReadInstalledEngineVersion,
+  UNKNOWN_SERVER_KEY,
+  MAX_SKEW_SERVERS,
+  _resetEngineSkew,
+};

package/src/utils/gateway-router.js

@@ -10,6 +10,7 @@
 const { resolved, routeError, selectionRequired, parseDescriptor } = require('./model-descriptor');
 const { classifyModel } = require('./model-classification');
 const { isDirectProvider } = require('./provider-registry');
+const HINTS = require('./remediation-hints');
 
 /** Build the executable id for a gateway. */
 function executableFor(gateway, vendor, model) {
@@ -86,8 +87,15 @@ function catalogGate({ id, gateway, req }) {
   if (req.allowSelection) {
     return { ok: false, result: selectionRequired({ requested: req.descriptor.raw, suggestions: [] }) };
   }
-  return { ok: false, result: routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
-    preferredGateway: gateway, suggestions: [] }) };
+  const e = routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
+    preferredGateway: gateway, suggestions: [] });
+  // B2 (V16): a bare id invalid on direct whose openrouter/ twin IS catalog-
+  // confirmed is exactly doctor's repairable fabricated-alias class — point at
+  // the repair. Hint only; reason and shape unchanged.
+  if (gateway === 'direct' && classifyModel(`openrouter/${id}`, 'openrouter', req.catalogInfo) === 'valid') {
+    e.hint = HINTS.repairFabricatedAlias;
+  }
+  return { ok: false, result: e };
 }
 
 /**

package/src/utils/model-catalog.js

@@ -152,4 +152,4 @@ async function getCatalogInfo(opts = {}) {
   };
 }
 
-module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION };
+module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION, DEFAULT_MAX_AGE_MS };

package/src/utils/result-schema.js

@@ -8,6 +8,8 @@
  * split out so ./abort-result.js can depend on it without a circular require).
  */
 const { SCHEMA_VERSION } = require('./result-schema-version');
+// v4.9 W13 Task A (PR #207 round 3, B3): the shared ttftMs honesty predicate.
+const { isMeasuredTtft } = require('./ttft');
 
 /** Leg/run statuses that count as terminal for wave aggregation. */
 const TERMINAL_STATUSES = ['complete', 'error', 'timeout', 'aborted', 'crashed', 'idle-timeout'];
@@ -70,6 +72,14 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     durationMs,
     sessionDir,
     opencodeSessionId: metadata.opencodeSessionId || null,
+    // v4.9 W13 Task A (probe only, R12): time-to-first-token, sourced straight
+    // off `metadata` like `opencodeSessionId` above. ADDITIVE and emit-when-set
+    // (the pack/tag spread form below, not the `|| null` coercion above): an
+    // absent ttft means "no substantive tick was observed", which is neither
+    // zero nor null, so it must not be coerced into either. PR #207 round 3
+    // (B3): emit-when-VALID via the shared predicate — `metadata` is read off
+    // disk, so NaN/±Infinity/negatives/fractions all reach here. See ./ttft.js.
+    ...(isMeasuredTtft(metadata.ttftMs) ? { ttftMs: metadata.ttftMs } : {}),
     usage: usage !== null ? usage : (metadata.usage || null),
     ...(metadata.pack ? { pack: metadata.pack } : {}),
     ...(metadata.tag ? { tag: metadata.tag } : {}),

package/src/utils/text-sanitize.js

@@ -0,0 +1,81 @@
+/**
+ * @module utils/text-sanitize
+ * One third-party string, safe to render: no escapes, no bidi, one short line.
+ *
+ * EXTRACTED from src/utils/engine-log-parse.js (v4.9 W10 round 3). It was built
+ * there for the engine-log excerpt (round-2 review B2), but reviews B1+C2 put a
+ * SECOND caller on it — `utils/engine-skew.js` runs server-reported version
+ * strings through the same pass before they reach the stderr notice and the
+ * death-report clause. Leaving it in the parse module meant the skew detector
+ * had to depend on the log parser to sanitize a version number, which is a
+ * dependency edge that says nothing true about either module. Here, neither
+ * caller owns it and both just use it.
+ *
+ * `engine-log-parse.js` RE-EXPORTS both names, so every existing import path
+ * stays valid and the extraction pins can assert these are the SAME function
+ * objects rather than a second copy — the same shape as the round-2 splits.
+ *
+ * THE RULE, in one line: this is the ONLY sanitizer. A second implementation
+ * would be a second set of holes, and the holes are the point — every finding
+ * that has landed here (ANSI in round 2, bidi in round 3) was a class the
+ * previous pass could not see.
+ *
+ * PURE: no I/O, no throwing paths, no state.
+ */
+
+'use strict';
+
+/** One short line: long enough for a real engine error, short enough to ride
+ *  inside an error string that already carries the backstop's own sentence. */
+const MAX_EXCERPT_CHARS = 200;
+
+/** An ANSI escape sequence: CSI (`ESC [ … final`), OSC (`ESC ] … BEL/ST`), or a
+ *  bare two-character escape. */
+// eslint-disable-next-line no-control-regex
+const ANSI_SEQUENCE = /\u001b(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|[@-_])/g;
+/** C0 and C1 control characters, DEL included. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR = /[\u0000-\u001f\u007f-\u009f]/g;
+/**
+ * Unicode BIDI controls: the embedding/override set, the isolates, the marks.
+ *
+ * Round-3 review A2. PRINTABLE-range code points, so the C0/C1 sweep above never
+ * saw them — and each reorders the characters that follow, letting a third
+ * party's error string rewrite the sentence it is quoted into (a RIGHT-TO-LEFT
+ * OVERRIDE renders the rest of the line backwards). Formatting, so DROPPED.
+ */
+const BIDI_CONTROL = /[\u202a-\u202e\u2066-\u2069\u200e\u200f\u061c]/g;
+
+/**
+ * One line, no control characters, no bidi controls, at most `maxChars`.
+ *
+ * SANITIZED, not just collapsed (round-2 review B2). This is quoted verbatim
+ * from a third party's text into output that reaches terminals and MCP
+ * surfaces; engine lines can embed provider output, colour codes and all.
+ * Escape sequences and bidi controls are DROPPED (formatting: removing them
+ * keeps `<esc>[31mred<esc>[0m` as `red`, not as spaced-out text); every
+ * remaining control byte becomes a space, which the collapse below tidies.
+ *
+ * THE CAP IS A PARAMETER because this is the house sanitizer for any
+ * third-party string we render, not only log excerpts: `utils/engine-skew.js`
+ * runs SERVER-SUPPLIED version strings through it at a shorter cap before they
+ * enter the stderr notice and the death-report clause (round-3 reviews B1+C2).
+ * One sanitizer, one dialect — a second implementation is a second set of holes.
+ * @param {*} text
+ * @param {number} [maxChars]
+ * @returns {string}
+ */
+function collapseExcerpt(text, maxChars = MAX_EXCERPT_CHARS) {
+  const oneLine = String(text === undefined || text === null ? '' : text)
+    .replace(ANSI_SEQUENCE, '')
+    .replace(BIDI_CONTROL, '')
+    .replace(CONTROL_CHAR, ' ')
+    .replace(/\s+/g, ' ').trim();
+  if (oneLine.length <= maxChars) { return oneLine; }
+  return `${oneLine.slice(0, maxChars - 1)}…`;
+}
+
+module.exports = {
+  collapseExcerpt,
+  MAX_EXCERPT_CHARS,
+};

package/src/utils/ttft.js

@@ -0,0 +1,57 @@
+/**
+ * @module utils/ttft
+ * The one honesty predicate for the time-to-first-token probe (v4.9 W13).
+ *
+ * ⚠️ The JSDoc leads this file, ahead of `'use strict'`, matching
+ * `utils/text-sanitize.js` / `utils/engine-skew.js` / `utils/alias-shadow.js`:
+ * `scripts/generate-docs.js` only reads a block comment that starts at byte
+ * zero, so a `// path` line above it would leave this module's CLAUDE.md row
+ * blank the way `utils/result-schema.js`'s already is.
+ *
+ * `ttftMs` is produced once — in `src/headless.js`'s poll loop, as a
+ * `Date.now()` delta — and then passes four EMIT GATES on its way to a
+ * document: `headless.js`'s three returns, `sidecar/fanout-leg.js`'s leg patch,
+ * `utils/result-schema.js :: buildRunResult`, and
+ * `council/run-stats-entry.js :: buildRunStatsEntry`. Every gate used to spell
+ * its own `typeof x === 'number'` test, which is four chances to disagree and
+ * four ways to publish a value both schemas forbid.
+ *
+ * ⚠️ `typeof` is not the schema's contract. `schemas/run.schema.json` and
+ * `schemas/council-tally.schema.json` both declare this field
+ * `integer, minimum 0`, and `typeof` admits four families that violate it:
+ *   · NaN — `JSON.stringify` writes it as `null`, so the artifact breaks its own
+ *     schema while LOOKING like the honest absence the emit-when-set rule means.
+ *   · ±Infinity — not hypothetical from an artifact: `JSON.parse('1e999')` is
+ *     `Infinity` (MEASURED), and it also serializes to `null`.
+ *   · Negative — the probe is a wall-clock delta, so a backward jump (NTP
+ *     correction, a VM resuming from suspend, a manual clock set) between the
+ *     clock origin and the first substantive poll measures below zero.
+ *   · Fractional — a hand-edited leg document.
+ *
+ * ⚠️ DROP, DO NOT CLAMP. A skewed −5 s reading clamped to `0` would publish
+ * "first token inside the first poll" — the most consequential value in the
+ * distribution the C2 derivation will read — for a leg that measured nothing of
+ * the kind. Emit-when-VALID is the same discipline as emit-when-set: absence
+ * already means "no honest measurement was made", and a dishonest number is
+ * exactly that. `0` itself stays a real, emittable measurement.
+ *
+ * ⚠️ Three of the four gates import this. The fourth,
+ * `council/run-stats-entry.js`, is pinned REQUIRE-FREE (P3,
+ * tests/council/run-stats-entry.test.js — the pin fires on the character
+ * sequence anywhere in that file, comments included) so require-free consumers
+ * can import it, so it spells the same expression by hand. The structural pins
+ * that keep the hand-spelled copy in step live in that same test file.
+ */
+
+'use strict';
+
+/**
+ * Is this a real time-to-first-token measurement, fit to ride a document?
+ * @param {*} value
+ * @returns {boolean} true only for a non-negative integer millisecond count.
+ */
+function isMeasuredTtft(value) {
+  return Number.isInteger(value) && value >= 0;
+}
+
+module.exports = { isMeasuredTtft };