@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/gates/red-witness.js

@@ -1,10 +1,11 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { pathsIdentifySameObject } from "../path-identity.js";
 import { refuseOpenForWrite, singleLine } from "../task.js";
 import { loadManifest } from "./manifest.js";
 import { exitCodeForStatus, makeGateResult, renderGateResult } from "./result.js";
-import { listWitnessSpecFiles, loadWitnessSpec, memberTouchedFiles, } from "../witness/spec.js";
+import { listWitnessSpecFiles, loadWitnessSpec, memberTouchedFiles, parseWitnessSpec, phaseOwnedMemberIndices, } from "../witness/spec.js";
 import { SPAWN_GREP, computePhaseDiff, evaluateWitness, gitIn, makeScratchRoot, readTestFilesAtHead, removeScratchRoot, resolveRepoRoot, shellSpawnsAndParses, } from "../witness/run.js";
 /**
  * THE RED-WITNESS GATE (kernel plan M2, M2-P2 steps 6 and 7).
@@ -86,9 +87,27 @@ function errorOutcome(startedAt, detail) {
         reEvaluationMs: 0,
     };
 }
-/** True when the repo-relative path is a phase-audited source path. */
+/**
+ * True when the repo-relative path is a phase-audited source path.
+ *
+ * WHY `plugin/src/` AND NOT `plugin/`. This list is the COVERAGE OBLIGATION:
+ * a changed path here must be touched by some witness's dangerous state or the
+ * gate reports it uncovered. `src/` and `bin/` are source trees, and the plugin
+ * package's source tree is `plugin/src/`. Adding bare `plugin/` would pull in
+ * `plugin/package.json` and `plugin/tsconfig.json`, which no witness mutates
+ * and which would therefore redden every plugin phase for its own packaging.
+ *
+ * WHY IT IS NOT THE SAME LIST AS THE GATE'S PRECONDITION, which reads
+ * `src/`, `bin/`, `plugin/`. The precondition decides whether the gate RUNS.
+ * This decides what it REQUIRES. T-038 widened the first and left the second,
+ * so from that fix until this one a diff touching only `plugin/` ran the gate
+ * and took no obligation from it: a plugin phase shipping ZERO witnesses was
+ * green. Found by M4-P29 while reading this file for a different reason.
+ */
 function isAuditedSource(path) {
-    return path.startsWith("src/") || path.startsWith("bin/");
+    return (path.startsWith("src/") ||
+        path.startsWith("bin/") ||
+        path.startsWith("plugin/src/"));
 }
 /**
  * Run the red-witness gate against a repository. Exported so tests can
@@ -192,6 +211,47 @@ export function runRedWitnessGate(run) {
     };
     const own = specs.filter((entry) => diff.files.has(entry.repoRelative));
     const stored = specs.filter((entry) => !diff.files.has(entry.repoRelative));
+    /**
+     * A patch member's body at the MERGE BASE, the old side of the ownership
+     * comparison. `readPatchAtHead` above is the new side. Two readers rather
+     * than one because the whole point of reading the body is that the same path
+     * can hold different content on the two revisions.
+     */
+    const readPatchAtMergeBase = (patchPath) => {
+        const shown = gitIn(repoRoot, ["show", `${diff.mergeBaseSha}:${patchPath}`]);
+        return shown.ok ? shown.stdout : undefined;
+    };
+    /**
+     * The members of an own spec that THIS PHASE AUTHORED, which is rule (d)'s
+     * scope. Membership in `own` is file-granular ("some byte of this spec
+     * changed") and rule (d)'s obligation is member-granular ("this declared
+     * dangerous state must intersect the diff"), so the two are reconciled here
+     * rather than by handing the harness a boolean for the whole file.
+     *
+     * The old side is read at the MERGE BASE, which is the revision the diff
+     * itself is taken against. A baseline that is absent, unreadable or invalid
+     * yields `undefined`, and `phaseOwnedMemberIndices` then owns every member:
+     * an added spec is wholly the phase's, and so is one whose previous version
+     * cannot be established.
+     *
+     * The WHOLE spec goes in, not just its members, because the spec's claim
+     * (`behavior` and `tests`) is part of what rule (d) is an obligation on. See
+     * `claimRePointed` for which fields are in that set, why the other four are
+     * not, and why the comparison is DIRECTIONAL: re-pointing a claim takes the
+     * obligation, extending its named tests does not.
+     */
+    const ownedMembersOf = (entry) => {
+        const readers = { head: readPatchAtHead, baseline: readPatchAtMergeBase };
+        const shown = gitIn(repoRoot, [
+            "show",
+            `${diff.mergeBaseSha}:${entry.repoRelative}`,
+        ]);
+        if (!shown.ok) {
+            return phaseOwnedMemberIndices(entry.spec, undefined, readers);
+        }
+        const baseline = parseWitnessSpec(shown.stdout, `${diff.mergeBaseSha}:${entry.repoRelative}`);
+        return phaseOwnedMemberIndices(entry.spec, baseline.ok ? baseline.spec : undefined, readers);
+    };
     const triggeredStored = stored.filter((entry) => entry.spec.dangerousStates.some((member) => memberTouchedFiles(member, readPatchAtHead).some((file) => diff.files.has(file))));
     // Coverage (step 7): source changed with no witness spec covering it is
     // red, never not-applicable. Coverage semantics are decision D-P2-2 in
