tickmarkr 1.30.0

package/dist/run/git.d.ts

@@ -0,0 +1,12 @@
+export interface ShResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export declare function sh(cmd: string, cwd: string, timeoutMs?: number): Promise<ShResult>;
+export declare function shOk(cmd: string, cwd: string): Promise<string>;
+export declare function gitHead(cwd: string): Promise<string>;
+export declare function resolveIntegrationBranch(repo: string, branch: string): Promise<string>;
+export declare function createWorktree(repo: string, branch: string, baseRef: string): Promise<string>;
+export declare function removeWorktree(repo: string, dir: string): Promise<void>;

package/dist/run/git.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { shq } from "../adapters/types.js";
+import { drovrDir } from "../graph/graph.js";
+// stdin "ignore": same class as HARD-05 / SubprocessDriver — never leave an open pipe a child can block on
+// (pi -p / codex exec wait for stdin EOF). timedOut distinguishes SIGKILL-timeout from a real nonzero exit.
+export function sh(cmd, cwd, timeoutMs = 600000) {
+    return new Promise((resolve) => {
+        const p = spawn("bash", ["-lc", cmd], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "", stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; p.kill("SIGKILL"); }, timeoutMs);
+        p.stdout.on("data", (d) => (stdout += d));
+        p.stderr.on("data", (d) => (stderr += d));
+        p.on("error", (e) => { clearTimeout(timer); resolve({ code: 127, stdout, stderr: String(e), timedOut }); });
+        p.on("close", (code) => { clearTimeout(timer); resolve({ code: code ?? 1, stdout, stderr, timedOut }); });
+    });
+}
+export async function shOk(cmd, cwd) {
+    const r = await sh(cmd, cwd);
+    if (r.code !== 0)
+        throw new Error(`command failed (${r.code}): ${cmd}\n${r.stderr || r.stdout}`);
+    return r.stdout;
+}
+export async function gitHead(cwd) {
+    return (await shOk("git rev-parse HEAD", cwd)).trim();
+}
+const sanitize = (branch) => branch.replace(/[^\w.-]+/g, "-");
+const branchExists = async (repo, branch) => (await sh(`git rev-parse --verify ${shq(`refs/heads/${branch}`)}`, repo)).code === 0;
+export async function resolveIntegrationBranch(repo, branch) {
+    if (!branch.startsWith("drovr/"))
+        return branch;
+    const legacy = `drover/${branch.slice("drovr/".length)}`;
+    return !(await branchExists(repo, branch)) && await branchExists(repo, legacy) ? legacy : branch;
+}
+const resolveTaskBranch = async (repo, branch) => {
+    const split = branch.lastIndexOf("--");
+    if (split < 0)
+        return branch;
+    const integration = await resolveIntegrationBranch(repo, branch.slice(0, split));
+    return `${integration}${branch.slice(split)}`;
+};
+export async function createWorktree(repo, branch, baseRef) {
+    branch = await resolveTaskBranch(repo, branch);
+    const dir = join(drovrDir(repo), "worktrees", sanitize(branch));
+    if (existsSync(dir))
+        await removeWorktree(repo, dir);
+    await shOk(`git worktree add -B ${shq(branch)} ${shq(dir)} ${shq(baseRef)}`, repo);
+    return dir;
+}
+export async function removeWorktree(repo, dir) {
+    await sh(`git worktree remove --force ${shq(dir)}`, repo); // best-effort; stale dirs are re-added with -B
+    await sh(`rm -rf ${shq(dir)}`, repo);
+    await sh("git worktree prune", repo);
+}

