stageflow 0.23.0 → 0.27.0

package/dist/runstore/diskUsage.js

@@ -0,0 +1,214 @@
+import { readdir, stat, statfs } from "node:fs/promises";
+import path from "node:path";
+const BLOCK_SIZE = 512;
+const STATE_DB_NAMES = ["state.db", "state.db-wal", "state.db-shm"];
+export const DISK_WARN_LOG_PREFIX = "stageflow.disk_warn";
+let walkCallCount = 0;
+let freeSpaceReaderOverride = null;
+export function getDiskUsageWalkCallCount() {
+    return walkCallCount;
+}
+export function resetDiskUsageWalkCallCount() {
+    walkCallCount = 0;
+}
+export function setFreeSpaceReaderForTests(reader) {
+    freeSpaceReaderOverride = reader;
+}
+function allocatedBytes(st) {
+    return st.blocks * BLOCK_SIZE;
+}
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+/** Walk `rootPath` summing `stat().blocks * 512`. Missing path → 0. */
+export async function diskUsageOf(rootPath) {
+    walkCallCount += 1;
+    if (!(await pathExists(rootPath)))
+        return 0;
+    let total = 0;
+    async function walk(current) {
+        let st;
+        try {
+            st = await stat(current);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        total += allocatedBytes(st);
+        if (!st.isDirectory())
+            return;
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            await walk(path.join(current, entry.name));
+        }
+    }
+    await walk(rootPath);
+    return total;
+}
+export async function readFilesystemSize(rootPath) {
+    if (freeSpaceReaderOverride !== null) {
+        return freeSpaceReaderOverride(rootPath);
+    }
+    let target = path.resolve(rootPath);
+    for (;;) {
+        try {
+            const fsStats = await statfs(target);
+            const blockSize = fsStats.bsize;
+            return {
+                freeBytes: fsStats.bavail * blockSize,
+                totalBytes: fsStats.blocks * blockSize,
+            };
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            const parent = path.dirname(target);
+            if (parent === target)
+                throw err;
+            target = parent;
+        }
+    }
+}
+async function usageOfMissingOk(target) {
+    try {
+        return await diskUsageOf(target);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+}
+async function stateDbBytes(durableRoot) {
+    let total = 0;
+    for (const name of STATE_DB_NAMES) {
+        const filePath = path.join(durableRoot, name);
+        try {
+            const st = await stat(filePath);
+            if (st.isFile()) {
+                walkCallCount += 1;
+                total += allocatedBytes(st);
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+    }
+    return total;
+}
+/** Category breakdown for the durable root, reusing `diskUsageOf` for directory trees. */
+export async function durableRootDiskBreakdown(durableRoot, options) {
+    const freeSpace = options?.freeSpace ?? readFilesystemSize;
+    const [runs_bytes, worktrees_bytes, repos_bytes, state_db_bytes, a2a_artifacts_bytes, cache_bytes, size] = await Promise.all([
+        usageOfMissingOk(path.join(durableRoot, "runs")),
+        usageOfMissingOk(path.join(durableRoot, "worktrees")),
+        usageOfMissingOk(path.join(durableRoot, "repos")),
+        stateDbBytes(durableRoot),
+        usageOfMissingOk(path.join(durableRoot, "a2a-artifacts")),
+        usageOfMissingOk(path.join(durableRoot, "cache")),
+        freeSpace(durableRoot),
+    ]);
+    return {
+        runs_bytes,
+        worktrees_bytes,
+        repos_bytes,
+        state_db_bytes,
+        a2a_artifacts_bytes,
+        cache_bytes,
+        free_bytes: size.freeBytes,
+    };
+}
+/**
+ * Parse `STAGEFLOW_DISK_WARN_BYTES` / floor-style env: integer bytes or `N%` of filesystem.
+ * Empty / unset / invalid → undefined (no threshold).
+ */
+export function parseDiskBytesThreshold(raw, filesystemTotalBytes) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return undefined;
+    if (trimmed.endsWith("%")) {
+        const pct = Number.parseFloat(trimmed.slice(0, -1));
+        if (!Number.isFinite(pct) || pct < 0 || pct > 100)
+            return undefined;
+        if (!Number.isFinite(filesystemTotalBytes) || filesystemTotalBytes < 0) {
+            return undefined;
+        }
+        return Math.floor((filesystemTotalBytes * pct) / 100);
+    }
+    const n = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return n;
+}
+const DEFAULT_MIN_FREE_DISK_BYTES = 2 * 1024 * 1024 * 1024;
+/**
+ * Resolve `STAGEFLOW_MIN_FREE_DISK_BYTES`: bytes or `%` of filesystem.
+ * Unset / empty / invalid → `max(2 GiB, 10% of filesystemTotalBytes)`.
+ */
+export function resolveMinFreeDiskFloor(raw, filesystemTotalBytes) {
+    const parsed = parseDiskBytesThreshold(raw, filesystemTotalBytes);
+    if (parsed !== undefined)
+        return parsed;
+    const total = Number.isFinite(filesystemTotalBytes) && filesystemTotalBytes > 0
+        ? filesystemTotalBytes
+        : 0;
+    const tenPercent = Math.floor(total * 0.1);
+    return Math.max(DEFAULT_MIN_FREE_DISK_BYTES, tenPercent);
+}
+/**
+ * One named warning when free space is below `STAGEFLOW_DISK_WARN_BYTES`. Never throws.
+ * @returns true when a warning line was emitted
+ */
+export async function warnDurableRootDiskIfNeeded(durableRoot, options) {
+    try {
+        const env = options?.env ?? process.env;
+        const raw = env.STAGEFLOW_DISK_WARN_BYTES;
+        if (raw === undefined || raw.trim() === "")
+            return false;
+        const freeSpace = options?.freeSpace ?? readFilesystemSize;
+        const size = await freeSpace(durableRoot);
+        const threshold = parseDiskBytesThreshold(raw, size.totalBytes);
+        if (threshold === undefined)
+            return false;
+        if (size.freeBytes >= threshold)
+            return false;
+        const log = options?.log ?? ((line) => console.warn(line));
+        log(`${DISK_WARN_LOG_PREFIX}: durable root free space ${size.freeBytes} bytes is below threshold ${threshold} bytes (${raw.trim()}); run sf runs gc`);
+        return true;
+    }
+    catch (err) {
+        const log = options?.log ?? ((line) => console.warn(line));
+        log(`${DISK_WARN_LOG_PREFIX}: free-space measurement failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+/** Measure one run workspace and persist `disk_bytes` / `disk_measured_at`. */
+export async function refreshRunDiskUsage(store, runId, options) {
+    const workspaceDir = store.getWorkspaceDir(runId);
+    const bytes = await diskUsageOf(workspaceDir);
+    const measuredAt = (options?.now ?? new Date()).toISOString();
+    await store.setRunDiskUsage(runId, bytes, measuredAt);
+    return bytes;
+}

package/dist/runstore/exportRunPayload.d.ts

@@ -0,0 +1,8 @@
+import { type RunProjection } from "../projection/projectRun.js";
+import type { RunDetail } from "./port.js";
+import { type RunManifest } from "./runManifest.js";
+export type RunExportPayload = RunProjection & {
+    run_manifest: RunManifest | null;
+};
+export declare function buildRunExportPayload(detail: RunDetail): RunExportPayload;
+export declare function runDetailWithRedactedManifest(detail: RunDetail): RunDetail;

package/dist/runstore/exportRunPayload.js

@@ -0,0 +1,23 @@
+import { projectRun } from "../projection/projectRun.js";
+import { redactRunManifestForRead, } from "./runManifest.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
+export function buildRunExportPayload(detail) {
+    return {
+        ...projectRun(detail),
+        run_manifest: redactRunManifestForRead(detail.run_manifest, {
+            namedSecrets: getNamedSecrets(),
+        }),
+    };
+}
+export function runDetailWithRedactedManifest(detail) {
+    const run_manifest = redactRunManifestForRead(detail.run_manifest, {
+        namedSecrets: getNamedSecrets(),
+    });
+    if (run_manifest === null) {
+        if (detail.run_manifest === undefined)
+            return detail;
+        const { run_manifest: _drop, ...rest } = detail;
+        return rest;
+    }
+    return { ...detail, run_manifest };
+}

package/dist/runstore/normalizeCatalogPath.d.ts

@@ -1 +1,2 @@
 export declare function normalizeCatalogPath(raw: string): string;
+export declare function normalizeProjectRoot(raw: string): string;

package/dist/runstore/normalizeCatalogPath.js

@@ -1,4 +1,14 @@
+import { realpathSync } from "node:fs";
 import path from "node:path";
 export function normalizeCatalogPath(raw) {
     return path.resolve(raw);
 }
+export function normalizeProjectRoot(raw) {
+    const resolved = path.resolve(raw);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}

package/dist/runstore/paths.d.ts

@@ -1,6 +1,11 @@
 export declare function newRunId(): string;
 /** Root for factory state under a project: `<rootDir>/.stageflow`. */
 export declare function storeRootFor(rootDir: string): string;
+export declare function isGlobalStageflowHome(rootDir: string): boolean;
+/** Project store root or the durable home when `rootDir` is the global home. */
+export declare function resolveStoreRoot(rootDir: string): string;
+export declare const NESTED_GLOBAL_STORE_CONFLICT = "Cannot open the global store: flat state.db has no runs table while nested .stageflow/state.db still holds run data. Resolve the conflict manually.";
+export declare function flattenNestedGlobalStore(home: string): void;
 export declare function migrateLegacyStoreRoot(rootDir: string): void;
 export declare function runsDir(storeRoot: string): string;
 export declare function runWorkspaceDir(storeRoot: string, runId: string): string;

package/dist/runstore/paths.js

@@ -1,6 +1,8 @@
 import { randomBytes } from "node:crypto";
-import { readdirSync, renameSync, rmdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, renameSync, rmdirSync, statSync, } from "node:fs";
 import path from "node:path";
+import Database from "better-sqlite3";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { guardStageId } from "./workspaceLayout.js";
 export function newRunId() {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -10,6 +12,148 @@ export function newRunId() {
 export function storeRootFor(rootDir) {
     return path.join(rootDir, ".stageflow");
 }
+export function isGlobalStageflowHome(rootDir) {
+    return path.resolve(rootDir) === globalStageflowHome();
+}
+/** Project store root or the durable home when `rootDir` is the global home. */
+export function resolveStoreRoot(rootDir) {
+    if (isGlobalStageflowHome(rootDir)) {
+        return globalStageflowHome();
+    }
+    return storeRootFor(rootDir);
+}
+const NESTED_GLOBAL_STORE_DIR = ".stageflow";
+const STATE_DB_BASENAME = "state.db";
+const STATE_DB_SIDECARS = ["state.db-wal", "state.db-shm"];
+const NESTED_STORE_MOVE_DIRS = ["runs", "a2a-artifacts"];
+export const NESTED_GLOBAL_STORE_CONFLICT = "Cannot open the global store: flat state.db has no runs table while nested .stageflow/state.db still holds run data. Resolve the conflict manually.";
+function sqliteHasRunsTable(dbPath) {
+    if (!existsSync(dbPath)) {
+        return false;
+    }
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        const row = db
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'runs'")
+            .get();
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        db?.close();
+    }
+}
+function assertNoNestedGlobalStoreConflict(home) {
+    const flatDb = path.join(home, STATE_DB_BASENAME);
+    const nestedDb = path.join(home, NESTED_GLOBAL_STORE_DIR, STATE_DB_BASENAME);
+    if (!existsSync(flatDb) || !existsSync(nestedDb)) {
+        return;
+    }
+    if (!sqliteHasRunsTable(flatDb) && sqliteHasRunsTable(nestedDb)) {
+        throw new Error(NESTED_GLOBAL_STORE_CONFLICT);
+    }
+}
+function renameIfExists(from, to) {
+    if (!existsSync(from) || existsSync(to)) {
+        return;
+    }
+    renameSync(from, to);
+}
+function rollbackStateDbSet(home, nested, moved) {
+    for (const name of [...moved].reverse()) {
+        const from = path.join(home, name);
+        const to = path.join(nested, name);
+        if (existsSync(from) && !existsSync(to)) {
+            renameSync(from, to);
+        }
+    }
+}
+function moveStateDbSet(home, nested) {
+    const flatMain = path.join(home, STATE_DB_BASENAME);
+    const nestedMain = path.join(nested, STATE_DB_BASENAME);
+    const flatHasMain = existsSync(flatMain);
+    const nestedHasMain = existsSync(nestedMain);
+    if (flatHasMain && nestedHasMain) {
+        return;
+    }
+    if (flatHasMain && !nestedHasMain) {
+        for (const sidecar of STATE_DB_SIDECARS) {
+            renameIfExists(path.join(nested, sidecar), path.join(home, sidecar));
+        }
+        return;
+    }
+    if (!flatHasMain && nestedHasMain) {
+        const names = [STATE_DB_BASENAME, ...STATE_DB_SIDECARS];
+        const moved = [];
+        try {
+            for (const name of names) {
+                const from = path.join(nested, name);
+                const to = path.join(home, name);
+                if (existsSync(from) && !existsSync(to)) {
+                    renameSync(from, to);
+                    moved.push(name);
+                }
+            }
+        }
+        catch (err) {
+            rollbackStateDbSet(home, nested, moved);
+            throw err;
+        }
+    }
+}
+function flatStorePathAbsent(home, name) {
+    const target = path.join(home, name);
+    const state = directoryState(target);
+    return state === "missing";
+}
+function moveNestedStoreDirs(home, nested) {
+    for (const dirName of NESTED_STORE_MOVE_DIRS) {
+        const from = path.join(nested, dirName);
+        const to = path.join(home, dirName);
+        if (directoryState(from) === "missing") {
+            continue;
+        }
+        if (!flatStorePathAbsent(home, dirName)) {
+            continue;
+        }
+        renameSync(from, to);
+    }
+}
+function removeNestedGlobalStoreDirIfEmpty(home) {
+    const nested = path.join(home, NESTED_GLOBAL_STORE_DIR);
+    const state = directoryState(nested);
+    if (state === "missing" || state === "other") {
+        return;
+    }
+    const inventory = [
+        STATE_DB_BASENAME,
+        ...STATE_DB_SIDECARS,
+        ...NESTED_STORE_MOVE_DIRS,
+    ];
+    for (const name of inventory) {
+        if (existsSync(path.join(nested, name))) {
+            return;
+        }
+    }
+    if (state === "empty") {
+        rmdirSync(nested);
+    }
+}
+export function flattenNestedGlobalStore(home) {
+    const nested = path.join(home, NESTED_GLOBAL_STORE_DIR);
+    const nestedState = directoryState(nested);
+    if (nestedState === "missing" || nestedState === "other") {
+        assertNoNestedGlobalStoreConflict(home);
+        return;
+    }
+    assertNoNestedGlobalStoreConflict(home);
+    moveStateDbSet(home, nested);
+    moveNestedStoreDirs(home, nested);
+    removeNestedGlobalStoreDirIfEmpty(home);
+}
 function directoryState(dirPath) {
     try {
         const st = statSync(dirPath);

package/dist/runstore/port.d.ts

@@ -1,18 +1,21 @@
 import type { StageLogLine } from "../agent/activity.js";
+import type { ConfigOriginRecord } from "../config/configOrigin.js";
+import type { RunSubmission, RunSubmissionRecord } from "./submission.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { FeedbackLoopConfig, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { FeedbackLoopConfig, InlinePipelineDefinition, ResolvedPipelineDag } from "../types/pipeline.js";
 import type { CompletionCheck } from "../types/completion.js";
 import type { StageGateKind } from "../types/stage.js";
 import type { StageUsage } from "../types/usage.js";
-export type RunStatus = "created" | "running" | "succeeded" | "failed";
+export type { ConfigOriginRecord };
+export type RunStatus = "created" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
 export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
     stage_ids: string[];
     gate_kinds?: Record<string, StageGateKind[]>;
     /** IR: per-stage clone assignment schema. YAML: `io.input.schema`. */
     clone_input_schema?: Record<string, unknown>;
 };
-export type StageReadiness = "blocked" | "ready" | "running" | "waiting" | "succeeded" | "failed" | "skipped";
+export type StageReadiness = "blocked" | "ready" | "running" | "waiting" | "interrupted" | "succeeded" | "failed" | "skipped";
 export type PipelineTrackNode = {
     stage_id: string;
     status: StageSnapshot["status"];
@@ -51,6 +54,27 @@ export type RunMeta = {
     pipeline_path?: string;
     task_path?: string;
     project_root?: string;
+    repository?: string;
+    ref?: string;
+    resolved_sha?: string;
+    run_branch?: string;
+    git_author_name?: string;
+    git_author_email?: string;
+    cancel_reason?: string;
+    finished_at?: string;
+    slimmed_at?: string;
+    disk_bytes?: number;
+    disk_measured_at?: string;
+    config_origins?: ConfigOriginRecord[];
+    pipeline_source?: "inline" | "path";
+    caller_id?: string;
+    run_manifest?: unknown;
+    skip_gates?: boolean;
+    /**
+     * Parsed inline pipeline body for stage-worker reload when there is no
+     * pipeline_path. Derived from stored pipeline_body.
+     */
+    inline_pipeline?: InlinePipelineDefinition;
 };
 export type CreatedRun = {
     runId: string;
@@ -64,7 +88,7 @@ export type StageLogEvent = StageLogLine & {
 export type StageSnapshot = {
     stage_id: string;
     definition_id?: string;
-    status: "pending" | "running" | "waiting_for_input" | "succeeded" | "failed" | "skipped";
+    status: "pending" | "running" | "waiting_for_input" | "interrupted" | "succeeded" | "failed" | "skipped";
     events: StageLogEvent[];
     envelope: StageEnvelope | null;
     artifacts: string[];
@@ -85,6 +109,7 @@ export type StageExecution = {
     envelope: StageEnvelope | null;
     cost_usd?: number;
     usage?: StageUsage;
+    auto_resume_count: number;
 };
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
@@ -94,6 +119,7 @@ export type StageExecutionPatch = {
     envelope?: StageEnvelope | null;
     cost_usd?: number;
     usage?: StageUsage;
+    auto_resume_count?: number;
 };
 /** The durable disposition of completion verification for one stage attempt. */
 export type VerificationOutcome = "not_run" | "passed" | "failed" | "error";
@@ -229,6 +255,16 @@ export type CompactStage = {
     definition_id?: string;
     cost_usd?: number;
 };
+export type RunBindingCompact = {
+    kind: "repository" | "checkout" | "unbound";
+    repository?: string;
+    ref?: string;
+    resolved_sha?: string;
+};
+export type RunBindingDetail = RunBindingCompact & {
+    run_branch?: string;
+    checkout_root?: string;
+};
 export type RunSummary = {
     run_id: string;
     pipeline_id: string;
@@ -236,9 +272,11 @@ export type RunSummary = {
     pipeline_path?: string;
     task_path?: string;
     project_root?: string;
+    pipeline_source?: "inline" | "path";
     status: RunStatus;
     created_at: string;
     updated_at?: string;
+    binding: RunBindingCompact;
     stages: CompactStage[];
     /** Present when a stage is waiting_for_input (first such stage). */
     waiting_stage_id?: string;
@@ -256,13 +294,22 @@ export type RunSummary = {
     active_feedback_loop?: FeedbackLoopRecord;
     /** Sum of every stage's cost_usd; omitted when no stage reported usage. */
     total_cost_usd?: number;
+    cancel_reason?: string;
+    finished_at?: string;
+    slimmed_at?: string;
+    disk_bytes?: number;
+    disk_measured_at?: string;
 };
-export type RunDetail = Omit<RunSummary, "stages"> & {
+export type RunDetail = Omit<RunSummary, "stages" | "binding"> & {
+    binding: RunBindingDetail;
     task_yaml: string;
     stages: StageSnapshot[];
     pipeline_track: PipelineTrackProjection;
     /** Append-only feedback-loop and replay history, ordered by creation. */
     feedback_loops: FeedbackLoopHistory[];
+    config_origins?: ConfigOriginRecord[];
+    caller_id?: string;
+    run_manifest?: unknown;
 };
 export type FeedbackLoopHistory = {
     loop: FeedbackLoopRecord;
@@ -275,6 +322,8 @@ export type FeedbackLoopHistory = {
     fork_generations: ForkGenerationRecord[];
 };
 export type CreateRunInput = {
+    submission?: RunSubmission;
+    runId?: string;
     pipelineId: string;
     taskYaml: string;
     taskId?: string;
@@ -286,6 +335,24 @@ export type CreateRunInput = {
     pipelinePath?: string;
     taskPath?: string;
     projectRoot?: string;
+    repository?: string;
+    ref?: string;
+    resolvedSha?: string;
+    runBranch?: string;
+    gitAuthorName?: string;
+    gitAuthorEmail?: string;
+    status?: RunStatus;
+    pipelineSource?: "inline" | "path";
+    /** Durable JSON string stored in pipeline_body. Prefer this for slots writers. */
+    pipelineBody?: string;
+    /**
+     * Convenience for callers/tests that have a parsed inline pipeline.
+     * Stored as pipeline_body JSON; surfaced back as meta.inline_pipeline on read.
+     */
+    inlinePipeline?: InlinePipelineDefinition;
+    callerId?: string;
+    runManifest?: unknown;
+    skipGates?: boolean;
 };
 export type ListRunsFilter = {
     status?: RunStatus;
@@ -293,6 +360,7 @@ export type ListRunsFilter = {
     since?: string;
     /** Match pipeline_id or pipeline_path */
     pipeline?: string;
+    caller_id?: string;
 };
 /**
  * Persistence port for pipeline run state.
@@ -301,10 +369,49 @@ export type ListRunsFilter = {
  * run id is all you have (catalog / rehydrate).
  */
 export interface RunStore {
+    /** Checkpoint WAL (when applicable) and release the store connection. */
+    close(): Promise<void>;
+    /**
+     * Consistent compacted snapshot of the live DB via `VACUUM INTO`.
+     * Only SqliteRunStore implements this; callers must not open a second raw connection.
+     */
+    snapshotInto(destPath: string): Promise<{
+        userVersion: number;
+    }>;
+    getRunBySubmission(key: string): Promise<RunSubmissionRecord | null>;
     createRun(input: CreateRunInput): Promise<CreatedRun>;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;
+    /**
+     * Conditional status update (CAS): sets `status` only when the row currently
+     * has `expectedStatus`. Returns false when the run exists but status differs;
+     * throws when the run is missing.
+     */
+    tryUpdateRunStatus(runId: string, status: RunStatus, expectedStatus: RunStatus): Promise<boolean>;
+    /** Patch workspace-binding columns on an existing run (queued → materialize). */
+    patchRunWorkspaceBinding(runId: string, patch: {
+        checkoutRoot?: string;
+        repository?: string;
+        ref?: string;
+        resolvedSha?: string;
+        runBranch?: string;
+    }): Promise<void>;
+    /** Append resolved config origin records (MCP / skill / verify). Dedupes by name+origin+path. */
+    appendConfigOrigins(runId: string, origins: ConfigOriginRecord[]): Promise<void>;
+    setCancelReason(runId: string, reason: string): Promise<void>;
+    /** Persist cached disk usage for `listRuns` (never measured inside listRuns). */
+    setRunDiskUsage(runId: string, diskBytes: number, measuredAt: string): Promise<void>;
+    /** Record that SLIM reclaim completed for this run (R18 idempotency gate). */
+    setSlimmedAt(runId: string, slimmedAt: string): Promise<void>;
+    /** Hard-delete every run-scoped row. Throws `Run not found: …` when missing. */
+    deleteRun(runId: string): Promise<void>;
     readRunMeta(runId: string): Promise<RunMeta>;
     readTaskYaml(runId: string): Promise<string>;
+    readPipelineBody(runId: string): Promise<string | null>;
+    /**
+     * Atomic replace of the `run_manifest` JSON blob (build → redact → write).
+     * Pass `null` to clear.
+     */
+    updateRunManifest(runId: string, manifest: unknown): Promise<void>;
     /** Opaque run workspace root for agents and artifact tools. */
     getWorkspaceDir(runId: string): string;
     ensureStageWorkspace(runId: string, stageId: string): Promise<void>;
@@ -314,6 +421,8 @@ export interface RunStore {
     getLatestStageExecution(runId: string, stageId: string): Promise<StageExecution | null>;
     countStageAttempts(runId: string, stageId: string): Promise<number>;
     getStageExecution(runId: string, stageId: string, attempt: number): Promise<StageExecution>;
+    /** Latest attempt rows whose status is `interrupted` (targeted scan; not listRuns). */
+    listInterruptedStageExecutions(): Promise<StageExecution[]>;
     updateStageExecution(runId: string, stageId: string, attempt: number, patch: StageExecutionPatch): Promise<void>;
     /** Create or update evidence for one check in a stage execution attempt. */
     upsertVerificationCheckResult(runId: string, stageId: string, result: VerificationCheckResultPatch, options?: {
@@ -333,8 +442,10 @@ export interface RunStore {
     }): Promise<void>;
     listStageEvents(runId: string, stageId: string, attempt?: number): Promise<StageLogEvent[]>;
     listRuns(filter?: ListRunsFilter): Promise<RunSummary[]>;
-    /** Every distinct non-empty project_root recorded across all runs. */
-    listProjectRoots(): Promise<string[]>;
+    /** Idempotent upsert; returns the realpath/resolve-normalized absolute key. */
+    ensureProject(absPath: string): Promise<string>;
+    /** Absolute roots from the durable projects registry. */
+    listRegisteredProjects(): Promise<string[]>;
     readRun(runId: string): Promise<RunDetail>;
     updatePipelineDag(runId: string, dag: RunPipelineDagSnapshot): Promise<void>;
     createFeedbackLoop(runId: string, input: CreateFeedbackLoopInput): Promise<FeedbackLoopRecord>;
@@ -364,4 +475,4 @@ export interface RunStore {
 }
 export declare function stageStatusFromEvents(events: StageLogEvent[]): StageSnapshot["status"];
 export declare function findUnhandledFailedStage(stages: StageSnapshot[], dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null): StageSnapshot | undefined;
-export declare function deriveStatusFromStages(stages: StageSnapshot[], dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null): RunStatus;
+export declare function deriveStatusFromStages(stages: StageSnapshot[], dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null, currentStatus?: RunStatus): RunStatus;