tickmarkr 2.5.6 → 2.5.8

package/dist/compile/retired-literals.d.ts

@@ -0,0 +1,22 @@
+import type { Task } from "../graph/schema.js";
+/** The file-system seam: tests substitute it to stage an unreadable file or a truncated read. */
+export interface PinScanIo {
+    size(abs: string): number;
+    read(abs: string): Buffer;
+    /** stat-following; throws like statSync (ENOENT for a broken link). */
+    isDirectory(abs: string): boolean;
+    /** stat-following: a regular file (or a link resolving to one) — never a FIFO, socket or device. */
+    isFile(abs: string): boolean;
+}
+export interface LiteralHit {
+    path: string;
+    line: number;
+}
+/** Each line of `content` holding `text`, 1-based. */
+export declare function literalHits(path: string, content: string, text: string): LiteralHit[];
+/**
+ * One line per uncovered obligation or uncertifiable scan; empty means every declared pin is covered
+ * by the task that declares it. Ownership by any OTHER task — merged predecessor or downstream — is
+ * named in the diagnostic and is no substitute.
+ */
+export declare function retiredLiteralErrors(tasks: ReadonlyArray<Pick<Task, "id" | "files" | "pins">>, repoRoot: string, io?: PinScanIo): string[];

package/dist/compile/retired-literals.js

