@lannguyensi/harness 0.41.0 → 0.42.0

package/dist/cli/pack/hook-solution-acceptance-writeguard.js

@@ -17,6 +17,40 @@
 //     (covers `echo >`, `$SOLUTION_VERDICT_DIR` spellings, `tee`, `mv`/`cp`/
 //     `ln`/`install`, `python3 -c '...path...'`, and `chmod`/`chattr` that
 //     would loosen perms) — or whose shell cwd is inside the dir.
+//   - Bash `cd` whose RESOLVED target is inside the verdict dir. `cd` itself
+//     is provably read-only (task fb67b402 added it to the shared
+//     read-only-bash floor: it mutates only the invoking shell's own cwd,
+//     never the filesystem), so it no longer reaches the "not read-only"
+//     checks below. But stepping into the dir is the setup half of a
+//     two-call forge (`cd <dir>` then, in a LATER un-chained Bash call,
+//     a bare relative write): this pre-check keeps that first step blocked
+//     as defense-in-depth, ahead of (not instead of) the cwd-inside check
+//     below, which is what actually closes the later relative-write call
+//     once cwd has genuinely moved. A `cd` target that `path.resolve`
+//     cannot literally evaluate does NOT get `cd`'s read-only fast path
+//     either: it falls through to the same reference-based checks as any
+//     other non-read-only Bash. `CD_TARGET_UNRESOLVABLE_CHARS` documents
+//     exactly WHICH expansions this enumerates (quoting, `$`/env-var,
+//     `~`, glob, and `{...}` brace expansion) — that list is what this
+//     check catches, not a claim that every shell-expansion class is
+//     closed. Known-open residual, pre-existing (not introduced by this
+//     branch, since it applies to `bashReferencesVerdictDir`'s textual
+//     match on ANY Bash command, not just `cd`): a backslash-escaped
+//     spelling of the leaf, e.g. `cd <parent>/solution\-verdicts`, still
+//     navigates into the dir under bash (verified against bash 3.2.57)
+//     while `bashReferencesVerdictDir` returns false — the backslash
+//     breaks the literal-leaf substring match and no metacharacter here
+//     triggers the glob/brace fallback either. Closing it needs
+//     shell-unescaping in the textual check itself, which is more than
+//     this task absorbs; do not assume the class is closed.
+//     A SECOND residual of the same class, and on a macOS operator
+//     machine the more reachable of the two: case variance.
+//     `cd <parent>/SOLUTION-VERDICTS` navigates into the dir on a
+//     case-insensitive APFS volume, but `isInsideDir` compares with a
+//     case-sensitive `path.relative` and the textual check uses a
+//     case-sensitive `includes`, so both return false. Also allowed:
+//     a trailing backslash, `cd <DIR>\`. Both pre-existing; closing
+//     them needs case-folding in the textual check.
 //
 // Pure reads (`cat <dir>/x.json`) are allowed so the guard is not over-broad.
 //
@@ -30,7 +64,10 @@
 // write paths above. A path constructed at runtime inside an interpreter
 // with no textual reference is NOT caught; marker signing (a cross-repo
 // follow-up) closes content-authenticity against an unguarded write
-// primitive.
+// primitive. The `cd`-target check added later (task fb67b402) has its own
+// enumerated, not exhaustive, expansion list — see the bullet above and
+// `CD_TARGET_UNRESOLVABLE_CHARS`'s docstring for the backslash-escaping
+// residual specifically.
 import { bashReferencesVerdictDir, isInsideDir, PACK_NAME, verdictDir as resolveVerdictDir, } from "../../policy-packs/builtin/solution-acceptance-runtime.js";
 import { isReadOnlyBashCommand } from "../../runtime/read-only-bash.js";
 import { checkHookPause, readStdin } from "./hook-bootstrap.js";
@@ -60,6 +97,94 @@ function bashCommandOf(toolInput) {
     const cmd = toolInput["command"];
     return typeof cmd === "string" ? cmd : "";
 }
