@cruxy/cli 1.11.2 → 1.11.3

package/dist/tools/shell/exec.js

@@ -33,6 +33,7 @@ export function execShell(command, ctx) {
  * throw coded errors from `sandbox.exec` and propagate — never caught here). */
 async function runSandboxed(command, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    const startedAt = Date.now();
     const result = await ctx.sandbox.exec(command, {
         cwd: ctx.cwd,
         timeoutMs,
@@ -45,11 +46,13 @@ async function runSandboxed(command, ctx) {
         signal: null,
         output: result.output,
         truncated: result.outputTruncated,
+        durationMs: Date.now() - startedAt,
     };
 }
 /** Spawn the command on the host, capture bounded output, enforce the timeout. */
 function runBounded(command, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    const startedAt = Date.now();
     return new Promise((resolve) => {
         // `spawnShell` routes through the resolved shell (POSIX default shell, Git
         // Bash, or PowerShell — see resolve-shell.ts) as the head of a killable tree
@@ -96,6 +99,7 @@ function runBounded(command, ctx) {
                 signal: null,
                 output: "",
                 truncated,
+                durationMs: Date.now() - startedAt,
             });
         }, timeoutMs);
         // External cancellation (C.33): a cancelled sibling's in-flight command is
@@ -114,6 +118,7 @@ function runBounded(command, ctx) {
                 signal: "SIGKILL",
                 output: Buffer.concat(chunks).toString("utf8"),
                 truncated,
+                durationMs: Date.now() - startedAt,
             });
         }
         if (abortSignal?.aborted) {
@@ -136,6 +141,7 @@ function runBounded(command, ctx) {
                 output: "",
                 truncated: false,
                 spawnError: err.message,
+                durationMs: Date.now() - startedAt,
             });
         });
         child.on("close", (code, closeSignal) => {
@@ -150,6 +156,7 @@ function runBounded(command, ctx) {
                 signal: closeSignal ?? null,
                 output: Buffer.concat(chunks).toString("utf8"),
                 truncated,
+                durationMs: Date.now() - startedAt,
             });
         });
     });

package/dist/tools/shell/run-command.js

@@ -9,27 +9,51 @@ import { runGatedShell } from "./exec.js";
  * C.19 hook runner — the single, un-bypassable shell path); this tool only maps
  * the structured result back onto its `ToolResult` framing.
  */
