@llblab/pi-actors 0.34.1 → 0.36.0

package/AGENTS.md

@@ -113,9 +113,11 @@ Pi host
 - `~/.pi/agent/recipes/*.json` is executable muscle memory: recipes there become persistent tools by location.
 - Preserve filename identity, atomic writes, explicit operator-gated changes, and local transportability.
 - Packaged/ad hoc recipes outside the agent root are components, not user tools.
+- Register existing recipes by importing them from the user-root wrapper and using a `{ "name": "alias" }` template node; do not duplicate a ready recipe's script command, defaults, mailbox, or artifact contract in the wrapper.
+- Skill-owned scripts must be exposed through skill-owned recipes first. If a local tool needs that capability, import the skill recipe via `{agent}/skills/<skill>/recipes/<recipe>.json` instead of calling `{agent}/skills/<skill>/scripts/*` directly.
 - Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed.
 - Packaged recipe growth is demand-driven: prefer reusable components over speculative scenario catalogs.
-- Recipe templates may point directly at executable helper scripts; keep script executable bits and avoid unnecessary `node` prefixes.
+- Recipe templates may point directly at executable helper scripts when the recipe owns that script boundary; keep script executable bits and avoid unnecessary `node` prefixes.
 
 ## Command And Recipe Layers
 

package/BACKLOG.md

@@ -51,91 +51,9 @@ No open hotfix items.
 
 ## Minor Backlog
 
-The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
+No open minor items.
 
