@lannguyensi/harness 0.10.1 → 0.12.0

package/dist/cli/gate/enable.js

@@ -0,0 +1,127 @@
+// `harness gate enable` — restore the most recent `gate disable` snapshot.
+//
+// Reads the newest `harness.gate-disable.*.json` next to settings.json,
+// merges its `removed[]` groups back into `hooks[event][]` at their
+// original indices, and atomically rewrites settings.json. Refuses if
+// settings.json has been edited since the snapshot was taken (the
+// recorded `settingsAfterSha256` no longer matches the on-disk content)
+// unless `--force` is passed, so a hand-edit between disable and enable
+// is not silently overwritten. Idempotent on an already-restored file
+// (the snapshot's `settingsBeforeSha256` matches the current sha →
+// nothing to do).
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { listSnapshots, readSnapshot, sha256Hex, } from "./snapshot.js";
+const DEFAULT_SETTINGS_REL = path.join(".claude", "settings.json");
+export class GateEnableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GateEnableError";
+    }
+}
+function resolveSettingsPath(opts) {
+    if (typeof opts.settingsPath === "string" && opts.settingsPath.length > 0) {
+        return opts.settingsPath;
+    }
+    const home = opts.homeDir ?? os.homedir();
+    return path.join(home, DEFAULT_SETTINGS_REL);
+}
+function readCurrentSettings(settingsPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(settingsPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new GateEnableError(`settings file not found: ${settingsPath} — cannot restore into a missing target`);
+        }
+        throw new GateEnableError(`cannot read ${settingsPath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GateEnableError(`${settingsPath} is not valid JSON (${err.message}); refusing to operate.`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new GateEnableError(`${settingsPath} is not a JSON object; refusing to operate.`);
+    }
+    const obj = parsed;
+    const rawHooks = obj["hooks"];
+    let hooks = {};
+    if (rawHooks !== undefined) {
+        if (rawHooks === null || typeof rawHooks !== "object" || Array.isArray(rawHooks)) {
+            throw new GateEnableError(`${settingsPath} \`hooks\` field is not an object.`);
+        }
+        for (const [event, groups] of Object.entries(rawHooks)) {
+            if (!Array.isArray(groups)) {
+                throw new GateEnableError(`${settingsPath} \`hooks.${event}\` is not an array; refusing to operate.`);
+            }
+            hooks[event] = groups.slice();
+        }
+    }
+    return { raw, obj, hooks };
+}
+function reinsertRemoved(hooks, snapshot) {
+    // Sort removed entries by event, then by ascending index, so we splice
+    // them back in growing order — that way an earlier insertion never
+    // shifts a later insertion's target index past the array end.
+    const sorted = [...snapshot.removed].sort((a, b) => {
+        if (a.event !== b.event)
+            return a.event < b.event ? -1 : 1;
+        return a.index - b.index;
+    });
+    let inserted = 0;
+    for (const entry of sorted) {
+        const arr = hooks[entry.event] ?? [];
+        const idx = Math.min(entry.index, arr.length);
+        arr.splice(idx, 0, entry.group);
+        hooks[entry.event] = arr;
+        inserted += 1;
+    }
+    return inserted;
+}
+export function gateEnable(opts = {}) {
+    const settingsPath = resolveSettingsPath(opts);
+    const settingsDir = path.dirname(settingsPath);
+    const snapshotPaths = listSnapshots(settingsDir);
+    if (snapshotPaths.length === 0) {
+        return { mode: "no-snapshots", settingsPath };
+    }
+    const latest = snapshotPaths[0];
+    const readResult = readSnapshot(latest);
+    if (!readResult.ok) {
+        throw new GateEnableError(readResult.reason);
+    }
+    const snapshot = readResult.snapshot;
+    const current = readCurrentSettings(settingsPath);
+    const currentSha = sha256Hex(current.raw);
+    if (currentSha === snapshot.settingsBeforeSha256) {
+        // The current file already matches the pre-disable state: nothing
+        // to restore. Idempotent return.
+        return { mode: "already-restored", settingsPath, snapshotPath: latest };
+    }
+    if (currentSha !== snapshot.settingsAfterSha256 && !opts.force) {
+        throw new GateEnableError(`settings.json has been edited since the snapshot was taken (current sha ${currentSha.slice(0, 12)}…, ` +
+            `snapshot's post-disable sha ${snapshot.settingsAfterSha256.slice(0, 12)}…). ` +
+            `Re-running would overwrite those edits. Inspect the diff against ` +
+            `${snapshot.settingsBackupPath}, then pass --force to restore anyway.`);
+    }
+    const restoredCount = reinsertRemoved(current.hooks, snapshot);
+    const newObj = { ...current.obj };
+    if (Object.keys(current.hooks).length === 0) {
+        delete newObj["hooks"];
+    }
+    else {
+        newObj["hooks"] = current.hooks;
+    }
+    const newSettings = `${JSON.stringify(newObj, null, 2)}\n`;
+    atomicWriteFile(settingsPath, newSettings);
+    return { mode: "restored", settingsPath, snapshotPath: latest, restoredCount };
+}
+/** Test-helper: re-export for the test suite to inspect snapshot pickup. */
+export { listSnapshots };
+//# sourceMappingURL=enable.js.map

