stageflow 0.40.0 → 0.44.0

package/dist/operatorAgent/profiles/workshopAuthorTools.js

@@ -1,8 +1,10 @@
 import path from "node:path";
+import { Type } from "typebox";
 import { peekDefaultModel } from "../../models/catalog.js";
 import { parse as parseYaml } from "yaml";
 import { CatalogPathError, resolveDefaultWriteRoot, } from "../../config/catalogRelativePath.js";
 import { defaultWorkshopPackageDirectory } from "../../config/ensureCatalogScanRoot.js";
+import { canonicalizeNeedTerminalState } from "../../config/pipelineNeeds.js";
 import { publishDraftPackage } from "../../config/publishDraftPackage.js";
 import { globalStageflowHome } from "../../project/globalHome.js";
 import { emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDraft, } from "../draftContext.js";
@@ -34,6 +36,9 @@ export const WORKSHOP_AUTHOR_TOOL_NAMES = [
     "retrieve_docs",
 ];
 export const WORKSHOP_FORBIDDEN_AGENT_TOOLS = ["bash", "write", "edit"];
+const closed = { additionalProperties: false };
+const jsonObject = Type.Record(Type.String(), Type.Unknown());
+const emptyParams = Type.Object({}, closed);
 const REQUIRED_IO = {
     io: {
         input: { schema: { type: "object" } },
@@ -82,6 +87,9 @@ function stringArg(args, key) {
     const value = args[key];
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function isStringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
 function applyMutation(ctx, summary, nextDraft) {
     const current = readDraftFromContext(ctx.getContext());
     const proposal = {
@@ -174,6 +182,52 @@ async function resolveSaveWriteTarget(ctx, options) {
         await store.close();
     }
 }
+function normalizeRouteOnField(on) {
+    if (Array.isArray(on)) {
+        return on.map((item) => canonicalizeNeedTerminalState(item) ?? item);
+    }
+    const one = canonicalizeNeedTerminalState(on);
+    return one ?? on;
+}
+function normalizeRouteEntries(route) {
+    if (!Array.isArray(route))
+        return route;
+    return route.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return entry;
+        const rec = entry;
+        if (rec.on === undefined)
+            return entry;
+        return { ...rec, on: normalizeRouteOnField(rec.on) };
+    });
+}
+function isInlinePipelineStageBody(stage) {
+    return stage.system_prompt !== undefined || stage.uses === undefined;
+}
+function normalizePipelineStagesRouteOn(stages, options) {
+    const next = stages.map((stage) => {
+        if (!stage || typeof stage !== "object")
+            return stage;
+        let out = { ...stage };
+        if (Array.isArray(out.route)) {
+            out = {
+                ...out,
+                route: normalizeRouteEntries(out.route),
+            };
+        }
+        if (isInlinePipelineStageBody(out) && out.io === undefined) {
+            out = { ...out, ...REQUIRED_IO };
+        }
+        return out;
+    });
+    if (options?.ensureEntry &&
+        next.length > 0 &&
+        !next.some((stage) => stage?.entry === true)) {
+        const first = next[0];
+        next[0] = { ...first, entry: true };
+    }
+    return next;
+}
 export function buildCreateStageDraft(draft, args) {
     const existingIds = new Set(draft.pipeline.stages.map((s) => (typeof s.id === "string" ? s.id : "")));
     let stageId = stringArg(args, "id") ??
@@ -211,7 +265,7 @@ export function buildCreateStageDraft(draft, args) {
         ...(entry ? { entry: true } : {}),
     };
     if (Array.isArray(args.route)) {
-        pipelineEntry.route = args.route;
+        pipelineEntry.route = normalizeRouteEntries(args.route);
     }
     const nextDraft = {
         ...draft,
@@ -244,7 +298,7 @@ export function buildEditStageDraft(draft, args) {
         if (typeof args.entry === "boolean")
             next.entry = args.entry;
         if (Array.isArray(args.route))
-            next.route = args.route;
+            next.route = normalizeRouteEntries(args.route);
         if (stringArg(args, "uses"))
             next.uses = stringArg(args, "uses");
         return next;
@@ -317,7 +371,16 @@ export function buildCreatePipelineDraft(draft, args) {
             ok: true,
             nextDraft: {
                 ...draft,
-                pipeline: { ...pipeline, id: pipeline.id.trim() },
+                pipeline: {
+                    ...pipeline,
+                    id: pipeline.id.trim(),
+                    model: typeof pipeline.model === "string" && pipeline.model.trim()
+                        ? pipeline.model
+                        : stringArg(args, "model") ?? peekDefaultModel(),
+                    stages: normalizePipelineStagesRouteOn(pipeline.stages, {
+                        ensureEntry: true,
+                    }),
+                },
                 ...(Array.isArray(args.stages)
                     ? { stages: args.stages }
                     : {}),
@@ -331,15 +394,51 @@ export function buildCreatePipelineDraft(draft, args) {
             pipeline: {
                 ...draft.pipeline,
                 id,
-                ...(stringArg(args, "model") ? { model: stringArg(args, "model") } : {}),
+                model: stringArg(args, "model") ?? peekDefaultModel(),
                 ...(args.agent !== undefined ? { agent: args.agent } : {}),
                 ...(Array.isArray(args.stages)
-                    ? { stages: args.stages }
+                    ? {
+                        stages: normalizePipelineStagesRouteOn(args.stages, { ensureEntry: true }),
+                    }
                     : {}),
             },
         },
     };
 }
+function normalizeDraftStagePath(stagePath) {
+    return stagePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function stageWiringMatchesArtifact(stage, artifact) {
+    const id = typeof stage.id === "string" ? stage.id : "";
+    const uses = typeof stage.uses === "string" ? stage.uses : "";
+    const bodyId = typeof artifact.body.id === "string" ? artifact.body.id : "";
+    return ((uses.length > 0 &&
+        normalizeDraftStagePath(artifact.path) ===
+            normalizeDraftStagePath(uses)) ||
+        (id.length > 0 && bodyId === id));
+}
+/** Refuse stages wiring that diverges from draft.stages bodies (no silent prune). */
+export function validateEditPipelineStagesWiring(draft, nextStages) {
+    const artifacts = draft.stages ?? [];
+    for (const stage of nextStages) {
+        const matched = artifacts.some((artifact) => stageWiringMatchesArtifact(stage, artifact));
+        if (!matched) {
+            const label = (typeof stage.id === "string" && stage.id) ||
+                (typeof stage.uses === "string" && stage.uses) ||
+                "(unnamed)";
+            return `edit_pipeline stages wiring references "${label}" without a matching stage body — use create_stage / edit_stage to add or change stage files`;
+        }
+    }
+    for (const artifact of artifacts) {
+        const stillWired = nextStages.some((stage) => stageWiringMatchesArtifact(stage, artifact));
+        if (!stillWired) {
+            const label = (typeof artifact.body.id === "string" && artifact.body.id) ||
+                artifact.path;
+            return `edit_pipeline stages wiring drops stage body "${label}" — use create_stage / edit_stage to change stage files; wiring-only remove is refused`;
+        }
+    }
+    return null;
+}
 export function buildEditPipelineDraft(draft, args) {
     const patch = isPlainObject(args.patch) ? args.patch : args;
     const nextPipeline = {
@@ -352,12 +451,30 @@ export function buildEditPipelineDraft(draft, args) {
     if (patch.agent !== undefined)
         nextPipeline.agent = patch.agent;
     if (Array.isArray(patch.stages)) {
-        nextPipeline.stages = patch.stages;
+        const nextStages = normalizePipelineStagesRouteOn(patch.stages);
+        const wiringError = validateEditPipelineStagesWiring(draft, nextStages);
+        if (wiringError)
+            return { ok: false, error: wiringError };
+        nextPipeline.stages = nextStages;
     }
     if (patch.schemas !== undefined)
         nextPipeline.schemas = patch.schemas;
     if (patch.requires !== undefined)
         nextPipeline.requires = patch.requires;
+    if (isStringList(patch.memories)) {
+        if (patch.memories.length === 0)
+            delete nextPipeline.memories;
+        else
+            nextPipeline.memories = patch.memories;
+    }
+    if (patch.channels !== undefined) {
+        if (Array.isArray(patch.channels) && patch.channels.length === 0) {
+            delete nextPipeline.channels;
+        }
+        else {
+            nextPipeline.channels = patch.channels;
+        }
+    }
     return {
         ok: true,
         nextDraft: { ...draft, pipeline: nextPipeline },
@@ -428,6 +545,7 @@ export function createWorkshopBuildTools() {
     const listBuildsTool = {
         name: "list_builds",
         description: "List the same workshop rows as the studio picker (open builds and unbound disk pipelines). Each row includes catalogListed (whether Tasks/Pipelines would list that pipeline path). Does not create a build. Works when no build is focused.",
+        parameters: emptyParams,
         async handler(_args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -458,7 +576,14 @@ export function createWorkshopBuildTools() {
     };
     const focusBuildTool = {
         name: "focus_build",
-        description: "Move this chat onto a build by id, or onto an unbound disk pipeline by projectRoot and relativePath. A failed open returns the error, creates nothing, and leaves the pointer unchanged.",
+        description: "Move this chat onto a build by id, or onto an unbound disk pipeline by projectRoot and relativePath. Mid-turn, the mutation pin moves with the focus so studio and draft tools stay on the same build. A failed open returns the error, creates nothing, and leaves the pointer unchanged.",
+        parameters: Type.Union([
+            Type.Object({ id: Type.String({ minLength: 1 }) }, closed),
+            Type.Object({
+                projectRoot: Type.String({ minLength: 1 }),
+                relativePath: Type.String({ minLength: 1 }),
+            }, closed),
+        ]),
         async handler(args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -530,7 +655,8 @@ export function createWorkshopBuildTools() {
     };
     const createBuildTool = {
         name: "create_build",
-        description: "Persist a new untitled build and focus it, including when another build is already focused. No build id argument.",
+        description: "Persist a new untitled build and focus it when none is pinned. When a build is already pinned, returns that build without creating another. No build id argument.",
+        parameters: emptyParams,
         async handler(_args, ctx) {
             const live = liveWorkshopBinding(ctx);
             if (!live) {
@@ -551,6 +677,13 @@ export function createWorkshopAuthorMutatingTools() {
     const createPipelineTool = {
         name: "create_pipeline",
         description: "Create or replace the draft pipeline (id, optional model/stages). Mutates the in-memory draft immediately.",
+        parameters: Type.Object({
+            id: Type.String({ minLength: 1 }),
+            model: Type.Optional(Type.String()),
+            agent: Type.Optional(Type.Unknown()),
+            stages: Type.Optional(Type.Array(jsonObject)),
+            pipeline: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildCreatePipelineDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -561,7 +694,18 @@ export function createWorkshopAuthorMutatingTools() {
     };
     const editPipelineTool = {
         name: "edit_pipeline",
-        description: "Edit pipeline fields on the current draft (id, model, stages wiring, etc.). Mutates immediately.",
+        description: "Edit pipeline fields on the current draft (id, model, stages wiring, etc.). Stages wiring must match existing stage bodies — use create_stage / edit_stage to add or remove stages. Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            model: Type.Optional(Type.String()),
+            agent: Type.Optional(Type.Unknown()),
+            stages: Type.Optional(Type.Array(jsonObject)),
+            schemas: Type.Optional(Type.Unknown()),
+            requires: Type.Optional(Type.Unknown()),
+            memories: Type.Optional(Type.Array(Type.String())),
+            channels: Type.Optional(Type.Unknown()),
+            patch: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildEditPipelineDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -573,6 +717,18 @@ export function createWorkshopAuthorMutatingTools() {
     const createStageTool = {
         name: "create_stage",
         description: "Add a file-backed stage to the draft (uses: ./id.yaml + stage body with io). Mutates immediately; Accept confirms, Reject soft-undos.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            summary: Type.Optional(Type.String()),
+            label: Type.Optional(Type.String()),
+            uses: Type.Optional(Type.String()),
+            body: Type.Optional(jsonObject),
+            system_prompt: Type.Optional(Type.String()),
+            model: Type.Optional(Type.String()),
+            io: Type.Optional(jsonObject),
+            entry: Type.Optional(Type.Boolean()),
+            route: Type.Optional(Type.Array(Type.Unknown())),
+        }, closed),
         handler(args, ctx) {
             const built = buildCreateStageDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -584,6 +740,18 @@ export function createWorkshopAuthorMutatingTools() {
     const editStageTool = {
         name: "edit_stage",
         description: "Edit an existing draft stage by id (body fields and/or pipeline entry route/entry/uses). Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.String({ minLength: 1 }),
+            patch: Type.Optional(jsonObject),
+            body: Type.Optional(jsonObject),
+            pipeline_entry: Type.Optional(jsonObject),
+            entry: Type.Optional(Type.Boolean()),
+            route: Type.Optional(Type.Array(Type.Unknown())),
+            uses: Type.Optional(Type.String()),
+            system_prompt: Type.Optional(Type.String()),
+            model: Type.Optional(Type.String()),
+            io: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildEditStageDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -595,6 +763,13 @@ export function createWorkshopAuthorMutatingTools() {
     const createTaskTool = {
         name: "create_task",
         description: "Create or replace the optional task (id + goal) on the draft. Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            goal: Type.Optional(Type.String()),
+            summary: Type.Optional(Type.String()),
+            filename: Type.Optional(Type.String()),
+            body: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildCreateTaskDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -606,6 +781,13 @@ export function createWorkshopAuthorMutatingTools() {
     const editTaskTool = {
         name: "edit_task",
         description: "Edit the draft task fields (id, goal, body). Mutates immediately.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String()),
+            goal: Type.Optional(Type.String()),
+            filename: Type.Optional(Type.String()),
+            patch: Type.Optional(jsonObject),
+            body: Type.Optional(jsonObject),
+        }, closed),
         handler(args, ctx) {
             const built = buildEditTaskDraft(readDraftFromContext(ctx.getContext()), args);
             if (!built.ok)
@@ -627,6 +809,12 @@ export function createSaveTool(options = {}) {
     return {
         name: "save",
         description: "Validate-then-write the draft via catalog facades (createDraftPackage / overwriteDraftPackage). When directory is omitted, writes under workshop/<pipeline-id> on registered catalogs (or <pipeline-id> on the workspace catalog). The host adds registered workshop paths to stageflow.yaml so Run can see them. Pass directory only when the operator names a folder. Soft undo does not reverse disk. Prefer mode auto; set allowInvalid only when the operator explicitly requests saving invalid YAML. Do not pass projectRoot — the host binds it.",
+        parameters: Type.Object({
+            directory: Type.Optional(Type.String()),
+            pipelineFilename: Type.Optional(Type.String()),
+            mode: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("create"), Type.Literal("overwrite")])),
+            allowInvalid: Type.Optional(Type.Boolean()),
+        }, closed),
         async handler(args, ctx) {
             const writeTarget = await resolveSaveWriteTarget(ctx, options);
             if (!writeTarget.ok) {

package/dist/operatorAgent/types.d.ts

@@ -1,3 +1,4 @@
+import type { TSchema } from "typebox";
 import type { DraftPackage } from "../config/draftPackage.js";
 import type { ValidationResult } from "../config/validateCatalog.js";
 import type { AcceptProposalResult, ProposalArtifactDiff, UndoMutationResult } from "./proposals.js";
@@ -10,6 +11,7 @@ export type OperatorAgentToolHandler = (args: Record<string, unknown>, ctx: Oper
 export type OperatorAgentTool = {
     name: string;
     description: string;
+    parameters: TSchema;
     handler: OperatorAgentToolHandler;
 };
 export type OperatorAgentToolContext = {
@@ -17,6 +19,14 @@ export type OperatorAgentToolContext = {
     setContext(next: unknown): void;
     /** Apply mutation immediately and record an undo receipt. */
     emitProposal(proposal: OperatorAgentProposal): void;
+    /**
+     * Set only on an eval session. Returning a result skips the tool handler.
+     * Returning null lets the handler run. Absent on Workshop, author and Guide sessions.
+     */
+    evalGate?: {
+        decide(name: string, args: Record<string, unknown>): OperatorAgentToolResult | null;
+        observe(name: string, result: OperatorAgentToolResult): void;
+    };
 };
 export type OperatorAgentProposal = {
     /** Mutation id (Accept confirms; Reject / undoMutation soft-undos). */
@@ -72,6 +82,10 @@ export type WorkshopToolActivityUpdate = {
     draft?: DraftPackage;
     /** Build the turn is editing. Absent when the chat is unlinked. */
     buildId?: string;
+    /** Tool arguments, on `running`. */
+    args?: Record<string, unknown>;
+    /** Tool result `content`, on `complete`. */
+    result?: unknown;
 };
 export type OperatorAgentSession = {
     readonly profileId: string;
@@ -111,6 +125,15 @@ export type OperatorAgentHost = {
         profileId: string;
         context: unknown;
     }): OperatorAgentSession;
+    /**
+     * A session whose tools pass through `gate` before they run. The gate is required:
+     * an eval session with no gate is refused.
+     */
+    openEvalSession(input: {
+        profileId: string;
+        context: unknown;
+        gate: NonNullable<OperatorAgentToolContext["evalGate"]>;
+    }): OperatorAgentSession;
 };
 export type WorkshopDraftContext = {
     draft: DraftPackage;

package/dist/package-meta.d.ts

@@ -1,3 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.40.0";
+export declare const PACKAGE_VERSION = "0.44.0";
 export declare const BUILD_SHA: string;

package/dist/package-meta.js

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.40.0";
+export const PACKAGE_VERSION = "0.44.0";
 export const BUILD_SHA = process.env.STAGEFLOW_BUILD_SHA ?? "unknown";

package/dist/runstore/port.d.ts

@@ -1,4 +1,5 @@
 import type { StageLogLine } from "../agent/activity.js";
+import type { EvalTargetKind } from "../evals/constants.js";
 import type { ConfigOriginRecord } from "../config/configOrigin.js";
 import type { RunSubmission, RunSubmissionRecord } from "./submission.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
@@ -8,6 +9,9 @@ import type { CompletionCheck } from "../types/completion.js";
 import type { StageGateKind } from "../types/stage.js";
 import type { StageUsage } from "../types/usage.js";
 import type { OverviewRunRow } from "./overviewSummary.js";
+import type { CreateEvalRunInput, EvalCaseInput, EvalCaseRow, EvalGraderVersionInput, EvalResultInput, EvalResultWithGrades, EvalReviewPatch, EvalReviewRow, EvalRunPage, EvalRunProgress, EvalRunRow, FinishEvalRunInput, ListEvalRunsQuery } from "../evals/storeTypes.js";
+import type { SuggestionStatus } from "../evals/triage/constants.js";
+import type { SuggestionInput, SuggestionRow } from "../evals/triage/types.js";
 export type { ConfigOriginRecord };
 export type RunStatus = "created" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
 export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
@@ -40,6 +44,7 @@ export type PipelineTrackProjection = {
     nodes: PipelineTrackNode[];
     edges: PipelineTrackEdge[];
 };
+export type RunOrigin = "eval";
 export type RunMeta = {
     run_id: string;
     pipeline_id: string;
@@ -69,6 +74,8 @@ export type RunMeta = {
     config_origins?: ConfigOriginRecord[];
     pipeline_source?: "inline" | "path";
     caller_id?: string;
+    /** `eval` for stage runs started by an eval run; absent for normal runs. */
+    origin?: RunOrigin;
     run_manifest?: unknown;
     skip_gates?: boolean;
     /**
@@ -372,6 +379,7 @@ export type CreateRunInput = {
      */
     inlinePipeline?: InlinePipelineDefinition;
     callerId?: string;
+    origin?: RunOrigin;
     runManifest?: unknown;
     skipGates?: boolean;
 };
@@ -382,6 +390,8 @@ export type ListRunsFilter = {
     /** Match pipeline_id or pipeline_path */
     pipeline?: string;
     caller_id?: string;
+    /** Default (undefined) hides eval stage runs; `"any"` includes them; `"eval"` returns only them. */
+    origin?: RunOrigin | "any";
 };
 /**
  * Persistence port for pipeline run state.
@@ -466,6 +476,39 @@ export interface RunStore {
     listRuns(filter?: ListRunsFilter): Promise<RunSummary[]>;
     /** One light row per run created at or after `since` (ISO), newest first, with summed stage cost. No stages are loaded. */
     listRunOverviewRows(since: string): Promise<OverviewRunRow[]>;
+    createEvalRun(input: CreateEvalRunInput): Promise<EvalRunRow>;
+    insertEvalCases(evalRunId: string, cases: EvalCaseInput[]): Promise<void>;
+    /** Result row and its grade rows in one transaction; replaces any earlier grades for the same result. */
+    upsertEvalResult(result: EvalResultInput): Promise<void>;
+    updateEvalRunProgress(evalRunId: string, progress: EvalRunProgress): Promise<void>;
+    finishEvalRun(evalRunId: string, input: FinishEvalRunInput): Promise<void>;
+    getEvalRun(evalRunId: string): Promise<EvalRunRow | null>;
+    getEvalRunByNumber(projectRoot: string, evalId: string, runNumber: number): Promise<EvalRunRow | null>;
+    listEvalRuns(query: ListEvalRunsQuery): Promise<EvalRunPage>;
+    listEvalResults(evalRunId: string): Promise<EvalResultWithGrades[]>;
+    getEvalResultsForCase(evalRunId: string, caseId: string): Promise<EvalResultWithGrades[]>;
+    getEvalCases(evalRunId: string): Promise<EvalCaseRow[]>;
+    /** `tags` replaces the tag set and is accepted only for results with `passed = 0`. */
+    putEvalReview(evalRunId: string, caseId: string, repeatIndex: number, patch: EvalReviewPatch): Promise<EvalReviewRow>;
+    getEvalReviews(evalRunId: string): Promise<EvalReviewRow[]>;
+    /** The eval's failure-type vocabulary, most recently used first. */
+    listFailureTypes(projectRoot: string, evalId: string): Promise<string[]>;
+    /** Inserts unseen grader hashes with the next ordinal per grader id; returns grader id to ordinal. */
+    recordGraderVersions(projectRoot: string, evalId: string, graders: EvalGraderVersionInput[]): Promise<Record<string, number>>;
+    /** Deletes the eval run and its rows; returns the stage run ids it started so the caller can delete those runs. */
+    deleteEvalRun(evalRunId: string): Promise<string[]>;
+    /** Distinct non-null result subject refs (stage run ids or agent session ids) when the run's target kind matches. */
+    listEvalSubjectRefs(evalRunId: string, targetKind: EvalTargetKind): Promise<string[]>;
+    /** Inserts or replaces pending suggestions (accepted and dismissed are kept); returns the rows written. */
+    upsertEvalSuggestions(evalRunId: string, inputs: SuggestionInput[]): Promise<SuggestionRow[]>;
+    listEvalSuggestions(evalRunId: string, status?: SuggestionStatus): Promise<SuggestionRow[]>;
+    /** Pending only; returns how many changed. */
+    dismissEvalSuggestions(evalRunId: string, ids: string[]): Promise<number>;
+    /** Pending only; adds the failure type and `bucket:` tags through the review write path. */
+    acceptEvalSuggestions(evalRunId: string, ids: string[]): Promise<{
+        accepted: number;
+        tagged: number;
+    }>;
     /** Idempotent upsert; returns the realpath/resolve-normalized absolute key. */
     ensureProject(absPath: string): Promise<string>;
     /** Absolute roots from the durable projects registry. */

package/dist/runstore/retention.d.ts

@@ -1,4 +1,5 @@
 import type { RunMeta, RunStatus } from "./port.js";
+import { type RunClockTerminalStatus } from "./runStatusClock.js";
 export type RetentionDecision = "none" | "slim" | "purge";
 export type StatusRetentionWindow = {
     slimMs: number;
@@ -24,4 +25,4 @@ export declare function slimArtifactMaxBytesFromEnv(env?: NodeJS.ProcessEnv): nu
  * 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";
+export declare function isTerminalRunStatus(status: RunStatus | undefined): status is RunClockTerminalStatus;

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,7 +1,11 @@
 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 { EvalTargetKind } from "../../evals/constants.js";
 import type { StageEnvelope } from "../../types/envelope.js";
 import type { StageLogLine } from "../../agent/activity.js";
 import { type CreateFeedbackLoopInput, type CreateFeedbackReplayInput, type CreateFeedbackReplayStagePassInput, type CreateForkGenerationInput, type CreateRunInput, type CreatedRun, type FeedbackLoopPatch, type FeedbackLoopRecord, type FeedbackLoopState, type FeedbackReplayPatch, type FeedbackReplayRecord, type FeedbackReplayStagePassPatch, type FeedbackReplayStagePassRecord, type ForkGenerationPatch, type ForkGenerationRecord, type ListRunsFilter, type RunDetail, type RunMeta, type RunPipelineDagSnapshot, type RunStatus, type RunStore, type RunSummary, type StageExecution, type StageExecutionPatch, type StageLogEvent, type TriggerRecord, type UpsertTriggerInput, type VerificationCheckResult, type VerificationCheckResultPatch, type ConfigOriginRecord } from "../port.js";
+import type { SuggestionStatus } from "../../evals/triage/constants.js";
+import type { SuggestionInput, SuggestionRow } from "../../evals/triage/types.js";
 import type { OverviewRunRow } from "../overviewSummary.js";
 import { type RunSubmissionRecord } from "../submission.js";
 type SqliteRunStoreOpenerMode = "assert" | "migrate";
@@ -28,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: {
@@ -78,6 +83,30 @@ export declare class SqliteRunStore implements RunStore {
     listStageEvents(runId: string, stageId: string, attempt?: number): Promise<StageLogEvent[]>;
     listRuns(filter?: ListRunsFilter): Promise<RunSummary[]>;
     listRunOverviewRows(since: string): Promise<OverviewRunRow[]>;
+    createEvalRun(input: CreateEvalRunInput): Promise<EvalRunRow>;
+    insertEvalCases(evalRunId: string, cases: EvalCaseInput[]): Promise<void>;
+    upsertEvalResult(result: EvalResultInput): Promise<void>;
+    updateEvalRunProgress(evalRunId: string, progress: EvalRunProgress): Promise<void>;
+    finishEvalRun(evalRunId: string, input: FinishEvalRunInput): Promise<void>;
+    getEvalRun(evalRunId: string): Promise<EvalRunRow | null>;
+    getEvalRunByNumber(projectRoot: string, evalId: string, runNumber: number): Promise<EvalRunRow | null>;
+    listEvalRuns(query: ListEvalRunsQuery): Promise<EvalRunPage>;
+    listEvalResults(evalRunId: string): Promise<EvalResultWithGrades[]>;
+    getEvalResultsForCase(evalRunId: string, caseId: string): Promise<EvalResultWithGrades[]>;
+    getEvalCases(evalRunId: string): Promise<EvalCaseRow[]>;
+    putEvalReview(evalRunId: string, caseId: string, repeatIndex: number, patch: EvalReviewPatch): Promise<EvalReviewRow>;
+    getEvalReviews(evalRunId: string): Promise<EvalReviewRow[]>;
+    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[]>;
+    upsertEvalSuggestions(evalRunId: string, inputs: SuggestionInput[]): Promise<SuggestionRow[]>;
+    listEvalSuggestions(evalRunId: string, status?: SuggestionStatus): Promise<SuggestionRow[]>;
+    dismissEvalSuggestions(evalRunId: string, ids: string[]): Promise<number>;
+    acceptEvalSuggestions(evalRunId: string, ids: string[]): Promise<{
+        accepted: number;
+        tagged: number;
+    }>;
+    deleteEvalRun(evalRunId: string): Promise<string[]>;
     ensureProject(absPath: string): Promise<string>;
     listRegisteredProjects(): Promise<string[]>;
     upsertTrigger(input: UpsertTriggerInput): Promise<TriggerRecord>;