@llblab/pi-actors 0.57.1 → 0.58.1

package/lib/recipes-usage.ts

@@ -101,7 +101,7 @@ function readRecipeSource(path: string): { fingerprint: string } | undefined {
 
 function inferRecipeRoot(path: string): string {
   const parent = dirname(resolve(path));
-  return basename(parent) === "drafts" ? dirname(parent) : parent;
+  return ["drafts", "library"].includes(basename(parent)) ? dirname(parent) : parent;
 }
 
 function pathKey(path: string, recipeRoot: string): string {
@@ -112,8 +112,9 @@ function pathKey(path: string, recipeRoot: string): string {
   return relation.replaceAll("\\", "/");
 }
 
-function recipeName(path: string): string {
-  return basename(path).replace(/\.(?:json|md)$/u, "");
+function recipeName(path: string, recipeRoot: string): string {
+  const name = basename(path).replace(/\.(?:json|md)$/u, "");
+  return dirname(resolve(path)) === resolve(recipeRoot, "library") ? `library/${name}` : name;
 }
 
 function lineageFilename(lineageName: string): string {
@@ -232,8 +233,10 @@ function findRelocatedRecipe(
   index: RecipeUsageIndex,
   fingerprint: string,
   recipeRoot: string,
+  newPath: string,
 ): { indexedName: string; path: string; record: RecipeUsageRecord } | undefined {
   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);
     return found?.record.fingerprint === fingerprint
@@ -288,7 +291,7 @@ export function ensureRecipeLineage(
       const source = readRecipeSource(path);
       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) {
@@ -392,11 +395,11 @@ export function recordRecipeLaunch(
       if (!source) 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)
@@ -436,7 +439,7 @@ export function recordRecipeLaunch(
           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)
@@ -591,7 +594,7 @@ export function moveRecipeUsage(
       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/lib/registry.ts

@@ -4,8 +4,8 @@
  * 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.ts";
 import * as Config from "./config.ts";
@@ -28,6 +28,7 @@ export interface RegisterToolInput {
   name?: string;
   description?: string;
   async?: boolean;
+  expose?: boolean;
   template?: CommandTemplates.CommandTemplateValue | null;
   from?: string;
   defaults?: Record<string, unknown>;
@@ -38,13 +39,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;
@@ -811,12 +815,18 @@ function executeRegisterToolUnlocked<TContext>(
   params: unknown,
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
-): RegisterToolResult {
+): RegisterToolResult | (() => RegisterToolResult) {
   const rawInput =
     params && typeof params === "object"
       ? (params as RegisterToolInput)
       : ({} as RegisterToolInput);
   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);
   const name = Identity.normalizeToolName(input.name);
@@ -995,16 +1005,191 @@ function executeRegisterToolUnlocked<TContext>(
   };
 }
 
+class RetainedRecipeRefusal extends Error {
+  readonly reason: string;
+  constructor(field: string, reason: string, cause?: unknown) {
+    super(ExecutionOutput.formatToolText(registryMetadataText({ field, result: reason })), { cause });
+    this.reason = reason;
+  }
+}
+
+function retainedDirectory(path: string) {
+  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: ReturnType<typeof retainedDirectory>): void {
+  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: string, ownTargetPublished = false): void {
+  for (const candidate of ownTargetPublished ? [path.replace(/\.json$/u, ".md")] : [path, path.replace(/\.json$/u, ".md")]) {
+    try { lstatSync(candidate); }
+    catch (error) {
+      let code: unknown;
+      try { code = (error as NodeJS.ErrnoException | undefined)?.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: string) {
+  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: string, path: string): boolean {
+  const relation = relative(resolve(root), resolve(path));
+  return relation === "" || (!isAbsolute(relation) && !/^\.\.(?:[\\/]|$)/u.test(relation));
+}
+
+function assertRetainedSourceLifetime(source: string, root: string, field: string): void {
+  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: unknown, path: string, root: string, context: RecipesContext.RecipeResolutionContext): void {
+  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 as Record<string, unknown>;
+    assertRetainedTemplateLifetimes(node.template, path, root, context);
+    assertRetainedTemplateLifetimes(node.recover, path, root, context);
+  }
+}
+
+function retainRecipe<TContext>(
+  input: RegisterToolInput,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  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 as keyof typeof before] !== after[key as keyof typeof after]) ||
+            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" as const, result: "retained" as const, persisted: true, resolved: true,
+            validated: true, activation: "not_requested" as const, 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<TContext>(
   params: unknown,
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
 ): Promise<RegisterToolResult> {
   const input = params as RegisterToolInput;
-  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),
-  );
+  let result: RegisterToolResult | (() => RegisterToolResult);
+  if (!input.name) 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/lib/run-delivery.ts

@@ -69,7 +69,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. */
@@ -467,8 +467,12 @@ function isFrontmatterCompletionLayout(layout: unknown): boolean {
   return layout === "frontmatter_v1" || layout === "frontmatter_v2";
 }
 
+function isRootedCompletionLayout(layout: unknown): boolean {
+  return layout === "completion_yaml_files_v1" || layout === "completion_yaml_files_v2";
+}
+
 function isYamlCompletionLayout(layout: unknown): boolean {
-  return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+  return layout === "completion_yaml_core_v1" || isRootedCompletionLayout(layout);
 }
 
 function isSharedCompletionLayout(layout: unknown): boolean {
@@ -895,7 +899,7 @@ export function requestRunCompletionStream(input: { tempDir: string; ownerId: st
 }
 
 export function admitRunCompletionBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  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. */
@@ -905,10 +909,10 @@ export function captureRunCompletionStreamBatch(input: AdmitRunCompletionBatchIn
 
 /** Private ordinary candidate composition; stream capture retains its separately gated codec. */
 export function captureRunCompletionYamlCandidateBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v2");
 }
 
-function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" = "frontmatter_v2"): RunCompletionBatch {
+function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" | "completion_yaml_files_v2" = "frontmatter_v2"): RunCompletionBatch {
   const now = (input.now ?? new Date()).toISOString();
   if (Object.hasOwn(input, "presentationFormat")) throw new Error("Completion presentation selection is not supported; new batches use AX.");
   if (Object.hasOwn(input, "numbering")) throw new Error("Completion numbering is assigned only by journal capture");
@@ -1869,12 +1873,13 @@ type PreparedCompletionYamlProjection =
 function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: readonly { row: CompletionRow; location?: CompletionPiece }[],
   references: ReadonlySet<number>, ordered: readonly RunCompletionBatchMember[]): PreparedCompletionYamlProjection {
   const packet: CompletionYamlPacket = { 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: Record<string, CompletionYamlData> = { index: displayed };
+    const metadata: Record<string, CompletionYamlData> = localSingleton ? {} : { index: displayed };
     for (const piece of row.pieces) {
       if (piece.block) continue;
       if (!piece.field) return { state: "unsupported" };
@@ -1917,7 +1922,9 @@ function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: r
     }
     packet.records.push({ metadata, parts });
   }
-  const service: Record<string, CompletionYamlData> = rooted ? { header_layout: "rooted_files_v1" } : {};
+  const service: Record<string, CompletionYamlData> = 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;
@@ -2349,7 +2356,7 @@ export function readRunCompletionPresentation(content: string, value: unknown):
         !completionYamlKeys(hint, ["format", "content_sha256"]) || hint.format !== completionYamlCodec ||
         hint.content_sha256 !== createHash("sha256").update(content).digest("hex")) return full;
     const segments: NonNullable<RunCompletionPresentationView["segments"]>[number][] = [];
-    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) segments.push({ kind: "separator", text: "\n" });
@@ -2581,6 +2588,8 @@ export function encodeCompletionYamlCarrier(input: unknown): { state: "available
       typeof packet.batchId !== "string" || !packet.batchId.length || !Array.isArray(packet.records) || packet.records.length > 64 ||
       (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: string[] = [];
   for (let index = 0; index < Math.max(1, packet.records.length); index++) {
     const row: CompletionYamlData | undefined = packet.records[index];
@@ -2596,13 +2605,15 @@ export function encodeCompletionYamlCarrier(input: unknown): { state: "available
       if (!completionYamlMapping(row) || !completionYamlKeys(row, ["metadata", "parts"]) ||
           !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/lib/tools-inspect.ts

@@ -448,9 +448,6 @@ function inspectRecipes(
   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 as {
@@ -506,7 +503,11 @@ function inspectRecipes(
       ...(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
@@ -532,6 +533,8 @@ function inspectRecipes(
         error: `Ambiguous active Skill Recipe namespace ${name}`,
       })),
     drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+    retained: retained.recipes,
+    retained_diagnostics: retained.diagnostics,
   };
   return {
     ...summary,

package/lib/tools-register.ts

@@ -40,6 +40,7 @@ export function createRegisterToolDefinition<TContext>(
           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/lib/tools-response.ts

@@ -517,6 +517,12 @@ export function recipeRegistryNextActions(
   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 =
@@ -532,16 +538,18 @@ export function compactYamlDocument(value: Record<string, unknown>): string {
   return `\n${text.replace(/\n$/u, "")}`;
 }
 
+function recipeInspectionHint(action: string): { view: "doctor" | "imports" | "summary"; verbose?: true } | undefined {
+  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: string, byteBudget: number): YamlPart {
-  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],
-  ] as const;
-  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);
@@ -550,10 +558,8 @@ export function nextActionMetadata(action: string, byteBudget: number): YamlPart
 
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export function formatInspectionHint(action: string): string {
-  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(
@@ -563,6 +569,7 @@ export function compactRecipeRegistry(
   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)
@@ -574,7 +581,7 @@ export function compactRecipeRegistry(
     ? (summary.next_actions as string[])
     : [];
   const hint = nextActions.length ? nextActionMetadata(nextActions[0]!, Limits.RUN_DELIVERY_MODEL_MAX_BYTES) : undefined;
-  const render = (): Record<string, unknown> => ({ recipes: "registry", active, drafts, shadowed, invalid, disabled,
+  const render = (): Record<string, unknown> => ({ recipes: "registry", active, drafts, retained, shadowed, invalid, disabled,
     current_policy: currentPolicy, skill_catalog_partial: skillCatalogPartial, recommendations, diagnostics,
     ...(hint ? hint.selected : {}) });
   return hint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.57.1",
+  "version": "0.58.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/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.