@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/verification/telemetry-emit.js

@@ -0,0 +1,254 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+const nodeFs = require('node:fs');
+const { SAFE_TOKEN, telemetryOff, TelemetryWriter } = require('../trace/telemetry.js');
+const { resolveRunsLocation } = require('../trace/ledger.js');
+const { DISPATCH_RUN_ID } = require('../dispatch/store.js');
+const { levelOf, v0Applies, v0Enabled, loadVerificationRegistry } = require('./registry.js');
+
+let defaultRegistry      = null;
+function getDefaultRegistry()      {
+  if (!defaultRegistry) {
+    try {
+      defaultRegistry = loadVerificationRegistry();
+    } catch {
+      defaultRegistry = null;
+    }
+  }
+  return defaultRegistry;
+}
+
+
+/**
+ * Verify telemetry (088 C.1, IC-006, DD-4): one `verify.run` line per verify run, one `verify.tier`
+ * per report tier and one `verify.check` per check, written through `TelemetryWriter`.
+ *
+ * The report is never touched: timing comes from the runner's `metrics` WeakMap (keyed by each
+ * check result object), so `verify --json` is the same bytes with telemetry on, off or faulted
+ * (FR-002, NFR-005, NFR-007). Records are built with every design field; the writer keeps only
+ * the keys `core/registry/telemetry.json` declares for the kind, so a later phase widens the lines
+ * by declaring keys, not by changing this module. Fields whose source does not exist yet are null:
+ * `level` until G.1, `v0` until G.2, `check_key` and `shared` until E.2.
+ *
+ * Where: `DOFLOW_CONFIG_DIR` when set, even over a nearer store; else the nearest `.doflow` above
+ * `start` that holds `state/runs`, so a `.doflow` without a ledger (one left by an older runtime's
+ * cwd-rooted verification logs) is walked past. With no project store nothing is written: no global
+ * fallback, so the lines stay under the project's state (NFR-006), as the bridge's hook lines do.
+ */
+
+                                              
+
+/** ISO 8601 with ms for an epoch-ms number, else undefined (the writer then stamps its own clock). */
+function isoAt(ms         )                     {
+  return typeof ms === 'number' && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+}
+
+/**
+ * The records for one verify run, in write order: run, then each tier followed by its checks.
+ * Pure; a value that fails its registry type is nulled by the writer, never here.
+ * @param {Object} input
+ * @param {Object} input.report a `runContract` report, or the dispatch runner's `{status, startedAt, finishedAt, tiers: []}`
+ * @param {WeakMap} [input.metrics] check result → `{ startedAt, durationMs }`
+ * @param {{verifyId: string, source: string, taskId: *, risk: *, exitCode: *}} input.ctx
+ * @returns {Array<Object>}
+ */
+function buildVerifyRecords({ report, metrics = null, ctx }     )        {
+  const verifyId = ctx.verifyId;
+  const runStart = Date.parse(report.startedAt);
+  const runEnd = Date.parse(report.finishedAt);
+  // Timestamp of a record with no start of its own (a tier with no check, an in-run duplicate):
+  // the latest instant seen so far, so line timestamps never go backwards.
+  let cursor = Number.isFinite(runStart) ? runStart : undefined;
+  // Check stamps come from ONE wall-clock base plus the monotonic clock the durations already use: the
+  // first executed check pins `anchor`, and a later check is stamped anchor.wall + (its monotonic start -
+  // anchor.mono), so a wall-clock step mid-run neither reorders checks nor collapses them onto one instant.
+  // A check with no monotonic start (reused, or a clock that could not be read) keeps its wall start.
+  let anchor                                        = null;
+  // The latest timestamp written so far: a record with no start of its own sits at the cursor, which
+  // advances by a rounded duration and can pass the next real start by a millisecond; no stamp goes back.
+  let latest = cursor;
+  const stamp = (ms                    )                     => {
+    if (ms === undefined) return latest;
+    latest = latest === undefined ? ms : Math.max(latest, ms);
+    return latest;
+  };
+  let firstStamp                    ;
+  let checksRun = 0;
+  const body        = [];
+  const commandKeys = new Map                       ();
+
+  for (const tier of Array.isArray(report.tiers) ? report.tiers : []) {
+    const checks        = [];
+    let tierMs                = null;
+    let tierStart                    ;
+    for (const check of Array.isArray(tier.checks) ? tier.checks : []) {
+      const timing = check && typeof check === 'object' && metrics ? metrics.get(check) : undefined;
+      let durationMs                = null;
+      let at = cursor;
+      let checkKey                = null;
+      let shared                = null;
+      let sharedRef                = null;
+      let tests                = null;
+      let testsFailed                = null;
+      let cpuMs                = null;
+      let resourceBasis                = null;
+      let failedFirst                = null;
+
+      if (check && check.status === 'NOT_RUN') {
+        durationMs = null;
+        failedFirst = null;
+      } else if (timing) {
+        // A follower waited on another run and a reused check (089 IC-007) read a record: neither executed.
+        if (timing.shared !== 'follower' && timing.shared !== 'reused') checksRun += 1;
+        if (Number.isFinite(timing.startedAt)) {
+          at = timing.startedAt;
+          if (Number.isFinite(timing.startedMonoMs)) {
+            anchor = anchor ?? { wall: timing.startedAt, mono: timing.startedMonoMs };
+            at = Math.round(anchor.wall + (timing.startedMonoMs - anchor.mono));
+            // Nothing but the run line is written yet when the first check lands before it: lower the floor.
+            if (firstStamp === undefined) { firstStamp = at; if (latest !== undefined && at < latest) latest = at; }
+          }
+        }
+        if (Number.isFinite(timing.durationMs)) durationMs = Math.round(timing.durationMs);
+        if (at !== undefined) cursor = Math.max(cursor ?? at, at + (durationMs ?? 0));
+        checkKey = timing.checkKey ?? null;
+        shared = timing.shared ?? 'none';
+        sharedRef = timing.sharedRef ?? null;
+        tests = typeof timing.tests === 'number' ? timing.tests : null;
+        testsFailed = typeof timing.testsFailed === 'number' ? timing.testsFailed : null;
+        cpuMs = typeof timing.cpuMs === 'number' ? timing.cpuMs : null;
+        resourceBasis = timing.resourceBasis ?? null;
+        failedFirst = timing.failedFirst ?? (check?.failedFirst ? (check.failedFirst.status === 'FAIL' ? 'fail' : 'pass') : 'none');
+        if (check && check.command && checkKey) {
+          commandKeys.set(check.command, checkKey);
+        }
+      } else if (check && check.deduplicated) {
+        durationMs = 0; // reused the result of an identical check earlier in this run (S-10)
+        shared = 'in-run';
+        failedFirst = 'none';
+        checkKey = (check.command && commandKeys.get(check.command)) ?? null;
+      } else if (check) {
+        failedFirst = check.failedFirst ? (check.failedFirst.status === 'FAIL' ? 'fail' : 'pass') : 'none';
+      }
+      if (durationMs !== null) tierMs = (tierMs ?? 0) + durationMs;
+      at = stamp(at);
+      if (tierStart === undefined) tierStart = at;
+      checks.push({
+        kind: 'verify.check',
+        timestamp: isoAt(at),
+        verify_id: verifyId,
+        tier: tier.id,
+        status: check ? check.status : null,
+        exit_code: check ? (check.exitCode ?? null) : null,
+        duration_ms: durationMs,
+        tests,
+        tests_failed: testsFailed,
+        cpu_ms: cpuMs,
+        resource_basis: resourceBasis,
+        check_key: checkKey,
+        shared,
+        shared_ref: sharedRef,
+        failed_first: failedFirst,
+      });
+    }
+    const selection = tier.selection || {};
+    body.push({
+      kind: 'verify.tier',
+      timestamp: isoAt(tierStart ?? stamp(cursor)),
+      verify_id: verifyId,
+      tier: tier.id,
+      status: tier.status,
+      duration_ms: tierMs, // derived: the sum of its checks (IC-006 basis derived-sum)
+      selection_basis: selection.basis ?? null,
+      selected: selection.selectedCount ?? null,
+      total: selection.totalCount ?? null,
+      fallback: selection.fallback ?? null,
+    }, ...checks);
+  }
+
+  const dispatchRun = ctx.dispatchRun ?? ctx.dispatch_run;
+  const reg = ctx.registry || getDefaultRegistry();
+  const risk = ctx.risk ?? null;
+  const level = ctx.level ?? (risk ? levelOf(reg, risk) : null);
+  const applies = ctx.v0Applies !== undefined ? Boolean(ctx.v0Applies) : (risk ? v0Applies(reg, risk) : false);
+
+  let v0                      = null;
+  if (ctx.source === 'dispatch') {
+    v0 = null;
+  } else if (ctx.v0 === 'off' || ctx.v0 === false) {
+    v0 = 'off';
+  } else if (ctx.v0 === 'on' || ctx.v0 === true) {
+    v0 = applies ? 'on' : null;
+  } else if (ctx.v0 === null) {
+    v0 = null;
+  } else {
+    const isEnabled = v0Enabled(ctx.env || process.env, ctx.configDir);
+    if (!isEnabled) {
+      v0 = 'off';
+    } else {
+      v0 = applies ? 'on' : null;
+    }
+  }
+
+  const run = {
+    kind: 'verify.run',
+    timestamp: isoAt(firstStamp !== undefined && Number.isFinite(runStart) ? Math.min(runStart, firstStamp) : runStart),
+    verify_id: verifyId,
+    source: ctx.source,
+    task: typeof ctx.taskId === 'string' && SAFE_TOKEN.test(ctx.taskId) ? ctx.taskId : null,
+    dispatch_run: ctx.source === 'dispatch' && typeof dispatchRun === 'string' && DISPATCH_RUN_ID.test(dispatchRun)
+      ? dispatchRun
+      : null,
+    risk,
+    level,
+    status: report.status,
+    exit_code: ctx.exitCode ?? null,
+    // Wall time between the report's own stamps: the engine clock, not a monotonic one.
+    duration_ms: Number.isFinite(runStart) && Number.isFinite(runEnd) ? Math.max(0, runEnd - runStart) : null,
+    checks_run: checksRun,
+    v0,
+  };
+  return [run, ...body];
+}
+
+/**
+ * The directory the writer should walk up from, or null when no project store exists.
+ * @param {string} [start]
+ * @param {Object} env
+ * @param {Object} fsImpl
+ * @returns {string|null}
+ */
+function storeStart(start                    , env     , fsImpl     )                {
+  const at = resolveRunsLocation({ start, env, fsImpl, containing: path.join('state', 'runs') });
+  if (at.origin === 'DOFLOW_CONFIG_DIR') return start || process.cwd(); // the writer reads the same variable
+  return at.origin === 'project' ? path.dirname(at.configDir) : null;
+}
+
+/**
+ * Writes the verify lines for one run. Never throws; any fault writes nothing (NFR-005).
+ * @param {Object} input
+ * @param {Object} input.report
+ * @param {WeakMap} [input.metrics]
+ * @param {{source: 'verb'|'dispatch', taskId: *, risk: *, exitCode: *}} input.ctx
+ * @param {Object} [input.env=process.env]
+ * @param {string} [input.start] the verify's working directory (walk-up origin)
+ * @param {Function} [input.now] writer clock; test seam
+ * @param {Object} [input.fsImpl] test seam
+ */
+function emitVerifyTelemetry({ report, metrics = null, ctx, env = process.env, start, now, fsImpl = nodeFs }     )       {
+  try {
+    if (telemetryOff(env)) return;
+    const from = storeStart(start, env, fsImpl);
+    if (from === null) return;
+    const records = buildVerifyRecords({ report, metrics, ctx: { env: ctx?.env || env, ...ctx, verifyId: crypto.randomBytes(8).toString('hex') } });
+    new TelemetryWriter({ env, fsImpl, start: from, ...(now ? { now } : {}) }).write(records);
+  } catch {
+    // Telemetry changes no outcome (FR-002, NFR-005).
+  }
+}
+
+module.exports = { buildVerifyRecords, emitVerifyTelemetry };

