grounder 0.5.0 → 0.6.0

package/dist/help.js

@@ -136,6 +136,18 @@ Subcommands:
   --markdown      Agent relay: file:// links + fenced snippets
   --json          Structured output (relativePath, fileUri, alsoMatchedHint per hit)`,
     },
+    {
+        id: "overview",
+        group: "Retrieve",
+        summary: "Bird's-eye view: counts + recent titles across notes/handoffs/plans",
+        listUsage: "overview",
+        usage: "grounder overview [--limit <n>] [--markdown] [--json]",
+        flags: `Flags:
+  --limit <n>  Max recent titles to print per bucket (default: 3)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+  --json       Structured output (total, count, truncated, items per bucket;
+               each item includes mtimeMs)`,
+    },
     {
         id: "path notes",
         group: "Paths",
@@ -174,7 +186,9 @@ Subcommands:
         group: "Maintain",
         summary: "Snapshot of machine + project link + resolved paths",
         listUsage: "status",
-        usage: "grounder status",
+        usage: "grounder status [--json]",
+        flags: `Flags:
+  --json  Print a single-line JSON payload instead of formatted text`,
     },
     {
         id: "doctor",
@@ -190,13 +204,20 @@ Subcommands:
         group: "Maintain",
         summary: "Refresh agent install after upgrading grounder",
         listUsage: "migrate",
-        usage: "grounder migrate [--force] [--dry-run] [--agent <id>] [--hooks]",
+        usage: "grounder migrate [--force] [--dry-run] [--agent <id>] [--hooks | --no-hooks]",
         flags: `Flags:
-  --force      Overwrite command files you edited locally; also needed
-               once when upgrading from Grounder before 0.3
+  --force      Overwrite skill files you edited locally; also needed
+               once when upgrading from Grounder before 0.3. Also
+               deletes locally-edited pre-skill grounder-*.md command
+               files left over from before 0.6 (edits are not ported)
   --dry-run    Preview without writing
   --agent <id> Limit to a specific agent (repeatable)
