@sentropic/h2a 0.85.16 → 0.85.18

package/dist/cli.js

@@ -40,7 +40,7 @@ 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, hostname } from "node:os";
-import { dirname, join, resolve as resolvePath } from "node:path";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // Static import — `@sentropic/track` is a LIGHT library (pure reader/model, no
@@ -68,7 +68,7 @@ import { H2A_OPENCODE_HOST } from "./hosts/opencode.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, reapAllDeadPresence, reapDeadInstancePresence, readPresence, resolveRecipient, safePathSegment, sanitizeStorePaths, writePresence } from "./runtime/local-files/index.js";
-import { runMcpStdio } from "./runtime/mcp/index.js";
+import { H2A_MCP_READY_FILE_ENV, H2A_MCP_READY_NONCE_ENV, runMcpStdio } from "./runtime/mcp/index.js";
 import { renderK8sSidecar } from "./runtime/deploy/k8s-sidecar.js";
 import { renderK8sTenant } from "./runtime/deploy/k8s-tenant.js";
 import { remoteServerForStore, sendRemoteEnvelope } from "./runtime/remote/index.js";
@@ -85,10 +85,11 @@ import { conductorFor } from "./runtime/governance/conductor.js";
 import { appendConductorClaim } from "./runtime/governance/claims.js";
 import { conductorLaunchCheck } from "./runtime/governance/launch-check.js";
 import { lastSpawnRequestAt, recordSpawnRequest, spawnAllowed } from "./runtime/governance/spawns.js";
-import { createObjectiveLoop, declareObjectiveLoopDone, joinObjectiveLoop, listLoopEvents, listObjectiveLoops, readObjectiveLoop, reportObjectiveLoop, stopObjectiveLoop } from "./runtime/loop/index.js";
+import { createObjectiveLoop, declareObjectiveLoopDone, joinObjectiveLoop, listLoopEvents, listObjectiveLoops, readObjectiveLoop, reportObjectiveLoop, stopObjectiveLoop, validateLoopLaunchSpec } from "./runtime/loop/index.js";
 import { runLoopWatch, runTick } from "./runtime/loop/engine/tick.js";
 import { gatherPendingDecisions } from "./runtime/canevas/gather.js";
 import { runCanevasServe } from "./runtime/canevas/serve.js";
