@cleocode/core 2026.9.4 → 2026.9.5

package/dist/tasks/heavy-tool-limit.d.ts

@@ -66,6 +66,17 @@ export interface LimitedCommand {
     readonly confined: boolean;
     /** Ceiling applied, in MiB; `null` when unconfined. */
     readonly memoryMaxMb: number | null;
+    /**
+     * The explicit transient-unit name this command runs under, or `null` when
+     * unconfined.
+     *
+     * Reported so a caller can stop or enumerate the scope. `suite-reaper.ts`
+     * already reaps via `systemctl --user stop <unitName>` and could never
+     * target a heavy-tool scope while the name was systemd's auto-generated one.
+     *
+     * @task T12221 (gh#1396)
+     */
+    readonly unitName: string | null;
 }
 /**
  * Memory ceiling for one heavy-tool invocation, in MiB.
@@ -98,6 +109,50 @@ export declare function resolveMemoryMaxMb(totalRamGib?: number, env?: NodeJS.Pr
 export declare function cgroupConfinementAvailable(env?: NodeJS.ProcessEnv): boolean;
 /** Reset the cached probe. Test-only. @internal */
 export declare function _resetConfinementCache(): void;
+/**
+ * Build the transient-unit name a confined heavy tool runs under.
+ *
+ * `cleo-tool-<canonical>-<rootHash8>-<rand8>.scope`, e.g.
+ * `cleo-tool-test-3f9a21c4-b7e01d55.scope`. Each component earns its place:
+ *
+ * | Component     | Defends against                                   |
+ * |---------------|---------------------------------------------------|
+ * | `cleo-tool-`  | *(legibility)* `systemctl --user list-units 'cleo-tool-*'` enumerates exactly CLEO's heavy-tool scopes, distinct from `cleo-agent-*`. |
+ * | `<canonical>` | *(legibility)* an operator sees WHICH tool is stuck without opening anything. |
+ * | `<rootHash8>` | two worktrees of one repo, and two projects on one host — both have different execution roots, so each gets its own namespace and either can be reaped without touching the other. |
+ * | `<rand8>`     | two concurrent verifies of the same tool in the same tree, which differ in nothing else; and PID reuse, by not using the PID. |
+ *
+ * **Deliberately not the PID.** The PID is the component that makes systemd's
+ * auto-generated `run-p<pid>-i<id>` collide, and it defends nothing randomness
+ * does not. Including it out of familiarity would import the failure mode this
+ * name exists to remove.
+ *
+ * `rootHash8` is taken off the execution root — the same identity the cache key
+ * already uses (T12112 / gh#1220) — so the scope and the cache agree on what
+ * "the tree under test" means rather than each deciding separately.
+ *
+ * At ~38 characters of `[a-z0-9-]` this is far inside systemd's 256-byte unit
+ * name limit and uses only characters valid in a unit name.
+ *
+ * @param canonical - the heavy tool being run.
+ * @param executionRoot - absolute path of the tree the tool runs in.
+ * @returns a unit name ending in `.scope`.
+ *
+ * @task T12221 (gh#1396)
+ */
+export declare function buildToolScopeUnitName(canonical: CanonicalTool, executionRoot: string): string;
+/**
+ * Is `cmd` a `systemd-run` invocation?
+ *
+ * Compares the basename so an absolute path (`/usr/bin/systemd-run`) is
+ * recognised as readily as the bare name a `testing.command` usually carries.
+ *
+ * @param cmd - the executable a resolved tool command starts with.
+ * @returns `true` when the command is itself systemd-run.
+ *
+ * @task T12221 (gh#1396)
+ */
+export declare function isSystemdRunCommand(cmd: string): boolean;
 /**
  * Wrap a heavy tool command so the kernel bounds its whole process tree.
  *
@@ -130,6 +185,12 @@ export declare function withMemoryLimit(canonical: CanonicalTool, cmd: string, a
     totalRamGib?: number;
     env?: NodeJS.ProcessEnv;
     available?: boolean;
+    /**
+     * Tree the tool runs in, used for the unit name's `rootHash8`. Defaults to
+     * `process.cwd()` so existing callers keep working; the tool-cache passes
+     * the execution root it already resolved.
+     */
+    executionRoot?: string;
 }): LimitedCommand;
 /**
  * One sentence describing the memory bound a given tool runs under, for use in
@@ -157,4 +218,62 @@ export declare function withMemoryLimit(canonical: CanonicalTool, cmd: string, a
  * @task T12116
  */
 export declare function describeMemoryLimit(canonical: CanonicalTool, env?: NodeJS.ProcessEnv): string;
