@llblab/pi-actors 0.57.1 → 0.58.0

package/AGENTS.md

@@ -52,6 +52,8 @@ Pi host
 
 `index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic. Prefer cohesive existing owners over per-phase or per-iteration modules; file size alone does not justify extraction. Earn new files through a real ownership, dependency, authority or reuse boundary. Colocation must preserve distinct typed admission/privacy contracts, not collapse them into generic helpers or broad facades. For architecture-affecting work, load and follow `.agents/skills/domain-dag/SKILL.md`; its validator is local agent tooling, not an npm, CI, or release gate.
 
+For product validation launched from an Actor, clear only `PI_ACTORS_DELIVERY_OWNER_ID`, `PI_ACTORS_DELIVERY_PARENT_RUN`, `PI_ACTORS_DELIVERY_PARENT_INSTANCE` and `PI_ACTORS_DELIVERY_PARENT_STATE_DIR` in the test command's environment. SDK fixtures are independent coordinators; inheriting the validation Actor's lineage can suppress their completion. Keep the launcher's own Run lineage, standard test preload, cases and watchdogs unchanged. Use Node24 for CI-equivalent release validation.
+
 The committed `dist/` tree is required for npm and git package installs. `npm run build` compiles into a temporary candidate and atomically replaces the distributive; `npm run build:check` must reject source/artifact drift without rewriting the working tree.
 
 Unit-owner files may construct real SDK sessions. Under a zero-SDK-session bound, do not use a broad negative `--test-name-pattern` as an execution guard: Node24 matches test ancestors, including `<root>`, and can admit forbidden leaves. Before execution, prove the declaration/import/ancestor closure with explicit positive leaf names and/or supported `--test-skip-pattern` exclusions. If exclusion is unproved, stop. Budget session-only lifecycle constructors separately from public fixture Runs and driver/provider/reopen sessions; passing logs never retroactively authorize excess.
@@ -166,6 +168,12 @@ The user-requested JSONL bundle/CodeMode direction is recorded in docs/compositi
 
 `~/.pi/agent/recipes/*.json` is executable capability memory. Preserve filename identity, atomic writes, canonical per-path locks with atomic owner publication and non-blocking abandoned staging, explicit operator-gated changes, and transportability.
 
+The adopted [capability-memory direction](docs/capability-memory.md) separates retaining a reusable Recipe from exposing a named tool. Sync/async is an execution contract, not a maturity/usefulness score or automatic registration rule; subagent-backed tools are capability launchers, not persisted live Runs. Explicit `register_tool expose=false` creates a new template/from Recipe under `recipes/library` without host activation or tool-map mutation. Its retained_recipe/not_requested receipt omits global callability flags because an unrelated same-named tool may already be active. Keep it create-only, source/size-admitted and exclusively published with root/library/target fences; preserve uncertain committed bytes and original causes. Retained update/delete/draft promotion and direct disposable-draft references are unsupported. Automatic retained lifecycle is not implemented: current root-based exposure and review actions remain unchanged. Read-only Recipe inspection now inventories `recipes/library` separately, in the same active Skill context, without granting review/callability/Run status. Keep library files outside automatic tool discovery, including older-host behavior. Do not invent automatic-review actions or Recipe exposure flags, or migrate the live portfolio from this implementation alone.
+
+Structural review and launch counts do not establish semantic purpose, good tool names, successful reuse, or accepted outcomes. Missing evidence is unknown, not a reason to fabricate usefulness or irreversibly discard a potentially useful capability. Preserve value-free review and unchanged-source executor boundaries; semantic evidence and new retention/exposure transitions require their own privacy, provenance, transaction and acceptance contract.
+
+Retained usage belongs to the parent Recipe root's existing `.usage` owner. Keep private `library/<stem>` lineage distinct from a same-stem tool entrypoint; that ledger label is not a public Recipe reference. Missing files and matching content do not authorize implicit lineage transfer between retained and tool/draft namespaces. Preserve explicit transaction/move ownership and unknown legacy nested evidence rather than guessing a migration.
+
 Automatic review receives value-free structural projections, not executable content, paths, prose, canonical names, or secrets. Deterministic executors derive unchanged Recipes from trusted captures. Approved mutation must journal intent before mutation and roll forward safely after crashes.
 
 `PI_ACTORS_AUTOMATIC_REVIEW=off` disables scheduling and safe-boundary activation while remaining visible in runtime status.

package/BACKLOG.md

@@ -6,6 +6,7 @@ Task IDs name bounded work, not execution order. The operator authorizes autonom
 
 ## Next bounded work
 
+- **Capability memory:** P1.3 must admit the evidence contract before P1.2c can change automatic retention/exposure. These future slices are separate from the explicit manual workflow; source/package acceptance does not authorize live migration or reload an already running host.
 - **Separate remaining owners:** F1.7 (one rollout candidate) remains the last open F1 owner; the migrated surfaces do not by themselves prove the loaded rollout or registry notice layout. Registry activation/promotion/deletion notice text stays outside the completed refusal migration. Inspector popup color recognition is verified against current producer results; a later feedback syntax change must update that anchored recognition with it.
 - **Explicit gates:** U1 requires authorized loaded-host observation/reload; N1.2p needs actual Windows profile evidence, N1.3 an asset-distribution decision, and N1.6 separate activation admission. Original-clock/native-scope, macOS research and composition decisions retain their own B/C/T gates. Existing release permission does not adopt them.
 - **Evidence reuse:** Reuse the accepted three-OS SOURCE/PACKED quit witnesses for B2.4; extend only the missing descendants/triggers/same-ID/crash cases. N1.9 stays a gated unresolved risk, not an instruction to repeat the completed ownership inquiry.
@@ -185,6 +186,18 @@ Exit: Any later cleanup is independently justified and validated against its own
 
 - [ ] **R1.2 — Remove temporary diagnostics after native acceptance.** Gate on N1.7; remove only proven temporary/redundant instrumentation, preserve owned regressions, then refresh invalidated focused checks and final candidate-bound packaging/native evidence. A dirty status note or earlier executable result is not final-tarball proof.
 
+## 8. Capability memory separate from tool exposure
+
+Outcome: Implement the [adopted capability-memory direction](docs/capability-memory.md): a reviewed Recipe can be retained without becoming a tool; sync/async remains execution policy. Success means easier, coherent management: one existing Recipe inspection surface distinguishes retained definitions from exposed tool candidates, with exact reuse references and no confusion with running instances. Existing explicit registration remains valid for both modes; no automatic-policy or live portfolio migration is authorized by local implementation alone.
+
+### P1 — Retention, evidence and deliberate exposure
+
+Exit: Retain/defer/expose/withdraw have explicit evidence and replay-safe transitions in existing owners; useful async capabilities remain eligible and unsuitable sync captures are not exposed solely by mode. Current activation, privacy, source identity and lineage contracts survive source/packed acceptance. No second runtime, resolver or tool registry.
+
+- [ ] **P1.2c — Integrate automatic lifecycle transitions.** After P1.3, extend the explicit manual path with CAS/recovery-safe retain/defer/expose/withdraw transitions through existing review transactions, without duplicate capability copies or demotion churn. Specify retention bounds and distinguish evidence deferral from safety rejection and admitted expiry/disposal before enabling automatic retention. Verify: draft/tool transaction, projection and recovery properties.
+- [ ] **P1.3 — Ground automatic exposure in admitted evidence.** Define the privacy/provenance/budget contract for any semantic or accepted-outcome evidence before using it; keep structural-only review honest and non-destructive on uncertainty. Do not infer task success from launches, invent names from opaque shape, weaken confidentiality or permit automatic executable rewrites. Verify: review/projection safety properties and controlled same-shape/different-purpose, failed-launch and insufficient-evidence cases.
+- [ ] **P1.4 — Accept and evaluate the automatic policy.** After P1.2c/P1.3, update owning Skills and current user docs and prove the automatic transitions in isolated source/packed portfolios. Reuse the explicit manual workflow witnesses when their source/activation semantics are unchanged; refresh only affected boundaries. Compare accepted useful reuse and selection cost against baseline, not tool counts. Any live migration requires an exact admitted portfolio plan and applicable operator authority; loaded-host claims require separate observation. Verify: registration-truth, agent journeys, installed-package and controlled policy evaluation.
+
 ## Evidence and scope notes
 
 The committed baseline of the former backlog is retained in Git at `16a3417`; later operational evidence is linked from the owning design and CI runs. Old candidate logs, review hashes and investigation iterations are evidence, not additional open work. Do not infer completed functionality from a closed author/reviewer process or infer publication/activation from a prototype PASS.

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ## Unreleased
 
+## 0.58.0: Explicit Capability Retention
+
+- `Capability Retention`: `register_tool expose=false` saves new template/from Recipes under `recipes/library` without activating tools or counting launches. Receipts return exact reusable paths and `activation: not_requested`, not failed activation. Both sync and async capabilities can be retained, spawned or deliberately exposed later; deleting an exposed wrapper preserves its retained source.
+- `Retained Discovery and Usage`: Recipe inspection distinguishes retained definitions from tool candidates and drafts, with exact verbose paths, execution modes and invalid/disabled diagnostics. Inspection is read-only. Retained launches share the existing usage owner while keeping same-named tool history separate; matching content cannot silently transfer lineage across that boundary.
+- `Safe Create-only Storage`: Retention validates sources and size, rejects direct disposable-draft dependencies and preserves name conflicts through atomic no-overwrite publication. Filesystems without hard-link support refuse rather than replace. Partial-effect failures preserve committed bytes and original causes; inspect before retrying. Retained update, delete and draft promotion remain unsupported.
+- `Compatibility and Guidance`: Existing registration, tool discovery, automatic review and live portfolios remain unchanged; no migration or default policy is enabled. Updated Skills distinguish execution mode, retention and tool exposure. Delegated sources remain external dependencies, not self-contained backups; structural review and launch counts do not prove usefulness or accepted success.
+
 ## 0.57.1: Rooted Completion Headers
 
 - `Completion Headers`: New captures keep all runtime metadata above the Actor Markdown, with no service/file footer. File references share literal roots with relative entries, English purposes and a read-first pointer. External roots and unresolved bases stay explicit; declarations do not prove production. Known cut counts remain at the cut. Original Markdown, source/generation/privacy fences, shared budgets and exact historical replay are preserved.

package/README.md

@@ -25,6 +25,12 @@ This topology does not require every task to become a subagent. Short work with
 
 Design notes for [portable Recipe composition bundles and CodeMode interoperability](docs/composition-transport.md) are recorded separately. JSONL bundle loading is not implemented or included in the current UX/AX release; host CodeMode, when available, calls existing tools rather than replacing the Run kernel.
 
+## Capability Memory Direction
+
+A reusable Recipe does not have to become a named tool. The [adopted capability-memory direction](docs/capability-memory.md) separates retention from tool exposure: sync/async determines execution, not usefulness, and a subagent-backed tool is a capability launcher rather than a saved live Actor. The aim is useful procedural memory with a selective tool interface, not more registered names.
+
+Use `register_tool expose=false` with a new name and a template/from source to save a capability in `recipes/library` without activating a tool. Its retained_recipe/not_requested receipt returns the exact Recipe path for `spawn` or later deliberate `register_tool from` exposure. Creation is exclusive; retained update, delete and draft promotion are not supported. `inspect target=recipes view=summary` distinguishes retained definitions, with exact paths, modes and diagnostics in verbose detail. Automatic retained lifecycle is not implemented. Current tool-root discovery, automatic review and ordinary registration remain unchanged; structural review and launch counts alone do not prove useful successful reuse. [BACKLOG.md](BACKLOG.md) owns implementation and evidence gates; adopting the direction neither migrates existing tools nor reloads a running host.
+
 ## Install
 
 Requires Node.js 22.19.0 or newer and Pi 1.0.0 or newer.
@@ -103,7 +109,7 @@ A Run exposes exactly `recipe`, `trace`, and `control` views. Run-specific `insp
 
 ### `register_tool`
 
-Persist a maintained Recipe with `register_tool name=<tool> from=<skill>/<recipe> defaults={...}`, or register a trusted command through the separate `template` mode. Definitions live under `~/.pi/agent/recipes`. Treat a tool as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
+Persist a maintained Recipe with `register_tool name=<tool> from=<skill>/<recipe> defaults={...}`, or register a trusted command through the separate `template` mode. Definitions live under `~/.pi/agent/recipes`. With `expose=false`, a new template/from definition is retained under `recipes/library` instead; its not_requested receipt makes no tool-callability claim. Treat an exposed tool as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
 
 ## Recipe
 

package/dist/lib/file-state.d.ts

@@ -13,6 +13,7 @@ export interface FileMutationLockOptions {
 export declare function acquireFileMutationLock(path: string, options?: FileMutationLockOptions): () => void;
 export declare function withFileMutationLock<T>(path: string, mutate: () => T, options?: FileMutationLockOptions): T;
 export declare function writeTextAtomic(path: string, content: string, options?: {
+    exclusive?: boolean;
     onBeforeReplace?(): void;
 }): void;
 export declare function writeJsonAtomic(path: string, value: unknown): void;

package/dist/lib/file-state.js

@@ -5,7 +5,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, parse, resolve } from "node:path";
 const FILE_MUTATION_LOCK_TIMEOUT_MS = process.platform === "win32" ? 30000 : 15000;
@@ -312,7 +312,13 @@ export function writeTextAtomic(path, content, options = {}) {
     try {
         writeFileSync(tempPath, content, "utf8");
         options.onBeforeReplace?.();
-        replaceFileWithRetry(tempPath, path);
+        if (options.exclusive === true) {
+            // Publish a complete new file atomically without clobbering an uncooperative creator.
+            linkSync(tempPath, path);
+            unlinkSync(tempPath);
+        }
+        else
+            replaceFileWithRetry(tempPath, path);
     }
     catch (error) {
         try {

package/dist/lib/prompts.d.ts

@@ -4,7 +4,7 @@
  * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
  */
 export declare const REGISTER_TOOL_DESCRIPTION: string;
