tickmarkr 1.87.0 → 1.90.0

package/dist/run/lock.js

@@ -17,8 +17,10 @@ export const STALE_MS = 60_000; // 6× heartbeat headroom; PITFALLS floor is ≥
 // pid/runId/startedAt are ever read; anything else is ignored (info-disclosure surface).
 const PayloadSchema = z.object({ pid: z.number().int().positive(), runId: z.string(), startedAt: z.number() });
 const lockPath = (repoRoot) => join(tickmarkrDir(repoRoot), "graph.lock");
+const approvalSerializationPath = (repoRoot) => join(tickmarkrDir(repoRoot), "approval.lock");
 let heartbeat;
 let heldPath;
+let approvalSequence = 0;
 // Best-effort release if the daemon exits without hitting its finally (crash mid-body). NO
 // SIGINT/SIGTERM handlers — those change kill semantics and leak listeners across the test
 // suite's many runDaemon calls; signal-death is exactly what stale-reclaim exists for.
@@ -141,16 +143,105 @@ export function releaseRunLock(repoRoot) {
     unlinkIfOurs(lockPath(repoRoot)); // never delete a reclaiming successor's lock — only ours
     heldPath = undefined;
 }
+// T14: task-approved append and the terminal outstandingApprovals sample + run-end append are one
+// cross-process critical section. The daemon keeps this boundary until AFTER it releases graph.lock:
+// an approval wins first and is necessarily in run-end, or run-end wins first and the command cannot
+// append until there is no live owner. There is no interval in which an accepted approval can land
+// behind the completion sample while graph.lock still makes it look deferred to that daemon.
+//
+// The boundary uses the same atomic link(2) idiom and the same inspect() authority as graph.lock.
+// A dead holder is reclaimed with the same inode+mtime guard; a live holder is waited out; garbage
+// fails closed. No caller re-derives pid liveness.
+export async function acquireApprovalSerialization(repoRoot, runId) {
+    const p = approvalSerializationPath(repoRoot);
+    let contended = false;
+    while (true) {
+        const tmp = join(tickmarkrDir(repoRoot), `approval.lock.${process.pid}.${approvalSequence++}.tmp`);
+        try {
+            writeFileSync(tmp, JSON.stringify({ pid: process.pid, runId, startedAt: Date.now() }));
+            try {
+                linkSync(tmp, p);
+            }
+            finally {
+                unlinkSync(tmp);
+            }
+            let released = false;
+            return {
+                contended,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    unlinkIfOurs(p);
+                },
+            };
+        }
+        catch (e) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* link loser already cleaned its private temporary */ }
+            if (e.code !== "EEXIST")
+                throw e;
+            contended = true;
+            let insp;
+            try {
+                insp = inspect(p);
+            }
+            catch (inspectError) {
+                if (inspectError.code === "ENOENT")
+                    continue;
+                throw inspectError;
+            }
+            if (insp.garbage) {
+                throw new Error(`${stateDirName(repoRoot)}/approval.lock holds an unreadable/garbage payload — refusing to cross the run-end boundary`);
+            }
+            if (insp.dead) {
+                let st;
+                try {
+                    st = statSync(p);
+                }
+                catch (statError) {
+                    if (statError.code === "ENOENT")
+                        continue;
+                    throw statError;
+                }
+                if (st.ino !== insp.ino || st.mtimeMs !== insp.mtimeMs)
+                    continue;
+                try {
+                    unlinkSync(p);
+                }
+                catch (e2) {
+                    if (e2.code !== "ENOENT")
+                        throw e2;
+                }
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+}
+// LOCK-04: the owner the decision table sees, read-only, for callers that need the pid as well as
+// the answer. inspect() owns pid-liveness (ESRCH dead / EPERM alive / garbage fail-closed); a second
+// `process.kill(pid, 0)` anywhere else would be a second copy of that rule, free to drift. undefined
+// ⇒ no lock at all — never conflate that with a lock whose recorded owner is dead.
+export function runLockOwner(repoRoot) {
+    let insp;
+    try {
+        insp = inspect(lockPath(repoRoot));
+    }
+    catch {
+        return undefined;
+    } // statSync ENOENT ⇒ not held
+    // `runId` is carried so a caller can name the run the live owner is actually executing — the lock is
+    // REPOSITORY-wide, so a live pid here is not proof it is running the run the caller cares about.
+    return { pid: insp.pid, runId: insp.runId, live: shouldRefuse(insp) };
+}
 // Read-only predicate: true iff a lock exists that the decision table would REFUSE on (alive,
 // EPERM, or ANY garbage). A provably-dead holder (ESRCH) reads not-live (LOCK-02/OBS-05). Never
 // mutates the lock. compile now acquires via acquireRunLock; this remains for drift oracles/tests.
 export function isRunLockLive(repoRoot) {
-    try {
-        return shouldRefuse(inspect(lockPath(repoRoot)));
-    }
-    catch {
-        return false;
-    } // no lock
+    return runLockOwner(repoRoot)?.live ?? false;
 }
 // LOCK-03: operator escape hatch. Liveness-checked delete — removes a dead-holder or garbage lock,
 // REFUSES to remove one whose holder is alive (incl. EPERM = alive-but-not-ours). No --force: the

