stageflow 0.25.0 → 0.27.0

package/dist/runstore/backup.js

@@ -0,0 +1,292 @@
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, createReadStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createGzip } from "node:zlib";
+import { pipeline } from "node:stream/promises";
+import { createWriteStream } from "node:fs";
+import Database from "better-sqlite3";
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { readFilesystemSize } from "./diskUsage.js";
+import { isInsideDir } from "./workspaceLayout.js";
+export class BackupError extends Error {
+    code;
+    detail;
+    constructor(message, code, detail) {
+        super(message);
+        this.name = "BackupError";
+        this.code = code;
+        if (detail !== undefined)
+            this.detail = detail;
+    }
+}
+const SECRET_WARNING = "This backup may contain provider credentials and must be treated as a secret.";
+const FREE_SPACE_MARGIN_BYTES = 8 * 1024 * 1024;
+export function backupsDir(homeDir = globalStageflowHome()) {
+    return path.join(homeDir, "backups");
+}
+export function defaultBackupOutPath(homeDir = globalStageflowHome(), now = new Date(), dbOnly = false) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    const ext = dbOnly ? ".db" : ".tar.gz";
+    return path.join(backupsDir(homeDir), `stageflow-${stamp}${ext}`);
+}
+export function assertBackupOutPathAllowed(outPath, homeDir = globalStageflowHome()) {
+    const segments = outPath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new BackupError("backup_out_denied: path must not contain .. segments", "backup_out_denied");
+    }
+    const resolved = path.resolve(outPath);
+    const worktrees = path.resolve(homeDir, "worktrees");
+    const runs = path.resolve(homeDir, "runs");
+    if (isInsideDir(resolved, worktrees) || isInsideDir(resolved, runs)) {
+        throw new BackupError("backup_out_denied: refusing to write under worktrees/ or runs/", "backup_out_denied", { path: resolved });
+    }
+    return resolved;
+}
+function fingerprint(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const st = statSync(filePath);
+    return `${st.size}:${Math.trunc(st.mtimeMs)}`;
+}
+function stateDbTripletBytes(homeDir) {
+    let total = 0;
+    for (const name of ["state.db", "state.db-wal", "state.db-shm"]) {
+        const p = path.join(homeDir, name);
+        if (!existsSync(p))
+            continue;
+        total += statSync(p).size;
+    }
+    return total;
+}
+export function verifyDbSnapshot(snapshotPath, expectedUserVersion) {
+    const db = new Database(snapshotPath, {
+        readonly: true,
+        fileMustExist: true,
+    });
+    try {
+        const qc = db.pragma("quick_check", { simple: true });
+        if (qc !== "ok") {
+            throw new BackupError(`backup_verify_failed: quick_check returned ${String(qc)}`, "backup_verify_failed", { quick_check: qc });
+        }
+        const version = db.pragma("user_version", { simple: true });
+        if (version !== expectedUserVersion) {
+            throw new BackupError(`backup_verify_failed: user_version ${version} != source ${expectedUserVersion}`, "backup_verify_failed", { user_version: version, expected: expectedUserVersion });
+        }
+        if (existsSync(`${snapshotPath}-wal`) || existsSync(`${snapshotPath}-shm`)) {
+            throw new BackupError("backup_verify_failed: snapshot has WAL/SHM sidecars", "backup_verify_failed");
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+function sha256File(filePath) {
+    const hash = createHash("sha256");
+    hash.update(readFileSync(filePath));
+    return hash.digest("hex");
+}
+function writeUstarHeader(name, size, mode) {
+    const buf = Buffer.alloc(512, 0);
+    const nameBytes = Buffer.from(name, "utf8");
+    if (nameBytes.length > 100) {
+        throw new Error(`tar member name too long: ${name}`);
+    }
+    nameBytes.copy(buf, 0);
+    buf.write(mode.toString(8).padStart(7, "0"), 100, 7, "utf8");
+    buf.write("0000000", 108, 7, "utf8");
+    buf.write("0000000", 116, 7, "utf8");
+    buf.write(size.toString(8).padStart(11, "0"), 124, 11, "utf8");
+    buf.write(Math.floor(Date.now() / 1000).toString(8).padStart(11, "0"), 136, 11, "utf8");
+    buf.write("        ", 148, 8, "utf8");
+    buf[156] = 0x30; // regular file
+    Buffer.from("ustar\0", "utf8").copy(buf, 257);
+    Buffer.from("00", "utf8").copy(buf, 263);
+    let sum = 0;
+    for (let i = 0; i < 512; i += 1)
+        sum += buf[i];
+    buf.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "utf8");
+    return buf;
+}
+async function writeTarGz(archivePath, members) {
+    const partial = `${archivePath}.partial`;
+    if (existsSync(partial))
+        rmSync(partial, { force: true });
+    const gzip = createGzip();
+    const out = createWriteStream(partial, { mode: 0o600 });
+    const writing = pipeline(gzip, out);
+    for (const member of members) {
+        const data = readFileSync(member.filePath);
+        gzip.write(writeUstarHeader(member.name, data.length, member.mode));
+        gzip.write(data);
+        const pad = (512 - (data.length % 512)) % 512;
+        if (pad > 0)
+            gzip.write(Buffer.alloc(pad, 0));
+    }
+    gzip.write(Buffer.alloc(1024, 0));
+    gzip.end();
+    await writing;
+    chmodSync(partial, 0o600);
+    renameSync(partial, archivePath);
+    chmodSync(archivePath, 0o600);
+}
+export async function createBackup(options) {
+    const homeDir = options.homeDir ?? globalStageflowHome();
+    const dbOnly = options.dbOnly === true;
+    const noCredentials = options.noCredentials === true;
+    const includeA2a = options.includeA2aArtifacts === true;
+    const now = options.now?.() ?? new Date();
+    const createdAt = now.toISOString();
+    const outPath = assertBackupOutPathAllowed(options.outPath ?? defaultBackupOutPath(homeDir, now, dbOnly), homeDir);
+    mkdirSync(path.dirname(outPath), { recursive: true });
+    const freeReader = options.freeSpace ?? readFilesystemSize;
+    const free = await freeReader(homeDir);
+    const needed = stateDbTripletBytes(homeDir) + FREE_SPACE_MARGIN_BYTES;
+    if (free.freeBytes < needed) {
+        throw new BackupError(`backup_insufficient_disk: need ~${needed} bytes free, have ${free.freeBytes}`, "backup_insufficient_disk", { needed_bytes: needed, free_bytes: free.freeBytes });
+    }
+    const settingsPath = path.join(homeDir, "settings.json");
+    const authPath = path.join(homeDir, "agent", "auth.json");
+    const settingsBefore = fingerprint(settingsPath);
+    const authBefore = fingerprint(authPath);
+    const staging = await mkdtemp(path.join(tmpdir(), "sf-backup-"));
+    const snapshotPath = path.join(staging, "state.db");
+    try {
+        const { userVersion } = await options.store.snapshotInto(snapshotPath);
+        verifyDbSnapshot(snapshotPath, userVersion);
+        if (dbOnly) {
+            const partial = `${outPath}.partial`;
+            if (existsSync(partial))
+                rmSync(partial, { force: true });
+            if (existsSync(outPath))
+                rmSync(outPath, { force: true });
+            copyFileSync(snapshotPath, partial);
+            chmodSync(partial, 0o600);
+            try {
+                renameSync(partial, outPath);
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === "EXDEV") {
+                    throw new BackupError("backup_cross_device: stage partial beside target on the same filesystem", "backup_cross_device");
+                }
+                throw err;
+            }
+            chmodSync(outPath, 0o600);
+            const bytes = statSync(outPath).size;
+            return {
+                path: outPath,
+                bytes,
+                sha256: sha256File(outPath),
+                schema_version: userVersion,
+                stageflow_version: PACKAGE_VERSION,
+                created_at: createdAt,
+                contents: ["state.db"],
+            };
+        }
+        const settingsAfter = fingerprint(settingsPath);
+        const authAfter = fingerprint(authPath);
+        const fingerprintSkew = settingsBefore !== settingsAfter || authBefore !== authAfter;
+        const contents = ["state.db", "manifest.json"];
+        const members = [
+            { name: "state.db", filePath: snapshotPath, mode: 0o600 },
+        ];
+        if (existsSync(settingsPath)) {
+            const stagedSettings = path.join(staging, "settings.json");
+            copyFileSync(settingsPath, stagedSettings);
+            members.push({
+                name: "settings.json",
+                filePath: stagedSettings,
+                mode: 0o600,
+            });
+            contents.push("settings.json");
+        }
+        if (!noCredentials && existsSync(authPath)) {
+            const stagedAuth = path.join(staging, "auth.json");
+            copyFileSync(authPath, stagedAuth);
+            chmodSync(stagedAuth, 0o600);
+            members.push({
+                name: "agent/auth.json",
+                filePath: stagedAuth,
+                mode: 0o600,
+            });
+            contents.push("agent/auth.json");
+        }
+        if (includeA2a) {
+            const a2aRoot = path.join(homeDir, "a2a-artifacts");
+            if (existsSync(a2aRoot)) {
+                contents.push("a2a-artifacts");
+            }
+        }
+        const manifest = {
+            created_at: createdAt,
+            stageflow_version: PACKAGE_VERSION,
+            schema_version: userVersion,
+            contents,
+            db_only: false,
+            credentials_included: !noCredentials && existsSync(authPath),
+            a2a_artifacts_included: includeA2a,
+            settings_fingerprint_before: settingsBefore,
+            settings_fingerprint_after: settingsAfter,
+            auth_fingerprint_before: authBefore,
+            auth_fingerprint_after: authAfter,
+            fingerprint_skew: fingerprintSkew,
+            secret_warning: SECRET_WARNING,
+        };
+        const manifestPath = path.join(staging, "manifest.json");
+        writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        members.push({
+            name: "manifest.json",
+            filePath: manifestPath,
+            mode: 0o600,
+        });
+        if (existsSync(outPath))
+            rmSync(outPath, { force: true });
+        await writeTarGz(outPath, members);
+        const bytes = statSync(outPath).size;
+        return {
+            path: outPath,
+            bytes,
+            sha256: sha256File(outPath),
+            schema_version: userVersion,
+            stageflow_version: PACKAGE_VERSION,
+            created_at: createdAt,
+            contents,
+        };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+export async function resolveBackupDownloadPath(name, homeDir = globalStageflowHome()) {
+    if (typeof name !== "string" ||
+        name.trim() === "" ||
+        name.includes("..") ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        path.isAbsolute(name) ||
+        name.toLowerCase().endsWith(".partial")) {
+        throw new BackupError("backup_out_denied: invalid backup name", "backup_out_denied");
+    }
+    const root = backupsDir(homeDir);
+    const candidate = path.resolve(root, name);
+    const { classifyRealPathContainment } = await import("./workspaceLayout.js");
+    const containment = await classifyRealPathContainment(candidate, root);
+    if (containment.status === "missing") {
+        throw new BackupError(`backup not found: ${name}`, "backup_out_denied");
+    }
+    if (containment.status === "outside") {
+        throw new BackupError("backup_out_denied: path escapes backups directory", "backup_out_denied");
+    }
+    if (path.basename(containment.realPath).toLowerCase().endsWith(".partial")) {
+        throw new BackupError("backup_out_denied: invalid backup name", "backup_out_denied");
+    }
+    return containment.realPath;
+}
+export function openBackupReadStream(filePath) {
+    return createReadStream(filePath);
+}

package/dist/runstore/createStore.d.ts

@@ -1,13 +1,30 @@
-import type Database from "better-sqlite3";
+import Database from "better-sqlite3";
+import type { EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
 import type { RunStore } from "./port.js";
+import { type StoreSchemaErrorCode } from "./sqlite/storeSchemaError.js";
 export type RunStoreKind = "sqlite";
+export type RunStoreOpenerMode = "assert" | "migrate";
 export type RunStoreConfig = {
     /** Project / factory root. Store data lives under `<rootDir>/.stageflow`. */
     rootDir: string;
     /** Defaults to `SF_STORE` env or `"sqlite"`. */
     kind?: RunStoreKind | "disk";
+    /** Default `assert`; Host and tests that need a fresh schema pass `migrate`. */
+    openerMode?: RunStoreOpenerMode;
 };
 export declare const DISK_STORE_REJECTED = "SF_STORE=disk is no longer a live RunStore. SQLite is the only adapter. Disk-era .stageflow/runs trees import automatically when the SQLite store is empty.";
+export declare function storeNeedsHostMigration(rootDir: string): boolean;
+export declare function createRunStoreAfterHostEnsure(config: RunStoreConfig, ensureService: () => Promise<EnsureGlobalServiceResult>): Promise<{
+    ok: true;
+    store: RunStore;
+} | {
+    ok: false;
+    message: string;
+    reason?: Extract<EnsureGlobalServiceResult, {
+        ok: false;
+    }>["reason"];
+    code?: StoreSchemaErrorCode;
+}>;
 /**
  * Composition-root factory: hands back the concrete SQLite connection alongside the `RunStore`,
  * for the one caller wiring a second, colocated store (A2A's tables) into the same `state.db`

package/dist/runstore/createStore.js

@@ -1,6 +1,11 @@
-import { mkdirSync } from "node:fs";
-import { migrateLegacyStoreRoot, storeRootFor } from "./paths.js";
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import { assertStageflowHomeWritable, globalStageflowHome, } from "../project/globalHome.js";
+import { flattenNestedGlobalStore, isGlobalStageflowHome, migrateLegacyStoreRoot, resolveStoreRoot, } from "./paths.js";
 import { SqliteRunStore } from "./sqlite/SqliteRunStore.js";
+import { CURRENT_SCHEMA_VERSION } from "./sqlite/migrations/index.js";
+import { StoreSchemaError } from "./sqlite/storeSchemaError.js";
 export const DISK_STORE_REJECTED = "SF_STORE=disk is no longer a live RunStore. SQLite is the only adapter. Disk-era .stageflow/runs trees import automatically when the SQLite store is empty.";
 function resolveKind(kind) {
     const raw = kind ?? process.env.SF_STORE?.trim().toLowerCase();
@@ -10,6 +15,50 @@ function resolveKind(kind) {
     }
     return "sqlite";
 }
+function resolveOpenerMode(config) {
+    if (config.openerMode !== undefined) {
+        return config.openerMode;
+    }
+    if (process.env.VITEST === "true") {
+        return "migrate";
+    }
+    return "assert";
+}
+export function storeNeedsHostMigration(rootDir) {
+    const storeRoot = resolveStoreRoot(rootDir);
+    const dbPath = path.join(storeRoot, "state.db");
+    if (!existsSync(dbPath)) {
+        return true;
+    }
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const version = db.pragma("user_version", { simple: true });
+        return version < CURRENT_SCHEMA_VERSION;
+    }
+    finally {
+        db.close();
+    }
+}
+export async function createRunStoreAfterHostEnsure(config, ensureService) {
+    if (storeNeedsHostMigration(config.rootDir)) {
+        const ensured = await ensureService();
+        if (!ensured.ok) {
+            return { ok: false, message: ensured.message, reason: ensured.reason };
+        }
+    }
+    try {
+        return {
+            ok: true,
+            store: createRunStore({ ...config, openerMode: "assert" }),
+        };
+    }
+    catch (err) {
+        if (err instanceof StoreSchemaError) {
+            return { ok: false, message: err.message, code: err.code };
+        }
+        throw err;
+    }
+}
 /**
  * Composition-root factory: hands back the concrete SQLite connection alongside the `RunStore`,
  * for the one caller wiring a second, colocated store (A2A's tables) into the same `state.db`
@@ -17,10 +66,20 @@ function resolveKind(kind) {
  */
 export function createRunStoreWithConnection(config) {
     resolveKind(config.kind);
-    migrateLegacyStoreRoot(config.rootDir);
-    const storeRoot = storeRootFor(config.rootDir);
+    const globalHome = isGlobalStageflowHome(config.rootDir);
+    if (globalHome) {
+        assertStageflowHomeWritable();
+        const home = globalStageflowHome();
+        mkdirSync(home, { recursive: true });
+        flattenNestedGlobalStore(home);
+    }
+    else {
+        migrateLegacyStoreRoot(config.rootDir);
+    }
+    const storeRoot = resolveStoreRoot(config.rootDir);
     mkdirSync(storeRoot, { recursive: true });
-    const store = new SqliteRunStore(storeRoot);
+    const openerMode = resolveOpenerMode(config);
+    const store = new SqliteRunStore(storeRoot, { openerMode });
     return { store, connection: store.connection };
 }
 /**

package/dist/runstore/debugBundle.d.ts

@@ -0,0 +1,60 @@
+import { type HostConfigPublicEcho } from "../config/hostConfig.js";
+import { type RunExportPayload } from "./exportRunPayload.js";
+import type { RunStore, StageLogEvent } from "./port.js";
+import { readStageVerificationHistory } from "./verificationHistory.js";
+export declare const DEBUG_BUNDLE_EVENTS_MAX_BYTES: number;
+export declare const DEBUG_BUNDLE_VERIFICATION_MAX_BYTES: number;
+export declare const DEBUG_BUNDLE_STREAM_LOG_MAX_BYTES: number;
+export declare const DEBUG_BUNDLE_DIFF_MAX_BYTES = 262144;
+export declare const DEBUG_BUNDLE_MAX_STAGES = 64;
+export declare const DEBUG_BUNDLE_MAX_ATTEMPTS_PER_STAGE = 32;
+export type DebugCappedMarker = {
+    truncated?: boolean;
+    original_bytes?: number;
+};
+export type DebugStageEventsSection = DebugCappedMarker & {
+    stages: Array<{
+        stage_id: string;
+        attempts: Array<{
+            attempt: number;
+            events: StageLogEvent[];
+        }>;
+    }>;
+};
+export type DebugVerificationSection = DebugCappedMarker & {
+    stages: Awaited<ReturnType<typeof readStageVerificationHistory>>[];
+};
+export type DebugStreamLogTail = DebugCappedMarker & {
+    stage_id: string;
+    attempt: number;
+    text: string;
+};
+export type DebugStreamLogsSection = DebugCappedMarker & {
+    tails: DebugStreamLogTail[];
+};
+export type DebugDiffSection = ({
+    available: true;
+    mode: "stat" | "patch";
+    base_sha: string;
+    base_source: "resolved_sha" | "HEAD";
+    content: string;
+    untracked: string[];
+} & DebugCappedMarker) | {
+    available: false;
+    code?: string;
+    error?: string;
+};
+export type DebugBundle = RunExportPayload & {
+    stage_events: DebugStageEventsSection;
+    verification: DebugVerificationSection;
+    diff: DebugDiffSection;
+    stream_log_tails: DebugStreamLogsSection;
+    host_config: HostConfigPublicEcho;
+};
+export declare function buildDebugBundle(store: RunStore, runId: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    streamLogMaxBytes?: number;
+    eventsMaxBytes?: number;
+    verificationMaxBytes?: number;
+    diffMaxBytes?: number;
+}): Promise<DebugBundle>;

package/dist/runstore/debugBundle.js

@@ -0,0 +1,143 @@
+import { loadHostConfig, redactHostConfig, } from "../config/hostConfig.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
+import { redact } from "../logging/redact.js";
+import { DEFAULT_DIFF_MAX_BYTES, getRunDiff, } from "../mcp/checkoutTools.js";
+import { readStreamLogTail } from "../mcp/tailStreamLog.js";
+import { buildRunExportPayload, } from "./exportRunPayload.js";
+import { readStageVerificationHistory } from "./verificationHistory.js";
+import { attemptStreamLogPath } from "./workspaceLayout.js";
+export const DEBUG_BUNDLE_EVENTS_MAX_BYTES = 256 * 1024;
+export const DEBUG_BUNDLE_VERIFICATION_MAX_BYTES = 256 * 1024;
+export const DEBUG_BUNDLE_STREAM_LOG_MAX_BYTES = 64 * 1024;
+export const DEBUG_BUNDLE_DIFF_MAX_BYTES = DEFAULT_DIFF_MAX_BYTES;
+export const DEBUG_BUNDLE_MAX_STAGES = 64;
+export const DEBUG_BUNDLE_MAX_ATTEMPTS_PER_STAGE = 32;
+function utf8Bytes(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function takeUtf8Tail(text, maxBytes) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= maxBytes)
+        return { text };
+    return {
+        text: buf.subarray(buf.length - maxBytes).toString("utf8"),
+        truncated: true,
+        original_bytes: buf.length,
+    };
+}
+function enforceSectionCap(section, maxBytes, shrink) {
+    const encoded = JSON.stringify(section);
+    const original_bytes = utf8Bytes(encoded);
+    if (original_bytes <= maxBytes)
+        return section;
+    return {
+        ...shrink(section),
+        truncated: true,
+        original_bytes,
+    };
+}
+function emptyStageEvents() {
+    return { stages: [] };
+}
+function emptyVerification() {
+    return { stages: [] };
+}
+export async function buildDebugBundle(store, runId, options = {}) {
+    const detail = await store.readRun(runId);
+    const exportPayload = buildRunExportPayload(detail);
+    const workspaceDir = store.getWorkspaceDir(runId);
+    const streamLogMaxBytes = options.streamLogMaxBytes ?? DEBUG_BUNDLE_STREAM_LOG_MAX_BYTES;
+    const eventsMaxBytes = options.eventsMaxBytes ?? DEBUG_BUNDLE_EVENTS_MAX_BYTES;
+    const verificationMaxBytes = options.verificationMaxBytes ?? DEBUG_BUNDLE_VERIFICATION_MAX_BYTES;
+    const diffMaxBytes = options.diffMaxBytes ?? DEBUG_BUNDLE_DIFF_MAX_BYTES;
+    const stageSnapshots = detail.stages.slice(0, DEBUG_BUNDLE_MAX_STAGES);
+    const stagesOmitted = detail.stages.length > DEBUG_BUNDLE_MAX_STAGES;
+    const stageEventRows = [];
+    const verificationRows = [];
+    const streamTails = [];
+    for (const stage of stageSnapshots) {
+        const executions = await store.listStageExecutions(runId, stage.stage_id);
+        const attemptNums = executions.length > 0
+            ? executions.map((e) => e.attempt)
+            : stage.attempt_count > 0
+                ? Array.from({ length: stage.attempt_count }, (_, i) => i + 1)
+                : [];
+        const cappedAttempts = attemptNums.slice(0, DEBUG_BUNDLE_MAX_ATTEMPTS_PER_STAGE);
+        const attemptEvents = [];
+        for (const attempt of cappedAttempts) {
+            const events = await store.listStageEvents(runId, stage.stage_id, attempt);
+            attemptEvents.push({ attempt, events });
+            const logPath = attemptStreamLogPath(workspaceDir, stage.stage_id, attempt);
+            const tail = await readStreamLogTail(logPath, undefined);
+            const capped = takeUtf8Tail(tail.text, streamLogMaxBytes);
+            streamTails.push({
+                stage_id: stage.stage_id,
+                attempt,
+                text: capped.text,
+                ...(capped.truncated
+                    ? {
+                        truncated: true,
+                        original_bytes: capped.original_bytes,
+                    }
+                    : {}),
+            });
+        }
+        if (attemptNums.length === 0) {
+            const events = await store.listStageEvents(runId, stage.stage_id);
+            attemptEvents.push({ attempt: 0, events });
+        }
+        stageEventRows.push({
+            stage_id: stage.stage_id,
+            attempts: attemptEvents,
+        });
+        verificationRows.push(await readStageVerificationHistory(store, runId, stage.stage_id));
+    }
+    const stage_events = enforceSectionCap({
+        stages: stageEventRows,
+        ...(stagesOmitted ? { truncated: true } : {}),
+    }, eventsMaxBytes, () => emptyStageEvents());
+    const verification = enforceSectionCap({
+        stages: verificationRows,
+        ...(stagesOmitted ? { truncated: true } : {}),
+    }, verificationMaxBytes, () => emptyVerification());
+    const stream_log_tails = enforceSectionCap({ tails: streamTails }, Math.max(streamLogMaxBytes, streamLogMaxBytes * Math.max(1, streamTails.length)), (full) => ({
+        tails: full.tails.map((t) => ({
+            stage_id: t.stage_id,
+            attempt: t.attempt,
+            text: "",
+            truncated: true,
+            original_bytes: t.original_bytes ?? utf8Bytes(t.text),
+        })),
+    }));
+    const diffResult = await getRunDiff(store, runId, {
+        mode: "patch",
+        maxBytes: diffMaxBytes,
+    });
+    const diff = diffResult.ok
+        ? {
+            available: true,
+            mode: diffResult.mode,
+            base_sha: diffResult.base_sha,
+            base_source: diffResult.base_source,
+            content: diffResult.content,
+            untracked: diffResult.untracked,
+            ...(diffResult.truncated ? { truncated: true } : {}),
+        }
+        : {
+            available: false,
+            code: diffResult.code,
+            error: diffResult.error,
+        };
+    const host_config = redactHostConfig(loadHostConfig({ env: options.env ?? process.env }));
+    const bundle = {
+        ...exportPayload,
+        stage_events,
+        verification,
+        diff,
+        stream_log_tails,
+        host_config,
+    };
+    return redact(bundle, {
+        namedSecrets: getNamedSecrets(),
+    });
+}

package/dist/runstore/diskUsage.d.ts

@@ -0,0 +1,50 @@
+import type { RunStore } from "./port.js";
+export type DiskBreakdown = {
+    runs_bytes: number;
+    worktrees_bytes: number;
+    repos_bytes: number;
+    state_db_bytes: number;
+    a2a_artifacts_bytes: number;
+    /** Shared dependency cache ($STAGEFLOW_HOME/cache); excluded from slim GC / per-run quotas. */
+    cache_bytes: number;
+    free_bytes: number;
+};
+export type FilesystemSize = {
+    freeBytes: number;
+    totalBytes: number;
+};
+export type FreeSpaceReader = (rootPath: string) => Promise<FilesystemSize>;
+export declare const DISK_WARN_LOG_PREFIX = "stageflow.disk_warn";
+export declare function getDiskUsageWalkCallCount(): number;
+export declare function resetDiskUsageWalkCallCount(): void;
+export declare function setFreeSpaceReaderForTests(reader: FreeSpaceReader | null): void;
+/** Walk `rootPath` summing `stat().blocks * 512`. Missing path → 0. */
+export declare function diskUsageOf(rootPath: string): Promise<number>;
+export declare function readFilesystemSize(rootPath: string): Promise<FilesystemSize>;
+/** Category breakdown for the durable root, reusing `diskUsageOf` for directory trees. */
+export declare function durableRootDiskBreakdown(durableRoot: string, options?: {
+    freeSpace?: FreeSpaceReader;
+}): Promise<DiskBreakdown>;
+/**
+ * Parse `STAGEFLOW_DISK_WARN_BYTES` / floor-style env: integer bytes or `N%` of filesystem.
+ * Empty / unset / invalid → undefined (no threshold).
+ */
+export declare function parseDiskBytesThreshold(raw: string | undefined, filesystemTotalBytes: number): number | undefined;
+/**
+ * Resolve `STAGEFLOW_MIN_FREE_DISK_BYTES`: bytes or `%` of filesystem.
+ * Unset / empty / invalid → `max(2 GiB, 10% of filesystemTotalBytes)`.
+ */
+export declare function resolveMinFreeDiskFloor(raw: string | undefined, filesystemTotalBytes: number): number;
+/**
+ * One named warning when free space is below `STAGEFLOW_DISK_WARN_BYTES`. Never throws.
+ * @returns true when a warning line was emitted
+ */
+export declare function warnDurableRootDiskIfNeeded(durableRoot: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    freeSpace?: FreeSpaceReader;
+    log?: (line: string) => void;
+}): Promise<boolean>;
+/** Measure one run workspace and persist `disk_bytes` / `disk_measured_at`. */
+export declare function refreshRunDiskUsage(store: RunStore, runId: string, options?: {
+    now?: Date;
+}): Promise<number>;