@llblab/pi-actors 0.20.2 → 0.21.0

package/BACKLOG.md

@@ -2,79 +2,6 @@
 
 ## Open Work
 
-### Branch Inbox Retention and Transition Scaling
-
-- Priority: Medium.
-- Goal: Keep direct branch message queues reliable for long-lived interactive branch runners without unbounded rewrite amplification.
-- Direction:
-  - Evaluate current whole-file branch inbox status rewrites under realistic long-lived direct-message workloads.
-  - Consider bounded retention, compaction, or append-only transition logs for `queued` / `claimed` / `handled` / `failed` state changes while preserving stable message IDs and exact-once claim semantics.
-  - Keep branch-local inbox append/status mutations lock-guarded and preserve inspector visibility for unread/current-branch filters.
-- Exit:
-  - A documented decision or implementation explains how branch inboxes scale for persistent runners and proves existing direct-message semantics remain compatible.
-
-### Installed Recipe Trust Boundary Hardening
-
-- Priority: Medium.
-- Goal: Keep recipe-library growth local-first without letting operator muscle memory become an accidental sandbox bypass.
-- Direction:
-  - Review packaged recipes, examples, and docs for destructive or external side effects and ensure they require explicit paths, typed args, narrow helper scripts, and clear operator gates.
-  - Keep warnings framed as diagnostics, not a security boundary.
-  - Prefer small audited helper scripts over broad shell templates when recipes touch files, processes, networks, or external services.
-- Exit:
-  - A trust-boundary review confirms packaged recipes and docs preserve the current local-first/not-sandbox-first contract, with any needed hardening captured in tests or docs.
-
-### Direct Branch Message Consumption Semantics
-
-- Priority: Medium.
-- Goal: Make it impossible to misunderstand branch inbox delivery as universal active delivery without a consuming coordinator or runner protocol.
-- Direction:
-  - Audit README, actor-message docs, async-run docs, actors skill, and recipe guidance for branch inbox wording.
-  - Clarify that direct branch messages are queued and become active work only when the relevant coordinator/runner claims, injects, handles, or fails them.
-  - Add or update a bounded smoke scenario that demonstrates queued direct messages, claim/handle transitions, and inspector visibility.
-- Exit:
-  - Public docs and tests show both halves of direct branch delivery: durable branch-local queueing and explicit worker consumption semantics.
-
-### Actor Rooms, Roster, and Cross-Branch Messaging
-
-- Priority: High.
-- Goal: Continue evolving actor communication without adding a second public messaging model.
-- Direction:
-  - Evaluate whether room storage/routing should remain built into the tool adapter or move behind a dedicated non-LLM communication actor recipe/script, possibly singleton-scoped. Preserve the same public `room:<run>` address and envelope either way.
-  - Treat the next backend decision as an evidence-backed experiment, not a rewrite: stress a real room/direct-message workload, compare the current file-backed adapter with a thin communication actor/helper, and record the decision.
-  - Consider reducing direct file-backed state where it improves coherence: model room/roster state as actor-owned data structures served by helper scripts/actors, with files retained only for durable snapshots, recovery, artifacts, or audit logs.
-  - Further storage changes should preserve the current burst/read/concurrency safeguards: branch communication snapshot writes are debounced, root snapshots stay current, roster files are not rewritten during bursts when only `last_seen` changes, room status inspection does not parse full timelines, branch-local inbox append/status rewrites are lock-guarded, and legacy no-ID branch inbox records can be claimed exactly once.
-  - Prevent monolith drift: `actor-rooms.ts` may remain a thin adapter, but growing routing policy, subscription loops, fanout policy, or long-lived state ownership should move behind a focused communication helper/actor rather than accumulating in the tool adapter.
-- Exit:
-  - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
-  - A short decision note or changelog entry explains why the room backend stayed file-backed or moved behind a communication actor/helper.
-
-### Graceful Actor Retirement
-
-- Priority: Medium.
-- Goal: Automatically retire coordinator/helper actors that were launched only to supervise a bounded worker tree once their dependent workers have finished.
-- Direction:
-  - Build on the existing `retire_when: "children_terminal"` recipe/run metadata contract and observability retirement-candidate detection for ephemeral supervisors.
-  - Treat auto-retirement as opt-in only; never infer it for arbitrary long-lived services, user tools, or persistent backlog implementers.
-  - Extend candidate detection beyond current active command/proc-descendant gating to full observed child async-run state rather than log text: the supervisor may retire only when all launched child async runs are terminal and required artifacts/outbox events have been flushed.
-  - Prefer graceful stop (`control.stop` / actor message) before process termination; escalate only after a bounded timeout and record the retirement event in run state.
-  - Preserve manual `cancel` / `kill` semantics and make retirement visible through `inspect` / ambient observability.
-- Exit:
-  - A packaged coordinator recipe can launch worker actors, complete its coordination duties, and shut itself down automatically after the worker tree reaches terminal state.
-  - Persistent services and implementer actors remain alive unless their recipe explicitly opts into retirement.
-
-### Coordinator Strategy Boundary
-
-- Priority: Medium.
-- Goal: Keep the generic coordinator from becoming a second overloaded monolith as room/direct-message workflows mature.
-- Direction:
-  - Split only at real pressure points: branch inbox claim/finalize helpers, participant execution, room transcript synthesis, and mode strategies are likely seams, but avoid cosmetic module churn.
-  - Preserve the current principle that the locker stays generic/thin and all orchestration policy stays in coordinator strategy code or recipe composition.
-  - Prefer reusable helper modules or small scripts only when at least two packaged workflows need the same behavior.
-- Exit:
-  - Adding a new coordinator mode or packaged multi-agent workflow does not require editing unrelated mode logic.
-  - Existing room-swarm, locker, and direct-branch-message tests still cover the extracted seams.
-
 ### Consensus-First Build Recipe
 
 - Priority: Medium.