+import { installTrackReportAiConfig, readH2AReportContext, TrackReportAiConfigConflictError } from "./runtime/reporting/index.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.
@@ -225,9 +226,9 @@ export function renderCliHelp() {
         "  h2a install-skills --host <claude|codex|gemini|agy> [--scope user|project] [--force]",
         "  h2a deploy k8s-sidecar [--instance <id>] [--host <h>] [--root <path>] [--image <ref>] [--cli-version <ver>] [--write <file>]",
         "  h2a deploy k8s-tenant [--namespace <ns>] [--root <path>] [--replicas <n>] [--storage <size>] [--storage-class <sc>] [--lease-ms <ms>] [--image <ref>] [--cli-version <ver>] [--write <file>]",
-        "  h2a loop create --name <n> --goal <text> [--repo <path[:role]>] [--track <json>] [--agent <host:role:placement>] [--root <path>]",
-        "  h2a loop join <loopId> --instance <id> [--agent-id <id>] [--role <role>] [--root <path>]",
-        "  h2a loop report <loopId> --note <text> [--instance <id>] [--agent-id <id>] [--root <path>]",
+        "  h2a loop create --name <n> --goal <text> [--repo <path[:role]>] [--track <json>] [--agent <host:role:placement> [--launch-stdin]] [--root <path>]",
+        "  h2a loop join <loopId> --instance <id> [--agent-id <id>] [--role <role>] [--launch-stdin] [--root <path>]",
+        "  h2a loop report <loopId> --note <text> [--instance <id>] [--agent-id <id>] [--auto-join] [--root <path>]",
         "  h2a loop done <loopId> [--note <text>] [--instance <id>] [--agent-id <id>] [--root <path>]",
         "  h2a loop stop <loopId> [--reason <text>] [--root <path>]",
         "  h2a loop list [--root <path>]",
@@ -236,9 +237,19 @@ export function renderCliHelp() {
         "  h2a loop attach <loopId> --agent <selector> [--root <path>]",
         "  h2a loop logs <loopId> [--agent <selector>] [--root <path>]",
         "",
+        "Track AI adapters (leaf commands; never call Track report/snapshot):",
+        "  h2a report-context --workspace-root <absolute-path> [--root <h2a-store>]",
+        "  h2a report-ai --model <model> --effort <low|medium|high|xhigh> --gateway required   (Track context envelope on stdin; one no-tools local-gateway request)",
+        "  h2a report-ai install-track-config [--force]   (atomic user XDG config, mode 0600; preserves overrides by default)",
+        "",
+        "Focus Web (packaged production app):",
+        "  h2a focus serve [--repo <path>] [--track-events <path>] [--host <host>] [--port <0-65535>]",
+        "  h2a focus web   [--repo <path>] [--track-events <path>] [--host <host>] [--port <0-65535>]   (exact alias)",
+        "    (defaults to the nearest tracked repo and 127.0.0.1:5178; bare `h2a focus …` remains the Track facade)",
+        "",
         "Track (délégué à @sentropic/track — le suivi/record du travail):",
         `  h2a ${[...TRACK_FACADE_VERBS].join(" · h2a ")}`,
-        "    (ex: h2a decision new …, h2a report, h2a item ls — voir `track <verbe> --help`)",
+        "    (ex: h2a decision new …, h2a report, h2a snapshot, h2a item ls — voir `track <verbe> --help`)",
         "",
         "Harness (délégué à h2a vendored harness — la méthode code-work / PR-workflow):",
         "  h2a harness <check|verify|init|audit|brainstorm|test|debug|review|plan|branch|skills> …",
@@ -1254,6 +1265,21 @@ export async function runMcpServe(flags, io = {
     warnIfCwdRootFallback(flags, cwd, { stderr: io.stderr, stdout: io.stdout, cwd });
     const root = resolveRoot(flags, cwd);
     const autoOpen = resolveAutoOpen(flags, cwd);
+    const readinessEnv = io.env ?? process.env;
+    const readyFile = readinessEnv[H2A_MCP_READY_FILE_ENV];
+    const readyNonce = readinessEnv[H2A_MCP_READY_NONCE_ENV];
+    let readiness;
+    if (readyFile !== undefined || readyNonce !== undefined) {
+        if (!readyFile ||
+            !isAbsolute(readyFile) ||
+            readyFile.includes("\0") ||
+            !readyNonce ||
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(readyNonce)) {
+            io.stderr.write("h2a mcp-serve: invalid internal readiness challenge\n");
+            return 1;
+        }
+        readiness = { file: readyFile, nonce: readyNonce };
+    }
     // DEC-107/108 (EVO-8 levels 2/3): version handling at boot. **Opt-in** — no
     // network on a default boot. `--auto-upgrade` self-installs @latest then
     // re-execs in place via process.execve (same PID/stdio, host stays connected;
@@ -1270,10 +1296,14 @@ export async function runMcpServe(flags, io = {
             // same-day release isn't masked by the 24h notice cache; the passive
             // `--upgrade-check` notice keeps the 24h throttle.
             const ttlMs = wantAutoUpgrade ? H2A_AUTO_UPGRADE_CHECK_TTL_MS : H2A_UPGRADE_CHECK_TTL_MS;
-            const result = checkUpgrade(current, { cachePath: upgradeCachePath(root), ttlMs });
+            const result = checkUpgrade(current, {
+                cachePath: upgradeCachePath(root),
+                ttlMs,
+                ...(io.upgradeRuntime ? { runtime: io.upgradeRuntime } : {})
+            });
             if (result.upgradeAvailable) {
                 if (wantAutoUpgrade) {
-                    const ok = performUpgrade();
+                    const ok = performUpgrade(io.upgradeRuntime);
                     if (ok && flags["no-restart"] === undefined && canReexec()) {
                         io.stderr.write(`h2a mcp-serve: auto-upgraded ${current} → ${result.latest}; restarting into the new version…\n`);
                         reexecSelf(); // on success the image is replaced (never returns)
@@ -1326,10 +1356,12 @@ export async function runMcpServe(flags, io = {
         }
         await runMcpStdio({
             root,
+            workspaceRoot: process.cwd(),
             stdin: io.stdin,
             stdout: io.stdout,
             stderr: io.stderr,
             ...(autoOpen ? { autoOpen } : {}),
+            ...(readiness ? { readiness } : {}),
             ...(wake ? { wake } : {}),
             ...(io.signal ? { signal: io.signal } : {})
         });
@@ -1640,6 +1672,16 @@ function collectRepeatedFlag(argv, flag) {
     }
     return out;
 }
+function parseLoopLaunch(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("--launch-stdin must contain valid JSON");
+    }
+    return validateLoopLaunchSpec(value);
+}
 function selectLoopAgent(loop, selector) {
     if (!selector)
         return undefined;
@@ -1653,7 +1695,17 @@ function cmdLoop(argv, streams) {
         if (sub === "create") {
             const repos = collectRepeatedFlag(argv, "--repo").map(parseLoopRepo);
             const refs = collectRepeatedFlag(argv, "--track").map(parseLoopTrack);
-            const agents = collectRepeatedFlag(argv, "--agent").map(parseLoopAgent);
+            let agents = collectRepeatedFlag(argv, "--agent").map(parseLoopAgent);
+            if (flags.launch)
+                throw new Error("--launch is unsafe because prompts must not be passed in argv; use --launch-stdin");
+            if (flags["launch-stdin"] === "true") {
+                if (agents.length !== 1)
+                    throw new Error("--launch-stdin requires exactly one --agent on loop create");
+                const launch = parseLoopLaunch(stdinText(streams) ?? "");
+                if (agents[0].host !== launch.profile)
+                    throw new Error("--agent host must match --launch-stdin profile");
+                agents = [{ ...agents[0], launch }];
+            }
             const loop = createObjectiveLoop(root, {
                 ...(flags.id ? { id: flags.id } : {}),
                 name: flags.name,
@@ -1675,11 +1727,15 @@ function cmdLoop(argv, streams) {
                 streams.stderr.write("h2a loop join: <loopId> and --instance <id> are required\n");
                 return 1;
             }
+            if (flags.launch)
+                throw new Error("--launch is unsafe because prompts must not be passed in argv; use --launch-stdin");
+            const launch = flags["launch-stdin"] === "true" ? parseLoopLaunch(stdinText(streams) ?? "") : undefined;
             const loop = joinObjectiveLoop(root, loopId, {
                 instance: flags.instance,
                 ...(flags["agent-id"] ? { agentId: flags["agent-id"] } : {}),
                 ...(flags.role ? { role: flags.role } : {}),
-                ...(flags.required ? { required: flags.required !== "false" } : {})
+                ...(flags.required ? { required: flags.required !== "false" } : {}),
+                ...(launch !== undefined ? { launch } : {})
             });
             streams.stdout.write(`${JSON.stringify(loop, null, 2)}\n`);
             return 0;
@@ -1693,6 +1749,7 @@ function cmdLoop(argv, streams) {
             const loop = reportObjectiveLoop(root, loopId, {
                 ...(flags.instance ? { instance: flags.instance } : {}),
                 ...(flags["agent-id"] ? { agentId: flags["agent-id"] } : {}),
+                ...(flags["auto-join"] === "true" ? { autoJoin: true } : {}),
                 note: flags.note
             });
             streams.stdout.write(`${JSON.stringify(loop, null, 2)}\n`);
@@ -4073,7 +4130,12 @@ function cmdDoctor(flags, streams) {
             }
         }
     }
-    // (d) --scan <dir>: find immediate child buses (ONE level deep)
+    // (d) --scan <dir>: find immediate child buses (ONE level deep).
+    // Safety model: a stray bus is ORPHAN only if it has zero live (fresh
+    // heartbeat) presence — checked via the same listPresence() used for the
+    // liveSessions hard check above. A bus with ANY live presence is reported
+    // but NEVER pruned, --prune or not. This is a dry-run-by-default sweep:
+    // the report always lists what --prune WOULD remove; only --prune deletes.
     const strayBuses = [];
     if (flags.scan) {
         try {
@@ -4090,7 +4152,17 @@ function cmdDoctor(flags, streams) {
                     catch {
                         instances = 0;
                     }
-                    strayBuses.push({ path: candidateBus, instances });
+                    // Liveness gate: any fresh presence heartbeat in this bus makes it
+                    // ACTIVE, not orphan — never a deletion candidate.
+                    let live = false;
+                    try {
+                        live = listPresence(candidateBus).length > 0;
+                    }
+                    catch {
+                        // Unreadable presence dir — treat conservatively as NOT orphan.
+                        live = true;
+                    }
+                    strayBuses.push({ path: candidateBus, instances, live, orphan: !live });
                 }
             }
         }
@@ -4098,15 +4170,21 @@ function cmdDoctor(flags, streams) {
             streams.stderr.write(`h2a doctor: --scan ${flags.scan}: ${error.message}\n`);
         }
         if (strayBuses.length > 0) {
+            const orphanBuses = strayBuses.filter((b) => b.orphan === true);
+            const liveBuses = strayBuses.filter((b) => b.orphan !== true);
             warnings.push({
                 check: "strayBuses",
                 count: strayBuses.length,
+                orphanCount: orphanBuses.length,
+                liveCount: liveBuses.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.`
+                    `candidate split-brain forks. ${orphanBuses.length} orphan (no live presence — ` +
+                    `${flags.prune !== undefined ? "removed by" : "would be removed by"} --prune), ` +
+                    `${liveBuses.length} live (has active presence — never pruned).`
             });
             if (flags.prune !== undefined) {
-                for (const bus of strayBuses) {
+                for (const bus of orphanBuses) {
                     const busPath = bus.path;
                     try {
                         rmSync(busPath, { recursive: true, force: true });
@@ -4116,6 +4194,10 @@ function cmdDoctor(flags, streams) {
                         streams.stderr.write(`h2a doctor --prune: cannot remove ${busPath}: ${error.message}\n`);
                     }
                 }
+                if (liveBuses.length > 0) {
+                    streams.stderr.write(`h2a doctor --prune: skipped ${liveBuses.length} stray bus(es) with live presence (never pruned): ` +
+                        `${liveBuses.map((b) => b.path).join(", ")}\n`);
+                }
             }
         }
     }
@@ -4883,7 +4965,7 @@ export async function cmdKeepalive(flags, streams) {
 // Verbes spécifiques, sans namespace `track` (dissous comme host/sub).
 export const TRACK_FACADE_VERBS = new Set([
     "decision", "report", "accept", "blocker", "item", "query",
-    "consolidate", "priority", "branch", "focus", "ingest", "restructure"
+    "consolidate", "priority", "branch", "focus", "ingest", "restructure", "snapshot"
 ]);
 // ④ de-spawn — a strict SUBSET of the facade verbs routed IN-PROCESS via
 // `@sentropic/track`'s `runCli`, no child process. Every native verb is proven
@@ -4896,14 +4978,14 @@ export const TRACK_FACADE_VERBS = new Set([
 //
 // The native set is split READ-ONLY vs WRITE because the throw-fallback rule
 // differs (RISK: double-write, see `delegateToTrackNative`):
-//   • READ-ONLY (`query`/`report`) — a native throw wrote nothing, so falling
+//   • READ-ONLY (`query`/`report`/`snapshot`) — a native throw wrote nothing, so falling
 //     back to the spawn facade is safe.
 //   • WRITE (the rest) — track's `appendCommand` is ATOMIC under the O_EXCL lock
 //     (read→validate→append→writeHead→verify): it throws either BEFORE the
 //     append (validation → nothing written) or AFTER a landed write (the
 //     verify receipt). A spawn fallback on that throw could DOUBLE-WRITE, so a
 //     write NEVER falls back on throw — it propagates the error (rc≠0 + stderr).
-export const TRACK_NATIVE_READONLY_VERBS = new Set(["query", "report"]);
+export const TRACK_NATIVE_READONLY_VERBS = new Set(["query", "report", "snapshot"]);
 // ④ tranche-2 — the SYNC write verbs, de-spawned in-process. Each dispatches
 // through runCli's mutating switch as a plain sync `cmd…` returning a `number`.
 // `focus` is absent (async); `restructure`/`ingest` are sync file-plan applies.
@@ -4947,6 +5029,44 @@ export async function runTrackMcpServe(flags, io = {
         return 1;
     }
 }
+function cmdReportContext(flags, streams) {
+    const workspaceRoot = flags["workspace-root"];
+    if (!workspaceRoot || workspaceRoot === "true") {
+        streams.stderr.write("h2a report-context: --workspace-root <absolute-path> is required\n");
+        return 1;
+    }
+    if (!isAbsolute(workspaceRoot)) {
+        streams.stderr.write("h2a report-context: --workspace-root must be an absolute path\n");
+        return 1;
+    }
+    try {
+        const context = readH2AReportContext({
+            storeRoot: resolveRoot(flags, streams.cwd ?? (() => process.cwd())),
+            workspaceRoot
+        });
+        streams.stdout.write(`${JSON.stringify(context)}\n`);
+        return 0;
+    }
+    catch (err) {
+        streams.stderr.write(`h2a report-context: ${err.message}\n`);
+        return 3;
+    }
+}
+function cmdInstallTrackReportAiConfig(flags, streams) {
+    try {
+        const result = installTrackReportAiConfig({ force: flags.force === "true" });
+        streams.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof TrackReportAiConfigConflictError) {
+            streams.stderr.write(`h2a report-ai install-track-config: ${err.message}\n`);
+            return 2;
+        }
+        streams.stderr.write(`h2a report-ai install-track-config: ${err.message}\n`);
+        return 3;
+    }
+}
 function resolveTrackBin() {
     // Le champ `exports` de @sentropic/track bloque l'accès à ./package.json,
     // donc on résout l'entrée puis on remonte jusqu'au package.json du package.
@@ -5069,6 +5189,14 @@ export function runCli(argv = process.argv.slice(2), streams = {
         streams.stdout.write(`${JSON.stringify(H2A_CLI_MCP_TOOL_NAMES, null, 2)}\n`);
         return 0;
     }
+    if (command === "report-context")
+        return cmdReportContext(flags, streams);
+    if (command === "report-ai") {
+        if (argv[1] === "install-track-config")
+            return cmdInstallTrackReportAiConfig(flags, streams);
+        streams.stderr.write("h2a report-ai: async adapter command — run via the h2a binary\n");
+        return 1;
+    }
     if (command === "init")
         return cmdInit(flags, streams);
     if (command === "register")