stageflow 0.25.0 → 0.27.0

package/dist/cli/runCommand.d.ts

@@ -1,11 +1,12 @@
 import type { RunStore } from "../runstore/port.js";
 import type { StartRunResult } from "../runtime/runManager.js";
+import type { TaskFile } from "../types/task.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
 import { type CliRunReportIo } from "./runOutput.js";
-export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
+export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
 export type RunCommandIo = CliRunReportIo;
 export type StartRunFn = (input: {
-    task: string;
+    task: string | TaskFile;
     pipeline: string;
     checkoutOverride?: string;
     skipGates?: boolean;

package/dist/cli/runCommand.js

@@ -1,11 +1,16 @@
-import { PipelineValidationError } from "../runtime/pipelineRunner.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { coerceTaskFile } from "../config/loadTask.js";
+import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
+import { PipelinePreflightError, PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
-import { httpStartRun, httpStoreReader, resolveAbsolute } from "./hostClient.js";
-import { reportCliRun, } from "./runOutput.js";
+import { httpEnsureProject, httpStartRun, httpStoreReader } from "./hostClient.js";
+import { reportCliRun, writeQueuedAdmissionLine, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_USAGE = `Usage:
-  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -20,6 +25,8 @@ function parseRunArgs(args) {
     let task;
     let pipeline;
     let checkout;
+    let repository;
+    let ref;
     let gitSha;
     let ciPrUrl;
     let ciJobUrl;
@@ -55,6 +62,20 @@ function parseRunArgs(args) {
             }
             checkout = value;
         }
+        else if (arg === "--repository") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --repository");
+            }
+            repository = value;
+        }
+        else if (arg === "--ref") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --ref");
+            }
+            ref = value;
+        }
         else if (arg === "--git-sha") {
             const value = args[++i];
             if (value === undefined || value.length === 0) {
@@ -123,6 +144,8 @@ function parseRunArgs(args) {
         task,
         pipeline,
         checkout,
+        repository,
+        ref,
         gitSha,
         ciPrUrl,
         ciJobUrl,
@@ -130,18 +153,60 @@ function parseRunArgs(args) {
         operatorAgentDir,
     };
 }
+async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
+    const absolute = path.resolve(cwd, taskPath);
+    const yamlText = await readFile(absolute, "utf8");
+    const raw = parseYaml(yamlText);
+    const task = coerceTaskFile(raw);
+    if (task === undefined) {
+        throw new Error(`Invalid task file ${absolute}: id and goal are required strings`);
+    }
+    if (overrides.repository !== undefined)
+        task.repository = overrides.repository;
+    if (overrides.ref !== undefined)
+        task.ref = overrides.ref;
+    return task;
+}
 function defaultStartRun(cwd, base, ensureService) {
     return async (input) => {
         const ensured = await ensureService();
         if (!ensured.ok) {
-            return { ok: false, reason: ensured.message, status: 503 };
+            return {
+                ok: false,
+                reason: ensured.message,
+                status: 503,
+                ...(ensured.reason === "autostart_disabled"
+                    ? { code: "autostart_disabled" }
+                    : {}),
+            };
         }
+        const pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+        let task = input.task;
+        let projectRoot = pipelineRef.project_root;
+        if (typeof input.task === "string") {
+            const absTask = path.resolve(cwd, input.task);
+            const cwdAbs = path.resolve(cwd);
+            const relTask = path.relative(cwdAbs, absTask);
+            if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
+                task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+            }
+            else {
+                const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
+                task = taskRef.path;
+                projectRoot = taskRef.project_root;
+            }
+        }
+        const ensuredProject = await httpEnsureProject(base, projectRoot);
+        if (!ensuredProject.ok)
+            return ensuredProject;
+        const checkoutOverride = input.checkoutOverride !== undefined
+            ? relativizeLocalPathForNetwork(cwd, input.checkoutOverride).path
+            : undefined;
         return httpStartRun(base, {
-            pipeline: resolveAbsolute(cwd, input.pipeline),
-            task: resolveAbsolute(cwd, input.task),
-            ...(input.checkoutOverride !== undefined
-                ? { checkoutOverride: resolveAbsolute(cwd, input.checkoutOverride) }
-                : {}),
+            pipeline: pipelineRef.path,
+            task,
+            project_root: ensuredProject.project_root,
+            ...(checkoutOverride !== undefined ? { checkoutOverride } : {}),
             ...(input.skipGates !== undefined ? { skipGates: input.skipGates } : {}),
             ...(input.gitSha !== undefined ? { gitSha: input.gitSha } : {}),
             ...(input.ciPrUrl !== undefined ? { ciPrUrl: input.ciPrUrl } : {}),
@@ -200,8 +265,15 @@ export async function runRunCommand(args, options = {}) {
     });
     const store = options.store ?? (parsed.includeStages ? httpStoreReader(base) : undefined);
     try {
+        const hasBindingOverride = parsed.repository !== undefined || parsed.ref !== undefined;
+        const taskInput = hasBindingOverride
+            ? await loadTaskWithBindingOverrides(parsed.task, cwd, {
+                repository: parsed.repository,
+                ref: parsed.ref,
+            })
+            : parsed.task;
         const started = await startRun({
-            task: parsed.task,
+            task: taskInput,
             pipeline: parsed.pipeline,
             checkoutOverride: parsed.checkout,
             ...(parsed.skipGates ? { skipGates: true } : {}),
@@ -210,6 +282,7 @@ export async function runRunCommand(args, options = {}) {
         if (!started.ok) {
             return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: out });
         }
+        writeQueuedAdmissionLine(started, out);
         return completeCliRun(started, out, {
             json: parsed.json,
             includeStages: parsed.includeStages,
@@ -226,6 +299,15 @@ export async function runRunCommand(args, options = {}) {
             }
             return exitCodeForValidation(err.result);
         }
+        if (err instanceof PipelinePreflightError) {
+            if (parsed.json) {
+                out.log(JSON.stringify(err.toNetworkBody(), null, 2));
+            }
+            else {
+                out.error(err.message);
+            }
+            return 1;
+        }
         out.error(err instanceof Error ? err.message : String(err));
         return 1;
     }

package/dist/cli/runOutput.d.ts

@@ -14,6 +14,10 @@ export type CliRunReportEvent = {
     kind: "completion";
     result: PipelineRunResult;
 };
+/** Stderr line when start_run was admitted to the queue (origin transparency rule). */
+export declare function writeQueuedAdmissionLine(started: Extract<StartRunResult, {
+    ok: true;
+}>, io: Pick<CliRunReportIo, "error">): void;
 export declare function reportCliRun(event: CliRunReportEvent, options: {
     json?: boolean;
     io: CliRunReportIo;

package/dist/cli/runOutput.js

@@ -20,6 +20,12 @@ async function tryReadTotalCostUsd(store, runId) {
 function isBusyCode(code) {
     return code === "busy_capacity" || code === "busy_checkout";
 }
+/** Stderr line when start_run was admitted to the queue (origin transparency rule). */
+export function writeQueuedAdmissionLine(started, io) {
+    if (started.queued === true && started.queuePosition !== undefined) {
+        io.error(`queued at position ${started.queuePosition}`);
+    }
+}
 function formatRunBusyJson(started) {
     const payload = {
         ok: false,
@@ -52,6 +58,13 @@ function formatRunStartFailedJson(started) {
     };
     if (started.code !== undefined)
         payload.code = started.code;
+    if (started.freeBytes !== undefined)
+        payload.freeBytes = started.freeBytes;
+    if (started.minFreeBytes !== undefined) {
+        payload.minFreeBytes = started.minFreeBytes;
+    }
+    if (started.stderr !== undefined)
+        payload.stderr = started.stderr;
     return stringify(payload);
 }
 function formatStartFailureJson(started) {
@@ -75,13 +88,21 @@ function baseRunCompletionPayload(result) {
                 runId: result.runId,
                 runDir: result.runDir,
             }
-            : {
-                ok: false,
-                outcome: "failed",
-                runId: result.runId,
-                runDir: result.runDir,
-            };
-    if (result.outcome === "failed" && result.reason !== undefined) {
+            : result.outcome === "cancelled"
+                ? {
+                    ok: false,
+                    outcome: "cancelled",
+                    runId: result.runId,
+                    runDir: result.runDir,
+                }
+                : {
+                    ok: false,
+                    outcome: "failed",
+                    runId: result.runId,
+                    runDir: result.runDir,
+                };
+    if ((result.outcome === "failed" || result.outcome === "cancelled") &&
+        result.reason !== undefined) {
         payload.reason = result.reason;
     }
     if (Array.isArray(result.findings) && result.findings.length > 0) {
@@ -130,6 +151,10 @@ function writeCompletionHuman(result, io, totalCostUsd) {
             io.error(`Pipeline failed: ${result.reason}`);
             io.error(`Run folder: ${result.runDir}`);
             break;
+        case "cancelled":
+            io.error(`Pipeline cancelled${result.reason ? `: ${result.reason}` : ""}`);
+            io.error(`Run folder: ${result.runDir}`);
+            break;
         case "succeeded":
             io.log(`Pipeline succeeded. Run folder: ${result.runDir}`);
             break;
@@ -145,6 +170,7 @@ function exitCodeForRunOutcome(outcome) {
         case "waiting":
             return 2;
         case "failed":
+        case "cancelled":
             return 1;
     }
 }

package/dist/cli/runStageCommand.d.ts

@@ -7,6 +7,7 @@ export type RunStageEnvelopeRef = {
 };
 export type RunStageToolArgs = {
     stage: string | Record<string, unknown>;
+    project_root?: string;
     task_path?: string;
     task?: Record<string, unknown>;
     envelope_ref?: RunStageEnvelopeRef | RunStageEnvelopeRef[];

package/dist/cli/runStageCommand.js

@@ -1,6 +1,7 @@
+import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
 import { PACKAGE_VERSION } from "../package-meta.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
-import { resolveAbsolute } from "./hostClient.js";
+import { httpEnsureProject } from "./hostClient.js";
 export const RUN_STAGE_USAGE = `Usage:
   sf run-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>] [--envelope-ref ...]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]
 
@@ -247,9 +248,17 @@ function defaultCallTool(base, ensureService) {
         if (!ensured.ok) {
             throw new Error(ensured.message);
         }
+        let toolArgs = args;
+        if (args.project_root !== undefined) {
+            const ensuredProject = await httpEnsureProject(base, args.project_root);
+            if (!ensuredProject.ok) {
+                throw new Error(ensuredProject.reason);
+            }
+            toolArgs = { ...args, project_root: ensuredProject.project_root };
+        }
         const sessionId = await mcpInitializeSession(base);
         try {
-            return await mcpToolCall(base, sessionId, "run_stage", args);
+            return await mcpToolCall(base, sessionId, "run_stage", toolArgs);
         }
         finally {
             await mcpCloseSession(base, sessionId);
@@ -338,37 +347,48 @@ export async function runRunStageCommand(args, options = {}) {
         return 1;
     }
     let stage;
-    if (parsed.stage !== undefined) {
-        stage = resolveAbsolute(cwd, parsed.stage);
-    }
-    else {
-        try {
-            stage = parseJsonFlag(parsed.stageInline, "--stage-inline");
+    let projectRoot;
+    try {
+        if (parsed.stage !== undefined) {
+            const stageRef = relativizeLocalPathForNetwork(cwd, parsed.stage);
+            stage = stageRef.path;
+            projectRoot = stageRef.project_root;
         }
-        catch (err) {
-            out.error(err instanceof Error ? err.message : String(err));
-            return 1;
+        else {
+            stage = parseJsonFlag(parsed.stageInline, "--stage-inline");
         }
     }
+    catch (err) {
+        out.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
     let taskPath;
     let task;
     let envelopeRef;
-    if (parsed.task !== undefined) {
-        taskPath = resolveAbsolute(cwd, parsed.task);
-    }
-    else if (parsed.taskInline !== undefined) {
-        try {
+    try {
+        if (parsed.task !== undefined) {
+            const taskRef = relativizeLocalPathForNetwork(cwd, parsed.task);
+            taskPath = taskRef.path;
+            projectRoot = taskRef.project_root;
+        }
+        else if (parsed.taskInline !== undefined) {
             task = parseJsonFlag(parsed.taskInline, "--task-inline");
         }
-        catch (err) {
-            out.error(err instanceof Error ? err.message : String(err));
-            return 1;
+        else {
+            const refs = parsed.envelopeRef.map(parseEnvelopeRefFlag);
+            envelopeRef = refs.length === 1 ? refs[0] : refs;
         }
     }
-    else {
+    catch (err) {
+        out.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    let checkout;
+    if (parsed.checkout !== undefined) {
         try {
-            const refs = parsed.envelopeRef.map(parseEnvelopeRefFlag);
-            envelopeRef = refs.length === 1 ? refs[0] : refs;
+            const checkoutRef = relativizeLocalPathForNetwork(cwd, parsed.checkout);
+            checkout = checkoutRef.path;
+            projectRoot = projectRoot ?? checkoutRef.project_root;
         }
         catch (err) {
             out.error(err instanceof Error ? err.message : String(err));
@@ -377,12 +397,11 @@ export async function runRunStageCommand(args, options = {}) {
     }
     const toolArgs = {
         stage,
+        ...(projectRoot !== undefined ? { project_root: projectRoot } : {}),
         ...(taskPath !== undefined ? { task_path: taskPath } : {}),
         ...(task !== undefined ? { task } : {}),
         ...(envelopeRef !== undefined ? { envelope_ref: envelopeRef } : {}),
-        ...(parsed.checkout !== undefined
-            ? { checkout: resolveAbsolute(cwd, parsed.checkout) }
-            : {}),
+        ...(checkout !== undefined ? { checkout } : {}),
         ...(parsed.model !== undefined ? { model: parsed.model } : {}),
         ...(parsed.blocking ? { blocking: true } : {}),
         ...(parsed.timeoutMs !== undefined ? { timeout_ms: parsed.timeoutMs } : {}),

package/dist/cli/runsCommand.d.ts

@@ -1,6 +1,6 @@
 import type { RunStore } from "../runstore/port.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
-export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs resume --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
+export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|queued|running|succeeded|failed|cancelled] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs resume --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs cancel --run <runId> --reason <text> [--json]\n  sf runs delete --run <runId> [--force] [--json]\n  sf runs gc [--dry-run] [--json]\n  sf runs rerun --run <runId> [--pinned] [--json]";
 export type RunsCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/runsCommand.js

@@ -4,16 +4,16 @@ import { projectRun } from "../projection/projectRun.js";
 import { waitRun } from "../mcp/waitRun.js";
 import { projectWaitingGates } from "../mcp/waitingGates.js";
 import { completeCliRun } from "./runCommand.js";
-import { reportCliRun } from "./runOutput.js";
+import { reportCliRun, writeQueuedAdmissionLine } from "./runOutput.js";
 import { globalStageflowHome } from "../project/globalHome.js";
-import { createRunStore } from "../runstore/createStore.js";
+import { createRunStore, storeNeedsHostMigration, } from "../runstore/createStore.js";
 import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
 import { mapRetryStageFailure } from "../server/operatorResults.js";
-import { httpAbandonStage, httpDecideFeedbackLoop, httpDeliverAnswer, httpRecoverManualStageUntilStop, httpRerun, httpResumeTimedOutStage, httpRetryStageUntilStop, httpStopManualRecovery, } from "./hostClient.js";
+import { httpAbandonStage, httpCancelRun, httpDecideFeedbackLoop, httpDeleteRun, httpDeliverAnswer, httpGcRuns, httpRecoverManualStageUntilStop, httpRerun, httpResumeTimedOutStage, httpRetryStageUntilStop, httpStopManualRecovery, } from "./hostClient.js";
 import { AskOperatorError, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 export const RUNS_USAGE = `Usage:
-  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
+  sf runs list [--status created|queued|running|succeeded|failed|cancelled] [--since <iso>] [--pipeline <id-or-path>] [--json]
   sf runs show --run <runId> [--from <sf-run.json>] [--json]
   sf runs verify --run <runId> --stage <stageId> [--json]
   sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]
@@ -24,16 +24,21 @@ export const RUNS_USAGE = `Usage:
   sf runs retry --run <runId> --stage <stageId> [--json]
   sf runs resume --run <runId> --stage <stageId> [--json]
   sf runs abandon --run <runId> --stage <stageId> [--json]
-  sf runs rerun --run <runId> [--json]`;
+  sf runs cancel --run <runId> --reason <text> [--json]
+  sf runs delete --run <runId> [--force] [--json]
+  sf runs gc [--dry-run] [--json]
+  sf runs rerun --run <runId> [--pinned] [--json]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
 };
 const RUN_STATUSES = [
     "created",
+    "queued",
     "running",
     "succeeded",
     "failed",
+    "cancelled",
 ];
 const LIST_FLAGS = new Set([
     "--status",
@@ -85,7 +90,10 @@ const FEEDBACK_DECIDE_FLAGS = new Set([
 ]);
 const RETRY_FLAGS = new Set(["--run", "--stage", "--json", "--help", "-h"]);
 const ABANDON_FLAGS = new Set(["--run", "--stage", "--json", "--help", "-h"]);
-const RERUN_FLAGS = new Set(["--run", "--json", "--help", "-h"]);
+const CANCEL_FLAGS = new Set(["--run", "--reason", "--json", "--help", "-h"]);
+const DELETE_FLAGS = new Set(["--run", "--force", "--json", "--help", "-h"]);
+const GC_FLAGS = new Set(["--dry-run", "--json", "--help", "-h"]);
+const RERUN_FLAGS = new Set(["--run", "--pinned", "--json", "--help", "-h"]);
 const VALUE_FLAGS = new Set([
     "--status",
     "--since",
@@ -125,6 +133,12 @@ function flagsFor(subcommand) {
             return RETRY_FLAGS;
         case "abandon":
             return ABANDON_FLAGS;
+        case "cancel":
+            return CANCEL_FLAGS;
+        case "delete":
+            return DELETE_FLAGS;
+        case "gc":
+            return GC_FLAGS;
         case "rerun":
             return RERUN_FLAGS;
         default:
@@ -156,6 +170,9 @@ function parseRunsArgs(args) {
     let answer;
     let guidance;
     let stop = false;
+    let pinned = false;
+    let force = false;
+    let dryRun = false;
     let loopId;
     let decision;
     let reason;
@@ -172,6 +189,21 @@ function parseRunsArgs(args) {
                 throw new Error(`Unknown flag: ${arg}`);
             stop = true;
         }
+        else if (arg === "--pinned") {
+            if (!allowed.has(arg))
+                throw new Error(`Unknown flag: ${arg}`);
+            pinned = true;
+        }
+        else if (arg === "--force") {
+            if (!allowed.has(arg))
+                throw new Error(`Unknown flag: ${arg}`);
+            force = true;
+        }
+        else if (arg === "--dry-run") {
+            if (!allowed.has(arg))
+                throw new Error(`Unknown flag: ${arg}`);
+            dryRun = true;
+        }
         else if (VALUE_FLAGS.has(arg)) {
             if (!allowed.has(arg)) {
                 throw new Error(`Unknown flag: ${arg}`);
@@ -229,6 +261,9 @@ function parseRunsArgs(args) {
         answer,
         guidance,
         stop,
+        pinned,
+        force,
+        dryRun,
         loopId,
         decision,
         reason,
@@ -287,8 +322,18 @@ const MUTATING_SUBCOMMANDS = new Set([
     "resume",
     "recover",
     "abandon",
+    "cancel",
+    "delete",
+    "gc",
     "rerun",
 ]);
+const READ_ONLY_SUBCOMMANDS = new Set([
+    "list",
+    "show",
+    "verify",
+    "waiting",
+    "wait",
+]);
 export async function runRunsCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const out = { ...defaultIo, ...options.io };
@@ -331,6 +376,21 @@ export async function runRunsCommand(args, options = {}) {
             return 1;
         }
     }
+    if (READ_ONLY_SUBCOMMANDS.has(parsed.subcommand) &&
+        resolvedStore === undefined) {
+        if (storeNeedsHostMigration(globalStageflowHome())) {
+            const ensured = await ensureService();
+            if (!ensured.ok) {
+                if (parsed.json) {
+                    printJson(out, { error: ensured.message, reason: ensured.reason });
+                }
+                else {
+                    out.error(ensured.message);
+                }
+                return 1;
+            }
+        }
+    }
     switch (parsed.subcommand) {
         case "list": {
             if (parsed.status === "waiting") {
@@ -338,7 +398,7 @@ export async function runRunsCommand(args, options = {}) {
                 return 1;
             }
             if (parsed.status !== undefined && !isRunStatus(parsed.status)) {
-                out.error("--status must be created, running, succeeded, or failed");
+                out.error("--status must be created, queued, running, succeeded, failed, or cancelled");
                 return 1;
             }
             if (parsed.since !== undefined && !Number.isFinite(Date.parse(parsed.since))) {
@@ -730,14 +790,108 @@ export async function runRunsCommand(args, options = {}) {
             }
             return 0;
         }
+        case "cancel": {
+            if (!parsed.runId || !parsed.reason) {
+                return usageError(out, "Missing --run and/or --reason");
+            }
+            const result = await httpCancelRun(base, parsed.runId, parsed.reason);
+            if (!result.ok) {
+                const payload = { error: result.reason };
+                if (result.status !== undefined)
+                    payload.status = result.status;
+                if (parsed.json) {
+                    printJson(out, payload);
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            if (parsed.json) {
+                printJson(out, {
+                    ok: true,
+                    runId: result.runId,
+                });
+            }
+            else {
+                out.log(result.runId);
+            }
+            return 0;
+        }
+        case "delete": {
+            if (!parsed.runId) {
+                return usageError(out, "Missing --run");
+            }
+            const result = await httpDeleteRun(base, parsed.runId, {
+                force: parsed.force === true,
+            });
+            if (!result.ok) {
+                const payload = { error: result.reason };
+                if (result.status !== undefined)
+                    payload.status = result.status;
+                if (parsed.json) {
+                    printJson(out, payload);
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            if (parsed.json) {
+                printJson(out, {
+                    ok: true,
+                    runId: result.runId,
+                });
+            }
+            else {
+                out.log(result.runId);
+            }
+            return 0;
+        }
+        case "gc": {
+            const execute = parsed.dryRun !== true;
+            const result = await httpGcRuns(base, { execute });
+            if (!result.ok) {
+                const payload = { error: result.reason };
+                if (result.status !== undefined)
+                    payload.status = result.status;
+                if (parsed.json) {
+                    printJson(out, payload);
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            const report = {
+                slimmed: result.slimmed,
+                purged: result.purged,
+                bareCachesEvicted: result.bareCachesEvicted,
+            };
+            if (parsed.json) {
+                printJson(out, report);
+            }
+            else {
+                out.log([
+                    `slimmed:\t${report.slimmed.length}`,
+                    ...report.slimmed.map((id) => `\t${id}`),
+                    `purged:\t${report.purged.length}`,
+                    ...report.purged.map((id) => `\t${id}`),
+                    `bareCachesEvicted:\t${report.bareCachesEvicted.length}`,
+                    ...report.bareCachesEvicted.map((id) => `\t${id}`),
+                ].join("\n"));
+            }
+            return 0;
+        }
         case "rerun": {
             if (!parsed.runId) {
                 return usageError(out, "Missing --run");
             }
-            const started = await httpRerun(base, parsed.runId);
+            const started = await httpRerun(base, parsed.runId, parsed.pinned ? { pinned: true } : undefined);
             if (!started.ok) {
                 return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: mutatingIo });
             }
+            writeQueuedAdmissionLine(started, mutatingIo);
             return completeCliRun(started, mutatingIo, {
                 json: parsed.json,
                 store: getStore(),