@davesheffer/hunch 1.38.0 → 1.39.0

package/dist/extractors/workspaces.js

@@ -0,0 +1,350 @@
+/**
+ * Workspace snapshot — THIS machine's worktrees and local branches, read from git with a
+ * fixed set of commands (docs/workspace-ledger.md). Deterministic, no LLM, no network
+ * unless `fetch` is explicitly requested.
+ *
+ * Every git invocation here uses execFileSync with a literal argv (never a shell), passes
+ * refs after `--end-of-options` / `--`, runs under `foreignRepoEnv` (so a hook's GIT_DIR
+ * cannot redirect a per-worktree query), and has a timeout. Paths come from
+ * `git worktree list` on this machine only — never from a stored record.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { foreignRepoEnv, gitCommonDir, mainWorktreeRoot, stableRepositoryName } from "./git.js";
+import { extracted } from "../core/types.js";
+import { MAX_BRANCHES, MAX_WORKTREES, WORKSPACE_SCHEMA_VERSION, WorkspaceSchema, isSafeBranchName, workspaceId, worktreeId, } from "../core/workspace.js";
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MAX_OUTPUT = 64 * 1024 * 1024;
+/** How far back in the default branch a squash-merge is searched for. */
+export const DEFAULT_SQUASH_SEARCH_COMMITS = 2000;
+function env() {
+    return foreignRepoEnv(process.env);
+}
+function run(cwd, args, timeout = 10_000) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: MAX_OUTPUT, env: env(), timeout, stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return null;
+    }
+}
+/** Exit status of a git predicate: 0 → true, 1 → false, anything else (git missing,
+ *  timeout, fatal) → null. Never collapse "no" and "error" (the CommitRepairStatus rule). */
+function predicate(cwd, args) {
+    const r = spawnSync("git", args, { cwd, env: env(), timeout: 10_000, stdio: "ignore" });
+    if (r.error || r.status === null)
+        return null;
+    if (r.status === 0)
+        return true;
+    return r.status === 1 ? false : null;
+}
+function sha(value) {
+    const v = value?.trim() ?? "";
+    return SHA.test(v) ? v : null;
+}
+function iso(value) {
+    const v = value?.trim() ?? "";
+    if (!v || !Number.isFinite(Date.parse(v)))
+        return null;
+    return new Date(v).toISOString();
+}
+/** origin/HEAD → origin/main|master → local main|master. Null when none resolves: every
+ *  verdict is then `unknown`, never `unmerged`. */
+function defaultBranch(root) {
+    const candidates = [];
+    const symbolic = run(root, ["symbolic-ref", "-q", "refs/remotes/origin/HEAD"])?.trim();
+    if (symbolic?.startsWith("refs/remotes/origin/")) {
+        const name = symbolic.slice("refs/remotes/origin/".length);
+        candidates.push({ name, ref: `origin/${name}`, full: symbolic });
+    }
+    for (const name of ["main", "master"]) {
+        candidates.push({ name, ref: `origin/${name}`, full: `refs/remotes/origin/${name}` });
+    }
+    for (const name of ["main", "master"])
+        candidates.push({ name, ref: name, full: `refs/heads/${name}` });
+    for (const c of candidates) {
+        if (!isSafeBranchName(c.name))
+            continue;
+        const head = sha(run(root, ["rev-parse", "--verify", "-q", "--end-of-options", `${c.full}^{commit}`]));
+        if (head)
+            return { name: c.name, ref: c.ref, head };
+    }
+    return null;
+}
+function listWorktrees(root) {
+    const out = run(root, ["worktree", "list", "--porcelain"]) ?? "";
+    const items = [];
+    let cur = null;
+    const flush = () => {
+        if (cur?.path && cur.head)
+            items.push({ path: cur.path, head: cur.head, branch: cur.branch ?? null, locked: !!cur.locked, prunable: !!cur.prunable, bare: !!cur.bare });
+        cur = null;
+    };
+    for (const line of out.split("\n")) {
+        if (!line.trim()) {
+            flush();
+            continue;
+        }
+        if (line.startsWith("worktree ")) {
+            flush();
+            cur = { path: line.slice(9) };
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (line.startsWith("HEAD "))
+            cur.head = sha(line.slice(5)) ?? undefined;
+        else if (line.startsWith("branch refs/heads/")) {
+            const b = line.slice("branch refs/heads/".length);
+            cur.branch = isSafeBranchName(b) ? b : null;
+        }
+        else if (line === "detached")
+            cur.branch = null;
+        else if (line === "locked" || line.startsWith("locked "))
+            cur.locked = true;
+        else if (line === "prunable" || line.startsWith("prunable "))
+            cur.prunable = true;
+        else if (line === "bare")
+            cur.bare = true;
+    }
+    flush();
+    return items.filter((w) => !w.bare);
+}
+/** `git status --porcelain` is non-empty → uncommitted or untracked work that
+ *  `git worktree remove` would refuse to discard. null when the path is gone. */
+function isDirty(path) {
+    if (!existsSync(path))
+        return null;
+    const out = run(path, ["status", "--porcelain", "--ignore-submodules"]);
+    return out === null ? null : out.trim().length > 0;
+}
+function listBranches(root) {
+    const format = ["%(refname)", "%(objectname)", "%(upstream)", "%(upstream:track,nobracket)", "%(committerdate:iso-strict)", "%(worktreepath)"].join("%00");
+    const out = run(root, ["for-each-ref", `--format=${format}`, "refs/heads/"]) ?? "";
+    const items = [];
+    let skipped = 0;
+    for (const line of out.split("\n")) {
+        if (!line)
+            continue;
+        const [refname = "", objectname = "", upstream = "", track = "", date = "", worktreePath = ""] = line.split("\0");
+        if (!refname.startsWith("refs/heads/"))
+            continue;
+        const name = refname.slice("refs/heads/".length);
+        const head = sha(objectname);
+        if (!head)
+            continue;
+        // git will create `refs/heads/-x` through update-ref even though check-ref-format
+        // --branch refuses it; such a name is never recorded, and the omission is stated.
+        if (!isSafeBranchName(name)) {
+            skipped++;
+            continue;
+        }
+        const up = upstream.startsWith("refs/remotes/") ? upstream.slice("refs/remotes/".length) : null;
+        items.push({ name, head, upstream: up, track, date: iso(date), worktreePath: worktreePath || null });
+    }
+    return { branches: items, skipped };
+}
+/** Newest first (by commit date, then name), so a truncated record keeps the branches
+ *  someone is most likely to ask about. */
+function newestFirst(items) {
+    const stamp = (x) => x.date ?? x.last_commit_at ?? "";
+    const key = (x) => x.name ?? x.path ?? "";
+    return [...items].sort((a, b) => stamp(b).localeCompare(stamp(a)) || key(a).localeCompare(key(b)));
+}
+function parseTrack(track) {
+    if (track.trim() === "gone")
+        return { gone: true, ahead: null, behind: null };
+    const ahead = /ahead (\d+)/.exec(track);
+    const behind = /behind (\d+)/.exec(track);
+    return { gone: false, ahead: ahead ? Number(ahead[1]) : 0, behind: behind ? Number(behind[1]) : 0 };
+}
+/** patch-id of the whole diff between two commits: what a squash-merge lands as one commit. */
+function combinedPatchId(root, base, head) {
+    let diff;
+    try {
+        diff = execFileSync("git", ["diff", "--binary", "--full-index", "--no-renames", "--no-ext-diff", "--no-textconv", base, head, "--"], { cwd: root, env: env(), maxBuffer: MAX_OUTPUT, timeout: 15_000, stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return null;
+    }
+    if (!diff.byteLength)
+        return null;
+    const r = spawnSync("git", ["patch-id", "--stable"], { cwd: root, env: env(), input: diff, encoding: "utf8", maxBuffer: MAX_OUTPUT, timeout: 15_000 });
+    if (r.error || r.status !== 0)
+        return null;
+    const id = r.stdout.trim().split(/\s+/)[0] ?? "";
+    return SHA.test(id) ? id : null;
+}
+/** patch-id → commit for a range, via one `git log -p | git patch-id` pipeline. `ok: false`
+ *  means the pipeline failed or overflowed — the caller says so instead of pretending the
+ *  search happened. */
+function patchIdsOf(root, range, limit, timeout) {
+    const map = new Map();
+    let log;
+    try {
+        log = execFileSync("git", ["log", "--format=%H", "-p", "--no-merges", "--binary", "--full-index", "--no-renames", "--no-ext-diff", "--no-textconv", ...(limit ? [`-n${limit}`] : []), ...range, "--"], { cwd: root, env: env(), maxBuffer: MAX_OUTPUT, timeout, stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return { map, ok: false };
+    }
+    if (!log.byteLength)
+        return { map, ok: true };
+    const r = spawnSync("git", ["patch-id", "--stable"], { cwd: root, env: env(), input: log, encoding: "utf8", maxBuffer: MAX_OUTPUT, timeout });
+    if (r.error || r.status !== 0)
+        return { map, ok: false };
+    for (const line of r.stdout.split("\n")) {
+        const [patchId = "", commit = ""] = line.trim().split(/\s+/);
+        if (SHA.test(patchId) && SHA.test(commit) && !map.has(patchId))
+            map.set(patchId, commit);
+    }
+    return { map, ok: true };
+}
+/** The pull request a MERGE COMMIT names for this branch, from the local commit subject
+ *  GitHub/GitLab write ("Merge pull request #N from owner/branch"). Bounded scan, JS-side
+ *  matching (no branch name reaches git), never a forge request. */
+function prFromMergeCommits(root, branch, range) {
+    const out = run(root, ["log", "--merges", "--format=%s", "-n500", range, "--"]) ?? "";
+    for (const subject of out.split("\n")) {
+        const m = /^Merge pull request #(\d{1,9}) from [^/\s]+\/(\S+)$/.exec(subject.trim());
+        if (m && m[2] === branch)
+            return Number(m[1]);
+    }
+    return undefined;
+}
+/** The pull request a SQUASH COMMIT names ("Title (#N)"). */
+function prFromSquashCommit(root, commit) {
+    const subject = run(root, ["log", "-1", "--format=%s", "--end-of-options", commit, "--"])?.trim() ?? "";
+    const m = /\(#(\d{1,9})\)$/.exec(subject);
+    return m ? Number(m[1]) : undefined;
+}
+function withPr(verdict, pr) {
+    return pr === undefined ? verdict : { ...verdict, pr, evidence: [...verdict.evidence, `pull request #${pr} (from the local commit subject)`] };
+}
+function mergedVerdict(root, name, head, def, patchIds, searched) {
+    if (!def)
+        return { status: "unknown", method: null, evidence: ["no default branch resolved (origin/HEAD, origin/main, origin/master, main, master)"] };
+    const ancestor = predicate(root, ["merge-base", "--is-ancestor", head, def.head]);
+    if (ancestor === null)
+        return { status: "unknown", method: null, evidence: ["git merge-base failed"] };
+    if (ancestor) {
+        const verdict = { status: "merged", method: "ancestry", evidence: [`${head.slice(0, 12)} is an ancestor of ${def.ref}@${def.head.slice(0, 12)}`] };
+        return withPr(verdict, prFromMergeCommits(root, name, `${head}..${def.head}`));
+    }
+    const base = sha(run(root, ["merge-base", head, def.head]));
+    if (!base)
+        return { status: "unknown", method: null, evidence: [`no merge base with ${def.ref}`] };
+    const known = patchIds();
+    if (!known.ok) {
+        return { status: "unmerged", method: null, evidence: [`not an ancestor of ${def.ref}@${def.head.slice(0, 12)}; squash/rebase search unavailable (default-branch history too large or git failed)`] };
+    }
+    const combined = combinedPatchId(root, base, head);
+    if (combined) {
+        const commit = known.map.get(combined);
+        if (commit) {
+            const verdict = { status: "merged", method: "squash", evidence: [`patch-id of ${base.slice(0, 12)}..${head.slice(0, 12)} equals ${def.ref} commit ${commit.slice(0, 12)}`] };
+            return withPr(verdict, prFromSquashCommit(root, commit));
+        }
+    }
+    // Rebase / cherry-pick: every commit of the branch has a patch-equivalent commit in the
+    // default branch. Uses the one-time map instead of `git cherry`, whose cost grows with
+    // the default branch's history for EVERY branch checked.
+    const own = patchIdsOf(root, [`${base}..${head}`], null, 30_000);
+    if (own.ok && own.map.size && [...own.map.keys()].every((id) => known.map.has(id))) {
+        return { status: "merged", method: "rebase", evidence: [`all ${own.map.size} commit(s) have a patch-equivalent commit in ${def.ref} (last ${searched} searched)`] };
+    }
+    return { status: "unmerged", method: null, evidence: [`not in ${def.ref}@${def.head.slice(0, 12)}; squash/rebase searched last ${searched} commits`] };
+}
+function realpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function fetchedAt(root) {
+    const common = gitCommonDir(root);
+    if (!common)
+        return null;
+    try {
+        return statSync(join(common, "FETCH_HEAD")).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+/** Snapshot this machine's workspace for the repository at `root`. Validated against the
+ *  strict schema before it is returned, so the extractor can never emit a record the
+ *  loader would refuse. */
+export function snapshotWorkspace(root, opts) {
+    const now = opts.now ?? new Date();
+    const main = mainWorktreeRoot(root);
+    if (opts.fetch)
+        run(main, ["fetch", "--prune", "--quiet"], 120_000);
+    const def = defaultBranch(main);
+    const searched = opts.squashSearchCommits ?? DEFAULT_SQUASH_SEARCH_COMMITS;
+    let patchIds = null;
+    const lazyPatchIds = () => (patchIds ??= def ? patchIdsOf(main, [def.head], searched, 60_000) : { map: new Map(), ok: true });
+    const notes = [];
+    const allWorktrees = listWorktrees(main).map((w) => ({ ...w, date: iso(run(main, ["log", "-1", "--format=%cI", "--end-of-options", w.head, "--"])) }));
+    const rawWorktrees = allWorktrees.length > MAX_WORKTREES ? newestFirst(allWorktrees).slice(0, MAX_WORKTREES) : allWorktrees;
+    if (rawWorktrees.length < allWorktrees.length)
+        notes.push(`truncated: ${allWorktrees.length - rawWorktrees.length} older worktree(s) omitted (record holds ${MAX_WORKTREES})`);
+    const mainReal = realpath(main);
+    const worktrees = rawWorktrees.map((w) => ({
+        id: worktreeId(w.path),
+        path: opts.publish === "full" ? w.path : null,
+        branch: w.branch,
+        head: w.head,
+        is_main: realpath(w.path) === mainReal,
+        dirty: w.prunable ? null : isDirty(w.path),
+        locked: w.locked,
+        prunable: w.prunable,
+        last_commit_at: w.date,
+    }));
+    const worktreeByPath = new Map(rawWorktrees.map((w) => [w.path, worktreeId(w.path)]));
+    const listed = listBranches(main);
+    if (listed.skipped)
+        notes.push(`skipped: ${listed.skipped} branch name(s) git would refuse as a branch argument`);
+    const maxBranches = Math.min(MAX_BRANCHES, Math.max(1, opts.maxBranches ?? MAX_BRANCHES));
+    const rawBranches = listed.branches.length > maxBranches ? newestFirst(listed.branches).slice(0, maxBranches) : listed.branches;
+    if (rawBranches.length < listed.branches.length)
+        notes.push(`truncated: ${listed.branches.length - rawBranches.length} older branch(es) omitted (record holds ${maxBranches})`);
+    const branches = rawBranches.map((b) => {
+        const track = b.upstream ? parseTrack(b.track) : { gone: false, ahead: null, behind: null };
+        return {
+            name: b.name,
+            head: b.head,
+            is_default: def?.name === b.name,
+            upstream: b.upstream,
+            upstream_gone: track.gone,
+            ahead: track.ahead,
+            behind: track.behind,
+            last_commit_at: b.date,
+            worktree: (b.worktreePath && worktreeByPath.get(b.worktreePath)) || null,
+            merged: def?.name === b.name
+                ? { status: "unmerged", method: null, evidence: ["default branch"] }
+                : mergedVerdict(main, b.name, b.head, def, lazyPatchIds, searched),
+        };
+    });
+    const record = {
+        schema: WORKSPACE_SCHEMA_VERSION,
+        id: workspaceId(opts.machine.id),
+        machine: { id: opts.machine.id, label: opts.machine.label, platform: process.platform },
+        repository: stableRepositoryName(main),
+        publish: opts.publish,
+        observed_at: now.toISOString(),
+        fetched_at: fetchedAt(main),
+        default_branch: def,
+        worktrees,
+        branches,
+        provenance: extracted(1, [
+            "git worktree list --porcelain", "git for-each-ref refs/heads/", "git status --porcelain",
+            "git merge-base --is-ancestor", "git diff | git patch-id --stable", "git log -p | git patch-id --stable",
+            ...notes,
+        ]),
+    };
+    return WorkspaceSchema.parse(record);
+}
+//# sourceMappingURL=workspaces.js.map

package/dist/integrations/claudemd.js

@@ -51,6 +51,7 @@ export function renderHunchSection(store, root) {
     lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
     lines.push("- `hunch_context(target, task_id)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST** for memory. Include the current task ID on each context call so its contribution is inspectable.");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
+    lines.push("- `hunch_workspaces(view?)` — which worktrees and branches are open on which machine, what is merged and deletable (read-only; this machine live, others from memory). Call it instead of `git branch` / `git worktree list`; never delete on its say-so.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");
     lines.push("- `hunch_escalations()` — the decisions only the HUMAN can make (including one exact imported ADR at a time, topic conflicts, and policy calls). Normally empty; when it isn't, ASK the user inline — an entry is a question, silence is never approval. Apply an ADR answer only through `hunch_review_imported_adr` with its printed source and review hashes.");
     lines.push("- `hunch now` (CLI) — recent decisions + the live roadmap; `hunch log` — the memory-move timeline (every capture/adopt/supersede/prune/repair, each revertable).");

package/dist/integrations/hooks.d.ts

@@ -28,6 +28,7 @@ export declare function installPreCommitHook(root: string, invocation: string, s
  *  a repo carrying only one half (an older install, or a hand-edited hook)
  *  gets the other appended rather than clobbered. */
 export declare function installPostMergeHook(root: string, invocation: string): HookInstall;
+export declare function installPostCheckoutHook(root: string, invocation: string): HookInstall;
 /** Read-only diagnostic (used by `hunch doctor`): which of the three managed
  *  hooks are currently present. Never writes anything — a hook counts as
  *  installed if its managed marker is present, regardless of whether the
@@ -38,4 +39,5 @@ export declare function hookStatus(root: string): {
     postCommit: boolean;
     preCommit: boolean;
     postMerge: boolean;
+    postCheckout: boolean;
 };

package/dist/integrations/hooks.js

@@ -25,6 +25,12 @@ function block(invocation, opts = {}) {
         // team policy, so only the explicit local-only mode forces deterministic.
         ...(opts.localOnly ? ["  export HUNCH_SYNTH_PROVIDER=deterministic"] : []),
         `  ( ${invocation} sync --from-hook --quiet${priv}${commit} >/dev/null 2>&1 || true ) &`,
+        // Deliberately NO workspace-ledger snapshot here (docs/workspace-ledger.md): a commit
+        // changes HEAD, not which branches and worktrees exist — post-checkout covers that, and
+        // a ledger read publishes a fresh observation when someone actually asks. Snapshotting
+        // per commit would add git work (up to a patch-id walk) to the most frequent operation
+        // there is, and its backgrounded child outliving `git commit` is what held a Windows
+        // clone directory open and broke team-matrix-e2e's teardown with EBUSY.
         "fi",
         ENDMARK,
     ].join("\n");
@@ -141,6 +147,24 @@ export function installPostMergeHook(root, invocation) {
     const repair = installManagedBlock(root, "post-merge", REPAIR_MERGE_MARK, REPAIR_MERGE_END, repairProvenanceMergeBlock(invocation));
     return ACTION_RANK[repair.action] >= ACTION_RANK[grounding.action] ? repair : grounding;
 }
+const CHECKOUT_MARK = "# >>> hunch post-checkout (workspace ledger) >>>";
+const CHECKOUT_END = "# <<< hunch post-checkout (workspace ledger) <<<";
+/** post-checkout is where branches and worktrees actually change (`git checkout`,
+ *  `git switch`, `git worktree add`). git passes `$3 = 1` for a branch checkout and `0`
+ *  for a file checkout; only the former can change the ledger. Constant argv (nothing
+ *  from repository content), HUNCH_SYNC-guarded, backgrounded, offline. */
+function checkoutBlock(invocation) {
+    return [
+        CHECKOUT_MARK,
+        'if [ -z "$HUNCH_SYNC" ] && [ "$3" = "1" ]; then',
+        `  ( HUNCH_SYNC=1 ${invocation} workspaces snapshot --quiet >/dev/null 2>&1 || true ) &`,
+        "fi",
+        CHECKOUT_END,
+    ].join("\n");
+}
+export function installPostCheckoutHook(root, invocation) {
+    return installManagedBlock(root, "post-checkout", CHECKOUT_MARK, CHECKOUT_END, checkoutBlock(invocation));
+}
 /** Read-only diagnostic (used by `hunch doctor`): which of the three managed
  *  hooks are currently present. Never writes anything — a hook counts as
  *  installed if its managed marker is present, regardless of whether the
@@ -162,6 +186,7 @@ export function hookStatus(root) {
         postCommit: has("post-commit", MARK),
         preCommit: has("pre-commit", PRE_MARK),
         postMerge: has("post-merge", GROUNDING_MERGE_MARK) && has("post-merge", REPAIR_MERGE_MARK),
+        postCheckout: has("post-checkout", CHECKOUT_MARK),
     };
 }
 //# sourceMappingURL=hooks.js.map

package/dist/integrations/scaffold.js

@@ -83,6 +83,16 @@ Capture the decision for **$ARGUMENTS** into Hunch's graph.
 5. Commit with \`hunch_record_decision\`, passing \`capture_token\` (from step 1) and the confirmed \`topic\`. The artifact is the graph write, not prose.
 6. On CONFLICT for the topic, do NOT auto-supersede — Hunch refuses and presents both; let me choose supersede (link) / split the topic / discard.
 `;
+const WORKTREES_CMD = `---
+description: Which worktrees and branches are open on which machine, what is merged and deletable — from Hunch's workspace ledger, not from git spelunking
+---
+Answer **$ARGUMENTS** (default: "what is open, and what can I delete?") from the workspace ledger.
+
+1. Call \`hunch_workspaces(view: "branches")\` (and \`view: "inventory"\` for the worktree list). Do NOT run \`git branch\`, \`git worktree list\` or \`git log\` yourself — the tool already read this machine live and every other machine from memory.
+2. Report the rows as they are: MACHINES, WORKTREE (dirty), UPSTREAM, MERGED (with its method) and the ACTION column. A verdict of \`unknown\` or a machine marked \`unverified\` is reported as such, never upgraded to a guess.
+3. Recommend only what the ACTION column says. You never delete a branch or remove a worktree from this command; the human runs the printed git commands (or \`hunch workspaces prune\` when it ships) on the machine that holds them.
+4. If a machine is missing or stale, say so: it has not run \`hunch workspaces snapshot\` (the post-checkout hook / MCP session start does this) or it is not sharing an overlay.
+`;
 const AUDIT_CMD = `---
 description: Run an audit and record what it finds into Hunch as findings (observed gaps, no code change)
 ---
@@ -232,6 +242,7 @@ export function writeSlashCommands(root) {
         ["capture.md", CAPTURE_CMD],
         ["heal.md", HEAL_CMD],
         ["audit.md", AUDIT_CMD],
+        ["worktrees.md", WORKTREES_CMD],
     ];
     for (const [name, body] of files) {
         const p = join(dir, name);

package/dist/integrations/workspaceLedger.d.ts

@@ -0,0 +1,73 @@
+import { type WorkspacesConfig } from "../core/config.js";
+import { type MachineIdentity } from "../core/machine.js";
+import { branchRows, worktreeRows, type BranchRow, type PrunePlan, type PruneStep, type Workspace, type WorktreeRow } from "../core/workspace.js";
+import type { HunchStore } from "../store/hunchStore.js";
+export interface LedgerView {
+    machine: MachineIdentity;
+    /** This machine, live (paths included; never written). */
+    live: Workspace;
+    /** live + every OTHER machine's stored record. */
+    records: Workspace[];
+    config: WorkspacesConfig;
+}
+export declare function workspaceLedgerView(store: HunchStore, root: string, opts?: {
+    fetch?: boolean;
+}): LedgerView;
+export type SnapshotOutcome = {
+    status: "off";
+} | {
+    status: "dry-run";
+    record: Workspace;
+} | {
+    status: "no-home";
+    record: Workspace;
+} | {
+    status: "unchanged";
+    record: Workspace;
+    previous: Workspace;
+}
+/** The OTHER memory home already holds a record with this machine's id (an old public
+ *  copy, or a record someone else wrote under this id): the store refuses a twin, and so
+ *  do we — `hunch workspaces forget <id>` removes the stale copy. */
+ | {
+    status: "collision";
+    record: Workspace;
+    reason: string;
+} | {
+    status: "written";
+    record: Workspace;
+    home: "private" | "public";
+    flushed: "pushed" | "committed" | null;
+};
+/** Record this machine's snapshot. Honors `workspaces.publish`, skips a write when the
+ *  content is unchanged and the stored record is under a day old (an idle machine's hooks
+ *  must not commit a record per checkout), and reports exactly what happened. */
+export declare function recordWorkspaceSnapshot(store: HunchStore, root: string, opts?: {
+    fetch?: boolean;
+    dryRun?: boolean;
+    live?: Workspace;
+}): SnapshotOutcome;
+/** Whether a snapshot could land anywhere on this root — used to skip work that would
+ *  write nothing. */
+export declare function snapshotHasHome(store: HunchStore, root: string): boolean;
+export declare function padTable(header: string[], rows: string[][]): string;
+export declare function renderWorktreeTable(view: LedgerView, rows: WorktreeRow[], now?: Date): string;
+export declare function describeUpstream(r: BranchRow): string;
+export declare function renderBranchTable(view: LedgerView, rows: BranchRow[]): string;
+/** One line for `hunch now` / `hunch_now`, from STORED records only (no git, so the hot
+ *  view stays fast); null when memory holds no workspace record. */
+export declare function workspaceSummaryLine(records: readonly Workspace[], config: WorkspacesConfig, now?: Date): string | null;
+export { branchRows, worktreeRows };
+export declare function prunePlanFor(view: LedgerView): PrunePlan;
+export interface PruneResult {
+    step: PruneStep;
+    outcome: "deleted" | "failed";
+    detail: string;
+}
+/** Execute the local steps of a plan. Each command is a fixed argv; the branch name was
+ *  validated by the record schema and is passed after `--`; the worktree path comes from
+ *  `git worktree list` on this machine. A failure stops that step, never the others. */
+export declare function applyPrune(root: string, steps: readonly PruneStep[]): PruneResult[];
+/** Interactive yes/no; false when stdin is not a terminal (the caller then needs --yes). */
+export declare function confirmPrune(question: string): Promise<boolean>;
+export declare function renderPrunePlan(view: LedgerView, plan: PrunePlan): string;