@sentropic/h2a-cli 0.57.0 → 0.61.0

package/dist/cli.js

@@ -36,9 +36,9 @@
  * The full machine-readable manifest lives in `./cli-contract.ts`
  * (`H2A_CLI_VERB_CONTRACTS`). Human-readable reference: `docs/cli-contract.md`.
  */
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { generateKeyPairSync } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, realpathSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -49,7 +49,7 @@ import { H2A_GEMINI_HOST } from "./hosts/gemini.js";
 import { H2A_AGY_HOST } from "./hosts/agy.js";
 import { H2A_CLI_MCP_TOOL_NAMES } from "./mcp.js";
 import { renderStopHook, claudeStopHookEntry, claudeDriveReceiveHookEntry, isH2ADriveReceiveHook, isH2ARecordHook, codexPluginManifest, codexMarketplaceManifest, codexPluginTrustCommands, H2A_CODEX_PLUGIN_NAME, H2A_HOST_PLUGIN_HOSTS } from "./hosts/plugin.js";
-import { H2A_STORE_SCHEMA_VERSION, assertHostQualifiedAddress, canonicalAddress, createLocalStore, listPresence, safePathSegment, sanitizeStorePaths } from "./runtime/local-files/index.js";
+import { H2A_STORE_SCHEMA_VERSION, assertHostQualifiedAddress, canonicalAddress, createLocalStore, listPresence, readPresence, resolveRecipient, safePathSegment, sanitizeStorePaths, writePresence } from "./runtime/local-files/index.js";
 import { runMcpStdio } from "./runtime/mcp/index.js";
 import { renderK8sSidecar } from "./runtime/deploy/k8s-sidecar.js";
 import { renderK8sTenant } from "./runtime/deploy/k8s-tenant.js";
@@ -172,7 +172,9 @@ export function renderCliHelp() {
         "",
         "High-level coordination (DEC-054):",
         "  h2a connect --host <codex|claude|gemini|agy|remote> [--root <path>] [--instance <id>] [--name <display>]",
-        "  h2a doctor [--root <path>]",
+        "  h2a doctor [--root <path>] [--scan <dir>] [--prune]   (--prune deletes host-less/phantom/orphan inbox dirs + stray buses; dry-run by default)",
+        "  h2a keepalive [--root <path>] [--interval <ms>] [--once]   (external keepalive prober — refreshes presence for agents whose tmux pane is still alive)",
+        "  h2a rename --instance <id> --name <name> [--root <path>]   (set a live session's display name so peers can find it via discover --name)",
         "  h2a status [--root <path>] [--scope <s>] [--instance <i>]",
         "  h2a sessions [--root <path>] [--scope <s>] [--instance <i>]",
         "  h2a thread --id <threadId> --instance <self> [--root <path>]   (the ordered conversation for a thread, from your inbox+outbox)",
@@ -216,10 +218,59 @@ function parseFlags(argv) {
     }
     return { command, flags };
 }
