@jini-ai/agent-plugins 0.4.1 → 0.4.3

package/dist/lifecycle/manifest.js

@@ -1,5 +1,4 @@
 /**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
  * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins v1.0.0
  * `plugin.json` / `mcp.json` grammar (agent-plugins.org/specification), verified against the live
  * spec rather than inferred from an example manifest.
@@ -11,8 +10,7 @@
  * shares none of those fields and defines no execution/trust/capability model at all — see this
  * feature's own header comment in `install.ts` for why the two formats cannot be unified.
  *
- * Spec facts this module encodes, quoted/paraphrased from agent-plugins.org/specification (verified
- * 2026-08-12, not carried forward from an earlier round's inference):
+ * Pinned v1.0.0 rules from agent-plugins.org/specification:
  * - `plugin.json`'s `name`: 1-64 chars, lowercase alphanumeric/hyphen/period only, must start and
  *   end alphanumeric, no `--` or `..` consecutive delimiters (§5.5). Valid: `my-plugin`,
  *   `acme.tools`, `lint3r`, `a`. Invalid: `My-Plugin`, `-start`, `has--double`.
@@ -23,12 +21,8 @@
  *   returns them as `warnings`, never as a rejection reason.
  * - `mcp.json`'s top-level shape is `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }` —
  *   `mcpServers` MUST be an object whose member names identify servers.
- * - Each server entry MUST carry a `type` discriminator matching exactly one of three CLOSED
- *   variants (re-verified live against `agent-plugins.org/schemas/1.0.0/mcp.schema.json` and
- *   `/specification`, 2026-09-10 — superseding this file's earlier "not validated, no caller needs
- *   it" note, which is now false: `capability-projection.ts`'s MCP-server descriptors are no longer
- *   unconditionally `execute: { kind: "unavailable" }`, and launching a server needs its real
- *   transport config, not just its id):
+ * - Each server entry MUST carry a `type` discriminator matching one of three CLOSED variants.
+ *   Launching requires the actual transport config, not just a server id:
  *     - `stdio`: requires `command` (non-empty string); optional `args` (string[]), `env`
  *       (string-valued object — MUST NOT set `PLUGIN_ROOT`/`PLUGIN_DATA`, which the spec reserves),
  *       `cwd` (plugin-relative path).
@@ -58,11 +52,11 @@
  * own "receives a JS value, never a file path or raw bytes" contract. `install.ts` is the only
  * caller that reads the file and hands the parsed value here.
  */
+import { readPluginIdentity, validatePluginIdentity } from "@jini-ai/core/plugin-directory";
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 /**
  * The one plugin.json schema version this loader understands. A manifest declaring any other
- * value is rejected outright (C2 in the debate: "the standard is a Working Draft; the loader pins
- * v1 and must survive spec churn") rather than guessed at.
+ * value is rejected outright rather than guessed at: pinning the grammar must survive spec churn.
  */
 const PLUGIN_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 const MCP_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