package/dist/run/journal.d.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { type Assignment } from "../adapters/types.js";
+import type { DrovrConfig } from "../config/config.js";
+import { type TaskStatus } from "../graph/schema.js";
+import { type RoutingProfile } from "../route/profile.js";
+export interface JournalEvent {
+    ts: string;
+    event: string;
+    taskId?: string;
+    data: Record<string, unknown>;
+}
+export declare function formatJournalNarration({ event, taskId, data }: JournalEvent): string;
+export interface ResumeState {
+    attempts: number;
+    tried: string[];
+    lastAssignment?: Assignment;
+}
+export declare const ATTEMPT_CAP_RELEASE: "attempt-cap";
+export declare const PARK_KINDS: readonly ["ladder-exhausted", "attempt-cap", "gate-fail", "quota", "reroute-exhausted", "setup", "stall", "merge-conflict"];
+export type ParkKind = (typeof PARK_KINDS)[number];
+export declare const RETRY_MODES: readonly ["resume", "fresh"];
+export type RetryMode = (typeof RETRY_MODES)[number];
+export declare const TelemetryRowSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    shape: z.ZodString;
+    adapter: z.ZodString;
+    model: z.ZodString;
+    channel: z.ZodString;
+    attempts: z.ZodNumber;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        done: "done";
+        human: "human";
+    }>;
+    durationMs: z.ZodNumber;
+    firstAttemptOk: z.ZodOptional<z.ZodBoolean>;
+    gateFails: z.ZodOptional<z.ZodNumber>;
+    consults: z.ZodOptional<z.ZodNumber>;
+    parkKind: z.ZodOptional<z.ZodEnum<{
+        setup: "setup";
+        "ladder-exhausted": "ladder-exhausted";
+        "attempt-cap": "attempt-cap";
+        "gate-fail": "gate-fail";
+        quota: "quota";
+        "reroute-exhausted": "reroute-exhausted";
+        stall: "stall";
+        "merge-conflict": "merge-conflict";
+    }>>;
+    tokens: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodOptional<z.ZodNumber>;
+        cacheWrite: z.ZodOptional<z.ZodNumber>;
+        reasoning: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    meteredAttempts: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    quotaFailover: z.ZodOptional<z.ZodLiteral<true>>;
+    overrun: z.ZodOptional<z.ZodLiteral<true>>;
+    retryMode: z.ZodOptional<z.ZodEnum<{
+        resume: "resume";
+        fresh: "fresh";
+    }>>;
+}, z.core.$strip>;
+export type TelemetryRow = z.infer<typeof TelemetryRowSchema>;
+export declare function newRunId(now?: Date): string;
+export declare function readAllTelemetry(repoRoot: string, lastK: number, opts?: {
+    after?: string;
+}): (TelemetryRow & {
+    runId: string;
+})[];
+export declare const RUNS_WINDOW = 50;
+export declare function readProfileCursor(repoRoot: string): string | undefined;
+export declare function loadRoutingProfile(repoRoot: string, cfg: DrovrConfig, opts?: {
+    preview?: boolean;
+}): RoutingProfile | undefined;
+export declare class Journal {
+    readonly dir: string;
+    readonly runId: string;
+    private readonly narrate?;
+    private constructor();
+    static create(repoRoot: string, runId: string, narrate?: (event: JournalEvent) => void): Journal;
+    static open(repoRoot: string, runId: string, narrate?: (event: JournalEvent) => void): Journal;
+    static latestRunId(repoRoot: string): string | null;
+    private get journalPath();
+    append(event: string, taskId?: string, data?: Record<string, unknown>): void;
+    read(): JournalEvent[];
+    replayStatuses(): Map<string, TaskStatus>;
+    replayResumeState(): Map<string, ResumeState>;
+    telemetry(row: TelemetryRow): void;
+    readTelemetry(): TelemetryRow[];
+}

package/dist/run/journal.js