@@ -233,7 +293,10 @@ export function runRedWitnessGate(run) {
             scratchRoot,
         };
         for (const entry of own) {
-            const inputs = { ...baseInputs, phaseOwn: true };
+            const inputs = {
+                ...baseInputs,
+                phaseOwnedMembers: ownedMembersOf(entry),
+            };
             if (run.hooks !== undefined) {
                 inputs.hooks = run.hooks;
             }
@@ -245,7 +308,12 @@ export function runRedWitnessGate(run) {
         }
         const reEvaluationStart = Date.now();
         for (const entry of triggeredStored) {
-            const inputs = { ...baseInputs, phaseOwn: false };
+            // A stored witness is one the phase diff does not touch at all, so no
+            // member of it is the phase's and rule (d) has nothing to apply to.
+            const inputs = {
+                ...baseInputs,
+                phaseOwnedMembers: new Set(),
+            };
             if (run.hooks !== undefined) {
                 inputs.hooks = run.hooks;
             }
@@ -378,13 +446,37 @@ const invokedDirectly = (() => {
     if (entry === undefined) {
         return false;
     }
-    try {
-        return import.meta.url === pathToFileURL(resolve(entry)).href;
-    }
-    catch {
-        return false;
-    }
+    // IDENTITY, NOT STRING EQUALITY (M4-P2 fix round, 2026-09-16). Going
+    // through a URL does not change what is compared: `resolve` leaves the
+    // caller's spelling intact while `import.meta.url` is canonical, so an
+    // invocation through a symlink leaves this gate silently not running.
+    return pathsIdentifySameObject(fileURLToPath(import.meta.url), entry);
 })();
 if (invokedDirectly) {
-    process.exit(main(process.argv.slice(2)));
+    // `process.exitCode`, NEVER `process.exit(main(...))` (M4-P29). This gate
+    // runs as a SUBPROCESS, so fd 1 is a buffered stream the parent owns and a
+    // write to one is QUEUED rather than completed. `process.exit` ends the
+    // process without draining that queue, so everything past the buffer is
+    // DISCARDED, while the exit code survives and the loss is silent.
+    //
+    // BE EXACT ABOUT WHICH STREAM, because the ceiling differs by a factor of
+    // two and the obvious word is the wrong one. `spawnSync`, which is how the
+    // registry runner invokes gates (src/gates/run.ts:1528), hands a child
+    // SOCKETPAIRS, not pipes; a shell pipeline, a `tee` or a CI log collector
+    // hands it a real pipe. Measured at the pre-fix parent commit on this
+    // container, same invocation, only the reader changed:
+    //
+    //   reader            wrote     delivered
+    //   regular file      176,530   176,530
+    //   shell pipe        176,530    65,536   (one pipe buffer)
+    //   spawnSync         434,530   146,176   (the socket send buffer)
+    //
+    // A regular file never truncates, which is why this survives casual
+    // testing. This gate is the measured instance rather than a hypothetical
+    // one: its single stdout line carries the whole `detail`, and `detail`
+    // grows with the number of uncovered sources and of red witnesses.
+    // Assigning `process.exitCode` lets the process end normally, which drains
+    // the queue first, and the full capture is
+    // witness/captures/m4-p29-gate-cli-stdio.txt.
+    process.exitCode = main(process.argv.slice(2));
 }

package/dist/src/gates/run.d.ts

@@ -1,5 +1,5 @@
 import type { GateEntry, GateManifest, RunParameter } from "./manifest.ts";
-import type { GateStatus } from "./result.ts";
+import type { GateStatus, PreconditionRecord } from "./result.ts";
 /**
  * THE GATE RUNNER (kernel plan M2, M2-P1 step 7 and step 8).
  *
@@ -143,6 +143,13 @@ export interface GateSummaryRow {
     unitLabel: string;
     vacuous: boolean;
     applicable: boolean;
+    /**
+     * M4-P11, DR-0038. True when this gate's `not-applicable` carries a
+     * declaration in its precondition evidence. Present on the ROW as well as in
+     * the reason line, because the reason line is one line and a reader auditing
+     * the bundle needs to reach the gate that declared without parsing prose.
+     */
+    declaredNotApplicable?: boolean;
     detail: string;
     record?: string;
     stdout?: string;
@@ -188,6 +195,13 @@ export interface RunSummary {
     };
     /** Named here as well as in the rows, because the reason line is one line. */
     requiredNotApplicable: string[];
+    /**
+     * M4-P11, DR-0038. Every gate whose `not-applicable` carries a declaration,
+     * sorted. Always present, EMPTY when there are none, so a consumer can tell
+     * "this run declared nothing" from "this run is from before the field
+     * existed"; an absent field would be the silence that reads as permission.
+     */
+    declaredNotApplicable: string[];
     /** True when a throw escaped the run and this summary is a partial record. */
     aborted: boolean;
     exitCode: number;
@@ -209,6 +223,39 @@ export interface RunOutcome {
     reason?: string;
 }
 export declare const NO_APPLICABLE_GATE = "no applicable gate";
+/**
+ * THE EVIDENCE ENTRY THAT MARKS A NOT-APPLICABLE AS DECLARED (M4-P11, DR-0038).
+ *
+ * `src/gates/release.ts:1050` already writes this exact string into
+ * `precondition.evidence` when a release verification is declared `none`, and
+ * `scripts/check-dual-review.mjs` now writes it for the declared single-family
+ * review exception. The owner's requirement for that exception is that nobody
+ * can hide it; it is stated here as a runner-level property because the place
+ * an exception hides is the AGGREGATE, not the gate's own record.
+ *
+ * WHY AN ARRAY ELEMENT AND NOT A FIELD. A boolean on `PreconditionRecord` would
+ * be the right home, and `src/gates/schemas/gate-result.schema.json` is
+ * `additionalProperties: false` on that object, so adding one is a schema
+ * change outside M4-P11's files-to-touch list. What is done instead is the
+ * narrowest available thing that is still structural: an EXACT element of a
+ * structured array, compared with `===`, never a pattern over the detail prose.
+ * MECHANISMS.md's row about deciding what another program will do by
+ * pattern-matching the text of a file it wrote is the failure this avoids, and
+ * matching one whole array element is on the safe side of it because the
+ * producer writes the element for this purpose and nothing else.
+ */
+export declare const DECLARED_PRECONDITION_EVIDENCE = "declared: true";
+/**
+ * Does this record's precondition carry a declaration?
+ *
+ * A not-applicable with NO precondition is not declared, and neither is one
+ * whose precondition carries no evidence: silence is never permission, and it
+ * is never a declaration either.
+ */
+export declare function isDeclaredNotApplicable(result: {
+    status: GateStatus;
+    precondition?: PreconditionRecord;
+}): boolean;
 /** The default assurance mode when `--registry` is given without `--mode`. */
 export declare const DEFAULT_MODE = "full";
 export type RegistryLoad = {
@@ -525,6 +572,7 @@ export interface AggregateCounts {
 export declare function decideAggregate(counts: AggregateCounts, requiredNotApplicable: string[], rows: {
     id: string;
     status: GateStatus;
+    declaredNotApplicable?: boolean;
 }[]): {
     exitCode: number;
     reason: string;

package/dist/src/gates/run.js

@@ -16,6 +16,45 @@ import { loadManifest, validateManifestDocument, validateResultDocument } from "
 import { comparePins, describePinDifference } from "./pin.js";
 import { EXIT_GATE_ERROR, EXIT_GREEN, EXIT_NOT_APPLICABLE, EXIT_RED, M2_C_2_DETAIL, exitCodeForStatus, makeGateResult, renderGateResult, statusForExitCode, } from "./result.js";
 export const NO_APPLICABLE_GATE = "no applicable gate";
+/**
+ * THE EVIDENCE ENTRY THAT MARKS A NOT-APPLICABLE AS DECLARED (M4-P11, DR-0038).
+ *
+ * `src/gates/release.ts:1050` already writes this exact string into
+ * `precondition.evidence` when a release verification is declared `none`, and
+ * `scripts/check-dual-review.mjs` now writes it for the declared single-family
+ * review exception. The owner's requirement for that exception is that nobody
+ * can hide it; it is stated here as a runner-level property because the place
+ * an exception hides is the AGGREGATE, not the gate's own record.
+ *
+ * WHY AN ARRAY ELEMENT AND NOT A FIELD. A boolean on `PreconditionRecord` would
+ * be the right home, and `src/gates/schemas/gate-result.schema.json` is
+ * `additionalProperties: false` on that object, so adding one is a schema
+ * change outside M4-P11's files-to-touch list. What is done instead is the
+ * narrowest available thing that is still structural: an EXACT element of a
+ * structured array, compared with `===`, never a pattern over the detail prose.
+ * MECHANISMS.md's row about deciding what another program will do by
+ * pattern-matching the text of a file it wrote is the failure this avoids, and
+ * matching one whole array element is on the safe side of it because the
+ * producer writes the element for this purpose and nothing else.
+ */
+export const DECLARED_PRECONDITION_EVIDENCE = "declared: true";
+/**
+ * Does this record's precondition carry a declaration?
+ *
+ * A not-applicable with NO precondition is not declared, and neither is one
+ * whose precondition carries no evidence: silence is never permission, and it
+ * is never a declaration either.
+ */
+export function isDeclaredNotApplicable(result) {
+    if (result.status !== "not-applicable") {
+        return false;
+    }
+    const evidence = result.precondition?.evidence;
+    if (!Array.isArray(evidence)) {
+        return false;
+    }
+    return evidence.some((entry) => entry === DECLARED_PRECONDITION_EVIDENCE);
+}
 /** The default assurance mode when `--registry` is given without `--mode`. */
 export const DEFAULT_MODE = "full";
 /**
@@ -1078,6 +1117,29 @@ function pinRefusal(record) {
  * at the aggregate level, M2R-012).
  */
 export function decideAggregate(counts, requiredNotApplicable, rows) {
+    /* M4-P11, DR-0038. THE ONE THING A DECLARED EXCEPTION MUST NEVER BE IS
+       INVISIBLE, AND THE AGGREGATE IS WHERE IT WOULD BE.
+       `scripts/check-dual-review.mjs` is a CONDITIONAL gate, so its
+       not-applicable never reaches `requiredNotApplicable` and never appears in
+       the reason line. Before this clause, a bundle carrying a gate that had
+       declined DR-0012's cross-family requirement by declaration printed "every
+       applicable gate is green" and exited 0, and the exception appeared nowhere
+       a reader of the bundle would look. That is the same substitution T-009
+       names, one scope smaller: a bundle-level green standing in for a
+       gate-level fact.
+  
+       IT IS APPENDED TO EVERY ARM, not only the success path. A declaration is
+       equally worth seeing beside a red, and an arm that reported it on one
+       branch and not another would be a guard that goes quiet exactly when
+       something else is also wrong. */
+    const declared = rows
+        .filter((row) => row.status === "not-applicable" && row.declaredNotApplicable === true)
+        .map((row) => row.id)
+        .sort();
+    const declaredClause = declared.length === 0
+        ? ""
+        : `; ${String(declared.length)} gate(s) not applicable by declaration: ${declared.join(", ")}`;
+    const decided = (verdict) => ({ exitCode: verdict.exitCode, reason: `${verdict.reason}${declaredClause}` });
     let exitCode = EXIT_GREEN;
     let reason = "every applicable gate is green";
     if (counts.error > 0) {
@@ -1124,11 +1186,11 @@ export function decideAggregate(counts, requiredNotApplicable, rows) {
         .map(([name]) => name)
         .sort();
     if (badCounts.length > 0) {
-        return {
+        return decided({
             exitCode: EXIT_GATE_ERROR,
             reason: "internal inconsistency: count(s) that are not non-negative integers: " +
                 `${badCounts.join(", ")} (${JSON.stringify(counts)})`,
-        };
+        });
     }
     for (const name of [
         "declared",
@@ -1141,10 +1203,10 @@ export function decideAggregate(counts, requiredNotApplicable, rows) {
         "vacuous",
     ]) {
         if (!Object.prototype.hasOwnProperty.call(counts, name)) {
-            return {
+            return decided({
                 exitCode: EXIT_GATE_ERROR,
                 reason: `internal inconsistency: the count ${name} is missing (${JSON.stringify(counts)})`,
-            };
+            });
         }
     }
     // THE SUCCESS PATH CANNOT DESCRIBE AN EMPTY GREEN BUCKET. The branches
@@ -1181,7 +1243,7 @@ export function decideAggregate(counts, requiredNotApplicable, rows) {
             `internal inconsistency: vacuous ${String(counts.vacuous)} exceeds ` +
                 `error ${String(counts.error)}, and vacuous is a strict subset of error`;
     }
-    return { exitCode, reason };
+    return decided({ exitCode, reason });
 }
 export const RUN_CLAIM_FILE = ".tiphys-gate-run.json";
 /**
@@ -1362,6 +1424,11 @@ function writeAbortedSummary(options, runId, reason) {
             vacuous: 0,
         },
         requiredNotApplicable: [],
+        /* An aborted run ran no gate, so nothing declared anything. EMPTY rather
+           than omitted, for the reason the field's own comment gives: an absent
+           field would be indistinguishable from an older summary that could not
+           have carried one. */
+        declaredNotApplicable: [],
         aborted: true,
         exitCode: EXIT_GATE_ERROR,
         reason,
@@ -1453,6 +1520,7 @@ function runClaimedBundle(options, cwd, startedAt, runId, loaded) {
         vacuous: 0,
     };
     const requiredNotApplicable = [];
+    const declaredNotApplicable = [];
     for (const entry of selected) {
         const outcome = runOneGate(entry, options, cwd, options.evidenceDir, runId);
         const result = outcome.result;
@@ -1469,6 +1537,14 @@ function runClaimedBundle(options, cwd, startedAt, runId, loaded) {
         if (result.status === "not-applicable" && entry.applicability === "required") {
             requiredNotApplicable.push(entry.id);
         }
+        /* M4-P11. READ OFF THE INGESTED RECORD, not off the manifest and not off
+           the gate's own claim about itself: `ingestGateRun` has already refused a
+           record whose status and exit code disagree, so by here the precondition
+           belongs to a record the runner accepted. */
+        const declaredHere = isDeclaredNotApplicable(result);
+        if (declaredHere) {
+            declaredNotApplicable.push(entry.id);
+        }
         // The runner owns the record on disk whenever it produced or changed
         // one: a not-applicable gate never ran and wrote nothing, and a rewritten
         // vacuous green must not stay green in the evidence (criterion 4).
@@ -1485,6 +1561,7 @@ function runClaimedBundle(options, cwd, startedAt, runId, loaded) {
             unitLabel: result.unitLabel,
             vacuous: result.vacuous === true,
             applicable: outcome.applicable,
+            declaredNotApplicable: declaredHere,
             detail: result.detail,
             record: dirRefusalForGate === undefined ? recordPath : undefined,
             stdout: outcome.stdoutPath,
@@ -1523,6 +1600,7 @@ function runClaimedBundle(options, cwd, startedAt, runId, loaded) {
         gates: rows,
         counts,
         requiredNotApplicable,
+        declaredNotApplicable: [...declaredNotApplicable].sort(),
         aborted: false,
         exitCode,
         reason,

package/dist/src/gates/schemas/phase-declaration.schema.json

@@ -37,6 +37,51 @@
       "items": {
         "type": "string"
       }
+    },
+    "gateClasses": {
+      "description": "DR-0029 part 2a (M4-P14). The kernel requires a PHASE to declare at least one gate in each required CLASS and never says what the command is. THE SHAPE IS DECLARED HERE AND THE SEMANTICS ARE NOT, deliberately: an absent reason on a not-applicable class, or a missing establishing phase on a not-yet-establishable one, must reach a reader as a RED gate naming the phase and the class, and a schema rejection would instead surface as the gate's `error` status, which M2-C-3 reserves for a check that could not reach a verdict. So this property admits every shape src/gates/gate-classes.ts is able to report on, and that module refuses the ones DR-0029 forbids. The property is OPTIONAL because every declaration written before this phase lacks it and a required field would make all of them fail to load, turning a red verdict into an error for a defect this schema is not the right instrument for.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "correctness": {
+          "$ref": "#/$defs/classDeclaration"
+        },
+        "scope": {
+          "$ref": "#/$defs/classDeclaration"
+        },
+        "review": {
+          "$ref": "#/$defs/classDeclaration"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "classDeclaration": {
+      "description": "One class's disposition. EITHER `gates` names one or more gate ids that assert this class, OR `status` declares an escape: `not-applicable` carrying a `reason`, or `not-yet-establishable` carrying `establishedBy`, the phase id that will establish it. DR-0029: a phase may start from nothing and may never SILENTLY have nothing, so the escape is data, it is visible, and it is carried forward.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gates": {
+          "description": "Gate ids from this repository's own gate registry that assert this class for this phase.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "status": {
+          "description": "The declared escape, when this phase asserts no gate in this class.",
+          "type": "string",
+          "enum": ["not-applicable", "not-yet-establishable"]
+        },
+        "reason": {
+          "description": "Required by src/gates/gate-classes.ts when status is not-applicable. Not required HERE: an empty or absent reason is a RED verdict naming the class, not a document that fails to load.",
+          "type": "string"
+        },
+        "establishedBy": {
+          "description": "Required by src/gates/gate-classes.ts when status is not-yet-establishable: the phase id that will establish this class. The IOU's due date.",
+          "type": "string"
+        }
+      }
     }
   }
 }

package/dist/src/gates/suite.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { lstatSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { pathsIdentifySameObject } from "../path-identity.js";
+import { pathsIdentifySameObject, pathsNameSameObject } from "../path-identity.js";
 import { classifyEntry, readRegularFileIfPresent, refuseOpenForWrite, runStep, singleLine, } from "../task.js";
 import { comparePins, describePinDifference, takePin } from "./pin.js";
 import { EXIT_GATE_ERROR, exitCodeForStatus, makeGateResult, renderGateResult, } from "./result.js";
@@ -323,7 +323,20 @@ export const MAPPING_STATEMENT = "pass, fail and skipped map directly; cancelled
 export function isFileWrapperPhantom(point, cwd) {
     return (point.entityType === "test" &&
         point.nesting === 0 &&
-        resolve(cwd, point.name) === point.file);
+        // IDENTITY, NOT STRING EQUALITY, and the paragraph above claims more
+        // than `===` delivers. "Invariant across every spelling node produces
+        // it in, by construction" is false for one spelling: `resolve` does not
+        // resolve SYMLINKS, and node reports the CANONICAL path in its
+        // reporter's `file` field whatever spelling it was invoked with.
+        // Measured 2026-09-16 on node v26.6.0: invoked as
+        // <link>/test/a.test.js, `data.file` came back as <real>/test/a.test.js,
+        // so `resolve(cwd, point.name)` and `point.file` were two strings for
+        // one file and the phantom was counted as a real test again, which is
+        // the CR-1306 defect through the one spelling the enumeration missed.
+        // The string comparison is kept and tried first (it answers without
+        // touching the filesystem and is the common case); the identity check
+        // only ever turns a false "different" into a true "same".
+        pathsNameSameObject(resolve(cwd, point.name), point.file));
 }
 export function bucketPoints(points) {
     const counts = {
@@ -820,21 +833,32 @@ export function runSuiteGate(argv) {
         });
     }
     // Discovery parity, both directions (step 3).
+    //
+    // NOT Set membership on the raw strings (DV2-1): `discoveredFiles` is
+    // composed by this gate's own walk from `resolve(cwd, root)`, which does
+    // not resolve a symlinked ANCESTOR of the declared root, while
+    // `reportedFiles` comes from node's own test reporter, which is canonical
+    // whatever spelling node was invoked with (the same reason
+    // `isFileWrapperPhantom` above already compares by identity rather than by
+    // string). A `--test-root` that reaches its target through a symlinked
+    // ancestor then produces one file discovered once and reported once,
+    // reported as BOTH "discovered but absent from the reporter" and
+    // "reported but outside the declared roots", because the two strings
+    // differ even though they name the same object. `pathsNameSameObject`
+    // (src/path-identity.ts) is the round's own primitive for exactly this.
     const reportedFiles = [
         ...new Set(points
             .filter((point) => point.entityType === "test")
             .map((point) => point.file)),
     ].sort();
-    const discoveredSet = new Set(discoveredFiles);
-    const reportedSet = new Set(reportedFiles);
     const findings = [];
     for (const file of discoveredFiles) {
-        if (!reportedSet.has(file)) {
+        if (!reportedFiles.some((other) => pathsNameSameObject(other, file))) {
             findings.push(`test file discovered by the walk but absent from the reporter: ${relative(cwd, file)}`);
         }
     }
     for (const file of reportedFiles) {
-        if (!discoveredSet.has(file)) {
+        if (!discoveredFiles.some((other) => pathsNameSameObject(other, file))) {
             findings.push(`test file reported but outside the declared roots and suffix: ${relative(cwd, file)}`);
         }
     }
@@ -923,5 +947,22 @@ export function runSuiteGate(argv) {
 const invokedDirectly = process.argv[1] !== undefined &&
     pathsIdentifySameObject(fileURLToPath(import.meta.url), process.argv[1]);
 if (invokedDirectly) {
-    process.exit(runSuiteGate(process.argv.slice(2)));
+    // `process.exitCode`, NEVER `process.exit(runSuiteGate(...))` (M4-P29).
+    // This gate runs as a SUBPROCESS, so fd 1 is a buffered stream the parent
+    // owns and a write to one is QUEUED rather than completed. `process.exit`
+    // ends the process without draining that queue, so everything past the
+    // buffer is DISCARDED, while the exit code survives and the loss is
+    // silent. The plan names this gate as the plausible future trigger because
+    // its `detail` carries up to ten findings and every finding quotes text
+    // this gate read out of another program's report.
+    //
+    // Measured at the pre-fix parent commit on this container, through
+    // `spawnSync`, which is how the registry runner invokes gates
+    // (src/gates/run.ts:1528) and which hands a child SOCKETPAIRS rather than
+    // pipes: 451,014 bytes written, 182,750 delivered. A regular file never
+    // truncates, which is why this survives casual testing. Assigning
+    // `process.exitCode` lets the process end normally, which drains the queue
+    // first, and the full capture is
+    // witness/captures/m4-p29-gate-cli-stdio.txt.
+    process.exitCode = runSuiteGate(process.argv.slice(2));
 }

package/dist/src/hooks.d.ts

@@ -25,8 +25,60 @@ import type { Fleet } from "./fleet.ts";
 export declare function turnEndHookPath(fleet: Fleet, taskId: string): string;
 /**
  * Generate the hook script. The turn-end path is baked in as a literal,
- * so the hook needs no fleet resolution and no environment at all.
+ * so the hook needs no fleet resolution.
+ *
+ * THE CHILD-OBSERVED POINTER RECORD (CR-B-001, the half that closes the hole
+ * rather than the half that stops mis-asserting it).
+ *
+ * `observeNames`, when given, is baked in as a literal array and the hook
+ * writes an `env` object holding what each of those names ACTUALLY IS in the
+ * environment the hook was launched with, or `null` where the name is unset.
+ * The kernel compares those against the harness-owned paths it handed over.
+ *
+ * WHY THIS IS STRONGER THAN AN ADAPTER'S REPORT AND WHY IT IS NOT PROOF.
+ * This script is written BY THE KERNEL and, for every adapter that honours
+ * the documented contract, runs in the SAME environment as the payload (the
+ * built-in adapter spreads the same `request.env` into both spawnSync calls,
+ * and M2R-004 edit 4 is the record of why a second unscrubbed launch is
+ * itself the leak). Against an adapter that does not invoke this script at
+ * all it proves nothing, and the record no longer says otherwise.
+ *
+ * THE COST SENTENCE THAT STOOD HERE IS WITHDRAWN, BECAUSE IT WAS REFUTED BY
+ * MEASUREMENT (CR-F-CRED-001, MEDIUM).
+ *
+ * It read: an adapter that quietly reverted `HOME` for the payload "has to
+ * revert it for the payload and NOT for the hook, which means launching two
+ * children with two different environments and is a substantially different
+ * act from passing a mutated copy once". Two children is one way to do it and
+ * it is not the cheap way. The cheap way is ONE child with the mutated
+ * environment plus a single `writeFileSync` of the turn-end path, which is
+ * STRICTLY LESS work than the honest path, because the honest path also
+ * spawns the hook. The turn-end path is handed to the adapter beside
+ * `hookPath`, and this generated script names it as a literal, so an adapter
+ * that never runs it can still produce a byte-identical record.
+ *
+ * WHY A NONCE DOES NOT CLOSE THIS, stated because it is the obvious repair and
+ * it was considered and refused rather than overlooked. Baking a per-task
+ * secret into this script and requiring it in the record moves the forgery
+ * from "know the path" to "read the file", and the adapter is HANDED the path
+ * of this file: it runs at the same uid, on the same filesystem, in a
+ * directory it must be able to read to invoke the hook at all. A guard whose
+ * condition the adversary can satisfy by reading one file is green and
+ * worthless, which is this repository's own recorded shape (T-008's
+ * postscript, the red-witness rule one level up). No artifact this script can
+ * write is unforgeable by a party that can read this script.
+ *
+ * So the repair is on the RECORD rather than on the check: the value is
+ * `turn-end-record`, it names the artifact the values were read from, and
+ * `CredentialHandoverRecord` (src/task.ts) says the artifact is
+ * adapter-reachable. A dishonest adapter is still not caught here, and that
+ * residue is declared at delivery/work-history/m4-p8.md item 3; what changed
+ * is that `meta.json` no longer positively asserts a child-side observation
+ * that no child made.
+ *
+ * The hook still reads no environment it was not told to read, and a hook
+ * generated with no `observeNames` behaves exactly as it did before.
  */
-export declare function renderTurnEndHook(turnEndFile: string): string;
+export declare function renderTurnEndHook(turnEndFile: string, observeNames?: readonly string[]): string;
 /** Write the hook for a task and return its path. */
-export declare function writeTurnEndHook(fleet: Fleet, taskId: string): string;
+export declare function writeTurnEndHook(fleet: Fleet, taskId: string, observeNames?: readonly string[]): string;