@lannguyensi/harness 0.50.0 → 0.52.0

package/dist/cli/doctor/settings-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-drift.js","sourceRoot":"","sources":["../../../src/cli/doctor/settings-drift.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,yEAAyE;AACzE,oEAAoE;AACpE,qEAAqE;AACrE,mEAAmE;AACnE,oEAAoE;AACpE,uEAAuE;AACvE,sEAAsE;AACtE,4DAA4D;AAC5D,oEAAoE;AACpE,iEAAiE;AACjE,EAAE;AACF,qEAAqE;AACrE,iEAAiE;AACjE,EAAE;AACF,gEAAgE;AAChE,8DAA8D;AAC9D,yEAAyE;AACzE,yEAAyE;AACzE,oDAAoD;AACpD,uEAAuE;AACvE,8EAA8E;AAC9E,sEAAsE;AACtE,wEAAwE;AACxE,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,4DAA4D;AAC5D,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,0DAA0D;AAC1D,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,gEAAgE;AAChE,oCAAoC;AACpC,EAAE;AACF,uEAAuE;AACvE,qEAAqE;AACrE,mCAAmC;AAEnC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAoB,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,mBAAmB,IAAI,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAejF,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAUD,SAAS,eAAe,CAAC,CAAe;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAAC,UAAmB;IAChD,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,GAAG,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,SAAS;YAC/B,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAK,CAAC,SAAS,CAAY,CAAC,CAAC,CAAC,EAAE,CAAC;YACzF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,SAAS;YACpC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;oBAAE,SAAS;gBAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,MAAM,CAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxE,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,SAAS,CAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjF,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,aAAa,CAAC,QAAiC;IACtD,MAAM,WAAW,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,IAAI,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;IACxC,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAED,SAAS,YAAY,CACnB,IAAuB,EACvB,QAAiC,EACjC,cAAmC,EACnC,QAAkB;IAElB,iEAAiE;IACjE,gEAAgE;IAChE,sEAAsE;IACtE,sEAAsE;IACtE,sEAAsE;IACtE,mDAAmD;IACnD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,YAAY,4BAA4B,CAAC,CAAC;QAChE,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC;IAEpB,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IACxE,MAAM,iBAAiB,GAAG,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oCAAoC,CAAC;IAEvE,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACtD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QACxD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CACX,kCAAkC,IAAI,CAAC,YAAY,8BAA8B,QAAQ,GAAG,MAAM,EAAE,CACrG,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CACX,kCAAkC,IAAI,CAAC,YAAY,iBAAiB,YAAY,OAAO,QAAQ,GAAG,MAAM,EAAE,CAC3G,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC;IACzG,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,gBAAgB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QACvD,QAAQ,CAAC,IAAI,CACX,mBAAmB,IAAI,CAAC,YAAY,0BAA0B,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,OAAO,IAAI,GAAG,GAAG,MAAM,EAAE,CACrG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,QAAgB;IAC1C,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC7C,OAAO,IAAI,GAAG,CACZ,WAAW;SACR,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CACpC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAAY;IACpD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,YAAY,KAAK,YAAY;QAAE,OAAO,GAAG,CAAC;IAC9C,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9F,IAAI,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAeD,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACnD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;QAC5D,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAC7B,CAAC;IAED,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC9D,IAAI,QAAQ,GAA4B,EAAE,CAAC;IAC3C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,QAAQ,CAAC,MAAM,CAAC;YAAE,QAAQ,GAAG,MAAM,CAAC;IAC1C,CAAC;IAED,MAAM,cAAc,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEzD,MAAM,gBAAgB,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,MAAM,UAAU,GAAwB;QACtC;YACE,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,eAAe,CAAC;YAChE,YAAY,EAAE,uBAAuB;SACtC;QACD;YACE,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,qBAAqB,CAAC;YACtE,YAAY,EAAE,6BAA6B;SAC5C;QACD;YACE,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC;YAC5C,YAAY,EAAE,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC;SACpD;KACF,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC"}

package/dist/cli/doctor/types.d.ts

@@ -9,6 +9,11 @@ import type { NpmBinReport } from "./npm-bin-path.js";
 import type { RogueLedgerDb } from "./rogue-ledger.js";
 import type { UnderstandingModeEnvDivergence } from "./understanding-mode-env.js";
 import type { ToolchainParitySection } from "./toolchain-parity.js";
+import type { UgAutoApprovalsSection } from "./ug-auto-approvals.js";
+import type { UgDelegationsSection } from "./ug-delegations.js";
+import type { SettingsDriftSection } from "./settings-drift.js";
+import type { AutoApproveModeWarning } from "./auto-approve-mode.js";
+import type { CodexConfigDriftSection } from "./codex-config-drift.js";
 /**
  * Phase 6 #6 follow-up — doctor target identifier. Distinct from
  * `Runtime` (which gates `harness apply --runtime`): doctor only adds
@@ -379,6 +384,65 @@ export interface DoctorReport {
      * `understanding-mode-env.ts` for the full rationale.
      */
     understandingModeEnv?: UnderstandingModeEnvDivergence;
