voratiq 0.1.0-beta.5 → 0.1.0-beta.6

package/README.md

@@ -2,7 +2,7 @@
 
 Run agents in parallel, compare results, and apply the best solution.
 
-![`voratiq run --spec specs/p1/agent-workspace-guardrails.md`](https://raw.githubusercontent.com/voratiq/voratiq/main/assets/run-demo.png)
+![`voratiq run --spec .voratiq/specs/apply-commit-flag.md`](https://raw.githubusercontent.com/voratiq/voratiq/main/assets/run-demo.png)
 
 ## Installation
 
@@ -18,7 +18,7 @@ Core:
 
 - Node 20+
 - git
-- 1+ AI coding agent (Claude [(>=2.0.55)](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [(>=0.66.0)](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [(>=0.19.4)](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install))
+- 1+ AI coding agent (Claude [>=2.0.55](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [>=0.66.0](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [>=0.19.4](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install))
 
 Platform-specific:
 
@@ -36,7 +36,10 @@ Note: Windows is not currently supported.
 voratiq init
 
 # Generate a spec
-voratiq spec --description "add dark mode toggle with localStorage persistence" --agent <agent-id> --yes
+voratiq spec \
+  --description "add dark mode toggle with localStorage persistence" \
+  --agent <agent-id> \
+  --yes
 
 # Run agents in parallel
 voratiq run --spec .voratiq/specs/add-dark-mode-toggle.md
@@ -48,7 +51,9 @@ voratiq review --run <run-id> --agent <agent-id>
 voratiq apply --run <run-id> --agent <agent-id>
 ```
 
-See the [docs](https://github.com/voratiq/voratiq/blob/main/docs/index.md) for core concepts, CLI reference, and guides on configuring agents, evals, runtime environments, and sandbox restrictions.
+For a full walkthrough, see the [CLI tutorial](https://github.com/voratiq/voratiq/blob/main/docs/tutorial.md).
+
+See the [docs](https://github.com/voratiq/voratiq/blob/main/docs/index.md) for core concepts, CLI reference, and configuration guides.
 
 ## License
 

package/dist/cli/apply.d.ts

@@ -4,6 +4,7 @@ export interface ApplyCommandOptions {
     runId: string;
     agentId: string;
     ignoreBaseMismatch?: boolean;
+    commit?: boolean;
 }
 export interface ApplyCommandResult {
     result: ApplyResult;

package/dist/cli/apply.js

@@ -4,7 +4,7 @@ import { ensureCleanWorkingTree, resolveCliContext, } from "../preflight/index.j
 import { renderApplyTranscript } from "../render/transcripts/apply.js";
 import { writeCommandOutput } from "./output.js";
 export async function runApplyCommand(options) {
-    const { runId, agentId, ignoreBaseMismatch = false } = options;
+    const { runId, agentId, ignoreBaseMismatch = false, commit = false, } = options;
     const { root, workspacePaths } = await resolveCliContext();
     await ensureCleanWorkingTree(root);
     const result = await executeApplyCommand({
@@ -13,6 +13,7 @@ export async function runApplyCommand(options) {
         runId,
         agentId,
         ignoreBaseMismatch,
+        commit,
     });
     const body = renderApplyTranscript(result);
     return { result, body };
@@ -23,12 +24,14 @@ export function createApplyCommand() {
         .requiredOption("--run <run-id>", "Identifier of the recorded run")
         .requiredOption("--agent <agent-id>", "Agent id to apply from the run")
         .option("--ignore-base-mismatch", "Apply even if the current HEAD differs from the recorded base", () => true)
+        .option("--commit", "Commit the applied diff immediately using the agent summary", () => true)
         .allowExcessArguments(false)
         .action(async (options) => {
         const result = await runApplyCommand({
             runId: options.run,
             agentId: options.agent,
             ignoreBaseMismatch: options.ignoreBaseMismatch ?? false,
+            commit: options.commit ?? false,
         });
         writeCommandOutput({
             body: result.body,

package/dist/cli/prune.d.ts

@@ -1,12 +1,13 @@
 import { Command } from "commander";
-import type { PruneResult } from "../commands/prune/types.js";
+import type { PruneAllResult, PruneResult } from "../commands/prune/types.js";
 export interface PruneCommandOptions {
-    runId: string;
+    runId?: string;
+    all?: boolean;
     purge?: boolean;
     yes?: boolean;
 }
 export interface PruneCommandResult {
-    result: PruneResult;
+    result: PruneResult | PruneAllResult;
     body: string;
     exitCode?: number;
 }

package/dist/cli/prune.js

@@ -1,12 +1,13 @@
-import { Command } from "commander";
-import { executePruneCommand } from "../commands/prune/command.js";
+import { Command, Option } from "commander";
+import { executePruneAllCommand, executePruneCommand, } from "../commands/prune/command.js";
 import { resolveCliContext } from "../preflight/index.js";
-import { renderPruneTranscript } from "../render/transcripts/prune.js";
+import { renderPruneAllTranscript, renderPruneTranscript, } from "../render/transcripts/prune.js";
 import { createConfirmationWorkflow } from "./confirmation.js";
 import { NonInteractiveShellError } from "./errors.js";
 import { writeCommandOutput } from "./output.js";
 export async function runPruneCommand(options) {
     const { runId } = options;
+    const all = Boolean(options.all);
     const purge = Boolean(options.purge);
     const assumeYes = Boolean(options.yes);
     const { root, workspacePaths } = await resolveCliContext();
@@ -17,6 +18,20 @@ export async function runPruneCommand(options) {
         },
     });
     try {
+        if (all) {
+            const result = await executePruneAllCommand({
+                root,
+                runsDir: workspacePaths.runsDir,
+                runsFilePath: workspacePaths.runsFile,
+                confirm: confirmation.confirm,
+                purge,
+            });
+            const body = renderPruneAllTranscript(result);
+            return { result, body };
+        }
+        if (!runId) {
+            throw new Error("Expected --run <run-id> when --all is not set.");
+        }
         const result = await executePruneCommand({
             root,
             runsDir: workspacePaths.runsDir,
@@ -35,14 +50,23 @@ export async function runPruneCommand(options) {
 export function createPruneCommand() {
     return new Command("prune")
         .description("Remove artifacts for a recorded run")
-        .requiredOption("--run <run-id>", "Identifier of the run to delete")
+        .addOption(new Option("--run <run-id>", "Identifier of the run to delete").conflicts("all"))
+        .addOption(new Option("--all", "Prune all non-pruned runs").conflicts("run"))
         .option("--purge", "Delete all associated configs and artifacts")
         .option("-y, --yes", "Assume yes for all prompts")
         .addHelpText("after", "\nThis command removes agent workspaces, deletes agent branches, and marks runs as pruned. \nPass --purge to also delete all associated configs and artifacts.")
         .allowExcessArguments(false)
-        .action(async (options) => {
+        .action(async (options, command) => {
+        const hasRun = typeof options.run === "string" && options.run.length > 0;
+        const wantsAll = Boolean(options.all);
+        if (!hasRun && !wantsAll) {
+            command.error("error: either --run <run-id> or --all must be provided", {
+                exitCode: 1,
+            });
+        }
         const result = await runPruneCommand({
             runId: options.run,
+            all: wantsAll,
             purge: Boolean(options.purge),
             yes: Boolean(options.yes),
         });

package/dist/cli/run.d.ts

@@ -3,6 +3,7 @@ import type { RunReport } from "../runs/records/types.js";
 export interface RunCommandOptions {
     specPath: string;
     maxParallel?: number;
+    branch?: boolean;
 }
 export interface RunCommandResult {
     report: RunReport;
@@ -10,4 +11,13 @@ export interface RunCommandResult {
     exitCode?: number;
 }
 export declare function runRunCommand(options: RunCommandOptions): Promise<RunCommandResult>;
+/**
+ * Derives a branch name from a spec file path by extracting the basename without extension.
+ *
+ * Examples:
+ * - `specs/separate-eval-outcomes.md` → `separate-eval-outcomes`
+ * - `specs/foo/bar.md` → `bar`
+ * - `my-feature.md` → `my-feature`
+ */
+export declare function deriveBranchNameFromSpecPath(specPath: string): string;
 export declare function createRunCommand(): Command;

package/dist/cli/run.js

@@ -1,17 +1,23 @@
+import { basename } from "node:path";
 import { Command } from "commander";
 import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
 import { executeRunCommand } from "../commands/run/command.js";
+import { checkoutOrCreateBranch } from "../preflight/branch.js";
 import { ensureCleanWorkingTree, ensureSandboxDependencies, ensureSpecPath, resolveCliContext, } from "../preflight/index.js";
 import { createRunRenderer } from "../render/transcripts/run.js";
 import { parsePositiveInteger } from "../utils/validators.js";
 import { writeCommandOutput } from "./output.js";
 export async function runRunCommand(options) {
-    const { specPath, maxParallel } = options;
+    const { specPath, maxParallel, branch } = options;
     const { root, workspacePaths } = await resolveCliContext();
     checkPlatformSupport();
     ensureSandboxDependencies();
     await ensureCleanWorkingTree(root);
     const { absolutePath, displayPath } = await ensureSpecPath(specPath, root);
+    if (branch) {
+        const branchName = deriveBranchNameFromSpecPath(displayPath);
+        await checkoutOrCreateBranch(root, branchName);
+    }
     const renderer = createRunRenderer();
     const report = await executeRunCommand({
         root,
@@ -23,11 +29,28 @@ export async function runRunCommand(options) {
     });
     const body = renderer.complete(report);
     // Unlike other commands, `run` signals a degraded outcome via exit code 1
-    // when any agent or eval fails. All other CLI commands either throw on error
+    // when any agent fails. Eval failures are quality signals displayed in the output
+    // but do not affect exit code. All other CLI commands either throw on error
     // or return a clean success with exit code 0, so keep this deviation explicit.
-    const exitCode = report.hadAgentFailure || report.hadEvalFailure ? 1 : undefined;
+    const exitCode = report.hadAgentFailure ? 1 : undefined;
     return { report, body, exitCode };
 }
+/**
+ * Derives a branch name from a spec file path by extracting the basename without extension.
+ *
+ * Examples:
+ * - `specs/separate-eval-outcomes.md` → `separate-eval-outcomes`
+ * - `specs/foo/bar.md` → `bar`
+ * - `my-feature.md` → `my-feature`
+ */
+export function deriveBranchNameFromSpecPath(specPath) {
+    const base = basename(specPath);
+    const lastDotIndex = base.lastIndexOf(".");
+    if (lastDotIndex <= 0) {
+        return base;
+    }
+    return base.slice(0, lastDotIndex);
+}
 function parseMaxParallelOption(value) {
     return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
 }
@@ -36,11 +59,13 @@ export function createRunCommand() {
         .description("Execute configured agents against a spec")
         .requiredOption("--spec <path>", "Path to the specification to execute")
         .option("--max-parallel <count>", "Maximum number of agents to run concurrently", parseMaxParallelOption)
+        .option("--branch", "Checkout or create a branch named after the spec file")
         .allowExcessArguments(false)
         .action(async (options) => {
         const runOptions = {
             specPath: options.spec,
             maxParallel: options.maxParallel,
+            branch: options.branch,
         };
         const result = await runRunCommand(runOptions);
         writeCommandOutput({

package/dist/commands/apply/command.d.ts

@@ -5,5 +5,6 @@ export interface ApplyCommandInput {
     runId: string;
     agentId: string;
     ignoreBaseMismatch: boolean;
+    commit?: boolean;
 }
 export declare function executeApplyCommand(input: ApplyCommandInput): Promise<ApplyResult>;

package/dist/commands/apply/command.js

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { buildRunRecordEnhanced } from "../../runs/records/enhanced.js";
 import { rewriteRunRecord } from "../../runs/records/persistence.js";
 import { toErrorMessage } from "../../utils/errors.js";
@@ -5,9 +6,9 @@ import { ensureFileExists } from "../../utils/fs.js";
 import { getGitStderr, getHeadRevision, runGitCommand, } from "../../utils/git.js";
 import { resolveDisplayPath } from "../../utils/path.js";
 import { fetchRunSafely } from "../fetch.js";
-import { ApplyAgentDiffMissingOnDiskError, ApplyAgentDiffNotRecordedError, ApplyAgentNotFoundError, ApplyBaseMismatchError, ApplyPatchApplicationError, ApplyRunDeletedError, } from "./errors.js";
+import { ApplyAgentDiffMissingOnDiskError, ApplyAgentDiffNotRecordedError, ApplyAgentNotFoundError, ApplyAgentSummaryEmptyError, ApplyAgentSummaryMissingOnDiskError, ApplyAgentSummaryNotRecordedError, ApplyBaseMismatchError, ApplyGitCommitError, ApplyPatchApplicationError, ApplyRunDeletedError, } from "./errors.js";
 export async function executeApplyCommand(input) {
-    const { root, runsFilePath, runId, agentId, ignoreBaseMismatch } = input;
+    const { root, runsFilePath, runId, agentId, ignoreBaseMismatch, commit = false, } = input;
     const runRecord = await fetchRunSafely({
         root,
         runsFilePath,
@@ -30,6 +31,8 @@ export async function executeApplyCommand(input) {
     }
     const diffAbsolutePath = resolveDisplayPath(root, diffDisplayPath) ?? diffDisplayPath;
     await ensureFileExists(diffAbsolutePath, () => new ApplyAgentDiffMissingOnDiskError(diffDisplayPath));
+    const summaryRecorded = agentRecord.artifacts?.summaryCaptured ?? false;
+    const summaryDisplayPath = enhancedAgent.assets.summaryPath;
     const headRevision = await getHeadRevision(root);
     const baseRevisionSha = runRecord.baseRevisionSha;
     const baseMismatch = headRevision !== baseRevisionSha;
@@ -63,6 +66,30 @@ export async function executeApplyCommand(input) {
         }
         throw error;
     }
+    let appliedCommitSha;
+    if (commit) {
+        try {
+            appliedCommitSha = await commitAppliedDiff({
+                root,
+                runId,
+                agentId,
+                summaryRecorded,
+                summaryDisplayPath,
+            });
+        }
+        catch (error) {
+            await recordApplyStatus({
+                root,
+                runsFilePath,
+                runId,
+                agentId,
+                ignoredBaseMismatch,
+                status: "failed",
+                detail: extractCommitFailureDetail(error),
+            });
+            throw error;
+        }
+    }
     await recordApplyStatus({
         root,
         runsFilePath,
@@ -70,6 +97,7 @@ export async function executeApplyCommand(input) {
         agentId,
         ignoredBaseMismatch,
         status: "succeeded",
+        appliedCommitSha,
     });
     return {
         runId: runRecord.runId,
@@ -81,6 +109,7 @@ export async function executeApplyCommand(input) {
         agent: agentRecord,
         diffPath: diffDisplayPath,
         ignoredBaseMismatch,
+        ...(appliedCommitSha ? { appliedCommitSha } : {}),
     };
 }
 async function applyPatch(options) {
@@ -96,7 +125,7 @@ async function applyPatch(options) {
     }
 }
 async function recordApplyStatus(options) {
-    const { root, runsFilePath, runId, agentId, status, ignoredBaseMismatch, detail, } = options;
+    const { root, runsFilePath, runId, agentId, status, ignoredBaseMismatch, appliedCommitSha, detail, } = options;
     const appliedAt = new Date().toISOString();
     const normalizedDetail = typeof detail === "string" && detail.length > 0
         ? truncateDetail(detail)
@@ -115,6 +144,9 @@ async function recordApplyStatus(options) {
             if (normalizedDetail !== undefined) {
                 applyStatus.detail = normalizedDetail;
             }
+            if (typeof appliedCommitSha === "string" && appliedCommitSha.length > 0) {
+                applyStatus.appliedCommitSha = appliedCommitSha;
+            }
             return {
                 ...record,
                 applyStatus,
@@ -129,7 +161,44 @@ function extractApplyFailureDetail(error) {
     }
     return error.message;
 }
+function extractCommitFailureDetail(error) {
+    const stderr = getGitStderr(error);
+    if (stderr && stderr.trim().length > 0) {
+        const [firstLine] = stderr.split(/\r?\n/);
+        if (firstLine && firstLine.trim().length > 0) {
+            return firstLine.trim();
+        }
+        return stderr.trim();
+    }
+    return toErrorMessage(error);
+}
 function truncateDetail(detail) {
     const trimmed = detail.trim();
     return trimmed.length > 256 ? trimmed.slice(0, 256) : trimmed;
 }
+async function commitAppliedDiff(options) {
+    const { root, runId, agentId, summaryRecorded, summaryDisplayPath } = options;
+    if (!summaryRecorded || !summaryDisplayPath) {
+        throw new ApplyAgentSummaryNotRecordedError(runId, agentId);
+    }
+    const summaryAbsolutePath = resolveDisplayPath(root, summaryDisplayPath) ?? summaryDisplayPath;
+    await ensureFileExists(summaryAbsolutePath, () => new ApplyAgentSummaryMissingOnDiskError(summaryDisplayPath));
+    const rawSummary = await readFile(summaryAbsolutePath, "utf8");
+    const commitSubject = normalizeCommitSubject(rawSummary);
+    if (!commitSubject) {
+        throw new ApplyAgentSummaryEmptyError(summaryDisplayPath);
+    }
+    try {
+        await runGitCommand(["add", "-A"], { cwd: root });
+        await runGitCommand(["commit", "-m", commitSubject], { cwd: root });
+        return await runGitCommand(["rev-parse", "HEAD"], { cwd: root });
+    }
+    catch (error) {
+        const detail = getGitStderr(error) ?? toErrorMessage(error);
+        throw new ApplyGitCommitError(detail);
+    }
+}
+function normalizeCommitSubject(summary) {
+    const normalized = summary.trim().replace(/\s+/gu, " ");
+    return normalized.length > 0 ? normalized : "";
+}

package/dist/commands/apply/errors.d.ts

@@ -23,6 +23,22 @@ export declare class ApplyAgentDiffMissingOnDiskError extends ApplyError {
     readonly diffPath: string;
     constructor(diffPath: string);
 }
+export declare class ApplyAgentSummaryNotRecordedError extends ApplyError {
+    readonly runId: string;
+    readonly agentId: string;
+    constructor(runId: string, agentId: string);
+}
+export declare class ApplyAgentSummaryMissingOnDiskError extends ApplyError {
+    readonly summaryPath: string;
+    constructor(summaryPath: string);
+}
+export declare class ApplyAgentSummaryEmptyError extends ApplyError {
+    readonly summaryPath: string;
+    constructor(summaryPath: string);
+}
+export declare class ApplyGitCommitError extends ApplyError {
+    constructor(detail: string);
+}
 export interface ApplyBaseMismatchOptions {
     baseRevisionSha: string;
     headRevision: string;

package/dist/commands/apply/errors.js

@@ -53,6 +53,42 @@ export class ApplyAgentDiffMissingOnDiskError extends ApplyError {
         this.name = "ApplyAgentDiffMissingOnDiskError";
     }
 }
+export class ApplyAgentSummaryNotRecordedError extends ApplyError {
+    runId;
+    agentId;
+    constructor(runId, agentId) {
+        super(`Agent ${agentId} did not record a summary for run ${runId}.`, ["A summary artifact is required for `voratiq apply --commit`."], [
+            "Re-run the spec to regenerate artifacts or apply without `--commit` and commit manually.",
+        ]);
+        this.runId = runId;
+        this.agentId = agentId;
+        this.name = "ApplyAgentSummaryNotRecordedError";
+    }
+}
+export class ApplyAgentSummaryMissingOnDiskError extends ApplyError {
+    summaryPath;
+    constructor(summaryPath) {
+        super("Recorded summary is missing from disk.", [`Expected summary at ${summaryPath} but it was not found.`], ["Ensure the run directory still exists or re-run the agents."]);
+        this.summaryPath = summaryPath;
+        this.name = "ApplyAgentSummaryMissingOnDiskError";
+    }
+}
+export class ApplyAgentSummaryEmptyError extends ApplyError {
+    summaryPath;
+    constructor(summaryPath) {
+        super("Recorded summary is empty.", [`Expected summary at ${summaryPath} to contain a commit subject.`], [
+            "Re-run the spec to regenerate artifacts or apply without `--commit` and commit manually.",
+        ]);
+        this.summaryPath = summaryPath;
+        this.name = "ApplyAgentSummaryEmptyError";
+    }
+}
+export class ApplyGitCommitError extends ApplyError {
+    constructor(detail) {
+        super("Failed to create git commit.", [detail], ["The diff remains applied; resolve the issue and commit manually."]);
+        this.name = "ApplyGitCommitError";
+    }
+}
 export class ApplyBaseMismatchError extends ApplyError {
     constructor(options) {
         const { baseRevisionSha, headRevision } = options;

package/dist/commands/apply/types.d.ts

@@ -10,4 +10,5 @@ export interface ApplyResult {
     agent: AgentInvocationRecord;
     diffPath: string;
     ignoredBaseMismatch: boolean;
+    appliedCommitSha?: string;
 }

package/dist/commands/prune/command.d.ts

@@ -1,2 +1,3 @@
-import type { PruneCommandInput, PruneResult } from "./types.js";
+import type { PruneAllCommandInput, PruneAllResult, PruneCommandInput, PruneResult } from "./types.js";
 export declare function executePruneCommand(input: PruneCommandInput): Promise<PruneResult>;
+export declare function executePruneAllCommand(input: PruneAllCommandInput): Promise<PruneAllResult>;

package/dist/commands/prune/command.js

@@ -1,8 +1,8 @@
 import * as fs from "node:fs/promises";
 import { NonInteractiveShellError } from "../../cli/errors.js";
-import { buildPruneConfirmationPreface } from "../../render/transcripts/prune.js";
+import { buildPruneAllConfirmationPreface, buildPruneConfirmationPreface, } from "../../render/transcripts/prune.js";
 import { RunRecordNotFoundError, RunRecordParseError, } from "../../runs/records/errors.js";
-import { rewriteRunRecord, RUN_RECORD_FILENAME, } from "../../runs/records/persistence.js";
+import { fetchRunsSafely, rewriteRunRecord, RUN_RECORD_FILENAME, } from "../../runs/records/persistence.js";
 import { toErrorMessage } from "../../utils/errors.js";
 import { pathExists } from "../../utils/fs.js";
 import { getGitStderr, runGitCommand } from "../../utils/git.js";
@@ -103,6 +103,52 @@ export async function executePruneCommand(input) {
         branches: branchSummary,
     };
 }
+export async function executePruneAllCommand(input) {
+    const { root, runsFilePath, confirm, clock, purge: purgeInput } = input;
+    const purge = purgeInput ?? false;
+    if (!confirm) {
+        throw new NonInteractiveShellError();
+    }
+    if (!(await pathExists(runsFilePath))) {
+        return { status: "noop", runIds: [] };
+    }
+    const { records, warnings } = await fetchRunsSafely({
+        root,
+        runsFilePath,
+    });
+    const firstWarning = warnings[0];
+    if (firstWarning) {
+        if (firstWarning.kind === "parse-error") {
+            throw new RunRecordParseError(firstWarning.displayPath, firstWarning.details);
+        }
+        throw new RunMetadataMissingError(firstWarning.runId);
+    }
+    if (records.length === 0) {
+        return { status: "noop", runIds: [] };
+    }
+    const eligibleRuns = sortRunRecordsByCreatedAt(records);
+    const runIds = eligibleRuns.map((record) => record.runId);
+    const confirmationAccepted = await confirm({
+        message: "Proceed?",
+        defaultValue: false,
+        prefaceLines: buildPruneAllConfirmationPreface({
+            records: eligibleRuns,
+        }),
+    });
+    if (!confirmationAccepted) {
+        return { status: "aborted", runIds };
+    }
+    for (const runId of runIds) {
+        await executePruneCommand({
+            ...input,
+            runId,
+            confirm: () => Promise.resolve(true),
+            purge,
+            clock,
+        });
+    }
+    return { status: "pruned", runIds };
+}
 function buildAgentDirectoryDisplayPaths(options) {
     const { runRecord } = options;
     const unique = new Set();
@@ -311,6 +357,16 @@ async function branchExists(root, branch) {
     });
     return output.length > 0;
 }
+function sortRunRecordsByCreatedAt(records) {
+    return Array.from(records).sort((a, b) => {
+        const aTimestamp = Date.parse(a.createdAt);
+        const bTimestamp = Date.parse(b.createdAt);
+        if (Number.isNaN(aTimestamp) || Number.isNaN(bTimestamp)) {
+            return a.createdAt.localeCompare(b.createdAt);
+        }
+        return aTimestamp - bTimestamp;
+    });
+}
 async function rewriteHistory(options) {
     const { root, runsFilePath, runId, deletedAt } = options;
     try {

package/dist/commands/prune/types.d.ts

@@ -9,6 +9,14 @@ export interface PruneCommandInput {
     purge?: boolean;
     clock?: () => Date;
 }
+export interface PruneAllCommandInput {
+    root: string;
+    runsDir: string;
+    runsFilePath: string;
+    confirm: PruneConfirmationHandler;
+    purge?: boolean;
+    clock?: () => Date;
+}
 export interface PruneBranchSummary {
     deleted: string[];
     skipped: string[];
@@ -40,3 +48,16 @@ export interface PruneAbortedResult {
     runPath: string;
 }
 export type PruneResult = PruneSuccessResult | PruneAbortedResult;
+export interface PruneAllSuccessResult {
+    status: "pruned";
+    runIds: string[];
+}
+export interface PruneAllNoopResult {
+    status: "noop";
+    runIds: string[];
+}
+export interface PruneAllAbortedResult {
+    status: "aborted";
+    runIds: string[];
+}
+export type PruneAllResult = PruneAllSuccessResult | PruneAllNoopResult | PruneAllAbortedResult;

package/dist/commands/run/agents/run-context.js

@@ -83,26 +83,9 @@ export class AgentRunContext {
             const evaluation = bySlug.get(fallback.slug);
             return evaluation ?? fallback;
         });
-        if (this.status === "failed") {
-            return;
-        }
-        const hasErrored = this.evalResults.some((evaluation) => {
-            return evaluation.status === "errored";
-        });
-        const hasFailed = this.evalResults.some((evaluation) => evaluation.status === "failed");
-        if (hasErrored) {
-            this.status = "errored";
-            if (!this.errorMessage) {
-                const erroredEval = this.evalResults.find((evaluation) => evaluation.status === "errored" && evaluation.error);
-                if (erroredEval?.error) {
-                    this.errorMessage = erroredEval.error;
-                }
-            }
-            return;
-        }
-        if (hasFailed) {
-            this.status = "failed";
-        }
+        // Evals are quality signals, not execution outcomes.
+        // Agent status depends only on execution results (process exit code, etc.),
+        // not on eval failures. Eval results are tracked and exposed separately.
     }
     markChatArtifact(format) {
         this.artifactState.chatCaptured = true;

package/dist/commands/run/command.js

@@ -90,7 +90,7 @@ export async function executeRunCommand(input) {
             mutators,
         });
         agentRecords = executionResult.agentRecords;
-        const derivedRunStatus = executionResult.hadAgentFailure || executionResult.hadEvalFailure
+        const derivedRunStatus = executionResult.hadAgentFailure
             ? "failed"
             : executionResult.agentReports.some((report) => report.status === "errored")
                 ? "errored"

package/dist/commands/run/lifecycle.d.ts

@@ -1,4 +1,5 @@
 import type { RunStatus } from "../../status/index.js";
+import { TERMINABLE_RUN_STATUSES } from "../../status/index.js";
 export declare const RUN_ABORT_WARNING = "Run aborted before agent completed.";
 interface ActiveRunContext {
     root: string;
@@ -11,9 +12,8 @@ interface ActiveRunAgentContext {
     providerId?: string;
     agentRoot: string;
 }
-declare const TERMINABLE_STATUSES: readonly ["failed", "aborted"];
 export declare function registerActiveRun(context: ActiveRunContext): void;
 export declare function clearActiveRun(runId: string): void;
 export declare function getActiveTerminationStatus(runId: string): RunStatus | undefined;
-export declare function terminateActiveRun(status: Extract<RunStatus, (typeof TERMINABLE_STATUSES)[number]>): Promise<void>;
+export declare function terminateActiveRun(status: Extract<RunStatus, (typeof TERMINABLE_RUN_STATUSES)[number]>): Promise<void>;
 export {};

package/dist/commands/run/lifecycle.js

@@ -1,12 +1,12 @@
 import { teardownSessionAuth } from "../../agents/runtime/registry.js";
 import { disposeRunRecordBuffer, getRunRecordSnapshot, rewriteRunRecord, } from "../../runs/records/persistence.js";
+import { TERMINABLE_RUN_STATUSES } from "../../status/index.js";
 import { toErrorMessage } from "../../utils/errors.js";
 import { preserveProviderChatTranscripts } from "../../workspace/chat/artifacts.js";
 export const RUN_ABORT_WARNING = "Run aborted before agent completed.";
 let activeRun;
 let terminationInFlight = false;
 let activeTerminationStatus;
-const TERMINABLE_STATUSES = ["failed", "aborted"];
 export function registerActiveRun(context) {
     activeRun = context;
 }
@@ -28,7 +28,7 @@ export function getActiveTerminationStatus(runId) {
     return activeTerminationStatus;
 }
 export async function terminateActiveRun(status) {
-    if (!TERMINABLE_STATUSES.includes(status)) {
+    if (!TERMINABLE_RUN_STATUSES.includes(status)) {
         return;
     }
     if (!activeRun || terminationInFlight) {

package/dist/preflight/branch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks out an existing branch or creates a new one from HEAD.
+ *
+ * - If the branch exists, switches to it (`git checkout`)
+ * - If the branch does not exist, creates it from HEAD (`git checkout -b`)
+ *
+ * @throws {BranchCheckoutError} If git checkout or branch creation fails
+ */
+export declare function checkoutOrCreateBranch(root: string, branchName: string): Promise<void>;

package/dist/preflight/branch.js

@@ -0,0 +1,48 @@
+import { getGitStderr, runGitCommand } from "../utils/git.js";
+import { BranchCheckoutError } from "./errors.js";
+/**
+ * Checks out an existing branch or creates a new one from HEAD.
+ *
+ * - If the branch exists, switches to it (`git checkout`)
+ * - If the branch does not exist, creates it from HEAD (`git checkout -b`)
+ *
+ * @throws {BranchCheckoutError} If git checkout or branch creation fails
+ */
+export async function checkoutOrCreateBranch(root, branchName) {
+    const branchExists = await doesBranchExist(root, branchName);
+    if (branchExists) {
+        await checkoutBranch(root, branchName);
+    }
+    else {
+        await createAndCheckoutBranch(root, branchName);
+    }
+}
+async function doesBranchExist(root, branchName) {
+    try {
+        await runGitCommand(["rev-parse", "--verify", `refs/heads/${branchName}`], {
+            cwd: root,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkoutBranch(root, branchName) {
+    try {
+        await runGitCommand(["checkout", branchName], { cwd: root });
+    }
+    catch (error) {
+        const stderr = getGitStderr(error);
+        throw new BranchCheckoutError(`Failed to checkout branch '${branchName}'`, stderr);
+    }
+}
+async function createAndCheckoutBranch(root, branchName) {
+    try {
+        await runGitCommand(["checkout", "-b", branchName], { cwd: root });
+    }
+    catch (error) {
+        const stderr = getGitStderr(error);
+        throw new BranchCheckoutError(`Failed to create branch '${branchName}'`, stderr);
+    }
+}

package/dist/preflight/errors.d.ts

@@ -8,3 +8,6 @@ export declare class DirtyWorkingTreeError extends CliError {
 export declare class SandboxDependenciesError extends CliError {
     constructor(missing: string);
 }
+export declare class BranchCheckoutError extends CliError {
+    constructor(message: string, gitError?: string);
+}

package/dist/preflight/errors.js

@@ -19,3 +19,10 @@ export class SandboxDependenciesError extends CliError {
         this.name = "SandboxDependenciesError";
     }
 }
+export class BranchCheckoutError extends CliError {
+    constructor(message, gitError) {
+        const detailLines = gitError ? [gitError] : [];
+        super(message, detailLines);
+        this.name = "BranchCheckoutError";
+    }
+}

package/dist/render/transcripts/apply.js

@@ -33,6 +33,10 @@ export function renderApplyTranscript(result) {
             `${colorize("Warning:", "yellow")} Applied despite base mismatch (\`--ignore-base-mismatch\`).`,
         ]
         : undefined;
+    const applyMessage = result.appliedCommitSha
+        ? `Diff applied to working tree (commit: ${result.appliedCommitSha}).`
+        : "Diff applied to working tree.";
+    const afterAgentsLines = [colorize(applyMessage, "green")];
     return renderTranscriptWithMetadata({
         metadata: {
             runId: result.runId,
@@ -44,9 +48,11 @@ export function renderApplyTranscript(result) {
         },
         agents: [agentDisplay],
         warnings,
-        afterAgents: [[colorize("Diff applied to working tree.", "green")]],
+        afterAgents: [afterAgentsLines],
         hint: {
-            message: "Review changes (e.g., `git status`) and run tests before committing.",
+            message: result.appliedCommitSha
+                ? "Review the commit (e.g., `git show --stat`) and run tests."
+                : "Review changes (e.g., `git status`) and run tests before committing.",
         },
     });
 }

package/dist/render/transcripts/prune.d.ts

@@ -1,4 +1,5 @@
-import type { PruneResult } from "../../commands/prune/types.js";
+import type { PruneAllResult, PruneResult } from "../../commands/prune/types.js";
+import type { RunRecord } from "../../runs/records/types.js";
 import type { RunStatus } from "../../status/index.js";
 export interface PruneConfirmationPrefaceOptions {
     runId: string;
@@ -13,4 +14,9 @@ export interface PruneConfirmationPrefaceOptions {
     previouslyDeletedAt?: string;
 }
 export declare function buildPruneConfirmationPreface(options: PruneConfirmationPrefaceOptions): string[];
+export interface PruneAllConfirmationPrefaceOptions {
+    records: readonly RunRecord[];
+}
+export declare function buildPruneAllConfirmationPreface(options: PruneAllConfirmationPrefaceOptions): string[];
 export declare function renderPruneTranscript(result: PruneResult): string;
+export declare function renderPruneAllTranscript(result: PruneAllResult): string;

package/dist/render/transcripts/prune.js

@@ -2,6 +2,7 @@ import { colorize } from "../../utils/colors.js";
 import { formatRunTimestamp } from "../utils/records.js";
 import { buildRunMetadataSection } from "../utils/runs.js";
 import { renderTranscript } from "../utils/transcript.js";
+import { renderRunList } from "./list.js";
 export function buildPruneConfirmationPreface(options) {
     const { runId, specPath, runStatus, createdAt, runPath, workspaces, directories, branches, purge, previouslyDeletedAt, } = options;
     const introLines = buildRunMetadataSection({
@@ -32,6 +33,14 @@ export function buildPruneConfirmationPreface(options) {
     lines.push("");
     return lines;
 }
+export function buildPruneAllConfirmationPreface(options) {
+    const { records } = options;
+    const tableOutput = renderRunList(records);
+    const lines = tableOutput.trim().length > 0 ? ["", ...tableOutput.split("\n")] : [];
+    const runLabel = records.length === 1 ? "run" : "runs";
+    lines.push("", `${records.length} ${runLabel} to prune.`, "");
+    return lines;
+}
 export function renderPruneTranscript(result) {
     if (result.status === "aborted") {
         const sections = [
@@ -48,3 +57,21 @@ export function renderPruneTranscript(result) {
         sections: [[colorize("Run pruned successfully.", "green")]],
     });
 }
+export function renderPruneAllTranscript(result) {
+    if (result.status === "noop") {
+        return renderTranscript({
+            sections: [["No runs to prune."]],
+        });
+    }
+    if (result.status === "aborted") {
+        return renderTranscript({
+            sections: [[colorize("Prune aborted; no changes were made.", "yellow")]],
+            hint: {
+                message: "Re-run `voratiq prune --all` when you are ready.",
+            },
+        });
+    }
+    return renderTranscript({
+        sections: [[colorize("Runs pruned successfully.", "green")]],
+    });
+}

package/dist/reviews/records/types.d.ts

@@ -1,10 +1,7 @@
 import { z } from "zod";
-export declare const reviewStatusSchema: z.ZodEnum<{
-    running: "running";
-    succeeded: "succeeded";
-    failed: "failed";
-}>;
-export type ReviewStatus = z.infer<typeof reviewStatusSchema>;
+import { type ReviewStatus, reviewStatusSchema, TERMINAL_REVIEW_STATUSES } from "../../status/index.js";
+export type { ReviewStatus };
+export { reviewStatusSchema, TERMINAL_REVIEW_STATUSES };
 export declare const reviewRecordSchema: z.ZodObject<{
     sessionId: z.ZodString;
     runId: z.ZodString;
@@ -21,4 +18,3 @@ export declare const reviewRecordSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ReviewRecord = z.infer<typeof reviewRecordSchema>;
 export type ReviewIndexEntry = Pick<ReviewRecord, "sessionId" | "createdAt" | "status">;
-export declare const TERMINAL_REVIEW_STATUSES: readonly ReviewStatus[];

package/dist/reviews/records/types.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { agentIdSchema } from "../../configs/agents/types.js";
+import { reviewStatusSchema, TERMINAL_REVIEW_STATUSES, } from "../../status/index.js";
 import { assertRepoRelativePath } from "../../utils/path.js";
+export { reviewStatusSchema, TERMINAL_REVIEW_STATUSES };
 function validateRepoRelativePath(value, ctx) {
     try {
         assertRepoRelativePath(value);
@@ -15,7 +17,6 @@ function validateRepoRelativePath(value, ctx) {
 const repoRelativePathSchema = z
     .string()
     .superRefine((value, ctx) => validateRepoRelativePath(value, ctx));
-export const reviewStatusSchema = z.enum(["running", "succeeded", "failed"]);
 export const reviewRecordSchema = z.object({
     sessionId: z.string(),
     runId: z.string(),
@@ -26,7 +27,3 @@ export const reviewRecordSchema = z.object({
     outputPath: repoRelativePathSchema,
     error: z.string().nullable().optional(),
 });
-export const TERMINAL_REVIEW_STATUSES = [
-    "succeeded",
-    "failed",
-];

package/dist/runs/records/types.d.ts

@@ -1,22 +1,11 @@
 import { z } from "zod";
-import type { AgentStatus as StatusAgentStatus } from "../../status/index.js";
+import { type AgentStatus, agentStatusSchema, EVAL_REQUIRED_AGENT_STATUSES, IN_PROGRESS_AGENT_STATUSES, TERMINAL_AGENT_STATUSES } from "../../status/index.js";
+export type { AgentStatus };
+export { agentStatusSchema, EVAL_REQUIRED_AGENT_STATUSES, IN_PROGRESS_AGENT_STATUSES, TERMINAL_AGENT_STATUSES, };
 export declare const runSpecDescriptorSchema: z.ZodObject<{
     path: z.ZodString;
 }, z.core.$strip>;
 export type RunSpecDescriptor = z.infer<typeof runSpecDescriptorSchema>;
-export declare const agentStatusSchema: z.ZodEnum<{
-    queued: "queued";
-    running: "running";
-    succeeded: "succeeded";
-    failed: "failed";
-    errored: "errored";
-    aborted: "aborted";
-    skipped: "skipped";
-}>;
-export type AgentStatus = StatusAgentStatus;
-export declare const TERMINAL_AGENT_STATUSES: AgentStatus[];
-export declare const EVAL_REQUIRED_AGENT_STATUSES: AgentStatus[];
-export declare const IN_PROGRESS_AGENT_STATUSES: AgentStatus[];
 export declare const watchdogMetadataSchema: z.ZodObject<{
     silenceTimeoutMs: z.ZodNumber;
     wallClockCapMs: z.ZodNumber;
@@ -128,6 +117,7 @@ export declare const applyStatusSchema: z.ZodObject<{
     }>;
     appliedAt: z.ZodString;
     ignoredBaseMismatch: z.ZodBoolean;
+    appliedCommitSha: z.ZodOptional<z.ZodString>;
     detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type RunApplyStatus = z.infer<typeof applyStatusSchema>;
@@ -217,6 +207,7 @@ export declare const runRecordSchema: z.ZodObject<{
         }>;
         appliedAt: z.ZodString;
         ignoredBaseMismatch: z.ZodBoolean;
+        appliedCommitSha: z.ZodOptional<z.ZodString>;
         detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
     deletedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/runs/records/types.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { agentIdSchema } from "../../configs/agents/types.js";
 import { evalSlugSchema, evalStatusSchema } from "../../configs/evals/types.js";
-import { agentStatusSchema as sharedAgentStatusSchema, applyStatusEnum, runStatusSchema, } from "../../status/index.js";
+import { agentStatusSchema, applyStatusSchema as applyStatusValueSchema, EVAL_REQUIRED_AGENT_STATUSES, IN_PROGRESS_AGENT_STATUSES, runStatusSchema, TERMINAL_AGENT_STATUSES, } from "../../status/index.js";
 import { assertRepoRelativePath } from "../../utils/path.js";
+export { agentStatusSchema, EVAL_REQUIRED_AGENT_STATUSES, IN_PROGRESS_AGENT_STATUSES, TERMINAL_AGENT_STATUSES, };
 function validateRepoRelativePath(value, ctx) {
     try {
         assertRepoRelativePath(value);
@@ -20,24 +21,6 @@ const repoRelativePathSchema = z
 export const runSpecDescriptorSchema = z.object({
     path: repoRelativePathSchema,
 });
-export const agentStatusSchema = sharedAgentStatusSchema;
-export const TERMINAL_AGENT_STATUSES = [
-    "succeeded",
-    "failed",
-    "errored",
-    "skipped",
-    "aborted",
-];
-export const EVAL_REQUIRED_AGENT_STATUSES = [
-    "succeeded",
-    "failed",
-    "errored",
-    "skipped",
-];
-export const IN_PROGRESS_AGENT_STATUSES = [
-    "queued",
-    "running",
-];
 const CHAT_ARTIFACT_FORMATS = [
     "json",
     "jsonl",
@@ -142,9 +125,10 @@ export const agentInvocationRecordSchema = z
 });
 export const applyStatusSchema = z.object({
     agentId: agentIdSchema,
-    status: applyStatusEnum,
+    status: applyStatusValueSchema,
     appliedAt: z.string(),
     ignoredBaseMismatch: z.boolean(),
+    appliedCommitSha: z.string().min(1).optional(),
     detail: z.string().max(256).nullable().optional(),
 });
 export const runRecordSchema = z.object({

package/dist/specs/records/types.d.ts

@@ -1,20 +1,13 @@
 import { z } from "zod";
+import { type SpecRecordStatus, specRecordStatusSchema, TERMINAL_SPEC_STATUSES } from "../../status/index.js";
+export type { SpecRecordStatus };
+export { specRecordStatusSchema, TERMINAL_SPEC_STATUSES };
 export declare const specIterationRecordSchema: z.ZodObject<{
     iteration: z.ZodNumber;
     createdAt: z.ZodString;
     accepted: z.ZodBoolean;
 }, z.core.$strip>;
 export type SpecIterationRecord = z.infer<typeof specIterationRecordSchema>;
-export declare const specRecordStatusSchema: z.ZodEnum<{
-    failed: "failed";
-    aborted: "aborted";
-    drafting: "drafting";
-    "awaiting-feedback": "awaiting-feedback";
-    refining: "refining";
-    saving: "saving";
-    saved: "saved";
-}>;
-export type SpecRecordStatus = z.infer<typeof specRecordStatusSchema>;
 export declare const specRecordSchema: z.ZodObject<{
     sessionId: z.ZodString;
     createdAt: z.ZodString;
@@ -41,4 +34,3 @@ export declare const specRecordSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SpecRecord = z.infer<typeof specRecordSchema>;
 export type SpecIndexEntry = Pick<SpecRecord, "sessionId" | "createdAt" | "status">;
-export declare const TERMINAL_SPEC_STATUSES: SpecRecordStatus[];

package/dist/specs/records/types.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { agentIdSchema } from "../../configs/agents/types.js";
+import { specRecordStatusSchema, TERMINAL_SPEC_STATUSES, } from "../../status/index.js";
 import { assertRepoRelativePath } from "../../utils/path.js";
+export { specRecordStatusSchema, TERMINAL_SPEC_STATUSES };
 function validateRepoRelativePath(value, ctx) {
     try {
         assertRepoRelativePath(value);
@@ -20,15 +22,6 @@ export const specIterationRecordSchema = z.object({
     createdAt: z.string(),
     accepted: z.boolean(),
 });
-export const specRecordStatusSchema = z.enum([
-    "drafting",
-    "awaiting-feedback",
-    "refining",
-    "saving",
-    "saved",
-    "aborted",
-    "failed",
-]);
 export const specRecordSchema = z.object({
     sessionId: z.string(),
     createdAt: z.string(),
@@ -41,8 +34,3 @@ export const specRecordSchema = z.object({
     iterations: z.array(specIterationRecordSchema),
     error: z.string().nullable().optional(),
 });
-export const TERMINAL_SPEC_STATUSES = [
-    "saved",
-    "aborted",
-    "failed",
-];

package/dist/status/index.d.ts

@@ -1,12 +1,6 @@
 import { z } from "zod";
 export declare const RUN_STATUS_VALUES: readonly ["queued", "running", "succeeded", "failed", "errored", "aborted", "pruned"];
 export type RunStatus = (typeof RUN_STATUS_VALUES)[number];
-export declare const AGENT_STATUS_VALUES: readonly ["queued", "running", "succeeded", "failed", "errored", "skipped", "aborted"];
-export type AgentStatus = (typeof AGENT_STATUS_VALUES)[number];
-export declare const EVAL_STATUS_VALUES: readonly ["succeeded", "failed", "errored", "skipped"];
-export type EvalStatus = (typeof EVAL_STATUS_VALUES)[number];
-export declare const APPLY_STATUS_VALUES: readonly ["succeeded", "failed"];
-export type ApplyStatus = (typeof APPLY_STATUS_VALUES)[number];
 export declare const runStatusSchema: z.ZodEnum<{
     queued: "queued";
     running: "running";
@@ -16,6 +10,20 @@ export declare const runStatusSchema: z.ZodEnum<{
     aborted: "aborted";
     pruned: "pruned";
 }>;
+/**
+ * Run statuses that indicate the run has finished execution.
+ */
+export declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
+/**
+ * Run statuses that indicate the run is queued or executing.
+ */
+export declare const IN_PROGRESS_RUN_STATUSES: readonly RunStatus[];
+/**
+ * Run statuses that allow forced termination (e.g., abort or fail).
+ */
+export declare const TERMINABLE_RUN_STATUSES: readonly RunStatus[];
+export declare const AGENT_STATUS_VALUES: readonly ["queued", "running", "succeeded", "failed", "errored", "skipped", "aborted"];
+export type AgentStatus = (typeof AGENT_STATUS_VALUES)[number];
 export declare const agentStatusSchema: z.ZodEnum<{
     queued: "queued";
     running: "running";
@@ -25,13 +33,56 @@ export declare const agentStatusSchema: z.ZodEnum<{
     aborted: "aborted";
     skipped: "skipped";
 }>;
+/**
+ * Agent statuses that indicate the agent has finished execution.
+ */
+export declare const TERMINAL_AGENT_STATUSES: readonly AgentStatus[];
+/**
+ * Agent statuses that indicate the agent is still running or waiting.
+ */
+export declare const IN_PROGRESS_AGENT_STATUSES: readonly AgentStatus[];
+/**
+ * Agent statuses that require eval results to be present.
+ * "aborted" is excluded because agents can be cancelled before evals are produced.
+ */
+export declare const EVAL_REQUIRED_AGENT_STATUSES: readonly AgentStatus[];
+export declare const EVAL_STATUS_VALUES: readonly ["succeeded", "failed", "errored", "skipped"];
+export type EvalStatus = (typeof EVAL_STATUS_VALUES)[number];
 export declare const evalStatusSchema: z.ZodEnum<{
     succeeded: "succeeded";
     failed: "failed";
     errored: "errored";
     skipped: "skipped";
 }>;
-export declare const applyStatusEnum: z.ZodEnum<{
+export declare const APPLY_STATUS_VALUES: readonly ["succeeded", "failed"];
+export type ApplyStatus = (typeof APPLY_STATUS_VALUES)[number];
+export declare const applyStatusSchema: z.ZodEnum<{
     succeeded: "succeeded";
     failed: "failed";
 }>;
+export declare const REVIEW_STATUS_VALUES: readonly ["running", "succeeded", "failed"];
+export type ReviewStatus = (typeof REVIEW_STATUS_VALUES)[number];
+export declare const reviewStatusSchema: z.ZodEnum<{
+    running: "running";
+    succeeded: "succeeded";
+    failed: "failed";
+}>;
+/**
+ * Review statuses that indicate the review session has finished.
+ */
+export declare const TERMINAL_REVIEW_STATUSES: readonly ReviewStatus[];
+export declare const SPEC_RECORD_STATUS_VALUES: readonly ["drafting", "awaiting-feedback", "refining", "saving", "saved", "aborted", "failed"];
+export type SpecRecordStatus = (typeof SPEC_RECORD_STATUS_VALUES)[number];
+export declare const specRecordStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    aborted: "aborted";
+    drafting: "drafting";
+    "awaiting-feedback": "awaiting-feedback";
+    refining: "refining";
+    saving: "saving";
+    saved: "saved";
+}>;
+/**
+ * Spec record statuses that indicate the spec session has finished.
+ */
+export declare const TERMINAL_SPEC_STATUSES: readonly SpecRecordStatus[];

package/dist/status/index.js

@@ -8,6 +8,30 @@ export const RUN_STATUS_VALUES = [
     "aborted",
     "pruned",
 ];
+export const runStatusSchema = z.enum(RUN_STATUS_VALUES);
+/**
+ * Run statuses that indicate the run has finished execution.
+ */
+export const TERMINAL_RUN_STATUSES = [
+    "succeeded",
+    "failed",
+    "errored",
+    "aborted",
+];
+/**
+ * Run statuses that indicate the run is queued or executing.
+ */
+export const IN_PROGRESS_RUN_STATUSES = [
+    "queued",
+    "running",
+];
+/**
+ * Run statuses that allow forced termination (e.g., abort or fail).
+ */
+export const TERMINABLE_RUN_STATUSES = [
+    "failed",
+    "aborted",
+];
 export const AGENT_STATUS_VALUES = [
     "queued",
     "running",
@@ -17,14 +41,67 @@ export const AGENT_STATUS_VALUES = [
     "skipped",
     "aborted",
 ];
+export const agentStatusSchema = z.enum(AGENT_STATUS_VALUES);
+/**
+ * Agent statuses that indicate the agent has finished execution.
+ */
+export const TERMINAL_AGENT_STATUSES = [
+    "succeeded",
+    "failed",
+    "errored",
+    "skipped",
+    "aborted",
+];
+/**
+ * Agent statuses that indicate the agent is still running or waiting.
+ */
+export const IN_PROGRESS_AGENT_STATUSES = [
+    "queued",
+    "running",
+];
+/**
+ * Agent statuses that require eval results to be present.
+ * "aborted" is excluded because agents can be cancelled before evals are produced.
+ */
+export const EVAL_REQUIRED_AGENT_STATUSES = [
+    "succeeded",
+    "failed",
+    "errored",
+    "skipped",
+];
 export const EVAL_STATUS_VALUES = [
     "succeeded",
     "failed",
     "errored",
     "skipped",
 ];
-export const APPLY_STATUS_VALUES = ["succeeded", "failed"];
-export const runStatusSchema = z.enum(RUN_STATUS_VALUES);
-export const agentStatusSchema = z.enum(AGENT_STATUS_VALUES);
 export const evalStatusSchema = z.enum(EVAL_STATUS_VALUES);
-export const applyStatusEnum = z.enum(APPLY_STATUS_VALUES);
+export const APPLY_STATUS_VALUES = ["succeeded", "failed"];
+export const applyStatusSchema = z.enum(APPLY_STATUS_VALUES);
+export const REVIEW_STATUS_VALUES = ["running", "succeeded", "failed"];
+export const reviewStatusSchema = z.enum(REVIEW_STATUS_VALUES);
+/**
+ * Review statuses that indicate the review session has finished.
+ */
+export const TERMINAL_REVIEW_STATUSES = [
+    "succeeded",
+    "failed",
+];
+export const SPEC_RECORD_STATUS_VALUES = [
+    "drafting",
+    "awaiting-feedback",
+    "refining",
+    "saving",
+    "saved",
+    "aborted",
+    "failed",
+];
+export const specRecordStatusSchema = z.enum(SPEC_RECORD_STATUS_VALUES);
+/**
+ * Spec record statuses that indicate the spec session has finished.
+ */
+export const TERMINAL_SPEC_STATUSES = [
+    "saved",
+    "aborted",
+    "failed",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voratiq",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.6",
   "description": "Run multiple AI coding agents in parallel, compare their results, and apply the best solution.",
   "keywords": [
     "ai",