@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/stratum-mcp-client.js

@@ -19,10 +19,50 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 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_]*)$/;
 
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function nonemptyStringOrNull(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function isBlockedDispatch(value) {
+  const candidates = [
+    value?.status,
+    value?.outcome,
+    value?.code,
+    value?.error?.status,
+    value?.error?.code,
+  ];
+  return candidates.some((candidate) => {
+    const normalized = typeof candidate === 'string' ? candidate.toLowerCase() : '';
+    return normalized === 'blocked'
+      || normalized === 'budget_exhausted'
+      || normalized === 'budget-exhausted';
+  });
+}
+
+function attachDispatchId(value, dispatchId) {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return;
+  try {
+    Object.defineProperty(value, 'dispatchId', {
+      configurable: true,
+      enumerable: false,
+      value: dispatchId,
+    });
+  } catch {
+    // A frozen third-party value cannot carry metadata. Dispatch behavior still
+    // wins over observability.
+  }
+}
+
 /**
  * Resolve producer-owned authoring values that TS v1 deliberately requires to
  * be literals. Compose knows these values at plan time, so mutate a cloned spec
@@ -113,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';
@@ -128,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 } : {}),
   };
 }
 
@@ -144,9 +186,150 @@ 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();
 
+  #recordAgentDispatch(dispatchId, agentType, opts, resultOrError, outcome, elapsedMs) {
+    try {
+      const context = opts.telemetry && typeof opts.telemetry === 'object'
+        ? opts.telemetry
+        : {};
+      const returnedTelemetry = resultOrError?.telemetry
+        && typeof resultOrError.telemetry === 'object'
+        ? resultOrError.telemetry
+        : {};
+      const usage = resultOrError?.usage && typeof resultOrError.usage === 'object'
+        ? resultOrError.usage
+        : {};
+      const effortIntended = Object.hasOwn(context, 'effort_intended')
+        ? nonemptyStringOrNull(context.effort_intended)
+        : nonemptyStringOrNull(opts.effort);
+      const event = {
+        kind: 'dispatch',
+        dispatch_id: dispatchId,
+        site: nonemptyStringOrNull(context.site) ?? 'unattributed',
+        agent: String(agentType ?? 'claude').split(':', 1)[0] || 'claude',
+        outcome,
+        model: nonemptyStringOrNull(returnedTelemetry.model)
+          ?? nonemptyStringOrNull(usage.model),
+        effort_intended: effortIntended,
+        effort_executed: nonemptyStringOrNull(returnedTelemetry.effort),
+        tokens_in: null,
+        tokens_out: null,
+        tokens_total: finiteOrNull(usage.tokens),
+        usd: finiteOrNull(usage.usd),
+        duration_ms: finiteOrNull(usage.ms)
+          ?? finiteOrNull(returnedTelemetry.durationMs)
+          ?? finiteOrNull(elapsedMs),
+      };
+      for (const [field, value] of [
+        ['build_id', context.build_id],
+        ['feature_code', context.feature_code],
+        ['step_id', context.step_id],
+      ]) {
+        if (nonemptyStringOrNull(value) !== null) event[field] = value;
+      }
+      if (finiteOrNull(context.attempt) !== null) event.attempt = context.attempt;
+      appendEvent(resolveDispatchLedgerCwd(context.project_cwd), event);
+    } catch {
+      // Dispatch capture is fail-open by contract.
+    }
+  }
+
+  async #dispatchAgentRun(agentType, prompt, opts, callOpts) {
+    const dispatchId = randomUUID();
+    const startedAt = Date.now();
+    try {
+      const result = await this.#invokeAgentRun(agentType, prompt, opts, callOpts);
+      this.#recordAgentDispatch(
+        dispatchId,
+        agentType,
+        opts,
+        result,
+        isBlockedDispatch(result) ? 'blocked' : 'ok',
+        Date.now() - startedAt,
+      );
+      attachDispatchId(result, dispatchId);
+      return result;
+    } catch (error) {
+      this.#recordAgentDispatch(
+        dispatchId,
+        agentType,
+        opts,
+        error,
+        isBlockedDispatch(error) ? 'blocked' : 'error',
+        Date.now() - startedAt,
+      );
+      attachDispatchId(error, dispatchId);
+      throw error;
+    }
+  }
+
+  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.
@@ -266,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(
@@ -276,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. */
@@ -289,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;
+    }
   }
 
   /**
@@ -318,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
@@ -360,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;
@@ -391,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 }
+        : {}),
     });
   }
 
@@ -422,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
@@ -431,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', {
@@ -509,15 +769,14 @@ 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.
-    return this.#callTool('stratum_agent_run',
-      buildAgentRunRequest(agentType, prompt, opts),
-      { subscribeProgress: true, correlationId });
+    // 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,
+      opts,
+      { subscribeProgress: true, correlationId },
+    );
   }
 
   /**
@@ -531,19 +790,87 @@ export class StratumMcpClient {
    * @returns {Promise<string>}
    */
   async runAgentText(agentType, prompt, opts = {}) {
-    const result = await this.#callTool('stratum_agent_run',
-      buildAgentRunRequest(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>}
@@ -552,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';
+}