@llblab/pi-actors 0.57.0 → 0.58.0

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";
+  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";
   /** 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 isYamlCompletionLayout(layout: unknown): boolean {
+  return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+}
+
 function isSharedCompletionLayout(layout: unknown): boolean {
-  return layout === "headings_shared_results" || layout === "headings_shared_kinds" || layout === "completion_yaml_core_v1" || isFrontmatterCompletionLayout(layout);
+  return layout === "headings_shared_results" || layout === "headings_shared_kinds" || isYamlCompletionLayout(layout) || isFrontmatterCompletionLayout(layout);
 }
 
 function parseBatch(value: unknown): RunCompletionBatch {
@@ -512,7 +516,7 @@ function parseBatch(value: unknown): RunCompletionBatch {
     throw new Error("Completion shared text budget is invalid");
   }
   const numberingDescriptor = Object.getOwnPropertyDescriptor(record, "numbering");
-  if (numberingDescriptor && (resultLayout === "completion_yaml_core_v1" || !Object.hasOwn(numberingDescriptor, "value") || presentationFormat !== "ax_records" || (resultLayout !== "headings" && resultLayout !== "headings_flat_omissions" && resultLayout !== "headings_outcomes" && !isSharedCompletionLayout(resultLayout)))) {
+  if (numberingDescriptor && (isYamlCompletionLayout(resultLayout) || !Object.hasOwn(numberingDescriptor, "value") || presentationFormat !== "ax_records" || (resultLayout !== "headings" && resultLayout !== "headings_flat_omissions" && resultLayout !== "headings_outcomes" && !isSharedCompletionLayout(resultLayout)))) {
     throw new Error("Completion numbering requires a canonical captured heading layout");
   }
   const numbering = numberingDescriptor ? parseCompletionNumbering(numberingDescriptor.value, members.length) : undefined;
@@ -891,7 +895,7 @@ export function requestRunCompletionStream(input: { tempDir: string; ownerId: st
 }
 
 export function admitRunCompletionBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  return captureCompletionBatch(input, false, "completion_yaml_core_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 
 /** Kernel-only opt-in; ordinary Pi capture stays fenced until session/lifecycle integration is admitted. */
@@ -901,10 +905,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_core_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 
-function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" = "frontmatter_v2"): RunCompletionBatch {
+function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" = "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");
@@ -917,7 +921,7 @@ function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: b
     members: input.members,
     phase: "pending",
   });
