@llblab/pi-actors 0.41.1 → 0.42.0

package/dist/lib/runs-index.js

@@ -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";
 import { join, resolve } from "node:path";
@@ -14,28 +14,51 @@ function matchesStatusFilter(status, filter) {
         return status !== "running";
     return status === filter;
 }
-export function listRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
-    if (!existsSync(stateRoot) || seen.has(resolve(stateRoot)))
-        return [];
-    seen.add(resolve(stateRoot));
-    let entries;
-    try {
-        entries = readdirSync(stateRoot, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const result = [];
-    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;
+export function discoverRunStateDirs(stateRoot, maxDepth = 8) {
+    const issues = [];
+    const stateDirs = [];
+    const seen = new Set();
+    const visit = (directory, depth) => {
+        const canonical = resolve(directory);
+        if (!existsSync(directory) || seen.has(canonical))
+            return;
+        seen.add(canonical);
+        let entries;
+        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) {
+    return discoverRunStateDirs(stateRoot).stateDirs;
 }
 function runIndexPath(stateRoot) {
     return join(stateRoot, "index.json");

package/dist/lib/runs-mailbox.d.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.
  */
 export type RunInboxStatus = "queued" | "sent" | "claimed" | "handled" | "failed";
 export type RunInboxMessage = Record<string, unknown> & {

package/dist/lib/runs-mailbox.js

@@ -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";
 import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";

package/dist/lib/runs-messages.d.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.
  */
 export interface RunControlEndpoint {

package/dist/lib/runs-messages.js

@@ -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.
  */
 import { closeSync, constants, existsSync, openSync, statSync, writeFileSync, writeSync, } from "node:fs";

package/dist/lib/runs-outbox.d.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";
 export type RunOutboxLevel = "info" | "warning" | "error";

package/dist/lib/runs-outbox.js

@@ -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 function normalizeRunOutboxDelivery(value) {
     return value === "notify" || value === "followup" ? value : "log";

package/dist/lib/runs-ownership.d.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.
  */
 export declare const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
 export declare function claimRunStateDirectory(stateDir: string, run: string): string;

package/dist/lib/runs-ownership.js

@@ -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 { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, } from "node:fs";
 import { randomUUID } from "node:crypto";

package/dist/lib/runs-parent-teardown.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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;
+}
+export declare function buildBoundedParentTeardownSummary(result: ParentRunTeardownResult, ownerId: string, trigger: string, ts: string): ParentRunTeardownSummary;
+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;
+}
+export declare function selectParentRunTeardownCandidates(ownerId: string | undefined, statuses: Array<Record<string, unknown>>): ParentRunTeardownCandidate[];
+export declare function teardownParentRuns(ownerId: string | undefined, deps: ParentRunTeardownDeps): ParentRunTeardownResult;

package/dist/lib/runs-parent-teardown.js

@@ -0,0 +1,172 @@
+/**
+ * Parent-session actor teardown.
+ * Owns: exact-owner running-run selection, kill revalidation, bounded outcomes, and partial-failure continuation.
+ */
+const SUMMARY_ENTRY_LIMIT = 200;
+const SUMMARY_TEXT_LIMIT = 500;
+function boundedSummaryText(value) {
+    return value.length > SUMMARY_TEXT_LIMIT
+        ? `${value.slice(0, SUMMARY_TEXT_LIMIT - 1)}…`
+        : value;
+}
+export function buildBoundedParentTeardownSummary(result, ownerId, trigger, ts) {
+    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,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function candidateFrom(ownerId, status) {
+    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, statuses) {
+    if (!ownerId)
+        return [];
+    const byStateDir = new Map();
+    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, attempt) {
+    try {
+        deps.recordAttempt(attempt);
+        return attempt;
+    }
+    catch (error) {
+        return {
+            ...attempt,
+            outcome: "failed",
+            reason: `${attempt.reason ? `${attempt.reason}; ` : ""}evidence: ${errorMessage(error)}`,
+        };
+    }
+}
+export function teardownParentRuns(ownerId, deps) {
+    let discovery;
+    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 = [];
+    for (const candidate of candidates) {
+        let attempt;
+        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/dist/lib/runs-process.d.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.
  */
 export interface RunProcessIdentity {
     command: string;

package/dist/lib/runs-process.js

@@ -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";
 import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";

package/dist/lib/runs-retention.d.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 { cpSync } from "node:fs";
 export declare function archiveTerminalRun(status: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/runs-retention.js

@@ -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";
 import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";

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

@@ -1,9 +1,11 @@
 /**
  * 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.
  */
-export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+import { type FileMutationLockOptions } from "./file-state.ts";
+type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 export declare function assertNoActiveRunState(stateDir: string, readJson: RunJsonReader, _runnerPath: string): void;
-export declare function acquireStateStartLock(stateDir: string): () => void;
+export declare function acquireStateStartLock(stateDir: string, options?: FileMutationLockOptions): () => void;
 export declare function prepareStateDirForStart(stateDir: string, readJson: RunJsonReader, _runnerPath: string): void;
+export {};

package/dist/lib/runs-start.js

@@ -1,12 +1,12 @@
 /**
  * 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 { isAlive, readProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
-const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+import { acquireFileMutationLock, } from "./file-state.js";
+import { isAlive, verifyRunProcessIdentity, } from "./runs-process.js";
 export function assertNoActiveRunState(stateDir, readJson, _runnerPath) {
     const meta = readJson(join(stateDir, "run.json"));
     if (!meta)
@@ -26,50 +26,8 @@ export function assertNoActiveRunState(stateDir, readJson, _runnerPath) {
         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, recovered = false) {
-    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) {
-    try {
-        const owner = JSON.parse(readFileSync(join(lockDir, "owner.json"), "utf8"));
-        const pid = Number(owner.pid || 0);
-        if (!pid)
-            return false;
-        return verifyRunProcessIdentity(pid, owner.process_identity).status === "dead_pid";
-    }
-    catch {
-        return false;
-    }
-}
-export function acquireStateStartLock(stateDir) {
-    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, options = {}) {
+    return acquireFileMutationLock(join(stateDir, ".lifecycle"), options);
 }
 export function prepareStateDirForStart(stateDir, readJson, _runnerPath) {
     const existing = readJson(join(stateDir, "run.json"));

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

@@ -1,8 +1,10 @@
 /**
  * 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.
  */
-export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
-export declare function buildRunStatus(stateDir: string, runOrDir: string, meta: Record<string, unknown>, readJson: RunJsonReader, _runnerPath: string, runnerIdentityGraceMs: number): Record<string, unknown>;
+export type AsyncRunStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
+type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+export declare function buildRunStatus(stateDir: string, runOrDir: string, meta: Record<string, unknown>, readJson: RunJsonReader, _runnerPath: string, _runnerIdentityGraceMs: number): Record<string, unknown>;
 export declare function tailFile(path: string, lines: number): string;
 export declare function tailLines(path: string, lines: number): string[];
+export {};

package/dist/lib/runs-status.js

@@ -1,10 +1,10 @@
 /**
  * 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 { isWithinRunnerIdentityGrace, verifyRunProcessIdentity, } from "./runs-process.js";
+import { verifyRunProcessIdentity, } from "./runs-process.js";
 import { readJsonlFileResilient } from "./state-readers.js";
 function getInterruptedRunStatus(stateDir) {
     const events = readJsonlFileResilient(join(stateDir, "events.jsonl")).records.slice(-200);
@@ -16,14 +16,12 @@ function getInterruptedRunStatus(stateDir) {
     }
     return undefined;
 }
-export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath, runnerIdentityGraceMs) {
+export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath, _runnerIdentityGraceMs) {
     const result = readJson(join(stateDir, "result.json"));
     const pid = Number(meta.pid || 0);
     const processIdentity = verifyRunProcessIdentity(pid, meta.process_identity);
     const aliveOwnedRunner = Boolean(pid &&
-        (processIdentity.valid ||
-            (processIdentity.status === "unsupported_proof" &&
-                isWithinRunnerIdentityGrace(meta, runnerIdentityGraceMs))));
+        (processIdentity.valid || processIdentity.status === "unsupported_proof"));
     const status = result
         ? Number(result.code ?? 0) === 0
             ? "done"

package/dist/lib/runtime.d.ts

@@ -3,6 +3,7 @@
  * Zones: runtime coordination, registry loading, pi tools
  * Owns persisted tool loading, reserved-name guards, runtime registration, and warning notification
  */
+import { watch } from "node:fs";
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
 import * as ToolsLocal from "./tools-local.ts";
@@ -34,4 +35,9 @@ export interface RecipeToolReloadWatcher {
     watch(ctx: RuntimeContext): void;
 }
 export declare function createAutoToolsRuntime(deps: ToolRegistryRuntimeDeps): ToolRegistryRuntime;
-export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools">): RecipeToolReloadWatcher;
+export interface RecipeToolReloadWatcherDeps {
+    exists?: (path: string) => boolean;
+    recipeRoot?: string;
+    watchPath?: typeof watch;
+}
+export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools">, deps?: RecipeToolReloadWatcherDeps): RecipeToolReloadWatcher;