-### M-18 Draft Recipe Promotion UX
-
-- Priority: High.
-- Status: Planned.
-- Goal: Make successful ad hoc actor patterns easy to promote manually from draft memory into active user recipe memory.
-- Why now: Draft recipes under `~/.pi/agent/recipes/drafts` are replayable but intentionally not active tools, and the two-stage memory model needs an explicit operator-gated promotion path.
-- Direction:
-  - List draft recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
-  - Promote a selected draft to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
-  - Run recipe validation/doctor before writing and expose collision/shadowing diagnostics.
-  - Preserve draft files unless deletion is explicitly requested.
-  - Prefer extending existing registry/tool surfaces over adding a new public noun.
-- Acceptance:
-  - Draft recipes remain non-tools until promotion.
-  - Promotion writes atomically and never auto-promotes.
-  - Tests cover valid promotion, invalid draft, name collision, and packaged-recipe shadowing.
-  - Docs explain draft memory vs active tool memory in one compact section.
-
-### M-19 Recipe Doctor Risk Labels v2
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Evolve recipe doctor into a compact capability-risk membrane without pretending to sandbox trusted local execution.
-- Why now: Recipe doctor already has remediation UX; the next useful slice is deterministic advisory risk classification for local capabilities.
-- Direction:
-  - Add advisory labels such as `risk.shell`, `risk.eval`, `risk.broad_fs_write`, `risk.destructive_fs`, `risk.network`, `risk.external_side_effect`, `risk.long_running`, `risk.platform_specific`, and `risk.secret_touching`.
-  - Keep labels advisory and deterministic; do not block execution unless existing validation already blocks it.
-  - Expose compact risk summaries in `inspect target=recipes view=doctor` and verbose per-recipe labels.
-  - Keep launch-time warnings quiet except for already-failing or clearly dangerous cases.
-  - Preserve honest wording: trusted local execution, not isolation.
-- Acceptance:
-  - Risk labels are deterministic and tested.
-  - Existing risky shell-boundary diagnostics remain intact.
-  - Doctor output stays compact by default.
-  - README/docs do not introduce sandbox or security-boundary claims.
-
-### M-20 Runtime Triage Surface
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Add one compact operator triage view that answers what needs attention right now without performing repairs.
-- Why now: Runtime status, recipe doctor, drafts, stale claims, session mismatches, failed runs, and other-session counts are currently separate bounded surfaces.
-- Direction:
-  - Add `inspect target=tool:pi-actors view=triage` or an equivalent existing inspect surface.
-  - Summarize runtime version/mode, active runs, other-session runs, invalid or blocking recipes, high-risk recipes, draft recipes, stale worker claims, recent failed runs, attention messages, and suggested next inspect actions.
-  - Keep every warning tied to a next inspect/action hint.
-  - Do not auto-repair, auto-prune, relax ownership, or hide detailed source-of-truth views.
-- Acceptance:
-  - Triage output is compact enough for agent context.
-  - Healthy and degraded states are covered by tests.
-  - Detailed inspect/doctor/status views remain source of truth.
-
-### M-21 Packaged Recipe QA Matrix
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Prevent packaged recipes from drifting into inconsistent mailbox, artifact, platform, or package-root behavior.
-- Why now: Packaged recipes are standard-library components; they should be boringly consistent before operators copy or register them as durable local capabilities.
-- Direction:
-  - Add an internal QA check over `recipes/*.json` for descriptions, async mailbox contracts, termination vocabulary, artifact declarations, platform notes, installed-package-safe helper paths, and compiled shim coverage.
-  - Keep `control.kill` as generic runtime termination and allow `control.stop` / `control.cancel` only as actor-domain vocabulary.
-  - Fail with exact recipe/path/key diagnostics.
-  - Avoid a broad recipe-library rewrite beyond violations discovered by the check.
-- Acceptance:
-  - QA runs under an existing validation command or a clearly named subcheck used by `npm run validate`.
-  - Tests/fixtures cover at least one positive and one negative case.
-  - Packaged recipes remain optional components, not policy workflows.
-
-### M-22 Wake and Watcher Chaos Fixtures
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Harden the invariant that durable files are canonical and wake notifications are advisory acceleration.
-- Why now: Wake, watcher, line-counter, and JSONL resilience are central to operator trust as actor counts grow.
-- Direction:
-  - Add deterministic fixtures for watcher restart, line-counter reset, duplicate terminal events, missing wake with present inbox record, wake before file catch-up, corrupt JSONL with later valid records, and killed run with stale progress phase.
-  - Preserve event-driven observability without reintroducing polling-first coordination examples.
-  - Keep tests fast and local.
-- Acceptance:
-  - Duplicate follow-ups do not reappear.
-  - Missing wake does not lose durable messages.
-  - Corrupt records degrade inspect but do not kill it.
-  - Killed/stale progress states remain diagnosable.
+The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
 ## Explicitly Deferred
 
@@ -145,7 +63,7 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 - Run restart/reattach policy: risky for isolation; defer until corruption recovery and protocol fixtures are stronger.
 - Cross-session force kill or attach/adopt/reparent: useful later, but ownership policy should not change until observability makes current boundaries clear.
 - Actor address helper CLI: keep diagnostics improving opportunistically inside existing parser/tests.
-- Golden flow docs and flow conformance runner: useful after M-14, M-15, M-17, and M-18 make the diagnostic and promotion surfaces stable.
+- Golden flow docs and flow conformance runner: useful after the diagnostic and promotion surfaces are stable.
 - Documentation refactor: defer until the canonical mailbox loop and worker recipe exist; avoid rewriting docs twice.
 - Host-level tool unregistration: blocked on host API support.
 - Branch-local checkpoint semantics: wait for real collaborative branch-runner experiments.
@@ -153,8 +71,4 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 
 ## Suggested Milestone Order
 
-```text
-Next milestone: M-18 Draft Recipe Promotion UX.
-Then: M-19 Recipe Doctor Risk Labels v2.
-Small cleanup lane: continue opportunistic domain polish only when a real ownership boundary appears.
-```
+No current milestone. Reassess runtime evidence before adding the next reliability slice.

package/CHANGELOG.md

@@ -2,11 +2,23 @@
 
 ## Unreleased
 
