stageflow 0.42.0 → 0.46.0

package/dist/runstore/retention.js

@@ -1,3 +1,4 @@
+import { isRunClockTerminal, } from "./runStatusClock.js";
 export const DAY_MS = 24 * 60 * 60 * 1000;
 /** Defaults: succeeded 3d/30d; failed and cancelled 30d/90d (R30 / AE6). */
 export const DEFAULT_RETENTION_WINDOWS = {
@@ -7,11 +8,6 @@ export const DEFAULT_RETENTION_WINDOWS = {
 };
 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;
@@ -52,7 +48,7 @@ export function slimArtifactMaxBytesFromEnv(env = process.env) {
  */
 export function retentionDecision(row, now, windows = DEFAULT_RETENTION_WINDOWS) {
     const status = row.status;
-    if (status === undefined || !TERMINAL.has(status))
+    if (!isRunClockTerminal(status))
         return "none";
     if (row.finished_at === undefined || row.finished_at === "")
         return "none";
@@ -70,5 +66,5 @@ export function retentionDecision(row, now, windows = DEFAULT_RETENTION_WINDOWS)
     return "none";
 }
 export function isTerminalRunStatus(status) {
-    return status !== undefined && TERMINAL.has(status);
+    return isRunClockTerminal(status);
 }

package/dist/runstore/runStatusClock.d.ts

@@ -0,0 +1,17 @@
+export declare const RUN_CLOCK_TERMINAL_STATUSES: readonly ["succeeded", "failed", "cancelled"];
+export type RunClockTerminalStatus = (typeof RUN_CLOCK_TERMINAL_STATUSES)[number];
+export type RunClockStatus = "created" | "queued" | "running" | RunClockTerminalStatus;
+export declare function isRunClockTerminal(status: string | undefined): status is RunClockTerminalStatus;
+export type FinishedAtDecision = {
+    action: "stamp";
+    finishedAt: string;
+} | {
+    action: "keep";
+} | {
+    action: "clear";
+};
+export declare function nextFinishedAt(input: {
+    nextStatus: RunClockStatus;
+    currentFinishedAt: string | null | undefined;
+    now: string;
+}): FinishedAtDecision;

package/dist/runstore/runStatusClock.js

@@ -0,0 +1,19 @@
+export const RUN_CLOCK_TERMINAL_STATUSES = [
+    "succeeded",
+    "failed",
+    "cancelled",
+];
+const TERMINAL = new Set(RUN_CLOCK_TERMINAL_STATUSES);
+export function isRunClockTerminal(status) {
+    return status !== undefined && TERMINAL.has(status);
+}
+export function nextFinishedAt(input) {
+    if (isRunClockTerminal(input.nextStatus)) {
+        if (input.currentFinishedAt != null &&
+            input.currentFinishedAt !== "") {
+            return { action: "keep" };
+        }
+        return { action: "stamp", finishedAt: input.now };
+    }
+    return { action: "clear" };
+}

package/dist/runstore/sqlite/SqliteRunStore.d.ts

@@ -1,5 +1,5 @@
 import Database from "better-sqlite3";
-import type { CreateEvalRunInput, EvalCaseInput, EvalCaseRow, EvalGraderVersionInput, EvalResultInput, EvalResultWithGrades, EvalReviewPatch, EvalReviewRow, EvalRunPage, EvalRunProgress, EvalRunRow, FinishEvalRunInput, ListEvalRunsQuery } from "../../evals/storeTypes.js";
+import type { CreateEvalRunInput, EvalCaseInput, EvalCaseRow, EvalGraderVersionInput, EvalResultInput, EvalResultWithGrades, EvalReviewPatch, EvalCalibrationInput, EvalCalibrationRow, EvalGraderLabelPatch, EvalGraderLabelRow, EvalReviewRow, EvalRunPage, EvalRunProgress, EvalRunRow, FinishEvalRunInput, ListEvalRunsQuery } from "../../evals/storeTypes.js";
 import type { EvalTargetKind } from "../../evals/constants.js";
 import type { StageEnvelope } from "../../types/envelope.js";
 import type { StageLogLine } from "../../agent/activity.js";
@@ -32,6 +32,7 @@ export declare class SqliteRunStore implements RunStore {
     findRunByDispatchKey(dispatchKey: string): Promise<CreatedRun | undefined>;
     private readSubmission;
     getRunBySubmission(key: string): Promise<RunSubmissionRecord | null>;
+    private applyRunStatusUpdate;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;
     tryUpdateRunStatus(runId: string, status: RunStatus, expectedStatus: RunStatus): Promise<boolean>;
     patchRunWorkspaceBinding(runId: string, patch: {
@@ -95,6 +96,15 @@ export declare class SqliteRunStore implements RunStore {
     getEvalCases(evalRunId: string): Promise<EvalCaseRow[]>;
     putEvalReview(evalRunId: string, caseId: string, repeatIndex: number, patch: EvalReviewPatch): Promise<EvalReviewRow>;
     getEvalReviews(evalRunId: string): Promise<EvalReviewRow[]>;
+    putEvalGraderLabel(evalRunId: string, caseId: string, repeatIndex: number, graderId: string, patch: EvalGraderLabelPatch): Promise<EvalGraderLabelRow | null>;
+    listGradedResultKeys(evalRunId: string, graderId: string): Promise<Array<{
+        caseId: string;
+        repeatIndex: number;
+    }>>;
+    listEvalGraderLabels(evalRunId: string): Promise<EvalGraderLabelRow[]>;
+    listEvalGraderLabelsForEval(projectRoot: string, evalId: string, graderId: string): Promise<EvalGraderLabelRow[]>;
+    insertEvalCalibration(input: EvalCalibrationInput): Promise<EvalCalibrationRow>;
+    listEvalCalibrations(projectRoot: string, evalId: string, graderId?: string, includeCandidates?: boolean, limit?: number): Promise<EvalCalibrationRow[]>;
     listFailureTypes(projectRoot: string, evalId: string): Promise<string[]>;
     recordGraderVersions(projectRoot: string, evalId: string, graders: EvalGraderVersionInput[]): Promise<Record<string, number>>;
     listEvalSubjectRefs(evalRunId: string, targetKind: EvalTargetKind): Promise<string[]>;

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -10,11 +10,13 @@ import { newRunId, runWorkspaceDir } from "../paths.js";
 import { attemptAgentDir, attemptArtifactsDir, stageDir, } from "../workspaceLayout.js";
 import { importDiskRunsIfEmpty } from "./migrateFromDisk.js";
 import * as evalStore from "./evalStore.js";
+import * as calibrationStore from "./calibrationStore.js";
 import * as suggestionStore from "./suggestionStore.js";
 import { applyPendingMigrations, assertSchemaVersion, } from "./migrations/index.js";
 import { StoreSchemaError } from "./storeSchemaError.js";
 import { applyStorePragmas } from "./applyStorePragmas.js";
 import { RunSubmissionExistsError } from "../submission.js";
+import { nextFinishedAt } from "../runStatusClock.js";
 const EXECUTION_SELECT_COLS = `run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json, auto_resume_count`;
 const ensuredStageDirs = new Set();
 function executionFromRow(row) {
@@ -289,58 +291,57 @@ export class SqliteRunStore {
         await this.ready();
         return this.readSubmission(key);
     }
+    applyRunStatusUpdate(runId, status, expectedStatus) {
+        const now = new Date().toISOString();
+        const current = this.db
+            .prepare(`SELECT finished_at FROM runs WHERE run_id = ?`)
+            .get(runId);
+        if (current === undefined) {
+            throw new Error(`Run not found: ${runId}`);
+        }
+        const decision = nextFinishedAt({
+            nextStatus: status,
+            currentFinishedAt: current.finished_at,
+            now,
+        });
+        const params = {
+            run_id: runId,
+            status,
+            updated_at: now,
+        };
+        let finishedSql;
+        if (decision.action === "stamp") {
+            finishedSql = "finished_at = @finished_at";
+            params.finished_at = decision.finishedAt;
+        }
+        else if (decision.action === "clear") {
+            finishedSql = "finished_at = NULL";
+        }
+        else {
+            finishedSql = "finished_at = finished_at";
+        }
+        const expectedClause = expectedStatus !== undefined
+            ? " AND status = @expected_status"
+            : "";
+        if (expectedStatus !== undefined) {
+            params.expected_status = expectedStatus;
+        }
+        const result = this.db
+            .prepare(`UPDATE runs SET status = @status, updated_at = @updated_at, ${finishedSql}
+         WHERE run_id = @run_id${expectedClause}`)
+            .run(params);
+        return result.changes;
+    }
     async updateRunStatus(runId, status) {
         await this.ready();
-        const now = new Date().toISOString();
-        const isTerminal = status === "succeeded" || status === "failed" || status === "cancelled";
-        const result = isTerminal
-            ? this.db
-                .prepare(`UPDATE runs SET status = @status, updated_at = @updated_at,
-              finished_at = COALESCE(finished_at, @finished_at)
-             WHERE run_id = @run_id`)
-                .run({
-                run_id: runId,
-                status,
-                updated_at: now,
-                finished_at: now,
-            })
-            : this.db
-                .prepare(`UPDATE runs SET status = @status, updated_at = @updated_at WHERE run_id = @run_id`)
-                .run({
-                run_id: runId,
-                status,
-                updated_at: now,
-            });
-        if (result.changes === 0) {
+        if (this.applyRunStatusUpdate(runId, status, undefined) === 0) {
             throw new Error(`Run not found: ${runId}`);
         }
     }
     async tryUpdateRunStatus(runId, status, expectedStatus) {
         await this.ready();
-        const now = new Date().toISOString();
-        const isTerminal = status === "succeeded" || status === "failed" || status === "cancelled";
-        const result = isTerminal
-            ? this.db
-                .prepare(`UPDATE runs SET status = @status, updated_at = @updated_at,
-              finished_at = COALESCE(finished_at, @finished_at)
-             WHERE run_id = @run_id AND status = @expected_status`)
-                .run({
-                run_id: runId,
-                status,
-                expected_status: expectedStatus,
-                updated_at: now,
-                finished_at: now,
-            })
-            : this.db
-                .prepare(`UPDATE runs SET status = @status, updated_at = @updated_at
-             WHERE run_id = @run_id AND status = @expected_status`)
-                .run({
-                run_id: runId,
-                status,
-                expected_status: expectedStatus,
-                updated_at: now,
-            });
-        if (result.changes > 0)
+        const changes = this.applyRunStatusUpdate(runId, status, expectedStatus);
+        if (changes > 0)
             return true;
         const exists = this.db
             .prepare(`SELECT 1 AS ok FROM runs WHERE run_id = ?`)
@@ -949,6 +950,30 @@ export class SqliteRunStore {
         await this.ready();
         return evalStore.getEvalReviews(this.db, evalRunId);
     }
+    async putEvalGraderLabel(evalRunId, caseId, repeatIndex, graderId, patch) {
+        await this.ready();
+        return calibrationStore.putEvalGraderLabel(this.db, evalRunId, caseId, repeatIndex, graderId, patch);
+    }
+    async listGradedResultKeys(evalRunId, graderId) {
+        await this.ready();
+        return evalStore.listGradedResultKeys(this.db, evalRunId, graderId);
+    }
+    async listEvalGraderLabels(evalRunId) {
+        await this.ready();
+        return calibrationStore.listEvalGraderLabels(this.db, evalRunId);
+    }
+    async listEvalGraderLabelsForEval(projectRoot, evalId, graderId) {
+        await this.ready();
+        return calibrationStore.listEvalGraderLabelsForEval(this.db, projectRoot, evalId, graderId);
+    }
+    async insertEvalCalibration(input) {
+        await this.ready();
+        return calibrationStore.insertEvalCalibration(this.db, input);
+    }
+    async listEvalCalibrations(projectRoot, evalId, graderId, includeCandidates, limit) {
+        await this.ready();
+        return calibrationStore.listEvalCalibrations(this.db, projectRoot, evalId, graderId, includeCandidates, limit);
+    }
     async listFailureTypes(projectRoot, evalId) {
         await this.ready();
         return evalStore.listFailureTypes(this.db, projectRoot, evalId);

package/dist/runstore/sqlite/calibrationStore.d.ts

@@ -0,0 +1,10 @@
+import type Database from "better-sqlite3";
+import type { EvalCalibrationInput, EvalCalibrationRow, EvalGraderLabelPatch, EvalGraderLabelRow } from "../../evals/storeTypes.js";
+/** Sets, changes or (label null) clears one grader label on a stored result. */
+export declare function putEvalGraderLabel(db: Database.Database, evalRunId: string, caseId: string, repeatIndex: number, graderId: string, patch: EvalGraderLabelPatch): EvalGraderLabelRow | null;
+export declare function listEvalGraderLabels(db: Database.Database, evalRunId: string): EvalGraderLabelRow[];
+/** Labels across every run of one eval, newest label first. */
+export declare function listEvalGraderLabelsForEval(db: Database.Database, projectRoot: string, evalId: string, graderId: string): EvalGraderLabelRow[];
+export declare function insertEvalCalibration(db: Database.Database, input: EvalCalibrationInput): EvalCalibrationRow;
+/** Newest first. Candidate (unsaved-rubric) calibrations are included only on request. */
+export declare function listEvalCalibrations(db: Database.Database, projectRoot: string, evalId: string, graderId?: string, includeCandidates?: boolean, limit?: number): EvalCalibrationRow[];

package/dist/runstore/sqlite/calibrationStore.js

@@ -0,0 +1,106 @@
+import { randomBytes } from "node:crypto";
+import { EVAL_LIMITS } from "../../evals/constants.js";
+import { EvalStoreError } from "../../evals/storeError.js";
+const now = () => new Date().toISOString();
+const labelFromDb = (r) => ({
+    evalRunId: r.eval_run_id,
+    caseId: r.case_id,
+    repeatIndex: r.repeat_index,
+    graderId: r.grader_id,
+    label: r.label,
+    note: r.note,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+});
+/** Sets, changes or (label null) clears one grader label on a stored result. */
+export function putEvalGraderLabel(db, evalRunId, caseId, repeatIndex, graderId, patch) {
+    if (typeof patch.note === "string" && patch.note.length > EVAL_LIMITS.reviewNoteMaxChars) {
+        throw new Error(`Label note must be at most ${EVAL_LIMITS.reviewNoteMaxChars} characters`);
+    }
+    const exists = db
+        .prepare(`SELECT 1 AS ok FROM eval_results WHERE eval_run_id = ? AND case_id = ? AND repeat_index = ?`)
+        .get(evalRunId, caseId, repeatIndex);
+    if (!exists)
+        throw new EvalStoreError("EVAL_RUN_NOT_FOUND", `No result for ${caseId}#${repeatIndex} in ${evalRunId}`);
+    if (patch.label === null) {
+        db.prepare(`DELETE FROM eval_grader_labels WHERE eval_run_id = ? AND case_id = ? AND repeat_index = ? AND grader_id = ?`).run(evalRunId, caseId, repeatIndex, graderId);
+        return null;
+    }
+    const at = now();
+    db.prepare(`INSERT INTO eval_grader_labels (eval_run_id, case_id, repeat_index, grader_id, label, note, created_at, updated_at)
+     VALUES (@run, @case, @repeat, @grader, @label, @note, @at, @at)
+     ON CONFLICT (eval_run_id, case_id, repeat_index, grader_id) DO UPDATE SET
+       label = excluded.label,
+       note = ${patch.note === undefined ? "eval_grader_labels.note" : "excluded.note"},
+       updated_at = excluded.updated_at`).run({
+        run: evalRunId,
+        case: caseId,
+        repeat: repeatIndex,
+        grader: graderId,
+        label: patch.label,
+        note: patch.note ?? null,
+        at,
+    });
+    return labelFromDb(db
+        .prepare(`SELECT * FROM eval_grader_labels WHERE eval_run_id = ? AND case_id = ? AND repeat_index = ? AND grader_id = ?`)
+        .get(evalRunId, caseId, repeatIndex, graderId));
+}
+export function listEvalGraderLabels(db, evalRunId) {
+    return db
+        .prepare(`SELECT * FROM eval_grader_labels WHERE eval_run_id = ? ORDER BY case_id, repeat_index, grader_id`)
+        .all(evalRunId).map(labelFromDb);
+}
+/** Labels across every run of one eval, newest label first. */
+export function listEvalGraderLabelsForEval(db, projectRoot, evalId, graderId) {
+    return db
+        .prepare(`SELECT l.* FROM eval_grader_labels l
+           JOIN eval_runs r ON r.eval_run_id = l.eval_run_id
+          WHERE r.project_root = ? AND r.eval_id = ? AND l.grader_id = ?
+          ORDER BY l.updated_at DESC, l.eval_run_id, l.case_id, l.repeat_index`)
+        .all(projectRoot, evalId, graderId).map(labelFromDb);
+}
+const calibrationFromDb = (r) => ({
+    id: r.id,
+    projectRoot: r.project_root,
+    evalId: r.eval_id,
+    graderId: r.grader_id,
+    graderHash: r.grader_hash,
+    judge: r.judge,
+    promptVersion: r.prompt_version,
+    split: r.split,
+    candidate: r.candidate === 1,
+    stats: JSON.parse(r.stats_json),
+    disagreements: JSON.parse(r.disagreements_json),
+    costUsd: r.cost_usd,
+    createdAt: r.created_at,
+});
+export function insertEvalCalibration(db, input) {
+    const id = `cal_${randomBytes(6).toString("hex")}`;
+    const createdAt = now();
+    db.prepare(`INSERT INTO eval_calibrations
+       (id, project_root, eval_id, grader_id, grader_hash, judge, prompt_version, split, candidate, stats_json, disagreements_json, cost_usd, created_at)
+     VALUES (@id, @project_root, @eval_id, @grader_id, @grader_hash, @judge, @prompt_version, @split, @candidate, @stats_json, @disagreements_json, @cost_usd, @created_at)`).run({
+        id,
+        project_root: input.projectRoot,
+        eval_id: input.evalId,
+        grader_id: input.graderId,
+        grader_hash: input.graderHash,
+        judge: input.judge,
+        prompt_version: input.promptVersion,
+        split: input.split,
+        candidate: input.candidate ? 1 : 0,
+        stats_json: JSON.stringify(input.stats),
+        disagreements_json: JSON.stringify(input.disagreements),
+        cost_usd: input.costUsd,
+        created_at: createdAt,
+    });
+    return { ...input, id, createdAt };
+}
+/** Newest first. Candidate (unsaved-rubric) calibrations are included only on request. */
+export function listEvalCalibrations(db, projectRoot, evalId, graderId, includeCandidates = false, limit = 20) {
+    return db
+        .prepare(`SELECT * FROM eval_calibrations
+          WHERE project_root = ? AND eval_id = ? AND (? IS NULL OR grader_id = ?) AND (candidate = 0 OR ?)
+          ORDER BY created_at DESC LIMIT ?`)
+        .all(projectRoot, evalId, graderId ?? null, graderId ?? null, includeCandidates ? 1 : 0, limit).map(calibrationFromDb);
+}

package/dist/runstore/sqlite/evalStore.d.ts

@@ -10,6 +10,11 @@ export declare function getEvalRun(db: Database.Database, evalRunId: string): Ev
 export declare function getEvalRunByNumber(db: Database.Database, projectRoot: string, evalId: string, runNumber: number): EvalRunRow | null;
 export declare function listEvalRuns(db: Database.Database, query: ListEvalRunsQuery): EvalRunPage;
 export declare function listEvalResults(db: Database.Database, evalRunId: string): EvalResultWithGrades[];
+/** Keys of the results one grader graded in a run, without their outputs. */
+export declare function listGradedResultKeys(db: Database.Database, evalRunId: string, graderId: string): Array<{
+    caseId: string;
+    repeatIndex: number;
+}>;
 export declare function getEvalResultsForCase(db: Database.Database, evalRunId: string, caseId: string): EvalResultWithGrades[];
 export declare function getEvalCases(db: Database.Database, evalRunId: string): EvalCaseRow[];
 export declare function putEvalReview(db: Database.Database, evalRunId: string, caseId: string, repeatIndex: number, patch: EvalReviewPatch): EvalReviewRow;

package/dist/runstore/sqlite/evalStore.js

@@ -335,6 +335,13 @@ export function listEvalResults(db, evalRunId) {
         .all(evalRunId);
     return attachGrades(db, rows.map(resultFromDb), evalRunId);
 }
+/** Keys of the results one grader graded in a run, without their outputs. */
+export function listGradedResultKeys(db, evalRunId, graderId) {
+    return db
+        .prepare(`SELECT DISTINCT case_id, repeat_index FROM eval_grades
+          WHERE eval_run_id = ? AND grader_id = ? AND status = 'graded' ORDER BY case_id, repeat_index`)
+        .all(evalRunId, graderId).map((r) => ({ caseId: r.case_id, repeatIndex: r.repeat_index }));
+}
 export function getEvalResultsForCase(db, evalRunId, caseId) {
     const rows = db
         .prepare(`SELECT * FROM eval_results WHERE eval_run_id = ? AND case_id = ? ORDER BY repeat_index`)

package/dist/runstore/sqlite/migrations/018-eval-grader-labels.d.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+/**
+ * Human verdicts per judged grader on one result, and stored judge calibrations.
+ * Labels cascade with their result; calibrations belong to the eval, not a run. Additive.
+ */
+export declare const MIGRATION_018: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/018-eval-grader-labels.js

@@ -0,0 +1,43 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Human verdicts per judged grader on one result, and stored judge calibrations.
+ * Labels cascade with their result; calibrations belong to the eval, not a run. Additive.
+ */
+export const MIGRATION_018 = {
+    version: 18,
+    name: "018_eval_grader_labels",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+CREATE TABLE eval_grader_labels (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  grader_id TEXT NOT NULL,
+  label TEXT NOT NULL CHECK (label IN ('pass','fail')),
+  note TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index, grader_id),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+
+CREATE TABLE eval_calibrations (
+  id TEXT PRIMARY KEY,
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  grader_id TEXT NOT NULL,
+  grader_hash TEXT NOT NULL,
+  judge TEXT NOT NULL,
+  prompt_version INTEGER NOT NULL,
+  split TEXT NOT NULL CHECK (split IN ('all','dev','held_out')),
+  candidate INTEGER NOT NULL DEFAULT 0,
+  stats_json TEXT NOT NULL,
+  disagreements_json TEXT NOT NULL,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX eval_calibrations_grader ON eval_calibrations (project_root, eval_id, grader_id, created_at);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/index.js

@@ -16,6 +16,7 @@ import { MIGRATION_014 } from "./014-agent-deliveries.js";
 import { MIGRATION_015 } from "./015-evals.js";
 import { MIGRATION_016 } from "./016-eval-subject-ref.js";
 import { MIGRATION_017 } from "./017-eval-result-suggestions.js";
+import { MIGRATION_018 } from "./018-eval-grader-labels.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -34,6 +35,7 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_015,
     MIGRATION_016,
     MIGRATION_017,
+    MIGRATION_018,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runstore/workspaceLayout.js

@@ -1,6 +1,7 @@
 import { access, lstat, mkdir, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { globalCredentialRoot } from "../project/globalHome.js";
+import { buildArtifactListedPath } from "../runtime/artifactPath.js";
 import { STAGEFLOW_AGENT_AUTH_PATH_ENV } from "../runtime/credentialBinding.js";
 import { SF_STAGE_WORKER } from "../runtime/stageWorkerProtocol.js";
 export { stageDir } from "./paths.js";
@@ -186,7 +187,11 @@ export function resolveArtifactTarget(runWorkspaceDir, stageId, attempt, relativ
         path.isAbsolute(relativeToArtifacts)) {
         throw new Error("path escapes the stage artifacts directory");
     }
-    const runRelativePath = path.posix.join("stages", stageId, "attempts", String(attempt), "artifacts", ...relativeToArtifacts.split(path.sep));
+    const runRelativePath = buildArtifactListedPath({
+        stageId,
+        attempt,
+        relative: relativeToArtifacts.split(path.sep).join("/"),
+    });
     return {
         absolutePath: resolved,
         runRelativePath,

package/dist/runtime/artifactDiskInspect.d.ts

@@ -0,0 +1,14 @@
+export type ArtifactDiskFileType = "file" | "directory" | "symlink" | "other" | "missing";
+export type ArtifactDiskPresence = {
+    file_type: ArtifactDiskFileType;
+    /** Lexical absolute path under root when the walk reached a leaf. */
+    absolutePath?: string;
+    /** From lstat when `file_type` is `file`. */
+    size_bytes?: number;
+};
+/**
+ * Closed-posture walk of `relativePath` under `rootDir`: lstat every segment,
+ * classify symlink / missing / file / directory / other. Does not follow
+ * symlinks. Escape attempts are `missing`. Non-ENOENT errors propagate.
+ */
+export declare function inspectArtifactUnderRoot(rootDir: string, relativePath: string): Promise<ArtifactDiskPresence>;

package/dist/runtime/artifactDiskInspect.js

@@ -0,0 +1,52 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Closed-posture walk of `relativePath` under `rootDir`: lstat every segment,
+ * classify symlink / missing / file / directory / other. Does not follow
+ * symlinks. Escape attempts are `missing`. Non-ENOENT errors propagate.
+ */
+export async function inspectArtifactUnderRoot(rootDir, relativePath) {
+    const target = path.resolve(rootDir, relativePath);
+    const relative = path.relative(rootDir, target);
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { file_type: "missing" };
+    }
+    try {
+        const segments = relative.split(path.sep).filter((segment) => segment !== "");
+        let current = rootDir;
+        let stats;
+        for (const segment of segments) {
+            current = path.join(current, segment);
+            stats = await lstat(current);
+            if (stats.isSymbolicLink()) {
+                return { file_type: "symlink", absolutePath: current };
+            }
+            if (current !== target && !stats.isDirectory()) {
+                return { file_type: "other", absolutePath: current };
+            }
+        }
+        if (stats === undefined) {
+            return { file_type: "missing" };
+        }
+        if (stats.isDirectory()) {
+            return { file_type: "directory", absolutePath: current };
+        }
+        if (!stats.isFile()) {
+            return { file_type: "other", absolutePath: current };
+        }
+        return {
+            file_type: "file",
+            absolutePath: current,
+            size_bytes: stats.size,
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { file_type: "missing" };
+        }
+        throw error;
+    }
+}

package/dist/runtime/artifactPath.d.ts

@@ -0,0 +1,24 @@
+/** Parts of a run-relative artifact path under `stages/.../artifacts/`. */
+export type ArtifactPathParts = {
+    stageId: string;
+    attempt: number;
+    relative: string;
+};
+export type ArtifactPathMode = {
+    kind: "grantable";
+} | {
+    kind: "current_attempt";
+    stageId: string;
+    attempt: number;
+};
+export declare function attemptArtifactsPrefix(stageId: string, attempt: number): string;
+export declare function buildArtifactListedPath(parts: ArtifactPathParts): string;
+/**
+ * Accept a listed artifact path under a mode.
+ * - `grantable`: full run-relative path to a prior stage/attempt artifact file.
+ * - `current_attempt`: that attempt's run-relative prefix, or a bare path under
+ *   its artifacts dir; foreign `stages/...` paths are rejected.
+ */
+export declare function acceptArtifactListedPath(listedPath: string, mode: ArtifactPathMode): ArtifactPathParts | undefined;
+export declare function parseArtifactListedPath(listedPath: string): ArtifactPathParts | undefined;
+export declare function isGrantableArtifactPath(listedPath: string): boolean;