harnery 0.9.0 → 0.11.0

package/README.md

@@ -20,6 +20,7 @@
 `harnery` keeps multiple AI coding agents from stepping on each other in a shared checkout. It was extracted from years of running several Claude Code / Cursor / Codex sessions at once against the same monorepo:
 
 - **Multi-agent coordination:** per-agent heartbeats in `.harnery/active/`, claim-time and commit-time guards, the canonical event stream, councils, a decision docket, per-agent scratchpads, and harness adapters for Claude Code / Cursor / Codex.
+- **Cross-machine presence:** sessions on every machine that shares a repo see each other, labeled by machine. Zero-config over the repo's own git remote (presence refs), with an optional live-socket upgrade via an end-to-end-encrypted relay — the public `relay.harnery.com`, or self-host with `harn relay serve` / the bundled Cloudflare Worker (`relay/worker/`). The relay sees only ciphertext in opaquely-named rooms.
 - **Coordination-aware workflows:** `harn workflow run <script>` executes bounded, schema-gated multi-subagent workflow scripts — plain JS stages fanning out to headless harness-CLI subagents that are born coordination-registered (heartbeats, events, claim guards), with deterministic code deciding the routing between stages.
 - **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).

package/dist/commander.d.ts.map

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

package/dist/commander.js

@@ -22,6 +22,7 @@ import { registerBackupCommand } from "./commands/backup.js";
 import { registerBrowseCommand } from "./commands/browse.js";
 import { registerBrowseAiCommand } from "./commands/browse-ai.js";
 import { registerCallersCommand } from "./commands/callers.js";
+import { registerClaudeDesktopCommand } from "./commands/claude-desktop.js";
 import { registerCompletionCommand } from "./commands/completion.js";
 import { registerConfigGetCommand } from "./commands/config-get.js";
 import { registerContextCommand } from "./commands/context.js";
@@ -37,10 +38,12 @@ import { registerEnvCommand } from "./commands/env.js";
 import { registerFetchCommand } from "./commands/fetch.js";
 import { registerFileHistoryCommand } from "./commands/file-history.js";
 import { registerGrepCommand } from "./commands/grep.js";
+import { registerHarnessCommand } from "./commands/harness.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerOutlineCommand } from "./commands/outline.js";
 import { registerPresenceCommand } from "./commands/presence.js";
 import { registerReadCommand } from "./commands/read.js";
+import { registerRelayCommand } from "./commands/relay.js";
 import { registerScratchCommand } from "./commands/scratch.js";
 import { registerSessionCommand } from "./commands/session.js";
 import { registerSyncCommand } from "./commands/sync.js";
