stageflow 0.25.0 → 0.30.0

package/dist/runstore/restore.js

@@ -0,0 +1,355 @@
+import { chmodSync, copyFileSync, createReadStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createGunzip } from "node:zlib";
+import { tmpdir } from "node:os";
+import path from "node:path";
+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 { CURRENT_SCHEMA_VERSION } from "./sqlite/migrations/index.js";
+import { StoreSchemaError } from "./sqlite/storeSchemaError.js";
+import { assertStoreQuickCheck } from "./sqlite/applyStorePragmas.js";
+import { verifyDbSnapshot } from "./backup.js";
+import { probeGlobalServiceDetailed, } from "../server/ensureGlobalService.js";
+export class RestoreError extends Error {
+    code;
+    detail;
+    constructor(message, code, detail) {
+        super(message);
+        this.name = "RestoreError";
+        this.code = code;
+        if (detail !== undefined)
+            this.detail = detail;
+    }
+}
+const ALLOWED_MEMBERS = new Set([
+    "state.db",
+    "settings.json",
+    "agent/auth.json",
+    "manifest.json",
+]);
+export function restorePendingDir(homeDir = globalStageflowHome()) {
+    return path.join(homeDir, "restore-pending");
+}
+export function restoreMarkerPath(homeDir = globalStageflowHome()) {
+    return path.join(restorePendingDir(homeDir), "marker.json");
+}
+export function restoreAppliedPath(homeDir = globalStageflowHome()) {
+    return path.join(homeDir, "restore.applied");
+}
+export function restoreFailedPath(homeDir = globalStageflowHome()) {
+    return path.join(homeDir, "restore.failed");
+}
+function majorVersion(version) {
+    return version.split(".")[0] ?? version;
+}
+async function gunzipToFile(src, dest) {
+    await pipeline(createReadStream(src), createGunzip(), createWriteStream(dest));
+}
+function parseUstarMembers(tarPath, destDir) {
+    const buf = readFileSync(tarPath);
+    const written = [];
+    let offset = 0;
+    while (offset + 512 <= buf.length) {
+        const header = buf.subarray(offset, offset + 512);
+        offset += 512;
+        if (header.every((b) => b === 0))
+            break;
+        const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
+        const sizeOctal = header.subarray(124, 135).toString("utf8").replace(/\0| /g, "");
+        const size = Number.parseInt(sizeOctal, 8) || 0;
+        const type = header[156];
+        if (name.includes("..") || path.isAbsolute(name) || name.startsWith("/")) {
+            throw new RestoreError(`restore_unsafe_member: ${name}`, "restore_unsafe_member");
+        }
+        if (type === 0x32 /* symlink */ || type === 0x31 /* hard link */) {
+            throw new RestoreError(`restore_unsafe_member: link ${name}`, "restore_unsafe_member");
+        }
+        if (!ALLOWED_MEMBERS.has(name) && name !== "") {
+            throw new RestoreError(`restore_unsafe_member: ${name} not in allowlist`, "restore_unsafe_member");
+        }
+        const data = buf.subarray(offset, offset + size);
+        offset += size + ((512 - (size % 512)) % 512);
+        if (name === "")
+            continue;
+        const outPath = path.join(destDir, name);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        writeFileSync(outPath, data);
+        written.push(name);
+    }
+    return written;
+}
+export async function extractVerifiedArchive(archivePath) {
+    const stagingDir = await mkdtemp(path.join(tmpdir(), "sf-restore-"));
+    try {
+        let dbPath = archivePath;
+        let manifest = null;
+        if (archivePath.endsWith(".tar.gz") || archivePath.endsWith(".tgz")) {
+            const tarPath = path.join(stagingDir, "archive.tar");
+            await gunzipToFile(archivePath, tarPath);
+            parseUstarMembers(tarPath, stagingDir);
+            dbPath = path.join(stagingDir, "state.db");
+            const manifestFile = path.join(stagingDir, "manifest.json");
+            if (existsSync(manifestFile)) {
+                manifest = JSON.parse(readFileSync(manifestFile, "utf8"));
+            }
+        }
+        else {
+            const copied = path.join(stagingDir, "state.db");
+            copyFileSync(archivePath, copied);
+            dbPath = copied;
+        }
+        if (!existsSync(dbPath)) {
+            throw new RestoreError("restore_verify_failed: archive missing state.db", "restore_verify_failed");
+        }
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        let schemaVersion;
+        try {
+            assertStoreQuickCheck(db);
+            schemaVersion = db.pragma("user_version", { simple: true });
+        }
+        finally {
+            db.close();
+        }
+        if (schemaVersion > CURRENT_SCHEMA_VERSION) {
+            throw new StoreSchemaError(`store_schema_too_new: on_disk=${schemaVersion} binary_max=${CURRENT_SCHEMA_VERSION}`, "store_schema_too_new");
+        }
+        verifyDbSnapshot(dbPath, schemaVersion);
+        let missingA2aArtifactRows = 0;
+        if (manifest && manifest.a2a_artifacts_included !== true) {
+            const probe = new Database(dbPath, { readonly: true, fileMustExist: true });
+            try {
+                const row = probe
+                    .prepare("SELECT COUNT(*) AS c FROM sqlite_master WHERE type='table' AND name='a2a_artifacts'")
+                    .get();
+                if (row.c > 0) {
+                    const count = probe
+                        .prepare("SELECT COUNT(*) AS c FROM a2a_artifacts")
+                        .get();
+                    missingA2aArtifactRows = count.c;
+                }
+            }
+            catch {
+                missingA2aArtifactRows = 0;
+            }
+            finally {
+                probe.close();
+            }
+        }
+        return {
+            stagingDir,
+            dbPath,
+            manifest,
+            schemaVersion,
+            missingA2aArtifactRows,
+        };
+    }
+    catch (err) {
+        await rm(stagingDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+export async function assertHostDownForRestore(options) {
+    const probe = options?.probe ?? probeGlobalServiceDetailed;
+    const result = await probe();
+    if (result === "up") {
+        throw new RestoreError("restore_host_live: Host is up (GET /livez). Stop it before restore.", "restore_host_live");
+    }
+}
+/**
+ * Open an exclusive lock on state.db with busy_timeout=0 and hold it through
+ * the provided callback (used to relocate the DB triplet safely).
+ */
+export function withExclusiveStoreLock(homeDir, fn) {
+    const dbPath = path.join(homeDir, "state.db");
+    if (!existsSync(dbPath)) {
+        return fn();
+    }
+    const lockDb = new Database(dbPath);
+    try {
+        lockDb.pragma("busy_timeout = 0");
+        try {
+            lockDb.prepare("BEGIN EXCLUSIVE").run();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/SQLITE_BUSY|database is locked/i.test(message)) {
+                throw new RestoreError("restore_store_busy: another process holds state.db", "restore_store_busy");
+            }
+            throw err;
+        }
+        return fn();
+    }
+    finally {
+        try {
+            lockDb.exec("ROLLBACK");
+        }
+        catch {
+            // ignore
+        }
+        lockDb.close();
+    }
+}
+function moveAsideTriplet(homeDir, stamp) {
+    for (const name of ["state.db", "state.db-wal", "state.db-shm"]) {
+        const from = path.join(homeDir, name);
+        if (!existsSync(from))
+            continue;
+        renameSync(from, `${from}.pre-restore-${stamp}`);
+    }
+}
+function assertNoSidecars(dbPath) {
+    for (const side of [`${dbPath}-wal`, `${dbPath}-shm`]) {
+        if (existsSync(side)) {
+            unlinkSync(side);
+        }
+    }
+    if (existsSync(`${dbPath}-wal`) || existsSync(`${dbPath}-shm`)) {
+        throw new RestoreError("restore_verify_failed: stale WAL/SHM sidecars remain", "restore_verify_failed");
+    }
+}
+export async function applyRestoreArchive(options) {
+    const homeDir = options.homeDir ?? globalStageflowHome();
+    await assertHostDownForRestore({ probe: options.probe });
+    const verified = await extractVerifiedArchive(options.archivePath);
+    try {
+        if (verified.manifest?.stageflow_version &&
+            majorVersion(verified.manifest.stageflow_version) !==
+                majorVersion(PACKAGE_VERSION) &&
+            options.force !== true) {
+            throw new RestoreError(`restore_version_mismatch: archive ${verified.manifest.stageflow_version} vs binary ${PACKAGE_VERSION} (pass --force)`, "restore_version_mismatch");
+        }
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const restoreCredentials = options.restoreCredentials !== false;
+        withExclusiveStoreLock(homeDir, () => {
+            moveAsideTriplet(homeDir, stamp);
+            const destDb = path.join(homeDir, "state.db");
+            copyFileSync(verified.dbPath, destDb);
+            assertNoSidecars(destDb);
+            if (restoreCredentials) {
+                const settingsSrc = path.join(verified.stagingDir, "settings.json");
+                const authSrc = path.join(verified.stagingDir, "agent", "auth.json");
+                if (existsSync(settingsSrc)) {
+                    copyFileSync(settingsSrc, path.join(homeDir, "settings.json"));
+                }
+                if (existsSync(authSrc)) {
+                    const agentDir = path.join(homeDir, "agent");
+                    mkdirSync(agentDir, { recursive: true });
+                    try {
+                        chmodSync(agentDir, 0o700);
+                    }
+                    catch {
+                        // best-effort
+                    }
+                    const authDest = path.join(agentDir, "auth.json");
+                    copyFileSync(authSrc, authDest);
+                    try {
+                        chmodSync(authDest, 0o600);
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+            }
+        });
+        const check = new Database(path.join(homeDir, "state.db"));
+        try {
+            assertStoreQuickCheck(check);
+        }
+        finally {
+            check.close();
+        }
+        return {
+            schema_version: verified.schemaVersion,
+            missing_a2a_artifact_rows: verified.missingA2aArtifactRows,
+            pre_restore_stamp: stamp,
+        };
+    }
+    finally {
+        await rm(verified.stagingDir, { recursive: true, force: true });
+    }
+}
+export async function stageRestoreForBoot(options) {
+    const homeDir = options.homeDir ?? globalStageflowHome();
+    if (existsSync(restoreFailedPath(homeDir))) {
+        throw new RestoreError("restore_failed: clear restore.failed before staging another restore", "restore_failed");
+    }
+    const verified = await extractVerifiedArchive(options.archivePath);
+    await rm(verified.stagingDir, { recursive: true, force: true });
+    if (verified.manifest?.stageflow_version &&
+        majorVersion(verified.manifest.stageflow_version) !==
+            majorVersion(PACKAGE_VERSION)) {
+        throw new RestoreError(`restore_version_mismatch: archive ${verified.manifest.stageflow_version} vs binary ${PACKAGE_VERSION}`, "restore_version_mismatch");
+    }
+    const pending = restorePendingDir(homeDir);
+    mkdirSync(pending, { recursive: true });
+    const basename = `staged-${Date.now()}${path.extname(options.archivePath) || ".tar.gz"}`;
+    const stagedPath = path.join(pending, basename);
+    copyFileSync(options.archivePath, stagedPath);
+    const graceMs = options.graceMs ?? 8000;
+    const marker = {
+        archive: basename,
+        attempts: 0,
+        staged_at: new Date().toISOString(),
+        drain_deadline: new Date(Date.now() + graceMs).toISOString(),
+    };
+    writeFileSync(restoreMarkerPath(homeDir), `${JSON.stringify(marker, null, 2)}\n`);
+    return { marker, stagedPath };
+}
+export async function resolveBackupNameForRestore(name, homeDir = globalStageflowHome()) {
+    const { resolveBackupDownloadPath } = await import("./backup.js");
+    return resolveBackupDownloadPath(name, homeDir);
+}
+/**
+ * Apply a staged restore marker before opening the store for serving.
+ * Never re-applies restore.applied. Two failures → restore.failed (hard non-serve).
+ */
+export async function applyPendingRestoreAtBoot(homeDir = globalStageflowHome()) {
+    if (existsSync(restoreFailedPath(homeDir))) {
+        const raw = readFileSync(restoreFailedPath(homeDir), "utf8");
+        let reason = "restore.failed present";
+        try {
+            reason = JSON.parse(raw).reason ?? reason;
+        }
+        catch {
+            // keep default
+        }
+        return { status: "blocked", reason };
+    }
+    if (existsSync(restoreAppliedPath(homeDir))) {
+        return { status: "none" };
+    }
+    const markerFile = restoreMarkerPath(homeDir);
+    if (!existsSync(markerFile)) {
+        return { status: "none" };
+    }
+    const marker = JSON.parse(readFileSync(markerFile, "utf8"));
+    const archivePath = path.join(restorePendingDir(homeDir), marker.archive);
+    marker.attempts += 1;
+    writeFileSync(markerFile, `${JSON.stringify(marker, null, 2)}\n`);
+    try {
+        if (!existsSync(archivePath)) {
+            throw new RestoreError(`restore_not_found: staged archive missing (${marker.archive})`, "restore_not_found");
+        }
+        const result = await applyRestoreArchive({
+            archivePath,
+            homeDir,
+            force: true,
+            probe: async () => "unreachable",
+        });
+        writeFileSync(restoreAppliedPath(homeDir), `${JSON.stringify({ ...result, applied_at: new Date().toISOString() }, null, 2)}\n`);
+        rmSync(markerFile, { force: true });
+        return { status: "applied", result };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        if (marker.attempts >= 2) {
+            writeFileSync(restoreFailedPath(homeDir), `${JSON.stringify({ reason, attempts: marker.attempts, at: new Date().toISOString() }, null, 2)}\n`);
+            rmSync(markerFile, { force: true });
+            return { status: "failed", reason, attempts: marker.attempts };
+        }
+        return { status: "failed", reason, attempts: marker.attempts };
+    }
+}

package/dist/runstore/retention.d.ts

@@ -0,0 +1,27 @@
+import type { RunMeta, RunStatus } from "./port.js";
+export type RetentionDecision = "none" | "slim" | "purge";
+export type StatusRetentionWindow = {
+    slimMs: number;
+    purgeMs: number;
+};
+export type RetentionWindows = {
+    succeeded: StatusRetentionWindow;
+    failed: StatusRetentionWindow;
+    cancelled: StatusRetentionWindow;
+};
+export declare const DAY_MS: number;
+/** Defaults: succeeded 3d/30d; failed and cancelled 30d/90d (R30 / AE6). */
+export declare const DEFAULT_RETENTION_WINDOWS: RetentionWindows;
+export declare const DEFAULT_BARE_CACHE_TTL_MS: number;
+export declare const DEFAULT_SLIM_ARTIFACT_MAX_BYTES: number;
+export type RetentionRow = Pick<RunMeta, "status" | "finished_at" | "slimmed_at">;
+/** Resolve retention windows from KD1 defaults plus per-status env overrides. */
+export declare function retentionWindowsFromEnv(env?: NodeJS.ProcessEnv): RetentionWindows;
+export declare function bareCacheTtlFromEnv(env?: NodeJS.ProcessEnv): number;
+export declare function slimArtifactMaxBytesFromEnv(env?: NodeJS.ProcessEnv): number;
+/**
+ * Clock-injected eligibility. Reads `finished_at` only (KTD1), never `updated_at`.
+ * Already-slimmed rows past SLIM but not PURGE return `"none"` (R18).
+ */
+export declare function retentionDecision(row: RetentionRow, now: Date, windows?: RetentionWindows): RetentionDecision;
+export declare function isTerminalRunStatus(status: RunStatus | undefined): status is "succeeded" | "failed" | "cancelled";

package/dist/runstore/retention.js

@@ -0,0 +1,74 @@
+export const DAY_MS = 24 * 60 * 60 * 1000;
+/** Defaults: succeeded 3d/30d; failed and cancelled 30d/90d (R30 / AE6). */
+export const DEFAULT_RETENTION_WINDOWS = {
+    succeeded: { slimMs: 3 * DAY_MS, purgeMs: 30 * DAY_MS },
+    cancelled: { slimMs: 30 * DAY_MS, purgeMs: 90 * DAY_MS },
+    failed: { slimMs: 30 * DAY_MS, purgeMs: 90 * DAY_MS },
+};
+export const DEFAULT_BARE_CACHE_TTL_MS = 30 * DAY_MS;
+export const DEFAULT_SLIM_ARTIFACT_MAX_BYTES = 1024 * 1024;
+const TERMINAL = new Set([
+    "succeeded",
+    "failed",
+    "cancelled",
+]);
+function parsePositiveMs(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return undefined;
+    const n = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return n;
+}
+function windowFromEnv(env, status, defaults) {
+    const statusKey = status.toUpperCase();
+    return {
+        slimMs: parsePositiveMs(env[`STAGEFLOW_SLIM_${statusKey}_MS`]) ?? defaults.slimMs,
+        purgeMs: parsePositiveMs(env[`STAGEFLOW_PURGE_${statusKey}_MS`]) ??
+            defaults.purgeMs,
+    };
+}
+/** Resolve retention windows from KD1 defaults plus per-status env overrides. */
+export function retentionWindowsFromEnv(env = process.env) {
+    return {
+        succeeded: windowFromEnv(env, "succeeded", DEFAULT_RETENTION_WINDOWS.succeeded),
+        failed: windowFromEnv(env, "failed", DEFAULT_RETENTION_WINDOWS.failed),
+        cancelled: windowFromEnv(env, "cancelled", DEFAULT_RETENTION_WINDOWS.cancelled),
+    };
+}
+export function bareCacheTtlFromEnv(env = process.env) {
+    return (parsePositiveMs(env.STAGEFLOW_BARE_CACHE_TTL_MS) ?? DEFAULT_BARE_CACHE_TTL_MS);
+}
+export function slimArtifactMaxBytesFromEnv(env = process.env) {
+    return (parsePositiveMs(env.STAGEFLOW_SLIM_ARTIFACT_MAX_BYTES) ??
+        DEFAULT_SLIM_ARTIFACT_MAX_BYTES);
+}
+/**
+ * Clock-injected eligibility. Reads `finished_at` only (KTD1), never `updated_at`.
+ * Already-slimmed rows past SLIM but not PURGE return `"none"` (R18).
+ */
+export function retentionDecision(row, now, windows = DEFAULT_RETENTION_WINDOWS) {
+    const status = row.status;
+    if (status === undefined || !TERMINAL.has(status))
+        return "none";
+    if (row.finished_at === undefined || row.finished_at === "")
+        return "none";
+    const finishedMs = Date.parse(row.finished_at);
+    if (!Number.isFinite(finishedMs))
+        return "none";
+    const ageMs = now.getTime() - finishedMs;
+    if (ageMs < 0)
+        return "none";
+    const window = windows[status];
+    if (ageMs >= window.purgeMs)
+        return "purge";
+    if (ageMs >= window.slimMs && row.slimmed_at === undefined)
+        return "slim";
+    return "none";
+}
+export function isTerminalRunStatus(status) {
+    return status !== undefined && TERMINAL.has(status);
+}

package/dist/runstore/runManifest.d.ts

@@ -0,0 +1,146 @@
+import type { CallerSurface } from "../server/requestAuthContext.js";
+import type { ToolchainCheck } from "../preflight/toolchain.js";
+import type { SkillOrigin } from "../config/listSkills.js";
+import type { ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
+import type { SkillsPayload } from "../runtime/runSkills.js";
+import type { LoadedStageConfig } from "../types/stage.js";
+import { type NamedSecret, type RedactOptions } from "../logging/redact.js";
+import type { RunStore } from "./port.js";
+export declare const RUN_MANIFEST_VERSION: 1;
+export type ModelAuthoredTier = "stage" | "pipeline" | "global";
+export type RunManifestHost = {
+    stageflow_version: string;
+    build_sha: string;
+    image_digest: string | null;
+    schema_version: number;
+};
+export type RunManifestCaller = {
+    caller_id: string | null;
+    surface: CallerSurface;
+};
+export type RunManifestBinding = {
+    kind: "repository";
+    repository: string;
+    ref?: string;
+    resolved_sha?: string;
+    branch?: string;
+    worktree_path?: string;
+} | {
+    kind: "checkout";
+    resolved_sha?: string;
+    worktree_path?: string;
+} | {
+    kind: "unbound";
+};
+export type RunManifestPipeline = {
+    source: "inline" | "path";
+    path: string | null;
+    bytes_sha256: string;
+    body: unknown;
+};
+export type RunManifestTask = {
+    source: "inline" | "path";
+    path: string | null;
+    bytes_sha256: string;
+    body: string;
+};
+export type RunManifestSkill = {
+    name: string;
+    origin: SkillOrigin;
+    digest: string;
+    files: string[];
+};
+export type RunManifestStageModel = {
+    authored: string;
+    authored_tier: ModelAuthoredTier;
+    resolved?: string;
+    thinking_level?: string;
+};
+export type RunManifestMcpServer = {
+    name: string;
+    command?: string;
+    args?: unknown;
+    env?: Record<string, unknown>;
+    url?: string;
+    origin?: string;
+    [key: string]: unknown;
+};
+export type RunManifestStage = {
+    stage_id: string;
+    model: RunManifestStageModel;
+    mcp_servers: RunManifestMcpServer[];
+};
+export type RunManifestToolchainEntry = {
+    tool: string;
+    required?: string;
+    resolved?: string;
+    path?: string;
+    origin?: ToolchainCheck["origin"];
+    status?: ToolchainCheck["status"];
+};
+export type RunManifestV1 = {
+    manifest_version: typeof RUN_MANIFEST_VERSION;
+    run_id: string;
+    created_at: string;
+    finalised_at?: string;
+    host: RunManifestHost;
+    caller: RunManifestCaller;
+    binding: RunManifestBinding;
+    pipeline: RunManifestPipeline;
+    task: RunManifestTask;
+    skills: RunManifestSkill[];
+    stages: RunManifestStage[];
+    toolchain: RunManifestToolchainEntry[];
+};
+export type RunManifest = RunManifestV1;
+export declare function sha256Hex(bytes: string | Buffer): string;
+export declare function sha256Digest(bytes: string | Buffer): string;
+export declare function digestSkillFiles(files: Record<string, string>): {
+    digest: string;
+    files: string[];
+};
+export declare function skillsFromPayload(payload: SkillsPayload | undefined): RunManifestSkill[];
+export declare function toolchainFromChecks(checks: readonly ToolchainCheck[]): RunManifestToolchainEntry[];
+export declare function bindingFromFields(fields: {
+    repository?: string;
+    ref?: string;
+    resolvedSha?: string;
+    runBranch?: string;
+    checkoutRoot?: string;
+}): RunManifestBinding;
+export declare function stagesFromLoaded(stages: readonly LoadedStageConfig[]): RunManifestStage[];
+export declare function buildHostIdentity(env?: NodeJS.ProcessEnv): RunManifestHost;
+export type BuildInitialRunManifestInput = {
+    runId: string;
+    createdAt: string;
+    callerId: string | null;
+    surface: CallerSurface;
+    binding: RunManifestBinding;
+    pipelineSource: "inline" | "path";
+    pipelinePath?: string;
+    pipelineBody?: string | null;
+    taskYaml: string;
+    taskPath?: string;
+    skills?: SkillsPayload;
+    stages: readonly LoadedStageConfig[];
+    toolchain: readonly ToolchainCheck[];
+    namedSecrets?: readonly NamedSecret[];
+};
+export declare function buildInitialRunManifest(input: BuildInitialRunManifestInput): RunManifestV1;
+export declare function parseRunManifest(value: unknown): RunManifest | null;
+export declare function collectMcpEnvNamedSecrets(servers: ResolvedMcpServers | undefined): NamedSecret[];
+export declare function collectDeclaredSecretValues(names: readonly string[], env?: NodeJS.ProcessEnv): NamedSecret[];
+export declare function redactMcpServers(servers: ResolvedMcpServers, namedSecrets: readonly NamedSecret[], origins?: ReadonlyMap<string, string>): RunManifestMcpServer[];
+export declare function redactRunManifest(manifest: RunManifestV1, options?: RedactOptions): RunManifestV1;
+/** Defense-in-depth redaction for get_run / export views (pipeline body included). */
+export declare function redactRunManifestForRead(value: unknown, options?: RedactOptions): RunManifest | null;
+export declare function withStageResolvedModel(manifest: RunManifestV1, stageId: string, resolved: {
+    model: string;
+    thinkingLevel?: string;
+}): RunManifestV1;
+export declare function withStageMcpServers(manifest: RunManifestV1, stageId: string, mcpServers: RunManifestMcpServer[]): RunManifestV1;
+export declare function withSkillEntry(manifest: RunManifestV1, skill: RunManifestSkill): RunManifestV1;
+export declare function finaliseRunManifest(manifest: RunManifestV1, finalisedAt?: string): RunManifestV1;
+export declare function readParsedRunManifest(store: Pick<RunStore, "readRunMeta">, runId: string): Promise<RunManifest | null>;
+export declare function patchRunManifest(store: Pick<RunStore, "readRunMeta" | "updateRunManifest">, runId: string, mutate: (current: RunManifestV1) => RunManifestV1, namedSecrets?: readonly NamedSecret[]): Promise<RunManifestV1 | null>;
+export declare function finaliseStoredRunManifest(store: Pick<RunStore, "readRunMeta" | "updateRunManifest">, runId: string, finalisedAt?: string): Promise<void>;