+## 0.36.0: Recipe Diagnostics And Runtime Triage
+
+- `[Recipe Doctor]` Added deterministic advisory risk labels for discovered recipes, including shell, eval, filesystem mutation, network, external side effect, long-running, platform-specific, and secret-touching signals in verbose recipe inspection plus compact doctor risk counts.
+- `[Runtime]` Added `inspect target=tool:pi-actors view=triage` as a compact read-only operator attention surface covering runtime mode, active and other-session runs, invalid or blocking recipes, exposed tool recipes with non-lifecycle risk labels, drafts, stale claims, failed runs, attention messages, and next inspect actions.
+- `[Recipes]` Added packaged recipe QA through `validate-recipe.mjs --qa` and `npm run recipes:qa`, with exact diagnostics for async mailbox contracts, termination vocabulary, artifact paths, platform scope, installed-package-safe helper paths, and missing helper scripts.
+- `[Runtime]` Hardened wake/watch chaos behavior with deterministic coverage for watcher restarts, partial wake records before file catch-up, corrupt wake JSONL with later valid records, missing wake records with durable inbox work, and killed runs with stale progress state.
+- `[Docs]` Documented recipe-doctor risk labels, runtime triage, packaged recipe QA, and import-first ready-recipe registration as operator review aids and source-of-truth preservation, not sandbox, repair, or security-boundary claims.
+
+## 0.35.0: Draft Recipe Promotion UX
+
+- `[Recipes]` Added draft recipe promotion UX: `inspect target=recipes view=summary verbose=true` now exposes draft timestamps, fingerprints, validation state, source run when known, and template previews, while `register_tool name=<tool> draft=<path>` promotes a validated draft into active recipe memory without deleting the draft and rejects collisions unless `update=true` is explicit.
+
 ## 0.34.1: Message Delivery Outcome Hotfix
 
 - `[Dogfood]` Added a deterministic actor-worker stale-claim smoke covering an intentionally claimed branch inbox record; the worker now reports stale claim counts in both `worker-status.json` and its awaiting-assignment room event without adding auto-recovery or scheduler policy.
-- `[Messages]` Completed the M-17 message delivery outcome contract by normalizing public message results with `delivered`, `persisted`, `queued`, `forwarded`, `consumer`, and `reason` fields across run, branch, room, coordinator, session, and tool destinations; room multicast now also exposes per-recipient branch delivery outcomes.
-- `[Backlog]` Closed M-15 Worker Stale-Claim Dogfood and M-17 Message Delivery Outcome Contract after adding delivery-result coverage for run, branch, room, coordinator, session, tool, and ownership-denied paths.
+- `[Messages]` Normalized public message results with `delivered`, `persisted`, `queued`, `forwarded`, `consumer`, and `reason` fields across run, branch, room, coordinator, session, and tool destinations; room multicast now also exposes per-recipient branch delivery outcomes.
+- `[Backlog]` Closed the worker stale-claim dogfood and message delivery outcome work after adding delivery-result coverage for run, branch, room, coordinator, session, tool, and ownership-denied paths.
 
 ## 0.34.0: Actor Kernel Domain Compression
 

package/README.md

@@ -132,6 +132,7 @@ docs_review scope="README.md" model="current-review-model" run_id=docs_review
 Inspect only when there is a reason:
 
 ```text
+inspect target=tool:pi-actors view=triage
 inspect target=run:docs_review view=status
 inspect target=run:docs_review view=tail lines=80
 inspect target=run:docs_review view=messages
@@ -207,7 +208,8 @@ Rules:
 - User recipes override same-name lower-priority recipes;
 - Same-id JSON recipes shadow Markdown recipes in the same priority layer;
 - Packaged recipes are standard-library components, not automatically installed operator policy;
-- `register_tool` creates, updates, lists, or deletes user recipe files through the normal agent interface.
+- Draft recipes in `~/.pi/agent/recipes/drafts/` are replayable memory, not active tools;
+- `register_tool` creates, updates, lists, deletes, or explicitly promotes draft recipe files through the normal agent interface.
 
 Example foreground tool:
 
@@ -226,6 +228,14 @@ register_tool name=docs_review \
   args="scope:path,model:string"
 ```
 
