stageflow 0.25.0 → 0.30.0

package/dist/runstore/port.d.ts

@@ -1,4 +1,5 @@
 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";
@@ -6,14 +7,15 @@ import type { FeedbackLoopConfig, InlinePipelineDefinition, ResolvedPipelineDag
 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"];
@@ -52,12 +54,25 @@ 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;
     /**
-     * The raw pipeline body for a run started from an inline pipeline
-     * (no pipeline_path). Lets a fresh stage-worker process — which has no
-     * memory of the original in-process call — reconstruct the pipeline
-     * without needing a catalog file, mirroring how task_yaml already lets
-     * task reconstruction work without a task_path.
+     * Parsed inline pipeline body for stage-worker reload when there is no
+     * pipeline_path. Derived from stored pipeline_body.
      */
     inline_pipeline?: InlinePipelineDefinition;
 };
@@ -73,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[];
@@ -94,6 +109,7 @@ export type StageExecution = {
     envelope: StageEnvelope | null;
     cost_usd?: number;
     usage?: StageUsage;
+    auto_resume_count: number;
 };
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
@@ -103,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";
@@ -231,6 +248,22 @@ export type CreateForkGenerationInput = Omit<ForkGenerationRecord, "run_id" | "s
     status?: ForkGenerationStatus;
 };
 export type ForkGenerationPatch = Partial<Pick<ForkGenerationRecord, "status">>;
