@llblab/pi-actors 0.35.0 → 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,73 +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-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
 
@@ -127,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.
@@ -135,8 +71,4 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 
 ## Suggested Milestone Order
 
-```text
-Next milestone: M-19 Recipe Doctor Risk Labels v2.
-Then: M-20 Runtime Recipe Triage.
-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,15 +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]` Completed M-18 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.
+- `[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
@@ -307,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/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)
@@ -445,6 +488,7 @@ export function listDraftRecipes(root) {
         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,
@@ -454,6 +498,7 @@ export function listDraftRecipes(root) {
             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 } : {}),
@@ -478,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) }
@@ -504,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/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);

package/dist/lib/tools-inspect.js

@@ -212,6 +212,170 @@ function getPiActorsRuntimeStatus() {
 function compactPiActorsRuntimeStatus(status) {
     return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
 }
+function isStaleClaim(message, now) {
+    if (message.status !== "claimed")
+        return false;
+    const claimedAt = Date.parse(String(message.claimed_at ?? ""));
+    return Number.isFinite(claimedAt) && now - claimedAt > 5 * 60 * 1000;
+}
+function getRunTriageSignals(runs) {
+    const now = Date.now();
+    const staleClaims = [];
+    const attentionMessages = [];
+    for (const run of runs) {
+        const stateDir = String(run.state_dir ?? "");
+        const runId = String(run.run ?? "");
+        if (!stateDir)
+            continue;
+        try {
+            for (const message of AsyncRuns.readRunInboxMessages(stateDir, 200)) {
+                if (!isStaleClaim(message, now))
+                    continue;
+                staleClaims.push({
+                    run: runId,
+                    id: message.id,
+                    claimed_at: message.claimed_at,
+                    claimed_by: message.claimed_by,
+                    type: message.type,
+                });
+            }
+        }
+        catch { }
+        try {
+            for (const event of AsyncRuns.readRunEvents(stateDir, 80)) {
+                if (event.metadata?.requires_response !== true)
+                    continue;
+                attentionMessages.push({
+                    run: runId,
+                    id: event.id,
+                    summary: event.summary,
+                    type: event.type ?? event.event,
+                });
+            }
+        }
+        catch { }
+    }
+    return { attention_messages: attentionMessages, stale_claims: staleClaims };
+}
+function isTriageHighRiskRecipe(recipe) {
+    if (recipe.tool !== true)
+        return false;
+    const labels = Array.isArray(recipe.risk_labels)
+        ? recipe.risk_labels.map((label) => String(label))
+        : [];
+    return labels.some((label) => label !== "risk.long_running");
+}
+function getPiActorsTriage(ctx, deps) {
+    const runtime = getPiActorsRuntimeStatus();
+    const currentSession = ToolsAccess.getContextSessionId(ctx);
+    const allRuns = AsyncRuns.listRuns().map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+    const visibleRuns = currentSession
+        ? allRuns.filter((run) => !run.ownerId || run.ownerId === currentSession)
+        : allRuns;
+    const activeRuns = visibleRuns.filter((run) => run.status === "running");
+    const failedRuns = visibleRuns.filter((run) => run.status === "failed");
+    const otherRuns = currentSession
+        ? allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession)
+        : [];
+    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    const discovered = RecipesDiscovery.discoverRecipeSources([
+        { root: recipeRoot, defaultTool: true, mutableUsage: true },
+        { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
+    ]);
+    const recipeSummary = {
+        ...RecipesDiscovery.summarizeDiscovery(discovered),
+        drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+    };
+    const activeRecipes = Array.isArray(recipeSummary.active)
+        ? recipeSummary.active
+        : [];
+    const highRiskRecipes = activeRecipes.filter(isTriageHighRiskRecipe);
+    const signals = getRunTriageSignals(visibleRuns);
+    const attentionMessages = signals.attention_messages;
+    const staleClaims = signals.stale_claims;
+    const invalidRecipes = Array.isArray(recipeSummary.invalid)
+        ? recipeSummary.invalid
+        : [];
+    const remediations = Array.isArray(recipeSummary.remediations)
+        ? recipeSummary.remediations
+        : [];
+    const drafts = Array.isArray(recipeSummary.drafts)
+        ? recipeSummary.drafts
+        : [];
+    const nextActions = [
+        invalidRecipes.length || remediations.length
+            ? "inspect target=recipes view=doctor"
+            : "",
+        drafts.length ? "inspect target=recipes view=summary verbose=true" : "",
+        failedRuns[0]?.run
+            ? `inspect target=run:${String(failedRuns[0].run)} view=tail lines=80`
+            : "",
+        attentionMessages[0]?.run
+            ? `inspect target=run:${String(attentionMessages[0].run)} view=messages`
+            : "",
+        activeRuns.length
+            ? "inspect target=session:all view=runs status=active"
+            : "",
+    ].filter(Boolean);
+    return {
+        runtime,
+        current_session: currentSession ?? null,
+        active_runs: activeRuns.map((run) => ({
+            run: run.run,
+            ownerId: run.ownerId,
+            recipe: run.recipe,
+            status: run.status,
+        })),
+        other_session_runs: otherRuns.length,
+        invalid_recipes: invalidRecipes,
+        blocking_recipes: remediations.filter((item) => String(item.kind ?? "").startsWith("blocking_")),
+        high_risk_recipes: highRiskRecipes.map((recipe) => ({
+            id: recipe.id,
+            path: recipe.path,
+            risk_labels: recipe.risk_labels,
+        })),
+        draft_recipes: drafts,
+        stale_claims: staleClaims,
+        recent_failed_runs: failedRuns.slice(0, 5).map((run) => ({
+            run: run.run,
+            recipe: run.recipe,
+            status: run.status,
+        })),
+        attention_messages: attentionMessages.slice(-10),
+        next_actions: [...new Set(nextActions)].slice(0, 5),
+    };
+}
+function compactPiActorsTriage(summary) {
+    const runtime = asRecord(summary.runtime);
+    const activeRuns = Array.isArray(summary.active_runs)
+        ? summary.active_runs.length
+        : 0;
+    const invalidRecipes = Array.isArray(summary.invalid_recipes)
+        ? summary.invalid_recipes.length
+        : 0;
+    const blockingRecipes = Array.isArray(summary.blocking_recipes)
+        ? summary.blocking_recipes.length
+        : 0;
+    const highRiskRecipes = Array.isArray(summary.high_risk_recipes)
+        ? summary.high_risk_recipes.length
+        : 0;
+    const drafts = Array.isArray(summary.draft_recipes)
+        ? summary.draft_recipes.length
+        : 0;
+    const staleClaims = Array.isArray(summary.stale_claims)
+        ? summary.stale_claims.length
+        : 0;
+    const failedRuns = Array.isArray(summary.recent_failed_runs)
+        ? summary.recent_failed_runs.length
+        : 0;
+    const attention = Array.isArray(summary.attention_messages)
+        ? summary.attention_messages.length
+        : 0;
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    return `\ntriage version=${String(runtime.version ?? "unknown")} mode=${String(runtime.mode ?? "unknown")} active_runs=${activeRuns} other_runs=${String(summary.other_session_runs ?? 0)} invalid_recipes=${invalidRecipes} blocking_recipes=${blockingRecipes} high_risk_recipes=${highRiskRecipes} drafts=${drafts} stale_claims=${staleClaims} failed_runs=${failedRuns} attention=${attention}${ToolsResponse.compactNextActions(nextActions)}`;
+}
 function compactToolActor(name, tool) {
     const parameters = asRecord(tool.parameters);
     const required = Array.isArray(parameters.required)
@@ -314,15 +478,19 @@ export function createInspectToolDefinition(deps = {}) {
             }
             if (address.kind === "tool" && address.value) {
                 if (address.value === "pi-actors") {
-                    if (view !== "status") {
-                        throw new Error("inspect tool:pi-actors supports view=status.");
+                    if (view !== "status" && view !== "triage") {
+                        throw new Error("inspect tool:pi-actors supports view=status or view=triage.");
                     }
-                    const details = getPiActorsRuntimeStatus();
+                    const details = view === "triage"
+                        ? getPiActorsTriage(ctx, deps)
+                        : getPiActorsRuntimeStatus();
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: maybeJsonText(details, input.verbose === true, compactPiActorsRuntimeStatus(details)),
+                                text: maybeJsonText(details, input.verbose === true, view === "triage"
+                                    ? compactPiActorsTriage(details)
+                                    : compactPiActorsRuntimeStatus(details)),
                             },
                         ],
                         details,