@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/cli/approve/understanding.js

@@ -1,996 +0,0 @@
-// Phase 6 #4 — `harness approve understanding [--session <id>]` CLI verb.
-//
-// Round-trips both approval sources for the
-// `understanding-before-execution` pack:
-//
-//   1. Writes the evidence-ledger tag `understanding-approved:${SESSION_ID}`
-//      via `grounding-mcp`'s `ledger_add` (best-effort: degraded ledger
-//      surfaces as a warning, not a hard failure).
-//   2. Flips `approvalStatus: "approved"` on the latest persisted JSON
-//      report under `.understanding-gate/reports/`. Atomic rewrite.
-//
-// Rationale for writing both: harnessed sessions consult the ledger as
-// canonical, but a solo `@lannguyensi/understanding-gate` user without
-// `grounding-mcp` wired only sees the persisted JSON. Round-tripping
-// both means switching between the two stacks doesn't lose history.
-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 { escapeForDisplay } from "../../io/display-path.js";
-import { approvedLedgerTagFor, defaultReportsDir, hashReportFile, listDirNamesBounded, listPersistedReportsBoundedWithSkips, MAX_HASHED_REPORT_BYTES, readReportFileBounded, readActiveClaim, selectReportForSession, TOLERANT_FALLBACK_MAX_AGE_MS, writeApprovalMarker, writeTaskApprovalMarker, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
-import { PACK_NAME as UNDERSTANDING_PACK_NAME, resolveMode, toPackageMode, } from "../../policy-packs/builtin/understanding-before-execution.js";
-import { addLedgerFact } from "../../runtime/ledger-add.js";
-import { clearPendingApproval, resolveGeneratedDir, } from "../../runtime/pending-approval.js";
-import { resolveApprovalSessionId } from "../../runtime/session-id.js";
-import { EX_FAIL, HarnessExitError } from "../exit-codes.js";
-import { loadManifest, resolvePaths } from "../loader.js";
-import { describeSectionKey } from "../pack/understanding-report-schema-hint.js";
-import { persistStdinReport } from "./stdin-report.js";
-/**
- * Human-scale age for operator messages: minutes up to two hours,
- * hours up to two days, then days. A 17-day-old report should read
- * "17d", not "24893m" (review finding on harness-discovery C1).
- */
-function formatAge(ms) {
-    const min = Math.round(ms / 60_000);
-    if (Math.abs(min) < 120)
-        return `${min}m`;
-    const hours = Math.round(min / 60);
-    if (Math.abs(hours) < 48)
-        return `${hours}h`;
-    return `${Math.round(hours / 24)}d`;
-}
-const DEFAULT_APPROVED_BY = "harness-approve-cli";
-function findGroundingMcp(manifest) {
-    return manifest.tools.mcp.find((m) => m.name === "grounding-mcp") ?? null;
-}
-function expandHomePath(p) {
-    if (p === "~")
-        return process.env.HOME ?? os.homedir();
-    if (p.startsWith("~/"))
-        return path.join(process.env.HOME ?? os.homedir(), p.slice(2));
-    return p;
-}
-/**
- * Load the manifest (best-effort, never throws) and resolve the
- * `understanding-before-execution` pack's declared config entry from it.
- * Extracted (agent-tasks 37ad0b05) so
- * `approveUnderstanding` and `issueDelegation` (`src/cli/delegate/index.ts`)
- * share one copy of this manifest-load-plus-pack-lookup shape instead of
- * each carrying its own byte-identical block
- * (`npm run check:duplication` was flagging the pair as a clone). Pure
- * extraction: the try/catch and the `declaredPack` fallback are unchanged
- * from what each call site did inline before this change.
- */
-export function loadDeclaredUnderstandingPack(opts) {
-    let manifest = null;
-    let manifestLoadError = null;
-    try {
-        manifest = opts.manifest ?? loadManifest(opts).manifest;
-    }
-    catch (err) {
-        manifestLoadError = err instanceof Error ? err.message : String(err);
-    }
-    const declaredPack = manifest?.policy_packs.find((p) => p.name === UNDERSTANDING_PACK_NAME && p.enabled !== false) ?? { name: UNDERSTANDING_PACK_NAME, config: {} };
-    return { manifest, manifestLoadError, declaredPack };
-}
-/**
- * Exported (agent-tasks 37ad0b05, Slice 3 of the auto-mode-approval ADR)
- * with an additive `source` parameter so `harness delegate` can reuse
- * this writer verbatim instead of re-implementing the same
- * findGroundingMcp + addLedgerFact shape a third time in this codebase
- * (branch-protection.ts already carries its own independent copy for
- * its own `harness-approve-branch-protection` source). `source` defaults
- * to this file's own literal, so `approveUnderstanding`'s own call below
- * (which does not pass it) is byte-identical to before this change: pure
- * additive parameterization, not a behaviour change for that caller.
- */
-export async function writeLedgerTag(manifest, sessionId, content, opts, source = "harness-approve-understanding") {
-    if (opts.ledgerAdd)
-        return opts.ledgerAdd(sessionId, content);
-    const server = findGroundingMcp(manifest);
-    if (!server) {
-        return { ok: false, reason: "grounding-mcp not declared in manifest" };
-    }
-    const command = Array.isArray(server.command)
-        ? server.command.map(expandHomePath)
-        : server.command.trim().split(/\s+/).map(expandHomePath);
-    return addLedgerFact({
-        mcpCommand: command,
-        ...(server.env && { mcpEnv: server.env }),
-        timeoutMs: server.health?.timeout_ms ?? 5_000,
-        sessionId,
-        content,
-        source,
-    });
-}
-/**
- * Find the freshest parse-error log under `<dir>` (the
- * `<reports-dir>/../parse-errors/` location the standalone Stop hook
- * writes to when `parseReport` rejects the agent's last message). Used
- * to upgrade `approve understanding`'s "no reports found" diagnostic
- * from a silent dead end to a "hook fired but parse failed because X"
- * pointer. Best-effort: any I/O error is swallowed and we report no
- * parse-error, mirroring the listPersistedReports contract.
- *
- * `sessionId` filter (agent-tasks/b13205b2): each parse-error log's JSON
- * header carries the `sessionId` of the session that produced it. The
- * lookup used to return the directory-newest log regardless of whose
- * session wrote it, so a stale parse-error from a previous session would
- * surface in the current operator's approve output and read like a
- * failure of THEIR session. Logs whose header sessionId does not match
- * `sessionId` are now skipped entirely. Logs missing a `sessionId` field
- * (or whose header is not JSON) are also skipped, since we cannot
- * attribute them.
- *
- * `malformedSections` (task 823837fd, follow-up to 7e29e5d7): when the
- * log's JSON header carries a non-empty `malformedSections` array (a
- * (list) section that was present but not a markdown list), the returned
- * `summary` names those sections explicitly so the CLI's one-line reason
- * does not read as a bare "missing" when the agent actually wrote
- * *something* under the heading. Exported so the PreToolUse hooks
- * (hook-pre-tool-use.ts, hook-codex-pre-tool-use.ts) can reuse the same
- * lookup + attribution logic rather than re-implementing the header scan.
- *
- * Both hooks pass `maxEntries` (`MAX_HOOK_LISTING_ENTRIES`): a directory with
- * more `*.log` entries than that is read not at all and yields no parse error,
- * and the logs read are charged against the hash scan's byte budget (the
- * larger of the `fstat` size and the per-entry floor, newest first), so a
- * planted directory cannot run the hook past its time budget. Once the budget
- * is spent the lookup yields no parse error.
- */
-export function findLatestParseError(dir, sessionId, opts = {}) {
-    // `maxEntries` is set by the PreToolUse hooks (the directory is agent-writable
-    // and the lookup stats and reads its logs): past it nothing is opened and the
-    // answer is no parse error (the listing of a too large directory is empty),
-    // and the reads below spend a byte budget. The operator command leaves it unset.
-    const listed = listDirNamesBounded(dir, ".log", opts.maxEntries ?? Number.POSITIVE_INFINITY);
-    const budget = opts.maxEntries === undefined ? undefined : { spent: 0 };
-    const candidates = [];
-    for (const name of listed.names) {
-        const full = path.join(dir, name);
-        let stat;
-        try {
-            stat = fs.statSync(full);
-        }
-        catch {
-            continue;
-        }
-        candidates.push({ filePath: full, mtimeMs: stat.mtimeMs });
-    }
-    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
-    for (const cand of candidates) {
-        // Agent-writable dir, reached by both hooks on the no-marker path: the stat
-        // above only orders the candidates; the bounded reader's descriptor decides
-        // type and size, so a FIFO, a huge or a growing log is skipped like an
-        // unreadable one.
-        const bounded = readReportFileBounded(cand.filePath, { budget });
-        if (!bounded.ok && bounded.reason === "over-budget")
-            return null;
-        if (!bounded.ok)
-            continue;
-        const raw = bounded.raw;
-        // The standalone package writes a JSON header followed by `--- raw ---`
-        // and the original assistant text. Read the header for a `message`,
-        // `reason`, or `missing` field; fall back to the first line if the
-        // schema is unfamiliar so a future format change still surfaces
-        // *something* rather than going silent.
-        const header = raw.split("\n--- raw ---")[0] ?? raw;
-        let summary = (header.split("\n")[0] ?? "").trim();
-        let headerSessionId = null;
-        let malformedSections = [];
-        // Tracks whether `summary` was taken verbatim from the package's own
-        // `message` field: `@lannguyensi/understanding-gate` >= 0.4.10 already
-        // annotates each malformed (list) section inline in that string
-        // ("Prior Art (list) (present but not a markdown list -- use '- ' or
-        // '1.' items)"). Appending the same names again below would duplicate
-        // them in one line; the append is only useful when `summary` came from
-        // the `reason` fallback or the raw first-line fallback, neither of
-        // which mentions the malformed sections on its own.
-        let summaryFromMessage = false;
-        try {
-            const parsed = JSON.parse(header);
-            if (typeof parsed["sessionId"] === "string") {
-                headerSessionId = parsed["sessionId"];
-            }
-            if (Array.isArray(parsed["malformedSections"])) {
-                malformedSections = parsed["malformedSections"].filter((m) => typeof m === "string");
-            }
-            if (typeof parsed["message"] === "string" && parsed["message"].length > 0) {
-                summary = parsed["message"];
-                summaryFromMessage = true;
-            }
-            else if (typeof parsed["reason"] === "string") {
-                const missing = Array.isArray(parsed["missing"])
-                    ? ` (missing: ${parsed["missing"].filter((m) => typeof m === "string").join(", ")})`
-                    : "";
-                summary = `${parsed["reason"]}${missing}`;
-            }
-        }
-        catch {
-            /* keep the first-line fallback; headerSessionId stays null */
-        }
-        if (headerSessionId !== sessionId)
-            continue;
-        if (malformedSections.length > 0 && !summaryFromMessage) {
-            summary = `${summary}; malformed (present but not a markdown list): ${malformedSections.join(", ")}`;
-        }
-        return { filePath: cand.filePath, summary, malformedSections };
-    }
-    return null;
-}
-/**
- * Render the agent-facing "your previous report had malformed sections"
- * sentence from a `ParseErrorSummary.malformedSections` list, or `null`
- * when there is nothing to say. Shared by both PreToolUse hooks
- * (hook-pre-tool-use.ts, hook-codex-pre-tool-use.ts, task 823837fd
- * review) so the sentence is defined once instead of duplicated
- * byte-identically in each runtime; same extraction shape as
- * `checkOperatorApprovalMarkers` (understanding-before-execution-runtime.ts),
- * a marker-check helper both hooks already call instead of
- * re-implementing.
- *
- * Section keys are mapped to their display name via `describeSectionKey`
- * (`Prior Art (priorArt)` rather than the bare camelCase key) so the
- * sentence reads consistently with `renderReportSchemaHint`'s section
- * bullets in the same block reason, instead of mixing two vocabularies
- * for the same section. The CLI's own one-line summary
- * (`findLatestParseError` above) intentionally stays on raw keys; it is
- * operator-facing and matches the parse-error log verbatim.
- */
-export function renderMalformedSectionsNotice(sections) {
-    if (sections.length === 0)
-        return null;
-    const named = sections.map((s) => describeSectionKey(s)).join(", ");
-    return (`Your previous Understanding Report attempt had malformed sections ` +
-        `(present but not a markdown list): ${named}.`);
-}
-/**
- * Exported (agent-tasks/74b4b17d) so the PreToolUse hook's auto-approval
- * path applies the SAME approve-time content validation this CLI does,
- * rather than a second, drifting copy: the ADR
- * (docs/decisions/2026-08-27-ug-auto-mode-approval.md, Option A
- * condition 3) requires the auto path's report precondition to be the
- * approve CLI's own check. Export only; the logic is unchanged.
- */
-export function validatePersistedReport(parsed) {
-    const mode = typeof parsed["mode"] === "string" ? parsed["mode"] : null;
-    if (mode !== "grill_me")
-        return { ok: true, mode };
-    const priorArt = parsed["priorArt"];
-    if (!Array.isArray(priorArt) || priorArt.length === 0) {
-        return {
-            ok: false,
-            field: "priorArt",
-            reason: "grill_me report is missing required Section 10 (Prior Art). " +
-                "The schema requires a non-empty list naming the channels searched " +
-                "and the closest existing solution.",
-        };
-    }
-    // Mirror the schema's `items: { type: "string", minLength: 1 }`.
-    for (const item of priorArt) {
-        if (typeof item !== "string" || item.trim().length === 0) {
-            return {
-                ok: false,
-                field: "priorArt",
-                reason: "grill_me report's priorArt contains a non-string or empty item; " +
-                    "every entry must be a non-empty string.",
-            };
-        }
-    }
-    // Deterrent for the literal `- None` / `None` placeholder. The parser
-    // intentionally accepts these structurally; approve-time is where the
-    // prompt's "do not write `- None`" rule turns into a hard refusal.
-    // Only blocks when EVERY item is the None literal; a mixed list with
-    // real content is accepted.
-    const isNone = (x) => typeof x === "string" && ["none", "- none"].includes(x.trim().toLowerCase());
-    if (priorArt.every(isNone)) {
-        return {
-            ok: false,
-            field: "priorArt",
-            reason: "grill_me report's priorArt is entirely literal `None` / `- None`. " +
-                "The section exists to force a written answer to 'should this be " +
-                "built at all'; name the channels searched and the closest existing tool.",
-        };
-    }
-    return { ok: true, mode };
-}
-/**
- * Exported (agent-tasks/74b4b17d) so the PreToolUse hook's auto-approval path
- * CONSUMES the report it used through the identical rewrite this CLI performs
- * (ADR Option A condition 5). `boundedRaw`: the text that path already read
- * through the bounded reader, so the consume never re-reads the agent-writable
- * path (a retargeted symlink); `harness approve understanding` reads by path
- * through the same bounded reader.
- */
-export function rewriteReportApproved(filePath, approvedAt, approvedBy, sessionId, boundedRaw) {
-    let raw = boundedRaw;
-    if (raw === undefined) {
-        // Bounded like every other read of this agent-writable directory: the path
-        // can be swapped for an oversized file or a FIFO after the listing.
-        const read = readReportFileBounded(filePath, { noFollow: true });
-        if (!read.ok)
-            throw new Error(`report ${read.detail}`);
-        raw = read.raw;
-    }
-    const { text, previousStatus, sessionIdStamped } = renderApprovedReport(raw, approvedAt, approvedBy, sessionId);
-    // Temp file plus rename: the rename replaces the directory entry (a symlink
-    // included) and never opens whatever a retargeted symlink points at.
-    atomicWriteFile(filePath, text);
-    return { previousStatus, sessionIdStamped };
-}
-/**
- * Thrown by {@link renderApprovedReport} when the approved report, once
- * pretty-printed with its approval fields, is over `MAX_HASHED_REPORT_BYTES`.
- * The gate-read scan reads no file over that cap, so a marker signed for such
- * a report would deny on every call and neither re-approval nor `--force`
- * could clear it.
- */
-export class ApprovedReportTooLargeError extends Error {
-    bytes;
-    constructor(bytes) {
-        super(`the approved report would be ${bytes} bytes, over the ${MAX_HASHED_REPORT_BYTES}-byte cap ` +
-            "for hashing its content, so the gate could not match it");
-        this.bytes = bytes;
-        this.name = "ApprovedReportTooLargeError";
-    }
-}
-/**
- * The text `rewriteReportApproved` writes: the report with its approval
- * fields stamped and pretty-printed. Pure, so a producer can check the size
- * of the rewritten bytes before it signs a marker or changes any file. Throws
- * {@link ApprovedReportTooLargeError} when those bytes exceed
- * `MAX_HASHED_REPORT_BYTES`: a report accepted just under the cap can cross
- * it through the pretty-print and the added fields.
- */
-export function renderApprovedReport(raw, approvedAt, approvedBy, sessionId) {
-    const parsed = JSON.parse(raw);
-    const previousStatus = typeof parsed["approvalStatus"] === "string" ? parsed["approvalStatus"] : null;
-    parsed["approvalStatus"] = "approved";
-    parsed["approvedAt"] = approvedAt;
-    parsed["approvedBy"] = approvedBy;
-    // `expiredAt` and `expiredBy` are `expirePersistedReport`'s stamp for how a
-    // report reached "expired" (understanding-before-execution-runtime.ts); they
-    // describe that specific past state, not the report's current one.
-    // Approving a report that was previously expired must not let that stale
-    // timestamp survive into the new snapshot, or the persisted record becomes
-    // self-contradictory: {approvalStatus: "approved", expiredAt: ...}. Mirrors
-    // the same idiom in the standalone package's `withApprovalStatus`
-    // (agent-grounding PR #173, from the 5120938c review). `delete` (not
-    // `= undefined`) so `JSON.stringify` below drops the key entirely instead
-    // of serializing `"expiredAt": null`-adjacent noise.
-    delete parsed["expiredAt"];
-    delete parsed["expiredBy"];
-    // Stamp the session id when the report lacks one (older Stop-hook package
-    // versions write reports without a `sessionId` field). This binds the report
-    // to the session that approved it, so every later lookup strict-matches it and
-    // the sessionId-null fallback can never re-adopt it for a different session
-    // (harness/0dce3880 friction #1). An existing sessionId is left untouched.
-    let sessionIdStamped = false;
-    const existing = parsed["sessionId"];
-    if (typeof existing !== "string" || existing.length === 0) {
-        parsed["sessionId"] = sessionId;
-        sessionIdStamped = true;
-    }
-    const text = `${JSON.stringify(parsed, null, 2)}\n`;
-    const bytes = Buffer.byteLength(text);
-    if (bytes > MAX_HASHED_REPORT_BYTES)
-        throw new ApprovedReportTooLargeError(bytes);
-    return { text, previousStatus, sessionIdStamped };
-}
-/**
- * Normalise a list of task ids supplied via `opts.tasks` (or the CLI's
- * variadic `--task`). Each entry is comma-split (so `--task a,b` and
- * `--task a b` are equivalent), trimmed, blank entries dropped, and the
- * result de-duplicated while preserving first-seen order.
- */
-export function dedupeTaskIds(raw) {
-    const seen = new Set();
-    const out = [];
-    for (const entry of raw) {
-        for (const part of entry.split(",")) {
-            const id = part.trim();
-            if (id.length === 0 || seen.has(id))
-                continue;
-            seen.add(id);
-            out.push(id);
-        }
-    }
-    return out;
-}
-/**
- * A reason `hashReportFile` gives for a report whose CONTENT cannot be hashed
- * (`--force` may sign a marker without a content binding over it), as opposed
- * to one that could not be read within the bound (oversized, not a regular
- * file, a link, unreadable, growing), which `--force` never overrides.
- */
-function isContentReason(reason) {
-    return reason === "too-deep" || reason === "not-json-object";
-}
-/**
- * The reports directory is writable by the gated agent, so `harness approve
- * understanding` lists it through the bounded reader (one `O_NOFOLLOW` open
- * and `fstat` per entry, never a read past the size cap) and refuses while any `*.json`
- * entry cannot be read as a report: oversized, a FIFO or other non-regular
- * file, a symbolic link, unreadable, or growing. Refusing, rather than
- * leaving the entry out, keeps the approval from binding an older report
- * while a newer one is hidden from it. Thrown before any side effect, so
- * no marker, ledger tag or report flip is written; `--force` does not
- * override it (it overrides report content validation only).
- */
-function refuseSkippedReports(skipped, reportsDir) {
-    if (skipped.length === 0)
-        return;
-    const lines = skipped.map((s) => `  ${escapeForDisplay(s.filePath)}: ${s.detail}`);
-    throw new HarnessExitError([
-        `refusing to approve: ${skipped.length === 1 ? "an entry" : `${skipped.length} entries`} in the reports directory ` +
-            `cannot be read as a report, so approval cannot tell which report it would bind:`,
-        ...lines,
-        "",
-        `Remove or move ${skipped.length === 1 ? "that file" : "those files"} out of ${reportsDir}, then re-run ` +
-            "`harness approve understanding`. No approval marker, ledger tag or report change was written.",
-        "(`harness gc` lists such entries too and leaves them in place.)",
-    ].join("\n"), EX_FAIL);
-}
-export async function approveUnderstanding(opts = {}) {
-    // harness.generated/ holds the `.pending-approval` staging file (the
-    // third resolution tier below) and is the directory this command cleans
-    // up after consuming a staged id. `resolvePaths` only computes paths —
-    // it does not read or parse the manifest — so the lookup still works
-    // even when the manifest itself is unparseable.
-    const generatedDir = opts.generatedDir ??
-        resolveGeneratedDir({
-            ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
-            manifestPath: resolvePaths(opts).base,
-        });
-    // Session id resolution, in precedence order:
-    //   1. explicit --session flag
-    //   2. $CLAUDE_CODE_SESSION_ID — the canonical Claude Code env, the
-    //      variable Claude Code itself exports into the agent shell. Read
-    //      first so the runtime's id wins over a manually exported legacy
-    //      $CLAUDE_SESSION_ID that may not match.
-    //   3. $CLAUDE_SESSION_ID — legacy / docs-name peer, kept for the
-    //      Codex pre-tool-use hook's own fallback chain and for operators
-    //      who set it by hand in older `!`-shell recipes.
-    //   4. $CODEX_SESSION_ID (set inside a live Codex session — symmetric
-    //      with the Codex pre-tool-use hook's own env fallback).
-    //   5. the `.pending-approval` file the gate hook staged on its last
-    //      block — this is what makes an arg-less `harness approve` work
-    //      from the operator's `!`-shell, where neither of the above is set.
-    //   6. the freshest persisted Understanding Report under <reportsDir>
-    //      whose JSON `sessionId` field is non-null. Runtime-neutral
-    //      fallback when the gate has not blocked yet (e.g. arg-less
-    //      approval right after the agent produced an Understanding Report,
-    //      before any tool call hit the gate to stage `.pending-approval`).
-    //
-    // Reports-dir resolution mirrors the downstream persisted-report write
-    // path: explicit opts.reportsDir wins (test injection), then
-    // UNDERSTANDING_GATE_REPORT_DIR env (honoured by defaultReportsDir),
-    // then manifest-anchored fallback via resolvePaths. resolvePaths is
-    // evaluated lazily so a test that injects opts.reportsDir does not
-    // also need to inject homeDir/configPath to satisfy the
-    // HARNESS_ALLOW_REAL_GENERATED_DIR loader guard.
-    const reportsDir = opts.reportsDir ??
-        defaultReportsDir(path.dirname(resolvePaths(opts).base));
-    // Refuse a planted entry before anything else: the session-id fallback
-    // below and the report lookup further down both list this directory.
-    refuseSkippedReports(listPersistedReportsBoundedWithSkips(reportsDir, { refuseSymlinks: true }).skipped, reportsDir);
-    const resolved = resolveApprovalSessionId({
-        session: opts.session,
-        generatedDir,
-        // Tier 6: guess the session from the freshest persisted report.
-        // Restricted to `pending` reports. An `approved` / `expired`
-        // report belongs to a finished gate cycle (often a different
-        // session days ago); adopting its sessionId silently approves an
-        // unrelated session while the live one stays gated
-        // (harness/56f51f2b). A `pending` report is one the Stop hook
-        // just produced that no approval has consumed yet, so it is far
-        // more likely to be the current session's. This mirrors the
-        // `tolerantFallback: "uncompleted"` restriction PR #218 applied
-        // to the report-flip path below. The residual case — a stale
-        // session left a never-approved `pending` report — is caught by
-        // the loud newest-report warning the CLI prints, which names the report
-        // file so the operator can verify before trusting the marker.
-        newestReportFallback: () => {
-            const newest = listPersistedReportsBoundedWithSkips(reportsDir, {
-                refuseSymlinks: true,
-            }).reports.find((r) => r.sessionId !== null && r.approvalStatus === "pending");
-            if (newest && newest.sessionId !== null) {
-                return { sessionId: newest.sessionId, filePath: newest.filePath };
-            }
-            return null;
-        },
-    });
-    const sessionId = resolved.sessionId;
-    const sessionSource = resolved.sessionSource;
-    const newestReportPath = resolved.newestReportPath;
-    if (sessionId === "") {
-        // Reaching here means: no --session flag, no $CLAUDE_CODE_SESSION_ID
-        // / $CLAUDE_SESSION_ID / $CODEX_SESSION_ID env, no staged
-        // `.pending-approval`, AND no `pending` persisted Understanding
-        // Report under <reportsDir> carries a sessionId field. Either the
-        // gate has never blocked this session and the agent never produced a
-        // report, or every report is already approved/expired or
-        // sessionId-null (tier 6 only adopts a fresh `pending` report).
-        // Spell out the retrieval paths so the operator does not have to
-        // dig through docs.
-        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).",
-            "",
-            `Both the understanding-gate PreToolUse hook AND \`harness session-start preflight\``,
-            "stage the session id in",
-            `  ${generatedDir}/.pending-approval`,
-            "(the hook on block, the preflight on every run with a resolved id) so an",
-            "arg-less `harness approve` works after either event. An empty result here means",
-            "neither has fired for the current session yet, or the staging file was already consumed.",
-            "",
-            "Fastest fix: run `harness preflight` once, then re-run `harness approve",
-            "understanding`. The preflight stages the staging file as a side effect.",
-            "",
-            "Other runtime-neutral recovery paths:",
-            `  • Read the JSON \`sessionId\` field from the newest report under`,
-            `      ${reportsDir}`,
-            "    The agent writes one report per Understanding Report it produces,",
-            "    so this is the canonical session-id source for both Claude Code",
-            "    and Codex runtimes regardless of cwd.",
-            "  • From inside the running agent: ask it to print its session id",
-            "    (Claude Code exposes $CLAUDE_CODE_SESSION_ID; Codex exposes",
-            "    $CODEX_SESSION_ID and also prints it in `codex doctor --json`).",
-            "",
-            "If approve writes the tag but the gate still blocks, the running",
-            "session is using a different session id than the report you picked.",
-            "In that case ask the agent to read its own session id and pass",
-            "that exact value to --session.",
-        ].join("\n"), EX_FAIL);
-    }
-    // Manifest is required for the ledger write path; if it can't load,
-    // we still try to flip the persisted report so a solo user benefits.
-    // Not blocking: a solo user still benefits from the report flip below
-    // even with no manifest. `manifestLoadError` captures the cause so the
-    // degraded-ok ledger result names WHY the write was skipped instead of
-    // leaving the operator with a bare `ledger: ok false` (no-silent-errors,
-    // M8).
-    // Gap-fill mode for a stdin report that declares none of its own
-    // (harness task 5d73d78d): resolve via `resolveMode` (Env >
-    // config.mode > DEFAULT_MODE — this IS a live runtime consumer, unlike
-    // `resolve()`/`buildHooks`'s generation path; see `MODE_ENV`'s doc
-    // comment in understanding-before-execution.ts for why the two differ),
-    // from whatever manifest is available (`loadDeclaredUnderstandingPack`
-    // above), so a report captured via this path is validated against the
-    // operator's actually-configured mode instead of a hardcoded
-    // "fast_confirm" regardless of harness.yaml. A missing manifest, or a
-    // manifest without the pack declared, resolves the same as an empty
-    // `config:` block, resolveMode still applies Env > DEFAULT_MODE in
-    // that case.
-    //
-    // A pack entry that IS declared but `enabled: false` is treated the
-    // SAME as undeclared (task 5d73d78d review LOW-10): a disabled pack's
-    // hooks never ran, so its `config.mode` is not "the operator's live
-    // mode" in any sense this gap-fill should honor. The synthesized
-    // fallback only needs `name` + `config` (resolveMode's minimal
-    // `ModeConfigSource` shape) — `source`/`enabled` would otherwise have
-    // to be invented for a pack entry that, by construction, was never
-    // matched. `loadDeclaredUnderstandingPack` applies that same rule.
-    const { manifest, manifestLoadError, declaredPack } = loadDeclaredUnderstandingPack(opts);
-    // Task 5d73d78d review LOW (fix-round-3): `resolveMode`'s own warning
-    // (an invalid `config.mode` or `UNDERSTANDING_GATE_MODE` value) used to
-    // be dropped on the floor here — only `.mode` was read. The Codex
-    // `UserPromptSubmit` injector (hook-codex-user-prompt-submit.ts)
-    // already surfaces the identical warning shape to stderr on this same
-    // `resolveMode` call; this path silently swallowed it, so an operator
-    // with a typo'd `config.mode` got no signal at all from `harness
-    // approve understanding`. Surfaced via `modeWarning` on the result so
-    // the CLI can print it the same way the marker/ledger/report lines are
-    // printed.
-    const modeResolution = resolveMode(declaredPack);
-    const resolvedMode = toPackageMode(modeResolution.mode);
-    // Report capture from stdin (task 61fd36db): persist BEFORE the
-    // lookup below so this very approve run selects, validates, and flips
-    // the report the agent just attached. Session-bound via the resolved
-    // sessionId, so the strict match wins over any stale leftovers.
-    let stdinReport;
-    if (typeof opts.reportMarkdown === "string" && opts.reportMarkdown.trim().length > 0) {
-        stdinReport = persistStdinReport({
-            markdown: opts.reportMarkdown,
-            reportsDir,
-            sessionId,
-            now: opts.now ?? new Date(),
-            mode: resolvedMode,
-        });
-    }
-    // Approve-time validation. Resolve the report we would flip BEFORE
-    // writing the marker, so a validation failure can short-circuit every
-    // downstream write. The `latest` + `reports` values are reused later;
-    // we do not list / find twice. The fallback age limit is what stops a
-    // weeks-old sessionId-less leftover from being adopted, validated,
-    // and stamped as if it were the live session's report when the
-    // producer Stop hook silently failed (harness-discovery C1).
-    // Listed again here (the stdin capture above may have written a report);
-    // a planted entry that appeared since the first listing is refused too.
-    const listing = listPersistedReportsBoundedWithSkips(reportsDir, { refuseSymlinks: true });
-    refuseSkippedReports(listing.skipped, reportsDir);
-    const reports = listing.reports;
-    const selection = selectReportForSession(reports, sessionId, {
-        tolerantFallback: "uncompleted",
-        maxFallbackAgeMs: TOLERANT_FALLBACK_MAX_AGE_MS,
-        now: opts.now,
-    });
-    const latest = selection.report;
-    let validation;
-    if (!latest) {
-        validation = { skipped: true };
-    }
-    else {
-        let parsed = null;
-        // Bounded read, not following a symbolic link: the listing above saw the
-        // file within the cap, but the path can be swapped for an oversized file,
-        // a FIFO or a link since.
-        const reread = readReportFileBounded(latest.filePath, { noFollow: true });
-        if (reread.ok) {
-            try {
-                parsed = JSON.parse(reread.raw);
-            }
-            catch {
-                parsed = null;
-            }
-        }
-        if (!reread.ok) {
-            // Enforced even under --force: a report that cannot be read within the
-            // bound has no content to bind, and --force never signs a marker over
-            // one (it overrides content validation only).
-            validation = {
-                ok: false,
-                field: "report",
-                reason: `${reread.detail}, so the approval could not bind it`,
-                enforced: true,
-            };
-        }
-        else if (!parsed) {
-            validation = { skipped: true };
-        }
-        else {
-            const v = validatePersistedReport(parsed);
-            validation = v.ok ? v : { ...v, enforced: !opts.force };
-            // A report the canonical hash cannot cover (larger than the size cap
-            // the gate reads, not a regular file, nested too deeply) would sign a
-            // marker whose `reportContentHash` is null, i.e. one the gate-read
-            // content check never applies to, so it fails validation instead.
-            // `--force` overrides only a content reason (too deep, not a JSON
-            // object); a size, type or read failure is enforced whatever the flag
-            // says. `hashReportFile` reads the file exactly as the gate-read scan
-            // does, except that it does not follow a symbolic link.
-            if (validation.ok) {
-                const hashed = hashReportFile(latest.filePath, { noFollow: true });
-                if (!hashed.ok) {
-                    validation = {
-                        ok: false,
-                        field: "report",
-                        reason: `${hashed.detail}, so the approval could not bind it`,
-                        enforced: !isContentReason(hashed.reason) || !opts.force,
-                    };
-                }
-            }
-        }
-    }
-    // Task 5d73d78d review HIGH-2: a stdin report that was REJECTED (failed
-    // to parse, e.g. because it does not meet the resolved mode's schema —
-    // typically a fast_confirm-shaped report submitted against a
-    // grill_me-configured host, see `resolvedMode` above) AND left no
-    // persisted report to fall back on must not fall through to `{ skipped:
-    // true }` above. "skipped" means "nothing was submitted to check"; here
-    // something WAS submitted and it was refused. Before this fix, that
-    // case still landed on `{ skipped: true }` (no `latest` report exists
-    // yet, since persistStdinReport never wrote one), which is not an `ok:
-    // false` validation outcome, so the enforced short-circuit below never
-    // triggered and the marker was written anyway — silently approving a
-    // session whose only report attempt was rejected.
-    //
-    // Fix-round-3 HIGH (5d73d78d review, verification round 2): the
-    // original guard checked only `!latest`, but `latest` can also be a
-    // sessionId-null report ADOPTED via `selectReportForSession`'s
-    // `tolerantFallback: "uncompleted"` mode above (any pending, sessionId-
-    // less report younger than `TOLERANT_FALLBACK_MAX_AGE_MS`). A rejected
-    // stdin submission with such a leftover sitting on disk used to sail
-    // through unconstrained: `latest` was truthy so this override never
-    // fired, the ADOPTED (unrelated) report's own — already-valid — content
-    // passed `validatePersistedReport` instead, and `rewriteReportApproved`
-    // below then stamped the live session's id onto that foreign report and
-    // wrote the marker: a session whose actual submission was refused got
-    // silently approved anyway. The condition now also treats a fallback-
-    // adopted `latest` as "nothing THIS session can claim":
-    // `selection.fallbackAdopted` is `true` exactly when the match was NOT
-    // a strict sessionId match.
-    //
-    // The deliberate carve-out for a genuine EARLIER same-session
-    // submission stays: when `latest` is a STRICT sessionId match
-    // (`selection.fallbackAdopted === false`), that report's own content
-    // validation above already governs the outcome and this block does not
-    // override it.
-    if (typeof opts.reportMarkdown === "string" &&
-        opts.reportMarkdown.trim().length > 0 &&
-        stdinReport !== undefined &&
-        stdinReport.ok === false &&
-        (!latest || selection.fallbackAdopted)) {
-        validation = {
-            ok: false,
-            field: "stdinReport",
-            reason: stdinReport.reason,
-            enforced: !opts.force,
-        };
-    }
-    // Short-circuit before any side effect if validation rejects and the
-    // operator did not pass --force. No marker, no ledger tag, no report
-    // flip — the gate stays closed and the audit trail records no
-    // approval. The CLI surfaces this as a hard failure so the operator
-    // does not believe they approved when they didn't.
-    if ("ok" in validation && validation.ok === false && validation.enforced) {
-        // Any --task / --tasks ids the operator passed are dropped on the
-        // floor: pre-approving a batch alongside a session whose own report
-        // failed validation would write task markers for a session that the
-        // gate is still going to refuse. The CLI surfaces this empty array
-        // alongside the rejection so an operator who batched several tasks
-        // can see the batch was NOT pre-approved.
-        return {
-            sessionId,
-            sessionSource,
-            ...(newestReportPath !== undefined ? { newestReportPath } : {}),
-            ...(modeResolution.warning !== null ? { modeWarning: modeResolution.warning } : {}),
-            marker: {
-                ok: false,
-                reason: `validation failed (${validation.field}): ${validation.reason}`,
-            },
-            taskMarkers: [],
-            ...(stdinReport !== undefined ? { stdinReport } : {}),
-            ledger: {
-                ok: false,
-                tag: approvedLedgerTagFor(sessionId),
-                reason: `skipped: ${validation.field} validation failed`,
-            },
-            persistedReport: {
-                ok: false,
-                reason: `skipped: ${validation.field} validation failed`,
-            },
-            validation,
-        };
-    }
-    // Report-content hash the marker's signature binds to (harness/f9485cc7):
-    // the canonical hash of the persisted report AT APPROVAL TIME, computed
-    // BEFORE `rewriteReportApproved` below flips its status/approvedAt/
-    // approvedBy fields, so it covers what the operator actually reviewed.
-    // `canonicalReportHash` leaves the lifecycle fields out, which is why the
-    // value survives that flip and a later `expirePersistedReport` rewrite;
-    // both PreToolUse hooks look for a report file with that hash at gate-read
-    // time (`verifyApprovedReportHash`, task fa423e9b) and refuse the marker
-    // when none is left. null when no persisted report was resolved or it
-    // cannot be read as a JSON object (validation skipped above, nothing to
-    // bind), or when its content cannot be hashed: nested too deeply or not a
-    // JSON object (reachable only under --force: the validation above refuses
-    // the first otherwise). A report larger than the size cap, not a regular
-    // file or a link never gets here: the validation above enforces that
-    // refusal under --force too, and the check below repeats it for a swap
-    // since.
-    let reportContentHash = null;
-    if (latest) {
-        const hashed = hashReportFile(latest.filePath, { noFollow: true });
-        if (hashed.ok) {
-            reportContentHash = hashed.hash;
-        }
-        else if (!isContentReason(hashed.reason)) {
-            // Swapped for an oversized file, a FIFO or a link after the validation
-            // above read it: refuse before any marker, ledger tag or report flip is
-            // written, `--force` or not (the validation above enforces the same).
-            throw new HarnessExitError(`refusing to approve: report ${escapeForDisplay(latest.filePath)} ${hashed.detail} ` +
-                "since it was validated, so the approval cannot bind it. No approval marker, " +
-                "ledger tag or report change was written; re-run `harness approve understanding`.", EX_FAIL);
-        }
-    }
-    // Write the canonical approval marker first. The gate consults this
-    // file (not the ledger) since agent-tasks/88ca4bb3 closed the self-
-    // approval backdoor: the agent has direct MCP access to the ledger,
-    // but no path to write a file under harness.generated/.
-    const approvedAtMarker = (opts.now ?? new Date()).toISOString();
-    const approvedByMarker = opts.approvedBy ?? DEFAULT_APPROVED_BY;
-    // The rewrite below pretty-prints the report and adds its approval fields,
-    // which can carry a report accepted just under the size cap over it. The
-    // gate-read scan reads no file over the cap, so the marker signed here would
-    // deny on every call, and neither re-approval nor --force could clear it.
-    // Render the rewrite first and refuse on its bytes, before any marker,
-    // ledger tag or report change is written, `--force` or not.
-    if (latest) {
-        const current = readReportFileBounded(latest.filePath, { noFollow: true });
-        if (current.ok) {
-            try {
-                renderApprovedReport(current.raw, approvedAtMarker, approvedByMarker, sessionId);
-            }
-            catch (err) {
-                if (err instanceof ApprovedReportTooLargeError) {
-                    throw new HarnessExitError(`refusing to approve: report ${escapeForDisplay(latest.filePath)}: ${err.message}. ` +
-                        "Shorten the report and re-run `harness approve understanding`. No approval marker, " +
-                        "ledger tag or report change was written.", EX_FAIL);
-                }
-                // Any other failure (unparseable text) keeps its existing handling below.
-            }
-        }
-    }
-    let markerResult;
-    try {
-        const filePath = writeApprovalMarker(generatedDir, sessionId, {
-            approvedAt: approvedAtMarker,
-            approvedBy: approvedByMarker,
-            reportContentHash,
-        });
-        markerResult = { ok: true, filePath, approvedAt: approvedAtMarker };
-    }
-    catch (err) {
-        markerResult = {
-            ok: false,
-            reason: `failed to write approval marker: ${err.message}`,
-        };
-    }
-    // Task-scoped markers (harness/1ee26e77 + v2 auto-resolve in
-    // harness/494fd1e5 + multi-task batch in harness/0dce3880). Written
-    // alongside the session marker. Resolution precedence:
-    //   - opts.tasks (explicit, multi) — pre-approve a whole batch, OR
-    //   - opts.task (explicit, single, back-compat), OR
-    //   - the active-claim file (source: "active-claim").
-    // A failure on any one id is surfaced loudly but does not abort the
-    // approve flow; the session marker still satisfies the gate as a
-    // fallback, and the other ids still get their markers.
-    let resolvedTaskIds = [];
-    let taskSource = "flag";
-    if (opts.tasks && opts.tasks.length > 0) {
-        resolvedTaskIds = dedupeTaskIds(opts.tasks);
-        taskSource = "flag";
-    }
-    else if (typeof opts.task === "string" && opts.task.length > 0) {
-        resolvedTaskIds = [opts.task];
-        taskSource = "flag";
-    }
-    else {
-        const fromFile = readActiveClaim(generatedDir);
-        if (fromFile !== null) {
-            resolvedTaskIds = [fromFile];
-            taskSource = "active-claim";
-        }
-    }
-    const taskMarkers = [];
-    for (const taskId of resolvedTaskIds) {
-        try {
-            const filePath = writeTaskApprovalMarker(generatedDir, taskId, {
-                approvedAt: approvedAtMarker,
-                approvedBy: approvedByMarker,
-                reportContentHash,
-            });
-            taskMarkers.push({
-                ok: true,
-                taskId,
-                filePath,
-                approvedAt: approvedAtMarker,
-                source: taskSource,
-            });
-        }
-        catch (err) {
-            taskMarkers.push({
-                ok: false,
-                taskId,
-                reason: `failed to write task marker: ${err.message}`,
-                source: taskSource,
-            });
-        }
-    }
-    // Ledger tag content: a `--force`-bypass of a validation failure
-    // stamps the bypass into the tag so audit can distinguish a clean
-    // approval from one that overrode a structural rule. The base tag
-    // shape (`understanding-approved:<session>`) stays intact so the gate
-    // matcher still recognises it; the `:forced:<field>` suffix is
-    // additive metadata.
-    const tag = "ok" in validation && validation.ok === false
-        ? `${approvedLedgerTagFor(sessionId)}:forced:${validation.field}`
-        : approvedLedgerTagFor(sessionId);
-    const ledgerResult = manifest
-        ? await writeLedgerTag(manifest, sessionId, tag, opts)
-        : {
-            ok: false,
-            reason: manifestLoadError
-                ? `manifest unreadable (${manifestLoadError}); skipped ledger write`
-                : "manifest unreadable; skipped ledger write",
-        };
-    // Persisted report: flip the latest matching one. `reports` + `latest`
-    // were resolved up front (alongside validation) so both paths agree
-    // on the same artefact.
-    let persistedReport;
-    if (!latest) {
-        // When no matching report exists, look at the sibling parse-errors
-        // directory (`<dir-of-reports>/../parse-errors/`, the path the
-        // standalone @lannguyensi/understanding-gate Stop hook writes to
-        // when its parser rejects the agent's last message). Surface the
-        // newest entry's reason so "no reports found" becomes "the hook
-        // fired but the parser rejected the report — here is why", rather
-        // than a silent dead end.
-        const parseErrorsDir = path.join(path.dirname(reportsDir), "parse-errors");
-        const latestParseError = findLatestParseError(parseErrorsDir, sessionId);
-        let reason;
-        if (reports.length === 0) {
-            reason = `no reports found at ${reportsDir}`;
-            if (latestParseError) {
-                reason += `; latest parse-error at ${escapeForDisplay(latestParseError.filePath)}: ${escapeForDisplay(latestParseError.summary)}`;
-            }
-        }
-        else if (selection.staleRejected.length > 0) {
-            // A sessionId-less pending report existed but exceeded the
-            // fallback age limit. This is its own failure mode, distinct from
-            // "no report": it usually means the live session's report was
-            // never persisted and only an unrelated leftover was on disk —
-            // exactly the artefact the limit refuses to bind (C1).
-            const newest = selection.staleRejected[0];
-            const age = formatAge((opts.now ?? new Date()).getTime() - newest.createdAtMs);
-            const maxMin = Math.round(TOLERANT_FALLBACK_MAX_AGE_MS / 60_000);
-            reason =
-                `no report matched session_id=${escapeForDisplay(sessionId)}; rejected ${selection.staleRejected.length} ` +
-                    `stale sessionId-less candidate(s) for age (newest: ${escapeForDisplay(newest.filePath)}, ` +
-                    `created ${escapeForDisplay(newest.createdAt ?? "<unknown>")}, age ${age} > max ${maxMin}m). ` +
-                    `If the agent just wrote an Understanding Report, the Stop hook likely failed to ` +
-                    `persist it; check ${parseErrorsDir}`;
-            if (latestParseError) {
-                reason += `; latest parse-error at ${escapeForDisplay(latestParseError.filePath)}: ${escapeForDisplay(latestParseError.summary)}`;
-            }
-        }
-        else {
-            reason = `no report matched session_id=${escapeForDisplay(sessionId)} (${reports.length} report(s) for other sessions)`;
-        }
-        persistedReport = { ok: false, reason };
-    }
-    else {
-        const approvedAt = (opts.now ?? new Date()).toISOString();
-        const approvedBy = opts.approvedBy ?? DEFAULT_APPROVED_BY;
-        try {
-            const { previousStatus, sessionIdStamped } = rewriteReportApproved(latest.filePath, approvedAt, approvedBy, sessionId);
-            persistedReport = {
-                ok: true,
-                filePath: latest.filePath,
-                previousStatus,
-                approvedAt,
-                sessionIdStamped,
-                ...(selection.fallbackAdopted
-                    ? {
-                        fallbackAdopted: {
-                            createdAt: latest.createdAt,
-                            ageMinutes: Math.round(((opts.now ?? new Date()).getTime() - latest.createdAtMs) / 60_000),
-                        },
-                    }
-                    : {}),
-            };
-        }
-        catch (err) {
-            persistedReport = {
-                ok: false,
-                reason: `failed to rewrite ${escapeForDisplay(latest.filePath)}: ${escapeForDisplay(err.message)}`,
-            };
-        }
-    }
-    // Drop the staging file once we have consumed it AND the canonical
-    // (marker) write landed, so a later arg-less `harness approve` cannot
-    // revive this id. A failed marker write keeps the file so the operator
-    // can retry; an id supplied by flag/env was never "ours" to clean up.
-    if (sessionSource === "pending-approval" && markerResult.ok) {
-        clearPendingApproval(generatedDir);
-    }
-    return {
-        sessionId,
-        sessionSource,
-        ...(newestReportPath !== undefined ? { newestReportPath } : {}),
-        ...(modeResolution.warning !== null ? { modeWarning: modeResolution.warning } : {}),
-        marker: markerResult,
-        taskMarkers,
-        ...(stdinReport !== undefined ? { stdinReport } : {}),
-        ledger: ledgerResult.ok
-            ? { ok: true, tag }
-            : { ok: false, tag, reason: ledgerResult.reason },
-        persistedReport,
-        validation,
-    };
-}
-//# sourceMappingURL=understanding.js.map