stageflow 0.39.0 → 0.42.0

package/dist/runstore/sqlite/migrations/015-evals.js

@@ -0,0 +1,157 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Eval runs, their cases, results, grades and the author's reviews, plus `runs.origin` so stage runs
+ * started by an eval can be hidden from normal run views. `eval_run_counters` keeps `run_number`
+ * from being reused after an eval run is deleted.
+ */
+export const MIGRATION_015 = {
+    version: 15,
+    name: "015_evals",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+ALTER TABLE runs ADD COLUMN origin TEXT;
+CREATE INDEX runs_origin ON runs (origin);
+
+CREATE TABLE eval_runs (
+  eval_run_id TEXT PRIMARY KEY,
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  run_number INTEGER NOT NULL,
+  eval_path TEXT NOT NULL,
+  eval_hash TEXT NOT NULL,
+  target_kind TEXT NOT NULL CHECK (target_kind IN ('stage','agent')),
+  target_ref_json TEXT NOT NULL,
+  target_version_hash TEXT NOT NULL,
+  dataset_path TEXT NOT NULL,
+  dataset_hash TEXT NOT NULL,
+  config_json TEXT NOT NULL,
+  config_fingerprint TEXT NOT NULL,
+  config_components_json TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('queued','running','completed','failed','cancelled','budget_stopped')),
+  status_reason TEXT,
+  passed INTEGER,
+  repeats INTEGER NOT NULL,
+  pass_threshold REAL NOT NULL,
+  max_cost_usd REAL NOT NULL,
+  cases_total INTEGER NOT NULL,
+  results_total INTEGER NOT NULL,
+  results_done INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  engine_name TEXT NOT NULL,
+  engine_version TEXT NOT NULL,
+  stageflow_version TEXT NOT NULL,
+  label TEXT,
+  started_via TEXT NOT NULL CHECK (started_via IN ('console','cli','mcp')),
+  caller_id TEXT,
+  summary_json TEXT,
+  created_at TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT
+);
+CREATE UNIQUE INDEX eval_runs_number ON eval_runs (project_root, eval_id, run_number);
+CREATE INDEX eval_runs_eval ON eval_runs (project_root, eval_id, created_at DESC);
+CREATE INDEX eval_runs_status ON eval_runs (status);
+
+CREATE TABLE eval_run_counters (
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  last_number INTEGER NOT NULL,
+  PRIMARY KEY (project_root, eval_id)
+);
+
+CREATE TABLE eval_cases (
+  eval_run_id TEXT NOT NULL REFERENCES eval_runs (eval_run_id) ON DELETE CASCADE,
+  case_id TEXT NOT NULL,
+  position INTEGER NOT NULL,
+  case_json TEXT NOT NULL,
+  PRIMARY KEY (eval_run_id, case_id)
+);
+
+CREATE TABLE eval_results (
+  eval_run_id TEXT NOT NULL REFERENCES eval_runs (eval_run_id) ON DELETE CASCADE,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('completed','stage_failed','needs_input','error','skipped_budget','cancelled')),
+  error_code TEXT,
+  error_message TEXT,
+  stage_run_id TEXT,
+  output_json TEXT,
+  latency_ms INTEGER,
+  cost_usd REAL,
+  tokens_in INTEGER,
+  tokens_out INTEGER,
+  score REAL,
+  passed INTEGER NOT NULL DEFAULT 0,
+  has_grader_errors INTEGER NOT NULL DEFAULT 0,
+  budget_warnings_json TEXT,
+  started_at TEXT,
+  finished_at TEXT,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index),
+  FOREIGN KEY (eval_run_id, case_id) REFERENCES eval_cases (eval_run_id, case_id) ON DELETE CASCADE
+);
+CREATE INDEX eval_results_stage_run ON eval_results (stage_run_id);
+
+CREATE TABLE eval_grades (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  grader_id TEXT NOT NULL,
+  grader_type TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('graded','error')),
+  passed INTEGER,
+  score REAL,
+  raw_value REAL,
+  reason TEXT,
+  details_json TEXT,
+  error_code TEXT,
+  judge_model TEXT,
+  judge_cost_usd REAL,
+  judge_tokens_in INTEGER,
+  judge_tokens_out INTEGER,
+  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_grader_versions (
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  grader_id TEXT NOT NULL,
+  grader_hash TEXT NOT NULL,
+  ordinal INTEGER NOT NULL,
+  first_seen_at TEXT NOT NULL,
+  PRIMARY KEY (project_root, eval_id, grader_id, grader_hash)
+);
+
+CREATE TABLE eval_failure_types (
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (project_root, eval_id, name COLLATE NOCASE)
+);
+
+CREATE TABLE eval_result_reviews (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER 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),
+  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_result_tags (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  tag TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index, tag COLLATE NOCASE),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/016-eval-subject-ref.d.ts

