tickmarkr 1.87.0 → 1.90.0

package/dist/run/protocol.js

@@ -0,0 +1,433 @@
+import { z } from "zod";
+import { GATE_NAMES } from "../graph/schema.js";
+import { normalizeGateOutcome } from "./outcome.js";
+// T32 (F2): the decision protocol is deliberately smaller than the journal. Existing journals contain
+// many observational event types and must remain readable; only the five event names below assert a
+// decision identity. T38 and T40 will migrate their producers to these rows. Until then, Journal's
+// legacy tuple append remains byte-compatible and this module supplies the validated object-write and
+// compatibility-read boundaries without dual-writing anything.
+const NonEmptyStringSchema = z.string().refine((value) => value.trim().length > 0, "must be a non-empty string");
+const TimestampSchema = NonEmptyStringSchema;
+const TaskIdSchema = NonEmptyStringSchema;
+const TaskIdsSchema = z.array(TaskIdSchema);
+const AttemptSchema = z.number().int().nonnegative();
+const EvidenceSchema = z.record(z.string(), z.unknown());
+/** The T31 outcome vocabulary, made executable and strict at the persistence boundary. */
+export const GateOutcomeSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("passed") }).strict(),
+    z.object({ kind: z.literal("failed") }).strict(),
+    z.object({ kind: z.literal("skipped"), reason: NonEmptyStringSchema }).strict(),
+    z.object({ kind: z.literal("declined"), reason: NonEmptyStringSchema }).strict(),
+    z.object({ kind: z.literal("held"), reason: NonEmptyStringSchema }).strict(),
+    z.object({ kind: z.literal("unavailable"), reason: NonEmptyStringSchema }).strict(),
+    z.object({
+        kind: z.literal("infra"),
+        reason: NonEmptyStringSchema,
+        retryable: z.boolean(),
+    }).strict(),
+]);
+export const ROLE_INVOCATION_ROLES = ["worker", "judge", "review", "consult"];
+export const ROLE_INVOCATION_OUTCOMES = ["completed", "failed", "unavailable"];
+export const RUN_TERMINAL_OUTCOMES = ["completed", "failed", "incomplete"];
+const MeasuredLoadSchema = z.object({
+    oneMinute: z.number().nonnegative(),
+    fiveMinute: z.number().nonnegative(),
+    cores: z.number().int().positive(),
+}).strict();
+const UnavailableLoadSchema = z.object({
+    unavailableReason: NonEmptyStringSchema,
+}).strict();
+const TokenUsageSchema = z.object({
+    input: z.number().int().nonnegative(),
+    output: z.number().int().nonnegative(),
+    cacheRead: z.number().int().nonnegative().optional(),
+    cacheWrite: z.number().int().nonnegative().optional(),
+    reasoning: z.number().int().nonnegative().optional(),
+}).strict();
+const GatePhaseStartDataSchema = z.object({
+    attempt: AttemptSchema,
+    gate: z.enum(GATE_NAMES),
+    evidence: EvidenceSchema.optional(),
+}).strict();
+const GateTerminalDataSchema = z.object({
+    attempt: AttemptSchema,
+    gate: z.enum(GATE_NAMES),
+    outcome: GateOutcomeSchema,
+    details: z.string().optional(),
+    load: z.union([MeasuredLoadSchema, UnavailableLoadSchema]).optional(),
+    evidence: EvidenceSchema.optional(),
+}).strict();
+// Adapter/model/vendor and metering fields are named now so T38 can publish them without reopening
+// this schema. They remain optional in T32 because identity/pair integrity lands before that producer
+// migration; T38 is the owner that will require them at every live invocation boundary.
+const RoleInvocationIdentityDataSchema = z.object({
+    attempt: AttemptSchema,
+    role: z.enum(ROLE_INVOCATION_ROLES),
+    adapter: NonEmptyStringSchema.optional(),
+    model: NonEmptyStringSchema.optional(),
+    vendor: NonEmptyStringSchema.optional(),
+    evidence: EvidenceSchema.optional(),
+});
+const RoleInvocationStartDataSchema = RoleInvocationIdentityDataSchema.strict();
+const RoleInvocationTerminalDataSchema = RoleInvocationIdentityDataSchema.extend({
+    outcome: z.enum(ROLE_INVOCATION_OUTCOMES),
+    reason: NonEmptyStringSchema,
+    tokens: TokenUsageSchema.optional(),
+    unmeteredReason: NonEmptyStringSchema.optional(),
+}).strict();
+const RunTerminalDataSchema = z.object({
+    outcome: z.enum(RUN_TERMINAL_OUTCOMES),
+    reason: NonEmptyStringSchema,
+    // `run-end` is already a live event name. These fields preserve the summary contract consumed by
+    // daemon resume and report readers when T40 moves the producer onto this validated object write.
+    runId: NonEmptyStringSchema,
+    branch: NonEmptyStringSchema,
+    done: TaskIdsSchema,
+    failed: TaskIdsSchema,
+    human: TaskIdsSchema,
+    blocked: TaskIdsSchema,
+    pending: TaskIdsSchema,
+    tipVerify: z.enum(["passed", "failed"]).optional(),
+    lastMergedTask: TaskIdSchema.optional(),
+    approvalDisposition: z.enum(["complete", "outstanding"]).optional(),
+    outstandingApprovals: TaskIdsSchema.optional(),
+    phase: NonEmptyStringSchema.optional(),
+    fatal: z.boolean().optional(),
+    error: z.string().optional(),
+    evidence: EvidenceSchema.optional(),
+}).strict();
+export const GatePhaseStartEventSchema = z.object({
+    ts: TimestampSchema,
+    // The shipped `phase-start` is a broader task-lifecycle marker. A distinct name prevents its
+    // worker/gates/merge payloads from being falsely claimed as malformed gate decisions.
+    event: z.literal("gate-phase-start"),
+    taskId: TaskIdSchema,
+    data: GatePhaseStartDataSchema,
+}).strict();
+export const GateTerminalEventSchema = z.object({
+    ts: TimestampSchema,
+    event: z.literal("gate-result"),
+    taskId: TaskIdSchema,
+    data: GateTerminalDataSchema,
+}).strict();
+export const RoleInvocationStartEventSchema = z.object({
+    ts: TimestampSchema,
+    event: z.literal("role-invocation-start"),
+    taskId: TaskIdSchema,
+    data: RoleInvocationStartDataSchema,
+}).strict();
+export const RoleInvocationTerminalEventSchema = z.object({
+    ts: TimestampSchema,
+    event: z.literal("role-invocation-terminal"),
+    taskId: TaskIdSchema,
+    data: RoleInvocationTerminalDataSchema,
+}).strict();
+export const RunTerminalEventSchema = z.object({
+    ts: TimestampSchema,
+    event: z.literal("run-end"),
+    data: RunTerminalDataSchema,
+}).strict();
+/**
+ * The complete decision-event vocabulary. There is no catch-all object arm: an event claiming one of
+ * these names either validates as exactly one member or becomes a protocol issue on read.
+ */
+export const DecisionEventSchema = z.discriminatedUnion("event", [
+    GatePhaseStartEventSchema,
+    GateTerminalEventSchema,
+    RoleInvocationStartEventSchema,
+    RoleInvocationTerminalEventSchema,
+    RunTerminalEventSchema,
+]);
+// New writers do not choose timestamps. Journal.append adds the timestamp and validates the resulting
+// full DecisionEvent before a byte reaches appendFileSync.
+export const DecisionEventWriteSchema = z.discriminatedUnion("event", [
+    GatePhaseStartEventSchema.omit({ ts: true }),
+    GateTerminalEventSchema.omit({ ts: true }),
+    RoleInvocationStartEventSchema.omit({ ts: true }),
+    RoleInvocationTerminalEventSchema.omit({ ts: true }),
+    RunTerminalEventSchema.omit({ ts: true }),
+]);
+export const DECISION_EVENT_NAMES = [
+    "gate-phase-start",
+    "gate-result",
+    "role-invocation-start",
+    "role-invocation-terminal",
+    "run-end",
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const rawDataOf = (raw) => isRecord(raw) ? raw.data : undefined;
+const eventTypeOf = (raw) => isRecord(raw) && typeof raw.event === "string" ? raw.event : undefined;
+const isDecisionEventName = (event) => event !== undefined && DECISION_EVENT_NAMES.includes(event);
+function legacyGateEvent(raw) {
+    if (!isRecord(raw) || raw.event !== "gate-result" || typeof raw.ts !== "string"
+        || typeof raw.taskId !== "string" || !isRecord(raw.data))
+        return undefined;
+    const data = raw.data;
+    // An `outcome` key declares the canonical format. A malformed or mixed canonical row must not fall
+    // through to the legacy booleans and become clean.
+    if (hasOwn(data, "outcome"))
+        return undefined;
+    const attempt = data.attempt === undefined ? 0 : data.attempt;
+    if (!Number.isInteger(attempt) || attempt < 0 || typeof data.gate !== "string"
+        || !GATE_NAMES.includes(data.gate))
+        return undefined;
+    const outcome = normalizeGateOutcome(data);
+    // T31's unavailable fallback is useful to old projections, but at this protocol boundary it means
+    // the known terminal could not be interpreted. Preserve it as a ProtocolIssue instead of silently
+    // manufacturing a terminal outcome.
+    if (outcome.kind === "unavailable")
+        return undefined;
+    const parsed = GateTerminalEventSchema.safeParse({
+        ts: raw.ts,
+        event: "gate-result",
+        taskId: raw.taskId,
+        data: {
+            attempt,
+            gate: data.gate,
+            outcome,
+            ...(typeof data.details === "string" ? { details: data.details } : {}),
+            evidence: { legacyData: data },
+        },
+    });
+    return parsed.success ? parsed.data : undefined;
+}
+const LegacyRunTerminalDataSchema = z.object({
+    runId: NonEmptyStringSchema,
+    branch: NonEmptyStringSchema,
+    done: TaskIdsSchema,
+    failed: TaskIdsSchema,
+    human: TaskIdsSchema,
+    blocked: TaskIdsSchema.optional(),
+    pending: TaskIdsSchema.optional(),
+    tipVerify: z.enum(["passed", "failed"]).optional(),
+    lastMergedTask: TaskIdSchema.optional(),
+    approvalDisposition: z.enum(["complete", "outstanding"]).optional(),
+    outstandingApprovals: TaskIdsSchema.optional(),
+    phase: NonEmptyStringSchema.optional(),
+    fatal: z.boolean().optional(),
+    error: z.string().optional(),
+}).passthrough();
+function legacyRunTerminalEvent(raw) {
+    if (!isRecord(raw) || raw.event !== "run-end" || typeof raw.ts !== "string"
+        || hasOwn(raw, "taskId") || !isRecord(raw.data))
+        return undefined;
+    // Either canonical discriminator declares a new-format row. Never repair a malformed canonical row
+    // from its summary arrays, because doing so could turn a rejected write into a clean terminal.
+    if (hasOwn(raw.data, "outcome") || hasOwn(raw.data, "reason"))
+        return undefined;
+    const legacy = LegacyRunTerminalDataSchema.safeParse(raw.data);
+    if (!legacy.success)
+        return undefined;
+    const data = legacy.data;
+    const failed = data.fatal === true || data.failed.length > 0 || data.tipVerify === "failed";
+    const incomplete = data.human.length > 0 || (data.blocked?.length ?? 0) > 0
+        || (data.pending?.length ?? 0) > 0 || data.approvalDisposition === "outstanding";
+    const outcome = failed ? "failed" : incomplete ? "incomplete" : "completed";
+    const reason = data.fatal === true
+        ? data.error?.trim() || "legacy run ended after a fatal error"
+        : failed
+            ? "legacy run summary records failed verification or tasks"
+            : incomplete
+                ? "legacy run summary records unfinished tasks or approvals"
+                : "legacy run summary records all tasks complete";
+    const parsed = RunTerminalEventSchema.safeParse({
+        ts: raw.ts,
+        event: "run-end",
+        data: {
+            outcome,
+            reason,
+            runId: data.runId,
+            branch: data.branch,
+            done: data.done,
+            failed: data.failed,
+            human: data.human,
+            blocked: data.blocked ?? [],
+            pending: data.pending ?? [],
+            ...(data.tipVerify === undefined ? {} : { tipVerify: data.tipVerify }),
+            ...(data.lastMergedTask === undefined ? {} : { lastMergedTask: data.lastMergedTask }),
+            ...(data.approvalDisposition === undefined ? {} : { approvalDisposition: data.approvalDisposition }),
+            ...(data.outstandingApprovals === undefined ? {} : { outstandingApprovals: data.outstandingApprovals }),
+            ...(data.phase === undefined ? {} : { phase: data.phase }),
+            ...(data.fatal === undefined ? {} : { fatal: data.fatal }),
+            ...(data.error === undefined ? {} : { error: data.error }),
+            evidence: { legacyData: raw.data },
+        },
+    });
+    return parsed.success ? parsed.data : undefined;
+}
+function schemaFor(event) {
+    switch (event) {
+        case "gate-phase-start": return GatePhaseStartEventSchema;
+        case "gate-result": return GateTerminalEventSchema;
+        case "role-invocation-start": return RoleInvocationStartEventSchema;
+        case "role-invocation-terminal": return RoleInvocationTerminalEventSchema;
+        case "run-end": return RunTerminalEventSchema;
+    }
+}
+function issueMessages(event, raw) {
+    const parsed = schemaFor(event).safeParse(raw);
+    if (parsed.success)
+        return [];
+    return parsed.error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "row";
+        return `${path}: ${issue.message}`;
+    });
+}
+/** Interpret every parseable JSONL row without dropping unknown or malformed-known events. */
+export function trackJournalRows(runId, sourceRows) {
+    return sourceRows.map(({ sourceIndex, raw }) => {
+        const eventType = eventTypeOf(raw);
+        const rawData = rawDataOf(raw);
+        if (!isDecisionEventName(eventType)) {
+            return { kind: "historical-unknown", runId, sourceIndex, eventType, raw, rawData };
+        }
+        const canonical = DecisionEventSchema.safeParse(raw);
+        const compatible = canonical.success
+            ? canonical.data
+            : eventType === "gate-result"
+                ? legacyGateEvent(raw)
+                : eventType === "run-end"
+                    ? legacyRunTerminalEvent(raw)
+                    : undefined;
+        if (compatible) {
+            return { kind: "decision", runId, sourceIndex, event: compatible, raw, rawData };
+        }
+        const issues = issueMessages(eventType, raw);
+        if (eventType === "gate-result" && isRecord(rawData) && !hasOwn(rawData, "outcome")) {
+            const outcome = normalizeGateOutcome(rawData);
+            if (outcome.kind === "unavailable")
+                issues.push(`data.outcome: ${outcome.reason}`);
+        }
+        return {
+            kind: "protocol-issue",
+            runId,
+            sourceIndex,
+            eventType,
+            issues: issues.length > 0 ? issues : ["row does not satisfy its closed decision schema"],
+            raw,
+            rawData,
+        };
+    });
+}
+const pairKey = ({ runId, taskId, attempt, role }) => JSON.stringify([runId, taskId, attempt, role]);
+function pairedIdentity(row) {
+    const event = row.event;
+    switch (event.event) {
+        case "gate-phase-start":
+            return {
+                identity: {
+                    runId: row.runId,
+                    taskId: event.taskId,
+                    attempt: event.data.attempt,
+                    role: `gate:${event.data.gate}`,
+                },
+                terminal: false,
+            };
+        case "gate-result":
+            return {
+                identity: {
+                    runId: row.runId,
+                    taskId: event.taskId,
+                    attempt: event.data.attempt,
+                    role: `gate:${event.data.gate}`,
+                },
+                terminal: true,
+            };
+        case "role-invocation-start":
+            return {
+                identity: {
+                    runId: row.runId,
+                    taskId: event.taskId,
+                    attempt: event.data.attempt,
+                    role: event.data.role,
+                },
+                terminal: false,
+            };
+        case "role-invocation-terminal":
+            return {
+                identity: {
+                    runId: row.runId,
+                    taskId: event.taskId,
+                    attempt: event.data.attempt,
+                    role: event.data.role,
+                },
+                terminal: true,
+            };
+        case "run-end":
+            return undefined;
+    }
+}
+/**
+ * Structural pair fold only. It does not reduce task or run state. An open start remains observable as
+ * open; duplicate starts/terminals and orphan terminals are invalid and never count as a closed pair.
+ */
+export function foldPairIntegrity(rows) {
+    const byIdentity = new Map();
+    const issues = [];
+    for (const row of rows) {
+        if (row.kind === "protocol-issue") {
+            issues.push({
+                kind: "malformed-decision",
+                sourceIndexes: [row.sourceIndex],
+                reason: `${row.eventType}: ${row.issues.join("; ")}`,
+            });
+            continue;
+        }
+        if (row.kind !== "decision")
+            continue;
+        const paired = pairedIdentity(row);
+        if (!paired)
+            continue;
+        const key = pairKey(paired.identity);
+        let accumulator = byIdentity.get(key);
+        if (!accumulator) {
+            accumulator = {
+                identity: paired.identity,
+                starts: [],
+                terminals: [],
+                firstSourceIndex: row.sourceIndex,
+            };
+            byIdentity.set(key, accumulator);
+        }
+        (paired.terminal ? accumulator.terminals : accumulator.starts).push(row.sourceIndex);
+    }
+    const accumulators = [...byIdentity.values()].sort((a, b) => a.firstSourceIndex - b.firstSourceIndex);
+    const pairs = accumulators.map((pair) => {
+        if (pair.starts.length > 1) {
+            issues.push({
+                kind: "duplicate-start",
+                identity: pair.identity,
+                sourceIndexes: [...pair.starts],
+                reason: "one structural identity has more than one start",
+            });
+        }
+        if (pair.terminals.length > 1) {
+            issues.push({
+                kind: "duplicate-terminal",
+                identity: pair.identity,
+                sourceIndexes: [...pair.terminals],
+                reason: "one structural identity has more than one terminal",
+            });
+        }
+        const orphanTerminals = pair.starts.length === 0
+            ? pair.terminals
+            : pair.terminals.filter((sourceIndex) => sourceIndex < pair.starts[0]);
+        if (orphanTerminals.length > 0) {
+            issues.push({
+                kind: "terminal-without-start",
+                identity: pair.identity,
+                sourceIndexes: [...orphanTerminals],
+                reason: "a terminal has no preceding start with the same run, task, attempt and role",
+            });
+        }
+        const invalid = pair.starts.length > 1 || pair.terminals.length > 1 || orphanTerminals.length > 0;
+        return {
+            identity: pair.identity,
+            state: invalid ? "invalid" : pair.terminals.length === 0 ? "open" : "closed",
+            startSourceIndexes: [...pair.starts],
+            terminalSourceIndexes: [...pair.terminals],
+        };
+    });
+    return { pairs, issues };
+}

