tickmarkr 2.4.2 → 2.5.0

package/dist/plan/scope.js

@@ -1,13 +1,16 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
-import { discoverChannels, getAdapter, probeAll } from "../adapters/registry.js";
+import { discoverChannels, getAdapter, probeAll, readDoctor } from "../adapters/registry.js";
 import { compileNative, LEGACY_PREFIX } from "../compile/native.js";
 import { pickDriver } from "../drivers/index.js";
 import { extractJson, runLlm } from "../gates/llm.js";
 import { TaskSchema } from "../graph/schema.js";
 import { route } from "../route/router.js";
 import { scopePrompt } from "./prompt.js";
+// R11/R45 (C10): the drafting loop's hard ceiling — shared by the loop itself and the preview
+// disclosure so the two can never state different budgets.
+export const MAX_SCOPE_ATTEMPTS = 3;
 const HEADING_RE = /^#{1,6}\s+(.+?)\s*$/;
 const ITEM_RE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)(?:\[[ xX]\]\s*)?(?:[QA]\d*:\s*)?(.+?)\s*$/;
 function sectionItems(source, heading) {
@@ -95,7 +98,13 @@ function validateDraft(draft) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
-export async function scopeIntent(intentFile, repoRoot, options) {
+function scopePlanningTask() {
+    return TaskSchema.parse({
+        id: "SCOPE", title: "Draft native spec", goal: "Draft a compiled native spec", shape: "spec", complexity: 7,
+        acceptance: [{ oracle: "judge", text: "Every requirement maps to a task with typed acceptance oracles" }],
+    });
+}
+function localValidate(intentFile) {
     if (!existsSync(intentFile))
         throw new Error(`no such intent file: ${intentFile}`);
     const intent = readFileSync(intentFile, "utf8");
@@ -103,21 +112,92 @@ export async function scopeIntent(intentFile, repoRoot, options) {
     if (unanswered.length) {
         throw new Error(`unanswered blocking questions (${unanswered.length}):\n${unanswered.map((q, i) => `${i + 1}. ${q}`).join("\n")}`);
     }
-    const specFile = specPathForIntent(intentFile);
+    return { intent, specFile: specPathForIntent(intentFile) };
+}
+/**
+ * R11/R45 (C10): local-only disclosure — intent/clarification checks and a candidate read off the
+ * doctor cache, never a fresh probe or a model turn. `readDoctor` and `discoverChannels`/`route` are
+ * pure reads over that cache, so this never touches an adapter.
+ */
+export function previewScope(intentFile, repoRoot, options) {
+    const { specFile } = localValidate(intentFile);
+    const cachedHealth = readDoctor(repoRoot);
+    let candidate;
+    if (cachedHealth) {
+        const channels = discoverChannels(options.cfg, options.adapters, cachedHealth);
+        if (channels.length) {
+            try {
+                const assignment = route(scopePlanningTask(), options.cfg, channels).assignment;
+                // Review fix (finding 1): routing.allowUnverifiedModels lets discoverChannels/route pick a
+                // channel whose modelAuth is simply absent (unknown) — that is routing PERMISSION, not proof
+                // of health. Only disclose a candidate when the doctor cache actually marked this exact model
+                // authed; otherwise this stays the "unknown" case below, never "installed/authed".
+                if (cachedHealth[assignment.adapter]?.modelAuth?.[assignment.model]?.authed === true) {
+                    candidate = { adapter: assignment.adapter, model: assignment.model };
+                }
+            }
+            catch {
+                // no eligible candidate in the cached snapshot — stays unknown, never "unreachable"
+            }
+        }
+    }
+    return {
+        intentFile, specFile, specExists: existsSync(specFile), cached: cachedHealth !== null,
+        candidate, authoringBudget: MAX_SCOPE_ATTEMPTS, probeCalls: options.adapters.length,
+    };
+}
+export function formatScopePreview(preview) {
+    const candidateLine = preview.candidate
+        ? `cached candidate: ${preview.candidate.adapter}:${preview.candidate.model} (installed/authed at last doctor run)`
+        : `cached candidate: unknown (${preview.cached ? "no eligible channel in the doctor cache" : "no doctor cache — run tickmarkr doctor"})`;
+    return [
+        `tickmarkr scope --preview ${preview.intentFile}:`,
+        candidateLine,
+        `output destination: ${preview.specFile}${preview.specExists ? " (exists — active scope needs --force)" : ""}`,
+        `authoring-call budget: up to ${preview.authoringBudget} call${preview.authoringBudget === 1 ? "" : "s"} if confirmed`,
+        `probe calls: ${preview.probeCalls} (disclosed separately — one per configured adapter, only on confirmed active scope)`,
+        "cache policy: read-only; no adapter was probed and no model was called",
+    ].join("\n");
+}
+// R11/R45 (C10 repair): a confirmed candidate is a promise made to the operator — find that exact
+// adapter:model in the freshly probed channels, or fail loud. Never let a stale-cache candidate
+// silently fall through to a fresh route() that could reroute to a different channel unconfirmed.
+function bindCandidate(candidate, channels) {
+    const c = channels.find((ch) => ch.adapter === candidate.adapter && ch.model === candidate.model);
+    if (!c) {
+        throw new Error(`confirmed candidate ${candidate.adapter}:${candidate.model} is no longer available after a fresh probe ` +
+            `(doctor found: ${channels.map((ch) => `${ch.adapter}:${ch.model}`).join(", ") || "(nothing)"}) — ` +
+            "re-run scope --preview and confirm again");
+    }
+    return { adapter: c.adapter, model: c.model, channel: c.channel, tier: c.tier };
+}
+// Adapter-level probes establish the current installation/auth state, but shipped adapters do not
+// return per-model verdicts from probe(). Preserve cached verdicts only where that fresh snapshot is
+// silent; an explicit fresh per-model verdict still wins, as do fresh adapter-level failures.
+function mergeCachedModelAuth(freshHealth, cachedHealth) {
+    if (!cachedHealth)
+        return freshHealth;
+    return Object.fromEntries(Object.entries(freshHealth).map(([adapter, fresh]) => {
+        const cachedModelAuth = cachedHealth[adapter]?.modelAuth;
+        if (!cachedModelAuth)
+            return [adapter, fresh];
+        return [adapter, { ...fresh, modelAuth: { ...cachedModelAuth, ...fresh.modelAuth } }];
+    }));
+}
+export async function scopeIntent(intentFile, repoRoot, options) {
+    const { intent, specFile } = localValidate(intentFile);
     if (existsSync(specFile) && !options.force)
         throw new Error(`${specFile} already exists; pass --force to overwrite it`);
-    const health = await probeAll(options.adapters);
+    const health = mergeCachedModelAuth(await probeAll(options.adapters), readDoctor(repoRoot));
     const channels = discoverChannels(options.cfg, options.adapters, health);
-    const planningTask = TaskSchema.parse({
-        id: "SCOPE", title: "Draft native spec", goal: "Draft a compiled native spec", shape: "spec", complexity: 7,
-        acceptance: [{ oracle: "judge", text: "Every requirement maps to a task with typed acceptance oracles" }],
-    });
-    const assignment = route(planningTask, options.cfg, channels).assignment;
+    const assignment = options.candidate
+        ? bindCandidate(options.candidate, channels)
+        : route(scopePlanningTask(), options.cfg, channels).assignment;
     const adapter = getAdapter(assignment.adapter, options.adapters);
     const driver = options.cfg.visibility.llm === "pane" ? options.driver ?? pickDriver(options.cfg) : undefined;
     const name = basename(specFile, ".spec.md");
     let prompt = scopePrompt(intent);
-    for (let attempts = 1; attempts <= 3; attempts++) {
+    for (let attempts = 1; attempts <= MAX_SCOPE_ATTEMPTS; attempts++) {
         const via = driver ? {
             driver, name: `scope-${name}-${attempts}-${adapter.id}`, label: "SCOPE",
             keep: options.cfg.visibility.keepPanes === "forever",
@@ -129,8 +209,8 @@ export async function scopeIntent(intentFile, repoRoot, options) {
         }
         catch (error) {
             const message = error.message;
-            if (attempts === 3)
-                throw new Error(`scope draft failed after 2 repair retries:\n${message}`);
+            if (attempts === MAX_SCOPE_ATTEMPTS)
+                throw new Error(`scope draft failed after ${MAX_SCOPE_ATTEMPTS - 1} repair retries:\n${message}`);
             prompt = scopePrompt(intent, { draft, error: message });
             continue;
         }

package/dist/report/operator-record.d.ts

@@ -0,0 +1,49 @@
+import type { TokenUsage } from "../adapters/types.js";
+import type { JournalEvent } from "../run/journal.js";
+import type { ChannelCost } from "./cost.js";
+export declare function formatTokenUsage(u: TokenUsage): string;
+export declare function totalTokens(u: TokenUsage): number;
+/** The channel a journal event's `assignment` names, or absent — never coalesced to a placeholder
+ * string here, so a caller decides its own absent-channel reading. */
+export declare function assignmentChannel(data: Record<string, unknown>): string | undefined;
+/** Worker token coverage: "unmetered" when the adapter reported no usage at all — distinct from a
+ * channel with no telemetry row whatsoever, which `labelChannelUsage` below calls "unknown". */
+export declare function formatChannelTokens(row: ChannelCost): string;
+export declare function formatRateBasis(row: ChannelCost): string | undefined;
+/** Nonmeasurable money always says so explicitly (`row.reason`, or "not recorded") — never a $0. */
+export declare function formatChannelMoney(row: ChannelCost): {
+    readonly prices: string[];
+    readonly bases: string[];
+};
+export interface ChannelUsageLabel {
+    readonly channel: string;
+    /** "unmetered" (metered run, adapter reported nothing), a real total, or "unknown" (no telemetry
+     *  row exists for this channel at all — missing metadata, never invented). */
+    readonly tokens: string;
+    /** "not measurable" (metered but unpriced/partial), a real dollar figure, or "unknown" (no row). */
+    readonly money: string;
+}
+/** Labels one channel's metered/priced facts. `row` absent means journal evidence names this
+ *  channel (e.g. a pre-telemetry run) but no telemetry row was ever recorded for it — missing
+ *  metadata, distinct from a recorded-but-unpriced/unmetered row. */
+export declare function labelChannelUsage(channel: string, row: ChannelCost | undefined): ChannelUsageLabel;
+export interface ChannelRoleCounts {
+    readonly channel: string;
+    /** Dispatches recorded for this channel as the task's worker. */
+    readonly worker: number;
+    /** Review gate-results whose reviewer identity resolved to this channel. */
+    readonly review: number;
+    /** Consult verdicts recorded against the task this channel was last dispatched on. */
+    readonly consult: number;
+}
+/** Recorded worker/review/consult appearances per channel, read only from journal evidence — no
+ *  extrapolation to an all-role invoice. A channel that only ever reviewed still gets a row with
+ *  worker:0, never a fabricated dispatch. */
+export declare function channelRoleCounts(events: readonly JournalEvent[]): ChannelRoleCounts[];
+export interface OperatorRecordRow extends ChannelRoleCounts, Omit<ChannelUsageLabel, "channel"> {
+}
+/** The shared record: one row per channel journal evidence actually names (role counts), joined
+ *  with that channel's metered/priced facts. A channel `costs` prices but journal evidence never
+ *  names gets no row here — this never invents a role from cost data alone. */
+export declare function buildOperatorRecord(events: readonly JournalEvent[], costs?: readonly ChannelCost[]): OperatorRecordRow[];
+export declare function formatOperatorRecordRow(row: OperatorRecordRow): string;

package/dist/report/operator-record.js

@@ -0,0 +1,137 @@
+const n = (x) => x.toLocaleString("en-US");
+export function formatTokenUsage(u) {
+    const parts = [`in ${n(u.input)}`, `out ${n(u.output)}`];
+    if (u.cacheRead !== undefined && u.cacheWrite !== undefined)
+        parts.push(`cache r/w ${n(u.cacheRead)}/${n(u.cacheWrite)}`);
+    if (u.reasoning !== undefined)
+        parts.push(`reasoning ${n(u.reasoning)}`);
+    return parts.join("  ");
+}
+export function totalTokens(u) {
+    return [u.input, u.output, u.cacheRead, u.cacheWrite, u.reasoning].filter((x) => x !== undefined).reduce((a, b) => a + b, 0);
+}
+/** The channel a journal event's `assignment` names, or absent — never coalesced to a placeholder
+ * string here, so a caller decides its own absent-channel reading. */
+export function assignmentChannel(data) {
+    const assignment = data.assignment;
+    if (!assignment || typeof assignment !== "object")
+        return undefined;
+    const { adapter, model } = assignment;
+    return typeof adapter === "string" && typeof model === "string" ? `${adapter}:${model}` : undefined;
+}
+/** Worker token coverage: "unmetered" when the adapter reported no usage at all — distinct from a
+ * channel with no telemetry row whatsoever, which `labelChannelUsage` below calls "unknown". */
+export function formatChannelTokens(row) {
+    return row.tokens
+        ? `${row.partialMetering ? "≥ " : ""}${formatTokenUsage(row.tokens)} (${n(totalTokens(row.tokens))} tokens)`
+        : "unmetered";
+}
+export function formatRateBasis(row) {
+    if (!row.rate)
+        return undefined;
+    const cache = row.rate.cacheReadPerMtok === undefined ? "" : `; cache-read $${row.rate.cacheReadPerMtok}/Mtok`;
+    const date = row.rate.rateDate === undefined ? "" : `; rate date ${row.rate.rateDate}`;
+    return `in/out $${row.rate.inPerMtok}/$${row.rate.outPerMtok}/Mtok${cache}${date}`;
+}
+/** Nonmeasurable money always says so explicitly (`row.reason`, or "not recorded") — never a $0. */
+export function formatChannelMoney(row) {
+    const prices = [];
+    const bases = [];
+    if (row.apiUsd !== undefined)
+        prices.push(`price: $${row.apiUsd.toFixed(6)}`);
+    if (row.amortizedUsd !== undefined && row.subPlan !== undefined) {
+        const [low, high] = row.amortizedUsd;
+        prices.push(`price: $${low.toFixed(6)}–$${high.toFixed(6)} amortized`);
+        bases.push(`${n(row.attempts)} windows × $${row.subPlan.planMonthly}/month ÷ ${row.subPlan.windowsPerMonthHigh}–${row.subPlan.windowsPerMonthLow} windows/month`);
+    }
+    if (row.counterfactualUsd !== undefined)
+        prices.push(`API-equivalent: $${row.counterfactualUsd.toFixed(6)}`);
+    const basis = formatRateBasis(row);
+    if (basis)
+        bases.push(basis);
+    if (!prices.length)
+        prices.push("price: not measurable");
+    if (!bases.length)
+        bases.push(row.reason || "not recorded");
+    return { prices, bases };
+}
+/** Labels one channel's metered/priced facts. `row` absent means journal evidence names this
+ *  channel (e.g. a pre-telemetry run) but no telemetry row was ever recorded for it — missing
+ *  metadata, distinct from a recorded-but-unpriced/unmetered row. */
+export function labelChannelUsage(channel, row) {
+    if (!row)
+        return { channel, tokens: "unknown", money: "unknown" };
+    const { prices } = formatChannelMoney(row);
+    return { channel, tokens: formatChannelTokens(row), money: prices.join("; ") };
+}
+const REVIEWER_PATTERN = /reviewer\s+([^\s;()]+:[^\s;()]+)/i;
+function reviewerChannel(data) {
+    if (typeof data.reviewer === "string" && data.reviewer.includes(":"))
+        return data.reviewer;
+    const meta = typeof data.meta === "object" && data.meta !== null ? data.meta : undefined;
+    if (meta && "reviewer" in meta && typeof meta.reviewer === "string" && meta.reviewer.includes(":"))
+        return meta.reviewer;
+    return typeof data.details === "string" ? REVIEWER_PATTERN.exec(data.details)?.[1] : undefined;
+}
+/** The channel a `consult-verdict` event names as ITS OWN consultant identity (daemon.ts always
+ *  appends `adapter`/`model` on every verdict) — never the task's worker dispatch, which is a
+ *  different channel a consult can (and typically does) disagree with. */
+function consultChannel(data) {
+    const { adapter, model } = data;
+    return typeof adapter === "string" && typeof model === "string" ? `${adapter}:${model}` : undefined;
+}
+/** Recorded worker/review/consult appearances per channel, read only from journal evidence — no
+ *  extrapolation to an all-role invoice. A channel that only ever reviewed still gets a row with
+ *  worker:0, never a fabricated dispatch. */
+export function channelRoleCounts(events) {
+    const counts = new Map();
+    const ensure = (channel) => {
+        let row = counts.get(channel);
+        if (!row) {
+            row = { worker: 0, review: 0, consult: 0 };
+            counts.set(channel, row);
+        }
+        return row;
+    };
+    for (const e of events) {
+        if (e.event === "task-dispatch") {
+            const channel = assignmentChannel(e.data);
+            if (channel)
+                ensure(channel).worker++;
+            continue;
+        }
+        if (e.event === "gate-result" && e.data.gate === "review") {
+            const channel = reviewerChannel(e.data);
+            if (channel)
+                ensure(channel).review++;
+            continue;
+        }
+        if (e.event === "review-leg2") {
+            const channel = reviewerChannel(e.data);
+            if (channel)
+                ensure(channel).review++;
+            continue;
+        }
+        if (e.event === "consult-verdict") {
+            const channel = consultChannel(e.data);
+            if (channel)
+                ensure(channel).consult++;
+        }
+    }
+    return [...counts.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([channel, role]) => ({ channel, ...role }));
+}
+/** The shared record: one row per channel journal evidence actually names (role counts), joined
+ *  with that channel's metered/priced facts. A channel `costs` prices but journal evidence never
+ *  names gets no row here — this never invents a role from cost data alone. */
+export function buildOperatorRecord(events, costs = []) {
+    const byChannel = new Map(costs.map((c) => [`${c.adapter}:${c.model}`, c]));
+    return channelRoleCounts(events).map((role) => {
+        const usage = labelChannelUsage(role.channel, byChannel.get(role.channel));
+        return { ...role, tokens: usage.tokens, money: usage.money };
+    });
+}
+export function formatOperatorRecordRow(row) {
+    return `${row.channel} — worker: ${row.worker}, review: ${row.review}, consult: ${row.consult}; tokens: ${row.tokens}; money: ${row.money}`;
+}

package/dist/run/daemon.d.ts

@@ -64,10 +64,9 @@ export interface RunSummary {
  */
 export declare function outstandingApprovals(events: JournalEvent[]): string[];
 export declare function formatSummary(s: RunSummary): string;
-/** The narrator's command, bound to THIS run. `status` takes exactly one positional and it is the
- *  run id (cli/commands/status.ts positionalRunId), so naming it here is what stops the board from
- *  following the newest journal in a repo that already carries a second, newer run — a board showing
- *  the wrong run is a recorded incident (skills/tickmarkr-overseer/SKILL.md). */
+/** The narrator enters the production Run cockpit for this exact run. The
+ *  completed static/growing four-hour records precede this default cutover;
+ *  an explicit ID prevents a newer journal from redirecting the owned board. */
 export declare const daemonEntrypoint: string;
 export declare const watchCommand: (runId: string) => string;
 /**

package/dist/run/daemon.js

@@ -134,12 +134,11 @@ export function formatSummary(s) {
         : "";
     return `done: ${s.done.length}, failed: ${s.failed.length}, human: ${s.human.length}, blocked: ${s.blocked.length}, pending: ${s.pending.length}\nintegration branch: ${s.branch}${tip}${outstanding}`;
 }
-/** The narrator's command, bound to THIS run. `status` takes exactly one positional and it is the
- *  run id (cli/commands/status.ts positionalRunId), so naming it here is what stops the board from
- *  following the newest journal in a repo that already carries a second, newer run — a board showing
- *  the wrong run is a recorded incident (skills/tickmarkr-overseer/SKILL.md). */
+/** The narrator enters the production Run cockpit for this exact run. The
+ *  completed static/growing four-hour records precede this default cutover;
+ *  an explicit ID prevents a newer journal from redirecting the owned board. */
 export const daemonEntrypoint = fileURLToPath(new URL("../cli/index.js", import.meta.url));
-export const watchCommand = (runId) => `${shq(process.execPath)} ${shq(daemonEntrypoint)} status --watch ${shq(runId)}`;
+export const watchCommand = (runId) => `${shq(process.execPath)} ${shq(daemonEntrypoint)} ui ${shq(runId)} --view run`;
 const MAX_ATTEMPTS = 10; // ponytail: hard cap so a pathological ladder can never loop forever
 // v1.85 T3 (retry economics): two repairs per engagement, then the fresh ladder. A repair re-uses the
 // findings and the landed diff instead of re-buying onboarding; when two of them have not closed the
@@ -1266,15 +1265,17 @@ export async function runDaemon(repoRoot, opts = {}) {
             // slot closed once (task-done, quota reroute, gate self-clean) can never be closed twice.
             const liveSlots = new Set();
             const closeSlot = async (s) => {
-                if (!liveSlots.delete(s))
+                if (!liveSlots.has(s))
                     return; // already closed — never twice
                 await driver.close(s);
+                liveSlots.delete(s);
             };
             const trackedDriver = {
                 id: driver.id,
                 interactive: driver.interactive,
                 ...(driver.readSource ? { readSource: driver.readSource } : {}),
                 ...(driver.describe ? { describe: driver.describe.bind(driver) } : {}),
+                ...(driver.focus ? { focus: driver.focus.bind(driver) } : {}),
                 slot: async (cwd, name, o) => { const s = await driver.slot(cwd, name, o); liveSlots.add(s); return s; },
                 run: (s, cmd) => driver.run(s, cmd),
                 waitOutput: (s, p, ms, o) => driver.waitOutput(s, p, ms, o),
@@ -1392,7 +1393,9 @@ export async function runDaemon(repoRoot, opts = {}) {
                     watchSlot = await trackedDriver.narrator(repoRoot, watchCommand(runId), runId);
                 }
                 catch (error) {
-                    journal.append("watch-placement-failed", undefined, { error: error instanceof Error ? error.message : String(error) });
+                    const reason = error instanceof Error ? error.message : String(error);
+                    journal.append("watch-placement-failed", undefined, { error: reason });
+                    console.error(`tickmarkr: narrator not opened: ${reason}`);
                 }
             };
             let baseRef;
@@ -1550,12 +1553,14 @@ export async function runDaemon(repoRoot, opts = {}) {
                     // (no run identity) is never this run's to sweep.
                     if (watchSlot && watchSlot.name === watchName && !desired.has(watchName)) {
                         const w = watchSlot;
-                        watchSlot = undefined;
                         await trackedDriver.close(w);
+                        watchSlot = undefined;
                     }
                 }
-                catch {
-                    /* cosmetic — visibility is never a gate */
+                catch (error) {
+                    const reason = error instanceof Error ? error.message : String(error);
+                    journal.append("watch-cleanup-failed", undefined, { error: reason });
+                    console.error(`tickmarkr: ${reason}`);
                 }
             };
             // run start/resume boundary: nothing in flight, so the sweep takes this run's judge/review/consult
@@ -2725,6 +2730,9 @@ export async function runDaemon(repoRoot, opts = {}) {
                         journal.append("worker-launch", t.id, {
                             attempt,
                             retryMode,
+                            driver: trackedDriver.id,
+                            slot: { ...slot },
+                            workspace: driver.id === "herdr" ? process.env.HERDR_WORKSPACE_ID : undefined,
                             ...(trackedDriver.describe ? await trackedDriver.describe(slot) : {}),
                         });
                     };

package/dist/run/lock.d.ts

@@ -36,12 +36,69 @@ export declare function runLockOwner(repoRoot: string): {
 export declare function runLockRunId(repoRoot: string): string | undefined;
 export declare function runStatusLine(repoRoot: string, runId: string, events: readonly RunLineEvent[]): string | null;
 export declare function isRunLockLive(repoRoot: string): boolean;
-export declare function unlockRun(repoRoot: string): {
+export interface LockSnapshot {
+    pid?: number;
+    runId?: string;
+    garbage: boolean;
+    unreadable: boolean;
+    dead: boolean;
+    ino: number;
+    mtimeMs: number;
+    raw: Buffer;
+}
+export type UnlockPreview = {
     held: false;
 } | {
     held: true;
+    eligible: false;
+    reason: string;
+    pid?: number;
+    runId?: string;
+} | {
+    held: true;
+    eligible: true;
+    pid: number;
+    runId: string;
+    ino: number;
+    mtimeMs: number;
+    raw: Buffer;
+};
+export declare function previewUnlock(repoRoot: string, runId: string): UnlockPreview;
+export declare function commitUnlock(repoRoot: string, target: {
+    pid: number;
+    runId: string;
+    ino: number;
+    mtimeMs: number;
+    raw: Buffer;
+}): {
     removed: true;
+    pid: number;
+    runId: string;
+} | {
+    removed: false;
+    reason: string;
+};
+export type UnlockGarbagePreview = {
+    held: false;
+} | {
+    held: true;
+    eligible: false;
+    reason: string;
     pid?: number;
     runId?: string;
-    garbage: boolean;
+} | {
+    held: true;
+    eligible: true;
+    ino: number;
+    raw: Buffer;
+};
+export declare function previewGarbageUnlock(repoRoot: string): UnlockGarbagePreview;
+export declare function commitGarbageUnlock(repoRoot: string, target: {
+    ino: number;
+    raw: Buffer;
+}): {
+    removed: true;
+} | {
+    removed: false;
+    reason: string;
 };