mandrel 2.21.0 → 2.23.0

package/.agents/README.md

@@ -325,7 +325,7 @@ persists Stories with inline `acceptance[]` / `verify[]` and a folded
 `main`. There is no `type::epic` / `type::task` label, Epic issue form, or
 `epic/<id>` integration branch; a ticket carrying an `Epic: #N` footer is
 refused by `/deliver`. The execution-model contract is owned by
-[`instructions.md` § 5.D](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
+[`instructions.md` § 5.B](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
 
 ---
 

package/.agents/agents/story-worker.md

@@ -102,6 +102,11 @@ close pipeline is the authoritative gate. The acceptance self-eval loop may
 share `lint` / `typecheck` evidence with close via `evidence-gate.js`;
 never stamp coverage / CRAP fresh that way.
 
+Before trusting a gate's output — or diagnosing a red one — read
+[`known-tooling-behavior.md`](../rules/known-tooling-behavior.md): measured
+cases where a command prints what it does not mean (lint exits 1 under a
+`0 error(s)` summary; a green `check-baselines.js` is not `baselines`).
+
 ## Acceptance self-eval before close (MUST)
 
 After the implementation commits land and **before** flipping to `closing`,

package/.agents/docs/configuration.md

@@ -291,6 +291,7 @@ top-level keys are validation errors.
 | `feedbackLoop` | No | `object` | — | Nested configuration block. |
 | `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story. |
 | `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
+| `feedbackLoop.frictionWindowDays` | No | `integer` | `30` | How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30. |
 | `auditToStories` | No | `object` | — | Nested configuration block. |
 | `auditToStories.severityFloor` | No | `"critical"` \| `"high"` \| `"medium"` \| `"low"` \| `"all"` | `"high"` | Minimum severity a finding must meet to be proposed as a Story on an unattended `/audit-to-stories --auto` sweep (Story #4626). Default high. |
 | `auditToStories.autoComment` | No | `boolean` | `true` | When true (default), `/audit-to-stories --auto` posts a re-detected comment on an already-open matched Issue instead of silently skipping it. |

package/.agents/instructions.md

@@ -14,10 +14,10 @@ and is read when the task engages it.
 ### A. Role Framing
 
 No persona packs, no `persona::*` labels — constraints come from this
-file, the rules, and skills. Role-scoped spawn contexts live under
+file, the rules, and skills; "act as [role]" means apply the matching
+skill or workflow guidance. Role-scoped spawn contexts live under
 `.agents/agents/` (`delivery.routing.roleScopedAgents`); `qa.personas`
-are a separate fixture concept. "Act as [role]" = apply the matching
-skill / workflow guidance.
+is a separate fixture concept.
 
 ### B. Skill Activation
 
@@ -32,11 +32,11 @@ Unsure? Match against the `description`s in
 
 ### C. Proactive Documentation
 
-For any code involving third-party libraries, fetch the latest official
-docs **before** writing code via the host's best live-documentation
-mechanism (docs MCP server, IDE lookup) — do not ask permission.
-Fallbacks: (1) in-repo docs and the package's bundled README/CHANGELOG,
-(2) web fetch/search. Note the channel you used.
+Before writing against a third-party API you are unsure of — or one
+that moves fast enough that recall may be stale — fetch the current
+official docs via the host's best live-documentation mechanism (docs
+MCP server, IDE lookup); do not ask permission. Fallbacks: (1) in-repo
+docs and the package's bundled README/CHANGELOG, (2) web fetch/search.
 
 ### D. Error Handling & Degradation
 
@@ -64,7 +64,8 @@ read **before** the matching work (each opens with a one-line "applies
 when…" scope header): `git-conventions-reference.md`,
 `shell-conventions.md`, `testing-standards.md`,
 `orchestration-error-handling.md` (scripts under `.agents/scripts/**`),
-`ci-remediation.md`, `api-conventions.md`, `gherkin-standards.md`,
+`ci-remediation.md`, `known-tooling-behavior.md`,
+`api-conventions.md`, `gherkin-standards.md`,
 `changelog-style.md`, `test-seams.md`. Read when unsure (on-demand
 loading does not lower a rule's authority — § 1.K).
 
@@ -138,8 +139,6 @@ sizing) **fail closed** naming what to trim:
 3. **Artifacts over Chat.** Write test/build/debug output to log
    files, not into chat.
 4. **Idempotency.** Scripts must be safe to run repeatedly.
-5. **Security First.** Never hardcode secrets; use environment variables
-   and secret scanning.
 
 ---
 
@@ -151,11 +150,9 @@ sizing) **fail closed** naming what to trim:
   spawn only when the work justifies replicating context. One objective
   per subagent; depth compounds the cost (every nested level re-pays).
 - **Anti-Laziness / No Dead Code.** NEVER use placeholder comments like
-  `// ... existing code ...` — output the ENTIRE file or complete
-  function; remove unused imports, commented-out code, and dead branches
+  `// ... existing code ...`; every edit must leave complete, runnable
+  code. Remove unused imports, commented-out code, and dead branches
   before finalizing.
-- **Lint Compliance.** Adhere strictly to project linters and
-  formatters.
 - **Verification.** Include explicit verification steps in every plan.
 
 ---
@@ -167,7 +164,7 @@ reference: `story-<storyId>` branches seeded by `single-story-init.js`,
 every Story reaching `main` via its own PR
 (`helpers/deliver-story` / `single-story-close.js`).
 
-### B. Status Tracking & Commit Standards
+### A. Status Tracking & Commit Standards
 
 State mutations are GitHub labels (`agent::ready`, `agent::executing`,
 `agent::done`) via
@@ -175,7 +172,7 @@ State mutations are GitHub labels (`agent::ready`, `agent::executing`,
 Do NOT manually update issue descriptions or status fields unless
 prompted.
 
-### D. Ticket hierarchy (Story-only)
+### B. Ticket hierarchy (Story-only)
 
 The v2 ticket model is Story-only: `acceptance[]` / `verify[]` live
 inline plus the folded Tech Spec in `## Spec` (over-budget Specs fail

package/.agents/rules/git-conventions.md

@@ -19,7 +19,7 @@ commit on that branch only. Close opens a PR against `main` (squash +
 required checks). No `epic/<id>` integration branch, no `--no-ff` wave
 merge, no child tickets: commits land on `story-<storyId>` directly, the
 subject referencing the Story via `(refs #<storyId>)` — see
-[`.agents/instructions.md` § 5.D](../instructions.md).
+[`.agents/instructions.md` § 5.B](../instructions.md).
 
 ## Conventional Commits
 

package/.agents/rules/known-tooling-behavior.md

@@ -0,0 +1,114 @@
+# Known Tooling Behavior
+
+This rule applies when you are about to trust the output of a gate, a
+baseline ratchet, or a local stand-in for a CI check — before pushing,
+before declaring a check green, and before diagnosing a red one.
+
+Each entry below records a **measured** behavior of this repository's own
+tooling: a place where a command's visible output does not mean what it
+looks like it means. Entries exist because each one has already cost a
+delivery cycle.
+
+## The entry bar
+
+- An entry states behavior that was **measured against this repo**, never
+  recalled and never assumed.
+- Every entry carries a **reproduction command** that was actually run. If
+  the command stops reproducing the behavior, **delete the entry** — do not
+  annotate it. A stale entry is worse than a missing one, because it is
+  trusted.
+- Entries describe the observable behavior and the safe move. They never
+  describe a way to bypass a gate, and recording a behavior here is not a
+  decision to keep it.
+
+## 1. `npm run lint` prints `Summary: 0 error(s)` and can still exit 1
+
+**Behavior.** `npm run lint` is `run-lint.js`, which spawns six tools
+concurrently with inherited stdio and exits with the first non-zero code.
+`Summary: 0 error(s)` is **markdownlint-cli2's own verdict**, not the
+aggregate — it is printed whether or not Biome, the lifecycle lint, the
+workflow-CLI lint, the label-vocabulary lint, or the arch-cycle ratchet
+failed. Because the tools run in parallel, that line can land anywhere in
+the output, including last, so the tail of a failing run reads green.
+Biome's format diagnostics are `error`-severity, so a file that only needs
+reformatting fails the check while emitting no lint rule name at all.
+
+**Reproduce.**
+
+```bash
+# a format-only diff is an error, not a warning
+printf 'export const x = {a:1,   b:2};\n' | npx biome check --stdin-file-path=probe.js
+echo "biome exit=$?"   # 1 — "The contents aren't fixed"
+
+# and markdownlint's Summary line is unconditional
+npm run lint 2>&1 | grep -c 'Summary: 0 error(s)'
+```
+
+**Safe move.** Trust the exit code, never the last line. When `npm run lint`
+exits non-zero and you cannot see why, re-run `npx biome ci .` on its own —
+`.agents/scripts/run-lint.js` lists every tool it fans out to. Fix formatting
+with `npm run format`; never reach for `--no-verify`.
+
+## 2. `check-baselines.js` is not the whole `baselines` check
+
+**Behavior.** `.agentrc.json` declares the `baselines` required check as
+`node .agents/scripts/check-baselines.js`, but that script only runs the
+gates configured under `delivery.quality.gates` — currently **crap,
+maintainability, and duplication**. CI's job named `baselines` in
+`.github/workflows/ci.yml` runs that script **and then five standalone
+ratchets** the script knows nothing about, so a locally green
+`check-baselines.js` is not evidence that the `baselines` check will pass.
+
+| Ratchet CI's `baselines` job runs | Covered by `check-baselines.js` | Covered by `npm run lint` | Covered by `npm run verify` |
+| --- | --- | --- | --- |
+| `.agents/scripts/check-arch-cycles.js` | no | **yes** | via `lint` |
+| `.agents/scripts/check-dead-exports.js` | no | no | **yes** |
+| `.agents/scripts/check-dead-exports.js --production` | no | no | **yes** |
+| `.agents/scripts/check-context-budget.js` | no | no | **yes** |
+| `.agents/scripts/check-workflow-citations.js` | no | no | **no** |
+
+`check-workflow-citations.js` is currently in **no** local aggregate command
+— it is reachable only as `npm run check:workflow-citations` or a direct
+invocation.
+
+**Reproduce.**
+
+```bash
+node .agents/scripts/check-baselines.js --format text   # names the 3 gates it ran
+sed -n '/name: baselines/,/windows-smoke/p' .github/workflows/ci.yml | grep 'check-'
+grep "label: '" .agents/scripts/run-verify.js            # the 7 steps verify covers
+```
+
+**Safe move.** `npm run verify` is the closest local mirror; run
+`node .agents/scripts/check-workflow-citations.js` alongside it when the
+change touches workflow prose under `.agents/workflows/`. Reproducing only
+the `.agentrc.json` command before a push is a false green.
+
+## 3. The two dead-export passes disagree, and the production pass is silent without `!`
+
+**Behavior.** `check-dead-exports.js` runs twice with two separate
+baselines. The default pass treats `tests/**` as knip entry points, so an
+export whose only importer is a test still reads as *used*; the
+`--production` pass discounts test importers and therefore sees a much
+larger surface — `baselines/dead-exports.json` carries 165 rows against
+`baselines/dead-exports-production.json`'s 667. A new export that is only
+imported by its test passes the default pass and fails the production one.
+
+The production pass depends entirely on the `!` suffix on the `entry` and
+`project` patterns in `knip.json`: `!` marks a pattern as
+production-relevant. Strip the suffixes and `knip --production` reports
+**zero** export rows and exits clean — a green that means "nothing was
+analyzed", not "nothing is dead".
+
+**Reproduce.**
+
+```bash
+node .agents/scripts/check-dead-exports.js              # default pass
+node .agents/scripts/check-dead-exports.js --production # strictly larger row set
+grep -c '!"' knip.json                                  # the production markers
+```
+
+**Safe move.** Run both passes before pushing. When an export is genuinely
+test-only, keep it and refresh the production baseline deliberately —
+`.agents/rules/test-seams.md` governs which seams are sanctioned. Never
+remove the `!` suffixes from `knip.json` to quieten the production pass.

package/.agents/schemas/agentrc.schema.json

@@ -1430,6 +1430,12 @@
               "type": "boolean",
               "default": true,
               "description": "When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas."
+            },
+            "frictionWindowDays": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 30,
+              "description": "How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30."
             }
           },
           "additionalProperties": false

package/.agents/scripts/check-context-budget.js

@@ -25,6 +25,21 @@
  * ratchet — each role def is a standalone system prompt a converted spawn boots
  * on, and adding another role def is legitimate.
  *
+ * The recorded `agentBoot` rows are additionally held **in sync with the tree**
+ * (Story #4830), because those rows are what an author sizes an edit against.
+ * The two drift directions are deliberately asymmetric:
+ *
+ *   - **permissive** (the row understates the file, or no row exists) — the row
+ *     promises headroom that does not exist, the gate stays green, and the
+ *     shortfall only lands as a ceiling failure once the edit is written. This
+ *     fails the gate.
+ *   - **restrictive** (the row overstates the file) — an author under-spends
+ *     and the ceiling is never surprised, so it is self-correcting. Reported as
+ *     a `-` line; exit stays 0.
+ *
+ * Each row also records its `headroomBytes` under the ceiling, so the budget an
+ * author reads is stated rather than re-derived.
+ *
  * A read-tier that resolves **empty** is skipped silently (the `docsContextFiles`
  * half skips when unconfigured / its files are absent), so a repo with no
  * `CLAUDE.md` and no context docs is a clean no-op.
@@ -98,6 +113,100 @@ export function agentBootOverflow(tierMap, ceiling = AGENT_BOOT_CEILING_BYTES) {
     .map((f) => ({ path: f.path, bytes: f.bytes, ceiling }));
 }
 
+/**
+ * Classify one agent-boot file against its recorded baseline row (#4830).
+ * Returns `null` when the row already agrees with the tree.
+ *
+ * `permissive` drift is the failure class this gate exists for: the row
+ * understates the file (or is missing entirely), so the headroom an author
+ * computes from it is larger than the headroom that exists, and the shortfall
+ * only surfaces as a ceiling failure *after* the edit is written.
+ * `restrictive` drift is the benign mirror — the row overstates the file, so an
+ * author under-spends and the ceiling gate is never surprised.
+ *
+ * @param {{ path: string, bytes: number }} file live file measurement
+ * @param {{ bytes?: number, headroomBytes?: number } | undefined} row recorded row
+ * @param {number} ceiling
+ * @returns {{ path: string, recorded: number|null, actual: number, delta: number,
+ *   direction: 'permissive'|'restrictive', recordedHeadroom: number|null,
+ *   headroomBytes: number } | null}
+ */
+function classifyBootRow(file, row, ceiling) {
+  const actual = file.bytes;
+  const headroomBytes = ceiling - actual;
+  const recorded = Number.isFinite(row?.bytes) ? row.bytes : null;
+  const recordedHeadroom = Number.isFinite(row?.headroomBytes)
+    ? row.headroomBytes
+    : recorded === null
+      ? null
+      : ceiling - recorded;
+  // A row is in sync only when both the byte count and the headroom it
+  // advertises match the tree — a stale headroom misleads on its own.
+  if (recorded === actual && recordedHeadroom === headroomBytes) return null;
+  const permissive =
+    recorded === null ||
+    recorded < actual ||
+    (recordedHeadroom !== null && recordedHeadroom > headroomBytes);
+  return {
+    path: file.path,
+    recorded,
+    actual,
+    delta: recorded === null ? actual : actual - recorded,
+    direction: permissive ? 'permissive' : 'restrictive',
+    recordedHeadroom,
+    headroomBytes,
+  };
+}
+
+/**
+ * Compare every recorded `agentBoot` row against the tree it describes.
+ *
+ * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
+ * @param {{ agentBoot?: { ceilingBytes?: number, files?: Array<{ path: string, bytes: number, headroomBytes?: number }> } } | null} baseline
+ * @param {number} [ceiling]
+ * @returns {Array<ReturnType<typeof classifyBootRow>>} drift rows (empty = in sync)
+ */
+export function agentBootDrift(tierMap, baseline, ceiling) {
+  const recordedCeiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
+    ? baseline.agentBoot.ceilingBytes
+    : AGENT_BOOT_CEILING_BYTES;
+  const effective = Number.isFinite(ceiling) ? ceiling : recordedCeiling;
+  const rows = new Map(
+    (baseline?.agentBoot?.files ?? []).map((f) => [f.path, f]),
+  );
+  const drift = [];
+  for (const file of tierMap?.tiers?.agentBoot ?? []) {
+    if (!Number.isFinite(file?.bytes)) continue;
+    const row = classifyBootRow(file, rows.get(file.path), effective);
+    if (row) drift.push(row);
+  }
+  return drift;
+}
+
+/**
+ * Render the agent-boot drift lines. `+` lines are permissive drift (gate
+ * fail); `-` lines are restrictive drift (informational). Each line states the
+ * **real** remaining headroom, so the author sizing the next edit reads the
+ * true number rather than re-deriving it from a row that just proved stale.
+ *
+ * @param {Array<ReturnType<typeof classifyBootRow>>} drift
+ * @returns {string[]}
+ */
+export function renderBootDrift(drift) {
+  return drift.map((d) => {
+    const marker = d.direction === 'permissive' ? '+' : '-';
+    const recorded =
+      d.recorded === null
+        ? 'has no recorded row'
+        : `records ${d.recorded} bytes but the file is ${d.actual}`;
+    const note =
+      d.direction === 'permissive'
+        ? 'the row overstates the headroom an author would size an edit against'
+        : 'the row is conservative — refresh at leisure';
+    return `${marker} agentBoot drift: ${d.path} ${recorded} — ${note} (real headroom ${d.headroomBytes})`;
+  });
+}
+
 /**
  * Parse argv for `--baseline <path>`, `--root <path>`, `--update`, `--json`.
  * Exported so unit tests can pin the parser.
@@ -168,7 +277,14 @@ export function buildBaseline(tierMap, toleranceBytes) {
   // The agent-boot tier is recorded top-level (not under `tiers`) because it is
   // gated by a per-file ceiling, not the total-byte ratchet the `tiers` entries
   // use — keeping it out of `tiers` keeps the ratchet diff loop unambiguous.
-  const agentBootFiles = tierMap.tiers.agentBoot ?? [];
+  // Each row carries the headroom it leaves under the ceiling, so an author
+  // sizing an edit reads the remaining budget straight off the row (#4830)
+  // instead of re-deriving it — and `agentBootDrift` keeps both numbers honest.
+  const agentBootFiles = (tierMap.tiers.agentBoot ?? []).map((f) => ({
+    path: f.path,
+    bytes: f.bytes,
+    headroomBytes: AGENT_BOOT_CEILING_BYTES - f.bytes,
+  }));
   return {
     $schema: 'https://mandrel.dev/baselines/context-budget.schema.json',
     generatedAt: new Date().toISOString(),
@@ -353,7 +469,14 @@ export async function runCli({
     ? baseline.agentBoot.ceilingBytes
     : AGENT_BOOT_CEILING_BYTES;
   const bootOverflow = agentBootOverflow(tierMap, ceiling);
-  const exitCode = diff.grown.length > 0 || bootOverflow.length > 0 ? 1 : 0;
+  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
+  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
+  const exitCode =
+    diff.grown.length > 0 ||
+    bootOverflow.length > 0 ||
+    permissiveDrift.length > 0
+      ? 1
+      : 0;
 
   if (json) {
     const envelope = {
@@ -370,6 +493,7 @@ export async function runCli({
       skipped: diff.skipped,
       agentBootCeilingBytes: ceiling,
       agentBootOverflow: bootOverflow,
+      agentBootDrift: bootDrift,
       workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
       exitCode,
     };
@@ -384,7 +508,15 @@ export async function runCli({
         `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
       );
     }
+    for (const line of renderBootDrift(bootDrift)) {
+      stdout.write(`${line}\n`);
+    }
     if (exitCode === 1) {
+      if (permissiveDrift.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
+        );
+      }
       if (bootOverflow.length > 0) {
         stderr.write(
           `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,

package/.agents/scripts/diagnose-friction.js

@@ -31,6 +31,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
+import { constants as osConstants } from 'node:os';
 import { getLimits, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
@@ -97,6 +98,72 @@ function classifyFrictionCategory(errorOutput) {
   return { category: matched.category, remediation: matched.remediation };
 }
 
+/**
+ * `spawnSync`'s own `timeout` option kills the child with `SIGTERM`, so a
+ * SIGTERM observed here almost always means the interceptor's configured
+ * `executionTimeoutMs` bound fired. Any other signal — a `SIGKILL` from the
+ * OOM killer, an operator `kill -9` — originated outside this process.
+ *
+ * @type {string}
+ */
+const INTERCEPTOR_TIMEOUT_SIGNAL = 'SIGTERM';
+
+/** Shell convention for "the process died by signal N": exit `128 + N`. */
+const SIGNAL_EXIT_BASE = 128;
+
+/**
+ * Describe a child that never exited normally — `status === null`, Node's
+ * documented representation of "did not exit normally". The raw status must
+ * never reach `process.exit`, because `process.exit(null)` exits **0**: the
+ * interceptor would report success for a command it just watched get killed
+ * (Story #4851).
+ *
+ * Which signal fired is the diagnostic value: SIGTERM points at the
+ * interceptor's own bound, anything else at the host. Recording that plus the
+ * bound itself is what makes the row actionable to a consumer who cannot edit
+ * the materialized framework tree.
+ *
+ * Deliberately module-local and pure — exporting it for tests would fail the
+ * `--production` dead-exports ratchet, and folding it into `main` would spend
+ * the file's per-file maintainability-delta headroom. The CLI contract is the
+ * seam the unit tests drive.
+ *
+ * @param {{signal: (string|null), error?: {message?: string}}} result A
+ *   `spawnSync` result whose `status` is `null`.
+ * @param {number} executionTimeoutMs The resolved interceptor bound, in ms.
+ * @returns {{category: string, remediation: string, details: object,
+ *   preview: string, exitCode: number}}
+ */
+function describeAbnormalExit(result, executionTimeoutMs) {
+  const signal = typeof result.signal === 'string' ? result.signal : null;
+  if (signal === null) {
+    return {
+      category: FRICTION_DEFAULT.category,
+      remediation: FRICTION_DEFAULT.remediation,
+      details: {
+        killedBySignal: null,
+        killOrigin: 'spawn-failure',
+        executionTimeoutMs,
+      },
+      preview: `Command did not exit normally and reported no signal: ${result.error?.message ?? 'spawn produced no exit status'}.`,
+      exitCode: 1,
+    };
+  }
+
+  const timedOut = signal === INTERCEPTOR_TIMEOUT_SIGNAL;
+  const killOrigin = timedOut ? 'interceptor-timeout' : 'external';
+  const signum = osConstants.signals[signal];
+  return {
+    category: timedOut ? 'Execution Timeout' : 'Execution Killed',
+    remediation: timedOut
+      ? ` - ${signal} matches the interceptor's own executionTimeoutMs bound (${executionTimeoutMs}ms), so the command was almost certainly cut off rather than broken. Split it into smaller steps, or raise the bound.`
+      : ` - ${signal} originated outside the interceptor — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire, so suspect an OOM kill or a hard kill from the host. Reduce the command's memory footprint or give the host more headroom.`,
+    details: { killedBySignal: signal, killOrigin, executionTimeoutMs },
+    preview: `Command terminated by signal ${signal} (${killOrigin}); executionTimeoutMs=${executionTimeoutMs}.`,
+    exitCode: Number.isInteger(signum) ? SIGNAL_EXIT_BASE + signum : 1,
+  };
+}
+
 function toIntOrNull(value) {
   if (value == null) return null;
   const n = Number.parseInt(String(value), 10);
@@ -121,6 +188,7 @@ function buildFrictionSignal({
   category,
   commandStr,
   errorPreview,
+  terminationDetails = null,
 }) {
   return {
     kind: 'friction',
@@ -133,11 +201,14 @@ function buildFrictionSignal({
     // and always null.
     taskId: null,
     category,
+    // `emitter.command` is what `classifySignalSource` step 1 scans, so the
+    // command-scan stays authoritative for `source`: a consumer command killed
+    // by its own host remains consumer-actionable (Story #4851).
     emitter: {
       tool: 'diagnose-friction.js',
       command: commandStr,
     },
-    details: { errorPreview },
+    details: { errorPreview, ...(terminationDetails ?? {}) },
   };
 }
 
@@ -176,10 +247,22 @@ export async function main(args = process.argv.slice(2)) {
   if (result.stderr) process.stderr.write(result.stderr);
 
   if (result.status !== 0) {
+    // A `null` status means the child never exited normally; the cause lives in
+    // `result.signal`, not in the status.
+    const abnormal =
+      result.status === null
+        ? describeAbnormalExit(result, executionTimeoutMs)
+        : null;
+    // With both streams empty an abnormal termination names its signal; the
+    // `Unknown exit code` fallback is therefore reachable only with a real
+    // numeric status, never as `Unknown exit code null`.
+    const noOutputFallback = abnormal
+      ? abnormal.preview
+      : `Unknown exit code ${result.status}`;
     const errorOutput = (
       result.stderr ||
       result.stdout ||
-      `Unknown exit code ${result.status}`
+      noOutputFallback
     ).trim();
     const errorPreview = errorOutput.substring(0, 500);
 
@@ -188,7 +271,12 @@ export async function main(args = process.argv.slice(2)) {
       'Command failed. Appending friction signal to NDJSON stream...',
     );
 
-    const { category, remediation } = classifyFrictionCategory(errorOutput);
+    // An abnormal termination classifies itself: the marker scan reads output
+    // the kill may have truncated (or never produced), so it cannot name the
+    // signal.
+    const classified = classifyFrictionCategory(errorOutput);
+    const category = abnormal?.category ?? classified.category;
+    const remediation = abnormal?.remediation ?? classified.remediation;
 
     const { storyId: resolvedStoryId, epicId: resolvedEpicId } =
       resolveContextIds({ storyId, epicId }, config);
@@ -199,6 +287,7 @@ export async function main(args = process.argv.slice(2)) {
       category,
       commandStr,
       errorPreview,
+      terminationDetails: abnormal?.details ?? null,
     });
 
     // Story #2874 — accept story-only context (no parent Epic). When
@@ -236,7 +325,9 @@ export async function main(args = process.argv.slice(2)) {
     Logger.error(remediation);
     Logger.error('----------------------------------------\n');
 
-    process.exit(result.status);
+    // Never `process.exit(result.status)` on a null status — that exits 0 and
+    // reports success for a killed command.
+    process.exit(abnormal?.exitCode ?? result.status);
   } else {
     process.exit(0);
   }