@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/commands/core-handoff.js

@@ -1,1144 +0,0 @@
-/** Native implementations of the handoff scaffold command family. */
-import { spawn, spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { archiveOldThreads } from "../lib/core-utils/archive-old-threads.js";
-import { summarizeHqStatus } from "../lib/core-utils/hq-status-summary.js";
-import { enqueueSessionEvent } from "../lib/mesh/live/enqueue.js";
-import { renderIndexTarget } from "../lib/index-render/index.js";
-import { defaultBackgroundDependencies, runBackgroundLauncher, } from "../lib/search-index/background.js";
-import { resolveLiveRoot } from "../utils/hq-roots.js";
-import { runBundledScript } from "../utils/run-bundled-script.js";
-import { describeCoreCommand } from "./core-command-catalog.js";
-import { compactJson, isRecord, jqTruthy, prettyJson, runHandoffOpenSteps, shellDate, } from "./core-handoff-open-steps.js";
-export { runHandoffOpenSteps };
-const ASSETS = {
-    finalize: "core/scripts/handoff-finalize.sh",
-    post: "core/scripts/handoff-post.sh",
-    openSteps: "core/scripts/handoff-open-steps.sh",
-};
-const DESCRIPTIONS = {
-    finalize: "Write and commit the current session handoff",
-    post: "Run best-effort post-handoff maintenance",
-    openSteps: "List and update open handoff steps",
-};
-const SESSION_ID_ENV_KEYS = [
-    "HQ_SESSION_ID",
-    "CLAUDE_CODE_SESSION_ID",
-    "CLAUDE_SESSION_ID",
-    "CODEX_SESSION_ID",
-    "CODEX_THREAD_ID",
-    "GROK_SESSION_ID",
-];
-function validSessionId(value) {
-    return value !== "" && value !== "." && value !== ".." && /^[A-Za-z0-9._-]+$/.test(value);
-}
-function resolveSessionId(root) {
-    for (const key of SESSION_ID_ENV_KEYS) {
-        const value = (process.env[key] ?? "").replace(/\s/g, "");
-        if (validSessionId(value))
-            return value;
-    }
-    const current = path.join(root, "workspace/sessions/.current");
-    try {
-        const value = fs.readFileSync(current, "utf8").replace(/\s/g, "");
-        return validSessionId(value) ? value : "";
-    }
-    catch {
-        return "";
-    }
-}
-function boundSessionCompany(root) {
-    const sessionId = resolveSessionId(root);
-    if (!sessionId)
-        return "";
-    const metadata = path.join(root, "workspace/sessions", sessionId, "meta.yaml");
-    let contents;
-    try {
-        contents = fs.readFileSync(metadata, "utf8");
-    }
-    catch {
-        return "";
-    }
-    const line = contents.split(/\r?\n/).find((entry) => /^\s*company_slug:/.test(entry));
-    if (!line)
-        return "";
-    const company = (line.replace(/^\s*company_slug:\s*/, "").replace(/^"|"$/g, ""));
-    return /^[a-z][a-z0-9_-]*$/.test(company) ? company : "";
-}
-class HandoffJsonOptionError extends Error {
-    flag;
-    constructor(flag, cause) {
-        super(cause instanceof Error ? cause.message : String(cause));
-        this.flag = flag;
-        this.name = "HandoffJsonOptionError";
-    }
-}
-function parseHandoffJson(value, flag) {
-    try {
-        return JSON.parse(value);
-    }
-    catch (error) {
-        throw new HandoffJsonOptionError(flag, error);
-    }
-}
-function nowFor(context) {
-    return context.now?.() ?? new Date();
-}
-function stamp(date) {
-    return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
-}
-function dayStamp(date) {
-    return date.toISOString().slice(0, 10).replaceAll("-", "");
-}
-function timeStamp(date) {
-    return date.toISOString().slice(11, 19).replaceAll(":", "");
-}
-function git(args, cwd) {
-    const result = spawnSync("git", args, {
-        cwd,
-        env: process.env,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (result.error)
-        return { code: 127, stdout: "", stderr: result.error.message };
-    return {
-        code: result.status ?? (result.signal ? 128 : 1),
-        stdout: typeof result.stdout === "string" ? result.stdout : "",
-        stderr: typeof result.stderr === "string" ? result.stderr : "",
-    };
-}
-function commandAvailable(name) {
-    for (const entry of (process.env.PATH ?? "").split(path.delimiter)) {
-        const candidate = path.resolve(entry || ".", name);
-        try {
-            fs.accessSync(candidate, fs.constants.X_OK);
-            if (fs.statSync(candidate).isFile())
-                return true;
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== "ENOENT" && code !== "ENOTDIR" && code !== "EACCES")
-                throw error;
-        }
-    }
-    return false;
-}
-function copyClipboardText(value, cwd) {
-    if (!value)
-        return false;
-    const command = [
-        { name: "pbcopy", args: [] },
-        { name: "wl-copy", args: [] },
-        { name: "xclip", args: ["-selection", "clipboard"] },
-    ].find((candidate) => commandAvailable(candidate.name));
-    if (!command)
-        return false;
-    try {
-        const result = spawnSync(command.name, command.args, {
-            cwd,
-            env: process.env,
-            input: value,
-            stdio: ["pipe", "ignore", "ignore"],
-        });
-        return result.status === 0;
-    }
-    catch {
-        // The shell implementation suppresses clipboard stderr and treats failure as false.
-        return false;
-    }
-}
-function mkdirParent(file) {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-}
-function writeAtomic(file, text, mode) {
-    mkdirParent(file);
-    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
-    fs.writeFileSync(temporary, text, mode === undefined ? undefined : { mode });
-    fs.renameSync(temporary, file);
-}
-function isSensitivePath(value) {
-    const exceptions = new Set(["core/settings/.gitkeep", "core/settings/pure-ralph.json"]);
-    if (exceptions.has(value))
-        return false;
-    const patterns = [
-        ".git", ".git/*", ".env", ".env.*", "*.credentials.json", "*.secret.*",
-        ".hq/deploy-passwords.json", ".hq/cognito-tokens.json", ".claude/settings.local.json",
-        ".claude/settings.local.*", "companies/*/settings/*", "settings/*.json",
-        "settings/**/*.json", "core/settings/*.json", "core/settings/**/*.json",
-    ];
-    return patterns.some((pattern) => globMatches(value, pattern));
-}
-function globMatches(value, pattern) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*").replaceAll("?", ".");
-    return new RegExp(`^${escaped}$`).test(value);
-}
-function normalizeRelativePath(raw, root) {
-    let relative = raw;
-    if (raw.startsWith(`${root}/`))
-        relative = raw.slice(root.length + 1);
-    else if (raw.startsWith("/"))
-        return undefined;
-    if (relative.startsWith("./"))
-        relative = relative.slice(2);
-    if (!relative || relative.startsWith("-") || relative === ".." || relative.startsWith("../")
-        || relative.includes("/../") || relative === ".git" || relative.startsWith(".git/"))
-        return undefined;
-    return relative;
-}
-function pathEntries(value) {
-    if (!Array.isArray(value))
-        return [];
-    const entries = [];
-    for (const entry of value) {
-        if (typeof entry === "string")
-            entries.push({ raw: entry, deleted: false });
-        else if (isRecord(entry)) {
-            const deleted = entry.deleted === true || entry.status === "deleted";
-            entries.push({ raw: typeof entry.path === "string" ? entry.path : "", deleted });
-        }
-    }
-    return entries;
-}
-function touchedCompanyPaths(paths) {
-    return [...new Set(paths.flatMap((item) => {
-            const match = /^companies\/([a-z][a-z0-9_-]*)\//.exec(item);
-            return match?.[1] ? [match[1]] : [];
-        }))].sort();
-}
-function mirrorThread(root, threadPath) {
-    try {
-        const thread = JSON.parse(fs.readFileSync(threadPath, "utf8"));
-        if (!isRecord(thread) || !isRecord(thread.metadata))
-            return;
-        const rawCompanies = thread.metadata.company;
-        if (!jqTruthy(rawCompanies))
-            return;
-        const companies = Array.isArray(rawCompanies) ? rawCompanies : [rawCompanies];
-        if (typeof thread.thread_id !== "string" || !thread.thread_id)
-            return;
-        const updatedAt = thread.updated_at ?? thread.created_at ?? "";
-        const kind = thread.type ?? "unknown";
-        const rawTitle = thread.metadata.title ?? thread.conversation_summary ?? "";
-        const title = Buffer.from(typeof rawTitle === "string" ? rawTitle : compactJson(rawTitle)).subarray(0, 200).toString("utf8");
-        const rowFor = (company) => compactJson({ thread_id: thread.thread_id, ts: updatedAt, kind, company, title }).trimEnd();
-        for (const company of companies) {
-            if (company === "")
-                continue;
-            const companyRoot = path.join(root, "companies", String(company));
-            if (!fs.existsSync(companyRoot))
-                continue;
-            const workspace = path.join(companyRoot, "workspace");
-            const sessions = path.join(workspace, "sessions");
-            const indexFile = path.join(workspace, "index.jsonl");
-            const ignoreFile = path.join(workspace, ".gitignore");
-            fs.mkdirSync(sessions, { recursive: true });
-            if (!fs.existsSync(ignoreFile)) {
-                fs.writeFileSync(ignoreFile, "# HQ workspace mirror — sessions are gitignored, index.jsonl is committed\nsessions/\n");
-            }
-            const target = path.join(sessions, `${thread.thread_id}.json`);
-            try {
-                fs.rmSync(target, { force: true });
-                fs.linkSync(threadPath, target);
-            }
-            catch {
-                try {
-                    fs.copyFileSync(threadPath, target);
-                }
-                catch { /* legacy hook is fail-soft at the caller */ }
-            }
-            const row = rowFor(company);
-            const dedupKey = `"thread_id":"${thread.thread_id}","ts":"${updatedAt}","kind":"${kind}"`;
-            if (fs.existsSync(indexFile) && fs.readFileSync(indexFile, "utf8").includes(dedupKey))
-                continue;
-            fs.appendFileSync(indexFile, `${row}\n`);
-        }
-    }
-    catch {
-        // The legacy finalizer ignores every mirror-hook error.
-    }
-}
-function statusSummary(root, touchedFile) {
-    let output = "";
-    try {
-        const code = summarizeHqStatus(["--session-files-file", touchedFile, "--json"], {
-            cwd: root,
-            root,
-            stdout: (text) => { output += text; },
-            stderr: () => { },
-        });
-        if (code !== 0 || !output.trim())
-            return {};
-        return JSON.parse(output);
-    }
-    catch {
-        return {};
-    }
-}
-function renderIndex(root, target, args = []) {
-    try {
-        renderIndexTarget(target, { root, output: () => { }, log: () => { } }, args);
-    }
-    catch { /* both legacy rebuild calls are fail-soft */ }
-}
-function mainCheckoutRoot(commonDir, root) {
-    const absolute = path.isAbsolute(commonDir) || /^[A-Za-z]:\//.test(commonDir)
-        ? commonDir
-        : path.join(root, commonDir);
-    return fs.realpathSync(path.dirname(absolute));
-}
-function finalizeGitProbe(root) {
-    const result = spawnSync("git", ["rev-parse", "--git-common-dir"], {
-        cwd: root,
-        env: { ...process.env, LC_ALL: "C" },
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (!result.error && result.status === 0)
-        return { hasGit: true, commonDir: String(result.stdout ?? "").trim() };
-    const output = `${String(result.stdout ?? "")}${String(result.stderr ?? "")}`.trimEnd();
-    const checkoutMarker = path.join(root, ".git");
-    if (!fs.existsSync(checkoutMarker) && !fs.lstatSync(checkoutMarker, { throwIfNoEntry: false })
-        && output.includes("not a git repository"))
-        return { hasGit: false, commonDir: "" };
-    return {
-        code: 4,
-        stdout: "",
-        stderr: `handoff-finalize: Git checkout probe failed (exit ${result.status ?? 127}): ${output}\n`,
-    };
-}
-function printGitStatus(root) {
-    return git(["status", "--porcelain"], root).stdout;
-}
-function stagePath(root, pathname) {
-    const absolute = path.join(root, pathname);
-    const exists = fs.existsSync(absolute) || git(["status", "--porcelain", "--", pathname], root).stdout !== "";
-    if (!exists)
-        return { attempted: false, ok: false, failed: false };
-    if (git(["add", "--", pathname], root).code === 0)
-        return { attempted: true, ok: true, failed: false };
-    if (git(["ls-files", "--error-unmatch", "--", pathname], root).code === 0) {
-        return git(["add", "-f", "--", pathname], root).code === 0
-            ? { attempted: true, ok: true, failed: false }
-            : { attempted: true, ok: false, failed: true };
-    }
-    if (git(["check-ignore", "--no-index", "-q", "--", pathname], root).code === 0) {
-        return { attempted: true, ok: false, failed: false };
-    }
-    return { attempted: true, ok: false, failed: true };
-}
-function tidyGitMessage(value) {
-    const flattened = value.replace(/[\r\n]/g, " ").replace(/  */g, " ").replace(/^ | $/g, "");
-    return Buffer.from(flattened).subarray(0, 500).toString("utf8").replace(/\uFFFD+$/, "");
-}
-function resolveFinalizeOptions(args) {
-    const values = {
-        title: "Handoff: session continuation", summary: "", message: "", nextSteps: "[]",
-        filesTouched: "[]", filesTouchedFile: "", learnings: "[]", tags: '["handoff"]',
-        slug: "handoff", nextCommand: "__auto__",
-    };
-    const map = {
-        "--title": "title", "--summary": "summary", "--message": "message",
-        "--next-steps-json": "nextSteps", "--files-touched-json": "filesTouched",
-        "--files-touched-json-file": "filesTouchedFile", "--learnings-json": "learnings",
-        "--tags-json": "tags", "--slug": "slug", "--next-command": "nextCommand",
-    };
-    for (let index = 0; index < args.length;) {
-        const key = args[index] ?? "";
-        const target = map[key];
-        if (!target)
-            return { values, error: { code: 2, stdout: "", stderr: `Unknown arg: ${key}\n` } };
-        if (index + 1 >= args.length) {
-            const shellAsset = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../assets/scaffold", ASSETS.finalize);
-            return { values, error: { code: 1, stdout: "", stderr: `${shellAsset}: line 93: $2: unbound variable\n` } };
-        }
-        values[target] = args[index + 1] ?? "";
-        index += 2;
-    }
-    return { values };
-}
-export function runHandoffFinalize(args, context) {
-    const root = fs.realpathSync(context.root);
-    const probe = finalizeGitProbe(root);
-    if ("code" in probe)
-        return probe;
-    let gitBgErrors = "";
-    const tmpRoot = context.tmpDir ?? "/tmp";
-    const gitPidFile = path.join(tmpRoot, "handoff-git-bg.pid");
-    if (fs.existsSync(gitPidFile)) {
-        let pid = "";
-        try {
-            pid = fs.readFileSync(gitPidFile, "utf8").trim();
-        }
-        catch { /* legacy reads fail-soft */ }
-        if (pid) {
-            const gitLog = path.join(tmpRoot, "handoff-git-bg.log");
-            if (fs.existsSync(gitLog)) {
-                try {
-                    gitBgErrors = fs.readFileSync(gitLog, "utf8").split(/\r?\n/).filter((entry) => entry.startsWith("ERR:")).join("\n");
-                }
-                catch {
-                    gitBgErrors = "";
-                }
-            }
-        }
-        try {
-            fs.rmSync(gitPidFile, { force: true });
-        }
-        catch { /* shell cleanup ignores rm failures */ }
-    }
-    const { values, error } = resolveFinalizeOptions(args);
-    if (error)
-        return error;
-    const timestamp = nowFor(context);
-    const ts = stamp(timestamp);
-    const date = dayStamp(timestamp);
-    const clock = timeStamp(timestamp);
-    const threadId = `T-${date}-${clock}-${values.slug}`;
-    const threadPath = `workspace/threads/${threadId}.json`;
-    const changesetPath = `workspace/threads/${threadId}.changeset.json`;
-    const threadsDir = path.join(root, "workspace/threads");
-    const tempDirectory = path.join(threadsDir, ".handoff-tmp");
-    fs.mkdirSync(tempDirectory, { recursive: true });
-    const cleanup = [];
-    const tempFile = () => {
-        const file = path.join(tempDirectory, `.handoff-${process.pid}-${Math.random().toString(36).slice(2)}`);
-        fs.writeFileSync(file, "");
-        cleanup.push(file);
-        return file;
-    };
-    try {
-        const safePaths = [];
-        const skipped = [];
-        let touchedValue;
-        if (values.filesTouchedFile) {
-            const file = path.isAbsolute(values.filesTouchedFile) ? values.filesTouchedFile : path.join(root, values.filesTouchedFile);
-            if (!fs.existsSync(file))
-                return { code: 3, stdout: "", stderr: `handoff-finalize: --files-touched-json-file not found: ${values.filesTouchedFile}\n` };
-            touchedValue = parseHandoffJson(fs.readFileSync(file, "utf8"), "--files-touched-json-file");
-        }
-        else {
-            touchedValue = parseHandoffJson(values.filesTouched, "--files-touched-json");
-        }
-        const touchedFile = values.filesTouchedFile
-            ? (path.isAbsolute(values.filesTouchedFile) ? values.filesTouchedFile : path.join(root, values.filesTouchedFile))
-            : tempFile();
-        if (!values.filesTouchedFile)
-            fs.writeFileSync(touchedFile, values.filesTouched);
-        for (const entry of pathEntries(touchedValue)) {
-            if (!entry.raw)
-                continue;
-            const relative = normalizeRelativePath(entry.raw, root);
-            if (relative === undefined) {
-                skipped.push({ path: entry.raw, reason: "unsafe-path" });
-                continue;
-            }
-            if (isSensitivePath(relative)) {
-                skipped.push({ path: relative, reason: "sensitive-path" });
-                continue;
-            }
-            if (!fs.existsSync(path.join(root, relative))) {
-                if (probe.hasGit && entry.deleted && git(["ls-files", "--error-unmatch", relative], root).code === 0)
-                    safePaths.push(relative);
-                else
-                    skipped.push({ path: relative, reason: "missing" });
-                continue;
-            }
-            safePaths.push(relative);
-        }
-        const sessionCompany = boundSessionCompany(root);
-        const companyDirectory = sessionCompany
-            ? fs.statSync(path.join(root, "companies", sessionCompany), { throwIfNoEntry: false })
-            : undefined;
-        const companies = [...new Set([
-                ...touchedCompanyPaths(safePaths),
-                ...(companyDirectory?.isDirectory() ? [sessionCompany] : []),
-            ])].sort();
-        const dirty = probe.hasGit && printGitStatus(root) !== "";
-        const branchResult = probe.hasGit ? git(["symbolic-ref", "--short", "HEAD"], root) : { code: 1, stdout: "", stderr: "" };
-        const commitResult = probe.hasGit ? git(["rev-parse", "--short", "HEAD"], root) : { code: 1, stdout: "", stderr: "" };
-        const branch = branchResult.code === 0 ? branchResult.stdout.trim() : "DETACHED";
-        const startCommit = commitResult.code === 0 ? commitResult.stdout.trim() : "unknown";
-        const status = statusSummary(root, touchedFile);
-        const stepsInput = parseHandoffJson(values.nextSteps, "--next-steps-json");
-        const nextSteps = Array.isArray(stepsInput) ? stepsInput.map((raw, index) => {
-            const step = typeof raw === "string" ? { step: raw } : isRecord(raw) ? { ...raw } : {};
-            if (!jqTruthy(step.id))
-                step.id = `${threadId}#${index + 1}`;
-            if (!jqTruthy(step.status))
-                step.status = "open";
-            delete step.key;
-            return step;
-        }) : [];
-        const thread = {
-            thread_id: threadId,
-            version: 1,
-            type: "handoff",
-            created_at: ts,
-            updated_at: ts,
-            workspace_root: root,
-            cwd: root,
-            git: { branch, current_commit: startCommit, dirty },
-            changeset_path: changesetPath,
-            conversation_summary: values.summary,
-            next_steps: nextSteps,
-            files_touched: touchedValue,
-            learnings: parseHandoffJson(values.learnings, "--learnings-json"),
-            metadata: { title: values.title, tags: parseHandoffJson(values.tags, "--tags-json"), company: companies },
-        };
-        fs.mkdirSync(threadsDir, { recursive: true });
-        fs.writeFileSync(path.join(root, threadPath), prettyJson(thread));
-        // Replay the old PostToolUse mirror in process; the hook was fail-soft.
-        if (fs.existsSync(path.join(root, ".claude/hooks/mirror-thread-to-company.sh"))) {
-            mirrorThread(root, path.join(root, threadPath));
-        }
-        const mirrored = companies.filter((company) => fs.existsSync(path.join(root, "companies", company, "workspace/sessions", `${threadId}.json`)));
-        const mirrorStagePaths = mirrored.flatMap((company) => [
-            `companies/${company}/workspace/index.jsonl`,
-            `companies/${company}/workspace/.gitignore`,
-        ]);
-        const changeset = {
-            thread_id: threadId,
-            thread_path: threadPath,
-            created_at: ts,
-            intent: { title: values.title, summary: values.summary },
-            git: {
-                branch,
-                started_commit: startCommit,
-                finalized_commit: null,
-                finalized_commit_note: "The exact handoff commit is emitted by handoff-finalize.sh as commit_after_finalize; a file cannot contain the hash of the commit that contains itself.",
-            },
-            files_touched: touchedValue,
-            staged_paths: probe.hasGit ? safePaths : [],
-            skipped_paths: skipped,
-            verification: { notes: [], upstream_refs_compared: [] },
-            status_summary: status,
-        };
-        fs.writeFileSync(path.join(root, changesetPath), prettyJson(changeset));
-        const pointerPath = path.join(root, "workspace/threads/handoff.json");
-        writeAtomic(pointerPath, prettyJson({
-            created_at: ts,
-            message: values.message,
-            last_thread: threadId,
-            thread_path: threadPath,
-            context_notes: values.summary,
-        }), 0o600);
-        if (probe.hasGit) {
-            const main = mainCheckoutRoot(probe.commonDir, root);
-            if (main !== root) {
-                writeAtomic(path.join(main, threadPath), fs.readFileSync(path.join(root, threadPath), "utf8"), 0o600);
-                writeAtomic(path.join(main, "workspace/threads/handoff.json"), prettyJson({
-                    created_at: ts,
-                    message: values.message,
-                    last_thread: threadId,
-                    thread_path: threadPath,
-                    context_notes: values.summary,
-                }), 0o600);
-            }
-        }
-        renderIndex(root, "threads", ["--both"]);
-        renderIndex(root, "orchestrator");
-        const indexPath = path.join(root, "INDEX.md");
-        if (fs.existsSync(indexPath)) {
-            const current = fs.readFileSync(indexPath, "utf8");
-            if (/^Generated:/m.test(current))
-                writeAtomic(indexPath, current.replace(/^Generated:.*$/gm, `Generated: ${ts}`), 0o600);
-        }
-        const explicit = [
-            ...safePaths,
-            ...mirrorStagePaths,
-            threadPath,
-            changesetPath,
-            "workspace/threads/handoff.json",
-            "workspace/threads/recent.md",
-            "workspace/threads/INDEX.md",
-            "workspace/orchestrator/INDEX.md",
-            "INDEX.md",
-        ];
-        let staged = 0;
-        const stageFailures = [];
-        if (probe.hasGit) {
-            for (const pathname of explicit) {
-                if (!pathname)
-                    continue;
-                const result = stagePath(root, pathname);
-                if (result.ok)
-                    staged += 1;
-                else if (result.failed)
-                    stageFailures.push(pathname);
-            }
-        }
-        let hqCommitted = false;
-        let commitStatus = probe.hasGit ? "nothing-to-commit" : "no-git-checkout";
-        let commitError = "";
-        let committedPaths = [];
-        if (probe.hasGit && staged > 0) {
-            const pending = git(["diff", "--cached", "--name-only"], root).stdout.split(/\r?\n/).filter(Boolean);
-            if (pending.length > 0) {
-                const committed = git(["commit", "-m", `checkpoint: handoff ${threadId}`], root);
-                if (committed.code === 0) {
-                    hqCommitted = true;
-                    commitStatus = "committed";
-                    committedPaths = pending;
-                }
-                else {
-                    commitStatus = "failed";
-                    commitError = tidyGitMessage(`${committed.stdout}${committed.stderr}`) || `git commit exited ${committed.code} with no output`;
-                }
-            }
-        }
-        if (stageFailures.length > 0 && commitStatus !== "failed") {
-            commitStatus = "stage-failed";
-            if (!commitError)
-                commitError = `git add failed for ${stageFailures.length} path(s) — see stage_failures`;
-        }
-        let qmdPid = "";
-        // This is the same TypeScript launcher reached by qmd-reindex-bg.sh.
-        try {
-            const qmd = runIndexBackground(root, path.join(tmpRoot, "qmd-handoff.log"));
-            if (qmd.output)
-                qmdPid = qmd.output;
-        }
-        catch { /* the shell helper is fail-soft */ }
-        const nextCommand = values.nextCommand === "__auto__" ? `/resumework ${threadId}` : values.nextCommand;
-        const clipboardCopied = copyClipboardText(nextCommand, root);
-        const payload = {
-            thread_id: threadId,
-            thread_path: threadPath,
-            changeset_path: changesetPath,
-            handoff_path: "workspace/threads/handoff.json",
-            hq_committed: hqCommitted,
-            hq_commit_status: commitStatus,
-            hq_commit_error: commitError,
-            commit_after_finalize: probe.hasGit ? (git(["rev-parse", "--short", "HEAD"], root).stdout.trim() || "unknown") : "unknown",
-            committed_paths: committedPaths,
-            stage_failures: stageFailures,
-            skipped_paths: skipped,
-            baseline_noise_count: isRecord(status) && isRecord(status.counts) ? status.counts.baseline_noise ?? 0 : 0,
-            indexes_regen: true,
-            qmd_pid: qmdPid,
-            git_bg_errors: gitBgErrors,
-            next_command: nextCommand,
-            clipboard_copied: clipboardCopied,
-            mirror_companies: mirrored,
-        };
-        const stdout = prettyJson(payload);
-        const stderrParts = [];
-        if (gitBgErrors)
-            stderrParts.push(`handoff-finalize: WARNING background git step reported errors: ${gitBgErrors}\n`);
-        if (stageFailures.length > 0) {
-            stderrParts.push(`handoff-finalize: ERROR git add failed for ${stageFailures.length} path(s):\n`);
-            for (const pathname of stageFailures)
-                stderrParts.push(`handoff-finalize:   ${pathname}\n`);
-        }
-        if (commitStatus === "failed" || commitStatus === "stage-failed") {
-            stderrParts.push("handoff-finalize: ERROR the HQ handoff commit FAILED — thread files were written but are NOT committed.\n");
-            stderrParts.push(`handoff-finalize: git said: ${commitError}\n`);
-            stderrParts.push("handoff-finalize: resolve the git error and re-run /handoff before ending the session.\n");
-            return { code: 4, stdout, stderr: stderrParts.join("") };
-        }
-        return { code: 0, stdout, stderr: stderrParts.join("") };
-    }
-    catch (error) {
-        if (error instanceof HandoffJsonOptionError) {
-            return { code: 2, stdout: "", stderr: `handoff-finalize: invalid JSON for ${error.flag}: ${error.message}\n` };
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        return { code: 1, stdout: "", stderr: `${message}\n` };
-    }
-    finally {
-        for (const file of cleanup) {
-            try {
-                fs.rmSync(file, { force: true });
-            }
-            catch { /* trap cleanup is best-effort */ }
-        }
-    }
-}
-function indexRenderer(root, target) {
-    let stderr = "";
-    try {
-        renderIndexTarget(target, {
-            root,
-            output: () => { },
-            log: (message) => { stderr += `${message}\n`; },
-        }, target === "threads" ? ["--both"] : []);
-        return { code: 0, stdout: "", stderr };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { code: 1, stdout: "", stderr: `${message}\n` };
-    }
-}
-function appendLog(file, text) {
-    fs.appendFileSync(file, text);
-}
-function recordCommand(log, result) {
-    if (result.stdout)
-        appendLog(log, result.stdout);
-    if (result.stderr)
-        appendLog(log, result.stderr);
-}
-function runArchive(root, now) {
-    let stderr = "";
-    const code = archiveOldThreads(["--gated"], {
-        hqRoot: root,
-        now: () => now,
-        stdout: () => { },
-        stderr: (text) => { stderr += text; },
-    });
-    return { code, stdout: "", stderr };
-}
-function runIndexBackground(root, logPath) {
-    let stderr = "";
-    const dependencies = defaultBackgroundDependencies(root);
-    dependencies.env = { ...dependencies.env, QMD_REINDEX_LOG: logPath };
-    dependencies.writeStderr = (text) => { stderr += text; };
-    const result = runBackgroundLauncher(dependencies);
-    const output = result.state === "launched"
-        ? String(result.pid)
-        : result.state === "skipped-agent" || result.state === "skipped"
-            ? result.state
-            : "";
-    return { output, stderr };
-}
-function readThreadCompanyNames(file) {
-    try {
-        const thread = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (!isRecord(thread) || !isRecord(thread.metadata))
-            return [];
-        const value = thread.metadata.company;
-        if (!jqTruthy(value))
-            return [];
-        const values = Array.isArray(value) ? value : [value];
-        return [...new Set(values.filter((item) => typeof item === "string" && /^[a-z][a-z0-9_-]*$/.test(item)))].sort();
-    }
-    catch {
-        return [];
-    }
-}
-function documentReleaseCounts(file) {
-    try {
-        const thread = JSON.parse(fs.readFileSync(file, "utf8"));
-        const touched = isRecord(thread) ? thread.files_touched : undefined;
-        const files = Array.isArray(touched) ? touched : [];
-        const paths = files.map((entry) => {
-            if (typeof entry === "string")
-                return entry;
-            if (isRecord(entry) && typeof entry.path === "string")
-                return entry.path;
-            return null;
-        });
-        return {
-            scope: paths.filter((item) => item !== null && /^(companies|repos)\//.test(item)).length,
-            skipped: paths.filter((item) => item === null).length,
-            invalid: false,
-        };
-    }
-    catch {
-        return { scope: 0, skipped: 0, invalid: true };
-    }
-}
-function workMeshSessionEnd(root) {
-    const hook = path.join(root, "core/hooks/SessionEnd/35-work-mesh-session-end.sh");
-    if (!fs.existsSync(hook))
-        return "work-mesh-session-end: skipped (hook absent)";
-    if (["1", "true", "TRUE", "yes", "YES", "on", "ON"].includes(process.env.HQ_WORK_MESH_DISABLED ?? ""))
-        return "work-mesh-session-end: skipped (hook disabled)";
-    if (/(^|,)(work-mesh|work-mesh-live|\*)(,|$)/.test(`,${process.env.HQ_DISABLED_HOOKS ?? ""},`))
-        return "work-mesh-session-end: skipped (hook disabled)";
-    const sessionId = resolveSessionId(root);
-    if (!sessionId)
-        return undefined;
-    let harness = process.env.HQ_HARNESS || process.env.HQ_WORK_MESH_HARNESS || process.env.HQ_CHECKPOINT_RUNTIME || "claude-code";
-    if (["claude", "Claude", "ClaudeCode"].includes(harness))
-        harness = "claude-code";
-    if (harness === "Codex")
-        harness = "codex";
-    if (harness === "Grok")
-        harness = "grok";
-    const adapterVersion = process.env.HQ_ADAPTER_CONTRACT_VERSION || "1.0.0";
-    const sequenceDirectory = process.env.WORK_MESH_SEQ_DIR || path.join(process.env.HOME || os.homedir(), ".hq/work-mesh/seq");
-    const sequenceFile = path.join(sequenceDirectory, sessionId);
-    let sequence = 0;
-    try {
-        const raw = fs.readFileSync(sequenceFile, "utf8").replace(/\s/g, "");
-        if (/^\d+$/.test(raw))
-            sequence = Number(raw);
-    }
-    catch { /* sequence file is optional */ }
-    sequence += 1;
-    try {
-        fs.mkdirSync(sequenceDirectory, { recursive: true, mode: 0o700 });
-        fs.chmodSync(sequenceDirectory, 0o700);
-        fs.writeFileSync(sequenceFile, `${sequence}\n`);
-        enqueueSessionEvent({
-            kind: "session_end",
-            sessionId,
-            harness: harness,
-            adapterVersion,
-            seq: sequence,
-            cwd: root,
-            hqRoot: root,
-            env: { ...process.env, HQ_ROOT: root, CLAUDE_CODE_SESSION_ID: sessionId },
-        });
-    }
-    catch {
-        // The SessionEnd hook suppresses work-mesh enqueue failures.
-    }
-    // The legacy entry is detached. The in-process implementation has completed
-    // the same local spool write before returning from the already-detached post.
-    return "work-mesh-session-end: launched";
-}
-function spawnBashDetached(script, args, cwd, root, logFile) {
-    let fd;
-    try {
-        mkdirParent(logFile);
-        fd = fs.openSync(logFile, "a");
-        const child = spawn("bash", [script, ...args], {
-            cwd,
-            env: { ...process.env, HQ_ROOT: root },
-            detached: true,
-            windowsHide: true,
-            stdio: ["ignore", fd, fd],
-        });
-        child.once("error", (error) => appendLog(logFile, `${error.message}\n`));
-        child.unref();
-        fs.closeSync(fd);
-        fd = undefined;
-        return child.pid;
-    }
-    catch {
-        return undefined;
-    }
-    finally {
-        if (fd !== undefined) {
-            try {
-                fs.closeSync(fd);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                appendLog(logFile, `worktree-gc: log close failed: ${message}\n`);
-            }
-        }
-    }
-}
-function parseLearningCount(file) {
-    try {
-        const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        return Array.isArray(value) ? value.length : 0;
-    }
-    catch {
-        return 0;
-    }
-}
-async function launchHandoffPost(args, root) {
-    return await new Promise((resolve) => {
-        try {
-            const child = spawn("hq", ["core", "--hq-root", root, "handoff", "post", ...args], {
-                cwd: root,
-                env: { ...process.env, HQ_NATIVE_HANDOFF_POST_CHILD: "1" },
-                detached: true,
-                windowsHide: true,
-                stdio: "ignore",
-            });
-            child.once("error", (error) => resolve({ code: 127, stdout: "", stderr: `${error.message}\n` }));
-            child.once("spawn", () => {
-                child.unref();
-                resolve({ code: 0, stdout: "", stderr: "" });
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            resolve({ code: 1, stdout: "", stderr: `${message}\n` });
-        }
-    });
-}
-export function runHandoffPost(args, context) {
-    const root = fs.realpathSync(context.root);
-    if (process.env.HQ_NATIVE_HANDOFF_POST_CHILD !== "1")
-        return launchHandoffPost(args, root);
-    return runHandoffPostWorker(args, { ...context, root });
-}
-export function runHandoffPostWorker(args, context) {
-    const root = fs.realpathSync(context.root);
-    const threadPath = args[0] ?? "";
-    const learningsFile = args[1] ?? "";
-    const threadFile = threadPath ? path.resolve(root, threadPath) : "";
-    const learningsFilePath = learningsFile ? path.resolve(root, learningsFile) : "";
-    const logDir = process.env.HANDOFF_LOG_DIR || "/tmp";
-    const logMain = path.join(logDir, "handoff-post.log");
-    const logQmd = path.join(logDir, "qmd-handoff.log");
-    const time = shellDate(nowFor(context));
-    const log = (message) => appendLog(logMain, `[${time}] ${message}\n`);
-    fs.writeFileSync(logMain, "");
-    log(`handoff-post starting (thread=${threadPath || "none"}, learnings=${learningsFile || "none"})`);
-    const archive = runArchive(root, nowFor(context));
-    recordCommand(logMain, archive);
-    log(archive.code === 0 ? "archive: ok" : "archive: error (continuing)");
-    const threadsIndex = indexRenderer(root, "threads");
-    recordCommand(logMain, threadsIndex);
-    log(threadsIndex.code === 0 ? "threads-index: ok" : "threads-index: error (continuing)");
-    const orchestratorIndex = indexRenderer(root, "orchestrator");
-    recordCommand(logMain, orchestratorIndex);
-    log(orchestratorIndex.code === 0 ? "orchestrator-index: ok" : "orchestrator-index: error (continuing)");
-    if (learningsFilePath && fs.existsSync(learningsFilePath) && fs.statSync(learningsFilePath).size > 0) {
-        const count = parseLearningCount(learningsFilePath);
-        if (count > 0)
-            log(`learn: eligible and pending runtime dispatch by handoff skill (${count} learning(s); no dispatch proof)`);
-        else
-            log("learn: no learnings to dispatch");
-    }
-    else
-        log("learn: no learnings file provided");
-    if (threadFile && fs.existsSync(threadFile)) {
-        const counts = documentReleaseCounts(threadFile);
-        if (counts.invalid)
-            log("document-release: skipped (invalid thread JSON)");
-        for (let index = 0; index < counts.skipped; index += 1)
-            log("document-release: skipped unsupported files_touched entry");
-        if (counts.scope > 0) {
-            const installedScript = path.join(root, "core/scripts/skill-installed.sh");
-            const logFd = fs.openSync(logMain, "a");
-            let installedStatus = null;
-            try {
-                const installed = spawnSync("bash", [installedScript, "document-release", process.env.HQ_ACTIVE_COMPANY || ""], {
-                    cwd: root,
-                    env: process.env,
-                    stdio: ["ignore", "ignore", logFd],
-                });
-                installedStatus = installed.status;
-            }
-            finally {
-                fs.closeSync(logFd);
-            }
-            if (installedStatus === 0) {
-                log(`document-release: eligible and pending runtime dispatch by handoff skill (${counts.scope} scoped files; no dispatch proof)`);
-            }
-            else
-                log("document-release: skipped (skill not installed)");
-        }
-        else
-            log("document-release: skipped (no company/repo files in files_touched)");
-    }
-    else
-        log("document-release: skipped (no thread path)");
-    if (threadFile && fs.existsSync(threadFile) && commandAvailable("hq")) {
-        let syncCompanies = readThreadCompanyNames(threadFile);
-        const sessionCompany = boundSessionCompany(root);
-        if (sessionCompany) {
-            const updatedCompanies = [...new Set([...syncCompanies, sessionCompany])].sort();
-            const companyListChanged = JSON.stringify(syncCompanies) !== JSON.stringify(updatedCompanies);
-            syncCompanies = updatedCompanies;
-            if (companyListChanged) {
-                try {
-                    const thread = JSON.parse(fs.readFileSync(threadFile, "utf8"));
-                    if (!isRecord(thread))
-                        throw new Error("thread is not an object");
-                    let metadata;
-                    if (thread.metadata === null || thread.metadata === undefined)
-                        metadata = {};
-                    else if (isRecord(thread.metadata))
-                        metadata = thread.metadata;
-                    else
-                        throw new Error("thread metadata is not an object");
-                    metadata.company = syncCompanies;
-                    thread.metadata = metadata;
-                    const temporaryThread = path.join(path.dirname(threadFile), `.handoff-post-${process.pid}-${Math.random().toString(36).slice(2)}`);
-                    let temporaryFd;
-                    try {
-                        temporaryFd = fs.openSync(temporaryThread, "wx", 0o600);
-                        fs.writeFileSync(temporaryFd, `${compactJson(thread).trimEnd()}\n`);
-                        fs.closeSync(temporaryFd);
-                        temporaryFd = undefined;
-                        fs.chmodSync(temporaryThread, 0o600);
-                        fs.renameSync(temporaryThread, threadFile);
-                    }
-                    catch (error) {
-                        if (temporaryFd !== undefined) {
-                            try {
-                                fs.closeSync(temporaryFd);
-                            }
-                            catch { /* temporary output cleanup remains best effort */ }
-                        }
-                        try {
-                            fs.rmSync(temporaryThread, { force: true });
-                        }
-                        catch { /* jq/mv cleanup is fail-soft */ }
-                        throw error;
-                    }
-                }
-                catch {
-                    log("workspace-sync: skipped (could not add bound company to handoff thread)");
-                    syncCompanies = [];
-                }
-            }
-        }
-        let threadId = "";
-        let threadMirrorable = false;
-        try {
-            const thread = JSON.parse(fs.readFileSync(threadFile, "utf8"));
-            threadId = isRecord(thread) && typeof thread.thread_id === "string" ? thread.thread_id : "";
-            const relative = path.relative(root, threadFile);
-            threadMirrorable = /^workspace[\\/]threads[\\/]T-[A-Za-z0-9._-]+\.json$/.test(relative)
-                && /^T-[A-Za-z0-9._-]+$/.test(threadId);
-        }
-        catch { /* shell helper treats an invalid thread as non-mirrorable */ }
-        if (threadMirrorable && syncCompanies.length > 0) {
-            const mirrorHook = path.join(root, ".claude/hooks/mirror-thread-to-company.sh");
-            if (fs.existsSync(mirrorHook))
-                mirrorThread(root, threadFile);
-            else
-                log("workspace-sync: mirror hook unavailable for handoff thread");
-        }
-        for (const company of syncCompanies) {
-            if (!fs.existsSync(path.join(root, "companies", company, "workspace")))
-                continue;
-            if (!threadMirrorable || !fs.existsSync(path.join(root, "companies", company, "workspace/sessions", `${threadId}.json`))) {
-                log(`workspace-sync: skipped (thread mirror missing for ${company})`);
-                continue;
-            }
-            const pushed = spawnSync("hq", ["sync", "push", "--company", company, `companies/${company}/workspace`], {
-                cwd: root,
-                env: process.env,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-            recordCommand(logMain, {
-                code: pushed.status ?? 1,
-                stdout: typeof pushed.stdout === "string" ? pushed.stdout : "",
-                stderr: typeof pushed.stderr === "string" ? pushed.stderr : "",
-            });
-            log(pushed.status === 0 ? `workspace-sync: pushed companies/${company}/workspace` : `workspace-sync: failed companies/${company}/workspace`);
-        }
-    }
-    else if (threadFile && fs.existsSync(threadFile))
-        log("workspace-sync: skipped (hq CLI unavailable)");
-    const qmdHelper = path.join(root, "core/scripts/qmd-reindex-bg.sh");
-    const fleetQmdHelper = "/usr/local/bin/hq-agent-qmd-reindex-bg";
-    let fleetQmdHelperExecutable = false;
-    if (!fs.existsSync(qmdHelper)) {
-        try {
-            fs.accessSync(fleetQmdHelper, fs.constants.X_OK);
-            fleetQmdHelperExecutable = true;
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== "ENOENT" && code !== "ENOTDIR" && code !== "EACCES")
-                throw error;
-        }
-    }
-    if (fs.existsSync(qmdHelper) || fleetQmdHelperExecutable) {
-        const background = runIndexBackground(root, logQmd);
-        if (background.stderr)
-            appendLog(logMain, background.stderr);
-        log(`qmd: reindex-bg → ${background.output || "busy-or-quiet"}`);
-    }
-    else if (fs.existsSync("/var/lib/hq-agent"))
-        log("qmd: skipped-agent (no helper; indexer owns freshness)");
-    else
-        log("qmd: skipped (helper missing)");
-    const meshMessage = workMeshSessionEnd(root);
-    if (meshMessage)
-        log(meshMessage);
-    else
-        log("work-mesh-session-end: skipped (no session id)");
-    if (fs.existsSync(path.join(root, "core/scripts/worktree-gc.sh"))) {
-        const script = path.join(root, "core/scripts/worktree-gc.sh");
-        const pid = spawnBashDetached(script, ["--apply", "--gated"], root, root, path.join(logDir, "worktree-gc.log"));
-        if (pid !== undefined)
-            log(`worktree-gc: launched PID ${pid} (--apply --gated)`);
-        else
-            log("worktree-gc: launched PID 0 (--apply --gated)");
-    }
-    else
-        log("worktree-gc: skipped (script absent)");
-    log("handoff-post complete");
-    return { code: 0, stdout: "", stderr: "" };
-}
-function withRootEnvironment(root, action) {
-    const saved = new Map();
-    for (const key of ["HQ_ROOT", "CLAUDE_PROJECT_DIR", "PWD"])
-        saved.set(key, process.env[key]);
-    process.env.HQ_ROOT = root;
-    process.env.CLAUDE_PROJECT_DIR = root;
-    process.env.PWD = root;
-    try {
-        return action();
-    }
-    finally {
-        for (const [key, value] of saved) {
-            if (value === undefined)
-                delete process.env[key];
-            else
-                process.env[key] = value;
-        }
-    }
-}
-function emitResult(result) {
-    if (result.stdout)
-        process.stdout.write(result.stdout);
-    if (result.stderr)
-        process.stderr.write(result.stderr);
-    if (result.code !== 0)
-        process.exit(result.code);
-}
-/** Fast-entry adapter; the shared family flag is resolved before this module loads. */
-export async function runHandoffFast(args, _stdin, _cwd, hqRoot, commandName) {
-    const liveRoot = hqRoot ?? resolveLiveRoot();
-    const context = { root: liveRoot, cwd: liveRoot };
-    const result = await withRootEnvironment(liveRoot, () => {
-        if (commandName === "finalize")
-            return runHandoffFinalize([...args], context);
-        if (commandName === "post")
-            return runHandoffPost([...args], context);
-        return runHandoffOpenSteps([...args], context);
-    });
-    if (result.stdout)
-        process.stdout.write(result.stdout);
-    if (result.stderr)
-        process.stderr.write(result.stderr);
-    if (result.code !== 0)
-        process.exitCode = result.code;
-    return result.code;
-}
-/** Register native handoff commands behind the shared default-off flag. */
-export function registerCoreHandoffCommand(core) {
-    const handoff = core.command("handoff").description("Handoff session helpers");
-    const names = ["finalize", "post", "open-steps"];
-    for (const name of names) {
-        const command = handoff.command(name)
-            .description(name === "open-steps" ? DESCRIPTIONS.openSteps : DESCRIPTIONS[name])
-            .allowUnknownOption()
-            .allowExcessArguments()
-            .helpOption(false)
-            .argument("[args...]", "arguments accepted for shell ABI compatibility")
-            .action(async (args = [], _options, cmd) => {
-            const scope = core.opts();
-            const root = resolveLiveRoot({ hqRoot: scope.hqRoot });
-            const operands = cmd.args.length > 0 ? cmd.args : args;
-            const { coreNativeHandoffEnabled } = await import("./core-native-handoff-flag.js");
-            if (!await coreNativeHandoffEnabled()) {
-                const bundled = runBundledScript({ asset: ASSETS[name === "open-steps" ? "openSteps" : name], args: operands, cwd: root, hqRoot: root });
-                if (bundled.code !== 0)
-                    process.exit(bundled.code);
-                return;
-            }
-            const result = withRootEnvironment(root, () => {
-                const context = { root, cwd: root };
-                if (name === "finalize")
-                    return runHandoffFinalize(operands, context);
-                if (name === "post")
-                    return runHandoffPost(operands, context);
-                return runHandoffOpenSteps(operands, context);
-            });
-            emitResult(await result);
-        });
-        const asset = ASSETS[name === "open-steps" ? "openSteps" : name];
-        describeCoreCommand(command, { execution: "native", asset, root: "live" });
-    }
-}
-//# sourceMappingURL=core-handoff.js.map