@@ -90,18 +17,6 @@
   - A packaged recipe can reproduce the interactive-music-instrument workflow shape for another single-artifact task without copying the demo script.
   - Docs and skills point agents to the packaged recipe and explain when to choose it over a free-form room swarm.
 
-### Actor OS Scenario Smoke Matrix
-
-- Priority: Medium.
-- Goal: Convert the 0.19.x actor-communication hardening into repeatable end-to-end scenario checks instead of relying on ad hoc demos.
-- Direction:
-  - Cover one scenario each for shared room coordination, direct branch work delivery, branch inbox claim/handle/fail transitions, inspector navigation, recipe context injection, recipe persistence suggestion, and opt-in retirement candidate detection.
-  - Keep scenarios local-first and bounded: fake `pi`/models where possible, no external services, no long sleeps, no broad golden transcripts.
-  - Prefer packaged recipes and public `spawn` / `message` / `inspect` calls so the smoke matrix exercises the same surface agents use.
-- Exit:
-  - A single validation command or documented test group verifies the actor OS behaviors that made 0.19.x production-useful.
-  - The smoke matrix catches regressions in actor communication, recipe memory, and observability without requiring a manual swarm demo.
-
 ### Persistent Backlog Implementer Workflow
 
 - Priority: Medium.

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+## 0.21.0: Native Windows Actor Control and Literate Recipes
+
+- `[Async Runs]` Added a platform-adapted run-control path: Unix FIFO behavior remains backward-compatible, native Windows can target named-pipe run-control endpoints recorded in run state, and run message receipts still update events and inbox state through the same actor-message path.
+- `[Async Runs]` Added Windows process-tree termination planning for cancel/kill through `taskkill`, while preserving Unix process-group signaling semantics.
+- `[Scripts]` Migrated `locker.mjs` and coordinator locker calls to platform-adapted control metadata: Unix still uses `control.fifo`, while native Windows can use a deterministic named-pipe endpoint with the same message protocol.
+- `[Branch Messages]` Added bounded branch-inbox terminal retention during status transitions, preserving active queued/claimed work while compacting older handled/failed records for long-lived branch runners.
+- `[Recipe Discovery]` Tightened trust-boundary diagnostics so combined short shell/eval flags such as `bash -lc` and nested recipe command-template objects are surfaced, including the packaged validation wrapper's trusted shell boundary.
+- `[Rooms]` Recorded the backend decision to keep the current file-backed room adapter until real workflows need live subscriptions/fanout or shared mutable state, backed by a mixed room/direct-branch workload regression.
+- `[Recipes]` Added Markdown-authored recipe loading for `.md` files with frontmatter metadata and fenced executable recipe/template blocks, with same-id JSON shadowing Markdown in the same priority layer.
+- `[Retirement]` Extended run summaries to discover nested child async-run state dirs, blocks opt-in retirement while nested children are still running, surfaces child/terminal child counts on candidates, and has the session watcher retire ready candidates with one graceful stop attempt plus owned cancellation fallback. Added an integration smoke where an idle supervisor stops after its nested child is terminal while a non-opt-in service remains running.
+- `[Coordinator]` Consolidated direct branch inbox claim/finalize rewrites behind one locked mutation helper and moved room-swarm mode dispatch behind an explicit mode registry. Unknown coordinator modes now fail closed, and `pipeline-room-swarm` exposes the supported mode enum.
+- `[Docs]` Documented the local Actor OS smoke matrix covered by `npm test`, spanning room coordination, direct branch delivery, inbox claim/handle transitions, inspector navigation, recipe context injection, persistence suggestions, and opt-in retirement smoke.
+- `[Docs/Tests]` Documented native Windows support scope and added regression coverage for Windows endpoint metadata, mocked named-pipe sends, Windows process-control planning, unchanged Unix FIFO behavior, locker control metadata, branch inbox compaction, mixed room/direct workloads, Markdown recipe loading/discovery/validation, nested child-run retirement gating, and packaged recipe trust diagnostics.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.21.0` for the minor release.
+
 ## 0.20.2: Installed Extension Entrypoint Hotfix
 
 - `[Packaging]` Added a JavaScript extension entrypoint wrapper and changed package metadata to load `./index.js`, so npm-installed packages import compiled `dist/index.js` instead of asking Node to strip `index.ts` under `node_modules`. Source checkouts still fall back to `index.ts` before a local build exists.

package/README.md

@@ -169,6 +169,7 @@ The persistent tool surface is file-discovered:
 
 ```text
 ~/.pi/agent/recipes/*.json
+~/.pi/agent/recipes/*.md
 ```
 
 That directory is operator-managed executable memory.
@@ -178,6 +179,7 @@ Rules:
 - User recipes in `~/.pi/agent/recipes/` are tools by location;
 - Recipe filenames define tool ids;
 - 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.
 
@@ -220,7 +222,7 @@ Templates support:
 - Retries, recovery, failure policy, delays, and guarded execution;
 - Async run values such as `{run_id}`, `{state_dir}`, `{actor_address}`, `{default_room}`, and `{communication_file}`.
 
-The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
+The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. JSON is the canonical precise recipe format; Markdown recipes use frontmatter plus fenced `template`/`json recipe` blocks for literate authoring and compile into the same model. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
 
 ## Recipe Library
 
@@ -249,6 +251,10 @@ Use artifacts when outputs should survive context compression.
 
 Use mailbox declarations when an actor has a stable conversational surface.
 
+## Platform Support
+
+Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use a platform adapter under the same `message` API: Unix-compatible recipes can use their existing local control endpoint, while native Windows recipes can expose a Windows-native endpoint in run state. Some packaged scripts still depend on Unix tools and are WSL/Linux/macOS-only until migrated; their public recipe surface should stay `spawn` / `message` / `inspect` either way.
+
 ## Safety Boundary
 
 `pi-actors` is local-first, not sandbox-first.

package/dist/index.js

@@ -6,6 +6,7 @@
  */
 import { existsSync, readdirSync, watch } from "node:fs";
 import * as ActorInspectorTui from "./lib/actor-inspector-tui.js";
