@llblab/pi-actors 0.41.0 → 0.42.0

package/dist/lib/review-diagnostics.js

@@ -0,0 +1,148 @@
+/**
+ * Automatic recipe-review diagnostics.
+ * Zones: bounded draft/tool cycle evidence, lineage summaries, revision snapshot inventory
+ * Owns read-only diagnostic projection; schedulers and transactions own mutation.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import * as Paths from "./paths.js";
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_ENTRIES = 100;
+function readJson(path) {
+    if (!path || !existsSync(path) || statSync(path).size > MAX_FILE_BYTES)
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function text(value, limit = 240) {
+    if (typeof value !== "string")
+        return undefined;
+    return value.length > limit ? `${value.slice(0, limit - 1)}…` : value;
+}
+function strings(value, limit = 20) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string").slice(-limit)
+        : [];
+}
+function cycleState(state) {
+    if (!state)
+        return { phase: "idle" };
+    return {
+        phase: text(state.phase) ?? "unknown",
+        attempts: state.attempts,
+        failed_stage: text(state.failedStage),
+        last_error: text(state.lastError, 500),
+        next_action: text(state.nextAction, 500),
+        processing_attempts: state.processingAttempts,
+        batch_id: text(state.batchId),
+        review_id: text(state.reviewId),
+        run_id: text(state.runId),
+        sources: Array.isArray(state.sourcePaths) ? state.sourcePaths.length : undefined,
+        tools: Array.isArray(state.toolNames) ? state.toolNames.length : undefined,
+        updated_at: text(state.updatedAt),
+    };
+}
+function draftEvidence(state) {
+    const evidence = readJson(text(state?.evidencePath, 4096));
+    if (!evidence)
+        return undefined;
+    const decisions = Array.isArray(evidence.decisions)
+        ? evidence.decisions
+        : [];
+    const garbage = evidence.garbageCollection;
+    return {
+        actions: Object.fromEntries(["promote", "discard"].map((action) => [
+            action,
+            decisions.filter((decision) => decision.action === action).length,
+        ])),
+        garbage_collection: garbage
+            ? { reviewed_sources: garbage.reviewedSources, status: garbage.status }
+            : undefined,
+        reviewed_sources: decisions.length,
+    };
+}
+function toolEvidence(state) {
+    const approved = readJson(text(state?.approvedPath, 4096));
+    if (!approved)
+        return undefined;
+    const decisions = Array.isArray(approved.decisions)
+        ? approved.decisions
+        : [];
+    return {
+        actions: Object.fromEntries(["keep", "evolve", "replace", "demote", "merge", "split"].map((action) => [
+            action,
+            decisions.filter((decision) => decision.action === action).length,
+        ])),
+        lineage_phase: readJson(text(state?.lineageJournalPath, 4096))?.phase,
+        review_id: text(approved.reviewId),
+        sources: Array.isArray(approved.sources) ? approved.sources.length : 0,
+        targets: Array.isArray(approved.targets) ? approved.targets.length : 0,
+        transaction_phase: readJson(join(dirname(text(state?.approvedPath, 4096)), "journal.json"))?.phase,
+    };
+}
+function lineageSummaries(recipeRoot) {
+    const root = join(recipeRoot, ".usage", "recipes");
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => join(root, entry.name))
+        .sort()
+        .slice(0, MAX_ENTRIES)
+        .flatMap((path) => {
+        const record = readJson(path);
+        if (!record)
+            return [];
+        return [{
+                current_path: text(record.current_path),
+                demoted_at: text(record.demoted_at),
+                demoted_from_revision: record.demoted_from_revision,
+                lifetime_calls: record.lifetime_calls,
+                name: text(record.lineage_name) ?? basename(path, ".json"),
+                review_epochs: strings(record.review_epochs, 5),
+                revision: record.revision,
+                revision_calls: record.revision_calls,
+                rollback_of_revision: record.rollback_of_revision,
+            }];
+    });
+}
+function snapshotCount(recipeRoot) {
+    const root = join(recipeRoot, ".usage", "revisions");
+    if (!existsSync(root))
+        return 0;
+    let count = 0;
+    for (const lineage of readdirSync(root, { withFileTypes: true }).slice(0, MAX_ENTRIES)) {
+        if (!lineage.isDirectory())
+            continue;
+        count += readdirSync(join(root, lineage.name), { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .length;
+    }
+    return count;
+}
+export function readAutomaticReviewDiagnostics(options = {}) {
+    const recipeRoot = options.recipeRoot ?? Paths.getRecipeRoot();
+    const draftState = readJson(options.draftStatePath ?? Paths.getDraftSleepStatePath());
+    const toolState = readJson(options.toolStatePath ?? Paths.getToolReviewStatePath());
+    const lineages = lineageSummaries(recipeRoot);
+    return {
+        draft_review: {
+            ...cycleState(draftState),
+            evidence: draftEvidence(draftState),
+        },
+        lineage_count: lineages.length,
+        lineages,
+        revision_snapshots: snapshotCount(recipeRoot),
+        tool_review: {
+            ...cycleState(toolState),
+            evidence: toolEvidence(toolState),
+        },
+    };
+}

package/dist/lib/review-projection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Automatic recipe-review confidentiality projection.
+ * Owns: value-free model inputs derived from trusted immutable draft/tool captures.
+ */
+import type { DraftReviewInput, DraftReviewResult } from "./draft-review.ts";
+import type { ToolReviewInput, ToolReviewResult } from "./tool-review.ts";
+export declare const draftReviewIdentity: (index: number) => string;
+export declare const toolReviewIdentity: (index: number) => string;
+export declare function draftReviewRevision(input: DraftReviewInput, index: number): string;
+export declare function toolReviewRevision(input: ToolReviewInput, index: number): string;
+export declare function projectDraftReviewInput(input: DraftReviewInput): Record<string, unknown>;
+export declare function restoreDraftReviewResult(input: DraftReviewInput, result: DraftReviewResult): DraftReviewResult;
+export declare function projectToolReviewInput(input: ToolReviewInput): Record<string, unknown>;
+export declare function restoreToolReviewResult(input: ToolReviewInput, result: ToolReviewResult): ToolReviewResult;