package/dist/run/supervision.d.ts

@@ -0,0 +1,29 @@
+/** How often a watcher rewrites its own tier's beat. */
+export declare const SUPERVISION_BEAT_MS = 10000;
+/** Ceiling before a beat reads STALE: SIX beats, lock.ts's ratio — five may be missed before alarm. */
+export declare const SUPERVISION_STALE_MS: number;
+export declare const SUPERVISION_FUTURE_GRACE_MS = 1000;
+export declare const SUPERVISION_TIERS: readonly ["orchestrator", "overseer", "watch"];
+export type SupervisionTier = (typeof SUPERVISION_TIERS)[number];
+export type SupervisionState = "ABSENT" | "STALE" | "ARMED" | "UNREADABLE" | "DISARMED";
+export interface TierLiveness {
+    tier: SupervisionTier;
+    state: SupervisionState;
+    /** Absent for ABSENT, UNREADABLE and DISARMED — no beat to age. Always present for STALE and ARMED. */
+    beatAgeMs?: number;
+}
+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): void;
+/** Handle a watcher holds for as long as it is supervising; disarm stands it down and is idempotent. */
+export interface ArmedSupervision {
+    disarm: () => void;
+}
+export declare function armSupervision(repoRoot: string, tier: SupervisionTier, beatMs?: number): ArmedSupervision;
+export declare function readTierLiveness(repoRoot: string, tier: SupervisionTier, now?: number): TierLiveness;
+export declare function supervisionStatus(repoRoot: string, tier: SupervisionTier, now?: number): TierLiveness;
+/** Every KNOWN tier, always — a tier omitted from this list would read as one that is fine. */
+export declare const readSupervision: (repoRoot: string, now?: number) => TierLiveness[];
+/** One line, one word per tier. Shared by both status surfaces so neither can render a state twice. */
+export declare const supervisionText: (tiers: readonly TierLiveness[], divider?: string) => string;