+    /**
+     * Auto-approval listing + last-N metric (ADR
+     * docs/decisions/2026-08-27-ug-auto-mode-approval.md slice 1,
+     * agent-tasks 74b4b17d, "Audit and doctor"). Present only when the
+     * `understanding-before-execution` pack is declared and enabled
+     * (mirrors `understandingModeEnv`'s gate) — a manifest that never
+     * uses the pack has no `.approvals/` markers this listing owns an
+     * opinion about. Purely informational (`ℹ`); never rolls into
+     * `warningCount`.
+     */
+    ugAutoApprovals?: UgAutoApprovalsSection;
+    /**
+     * Delegations-on-disk metric (same ADR, slice 3, "Audit and doctor",
+     * agent-tasks 37ad0b05): `total`/`expired`/`unreadable` counts
+     * from `harness.generated/.delegations/`, distinct from
+     * `ugAutoApprovals` (which reads `.approvals/` only). Present only
+     * when the `understanding-before-execution` pack is declared and
+     * enabled (mirrors `ugAutoApprovals`'s gate). `delegationsDirPresent`
+     * mirrors `ugAutoApprovals`'s `approvalsDirPresent`: the rendered line
+     * stays silent when `.delegations/` does not exist at all, and shows
+     * the zero-count line when it exists but is empty (both cases resolve
+     * `total`/`expired`/`unreadable` to `0`). Informational (`ℹ`) unless
+     * `unreadable > 0`, in which case it rolls one warning into
+     * `warningCount`.
+     */
+    ugDelegations?: UgDelegationsSection;
+    /**
+     * `auto_approve` configured without `mode: grill_me` (agent-tasks
+     * abfad738, follow-up of ADR
+     * docs/decisions/2026-08-27-ug-auto-mode-approval.md slice 1).
+     * Present only when the pack is declared and enabled AND
+     * `config.auto_approve` parses as a valid opt-in block. Always
+     * advisory (rolls into `warningCount`, never `errorCount`). See
+     * `auto-approve-mode.ts` for the full rationale.
+     */
+    ugAutoApproveMode?: AutoApproveModeWarning;
+    /**
+     * Settings-drift compensating control (same ADR, threat model (c)): a
+     * `permissions.defaultMode` or hook entry present in a live Claude
+     * Code settings file but absent from harness's own last-apply
+     * snapshot. Present only when the understanding-gate pack is enabled
+     * AND `harness apply` has run at least once for this manifest
+     * (`harness.generated/` exists) — otherwise there is no baseline to
+     * compare against and nothing to say. `warnings` roll into
+     * `warningCount`; `notes` never do.
+     */
+    settingsDrift?: SettingsDriftSection;
+    /**
+     * Codex counterpart of `settingsDrift` (follow-up of slice 2 of the
+     * same ADR, agent-tasks f59ea0eb): a live `approval_policy = "never"`
+     * or full-access `default_permissions` selection in `$CODEX_HOME
+     * /config.toml` or `<repo>/.codex/config.toml`. Present only when the
+     * understanding-gate pack's `auto_approve.harnesses` lists `codex`;
+     * a repo that never opted Codex into the auto path has no live signal
+     * for this key to pre-set. Unlike `settingsDrift`, this always warns
+     * while the key is present and the repo is opted in (not gated on
+     * drift since the last apply); `warnings` roll into `warningCount`.
+     */
+    codexConfigDrift?: CodexConfigDriftSection;
     memory: MemoryReport;
     hooks: HookEntryReport[];
     policies: PolicyEntryReport[];
@@ -478,5 +542,10 @@ export interface DoctorReport {
 export type { NpmBinReport } from "./npm-bin-path.js";
 export type { ClaudeMcpRegistrationSection, ClaudeMcpEntryReport } from "./claude-mcp.js";
 export type { UnderstandingModeEnvDivergence } from "./understanding-mode-env.js";
+export type { UgAutoApprovalsSection, AutoApprovalListingEntry } from "./ug-auto-approvals.js";
+export type { UgDelegationsSection } from "./ug-delegations.js";
+export type { AutoApproveModeWarning } from "./auto-approve-mode.js";
+export type { SettingsDriftSection } from "./settings-drift.js";
+export type { CodexConfigDriftSection } from "./codex-config-drift.js";
 export type { ToolchainParitySection, ToolchainParityPeerReport } from "./toolchain-parity.js";
 export type { Manifest, McpProbeResult, MemoryReport, StaleMemory, CodexTargetReport, RogueLedgerDb, };

package/dist/cli/doctor/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cli/doctor/types.ts"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,UAAU,CAAU,CAAC;AAGnE,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAClG,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cli/doctor/types.ts"],"names":[],"mappings":"AAiBA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,UAAU,CAAU,CAAC;AAGnE,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAClG,CAAC"}

package/dist/cli/doctor/ug-auto-approvals.d.ts