package/dist/run/merge.d.ts

@@ -1,4 +1,5 @@
 import type { TickmarkrConfig } from "../config/config.js";
+import { type Baseline } from "../gates/baseline.js";
 export interface TipVerifyResult {
     gate: string;
     cmd: string;
@@ -7,6 +8,8 @@ export interface TipVerifyResult {
     fingerprints: string[];
     details: string;
     artifact?: string;
+    /** Q121s: nonzero exit whose failures are ALL baseline-recorded — forgiven exactly as the battery forgives. */
+    forgiven?: boolean;
 }
 export declare function integrationBranch(cfg: TickmarkrConfig, runId: string): string;
 export declare function ensureIntegration(repo: string, branch: string, baseRef: string): Promise<string>;
@@ -19,4 +22,4 @@ export declare function mergeTask(intWt: string, taskBranch: string, message: st
         branchTip: string;
     };
 }>;
-export declare function verifyIntegrationTip(intWt: string, commands: Record<string, string>, runDir: string): Promise<TipVerifyResult[]>;
+export declare function verifyIntegrationTip(intWt: string, commands: Record<string, string>, runDir: string, baseline?: Baseline): Promise<TipVerifyResult[]>;

package/dist/run/merge.js

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { shq } from "../adapters/types.js";
-import { fingerprint } from "../gates/baseline.js";
+import { classifyFailureOutput, fingerprint, freshFailures } from "../gates/baseline.js";
 import { tickmarkrDir } from "../graph/graph.js";
 import { gitHead, linkNodeModules, resolveIntegrationBranch, sh, shGit, shGitOk, WORKTREES_DIR } from "./git.js";
 export function integrationBranch(cfg, runId) {
@@ -44,22 +44,41 @@ export async function mergeTask(intWt, taskBranch, message, gatedCommit) {
     await shGit("git merge --abort", intWt);
     return { ok: false, conflict };
 }
-// OBS-34: strict exit-code verify on the integration tip — no baseline forgiveness.
-export async function verifyIntegrationTip(intWt, commands, runDir) {
+// OBS-34 ruled strict exit-code verify; Q121s (TRIAL T-OBS-1) narrows it: a red whose failure
+// fingerprints are ALL recorded in the run's baseline is forgiven with the battery's own math
+// (freshFailures) — on any repo whose main carries a pre-existing red, strict verify made a green
+// terminus unreachable by construction and misattributed the red to the last merged task.
+// Fail-closed edges kept: no baseline → strict; baseline green for that gate → strict; any fresh
+// fingerprint, or output with no recognizable failure shape, → failed.
+export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
     const results = [];
     for (const [gate, cmd] of Object.entries(commands)) {
         const r = await sh(cmd, intWt);
         const raw = r.stdout + "\n" + r.stderr;
-        const artifact = r.code !== 0 ? join(runDir, `tip-verify-${gate}.log`) : undefined;
+        const stripped = raw.split(intWt).join("");
+        const entry = baseline?.commands[gate];
+        const { failing, unreadable } = freshFailures(entry, stripped);
+        // `?? 1` is the battery's own default (baseline.ts compareToBaseline): an exitCode-less legacy
+        // entry reads as red-at-baseline there, so it must read the same here or old baselines silently
+        // lose forgiveness. Battery parity on the infra rule too (T9): infrastructure-only output means
+        // the runner never completed a suite — nothing was verified, so nothing is forgivable, however
+        // familiar its fingerprints. Stricter-than-battery edge kept: unreadable output never forgives.
+        const forgiven = r.code !== 0 && entry !== undefined && (entry.exitCode ?? 1) !== 0
+            && failing.length === 0 && !unreadable && classifyFailureOutput(stripped) !== "infra";
+        const pass = r.code === 0 || forgiven;
+        const artifact = pass ? undefined : join(runDir, `tip-verify-${gate}.log`);
         if (artifact)
             writeFileSync(artifact, raw);
         results.push({
             gate,
             cmd,
-            pass: r.code === 0,
+            pass,
             exitCode: r.code,
-            fingerprints: r.code !== 0 ? fingerprint(raw.split(intWt).join("")) : [],
-            details: r.code === 0 ? "exit 0" : `exit ${r.code}`,
+            fingerprints: r.code !== 0 ? fingerprint(stripped) : [],
+            details: r.code === 0 ? "exit 0"
+                : forgiven ? `exit ${r.code} but only baseline-recorded failures (forgiven vs baseline)`
+                    : `exit ${r.code}`,
+            ...(forgiven ? { forgiven: true } : {}),
             ...(artifact ? { artifact } : {}),
         });
     }

package/dist/run/outcome.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a gate phase did, closed. `passed` and `failed` are verdicts and carry nothing else; every
+ * other member is a NON-VERDICT and must say why, so no arm of this union can be produced without the
+ * reason a reader needs to act on it.
+ */
+export type GateOutcome = {
+    kind: "passed";
+} | {
+    kind: "failed";
+}
+/** The gate had nothing to run — the repository configures no such command (baseline.ts:262). */
+ | {
+    kind: "skipped";
+    reason: string;
+}
+/** A policy declined to run the gate that was configured (review.ts:411). */
+ | {
+    kind: "declined";
+    reason: string;
+}
+/** A green that is not yet the verdict — a screen the full suite has not superseded. */
+ | {
+    kind: "held";
+    reason: string;
+}
+/** The outcome could not be read at all. Never clean, never a pass. */
+ | {
+    kind: "unavailable";
+    reason: string;
+}
+/** The runner died on the machine, so the gate verified nothing whatever it reported. */
+ | {
+    kind: "infra";
+    reason: string;
+    retryable: boolean;
+};
+/** The closed table, as data — a consumer can range over the vocabulary without re-listing it. */
+export declare const GATE_OUTCOME_KINDS: readonly ["passed", "failed", "skipped", "declined", "held", "unavailable", "infra"];
+export type GateOutcomeKind = (typeof GATE_OUTCOME_KINDS)[number];
+type AssertNever<T extends never> = T;
+export type UntabledGateOutcomeKind = AssertNever<Exclude<GateOutcome["kind"], GateOutcomeKind>>;
+/**
+ * Read one gate outcome — canonical or legacy — as a member of the closed vocabulary.
+ *
+ * Takes `unknown` deliberately: the malformed row is a real input class, not a caller error. A journal
+ * row's `data` is `Record<string, unknown>` and a `GateResult`'s `{ ...meta }` spread is the same
+ * shape, so both pass without a cast and neither needs its own entry point.
+ */
+export declare function normalizeGateOutcome(source: unknown): GateOutcome;
+export {};

package/dist/run/outcome.js

@@ -0,0 +1,152 @@
+// T31 (F1 + Q18's producer half): ONE vocabulary for what a gate phase actually did, and ONE
+// normalizer that reads every shape the shipped record already writes into it.
+//
+// This module is a PRODUCER ONLY. It is a new file with no imports and no writes: nothing it exports
+// replaces or re-types an existing symbol, so capture.ts, demo.ts, live.ts, run-cockpit.tsx and
+// setup-cockpit.tsx — and every other current caller — compile exactly as before. It adds no general
+// reducer and no dual-write. The read-side wiring of status, the Markdown report, the proof bundle and
+// the retained derive projection is T41's; the typed writer half is T40's.
+//
+// Why a vocabulary at all. The legacy record spells a gate's NON-FAILURE across four disjoint fields —
+// `pass`, `skipped`, `verdict` and `infra` — and a row may state NONE of them: daemon.ts:1376 omits
+// `pass` entirely for a decline, because a review that did not run has no verdict to state. Every
+// consumer therefore re-derived the same question from raw fields, and each one that got it wrong read
+// a non-failure as a green. The union below makes that collapse unrepresentable: a gate that did not
+// run cannot be spelled `passed`, and a row nobody can read cannot be spelled clean.
+/** The closed table, as data — a consumer can range over the vocabulary without re-listing it. */
+export const GATE_OUTCOME_KINDS = [
+    "passed", "failed", "skipped", "declined", "held", "unavailable", "infra",
+];
+const stated = (value) => typeof value === "string" && value.trim() !== "" ? value : undefined;
+/**
+ * Every reason the row states, in the order the record writes them. A declined review populates BOTH
+ * fields with different facts — `reason` is the policy's reason, `details` the operator-facing
+ * sentence — so preferring either one alone would silently drop the other.
+ */
+function reasonOf(row, fallback) {
+    const reasons = [...new Set([stated(row.reason), stated(row.details)])].filter((r) => r !== undefined);
+    return reasons.join(" — ") || fallback;
+}
+// Presence, not truthiness, is the boundary: a canonical outcome and any one of the four fields that
+// spell legacy truth would be a dual-write. Treating even a consistent-looking pair as canonical
+// would let a contradictory legacy field become clean as soon as producers drifted apart.
+const LEGACY_OUTCOME_DISCRIMINATORS = ["pass", "skipped", "verdict", "infra"];
+const hasOwn = (row, field) => Object.prototype.hasOwnProperty.call(row, field);
+function legacyDiscriminatorsOf(row) {
+    return LEGACY_OUTCOME_DISCRIMINATORS.filter((field) => hasOwn(row, field));
+}
+/** The gates the baseline battery runs (run-gates.ts:203) — the only producer of a command-absent skip. */
+const BASELINE_GATES = new Set(["build", "test", "lint"]);
+/**
+ * The oldest declines predate the `skipped` field entirely and state the decline only in the details
+ * prefix ("skipped — complexity 4 < threshold 7"). This compatibility branch is limited to that
+ * historical shape: a review carrying the old `pass: true` encoding and neither modern decline
+ * discriminator. The ^ anchor is load-bearing too: a review that genuinely RAN can mention a skipped
+ * something mid-body, and a failed non-review gate can begin its diagnostic with that word.
+ */
+const declinedByDetails = (row) => row.gate === "review"
+    && row.pass === true
+    && !hasOwn(row, "skipped")
+    && !hasOwn(row, "verdict")
+    && /^skipped\b/.test(String(row.details ?? ""));
+/**
+ * Already-canonical input, validated arm by arm. This is what makes the normalizer idempotent over the
+ * vocabulary: T40 will publish typed outcomes while pre-T40 journals still hold legacy rows, and a
+ * projection must be able to call this on either without asking which era it is reading.
+ */
+function isGateOutcome(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const o = value;
+    if (legacyDiscriminatorsOf(o).length > 0)
+        return false;
+    switch (o.kind) {
+        case "passed":
+        case "failed":
+            return true;
+        case "skipped":
+        case "declined":
+        case "held":
+        case "unavailable":
+            return typeof o.reason === "string";
+        case "infra":
+            return typeof o.reason === "string" && typeof o.retryable === "boolean";
+        default:
+            return false;
+    }
+}
+/**
+ * Read one gate outcome — canonical or legacy — as a member of the closed vocabulary.
+ *
+ * Takes `unknown` deliberately: the malformed row is a real input class, not a caller error. A journal
+ * row's `data` is `Record<string, unknown>` and a `GateResult`'s `{ ...meta }` spread is the same
+ * shape, so both pass without a cast and neither needs its own entry point.
+ */
+export function normalizeGateOutcome(source) {
+    if (typeof source !== "object" || source === null || Array.isArray(source)) {
+        const shape = source === null ? "null" : Array.isArray(source) ? "an array" : typeof source;
+        return { kind: "unavailable", reason: `malformed gate result: expected an object, read ${shape}` };
+    }
+    const row = source;
+    // `kind` selects the canonical format. It must validate as exactly one canonical arm without any
+    // legacy truth discriminator; otherwise continuing through the legacy branches could reinterpret a
+    // contradictory dual-write as passed, failed or infra. Mixed and malformed canonical rows stay
+    // explicitly unavailable, retaining any reason/details the producer did manage to state.
+    if (hasOwn(row, "kind")) {
+        if (isGateOutcome(source))
+            return source;
+        const legacyFields = legacyDiscriminatorsOf(row);
+        const fallback = legacyFields.length > 0
+            ? `malformed gate result: canonical kind cannot carry legacy discriminator(s): ${legacyFields.join(", ")}`
+            : "malformed gate result: invalid canonical outcome";
+        return { kind: "unavailable", reason: reasonOf(row, fallback) };
+    }
+    // Infra dominates every other field (daemon.ts:220): a runner that died on the machine verified
+    // nothing, so this is checked before any clause that could read the same row as satisfied.
+    // `retryable` defaults true because the one shipped producer of these rows (baseline.ts:277) is by
+    // construction the retryable class — "the runner never completed a suite" — and a later producer
+    // that knows its failure is terminal says so on the row rather than relying on this default.
+    if (row.infra === true) {
+        return {
+            kind: "infra",
+            reason: reasonOf(row, "the runner never completed a suite, so this gate verified nothing"),
+            retryable: row.retryable !== false,
+        };
+    }
+    // Two different facts wear the same `skipped: true` flag, and telling them apart is most of why this
+    // vocabulary exists. The GATE IDENTITY is what separates them, not `pass` and not `verdict`: the
+    // command-absent skip has exactly one producer, the baseline battery, which runs build/test/lint
+    // only (run-gates.ts:203) and records a gate the repository never configured with `pass: true`
+    // beside `skipped: true` (baseline.ts:262). Every OTHER skip is a policy declining a gate that WAS
+    // configured. That distinction cannot be read off `pass`, because the review declines persisted in
+    // pre-R3 journals carry `pass: true` too — R3 (daemon.ts:1386) only stopped writing a verdict for
+    // NEW ones, and the old rows are still on disk. Reading them by field alone files a policy decline
+    // as "no command detected", which is the same collapse in a quieter costume.
+    if (row.skipped === true || row.verdict === "skipped" || declinedByDetails(row)) {
+        const commandAbsent = BASELINE_GATES.has(String(row.gate))
+            && row.pass === true
+            && row.verdict !== "skipped";
+        return commandAbsent
+            ? { kind: "skipped", reason: reasonOf(row, "no command detected for this gate") }
+            : { kind: "declined", reason: reasonOf(row, "a policy declined to run this gate") };
+    }
+    // A selected-test green is a SCREEN and never the merge verdict (journal.ts:1067). It reports
+    // `pass: true`, so reading it by that field alone is exactly the collapse of a non-failure into a
+    // pass — the full suite has not spoken yet.
+    if (row.pass === true && Array.isArray(row.selectedTests) && row.fullSuite !== true) {
+        return {
+            kind: "held",
+            reason: reasonOf(row, `${row.selectedTests.length} selected test(s) screened; the full suite has not spoken`),
+        };
+    }
+    if (row.pass === true)
+        return { kind: "passed" };
+    if (row.pass === false)
+        return { kind: "failed" };
+    // Neither a verdict nor a stated non-run. Unknown is not clean: it stays non-passing and carries
+    // whatever the row did say, so a reader can see why it could not be read.
+    return {
+        kind: "unavailable",
+        reason: reasonOf(row, "gate result states no pass, skip, decline or infra verdict"),
+    };
+}