package/dist/run/supervision.js

@@ -0,0 +1,189 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stateDirName, tickmarkrDir } from "../graph/graph.js";
+// SUP-01: supervision liveness as FILE STATE, not as a report — lock.ts's proven shape, one file per
+// tier. A watcher beats its OWN file; every other seat derives that tier's state by stat()ing it. So
+// "watchers alive" stops being the one claim only the seat that already lost it could make: the reader
+// is never the watcher, and a watcher that dies stops writing without having to notice it died.
+//
+// BOTH polarities are distinguishable by construction, because collapsing them IS the defect: a seat
+// that never armed reads exactly like one that armed and then died. No record at all ⇒ ABSENT (never
+// armed). A record whose beat has aged past the ceiling ⇒ STALE (armed, then died). A fresh one ⇒
+// ARMED. ABSENT is its own branch below and carries no age — STALE always carries one.
+//
+// SUP-02: the beat mtime is the ONLY input. Nothing here reads a process table and nothing matches a
+// process name — a poll-grep watcher carries `grep` in its own argv, so the filter that removes the
+// probing grep removes the watched one. The payload records a pid for an OPERATOR to read off a STALE
+// record; the derivation never consults it, so a reused, dead or unreadable pid changes no state.
+// Zero new deps — node:fs stdlib, exactly as lock.ts.
+/** How often a watcher rewrites its own tier's beat. */
+export const SUPERVISION_BEAT_MS = 10_000;
+/** Ceiling before a beat reads STALE: SIX beats, lock.ts's ratio — five may be missed before alarm. */
+export const SUPERVISION_STALE_MS = 6 * SUPERVISION_BEAT_MS;
+// SUP-03: the ONLY legitimate reason a beat's mtime may lead the reader's clock is that the two are
+// not the same clock and not the same resolution — a filesystem stamps sub-millisecond, Date.now()
+// truncates to whole milliseconds, so a beat written this instant can read a fraction of a
+// millisecond into the future. A second of slack covers even a coarse filesystem. Anything past it
+// is SKEW, and skew is the one direction this instrument may not fail in: see readTierLiveness.
+export const SUPERVISION_FUTURE_GRACE_MS = 1_000;
+// The supervision seats this harness has. An unlisted tier is an INVISIBLE tier, which is the failure
+// mode itself — an auditor read "no watchers were ever armed" off a surface that named none. Adding a
+// seat means adding it here, and `status` then renders it whether or not it has ever beaten.
+export const SUPERVISION_TIERS = ["orchestrator", "overseer", "watch"];
+// PURE path math: stateDirName, never tickmarkrDir — the latter mkdirs the state dir and writes its
+// .gitignore, so routing a READER through it would make status create the very tree it reports on.
+export const supervisionBeatPath = (repoRoot, tier) => join(repoRoot, stateDirName(repoRoot), "supervision", `${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(repoRoot, stateDirName(repoRoot), "supervision", `${tier}.standdown`);
+// 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.
+export function beatSupervision(repoRoot, tier) {
+    tickmarkrDir(repoRoot); // the write path DOES create — beats land inside the gitignored state dir
+    const p = supervisionBeatPath(repoRoot, tier);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify({ tier, pid: process.pid, beatAt: new Date().toISOString() }) + "\n");
+}
+// 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,
+// hangs or is SIGKILLed stops beating without having to notice, which is the whole point. lock.ts's
+// heartbeat shape exactly: an immediate first write (ARMED from instant zero, not one interval later),
+// an unref'd interval that never holds the watcher's event loop open, and a beat failure that is
+// swallowed rather than crashing the watcher — an unwritten beat ages out and reads STALE, which is
+// the truth. The FIRST beat is swallowed on the same rule: a cosmetic instrument that could not write
+// must not take the run down with it. NOT called from `status`: status is a reader (its purity fence
+// is a test); the in-repo callsite is runDaemon, which arms the orchestrator tier for the life of
+// the run. A tier nobody arms reads ABSENT — exactly what ABSENT means, not a false "healthy".
+//
+// Arming CLEARS any prior stand-down record: a tier that stood down and armed again is armed, and a
+// marker left behind by the last run would otherwise report the live one as stood down forever.
+export function armSupervision(repoRoot, tier, beatMs = SUPERVISION_BEAT_MS) {
+    // The clearing gets its OWN try: a cleanup that cannot complete (a directory dropped at the marker
+    // path, a permission) must not cost the first beat. Sharing one try did exactly that — the tier armed
+    // with NO beat while the old marker stayed on disk, the one combination that reports a live watcher
+    // as stood down. Recursive because the path is ours: whatever occupies it is not our marker.
+    try {
+        rmSync(supervisionStandDownPath(repoRoot, tier), { force: true, recursive: true });
+    }
+    catch { /* uncleared: the reader validates the marker and a newer beat outranks it — never masked */ }
+    try {
+        beatSupervision(repoRoot, tier);
+    }
+    catch { /* repo gone / disk full — the tier reads ABSENT rather than crashing its watcher */ }
+    const timer = setInterval(() => {
+        try {
+            beatSupervision(repoRoot, tier);
+        }
+        catch { /* repo gone / disk full — let the beat expire */ }
+    }, beatMs);
+    timer.unref();
+    let stoodDown = false;
+    return {
+        // Stand down: stop beating AND say so. Idempotent because the daemon disarms from more than one
+        // exit path (its signal reaper exits the process before the finally can run), and the recorded
+        // instant belongs to the first stand-down.
+        disarm: () => {
+            if (stoodDown)
+                return;
+            stoodDown = true;
+            clearInterval(timer);
+            // Published ATOMICALLY — written aside, renamed over — so no reader can ever meet a half-written
+            // marker. A torn marker is rejected anyway (see readStandDown), but a stand-down that reads as
+            // garbage is a stand-down that reports as a death, and the rename costs one line.
+            const p = supervisionStandDownPath(repoRoot, tier);
+            const tmp = `${p}.${process.pid}.tmp`;
+            try {
+                mkdirSync(dirname(p), { recursive: true });
+                writeFileSync(tmp, JSON.stringify({ tier, pid: process.pid, disarmedAt: new Date().toISOString() }) + "\n");
+                renameSync(tmp, p);
+            }
+            catch { /* unrecordable stand-down ages out as STALE — pessimistic, which is the safe way to fail */ }
+        },
+    };
+}
+// BEAT DERIVATION — pure, and the only thing that reads the beat. One statSync: never creates,
+// touches or reaps the record it reports on, and never creates the directory that holds it. ONLY a
+// missing path is ABSENT: ENOENT (no beat file) and ENOTDIR (nothing that could hold one) mean no
+// record was ever written. Every other stat failure is a record we could not read, and a stat-able
+// inode that is not a regular file is not a beat — both are UNREADABLE, never silently ABSENT and
+// never silently ARMED. Callers wanting the TIER's state want supervisionStatus below; this answers
+// the narrower question "does the beat say alive", which is all a beat can ever say.
+export function readTierLiveness(repoRoot, tier, now = Date.now()) {
+    return beatLiveness(tier, beatMtimeMs(repoRoot, tier), now);
+}
+// The beat's inode, or why there is no age to derive from it. Split out so the stand-down ranking below
+// reads the SAME mtime this derivation does rather than a second, later stat of a moving record.
+function beatMtimeMs(repoRoot, tier) {
+    let st;
+    try {
+        st = statSync(supervisionBeatPath(repoRoot, tier));
+    }
+    catch (e) {
+        const code = e.code;
+        // never armed — reachable without anything having been written
+        return code === "ENOENT" || code === "ENOTDIR" ? "ABSENT" : "UNREADABLE";
+    }
+    return st.isFile() ? st.mtimeMs : "UNREADABLE"; // a directory at the beat path is not a heartbeat
+}
+function beatLiveness(tier, mtimeMs, now) {
+    if (typeof mtimeMs !== "number")
+        return { tier, state: mtimeMs };
+    const age = now - mtimeMs;
+    // SUP-03: a beat dated AHEAD of the reader's clock past the grace above is not a fresh beat — it is
+    // a record whose age cannot be derived. Clamping it to zero (what this line used to do) made any
+    // future stamp read ARMED forever, so filesystem skew or one bad utimes froze a DEAD watcher as
+    // alive: fail-OPEN in the instrument built to catch exactly that, in the one direction it may not
+    // fail. UNREADABLE says what is true — something is there and its age is not knowable — and, unlike
+    // ARMED, it never claims a watcher is alive.
+    if (age < -SUPERVISION_FUTURE_GRACE_MS)
+        return { tier, state: "UNREADABLE" };
+    const beatAgeMs = Math.max(0, age); // inside the grace: the two clocks' resolutions, not skew
+    return { tier, state: beatAgeMs > SUPERVISION_STALE_MS ? "STALE" : "ARMED", beatAgeMs };
+}
+// A stand-down is only what a watcher RECORDED, so the record has to READ as one: a regular file whose
+// payload names this tier and the instant it stood down. Path existence is not proof — a directory, a
+// torn write or a stray file at that path says nothing about any watcher, and calling one of those a
+// clean hand-off would hide a death behind whatever happened to be lying there. Pure: one stat, one
+// read, and neither creates the record or the directory holding it.
+function readStandDown(repoRoot, tier) {
+    const p = supervisionStandDownPath(repoRoot, tier);
+    let st;
+    try {
+        st = statSync(p);
+    }
+    catch (e) {
+        const code = e.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? "NONE" : "UNREADABLE";
+    }
+    if (!st.isFile())
+        return "UNREADABLE";
+    try {
+        const rec = JSON.parse(readFileSync(p, "utf8"));
+        if (rec?.tier !== tier)
+            return "UNREADABLE";
+        if (typeof rec.disarmedAt !== "string" || Number.isNaN(Date.parse(rec.disarmedAt)))
+            return "UNREADABLE";
+    }
+    catch {
+        return "UNREADABLE";
+    } // unparseable or unreadable bytes — not a stand-down anyone can read
+    return { mtimeMs: st.mtimeMs };
+}
+// 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 beat stamped after the marker was written by
+// a watcher that armed again, so a marker some failed cleanup left behind can never mask a live tier.
+export function supervisionStatus(repoRoot, tier, now = Date.now()) {
+    const beat = beatMtimeMs(repoRoot, tier);
+    const standDown = readStandDown(repoRoot, tier);
+    if (standDown === "UNREADABLE")
+        return { tier, state: "UNREADABLE" };
+    if (standDown !== "NONE" && !(typeof beat === "number" && beat > standDown.mtimeMs)) {
+        return { tier, state: "DISARMED" };
+    }
+    return beatLiveness(tier, beat, now);
+}
+/** Every KNOWN tier, always — a tier omitted from this list would read as one that is fine. */
+export const readSupervision = (repoRoot, now = Date.now()) => SUPERVISION_TIERS.map((tier) => supervisionStatus(repoRoot, tier, now));
+/** One line, one word per tier. Shared by both status surfaces so neither can render a state twice. */
+export const supervisionText = (tiers, divider = " · ") => `supervision: ${tiers.map((t) => `${t.tier} ${t.state}`).join(divider)}`;

package/fixtures/authoring-lints/01-awk-range-self-pass.spec.md

@@ -0,0 +1,12 @@
+<!-- tickmarkr:spec -->
+<!-- provenance: v1.89 Finding 0 awk-range self-pass certified only the task heading -->
+
+## T1: Clean leading task
+- goal: Keep the first extracted task deliberately clean
+- acceptance:
+  - judge: the first task remains ordinary canary data
+
+## T2: Finding after the range start
+- goal: Consume T28 classification without declaring the dependency
+- acceptance:
+  - judge: classification controls the conclusion

package/fixtures/authoring-lints/02-judge-text-key-miss.spec.md

@@ -0,0 +1,7 @@
+<!-- tickmarkr:spec -->
+<!-- provenance: v1.89 judge-text extractor read judge instead of the compiled text key -->
+
+## T1: Typed judge finding
+- goal: Put the finding only in a typed judge item
+- acceptance:
+  - judge: cite the audit before accepting the task