package/src/runtime/verification/test-selection.js

@@ -20,7 +20,7 @@ const nodeFs = require('node:fs');
 /** The guard lane of a `node --test` repository: structural checks that run with every selection. */
 const GUARD_DIR = 'test/guards';
 
-const NODE_TEST_FILE = /\.test\.(?:js|mjs|cjs)$/;
+const NODE_TEST_FILE = /\.test\.(?:js|mjs|cjs|ts)$/;
 const PYTEST_FILE = /(?:^|\/)(?:test_[^/]*|[^/]*_test)\.py$/;
 
 const SKIPPED_DIRS = new Set(['node_modules', '.git', '.venv', 'venv', '__pycache__']);
@@ -97,14 +97,37 @@ function conventionFor(found     )      {
       roots,
       isTest: (file        ) => NODE_TEST_FILE.test(file) && underRoot(file),
       guardDir: roots.some((r        ) => GUARD_DIR === r || GUARD_DIR.startsWith(`${r}/`)) ? GUARD_DIR : null,
+      found,
     };
   }
   if (found && found.source === 'pyproject.toml') {
-    return { basis: 'changed-test-files', roots: ['.'], isTest: (file        ) => PYTEST_FILE.test(file), guardDir: null };
+    return { basis: 'changed-test-files', roots: ['.'], isTest: (file        ) => PYTEST_FILE.test(file), guardDir: null, found };
   }
   return null;
 }
 