-  --hooks      Also install hooks if not previously installed`,
+  --hooks      Also install hooks if not previously installed
+  --no-hooks   Turn hooks off and remove the installed hook entry
+               (sticky — a later plain migrate will not re-enable it)
+
+Also retires pre-skill grounder-*.md command files superseded by
+SKILL.md packaging (safe ones automatically; edited ones need --force).`,
     },
     {
         id: "handoff peek",
@@ -240,6 +261,7 @@ export const DISPATCHED_COMMAND_IDS = [
     "plan",
     "plan list",
     "search",
+    "overview",
     "path",
     "path notes",
     "path logs",

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/reconcile/apply.d.ts

@@ -0,0 +1,31 @@
+import { type PlanEntry } from "./core.js";
+export interface ApplyPlanOptions {
+    agentId: string;
+    plan: readonly PlanEntry[];
+    /** Desired content for `create`/`update`/`noop` entries — path → rendered bytes. */
+    content: Record<string, string>;
+    grounderVersion: string;
+    homeDir?: string;
+    /**
+     * Directories this agent is allowed to write into / delete from (its own
+     * `AgentAdapter#ownedPrefixes`) — re-checked here via
+     * {@link isUnderOwnedPrefix}, not trusted solely from the caller, so a plan
+     * built from a stray/corrupted ledger entry can never be applied as a
+     * filesystem write outside the agent's own tree.
+     */
+    ownedPrefixes: readonly string[];
+}
+/**
+ * Execute a whole-file plan: write/delete each path, and persist that path's
+ * ledger hash right after its own file write succeeds (per-artifact, not
+ * batched) — a mid-run crash leaves the ledger consistent with whatever
+ * actually completed.
+ *
+ * Returns nothing: callers render their tables from the `PlanEntry[]` they
+ * passed in (see `commands/render-artifact-table.ts`'s
+ * `rowStatusFromPlanAction`), so a second per-path outcome vocabulary here
+ * would only be a chance for the two to disagree. Failure is a throw, not a
+ * status — every entry that doesn't throw did exactly what its action says.
+ */
+export declare function applyPlan(opts: ApplyPlanOptions): Promise<void>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/reconcile/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/reconcile/apply.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFrE"}

package/dist/reconcile/apply.js

@@ -0,0 +1,97 @@
+import { unlink } from "node:fs/promises";
+import { forgetLedgerFile, setLedgerFileHash } from "../connector/state.js";
+import { writeFileAtomic } from "../util/fs.js";
+import { hashContent } from "../util/hash.js";
+import { isUnderOwnedPrefix } from "./core.js";
+/**
+ * Execute a whole-file plan: write/delete each path, and persist that path's
+ * ledger hash right after its own file write succeeds (per-artifact, not
+ * batched) — a mid-run crash leaves the ledger consistent with whatever
+ * actually completed.
+ *
+ * Returns nothing: callers render their tables from the `PlanEntry[]` they
+ * passed in (see `commands/render-artifact-table.ts`'s
+ * `rowStatusFromPlanAction`), so a second per-path outcome vocabulary here
+ * would only be a chance for the two to disagree. Failure is a throw, not a
+ * status — every entry that doesn't throw did exactly what its action says.
+ */
+export async function applyPlan(opts) {
+    for (const entry of opts.plan) {
+        if ((entry.action === "create" || entry.action === "update" || entry.action === "delete") &&
+            !isUnderOwnedPrefix(entry.path, opts.ownedPrefixes)) {
+            throw new Error(`Refusing to ${entry.action} ${entry.path}: outside ${opts.agentId}'s owned prefixes`);
+        }
+        switch (entry.action) {
+            case "create":
+            case "update": {
+                const content = opts.content[entry.path];
+                if (content === undefined) {
+                    throw new Error(`No desired content for ${entry.path} (action: ${entry.action})`);
+                }
+                await writeFileAtomic(entry.path, content);
+                await setLedgerFileHash({
+                    agentId: opts.agentId,
+                    filePath: entry.path,
+                    hash: hashContent(content),
+                    grounderVersion: opts.grounderVersion,
+                    homeDir: opts.homeDir,
+                });
+                break;
+            }
+            case "noop": {
+                // A desired path already matching on disk — hydrate the ledger hash
+                // when it wasn't recorded yet (or recorded stale), so a manually
+                // correct file becomes safely Grounder-managed going forward.
+                const content = opts.content[entry.path];
+                if (content !== undefined) {
+                    await setLedgerFileHash({
+                        agentId: opts.agentId,
+                        filePath: entry.path,
+                        hash: hashContent(content),
+                        grounderVersion: opts.grounderVersion,
+                        homeDir: opts.homeDir,
+                    });
+                }
+                break;
+            }
+            case "delete": {
+                try {
+                    await unlink(entry.path);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        // A real failure (EACCES, EISDIR, …) — propagate rather than
+                        // forgetting the ledger hash for a file that's still on disk;
+                        // swallowing it here would leave the ledger and disk permanently
+                        // disagreeing, with no way for a future run to notice and retry.
+                        throw error;
+                    }
+                }
+                await forgetLedgerFile({
+                    agentId: opts.agentId,
+                    filePath: entry.path,
+                    grounderVersion: opts.grounderVersion,
+                    homeDir: opts.homeDir,
+                });
+                break;
+            }
+            case "forget": {
+                // Already gone from disk, but the ledger still holds a stale hash
+                // (removed outside `migrate`) — drop it so it doesn't linger forever.
+                await forgetLedgerFile({
+                    agentId: opts.agentId,
+                    filePath: entry.path,
+                    grounderVersion: opts.grounderVersion,
+                    homeDir: opts.homeDir,
+                });
+                break;
+            }
+            case "conflict":
+                // Left alone on purpose — on-disk content Grounder can't confirm it
+                // wrote. `--force` is what turns this into an `update`/`delete`
+                // upstream in `reconcile()`, so there is nothing to do here.
+                break;
+        }
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/reconcile/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/reconcile/apply.ts"],"names":[],"mappings":"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"}

package/dist/reconcile/core.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure reconciliation core — no I/O anywhere in this file.
+ *
+ * Two shapes, per the design: {@link desiredDrift} answers "would migrate
+ * change something" cheaply (ledger vs. rendered template hashes only, no
+ * disk read) for `peek`/`status`; {@link reconcile} is the full three-way
+ * (desired vs. ledger vs. on-disk) plan `setup`/`migrate`/`doctor` execute or
+ * preview. Modeled on chezmoi's source/destination/target state and dpkg's
+ * old-pristine/new-pristine/on-disk compare.
+ */
+/**
+ * True when `filePath` sits under one of `prefixes` (a directory, matched
+ * exactly or via a `prefix + separator` boundary — never a bare substring
+ * match, and never a `..`-segment escape). Callers use this to keep a
+ * ledger's extra/stray entries — a hand-edited or corrupted `state.json`,
+ * say — from ever being treated as delete candidates for paths outside the
+ * directories an adapter actually manages. Comparison is lexical
+ * (`path.resolve` + `path.relative`, no symlink following): both sides are
+ * resolved to absolute form first, so a `../` segment in `filePath` cannot
+ * walk back out of a prefix it superficially starts with.
+ * `reconcile()` itself stays agnostic to this (see its own docs); callers
+ * filter `ledger` before passing it in.
+ */
+export declare function isUnderOwnedPrefix(filePath: string, prefixes: readonly string[]): boolean;
+export type DriftKind = "create" | "update";
+export interface DriftEntry {
+    path: string;
+    kind: DriftKind;
+}
+/** One agent's last-applied manifest — path → hash of the bytes Grounder wrote. */
+export type LedgerManifest = Record<string, {
+    hash?: string;
+}>;
+/**
+ * Compare desired (rendered template) hashes against one agent's last-applied
+ * ledger manifest. No disk I/O — the caller renders + hashes templates, and
+ * passes in the ledger's `files` map already read from `state.json`.
+ *
+ * `ledger === undefined` means this agent has no ledger entry at all (never
+ * installed) — returns no drift. Scoping to ledger-recorded agents lives
+ * here, not in every caller: otherwise a detected-but-never-installed agent
+ * would tease `migrate` forever with no command able to silence it.
+ *
+ * Within a ledger-recorded agent, a desired path missing from its `files` map
+ * IS drift (`"create"`) — that's how a newly added skill file surfaces here.
+ */
+export declare function desiredDrift(desired: Record<string, string>, ledger: LedgerManifest | undefined): DriftEntry[];
+export type PlanAction = "create" | "update" | "delete" | "conflict" | "noop" | "forget";
+export interface PlanEntry {
+    path: string;
+    action: PlanAction;
+    /** Only set when `action === "conflict"` — which action `--force` would take. */
+    blockedAction?: "overwrite" | "delete";
+}
+/** path → on-disk content hash, `undefined` when the path does not exist. */
+export type DiskHashes = Record<string, string | undefined>;
+/**
+ * Full three-way reconcile for one agent's whole-file artifacts: desired
+ * (current templates) vs. ledger (last-applied) vs. disk (actual). Pure —
+ * `disk`/`ledger` are already-read snapshots, not live filesystem access.
+ *
+ * `tombstones` are extra "previously desired, no longer desired" paths
+ * (pre-skill command files, etc.) unioned into the retirement side of the
+ * diff even when the ledger never recorded them — the case a pure
+ * ledger-manifest diff is blind to (pre-hash-tracking installs).
+ *
+ * Safety: only ever call this for a known agent id whose `desired` this
+ * binary can actually compute — never for an unrecognized ledger entry,
+ * which would treat its entire recorded file set as delete candidates.
+ */
+export declare function reconcile(desired: Record<string, string>, tombstones: readonly string[], ledger: LedgerManifest | undefined, disk: DiskHashes, force: boolean): PlanEntry[];
+/**
+ * Would applying `plan` actually change the ledger? Pure — mirrors exactly
+ * what `applyPlan()`'s per-artifact writes do (each has its own no-op guard):
+ * `create`/`update`/`noop` only write when the recorded hash would actually
+ * change; `delete` only forgets an entry that exists; `forget` always writes
+ * (by construction it only exists when there's something to forget);
+ * `conflict` never touches the ledger. Used so `--dry-run` and a real run
+ * predict/report the exact same thing for the exact same reason.
+ */
+export declare function planChangesLedger(plan: readonly PlanEntry[], ledger: LedgerManifest | undefined, desired: Record<string, string>): boolean;
+//# sourceMappingURL=core.d.ts.map

package/dist/reconcile/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/reconcile/core.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAezF;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,UAAU,EAAE,CAcd;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,iFAAiF;IACjF,aAAa,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CACxC;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,OAAO,GACb,SAAS,EAAE,CA4Cb;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAyBT"}

package/dist/reconcile/core.js

@@ -0,0 +1,163 @@
+import path from "node:path";
+/**
+ * Pure reconciliation core — no I/O anywhere in this file.
+ *
+ * Two shapes, per the design: {@link desiredDrift} answers "would migrate
+ * change something" cheaply (ledger vs. rendered template hashes only, no
+ * disk read) for `peek`/`status`; {@link reconcile} is the full three-way
+ * (desired vs. ledger vs. on-disk) plan `setup`/`migrate`/`doctor` execute or
+ * preview. Modeled on chezmoi's source/destination/target state and dpkg's
+ * old-pristine/new-pristine/on-disk compare.
+ */
+/**
+ * True when `filePath` sits under one of `prefixes` (a directory, matched
+ * exactly or via a `prefix + separator` boundary — never a bare substring
+ * match, and never a `..`-segment escape). Callers use this to keep a
+ * ledger's extra/stray entries — a hand-edited or corrupted `state.json`,
+ * say — from ever being treated as delete candidates for paths outside the
+ * directories an adapter actually manages. Comparison is lexical
+ * (`path.resolve` + `path.relative`, no symlink following): both sides are
+ * resolved to absolute form first, so a `../` segment in `filePath` cannot
+ * walk back out of a prefix it superficially starts with.
+ * `reconcile()` itself stays agnostic to this (see its own docs); callers
+ * filter `ledger` before passing it in.
+ */
+export function isUnderOwnedPrefix(filePath, prefixes) {
+    const target = path.resolve(filePath);
+    return prefixes.some((prefix) => {
+        const root = path.resolve(prefix);
+        if (root === target) {
+            return true;
+        }
+        const relative = path.relative(root, target);
+        return (relative !== "" &&
+            relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative));
+    });
+}
+/**
+ * Compare desired (rendered template) hashes against one agent's last-applied
+ * ledger manifest. No disk I/O — the caller renders + hashes templates, and
+ * passes in the ledger's `files` map already read from `state.json`.
+ *
+ * `ledger === undefined` means this agent has no ledger entry at all (never
+ * installed) — returns no drift. Scoping to ledger-recorded agents lives
+ * here, not in every caller: otherwise a detected-but-never-installed agent
+ * would tease `migrate` forever with no command able to silence it.
+ *
+ * Within a ledger-recorded agent, a desired path missing from its `files` map
+ * IS drift (`"create"`) — that's how a newly added skill file surfaces here.
+ */
+export function desiredDrift(desired, ledger) {
+    if (!ledger) {
+        return [];
+    }
+    const out = [];
+    for (const [path, hash] of Object.entries(desired)) {
+        const recorded = ledger[path]?.hash;
+        if (recorded === undefined) {
+            out.push({ path, kind: "create" });
+        }
+        else if (recorded !== hash) {
+            out.push({ path, kind: "update" });
+        }
+    }
+    return out;
+}
+/**
+ * Full three-way reconcile for one agent's whole-file artifacts: desired
+ * (current templates) vs. ledger (last-applied) vs. disk (actual). Pure —
+ * `disk`/`ledger` are already-read snapshots, not live filesystem access.
+ *
+ * `tombstones` are extra "previously desired, no longer desired" paths
+ * (pre-skill command files, etc.) unioned into the retirement side of the
+ * diff even when the ledger never recorded them — the case a pure
+ * ledger-manifest diff is blind to (pre-hash-tracking installs).
+ *
+ * Safety: only ever call this for a known agent id whose `desired` this
+ * binary can actually compute — never for an unrecognized ledger entry,
+ * which would treat its entire recorded file set as delete candidates.
+ */
+export function reconcile(desired, tombstones, ledger, disk, force) {
+    const ledgerFiles = ledger ?? {};
+    const allPaths = new Set([
+        ...Object.keys(desired),
+        ...Object.keys(ledgerFiles),
+        ...tombstones,
+    ]);
+    const entries = [];
+    for (const path of allPaths) {
+        const desiredHash = desired[path];
+        const ledgerHash = ledgerFiles[path]?.hash;
+        const onDisk = disk[path];
+        if (desiredHash !== undefined) {
+            // Whole-file artifact currently wanted.
+            if (onDisk === undefined) {
+                entries.push({ path, action: "create" });
+            }
+            else if (onDisk === desiredHash) {
+                entries.push({ path, action: "noop" });
+            }
+            else if (force || (ledgerHash !== undefined && ledgerHash === onDisk)) {
+                entries.push({ path, action: "update" });
+            }
+            else {
+                entries.push({ path, action: "conflict", blockedAction: "overwrite" });
+            }
+            continue;
+        }
+        // Not in the current desired set — retirement candidate (tombstone, or a
+        // path dropped from the manifest by a schema change).
+        if (onDisk === undefined) {
+            // Already gone — noop, not a recurring delete (doctor would otherwise
+            // warn about an already-cleaned-up legacy path forever). If the ledger
+            // still holds a stale hash for it (removed outside `migrate`), that's
+            // a ledger-only cleanup ("forget"), not a file action.
+            entries.push({ path, action: ledgerHash !== undefined ? "forget" : "noop" });
+        }
+        else if (force || (ledgerHash !== undefined && ledgerHash === onDisk)) {
+            entries.push({ path, action: "delete" });
+        }
+        else {
+            entries.push({ path, action: "conflict", blockedAction: "delete" });
+        }
+    }
+    return entries;
+}
+/**
+ * Would applying `plan` actually change the ledger? Pure — mirrors exactly
+ * what `applyPlan()`'s per-artifact writes do (each has its own no-op guard):
+ * `create`/`update`/`noop` only write when the recorded hash would actually
+ * change; `delete` only forgets an entry that exists; `forget` always writes
+ * (by construction it only exists when there's something to forget);
+ * `conflict` never touches the ledger. Used so `--dry-run` and a real run
+ * predict/report the exact same thing for the exact same reason.
+ */
+export function planChangesLedger(plan, ledger, desired) {
+    const ledgerFiles = ledger ?? {};
+    for (const entry of plan) {
+        switch (entry.action) {
+            case "create":
+            case "update":
+            case "noop": {
+                const desiredHash = desired[entry.path];
+                if (desiredHash !== undefined && ledgerFiles[entry.path]?.hash !== desiredHash) {
+                    return true;
+                }
+                break;
+            }
+            case "delete":
+                if (ledgerFiles[entry.path]?.hash !== undefined) {
+                    return true;
+                }
+                break;
+            case "forget":
+                return true;
+            case "conflict":
+                break;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=core.js.map

package/dist/reconcile/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/reconcile/core.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;GASG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,QAA2B;IAC9E,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,CACL,QAAQ,KAAK,EAAE;YACf,QAAQ,KAAK,IAAI;YACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;YACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAC3B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAYD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA+B,EAC/B,MAAkC;IAElC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QACpC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC7B,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAcD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CACvB,OAA+B,EAC/B,UAA6B,EAC7B,MAAkC,EAClC,IAAgB,EAChB,KAAc;IAEd,MAAM,WAAW,GAAG,MAAM,IAAI,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS;QAC/B,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;QACvB,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;QAC3B,GAAG,UAAU;KACd,CAAC,CAAC;IAEH,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAE1B,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,wCAAwC;YACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC3C,CAAC;iBAAM,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YACzC,CAAC;iBAAM,IAAI,KAAK,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,MAAM,CAAC,EAAE,CAAC;gBACxE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,CAAC;YACzE,CAAC;YACD,SAAS;QACX,CAAC;QAED,yEAAyE;QACzE,sDAAsD;QACtD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,sEAAsE;YACtE,uEAAuE;YACvE,sEAAsE;YACtE,uDAAuD;YACvD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/E,CAAC;aAAM,IAAI,KAAK,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,MAAM,CAAC,EAAE,CAAC;YACxE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA0B,EAC1B,MAAkC,EAClC,OAA+B;IAE/B,MAAM,WAAW,GAAG,MAAM,IAAI,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;YACrB,KAAK,QAAQ,CAAC;YACd,KAAK,QAAQ,CAAC;YACd,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACxC,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;oBAC/E,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,QAAQ;gBACX,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;oBAChD,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,MAAM;YACR,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC;YACd,KAAK,UAAU;gBACb,MAAM;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/reconcile/disk.d.ts

@@ -0,0 +1,13 @@
+import type { DiskHashes } from "./core.js";
+/**
+ * Read + hash each path; a missing file maps to `undefined`. Any other read
+ * failure (EACCES, EISDIR, …) propagates instead of being folded into
+ * "missing" — an unreadable-but-present file must never be silently planned
+ * as a `create`, writing blind over content this binary never actually saw.
+ * Both callers already have somewhere for that to land gracefully: doctor's
+ * `computeAgentPlansSafe` catches per-agent and turns it into a "could not
+ * verify skill drift" warning; `setup`/`migrate` catch it around
+ * `applyAgentInstalls` and report it on stderr.
+ */
+export declare function readDiskHashes(paths: Iterable<string>): Promise<DiskHashes>;
+//# sourceMappingURL=disk.d.ts.map

package/dist/reconcile/disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../src/reconcile/disk.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAajF"}

package/dist/reconcile/disk.js

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { hashContent } from "../util/hash.js";
+/**
+ * Read + hash each path; a missing file maps to `undefined`. Any other read
+ * failure (EACCES, EISDIR, …) propagates instead of being folded into
+ * "missing" — an unreadable-but-present file must never be silently planned
+ * as a `create`, writing blind over content this binary never actually saw.
+ * Both callers already have somewhere for that to land gracefully: doctor's
+ * `computeAgentPlansSafe` catches per-agent and turns it into a "could not
+ * verify skill drift" warning; `setup`/`migrate` catch it around
+ * `applyAgentInstalls` and report it on stderr.
+ */
+export async function readDiskHashes(paths) {
+    const out = {};
+    for (const p of paths) {
+        try {
+            out[p] = hashContent(await readFile(p, "utf8"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            out[p] = undefined;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=disk.js.map

package/dist/reconcile/disk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.js","sourceRoot":"","sources":["../../src/reconcile/disk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAuB;IAC1D,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/util/fs.d.ts

@@ -5,6 +5,20 @@ export declare function fileExists(filePath: string): Promise<boolean>;
  * not oversell POSIX execute-bit semantics there.
  */
 export declare function isExecutable(filePath: string): Promise<boolean>;
+/**
+ * Write `content` to `filePath` via tmp file + rename, so a crash mid-write
+ * never leaves a truncated file at the real path. Creates the destination
+ * directory if needed; best-effort removes the tmp file if `rename` itself
+ * throws, so a failed write doesn't leave an orphaned `.tmp-*` sibling behind.
+ * `mode` (e.g. the pre-existing file's permission bits), when given, is
+ * applied to the tmp file before the rename — otherwise the replaced file
+ * would pick up the tmp file's default umask permissions instead of keeping
+ * whatever the file already had, which matters for host-owned config files
+ * edited by other tools.
+ */
+export declare function writeFileAtomic(filePath: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
 /**
  * Creates a new markdown file under `dir`; never overwrites.
  * Tries `basename.md`, then `basename_02.md`, `_03`, … with `wx` (O_EXCL)

package/dist/util/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAIA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAgBjB"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAIA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAgBjB"}

package/dist/util/fs.js

@@ -1,4 +1,4 @@
-import { access, constants, writeFile } from "node:fs/promises";
+import { access, chmod, constants, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { collisionSuffix } from "./timestamp-slug.js";
 export async function fileExists(filePath) {
@@ -24,6 +24,32 @@ export async function isExecutable(filePath) {
         return false;
     }
 }
+/**
+ * Write `content` to `filePath` via tmp file + rename, so a crash mid-write
+ * never leaves a truncated file at the real path. Creates the destination
+ * directory if needed; best-effort removes the tmp file if `rename` itself
+ * throws, so a failed write doesn't leave an orphaned `.tmp-*` sibling behind.
+ * `mode` (e.g. the pre-existing file's permission bits), when given, is
+ * applied to the tmp file before the rename — otherwise the replaced file
+ * would pick up the tmp file's default umask permissions instead of keeping
+ * whatever the file already had, which matters for host-owned config files
+ * edited by other tools.
+ */
+export async function writeFileAtomic(filePath, content, options = {}) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(tmpPath, content, "utf8");
+    if (options.mode !== undefined) {
+        await chmod(tmpPath, options.mode);
+    }
+    try {
+        await rename(tmpPath, filePath);
+    }
+    catch (error) {
+        await unlink(tmpPath).catch(() => { });
+        throw error;
+    }
+}
 /**
  * Creates a new markdown file under `dir`; never overwrites.
  * Tries `basename.md`, then `basename_02.md`, `_03`, … with `wx` (O_EXCL)

package/dist/util/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW,EACX,QAAgB,EAChB,OAAe;IAEf,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9F,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAAe,EACf,UAA6B,EAAE;IAE/B,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,GAAG,QAAQ,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC/D,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACtC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW,EACX,QAAgB,EAChB,OAAe;IAEf,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC"}