@iseoane/agent-depot 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-10-11
+
+### Added
+
+- `agent-depot self update [--yes]` checks npm and updates only a verified npm global installation after explicit confirmation. Other installation methods receive manual guidance; downgrades are refused.
+- A Pi Package containing the `/agents` panel, with a versioned snapshot-provider contract, measured telemetry, active-first newest-first ordering and stable selection. Migrating from the former pstack panel requires the coordinated adapter described in `docs/pi-agents-panel.md`.
+- Manual npm trusted publishing through GitHub Actions OIDC, with version, source commit and tarball integrity checks, without stored npm tokens.
+
+### Changed
+
+- Agent instructions use focused context pointers and a disclosed workflow guide. English and Spanish usage docs describe current Package ownership, TUI controls and delegated-command safety limits.
+
+### Fixed
+
+- `doctor-md-agents` analyzes Pi correction history and reports missing or unsupported sources explicitly. `doctor-md-skill` follows the active Pi session branch rather than scoring abandoned branches.
+- Installed Pi Packages with local changes display the version declared at verified Git HEAD, qualified as HEAD-only evidence. Local modifications still prevent update assessment and never become persisted verified installation evidence.
+- TUI tests wait for a complete resized frame and unmount views before deleting their temporary state, avoiding CI teardown races.
+
+## [0.5.1] - 2026-10-07
+
+### Changed
+
+- The TUI fills the terminal from startup, responds to resize, and restores the primary screen on exit.
+- Catalog keeps a stable list height while you move between Skills with different Package owners.
+- Catalog `a` marks or clears only visible loose Skills in the repository under the cursor. Marks in other repositories and filtered-out Skills stay unchanged.
+
+### Fixed
+
+- Catalog rows use readable contrast, one-line truncation, and compact Package badges. A separate panel explains the highlighted Skill's ownership.
+- Host-confirmed installed Packages disappear from Catalog. Selected-only Packages and Packages with unknown installation state remain visible.
+- Pi Git Package inspections read the installed checkout's origin, commit, and version without changing the checkout. Local modifications keep the Package installed but make version assessment unavailable.
+- Git Package updates require cached Source history to prove that the installed commit precedes the available commit. Different or locally divergent commits alone do not imply an update.
+- Tests isolate `PI_CODING_AGENT_DIR` so an inherited shell override cannot redirect fixtures to user state.
+
 ## [0.5.0] - 2026-10-06
 
 ### Added

package/README.es.md

@@ -24,7 +24,7 @@ Qué hace:
   App recipes escritas por el usuario que deben aprobarse antes de ejecutarse.
 - **Packages**: instala, actualiza y desinstala bundles nativos del Host (paquetes de
   Pi y plugins de Claude Code) delegando el ciclo de vida en la CLI de cada Host y
-  leyendo la versión instalada de los propios archivos de estado del Host. Un bundle
+  leyendo evidencia de instalación y versión propiedad del Host. Un bundle
   reserva sus Skills solo mientras lo hayas seleccionado o un Host demuestre que está
   instalado, así que los Skills de un bundle no seleccionado siguen siendo instalables
   por separado.
@@ -32,8 +32,13 @@ Qué hace:
   de Packages globales de usuario a un archivo portable e impórtalos, solo añadiendo,
   en otra máquina.
 
-Agent Depot nunca sobrescribe ni elimina contenido sin una previsualización y una
-confirmación, y rechaza rutas y enlaces inseguros.
+Agent Depot previsualiza y confirma los cambios del sistema de archivos que
+gestiona. Esta garantía no cubre los efectos de comandos delegados. Los métodos de
+Skill proporcionados por el usuario, las App recipes aprobadas y los comandos de
+Host aprobados para Packages se ejecutan como procesos hijos. Agent Depot no puede
+previsualizar por completo ni revertir los efectos que queden fuera de sus propios
+cambios gestionados. Agent Depot rechaza rutas y enlaces inseguros en sus
+operaciones gestionadas del sistema de archivos.
 
 Requiere Node.js >= 24 (Active LTS). La [TUI interactiva](#tui-interactiva)
 necesita un terminal interactivo.
@@ -68,13 +73,23 @@ npx @iseoane/agent-depot@latest tui
 pnpm dlx @iseoane/agent-depot@latest tui
 ```
 
-Una instalación global se actualiza con el gestor de paquetes que la instaló:
+Comprueba y actualiza una instalación global de npm con Agent Depot:
 
 ```sh
-npm install --global @iseoane/agent-depot@latest
-pnpm add --global @iseoane/agent-depot@latest
+agent-depot self update
+agent-depot self update --yes
 ```
 
+El primer comando consulta el registro público de npm y previsualiza una versión más
+reciente sin actualizar. El segundo repite la comprobación, previsualiza el destino
+exacto y lo instala. Agent Depot solo admite este flujo si la ruta del paquete cargado
+coincide con el directorio global que informa npm. Para las demás instalaciones,
+incluidas las de pnpm, npx, locales de proyecto, mediante enlace o de procedencia
+desconocida, muestra instrucciones manuales. La actualización invoca npm sin shell,
+desactiva los scripts del paquete y no solicita privilegios elevados ni cambia la
+configuración de npm. Si npm falla durante la instalación, el paquete global puede
+quedar actualizado solo en parte; Agent Depot no puede revertir los cambios de npm.
+
 Un Agent Depot en ejecución nunca degrada los Skills integrados: un Skill instalado
 por un Agent Depot más reciente se notifica como no actualizable (actualiza primero
 Agent Depot).
@@ -94,10 +109,10 @@ agent-depot source remove git:<source-id> --yes
 agent-depot source remove git:<source-id> --skill <id|path> --yes
 agent-depot source migrate git:<old-source-id> git:<new-source-id> --skill <path> --yes
 agent-depot discover builtin:agent-depot git:<source-id>
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
-agent-depot install --scope user-global --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
+agent-depot install --scope user-global --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
 # Only for an explicitly reviewed, untracked real-directory conflict:
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 agent-depot install --scope project --manifest --portable-v1 --yes
 agent-depot update check --scope project
 agent-depot update apply --scope project --all --yes
@@ -251,7 +266,7 @@ actualizable. Solo para `--scope user-global`, la comprobación también informa
 directorios de Skill reales `Unmanaged` encontrados en ubicaciones absolutas exactas
 bajo las raíces globales de usuario admitidas. Estos no son candidatos a
 actualización, no se incluyen en los recuentos de estado de los gestionados y nunca
-se buscan a través de una Source. Las comprobaciones de proyecto no inventarían ni
+se buscan a través de una Source. Las comprobaciones de proyecto no examinan ni
 informan de directorios no gestionados.
 
 Las entradas globales omitidas o inseguras se muestran por separado con
@@ -328,7 +343,7 @@ un único objeto de método JSON estricto, por ejemplo:
 
 ```sh
 agent-depot install --scope user-global --source builtin:agent-depot \
-  --skill architecture --host pi --version latest \
+  --skill agent-depot-apprecipe --host pi --version latest \
   --method '{"kind":"command","argv":["node","scripts/install.mjs"],"cwd":"tools"}' \
   --portable-v1 --yes
 ```
@@ -391,7 +406,7 @@ directorio real sin registrar cuyo contenido difiere, el reemplazo requiere tant
 
 ```sh
 agent-depot install --scope project --source builtin:agent-depot \
-  --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+  --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 ```
 
 La previsualización es explícita sobre esta distinción: sin `--yes` no se modifica
@@ -491,15 +506,17 @@ agent-depot tui
 
 La TUI es un front end de [Ink](https://github.com/vadimdemedes/ink) (React para
 terminales) sobre las mismas operaciones que la CLI. Necesita Node.js >= 24 y un
-terminal interactivo; en caso contrario, `tui` falla con un error. Cambia de vista
-con `1`-`5` y sal con `q` (no mientras haya un aviso abierto). Toda lista se
-desplaza cuando es más alta que el terminal. `j`/`k` o las flechas mueven la
-selección.
+terminal interactivo; en caso contrario, `tui` falla con un error. Usa la pantalla
+alternativa del terminal y vuelve a la pantalla anterior al salir. Se adapta al
+redimensionado del terminal. Cambia de vista con `1`-`5` y sal con `q` (no mientras
+haya un aviso abierto). Las listas se desplazan cuando superan la altura del
+terminal. En Sources, Catalog, Installations y Updates, `j`/`k` o las flechas mueven
+una fila; `PageUp` y `PageDown` avanzan una página visible.
 
 | Vista | Propósito |
 | --- | --- |
 | 1 Sources | Sources de Git (sus skills y Packages) y recetas App del usuario en una sola lista, con tipos `skills`/`app` y acciones contextuales. |
-| 2 Catalog | Skills que se pueden instalar: los que aún no están instalados, como Source y luego Skills. Cada Source muestra además un grupo Packages, y los Skills que posee un bundle se marcan y se atenúan. |
+| 2 Catalog | Skills y Packages disponibles, agrupados por Source. Los Packages que el Host confirma como instalados se ocultan; los que solo están seleccionados siguen visibles. Un Skill propiedad de un Package activo conserva el contraste normal y muestra una insignia breve; no se puede marcar ni instalar por separado. Sitúa el cursor encima para ver el motivo. |
 | 3 Installations | Lo que hay en disco: instalaciones gestionadas (globales de usuario y de proyecto), selecciones de Packages y skills globales de usuario no gestionados. |
 | 4 Updates | Skills y Packages gestionados con una versión más reciente disponible, para el ámbito global de usuario y de proyecto. |
 | 5 Import/Export | Transferir las elecciones portables de Sources globales de usuario, las selecciones de Skills, las App recipes y las selecciones de Packages. |
@@ -510,9 +527,9 @@ confirmar):
 | Vista | Teclas |
 | --- | --- |
 | Sources | `j`/`k` recorren Sources de Git y recetas App, sin cambiar de sección con Tab. `Enter` abre el Catálogo de una Source de Git (sus skills y Packages) o previsualiza/aprueba una receta. `n` añade una Source de Git reutilizable o guía la creación de recetas; `r` refresca Sources o recarga el estado de recetas; `d` elimina. `space`/`a` solo marcan Sources de Git. |
-| Catalog | `Enter`/flechas expandir y contraer, `space` marcar, `a` marcar todos los listados, `i` instalar las Skills marcadas (o el skill resaltado) o previsualizar el bundle de Package resaltado, `/` filtrar, `s` alternar entre una Source o todas (cuando se abre desde una Source) |
+| Catalog | `Enter`/flechas expandir y contraer, `space` alternar el Skill disponible resaltado, `a` alternar todos los Skills disponibles de la Source resaltada que coincidan con el filtro actual, `i` instalar los Skills marcados que coincidan con el filtro o el Skill disponible resaltado, o previsualizar el Package resaltado, `/` filtrar, `s` alternar una Source o todas (si se abrió desde una Source). Las marcas de otras Sources se conservan. |
 | Installations | `Enter`/flechas expandir y contraer, `u` desinstalar (todos los Hosts o los Hosts elegidos) o eliminar un skill no gestionado, `h` o `i` añadir Hosts a una instalación, `A` o `Enter` adoptar un skill no gestionado, `space` marca una hoja y `a` marca todas las hojas visibles: con marcas, `u` y `h` actúan sobre todas ellas con una única previsualización combinada y una única confirmación (las instalaciones de proyecto se omiten con un motivo). En una fila de Package: `i` previsualiza el plan de instalación congelado y lo ejecuta, aprobando antes el recibo si falta; `Enter` solo aprueba la declaración de instalación; `U` actualiza, `u` desinstala, `f` olvida el registro de selección. Las filas de Package no se pueden marcar para acciones por lotes. |
-| Updates | `space` marcar, `a` marcar todo, `t`/`p`/`g` mostrar todo, proyecto o global de usuario, `Enter` previsualizar las marcas, `r` comprobar de nuevo, las flechas pliegan la línea "cannot assess". Un Package marcado se une al lote y se aprueba antes de ejecutar su actualización. |
+| Updates | `space` marcar, `a` marcar todo, `t`/`p`/`g` mostrar todo, proyecto o global de usuario, `Enter` previsualizar las marcas, `r` comprobar de nuevo, las flechas pliegan el grupo "cannot be checked". Sus filas son informativas y no se pueden marcar para actualizar. Un Package marcado se une al lote y se aprueba antes de ejecutar su actualización. |
 | Import/Export | `e` exportar, `i` importar; introduce una ruta de archivo, `space` alterna opciones, `a` alterna todas, `Enter` previsualiza, `y` aplica; `j`/`k` desplazan las previsualizaciones y los resultados |
 
 Al eliminar una receta App se comprueban su comando de versión aprobado y su
@@ -659,8 +676,8 @@ agent-depot app teardown example --host pi --yes
 ```
 
 Cada paso previsualiza su texto argv/manual, el ejecutable resuelto, el directorio de
-trabajo (el personal del usuario) y el entorno. El recurso manual solo se produce
-cuando un proceso no puede lanzarse, nunca tras una salida con código distinto de
+trabajo (el directorio personal del usuario) y el entorno. Las instrucciones
+manuales solo se ofrecen cuando un proceso no puede iniciarse, nunca tras una salida con código distinto de
 cero (que se notifica con stdout/stderr). Ejecuta tú mismo las instrucciones manuales
 mostradas y después certifica la finalización sin volver a ejecutar el argv:
 
@@ -738,10 +755,12 @@ nunca cambian el seguimiento de Apps instaladas.
 ## Packages
 
 Un Package es un bundle nativo del Host descubierto dentro de una Source registrada:
-un paquete de Pi (un `package.json` con una clave `pi`, o los directorios
-convencionales `extensions/`, `skills/`, `prompts/` y `themes/`) o un plugin de Claude
-Code (un `.claude-plugin/plugin.json` vinculado por un
-`.claude-plugin/marketplace.json` dentro del repositorio). Un mismo repositorio puede
+un paquete de Pi (un `package.json` con una clave `pi`, la palabra clave
+`pi-package` o un directorio convencional específico de Pi, como `extensions/` o
+`prompts/`) o un plugin de Claude Code (un `.claude-plugin/plugin.json` vinculado
+por un `.claude-plugin/marketplace.json` dentro del repositorio). Los directorios
+`skills/` y `themes/` también son convencionales en Claude Code, por lo que un
+repositorio que solo contiene Skills compartidos no se identifica como paquete de Pi. Un mismo repositorio puede
 ser ambas cosas, como `pstack-claude`. V1 solo admite los Hosts Pi y Claude Code; el
 empaquetado de Codex y OpenCode, los paquetes de Pi procedentes de npm y los Packages
 de ámbito de proyecto quedan aplazados.
@@ -749,10 +768,26 @@ de ámbito de proyecto quedan aplazados.
 Agent Depot no copia el contenido de un bundle. Lee el manifiesto del bundle en un
 inventario de componentes tipado, deriva los comandos propios del Host a partir de esa
 declaración, los ejecuta mediante el ejecutor de comandos sin shell tras la aprobación
-y lee la versión instalada de los archivos de estado del Host. El Host posee lo que
-está instalado. Agent Depot posee el registro de selección y el recibo de lo que
-delegó. Los Skills propios de un bundle nunca se ofrecen para adopción ni se instalan
-por segunda vez, porque el Host posee sus archivos y ubicaciones.
+y lee el estado instalado de archivos propiedad del Host. Agent Depot lee esos
+archivos y nunca los escribe. Para Pi, el ajuste `packages` de
+`~/.pi/agent/settings.json` identifica un paquete configurado. Agent Depot verifica
+después el checkout bajo `$PI_CODING_AGENT_DIR/git` (o `~/.pi/agent/git` si la
+variable no está definida): la raíz del checkout, `origin`, el commit `HEAD` y el
+`package.json` de ese commit. Si no puede verificar la raíz, el origen o `HEAD`, el
+paquete sigue instalado, pero su versión no está disponible. Si los cambios locales
+hacen que el checkout esté modificado, Agent Depot muestra la versión de `HEAD`, pero
+no usa el commit para evaluar actualizaciones. Installations y `package inspect`
+indican `(HEAD; local changes)` en la etiqueta. Tanto los cambios en archivos
+controlados como los archivos sin seguimiento cuentan; Agent Depot no ignora archivos
+de bloqueo ni otros archivos locales. La versión del manifiesto sirve para mostrar
+información, pero no demuestra que el checkout coincida con la Source seleccionada.
+La evaluación de actualizaciones compara el commit de un checkout limpio con el
+commit disponible de la Source mediante la ascendencia en el historial en caché.
+Para Claude, Agent Depot lee los archivos de estado de plugins y marketplaces. El
+Host posee lo que está instalado. Agent Depot posee el registro de selección y el
+recibo de lo que delegó. Mientras un Package está seleccionado o confirmado como instalado, sus
+Skills declarados no pueden adoptarse ni instalarse por separado. Un descriptor
+descubierto, por sí solo, no reserva sus Skills.
 
 ### Añadir una Source y descubrir sus bundles
 
@@ -834,8 +869,12 @@ evidencia de versión que Agent Depot registró. La evidencia en vivo procede de
 `~/.pi/agent/settings.json` y `~/.claude/plugins/installed_plugins.json`, que Agent
 Depot lee y nunca escribe. Un archivo de Host ausente es una vista vacía. Un archivo
 desviado o ilegible deja la búsqueda afectada en `unknown` y nunca lanza una
-excepción. Un paquete git de Pi sin versión se informa como `unknown`, nunca como
-`current`.
+excepción. Un paquete Git de Pi cuyo manifiesto no declara versión aún puede tener evidencia
+de commit verificada. Si Agent Depot verifica la identidad del checkout, pero detecta
+cambios locales, puede mostrar la versión del manifiesto de `HEAD`, pero no comparar
+el checkout para buscar actualizaciones. Si no puede verificar la raíz, el origen o
+`HEAD`, la versión instalada no está disponible. En ambos casos, el estado de
+actualización es `cannot assess`, no `current`.
 
 Una actualización registra una versión nueva solo cuando el estado del Host cambió de
 una forma que Agent Depot puede verificar, es decir, cuando las dos observaciones
@@ -863,8 +902,14 @@ comando del Host y deja la instalación del Host tal cual.
   de pin admitida por Claude.
 - Un plugin de Claude sin vinculación a un marketplace dentro del repositorio se
   informa pero no es instalable.
-- Agent Depot no lee la salida en prosa de la CLI del Host, incluido `pi list`. La
-  evidencia instalada procede solo de los archivos de estado del Host.
+- Agent Depot no usa la salida en prosa de la CLI del Host, incluido `pi list`, como
+evidencia del estado instalado. Para Pi, combina el ajuste de solo lectura con
+evidencia del checkout verificado. Para Claude, lee los archivos de estado del Host.
+Nunca escribe esos archivos.
+
+## Panel de agentes de Pi
+
+Agent Depot también incluye una extensión de Pi con el panel `/agents`. Muestra estado, actividad y consumo medido desde un proveedor conectado, con los agentes en ejecución primero y los más nuevos antes que los antiguos. Es un Package, no un Skill ni una App. Instalarlo junto a pstack requiere el adaptador coordinado de snapshots para evitar dos comandos `/agents`; sin proveedor, informa de que no hay datos disponibles. Consulta los [detalles de instalación y del proveedor](docs/pi-agents-panel.md).
 
 ## Exportar un Profile global de usuario
 

package/README.md

@@ -23,15 +23,19 @@ What it does:
   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
+  reading Host-owned installation and version evidence. 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.
+Agent Depot previews and confirms the filesystem changes it manages. This
+guarantee does not cover side effects from delegated commands. User-provided Skill
+methods, approved App recipes, and approved Package Host commands run as child
+processes. Agent Depot cannot fully preview or roll back their effects outside its
+managed changes. Agent Depot rejects unsafe paths and links in its managed
+filesystem operations.
 
 Requires Node.js >= 24 (Active LTS). The [interactive TUI](#interactive-tui)
 needs an interactive terminal.
@@ -66,13 +70,22 @@ npx @iseoane/agent-depot@latest tui
 pnpm dlx @iseoane/agent-depot@latest tui
 ```
 
-A global install is updated with the package manager that installed it:
+Check and update an npm global installation with Agent Depot:
 
 ```sh
-npm install --global @iseoane/agent-depot@latest
-pnpm add --global @iseoane/agent-depot@latest
+agent-depot self update
+agent-depot self update --yes
 ```
 
+The first command checks the public npm registry and previews a newer version without
+updating. The second repeats the check, previews its exact target, and applies it.
+Agent Depot supports this flow only when its loaded package directory matches the
+global directory reported by npm. It prints manual guidance for other installations,
+including pnpm, npx, project-local, linked, and unknown installations. The update uses
+npm without a shell, disables package lifecycle scripts, and never requests elevated
+privileges or changes npm configuration. If npm fails during installation, the global
+package may be left partially updated; Agent Depot cannot roll back npm's changes.
+
 A running Agent Depot never downgrades built-in Skills: a Skill installed by a newer
 Agent Depot is reported as not updatable (update Agent Depot first).
 
@@ -91,10 +104,10 @@ agent-depot source remove git:<source-id> --yes
 agent-depot source remove git:<source-id> --skill <id|path> --yes
 agent-depot source migrate git:<old-source-id> git:<new-source-id> --skill <path> --yes
 agent-depot discover builtin:agent-depot git:<source-id>
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
-agent-depot install --scope user-global --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
+agent-depot install --scope user-global --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
 # Only for an explicitly reviewed, untracked real-directory conflict:
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 agent-depot install --scope project --manifest --portable-v1 --yes
 agent-depot update check --scope project
 agent-depot update apply --scope project --all --yes
@@ -299,7 +312,7 @@ method object, for example:
 
 ```sh
 agent-depot install --scope user-global --source builtin:agent-depot \
-  --skill architecture --host pi --version latest \
+  --skill agent-depot-apprecipe --host pi --version latest \
   --method '{"kind":"command","argv":["node","scripts/install.mjs"],"cwd":"tools"}' \
   --portable-v1 --yes
 ```
@@ -358,7 +371,7 @@ requires both `--overwrite` and `--yes`:
 
 ```sh
 agent-depot install --scope project --source builtin:agent-depot \
-  --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+  --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 ```
 
 The preview is explicit about this distinction: without `--yes`, zero files or
@@ -446,14 +459,17 @@ agent-depot tui
 
 The TUI is an [Ink](https://github.com/vadimdemedes/ink) (React for terminals)
 front end over the same operations as the CLI. It needs Node.js >= 24 and an
-interactive terminal; otherwise `tui` fails with an error. Switch views with
-`1`-`5`, quit with `q` (not while a prompt is open). Every list scrolls when it is
-taller than the terminal. `j`/`k` or the arrow keys move.
+interactive terminal; otherwise `tui` fails with an error. It uses the terminal's
+alternate screen and returns to the previous screen when you quit. It adjusts to
+terminal resizing. Switch views with `1`-`5`, quit with `q` (not while a prompt is
+open). Lists scroll when they are taller than the terminal. In Sources, Catalog,
+Installations, and Updates, `j`/`k` or the arrows move one row; `PageUp` and
+`PageDown` move by one visible page.
 
 | View | Purpose |
 | --- | --- |
 | 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. |
+| 2 Catalog | Available Skills and Packages, grouped by Source. Host-confirmed installed Packages are hidden; selected-only Packages remain visible. An active Package-owned Skill stays at normal contrast with a compact owner badge; it cannot be marked or installed separately. Move the cursor to it to see why. |
 | 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. |
@@ -463,9 +479,9 @@ Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 | View | Keys |
 | --- | --- |
 | 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) |
+| Catalog | `Enter`/arrows expand and collapse, `space` toggle the highlighted loose Skill, `a` toggle all loose Skills in the highlighted Source that match the current filter, `i` install marked Skills that match the filter or the highlighted loose Skill, or preview the highlighted Package, `/` filter, `s` toggle one Source or all (when opened from a Source). Marks in other Sources remain unchanged. |
 | 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. |
+| 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 be checked" group. Rows in that group are informational and cannot be marked for an update. 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.
@@ -682,11 +698,25 @@ 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.
+runs them through the no-shell command runner after approval, and reads installed
+state from Host-owned files. Agent Depot reads those files and never writes them.
+For Pi, the `packages` setting in `~/.pi/agent/settings.json` identifies a
+configured package. Agent Depot then verifies the checkout under
+`$PI_CODING_AGENT_DIR/git` (or `~/.pi/agent/git` when unset): the checkout root,
+`origin`, `HEAD` commit, and `package.json` at that commit. If the root, origin, or
+`HEAD` cannot be verified, the package remains installed but its version is
+unavailable. If local changes make the checkout dirty, Agent Depot still displays
+the version from `HEAD` but withholds the commit, so Updates reports `cannot assess`.
+Installations and `package inspect` mark that label as `(HEAD; local changes)`.
+Tracked and untracked changes both count; Agent Depot does not ignore lockfiles or
+other local files. A manifest version is display evidence, not proof that the
+checkout matches the selected Source. Update assessment compares a clean checkout's
+commit with the available Source commit using ancestry in the cached Source history.
+For Claude, Agent Depot reads the plugin and marketplace state files. The Host owns
+what is installed. Agent Depot owns the selection record and the receipt for what it
+delegated. While a Package is selected or confirmed
+installed, its declared Skills cannot be adopted or installed separately. A
+discovered descriptor alone does not reserve its Skills.
 
 ### Add a Source and discover its bundles
 
@@ -767,7 +797,12 @@ 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`.
+A Pi git package with no version in its manifest can still have verified commit
+evidence. If Agent Depot verifies the checkout identity but finds local changes, it
+can display the manifest version from `HEAD` but cannot use that checkout for update
+comparison. If it cannot verify the checkout root, origin, or `HEAD`, the installed
+version is unavailable. In either case, the update status is `cannot assess`, not
+`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
@@ -793,8 +828,14 @@ and leaves the Host install as it is.
   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.
+- Agent Depot does not use Host CLI prose output, including `pi list`, as
+installed-state evidence. For Pi, it combines the read-only settings entry with
+verified checkout evidence. For Claude, it reads Host state files. Agent Depot
+never writes those Host files.
+
+## Pi agents panel
+
+Agent Depot also contains a Pi extension with an `/agents` panel. It displays agent status, activity and measured usage from a connected provider, placing running agents first and newer agents before older ones. This is a Package, not a Skill or App. Installing it alongside pstack requires the coordinated snapshot adapter to avoid duplicate `/agents` commands; without a provider, it reports unavailable data. See [installation and provider details](docs/pi-agents-panel.md).
 
 ## Export a user-global Profile
 

package/dist/src/cli.js

@@ -20,6 +20,7 @@ import { executeHostAddition, executeHostRemoval, planHostAddition, planHostRemo
 import { executeSkillRemoval, inspectSkillRemovals, planSkillRemoval, describeSkillRemoval, recheckSkillRemoval, removeSkillFiles, removeSkillsAndRecords, selectUserGlobalSkills, SkillSelectionError, userGlobalRemovalOptions, } from "./skill-removal.js";
 import { defaultProjectSkillTreeAccess, executeOrRejectMethod, executeSingleInstall, externalMethodFailure, isValidFixedVersion, findSource, installOne, outputInstallationResult, outputInstallPreview, outputSingleInstallPreview, planSingleInstall, refreshResolvedSource, rejectInstallationCollision, resolveSelection, rollbackTransactions, } from "./skill-install.js";
 import { CliUsageError } from "./usage-error.js";
+import { createSelfUpdateOperations } from "./self-update.js";
 import { selectionWithInstallation } from "./skill-update.js";
 import { applyConfirmedUpdates, describeUpdatePreview, findPathConfirmationProblem, loadUpdates, previewUpdateCandidates } from "./update-flow.js";
 import { assertNoOverlappingUserGlobalSkillRemovals, inspectUserGlobalSkillRemoval, scanUserGlobalSkillInventory, } from "./user-global-skill-inventory.js";
@@ -36,6 +37,7 @@ const USAGE = [
     "  agent-depot update check --scope <project|user-global> [--package <selection>...]",
     "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>... | --app <name>... | --package <selection>...) [--yes] [--confirm-path <relative-path>...]",
     "    Apps and Packages run after Skills; --all --scope project skips Apps and Packages.",
+    "  agent-depot self update [--yes] (npm global installations only; otherwise prints manual guidance)",
     "  agent-depot skill remove <id|path>... [--yes]",
     "  agent-depot skill remove <id|path> --host <host>... [--yes]",
     "  agent-depot skill host add <id|path> --host <host>... [--yes] [--confirm-additional-host]",
@@ -96,6 +98,11 @@ const COMMANDS = new Map([
             return 0;
         }],
     ["update", (values, { operations, dependencies, output }) => runUpdate(values, operations, dependencies, output)],
+    ["self", async (values, { dependencies, output }) => {
+            if (values[0] !== "update")
+                throw new CliUsageError("Usage: agent-depot self update [--yes]");
+            return runSelfUpdate(values.slice(1), dependencies, output);
+        }],
     ["skill", async (values, { operations, dependencies, output }) => {
             if (values[0] === "remove") {
                 await runSkillRemoval(values.slice(1), operations, dependencies, output);
@@ -698,6 +705,54 @@ async function runUninstall(argv, operations, dependencies, output) {
     }
     outputUninstallSummary(options, selectedInstallations.length, output);
 }
+function selfUpdateOperationsFor(dependencies) {
+    if (dependencies.selfUpdateOperations !== undefined)
+        return dependencies.selfUpdateOperations;
+    if (AGENT_DEPOT_PACKAGE_NAME === undefined || AGENT_DEPOT_PACKAGE_VERSION === undefined) {
+        throw new Error("Unable to determine the Agent Depot package name and version");
+    }
+    return createSelfUpdateOperations({
+        packageName: AGENT_DEPOT_PACKAGE_NAME,
+        packageVersion: AGENT_DEPOT_PACKAGE_VERSION,
+        packageRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.."),
+    });
+}
+async function runSelfUpdate(argv, dependencies, output) {
+    if (argv.length > 1 || (argv.length === 1 && argv[0] !== "--yes")) {
+        throw new CliUsageError("Usage: agent-depot self update [--yes]");
+    }
+    const confirmed = argv[0] === "--yes";
+    const selfUpdate = selfUpdateOperationsFor(dependencies);
+    const status = await selfUpdate.check();
+    switch (status.kind) {
+        case "unsupported":
+            output(`Self-update is unavailable: ${status.reason}`);
+            output("For a persistent global installation, use the package manager that installed it:");
+            output(`  npm install --global ${AGENT_DEPOT_PACKAGE_NAME ?? "@iseoane/agent-depot"}@latest`);
+            output(`  pnpm add --global ${AGENT_DEPOT_PACKAGE_NAME ?? "@iseoane/agent-depot"}@latest`);
+            output("For a one-off run, use:");
+            output(`  npx ${AGENT_DEPOT_PACKAGE_NAME ?? "@iseoane/agent-depot"}@latest tui`);
+            return 0;
+        case "current":
+            output(`Agent Depot ${status.current} is current`);
+            return 0;
+        case "ahead":
+            output(`Agent Depot ${status.current} is newer than npm's latest ${status.latest}; refusing to downgrade`);
+            return 0;
+        case "available":
+            output(`Preview: update Agent Depot from ${status.current} to ${status.latest}`);
+            output(`  command: npm install --global --no-audit --no-fund --no-update-notifier --logs-max=0 --ignore-scripts --registry=https://registry.npmjs.org/ ${AGENT_DEPOT_PACKAGE_NAME ?? "@iseoane/agent-depot"}@${status.latest}`);
+            output("  npm package scripts will not run; no elevated privileges will be requested");
+            requireConfirmation(confirmed, "Self-update not confirmed; rerun with --yes after reviewing the preview");
+            await selfUpdate.apply(status.latest);
+            output(`Updated Agent Depot to ${status.latest}; restart the CLI to use the new version`);
+            return 0;
+        default: {
+            const _exhaustive = status;
+            return _exhaustive;
+        }
+    }
+}
 async function runUpdate(argv, operations, dependencies, output) {
     const options = parseUpdateOptions(argv);
     const apps = dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory });

package/dist/src/git-source.js

@@ -238,6 +238,27 @@ export class GitSourceSnapshotAccess {
             files: Object.freeze(files),
         });
     }
+    /** True only when the cached Source history proves `olderCommit` precedes `newerCommit`. */
+    async isAncestor(source, olderCommit, newerCommit) {
+        if (![olderCommit, newerCommit].every((commit) => /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(commit))) {
+            return undefined;
+        }
+        try {
+            const destination = await this.requireMirror(source);
+            await this.runner.run("git", [
+                "--git-dir",
+                destination,
+                "merge-base",
+                "--is-ancestor",
+                olderCommit,
+                newerCommit,
+            ]);
+            return true;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Resolves the selected ref to an immutable commit without refreshing the mirror. */
     async readResolvedCommit(source) {
         const destination = await this.requireMirror(source);

package/dist/src/package-cli.js

@@ -383,7 +383,8 @@ function describeEvidence(evidence) {
     switch (evidence.kind) {
         case "installed": {
             if (evidence.version !== undefined) {
-                return `installed ${evidence.version}`;
+                const qualifier = evidence.reason === undefined ? "" : " (HEAD; local changes)";
+                return `installed ${evidence.version}${qualifier}`;
             }
             if (evidence.commit !== undefined) {
                 return `installed commit ${evidence.commit}`;