-export const runCommandTool = {
-    name: "run_command",
-    description: "Run a shell command in the project root and return its exit code, stdout, and stderr. Use this for builds, tests, linters, and git. Prefer the dedicated file tools (read_file/write_file/edit_file) over shelling out to cat/sed/echo for inspecting or editing files. A non-zero exit is still returned so you can react to the failure output.",
-    parameters: z.object({
-        command: z
-            .string()
-            .describe("The shell command to run (executed via the system shell)."),
-    }),
-    async execute(input, ctx) {
-        // A thrown CRUXY_E_APPROVAL_REQUIRED (non-interactive) / sandbox coded error
-        // propagates from runGatedShell — do not catch (fail loud).
-        const outcome = await runGatedShell(input.command, ctx);
-        if (!outcome.approved) {
-            return {
-                ok: false,
-                error: outcome.rejection ?? "command denied by the user",
-            };
-        }
-        return mapExecResult(outcome.exec, ctx);
-    },
-};
+/** Build the `run_command` tool. `deps.onResult` is the record's seam. */
+export function makeRunCommandTool(deps = {}) {
+    return {
+        name: "run_command",
+        description: "Run a shell command in the project root and return its exit code, stdout, and stderr. Use this for builds, tests, linters, and git. Prefer the dedicated file tools (read_file/write_file/edit_file) over shelling out to cat/sed/echo for inspecting or editing files. A non-zero exit is still returned so you can react to the failure output.",
+        parameters: z.object({
+            command: z
+                .string()
+                .describe("The shell command to run (executed via the system shell)."),
+        }),
+        async execute(input, ctx) {
+            // A thrown CRUXY_E_APPROVAL_REQUIRED (non-interactive) / sandbox coded error
+            // propagates from runGatedShell — do not catch (fail loud).
+            const outcome = await runGatedShell(input.command, ctx);
+            if (!outcome.approved) {
+                return {
+                    ok: false,
+                    error: outcome.rejection ?? "command denied by the user",
+                };
+            }
+            const exec = outcome.exec;
+            // Report from the same object the model's string is built from — and only
+            // when something ran. A spawn error never started, so there is no run.
+            if (exec.spawnError === undefined) {
+                try {
+                    deps.onResult?.({
+                        command: input.command,
+                        exitCode: exec.exitCode,
+                        timedOut: exec.timedOut,
+                        durationMs: exec.durationMs,
+                        outputTruncated: exec.truncated,
+                        substrate: ctx.sandbox ? "sandbox" : "host",
+                    });
+                }
+                catch {
+                    // A recording problem is not a command problem.
+                }
+            }
+            return mapExecResult(exec, ctx);
+        },
+    };
+}
+/** The default instance — no observer. Registries that record build their own
+ * via {@link makeRunCommandTool}; everything else is byte-identical. */
+export const runCommandTool = makeRunCommandTool();
 /**
  * Map a {@link ShellExecResult} onto the tool's `ToolResult` — the same "exit
  * code N" framing, truncation note, and timeout / spawn-error messages as

package/dist/vcs/generate.js

@@ -1,3 +1,4 @@
+import { verificationMarkdown } from "../verification/view.js";
 /**
  * Turn a diff + session context into the PR publish content (C.15): a
  * conventional-commit subject, a structured body, a branch name, and the PR
@@ -8,6 +9,14 @@
  *
  * Secrets never leave: the diff is redacted before the LLM sees it, and the
  * generated bodies are redacted again (defense-in-depth).
+ *
+ * The `## Verification` section is the record's, on BOTH paths (P2
+ * verification). The model is handed a diff; it has no way to know what ran,
+ * and asking it to write that section produced the same manufactured claim
+ * cli#309 removed from the fallback body, one layer up. So the prompt no
+ * longer asks for it, `finalize` drops one the model writes anyway, and the
+ * section that does appear is built here from `GenerateInput.verification` —
+ * the runs that actually executed, with their exit codes and timestamps.
  */
 /** Conventional-commit types accepted by `@commitlint/config-conventional`. */
 export const CONVENTIONAL_TYPES = [
@@ -183,11 +192,19 @@ export async function generateWithLlm(provider, input, opts = {}) {
 /** Shared final assembly: normalize the subject, redact bodies, pick a branch. */
 function finalize(rawSubject, rawBody, input, extra = {}) {
     const commitSubject = normalizeSubject(rawSubject, input.scopes);
-    const body = redactSecrets((rawBody ?? extra.prBody ?? "").trim() ||
-        assembleBody({
-            what: rawSubject || commitSubject,
-            verification: "`pnpm -r typecheck && pnpm lint && pnpm -r test`",
-        }));
+    // The body's prose is the caller's or the model's; its `## Verification`
+    // section is the record's. Any such section in the supplied body is dropped
+    // first — the deterministic guarantee, same posture as `normalizeSubject`:
+    // the prompt says not to write one, and this holds even if the model slips.
+    // When no body was supplied, the fallback carries ONLY what is known: the
+    // subject. (It used to add a Verification section naming a typecheck + lint
+    // + test command on every PR, whether or not anything ran — cli#309.) Then
+    // the record's section is appended, when there is a record: a body that
+    // names what ran comes only from something that knows what ran, and a
+    // missing section is the honest shape for missing evidence.
+    const prose = stripVerificationSection((rawBody ?? extra.prBody ?? "").trim()) ||
+        assembleBody({ what: rawSubject || commitSubject });
+    const body = redactSecrets(withRecordedVerification(prose, input.verification));
     const commitBody = redactSecrets((extra.commitBody ?? rawBody ?? "").trim());
     const branchName = input.currentBranch ??
         sanitizeBranch(extra.branchName) ??
@@ -200,6 +217,31 @@ function finalize(rawSubject, rawBody, input, extra = {}) {
         prBody: body,
     };
 }
+/**
+ * Drop a `## Verification` section — its heading through the line before the
+ * next `## ` heading, or the end — from a markdown body. Only the H2 shape the
+ * prompt itself describes is recognised; nothing else in the prose is touched.
+ */
+export function stripVerificationSection(markdown) {
+    const out = [];
+    let dropping = false;
+    for (const line of markdown.split("\n")) {
+        if (/^##\s/.test(line))
+            dropping = /^##\s+verification\b/i.test(line);
+        if (!dropping)
+            out.push(line);
+    }
+    return out.join("\n").trim();
+}
+/** Append the record's `## Verification` section, when there is a record. */
+function withRecordedVerification(body, verification) {
+    if (!verification)
+        return body;
+    const md = verificationMarkdown(verification.runs, {
+        ...(verification.from ? { from: verification.from } : {}),
+    });
+    return md === null ? body : `${body}\n\n## Verification\n\n${md}`;
+}
 /** Accept a model-proposed branch only if it's a plausible ref; else null. */
 function sanitizeBranch(name) {
     if (!name)
@@ -251,7 +293,7 @@ function buildSystemPrompt(input) {
     if (input.scopes.length > 0) {
         lines.push(`- If you use a scope, it must be one of: ${input.scopes.join(", ")}.`);
     }
-    lines.push("", "prBody: GitHub-flavored markdown with sections '## What changed', '## Why', '## Verification'.", "branchName: short kebab-case `type/slug`, no spaces.", "Never include secrets, tokens, or credentials in any field.");
+    lines.push("", "prBody: GitHub-flavored markdown with sections '## What changed' and '## Why'.", "Do NOT write a '## Verification' section, and do not state what was run, tested, built, or checked anywhere in prBody or commitBody:", "you have the diff, not the record of what executed. That section is appended afterwards from cruxy's record of the commands that actually ran, and one you write is dropped.", "branchName: short kebab-case `type/slug`, no spaces.", "Never include secrets, tokens, or credentials in any field.");
     if (input.skillBody) {
         lines.push("", "Repository commit conventions (authoritative):", input.skillBody);
     }

package/dist/verification/index.js

@@ -0,0 +1,15 @@
+/**
+ * The verification record (P2 verification): evidence of what ran and how it
+ * exited, keyed to the turn it ran in. Evidence, not enforcement — see
+ * `types.ts` for why that decision stands.
+ *
+ *  - `types.ts`  — the record shapes and the honesty rules;
+ *  - `ledger.ts` — the in-memory side a live session's surfaces read;
+ *  - `view.ts`   — the one formatter every surface shares.
+ *
+ * The durable side is the session log (`session/types.ts`: `verification` and
+ * `external-change` events), written from the same call as the ledger.
+ */
+export * from "./types.js";
+export * from "./ledger.js";
+export * from "./view.js";

package/dist/verification/ledger.js

@@ -0,0 +1,99 @@
+import { MAX_FAILURE_NAMES, } from "./types.js";
+/**
+ * The in-memory side of the verification record — what the surfaces of a LIVE
+ * session read. The durable side is the session log, reached through `sink`.
+ *
+ * The split mirrors `Session.lastRun` against the usage store: the process
+ * keeps the few facts its own surfaces ask for (this turn's runs for the
+ * one-shot summary, the last run for `/status`), and the log keeps everything
+ * for as long as the session survives retention. Neither re-derives from the
+ * other; both are written from the same call.
+ *
+ * ONE LEDGER PER SESSION, shared by every tool instance and every subagent
+ * the session drives. A subagent's test run is still a run that happened in
+ * this turn, and a fan-out's refused write is still a file that moved.
+ */
+export class VerificationLedger {
+    deps;
+    last;
+    /** Runs recorded this session, oldest first, bounded (see `SESSION_CAP`). */
+    runs = [];
+    turnRuns = [];
+    turnChanges = [];
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    /**
+     * A new user turn begins: this turn's lists start empty. The session-wide
+     * facts (`lastVerification`, `sessionRuns`) are untouched — a run from an
+     * earlier turn is still the last thing that ran.
+     */
+    beginTurn() {
+        this.turnRuns = [];
+        this.turnChanges = [];
+    }
+    /**
+     * Record one observation: stamp it, keep it, and hand it to the sink.
+     *
+     * The sink is wrapped because a recording problem is not a test-run problem.
+     * The run already happened and its result is on its way to the model; a
+     * session log that cannot write must degrade to "not saved", never fail the
+     * tool call that produced the fact.
+     */
+    record(obs) {
+        const at = this.deps.now?.() ?? new Date().toISOString();
+        if (obs.kind === "verification") {
+            const rec = {
+                ...withoutKind(obs),
+                failureNames: obs.failureNames.slice(0, MAX_FAILURE_NAMES),
+                at,
+            };
+            this.last = rec;
+            this.turnRuns.push(rec);
+            this.runs.push(rec);
+            if (this.runs.length > SESSION_CAP)
+                this.runs.shift();
+        }
+        else {
+            this.turnChanges.push({ ...withoutKind(obs), at });
+        }
+        try {
+            this.deps.sink?.(obs);
+        }
+        catch {
+            // Persistence is not allowed to fail the run it is recording.
+        }
+    }
+    /**
+     * Adopt the last run a resumed session's log recorded, so `/status` after
+     * `--resume` shows it rather than "none this session". Absent when the log
+     * pre-dates the record — absence is "not recorded", never "did not happen".
+     */
+    seed(last) {
+        if (!last)
+            return;
+        this.last = last;
+        this.runs = [last];
+    }
+    /** The most recent run that executed, this session (or seeded on resume). */
+    get lastVerification() {
+        return this.last;
+    }
+    /** Every run recorded this session, oldest first, bounded. */
+    sessionRuns() {
+        return this.runs;
+    }
+    /** What THIS turn recorded — the one-shot summary's unit. */
+    turn() {
+        return { verifications: this.turnRuns, externalChanges: this.turnChanges };
+    }
+}
+/** Most runs kept in memory per session. The log keeps the rest. */
+export const SESSION_CAP = 50;
+/** The observation minus its discriminant — the record is what happened, and
+ * `kind` was only ever the routing tag. */
+function withoutKind(obs) {
+    const copy = { ...obs };
+    delete copy.kind;
+    return copy;
+}

package/dist/verification/types.js

@@ -0,0 +1,26 @@
+/**
+ * The verification record (P2 verification): what ran, and how it exited.
+ *
+ * The loop's only completion criterion is "the model emitted no tool calls"
+ * (`agent/loop.ts`). Nothing checks that tests ran, a build passed, or a diff
+ * was reviewed, and the system prompt's instruction to verify is exactly that:
+ * an instruction. This module makes the absence VISIBLE without making the
+ * presence MANDATORY — C.13 shipped voluntary verification and delegated the
+ * iteration to the ordinary loop, and that decision stands. Three reasons it
+ * is not reversed here:
+ *
+ *  - `run_tests`' failing-run breaker latches for the turn after
+ *    `test.maxIterations` runs, so a turn that MUST end green could never end.
+ *  - A project with no test command has no defensible verdict: the coded
+ *    not-found error already tells the model to ask the user, not to guess.
+ *  - Enforcement changes the one-shot exit contract — "completed but
+ *    unverified" would be a new stop kind, and CI reads that exit code today.
+ *
+ * So this is EVIDENCE: a record of each run that actually executed, keyed to
+ * the turn it ran in, read back by the surfaces a user checks afterwards. What
+ * it never does is INFER. `passed` is the exit code and nothing else; nothing
+ * here decides that a command was "a build" or "the tests" from its text. The
+ * record says what ran and how it exited; the reader judges.
+ */
+/** Most failure names kept per record — an index, not a transcript. */
+export const MAX_FAILURE_NAMES = 5;

package/dist/verification/view.js

@@ -0,0 +1,87 @@
+import { formatDuration } from "../render/test-view.js";
+/**
+ * Rendering the verification record — the shared formatter behind every
+ * surface that reads it, so the one-shot summary, `/status`, the resume
+ * notice and the PR body all describe a run the same way.
+ *
+ * The honesty rules are `verification/types`'s, carried through rather than
+ * re-derived: the exit code is the fact, the tool and command are named as
+ * they ran, and nothing here calls a run "the build" or "the tests" from its
+ * text. A non-zero exit is shown as that exit — never as "1 test failed"
+ * unless a parser actually counted one.
+ */
+/** `run_tests pnpm test → exit 0 (4.2s)`, coloured by exit. */
+export function describeRun(rec, t) {
+    const exit = rec.exitCode === null ? "no exit code" : `exit ${rec.exitCode}`;
+    const verdict = rec.passed ? t.muted(exit) : t.danger(exit);
+    const counts = countClause(rec);
+    return (`${t.muted(rec.tool)} ${rec.command} ${t.glyph.arrow} ${verdict}` +
+        (counts ? ` ${t.danger(counts)}` : "") +
+        ` ${t.muted(`(${formatDuration(rec.durationMs)})`)}`);
+}
+/** "3 of 128 failed" / "3 failures" / "" — only what a parser actually counted. */
+function countClause(rec) {
+    if (rec.passed)
+        return "";
+    if (rec.total !== undefined && rec.failureCount > 0)
+        return `${rec.failureCount} of ${rec.total} failed`;
+    if (rec.failureCount > 0)
+        return `${rec.failureCount} failure${rec.failureCount === 1 ? "" : "s"}`;
+    return "";
+}
+/**
+ * The one-shot summary's block (the CI reader). Printed next to the exit code
+ * CI already trusts, for BOTH a completed run and one that gave up, so the
+ * line that says "completed" is never read on its own.
+ *
+ * "none ran this turn" is a sentence, not an omitted row: the whole point of
+ * the record is that the absence of verification is visible.
+ */
+export function verificationTurnLines(turn, t) {
+    const lines = [];
+    const key = t.strong("verification");
+    if (turn.verifications.length === 0) {
+        lines.push(`${key} ${t.warning("none ran this turn")}`);
+    }
+    else {
+        turn.verifications.forEach((rec, i) => {
+            lines.push(`${i === 0 ? key : " ".repeat(12)} ${describeRun(rec, t)}`);
+        });
+    }
+    turn.externalChanges.forEach((change, i) => {
+        lines.push(`${i === 0 ? t.strong("refused") : " ".repeat(7)} ${t.warning(`${change.path} ${change.what} — nothing was written`)}`);
+    });
+    return lines;
+}
+/**
+ * The `## Verification` section for a PR body, from the runs a session
+ * recorded — newest first, with their timestamps, so a run from before the
+ * last edit is dated rather than presented as current. Returns `null` when
+ * nothing ran: a missing section is the honest shape for missing evidence.
+ *
+ * `from` names where the runs were read from when it is NOT the live session
+ * — `cruxy pr` runs outside any session and reads the project's latest log —
+ * so the header never says "this session" about a session that has ended.
+ */
+export function verificationMarkdown(runs, opts = {}) {
+    if (runs.length === 0)
+        return null;
+    const shown = [...runs].reverse().slice(0, opts.limit ?? MARKDOWN_LIMIT);
+    const items = shown.map((rec) => {
+        const exit = rec.exitCode === null ? "no exit code" : `exit ${rec.exitCode}`;
+        const counts = countClause(rec);
+        return (`- \`${rec.command}\` — ${exit}${counts ? ` (${counts})` : ""}, ` +
+            `${formatDuration(rec.durationMs)}, via ${rec.tool} at ${rec.at}`);
+    });
+    const omitted = runs.length - shown.length;
+    return [
+        `Runs recorded by cruxy ${opts.from ?? "this session"}, newest first (exit codes as observed; nothing inferred):`,
+        "",
+        ...items,
+        ...(omitted > 0
+            ? ["", `…and ${omitted} earlier run${omitted === 1 ? "" : "s"}.`]
+            : []),
+    ].join("\n");
+}
+/** Most runs listed in a PR body. */
+export const MARKDOWN_LIMIT = 8;

package/package.json

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