-function resolveRoot(flags, cwd) {
+/**
+ * Resolve the h2a store root, with its provenance.
+ *
+ * Precedence: explicit `--root` flag → `H2A_ROOT` env → the shared global
+ * default `~/h2a-workspace/.h2a`. The global default lets all agents on the
+ * same machine share one bus without any explicit configuration — eliminating
+ * the split-brain failure (F4) that the old `cwd/.h2a` fallback caused.
+ * Callers on long-lived paths (`mcp-serve`, `connect`) warn when a repo-local
+ * `.h2a` exists and is being ignored in favour of the shared bus.
+ */
+function resolveRootInfo(flags, cwd) {
     if (flags.root)
-        return flags.root;
-    return join(cwd(), ".h2a");
+        return { root: flags.root, source: "flag" };
+    const env = process.env.H2A_ROOT;
+    if (env && env.length > 0)
+        return { root: env, source: "env" };
+    return { root: join(homedir(), "h2a-workspace", ".h2a"), source: "default" };
+}
+function resolveRoot(flags, cwd) {
+    return resolveRootInfo(flags, cwd).root;
+}
+/**
+ * Warn (once, to stderr) when the root was taken from the shared default but a
+ * DIFFERENT repo-local `.h2a` exists in the current working directory. The
+ * user may have intended to use the local bus — so we alert them to pass
+ * `--root <cwd>/.h2a` if that was their intent. When the default IS the right
+ * bus (no local `.h2a` around), stay silent. Used by `mcp-serve` and `connect`.
+ */
+function warnIfCwdRootFallback(flags, cwd, streams) {
+    const info = resolveRootInfo(flags, cwd);
+    if (info.source !== "default")
+        return;
+    const cwdLocal = join(cwd(), ".h2a");
+    try {
+        if (!existsSync(cwdLocal))
+            return;
+        const resolvedLocal = realpathSync(cwdLocal);
+        const resolvedRoot = (() => {
+            try {
+                return realpathSync(info.root);
+            }
+            catch {
+                return info.root;
+            }
+        })();
+        if (resolvedLocal === resolvedRoot)
+            return;
+        streams.stderr.write(`h2a: a repo-local .h2a exists here but I'm using the shared bus ${info.root}. ` +
+            `Pass --root ${cwdLocal} if you meant the local one.\n`);
+    }
+    catch {
+        // silently ignore filesystem errors
+    }
 }
 /**
  * Resolve `causationId` / `correlationId` for a new negotiation event.
@@ -434,6 +485,20 @@ function cmdMailbox(argv, mailbox, streams) {
                 streams.stderr.write(`\n${error.message}\n`);
                 return 1;
             }
+            // WP-2: resolve-before-send — legibility gate (does NOT change destination).
+            const root = resolveRoot(flags, streams.cwd ?? (() => process.cwd()));
+            const liveSessions = listPresence(root).map((s) => s.instance);
+            const registeredIds = store.listInstances().map((i) => i.instance ?? i.id);
+            const resolution = resolveRecipient({
+                target: flags.instance,
+                liveInstances: liveSessions,
+                registeredInstances: registeredIds
+            });
+            if (resolution.kind === "refuse") {
+                streams.stderr.write(`\nh2a: ${resolution.reason}${resolution.candidates ? `\ncandidates: ${resolution.candidates.join(", ")}` : ""}\n`);
+                return 1;
+            }
+            // deliver / deliver-dormant / deliver-hint → proceed with put below.
         }
         try {
             if (mailbox === "inbox") {
@@ -447,7 +512,24 @@ function cmdMailbox(argv, mailbox, streams) {
             const recipientLive = mailbox === "inbox"
                 ? listPresence(store.paths.root).some((s) => canonicalAddress(s.instance) === canonicalAddress(flags.instance))
                 : undefined;
-            streams.stdout.write(`${JSON.stringify({ ok: true, id: envelope.id, mailbox, instance: flags.instance, ...(recipientLive !== undefined ? { recipientLive } : {}) }, null, 2)}\n`);
+            // WP-2: enrich stdout with resolution metadata.
+            let resolutionMeta = {};
+            if (mailbox === "inbox") {
+                const root2 = resolveRoot(flags, streams.cwd ?? (() => process.cwd()));
+                const liveSessions2 = listPresence(root2).map((s) => s.instance);
+                const registeredIds2 = store.listInstances().map((i) => i.instance ?? i.id);
+                const resolution2 = resolveRecipient({
+                    target: flags.instance,
+                    liveInstances: liveSessions2,
+                    registeredInstances: registeredIds2
+                });
+                resolutionMeta = {
+                    resolution: resolution2.kind,
+                    ...(resolution2.kind === "deliver-hint" ? { liveCandidate: resolution2.liveCandidate, reason: resolution2.reason } : {}),
+                    ...(resolution2.kind === "deliver-dormant" ? { reason: resolution2.reason, dormant: true } : {})
+                };
+            }
+            streams.stdout.write(`${JSON.stringify({ ok: true, id: envelope.id, mailbox, instance: flags.instance, ...(recipientLive !== undefined ? { recipientLive } : {}), ...resolutionMeta }, null, 2)}\n`);
             return 0;
         }
         catch (error) {
@@ -1093,6 +1175,7 @@ export async function runMcpServe(flags, io = {
     stderr: process.stderr
 }) {
     const cwd = io.cwd ?? (() => process.cwd());
+    warnIfCwdRootFallback(flags, cwd, { stderr: io.stderr, stdout: io.stdout, cwd });
     const root = resolveRoot(flags, cwd);
     const autoOpen = resolveAutoOpen(flags, cwd);
     // DEC-107/108 (EVO-8 levels 2/3): version handling at boot. **Opt-in** — no
@@ -2914,9 +2997,11 @@ function cmdDoctor(flags, streams) {
     const report = {
         ok: true,
         root,
+        warnings: [],
         checks: {}
     };
     const checks = report.checks;
+    const warnings = report.warnings;
     // 1. Root reachable
     if (!existsSync(root)) {
         checks.rootExists = { ok: false, message: `root does not exist: ${root}` };
@@ -2969,6 +3054,247 @@ function cmdDoctor(flags, streams) {
     }
     // 4. h2a binary reachable (self-check via existing API)
     checks.cliBinary = { ok: true };
+    // ── Warning checks (do NOT flip report.ok) ──────────────────────────────
+    // (a) rootSource: record where the root came from
+    const rootInfo = resolveRootInfo(flags, cwd);
+    report.rootSource = rootInfo.source;
+    if (rootInfo.source === "default") {
+        warnings.push({
+            check: "rootSource",
+            message: `The bus root is the global shared default (${root}). ` +
+                `Set H2A_ROOT or pass --root <path> to use a different bus. ` +
+                `Agents on different roots cannot exchange messages.`
+        });
+    }
+    // (b) splitBrain: a repo-local .h2a exists alongside a DIFFERENT active root
+    const cwdLocal = join(cwd(), ".h2a");
+    try {
+        if (existsSync(cwdLocal)) {
+            const resolvedLocal = realpathSync(cwdLocal);
+            const resolvedRoot = (() => {
+                try {
+                    return realpathSync(root);
+                }
+                catch {
+                    return root;
+                }
+            })();
+            if (resolvedLocal !== resolvedRoot) {
+                warnings.push({
+                    check: "splitBrain",
+                    message: `A repo-local .h2a (${cwdLocal}) exists alongside a DIFFERENT active root (${root}). ` +
+                        `Messages written to the repo-local bus are invisible to peers on ${root} — split-brain.`
+                });
+            }
+        }
+    }
+    catch {
+        // silently ignore (the cwd-local path may not be resolvable)
+    }
+    // (c) inboxHygiene: scan inbox for case/slug duplicates, host-less dirs, phantom 3-segment dirs
+    const inboxDir = join(root, "inbox");
+    // Collect dirs to prune (with --prune only).
+    const pruned = [];
+    if (existsSync(inboxDir)) {
+        let inboxEntries = [];
+        try {
+            inboxEntries = readdirSync(inboxDir);
+        }
+        catch {
+            // not readable — skip hygiene check
+        }
+        if (inboxEntries.length > 0) {
+            const KNOWN_HOSTS = new Set(["claude", "codex", "gemini", "remote"]);
+            // Reconstruct an address from a dir name: double-underscore → colon.
+            function dirToAddress(name) {
+                return name.replace(/__/g, ":");
+            }
+            // Case/slug duplicates: two dir names that map to the same canonicalAddress
+            const byCanonical = new Map();
+            for (const entry of inboxEntries) {
+                const addr = dirToAddress(entry);
+                let canonical;
+                try {
+                    canonical = canonicalAddress(addr);
+                }
+                catch {
+                    canonical = addr.toLowerCase();
+                }
+                const group = byCanonical.get(canonical) ?? [];
+                group.push(entry);
+                byCanonical.set(canonical, group);
+            }
+            const dupGroups = [...byCanonical.values()].filter((g) => g.length > 1);
+            if (dupGroups.length > 0) {
+                const examples = dupGroups.slice(0, 5).map((g) => g.join(" | "));
+                warnings.push({
+                    check: "inboxHygiene",
+                    kind: "caseDuplicates",
+                    count: dupGroups.length,
+                    examples,
+                    message: `${dupGroups.length} case/slug duplicate group(s) in inbox — ` +
+                        `different dir names map to the same canonical address. ` +
+                        `Examples: ${examples.join(", ")}. (Not pruned — too risky; resolve manually.)`
+                });
+            }
+            // Host-less dirs: first segment (before first __) is not a known host
+            const hostless = inboxEntries.filter((entry) => {
+                const firstSeg = entry.split("__")[0];
+                return !KNOWN_HOSTS.has(firstSeg);
+            });
+            if (hostless.length > 0) {
+                const examples = hostless.slice(0, 5);
+                warnings.push({
+                    check: "inboxHygiene",
+                    kind: "hostlessDirs",
+                    count: hostless.length,
+                    examples,
+                    message: `${hostless.length} host-less inbox dir(s) (first segment is not claude/codex/gemini/remote). ` +
+                        `Examples: ${examples.join(", ")}`
+                });
+                if (flags.prune !== undefined) {
+                    for (const name of hostless) {
+                        const dir = join(inboxDir, name);
+                        try {
+                            rmSync(dir, { recursive: true, force: true });
+                            pruned.push({ name, path: dir });
+                        }
+                        catch (error) {
+                            streams.stderr.write(`h2a doctor --prune: cannot remove ${dir}: ${error.message}\n`);
+                        }
+                    }
+                }
+            }
+            // Phantom 3-segment dirs: exactly 3 __ segments but 3rd is not a 12-char hex session id
+            const VALID_TAIL_RE = /^[0-9a-f]{12}$/i;
+            const phantom = inboxEntries.filter((entry) => {
+                const segs = entry.split("__");
+                if (segs.length !== 3)
+                    return false;
+                return !VALID_TAIL_RE.test(segs[2]);
+            });
+            if (phantom.length > 0) {
+                const examples = phantom.slice(0, 5);
+                warnings.push({
+                    check: "inboxHygiene",
+                    kind: "phantomThreeSegment",
+                    count: phantom.length,
+                    examples,
+                    message: `${phantom.length} phantom 3-segment inbox dir(s) where the tail is not a 12-char hex session id. ` +
+                        `Examples: ${examples.join(", ")}`
+                });
+                if (flags.prune !== undefined) {
+                    for (const name of phantom) {
+                        const dir = join(inboxDir, name);
+                        try {
+                            rmSync(dir, { recursive: true, force: true });
+                            pruned.push({ name, path: dir });
+                        }
+                        catch (error) {
+                            streams.stderr.write(`h2a doctor --prune: cannot remove ${dir}: ${error.message}\n`);
+                        }
+                    }
+                }
+            }
+            // Orphan 3-segment dirs: 3 segments, valid hex tail, but UUID is NOT in registry/instances.jsonl
+            if (flags.prune !== undefined) {
+                const instancesFile = join(root, "registry", "instances.jsonl");
+                let registeredUuids = new Set();
+                try {
+                    const content = readFileSync(instancesFile, "utf8");
+                    for (const line of content.split("\n")) {
+                        const trimmed = line.trim();
+                        if (!trimmed)
+                            continue;
+                        try {
+                            const obj = JSON.parse(trimmed);
+                            const id = typeof obj.instance === "string" ? obj.instance : (typeof obj.id === "string" ? obj.id : "");
+                            // Extract the hex tail segment from the instance id (e.g. host:label:abc123456789)
+                            const parts = id.split(":");
+                            if (parts.length >= 3) {
+                                const tail = parts[parts.length - 1];
+                                if (VALID_TAIL_RE.test(tail))
+                                    registeredUuids.add(tail.toLowerCase());
+                            }
+                        }
+                        catch {
+                            // skip malformed
+                        }
+                    }
+                }
+                catch {
+                    // instances file absent — keep set empty (prune all orphans below)
+                }
+                const orphan3seg = inboxEntries.filter((entry) => {
+                    const segs = entry.split("__");
+                    if (segs.length !== 3)
+                        return false;
+                    if (!VALID_TAIL_RE.test(segs[2]))
+                        return false; // already handled as phantom
+                    return !registeredUuids.has(segs[2].toLowerCase());
+                });
+                for (const name of orphan3seg) {
+                    const dir = join(inboxDir, name);
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                        pruned.push({ name, path: dir });
+                    }
+                    catch (error) {
+                        streams.stderr.write(`h2a doctor --prune: cannot remove ${dir}: ${error.message}\n`);
+                    }
+                }
+            }
+        }
+    }
+    // (d) --scan <dir>: find immediate child buses (ONE level deep)
+    const strayBuses = [];
+    if (flags.scan) {
+        try {
+            const scanChildren = readdirSync(flags.scan);
+            for (const child of scanChildren) {
+                const candidateBus = join(flags.scan, child, ".h2a");
+                if (existsSync(candidateBus)) {
+                    const instancesFile = join(candidateBus, "registry", "instances.jsonl");
+                    let instances = 0;
+                    try {
+                        const content = readFileSync(instancesFile, "utf8");
+                        instances = content.split("\n").filter((l) => l.trim().length > 0).length;
+                    }
+                    catch {
+                        instances = 0;
+                    }
+                    strayBuses.push({ path: candidateBus, instances });
+                }
+            }
+        }
+        catch (error) {
+            streams.stderr.write(`h2a doctor: --scan ${flags.scan}: ${error.message}\n`);
+        }
+        if (strayBuses.length > 0) {
+            warnings.push({
+                check: "strayBuses",
+                count: strayBuses.length,
+                buses: strayBuses,
+                message: `${strayBuses.length} stray repo-local .h2a bus(es) found under ${flags.scan} — ` +
+                    `candidate split-brain forks. Each may have agents on a different root.`
+            });
+            if (flags.prune !== undefined) {
+                for (const bus of strayBuses) {
+                    const busPath = bus.path;
+                    try {
+                        rmSync(busPath, { recursive: true, force: true });
+                        pruned.push({ name: busPath, path: busPath });
+                    }
+                    catch (error) {
+                        streams.stderr.write(`h2a doctor --prune: cannot remove ${busPath}: ${error.message}\n`);
+                    }
+                }
+            }
+        }
+    }
+    if (flags.prune !== undefined) {
+        report.pruned = pruned;
+    }
     streams.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
     return report.ok ? 0 : 2;
 }
@@ -3089,6 +3415,7 @@ function cmdConnect(flags, streams) {
         return 1;
     }
     const cwd = streams.cwd ?? (() => process.cwd());
+    warnIfCwdRootFallback(flags, cwd, streams);
     const root = resolveRoot(flags, cwd);
     const identity = resolveLiveIdentity({
         root,
@@ -3497,6 +3824,93 @@ function cmdDeployTenant(flags, streams) {
     }, null, 2)}\n`);
     return 0;
 }
+// ── WP-5: keepalive ────────────────────────────────────────────────────────
+/**
+ * Single-pass keepalive logic, testable without real tmux.
+ *
+ * For each presence file under `root`, if the session has a
+ * `launchContext.tmux.pane` that is in `livePanes`, rewrite its `heartbeatAt`
+ * to `now` so the session does not expire.
+ */
+export function keepaliveOnce(opts) {
+    const { root, livePanes } = opts;
+    const nowIso = (opts.now ?? new Date()).toISOString();
+    const refreshed = [];
+    // includeExpired=true so we can refresh sessions that are about to expire
+    const sessions = listPresence(root, { includeExpired: true });
+    for (const session of sessions) {
+        const pane = session.launchContext?.tmux?.pane;
+        if (!pane)
+            continue;
+        if (!livePanes.has(pane))
+            continue;
+        // Rewrite heartbeatAt to now
+        const updated = { ...session, heartbeatAt: nowIso };
+        try {
+            writePresence(root, updated);
+            refreshed.push({ instance: session.instance, sessionId: session.sessionId, pane });
+        }
+        catch {
+            // best-effort — ignore write failures
+        }
+    }
+    return refreshed;
+}
+/**
+ * `h2a keepalive [--root <path>] [--interval <ms>] [--once]`
+ *
+ * External keepalive prober: runs by the launcher/remote so a host-suspended
+ * `mcp-serve` still shows live as long as its tmux pane is alive. `--once`
+ * does a single pass then exits 0. Without `--once`, loops on an unref'd
+ * interval (default 30 000 ms).
+ */
+export async function cmdKeepalive(flags, streams) {
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    const intervalMs = flags.interval ? Number.parseInt(flags.interval, 10) : 30_000;
+    if (!Number.isInteger(intervalMs) || intervalMs < 1000) {
+        streams.stderr.write(`h2a keepalive: --interval must be >= 1000 ms (got "${flags.interval}")\n`);
+        return 1;
+    }
+    function getLivePanes() {
+        try {
+            const out = execFileSync("tmux", ["list-panes", "-aF", "#{pane_id}"], {
+                encoding: "utf8",
+                timeout: 5000
+            });
+            const panes = new Set(out
+                .split("\n")
+                .map((l) => l.trim())
+                .filter((l) => l.length > 0));
+            return panes;
+        }
+        catch {
+            streams.stderr.write("h2a keepalive: tmux not available or returned an error — treating live-pane set as empty.\n");
+            return new Set();
+        }
+    }
+    function runOnce() {
+        const livePanes = getLivePanes();
+        const refreshed = keepaliveOnce({ root, livePanes });
+        for (const item of refreshed) {
+            streams.stdout.write(`h2a keepalive: refreshed ${item.instance} (session ${item.sessionId}, pane ${item.pane})\n`);
+        }
+    }
+    runOnce();
+    if (flags.once !== undefined) {
+        return 0;
+    }
+    // Long-running loop — unref the interval so it does not keep the process alive.
+    return new Promise((resolve) => {
+        const timer = setInterval(() => {
+            runOnce();
+        }, intervalMs);
+        timer.unref();
+        // The process will exit naturally when there is nothing else keeping it alive.
+        // For tests that want to abort, they should pass --once.
+        void resolve; // keep linter happy
+    });
+}
 export function runCli(argv = process.argv.slice(2), streams = {
     stdout: process.stdout,
     stderr: process.stderr
@@ -3581,6 +3995,10 @@ export function runCli(argv = process.argv.slice(2), streams = {
         return cmdDoctor(flags, streams);
     if (command === "connect")
         return cmdConnect(flags, streams);
+    if (command === "keepalive") {
+        streams.stderr.write("h2a keepalive: async command — run via the h2a binary, not the synchronous API.\n");
+        return 1;
+    }
     if (command === "install-skills")
         return cmdInstallSkills(flags, streams);
     if (command === "deploy")