@lannguyensi/harness 0.23.2 → 0.24.0

package/dist/cli/index.js

@@ -56,6 +56,7 @@ import { runPackHookBranchProtectionCli } from "./pack/hook-branch-protection.js
 import { gateDisable, GateDisableError } from "./gate/disable.js";
 import { gateEnable, GateEnableError } from "./gate/enable.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";
 import { formatSmokeReport, runSmoke, splitCommaList, } from "./smoke/index.js";
 import { formatReport, validate } from "./validate/index.js";
@@ -88,7 +89,7 @@ export function buildProgram(opts = {}) {
     program
         .command("describe")
         .description("Print the effective merged manifest")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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("--pillar <pillar>", "filter output to one section: grounding | tools | memory | hooks | policies | workflows | review_templates")
         .option("--json", "emit JSON instead of YAML")
@@ -113,7 +114,7 @@ export function buildProgram(opts = {}) {
     program
         .command("validate")
         .description("Lint the manifest + referenced assets")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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("--strict", "promote warnings to errors")
         .option("--check-lock", "surface harness.lock asset-content drift as warnings (or errors with --strict)")
@@ -136,7 +137,7 @@ export function buildProgram(opts = {}) {
     program
         .command("doctor")
         .description("Health summary across all pillars")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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("--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(", ")})`)
@@ -166,7 +167,7 @@ export function buildProgram(opts = {}) {
     program
         .command("list <category>")
         .description("Flat denormalised listing per category: mcp / cli / skills / memories / hooks / policies / workflows")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--filter <substr>", "case-insensitive substring filter on name (or path for memories)")
         .option("--json", "emit JSON array instead of an aligned text table")
@@ -187,7 +188,7 @@ export function buildProgram(opts = {}) {
         .description("Diff the manifest against a git ref (--since <ref>) or against the last " +
         "applied state (--since-apply). --memory-detail expands per-memory-dir " +
         "Merkle drift back to per-file changes.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--since <ref>", "git ref to diff against")
         .option("--since-apply", "diff against harness.generated/.last-apply")
@@ -230,8 +231,8 @@ export function buildProgram(opts = {}) {
         .description("Bootstrap a starter harness.yaml from a template")
         .option("--template <name>", `template to instantiate: ${KNOWN_TEMPLATES.join(" | ")} (default: minimal)`)
         .option("--force", "overwrite an existing manifest")
-        .option("--config <path>", "manifest path to write (default: ~/.claude/harness.yaml)")
-        .option("--probe", "skip writing, print a JSON snapshot of detected runtimes (Claude Code, Codex), the existing ~/.claude/harness.yaml, and MCP servers wired in settings.json. Read-only.")
+        .option("--config <path>", "manifest path to write (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--probe", "skip writing, print a JSON snapshot of detected runtimes (Claude Code, Codex), the existing ~/.harness/harness.yaml (or legacy ~/.claude/harness.yaml), and MCP servers wired in settings.json. Read-only.")
         .option("--interactive", "run the guided wizard (detect environment, pick profile, preview + write). Mutually exclusive with --probe / --template.")
         .action(async (options) => {
         if (options.probe && options.interactive) {
@@ -275,7 +276,7 @@ export function buildProgram(opts = {}) {
         .description("Insert a new entry into harness.yaml (managed mutation)");
     function addCommonOptions(c) {
         return c
-            .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+            .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");
     }
     function parseBlocking(s) {
@@ -383,7 +384,7 @@ export function buildProgram(opts = {}) {
         .description("Emit the effective merged manifest as a single self-contained YAML " +
         "(or JSON). --sanitize redacts /home/<user>/ paths and env values whose " +
         "key looks credential-shaped.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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("--sanitize", "redact /home/<user>/ paths and credential-shaped env values")
         .option("--json", "emit JSON instead of YAML")
@@ -410,7 +411,7 @@ export function buildProgram(opts = {}) {
         .description("Capture hand-edits from a runtime file (today: ~/.claude/settings.json) " +
         "into the manifest. Diffs against the manifest's current declarations and " +
         "prompts y/N before writing.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--yes", "skip the confirmation prompt (for non-interactive use)")
         .action(async (file, options) => {
         const result = await adopt(file, { configPath: options.config, yes: options.yes });
@@ -441,7 +442,7 @@ export function buildProgram(opts = {}) {
         .description("Regenerate harness.generated/ outputs (settings.json + MEMORY.md index) " +
         "from the manifest. Refuses to overwrite hand-edits without --overwrite-drift; " +
         "use `harness adopt <file>` to capture them back into the manifest instead.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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`)")
@@ -452,6 +453,8 @@ export function buildProgram(opts = {}) {
         .option("--runtime <runtime>", `policy-pack adapter runtime (${KNOWN_RUNTIMES.join(" | ")}; default: claude-code). ` +
         "Selects which adapter shape policy-pack hooks expand into and which artefacts apply writes. " +
         "`codex` emits harness.generated/codex/config.toml in place of settings.json.")
+        .option("--install", "with --runtime codex, merge the generated hook block into ~/.codex/config.toml")
+        .option("--codex-config <path>", "with --runtime codex --install, override the Codex config path (default ~/.codex/config.toml)")
         .option("--quiet", "suppress the post-apply Next-steps hint")
         .option("--json", "emit a structured JSON summary instead of prose (implies --quiet)")
         .action(async (options) => {
@@ -478,6 +481,10 @@ export function buildProgram(opts = {}) {
             ...(options.merge ? { merge: true } : {}),
             ...(options.force ? { force: true } : {}),
             ...(runtime !== undefined ? { runtime } : {}),
+            ...(options.install ? { installCodex: true } : {}),
+            ...(options.codexConfig !== undefined
+                ? { codexConfigPath: options.codexConfig }
+                : {}),
         });
         if (options.json) {
             // Machine-readable: one JSON object on stdout regardless of
@@ -532,6 +539,9 @@ export function buildProgram(opts = {}) {
             for (const f of changedFiles) {
                 stdout(`  ${f.path}\n`);
             }
+            if (result.codexConfigInstall?.changed) {
+                stdout(`  ${result.codexConfigInstall.configPath} (Codex install)\n`);
+            }
         }
         else {
             stdout(`applied ${changedFiles.length} file(s):\n`);
@@ -546,6 +556,12 @@ export function buildProgram(opts = {}) {
                     stdout(`wrote target: ${result.targetPath}\n`);
                 }
             }
+            if (result.codexConfigInstall?.written) {
+                stdout(`${result.codexConfigInstall.summary}\n`);
+                if (result.codexConfigInstall.backupPath) {
+                    stdout(`backup written to ${result.codexConfigInstall.backupPath}\n`);
+                }
+            }
             stdout(`harness.lock written to ${result.lockPath}\n`);
             if (!options.quiet) {
                 // The hint passes `targetPath` only when the target was
@@ -587,7 +603,7 @@ export function buildProgram(opts = {}) {
         .command("remove <type> <name>")
         .description(`Remove an entry by name. <type> is one of ${KNOWN_REMOVE_TYPES.join(" | ")}. ` +
         "Refuses to remove a hook still referenced by a policy unless --force.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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")
         .option("--force", "remove even if a policy references this entry (dangling policy.hook is then caught by schema)")
         .action(async (type, name, options) => {
@@ -615,7 +631,7 @@ export function buildProgram(opts = {}) {
     packCmd
         .command("add <name>")
         .description("Insert a new policy_packs entry. <name> must be a known builtin (see docs/policy-packs/).")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--mode <mode>", "pack-specific config.mode value (e.g. fast_confirm | grill_me | strict)")
         .option("--source <src>", "pack source (default: builtin)")
         .option("--description <text>", "operator-facing description")
@@ -645,7 +661,7 @@ export function buildProgram(opts = {}) {
         .command("remove <name>")
         .description("Remove a policy_packs entry. Refuses without --force when applied state " +
         "is recorded in .last-apply.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .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")
         .option("--force", "remove the manifest entry AND clean up the on-disk pack files + .last-apply state")
         .action(async (name, options) => {
@@ -673,7 +689,7 @@ export function buildProgram(opts = {}) {
     packHookCmd
         .command("pre-tool-use")
         .description("PreToolUse blocker: read tool-event JSON from stdin, consult ledger + persisted report, emit deny JSON on block")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--pack <name>", "pack name to evaluate (default: understanding-before-execution)")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
@@ -698,7 +714,7 @@ export function buildProgram(opts = {}) {
     packHookCmd
         .command("post-tool-use")
         .description("PostToolUse marker-expiry: read tool-event JSON from stdin, delete the per-session approval marker when the just-completed tool matches config.approval_lifecycle.expire_on_tool_match (agent-tasks/d8ee60ca)")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--pack <name>", "pack name to evaluate (default: understanding-before-execution)")
         .action(async (options) => {
@@ -714,7 +730,7 @@ export function buildProgram(opts = {}) {
     packHookCmd
         .command("track-active-claim")
         .description("PostToolUse: read tool-event JSON from stdin, maintain ~/.claude/harness.generated/active-claim on agent-tasks task_start / task_finish / task_abandon so `harness approve understanding` can auto-resolve the task id without --task (harness/494fd1e5).")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--pack <name>", "pack name to evaluate (default: understanding-before-execution)")
         .action(async (options) => {
@@ -733,7 +749,7 @@ export function buildProgram(opts = {}) {
     packHookCmd
         .command("codex-pre-tool-use")
         .description("Codex PreToolUse blocker: read tool-event JSON from stdin, consult ledger + persisted report, exit 2 with stderr reason on block")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--pack <name>", "pack name to evaluate (default: understanding-before-execution)")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
@@ -761,7 +777,7 @@ export function buildProgram(opts = {}) {
     packHookCmd
         .command("codex-user-prompt-submit")
         .description("Codex UserPromptSubmit injector: emit the Understanding-Gate instruction template on stdout for Codex to prepend to additional_instructions")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--pack <name>", "pack name to evaluate (default: understanding-before-execution)")
         .action(async (options) => {
@@ -779,7 +795,7 @@ export function buildProgram(opts = {}) {
         .description("PreToolUse blocker for the branch-protection pack: read tool-event JSON from stdin, consult the " +
         "evidence ledger, emit a deny envelope on protected branches unless either a fresh " +
         "`branch:non-protected` tag (within 5m) or a `branch-protection-ack` override is present.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
         .option("--cwd <path>", "override cwd resolution (default: stdin event.cwd then process.cwd())")
@@ -804,7 +820,7 @@ export function buildProgram(opts = {}) {
     packHookCmd
         .command("codex-stop")
         .description("Codex Stop-equivalent: parse the agent's last message for an Understanding Report and persist it under .understanding-gate/reports/ as approvalStatus:pending. Failure modes resolve to exit 0 (capture must never block the agent's stop path).")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--pack <name>", "pack name to evaluate (default: understanding-before-execution)")
         .option("--reports-dir <path>", "override the persisted-report directory (default: ./.understanding-gate/reports)")
@@ -830,7 +846,7 @@ export function buildProgram(opts = {}) {
     packCmd
         .command("list")
         .description("Print policy_packs entries as a flat table or JSON.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--enabled-only", "skip entries with enabled: false")
         .option("--json", "emit JSON array instead of an aligned text table")
@@ -854,7 +870,7 @@ export function buildProgram(opts = {}) {
         .command("understanding")
         .description("Mark the latest Understanding Report as approved AND write the evidence-ledger tag. " +
         "Round-trips both sources so harnessed and solo (@lannguyensi/understanding-gate) stacks stay in sync.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--session <id>", "explicit session id (default: $CLAUDE_SESSION_ID)")
         .option("--task <id>", "agent-tasks task id — when set, also writes a task-scoped marker so the next task re-prompts for an Understanding Report (harness/1ee26e77)")
@@ -880,9 +896,13 @@ export function buildProgram(opts = {}) {
         // a wrong id before it lands in the ledger.
         const sourceNote = result.sessionSource === "pending-approval"
             ? " (resolved from .pending-approval staged by the gate hook)"
-            : result.sessionSource === "env"
+            : result.sessionSource === "env-claude"
                 ? " (from $CLAUDE_SESSION_ID)"
-                : "";
+                : result.sessionSource === "env-codex"
+                    ? " (from $CODEX_SESSION_ID)"
+                    : result.sessionSource === "newest-report"
+                        ? " (resolved from sessionId field of the newest persisted Understanding Report)"
+                        : "";
         lines.push(`session: ${result.sessionId}${sourceNote}`);
         if (result.marker.ok) {
             lines.push(`marker:  ✓ ${result.marker.filePath} (canonical gate signal)`);
@@ -923,7 +943,7 @@ export function buildProgram(opts = {}) {
     program
         .command("explain [policy]")
         .description("Print a policy's definition; --trace reads the last recorded evaluation; --last traces the most recent decision in the ledger")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--json", "emit JSON instead of YAML")
         .option("--trace", "include the full decision trail from the most recent evaluation")
@@ -965,7 +985,7 @@ export function buildProgram(opts = {}) {
         .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 / deny / warn-degraded)")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--session <id>", "grounding session whose audit log to read (default: $CLAUDE_SESSION_ID, then 'default')")
         .option("--json", "emit JSON instead of a table")
@@ -991,7 +1011,7 @@ export function buildProgram(opts = {}) {
     program
         .command("session-export [sessionId]")
         .description("Export a chronological audit artifact joining the on-disk transcript JSONL and the evidence ledger for a session")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--format <fmt>", "output format: json (default) or jsonl", "json")
         .option("-o, --out <file>", "write the export to <file> instead of stdout")
@@ -1022,7 +1042,7 @@ export function buildProgram(opts = {}) {
     program
         .command("dry-run <prompt>")
         .description("Statically predict which hooks fire / policies match / memories route for a prompt")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--tool <name>", "simulate a PreToolUse event for this tool name")
         .option("--tool-args <json>", "JSON for tool_input (default: {})")
@@ -1049,7 +1069,7 @@ export function buildProgram(opts = {}) {
         "Replaces the hand-rolled dogfood recipes under dogfood/phase5/.")
         .requiredOption("--prompt <text>", "Prompt fed to claude -p")
         .requiredOption("--output-dir <path>", "Directory for stream.jsonl + stderr.log + settings.json")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--session-id <id>", "session id (default: fresh uuid)")
         .option("--claude-bin <path>", "claude binary (default: $CLAUDE_BIN, then 'claude' on PATH)")
@@ -1110,7 +1130,7 @@ export function buildProgram(opts = {}) {
         .command("preflight")
         .description("Alias for `harness session-start preflight`: run agent-preflight against the session cwd " +
         "and, on a ready:true result, record a `preflight:${REPO}` fact to the evidence ledger.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--session <id>", "explicit session id (overrides stdin event + env)")
         .option("--timeout <ms>", "agent-preflight subprocess timeout in milliseconds (default 60000)")
@@ -1148,7 +1168,7 @@ export function buildProgram(opts = {}) {
         "record a `preflight:${REPO}` fact to the evidence ledger so the preflight-before-* policies have a " +
         "fresh tag to match. Reads SessionStart event JSON from stdin ({ session_id, cwd, hook_event_name }). " +
         "blocking:false — every failure path logs to stderr and exits 0.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--session <id>", "explicit session id (overrides stdin event + env). Use for manual / scripted invocations " +
         "where no SessionStart event JSON is piped on stdin. Without it the resolver tries " +
@@ -1187,7 +1207,7 @@ export function buildProgram(opts = {}) {
         "record a `branch:non-protected:<branch>` fact to the evidence ledger so the pack's PreToolUse " +
         "blocker has a fresh tag to satisfy its 5-minute freshness window. Also runnable on demand from " +
         "the operator's shell. blocking:false — every failure path logs to stderr and exits 0.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--session <id>", "explicit session id (overrides stdin event + env)")
         .option("--cwd <path>", "override cwd resolution (default: stdin event.cwd then process.cwd())")
@@ -1421,12 +1441,25 @@ export function buildProgram(opts = {}) {
         }
     });
     program
+        .command("migrate-home")
+        .description("Move harness operator-state from the legacy ~/.claude/ root to the runtime-neutral " +
+        "~/.harness/ root introduced in v0.24.0. Dry-run by default; pass --apply to perform " +
+        "the move. Re-running on already-migrated state is a no-op. Moves: harness.yaml, " +
+        "harness.generated/, .understanding-gate/, harness.lock. Does NOT touch settings.json " +
+        "or any other ~/.claude/ contents.")
+        .option("--apply", "perform the move (default: dry-run report only)")
+        .action(async (options) => {
+        const result = migrateHome({ ...(options.apply ? { apply: true } : {}) });
+        if (result.outcome === "target-conflict") {
+            throw new HarnessExitError("", EX_FAIL);
+        }
+    })
         .command("pause")
         .description("Temporarily make all harness hooks dormant by writing a sentinel under harness.generated/. " +
         "Operator-only (refuses when $CLAUDE_SESSION_ID is set or stdin is non-TTY). Intended for " +
         "lockout recovery, debug A/B-tests, and incident hotfixes. NOT for routine gate bypass: " +
         "for permanent per-policy disable, edit `policies[].enabled` in the manifest.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--for <duration>", "auto-resume after this duration (e.g. 5m, 1h, PT30S; default: 15m)")
         .option("--indefinite", "skip auto-expiry (requires --i-am-the-operator-and-accept-no-auto-resume)")
@@ -1476,7 +1509,7 @@ export function buildProgram(opts = {}) {
         .command("resume")
         .description("Delete the pause sentinel and re-enable harness hooks. Operator-only. Idempotent: " +
         "running against an un-paused install exits 0 with a notice.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--i-am-the-operator", "acknowledge a scripted / non-TTY invocation (otherwise refused)")
         .action(async (options) => {
@@ -1516,7 +1549,7 @@ export function buildProgram(opts = {}) {
         "Stdin shape (per Claude Code hook protocol): " +
         "{ session_id, hook_event_name, tool_name, tool_input, cwd?, transcript_path? }. " +
         "hook_event_name is required for any policy to match; if missing or unmatched, a one-line diagnostic is written to stderr.")
-        .option("--config <path>", "manifest path (default: ~/.claude/harness.yaml)")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
         .option("--verbose", "emit a stderr diagnostic block for each non-allow decision (also enabled by HARNESS_POLICY_VERBOSE=1)")