+/**
+ * Walks the test files for the toolchain described by `found`.
+ * Returns sorted unique repo-relative paths of regular files that satisfy `convention.isTest`.
+ * @param {Object} found the detected `testTargeted` entry
+ * @param {string} root project root
+ * @param {Object} [fsImpl]
+ * @returns {Array<string>}
+ */
+function testFilesFor(found     , root        , fsImpl      = nodeFs)           {
+  const convention = conventionFor(found);
+  if (!convention) return [];
+  const files = new Set        ();
+  for (const r of convention.roots) {
+    for (const file of walkFiles(fsImpl, root, r)) {
+      if (convention.isTest(file) && statOf(fsImpl, path.join(root, file))?.isFile()) {
+        files.add(file);
+      }
+    }
+  }
+  return [...files].sort();
+}
+
 /**
  * @param {Object} input
  * @param {Object} input.found the detected `testTargeted` entry (`source`, `testDirs`)
@@ -126,10 +149,7 @@ function selectChangedTests({ found, observation, root, fsImpl = nodeFs, platfor
   const convention = conventionFor(found);
   if (!convention) return null;
 
-  const total = new Set        ();
-  for (const r of convention.roots) {
-    for (const file of walkFiles(fsImpl, root, r)) if (convention.isTest(file)) total.add(file);
-  }
+  const total = new Set        (testFilesFor(found, root, fsImpl));
   const totalCount = total.size;
   const fallback = (reason        , selectedCount                = 0) => ({
     pattern: null,
@@ -169,4 +189,44 @@ function selectChangedTests({ found, observation, root, fsImpl = nodeFs, platfor
   };
 }
 
-module.exports = { selectChangedTests, quotePath, GUARD_DIR };
+/**
+ * Formats a sorted list of selected test files into a shell-quoted command argument pattern (IC-003).
+ * When guardDir is present and files under guardDir are included in selectedTests, they are replaced
+ * by a single quoted `${guardDir}/` token.
+ *
+ * @param {Object} input
+ * @param {Array<string>} input.selectedTests repo-relative test paths
+ * @param {string|null} [input.guardDir] optional guard directory (e.g. 'test/guards')
+ * @param {string} [input.platform] platform for path quoting
+ * @returns {string} shell-quoted argument string
+ */
+function formatSelectedTestPattern({
+  selectedTests = [],
+  guardDir = null,
+  platform = process.platform,
+}   
+                           
+                           
+                    
+ )         {
+  const underGuard = (file        ) => Boolean(guardDir && (file === guardDir || file.startsWith(`${guardDir}/`)));
+  const nonGuard = [...new Set(selectedTests.map(normalize))]
+    .filter((f        ) => !underGuard(f))
+    .sort();
+  const asArgument = (file        ) => (file.startsWith('-') ? `./${file}` : file);
+  const words = nonGuard.map((file        ) => quotePath(asArgument(file), platform));
+  const hasGuard = Boolean(guardDir && (selectedTests.some(underGuard) || selectedTests.length === 0));
+  if (hasGuard) {
+    words.push(quotePath(`${guardDir}/`, platform));
+  }
+  return words.join(' ');
+}
+
+module.exports = {
+  selectChangedTests,
+  formatSelectedTestPattern,
+  quotePath,
+  GUARD_DIR,
+  testFilesFor,
+  conventionFor,
+};