@@ -0,0 +1,40 @@
+/** Default doctor window when `--recent-sessions` is not passed. */
+export declare const DEFAULT_RECENT_SESSIONS = 20;
+export interface AutoApprovalListingEntry {
+    sessionId: string;
+    mode: string;
+    harness: string;
+    approvedAt: string;
+}
+export interface UgAutoApprovalsSection {
+    /** Whether `<generatedDir>/.approvals/` exists at all. */
+    approvalsDirPresent: boolean;
+    /** The `recentSessions` window that was applied. */
+    windowSize: number;
+    /** Auto approvals among the newest `windowSize` session markers. */
+    autoApprovedCount: number;
+    /** Per-mode breakdown of `autoApprovedCount` (e.g. `{bypassPermissions: 3}`). */
+    byMode: Record<string, number>;
+    /** Per-harness breakdown of `autoApprovedCount` (e.g. `{"claude-code": 3}`). */
+    byHarness: Record<string, number>;
+    /** `(sessionId, mode, approvedAt)` for each auto approval in the window, newest first. */
+    entries: AutoApprovalListingEntry[];
+    /**
+     * Session markers whose body could not be read as JSON with a
+     * parseable `approvedAt` (corrupt file, non-JSON content, missing
+     * `approvedAt`). Excluded from the window (there is no timestamp to
+     * sort them by) and never counted as auto approvals; surfaced as a
+     * single summary count instead of per-file noise.
+     */
+    unreadableCount: number;
+}
+/**
+ * Build the auto-approval listing + last-N metric. Pure filesystem read;
+ * never throws for ordinary "nothing to see" states (missing
+ * `.approvals/`, empty directory, every marker unreadable) — those all
+ * resolve to an empty-ish section rather than an exception, mirroring
+ * the rest of doctor's read-only checks.
+ */
+export declare function buildUgAutoApprovals(generatedDir: string, opts: {
+    recentSessions: number;
+}): UgAutoApprovalsSection;

package/dist/cli/doctor/ug-auto-approvals.js

@@ -0,0 +1,116 @@
+// Doctor visibility half of ADR docs/decisions/2026-08-27-ug-auto-mode-approval.md
+// slice 1 (agent-tasks 74b4b17d): the "auto approvals in the last N
+// sessions" listing named in the ADR's "Audit and doctor" section and
+// slice 1 acceptance criterion 7.
+//
+// Scans `<generatedDir>/.approvals/` for SESSION markers (skips the
+// per-task markers named `task-<id>` and the branch-protection markers
+// named `branch-protection-<sid>`, neither of which is a session
+// approval), sorts the readable ones newest-first by `approvedAt`,
+// takes the newest `recentSessions` of them, and reports how many of
+// THOSE were minted by the auto path (`approvedBy` starting with
+// `auto-mode:`, see auto-approve.ts's `parseAutoApprovedBy`).
+//
+// This is an AUDIT SURFACE, not a security check: it never verifies a
+// marker's HMAC signature (that is `checkApprovalMarker`'s job at gate
+// time; a forged marker still gets rejected there regardless of what
+// this listing shows) and it never blocks or writes anything.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readRegularFileRejectingSymlink } from "../../io/read-regular-file.js";
+import { safeJsonParse } from "../../io/safe-json-parse.js";
+import { BRANCH_PROTECTION_MARKER_PREFIX } from "../../policy-packs/builtin/branch-protection-runtime.js";
+import { APPROVAL_MARKER_DIRNAME, APPROVAL_MARKER_TASK_PREFIX, parseAutoApprovedBy, } from "../../policy-packs/builtin/understanding-before-execution/index.js";
+/** Default doctor window when `--recent-sessions` is not passed. */
+export const DEFAULT_RECENT_SESSIONS = 20;
+function emptySection(windowSize) {
+    return {
+        approvalsDirPresent: false,
+        windowSize,
+        autoApprovedCount: 0,
+        byMode: {},
+        byHarness: {},
+        entries: [],
+        unreadableCount: 0,
+    };
+}
+/**
+ * Build the auto-approval listing + last-N metric. Pure filesystem read;
+ * never throws for ordinary "nothing to see" states (missing
+ * `.approvals/`, empty directory, every marker unreadable) — those all
+ * resolve to an empty-ish section rather than an exception, mirroring
+ * the rest of doctor's read-only checks.
+ */
+export function buildUgAutoApprovals(generatedDir, opts) {
+    const windowSize = opts.recentSessions;
+    const dir = path.join(generatedDir, APPROVAL_MARKER_DIRNAME);
+    let dirents;
+    try {
+        dirents = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return emptySection(windowSize);
+    }
+    const readable = [];
+    let unreadableCount = 0;
+    for (const d of dirents) {
+        const name = d.name;
+        if (name.startsWith(APPROVAL_MARKER_TASK_PREFIX))
+            continue;
+        if (name.startsWith(BRANCH_PROTECTION_MARKER_PREFIX))
+            continue;
+        const full = path.join(dir, name);
+        const read = readRegularFileRejectingSymlink(full);
+        // A symlink / non-regular / raced-away entry is not a session marker
+        // this listing owns an opinion about; skip silently rather than
+        // counting it as "unreadable" (that count is for a FILE we expected
+        // to be a marker but could not parse).
+        if (read.kind === "symlink" || read.kind === "not-regular" || read.kind === "missing") {
+            continue;
+        }
+        if (read.kind === "unreadable") {
+            unreadableCount++;
+            continue;
+        }
+        const parsed = safeJsonParse(read.content);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            unreadableCount++;
+            continue;
+        }
+        const obj = parsed;
+        const approvedAt = obj["approvedAt"];
+        if (typeof approvedAt !== "string" || Number.isNaN(Date.parse(approvedAt))) {
+            unreadableCount++;
+            continue;
+        }
+        readable.push({ sessionId: name, approvedAt, approvedBy: obj["approvedBy"] });
+    }
+    readable.sort((a, b) => Date.parse(b.approvedAt) - Date.parse(a.approvedAt));
+    const windowed = readable.slice(0, windowSize);
+    const byMode = {};
+    const byHarness = {};
+    const entries = [];
+    for (const m of windowed) {
+        const parsedAuto = parseAutoApprovedBy(m.approvedBy);
+        if (parsedAuto === null)
+            continue;
+        byMode[parsedAuto.mode] = (byMode[parsedAuto.mode] ?? 0) + 1;
+        byHarness[parsedAuto.harness] = (byHarness[parsedAuto.harness] ?? 0) + 1;
+        entries.push({
+            sessionId: m.sessionId,
+            mode: parsedAuto.mode,
+            harness: parsedAuto.harness,
+            approvedAt: m.approvedAt,
+        });
+    }
+    return {
+        approvalsDirPresent: true,
+        windowSize,
+        autoApprovedCount: entries.length,
+        byMode,
+        byHarness,
+        entries,
+        unreadableCount,
+    };
+}
+//# sourceMappingURL=ug-auto-approvals.js.map