@@ -0,0 +1,287 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { channelKey, TokenUsageSchema } from "../adapters/types.js";
+import { stateDirName } from "../graph/graph.js";
+import { TIERS } from "../graph/schema.js";
+import { buildProfile } from "../route/profile.js";
+export function formatJournalNarration({ event, taskId, data }) {
+    const assignment = data.assignment;
+    const direct = [data.summary, data.reason, data.error, data.step, data.action, data.lint, data.branch, data.from]
+        .find((value) => typeof value === "string" || typeof value === "number");
+    const detail = Array.isArray(data.done)
+        ? `done ${data.done.length}, failed ${Array.isArray(data.failed) ? data.failed.length : 0}`
+        : typeof data.gate === "string"
+            ? `${data.gate}${data.pass === true ? " passed" : data.pass === false ? " failed" : ""}`
+            : typeof data.code === "number" ? `exit ${data.code}`
+                : typeof data.pid === "number" ? `pid ${data.pid}`
+                    : typeof data.baseRef === "string" ? `base ${data.baseRef.slice(0, 12)}`
+                        : direct === undefined
+                            ? typeof assignment?.adapter === "string" && typeof assignment.model === "string" ? `${assignment.adapter}:${assignment.model}` : undefined
+                            : String(direct);
+    return [event, taskId, detail?.replace(/\s+/g, " ").slice(0, 120)].filter(Boolean).join(" — ");
+}
+// v1.24 OBS-18: explicit data on task-approved when the operator releases an attempt-cap park.
+// Approve stamps this; replayResumeState zeros the attempt counter (fresh budget) while keeping
+// tried (consult bans / burned channels). Absent on pre-v1.24 events ⇒ inert (corpus outcome-identical).
+export const ATTEMPT_CAP_RELEASE = "attempt-cap";
+// Fail-closed shape for a dispatched assignment (journal.ts:75-90 posture): a malformed assignment in
+// one dispatch degrades that single task toward today's behavior — counts toward attempts, contributes
+// nothing to tried, poisons only lastAssignment — never crashes resume, never poisons other tasks.
+const DispatchAssignmentSchema = z.object({
+    adapter: z.string(),
+    model: z.string(),
+    channel: z.enum(["sub", "api"]),
+    tier: z.enum(TIERS),
+});
+export const PARK_KINDS = ["ladder-exhausted", "attempt-cap", "gate-fail", "quota",
+    "reroute-exhausted", "setup", "stall", "merge-conflict"];
+export const RETRY_MODES = ["resume", "fresh"];
+export const TelemetryRowSchema = z.object({
+    // v1.5 core — required; every old row has all eight (daemon.ts writes all eight)
+    taskId: z.string(), shape: z.string(), adapter: z.string(), model: z.string(), channel: z.string(),
+    attempts: z.number(), outcome: z.enum(["done", "failed", "human"]), durationMs: z.number(),
+    // v1.6 additive (TEL-01/02) — OPTIONAL: a v1.5 row parses with these === undefined ("unobserved"),
+    // never false/0. Phase 12 readers must branch on === true / === false; `?? false` is the poisoning bug.
+    firstAttemptOk: z.boolean().optional(),
+    gateFails: z.number().optional(),
+    consults: z.number().optional(),
+    parkKind: z.enum(PARK_KINDS).optional(),
+    // v1.7 additive (SPEND-02) — OPTIONAL: absent = unmetered, never 0. .catch(undefined): a MALFORMED
+    // tokens sub-object degrades to unmetered instead of safeParse-dropping the whole row — a metering
+    // bug must never remove a row from profile derivation (that would let metering perturb routing).
+    tokens: TokenUsageSchema.optional().catch(undefined),
+    // v1.7 (SPEND-02): count of attempts that produced a usage record. Present IFF tokens is present.
+    // meteredAttempts < attempts ⇒ tokens is a FLOOR (partially metered task) — Phase 18 must label it,
+    // never print it as a total. Absent ⇒ the row is unmetered entirely.
+    meteredAttempts: z.number().int().positive().optional().catch(undefined),
+    // v1.8 additive (TEL-05) — OPTIONAL, z.literal(true) so `false` is UNREPRESENTABLE: absent = "no
+    // mid-task quota failover observed" (never false), present = attributed to the channel throttled
+    // away FROM. Phase 26 ROUTE-12 (utilization axis) consumes this; only the if(next) branch writes it.
+    quotaFailover: z.literal(true).optional(),
+    // v1.13 additive (ROUTE-18) — OPTIONAL, z.literal(true) so `false` is UNREPRESENTABLE: absent = "no
+    // overrun observed" (never false), present = the channel burned a window without emitting a trailer
+    // (worker-result ok:false, finished:false — no-trailer timeout OR trailer-less crash-exit). Written
+    // only at the daemon's !finished site (after the quota check, quota-disjoint); 48-01's ProfileRow
+    // (src/route/profile.ts) consumes the field-name contract `overrun`. Mirrors quotaFailover exactly.
+    overrun: z.literal(true).optional(),
+    // v1.29 additive: mode of the attempt represented by this row. Absent on old telemetry.
+    retryMode: z.enum(RETRY_MODES).optional(),
+});
+export function newRunId(now = new Date()) {
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return `run-${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+}
+const runsDir = (repoRoot) => join(repoRoot, stateDirName(repoRoot), "runs");
+// One JSONL reader for every append-only log: skip blanks, drop any line that
+// won't parse, keeping everything before it intact.
+function readJsonl(path) {
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // torn trailing write after a crash — ignore; everything before it is intact
+        }
+    }
+    return out;
+}
+// Cross-run telemetry for Phase-12 profile derivation: the last K runs' rows, each
+// tagged with its runId (runIds are zero-padded run-YYYYMMDD-HHMMSS ⇒ plain .sort() is
+// chronological, same as latestRunId). Rows are facts, not classifications — Phase 12
+// owns the quality-denominator/reward policy. A safeParse failure drops that one row
+// (same posture as a torn line); a garbage row must never crash profile derivation.
+// Note: a per-task row attributes to the FINAL channel — a channel escalated away from
+// mid-task contributes no row; accepted for v1.6.
+export function readAllTelemetry(repoRoot, lastK, opts = {}) {
+    const dir = runsDir(repoRoot);
+    if (!existsSync(dir))
+        return [];
+    let runIds = readdirSync(dir).filter((d) => d.startsWith("run-")).sort();
+    // VIS-03 reset cursor: runIds are zero-padded run-YYYYMMDD-HHMMSS ⇒ string > is chronological
+    if (opts.after)
+        runIds = runIds.filter((id) => id > opts.after);
+    runIds = runIds.slice(-lastK);
+    const out = [];
+    for (const runId of runIds) {
+        for (const raw of readJsonl(join(dir, runId, "telemetry.jsonl"))) {
+            const r = TelemetryRowSchema.safeParse(raw);
+            if (r.success)
+                out.push({ ...r.data, runId });
+        }
+    }
+    return out;
+}
+// ponytail: fixed 50-run window; promote to a routing.learned.* config knob only if operators need to tune it.
+export const RUNS_WINDOW = 50;
+// VIS-03 reset cursor — one trimmed runId line at .drovr/profile-since; absent/empty ⇒ undefined.
+// Opaque: used ONLY in the runId > comparison above, never a shell or path join beyond .drovr/.
+export function readProfileCursor(repoRoot) {
+    const path = join(repoRoot, stateDirName(repoRoot), "profile-since");
+    if (!existsSync(path))
+        return undefined;
+    return readFileSync(path, "utf8").trim() || undefined;
+}
+// The one shared profile builder (criterion 4: plan and daemon share ONE code path).
+// preview:true bypasses the routing.learned:off short-circuit so `drovr plan` can render the
+// trust-ramp preview while the daemon (no preview) stays inert (VALIDATION 13-01-11).
+export function loadRoutingProfile(repoRoot, cfg, opts = {}) {
+    if (cfg.routing.learned === "off" && !opts.preview)
+        return undefined; // never built, never passed
+    const rows = readAllTelemetry(repoRoot, RUNS_WINDOW, { after: readProfileCursor(repoRoot) });
+    // ROUTE-15: halfLifeRuns threads from config as a pure param; undefined ⇒ module default (byte-identical).
+    return rows.length ? buildProfile(rows, { halfLifeRuns: cfg.routing.learnedTuning?.halfLifeRuns }) : undefined; // cold ⇒ undefined ⇒ v1.5 dead-code path
+}
+export class Journal {
+    dir;
+    runId;
+    narrate;
+    constructor(dir, runId, narrate) {
+        this.dir = dir;
+        this.runId = runId;
+        this.narrate = narrate;
+    }
+    static create(repoRoot, runId, narrate) {
+        const dir = join(runsDir(repoRoot), runId);
+        mkdirSync(dir, { recursive: true });
+        return new Journal(dir, runId, narrate);
+    }
+    static open(repoRoot, runId, narrate) {
+        const dir = join(runsDir(repoRoot), runId);
+        if (!existsSync(join(dir, "journal.jsonl")))
+            throw new Error(`no journal for ${runId} at ${dir}`);
+        return new Journal(dir, runId, narrate);
+    }
+    static latestRunId(repoRoot) {
+        if (!existsSync(runsDir(repoRoot)))
+            return null;
+        const ids = readdirSync(runsDir(repoRoot)).filter((d) => d.startsWith("run-")).sort();
+        return ids.at(-1) ?? null;
+    }
+    get journalPath() {
+        return join(this.dir, "journal.jsonl");
+    }
+    append(event, taskId, data = {}) {
+        const row = { ts: new Date().toISOString(), event, ...(taskId ? { taskId } : {}), data };
+        appendFileSync(this.journalPath, JSON.stringify(row) + "\n");
+        try {
+            this.narrate?.(row);
+        }
+        catch {
+            // narration is observational; a broken sink must not affect the journal or run
+        }
+    }
+    read() {
+        return readJsonl(this.journalPath);
+    }
+    replayStatuses() {
+        const s = new Map();
+        for (const e of this.read()) {
+            if (!e.taskId)
+                continue;
+            if (e.event === "task-dispatch")
+                s.set(e.taskId, "running");
+            else if (e.event === "task-done")
+                s.set(e.taskId, "done");
+            else if (e.event === "task-failed")
+                s.set(e.taskId, "failed");
+            else if (e.event === "task-human")
+                s.set(e.taskId, "human");
+            // GATE-08 (v1.12): approval is a journal EVENT, never a graph.json mutation (graph.json is compiled
+            // output; recompile re-emits humanGate:true and would silently erase it — Phase 42 D-02). Events
+            // replay in order, so task-human → task-approved lands on pending (last write wins). Additive-only:
+            // 26 real journals with no such event replay byte-identically (D-04).
+            else if (e.event === "task-approved")
+                s.set(e.taskId, "pending");
+        }
+        for (const [id, st] of s)
+            if (st === "running")
+                s.set(id, "pending");
+        return s;
+    }
+    // Phase 46 (RES-01/RES-02): companion replay — derives per-task resume state {attempts, tried,
+    // lastAssignment} from EXISTING events only (task-dispatch + consult-verdict + optional v1.24
+    // task-approved{release:attempt-cap}). Additive-only: no new required event, no schema change, the
+    // status replay above is byte-untouched (corpus criterion 3 is git-diff-provable). Motivated by the
+    // 2026-07-11 incident (run-20260711-185020, P43-03): `drovr resume` re-dispatched at attempt 0 on
+    // pi:zai/glm-5.2, the exact channel a frontier consult had just banned, because execTask's
+    // attempt/tried/assignment state is loop-local and dies with the process while the journal held every fact needed.
+    //
+    // attempts is a COUNT of task-dispatch events, NEVER max(data.attempt)+1: existing journals'
+    // post-resume dispatches restart at 0 (the bug corrupted its own evidence — incident journal L58
+    // logged attempt 0 two ms after run-resume). Count === max+1 on clean journals and is truthful on
+    // corrupted ones. tried is the ordered dedup of channelKey(assignment) across dispatches (≡ the
+    // pre-kill tried list). lastAssignment is the last well-formed dispatched assignment.
+    replayResumeState() {
+        const m = new Map();
+        const pendingReroute = new Set(); // reroute verdicts not yet cleared by a later dispatch
+        for (const e of this.read()) {
+            if (!e.taskId)
+                continue;
+            if (e.event === "task-dispatch") {
+                // A subsequent dispatch clears the pending reroute — the reroute was acted on pre-kill.
+                pendingReroute.delete(e.taskId);
+                let st = m.get(e.taskId);
+                if (!st) {
+                    st = { attempts: 0, tried: [] };
+                    m.set(e.taskId, st);
+                }
+                st.attempts++; // COUNT, never max(data.attempt)+1 — see rationale above
+                const parsed = DispatchAssignmentSchema.safeParse(e.data.assignment);
+                if (parsed.success) {
+                    const key = channelKey(parsed.data);
+                    if (!st.tried.includes(key))
+                        st.tried.push(key);
+                    st.lastAssignment = parsed.data;
+                }
+                else {
+                    // fail closed: malformed assignment still COUNTS (above) but adds nothing to tried and
+                    // poisons only lastAssignment (a malformed LAST dispatch must not be restored).
+                    st.lastAssignment = undefined;
+                }
+            }
+            else if (e.event === "consult-verdict" && e.data.action === "reroute") {
+                // A reroute bans the in-force channel; retry/decompose/human verdicts ban nothing (D-03).
+                pendingReroute.add(e.taskId);
+            }
+            else if (e.event === "task-approved" && e.data.release === ATTEMPT_CAP_RELEASE) {
+                // v1.24 OBS-18: operator released an attempt-cap park. Pre-v1.24 task-approved events have no
+                // `release` key ⇒ this branch never fires (corpus criterion: identical statuses + resume state).
+                // attempts reset to 0 so the daemon's attempt-cap check does not re-park in the same tick;
+                // tried survives (consult bans and burned channels are not forgotten); lastAssignment is
+                // cleared so the daemon's nextChannel-over-tried path skips burned channels on first dispatch
+                // (restoring the last burned assignment would re-try it first — the failure the tried-list exists to prevent).
+                const st = m.get(e.taskId);
+                if (st) {
+                    st.attempts = 0;
+                    st.lastAssignment = undefined;
+                }
+            }
+        }
+        // Trailing-reroute edge (D-01 kill between verdict and dispatch): a reroute verdict with NO
+        // subsequent dispatch means the last-dispatched channel is itself banned — add it to tried (if
+        // absent) and clear lastAssignment so the daemon falls back to nextChannel over the exclusions.
+        for (const taskId of pendingReroute) {
+            const st = m.get(taskId);
+            if (st?.lastAssignment) {
+                const key = channelKey(st.lastAssignment);
+                if (!st.tried.includes(key))
+                    st.tried.push(key);
+                st.lastAssignment = undefined;
+            }
+        }
+        return m;
+    }
+    telemetry(row) {
+        appendFileSync(join(this.dir, "telemetry.jsonl"), JSON.stringify(row) + "\n");
+    }
+    // Per-run, raw (NOT schema-validated) — report.ts reads v1.5 core fields; stays byte-compatible.
+    readTelemetry() {
+        return readJsonl(join(this.dir, "telemetry.jsonl"));
+    }
+}

package/dist/run/lock.d.ts

@@ -0,0 +1,29 @@
+export declare const HEARTBEAT_MS = 10000;
+export declare const STALE_MS = 60000;
+export interface Inspection {
+    pid?: number;
+    runId?: string;
+    garbage: boolean;
+    dead: boolean;
+    expired: boolean;
+    mtimeMs: number;
+    ino: number;
+}
+export declare function shouldRefuse(i: Pick<Inspection, "garbage" | "dead">): boolean;
+export declare function acquireRunLock(repoRoot: string, runId: string): {
+    reclaimed?: {
+        pid: number;
+        mtimeMs: number;
+    };
+};
+export declare function releaseRunLock(repoRoot: string): void;
+export declare function isRunLockLive(repoRoot: string): boolean;
+export declare function unlockRun(repoRoot: string): {
+    held: false;
+} | {
+    held: true;
+    removed: true;
+    pid?: number;
+    runId?: string;
+    garbage: boolean;
+};

package/dist/run/lock.js

@@ -0,0 +1,182 @@
+import { linkSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { drovrDir } from "../graph/graph.js";
+// HARD-01/02: coarse per-run advisory lock over .drovr/graph.json. LOCK-02: the lock is created by
+// the link(2) idiom — write the full payload to graph.lock.<pid>.tmp, then linkSync(tmp, lockPath),
+// which is atomic and throws EEXIST if the lock already exists (the mutual-exclusion primitive).
+// rename() was REJECTED: it silently clobbers an existing destination, destroying that mutual
+// exclusion (two daemons would both "acquire"). LOCK-02 (OBS-05): a PROVABLY-dead holder (ESRCH)
+// self-clears immediately — expiry is NOT required. ESRCH is proof-positive death; the PID-reuse
+// hazard runs the OTHER way (a reused pid reads ALIVE and refuses until `drovr unlock`). mtime stays
+// the heartbeat — it feeds the reclaim race guard (ino+mtime re-stat) and the reclaimed audit value.
+// Zero new deps — node:fs stdlib.
+export const HEARTBEAT_MS = 10_000;
+export const STALE_MS = 60_000; // 6× heartbeat headroom; PITFALLS floor is ≥5s beat / ~30s staleness
+// T-10-01: the payload is a trust boundary — parse with zod, fail closed on garbage. Only
+// 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(drovrDir(repoRoot), "graph.lock");
+let heartbeat;
+let heldPath;
+// 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.
+process.once("exit", () => { if (heldPath)
+    unlinkIfOurs(heldPath); });
+// LOCK-04: the ONE decision table. Both acquireRunLock and isRunLockLive consume this — the two
+// hand-maintained copies of the rule cannot drift. The table changes HERE, once. unlockRun uses the
+// SAME inspect() with its own live-holder refusal (`!dead && !garbage`) — it is the escape hatch, not
+// a second copy of the rule.
+// LOCK-02 (OBS-05): refuse iff garbage OR alive. dead (ESRCH) self-clears through the reclaim branch
+// below — no 60s heartbeat wait. Expiry no longer participates in the DECISION (Inspect still carries
+// `expired` for the race guard + reclaim audit); the heartbeat mechanism itself is untouched.
+// ponytail: a pid REUSED by an unrelated live process reads ALIVE (kill(pid,0) succeeds) and now
+// refuses indefinitely instead of expiring out in ≤60s — that is the fail-closed direction; the
+// escape hatch is `drovr unlock`. Acceptable for a single-machine tool (ESRCH is the only
+// proof-positive death; narrowing further needs pid-start-time correlation, out of scope here).
+// LOCK-01: garbage ⇒ always refuse (mtime irrelevant). It short-circuits before dead can matter —
+// so inspect()'s `dead = pid === undefined` fallback for the garbage row stays harmless. Safe post-16-01:
+// the atomic link(2) write means drovr can no longer mint garbage itself; a garbage payload can only
+// come from external corruption, which is exactly what must refuse. Only `drovr unlock` removes it
+// — a self-heal reclaim would silently overwrite whatever corrupted the file.
+export function shouldRefuse(i) {
+    return i.garbage || !i.dead;
+}
+// statSync throws ENOENT when no lock exists — callers treat that as "not held".
+function inspect(p) {
+    const st = statSync(p); // single stat: both the heartbeat mtime and the reclaim-guard inode
+    const mtimeMs = st.mtimeMs;
+    const expired = Date.now() - mtimeMs > STALE_MS;
+    const parsed = PayloadSchema.safeParse(readPayload(p));
+    const garbage = !parsed.success; // LOCK-01: its own state — shouldRefuse refuses it unconditionally; only `drovr unlock` removes it
+    const pid = parsed.success ? parsed.data.pid : undefined;
+    let dead = pid === undefined; // harmless fallback for the garbage row — garbage short-circuits shouldRefuse before this is read
+    if (pid !== undefined) {
+        try {
+            process.kill(pid, 0);
+            dead = false;
+        } // no throw ⇒ ALIVE
+        catch (k) {
+            dead = k.code === "ESRCH";
+        } // ESRCH ⇒ dead; EPERM ⇒ ALIVE
+    }
+    return { pid, runId: parsed.success ? parsed.data.runId : undefined, garbage, dead, expired, mtimeMs, ino: st.ino };
+}
+function readPayload(p) {
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function unlinkIfOurs(p) {
+    try {
+        const parsed = PayloadSchema.safeParse(readPayload(p));
+        if (parsed.success && parsed.data.pid === process.pid)
+            unlinkSync(p);
+    }
+    catch { /* ENOENT — nothing to release */ }
+}
+export function acquireRunLock(repoRoot, runId) {
+    const p = lockPath(repoRoot);
+    const tmp = join(drovrDir(repoRoot), `graph.lock.${process.pid}.tmp`);
+    try {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* W6: best-effort clean of our own stray tmp from a prior SIGKILL */ }
+        writeFileSync(tmp, JSON.stringify({ pid: process.pid, runId, startedAt: Date.now() }));
+        try {
+            linkSync(tmp, p); // atomic: exists ⇒ EEXIST — replaces the old exclusive-create open, no write window on the lock path
+        }
+        finally {
+            unlinkSync(tmp); // the link survives; tmp is just a handle. finally ⇒ no litter, even for the EEXIST loser
+        }
+        heldPath = p;
+        heartbeat = setInterval(() => { try {
+            const now = new Date();
+            utimesSync(p, now, now);
+        }
+        catch { /* released */ } }, HEARTBEAT_MS);
+        heartbeat.unref(); // never hold the daemon's event loop open
+        return {};
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+        const insp = inspect(p);
+        const { pid, runId: heldRun, garbage, mtimeMs } = insp;
+        if (!shouldRefuse(insp)) {
+            // ponytail: inode+mtime guard NARROWS but does not close the cross-process reclaim double-unlink
+            // race; a real fix needs unlink-by-inode (no POSIX primitive) or a lock-directory rename dance.
+            // Single-machine tool — this is the ceiling.
+            const st = statSync(p); // re-stat immediately before removing — abort if replaced since inspect()
+            if (st.ino !== insp.ino || st.mtimeMs !== insp.mtimeMs)
+                return acquireRunLock(repoRoot, runId); // loser path
+            try {
+                unlinkSync(p);
+            }
+            catch (e2) {
+                if (e2.code !== "ENOENT")
+                    throw e2;
+            } // successor already took it
+            const again = acquireRunLock(repoRoot, runId); // re-serializes two stealers through linkSync
+            return { reclaimed: { pid: pid ?? -1, mtimeMs }, ...again };
+        }
+        if (garbage)
+            throw new Error(".drovr/graph.lock holds an unreadable/garbage payload — refusing to reclaim it; run `drovr unlock` to remove it");
+        // LOCK-02: shouldRefuse is false whenever dead, so this throw is reached only for a LIVE holder
+        // (incl. EPERM = alive-but-not-ours). The dead-but-fresh case self-clears via the reclaim branch.
+        throw new Error(`.drovr/graph.lock held by pid ${pid ?? "?"}${heldRun ? ` (run ${heldRun})` : ""} — another drovr run? (operator escape: \`drovr unlock\`)`);
+    }
+}
+export function releaseRunLock(repoRoot) {
+    if (heartbeat) {
+        clearInterval(heartbeat);
+        heartbeat = undefined;
+    }
+    unlinkIfOurs(lockPath(repoRoot)); // never delete a reclaiming successor's lock — only ours
+    heldPath = undefined;
+}
+// Read-only check for compile: 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 — compile proceeds
+// in step with resume (LOCK-02/OBS-05). Never mutates the lock.
+export function isRunLockLive(repoRoot) {
+    try {
+        return shouldRefuse(inspect(lockPath(repoRoot)));
+    }
+    catch {
+        return false;
+    } // no lock
+}
+// 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
+// refusal names the pid; the operator kills the process. Liveness logic stays here (LOCK-04
+// discipline extends to this caller) — the CLI command is a thin formatter.
+// W4 TOCTOU: liveness is checked, THEN unlinked — a live holder that dies (or a dead pid reused)
+// between inspect() and unlinkSync is a window this does NOT close. Acceptable: unlock is
+// operator-initiated on an already-parked run; worst case is removing a lock a just-reborn process
+// would want, which the operator triggered and can recover by re-running. NOT an atomic re-check.
+export function unlockRun(repoRoot) {
+    const p = lockPath(repoRoot);
+    let insp;
+    try {
+        insp = inspect(p);
+    }
+    catch {
+        return { held: false };
+    } // statSync ENOENT ⇒ no lock
+    if (!insp.dead && !insp.garbage) {
+        throw new Error(`.drovr/graph.lock held by LIVE pid ${insp.pid}${insp.runId ? ` (run ${insp.runId})` : ""} — refusing to unlock; stop that run first`);
+    }
+    try {
+        unlinkSync(p);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    return { held: true, removed: true, pid: insp.pid, runId: insp.runId, garbage: insp.garbage };
+}