tickmarkr 1.30.0

package/dist/cli/commands/status.js

@@ -0,0 +1,162 @@
+import { blockedTasks, loadGraph, pendingTasks } from "../../graph/graph.js";
+import { GATE_NAMES } from "../../graph/schema.js";
+import { Journal } from "../../run/journal.js";
+// ponytail: fixed 2s refresh; promote to config.visibility.* only when an operator asks.
+const REFRESH_MS = 2000;
+// The timer must keep the process ALIVE: an unref'd timer here let the event loop drain after the
+// first frame, so a live `--watch` printed once and exited 0 (OBS-11). Never unref this.
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const attemptStartIdx = (events, taskId) => {
+    let idx = -1;
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.taskId === taskId && (e.event === "task-dispatch" || e.event === "escalation"))
+            idx = i;
+    }
+    return idx;
+};
+/** Derive the live phase column for one task. Counts only that task's events since its last dispatch/escalation. */
+export const derivePhase = (task, events, channel) => {
+    const startIdx = attemptStartIdx(events, task.id);
+    if (startIdx < 0)
+        return "";
+    // Scope to this task — concurrent tasks' events must not leak into the attempt window (D-03).
+    const attempt = events.slice(startIdx).filter((e) => e.taskId === task.id);
+    if (attempt.some((e) => e.event === "task-done" || e.event === "task-failed" || e.event === "task-human"))
+        return "";
+    if (!attempt.some((e) => e.event === "task-dispatch"))
+        return "retrying"; // escalation before re-dispatch
+    if (!attempt.some((e) => e.event === "worker-result"))
+        return channel ? `worker · ${channel}` : "worker";
+    const enabled = GATE_NAMES.filter((g) => task.gates.includes(g));
+    const n = enabled.length;
+    const gateResults = attempt.filter((e) => e.event === "gate-result");
+    if (gateResults.length > 0) {
+        const last = gateResults[gateResults.length - 1];
+        if (!last.data.pass)
+            return `gate ✗ ${last.data.gate}`;
+    }
+    const passed = new Set();
+    for (const e of gateResults)
+        if (e.data.pass)
+            passed.add(String(e.data.gate));
+    const k = passed.size;
+    // n===0 (no enabled gates) → merge window immediately after worker-result
+    if (n === 0 || k >= n) {
+        if (!attempt.some((e) => e.event === "merge" || e.event === "task-done"))
+            return "merging";
+        return "";
+    }
+    return `gate ${k + 1}/${n} ${enabled[k]}`;
+};
+// VIS-11 (v1.13): a liveness header for renderFrame — last journal event age + whether the recorded
+// daemon pid is still alive. Honest about unknowns: a pre-v1.13 journal with no pid renders "unknown",
+// never fabricated (garbage pid data fails toward unknown too). kill(pid,0) is a signal probe, not a
+// write — VIS-07 purity holds (status stays a pure reader; the snapshot-purity test is the fence).
+// The lock.ts:52-53 idiom: ESRCH ⇒ dead, EPERM/success ⇒ alive.
+const fmtAge = (ms) => {
+    if (ms < 90_000)
+        return `${Math.floor(ms / 1000)}s`;
+    if (ms < 5_400_000)
+        return `${Math.floor(ms / 60_000)}m`;
+    return `${Math.floor(ms / 3_600_000)}h`;
+};
+// last valid recording wins: scan from the newest event for the most recent run-start/run-resume
+// carrying a positive-integer pid. Anything else (absent, non-integer, ≤0) ⇒ undefined ⇒ unknown.
+const daemonPid = (events) => {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if ((e.event === "run-start" || e.event === "run-resume") && Number.isInteger(e.data.pid) && e.data.pid > 0) {
+            return e.data.pid;
+        }
+    }
+    return undefined;
+};
+const livenessLine = (events) => {
+    const last = events.at(-1);
+    if (!last)
+        return null; // nothing to be honest about
+    const age = fmtAge(Date.now() - Date.parse(last.ts));
+    const pid = daemonPid(events);
+    if (pid === undefined)
+        return `  last event ${age} ago · daemon pid unknown`;
+    let state;
+    try {
+        process.kill(pid, 0);
+        state = "alive";
+    } // no throw ⇒ alive
+    catch (k) {
+        state = k.code === "ESRCH" ? "dead" : "alive";
+    } // EPERM ⇒ alive
+    return `  last event ${age} ago · daemon pid ${pid} ${state}`;
+};
+const renderFrame = (cwd) => {
+    const g = loadGraph(cwd);
+    const runId = Journal.latestRunId(cwd);
+    const assignments = new Map();
+    const gates = new Map();
+    let replayed = null;
+    let events = [];
+    // v1.23 T2: latest known context tokens per task (from context-sample journal events). Informational
+    // only — never feeds status/phase/gate classification (derivePhase and replayStatuses ignore them).
+    const contexts = new Map();
+    if (runId) {
+        const j = Journal.open(cwd, runId);
+        events = j.read();
+        replayed = j.replayStatuses();
+        for (const e of events) {
+            if (e.event === "task-dispatch" && e.taskId) {
+                const a = e.data.assignment;
+                assignments.set(e.taskId, `${a.adapter}:${a.model}`);
+            }
+            if (e.event === "gate-result" && e.taskId) {
+                const prev = gates.get(e.taskId) ?? "";
+                gates.set(e.taskId, `${prev}${e.data.pass ? "✓" : "✗"}${e.data.gate} `);
+            }
+            if (e.event === "context-sample" && e.taskId && typeof e.data.tokens === "number" && Number.isFinite(e.data.tokens)) {
+                contexts.set(e.taskId, e.data.tokens); // last write wins
+            }
+        }
+    }
+    const effective = { ...g, tasks: g.tasks.map((t) => ({ ...t, status: replayed?.get(t.id) ?? t.status })) };
+    const starved = new Set(blockedTasks(effective).map((t) => t.id));
+    const waiting = new Set(pendingTasks(effective).map((t) => t.id));
+    const rows = g.tasks.map((t) => {
+        const st = replayed?.get(t.id) ?? t.status;
+        const label = starved.has(t.id) ? " starved" : waiting.has(t.id) ? " dep-waiting" : "";
+        const phase = derivePhase(t, events, assignments.get(t.id)) || "-";
+        const base = assignments.get(t.id) ?? "-";
+        const ctx = contexts.get(t.id);
+        // Informational suffix only when known — never invents 0 from absence.
+        const assignCol = ctx !== undefined ? `${base} · ctx ${ctx}` : base;
+        return `  ${t.id.padEnd(6)} ${String(st).padEnd(8)} ${phase.padEnd(28)} ${assignCol.padEnd(28)} ${gates.get(t.id) ?? ""}${label}`;
+    });
+    return [
+        `drovr status${runId ? ` — run ${runId}` : " — no runs yet"}`,
+        ...(runId ? [livenessLine(events)].filter((l) => l !== null) : []),
+        "  task   status   phase                        assignment                   gates",
+        ...rows,
+    ].join("\n");
+};
+export async function status(argv, cwd = process.cwd(), opts = {}) {
+    if (!argv.includes("--watch"))
+        return renderFrame(cwd);
+    const iterations = opts.iterations ?? Infinity;
+    const sleep = opts.sleep ?? defaultSleep;
+    const bounded = Number.isFinite(iterations);
+    const frames = [];
+    const sep = "\n---\n";
+    const tty = process.stdout.isTTY;
+    for (let i = 0; i < iterations; i++) {
+        const frame = renderFrame(cwd);
+        if (tty)
+            process.stdout.write(`\x1b[2J\x1b[H${frame}`);
+        else
+            process.stdout.write(frame + sep);
+        if (bounded)
+            frames.push(frame);
+        if (i + 1 < iterations)
+            await sleep(REFRESH_MS);
+    }
+    return bounded ? frames.join(sep) : "";
+}

