@smartmemory/compose 0.4.1 → 0.5.0

package/lib/build.js

@@ -13,8 +13,9 @@ import { join, resolve, dirname, relative, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync, execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
 
-import { StratumMcpClient, StratumError, resolvePlanSpecValues, resolveStepProfile } from './stratum-mcp-client.js';
+import { StratumMcpClient, StratumError, resolvePlanSpecValues, resolveStepProfile, asTransportRefusal, isUnknownFlowError } from './stratum-mcp-client.js';
 import { resolveStratumMcpConnection } from './stratum-engine.js';
 import { runAndNormalize, mergeUsage, AgentTimeoutError, AgentAbortedError, UserInterruptError, AgentError } from './result-normalizer.js';
 import { checkCapabilityViolation } from './capability-checker.js';
@@ -58,6 +59,20 @@ import { isTriageStale } from './triage.js';
 import { applyFrontTriage, maybeEscalateLane } from './lane-gate.js';
 import { LENS_DEFINITIONS } from './review-lenses.js';
 import { injectCertInstructions } from './cert-inject.js';
+// COMP-BUILD-CANCEL: the build-level cancel handle, its registry and the bounded
+// SIGINT/SIGTERM teardown (blueprint §3.4-§3.6).
+import {
+  createBuildCancel,
+  confirmCancellation,
+  isRunCancelled,
+  flowTag,
+  runCancelTeardown,
+  cancelBudgets,
+  withDeadline,
+  registerBuildCancel,
+  unregisterBuildCancel,
+  lookupBuildCancel,
+} from './build-cancel.js';
 import { buildReviewPrompt } from './review-prompt.js';
 import { detectTestFramework, scaffoldTestFramework, parseTestSummary, deriveTestsPass, deriveTestsAttested, isTestFile } from './test-bootstrap.js';
 import { classifyStepAsTier, evaluateTiers } from './gate-tiers.js';
@@ -76,6 +91,7 @@ import {
   ConsumerArtifactError,
   ConsumerFanoutArtifacts,
   ConsumerMergeDecisionError,
+  MergeAfterCancelError,
   isConsumerDescriptor,
   recoverAdvancedConsumerArtifacts,
   verifyConsumerRunRevision,
@@ -687,6 +703,16 @@ function responseReissuesStep(response, stepId) {
   return response.ready.some((ready) => ready?.id === stepId && ready?.previousFailure);
 }
 
+async function callFlowWithCancellation(stratum, method, flowId, buildCancel, ...args) {
+  if (buildCancel.cancelled) throw buildCancel.signal.reason;
+  try {
+    return await stratum[method](flowId, ...args);
+  } catch (error) {
+    await confirmCancellation(error, { stratum, flowId, buildCancel });
+    throw error;
+  }
+}
+
 async function reportConsumerStepDone({
   descriptor,
   flowId,
@@ -695,7 +721,9 @@ async function reportConsumerStepDone({
   artifacts,
   progress,
   streamWriter,
+  buildCancel,
 }) {
+  if (buildCancel?.cancelled) throw buildCancel.signal.reason;
   try {
     return {
       response: await stratum.stepDone(
@@ -704,6 +732,7 @@ async function reportConsumerStepDone({
       skipped: false,
     };
   } catch (error) {
+    if (await confirmCancellation(error, { stratum, flowId, buildCancel })) throw error;
     if (!isStaleOrDuplicateConsumerReportError(error)) throw error;
 
     const summary = `consumer item ${descriptor.id} (index ${descriptor.itemIndex}) step_done skipped:`
@@ -761,6 +790,9 @@ export async function runConsumerIssuance({
   // events for this item and halts a spinning run.
   perItemTimeoutMs = null,
   stuckDetector = null,
+  // COMP-BUILD-CANCEL S03-5: the build-level cancel handle, so an item's agent dies with
+  // the build. Optional — lib/gsd.js calls this without one.
+  buildCancel = null,
   // D6: the full agent profile string for this fanout step (from the compose
   // sidecar), applied at invocation so e.g. an isolation:none review fanout runs
   // read-only. Absent → the descriptor's bare provider literal (no restrictions).
@@ -782,7 +814,7 @@ export async function runConsumerIssuance({
     const envelope = { failure: `${artifactError.code}: ${artifactError.message}` };
     artifacts.prepareArtifactFailure(descriptor, envelope, artifactError);
     const report = await reportConsumerStepDone({
-      descriptor, flowId, envelope, stratum, artifacts, progress, streamWriter,
+      descriptor, flowId, envelope, stratum, artifacts, progress, streamWriter, buildCancel,
     });
     if (report.skipped) return report.response;
     const { response } = report;
@@ -801,6 +833,7 @@ export async function runConsumerIssuance({
       descriptor,
       flowId,
       envelope: recovery.envelope,
+      buildCancel,
       stratum,
       artifacts,
       progress,
@@ -943,6 +976,14 @@ export async function runConsumerIssuance({
       reviewMode: reviewOpts.reviewMode,
       confidenceGate: reviewOpts.confidenceGate,
       lens: reviewOpts.lens,
+      // COMP-BUILD-CANCEL S03-4: tag the item so `stratum_flow_cancel` can reach it
+      // from another process, and chain the build handle so a local `isolation: none`
+      // item — which never enters stratum — dies with the build.
+      ...(flowTag(flowId, descriptor.step ?? descriptor.id, descriptor.itemIndex)
+        ? { flow: flowTag(flowId, descriptor.step ?? descriptor.id, descriptor.itemIndex) }
+        : {}),
+      flowId, buildCancel,
+      buildSignal: buildCancel?.signal,
       telemetry: {
         site: context.gsd ? 'gsd' : 'consumer',
         project_cwd: context.projectCwd ?? context.cwd,
@@ -956,6 +997,7 @@ export async function runConsumerIssuance({
       localExecution: descriptor.policy?.isolation === 'none',
     });
   } catch (error) {
+    if (buildCancel?.cancelled) throw error;
     const failedUsage = failureUsageFields(error);
     // Control failures do not settle the item, so record known dispatch usage
     // before aborting the pump. Never retry work with uncertain termination.
@@ -1089,7 +1131,7 @@ export async function runConsumerIssuance({
   }
 
   const report = await reportConsumerStepDone({
-    descriptor, flowId, envelope, stratum, artifacts, progress, streamWriter,
+    descriptor, flowId, envelope, stratum, artifacts, progress, streamWriter, buildCancel,
   });
   if (report.skipped) return report.response;
   const { response } = report;
@@ -1243,7 +1285,7 @@ function usagePayload(usage, usages) {
 
 /** Send one surface-15 receipt per underlying model dispatch. */
 export async function reportUsageReceipts(context, usage, meta = {}) {
-  if (!context?.receiptsMode || !context.flowId || typeof context.stratum?.usageReport !== 'function') {
+  if (context?.buildCancel?.cancelled || !context?.receiptsMode || !context.flowId || typeof context.stratum?.usageReport !== 'function') {
     return [];
   }
   const entries = Array.isArray(usage)
@@ -1251,6 +1293,7 @@ export async function reportUsageReceipts(context, usage, meta = {}) {
     : (Array.isArray(usage?.usages) ? usage.usages : (usage ? [usage] : []));
   const responses = [];
   for (const entry of entries) {
+    if (context.buildCancel?.cancelled) break;
     if (!entry || typeof entry !== 'object') continue;
     const engineUsage = toEngineUsage(entry);
     if (!engineUsage) continue;
@@ -1292,6 +1335,7 @@ export async function reportUsageReceipts(context, usage, meta = {}) {
     try {
       responses.push(await context.stratum.usageReport(context.flowId, receipt));
     } catch (error) {
+      if (await confirmCancellation(error, context)) break;
       console.warn(`[usage-receipt] failed for ${receipt.dispatchId}: ${error?.message ?? error}`);
     }
   }
@@ -1466,12 +1510,38 @@ function readActiveBuild(dataDir) {
   }
 }
 
-function writeActiveBuild(dataDir, state) {
+/**
+ * COMP-BUILD-CANCEL §3.7 — re-read and CLAIM before ANY mutation of the active-build
+ * record. Strict on purpose: a missing flow id must never match anything.
+ *
+ * Returns the claimed record, or a REASON. C48: the fallback validates PRESENCE before
+ * equality, because `undefined === undefined` is true and two records that both lack a
+ * pid would otherwise claim each other.
+ */
+function claimActiveBuild(dataDir, active) {
+  const cur = readActiveBuild(dataDir);
+  if (!cur) return { ok: false, reason: 'ownership_lost' };
+  if (cur.featureCode !== active.featureCode) return { ok: false, reason: 'ownership_lost' };
+  if (cur.flowId && active.flowId) {
+    return cur.flowId === active.flowId
+      ? { ok: true, record: cur }
+      : { ok: false, reason: 'ownership_lost' };
+  }
+  // No flow id on one side: fall back to pid + startedAt, but ONLY when all four are present.
+  const present = Boolean(cur.pid) && Boolean(active.pid)
+    && Boolean(cur.startedAt) && Boolean(active.startedAt);
+  if (!present) return { ok: false, reason: 'ownership_unverifiable' };
+  return (cur.pid === active.pid && cur.startedAt === active.startedAt)
+    ? { ok: true, record: cur }
+    : { ok: false, reason: 'ownership_lost' };
+}
+
+export function writeActiveBuild(dataDir, state, { stampPid = true } = {}) {
   mkdirSync(dataDir, { recursive: true });
-  // Always stamp PID so concurrent processes can detect each other
-  state.pid = process.pid;
+  // The aborter must preserve the driver's identity when it owns the terminal write.
+  if (stampPid) state.pid = process.pid;
   const target = activeBuildPath(dataDir);
-  const tmp = target + '.tmp';
+  const tmp = `${target}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
   writeFileSync(tmp, JSON.stringify(state, null, 2));
   renameSync(tmp, target);
 }
@@ -1971,8 +2041,15 @@ export function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
       `${fileRef} this question concisely:\n\n` +
       `${question}\n\n` +
       `Keep your answer brief — 2-3 sentences max.`;
+    if (context.buildCancel?.cancelled) throw context.buildCancel.signal.reason;
+    const taggedFlow = flowTag(context.flowId, gateDispatch.step_id ?? gateDispatch.id);
     const text = await stratum.runAgentText('claude', qaPrompt, {
       cwd: context.cwd,
+      // S03-4 (R1): a gate pause leaves the run `running`, so a gate-time agent IS
+      // admitted and tags successfully (C1). Conditional on `context.flowId` because
+      // `makeAskAgent` is exported and called with a bare, flow-less context in tests.
+      ...(taggedFlow ? { flow: taggedFlow } : {}),
+      signal: context.buildCancel?.signal,
       telemetry: {
         site: 'gate-qa',
         project_cwd: context.projectCwd ?? context.cwd,
@@ -1990,6 +2067,9 @@ export function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
           budgetExhausted = true;
         }
       },
+    }).catch(async error => {
+      await confirmCancellation(error, { stratum, flowId: context.flowId, buildCancel: context.buildCancel, tagged: Boolean(taggedFlow) });
+      throw error;
     });
     return text || '(no answer)';
   };
@@ -2009,8 +2089,8 @@ export function deleteActiveBuild(dataDir) {
  * never produce more steps.  Used to detect stale lock files and decide
  * whether a resumed flow needs a fresh start.
  */
-function isTerminalFlow(status) {
-  return ['completed', 'failed', 'budget_exhausted'].includes(status);
+export function isTerminalFlow(status) {
+  return ['completed', 'failed', 'budget_exhausted', 'cancelled'].includes(status);
 }
 
 function isRecoverableFlowProbeError(err) {
@@ -2158,7 +2238,34 @@ export async function emitBugCheckpointOnTerminalFailure(context, exhaustedStepI
   }
 }
 
+/** Guard the actual vision mutation, after updateItemStatus's async server probe.
+ * Use a per-call receiver so a late best-effort update cannot outlive its claim. */
+async function killOwnedBuildVision(visionWriter, itemId, claimOwnership) {
+  const ownedWriter = Object.create(visionWriter);
+  for (const method of ['_directUpdateItemStatus', '_restUpdateItemStatus']) {
+    ownedWriter[method] = (...args) => {
+      const claim = claimOwnership();
+      if (!claim.ok) throw Object.assign(new Error(claim.reason), { reason: claim.reason });
+      return visionWriter[method](...args);
+    };
+  }
+  return ownedWriter.updateItemStatus(itemId, 'killed');
+}
+
+/** Claims protect the cancelled driver's record AND its vision projection. */
+async function terminalizeCancelledBuild({ dataDir, buildIdentity, visionWriter, itemId, failureReason }) {
+  if (!buildIdentity) return;
+  const claim = claimActiveBuild(dataDir, buildIdentity);
+  if (!claim.ok) return;
+  writeActiveBuild(dataDir, {
+    ...claim.record, status: 'aborted', failureReason,
+    completedAt: claim.record.completedAt ?? new Date().toISOString(),
+  });
+  try { await killOwnedBuildVision(visionWriter, itemId, () => claimActiveBuild(dataDir, buildIdentity)); } catch { /* best-effort projection */ }
+}
+
 async function terminalizeThrownBuild({
+  buildCancel, buildIdentity,
   cwd,
   dataDir,
   cfg,
@@ -2175,7 +2282,9 @@ async function terminalizeThrownBuild({
 }) {
   const flowId = response?.runId ?? null;
   if (!flowId) return false;
-  await writeFailedBuildTerminalState({
+  if (buildCancel?.cancelled) {
+    await terminalizeCancelledBuild({ dataDir, buildIdentity, visionWriter, itemId, failureReason });
+  } else await writeFailedBuildTerminalState({
     cwd,
     dataDir,
     cfg,
@@ -2190,7 +2299,7 @@ async function terminalizeThrownBuild({
       featureCode,
       flowId,
       mode,
-      status: 'failed',
+      status: buildCancel?.cancelled ? 'aborted' : 'failed',
       startedAt: buildStartedAt,
       completedAt: new Date().toISOString(),
       durationMs: Date.now() - new Date(buildStartedAt).getTime(),
@@ -2249,8 +2358,7 @@ export async function runBuild(featureCode, opts = {}) {
   // Handle --abort early (featureCode may be null). C2: pass the project root so
   // the engine is resolved from this project's capabilities, not process.cwd().
   if (opts.abort) {
-    await abortBuild(dataDir, featureCode, cwd);
-    return;
+    return await abortBuild(dataDir, featureCode, cwd);
   }
 
   const {
@@ -2265,6 +2373,15 @@ export async function runBuild(featureCode, opts = {}) {
   let accumulatorPersisted = !isNewAccumulator;
   const buildStartedAt = new Date().toISOString();
   let buildStatus = 'failed';
+  // COMP-BUILD-CANCEL §3.4: one handle per runBuild. `signal` is the D-F chain into every
+  // dispatch; `cancelled` is the merge guard's flag; `teardownStarted` is what a second
+  // Ctrl-C keys on. Registered by flow id once the runId exists (S03-5b).
+  const buildCancel = createBuildCancel();
+  let buildIdentity = null;
+  // The flow id this build registered its handle under, so the outermost finally can
+  // unregister without reaching into the inner try's `response`.
+  let registeredFlowId = null;
+  const { cancelMs: cancelTimeoutMs, drainMs: drainTimeoutMs, joinMs: teardownJoinMs } = cancelBudgets();
   let attemptStarted = true;
   let attemptFinalized = false;
   // COMP-TRIAGE-6-4: function-scoped so finalizeBuildAttempt's ownership guard
@@ -2294,6 +2411,7 @@ export async function runBuild(featureCode, opts = {}) {
   };
   const finalizeBuildAttempt = () => {
     if (!attemptStarted || attemptFinalized) return;
+    if (buildCancel.teardown || buildCancel.cancelled) buildStatus = 'aborted';
     const terminalStatus = buildStatus === 'complete'
       ? 'complete'
       : (buildStatus === 'killed' || buildStatus === 'aborted')
@@ -2766,16 +2884,36 @@ export async function runBuild(featureCode, opts = {}) {
       && isProcessAlive(activeForDecision.pid)
     );
     const sameMode = !activeForDecision?.mode || activeForDecision.mode === mode;
-    let flowTerminal = !activeForDecision?.flowId;
-    if (activeForDecision?.flowId && ['complete', 'aborted', 'killed'].includes(activeForDecision.status)) {
-      flowTerminal = true;
-    } else if (activeForDecision?.flowId && !pidAlive) {
+    let flowTerminal = !activeForDecision?.flowId
+      || ['complete', 'aborted', 'killed'].includes(activeForDecision.status);
+    const probeFlowId = opts.resumeFlowId ?? activeForDecision?.flowId;
+    // Probe only when the engine can tell us something the local record cannot: an
+    // explicit resume target, or a record that is not already terminal. A locally
+    // terminal record needs no probe (pre-S05 semantics, kept).
+    if (probeFlowId && !opts.fresh && (opts.resumeFlowId || !flowTerminal)) {
       try {
-        const audit = await stratum.audit(activeForDecision.flowId);
+        const audit = await stratum.audit(probeFlowId);
+        if (audit?.status === 'cancelled') {
+          // C42/C49: a resume probe is not necessarily the owning driver.
+          const handle = lookupBuildCancel(probeFlowId);
+          if (handle) {
+            handle.cancel('flow_cancelled');
+          } else if (activeForDecision?.flowId === probeFlowId) {
+            const claim = claimActiveBuild(dataDir, activeForDecision);
+            if (claim.ok) writeActiveBuild(dataDir, {
+              ...claim.record, status: 'aborted', failureReason: 'flow_cancelled',
+              completedAt: new Date().toISOString(),
+            });
+          }
+          buildStatus = 'aborted';
+          throw Object.assign(new Error(`Flow ${probeFlowId} was cancelled; it cannot be resumed. Run with --fresh to start a new build.`), {
+            code: 'FLOW_CANCELLED', reason: 'flow_cancelled',
+          });
+        }
         flowTerminal = isTerminalFlow(audit?.status);
         if (flowTerminal) {
           recoverAdvancedConsumerArtifacts({
-            runId: activeForDecision.flowId,
+            runId: probeFlowId,
             targetCwd: agentCwd,
             artifactRoot: opts.consumerArtifactsRoot,
             audit,
@@ -2783,7 +2921,10 @@ export async function runBuild(featureCode, opts = {}) {
         }
       } catch (err) {
         if (isRecoverableFlowProbeError(err)) {
-          flowTerminal = true;
+          // An unknown flow is only evidence the build is over when its driver is
+          // gone. With a live driver pid it is not evidence of anything, and the
+          // same-feature conflict guard below must still hold (pre-S05 semantics).
+          if (!pidAlive) flowTerminal = true;
         } else {
           throw err;
         }
@@ -2902,6 +3043,58 @@ export async function runBuild(featureCode, opts = {}) {
       if (triageEstimate) emitTriageEstimate(cwd, triageEstimate);
     }
 
+    // COMP-BUILD-CANCEL S03-5b (C36): register the in-process handle the moment the run id
+    // exists — BEFORE the Codex worktree preflight below, which can hold for up to
+    // PROBE_AGENT_TIMEOUT_MS. `active-build.json` already advertises this flow id and pid,
+    // so a same-process abort arriving in that window would otherwise find no handle, fall
+    // through to the foreign-pid branch, and SIGTERM the compose server itself.
+    registeredFlowId = response?.runId ?? null;
+    registerBuildCancel(registeredFlowId, buildCancel);
+    buildIdentity = { featureCode, flowId: registeredFlowId, pid: process.pid,
+      startedAt: readActiveBuild(dataDir)?.startedAt };
+
+    // SIGINT/SIGTERM: cancel the flow, tear down, exit (COMP-BUILD-CANCEL §9). A SECOND
+    // signal during teardown exits immediately — a user pressing Ctrl-C twice is asking to
+    // stop waiting, and the durable state a bounded teardown would have written is worth
+    // less than obeying that.
+    signalHandler = (signal) => {
+      // No local `tearingDown` flag: the handle owns that state (C27), so a teardown
+      // started by any other path is visible here too.
+      if (buildCancel.teardownStarted) { process.exit(signal === 'SIGINT' ? 130 : 143); return; }
+      buildStatus = 'aborted';
+      // ASSIGN, do not fire and forget (C45). The promise is what the outer catch reads to
+      // stand down and what the outermost finally and the CLI join on. `runCancelTeardown`
+      // sets `teardownStarted` synchronously, so a second signal takes the branch above.
+      buildCancel.teardown = runCancelTeardown({
+        buildCancel,
+        signal,
+        flowId: response?.runId,
+        flowCancel: (id) => stratum.flowCancel(id),
+        timeoutMs: cancelTimeoutMs,
+        drainMs: drainTimeoutMs,
+        claimOwnership: () => claimActiveBuild(dataDir, buildIdentity),
+        killVision: () => killOwnedBuildVision(visionWriter, itemId, () => claimActiveBuild(dataDir, buildIdentity)),
+        // The teardown re-claims after vision, immediately before this write (§3.7).
+        writeTerminal: (record) => {
+          writeActiveBuild(dataDir, { ...record, status: 'aborted', completedAt: new Date().toISOString() });
+        },
+        removeListeners: () => {
+          process.removeListener('SIGINT', onSigint);
+          process.removeListener('SIGTERM', onSigterm);
+        },
+        exit: (code) => process.exit(code),
+        // eslint-disable-next-line no-console
+        log: (message) => console.warn(`[build] ${message}`),
+      });
+    };
+    // Named wrappers, because the two existing removeListener sites must remove the same
+    // function references that were registered.
+    const onSigint = () => signalHandler('SIGINT');
+    const onSigterm = () => signalHandler('SIGTERM');
+    signalHandler.listeners = { onSigint, onSigterm };
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+
     // COMP-CODEX-IMPL: verify Codex can write inside a detached git worktree (the
     // execute step's isolation primitive) before any step dispatches. Runs on the
     // EFFECTIVE role — after resume restoration above — so a resumed Codex build is
@@ -2922,8 +3115,12 @@ export async function runBuild(featureCode, opts = {}) {
         stratum,
         dataDir,
         ts: new Date().toISOString().replace(/[:.]/g, '-'),
+        // C36/C51: an abort during the probe stops the probe too.
+        signal: buildCancel.signal,
       });
       if (!probe.ok) {
+        // The signal teardown owns terminal writes; let the catch/finally drain it.
+        if (buildCancel.teardown) throw new Error(codexProbeAbortMessage(probe.reason));
         // The plan/resume above already persisted feature.json=IN_PROGRESS and
         // active-build.json='running'. A preflight abort throws before the normal
         // terminal handlers run, so roll BOTH back here (mirrors the killed/failed
@@ -2972,14 +3169,6 @@ export async function runBuild(featureCode, opts = {}) {
       specPath: `pipelines/${templateName}.stratum.yaml`,
     });
 
-    // SIGINT/SIGTERM: mark build as killed
-    signalHandler = () => {
-      buildStatus = 'killed';
-      streamWriter.close('killed');
-    };
-    process.on('SIGINT', signalHandler);
-    process.on('SIGTERM', signalHandler);
-
     // V4: merge the runtime profile map over the static sidecar (runtime wins).
     // Tiers/templates carried by $.input.* agents (e.g. --implementer=claude::critical)
     // are stripped to the bare provider at resolution for the engine; recover the
@@ -3020,6 +3209,7 @@ export async function runBuild(featureCode, opts = {}) {
     const context = {
       stratum,
       flowId: response.runId,
+      buildCancel,
       receiptsMode,
       cwd: agentCwd,
       projectCwd: cwd,
@@ -3207,6 +3397,7 @@ export async function runBuild(featureCode, opts = {}) {
       return runConsumerIssuance({
         descriptor,
         flowId,
+        buildCancel,
         stratum,
         artifacts,
         audit,
@@ -3224,7 +3415,7 @@ export async function runBuild(featureCode, opts = {}) {
     };
 
     const launchPendingConsumers = () => {
-      while (!consumerFatalError
+      while (!consumerFatalError && !buildCancel.cancelled
         && consumerInFlight.size < consumerConcurrency
         && consumerPending.length > 0) {
         const work = consumerPending.shift();
@@ -3286,6 +3477,10 @@ export async function runBuild(featureCode, opts = {}) {
       let current = engineResponse;
       let latestNonReady = current?.status !== 'ready' ? current : null;
       while (true) {
+        if (buildCancel.cancelled) {
+          consumerFatalError ??= buildCancel.signal.reason;
+          await drainConsumerFatal();
+        }
         let ordinary;
         try {
           ordinary = await enqueueConsumerReady(current);
@@ -3331,7 +3526,7 @@ export async function runBuild(featureCode, opts = {}) {
       throw error;
     };
     try {
-    while (!isTerminalFlow(response.status)) {
+    while (!isTerminalFlow(response.status) && !buildCancel.cancelled) {
       if (response?.revisionDigest) runRevisionDigest = response.revisionDigest;
       response = await mergeConsumerReady(response);
       const readyStep = response.status === 'ready' ? response.ready?.[0] : null;
@@ -3479,8 +3674,8 @@ export async function runBuild(featureCode, opts = {}) {
           const shipStepResult = response.status === 'ready'
             ? { output: tsShipOutput }
             : shipResult;
-          response = await stratum.stepDone(
-            flowId, stepId, shipStepResult, readyStep?.dispatchToken,
+          response = await callFlowWithCancellation(stratum, 'stepDone', flowId, buildCancel,
+            stepId, shipStepResult, readyStep?.dispatchToken,
           );
           streamWriter.write({
             type: 'build_step_done',
@@ -3519,6 +3714,9 @@ export async function runBuild(featureCode, opts = {}) {
               profile: resolveStepProfile(context.stepProfiles, 'fix')
                 ?? resolveStepProfile(context.stepProfiles, stepId),
               sandboxMode: 'workspace-write',
+              ...(flowTag(flowId, stepId) ? { flow: flowTag(flowId, stepId) } : {}),
+              flowId, buildCancel,
+              buildSignal: buildCancel.signal,
               telemetry: {
                 site: 'review-repair',
                 project_cwd: cwd,
@@ -3538,6 +3736,7 @@ export async function runBuild(featureCode, opts = {}) {
               } catch { /* fail-open */ }
             }
           } catch (err) {
+            if (buildCancel.cancelled) throw err;
             if (err?.usage && typeof context.recordBuildUsage === 'function') {
               try {
                 await context.recordBuildUsage(usagePayload(err.usage, err.usages), {
@@ -3603,6 +3802,9 @@ export async function runBuild(featureCode, opts = {}) {
             reviewMode: isReviewMain,
             confidenceGate: confGateMain,
             lens: response.inputs?.lens_name ?? response.lens_name ?? 'general',
+            ...(flowTag(flowId, stepId) ? { flow: flowTag(flowId, stepId) } : {}),
+            flowId, buildCancel,
+            buildSignal: buildCancel.signal,
             telemetry: {
               site: isReviewMain ? 'review' : 'build-step',
               project_cwd: cwd,
@@ -3617,6 +3819,7 @@ export async function runBuild(featureCode, opts = {}) {
             profile: resolveStepProfile(effectiveProfiles, stepId),
           });
         } catch (err) {
+          if (buildCancel.cancelled) throw err;
           const failedUsage = failureUsageFields(err);
           if (err instanceof UserInterruptError) {
             if (err.action === 'skip') {
@@ -3692,6 +3895,9 @@ export async function runBuild(featureCode, opts = {}) {
                   reviewMode: isReviewMain,
                   confidenceGate: confGateMain,
                   profile: resolveStepProfile(effectiveProfiles, stepId),
+                  ...(flowTag(flowId, stepId) ? { flow: flowTag(flowId, stepId) } : {}),
+                  flowId, buildCancel,
+                  buildSignal: buildCancel.signal,
                   telemetry: {
                     site: 'policy-revision',
                     project_cwd: cwd,
@@ -3739,6 +3945,7 @@ export async function runBuild(featureCode, opts = {}) {
               }
               // The second result stands either way — no further passes.
             } catch (err) {
+              if (buildCancel.cancelled) throw err;
               if (err?.usage && typeof context.recordBuildUsage === 'function') {
                 try {
                   await context.recordBuildUsage(usagePayload(err.usage, err.usages), {
@@ -3942,8 +4149,8 @@ export async function runBuild(featureCode, opts = {}) {
           });
           streamWriter.writeUsage(stepId, stepUsage);
         }
-        response = await stratum.stepDone(
-          flowId, stepId, stepDoneResult, readyStep?.dispatchToken,
+        response = await callFlowWithCancellation(stratum, 'stepDone', flowId, buildCancel,
+          stepId, stepDoneResult, readyStep?.dispatchToken,
         );
         {
           const isEnsureRetry = responseReissuesStep(response, stepId);
@@ -4187,6 +4394,21 @@ export async function runBuild(featureCode, opts = {}) {
         }
 
         const resolveGateWithConsumerMerge = async (requestedOutcome, requestedRationale, resolvedBy) => {
+          let mergeApplied = false;
+          const reverseCancelledMerge = () => {
+            buildCancel.cancel('flow_cancelled');
+            try {
+              consumerMergeArtifacts.restoreMergeBaseline(consumerMergeTransaction, gateAudit, { reason: 'cancelled' });
+            } catch (revertError) {
+              // #mutate cannot persist anything when the restore callback throws.
+              // This separate mutation is the durable indeterminate-tree finding.
+              let journalFailure = '';
+              try { consumerMergeArtifacts.markRollbackFailed(consumerMergeTransaction, revertError); }
+              catch (error) { journalFailure = `; rollback failure journal also failed: ${error.message}`; }
+              throw new MergeAfterCancelError(`merge reversal FAILED after cancel; working tree is indeterminate: ${revertError.message}${journalFailure}`);
+            }
+            throw new MergeAfterCancelError('merge reversed: the run was cancelled while the merge was applying');
+          };
           let outcome = requestedOutcome;
           let rationale = requestedRationale;
           const repairOutcome = gateStep?.gate?.on_revise ? 'revise' : 'kill';
@@ -4220,8 +4442,14 @@ export async function runBuild(featureCode, opts = {}) {
             if (consumerMergePreparationError) {
               repairFor(consumerMergePreparationError);
             } else {
+              // Both fences are outside the repairFor catch: cancellation cannot revise.
+              if (buildCancel.cancelled) {
+                streamWriter.write({ type: 'build_note', note: `merge skipped: build cancelled (${buildCancel.reason})`, flowId });
+                throw new MergeAfterCancelError(`merge refused: build was cancelled at ${buildCancel.at}`);
+              }
               try {
                 await consumerMergeArtifacts.applyMerge(consumerMergeTransaction);
+                mergeApplied = true;
                 try {
                   const changed = execSync(
                     'git diff --name-only HEAD; git ls-files --others --exclude-standard',
@@ -4238,6 +4466,10 @@ export async function runBuild(featureCode, opts = {}) {
                 if (!(error instanceof ConsumerMergeDecisionError)) throw error;
                 repairFor(error);
               }
+              const runCancelled = mergeApplied && !buildCancel.cancelled && await isRunCancelled(stratum, flowId);
+              if (mergeApplied && (buildCancel.cancelled || runCancelled)) {
+                reverseCancelledMerge();
+              }
             }
           }
           // Seam between a completed applyMerge (issuances now journaled `merged`)
@@ -4257,9 +4489,17 @@ export async function runBuild(featureCode, opts = {}) {
             consumerMergeArtifacts.restoreMergeBaseline(consumerMergeTransaction, gateAudit);
           }
 
-          let next = await stratum.gateResolve(
-            flowId, stepId, outcome, rationale, resolvedBy, gateToken,
-          );
+          let next;
+          try {
+            next = await callFlowWithCancellation(stratum, 'gateResolve', flowId, buildCancel,
+              stepId, outcome, rationale, resolvedBy, gateToken,
+            );
+            if (next.status === 'cancelled') buildCancel.cancel('flow_cancelled');
+            if (buildCancel.cancelled) throw buildCancel.signal.reason;
+          } catch (error) {
+            if (mergeApplied && buildCancel.cancelled) reverseCancelledMerge();
+            throw error;
+          }
           if (consumerMergeArtifacts) {
             if (typeof consumerMergeArtifacts.hooks.afterGateResolve === 'function') {
               await consumerMergeArtifacts.hooks.afterGateResolve({
@@ -4270,6 +4510,7 @@ export async function runBuild(featureCode, opts = {}) {
                 response: next,
               });
             }
+            if (mergeApplied && buildCancel.cancelled) reverseCancelledMerge();
             consumerMergeArtifacts.markGateResolved(consumerMergeTransaction, outcome);
             if (outcome === 'approve' || outcome === 'kill' || isTerminalFlow(next.status)) {
               consumerMergeArtifacts.cleanupWorktrees(
@@ -4374,6 +4615,12 @@ export async function runBuild(featureCode, opts = {}) {
               const gateFixResult = await runAndNormalize(undefined, fixPrompt, { step_id: 'review_fix', agent: fixAgent, flow_id: flowId }, {
                 progress, streamWriter, maxDurationMs: STEP_TIMEOUT_MS.review_merge ?? DEFAULT_TIMEOUT_MS,
                 stratum, cwd: agentCwd, sandboxMode: 'workspace-write', profile: resolveStepProfile(effectiveProfiles, 'fix'),
+                // S03-4: tag with `gateStepId`, not the literal `review_fix` this dispatch
+                // carries as its step_id — the run's real step is the gate, and flow.stepId
+                // is audit decoration (the server validates it against nothing).
+                ...(flowTag(flowId, gateStepId) ? { flow: flowTag(flowId, gateStepId) } : {}),
+                flowId, buildCancel,
+                buildSignal: buildCancel.signal,
                 telemetry: {
                   site: 'review-repair',
                   project_cwd: cwd,
@@ -4393,6 +4640,7 @@ export async function runBuild(featureCode, opts = {}) {
                 } catch { /* fail-open */ }
               }
             } catch (err) {
+              if (buildCancel.cancelled) throw err;
               if (err?.usage && typeof context.recordBuildUsage === 'function') {
                 try {
                   await context.recordBuildUsage(usagePayload(err.usage, err.usages), {
@@ -4482,13 +4730,20 @@ export async function runBuild(featureCode, opts = {}) {
           if (serverUp) {
             gateId = await visionWriter.createGate(flowId, stepId, itemId, { ...gateExtras, policyMode: 'gate', round });
             console.log('Gate delegated to web UI. Waiting for resolution...');
-            const resolved = await pollGateResolution(visionWriter, gateId);
+            let resolved;
+            try {
+              resolved = await pollGateResolution(visionWriter, gateId, 2000, buildCancel.signal);
+            } catch (error) {
+              await confirmCancellation(error, { stratum, flowId, buildCancel });
+              throw error;
+            }
             if (resolved) {
               outcome = resolved.outcome;
               rationale = resolved.comment ?? '';
             } else {
               const result = await promptGate(gateDispatch, {
                 ...(opts.gateOpts ?? {}),
+                signal: buildCancel.signal,
                 artifact: context.cwd,
                 askAgent,
                 gateExtras,
@@ -4500,6 +4755,7 @@ export async function runBuild(featureCode, opts = {}) {
             gateId = await visionWriter.createGate(flowId, stepId, itemId, { ...gateExtras, policyMode: 'gate', round });
             const result = await promptGate(gateDispatch, {
               ...(opts.gateOpts ?? {}),
+              signal: buildCancel.signal,
               artifact: context.cwd,
               askAgent,
               gateExtras,
@@ -4566,16 +4822,26 @@ export async function runBuild(featureCode, opts = {}) {
       consumerArtifacts.cleanupWorktrees('run terminalized');
     }
 
+    if (response.status === 'cancelled') buildCancel.cancel('flow_cancelled');
+
     // Flow complete — write terminal state (file retained per STRAT-COMP-4 contract).
     // COMP-COMPLETION-GATE slice 2: set when the flow completed and the feature is
     // eligible to be completed — the actual completion runs after the health gate.
     let pendingCompletion = null;
-    if (response.status === 'completed') buildStatus = 'complete';
-    if ((response.status === 'failed' || response.status === 'budget_exhausted') && !killedByGate) {
+    if (!buildCancel.cancelled && response.status === 'completed') buildStatus = 'complete';
+    if (!buildCancel.cancelled && (response.status === 'failed' || response.status === 'budget_exhausted') && !killedByGate) {
       buildStatus = 'failed';
       terminalFailureReason = response.failure?.reason ?? null;
     }
-    if (response.status === 'completed' && buildStatus === 'complete') {
+    if (buildCancel.teardown) {
+      // A successful final stepDone can race SIGINT. The teardown still owns
+      // terminal state; retain aborted for history, stream closure and actuals.
+      buildStatus = 'aborted';
+    } else if (buildCancel.cancelled) {
+      buildStatus = 'aborted';
+      terminalFailureReason = buildCancel.reason;
+      await terminalizeCancelledBuild({ dataDir, buildIdentity, visionWriter, itemId, failureReason: buildCancel.reason });
+    } else if (response.status === 'completed' && buildStatus === 'complete') {
       console.log('\nBuild complete.');
       // COMP-COMPLETION-GATE slice 2: the COMPLETION does not happen here.
       //
@@ -4640,9 +4906,13 @@ export async function runBuild(featureCode, opts = {}) {
     // for the history record — health-gate failures have no failed step, so
     // the lastFailedStep-derived failureReason would otherwise be generic.
     let healthDowngradeReason = null;
-    if (streamWriter) {
+    if (streamWriter && !buildCancel.teardown && !buildCancel.cancelled) {
+      const checkHealthOwnership = () => {
+        if (buildCancel.teardown || buildCancel.cancelled) throw buildCancel.signal.reason;
+      };
       try {
         // Runtime errors signal — accumulated across all steps
+        checkHealthOwnership();
         if (allViolations.length > 0) {
           buildSignals.runtime_errors = allViolations;
         } else if (!buildSignals.runtime_errors) {
@@ -4657,6 +4927,7 @@ export async function runBuild(featureCode, opts = {}) {
         // chain + mtimes, so it needs no marker to be written first.
         try {
           const { findStaleArtifacts } = await import('./lineage.js');
+          checkHealthOwnership();
           buildSignals.doc_freshness = findStaleArtifacts(resolveItemDir(featureCode));
         } catch { /* staleness check is optional — skip on error */ }
 
@@ -4669,6 +4940,7 @@ export async function runBuild(featureCode, opts = {}) {
         // lifecycle-writer surface that materialises wasGeneratedBy/wasDerivedFrom.
         try {
           const { stampFeatureLineage } = await import('./lineage.js');
+          checkHealthOwnership();
           stampFeatureLineage(resolveItemDir(featureCode));
         } catch { /* lineage stamping is optional — skip on error */ }
 
@@ -4688,10 +4960,12 @@ export async function runBuild(featureCode, opts = {}) {
         );
 
         // Emit to build stream
+        checkHealthOwnership();
         streamWriter.writeHealthScore(score, breakdown, missing);
 
         // Persist to history
         try {
+          checkHealthOwnership();
           recordScore(cwd, { featureCode, phase: buildStatus, score, breakdown });
         } catch (err) {
           console.warn(`[health] Failed to persist score: ${err.message}`);
@@ -4701,6 +4975,7 @@ export async function runBuild(featureCode, opts = {}) {
         // If health score is below the configured threshold, mark the build as failed
         // so downstream consumers (vision item status, exit code) reflect the rejection.
         const threshold = healthSettings.gate_threshold;
+        checkHealthOwnership();
         if (typeof threshold === 'number' && score < threshold) {
           streamWriter.write({
             type: 'gate_health_rejection',
@@ -4711,12 +4986,14 @@ export async function runBuild(featureCode, opts = {}) {
           });
           console.warn(`  [health] Build health score ${score} is below gate threshold ${threshold} — marking build as failed`);
           // Enforce: downgrade build status so the build is reported as failed
+          checkHealthOwnership();
           buildStatus = 'failed';
           // COMP-MOBILE-1-1: re-persist the downgrade to active-build.json so the
           // file watcher re-broadcasts buildState over /ws/vision. Without this,
           // the terminal write above already said 'complete' and clients never
           // learn the build actually failed (mobile compensated via history).
           // Identity-guarded: no-ops if a concurrent build replaced the file.
+          checkHealthOwnership();
           const downgraded = persistHealthGateDowngrade(dataDir, {
             score,
             threshold,
@@ -4730,7 +5007,7 @@ export async function runBuild(featureCode, opts = {}) {
         console.log(`  Health score: ${score}/100 (${Object.keys(breakdown).length} dimensions scored)`);
       } catch (err) {
         // Non-fatal — health scoring never blocks the build
-        console.warn(`[health] Score computation failed: ${err.message}`);
+        if (!buildCancel.teardown && !buildCancel.cancelled) console.warn(`[health] Score computation failed: ${err.message}`);
       }
     }
 
@@ -4741,7 +5018,7 @@ export async function runBuild(featureCode, opts = {}) {
     // a health-rejected build completes nothing: no completion record, no
     // COMPLETE status, no vision completion, no guard transition.
     // ---------------------------------------------------------------------
-    if (pendingCompletion && buildStatus === 'complete') {
+    if (pendingCompletion && !buildCancel.teardown && !buildCancel.cancelled && buildStatus === 'complete') {
       const ev = context.completionEvidence || {};
       const acc = readBuildAccumulator(cwd, featureCode);
       // Persisted, because it survives a resume; the in-memory value wins when
@@ -4829,6 +5106,10 @@ export async function runBuild(featureCode, opts = {}) {
     // the COMP-HEALTH gate above may have downgraded buildStatus to 'failed'.
     // Assembled from the in-memory build context for THIS run (never re-read
     // active-build.json, which is last-writer-wins across concurrent builds).
+    if (buildCancel.teardown || buildCancel.cancelled) {
+      buildStatus = 'aborted';
+      terminalFailureReason = buildCancel.reason;
+    }
     if (['complete', 'aborted', 'failed', 'killed'].includes(buildStatus)) {
       const failureReason = buildFailureReason({
         buildStatus,
@@ -4929,10 +5210,18 @@ export async function runBuild(featureCode, opts = {}) {
     // File retained on disk per STRAT-COMP-4 — overwritten on next build start
 
   } catch (err) {
-    buildStatus = 'failed';
-    const failureReason = err?.message ?? 'Build failed';
+    // COMP-BUILD-CANCEL §3.6: a pending teardown is the single terminal owner. Stand down —
+    // do NOT terminalize (two writers, one record) and do NOT await it (the teardown is
+    // waiting on `drained`, which this rethrow is what releases).
+    if (buildCancel.teardown) {
+      buildStatus = 'aborted';
+      throw err;
+    }
+    buildStatus = buildCancel.cancelled ? 'aborted' : 'failed';
+    const failureReason = buildCancel.cancelled ? buildCancel.reason : (err?.message ?? 'Build failed');
     try {
       await terminalizeThrownBuild({
+        buildCancel, buildIdentity,
         cwd,
         dataDir,
         cfg,
@@ -4963,13 +5252,26 @@ export async function runBuild(featureCode, opts = {}) {
     if (streamWriter) {
       streamWriter.close(buildStatus, buildCostTotals);
     }
-    if (signalHandler) {
-      process.removeListener('SIGINT', signalHandler);
-      process.removeListener('SIGTERM', signalHandler);
+    // §3.6: the teardown removes the listeners itself, AFTER its writes. Removing them here
+    // while it is pending would send a second Ctrl-C to the default handler, killing the
+    // process mid-write.
+    if (signalHandler && !buildCancel.teardown) {
+      process.removeListener('SIGINT', signalHandler.listeners.onSigint);
+      process.removeListener('SIGTERM', signalHandler.listeners.onSigterm);
     }
     progress.finish();
-    await stratum.close();
+    // A pending teardown may still have a `flowCancel` in flight over this client; closing it
+    // underneath would abandon the cancel. The teardown exits the process, so the deferred
+    // close is a courtesy, not a leak.
+    if (buildCancel.teardown) {
+      void buildCancel.teardown.then(() => stratum.close()).catch(() => undefined);
+    } else {
+      await stratum.close();
+    }
     runtimeResourcesFinalized = true;
+    // §3.6: release the teardown's bounded wait — this build's resources are now closed and
+    // finalizeBuildAttempt has emitted its actuals, so the teardown's writes cannot race it.
+    buildCancel.resolveDrained();
     if (actualsError) throw actualsError;
   }
   } finally {
@@ -4979,15 +5281,30 @@ export async function runBuild(featureCode, opts = {}) {
       try {
         if (!runtimeResourcesFinalized) {
           if (streamWriter) streamWriter.close(buildStatus);
-          if (signalHandler) {
-            process.removeListener('SIGINT', signalHandler);
-            process.removeListener('SIGTERM', signalHandler);
+          if (signalHandler && !buildCancel.teardown) {
+            process.removeListener('SIGINT', signalHandler.listeners.onSigint);
+            process.removeListener('SIGTERM', signalHandler.listeners.onSigterm);
           }
           progress?.finish();
-          if (stratum) await stratum.close();
+          if (stratum && !buildCancel.teardown) await stratum.close();
           runtimeResourcesFinalized = true;
+          buildCancel.resolveDrained();
+        }
+        // §3.6: join the teardown so the CLI cannot exit out from under it. The bound is
+        // DERIVED from the teardown's own two deadlines (C46), never chosen.
+        if (buildCancel.teardown) {
+          await withDeadline(buildCancel.teardown, teardownJoinMs).catch(() => undefined);
         }
       } finally {
+        // S03-5b: a crashed build must leave no stale handle behind.
+        // A join deadline is not settlement. Keep the handle visible to the CLI
+        // until teardown finishes, even when this outer finally stops waiting.
+        if (buildCancel.teardown) {
+          const unregister = () => unregisterBuildCancel(registeredFlowId);
+          void buildCancel.teardown.then(unregister, unregister);
+        } else {
+          unregisterBuildCancel(registeredFlowId);
+        }
         // COMP-MCP-MIGRATION-1: restore COMPOSE_BUILD_ID env to its prior value
         // (or unset) so subsequent processes / tests don't inherit a stale UUID.
         _restoreBuildIdEnv();
@@ -5654,18 +5971,22 @@ function syncStepHistory(dataDir, stepHistory) {
  * @param {VisionWriter} visionWriter
  * @param {string} gateId
  * @param {number} [intervalMs=2000]
+ * @param {AbortSignal} [signal]
  * @returns {Promise<object|null>} resolved gate or null (server lost mid-poll)
  */
-async function pollGateResolution(visionWriter, gateId, intervalMs = 2000) {
+export async function pollGateResolution(visionWriter, gateId, intervalMs = 2000, signal) {
   let consecutiveFailures = 0;
   while (true) {
+    signal?.throwIfAborted();
     try {
       const gate = await visionWriter.getGate(gateId, { requireServer: true });
+      signal?.throwIfAborted();
       consecutiveFailures = 0;
       if (!gate) throw new Error(`Gate ${gateId} not found (404)`);
       if (gate.status === 'expired') throw new Error(`Gate ${gateId} expired`);
       if (gate.status !== 'pending') return gate;
     } catch (err) {
+      signal?.throwIfAborted();
       if (err instanceof ServerUnreachableError) {
         consecutiveFailures++;
         if (consecutiveFailures >= 3) {
@@ -5676,7 +5997,7 @@ async function pollGateResolution(visionWriter, gateId, intervalMs = 2000) {
         throw err;
       }
     }
-    await new Promise(r => setTimeout(r, intervalMs));
+    await sleep(intervalMs, undefined, { signal });
   }
 }
 
@@ -5796,51 +6117,195 @@ function loadFeatureDescription(featureDir, featureCode) {
   return featureCode;
 }
 
+const ABORT_TERMINAL_STATUSES = new Set(['complete', 'aborted', 'killed', 'failed']);
+
+function abortSetting(name, fallback) {
+  const value = Number(process.env[name] ?? fallback);
+  return Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+}
+
+function abortRefusal(error) {
+  if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT', 'FLOW_NOT_FOUND'].includes(error?.code)) return error;
+  if (isUnknownFlowError(error)) {
+    return { code: 'FLOW_NOT_FOUND', reason: 'flow_not_found', status: null, flowSettled: false, agents: null };
+  }
+  return asTransportRefusal(error);
+}
+
+function reportAbort(result) {
+  console.log(`Flow status: ${result.status ?? 'unknown'} (settled: ${result.flowSettled}).`);
+  if (result.reason) console.log(`Reason: ${result.reason}${result.holderPid == null ? '' : `; holderPid: ${result.holderPid}`}.`);
+  for (const [counter, count] of Object.entries(result.agents ?? {})) {
+    if (count > 0) console.log(`Agents ${counter}: ${count}.`);
+  }
+  console.log(`Driver: ${result.driverMode}; signalled: ${result.driverSignalled}; exited: ${result.driverExited}; terminal writer: ${result.terminalWriter}.`);
+  console.log(result.ok ? 'Build aborted.' : `Build NOT aborted — ${result.reason}.`);
+  return result;
+}
+
+/** Retry only pre-settle lock refusals; a settled timeout gets one idempotent sweep. */
+async function cancelAbortFlow(stratum, flowId, result) {
+  const retries = abortSetting('COMPOSE_ABORT_RETRIES', 2);
+  let lockRetries = 0;
+  let reswept = false;
+  let settled = null;
+  for (;;) {
+    result.attempts++;
+    let outcome;
+    try {
+      outcome = await stratum.flowCancel(flowId);
+    } catch (error) {
+      outcome = abortRefusal(error);
+    }
+    // Once durable settlement is known, a later broken pipe cannot undo it. Keep
+    // the last settled counters/status and report the failed re-sweep separately.
+    if (settled && outcome.flowSettled !== true) {
+      console.log(`Re-sweep failed: ${outcome.reason ?? outcome.code ?? 'transport'}.`);
+      return settled;
+    }
+    if (outcome.flowSettled === true) {
+      settled = outcome;
+      if (outcome.code === 'CANCELLATION_TEARDOWN_TIMEOUT' && !reswept) {
+        reswept = true;
+        console.log('Flow settled; re-sweeping agent teardown once.');
+        continue;
+      }
+      return outcome;
+    }
+    if (outcome.code === 'CANCELLATION_UNCONFIRMED' && outcome.reason === 'run_lock_held'
+      && Object.values(outcome.agents ?? {}).every(count => count === 0) && lockRetries < retries) {
+      lockRetries++;
+      console.log(`Cancel lock held${outcome.holderPid == null ? '' : ` by ${outcome.holderPid}`}; retry ${lockRetries}/${retries}.`);
+      await new Promise(resolve => setTimeout(resolve, 100));
+      continue;
+    }
+    return outcome;
+  }
+}
+
+/** The driver owns all terminal writes while it can still finish them itself. */
+async function waitForAbortDriver(dataDir, active, handle) {
+  const deadline = Date.now() + abortSetting('COMPOSE_ABORT_DRIVER_WAIT_MS', 20000);
+  for (;;) {
+    const claim = claimActiveBuild(dataDir, active);
+    if (!claim.ok) return claim;
+    if (ABORT_TERMINAL_STATUSES.has(claim.record.status)
+      && (!handle || !lookupBuildCancel(active.flowId))) {
+      return { ...claim, exited: true };
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { ...claim, exited: false };
+    await new Promise(resolve => setTimeout(resolve, Math.min(50, remaining)));
+  }
+}
+
 export async function abortBuild(dataDir, featureCode, cwd, opts = {}) {
   const active = readActiveBuild(dataDir);
+  const result = {
+    ok: false, flowId: active?.flowId ?? null, status: null, flowSettled: false,
+    acknowledged: false, code: null, reason: null, holderPid: null, agents: null,
+    attempts: 0, driverMode: 'none', driverSignalled: false, driverExited: false,
+    terminalWriter: 'none', localCleanup: false,
+  };
+  const refuse = reason => reportAbort({ ...result, ok: false, reason, terminalWriter: 'none', localCleanup: false });
   if (!active) {
     console.log('No active build to abort.');
-    return;
+    return refuse('no_active_build');
   }
-
   if (featureCode && active.featureCode !== featureCode) {
     console.log(`Active build is for ${active.featureCode}, not ${featureCode}.`);
-    return;
+    return refuse('feature_mismatch');
   }
+  if (ABORT_TERMINAL_STATUSES.has(active.status)) return refuse(`already_${active.status}`);
 
+  const handle = lookupBuildCancel(active.flowId);
+  const foreignPid = !handle && active.pid && active.pid !== process.pid
+    && active.status === 'running' && isProcessAlive(active.pid) ? active.pid : null;
+  result.driverMode = handle ? 'in-process' : foreignPid ? 'foreign-pid' : 'none';
   console.log(`Aborting build for ${active.featureCode}...`);
 
-  // Probe the persisted TS run before abandoning the local build. Foreground TS
-  // runs advance only through this client, so closing it prevents more dispatch.
-  const stratum = opts.stratum ?? new StratumMcpClient();
-  const connection = resolveStratumMcpConnection(cwd);
+  // Configuration errors (notably the retired Python pin) still reject BEFORE
+  // connecting. Only a connection/transport failure belongs in the outcome table.
+  const connection = active.flowId ? resolveStratumMcpConnection(cwd) : null;
+  const stratum = connection ? (opts.stratum ?? new StratumMcpClient()) : null;
   try {
-    await stratum.connect(connection);
-    const audit = await stratum.audit(active.flowId);
-    if (isTerminalFlow(audit.status)) {
-      console.log(`Flow already ${audit.status}.`);
+    let outcome = { flowSettled: true };
+    if (stratum) {
+      try {
+        await stratum.connect({ ...connection,
+          env: { ...process.env, STRATUM_CANCEL_LOCK_WAIT_MS: String(abortSetting('COMPOSE_ABORT_LOCK_WAIT_MS', 10000)) },
+        });
+      } catch (error) {
+        outcome = asTransportRefusal(error);
+      }
+      if (!outcome.code) outcome = await cancelAbortFlow(stratum, active.flowId, result);
+    }
+    for (const key of ['status', 'code', 'reason', 'holderPid', 'agents']) result[key] = outcome[key] ?? null;
+    result.flowSettled = outcome.flowSettled === true;
+    result.acknowledged = outcome.acknowledged === true;
+    const alreadyTerminal = !outcome.code && ['completed', 'failed', 'budget_exhausted'].includes(outcome.status)
+      && outcome.reason === `already_${outcome.status}`;
+    if (!result.flowSettled && !alreadyTerminal) return refuse(result.reason ?? 'transport');
+
+    // C41/C48: the awaits above may have handed ownership to a different build.
+    // Claim BEFORE even cancelling the local controller or signalling a driver.
+    let claim = claimActiveBuild(dataDir, active);
+    if (!claim.ok) return refuse(claim.reason);
+    if (result.flowSettled) {
+      if (handle) handle.cancel('abort');
+      else if (foreignPid && isProcessAlive(foreignPid)) {
+        try { process.kill(foreignPid, 'SIGTERM'); result.driverSignalled = true; }
+        catch (error) {
+          if (error.code !== 'ESRCH') console.log(`Driver SIGTERM failed: ${error.code ?? error.message}.`);
+        }
+      }
+    }
+    if (result.driverMode !== 'none') {
+      const driver = await waitForAbortDriver(dataDir, active, handle);
+      if (!driver.ok) return refuse(driver.reason);
+      if (driver.exited) {
+        result.driverExited = true;
+        result.terminalWriter = 'driver';
+        result.ok = ['aborted', 'killed'].includes(driver.record.status);
+        result.localCleanup = result.ok;
+        if (!result.ok) result.reason = `already_${driver.record.status}`;
+        return reportAbort(result);
+      }
     }
-  } catch {
-    // A missing/unreadable run does not prevent local cleanup.
-  } finally {
-    await stratum.close();
-  }
-
-  // Update vision state
-  const visionWriter = new VisionWriter(dataDir);
-  const item = await visionWriter.findFeatureItem(active.featureCode);
-  const itemId = item?.id;
-  if (itemId) {
-    await visionWriter.updateItemStatus(itemId, 'killed');
-  }
 
-  // Write terminal state (file retained per STRAT-COMP-4 contract)
-  writeActiveBuild(dataDir, { ...active, status: 'aborted', completedAt: new Date().toISOString() });
-  const accumulator = readBuildAccumulator(cwd, active.featureCode);
-  if (accumulator) {
-    emitBuildActuals(cwd, accumulator, 'aborted');
+    // Re-claim after the bounded wait, covering vision + state + actuals as one
+    // cleanup. The aborter never restamps the driver's pid.
+    claim = claimActiveBuild(dataDir, active);
+    if (!claim.ok) return refuse(claim.reason);
+    if (ABORT_TERMINAL_STATUSES.has(claim.record.status)) return refuse(`already_${claim.record.status}`);
+    const visionWriter = new VisionWriter(dataDir);
+    const item = await visionWriter.findFeatureItem(active.featureCode);
+    claim = claimActiveBuild(dataDir, active);
+    if (!claim.ok) return refuse(claim.reason);
+    if (ABORT_TERMINAL_STATUSES.has(claim.record.status)) return refuse(`already_${claim.record.status}`);
+    if (item?.id) {
+      try { await killOwnedBuildVision(visionWriter, item.id, () => claimActiveBuild(dataDir, active)); }
+      catch (error) {
+        if (['ownership_lost', 'ownership_unverifiable'].includes(error.reason)) return refuse(error.reason);
+        throw error;
+      }
+    }
+    claim = claimActiveBuild(dataDir, active);
+    if (!claim.ok) return refuse(claim.reason);
+    if (ABORT_TERMINAL_STATUSES.has(claim.record.status)) return refuse(`already_${claim.record.status}`);
+    writeActiveBuild(dataDir, { ...claim.record, status: 'aborted', completedAt: new Date().toISOString() }, { stampPid: false });
+    const accumulator = readBuildAccumulator(cwd, active.featureCode);
+    if (accumulator) emitBuildActuals(cwd, accumulator, 'aborted');
+    result.ok = true;
+    result.localCleanup = true;
+    result.terminalWriter = 'abort';
+    return reportAbort(result);
+  } finally {
+    if (stratum) {
+      try { await stratum.close(); }
+      catch (error) { console.warn(`Abort client close failed: ${error.message}`); }
+    }
   }
-  console.log('Build aborted.');
 }
 
 /** Optional revision failures keep the draft; only user control or uncertain teardown stops the build. */