+import * as AsyncRuns from "./lib/async-runs.js";
 import * as CommandTemplates from "./lib/command-templates.js";
 import * as Observability from "./lib/observability.js";
 import * as Paths from "./lib/paths.js";
@@ -38,6 +39,7 @@ export default function toolRegistryExtension(pi) {
     const runDirWatchers = new Map();
     const observedRuns = new Map();
     const observedRunEventLines = new Map();
+    const retirementAttempts = new Set();
     let runStatusFrame = 0;
     let communicationWidgetVisible = false;
     let actorInspectorRows = 12;
@@ -49,6 +51,14 @@ export default function toolRegistryExtension(pi) {
     let selectedInspectorSequence;
     let recipeWatcherFailureNotified = false;
     const getRunOwnerId = (ctx) => ctx.sessionManager.getSessionId();
+    const retireCandidateRuns = (ctx, summary) => {
+        void Observability.executeRunRetirements(summary, {
+            attempted: retirementAttempts,
+            cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+            notify: (message, level) => ctx.ui.notify(message, level),
+            sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+        });
+    };
     const updateRunUi = (ctx, notify = false) => {
         const ownerId = getRunOwnerId(ctx);
         const summary = Observability.summarizeRuns(undefined, ownerId);
@@ -93,6 +103,7 @@ export default function toolRegistryExtension(pi) {
         const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary);
         if (!notify)
             return;
+        retireCandidateRuns(ctx, summary);
         for (const transition of transitions) {
             if (!Observability.shouldNotifyRunTransition(transition))
                 continue;

package/dist/lib/actor-rooms.d.ts

@@ -67,6 +67,7 @@ export declare function readBranchInboxMessages(stateDir: string, run: string, a
     queued_at?: string;
     status?: string;
 }>;
+export declare function getBranchInboxTerminalRetainLimit(): number;
 export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
 export declare function updateBranchInboxMessageStatus(stateDir: string, run: string, address: string, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
 export declare function appendRoomMessage(stateDir: string, room: string, message: ActorMessage): RoomAppendResult;

package/dist/lib/actor-rooms.js

@@ -9,6 +9,7 @@ import * as path from "node:path";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
+const DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED = 2000;
 const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
 function roomDir(stateDir, room) {
     return path.join(stateDir, "rooms", room);
@@ -275,6 +276,18 @@ export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
         throw error;
     }
 }
+export function getBranchInboxTerminalRetainLimit() {
+    const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
+    return Number.isInteger(value) && value >= 0
+        ? value
+        : DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED;
+}
+function compactBranchInboxMessages(messages) {
+    const retainTerminal = getBranchInboxTerminalRetainLimit();
+    const active = messages.filter((message) => message.status !== "handled" && message.status !== "failed");
+    const terminal = messages.filter((message) => message.status === "handled" || message.status === "failed");
+    return [...terminal.slice(-retainTerminal), ...active];
+}
 export function appendBranchInboxMessage(stateDir, run, address, message) {
     const branch = branchIdFromAddress(address, run);
     if (!branch)
@@ -305,7 +318,8 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
         });
         if (!changed)
             return false;
-        fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+        const compacted = compactBranchInboxMessages(updated);
+        fs.writeFileSync(file, `${compacted.map((message) => JSON.stringify(message)).join("\n")}\n`);
         return true;
     }
     finally {

package/dist/lib/async-runs.d.ts

@@ -6,8 +6,13 @@
 import type { CommandTemplateFailureScope, CommandTemplateValue } from "./command-templates.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 export type AsyncRunLaunchSource = "spawn" | "tool";
+export interface AsyncRunControlEndpoint {
+    path: string;
+    type: "fifo" | "named-pipe";
+}
 export interface AsyncRunStartParams {
     async?: boolean;
+    control?: AsyncRunControlEndpoint;
     file?: string;
     launch_source?: AsyncRunLaunchSource;
     name?: string;
@@ -72,6 +77,7 @@ export interface AsyncRunMeta {
     template: CommandTemplateValue;
     values: Record<string, unknown>;
     artifacts?: Record<string, string>;
+    control?: AsyncRunControlEndpoint;
     mailbox?: RecipeReferences.TemplateRecipeMailbox;
     recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
@@ -96,6 +102,16 @@ export declare function appendRunOutboxEvent(runOrDir: string, event: {
     to?: string;
     type?: string;
 }): Record<string, unknown>;
-export declare function sendRunMessage(runOrDir: string, message: string): Record<string, unknown>;
+export interface SendRunMessageOptions {
+    namedPipeSend?: (path: string, payload: string) => Promise<number>;
+    platform?: NodeJS.Platform;
+}
+export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
+export interface RunProcessSignalPlan {
+    args?: string[];
+    command?: string;
+    signalTarget: "processGroup" | "process" | "processTree";
+}
+export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
 export declare function killRun(runOrDir: string): Record<string, unknown>;

package/dist/lib/async-runs.js

@@ -3,8 +3,9 @@
  * Zones: async runtime, lifecycle, state files
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { createConnection } from "node:net";
 import { platform } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -89,7 +90,8 @@ function assertNoActiveRunState(stateDir) {
     throw new Error(`Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`);
 }
 function resolveRecipeFile(file) {
-    return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
+    return (RecipeReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
+        RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT));
 }
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
@@ -300,6 +302,7 @@ export function startRun(params, cwd) {
             template: resolved.template,
             values,
             ...(artifacts ? { artifacts } : {}),
+            ...(startParams.control ? { control: startParams.control } : {}),
             ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
             ...(recipeContextRecords && recipeContextRecords.length > 0
                 ? { recipe_context_records: recipeContextRecords }
@@ -507,10 +510,84 @@ export function appendRunOutboxEvent(runOrDir, event) {
         state_dir: stateDir,
     };
 }
-export function sendRunMessage(runOrDir, message) {
-    if (process.platform === "win32") {
-        throw new Error("run actor messages require Unix FIFO support; use WSL/Linux/macOS or a recipe-specific Windows transport.");
+function getRunControlEndpoint(status, stateDir) {
+    const control = status.control;
+    if (control && typeof control === "object" && !Array.isArray(control)) {
+        const record = control;
+        if ((record.type === "fifo" || record.type === "named-pipe") &&
+            typeof record.path === "string" &&
+            record.path.trim()) {
+            return { path: record.path, type: record.type };
+        }
+    }
+    return { path: join(stateDir, "control.fifo"), type: "fifo" };
+}
+function writeRunMessageReceipt(stateDir, message, bytes) {
+    const trimmedMessage = message.trim().toLowerCase();
+    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+    const ts = new Date().toISOString();
+    writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
+    try {
+        const envelope = JSON.parse(message);
+        writeFileSync(join(stateDir, "inbox.jsonl"), `${JSON.stringify({ ...envelope, received_at: ts })}\n`, { flag: "a" });
+    }
+    catch {
+        // Plain control lines are already represented in events.jsonl.
+    }
+    if (terminalMessage) {
+        markTerminalHandled(stateDir, {
+            event: "run.message",
+            message: trimmedMessage,
+        });
+    }
+}
+function sendRunMessageToFifo(endpoint, payload) {
+    if (!existsSync(endpoint.path))
+        throw new Error(`Run control FIFO not found: ${endpoint.path}`);
+    const stat = statSync(endpoint.path);
+    if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+        throw new Error(`Run control endpoint is not a FIFO: ${endpoint.path}`);
     }
+    let fd;
+    try {
+        fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+        return writeSync(fd, payload);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function sendRunMessageToNamedPipe(endpoint, payload, send) {
+    if (send)
+        return send(endpoint.path, payload);
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(endpoint.path);
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(new Error("named pipe connection timed out"));
+        }, 5000);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (error)
+                reject(error);
+            else
+                resolve(Buffer.byteLength(payload));
+        };
+        socket.on("error", finish);
+        socket.on("connect", () => {
+            socket.end(payload, () => finish());
+        });
+    });
+}
+export async function sendRunMessage(runOrDir, message, options = {}) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? runOrDir);
@@ -521,52 +598,66 @@ export function sendRunMessage(runOrDir, message) {
         throw new Error(`Run pid is not alive: ${run}`);
     if (!pidMatchesRun(pid, String(status.cwd), stateDir))
         throw new Error(`Run pid owner mismatch: ${run}`);
-    const controlPath = join(stateDir, "control.fifo");
-    if (!existsSync(controlPath))
-        throw new Error(`Run control FIFO not found: ${controlPath}`);
-    const stat = statSync(controlPath);
-    if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
-        throw new Error(`Run control endpoint is not a FIFO: ${controlPath}`);
-    }
+    const endpoint = getRunControlEndpoint(status, stateDir);
     const payload = message.endsWith("\n") ? message : `${message}\n`;
-    let fd;
+    const runtimePlatform = options.platform ?? process.platform;
     try {
-        fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
-        const bytes = writeSync(fd, payload);
-        const trimmedMessage = message.trim().toLowerCase();
-        const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
-        const ts = new Date().toISOString();
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
-        try {
-            const envelope = JSON.parse(message);
-            writeFileSync(join(stateDir, "inbox.jsonl"), `${JSON.stringify({ ...envelope, received_at: ts })}\n`, { flag: "a" });
-        }
-        catch {
-            // Plain control lines are already represented in events.jsonl.
-        }
-        if (terminalMessage) {
-            markTerminalHandled(stateDir, {
-                event: "run.message",
-                message: trimmedMessage,
-            });
+        if (endpoint.type === "fifo") {
+            if (runtimePlatform === "win32") {
+                throw new Error("run actor messages on native Windows require a named-pipe control endpoint; this recipe still exposes Unix FIFO control.");
+            }
+            const bytes = sendRunMessageToFifo(endpoint, payload);
+            writeRunMessageReceipt(stateDir, message, bytes);
+            return {
+                bytes,
+                control: "control.fifo",
+                control_path: endpoint.path,
+                control_type: endpoint.type,
+                run,
+                sent: true,
+                state_dir: stateDir,
+            };
         }
+        const bytes = await sendRunMessageToNamedPipe(endpoint, payload, options.namedPipeSend);
+        writeRunMessageReceipt(stateDir, message, bytes);
         return {
             bytes,
-            control: "control.fifo",
+            control: endpoint.path,
+            control_path: endpoint.path,
+            control_type: endpoint.type,
             run,
             sent: true,
             state_dir: stateDir,
         };
     }
     catch (error) {
-        throw new Error(`Run control FIFO is not ready: ${controlPath}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    finally {
-        if (fd !== undefined)
-            closeSync(fd);
+}
+export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.platform) {
+    if (runtimePlatform === "win32") {
+        return {
+            args: [
+                "/PID",
+                String(pid),
+                "/T",
+                ...(signal === "SIGKILL" ? ["/F"] : []),
+            ],
+            command: "taskkill",
+            signalTarget: "processTree",
+        };
     }
+    return { signalTarget: "processGroup" };
 }
 function signalOwnedRunProcess(pid, signal) {
+    const plan = getRunProcessSignalPlan(pid, signal);
+    if (plan.command && plan.args) {
+        const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
+        if (result.status !== 0) {
+            throw new Error(result.stderr?.trim() || result.stdout?.trim() || `${plan.command} failed`);
+        }
+        return plan;
+    }
     try {
         process.kill(-pid, signal);
         return { signalTarget: "processGroup" };

package/dist/lib/command-templates.js

@@ -74,8 +74,15 @@ function getExecutableName(command) {
         return "";
     return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
 }
+function matchesFlag(arg, flag) {
+    if (arg === flag)
+        return true;
+    if (/^-[A-Za-z]$/.test(flag) && /^-[A-Za-z]+$/.test(arg))
+        return arg.slice(1).includes(flag.slice(1));
+    return false;
+}
 function hasAnyFlag(args, flags) {
-    return args.some((arg) => flags.includes(arg));
+    return args.some((arg) => flags.some((flag) => matchesFlag(arg, flag)));
 }
 function hasRiskyPathArg(args) {
     return args.some((arg) => arg === "/" ||

package/dist/lib/observability.d.ts

@@ -37,9 +37,23 @@ export interface RunSummary {
 }
 export interface RunRetirementCandidate {
     activeSubagents: number;
+    childRuns: number;
     descendantSubagents: number;
     run: string;
     stateDir: string;
+    terminalChildRuns: number;
+}
+export interface RunRetirementExecution {
+    action: "stop" | "cancel" | "skip" | "failed";
+    error?: string;
+    run: string;
+    stateDir: string;
+}
+export interface RunRetirementExecutorOptions {
+    attempted?: Set<string>;
+    cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;
+    notify?: (message: string, level: "info" | "warning" | "error") => void;
+    sendStop: (candidate: RunRetirementCandidate) => Promise<unknown>;
 }
 export interface RunTransition {
     from: RunObservedStatus;
@@ -72,6 +86,7 @@ export declare function countRunningSubagents(stateRoot?: string, ownerId?: stri
 export declare function renderSubagentStatus(count: number, frame?: number): string | undefined;
 export declare function renderRunStatus(summary: RunSummary, frame?: number): string | undefined;
 export declare function findRunRetirementCandidates(summary: RunSummary): RunRetirementCandidate[];
+export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
 export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
 export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>): void;
 export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary): RunOutboxEvent[];