@sentropic/h2a 0.80.0 → 0.82.0

package/dist/cli.js

@@ -43,6 +43,12 @@ import { homedir, hostname } from "node:os";
 import { dirname, 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
+// pty/aws/runtime). The golden rule (lazy-only) is scoped to
+// `@sentropic/h2a-runtime`/node-pty/aws-sdk, which track is NOT. Importing its
+// public `runCli` lets ④ run read-only track verbs IN-PROCESS (no spawn), on the
+// same `.track` under the same lock as the surviving spawn facade.
+import { runCli as runTrackCli } from "@sentropic/track";
 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, deriveConnectionConfidence, 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";
@@ -69,6 +75,9 @@ 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, listLoopEvents, listObjectiveLoops, readObjectiveLoop } 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";
 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.
@@ -1681,16 +1690,8 @@ function cmdLoop(argv, streams) {
             streams.stdout.write(`${JSON.stringify({ loopId, ...(agent ? { agent } : {}), events: listLoopEvents(root, loopId) }, null, 2)}\n`);
             return 0;
         }
-        if (sub === "tick" || sub === "watch") {
-            const loopId = argv[1];
-            if (!loopId || loopId.startsWith("--")) {
-                streams.stderr.write(`h2a loop ${sub}: <loopId> is required\n`);
-                return 1;
-            }
-            readObjectiveLoop(root, loopId);
-            streams.stdout.write(`${JSON.stringify({ ok: true, loopId, action: sub, supported: false, reason: "loop orchestration is not implemented in h2a loop MVP" }, null, 2)}\n`);
-            return 0;
-        }
+        // `tick` / `watch` are ASYNC (lazy runtime + periodic loop) → dispatched in
+        // bin.ts via `runLoopEngineCli`, not here (cmdLoop is synchronous).
     }
     catch (error) {
         streams.stderr.write(`h2a loop ${sub ?? ""}: ${error.message}\n`);
@@ -1699,6 +1700,83 @@ function cmdLoop(argv, streams) {
     streams.stderr.write("h2a loop: subcommand required (create, list, status, agents, attach, logs, tick, watch)\n");
     return 1;
 }
+/**
+ * Async dispatcher for `h2a loop tick|watch` (SLICE-1: dry-run only — produces a
+ * plan via the pure core + lazy adapters, executes nothing). Called from bin.ts
+ * because these are async (lazy runtime import + periodic loop). `argv` is the
+ * full bin argv: `["loop", "tick"|"watch", "<loopId>", ...flags]`.
+ */
+export async function runLoopEngineCli(argv, streams, signal) {
+    const sub = argv[1];
+    const loopId = argv[2];
+    const { flags } = parseFlags(argv);
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    if (!loopId || loopId.startsWith("--")) {
+        streams.stderr.write(`h2a loop ${sub}: <loopId> is required\n`);
+        return 1;
+    }
+    try {
+        if (sub === "watch") {
+            const intervalMs = flags["interval-ms"] ? Number(flags["interval-ms"]) : undefined;
+            const max = flags.max ? Number(flags.max) : undefined;
+            return await runLoopWatch(root, loopId, {
+                ...(intervalMs !== undefined && Number.isFinite(intervalMs) ? { intervalMs } : {}),
+                ...(max !== undefined && Number.isFinite(max) ? { max } : {}),
+                ...(signal ? { signal } : {}),
+                stdout: streams.stdout
+            });
+        }
+        // tick — DRY-RUN by default; `--execute` runs the plan (tranche 1: close only).
+        const execute = argv.includes("--execute");
+        const { plan, exec } = await runTick(root, loopId, { execute });
+        const out = exec ? { ...plan, exec } : plan;
+        streams.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+        return plan.outcome === "failed" ? 1 : 0;
+    }
+    catch (error) {
+        streams.stderr.write(`h2a loop ${sub}: ${error.message}\n`);
+        return classifyStoreError(error.message);
+    }
+}
+// Canevas ③ — read-only tranche-1 : agrège les décisions humaines en attente
+// (enveloppes `escalate` des inbox des instances live) en un JSON stable. La vue
+// session (capturePane runtime lazy), le serveur Hono et le pont-réponse
+// (reply-envelope gardé) sont des tranches ultérieures.
+function cmdCanevas(argv, streams) {
+    const { command: sub, flags } = parseFlags(argv);
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    if (sub === "list") {
+        try {
+            const decisions = gatherPendingDecisions(root);
+            streams.stdout.write(`${JSON.stringify({ kind: "canevas-decisions", version: 1, decisions }, null, 2)}\n`);
+            return 0;
+        }
+        catch (error) {
+            streams.stderr.write(`h2a canevas list: ${error.message}\n`);
+            return classifyStoreError(error.message);
+        }
+    }
+    streams.stderr.write("h2a canevas: subcommand required (list, serve)\n");
+    return 1;
+}
+/**
+ * Async dispatcher for `h2a canevas serve` (read-only Hono server on 127.0.0.1).
+ * Called from bin.ts (async + long-running). `argv` = full bin argv.
+ */
+export async function runCanevasServeCli(argv, streams, signal) {
+    const { flags } = parseFlags(argv);
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    const port = flags.port ? Number(flags.port) : undefined;
+    return runCanevasServe({
+        root,
+        ...(port !== undefined && Number.isFinite(port) ? { port } : {}),
+        stderr: streams.stderr,
+        ...(signal ? { signal } : {})
+    });
+}
 function cmdDrumbeat(argv, streams) {
     // DEC-086 (D2): durable anti-stall registry — record stops, scan candidates,
     // clear. The long-running `watch` daemon is async (dispatched from bin.ts).
@@ -4535,10 +4613,43 @@ export async function cmdKeepalive(flags, streams) {
 // P3 (façade track) — les verbes track sont délégués à la CLI `@sentropic/track`
 // par shell-out (le store `.track` est append-only single-writer : pas de 2ᵉ writer).
 // Verbes spécifiques, sans namespace `track` (dissous comme host/sub).
-const TRACK_FACADE_VERBS = new Set([
+export const TRACK_FACADE_VERBS = new Set([
     "decision", "report", "accept", "blocker", "item", "query",
     "consolidate", "priority", "branch", "focus", "ingest", "restructure"
 ]);
+// ④ 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
+// SYNC in the pinned track (dispatches through runCli's synchronous switch and
+// returns a `number`); the ONLY async verb, `focus` (dynamic
+// `import('@sentropic/focus')` → Promise), is deliberately excluded and keeps
+// shelling out. All paths resolve the SAME `.track` (native uses
+// `process.cwd()`, the spawn inherits it) and share track's single O_EXCL lock —
+// no split-brain, no second writer.
+//
+// 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
+//     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"]);
+// ④ 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.
+export const TRACK_NATIVE_WRITE_VERBS = new Set([
+    "decision", "item", "accept", "blocker",
+    "consolidate", "priority", "branch", "ingest", "restructure"
+]);
+// Union of the in-process verbs (read-only + sync writes). `focus` (async) is
+// NOT here and keeps the spawn facade. Kept exported as the single "is this verb
+// native?" predicate used by the dispatcher and the contract tests.
+export const TRACK_NATIVE_VERBS = new Set([
+    ...TRACK_NATIVE_READONLY_VERBS,
+    ...TRACK_NATIVE_WRITE_VERBS
+]);
 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.
@@ -4568,12 +4679,85 @@ function delegateToTrack(argv, streams) {
         return 1;
     }
 }
+/**
+ * ④ — run a track verb IN-PROCESS via `@sentropic/track`'s `runCli`.
+ *
+ * Split-brain mitigation (RISK #1): the native call resolves `.track` from
+ * `process.cwd()` — the SAME cwd the spawn facade inherits (`spawnSync` with no
+ * `cwd` option) — so both paths bind the identical store, and track's own
+ * O_EXCL lock still serialises them. We deliberately do NOT wrap the call in any
+ * h2a file-lock: track's lock is not re-entrant, and the facade never took one.
+ *
+ * Output is BUFFERED, then flushed only on a synchronous result.
+ *
+ * Two escape hatches, and the DOUBLE-WRITE rule (RISK #2) that separates them:
+ *   • `runCli` returns a Promise — an async verb (e.g. `focus`) that has NOT yet
+ *     written synchronously. The buffer is discarded and we fall back to the
+ *     spawn facade. Safe for reads AND writes; unreachable for the shipped set
+ *     (only sync verbs are routed here), so it is a defensive belt.
+ *   • `runCli` throws — an UNEXPECTED escape from track's own try/catch. For a
+ *     `readOnly` verb nothing was written, so we fall back to the spawn facade.
+ *     For a WRITE verb we MUST NOT re-run: track's `appendCommand` is atomic
+ *     (throws BEFORE the append on validation, or AFTER a landed write on the
+ *     verify receipt), so a spawn retry could double-write. We flush the buffered
+ *     native output and propagate a non-zero rc + stderr instead.
+ */
+function delegateToTrackNative(argv, streams, readOnly) {
+    const outBuf = [];
+    const errBuf = [];
+    const io = {
+        // CRITICAL: same root as the spawn facade inherits. Do NOT swap in
+        // `streams.cwd` here — divergence would split-brain the two paths.
+        cwd: process.cwd(),
+        out: (s) => {
+            outBuf.push(s);
+        },
+        err: (s) => {
+            errBuf.push(s);
+        }
+    };
+    try {
+        const rc = runTrackCli([...argv], io);
+        // Async verb (Promise) — nothing written synchronously yet, so a spawn
+        // fallback cannot double-write. Not representable for the shipped sync set.
+        if (rc !== null && typeof rc === "object" && typeof rc.then === "function") {
+            return delegateToTrack(argv, streams);
+        }
+        for (const s of outBuf)
+            streams.stdout.write(s);
+        for (const s of errBuf)
+            streams.stderr.write(s);
+        return rc;
+    }
+    catch (err) {
+        // READ-ONLY throw: nothing persisted → the spawn facade may safely re-run.
+        if (readOnly) {
+            return delegateToTrack(argv, streams);
+        }
+        // WRITE throw (anti-double-write): DO NOT re-run. `appendCommand` is atomic,
+        // so either nothing landed or the write already landed — a spawn retry could
+        // append a second event. Flush what the native path emitted and fail loud.
+        for (const s of outBuf)
+            streams.stdout.write(s);
+        for (const s of errBuf)
+            streams.stderr.write(s);
+        streams.stderr.write(`h2a ${argv[0]}: track write failed in-process (${err.message}). ` +
+            `No spawn retry — the store append is atomic; a retry could double-write.\n`);
+        return 1;
+    }
+}
 export function runCli(argv = process.argv.slice(2), streams = {
     stdout: process.stdout,
     stderr: process.stderr
 }) {
     const { command, flags } = parseFlags(argv);
     if (command && TRACK_FACADE_VERBS.has(command)) {
+        // ④: read-only + sync-write verbs run in-process; `focus` (async) keeps
+        // shelling out. Same `.track`, same lock. A native WRITE never falls back to
+        // spawn on throw (anti-double-write) — hence the read-only flag below.
+        if (TRACK_NATIVE_VERBS.has(command)) {
+            return delegateToTrackNative(argv, streams, TRACK_NATIVE_READONLY_VERBS.has(command));
+        }
         return delegateToTrack(argv, streams);
     }
     if (!command || command === "--help" || command === "-h" || command === "help") {
@@ -4598,6 +4782,8 @@ export function runCli(argv = process.argv.slice(2), streams = {
         return cmdSubagent(argv.slice(1), streams);
     if (command === "loop")
         return cmdLoop(argv.slice(1), streams);
+    if (command === "canevas")
+        return cmdCanevas(argv.slice(1), streams);
     if (command === "drumbeat") {
         const sub = argv[1];
         if (sub === "watch") {