package/dist/cli/doctor/ug-auto-approvals.js.map

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

package/dist/cli/doctor/ug-delegations.d.ts

@@ -0,0 +1,26 @@
+export interface UgDelegationsSection {
+    /** Whether `<generatedDir>/.delegations/` exists at all. */
+    delegationsDirPresent: boolean;
+    /** Delegation files found in `.delegations/`, readable or not. */
+    total: number;
+    /** Of `total`, how many parsed with an `expires` segment in the past. */
+    expired: number;
+    /** Of `total`, how many were not valid JSON, or failed `parseDelegationApprovedBy`. */
+    unreadable: number;
+}
+/**
+ * Build the delegations-on-disk doctor metric. Pure filesystem read;
+ * never throws for "nothing to see" states (missing `.delegations/`,
+ * empty directory, every file unreadable), those all resolve to a
+ * zero-ish section, mirroring `buildUgAutoApprovals`. `total`/`expired`/
+ * `unreadable` read `0` for both an EMPTY and a MISSING directory; only
+ * `delegationsDirPresent` tells them apart, the same way
+ * `approvalsDirPresent` does for `buildUgAutoApprovals`, doctor's
+ * render layer uses it to stay silent when there is truly nothing on
+ * disk (`format.ts`'s own "no line for a check that found nothing"
+ * convention) while still rendering the zero-count line for a
+ * `harness delegate`-touched, now-empty directory.
+ */
+export declare function buildUgDelegations(generatedDir: string, opts?: {
+    now?: Date;
+}): UgDelegationsSection;

package/dist/cli/doctor/ug-delegations.js