-  const draft: RunCompletionBatch = layout === "completion_yaml_core_v1"
+  const draft: RunCompletionBatch = isYamlCompletionLayout(layout)
     ? parseBatch({ ...captured, result_layout: layout }) : { ...captured, result_layout: layout };
   return mutateJournal(input.tempDir, input.ownerId, (journal) => {
     let batch = draft;
@@ -946,9 +950,9 @@ function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: b
     } else if (journal.completion_stream) {
       throw new Error("Completion stream capture requires the numbered kernel path; stream state is retained");
     }
-    if (layout !== "completion_yaml_core_v1") batch = retainSharedCompletionTexts(batch);
+    if (!isYamlCompletionLayout(layout)) batch = retainSharedCompletionTexts(batch);
     if (projectCompletionBatchMessage(batch).membersShown === batch.members.length) {
-      if (layout === "completion_yaml_core_v1") batch = retainSharedCompletionTexts(batch);
+      if (isYamlCompletionLayout(layout)) batch = retainSharedCompletionTexts(batch);
       journal.completion_batch = batch;
       return batch;
     }
@@ -1515,7 +1519,7 @@ function isRoutineCompletionSummary(member: RunCompletionBatchMember): boolean {
 }
 
 function completionRecordRow(member: RunCompletionBatchMember, index: number, byIdentity: Map<string, RunCompletionBatchMember>, flat = false, layout?: RunCompletionBatch["result_layout"], textBudget?: number): CompletionRow {
-  const frontmatter = isFrontmatterCompletionLayout(layout) || layout === "completion_yaml_core_v1";
+  const frontmatter = isFrontmatterCompletionLayout(layout) || isYamlCompletionLayout(layout);
   const simpleKinds = frontmatter || layout === "headings_shared_kinds", shared = isSharedCompletionLayout(layout);
   const outcomes = shared || layout === "headings_outcomes", directOmission = outcomes || layout === "headings_flat_omissions";
   const run = member.run.startsWith("run:") ? member.run.slice(4) : member.run;
@@ -1780,6 +1784,83 @@ function completionYamlReferences(row: CompletionRow): Record<string, Completion
   return technical;
 }
 
+/** Split selected paths without normalize/resolve/relative: dot and symlink routes must not be rewritten. */
+function rootedCompletionPath(path: CompletionYamlData, runRoot?: string): { root: string; path: string } | undefined {
+  if (typeof path !== "string" || !path.isWellFormed()) return undefined;
+  const windows = /^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/])/u.test(path);
+  const separator = windows ? /[\\/]/u : /\//u;
+  if (!windows && !path.startsWith("/")) return undefined;
+  if (path.split(separator).some(part => part === "." || part === "..")) return undefined;
+  if (runRoot && path.startsWith(runRoot)) {
+    const tail = path.slice(runRoot.length);
+    if (separator.test(runRoot.slice(-1)) ? tail.length > 0 : separator.test(tail[0] ?? "")) {
+      const relative = separator.test(runRoot.slice(-1)) ? tail : tail.slice(1);
+      if (relative && !separator.test(relative[0]!)) return { root: runRoot, path: relative };
+    }
+  }
+  let split = -1;
+  for (let i = 0; i < path.length; i++) if (separator.test(path[i]!)) split = i;
+  if (split < 0 || split === path.length - 1) return undefined;
+  const end = split === 0 || (windows && split === 2 && path[1] === ":") ? split + 1 : split;
+  return { root: path.slice(0, end), path: path.slice(split + 1) };
+}
+
+/** Body-free, read-free navigation over already selected references. Roots are presentation bases, not containment proof. */
+function completionRootedFiles(row: CompletionRow, member: RunCompletionBatchMember, locations?: RunDirectoryNavigation): Record<string, CompletionYamlData> {
+  const technical = completionYamlReferences(row), files: Record<string, CompletionYamlData> = {};
+  const groups: Array<{ root: CompletionYamlData; entries: Record<string, CompletionYamlData>[] }> = [];
+  const runRoot = locations?.state === "available" ? locations.directory : undefined;
+  const group = (root: CompletionYamlData): number => {
+    const found = groups.findIndex(item => item.root === root);
+    if (found >= 0) return found;
+    groups.push({ root, entries: [] }); return groups.length - 1;
+  };
+  let priority = Infinity;
+  const add = (path: CompletionYamlData, entry: Record<string, CompletionYamlData>, rank = Infinity, base?: string): void => {
+    const selected = rootedCompletionPath(path, runRoot);
+    const index = group(selected?.root ?? (base === undefined ? null : completionYamlString(base)));
+    const selectedPath = selected?.path ?? path;
+    groups[index]!.entries.push({ ...entry, path: selectedPath,
+      ...(!selected && base === undefined ? { path_basis: "as_recorded", base_unavailable: true } : {}) });
+    if (selected && rank < priority) {
+      priority = rank; files.read_first = { group: index, entry: groups[index]!.entries.length - 1 };
+    }
+  };
+  for (const [role, purpose, rank] of [
+    ["primary", "Full result text", 0], ["diagnostic_metadata", "Recorded error and command metadata", 1],
+    ["artifact_inventory", "Declared artifact inventory; target availability unproven", 2],
+  ] as const) {
+    const detail = technical[role] as Record<string, CompletionYamlData> | undefined;
+    if (!detail) continue;
+    const { source: rawSource, ...facts } = detail;
+    const { path, ...binding } = rawSource as Record<string, CompletionYamlData>;
+    add(path!, { role, purpose, ...facts, source: binding }, rank);
+    delete technical[role];
+  }
+  const artifacts = technical.artifacts as { scope: string; declarations: { name: CompletionYamlData; path: CompletionYamlData }[] } | undefined;
+  if (artifacts) {
+    for (const item of artifacts.declarations)
+      add(item.path, { role: "artifact", purpose: "Declared artifact", name: item.name, scope: artifacts.scope, state: "declared" });
+    delete technical.artifacts;
+  }
+  if (locations?.state === "available") {
+    const { directory, files: selectedFiles, ...observation } = locations;
+    files.observation = { ...observation, run: completionYamlString(locations.run), run_instance_id: completionYamlString(locations.run_instance_id),
+      group: group(completionYamlString(directory)) };
+    for (const item of selectedFiles) {
+      const { path, ...facts } = item;
+      const purpose = item.role === "result" ? "Recorded result metadata" : item.role === "execution" ? "Recorded execution and capture locations" : "Recorded Run file";
+      add(typeof path === "string" ? completionYamlString(path) : null, { ...facts, purpose },
+        item.state === "present" && item.role === "result" ? 3 : item.state === "present" && item.role === "execution" ? 4 : Infinity, directory);
+    }
+  } else if (locations) files.observation = { ...locations, run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id) };
+  if (groups.length) {
+    files.groups = groups;
+  }
+  if (Object.keys(technical).length) files.notes = technical;
+  return files;
+}
+
 type PreparedCompletionYamlProjection =
   | { state: "unsupported" }
   | { state: "overbudget" }
