@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/stage-reuse.d.ts

@@ -0,0 +1,11 @@
+import type { BuildStageExecutionDefinition } from "./build-target.js";
+export declare function computeStageFingerprint(contextGraphPath: string, stageDefinition: BuildStageExecutionDefinition): string | null;
+export interface StageReuseDecision {
+    reuse: boolean;
+    fingerprint: string | null;
+    summary: string;
+}
+export declare function stageReuseDecision(options: {
+    contextGraphPath: string;
+    stageDefinition: BuildStageExecutionDefinition;
+}): StageReuseDecision;

package/dist/packages/runtime/build/stage-reuse.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { buildPlanPackagePathForContextGraph, } from "./context-graph-paths.js";
+import { buildBuildStageExecutionPlan } from "./build-stage-plan.js";
+import { loadState } from "./state.js";
+import { loadBuildStageInputs, loadContextGraphSourceManifest } from "./source-manifest.js";
+import { validateBuildStage } from "./validate.js";
+import { StageFingerprintSchema } from "./lib/schema.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { readExecutionStageLedgerHistory } from "../runtime-persistence.js";
+import { stageEvidenceAcceptanceFailure, supportsStageEvidenceHarness, } from "./stage-evidence.js";
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]));
+}
+function stableJson(value) {
+    return JSON.stringify(stableValue(value));
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function fileHash(path) {
+    if (!existsSync(path))
+        return null;
+    return sha256(readFileSync(path));
+}
+function latestStageRun(runs, runId, stageId) {
+    if (!runId)
+        return null;
+    return runs
+        .filter((run) => run.run_id === runId && run.stage === stageId)
+        .sort((left, right) => left.updated_at.localeCompare(right.updated_at))
+        .at(-1) ?? null;
+}
+function buildPlanPackageHash(contextGraphPath) {
+    const root = buildPlanPackagePathForContextGraph(contextGraphPath);
+    const files = listFilesRecursive(root)
+        .map((path) => ({
+        path,
+        relativePath: relative(root, path).replaceAll("\\", "/"),
+    }))
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    return sha256(stableJson(files.map((file) => ({
+        path: file.relativePath,
+        hash: fileHash(file.path),
+    }))));
+}
+function stageFingerprintProjectIntent(stageDefinition, projectIntent) {
+    if (stageDefinition.contractType === "build-file-evidence")
+        return null;
+    return projectIntent;
+}
+export function computeStageFingerprint(contextGraphPath, stageDefinition) {
+    const stageInputs = loadBuildStageInputs(contextGraphPath, stageDefinition.id);
+    if (!stageInputs)
+        return null;
+    if (stageInputs.version !== 3 || !stageInputs.source_manifest_id)
+        return null;
+    const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (!sourceManifest || sourceManifest.manifest_id !== stageInputs.source_manifest_id)
+        return null;
+    const plan = buildBuildStageExecutionPlan(contextGraphPath, stageDefinition);
+    const stageSkillPath = join(buildPlanPackagePathForContextGraph(contextGraphPath), "build", "stages", stageDefinition.skillDir, "SKILL.md");
+    const payload = {
+        build_plan: {
+            id: plan.context.buildPlanId,
+            package_hash: buildPlanPackageHash(contextGraphPath),
+        },
+        project: {
+            id: plan.context.project.id,
+            intent: stageFingerprintProjectIntent(stageDefinition, plan.context.projectIntent),
+        },
+        source_manifest: {
+            manifest_id: sourceManifest.manifest_id,
+            generated_at: sourceManifest.generated_at,
+            source_total: sourceManifest.source_total,
+        },
+        source_slice: stageInputs.inputs
+            .map((input) => ({
+            source_file_id: input.source_file_id,
+            path: input.path,
+            locator: input.locator,
+            kind: input.kind,
+            size_bytes: input.size_bytes,
+            page_count: input.page_count,
+            inspectable_units: input.inspectable_units,
+            content_hash: input.content_hash,
+        }))
+            .sort((left, right) => `${left.source_file_id}:${left.path}`.localeCompare(`${right.source_file_id}:${right.path}`)),
+        stage: {
+            id: stageDefinition.id,
+            skill_dir: stageDefinition.skillDir,
+            skill_hash: fileHash(stageSkillPath),
+        },
+        contract: {
+            stage: stageDefinition.id,
+            contract_type: stageDefinition.contractType,
+            counts: plan.contract.counts,
+            artifacts: {
+                reads: [...plan.contract.artifacts.reads].sort((left, right) => left.localeCompare(right)),
+                writes: [...plan.contract.artifacts.writes].sort((left, right) => left.localeCompare(right)),
+                write_contracts: [...plan.contract.artifacts.write_contracts]
+                    .map((contract) => ({
+                    artifact_id: contract.artifact_id,
+                    path: contract.path,
+                    checks: contract.checks,
+                }))
+                    .sort((left, right) => `${left.artifact_id}:${left.path}`.localeCompare(`${right.artifact_id}:${right.path}`)),
+            },
+            context_checks: stageDefinition.contractType === "build-file-evidence"
+                ? []
+                : [...plan.contract.context_checks],
+        },
+    };
+    return StageFingerprintSchema.parse(sha256(stableJson(payload)));
+}
+export function stageReuseDecision(options) {
+    const fingerprint = computeStageFingerprint(options.contextGraphPath, options.stageDefinition);
+    if (!fingerprint) {
+        return { reuse: false, fingerprint, summary: "missing stage fingerprint input" };
+    }
+    const state = loadState(options.contextGraphPath);
+    const record = state?.stages?.[options.stageDefinition.id];
+    if (!record || record.status !== "succeeded") {
+        return { reuse: false, fingerprint, summary: "stage has not succeeded yet" };
+    }
+    if (record.fingerprint !== fingerprint) {
+        return { reuse: false, fingerprint, summary: "stage fingerprint changed" };
+    }
+    if (supportsStageEvidenceHarness(options.stageDefinition)) {
+        const acceptedEvidenceRun = latestStageRun(readExecutionStageLedgerHistory(options.contextGraphPath), record.run_id, options.stageDefinition.id);
+        if (acceptedEvidenceRun?.status !== "succeeded") {
+            return { reuse: false, fingerprint, summary: "stage evidence run has not succeeded" };
+        }
+        const evidenceFailure = stageEvidenceAcceptanceFailure(acceptedEvidenceRun?.evidence ?? null);
+        if (evidenceFailure) {
+            return { reuse: false, fingerprint, summary: evidenceFailure };
+        }
+    }
+    const validation = validateBuildStage(options.contextGraphPath, options.stageDefinition.id);
+    if (!validation.required) {
+        return { reuse: false, fingerprint, summary: "stage is not required yet" };
+    }
+    if (!validation.ok) {
+        return { reuse: false, fingerprint, summary: validation.summary };
+    }
+    return { reuse: true, fingerprint, summary: "reused (verified, unchanged)" };
+}

package/dist/packages/runtime/build/stage-session.d.ts

@@ -0,0 +1,81 @@
+import { type AgentExecutor } from "../agents/lib/executors.js";
+import { type ExecutionStageLedger, type RuntimeStageContract, type StageExecutionSession } from "./lib/schema.js";
+import type { AgentJobType } from "./lib/schema.js";
+import type { BuildPlanId, ProjectId, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage } from "../../contracts/lib/schema.js";
+export declare function writeStageExecutionSessionStarted(options: {
+    contextGraphPath: string;
+    jobType?: AgentJobType;
+    project: ProjectId;
+    projectIntent?: string | null;
+    buildPlanId: BuildPlanId;
+    buildRunId?: string | null;
+    stageId: RuntimeStage | null;
+    stageLabel: string | null;
+    contractType: RuntimeContractType | null;
+    stageRunId: string;
+    attempt?: number;
+    executor: RuntimeExecutorInfo | AgentExecutor;
+    shellRoot: string | null;
+    contractPath: string | null;
+    promptPath: string | null;
+    eventStreamPath: string | null;
+    statusPath: string | null;
+    summary: string | null;
+}): StageExecutionSession;
+export declare function writeStageExecutionSessionStartedFromLedger(options: {
+    contextGraphPath: string;
+    run: ExecutionStageLedger;
+    contract: RuntimeStageContract;
+    buildRunId?: string | null;
+    shellRoot: string | null;
+    promptPath: string | null;
+    eventStreamPath: string | null;
+    statusPath: string | null;
+}): StageExecutionSession;
+/**
+ * Project the terminal session state from a finished ExecutionStageLedger. The
+ * session is a projection of the ledger, so the ledger→session field mapping
+ * (stage, run id, terminal status, summary, error) lives HERE, once, instead of
+ * being re-stated by hand at every ledger-terminal write site. A `running`
+ * ledger is not terminal and is ignored (no-op) so callers can pass the record
+ * unconditionally. Returns null when no session exists for the run (same
+ * contract as `writeStageExecutionSessionFinished`).
+ */
+export declare function projectSessionFinishedFromLedger(contextGraphPath: string, ledger: ExecutionStageLedger): StageExecutionSession | null;
+export declare function writeStageExecutionSessionFinished(options: {
+    contextGraphPath: string;
+    stageId: string | null;
+    stageRunId: string;
+    status: "succeeded" | "failed";
+    summary: string;
+    error?: string | null;
+}): StageExecutionSession | null;
+export declare function recordStageExecutionSessionValidationAttempt(options: {
+    contextGraphPath: string;
+    stageId: string;
+    stageRunId: string;
+    attempt: number;
+    status: "succeeded" | "failed";
+    summary: string;
+}): StageExecutionSession | null;
+export declare function markStageExecutionSessionsShellPreserved(options: {
+    contextGraphPath: string;
+    shellRoot: string;
+}): void;
+/**
+ * Reconcile sessions after their stage execution shells were pruned. The build
+ * pipeline deletes the whole execution-shells root on a successful build under
+ * non-"always" retention, but the session records live in a SEPARATE
+ * stage-sessions dir and would keep pointing at the deleted shell with
+ * `replay_ready: true` — a dangling pointer (F2). For every session whose shell
+ * root no longer exists on disk, downgrade it so "session exists" still implies
+ * "session is real": `replay_ready` false, preserved-shell manifest path
+ * nulled, and a retention reason recorded. Already-downgraded sessions and
+ * sessions whose shell still exists are left untouched. Best-effort and
+ * idempotent; runs in the build's `finally`, so it must never throw.
+ */
+export declare function reconcilePrunedStageExecutionSessions(options: {
+    contextGraphPath: string;
+    reason?: string;
+}): void;
+export declare function listStageExecutionSessions(contextGraphPath: string): StageExecutionSession[];

package/dist/packages/runtime/build/stage-session.js

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync, readdirSync, } from "node:fs";
+import { isAbsolute, join, relative, } from "node:path";
+import { preservedShellManifestPath, shellWorkspaceManifestPath, } from "../agents/lib/shell-paths.js";
+import { buildRuntimeExecutorInfo, } from "../agents/lib/executors.js";
+import { contextGraphRuntimeStageSessionPath, contextGraphRuntimeStageSessionsRoot, } from "./context-graph-paths.js";
+import { writeJsonAtomic } from "./atomic-fs.js";
+import { ExecutionShellPathsSchema, StageExecutionSessionSchema, } from "./lib/schema.js";
+function contextRelative(contextGraphPath, path) {
+    if (!path)
+        return null;
+    const rel = isAbsolute(path) ? relative(contextGraphPath, path) : path;
+    return rel.replaceAll("\\", "/");
+}
+function shellRuntimeFile(contextGraphPath, shellRoot, fileName) {
+    if (!shellRoot)
+        return null;
+    return contextRelative(contextGraphPath, join(shellRoot, "runtime", fileName));
+}
+/**
+ * Context-relative path to a shell runtime file ONLY when it exists on disk.
+ * Used for artifacts that are written DURING the run (e.g. the agent reasoning
+ * transcript), so a session never advertises a dangling path: null at session
+ * start (the file does not exist yet, and a non-reasoning run never creates it),
+ * the real path once it has been teed. `shellRootRel` is the context-relative
+ * shell root (`.` for the no-shell case, which has no runtime dir to reference).
+ */
+function runtimeFileIfExists(contextGraphPath, shellRootRel, fileName) {
+    if (!shellRootRel || shellRootRel === ".")
+        return null;
+    const rel = `${shellRootRel.replace(/\/+$/, "")}/runtime/${fileName}`;
+    return existsSync(join(contextGraphPath, rel)) ? rel : null;
+}
+function readShellPaths(shellRoot) {
+    if (!shellRoot)
+        return null;
+    const filePath = join(shellRoot, "runtime", "paths.json");
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return ExecutionShellPathsSchema.parse(JSON.parse(readFileSync(filePath, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+// Stage jobs key the session dir off `stage_id`. Non-stage jobs (job_type !==
+// "stage"/"source-inventory") carry a null stage_id, so they bucket under a
+// stable "_job" segment keyed by stage_run_id. Stage layout is unchanged: every
+// current writer passes a real stage id.
+function stageSessionPath(contextGraphPath, stageId, stageRunId) {
+    return contextGraphRuntimeStageSessionPath(contextGraphPath, stageId ?? "_job", stageRunId);
+}
+function readSessionAt(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return StageExecutionSessionSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+function readSession(contextGraphPath, stageId, stageRunId) {
+    return readSessionAt(stageSessionPath(contextGraphPath, stageId, stageRunId));
+}
+function writeSession(contextGraphPath, session) {
+    const parsed = StageExecutionSessionSchema.parse(session);
+    writeJsonAtomic(stageSessionPath(contextGraphPath, parsed.stage_id, parsed.stage_run_id), parsed);
+    return parsed;
+}
+function nextAttemptForStage(contextGraphPath, stageId) {
+    return listStageExecutionSessions(contextGraphPath)
+        .filter((session) => session.stage_id === stageId)
+        .length + 1;
+}
+export function writeStageExecutionSessionStarted(options) {
+    const now = new Date().toISOString();
+    const shellRoot = options.shellRoot;
+    const paths = readShellPaths(shellRoot);
+    const shellRootPath = contextRelative(options.contextGraphPath, shellRoot) ?? ".";
+    const workspacePath = shellRoot ? shellWorkspaceManifestPath(shellRoot) : null;
+    const preservedPath = shellRoot ? preservedShellManifestPath(shellRoot) : null;
+    const executor = "execute" in options.executor
+        ? buildRuntimeExecutorInfo(options.executor)
+        : options.executor;
+    const existing = readSession(options.contextGraphPath, options.stageId, options.stageRunId);
+    return writeSession(options.contextGraphPath, {
+        kind: "interf-stage-execution-session",
+        version: 1,
+        job_type: existing?.job_type ?? options.jobType ?? "stage",
+        generated_at: existing?.generated_at ?? now,
+        updated_at: now,
+        project: options.project,
+        project_intent: options.projectIntent ?? null,
+        context_graph_path: options.contextGraphPath,
+        build_plan: options.buildPlanId,
+        build_run_id: options.buildRunId ?? null,
+        stage_id: options.stageId,
+        stage_label: options.stageLabel,
+        contract_type: options.contractType,
+        stage_run_id: options.stageRunId,
+        attempt: existing?.attempt ?? options.attempt ?? nextAttemptForStage(options.contextGraphPath, options.stageId),
+        status: existing?.status ?? "running",
+        executor,
+        shell: {
+            root_path: shellRootPath,
+            workspace_manifest_path: workspacePath && existsSync(workspacePath)
+                ? contextRelative(options.contextGraphPath, workspacePath)
+                : null,
+            preserved_shell_manifest_path: preservedPath && existsSync(preservedPath)
+                ? contextRelative(options.contextGraphPath, preservedPath)
+                : null,
+            replay_ready: Boolean(shellRoot && existsSync(join(shellRoot, "AGENTS.md"))),
+            retention_reason: existing?.shell.retention_reason ?? null,
+        },
+        logs: {
+            prompt_path: contextRelative(options.contextGraphPath, options.promptPath),
+            event_stream_path: contextRelative(options.contextGraphPath, options.eventStreamPath),
+            status_path: contextRelative(options.contextGraphPath, options.statusPath),
+        },
+        runtime_files: {
+            project_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "project.json"),
+            contract_path: contextRelative(options.contextGraphPath, options.contractPath),
+            paths_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "paths.json"),
+            source_locator_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "source-locator.json"),
+            source_manifest_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "source-manifest.json"),
+            source_state_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "source-state.json"),
+            stage_inputs_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "stage-inputs.json"),
+            expected_inputs_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "expected-inputs.json"),
+            reviewed_inputs_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "reviewed-inputs.json"),
+            previous_attempts_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "previous-attempts.json"),
+            retry_feedback_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "retry-feedback.md"),
+            last_validation_failure_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "last-validation-failure.txt"),
+            verifier_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "check-stage.mjs"),
+            stage_evidence_path: shellRuntimeFile(options.contextGraphPath, shellRoot, "stage-evidence.json"),
+            reasoning_path: existing?.runtime_files.reasoning_path
+                ?? runtimeFileIfExists(options.contextGraphPath, shellRootPath, "agent-reasoning.jsonl"),
+        },
+        artifacts: {
+            reads: paths?.reads ?? [],
+            writes: paths?.writes ?? [],
+        },
+        validation_attempts: existing?.validation_attempts ?? [],
+        summary: options.summary,
+        error: existing?.error ?? null,
+    });
+}
+export function writeStageExecutionSessionStartedFromLedger(options) {
+    return writeStageExecutionSessionStarted({
+        contextGraphPath: options.contextGraphPath,
+        project: options.contract.project.id,
+        projectIntent: options.contract.project.intent,
+        buildPlanId: options.contract.build_plan.id,
+        buildRunId: options.buildRunId ?? null,
+        stageId: options.run.stage,
+        stageLabel: options.run.stage_label,
+        contractType: options.run.contract_type,
+        stageRunId: options.run.run_id,
+        executor: options.run.executor,
+        shellRoot: options.shellRoot,
+        contractPath: options.shellRoot
+            ? join(options.shellRoot, "runtime", "stage-contract.json")
+            : join(options.contextGraphPath, options.run.contract_path),
+        promptPath: options.promptPath,
+        eventStreamPath: options.eventStreamPath,
+        statusPath: options.statusPath,
+        summary: options.run.summary,
+    });
+}
+/**
+ * Project the terminal session state from a finished ExecutionStageLedger. The
+ * session is a projection of the ledger, so the ledger→session field mapping
+ * (stage, run id, terminal status, summary, error) lives HERE, once, instead of
+ * being re-stated by hand at every ledger-terminal write site. A `running`
+ * ledger is not terminal and is ignored (no-op) so callers can pass the record
+ * unconditionally. Returns null when no session exists for the run (same
+ * contract as `writeStageExecutionSessionFinished`).
+ */
+export function projectSessionFinishedFromLedger(contextGraphPath, ledger) {
+    if (ledger.status === "running")
+        return null;
+    return writeStageExecutionSessionFinished({
+        contextGraphPath,
+        stageId: ledger.stage,
+        stageRunId: ledger.run_id,
+        status: ledger.status,
+        summary: ledger.summary,
+        error: ledger.error,
+    });
+}
+export function writeStageExecutionSessionFinished(options) {
+    const current = readSession(options.contextGraphPath, options.stageId, options.stageRunId);
+    if (!current)
+        return null;
+    return writeSession(options.contextGraphPath, {
+        ...current,
+        updated_at: new Date().toISOString(),
+        status: options.status,
+        summary: options.summary,
+        error: options.error ?? null,
+        runtime_files: {
+            ...current.runtime_files,
+            // The reasoning transcript is teed DURING the run, so resolve it at finish:
+            // set the path iff the agent actually emitted reasoning (file exists), else
+            // leave null. Keeps "session references a reasoning file" => "the file is real".
+            reasoning_path: current.runtime_files.reasoning_path
+                ?? runtimeFileIfExists(options.contextGraphPath, current.shell.root_path, "agent-reasoning.jsonl"),
+        },
+    });
+}
+export function recordStageExecutionSessionValidationAttempt(options) {
+    const current = readSession(options.contextGraphPath, options.stageId, options.stageRunId);
+    if (!current)
+        return null;
+    const withoutExisting = current.validation_attempts
+        .filter((attempt) => attempt.attempt !== options.attempt);
+    return writeSession(options.contextGraphPath, {
+        ...current,
+        updated_at: new Date().toISOString(),
+        validation_attempts: [
+            ...withoutExisting,
+            {
+                attempt: options.attempt,
+                recorded_at: new Date().toISOString(),
+                status: options.status,
+                summary: options.summary,
+            },
+        ].sort((left, right) => left.attempt - right.attempt),
+    });
+}
+export function markStageExecutionSessionsShellPreserved(options) {
+    const shellRootPath = contextRelative(options.contextGraphPath, options.shellRoot);
+    const preservedPath = preservedShellManifestPath(options.shellRoot);
+    const preservedRel = existsSync(preservedPath)
+        ? contextRelative(options.contextGraphPath, preservedPath)
+        : null;
+    for (const session of listStageExecutionSessions(options.contextGraphPath)) {
+        if (session.shell.root_path !== shellRootPath)
+            continue;
+        writeSession(options.contextGraphPath, {
+            ...session,
+            updated_at: new Date().toISOString(),
+            shell: {
+                ...session.shell,
+                preserved_shell_manifest_path: preservedRel,
+                replay_ready: session.shell.replay_ready && existsSync(join(options.shellRoot, "AGENTS.md")),
+            },
+        });
+    }
+}
+/**
+ * Reconcile sessions after their stage execution shells were pruned. The build
+ * pipeline deletes the whole execution-shells root on a successful build under
+ * non-"always" retention, but the session records live in a SEPARATE
+ * stage-sessions dir and would keep pointing at the deleted shell with
+ * `replay_ready: true` — a dangling pointer (F2). For every session whose shell
+ * root no longer exists on disk, downgrade it so "session exists" still implies
+ * "session is real": `replay_ready` false, preserved-shell manifest path
+ * nulled, and a retention reason recorded. Already-downgraded sessions and
+ * sessions whose shell still exists are left untouched. Best-effort and
+ * idempotent; runs in the build's `finally`, so it must never throw.
+ */
+export function reconcilePrunedStageExecutionSessions(options) {
+    const reason = options.reason
+        ?? "Stage execution shell pruned after a successful Build (on-failure retention).";
+    for (const session of listStageExecutionSessions(options.contextGraphPath)) {
+        const shellRootAbsolute = join(options.contextGraphPath, session.shell.root_path);
+        if (existsSync(shellRootAbsolute))
+            continue;
+        if (!session.shell.replay_ready
+            && session.shell.preserved_shell_manifest_path === null
+            && session.shell.retention_reason !== null) {
+            continue;
+        }
+        writeSession(options.contextGraphPath, {
+            ...session,
+            updated_at: new Date().toISOString(),
+            shell: {
+                ...session.shell,
+                preserved_shell_manifest_path: null,
+                replay_ready: false,
+                retention_reason: reason,
+            },
+        });
+    }
+}
+export function listStageExecutionSessions(contextGraphPath) {
+    const root = contextGraphRuntimeStageSessionsRoot(contextGraphPath);
+    if (!existsSync(root))
+        return [];
+    const sessions = [];
+    for (const stageId of readdirSync(root)) {
+        const stageRoot = join(root, stageId);
+        if (!existsSync(stageRoot))
+            continue;
+        for (const stageRunId of readdirSync(stageRoot)) {
+            const session = readSessionAt(join(stageRoot, stageRunId, "session.json"));
+            if (session)
+                sessions.push(session);
+        }
+    }
+    return sessions.sort((left, right) => {
+        const byGenerated = Date.parse(left.generated_at) - Date.parse(right.generated_at);
+        if (byGenerated !== 0)
+            return byGenerated;
+        return left.stage_run_id.localeCompare(right.stage_run_id);
+    });
+}