@@ -0,0 +1,112 @@
+// Doctor visibility for slice 3 delegations (ADR
+// docs/decisions/2026-08-27-ug-auto-mode-approval.md, "Audit and
+// doctor", agent-tasks 37ad0b05): "delegations on disk: <count>
+// (<count> expired)" from `<generatedDir>/.delegations/`, distinct from
+// the `.approvals/` auto-approval listing in `ug-auto-approvals.ts`.
+//
+// SEPARATE DIRECTORY, DELIBERATELY: a delegation never lands in
+// `.approvals/` (delegation-markers.ts's module header), so this scan
+// reads `DELEGATION_MARKER_DIRNAME` (".delegations") only and never
+// touches the approvals directory `ug-auto-approvals.ts` owns. Mirrors
+// that module's read-only-audit shape (no signature verification here
+// either; a forged delegation still gets rejected by the dedicated
+// verifier at gate time, `delegation-markers.ts`'s `verifyDelegation`)
+// but does not share its code: the two scans read different
+// directories, filter differently (no task-marker / branch-protection
+// prefix skip here), and count differently (an approval count vs. an
+// expiry count), so a shared helper would mostly be parameters threading
+// through an otherwise-empty shell. `npm run check:duplication` is the
+// backstop if that stops being true.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readRegularFileRejectingSymlink } from "../../io/read-regular-file.js";
+import { safeJsonParse } from "../../io/safe-json-parse.js";
+import { DELEGATION_MARKER_DIRNAME, parseDelegationApprovedBy, } from "../../policy-packs/builtin/understanding-before-execution/index.js";
+function emptySection() {
+    return { delegationsDirPresent: false, total: 0, expired: 0, unreadable: 0 };
+}
+/**
+ * A delegation filename is always a session id: a UUID handed out by
+ * Claude Code or Codex, or (in this repo's own test fixtures) a short
+ * alnum/hyphen placeholder. Neither ever contains a literal `.` or
+ * starts with one. Filtering on that BEFORE the read is what keeps
+ * filesystem debris that happens to sit next to `.delegations/` files
+ * (macOS's `.DS_Store`, a stray `foo.txt`) from counting toward `total`
+ * at all: without it, such a file reads as valid-but-not-JSON and rolls
+ * into `unreadable`, which flips this metric's doctor line from
+ * informational (ℹ) straight to a WARNING (⚠) for debris that was never
+ * a delegation to begin with. Mirrors the same non-empty/no-traversal
+ * shape family `rejectMalformedSessionId` pins for a delegation's own
+ * filename on the write side (`delegationMarkerPathFor`), tightened to
+ * additionally exclude a dot, which is the part that actually
+ * discriminates a stray dotfile from a real session id.
+ */
+const SESSION_ID_BASENAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+ * Build the delegations-on-disk doctor metric. Pure filesystem read;
+ * never throws for "nothing to see" states (missing `.delegations/`,
+ * empty directory, every file unreadable), those all resolve to a
+ * zero-ish section, mirroring `buildUgAutoApprovals`. `total`/`expired`/
+ * `unreadable` read `0` for both an EMPTY and a MISSING directory; only
+ * `delegationsDirPresent` tells them apart, the same way
+ * `approvalsDirPresent` does for `buildUgAutoApprovals`, doctor's
+ * render layer uses it to stay silent when there is truly nothing on
+ * disk (`format.ts`'s own "no line for a check that found nothing"
+ * convention) while still rendering the zero-count line for a
+ * `harness delegate`-touched, now-empty directory.
+ */
+export function buildUgDelegations(generatedDir, opts = {}) {
+    const now = opts.now ?? new Date();
+    const dir = path.join(generatedDir, DELEGATION_MARKER_DIRNAME);
+    let dirents;
+    try {
+        dirents = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return emptySection();
+    }
+    let total = 0;
+    let expired = 0;
+    let unreadable = 0;
+    for (const d of dirents) {
+        // Not a session-id-shaped basename: never a delegation file (a
+        // stray dotfile, an extensioned file, a directory, ...), skip
+        // before even reading it. The once-per-session adoption ledger is
+        // never nested under here: `.delegation-adoptions/` is a SIBLING of
+        // `.delegations/` (see delegation-markers.ts's module header), so
+        // this filter has no ledger-shaped entry to reason about; an
+        // ordinary session-id-named directory would still fall through to
+        // the `not-regular` skip below, same as any other directory would.
+        if (!SESSION_ID_BASENAME_RE.test(d.name))
+            continue;
+        const full = path.join(dir, d.name);
+        const read = readRegularFileRejectingSymlink(full);
+        // A symlink / non-regular / raced-away entry is not a delegation
+        // file this metric owns an opinion about; skip silently, same
+        // reasoning as `buildUgAutoApprovals`.
+        if (read.kind === "symlink" || read.kind === "not-regular" || read.kind === "missing") {
+            continue;
+        }
+        total++;
+        if (read.kind === "unreadable") {
+            unreadable++;
+            continue;
+        }
+        const parsed = safeJsonParse(read.content);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            unreadable++;
+            continue;
+        }
+        const obj = parsed;
+        const segments = parseDelegationApprovedBy(obj["approvedBy"]);
+        if (!segments.ok) {
+            unreadable++;
+            continue;
+        }
+        if (Date.parse(segments.value.expiresAt) <= now.getTime()) {
+            expired++;
+        }
+    }
+    return { delegationsDirPresent: true, total, expired, unreadable };
+}
+//# sourceMappingURL=ug-delegations.js.map

package/dist/cli/doctor/ug-delegations.js.map

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

package/dist/cli/doctor/understanding-mode-env.d.ts

@@ -1,5 +1,6 @@
 import { type Mode } from "../../policy-packs/builtin/understanding-before-execution.js";
 import type { Manifest } from "../../schema/index.js";
