@lannguyensi/harness 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-06-09
+
+**Headline: a security-driven release that closes two gate-bypasses.** A read-only-bash classifier hole let `command rm -rf /` and `env FOO=bar rm -rf /` run as "read-only" past the hard Understanding Gate, and the branch-protection override could be self-blessed by an agent-writable ledger ACK. Both are now closed: command runners recurse-classify their nested argv, and the branch-protection override is an operator-only canonical marker (new `harness approve branch-protection` verb), mirroring the understanding gate. Also bundled: a vitest CVE bump, clearer gate-block messages surfaced by dogfooding, and a `SOLUTION_VERDICT_ID` knob for solo sessions. **Operator action**: none required, back-compat. Re-run `npm i -g @lannguyensi/harness` to upgrade.
+
+### Added
+
+- **`solution-acceptance`: `SOLUTION_VERDICT_ID` env knob for solo / non-agent-tasks sessions** (task 01435583, PR #272): the completion-gate derived the verdict id solely from the agent-tasks `active-claim`, so a session that never calls `task_start` was permanently blocked with "no active-claim". It now falls back to a `SOLUTION_VERDICT_ID` env var when no claim is present. Resolution order is active-claim first, then `SOLUTION_VERDICT_ID`, then fail-closed, so a claimed session's id stays authoritative and cannot be redirected by the env (a sessionId fallback is still intentionally absent). The env value is validated as a safe single path segment; a malformed value fails closed. Set it to the same id you pass to `mcp__agent-grounding__solution_evaluate({ id })`.
+
+### Changed
+
+- **Gate-block messages are clearer about preflight ordering, mode-aware wording, and the approve escape hatch** (PR #274), surfaced by dogfooding the gates. `preflight-before-investigation` / `preflight-before-push` `ux.required` now note that `harness preflight` is itself gated by the Understanding Gate, so the "Run: harness preflight" remedy no longer dead-ends when the report is not yet approved. A new `understandingApprovalRequirement(mode)` helper derives the understanding `ux.required` phrase from the mode (only `strict` says "a human-approved Understanding Report"; `fast_confirm` / `grill_me` stay "an approved Understanding Report"); no output change for current `grill_me` profiles. `approveEscapeHint()` appends a targeted hint when a blocked Bash command starts with `harness approve` but trips the (unchanged) metachar guard, telling the agent to re-run it bare; the understanding `ux.run` line gains the same "(bare, no pipes, chaining, or redirection)" guidance.
+
+### Security
+
+- **Command runners `env` / `command` no longer bypass the hard gate** (HIGH audit finding, PR #271). The read-only-bash classifier listed `env` and `command` in `SIMPLE_READ_ONLY_BINS`, so the gate treated `command rm -rf /tmp/x` and `env FOO=bar rm -rf /` as read-only and allowed them without an approved Understanding Report, a hard-gate bypass across `hook-pre-tool-use`, `hook-codex-pre-tool-use`, and `hook-solution-acceptance-writeguard`. Both binaries are command runners (their argv is itself a nested command); they are removed from the simple set and given a find-style special case that strips the runner's own leading flags/assignments and recurse-classifies the residual underlying command. Bare and lookup-only forms (`env`, `env -u X`, `command -v node`) stay read-only; `env -S` / `--split-string` fails closed since it re-parses a string into a fresh argv that defeats whitespace tokenization.
+
+- **branch-protection override is now an operator-only canonical marker** (MEDIUM audit finding #39, PR #275). The override was satisfied by any `branch-protection-ack` ledger entry, which an agent can self-write via `mcp__agent-grounding__ledger_add`, letting it bless its own protected-branch edit. The agent-writable ledger ACK is replaced with an operator-only canonical marker file under `harness.generated/.approvals/branch-protection-<sessionId>`, mirroring the understanding gate (`writeApprovalMarker` / `checkApprovalMarker`). A new operator verb `harness approve branch-protection` writes the marker and records the `branch-protection-ack` ledger row as a best-effort audit echo only. The blocker now reads the marker as the canonical override; the ledger tag alone no longer opens the gate.
+
+- **vitest bumped to `^4.1.4`** (CVE-2026-47429 / GHSA-5xrq-8626-4rwp, PR #273). vitest < 4.1.0 lets the UI server read and execute arbitrary files. vitest is a devDependency; the lockfile is regenerated.
+
 ## [0.32.0] - 2026-05-30
 
 **Headline: harness ships a new opt-in `solution-acceptance` policy pack that makes task completion EARNED from a real preflight run rather than self-attested.** The producer (`@lannguyensi/grounding-mcp` >= 0.3.2 `solution_evaluate`) records a HEAD-pinned verdict from a real `preflight run --json`; this pack gates the task-finishing tools (agent-tasks completion verbs + `git push` / `gh pr merge`) on a ready verdict at the current HEAD, and adds an anti-forgery write-guard so the agent cannot hand-write the verdict marker. **Operator action**: none required, back-compat. The pack is opt-in (`harness pack add solution-acceptance`, or flip the disabled exemplar in the full template); it needs `grounding-mcp` under `tools.mcp` and the `preflight` binary on PATH, and `harness validate` warns if you enable it without the producer. Re-run `npm i -g @lannguyensi/harness` to upgrade.

package/dist/cli/approve/branch-protection.d.ts

@@ -0,0 +1,69 @@
+import type { Manifest } from "../../schema/index.js";
+import { type LoaderOptions } from "../loader.js";
+export interface ApproveBranchProtectionOptions extends LoaderOptions {
+    /** Explicit session id (overrides $CLAUDE_CODE_SESSION_ID / $CLAUDE_SESSION_ID / $CODEX_SESSION_ID). */
+    session?: string;
+    /**
+     * Free-form note recorded in the audit ledger tag
+     * (`branch-protection-ack:<reason>`) so a later `harness audit` can read
+     * WHY the override fired. Optional; defaults to a generic note.
+     */
+    reason?: string;
+    /** Override the harness.generated/ directory (test injection). */
+    generatedDir?: string;
+    /** Override "now" for deterministic tests. */
+    now?: Date;
+    /** Override the actor recorded in the marker (default: harness-approve-cli). */
+    approvedBy?: string;
+    /** Inject a manifest (test); bypasses `loadManifest`. */
+    manifest?: Manifest;
+    /** Override the ledger writer (test). */
+    ledgerAdd?: (sessionId: string, content: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+}
+export interface ApproveBranchProtectionResult {
+    sessionId: string;
+    /** Where `sessionId` came from — surfaced so the operator can sanity-check it. */
+    sessionSource: "flag" | "env-claude-code" | "env-claude" | "env-codex" | "pending-approval";
+    /**
+     * Canonical gate-satisfying signal. `ok: false` means the marker file
+     * could not be written (rare: fs permission, missing parent dir) and the
+     * gate will still block on the next tool call. The CLI surfaces this as a
+     * hard error so the operator does not think they approved when they didn't.
+     */
+    marker: {
+        ok: true;
+        filePath: string;
+        approvedAt: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /** Best-effort audit echo. Never affects the gate decision. */
+    ledger: {
+        ok: boolean;
+        tag: string;
+        reason?: string;
+    };
+}
+/** The audit ledger tag content this verb records (best-effort only). */
+export declare function branchProtectionAckTag(reason: string): string;
+/**
+ * Resolve the target session id, write its canonical override marker, and
+ * record a best-effort audit ledger tag. Session id precedence mirrors
+ * `harness approve risk` tiers 1-5: explicit `--session`, then
+ * `$CLAUDE_CODE_SESSION_ID`, then `$CLAUDE_SESSION_ID` (legacy), then
+ * `$CODEX_SESSION_ID`, then the `.pending-approval` file the gate hook
+ * staged on its last block. There is no persisted-report tier: the
+ * branch-protection gate produces no persisted reports.
+ *
+ * Throws `HarnessExitError(EX_FAIL)` when no session id can be resolved. A
+ * marker write failure is surfaced in the result (not thrown) so the
+ * operator still learns the resolved id; a degraded ledger is likewise
+ * surfaced, never thrown.
+ */
+export declare function approveBranchProtection(opts?: ApproveBranchProtectionOptions): Promise<ApproveBranchProtectionResult>;

package/dist/cli/approve/branch-protection.js

@@ -0,0 +1,157 @@
+// `harness approve branch-protection [--session <id>]` CLI verb.
+//
+// The operator's deliberate blessing of a protected-branch edit (version
+// bumps, CI workflow patches, hotfixes) for one session. Audit finding
+// #39: the old override was a `branch-protection-ack:` ledger tag, but the
+// agent has direct `mcp__agent-grounding__ledger_add` access and could
+// self-write that tag to bless its own edit. This verb instead writes the
+// canonical operator-only approval MARKER under
+// `harness.generated/.approvals/branch-protection-<sessionId>` (the same
+// trust boundary the understanding gate uses: Edit / Write / Bash are all
+// gated from writing there, and no configured MCP server exposes a
+// filesystem write). The branch-protection blocker consults that marker.
+//
+// The `branch-protection-ack:<reason>` ledger row is still written, as a
+// best-effort AUDIT echo only, so `harness audit` / forensics keep a trail
+// of WHY the override fired. A degraded / absent grounding-mcp surfaces as
+// a warning, never a hard failure: the marker is what unblocks the gate.
+import { ACK_TAG_PREFIX, writeBranchProtectionMarker, } from "../../policy-packs/builtin/branch-protection-runtime.js";
+import { addLedgerFact } from "../../runtime/ledger-add.js";
+import { readPendingApproval, resolveGeneratedDir, } from "../../runtime/pending-approval.js";
+import { EX_FAIL, HarnessExitError } from "../exit-codes.js";
+import { loadManifest, resolvePaths } from "../loader.js";
+const DEFAULT_APPROVED_BY = "harness-approve-cli";
+const DEFAULT_REASON = "operator branch-protection override";
+function findGroundingMcp(manifest) {
+    return manifest.tools.mcp.find((m) => m.name === "grounding-mcp") ?? null;
+}
+/** The audit ledger tag content this verb records (best-effort only). */
+export function branchProtectionAckTag(reason) {
+    return `${ACK_TAG_PREFIX}:${reason}`;
+}
+async function writeLedgerTag(manifest, sessionId, content, opts) {
+    if (opts.ledgerAdd)
+        return opts.ledgerAdd(sessionId, content);
+    const server = findGroundingMcp(manifest);
+    if (!server) {
+        return { ok: false, reason: "grounding-mcp not declared in manifest" };
+    }
+    // No `~` expansion: `addLedgerFact` expands leading `~/` in every command
+    // token itself, so a second pass would be dead work.
+    const command = Array.isArray(server.command)
+        ? server.command
+        : server.command.trim().split(/\s+/);
+    return addLedgerFact({
+        mcpCommand: command,
+        ...(server.env && { mcpEnv: server.env }),
+        timeoutMs: server.health?.timeout_ms ?? 5_000,
+        sessionId,
+        content,
+        source: "harness-approve-branch-protection",
+    });
+}
+/**
+ * Resolve the target session id, write its canonical override marker, and
+ * record a best-effort audit ledger tag. Session id precedence mirrors
+ * `harness approve risk` tiers 1-5: explicit `--session`, then
+ * `$CLAUDE_CODE_SESSION_ID`, then `$CLAUDE_SESSION_ID` (legacy), then
+ * `$CODEX_SESSION_ID`, then the `.pending-approval` file the gate hook
+ * staged on its last block. There is no persisted-report tier: the
+ * branch-protection gate produces no persisted reports.
+ *
+ * Throws `HarnessExitError(EX_FAIL)` when no session id can be resolved. A
+ * marker write failure is surfaced in the result (not thrown) so the
+ * operator still learns the resolved id; a degraded ledger is likewise
+ * surfaced, never thrown.
+ */
+export async function approveBranchProtection(opts = {}) {
+    const generatedDir = opts.generatedDir ??
+        resolveGeneratedDir({
+            ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
+            manifestPath: resolvePaths(opts).base,
+        });
+    let sessionId = "";
+    let sessionSource = "flag";
+    if (typeof opts.session === "string" && opts.session.length > 0) {
+        sessionId = opts.session;
+        sessionSource = "flag";
+    }
+    else if (typeof process.env.CLAUDE_CODE_SESSION_ID === "string" &&
+        process.env.CLAUDE_CODE_SESSION_ID.length > 0) {
+        sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+        sessionSource = "env-claude-code";
+    }
+    else if (typeof process.env.CLAUDE_SESSION_ID === "string" &&
+        process.env.CLAUDE_SESSION_ID.length > 0) {
+        sessionId = process.env.CLAUDE_SESSION_ID;
+        sessionSource = "env-claude";
+    }
+    else if (typeof process.env.CODEX_SESSION_ID === "string" &&
+        process.env.CODEX_SESSION_ID.length > 0) {
+        sessionId = process.env.CODEX_SESSION_ID;
+        sessionSource = "env-codex";
+    }
+    else {
+        const staged = readPendingApproval(generatedDir);
+        if (staged !== null) {
+            sessionId = staged;
+            sessionSource = "pending-approval";
+        }
+    }
+    if (sessionId === "") {
+        throw new HarnessExitError([
+            "no session id available. Pass --session <id>, or set one of",
+            "$CLAUDE_CODE_SESSION_ID (Claude Code) / $CLAUDE_SESSION_ID (legacy) /",
+            "$CODEX_SESSION_ID (Codex).",
+            "",
+            "The branch-protection PreToolUse hook and `harness preflight` both stage the",
+            `session id in ${generatedDir}/.pending-approval, so an arg-less`,
+            "`harness approve branch-protection` works after either has fired. An empty result",
+            "means neither has run for the current session yet.",
+            "",
+            "From inside the running agent you can also read the id directly:",
+            "Claude Code exposes $CLAUDE_CODE_SESSION_ID; Codex exposes $CODEX_SESSION_ID.",
+        ].join("\n"), EX_FAIL);
+    }
+    // Write the canonical marker first — it is what unblocks the gate.
+    const approvedAt = (opts.now ?? new Date()).toISOString();
+    const approvedBy = opts.approvedBy ?? DEFAULT_APPROVED_BY;
+    let markerResult;
+    try {
+        const filePath = writeBranchProtectionMarker(generatedDir, sessionId, {
+            approvedAt,
+            approvedBy,
+        });
+        markerResult = { ok: true, filePath, approvedAt };
+    }
+    catch (err) {
+        markerResult = {
+            ok: false,
+            reason: `failed to write approval marker: ${err.message}`,
+        };
+    }
+    // Best-effort audit ledger echo. Loaded lazily so a missing / unparseable
+    // manifest degrades the audit row to a warning rather than aborting the
+    // marker-based approval.
+    let manifest = null;
+    try {
+        manifest = opts.manifest ?? loadManifest(opts).manifest;
+    }
+    catch {
+        /* swallow; ledger write becomes a degraded-ok */
+    }
+    const reason = opts.reason && opts.reason.trim().length > 0 ? opts.reason.trim() : DEFAULT_REASON;
+    const tag = branchProtectionAckTag(reason);
+    const ledgerResult = manifest
+        ? await writeLedgerTag(manifest, sessionId, tag, opts)
+        : { ok: false, reason: "manifest unreadable; skipped ledger write" };
+    return {
+        sessionId,
+        sessionSource,
+        marker: markerResult,
+        ledger: ledgerResult.ok
+            ? { ok: true, tag }
+            : { ok: false, tag, reason: ledgerResult.reason },
+    };
+}
+//# sourceMappingURL=branch-protection.js.map

package/dist/cli/approve/branch-protection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-protection.js","sourceRoot":"","sources":["../../../src/cli/approve/branch-protection.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -33,6 +33,7 @@ import { runPackHookCodexPreToolUseCli } from "./pack/hook-codex-pre-tool-use.js
 import { runPackHookCodexStopCli } from "./pack/hook-codex-stop.js";
 import { runPackHookCodexUserPromptSubmitCli } from "./pack/hook-codex-user-prompt-submit.js";
 import { isRuntime, KNOWN_RUNTIMES } from "../policy-packs/index.js";
+import { approveBranchProtection } from "./approve/branch-protection.js";
 import { approveRisk } from "./approve/risk.js";
 import { approveUnderstanding } from "./approve/understanding.js";
 import { describe, isPillar } from "./describe.js";
@@ -835,7 +836,8 @@ export function buildProgram(opts = {}) {
         .command("branch-protection")
         .description("PreToolUse blocker for the branch-protection pack: read tool-event JSON from stdin, consult the " +
         "evidence ledger, emit a deny envelope on protected branches unless either a fresh " +
-        "`branch:non-protected` tag (within 5m) or a `branch-protection-ack` override is present.")
+        "`branch:non-protected` tag (within 5m) or the operator-only override marker " +
+        "(written by `harness approve branch-protection`) is present.")
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
@@ -1170,6 +1172,58 @@ export function buildProgram(opts = {}) {
         }
         stdout(`${lines.join("\n")}\n`);
     });
+    approveCmd
+        .command("branch-protection")
+        .description("Bless a deliberate protected-branch edit for one session. Writes the canonical " +
+        "operator-only approval marker under harness.generated/.approvals/ that the " +
+        "branch-protection blocker consults, plus a best-effort branch-protection-ack " +
+        "ledger row for audit. Operator action: the marker (not the ledger tag) is the " +
+        "trusted override, because the ledger is agent-writable.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--session <id>", "explicit session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then $CODEX_SESSION_ID, then staged .pending-approval)")
+        .option("--reason <text>", "free-form note recorded in the audit ledger tag (why the override fired)")
+        .option("--approved-by <actor>", "actor to record on the marker (default: harness-approve-cli)")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.session)
+            cliOpts.session = options.session;
+        if (options.reason)
+            cliOpts.reason = options.reason;
+        if (options.approvedBy)
+            cliOpts.approvedBy = options.approvedBy;
+        const result = await approveBranchProtection(cliOpts);
+        const lines = [];
+        const sourceNote = result.sessionSource === "pending-approval"
+            ? " (resolved from .pending-approval staged by the gate hook)"
+            : result.sessionSource === "env-claude-code"
+                ? " (from $CLAUDE_CODE_SESSION_ID)"
+                : result.sessionSource === "env-claude"
+                    ? " (from $CLAUDE_SESSION_ID)"
+                    : result.sessionSource === "env-codex"
+                        ? " (from $CODEX_SESSION_ID)"
+                        : "";
+        lines.push(`session: ${result.sessionId}${sourceNote}`);
+        if (result.marker.ok) {
+            lines.push(`marker:  ✓ ${result.marker.filePath} (canonical gate signal)`);
+            lines.push("  the branch-protection gate now allows protected-branch edits for this session.");
+        }
+        else {
+            lines.push(`marker:  ✗ FAILED (${result.marker.reason})`);
+            lines.push("  the gate WILL keep blocking the next tool call until the marker exists.");
+        }
+        if (result.ledger.ok) {
+            lines.push(`ledger:  ✓ wrote ${result.ledger.tag} (audit only)`);
+        }
+        else {
+            lines.push(`ledger:  ⚠ skipped (${result.ledger.reason ?? "unknown"}) (audit only)`);
+        }
+        stdout(`${lines.join("\n")}\n`);
+    });
     const VALID_DECISION_FILTERS = [
         "allow",
         "warn",