@@ -91,13 +85,6 @@ function isJsonObject(value) {
 function coerceOptionalString(value) {
     return typeof value === "string" ? value : undefined;
 }
-/**
- * `value` narrowed to a `string[]` (non-string entries dropped), or `undefined` when `value`
- * itself isn't an array — `keywords`'s own coercion.
- */
-function coerceStringArray(value) {
-    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : undefined;
-}
 function parseManifestAuthor(value) {
     if (typeof value === 'string')
         return value; // Existing installed manifests may carry a string.
@@ -134,7 +121,7 @@ function resolveManifestName(raw) {
  * `plugin-runtime/discovery.ts`).
  * @complexity O(k + n) time and space in the input keys and keyword entries.
  */
-export function parseAgentPluginManifest({ value }) {
+export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu" } = {}) {
     if (!isJsonObject(value))
         return { ok: false, errors: ["plugin.json must be a JSON object"] };
     const raw = value;
@@ -152,15 +139,20 @@ export function parseAgentPluginManifest({ value }) {
         if (!KNOWN_MANIFEST_KEYS.has(key))
             warnings.push(`unrecognized plugin.json field '${key}' (ignored per spec)`);
     }
+    errors.push(...validatePluginIdentity({ manifest: raw, namespace: identityNamespace }).errors);
     if (errors.length > 0)
         return { ok: false, errors };
+    const identity = readPluginIdentity({ manifest: raw, namespace: identityNamespace });
+    warnings.push(...identity.warnings);
     const manifest = {
         name: nameResult.name,
+        id: identity.id,
+        provides: identity.provides,
         version: coerceOptionalString(raw.version),
         description: coerceOptionalString(raw.description),
         author: parseManifestAuthor(raw.author),
         license: coerceOptionalString(raw.license),
-        keywords: coerceStringArray(raw.keywords),
+        keywords: raw.keywords === undefined ? undefined : identity.keywords,
         ...(isJsonObject(raw.extensions) ? { extensions: raw.extensions } : {}),
     };
     return { ok: true, manifest, warnings };

package/dist/lifecycle/package-paths.d.ts

@@ -1,4 +1,6 @@
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/** Raised for any path a package entry (or a later read against an already-installed package) is
+ * not allowed to reach — lexically invalid, or resolving outside the package root. */
 export declare class PackagePathViolation extends Error {
     constructor({ message }: {
         readonly message: string;

package/dist/lifecycle/package-paths.js

@@ -1,10 +1,45 @@
+/**
+ * @file The one path-safety primitive every Agent Plugin package read goes through — extraction
+ * (`install.ts`) today, any future preview/read path tomorrow. One implementation, not two, so the
+ * containment guarantee cannot drift between "how a package is written" and "how it is later read".
+ *
+ * The rule is not invented here. The Agent Plugins spec (v1.0.0, "Path safety") states it as a MUST:
+ * "the filesystem-resolved path MUST remain within the filesystem-resolved plugin root... symlinks,
+ * junctions, reparse points, and equivalent filesystem mechanisms MAY resolve to targets within the
+ * plugin root, but clients MUST reject package paths that resolve outside it." The word
+ * "filesystem-resolved" is exactly what a lexical `../`-string check alone does not satisfy — a
+ * hostile archive can plant a symlinked directory at a lexically-clean path and let a later,
+ * innocent-looking entry walk through it (the two-step zip-slip vector; see `install.ts`'s header
+ * for the extraction-time mitigation, which is to refuse symlink ENTRIES outright rather than ever
+ * relying on this function to catch one after the fact).
+ *
+ * Architectural role:
+ * Pure path logic plus the minimum filesystem calls (`realpath`) the spec's own wording requires.
+ * No policy about what happens after containment is established — that is every caller's own job.
+ */
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import path from "node:path";
+/** Raised for any path a package entry (or a later read against an already-installed package) is
+ * not allowed to reach — lexically invalid, or resolving outside the package root. */
 export class PackagePathViolation extends Error {
     constructor({ message }, optional = {}) { super(message, optional); }
 }
 function buildModule(ports) {
     const realpath = ports.filesystem.realpath.bind(ports.filesystem);
+    /**
+   * Rejects an absolute path, a NUL byte, a Windows drive prefix, or a lexical `..`/`.` segment —
+   * BEFORE any filesystem call. This is the cheap majority of attempts; {@link assertContainedOnDisk}
+   * catches the rest (an entry that is lexically clean but is, or passes through, a symlink).
+   *
+   * Backslashes are normalized to `/` rather than rejected: the spec models paths as POSIX-style
+   * (`./`-prefixed), and an archive built on Windows may use them as its own separator without any
+   * hostile intent — the traversal segments that actually matter (`..`, an absolute prefix) are
+   * checked after normalization either way.
+   *
+   * @throws {PackagePathViolation} If the path is unsafe by construction, independent of any
+   * filesystem state.
+   * @complexity O(n) in the path's own length.
+   */
     function normalizePackageEntryPath(rawEntryPath) {
         if (rawEntryPath.includes("\0")) {
             throw new PackagePathViolation({ message: `package entry path contains a NUL byte: '${rawEntryPath}'` });
@@ -19,6 +54,30 @@ function buildModule(ports) {
         }
         return normalized;
     }
+    /**
+   * Resolves `entryPath` against `packageRoot` and asserts the REAL, symlink-resolved result is still
+   * inside the REAL, symlink-resolved root — the spec's "filesystem-resolved" requirement, not a
+   * string comparison.
+   *
+   * `packageRoot` is `realpath`'d fresh on every call rather than accepted pre-resolved from the
+   * caller, so a root whose own directory entry is later replaced by a symlink between two calls
+   * cannot smuggle a stale trusted root in.
+   *
+   * Handles the case extraction needs and a plain read doesn't: the target may not exist yet (mid-
+   * extraction, before this entry's own write), in which case the deepest EXISTING ancestor is
+   * `realpath`'d instead — so a symlinked PARENT directory planted by an earlier archive entry is
+   * still caught even though the leaf hasn't been created yet.
+   *
+   * @param packageRoot - Absolute path to the package root (extraction destination, or an already-
+   * installed package's root).
+   * @param entryPath - A package-relative path, as found in an archive entry name or a caller's own
+   * read request. Lexically validated internally via {@link normalizePackageEntryPath}.
+   * @returns The resolved (lexical, not yet realpath'd) absolute destination — safe for the caller to
+   * `open`/`mkdir`/`stat` against.
+   * @throws {PackagePathViolation} If the path is lexically unsafe, or the filesystem-resolved result
+   * (direct or via a symlinked ancestor) falls outside `packageRoot`.
+   * @complexity O(d) in path depth — one `realpath` per unresolved ancestor in the worst case.
+   */
     async function assertContainedOnDisk(packageRoot, entryPath) {
         const normalized = normalizePackageEntryPath(entryPath);
         const realRoot = await realpath(packageRoot);
@@ -42,6 +101,9 @@ function buildModule(ports) {
         const relative = path.relative(root, candidate);
         return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
     }
+    /** Walks up from `candidate` until an existing ancestor is found, `realpath`s that ancestor, and
+   * reattaches the non-existent tail — so a symlinked ancestor is caught even for a path whose leaf
+   * (and possibly several parent segments) have not been created yet. */
     async function realpathDeepestExistingAncestor(candidate) {
         let current = path.dirname(candidate);
         const tail = [path.basename(candidate)];

package/dist/lifecycle/persistent-state.d.ts

@@ -1,6 +1,10 @@
 import type { AgentPluginLifecyclePorts } from './ports.js';
 /** Reuses the platform lock with injected effects, never age-stealing a living migration. */
 export declare function createPersistentStateModule(ports: AgentPluginLifecyclePorts, _optional?: Record<string, never>): {
+    withIdentityLock: <T>(required: {
+        workspaceRoot: string;
+        run(): Promise<T>;
+    }, _optional?: {}) => Promise<T>;
     withPluginLock: <T>(required: {
         workspaceRoot: string;
         pluginId: string;
@@ -9,7 +13,7 @@ export declare function createPersistentStateModule(ports: AgentPluginLifecycleP
     memory: (required: {
         workspaceRoot: string;
         pluginId: string;
-    }, optional?: {}) => import("../../persistent-state.js").PluginMemory;
+    }, optional?: {}) => import("../../core/persistent-state.js").PluginMemory;
     assertOwnedPath: (required: {
         workspaceRoot: string;
         entryPath: string;

package/dist/lifecycle/persistent-state.js

@@ -1,4 +1,5 @@
-import { createPluginMemory, migratePluginLayout, assertPluginStatePath, withPluginStateLock } from '../../persistent-state.js';
+import { createPluginMemory, migratePluginLayout, assertPluginStatePath, withPluginStateLock } from '../../core/persistent-state.js';
+import path from 'node:path';
 import { withFileLock } from '@jini-ai/platform/fs/file-lock';
 import { createPackagePathsModule } from './package-paths.js';
 import { parseAgentPluginManifest } from './manifest.js';
@@ -16,6 +17,7 @@ export function createPersistentStateModule(ports, _optional = {}) {
         }),
     };
     return {
+        withIdentityLock: (required, _optional = {}) => effects.withLock({ lockPath: path.join(required.workspaceRoot, '.publisher-identity.lock'), run: required.run }),
         withPluginLock: (required, optional = {}) => withPluginStateLock({ ...effects, ...required }, optional),
         memory: (required, optional = {}) => createPluginMemory({ ...effects, ...required }, optional),
         assertOwnedPath: (required, optional = {}) => assertPluginStatePath({ ...effects, ...required }, optional),

package/dist/lifecycle/ports.d.ts

@@ -52,6 +52,12 @@ export interface AgentPluginOutboundGuardPort {
     }): Promise<void>;
 }
 export interface AgentPluginLifecyclePorts {
+    /** Optional host admission serializes cross-kind identity checking and publication. */
+    readonly identityAdmission?: (<T>(required: {
+        id: string;
+        localId: string;
+        run: () => Promise<T>;
+    }, optional?: Record<string, never>) => Promise<T>) | undefined;
     readonly onEvent?: ((required: {
         readonly event: string;
         readonly message: string;
@@ -69,6 +75,18 @@ export interface AgentPluginLifecyclePorts {
     readonly layout: AgentPluginLayoutPort;
     readonly productName: string;
     readonly extensionNamespace: string;
+    /** Host boot policy may migrate every workspace before seeding the requested workspace.
+     * A failure refuses all publication; absent uses the owner's single-workspace migration. */
+    readonly migrateBeforeSeed?: ((required: {
+        readonly layout: AgentPluginLayoutPort;
+        readonly workspaceId: string;
+    }, optional: Record<string, never>) => Promise<{
+        readonly complete: boolean;
+    }>) | undefined;
+    /** Host-facing recovery instructions; the bundled refusal and its security gate remain owned here. */
+    readonly formatBundledUninstallRecovery?: ((required: {
+        readonly pluginId: string;
+    }, optional: Record<string, never>) => string) | undefined;
     readonly readServerMetadata?: AgentPluginServerMetadataReader | undefined;
     readonly deliveryMode: AgentPluginDeliveryMode;
     readonly mcpProvisioning: AgentPluginMcpProvisioningPort;
@@ -76,6 +94,6 @@ export interface AgentPluginLifecyclePorts {
     readonly outboundGuard: AgentPluginOutboundGuardPort;
 }
 /** Application policy/effects are required; observers and metadata translators are optional. */
-export type AgentPluginLifecycleRequired = Omit<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata'>;
-export type AgentPluginLifecycleOptional = Pick<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata'>;
+export type AgentPluginLifecycleRequired = Omit<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery' | 'identityAdmission'>;
+export type AgentPluginLifecycleOptional = Pick<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery' | 'identityAdmission'>;
 //# sourceMappingURL=ports.d.ts.map

package/dist/lifecycle/resolve-agent-plugin-refs.d.ts

@@ -1,4 +1,16 @@
-import type { AgentPluginDeliveryMode, InstalledAgentPlugin } from "./types.js";
+import type { /**
+ * How a pinned ref's content reaches the agent.
+ *
+ * - `inject` — the whole eponymous SKILL.md (~15KB for `ui-ux-design`) plus every other package file
+ *   listed by absolute path, in the run's prompt prefix. Today's shipped behaviour, and the default.
+ * - `pointer` — ~400 bytes naming the exact tool call that returns that SAME SKILL.md, and nothing
+ *   else. The content is identical; only the delivery differs, which is what makes the two a
+ *   controlled comparison rather than two different experiments.
+ *
+ * Selected per-process by the host-supplied `deliveryMode` port. This is a MEASUREMENT AFFORDANCE, not a
+ * migration flag: pointer and inject must coexist to compare delivery of identical content.
+ * Selecting an unconditional mode requires the measurement result.
+ */ AgentPluginDeliveryMode, InstalledAgentPlugin } from "./types.js";
 import type { AgentPluginWorkspaceLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 export type { AgentPluginDeliveryMode } from "./types.js";

package/dist/lifecycle/resolve-agent-plugin-refs.js

@@ -1,24 +1,105 @@
+import { listInstalledPackageRoots, INSTALLED_PLUGIN_DIGEST_PATTERN } from "./installed-package-roots.js";
+/**
+ * @file Resolves a run's pinned Agent Plugin refs (`pluginRefIds` — `run-start-context.ts`'s
+ * decoded `contextRef` field, itself sourced from the composer's `pluginRefId` chips,
+ * `composer-capabilities.ts`'s own doc) into the real prompt-prefix text `agent-daemon-server.ts`'s
+ * `onStarted` prepends to the run's prompt.
+ *
+ * ---------------------------------------------------------------------------
+ * The activation-record gap this function works around (KNOWN GAP, not silently papered over)
+ * ---------------------------------------------------------------------------
+ * `activation.ts` owns the per-workspace enabled decision; a disabled or undetermined ref is
+ * refused before resolution.
+ * What that record deliberately does NOT carry is which installed DIGEST is current for a plugin id.
+ * For a BUNDLED plugin, `bundled-digests.ts`'s ledger answers that: the boot seeder
+ * records which digest the running build published, so a workspace holding an upgraded plugin's old
+ * and new package is no longer ambiguous — the build's own record names the winner. For every other
+ * plugin id, closing this needs the operator-facing upgrade/pin flow (and, alongside it, the
+ * admission gate for MCP servers `capability-projection.ts`'s own header names) and remains a
+ * separate, later decision.
+ *
+ * So this function still scans every digest this workspace has ever installed under
+ * `packages/sha256/*` and matches on the installed `plugin.json`'s own `name` field, after dropping
+ * any digest of a bundled plugin the ledger records as superseded:
+ *
+ * - Exactly one match: resolves normally.
+ * - Zero matches: fails with a "not installed" reason — the operator pinned a chip for a plugin
+ *   that is not (or no longer) actually on disk for this workspace.
+ * - More than one match: fails with an explicit ambiguity reason naming every matching digest.
+ *   Silently picking one (e.g. the lexicographically-last, or "the newest") would be a WORSE
+ *   failure mode than an explicit error — a wrong plugin's content would reach the agent, and
+ *   nothing about the run would look wrong until someone noticed the agent's advice didn't match
+ *   what was supposedly pinned. An explicit error is loud and immediately actionable instead. That
+ *   refusal is UNCHANGED and still the default: the ledger narrows a plugin id only when the build
+ *   itself published one of the installed digests, which is authority rather than a guess, and it
+ *   has no say at all over packages an operator installed (`bundled-digests.ts`, consequence 1).
+ *
+ * ---------------------------------------------------------------------------
+ * What gets injected, and why not the whole 280K package
+ * ---------------------------------------------------------------------------
+ * Only the resolved plugin's own eponymous skill — `skills/<pluginRefId>/SKILL.md` (the skill
+ * folder whose name equals the plugin's own id; for `ui-ux-design` specifically, this is real,
+ * ~5.5KB content, not all seven of that plugin's skill folders). The reasoning mirrors
+ * `capability-projection.ts`'s own "Skills get a real executable binding" rule: a Skill's markdown
+ * IS the plugin's real, agent-facing content, while the rest of the package (references,
+ * examples, scripts) is supporting material a plugin's own SKILL.md is written to point an agent
+ * at when it needs more depth (the Agent Plugins spec's own convention every skill in this package
+ * follows). Injecting the FULL package indiscriminately would balloon every run's prompt with
+ * pages this specific task usually never needs. Every OTHER file in the resolved package is still
+ * listed by absolute path — genuinely `Read`-able by the spawned CLI agent, which runs with real
+ * filesystem access unlike a browser-facing preview — so nothing is unreachable, only deferred to
+ * an explicit follow-up read.
+ *
+ * Architectural role:
+ * Server-side only (reads `node:fs/promises`, imports `install.ts`'s `indexInstalledRoot`) — never
+ * imported into a browser bundle. Returns a discriminated result rather than throwing, so
+ * `agent-daemon-server.ts`'s `onStarted` gets one place to branch on success/failure without a
+ * second try/catch layer duplicating this module's own error classification.
+ */
 import { createPersistentStateModule } from "./persistent-state.js";
-/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import path from "node:path";
 import { createPackagePathsModule } from "./package-paths.js";
-import {} from "./activation.js";
 import { createActivationModule } from "./activation.js";
-import {} from "./bundled-digests.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
 import { createInstallModule } from "./install.js";
 import { createCapabilityProjectionModule } from "./capability-projection.js";
 function buildModule(ports) {
     const persistentState = createPersistentStateModule(ports);
     const { assertContainedOnDisk } = createPackagePathsModule(ports);
-    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
     const stat = ports.filesystem.stat.bind(ports.filesystem);
     const { resolveAgentPluginActivation } = createActivationModule(ports);
     const { preferBundledAgentPluginDigests, readBundledAgentPluginDigests } = createBundledDigestsModule(ports);
     const { indexInstalledRoot } = createInstallModule(ports);
     const { readInstalledSkillMarkdown } = createCapabilityProjectionModule(ports);
-    const SHA256_DIGEST_DIRNAME_PATTERN = /^[a-f0-9]{64}$/;
+    /** Reads the delivery mode for this process. An unset or unrecognised value is `inject` — an A/B
+   *  affordance must never be able to change production behaviour by typo. */
     function resolveAgentPluginDeliveryMode() { return ports.deliveryMode; }
+    /**
+   * Resolves every pinned `pluginRefId` into real on-disk text and joins the results into one
+   * prompt-prefix block, in the order the refs were pinned.
+   *
+   * @param pluginRefIds - This run's pinned Agent Plugin ids (`run-start-context.ts`'s decoded
+   *   `pluginRefIds` — already filtered to non-empty strings by that point). An empty array resolves
+   *   to an empty prefix with no filesystem access at all — the common case (no plugin pinned).
+   * @param workspaceLayout - This run's own workspace's Agent Plugin layout
+   *   (`resolveAgentPluginLayout().forWorkspace(workspaceId)`), never a shared/instance-level one —
+   *   see `layout.ts`'s own tenant-isolation header for why a workspace's installed packages must
+   *   never be resolved against another workspace's tree.
+   * @returns `{ ok: true, promptPrefix }` once every ref resolves, or the FIRST `{ ok: false, reason }`
+   *   encountered — a run pinning two refs where the second is ambiguous still fails clearly, rather
+   *   than partially augmenting the prompt with only the first ref's content.
+   * @complexity O(r * d) where r is `pluginRefIds.length` and d is the number of installed digests in
+   *   this workspace — each ref independently re-scans the (typically small) digest list, since a
+   *   different ref may resolve to a different digest.
+   */
+    // Read ONCE for the whole call, not per ref: it is one small file, and every ref resolves against
+    // the same workspace's ledger. See `bundled-digests.ts` for why this can only ever RESOLVE an
+    // ambiguity below, never create one.
+    // See activation.ts for the shared activation rule. One small file read per pinned ref; the
+    // fail-CLOSED `resolveAgentPluginActivation` (the same reader the per-call tool gate uses)
+    // refuses on a corrupt/unreadable file instead of reading it as "nothing recorded" — injecting a
+    // plugin's guidance SPENDS it exactly like a tool call, so this surface must refuse rather than
+    // read a fault as consent.
     async function resolveAgentPluginRefs(pluginRefIds, workspaceLayout, deliveryMode = resolveAgentPluginDeliveryMode()) {
         if (pluginRefIds.length === 0)
             return { ok: true, promptPrefix: "" };
@@ -35,6 +116,12 @@ function buildModule(ports) {
         }
         return { ok: true, promptPrefix: sections.join("\n\n") };
     }
+    /** The run-start refusal for one ref's activation verdict, or `undefined` when it may be injected.
+   *  @complexity O(1). */
+    // A distinct reason from "not installed", because the operator's remedy is different: the bytes
+    // ARE here and the fix is to enable the plugin, not to install it. Telling them to install
+    // something already present is the kind of wrong-but-plausible error message that costs an
+    // afternoon.
     function activationRefusal(pluginRefId, verdict) {
         if (verdict.verdict === "active")
             return undefined;
@@ -45,47 +132,57 @@ function buildModule(ports) {
         return (`Agent Plugin '${pluginRefId}' is installed in this workspace but is not enabled — it ships with ${ports.productName} and ` +
             "stays inactive until an operator turns it on. Enable it before pinning it to a run.");
     }
+    /** Every installed digest's `InstalledAgentPlugin`, indexed once per call to
+   *  {@link resolveAgentPluginRefs} — one `readdir` plus one `indexInstalledRoot` walk per digest.
+   *  Digest directory names that do not match the expected 64-hex-character shape are skipped rather
+   *  than passed to `indexInstalledRoot` — `packages/sha256/` is not asserted empty of anything else
+   *  a future tool might place there, and a non-digest entry is not this function's to interpret.
+   *
+   *  Exported for a second caller outside this module: `tool-registrations.ts`'s
+   *  `loadInstalledAgentPluginToolSources` needs the SAME per-digest walk (every installed digest,
+   *  whichever skills each one carries) to build one `agent_plugin_<pluginId>` tool per installed
+   *  plugin — the exact shape this function already builds, just consumed differently than
+   *  `resolveOnePluginRef`'s own "resolve one pinned ref" use below. Reusing this rather than
+   *  re-walking `packages/sha256/*` a second, less-validated way keeps the digest-directory-name check
+   *  and the per-digest failure isolation in exactly one place. */
     async function listInstalledPlugins(workspaceRoot) {
-        let folders;
-        try {
-            folders = await readdir(workspaceRoot, { withFileTypes: true });
-        }
-        catch (error) {
-            if (isEnoent(error))
-                return [];
-            throw error;
-        }
         const installed = [];
-        for (const folder of folders) {
-            if (!folder.isDirectory() || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(folder.name) || folder.name.length > 64)
-                continue;
-            const packagesDir = path.join(workspaceRoot, folder.name, "package", "sha256");
-            let entries;
+        for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
             try {
-                await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
-                entries = await readdir(packagesDir, { withFileTypes: true });
+                const plugin = await indexInstalledRoot(root.packageRoot, root.archiveDigest);
+                if (plugin.pluginId === root.localId)
+                    installed.push(plugin);
             }
             catch {
-                continue;
-            }
-            for (const entry of entries) {
-                if (!entry.isDirectory() || !SHA256_DIGEST_DIRNAME_PATTERN.test(entry.name))
-                    continue;
-                try {
-                    const packageRoot = await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
-                    const plugin = await indexInstalledRoot(packageRoot, entry.name);
-                    if (plugin.pluginId === folder.name)
-                        installed.push(plugin);
-                }
-                catch {
-                    // One corrupt package never hides another plugin. Memory-only folders are not installs.
-                }
+                // One corrupt package never hides another plugin. Memory-only folders are not installs.
             }
         }
         return installed;
     }
+    /**
+   * Whether one installed archive digest still has its package directory under `packagesDir` — the
+   * cheap, per-call "is this still installed" signal `tool-registrations.ts`'s tool gate needs.
+   *
+   * Lives here, beside {@link listInstalledPlugins}, because it must agree with that walk about two
+   * things a second implementation would eventually get wrong: that an installed package root IS
+   * `<packagesDir>/<digest>` and nothing else, and that a directory name is only a digest when it
+   * matches the 64-hex shape. It deliberately does NOT re-index the package (`indexInstalledRoot`
+   * reads and validates a manifest, which is far too much per tool call): directory presence is
+   * exactly what `uninstall.ts` removes, and it removes it by `rename` BEFORE it touches the
+   * activation record, so the gate observes a removal at least as early as it observes the record's
+   * deletion, never later.
+   *
+   * Follows symlinks (plain `stat`, not `lstat`) on purpose — `listInstalledPlugins` does too, so a
+   * deployment whose digest directory is a symlink registers a tool that this would otherwise refuse
+   * to authorize.
+   *
+   * @returns `false` for a digest that does not match the installed-directory grammar, for a missing
+   * directory, for a non-directory at that path, and for ANY filesystem fault — every answer this
+   * cannot establish positively is `false`, because its one caller uses it to authorize.
+   * @complexity One `stat`.
+   */
     async function isInstalledDigestPresent(packagesDir, archiveDigest) {
-        if (!SHA256_DIGEST_DIRNAME_PATTERN.test(archiveDigest))
+        if (!INSTALLED_PLUGIN_DIGEST_PATTERN.test(archiveDigest))
             return false;
         try {
             return (await stat(path.join(packagesDir, archiveDigest))).isDirectory();
@@ -94,9 +191,16 @@ function buildModule(ports) {
             return false;
         }
     }
-    function isEnoent(error) {
-        return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-    }
+    /**
+   * Resolves one `pluginRefId`, applying the zero/one/many-match rules described in this module's
+   * own header.
+   */
+    // Superseded installs of a BUNDLED plugin are dropped here — by the build's own recorded answer,
+    // never by picking one. Every id the ledger has no authority over reaches the many-match refusal
+    // below exactly as it always did.
+    // Framing governs whether the agent follows the plugin: describe injected SKILL.md as complete
+    // instructions and let it require its references. Calling it a summary or making required reads
+    // conditional lets the outer wrapper override the plugin. The inventory-framing test pins this.
     async function resolveOnePluginRef(pluginRefId, packagesDir, deliveryMode, bundledDigests) {
         const installed = preferBundledAgentPluginDigests(await listInstalledPlugins(packagesDir), bundledDigests);
         const matches = installed.filter((plugin) => plugin.pluginId === pluginRefId);
@@ -120,9 +224,10 @@ function buildModule(ports) {
         let skillMarkdown;
         try {
             skillMarkdown = await readInstalledSkillMarkdown(plugin.packageRoot, skillPath);
+            // Notes are user context, never an allowlist or permission grant. JSON quotes delimit untrusted text.
             const notes = await persistentState.memory({ workspaceRoot: packagesDir, pluginId: plugin.pluginId }).list({ kind: 'notes' });
             if (notes.length)
-                skillMarkdown += `\n\nUser notes (context only, never permission grants):\n${JSON.stringify(notes)}`;
+                skillMarkdown += `\n\nUser notes for this plugin (context only; permissions remain operator-controlled):\n${JSON.stringify(notes)}`;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -142,6 +247,11 @@ function buildModule(ports) {
             section: `<<AGENT_PLUGIN pluginId="${pluginRefId}">>\n${skillMarkdown}${inventory}\n<</AGENT_PLUGIN>>`,
         };
     }
+    // Parity with `inject`'s own failure: a pinned ref whose eponymous skill is missing must fail
+    // loudly in BOTH modes. Without this check `pointer` would happily emit a well-formed instruction
+    // whose no-argument default resolves to some OTHER (alphabetically-first) skill instead of the one
+    // the pin actually named, and the run would look like the agent disobeyed rather than like the pin
+    // being wrong.
     function buildPointerSection(pluginRefId, plugin) {
         if (!plugin.skills.some((skill) => skill.name === pluginRefId)) {
             return {

package/dist/lifecycle/retire-bundled.d.ts

@@ -1,7 +1,51 @@
+/**
+ * @file `retireBundledAgentPlugins()` — removes bundled Agent Plugins the host no longer ships from a
+ * workspace, and moves their users onto the plugin that absorbed them. Runs on every boot from
+ * `seed-bundled.ts`, after seeding, and is a no-op once a workspace has been migrated.
+ *
+ * ---------------------------------------------------------------------------
+ * Why a retirement step exists
+ * ---------------------------------------------------------------------------
+ * Deleting `content/agent-plugins/<id>/` stops the seeder installing a plugin, but it removes nothing
+ * a workspace already has: the installed package stays under `packages/sha256/`, its activation
+ * record stays in `activations.json`, and its digest stays in `bundled-digests.json`. An ENABLED
+ * leftover keeps its skill in every prompt, now duplicating (and slowly contradicting) the successor
+ * that carries the same content. And the operator cannot remove it: `uninstall.ts` refuses a
+ * bundled plugin because it would be re-seeded, which is exactly what stops being true here. Owner
+ * rule: the user never fixes anything by hand, so the boot does it.
+ *
+ * ---------------------------------------------------------------------------
+ * What happens per retired id (idempotent)
+ * ---------------------------------------------------------------------------
+ * 1. Nothing installed and no activation record: nothing to do (the second boot after a migration).
+ *    A leftover ledger entry is still dropped.
+ * 2. The retired plugin was ENABLED (explicitly, or by the "absent means active" default while its
+ *    package is installed): the successor is switched on — unless an operator explicitly turned the
+ *    successor off, which is left exactly as it is and reported in the outcome. No silent override.
+ * 3. The retired plugin's package(s) and activation record are removed through `uninstall.ts`
+ *    (`retiredBundled: true` skips only its bundled refusal). A record with no package left is
+ *    deleted directly.
+ * 4. The retired id is dropped from `bundled-digests.json`.
+ *
+ * A malformed or unreadable activation record for the retired id stops that id's retirement with a
+ * `failed` outcome and changes nothing: whether the operator had it enabled cannot be established,
+ * so neither enabling the successor nor deleting the record is safe. The next boot retries.
+ *
+ * Out of scope on purpose: nothing a retired plugin could own survives it. Agent Plugins have no
+ * per-plugin settings store (a workspace's `data/<pluginId>` directory has no production writer),
+ * and custom credentials (a saved `fly.io` token, say) belong to the workspace, not to a plugin.
+ *
+ * Architectural role:
+ * Composition over `activation.ts`, `uninstall.ts`, and `bundled-digests.ts`. Never throws: every
+ * failure is captured per id, exactly like `seed-bundled.ts`'s own outcomes, so one stuck retirement
+ * cannot stop a workspace from booting.
+ */
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
-import { type BundledAgentPluginEnableOutcome } from "./activation.js";
+import type { BundledAgentPluginEnableOutcome } from "./activation.js";
 import type { AgentPluginLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/** What happened to the successor. `not-needed`: the retired plugin was off, so the successor was
+ *  left as it was. The other three are {@link BundledAgentPluginEnableOutcome}. */
 export type RetiredAgentPluginSuccessorOutcome = BundledAgentPluginEnableOutcome | "not-needed";
 export type RetiredAgentPluginOutcome = {
     readonly pluginId: string;
@@ -11,9 +55,12 @@ export type RetiredAgentPluginOutcome = {
     readonly pluginId: string;
     readonly successorId: string;
     readonly status: "retired";
+    /** Every installed archive digest removed; empty when only a record or ledger entry was left. */
     readonly removedDigests: readonly string[];
     readonly activationRemoved: boolean;
     readonly ledgerEntryRemoved: boolean;
+    /** `left-disabled-by-operator` is the one case a caller should surface: the retired plugin was
+     *  on, its successor was explicitly turned off, and this step did not override that. */
     readonly successor: RetiredAgentPluginSuccessorOutcome;
 } | {
     readonly pluginId: string;
@@ -22,10 +69,12 @@ export type RetiredAgentPluginOutcome = {
     readonly reason: string;
 };
 export interface RetireBundledAgentPluginsRequired {
+    /** The INSTANCE-level layout, for the same reason `seed-bundled.ts` takes one. */
     readonly layout: AgentPluginLayout;
     readonly workspaceId: string;
 }
 export interface RetireBundledAgentPluginsOptional {
+    /** Defaults to {@link RETIRED_BUNDLED_AGENT_PLUGINS}; tests pass their own. */
     readonly retired?: (ReadonlyMap<string, string>) | undefined;
     readonly now?: ((required: Record<string, never>) => Date) | undefined;
 }

package/dist/lifecycle/retire-bundled.js

@@ -1,5 +1,3 @@
-/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
-import {} from "./activation.js";
 import { createActivationModule } from "./activation.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
@@ -9,6 +7,13 @@ function buildModule(ports) {
     const { removeBundledAgentPluginDigest } = createBundledDigestsModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
     const { uninstallAgentPlugin } = createUninstallModule(ports);
+    /**
+   * Retires every id in `retired` from one workspace. See this file's header for the steps.
+   *
+   * @returns One outcome per retired id, in map order.
+   * @throws Nothing.
+   * @complexity O(r) retired ids, each one `listInstalledPlugins` walk plus a few small file writes.
+   */
     async function retireBundledAgentPlugins(required, optional = {}) {
         const outcomes = [];
         for (const [pluginId, successorId] of optional.retired ?? ports.retiredBundledPlugins) {
@@ -21,6 +26,8 @@ function buildModule(ports) {
         }
         return outcomes;
     }
+    // The successor first: if a later step fails, the operator keeps the capability, and the next boot
+    // (which finds this step already done) retries only what is left.
     async function retireOne(required, optional, pluginId, successorId) {
         const workspaceLayout = required.layout.forWorkspace({ workspaceId: required.workspaceId });
         const workspaceRoot = workspaceLayout.root;