@cruxy/cli 0.10.0 → 0.11.0

package/dist/approval/classify.js

@@ -16,6 +16,8 @@ export function classify(action, cwd) {
             return fileRequest(action, patchHasDelete(action) ? "destructive" : "mutate", root);
         case "shell":
             return shellRequest(action, root);
+        case "test":
+            return testRequest(action, root);
         case "vcs":
             return vcsRequest(action, root);
         case "rollback":
@@ -69,6 +71,25 @@ function shellRequest(action, root) {
         cwd: root,
     };
 }
+// ── test (run the project's test suite, C.13) ──────────────────────────────────
+/**
+ * A test-suite execution. Destructive tier — a test script is arbitrary code
+ * from package.json — but grantable at the tightest possible scope: the exact
+ * command string. That is precisely what an edit→re-run iteration needs
+ * (approve once, re-run the same suite freely) without widening to a program
+ * prefix the way a shell grant would.
+ */
+function testRequest(action, root) {
+    const command = (action.command ?? "").trim();
+    return {
+        action,
+        tier: "destructive",
+        scope: command === "" ? { kind: "none" } : { kind: "shell-exact", command },
+        summary: `run tests: ${command}`,
+        targets: [],
+        cwd: root,
+    };
+}
 // ── vcs (open pull request) ─────────────────────────────────────────────────────
 /**
  * A pull-request publish (C.15): branch → commit → push → open PR. Always

package/dist/approval/policy.js

@@ -38,6 +38,12 @@ export function scopeCovers(scope, request) {
         const tokens = commandTokens(request.action.command ?? "");
         return tokens !== null && tokens[0] === scope.token;
     }
+    if (scope.kind === "shell-exact") {
+        // Test grants (C.13): the exact command string, test actions only — a
+        // grant for `pnpm test` can never cover run_command or any other command.
+        return (request.action.kind === "test" &&
+            (request.action.command ?? "").trim() === scope.command);
+    }
     // file-subtree
     return (request.targets.length > 0 &&
         request.targets.every((t) => isInside(scope.root, t)));

package/dist/approval/prompt.js

@@ -45,9 +45,9 @@ export function render(request, color) {
     lines.push(choices(request.scope, c));
     return lines.filter((l) => l !== "").join("\n") + " ";
 }
-/** The action detail: a diff for file actions, the command + cwd for shell. */
+/** The action detail: a diff for file actions, the command + cwd for shell/test. */
 function detail(request, c) {
-    if (request.action.kind === "shell") {
+    if (request.action.kind === "shell" || request.action.kind === "test") {
         return [
             `  ${c.dim("$")} ${request.action.command ?? ""}`,
             `  ${c.dim(`in ${request.cwd}`)}`,
@@ -67,6 +67,8 @@ function choices(scope, c) {
 function scopeLabel(scope) {
     if (scope.kind === "shell-prefix")
         return `${scope.token} commands`;
+    if (scope.kind === "shell-exact")
+        return `re-runs of \`${scope.command}\``;
     if (scope.kind === "file-subtree")
         return `changes under ${path.basename(scope.root)}/`;
     return null;

package/dist/approval/types.d.ts

@@ -17,6 +17,8 @@ export type RiskTier = "read" | "mutate" | "destructive";
  * The tight scope a session grant is keyed by. Never blanket.
  * - `shell-prefix` — a command's leading program token (e.g. `git`); only ever
  *   matches commands we can *positively* prove are simple (no shell features).
+ * - `shell-exact` — one exact command string, for `test` actions only (C.13):
+ *   a grant covers re-runs of precisely that test command, nothing else.
  * - `file-subtree` — an absolute directory (or, under the root-cap, an exact
  *   file path); matches targets that resolve inside it.
  * - `none` — nothing safe to grant (e.g. a multi-file patch spanning the root).
@@ -24,6 +26,9 @@ export type RiskTier = "read" | "mutate" | "destructive";
 export type Scope = {
     readonly kind: "shell-prefix";
     readonly token: string;
+} | {
+    readonly kind: "shell-exact";
+    readonly command: string;
 } | {
     readonly kind: "file-subtree";
     readonly root: string;

package/dist/cli/commands/test.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+/**
+ * `cruxy test` (C.13) — run the project's detected/configured test command
+ * once and print the structured result the agent would see. Directly
+ * user-invoked, so there is no approval gate (typing the command IS the
+ * consent — same as running the suite by hand); the process exit code mirrors
+ * the suite's pass/fail so scripts and CI can branch on it.
+ */
+export declare function testCommand(): Command;

package/dist/cli/commands/test.js

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { testCommandNotFound } from "../../errors/index.js";
+import { CommandTestRunner, detectTestCommand } from "../../testing/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy test` (C.13) — run the project's detected/configured test command
+ * once and print the structured result the agent would see. Directly
+ * user-invoked, so there is no approval gate (typing the command IS the
+ * consent — same as running the suite by hand); the process exit code mirrors
+ * the suite's pass/fail so scripts and CI can branch on it.
+ */
+export function testCommand() {
+    return new Command("test")
+        .description("run the project's test suite once and show the parsed result")
+        .action(async () => {
+        const { config } = loadConfig();
+        const cwd = process.cwd();
+        const detected = detectTestCommand(cwd, config);
+        if (detected === null)
+            throw testCommandNotFound();
+        logger.print(pc.dim(`running: ${detected.command}  [${detected.source}]`));
+        const result = await new CommandTestRunner().run(detected.command, {
+            cwd,
+            timeoutMs: config.shell.timeoutMs,
+            captureBytes: config.test.captureBytes,
+        });
+        const seconds = (result.durationMs / 1000).toFixed(1);
+        if (result.passed) {
+            logger.print(`${pc.green("✓")} tests passed${result.total !== undefined ? ` (${result.total})` : ""} in ${seconds}s`);
+            return;
+        }
+        logger.print(`${pc.red("✗")} tests failed (exit ${result.exitCode ?? "signal"}) in ${seconds}s`);
+        for (const failure of result.failures) {
+            const where = failure.file !== undefined
+                ? pc.dim(`  ${failure.file}${failure.line !== undefined ? `:${failure.line}` : ""}`)
+                : "";
+            logger.print(`  ${pc.red("✗")} ${failure.name}${where}`);
+        }
+        if (result.failures.length === 0) {
+            // Nothing parseable — show the honest tail instead of fake structure.
+            logger.print(pc.dim(result.output.trimEnd()));
+        }
+        process.exitCode = 1;
+    });
+}

package/dist/cli/program.js

@@ -12,6 +12,7 @@ import { loginCommand } from "./commands/login.js";
 import { initCommand } from "./commands/init.js";
 import { checkpointCommand } from "./commands/checkpoint.js";
 import { rollbackCommand } from "./commands/rollback.js";
+import { testCommand } from "./commands/test.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -40,6 +41,7 @@ export function buildProgram() {
     program.addCommand(initCommand());
     program.addCommand(checkpointCommand());
     program.addCommand(rollbackCommand());
+    program.addCommand(testCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/session-factory.js

@@ -67,10 +67,14 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
         if (request.tier === "read")
             return decision;
         await checkpoints.ensureCheckpoint();
-        if (action.kind === "shell")
+        // Shell AND test executions (C.13) can mutate files we can't attribute
+        // (scripts, snapshot writers) — record the lost attribution the same way.
+        if (action.kind === "shell" || action.kind === "test") {
             await checkpoints.recordShellMutation();
-        else
+        }
+        else {
             await checkpoints.recordTouched([...request.targets]);
+        }
         return decision;
     };
 }

package/dist/config/schema.d.ts

@@ -219,6 +219,27 @@ export declare const CheckpointConfigSchema: z.ZodObject<{
     enabled?: boolean | undefined;
     retention?: number | undefined;
 }>;
+/**
+ * Test-execution loop (C.13): how the agent runs the project's test suite and
+ * iterates on failures. The command is detected from package.json when unset;
+ * cruxy never invents one.
+ */
+export declare const TestConfigSchema: z.ZodObject<{
+    /** Explicit test command (overrides package.json detection). */
+    command: z.ZodOptional<z.ZodString>;
+    /** Consecutive failing runs before the edit→re-run loop trips its cap. */
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    /** Cap on captured test output bytes (tail-biased — failures come last). */
+    captureBytes: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxIterations: number;
+    captureBytes: number;
+    command?: string | undefined;
+}, {
+    maxIterations?: number | undefined;
+    command?: string | undefined;
+    captureBytes?: number | undefined;
+}>;
 /**
  * Subagent orchestration (C.14): scoped child agents the main agent can spawn
  * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
@@ -514,6 +535,22 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             timeoutMs?: number | undefined;
         } | undefined;
     }>>;
+    test: z.ZodDefault<z.ZodObject<{
+        /** Explicit test command (overrides package.json detection). */
+        command: z.ZodOptional<z.ZodString>;
+        /** Consecutive failing runs before the edit→re-run loop trips its cap. */
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        /** Cap on captured test output bytes (tail-biased — failures come last). */
+        captureBytes: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxIterations: number;
+        captureBytes: number;
+        command?: string | undefined;
+    }, {
+        maxIterations?: number | undefined;
+        command?: string | undefined;
+        captureBytes?: number | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -592,6 +629,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             timeoutMs?: number | undefined;
         };
     };
+    test: {
+        maxIterations: number;
+        captureBytes: number;
+        command?: string | undefined;
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -662,6 +704,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             timeoutMs?: number | undefined;
         } | undefined;
     } | undefined;
+    test?: {
+        maxIterations?: number | undefined;
+        command?: string | undefined;
+        captureBytes?: number | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -149,6 +149,25 @@ export const CheckpointConfigSchema = z
     retention: z.number().int().positive().default(10),
 })
     .strict();
+/**
+ * Test-execution loop (C.13): how the agent runs the project's test suite and
+ * iterates on failures. The command is detected from package.json when unset;
+ * cruxy never invents one.
+ */
+export const TestConfigSchema = z
+    .object({
+    /** Explicit test command (overrides package.json detection). */
+    command: z.string().min(1).optional(),
+    /** Consecutive failing runs before the edit→re-run loop trips its cap. */
+    maxIterations: z.number().int().positive().default(4),
+    /** Cap on captured test output bytes (tail-biased — failures come last). */
+    captureBytes: z
+        .number()
+        .int()
+        .positive()
+        .default(64 * 1024),
+})
+    .strict();
 /**
  * Subagent orchestration (C.14): scoped child agents the main agent can spawn
  * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
@@ -196,6 +215,7 @@ export const CruxyConfigSchema = z
     index: IndexConfigSchema.default({}),
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
+    test: TestConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/errors/constructors.d.ts

@@ -85,6 +85,11 @@ export declare function subagentDepthExceeded(depth: number, maxDepth: number):
  * reasons over; thrown only when the orchestrator itself cannot proceed.
  */
 export declare function subagentFailed(underlying?: unknown): CruxyError;
+/**
+ * No test command could be detected and none is configured (C.13). cruxy never
+ * invents a test command — the fix is always to declare one.
+ */
+export declare function testCommandNotFound(): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -436,6 +436,22 @@ export function subagentFailed(underlying) {
         underlying,
     });
 }
