tickmarkr 2.5.7 → 2.5.9

package/dist/run/protocol.js

@@ -33,6 +33,41 @@ export const ShellReceiptSchema = z.object({
     error: z.string().optional(),
     durationMs: z.number().nonnegative().optional(),
 }).strict();
+export const EVIDENCE_AVAILABILITIES = ["available", "not-started", "capture-failed", "killed", "expired", "missing"];
+export const EvidenceArtifactSchema = z.object({
+    path: z.string().refine(p => p.length > 0 && !p.startsWith("/") && !p.includes("\\") && !p.split("/").includes("..")),
+    availability: z.enum(EVIDENCE_AVAILABILITIES),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    retainedBytes: z.number().int().min(0).max(16 * 1024),
+    droppedBytes: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+}).strict().superRefine((ref, ctx) => {
+    if (ref.truncated !== (ref.droppedBytes > 0))
+        ctx.addIssue({ code: "custom", message: "truncation must agree with dropped bytes" });
+    if (ref.availability === "available" && ref.sha256 === null)
+        ctx.addIssue({ code: "custom", message: "available bytes require a hash" });
+});
+export const GateEvidenceReceiptSchema = z.object({
+    invocationId: NonEmptyStringSchema,
+    nonce: NonEmptyStringSchema.optional(),
+    subject: z.object({
+        runId: NonEmptyStringSchema,
+        taskId: NonEmptyStringSchema.nullable(),
+        attempt: AttemptSchema.nullable(),
+        gate: NonEmptyStringSchema,
+        subjectCommit: NonEmptyStringSchema.nullable(),
+    }).strict(),
+    termination: z.object({
+        kind: z.enum(["exit", "signal", "timeout", "not-started", "unknown"]),
+        exitCode: z.number().int().nullable(),
+        signal: NonEmptyStringSchema.nullable(),
+        timedOut: z.boolean().nullable(),
+    }).strict(),
+    availability: z.enum(EVIDENCE_AVAILABILITIES),
+    redaction: z.object({ material: z.boolean() }).strict(),
+    stdout: EvidenceArtifactSchema,
+    stderr: EvidenceArtifactSchema,
+}).strict();
 /** A task-build row must carry the entire caller-owned correlation, even before spawn. */
 export const CommandReceiptSchema = ShellReceiptSchema.extend({
     attribution: CommandReceiptAttributionSchema,

package/dist/run/receipt-resolver.d.ts

@@ -0,0 +1,18 @@
+import { type GateEvidenceReceipt } from "./protocol.js";
+export declare const RECEIPT_UNAVAILABLE_REASONS: readonly ["outside-root", "symlink", "hash-mismatch", "expired", "missing"];
+export type ReceiptUnavailableReason = (typeof RECEIPT_UNAVAILABLE_REASONS)[number];
+export type ReceiptResolution = {
+    readonly ok: true;
+    readonly path: string;
+    readonly sha256: string;
+} | {
+    readonly ok: false;
+    readonly path: string;
+    readonly reason: ReceiptUnavailableReason;
+};
+/** Resolve one artifact reference against the run root it was recorded under. Fails closed. */
+export declare function resolveReceipt(reference: unknown, runRoot: string): ReceiptResolution;
+/** Both artifacts of a receipt, stdout first, each resolved independently. */
+export declare function resolveReceiptArtifacts(receipt: GateEvidenceReceipt, runRoot: string): ReceiptResolution[];
+/** One line per artifact for a human surface: the reference, then its verified availability. */
+export declare function formatReceiptResolution(r: ReceiptResolution): string;

package/dist/run/receipt-resolver.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { EvidenceArtifactSchema } from "./protocol.js";
+// OBS-1101 retrieval (D-174): the one production reader of an execution-evidence receipt. It answers
+// from the bytes on disk under the run root the receipt was minted in and nothing else — no
+// re-execution, no substitute chosen by name or timestamp, no symlink followed anywhere: not in the
+// reference, not at the root, not above it. The caller hands a canonical root (its own trust anchor);
+// a root reached through any link is refused outright.
+export const RECEIPT_UNAVAILABLE_REASONS = ["outside-root", "symlink", "hash-mismatch", "expired", "missing"];
+/** Resolve one artifact reference against the run root it was recorded under. Fails closed. */
+export function resolveReceipt(reference, runRoot) {
+    const parsed = EvidenceArtifactSchema.safeParse(reference);
+    const path = typeof reference?.path === "string" ? reference.path : "";
+    if (!parsed.success) {
+        const escapes = path && (isAbsolute(path) || path.includes("\\") || path.split("/").includes(".."));
+        return { ok: false, path, reason: escapes ? "outside-root" : "missing" };
+    }
+    const ref = parsed.data;
+    if (ref.availability === "expired")
+        return { ok: false, path: ref.path, reason: "expired" };
+    if (ref.availability !== "available" || ref.sha256 === null)
+        return { ok: false, path: ref.path, reason: "missing" };
+    const root = resolve(runRoot);
+    const full = resolve(root, ref.path);
+    const rel = relative(root, full);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return { ok: false, path: ref.path, reason: "outside-root" };
+    const read = readUnderRoot(root, rel.split(sep));
+    if (typeof read === "string")
+        return { ok: false, path: ref.path, reason: read };
+    const sha256 = createHash("sha256").update(read).digest("hex");
+    if (sha256 !== ref.sha256 || read.length !== ref.retainedBytes)
+        return { ok: false, path: ref.path, reason: "hash-mismatch" };
+    return { ok: true, path: ref.path, sha256 };
+}
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+/** Every ancestor of the root, root first excluded — "/" itself cannot be a link. */
+function ancestors(root) {
+    const out = [];
+    for (let p = dirname(root); p !== dirname(p); p = dirname(p))
+        out.push(p);
+    return out;
+}
+/**
+ * Walk `parts` below `root` one descriptor at a time and return the leaf's bytes. Every component —
+ * the root's ancestors, the root, each directory, the leaf — is opened O_NOFOLLOW and must be the
+ * same inode lstat reports for that name before AND after the open, so a component swapped for a
+ * link mid-walk is refused rather than followed. Every platform takes the same pathname open: an
+ * ancestor swap by a same-privilege writer can only ever yield hash-identical bytes (D-269), so no
+ * descriptor-anchored traversal is layered on top (D-279: the boundary is the run root).
+ */
+function readUnderRoot(root, parts) {
+    for (const p of ancestors(root)) {
+        let st;
+        try {
+            st = lstatSync(p);
+        }
+        catch {
+            return "missing";
+        }
+        if (st.isSymbolicLink())
+            return "symlink";
+    }
+    const fds = [];
+    try {
+        let parent = openComponent(root, true);
+        if (typeof parent === "string")
+            return parent;
+        fds.push(parent);
+        let at = root;
+        for (let i = 0; i < parts.length; i++) {
+            at = resolve(at, parts[i]);
+            const fd = openComponent(at, i < parts.length - 1);
+            if (typeof fd === "string")
+                return fd;
+            fds.push(fd);
+            parent = fd;
+        }
+        return readFileSync(parent);
+    }
+    catch (e) {
+        return e.code === "ELOOP" ? "symlink" : "missing";
+    }
+    finally {
+        for (const fd of fds)
+            closeSync(fd);
+    }
+}
+function openComponent(path, dir) {
+    let before;
+    try {
+        before = lstatSync(path);
+    }
+    catch {
+        return "missing";
+    }
+    if (before.isSymbolicLink())
+        return "symlink";
+    if (dir ? !before.isDirectory() : !before.isFile())
+        return "missing";
+    const flags = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK | (dir ? constants.O_DIRECTORY : 0);
+    const fd = openSync(path, flags);
+    let after;
+    try {
+        after = lstatSync(path);
+    }
+    catch {
+        closeSync(fd);
+        return "missing";
+    }
+    const opened = fstatSync(fd);
+    if (after.isSymbolicLink() || !same(before, opened) || !same(after, opened)) {
+        closeSync(fd);
+        return "symlink";
+    }
+    // A leaf reachable under a second name (a hard link) is an alias the inode check cannot see through;
+    // evidence is written once under one name, so any aliased leaf is refused.
+    if (!dir && opened.nlink !== 1) {
+        closeSync(fd);
+        return "symlink";
+    }
+    return fd;
+}
+/** Both artifacts of a receipt, stdout first, each resolved independently. */
+export function resolveReceiptArtifacts(receipt, runRoot) {
+    return [receipt.stdout, receipt.stderr].map(ref => resolveReceipt(ref, runRoot));
+}
+/** One line per artifact for a human surface: the reference, then its verified availability. */
+export function formatReceiptResolution(r) {
+    return r.ok ? `${r.path} available sha256=${r.sha256}` : `${r.path} unavailable (${r.reason})`;
+}

package/dist/run/repair-disposition.d.ts

@@ -0,0 +1,41 @@
+import type { GateResult } from "../gates/types.js";
+/** Pure decision table of the scope-red disposition (OBS-1077, OBS-1074 residual): no filesystem,
+ * process, clock or journal. The caller supplies the inventory and performs every side effect. */
+export type RepairDispositionKind = "fund-repair" | "scope-request" | "authoring" | "none";
+export interface RepairDisposition {
+    kind: RepairDispositionKind;
+    /** validated inventory paths only — the sole paths a caller may put in an executable command */
+    paths: string[];
+    reason: string;
+    /** which evidence decided: a gate name, "worker" for a refusal, absent for the ordinary disposition */
+    source?: string;
+    /** an independent classification that kept priority over path prose */
+    blocker?: "infra" | "scope-collateral";
+    /** candidates that bound to nothing, or to more than one path; evidence, never approval advice */
+    diagnostics: ScopeHintDiagnostic[];
+}
+export interface ScopeHintDiagnostic {
+    candidate: string;
+    kind: "unresolved" | "ambiguous";
+    matches: string[];
+    reason: string;
+}
+export interface ScopeHintResolution {
+    resolved: string[];
+    diagnostics: ScopeHintDiagnostic[];
+}
+export interface RepairDispositionInput {
+    /** the failing gate results (passing rows are ignored) */
+    results: readonly GateResult[];
+    files: readonly string[];
+    /** the worker's refusal summary — present only when the worker reported ok:false */
+    refusalSummary?: string;
+    /** task tree plus diff, deleted tracked paths included */
+    inventory: Iterable<string>;
+}
+/** Lexing never starts in the middle of a word (same lexer as the daemon's scope-red disposition). */
+export declare const namedPaths: (text: string) => string[];
+/** Binds candidates to the SUPPLIED inventory and nothing else: an exact path, else a unique
+ * path-suffix. Anything unbound or bound twice comes back as a non-executable diagnostic. */
+export declare function resolveScopeHints(candidates: Iterable<string>, inventory: Iterable<string>): ScopeHintResolution;
+export declare function classifyRepairDisposition(input: RepairDispositionInput): RepairDisposition;

package/dist/run/repair-disposition.js

@@ -0,0 +1,77 @@
+import { filesGlob } from "../graph/files-glob.js";
+const failed = (g) => !(g.pass || g.meta?.skipped === true) || g.meta?.infra === true;
+const REFUSAL_RE = /outside|out.of.scope|allowlist|scope expansion|not (?:in|own)|unowned/i;
+/** Lexing never starts in the middle of a word (same lexer as the daemon's scope-red disposition). */
+export const namedPaths = (text) => [...text.matchAll(/(?:^|[\s`'"])((?:[A-Za-z0-9_@.()[\]-]+\/)+[A-Za-z0-9_@.[\]-]+|[A-Za-z0-9_@-]+(?:\.[A-Za-z0-9_-]+)+)(?=$|[\s`'"),:;.!?])/g)]
+    .map((match) => match[1].replace(/^\.\//, "").replace(/\.$/, ""))
+    .filter((path) => !path.split("/").includes(".."));
+/** Binds candidates to the SUPPLIED inventory and nothing else: an exact path, else a unique
+ * path-suffix. Anything unbound or bound twice comes back as a non-executable diagnostic. */
+export function resolveScopeHints(candidates, inventory) {
+    const known = new Set(inventory);
+    const resolved = new Set();
+    const diagnostics = [];
+    for (const candidate of new Set(candidates)) {
+        if (known.has(candidate)) {
+            resolved.add(candidate);
+            continue;
+        }
+        const matches = [...known].filter((path) => path.endsWith(`/${candidate}`)).sort();
+        if (matches.length === 1)
+            resolved.add(matches[0]);
+        else
+            diagnostics.push(matches.length === 0
+                ? { candidate, kind: "unresolved", matches, reason: `scope hint resolves to nothing in the task tree: ${candidate}` }
+                : { candidate, kind: "ambiguous", matches, reason: `scope hint ${candidate} matches ${matches.length} paths: ${matches.join(", ")}` });
+    }
+    return { resolved: [...resolved].sort(), diagnostics };
+}
+export function classifyRepairDisposition(input) {
+    const reds = input.results.filter(failed);
+    const none = (reason, extra = {}) => ({ kind: "none", paths: [], reason, diagnostics: [], ...extra });
+    // Independent classifications first: prose naming a path never erases them.
+    const infra = reds.find((g) => g.meta?.infra === true);
+    if (infra)
+        return none(`${infra.gate}: infra red keeps its own classification`, { source: infra.gate, blocker: "infra" });
+    const verdict = reds.find((g) => g.gate === "scope")?.meta?.collateral;
+    if (verdict) {
+        return verdict.authoring
+            ? { kind: "authoring", paths: [...verdict.predicted], reason: verdict.repair, source: "scope", blocker: "scope-collateral", diagnostics: [] }
+            : none("scope: collateral verdict has unpredicted offenders — ordinary chargeable disposition", { source: "scope", blocker: "scope-collateral" });
+    }
+    if (input.files.length === 0)
+        return none("task declares no files[]");
+    const allowed = filesGlob([...input.files]);
+    const inventory = [...input.inventory];
+    const unowned = (text) => {
+        const r = resolveScopeHints(namedPaths(text).filter((path) => !allowed(path)), inventory);
+        return { paths: r.resolved.filter((path) => !allowed(path)), diagnostics: r.diagnostics };
+    };
+    const owned = (text) => resolveScopeHints(namedPaths(text), inventory).resolved.some(allowed);
+    const refusal = input.refusalSummary !== undefined && REFUSAL_RE.test(input.refusalSummary)
+        ? unowned(input.refusalSummary) : { paths: [], diagnostics: [] };
+    // A test gate names where the ASSERTION lives — a detection site, not the code that needs fixing.
+    const sites = reds.filter((g) => g.gate === "test").map((g) => unowned(g.details));
+    const others = reds.filter((g) => g.gate !== "test");
+    const hints = others.map((g) => unowned(g.details));
+    const diagnostics = [refusal, ...sites, ...hints].flatMap((r) => r.diagnostics)
+        .filter((d, i, all) => all.findIndex((o) => o.candidate === d.candidate) === i);
+    const uniq = (rs) => [...new Set(rs.flatMap((r) => r.paths))].sort();
+    if (refusal.paths.length) {
+        return { kind: "scope-request", paths: refusal.paths, source: "worker", diagnostics,
+            reason: `worker refusal names unowned paths: ${refusal.paths.join(", ")}` };
+    }
+    const repair = uniq(hints);
+    if (repair.length && !others.some((g) => owned(g.details))) {
+        const review = others.some((g) => g.gate === "review");
+        return { kind: review ? "scope-request" : "authoring", paths: repair, source: others[0].gate, diagnostics,
+            reason: `files[] repair hint: ${repair.join(", ")}` };
+    }
+    const detection = uniq(sites);
+    if (detection.length) {
+        return { kind: "fund-repair", paths: detection, source: "test", diagnostics,
+            reason: `test gate names a detection site, not an out-of-scope repair: ${detection.join(", ")}` };
+    }
+    // Unknown attribution never blocks funding: the ordinary chargeable disposition applies.
+    return none("no attributable out-of-scope repair — ordinary chargeable disposition", { diagnostics });
+}

package/dist/run/supervision.d.ts

@@ -39,7 +39,20 @@ export interface SupervisionBeatObservation {
 export declare const supervisionBeatPath: (repoRoot: string, tier: SupervisionTier) => string;
 /** Where a watcher records that it STOOD DOWN. Its own file: the beat keeps meaning only "alive". */
 export declare const supervisionStandDownPath: (repoRoot: string, tier: SupervisionTier) => string;
-export declare function beatSupervision(repoRoot: string, tier: SupervisionTier, seat?: string, observation?: SupervisionBeatObservation): void;
+/** Durable CLI arm; ticks never advance its epoch or its stand-down fence. */
+export interface SupervisionArm {
+    armId: string;
+    armEpoch: string;
+    markerFence: string;
+}
+export declare const supervisionArmPath: (repoRoot: string, tier: SupervisionTier) => string;
+/** Explicit arming acknowledges the current marker without deleting it. */
+export declare function newSupervisionArm(repoRoot: string, tier: SupervisionTier, armId?: string, initial?: boolean): SupervisionArm;
+export declare function beatSupervision(repoRoot: string, tier: SupervisionTier, seat?: string, observation?: SupervisionBeatObservation, options?: {
+    arm?: SupervisionArm;
+    armId?: string;
+    loop?: boolean;
+}): boolean;
 /** Handle a watcher holds for as long as it is supervising; disarm stands it down and is idempotent. */
 export interface ArmedSupervision {
     disarm: () => void;

package/dist/run/supervision.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
 import { parseRunId } from "./journal.js";
 import { stateDirName, tickmarkrDir } from "../graph/graph.js";
@@ -86,6 +86,63 @@ const supervisionDir = (repoRoot) => join(repoRoot, stateDirName(repoRoot), "sup
 export const supervisionBeatPath = (repoRoot, tier) => join(supervisionDir(repoRoot), `${tier}.beat`);
 /** Where a watcher records that it STOOD DOWN. Its own file: the beat keeps meaning only "alive". */
 export const supervisionStandDownPath = (repoRoot, tier) => join(supervisionDir(repoRoot), `${tier}.standdown`);
+export const supervisionArmPath = (repoRoot, tier) => join(supervisionDir(repoRoot), `${tier}.arm`);
+function readArm(repoRoot, tier) {
+    try {
+        const arm = JSON.parse(readFileSync(supervisionArmPath(repoRoot, tier), "utf8"));
+        if (typeof arm.armId !== "string" || !arm.armId.trim() ||
+            typeof arm.armEpoch !== "string" || Number.isNaN(Date.parse(arm.armEpoch)) ||
+            typeof arm.markerFence !== "string")
+            throw new Error("invalid arm");
+        return arm;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`${tier} arm is unreadable`, { cause: error });
+    }
+}
+function markerFence(repoRoot, tier) {
+    const marker = readStandDown(repoRoot, tier);
+    if (marker === "UNREADABLE")
+        throw new Error(`${tier} stand-down is unreadable`);
+    return marker === "NONE" ? "NONE" : marker.fence;
+}
+/** Explicit arming acknowledges the current marker without deleting it. */
+export function newSupervisionArm(repoRoot, tier, armId = randomUUID(), initial = false) {
+    // Acknowledge only the marker observed when arming begins. In particular, do not
+    // sample it after stamping the epoch: a stand-down published in that gap is a
+    // later act, and must fence this arm rather than be silently acknowledged by it.
+    const fence = initial ? "NONE" : markerFence(repoRoot, tier);
+    const previous = readArm(repoRoot, tier);
+    const arm = {
+        armId, armEpoch: new Date(Math.max(Date.now(), previous ? Date.parse(previous.armEpoch) + 1 : 0)).toISOString(),
+        markerFence: fence,
+    };
+    tickmarkrDir(repoRoot);
+    const path = supervisionArmPath(repoRoot, tier);
+    if (!initial) {
+        atomicRecord(path, arm);
+        return arm;
+    }
+    // Only one legacy first tick may install the initial arm. A losing process reuses the winner.
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(arm) + "\n");
+        try {
+            linkSync(tmp, path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+    return readArm(repoRoot, tier);
+}
 /** The independent latch a stand-down cannot overwrite or remove. */
 const supervisionObligationPath = (repoRoot, tier) => join(supervisionDir(repoRoot), `${tier}.clear-owed`);
 // SUP-06: PRESENCE — one file per ARMED WATCHER, because a tier may legitimately have more than one.
@@ -190,6 +247,22 @@ function dischargeClearObligation(repoRoot, tier, observation) {
         rmSync(supervisionObligationPath(repoRoot, tier), { force: true });
     }
 }
+function raiseIfCrossed(repoRoot, tier, observation) {
+    if (observation.pct >= observation.thresholdPct) {
+        raiseClearObligation(repoRoot, tier, observation.armId, observation.thresholdPct);
+    }
+}
+// The latch is orthogonal to liveness: a stood-down tier still raises a crossing and still lets a
+// different arm below threshold discharge it. Otherwise the context instrument goes silent after the
+// first hand-off — the watcher script stands its tier down on every exit.
+function observeWithoutBeat(repoRoot, tier, observation) {
+    if (observation !== undefined) {
+        tickmarkrDir(repoRoot);
+        raiseIfCrossed(repoRoot, tier, observation);
+        dischargeClearObligation(repoRoot, tier, observation);
+    }
+    return false;
+}
 function validateObservation(observation) {
     if (!observation.armId.trim())
         throw new Error("a supervision observation needs a non-empty arm identity");
@@ -202,7 +275,7 @@ function validateObservation(observation) {
 // WRITER — a watcher's own call, on its own tier, every SUPERVISION_BEAT_MS. Never a reader's: the
 // purity fence (status --watch leaves the state dir byte-identical) is the test that catches a reader
 // that beats on the watcher's behalf, which would report every dead tier as healthy.
-function writeSupervisionBeat(repoRoot, tier, seat, armId, observation) {
+function writeSupervisionBeat(repoRoot, tier, seat, armId, observation, arm, loop = false) {
     // A seat tier may not be armed anonymously, and the refusal belongs HERE rather than only in the
     // verb: any caller that could write a seatless record could arm a tier nobody occupies.
     if (isSeatTier(tier) && !seat?.trim()) {
@@ -215,19 +288,42 @@ function writeSupervisionBeat(repoRoot, tier, seat, armId, observation) {
     mkdirSync(dirname(p), { recursive: true });
     // Raise before the beat so a later beat failure cannot hide a duty; discharge only after the
     // below-threshold observation exists on disk.
-    if (observation !== undefined && observation.pct >= observation.thresholdPct) {
-        raiseClearObligation(repoRoot, tier, observation.armId, observation.thresholdPct);
-    }
-    writeFileSync(p, JSON.stringify({
+    if (observation !== undefined)
+        raiseIfCrossed(repoRoot, tier, observation);
+    atomicRecord(p, {
         tier, ...(seat ? { seat } : {}), ...(armId ? { armId } : {}),
         ...(observation !== undefined ? { pct: observation.pct, thresholdPct: observation.thresholdPct } : {}),
-        exitedWriterPid: process.pid, beatAt: new Date().toISOString(),
-    }) + "\n");
+        ...arm,
+        ...(loop ? { pid: process.pid } : { exitedWriterPid: process.pid }),
+        beatAt: new Date().toISOString(),
+    });
     if (observation !== undefined)
         dischargeClearObligation(repoRoot, tier, observation);
 }
-export function beatSupervision(repoRoot, tier, seat, observation) {
-    writeSupervisionBeat(repoRoot, tier, seat, undefined, observation);
+export function beatSupervision(repoRoot, tier, seat, observation, options = {}) {
+    // `armId` only NAMES a first legacy arm; an existing arm is never refused for a name mismatch —
+    // the recorded id is a UUID no operator can know, and a mismatch is not a stand-down.
+    if (isSeatTier(tier) && !seat?.trim()) {
+        throw new Error(`${tier} is a per-seat tier — a beat must declare the seat identity it speaks for`);
+    }
+    if (observation !== undefined)
+        validateObservation(observation);
+    let arm = options.arm ?? readArm(repoRoot, tier);
+    if (!arm) {
+        if (markerFence(repoRoot, tier) !== "NONE")
+            return observeWithoutBeat(repoRoot, tier, observation);
+        arm = newSupervisionArm(repoRoot, tier, options.armId ?? observation?.armId, true);
+        // A marker published during initial creation must not be acknowledged implicitly.
+        if (arm.markerFence !== "NONE")
+            return observeWithoutBeat(repoRoot, tier, observation);
+    }
+    const current = readArm(repoRoot, tier);
+    if (current?.armId !== arm.armId || current.armEpoch !== arm.armEpoch ||
+        markerFence(repoRoot, tier) !== arm.markerFence)
+        return observeWithoutBeat(repoRoot, tier, observation);
+    writeSupervisionBeat(repoRoot, tier, seat, arm.armId, observation, arm, options.loop);
+    // The immutable fence travels WITH the beat, so a rename racing stand-down cannot outrank it.
+    return markerFence(repoRoot, tier) === arm.markerFence;
 }
 // THE WATCHER-FACING ENTRY POINT — the loop SUPERVISION_BEAT_MS actually drives. A supervising seat
 // calls this once at the top of its watch and holds the handle for the duration; a seat that dies,
@@ -348,11 +444,12 @@ function readBeat(repoRoot, tier) {
     // is not evidence that nobody armed the tier). On a SEAT tier it is the opposite: a record naming no
     // seat leaves the tier armed and unattributable, which reads as coverage no seat is providing, so
     // it is UNREADABLE — something is there and no beat any reader can attribute comes out of it.
-    const { seat, armId } = beatMetadata(p);
+    const { seat, armId, markerFence } = beatMetadata(p);
     if (isSeatTier(tier) && seat === undefined)
         return "UNREADABLE";
     return {
         mtimeMs: st.mtimeMs,
+        ...(markerFence !== undefined ? { markerFence } : {}),
         ...(seat !== undefined ? { seat } : {}),
         ...(armId !== undefined ? { armId } : {}),
     };
@@ -363,7 +460,8 @@ function beatMetadata(path) {
         const rec = JSON.parse(readFileSync(path, "utf8"));
         const seat = typeof rec?.seat === "string" && rec.seat.trim() ? rec.seat : undefined;
         const armId = typeof rec?.armId === "string" && rec.armId.trim() ? rec.armId : undefined;
-        return { ...(seat !== undefined ? { seat } : {}), ...(armId !== undefined ? { armId } : {}) };
+        const markerFence = typeof rec?.markerFence === "string" ? rec.markerFence : undefined;
+        return { ...(markerFence !== undefined ? { markerFence } : {}), ...(seat !== undefined ? { seat } : {}), ...(armId !== undefined ? { armId } : {}) };
     }
     catch {
         return {};
@@ -414,8 +512,11 @@ function readStandDown(repoRoot, tier) {
         return "UNREADABLE";
     let seat;
     let armId;
+    let fence;
     try {
-        const rec = JSON.parse(readFileSync(p, "utf8"));
+        const bytes = readFileSync(p, "utf8");
+        fence = createHash("sha256").update(bytes).digest("hex");
+        const rec = JSON.parse(bytes);
         if (rec?.tier !== tier)
             return "UNREADABLE";
         if (typeof rec.disarmedAt !== "string" || Number.isNaN(Date.parse(rec.disarmedAt)))
@@ -431,25 +532,22 @@ function readStandDown(repoRoot, tier) {
         return "UNREADABLE";
     } // unparseable or unreadable bytes — not a stand-down anyone can read
     return {
-        mtimeMs: st.mtimeMs,
+        mtimeMs: st.mtimeMs, fence,
         ...(seat !== undefined ? { seat } : {}),
         ...(armId !== undefined ? { armId } : {}),
     };
 }
-// THE TIER'S STATE — what every surface and every operator reads. A valid stand-down outranks the beat:
-// the watcher that wrote it is gone ON PURPOSE, and its last beat ages out exactly like a dead one's
-// would. It outranks the beat it FOLLOWED and no other — a later timestamp OR a FRESH different
-// armed-watcher identity is another arm, so a marker whose rename lost that race cannot mask a live
-// watcher. Once that foreign beat is stale, a newer clean hand-off must win: otherwise overlapping
-// boards closed in last-beater-first order would leave the tier reporting a death forever.
+// CLI beats carry the marker generation acknowledged at arm time, never at tick time. A new
+// marker dominates every tick of that arm regardless of rename order or beat mtime. The separate
+// presence-based lifecycle retains overlapping watch owners and their last-owner stand-down.
 export function supervisionStatus(repoRoot, tier, now = Date.now()) {
     const beat = readBeat(repoRoot, tier);
     const standDown = readStandDown(repoRoot, tier);
     if (standDown === "UNREADABLE")
         return withClearObligation(repoRoot, tier, { tier, state: "UNREADABLE" });
-    const beatOutranksStandDown = standDown !== "NONE" && typeof beat === "object" && (beat.mtimeMs > standDown.mtimeMs || (now - beat.mtimeMs <= SUPERVISION_STALE_MS &&
-        beat.armId !== undefined && standDown.armId !== undefined && beat.armId !== standDown.armId &&
-        existsSync(supervisionPresencePath(repoRoot, tier, beat.armId))));
+    const beatOutranksStandDown = standDown !== "NONE" && typeof beat === "object" && (beat.markerFence !== undefined ? beat.markerFence === standDown.fence :
+        beat.armId !== undefined && existsSync(supervisionPresencePath(repoRoot, tier, beat.armId)) && (beat.mtimeMs > standDown.mtimeMs || (now - beat.mtimeMs <= SUPERVISION_STALE_MS &&
+            standDown.armId !== undefined && beat.armId !== standDown.armId)));
     if (standDown !== "NONE" && !beatOutranksStandDown) {
         // the seat that stood down is named by the marker, falling back to whatever its last beat named
         const seat = standDown.seat ?? (typeof beat === "object" ? beat.seat : undefined);

package/dist/tui/cockpit/evidence-view.d.ts

@@ -27,6 +27,10 @@ export interface EvidenceRow {
     /** Durable artifact locations this row's detail names (e.g. a saved raw-review capture); empty
      *  when none were recorded — rendered as "missing", never silently omitted. */
     readonly artifacts: readonly string[];
+    /** The row's execution-evidence receipt, each artifact resolved through the shared resolver against
+     *  the run root it was minted in (`originRunRoot` for a reused verdict) — reference then verified
+     *  availability; empty when the row carries no receipt. */
+    readonly receipts: readonly string[];
     readonly taskId?: string;
     readonly gate?: string;
 }
@@ -34,7 +38,10 @@ export interface EvidenceRow {
 export declare function parseArtifactLocations(details: string): string[];
 /** Pure C2-journal-to-Evidence-rows mapping: the original journal position IS the evidence identity
  *  — assigned once here, from the full unfiltered event list, never recomputed from a display slice. */
-export declare function deriveEvidenceJournal(eventsOrRows: readonly (JournalEvent | TrackedJournalRow)[], source?: string): EvidenceRow[];
+export declare function deriveEvidenceJournal(eventsOrRows: readonly (JournalEvent | TrackedJournalRow)[], source?: string, runRoot?: string): EvidenceRow[];
+/** The live cockpit names its journal by absolute path (`<state>/runs/<runId>/journal.jsonl`); that
+ *  directory IS the run root. A relative or foreign source names no root — nothing is guessed. */
+export declare function runRootOf(source: string | undefined): string | undefined;
 /** The most recent review verdict recorded for a task — by original journal position, so a merged
  *  task's review opens the row it actually happened on rather than any on-screen index. */
 export declare function selectTaskReview(journal: readonly EvidenceRow[], taskId: string): EvidenceRow | undefined;
@@ -42,6 +49,8 @@ export interface EvidenceViewInput {
     readonly events?: readonly JournalEvent[];
     readonly rows?: readonly TrackedJournalRow[];
     readonly source?: string;
+    /** The displayed run's root (its journal directory); receipts minted by this run resolve under it. */
+    readonly runRoot?: string;
     readonly costs?: readonly ChannelCost[];
     /** Caller-supplied Report-tab text (e.g. from `renderMarkdownRecord`/`textReport`) — kept as a pure
      *  input so this leaf never reads config/telemetry itself. */