@@ -0,0 +1,271 @@
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { filesGlob, literalParens } from "../graph/files-glob.js";
+const NODE_IO = {
+    size: (abs) => statSync(abs).size,
+    read: (abs) => readFileSync(abs),
+    isDirectory: (abs) => statSync(abs).isDirectory(),
+    isFile: (abs) => statSync(abs).isFile(),
+};
+const cause = (error) => (error instanceof Error ? error.message : String(error));
+const patternsOf = (pin) => (pin.kind === "literal" ? [pin.glob] : pin.paths);
+/** Leading segments with no glob syntax at all (never the last): every match of the pattern sits under them. */
+const literalBase = (pattern) => {
+    const segs = literalParens(pattern).split("/");
+    const wild = segs.findIndex((s) => !/^[\w.-]+$/.test(s) || s === "..");
+    return segs.slice(0, Math.min(wild < 0 ? segs.length : wild, segs.length - 1)).join("/");
+};
+/**
+ * picomatch's brace semantics are expansion (`{a,b/c}/x` ≡ `a/x`, `b/c/x`; `\,` and `\{` are literal):
+ * every top-level comma-holding brace is expanded until none remains, so a slash inside a brace is an
+ * honest segment boundary. A brace with no top-level comma (`{a}`, `{1..3}`) is left for filesGlob.
+ */
+function expandBraces(pattern) {
+    let depth = 0;
+    let open = -1;
+    let alts = [];
+    let last = -1;
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "\\")
+            i++;
+        else if (c === "{") {
+            if (depth++ === 0) {
+                open = i;
+                last = i + 1;
+                alts = [];
+            }
+        }
+        else if (c === "," && depth === 1) {
+            alts.push(pattern.slice(last, i));
+            last = i + 1;
+        }
+        else if (c === "}" && depth > 0 && --depth === 0) {
+            if (!alts.length)
+                continue; // no top-level comma: a literal or range brace, not an alternation
+            alts.push(pattern.slice(last, i));
+            const head = pattern.slice(0, open);
+            const tail = pattern.slice(i + 1);
+            return alts.flatMap((a) => expandBraces(head + a + tail));
+        }
+    }
+    return [pattern];
+}
+/** Split on "/" where it is a segment boundary; null when a slash is escaped or sits inside brackets. */
+function segmentsOf(pattern) {
+    const out = [""];
+    let depth = 0;
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "\\") {
+            if (pattern[i + 1] === "/")
+                return null;
+            out[out.length - 1] += c + (pattern[++i] ?? "");
+        }
+        else if (c === "/") {
+            if (depth)
+                return null;
+            out.push("");
+        }
+        else {
+            if (c === "[")
+                depth++;
+            else if (c === "]" && depth)
+                depth--;
+            out[out.length - 1] += c;
+        }
+    }
+    return out;
+}
+/**
+ * Does `alt` (brace-free) match EVERY path beneath `d`? Only a trailing globstar right after a matched prefix
+ * proves it; a globstar before that may swallow any run of `d`'s segments (`**\/cache/**` covers fixtures/cache/loop).
+ */
+function coversBeneath(alt, d) {
+    const segs = segmentsOf(alt);
+    if (!segs)
+        return false;
+    const covers = (si, di) => {
+        if (si >= segs.length)
+            return false;
+        if (segs[si] === "**") {
+            if (si === segs.length - 1)
+                return true;
+            for (let k = di; k <= d.length; k++)
+                if (covers(si + 1, k))
+                    return true;
+            return false;
+        }
+        if (di >= d.length)
+            return false;
+        // the prefix is matched as ONE pattern: a standalone `!cache` segment would read as a negation
+        return filesGlob(segs.slice(0, si + 1).join("/"))(d.slice(0, di + 1).join("/")) && covers(si + 1, di + 1);
+    };
+    return covers(0, 0);
+}
+/**
+ * Could `pattern` match a path strictly beneath directory `dir`? Matcher-consistent by construction:
+ * braces are expanded the way picomatch reads them, then every segment prefix is decided by filesGlob itself,
+ * and only an exact `**` segment is a globstar (`**.txt` is one ordinary segment). A leading `!` matches
+ * every path its body does not, so it reaches beneath `dir` unless some branch of the body provably covers
+ * all of it. What still cannot be split soundly (an escaped or bracketed slash) answers yes rather than certify blind.
+ */
+function reachesBeneath(pattern, dir) {
+    const p = pattern.replace(/^\.\//, "");
+    const d = dir ? dir.split("/") : [];
+    if (p.startsWith("!"))
+        return !expandBraces(literalParens(p.slice(1))).some((alt) => coversBeneath(alt, d));
+    return expandBraces(literalParens(p)).some((alt) => {
+        const segs = segmentsOf(alt);
+        if (!segs)
+            return true;
+        for (let i = 0; i < d.length; i++) {
+            if (i >= segs.length)
+                return false;
+            if (segs[i] === "**")
+                return true;
+            // the prefix is matched as ONE pattern: a standalone `!cache` segment would read as a negation
+            if (!filesGlob(segs.slice(0, i + 1).join("/"))(d.slice(0, i + 1).join("/")))
+                return false;
+        }
+        return segs.length > d.length;
+    });
+}
+/**
+ * Every non-directory path at or under `base`, decided later by filesGlob alone. NOTHING is pruned:
+ * not .git, not node_modules, not ignored files, not the state dir — the declared glob is the only
+ * narrowing (the literal base is exact: no match can sit outside it). A directory symlink is
+ * followed so matches behind it are listed under the symlink's own path; a link back into its own
+ * ancestry has no finite listing, so it refuses by name instead of being skipped.
+ * ponytail: a rootless glob such as ** / *.txt walks node_modules too; narrow the glob if that is slow.
+ */
+function walkAll(repoRoot, base, io) {
+    const out = { paths: [], causes: [] };
+    const visit = (rel, chain) => {
+        const abs = join(repoRoot, rel);
+        let isDir;
+        try {
+            isDir = io.isDirectory(abs);
+        }
+        catch (error) {
+            try {
+                // only a confirmed ENOENT is a known non-directory: a broken link stays a candidate whose read names the cause
+                if (error.code === "ENOENT") {
+                    if (lstatSync(abs, { throwIfNoEntry: false }))
+                        out.paths.push(rel);
+                    return;
+                }
+            }
+            catch { /* the lstat failed too: fall through to the refusal */ }
+            // anything else may be a directory hiding obligations: never a candidate that a glob could filter away
+            out.causes.push({ at: rel, why: `unstattable path ${rel || "."} (${cause(error)})`, maybeFile: true });
+            return;
+        }
+        if (!isDir) {
+            if (rel)
+                out.paths.push(rel);
+            return;
+        }
+        try {
+            const real = realpathSync(abs);
+            if (chain.includes(real)) {
+                out.causes.push({ at: rel, why: `symlink cycle at ${rel} cannot be enumerated`, maybeFile: false });
+                return;
+            }
+            for (const name of readdirSync(abs).sort())
+                visit(rel ? `${rel}/${name}` : name, [...chain, real]);
+        }
+        catch (error) {
+            out.causes.push({ at: rel, why: `unlistable directory ${rel || "."} (${cause(error)})`, maybeFile: false });
+        }
+    };
+    visit(base, []);
+    return out;
+}
+/** Whole-file read, or a thrown cause: a short read is never evidence of absence. */
+function readWhole(repoRoot, rel, io) {
+    const abs = join(repoRoot, rel);
+    let size;
+    let bytes;
+    try {
+        // a FIFO, socket or device has no finite whole to read: refuse it by kind before any read could block
+        if (!io.isFile(abs))
+            throw new Error(`unsupported file ${rel} (not a regular file)`);
+        size = io.size(abs);
+        bytes = io.read(abs);
+    }
+    catch (error) {
+        throw new Error(`unreadable file ${rel} (${cause(error)})`);
+    }
+    if (bytes.length !== size)
+        throw new Error(`truncated read of ${rel} (${bytes.length} of ${size} bytes)`);
+    return bytes.toString("utf8");
+}
+/** Each line of `content` holding `text`, 1-based. */
+export function literalHits(path, content, text) {
+    return content.split("\n").flatMap((line, i) => (line.includes(text) ? [{ path, line: i + 1 }] : []));
+}
+const pinName = (pin) => pin.kind === "literal" ? `literal ${JSON.stringify(pin.text)} in ${pin.glob}` : `fixture pin ${pin.paths.join(", ")}`;
+/**
+ * One line per uncovered obligation or uncertifiable scan; empty means every declared pin is covered
+ * by the task that declares it. Ownership by any OTHER task — merged predecessor or downstream — is
+ * named in the diagnostic and is no substitute.
+ */
+export function retiredLiteralErrors(tasks, repoRoot, io = NODE_IO) {
+    const declaring = tasks.filter((t) => t.pins?.length);
+    if (!declaring.length)
+        return [];
+    const walks = new Map();
+    const walked = (base) => walks.get(base) ?? walks.set(base, walkAll(repoRoot, base, io)).get(base);
+    const owns = new Map(tasks.map((t) => [t.id, filesGlob(t.files.map((f) => f.replace(/^\.\//, "")))]));
+    const errors = [];
+    for (const task of declaring) {
+        const owner = (path) => {
+            const others = tasks.filter((t) => t.id !== task.id && owns.get(t.id)(path)).map((t) => t.id);
+            return others.length
+                ? `owned by ${others.join(", ")}, which is no substitute: add it to ${task.id}.files[]`
+                : `owned by no task: add it to ${task.id}.files[]`;
+        };
+        for (const pin of task.pins) {
+            const matches = filesGlob(patternsOf(pin));
+            const found = [...new Set(patternsOf(pin).map((p) => literalBase(p.replace(/^\.\//, ""))))].map(walked);
+            // a cause refuses only a pin that could match at or beneath it: a cycle under fixtures/sub never refuses fixtures/*.txt
+            const affects = (c) => (c.maybeFile && matches(c.at)) || patternsOf(pin).some((p) => reachesBeneath(p, c.at));
+            const causes = [...new Set(found.flatMap((w) => w.causes).filter(affects).map((c) => c.why))];
+            for (const why of causes)
+                errors.push(`${task.id}: ${pinName(pin)} refuses certification: ${why}`);
+            const refused = causes.length > 0;
+            const surface = [...new Set(found.flatMap((w) => w.paths))].filter(matches).sort();
+            if (!surface.length) {
+                if (refused)
+                    continue; // the refusal above already names why nothing was certified
+                errors.push(`${task.id}: ${pinName(pin)} refuses certification: empty search surface (the pattern matches no file)`);
+                continue;
+            }
+            for (const path of surface) {
+                const owned = owns.get(task.id)(path);
+                // both kinds certify a whole-file read first: an owned fixture nobody could read is not evidence
+                let content;
+                try {
+                    content = readWhole(repoRoot, path, io);
+                }
+                catch (error) {
+                    errors.push(`${task.id}: ${pinName(pin)} refuses certification: ${cause(error)}`);
+                    continue;
+                }
+                if (pin.kind === "fixture") {
+                    if (!owned)
+                        errors.push(`${task.id}: ${pinName(pin)} obligates ${path}, outside ${task.id}.files[] (${owner(path)})`);
+                    continue;
+                }
+                const hits = literalHits(path, content, pin.text);
+                if (owned)
+                    continue;
+                for (const hit of hits) {
+                    errors.push(`${task.id}: ${pinName(pin)} still appears at ${hit.path}:${hit.line}, outside ${task.id}.files[] (${owner(path)})`);
+                }
+            }
+        }
+    }
+    return errors;
+}

package/dist/drivers/index.d.ts

@@ -13,9 +13,11 @@ export declare function classifyHost(env?: NodeJS.ProcessEnv): ClassifiedHost;
 /**
  * A config driver of herdr or orca whose host is not the classified one is refused naming the
  * detected host, the config line and the --driver remedy. Any explicit --driver value bypasses
- * this; auto and subprocess are never refused.
+ * that; auto and subprocess are never refused. Then, when the RESOLVED driver is orca (config,
+ * auto on an Orca host, or an explicit flag), the run root is admitted by one probe before any run
+ * directory, journal row or dispatch exists. Subprocess and herdr selections probe nothing.
  */
-export declare function preflightHostDriver(cfg: TickmarkrConfig, driverOverride: string | undefined, host: ClassifiedHost): void;
+export declare function preflightHostDriver(cfg: TickmarkrConfig, driverOverride: string | undefined, host: ClassifiedHost, runRoot: string, env?: NodeJS.ProcessEnv): Promise<void>;
 /**
  * Orca authors both markers on every terminal it creates. Requiring the pair avoids treating an
  * unrelated TERM_PROGRAM value or a copied terminal handle as host identity. This is deliberately

package/dist/drivers/index.js

@@ -1,5 +1,7 @@
 import { HerdrDriver } from "./herdr.js";
-import { OrcaDriver } from "./orca.js";
+import { shq } from "../adapters/types.js";
+import { sh } from "../run/git.js";
+import { canonicalWorktreePath, OrcaDriver, OrcaError, parseEnvelope, resolveOrcaCliBinary, terminalWorktree } from "./orca.js";
 import { SubprocessDriver } from "./subprocess.js";
 export const DRIVER_CHOICES = ["auto", "herdr", "subprocess", "orca"];
 const overrideByDriver = new WeakMap();
@@ -20,18 +22,64 @@ export function classifyHost(env = process.env) {
         return "orca";
     return "none";
 }
+const UNMANAGED_CHECKOUT = "checkout is not Orca-managed; run from an orca worktree create checkout or pass --driver subprocess";
+/**
+ * OBS-1061: the ONE admission probe — `worktree current` asked from the run root. Like the driver's
+ * own per-checkout query it accepts an enclosing tracked checkout after path canonicalisation. An
+ * untracked checkout refuses with both remedies; any other failure refuses naming its reason, never
+ * read as managed.
+ */
+async function admitOrcaCheckout(runRoot, env) {
+    const bin = resolveOrcaCliBinary(runRoot, { env }) ?? "orca";
+    const refuse = (reason) => new Error(`refusing driver 'orca': Orca admission probe of ${runRoot} failed — ${reason}`);
+    let reported;
+    // The transport's own diagnostics (timeout, exit, stderr): a stderr-only failure such as a missing
+    // executable parses as 'empty response', which alone names no cause.
+    let transport = "";
+    try {
+        // Config values flow into a shell here: every argv element is quoted, always.
+        const r = await sh([bin, "worktree", "current", "--json"].map(shq).join(" "), runRoot);
+        const raw = [r.stdout, r.stderr ? `STDERR: ${r.stderr}` : ""].filter(Boolean).join("\n");
+        transport = [r.timedOut ? "probe timed out" : r.code !== 0 ? `orca exited ${r.code}` : "", r.stderr.trim() ? `stderr: ${r.stderr.trim()}` : ""]
+            .filter(Boolean).join("; ");
+        const envelope = parseEnvelope("worktree-current", r.stdout, raw);
+        // An ok:true body on a nonzero exit is a transport failure (stale stdout), as in the driver.
+        if (r.code !== 0)
+            throw new OrcaError("worktree-current", `orca exited ${r.code}`, raw);
+        const worktree = envelope.result.worktree;
+        reported = typeof worktree === "object" && worktree !== null && !Array.isArray(worktree)
+            ? terminalWorktree(worktree)
+            : undefined;
+        if (!reported)
+            throw new OrcaError("worktree-current", "response carries no worktree path", raw);
+    }
+    catch (e) {
+        if (e instanceof OrcaError && e.code === "selector_not_found")
+            throw new Error(`refusing driver 'orca': ${UNMANAGED_CHECKOUT}`);
+        const reason = e instanceof OrcaError ? e.reason : e.message;
+        throw refuse(transport.startsWith(reason) ? transport : [reason, transport].filter(Boolean).join("; "));
+    }
+    const tracked = canonicalWorktreePath(reported);
+    const root = canonicalWorktreePath(runRoot);
+    if (tracked !== root && !root.startsWith(`${tracked}/`))
+        throw new Error(`refusing driver 'orca': ${UNMANAGED_CHECKOUT}`);
+}
 /**
  * A config driver of herdr or orca whose host is not the classified one is refused naming the
  * detected host, the config line and the --driver remedy. Any explicit --driver value bypasses
- * this; auto and subprocess are never refused.
+ * that; auto and subprocess are never refused. Then, when the RESOLVED driver is orca (config,
+ * auto on an Orca host, or an explicit flag), the run root is admitted by one probe before any run
+ * directory, journal row or dispatch exists. Subprocess and herdr selections probe nothing.
  */
-export function preflightHostDriver(cfg, driverOverride, host) {
-    if (driverOverride !== undefined)
-        return;
-    if ((cfg.driver === "herdr" || cfg.driver === "orca") && cfg.driver !== host) {
+export async function preflightHostDriver(cfg, driverOverride, host, runRoot, env = process.env) {
+    if (driverOverride === undefined && (cfg.driver === "herdr" || cfg.driver === "orca") && cfg.driver !== host) {
         const remedy = host === "none" ? "subprocess" : host;
         throw new Error(`refusing driver '${cfg.driver}' (config line 'driver: ${cfg.driver}'): detected host is ${host}; use --driver ${remedy} to override`);
     }
+    const want = parseDriverOverride(driverOverride) ?? cfg.driver;
+    const resolved = want === "auto" ? (host === "none" ? "subprocess" : host) : want;
+    if (resolved === "orca")
+        await admitOrcaCheckout(runRoot, env);
 }
 /**
  * Orca authors both markers on every terminal it creates. Requiring the pair avoids treating an

package/dist/gates/baseline.d.ts

@@ -1,6 +1,6 @@
 import type { TickmarkrConfig } from "../config/config.js";
 import type { AcceptanceItem } from "../graph/schema.js";
-import { type RunCapacity, type ShResult } from "../run/git.js";
+import { type RunCapacity, type ShellOptions, type ShResult } from "../run/git.js";
 import type { GateResult } from "./types.js";
 /**
  * T7: the capacity a gate's own command ran under rides the RESULT, beside the verdict it explains,
@@ -157,7 +157,12 @@ export declare const CAPTURE_CEILING_MS = 1800000;
 /** OBS-1044: a cached vitest entry whose count is a stdout sum may be inflated; only a manifest-derived
  * count is safe to apply as a deficit floor. A null count compares nothing and is safe as-is. */
 export declare function staleFileCountCommands(baseline: Baseline, commands: Record<string, string>, cwd: string): string[];
-export declare function captureBaseline(cwd: string, commands: Record<string, string>): Promise<Baseline>;
+export interface BaselineReceiptOptions {
+    onReceipt?: ShellOptions["onReceipt"];
+    /** Only comparison's build command may carry task-build identity; capture never does. */
+    taskBuildAttribution?: ShellOptions["receiptAttribution"];
+}
+export declare function captureBaseline(cwd: string, commands: Record<string, string>, opts?: BaselineReceiptOptions): Promise<Baseline>;
 export interface VacuousOracleWarning {
     kind: "vacuous-oracle";
     taskId: string;
@@ -171,7 +176,7 @@ export declare function detectVacuousOracles(cwd: string, tasks: ReadonlyArray<{
 export interface RetryOptions {
     authorizeRetry?: (cause: "infra" | "host-starved") => boolean;
 }
-export declare function compareToBaseline(cwd: string, commands: Record<string, string>, baseline: Baseline, enabled: string[], opts?: RetryOptions & {
+export declare function compareToBaseline(cwd: string, commands: Record<string, string>, baseline: Baseline, enabled: string[], opts?: RetryOptions & BaselineReceiptOptions & {
     rerunOf?: HostStarvedRerun;
     infraRerun?: HostStarvedRerun;
     selected?: readonly string[];

package/dist/gates/baseline.js

@@ -487,13 +487,13 @@ export function staleFileCountCommands(baseline, commands, cwd) {
     })
         .map(([name]) => name);
 }
-export async function captureBaseline(cwd, commands) {
+export async function captureBaseline(cwd, commands, opts = {}) {
     const base = { commands: {} };
     for (const [name, cmd] of Object.entries(commands)) {
         if (name === "tipTest" && commands.test !== undefined && cmd === commands.test) {
             continue;
         }
-        const r = await sh(cmd, cwd, CAPTURE_CEILING_MS);
+        const r = await sh(cmd, cwd, CAPTURE_CEILING_MS, { onReceipt: opts.onReceipt });
         // ponytail: strip the executing cwd so repo-root capture and worktree compare fingerprint identically; /private-vs-/tmp symlink variance is out of scope
         // ponytail: a capture that was itself killed records the ceiling as its "measurement", which
         // scales the next ceiling up — the right direction for a suite that never finished once.
@@ -634,7 +634,10 @@ export async function compareToBaseline(cwd, commands, baseline, enabled, opts =
         }
         const entry = baseline.commands[name];
         const ceilingMs = effectiveCeilingMs(entry);
-        const r = await sh(cmd, cwd, ceilingMs);
+        const r = await sh(cmd, cwd, ceilingMs, {
+            onReceipt: opts.onReceipt,
+            ...(name === "build" ? { receiptAttribution: opts.taskBuildAttribution } : {}),
+        });
         // T7: every verdict below carries the capacity ITS OWN command ran under, taken off the shell
         // result rather than re-derived after the fact. The skip row above ran no command and therefore
         // states no capacity — a row that never divided the machine must not claim that it did.

package/dist/gates/review.js

@@ -185,7 +185,10 @@ export { modelProvider };
 export function matchClosureId(candidate, target) {
     if (typeof candidate !== "string")
         return typeof target === "string" ? false : undefined;
-    const normCandidate = candidate.replace(/\s+/g, "");
+    // OBS-1068: the brief's copy block printed each id as `Fingerprint: <id>` and told the seat to copy
+    // it EXACTLY — three faithful approvals in one run were discarded as closure-mismatch. A leading
+    // `Fingerprint:` label is the brief's own wording, never the reviewer's id; strip it before comparing.
+    const normCandidate = candidate.replace(/^\s*fingerprint\s*:\s*/i, "").replace(/\s+/g, "");
     if (typeof target === "string") {
         return normCandidate === target.replace(/\s+/g, "");
     }
@@ -476,6 +479,11 @@ carriedAuthors = []) {
         return capFail;
     const nonce = generateVerdictNonce();
     const repoRoot = daemonRepoRoot(worktree, artifactDir);
+    // OBS-880 add.1: guidance only. Do not expand scope globs into permission to run suites.
+    const ownTestFiles = [...new Set(task.files.filter((file) => !/[*?[\]{}()!]/.test(file) && /(?:^|\/)[^/]*\.(?:test|spec)\.[cm]?[jt]sx?$/.test(file)))];
+    const suiteBudget = ownTestFiles.length
+        ? `You may run at most the task's own test files explicitly named in files[]; these are the only suites you may run: ${ownTestFiles.map((file) => `\`${file}\``).join(", ")}.`
+        : "No suite may be run: files[] names no explicit test file owned by this task.";
     const prompt = `TICKMARKR-REVIEW
 You are a skeptical cross-vendor code reviewer. Another agent (vendor: ${author.adapter}) authored this diff.
 Look for correctness bugs, security issues, and acceptance-criteria gaps. Approve only if you would merge it.
@@ -489,6 +497,9 @@ ${task.acceptance.map((a) => `- ${renderAcceptanceItem(a)}`).join("\n")}
 
 ${renderDeclaredWriteScope(task.files)}
 
+## Reviewer suite budget
+${suiteBudget} Never run the whole suite (including an unfiltered npm test or vitest run). The gate suite owns the runner lease; a parallel full suite starves the gate.
+
 ${priorMaterials.length ? `${renderPriorMaterials(priorMaterials)}
 
 ` : ""}## Diff

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

@@ -1,3 +1,4 @@
+import type { CommandReceiptAttribution } from "../run/protocol.js";
 import { type Assignment, type BillingChannel, type WorkerAdapter, type WorkerResult } from "../adapters/types.js";
 import { type TickmarkrConfig } from "../config/config.js";
 import { type GateName, type Task } from "../graph/schema.js";
@@ -42,9 +43,10 @@ export type GateEvent = {
     gate: GateName;
     name: string;
     payload: Record<string, unknown>;
-    result: GateResult;
+    result?: GateResult;
 };
 export interface GateContext {
+    buildReceiptIdentity?: Omit<CommandReceiptAttribution, "invocation">;
     authorizeInfraRetry?: (subject: string, cause?: VerificationRetryCause) => boolean;
     verificationScope?: VerificationScope;
     worktree: string;
@@ -62,6 +64,9 @@ export interface GateContext {
     excludeReviewers?: string[];
     demotedReviewers?: Set<string>;
     reviewNoVerdicts?: Map<string, string[]>;
+    recheck?: boolean;
+    /** Explicit worker funding requires fresh red measurements, never a gate waiver. */
+    cachedRedBypass?: "operator-rerun";
     carriedAuthors?: readonly string[];
     reviewHistory?: string[];
     priorReviewers?: PriorReviewer[];

package/dist/gates/run-gates.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { loadavg, tmpdir } from "node:os";
 import { join, posix } from "node:path";
@@ -258,6 +259,40 @@ function classifySignalOnlyTest(g) {
 }
 export async function runGates(task, ctx) {
     const results = [];
+    // Receipt identity belongs to this round, never to a cached verdict. Each call from the shell
+    // allocates a new invocation, including retries whose local spawn counter starts at one again.
+    let currentBuild;
+    let buildStarted = false;
+    let receiptNotes = Promise.resolve();
+    const beginBuild = () => {
+        buildStarted = false;
+        currentBuild = { ...(ctx.buildReceiptIdentity ?? {
+                runId: ctx.artifactDir ?? "standalone", taskId: task.id, attempt: 0, gateRound: 0,
+            }), invocation: randomUUID() };
+        return { ...currentBuild };
+    };
+    const buildReceipt = (receipt, reason) => {
+        const matches = currentBuild !== undefined && receipt.attribution !== undefined
+            && Object.keys(currentBuild)
+                .every((key) => receipt.attribution[key] === currentBuild[key]);
+        const attributed = matches && (receipt.outcome === "started" || !receipt.confirmedStart || buildStarted);
+        if (attributed)
+            buildStarted = receipt.outcome === "started";
+        const { attribution, ...observation } = receipt;
+        const payload = attributed ? { ...receipt, gate: "build", ...(reason ? { reason, freshBuildRan: false } : {}) } : {
+            ...observation, gate: "build", attributionStatus: "unattributed",
+            reportedAttribution: attribution,
+        };
+        // Shell observers are synchronous. Serialize asynchronous note sinks and drain before the
+        // verdict (also on cancellation), without letting an observer change execution or retry policy.
+        receiptNotes = receiptNotes.then(async () => {
+            await ctx.onGate?.({ phase: "note", gate: "build", name: "build-receipt", payload });
+        }).catch(() => { });
+    };
+    const noBuild = async (outcome, reason) => {
+        buildReceipt({ outcome, confirmedStart: false, attribution: beginBuild() }, reason);
+        await receiptNotes;
+    };
     let selectionDecision;
     let commits = [];
     const stateDir = ctx.stateDir ?? resolveStateDir(ctx.worktree, ctx.artifactDir);
@@ -272,6 +307,16 @@ export async function runGates(task, ctx) {
     // the ledger names the reuse and the identity even where the gate-result row's details must stay
     // the fresh verdict's (see formatReusedRow).
     const noteReuse = (gate, r, id) => ctx.onGate?.({ phase: "note", gate, name: "gate-reused-verdict", payload: { gate, pass: r.pass, details: r.meta?.reusedDetails, ...reusedIdentity(id) }, result: r });
+    // OBS-1055: on a recheck a cached red is the answer the operator just said was wrongly given; it is
+    // journaled as discarded and the gate runs. Returns true when the hit must NOT be reused.
+    const discardCachedRed = async (gate, hit) => {
+        const reason = ctx.recheck ? "recheck" : ctx.cachedRedBypass;
+        if (!reason || hit.pass)
+            return false;
+        await ctx.onGate?.({ phase: "note", gate, name: reason === "recheck" ? "recheck-rerun" : "gate-rerun",
+            payload: { gate, reason: "cached-red-discarded", ...(reason === "recheck" ? {} : { bypass: reason }) }, result: hit });
+        return true;
+    };
     const shapeGates = ctx.cfg.gates.byShape?.[task.shape];
     const enabled = (g) => task.gates.includes(g) && (g !== "acceptance" && g !== "review" || shapeGates?.[g] !== false);
     const failed = () => results.some((r) => !r.pass);
@@ -595,20 +640,30 @@ export async function runGates(task, ctx) {
                 const hit = verdictStore.get(identity);
                 if (hit)
                     classifySignalOnlyTest(hit); // Older entries predate classification at the write seam.
-                if (hit && identity && !isInfraResult(hit) && (hit.pass || (ctx.verificationScope ?? "battery") === "battery")) {
+                if (hit && identity && !isInfraResult(hit) && (hit.pass || (ctx.verificationScope ?? "battery") === "battery")
+                    && !(await discardCachedRed(g, hit))) {
                     r = formatReusedRow(hit, identity);
                     cached = true;
+                    if (g === "build")
+                        await noBuild("reused-result", "verdict reused; no fresh build ran in this invocation");
                     await noteReuse(g, r, identity);
                 }
             }
             if (!r) {
-                // VL-1: a detected vitest test command is judged by its own invocation-bound report — the
-                // stdout-count/file-count path (compareToBaseline's fileCountDeficit) never runs for it. Any
-                // other scripted test command keeps today's exit-code contract byte-identically.
-                const useManifest = g === "test" && commands.test !== undefined && isVitestTestCommand(commands.test, ctx.worktree);
-                r = useManifest
-                    ? await measure(g, () => runVitestManifestGate(ctx.worktree, commands.test, ctx.baseline, selected, ctx.artifactDir, retryOptions(identity)))
-                    : (await measure(g, () => compareToBaseline(ctx.worktree, commands, ctx.baseline, [g], { ...retryOptions(identity), ...(g === "test" && selected ? { selected } : {}) })))[0];
+                if (g === "build" && !cmd)
+                    await noBuild("skipped", "no build command detected");
+                try {
+                    // VL-1: a detected vitest test command is judged by its own invocation-bound report — the
+                    // stdout-count/file-count path (compareToBaseline's fileCountDeficit) never runs for it. Any
+                    // other scripted test command keeps today's exit-code contract byte-identically.
+                    const useManifest = g === "test" && commands.test !== undefined && isVitestTestCommand(commands.test, ctx.worktree);
+                    r = useManifest
+                        ? await measure(g, () => runVitestManifestGate(ctx.worktree, commands.test, ctx.baseline, selected, ctx.artifactDir, retryOptions(identity)))
+                        : (await measure(g, () => compareToBaseline(ctx.worktree, commands, ctx.baseline, [g], { ...retryOptions(identity), ...(g === "build" ? { onReceipt: buildReceipt, taskBuildAttribution: beginBuild } : {}), ...(g === "test" && selected ? { selected } : {}) })))[0];
+                }
+                finally {
+                    await receiptNotes;
+                }
             }
             // the screen's interval IS the test gate's first interval, so the split needs no second clock
             if (g === "test" && selected)
@@ -929,6 +984,8 @@ export async function runGates(task, ctx) {
     if (entryDirt) {
         addMeasurement(sequence[0], entryMeasurement);
         await emitStart(sequence[0]);
+        if (enabled("build"))
+            await noBuild("refused", "dirty worktree; no build start confirmed");
         await record(await dirtyRefusal(sequence[0], entryDirt));
         return done();
     }
@@ -1037,7 +1094,8 @@ export async function runGates(task, ctx) {
             const hit = verdictStore.get(identity);
             if (hit)
                 classifySignalOnlyTest(hit);
-            if (hit && identity && !isInfraResult(hit) && (hit.pass || (ctx.verificationScope ?? "battery") === "battery")) {
+            if (hit && identity && !isInfraResult(hit) && (hit.pass || (ctx.verificationScope ?? "battery") === "battery")
+                && !(await discardCachedRed("test", hit))) {
                 full = formatReusedRow(hit, identity);
                 cached = true;
                 await noteReuse("test", full, identity);