+/**
+ * Extract `cd`'s destination argument from a Bash command string, or null
+ * when the command is not a `cd` invocation or has no statically resolvable
+ * destination. Whitespace-tokenized, same as `read-only-bash.ts`'s own
+ * classifier (this hook does not shell-parse either).
+ *
+ * Deliberately narrow:
+ *   - Only fires when the FIRST token is exactly `cd`. `env cd x` or a
+ *     chained `foo && cd x` do not match here (tokens[0] would be `env` /
+ *     `foo`); those are unaffected by this pre-check and are still governed
+ *     by the existing not-read-only + `bashReferencesVerdictDir` checks
+ *     below, which already close the `cd <parent> && write <relative>`
+ *     descent via the leaf-segment match.
+ *   - `cd`'s own flags (`-L`, `-P`, `-e`, `-@`, and combinations) are
+ *     skipped to find the first positional path argument.
+ *   - `cd -` (switch to `$OLDPWD`) and a bare `cd` (goes to `$HOME`) have no
+ *     destination this function can resolve without ambient shell state;
+ *     both return null (not flagged), the same conservative stance as the
+ *     rest of this module's enumerated-path checks.
+ *   - A single layer of surrounding quotes (`"..."` or `'...'`) is stripped
+ *     from the returned token before the caller does anything with it, so
+ *     `cd "<path>"` and `cd <path>` are treated identically (both the
+ *     resolved-path inside-dir check AND the unresolvable-chars check see
+ *     the same unquoted value). Without this, a quoted literal that merely
+ *     shares a text prefix with the verdict dir (`cd "<dir>-decoy"`) would
+ *     route to the textual leaf match and be wrongly blocked, while the
+ *     unquoted `cd <dir>-decoy` correctly passes via the resolved-path
+ *     check — spelling-dependent behavior for what is the same destination.
+ */
+function cdTargetArgument(command) {
+    const tokens = command.trim().split(/\s+/);
+    if (tokens[0] !== "cd")
+        return null;
+    for (let i = 1; i < tokens.length; i += 1) {
+        const t = tokens[i];
+        if (t === undefined)
+            break;
+        if (t === "-")
+            return null;
+        if (t.startsWith("-"))
+            continue;
+        return stripSurroundingQuotes(t);
+    }
+    return null;
+}
+/**
+ * Strip one layer of surrounding double or single quotes from `token`, or
+ * return it unchanged if it is not fully wrapped in a matching pair. Does
+ * NOT attempt any other shell-quoting semantics (no backslash-escape
+ * handling, no nested-quote handling) — this is a narrow normalization so a
+ * simple quoted literal reads the same as its unquoted form, not a shell
+ * parser.
+ */
+function stripSurroundingQuotes(token) {
+    if (token.length >= 2 &&
+        ((token.startsWith('"') && token.endsWith('"')) ||
+            (token.startsWith("'") && token.endsWith("'")))) {
+        return token.slice(1, -1);
+    }
+    return token;
+}
+/**
+ * Characters/sequences that make a `cd` destination token something
+ * `path.resolve` cannot literally evaluate: quoting (`"`, `'` — the residual
+ * case after `stripSurroundingQuotes` has already removed a clean single
+ * layer, e.g. an unbalanced or embedded quote), env-var expansion (`$`),
+ * home-directory expansion (`~`), shell globbing (`*`, `?`, `[`), and brace
+ * expansion (`{`, `}`, `,`). `path.resolve` treats the raw token as a
+ * literal path segment, so `cd "$SOLUTION_VERDICT_DIR"`, `cd
+ * ~/.../solution-verdicts`, or `cd <parent>/{solution-verdicts,x}` all
+ * resolve to a nonsense path that is never "inside" the dir even though a
+ * real shell would expand each of them TO (or, for the brace form, INTO)
+ * the dir. A `cd` target containing any of these must therefore NOT take
+ * the read-only fast path in `evaluateWriteGuard`: control must fall
+ * through to the same `bashReferencesVerdictDir` text-reference check any
+ * other non-read-only Bash command goes through, which DOES recognize
+ * these spellings (the env-var token, the `agent-grounding/solution-verdicts`
+ * tail, and — after the matching widening in
+ * `solution-acceptance-runtime.ts`'s glob-metacharacter test — glob- and
+ * brace-obscured leaf words).
+ *
+ * This list is enumerated, not exhaustive: it is exactly the expansion
+ * classes this check has been reasoned about, not a claim that every way a
+ * shell can rewrite a `cd` argument is covered. A known-open residual
+ * (pre-existing, not introduced by this check) is backslash escaping — see
+ * the module header's "Known-open residual" note.
+ */
+const CD_TARGET_UNRESOLVABLE_CHARS = /[$~*?[{},"']/;
 /**
  * Pure write-guard decision for a tool event. Exported for direct unit
  * testing of the full forge-attempt matrix without spinning up the CLI.
@@ -100,7 +225,28 @@ export function evaluateWriteGuard(toolName, toolInput, dir, cwd) {
         const command = bashCommandOf(toolInput);
         if (command === "")
             return { blocked: false, reason: "empty Bash command" };
-        if (isReadOnlyBashCommand(command)) {
+        // Defense-in-depth, ahead of the read-only fast path below: `cd` itself
+        // cannot write, but `cd`ing into the verdict dir is the setup half of a
+        // two-call forge (see the module header). Only a RESOLVED-path check
+        // (via the shared `isInsideDir`, not a substring match) so a sibling
+        // that merely shares a text prefix with the dir (`solution-verdicts-decoy`,
+        // or a parent directory of it) is not wrongly flagged.
+        const cdTarget = cdTargetArgument(command);
+        if (cdTarget !== null && isInsideDir(cdTarget, dir, cwd)) {
+            return {
+                blocked: true,
+                reason: `cd targets the harness-protected solution-verdict dir (${dir}); stepping into it would set up a later un-chained relative write to forge the verdict marker`,
+            };
+        }
+        // A `cd` target containing one of the enumerated unresolvable
+        // expansions (see `CD_TARGET_UNRESOLVABLE_CHARS`'s docstring for the
+        // exact list and its non-exhaustive scope) must not take `cd`'s
+        // read-only fast path below: without this, `cd "$SOLUTION_VERDICT_DIR"`
+        // etc. would be waved through by `isReadOnlyBashCommand` (true for ANY
+        // `cd`, per the shared read-only-bash floor) before ever reaching the
+        // reference check that recognizes these exact spellings.
+        const cdTargetUnresolvable = cdTarget !== null && CD_TARGET_UNRESOLVABLE_CHARS.test(cdTarget);
+        if (!cdTargetUnresolvable && isReadOnlyBashCommand(command)) {
             return { blocked: false, reason: "read-only Bash command" };
         }
         if (isInsideDir(".", dir, cwd)) {

package/dist/cli/pack/hook-solution-acceptance-writeguard.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-solution-acceptance-writeguard.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-solution-acceptance-writeguard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hook-solution-acceptance-writeguard.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-solution-acceptance-writeguard.ts"],"names":[],"mappings":"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"}

package/dist/cli/pack/understanding-report-schema-hint.js

@@ -53,7 +53,7 @@ export function renderReportSchemaHint() {
     // one pair implied exhaustiveness. The bullets below show the canonical
     // names; the parser's alias-tolerance is a quiet bonus, not something
     // the agent needs to choose between.
-    const intro = "Report format (parsed by `@lannguyensi/understanding-gate`): markdown with these ten sections, any heading level (#, ##, ###), names case-insensitive. Missing any section produces a parse-error under `.understanding-gate/parse-errors/` and the audit trail is empty even though the gate-approval marker still gets written.";
+    const intro = "Report format (parsed by `@lannguyensi/understanding-gate`): markdown with these ten sections, any heading level (#, ##, ###), names case-insensitive. Sections marked (list) need markdown list items ('- ' or '1.') in the body — a prose paragraph under a (list) heading is rejected the same as a missing section. Missing any section produces a parse-error under `.understanding-gate/parse-errors/` and the audit trail is empty even though the gate-approval marker still gets written.";
     const bullets = UNDERSTANDING_REPORT_REQUIRED_SECTIONS.map((s) => `  - ${s}`).join("\n");
     // Submission recipe (task 61fd36db): the Stop-hook producer fires only
     // at END of turn — after `harness approve understanding` already ran —

package/dist/cli/pack/understanding-report-schema-hint.js.map

@@ -1 +1 @@
-{"version":3,"file":"understanding-report-schema-hint.js","sourceRoot":"","sources":["../../../src/cli/pack/understanding-report-schema-hint.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wEAAwE;AACxE,EAAE;AACF,kEAAkE;AAClE,qEAAqE;AACrE,sEAAsE;AACtE,wEAAwE;AACxE,uEAAuE;AACvE,+CAA+C;AAC/C,EAAE;AACF,kEAAkE;AAClE,wDAAwD;AACxD,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,oEAAoE;AACpE,oEAAoE;AACpE,mEAAmE;AAEnE,MAAM,CAAC,MAAM,sCAAsC,GAAG;IACpD,mCAAmC;IACnC,8BAA8B;IAC9B,sBAAsB;IACtB,4BAA4B;IAC5B,oBAAoB;IACpB,uBAAuB;IACvB,qBAAqB;IACrB,cAAc;IACd,0BAA0B;IAC1B,qEAAqE;IACrE,yDAAyD;IACzD,kEAAkE;IAClE,kEAAkE;IAClE,qCAAqC;IACrC,kBAAkB;CACV,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB;IACpC,uEAAuE;IACvE,wEAAwE;IACxE,+DAA+D;IAC/D,yEAAyE;IACzE,oEAAoE;IACpE,wEAAwE;IACxE,sEAAsE;IACtE,qCAAqC;IACrC,MAAM,KAAK,GACT,mUAAmU,CAAC;IACtU,MAAM,OAAO,GAAG,sCAAsC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,uEAAuE;IACvE,uEAAuE;IACvE,mEAAmE;IACnE,oEAAoE;IACpE,sDAAsD;IACtD,MAAM,MAAM,GACV,yFAAyF;QACzF,sFAAsF;QACtF,4DAA4D;QAC5D,6BAA6B;QAC7B,uBAAuB;QACvB,wBAAwB,CAAC;IAC3B,OAAO,GAAG,KAAK,KAAK,OAAO,KAAK,MAAM,EAAE,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"understanding-report-schema-hint.js","sourceRoot":"","sources":["../../../src/cli/pack/understanding-report-schema-hint.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wEAAwE;AACxE,EAAE;AACF,kEAAkE;AAClE,qEAAqE;AACrE,sEAAsE;AACtE,wEAAwE;AACxE,uEAAuE;AACvE,+CAA+C;AAC/C,EAAE;AACF,kEAAkE;AAClE,wDAAwD;AACxD,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,oEAAoE;AACpE,oEAAoE;AACpE,mEAAmE;AAEnE,MAAM,CAAC,MAAM,sCAAsC,GAAG;IACpD,mCAAmC;IACnC,8BAA8B;IAC9B,sBAAsB;IACtB,4BAA4B;IAC5B,oBAAoB;IACpB,uBAAuB;IACvB,qBAAqB;IACrB,cAAc;IACd,0BAA0B;IAC1B,qEAAqE;IACrE,yDAAyD;IACzD,kEAAkE;IAClE,kEAAkE;IAClE,qCAAqC;IACrC,kBAAkB;CACV,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB;IACpC,uEAAuE;IACvE,wEAAwE;IACxE,+DAA+D;IAC/D,yEAAyE;IACzE,oEAAoE;IACpE,wEAAwE;IACxE,sEAAsE;IACtE,qCAAqC;IACrC,MAAM,KAAK,GACT,oeAAoe,CAAC;IACve,MAAM,OAAO,GAAG,sCAAsC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,uEAAuE;IACvE,uEAAuE;IACvE,mEAAmE;IACnE,oEAAoE;IACpE,sDAAsD;IACtD,MAAM,MAAM,GACV,yFAAyF;QACzF,sFAAsF;QACtF,4DAA4D;QAC5D,6BAA6B;QAC7B,uBAAuB;QACvB,wBAAwB,CAAC;IAC3B,OAAO,GAAG,KAAK,KAAK,OAAO,KAAK,MAAM,EAAE,CAAC;AAC3C,CAAC"}

package/dist/cli/record/index.d.ts

@@ -0,0 +1,64 @@
+import { type LedgerWriteFn } from "../../runtime/ledger-writer.js";
+import { type ResolveReadSessionOptions } from "../../runtime/session-id.js";
+import { type LoaderOptions } from "../loader.js";
+/** Options shared by every `record` verb. */
+export interface RecordCommonOptions extends LoaderOptions {
+    /** Working directory used for git-context resolution. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Defaults to `process.stderr`. Warnings and error reasons land here. */
+    stderr?: NodeJS.WritableStream;
+    /** Explicit session id (overrides env + transcript discovery). */
+    session?: string;
+    /** Per-call ledger timeout in ms. */
+    ledgerTimeoutMs?: number;
+    /**
+     * Inject the read-path session resolver (test seam). Production uses
+     * `resolveReadSessionId` from `runtime/session-id`, the same
+     * precedence chain `harness audit` / `harness explain --trace` use.
+     */
+    resolveSession?: (explicit: string | undefined, opts: ResolveReadSessionOptions) => string;
+    /** Inject the ledger writer (test seam). */
+    writeLedger?: LedgerWriteFn;
+}
+/** Structured outcome of a `record` verb — testable without spawning a process. */
+export interface RecordResult {
+    /** 0 on success; EX_USAGE (64) for a bad argument, EX_FAIL (1) for a runtime failure. */
+    exitCode: number;
+    /** Whether the ledger fact was actually written. */
+    wrote: boolean;
+    /** The exact content string written (or that would have been written); "" on early validation failure. */
+    content: string;
+    /** Resolved session id ("" only when validation failed before session resolution). */
+    sessionId: string;
+    /** Resolved branch tag ("" when the verb does not use one, or resolution failed). */
+    branch: string;
+    /** Human-readable explanation of a non-write outcome. */
+    reason?: string;
+}
+export interface RecordReviewOptions extends RecordCommonOptions {
+    /** PR number (or identifier) — required, non-empty. */
+    pr: string;
+    /** Explicit base-branch override; see resolveBase() for the fallback chain. */
+    base?: string;
+    /** Explicit branch override (otherwise resolved via resolveGitContext(cwd)). */
+    branch?: string;
+    /** Free-form review summary — required, non-empty. */
+    summary: string;
+}
+export declare function runRecordReview(opts: RecordReviewOptions): Promise<RecordResult>;
+export interface RecordReviewSubagentOptions extends RecordCommonOptions {
+    /** agent-tasks task id — required, non-empty. */
+    task: string;
+    /** Reviewer verdict — required, non-empty. */
+    verdict: string;
+    /** Explicit branch override (otherwise resolved via resolveGitContext(cwd)). */
+    branch?: string;
+    /** Optional free-form summary appended after the verdict. */
+    summary?: string;
+}
+export declare function runRecordReviewSubagent(opts: RecordReviewSubagentOptions): Promise<RecordResult>;
+export interface RecordDogfoodOptions extends RecordCommonOptions {
+    /** End-to-end smoke summary — required, non-empty. */
+    summary: string;
+}
+export declare function runRecordDogfood(opts: RecordDogfoodOptions): Promise<RecordResult>;

package/dist/cli/record/index.js

@@ -0,0 +1,211 @@
+// `harness record {review,review-subagent,dogfood}` — operator/agent-
+// driven evidence-ledger producers for the review-before-merge,
+// review-subagent-before-pr-create, and dogfood-before-release gate
+// families (see src/cli/init/templates.ts for the exact policy
+// definitions and tag shapes these verbs feed).
+//
+// Unlike `harness session-start preflight` (a SessionStart hook that
+// MUST exit 0 on every path so it never breaks the session loop), the
+// `record` verbs are INTERACTIVE: an agent or operator invokes them
+// deliberately to attach a review verdict / dogfood summary to the
+// ledger. A failure here (unreachable ledger, no git context, an empty
+// summary) is a real error the caller needs to see and react to, so
+// every verb exits non-zero with a clear stderr message on failure
+// instead of degrading silently. Each verb still returns a structured
+// `RecordResult` (not just a thrown error) so both paths are testable
+// without spawning a process — same "degrade-with-reason" convention
+// `runSessionStartPreflight` uses.
+//
+// Composition mirrors session-start/index.ts: build the ledger write
+// via the manifest's declared `grounding-mcp` server (through the
+// shared `resolveManifestLedgerWriter` — see runtime/ledger-writer.ts),
+// resolve branch via `resolveGitContext` (the SAME function the
+// preflight-before-* gates use) and session via `resolveReadSessionId`,
+// with `--branch` / `--session` as explicit overrides. No new JSON-RPC
+// or subprocess code: every ledger write goes through the existing
+// `addLedgerFact` primitive.
+import { findGitEntry, resolveCommonDir, resolveGitContext, resolveOriginHeadBase, } from "../../runtime/git-context.js";
+import { resolveManifestLedgerWriter } from "../../runtime/ledger-writer.js";
+import { resolveReadSessionId, } from "../../runtime/session-id.js";
+import { EX_FAIL, EX_USAGE } from "../exit-codes.js";
+import { loadManifest } from "../loader.js";
+const LEDGER_SOURCE_REVIEW = "harness-record-review";
+const LEDGER_SOURCE_REVIEW_SUBAGENT = "harness-record-review-subagent";
+const LEDGER_SOURCE_DOGFOOD = "harness-record-dogfood";
+function resolveSession(opts) {
+    const resolve = opts.resolveSession ?? resolveReadSessionId;
+    return resolve(opts.session, {});
+}
+/**
+ * Write one ledger fact via the manifest's declared `grounding-mcp`
+ * server (or the injected `opts.writeLedger` test seam). Mirrors the
+ * manifest-wiring block `runSessionStartPreflight` uses, factored
+ * through the shared `resolveManifestLedgerWriter` helper.
+ */
+async function writeLedgerFact(opts, sessionId, source, content) {
+    let writeLedger = opts.writeLedger;
+    if (!writeLedger) {
+        let manifest;
+        try {
+            manifest = loadManifest(opts).manifest;
+        }
+        catch (err) {
+            return { ok: false, reason: `manifest load failed: ${err.message}` };
+        }
+        const resolved = resolveManifestLedgerWriter(manifest, {
+            ...(opts.ledgerTimeoutMs !== undefined ? { ledgerTimeoutMs: opts.ledgerTimeoutMs } : {}),
+        });
+        if (!resolved.ok) {
+            return { ok: false, reason: `${resolved.reason}; cannot record ${source} tag` };
+        }
+        writeLedger = resolved.write;
+    }
+    const result = await writeLedger({ sessionId, content, source });
+    if (!result.ok) {
+        return { ok: false, reason: `ledger write failed: ${result.reason ?? "unknown error"}` };
+    }
+    return { ok: true };
+}
+/**
+ * Shared setup every verb runs first: a `note()` sink prefixed with the
+ * verb's own name (so stderr lines are attributable when several verbs
+ * run in a script), the resolved cwd, and the resolved session id.
+ * Session id is resolved this early because `record dogfood`'s content
+ * embeds it directly (`dogfood:${sessionId}`).
+ */
+function initRecordVerb(opts, verbName) {
+    const stderr = opts.stderr ?? process.stderr;
+    const note = (msg) => {
+        stderr.write(`harness record ${verbName}: ${msg}\n`);
+    };
+    return { note, cwd: opts.cwd ?? process.cwd(), sessionId: resolveSession(opts) };
+}
+/**
+ * Trim `value` and refuse it if empty (a required flag / positional
+ * argument left blank). Returns the ready-to-`return`ed EX_USAGE
+ * `RecordResult` on failure so callers do not repeat that construction
+ * — shared by every "--pr / --task / --verdict / summary must not be
+ * empty" check across the three verbs.
+ */
+function requireNonEmpty(value, flagLabel, sessionId, note) {
+    const trimmed = (value ?? "").trim();
+    if (trimmed.length === 0) {
+        const reason = `${flagLabel} must not be empty`;
+        note(reason);
+        return {
+            ok: false,
+            result: { exitCode: EX_USAGE, wrote: false, content: "", sessionId, branch: "", reason },
+        };
+    }
+    return { ok: true, value: trimmed };
+}
+/**
+ * Resolve the branch tag `review` and `review-subagent` both require:
+ * explicit `--branch` wins, otherwise `resolveGitContext(cwd)` (the SAME
+ * function the preflight-before-* gates use). Returns the ready-to-
+ * `return`ed failure `RecordResult` on the shared "cannot resolve any
+ * branch" degrade path so callers do not repeat that construction.
+ */
+function resolveRequiredBranch(cwd, explicitBranch, sessionId, note) {
+    const gitContext = resolveGitContext(cwd);
+    const branch = (explicitBranch ?? "").trim() || gitContext.branch;
+    if (branch.length === 0) {
+        const reason = "no branch resolvable (cwd is not inside a git work tree, or HEAD is detached); pass --branch <name>";
+        note(reason);
+        return {
+            ok: false,
+            result: { exitCode: EX_FAIL, wrote: false, content: "", sessionId, branch: "", reason },
+        };
+    }
+    return { ok: true, branch };
+}
+/**
+ * Shared tail every verb runs last: write the fact, translate a failure
+ * into the degrade-with-reason `RecordResult` shape, or report success.
+ */
+async function finishRecordWrite(opts, sessionId, branch, source, content, note) {
+    const written = await writeLedgerFact(opts, sessionId, source, content);
+    if (!written.ok) {
+        note(written.reason);
+        return { exitCode: EX_FAIL, wrote: false, content, sessionId, branch, reason: written.reason };
+    }
+    return { exitCode: 0, wrote: true, content, sessionId, branch };
+}
+// ---------------------------------------------------------------------------
+// Base-branch resolution for `record review` (--base flag > origin/HEAD
+// filesystem fallback > omit with a loud stderr warning). No `gh`
+// shell-out: everything is read straight off the `.git` directory,
+// reusing runtime/git-context.ts's exported `findGitEntry` walk instead
+// of re-implementing it. `resolveOriginHeadBase` / `resolveCommonDir`
+// themselves now live in runtime/git-context.ts too (task post-merge-gate,
+// T-001) so `policy-packs/builtin/post-merge-gate-runtime.ts` can share
+// them without a policy-pack module reaching into `cli/`; imported here
+// unchanged.
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the base branch for `record review`: explicit `--base` wins,
+ * then the origin/HEAD filesystem fallback, then omission with a loud
+ * stderr warning (never a silent gap — the operator needs to know the
+ * `review:<base>` tag did not land).
+ */
+function resolveBase(cwd, explicitBase, note) {
+    const flag = (explicitBase ?? "").trim();
+    if (flag.length > 0)
+        return flag;
+    const gitDir = findGitEntry(cwd)?.gitDir;
+    if (gitDir) {
+        const base = resolveOriginHeadBase(resolveCommonDir(gitDir));
+        if (base)
+            return base;
+    }
+    note("no --base given and origin/HEAD could not be resolved (checked " +
+        "refs/remotes/origin/HEAD and packed-refs); omitting the review:<base> tag. " +
+        "Pass --base <branch> to record it explicitly.");
+    return undefined;
+}
+export async function runRecordReview(opts) {
+    const { note, cwd, sessionId } = initRecordVerb(opts, "review");
+    const summaryResult = requireNonEmpty(opts.summary, "summary", sessionId, note);
+    if (!summaryResult.ok)
+        return summaryResult.result;
+    const summary = summaryResult.value;
+    const prResult = requireNonEmpty(opts.pr, "--pr", sessionId, note);
+    if (!prResult.ok)
+        return prResult.result;
+    const pr = prResult.value;
+    const branchResult = resolveRequiredBranch(cwd, opts.branch, sessionId, note);
+    if (!branchResult.ok)
+        return branchResult.result;
+    const branch = branchResult.branch;
+    const base = resolveBase(cwd, opts.base, note);
+    const content = `review:${pr} review:${branch}${base ? ` review:${base}` : ""} — ${summary}`;
+    return finishRecordWrite(opts, sessionId, branch, LEDGER_SOURCE_REVIEW, content, note);
+}
+export async function runRecordReviewSubagent(opts) {
+    const { note, cwd, sessionId } = initRecordVerb(opts, "review-subagent");
+    const taskResult = requireNonEmpty(opts.task, "--task", sessionId, note);
+    if (!taskResult.ok)
+        return taskResult.result;
+    const task = taskResult.value;
+    const verdictResult = requireNonEmpty(opts.verdict, "--verdict", sessionId, note);
+    if (!verdictResult.ok)
+        return verdictResult.result;
+    const verdict = verdictResult.value;
+    const branchResult = resolveRequiredBranch(cwd, opts.branch, sessionId, note);
+    if (!branchResult.ok)
+        return branchResult.result;
+    const branch = branchResult.branch;
+    const summary = typeof opts.summary === "string" ? opts.summary.trim() : "";
+    const content = `review-subagent:${task} review-subagent:${branch} verdict:${verdict}${summary.length > 0 ? ` — ${summary}` : ""}`;
+    return finishRecordWrite(opts, sessionId, branch, LEDGER_SOURCE_REVIEW_SUBAGENT, content, note);
+}
+export async function runRecordDogfood(opts) {
+    const { note, sessionId } = initRecordVerb(opts, "dogfood");
+    const summaryResult = requireNonEmpty(opts.summary, "summary", sessionId, note);
+    if (!summaryResult.ok)
+        return summaryResult.result;
+    const summary = summaryResult.value;
+    const content = `dogfood:${sessionId} — ${summary}`;
+    return finishRecordWrite(opts, sessionId, "", LEDGER_SOURCE_DOGFOOD, content, note);
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/record/index.js.map

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

package/dist/cli/session-start/index.d.ts

@@ -35,6 +35,13 @@ export interface SessionStartPreflightOptions extends LoaderOptions {
     ledgerTimeoutMs?: number;
     /** Inject the preflight runner (tests). */
     runPreflight?: (cwd: string, timeoutMs: number) => Promise<RunPreflightResult>;
+    /**
+     * Directory the not-ready diagnostic JSON is persisted to (task
+     * T-001). Test seam — production defaults to `~/.harness/logs`
+     * (`os.homedir()`-based). Always pass a tmp dir in tests so nothing
+     * ever touches the operator's real `~/.harness/logs/`.
+     */
+    logDir?: string;
     /** Inject the ledger writer (tests). */
     writeLedger?: (args: {
         sessionId: string;