@llblab/pi-actors 0.39.0 → 0.40.1

package/dist/lib/prompts.js

@@ -16,23 +16,22 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, output.
+- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
-- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
+- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 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.",
     templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
     templateNull: "Delete the tool when template is null.",

package/dist/lib/recipes-context.js

@@ -47,10 +47,10 @@ function piOptionConsumesNextArg(arg) {
 function isPiFileArgument(arg) {
     return arg.startsWith("@") && arg.length > 1;
 }
-export function findPiPrintPromptIndex(args) {
+function findPiPrintPromptIndexes(args) {
     let printMode = false;
     let positionalOnly = false;
-    let promptIndex;
+    const promptIndexes = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!positionalOnly && arg === "--") {
@@ -68,9 +68,12 @@ export function findPiPrintPromptIndex(args) {
         }
         if (!printMode || isPiFileArgument(arg))
             continue;
-        promptIndex = index;
+        promptIndexes.push(index);
     }
-    return promptIndex;
+    return promptIndexes;
+}
+export function findPiPrintPromptIndex(args) {
+    return findPiPrintPromptIndexes(args).at(-1);
 }
 function matchesActorContext(record, context) {
     if (!context)
@@ -134,14 +137,19 @@ export function appendRecipeContextToPiArgs(command, args, records, context) {
 export function materializePiPrintPromptArg(command, args, promptFile) {
     if (!isPiCommand(command))
         return { args };
-    const promptIndex = findPiPrintPromptIndex(args);
-    if (promptIndex === undefined)
+    const promptIndexes = findPiPrintPromptIndexes(args);
+    if (promptIndexes.length === 0)
         return { args };
-    const prompt = args[promptIndex];
+    const prompt = promptIndexes.map((index) => args[index]).join(" ");
     const path = typeof promptFile === "function" ? promptFile() : promptFile;
     writeFileSync(path, prompt, "utf8");
-    const next = [...args];
-    next[promptIndex] = `@${path}`;
+    const promptIndexSet = new Set(promptIndexes);
+    const firstPromptIndex = promptIndexes[0];
+    const next = args.flatMap((arg, index) => {
+        if (index === firstPromptIndex)
+            return [`@${path}`];
+        return promptIndexSet.has(index) ? [] : [arg];
+    });
     return {
         args: next,
         promptBytes: Buffer.byteLength(prompt),

package/dist/lib/recipes-discovery.js

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as ModelContext from "./model-context.js";
 import * as RecipesReferences from "./recipes-references.js";
+import * as RecipesUsage from "./recipes-usage.js";
 import * as Schema from "./schema.js";
 function assertToolSafeRepeatConfig(config, argTypes, defaults) {
     if (typeof config === "string" || config === undefined || config === null)
@@ -242,8 +243,13 @@ export function discoverRecipeSources(sources) {
 export function discoverRecipes(roots) {
     return discoverRecipeSources(roots.map((root) => ({ root })));
 }
-function recipeUsage(config) {
-    const usage = config?.usage;
+function recipeUsage(entry) {
+    const stored = entry.mutableUsage
+        ? RecipesUsage.readRecipeUsage(entry.path)
+        : undefined;
+    if (stored)
+        return stored;
+    const usage = entry.config?.usage;
     return usage && typeof usage === "object" && !Array.isArray(usage)
         ? usage
         : undefined;
@@ -273,7 +279,7 @@ function cleanupRecommendation(entry) {
             actions: ["keep disabled", "delete", "archive"],
         };
     }
-    const usage = recipeUsage(entry.config);
+    const usage = recipeUsage(entry);
     const calls = Number(usage?.calls ?? 0);
     if (entry.mutableUsage && entry.tool && calls === 0) {
         return {
@@ -581,8 +587,8 @@ export function summarizeDiscovery(result) {
                 }
                 : {}),
             ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
-            ...(recipeUsage(entry.config)
-                ? { usage: recipeUsage(entry.config) }
+            ...(recipeUsage(entry)
+                ? { usage: recipeUsage(entry) }
                 : {}),
         }))
             .sort((a, b) => a.id.localeCompare(b.id)),

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

@@ -39,6 +39,7 @@ export interface TemplateRecipeDefinition {
     when?: boolean | string;
     timeout?: number | string;
     delay?: number | string;
+    accept_output?: "review_evidence";
     output?: string;
     artifacts?: Record<string, string>;
     mailbox?: TemplateRecipeMailbox;
@@ -52,7 +53,6 @@ export interface TemplateRecipeDefinition {
 }
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
     async?: boolean;
-    state_dir?: string;
 }
 export interface TemplateRecipeContextRecord {
     alias?: string;

package/dist/lib/recipes-references.js

@@ -141,6 +141,7 @@ function getRecipeCommandTemplate(raw) {
         "when",
         "timeout",
         "delay",
+        "accept_output",
         "output",
         "retry",
         "failure",
@@ -695,11 +696,6 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
                     : delegated?.async === false
                         ? { async: false }
                         : {}),
-        ...(typeof substituted.state_dir === "string"
-            ? { state_dir: substituted.state_dir }
-            : typeof delegated?.state_dir === "string"
-                ? { state_dir: delegated.state_dir }
-                : {}),
         ...(Object.keys(imports).length > 0
             ? { imports: getRecipeImports(raw) }
             : {}),
@@ -736,6 +732,9 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
             typeof substituted.delay === "string"
             ? { delay: substituted.delay }
             : {}),
+        ...(substituted.accept_output === "review_evidence"
+            ? { accept_output: substituted.accept_output }
+            : {}),
         ...(typeof substituted.output === "string"
             ? { output: substituted.output }
             : {}),

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

@@ -4,4 +4,6 @@
  * Owns lightweight launch counters for user-owned recipe files
  */
 export type RecipeLaunchKind = "direct" | "spawn" | "tool";
+export declare function getRecipeUsagePath(path: string): string;
+export declare function readRecipeUsage(path: string): Record<string, unknown> | undefined;
 export declare function recordRecipeLaunch(path: string, now?: Date, kind?: RecipeLaunchKind): boolean;

package/dist/lib/recipes-usage.js

@@ -5,7 +5,8 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { writeJsonAtomic } from "./file-state.js";
+import { basename, dirname, join } from "node:path";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.js";
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
@@ -28,25 +29,38 @@ function getRecipeFingerprint(raw) {
     const { usage: _usage, ...content } = raw;
     return createHash("sha256").update(stableStringify(content)).digest("hex");
 }
+export function getRecipeUsagePath(path) {
+    return join(dirname(path), ".usage", `${basename(path)}.json`);
+}
+export function readRecipeUsage(path) {
+    try {
+        const value = JSON.parse(readFileSync(getRecipeUsagePath(path), "utf8"));
+        return isRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function launchCounterKey(kind) {
     return `${kind}_calls`;
 }
 export function recordRecipeLaunch(path, now = new Date(), kind = "direct") {
     if (!existsSync(path))
         return false;
-    try {
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        if (!isRecord(raw))
-            return false;
-        const usage = isRecord(raw.usage) ? raw.usage : {};
-        const fingerprint = getRecipeFingerprint(raw);
-        const changed = typeof usage.fingerprint === "string" &&
-            usage.fingerprint !== fingerprint;
-        const nowIso = now.toISOString();
-        const counterKey = launchCounterKey(kind);
-        writeJsonAtomic(path, {
-            ...raw,
-            usage: {
+    const usagePath = getRecipeUsagePath(path);
+    return withFileMutationLock(usagePath, () => {
+        try {
+            const raw = JSON.parse(readFileSync(path, "utf8"));
+            if (!isRecord(raw))
+                return false;
+            const storedUsage = readRecipeUsage(path);
+            const usage = storedUsage ?? (isRecord(raw.usage) ? raw.usage : {});
+            const fingerprint = getRecipeFingerprint(raw);
+            const changed = typeof usage.fingerprint === "string" &&
+                usage.fingerprint !== fingerprint;
+            const nowIso = now.toISOString();
+            const counterKey = launchCounterKey(kind);
+            writeJsonAtomic(usagePath, {
                 ...usage,
                 calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
                 [counterKey]: (changed ? 0 : normalizeCalls(usage[counterKey])) + 1,
@@ -59,11 +73,11 @@ export function recordRecipeLaunch(path, now = new Date(), kind = "direct") {
                         reset_reason: "recipe content fingerprint changed",
                     }
                     : {}),
-            },
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
 }

package/dist/lib/registry.d.ts

@@ -9,7 +9,6 @@ export interface RegisterToolInput {
     name?: string;
     description?: string;
     async?: boolean;
-    state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue | null;
     draft?: string;
     args?: string;
@@ -24,7 +23,6 @@ export interface RegisterToolResultDetails {
     draft?: string;
     promoted?: boolean;
     recipeName?: string;
-    state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue;
     templateWarnings?: string[];
     tool: string;

package/dist/lib/registry.js

@@ -3,11 +3,12 @@
  * Zones: registry mutations, persistence, runtime activation
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
-import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
+import * as Config from "./config.js";
 import * as ExecutionOutput from "./execution-output.js";
-import { writeJsonAtomic } from "./file-state.js";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.js";
 import * as Identity from "./identity.js";
 import * as Paths from "./paths.js";
 import * as RecipesReferences from "./recipes-references.js";
@@ -94,7 +95,6 @@ function persistToolRecipe(deps, cfg) {
     writeJsonAtomic(path, {
         description: cfg.description,
         ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
-        ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
         ...(cfg.storedArgs ? { args: cfg.storedArgs } : {}),
         ...(cfg.storedDefaults ? { defaults: cfg.storedDefaults } : {}),
         ...(cfg.recipe?.values ? { values: cfg.recipe.values } : {}),
@@ -125,6 +125,23 @@ function deleteTool(name, ctx, deps) {
         details: { config: recipePath, tool: name },
     };
 }
+function readAuthoritativeStoredTool(deps, name) {
+    const path = getToolRecipePath(deps, name);
+    if (!existsSync(path))
+        return { exists: false };
+    try {
+        const normalized = Config.normalizeStoredTool(name, JSON.parse(readFileSync(path, "utf8")), deps.reservedToolNames);
+        if (!normalized.cfg)
+            return { exists: true };
+        return {
+            exists: true,
+            tool: { ...normalized.cfg, sourcePath: path },
+        };
+    }
+    catch {
+        return { exists: true };
+    }
+}
 function getInputTemplate(value) {
     if (typeof value === "string")
         return value.trim();
@@ -167,9 +184,6 @@ function buildConfig(name, input, existing) {
         ? {
             name: inputRecipe,
             ...(typeof input.async === "boolean" ? { async: input.async } : {}),
-            ...(typeof input.state_dir === "string" && input.state_dir.trim()
-                ? { state_dir: input.state_dir.trim() }
-                : {}),
             template: finalTemplate,
             ...(input.values && typeof input.values === "object"
                 ? { values: input.values }
@@ -219,7 +233,7 @@ function buildConfig(name, input, existing) {
         ...(storedDefaults !== undefined ? { storedDefaults } : {}),
     };
 }
-export async function executeRegisterTool(params, ctx, deps) {
+function executeRegisterToolUnlocked(params, ctx, deps) {
     const input = params;
     if (!input.name)
         return listTools(deps);
@@ -237,11 +251,12 @@ export async function executeRegisterTool(params, ctx, deps) {
     if (templateProvided && (template === null || template === ""))
         return deleteTool(name, ctx, deps);
     const tools = deps.getTools();
-    const existing = tools.get(name);
+    const authoritative = readAuthoritativeStoredTool(deps, name);
+    const existing = authoritative.tool ?? tools.get(name);
     const blocker = deps.getToolNameBlocker(name);
     if (blocker)
         throw new Error(ExecutionOutput.formatToolText(blocker));
-    if (existing && !input.update) {
+    if ((authoritative.exists || existing) && !input.update) {
         throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
     }
     if (template === undefined && !existing) {
@@ -275,10 +290,18 @@ export async function executeRegisterTool(params, ctx, deps) {
             defaults: cfg.defaults,
             ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
             ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),
-            ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
             ...(cfg.template ? { template: cfg.template } : {}),
             ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
             tool: name,
         },
     };
 }
+export async function executeRegisterTool(params, ctx, deps) {
+    const input = params;
+    if (!input.name)
+        return executeRegisterToolUnlocked(params, ctx, deps);
+    const name = Identity.normalizeToolName(input.name);
+    if (!name)
+        return executeRegisterToolUnlocked(params, ctx, deps);
+    return withFileMutationLock(getToolRecipePath(deps, name), () => executeRegisterToolUnlocked(params, ctx, deps));
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Async run state-directory ownership.
+ * Owns the marker proof required before launch and destructive retention.
+ */
+export declare const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
+export declare function claimRunStateDirectory(stateDir: string, run: string): string;
+export declare function assertOwnedRunStateDirectory(stateDir: string, run: string): string;

package/dist/lib/runs-ownership.js

@@ -0,0 +1,82 @@
+/**
+ * Async run state-directory ownership.
+ * Owns the marker proof required before launch and destructive retention.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { writeJsonAtomic } from "./file-state.js";
+export const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
+function markerPath(stateDir) {
+    return join(stateDir, RUN_STATE_OWNERSHIP_FILE);
+}
+function comparablePath(path) {
+    const resolved = resolve(path);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function assertCanonicalDirectory(stateDir) {
+    const resolved = resolve(stateDir);
+    if (lstatSync(resolved).isSymbolicLink()) {
+        throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
+    }
+    const canonical = realpathSync(resolved);
+    if (comparablePath(canonical) !== comparablePath(resolved)) {
+        throw new Error(`Run state directory has an ambiguous symlink alias: ${resolved}`);
+    }
+    return resolved;
+}
+function readMarker(stateDir) {
+    try {
+        const value = JSON.parse(readFileSync(markerPath(stateDir), "utf8"));
+        if (value.version !== 1 ||
+            typeof value.run !== "string" ||
+            typeof value.state_dir !== "string" ||
+            typeof value.ownership_token !== "string" ||
+            !value.ownership_token) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function assertMarkerMatches(marker, stateDir, run) {
+    if (!marker) {
+        throw new Error(`Run state ownership marker is missing or invalid: ${stateDir}`);
+    }
+    if (marker.state_dir !== stateDir || marker.run !== run) {
+        throw new Error(`Run state ownership marker does not match run ${run}: ${stateDir}`);
+    }
+    return marker;
+}
+export function claimRunStateDirectory(stateDir, run) {
+    const resolved = resolve(stateDir);
+    if (existsSync(resolved) && lstatSync(resolved).isSymbolicLink()) {
+        throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
+    }
+    mkdirSync(resolved, { recursive: true });
+    const canonical = assertCanonicalDirectory(resolved);
+    const existing = readMarker(canonical);
+    if (existing) {
+        assertMarkerMatches(existing, canonical, run);
+        return canonical;
+    }
+    const existingEntries = readdirSync(canonical).filter((entry) => entry !== ".start.lock");
+    if (existingEntries.length > 0) {
+        throw new Error(`Refusing to claim existing non-run directory: ${canonical}`);
+    }
+    writeJsonAtomic(markerPath(canonical), {
+        created_at: new Date().toISOString(),
+        ownership_token: randomUUID(),
+        run,
+        state_dir: canonical,
+        version: 1,
+    });
+    return canonical;
+}
+export function assertOwnedRunStateDirectory(stateDir, run) {
+    const canonical = assertCanonicalDirectory(stateDir);
+    assertMarkerMatches(readMarker(canonical), canonical, run);
+    return canonical;
+}

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

@@ -1,7 +1,22 @@
 /**
  * Async run process identity helpers.
- * Owns liveness checks and Linux runner identity matching for run-owned processes.
+ * Owns cross-platform liveness and stable runner process identity proofs.
  */
+export interface RunProcessIdentity {
+    command: string;
+    cwd?: string;
+    platform: NodeJS.Platform;
+    start_time: string;
+}
+export type RunProcessIdentityStatus = "valid" | "dead_pid" | "owner_mismatch" | "unsupported_proof";
+export interface RunProcessIdentityResult {
+    status: RunProcessIdentityStatus;
+    valid: boolean;
+}
+type ProcessIdentityReader = (pid: number, runtimePlatform: NodeJS.Platform) => RunProcessIdentity | undefined;
 export declare function isAlive(pid: number): boolean;
-export declare function pidMatchesRun(pid: number, cwd: string, stateDir: string, runnerPath: string): boolean;
+export declare function readProcessIdentity(pid: number, runtimePlatform?: NodeJS.Platform): RunProcessIdentity | undefined;
+export declare function captureRunProcessIdentity(pid: number, cwd: string, stateDir: string, runnerPath: string, runtimePlatform?: NodeJS.Platform, reader?: ProcessIdentityReader): RunProcessIdentity | undefined;
+export declare function verifyRunProcessIdentity(pid: number, expected: RunProcessIdentity | undefined, runtimePlatform?: NodeJS.Platform, reader?: ProcessIdentityReader, alive?: (pid: number) => boolean): RunProcessIdentityResult;
 export declare function isWithinRunnerIdentityGrace(meta: Record<string, unknown>, graceMs: number): boolean;
+export {};

package/dist/lib/runs-process.js

@@ -1,8 +1,9 @@
 /**
  * Async run process identity helpers.
- * Owns liveness checks and Linux runner identity matching for run-owned processes.
+ * Owns cross-platform liveness and stable runner process identity proofs.
  */
-import { existsSync, readFileSync, readlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { platform } from "node:os";
 import { resolve } from "node:path";
 export function isAlive(pid) {
@@ -14,19 +15,106 @@ export function isAlive(pid) {
         return false;
     }
 }
-export function pidMatchesRun(pid, cwd, stateDir, runnerPath) {
-    if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
-        return isAlive(pid);
+function readLinuxIdentity(pid) {
+    if (!existsSync(`/proc/${pid}`))
+        return undefined;
     try {
-        const procCwd = readlinkSync(`/proc/${pid}/cwd`);
-        const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
-        return (procCwd === resolve(cwd) &&
-            cmdline.includes(runnerPath) &&
-            cmdline.includes(stateDir));
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const close = stat.lastIndexOf(")");
+        const fields = stat.slice(close + 2).trim().split(/\s+/);
+        const startTime = fields[19];
+        if (!startTime)
+            return undefined;
+        return {
+            command: readFileSync(`/proc/${pid}/cmdline`, "utf8").replaceAll("\0", " ").trim(),
+            cwd: readlinkSync(`/proc/${pid}/cwd`),
+            platform: "linux",
+            start_time: startTime,
+        };
     }
     catch {
-        return false;
+        return undefined;
+    }
+}
+function readDarwinIdentity(pid) {
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "command="], { encoding: "utf8" });
+    if (result.status !== 0)
+        return undefined;
+    const match = result.stdout.trim().match(/^(.{24})\s+(.+)$/s);
+    if (!match)
+        return undefined;
+    return {
+        command: match[2].trim(),
+        platform: "darwin",
+        start_time: match[1].trim(),
+    };
+}
+function readWindowsIdentity(pid) {
+    const command = [
+        `$p = Get-CimInstance Win32_Process -Filter \"ProcessId = ${pid}\";`,
+        "if ($null -eq $p) { exit 3 };",
+        "$p | Select-Object CreationDate,ExecutablePath,CommandLine | ConvertTo-Json -Compress",
+    ].join(" ");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], { encoding: "utf8", windowsHide: true });
+    if (result.status !== 0)
+        return undefined;
+    try {
+        const value = JSON.parse(result.stdout);
+        if (typeof value.CreationDate !== "string")
+            return undefined;
+        const executable = typeof value.ExecutablePath === "string" ? value.ExecutablePath : "";
+        const commandLine = typeof value.CommandLine === "string" ? value.CommandLine : "";
+        return {
+            command: `${executable}\n${commandLine}`.trim(),
+            platform: "win32",
+            start_time: value.CreationDate,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readProcessIdentity(pid, runtimePlatform = platform()) {
+    if (runtimePlatform === "linux")
+        return readLinuxIdentity(pid);
+    if (runtimePlatform === "darwin")
+        return readDarwinIdentity(pid);
+    if (runtimePlatform === "win32")
+        return readWindowsIdentity(pid);
+    return undefined;
+}
+export function captureRunProcessIdentity(pid, cwd, stateDir, runnerPath, runtimePlatform = platform(), reader = readProcessIdentity) {
+    const identity = reader(pid, runtimePlatform);
+    if (!identity)
+        return undefined;
+    if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
+        return undefined;
+    }
+    const resolvedCwd = resolve(cwd);
+    const canonicalCwd = existsSync(resolvedCwd)
+        ? realpathSync.native(resolvedCwd)
+        : resolvedCwd;
+    const expectedCwd = runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;
+    const actualCwd = runtimePlatform === "win32" && identity.cwd
+        ? identity.cwd.toLowerCase()
+        : identity.cwd;
+    if (actualCwd && actualCwd !== expectedCwd)
+        return undefined;
+    return identity;
+}
+export function verifyRunProcessIdentity(pid, expected, runtimePlatform = platform(), reader = readProcessIdentity, alive = isAlive) {
+    if (!alive(pid))
+        return { status: "dead_pid", valid: false };
+    if (!expected || expected.platform !== runtimePlatform) {
+        return { status: "unsupported_proof", valid: false };
     }
+    const current = reader(pid, runtimePlatform);
+    if (!current)
+        return { status: "unsupported_proof", valid: false };
+    const valid = current.start_time === expected.start_time &&
+        current.command === expected.command &&
+        current.cwd === expected.cwd;
+    return { status: valid ? "valid" : "owner_mismatch", valid };
 }
 export function isWithinRunnerIdentityGrace(meta, graceMs) {
     const createdAt = typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;

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

@@ -2,7 +2,10 @@
  * Async run retention operations.
  * Owns terminal-run archive and prune filesystem behavior.
  */
+import { cpSync } from "node:fs";
 export declare function archiveTerminalRun(status: Record<string, unknown>): Record<string, unknown>;
 export declare function pruneTerminalRun(status: Record<string, unknown>, options?: {
     preserveArtifacts?: boolean;
+}, deps?: {
+    copyArtifact?: typeof cpSync;
 }): Record<string, unknown>;