+/**
+ * Decide whether a non-zero exit came from CLEO's own confinement wrapper
+ * failing to start, rather than from the wrapped tool running and failing.
+ *
+ * ## Why this cannot be done with the exit code
+ *
+ * `systemd-run --scope` is transparent on success: it exits with the WRAPPED
+ * command's status. Measured on systemd 259 — a scope that starts and runs
+ * `sh -c 'exit 7'` makes `systemd-run` exit `7`. When it cannot create the
+ * unit it exits `1` and the wrapped command never runs.
+ *
+ * `1` is also the exit code of a test suite with a failing test. So the two
+ * outcomes CLEO most needs to tell apart — "the harness never started" and
+ * "the suite ran and was red" — are identical in the exit code, and differ
+ * only in stderr. That is the whole of gh#1397: not a missing error code
+ * ({@link validateTool} has had `E_EVIDENCE_TOOL_UNAVAILABLE` all along) but a
+ * missing route into it.
+ *
+ * ## Scope of the claim
+ *
+ * Returns the matched diagnostic line so the caller can quote the real reason
+ * rather than paraphrase it.
+ *
+ * Gated on whether the spawned command was a `systemd-run` invocation AT ALL —
+ * NOT on whether CLEO added it. Those two were the same question until
+ * double-wrap detection landed; now a project that pins its own
+ * `systemd-run` test command is spawned unconfined by CLEO, and a failure of
+ * ITS wrapper still means the suite never ran. Keying on
+ * {@link LimitedCommand.confined} alone would have reported exactly the
+ * gh#1396 project's harness failures as red suites — the defect this function
+ * exists to remove, reintroduced by the fix for its sibling.
+ *
+ * This is a stderr match, so it is not airtight: a project whose own test
+ * output contained one of these strings verbatim AND exited non-zero would be
+ * misreported. That is judged acceptable against the alternative, which is the
+ * status quo of reporting every harness failure as a red suite. The markers
+ * are `systemd-run`'s, the check is gated on CLEO having wrapped the call, and
+ * the returned message is quoted rather than asserted.
+ *
+ * @param stderr - captured stderr from the spawn.
+ * @param viaSystemdRun - whether the spawned command was a systemd-run invocation,
+ *   whether CLEO added it or the project pinned it.
+ * @returns the matched diagnostic line, or `null` when the wrapper started fine.
+ *
+ * @example
+ * ```ts
+ * confinementStartupFailure(
+ *   'Failed to start transient scope unit: Unit run-p1-i2.scope was already loaded.',
+ *   true,
+ * );
+ * // => 'Failed to start transient scope unit: Unit run-p1-i2.scope was already loaded.'
+ * confinementStartupFailure('2 tests failed', true);   // => null
+ * confinementStartupFailure('Failed to connect to bus', false); // => null (not systemd-run)
+ * ```
+ *
+ * @task T12116 (gh#1397)
+ */
+export declare function confinementStartupFailure(stderr: string, viaSystemdRun: boolean): string | null;
 //# sourceMappingURL=heavy-tool-limit.d.ts.map