package/dist/packages/runtime/build/state-artifacts.d.ts

@@ -0,0 +1,9 @@
+import { type ContextGraphHealth, type ContextGraphViewSpec, type SourceFiles, type SourceState } from "./lib/schema.js";
+export declare function refreshContextGraphArtifacts(dirPath: string, options?: {
+    ensureViewSpec?: boolean;
+}): {
+    health: ContextGraphHealth;
+    viewSpec?: ContextGraphViewSpec;
+    sourceFiles: SourceFiles;
+    sourceState: SourceState;
+};

package/dist/packages/runtime/build/state-artifacts.js

@@ -0,0 +1,14 @@
+import { saveContextGraphHealth, } from "./state-io.js";
+import { computeContextGraphHealth, } from "./state-health.js";
+import { ensureContextGraphSourceFiles, ensureContextGraphSourceState, ensureContextGraphViewSpec, } from "./state-view.js";
+export function refreshContextGraphArtifacts(dirPath, options) {
+    const health = computeContextGraphHealth(dirPath);
+    saveContextGraphHealth(dirPath, health);
+    const sourceFiles = ensureContextGraphSourceFiles(dirPath);
+    const sourceState = ensureContextGraphSourceState(dirPath, sourceFiles);
+    let viewSpec;
+    if (options?.ensureViewSpec) {
+        viewSpec = ensureContextGraphViewSpec(dirPath);
+    }
+    return { health, viewSpec, sourceFiles, sourceState };
+}

package/dist/packages/runtime/build/state-health.d.ts

@@ -0,0 +1,4 @@
+import { type ContextGraphHealth, type BuildStage, type RuntimeStatus } from "./lib/schema.js";
+export declare function computeContextGraphHealth(dirPath: string): ContextGraphHealth;
+export declare function resolveContextGraphStatus(..._args: unknown[]): RuntimeStatus;
+export declare function resolveBuildStage(...args: unknown[]): BuildStage;