@llblab/pi-actors 0.39.0 → 0.40.0

package/lib/runs-start.ts

@@ -4,10 +4,21 @@
  * preparation before a new runner process is spawned.
  */
 
-import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
-import { isAlive, pidMatchesRun } from "./runs-process.ts";
+import {
+  isAlive,
+  readProcessIdentity,
+  verifyRunProcessIdentity,
+  type RunProcessIdentity,
+} from "./runs-process.ts";
 
 const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 
@@ -16,39 +27,79 @@ export type RunJsonReader = (path: string) => Record<string, unknown> | undefine
 export function assertNoActiveRunState(
   stateDir: string,
   readJson: RunJsonReader,
-  runnerPath: string,
+  _runnerPath: string,
 ): void {
   const meta = readJson(join(stateDir, "run.json"));
   if (!meta) return;
   const pid = Number(meta.pid || 0);
   const cwd = String(meta.cwd ?? "");
-  if (!pid || !isAlive(pid) || !pidMatchesRun(pid, cwd, stateDir, runnerPath))
-    return;
-  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.`,
+  if (!pid || !isAlive(pid)) return;
+  const identity = verifyRunProcessIdentity(
+    pid,
+    meta.process_identity as RunProcessIdentity | undefined,
   );
+  if (identity.status === "owner_mismatch") {
+    throw new Error(
+      `Run state process identity does not match the live pid: ${String(meta.run ?? stateDir)}. Refusing to reuse the state directory while pid ${pid} is alive.`,
+    );
+  }
+  if (identity.status === "unsupported_proof") {
+    throw new Error(
+      `Run state process identity proof is unavailable: ${String(meta.run ?? stateDir)}. Refusing to reuse the state directory while pid ${pid} is alive.`,
+    );
+  }
+  if (identity.valid) {
+    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 writeStartLockOwner(lockDir: string, recovered = false): void {
+  const processIdentity = readProcessIdentity(process.pid);
+  writeFileSync(
+    join(lockDir, "owner.json"),
+    `${JSON.stringify({
+      pid: process.pid,
+      createdAt: new Date().toISOString(),
+      ...(processIdentity ? { process_identity: processIdentity } : {}),
+      ...(recovered ? { recovered: true } : {}),
+    })}\n`,
+    "utf8",
+  );
+}
+
+function isStartLockOwnerProvenDead(lockDir: string): boolean {
+  try {
+    const owner = JSON.parse(
+      readFileSync(join(lockDir, "owner.json"), "utf8"),
+    ) as Record<string, unknown>;
+    const pid = Number(owner.pid || 0);
+    if (!pid) return false;
+    return verifyRunProcessIdentity(
+      pid,
+      owner.process_identity as RunProcessIdentity | undefined,
+    ).status === "dead_pid";
+  } catch {
+    return false;
+  }
 }
 
 export function acquireStateStartLock(stateDir: string): () => void {
   const lockDir = join(stateDir, ".start.lock");
   try {
     mkdirSync(lockDir);
-    writeFileSync(
-      join(lockDir, "owner.json"),
-      `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
-      "utf8",
-    );
+    writeStartLockOwner(lockDir);
   } catch (error) {
     try {
       const stat = statSync(lockDir);
-      if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+      if (
+        Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS &&
+        isStartLockOwnerProvenDead(lockDir)
+      ) {
         rmSync(lockDir, { recursive: true, force: true });
         mkdirSync(lockDir);
-        writeFileSync(
-          join(lockDir, "owner.json"),
-          `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), recovered: true })}\n`,
-          "utf8",
-        );
+        writeStartLockOwner(lockDir, true);
         return () => rmSync(lockDir, { recursive: true, force: true });
       }
     } catch {
@@ -65,23 +116,30 @@ export function acquireStateStartLock(stateDir: string): () => void {
 export function prepareStateDirForStart(
   stateDir: string,
   readJson: RunJsonReader,
-  runnerPath: string,
+  _runnerPath: string,
 ): void {
   const existing = readJson(join(stateDir, "run.json"));
   const existingPid = Number(existing?.pid || 0);
-  const existingCwd =
-    typeof existing?.cwd === "string" ? existing.cwd : undefined;
-  const existingResult = readJson(join(stateDir, "result.json"));
-  if (
-    !existingResult &&
-    existingPid &&
-    existingCwd &&
-    isAlive(existingPid) &&
-    pidMatchesRun(existingPid, existingCwd, stateDir, runnerPath)
-  ) {
-    throw new Error(
-      `Run state already has an active owned process: ${String(existing?.run ?? stateDir)}. Stop it before restarting.`,
+  if (existingPid && isAlive(existingPid)) {
+    const identity = verifyRunProcessIdentity(
+      existingPid,
+      existing?.process_identity as RunProcessIdentity | undefined,
     );
+    if (identity.status === "owner_mismatch") {
+      throw new Error(
+        `Run state process identity does not match the live pid: ${String(existing?.run ?? stateDir)}. Refusing to prepare the state directory while pid ${existingPid} is alive.`,
+      );
+    }
+    if (identity.status === "unsupported_proof") {
+      throw new Error(
+        `Run state process identity proof is unavailable: ${String(existing?.run ?? stateDir)}. Refusing to prepare the state directory while pid ${existingPid} is alive.`,
+      );
+    }
+    if (identity.valid) {
+      throw new Error(
+        `Run state already has an active owned process: ${String(existing?.run ?? stateDir)}. Stop it before restarting.`,
+      );
+    }
   }
   for (const file of [
     "events.jsonl",

package/lib/runs-status.ts

@@ -7,7 +7,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { AsyncRunStatus } from "./async-runs.ts";
-import { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun } from "./runs-process.ts";
+import {
+  isWithinRunnerIdentityGrace,
+  verifyRunProcessIdentity,
+  type RunProcessIdentity,
+} from "./runs-process.ts";
 import { readJsonlFileResilient } from "./state-readers.ts";
 
 export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
@@ -30,17 +34,20 @@ export function buildRunStatus(
   runOrDir: string,
   meta: Record<string, unknown>,
   readJson: RunJsonReader,
-  runnerPath: string,
+  _runnerPath: string,
   runnerIdentityGraceMs: number,
 ): Record<string, unknown> {
   const result = readJson(join(stateDir, "result.json"));
   const pid = Number(meta.pid || 0);
+  const processIdentity = verifyRunProcessIdentity(
+    pid,
+    meta.process_identity as RunProcessIdentity | undefined,
+  );
   const aliveOwnedRunner = Boolean(
     pid &&
-      isAlive(pid) &&
-      (!Array.isArray(meta.argv) ||
-        pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir, runnerPath) ||
-        isWithinRunnerIdentityGrace(meta, runnerIdentityGraceMs)),
+      (processIdentity.valid ||
+        (processIdentity.status === "unsupported_proof" &&
+          isWithinRunnerIdentityGrace(meta, runnerIdentityGraceMs))),
   );
   const status: AsyncRunStatus = result
     ? Number(result.code ?? 0) === 0
@@ -53,8 +60,10 @@ export function buildRunStatus(
   return {
     ...meta,
     eventsFile: join(stateDir, "events.jsonl"),
+    evidenceFile: join(stateDir, "review-evidence.json"),
     inboxFile: join(stateDir, "inbox.jsonl"),
     outboxFile: join(stateDir, "outbox.jsonl"),
+    process_identity_status: processIdentity.status,
     progress: readJson(join(stateDir, "progress.json")) || null,
     result: result || null,
     ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),

package/lib/runtime.ts

@@ -5,6 +5,7 @@
  */
 
 import { existsSync, watch, type FSWatcher } from "node:fs";
+import { basename, dirname } from "node:path";
 
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
@@ -186,10 +187,13 @@ export function createRecipeToolReloadWatcher(
 ): RecipeToolReloadWatcher {
   let reloadTimeout: NodeJS.Timeout | undefined;
   let rootWatcher: FSWatcher | undefined;
+  let parentWatcher: FSWatcher | undefined;
   let failureNotified = false;
   const close = (): void => {
     rootWatcher?.close();
     rootWatcher = undefined;
+    parentWatcher?.close();
+    parentWatcher = undefined;
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = undefined;
   };
@@ -210,21 +214,69 @@ export function createRecipeToolReloadWatcher(
     }, 150);
     reloadTimeout.unref?.();
   };
+  const watchParent = (ctx: RuntimeContext, recipeRoot: string): void => {
+    if (parentWatcher || rootWatcher) return;
+    const parent = dirname(recipeRoot);
+    if (!existsSync(parent)) {
+      notifyFailure(ctx);
+      return;
+    }
+    try {
+      parentWatcher = watch(parent, (_event, changedFile) => {
+        if (
+          changedFile &&
+          String(changedFile) !== basename(recipeRoot) &&
+          !existsSync(recipeRoot)
+        ) {
+          return;
+        }
+        if (!existsSync(recipeRoot)) return;
+        parentWatcher?.close();
+        parentWatcher = undefined;
+        watchRoot(ctx, recipeRoot);
+        scheduleReload(ctx);
+      });
+      parentWatcher.on("error", () => {
+        parentWatcher?.close();
+        parentWatcher = undefined;
+        notifyFailure(ctx);
+      });
+    } catch {
+      notifyFailure(ctx);
+    }
+  };
+  const watchRoot = (ctx: RuntimeContext, recipeRoot: string): void => {
+    if (rootWatcher) return;
+    if (!existsSync(recipeRoot)) {
+      watchParent(ctx, recipeRoot);
+      return;
+    }
+    try {
+      rootWatcher = watch(recipeRoot, () => {
+        if (!existsSync(recipeRoot)) {
+          rootWatcher?.close();
+          rootWatcher = undefined;
+          scheduleReload(ctx);
+          watchParent(ctx, recipeRoot);
+          return;
+        }
+        scheduleReload(ctx);
+      });
+      rootWatcher.on("error", () => {
+        rootWatcher?.close();
+        rootWatcher = undefined;
+        if (existsSync(recipeRoot)) notifyFailure(ctx);
+        else watchParent(ctx, recipeRoot);
+      });
+    } catch {
+      notifyFailure(ctx);
+    }
+  };
   return {
     close,
     watch(ctx: RuntimeContext): void {
-      const recipeRoot = Paths.getRecipeRoot();
-      if (rootWatcher || !existsSync(recipeRoot)) return;
-      try {
-        rootWatcher = watch(recipeRoot, () => scheduleReload(ctx));
-        rootWatcher.on("error", () => {
-          rootWatcher?.close();
-          rootWatcher = undefined;
-          notifyFailure(ctx);
-        });
-      } catch {
-        notifyFailure(ctx);
-      }
+      if (rootWatcher || parentWatcher) return;
+      watchRoot(ctx, Paths.getRecipeRoot());
     },
   };
 }

package/lib/tools-inspect.ts

@@ -139,6 +139,31 @@ function compactArtifactPath(value: unknown): string {
   return String(record.path ?? "<missing>");
 }
 
+function readBoundedReviewEvidence(
+  status: Record<string, unknown>,
+  limit: number,
+): Record<string, unknown> | undefined {
+  const evidenceFile = status.evidenceFile;
+  if (typeof evidenceFile !== "string" || !existsSync(evidenceFile))
+    return undefined;
+  try {
+    const manifest = asRecord(JSON.parse(readFileSync(evidenceFile, "utf8")));
+    const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
+    const bounded = commands.slice(-Math.max(1, limit));
+    return {
+      ...manifest,
+      commands: bounded,
+      commands_total: commands.length,
+      ...(bounded.length < commands.length ? { commands_truncated: true } : {}),
+    };
+  } catch {
+    return {
+      status: "invalid",
+      error: "review evidence manifest is unreadable",
+    };
+  }
+}
+
 function compactActorFiles(status: Record<string, unknown>): string {
   const run = String(status.run ?? "<unknown>");
   const artifacts = asRecord(status.artifacts);
@@ -147,6 +172,7 @@ function compactActorFiles(status: Record<string, unknown>): string {
     status.stderrLog,
     status.eventsFile,
     status.outboxFile,
+    status.evidenceFile,
     status.state_dir
       ? `${String(status.state_dir)}/communication.json`
       : undefined,
@@ -305,9 +331,15 @@ function getPiActorsTriage(
 ): Record<string, unknown> {
   const runtime = getPiActorsRuntimeStatus();
   const currentSession = ToolsAccess.getContextSessionId(ctx);
-  const allRuns = AsyncRuns.listRuns().map((run) =>
-    AsyncRuns.getRunStatus(String(run.state_dir)),
-  );
+  const listRuns = deps.listRuns ?? AsyncRuns.listRuns;
+  const getRunStatus = deps.getRunStatus ?? AsyncRuns.getRunStatus;
+  const allRuns = listRuns().flatMap((run) => {
+    try {
+      return [getRunStatus(String(run.state_dir))];
+    } catch {
+      return [];
+    }
+  });
   const visibleRuns = currentSession
     ? allRuns.filter(
         (run) => !run.ownerId || run.ownerId === currentSession,
@@ -433,7 +465,9 @@ function compactToolActor(name: string, tool: Record<string, unknown>): string {
 }
 
 export interface InspectToolDeps<TContext = unknown> {
+  getRunStatus?: (runOrDir: string) => Record<string, any>;
   getTool?: (name: string) => any | undefined;
+  listRuns?: () => Array<Record<string, any>>;
   packagedRecipeRoot?: string;
   recipeRoot?: string;
 }
@@ -832,16 +866,24 @@ export function createInspectToolDefinition<TContext = unknown>(
               | Record<string, AsyncRuns.RunArtifactDeclaration>
               | undefined,
           );
+          const reviewEvidence = readBoundedReviewEvidence(
+            status,
+            Number(input.lines || Limits.DEFAULT_INSPECT_LINES),
+          );
           const details = artifactManifest
             ? {
                 ...status,
+                ...(reviewEvidence ? { review_evidence: reviewEvidence } : {}),
                 artifact_manifest: artifactManifest,
                 next_actions: ToolsResponse.artifactNextActions(
                   status.run ?? runId,
                   asRecord(status.artifacts),
                 ),
               }
-            : status;
+            : {
+                ...status,
+                ...(reviewEvidence ? { review_evidence: reviewEvidence } : {}),
+              };
           return {
             content: [
               {

package/lib/tools-register.ts

@@ -38,9 +38,6 @@ export function createRegisterToolDefinition<TContext>(
         ),
         draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
         name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
-        state_dir: stringSchema(
-          Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir,
-        ),
         template: unionSchema([
           stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
           looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),

package/lib/tools-spawn.ts

@@ -143,9 +143,6 @@ export function createSpawnToolDefinition<
         recipe: Schema.stringSchema(
           "Alias for file; template recipe JSON file/name to spawn.",
         ),
-        state_dir: Schema.stringSchema(
-          "Optional explicit run state directory.",
-        ),
         template: Schema.unionSchema([
           Schema.stringSchema("Inline command template string"),
           Schema.arraySchema(
@@ -172,6 +169,11 @@ export function createSpawnToolDefinition<
       ctx: TContext,
     ) {
       const input = asRecord(params);
+      if (input.state_dir !== undefined) {
+        throw new Error(
+          "spawn.state_dir is not supported; run state is runtime-owned so run:<id> remains addressable and retention-safe.",
+        );
+      }
       const runId = runIdFromActorAddress(
         typeof input.as === "string" ? input.as : undefined,
       );
@@ -189,8 +191,6 @@ export function createSpawnToolDefinition<
             launch_source: "spawn",
             ownerId: getRunOwnerId(ctx),
             run_id: runId,
-            state_dir:
-              typeof input.state_dir === "string" ? input.state_dir : undefined,
             ...(input.template !== undefined
               ? {
                   template:

package/lib/tools.ts

@@ -32,6 +32,14 @@ export interface CoreActorToolDefinitionDeps<
   setActiveTools: (toolNames: string[]) => void;
 }
 
+export function resolveActiveRuntimeTool(
+  name: string,
+  activeTools: Pick<Map<string, unknown>, "has">,
+  getDefinition: (name: string) => unknown,
+): unknown {
+  return activeTools.has(name) ? getDefinition(name) : undefined;
+}
+
 export const RESERVED_TOOL_NAMES = new Set([
   "read",
   "write",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -51,7 +51,7 @@
   ],
   "pi": {
     "extensions": [
-      "./dist/index.js"
+      "./dist/pi-actors/index.js"
     ],
     "sourceExtensions": [
       "./index.ts"

package/recipes/subagent-judge.json

@@ -28,5 +28,6 @@
       "run.failed"
     ]
   },
-  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Judge this report: {report}. Rubric: {rubric}. Evidence: {evidence}. Output format: {output_format}"
+  "accept_output": "review_evidence",
+  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Judge this report: {report}. Rubric: {rubric}. Evidence: {evidence}. Begin the response with ACTOR_REVIEW_RESULT on its own line. Output format: {output_format}"
 }

package/recipes/subagent-merge.json

@@ -30,5 +30,6 @@
       "run.failed"
     ]
   },
-  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Merge these subagent outputs using mode {mode}: {inputs}. Merge policy: {merge_policy}. Risk policy: {risk_policy}. Output format: {output_format}"
+  "accept_output": "review_evidence",
+  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Merge these subagent outputs using mode {mode}: {inputs}. Merge policy: {merge_policy}. Risk policy: {risk_policy}. Begin the response with ACTOR_REVIEW_RESULT on its own line. Output format: {output_format}"
 }

package/recipes/subagent-normalize.json

@@ -26,5 +26,6 @@
       "run.failed"
     ]
   },
-  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Normalize this subagent output. Target format: {format}. Preservation policy: {preservation_policy}. Input: {input}"
+  "accept_output": "review_evidence",
+  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Normalize this subagent output. Begin the response with ACTOR_REVIEW_RESULT on its own line. Target format: {format}. Preservation policy: {preservation_policy}. Input: {input}"
 }

package/recipes/subagent-review-coordinator.json

@@ -174,7 +174,7 @@
       "values": {
         "input": "Use merged and judged output from stdin.",
         "format": "{output_format}",
-        "preservation_policy": "Preserve branch status and explicitly mark Status as complete, degraded, or insufficient_data.",
+        "preservation_policy": "Preserve branch status and explicitly mark Status as complete, degraded, or insufficient_data. Include stable ACTOR_EVIDENCE_REF values from stdin in the Evidence section for every reviewer, verifier, merger, and judge source used. Do not claim complete when any required evidence reference is absent or inconsistent.",
         "model": "{merger_model}",
         "thinking": "{thinking}",
         "tools": "{tools}"

package/recipes/subagent-review.json

@@ -32,5 +32,6 @@
       "run.failed"
     ]
   },
-  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Review {scope} through this lens: {lens}. Instructions: {instructions}. Evidence policy: {evidence_policy}. Risk policy: {risk_policy}. Output format: {output_format}"
+  "accept_output": "review_evidence",
+  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Review {scope} through this lens: {lens}. Instructions: {instructions}. Evidence policy: {evidence_policy}. Risk policy: {risk_policy}. Begin the response with ACTOR_REVIEW_RESULT on its own line. Output format: {output_format}"
 }

package/recipes/subagent-verify.json

@@ -29,5 +29,6 @@
       "run.failed"
     ]
   },
-  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Verify this claim against the provided evidence. Claim: {claim}. Evidence or artifact paths: {evidence}. Acceptance: {acceptance}. Evidence policy: {evidence_policy}. Output format: {output_format}"
+  "accept_output": "review_evidence",
+  "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Verify this claim against the provided evidence. Claim: {claim}. Evidence or artifact paths: {evidence}. Acceptance: {acceptance}. Evidence policy: {evidence_policy}. Begin the response with ACTOR_REVIEW_RESULT on its own line. Output format: {output_format}"
 }