@@ -96,6 +99,7 @@ export function createHarneryProgram(opts = {}) {
     registerEmlCommand(program, emit);
     registerEnvCommand(program, emit, opts.context);
     registerPresenceCommand(program, emit);
+    registerRelayCommand(program, emit);
     registerConfigGetCommand(program, emit);
     registerFileHistoryCommand(program, emit);
     registerOutlineCommand(program, emit);
@@ -104,6 +108,7 @@ export function createHarneryProgram(opts = {}) {
     registerCallersCommand(program, emit, opts.context);
     registerEditBatchCommand(program, emit);
     registerGrepCommand(program, emit, opts.context);
+    registerHarnessCommand(program, emit);
     registerCookiesCommand(program, emit);
     registerFetchCommand(program, emit, opts.context);
     registerReadCommand(program, emit);
@@ -122,6 +127,7 @@ export function createHarneryProgram(opts = {}) {
     registerInitCommand(program, emit, opts.binName);
     registerDeinitCommand(program, emit, opts.binName);
     registerBackupCommand(program, emit);
+    registerClaudeDesktopCommand(program, emit);
     registerSyncCommand(program, emit);
     registerWorkflowCommand(program, emit);
     if (include("web"))

package/dist/commands/agents.d.ts

@@ -14,5 +14,29 @@
  */
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
+/**
+ * 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 declare function coordHelperOpts(root: string): {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+};
 export declare function registerAgentsCommand(program: Command, emitParam: EmitContext): void;
+/**
+ * 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 declare function buildSuggestedName(agentName: string, descriptionParts: string[]): {
+    suggestedName: string;
+    description: string;
+} | null;
 //# sourceMappingURL=agents.d.ts.map

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAwFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA4OpF"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyEnD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,CAErF;AAgCD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6PpF;AA0iCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EAAE,GACzB;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKvD"}

package/dist/commands/agents.js

@@ -18,7 +18,8 @@ import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { readStreamTailBounded } from "../core/agents/events/consume.js";
 import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, } from "../core/agents/index.js";
-import { resolveBinName } from "../core/config.js";
+import { coordFreshnessSeconds, resolveBinName } from "../core/config.js";
+import { readRemoteMachines } from "../core/presence/index.js";
 /** 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
  * never throw; covers ample recent history for a diagnostic scan. */
@@ -26,11 +27,34 @@ const STREAM_SCAN_CAP_BYTES = 128 * 1024 * 1024; // 128 MiB
 import { parsePsChainLine } from "../core/hooks/resolve/anchor.js";
 import { appendEntry, resolveOwnerByName } from "../core/scratch/index.js";
 import { buildCouncilId, buildInviteMarkdown, COUNCIL_SCHEMA_VERSION, contributorsInRound, councilBodyDir, councilsArchiveDir, deleteArchivedCouncil, effectiveSteward, findManifestByPartialId, listKnownAgents, listManifests, moveFromArchive, moveToArchive, normalizeAgentName, pendingCouncilsForMember, readArchivedManifest, readManifest, readRoundPrompts, roundDir, setCouncilSteward, writeContribution, writeManifest, writePrompt, } from "../lib/council/index.js";
+import { assumeIdentity, IdentityAssumeError } from "../lib/identities/assume.js";
 import { displayName as displayAgentName, ensureIdentity, listIdentities, lookupById as lookupIdentityById, lookupByName as lookupIdentityByName, } from "../lib/identities/index.js";
-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() {
+    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) {
+    return { cwd: root, env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root } };
+}
 function formatPlatformLabel(platform) {
     if (platform === "cursor")
         return "Cursor";
@@ -70,6 +94,17 @@ export function registerAgentsCommand(program, emitParam) {
         .action((opts) => {
         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, opts) => {
+        runSuggestName(description, opts);
+    });
     cmd
         .command("watch")
         .description("Stream peer state changes in real time (file watcher on .harnery/active/). " +
@@ -279,6 +314,59 @@ function registerIdentityCommands(parent) {
             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, opts) => {
+        runIdentityAssume(target, opts);
+    });
+}
+function runIdentityAssume(target, opts) {
+    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) {
     const council = parent
@@ -454,6 +542,7 @@ function runWhoami(opts) {
     }
     const 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),
@@ -512,7 +601,7 @@ function runList(opts) {
     }
     // 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) => {
@@ -542,6 +631,7 @@ function runList(opts) {
             // 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",
@@ -566,6 +656,7 @@ function runList(opts) {
         }
         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),
@@ -585,6 +676,30 @@ function runList(opts) {
     // (legacy zombies), and an unguarded .localeCompare throws, which is exactly
     // 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) {
@@ -691,7 +806,7 @@ async function runWatch(pollMs) {
 function listActiveHeartbeats(activeDir) {
     const out = [];
     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;
@@ -735,7 +850,7 @@ async function runShow(name, opts) {
     // Read all heartbeats; match by name (case-insensitive). Apply freshness filter.
     const matches = [];
     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;
@@ -885,6 +1000,12 @@ function shouldBootstrapCursorSession() {
 function ensureCursorSession(root) {
     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();
@@ -941,6 +1062,7 @@ function runReleaseClaim(path) {
     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({
@@ -973,10 +1095,20 @@ function runSetTask(task, opts) {
         });
         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({
@@ -993,13 +1125,87 @@ function runSetTask(task, opts) {
         harness: normalizeHarness(hb?.platform),
         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, descriptionParts) {
+    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, opts) {
+    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) {
     const root = monorepoRoot();
     if (!root) {
@@ -1038,6 +1244,7 @@ function runStatus(opts) {
         spawnSync(helper, ["stamp-status-call", myOwner], {
             encoding: "utf8",
             timeout: 2000,
+            ...coordHelperOpts(root),
         });
     }
     catch {
@@ -1060,7 +1267,7 @@ function runStatus(opts) {
         : 0;
     const activeDir = resolve(root, ".harnery", "active");
     const nowSec = Math.floor(Date.now() / 1000);
-    const cutoff = nowSec - FRESHNESS_SECS;
+    const cutoff = nowSec - freshnessCutoffSecs();
     const livePeers = [];
     let peersStale = 0;
     if (existsSync(activeDir)) {
@@ -1097,7 +1304,9 @@ function runStatus(opts) {
     });
     const filesHeld = hb.files_touched ?? [];
     const filesStr = formatList(filesHeld.map((p) => basename(p)), 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;
     if (!ctxUsage) {
@@ -1136,6 +1345,15 @@ function runStatus(opts) {
             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,
@@ -1183,8 +1401,8 @@ function formatList(items, cap, emptyLabel) {
     const shown = items.slice(0, cap).join(", ");
     return `${shown}, +${items.length - cap} more`;
 }
-function formatPeers(peers, cap, staleCount) {
-    if (peers.length === 0 && staleCount === 0)
+function formatPeers(peers, cap, staleCount, remoteMachines = []) {
+    if (peers.length === 0 && staleCount === 0 && remoteMachines.length === 0)
         return "none";
     const labels = peers.map((p) => {
         const name = p.name || "unnamed";
@@ -1203,7 +1421,17 @@ function formatPeers(peers, cap, staleCount) {
     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) {
     if (n < 1000)
@@ -1825,6 +2053,9 @@ function traceLine(ev, allTools) {
         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":
@@ -2090,7 +2321,7 @@ function runHealth(opts) {
             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)
+            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).
@@ -2126,7 +2357,7 @@ function runHealth(opts) {
         }
     }
     if (staleHeartbeats > 0) {
-        anomalies.push(`${staleHeartbeats} active heartbeat(s) older than ${Math.floor(FRESHNESS_SECS / 60)}min; heal mechanism may not be firing`);
+        anomalies.push(`${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");
     if (unexpectedSchemas.length > 0) {
@@ -2806,8 +3037,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) {
         emit.error({

package/dist/commands/backup.d.ts

@@ -11,10 +11,11 @@
  *   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 type { Command } from "commander";
 import type { EmitContext } from "../commander.js";

package/dist/commands/backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAkM/E"}
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4EnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAuM/E"}

package/dist/commands/backup.js

@@ -11,24 +11,22 @@
  *   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 { backupConfig } from "../core/config.js";
 function defaultRepo() {
-    const home = os.homedir();
-    return process.env.HARNERY_RESTIC_REPO ?? path.join(home, ".cache", "harnery", "restic-repo");
+    return backupConfig().repo;
 }
 function defaultPasswordFile() {
-    const home = os.homedir();
-    return (process.env.HARNERY_RESTIC_PASSWORD_FILE ??
-        path.join(home, ".config", "harnery", "restic-password"));
+    return backupConfig().passwordFile;
 }
 function findHarneryDir() {
     let dir = process.cwd();
@@ -203,12 +201,15 @@ export function registerBackupCommand(program, emit) {
         emit.setExitCode(r.exitCode);
     });
     // -- 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/dist/commands/browse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiH1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0KN"}
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAmH1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAoLN"}