+/** Durable registration of a catalog-owned `*.trigger.yaml` definition. */
+export type TriggerRecord = {
+    id: string;
+    definition_ref: string;
+    enabled: boolean;
+    last_fired_at?: string;
+    last_run_id?: string;
+    next_run_at?: string;
+    created_at: string;
+    updated_at: string;
+};
+export type UpsertTriggerInput = {
+    id: string;
+    definitionRef: string;
+    enabled: boolean;
+};
 export type CompactStage = {
     id: string;
     status: StageSnapshot["status"];
@@ -238,6 +271,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;
@@ -245,9 +288,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;
@@ -265,13 +310,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;
@@ -285,6 +339,7 @@ export type FeedbackLoopHistory = {
 };
 export type CreateRunInput = {
     submission?: RunSubmission;
+    runId?: string;
     pipelineId: string;
     taskYaml: string;
     taskId?: string;
@@ -296,8 +351,24 @@ export type CreateRunInput = {
     pipelinePath?: string;
     taskPath?: string;
     projectRoot?: string;
-    /** Raw inline pipeline body, persisted only when pipelinePath is absent. */
+    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;
@@ -305,6 +376,7 @@ export type ListRunsFilter = {
     since?: string;
     /** Match pipeline_id or pipeline_path */
     pipeline?: string;
+    caller_id?: string;
 };
 /**
  * Persistence port for pipeline run state.
@@ -313,11 +385,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>;
@@ -327,6 +437,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?: {
@@ -346,8 +458,22 @@ 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[]>;
+    /** Idempotent create-or-update of a trigger's catalog registration. */
+    upsertTrigger(input: UpsertTriggerInput): Promise<TriggerRecord>;
+    getTrigger(id: string): Promise<TriggerRecord | null>;
+    listTriggers(): Promise<TriggerRecord[]>;
+    /** Record a fire: stamps last_fired_at/last_run_id. Throws if the trigger is missing. */
+    recordTriggerFired(id: string, runId: string): Promise<void>;
+    /** Persist the next computed fire time for a schedule-kind trigger. Throws if the trigger is missing. */
+    setTriggerNextRun(id: string, nextRunAt: string): Promise<void>;
+    /** Read a single adapter-owned state value for a trigger, or null if unset. */
+    getTriggerAdapterState(triggerId: string, key: string): Promise<string | null>;
+    /** Upsert a single adapter-owned state value for a trigger. */
+    setTriggerAdapterState(triggerId: string, key: string, value: string): Promise<void>;
     readRun(runId: string): Promise<RunDetail>;
     updatePipelineDag(runId: string, dag: RunPipelineDagSnapshot): Promise<void>;
     createFeedbackLoop(runId: string, input: CreateFeedbackLoopInput): Promise<FeedbackLoopRecord>;
@@ -377,4 +503,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;

package/dist/runstore/port.js

@@ -6,6 +6,8 @@ export function stageStatusFromEvents(events) {
             status = "running";
         if (ev.event === "waiting_for_input")
             status = "waiting_for_input";
+        if (ev.event === "interrupted")
+            status = "interrupted";
         if (ev.event === "succeeded")
             status = "succeeded";
         if (ev.event === "failed")
@@ -54,7 +56,11 @@ function stageResolvedForSuccess(stage, dag, byId) {
     }
     return false;
 }
-export function deriveStatusFromStages(stages, dag) {
+const OPERATOR_TERMINAL_STATUSES = new Set(["cancelled", "queued"]);
+export function deriveStatusFromStages(stages, dag, currentStatus) {
+    if (currentStatus !== undefined && OPERATOR_TERMINAL_STATUSES.has(currentStatus)) {
+        return currentStatus;
+    }
     if (stages.length === 0)
         return "created";
     if (findUnhandledFailedStage(stages, dag))
@@ -65,6 +71,7 @@ export function deriveStatusFromStages(stages, dag) {
     }
     if (stages.some((s) => s.status === "running" ||
         s.status === "waiting_for_input" ||
+        s.status === "interrupted" ||
         s.status === "succeeded")) {
         return "running";
     }

package/dist/runstore/restore.d.ts

@@ -0,0 +1,81 @@
+import { type ServiceProbeResult } from "../server/ensureGlobalService.js";
+export type RestoreErrorCode = "restore_host_live" | "restore_store_busy" | "restore_verify_failed" | "restore_schema_too_new" | "restore_version_mismatch" | "restore_unsafe_member" | "restore_failed" | "restore_not_found";
+export declare class RestoreError extends Error {
+    readonly code: RestoreErrorCode;
+    readonly detail?: Record<string, unknown>;
+    constructor(message: string, code: RestoreErrorCode, detail?: Record<string, unknown>);
+}
+export type RestoreManifest = {
+    created_at?: string;
+    stageflow_version?: string;
+    schema_version?: number;
+    contents?: string[];
+    credentials_included?: boolean;
+    a2a_artifacts_included?: boolean;
+    fingerprint_skew?: boolean;
+};
+export type VerifiedRestoreArchive = {
+    stagingDir: string;
+    dbPath: string;
+    manifest: RestoreManifest | null;
+    schemaVersion: number;
+    missingA2aArtifactRows: number;
+};
+export declare function restorePendingDir(homeDir?: string): string;
+export declare function restoreMarkerPath(homeDir?: string): string;
+export declare function restoreAppliedPath(homeDir?: string): string;
+export declare function restoreFailedPath(homeDir?: string): string;
+export type RestoreMarker = {
+    archive: string;
+    attempts: number;
+    staged_at: string;
+    drain_deadline?: string;
+};
+export declare function extractVerifiedArchive(archivePath: string): Promise<VerifiedRestoreArchive>;
+export declare function assertHostDownForRestore(options?: {
+    probe?: () => Promise<ServiceProbeResult>;
+}): Promise<void>;
+/**
+ * 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 declare function withExclusiveStoreLock<T>(homeDir: string, fn: () => T): T;
+export type ApplyRestoreResult = {
+    schema_version: number;
+    missing_a2a_artifact_rows: number;
+    pre_restore_stamp: string;
+};
+export declare function applyRestoreArchive(options: {
+    archivePath: string;
+    homeDir?: string;
+    force?: boolean;
+    restoreCredentials?: boolean;
+    probe?: () => Promise<ServiceProbeResult>;
+}): Promise<ApplyRestoreResult>;
+export declare function stageRestoreForBoot(options: {
+    archivePath: string;
+    homeDir?: string;
+    graceMs?: number;
+}): Promise<{
+    marker: RestoreMarker;
+    stagedPath: string;
+}>;
+export declare function resolveBackupNameForRestore(name: string, homeDir?: string): Promise<string>;
+export type BootRestoreOutcome = {
+    status: "none";
+} | {
+    status: "applied";
+    result: ApplyRestoreResult;
+} | {
+    status: "failed";
+    reason: string;
+    attempts: number;
+} | {
+    status: "blocked";
+    reason: string;
+};
+/**
+ * Apply a staged restore marker before opening the store for serving.
+ * Never re-applies restore.applied. Two failures → restore.failed (hard non-serve).
+ */
+export declare function applyPendingRestoreAtBoot(homeDir?: string): Promise<BootRestoreOutcome>;