-export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent Recipes or command templates as agent-callable tools";
+export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Persist command templates or Recipes with register_tool; use expose=false to retain without tool activation";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
 export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors Skill routing:\n- Treat active bundled Skills as the operating authority.\n- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.\n- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.\n- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.\n- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.\n- Treat persistence or registration as distinct from current callability; actors owns activation proof.\n- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.\n- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.\n- README and docs are human-facing references, not the normal agent operating path.\n- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
@@ -13,6 +13,7 @@ export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.";
     readonly defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.";
     readonly draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.";
+    readonly expose: "Set false to retain a new named template/from Recipe in recipes/library without registering or activating a tool. Default true preserves ordinary tool registration. Retained update, delete and draft promotion are unsupported.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
     readonly template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.";
     readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";

package/dist/lib/prompts.js

@@ -5,12 +5,15 @@
  */
 export const REGISTER_TOOL_DESCRIPTION = "Register a persistent custom tool from one maintained Recipe, command template, or captured draft. " +
     "Use from for Recipe specialization, template for trusted commands, or draft for promotion. " +
+    "Set expose=false to retain a new template/from Recipe without tool activation. " +
     "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
-export const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent Recipes or command templates as agent-callable tools";
+export const REGISTER_TOOL_PROMPT_SNIPPET = "Persist command templates or Recipes with register_tool; use expose=false to retain without tool activation";
 export const REGISTER_TOOL_GUIDELINES = [
     "Use register_tool from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
     "Use register_tool template only for trusted command templates, and use register_tool draft only for captured draft promotion.",
-    "After register_tool succeeds, trust its callable_now and activation result; persistence alone is not callability.",
+    "Use register_tool expose=false to retain a new named template/from Recipe without activation; update, delete and draft promotion are unsupported in this mode.",
+    "A register_tool retained_recipe receipt with activation=not_requested is deliberate retention, not failed activation; reuse its exact Recipe path through spawn.",
+    "When register_tool requests tool exposure, trust callable_now and activation; persistence alone is not callability.",
     'Set template=null or template="" in register_tool to delete a persisted tool.',
     "Set update=true in register_tool to overwrite an existing tool registration.",
 ];
