@davesheffer/hunch 1.38.1 → 1.39.0

package/dist/core/config.d.ts

@@ -9,12 +9,28 @@ import type { HunchPaths } from "./paths.js";
 export type Firmness = "off" | "advisory" | "firm" | "strict";
 export declare const FIRMNESS_LEVELS: readonly Firmness[];
 export declare const DEFAULT_FIRMNESS: Firmness;
+/** Workspace-ledger knobs (docs/workspace-ledger.md). `publish` decides what a snapshot
+ *  carries: `branches` (default — label, branches, verdicts, dirty/locked flags, no paths),
+ *  `full` (worktree paths too), `off` (no record). `publish_public` lets a repo WITHOUT an
+ *  overlay commit the record into its tracked .hunch/ — off by default: per-machine facts
+ *  churning the code repo is rarely wanted. */
+export type WorkspacePublish = "full" | "branches" | "off";
+export declare const WORKSPACE_PUBLISH_MODES: readonly WorkspacePublish[];
+export declare const DEFAULT_WORKSPACE_PUBLISH: WorkspacePublish;
+export interface WorkspacesConfig {
+    publish: WorkspacePublish;
+    stale_after_days: number;
+    publish_public: boolean;
+}
 export interface HunchConfig {
     firmness: Firmness;
     /** MCP tool groups beyond the everyday set: `all`, `core`, or `core,nuryel`
      *  (see src/mcp/toolset.ts). Undefined = decide from the root's contents. */
     mcp_tools?: string;
+    workspaces?: Partial<WorkspacesConfig>;
 }
+/** The effective workspace config: every field present, unknown values ignored. */
+export declare function workspacesConfig(config: HunchConfig): WorkspacesConfig;
 export declare function isFirmness(v: unknown): v is Firmness;
 /** Read `.hunch/config.json`. A missing/unparseable file, or an unknown firmness
  *  value, falls back to defaults — the hook must NEVER crash an edit over config. */

package/dist/core/config.js

@@ -6,6 +6,18 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 export const FIRMNESS_LEVELS = ["off", "advisory", "firm", "strict"];
 export const DEFAULT_FIRMNESS = "advisory";
+export const WORKSPACE_PUBLISH_MODES = ["full", "branches", "off"];
+export const DEFAULT_WORKSPACE_PUBLISH = "branches";
+/** The effective workspace config: every field present, unknown values ignored. */
+export function workspacesConfig(config) {
+    const raw = config.workspaces ?? {};
+    const days = Number(raw.stale_after_days);
+    return {
+        publish: WORKSPACE_PUBLISH_MODES.includes(raw.publish) ? raw.publish : DEFAULT_WORKSPACE_PUBLISH,
+        stale_after_days: Number.isInteger(days) && days >= 1 && days <= 3650 ? days : 7,
+        publish_public: raw.publish_public === true,
+    };
+}
 function defaults() {
     return { firmness: DEFAULT_FIRMNESS };
 }
