@smartmemory/compose 0.4.1 → 0.5.0

package/lib/receipts-gate.js

@@ -0,0 +1,268 @@
+/**
+ * receipts-gate.js — a claim written as a fact must carry its receipt.
+ *
+ * Runs on every push (pre-push hook, including docs-only pushes) over the ADDED
+ * lines of the pushed range — never the corpus. Scope: every `*.md` at any depth
+ * (git pathspecs match `*` across `/`; rules files are in, deliberately) plus
+ * docs/ JSON files, and every commit message in the range. That is what makes it a gate
+ * that fires at the moment of the mistake rather than a memory nobody reads at
+ * that moment, and what lets it ship with no baseline to reconcile.
+ *
+ * It is narrow on purpose. Three claim shapes, each one that did measurable
+ * damage in this repo (2026-09-07, five wrong facts in one sweep, one habit):
+ *
+ *   test-coverage  a CHECKED acceptance box or a commit line saying a test pins
+ *                  something, with no test path. FOH-7 had three of these; the
+ *                  boxes were ticked off an audit that sampled 2 of 17 citations.
+ *                  Receipt: a `test/...` path.
+ *   flake-label    `flake`/`flaky` written as a state. build-stream-smoke was
+ *                  labelled that way in three places over two months and was a
+ *                  live product defect the whole time (12a357a). Receipt: a
+ *                  measurement (`14/450`, `0 of 40`, `15 runs`) or a resolution
+ *                  pinned to a sha.
+ *   suite-green    a commit message claiming the suite passes with no counts.
+ *                  The prior session reported green off a wrapper's exit code
+ *                  and put numbers measured on an older tree into a commit.
+ *                  Receipt: `N/M` anywhere in the message.
+ *
+ * Talking ABOUT a phrase is not asserting it: inline code spans and fenced
+ * blocks are stripped before matching, so `pinned by test` in backticks passes.
+ * An UNCHECKED box may say "(pinned by test)" — that is a design intent, and the
+ * gate fires when the box is ticked, which is when the claim becomes a fact.
+ *
+ * Extending it: add a shape here with the incident that justifies it, and a
+ * fixture in test/receipts-gate.test.js that MUST fire and one that MUST pass.
+ * A shape with no incident behind it is a philosophy checker, not a gate.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const CHECKED_BOX = /^\s*[-*]\s+\[[xX]\]/;
+const TEST_CLAIM = /\b(pinned|covered|guarded|locked|protected)\s+by\s+(a\s+|the\s+|its\s+)?tests?\b|\bhas\s+(a\s+|its\s+own\s+)?tests?\b|\btested\s+by\b/i;
+const TEST_RECEIPT = /\btests?\/[\w./@-]+|\.test\.(m?js|jsx|ts)\b/;
+
+const FLAKE_CLAIM = /\bflak(e|y|es|ed|ing|iness)\b/i;
+const MEASUREMENT = /\b\d+\s*(\/|of|out\s+of|in)\s*\d+\b|\b\d+\s*(\w+\s+)?(runs?|x|times|iterations)\b/i;
+const HEADING = /^\s*#{1,6}\s/;
+// A flake claim is receipted by a measurement, or by being CLOSED the way this
+// repo closes claims at their origin: an uppercase status word next to a sha
+// or a date. Lowercase "fixed"/"closed" do NOT count — they are everywhere in
+// prose and a neighbouring thread's "fixed @sha" was found vouching for an
+// unrelated open flake claim. DISOWNED is for the line itself saying the flake
+// was never one.
+const CLOSED = /\b(RESOLVED|KILLED|SUPERSEDED|FIXED)\b/;
+const CLOSER = /\b[0-9a-f]{7,40}\b|\b20\d\d-\d\d-\d\d\b/;
+const DISOWNED = /\b(not\s+a\s+flake|never\s+a\s+flake|was\s+real|defect|root\s+cause)\b/i;
+
+const GREEN_CLAIM = /\b(suite|tests?|everything|all)\s+(is\s+|are\s+|was\s+|were\s+|went\s+)?(green|pass(es|ed|ing)?)\b|\ball\s+green\b|\bgreen\s+suite\b/i;
+const COUNTS = /\b\d+\s*\/\s*\d+\b/;
+
+/** Remove inline code spans — a quoted phrase is mentioned, not asserted. */
+function stripCodeSpans(line) {
+  return line.replace(/`[^`]*`/g, '');
+}
+
+/** How far "beside it" reaches: a wrapped checkbox or sentence, or a
+ *  RESOLVED annotation indented under the claim. Not a paragraph. */
+export const RECEIPT_WINDOW = 3;
+
+/**
+ * Classify one ADDED line from a doc. The CLAIM must be on the line; the
+ * RECEIPT may be anywhere in `context` (the line plus its neighbours within
+ * RECEIPT_WINDOW added lines of the same file — `scanRange` builds it). With
+ * no context given, the line is its own context.
+ *
+ * Headings are exempt from `flake-label`: a heading titles the body that
+ * follows, and that body is scanned line by line on its own.
+ *
+ * @param {string} rawLine
+ * @param {string} [context]
+ * @returns {{shape: string, needs: string} | null}
+ */
+export function classifyDocLine(rawLine, context = rawLine) {
+  // The CLAIM is read with code spans stripped (quoting a phrase is mentioning
+  // it). The RECEIPT is read raw: a path or a count in backticks is still a
+  // receipt — paths are conventionally written that way.
+  const line = stripCodeSpans(rawLine);
+  const near = context;
+  if (CHECKED_BOX.test(line) && TEST_CLAIM.test(line) && !TEST_RECEIPT.test(near)) {
+    return { shape: 'test-coverage', needs: `the test path (test/<file>.test.js[:line]) within ${RECEIPT_WINDOW} lines` };
+  }
+  if (!HEADING.test(line) && FLAKE_CLAIM.test(line) && !DISOWNED.test(line)
+      && !MEASUREMENT.test(near) && !(CLOSED.test(near) && CLOSER.test(near))) {
+    return { shape: 'flake-label', needs: `a measurement (e.g. "3/40 under load"), or RESOLVED/KILLED with a sha or date, within ${RECEIPT_WINDOW} lines` };
+  }
+  return null;
+}
+
+/**
+ * Classify one commit message (whole body — receipts for a suite claim are
+ * usually on their own line). Returns violations.
+ * @param {string} message
+ * @returns {Array<{shape: string, needs: string, excerpt: string}>}
+ */
+export function classifyCommitMessage(message) {
+  const out = [];
+  const stripped = stripFences(message).split('\n').map(stripCodeSpans);
+  const whole = stripFences(message); // receipts are read raw, claims stripped
+  for (const line of stripped) {
+    if (TEST_CLAIM.test(line) && !TEST_RECEIPT.test(line) && !TEST_RECEIPT.test(whole)) {
+      out.push({ shape: 'test-coverage', needs: 'a test path somewhere in the message', excerpt: line.trim() });
+      break;
+    }
+  }
+  for (const line of stripped) {
+    if (GREEN_CLAIM.test(line) && !COUNTS.test(whole)) {
+      out.push({ shape: 'suite-green', needs: 'pass/total counts (e.g. "node 6412/6412") somewhere in the message', excerpt: line.trim() });
+      break;
+    }
+  }
+  for (const line of stripped) {
+    // A commit message is one unit: the disowning phrase, like every other
+    // receipt here, may sit anywhere in it.
+    const v = FLAKE_CLAIM.test(line) && !DISOWNED.test(whole)
+      && !MEASUREMENT.test(whole) && !(CLOSED.test(whole) && CLOSER.test(whole))
+      ? { shape: 'flake-label', needs: 'a measurement, or RESOLVED/KILLED with a sha or date, somewhere in the message', excerpt: line.trim() }
+      : null;
+    if (v) { out.push(v); break; }
+  }
+  return out;
+}
+
+/** Drop fenced code blocks (``` ... ```). */
+function stripFences(text) {
+  return text.replace(/```[\s\S]*?```/g, '');
+}
+
+/**
+ * Added doc lines in `base..head`, as {file, line, text}. Fenced blocks are
+ * skipped by tracking fence state per file — the diff is unified=0 so context
+ * is absent, which means a fence opened in an UNCHANGED line is invisible; a
+ * miss there is a false positive the author fixes by quoting the phrase inline.
+ */
+export function addedDocLines(base, head, { cwd = process.cwd(), git = runGit } = {}) {
+  const diff = git(['diff', '--unified=0', '--no-color', `${base}..${head}`, '--',
+    'docs/**/*.md', 'docs/**/*.json', '*.md'], cwd);
+  const out = [];
+  let file = null;
+  let lineNo = 0;
+  let inFence = false;
+  for (const raw of diff.split('\n')) {
+    if (raw.startsWith('+++ ')) { file = raw.slice(4).replace(/^b\//, ''); inFence = false; continue; }
+    if (raw.startsWith('--- ') || raw.startsWith('diff ') || raw.startsWith('index ')) continue;
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+    if (hunk) { lineNo = Number(hunk[1]); continue; }
+    if (raw.startsWith('+')) {
+      const text = raw.slice(1);
+      if (/^\s*```/.test(text)) { inFence = !inFence; lineNo++; continue; }
+      if (!inFence && file && file !== '/dev/null') out.push({ file, line: lineNo, text });
+      lineNo++;
+    }
+  }
+  return out;
+}
+
+/** Commit messages in `base..head`, oldest first, as {sha, message}. */
+export function commitMessages(base, head, { cwd = process.cwd(), git = runGit } = {}) {
+  const sep = '\u001e'; // record separator — commit bodies contain every printable char
+  const raw = git(['log', '--reverse', `--format=%H${sep}%B${sep}`, `${base}..${head}`], cwd);
+  const out = [];
+  const parts = raw.split(sep);
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const sha = parts[i].trim();
+    if (!sha) continue;
+    out.push({ sha, message: parts[i + 1] });
+  }
+  return out;
+}
+
+/**
+ * Scan a range. Returns every violation with its location.
+ * @returns {Array<{where: string, shape: string, needs: string, excerpt: string}>}
+ */
+export function scanRange(base, head, opts = {}) {
+  const found = [];
+  const added = addedDocLines(base, head, opts);
+  const { cwd = process.cwd(), git = runGit } = opts;
+  const filesAtHead = new Map();
+  const fileAtHead = (file) => {
+    if (!filesAtHead.has(file)) {
+      let body = '';
+      try { body = git(['show', `${head}:${file}`], cwd); } catch { body = ''; }
+      filesAtHead.set(file, body);
+    }
+    return filesAtHead.get(file);
+  };
+  for (let i = 0; i < added.length; i++) {
+    const { file, line, text } = added[i];
+    const context = CHECKED_BOX.test(text)
+      ? listItemOf(fileAtHead(file), line)
+      : neighboursOf(added, i);
+    const v = classifyDocLine(text, context);
+    if (v) found.push({ where: `${file}:${line}`, ...v, excerpt: text.trim() });
+  }
+  for (const { sha, message } of commitMessages(base, head, opts)) {
+    for (const v of classifyCommitMessage(message)) {
+      found.push({ where: `commit ${sha.slice(0, 7)}`, ...v });
+    }
+  }
+  return found;
+}
+
+/**
+ * Prose context: same file, within RECEIPT_WINDOW by LINE NUMBER — two hunks
+ * far apart in one file are not "beside" each other just because the diff
+ * lists them consecutively.
+ */
+function neighboursOf(added, i) {
+  const { file, line } = added[i];
+  return added
+    .slice(Math.max(0, i - RECEIPT_WINDOW), i + RECEIPT_WINDOW + 1)
+    .filter((n) => n.file === file && Math.abs(n.line - line) <= RECEIPT_WINDOW)
+    .map((n) => n.text)
+    .join('\n');
+}
+
+/**
+ * Checklist context: the item ITSELF — its line plus the indented continuation
+ * lines under it, up to the next item, heading, or blank line. Checklists are
+ * dense and every item is its own claim, so a symmetric window let a
+ * neighbouring item's test path vouch for a box that had none (that is exactly
+ * how the FOH-7 audit commit slipped through a first draft of this gate).
+ *
+ * Read from the FILE AT `head`, not the diff: a box flipped [ ]→[x] with its
+ * receipt already on an unchanged continuation line is fine, and a zero-context
+ * diff cannot see that line.
+ */
+function listItemOf(fileAtHead, lineNo) {
+  const lines = fileAtHead.split('\n');
+  const parts = [lines[lineNo - 1] ?? ''];
+  for (let j = lineNo; j < lines.length; j++) {
+    const t = lines[j];
+    if (!/^\s+\S/.test(t) || /^\s*[-*]\s+\[/.test(t) || HEADING.test(t)) break;
+    parts.push(t);
+  }
+  return parts.join('\n');
+}
+
+/** Render violations for the hook. */
+export function formatViolations(found) {
+  const lines = [`receipts-gate: ${found.length} claim(s) written as fact with no receipt beside them:`, ''];
+  for (const v of found) {
+    lines.push(`  ${v.where}  [${v.shape}]`);
+    lines.push(`    ${truncate(v.excerpt, 140)}`);
+    lines.push(`    needs: ${v.needs}`);
+    lines.push('');
+  }
+  lines.push('A fact without a measurement is a guess with good posture. Add the receipt, or');
+  lines.push('quote the phrase in backticks if you are talking about it rather than asserting it.');
+  return lines.join('\n');
+}
+
+function truncate(s, n) {
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+function runGit(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}

package/lib/result-normalizer.js

@@ -14,6 +14,7 @@ import { resolveAgentConfig } from './agent-string.js';
 import { normalizeReviewResult } from './review-normalize.js';
 import { KNOWN_VERSIONS } from './build-stream-schema.js';
 import { runLocalClaudeAgent } from './local-claude-connector.js';
+import { confirmCancellation } from './build-cancel.js';
 
 // ---------------------------------------------------------------------------
 // Error classes
@@ -433,6 +434,15 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   const abortController = new AbortController();
   const stopRun = () => abortController.abort();
 
+  // COMP-BUILD-CANCEL S03-2 (D-F, C13): the build-level cancel handle. ONE hook covers
+  // BOTH dispatch branches, because both hang off this single controller — the local SDK
+  // agent (via opts.abortController) and the two MCP dispatches (via abortController
+  // .signal). `executionOptions` is deliberately untouched: it is spread into the MCP
+  // wire request, where an AbortSignal does not belong.
+  const buildSignal = opts.buildSignal ?? null;
+  if (buildSignal?.aborted) stopRun();
+  else buildSignal?.addEventListener('abort', stopRun, { once: true });
+
   // Subscribe BEFORE calling agentRun — events fire during the call.
   const unsub = stratum.onEvent(correlationId, subStepId, (env) => {
     // Accept every KNOWN_VERSIONS envelope (producer emits 0.2.6). Hard-pinning
@@ -581,6 +591,10 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
         runResult = await stratum.agentRun(agentType, actualPrompt, {
           ...executionOptions,
           signal: abortController.signal,
+          // S03-3: the tag is supplied by the CALL SITE, never inferred from
+          // stepDispatch.flow_id — inference would silently tag sites the driver
+          // does not mean to tag, and an explicit opts.flow keeps them greppable.
+          ...(opts.flow ? { flow: opts.flow } : {}),
           correlationId,
           telemetry:        primaryTelemetry,
         });
@@ -590,6 +604,9 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
         : null;
     } catch (err) {
       if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(err?.code)) throw primaryFailure(err, err);
+      if (await confirmCancellation(err, {
+        stratum, flowId: opts.flowId, buildCancel: opts.buildCancel, tagged: Boolean(opts.flow),
+      })) throw primaryFailure(err, err);
       // F3/G3: preserve any billable usage the failed run reported (the local
       // connector attaches it on a non-success result / usage-bearing rejection) so
       // the consumer failure envelope can still debit the engine/GSD ledgers. G3:
@@ -747,6 +764,7 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
               const repairResult = await stratum.agentRun(reviewAgentType, repairPrompt, {
                 ...executionOptions,
                 signal: abortController.signal,
+                ...(opts.flow ? { flow: opts.flow } : {}),
                 telemetry: { ...primaryTelemetry, site: 'review-repair' },
               });
               repairResultForControl = repairResult;
@@ -765,6 +783,11 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
               return repairResult?.text ?? '';
             } catch (error) {
               repairFailure = error;
+              if (!['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(error?.code)) {
+                await confirmCancellation(error, {
+                  stratum, flowId: opts.flowId, buildCancel: opts.buildCancel, tagged: Boolean(opts.flow),
+                });
+              }
               repairDispatchId = typeof error?.dispatchId === 'string'
                 ? error.dispatchId
                 : null;
@@ -791,7 +814,8 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
       });
       // The tolerant text parser can recover ordinary repair failures, but it
       // must never turn a cancelled or still-running repair into a clean review.
-      if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(repairFailure?.code)) {
+      if (repairFailure && (opts.buildCancel?.cancelled
+        || ['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(repairFailure.code))) {
         repairFailure.usages = usages;
         throw repairFailure;
       }
@@ -854,6 +878,9 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   } finally {
     if (timeoutHandle) clearTimeout(timeoutHandle);
     if (onInterrupt && progress?.removeListener) progress.removeListener('interrupt', onInterrupt);
+    // Release the build-level listener, so a long build does not accumulate one per
+    // dispatch across hundreds of runs.
+    buildSignal?.removeEventListener('abort', stopRun);
     unsub();
   }
 }

package/lib/smartmemory-client.js

@@ -47,6 +47,7 @@
  * is, how it is identified, how it serializes — belongs to the caller.
  */
 
+import { randomUUID } from 'node:crypto';
 import { APIError, SmartMemoryClient } from '@smartmemory/sdk-js/core';
 
 /**
@@ -58,12 +59,28 @@ import { APIError, SmartMemoryClient } from '@smartmemory/sdk-js/core';
  * both still surface as one failure type upstream (sync: `failed`; emitter:
  * counts toward the circuit breaker).
  */
+/**
+ * Marker for an authorization refusal carried through the SDK's error wrapping.
+ * Format: `<marker><status>:<scope-error or empty>`.
+ */
+const REFUSED_MARKER = 'compose-sm-refused';
+
 export class SmartmemoryHttpError extends Error {
-  constructor(message, status, kind) {
+  constructor(message, status, kind, scopeError = null) {
     super(message);
     this.name = 'SmartmemoryHttpError';
     this.status = status;
     this.kind = kind;
+    /**
+     * The upstream `X-SM-Scope-Error` value, when it sent one.
+     *
+     * Additive and defaulted to null: no existing caller reads it, so retaining
+     * it changes nothing for them. It exists because "you are not a member of
+     * that workspace" and "your key lacks the required scope" are two different
+     * problems with two different fixes, and a 403 that cannot tell them apart
+     * sends the user to guess.
+     */
+    this.scopeError = scopeError;
   }
 }
 
@@ -81,6 +98,14 @@ const MALFORMED = 'malformed-response';
  * @returns {object} the client surface documented per-method below
  */
 export function createSmartmemoryClient(cfg) {
+  // A per-client nonce, because the marker travels through the SDK inside an
+  // error MESSAGE and upstream controls message content. A static marker meant a
+  // 500 whose JSON body happened to contain the marker text was converted into a
+  // 403 membership refusal — upstream could forge an authorization verdict by
+  // echoing a string. The nonce is generated per client and never leaves the
+  // process, so a body cannot carry a matching one.
+  const refusedNonce = randomUUID();
+  const refusedRe = new RegExp(`^${REFUSED_MARKER}:${refusedNonce}:(\\d{3}):(\\S*)$`);
   const baseUrl = cfg.baseUrl;
   const timeoutMs = cfg.timeoutMs ?? 3000;
 
@@ -125,6 +150,26 @@ export function createSmartmemoryClient(cfg) {
       parseFailed = true;
     }
 
+    // An authorization refusal is converted HERE, where the response and its
+    // headers are demonstrably in hand. The SDK builds its own error objects and
+    // does not carry headers onto them, so classifying downstream produced
+    // `scopeError: null` for every 403 — leaving the two actionable diagnoses
+    // ("not a member" vs "the key lacks scope") permanently collapsed into
+    // "reason undetermined". `asHttpError` passes a SmartmemoryHttpError through
+    // untouched, so throwing ours early is compatible with every caller.
+    if (res.status === 401 || res.status === 403) {
+      const scope = res.headers?.get?.('x-sm-scope-error');
+      const value = typeof scope === 'string' && scope.trim() ? scope.trim() : '';
+      // Carried in the MESSAGE, not on the object. The SDK wraps whatever the
+      // fetchFn throws and keeps only its text — no `cause`, no status, no
+      // custom fields (verified: the wrapper arrives with status 0 and every
+      // property lost). Since we author both the throw and the parse, and the
+      // marker is our own text rather than user data, encoding it here is
+      // deterministic; reconstructing it downstream from an object that no
+      // longer exists is not.
+      throw new Error(`${REFUSED_MARKER}:${refusedNonce}:${res.status}:${value}`);
+    }
+
     // 204 is exempt: it has no body by definition and BaseAPI returns null for
     // it without ever asking for one.
     if (res.ok && res.status !== 204 && parseFailed) {
@@ -204,8 +249,30 @@ export function createSmartmemoryClient(cfg) {
     }
   }
 
+  /**
+   * The upstream scope diagnosis, if the response carried one. Headers are
+   * available on the transport result and were simply not carried forward.
+   */
+  function refusalOf(err) {
+    // The SDK prefixes its own text, so scan lines and match each EXACTLY —
+    // an unanchored search would accept the marker anywhere in a body we do not
+    // control.
+    for (const part of String(err?.message ?? '').split(/[\s]+/)) {
+      const m = part.match(refusedRe);
+      if (m) return { status: Number(m[1]), scopeError: m[2] ? m[2] : null };
+    }
+    return null;
+  }
+
   function asHttpError(op, err) {
     if (err instanceof SmartmemoryHttpError) return err;
+    const refusal = refusalOf(err);
+    if (refusal) {
+      return new SmartmemoryHttpError(
+        `smartmemory: ${op} refused (HTTP ${refusal.status})`,
+        refusal.status, undefined, refusal.scopeError,
+      );
+    }
     if (err?.detail?.composeKind === MALFORMED) {
       return new SmartmemoryHttpError(
         `smartmemory: ${op} returned a 2xx (HTTP ${err.status}) with a non-JSON body`,

package/lib/stratum-mcp-client.js

@@ -151,12 +151,34 @@ export function resolveStepProfile(profiles, stepId) {
   return undefined;
 }
 
+/** The stratum MCP surface version compose's request vocabulary requires.
+ *  Pinned in stratum at ts/contracts/mcp-surface.json ("surface": 19) and asserted by
+ *  ts/tests/mcp/contracts-grammar.test.ts. Bump this and the package floor together. */
+export const REQUIRED_STRATUM_SURFACE = 19;
+export const REQUIRED_STRATUM_RANGE = '>=0.5.0';
+
 /**
  * Build the TS `stratum_agent_run` request from an agent string + compose-side
  * options. Capability restrictions and reasoning are execution requirements,
  * not telemetry: preserve them on the wire. The server validates provider
  * support, and refuses unsupported options instead of silently dropping them.
  */
+/**
+ * Compose's DERIVED transport for an agent run — a deterministic rule over compose's own
+ * inputs, not an observation: stratum reports no transport on its `ConnectorResult`
+ * (stratum/ts/src/connectors/base.ts). Owning a process group requires exec, and a
+ * `cancellationId` is what asks for one (stratum/ts/src/connectors/codex.ts), so a codex
+ * run with an id is exec. Without an id the server may select either transport
+ * (including through its own environment), so derive unknown. Only codex has two transports; every
+ * other provider derives null. The `_derived` suffix carries the distinction, so a later
+ * reader does not mistake this for ground truth (C33).
+ */
+export function derivedTransport(agentType, cancellationId) {
+  const provider = String(agentType ?? 'claude').split(':', 1)[0] || 'claude';
+  if (provider !== 'codex') return null;
+  return cancellationId ? 'exec' : 'unknown';
+}
+
 export function buildAgentRunRequest(agentType, prompt, opts = {}) {
   const provider = String(agentType ?? 'claude').split(':', 1)[0] || 'claude';
   return {
@@ -170,6 +192,7 @@ export function buildAgentRunRequest(agentType, prompt, opts = {}) {
     ...(opts.thinking !== undefined ? { thinking: opts.thinking } : {}),
     ...(opts.effort !== undefined ? { effort: opts.effort } : {}),
     ...(opts.cancellationId !== undefined ? { cancellationId: opts.cancellationId } : {}),
+    ...(opts.flow !== undefined ? { flow: opts.flow } : {}),
   };
 }
 
@@ -191,7 +214,7 @@ export class StratumMcpClient {
   // STRAT-PAR-STREAM: subscribers keyed by `${flowId}::${stepId}` → Set<handler>
   #eventSubs = new Map();
 
-  #recordAgentDispatch(dispatchId, agentType, opts, resultOrError, outcome, elapsedMs) {
+  #recordAgentDispatch(dispatchId, agentType, opts, resultOrError, outcome, elapsedMs, dispatchMeta = {}) {
     try {
       const context = opts.telemetry && typeof opts.telemetry === 'object'
         ? opts.telemetry
@@ -223,6 +246,10 @@ export class StratumMcpClient {
         duration_ms: finiteOrNull(usage.ms)
           ?? finiteOrNull(returnedTelemetry.durationMs)
           ?? finiteOrNull(elapsedMs),
+        // C51: the cancellationId that decides the transport is minted later and
+        // locally, inside #invokeAgentRun, so the builder cannot see it. The fact is
+        // derived where the id is minted and handed forward on `dispatchMeta`.
+        transport_derived: dispatchMeta.transportDerived ?? null,
       };
       for (const [field, value] of [
         ['build_id', context.build_id],
@@ -241,8 +268,11 @@ export class StratumMcpClient {
   async #dispatchAgentRun(agentType, prompt, opts, callOpts) {
     const dispatchId = randomUUID();
     const startedAt = Date.now();
+    // Carries facts #invokeAgentRun derives after the event builder's inputs are
+    // fixed — today only the transport (C51). Mutated in place by the invoke below.
+    const dispatchMeta = {};
     try {
-      const result = await this.#invokeAgentRun(agentType, prompt, opts, callOpts);
+      const result = await this.#invokeAgentRun(agentType, prompt, opts, callOpts, dispatchMeta);
       this.#recordAgentDispatch(
         dispatchId,
         agentType,
@@ -250,6 +280,7 @@ export class StratumMcpClient {
         result,
         isBlockedDispatch(result) ? 'blocked' : 'ok',
         Date.now() - startedAt,
+        dispatchMeta,
       );
       attachDispatchId(result, dispatchId);
       return result;
@@ -261,15 +292,22 @@ export class StratumMcpClient {
         error,
         isBlockedDispatch(error) ? 'blocked' : 'error',
         Date.now() - startedAt,
+        dispatchMeta,
       );
       attachDispatchId(error, dispatchId);
       throw error;
     }
   }
 
-  async #invokeAgentRun(agentType, prompt, opts, callOpts) {
+  async #invokeAgentRun(agentType, prompt, opts, callOpts, dispatchMeta = {}) {
     const signal = opts.signal;
-    const cancellationId = opts.cancellationId ?? (signal ? randomUUID() : undefined);
+    // `flow` REQUIRES a cancellationId server-side (stratum/ts/src/mcp/server.ts:182-186):
+    // without an owned process group there is nothing for a cross-process cancel to kill.
+    // Minting one without a signal is inert locally — the abort path below is armed only by
+    // `signal` — but it is what makes the run reachable from another process at all.
+    const cancellationId = opts.cancellationId ?? ((signal || opts.flow) ? randomUUID() : undefined);
+    // C51: derive the transport HERE, where the id exists, and hand it to the ledger row.
+    dispatchMeta.transportDerived = derivedTransport(agentType, cancellationId);
     const request = buildAgentRunRequest(agentType, prompt, { ...opts, cancellationId });
     signal?.throwIfAborted();
     // Probe under the same deadline as execution. No run has been dispatched yet,
@@ -285,7 +323,8 @@ export class StratumMcpClient {
         const installed = this.#client.getServerVersion()?.version ?? 'unknown';
         throw new StratumError('UNSUPPORTED_AGENT_OPTIONS',
           `Installed Stratum ${installed} does not support ${missing.join(', ')} required by this call; ` +
-          'required execution surface: 17 (@smartmemory/stratum >=0.4.0).', '');
+          `required execution surface: ${REQUIRED_STRATUM_SURFACE} `
+          + `(@smartmemory/stratum ${REQUIRED_STRATUM_RANGE}).`, '');
       }
     }
     signal?.throwIfAborted();
@@ -878,6 +917,66 @@ export class StratumMcpClient {
   async cancelAgentRun(runId) {
     return this.#callTool('stratum_cancel_agent_run', { runId });
   }
+
+  /**
+   * Cancel a running FOREGROUND flow by flow id (stratum >= 0.5.0). Settles the run and
+   * sweeps the agent groups stratum spawned for it. Resolves on success (including an
+   * already-terminal run); throws a StratumError on an incomplete sweep or a refusal.
+   */
+  async flowCancel(runId) {
+    try {
+      return await this.#callTool('stratum_flow_cancel', { runId });
+    } catch (error) {
+      const data = (error && typeof error.data === 'object' && error.data) || {};
+      if (error?.code === 'CANCELLATION_UNCONFIRMED' || error?.code === 'CANCELLATION_TEARDOWN_TIMEOUT') {
+        const wrapped = new StratumError(error.code, error.message, '');
+        wrapped.status = data.status ?? null;
+        wrapped.flowSettled = data.flowSettled === true;
+        wrapped.reason = data.reason ?? null;
+        wrapped.holderPid = data.holderPid ?? null;
+        wrapped.agents = data.agents ?? null;
+        if (error.rpcCode !== undefined) wrapped.rpcCode = error.rpcCode;
+        throw wrapped;
+      }
+      if (isUnknownFlowError(error)) {
+        const missing = new StratumError('FLOW_NOT_FOUND', `Stratum has no run ${runId}: ${error.message}`, '');
+        missing.status = null; missing.flowSettled = false; missing.reason = 'flow_not_found';
+        missing.holderPid = null; missing.agents = null;
+        throw missing;
+      }
+      // C38: NORMALISE, never rethrow. A dead server, a broken pipe or an undeclared engine
+      // error must still land in abortBuild's outcome table, and a refusal sweeps nothing —
+      // so flowSettled is false and the counters are zero, which is the literal truth.
+      throw asTransportRefusal(error);
+    }
+  }
+}
+
+/** The all-zero agent-sweep counters used whenever a refusal swept nothing. */
+const ZERO_AGENTS = Object.freeze({
+  signalled: 0, reaped: 0, gone: 0, unreachable: 0,
+  alreadySettled: 0, unresolved: 0, unsettled: 0, unreaped: 0,
+});
+
+/** The one shape every unclassifiable cancel failure takes. Exported because abortBuild wraps
+ *  its own connect() in it: connect happens OUTSIDE flowCancel, so a spawn or handshake failure
+ *  would otherwise bypass the table entirely (C38). */
+export function asTransportRefusal(error) {
+  const refusal = new StratumError('CANCELLATION_UNCONFIRMED',
+    `Stratum cancel could not be attempted: ${error?.message ?? String(error)}`, '');
+  refusal.status = null; refusal.flowSettled = false; refusal.reason = 'transport';
+  refusal.holderPid = null; refusal.agents = ZERO_AGENTS;
+  return refusal;
+}
+
+/** An unknown run id has NO structured envelope on the MCP surface — the SDK wraps the raw
+ *  ENOENT as a generic InternalError with no `data` at all. Both halves are required: `data`
+ *  absent AND an ENOENT-shaped message. Over-matching here turns a LIVE build into "nothing to
+ *  cancel", which is the one misclassification on this surface that loses work. */
+export function isUnknownFlowError(error) {
+  if (!error || error.data !== undefined) return false;
+  if (typeof error.code === 'string') return false;   // a coded failure is never this path
+  return /ENOENT|no such run|not found/i.test(String(error.message ?? ''));
 }
 
 function failureUsage(error) {

package/lib/tool-inventory.js

@@ -35,7 +35,6 @@ export const EFFECTS = /** @type {const} */ (['read', 'mutating', 'setup']);
  */
 export const CANON_IDS = new Set([
   'roadmap', 'changelog', 'feature-json', 'judgment',
-  'override-ledger', 'override-attest', 'override-grants',
 ]);
 
 /**

package/lib/version-check.js

@@ -75,10 +75,16 @@ async function fetchLatest(pkg) {
 export function compareVersions(a, b) {
   if (typeof a !== 'string' || typeof b !== 'string') return null
   const parse = (s) => {
-    const [core, pre] = s.split('-')
-    const parts = core.split('.').map(n => Number.parseInt(n, 10))
+    const buildIndex = s.indexOf('+')
+    const withoutBuild = buildIndex === -1 ? s : s.slice(0, buildIndex)
+    const prereleaseIndex = withoutBuild.indexOf('-')
+    const core = prereleaseIndex === -1 ? withoutBuild : withoutBuild.slice(0, prereleaseIndex)
+    const pre = prereleaseIndex === -1 ? null : withoutBuild.slice(prereleaseIndex + 1)
+    // parseInt is lenient: '3garbage' -> 3. A strict all-digits test is what makes
+    // the NaN guard below actually fire for trailing junk (COMP-SEMVER-STRICT).
+    const parts = core.split('.').map(n => (/^\d+$/.test(n) ? Number(n) : NaN))
     if (parts.length !== 3 || parts.some(n => Number.isNaN(n))) return null
-    return { parts, pre: pre ?? null }
+    return { parts, pre }
   }
   const pa = parse(a)
   const pb = parse(b)