@lannguyensi/harness 0.51.0 → 0.53.0

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";
@@ -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";
@@ -860,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
@@ -1516,6 +1547,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",
@@ -1641,7 +1752,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)")
@@ -1738,6 +1849,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) {
@@ -1761,6 +1874,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)
@@ -2168,11 +2285,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)")
@@ -2195,10 +2314,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("") +