package/dist/cli/gate/enable.js.map

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

package/dist/cli/gate/snapshot.d.ts

@@ -0,0 +1,65 @@
+export declare const SNAPSHOT_BASENAME_PREFIX = "harness.gate-disable.";
+export declare const SNAPSHOT_BASENAME_SUFFIX = ".json";
+export declare const SNAPSHOT_VERSION: 1;
+export interface RemovedGroup {
+    /** Hook event the group lived under, e.g. "PreToolUse". */
+    event: string;
+    /** Position of the group inside `hooks[event][]` at the time of removal. */
+    index: number;
+    /** The literal JSON value of the removed group; preserved verbatim. */
+    group: unknown;
+}
+export interface GateDisableSnapshot {
+    version: typeof SNAPSHOT_VERSION;
+    /** ISO-8601 UTC timestamp of the disable call. */
+    createdAt: string;
+    /** Absolute path to the settings.json that was mutated. */
+    settingsPath: string;
+    /** Absolute path the pre-mutation copy was written to. */
+    settingsBackupPath: string;
+    /**
+     * SHA-256 of `settings.json` content BEFORE the removal. `gate enable`
+     * compares the live settings.json sha against this to detect operator
+     * edits since the disable; a mismatch refuses unless `--force`.
+     */
+    settingsBeforeSha256: string;
+    /** SHA-256 of `settings.json` content AFTER the removal. */
+    settingsAfterSha256: string;
+    /** The filter the operator applied — recorded for the audit trail. */
+    filter: {
+        matcher?: string;
+        event?: string;
+    };
+    /** Groups removed, in stable order (sorted by event then ascending index). */
+    removed: RemovedGroup[];
+}
+export declare function sha256Hex(input: string | Buffer): string;
+/**
+ * Build the snapshot file path for `settingsPath` at `now`. ISO timestamps
+ * use `-` in place of `:` so the filename is portable across filesystems
+ * (Windows reject `:` in basenames).
+ */
+export declare function snapshotPath(settingsPath: string, now: Date): string;
+/** Build the settings-backup file path for `settingsPath` at `now`. */
+export declare function backupPath(settingsPath: string, now: Date): string;
+/**
+ * Return all gate-disable snapshot paths in `settingsDir`, newest-first
+ * by mtime. Missing directory returns []. Any file that isn't a valid
+ * snapshot is silently skipped — `gate enable` re-parses the candidates
+ * and surfaces format errors at that point.
+ */
+export declare function listSnapshots(settingsDir: string): string[];
+export interface SnapshotReadOk {
+    ok: true;
+    snapshot: GateDisableSnapshot;
+}
+export interface SnapshotReadErr {
+    ok: false;
+    reason: string;
+}
+/**
+ * Parse a snapshot file. Validates structural shape only — the body's
+ * `removed[].group` payload is opaque (preserved verbatim from
+ * settings.json) and not re-validated against a hook schema.
+ */
+export declare function readSnapshot(filePath: string): SnapshotReadOk | SnapshotReadErr;

package/dist/cli/gate/snapshot.js