+Promote a successful captured draft only after an explicit operator decision:
+
+```text
+register_tool name=docs_review draft=~/.pi/agent/recipes/drafts/spawned-run.json
+```
+
+Promotion validates the draft, writes `~/.pi/agent/recipes/<name>.json`, preserves the draft, and rejects collisions unless `update=true` is supplied.
+
 Inspect the discovered registry:
 
 ```text
@@ -298,7 +308,7 @@ Packaged recipes should prefer mailbox/wake behavior for portable control. Recip
 
 Commands execute directly without shell evaluation where possible, but trusted executables still run with the same system permissions as Pi. Only register commands, scripts, recipes, and paths you trust.
 
-High-risk templates such as shells, interpreter eval modes, and broad filesystem mutation may surface warnings, but the runtime is not a security boundary.
+High-risk templates such as shells, interpreter eval modes, and broad filesystem mutation may surface warnings, but the runtime is not a security boundary. Recipe doctor also exposes advisory labels like `risk.shell`, `risk.eval`, `risk.destructive_fs`, `risk.network`, and `risk.external_side_effect` for operator review.
 
 Prefer:
 

package/dist/lib/command-templates.d.ts

@@ -50,6 +50,7 @@ export interface CommandTemplateExecResult {
     code: number;
     killed: boolean;
 }
+export type CommandTemplateRiskLabel = "risk.shell" | "risk.eval" | "risk.broad_fs_write" | "risk.destructive_fs" | "risk.network" | "risk.external_side_effect" | "risk.long_running" | "risk.platform_specific" | "risk.secret_touching";
 export type CommandTemplateExecCommand = (command: string, args: string[], options?: CommandTemplateExecOptions) => Promise<CommandTemplateExecResult>;
 export declare function normalizeCommandTemplateConfig(config: CommandTemplateConfig): CommandTemplateObjectConfig;
 export declare function resolveInheritedDefaultReferences(ownDefaults: Record<string, unknown> | undefined, inheritedDefaults: Record<string, unknown> | undefined, runtimeValues?: Record<string, unknown>): Record<string, unknown> | undefined;
@@ -58,6 +59,7 @@ export declare function isCommandTemplateRepeatPlaceholder(name: string): boolea
 export declare function getCommandTemplateRepeatDefaults(index: number, repeat: number): Record<string, string>;
 export declare function expandCommandTemplateConfigs(config: CommandTemplateConfig, inherited?: Pick<CommandTemplateObjectConfig, "args" | "defaults">): CommandTemplateLeafConfig[];
 export declare function getCommandTemplateWarnings(config: CommandTemplateConfig): string[];
+export declare function getCommandTemplateRiskLabels(config: CommandTemplateConfig): CommandTemplateRiskLabel[];
 export declare function getCommandTemplateDefaults(config: CommandTemplateConfig | undefined): Record<string, string>;
 export declare function splitCommandTemplate(input: string): string[];
 export declare function expandCommandTemplateExecutable(command: string, cwd: string): string;

package/dist/lib/command-templates.js

@@ -6,6 +6,17 @@
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
+const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
+    "risk.shell",
+    "risk.eval",
+    "risk.destructive_fs",
+    "risk.broad_fs_write",
+    "risk.external_side_effect",
+    "risk.secret_touching",
+    "risk.network",
+    "risk.long_running",
+    "risk.platform_specific",
+];
 function normalizeCommandTemplateArgs(value) {
     if (!Array.isArray(value))
         return [];
@@ -93,6 +104,68 @@ function hasRiskyPathArg(args) {
         arg.startsWith("~/") ||
         arg.startsWith("/"));
 }
+function sortRiskLabels(labels) {
+    const unique = new Set(labels);
+    return COMMAND_TEMPLATE_RISK_LABEL_ORDER.filter((label) => unique.has(label));
+}
+function hasAnyArg(args, values) {
+    return args.some((arg) => values.includes(arg.toLowerCase()));
+}
+function hasSecretTouchingText(parts) {
+    return parts.some((part) => /(^|[{}._\-\s/])(?:secret|token|password|passwd|credential|api[_-]?key|private[_-]?key|\.env|ssh[_-]?key)(?:[{}._\-\s/]|$)/i.test(part));
+}
+function getLeafCommandTemplateRiskLabels(config) {
+    const parts = splitCommandTemplate(config.template);
+    const command = getExecutableName(parts[0]);
+    const args = parts.slice(1);
+    const labels = new Set();
+    if (["bash", "sh", "zsh", "fish"].includes(command)) {
+        labels.add("risk.shell");
+        if (hasAnyFlag(args, ["-c"]))
+            labels.add("risk.eval");
+    }
+    if (["node", "deno", "bun"].includes(command) &&
+        hasAnyFlag(args, ["-e", "--eval"])) {
+        labels.add("risk.eval");
+    }
+    if (["python", "python3", "perl", "ruby"].includes(command) &&
+        hasAnyFlag(args, ["-c", "-e"])) {
+        labels.add("risk.eval");
+    }
+    if (command === "rm" &&
+        (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
+            hasRiskyPathArg(args))) {
+        labels.add("risk.destructive_fs");
+    }
+    if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
+        labels.add("risk.broad_fs_write");
+    }
+    if (["curl", "wget", "ssh", "scp", "sftp", "rsync", "nc", "ncat", "telnet", "ftp"].includes(command) ||
+        (command === "git" &&
+            hasAnyArg(args, ["clone", "fetch", "pull", "push", "ls-remote"])) ||
+        ["npm", "pnpm", "yarn", "pip", "cargo"].includes(command)) {
+        labels.add("risk.network");
+    }
+    if (["gh", "glab", "hub", "kubectl", "terraform"].includes(command) ||
+        (command === "git" && hasAnyArg(args, ["push"])) ||
+        (["npm", "pnpm", "yarn"].includes(command) &&
+            hasAnyArg(args, ["publish", "login", "logout", "deprecate"]))) {
+        labels.add("risk.external_side_effect");
+    }
+    if (command === "sleep" ||
+        command === "watch" ||
+        (command === "tail" && hasAnyFlag(args, ["-f"])) ||
+        hasAnyArg(args, ["--watch", "--serve", "serve"])) {
+        labels.add("risk.long_running");
+    }
+    if (["systemctl", "launchctl", "osascript", "open", "xdg-open", "powershell", "pwsh", "cmd.exe", "apt", "apt-get", "dnf", "yum", "brew", "pacman", "apk", "xclip", "wl-copy"].includes(command)) {
+        labels.add("risk.platform_specific");
+    }
+    if (["pass", "gpg", "ssh-add"].includes(command) || hasSecretTouchingText(parts)) {
+        labels.add("risk.secret_touching");
+    }
+    return sortRiskLabels(labels);
+}
 function getLeafCommandTemplateWarnings(config) {
     const parts = splitCommandTemplate(config.template);
     const command = getExecutableName(parts[0]);
@@ -206,6 +279,9 @@ export function getCommandTemplateWarnings(config) {
         ...new Set(expandCommandTemplateConfigs(config).flatMap((leaf) => getLeafCommandTemplateWarnings(leaf))),
     ];
 }
+export function getCommandTemplateRiskLabels(config) {
+    return sortRiskLabels(expandCommandTemplateConfigs(config).flatMap((leaf) => getLeafCommandTemplateRiskLabels(leaf)));
+}
 function parseCommandTemplateArgToken(value) {
     const separatorIndex = value.indexOf("=");
     const rawName = separatorIndex === -1 ? value : value.slice(0, separatorIndex);

package/dist/lib/prompts.d.ts

@@ -10,6 +10,7 @@ export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";
+    readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
     readonly state_dir: "Optional async run state directory for a co-located template recipe.";
     readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";

package/dist/lib/prompts.js

@@ -30,6 +30,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
+    draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
     state_dir: "Optional async run state directory for a co-located template recipe.",
     template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",

package/dist/lib/recipes-discovery.d.ts

@@ -3,6 +3,7 @@
  * Zones: recipe discovery, tool exposure, registry diagnostics
  * Owns filename identity discovery across prioritized recipe roots
  */
+import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import type { TemplateRecipeConfig } from "./recipes-references.ts";
 export interface DiscoveredRecipe {
@@ -18,6 +19,7 @@ export interface DiscoveredRecipe {
     tool: boolean;
     mutableUsage: boolean;
     diagnostics: string[];
+    riskLabels: CommandTemplates.CommandTemplateRiskLabel[];
     shadows: string[];
 }
 export interface RecipeIntegrityManifestEntry {

package/dist/lib/recipes-discovery.js

@@ -45,15 +45,35 @@ function listRecipeFiles(root) {
         .localeCompare(b.replace(/\.md$/, ".json")) ||
         (a.endsWith(".json") ? -1 : 1));
 }
+function getRecipeCommandTemplateConfig(config) {
+    return (typeof config.template === "object" && config.template !== null
+        ? config.template
+        : config);
+}
 function getRecipeConfigDiagnostics(file, config) {
     if (!config) {
         const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
         return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
     }
-    const commandTemplateConfig = typeof config.template === "object" && config.template !== null
-        ? config.template
-        : config;
-    return CommandTemplates.getCommandTemplateWarnings(commandTemplateConfig).map((warning) => `Recipe ${file}: ${warning}`);
+    return CommandTemplates.getCommandTemplateWarnings(getRecipeCommandTemplateConfig(config)).map((warning) => `Recipe ${file}: ${warning}`);
+}
+function getRecipeRiskLabels(config) {
+    if (!config)
+        return [];
+    const labels = new Set(CommandTemplates.getCommandTemplateRiskLabels(getRecipeCommandTemplateConfig(config)));
+    if (config.async === true)
+        labels.add("risk.long_running");
+    return [
+        "risk.shell",
+        "risk.eval",
+        "risk.destructive_fs",
+        "risk.broad_fs_write",
+        "risk.external_side_effect",
+        "risk.secret_touching",
+        "risk.network",
+        "risk.long_running",
+        "risk.platform_specific",
+    ].filter((label) => labels.has(label));
 }
 function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false) {
     const id = RecipesReferences.getRecipeIdFromPath(file);
@@ -74,6 +94,7 @@ function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutable
             tool: defaultTool && !disabled && !invalid,
             mutableUsage,
             diagnostics: getRecipeConfigDiagnostics(file, config),
+            riskLabels: getRecipeRiskLabels(config),
             shadows: [],
         };
     }
@@ -92,6 +113,7 @@ function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutable
             diagnostics: [
                 `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
             ],