package/dist/tasks/heavy-tool-limit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-tool-limit.d.ts","sourceRoot":"","sources":["../../src/tasks/heavy-tool-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD,sDAAsD;AACtD,eAAO,MAAM,WAAW,wBAAwB,CAAC;AAEjD,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,GAAE,MAA+B,EAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAMR;AAKD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAgCxF;AAED,mDAAmD;AACnD,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;CAChB,GACL,cAAc,CAsChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAUR"}
+{"version":3,"file":"heavy-tool-limit.d.ts","sourceRoot":"","sources":["../../src/tasks/heavy-tool-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD,sDAAsD;AACtD,eAAO,MAAM,WAAW,wBAAwB,CAAC;AAEjD,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,GAAE,MAA+B,EAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAMR;AAKD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAgCxF;AAED,mDAAmD;AACnD,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,GACL,cAAc,CAiGhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAaR;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAS/F"}

package/dist/tasks/heavy-tool-limit.js

@@ -46,6 +46,7 @@
  * @task T12116
  */
 import { spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
 import { totalmem } from 'node:os';
 import { isHeavyTool } from './heavy-tool-env.js';
 /** Fraction of host RAM one heavy tool invocation may occupy. */
@@ -130,6 +131,57 @@ export function cgroupConfinementAvailable(env = process.env) {
 export function _resetConfinementCache() {
     _available = null;
 }
+/**
+ * Build the transient-unit name a confined heavy tool runs under.
+ *
+ * `cleo-tool-<canonical>-<rootHash8>-<rand8>.scope`, e.g.
+ * `cleo-tool-test-3f9a21c4-b7e01d55.scope`. Each component earns its place:
+ *
+ * | Component     | Defends against                                   |
+ * |---------------|---------------------------------------------------|
+ * | `cleo-tool-`  | *(legibility)* `systemctl --user list-units 'cleo-tool-*'` enumerates exactly CLEO's heavy-tool scopes, distinct from `cleo-agent-*`. |
+ * | `<canonical>` | *(legibility)* an operator sees WHICH tool is stuck without opening anything. |
+ * | `<rootHash8>` | two worktrees of one repo, and two projects on one host — both have different execution roots, so each gets its own namespace and either can be reaped without touching the other. |
+ * | `<rand8>`     | two concurrent verifies of the same tool in the same tree, which differ in nothing else; and PID reuse, by not using the PID. |
+ *
+ * **Deliberately not the PID.** The PID is the component that makes systemd's
+ * auto-generated `run-p<pid>-i<id>` collide, and it defends nothing randomness
+ * does not. Including it out of familiarity would import the failure mode this
+ * name exists to remove.
+ *
+ * `rootHash8` is taken off the execution root — the same identity the cache key
+ * already uses (T12112 / gh#1220) — so the scope and the cache agree on what
+ * "the tree under test" means rather than each deciding separately.
+ *
+ * At ~38 characters of `[a-z0-9-]` this is far inside systemd's 256-byte unit
+ * name limit and uses only characters valid in a unit name.
+ *
+ * @param canonical - the heavy tool being run.
+ * @param executionRoot - absolute path of the tree the tool runs in.
+ * @returns a unit name ending in `.scope`.
+ *
+ * @task T12221 (gh#1396)
+ */
+export function buildToolScopeUnitName(canonical, executionRoot) {
+    const rootHash8 = createHash('sha256').update(executionRoot).digest('hex').slice(0, 8);
+    const rand8 = randomBytes(4).toString('hex');
+    return `cleo-tool-${canonical}-${rootHash8}-${rand8}.scope`;
+}
+/**
+ * Is `cmd` a `systemd-run` invocation?
+ *
+ * Compares the basename so an absolute path (`/usr/bin/systemd-run`) is
+ * recognised as readily as the bare name a `testing.command` usually carries.
+ *
+ * @param cmd - the executable a resolved tool command starts with.
+ * @returns `true` when the command is itself systemd-run.
+ *
+ * @task T12221 (gh#1396)
+ */
+export function isSystemdRunCommand(cmd) {
+    const base = cmd.split('/').pop() ?? cmd;
+    return base === 'systemd-run';
+}
 /**
  * Wrap a heavy tool command so the kernel bounds its whole process tree.
  *
@@ -164,18 +216,75 @@ export function withMemoryLimit(canonical, cmd, args, opts = {}) {
     // the spawn deadline. Four independent literals agreeing by coincidence is
     // how a fifth heavy tool gets a long deadline and no memory bound.
     if (!isHeavyTool(canonical)) {
-        return { cmd, args, confined: false, memoryMaxMb: null };
+        return { cmd, args, confined: false, memoryMaxMb: null, unitName: null };
+    }
+    // gh#1396: do NOT wrap a command that already carries its own resource
+    // wrapper. `axiom-analytics` pins
+    //
+    //   testing.command = "systemd-run --user --scope --quiet -p MemoryMax=8G \
+    //                      -p MemorySwapMax=0 -- env … pnpm exec vitest run"
+    //
+    // and `parseCommandString` splits on whitespace, so `cmd` is literally
+    // `systemd-run`. Prepending a second one nests two transient scopes, and
+    // `systemd-run --scope` execs its payload rather than forking — so the inner
+    // client regenerates a unit name the outer has already registered.
+    // Measured: nested 5/5 collide with
+    // "Unit run-p<pid>-i<id>.scope was already loaded or has a fragment file";
+    // a single invocation, 0/6.
+    //
+    // The collision is the symptom. The defect is the double wrap, and declining
+    // it is the rule this codebase has already adopted twice for exactly this
+    // shape: `heapCapApplied()` in `bin/cleo.js` does not re-exec when an
+    // operator's own `NODE_OPTIONS` already sets a heap cap, and
+    // `mergeNodeOptions()` lets an existing explicit value outrank our default.
+    // A project whose test command IS `systemd-run -p MemoryMax=8G` has made
+    // that same explicit choice, and a second cap it did not ask for is the
+    // thing to avoid, not merely the name clash.
+    //
+    // Deliberately systemd-run-SPECIFIC. `env`, `nice`, `taskset` and `timeout`
+    // are all plausible leading tokens too, but none of them imposes the cgroup
+    // memory bound this function exists to apply, so treating them as
+    // "already confined" would silently drop the ceiling. Detecting general
+    // intent would be guessing; this detects our own mechanism only.
+    if (isSystemdRunCommand(cmd)) {
+        return { cmd, args, confined: false, memoryMaxMb: null, unitName: null };
     }
     const available = opts.available ?? cgroupConfinementAvailable(env);
     if (!available) {
-        return { cmd, args, confined: false, memoryMaxMb: null };
+        return { cmd, args, confined: false, memoryMaxMb: null, unitName: null };
     }
     const memoryMaxMb = resolveMemoryMaxMb(opts.totalRamGib ?? totalmem() / 1024 ** 3, env);
+    // CWD-OK: do NOT replace this with `resolveOrCwd(opts.executionRoot)`, which
+    // is what the project-root lint recommends. That helper falls back to
+    // `getProjectRoot()`, and `getProjectRoot()` DELIBERATELY collapses a git
+    // worktree to the main repo (paths.ts, step 2.5: "the canonical project root
+    // is the MAIN repo, not the worktree dir"). That is correct for locating
+    // state, and wrong here: every worktree of a repo would then hash to the same
+    // `rootHash8`, so two worktrees running `test` concurrently would build the
+    // same unit-name namespace — reintroducing a collision class inside the fix
+    // for a collision bug, and destroying the property this component exists to
+    // provide (see {@link buildToolScopeUnitName}).
+    //
+    // The production call site (`tool-cache.ts`) ALWAYS passes `executionRoot` —
+    // the same execution root the cache key uses — so this fallback is reached
+    // only by callers that do not identify a tree: tests, and any future
+    // in-process caller. For those, the process cwd is the best available answer
+    // and a wrong-but-unique namespace is harmless, whereas a collapsed one is
+    // not. Making `executionRoot` required would remove this line entirely and
+    // is the right follow-up.
+    const unitName = buildToolScopeUnitName(canonical, opts.executionRoot ?? process.cwd()); // CWD-OK: getProjectRoot() collapses worktrees to the main repo, which would give every worktree the same rootHash8 — see the note above
     return {
         cmd: 'systemd-run',
         args: [
             '--user',
             '--scope',
+            // gh#1396: an EXPLICIT name. Without `--unit=` systemd generates
+            // `run-p<pid>-i<dbus-id>`, which is unstoppable by name (so
+            // `suite-reaper.ts` cannot target it) and collides outright when two
+            // systemd-run clients share a pid. `--scope` picks the unit TYPE and
+            // `--unit=` supplies its NAME; they are independent and compose, which
+            // the TSDoc here asserted otherwise for the whole life of this defect.
+            `--unit=${unitName}`,
             '--quiet',
             '--collect',
             '-p',
@@ -191,6 +300,7 @@ export function withMemoryLimit(canonical, cmd, args, opts = {}) {
         ],
         confined: true,
         memoryMaxMb,
+        unitName,
     };
 }
 /**
@@ -219,7 +329,10 @@ export function withMemoryLimit(canonical, cmd, args, opts = {}) {
  * @task T12116
  */
 export function describeMemoryLimit(canonical, env = process.env) {
-    const limited = withMemoryLimit(canonical, 'probe', [], { env });
+    // `executionRoot` is a stable sentinel, not a real path: this probe reads
+    // only `confined` and `memoryMaxMb` and discards the unit name, so making it
+    // read the process cwd would be a side effect with no consumer.
+    const limited = withMemoryLimit(canonical, 'probe', [], { env, executionRoot: 'probe' });
     if (!limited.confined || limited.memoryMaxMb === null)
         return '';
     return (` This tool runs inside a memory-bounded systemd scope ` +
@@ -228,4 +341,93 @@ export function describeMemoryLimit(canonical, env = process.env) {
         `though an external kill looks identical. Raise it with ${MEMORY_MAX_ENV}=<megabytes>, ` +
         `reduce the tool's own worker count, or set ${DISABLE_ENV}=1 to run unconfined.`);
 }
+/**
+ * `systemd-run`'s own pre-exec failure diagnostics.
+ *
+ * Each of these is printed by `systemd-run` itself, BEFORE it execs the wrapped
+ * command, when it cannot create the transient unit. They are not produced by
+ * the tool being wrapped, because the tool never ran.
+ *
+ * Matched case-insensitively against the captured stderr. The list is
+ * deliberately narrow: every entry is a message `systemd-run` emits on the
+ * failure path, not a generic systemd string that could plausibly appear in a
+ * project's own test output.
+ *
+ * @task T12116 (gh#1397)
+ */
+const CONFINEMENT_STARTUP_MARKERS = [
+    'failed to start transient scope unit',
+    'failed to start transient service unit',
+    'failed to connect to bus',
+    'failed to create bus connection',
+    'interactive authentication required',
+];
+/**
+ * Decide whether a non-zero exit came from CLEO's own confinement wrapper
+ * failing to start, rather than from the wrapped tool running and failing.
+ *
+ * ## Why this cannot be done with the exit code
+ *
+ * `systemd-run --scope` is transparent on success: it exits with the WRAPPED
+ * command's status. Measured on systemd 259 — a scope that starts and runs
+ * `sh -c 'exit 7'` makes `systemd-run` exit `7`. When it cannot create the
+ * unit it exits `1` and the wrapped command never runs.
+ *
+ * `1` is also the exit code of a test suite with a failing test. So the two
+ * outcomes CLEO most needs to tell apart — "the harness never started" and
+ * "the suite ran and was red" — are identical in the exit code, and differ
+ * only in stderr. That is the whole of gh#1397: not a missing error code
+ * ({@link validateTool} has had `E_EVIDENCE_TOOL_UNAVAILABLE` all along) but a
+ * missing route into it.
+ *
+ * ## Scope of the claim
+ *
+ * Returns the matched diagnostic line so the caller can quote the real reason
+ * rather than paraphrase it.
+ *
+ * Gated on whether the spawned command was a `systemd-run` invocation AT ALL —
+ * NOT on whether CLEO added it. Those two were the same question until
+ * double-wrap detection landed; now a project that pins its own
+ * `systemd-run` test command is spawned unconfined by CLEO, and a failure of
+ * ITS wrapper still means the suite never ran. Keying on
+ * {@link LimitedCommand.confined} alone would have reported exactly the
+ * gh#1396 project's harness failures as red suites — the defect this function
+ * exists to remove, reintroduced by the fix for its sibling.
+ *
+ * This is a stderr match, so it is not airtight: a project whose own test
+ * output contained one of these strings verbatim AND exited non-zero would be
+ * misreported. That is judged acceptable against the alternative, which is the
+ * status quo of reporting every harness failure as a red suite. The markers
+ * are `systemd-run`'s, the check is gated on CLEO having wrapped the call, and
+ * the returned message is quoted rather than asserted.
+ *
+ * @param stderr - captured stderr from the spawn.
+ * @param viaSystemdRun - whether the spawned command was a systemd-run invocation,
+ *   whether CLEO added it or the project pinned it.
+ * @returns the matched diagnostic line, or `null` when the wrapper started fine.
+ *
+ * @example
+ * ```ts
+ * confinementStartupFailure(
+ *   'Failed to start transient scope unit: Unit run-p1-i2.scope was already loaded.',
+ *   true,
+ * );
+ * // => 'Failed to start transient scope unit: Unit run-p1-i2.scope was already loaded.'
+ * confinementStartupFailure('2 tests failed', true);   // => null
+ * confinementStartupFailure('Failed to connect to bus', false); // => null (not systemd-run)
+ * ```
+ *
+ * @task T12116 (gh#1397)
+ */
+export function confinementStartupFailure(stderr, viaSystemdRun) {
+    if (!viaSystemdRun || stderr === '')
+        return null;
+    for (const line of stderr.split('\n')) {
+        const haystack = line.toLowerCase();
+        if (CONFINEMENT_STARTUP_MARKERS.some((m) => haystack.includes(m))) {
+            return line.trim();
+        }
+    }
+    return null;
+}
 //# sourceMappingURL=heavy-tool-limit.js.map

package/dist/tasks/heavy-tool-limit.js.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-tool-limit.js","sourceRoot":"","sources":["../../src/tasks/heavy-tool-limit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"heavy-tool-limit.js","sourceRoot":"","sources":["../../src/tasks/heavy-tool-limit.ts"],"names":[],"mappings":"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"}

package/dist/tasks/tool-cache.d.ts

@@ -69,7 +69,7 @@ export interface ToolCacheEntry {
     source: string;
     /** Git HEAD sha at execution time. */
     head: string | null;
-    /** sha256 of `git status --porcelain` (uncommitted tree fingerprint). */
+    /** sha256 of `git diff HEAD` — CONTENT of the uncommitted tracked changes (gh#1452). */
     dirtyFingerprint: string | null;
     /**
      * Absolute, symlink-resolved path of the tree the tool actually ran in.
@@ -161,6 +161,24 @@ export interface ToolRunResult {
      * @task T12112 (gh#1220)
      */
     executionRoot: string;
+    /**
+     * The diagnostic line from CLEO's own confinement wrapper when it failed to
+     * START the tool, else `null`.
+     *
+     * gh#1397: `systemd-run --scope` is transparent on success — it exits with
+     * the wrapped command's status — but exits `1` when it cannot create the
+     * transient unit, and `1` is also what a suite with a failing test exits
+     * with. "The harness never started" and "the suite ran and was red" are
+     * therefore identical in `exitCode`, and CLEO reported both as
+     * `E_EVIDENCE_TOOL_FAILED`: a fast red suite. Five occurrences of gh#1396
+     * produced no diagnosis for exactly this reason.
+     *
+     * Non-null means the tool did NOT run, so nothing is cached and the caller
+     * must report an unavailable harness rather than a failing tool.
+     *
+     * @task T12116 (gh#1397)
+     */
+    harnessFailure: string | null;
     /** Full cache entry — useful for audit / debugging. */
     entry: ToolCacheEntry;
 }
@@ -437,44 +455,6 @@ export declare function isEntryUsable(entry: Partial<ToolCacheEntry>): boolean;
  * @task T1534
  */
 export declare function captureHead(projectRoot: string): Promise<string | null>;
-/**
- * Capture a fingerprint of the uncommitted TRACKED tree by sha256-hashing
- * `git status --porcelain=v1 --untracked-files=no`. Returns `null` for
- * non-git roots.
- *
- * Two repos with identical tracked content but different uncommitted edits
- * produce different fingerprints — so editing a tracked file before
- * re-verifying always invalidates the cache for tools sensitive to that file.
- *
- * ## Why untracked files are excluded (gh#1221)
- *
- * The fingerprint is captured BEFORE the tool spawns and is the key the
- * result is stored under. When untracked files were included, a tool that
- * emitted any untracked artifact changed the fingerprint that the NEXT call
- * computes — so the tool invalidated its own cache entry simply by running,
- * and the cache could never hit. This is not hypothetical or
- * multi-agent-specific: in this repo `coverage/`, `.vitest/` and `*.log` are
- * not gitignored, so a single suite run is enough. A one-line marker file is
- * enough.
- *
- * Excluding untracked files fixes that at the root, rather than maintaining a
- * per-project list of build-output paths that rots as tooling changes.
- *
- * TRADEOFF (deliberate): a brand-new UNTRACKED source or test file no longer
- * invalidates the cache either, so `cleo verify` can return a cached pass
- * that did not exercise it. Commit the file (HEAD moves, the key moves) or
- * force a fresh run with {@link RunToolOptions.bypassCache} — surfaced as
- * `CLEO_EVIDENCE_FRESH=1`. The alternative — a maintained exclude list — trades
- * a loud, documented staleness for a silent, per-project one.
- *
- * The cache directory itself (`.cleo/cache/`) and other CLEO-managed runtime
- * state (`.cleo/tasks.db`, `.cleo/brain.db`, journal/log files) remain
- * excluded via pathspec so a tracked-and-modified CLEO file cannot reintroduce
- * the same self-invalidation.
- *
- * @task T1534
- * @task T12112 (gh#1221)
- */
 export declare function captureDirtyFingerprint(projectRoot: string): Promise<string | null>;
 /**
  * Resolve the absolute path for a cache entry by key.

package/dist/tasks/tool-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-cache.d.ts","sourceRoot":"","sources":["../../src/tasks/tool-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-cache.d.ts","sourceRoot":"","sources":["../../src/tasks/tool-cache.ts"],"names":[],"mappings":"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"}