harnery 0.9.0 → 0.11.0

package/src/commands/agents.ts

@@ -39,7 +39,8 @@ import {
   resolveOwnerBySessionEnv,
   resolveOwnerWithSource,
 } from "../core/agents/index.ts";
-import { resolveBinName } from "../core/config.ts";
+import { coordFreshnessSeconds, resolveBinName } from "../core/config.ts";
+import { type RemoteMachine, readRemoteMachines } from "../core/presence/index.ts";
 
 /** Cap for CLI scans of the unbounded event ledger (`trace` / `health`). Well
  * under V8's ~512MB max string length so a `readFileSync` of the whole file can
@@ -75,6 +76,7 @@ import {
   writeManifest,
   writePrompt,
 } from "../lib/council/index.ts";
+import { assumeIdentity, IdentityAssumeError } from "../lib/identities/assume.ts";
 import {
   displayName as displayAgentName,
   ensureIdentity,
@@ -83,13 +85,36 @@ import {
   lookupByName as lookupIdentityByName,
 } from "../lib/identities/index.ts";
 
-const FRESHNESS_SECS = 600; // 10-minute heartbeat-freshness window.
+/**
+ * Heartbeat-freshness window (seconds). Reads `coord.freshness_seconds` /
+ * `HARNERY_AGENT_COORD_FRESHNESS` via the shared accessor (defaults to 600 =
+ * 10 min). A function, not a const, so a config edit takes effect without a
+ * process restart (mtime-cached).
+ */
+function freshnessCutoffSecs(): number {
+  return coordFreshnessSeconds();
+}
 
 const SUBAGENT_NOTE =
   "Bash identity is process-level in v1; if you're running inside a subagent, " +
   "this resolves to the parent group's name, not the subagent's. A subagent-aware " +
   "bridge (per-shell marker file at .harnery/shells/<pid>) is out of scope.";
 
+/**
+ * Spawn options for agent-coord child processes: pin the coord root the
+ * command already resolved (git-superproject-aware via `monorepoRoot()`), so
+ * the helper can't re-resolve a DIFFERENT root by walking up from a drifted
+ * shell cwd. The concrete failure this prevents: a shell cd'd into an
+ * embedded harnery checkout (which carries its own committed `.harnery/`)
+ * made agent-coord resolve that nested root and miss the session's real
+ * heartbeat — `set-task: no heartbeat at .harnery/active/<id>.json` while
+ * `status` (which resolves in-process) worked fine. Mirrors the hooks side's
+ * `childEnv()`; every agent-coord spawn must carry this.
+ */
+export function coordHelperOpts(root: string): { cwd: string; env: NodeJS.ProcessEnv } {
+  return { cwd: root, env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root } };
+}
+
 function formatPlatformLabel(platform?: string | null): string {
   if (platform === "cursor") return "Cursor";
   if (platform === "codex") return "Codex";
@@ -98,10 +123,12 @@ function formatPlatformLabel(platform?: string | null): string {
 
 interface Row {
   name: string;
+  /** Durable persona UUID after an explicit identity assumption. */
+  agent_id?: string | null;
   instance_id: string;
   session_id: string;
   kind: string;
-  relation: "self" | "group" | "blocks" | "unknown";
+  relation: "self" | "group" | "blocks" | "remote" | "unknown";
   started_at: string;
   last_heartbeat: string;
   files_touched: string[];
@@ -111,6 +138,9 @@ interface Row {
   turn_summary?: string | null;
   turn_summary_updated_at?: string | null;
   platform?: string | null;
+  /** Set on relation=remote rows: the machine label the row arrived from
+   * via the cross-machine presence transport (ADR 0016). */
+  machine?: string | null;
 }
 
 let emit: EmitContext;
@@ -153,6 +183,23 @@ export function registerAgentsCommand(program: Command, emitParam: EmitContext):
       runStatus(opts);
     });
 
+  cmd
+    .command("suggest-name [description...]")
+    .description(
+      'Reprint a session name ("Agent <you> - <description>") for the operator to set as their ' +
+        "harness tab title. With no arg, derives it from your current task. The primary naming path " +
+        "is set-task (it suggests a name on the first focus declaration); reach for this to reprint " +
+        "or re-suggest after a topic pivot. Read-only.",
+    )
+    .option("--json", "JSON output instead of the bare name")
+    .option(
+      "--session-id <id>",
+      "Lookup heartbeat by session_id directly, bypassing the ppid walk.",
+    )
+    .action((description: string[], opts: { json?: boolean; sessionId?: string }) => {
+      runSuggestName(description, opts);
+    });
+
   cmd
     .command("watch")
     .description(
@@ -445,6 +492,63 @@ function registerIdentityCommands(parent: Command): void {
         meta: { action: "identity-ensure" },
       });
     });