+            riskLabels: [],
             shadows: [],
         };
     }
@@ -266,7 +288,7 @@ function diagnosticSeverity(message) {
     if (/invalid|failed to load|not found|cyclic|exceeds|must define|repeat must/i.test(message)) {
         return "error";
     }
-    if (/world-writable|group-writable|invokes bash|eval|destructive|unsafe/i.test(message)) {
+    if (/world-writable|group-writable|invokes bash|eval|destructive|broad filesystem|unsafe/i.test(message)) {
         return "warning";
     }
     return "info";
@@ -304,6 +326,7 @@ function diagnosticDetails(result) {
         seen.add(key);
         details.push({
             ...(entry ? { id: entry.id, path: entry.path } : {}),
+            ...(entry?.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
             action: diagnosticSuggestedAction(message),
             message,
             severity: diagnosticSeverity(message),
@@ -357,6 +380,7 @@ function remediationForEntry(entry, activePath) {
             kind: "risky_shell_boundary",
             severity: "warning",
             path: entry.path,
+            ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
             reason: riskyDiagnostics[0],
             action: "audit trusted command boundary; keep only if the recipe is local and intentional",
         };
@@ -400,6 +424,25 @@ function discoveryRemediations(result) {
         String(a.id).localeCompare(String(b.id)) ||
         String(a.path).localeCompare(String(b.path)));
 }
+function summarizeRiskLabels(entries) {
+    const counts = new Map();
+    for (const entry of entries) {
+        for (const label of entry.riskLabels) {
+            const current = counts.get(label) ?? { count: 0, ids: new Set() };
+            current.count += 1;
+            current.ids.add(entry.id);
+            counts.set(label, current);
+        }
+    }
+    return [...counts.entries()]
+        .map(([label, value]) => ({
+        label,
+        count: value.count,
+        recipes: [...value.ids].sort(),
+    }))
+        .sort((a, b) => Number(b.count) - Number(a.count) ||
+        String(a.label).localeCompare(String(b.label)));
+}
 function recommendationForEntry(entry, activePath) {
     const recommendation = cleanupRecommendation(entry);
     if (!recommendation)
@@ -425,14 +468,41 @@ export function getShadowedLaunchDiagnostic(result, id) {
         reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
     };
 }
+function templatePreview(value) {
+    const rendered = typeof value === "string"
+        ? value
+        : value === undefined
+            ? undefined
+            : JSON.stringify(value);
+    return rendered && rendered.length > 120
+        ? `${rendered.slice(0, 117)}...`
+        : rendered;
+}
 export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
         const id = RecipesReferences.getRecipeIdFromPath(path);
+        const bytes = readFileSync(path);
+        const stat = statSync(path);
         const config = RecipesReferences.readRawRecipeConfig(path);
+        const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+        const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+        const sourceRun = String(config?.description ?? "").match(/spawn run ([^\s]+)/)?.[1];
+        const preview = templatePreview(config?.template);
+        const riskLabels = getRecipeRiskLabels(resolved);
         return {
             id,
             path,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            size: bytes.byteLength,
+            created_at: stat.birthtime.toISOString(),
+            modified_at: stat.mtime.toISOString(),
+            valid: Boolean(resolved),
+            diagnostics,
+            ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
             ...(config?.description ? { description: config.description } : {}),
+            ...(sourceRun ? { source_run: sourceRun } : {}),
+            ...(config?.async !== undefined ? { async: config.async } : {}),
+            ...(preview ? { template_preview: preview } : {}),
         };
     });
 }
@@ -453,6 +523,7 @@ export function summarizeDiscovery(result) {
             disabled: entry.disabled,
             invalid: entry.invalid,
             shadows: entry.shadows,
+            ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
             ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
             ...(recipeUsage(entry.config)
                 ? { usage: recipeUsage(entry.config) }
@@ -479,6 +550,7 @@ export function summarizeDiscovery(result) {
             .filter((entry) => entry.disabled)
             .map((entry) => ({ id: entry.id, path: entry.path }))
             .sort((a, b) => a.id.localeCompare(b.id)),
+        risk_summary: summarizeRiskLabels(result.entries),
         recommendations,
         remediations,
         top_action: remediations[0],

package/dist/lib/registry.d.ts

@@ -11,6 +11,7 @@ export interface RegisterToolInput {
     async?: boolean;
     state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue | null;
+    draft?: string;
     args?: string;
     update?: boolean;
     values?: Record<string, unknown>;
@@ -20,6 +21,8 @@ export interface RegisterToolResultDetails {
     async?: boolean;
     config?: string;
     defaults?: Record<string, string>;
+    draft?: string;
+    promoted?: boolean;
     recipeName?: string;
     state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue;

package/dist/lib/registry.js

@@ -4,7 +4,7 @@
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as ExecutionOutput from "./execution-output.js";
 import { writeJsonAtomic } from "./file-state.js";
@@ -32,6 +32,62 @@ function getRecipeRoot(deps) {
 function getToolRecipePath(deps, name) {
     return join(getRecipeRoot(deps), `${name}.json`);
 }
+function assertDraftPath(deps, draft) {
+    const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+    const path = resolve(draft);
+    const relation = relative(draftRoot, path);
+    if (relation === "" ||
+        relation.startsWith("..") ||
+        resolve(relation) === relation) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`));
+    }
+    if (!existsSync(path)) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+    }
+    return path;
+}
+function promoteDraftRecipe(name, input, ctx, deps) {
+    const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+    const targetPath = getToolRecipePath(deps, name);
+    const tools = deps.getTools();
+    const existing = tools.get(name);
+    const conflict = deps.getExternalToolConflict(name);
+    if (conflict)
+        throw new Error(ExecutionOutput.formatToolText(conflict));
+    if ((existing || existsSync(targetPath)) && !input.update) {
+        throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+    }
+    const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
+    if (!config) {
+        const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+        throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid${reason ? `: ${reason}` : "."}`));
+    }
+    const promoted = buildConfig(name, {
+        ...input,
+        description: input.description ?? config.description,
+        template: draftPath,
+    }, existing);
+    const raw = RecipesReferences.readRawRecipeConfig(draftPath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeJsonAtomic(targetPath, raw);
+    promoted.template = targetPath;
+    promoted.sourcePath = targetPath;
+    tools.set(name, promoted);
+    deps.registerRuntimeTool(promoted);
+    deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`)),
+        ],
+        details: {
+            args: promoted.args,
+            config: targetPath,
+            draft: draftPath,
+            promoted: true,
+            tool: name,
+        },
+    };
+}
 function persistToolRecipe(deps, cfg) {
     const path = getToolRecipePath(deps, cfg.name);
     mkdirSync(dirname(path), { recursive: true });
@@ -173,6 +229,9 @@ export async function executeRegisterTool(params, ctx, deps) {
     if (deps.reservedToolNames.has(name)) {
         throw new Error(ExecutionOutput.formatToolText(`Reserved tool name: ${name}`));
     }
+    if (typeof input.draft === "string" && input.draft.trim()) {
+        return promoteDraftRecipe(name, input, ctx, deps);
+    }
     const templateProvided = Object.hasOwn(input, "template");
     const template = getInputTemplate(input.template);
     if (templateProvided && (template === null || template === ""))

package/dist/lib/runtime-notifier.js

@@ -74,6 +74,7 @@ export function createFileRuntimeNotifier(stateDir, options = {}) {
         subscribe: (actor, onWake, subscribeOptions = {}) => {
             mkdirSync(dirname(file), { recursive: true });
             let position = options.replay || !existsSync(file) ? 0 : statSync(file).size;
+            let pending = "";
             let closed = false;
             const reconcile = (reason) => {
                 if (closed)
@@ -89,11 +90,15 @@ export function createFileRuntimeNotifier(stateDir, options = {}) {
                 if (closed || !existsSync(file))
                     return;
                 const buffer = readFileSync(file);
-                if (position > buffer.length)
+                if (position > buffer.length) {
                     position = 0;
-                const chunk = buffer.subarray(position).toString("utf8");
+                    pending = "";
+                }
+                const chunk = pending + buffer.subarray(position).toString("utf8");
                 position = buffer.length;
-                for (const line of chunk.split("\n")) {
+                const lines = chunk.split("\n");
+                pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
+                for (const line of lines) {
                     if (!line.trim())
                         continue;
                     const event = parseRuntimeWakeEventLine(line);