@@ -1788,6 +1869,7 @@ 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";
   if (!safe.batch_id.isWellFormed()) return { state: "unsupported" };
   for (const [index, { row, location }] of candidates.entries()) {
     const member = ordered[index]!;
@@ -1804,28 +1886,38 @@ function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: r
       else if (key === "artifact_declarations") metadata[key] = member.artifact_inventory?.declarations_total ?? Object.keys(member.artifacts ?? {}).length;
       else metadata[key] = completionYamlString(value);
     }
-    const technical = completionYamlReferences(row);
-    if (Object.keys(technical).length) metadata.references = technical;
-    if (references.has(index) && location) {
-      const navigation = safe.file_navigation!.find(item => safe.members[item.member_index] === member)!;
-      // Navigation is already decoded native data, not the JSON display field.
-      const locations = navigation.locations;
-      metadata.run_files = { run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id),
-        locations: locations.state === "available" ? { ...locations, run: completionYamlString(locations.run),
-          run_instance_id: completionYamlString(locations.run_instance_id), directory: completionYamlString(locations.directory),
-          files: locations.files.map(file => ({ ...file, ...(typeof file.path === "string" ? { path: completionYamlString(file.path) } : {}) })) } as CompletionYamlData
-          : { ...locations } };
+    const navigation = references.has(index) && location
+      ? safe.file_navigation!.find(item => safe.members[item.member_index] === member)!.locations : undefined;
+    if (rooted) {
+      const files = completionRootedFiles(row, member, navigation);
+      if (Object.keys(files).length) metadata.files = files;
+    } else {
+      const technical = completionYamlReferences(row);
+      if (Object.keys(technical).length) metadata.references = technical;
+      if (navigation) {
+        metadata.run_files = { run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id),
+          locations: navigation.state === "available" ? { ...navigation, run: completionYamlString(navigation.run),
+            run_instance_id: completionYamlString(navigation.run_instance_id), directory: completionYamlString(navigation.directory),
+            files: navigation.files.map(file => ({ ...file, ...(typeof file.path === "string" ? { path: completionYamlString(file.path) } : {}) })) } as CompletionYamlData
+              : { ...navigation } };
+      }
     }
     const parts: CompletionYamlPart[] = [];
     const add = (part: CompletionYamlPart) => { if (parts.length) parts.push({ marker: "\n" }); parts.push(part); };
     for (const piece of row.pieces) if (piece.block) {
       if (!piece.text.isWellFormed()) return { state: "unsupported" };
-      add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
+      if (rooted && piece.block === "marker" && !/^\[[0-9]+ characters omitted\]$/u.test(piece.text)) {
+        metadata.text_warnings ??= [];
+        (metadata.text_warnings as CompletionYamlData[]).push(piece.text);
+      } else add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
+    }
+    if (safe.file_navigation !== undefined && !references.has(index)) {
+      if (rooted) metadata.run_files_omission = { reason: "packet_byte_limit", shown: 0, omitted: 1, total: 1 };
+      else add({ marker: "Run-file reference omitted (packet byte limit)." });
     }
-    if (safe.file_navigation !== undefined && !references.has(index)) add({ marker: "Run-file reference omitted (packet byte limit)." });
     packet.records.push({ metadata, parts });
   }
-  const service: Record<string, CompletionYamlData> = {};
+  const service: Record<string, CompletionYamlData> = rooted ? { header_layout: "rooted_files_v1" } : {};
   const omitted = safe.members.length - candidates.length;
   if (omitted) {
     service.omitted_results = omitted;
@@ -1841,7 +1933,11 @@ function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: r
     service.numbering = { ...safe.numbering, session_id: completionYamlString(safe.numbering.session_id), member_order: [...safe.numbering.member_order] };
     if (safe.numbering.kind === "unavailable") service.numbering_unavailable = safe.numbering.reason;
   }