+// ── testing (exit 2) ──────────────────────────────────────────────────────────
+/**
+ * No test command could be detected and none is configured (C.13). cruxy never
+ * invents a test command — the fix is always to declare one.
+ */
+export function testCommandNotFound() {
+    return new CruxyError({
+        code: ErrorCode.TestCommandNotFound,
+        title: "no test command found for this project",
+        cause: "package.json has no usable `scripts.test` and `test.command` is not configured",
+        nextSteps: [
+            'set `test.command` in your cruxy config (e.g. `cruxy config set test.command "pnpm test"`)',
+            "or add a `test` script to package.json",
+        ],
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -49,6 +49,9 @@ export declare const ErrorCode: {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     readonly SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET";
     readonly SubagentFailed: "CRUXY_E_SUBAGENT_FAILED";
+    readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
+    /** Carried inside a run_tests result (informational) — never fatal by itself. */
+    readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -60,6 +60,10 @@ export const ErrorCode = {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET",
     SubagentFailed: "CRUXY_E_SUBAGENT_FAILED",
+    // testing (exit 2 / 11)
+    TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND",
+    /** Carried inside a run_tests result (informational) — never fatal by itself. */
+    TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -104,6 +108,10 @@ const EXIT_CODES = {
     [ErrorCode.SubagentDepthExceeded]: 2,
     [ErrorCode.SubagentBudget]: 11,
     [ErrorCode.SubagentFailed]: 11,
+    // No test command is a configuration gap (usage); the iteration limit
+    // surfaces inside a run_tests result and is never fatal by itself.
+    [ErrorCode.TestCommandNotFound]: 2,
+    [ErrorCode.TestIterationLimit]: 11,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/testing/detect.d.ts

@@ -0,0 +1,3 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { TestCommand } from "./types.js";
+export declare function detectTestCommand(cwd: string, config: CruxyConfig): TestCommand | null;

package/dist/testing/detect.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Resolve the project's test command (C.13). Order: explicit `test.command`
+ * config, then package.json `scripts.test`. Returns `null` when neither
+ * yields one — cruxy NEVER invents a test command; the caller surfaces the
+ * coded not-configured error instead.
+ */
+/** npm's scaffold placeholder is an error message, not a test suite. */
+const NPM_PLACEHOLDER = /no test specified/i;
+export function detectTestCommand(cwd, config) {
+    if (config.test.command) {
+        return { command: config.test.command, source: "config" };
+    }
+    const script = readTestScript(cwd);
+    if (script === null)
+        return null;
+    return { command: `${packageManager(cwd)} test`, source: "package-json" };
+}
+/** The package.json `scripts.test` value, or null if absent/placeholder/unreadable. */
+function readTestScript(cwd) {
+    try {
+        const raw = readFileSync(path.join(cwd, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        const script = pkg.scripts?.test;
+        if (typeof script !== "string" || script.trim() === "")
+            return null;
+        if (NPM_PLACEHOLDER.test(script))
+            return null;
+        return script;
+    }
+    catch {
+        // No package.json / unparseable → not detected (never a crash).
+        return null;
+    }
+}
+/** Pick the package manager by lockfile; npm when nothing identifies one. */
+function packageManager(cwd) {
+    if (existsSync(path.join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(path.join(cwd, "yarn.lock")))
+        return "yarn";
+    return "npm";
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./runner.js";
+export * from "./parse.js";
+export * from "./run-tests-tool.js";

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./runner.js";
+export * from "./parse.js";
+export * from "./run-tests-tool.js";

package/dist/testing/parse.d.ts

@@ -0,0 +1,33 @@
+import type { FailureParser, TestFailure } from "./types.js";
+/**
+ * Best-effort failure extraction (C.13). Two conservative parsers ship —
+ * vitest-style and jest-style — behind the pluggable {@link FailureParser}
+ * seam. The contract: extract only what a pattern positively recognizes;
+ * when nothing matches, return NOTHING (the caller falls back to the raw
+ * tail). Parsers never decide pass/fail and never invent counts — `message`
+ * fields are verbatim runner output, not summaries we authored.
+ */
+/**
+ * Vitest: per-test failure lines (`FAIL src/x.test.ts > suite > name`, also
+ * `×`/`✗` markers) and the `Tests  2 failed | 570 passed (572)` summary.
+ * Plain file-level `FAIL <file>` lines are deliberately left to the jest
+ * parser, which owns the file+bullet association.
+ */
+export declare const parseVitest: FailureParser;
+/**
+ * Jest: `FAIL <file>` headers with `● <name>` bullets underneath (the bullet's
+ * following indented lines are its message, verbatim), and the
+ * `Tests: …, N total` summary. A FAIL header with no bullets (e.g. a suite
+ * that failed to load) becomes one file-level failure.
+ */
+export declare const parseJest: FailureParser;
+/** Parser order: most-specific first. The pluggable seam for new frameworks. */
+export declare const defaultParsers: readonly FailureParser[];
+/**
+ * Run the parser chain; the first parser that recognizes anything wins.
+ * Nothing recognized → empty failures, no total — the raw tail is the result.
+ */
+export declare function parseFailures(output: string): {
+    failures: TestFailure[];
+    total?: number;
+};

package/dist/testing/parse.js

@@ -0,0 +1,137 @@
+/**
+ * Best-effort failure extraction (C.13). Two conservative parsers ship —
+ * vitest-style and jest-style — behind the pluggable {@link FailureParser}
+ * seam. The contract: extract only what a pattern positively recognizes;
+ * when nothing matches, return NOTHING (the caller falls back to the raw
+ * tail). Parsers never decide pass/fail and never invent counts — `message`
+ * fields are verbatim runner output, not summaries we authored.
+ */
+/**
+ * Vitest: per-test failure lines (`FAIL src/x.test.ts > suite > name`, also
+ * `×`/`✗` markers) and the `Tests  2 failed | 570 passed (572)` summary.
+ * Plain file-level `FAIL <file>` lines are deliberately left to the jest
+ * parser, which owns the file+bullet association.
+ */
+export const parseVitest = (output) => {
+    const failures = [];
+    for (const line of output.split("\n")) {
+        const match = /^\s*(?:FAIL|✗|×)\s+(\S+)\s+>\s+(.+?)\s*$/.exec(line);
+        if (match) {
+            failures.push({
+                name: match[2],
+                message: line.trim(),
+                file: match[1],
+            });
+        }
+    }
+    attachLines(failures, output);
+    const total = /^\s*Tests\s+.*\((\d+)\)\s*$/m.exec(output);
+    return {
+        failures,
+        ...(total ? { total: Number(total[1]) } : {}),
+    };
+};
+/**
+ * Jest: `FAIL <file>` headers with `● <name>` bullets underneath (the bullet's
+ * following indented lines are its message, verbatim), and the
+ * `Tests: …, N total` summary. A FAIL header with no bullets (e.g. a suite
+ * that failed to load) becomes one file-level failure.
+ */
+export const parseJest = (output) => {
+    const failures = [];
+    const lines = output.split("\n");
+    let currentFile;
+    const filesWithBullets = new Set();
+    const bareFiles = [];
+    for (let i = 0; i < lines.length; i++) {
+        const fail = /^\s*FAIL\s+(\S+)\s*$/.exec(lines[i]);
+        if (fail) {
+            currentFile = fail[1];
+            bareFiles.push(fail[1]);
+            continue;
+        }
+        const bullet = /^\s*●\s+(.+?)\s*$/.exec(lines[i]);
+        if (bullet) {
+            failures.push({
+                name: bullet[1],
+                message: bulletMessage(lines, i),
+                ...(currentFile ? { file: currentFile } : {}),
+            });
+            if (currentFile)
+                filesWithBullets.add(currentFile);
+        }
+    }
+    // A failed suite with no per-test bullets is still one honest failure.
+    for (const file of bareFiles) {
+        if (!filesWithBullets.has(file)) {
+            failures.push({ name: file, message: `FAIL ${file}`, file });
+        }
+    }
+    attachLines(failures, output);
+    const total = /^Tests:.*?(\d+)\s+total\s*$/m.exec(output);
+    return {
+        failures,
+        ...(total ? { total: Number(total[1]) } : {}),
+    };
+};
+/**
+ * Up to three non-blank lines under a jest bullet — its verbatim message.
+ * Jest separates the bullet from its detail with a blank line, so leading
+ * blanks are skipped; collection stops at the next blank, the next bullet,
+ * or the cap.
+ */
+function bulletMessage(lines, bulletIndex) {
+    const body = [];
+    for (let j = bulletIndex + 1; j < lines.length && body.length < 3; j++) {
+        const text = lines[j].trim();
+        if (text === "") {
+            if (body.length === 0)
+                continue; // the separator blank under the bullet
+            break;
+        }
+        if (/^\s*●\s+/.test(lines[j]))
+            break;
+        body.push(text);
+    }
+    return body.length > 0 ? body.join("\n") : lines[bulletIndex].trim();
+}
+/**
+ * Attach `line` to failures whose file appears in a `file:line:col` stack
+ * reference anywhere in the output (vitest `❯ file:39:5`, jest
+ * `at … (file:12:15)`). First reference per file wins; no reference → no line.
+ */
+function attachLines(failures, output) {
+    if (failures.length === 0)
+        return;
+    const firstLineFor = new Map();
+    for (const match of output.matchAll(/([^\s():]+):(\d+):\d+/g)) {
+        if (!firstLineFor.has(match[1])) {
+            firstLineFor.set(match[1], Number(match[2]));
+        }
+    }
+    for (const failure of failures) {
+        if (failure.file === undefined || failure.line !== undefined)
+            continue;
+        const line = firstLineFor.get(failure.file);
+        if (line !== undefined)
+            failure.line = line;
+    }
+}
+/** Parser order: most-specific first. The pluggable seam for new frameworks. */
+export const defaultParsers = [
+    parseVitest,
+    parseJest,
+];
+/**
+ * Run the parser chain; the first parser that recognizes anything wins.
+ * Nothing recognized → empty failures, no total — the raw tail is the result.
+ */
+export function parseFailures(output) {
+    for (const parser of defaultParsers) {
+        const result = parser(output);
+        if (result.failures.length > 0 || result.total !== undefined) {
+            return result;
+        }
+    }
+    return { failures: [] };
+}

package/dist/testing/run-tests-tool.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { Tool, ToolContext } from "../tools/types.js";
+import type { TestCommand, TestRunner } from "./types.js";
+/**
+ * The `run_tests` tool (C.13): execute the project's test suite and return a
+ * structured result the model can iterate on (edit → re-run → repeat). The
+ * iteration loop itself is the ordinary agent loop; this module contributes
+ * the two guarantees that make it trustworthy — honest green (exit-code-only)
+ * and a hard cap on consecutive failing runs.
+ */
+/**
+ * Counts consecutive FAILING test executions; a green run resets it. When the
+ * count reaches the cap, the next attempt is refused with the coded
+ * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
+ * resets — so the episode ends loudly, but a deliberate later attempt (a new
+ * user instruction) starts fresh rather than finding a permanently dead tool.
+ * Per-turn work stays bounded regardless via `agent.maxIterations`.
+ */
+export declare class TestIterationBudget {
+    private failedRuns;
+    /** Runs already spent in the current failing streak. */
+    get spent(): number;
+    /** True when the next run must be refused; resets the streak as it trips. */
+    trip(maxIterations: number): boolean;
+    record(passed: boolean): void;
+}
+declare const parameters: z.ZodObject<{
+    command: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    command?: string | undefined;
+}, {
+    command?: string | undefined;
+}>;
+export interface RunTestsToolDeps {
+    /** Execution seam (tests inject a fake; default spawns the real command). */
+    runner?: TestRunner;
+    /** Detection seam (defaults to config + package.json detection). */
+    detect?: (ctx: ToolContext) => TestCommand | null;
+}
+/** Build the `run_tests` tool. One instance = one session's iteration budget. */
+export declare function makeRunTestsTool(deps?: RunTestsToolDeps): Tool<typeof parameters>;
+export {};

package/dist/testing/run-tests-tool.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { ErrorCode } from "../errors/index.js";
+import { detectTestCommand } from "./detect.js";
+import { CommandTestRunner } from "./runner.js";
+/**
+ * The `run_tests` tool (C.13): execute the project's test suite and return a
+ * structured result the model can iterate on (edit → re-run → repeat). The
+ * iteration loop itself is the ordinary agent loop; this module contributes
+ * the two guarantees that make it trustworthy — honest green (exit-code-only)
+ * and a hard cap on consecutive failing runs.
+ */
+/**
+ * Counts consecutive FAILING test executions; a green run resets it. When the
+ * count reaches the cap, the next attempt is refused with the coded
+ * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
+ * resets — so the episode ends loudly, but a deliberate later attempt (a new
+ * user instruction) starts fresh rather than finding a permanently dead tool.
+ * Per-turn work stays bounded regardless via `agent.maxIterations`.
+ */
+export class TestIterationBudget {
+    failedRuns = 0;
+    /** Runs already spent in the current failing streak. */
+    get spent() {
+        return this.failedRuns;
+    }
+    /** True when the next run must be refused; resets the streak as it trips. */
+    trip(maxIterations) {
+        if (this.failedRuns < maxIterations)
+            return false;
+        this.failedRuns = 0;
+        return true;
+    }
+    record(passed) {
+        this.failedRuns = passed ? 0 : this.failedRuns + 1;
+    }
+}
+const parameters = z.object({
+    command: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Override the detected test command (still requires approval). " +
+        "Omit to use the project's configured/detected command."),
+});
+/** The wire shape fed back to the model — structured, bounded, honest. */
+function renderResult(result, command, iteration) {
+    return JSON.stringify({
+        passed: result.passed,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        command: command.command,
+        ...(result.total !== undefined ? { total: result.total } : {}),
+        failures: result.failures,
+        iteration,
+        output: result.output,
+        outputTruncated: result.outputTruncated,
+    });
+}
+/** Build the `run_tests` tool. One instance = one session's iteration budget. */
+export function makeRunTestsTool(deps = {}) {
+    const runner = deps.runner ?? new CommandTestRunner();
+    const detect = deps.detect ??
+        ((ctx) => detectTestCommand(ctx.cwd, ctx.config));
+    const budget = new TestIterationBudget();
+    return {
+        name: "run_tests",
+        description: "Run the project's test suite and get a structured result: passed (from the exit code), " +
+            "extracted failures with file/line where recognizable, and the output tail. " +
+            "Use it to verify changes: run, read the failures, fix, re-run. The edit→re-run loop is " +
+            "capped — when the iteration limit trips, stop, summarize the remaining failures, and ask the user.",
+        parameters,
+        async execute(input, ctx) {
+            // Resolve the command first: detection failure needs no approval and
+            // must be a coded, actionable error — never an invented command.
+            let resolved;
+            if (input.command !== undefined) {
+                resolved = { command: input.command, source: "override" };
+            }
+            else {
+                const detected = detect(ctx);
+                if (detected === null)
+                    return { ok: false, error: NOT_FOUND };
+                resolved = detected;
+            }
+            // Iteration cap BEFORE the gate and the run: a refused attempt executes
+            // nothing and costs nothing.
+            const max = ctx.config.test.maxIterations;
+            if (budget.trip(max)) {
+                return {
+                    ok: false,
+                    error: `${ErrorCode.TestIterationLimit}: tests are still failing after ${max} run${max === 1 ? "" : "s"}. ` +
+                        "Stop iterating. Summarize the remaining failures and what you tried, then ask the user how to proceed.",
+                };
+            }
+            // U.3 gate (destructive tier, exact-command grant scope). A thrown
+            // CRUXY_E_APPROVAL_REQUIRED (non-interactive) propagates — do not catch.
+            const decision = await ctx.requestApproval({
+                kind: "test",
+                command: resolved.command,
+            });
+            if (!decision.allow) {
+                return {
+                    ok: false,
+                    error: decision.feedback ?? "test run denied by the user",
+                };
+            }
+            const result = await runner.run(resolved.command, {
+                cwd: ctx.cwd,
+                timeoutMs: ctx.config.shell.timeoutMs,
+                captureBytes: ctx.config.test.captureBytes,
+            });
+            budget.record(result.passed);
+            const payload = renderResult(result, resolved, {
+                run: result.passed ? 0 : budget.spent,
+                max,
+            });
+            // Failing tests are an is_error result so the U.4 trail note reads ✗ —
+            // the payload is identical either way; the model reasons over both.
+            return result.passed
+                ? { ok: true, output: payload }
+                : { ok: false, error: payload };
+        },
+    };
+}
+/** The coded not-configured message, actionable for model and user alike. */
+const NOT_FOUND = `${ErrorCode.TestCommandNotFound}: no test command found — package.json has no usable ` +
+    "`scripts.test` and `test.command` is not configured. Ask the user to set `test.command` " +
+    '(e.g. `cruxy config set test.command "pnpm test"`); do not guess a command.';

package/dist/testing/runner.d.ts

@@ -0,0 +1,26 @@
+import type { TestRunner, TestRunOptions, TestRunResult } from "./types.js";
+/**
+ * The shipped {@link TestRunner}: spawn the command via the system shell (the
+ * same detached-group + kill-tree discipline as `run_command`), capture a
+ * TAIL-biased, byte-capped transcript (failures live at the end of test
+ * output), and derive `passed` from the exit code — the only source of truth.
+ * A timeout, a signal kill, or a spawn error is a *failed result*, never a
+ * thrown exception and never a fabricated success.
+ */
+export declare class CommandTestRunner implements TestRunner {
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}
+/**
+ * A rolling, tail-biased capture: whole chunks are dropped from the FRONT
+ * once the byte cap is exceeded, so the end of the output — where test
+ * runners print their failure summaries — always survives.
+ */
+export declare class TailCapture {
+    private readonly cap;
+    private chunks;
+    private bytes;
+    truncated: boolean;
+    constructor(cap: number);
+    push(buf: Buffer): void;
+    text(): string;
+}

package/dist/testing/runner.js

@@ -0,0 +1,124 @@
+import { spawn } from "node:child_process";
+import { parseFailures } from "./parse.js";
+/**
+ * The shipped {@link TestRunner}: spawn the command via the system shell (the
+ * same detached-group + kill-tree discipline as `run_command`), capture a
+ * TAIL-biased, byte-capped transcript (failures live at the end of test
+ * output), and derive `passed` from the exit code — the only source of truth.
+ * A timeout, a signal kill, or a spawn error is a *failed result*, never a
+ * thrown exception and never a fabricated success.
+ */
+export class CommandTestRunner {
+    run(command, opts) {
+        const startedAt = Date.now();
+        return new Promise((resolve) => {
+            const capture = new TailCapture(opts.captureBytes);
+            let child;
+            try {
+                child = spawn(command, {
+                    shell: true,
+                    cwd: opts.cwd,
+                    detached: true,
+                });
+            }
+            catch (err) {
+                resolve(failed(null, err.message, startedAt));
+                return;
+            }
+            child.stdout?.on("data", (buf) => capture.push(buf));
+            child.stderr?.on("data", (buf) => capture.push(buf));
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                killTree(child.pid);
+                resolve(failed(null, capture.text() +
+                    `\n… [test run timed out after ${opts.timeoutMs}ms and was killed]`, startedAt, capture.truncated));
+            }, opts.timeoutMs);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(failed(null, err.message, startedAt));
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const output = capture.text();
+                // THE honest-green rule: exit code 0 and nothing else means passed.
+                // `code` is null on a signal kill — a failure, whatever the output says.
+                const passed = code === 0;
+                const parsed = passed ? { failures: [] } : parseFailures(output);
+                resolve({
+                    passed,
+                    exitCode: code,
+                    durationMs: Date.now() - startedAt,
+                    ...(parsed.total !== undefined ? { total: parsed.total } : {}),
+                    failures: parsed.failures,
+                    output,
+                    outputTruncated: capture.truncated,
+                });
+            });
+        });
+    }
+}
+/** Shape a non-execution failure (spawn error, timeout) as a failed result. */
+function failed(exitCode, output, startedAt, truncated = false) {
+    return {
+        passed: false,
+        exitCode,
+        durationMs: Date.now() - startedAt,
+        failures: [],
+        output,
+        outputTruncated: truncated,
+    };
+}
+/**
+ * A rolling, tail-biased capture: whole chunks are dropped from the FRONT
+ * once the byte cap is exceeded, so the end of the output — where test
+ * runners print their failure summaries — always survives.
+ */
+export class TailCapture {
+    cap;
+    chunks = [];
+    bytes = 0;
+    truncated = false;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    push(buf) {
+        this.chunks.push(buf);
+        this.bytes += buf.length;
+        // Drop head chunks while the REMAINDER still meets the cap.
+        while (this.chunks.length > 1 &&
+            this.bytes - this.chunks[0].length >= this.cap) {
+            this.bytes -= this.chunks[0].length;
+            this.chunks.shift();
+            this.truncated = true;
+        }
+    }
+    text() {
+        let all = Buffer.concat(this.chunks);
+        if (all.length > this.cap) {
+            all = all.subarray(all.length - this.cap);
+            this.truncated = true;
+        }
+        const body = all.toString("utf8");
+        return this.truncated ? `… [earlier output truncated]\n${body}` : body;
+    }
+}
+/** Kill the whole process group (POSIX; matches run_command's behavior). */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/testing/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Types for the test-execution loop (C.13): run the project's test suite,
+ * parse what's honestly parseable, and let the agent iterate on failures
+ * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
+ * derived from the exit code and nothing else.**
+ */
+/** A resolved test command and where it came from — shown, never guessed. */
+export interface TestCommand {
+    command: string;
+    source: "config" | "package-json";
+}
+/** One extracted failure. Every field beyond `name`/`message` is best-effort. */
+export interface TestFailure {
+    name: string;
+    message: string;
+    file?: string;
+    line?: number;
+}
+/** The structured outcome of one test-suite execution. */
+export interface TestRunResult {
+    /** `exitCode === 0`, full stop — never inferred from output text. */
+    passed: boolean;
+    /** The command's exit code; `null` when killed by signal or never spawned. */
+    exitCode: number | null;
+    /** Measured wall time of the execution. */
+    durationMs: number;
+    /** Total tests, only when a parser confidently extracted it. */
+    total?: number;
+    /** Best-effort extracted failures; may be empty even when `passed` is false. */
+    failures: TestFailure[];
+    /** Tail-biased captured stdout+stderr, capped at `test.captureBytes`. */
+    output: string;
+    /** Whether the head of the output was dropped to honor the byte cap. */
+    outputTruncated: boolean;
+}
+/** Execution bounds handed to a runner per run. */
+export interface TestRunOptions {
+    cwd: string;
+    /** Kill the run (and its process tree) after this many ms. */
+    timeoutMs: number;
+    /** Cap on captured output bytes (tail-biased). */
+    captureBytes: number;
+}
+/**
+ * The swappable execution seam (same discipline as VectorStore/ForgeProvider):
+ * the shipped {@link CommandTestRunner} spawns the command via the system
+ * shell; tests inject fakes, and a future framework-native runner (e.g. a
+ * vitest API runner) slots in without touching the tool.
+ */
+export interface TestRunner {
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}
+/**
+ * A pluggable best-effort failure extractor: given the captured output,
+ * return whatever structure it can positively recognize — and nothing it
+ * can't. Parsers never touch `passed` and never fabricate counts.
+ */
+export type FailureParser = (output: string) => {
+    failures: TestFailure[];
+    total?: number;
+};

package/dist/testing/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the test-execution loop (C.13): run the project's test suite,
+ * parse what's honestly parseable, and let the agent iterate on failures
+ * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
+ * derived from the exit code and nothing else.**
+ */
+export {};

package/dist/tools/registry.js

@@ -3,6 +3,7 @@ import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
+import { makeRunTestsTool } from "../testing/run-tests-tool.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
 import { loadSkillTool } from "./load-skill.js";
@@ -63,6 +64,8 @@ export function buildDefaultRegistry() {
     registry.register(grepFilesTool);
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
+    // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
+    registry.register(makeRunTestsTool());
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);

package/dist/tools/types.d.ts

@@ -101,10 +101,10 @@ export type ActionPreview =
  */
 export interface ApproveAction {
     /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback";
+    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback" | "test";
     /** Absolute resolved path the action targets (write/edit). */
     path?: string;
-    /** The command to run (shell). */
+    /** The command to run (shell / test). */
     command?: string;
     /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
     preview?: ActionPreview;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {