@sentropic/h2a-cli 0.60.0 → 0.62.0

package/dist/cli.js

@@ -36,20 +36,20 @@
  * 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, readdirSync, realpathSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
-import { H2A_ATTESTER_COMPREHENSION_RIGHT, H2A_COMPREHENSION_ATTESTATION_BODY_KIND, H2A_DECLARATION_INTERET_BODY_KIND, H2A_ORG_MANIFEST_FILENAME, H2A_ORG_PROPOSAL_BODY_KIND, H2A_ORG_RATIFIED_BODY_KIND, H2A_ROLES, H2A_WORK_STATUSES, auditNhiPosture, buildComprehensionAttestation, canAttestComprehension, checkEnvelopeFreshness, computeHash, createEnvelope, diffOrgManifest, effectiveOrgInstances, isComprehensionAttestation, nhiAttestationEnvelope, nhiInventory, nhiTrustBundle, orgAssignmentEnvelope, parseOrgManifest, signCanonical, signEnvelope, subagentAddress, validateOrgManifest, verifyComprehensionAttestation } from "@sentropic/h2a";
+import { H2A_ATTESTER_COMPREHENSION_RIGHT, H2A_COMPREHENSION_ATTESTATION_BODY_KIND, H2A_DECLARATION_INTERET_BODY_KIND, H2A_ORG_MANIFEST_FILENAME, H2A_ORG_PROPOSAL_BODY_KIND, H2A_ORG_RATIFIED_BODY_KIND, H2A_ROLES, H2A_WORK_STATUSES, auditNhiPosture, buildComprehensionAttestation, canAttestComprehension, checkEnvelopeFreshness, computeHash, createEnvelope, deriveWorkspaceId, diffOrgManifest, effectiveOrgInstances, isComprehensionAttestation, nhiAttestationEnvelope, nhiInventory, nhiTrustBundle, orgAssignmentEnvelope, parseOrgManifest, signCanonical, signEnvelope, subagentAddress, validateOrgManifest, verifyComprehensionAttestation } from "@sentropic/h2a";
 import { H2A_CLAUDE_HOST } from "./hosts/claude.js";
 import { H2A_CODEX_HOST } from "./hosts/codex.js";
 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, resolveRecipient, 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";
@@ -63,6 +63,7 @@ import { authorizeDrive, chainDriver, formatSignedDriveInstruction, headlessDriv
 import { verifyEnvelopeSysmlRef } from "./runtime/sysml/index.js";
 import { checkUpgrade, performUpgrade, currentCliVersion, upgradeCachePath, canReexec, reexecSelf, H2A_AUTO_UPGRADE_CHECK_TTL_MS, H2A_REEXEC_GUARD_ENV, H2A_UPGRADE_CHECK_TTL_MS } from "./runtime/upgrade/index.js";
 import { resolveLiveIdentity } from "./runtime/identity/index.js";
+import { conductorFor } from "./runtime/governance/conductor.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 // `dist/cli.js` lives in `packages/h2a-cli/dist/`; skills are at
 // `packages/h2a-cli/skills/`. Two levels up from the dist file.
@@ -172,7 +173,10 @@ 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>] [--scan <dir>]",
+        "  h2a conductor [--workspace <id|path>] [--root <path>]   (who is the live conductor/owner of a workspace — derived from presence; conductor=role CONDUCTOR if set, else null; candidates=in-workspace live agents)",
+        "  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)",
@@ -219,12 +223,12 @@ function parseFlags(argv) {
 /**
  * Resolve the h2a store root, with its provenance.
  *
- * Precedence: explicit `--root` flag → `H2A_ROOT` env → the `cwd/.h2a` fallback.
- * Honoring `H2A_ROOT` here brings the stdio CLI (incl. `mcp-serve`) to parity
- * with the HTTP/k8s servers, which already read it (mcp-http/serve.ts). The
- * `cwd` fallback silently forks an agent onto a repo-local bus that no peer on
- * the shared root can see — the split-brain root failure (F4). Callers on
- * long-lived paths (`mcp-serve`, `connect`) warn when `source === "cwd"`.
+ * 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)
@@ -232,24 +236,43 @@ function resolveRootInfo(flags, cwd) {
     const env = process.env.H2A_ROOT;
     if (env && env.length > 0)
         return { root: env, source: "env" };
-    return { root: join(cwd(), ".h2a"), source: "cwd" };
+    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 `cwd` fallback rather
- * than an explicit `--root`/`H2A_ROOT`. Used by the long-lived `mcp-serve` /
- * `connect` paths that establish an agent's bus — a silent cwd fork there is the
- * split-brain root bug. One-shot verbs stay quiet.
+ * 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 !== "cwd")
+    if (info.source !== "default")
         return;
-    streams.stderr.write(`h2a: no --root/H2A_ROOT set — using this repo's local bus ${info.root}. ` +
-        `Agents on different roots cannot see each other; if you meant the shared bus, ` +
-        `set H2A_ROOT (e.g. ~/h2a-workspace/.h2a) or pass --root. Run \`h2a doctor\` to check.\n`);
+    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.
@@ -2970,6 +2993,70 @@ function cmdStatus(flags, streams) {
         return 3;
     }
 }
+/**
+ * Read the stable machine-id for workspace derivation (mirrors live.ts).
+ * Used only by `cmdConductor` when the caller passes a filesystem path.
+ */
+function cliReadMachineId() {
+    for (const p of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+        try {
+            const id = readFileSync(p, "utf8").trim();
+            if (id.length > 0)
+                return id;
+        }
+        catch {
+            // try next source
+        }
+    }
+    return hostname() || "unknown-machine";
+}
+/**
+ * `h2a conductor [--workspace <id|path>] [--root <path>]`
+ *
+ * Resolve the live conductor/owner of a workspace (WP-G1, read-only).
+ * --workspace accepts a workspace id (`ws:…`) OR a filesystem path; a path
+ * is resolved to a workspaceId via the same derivation presence uses. If
+ * omitted, defaults to cwd.
+ *
+ * Output shape: resource (JSON of ConductorResolution). Exit 0 always.
+ */
+function cmdConductor(flags, streams) {
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    let workspaceId;
+    const wsFlag = flags.workspace;
+    if (!wsFlag) {
+        // Default to cwd
+        const cwdPath = cwd();
+        let realPath = cwdPath;
+        try {
+            realPath = realpathSync(cwdPath);
+        }
+        catch { /* use cwd as-is */ }
+        workspaceId = deriveWorkspaceId({ machineId: cliReadMachineId(), path: realPath });
+    }
+    else if (wsFlag.startsWith("ws:")) {
+        workspaceId = wsFlag;
+    }
+    else {
+        // Treat as a filesystem path
+        let realPath = wsFlag;
+        try {
+            realPath = realpathSync(wsFlag);
+        }
+        catch { /* use as-is */ }
+        workspaceId = deriveWorkspaceId({ machineId: cliReadMachineId(), path: realPath });
+    }
+    try {
+        const result = conductorFor({ root, workspaceId });
+        streams.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        streams.stderr.write(`h2a conductor: ${error.message}\n`);
+        return 1;
+    }
+}
 function cmdDoctor(flags, streams) {
     const cwd = streams.cwd ?? (() => process.cwd());
     const root = resolveRoot(flags, cwd);
@@ -3037,11 +3124,11 @@ function cmdDoctor(flags, streams) {
     // (a) rootSource: record where the root came from
     const rootInfo = resolveRootInfo(flags, cwd);
     report.rootSource = rootInfo.source;
-    if (rootInfo.source === "cwd") {
+    if (rootInfo.source === "default") {
         warnings.push({
             check: "rootSource",
-            message: `The bus root is the repo-local cwd fallback (${root}). ` +
-                `Set H2A_ROOT or pass --root <shared-bus-path> so all agents see each other. ` +
+            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.`
         });
     }
@@ -3072,6 +3159,8 @@ function cmdDoctor(flags, streams) {
     }
     // (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 {
@@ -3111,7 +3200,7 @@ function cmdDoctor(flags, streams) {
                     examples,
                     message: `${dupGroups.length} case/slug duplicate group(s) in inbox — ` +
                         `different dir names map to the same canonical address. ` +
-                        `Examples: ${examples.join(", ")}`
+                        `Examples: ${examples.join(", ")}. (Not pruned — too risky; resolve manually.)`
                 });
             }
             // Host-less dirs: first segment (before first __) is not a known host
@@ -3129,6 +3218,18 @@ function cmdDoctor(flags, streams) {
                     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;
@@ -3148,12 +3249,72 @@ function cmdDoctor(flags, streams) {
                     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) {
-        const strayBuses = [];
         try {
             const scanChildren = readdirSync(flags.scan);
             for (const child of scanChildren) {
@@ -3183,8 +3344,23 @@ function cmdDoctor(flags, streams) {
                 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;
 }
@@ -3714,6 +3890,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
@@ -3798,6 +4061,12 @@ export function runCli(argv = process.argv.slice(2), streams = {
         return cmdDoctor(flags, streams);
     if (command === "connect")
         return cmdConnect(flags, streams);
+    if (command === "conductor")
+        return cmdConductor(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")