@llblab/pi-actors 0.57.0 → 0.58.0

package/dist/lib/registry.js

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

package/dist/lib/run-delivery.d.ts

@@ -66,7 +66,7 @@ export interface RunCompletionBatch {
     /** Retained singleton capture; absence preserves older indexed bytes. Never a new-capture selector. */
     readonly single_result?: true;
     /** Captured record-list shape; no public format/version choice or source authority. */
-    readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1";
+    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. */

package/dist/lib/run-delivery.js

@@ -278,8 +278,11 @@ function parseInventorySource(value, batch) {
 function isFrontmatterCompletionLayout(layout) {
     return layout === "frontmatter_v1" || layout === "frontmatter_v2";
 }
+function isYamlCompletionLayout(layout) {
+    return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+}
 function isSharedCompletionLayout(layout) {
-    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) {
     const record = asRecord(value, "Completion batch");
@@ -322,7 +325,7 @@ function parseBatch(value) {
         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;
@@ -685,7 +688,7 @@ export function requestRunCompletionStream(input) {
     });
 }
 export function admitRunCompletionBatch(input) {
-    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. */
 export function captureRunCompletionStreamBatch(input) {
@@ -693,7 +696,7 @@ export function captureRunCompletionStreamBatch(input) {
 }
 /** Private ordinary candidate composition; stream capture retains its separately gated codec. */
 export function captureRunCompletionYamlCandidateBatch(input) {
-    return captureCompletionBatch(input, false, "completion_yaml_core_v1");
+    return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
     const now = (input.now ?? new Date()).toISOString();
@@ -710,7 +713,7 @@ function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
         members: input.members,
         phase: "pending",
     });
-    const draft = layout === "completion_yaml_core_v1"
+    const draft = isYamlCompletionLayout(layout)
         ? parseBatch({ ...captured, result_layout: layout }) : { ...captured, result_layout: layout };
     return mutateJournal(input.tempDir, input.ownerId, (journal) => {
         let batch = draft;
@@ -741,10 +744,10 @@ function captureCompletionBatch(input, numbered, layout = "frontmatter_v2") {
         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")
+        if (!isYamlCompletionLayout(layout))
             batch = retainSharedCompletionTexts(batch);
         if (projectCompletionBatchMessage(batch).membersShown === batch.members.length) {
-            if (layout === "completion_yaml_core_v1")
+            if (isYamlCompletionLayout(layout))
                 batch = retainSharedCompletionTexts(batch);
             journal.completion_batch = batch;
             return batch;
@@ -1281,7 +1284,7 @@ function isRoutineCompletionSummary(member) {
     return member.summary === (member.status === "done" ? "Run completed." : `Run ${member.status}.`);
 }
 function completionRecordRow(member, index, byIdentity, flat = false, layout, textBudget) {
-    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;
@@ -1604,8 +1607,97 @@ function completionYamlReferences(row) {
             })) };
     return technical;
 }
+/** Split selected paths without normalize/resolve/relative: dot and symlink routes must not be rewritten. */
+function rootedCompletionPath(path, runRoot) {
+    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, member, locations) {
+    const technical = completionYamlReferences(row), files = {};
+    const groups = [];
+    const runRoot = locations?.state === "available" ? locations.directory : undefined;
+    const group = (root) => {
+        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, entry, rank = Infinity, base) => {
+        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],
+    ]) {
+        const detail = technical[role];
+        if (!detail)
+            continue;
+        const { source: rawSource, ...facts } = detail;
+        const { path, ...binding } = rawSource;
+        add(path, { role, purpose, ...facts, source: binding }, rank);
+        delete technical[role];
+    }
+    const artifacts = technical.artifacts;
+    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;
+}
 function prepareCompletionYamlProjection(safe, candidates, references, ordered) {
     const packet = { 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()) {
@@ -1630,18 +1722,24 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
             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) } : {}) })) }
-                    : { ...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) } : {}) })) }
+                        : { ...navigation } };
+            }
         }
         const parts = [];
         const add = (part) => { if (parts.length)
@@ -1650,13 +1748,22 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
             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.push(piece.text);
+                }
+                else
+                    add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
             }
-        if (safe.file_navigation !== undefined && !references.has(index))
-            add({ marker: "Run-file reference omitted (packet byte limit)." });
+        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)." });
+        }
         packet.records.push({ metadata, parts });
     }
-    const service = {};
+    const service = rooted ? { header_layout: "rooted_files_v1" } : {};
     const omitted = safe.members.length - candidates.length;
     if (omitted) {
         service.omitted_results = omitted;
@@ -1676,8 +1783,11 @@ function prepareCompletionYamlProjection(safe, candidates, references, ordered)
         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 = [];
@@ -1737,7 +1847,7 @@ export function projectRunCompletionYamlPrototype(batch) {
         throw error;
     }
 }
-function projectCompletionRecords(safe, assembler = safe.result_layout === "completion_yaml_core_v1" ? "yaml" : "legacy") {
+function projectCompletionRecords(safe, assembler = isYamlCompletionLayout(safe.result_layout) ? "yaml" : "legacy") {
     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;
@@ -2024,7 +2134,7 @@ export function projectRunCompletionBatchPresentation(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")
+    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"),
             }) };
@@ -2192,10 +2302,14 @@ export function readRunCompletionPresentation(content, value) {
             hint.content_sha256 !== createHash("sha256").update(content).digest("hex"))
             return full;
         const segments = [];
+        const rooted = core.packet.service?.header_layout === "rooted_files_v1";
+        const 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;
@@ -2203,13 +2317,13 @@ export function readRunCompletionPresentation(content, value) {
             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/dist/lib/tools-inspect.js

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

package/dist/lib/tools-register.js

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

package/dist/lib/tools-response.js

@@ -512,6 +512,10 @@ export function recipeRegistryNextActions(summary, view) {
     if (summary.skill_recipe_catalog_partial === true) {
         actions.push("inspect target=recipes view=imports verbose=true");
     }
+    if ((Array.isArray(summary.retained) && summary.retained.length > 0) ||
+        (Array.isArray(summary.retained_diagnostics) && summary.retained_diagnostics.length > 0)) {
+        actions.push("inspect target=recipes view=summary verbose=true");
+    }
     if (drafts.length > 0) {
         actions.push("inspect target=recipes view=summary verbose=true");
         const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
@@ -555,6 +559,7 @@ export function compactRecipeRegistry(summary) {
     const active = count("active", summary.active), shadowed = count("shadowed", summary.shadowed);
     const invalid = count("invalid", summary.invalid), disabled = count("disabled", summary.disabled);
     const diagnostics = count("diagnostics", summary.diagnostics), drafts = count("drafts", summary.drafts);
+    const retained = count("retained", summary.retained);
     const recommendations = count("recommendations", summary.recommendations);
     const skillCatalogPartial = summary.skill_recipe_catalog_partial === true;
     const currentPolicy = Array.isArray(summary.active)
@@ -564,7 +569,7 @@ export function compactRecipeRegistry(summary) {
         ? summary.next_actions
         : [];
     const hint = nextActions.length ? nextActionMetadata(nextActions[0], Limits.RUN_DELIVERY_MODEL_MAX_BYTES) : undefined;
-    const render = () => ({ recipes: "registry", active, drafts, shadowed, invalid, disabled,
+    const render = () => ({ recipes: "registry", active, drafts, retained, shadowed, invalid, disabled,
         current_policy: currentPolicy, skill_catalog_partial: skillCatalogPartial, recommendations, diagnostics,
         ...(hint ? hint.selected : {}) });
     return hint