@@ -0,0 +1,119 @@
+// Snapshot file format + I/O for `harness gate disable` / `harness gate enable`.
+//
+// A snapshot is the on-disk record of one `gate disable` invocation. It
+// captures (a) which hook groups were removed and where they came from,
+// (b) the SHA-256 of `settings.json` immediately before and after the
+// removal, and (c) the path the original was backed up to. `gate enable`
+// reads the newest snapshot in the settings directory, refuses to restore
+// over a settings.json the operator has edited since (`--force` overrides),
+// and writes the removed groups back into place.
+//
+// The format is intentionally narrow: no compression, no transform, just
+// the literal JSON groups as they were read out of settings.json.
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const SNAPSHOT_BASENAME_PREFIX = "harness.gate-disable.";
+export const SNAPSHOT_BASENAME_SUFFIX = ".json";
+export const SNAPSHOT_VERSION = 1;
+export function sha256Hex(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Build the snapshot file path for `settingsPath` at `now`. ISO timestamps
+ * use `-` in place of `:` so the filename is portable across filesystems
+ * (Windows reject `:` in basenames).
+ */
+export function snapshotPath(settingsPath, now) {
+    const stamp = now.toISOString().replace(/:/g, "-");
+    return path.join(path.dirname(settingsPath), `${SNAPSHOT_BASENAME_PREFIX}${stamp}${SNAPSHOT_BASENAME_SUFFIX}`);
+}
+/** Build the settings-backup file path for `settingsPath` at `now`. */
+export function backupPath(settingsPath, now) {
+    const stamp = now.toISOString().replace(/:/g, "-");
+    return `${settingsPath}.bak.${stamp}`;
+}
+/**
+ * Return all gate-disable snapshot paths in `settingsDir`, newest-first
+ * by mtime. Missing directory returns []. Any file that isn't a valid
+ * snapshot is silently skipped — `gate enable` re-parses the candidates
+ * and surfaces format errors at that point.
+ */
+export function listSnapshots(settingsDir) {
+    let names;
+    try {
+        names = fs.readdirSync(settingsDir);
+    }
+    catch {
+        return [];
+    }
+    const candidates = [];
+    for (const name of names) {
+        if (!name.startsWith(SNAPSHOT_BASENAME_PREFIX))
+            continue;
+        if (!name.endsWith(SNAPSHOT_BASENAME_SUFFIX))
+            continue;
+        const full = path.join(settingsDir, name);
+        try {
+            const stat = fs.statSync(full);
+            if (!stat.isFile())
+                continue;
+            candidates.push({ filePath: full, mtimeMs: stat.mtimeMs });
+        }
+        catch {
+            continue;
+        }
+    }
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates.map((c) => c.filePath);
+}
+/**
+ * Parse a snapshot file. Validates structural shape only — the body's
+ * `removed[].group` payload is opaque (preserved verbatim from
+ * settings.json) and not re-validated against a hook schema.
+ */
+export function readSnapshot(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        return { ok: false, reason: `cannot read snapshot ${filePath}: ${err.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, reason: `snapshot ${filePath} is not valid JSON: ${err.message}` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, reason: `snapshot ${filePath} is not a JSON object` };
+    }
+    const obj = parsed;
+    if (obj["version"] !== SNAPSHOT_VERSION) {
+        return {
+            ok: false,
+            reason: `snapshot ${filePath} has unsupported version ${JSON.stringify(obj["version"])}; expected ${SNAPSHOT_VERSION}`,
+        };
+    }
+    for (const field of [
+        "createdAt",
+        "settingsPath",
+        "settingsBackupPath",
+        "settingsBeforeSha256",
+        "settingsAfterSha256",
+    ]) {
+        if (typeof obj[field] !== "string") {
+            return { ok: false, reason: `snapshot ${filePath} is missing string field "${field}"` };
+        }
+    }
+    if (typeof obj["filter"] !== "object" || obj["filter"] === null) {
+        return { ok: false, reason: `snapshot ${filePath} is missing object field "filter"` };
+    }
+    if (!Array.isArray(obj["removed"])) {
+        return { ok: false, reason: `snapshot ${filePath} is missing array field "removed"` };
+    }
+    return { ok: true, snapshot: obj };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/cli/gate/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/cli/gate/snapshot.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,4EAA4E;AAC5E,iDAAiD;AACjD,EAAE;AACF,yEAAyE;AACzE,kEAAkE;AAElE,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,CAAC,MAAM,wBAAwB,GAAG,uBAAuB,CAAC;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAoC3C,MAAM,UAAU,SAAS,CAAC,KAAsB;IAC9C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB,EAAE,GAAS;IAC1D,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,IAAI,CACd,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAC1B,GAAG,wBAAwB,GAAG,KAAK,GAAG,wBAAwB,EAAE,CACjE,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,YAAoB,EAAE,GAAS;IACxD,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,GAAG,YAAY,QAAQ,KAAK,EAAE,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,UAAU,GAAiD,EAAE,CAAC;IACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,wBAAwB,CAAC;YAAE,SAAS;QACzD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC;YAAE,SAAS;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;gBAAE,SAAS;YAC7B,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IACD,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC3C,CAAC;AAYD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,QAAQ,KAAM,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IAC9F,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,QAAQ,uBAAwB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IACpG,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,QAAQ,uBAAuB,EAAE,CAAC;IAC5E,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,IAAI,GAAG,CAAC,SAAS,CAAC,KAAK,gBAAgB,EAAE,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,YAAY,QAAQ,4BAA4B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,cAAc,gBAAgB,EAAE;SACvH,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI;QAClB,WAAW;QACX,cAAc;QACd,oBAAoB;QACpB,sBAAsB;QACtB,qBAAqB;KACtB,EAAE,CAAC;QACF,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,QAAQ,6BAA6B,KAAK,GAAG,EAAE,CAAC;QAC1F,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;QAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,QAAQ,mCAAmC,EAAE,CAAC;IACxF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,QAAQ,mCAAmC,EAAE,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAqC,EAAE,CAAC;AACvE,CAAC"}

package/dist/cli/index.js

@@ -27,6 +27,9 @@ import { audit } from "./audit.js";
 import { sessionExport } from "./session-export/index.js";
 import { dryRun } from "./dry-run.js";
 import { runInterceptCli } from "./policy/intercept.js";
+import { runSessionStartPreflight } from "./session-start/index.js";
+import { gateDisable, GateDisableError } from "./gate/disable.js";
+import { gateEnable, GateEnableError } from "./gate/enable.js";
 import { formatSmokeReport, runSmoke, splitCommaList, } from "./smoke/index.js";
 import { formatReport, validate } from "./validate/index.js";
 import { VERSION } from "../version.js";
@@ -783,7 +786,14 @@ export function buildProgram(opts = {}) {
             cliOpts.approvedBy = options.approvedBy;
         const result = await approveUnderstanding(cliOpts);
         const lines = [];
-        lines.push(`session: ${result.sessionId}`);
+        // Annotate non-explicit session sources so the operator can spot
+        // a wrong id before it lands in the ledger.
+        const sourceNote = result.sessionSource === "pending-approval"
+            ? " (resolved from .pending-approval staged by the gate hook)"
+            : result.sessionSource === "env"
+                ? " (from $CLAUDE_SESSION_ID)"
+                : "";
+        lines.push(`session: ${result.sessionId}${sourceNote}`);
         if (result.ledger.ok) {
             lines.push(`ledger:  ✓ wrote ${result.ledger.tag}`);
         }
@@ -983,6 +993,136 @@ export function buildProgram(opts = {}) {
             throw new HarnessExitError("", result.exitCode);
         }
     });
+    const sessionStart = program
+        .command("session-start")
+        .description("SessionStart hook entrypoints (called by Claude Code via settings.json)");
+    sessionStart
+        .command("preflight")
+        .description("SessionStart producer: run agent-preflight against the session cwd and, on a ready:true result, " +
+        "record a `preflight:${REPO}` fact to the evidence ledger so the preflight-before-* policies have a " +
+        "fresh tag to match. Reads SessionStart event JSON from stdin ({ session_id, cwd, hook_event_name }). " +
+        "blocking:false — every failure path logs to stderr and exits 0.")
+        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--session <id>", "explicit session id (overrides stdin event + env). Use for manual / scripted invocations " +
+        "where no SessionStart event JSON is piped on stdin. Without it the resolver tries " +
+        "stdin event → $CLAUDE_SESSION_ID → newest Claude Code transcript → 'default' (which logs " +
+        "a loud warning since the literal 'default' session never satisfies a preflight-before-* gate).")
+        .option("--timeout <ms>", "agent-preflight subprocess timeout in milliseconds (default 25000)")
+        .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
+        .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.timeout) {
+            const n = Number.parseInt(options.timeout, 10);
+            if (Number.isFinite(n) && n > 0)
+                cliOpts.preflightTimeoutMs = n;
+        }
+        if (options.ledgerTimeout) {
+            const n = Number.parseInt(options.ledgerTimeout, 10);
+            if (Number.isFinite(n) && n > 0)
+                cliOpts.ledgerTimeoutMs = n;
+        }
+        await runSessionStartPreflight(cliOpts);
+    });
+    // `harness gate` — operator escape hatch for hard-blocking hooks.
+    // Task 8fcddb26: the understanding-before-execution PreToolUse hook can
+    // lock a Claude session out of every Bash call, and the recommended
+    // recovery (`harness approve understanding`) is itself a Bash invocation
+    // and gets caught by the same gate. `gate disable` strips the
+    // offending hook group out of settings.json with a reversible snapshot.
+    const gate = program
+        .command("gate")
+        .description("Operator escape hatch: disable/restore hook groups in ~/.claude/settings.json");
+    gate
+        .command("disable")
+        .description("Remove hook groups from ~/.claude/settings.json whose `matcher` substring-matches " +
+        "`--matcher <pattern>`. Writes a snapshot of the removed groups next to settings.json " +
+        "(`harness.gate-disable.<ts>.json`) and backs up the original to `settings.json.bak.<ts>` " +
+        "so `harness gate enable` can restore them. With no `--matcher` flag, lists the candidate " +
+        "groups without writing.")
+        .option("--matcher <pattern>", "remove groups whose matcher includes this substring")
+        .option("--settings <path>", "override ~/.claude/settings.json")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.matcher)
+            cliOpts.matcher = options.matcher;
+        if (options.settings)
+            cliOpts.settingsPath = options.settings;
+        try {
+            const result = gateDisable(cliOpts);
+            if (result.mode === "list") {
+                if (result.candidates.length === 0) {
+                    stdout(`no hook groups in ${result.settingsPath}; nothing to disable.\n`);
+                    return;
+                }
+                stdout(`candidate hook groups in ${result.settingsPath}:\n`);
+                for (const c of result.candidates) {
+                    const matcherLabel = c.matcher === null ? "(no matcher)" : JSON.stringify(c.matcher);
+                    stdout(`  ${c.event}[${c.index}] matcher=${matcherLabel}: ${c.description}\n`);
+                }
+                stdout(`\nPass --matcher <substring> to remove a group. Removal is reversible via ` +
+                    `\`harness gate enable\`.\n`);
+                return;
+            }
+            stdout(`disabled ${result.removed.length} hook group(s) in ${result.settingsPath}:\n`);
+            for (const r of result.removed) {
+                const matcherLabel = r.group !== null && typeof r.group === "object" && !Array.isArray(r.group)
+                    ? JSON.stringify(r.group["matcher"] ?? null)
+                    : "null";
+                stdout(`  ${r.event}[${r.index}] matcher=${matcherLabel}\n`);
+            }
+            stdout(`backup:   ${result.backupPath}\n`);
+            stdout(`snapshot: ${result.snapshotPath}\n`);
+            stdout(`This is reversible: run \`harness gate enable\` to restore.\n`);
+        }
+        catch (err) {
+            if (err instanceof GateDisableError) {
+                throw new HarnessExitError(err.message, EX_FAIL);
+            }
+            throw err;
+        }
+    });
+    gate
+        .command("enable")
+        .description("Restore hook groups from the newest `harness.gate-disable.*.json` snapshot next to " +
+        "settings.json. Refuses if settings.json has been edited since the snapshot was taken " +
+        "(use `--force` to restore anyway). Idempotent: if settings.json already matches the " +
+        "pre-disable state, exits 0 without writing.")
+        .option("--settings <path>", "override ~/.claude/settings.json")
+        .option("--force", "restore even when settings.json has been edited since the snapshot")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.settings)
+            cliOpts.settingsPath = options.settings;
+        if (options.force)
+            cliOpts.force = true;
+        try {
+            const result = gateEnable(cliOpts);
+            if (result.mode === "no-snapshots") {
+                stdout(`no gate-disable snapshots found next to ${result.settingsPath}; nothing to restore.\n`);
+                return;
+            }
+            if (result.mode === "already-restored") {
+                stdout(`settings.json already matches the pre-disable state; no write needed. ` +
+                    `(snapshot: ${result.snapshotPath})\n`);
+                return;
+            }
+            stdout(`restored ${result.restoredCount} hook group(s) into ${result.settingsPath} from ` +
+                `${result.snapshotPath}.\n`);
+        }
+        catch (err) {
+            if (err instanceof GateEnableError) {
+                throw new HarnessExitError(err.message, EX_FAIL);
+            }
+            throw err;
+        }
+    });
     const policy = program.command("policy").description("Policy runtime verbs");
     policy
         .command("intercept")