package/dist/cli/commands/unlock.d.ts

@@ -0,0 +1 @@
+export declare function unlock(_argv: string[], cwd?: string): Promise<string>;

package/dist/cli/commands/unlock.js

@@ -0,0 +1,11 @@
+import { unlockRun } from "../../run/lock.js";
+// LOCK-03: thin formatter over unlockRun. A live-holder refusal propagates as the throw — the
+// dispatcher prints `drovr unlock: …` and exits 1 (src/cli/index.ts).
+export async function unlock(_argv, cwd = process.cwd()) {
+    const r = unlockRun(cwd);
+    if (!r.held)
+        return "no lock held — nothing to remove";
+    if (r.garbage)
+        return "removed garbage lock (unparseable payload)";
+    return `removed stale lock — holder pid ${r.pid}${r.runId ? ` (run ${r.runId})` : ""} is dead`;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export type CommandMap = Record<string, (argv: string[]) => Promise<string>>;
+export declare const COMMANDS: CommandMap;
+export declare const USAGE = "drovr \u2014 spec-driven orchestration harness for AI coding agents\nusage: drovr <command>\n  init          guided setup + doctor\n  doctor        re-probe adapters, herdr, auth; print capability matrix\n  compile <src> spec \u2192 .drovr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  run           execute the graph (--concurrency N --driver herdr|subprocess --route-strict)\n  status        live run state\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  approve <id> <task>  approve a parked human gate (--by <name> --reason <text>); takes effect on resume";
+export declare function dispatch(cmd: string | undefined, argv: string[], commands?: CommandMap): Promise<{
+    out: string;
+    code: number;
+}>;

package/dist/cli/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { approve } from "./commands/approve.js";
+import { compile } from "./commands/compile.js";
+import { doctor } from "./commands/doctor.js";
+import { init } from "./commands/init.js";
+import { plan } from "./commands/plan.js";
+import { profile } from "./commands/profile.js";
+import { report } from "./commands/report.js";
+import { resume } from "./commands/resume.js";
+import { run } from "./commands/run.js";
+import { scope } from "./commands/scope.js";
+import { status } from "./commands/status.js";
+import { unlock } from "./commands/unlock.js";
+export const COMMANDS = {
+    init, doctor, compile, scope, plan, run, status, resume, report, profile, unlock, approve,
+};
+export const USAGE = `drovr — spec-driven orchestration harness for AI coding agents
+usage: drovr <command>
+  init          guided setup + doctor
+  doctor        re-probe adapters, herdr, auth; print capability matrix
+  compile <src> spec → .drovr/graph.json (fails without acceptance criteria)
+  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)
+  plan          dry-run routing table + cost estimate + floor lints
+  run           execute the graph (--concurrency N --driver herdr|subprocess --route-strict)
+  status        live run state
+  resume <id>   continue a run from its journal
+  report <id>   cost/quality report (--md for committable execution record)
+  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)
+  unlock        remove a stale/garbage run lock (refuses if the holder is alive)
+  approve <id> <task>  approve a parked human gate (--by <name> --reason <text>); takes effect on resume`;
+// pure, testable dispatcher: resolves a command, forwards argv, shapes the result — no side effects.
+// unknown/missing cmd → USAGE (exit 1 if a cmd was typed, 0 for bare `drovr`); a handler throw becomes
+// a one-line `drovr <cmd>: <message>` (never a raw stack) at exit 1.
+export async function dispatch(cmd, argv, commands = COMMANDS) {
+    const fn = cmd ? commands[cmd] : undefined;
+    if (!fn)
+        return { out: USAGE, code: cmd ? 1 : 0 };
+    try {
+        return { out: await fn(argv), code: 0 };
+    }
+    catch (err) {
+        return { out: `drovr ${cmd}: ${err.message}`, code: 1 };
+    }
+}
+/* v8 ignore start -- binary entry: printing + process.exit side effects, not unit-testable (ROADMAP crit 2) */
+// node realpaths the main module (import.meta.url) but argv[1] keeps the symlink path —
+// a globally-linked `drovr` bin silently no-oped here (OBS-10); compare realpaths
+const argv1Real = (() => { try {
+    return process.argv[1] ? realpathSync(process.argv[1]) : "";
+}
+catch {
+    return "";
+} })();
+if (argv1Real && import.meta.url === pathToFileURL(argv1Real).href) {
+    const [cmd, ...argv] = process.argv.slice(2);
+    dispatch(cmd, argv).then(({ out, code }) => {
+        // byte-identical streams: usage + success → stdout; a handler throw → stderr (original behavior)
+        (out === USAGE || code === 0 ? console.log : console.error)(out);
+        if (code !== 0)
+            process.exit(code);
+    });
+}
+/* v8 ignore stop */

package/dist/compile/collateral.d.ts

@@ -0,0 +1,6 @@
+import type { Task } from "../graph/schema.js";
+/**
+ * Return human-readable scope-lint lines for plan output (no `!` prefix — plan owns that).
+ * Each line names the task id and at least one missing collateral test path.
+ */
+export declare function collateralLints(tasks: ReadonlyArray<Pick<Task, "id" | "files">>, repoRoot: string): string[];

package/dist/compile/collateral.js

@@ -0,0 +1,128 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+// Advisory plan-time scan only (OBS-12/13/14/21). NEVER expands files[], fails compile, or
+// feeds the scope gate — a warning the author acts on. Plain-text (no AST), capped + sorted.
+/** Max test files walked under tests/ (sorted walk; rest ignored). */
+const MAX_TEST_FILES = 400;
+/** Max collateral test paths listed per task. */
+const MAX_HITS_PER_TASK = 20;
+/** Skip giant fixtures / snapshots. */
+const MAX_READ_BYTES = 512 * 1024;
+const SRC_EXT = /\.(ts|tsx|js|jsx|mts|cts)$/;
+const CODE_EXT = /\.(ts|tsx|js|jsx|mts|cts)$/;
+function isSrcPath(p) {
+    const n = p.replace(/^\.\//, "");
+    return n.startsWith("src/") && SRC_EXT.test(n) && !n.includes("node_modules/");
+}
+function needlesFor(srcPath) {
+    const n = srcPath.replace(/^\.\//, "");
+    const noExt = n.slice(0, n.length - extname(n).length); // src/adapters/codex
+    // path needles only (no bare basename — avoids prose/identifier false positives)
+    // repo-relative import forms that appear in tests (ESM often uses .js)
+    return [...new Set([noExt, `${noExt}.js`, `${noExt}.ts`, n])].filter((s) => s.length > 0);
+}
+function walkTests(repoRoot) {
+    const root = join(repoRoot, "tests");
+    const out = [];
+    const walk = (dir) => {
+        if (out.length >= MAX_TEST_FILES)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // no tests/ or unreadable — zero lints
+        }
+        // deterministic order
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (out.length >= MAX_TEST_FILES)
+                return;
+            if (e.name === "node_modules" || e.name === ".git" || e.name.startsWith("."))
+                continue;
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!e.isFile() || !CODE_EXT.test(e.name))
+                continue;
+            const rel = relative(repoRoot, full).split("\\").join("/");
+            out.push(rel);
+        }
+    };
+    try {
+        if (!statSync(root).isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    walk(root);
+    return out;
+}
+function mentions(content, needles) {
+    for (const n of needles) {
+        if (n.length >= 2 && content.includes(n))
+            return true;
+    }
+    return false;
+}
+/**
+ * Return human-readable scope-lint lines for plan output (no `!` prefix — plan owns that).
+ * Each line names the task id and at least one missing collateral test path.
+ */
+export function collateralLints(tasks, repoRoot) {
+    const testFiles = walkTests(repoRoot);
+    if (!testFiles.length)
+        return [];
+    // cache file bodies (one read per test path)
+    const body = new Map();
+    const read = (rel) => {
+        if (body.has(rel))
+            return body.get(rel);
+        try {
+            const st = statSync(join(repoRoot, rel));
+            if (st.size > MAX_READ_BYTES) {
+                body.set(rel, null);
+                return null;
+            }
+            const text = readFileSync(join(repoRoot, rel), "utf8");
+            body.set(rel, text);
+            return text;
+        }
+        catch {
+            body.set(rel, null);
+            return null;
+        }
+    };
+    const lines = [];
+    for (const t of tasks) {
+        const scoped = new Set(t.files.map((f) => f.replace(/^\.\//, "")));
+        const srcFiles = t.files.map((f) => f.replace(/^\.\//, "")).filter(isSrcPath);
+        if (!srcFiles.length)
+            continue;
+        // needles unioned across all src files in this task
+        const needles = [...new Set(srcFiles.flatMap(needlesFor))];
+        const hits = [];
+        for (const tf of testFiles) {
+            if (scoped.has(tf))
+                continue;
+            const text = read(tf);
+            if (text === null)
+                continue;
+            if (mentions(text, needles))
+                hits.push(tf);
+            if (hits.length >= MAX_HITS_PER_TASK)
+                break;
+        }
+        if (!hits.length)
+            continue;
+        // deterministic: walk already sorted; stable list
+        const listed = hits.join(", ");
+        const tail = hits.length >= MAX_HITS_PER_TASK ? " (capped)" : "";
+        lines.push(`${t.id}: likely collateral tests not in files[]: ${listed}${tail}`);
+    }
+    return lines;
+}

package/dist/compile/common.d.ts

@@ -0,0 +1,12 @@
+import type { Shape } from "../graph/schema.js";
+export declare class CompileError extends Error {
+    constructor(msg: string);
+}
+export declare function sha256(content: string): string;
+export declare function inferShape(description: string): Shape;
+export interface WriteDirective {
+    path: string;
+    directive: string;
+    bare?: string;
+}
+export declare function assertWriteScope(source: string, taskId: string, files: string[], writes: WriteDirective[]): void;

package/dist/compile/common.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import picomatch from "picomatch";
+export class CompileError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "CompileError";
+    }
+}
+export function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function inferShape(description) {
+    if (/\btests?\b|\btesting\b/i.test(description))
+        return "tests";
+    if (/\bdocs?\b|\bdocument(ation)?\b/i.test(description))
+        return "docs";
+    if (/migrat/i.test(description))
+        return "migration";
+    if (/\b(ui|screen|component)\b/i.test(description))
+        return "ui";
+    if (/refactor/i.test(description))
+        return "refactor";
+    return "implement";
+}
+// DOCUMENTED LIMIT: a write demand in freeform prose with no backticked path after a write verb
+// is NOT caught here (zero such cases across 87 real acceptance criteria). The runtime scope gate
+// is the backstop — weakened because it passes anything a worker declares as a deviation.
+export function assertWriteScope(source, taskId, files, writes) {
+    // #1 over-fire landmine: empty files[] is unrestricted — mirrors scope.ts:12
+    if (!files.length)
+        return;
+    const inScope = picomatch(files, { dot: true }); // byte-identical options to src/gates/scope.ts:15
+    for (const { path, directive, bare } of writes) {
+        const normalized = path.replace(/^\.\//, "");
+        if (inScope(normalized))
+            continue;
+        // HARD-09: relocation-invariant self-write check. A bare-name directive is scoped iff SOME
+        // files_modified entry names that exact filename (literal suffix — no second matcher semantics;
+        // one matcher, per the v1.11 byte-identity decision with src/gates/scope.ts). v1.9-29's P30-02
+        // shape has NO entry with the SUMMARY's basename anywhere → still rejected. Moreover v1.9-29's
+        // four directives all carry a full slashed path (bare is never set), so it never reaches here.
+        //
+        // DOCUMENTED LIMIT A: a files_modified entry naming the same basename in a DIFFERENT directory
+        // satisfies the fallback although the write lands in the phase dir. Zero such cases in the real
+        // corpus (every observed self-write entry lives in the plan's own dir); the now-fixed runtime
+        // scope gate (src/gates/scope.ts) is the backstop.
+        // DOCUMENTED LIMIT B: a relocated plan whose self-write scope is a GLOB rather than a literal
+        // still over-fires. Zero such cases exist (all corpus files_modified entries are literal paths).
+        if (bare && files.some((f) => f === bare || f.endsWith(`/${bare}`)))
+            continue;
+        throw new CompileError(`${source}: task ${taskId} write directive orders a path outside files_modified.\n` +
+            `  directive: ${directive.trim()}\n` +
+            `  path: ${normalized}\n` +
+            `  remedy: add the path to files_modified, or drop the directive.`);
+    }
+}

package/dist/compile/gsd.d.ts

@@ -0,0 +1,3 @@
+import { type RunGraph } from "../graph/schema.js";
+export declare function isGsdPhaseDir(dir: string): boolean;
+export declare function compileGsd(src: string, root?: string): RunGraph;