@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/cli/approve/understanding.d.ts

@@ -1,410 +0,0 @@
-import { type ModeConfigSource } from "../../policy-packs/builtin/understanding-before-execution.js";
-import type { Manifest } from "../../schema/index.js";
-import { type LoaderOptions } from "../loader.js";
-import { type StdinReportOutcome } from "./stdin-report.js";
-export interface ApproveUnderstandingOptions extends LoaderOptions {
-    /** Explicit session id (overrides $CLAUDE_CODE_SESSION_ID / $CLAUDE_SESSION_ID / $CODEX_SESSION_ID). */
-    session?: string;
-    /**
-     * Override the approve-time report validation (priorArt enforcement for
-     * `grill_me` reports). Writes the marker / ledger / report-flip anyway
-     * and stamps the ledger tag content with a `:forced:<field>-<reason>`
-     * suffix so the audit trail records the bypass. Emergency-unblock path:
-     * the default refuses the marker when validation fails so an agent
-     * cannot ship a hollow Understanding Report and still get the gate open.
-     */
-    force?: boolean;
-    /**
-     * Optional agent-tasks task id (harness/1ee26e77). When set, an
-     * additional task-scoped marker file is written at
-     * `<generatedDir>/.approvals/task-<taskId>`, in addition to the
-     * legacy session-scoped marker. Either satisfies the gate; the
-     * task-scoped marker is the design-intent target for multi-task
-     * sessions so the next task can require its own Understanding Report.
-     *
-     * When omitted, `harness approve understanding` falls back to reading
-     * `<generatedDir>/active-claim` (written by the track-active-claim
-     * PostToolUse hook on `task_start`, harness/494fd1e5). If that file
-     * exists, its content is used as the task id. If absent, no task
-     * marker is written — the session marker is the only one (v1
-     * back-compat).
-     *
-     * Single-id back-compat field. For pre-approving a batch use `tasks`;
-     * when both are set, `tasks` wins.
-     */
-    task?: string;
-    /**
-     * Multiple agent-tasks task ids to pre-approve in one operator action
-     * (harness/0dce3880 friction #2). One task-scoped marker is written
-     * per id. As the agent's active claim cycles through the listed
-     * tasks, each `task_start` finds its own marker already present, so a
-     * homogeneous batch (e.g. a CVE sweep across N repos) needs a single
-     * `harness approve understanding --task a b c` instead of one
-     * approval per `task_finish`. The understanding gate stays
-     * task-scoped: the operator's report still has to enumerate every
-     * task it covers; only the round-trip count collapses. Empty / blank
-     * entries are dropped and duplicates de-duplicated.
-     */
-    tasks?: string[];
-    /**
-     * Understanding Report markdown captured from the command's stdin
-     * (the report-heredoc shape, task 61fd36db). When set and non-blank,
-     * it is parsed and persisted as a pending, session-bound report BEFORE
-     * the report lookup below, so this very approve run validates and
-     * flips it. A parse failure degrades loudly (parse-error log + reason
-     * on the result) but does not abort the approval — the operator just
-     * approved interactively; a formatting nit must not brick that.
-     */
-    reportMarkdown?: string;
-    /** Override the reports directory (test injection). */
-    reportsDir?: string;
-    /** Override the harness.generated/ directory (test injection). */
-    generatedDir?: string;
-    /** Override "now" for deterministic tests. */
-    now?: Date;
-    /** Override the actor recorded in the persisted report. */
-    approvedBy?: string;
-    /** Inject a manifest (test). */
-    manifest?: Manifest;
-    /** Override the ledger writer (test). */
-    ledgerAdd?: (sessionId: string, content: string) => Promise<{
-        ok: true;
-    } | {
-        ok: false;
-        reason: string;
-    }>;
-}
-/** Outcome of writing one task-scoped approval marker. */
-export type TaskMarkerOutcome = {
-    ok: true;
-    taskId: string;
-    filePath: string;
-    approvedAt: string;
-    source: "flag" | "active-claim";
-} | {
-    ok: false;
-    taskId: string;
-    reason: string;
-    source: "flag" | "active-claim";
-};
-export interface ApproveUnderstandingResult {
-    sessionId: string;
-    /**
-     * Where `sessionId` came from. Surfaced so the CLI can show the
-     * operator when the id was not explicit (`pending-approval` / `env`),
-     * which is the moment to sanity-check it against the live session.
-     */
-    sessionSource: "flag" | "env-claude-code" | "env-claude" | "env-codex" | "pending-approval" | "newest-report";
-    /**
-     * When `sessionSource` is `"newest-report"`, the absolute path of the
-     * persisted report the session id was guessed from. Undefined for
-     * every other source. The CLI names this file in its loud tier-5
-     * "verify this is your live session" warning so the operator can open
-     * it and check before trusting the marker (harness/56f51f2b).
-     */
-    newestReportPath?: string;
-    /**
-     * Canonical gate-satisfying signal as of agent-tasks/88ca4bb3.
-     * `ok: false` means the marker file could not be written (rare:
-     * fs permission, missing parent directory) and the gate will still
-     * block on the next tool call. The CLI surfaces this as a hard error
-     * to the operator so they don't think they approved when they didn't.
-     */
-    marker: {
-        ok: true;
-        filePath: string;
-        approvedAt: string;
-    } | {
-        ok: false;
-        reason: string;
-    };
-    /**
-     * Task-scoped marker write outcomes, one entry per resolved task id
-     * (harness/0dce3880). Populated when `--task` / `opts.task` /
-     * `opts.tasks` was supplied OR when the active-claim file resolved an
-     * id (harness/494fd1e5). Empty array when no task was resolved
-     * through any surface, so a regression cannot silently flip
-     * session-only sessions into task-mode.
-     *
-     * The `source` field tells the operator which surface fed each id so
-     * a wrong claim file can be spotted before it lands in the marker.
-     */
-    taskMarkers: TaskMarkerOutcome[];
-    /**
-     * `resolveMode`'s own warning (invalid `config.mode` in `harness.yaml`,
-     * or an invalid `UNDERSTANDING_GATE_MODE` env value) surfaced verbatim
-     * (task 5d73d78d review LOW, fix-round-3). Absent when the resolution
-     * was clean. This mirrors what the Codex `UserPromptSubmit` injector
-     * already writes to stderr for the exact same `resolveMode` call — this
-     * command used to compute the same warning and drop it silently.
-     */
-    modeWarning?: string;
-    /**
-     * Outcome of capturing a report passed on stdin (`reportMarkdown`).
-     * Absent when no report was supplied. `ok: true` means the markdown
-     * parsed and was persisted pending + session-bound; the
-     * `persistedReport` result below then reports the flip of that same
-     * file. `ok: false` carries the parse/persist failure reason (and the
-     * parse-error log path when one was written).
-     */
-    stdinReport?: StdinReportOutcome;
-    ledger: {
-        ok: boolean;
-        tag: string;
-        reason?: string;
-    };
-    persistedReport: {
-        ok: true;
-        filePath: string;
-        previousStatus: string | null;
-        approvedAt: string;
-        /** True when this approval stamped a missing `sessionId` onto the report. */
-        sessionIdStamped: boolean;
-        /**
-         * Present when the report was adopted via the sessionId-less
-         * tolerant fallback rather than a strict sessionId match. The
-         * CLI prints it loudly: the operator must verify the adopted
-         * report is the one they just read, because a fallback adoption
-         * means the live session's own report was never persisted
-         * (harness-discovery C1).
-         */
-        fallbackAdopted?: {
-            createdAt: string | null;
-            ageMinutes: number;
-        };
-    } | {
-        ok: false;
-        reason: string;
-    };
-    /**
-     * Approve-time content validation of the persisted report. `mode` is
-     * the report's stamped mode field (the schema variant the report is
-     * judged against). `ok: false` means a structural rule the prompt
-     * already declared was violated (today: `grill_me` reports must have
-     * a non-empty priorArt list with no literal `- None`).
-     *
-     * `enforced: false` means the failure was bypassed via `--force`; the
-     * marker / ledger / report-flip still ran, and `ledger.tag` carries a
-     * `:forced:<field>-<reason>` suffix so audit can distinguish forced
-     * approvals from clean ones.
-     *
-     * `skipped: true` means no report was loaded to validate (no `latest`
-     * matched the session, ledger-only path); validation is silently
-     * waived because there is nothing to enforce.
-     */
-    validation: {
-        ok: true;
-        mode: string | null;
-    } | {
-        ok: false;
-        field: string;
-        reason: string;
-        enforced: boolean;
-    } | {
-        skipped: true;
-    };
-}
-/** Best-effort manifest load plus the resolved `understanding-before-execution` pack config entry it feeds. */
-export interface DeclaredUnderstandingPack {
-    /** `null` when the manifest could not be loaded; the caller degrades gracefully rather than treating this as fatal. */
-    manifest: Manifest | null;
-    /** The load failure's message, when `manifest` is `null`. `null` on a clean load. */
-    manifestLoadError: string | null;
-    /**
-     * The pack's own declared entry when present and not explicitly
-     * `enabled: false`; otherwise a synthesized empty entry (`config: {}`)
-     * so a caller's `resolveMode` / `approval_lifecycle` read still resolves
-     * via Env > default instead of needing a null check.
-     */
-    declaredPack: ModeConfigSource;
-}
-/**
- * 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 declare function loadDeclaredUnderstandingPack(opts: LoaderOptions & {
-    manifest?: Manifest;
-}): DeclaredUnderstandingPack;
-/**
- * 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 declare function writeLedgerTag(manifest: Manifest, sessionId: string, content: string, opts: ApproveUnderstandingOptions, source?: string): Promise<{
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-}>;
-export interface ParseErrorSummary {
-    filePath: string;
-    /** One-line human-readable summary suitable for inlining in the CLI reason. */
-    summary: string;
-    /**
-     * Section keys the log's `malformedSections` field named: a (list)
-     * heading that WAS present but whose body was prose instead of markdown
-     * list items (`@lannguyensi/understanding-gate` >= 0.4.10, agent-tasks
-     * be98cd96). Empty when the field is absent/empty on the log (older
-     * package pin, or an unrelated parse-error reason). `summary` already
-     * has this named, appended as its own clause; this is exposed
-     * separately too so a caller that wants to build its own sentence
-     * (e.g. the PreToolUse hooks' agent-facing block reason, task
-     * 823837fd) does not have to re-parse the log.
-     */
-    malformedSections: string[];
-}
-/**
- * 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 declare function findLatestParseError(dir: string, sessionId: string, opts?: {
-    maxEntries?: number;
-}): ParseErrorSummary | 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 declare function renderMalformedSectionsNotice(sections: string[]): string | null;
-/**
- * Approve-time content validation. v1 enforces the one rule the dogfood
- * loop discovered today (2026-05-24): a `grill_me` Report must declare a
- * non-empty `priorArt` list with no literal `- None`. The structural
- * parser in `@lannguyensi/understanding-gate` only checks that the
- * Prior Art section is present (required since 0.4.0,
- * `CHANGELOG.md:#0.28.0`); it cannot judge the content, so the approve
- * CLI is the boundary that refuses a hollow list here, so an agent
- * cannot ship a hollow Understanding Report and still get the gate open.
- *
- * Modes that skip validation:
- *   - `fast_confirm`: schema-relaxed variant (`UNDERSTANDING_REPORT_SCHEMA_FAST_CONFIRM`)
- *     drops priorArt from `required`, on purpose: fast_confirm is for
- *     low-stakes prompts where the gate barely fires.
- *   - missing/unknown mode: legacy reports pre-date the mode field;
- *     enforcing on them would retroactively invalidate every historical
- *     report.
- *
- * v1 limits the enforced list to `priorArt` because that is the
- * concrete failure observed in dogfood. Broader schema enforcement
- * (e.g. empty `derivedTodos`) is a follow-up if the same class of
- * "agent skipped a required section" failure recurs.
- */
-export type ValidationResult = {
-    ok: true;
-    mode: string | null;
-} | {
-    ok: false;
-    field: string;
-    reason: string;
-};
-/**
- * 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 declare function validatePersistedReport(parsed: Record<string, unknown>): ValidationResult;
-/**
- * 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 declare function rewriteReportApproved(filePath: string, approvedAt: string, approvedBy: string, sessionId: string, boundedRaw?: string): {
-    previousStatus: string | null;
-    sessionIdStamped: boolean;
-};
-/**
- * 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 declare class ApprovedReportTooLargeError extends Error {
-    readonly bytes: number;
-    constructor(bytes: number);
-}
-/**
- * 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 declare function renderApprovedReport(raw: string, approvedAt: string, approvedBy: string, sessionId: string): {
-    text: string;
-    previousStatus: string | null;
-    sessionIdStamped: boolean;
-};
-/**
- * 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 declare function dedupeTaskIds(raw: string[]): string[];
-export declare function approveUnderstanding(opts?: ApproveUnderstandingOptions): Promise<ApproveUnderstandingResult>;