+
+  identity
+    .command("assume <name-or-id>")
+    .description(
+      "Bind this live session to a durable persona. Reclaims an abandoned " +
+        "local namesake (no live process); refuses when another live process " +
+        "or known remote session still holds the name. Updates name history, " +
+        "the event ledger, and the heartbeat.",
+    )
+    .option("--json", "JSON envelope output")
+    .option(
+      "--session-id <id>",
+      "Bind the heartbeat with this session_id directly, bypassing the ppid walk.",
+    )
+    .action((target: string, opts: { json?: boolean; sessionId?: string }) => {
+      runIdentityAssume(target, opts);
+    });
+}
+
+function runIdentityAssume(target: string, opts: { json?: boolean; sessionId?: string }): void {
+  if (opts.json) emit.config({ format: "json" });
+  const root = monorepoRoot();
+  if (!root) {
+    emit.error({
+      code: "not_in_repo",
+      message: "not in an agent session; coord_root() returned null",
+    });
+    process.exit(1);
+  }
+  if (!opts.sessionId) ensureCursorSession(root);
+  const owner = opts.sessionId ?? resolveOwner();
+  if (!owner) {
+    emit.error({
+      code: "no_pidmap_entry",
+      message:
+        "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
+    });
+    process.exit(1);
+  }
+  try {
+    const result = assumeIdentity(root, owner, target);
+    emit.data({
+      ...result,
+      display_name: displayAgentName(result.name),
+      action: "identity-assume",
+    });
+  } catch (error) {
+    if (error instanceof IdentityAssumeError) {
+      emit.error({ code: error.code, message: error.message });
+    } else {
+      emit.error({
+        code: "identity_assume_failed",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+    process.exit(1);
+  }
 }
 
 function registerCouncilCommands(parent: Command): void {
@@ -716,6 +820,7 @@ function runWhoami(opts: { json?: boolean }): void {
 
   const row: Row = {
     name: hb.name || "unknown",
+    agent_id: hb.agent_id || null,
     instance_id: hb.instance_id,
     session_id: hb.session_id,
     kind: normalizeKind(hb.kind),
@@ -779,7 +884,7 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
 
   // Apply staleness filter unless --stale.
   const nowSec = Math.floor(Date.now() / 1000);
-  const cutoff = nowSec - FRESHNESS_SECS;
+  const cutoff = nowSec - freshnessCutoffSecs();
   const live = opts.stale
     ? heartbeats
     : heartbeats.filter((h) => {
@@ -813,6 +918,7 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
       // Orphan transient case
       rows.push({
         name: h.name || "unknown",
+        agent_id: h.agent_id || null,
         instance_id: h.instance_id,
         session_id: h.session_id,
         kind: "transient",
@@ -837,6 +943,7 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
     }
     rows.push({
       name: h.name || "unknown",
+      agent_id: h.agent_id || null,
       instance_id: h.instance_id,
       session_id: h.session_id,
       kind: normalizeKind(h.kind),
@@ -858,6 +965,31 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
   // what made `harn agents list --all --stale` crash.
   rows.sort((a, b) => (a.started_at ?? "").localeCompare(b.started_at ?? ""));
 
+  // Cross-machine presence (ADR 0016): append sessions on OTHER machines from
+  // the locally-fetched presence refs. Advisory rows (relation=remote) — they
+  // don't participate in local claim blocking in v1.
+  for (const rm of readRemoteMachines(root)) {
+    for (const a of rm.agents) {
+      rows.push({
+        name: a.name || "unknown",
+        instance_id: a.instance_id,
+        session_id: a.session_id ?? a.instance_id,
+        kind: normalizeKind(a.kind),
+        relation: "remote",
+        started_at: a.started_at ?? "",
+        last_heartbeat: a.last_heartbeat ?? "",
+        files_touched: [...(a.files_touched ?? [])].sort(),
+        last_tool: a.last_tool ?? null,
+        last_tool_target: null,
+        task: a.task ?? null,
+        turn_summary: a.turn_summary ?? null,
+        turn_summary_updated_at: null,
+        platform: a.platform ?? "claude_code",
+        machine: rm.machine,
+      });
+    }
+  }
+
   // Emit. JSON format gets {rows, note}; TTY gets the rows with note as a footnote.
   emit.data({ rows, note: SUBAGENT_NOTE });
   if (process.stdout.isTTY && !opts.json) {
@@ -976,7 +1108,7 @@ async function runWatch(pollMs: number): Promise<void> {
 function listActiveHeartbeats(activeDir: string): Heartbeat[] {
   const out: Heartbeat[] = [];
   const nowSec = Math.floor(Date.now() / 1000);
-  const cutoff = nowSec - FRESHNESS_SECS;
+  const cutoff = nowSec - freshnessCutoffSecs();
   for (const file of readdirSync(activeDir)) {
     if (!file.endsWith(".json")) continue;
     try {
@@ -1020,7 +1152,7 @@ async function runShow(name: string, opts: { json?: boolean }): Promise<void> {
   // Read all heartbeats; match by name (case-insensitive). Apply freshness filter.
   const matches: Heartbeat[] = [];
   const nowSec = Math.floor(Date.now() / 1000);
-  const cutoff = nowSec - FRESHNESS_SECS;
+  const cutoff = nowSec - freshnessCutoffSecs();
   for (const file of readdirSync(activeDir)) {
     if (!file.endsWith(".json")) continue;
     try {
@@ -1185,6 +1317,11 @@ function shouldBootstrapCursorSession(): boolean {
 
 function ensureCursorSession(root: string): void {
   if (!shouldBootstrapCursorSession()) return;
+  // Explicit owner override means the caller already knows who they are.
+  // Bootstrapping sessionStart inherits that env into the child hook, which
+  // re-projects a fresh heartbeat onto the override owner and can wipe an
+  // assumed persona agent_id (seen under Cursor integration fixtures).
+  if (process.env.HARNERY_AGENT_COORD_OWNER?.trim()) return;
   if (resolveOwnerBySessionEnv(root)) return;
 
   const sessionId = cursorEnvSessionId();
@@ -1242,6 +1379,7 @@ function runReleaseClaim(path: string): void {
   const helper = resolve(root, "harnery", "bin", "agent-coord");
   const result = spawnSync(helper, ["release-claim", myOwner, canonical], {
     encoding: "utf8",
+    ...coordHelperOpts(root),
   });
   if (result.status !== 0) {
     emit.error({
@@ -1276,10 +1414,21 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
     process.exit(1);
   }
 
+  // Snapshot BEFORE the mutation: a heartbeat that has never carried a task
+  // has no `task_updated_at` stamp (setTask always stamps it, even on a clear),
+  // so its absence is the "focus never declared this session" signal — i.e. the
+  // first set-task of the session. That's the natural moment to also hand the
+  // operator a session name built from the same declaration (one source of
+  // truth: the focus you declare names the session). Distinct from task===""
+  // (a deliberate clear), which carries a stamp and does NOT re-trigger.
+  const priorHb = readHeartbeat(myOwner);
+  const firstOfSession = !priorHb?.task_updated_at;
+
   // Heartbeat mutation goes through agent-coord (atomic temp+rename).
   const helper = resolve(root, "harnery", "bin", "agent-coord");
   const result = spawnSync(helper, ["set-task", myOwner, task], {
     encoding: "utf8",
+    ...coordHelperOpts(root),
   });
   if (result.status !== 0) {
     emit.error({
@@ -1298,14 +1447,102 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
     data: { task, cleared: !task || task.length === 0 },
   });
 
+  // On the first focus declaration of a session, surface a suggested session
+  // name for the operator to set as their harness tab title. Read the result
+  // (`suggested_session_name`) and reproduce it in a fenced code block so the
+  // UI's Copy button hands over the exact string. null on every later call.
+  const built =
+    firstOfSession && !opts?.sessionId ? buildSuggestedName(hb?.name ?? "unknown", [task]) : null;
+
   emit.data({
     instance_id: myOwner,
     name: hb?.name ?? null,
     task: hb?.task ?? null,
     cleared: !task || task.length === 0,
+    first_of_session: firstOfSession,
+    suggested_session_name: built?.suggestedName ?? null,
   });
 }
 
+/**
+ * Build the copy-pasteable session name from the coord identity + the agent's
+ * description parts. Pure (no coord-state reads) so it's unit-testable; collapses
+ * internal whitespace and trims. Returns null when the description is empty.
+ */
+export function buildSuggestedName(
+  agentName: string,
+  descriptionParts: string[],
+): { suggestedName: string; description: string } | null {
+  const description = descriptionParts.join(" ").replace(/\s+/g, " ").trim();
+  if (!description) return null;
+  const name = agentName?.trim() || "unknown";
+  return { suggestedName: `Agent ${name} - ${description}`, description };
+}
+
+function runSuggestName(
+  descriptionParts: string[],
+  opts: { json?: boolean; sessionId?: string },
+): void {
+  const root = monorepoRoot();
+  if (!root) {
+    emit.error({
+      code: "not_in_repo",
+      message: "not in an agent session; coord_root() returned null",
+    });
+    process.exit(1);
+  }
+
+  // Identity: prefer explicit --session-id (ppid-walk-free escape hatch, mirrors
+  // `status`/`set-task`), fall back to the ppid walk for interactive shell use.
+  if (!opts.sessionId) ensureCursorSession(root);
+  const myOwner = opts.sessionId ?? resolveOwner();
+  if (!myOwner) {
+    emit.error({
+      code: "no_pidmap_entry",
+      message:
+        "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
+    });
+    process.exit(1);
+  }
+
+  const hb = readHeartbeat(myOwner);
+  const agentName = hb?.name || "unknown";
+  // Description resolution: an explicit arg wins; with no arg, fall back to the
+  // agent's current declared task, so a bare `suggest-name` reprints the running
+  // session's name (handy after a topic pivot). Read-only — mutates no state;
+  // the primary naming path is set-task's first-of-session suggestion.
+  const parts = descriptionParts.length > 0 ? descriptionParts : hb?.task ? [hb.task] : [];
+  const built = buildSuggestedName(agentName, parts);
+  if (!built) {
+    emit.error({
+      code: "no_description",
+      message:
+        'pass a 2-5 word topic (e.g. suggest-name "Auth Refactor"), or declare one first with set-task',
+    });
+    process.exit(1);
+  }
+  const { suggestedName, description } = built;
+  const displayName = `agent-${agentName}`;
+
+  if (opts.json) {
+    emit.config({ format: "json" });
+    emit.data({
+      name: displayName,
+      suggested_session_name: suggestedName,
+      agent_name: agentName,
+      description,
+    });
+    return;
+  }
+
+  // Emit the bare name only — no box. The agent reproduces this exact string in
+  // a fenced code block in its reply, which every chat UI decorates with a
+  // one-click Copy button so the operator can grab it without hand-selecting.
+  // (A drawn box would copy its borders + labels too.) Direct write, not
+  // emit.text: runs via Bash with no TTY, same chat-paste contract as runStatus.
+  process.stdout.write(`${suggestedName}\n`); // lint-ok-emission: chat-paste path
+}
+
 function runStatus(opts: { json?: boolean; sessionId?: string }): void {
   const root = monorepoRoot();
   if (!root) {
@@ -1347,6 +1584,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
     spawnSync(helper, ["stamp-status-call", myOwner], {
       encoding: "utf8",
       timeout: 2000,
+      ...coordHelperOpts(root),
     });
   } catch {
     /* non-fatal */
@@ -1370,7 +1608,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
 
   const activeDir = resolve(root, ".harnery", "active");
   const nowSec = Math.floor(Date.now() / 1000);
-  const cutoff = nowSec - FRESHNESS_SECS;
+  const cutoff = nowSec - freshnessCutoffSecs();
   const livePeers: Heartbeat[] = [];
   let peersStale = 0;
   if (existsSync(activeDir)) {
@@ -1407,7 +1645,9 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
     4,
     "0 held",
   );
-  const peersStr = formatPeers(livePeers, 4, peersStale);
+  // Cross-machine presence (ADR 0016): sessions on other machines, advisory.
+  const remoteMachines = readRemoteMachines(root);
+  const peersStr = formatPeers(livePeers, 4, peersStale, remoteMachines);
 
   const ctxUsage = readContextUsage(hb.session_id, hb.platform);
   let ctxStr: string;
@@ -1449,6 +1689,15 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
       name: p.name || "unnamed",
       files: p.files_touched?.length ?? 0,
     })),
+    remote_machines: remoteMachines.map((m) => ({
+      machine: m.machine,
+      age_secs: m.age_secs,
+      agents: m.agents.map((a) => ({
+        name: a.name || "unnamed",
+        task: a.task ?? null,
+        files: a.files_touched?.length ?? 0,
+      })),
+    })),
     pending_councils: pendingCouncils,
     context_used: ctxUsage?.used ?? null,
     context_window: ctxUsage?.window ?? null,
@@ -1499,8 +1748,13 @@ function formatList(items: string[], cap: number, emptyLabel: string): string {
   return `${shown}, +${items.length - cap} more`;
 }
 
-function formatPeers(peers: Heartbeat[], cap: number, staleCount: number): string {
-  if (peers.length === 0 && staleCount === 0) return "none";
+function formatPeers(
+  peers: Heartbeat[],
+  cap: number,
+  staleCount: number,
+  remoteMachines: RemoteMachine[] = [],
+): string {
+  if (peers.length === 0 && staleCount === 0 && remoteMachines.length === 0) return "none";
   const labels = peers.map((p) => {
     const name = p.name || "unnamed";
     const plat = formatPlatformLabel(p.platform);
@@ -1516,7 +1770,16 @@ function formatPeers(peers: Heartbeat[], cap: number, staleCount: number): strin
   } else {
     main = `${labels.slice(0, cap).join(", ")}, +${labels.length - cap} more`;
   }
-  return staleCount > 0 ? `${main}; ${staleCount} stale` : main;
+  if (staleCount > 0) main = `${main}; ${staleCount} stale`;
+  // Remote machines (presence transport): `Name @machine` labels, capped.
+  if (remoteMachines.length > 0) {
+    const remote = remoteMachines
+      .flatMap((m) => m.agents.map((a) => `${a.name || "unnamed"} @${m.machine}`))
+      .slice(0, cap);
+    const extra = remoteMachines.reduce((n, m) => n + m.agents.length, 0) - remote.length;
+    main = `${main}; ${remote.join(", ")}${extra > 0 ? `, +${extra} more` : ""}`;
+  }
+  return main;
 }
 
 function fmtTokens(n: number): string {
@@ -2213,6 +2476,9 @@ function traceLine(ev: CanonicalEvent, allTools: boolean): TraceEntry | null {
     case "state.status_checked":
       detail = "status box rendered";
       break;
+    case "identity.assumed":
+      detail = `${s("previous_name") || "unknown"} → ${s("name") || "unknown"}${s("agent_id") ? ` · persona=${s("agent_id").slice(0, 8)}…` : ""}`;
+      break;
     case "claim.acquire":
     case "claim.release":
     case "claim.conflict":
@@ -2493,7 +2759,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       activeBySchema[schemaKey] = (activeBySchema[schemaKey] ?? 0) + 1;
       const lastHbMs = hb.last_heartbeat ? Date.parse(hb.last_heartbeat) : Number.NaN;
       const ageMs = Number.isFinite(lastHbMs) ? nowMs - lastHbMs : Number.POSITIVE_INFINITY;
-      if (ageMs > FRESHNESS_SECS * 1000) staleHeartbeats++;
+      if (ageMs > freshnessCutoffSecs() * 1000) staleHeartbeats++;
       // Zombie heuristics on a parseable heartbeat: no name, or an age so large
       // it can only be a broken/epoch timestamp (a real agent would have healed).
       if (!hb.name || hb.name === "unknown" || ageMs > ABSURD_AGE_MS) {
@@ -2533,7 +2799,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
   }
   if (staleHeartbeats > 0) {
     anomalies.push(
-      `${staleHeartbeats} active heartbeat(s) older than ${Math.floor(FRESHNESS_SECS / 60)}min; heal mechanism may not be firing`,
+      `${staleHeartbeats} active heartbeat(s) older than ${Math.floor(freshnessCutoffSecs() / 60)}min; heal mechanism may not be firing`,
     );
   }
   const unexpectedSchemas = Object.keys(activeBySchema).filter((k) => k !== "v1");
@@ -3317,8 +3583,8 @@ function runHeal(opts: {
   // agent-coord binary at harnery/bin/agent-coord.
   const helper = `${root}/harnery/bin/agent-coord`;
   const proc = spawnSync(helper, helperArgs, {
-    cwd: root,
     encoding: "utf8",
+    ...coordHelperOpts(root),
   });
 
   if (proc.status !== 0) {

package/src/commands/backup.ts

@@ -11,31 +11,27 @@
  *   restore   restic restore <id>
  *   prune     restic forget --keep-daily 7 --keep-weekly 4 --prune
  *
- * Power users override via env vars (HARNERY_RESTIC_REPO, HARNERY_RESTIC_PASSWORD_FILE)
- * or by passing through any restic args after `--`. The wrapper deliberately
- * doesn't try to abstract restic; it surfaces it, with opinionated defaults plus
- * passthrough.
+ * Defaults (repo path, password file, and the keep-daily/weekly/monthly prune
+ * policy) come from `.harnery/config.jsonc` `backup.*`, overridable per field by
+ * env vars (HARNERY_RESTIC_REPO, HARNERY_RESTIC_PASSWORD_FILE) and CLI flags —
+ * see `backupConfig()`. The wrapper deliberately doesn't try to abstract restic;
+ * it surfaces it, with opinionated defaults plus passthrough after `--`.
  */
 
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { backupConfig } from "../core/config.ts";
 
 function defaultRepo(): string {
-  const home = os.homedir();
-  return process.env.HARNERY_RESTIC_REPO ?? path.join(home, ".cache", "harnery", "restic-repo");
+  return backupConfig().repo;
 }
 
 function defaultPasswordFile(): string {
-  const home = os.homedir();
-  return (
-    process.env.HARNERY_RESTIC_PASSWORD_FILE ??
-    path.join(home, ".config", "harnery", "restic-password")
-  );
+  return backupConfig().passwordFile;
 }
 
 function findHarneryDir(): string | null {
@@ -237,12 +233,17 @@ export function registerBackupCommand(program: Command, emit: EmitContext): void
     });
 
   // -- prune --
+  // Prune-policy defaults come from backup.keep_* in config.jsonc (falling back
+  // to 7/4/6); an explicit --keep-* flag still overrides per invocation.
+  const prunePolicy = backupConfig();
   backup
     .command("prune")
-    .description("Forget + prune snapshots (default policy: keep 7 daily / 4 weekly / 6 monthly).")
-    .option("--keep-daily <n>", "Daily snapshots to keep", "7")
-    .option("--keep-weekly <n>", "Weekly snapshots to keep", "4")
-    .option("--keep-monthly <n>", "Monthly snapshots to keep", "6")
+    .description(
+      `Forget + prune snapshots (default policy: keep ${prunePolicy.keepDaily} daily / ${prunePolicy.keepWeekly} weekly / ${prunePolicy.keepMonthly} monthly).`,
+    )
+    .option("--keep-daily <n>", "Daily snapshots to keep", String(prunePolicy.keepDaily))
+    .option("--keep-weekly <n>", "Weekly snapshots to keep", String(prunePolicy.keepWeekly))
+    .option("--keep-monthly <n>", "Monthly snapshots to keep", String(prunePolicy.keepMonthly))
     .option("--dry-run", "Show what would be pruned without actually pruning")
     .option("--repo <path>", "Repository path")
     .option("--password-file <path>", "Password file")

package/src/commands/browse.ts

@@ -13,6 +13,7 @@ import {
   type RuntsResult,
   type VisibilityResult,
   type WidthResult,
+  wslHeadedLaunchArgs,
 } from "../lib/browser/index.ts";
 import {
   type DiffResult,
@@ -66,6 +67,7 @@ interface BrowseOpts {
   networkHar?: string;
   login?: boolean;
   headed?: boolean;
+  browserArg?: string[];
   cookies?: boolean;
   store?: string;
   profile?: string;
@@ -162,6 +164,16 @@ export function registerBrowseCommand(
     )
     .option("--login", "Headed mode for one-time auth flow (cookies persist in profile)")
     .option("--headed", "Headed mode for one-off (no auth-flow framing)")
+    .option(
+      "--browser-arg <flag>",
+      "Extra Chromium launch flag, passed straight to the browser (repeatable). " +
+        "e.g. --browser-arg --disable-gpu. Also settable machine-wide via the " +
+        "HARNERY_BROWSER_ARGS env var (whitespace-separated). Under WSL, headed " +
+        "launches auto-add --disable-gpu to fix blank-window paint; opt out with " +
+        "HARNERY_BROWSER_NO_WSL_DEFAULTS=1.",
+      (value: string, prev: string[] = []) => [...prev, value],
+      [] as string[],
+    )
     .option("--no-cookies", "Skip cookie-jar attach and persist")
     .option("--store <path>", `Cookie store path (default ${DEFAULT_STORE})`)
     .option("--profile <dir>", `Persistent Chromium profile dir (default ${DEFAULT_PROFILE})`)
@@ -313,6 +325,7 @@ async function runBrowse(
     waitUntil: opts.waitUntil as BrowseOpts["waitUntil"] as never,
     recordHarPath: opts.networkHar ? resolve(opts.networkHar) : undefined,
     extraHeaders: context?.extraHeaders,
+    launchArgs: resolveLaunchArgs(opts, Boolean(headed)),
   });
 
   // Print mode: --snapshot / --html / --json all suppress file writes.
@@ -878,6 +891,25 @@ function summarizeDiagnostics(diag: Diagnostics): Record<string, unknown> {
   };
 }
 
+/**
+ * Merge Chromium launch flags from three sources, in order, de-duped:
+ *   1. WSLg headed default (`--disable-gpu`) — auto-applied for headed launches
+ *      under WSL so the window actually paints. Opt out with
+ *      HARNERY_BROWSER_NO_WSL_DEFAULTS=1.
+ *   2. HARNERY_BROWSER_ARGS env (whitespace-separated) — a machine-wide default.
+ *   3. --browser-arg flags on this invocation (repeatable).
+ */
+function resolveLaunchArgs(opts: BrowseOpts, headed: boolean): string[] {
+  const args: string[] = [];
+  if (headed && !process.env.HARNERY_BROWSER_NO_WSL_DEFAULTS) {
+    args.push(...wslHeadedLaunchArgs());
+  }
+  const envArgs = process.env.HARNERY_BROWSER_ARGS?.trim();
+  if (envArgs) args.push(...envArgs.split(/\s+/));
+  if (opts.browserArg && opts.browserArg.length > 0) args.push(...opts.browserArg);
+  return [...new Set(args)];
+}
+
 function parseViewport(spec: string): { width: number; height: number } {
   const preset = VIEWPORT_PRESETS[spec.toLowerCase()];
   if (preset) return preset;