@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/core-handoff.js

@@ -0,0 +1,1144 @@
+/** 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