@davesheffer/hunch 1.38.0 → 1.39.0

package/dist/core/taskReportHook.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { findRoot } from "./paths.js";
 import { canonicalReportRoot } from "./taskReportPaths.js";
 import { isCredentialFreeText } from "./types.js";
-import { continuationLinks, finishReportTask, isEmptyTaskReport, latestSessionTask, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, startReportTask } from "./taskReport.js";
+import { aliasReportTask, continuationLinks, finishReportTask, isEmptyTaskReport, latestSessionTask, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, resolveReportTask, settleSessionTasks, startReportTask } from "./taskReport.js";
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
 import { renderTaskReport } from "./taskReportRender.js";
 /** The exact task identity a native host prompt maps to. */
@@ -73,7 +73,14 @@ function identity(root, provider, event) {
         return null;
     if (!event.prompt_id)
         return "legacy";
-    return promptTaskId(root, event.session_id, event.prompt_id, event.agent_id ?? null, provider);
+    const id = promptTaskId(root, event.session_id, event.prompt_id, event.agent_id ?? null, provider);
+    // A notification turn reports to the task it continued (an explicit alias).
+    try {
+        return resolveReportTask(root, id);
+    }
+    catch {
+        return id;
+    }
 }
 export function hookReportTaskId(root, provider, event) {
     try {
@@ -103,11 +110,19 @@ export function startHookReport(root, provider, event) {
     // the episode's graph record is written under the first task's id. The key
     // is a hash; the host session identifier itself is still never retained.
     let links = {};
-    if (event.session_id) {
-        const sessionKey = reportHash([cwd, provider, event.session_id, event.agent_id ?? null]);
+    const sessionKey = hookSessionKey(cwd, provider, event);
+    if (sessionKey) {
         links = { session_key: sessionKey };
         try {
             const previous = latestSessionTask(root, sessionKey);
+            // A host notification (a background command finished) is not new work:
+            // it continues the session's latest task instead of opening an empty row,
+            // unless the agent already closed that task for good. The alias makes
+            // this prompt's Stop and hook observations report to that task.
+            if (previous && previous.task_id !== id && isNotificationPrompt(event.prompt) && previous.closed_by !== "agent") {
+                aliasReportTask(root, id, previous.task_id);
+                return taskInstruction(previous, cwdLiteral);
+            }
             const continued = previous && previous.task_id !== id ? continuationLinks(previous) : null;
             if (continued)
                 links = { ...links, ...continued };
@@ -127,8 +142,41 @@ export function startHookReport(root, provider, event) {
             throw error;
         task = existing;
     }
+    return taskInstruction(task, cwdLiteral);
+}
+function taskInstruction(task, cwdLiteral) {
     return `Hunch has opened this prompt's report: ${task.task_id}. Reuse this exact ID for this prompt. Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv; do not create another report. Pass this task_id and cwd: ${cwdLiteral} to hunch_context and decision/correction/finding captures, and pass the same cwd when finishing with hunch_task before responding. A host Stop notice will show the evidence even if no task-linked memory was observed.`;
 }
+/** The session key a hook event maps to: a hash of (root, provider, session,
+ * agent), never the identifier itself. Null without a host session. */
+function hookSessionKey(cwd, provider, event) {
+    return event.session_id ? reportHash([cwd, provider, event.session_id, event.agent_id ?? null]) : null;
+}
+/** A prompt the host generated to report a background command's completion,
+ * not something the user typed. */
+export function isNotificationPrompt(prompt) {
+    if (typeof prompt !== "string")
+        return false;
+    const firstLine = prompt.split(/\r?\n/).map(l => l.trim()).find(l => l.length > 0) ?? "";
+    return /^<task-notification>/i.test(firstLine);
+}
+/** Close, as host closes, the tasks of this session that an earlier prompt left
+ * open: the prompt was interrupted before its Stop, or a late observation
+ * reopened its task. Called when a new prompt starts (`keepNewest`: the new
+ * task, or the task a notification turn continues, stays open) and when the
+ * current prompt stops. Returns the ids closed here for the caller to persist. */
+export function settleHookSession(root, provider, event, options = {}) {
+    const cwd = nativeHookCwd(root, provider, event);
+    const key = cwd ? hookSessionKey(cwd, provider, event) : null;
+    if (!key)
+        return [];
+    try {
+        return settleSessionTasks(root, key, options);
+    }
+    catch {
+        return [];
+    }
+}
 /** Stop ends the turn, so the prompt's task closes here as a HOST close: the
  * ledger says the task completed even when the agent never called finish, and
  * a task with observations becomes a graph record without anyone's cooperation.
@@ -136,30 +184,34 @@ export function startHookReport(root, provider, event) {
  * continuation: the next observation reopens the task and the following Stop
  * closes it again (the record is refreshed from the report). An explicit agent
  * finish with any outcome overrides a host close. Pending verification keeps
- * the task open. Returns the task id when the task is closed after this call,
- * so the caller can persist its record; null when nothing is closed. */
+ * the task open. Tasks an earlier prompt of the session left open close here
+ * too. Returns the ids of the tasks closed after this call, so the caller can
+ * persist their records; empty when nothing is closed. */
 export function closeHookTask(root, provider, event) {
     let id;
     try {
         id = identity(root, provider, event);
     }
     catch {
-        return null;
+        return [];
     }
     if (!id || id === "legacy")
-        return null;
+        return [];
+    const closed = [];
     try {
         const task = readTaskReport(root, id).task;
-        if (task.state === "interrupted")
-            return null;
         if (task.state === "open")
             finishReportTask(root, id, "completed", { by: "host" });
-        return id;
+        if (task.state !== "interrupted")
+            closed.push(id);
     }
     catch {
-        // No task for this prompt, or verification still running: leave it as it is.
-        return null;
+        // No task for this prompt (a notification turn), or verification still running: leave it as it is.
     }
+    for (const other of settleHookSession(root, provider, event, { keepId: id }))
+        if (!closed.includes(other))
+            closed.push(other);
+    return closed;
 }
 /** A presentation notice never denies Stop or injects another model turn.
  * A prompt with no observation at all prints nothing: the empty task row stays

package/dist/core/taskTouched.d.ts

@@ -1,5 +1,9 @@
+/** Files Hunch regenerates on every capture (src/integrations/providers.ts,
+ * claudemd.ts): a fresh mtime on them is the capture, not the task's work. */
+export declare const HUNCH_MANAGED_FILES: ReadonlySet<string>;
 export declare function gitTouchedFiles(root: string, startedAt: string, finishedAt: string | null, options?: {
     limit?: number;
     timeoutMs?: number;
     now?: number;
+    workingTree?: boolean;
 }): string[];

package/dist/core/taskTouched.js

@@ -8,15 +8,26 @@
  * never a failed finish):
  *  - commits authored by the configured git user whose commit time falls in
  *    the task window (merges excluded);
- *  - working-tree changes (modified, added, untracked) whose mtime falls in it.
- * Hunch's own memory and cache paths are excluded, so a capture commit made
- * during the task does not count as work on a file. Deleted paths are skipped:
- * nothing dates the deletion. Commit dates get one second of slack (git keeps
- * seconds); working-tree mtimes get none before the start. */
+ *  - working-tree changes (modified, added, untracked) whose mtime falls in it,
+ *    unless the caller knows another session shared the checkout (`workingTree:
+ *    false`): mtimes cannot say whose edit it was, commits can.
+ * Hunch's own work never counts as the task's: memory and cache paths, commits
+ * Hunch makes (`hunch:` subjects — captures, task records, repairs), and the
+ * grounding files a capture rewrites (CLAUDE.md, AGENTS.md, the host rule
+ * files) when they merely changed in the working tree; a user commit that
+ * edits one of those files still counts, as does a delivery that named it.
+ * Deleted paths are skipped: nothing dates the deletion. Commit dates get one
+ * second of slack (git keeps seconds); working-tree mtimes get none before
+ * the start. */
 import { execFileSync } from "node:child_process";
 import { statSync } from "node:fs";
 import { join } from "node:path";
 const EXCLUDED_SEGMENTS = new Set([".hunch", ".hunch-cache", ".git"]);
+/** Files Hunch regenerates on every capture (src/integrations/providers.ts,
+ * claudemd.ts): a fresh mtime on them is the capture, not the task's work. */
+export const HUNCH_MANAGED_FILES = new Set(["CLAUDE.md", "AGENTS.md", ".cursor/rules/hunch.mdc", ".github/copilot-instructions.md", ".windsurf/rules/hunch.md"]);
+/** Commit subjects Hunch writes itself. */
+const HUNCH_COMMIT_SUBJECT = /^hunch:/i;
 function gitDate(ms) {
     // Second resolution, a format every git accepts.
     return `${new Date(ms).toISOString().slice(0, 19).replace("T", " ")} +0000`;
@@ -38,8 +49,9 @@ export function gitTouchedFiles(root, startedAt, finishedAt, options = {}) {
             delete env[key];
     const run = (args) => execFileSync("git", ["-C", root, "-c", "core.quotePath=false", ...args], { env, encoding: "utf8", timeout, maxBuffer: 4_000_000, stdio: ["ignore", "pipe", "ignore"] });
     const out = new Set();
+    const normalize = (raw) => raw.trim().replace(/\\/g, "/").replace(/^\.\//, "");
     const keep = (raw) => {
-        const path = raw.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+        const path = normalize(raw);
         if (!path || path.split("/").some((segment) => EXCLUDED_SEGMENTS.has(segment)))
             return;
         out.add(path);
@@ -47,12 +59,20 @@ export function gitTouchedFiles(root, startedAt, finishedAt, options = {}) {
     try {
         const email = run(["config", "--get", "user.email"]).trim();
         if (email) {
-            const log = run(["log", "--no-merges", "-n", "50", `--since=${gitDate(from)}`, `--until=${gitDate(to)}`, `--author=${email}`, "--format=", "--name-only"]);
-            for (const line of log.split("\n"))
-                keep(line);
+            // One record per commit: a separator, the subject, then the paths.
+            const log = run(["log", "--no-merges", "-n", "50", `--since=${gitDate(from)}`, `--until=${gitDate(to)}`, `--author=${email}`, "--format=%x1e%s", "--name-only"]);
+            for (const block of log.split("\x1e")) {
+                const [subject = "", ...paths] = block.split("\n");
+                if (HUNCH_COMMIT_SUBJECT.test(subject.trim()))
+                    continue;
+                for (const line of paths)
+                    keep(line);
+            }
         }
     }
     catch { /* no commits, no git user, or no git: the working tree may still say something */ }
+    if (options.workingTree === false)
+        return [...out].sort().slice(0, limit);
     try {
         const entries = run(["status", "--porcelain=v1", "-z", "--untracked-files=all"]).split("\0").filter(Boolean);
         for (let i = 0; i < entries.length; i++) {
@@ -61,7 +81,7 @@ export function gitTouchedFiles(root, startedAt, finishedAt, options = {}) {
             // A rename or copy is followed by its original path as a separate entry.
             if (code[0] === "R" || code[0] === "C")
                 i++;
-            if (code.includes("D") || !path)
+            if (code.includes("D") || !path || HUNCH_MANAGED_FILES.has(normalize(path)))
                 continue;
             try {
                 const mtime = statSync(join(root, path)).mtimeMs;

package/dist/core/types.d.ts

@@ -8,6 +8,7 @@
 import { z } from "zod";
 import { ProvenanceSchema, isCredentialFreeText, type Provenance } from "./provenance.js";
 import { type Convention, type ActionReceipt, type Commitment, type DerivedState, type ExternalEntity, type StateRelationship } from "./stateRecords.js";
+import { type Workspace } from "./workspace.js";
 export { ProvenanceSchema, isCredentialFreeText };
 export type { Provenance };
 export declare const ComponentKind: z.ZodEnum<{
@@ -701,7 +702,7 @@ export declare function assertLandscapeDriftCandidate(value: unknown): asserts v
 /** Convert one valid external observation into advisory Hunch memory, never graph authority. */
 export declare function landscapeDriftCandidateFinding(value: unknown): Finding;
 /** The entity collections, keyed by their on-disk directory name. */
-export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions", "tasks"];
+export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions", "tasks", "workspaces"];
 export type EntityKind = (typeof ENTITY_KINDS)[number];
 export declare const SCHEMAS: {
     readonly components: z.ZodObject<{
@@ -1534,6 +1535,69 @@ export declare const SCHEMAS: {
             last_verified: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>;
+    readonly workspaces: z.ZodObject<{
+        schema: z.ZodLiteral<"hunch.workspace/1">;
+        id: z.ZodString;
+        machine: z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            platform: z.ZodString;
+        }, z.core.$strict>;
+        repository: z.ZodString;
+        publish: z.ZodEnum<{
+            full: "full";
+            branches: "branches";
+        }>;
+        observed_at: z.ZodString;
+        fetched_at: z.ZodNullable<z.ZodString>;
+        default_branch: z.ZodNullable<z.ZodObject<{
+            name: z.ZodString;
+            ref: z.ZodUnion<[z.ZodString, z.ZodString]>;
+            head: z.ZodString;
+        }, z.core.$strict>>;
+        worktrees: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            path: z.ZodNullable<z.ZodString>;
+            branch: z.ZodNullable<z.ZodString>;
+            head: z.ZodString;
+            is_main: z.ZodBoolean;
+            dirty: z.ZodNullable<z.ZodBoolean>;
+            locked: z.ZodBoolean;
+            prunable: z.ZodBoolean;
+            last_commit_at: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+        branches: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            head: z.ZodString;
+            is_default: z.ZodBoolean;
+            upstream: z.ZodNullable<z.ZodString>;
+            upstream_gone: z.ZodBoolean;
+            ahead: z.ZodNullable<z.ZodNumber>;
+            behind: z.ZodNullable<z.ZodNumber>;
+            last_commit_at: z.ZodNullable<z.ZodString>;
+            worktree: z.ZodNullable<z.ZodString>;
+            merged: z.ZodObject<{
+                status: z.ZodEnum<{
+                    unknown: "unknown";
+                    merged: "merged";
+                    unmerged: "unmerged";
+                }>;
+                method: z.ZodNullable<z.ZodEnum<{
+                    ancestry: "ancestry";
+                    squash: "squash";
+                    rebase: "rebase";
+                }>>;
+                evidence: z.ZodArray<z.ZodString>;
+                pr: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        provenance: z.ZodObject<{
+            source: z.ZodString;
+            confidence: z.ZodNumber;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            last_verified: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strict>;
 };
 export type EntityFor = {
     components: Component;
@@ -1552,6 +1616,7 @@ export type EntityFor = {
     entities: ExternalEntity;
     relationships: StateRelationship;
     tasks: TaskRecord;
+    workspaces: Workspace;
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export declare function extracted(confidence: number, evidence?: string[]): Provenance;

package/dist/core/types.js

@@ -11,6 +11,7 @@ import { createHash } from "node:crypto";
 import { findingId, resourceId, resourceRelationshipId } from "./ids.js";
 import { ProvenanceSchema, SENSITIVE_METADATA_KEY, isCredentialFreeText } from "./provenance.js";
 import { ConventionSchema, ActionReceiptSchema, CommitmentSchema, DerivedStateSchema, ExternalEntitySchema, StateRelationshipSchema, } from "./stateRecords.js";
+import { WorkspaceSchema } from "./workspace.js";
 // Provenance and the credential-free text check live in the leaf module ./provenance.js so
 // record schemas registered below can import them without a cycle; re-exported unchanged.
 export { ProvenanceSchema, isCredentialFreeText };
@@ -639,6 +640,7 @@ export function landscapeDriftCandidateFinding(value) {
 export const ENTITY_KINDS = [
     "components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings",
     "receipts", "commitments", "derived", "entities", "relationships", "conventions", "tasks",
+    "workspaces",
 ];
 export const SCHEMAS = {
     components: ComponentSchema,
@@ -657,6 +659,7 @@ export const SCHEMAS = {
     entities: ExternalEntitySchema,
     relationships: StateRelationshipSchema,
     tasks: TaskRecordSchema,
+    workspaces: WorkspaceSchema,
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export function extracted(confidence, evidence = []) {

package/dist/core/workspace.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Workspace ledger — one record per MACHINE per repository describing that machine's
+ * git worktrees and local branches, with deterministic merged verdicts
+ * (docs/workspace-ledger.md). A LEAF module (zod + ids + provenance only) so types.ts
+ * can register the kind without a cycle, like stateRecords.ts.
+ *
+ * Security posture, in code: the schema is `.strict()` with bounded lengths, every
+ * branch name must be a git-valid ref component, every free-text field passes the
+ * credential filter, and NOTHING here reads a record back as authority — the
+ * aggregation below produces DISPLAY rows and a recommended action; `prune --apply`
+ * (Phase 3) re-snapshots live git and never acts on a stored record.
+ */
+import { z } from "zod";
+export declare const WORKSPACE_SCHEMA_VERSION: "hunch.workspace/1";
+/** Record bounds. The extractor keeps the most recently committed entries and says so in
+ *  provenance, so a huge repository degrades to a truncated record, never to a crash. */
+export declare const MAX_WORKTREES = 512;
+export declare const MAX_BRANCHES = 4096;
+export declare const MACHINE_ID: RegExp;
+export declare const MACHINE_LABEL: RegExp;
+/** A branch name git would accept (`git check-ref-format --branch`), fail-closed: no
+ *  leading `-` (flag smuggling), no control/whitespace characters, no `..`, `@{`,
+ *  `.lock` suffix, leading/trailing `.` or `/`, and bounded length. Every real branch
+ *  from `for-each-ref` passes; a crafted record cannot smuggle an argument. */
+export declare function isSafeBranchName(name: string): boolean;
+export declare const WorkspaceWorktreeSchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodNullable<z.ZodString>;
+    branch: z.ZodNullable<z.ZodString>;
+    head: z.ZodString;
+    is_main: z.ZodBoolean;
+    dirty: z.ZodNullable<z.ZodBoolean>;
+    locked: z.ZodBoolean;
+    prunable: z.ZodBoolean;
+    last_commit_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type WorkspaceWorktree = z.infer<typeof WorkspaceWorktreeSchema>;
+export declare const MERGED_STATUSES: readonly ["merged", "unmerged", "unknown"];
+export declare const MERGED_METHODS: readonly ["ancestry", "squash", "rebase"];
+export declare const MergedVerdictSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        merged: "merged";
+        unmerged: "unmerged";
+    }>;
+    method: z.ZodNullable<z.ZodEnum<{
+        ancestry: "ancestry";
+        squash: "squash";
+        rebase: "rebase";
+    }>>;
+    evidence: z.ZodArray<z.ZodString>;
+    pr: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type MergedVerdict = z.infer<typeof MergedVerdictSchema>;
+export declare const WorkspaceBranchSchema: z.ZodObject<{
+    name: z.ZodString;
+    head: z.ZodString;
+    is_default: z.ZodBoolean;
+    upstream: z.ZodNullable<z.ZodString>;
+    upstream_gone: z.ZodBoolean;
+    ahead: z.ZodNullable<z.ZodNumber>;
+    behind: z.ZodNullable<z.ZodNumber>;
+    last_commit_at: z.ZodNullable<z.ZodString>;
+    worktree: z.ZodNullable<z.ZodString>;
+    merged: z.ZodObject<{
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            merged: "merged";
+            unmerged: "unmerged";
+        }>;
+        method: z.ZodNullable<z.ZodEnum<{
+            ancestry: "ancestry";
+            squash: "squash";
+            rebase: "rebase";
+        }>>;
+        evidence: z.ZodArray<z.ZodString>;
+        pr: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type WorkspaceBranch = z.infer<typeof WorkspaceBranchSchema>;
+export declare const WorkspaceSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"hunch.workspace/1">;
+    id: z.ZodString;
+    machine: z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        platform: z.ZodString;
+    }, z.core.$strict>;
+    repository: z.ZodString;
+    publish: z.ZodEnum<{
+        full: "full";
+        branches: "branches";
+    }>;
+    observed_at: z.ZodString;
+    fetched_at: z.ZodNullable<z.ZodString>;
+    default_branch: z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        ref: z.ZodUnion<[z.ZodString, z.ZodString]>;
+        head: z.ZodString;
+    }, z.core.$strict>>;
+    worktrees: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        branch: z.ZodNullable<z.ZodString>;
+        head: z.ZodString;
+        is_main: z.ZodBoolean;
+        dirty: z.ZodNullable<z.ZodBoolean>;
+        locked: z.ZodBoolean;
+        prunable: z.ZodBoolean;
+        last_commit_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    branches: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        head: z.ZodString;
+        is_default: z.ZodBoolean;
+        upstream: z.ZodNullable<z.ZodString>;
+        upstream_gone: z.ZodBoolean;
+        ahead: z.ZodNullable<z.ZodNumber>;
+        behind: z.ZodNullable<z.ZodNumber>;
+        last_commit_at: z.ZodNullable<z.ZodString>;
+        worktree: z.ZodNullable<z.ZodString>;
+        merged: z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                merged: "merged";
+                unmerged: "unmerged";
+            }>;
+            method: z.ZodNullable<z.ZodEnum<{
+                ancestry: "ancestry";
+                squash: "squash";
+                rebase: "rebase";
+            }>>;
+            evidence: z.ZodArray<z.ZodString>;
+            pr: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type Workspace = z.infer<typeof WorkspaceSchema>;
+/** One record per machine: the id derives from the machine id, so a re-snapshot
+ *  UPDATES the machine's record and two machines can never collide on a file. */
+export declare function workspaceId(machineId: string): string;
+/** Path-free worktree handle. */
+export declare function worktreeId(path: string): string;
+/** The same observation, published under `publish`: `branches` drops every worktree path
+ *  (the default), `full` keeps them. Pure, so a caller that already took a live snapshot
+ *  (paths included, for its own display) can publish it without re-running git. */
+export declare function withPublishMode(record: Workspace, publish: "full" | "branches"): Workspace;
+/** True when two snapshots of the same machine describe the same workspace, ignoring the
+ *  observation stamps — so an idle machine's hook does not commit a new record per
+ *  checkout. Provenance is constant per build and is compared too. */
+export declare function sameWorkspaceContent(a: Workspace, b: Workspace): boolean;
+export interface AggregateOptions {
+    /** Records older than this many days are reported as unverified. */
+    staleAfterDays?: number;
+    now?: Date;
+}
+export interface WorktreeRow {
+    machine: string;
+    worktree_id: string;
+    /** null in `branches` publish mode. */
+    path: string | null;
+    branch: string | null;
+    head: string;
+    dirty: boolean | null;
+    locked: boolean;
+    prunable: boolean;
+    last_commit_at: string | null;
+    seen_at: string;
+    unverified: boolean;
+}
+export interface BranchRow {
+    name: string;
+    /** Machine labels that hold this branch locally. */
+    machines: string[];
+    /** Machine labels with a worktree checked out on it. */
+    worktree_on: string[];
+    /** Machine labels whose worktree on it has uncommitted changes. */
+    dirty_on: string[];
+    /** Distinct heads across machines; more than one means the local branches diverged. */
+    heads: string[];
+    is_default: boolean;
+    upstream: string | null;
+    upstream_gone: boolean;
+    ahead: number | null;
+    behind: number | null;
+    last_commit_at: string | null;
+    merged: MergedVerdict;
+    /** Machine labels whose record is older than the staleness window. */
+    unverified_on: string[];
+    action: string;
+}
+export declare const DEFAULT_STALE_AFTER_DAYS = 7;
+export declare function isUnverified(record: Pick<Workspace, "observed_at">, opts?: AggregateOptions): boolean;
+/** Same machine id → the newest observation wins; a stale duplicate never shadows a fresh one. */
+export declare function latestPerMachine(records: readonly Workspace[]): Workspace[];
+export declare function worktreeRows(records: readonly Workspace[], opts?: AggregateOptions): WorktreeRow[];
+/** The recommendation rules from docs/workspace-ledger.md — deterministic text an agent
+ *  or a human reads; nothing executes it. */
+export declare function recommendAction(row: Omit<BranchRow, "action">, opts?: AggregateOptions): string;
+export declare function branchRows(records: readonly Workspace[], opts?: AggregateOptions): BranchRow[];
+/** "2h ago" / "9d ago" for the SEEN column. */
+export declare function ago(iso: string, now?: Date): string;
+export interface PruneStep {
+    branch: string;
+    head: string;
+    /** Worktree checked out on the branch, when one exists and can be removed first. */
+    worktree: {
+        id: string;
+        path: string | null;
+    } | null;
+    commands: string[];
+    why: string;
+}
+export interface PrunePlan {
+    /** Executable on this machine (live record). */
+    local: PruneStep[];
+    /** Display-only, keyed by machine label (stored records). */
+    others: Record<string, PruneStep[]>;
+    /** Branches this machine holds that were considered and left alone, with the reason. */
+    skipped: Array<{
+        branch: string;
+        reason: string;
+    }>;
+}
+/** Why a branch must not be pruned, or null when it may. The rules are the documented ones:
+ *  proven merged, not the default branch, worktree (if any) clean, unlocked and present. */
+export declare function pruneRefusal(b: WorkspaceBranch, wt: WorkspaceWorktree | undefined): string | null;
+export declare function planPrune(live: Workspace, others: readonly Workspace[]): PrunePlan;