@north-light/crouter 0.3.172 → 0.3.174

package/dist/daemon/api/__tests__/{full/push-parity.test.js → seam/leaf-api-parity.test.js}

@@ -1,26 +1,22 @@
-// Run with: node --import tsx/esm --test src/daemon/api/__tests__/full/push-parity.test.ts
+// Run with: node --import tsx/esm --test src/daemon/api/__tests__/seam/leaf-api-parity.test.ts
 //
-// B-5 acceptance (plan §Stage B, B1 for push) — the re-plumbed `crtr push`
-// verb (src/commands/push.ts) is now a PURE crtrd API client: every tier goes
-// through `POST /nodes/{id}/reports` and the report write, the per-subscriber
-// inbox fan, and (final only) the lifecycle transition all happen SERVER-side
-// inside feed `push()` (spec §7.4). This proves that end-to-end by driving the
-// ACTUAL `push.ts` leaf (not `client.pushReport` directly) against a
-// CRTR_HOME-isolated in-process crtrd, with a real parent+child pair.
+// The `crtr push` and `crtr node worktree close` leaves are pure crtrd API
+// clients: the report write, the per-subscriber inbox fan, the lifecycle
+// transition (spec §7.4), and the worktree land+close git transaction all
+// happen SERVER-side. These tests drive the ACTUAL leaves (not the client
+// methods directly) against a CRTR_HOME-isolated in-process crtrd, with real
+// parent+child pairs and real git repos.
 //
-// FULL TIER (real-boot-bound): lives in `__tests__/full/` for the 30s-per-test
-// / CI-only tier (scripts/test-runner.mjs, `file.includes('/__tests__/full/')`),
-// same harness as api-server.test.ts (A-11). tmux-free (createHeadlessHarness)
-// but boots REAL broker processes with the fake engine — no LLM cost.
+// COMPILED SEAM (real-boot-bound): lives in `__tests__/seam/` for the 30s-per-test
+// / CI-only tier, same harness as api-server.test.ts. tmux-free
+// (createHeadlessHarness) but boots REAL broker processes with the fake engine
+// — no LLM cost.
 //
-// The push leaf resolves its client through `cliClient()` →
+// A leaf resolves its client through `cliClient()` →
 // `CrtrClient.forLocalSocket` → `apiSocketPath()` == `<CRTR_HOME>/crtrd.sock`,
 // the SAME socket `createApiServer()` binds here. So `pushLeaf(tier).run()` in
-// this process, with `CRTR_NODE_ID` set to the child, connects to the
-// in-process server exactly as a real `crtr push` CLI process would. The leaf
-// reaches ZERO canvas state-store code (proven separately by the emitted
-// dist import-graph, reported in this node's B-5 final); this test proves the
-// runtime behavior on the far side of that boundary.
+// this process, with `CRTR_NODE_ID` set to the caller, connects to the
+// in-process server exactly as a real `crtr push` CLI process would.
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
@@ -31,6 +27,7 @@ import { createApiServer } from '../../server.js';
 import { apiSocketPath } from '../../../../core/canvas/paths.js';
 import { CrtrClient } from '../../../../api/index.js';
 import { registerPush } from '../../../../commands/push.js';
+import { registerNode } from '../../../../commands/node.js';
 import { createNode, getNode } from '../../../../core/canvas/canvas.js';
 import { createManagedWorktree } from '../../../../core/worktree.js';
 import { gitSync } from '../../../../core/git.js';