@@ -31,6 +34,7 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.",
     defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.",
     draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.",
+    expose: "Set false to retain a new named template/from Recipe in recipes/library without registering or activating a tool. Default true preserves ordinary tool registration. Retained update, delete and draft promotion are unsupported.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
     template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.",
     templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",

package/dist/lib/recipes-discovery.d.ts

@@ -67,6 +67,10 @@ export declare function discoverRecipeSources(sources: RecipesDiscoverySource[])
 export declare function discoverRecipes(roots: string[]): RecipesDiscoveryResult;
 export declare function createRecipeIntegrityManifest(result: RecipesDiscoveryResult): RecipeIntegrityManifestEntry[];
 export declare function getShadowedLaunchDiagnostic(result: RecipesDiscoveryResult, id: string): Record<string, unknown> | undefined;
+export declare function inventoryRetainedRecipes(recipeRoot: string, resolutionContext?: RecipeResolutionContext): {
+    recipes: Array<Record<string, unknown>>;
+    diagnostics: string[];
+};
 export declare function listDraftRecipes(root: string): Array<Record<string, unknown>>;
 export declare function summarizeDiscovery(result: RecipesDiscoveryResult): Record<string, unknown>;
 export declare function summarizeRegisteredToolArgs(tool: RegisteredTool): {

package/dist/lib/recipes-discovery.js

@@ -550,6 +550,28 @@ function templatePreview(value) {
         ? `${rendered.slice(0, 117)}...`
         : rendered;
 }
+export function inventoryRetainedRecipes(recipeRoot, resolutionContext) {
+    const discovery = discoverRecipeSources([
+        { root: join(recipeRoot, "library"), resolutionContext },
+    ]);
+    return {
+        recipes: [...discovery.active.values()]
+            .map((entry) => ({
+            id: entry.id,
+            path: entry.path,
+            source_kind: "user_retained_recipe",
+            tool: false,
+            invalid: entry.invalid,
+            disabled: entry.disabled,
+            ...(entry.config ? { async: entry.config.async === true } : {}),
+            ...(entry.config?.description ? { description: entry.config.description } : {}),
+            ...(entry.diagnostics.length ? { diagnostics: entry.diagnostics } : {}),
+            ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        diagnostics: discovery.diagnostics,
+    };
+}
 export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
         for (let attempt = 0; attempt < 3; attempt += 1) {

package/dist/lib/recipes-references.d.ts

@@ -5,6 +5,7 @@
  */
 import type { CommandTemplateValue } from "./command-templates.ts";
 import * as CommandTemplates from "./command-templates.ts";
+export declare const MAX_RECIPE_FILE_BYTES: number;
 export interface TemplateRecipeImportBinding {
     from?: string;
     defaults?: Record<string, unknown>;

package/dist/lib/recipes-references.js

@@ -9,7 +9,7 @@ import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 import * as RecipeControl from "./recipe-control.js";
 import * as Schema from "./schema.js";
-const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
+export const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
 const RESERVED_AUTHORED_RECIPE_VALUE_NAMES = new Set([
     "recipe_dir",

package/dist/lib/recipes-usage.js

@@ -44,7 +44,7 @@ function readRecipeSource(path) {
 }
 function inferRecipeRoot(path) {
     const parent = dirname(resolve(path));
-    return basename(parent) === "drafts" ? dirname(parent) : parent;
+    return ["drafts", "library"].includes(basename(parent)) ? dirname(parent) : parent;
 }
 function pathKey(path, recipeRoot) {
     const relation = relative(resolve(recipeRoot), resolve(path));
@@ -53,8 +53,9 @@ function pathKey(path, recipeRoot) {
     }
     return relation.replaceAll("\\", "/");
 }
-function recipeName(path) {
-    return basename(path).replace(/\.(?:json|md)$/u, "");
+function recipeName(path, recipeRoot) {
+    const name = basename(path).replace(/\.(?:json|md)$/u, "");
+    return dirname(resolve(path)) === resolve(recipeRoot, "library") ? `library/${name}` : name;
 }
 function lineageFilename(lineageName) {
     if (!lineageName || lineageName === "." || lineageName === "..") {
@@ -117,8 +118,10 @@ function readIndexedLedger(indexedName, recipeRoot) {
     const current = readLedger(indexedName, recipeRoot);
     return current ? { record: current } : undefined;
 }
-function findRelocatedRecipe(index, fingerprint, recipeRoot) {
+function findRelocatedRecipe(index, fingerprint, recipeRoot, newPath) {
     const candidates = Object.entries(index.paths).flatMap(([oldPath, indexedName]) => {
+        if (oldPath.startsWith("library/") !== newPath.startsWith("library/"))
+            return [];
         if (existsSync(join(recipeRoot, oldPath)))
             return [];
         const found = readIndexedLedger(indexedName, recipeRoot);
@@ -157,7 +160,7 @@ export function ensureRecipeLineage(path, now = new Date(), recipeRoot = inferRe
             if (!source)
                 return false;
             const key = pathKey(path, recipeRoot);
-            const name = recipeName(path);
+            const name = recipeName(path, recipeRoot);
             const index = readIndex(recipeRoot);
             const indexedName = index.paths[key];
             if (indexedName) {
@@ -253,11 +256,11 @@ export function recordRecipeLaunch(path, now = new Date(), kind = "direct", reci
                     return false;
                 const { fingerprint } = source;
                 const key = pathKey(path, recipeRoot);
-                const desiredName = recipeName(path);
+                const desiredName = recipeName(path, recipeRoot);
                 const index = readIndex(recipeRoot);
                 const relocated = index.paths[key]
                     ? undefined
-                    : findRelocatedRecipe(index, fingerprint, recipeRoot);
+                    : findRelocatedRecipe(index, fingerprint, recipeRoot, key);
                 const indexedName = index.paths[key] ?? relocated?.indexedName;
                 const found = indexedName
                     ? readIndexedLedger(indexedName, recipeRoot)
@@ -298,7 +301,7 @@ export function recordRecipeLaunch(path, now = new Date(), kind = "direct", reci
                         former_names: renamed
                             ? appendBounded(stored?.former_names ?? [], stored.lineage_name)
                             : relocated
-                                ? appendBounded(stored?.former_names ?? [], recipeName(relocated.path))
+                                ? appendBounded(stored?.former_names ?? [], recipeName(join(recipeRoot, relocated.path), recipeRoot))
                                 : stored?.former_names ?? [],
                         former_paths: relocated
                             ? appendBounded(stored?.former_paths ?? [], relocated.path)
@@ -444,7 +447,7 @@ export function moveRecipeUsage(fromPath, toPath, recipeRoot = inferRecipeRoot(f
             const toKey = pathKey(toPath, recipeRoot);
             const index = readIndex(recipeRoot);
             const oldName = index.paths[fromKey];
-            const newName = recipeName(toPath);
+            const newName = recipeName(toPath, recipeRoot);
             if (!oldName) {
                 return index.paths[toKey] === newName && Boolean(readLedger(newName, recipeRoot));
             }

package/dist/lib/registry.d.ts

@@ -10,6 +10,7 @@ export interface RegisterToolInput {
     name?: string;
     description?: string;
     async?: boolean;
+    expose?: boolean;
     template?: CommandTemplates.CommandTemplateValue | null;
     from?: string;
     defaults?: Record<string, unknown>;
@@ -19,13 +20,16 @@ export interface RegisterToolInput {
 }
 export interface RegisterToolResultDetails {
     active_tool?: boolean;
-    activation?: "current_session" | "unverified";
+    activation?: "current_session" | "unverified" | "not_requested";
     activation_boundary?: string;
     args?: string[];
     async?: boolean;
     callable_now?: boolean;
     defaults?: Record<string, string>;
     host_registered?: boolean;
+    kind?: "retained_recipe";
+    recipe?: string;
+    result?: "retained";
     next_actions?: string[];
     optional_args?: string[];
     persisted?: boolean;

package/dist/lib/registry.js

@@ -3,8 +3,8 @@
  * Zones: registry mutations, persistence, runtime activation
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Config from "./config.js";
 import * as ExecutionOutput from "./execution-output.js";
@@ -560,6 +560,14 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
         ? params
         : {};
     assertRegisterToolInputModes(rawInput);
+    if (Object.hasOwn(rawInput, "expose")) {
+        const exposure = rawInput.expose;
+        if (typeof exposure !== "boolean")
+            throw new RetainedRecipeRefusal("expose", "expose must be Boolean.");
+        // Select under the existing name reservation; acquire retention locks only after it releases.
+        if (exposure === false)
+            return () => retainRecipe(rawInput, ctx, deps);
+    }
     let input = rawInput;
     if (!input.name)
         return listTools(deps);
@@ -702,12 +710,196 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
         },
     };
 }
+class RetainedRecipeRefusal extends Error {
+    reason;
+    constructor(field, reason, cause) {
+        super(ExecutionOutput.formatToolText(registryMetadataText({ field, result: reason })), { cause });
+        this.reason = reason;
+    }
+}
+function retainedDirectory(path) {
+    const stat = lstatSync(path, { bigint: true });
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new RetainedRecipeRefusal("storage", "Retained storage must be a regular non-symlink directory.");
+    }
+    return { path, realpath: realpathSync.native(path), dev: stat.dev, ino: stat.ino };
+}
+function recheckRetainedDirectory(frame) {
+    const current = retainedDirectory(frame.path);
+    if (current.realpath !== frame.realpath || current.dev !== frame.dev || current.ino !== frame.ino) {
+        throw new RetainedRecipeRefusal("storage", "Retained storage identity changed.");
+    }
+}
+function retainedSlotAbsent(path, ownTargetPublished = false) {
+    for (const candidate of ownTargetPublished ? [path.replace(/\.json$/u, ".md")] : [path, path.replace(/\.json$/u, ".md")]) {
+        try {
+            lstatSync(candidate);
+        }
+        catch (error) {
+            let code;
+            try {
+                code = error?.code;
+            }
+            catch (observationError) {
+                throw new AggregateError([error, observationError], "Retained slot observation failed.", { cause: error });
+            }
+            if (code === "ENOENT")
+                continue;
+            throw error;
+        }
+        throw new RetainedRecipeRefusal("name", "Retained Recipe already exists; this path is create-only.");
+    }
+}
+function retainedFile(path) {
+    const stat = lstatSync(path, { bigint: true });
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new RetainedRecipeRefusal("storage", "Retained target must be a regular non-symlink file.");
+    }
+    if (stat.size > BigInt(RecipesReferences.MAX_RECIPE_FILE_BYTES))
+        throw new RetainedRecipeRefusal("storage", "Retained target exceeds the source size limit.");
+    return { dev: stat.dev, ino: stat.ino, size: stat.size, mtime: stat.mtimeNs, ctime: stat.ctimeNs };
+}
+function withinRetainedSource(root, path) {
+    const relation = relative(resolve(root), resolve(path));
+    return relation === "" || (!isAbsolute(relation) && !/^\.\.(?:[\\/]|$)/u.test(relation));
+}
+function assertRetainedSourceLifetime(source, root, field) {
+    const drafts = join(root, "drafts");
+    if (withinRetainedSource(drafts, source) ||
+        (existsSync(drafts) && existsSync(source) && withinRetainedSource(realpathSync.native(drafts), realpathSync.native(source)))) {
+        throw new RetainedRecipeRefusal(field, "Retained creation cannot reference a managed disposable draft.");
+    }
+}
+function assertRetainedTemplateLifetimes(value, path, root, context) {
+    if (typeof value === "string") {
+        const source = RecipesReferences.resolveRecipeReferencePath(value, dirname(path), context.activeSkills);
+        if (source)
+            assertRetainedSourceLifetime(source, root, "template");
+    }
+    else if (Array.isArray(value)) {
+        for (const child of value)
+            assertRetainedTemplateLifetimes(child, path, root, context);
+    }
+    else if (value && typeof value === "object") {
+        const node = value;
+        assertRetainedTemplateLifetimes(node.template, path, root, context);
+        assertRetainedTemplateLifetimes(node.recover, path, root, context);
+    }
+}
+function retainRecipe(input, ctx, deps) {
+    assertRegisterToolInputModes(input);
+    if (typeof input.name !== "string" || !input.name.trim()) {
+        throw new RetainedRecipeRefusal("name", "Retained creation requires a name.");
+    }
+    const name = Identity.normalizeToolName(input.name);
+    if (!name || deps.reservedToolNames.has(name)) {
+        throw new RetainedRecipeRefusal("name", "Invalid or reserved retained Recipe name.");
+    }
+    const blocker = deps.getToolNameBlocker(name);
+    if (blocker)
+        throw new Error(ExecutionOutput.formatToolText(blocker));
+    if (input.update || Object.hasOwn(input, "draft")) {
+        throw new RetainedRecipeRefusal("expose", "Retained creation does not support update or draft promotion.");
+    }
+    const template = getInputTemplate(input.template);
+    if (template === null || template === "") {
+        throw new RetainedRecipeRefusal("template", "Retained deletion is not supported.");
+    }
+    if (template === undefined && !input.from) {
+        throw new RetainedRecipeRefusal("source", "Retained creation requires template or from.");
+    }
+    const root = resolve(getRecipeRoot(deps)), library = join(root, "library"), path = join(library, `${name}.json`);
+    const context = getRegistrationResolutionContext(ctx, deps);
+    const from = input.from === undefined ? undefined : normalizeFromReference(input.from, context);
+    if (from) {
+        const source = from.endsWith(".json") || from.endsWith(".md") ? from
+            : RecipesReferences.resolveRecipeReferencePath(from, context.cwd, context.activeSkills);
+        if (source)
+            assertRetainedSourceLifetime(source, root, "from");
+    }
+    const authored = buildAuthoredRecipe({ ...input, ...(from ? { from } : {}) }, undefined, undefined);
+    if (!from)
+        assertRetainedTemplateLifetimes(authored.template, path, root, context);
+    const bytes = `${JSON.stringify(authored, null, 2)}\n`;
+    if (Buffer.byteLength(bytes) > RecipesReferences.MAX_RECIPE_FILE_BYTES) {
+        throw new RetainedRecipeRefusal("source", "Retained Recipe exceeds the 1 MiB source limit.");
+    }
+    const candidate = RecipesDiscovery.admitUserRecipe(path, context, authored);
+    if (!candidate.validated || !candidate.tool) {
+        throw new RetainedRecipeRefusal("source", "Retained Recipe admission failed; check the source and caller argument contract.", candidate.diagnostics);
+    }
+    let stage = "storage";
+    try {
+        return withFileMutationLock(root, () => {
+            mkdirSync(root, { recursive: true });
+            const rootFrame = retainedDirectory(root);
+            return withFileMutationLock(library, () => {
+                recheckRetainedDirectory(rootFrame);
+                mkdirSync(library, { recursive: true });
+                const libraryFrame = retainedDirectory(library);
+                const relation = relative(rootFrame.realpath, libraryFrame.realpath);
+                if ((process.platform === "win32" ? relation.toLowerCase() : relation) !== "library") {
+                    throw new RetainedRecipeRefusal("storage", "Retained library escapes its Recipe root.");
+                }
+                const recheck = () => { recheckRetainedDirectory(rootFrame); recheckRetainedDirectory(libraryFrame); };
+                return withFileMutationLock(path, () => {
+                    recheck();
+                    retainedSlotAbsent(path);
+                    stage = "persistence";
+                    writeTextAtomic(path, bytes, { exclusive: true, onBeforeReplace: () => { recheck(); retainedSlotAbsent(path); } });
+                    stage = "persisted_admission";
+                    recheck();
+                    retainedSlotAbsent(path, true);
+                    const before = retainedFile(path);
+                    if (readFileSync(path, "utf8") !== bytes)
+                        throw new RetainedRecipeRefusal("storage", "Persisted retained content changed.");
+                    const admitted = RecipesDiscovery.admitUserRecipe(path, context);
+                    if (!admitted.validated || !admitted.tool)
+                        throw new RetainedRecipeRefusal("source", "Persisted retained Recipe admission failed.", admitted.diagnostics);
+                    const after = retainedFile(path);
+                    if (Object.keys(before).some(key => before[key] !== after[key]) ||
+                        readFileSync(path, "utf8") !== bytes)
+                        throw new RetainedRecipeRefusal("storage", "Persisted retained content changed.");
+                    recheck();
+                    retainedSlotAbsent(path, true);
+                    stage = "receipt";
+                    const args = RecipesDiscovery.summarizeRegisteredToolArgs(admitted.tool);
+                    const source = from ? from.endsWith(".json") || from.endsWith(".md") ? `<explicit-file:${basename(from)}>` : from : "template";
+                    const recipe = registrySelected("recipe", path), selectedName = registrySelected("tool", name);
+                    const selectedSource = registrySelected("source", source);
+                    const required = ToolsResponse.selectYamlField("required_args", args.required, REGISTRY_METADATA_BUDGET);
+                    const optional = ToolsResponse.selectYamlField("optional_args", args.optional, REGISTRY_METADATA_BUDGET);
+                    const facts = { kind: "retained_recipe", result: "retained", persisted: true, resolved: true,
+                        validated: true, activation: "not_requested", async: admitted.async };
+                    const text = growRegistryDocument(() => ({ ...selectedName.selected, ...facts, ...recipe.selected, ...selectedSource.selected,
+                        ...required.selected, ...optional.selected, next: { tool: "inspect", target: "recipes", view: "summary", verbose: true } }), [recipe, selectedName, selectedSource, required, optional]);
+                    const result = {
+                        content: [textContent(ExecutionOutput.formatToolText(text))],
+                        details: { ...facts, tool: name, recipe: path, source, required_args: args.required, optional_args: args.optional,
+                            next_actions: ["inspect target=recipes view=summary verbose=true"] },
+                    };
+                    stage = "release";
+                    return result;
+                });
+            });
+        });
+    }
+    catch (error) {
+        const reason = error instanceof RetainedRecipeRefusal ? { reason: error.reason } : {};
+        throw new Error(ExecutionOutput.formatToolText(registryMetadataText({ operation: "retain", stage, result: "unconfirmed",
+            effects: "unknown; inspect retained inventory before retry", ...reason,
+            next: { tool: "inspect", target: "recipes", view: "summary", verbose: true } })), { cause: error });
+    }
+}
 export async function executeRegisterTool(params, ctx, deps) {
     const input = params;
+    let result;
     if (!input.name)
-        return executeRegisterToolUnlocked(params, ctx, deps);
-    const name = Identity.normalizeToolName(input.name);
-    if (!name)
-        return executeRegisterToolUnlocked(params, ctx, deps);
-    return withFileMutationLock(getToolRecipePath(deps, name), () => executeRegisterToolUnlocked(params, ctx, deps));
+        result = executeRegisterToolUnlocked(params, ctx, deps);
+    else {
+        const name = Identity.normalizeToolName(input.name);
+        result = !name ? executeRegisterToolUnlocked(params, ctx, deps)
+            : withFileMutationLock(getToolRecipePath(deps, name), () => executeRegisterToolUnlocked(params, ctx, deps));
+    }
+    return typeof result === "function" ? result() : result;
 }

package/dist/lib/tools-inspect.js

@@ -364,9 +364,6 @@ function inspectRecipes(requestedView, input, deps, context) {
     if (view === "reviews") {
         return ReviewDiagnostics.readAutomaticReviewDiagnostics({ recipeRoot });
     }
-    const discovered = RecipesDiscovery.discoverRecipeSources([
-        { root: recipeRoot, defaultTool: true, mutableUsage: true },
-    ]);
     const resolutionContext = context && typeof context === "object" && "recipeResolutionContext" in context
         ? context.recipeResolutionContext
         : undefined;
@@ -399,7 +396,11 @@ function inspectRecipes(requestedView, input, deps, context) {
         skill: diagnostic.skill,
         ...(diagnostic.stem ? { stem: diagnostic.stem } : {}),
     }));
+    const discovered = RecipesDiscovery.discoverRecipeSources([
+        { root: recipeRoot, defaultTool: true, mutableUsage: true, resolutionContext },
+    ]);
     const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
+    const retained = RecipesDiscovery.inventoryRetainedRecipes(recipeRoot, resolutionContext);
     const summary = {
         ...discoverySummary,
         ...(registryStatus
@@ -425,6 +426,8 @@ function inspectRecipes(requestedView, input, deps, context) {
             error: `Ambiguous active Skill Recipe namespace ${name}`,
         })),
         drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+        retained: retained.recipes,
+        retained_diagnostics: retained.diagnostics,
     };
     return {
         ...summary,

package/dist/lib/tools-register.js

@@ -26,6 +26,7 @@ export function createRegisterToolDefinition(deps) {
             description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
             defaults: looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.defaults),
             draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
+            expose: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.expose),
             from: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.from),
             name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
             template: unionSchema([