@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/runs-controls.js

@@ -0,0 +1,283 @@
+/**
+ * Run Control journal.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import * as Control from "./control.js";
+import { acquireFileMutationLock, writeTextAtomic } from "./file-state.js";
+import * as Limits from "./limits.js";
+import { classifyRunControlRecord, computeRunControlCapacity, decideRunControlAdmission, runControlStatusTimestamp, } from "./run-evidence-policy.js";
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.js";
+function admissionError(details) {
+    return Object.assign(new Error(details.reason === "control_backpressure"
+        ? `Run Control admission backpressured: pending=${details.pending}/${details.limit}`
+        : `Run Control journal integrity failed: ${details.integrity_reason ?? "unknown"}`), details);
+}
+const STATUSES = new Set([
+    "queued", "delivered", "claimed", "handled", "failed",
+]);
+export function runControlsFile(stateDir) {
+    return join(stateDir, "controls.jsonl");
+}
+export function readRunControlJournalFromStateDir(stateDir) {
+    const path = runControlsFile(stateDir);
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { diagnostics: [], records: [] };
+        return { diagnostics: [{ message: String(error), path }], records: [] };
+    }
+    try {
+        const bytes = fstatSync(fd).size;
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+            return { diagnostics: [{ message: "Run Control journal exceeds bounded read limit", path }], records: [] };
+        }
+        const buffer = Buffer.allocUnsafe(bytes);
+        let consumed = 0;
+        while (consumed < bytes) {
+            const count = readSync(fd, buffer, consumed, bytes - consumed, consumed);
+            if (count === 0)
+                return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+            consumed += count;
+        }
+        if (fstatSync(fd).size !== bytes)
+            return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+        const records = [];
+        const diagnostics = [];
+        for (const [index, line] of buffer.toString("utf8").split("\n").entries()) {
+            if (!line.trim())
+                continue;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch (error) {
+                diagnostics.push({ line: index + 1, message: String(error), path });
+            }
+        }
+        return { diagnostics, records };
+    }
+    catch (error) {
+        return { diagnostics: [{ message: String(error), path }], records: [] };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readRunControlsFromStateDir(stateDir) {
+    return readRunControlJournalFromStateDir(stateDir).records;
+}
+function acquireRunControlsLock(stateDir) {
+    return acquireFileMutationLock(runControlsFile(stateDir));
+}
+function compactRunControls(records) {
+    const active = records.filter((record) => classifyRunControlRecord(record) !== "terminal");
+    const terminal = records.filter((record) => classifyRunControlRecord(record) === "terminal")
+        .slice(-Limits.RUN_CONTROL_TERMINAL_LIMIT);
+    const retained = new Set([...active, ...terminal]);
+    return records.filter((record) => retained.has(record)).map((record) => typeof record.error === "string" && Buffer.byteLength(record.error) > Limits.RUN_CONTROL_ERROR_MAX_BYTES
+        ? { ...record, error: boundedControlError(record.error) } : record);
+}
+function encodeRunControls(records) {
+    return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
+}
+function boundedControlError(value) {
+    if (Buffer.byteLength(value) <= Limits.RUN_CONTROL_ERROR_MAX_BYTES)
+        return value;
+    const suffix = "… [truncated]";
+    const limit = Limits.RUN_CONTROL_ERROR_MAX_BYTES - Buffer.byteLength(suffix);
+    const bytes = Buffer.from(value);
+    let end = limit;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return `${bytes.subarray(0, end).toString("utf8")}${suffix}`;
+}
+function writeRunControls(stateDir, records) {
+    const encoded = encodeRunControls(compactRunControls(records));
+    if (Buffer.byteLength(encoded) > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+        throw new Error("Run Control journal transition exceeds bounded byte limit");
+    }
+    writeTextAtomic(runControlsFile(stateDir), encoded);
+}
+function readMutableRunControls(stateDir, runInstanceId) {
+    const journal = readRunControlJournalFromStateDir(stateDir);
+    if (journal.diagnostics.length)
+        return undefined;
+    const records = journal.records;
+    if (runInstanceId && records.some((record) => controlIntegrity(record, runInstanceId) !== "valid"))
+        return undefined;
+    return records;
+}
+function controlIntegrity(value, runInstanceId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "invalid_record";
+    const record = value;
+    if (typeof record.id !== "string" || !record.id ||
+        typeof record.run_instance_id !== "string" || !record.run_instance_id ||
+        typeof record.status !== "string" || !STATUSES.has(record.status) ||
+        (record.error !== undefined && typeof record.error !== "string"))
+        return "invalid_record";
+    try {
+        Control.normalizeControlAction(record.action);
+        if (record.input !== undefined)
+            Control.normalizeControlInput(record.input);
+    }
+    catch {
+        return "invalid_record";
+    }
+    const timestamp = runControlStatusTimestamp(record, record.status);
+    if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp)))
+        return "invalid_status_timestamp";
+    if (classifyRunControlRecord(record) === "pending" &&
+        record.run_instance_id !== runInstanceId)
+        return "generation_mismatch";
+    return "valid";
+}
+export function appendRunControlInStateDir(stateDir, request) {
+    const action = Control.normalizeControlAction(request.action);
+    const input = request.input === undefined ? undefined : Control.normalizeControlInput(request.input);
+    const record = {
+        id: randomUUID(),
+        run_instance_id: request.run_instance_id,
+        action,
+        ...(input !== undefined ? { input } : {}),
+        status: "queued",
+        queued_at: new Date().toISOString(),
+    };
+    const encodedRecordBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`);
+    const releaseLock = acquireRunControlsLock(stateDir);
+    try {
+        const path = runControlsFile(stateDir);
+        let bytes = 0;
+        try {
+            bytes = statSync(path).size;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                bytes = Number.MAX_SAFE_INTEGER;
+        }
+        const journal = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+            ? { diagnostics: [], records: [] } : readRunControlJournalFromStateDir(stateDir);
+        let integrity = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+            ? "journal_bytes"
+            : journal.diagnostics.some((item) => item.line !== undefined)
+                ? "malformed"
+                : journal.diagnostics.length ? "unreadable" : "valid";
+        for (const value of journal.records) {
+            if (integrity !== "valid")
+                break;
+            integrity = controlIntegrity(value, request.run_instance_id);
+        }
+        const records = journal.records;
+        const retained = encodeRunControls(compactRunControls(records));
+        const decision = decideRunControlAdmission({
+            integrity,
+            journalBytes: bytes,
+            newRecordBytes: encodedRecordBytes,
+            records,
+            retainedJournalBytes: Buffer.byteLength(retained),
+            runInstanceId: request.run_instance_id,
+            capacity: computeRunControlCapacity(records),
+        });
+        if (!decision.admitted)
+            throw admissionError(decision.error);
+        writeTextAtomic(path, `${retained}${JSON.stringify(record)}\n`);
+        return record;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metadata = {}, expectedStatuses) {
+    const releaseLock = acquireRunControlsLock(stateDir);
+    try {
+        const records = readMutableRunControls(stateDir);
+        if (!records)
+            return false;
+        const index = records.findIndex((record) => record.id === id);
+        if (index < 0)
+            return false;
+        const record = records[index];
+        if (records.some((value) => controlIntegrity(value, record.run_instance_id) !== "valid"))
+            return false;
+        if (expectedStatuses && !expectedStatuses.includes(record.status))
+            return false;
+        if (record.status === nextStatus)
+            return false;
+        const timestamp = new Date().toISOString();
+        if (nextStatus === "delivered") {
+            if (record.delivered_at)
+                return false;
+            records[index] = { ...record, delivered_at: timestamp,
+                ...(record.status === "queued" ? { status: "delivered" } : {}) };
+        }
+        else {
+            if (classifyRunControlRecord(record) === "terminal" || nextStatus === "queued")
+                return false;
+            if ((nextStatus === "claimed" && record.status !== "queued" &&
+                record.status !== "delivered") ||
+                (nextStatus === "handled" && record.status !== "claimed"))
+                return false;
+            records[index] = { ...record,
+                ...(metadata.error !== undefined ? { error: boundedControlError(metadata.error) } : {}),
+                [`${nextStatus}_at`]: timestamp, status: nextStatus };
+        }
+        writeRunControls(stateDir, records);
+        return true;
+    }
+    finally {
+        releaseLock();
+    }
+}
+function claimRunControl(stateDir, runInstanceId, controlId) {
+    const releaseLock = acquireRunControlsLock(stateDir);
+    try {
+        const records = readMutableRunControls(stateDir, runInstanceId);
+        if (!records)
+            return undefined;
+        const index = records.findIndex((record) => (controlId === undefined || record.id === controlId) &&
+            record.run_instance_id === runInstanceId &&
+            (record.status === "queued" || record.status === "delivered"));
+        if (index < 0)
+            return undefined;
+        const claimed = {
+            ...records[index], claimed_at: new Date().toISOString(), status: "claimed"
+        };
+        records[index] = claimed;
+        writeRunControls(stateDir, records);
+        return claimed;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function claimRunControlInStateDir(stateDir, runInstanceId) {
+    return claimRunControl(stateDir, runInstanceId);
+}
+export function claimRunControlByIdInStateDir(stateDir, runInstanceId, controlId) {
+    return claimRunControl(stateDir, runInstanceId, controlId);
+}
+export async function processRunControlsInStateDir(stateDir, runInstanceId, handler, limit = 1) {
+    const result = { claimed: 0, failed: 0, handled: 0 };
+    for (let index = 0; index < Math.max(1, limit); index += 1) {
+        const control = claimRunControlInStateDir(stateDir, runInstanceId);
+        if (!control)
+            break;
+        result.claimed += 1;
+        try {
+            await handler(control);
+            if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"]))
+                result.handled += 1;
+        }
+        catch (error) {
+            if (updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: error instanceof Error ? error.message : String(error) }, ["claimed"]))
+                result.failed += 1;
+        }
+    }
+    return result;
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-identity.d.ts

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

package/node_modules/@llblab/pi-actors/dist/lib/runs-identity.js

@@ -0,0 +1,11 @@
+/**
+ * Async run identity helpers.
+ * Owns: run id normalization shared by run lifecycle and retention paths.
+ */
+export function safeRunId(value) {
+    const run = (value || `run-${Date.now()}`).trim();
+    if (!/^[A-Za-z0-9_.-]+$/.test(run)) {
+        throw new Error("Run id may contain only letters, numbers, dot, underscore, and dash.");
+    }
+    return run;
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Async run state index.
+ * Owns: recursive run-state discovery, index rebuild/read, and status filtering.
+ */
+export interface RunStateIndexEntry {
+    ownerId?: string;
+    recipe?: string;
+    run: string;
+    state_dir: string;
+    status: string;
+    tool?: string;
+    updated_at?: string;
+}
+export type RunStatusReader = (runOrDir: string) => Record<string, unknown>;
+export interface RunStateDiscoveryIssue {
+    path: string;
+    reason: "depth_truncated" | "unreadable";
+}
+export interface RunStateDiscoveryResult {
+    issues: RunStateDiscoveryIssue[];
+    stateDirs: string[];
+}
+export declare function discoverRunStateDirs(stateRoot: string, maxDepth?: number): RunStateDiscoveryResult;
+export declare function listRunStateDirs(stateRoot: string): string[];
+export declare function rebuildRunStateIndex(stateRoot: string, getRunStatus: RunStatusReader): RunStateIndexEntry[];
+export declare function readRunStateIndex(stateRoot: string, readJson: (path: string) => Record<string, unknown> | undefined): RunStateIndexEntry[] | undefined;
+export declare function listRuns(stateRoot: string, getRunStatus: RunStatusReader, readJson: (path: string) => Record<string, unknown> | undefined, statusFilter?: string): Array<Record<string, unknown>>;

package/node_modules/@llblab/pi-actors/dist/lib/runs-index.js

@@ -0,0 +1,142 @@
+/**
+ * Async run state index.
+ * Owns: recursive run-state discovery, index rebuild/read, and status filtering.
+ */
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { writeJsonAtomic } from "./file-state.js";
+function matchesStatusFilter(status, filter) {
+    if (!filter || filter === "all")
+        return true;
+    if (filter === "active")
+        return status === "running";
+    if (filter === "terminal")
+        return status !== "running";
+    return status === filter;
+}
+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");
+}
+function indexEntryFromStatus(status) {
+    const progress = status.progress && typeof status.progress === "object"
+        ? status.progress
+        : {};
+    return {
+        ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
+        ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
+        run: String(status.run),
+        state_dir: String(status.state_dir),
+        status: String(status.status),
+        ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
+        updated_at: typeof progress.updatedAt === "string"
+            ? progress.updatedAt
+            : typeof status.createdAt === "string"
+                ? status.createdAt
+                : new Date(0).toISOString(),
+    };
+}
+export function rebuildRunStateIndex(stateRoot, getRunStatus) {
+    mkdirSync(stateRoot, { recursive: true });
+    const entries = listRunStateDirs(stateRoot)
+        .flatMap((stateDir) => {
+        try {
+            return [indexEntryFromStatus(getRunStatus(stateDir))];
+        }
+        catch {
+            return [];
+        }
+    })
+        .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+    writeJsonAtomic(runIndexPath(stateRoot), {
+        entries,
+        rebuilt_at: new Date().toISOString(),
+    });
+    return entries;
+}
+export function readRunStateIndex(stateRoot, readJson) {
+    const index = readJson(runIndexPath(stateRoot));
+    if (!index || typeof index !== "object")
+        return undefined;
+    const entries = index.entries;
+    if (!Array.isArray(entries))
+        return undefined;
+    const valid = entries.filter((entry) => {
+        const record = entry && typeof entry === "object"
+            ? entry
+            : {};
+        return (typeof record.run === "string" &&
+            typeof record.state_dir === "string" &&
+            typeof record.status === "string");
+    });
+    if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
+        return undefined;
+    const indexedDirs = new Set(valid.map((entry) => resolve(entry.state_dir)));
+    const stateDirs = listRunStateDirs(stateRoot).map((stateDir) => resolve(stateDir));
+    if (stateDirs.some((stateDir) => !indexedDirs.has(stateDir)))
+        return undefined;
+    return valid;
+}
+function compactIndexEntry(entry) {
+    return {
+        run: entry.run,
+        state_dir: entry.state_dir,
+        status: entry.status,
+        ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(entry.recipe ? { recipe: entry.recipe } : {}),
+    };
+}
+export function listRuns(stateRoot, getRunStatus, readJson, statusFilter) {
+    if (!existsSync(stateRoot))
+        return [];
+    const indexed = readRunStateIndex(stateRoot, readJson);
+    const entries = indexed ?? rebuildRunStateIndex(stateRoot, getRunStatus);
+    return entries
+        .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+        .map(compactIndexEntry);
+}

package/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/dist/lib/runs-ownership.js

@@ -0,0 +1,96 @@
+/**
+ * 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 { tmpdir } from "node:os";
+import { isAbsolute, join, relative, 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 isSystemTempRootAlias(resolved, canonical) {
+    const tempRoot = resolve(tmpdir());
+    const relativeStateDir = relative(tempRoot, resolved);
+    if (relativeStateDir === ".." ||
+        relativeStateDir.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) ||
+        isAbsolute(relativeStateDir)) {
+        return false;
+    }
+    const canonicalTempRoot = realpathSync.native(tempRoot);
+    const expectedCanonical = resolve(canonicalTempRoot, relativeStateDir);
+    return comparablePath(canonical) === comparablePath(expectedCanonical);
+}
+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.native(resolved);
+    if (comparablePath(canonical) !== comparablePath(resolved) &&
+        !isSystemTempRootAlias(resolved, canonical)) {
+        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/node_modules/@llblab/pi-actors/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;