@@ -49,7 +46,7 @@ function git(args, cwd) {
 /** A fresh git repo with one commit on `main` — the base a managed worktree
  *  branches off. Returns the repo dir (caller removes it). */
 function initRepo() {
-    const repo = mkdtempSync(join(tmpdir(), 'crtr-pushparity-repo-'));
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-leafparity-repo-'));
     git(['init', '-b', 'main'], repo);
     git(['config', 'user.email', 'test@example.com'], repo);
     git(['config', 'user.name', 'Test'], repo);
@@ -88,8 +85,27 @@ async function runPushAs(caller, tier, body) {
             process.env['CRTR_NODE_ID'] = prev;
     }
 }
+// The `node worktree close` leaf, resolved from the real command tree exactly as
+// the CLI dispatcher would, and driven as the given caller node.
+async function runCloseAs(caller) {
+    const worktree = registerNode().children.find((c) => c.name === 'worktree');
+    assert.ok(worktree !== undefined && worktree.kind === 'branch', 'node worktree branch resolves');
+    const close = worktree.children.find((c) => c.name === 'close');
+    assert.ok(close !== undefined && close.kind === 'leaf', 'node worktree close leaf resolves');
+    const prev = process.env['CRTR_NODE_ID'];
+    process.env['CRTR_NODE_ID'] = caller;
+    try {
+        return (await close.run({}));
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = prev;
+    }
+}
 before(async () => {
-    h = await createHeadlessHarness({ sessionPrefix: 'crtr-pushparity' });
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-leafparity' });
     server = createApiServer(); // binds <h.home>/crtrd.sock (CRTR_HOME set by harness)
     sockPath = apiSocketPath();
     await h.waitFor(() => existsSync(sockPath), { label: 'api socket bound', timeoutMs: 10_000 });
@@ -112,28 +128,13 @@ after(async () => {
         process.env['CRTR_NODE_ID'] = savedNodeId;
 });
 // ---------------------------------------------------------------------------
-// B1 (push) — structural parity of report_path / notified / transitioned on
-// update + final, driven through the real push.ts leaf. A parent spawns a
-// child (so the parent subscribes to the child); the child pushes.
+// push final — the report write, the subscriber fan, and the lifecycle
+// transition all happen server-side, driven through the real push.ts leaf. A
+// parent spawns a child (so the parent subscribes to the child); the child
+// pushes.
 // ---------------------------------------------------------------------------
-test('B1: `crtr push update` from a child writes a report, notifies the subscribed parent, and does NOT transition — leaf output has the exact { report_path, notified } shape with no transitioned field', async () => {
-    const parent = h.spawnRoot('push-parity update parent'); // resident, subscribes to its child
-    const child = (await client.createNode({ kind: 'developer', parent, prompt: 'update worker' })).node_id;
-    await h.awaitBoot(child);
-    assert.equal(h.node(child)?.status, 'active', 'the child is live/active before the update push');
-    const out = await runPushAs(child, 'update', 'update from the child');
-    // report_path: an absolute path to a report file the server actually wrote.
-    assert.equal(typeof out['report_path'], 'string', 'report_path is a string');
-    assert.ok(existsSync(out['report_path']), `report file written at ${String(out['report_path'])}`);
-    // notified: the subscribed parent received an inbox pointer.
-    assert.ok(Array.isArray(out['notified']), 'notified is an array');
-    assert.ok(out['notified'].includes(parent), `update notifies the subscribed parent (notified=${JSON.stringify(out['notified'])})`);
-    // transitioned: ABSENT for a non-final tier — an update never flips lifecycle.
-    assert.equal('transitioned' in out, false, 'update carries no transitioned field');
-    assert.equal(h.node(child)?.status, 'active', 'the child stays active after an update (no transition)');
-});
-test('B1: `crtr push final` from a child writes a report, notifies the subscribed parent, AND transitions the child row active→done — leaf output carries transitioned={from,to} and the row is genuinely done', async () => {
-    const parent = h.spawnRoot('push-parity final parent');
+test('`crtr push final` from a child writes a report, notifies the subscribed parent, AND transitions the child row active→done', async () => {
+    const parent = h.spawnRoot('leaf-api-parity final parent');
     const child = (await client.createNode({ kind: 'developer', parent, prompt: 'final worker' })).node_id;
     await h.awaitBoot(child);
     assert.equal(h.node(child)?.status, 'active', 'the child is live/active before the final push');
@@ -179,7 +180,7 @@ test('re-homed guard: `crtr push final` on a node with a managed worktree holdin
         rmSync(repo, { recursive: true, force: true });
     }
 });
-test('re-homed auto-drop: `crtr push final` on a node with a CLEAN, zero-commit managed worktree auto-drops it server-side, surfaces worktree_auto_dropped(+path) on the leaf output, and finalizes normally', async () => {
+test('auto-drop: `crtr push final` on a node with a CLEAN, zero-commit managed worktree auto-drops it server-side, surfaces worktree_auto_dropped(+path) on the leaf output, and finalizes normally', async () => {
     const repo = initRepo();
     try {
         const id = 'wt-clean-empty-final';
@@ -197,3 +198,21 @@ test('re-homed auto-drop: `crtr push final` on a node with a CLEAN, zero-commit
         rmSync(repo, { recursive: true, force: true });
     }
 });
+// ---------------------------------------------------------------------------
+// `node worktree close` error parity — the SPECIFIC WorktreeError code + its
+// `next` remediation round-trip verbatim through the server → ApiError → the
+// bespoke CLI mapper in node-worktree.ts, instead of collapsing to a generic
+// status bucket. That mapper exists for exactly this contract, so this is the
+// load-bearing regression to lock.
+// ---------------------------------------------------------------------------
+test('`crtr node worktree close` on a node with NO managed worktree round-trips the specific `no_managed_worktree` code + its exact next-hint (not a generic status bucket)', async () => {
+    const id = 'wt-close-none';
+    createNode({ node_id: id, name: id, created: new Date().toISOString(), cwd: process.cwd(), kind: 'developer', mode: 'base', lifecycle: 'terminal', status: 'active' });
+    await assert.rejects(() => runCloseAs(id), (e) => e instanceof InputError &&
+        e.payload.error === 'no_managed_worktree' &&
+        typeof e.payload.next === 'string' &&
+        e.payload.next.includes('Nothing to close'), 'the specific WorktreeError code + next survive the server → ApiError → custom CLI mapper');
+});
+test('`crtr node worktree close` for an UNKNOWN node round-trips the specific `unknown_node` code (a 404 that is NOT flattened to not_found)', async () => {
+    await assert.rejects(() => runCloseAs('no-such-node-xyz'), (e) => e instanceof InputError && e.payload.error === 'unknown_node', 'unknown_node keeps its specific code even though it maps to a 404 status');
+});

package/dist/daemon/api/bridge.js

@@ -1,34 +1,23 @@
-// bridge.ts — the crtrd WS attach bridge (spec §5, esp. §5.3).
+// bridge.ts — crtrd's WebSocket attach bridge (spec §5, especially §5.3).
 //
-// Relays ONE remote WebSocket ⇄ ONE node broker `view.sock`, byte-for-byte, for
-// `GET /v1/nodes/{id}/attach` with `Upgrade: websocket`. The relay is a
-// near-verbatim lift of `bridgeConnection` from `clients/web/server.ts` — it
-// NEVER interprets a frame, only splits/joins the newline framing: each complete
-// broker frame becomes one WS text message (bounded decode via
-// `FrameDecoder(CLIENT_READ_CAPS)`), and each WS message becomes one
-// newline-terminated line into the socket. Idempotent teardown, no leaks, one
-// `view.sock` connection per WS (the broker fans out natively).
+// `GET /v1/nodes/{id}/attach` relays one remote WebSocket to one node broker
+// `view.sock`. The bridge never interprets frames: each complete broker frame
+// becomes one WebSocket text message (bounded by `FrameDecoder(CLIENT_READ_CAPS)`),
+// and each WebSocket message becomes one newline-terminated socket line.
+// Teardown is idempotent, and each WebSocket owns one `view.sock` connection;
+// the broker fans out to its clients natively.
 //
-// The ONE functional addition over the web relay (spec §5.3): ATTACH IMPLIES
-// REVIVE. Opening a conversation means "wake it." BEFORE the WS is opened (so the
-// socket exists when the bridge connects — no racy revive-then-attach dance) the
-// upgrade handler calls `reviveNode(id, { resume: true })`
-// unless the caller opts out with `?revive=0` or header `X-Crtr-Attach-Revive: 0`,
-// then waits for the broker's `view.sock` to be listenable
-// (`waitForBrokerViewSocket`, bounded). If revive throws (finalization latch,
-// boot fault) or the socket never becomes listenable, the upgrade is REFUSED with
-// 409 and the WS is never opened. With revive opted out on a dormant node, the
-// socket can't stream, so the upgrade is likewise refused 409 (spec §5.3's named
-// asymmetry — the POST-local path returns a possibly-dead path instead). ALL
-// pre-upgrade refusals write a plain HTTP error response to the raw socket and
-// destroy it; only post-upgrade faults use WS close codes (1008/1009/1011).
+// Attach implies revive. Before opening WebSocket, the upgrade handler calls
+// `reviveNode(id, { resume: true })` unless `?revive=0` or
+// `X-Crtr-Attach-Revive: 0` opts out, then waits for `view.sock` to become
+// listenable. A failed revive or an unready socket refuses the upgrade with 409.
+// With revive opted out, a dormant node also refuses with 409. Pre-upgrade
+// refusals send a plain HTTP error and destroy the raw socket; post-upgrade
+// faults use WebSocket close codes (1008/1009/1011).
 //
-// §0 ONE-WRITER: like the web relay, once open this bridge is ONLY a socket
-// relay — it NEVER touches SessionManager, spawns `pi --session`, or writes a
-// `.jsonl`. The ONLY engine launch it performs is the sanctioned
-// `reviveNode()` (spec §5.3), the canonical broker launcher; the relay itself
-// launches nothing. The sole direct canvas write is a relay fault record when the
-// broker socket fails.
+// Once open, the bridge only relays sockets. It never touches SessionManager,
+// spawns `pi --session`, or writes a `.jsonl`; `reviveNode()` is its sole engine
+// launch path. It records a fault only when the broker socket fails.
 import { createConnection } from 'node:net';
 import { WebSocketServer } from 'ws';
 import { isSafeNodeId, viewSocketPath } from '../../core/canvas/paths.js';
@@ -37,12 +26,12 @@ import { BROKER_READ_CAPS, CLIENT_READ_CAPS, FrameDecoder, FrameOverflowError, }
 import { classify } from '../../core/fault-classifier.js';
 import { clearFault, recordFault } from '../../core/runtime/fault.js';
 import { reviveNode } from '../../core/runtime/revive.js';
-import { waitForBrokerViewSocket } from '../../core/runtime/placement-tmux.js';
+import { probeViewSocket, waitForBrokerViewSocket } from '../../core/runtime/view-socket.js';
 /** Our own noServer WS server: A-9 routes matched attach upgrades to
  *  {@link handleAttachUpgrade}, which performs the handshake through this. Bounds
  *  the INBOUND remote→broker path to the broker's OWN read cap (not the generous
- *  client cap) so a remote peer can't buffer 256MiB/message before the broker's
- *  24MiB decoder rejects it (memory amplification — mirrors the web relay's M3). */
+ *  client cap) so a remote peer cannot buffer 256MiB before the broker's 24MiB
+ *  decoder rejects the message. */
 const wss = new WebSocketServer({ noServer: true, maxPayload: BROKER_READ_CAPS.maxLineBytes });
 /** A WS close reason is capped at 123 UTF-8 bytes by the protocol. */
 function clampReason(reason) {
@@ -84,35 +73,6 @@ function reviveOptedOut(req) {
     const value = Array.isArray(header) ? header[0] : header;
     return value === '0';
 }
-/** Single-shot connect probe: resolves true only if the broker's `view.sock`
- *  accepts a connection right now (a dormant node's socket refuses/absent →
- *  false). Used for the revive-opted-out dormant-refusal path, where a bounded
- *  retry loop would be wrong — we want a decisive is-it-live-NOW answer, not a
- *  wait. (placement's `probeBrokerViewSocket` is not exported.) */
-function probeViewSocketOnce(sockPath, timeoutMs = 250) {
-    return new Promise((resolve) => {
-        let done = false;
-        let socket = null;
-        const finish = (ok) => {
-            if (done)
-                return;
-            done = true;
-            if (socket !== null)
-                socket.destroy();
-            resolve(ok);
-        };
-        try {
-            socket = createConnection(sockPath);
-        }
-        catch {
-            finish(false);
-            return;
-        }
-        socket.once('connect', () => finish(true));
-        socket.once('error', () => finish(false));
-        socket.setTimeout(timeoutMs, () => finish(false));
-    });
-}
 /** Relay one remote WS ⇄ one node broker `view.sock`. Opens the socket on
  *  connect; forwards each complete frame socket→WS (bounded decode, one WS
  *  message per frame) and re-frames each WS message WS→socket (trailing
@@ -120,8 +80,7 @@ function probeViewSocketOnce(sockPath, timeoutMs = 250) {
  *  (it only splits/joins the newline framing). Closes the WS on socket
  *  gone/no-broker, destroys the socket on WS close; idempotent teardown, no
  *  leaks. Validates the node id first (path-safety + existence) as belt-and-
- *  suspenders — the upgrade handler already guarded both. Near-verbatim lift of
- *  `bridgeConnection` from `clients/web/server.ts`. */
+ *  suspenders — the upgrade handler already guarded both. */
 function bridgeConnection(ws, nodeId) {
     if (!isSafeNodeId(nodeId)) {
         try {
@@ -141,12 +100,12 @@ function bridgeConnection(ws, nodeId) {
         }
         return;
     }
-    clearFault(nodeId, { link: 'browser↔relay' });
+    clearFault(nodeId, { link: 'viewer↔crtrd' });
     const sockPath = viewSocketPath(nodeId);
     const socket = createConnection(sockPath);
     const decoder = new FrameDecoder(CLIENT_READ_CAPS);
     let closed = false;
-    let browserFaultRecorded = false;
+    let viewerFaultRecorded = false;
     socket.on('connect', () => {
         clearFault(nodeId, { link: 'relay↔broker' });
     });
@@ -211,38 +170,38 @@ function bridgeConnection(ws, nodeId) {
         const reasonText = reason.toString('utf8');
         if (closed) {
             if (code === 1000)
-                clearFault(nodeId, { link: 'browser↔relay' });
+                clearFault(nodeId, { link: 'viewer↔crtrd' });
             return;
         }
         if (code === 1000) {
-            clearFault(nodeId, { link: 'browser↔relay' });
+            clearFault(nodeId, { link: 'viewer↔crtrd' });
         }
-        else if (!browserFaultRecorded) {
-            browserFaultRecorded = true;
-            const classification = classify('browser↔relay', { code, reason: reasonText });
+        else if (!viewerFaultRecorded) {
+            viewerFaultRecorded = true;
+            const classification = classify('viewer↔crtrd', { code, reason: reasonText });
             recordFault(nodeId, {
-                link: 'browser↔relay',
-                op: 'browser websocket',
+                link: 'viewer↔crtrd',
+                op: 'remote attach websocket',
                 kind: classification.kind,
                 retry: { disposition: 'manual' },
-                message: reasonText || `browser relay closed (${code})`,
+                message: reasonText || `remote attach closed (${code})`,
             });
         }
-        teardown(code, reasonText || `browser relay closed (${code})`);
+        teardown(code, reasonText || `remote attach closed (${code})`);
     });
     ws.on('error', () => {
-        if (!browserFaultRecorded) {
-            browserFaultRecorded = true;
-            const classification = classify('browser↔relay', { code: 1006, reason: 'browser ws error' });
+        if (!viewerFaultRecorded) {
+            viewerFaultRecorded = true;
+            const classification = classify('viewer↔crtrd', { code: 1006, reason: 'remote attach websocket error' });
             recordFault(nodeId, {
-                link: 'browser↔relay',
-                op: 'browser websocket',
+                link: 'viewer↔crtrd',
+                op: 'remote attach websocket',
                 kind: classification.kind,
                 retry: { disposition: 'manual' },
-                message: 'browser ws error',
+                message: 'remote attach websocket error',
             });
         }
-        teardown(1011, 'browser ws error');
+        teardown(1011, 'remote attach websocket error');
     });
     // WS → socket: re-frame each message as one newline-terminated JSON line.
     // VERBATIM (no parse) — the broker validates and bounds its own reads.
@@ -304,7 +263,7 @@ export async function handleAttachUpgrade(req, socket, head, nodeId) {
             // (3) Revive opted out: the socket must already be live. A dormant node's
             // socket can't stream, so refuse 409 rather than open a WS that would
             // immediately 1011 (spec §5.3 named asymmetry).
-            if (!(await probeViewSocketOnce(viewSocketPath(nodeId)))) {
+            if (!(await probeViewSocket(viewSocketPath(nodeId), 250))) {
                 refuseUpgrade(socket, 409, 'Conflict', 'node_dormant', `node ${nodeId} is dormant and revive was opted out (?revive=0)`);
                 return;
             }

package/dist/daemon/api/handlers/broker-ops.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const brokerOperationRoutes: RouteTable;