@llblab/pi-actors 0.41.0 → 0.42.0

package/lib/runs-control.ts

@@ -1,12 +1,17 @@
 /**
  * Async run process control primitives.
- * Owns platform signal planning, owned-process signalling, and terminal control markers.
+ * Owns: platform signal planning, owned-process signalling, and terminal control markers.
  */
 
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 
 import { writeJsonAtomic } from "./file-state.ts";
+import {
+  verifyRunProcessIdentity,
+  type RunProcessIdentity,
+  type RunProcessIdentityResult,
+} from "./runs-process.ts";
 
 export interface RunProcessSignalPlan {
   args?: string[];
@@ -34,11 +39,36 @@ export function getRunProcessSignalPlan(
   return { signalTarget: "processGroup" };
 }
 
+export interface RunProcessSignalDeps {
+  killProcess?: typeof process.kill;
+  runtimePlatform?: NodeJS.Platform;
+  verifyIdentity?: (
+    pid: number,
+    expected: RunProcessIdentity,
+    runtimePlatform: NodeJS.Platform,
+  ) => RunProcessIdentityResult;
+}
+
 export function signalOwnedRunProcess(
   pid: number,
   signal: NodeJS.Signals,
+  expectedIdentity?: RunProcessIdentity,
+  deps: RunProcessSignalDeps = {},
 ): RunProcessSignalPlan {
-  const plan = getRunProcessSignalPlan(pid, signal);
+  const runtimePlatform = deps.runtimePlatform ?? process.platform;
+  if (expectedIdentity) {
+    const proof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(
+      pid,
+      expectedIdentity,
+      runtimePlatform,
+    );
+    if (!proof.valid) {
+      throw new Error(
+        `Run process identity changed before signaling: ${proof.status.replaceAll("_", " ")}`,
+      );
+    }
+  }
+  const plan = getRunProcessSignalPlan(pid, signal, runtimePlatform);
   if (plan.command && plan.args) {
     const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
     if (result.status !== 0) {
@@ -50,11 +80,25 @@ export function signalOwnedRunProcess(
     }
     return plan;
   }
+  const killProcess = deps.killProcess ?? process.kill.bind(process);
   try {
-    process.kill(-pid, signal);
+    killProcess(-pid, signal);
     return { signalTarget: "processGroup" };
-  } catch {
-    process.kill(pid, signal);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+    if (expectedIdentity) {
+      const fallbackProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(
+        pid,
+        expectedIdentity,
+        runtimePlatform,
+      );
+      if (!fallbackProof.valid) {
+        throw new Error(
+          `Run process identity changed before pid fallback: ${fallbackProof.status.replaceAll("_", " ")}`,
+        );
+      }
+    }
+    killProcess(pid, signal);
     return { signalTarget: "process" };
   }
 }

package/lib/runs-identity.ts

@@ -1,6 +1,6 @@
 /**
  * Async run identity helpers.
- * Owns run id normalization shared by run lifecycle and retention paths.
+ * Owns: run id normalization shared by run lifecycle and retention paths.
  */
 
 export function safeRunId(value: string | undefined): string {

package/lib/runs-index.ts

@@ -1,6 +1,6 @@
 /**
  * Async run state index.
- * Owns recursive run-state discovery, index rebuild/read, and status filtering.
+ * Owns: recursive run-state discovery, index rebuild/read, and status filtering.
  */
 
 import { existsSync, mkdirSync, readdirSync } from "node:fs";
@@ -30,27 +30,63 @@ function matchesStatusFilter(
   return status === filter;
 }
 
-export function listRunStateDirs(
+export interface RunStateDiscoveryIssue {
+  path: string;
+  reason: "depth_truncated" | "unreadable";
+}
+
+export interface RunStateDiscoveryResult {
+  issues: RunStateDiscoveryIssue[];
+  stateDirs: string[];
+}
+
+export function discoverRunStateDirs(
   stateRoot: string,
-  depth = 0,
-  seen = new Set<string>(),
-): string[] {
-  if (!existsSync(stateRoot) || seen.has(resolve(stateRoot))) return [];
-  seen.add(resolve(stateRoot));
-  let entries: import("node:fs").Dirent[];
-  try {
-    entries = readdirSync(stateRoot, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const result: string[] = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const child = join(stateRoot, entry.name);
-    if (existsSync(join(child, "run.json"))) result.push(child);
-    if (depth + 1 < 8) result.push(...listRunStateDirs(child, depth + 1, seen));
-  }
-  return result;
+  maxDepth = 8,
+): RunStateDiscoveryResult {
+  const issues: RunStateDiscoveryIssue[] = [];
+  const stateDirs: string[] = [];
+  const seen = new Set<string>();
+  const visit = (directory: string, depth: number): void => {
+    const canonical = resolve(directory);
+    if (!existsSync(directory) || seen.has(canonical)) return;
+    seen.add(canonical);
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(directory, { withFileTypes: true });
+    } catch {
+      issues.push({ path: directory, reason: "unreadable" });
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const child = join(directory, entry.name);
+      if (existsSync(join(child, "run.json"))) stateDirs.push(child);
+      if (depth + 1 < maxDepth) visit(child, depth + 1);
+      else {
+        try {
+          if (
+            readdirSync(child, { withFileTypes: true }).some((item) =>
+              item.isDirectory(),
+            )
+          ) {
+            issues.push({ path: child, reason: "depth_truncated" });
+          }
+        } catch {
+          issues.push({ path: child, reason: "unreadable" });
+        }
+      }
+    }
+  };
+  visit(stateRoot, 0);
+  return {
+    issues: issues.sort((left, right) => left.path.localeCompare(right.path)),
+    stateDirs: [...new Set(stateDirs)].sort(),
+  };
+}
+
+export function listRunStateDirs(stateRoot: string): string[] {
+  return discoverRunStateDirs(stateRoot).stateDirs;
 }
 
 function runIndexPath(stateRoot: string): string {

package/lib/runs-mailbox.ts

@@ -1,6 +1,6 @@
 /**
  * Async run mailbox state.
- * Owns durable run inbox records, claim locks, and handler status transitions.
+ * Owns: durable run inbox records, claim locks, and handler status transitions.
  */
 
 import { randomUUID } from "node:crypto";

package/lib/runs-messages.ts

@@ -1,6 +1,6 @@
 /**
  * Async run message delivery.
- * Owns run control endpoint resolution, inbox enqueueing, wake notification,
+ * Owns: run control endpoint resolution, inbox enqueueing, wake notification,
  * transport writes, and delivery receipts.
  */
 

package/lib/runs-outbox.ts

@@ -1,6 +1,6 @@
 /**
  * Async run outbox events.
- * Owns outbox event normalization, parsing, and append payload formatting.
+ * Owns: outbox event normalization, parsing, and append payload formatting.
  */
 
 export type RunOutboxDelivery = "log" | "notify" | "followup";

package/lib/runs-ownership.ts

@@ -1,6 +1,6 @@
 /**
  * Async run state-directory ownership.
- * Owns the marker proof required before launch and destructive retention.
+ * Owns: the marker proof required before launch and destructive retention.
  */
 
 import {

package/lib/runs-parent-teardown.ts

@@ -0,0 +1,257 @@
+/**
+ * Parent-session actor teardown.
+ * Owns: exact-owner running-run selection, kill revalidation, bounded outcomes, and partial-failure continuation.
+ */
+
+export interface ParentRunTeardownCandidate {
+  ownerId: string;
+  run: string;
+  runInstanceId?: string;
+  stateDir: string;
+}
+
+export type ParentRunTeardownOutcome =
+  | "killed"
+  | "skipped"
+  | "failed";
+
+export interface ParentRunTeardownAttempt extends ParentRunTeardownCandidate {
+  outcome: ParentRunTeardownOutcome;
+  reason?: string;
+}
+
+export interface ParentRunTeardownDiscoveryFailure {
+  path: string;
+  reason: string;
+}
+
+export interface ParentRunTeardownResult {
+  attempted: number;
+  discoveryFailed: number;
+  discoveryFailures: ParentRunTeardownDiscoveryFailure[];
+  failed: number;
+  killed: number;
+  skipped: number;
+  attempts: ParentRunTeardownAttempt[];
+}
+
+export interface ParentRunTeardownSummary extends ParentRunTeardownResult {
+  attemptsOmitted: number;
+  discoveryFailuresOmitted: number;
+  ownerId: string;
+  trigger: string;
+  ts: string;
+  version: 1;
+}
+
+const SUMMARY_ENTRY_LIMIT = 200;
+const SUMMARY_TEXT_LIMIT = 500;
+
+function boundedSummaryText(value: string): string {
+  return value.length > SUMMARY_TEXT_LIMIT
+    ? `${value.slice(0, SUMMARY_TEXT_LIMIT - 1)}…`
+    : value;
+}
+
+export function buildBoundedParentTeardownSummary(
+  result: ParentRunTeardownResult,
+  ownerId: string,
+  trigger: string,
+  ts: string,
+): ParentRunTeardownSummary {
+  const attempts = result.attempts.slice(0, SUMMARY_ENTRY_LIMIT).map((attempt) => ({
+    ownerId: boundedSummaryText(attempt.ownerId),
+    outcome: attempt.outcome,
+    ...(attempt.reason ? { reason: boundedSummaryText(attempt.reason) } : {}),
+    run: boundedSummaryText(attempt.run),
+    ...(attempt.runInstanceId
+      ? { runInstanceId: boundedSummaryText(attempt.runInstanceId) }
+      : {}),
+    stateDir: boundedSummaryText(attempt.stateDir),
+  }));
+  const discoveryFailures = result.discoveryFailures
+    .slice(0, SUMMARY_ENTRY_LIMIT)
+    .map((failure) => ({
+      path: boundedSummaryText(failure.path),
+      reason: boundedSummaryText(failure.reason),
+    }));
+  return {
+    attempted: result.attempted,
+    attempts,
+    attemptsOmitted: Math.max(0, result.attempts.length - attempts.length),
+    discoveryFailed: result.discoveryFailed,
+    discoveryFailures,
+    discoveryFailuresOmitted: Math.max(
+      0,
+      result.discoveryFailures.length - discoveryFailures.length,
+    ),
+    failed: result.failed,
+    killed: result.killed,
+    ownerId: boundedSummaryText(ownerId),
+    skipped: result.skipped,
+    trigger: boundedSummaryText(trigger),
+    ts: boundedSummaryText(ts),
+    version: 1,
+  };
+}
+
+export interface ParentRunTeardownDeps {
+  getRunStatus: (stateDir: string) => Record<string, unknown>;
+  killRun: (
+    stateDir: string,
+    expected: { ownerId: string; runInstanceId: string },
+  ) => Record<string, unknown>;
+  listRunStatuses: () =>
+    | Array<Record<string, unknown>>
+    | {
+        failures: ParentRunTeardownDiscoveryFailure[];
+        statuses: Array<Record<string, unknown>>;
+      };
+  recordAttempt: (attempt: ParentRunTeardownAttempt) => void;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function candidateFrom(
+  ownerId: string,
+  status: Record<string, unknown>,
+): ParentRunTeardownCandidate | undefined {
+  if (
+    status.ownerId !== ownerId ||
+    status.status !== "running" ||
+    typeof status.run !== "string" ||
+    typeof status.state_dir !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    ownerId,
+    run: status.run,
+    ...(typeof status.run_instance_id === "string"
+      ? { runInstanceId: status.run_instance_id }
+      : {}),
+    stateDir: status.state_dir,
+  };
+}
+
+export function selectParentRunTeardownCandidates(
+  ownerId: string | undefined,
+  statuses: Array<Record<string, unknown>>,
+): ParentRunTeardownCandidate[] {
+  if (!ownerId) return [];
+  const byStateDir = new Map<string, ParentRunTeardownCandidate>();
+  for (const status of statuses) {
+    const candidate = candidateFrom(ownerId, status);
+    if (candidate && !byStateDir.has(candidate.stateDir)) {
+      byStateDir.set(candidate.stateDir, candidate);
+    }
+  }
+  return [...byStateDir.values()].sort((left, right) =>
+    left.run.localeCompare(right.run),
+  );
+}
+
+function recordAttempt(
+  deps: ParentRunTeardownDeps,
+  attempt: ParentRunTeardownAttempt,
+): ParentRunTeardownAttempt {
+  try {
+    deps.recordAttempt(attempt);
+    return attempt;
+  } catch (error) {
+    return {
+      ...attempt,
+      outcome: "failed",
+      reason: `${attempt.reason ? `${attempt.reason}; ` : ""}evidence: ${errorMessage(error)}`,
+    };
+  }
+}
+
+export function teardownParentRuns(
+  ownerId: string | undefined,
+  deps: ParentRunTeardownDeps,
+): ParentRunTeardownResult {
+  let discovery: ReturnType<ParentRunTeardownDeps["listRunStatuses"]>;
+  try {
+    const listed = deps.listRunStatuses();
+    discovery = Array.isArray(listed)
+      ? { failures: [], statuses: listed }
+      : listed;
+  } catch (error) {
+    discovery = {
+      failures: [{ path: "<state-root>", reason: errorMessage(error) }],
+      statuses: [],
+    };
+  }
+  const candidates = selectParentRunTeardownCandidates(
+    ownerId,
+    discovery.statuses,
+  );
+  const attempts: ParentRunTeardownAttempt[] = [];
+  for (const candidate of candidates) {
+    let attempt: ParentRunTeardownAttempt;
+    try {
+      const current = deps.getRunStatus(candidate.stateDir);
+      if (!candidate.runInstanceId) {
+        attempt = {
+          ...candidate,
+          outcome: "failed",
+          reason: "run generation unavailable",
+        };
+      } else if (current.ownerId !== candidate.ownerId) {
+        attempt = {
+          ...candidate,
+          outcome: "skipped",
+          reason: "ownership changed",
+        };
+      } else if (current.run_instance_id !== candidate.runInstanceId) {
+        attempt = {
+          ...candidate,
+          outcome: "skipped",
+          reason: "run generation changed",
+        };
+      } else if (current.status !== "running") {
+        attempt = {
+          ...candidate,
+          outcome: "skipped",
+          reason: "already terminal",
+        };
+      } else {
+        const killed = deps.killRun(candidate.stateDir, {
+          ownerId: candidate.ownerId,
+          runInstanceId: candidate.runInstanceId,
+        });
+        attempt = killed.killed === true
+          ? { ...candidate, outcome: "killed" }
+          : {
+              ...candidate,
+              outcome: "failed",
+              reason:
+                typeof killed.reason === "string"
+                  ? killed.reason
+                  : "kill rejected",
+            };
+      }
+    } catch (error) {
+      attempt = {
+        ...candidate,
+        outcome: "failed",
+        reason: errorMessage(error),
+      };
+    }
+    attempts.push(recordAttempt(deps, attempt));
+  }
+  return {
+    attempted: candidates.length,
+    discoveryFailed: discovery.failures.length,
+    discoveryFailures: discovery.failures,
+    failed:
+      attempts.filter((attempt) => attempt.outcome === "failed").length +
+      discovery.failures.length,
+    killed: attempts.filter((attempt) => attempt.outcome === "killed").length,
+    skipped: attempts.filter((attempt) => attempt.outcome === "skipped").length,
+    attempts,
+  };
+}

package/lib/runs-process.ts

@@ -1,6 +1,6 @@
 /**
  * Async run process identity helpers.
- * Owns cross-platform liveness and stable runner process identity proofs.
+ * Owns: cross-platform liveness and stable runner process identity proofs.
  */
 
 import { spawnSync } from "node:child_process";

package/lib/runs-retention.ts

@@ -1,6 +1,6 @@
 /**
  * Async run retention operations.
- * Owns terminal-run archive and prune filesystem behavior.
+ * Owns: terminal-run archive and prune filesystem behavior.
  */
 
 import { createHash } from "node:crypto";

package/lib/runs-start.ts

@@ -1,28 +1,23 @@
 /**
  * Async run start guards.
- * Owns active-run reuse checks, start lock acquisition, and safe state-dir
+ * Owns: active-run reuse checks, start lock acquisition, and safe state-dir
  * preparation before a new runner process is spawned.
  */
 
-import {
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
+import { rmSync } from "node:fs";
 import { join } from "node:path";
 
+import {
+  acquireFileMutationLock,
+  type FileMutationLockOptions,
+} from "./file-state.ts";
 import {
   isAlive,
-  readProcessIdentity,
   verifyRunProcessIdentity,
   type RunProcessIdentity,
 } from "./runs-process.ts";
 
-const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
-
-export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 
 export function assertNoActiveRunState(
   stateDir: string,
@@ -55,62 +50,11 @@ export function assertNoActiveRunState(
   }
 }
 
-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);
-    writeStartLockOwner(lockDir);
-  } catch (error) {
-    try {
-      const stat = statSync(lockDir);
-      if (
-        Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS &&
-        isStartLockOwnerProvenDead(lockDir)
-      ) {
-        rmSync(lockDir, { recursive: true, force: true });
-        mkdirSync(lockDir);
-        writeStartLockOwner(lockDir, true);
-        return () => rmSync(lockDir, { recursive: true, force: true });
-      }
-    } catch {
-      // Keep the original lock acquisition error below.
-    }
-    throw new Error(
-      `Run state is already being started: ${stateDir}. Retry after the current start finishes.`,
-      { cause: error },
-    );
-  }
-  return () => rmSync(lockDir, { recursive: true, force: true });
+export function acquireStateStartLock(
+  stateDir: string,
+  options: FileMutationLockOptions = {},
+): () => void {
+  return acquireFileMutationLock(join(stateDir, ".lifecycle"), options);
 }
 
 export function prepareStateDirForStart(

package/lib/runs-status.ts

@@ -1,20 +1,26 @@
 /**
  * Async run status and log readers.
- * Owns status derivation from run state files plus bounded log/event tails.
+ * Owns: status derivation from run state files plus bounded log/event tails.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import type { AsyncRunStatus } from "./async-runs.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;
+export type AsyncRunStatus =
+  | "running"
+  | "done"
+  | "failed"
+  | "exited"
+  | "cancelled"
+  | "killed";
+
+type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 
 function getInterruptedRunStatus(
   stateDir: string,
@@ -35,7 +41,7 @@ export function buildRunStatus(
   meta: Record<string, unknown>,
   readJson: RunJsonReader,
   _runnerPath: string,
-  runnerIdentityGraceMs: number,
+  _runnerIdentityGraceMs: number,
 ): Record<string, unknown> {
   const result = readJson(join(stateDir, "result.json"));
   const pid = Number(meta.pid || 0);
@@ -45,9 +51,7 @@ export function buildRunStatus(
   );
   const aliveOwnedRunner = Boolean(
     pid &&
-      (processIdentity.valid ||
-        (processIdentity.status === "unsupported_proof" &&
-          isWithinRunnerIdentityGrace(meta, runnerIdentityGraceMs))),
+      (processIdentity.valid || processIdentity.status === "unsupported_proof"),
   );
   const status: AsyncRunStatus = result
     ? Number(result.code ?? 0) === 0