package/dist/lib/review-projection.js

@@ -0,0 +1,170 @@
+/**
+ * Automatic recipe-review confidentiality projection.
+ * Owns: value-free model inputs derived from trusted immutable draft/tool captures.
+ */
+function occurrenceId(prefix, index) {
+    return `${prefix}_${String(index + 1).padStart(2, "0")}`;
+}
+export const draftReviewIdentity = (index) => occurrenceId("draft", index);
+export const toolReviewIdentity = (index) => occurrenceId("tool", index);
+function contentGroups(hashes) {
+    const groups = new Map();
+    return hashes.map((hash) => {
+        let group = groups.get(hash);
+        if (!group) {
+            group = occurrenceId("content_group", groups.size);
+            groups.set(hash, group);
+        }
+        return group;
+    });
+}
+function draftContentGroups(input) {
+    return contentGroups([
+        ...input.activeTools.map((tool) => tool.sha256),
+        ...input.drafts.map((draft) => draft.sha256),
+    ]);
+}
+export function draftReviewRevision(input, index) {
+    return draftContentGroups(input)[input.activeTools.length + index];
+}
+export function toolReviewRevision(input, index) {
+    return contentGroups(input.tools.map((tool) => tool.sha256))[index];
+}
+function countArray(value) {
+    return Array.isArray(value) ? value.length : 0;
+}
+function countRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? Object.keys(value).length
+        : 0;
+}
+function templateShape(value) {
+    if (typeof value === "string")
+        return { kind: "command", nodes: 1 };
+    if (Array.isArray(value)) {
+        return {
+            branches: value.length,
+            kind: "sequence",
+            nodes: 1 + value.reduce((total, child) => total + Number(templateShape(child).nodes ?? 0), 0),
+        };
+    }
+    if (!value || typeof value !== "object")
+        return { kind: "invalid", nodes: 0 };
+    const record = value;
+    const children = Array.isArray(record.template)
+        ? record.template
+        : record.template === undefined
+            ? []
+            : [record.template];
+    return {
+        branches: children.length,
+        conditional: record.when !== undefined,
+        kind: record.parallel === true ? "parallel" : "object",
+        repeat: record.repeat !== undefined,
+        retry: record.retry !== undefined,
+        nodes: 1 + children.reduce((total, child) => total + Number(templateShape(child).nodes ?? 0), 0),
+    };
+}
+function contractShape(recipe) {
+    if (!recipe)
+        return undefined;
+    const mailbox = recipe.mailbox && typeof recipe.mailbox === "object" && !Array.isArray(recipe.mailbox)
+        ? recipe.mailbox
+        : {};
+    return {
+        argument_count: countArray(recipe.args),
+        artifact_count: countRecord(recipe.artifacts),
+        async: recipe.async === true,
+        default_count: countRecord(recipe.defaults),
+        import_count: countRecord(recipe.imports),
+        mailbox_accepts_count: countArray(mailbox.accepts),
+        mailbox_emits_count: countArray(mailbox.emits),
+        template_shape: templateShape(recipe.template),
+    };
+}
+function usageShape(usage) {
+    const numeric = (key) => {
+        const value = usage?.[key];
+        return typeof value === "number" && Number.isFinite(value) && value >= 0
+            ? value
+            : 0;
+    };
+    return {
+        lifetime_calls: numeric("lifetime_calls") || numeric("calls"),
+        revision: numeric("revision"),
+        revision_calls: numeric("revision_calls"),
+    };
+}
+export function projectDraftReviewInput(input) {
+    return {
+        activeTools: input.activeTools.map((_tool, index) => ({
+            name: occurrenceId("active_tool", index),
+            sha256: draftContentGroups(input)[index],
+        })),
+        batchId: input.batchId,
+        createdAt: input.createdAt,
+        drafts: input.drafts.map((draft, index) => ({
+            contract: contractShape(draft.recipe),
+            draft: draftReviewIdentity(index),
+            riskLabels: [...draft.riskLabels],
+            sha256: draftReviewRevision(input, index),
+            usage: usageShape(draft.usage),
+            valid: draft.valid,
+        })),
+    };
+}
+export function restoreDraftReviewResult(input, result) {
+    const drafts = new Map(input.drafts.map((draft, index) => [draftReviewIdentity(index), {
+            draft,
+            revision: draftReviewRevision(input, index),
+        }]));
+    return {
+        ...result,
+        decisions: result.decisions.map((decision) => {
+            const captured = drafts.get(decision.draft);
+            return {
+                ...decision,
+                draft: captured?.draft.path ?? `unknown:${decision.draft}`,
+                sha256: captured && decision.sha256 === captured.revision
+                    ? captured.draft.sha256
+                    : `invalid:${decision.sha256}`,
+            };
+        }),
+    };
+}
+export function projectToolReviewInput(input) {
+    return {
+        createdAt: input.createdAt,
+        reviewId: input.reviewId,
+        tools: input.tools.map((tool, index) => ({
+            contract: contractShape(tool.recipe),
+            name: toolReviewIdentity(index),
+            riskLabels: [...tool.riskLabels],
+            sha256: toolReviewRevision(input, index),
+            usage: usageShape(tool.usage),
+            valid: tool.valid,
+        })),
+    };
+}
+export function restoreToolReviewResult(input, result) {
+    const tools = new Map(input.tools.map((tool, index) => [toolReviewIdentity(index), {
+            revision: toolReviewRevision(input, index),
+            tool,
+        }]));
+    return {
+        ...result,
+        decisions: result.decisions.map((decision) => {
+            const captured = tools.get(decision.source);
+            return {
+                ...decision,
+                sha256: captured && decision.sha256 === captured.revision
+                    ? captured.tool.sha256
+                    : `invalid:${decision.sha256}`,
+                source: captured?.tool.name ?? `unknown:${decision.source}`,
+                ...(decision.target
+                    ? { target: tools.get(decision.target)?.tool.name ?? decision.target }
+                    : {}),
+            };
+        }),
+    };
+}

