@llblab/pi-actors 0.57.1 → 0.58.1

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/run-delivery.d.ts

@@ -66,7 +66,7 @@ export interface RunCompletionBatch {
     /** Retained singleton capture; absence preserves older indexed bytes. Never a new-capture selector. */
     readonly single_result?: true;
     /** Captured record-list shape; no public format/version choice or source authority. */
-    readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1";
+    readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" | "completion_yaml_files_v2";
     /** Immutable scope/order/range data, not a caller-selected format or allocation authority. */
     readonly numbering?: RunCompletionNumbering;
     /** Formatting version/data only; no recipient ownership, read or publication capability. */

package/dist/lib/run-delivery.js

@@ -278,8 +278,11 @@ function parseInventorySource(value, batch) {
 function isFrontmatterCompletionLayout(layout) {
     return layout === "frontmatter_v1" || layout === "frontmatter_v2";
 }
+function isRootedCompletionLayout(layout) {
+    return layout === "completion_yaml_files_v1" || layout === "completion_yaml_files_v2";
+}
 function isYamlCompletionLayout(layout) {
-    return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+    return layout === "completion_yaml_core_v1" || isRootedCompletionLayout(layout);
 }
 function isSharedCompletionLayout(layout) {
     return layout === "headings_shared_results" || layout === "headings_shared_kinds" || isYamlCompletionLayout(layout) || isFrontmatterCompletionLayout(layout);
@@ -688,7 +691,7 @@ export function requestRunCompletionStream(input) {
     });
 }
 export function admitRunCompletionBatch(input) {
-    return captureCompletionBatch(input, false, "completion_yaml_files_v1");
+    return captureCompletionBatch(input, false, "completion_yaml_files_v2");
 }
 /** Kernel-only opt-in; ordinary Pi capture stays fenced until session/lifecycle integration is admitted. */
 export function captureRunCompletionStreamBatch(input) {
@@ -696,7 +699,7 @@ export function captureRunCompletionStreamBatch(input) {
 }
 /** Private ordinary candidate composition; stream capture retains its separately gated codec. */
 export function captureRunCompletionYamlCandidateBatch(input) {
-    return captureCompletionBatch(input, false, "completion_yaml_files_v1");
+    return captureCompletionBatch(input, false, "completion_yaml_files_v2");
 }
 function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
     const now = (input.now ?? new Date()).toISOString();
@@ -1697,13 +1700,14 @@ function completionRootedFiles(row, member, locations) {
 }
 function prepareCompletionYamlProjection(safe, candidates, references, ordered) {
     const packet = { batchId: safe.batch_id, records: [] };
-    const rooted = safe.result_layout === "completion_yaml_files_v1";
+    const rooted = isRootedCompletionLayout(safe.result_layout);
+    const localSingleton = safe.result_layout === "completion_yaml_files_v2" && !safe.numbering && candidates.length === 1;
     if (!safe.batch_id.isWellFormed())
         return { state: "unsupported" };
     for (const [index, { row, location }] of candidates.entries()) {
         const member = ordered[index];
         const displayed = safe.numbering ? safe.numbering.kind === "stream" ? safe.numbering.first_index + index : "?" : index;
-        const metadata = { index: displayed };
+        const metadata = localSingleton ? {} : { index: displayed };
         for (const piece of row.pieces) {
             if (piece.block)
                 continue;
@@ -1763,7 +1767,9 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
         }
         packet.records.push({ metadata, parts });
     }
-    const service = rooted ? { header_layout: "rooted_files_v1" } : {};
+    const service = rooted ? {
+        header_layout: safe.result_layout === "completion_yaml_files_v2" ? "rooted_files_v2" : "rooted_files_v1",
+    } : {};
     const omitted = safe.members.length - candidates.length;
     if (omitted) {
         service.omitted_results = omitted;
@@ -2302,7 +2308,7 @@ export function readRunCompletionPresentation(content, value) {
             hint.content_sha256 !== createHash("sha256").update(content).digest("hex"))
             return full;
         const segments = [];
-        const rooted = core.packet.service?.header_layout === "rooted_files_v1";
+        const rooted = core.packet.service?.header_layout === "rooted_files_v1" || core.packet.service?.header_layout === "rooted_files_v2";
         const facts = Object.fromEntries(Object.entries(core.packet.service ?? {}).filter(([key]) => key !== "header_layout"));
         for (const [index, record] of core.packet.records.entries()) {
             if (index)
@@ -2551,6 +2557,8 @@ export function encodeCompletionYamlCarrier(input) {
         (Object.hasOwn(packet, "service") && (!completionYamlMapping(packet.service) || !Object.keys(packet.service).length)) ||
         (!packet.records.length && !Object.hasOwn(packet, "service")))
         return unavailable;
+    const localSingleton = packet.records.length === 1 && completionYamlMapping(packet.service) &&
+        packet.service.header_layout === "rooted_files_v2" && !Object.hasOwn(packet.service, "numbering");
     const rows = [];
     for (let index = 0; index < Math.max(1, packet.records.length); index++) {
         const row = packet.records[index];
@@ -2568,14 +2576,16 @@ export function encodeCompletionYamlCarrier(input) {
                 !completionYamlMapping(row.metadata) || !Array.isArray(row.parts))
                 return unavailable;
             const meta = row.metadata;
-            if (!(meta.index === "?" || (typeof meta.index === "number" && Number.isSafeInteger(meta.index) && meta.index >= 0)) ||
+            const validIndex = localSingleton ? !Object.hasOwn(meta, "index")
+                : meta.index === "?" || (typeof meta.index === "number" && Number.isSafeInteger(meta.index) && meta.index >= 0);
+            if (!validIndex ||
                 typeof meta.run !== "string" || !meta.run.length || typeof meta.state !== "string" || !meta.state.length ||
                 (Object.hasOwn(meta, "kind") && meta.kind !== "primary" && meta.kind !== "diagnostic") ||
                 Object.hasOwn(meta, completionYamlServiceKey) ||
                 // JS enumerates array-index keys before semantic core fields; do not silently reorder the header.
                 Object.keys(meta).some(key => /^(0|[1-9]\d*)$/u.test(key) && Number(key) < 4294967295))
                 return unavailable;
-            for (const key of ["index", "run", "state", ...(Object.hasOwn(meta, "kind") ? ["kind"] : []),
+            for (const key of [...(localSingleton ? [] : ["index"]), "run", "state", ...(Object.hasOwn(meta, "kind") ? ["kind"] : []),
                 ...Object.keys(meta).filter(key => !["index", "run", "state", "kind"].includes(key))]) {
                 Object.defineProperty(header, key, { value: meta[key], enumerable: true });
             }

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([

package/dist/lib/tools-response.js

@@ -512,6 +512,10 @@ export function recipeRegistryNextActions(summary, view) {
     if (summary.skill_recipe_catalog_partial === true) {
         actions.push("inspect target=recipes view=imports verbose=true");
     }
+    if ((Array.isArray(summary.retained) && summary.retained.length > 0) ||
+        (Array.isArray(summary.retained_diagnostics) && summary.retained_diagnostics.length > 0)) {
+        actions.push("inspect target=recipes view=summary verbose=true");
+    }
     if (drafts.length > 0) {
         actions.push("inspect target=recipes view=summary verbose=true");
         const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
@@ -525,16 +529,20 @@ export function compactYamlDocument(value) {
     const text = growYamlDocument(() => value, [], Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
     return `\n${text.replace(/\n$/u, "")}`;
 }
+function recipeInspectionHint(action) {
+    if (action === "inspect target=recipes view=doctor")
+        return { view: "doctor" };
+    if (action === "inspect target=recipes view=imports verbose=true")
+        return { view: "imports", verbose: true };
+    if (action === "inspect target=recipes view=summary verbose=true")
+        return { view: "summary", verbose: true };
+    return undefined;
+}
 /** Only the closed read-only Recipe inspect literals become typed next; other advice stays opaque content. */
 export function nextActionMetadata(action, byteBudget) {
-    const recognized = [
-        ["inspect target=recipes view=doctor", "doctor", false],
-        ["inspect target=recipes view=imports verbose=true", "imports", true],
-        ["inspect target=recipes view=summary verbose=true", "summary", true],
-    ];
-    const match = recognized.find(([literal]) => literal === action);
-    if (match) {
-        const typed = { next: { tool: "inspect", target: "recipes", view: match[1], ...(match[2] ? { verbose: true } : {}) } };
+    const hint = recipeInspectionHint(action);
+    if (hint) {
+        const typed = { next: { tool: "inspect", target: "recipes", ...hint } };
         return { full: typed, selected: typed };
     }
     const instruction = selectYamlField("instruction", action, byteBudget);
@@ -542,19 +550,15 @@ export function nextActionMetadata(action, byteBudget) {
 }
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export function formatInspectionHint(action) {
-    if (action === "inspect target=recipes view=doctor")
-        return formatInspectNextAction("recipes", "doctor");
-    if (action === "inspect target=recipes view=imports verbose=true")
-        return formatInspectNextAction("recipes", "imports", true);
-    if (action === "inspect target=recipes view=summary verbose=true")
-        return formatInspectNextAction("recipes", "summary", true);
-    return formatMarkdownField("instruction", action);
+    const hint = recipeInspectionHint(action);
+    return hint ? formatInspectNextAction("recipes", hint.view, hint.verbose) : formatMarkdownField("instruction", action);
 }
 export function compactRecipeRegistry(summary) {
     const count = (key, source) => Array.isArray(source) ? source.length : 0;
     const active = count("active", summary.active), shadowed = count("shadowed", summary.shadowed);
     const invalid = count("invalid", summary.invalid), disabled = count("disabled", summary.disabled);
     const diagnostics = count("diagnostics", summary.diagnostics), drafts = count("drafts", summary.drafts);
+    const retained = count("retained", summary.retained);
     const recommendations = count("recommendations", summary.recommendations);
     const skillCatalogPartial = summary.skill_recipe_catalog_partial === true;
     const currentPolicy = Array.isArray(summary.active)
@@ -564,7 +568,7 @@ export function compactRecipeRegistry(summary) {
         ? summary.next_actions
         : [];
     const hint = nextActions.length ? nextActionMetadata(nextActions[0], Limits.RUN_DELIVERY_MODEL_MAX_BYTES) : undefined;
-    const render = () => ({ recipes: "registry", active, drafts, shadowed, invalid, disabled,
+    const render = () => ({ recipes: "registry", active, drafts, retained, shadowed, invalid, disabled,
         current_policy: currentPolicy, skill_catalog_partial: skillCatalogPartial, recommendations, diagnostics,
         ...(hint ? hint.selected : {}) });
     return hint

package/dist/skills/actors/SKILL.md

@@ -19,6 +19,9 @@ Make a maintained capability a persistent agent-callable tool
 Keep the same capability but narrow caller defaults
 → use register_tool from=<skill>/<recipe> defaults={...}
 
+Retain a new named capability without exposing a tool
+→ use register_tool expose=false with from or template
+
 Register a trusted command directly
 → use register_tool template="..."
 
@@ -54,6 +57,12 @@ Run Control ≠ actor chat
 
 A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
+Sync/async is an execution contract, not a usefulness or tool-exposure rule. A sync tool awaits its result; an async tool returns a Run launch receipt, with the eventual result delivered separately. A subagent-backed tool is a capability launcher, not a persisted live subagent. Register a stable, meaningfully parameterized capability when its name and contract save repeated planning; prefer one-off `spawn` over a redundant generic launcher or a new tool for every mission.
+
+Use `register_tool expose=false` with a new name and one `template` or `from` source to retain a capability without requesting tool activation. Its `kind: retained_recipe`, `activation: not_requested` receipt is deliberate retention, not failed registration; it omits global callability flags because a same-named tool may already exist. Reuse the exact returned Recipe path through `spawn`, or deliberately expose it later with ordinary `register_tool from=<exact path>`. Retained update, delete and draft promotion are unsupported; do not hand-edit the live registry to bypass those guards.
+
+Automatic retained lifecycle is not implemented. Current user-root tool discovery and automatic review actions are unchanged. `inspect target=recipes view=summary` distinguishes retained definitions under `recipes/library` from root tool candidates; verbose detail gives exact paths, resolved mode and invalid/disabled diagnostics. Storage is not proof of review, callability or a running Actor. `expose` is registration input, not a Recipe field or automatic-review action; do not invent retain/defer review commands. See [persistent tools](./references/persistent-tools.md) for current selection and activation proof.
+
 `actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 
 ## Presentation Direction and Current Output
@@ -64,7 +73,7 @@ Rollout is partial: compact launch/attachment receipts use block YAML; other ope
 
 Compact launches use bare block-YAML mappings for the Run/state/launch facts and nested observed locations, explicitly identify actual existing-Run reuse, and preserve multiline scalar contents. One leading response-separator LF supplies invocation spacing; it is outside the pure metadata emitter and is not a `---` wrapper. Model/thinking provenance groups are labeled model and thinking, without a redundant _policy suffix; structured data and saved text stay unchanged. A complete direct file-location row needs no repeated session-map hint; absent/unavailable/omitted rows retain one optional next node naming inspect, target=runtime, view=runs and verbose=true. It never executes automatically. Exact locations, verbose details and saved completion formats stay unchanged.
 
-Fresh automatic completions have one AX capture path with no format selector: YAML frontmatter begins index, run, state, then kind:primary for admitted primary/final Actor response or kind:diagnostic for explicit diagnostics. Markdown follows unindented outside the closed metadata block, without #N heading, result:/preview: wrapper or whole-body literal fence. One record uses the same shape as many. Display index is not member_index or generation; default indices are packet-local. Whole-result/reference omissions and non-done omitted states stay explicit. Known display loss appears at the actual cut as [N characters omitted], counting Unicode scalar characters of admitted retained text/field, never raw/private loss; no extra clipping ellipsis or body clipping flags/counts in YAML. Unknown upstream completeness/privacy remains separately visible at the body boundary, not a fabricated count or a known positive loss. Untracked fallback has no kind and cannot become primary. Full text fitting its share has no display-cut marker; upstream uncertainty still prevents a completeness claim. New packets share48KiB UTF-8 including references/framing across at most64candidate rows, with frozen equal shares and no unused-share redistribution or fixed16KiB result/2KiB preview cap. Captured members remain bounded at256. Text is admitted work output/final response or explicit error/failure diagnostics, never launch commands. Successful composition/retry/Pi text-print can retain text_basis:actor_response; scope and exact references remain technical, while original coverage facts remain structured retained data. The model receives one complete content with whole source/generation/location references or truthful omission/inventory, not a standing full-map instruction. The TUI renders compiler headers/markers as Text and each body as independent native Markdown; only whole validated header reference/location rows and framing disappear in compact view. Body-authored YAML, next/tool/batch and omission lookalikes remain content. Content-bound hashes/ranges/blocks are display consistency, not authentication, source/read/action or acceptance authority. Invalid/missing hints and expansion reveal full original text, without Run-source IO. Old saved codecs, budgets, labels, excerpts, counts and hints replay exactly with no refresh, repair, ACK/resend or restyling—including earlier #N packets and the first frontmatter encoding. Fresh unavailable indices use quoted YAML "?"; an old saved unquoted value is not silently corrected. Routine successful delivery adds no separate completions/delivery-accepted toast; actual failures and handled-generation fences remain. These source/package rules do not prove that an already loaded session was reloaded. Fresh explicit agent Trace previews append boundary … and [omitted: N chars] from normalized retained turn, with a separate upstream [omitted: unknown]. N counts only display loss after existing session privacy, not discarded original/source text. Short well-formed summaries stay unchanged, including authored older-looking markers; malformed retained text yields Agent turn [omitted: unknown] (malformed retained text), never a guessed count or repaired scalar. This is read-time display only, not a rewrite/version of saved packets or sources. Other legacy clipping is not yet uniformly covered. Follow retained references selectively without inventing completeness or permission. Agent Trace ids reference recorded entry provenance, not aggregate traversal order or chronological event numbers. Native entry keys survive sibling growth; bounded legacy/ambiguous/private-metadata fallbacks are not permanent identities, source immutability or new read/work permission.
+Fresh automatic completions have one AX capture path with no format selector: YAML frontmatter begins run, state, then kind:primary for admitted primary/final Actor response or kind:diagnostic for explicit diagnostics. Markdown follows unindented outside the closed metadata block, without #N heading, result:/preview: wrapper or whole-body literal fence. Prepend index only when two or more results are shown; exactly one shown result omits it even if other results were omitted. Omission/inventory facts remain explicit. Display index is not member_index or generation; default indices are packet-local. This new-capture rule neither restyles saved messages nor changes numbered-stream presentation. Whole-result/reference omissions and non-done omitted states stay explicit. Known display loss appears at the actual cut as [N characters omitted], counting Unicode scalar characters of admitted retained text/field, never raw/private loss; no extra clipping ellipsis or body clipping flags/counts in YAML. Unknown upstream completeness/privacy remains separately visible at the body boundary, not a fabricated count or a known positive loss. Untracked fallback has no kind and cannot become primary. Full text fitting its share has no display-cut marker; upstream uncertainty still prevents a completeness claim. New packets share48KiB UTF-8 including references/framing across at most64candidate rows, with frozen equal shares and no unused-share redistribution or fixed16KiB result/2KiB preview cap. Captured members remain bounded at256. Text is admitted work output/final response or explicit error/failure diagnostics, never launch commands. Successful composition/retry/Pi text-print can retain text_basis:actor_response; scope and exact references remain technical, while original coverage facts remain structured retained data. The model receives one complete content with whole source/generation/location references or truthful omission/inventory, not a standing full-map instruction. The TUI renders compiler headers/markers as Text and each body as independent native Markdown; only whole validated header reference/location rows and framing disappear in compact view. Body-authored YAML, next/tool/batch and omission lookalikes remain content. Content-bound hashes/ranges/blocks are display consistency, not authentication, source/read/action or acceptance authority. Invalid/missing hints and expansion reveal full original text, without Run-source IO. Old saved codecs, budgets, labels, excerpts, counts and hints replay exactly with no refresh, repair, ACK/resend or restyling—including earlier #N packets and the first frontmatter encoding. Fresh unavailable indices use quoted YAML "?"; an old saved unquoted value is not silently corrected. Routine successful delivery adds no separate completions/delivery-accepted toast; actual failures and handled-generation fences remain. These source/package rules do not prove that an already loaded session was reloaded. Fresh explicit agent Trace previews append boundary … and [omitted: N chars] from normalized retained turn, with a separate upstream [omitted: unknown]. N counts only display loss after existing session privacy, not discarded original/source text. Short well-formed summaries stay unchanged, including authored older-looking markers; malformed retained text yields Agent turn [omitted: unknown] (malformed retained text), never a guessed count or repaired scalar. This is read-time display only, not a rewrite/version of saved packets or sources. Other legacy clipping is not yet uniformly covered. Follow retained references selectively without inventing completeness or permission. Agent Trace ids reference recorded entry provenance, not aggregate traversal order or chronological event numbers. Native entry keys survive sibling growth; bounded legacy/ambiguous/private-metadata fallbacks are not permanent identities, source immutability or new read/work permission.
 
 Current completion index fields are packet-local, not persistent historical indices; earlier saved #N headings keep their original meaning. Session completion streams are adopted work in progress, not an available action; do not invent a start-stream command, initialize a missing counter or reinterpret old headings. A kernel-only path commits numbered snapshots/counters/activation atomically. Its internal runtime bridge requires trusted fresh-session opt-in plus current manager/generation binding; the default entrypoint does not opt in and no public tool/command exposes it. Unknown state does not fall back to local numbering on that path. Startup/reload/resume, including ambiguous imports, cannot resume a stream automatically; stored numbers remain data, not a new session grant. A pending target or projected scope is not an active stream. Missing state never authorizes bootstrap, and unknown/conflicting delivery never authorizes bypass or reallocation. Saved numbers stay exact; an admitted unavailable counter or unfitting whole range freezes an unknown index (quoted "?" in fresh YAML, #? in older layouts) rather than resetting or partially numbering a packet.
 
@@ -168,7 +177,7 @@ When a pi-actors operation fails:
 3. Report resolver, registry, activation, Run, Trace, or Control truth exactly.
 4. Retry only after the owning state is healthy.
 
-Stop if spawn and registry resolve the same Recipe differently. Stop if registration persists but is not callable. Stop if an operation cannot be proven through pi-actors surfaces.
+Stop if spawn and registry resolve the same Recipe differently. When tool exposure was requested, stop if registration persists but is not callable. A `retained_recipe` receipt with `activation: not_requested` instead permits ordinary Recipe reuse, not a claim of tool invocation. Stop if an operation cannot be proven through pi-actors surfaces.
 
 Never recover by copying maintained Recipe args, defaults, Control, artifacts, or helper commands. Never hard-code a `{skill_dir}` replacement path. Never introduce `bash -lc`, `eval`, direct bundled-helper execution, or shell backgrounding to bypass resolution. Never call `spawn` and claim a tool call. Use [diagnostics](./references/diagnostics.md) for the safe next action.
 

package/dist/skills/actors/references/persistent-tools.md

@@ -2,6 +2,14 @@
 
 Use a persistent tool when the agent should call a trusted capability by name across turns or sessions. Use `spawn` instead for one-off Recipe execution.
 
+## Select the capability, not the execution mode
+
+Both sync and async Recipes can be tools. Sync invocation awaits the result; async invocation returns a launch receipt and the eventual result arrives separately. Neither synchrony nor a model-backed implementation establishes usefulness. A subagent-backed tool launches a capability, not a saved live subagent. Synchronous tools execute inline; non-singleton async calls launch Run executions, while singleton attachment follows its existing compatibility contract.
+
+Prefer a stable purpose/name, caller-owned parameterized inputs, a clear result/acceptance boundary, understood effects and failure/cancellation limits, and meaningful leverage over existing tools or one-off `spawn`. Do not register every transient mission or a generic arbitrary-prompt alias merely to add a name. A successful registration is not permission for new effects, and a launch receipt is not successful task completion.
+
+Current user-root Recipes are tool candidates by location; Skill components do not become tools automatically. Explicit create-only retention is supported through `register_tool expose=false`; it is separate from tool exposure. Automatic retained lifecycle is not implemented. Read-only `inspect target=recipes view=summary` reports retained counts for `recipes/library`; use `verbose=true` for exact `retained` paths, resolved mode, invalid/disabled state and diagnostics. Reuse a valid enabled entry through `spawn recipe=<exact path>` with required caller values, or deliberately register it with `from=<exact path>`. A stored definition is not review, activation or Run evidence; use `tool:<name>` for activation and `runtime view=runs` for running instances. A `library/<stem>` usage-lineage label is private accounting identity, not a callable name or Skill Recipe reference; reuse the exact file path from inspection. Do not populate or migrate the live registry manually. `expose` is a registration input, not a Recipe field; do not invent review actions or bypass unsupported retained mutations. Existing explicit `register_tool` works for both modes; automatic review remains under its existing policy. Launch counts and value-free structural review alone do not establish semantic purpose, a good name, or accepted useful reuse.
+
 ## Choose one source mode
 
 ```text
@@ -32,9 +40,19 @@ Resolution uses Pi's authoritative active-session Skill snapshot across every Sk
 
 Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
 
+## Retain without exposing a tool
+
+Use `register_tool name=<name> expose=false from=<skill>/<recipe>` or a trusted `template` source to create `recipes/library/<name>.json`. A description is still required for authored command templates; source defaults/args/origins still belong to the maintained Recipe. This is create-only: retained `update=true`, null/empty deletion, `draft` mode and direct Recipe dependencies on managed disposable drafts are rejected, including Recipe-valued template leaves. A duplicate retained JSON/Markdown stem is a conflict; no older file is overwritten.
+
+The `kind: retained_recipe`, `activation: not_requested` receipt confirms persistence/admission, not host activation or review. It returns the exact Recipe path and required/optional argument names, without global callability flags or default values. A same-named tool is left untouched. Use the exact returned path with `spawn`; if compact output omits the whole path, follow its read-only verbose Recipe inspection hint rather than guessing it. Retention records no launch and makes no self-contained-backup promise for referenced sources.
+
+To expose a retained capability deliberately, call ordinary `register_tool name=<tool> from=<exact retained path>`, prove activation below, then call the actual tool. Deleting that admitted wrapper through the ordinary deletion path leaves the retained source; it does not stop active Runs. This is not a migration or safe-retention rule for old standalone tools.
+
+Publication uses a complete atomic no-overwrite file link; unsupported filesystems refuse without an overwrite fallback. A storage, admission or lock-release failure can follow committed bytes. Inspect the retained inventory and preserve the original cause; do not blindly repeat the request or delete an uncertain file.
+
 ## Prove registration
 
-Read registration as a state transition, not one success word:
+When tool exposure was requested, read registration as a state transition, not one success word:
 
 ```text
 resolved
@@ -46,7 +64,7 @@ resolved
 → callable_now
 ```
 
-When `callable_now` is true, call the actual generated tool and verify `launch_kind: "tool"` when provenance matters. When false, stop at the reported activation boundary and use tool/Recipe diagnosis. A Recipe spawn is not an activation test or tool invocation substitute.
+For tool exposure, when `callable_now` is true, call the actual generated tool and verify `launch_kind: "tool"` when provenance matters. When false, stop at the reported activation boundary and use tool/Recipe diagnosis. A Recipe spawn is not an activation test or tool invocation substitute.
 
 Use:
 

package/dist/skills/actors/references/runs.md

@@ -24,7 +24,7 @@ inspect target=run:<id> view=trace
 inspect target=run:<id> view=control
 ```
 
-Fresh root completions use index-first YAML frontmatter (index, run, state, admitted kind), followed by raw left-edge Markdown. New source captures put all runtime metadata above that body, with no service/file footer. files.groups gives one literal root plus relative entry paths; files.read_first names zero-based group/entry indices for the first useful source, not an automatic read. role/purpose guidance is English; Actor Markdown and path/name bytes are unchanged. External paths use separate roots; unknown bases remain explicit rather than guessed from cwd or Run id. Known cut counts alone may follow the cut body; unknown-loss warnings and packet omission/inventory facts stay in the header. Retained captures preserve their old bytes and presentation. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
+Fresh root completions use YAML frontmatter (run, state, admitted kind), followed by raw left-edge Markdown. Prepend the packet-local index only when two or more results are shown. Exactly one shown result omits its index even with omitted results; preserve omission/inventory metadata, internal member/generation/correlation and every saved message. This rule does not apply to numbered streams. New source captures put all runtime metadata above that body, with no service/file footer. files.groups gives one literal root plus relative entry paths; files.read_first names zero-based group/entry indices for the first useful source, not an automatic read. role/purpose guidance is English; Actor Markdown and path/name bytes are unchanged. External paths use separate roots; unknown bases remain explicit rather than guessed from cwd or Run id. Known cut counts alone may follow the cut body; unknown-loss warnings and packet omission/inventory facts stay in the header. Retained captures preserve their old bytes and presentation. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
 
 Current completion index values restart within each packet; they are not session-wide historical references. Completion streams are adopted but not enabled, and no start-stream command is available yet. Do not infer an active stream or reset a counter from missing metadata or a pending target, and never relabel older saved packets. The kernel-only allocator now commits fixed scope/order/indices, the counter and first-packet target activation together, and an internal fresh-session bridge can use it after current manager/generation admission. The default runtime does not opt in; no public action exposes it. Event reason or a matching ID alone is insufficient. Old callbacks/wrappers cannot act after replacement; fresh wrappers must belong to the current original manager. Startup/reload/resume and ambiguous imports remain closed to stream capture/ACK, without changing saved packets or inferring a counter from history. Its whole-range exhaustion or admitted counter unavailability yields a frozen unknown index (quoted "?" in fresh YAML; #? in older saved layouts), never partial indices or an automatic fresh stream. Old packets retain their original scope while a pending switch waits; uncertainty does not permit reallocation. Stream state outlives packet cleanup/receipt rotation. Malformed/missing state remains refused, not a zero counter or proof of non-connection.
 

package/dist/skills/recipe-memory/SKILL.md

@@ -7,6 +7,12 @@ description: Use only for internal automatic Recipe-memory review, diagnosis, or
 
 Use this Skill only when automatic draft-memory or active-tool review needs diagnosis or bounded recovery. Normal agents must not spawn, register, specialize, or invoke `recipe-memory/draft-review` or `recipe-memory/tool-review`; they are package-owned internal reviewer components.
 
+## Evidence limits
+
+Automatic reviewers receive value-free contract shape, risk labels, usage counts, and batch-local equality groups, not executable content, descriptions, paths, or canonical names. Structural evidence and launch counts alone do not establish semantic purpose, good tool names, successful reuse, or accepted outcomes. Promotion preserves unchanged captured executable content; it does not generalize a one-off mission.
+
+Explicit create-only retention is owned by `actors` through `register_tool expose=false`, not by these internal reviewers. Automatic retained lifecycle is not implemented. Current draft promote/discard and tool-review behavior are unchanged. Missing evidence is unknown; this guidance adds no retain/defer action, retry permission, automatic rewrite, or live migration. Do not bypass confidentiality or edit review state to simulate the future policy.
+
 ## Diagnose first
 
 ```text

package/docs/README.md

@@ -18,6 +18,7 @@ Living index of all documentation in the `/docs` directory.
 
 ## Planned Contracts
 
+- [capability-memory.md](./capability-memory.md) — Adopted separation of retained Recipes and deliberate tool exposure, with implemented read-only library inventory and isolated usage identity; explicit create-only persistence is implemented without tool activation, while retained update/delete and automatic lifecycle/migration remain separate
 - [windows-process-observation.md](./windows-process-observation.md) — User-approved recovery preparation: passing inert Windows x64 MI child experiment, reviewed unadmitted raw codec and artifact preparation contract; broader profile evidence, unsigned asset distribution and default activation remain separate gates
 - [run-supervision.md](./run-supervision.md) — Accepted future supervision contract and implemented AX/evidence slices, with same-logical-session file research and candidate-bound acceptance; the next selective AX/runtime release does not enable deadlines, independent owner-loss supervision or public completion streams
 - [inactive-foundations-inventory.md](./inactive-foundations-inventory.md) — Reachability and package evidence for packaged-but-unactivated supervision, stream-numbering and native foundations, distinguishing reviewed runtime dependencies from optional ones; no removal decision, nothing activated