@lannguyensi/harness 0.52.0 → 0.54.0

package/dist/cli/gc/index.js

@@ -14,12 +14,47 @@
 //       <reportsDir>            terminal-status reports (approved / expired)
 //       <reportsDir>/../parse-errors   parse-error logs
 //       <generatedDir>/.approvals      session / task / branch-protection markers
+//       <generatedDir>/.delegations       signed delegation markers (slice 3)
+//       <generatedDir>/.delegation-adoptions   once-per-session adoption ledgers
+//       <generatedDir>/.permission-mode-observations   per-session PreToolUse
+//                                          permission_mode observations (task 8f637efd)
 //     The evidence ledger (grounding-mcp) and solution-acceptance
 //     verdict dirs (producer-owned) are out of scope by design.
 //   - Deletion failures are surfaced loudly per file, never swallowed.
+//
+// DELEGATIONS SWEEP (task 3ece079d, follow-up from UG auto-mode slice 3,
+// agent-tasks 37ad0b05): a delegation marker is refused once expired
+// (`verifyDelegation`'s "expired" reason), but nothing ever removed the
+// FILE, so `.delegations/` grows the same way `.approvals/` used to. The
+// adoption ledger at `.delegation-adoptions/<sid>` is worse: it is
+// appended to once per captured transcript entry and never cleared at
+// all, delegation expiry or not. Both sweep under one `"delegation"`
+// category, on the SAME retention/grace window as everything else in this
+// file (`retentionDays` / `cutoffMs`): a delegation marker is a candidate
+// once its own `expires` segment (read via `parseDelegationApprovedBy`,
+// no signature check needed for a retention decision) is older than
+// `cutoffMs`, and its ledger sibling is a candidate once the marker for
+// that session id is gone or itself a candidate. A marker whose content
+// cannot be parsed is never a deletion candidate (fail closed, same as a
+// pending report): it is surfaced separately in `GcResult.unparseable` so
+// an operator can see it, but `--apply` never touches it, and its ledger
+// sibling (if any) stays too, since "this delegation is dead" cannot be
+// established for one gc cannot read.
+//
+// PERMISSION-MODE OBSERVATIONS SWEEP (task 8f637efd review round 2 F5):
+// `.permission-mode-observations/` (one small per-session file, see
+// permission-mode-observations.ts) grows the same way `.approvals/` and
+// `.delegations/` do (nothing else ever removes an entry), and gc had
+// not been taught about it. Swept under its own `"permission-mode-
+// observation"` category by mtime, same `staleFilesByMtime` helper and
+// `retentionDays` window every mtime-aged category here already uses (no
+// signed `expires` to key off, unlike the delegation sweep: this is a
+// plain observation record, not an approval artifact).
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { APPROVAL_MARKER_DIRNAME, defaultReportsDir, listPersistedReports, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
+import { readRegularFileRejectingSymlink } from "../../io/read-regular-file.js";
+import { safeJsonParse } from "../../io/safe-json-parse.js";
+import { ADOPTION_LEDGER_DIRNAME, APPROVAL_MARKER_DIRNAME, DELEGATION_MARKER_DIRNAME, PERMISSION_MODE_OBSERVATION_DIRNAME, defaultReportsDir, listPersistedReports, parseDelegationApprovedBy, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
 import { resolveGeneratedDir } from "../../runtime/pending-approval.js";
 import { resolvePaths } from "../loader.js";
 export const DEFAULT_RETENTION_DAYS = 30;
@@ -66,6 +101,158 @@ function staleFilesByMtime(dir, cutoffMs, nowMs, category) {
     }
     return { candidates, kept };
 }
+/**
+ * A delegation filename is always a session id (mirrors
+ * `doctor/ug-delegations.ts`'s own filter and rationale): filtering on
+ * this shape before reading keeps filesystem debris that happens to sit
+ * next to `.delegations/` or `.delegation-adoptions/` (macOS's
+ * `.DS_Store`, a stray dotfile) from ever becoming an "unparseable"
+ * candidate gc reports on. Not shared code with that module (see its own
+ * header for why); `check:duplication` is the backstop if that stops
+ * being a coincidence.
+ */
+const SESSION_ID_BASENAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+ * Read a `.delegations/<sid>` marker and classify it against `cutoffMs`,
+ * WITHOUT verifying its signature: gc is deciding whether to delete a
+ * file, not whether to trust it as an approval, and `parseDelegationApprovedBy`
+ * is the same reader `harness doctor`'s delegations metric uses read-only.
+ * Any failure to read the file, parse it as JSON, or parse its
+ * `approvedBy`/`expires` segment is `unparseable`, never `expired`: a
+ * marker gc cannot understand is never deleted (mutation probe M2).
+ */
+function readDelegationStatus(filePath, cutoffMs, nowMs) {
+    const read = readRegularFileRejectingSymlink(filePath);
+    if (read.kind !== "ok") {
+        return { kind: "unparseable", reason: `could not read ${filePath} (${read.kind})` };
+    }
+    const parsed = safeJsonParse(read.content);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { kind: "unparseable", reason: "not a JSON object" };
+    }
+    const segments = parseDelegationApprovedBy(parsed["approvedBy"]);
+    if (!segments.ok) {
+        return { kind: "unparseable", reason: segments.reason };
+    }
+    const expiresMs = Date.parse(segments.value.expiresAt);
+    if (!Number.isFinite(expiresMs)) {
+        return {
+            kind: "unparseable",
+            reason: `expires segment is not a valid instant: ${JSON.stringify(segments.value.expiresAt)}`,
+        };
+    }
+    // The expiry comparison itself: mutation probe M1 skips this and treats
+    // every parseable marker as expired, which flips a "valid delegation is
+    // kept" test red.
+    if (expiresMs < cutoffMs) {
+        return {
+            kind: "expired",
+            reason: `expired ${ageDays(nowMs, expiresMs)}d ago (past the ${ageDays(nowMs, cutoffMs)}d grace)`,
+        };
+    }
+    return { kind: "valid" };
+}
+/**
+ * Sweep `.delegations/` (expired markers) and `.delegation-adoptions/`
+ * (ledgers orphaned once their marker is gone or expired). One shared
+ * category (`"delegation"`), mirroring the approval-marker sweep's
+ * dry-run/candidate/kept shape but keyed off the marker's OWN `expires`
+ * segment instead of file mtime, since a delegation's age on disk and its
+ * validity window are two different things.
+ */
+function sweepDelegations(generatedDir, cutoffMs, nowMs) {
+    const delegationsDir = path.join(generatedDir, DELEGATION_MARKER_DIRNAME);
+    const ledgerDir = path.join(generatedDir, ADOPTION_LEDGER_DIRNAME);
+    const candidates = [];
+    const unparseable = [];
+    let kept = 0;
+    // Session id -> status, for every delegation marker actually present
+    // and session-id-shaped, so the ledger pass below can tell "expired"
+    // from "absent" from "still valid" without re-reading the file.
+    const statusBySessionId = new Map();
+    let delegationNames;
+    try {
+        delegationNames = fs.readdirSync(delegationsDir);
+    }
+    catch {
+        delegationNames = [];
+    }
+    for (const name of delegationNames) {
+        if (!SESSION_ID_BASENAME_RE.test(name))
+            continue;
+        const full = path.join(delegationsDir, name);
+        const status = readDelegationStatus(full, cutoffMs, nowMs);
+        statusBySessionId.set(name, status);
+        if (status.kind === "expired") {
+            candidates.push({ filePath: full, category: "delegation", reason: status.reason });
+        }
+        else if (status.kind === "unparseable") {
+            unparseable.push({ filePath: full, category: "delegation", reason: status.reason });
+            kept += 1;
+        }
+        else {
+            kept += 1;
+        }
+    }
+    let ledgerNames;
+    try {
+        ledgerNames = fs.readdirSync(ledgerDir);
+    }
+    catch {
+        ledgerNames = [];
+    }
+    for (const name of ledgerNames) {
+        if (!SESSION_ID_BASENAME_RE.test(name))
+            continue;
+        const full = path.join(ledgerDir, name);
+        let stat;
+        try {
+            stat = fs.statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile()) {
+            kept += 1;
+            continue;
+        }
+        const status = statusBySessionId.get(name);
+        if (status === undefined) {
+            // No marker for this session id at all: only a candidate once the
+            // LEDGER's own age clears the cutoff. Without this check a ledger
+            // written seconds ago (its marker legitimately not written yet, or
+            // already cleaned up by something else) would be swept regardless
+            // of age, contradicting the "older than the retention window"
+            // posture documented on the command and the listing header; it
+            // also closes the TOCTOU window between the two readdir calls
+            // above, since a ledger written between them is newer than cutoff.
+            if (stat.mtimeMs < cutoffMs) {
+                candidates.push({
+                    filePath: full,
+                    category: "delegation",
+                    reason: "orphaned adoption ledger (no delegation marker for this session)",
+                });
+            }
+            else {
+                kept += 1;
+            }
+        }
+        else if (status.kind === "expired") {
+            candidates.push({
+                filePath: full,
+                category: "delegation",
+                reason: `orphaned adoption ledger (delegation ${status.reason})`,
+            });
+        }
+        else {
+            // Marker still valid, or unparseable (gc cannot prove it is dead):
+            // keep the ledger either way, same fail-closed posture as the
+            // marker itself.
+            kept += 1;
+        }
+    }
+    return { candidates, unparseable, kept };
+}
 export function gc(opts = {}) {
     const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS;
     if (!Number.isFinite(retentionDays) || retentionDays < 1) {
@@ -92,7 +279,11 @@ export function gc(opts = {}) {
             manifestPath: manifestBase(),
         });
     const approvalsDir = path.join(generatedDir, APPROVAL_MARKER_DIRNAME);
+    const delegationsDir = path.join(generatedDir, DELEGATION_MARKER_DIRNAME);
+    const adoptionLedgerDir = path.join(generatedDir, ADOPTION_LEDGER_DIRNAME);
+    const permissionModeObservationsDir = path.join(generatedDir, PERMISSION_MODE_OBSERVATION_DIRNAME);
     const candidates = [];
+    const unparseable = [];
     let keptCount = 0;
     // Reports: only terminal statuses age out. A pending report is never
     // deleted regardless of age; since the C1 fix, stale pending leftovers
@@ -119,6 +310,13 @@ export function gc(opts = {}) {
     const markers = staleFilesByMtime(approvalsDir, cutoffMs, nowMs, "approval-marker");
     candidates.push(...markers.candidates);
     keptCount += markers.kept;
+    const delegations = sweepDelegations(generatedDir, cutoffMs, nowMs);
+    candidates.push(...delegations.candidates);
+    unparseable.push(...delegations.unparseable);
+    keptCount += delegations.kept;
+    const permissionModeObservations = staleFilesByMtime(permissionModeObservationsDir, cutoffMs, nowMs, "permission-mode-observation");
+    candidates.push(...permissionModeObservations.candidates);
+    keptCount += permissionModeObservations.kept;
     const removed = [];
     const failures = [];
     if (opts.apply === true) {
@@ -138,7 +336,11 @@ export function gc(opts = {}) {
         reportsDir,
         parseErrorsDir,
         approvalsDir,
+        delegationsDir,
+        adoptionLedgerDir,
+        permissionModeObservationsDir,
         candidates,
+        unparseable,
         removed,
         failures,
         keptCount,

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/gc/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/gc/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,iEAAiE;AACjE,sEAAsE;AACtE,oEAAoE;AACpE,kEAAkE;AAClE,sEAAsE;AACtE,gEAAgE;AAChE,0CAA0C;AAC1C,EAAE;AACF,yDAAyD;AACzD,6CAA6C;AAC7C,+DAA+D;AAC/D,6EAA6E;AAC7E,wDAAwD;AACxD,kFAAkF;AAClF,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAC9E,wFAAwF;AACxF,kEAAkE;AAClE,gEAAgE;AAChE,uEAAuE;AACvE,EAAE;AACF,yEAAyE;AACzE,qEAAqE;AACrE,wEAAwE;AACxE,yEAAyE;AACzE,mEAAmE;AACnE,sEAAsE;AACtE,qEAAqE;AACrE,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,oEAAoE;AACpE,wEAAwE;AACxE,wEAAwE;AACxE,yEAAyE;AACzE,0EAA0E;AAC1E,yEAAyE;AACzE,wEAAwE;AACxE,sCAAsC;AACtC,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,wEAAwE;AACxE,sEAAsE;AACtE,mEAAmE;AACnE,uEAAuE;AACvE,yEAAyE;AACzE,sEAAsE;AACtE,uDAAuD;AAEvD,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,mCAAmC,EACnC,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAsB,MAAM,cAAc,CAAC;AAEhE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,wEAAwE;AACxE,iDAAiD;AACjD,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAgE5C,SAAS,OAAO,CAAC,KAAa,EAAE,MAAc;IAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC;AACnD,CAAC;AAED,iEAAiE;AACjE,SAAS,iBAAiB,CACxB,GAAW,EACX,QAAgB,EAChB,KAAa,EACb,QAAoB;IAEpB,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrC,CAAC;IACD,MAAM,UAAU,GAAkB,EAAE,CAAC;IACrC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACnB,IAAI,IAAI,CAAC,CAAC;YACV,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC;YAC5B,UAAU,CAAC,IAAI,CAAC;gBACd,QAAQ,EAAE,IAAI;gBACd,QAAQ;gBACR,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe;aACvD,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,sBAAsB,GAAG,6BAA6B,CAAC;AAO7D;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,QAAgB,EAAE,QAAgB,EAAE,KAAa;IAC7E,MAAM,IAAI,GAAG,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,QAAQ,KAAK,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IACtF,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9D,CAAC;IACD,MAAM,QAAQ,GAAG,yBAAyB,CAAE,MAAkC,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9F,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC1D,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,2CAA2C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;SAC9F,CAAC;IACJ,CAAC;IACD,wEAAwE;IACxE,wEAAwE;IACxE,kBAAkB;IAClB,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,WAAW,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,mBAAmB,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU;SAClG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,gBAAgB,CACvB,YAAoB,EACpB,QAAgB,EAChB,KAAa;IAEb,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC;IAEnE,MAAM,UAAU,GAAkB,EAAE,CAAC;IACrC,MAAM,WAAW,GAAoB,EAAE,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,qEAAqE;IACrE,qEAAqE;IACrE,gEAAgE;IAChE,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAgC,CAAC;IAElE,IAAI,eAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,eAAe,GAAG,EAAE,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,eAAe,GAAG,EAAE,CAAC;IACvB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC3D,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACrF,CAAC;aAAM,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACzC,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YACpF,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IAED,IAAI,WAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,WAAW,GAAG,EAAE,CAAC;IACnB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACnB,IAAI,IAAI,CAAC,CAAC;YACV,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,kEAAkE;YAClE,kEAAkE;YAClE,mEAAmE;YACnE,kEAAkE;YAClE,8DAA8D;YAC9D,+DAA+D;YAC/D,8DAA8D;YAC9D,mEAAmE;YACnE,IAAI,IAAI,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC;gBAC5B,UAAU,CAAC,IAAI,CAAC;oBACd,QAAQ,EAAE,IAAI;oBACd,QAAQ,EAAE,YAAY;oBACtB,MAAM,EAAE,kEAAkE;iBAC3E,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,IAAI,IAAI,CAAC,CAAC;YACZ,CAAC;QACH,CAAC;aAAM,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACrC,UAAU,CAAC,IAAI,CAAC;gBACd,QAAQ,EAAE,IAAI;gBACd,QAAQ,EAAE,YAAY;gBACtB,MAAM,EAAE,wCAAwC,MAAM,CAAC,MAAM,GAAG;aACjE,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,mEAAmE;YACnE,8DAA8D;YAC9D,iBAAiB;YACjB,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,EAAE,CAAC,OAAkB,EAAE;IACrC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACnE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,oDAAoD,aAAa,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,KAAK,GAAG,aAAa,GAAG,UAAU,CAAC;IAEpD,qEAAqE;IACrE,wEAAwE;IACxE,iEAAiE;IACjE,aAAa;IACb,IAAI,YAAgC,CAAC;IACrC,MAAM,YAAY,GAAG,GAAW,EAAE,CAAC,CAAC,YAAY,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,UAAU,GACd,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IACrE,MAAM,kBAAkB,GACtB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,SAAS;QACvC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,KAAK,qBAAqB,CAAC;IACpE,MAAM,cAAc,GAAG,kBAAkB;QACvC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;QAC3D,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,YAAY,GAChB,IAAI,CAAC,YAAY;QACjB,mBAAmB,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,YAAY,EAAE,YAAY,EAAE;SAC7B,CAAC,CAAC;IACL,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC;IACtE,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC;IAC1E,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC;IAC3E,MAAM,6BAA6B,GAAG,IAAI,CAAC,IAAI,CAC7C,YAAY,EACZ,mCAAmC,CACpC,CAAC;IAEF,MAAM,UAAU,GAAkB,EAAE,CAAC;IACrC,MAAM,WAAW,GAAoB,EAAE,CAAC;IACxC,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,qEAAqE;IACrE,uEAAuE;IACvE,kEAAkE;IAClE,oEAAoE;IACpE,KAAK,MAAM,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACtD,MAAM,QAAQ,GACZ,MAAM,CAAC,cAAc,KAAK,UAAU,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC;QAC9E,IAAI,QAAQ,IAAI,MAAM,CAAC,WAAW,GAAG,QAAQ,EAAE,CAAC;YAC9C,UAAU,CAAC,IAAI,CAAC;gBACd,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,QAAQ;gBAClB,MAAM,EAAE,GAAG,MAAM,CAAC,cAAc,aAAa,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO;aACvF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,iBAAiB,CAAC,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;QACtF,UAAU,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;QAC3C,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC;IAChC,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC;IACpF,UAAU,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAE1B,MAAM,WAAW,GAAG,gBAAgB,CAAC,YAAY,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACpE,UAAU,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IAC3C,WAAW,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC;IAE9B,MAAM,0BAA0B,GAAG,iBAAiB,CAClD,6BAA6B,EAC7B,QAAQ,EACR,KAAK,EACL,6BAA6B,CAC9B,CAAC;IACF,UAAU,CAAC,IAAI,CAAC,GAAG,0BAA0B,CAAC,UAAU,CAAC,CAAC;IAC1D,SAAS,IAAI,0BAA0B,CAAC,IAAI,CAAC;IAE7C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAgD,EAAE,CAAC;IACjE,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACxB,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAC1B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa;QACb,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE;QAC3C,UAAU;QACV,cAAc;QACd,YAAY;QACZ,cAAc;QACd,iBAAiB;QACjB,6BAA6B;QAC7B,UAAU;QACV,WAAW;QACX,OAAO;QACP,QAAQ;QACR,SAAS;QACT,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI;KAC7B,CAAC;AACJ,CAAC"}

package/dist/cli/index.js

@@ -27,7 +27,7 @@ import { add } from "./add/index.js";
 import { adopt } from "./adopt/index.js";
 import { apply, CODEX_CONFIG_BASENAME, DRIFT_HINT_MESSAGE, formatNextSteps, OPENCODE_CONFIG_BASENAME, SETTINGS_BASENAME, } from "./apply/index.js";
 import { isRemoveType, KNOWN_REMOVE_TYPES, remove } from "./remove/index.js";
-import { packAdd, packList, packRemove, packReseed } from "./pack/index.js";
+import { packAdd, packList, packRemove, packReseed, packUpgrade } from "./pack/index.js";
 import { runPackHookPreToolUseCli } from "./pack/hook-pre-tool-use.js";
 import { runPackHookPostToolUseCli } from "./pack/hook-post-tool-use.js";
 import { runPackHookTrackActiveClaimCli } from "./pack/hook-track-active-claim.js";
@@ -862,6 +862,35 @@ export function buildProgram(opts = {}) {
         }
         stdout(`reseeded ${result.fieldsChanged.map((f) => `config.${f}`).join(", ")} for policy_packs entry ${JSON.stringify(result.name)} in ${result.path}\n`);
     });
+    // `harness pack upgrade <name>` (task 8f637efd, D-004): text-level
+    // insertion of a pack's missing default config block into an existing
+    // manifest, idempotent, never rewrites content outside the inserted
+    // block. Today's only wired upgrade is `understanding-before-
+    // execution`'s `auto_approve` default; see upgrade.ts's module header
+    // for why this is text-level rather than a Document-API mutation like
+    // `add` / `reseed`.
+    packCmd
+        .command("upgrade <name>")
+        .description("Insert a pack's missing default config block into an existing manifest (today: " +
+        "understanding-before-execution's auto_approve default). Idempotent; " +
+        "refuses on ambiguity rather than guessing where to insert.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--dry-run", "print the unified diff and exit without writing")
+        .action(async (name, options) => {
+        const result = await packUpgrade(name, {
+            configPath: options.config,
+            dryRun: options.dryRun,
+        });
+        if (result.alreadyPresent) {
+            stdout(`policy_packs entry ${JSON.stringify(result.name)} already carries this upgrade; nothing to insert (${result.path} unchanged).\n`);
+            return;
+        }
+        if (options.dryRun) {
+            stdout(result.diff);
+            return;
+        }
+        stdout(`upgraded policy_packs entry ${JSON.stringify(result.name)} in ${result.path}\n`);
+    });
     // `harness pack hook` runtime sub-tree (Phase 6 #4): wired by the
     // pack's PreToolUse hook contribution; reads PreToolUse JSON from
     // stdin, consults the signed approval marker (the persisted report and
@@ -1530,13 +1559,16 @@ export function buildProgram(opts = {}) {
         .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.")
+        "harness.generated/.delegations/<child-sid>, never .approvals/. Consumption is " +
+        "Claude Code only: the Codex adapter has no delegation consumer, so a Codex " +
+        "session cannot be the delegated child. A Codex session CAN be the delegating " +
+        "parent today (parent resolution reads $CODEX_SESSION_ID and accepts any " +
+        "validly signed marker). 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("--report <path>", "fallback shape: copy the child's Understanding Report to harness.generated/.delegation-reports/<child-sid>.md and bind it by content + that conventional path's hash at spawn time; the child's PreToolUse hook reads it back from there, 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")
@@ -1952,8 +1984,9 @@ export function buildProgram(opts = {}) {
         "Interactive verbs (not hooks): a failure exits non-zero.");
     recordCmd
         .command("review <summary>")
-        .description("Record a review:${PR_NUMBER} + review:${BRANCH} (+ review:${BASE}) fact for the " +
-        "review-before-merge / review-before-merge-bash gates.")
+        .description("Record a review:${PR_NUMBER} + review:${BRANCH} (+ review:${BASE}, + review:${TASK_ID} " +
+        "with --task) fact for the review-before-merge / review-before-merge-bash / " +
+        "review-before-task-merge / review-before-task-finish-automerge gates.")
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .requiredOption("--pr <number>", "PR number the review:${PR_NUMBER} tag is namespaced by")
@@ -1961,6 +1994,8 @@ export function buildProgram(opts = {}) {
         "refs/remotes/origin/HEAD (packed-refs fallback included); omitted with a stderr warning " +
         "when neither resolves. No `gh` shell-out.")
         .option("--branch <name>", "explicit branch override for review:${BRANCH} (default: current git branch)")
+        .option("--task <id>", "agent-tasks task id for the review:${TASK_ID} tag the task_merge / task_finish(autoMerge) gates read. " +
+        "Optional; pass it and one recorded review satisfies all four merge surfaces.")
         .option("--session <id>", "explicit session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then newest Claude Code transcript)")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
         .action(async (summary, options) => {
@@ -1973,6 +2008,8 @@ export function buildProgram(opts = {}) {
             cliOpts.base = options.base;
         if (options.branch)
             cliOpts.branch = options.branch;
+        if (options.task !== undefined)
+            cliOpts.task = options.task;
         if (options.session)
             cliOpts.session = options.session;
         applyLedgerTimeout(options.ledgerTimeout, cliOpts);
@@ -2256,11 +2293,13 @@ export function buildProgram(opts = {}) {
     program
         .command("gc")
         .description("Retention-based cleanup of harness-owned gate state: terminal " +
-        "(approved/expired) understanding-gate reports, parse-error logs, and " +
-        "approval markers older than the retention window. Pending reports and " +
-        "anything outside the enumerated harness-owned dirs are never touched " +
-        "(the evidence ledger and solution-acceptance verdict dirs are owned by " +
-        "their producers). Dry-run by default; pass --apply to delete.")
+        "(approved/expired) understanding-gate reports, parse-error logs, " +
+        "approval markers, expired delegation markers, orphaned delegation " +
+        "adoption ledgers, and stale permission-mode observations older than " +
+        "the retention window. Pending reports and anything outside the " +
+        "enumerated harness-owned dirs are never touched (the evidence " +
+        "ledger and solution-acceptance verdict dirs are owned by their " +
+        "producers). Dry-run by default; pass --apply to delete.")
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--retention-days <n>", `delete artifacts older than this many days (default: ${DEFAULT_RETENTION_DAYS})`)
         .option("--apply", "delete the listed artifacts (default: dry-run listing only)")
@@ -2283,10 +2322,17 @@ export function buildProgram(opts = {}) {
             result.reportsDir,
             ...(result.parseErrorsDir !== null ? [result.parseErrorsDir] : []),
             result.approvalsDir,
+            result.delegationsDir,
+            result.adoptionLedgerDir,
+            result.permissionModeObservationsDir,
         ];
         if (result.parseErrorsDir === null) {
             stderr("gc: skipping the parse-errors sweep (reports dir does not have the conventional .understanding-gate/reports shape)\n");
         }
+        if (result.unparseable.length > 0) {
+            stderr(`gc: ${result.unparseable.length} delegation file(s) could not be parsed and were left in place:\n` +
+                result.unparseable.map((u) => `  [${u.category}] ${u.filePath} (${u.reason})\n`).join(""));
+        }
         if (result.candidates.length === 0) {
             stdout(`gc: nothing older than ${result.retentionDays}d (cutoff ${result.cutoffIso}) under\n` +
                 sweptDirs.map((d) => `  ${d}\n`).join("") +