@smartmemory/compose 0.3.7 → 0.4.0

package/lib/smartmemory-config.js

@@ -48,3 +48,57 @@ export function resolveProjectTag(cwd) {
 export function sourcePathFor(projectTag, repoRel) {
   return `compose/${projectTag}/${repoRel}`;
 }
+
+/**
+ * GOV-COMPOSE-SEAM-1 step 0 (`plumbing`).
+ *
+ * Translate the `smartmemory` config block into the three env vars Stratum's
+ * policy client reads, so Compose's ingest events and Stratum's enforcement
+ * events land in ONE workspace instead of two (or, today, one and nowhere).
+ *
+ * Two traps this function exists to close:
+ *
+ * 1. `workspaceId` is two different things. Top-level `compose.json#workspaceId`
+ *    is a Compose PROJECT SLUG (`^[a-z][a-z0-9-]{1,63}$`, see
+ *    discover-workspaces.js) used for provenance tagging. The SmartMemory
+ *    workspace id lives at `smartmemory.workspaceId` and looks like
+ *    `team_26f0bbe60a4c`. Sending the slug as `X-Workspace-Id` scopes every
+ *    event to a workspace that does not exist, and the API answers 200, so the
+ *    failure is silent. This reads the block, never the top level.
+ * 2. Stratum's `SmartMemoryClient` reads `process.env` ONCE at construction
+ *    (policy/smartmemory_client.ts). Setting these after the MCP subprocess
+ *    starts is a no-op — they must be in the spawn env, which is why this
+ *    returns a plain object for `connect()` to merge rather than mutating
+ *    `process.env`.
+ *
+ * Fail-quiet by design, matching the existing fail-open ingest contract: an
+ * unconfigured, disabled, or half-configured workspace returns `{}` and Stratum
+ * simply runs without policy delivery (it warns once on its own). A partial env
+ * would be worse than none — it produces events addressed to nowhere.
+ *
+ * @param {string} cwd
+ * @returns {{SMARTMEMORY_API_URL?: string, SMARTMEMORY_API_KEY?: string, SMARTMEMORY_WORKSPACE_ID?: string}}
+ */
+export function resolveStratumPolicyEnv(cwd) {
+  let cfg;
+  try {
+    cfg = getSmartmemoryConfig(cwd);
+  } catch {
+    return {};
+  }
+  if (cfg.enabled !== true) return {};
+
+  const baseUrl = typeof cfg.baseUrl === 'string' ? cfg.baseUrl.trim() : '';
+  // NEVER cfg.workspaceId's top-level namesake — see trap 1 above.
+  const workspaceId = typeof cfg.workspaceId === 'string' ? cfg.workspaceId.trim() : '';
+  const apiKey = cfg.apiKeyEnv ? process.env[cfg.apiKeyEnv] : undefined;
+
+  // All three or nothing.
+  if (!baseUrl || !workspaceId || !apiKey) return {};
+
+  return {
+    SMARTMEMORY_API_URL: baseUrl,
+    SMARTMEMORY_API_KEY: apiKey,
+    SMARTMEMORY_WORKSPACE_ID: workspaceId,
+  };
+}

package/lib/smartmemory-ingest.js

@@ -26,9 +26,23 @@ export function renderFeatureEventContent(row, projectTag) {
   return `[compose:${projectTag}] ${row.ts} ${row.tool} ${row.code ?? row.feature_code ?? '-'} by ${row.actor ?? 'mcp:agent'}`;
 }
 
-/** PURE. One deterministic line per gate-log entry. Shared with sync. */
+/** PURE. One deterministic line per gate-log entry. Shared with sync.
+ *
+ * GOV-COMPOSE-SEAM-1 step 0 (F2): this is a **Vision UI product gate** — a
+ * human approving a feature in the Compose UI, keyed by the UI gate id and a
+ * feature code. It is NOT Stratum's `gate_resolution`, which is a flow-step
+ * gate keyed by `run_id`/`step_id` and emitted by the engine when a run carries
+ * a policy bundle. The design assumed these were two records of one event and
+ * called for deduping them by `run_id`; they are two events, and no Stratum
+ * run id exists at this call site (see gate-log-store.js). Deduping them would
+ * have destroyed a real record.
+ *
+ * So they are disambiguated instead of merged: this line is tagged
+ * `vision-gate` rather than the bare `gate`, so a workspace query can separate
+ * product approvals from enforcement gates without guessing from shape.
+ */
 export function renderGateLogContent(entry, projectTag) {
-  return `[compose:${projectTag}] ${entry.timestamp} gate:${entry.decision} ${entry.feature_code ?? '-'} ${entry.id}`;
+  return `[compose:${projectTag}] ${entry.timestamp} vision-gate:${entry.decision} ${entry.feature_code ?? '-'} ${entry.id}`;
 }
 
 /** PURE. context for an event item (cli:compose regime — content-hash dedupe). */
@@ -45,6 +59,9 @@ export function buildGateLogContext(projectTag, entry) {
   return {
     origin: 'cli:compose',
     project: projectTag,
+    // Explicit record kind so a Compose product-gate approval is never mistaken
+    // for a Stratum enforcement `gate_resolution`. See renderGateLogContent.
+    record_kind: 'compose_vision_gate',
     source_path: sourcePathFor(projectTag, '.compose/data/gate-log.jsonl'),
     event: entry,
   };

package/lib/step-prompt.js

@@ -4,7 +4,7 @@
 
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { checkStaleness } from './staleness.js';
+import { findStaleArtifacts } from './lineage.js';
 import { readHypotheses, formatRejectedHypotheses } from './bug-ledger.js';
 
 // ---------------------------------------------------------------------------
@@ -242,13 +242,14 @@ export function buildGateContext(gateDispatch, context, gateExtras) {
     sections.push(`## Files Changed by This Feature\n${context.filesChanged.map(f => '- ' + f).join('\n')}`);
   }
 
-  // Staleness warnings — flag artifacts that belong to an earlier phase
-  if (context.featureDir && gateExtras?.toPhase) {
-    const staleArtifacts = checkStaleness(context.featureDir, gateExtras.toPhase);
-    const stale = staleArtifacts.filter(a => a.stale);
+  // Staleness warnings — derivation-based (COMP-PROV-LINEAGE): flag artifacts
+  // whose upstream (wasDerivedFrom) changed more recently than they did. Phase-
+  // independent, so it does not need gateExtras.toPhase.
+  if (context.featureDir) {
+    const stale = findStaleArtifacts(context.featureDir).filter(a => a.stale);
     if (stale.length > 0) {
       const lines = stale.map(a =>
-        `- **${a.file}** was written in phase \`${a.writtenPhase}\` but feature is now in \`${a.currentPhase}\``
+        `- **${a.file}** may be outdated — an upstream it was derived from (${a.staleAgainst.join(', ')}) changed more recently`
       );
       sections.push(`## Stale Artifacts\nThe following artifacts may be outdated:\n${lines.join('\n')}`);
     }

package/lib/stratum-engine.js

@@ -137,6 +137,46 @@ const BIN_CONFIG = {
   },
 };
 
+// Sibling checkout's package.json — used only to tell the user when the
+// installed dependency is shadowing a checkout at a different version.
+export const LIVE_STRATUM_TS_PACKAGE_JSON = resolve(
+  __dirname, '..', '..', 'stratum', 'ts', 'package.json',
+);
+
+function readPackageVersion(packageJsonPath) {
+  try {
+    const version = JSON.parse(readFileSync(packageJsonPath, 'utf8'))?.version;
+    return typeof version === 'string' ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// One warning per (kind, paths, versions) per process: the resolver runs on every connect.
+const shadowWarned = new Set();
+
+/**
+ * The installed dependency wins over the sibling checkout by design (CI has no
+ * sibling). In the monorepo that silently runs a STALE stratum after a local
+ * rebuild — found 2026-08-30 when the STRAT-LEARN-COST census ran against
+ * 0.3.3 (no `stratum_usage_report`) while `stratum/ts` was at 0.3.4. Say so
+ * once, with the escape hatch, whenever the two versions differ.
+ */
+function warnIfSiblingShadowed(kind, envVar, installedPackageJsonPath, siblingPackageJsonPath, warn) {
+  if (!siblingPackageJsonPath || !existsSync(siblingPackageJsonPath)) return;
+  const installedVersion = readPackageVersion(installedPackageJsonPath);
+  const siblingVersion = readPackageVersion(siblingPackageJsonPath);
+  if (!installedVersion || !siblingVersion || installedVersion === siblingVersion) return;
+  const key = `${kind}|${installedPackageJsonPath}|${siblingPackageJsonPath}|${installedVersion}|${siblingVersion}`;
+  if (shadowWarned.has(key)) return;
+  shadowWarned.add(key);
+  warn(
+    `[stratum-engine] using installed @smartmemory/stratum ${installedVersion}; `
+      + `the sibling checkout at ${dirname(siblingPackageJsonPath)} is ${siblingVersion} and is NOT what compose runs. `
+      + `Set ${envVar} to run a rebuilt checkout (${kind === 'mcp' ? 'dist/mcp/main.js' : 'dist/cli/stratum.js'}).`,
+  );
+}
+
 /** Resolve a bin from an installed @smartmemory/stratum package, if present. */
 function resolveInstalledBin(packageBin, requireResolve) {
   let packageJsonPath;
@@ -156,7 +196,7 @@ function resolveInstalledBin(packageBin, requireResolve) {
       ? packageJson.bin?.[packageBin]
       : undefined;
     if (typeof relativeBin !== 'string') return undefined;
-    return resolve(dirname(packageJsonPath), relativeBin);
+    return { bin: resolve(dirname(packageJsonPath), relativeBin), packageJsonPath };
   } catch {
     return undefined;
   }
@@ -168,7 +208,7 @@ function resolveInstalledBin(packageBin, requireResolve) {
  *
  * @param {'mcp'|'cli'} kind
  * @param {string} [cwd]
- * @param {{env?: object, requireResolve?: Function, siblingBins?: object}} [deps]
+ * @param {{env?: object, requireResolve?: Function, siblingBins?: object, siblingPackageJson?: string, warn?: Function}} [deps]
  */
 export function resolveStratumBin(kind, cwd = process.cwd(), deps = {}) {
   const config = BIN_CONFIG[kind];
@@ -180,11 +220,20 @@ export function resolveStratumBin(kind, cwd = process.cwd(), deps = {}) {
     || (kind === 'cli' ? env.COMPOSE_STRATUM_TS_BIN : undefined);
   if (envCandidate && existsSync(envCandidate)) return envCandidate;
 
-  const installedCandidate = resolveInstalledBin(
+  const installed = resolveInstalledBin(
     config.packageBin,
     deps.requireResolve ?? require.resolve.bind(require),
   );
-  if (installedCandidate && existsSync(installedCandidate)) return installedCandidate;
+  if (installed && existsSync(installed.bin)) {
+    warnIfSiblingShadowed(
+      kind,
+      config.env,
+      installed.packageJsonPath,
+      deps.siblingPackageJson ?? LIVE_STRATUM_TS_PACKAGE_JSON,
+      deps.warn ?? ((message) => console.warn(message)),
+    );
+    return installed.bin;
+  }
 
   const siblingCandidate = deps.siblingBins?.[kind] ?? config.sibling;
   if (siblingCandidate && existsSync(siblingCandidate)) return siblingCandidate;

package/lib/stratum-mcp-client.js

@@ -21,6 +21,7 @@ import YAML from 'yaml';
 import { validateBuildStreamEvent } from './build-stream-schema.js';
 import { appendEvent, resolveDispatchLedgerCwd } from './dispatch-ledger.js';
 import { resolveStratumMcpConnection } from './stratum-engine.js';
+import { resolveStratumPolicyEnv } from './smartmemory-config.js';
 
 const RUNTIME_INPUT_REF = /^\$\.input\.([A-Za-z_][A-Za-z0-9_]*)$/;
 
@@ -152,12 +153,9 @@ export function resolveStepProfile(profiles, stepId) {
 
 /**
  * Build the TS `stratum_agent_run` request from an agent string + compose-side
- * options. The engine surface (contracts/mcp-surface.json) accepts only
- * {agent, prompt, cwd, model?, sandboxMode?, background?} and rejects any other
- * key, so the python-era knobs (allowed_tools/thinking/effort/correlation_id)
- * are NOT sent — they are compose-side concerns applied at the invocation
- * (resolveAgentConfig). `agent` is normalized to the bare provider literal the
- * engine requires; `cwd` is required and defaults to the process cwd.
+ * 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.
  */
 export function buildAgentRunRequest(agentType, prompt, opts = {}) {
   const provider = String(agentType ?? 'claude').split(':', 1)[0] || 'claude';
@@ -167,6 +165,11 @@ export function buildAgentRunRequest(agentType, prompt, opts = {}) {
     cwd: opts.cwd ?? process.cwd(),
     ...(opts.modelID ? { model: opts.modelID } : {}),
     ...(opts.sandboxMode ? { sandboxMode: opts.sandboxMode } : {}),
+    ...(opts.allowedTools !== undefined ? { allowedTools: opts.allowedTools } : {}),
+    ...(opts.disallowedTools !== undefined ? { disallowedTools: opts.disallowedTools } : {}),
+    ...(opts.thinking !== undefined ? { thinking: opts.thinking } : {}),
+    ...(opts.effort !== undefined ? { effort: opts.effort } : {}),
+    ...(opts.cancellationId !== undefined ? { cancellationId: opts.cancellationId } : {}),
   };
 }
 
@@ -183,6 +186,8 @@ export class StratumMcpClient {
   #client = null;
   #transport = null;
   #connected = false;
+  #toolNames = null;
+  #agentFields = null;
   // STRAT-PAR-STREAM: subscribers keyed by `${flowId}::${stepId}` → Set<handler>
   #eventSubs = new Map();
 
@@ -237,11 +242,7 @@ export class StratumMcpClient {
     const dispatchId = randomUUID();
     const startedAt = Date.now();
     try {
-      const result = await this.#callTool(
-        'stratum_agent_run',
-        buildAgentRunRequest(agentType, prompt, opts),
-        callOpts,
-      );
+      const result = await this.#invokeAgentRun(agentType, prompt, opts, callOpts);
       this.#recordAgentDispatch(
         dispatchId,
         agentType,
@@ -266,6 +267,69 @@ export class StratumMcpClient {
     }
   }
 
+  async #invokeAgentRun(agentType, prompt, opts, callOpts) {
+    const signal = opts.signal;
+    const cancellationId = opts.cancellationId ?? (signal ? randomUUID() : undefined);
+    const request = buildAgentRunRequest(agentType, prompt, { ...opts, cancellationId });
+    signal?.throwIfAborted();
+    // Probe under the same deadline as execution. No run has been dispatched yet,
+    // so aborting a stalled probe requires no server cancellation acknowledgement.
+    if (this.#connected) {
+      if (!this.#agentFields) {
+        const listed = await abortable(this.#client.listTools(undefined, { signal }), signal);
+        const tool = listed.tools.find(entry => entry.name === 'stratum_agent_run');
+        this.#agentFields = new Set(Object.keys(tool?.inputSchema?.properties ?? {}));
+      }
+      const missing = Object.keys(request).filter(key => !this.#agentFields.has(key));
+      if (missing.length) {
+        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).', '');
+      }
+    }
+    signal?.throwIfAborted();
+    const teardownMs = opts.cancellationTimeoutMs ?? Number(process.env.COMPOSE_CANCEL_TIMEOUT_MS ?? 15000);
+    const rpc = this.#callTool('stratum_agent_run', request, callOpts);
+    // Keep the original rejection intact, including on a dead transport. Only an
+    // explicit abort initiates cancellation; a failed RPC alone must remain retryable.
+    const outcome = rpc.then(value => ({ value }), error => ({ error }));
+    let cancellation;
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => { rejectAbort = reject; });
+    const cancel = () => {
+      cancellation ??= (async () => {
+        let ack;
+        try {
+          ack = await cancellationDeadline(this.cancelAgentRun(cancellationId), teardownMs, 'Cancellation acknowledgement');
+        } catch (error) {
+          if (error?.code === 'CANCELLATION_TEARDOWN_TIMEOUT') throw error;
+          throw new StratumError('CANCELLATION_UNCONFIRMED', `Foreground cancellation could not be acknowledged: ${error.message}`, '');
+        }
+        if (!['cancelled', 'already_cancelled', 'already_complete', 'already_error', 'not_found'].includes(ack?.status)) {
+          throw new StratumError('CANCELLATION_UNCONFIRMED',
+            `Stratum did not confirm foreground termination (${ack?.status ?? 'missing status'})`, '');
+        }
+        const settled = await cancellationDeadline(outcome, teardownMs, 'Original agent RPC after cancellation acknowledgement');
+        const error = new Error('Agent execution cancelled after termination was acknowledged');
+        error.name = 'AbortError';
+        for (const key of ['usage', 'telemetry', 'split', 'usdSource']) {
+          if ((settled.error ?? settled.value)?.[key] !== undefined) error[key] = (settled.error ?? settled.value)[key];
+        }
+        throw error;
+      })();
+      cancellation.catch(rejectAbort);
+    };
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+    try {
+      const settled = await Promise.race([outcome, aborted]);
+      if (cancellation) await cancellation;
+      if (settled.error) throw settled.error;
+      return settled.value;
+    } finally { signal?.removeEventListener('abort', cancel); }
+  }
+
   /**
    * Subscribe to BuildStreamEvent push notifications scoped to a (flowId, stepId).
    * Handler receives a parsed BuildStreamEvent envelope. Returns an unsubscribe fn.
@@ -385,7 +449,15 @@ export class StratumMcpClient {
     // agent step failed with `403 forbidden / "Request not allowed"`. Pass the
     // full env through; the stratum connector scrubs SENSITIVE_ENV_VARS
     // (API keys, CLAUDECODE) before it spawns the agent.
-    transportOpts.env = opts.env ?? { ...process.env };
+    // GOV-COMPOSE-SEAM-1 step 0: hand Stratum the SmartMemory coordinates from
+    // `.compose/compose.json` so its enforcement events and Compose's ingest
+    // events land in one workspace. Resolved from config, not inherited from the
+    // ambient shell, and `{}` when the coupling is off — so a workspace without
+    // the `smartmemory` block spawns a byte-identical env to before this change.
+    // Must be in the SPAWN env: Stratum's policy client reads process.env once,
+    // at construction.
+    const policyEnv = resolveStratumPolicyEnv(opts.cwd ?? defaults.cwd ?? process.cwd());
+    transportOpts.env = { ...(opts.env ?? { ...process.env }), ...policyEnv };
     this.#transport = new StdioClientTransport(transportOpts);
 
     this.#client = new Client(
@@ -395,6 +467,8 @@ export class StratumMcpClient {
 
     await this.#client.connect(this.#transport);
     this.#connected = true;
+    this.#toolNames = null;
+    this.#agentFields = null;
   }
 
   /** Kill subprocess and clean up. */
@@ -408,6 +482,28 @@ export class StratumMcpClient {
     this.#client = null;
     this.#transport = null;
     this.#connected = false;
+    this.#toolNames = null;
+    this.#agentFields = null;
+  }
+
+  /** Feature-detect an MCP tool once per connection. Listing failures mean absent. */
+  async hasTool(name) {
+    if (this.#toolNames) return this.#toolNames.has(name);
+    const client = (process.env.NODE_ENV === 'test' && this._testClient) || this.#client;
+    if (!client || (!this.#connected && !(process.env.NODE_ENV === 'test' && this._testClient))) {
+      return false;
+    }
+    try {
+      const listed = await client.listTools();
+      this.#toolNames = new Set(
+        (Array.isArray(listed?.tools) ? listed.tools : [])
+          .map((tool) => tool?.name)
+          .filter((toolName) => typeof toolName === 'string'),
+      );
+      return this.#toolNames.has(name);
+    } catch {
+      return false;
+    }
   }
 
   /**
@@ -437,7 +533,19 @@ export class StratumMcpClient {
       requestOpts.maxTotalTimeout = 24 * 60 * 60 * 1000; // 24h hard cap
     }
 
-    const result = await (client ?? this.#client).callTool(callArgs, undefined, requestOpts);
+    const result = await (client ?? this.#client).callTool(callArgs, undefined, requestOpts).catch(error => {
+      if (error?.data && typeof error.data === 'object') {
+        // C11: `error.code` arrives as the JSON-RPC numeric code and callers
+        // then overwrite it with the engine's string code. Keep the numeric one
+        // reachable instead of destroying it.
+        if (error.data.code !== undefined && typeof error.code === 'number') error.rpcCode = error.code;
+        for (const key of ['code', 'usage', 'split', 'usdSource', 'stderr', 'telemetry']) {
+          if (error.data[key] !== undefined) error[key] = error.data[key];
+        }
+        if (error.usage) error.usage = failureUsage(error);
+      }
+      throw error;
+    });
 
     // TS stratum returns the payload as native MCP structured content and also
     // mirrors it as JSON text. Prefer the native object, retaining text parsing
@@ -479,11 +587,12 @@ export class StratumMcpClient {
     // Check for Stratum error envelope
     if (parsed.status === 'error' || parsed.error) {
       const err = parsed.error ?? parsed;
-      throw new StratumError(
-        err.code ?? 'STRATUM_ERROR',
-        err.message ?? 'Stratum tool call failed',
-        err.detail ?? ''
-      );
+      const error = new StratumError(err.code ?? 'STRATUM_ERROR', err.message ?? 'Stratum tool call failed', err.detail ?? '');
+      for (const key of ['usage', 'split', 'usdSource', 'stderr', 'telemetry']) {
+        if ((parsed[key] ?? err[key]) !== undefined) error[key] = parsed[key] ?? err[key];
+      }
+      if (error.usage) error.usage = failureUsage(error);
+      throw error;
     }
 
     return parsed;
@@ -510,6 +619,15 @@ export class StratumMcpClient {
       ...(typeof opts.workspaceRoot === 'string' && opts.workspaceRoot.length > 0
         ? { workspaceRoot: opts.workspaceRoot }
         : {}),
+      // GOV-COMPOSE-SEAM-1: the engine arg is `policy_step_selector`, NOT
+      // `step_selector` — the latter is the field inside a bundle rule, and a
+      // caller selector can only narrow a rule's own selector (intersection),
+      // never widen it. Nothing passes these yet; `consume-bundle` (step 2)
+      // is the consumer, and is gated on the canon step landing first.
+      ...(opts.policyBundle !== undefined ? { policy_bundle: opts.policyBundle } : {}),
+      ...(typeof opts.policyStepSelector === 'string' && opts.policyStepSelector.length > 0
+        ? { policy_step_selector: opts.policyStepSelector }
+        : {}),
     });
   }
 
@@ -541,6 +659,10 @@ export class StratumMcpClient {
     });
   }
 
+  async usageReport(runId, receipt) {
+    return this.#callTool('stratum_usage_report', { runId, receipt });
+  }
+
   /**
    * Resolve a gate step.
    * @param {string} flowId
@@ -550,6 +672,25 @@ export class StratumMcpClient {
    * @param {'human'|'agent'|'system'} resolvedBy
    * @param {string} [gateToken] - Audit-discovered waiting-gate issuance token to echo
    * @returns {Promise<object>}
+   *
+   * GOV-COMPOSE-SEAM-1 step 0 — why `rationale` and `resolvedBy` are accepted
+   * but deliberately NOT transmitted (they are used by this repo's own callers):
+   *
+   *   - `rationale`: `stratum_gate_resolve` has no rationale parameter and the
+   *     `gate_resolution` policy event has no field for it (engine.ts
+   *     buildGateResolutionEvent). Sending it would be dropped on the floor.
+   *     Carrying gate rationale into the audit chain needs a Stratum contract
+   *     change; it is not step-0 plumbing.
+   *   - `resolvedBy` is a ROLE (`human`/`agent`/`system`), not an identity, and
+   *     Compose has no user identity at this call site at all. The engine's
+   *     `user_id` populates `resolved_by_user_id`, an audit field that is
+   *     supposed to name a person. Passing "human" into it would manufacture
+   *     false provenance, which is worse than leaving it absent. Threading a
+   *     real identity belongs with roles (Stratum P3 / GOV-ROLES-1).
+   *
+   * Note also that `gate_resolution` only fires when the run carries a
+   * `bundle_id`, i.e. only once a policy bundle is passed at plan time. Until
+   * `consume-bundle` lands there is no gate policy event to enrich either way.
    */
   async gateResolve(flowId, stepId, outcome, rationale, resolvedBy = 'human', gateToken) {
     return this.#callTool('stratum_gate_resolve', {
@@ -628,12 +769,8 @@ export class StratumMcpClient {
    */
   async agentRun(agentType, prompt, opts = {}) {
     const correlationId = opts.correlationId ?? randomUUID();
-    // TS surface (contracts/mcp-surface.json → stratum_agent_run): the request
-    // is {agent, prompt, cwd, model?, sandboxMode?, background?} and rejects any
-    // undeclared key. The python-era tier accepted {type, allowed_tools, ...};
-    // those knobs are resolved compose-side (resolveAgentConfig) and applied at
-    // this seam — the engine's connector honors model + sandboxMode. `cwd` is
-    // required, so default to the process cwd when the caller omits it.
+    // The AbortSignal stays local; a cancellation ID crosses MCP so the caller
+    // waits for remote termination, unlike MCP's immediately rejecting abort.
     return this.#dispatchAgentRun(
       agentType,
       prompt,
@@ -653,22 +790,87 @@ export class StratumMcpClient {
    * @returns {Promise<string>}
    */
   async runAgentText(agentType, prompt, opts = {}) {
-    const result = await this.#dispatchAgentRun(
-      agentType,
-      prompt,
-      opts,
-      { subscribeProgress: false },
-    );
+    const toUsageRecords = (value) => {
+      const usage = value?.usage;
+      if (!usage || typeof usage !== 'object') return [];
+      const numeric = [
+        usage.tokens, usage.input_tokens, usage.output_tokens,
+        usage.cache_read, usage.cache_read_input_tokens,
+        usage.cache_creation, usage.cache_creation_input_tokens,
+        usage.cost_usd, usage.usd, usage.ms, usage.duration_ms,
+      ].some((item) => typeof item === 'number' && Number.isFinite(item) && item !== 0);
+      if (!numeric) return [];
+      const telemetry = value?.telemetry && typeof value.telemetry === 'object'
+        ? value.telemetry
+        : {};
+      // STRAT-USAGE-SPLIT: connectors report the true input/output detail
+      // BESIDE the Budget-shaped usage (same seam as usdSource). Prefer it —
+      // the legacy reconstruction below cannot tell input from output and
+      // filed the whole aggregate as output for every record ever written.
+      const split = value?.split && typeof value.split === 'object' ? value.split : null;
+      const input = split?.input ?? usage.input_tokens ?? 0;
+      const output = split?.output
+        ?? usage.output_tokens
+        ?? (typeof usage.tokens === 'number' ? Math.max(0, usage.tokens - input) : 0);
+      const record = {
+        dispatch_id: value?.dispatchId ?? randomUUID(),
+        model: telemetry.model ?? usage.model ?? opts.modelID ?? 'unknown',
+        ...(telemetry.effort ?? opts.effort ? { effort: telemetry.effort ?? opts.effort } : {}),
+        duration_ms: telemetry.durationMs ?? usage.duration_ms ?? usage.ms ?? 0,
+        input_tokens: input,
+        output_tokens: output,
+        ...(typeof (split?.cacheRead ?? usage.cache_read ?? usage.cache_read_input_tokens) === 'number'
+          ? { cache_read: split?.cacheRead ?? usage.cache_read ?? usage.cache_read_input_tokens }
+          : {}),
+        ...(typeof (split?.cacheCreation ?? usage.cache_creation ?? usage.cache_creation_input_tokens) === 'number'
+          ? { cache_creation: split?.cacheCreation ?? usage.cache_creation ?? usage.cache_creation_input_tokens }
+          : {}),
+      };
+      const cost = usage.cost_usd ?? usage.usd;
+      // Engine connectors label provenance as `usdSource` (camel, ConnectorUsage);
+      // compose-native usage records use `usd_source`. Either is acceptable;
+      // an unlabelled usd is still dropped (fail closed).
+      // The engine's ledger only admits budget keys inside `usage`, so the
+      // connector reports provenance BESIDE it (ConnectorResult.usdSource).
+      const rawUsdSource = usage.usd_source ?? value?.usdSource ?? usage.usdSource;
+      const usdSource = ['reported', 'estimated'].includes(rawUsdSource)
+        ? rawUsdSource
+        : null;
+      if (typeof cost === 'number' && Number.isFinite(cost) && cost > 0 && usdSource) {
+        record.cost_usd = cost;
+        record.usd_source = usdSource;
+      }
+      return [record];
+    };
+
+    const reportUsage = async (value) => {
+      if (typeof opts.onUsage !== 'function') return;
+      try {
+        await opts.onUsage(toUsageRecords(value));
+      } catch (error) {
+        console.warn(`[stratum-agent] onUsage hook failed: ${error?.message ?? error}`);
+      }
+    };
+
+    let result;
+    try {
+      result = await this.#dispatchAgentRun(
+        agentType,
+        prompt,
+        opts,
+        { subscribeProgress: false },
+      );
+    } catch (error) {
+      if (error?.usage) await reportUsage(error);
+      throw error;
+    }
+    await reportUsage(result);
     return result?.text ?? '';
   }
 
   /**
-   * Cancel an in-flight agent run. V2: the TS surface
-   * (contracts/mcp-surface.json → stratum_cancel_agent_run) takes {runId}, not
-   * the python-era {correlation_id} the engine now rejects. Only BACKGROUND runs
-   * carry a runId to cancel; a synchronous agent_run returns no handle, so this
-   * is a no-op (not_found) there — synchronous controlled executions are
-   * interrupted via the local connector's AbortController instead.
+   * Cancel a background runId or a foreground cancellationId. A successful
+   * acknowledgement means connector cleanup has finished.
    *
    * @param {string} runId
    * @returns {Promise<object>}
@@ -677,3 +879,36 @@ export class StratumMcpClient {
     return this.#callTool('stratum_cancel_agent_run', { runId });
   }
 }
+
+function failureUsage(error) {
+  const u = error.usage;
+  return { ...u,
+    ...(error.telemetry?.model ? { model: error.telemetry.model } : {}),
+    ...(error.split ? { input_tokens: error.split.input, output_tokens: error.split.output,
+      cache_read_input_tokens: error.split.cacheRead ?? 0, cache_creation_input_tokens: error.split.cacheCreation ?? 0 } : {}),
+    ...(u.usd !== undefined ? { cost_usd: u.usd } : {}),
+    ...(u.ms !== undefined ? { duration_ms: u.ms } : {}),
+    ...(error.usdSource ? { usd_source: error.usdSource } : {}),
+  };
+}
+
+async function abortable(operation, signal) {
+  if (!signal) return operation;
+  let abort;
+  try {
+    return await Promise.race([operation, new Promise((_, reject) => {
+      abort = () => reject(signal.reason ?? Object.assign(new Error('Aborted'), { name: 'AbortError' }));
+      signal.addEventListener('abort', abort, { once: true });
+      if (signal.aborted) abort();
+    })]);
+  } finally { signal.removeEventListener('abort', abort); }
+}
+
+async function cancellationDeadline(operation, ms, label) {
+  let timer;
+  try {
+    return await Promise.race([operation, new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new StratumError('CANCELLATION_TEARDOWN_TIMEOUT', `${label} did not settle after ${ms}ms`, '')), ms);
+    })]);
+  } finally { clearTimeout(timer); }
+}

package/lib/test-bootstrap.js

@@ -562,3 +562,34 @@ export function deriveTestsPass(summary) {
   if (!summary || !summary.parsed) return true;
   return summary.test_count >= 1 && summary.pass_rate === 100;
 }
+
+/**
+ * COMP-COMPLETION-GATE: the attestation the completion gate consumes.
+ *
+ * This is `deriveTestsPass` with its safety valve removed, as a TRI-state:
+ *
+ *   'passed'    — the output parsed, at least one test ran, all passed
+ *   'failed'    — the output parsed and something failed (or nothing ran)
+ *   'no-signal' — the output could not be read at all
+ *
+ * The distinction that matters is the third one. `deriveTestsPass` collapses
+ * "unreadable" into `true`, so a framework the parser does not understand
+ * (`ava`, `tap`, anything unknown) silently attests a passing test run that was
+ * never observed. That value then goes onto a permanent completion record and,
+ * under the gate, into a tamper-evident ledger — which is exactly the kind of
+ * claim the ledger exists to make trustworthy.
+ *
+ * ABSENCE OF SIGNAL IS NEVER ATTESTATION. The gate refuses 'no-signal' and tells
+ * the operator to configure `guard.testCommand`, whose real exit code can attest
+ * where the parser cannot.
+ *
+ * `deriveTestsPass` is retained for the ungated ship-step path and its existing
+ * degrade contract; it is not the gate's input.
+ *
+ * @param {{ test_count: number, pass_rate: number, parsed: boolean }|null} summary
+ * @returns {'passed'|'failed'|'no-signal'}
+ */
+export function deriveTestsAttested(summary) {
+  if (!summary || !summary.parsed) return 'no-signal';
+  return (summary.test_count >= 1 && summary.pass_rate === 100) ? 'passed' : 'failed';
+}