+import type { PolicyPack } from "../../schema/policy-packs.js";
 export interface UnderstandingModeEnvDivergence {
     /** `UNDERSTANDING_GATE_MODE`, normalised (trim + lowercase, mirrors `resolveMode`'s own normalisation). */
     envMode: Mode;
@@ -36,4 +37,15 @@ export interface UnderstandingModeEnvDivergence {
  *     warn about.
  *   - the normalised env mode differs from the resolved `config.mode`.
  */
+/**
+ * Shared gate for the understanding-gate doctor sub-checks that only
+ * make sense when the pack is actually live: this divergence advisory,
+ * and (ADR docs/decisions/2026-08-27-ug-auto-mode-approval.md slice 1,
+ * agent-tasks 74b4b17d) the auto-approval listing and settings-drift
+ * checks. Declared-but-disabled counts as not enabled, mirroring the
+ * `p.enabled !== false` gate `checkUnderstandingModeEnvDivergence` uses
+ * inline below.
+ */
+export declare function findEnabledUnderstandingPack(manifest: Manifest): PolicyPack | undefined;
+export declare function isUnderstandingPackEnabled(manifest: Manifest): boolean;
 export declare function checkUnderstandingModeEnvDivergence(manifest: Manifest, env: NodeJS.ProcessEnv): UnderstandingModeEnvDivergence | undefined;

package/dist/cli/doctor/understanding-mode-env.js

@@ -48,8 +48,23 @@ import { isMode, MODE_ENV, PACK_NAME as UNDERSTANDING_PACK_NAME, resolveModeFrom
  *     warn about.
  *   - the normalised env mode differs from the resolved `config.mode`.
  */
+/**
+ * Shared gate for the understanding-gate doctor sub-checks that only
+ * make sense when the pack is actually live: this divergence advisory,
+ * and (ADR docs/decisions/2026-08-27-ug-auto-mode-approval.md slice 1,
+ * agent-tasks 74b4b17d) the auto-approval listing and settings-drift
+ * checks. Declared-but-disabled counts as not enabled, mirroring the
+ * `p.enabled !== false` gate `checkUnderstandingModeEnvDivergence` uses
+ * inline below.
+ */
+export function findEnabledUnderstandingPack(manifest) {
+    return manifest.policy_packs.find((p) => p.name === UNDERSTANDING_PACK_NAME && p.enabled !== false);
+}
+export function isUnderstandingPackEnabled(manifest) {
+    return findEnabledUnderstandingPack(manifest) !== undefined;
+}
 export function checkUnderstandingModeEnvDivergence(manifest, env) {
-    const pack = manifest.policy_packs.find((p) => p.name === UNDERSTANDING_PACK_NAME && p.enabled !== false);
+    const pack = findEnabledUnderstandingPack(manifest);
     if (!pack)
         return undefined;
     const envRaw = env[MODE_ENV];

package/dist/cli/doctor/understanding-mode-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"understanding-mode-env.js","sourceRoot":"","sources":["../../../src/cli/doctor/understanding-mode-env.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,mEAAmE;AACnE,EAAE;AACF,iEAAiE;AACjE,0EAA0E;AAC1E,kEAAkE;AAClE,wEAAwE;AACxE,kEAAkE;AAClE,sEAAsE;AACtE,oEAAoE;AACpE,sEAAsE;AACtE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,uDAAuD;AACvD,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,wEAAwE;AACxE,sEAAsE;AACtE,4DAA4D;AAC5D,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AACxE,qEAAqE;AACrE,yEAAyE;AACzE,+DAA+D;AAC/D,EAAE;AACF,+DAA+D;AAC/D,0EAA0E;AAC1E,kEAAkE;AAClE,2BAA2B;AAE3B,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,IAAI,uBAAuB,EACpC,qBAAqB,GAEtB,MAAM,8DAA8D,CAAC;AAwBtE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mCAAmC,CACjD,QAAkB,EAClB,GAAsB;IAEtB,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,CAAC,IAAI,CACrC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAuB,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,CACjE,CAAC;IACF,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAE5B,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACjF,IAAI,aAAa,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAEnD,yEAAyE;IACzE,yEAAyE;IACzE,yEAAyE;IACzE,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,sBAAsB,CAAC;IAEhE,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,UAAU;QACV,OAAO,EAAE,GAAG,QAAQ,IAAI,aAAa,8BAA8B,UAAU,EAAE;QAC/E,MAAM,EAAE;YACN,uFAAuF;gBACrF,iFAAiF,aAAa,GAAG;YACnG,yBAAyB,UAAU,GAAG,WAAW,EAAE;YACnD,uDAAuD,QAAQ,wBAAwB;SACxF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"understanding-mode-env.js","sourceRoot":"","sources":["../../../src/cli/doctor/understanding-mode-env.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,mEAAmE;AACnE,EAAE;AACF,iEAAiE;AACjE,0EAA0E;AAC1E,kEAAkE;AAClE,wEAAwE;AACxE,kEAAkE;AAClE,sEAAsE;AACtE,oEAAoE;AACpE,sEAAsE;AACtE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,uDAAuD;AACvD,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,wEAAwE;AACxE,sEAAsE;AACtE,4DAA4D;AAC5D,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AACxE,qEAAqE;AACrE,yEAAyE;AACzE,+DAA+D;AAC/D,EAAE;AACF,+DAA+D;AAC/D,0EAA0E;AAC1E,kEAAkE;AAClE,2BAA2B;AAE3B,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,IAAI,uBAAuB,EACpC,qBAAqB,GAEtB,MAAM,8DAA8D,CAAC;AAyBtE;;;;;;;;;;;;;;;GAeG;AACH;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,QAAkB;IAC7D,OAAO,QAAQ,CAAC,YAAY,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAuB,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,CACjE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,QAAkB;IAC3D,OAAO,4BAA4B,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,mCAAmC,CACjD,QAAkB,EAClB,GAAsB;IAEtB,MAAM,IAAI,GAAG,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAE5B,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACjF,IAAI,aAAa,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAEnD,yEAAyE;IACzE,yEAAyE;IACzE,yEAAyE;IACzE,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,sBAAsB,CAAC;IAEhE,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,UAAU;QACV,OAAO,EAAE,GAAG,QAAQ,IAAI,aAAa,8BAA8B,UAAU,EAAE;QAC/E,MAAM,EAAE;YACN,uFAAuF;gBACrF,iFAAiF,aAAa,GAAG;YACnG,yBAAyB,UAAU,GAAG,WAAW,EAAE;YACnD,uDAAuD,QAAQ,wBAAwB;SACxF;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/index.js

@@ -41,6 +41,8 @@ import { approveBranchProtection } from "./approve/branch-protection.js";
 import { approveRisk } from "./approve/risk.js";
 import { approveUnderstanding } from "./approve/understanding.js";
 import { readPipedStdin } from "./approve/stdin-report.js";
+import { issueDelegation } from "./delegate/index.js";
+import { InvalidDurationError, parseDurationSeconds } from "../policies/index.js";
 import { runRecordDogfood, runRecordReview, runRecordReviewSubagent, } from "./record/index.js";
 import { describe, isPillar } from "./describe.js";
 import { diff as diffRun } from "./diff/index.js";
@@ -175,6 +177,7 @@ export function buildProgram(opts = {}) {
         .option("--project <name>", "apply per-project overrides for this project name")
         .option("--shallow", "skip MCP probes (CLI --version probes still run); report manifest-reference state only")
         .option("--target <runtime>", `additionally evaluate the harness-side adapter health for a runtime (allowed: ${KNOWN_DOCTOR_TARGETS.join(", ")})`)
+        .option("--recent-sessions <n>", "understanding-gate auto-approval doctor window: how many of the newest .approvals/ session markers to scan (default: 20)")
         .option("--json", "emit a structured JSON DoctorReport instead of prose (--rm-rogue-ledgers is ignored with --json)")
         .option("--rm-rogue-ledgers", "after reporting, delete each rogue evidence-ledger directory found (prompts per hit; combine with --yes to skip prompts)")
         .option("--yes", "with --rm-rogue-ledgers, skip per-hit confirmation prompts")
@@ -187,12 +190,22 @@ export function buildProgram(opts = {}) {
             }
             target = options.target;
         }
+        let recentSessions;
+        if (options.recentSessions !== undefined) {
+            const parsed = Number(options.recentSessions);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                stderr(`--recent-sessions must be an integer >= 1, got ${JSON.stringify(options.recentSessions)}\n`);
+                throw new HarnessExitError("", EX_USAGE);
+            }
+            recentSessions = parsed;
+        }
         const report = await doctor({
             configPath: options.config,
             project: options.project,
             shallow: options.shallow,
             versionProbe: defaultVersionProbe,
             ...(target !== undefined ? { target } : {}),
+            ...(recentSessions !== undefined ? { recentSessions } : {}),
             ...(opts.rogueLedgerScanOptions !== undefined
                 ? { rogueLedgerScanOptions: opts.rogueLedgerScanOptions }
                 : {}),
@@ -1505,6 +1518,86 @@ export function buildProgram(opts = {}) {
         }
         stdout(`${lines.join("\n")}\n`);
     });
+    // `harness delegate` (Slice 3 of docs/decisions/2026-08-27-ug-auto-mode-approval.md,
+    // agent-tasks 37ad0b05): issue a signed pre-authorization for a
+    // headless `claude -p` child session, bound to an already-approved
+    // PARENT session. NOT an approval: the child still writes and gets its
+    // own Understanding Report checked by its own PreToolUse hook before
+    // its auto-marker is minted. Writes harness.generated/.delegations/,
+    // never .approvals/.
+    program
+        .command("delegate")
+        .description("Issue a signed delegation for a headless `claude -p` child session, bound to " +
+        "an already-approved parent session (pre-authorization, not an approval: the " +
+        "child still writes and gets its own Understanding Report checked). Writes " +
+        "harness.generated/.delegations/<child-sid>, never .approvals/. See " +
+        "docs/decisions/2026-08-27-ug-auto-mode-approval.md.")
+        .requiredOption("--child-session <uuid>", "session id of the claude -p child this delegation authorizes (UUID)")
+        .option("--cwd <path>", "bind the delegation to this working directory; at least one of --cwd/--task is required")
+        .option("--task <id>", "bind the delegation to this agent-tasks task id; at least one of --cwd/--task is required")
+        .option("--ttl <duration>", "delegation lifetime (e.g. 30m, 1h); default: the pack's approval_lifecycle.max_age when set, else 1h")
+        .option("--report <path>", "fallback shape: bind the child's Understanding Report by content + path hash at spawn time; not yet consumed by the child hook, see the pack doc")
+        .option("--session-id <id>", "explicit parent session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then $CODEX_SESSION_ID, then staged .pending-approval)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .action(async (options) => {
+        // Usage-level check ahead of every deeper resolution, with the
+        // exact message the ADR slice 3 acceptance criterion pins.
+        // `issueDelegation` carries the identical check (reason
+        // "no-binding") for callers that invoke it directly (the smoke
+        // runner, tests) without going through commander's flag parsing.
+        if (options.cwd === undefined && options.task === undefined) {
+            throw new HarnessExitError("a delegation must bind a cwd or a task", EX_FAIL);
+        }
+        let ttlSeconds;
+        if (options.ttl) {
+            try {
+                ttlSeconds = parseDurationSeconds(options.ttl);
+            }
+            catch (err) {
+                if (err instanceof InvalidDurationError) {
+                    throw new HarnessExitError(`--ttl: ${err.message}`, EX_USAGE);
+                }
+                throw err;
+            }
+        }
+        const cliOpts = {
+            childSessionId: options.childSession,
+        };
+        // `!== undefined` (not truthy), agreeing with the usage check
+        // above: a truthy check would silently drop an explicit `--cwd
+        // ''` / `--task ''` instead of letting `issueDelegation` refuse
+        // it with `invalid-cwd` / `invalid-task` (L3 fix, agent-tasks
+        // 37ad0b05).
+        if (options.cwd !== undefined)
+            cliOpts.cwd = options.cwd;
+        if (options.task !== undefined)
+            cliOpts.taskId = options.task;
+        if (ttlSeconds !== undefined)
+            cliOpts.ttlSeconds = ttlSeconds;
+        if (options.report)
+            cliOpts.reportPath = options.report;
+        if (options.sessionId)
+            cliOpts.parentSessionId = options.sessionId;
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        const result = await issueDelegation(cliOpts);
+        if (!result.ok) {
+            throw new HarnessExitError(`delegate refused (${result.reason}): ${result.detail}`, EX_FAIL);
+        }
+        const lines = [
+            `delegation: ✓ ${result.filePath} (child ${result.childSessionId}, parent ${result.parentSessionId}, expires ${result.expiresAt})`,
+        ];
+        if (result.ledgerFact.written) {
+            lines.push(`ledger:     ✓ wrote understanding-delegated:${result.childSessionId}:${result.parentSessionId} (audit only)`);
+        }
+        else {
+            lines.push(`ledger:     ⚠ skipped (${result.ledgerFact.reason ?? "unknown"}) (audit only)`);
+        }
+        stdout(`${lines.join("\n")}\n`);
+    });
     const VALID_DECISION_FILTERS = [
         "allow",
         "warn",
@@ -1630,7 +1723,7 @@ export function buildProgram(opts = {}) {
     });
     program
         .command("audit")
-        .description("Replay policy decisions from the evidence ledger for a time window")
+        .description("Replay policy decisions from the evidence ledger for a time window, plus an approvals section listing raw understanding-gate approval facts")
         .option("--since <duration>", "time window (default: 24h)")
         .option("--policy <name>", "filter to a single policy by name")
         .option("--outcome <outcome>", "filter by decision outcome (allow / warn / require_approval / deny / warn-degraded / deny-degraded)")
@@ -1727,6 +1820,8 @@ export function buildProgram(opts = {}) {
         .option("--expect-no-hook <names>", "comma-separated list of hook names / events that MUST NOT fire (repeatable)", (value, prev = []) => prev.concat(splitCommaList(value)), [])
         .option("--expect-exit <n>", "expected result.is_error: 0 ⇒ false, !=0 ⇒ true")
         .option("--expect-decision <kind>", "policy decision must be one of allow|deny|warn")
+        .option("--no-delegate", "do not pre-authorize the spawned child (docs/decisions/2026-08-27-ug-auto-mode-approval.md); " +
+        "it then has no delegation binding it to this approved session and falls back to the plain opt-in path")
         .action(async (options) => {
         const expectations = {};
         if (options.expectHook && options.expectHook.length > 0) {
@@ -1750,6 +1845,10 @@ export function buildProgram(opts = {}) {
             outputDir: options.outputDir,
             expectations,
         };
+        // commander's `--no-delegate` negates `options.delegate` (default
+        // true); only an explicit `--no-delegate` flips it to `false`.
+        if (options.delegate === false)
+            smokeOpts.noDelegate = true;
         if (options.config)
             smokeOpts.configPath = options.config;
         if (options.project)