@llblab/pi-actors 0.57.1 → 0.58.0

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/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.1",
+  "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
@@ -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/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