@@ -0,0 +1,12 @@
+import type Database from "better-sqlite3";
+/**
+ * Agent eval results point at an agent session, not a stage run: `subject_ref` is the root subject id
+ * (stage run id for stage results, agent session id for agent results). `turns` and `tool_call_count`
+ * are agent summaries. Additive; stage rows keep `stage_run_id` and are backfilled.
+ */
+export declare const MIGRATION_016: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/016-eval-subject-ref.js

@@ -0,0 +1,20 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Agent eval results point at an agent session, not a stage run: `subject_ref` is the root subject id
+ * (stage run id for stage results, agent session id for agent results). `turns` and `tool_call_count`
+ * are agent summaries. Additive; stage rows keep `stage_run_id` and are backfilled.
+ */
+export const MIGRATION_016 = {
+    version: 16,
+    name: "016_eval_subject_ref",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+ALTER TABLE eval_results ADD COLUMN subject_ref TEXT;
+ALTER TABLE eval_results ADD COLUMN turns INTEGER;
+ALTER TABLE eval_results ADD COLUMN tool_call_count INTEGER;
+UPDATE eval_results SET subject_ref = stage_run_id WHERE stage_run_id IS NOT NULL;
+CREATE INDEX eval_results_subject_ref ON eval_results (subject_ref);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/017-eval-result-suggestions.d.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+/**
+ * Suggested bucket and failure type per failed eval result, produced on request by a classifier
+ * (`jev` or `judge`). A suggestion becomes a tag only when the author accepts it. Additive.
+ */
+export declare const MIGRATION_017: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/017-eval-result-suggestions.js

@@ -0,0 +1,36 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Suggested bucket and failure type per failed eval result, produced on request by a classifier
+ * (`jev` or `judge`). A suggestion becomes a tag only when the author accepts it. Additive.
+ */
+export const MIGRATION_017 = {
+    version: 17,
+    name: "017_eval_result_suggestions",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+CREATE TABLE eval_result_suggestions (
+  id TEXT PRIMARY KEY,
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('jev','judge')),
+  bucket TEXT NOT NULL CHECK (bucket IN ('agent_wrong','grader_wrong','case_wrong','unclear')),
+  failure_type TEXT,
+  confidence REAL NOT NULL,
+  probabilities_json TEXT NOT NULL,
+  grader_false_alarms_json TEXT NOT NULL,
+  model TEXT NOT NULL,
+  prompt_version INTEGER NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','accepted','dismissed')),
+  batch_id TEXT NOT NULL,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  state_truncated INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  UNIQUE (eval_run_id, case_id, repeat_index, source),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+CREATE INDEX eval_result_suggestions_run ON eval_result_suggestions (eval_run_id, status);
+`);
+    },
+};

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

@@ -13,6 +13,9 @@ import { MIGRATION_011 } from "./011-email-dispatch-key.js";
 import { MIGRATION_012 } from "./012-trigger-fires.js";
 import { MIGRATION_013 } from "./013-agents.js";
 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";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -28,6 +31,9 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_012,
     MIGRATION_013,
     MIGRATION_014,
+    MIGRATION_015,
+    MIGRATION_016,
+    MIGRATION_017,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

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

@@ -0,0 +1,14 @@
+import type Database from "better-sqlite3";
+import type { SuggestionInput, SuggestionRow } from "../../evals/triage/types.js";
+/** Inserts or replaces pending suggestions; accepted and dismissed ones are kept. Returns the rows this call wrote. */
+export declare function upsertEvalSuggestions(db: Database.Database, evalRunId: string, inputs: SuggestionInput[]): SuggestionRow[];
+export declare function listEvalSuggestions(db: Database.Database, evalRunId: string, status?: SuggestionRow["status"]): SuggestionRow[];
+export declare function dismissEvalSuggestions(db: Database.Database, evalRunId: string, ids: string[]): number;
+/**
+ * Marks pending suggestions accepted and adds their failure type and `bucket:<bucket>` tags to the result
+ * through `putEvalReview`, keeping tags already there. Returns how many were accepted and how many results gained a tag.
+ */
+export declare function acceptEvalSuggestions(db: Database.Database, evalRunId: string, ids: string[]): {
+    accepted: number;
+    tagged: number;
+};

package/dist/runstore/sqlite/suggestionStore.js

@@ -0,0 +1,132 @@
+import { randomBytes } from "node:crypto";
+import { EvalStoreError } from "../../evals/storeError.js";
+import { BUCKET_TAG_PREFIX } from "../../evals/triage/constants.js";
+import { getEvalReviews, putEvalReview } from "./evalStore.js";
+const now = () => new Date().toISOString();
+function suggestionFromDb(row) {
+    return {
+        id: row.id,
+        evalRunId: row.eval_run_id,
+        caseId: row.case_id,
+        repeatIndex: row.repeat_index,
+        source: row.source,
+        bucket: row.bucket,
+        failureType: row.failure_type,
+        confidence: row.confidence,
+        bucketProbabilities: JSON.parse(row.probabilities_json),
+        graderFalseAlarms: JSON.parse(row.grader_false_alarms_json),
+        model: row.model,
+        promptVersion: row.prompt_version,
+        status: row.status,
+        batchId: row.batch_id,
+        costUsd: row.cost_usd,
+        stateTruncated: row.state_truncated === 1,
+        createdAt: row.created_at,
+    };
+}
+/** Inserts or replaces pending suggestions; accepted and dismissed ones are kept. Returns the rows this call wrote. */
+export function upsertEvalSuggestions(db, evalRunId, inputs) {
+    const written = [];
+    const at = now();
+    db.transaction(() => {
+        for (const input of inputs) {
+            const info = db
+                .prepare(`INSERT INTO eval_result_suggestions
+             (id, eval_run_id, case_id, repeat_index, source, bucket, failure_type, confidence, probabilities_json,
+              grader_false_alarms_json, model, prompt_version, status, batch_id, cost_usd, state_truncated, created_at)
+           VALUES (@id, @eval_run_id, @case_id, @repeat_index, @source, @bucket, @failure_type, @confidence, @probabilities_json,
+              @grader_false_alarms_json, @model, @prompt_version, 'pending', @batch_id, @cost_usd, @state_truncated, @at)
+           ON CONFLICT (eval_run_id, case_id, repeat_index, source) DO UPDATE SET
+             bucket = excluded.bucket, failure_type = excluded.failure_type, confidence = excluded.confidence,
+             probabilities_json = excluded.probabilities_json, grader_false_alarms_json = excluded.grader_false_alarms_json,
+             model = excluded.model, prompt_version = excluded.prompt_version, batch_id = excluded.batch_id,
+             cost_usd = excluded.cost_usd, state_truncated = excluded.state_truncated, created_at = excluded.created_at
+           WHERE eval_result_suggestions.status = 'pending'`)
+                .run({
+                id: `sg_${randomBytes(8).toString("hex")}`,
+                eval_run_id: evalRunId,
+                case_id: input.caseId,
+                repeat_index: input.repeatIndex,
+                source: input.source,
+                bucket: input.bucket,
+                failure_type: input.failureType,
+                confidence: input.confidence,
+                probabilities_json: JSON.stringify(input.bucketProbabilities),
+                grader_false_alarms_json: JSON.stringify(input.graderFalseAlarms),
+                model: input.model,
+                prompt_version: input.promptVersion,
+                batch_id: input.batchId,
+                cost_usd: input.costUsd,
+                state_truncated: input.stateTruncated ? 1 : 0,
+                at,
+            });
+            if (info.changes === 0)
+                continue;
+            const row = db
+                .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? AND case_id = ? AND repeat_index = ? AND source = ?`)
+                .get(evalRunId, input.caseId, input.repeatIndex, input.source);
+            written.push(suggestionFromDb(row));
+        }
+    })();
+    return written;
+}
+export function listEvalSuggestions(db, evalRunId, status) {
+    const rows = (status !== undefined
+        ? db
+            .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? AND status = ? ORDER BY case_id, repeat_index, source`)
+            .all(evalRunId, status)
+        : db
+            .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? ORDER BY case_id, repeat_index, source`)
+            .all(evalRunId));
+    return rows.map(suggestionFromDb);
+}
+export function dismissEvalSuggestions(db, evalRunId, ids) {
+    let changed = 0;
+    db.transaction(() => {
+        for (const id of ids) {
+            changed += db
+                .prepare(`UPDATE eval_result_suggestions SET status = 'dismissed' WHERE eval_run_id = ? AND id = ? AND status = 'pending'`)
+                .run(evalRunId, id).changes;
+        }
+    })();
+    return changed;
+}
+/**
+ * Marks pending suggestions accepted and adds their failure type and `bucket:<bucket>` tags to the result
+ * through `putEvalReview`, keeping tags already there. Returns how many were accepted and how many results gained a tag.
+ */
+export function acceptEvalSuggestions(db, evalRunId, ids) {
+    let accepted = 0;
+    let tagged = 0;
+    db.transaction(() => {
+        for (const id of ids) {
+            const found = db
+                .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? AND id = ? AND status = 'pending'`)
+                .get(evalRunId, id);
+            if (found === undefined)
+                continue;
+            const suggestion = suggestionFromDb(found);
+            const add = [
+                ...(suggestion.failureType !== null ? [suggestion.failureType] : []),
+                `${BUCKET_TAG_PREFIX}${suggestion.bucket}`,
+            ];
+            const have = getEvalReviews(db, evalRunId).find((r) => r.caseId === suggestion.caseId && r.repeatIndex === suggestion.repeatIndex)?.tags ?? [];
+            const haveKeys = new Set(have.map((t) => t.toLowerCase()));
+            const fresh = add.filter((t) => !haveKeys.has(t.toLowerCase()));
+            if (fresh.length > 0) {
+                try {
+                    putEvalReview(db, evalRunId, suggestion.caseId, suggestion.repeatIndex, { tags: [...have, ...fresh] });
+                    tagged += 1;
+                }
+                catch (err) {
+                    if (err instanceof EvalStoreError && err.code === "EVAL_TAGS_ON_PASSED_RESULT")
+                        continue;
+                    throw err;
+                }
+            }
+            db.prepare(`UPDATE eval_result_suggestions SET status = 'accepted' WHERE id = ?`).run(id);
+            accepted += 1;
+        }
+    })();
+    return { accepted, tagged };
+}

package/dist/runtime/gitCheckoutCapability.d.ts

@@ -1,4 +1,5 @@
 import type { CheckoutCapability } from "./completionCheckRunner.js";
+export declare function runGit(root: string, args: string[]): Promise<Buffer>;
 /**
  * Git-backed checkout observation. It fingerprints tracked and untracked
  * files before the agent runs, so pre-existing changes are not attributed to

package/dist/runtime/gitCheckoutCapability.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, readFile, readlink } from "node:fs/promises";
 import path from "node:path";
 import { runGit as execGit } from "../git/exec.js";
-async function runGit(root, args) {
+export async function runGit(root, args) {
     const result = await execGit({
         cwd: root,
         args,

package/dist/runtime/gitWorktreeCheckout.d.ts

@@ -0,0 +1,22 @@
+import { sanitizeContainerNameSegment } from "./sandboxContainer.js";
+export declare const sanitizeBranchForPath: typeof sanitizeContainerNameSegment;
+export declare function defaultBranchNameForTask(taskId: string): string;
+export declare function worktreePathFor(projectRoot: string, branch: string): string;
+/**
+ * Ensures a git worktree checked out to `branch` (creating the branch from
+ * `base` if it doesn't exist yet) exists at a deterministic path derived
+ * from the branch name, and returns that path.
+ *
+ * Deterministic (not per-run/random) on purpose: `resolveAndValidateCheckout`
+ * is called twice per run start (runManager.ts, for the checkout lease key,
+ * then pipelineRunner.ts, for the durable run record) — a random path would
+ * create two worktrees for one run. A stable path also means rerunning the
+ * same task/branch reuses the same worktree, matching the "leave it in
+ * place" behavior an operator gets from making one by hand.
+ */
+export declare function ensureWorktreeCheckout(params: {
+    projectRoot: string;
+    branch?: string;
+    base?: string;
+    taskId: string;
+}): Promise<string>;

package/dist/runtime/gitWorktreeCheckout.js

@@ -0,0 +1,120 @@
+import { access, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { runGit } from "./gitCheckoutCapability.js";
+import { sanitizeContainerNameSegment } from "./sandboxContainer.js";
+/**
+ * Auto-created worktrees live as siblings of the project root (not nested
+ * inside it) — the same place `examples/ship-feature/README.md` already
+ * tells operators to put a hand-made one, just automated.
+ */
+const WORKTREES_DIR_NAME = ".stageflow-worktrees";
+export const sanitizeBranchForPath = sanitizeContainerNameSegment;
+export function defaultBranchNameForTask(taskId) {
+    return `stageflow/${sanitizeBranchForPath(taskId)}`;
+}
+export function worktreePathFor(projectRoot, branch) {
+    return path.join(path.dirname(projectRoot), WORKTREES_DIR_NAME, sanitizeBranchForPath(branch));
+}
+async function git(projectRoot, args) {
+    const stdout = await runGit(projectRoot, args);
+    return stdout.toString("utf8");
+}
+async function registeredWorktreePaths(projectRoot) {
+    const stdout = await git(projectRoot, ["worktree", "list", "--porcelain"]);
+    const paths = new Set();
+    for (const line of stdout.split("\n")) {
+        const match = /^worktree (.+)$/.exec(line);
+        if (match)
+            paths.add(match[1]);
+    }
+    return paths;
+}
+async function branchExists(projectRoot, branch) {
+    try {
+        await git(projectRoot, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// A ref/branch value starting with `-` can get reinterpreted by git as a
+// flag instead of a literal name (e.g. `-b --upload-pack=...`) — task YAML
+// is operator-authored, not attacker input, but rejecting this outright is
+// free and closes the class of mistake/footgun entirely.
+function assertNotFlagLike(value, label) {
+    if (value.startsWith("-")) {
+        throw new Error(`Invalid ${label} "${value}": must not start with "-"`);
+    }
+}
+/**
+ * Ensures a git worktree checked out to `branch` (creating the branch from
+ * `base` if it doesn't exist yet) exists at a deterministic path derived
+ * from the branch name, and returns that path.
+ *
+ * Deterministic (not per-run/random) on purpose: `resolveAndValidateCheckout`
+ * is called twice per run start (runManager.ts, for the checkout lease key,
+ * then pipelineRunner.ts, for the durable run record) — a random path would
+ * create two worktrees for one run. A stable path also means rerunning the
+ * same task/branch reuses the same worktree, matching the "leave it in
+ * place" behavior an operator gets from making one by hand.
+ */
+export async function ensureWorktreeCheckout(params) {
+    // `git worktree list --porcelain` reports canonicalized paths (symlinks
+    // resolved, e.g. macOS's /var -> /private/var) — realpath the project
+    // root up front so every path this function builds or compares matches
+    // what git itself reports, instead of drifting apart on a symlinked tmp
+    // dir or similar.
+    const projectRoot = await realpath(params.projectRoot);
+    const branch = params.branch ?? defaultBranchNameForTask(params.taskId);
+    assertNotFlagLike(branch, "checkout.branch");
+    if (params.base !== undefined)
+        assertNotFlagLike(params.base, "checkout.base");
+    const targetPath = worktreePathFor(projectRoot, branch);
+    const registered = await registeredWorktreePaths(projectRoot);
+    if (registered.has(targetPath)) {
+        if (await pathExists(targetPath)) {
+            return targetPath;
+        }
+        // Registered but the directory is gone (e.g. deleted with `rm -rf`
+        // instead of `git worktree remove`) — clear the stale registration so
+        // `worktree add` below doesn't refuse to reuse the path.
+        await git(projectRoot, ["worktree", "prune"]);
+    }
+    else if (await pathExists(targetPath)) {
+        throw new Error(`Worktree path already exists but is not a registered git worktree: ${targetPath}. Remove it or use a different branch name.`);
+    }
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    if (await branchExists(projectRoot, branch)) {
+        await git(projectRoot, ["worktree", "add", targetPath, branch]);
+    }
+    else {
+        await git(projectRoot, [
+            "worktree",
+            "add",
+            targetPath,
+            "-b",
+            branch,
+            params.base ?? "HEAD",
+        ]);
+    }
+    // Two concurrent run-starts auto-creating the same branch/worktree can
+    // race inside `git worktree add` itself — for the "branch already
+    // exists" path this has been observed to exit 0 while leaving no
+    // directory behind (the loser silently no-ops instead of erroring).
+    // Turn that into a loud, unambiguous failure rather than handing back a
+    // "successful" path that doesn't exist.
+    if (!(await pathExists(targetPath))) {
+        throw new Error(`git worktree add reported success but ${targetPath} does not exist — likely a concurrent worktree creation for the same branch ("${branch}"); retry.`);
+    }
+    return targetPath;
+}

package/dist/runtime/pipelineRunner.d.ts

@@ -1,7 +1,7 @@
 import type { RunSubmission } from "../runstore/submission.js";
 import type { StagePort } from "../agent/port.js";
 import { type ValidationFinding } from "../config/validateCatalog.js";
-import type { RunStore } from "../runstore/port.js";
+import type { RunOrigin, RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { StageHitlController } from "./stageHitl.js";
 import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline.js";
@@ -130,6 +130,7 @@ export declare function startPipeline(options: {
         halted: boolean;
     };
     callerId?: string | null;
+    origin?: RunOrigin;
     skills?: SkillsPayload;
 }): Promise<StartedPipeline>;
 export declare function resolveTaskPath(taskArg: string, cwd?: string): string;

package/dist/runtime/pipelineRunner.js

@@ -224,6 +224,7 @@ async function preparePipeline(options) {
                 ? { pipelineBody: persistence.fields.pipelineBody }
                 : {}),
             ...(callerId !== null ? { callerId } : {}),
+            ...(options.origin !== undefined ? { origin: options.origin } : {}),
             runManifest,
             skipGates: options.skipGates,
         });
@@ -329,6 +330,7 @@ export async function startPipeline(options) {
         operatorCatalog: options.operatorCatalog,
         skipGates: options.skipGates,
         callerId: options.callerId,
+        ...(options.origin !== undefined ? { origin: options.origin } : {}),
         ...(options.skills !== undefined ? { skills: options.skills } : {}),
     });
     if (prepared.run.created === false) {

package/dist/runtime/runManager.d.ts

@@ -2,7 +2,7 @@ import { type RunSubmission } from "../runstore/submission.js";
 import type { StagePort, OpaqueAnswer } from "../agent/port.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type DiskBreakdown, type FreeSpaceReader } from "../runstore/diskUsage.js";
-import { type RunStore } from "../runstore/port.js";
+import { type RunOrigin, type RunStore } from "../runstore/port.js";
 import type { TaskFile } from "../types/task.js";
 import { type PipelineRunResult } from "./pipelineRunner.js";
 import { type SkillsPayload } from "./runSkills.js";
@@ -314,6 +314,7 @@ export declare class RunManager {
         projectRoot?: string;
         /** Attribution from auth only — never from request body/query. */
         callerId?: string | null;
+        origin?: RunOrigin;
         skills?: SkillsPayload;
     }, submission?: RunSubmission): Promise<StartRunResult>;
     rerun(runId: string, options?: {