@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/core-utils/worktree-resume.js

@@ -0,0 +1,1198 @@
+/** Native TypeScript ports of the Wave 2 worktree and resume helpers. */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { serializeJqJson } from "./jq-json-serializer.js";
+export const WORKTREE_GC_ASSET = "core/scripts/worktree-gc.sh";
+export const CLEAN_HANDOFF_ASSET = "core/scripts/clean-worktree-reconcile-handoff.sh";
+export const RESUME_LOCK_ASSET = "core/scripts/resume-thread-lock.sh";
+export const VERIFY_DELIVERABLES_ASSET = "core/scripts/verify-story-deliverables.sh";
+const stdout = (io, value) => (io.stdout ?? ((v) => process.stdout.write(v)))(value);
+const stderr = (io, value) => (io.stderr ?? ((v) => process.stderr.write(v)))(value);
+const envOf = (io) => io.env ?? process.env;
+const nowOf = (io) => (io.now ?? (() => new Date()))();
+const stripTrailingNewlines = (value) => value.replace(/\n+$/u, "");
+function git(args, options = {}) {
+    const childEnv = options.env;
+    let priorAllow;
+    if (!childEnv && options.allowHqRoot) {
+        priorAllow = process.env.HQ_ALLOW_HQ_ROOT_GIT;
+        process.env.HQ_ALLOW_HQ_ROOT_GIT = "1";
+    }
+    try {
+        const result = spawnSync("git", [...args], {
+            cwd: options.cwd,
+            encoding: "buffer",
+            timeout: options.timeout,
+            maxBuffer: 512 * 1024 * 1024,
+            ...(childEnv ? { env: childEnv } : {}),
+        });
+        return {
+            status: result.status ?? (result.error ? 127 : 1),
+            stdout: result.stdout ?? Buffer.alloc(0),
+            stderr: result.stderr ?? Buffer.alloc(0),
+            ...(result.error ? { error: result.error } : {}),
+        };
+    }
+    finally {
+        if (!childEnv && options.allowHqRoot) {
+            if (priorAllow === undefined)
+                delete process.env.HQ_ALLOW_HQ_ROOT_GIT;
+            else
+                process.env.HQ_ALLOW_HQ_ROOT_GIT = priorAllow;
+        }
+    }
+}
+function gitText(args, options = {}) {
+    const result = git(args, options);
+    return { ...result, text: result.stdout.toString("utf8") };
+}
+function commandOutput(result) {
+    return stripTrailingNewlines(result.text);
+}
+function fileExists(file) {
+    try {
+        fs.accessSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function statMtime(file) {
+    try {
+        return Math.floor(fs.statSync(file).mtimeMs / 1000);
+    }
+    catch {
+        return 0;
+    }
+}
+export function worktreeGcPathKey(value) {
+    const bytes = Buffer.from(value, "utf8");
+    let crc = 0;
+    const add = (byte) => {
+        crc = (crc ^ (byte << 24)) >>> 0;
+        for (let bit = 0; bit < 8; bit++) {
+            crc = crc & 0x80000000 ? ((crc << 1) ^ 0x04c11db7) >>> 0 : (crc << 1) >>> 0;
+        }
+    };
+    for (const byte of bytes)
+        add(byte);
+    let length = bytes.length;
+    while (length !== 0) {
+        add(length & 0xff);
+        length = Math.floor(length / 256);
+    }
+    return ((~crc) >>> 0).toString(10);
+}
+function byteSort(values) {
+    return values.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+}
+function walkGitFiles(root, maxDepth) {
+    const found = [];
+    const visit = (directory, depth) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const candidate = path.join(directory, entry.name);
+            if (entry.name === ".git" && depth + 1 <= maxDepth && entry.isFile())
+                found.push(candidate);
+            else if (depth + 1 < maxDepth && entry.isDirectory())
+                visit(candidate, depth + 1);
+        }
+    };
+    if (fileExists(root))
+        visit(root, 0);
+    return found;
+}
+function sessionReferences(hqRoot, worktree) {
+    const roots = [
+        path.join(hqRoot, "workspace/sessions"),
+        path.join(hqRoot, ".claude/state"),
+        path.join(hqRoot, "workspace/threads/handoff.json"),
+        path.join(hqRoot, "workspace/locks"),
+    ];
+    const needle = Buffer.from(worktree, "utf8");
+    const visit = (target) => {
+        let info;
+        try {
+            info = fs.lstatSync(target);
+        }
+        catch {
+            return false;
+        }
+        if (info.isSymbolicLink())
+            return false;
+        if (info.isDirectory()) {
+            let names;
+            try {
+                names = fs.readdirSync(target);
+            }
+            catch {
+                return false;
+            }
+            for (const name of names)
+                if (visit(path.join(target, name)))
+                    return true;
+            return false;
+        }
+        if (!info.isFile())
+            return false;
+        try {
+            return fs.readFileSync(target).includes(needle);
+        }
+        catch {
+            return false;
+        }
+    };
+    return roots.some(visit);
+}
+function executableOnPath(name, env) {
+    const pathValue = env.PATH ?? "";
+    for (const directory of pathValue.split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, name);
+        try {
+            fs.accessSync(candidate, process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
+            if (!fs.statSync(candidate).isDirectory())
+                return true;
+        }
+        catch { /* command -v continues through PATH */ }
+    }
+    return false;
+}
+function duSizeKb(root) {
+    let bytes = 0;
+    const seen = new Set();
+    const visit = (target) => {
+        let info;
+        try {
+            info = fs.lstatSync(target);
+        }
+        catch {
+            return;
+        }
+        if (info.isSymbolicLink())
+            return;
+        const inode = `${info.dev}:${info.ino}`;
+        if (info.isFile() && seen.has(inode))
+            return;
+        if (info.isFile())
+            seen.add(inode);
+        bytes += typeof info.blocks === "number" ? info.blocks * 512 : info.size;
+        if (info.isDirectory()) {
+            let children;
+            try {
+                children = fs.readdirSync(target);
+            }
+            catch {
+                return;
+            }
+            for (const child of children)
+                visit(path.join(target, child));
+        }
+    };
+    visit(root);
+    return Math.ceil(bytes / 1024);
+}
+const WORKTREE_GC_HELP = `hq-core: public
+worktree-gc.sh — safe garbage collector for stale HQ git worktrees.
+
+HQ worktrees accumulate forever. Nothing GCs them, and a busy machine can
+reach hundreds of worktrees / hundreds of GB. This script enumerates the
+linked worktrees HQ creates under:
+  <hqRoot>/workspace/worktrees/                (flat <name>/ and nested <repo>/<name>/)
+  <hqRoot>/.claude/worktrees/                  (agent-* local-only worktrees)
+and removes ONLY the ones that are provably safe to lose.
+
+DATA SAFETY IS PARAMOUNT. A worktree is removed only when EVERY guard holds:
+  1. Working tree is clean            — \`git status --porcelain\` is empty.
+  2. Old enough                       — creation stamp (or dir mtime) is older
+                                        than the retention window (default 7d).
+  3. Branch work is preserved         — for a pushable (github) repo the tip is
+                                        reachable from origin (or the branch is
+                                        on origin at the same tip); for an
+                                        HQ-root local-only worktree the branch
+                                        is already merged into the HQ root's
+                                        local \`main\`. Fetch is best-effort; a
+                                        failed fetch makes the worktree UNSAFE.
+  4. Not in use                       — no active session references its path,
+                                        and it was not touched in the last 2h.
+
+Removal mechanics are the gentle git verbs only — never \`rm -rf\`, never
+\`--force\`, never \`branch -D\`:
+  git -C <main-repo> worktree remove <abs>   (HQ_ALLOW_HQ_ROOT_GIT=1 for HQ root)
+  git -C <main-repo> worktree prune
+  git -C <main-repo> branch -d <branch>
+
+DRY-RUN IS THE DEFAULT. Nothing is removed unless \`--apply\` is passed. A single
+worktree error is logged and skipped — it never aborts the run.
+
+Usage:
+  worktree-gc.sh [--days N] [--apply] [--dry-run] [--gated] [--json]
+
+Flags:
+  --days N     retention window in days (default 7; env HQ_WORKTREE_GC_DAYS)
+  --apply      actually remove safe worktrees (default: dry-run, no changes)
+  --dry-run    classify only, make no changes (the default; explicit for clarity)
+  --gated      no-op if a GC run already happened in the last 24h (for cadence
+               callers like handoff-post.sh); writes a marker on each real run
+  --json       emit a machine-readable summary + per-worktree records on stdout
+
+`;
+export function runWorktreeGc(args, hqRoot, io = {}) {
+    const env = envOf(io);
+    let days = env.HQ_WORKTREE_GC_DAYS ?? "7";
+    let apply = false;
+    let json = false;
+    let gated = false;
+    for (let i = 0; i < args.length;) {
+        const arg = args[i] ?? "";
+        if (arg === "--days") {
+            days = args[i + 1] ?? "";
+            if (i + 1 >= args.length)
+                return 1;
+            i += 2;
+        }
+        else if (arg.startsWith("--days=")) {
+            days = arg.slice(7);
+            i++;
+        }
+        else if (arg === "--apply") {
+            apply = true;
+            i++;
+        }
+        else if (arg === "--dry-run") {
+            apply = false;
+            i++;
+        }
+        else if (arg === "--gated") {
+            gated = true;
+            i++;
+        }
+        else if (arg === "--json") {
+            json = true;
+            i++;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            stdout(io, WORKTREE_GC_HELP);
+            return 0;
+        }
+        else {
+            stderr(io, `worktree-gc: unknown arg: ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!/^\d+$/u.test(days)) {
+        stderr(io, `worktree-gc: --days must be a non-negative integer (got: ${days})\n`);
+        return 2;
+    }
+    const now = Math.floor(nowOf(io).getTime() / 1000);
+    const dayCount = Number(days);
+    const cutoffEpoch = now - dayCount * 86400;
+    const recentEpoch = now - 2 * 60 * 60;
+    const metaDir = path.join(hqRoot, "workspace/worktrees/.gc-meta");
+    const gateMarker = path.join(metaDir, ".last-gc-run");
+    if (gated) {
+        if (fileExists(gateMarker) && now - statMtime(gateMarker) < 86400) {
+            stdout(io, json
+                ? '{"skipped":"gated","reason":"ran within 24h"}\n'
+                : "worktree-gc: skipped (gated — ran within 24h)\n");
+            return 0;
+        }
+        try {
+            fs.mkdirSync(metaDir, { recursive: true });
+        }
+        catch { /* shell uses mkdir ... || true */ }
+        try {
+            const fd = fs.openSync(gateMarker, "a");
+            fs.closeSync(fd);
+            const date = nowOf(io);
+            fs.utimesSync(gateMarker, date, date);
+        }
+        catch { /* shell uses touch ... || true */ }
+    }
+    const candidates = byteSort([
+        ...walkGitFiles(path.join(hqRoot, "workspace/worktrees"), 4),
+        ...walkGitFiles(path.join(hqRoot, ".claude/worktrees"), 3),
+    ].map((file) => {
+        try {
+            return fs.realpathSync(path.dirname(file));
+        }
+        catch {
+            return path.resolve(path.dirname(file));
+        }
+    }).filter((value, index, all) => all.indexOf(value) === index));
+    const selfDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+    const records = [];
+    let examined = 0, removed = 0, would = 0, reclaimedKb = 0, skipped = 0;
+    const record = (values) => { records.push(values); };
+    const skip = (wt, repo, branch, isHqRoot, ageDays, sizeKb, reason) => {
+        skipped++;
+        if (reason === "remove-failed")
+            record({ path: wt, repo, branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "skipped", reason });
+        if (!json)
+            stdout(io, `  skip  [${reason}] ${wt}\n`);
+    };
+    const runFetch = (repo) => {
+        const timeoutName = executableOnPath("timeout", env) ? "timeout" : executableOnPath("gtimeout", env) ? "gtimeout" : undefined;
+        const timeoutSeconds = timeoutName ? 45_000 : undefined;
+        // The timeout utility itself is intentionally not spawned. spawnSync applies the
+        // same 45 second ceiling directly around the permitted git child.
+        return git(["-C", repo, "fetch", "origin", "--quiet"], { timeout: timeoutSeconds }).status === 0;
+    };
+    const isAncestor = (repo, ancestor, descendant) => git(["-C", repo, "merge-base", "--is-ancestor", ancestor, descendant]).status === 0;
+    const wtGit = (repo, isHqRoot, gitArgs) => git(["-C", repo, ...gitArgs], { allowHqRoot: isHqRoot });
+    for (const wt of candidates) {
+        examined++;
+        if (selfDir === wt || selfDir.startsWith(`${wt}${path.sep}`)) {
+            skip(wt, "", "", false, null, null, "self");
+            continue;
+        }
+        const common = gitText(["-C", wt, "rev-parse", "--path-format=absolute", "--git-common-dir"]);
+        const commonDir = common.status === 0 ? commandOutput(common) : "";
+        if (!commonDir) {
+            skip(wt, "", "", false, null, null, "git-error");
+            continue;
+        }
+        let mainRepo = "";
+        try {
+            mainRepo = fs.realpathSync(path.dirname(commonDir));
+        }
+        catch { /* pwd -P fallback is empty on failure */ }
+        if (!mainRepo || !fileExists(mainRepo)) {
+            skip(wt, "", "", false, null, null, "git-error");
+            continue;
+        }
+        let isHqRoot = false;
+        try {
+            isHqRoot = fs.realpathSync(mainRepo) === fs.realpathSync(hqRoot);
+        }
+        catch { /* both paths are already resolved by the core root resolver */ }
+        const branchResult = gitText(["-C", wt, "symbolic-ref", "--short", "HEAD"]);
+        const branch = branchResult.status === 0 ? commandOutput(branchResult) : "";
+        const headResult = gitText(["-C", wt, "rev-parse", "HEAD"]);
+        const head = headResult.status === 0 ? commandOutput(headResult) : "";
+        const statusResult = gitText(["-C", wt, "status", "--porcelain"]);
+        const porcelain = statusResult.status === 0 ? stripTrailingNewlines(statusResult.text) : "__ERR__";
+        if (porcelain === "__ERR__") {
+            skip(wt, mainRepo, branch, isHqRoot, null, null, "git-error");
+            continue;
+        }
+        if (porcelain !== "") {
+            skip(wt, mainRepo, branch, isHqRoot, null, null, "dirty");
+            continue;
+        }
+        const wtMtime = statMtime(wt);
+        if (wtMtime > recentEpoch) {
+            skip(wt, mainRepo, branch, isHqRoot, null, null, "recent-activity");
+            continue;
+        }
+        if (sessionReferences(hqRoot, wt)) {
+            skip(wt, mainRepo, branch, isHqRoot, null, null, "active-session");
+            continue;
+        }
+        let createdEpoch = wtMtime;
+        const stampFile = path.join(metaDir, `${worktreeGcPathKey(wt)}.json`);
+        if (fileExists(stampFile)) {
+            try {
+                const stamp = JSON.parse(fs.readFileSync(stampFile, "utf8"));
+                const stamped = stamp?.createdAtEpoch;
+                if (stamped !== undefined && stamped !== null && stamped !== "") {
+                    const numeric = Number(stamped);
+                    if (Number.isFinite(numeric))
+                        createdEpoch = numeric;
+                }
+            }
+            catch { /* jq read errors are silenced */ }
+        }
+        const ageDays = Math.trunc((now - createdEpoch) / 86400);
+        if (createdEpoch > cutoffEpoch) {
+            skip(wt, mainRepo, branch, isHqRoot, ageDays, null, "too-recent");
+            continue;
+        }
+        let preserved = false;
+        if (isHqRoot) {
+            if (head && isAncestor(hqRoot, head, "main"))
+                preserved = true;
+            if (!preserved) {
+                skip(wt, mainRepo, branch, isHqRoot, ageDays, null, "unmerged-local");
+                continue;
+            }
+        }
+        else {
+            const originResult = gitText(["-C", mainRepo, "remote", "get-url", "origin"]);
+            const origin = originResult.status === 0 ? commandOutput(originResult) : "";
+            if (!origin.includes("github")) {
+                skip(wt, mainRepo, branch, isHqRoot, ageDays, null, "non-github-remote");
+                continue;
+            }
+            if (!runFetch(mainRepo)) {
+                skip(wt, mainRepo, branch, isHqRoot, ageDays, null, "fetch-failed");
+                continue;
+            }
+            for (const ref of ["origin/HEAD", "origin/main", "origin/master"]) {
+                if (git(["-C", mainRepo, "rev-parse", "--verify", "--quiet", ref]).status === 0 && head && isAncestor(mainRepo, head, ref)) {
+                    preserved = true;
+                    break;
+                }
+            }
+            if (!preserved && branch && head) {
+                let remote = gitText(["-C", mainRepo, "rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`]);
+                let remoteSha = remote.status === 0 ? commandOutput(remote) : "";
+                if (!remoteSha) {
+                    remote = gitText(["-C", mainRepo, "ls-remote", "--heads", "origin", branch]);
+                    if (remote.status === 0)
+                        remoteSha = (remote.text.split(/\r?\n/u).find(Boolean) ?? "").split(/\s+/u)[0] ?? "";
+                }
+                if (remoteSha && remoteSha === head)
+                    preserved = true;
+            }
+            if (!preserved) {
+                skip(wt, mainRepo, branch, isHqRoot, ageDays, null, "unpushed");
+                continue;
+            }
+        }
+        const sizeKb = duSizeKb(wt);
+        if (!apply) {
+            would++;
+            reclaimedKb += sizeKb;
+            record({ path: wt, repo: mainRepo, branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "would-remove", reason: "safe" });
+            if (!json)
+                stdout(io, `  DRY   would remove (${Math.floor(sizeKb / 1024)} MB, ${ageDays}d) ${wt}\n`);
+            continue;
+        }
+        if (wtGit(mainRepo, isHqRoot, ["worktree", "remove", wt]).status !== 0) {
+            skip(wt, mainRepo, branch, isHqRoot, ageDays, sizeKb, "remove-failed");
+            continue;
+        }
+        wtGit(mainRepo, isHqRoot, ["worktree", "prune"]);
+        if (branch)
+            wtGit(mainRepo, isHqRoot, ["branch", "-d", branch]);
+        try {
+            fs.unlinkSync(stampFile);
+        }
+        catch { /* rm -f */ }
+        removed++;
+        reclaimedKb += sizeKb;
+        record({ path: wt, repo: mainRepo, branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "removed", reason: "safe" });
+        if (!json)
+            stdout(io, `  GC    removed (${Math.floor(sizeKb / 1024)} MB, ${ageDays}d) ${wt}\n`);
+    }
+    const reclaimedGb = Number((reclaimedKb / 1024 / 1024).toFixed(2));
+    if (json) {
+        const skippedByReason = {};
+        for (const reason of records.filter((item) => item.action === "skipped").map((item) => item.reason).sort()) {
+            skippedByReason[reason] = (skippedByReason[reason] ?? 0) + 1;
+        }
+        const serialized = serializeJqJson({
+            mode: apply ? "apply" : "dry-run",
+            retention_days: dayCount,
+            examined,
+            removed,
+            reclaimed_gb: reclaimedGb,
+            reclaimed_kb: reclaimedKb,
+            skipped_by_reason: skippedByReason,
+            records,
+        }, "pretty").replace(/("reclaimed_gb": )(-?\d+(?:\.\d+)?)/u, `$1${(reclaimedKb / 1024 / 1024).toFixed(2)}`);
+        stdout(io, serialized);
+    }
+    else if (apply) {
+        stdout(io, `worktree-gc [apply]: examined ${examined} · removed ${removed} · reclaimed ${reclaimedGb.toFixed(2)} GB · skipped ${skipped} (retention ${days}d)\n`);
+    }
+    else {
+        stdout(io, `worktree-gc [dry-run]: examined ${examined} · would remove ${would} · would reclaim ${reclaimedGb.toFixed(2)} GB · skipped ${skipped} (retention ${days}d)\n`);
+    }
+    return 0;
+}
+const CLEAN_HANDOFF_USAGE = "Usage: clean-worktree-reconcile-handoff.sh <absolute-hq-root> <local-branch>\n";
+function cleanUsage(io) { stderr(io, CLEAN_HANDOFF_USAGE); }
+function cleanGitError(io, message) { stderr(io, `${message}\n`); return 1; }
+function realPathOrResolved(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function gitShowFile(root, branchRef, relativePath) {
+    return git(["-C", root, "show", `${branchRef}:${relativePath}`]);
+}
+function pathType(target) {
+    try {
+        const info = fs.lstatSync(target);
+        return info.isFile() && !info.isSymbolicLink() ? "regular" : "other";
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "missing" : "other";
+    }
+}
+function compareBranchFile(root, branchRef, relativePath, localFile) {
+    const incoming = gitShowFile(root, branchRef, relativePath);
+    if (incoming.status !== 0)
+        return 2;
+    try {
+        return fs.readFileSync(localFile).equals(incoming.stdout) ? 0 : 1;
+    }
+    catch {
+        return 2;
+    }
+}
+export function runCleanWorktreeReconcileHandoff(args, io = {}) {
+    if (args.length !== 2) {
+        cleanUsage(io);
+        return 64;
+    }
+    const rawRoot = args[0] ?? "";
+    const branch = args[1] ?? "";
+    if (!rawRoot.startsWith("/")) {
+        stderr(io, `ERROR: HQ root must be an absolute path\n`);
+        cleanUsage(io);
+        return 64;
+    }
+    if (!fileExists(rawRoot) || !fs.statSync(rawRoot).isDirectory()) {
+        return cleanGitError(io, `ERROR: HQ root is not a directory: ${rawRoot}`);
+    }
+    const hqRoot = realPathOrResolved(rawRoot);
+    const top = gitText(["-C", hqRoot, "rev-parse", "--show-toplevel"]);
+    if (top.status !== 0)
+        return cleanGitError(io, `ERROR: HQ root is not a Git worktree: ${hqRoot}`);
+    const topLevel = realPathOrResolved(commandOutput(top));
+    if (topLevel !== hqRoot)
+        return cleanGitError(io, `ERROR: supplied path is not the Git worktree root: ${hqRoot}`);
+    const branchRef = `refs/heads/${branch}`;
+    if (git(["-C", hqRoot, "show-ref", "--verify", "--quiet", branchRef]).status !== 0) {
+        return cleanGitError(io, `ERROR: incoming branch does not exist locally: ${branch}`);
+    }
+    const pointerPath = "workspace/threads/handoff.json";
+    if (git(["-C", hqRoot, "cat-file", "-e", `${branchRef}:${pointerPath}`]).status !== 0) {
+        stdout(io, `No incoming handoff pointer on ${branch}; no mirror paths to reconcile.\n`);
+        return 0;
+    }
+    const pointer = gitShowFile(hqRoot, branchRef, pointerPath);
+    let threadPath;
+    try {
+        const parsed = JSON.parse(pointer.stdout.toString("utf8"));
+        threadPath = parsed?.thread_path;
+    }
+    catch {
+        threadPath = undefined;
+    }
+    if (pointer.status !== 0 || typeof threadPath !== "string") {
+        return cleanGitError(io, "ERROR: incoming branch handoff pointer has no string thread_path");
+    }
+    if (!threadPath.startsWith("workspace/threads/")) {
+        return cleanGitError(io, `ERROR: unsafe incoming handoff thread_path: ${threadPath}`);
+    }
+    if (threadPath.includes("//") || threadPath.includes("/./") || threadPath.includes("/../") || threadPath === pointerPath || /[\n\r]/u.test(threadPath)) {
+        return cleanGitError(io, `ERROR: unsafe incoming handoff thread_path: ${threadPath}`);
+    }
+    if (git(["-C", hqRoot, "cat-file", "-e", `${branchRef}:${threadPath}`]).status !== 0) {
+        return cleanGitError(io, `ERROR: incoming handoff thread is missing from ${branch}: ${threadPath}`);
+    }
+    const mirrors = [pointerPath, threadPath];
+    const identical = [];
+    const differing = [];
+    for (const relativePath of mirrors) {
+        const absolute = path.join(hqRoot, relativePath);
+        const type = pathType(absolute);
+        if (type === "missing")
+            continue;
+        if (type !== "regular") {
+            differing.push(`${relativePath} (not a regular file)`);
+            continue;
+        }
+        const status = compareBranchFile(hqRoot, branchRef, relativePath, absolute);
+        if (status === 0)
+            identical.push(relativePath);
+        else if (status === 1)
+            differing.push(`${relativePath} (content differs from ${branch})`);
+        else
+            return cleanGitError(io, `ERROR: could not compare incoming ${relativePath} with ${absolute}`);
+    }
+    if (differing.length > 0) {
+        for (const relativePath of differing)
+            stderr(io, `BLOCK: preserved main-checkout handoff path: ${relativePath}\n`);
+        stderr(io, `No mirror paths were removed; surface these local files before merging.\n`);
+        return 2;
+    }
+    let reconciliationBlocked = false;
+    for (const relativePath of identical) {
+        const absolute = path.join(hqRoot, relativePath);
+        const type = pathType(absolute);
+        if (type === "missing")
+            continue;
+        if (type !== "regular") {
+            stderr(io, `BLOCK: preserved changed main-checkout path: ${relativePath}\n`);
+            reconciliationBlocked = true;
+            continue;
+        }
+        const destinationDir = path.dirname(absolute);
+        let movedFile = "";
+        try {
+            for (let attempt = 0; attempt < 10; attempt++) {
+                const candidate = path.join(destinationDir, `.clean-worktree-handoff.${randomBytes(4).toString("hex").slice(0, 6)}`);
+                try {
+                    fs.writeFileSync(candidate, "", { flag: "wx", mode: 0o600 });
+                    movedFile = candidate;
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                }
+            }
+            if (!movedFile)
+                throw new Error("could not allocate a temporary handoff filename");
+        }
+        catch {
+            return cleanGitError(io, `ERROR: could not safely move mirrored handoff path: ${relativePath}`);
+        }
+        try {
+            fs.renameSync(absolute, movedFile);
+        }
+        catch {
+            try {
+                fs.unlinkSync(movedFile);
+            }
+            catch { /* rm -f */ }
+            return cleanGitError(io, `ERROR: could not safely move mirrored handoff path: ${relativePath}`);
+        }
+        const comparison = pathType(movedFile) === "regular"
+            ? compareBranchFile(hqRoot, branchRef, relativePath, movedFile)
+            : 1;
+        if (comparison === 0) {
+            if (pathType(absolute) !== "missing") {
+                try {
+                    fs.unlinkSync(movedFile);
+                }
+                catch { /* rm -f */ }
+                stderr(io, `BLOCK: a new main-checkout file appeared during reconciliation; preserved it: ${relativePath}\n`);
+                reconciliationBlocked = true;
+            }
+            else {
+                try {
+                    fs.unlinkSync(movedFile);
+                }
+                catch { /* rm */ }
+                stdout(io, `Reconciled byte-identical handoff mirror: ${relativePath}\n`);
+            }
+        }
+        else {
+            if (pathType(absolute) === "missing") {
+                try {
+                    fs.renameSync(movedFile, absolute);
+                    stderr(io, `BLOCK: handoff path changed during reconciliation; restored it untouched: ${relativePath}\n`);
+                }
+                catch {
+                    stderr(io, `BLOCK: handoff path changed during reconciliation; preserved it at ${movedFile}\n`);
+                }
+            }
+            else {
+                stderr(io, `BLOCK: handoff path changed during reconciliation; preserved captured file at ${movedFile} and current path ${absolute}\n`);
+            }
+            if (comparison === 2)
+                return cleanGitError(io, `ERROR: could not compare incoming ${relativePath} with its moved file`);
+            reconciliationBlocked = true;
+        }
+    }
+    if (reconciliationBlocked) {
+        stderr(io, `No merge should be attempted until the changed handoff paths are surfaced.\n`);
+        return 2;
+    }
+    return 0;
+}
+const RESUME_LOCK_USAGE = `usage:
+  resume-thread-lock.sh inspect <thread-id>
+  resume-thread-lock.sh acquire <thread-id> --session-id <session-id>
+  resume-thread-lock.sh acquire <thread-id> --replace --expected-generation <generation> --session-id <session-id>
+`;
+function lockState(threadId, relativeLockPath, lockDir, recordPath, staleSeconds, now) {
+    const unlocked = () => ({ status: "unlocked", thread_id: threadId, lock_path: relativeLockPath });
+    const stale = (reason, sessionId, resumedAt, generation) => ({
+        status: "stale", thread_id: threadId, lock_path: relativeLockPath, stale_reason: reason,
+        session_id: sessionId, resumed_at: resumedAt, lock_generation: generation,
+        prompt: `This thread was already resumed by ${sessionId} at ${resumedAt}. Its lock is stale (${reason}). Re-resume anyway?`,
+    });
+    const locked = (sessionId, resumedAt, generation) => ({
+        status: "locked", thread_id: threadId, lock_path: relativeLockPath,
+        session_id: sessionId, resumed_at: resumedAt, lock_generation: generation,
+        prompt: `This thread was already resumed by ${sessionId} at ${resumedAt}. Re-resume anyway?`,
+    });
+    let lockStat;
+    try {
+        lockStat = fs.statSync(lockDir);
+    }
+    catch { /* absent/unreadable path */ }
+    if (!lockStat?.isDirectory())
+        return fileExists(lockDir) ? stale("invalid-lock-path", "unknown session", "unknown time", "") : unlocked();
+    let recordStat;
+    try {
+        recordStat = fs.statSync(recordPath);
+    }
+    catch { /* absent/unreadable path */ }
+    if (!recordStat?.isFile())
+        return stale("missing-record", "unknown session", "unknown time", "");
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(recordPath, "utf8"));
+    }
+    catch (error) {
+        return error.code === "ENOENT"
+            ? stale("missing-record", "unknown session", "unknown time", "")
+            : stale("invalid-record", "unknown session", "unknown time", "");
+    }
+    const value = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    if (!(value.version === 1 && typeof value.thread_id === "string" && value.thread_id.length > 0 &&
+        typeof value.session_id === "string" && value.session_id.length > 0 &&
+        typeof value.resumed_at === "string" && value.resumed_at.length > 0 &&
+        typeof value.resumed_epoch === "number" && Number.isFinite(value.resumed_epoch) &&
+        typeof value.generation === "string" && value.generation.length > 0)) {
+        return stale("invalid-record", "unknown session", "unknown time", "");
+    }
+    const record = value;
+    if (record.thread_id !== threadId || !/^\d+$/u.test(String(record.resumed_epoch))) {
+        return stale("invalid-record", record.session_id, record.resumed_at, record.generation);
+    }
+    const currentEpoch = Math.floor(now.getTime() / 1000);
+    if (currentEpoch - record.resumed_epoch > staleSeconds) {
+        return stale("expired", record.session_id, record.resumed_at, record.generation);
+    }
+    return locked(record.session_id, record.resumed_at, record.generation);
+}
+function writeLockRecord(lockDir, recordPath, threadId, sessionId, now) {
+    const epoch = Math.floor(now.getTime() / 1000);
+    const timestamp = now.toISOString().replace(/\.\d{3}Z$/u, "Z");
+    let temporary = "";
+    for (let attempt = 0; attempt < 10; attempt++) {
+        const generation = `.current.${randomBytes(8).toString("base64url").slice(0, 6)}`;
+        const candidate = path.join(lockDir, generation);
+        try {
+            fs.writeFileSync(candidate, serializeJqJson({ version: 1, thread_id: threadId, session_id: sessionId, resumed_at: timestamp, resumed_epoch: epoch, generation }, "compact"), { flag: "wx", mode: 0o600 });
+            temporary = candidate;
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    if (!temporary)
+        throw new Error("could not allocate a lock record filename");
+    const generation = path.basename(temporary);
+    fs.renameSync(temporary, recordPath);
+    return generation;
+}
+export function runResumeThreadLock(args, hqRoot, io = {}) {
+    const env = envOf(io);
+    const staleSecondsText = env.HQ_RESUME_LOCK_STALE_SECONDS ?? "86400";
+    const replaceClaimStaleText = env.HQ_RESUME_REPLACE_CLAIM_STALE_SECONDS ?? "60";
+    const failUsage = (message) => { stderr(io, `resume-thread-lock: ${message}\n${RESUME_LOCK_USAGE}`); return 2; };
+    const emit = (state) => stdout(io, serializeJqJson(state, "compact"));
+    if (!/^\d+$/u.test(staleSecondsText))
+        return failUsage("HQ_RESUME_LOCK_STALE_SECONDS must be a non-negative integer");
+    if (!/^\d+$/u.test(replaceClaimStaleText))
+        return failUsage("HQ_RESUME_REPLACE_CLAIM_STALE_SECONDS must be a non-negative integer");
+    const staleSeconds = Number(staleSecondsText);
+    const replaceClaimStaleSeconds = Number(replaceClaimStaleText);
+    const rest = [...args];
+    const subcommand = rest.shift() ?? "";
+    const threadId = rest.shift() ?? "";
+    if (!/^T-[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(threadId))
+        return failUsage("thread id must be a canonical T-* id");
+    let replace = false, sessionId = "", expectedGeneration = "", expectedGenerationSet = false;
+    while (rest.length > 0) {
+        const arg = rest.shift() ?? "";
+        if (arg === "--replace")
+            replace = true;
+        else if (arg === "--session-id") {
+            if (rest.length === 0)
+                return failUsage("--session-id requires a value");
+            sessionId = rest.shift() ?? "";
+        }
+        else if (arg === "--expected-generation") {
+            if (rest.length === 0)
+                return failUsage("--expected-generation requires a value");
+            expectedGeneration = rest.shift() ?? "";
+            expectedGenerationSet = true;
+        }
+        else
+            return failUsage(`unknown argument: ${arg}`);
+    }
+    if (subcommand === "inspect") {
+        if (replace || sessionId.length > 0)
+            return failUsage("inspect takes only a thread id");
+    }
+    else if (subcommand === "acquire") {
+        if (!sessionId)
+            return failUsage("acquire requires --session-id");
+        if (replace) {
+            if (!expectedGenerationSet)
+                return failUsage("--replace requires --expected-generation from the inspected lock");
+        }
+        else if (expectedGenerationSet)
+            return failUsage("--expected-generation is only valid with --replace");
+    }
+    else
+        return failUsage("expected inspect or acquire");
+    const threadsDir = path.join(hqRoot, "workspace/threads");
+    const locksDir = path.join(threadsDir, "resume-locks");
+    const lockDir = path.join(locksDir, `${threadId}.lock`);
+    const recordPath = path.join(lockDir, "current.json");
+    const claimDir = path.join(lockDir, ".replace-claim");
+    const relativeLockPath = `workspace/threads/resume-locks/${threadId}.lock`;
+    const now = () => nowOf(io);
+    if (subcommand === "inspect") {
+        emit(lockState(threadId, relativeLockPath, lockDir, recordPath, staleSeconds, now()));
+        return 0;
+    }
+    fs.mkdirSync(locksDir, { recursive: true });
+    try {
+        fs.mkdirSync(lockDir);
+        const generation = writeLockRecord(lockDir, recordPath, threadId, sessionId, now());
+        emit({ status: "acquired", thread_id: threadId, lock_path: relativeLockPath, session_id: sessionId, lock_generation: generation });
+        return 0;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    if (!replace) {
+        emit(lockState(threadId, relativeLockPath, lockDir, recordPath, staleSeconds, now()));
+        return 3;
+    }
+    let lockInfo;
+    try {
+        lockInfo = fs.statSync(lockDir);
+    }
+    catch { /* not a directory */ }
+    if (!lockInfo?.isDirectory()) {
+        stderr(io, `resume-thread-lock: cannot refresh non-directory lock path: ${relativeLockPath}\n`);
+        return 1;
+    }
+    const claimIsStale = () => Math.floor(now().getTime() / 1000) - statMtime(claimDir) > replaceClaimStaleSeconds;
+    let acquiredClaim = false;
+    try {
+        fs.mkdirSync(claimDir);
+        acquiredClaim = true;
+    }
+    catch { /* existing claim */ }
+    if (!acquiredClaim) {
+        let claimStat;
+        try {
+            claimStat = fs.statSync(claimDir);
+        }
+        catch { /* absent or invalid */ }
+        if (claimStat?.isDirectory() && claimIsStale()) {
+            try {
+                fs.rmdirSync(claimDir);
+            }
+            catch { /* rmdir refuses a claim with payloads */ }
+            try {
+                fs.mkdirSync(claimDir);
+                acquiredClaim = true;
+            }
+            catch { /* another process acquired it */ }
+        }
+    }
+    if (!acquiredClaim) {
+        emit(lockState(threadId, relativeLockPath, lockDir, recordPath, staleSeconds, now()));
+        return 4;
+    }
+    try {
+        const current = lockState(threadId, relativeLockPath, lockDir, recordPath, staleSeconds, now());
+        const currentGeneration = typeof current.lock_generation === "string" ? current.lock_generation : "";
+        if (currentGeneration !== expectedGeneration) {
+            emit(current);
+            return 4;
+        }
+        const generation = writeLockRecord(lockDir, recordPath, threadId, sessionId, now());
+        emit({ status: "acquired", thread_id: threadId, lock_path: relativeLockPath, session_id: sessionId, lock_generation: generation });
+        return 0;
+    }
+    finally {
+        try {
+            fs.rmdirSync(claimDir);
+        }
+        catch { /* shell trap only removes an empty directory */ }
+    }
+}
+const VERIFY_DELIVERABLES_HELP = "# hq-core: public\n# verify-story-deliverables.sh — make `passes: true` checkable: verify the\n# evidence a story worker returns, and any deliverables the PRD declared\n# (2026-09-07).\n#\n# Why: a PRD \"passes\" flag recorded that a step RAN, not that work EXISTS. An\n# audit found a project marked 16/17 complete whose named deliverables mostly\n# did not exist anywhere. Nothing anywhere checked disk or git.\n#\n# Two inputs, both optional, deliberately NOT strict by default:\n#   * EVIDENCE — what the worker says it produced, returned at completion in\n#     the run-project / execute-task return contract (`evidence: [...]`, plus\n#     `commits: [...]` which are checked as `commit:` evidence). This is the\n#     primary signal: it is written at the moment of completion, so it is\n#     accurate to what was built, and --write records it on the story as an\n#     audit trail. A claimed-but-missing item FAILS (a fabricated claim is\n#     worse than no claim). No evidence at all is allowed (legacy workers).\n#   * DELIVERABLES — what the PRD declared up front (optional). Checked when\n#     present; a planned-but-missing item fails, because that is exactly the\n#     \"16/17 complete, nothing on disk\" case.\n#\n# Usage:\n#   verify-story-deliverables.sh --prd <prd.json> --story <id> [--repo <path>]\n#       [--evidence-json '<array>'] [--commits-json '<array>'] [--write] [--json] [--strict]\n#\n# Reference forms (evidence and deliverables share them):\n#   \"deliverables\": [\n#     \"path:core/scripts/foo.sh\",            # file or dir, relative to HQ root\n#     \"repo-path:src/lib/bar.ts\",            # relative to --repo (or metadata.repoPath)\n";
+function jqText(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object")
+        return serializeJqJson(value, "compact").replace(/\n$/u, "");
+    return String(value);
+}
+function jsonDecode(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function jqArrayCheck(value) { return Array.isArray(value); }
+function isReadable(file) {
+    try {
+        fs.accessSync(file, fs.constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function joinShellPath(root, value) {
+    return value.startsWith("/") ? value : `${root}/${value}`;
+}
+async function urlIsPresent(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    try {
+        let current;
+        try {
+            current = new URL(url);
+        }
+        catch {
+            return false;
+        }
+        for (let redirects = 0; redirects <= 50; redirects++) {
+            const response = await fetch(current, { method: "GET", redirect: "manual", signal: controller.signal });
+            await drainResponseBody(response);
+            if (response.status >= 200 && response.status < 300)
+                return true;
+            if (response.status < 300 || response.status >= 400)
+                return false;
+            const location = response.headers.get("location");
+            if (!location)
+                return true;
+            try {
+                current = new URL(location, current);
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function drainResponseBody(response) {
+    if (!response.body)
+        return;
+    const reader = response.body.getReader();
+    try {
+        while (!(await reader.read()).done) { /* curl -o /dev/null consumes the full transfer */ }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
+    const env = envOf(io);
+    let prdPath = "", storyId = "", repo = "";
+    let json = false, strict = false, write = false;
+    let evidenceJson = "[]", commitsJson = "[]";
+    let offline = env.HQ_DELIVERABLES_OFFLINE ?? "0";
+    for (let index = 0; index < args.length;) {
+        const arg = args[index] ?? "";
+        if (["--prd", "--story", "--repo", "--evidence-json", "--commits-json"].includes(arg)) {
+            if (index + 1 >= args.length)
+                return 1;
+            const value = args[index + 1] ?? "";
+            if (arg === "--prd")
+                prdPath = value;
+            else if (arg === "--story")
+                storyId = value;
+            else if (arg === "--repo")
+                repo = value;
+            else if (arg === "--evidence-json")
+                evidenceJson = value;
+            else
+                commitsJson = value;
+            index += 2;
+        }
+        else if (arg === "--write") {
+            write = true;
+            index++;
+        }
+        else if (arg === "--json") {
+            json = true;
+            index++;
+        }
+        else if (arg === "--strict") {
+            strict = true;
+            index++;
+        }
+        else if (arg === "--offline") {
+            offline = "1";
+            index++;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            stdout(io, VERIFY_DELIVERABLES_HELP);
+            return 0;
+        }
+        else {
+            stderr(io, `verify-story-deliverables: unknown arg ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!prdPath || !storyId) {
+        stderr(io, `usage: --prd <prd.json> --story <id> [--repo <path>]\n`);
+        return 2;
+    }
+    const prdFilePath = path.resolve(hqRoot, prdPath);
+    if (!isReadable(prdFilePath)) {
+        stderr(io, `verify-story-deliverables: cannot read ${prdPath}\n`);
+        return 2;
+    }
+    let prd;
+    try {
+        prd = JSON.parse(fs.readFileSync(prdFilePath, "utf8"));
+    }
+    catch {
+        prd = {};
+    }
+    const userStories = Array.isArray(prd.userStories) ? prd.userStories : [];
+    const story = userStories.find((item) => item && item.id === storyId);
+    if (!story) {
+        stderr(io, `verify-story-deliverables: story ${storyId} not in ${prdPath}\n`);
+        return 2;
+    }
+    if (!repo) {
+        const metadata = prd.metadata && typeof prd.metadata === "object" && !Array.isArray(prd.metadata)
+            ? prd.metadata : {};
+        repo = jqText(metadata.repoPath);
+    }
+    if (repo && !repo.startsWith("/"))
+        repo = `${hqRoot}/${repo}`;
+    const evidence = jsonDecode(evidenceJson);
+    if (!jqArrayCheck(evidence)) {
+        stderr(io, `verify-story-deliverables: --evidence-json must be a JSON array\n`);
+        return 2;
+    }
+    const commits = jsonDecode(commitsJson);
+    if (!jqArrayCheck(commits)) {
+        stderr(io, `verify-story-deliverables: --commits-json must be a JSON array\n`);
+        return 2;
+    }
+    const declaredRaw = story.deliverables ?? [];
+    if (!Array.isArray(declaredRaw) || !Array.isArray(evidence) || !Array.isArray(commits)) {
+        // jq's `+` is array concatenation in the normal contract; malformed PRD
+        // deliverables are left to jq's normal processing behavior.
+        const refsRaw = declaredRaw;
+        if (!Array.isArray(refsRaw)) {
+            stderr(io, `verify-story-deliverables: story ${storyId} not in ${prdPath}\n`);
+            return 2;
+        }
+    }
+    const declared = Array.isArray(declaredRaw) ? declaredRaw : [];
+    const refs = [...declared, ...evidence, ...commits.map((commit) => `commit:${jqText(commit)}`)]
+        .filter((ref) => typeof ref === "string" && ref.length > 0)
+        .sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))
+        .filter((ref, index, all) => index === 0 || ref !== all[index - 1]);
+    const declaredCount = Array.isArray(story.deliverables)
+        ? story.deliverables.length
+        : typeof story.deliverables === "string" ? [...story.deliverables].length
+            : story.deliverables && typeof story.deliverables === "object" ? Object.keys(story.deliverables).length
+                : 0;
+    if (refs.length === 0) {
+        if (strict) {
+            stderr(io, `verify-story-deliverables: ${storyId} has no evidence and declares no deliverables (--strict)\n`);
+            if (json)
+                stdout(io, serializeJqJson({ story: storyId, status: "unverified", missing: [], present: [] }, "compact"));
+            return 3;
+        }
+        if (json)
+            stdout(io, serializeJqJson({ story: storyId, status: "unverified", missing: [], present: [] }, "compact"));
+        else
+            stdout(io, `verify-story-deliverables: ${storyId} — nothing to verify (worker returned no evidence; PRD declares no deliverables). Allowed, but this done-mark is unverified.\n`);
+        return 0;
+    }
+    const present = [];
+    const missing = [];
+    for (const reference of refs) {
+        const colon = reference.indexOf(":");
+        const kind = colon >= 0 ? reference.slice(0, colon) : "path";
+        const value = colon >= 0 ? reference.slice(colon + 1) : reference;
+        let ok = false;
+        if (kind === "path")
+            ok = fileExists(joinShellPath(hqRoot, value));
+        else if (kind === "repo-path")
+            ok = Boolean(repo) && fileExists(`${repo}/${value}`);
+        else if (kind === "branch" && repo && fileExists(repo)) {
+            ok = git(["-C", repo, "show-ref", "--verify", "--quiet", `refs/heads/${value}`]).status === 0 ||
+                git(["-C", repo, "show-ref", "--verify", "--quiet", `refs/remotes/origin/${value}`]).status === 0;
+        }
+        else if (kind === "commit" && repo && fileExists(repo)) {
+            ok = git(["-C", repo, "cat-file", "-e", `${value}^{commit}`]).status === 0;
+        }
+        else if (kind === "url")
+            ok = offline === "1" || await urlIsPresent(value);
+        if (ok)
+            present.push(reference);
+        else
+            missing.push(reference);
+    }
+    if (json)
+        stdout(io, serializeJqJson({ story: storyId, status: missing.length === 0 ? "present" : "missing", missing, present }, "compact"));
+    if (missing.length > 0) {
+        stderr(io, `verify-story-deliverables: ${storyId} is NOT verifiably complete — ${missing.length} of ${refs.length} reference(s) do not exist:\n`);
+        for (const reference of missing)
+            stderr(io, `  - ${reference}\n`);
+        stderr(io, `Do not write passes:true. A claimed path/branch/commit/URL must exist; a declared deliverable must be produced (or the declaration corrected).\n`);
+        return 3;
+    }
+    if (write) {
+        const verifiedAt = nowOf(io).toISOString().replace(/\.\d{3}Z$/u, "Z");
+        const rewritten = {
+            ...prd,
+            userStories: userStories.map((item) => item.id === storyId
+                ? { ...item, evidence: present.map((ref) => ({ ref, verifiedAt })) }
+                : item),
+        };
+        try {
+            fs.writeFileSync(`${prdFilePath}.tmp`, serializeJqJson(rewritten, "pretty"), "utf8");
+            fs.renameSync(`${prdFilePath}.tmp`, prdFilePath);
+        }
+        catch { /* jq/mv are not checked; the legacy command continues to success */ }
+    }
+    const recordedSuffix = write ? "; recorded on the story" : "";
+    if (!json)
+        stdout(io, `verify-story-deliverables: ${storyId} — all ${refs.length} reference(s) present (${declaredCount} declared, ${refs.length - declaredCount} from worker evidence)${recordedSuffix}\n`);
+    return 0;
+}
+/** Fast-entry adapter; family gating and shell fallback happen before import. */
+export async function runWorktreeResumeFast(args, _stdin, cwd, hqRoot, commandName) {
+    const root = hqRoot ?? cwd;
+    let code;
+    if (commandName === "worktree-gc")
+        code = runWorktreeGc(args, root);
+    else if (commandName === "clean-worktree-reconcile-handoff")
+        code = runCleanWorktreeReconcileHandoff(args);
+    else if (commandName === "resume-thread-lock")
+        code = runResumeThreadLock(args, root);
+    else
+        code = await runVerifyStoryDeliverables(args, root);
+    if (code !== 0)
+        process.exitCode = code;
+    return code;
+}
+//# sourceMappingURL=worktree-resume.js.map