@lannguyensi/harness 0.33.0 → 0.34.0

package/dist/cli/gc/index.js

@@ -0,0 +1,148 @@
+// `harness gc` — retention-based cleanup of harness-owned gate state.
+//
+// Nothing else ever deletes terminal understanding-gate reports,
+// parse-error logs, or approval markers of long-dead sessions, so the
+// state dirs grow unbounded (harness-discovery M3; 103 report files
+// accumulated in under a month on the originating install). Stale
+// pending reports were also the raw material of the C1 stale-adoption
+// bug, but pending state is deliberately NOT touched here: only
+// artifacts in a terminal status age out.
+//
+// Safety posture (mirrors `uninstall` / `migrate-home`):
+//   - Dry-run by default; `--apply` commits.
+//   - Only enumerated, harness-owned locations are considered:
+//       <reportsDir>            terminal-status reports (approved / expired)
+//       <reportsDir>/../parse-errors   parse-error logs
+//       <generatedDir>/.approvals      session / task / branch-protection markers
+//     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.
+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 { resolveGeneratedDir } from "../../runtime/pending-approval.js";
+import { resolvePaths } from "../loader.js";
+export const DEFAULT_RETENTION_DAYS = 30;
+// Same literal `harness approve understanding` uses for its parse-error
+// diagnostics lookup (approve/understanding.ts).
+const PARSE_ERRORS_DIRNAME = "parse-errors";
+function ageDays(nowMs, thenMs) {
+    return Math.round((nowMs - thenMs) / 86_400_000);
+}
+/** Plain files in `dir` whose mtime is older than `cutoffMs`. */
+function staleFilesByMtime(dir, cutoffMs, nowMs, category) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return { candidates: [], kept: 0 };
+    }
+    const candidates = [];
+    let kept = 0;
+    for (const name of names) {
+        const full = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile()) {
+            kept += 1;
+            continue;
+        }
+        if (stat.mtimeMs < cutoffMs) {
+            candidates.push({
+                filePath: full,
+                category,
+                reason: `${ageDays(nowMs, stat.mtimeMs)}d old (mtime)`,
+            });
+        }
+        else {
+            kept += 1;
+        }
+    }
+    return { candidates, kept };
+}
+export function gc(opts = {}) {
+    const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    if (!Number.isFinite(retentionDays) || retentionDays < 1) {
+        throw new Error(`retention must be a positive number of days, got ${retentionDays}`);
+    }
+    const now = opts.now ?? new Date();
+    const nowMs = now.getTime();
+    const cutoffMs = nowMs - retentionDays * 86_400_000;
+    // Path resolution mirrors `approve understanding`: explicit opts win
+    // (test injection), then env / manifest-anchored defaults. resolvePaths
+    // is evaluated lazily (and once) so injected dirs don't drag the
+    // loader in.
+    let resolvedBase;
+    const manifestBase = () => (resolvedBase ??= resolvePaths(opts).base);
+    const reportsDir = opts.reportsDir ?? defaultReportsDir(path.dirname(manifestBase()));
+    const conventionalLayout = path.basename(reportsDir) === "reports" &&
+        path.basename(path.dirname(reportsDir)) === ".understanding-gate";
+    const parseErrorsDir = conventionalLayout
+        ? path.join(path.dirname(reportsDir), PARSE_ERRORS_DIRNAME)
+        : null;
+    const generatedDir = opts.generatedDir ??
+        resolveGeneratedDir({
+            ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
+            manifestPath: manifestBase(),
+        });
+    const approvalsDir = path.join(generatedDir, APPROVAL_MARKER_DIRNAME);
+    const candidates = [];
+    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
+    // can no longer satisfy `approve understanding`, and keeping them
+    // preserves the forensic trail for the producer-side investigation.
+    for (const report of listPersistedReports(reportsDir)) {
+        const terminal = report.approvalStatus === "approved" || report.approvalStatus === "expired";
+        if (terminal && report.createdAtMs < cutoffMs) {
+            candidates.push({
+                filePath: report.filePath,
+                category: "report",
+                reason: `${report.approvalStatus}, created ${ageDays(nowMs, report.createdAtMs)}d ago`,
+            });
+        }
+        else {
+            keptCount += 1;
+        }
+    }
+    if (parseErrorsDir !== null) {
+        const parseErrors = staleFilesByMtime(parseErrorsDir, cutoffMs, nowMs, "parse-error");
+        candidates.push(...parseErrors.candidates);
+        keptCount += parseErrors.kept;
+    }
+    const markers = staleFilesByMtime(approvalsDir, cutoffMs, nowMs, "approval-marker");
+    candidates.push(...markers.candidates);
+    keptCount += markers.kept;
+    const removed = [];
+    const failures = [];
+    if (opts.apply === true) {
+        for (const c of candidates) {
+            try {
+                fs.unlinkSync(c.filePath);
+                removed.push(c.filePath);
+            }
+            catch (err) {
+                failures.push({ filePath: c.filePath, reason: err.message });
+            }
+        }
+    }
+    return {
+        retentionDays,
+        cutoffIso: new Date(cutoffMs).toISOString(),
+        reportsDir,
+        parseErrorsDir,
+        approvalsDir,
+        candidates,
+        removed,
+        failures,
+        keptCount,
+        applied: opts.apply === true,
+    };
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/cli/index.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { Command } from "commander";
 // Production version probe for `harness doctor`: synchronous --version
@@ -65,6 +66,7 @@ import { runPackHookSolutionAcceptanceWriteguardCli } from "./pack/hook-solution
 import { runPackHookRuntimeRealityCli } from "./pack/hook-runtime-reality.js";
 import { gateDisable, GateDisableError } from "./gate/disable.js";
 import { gateEnable, GateEnableError } from "./gate/enable.js";
+import { DEFAULT_RETENTION_DAYS, gc } from "./gc/index.js";
 import { uninstall, UninstallError } from "./uninstall/index.js";
 import { migrateHome } from "./migrate-home/index.js";
 import { pause as pauseHarness, resume as resumeHarness } from "./pause/index.js";
@@ -128,6 +130,7 @@ export function buildProgram(opts = {}) {
         .option("--project <name>", "apply per-project overrides for this project name")
         .option("--strict", "promote warnings to errors")
         .option("--check-lock", "surface harness.lock asset-content drift as warnings (or errors with --strict)")
+        .option("--json", "emit a structured JSON report ({ diagnostics, errorCount, warningCount }) instead of prose")
         .action((options) => {
         const result = validate({
             configPath: options.config,
@@ -135,11 +138,22 @@ export function buildProgram(opts = {}) {
             strict: options.strict,
             checkLock: options.checkLock,
         });
-        const report = formatReport(result);
-        if (result.diagnostics.length > 0)
-            stderr(report);
-        else
-            stdout(report);
+        if (options.json) {
+            // JSON goes to stdout regardless of outcome so pipelines can
+            // always parse it; the exit code still carries pass/fail.
+            stdout(`${JSON.stringify({
+                diagnostics: result.diagnostics,
+                errorCount: result.errorCount,
+                warningCount: result.warningCount,
+            }, null, 2)}\n`);
+        }
+        else {
+            const report = formatReport(result);
+            if (result.diagnostics.length > 0)
+                stderr(report);
+            else
+                stdout(report);
+        }
         if (result.errorCount > 0) {
             throw new HarnessExitError("", EX_FAIL);
         }
@@ -464,7 +478,8 @@ export function buildProgram(opts = {}) {
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides for this project name")
         .option("--dry-run", "print the would-be diff + restart hints; do not write")
-        .option("--overwrite-drift", "discard any on-disk hand-edits to harness.generated/ files (prompts for `yes`)")
+        .option("--overwrite-drift", "discard any on-disk hand-edits to harness.generated/ files (prompts for `yes`; pair with --yes for non-interactive runs)")
+        .option("--yes", "with --overwrite-drift, skip the confirmation prompt (for non-interactive use)")
         .option("--strict-lock", "refuse with exit 1 (no write) when harness.lock asset drift is detected; dry-run wins")
         .option("--target <path>", "additionally write the generated settings.json to <path> (e.g. .claude/settings.local.json)")
         .option("--merge", "with --target, 3-way merge into an existing target file (replace owned keys, preserve others)")
@@ -495,6 +510,7 @@ export function buildProgram(opts = {}) {
             ...(options.project !== undefined ? { project: options.project } : {}),
             ...(options.dryRun ? { dryRun: true } : {}),
             ...(options.overwriteDrift ? { overwriteDrift: true } : {}),
+            ...(options.yes ? { yes: true } : {}),
             ...(options.strictLock ? { strictLock: true } : {}),
             ...(options.target !== undefined ? { target: options.target } : {}),
             ...(options.merge ? { merge: true } : {}),
@@ -1066,6 +1082,11 @@ export function buildProgram(opts = {}) {
                 ? "; stamped sessionId"
                 : "";
             lines.push(`report:  ✓ ${result.persistedReport.filePath} (approvalStatus: ${prev} → approved${stampNote})`);
+            const fb = result.persistedReport.fallbackAdopted;
+            if (fb) {
+                lines.push(`  ⚠ adopted via sessionId-less fallback: created ${fb.createdAt ?? "<unknown>"} (${fb.ageMinutes}m ago).`);
+                lines.push("  The live session's report was never persisted, or an older producer", "  wrote it without a sessionId. Verify this is the report you just read", "  before trusting the approval.");
+            }
         }
         else {
             lines.push(`report:  ⚠ skipped (${result.persistedReport.reason})`);
@@ -1689,18 +1710,77 @@ export function buildProgram(opts = {}) {
             throw err;
         }
     });
+    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.")
+        .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)")
+        .action((options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.apply)
+            cliOpts.apply = true;
+        if (options.retentionDays !== undefined) {
+            const parsed = Number(options.retentionDays);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                stderr(`--retention-days must be a positive number, got ${JSON.stringify(options.retentionDays)}\n`);
+                throw new HarnessExitError("", EX_USAGE);
+            }
+            cliOpts.retentionDays = parsed;
+        }
+        const result = gc(cliOpts);
+        const sweptDirs = [
+            result.reportsDir,
+            ...(result.parseErrorsDir !== null ? [result.parseErrorsDir] : []),
+            result.approvalsDir,
+        ];
+        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.candidates.length === 0) {
+            stdout(`gc: nothing older than ${result.retentionDays}d (cutoff ${result.cutoffIso}) under\n` +
+                sweptDirs.map((d) => `  ${d}\n`).join("") +
+                `${result.keptCount} artifact(s) inspected and kept.\n`);
+            return;
+        }
+        const verb = result.applied ? "removing" : "would remove";
+        stdout(`gc: ${verb} ${result.candidates.length} artifact(s) older than ${result.retentionDays}d (cutoff ${result.cutoffIso}); keeping ${result.keptCount}:\n`);
+        for (const c of result.candidates) {
+            stdout(`  [${c.category}] ${c.filePath} (${c.reason})\n`);
+        }
+        if (!result.applied) {
+            stdout(`\nDry-run; pass --apply to delete.\n`);
+            return;
+        }
+        stdout(`removed ${result.removed.length} file(s).\n`);
+        if (result.failures.length > 0) {
+            for (const f of result.failures) {
+                stderr(`gc: failed to remove ${f.filePath}: ${f.reason}\n`);
+            }
+            throw new HarnessExitError(`${result.failures.length} deletion(s) failed`, EX_FAIL);
+        }
+    });
     program
         .command("uninstall")
         .description("Clean teardown of a harness installation. Inventories harness-owned " +
-        "entries in ~/.claude/ (manifest, lock, harness.generated/, hook groups " +
-        "and mcpServers in settings.json) and prints them. With --apply, removes " +
-        "them after writing a reversible settings.json backup + snapshot. " +
+        "state (manifest, lock, harness.generated/, .understanding-gate/ under " +
+        "the state root; hook groups and mcpServers in ~/.claude/settings.json) " +
+        "and prints it. With --apply, removes it after writing a reversible " +
+        "settings.json backup + snapshot. " +
         "settings.json.pre-harness-<TS> backups are listed but never deleted, " +
         "so the operator can hand them to --restore-from <path> (atomic restore " +
         "from that file) or `rm` them manually.")
         .option("--apply", "execute the teardown (default: dry-run listing only)")
         .option("--restore-from <path>", "atomic restore: copy this file over settings.json instead of selective removal (implies --apply)")
-        .option("--home <path>", "override ~/.claude/ root (for tests / non-default installs)")
+        .option("--home <path>", "override ~/.claude/ (settings home; without --state it also overrides the state root, for tests / non-default installs)")
+        .option("--state <path>", "override the harness state root (default: ~/.harness/, legacy fallback ~/.claude/)")
         .option("--settings <path>", "override ~/.claude/settings.json")
         .action(async (options) => {
         const cliOpts = {};
@@ -1710,6 +1790,8 @@ export function buildProgram(opts = {}) {
             cliOpts.restoreFrom = options.restoreFrom;
         if (options.home)
             cliOpts.homeDir = options.home;
+        if (options.state)
+            cliOpts.stateDir = options.state;
         if (options.settings)
             cliOpts.settingsPath = options.settings;
         try {
@@ -1719,22 +1801,28 @@ export function buildProgram(opts = {}) {
                 const nothing = inv.manifestPath === null &&
                     inv.lockPath === null &&
                     inv.generatedDir === null &&
+                    inv.gateStateDir === null &&
                     inv.hookGroups.length === 0 &&
                     inv.mcpServers.length === 0 &&
                     inv.preHarnessBackups.length === 0;
+                const rootsLabel = inv.stateDir === inv.homeDir
+                    ? inv.homeDir
+                    : `${inv.stateDir} (state) + ${inv.homeDir} (settings)`;
                 if (nothing) {
-                    stdout(`no harness install found under ${inv.homeDir}; nothing to do.\n`);
+                    stdout(`no harness install found under ${rootsLabel}; nothing to do.\n`);
                     for (const w of inv.warnings)
                         stderr(`warning: ${w}\n`);
                     return;
                 }
-                stdout(`harness install under ${inv.homeDir}:\n`);
+                stdout(`harness install under ${rootsLabel}:\n`);
                 if (inv.manifestPath)
                     stdout(`  manifest:  ${inv.manifestPath}\n`);
                 if (inv.lockPath)
                     stdout(`  lock:      ${inv.lockPath}\n`);
                 if (inv.generatedDir)
                     stdout(`  generated: ${inv.generatedDir}/\n`);
+                if (inv.gateStateDir)
+                    stdout(`  gate:      ${inv.gateStateDir}/ (understanding-gate state)\n`);
                 if (inv.hookGroups.length > 0) {
                     stdout(`  hook groups in ${inv.settingsPath}:\n`);
                     for (const g of inv.hookGroups) {
@@ -1788,11 +1876,29 @@ export function buildProgram(opts = {}) {
                 stdout(`removed from disk:\n`);
                 for (const f of result.removedFiles)
                     stdout(`  ${f}\n`);
+                // Explicit kept-list: name whatever survives under the state
+                // root (machines/ + projects/ override layers are
+                // operator-authored; foreign files are not ours to judge) so
+                // the operator never has to discover residue by accident.
+                try {
+                    const residue = fs
+                        .readdirSync(inv.stateDir)
+                        .filter((name) => !name.startsWith("settings.json"));
+                    if (residue.length > 0) {
+                        stdout(`kept under ${inv.stateDir}: ${residue.join(", ")} (not removed; operator-authored or out of scope)\n`);
+                    }
+                }
+                catch {
+                    /* state root itself may be gone or unreadable; nothing to report */
+                }
             }
             if (result.backupPath === null &&
                 result.snapshotPath === null &&
                 result.removedFiles.length === 0) {
-                stdout(`no harness install found under ${inv.homeDir}; nothing to remove.\n`);
+                const rootsLabel = inv.stateDir === inv.homeDir
+                    ? inv.homeDir
+                    : `${inv.stateDir} (state) + ${inv.homeDir} (settings)`;
+                stdout(`no harness install found under ${rootsLabel}; nothing to remove.\n`);
             }
             else {
                 stdout(`\nTo finish: \`npm uninstall -g @lannguyensi/harness\` (uninstall does not touch the npm install).\n`);