package/dist/lib/run-ui-runtime.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Ambient run observability runtime.
+ * Zones: run watcher lifecycle, terminal reconciliation, status animation, shutdown teardown
+ * Owns event-driven run UI coordination without owning actor execution semantics.
+ */
+import * as Pi from "./pi.ts";
+export interface RunUiRuntime {
+    close(): void;
+    shutdown(eventReason: string, ctx: Pi.ExtensionContext): void;
+    start(ctx: Pi.ExtensionContext): void;
+}
+export interface RunUiRuntimeDeps {
+    getActiveContext(): Pi.ExtensionContext | undefined;
+    getRunOwnerId(ctx: Pi.ExtensionContext): string;
+    onRunEvent(): void;
+    pi: Pi.ExtensionAPI;
+}
+export declare function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime;

package/dist/lib/run-ui-runtime.js

@@ -0,0 +1,123 @@
+/**
+ * Ambient run observability runtime.
+ * Zones: run watcher lifecycle, terminal reconciliation, status animation, shutdown teardown
+ * Owns event-driven run UI coordination without owning actor execution semantics.
+ */
+import * as AsyncRuns from "./async-runs.js";
+import * as Observability from "./observability.js";
+import * as Paths from "./paths.js";
+import * as Pi from "./pi.js";
+export function createRunUiRuntime(deps) {
+    let animationInterval;
+    let notifyTimeout;
+    let lastWatcherDiagnosticId = 0;
+    const observation = Observability.createRunUiObservationState();
+    const retirementAttempts = new Set();
+    const terminalNotificationsInFlight = new Set();
+    const retireCandidateRuns = (ctx, summary) => {
+        void Observability.executeRunRetirements(summary, {
+            attempted: retirementAttempts,
+            cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+            notify: (message, level) => ctx.ui.notify(message, level),
+            sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+        });
+    };
+    const update = (ctx, notify = false, terminalOnly = false) => {
+        const ownerId = deps.getRunOwnerId(ctx);
+        const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
+        ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
+        if (!notify)
+            return;
+        const sink = Pi.createNotificationSink(deps.pi, ctx);
+        retireCandidateRuns(ctx, snapshot.summary);
+        Observability.deliverRunTransitionNotifications(snapshot.transitions, sink, terminalNotificationsInFlight);
+        Observability.pruneRunUiObservationState(observation, snapshot);
+        if (!terminalOnly) {
+            Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, sink);
+        }
+    };
+    const reportDiagnostics = (ctx) => {
+        for (const diagnostic of watcher.getDiagnostics()) {
+            if (diagnostic.id <= lastWatcherDiagnosticId)
+                continue;
+            lastWatcherDiagnosticId = diagnostic.id;
+            ctx.ui.notify(diagnostic.message, diagnostic.code === "rearmed" ? "info" : "warning");
+        }
+    };
+    const scheduleUpdate = () => {
+        if (notifyTimeout)
+            clearTimeout(notifyTimeout);
+        notifyTimeout = setTimeout(() => {
+            const ctx = deps.getActiveContext();
+            if (!ctx)
+                return;
+            watcher.refresh();
+            update(ctx, true);
+            deps.onRunEvent();
+            reportDiagnostics(ctx);
+        }, 50);
+        notifyTimeout.unref?.();
+    };
+    const watcher = Observability.createRunStateWatcher({
+        stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+        onChange: scheduleUpdate,
+    });
+    const reconciliation = Observability.createRunTerminalReconciliationLoop({
+        onError: (error) => {
+            const ctx = deps.getActiveContext();
+            if (!ctx)
+                return;
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+        },
+        reconcile: () => {
+            const ctx = deps.getActiveContext();
+            if (!ctx)
+                return;
+            Observability.reconcileRunTerminalNotifications({
+                inFlight: terminalNotificationsInFlight,
+                ownerId: deps.getRunOwnerId(ctx),
+                sink: Pi.createNotificationSink(deps.pi, ctx),
+                state: observation,
+            });
+            reportDiagnostics(ctx);
+        },
+        refreshWatcher: () => watcher.refresh(),
+    });
+    const close = () => {
+        watcher.close();
+        reconciliation.close();
+        if (notifyTimeout)
+            clearTimeout(notifyTimeout);
+        notifyTimeout = undefined;
+        if (animationInterval)
+            clearInterval(animationInterval);
+        animationInterval = undefined;
+    };
+    return {
+        close,
+        shutdown(eventReason, ctx) {
+            close();
+            const teardown = AsyncRuns.teardownRunsOwnedByParent(deps.getRunOwnerId(ctx), Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, { trigger: `session_shutdown:${eventReason}` });
+            if (teardown.failed === 0)
+                return;
+            try {
+                ctx.ui.notify(`Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`, "warning");
+            }
+            catch {
+                /* stale shutdown context */
+            }
+        },
+        start(ctx) {
+            close();
+            update(ctx, true, true);
+            watcher.refresh();
+            reconciliation.start();
+            animationInterval = setInterval(() => {
+                if (deps.getActiveContext() === ctx)
+                    update(ctx);
+            }, 1000);
+            animationInterval.unref?.();
+        },
+    };
+}

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

