grounder 0.5.0 → 0.6.0

package/dist/agents/types.d.ts

@@ -1,10 +1,12 @@
 /**
  * - `created` / `overwritten` — wrote new content
  * - `skipped` — already current (or dry-run would no-op)
- * - `modified` — on-disk content differs from last Grounder write; left alone
- *   unless `--force`
+ *
+ * No `modified`/conflict status here: hook fragments always-converge (see
+ * `installHooks`'s own docs on `AgentAdapter`) — unlike whole-file artifacts,
+ * there is no `--force` gate to report a blocked state for.
  */
-export type ArtifactStatus = "created" | "skipped" | "overwritten" | "modified";
+export type ArtifactStatus = "created" | "skipped" | "overwritten";
 export interface AgentInstallOptions {
     force?: boolean;
     /** Preview decisions without writing files or updating the install ledger. */
@@ -20,24 +22,62 @@ export interface AgentAdapter {
     readonly id: string;
     /** Human-readable display name, e.g. "Cursor". */
     readonly name: string;
+    /** Returns true when this agent appears to be installed on the machine. */
+    isInstalled(): Promise<boolean>;
+    /** Absolute paths of whole-file artifacts this adapter installs (read-only inspect). */
+    expectedArtifacts(homeDir?: string): string[];
     /**
-     * Bump when `install()` output's contract changes (placeholders, file set,
-     * frontmatter). Recorded in `~/.grounder/state.json`.
+     * Pure render (package-local template read only, no host filesystem
+     * touched): every whole-file artifact this adapter currently wants
+     * installed, path → rendered content. Reconciled against the ledger and
+     * disk by `reconcile()`.
+     *
+     * `options.invocation`, when given, replaces the live process's own
+     * `runtimeInvocation()` for the `{{GROUNDER_CLI}}` substitution. The real
+     * write path (`setup`/`migrate`, and `doctor`'s dry-run preview of it) must
+     * never pass this — it needs the live `process.execPath` so switching Node
+     * and re-running `migrate` still repairs a stale interpreter path (see
+     * docs/architecture/runtime-invocation.md's "Repair loop"). Only the cheap
+     * drift check (`status`/`peek`) passes the ledger's last-recorded
+     * invocation, so a *different* checking process never manufactures false
+     * drift purely from its own `process.execPath` differing from whatever
+     * process last ran a real install. An options object rather than a second
+     * positional string, deliberately: this is the one call that must never be
+     * passed on the write path, and a bare positional is easy to pass by
+     * mistake once a third parameter exists.
      */
-    readonly commandsSchema: number;
+    desiredArtifacts(homeDir?: string, options?: {
+        invocation?: string;
+    }): Promise<Record<string, string>>;
     /**
-     * Bump when `installHooks()` output's contract changes. Omit when the
-     * adapter has no hooks. Recorded in `~/.grounder/state.json`.
+     * Historical paths a previous install shape wrote that the current shape no
+     * longer wants at all (e.g. pre-Agent-Skills command markdown) — unioned
+     * into the "previous desired" side of `reconcile()`'s diff so they retire
+     * even when the ledger never recorded them (pre-hash-tracking installs).
+     */
+    tombstones(homeDir?: string): string[];
+    /**
+     * Directories this adapter is allowed to create in and delete from for its
+     * whole-file artifacts (skills dir, legacy commands dir) — never hook
+     * config, which is a shared JSON file merged/unmerged in place, not
+     * whole-file reconciled. Callers use this to keep a stray ledger entry
+     * (hand-edited or corrupted `state.json`) from being treated as a delete
+     * candidate just because it happens to share this agent's id.
+     */
+    ownedPrefixes(homeDir?: string): string[];
+    /**
+     * Optional: converge session hooks (separate from whole-file artifact
+     * install) — always-converge, no conflict/`--force` gate: removes every
+     * recognizer match and inserts exactly one canonical entry.
      */
-    readonly hooksSchema?: number;
-    /** Returns true when this agent appears to be installed on the machine. */
-    isInstalled(): Promise<boolean>;
-    /** Absolute paths of artifacts this adapter installs (read-only inspect). */
-    expectedArtifacts(homeDir?: string): string[];
-    /** Install all agent-specific artifacts (commands, rules, etc.). */
-    install(opts: AgentInstallOptions): Promise<AgentInstallResult>;
-    /** Optional: install session hooks (separate from slash-command install). */
     installHooks?(opts: AgentInstallOptions): Promise<AgentInstallResult>;
+    /**
+     * Optional: remove Grounder's hook fragment entirely (`--no-hooks`). Must
+     * actually delete the entry, not just report it as absent — an opt-out
+     * that leaves the fragment in place isn't sticky against the next
+     * `migrate`.
+     */
+    removeHooks?(opts: AgentInstallOptions): Promise<AgentInstallResult>;
     /** Optional: absolute path(s) of hook config this adapter would touch. */
     expectedHookArtifacts?(homeDir?: string): string[];
 }

package/dist/agents/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEhF,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,6EAA6E;IAC7E,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9C,oEAAoE;IACpE,OAAO,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChE,6EAA6E;IAC7E,YAAY,CAAC,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACtE,0EAA0E;IAC1E,qBAAqB,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACpD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,wFAAwF;IACxF,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CACd,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnC;;;;;OAKG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvC;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1C;;;;OAIG;IACH,YAAY,CAAC,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACtE;;;;;OAKG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrE,0EAA0E;IAC1E,qBAAqB,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACpD"}

package/dist/cli.js

@@ -10,6 +10,7 @@ import { runLink } from "./commands/link.js";
 import { runMigrate } from "./commands/migrate.js";
 import { runNoteList } from "./commands/note/list.js";
 import { runNote } from "./commands/note.js";
+import { runOverview } from "./commands/overview.js";
 import { runPathLogs } from "./commands/path/logs.js";
 import { runPathNotes } from "./commands/path/notes.js";
 import { runPathPlans } from "./commands/path/plans.js";
@@ -91,6 +92,9 @@ async function main() {
     if (command === "search") {
         process.exit(await runSearch(rest));
     }
+    if (command === "overview") {
+        process.exit(await runOverview(rest));
+    }
     if (command === "path") {
         if (rest[0] === "notes") {
             process.exit(await runPathNotes(rest.slice(1)));

package/dist/cli.js.map

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

package/dist/commands/apply.d.ts

@@ -0,0 +1,69 @@
+import type { AgentAdapter, AgentInstallResult, ArtifactStatus } from "../agents/types.js";
+import { type PlanEntry } from "../reconcile/core.js";
+export interface ApplyAgentInstallsOptions {
+    agents: AgentAdapter[];
+    force?: boolean;
+    /** Explicitly install/refresh session hooks (setup --hooks / migrate --hooks). */
+    hooks?: boolean;
+    /**
+     * Explicitly turn hooks off (`migrate --no-hooks`) — removes the fragment
+     * and flips `hooksEnabled` to `false` (sticky: a later plain `migrate`
+     * will not re-hydrate it). Mutually exclusive with `hooks` in practice
+     * (the CLI layer rejects both at once); if both are somehow set, `hooks`
+     * wins for that one call.
+     */
+    noHooks?: boolean;
+    /**
+     * When true (migrate), also refresh hooks that were previously enabled or
+     * already present on disk — without installing hooks for agents that never
+     * opted in.
+     */
+    refreshInstalledHooks?: boolean;
+    /**
+     * Retire tombstoned legacy paths (pre-skill `grounder-*.md` command files).
+     * Defaults to `true` (`migrate`'s behavior). `setup` passes `false` — per
+     * `docs/upgrading.md`, `setup --force` is a documented repair path that
+     * never deletes legacy files, only `migrate` does; `setup` overwriting a
+     * user's hand-edited leftover on `--force` would silently discard edits
+     * that were never ported into the new `SKILL.md`.
+     */
+    retireLegacy?: boolean;
+    dryRun?: boolean;
+    homeDir?: string;
+    /** Running package version — recorded in the ledger and checked on the write path. */
+    grounderVersion: string;
+}
+export interface AgentApplyResult {
+    agent: AgentAdapter;
+    plan: PlanEntry[];
+    hooks?: AgentInstallResult;
+    /** Would/did this agent's install change `~/.grounder/state.json`? */
+    ledgerChanged: boolean;
+    /**
+     * Set when this agent's hook install/removal threw (e.g. a shared hook
+     * config file has a `hooks` key that isn't a JSON object — see
+     * `readHooksObject`). This agent's whole-file artifacts (`plan` above)
+     * already applied by this point regardless; only the hook step failed, and
+     * later agents in the same run are unaffected — see the per-agent `try`
+     * in the loop below.
+     */
+    error?: string;
+}
+export interface ApplyAgentInstallsResult {
+    runtime?: {
+        cliPath: string;
+        status: ArtifactStatus;
+        mode: "symlink" | "copy";
+    };
+    agents: AgentApplyResult[];
+}
+/**
+ * Materialize runtime + install/refresh agent whole-file artifacts (and
+ * optional hooks). Shared by `grounder setup` and `grounder migrate`, both of
+ * which render the result themselves via `render-artifact-table.ts`.
+ *
+ * `--dry-run` = compute plans and preview, never call `applyPlan()` or write
+ * hooks/ledger.
+ */
+export declare function applyAgentInstalls(opts: ApplyAgentInstallsOptions): Promise<ApplyAgentInstallsResult>;
+//# sourceMappingURL=apply.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/commands/apply.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAa3F,OAAO,EAAE,KAAK,SAAS,EAAgC,MAAM,sBAAsB,CAAC;AAKpF,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,sEAAsE;IACtE,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;KAAE,CAAC;IAChF,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAyCD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CA2MnC"}

package/dist/commands/apply.js

@@ -0,0 +1,238 @@
+import { hookFileHasGrounderEntry, installHookRuntime, isHookRuntimeStale, runtimeCliPath, runtimeInvocation, runtimeMode, } from "../agents/hook-runtime.js";
+import { ownedLedgerFiles } from "../agents/index.js";
+import { assertVersionSupportsWrite, ledgerFilesFor, readGrounderState, recordedHooksEnabled, recordedInvocation, setHooksEnabled, setLedgerInvocation, touchGrounderVersion, } from "../connector/state.js";
+import { isUnsupportedSchemaError } from "../connector/unsupported-schema.js";
+import { applyPlan } from "../reconcile/apply.js";
+import { planChangesLedger, reconcile } from "../reconcile/core.js";
+import { readDiskHashes } from "../reconcile/disk.js";
+import { fileExists } from "../util/fs.js";
+import { hashContent } from "../util/hash.js";
+async function agentHasInstalledHooks(agent, homeDir) {
+    if (!agent.expectedHookArtifacts) {
+        return false;
+    }
+    const paths = agent.expectedHookArtifacts(homeDir);
+    for (const p of paths) {
+        if (await hookFileHasGrounderEntry(p)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * `hooksEnabled` tri-state drives whether a plain (no `--hooks`) migrate
+ * refreshes hooks: `true` → refresh, `false` → never (sticky opt-out),
+ * `undefined` → fall back to an on-disk recognizer match (legacy ledger, or
+ * hooks installed before the ledger tracked them at all).
+ */
+async function shouldInstallHooks(agent, opts, hooksEnabled) {
+    if (!agent.installHooks) {
+        return false;
+    }
+    if (opts.hooks) {
+        return true;
+    }
+    if (!opts.refreshInstalledHooks) {
+        return false;
+    }
+    if (hooksEnabled !== undefined) {
+        return hooksEnabled;
+    }
+    return agentHasInstalledHooks(agent, opts.homeDir);
+}
+/**
+ * Materialize runtime + install/refresh agent whole-file artifacts (and
+ * optional hooks). Shared by `grounder setup` and `grounder migrate`, both of
+ * which render the result themselves via `render-artifact-table.ts`.
+ *
+ * `--dry-run` = compute plans and preview, never call `applyPlan()` or write
+ * hooks/ledger.
+ */
+export async function applyAgentInstalls(opts) {
+    const force = opts.force ?? false;
+    const dryRun = opts.dryRun ?? false;
+    const retireLegacy = opts.retireLegacy ?? true;
+    const homeDir = opts.homeDir;
+    const agents = opts.agents;
+    const state = await readGrounderState(homeDir);
+    // Not gated on `dryRun` — a dry-run preview must refuse exactly like a real
+    // run would, so the two never disagree about whether this binary can write
+    // at all (see docs/architecture/state-reconciliation.md).
+    assertVersionSupportsWrite(opts.grounderVersion, state);
+    let runtime;
+    if (agents.length > 0) {
+        const cliPath = runtimeCliPath(homeDir);
+        // Grounder owns this directory outright (no user edits to protect), so
+        // `force` isn't needed to justify a reinstall — only actual staleness is.
+        const stale = await isHookRuntimeStale(homeDir);
+        if (!stale) {
+            runtime = { cliPath, status: "skipped", mode: await runtimeMode() };
+        }
+        else if (dryRun) {
+            runtime = {
+                cliPath,
+                status: (await fileExists(cliPath)) ? "overwritten" : "created",
+                mode: await runtimeMode(),
+            };
+        }
+        else {
+            runtime = await installHookRuntime({ homeDir });
+        }
+    }
+    const results = [];
+    for (const agent of agents) {
+        // No invocation override here, deliberately: this is the real write path
+        // (`setup`/`migrate`), which must always render against the live
+        // process's own `process.execPath` so switching Node and re-running
+        // `migrate` still repairs a stale interpreter path. See
+        // docs/architecture/runtime-invocation.md's "Repair loop" — only the
+        // cheap drift check (`install-drift.ts`) replays a stored invocation.
+        const desired = await agent.desiredArtifacts(homeDir);
+        const tombstones = retireLegacy ? agent.tombstones(homeDir) : [];
+        let ledgerFiles = ownedLedgerFiles(agent, ledgerFilesFor(state, agent.id), homeDir);
+        if (!retireLegacy && ledgerFiles) {
+            // `setup` must not retire legacy paths it already retired the ledger
+            // entry for either — an empty `tombstones` list alone isn't enough:
+            // `ownedLedgerFiles` still includes the legacy-commands-dir entry
+            // `migrate` recorded, and reconcile() would still see it and plan a
+            // delete. Restrict the ledger view itself to currently-desired paths.
+            const desiredPaths = new Set(Object.keys(desired));
+            ledgerFiles = Object.fromEntries(Object.entries(ledgerFiles).filter(([p]) => desiredPaths.has(p)));
+        }
+        const diskPaths = new Set([
+            ...Object.keys(desired),
+            ...Object.keys(ledgerFiles ?? {}),
+            ...tombstones,
+        ]);
+        const disk = await readDiskHashes(diskPaths);
+        const desiredHashes = {};
+        for (const [p, content] of Object.entries(desired)) {
+            desiredHashes[p] = hashContent(content);
+        }
+        const plan = reconcile(desiredHashes, tombstones, ledgerFiles, disk, force);
+        // `lastInvocation` only means "the {{GROUNDER_CLI}} baked into files'
+        // recorded hashes" if applying this plan actually gives every desired
+        // path a live hash. A desired path stuck on `conflict` (force not passed,
+        // on-disk content Grounder can't vouch for) keeps whatever hash it had
+        // before — recording the live invocation anyway would make the cheap
+        // check replay it against that stale hash and report drift forever, even
+        // after the conflict is resolved by an unrelated later run. Only skip
+        // when *nothing* for this agent got a live hash this run (every desired
+        // path conflicted) — a mixed run still records it: the paths that did
+        // get a live hash now correctly replay, and the still-conflicted ones
+        // showing drift is real remaining work (they need `--force`), not a
+        // false positive.
+        const hasLiveDesiredWrite = plan.some((entry) => entry.action !== "conflict" && desiredHashes[entry.path] !== undefined);
+        // Computed unconditionally (not just inside the `!dryRun` write below) so
+        // dry-run and a real run report the same "would state.json change?"
+        // verdict — matching `hooksLedgerChanged`'s pattern below. A self-heal
+        // case (a current install whose ledger predates this field) has an
+        // all-noop `plan` and unchanged hooks, so without this, `ledgerChanged`
+        // would miss the one write `setLedgerInvocation` is about to make.
+        const invocation = runtimeInvocation(homeDir);
+        const invocationChanged = hasLiveDesiredWrite && recordedInvocation(state, agent.id) !== invocation;
+        if (!dryRun) {
+            await applyPlan({
+                agentId: agent.id,
+                plan,
+                content: desired,
+                grounderVersion: opts.grounderVersion,
+                homeDir,
+                ownedPrefixes: agent.ownedPrefixes(homeDir),
+            });
+            if (hasLiveDesiredWrite) {
+                // Record what `{{GROUNDER_CLI}}` was actually rendered with above
+                // (the live process's own `process.execPath` — `desired` was never
+                // computed with an override), so the cheap drift check can replay
+                // the exact same invocation later instead of whichever process
+                // happens to be checking. See
+                // docs/architecture/runtime-invocation.md's "Repair loop".
+                await setLedgerInvocation({
+                    agentId: agent.id,
+                    invocation,
+                    grounderVersion: opts.grounderVersion,
+                    homeDir,
+                });
+            }
+        }
+        // A tombstoned path that's simply already gone (`noop`) carries nothing
+        // actionable — drop it from the table-facing plan (matches the old
+        // migration runner's "already-absent stays unreported"). Every other
+        // outcome, including a desired path's own `noop`, stays visible.
+        const desiredPaths = new Set(Object.keys(desired));
+        const visiblePlan = plan.filter((entry) => desiredPaths.has(entry.path) || entry.action !== "noop");
+        const hooksEnabled = recordedHooksEnabled(state, agent.id);
+        let hooksResult;
+        let hooksLedgerChanged = false;
+        let hooksError;
+        // Isolated per agent: a hook merge can throw on a shared config file this
+        // agent doesn't own the shape of (e.g. a `hooks` key that isn't a JSON
+        // object — see `readHooksObject`). Left uncaught, that unwinds past this
+        // loop and skips every agent after this one, even though their installs
+        // are entirely independent. `UnsupportedSchemaError` is the one exception
+        // that must still abort the whole run (same contract as
+        // `assertVersionSupportsWrite` above).
+        try {
+            if (opts.noHooks && !opts.hooks) {
+                const removeHooksFn = agent.removeHooks;
+                if (removeHooksFn) {
+                    hooksResult = await removeHooksFn({ force, dryRun, homeDir });
+                    if (hooksEnabled !== false) {
+                        hooksLedgerChanged = true;
+                        if (!dryRun) {
+                            await setHooksEnabled({
+                                agentId: agent.id,
+                                enabled: false,
+                                grounderVersion: opts.grounderVersion,
+                                homeDir,
+                            });
+                        }
+                    }
+                }
+            }
+            else if (await shouldInstallHooks(agent, opts, hooksEnabled)) {
+                const installHooksFn = agent.installHooks;
+                if (installHooksFn) {
+                    hooksResult = await installHooksFn({ force, dryRun, homeDir });
+                    if (hooksEnabled !== true) {
+                        hooksLedgerChanged = true;
+                        if (!dryRun) {
+                            await setHooksEnabled({
+                                agentId: agent.id,
+                                enabled: true,
+                                grounderVersion: opts.grounderVersion,
+                                homeDir,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (isUnsupportedSchemaError(error)) {
+                throw error;
+            }
+            hooksError = error instanceof Error ? error.message : String(error);
+        }
+        const ledgerChanged = planChangesLedger(plan, ledgerFiles, desiredHashes) ||
+            hooksLedgerChanged ||
+            invocationChanged;
+        results.push({
+            agent,
+            plan: visiblePlan,
+            hooks: hooksResult,
+            ledgerChanged,
+            error: hooksError,
+        });
+    }
+    // Per-artifact writes above have no hook for an all-noop plan — stamp
+    // grounderVersion unconditionally at the end of a real run so the upgrade
+    // banner still clears on a fully-current machine (matches the old
+    // recordAgentInstallState's every-real-run behavior). A no-op write when
+    // already current.
+    if (!dryRun && agents.length > 0) {
+        await touchGrounderVersion(opts.grounderVersion, homeDir);
+    }
+    return { runtime, agents: results };
+}
+//# sourceMappingURL=apply.js.map

package/dist/commands/apply.js.map

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

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAipBD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBvF"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA8vBD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBvF"}