@@ -22,6 +34,7 @@ export function readConfig(paths) {
         return {
             firmness: isFirmness(raw.firmness) ? raw.firmness : DEFAULT_FIRMNESS,
             ...(typeof raw.mcp_tools === "string" && raw.mcp_tools.trim() ? { mcp_tools: raw.mcp_tools.trim() } : {}),
+            ...(raw.workspaces && typeof raw.workspaces === "object" && !Array.isArray(raw.workspaces) ? { workspaces: raw.workspaces } : {}),
         };
     }
     catch {

package/dist/core/machine.d.ts

@@ -0,0 +1,20 @@
+export interface MachineIdentity {
+    id: string;
+    label: string;
+    created_at: string;
+}
+export interface MachinePathOptions {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    platform?: NodeJS.Platform;
+}
+export declare function machineFile(opts?: MachinePathOptions): string;
+export declare function defaultMachineLabel(id: string): string;
+/** The machine's identity, minted on first use. An unreadable or invalid file is
+ *  replaced (a machine that lost its id simply becomes a new machine; the old record
+ *  ages out as unverified and `hunch workspaces forget` removes it). */
+export declare function loadOrCreateMachine(opts?: MachinePathOptions): MachineIdentity;
+export declare function setMachineLabel(label: string, opts?: MachinePathOptions): MachineIdentity;
+/** A label that equals the hostname or the OS username publishes personal data into a
+ *  shared store; `doctor` and `label` warn, they do not refuse — the user chose it. */
+export declare function labelLeaksIdentity(label: string): string | null;

package/dist/core/machine.js

@@ -0,0 +1,101 @@
+/**
+ * Machine identity for the workspace ledger (docs/workspace-ledger.md): a random id
+ * generated ONCE per machine and stored at the user level, so every clone on the
+ * machine reports as the same machine. Deliberately NOT derived from the hostname,
+ * a MAC address or a hardware serial — it identifies nothing outside Hunch. The
+ * label is user-chosen; the default embeds nothing personal.
+ *
+ * Lives under the platform's per-user config root (XDG_CONFIG_HOME / %APPDATA% /
+ * ~/.config) and, like updatecheck.ts, never creates a `.hunch` path segment: that
+ * is findRoot()'s repository marker.
+ */
+import { lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir, hostname, userInfo } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { randomBytes, randomUUID } from "node:crypto";
+import { MACHINE_ID, MACHINE_LABEL } from "./workspace.js";
+const MAX_MACHINE_FILE_BYTES = 4096;
+function configuredRoot(value, platform) {
+    if (!value)
+        return null;
+    const absolute = platform === "win32" ? /^(?:[A-Za-z]:[\\/]|\\\\)/.test(value) : value.startsWith("/");
+    const marker = value.replace(/\\/g, "/").split("/").some((part) => part.toLowerCase().replace(/[ .]+$/g, "") === ".hunch");
+    return absolute && !marker ? value : null;
+}
+export function machineFile(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? homedir();
+    const platform = opts.platform ?? process.platform;
+    const configHome = configuredRoot(env.XDG_CONFIG_HOME, platform)
+        || (platform === "win32" && configuredRoot(env.APPDATA, platform))
+        || join(home, ".config");
+    return join(configHome, "hunch", "machine.json");
+}
+export function defaultMachineLabel(id) {
+    return `machine-${id.replace(/^mac_/, "").slice(0, 4)}`;
+}
+function readMachine(file) {
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_MACHINE_FILE_BYTES)
+            return null;
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof raw.id !== "string" || !MACHINE_ID.test(raw.id))
+            return null;
+        const label = typeof raw.label === "string" && MACHINE_LABEL.test(raw.label) ? raw.label : defaultMachineLabel(raw.id);
+        const created = typeof raw.created_at === "string" && Number.isFinite(Date.parse(raw.created_at)) ? raw.created_at : new Date(0).toISOString();
+        return { id: raw.id, label, created_at: created };
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic, owner-only write: a half-written id file would mint a second machine. */
+function writeMachine(file, identity) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    writeFileSync(temp, JSON.stringify(identity, null, 2) + "\n", { mode: 0o600 });
+    renameSync(temp, file);
+}
+/** The machine's identity, minted on first use. An unreadable or invalid file is
+ *  replaced (a machine that lost its id simply becomes a new machine; the old record
+ *  ages out as unverified and `hunch workspaces forget` removes it). */
+export function loadOrCreateMachine(opts = {}) {
+    const file = machineFile(opts);
+    const existing = readMachine(file);
+    if (existing)
+        return existing;
+    const id = `mac_${randomBytes(16).toString("hex")}`;
+    const fresh = { id, label: defaultMachineLabel(id), created_at: new Date().toISOString() };
+    writeMachine(file, fresh);
+    return fresh;
+}
+export function setMachineLabel(label, opts = {}) {
+    if (!MACHINE_LABEL.test(label)) {
+        throw new Error("machine label must be 1-64 characters of letters, digits, '.', '_' or '-' and start with a letter or digit");
+    }
+    const next = { ...loadOrCreateMachine(opts), label };
+    writeMachine(machineFile(opts), next);
+    return next;
+}
+/** A label that equals the hostname or the OS username publishes personal data into a
+ *  shared store; `doctor` and `label` warn, they do not refuse — the user chose it. */
+export function labelLeaksIdentity(label) {
+    const lower = label.toLowerCase();
+    let host = "";
+    let user = "";
+    try {
+        host = hostname().toLowerCase();
+    }
+    catch { /* unavailable */ }
+    try {
+        user = userInfo().username.toLowerCase();
+    }
+    catch { /* unavailable */ }
+    if (host && (lower === host || lower === host.split(".")[0]))
+        return "hostname";
+    if (user && lower === user)
+        return "OS username";
+    return null;
+}
+//# sourceMappingURL=machine.js.map

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;