package/src/runtime/worker/active.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { shippedWorkerIds, knownWorkerIds } = require('../../registry/worker-ids.js');
+const { loadRegistry } = require('../../registry/index.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+                      
+                                     
+                    
+                     
+                     
+                                                   
+                        
+                                
+  
+
+/** IC-009: resolve the usable workers and in-session permission from workers.enabled. */
+function activeWorkers({ registry, view, env = process.env, projectRoot = null }      = {})                {
+  const reg = registry || loadRegistry({ repoRoot: REPO_ROOT });
+  const known = knownWorkerIds({ registry: reg, view }).ids;
+  let res     ;
+  try {
+    const { loadSettings } = require('../settings/resolve.js');
+    res = loadSettings({ projectRoot, env: { ...env } }).get('workers.enabled', 'project');
+  } catch {
+    return {
+      state: 'invalid', workers: [], inSession: false, dangling: [],
+      origin: { layer: 'default', source: null }, reason: 'unreadable', narrowedFrom: null,
+    };
+  }
+
+  const origin = { layer: res.origin.layer, source: res.origin.source };
+  if (res.state === 'invalid') {
+    const candidate = res.candidates.find((item     ) =>
+      item.status === 'invalid' && item.layer === origin.layer && item.source === origin.source);
+    return {
+      state: 'invalid', workers: [], inSession: false, dangling: [],
+      origin, reason: candidate?.reason || 'invalid', narrowedFrom: null,
+    };
+  }
+  if (origin.layer === 'default') {
+    return {
+      state: 'unset', workers: shippedWorkerIds(reg), inSession: true, dangling: [],
+      origin, reason: null, narrowedFrom: null,
+    };
+  }
+
+  const value = res.value            ;
+  const ids = value.filter((id) => id !== 'primary');
+  const user = origin.layer === 'project' || origin.layer === 'local'
+    ? res.candidates.find((item     ) => item.layer === 'user' && item.value !== null && item.status === 'overridden')
+    : null;
+  return {
+    state: 'set',
+    workers: ids.filter((id) => known.includes(id)),
+    inSession: value.at(-1) === 'primary',
+    dangling: ids.filter((id) => !known.includes(id)),
+    origin,
+    reason: null,
+    narrowedFrom: user ? [...user.value] : null,
+  };
+}
+
+/** IC-009: refuse a worker outside the resolved usable set. */
+function workerGate(active               , id        ) {
+  if (active.workers.includes(id)) return null;
+  return {
+    reason: active.state === 'invalid' ? 'workers-enabled-invalid' : 'worker-disabled',
+    harness: id,
+    enabled: [...active.workers],
+    origin: active.origin,
+  };
+}
+
+/** IC-009: refuse in-session work when primary is absent or the list is invalid. */
+function inSessionGate(active               ) {
+  if (active.inSession) return null;
+  if (active.state === 'invalid') {
+    return {
+      reason: 'workers-enabled-invalid',
+      text: 'workers-enabled-invalid: workers.enabled is invalid, do not run in-session',
+    };
+  }
+  return {
+    reason: 'no-enabled-worker',
+    text: 'no-enabled-worker: primary not enabled, do not run in-session',
+  };
+}
+
+module.exports = { activeWorkers, workerGate, inSessionGate };

package/src/runtime/worker/cancel.js

@@ -0,0 +1,222 @@
+'use strict';
+
+// Feature 081 C.1 (IC-021, IC-020 end state; DEC-005, DEC-038, DEC-040, DEC-046, DEC-047, DEC-050):
+// the cancel sequence, shared by the `worker --action cancel` command and the supervisor's timeout.
+//
+// In order: (1) refusals before any write or signal, against the calling process's own identity;
+// (2) the `cancelling` transition; (3) the tree escalation, outside every lock; (4) 080's attempt
+// cancel, in process, with the caller's own `env` and `cwd` and no rebuilt identity, a refusal
+// recorded and a throw stored as `disposition: 'error'`; (5) the end, always written once step 2
+// applied. The escalation runs before the 080 cancel, so an 080 failure never leaves the tree alive.
+// A child run (082 IC-015, DEC-028, DEC-041) shares its granter's 080 attempt, so step 4 is skipped
+// for it on the user and timeout paths alike: `attemptCancel: { disposition: 'skipped', reason:
+// 'child-run' }`, and ending a child never cancels its granter's attempt.
+//
+// This module makes no fs write call: every write goes through the run store's `transition`, and
+// the 080 ledger is written only by 080's own `cancel` (G26 (b), IC-027).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readRuns, transition, RunStoreError } = require('./run-store.js');
+const processTree = require('./process-tree.js');
+const { runKeyFor, identityRefusal } = require('../task-run.js');
+const attempts = require('../task-attempts.js');
+
+/** 080's `SAFE_NAME`, which `--by` must match. */
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._ -]*$/;
+/** A `cancelling` run whose request is younger than this belongs to the canceller that holds it. */
+const CANCEL_TAKEOVER_MS = 30000;
+/** How long a cancel of a launching run waits for its supervisor: its own escalation of a
+ * SIGTERM-ignoring worker, both waits and both `ps` bounds (IC-021 step 3, DEC-040, DEC-064). */
+const LAUNCH_WAIT_MS = processTree.KILL_GRACE_MS + processTree.KILL_FINAL_MS + 2 * processTree.PS_TIMEOUT_MS;
+const SOURCES = Object.freeze(['user', 'timeout']);
+
+/** Thrown inside a locked transition to abandon it with a refusal and no write. */
+class Refused extends Error {
+                      
+  constructor(result     ) {
+    super(result.reason);
+    this.result = result;
+  }
+}
+
+const defaultSleep = (ms        ) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function refused(reason        , runId        , extra      = {}) {
+  return { disposition: 'refused', reason, runId, ...extra };
+}
+
+/** `<root>/.doflow/state/worker-runs/<slug>.json` gives the lifecycle root and the slug: the 080
+ * ledger lives under the same root (data-model.md §1). */
+function ledgerFor(file        ) {
+  const root = path.resolve(path.dirname(file), '..', '..', '..');
+  const slug = path.basename(file, '.json');
+  return { root, slug, ledger: attempts.storeFile(root, slug) };
+}
+
+/** A `cancelling` run whose request is under 30 s old, or null. Pure. */
+function inProgress(run     , at      ) {
+  if (run.phase !== 'cancelling') return null;
+  const requested = Date.parse(run.cancel?.requestedAt);
+  if (Number.isFinite(requested) && at.getTime() - requested < CANCEL_TAKEOVER_MS) {
+    return refused('cancel-in-progress', run.runId, { requestedAt: run.cancel.requestedAt });
+  }
+  return null;
+}
+
+const pidOf = (entry     ) => (entry && typeof entry === 'object' ? entry.pid : entry);
+
+function union(a        = [], b        = []) {
+  const seen = new Map          ();
+  for (const entry of [...a, ...b]) if (!seen.has(pidOf(entry))) seen.set(pidOf(entry), entry);
+  return [...seen.values()];
+}
+
+/**
+ * IC-014's add-only rule (DEC-059): a recorded `supervisorCleanup` may only add to `cleanup`. An
+ * `unknown` status becomes `verified` only when `supervisorCleanup.status` is `verified`, becomes
+ * `survivors` when the supervisor found any, and otherwise stays `unknown` with its own reason; a
+ * `verified` one becomes `survivors` when the supervisor found any; the lists are unions.
+ */
+function mergeCleanup(cleanup     , supervisorCleanup     ) {
+  if (!supervisorCleanup) return cleanup;
+  const survivors = union(cleanup?.survivors, supervisorCleanup.survivors);
+  const zombies = union(cleanup?.zombies, supervisorCleanup.zombies);
+  let status        ;
+  if (survivors.length || cleanup?.status === 'survivors') status = 'survivors';
+  else if (cleanup?.status === 'verified' || supervisorCleanup.status === 'verified') status = 'verified';
+  else status = 'unknown';
+  const reason = status === 'unknown' ? cleanup?.reason ?? supervisorCleanup.reason ?? null : null;
+  return { status, reason, survivors, zombies };
+}
+
+/** Polls the store until the supervisor has exited or recorded `supervisorCleanup`, up to `budgetMs`. */
+async function waitForSupervisor({ file, runId, supervisor, platform, budgetMs, sleep, clock }     ) {
+  const until = clock().getTime() + budgetMs;
+  for (;;) {
+    const run = readRuns(file)[runId];
+    if (run?.supervisorCleanup) return { run, supervisorAlive: false };
+    const live = supervisor ? processTree.alive(supervisor, { platform }) : false;
+    if (live === false || clock().getTime() >= until) return { run, supervisorAlive: live };
+    await sleep(processTree.POLL_MS);
+  }
+}
+
+/** IC-021 step 3 for the record step 2 returned. */
+async function endTree({ file, runId, run, platform, sleep, clock, escalate }     ) {
+  if (platform === 'win32') {
+    if (run.worker) await escalate({ proc: run.worker, platform });
+    return { status: 'unknown', reason: 'win32', survivors: [], zombies: [] };
+  }
+  if (run.worker) return escalate({ proc: run.worker, platform });
+  // A starting run. With no `launchingAt` the supervisor's launch transition is refused and it
+  // spawns nothing (DEC-040).
+  if (!run.launchingAt) return { status: 'verified', reason: 'not-launched', survivors: [], zombies: [] };
+  // `launchingAt` and no `worker`: the supervisor may already have spawned. Its own `running`
+  // transition is refused, so it kills its worker and records `supervisorCleanup`; wait for that,
+  // then end the supervisor's tree when it still runs. The verdict stays `unknown` here: only a
+  // recorded `supervisorCleanup` resolves it, at step 5.
+  const waited = await waitForSupervisor({ file, runId, supervisor: run.supervisor, platform, budgetMs: LAUNCH_WAIT_MS, sleep, clock });
+  let survivors        = [];
+  let zombies        = [];
+  if (waited.supervisorAlive === true) {
+    const outcome = await escalate({ proc: run.supervisor, platform });
+    survivors = outcome.survivors;
+    zombies = outcome.zombies;
+  }
+  return { status: 'unknown', reason: 'worker-unrecorded', survivors, zombies };
+}
+
+/** 082 IC-015: what step 4 records for a child run, which has no 080 attempt of its own. */
+const CHILD_SKIP = Object.freeze({ disposition: 'skipped', reason: 'child-run' });
+
+/** IC-021 step 4: 080's cancel, its refusal recorded and its throw stored (DEC-046). */
+function attemptCancelStep({ file, run, by, reason, env, cwd, clock, cancelImpl }     ) {
+  const { root, slug, ledger } = ledgerFor(file);
+  try {
+    const answer = cancelImpl({
+      file: ledger, fsImpl: fs, roots: [...new Set([path.resolve(cwd), root])], slug,
+      task: run.task, token: run.token, by, reason, env, cwd, now: clock(),
+    });
+    return { disposition: answer?.disposition ?? 'error', reason: answer?.reason ?? null };
+  } catch (error     ) {
+    return { disposition: 'error', reason: typeof error?.code === 'string' && error.code ? error.code : 'cancel-threw' };
+  }
+}
+
+/**
+ * IC-021 steps 1 to 5. `now` is a clock function (default `() => new Date()`) or a fixed Date.
+ * Refusals return `{ disposition: 'refused', reason, runId, ... }` with nothing written or
+ * signalled; success returns `{ disposition: 'cancelled', runId, endState, cleanup, attemptCancel,
+ * attemptCancelled }`, survivors included. `cancelImpl`, `escalate` and `sleep` default to the real
+ * 080 cancel, A.3's escalation and a timer, and exist for in-process tests.
+ */
+async function cancelRun({
+  file, runId, by, reason, source = 'user', env = process.env, cwd = process.cwd(), platform = process.platform,
+  now = () => new Date(), cancelImpl = attempts.cancel, escalate = processTree.escalate, sleep = defaultSleep,
+}     ) {
+  if (!by || !SAFE_NAME.test(String(by))) throw new RunStoreError('usage', '--by is required: the name of the agent or person cancelling the run');
+  const why = typeof reason === 'string' ? reason.trim() : '';
+  if (!why) throw new RunStoreError('usage', '--reason is required: why the run is being cancelled');
+  if (!SOURCES.includes(source)) throw new RunStoreError('usage', `source '${source}' is not one of ${SOURCES.join(', ')}`);
+  const clock = typeof now === 'function' ? now : () => now;
+
+  // Step 1: the calling process's own identity, before anything is read for writing.
+  const key = runKeyFor(env, cwd);
+  const who = identityRefusal(key.identity);
+  if (who) return refused(who.reason, runId, { runKey: key.runKey });
+  const seen = readRuns(file)[runId];
+  if (!seen) return refused('unknown-run', runId);
+  if (seen.caller?.runKey !== key.runKey) return refused('foreign-run', runId, { runKey: seen.caller?.runKey ?? null });
+  if (seen.phase === 'ended') return refused('run-ended', runId, { endState: seen.end?.state ?? null });
+  const early = inProgress(seen, clock());
+  if (early) return early;
+
+  // Step 2: the same checks again under the lock, then `cancelling`.
+  const requestedAt = clock();
+  let marked     ;
+  try {
+    marked = transition(file, runId, ['starting', 'running', 'cancelling'], (run     ) => {
+      if (run.caller?.runKey !== key.runKey) throw new Refused(refused('foreign-run', runId, { runKey: run.caller?.runKey ?? null }));
+      const busy = inProgress(run, requestedAt);
+      if (busy) throw new Refused(busy);
+      run.phase = 'cancelling';
+      run.cancel = { requestedAt: requestedAt.toISOString(), by: String(by), reason: why, source };
+    });
+  } catch (error     ) {
+    if (error instanceof Refused) return error.result;
+    throw error;
+  }
+  if (!marked.applied) {
+    if (marked.reason === 'unknown-run') return refused('unknown-run', runId);
+    return refused('run-ended', runId, { endState: marked.run?.end?.state ?? null });
+  }
+
+  // Step 3, outside every lock.
+  const cleanup = await endTree({ file, runId, run: marked.run, platform, sleep, clock, escalate });
+
+  // Step 4, after the tree is ended.
+  const attemptCancel = marked.run.childOf
+    ? { ...CHILD_SKIP }
+    : attemptCancelStep({ file, run: marked.run, by: String(by), reason: why, env, cwd, clock, cancelImpl });
+
+  // Step 5: always written.
+  const endState = source === 'timeout' ? 'timed-out' : 'cancelled';
+  const ended = transition(file, runId, ['cancelling'], (run     ) => {
+    run.attemptCancel = attemptCancel;
+    run.cleanup = mergeCleanup(cleanup, run.supervisorCleanup);
+    run.end = { state: endState, at: clock().toISOString() };
+    run.phase = 'ended';
+  });
+  if (!ended.applied) return refused('run-ended', runId, { endState: ended.run?.end?.state ?? null, cleanup, attemptCancel });
+  return {
+    disposition: 'cancelled',
+    runId,
+    endState,
+    cleanup: ended.run.cleanup,
+    attemptCancel,
+    attemptCancelled: attemptCancel.disposition === 'cancelled',
+  };
+}
+
+module.exports = { cancelRun, mergeCleanup, CANCEL_TAKEOVER_MS, LAUNCH_WAIT_MS };