@@ -1,6 +1,6 @@
 /**
  * Async run artifact declarations and manifest resolution.
- * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ * Owns: artifact path template expansion and filesystem-backed artifact metadata.
  */
 export type RunArtifactDeclaration = string | {
     path: string;

package/dist/lib/runs-artifacts.js

@@ -1,6 +1,6 @@
 /**
  * Async run artifact declarations and manifest resolution.
- * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ * Owns: artifact path template expansion and filesystem-backed artifact metadata.
  */
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";

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

@@ -1,13 +1,19 @@
 /**
  * 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 { type RunProcessIdentity, type RunProcessIdentityResult } from "./runs-process.ts";
 export interface RunProcessSignalPlan {
     args?: string[];
     command?: string;
     signalTarget: "processGroup" | "process" | "processTree";
 }
 export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
-export declare function signalOwnedRunProcess(pid: number, signal: NodeJS.Signals): RunProcessSignalPlan;
+export interface RunProcessSignalDeps {
+    killProcess?: typeof process.kill;
+    runtimePlatform?: NodeJS.Platform;
+    verifyIdentity?: (pid: number, expected: RunProcessIdentity, runtimePlatform: NodeJS.Platform) => RunProcessIdentityResult;
+}
+export declare function signalOwnedRunProcess(pid: number, signal: NodeJS.Signals, expectedIdentity?: RunProcessIdentity, deps?: RunProcessSignalDeps): RunProcessSignalPlan;
 export declare function markTerminalHandled(stateDir: string, details: Record<string, unknown>): void;
 export declare function buildTerminalProgress(existing: Record<string, unknown> | undefined, phase: "cancelled" | "killed"): Record<string, unknown>;

package/dist/lib/runs-control.js

@@ -1,10 +1,11 @@
 /**
  * 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.js";
+import { verifyRunProcessIdentity, } from "./runs-process.js";
 export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.platform) {
     if (runtimePlatform === "win32") {
         return {
@@ -20,8 +21,15 @@ export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.p
     }
     return { signalTarget: "processGroup" };
 }
-export function signalOwnedRunProcess(pid, signal) {
-    const plan = getRunProcessSignalPlan(pid, signal);
+export function signalOwnedRunProcess(pid, signal, expectedIdentity, deps = {}) {
+    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) {
@@ -31,12 +39,21 @@ export function signalOwnedRunProcess(pid, signal) {
         }
         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.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/dist/lib/runs-identity.d.ts

@@ -1,5 +1,5 @@
 /**
  * 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 declare function safeRunId(value: string | undefined): string;

package/dist/lib/runs-identity.js

@@ -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) {
     const run = (value || `run-${Date.now()}`).trim();

package/dist/lib/runs-index.d.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.
  */
 export interface RunStateIndexEntry {
     ownerId?: string;
@@ -12,7 +12,16 @@ export interface RunStateIndexEntry {
     updated_at?: string;
 }
 export type RunStatusReader = (runOrDir: string) => Record<string, unknown>;
-export declare function listRunStateDirs(stateRoot: string, depth?: number, seen?: Set<string>): string[];
+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>>;