-  if (safe.inventory_source) service.result_inventory = { ...safe.inventory_source, path: completionYamlString(safe.inventory_source.path) };
+  if (safe.inventory_source) {
+    const path = rooted ? rootedCompletionPath(safe.inventory_source.path) : undefined;
+    service.result_inventory = { ...safe.inventory_source,
+      ...(path ? { root: path.root, path: path.path } : { path: completionYamlString(safe.inventory_source.path) }) };
+  }
   if (Object.keys(service).length) packet.service = service;
   const chunks: string[] = [];
   let bytes = 0;
@@ -1890,7 +1986,7 @@ export function projectRunCompletionYamlPrototype(batch: unknown):
   }
 }
 
-function projectCompletionRecords(safe: RunCompletionBatch, assembler: "legacy" | "yaml" = safe.result_layout === "completion_yaml_core_v1" ? "yaml" : "legacy"): { message: string; membersShown: number; compact_ranges: [number, number][]; textBudget?: number; blocks?: readonly CompletionBlock[] } {
+function projectCompletionRecords(safe: RunCompletionBatch, assembler: "legacy" | "yaml" = isYamlCompletionLayout(safe.result_layout) ? "yaml" : "legacy"): { message: string; membersShown: number; compact_ranges: [number, number][]; textBudget?: number; blocks?: readonly CompletionBlock[] } {
   const frontmatter = isFrontmatterCompletionLayout(safe.result_layout) || assembler === "yaml";
   const shared = isSharedCompletionLayout(safe.result_layout);
   const maxBytes = shared ? Limits.RUN_COMPLETION_MODEL_MAX_BYTES : Limits.RUN_DELIVERY_MODEL_MAX_BYTES;
@@ -2118,7 +2214,7 @@ export function projectRunCompletionBatchPresentation(batch: RunCompletionBatch)
   const safe = parseBatch(batch);
   if (safe.presentation_format !== "ax_records" && safe.presentation_format !== "ax_records_v3") return { content: projectCompletionBatchMessage(safe).message };
   const result = safe.result_layout !== undefined ? projectCompletionRecords(safe) : projectRetainedRecordCompletionBatch(safe);
-  if (safe.result_layout === "completion_yaml_core_v1") return { content: result.message, presentation: Object.freeze({
+  if (isYamlCompletionLayout(safe.result_layout)) return { content: result.message, presentation: Object.freeze({
     format: "completion_yaml_core_v1", content_sha256: createHash("sha256").update(result.message).digest("hex"),
   }) };
   return { content: result.message, presentation: Object.freeze({ format: isFrontmatterCompletionLayout(safe.result_layout) ? "completion_frontmatter_v1" : safe.presentation_format, content_sha256: createHash("sha256").update(result.message).digest("hex"),
@@ -2253,19 +2349,22 @@ 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 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" });
-      const metadata = Object.fromEntries(Object.entries(record.metadata).filter(([key]) => key !== "references" && key !== "run_files"));
+      const metadata = Object.fromEntries(Object.entries(record.metadata).filter(([key]) => rooted || (key !== "references" && key !== "run_files")));
+      if (rooted && index === 0 && Object.keys(facts).length) metadata.delivery = facts;
       const header = renderYamlMetadata(metadata, completionYamlMaxBytes);
       if (header.state !== "available") return full;
       segments.push({ kind: "header", text: record.parts.length ? `---\n${header.text}---` : header.text.replace(/\n$/u, "") });
       for (const part of record.parts) segments.push("body" in part ? { kind: "body", text: part.body } : { kind: "marker", text: part.marker });
     }
-    if (core.packet.service) {
-      const service = renderYamlMetadata(core.packet.service, completionYamlMaxBytes);
+    if (core.packet.service && (!rooted || !core.packet.records.length)) {
+      const service = renderYamlMetadata(rooted ? facts : core.packet.service, completionYamlMaxBytes);
       if (service.state !== "available") return full;
       if (segments.length) segments.push({ kind: "separator", text: "\n" });
-      segments.push({ kind: "service", text: service.text.replace(/\n$/u, "") });
+      segments.push({ kind: rooted ? "header" : "service", text: service.text.replace(/\n$/u, "") });
     }
     return { text: segments.map(segment => segment.text).join("\n"), compact: true, records: true, yaml: true,
       segments: Object.freeze(segments.map(segment => Object.freeze(segment))) };

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 =
@@ -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.0",
+  "version": "0.58.0",
   "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
@@ -151,7 +160,7 @@ Run = Recipe + Trace + Control
 5. Send `message` only for an action declared and consumed by that controlled Recipe.
 6. Use terminal state, result, declared artifacts, and execution evidence to prove completion. When an outcome includes a retained primary-source, declaration-inventory or diagnostic-metadata reference, use that exact reference for further reading, not guessed captures or sibling files. Literal previews may be clipped; their field/range/counts describe what was shown. Diagnostic sources contain recorded command/error/failure-reason metadata only, not complete primary output; other recorded fields may be referenced without being shown. Artifact inventories list declarations only: they do not assert that target files exist or were produced, or grant body-read permission. Explicit unavailability has no guessed legacy body/path fallback.
 
-Compact launch receipts include `run_files` as nested block YAML containing the exact selected observed location values, labeled observed locations/mutable for the exact launched Run generation when the current session and physical identity agree; otherwise they report unavailability or whole-row omission. Machine `file_navigation` details stay JSON-compatible; saved terminal messages retain their own original encodings. Selectively ordinary-read those starting locations when needed; layout/size hints are not body, privacy, terminal or native proof. No evidence bodies or session-wide catalog map are read to build this row. New terminal packets also freeze bounded location rows for captured completion members at fresh current-session admission. Each shown result keeps its whole Run-file row or explicit per-record omission; wholly omitted results stay covered by result omission/inventory. This describes Run-row coverage, not a complete file/tree inventory. Older captured formats retain their original shown/omitted/total counters; unavailability remains explicit. Ordinary-read selected paths only when needed. Packet reload/render never refreshes sources, and old absent/request-only formats keep their text. Source/npm SDK verifies an explicitly requested ordinary read from a delivered terminal result path; this is research, never routine completion polling or new primary/privacy/clock/native authority. Use the request only for file investigation, not routine completion/status polling. Copied locations/hints remain data, never transferred scope; older batches keep their original text.
+Compact launch receipts include `run_files` as nested block YAML containing the exact selected observed location values, labeled observed locations/mutable for the exact launched Run generation when the current session and physical identity agree; otherwise they report unavailability or whole-row omission. Machine `file_navigation` details stay JSON-compatible; saved terminal messages retain their own original encodings. Selectively ordinary-read those starting locations when needed; layout/size hints are not body, privacy, terminal or native proof. No evidence bodies or session-wide catalog map are read to build this row. New terminal packets also freeze bounded location rows for captured completion members at fresh current-session admission. Fresh rooted completion headers group paths under literal roots with relative entries, English purposes and a read_first group/entry pointer; no cwd guess, source refresh or automatic read follows. Unknown bases stay explicit. Runtime navigation/omission/inventory facts remain above the Actor Markdown, not in a footer; retained packets keep their original projection. Each shown result keeps its whole Run-file row or explicit per-record omission; wholly omitted results stay covered by result omission/inventory. This describes Run-row coverage, not a complete file/tree inventory. Older captured formats retain their original shown/omitted/total counters; unavailability remains explicit. Ordinary-read selected paths only when needed. Packet reload/render never refreshes sources, and old absent/request-only formats keep their text. Source/npm SDK verifies an explicitly requested ordinary read from a delivered terminal result path; this is research, never routine completion polling or new primary/privacy/clock/native authority. Use the request only for file investigation, not routine completion/status polling. Copied locations/hints remain data, never transferred scope; older batches keep their original text.
 
 For selective investigation of already cataloged files, use `inspect target=runtime view=runs verbose=true`, then ordinary file tools on its current-session root-first navigation. Ordinary maps keep latest-registration order between roots and prioritize known failed subtrees within each root. For a failed investigation add status=failed: inventory is filtered, while the full owned map prioritizes observed failed subtrees across roots, always ancestors first. Priority uses only exact-generation matched inventory observations, not complete terminal truth. Launches and compatible singleton attachments populate the catalog; reads do not backfill missing locations. A `catalog: unavailable` launch warning is not workload failure: do not spawn again merely to repair navigation. The starting map's format hints do not certify syntax, encoding or complete output. See [Runs](./references/runs.md) for selective recorded-capture research and resume boundaries.
 
@@ -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/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/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. 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 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.
 
 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/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