@iseoane/agent-depot 0.4.1 → 0.5.1

package/README.md

@@ -1,6 +1,37 @@
 # Agent Depot
 
-Agent Depot keeps a global catalog of Git Sources for future skill discovery.
+[**English**](README.md) · [Español](README.es.md)
+
+Agent Depot is a cross-platform manager for the reusable resources that coding agents
+use. It discovers Skills from Git Sources, installs them into one or more Hosts
+(Pi, Claude Code, Codex and OpenCode), manages user-global Apps and host-native
+Packages, keeps track of what it installed and updates it safely, all from a CLI or
+an interactive TUI.
+
+What it does:
+
+- **Sources and catalog**: register Git repositories (plus the built-in
+  `builtin:agent-depot` Source) and discover the Skills they contain.
+- **Install Skills** user-global or per project, for several Hosts at once, pinned
+  to a version or following the latest. A project manifest lets a fresh checkout
+  reinstall the same Skills.
+- **Updates**: check and apply updates in batch; every change is previewed first and
+  needs explicit confirmation.
+- **Existing installations**: report unmanaged Skills already on disk, adopt the
+  ones that exactly match a Source, or remove them by explicit path.
+- **Apps**: install, update and uninstall user-global applications through
+  user-written App recipes that must be approved before they run.
+- **Packages**: install, update and uninstall host-native bundles (Pi packages and
+  Claude Code plugins) by delegating the lifecycle to each Host's own CLI and
+  reading the installed version from the Host's own state files. A bundle reserves
+  its Skills only while you have selected it or a Host proves it installed, so an
+  unselected bundle's Skills stay installable on their own.
+- **Profiles**: export your user-global Sources, Skill selections, App recipes and
+  Package selections to a portable file and import them, add-only, on another
+  machine.
+
+Agent Depot never overwrites or deletes content without a preview and confirmation,
+and refuses unsafe paths and links.
 
 Requires Node.js >= 24 (Active LTS). The [interactive TUI](#interactive-tui)
 needs an interactive terminal.
@@ -78,12 +109,35 @@ agent-depot uninstall --data --yes
 agent-depot app list
 agent-depot app approve <name> --yes
 agent-depot app install <name> --yes
+agent-depot package list
+agent-depot package discover <source-id>
+agent-depot package inspect <source-id>::<bundle-path> --host <host>
+agent-depot package approve <source-id>::<bundle-path> --host <host> --action install
+agent-depot package install <source-id>::<bundle-path> --host <host> --yes
+agent-depot package forget <source-id>::<bundle-path> --host <host> --yes
+agent-depot update check --scope user-global --package <selection>
 agent-depot export --out profile.json
 agent-depot import profile.json --yes
 agent-depot tui
 agent-depot --version
 ```
 
+GitHub directory URLs such as `https://github.com/cursor/plugins/tree/main/pstack`
+are also supported: Agent Depot clones the repository, reads the URL's ref, and
+only discovers Skills inside that directory. Skill paths stay repository-relative.
+The full URL remains the Source identity, so an already registered directory URL
+can simply be refreshed. The ref occupies one URL segment; encode any `/` in a
+branch name as `%2F` (for example `tree/release%2Fstable/pstack`). An explicit
+fixed-version ref overrides the URL ref while keeping the directory scope.
+
+Catalog groups show repository names instead of opaque Git IDs. Catalog and
+Installations start with all groups collapsed; use Enter or the right arrow to
+open a group. A Catalog filter automatically expands matching Sources.
+
+The TUI Catalog reports unavailable Sources individually and keeps other Sources
+browsable. To create a missing mirror, go to Sources (`1`) and refresh with `r`;
+opening the Catalog does not initiate network access.
+
 Refresh first prints the registered URL as a preview. It requires explicit
 `--yes` confirmation before any network access and otherwise fails closed. The
 package-owned `builtin:agent-depot` Source is listed as read-only and cannot be
@@ -190,8 +244,16 @@ index, or an unambiguous Skill path:
 ```sh
 agent-depot update apply --scope project --all --yes
 agent-depot update apply --scope user-global --skill 0 --yes
+agent-depot update apply --scope user-global --package git:<source-id>::pi:. --yes
 ```
 
+For `--scope user-global` only, the check also assesses every recorded Package and
+`update apply` accepts repeatable `--package <selection>` or includes updateable
+Packages under `--all`. A Package with `unknown` version status is never offered as
+an update. Packages run after Skills and Apps, each selected Package previews its
+frozen plan, and a Package whose update receipt is missing requires a separate `package approve --action update` before CLI execution. Project
+scope never reads or selects a Package.
+
 A Skill tracked at a non-canonical project path (outside `.agents/skills/<name>` and
 `.claude/skills/<name>`) is repository-controlled, so `--yes` alone does not update it. The
 preview prints the relative path; repeat it with `--confirm-path` (once per such path):
@@ -390,23 +452,29 @@ taller than the terminal. `j`/`k` or the arrow keys move.
 
 | View | Purpose |
 | --- | --- |
-| 1 Sources | Where skills come from: the fixed built-in Source plus registered Git Sources. |
-| 2 Catalog | Skills that can be installed: those not installed yet, as Source, then Skills. |
-| 3 Installations | What is on disk: managed installations (user-global and project) and unmanaged user-global skills. |
-| 4 Updates | Managed skills with a newer version available, for user-global and project scope. |
-| 5 Import/Export | Transfer portable user-global Source choices, Skill selections and App recipes. |
+| 1 Sources | Git Sources (their skills and Packages) and user-owned App recipes in one list, with `skills`/`app` kinds and contextual actions. |
+| 2 Catalog | Skills that can be installed: those not installed yet, as Source, then Skills. Each Source also shows a Packages group, and the Skills a bundle owns are marked and dimmed. |
+| 3 Installations | What is on disk: managed installations (user-global and project), Package selections and unmanaged user-global skills. |
+| 4 Updates | Managed skills and Packages with a newer version available, for user-global and project scope. |
+| 5 Import/Export | Transfer portable user-global Source choices, Skill selections, App recipes and Package selections. |
 
 Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 
 | View | Keys |
 | --- | --- |
-| Sources | `space` mark, `a` mark all, `Enter` open the Source in the Catalog, `n` add a Git Source, `r` refresh the marked (or highlighted) Sources, `d` remove |
-| Catalog | `Enter`/arrows expand and collapse, `space` mark, `a` mark all listed, `i` install the marks (or the highlighted skill), `/` filter, `s` toggle one Source or all (when opened from a Source) |
-| Installations | `Enter`/arrows expand and collapse, `u` uninstall (all Hosts or chosen Hosts) or remove an unmanaged skill, `h` or `i` add Hosts to an installation, `A` or `Enter` adopt an unmanaged skill, `space` marks a leaf and `a` marks all visible leaves: with marks, `u` and `h` act on all of them with one combined preview and one confirmation (project installations are skipped with a reason) |
-| Updates | `space` mark, `a` mark all, `t`/`p`/`g` show all, project or user-global, `Enter` preview the marks, `r` check again, arrows fold the "cannot assess" line |
-
+| Sources | `j`/`k` move through Git Sources and App recipes (no Tab section switch). `Enter` opens the Catalog for a Git Source (its skills and Packages) or previews/approves an App recipe. `n` adds a reusable Git Source or guides recipe authoring; `r` refreshes Sources or reloads recipe status; `d` removes. `space`/`a` mark Git Sources only. |
+| Catalog | `Enter`/arrows expand and collapse, `space` mark, `a` mark all listed, `i` install the marked Skills (or the highlighted skill) or preview the highlighted Package bundle, `/` filter, `s` toggle one Source or all (when opened from a Source) |
+| Installations | `Enter`/arrows expand and collapse, `u` uninstall (all Hosts or chosen Hosts) or remove an unmanaged skill, `h` or `i` add Hosts to an installation, `A` or `Enter` adopt an unmanaged skill, `space` marks a leaf and `a` marks all visible leaves: with marks, `u` and `h` act on all of them with one combined preview and one confirmation (project installations are skipped with a reason). On a Package row: `i` previews the frozen install plan and runs it, approving the receipt first when it is missing, `Enter` approves the install declaration only, `U` update, `u` uninstall, `f` forget the selection record. Package rows are not markable for bulk actions. |
+| Updates | `space` mark, `a` mark all, `t`/`p`/`g` show all, project or user-global, `Enter` preview the marks, `r` check again, arrows fold the "cannot assess" line. A marked Package joins the batch and is approved before its update runs. |
 | Import/Export | `e` export, `i` import; enter a file path, `space` toggle choices, `a` toggle all, `Enter` preview, `y` apply; `j`/`k` scroll previews and results |
 
+Removing an App recipe checks its approved version command and tracked state.
+If the App is installed or tracked, the TUI offers the existing uninstall flow;
+`n` cancels removal and a failed uninstall keeps the recipe. After verified
+uninstall (or when not installed), a separate preview confirms deletion of only
+the recipe file or symlink. App data and Host configuration are not implicitly
+deleted. Invalid recipes must be repaired before their App state can be checked.
+
 Safety model:
 
 - Nothing is written before a preview and an explicit `y`. Exposing a skill to an
@@ -414,6 +482,11 @@ Safety model:
 - An install refreshes its Git Source before the preview, so the content you
   confirm is the content that is applied. The Updates view refreshes
   the Git Sources in use when you enter it and on `r`.
+- A Package action previews the frozen declaration and the exact Host commands.
+  When the action's receipt is missing, the first `y` approves it and a second `y`
+  runs the Host command; an already approved action runs on the first `y`. `n` or
+  `Esc` at either gate cancels without approving or running anything. Listing and
+  reloading Packages never run a Host command.
 - The built-in Source is fixed: it is shown as an unselectable row and cannot be
   refreshed or removed.
 - Removal is user-global only. Project installations are listed, but project
@@ -443,6 +516,11 @@ Git mirrors are cached separately from the catalog:
 
 ## Limitations
 
+Packages are limited to the Pi and Claude Code Hosts in V1. Codex and OpenCode
+plugins, npm-sourced Pi packages, project-scoped Packages and external Claude
+marketplace sources are deferred, and a fixed-version Claude selection is refused;
+see [Packages](#packages).
+
 Only Git repository URLs using `git:`, `http:`, `https:`, or `ssh:` are
 accepted. Refresh uses the registered URL and runs Git with argument arrays,
 without a shell. It creates or fetches a bare mirror, explicitly synchronizes
@@ -589,6 +667,135 @@ remaining Hosts. For manual completion, rerun the selected Host with
 `--manual-done --yes`. This checks the App version, not Host wiring. Host actions
 never change installed-App tracking.
 
+## Packages
+
+A Package is a host-native bundle discovered inside a registered Source: a Pi
+package (a `package.json` with a `pi` key, or a `pi-package` keyword or a
+Pi-specific `extensions/` or `prompts/` directory) or a Claude Code plugin (a
+`.claude-plugin/plugin.json` bound by an in-repo `.claude-plugin/marketplace.json`).
+Because `skills/` and `themes/` are also Claude Code default locations, a
+conventional Pi package needs a Pi-specific directory, so an ordinary repository
+of shared skills is not read as a Pi package. One repository can be both, as
+`pstack-claude` is. V1 supports the Pi and Claude Code Hosts only; Codex and
+OpenCode packaging, npm-sourced Pi packages and project-scoped Packages are
+deferred.
+
+Agent Depot does not copy a bundle's contents. It reads the bundle manifest into a
+typed component inventory, derives the Host's own commands from that declaration,
+runs them through the no-shell command runner after approval, and reads the
+installed version back from the Host's state files. The Host owns what is
+installed. Agent Depot owns the selection record and the receipt for what it
+delegated. A bundle's own Skills are never offered for adoption or installed a
+second time, because the Host owns their files and locations.
+
+### Add a Source and discover its bundles
+
+Discovery reads the cached Git mirror and never refreshes it. The first discovery
+of a Source whose mirror is missing fails until you refresh that Source:
+
+```sh
+agent-depot source add https://github.com/michael-denyer/pstack-claude.git
+agent-depot source list
+agent-depot source refresh git:<source-id> --yes
+agent-depot package discover git:<source-id>
+```
+
+`package discover` prints one line per bundle in the Source plus its component
+inventory. `pstack-claude` yields a Pi bundle at the repository root and a Claude
+bundle from its in-repo marketplace:
+
+```text
+Package git:<source-id>::pi:.: pstack
+Package git:<source-id>::claude:.#pstack: pstack
+```
+
+Each component line names a kind, an ownership (`skill-category` or `host-only`),
+an effect and the declared paths. Agent definitions and MCP servers appear as
+`host-only`: Agent Depot reports them and leaves them to the Host.
+
+### Select, approve and run a lifecycle action
+
+A selection is `<source-id>::<bundle-path>` plus `--host`, or a host-qualified
+`<source-id>::<host>:<bundle-path>`. A Claude bundle path ends in `#<plugin-name>`
+when the Source offers more than one plugin.
+
+`approve` is per action. It writes the receipt for the exact declaration of that
+one action, so approving `install` does not authorize `update`. `--yes` confirms
+execution and never substitutes for approval. Planning a lifecycle action
+refreshes the selection's Git Source first, so the previewed manifest is the one
+the commands derive from.
+
+```sh
+# Pi package at the repository root
+agent-depot package inspect git:<source-id>::pi:. --host pi
+agent-depot package install git:<source-id>::pi:. --host pi
+agent-depot package approve git:<source-id>::pi:. --host pi --action install
+agent-depot package install git:<source-id>::pi:. --host pi --yes
+
+# Claude Code plugin from the in-repo marketplace
+agent-depot package inspect git:<source-id>::claude:.#pstack --host claude
+agent-depot package approve git:<source-id>::claude:.#pstack --host claude --action install
+agent-depot package install git:<source-id>::claude:.#pstack --host claude --yes
+```
+
+The `install`, `update` and `uninstall` commands print the full preview, then exit
+non-zero until both the action's receipt exists and `--yes` is given. The preview
+shows the resolved origin and commit, the descriptor, the component inventory with
+ownership and effect, every Host command with its executable name, the
+recorded coordinates the action can change (`affects`), the working directory, the
+environment, and any warning. Immediately before execution, Agent Depot re-derives
+the declaration and stops with `stale plan` if the manifest, commit, install
+identity or ordered commands changed since the preview. When the Host already
+reports the bundle installed, the plan runs no command and only records the
+selection.
+
+The Host commands for the two V1 Hosts:
+
+| Host | Install | Update | Uninstall |
+| --- | --- | --- | --- |
+| Pi | `pi install <source>` | `pi update <source>` | `pi remove <source>` |
+| Claude Code | `claude plugin marketplace add <source>`, then `claude plugin install <plugin>@<marketplace>` | `claude plugin marketplace update <marketplace>`, then `claude plugin update <plugin>@<marketplace>` | `claude plugin uninstall <plugin>@<marketplace>` |
+
+Agent Depot omits the `marketplace add` step when the Host already knows the
+marketplace, and always names the marketplace on the scoped update verb. Every V1
+action affects only its own selection.
+
+### Installed state, versions and removal
+
+`package list` shows every recorded selection with its install id and the version
+evidence Agent Depot recorded. Live evidence comes from
+`~/.pi/agent/settings.json` and `~/.claude/plugins/installed_plugins.json`, which
+Agent Depot reads and never writes. A missing Host file is an empty view. A
+drifted or undecodable file leaves the affected lookup `unknown` and never throws.
+An unversioned Pi git package is reported as `unknown`, never as `current`.
+
+An update records a new version only when the Host state changed in a way Agent
+Depot can verify, meaning the two observations agree on a version or a
+hexadecimal commit and differ, or the Host went from nothing installed to
+installed. An unverifiable update fails and leaves the record untouched. Uninstall
+delegates the Host command and then drops the selection record:
+
+```sh
+agent-depot package approve git:<source-id>::pi:. --host pi --action uninstall
+agent-depot package uninstall git:<source-id>::pi:. --host pi --yes
+agent-depot package forget git:<source-id>::pi:. --host pi --yes
+```
+
+`forget` removes only the Agent Depot selection record. It runs no Host command
+and leaves the Host install as it is.
+
+### Package limits
+
+- A fixed-version Claude selection cannot be delegated. `claude plugin install`
+  takes `<plugin>@<marketplace>` and has no pin slot, so planning a Claude
+  `install` or `update` with a `fixed` version policy fails closed instead of
+  claiming a pin the Host would ignore. Use `latest` for a Claude selection, or a
+  fixed pin for a Pi selection, until a supported Claude pin form is verified.
+- A Claude plugin with no in-repo marketplace binding is reported but not
+  installable.
+- Agent Depot does not read Host CLI prose output, including `pi list`. Installed
+  evidence comes from the Host state files only.
+
 ## Export a user-global Profile
 
 Export portable choices to another machine or keep them in git:
@@ -598,25 +805,30 @@ agent-depot export > profile.json
 agent-depot export --out profile.json
 agent-depot export --no-apps --source <source-id> --skill doctor-md-agents
 agent-depot export --no-sources --no-skills --app my-tool --app another-tool
+agent-depot export --package git:<source-id>::pi:.
 ```
 
-Everything portable is selected by default. `--no-sources`, `--no-skills` and
-`--no-apps` exclude blocks; repeatable `--source <id|url>`, `--skill <path|name>`
-and `--app <name>` restrict each block independently. Unknown selections and
-combining a block's inclusion filter with its `--no-*` flag are errors.
+Everything portable is selected by default. `--no-sources`, `--no-skills`,
+`--no-apps` and `--no-packages` exclude blocks; repeatable `--source <id|url>`,
+`--skill <path|name>`, `--app <name>` and `--package <selection>` restrict each block
+independently. Unknown selections and combining a block's inclusion filter with its
+`--no-*` flag are errors.
 
 Stdout contains JSON only; stderr shows the preview and exclusion reasons.
 `--out` requires a new file (existing files and symlinks are not replaced).
 Profiles contain canonical Git URLs with discovery inclusion, recorded Skill
-version policies/Hosts/user methods, and complete App recipes, including recipes
-for other platforms. CLI export always writes `included: true`; discovery choices are transient, while
+version policies/Hosts/user methods, complete App recipes, including recipes for
+other platforms, and Package selections as declarations only: their Source, host
+coordinates and version policy. CLI export always writes `included: true`; discovery choices are transient, while
 the TUI may pass explicit inclusion choices to the shared export core.
-Export neither refreshes Sources nor runs App commands.
+Export neither refreshes Sources nor runs App commands, and a Package receipt never
+travels in a Profile.
 
 Local paths and obvious credentials are not portable. Nonportable/invalid items
 are excluded with reasons, as are unmanaged/App-owned and project Skills,
-installation locations/evidence, approval receipts, installed-App state and
-pending updates. Free-text recipe portability checks are conservative; review
+installation locations/evidence, approval receipts, installed-App state, pending
+updates and Package receipts/installed state. Free-text recipe portability checks
+are conservative; review
 profiles before sharing them—arbitrary secrets cannot be detected automatically.
 
 ## Import a user-global Profile
@@ -629,19 +841,26 @@ agent-depot import profile.json --yes
 agent-depot import profile.json --no-apps --skill doctor-md-agents --yes
 ```
 
-Import uses the same independent block/name filters as export. It reports **add**,
+Import uses the same independent block/name filters as export, including
+`--no-packages` and `--package <selection>`. It reports **add**,
 **same** (skipped), and **conflict** (difference shown, skipped). Without `--yes`,
 nothing is written. Existing choices and conflicting files are never replaced.
 A profile produced by a newer Agent Depot version gives a warning, not an error.
 
 Confirmed additions run in order: Source registration, user-global Skills through
-normal refreshed install previews and safety checks, then App recipes. Recorded
-Hosts, version policies and user methods are retained. Even without `--yes`,
+normal refreshed install previews and safety checks, then App recipes, then Package
+selections. Recorded Hosts, version policies and user methods are retained. Even
+without `--yes`,
 each add-Skill preview shows its Source, Hosts, version policy and full argv for
 every user-provided method, marked as running only after confirmation. The normal
 install preview still appears before execution. Each failure is reported independently and remaining items
 continue; any failed item makes the command exit non-zero.
 
+A Package selection is a selection only. Import replays it through the flow's
+`select` action, which writes a receipt for that action alone, whose declaration
+carries no argv. No install or update is authorized and no Host command runs, so
+import never installs a Package.
+
 Recipes, including those for other platforms, arrive **unapproved** in `apps/`.
 A same-name destination recipe blocks import only when its platform overlaps the
 incoming recipe: equal platforms overlap, and a missing platform overlaps every
@@ -661,3 +880,5 @@ The **5 Import/Export** TUI tab offers grouped checklists and the same shared-co
 previews as the CLI. Exclusions and conflicts cannot be selected. Export creates
 a new file only; empty exports write nothing (CLI reports an error). Import adds missing choices without replacing existing ones.
 Imported recipes remain unapproved and Apps are never installed by import.
+Imported Package selections are recorded without installing a bundle and without
+running a Host command.

package/dist/src/app-flow.js

@@ -1,5 +1,4 @@
 import { access, chmod, mkdir, readFile, readdir, realpath, unlink } from "node:fs/promises";
-import { constants } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -7,6 +6,7 @@ import { compareAppVersions, sameAppVersion } from "./app-version.js";
 import { fetchAppLatest } from "./app-latest.js";
 import { writeFileAtomically } from "./atomic-file.js";
 import { parseAppRecipe } from "./app-recipes.js";
+import { createPortableExecutableResolver } from "./executable-resolution.js";
 import { runProcess } from "./process-runner.js";
 import { defaultSourceStatePath } from "./source-state.js";
 const APP_OUTPUT_LIMIT = 1024 * 1024;
@@ -21,42 +21,12 @@ export function createAppOperations(environment = {}) {
     const isWsl = environment.isWsl ?? (platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP));
     const mountRoot = environment.wslMountRoot ?? "/mnt";
     const runner = environment.runner ?? runProcess;
-    function isWindowsExecutable(executable) {
-        const relative = path.posix.relative(mountRoot, executable);
-        return isWsl && /^[a-z]\//iu.test(relative);
-    }
-    async function resolve(name) {
-        if (environment.resolveExecutable) {
-            const executable = await environment.resolveExecutable(name);
-            const target = executable ? await realpath(executable).catch(() => executable) : undefined;
-            return { executable, blocked: target !== undefined && isWindowsExecutable(target) };
-        }
-        let blockedExecutable;
-        const suffixes = platform === "win32"
-            ? ["", ...(process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")]
-            : [""];
-        for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
-            if (!path.isAbsolute(dir))
-                continue;
-            for (const suffix of suffixes) {
-                const candidate = path.join(dir, name + suffix);
-                try {
-                    await access(candidate, platform === "win32" ? constants.F_OK : constants.X_OK);
-                    const target = await realpath(candidate);
-                    if (isWindowsExecutable(target)) {
-                        blockedExecutable ??= candidate;
-                        continue;
-                    }
-                    // Preserve shim/multicall identity when spawning; realpath is only a safety check.
-                    return { executable: candidate, blocked: false };
-                }
-                catch {
-                    // Try the next PATH entry.
-                }
-            }
-        }
-        return { executable: blockedExecutable, blocked: blockedExecutable !== undefined };
-    }
+    const resolve = createPortableExecutableResolver({
+        platform,
+        isWsl,
+        wslMountRoot: mountRoot,
+        ...(environment.resolveExecutable === undefined ? {} : { resolveExecutable: environment.resolveExecutable }),
+    });
     const receiptPath = (entry) => path.join(receipts, createHash("sha256").update(entry.canonicalFile).digest("hex") + ".json");
     async function read(file) {
         try {
@@ -178,25 +148,28 @@ export function createAppOperations(environment = {}) {
             return approval;
         if (cached)
             return cached.installedVersion
-                ? { status: "installed", installedVersion: cached.installedVersion } : { status: "not installed" };
+                ? { status: "installed", installedVersion: cached.installedVersion, evidence: "recorded" }
+                : { status: "not installed" };
         const { executable, blocked } = await resolve(entry.recipe.version.argv[0]);
         if (!executable || blocked) {
             return { status: "not installed", executable, reason: blocked ? WINDOWS_EXECUTABLE_WARNING : undefined };
         }
+        let installedVersion;
         try {
             const result = await runner(executable, entry.recipe.version.argv.slice(1), {
                 cwd: home, captureStdout: true, maxOutputBytes: APP_OUTPUT_LIMIT, maxStderrBytes: APP_OUTPUT_LIMIT,
             });
-            const installedVersion = result.code === 0 && !result.signal && !result.outputTooLarge
+            installedVersion = result.code === 0 && !result.signal && !result.outputTooLarge
                 ? new RegExp(entry.recipe.version.pattern).exec(result.stdout.toString("utf8"))?.[1]
                 : undefined;
-            return installedVersion
-                ? { status: "installed", executable, installedVersion }
-                : { status: "not installed", executable };
         }
         catch {
             return { status: "not installed", executable };
         }
+        if (!installedVersion)
+            return { status: "not installed", executable };
+        await reconcileTracked(entry, installedVersion);
+        return { status: "installed", executable, installedVersion, evidence: "verified" };
     }
     async function checkUpdate(entry) {
         const inspection = await inspect(entry);
@@ -273,6 +246,25 @@ export function createAppOperations(environment = {}) {
         }
         return records;
     }
+    async function writeTracked(name, recipeFile, installedVersion) {
+        await mkdir(installations, { recursive: true, mode: 0o700 });
+        await chmod(installations, 0o700);
+        await writeFileAtomically(installationPath(name), JSON.stringify({ name, recipeFile, installedVersion }), { mode: 0o600 });
+    }
+    /**
+     * A live probe that verifies a version ahead of tracking rewrites that existing record,
+     * so a reload shows the version the App actually reports. Only a record whose recipe file
+     * matches is touched; an untracked App, an equal or older version and a failed probe write nothing.
+     */
+    async function reconcileTracked(entry, installedVersion) {
+        const name = entry.recipe?.name;
+        if (!name || !entry.canonicalFile)
+            return;
+        const tracked = (await trackedApps(() => { })).find(record => record.name === name && record.recipeFile === entry.canonicalFile);
+        if (!tracked || compareAppVersions(installedVersion, tracked.installedVersion) !== 1)
+            return;
+        await writeTracked(name, entry.canonicalFile, installedVersion);
+    }
     async function previewForget(name) {
         const file = installationPath(name);
         try {
@@ -336,11 +328,7 @@ export function createAppOperations(environment = {}) {
             if (plan.action === "update" && (!plan.previousVersion || sameAppVersion(inspection.installedVersion, plan.previousVersion))) {
                 return { status: "failed", reason: `version unchanged (${plan.previousVersion ?? "unknown"}); expected ${plan.latestVersion ?? "unknown"}` };
             }
-            await mkdir(installations, { recursive: true, mode: 0o700 });
-            await chmod(installations, 0o700);
-            await writeFileAtomically(installationPath(name), JSON.stringify({
-                name, recipeFile: plan.entry.canonicalFile, installedVersion: inspection.installedVersion,
-            }), { mode: 0o600 });
+            await writeTracked(name, plan.entry.canonicalFile, inspection.installedVersion);
             if (plan.action === "update")
                 await clearPendingUpdate(name);
             return { status: "installed", previousVersion: plan.previousVersion,
@@ -358,8 +346,12 @@ export function createAppOperations(environment = {}) {
         if (!confirmed)
             throw new Error("App step not confirmed; review and confirm first");
         await recheckPlan(plan);
-        if (!plan.argv || !plan.executable || plan.warning)
-            return manualFallback(plan);
+        if (!plan.argv)
+            return manualFallback(plan, `The ${plan.action} step requires manual completion`);
+        if (plan.warning)
+            return manualFallback(plan, `Cannot run ${JSON.stringify(plan.argv[0])}: ${plan.warning}`);
+        if (!plan.executable)
+            return manualFallback(plan, missingExecutableReason(plan.argv[0], plan.action));
         let result;
         try {
             result = await runner(plan.executable, plan.argv.slice(1), {
@@ -370,7 +362,10 @@ export function createAppOperations(environment = {}) {
             const code = error?.code;
             if (!code || !["ENOENT", "EACCES", "ENOEXEC", "EPERM"].includes(code))
                 throw error;
-            return manualFallback(plan, error instanceof Error ? error.message : String(error));
+            const detail = error instanceof Error ? error.message : String(error);
+            return manualFallback(plan, code === "ENOENT"
+                ? `${missingExecutableReason(plan.argv[0], plan.action)} (${detail})`
+                : `Cannot run ${JSON.stringify(plan.argv[0])} for ${plan.action} (${code}): ${detail}. Check the executable's permissions and runtime.`);
         }
         if (result.code !== 0 || result.signal || result.outputTooLarge) {
             const reason = result.outputTooLarge ? `output exceeded ${APP_OUTPUT_LIMIT} bytes`
@@ -389,7 +384,13 @@ export function createAppOperations(environment = {}) {
                 throw error;
         });
     }
-    async function manualFallback(plan, reason = "Executable unavailable") {
+    function missingExecutableReason(executable, action) {
+        const guidance = executable === "brew"
+            ? "Install Homebrew and make sure brew is on the PATH used by Agent Depot, then retry."
+            : `Install the required executable or make it available on the PATH used by Agent Depot, then retry.`;
+        return `Required executable ${JSON.stringify(executable)} for ${action} was not found or could not be started. ${guidance}`;
+    }
+    async function manualFallback(plan, reason) {
         if (plan.action === "update" && plan.manual) {
             await mkdir(pendingUpdates, { recursive: true, mode: 0o700 });
             await chmod(pendingUpdates, 0o700);

package/dist/src/app-recipe-removal.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readlink, realpath, unlink } from "node:fs/promises";
+import path from "node:path";
+import { assertNoSymlinkPath } from "./path-safety.js";
+function sameIdentity(left, right) {
+    return left.device === right.device && left.inode === right.inode && left.hash === right.hash && left.link === right.link;
+}
+async function recipeIdentity(file) {
+    await assertNoSymlinkPath(path.dirname(file), "App recipes directory");
+    const info = await lstat(file);
+    if (!info.isFile() && !info.isSymbolicLink())
+        throw new Error("App recipe is not a file or symbolic link");
+    // A symlink is removed as a link, never by unlinking its target.
+    const link = info.isSymbolicLink() ? await readlink(file) : undefined;
+    const bytes = await readFile(file);
+    return { device: info.dev, inode: info.ino, hash: createHash("sha256").update(bytes).digest("hex"),
+        ...(link === undefined ? {} : { link }) };
+}
+/** Explicit removal may check version, but never runs an unapproved recipe. */
+export async function planAppRecipeRemoval(apps, entry) {
+    const file = path.resolve(entry.file);
+    if (path.dirname(file) !== path.resolve(apps.directory))
+        throw new Error("App recipe is outside the recipes directory");
+    const identity = await recipeIdentity(file);
+    const [current] = await apps.load([file]);
+    if (current.error || !current.recipe)
+        throw new Error(`Cannot verify App state: ${current.error ?? "invalid recipe"}. Repair the recipe before removing it.`);
+    if (current.hash !== entry.hash || current.canonicalFile !== entry.canonicalFile)
+        throw new Error("App recipe changed; review it again");
+    const tracked = (await apps.trackedApps()).find((record) => record.name === current.recipe.name);
+    const inspection = await apps.inspect(current);
+    if (inspection.status !== "installed" && inspection.status !== "not installed" && inspection.status !== "not applicable here") {
+        throw new Error(`Cannot verify App state (${inspection.status}); approve the recipe before removing it`);
+    }
+    // Nothing resolved a version executable, so installed state was never verified.
+    if (inspection.status === "not installed" && (inspection.executable === undefined || inspection.reason !== undefined)) {
+        throw new Error(`Cannot verify App state: the version command for ${current.recipe.name} did not run. Make it available, then remove the recipe.`);
+    }
+    const installed = inspection.status === "installed" || tracked !== undefined;
+    return Object.freeze({ entry: current, file, identity, installed,
+        installedVersion: inspection.installedVersion ?? tracked?.installedVersion });
+}
+/** Rechecks content, inode and symlink target before any unlink; the live version read is a window. */
+async function assertRecipeUnchanged(plan) {
+    const identity = await recipeIdentity(plan.file);
+    const canonicalFile = await realpath(plan.file);
+    if (!sameIdentity(identity, plan.identity) || canonicalFile !== plan.entry.canonicalFile) {
+        throw new Error("App recipe changed after preview; removal cancelled");
+    }
+}
+/** Rechecks the preview and installed state before unlinking only the recipe path. */
+export async function removeAppRecipe(apps, plan, confirmed) {
+    if (!confirmed)
+        throw new Error("App recipe removal must be confirmed");
+    if (path.dirname(plan.file) !== path.resolve(apps.directory))
+        throw new Error("App recipe is outside the recipes directory");
+    await assertRecipeUnchanged(plan);
+    const current = await planAppRecipeRemoval(apps, plan.entry);
+    if (current.installed)
+        throw new Error("App is still installed or tracked; uninstall it before removing its recipe");
+    await assertRecipeUnchanged(plan);
+    await unlink(plan.file);
+}