@north-light/crouter 0.3.154

package/dist/daemon/__tests__/broker-ownership.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/__tests__/broker-ownership.test.js

@@ -0,0 +1,25 @@
+// Regression (2026-07-22 cross-canvas broker slaughter): the orphan reaper
+// matched every broker-cli.js process on the machine, so a test-fixture
+// daemon in a temp CRTR_HOME SIGTERMed the real fleet each test iteration
+// while the real daemon reaped the fixture's brk-* brokers. Ownership is now
+// DECLARED at spawn — `broker-cli.js --canvas-home <home> <nodeId>` — and
+// the census/reap match exactly the daemon's own canvas home; untagged or
+// foreign-home brokers are invisible to both.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { brokerCommandDeclaresCanvasHome } from '../crtrd.js';
+const HOME = '/Users/u/.crouter/canvas';
+const CMD = `1234 /Users/u/.crouter/host/crouter /Users/u/.crouter/runtime/generations/abc/dist/core/runtime/broker-cli.js --canvas-home ${HOME} mrnode01-aabbccdd`;
+test('matches a broker declaring this canvas home', () => {
+    assert.equal(brokerCommandDeclaresCanvasHome(CMD, HOME), true);
+});
+test('rejects a broker declaring a different canvas home', () => {
+    assert.equal(brokerCommandDeclaresCanvasHome(CMD, '/tmp/crtr-test-xyz/canvas'), false);
+});
+test('rejects an untagged (pre-tag or harness-spawned) broker', () => {
+    const untagged = '1234 node /repo/dist/core/runtime/broker-cli.js brk-99-0';
+    assert.equal(brokerCommandDeclaresCanvasHome(untagged, HOME), false);
+});
+test('rejects a home that is a prefix of the declared home', () => {
+    assert.equal(brokerCommandDeclaresCanvasHome(CMD, '/Users/u/.crouter'), false);
+});

package/dist/daemon/__tests__/daemon-ownership.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/__tests__/daemon-ownership.test.js

@@ -0,0 +1,27 @@
+// Regression (issue #518): `crtr sys daemon stop` under an isolated
+// CRTR_HOME/HOME ran a machine-wide `sweepStrayDaemons()` — findDaemonPids()
+// matched every `daemon/crtrd` process on the host with zero scoping to the
+// invoking process's own canvas home — so it SIGTERM/SIGKILL'd a real,
+// unrelated daemon elsewhere on the same machine. Ownership is now DECLARED
+// at spawn — `crtrd-cli.js --canvas-home <home>` (spawnDaemon) — and the
+// stray scan matches exactly the invoking process's own canvas home;
+// untagged or foreign-home daemons are invisible to it. Mirrors the sibling
+// broker-ownership fix (daemon/__tests__/broker-ownership.test.ts).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { daemonCommandDeclaresCanvasHome } from '../manage.js';
+const HOME = '/Users/u/.crouter/canvas';
+const CMD = `1234 /Users/u/.crouter/host/crouter /Users/u/.crouter/runtime/generations/abc/dist/daemon/crtrd-cli.js --canvas-home ${HOME}`;
+test('matches a daemon declaring this canvas home', () => {
+    assert.equal(daemonCommandDeclaresCanvasHome(CMD, HOME), true);
+});
+test('rejects a daemon declaring a different canvas home', () => {
+    assert.equal(daemonCommandDeclaresCanvasHome(CMD, '/tmp/crtr-test-xyz/canvas'), false);
+});
+test('rejects an untagged (pre-tag or externally-launched, e.g. launchd) daemon', () => {
+    const untagged = '1234 node /repo/dist/daemon/crtrd-cli.js';
+    assert.equal(daemonCommandDeclaresCanvasHome(untagged, HOME), false);
+});
+test('rejects a home that is a prefix of the declared home', () => {
+    assert.equal(daemonCommandDeclaresCanvasHome(CMD, '/Users/u'), false);
+});

package/dist/daemon/api/__tests__/error-seam.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/api/__tests__/error-seam.test.js

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { toErrorBody } from '../map.js';
+import { ApiError } from '../../../api/errors.js';
+import { apiErrorToCliError, InputError } from '../../../core/io.js';
+import { brokerLaunchFailed } from '../../../core/errors.js';
+// Regression for crouter#521: choosing the root profile on a virgin machine
+// died with a bare `<error code="internal">\ninternal error` and ZERO cause —
+// the front-door `createNode({root:true})` boot failure was thrown as a plain
+// Error deep in spawnChild, collapsed to a 500 by the daemon (which stripped
+// the message AND logged nothing), and rebuilt client-side as an opaque
+// internal. These tests pin the two halves of the fix at the seam they cross.
+/** Reproduce crtrd's server → wire → client round-trip exactly: the daemon maps
+ *  a thrown value to a wire body (`toErrorBody`), the client rebuilds an
+ *  `ApiError` from that body the way `client.ts:parse` does, and
+ *  `apiErrorToCliError` turns it into the CLI-facing error a caller sees. */
+function roundTrip(thrown) {
+    const { status, body } = toErrorBody(thrown);
+    const client = new ApiError(status, body.error.code, body.error.message, body.error.details);
+    const cli = apiErrorToCliError(client);
+    assert.ok(cli instanceof InputError, 'a 4xx/5xx round-trips to an InputError the CLI renders');
+    return cli;
+}
+test('a named broker-launch failure round-trips verbatim, never a bare internal', () => {
+    const cli = roundTrip(brokerLaunchFailed('the root broker mrxz-1 could not start — resolveLaunchModel: no model configured', 'Resolve the cause named above, then retry.'));
+    // The specific code, curated message, and actionable next all survive the API
+    // boundary — the caller learns exactly what failed and what to do.
+    assert.equal(cli.payload.error, 'broker_launch_failed');
+    assert.match(cli.payload.message, /could not start — resolveLaunchModel: no model configured/);
+    assert.equal(cli.payload.next, 'Resolve the cause named above, then retry.');
+    // The exact failure mode #521 reported must NOT recur.
+    assert.notEqual(cli.payload.error, 'internal');
+    assert.notEqual(cli.payload.message, 'internal error');
+});
+test('an unanticipated 500 surfaces its cause instead of a causeless "internal error"', () => {
+    const cli = roundTrip(new Error('sqlite: database is locked'));
+    assert.equal(cli.payload.error, 'internal');
+    // The real cause reaches the caller (previously stripped to "internal error").
+    assert.match(cli.payload.message, /database is locked/);
+    assert.notEqual(cli.payload.message, 'internal error');
+    // ...and the next-hint is the crtr-bug guidance, not "adjust the call".
+    assert.match(cli.payload.next, /crtr bug/);
+});
+test('a 500 body carries only the bounded first line, never a multi-line stack', () => {
+    const withStack = new Error('top cause of the failure');
+    withStack.stack = 'Error: top cause of the failure\n    at foo (bar.js:1:1)\n    at baz (qux.js:2:2)';
+    // A real thrown Error surfaces its .message (single line by construction); the
+    // guard additionally clamps any embedded newline so a stack can never leak.
+    const multiline = new Error('first line\n    at leak (secret.js:9:9)');
+    const { status, body } = toErrorBody(multiline);
+    assert.equal(status, 500);
+    assert.equal(body.error.message, 'first line');
+    assert.equal(body.error.details, undefined, 'a 500 still omits structured details for hygiene');
+    // sanity: an ordinary message passes through untouched
+    assert.equal(toErrorBody(withStack).body.error.message, 'top cause of the failure');
+});

package/dist/daemon/api/__tests__/full/api-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/api/__tests__/full/api-server.test.js

@@ -0,0 +1,369 @@
+// Run with: node --import tsx/esm --test src/daemon/api/__tests__/full/api-server.test.ts
+//
+// A-11 — the Stage-A acceptance gate for the crtrd API server (spec §10, plan
+// §Stage A). Proves A1–A8: the `CrtrClient` HTTP+WS transport drives the FULL
+// server → router → handlers → bridge stack over the real unix socket, against a
+// CRTR_HOME-isolated crtrd, with a fake broker engine (zero LLM cost).
+//
+// FULL TIER (real-boot-bound): this file lives in `__tests__/full/` so the
+// runner (scripts/test-runner.mjs, `file.includes('/__tests__/full/')`) gives it
+// the 30s-per-test / CI-only tier, exactly like the tmux-free
+// `src/core/__tests__/full/broker-attach-stream.test.ts` precedent. It is
+// tmux-free (createHeadlessHarness) but boots REAL broker processes, so it is NOT
+// on the fast local loop.
+//
+// APPROACH (see this node's a11-plan.md): the harness stands in for crtrd
+// (in-process superviseTick, fake-live-daemon pidfile, isolated CRTR_HOME + the
+// fake-pi/fake-engine seams); we additionally start `createApiServer()`
+// IN-PROCESS, which binds the unix socket at `apiSocketPath()` == `<home>/
+// crtrd.sock`. Handlers call the SAME in-process internals (spawnChild /
+// reviveNode / push / appendInbox), and brokers spawned by handlers inherit the
+// test process env (fake engine). NO product code is edited by this test.
+//
+// HONEST PROXIES (documented per criterion below):
+//  - A6 model-auth reload fan: the mtime watcher that fans `reload_auth` lives in
+//    crtrd's runDaemon(), NOT createApiServer(). Running the server in-process
+//    (not full runDaemon) means that watcher is inactive, so A6 asserts the
+//    auth.json FILE WRITE only — the plan's sanctioned substitution.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { statSync, existsSync, readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import WebSocket from 'ws';
+import { createHeadlessHarness } from '../../../../core/__tests__/helpers/harness.js';
+import { createAttachKit } from '../../../../core/__tests__/helpers/broker-clients.js';
+import { ApiError, CrtrClient } from '../../../../api/index.js';
+import { createApiServer } from '../../server.js';
+import { apiSocketPath, inboxPath } from '../../../../core/canvas/paths.js';
+import { isPidAlive } from '../../../../core/canvas/pid.js';
+let h;
+let server;
+let client;
+let sockPath;
+const kit = createAttachKit(() => h);
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-apisrv' });
+    server = createApiServer(); // binds <h.home>/crtrd.sock (CRTR_HOME set by harness)
+    sockPath = apiSocketPath();
+    // listen() is async — the socket file appears in its callback.
+    await h.waitFor(() => existsSync(sockPath), { label: 'api socket bound', timeoutMs: 10_000 });
+    client = new CrtrClient({ socketPath: sockPath, autostart: false });
+});
+after(async () => {
+    kit.closeAll();
+    await server?.close();
+    await h?.dispose();
+});
+// Seed a non-empty assistant session so `close` takes the cancel+notice path
+// (leaving a revivable 'canceled' husk) rather than the reap-empty path (which
+// deletes the row). Mirrors cascade-close.test.ts — an empty session is reaped,
+// a non-empty one is canceled and kept.
+function seedAssistantSession(sessionFile) {
+    mkdirSync(dirname(sessionFile), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
+}
+// Count non-empty lines in a jsonl file (raw, cursor-independent — the live
+// broker's inbox-watcher advances a SEPARATE cursor sidecar, so reading the
+// append-only file directly is stable regardless of consumption).
+function countLines(path) {
+    try {
+        return readFileSync(path, 'utf8').split('\n').filter((l) => l.trim() !== '').length;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// A1 — /healthz ok + socket mode 0600
+// ---------------------------------------------------------------------------
+test('A1: /healthz is ok and the unix socket is bound mode 0600', async () => {
+    const health = await client.healthz();
+    assert.equal(health.ok, true, 'GET /healthz → { ok: true }');
+    const mode = statSync(sockPath).mode & 0o777;
+    assert.equal(mode, 0o600, `socket mode is 0600 (fs-perms-as-auth), got 0o${mode.toString(8)}`);
+});
+test('attention counts reads only the requested node slice', async () => {
+    const root = h.spawnRoot('attention root');
+    const result = await client.attentionCounts([root, 'unknown-node']);
+    assert.deepEqual(result.counts, { [root]: 0, 'unknown-node': 0 });
+});
+// ---------------------------------------------------------------------------
+// A2 — POST /nodes → live node (row + broker + recorded pid), GET shows active,
+//      view.sock exists
+// ---------------------------------------------------------------------------
+test('A2: POST /nodes boots a live broker; GET /nodes/{id} shows active + live pid + view.sock', async () => {
+    const root = h.spawnRoot('a2 root'); // in-process resident, pi_pid = harness pid (alive)
+    const detail = await client.createNode({ kind: 'developer', parent: root, prompt: 'a2 worker' });
+    const id = detail.node_id;
+    assert.ok(id && id !== '', 'create returns a node_id');
+    await h.awaitBoot(id); // fake-pi wrote its boot proof → broker engine is up
+    const got = await client.getNode(id);
+    assert.equal(got.status, 'active', 'GET /nodes/{id} reports active');
+    assert.ok(got.pi_pid != null && isPidAlive(got.pi_pid), 'detail carries a live recorded pid');
+    const meta = h.node(id);
+    assert.ok(meta?.pi_pid != null && isPidAlive(meta.pi_pid), 'row records a live broker pid');
+    assert.ok(existsSync(h.brokerSock(id)), 'view.sock exists for the live broker');
+});
+// ---------------------------------------------------------------------------
+// A3 — POST .../messages appends inbox.jsonl; POST .../reports {tier:'final'}
+//      writes the report, notifies subscribers, transitions the row
+// ---------------------------------------------------------------------------
+test('A3: messages append inbox.jsonl; final report writes + notifies subscriber + transitions row', async () => {
+    const A = h.spawnRoot('a3 mgr');
+    const B = (await client.createNode({ kind: 'developer', parent: A, prompt: 'a3 worker' })).node_id;
+    await h.awaitBoot(B);
+    // --- messages append inbox.jsonl (raw line count is cursor-independent) ---
+    const inboxFile = inboxPath(B);
+    const before = countLines(inboxFile);
+    const msg = await client.sendMessage(B, { body: 'hello inbox' });
+    assert.equal(msg.delivered, true, 'message reports delivered');
+    await h.waitFor(() => countLines(inboxFile) > before, { label: 'inbox.jsonl appended', timeoutMs: 10_000 });
+    // --- final report: file written + subscriber notified + row transitioned ---
+    const res = await client.pushReport(B, { tier: 'final', body: 'a3 done result' });
+    assert.ok(existsSync(res.report_path), `report file written at ${res.report_path}`);
+    assert.ok(res.notified.includes(A), `final push notifies the spawn-subscribed manager A (notified=${JSON.stringify(res.notified)})`);
+    assert.deepEqual(res.transitioned, { from: 'active', to: 'done' }, 'row transitioned active→done');
+    assert.equal(h.node(B)?.status, 'done', 'row status is done after final');
+});
+// ---------------------------------------------------------------------------
+// A4 — WS attach → welcome.snapshot byte-identical vs a direct ViewSocketClient;
+//      ?revive=0 on a dormant node → 409 without launching a broker
+// ---------------------------------------------------------------------------
+test('A4a: WS attach welcome.snapshot is byte-identical to a direct ViewSocketClient snapshot', async () => {
+    const root = h.spawnRoot('a4 root');
+    const id = (await client.createNode({ kind: 'developer', parent: root, prompt: 'a4 worker' })).node_id;
+    await h.awaitBoot(id);
+    // Direct capture via the production ViewSocketClient (the attach kit).
+    const direct = await kit.attach(id, 'observer', 'a4-direct');
+    // WS capture over the unix socket at the attach path. The node is already
+    // live+booted, so ?revive=0 is fine (the socket is listenable).
+    const wsWelcome = await new Promise((resolveWelcome, rejectWelcome) => {
+        const ws = new WebSocket(`ws+unix://${sockPath}:/v1/nodes/${id}/attach?revive=0`);
+        const timer = setTimeout(() => {
+            ws.terminate();
+            rejectWelcome(new Error('timed out waiting for WS welcome frame'));
+        }, 15_000);
+        ws.on('open', () => ws.send(JSON.stringify({ type: 'hello', role: 'observer', client_id: 'a4-ws' })));
+        ws.on('message', (data) => {
+            try {
+                const frame = JSON.parse(data.toString('utf8'));
+                if (frame['type'] === 'welcome') {
+                    clearTimeout(timer);
+                    ws.close();
+                    resolveWelcome(frame);
+                }
+            }
+            catch {
+                /* not a JSON frame — ignore */
+            }
+        });
+        ws.on('error', (err) => {
+            clearTimeout(timer);
+            rejectWelcome(err);
+        });
+    });
+    // Compare the SNAPSHOT field only (role differs controller/observer between the
+    // two connections; the reconstructed snapshot of an idle broker is stable).
+    assert.equal(JSON.stringify(wsWelcome.snapshot), JSON.stringify(direct.welcome.snapshot), 'WS welcome.snapshot is byte-identical to the direct ViewSocketClient snapshot');
+    direct.close();
+});
+test('A4b: ?revive=0 on a dormant node refuses 409 without launching a broker', async () => {
+    const root = h.spawnRoot('a4b root');
+    // A dormant row: no live broker, no pi_pid, view.sock absent.
+    const dorm = h.fabricateBrokerNode({ parent: root, status: 'active', pi_pid: null });
+    const bootsBefore = h.bootCount(dorm);
+    const status = await new Promise((resolveStatus, rejectStatus) => {
+        const ws = new WebSocket(`ws+unix://${sockPath}:/v1/nodes/${dorm}/attach?revive=0`);
+        const timer = setTimeout(() => {
+            ws.terminate();
+            rejectStatus(new Error('timed out waiting for the upgrade refusal'));
+        }, 10_000);
+        ws.on('unexpected-response', (_req, res) => {
+            clearTimeout(timer);
+            res.destroy();
+            ws.terminate();
+            resolveStatus(res.statusCode ?? 0);
+        });
+        ws.on('open', () => {
+            clearTimeout(timer);
+            ws.close();
+            rejectStatus(new Error('upgrade unexpectedly succeeded for a dormant node'));
+        });
+        ws.on('error', () => {
+            /* the refusal surfaces via unexpected-response; the trailing error is expected */
+        });
+    });
+    assert.equal(status, 409, 'dormant + ?revive=0 → HTTP 409 refusal');
+    assert.equal(h.bootCount(dorm), bootsBefore, 'no broker was launched (boot count unchanged)');
+    assert.equal(h.node(dorm)?.pi_pid ?? null, null, 'no pid recorded — the node stayed dormant');
+});
+// ---------------------------------------------------------------------------
+// A5 — POST .../close tears down the broker + cascades per edges
+// ---------------------------------------------------------------------------
+test('A5: close tears down the target broker and cascades its subtree, leaving the ancestor untouched', async () => {
+    const A = h.spawnRoot('a5 root');
+    const B = (await client.createNode({ kind: 'developer', parent: A, prompt: 'a5 mid' })).node_id;
+    await h.awaitBoot(B);
+    const C = (await client.createNode({ kind: 'developer', parent: B, prompt: 'a5 leaf' })).node_id;
+    await h.awaitBoot(C);
+    // Non-empty sessions → close leaves revivable 'canceled' husks (not reaped).
+    for (const id of [B, C]) {
+        const sessionFile = h.node(id)?.pi_session_file;
+        assert.ok(sessionFile != null, `${id} has a session file`);
+        seedAssistantSession(sessionFile);
+    }
+    const result = await client.closeNode(B);
+    assert.equal(result.root, B, 'close result names B as the cascade root');
+    assert.deepEqual([...result.closed].sort(), [B, C].sort(), 'B and its child C are the closed set');
+    assert.deepEqual(result.spared, [], 'nothing spared');
+    // Broker engines for B and C are torn down (pid gone / not alive).
+    for (const id of [B, C]) {
+        await h.waitFor(() => {
+            const pid = h.node(id)?.pi_pid ?? null;
+            return pid === null || !isPidAlive(pid);
+        }, { label: `${id} broker torn down by close`, timeoutMs: 20_000 });
+    }
+    assert.equal(h.node(B)?.status, 'canceled', 'B is canceled');
+    assert.equal(h.node(C)?.status, 'canceled', 'cascaded child C is canceled');
+    assert.equal(h.node(A)?.status, 'active', 'ancestor A is untouched (still active)');
+});
+// ---------------------------------------------------------------------------
+// A6 — PUT /profiles/{name} idempotent; PUT /model-auth/{provider} writes
+//      auth.json (sandboxed PI_CODING_AGENT_DIR).
+//      HONEST PROXY: reload fan is asserted as the file write only (the mtime
+//      watcher lives in runDaemon, not createApiServer).
+// ---------------------------------------------------------------------------
+test('A6a: PUT /profiles/{name} is idempotent (twice → same profile id)', async () => {
+    // Profiles write under `join(homedir(), '.crouter', 'profiles')` — homedir()
+    // honors HOME, which the harness only overrides for SUBPROCESS children. For
+    // our in-process handler calls, isolate HOME to the harness's agentHome.
+    const savedHome = process.env['HOME'];
+    process.env['HOME'] = h.agentHome;
+    try {
+        const p1 = await client.ensureProfile('a6prof');
+        const p2 = await client.ensureProfile('a6prof');
+        assert.ok(p1.id && p1.id !== '', 'profile has a stable id');
+        assert.equal(p2.id, p1.id, 'a re-PUT of the same name returns the same profile id (idempotent)');
+        assert.equal(p2.name, 'a6prof', 'profile name round-trips');
+    }
+    finally {
+        if (savedHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = savedHome;
+    }
+});
+test('A6b: PUT /model-auth/{provider} writes auth.json (reload fan asserted as file write — honest proxy)', async () => {
+    // Sandbox pi's credential store so the write lands in a throwaway dir, never
+    // the developer's real ~/.pi/agent/auth.json.
+    const savedPiDir = process.env['PI_CODING_AGENT_DIR'];
+    const piDir = mkdtempSync(join(tmpdir(), 'crtr-apisrv-pi-'));
+    process.env['PI_CODING_AGENT_DIR'] = piDir;
+    try {
+        const res = await client.installCredential('anthropic', { kind: 'api_key', api_key: 'sk-test-xyz' });
+        assert.equal(res.installed, true, 'credential reports installed');
+        assert.equal(res.managed, false, 'api_key install is not a managed-pool account');
+        const authFile = join(piDir, 'auth.json');
+        assert.ok(existsSync(authFile), 'auth.json was written to the sandboxed PI_CODING_AGENT_DIR');
+        const contents = readFileSync(authFile, 'utf8');
+        assert.ok(contents.includes('sk-test-xyz') || contents.includes('anthropic'), 'auth.json carries the installed credential material');
+        // HONEST PROXY: the `reload_auth` fan is driven by crtrd's runDaemon() mtime
+        // watcher, not createApiServer(); with the server run in-process that watcher
+        // is inactive, so we assert only the durable file write (plan's sanctioned
+        // substitution).
+    }
+    finally {
+        if (savedPiDir === undefined)
+            delete process.env['PI_CODING_AGENT_DIR'];
+        else
+            process.env['PI_CODING_AGENT_DIR'] = savedPiDir;
+        rmSync(piDir, { recursive: true, force: true });
+    }
+});
+// ---------------------------------------------------------------------------
+// /v1/files/peek — host file read (capped → `truncated`), plus the
+// usage/relative/404 error mapping. Covers the handler's non-trivial
+// branching (usage / notFound / directory / truncation boundary).
+// ---------------------------------------------------------------------------
+const PEEK_CAP = 512 * 1024; // MUST mirror PEEK_MAX_BYTES in handlers/files.ts
+test('files/peek: 200 returns full content, untruncated, for a small file', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-peek-'));
+    try {
+        const file = join(dir, 'hello.txt');
+        writeFileSync(file, 'peek me');
+        const res = await client.peekFile(file);
+        assert.equal(res.path, file, 'echoes the absolute path back');
+        assert.equal(res.content, 'peek me', 'returns the full file content');
+        assert.equal(res.truncated, false, 'a small file is not flagged truncated');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('files/peek: truncation boundary — exactly at cap is whole; one byte over truncates', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-peek-'));
+    try {
+        // Exactly at the cap: read min(size,cap)+1 yields bytesRead === cap, so NOT
+        // flagged truncated, and the full content is returned.
+        const atCap = join(dir, 'at-cap.bin');
+        writeFileSync(atCap, 'a'.repeat(PEEK_CAP));
+        const atRes = await client.peekFile(atCap);
+        assert.equal(atRes.truncated, false, 'a file exactly at the cap is not truncated');
+        assert.equal(atRes.content.length, PEEK_CAP, 'full content returned at the cap');
+        // One byte over: bytesRead === cap+1 > cap ⇒ truncated, content clipped to cap.
+        const overCap = join(dir, 'over-cap.bin');
+        writeFileSync(overCap, 'a'.repeat(PEEK_CAP + 1));
+        const overRes = await client.peekFile(overCap);
+        assert.equal(overRes.truncated, true, 'bytesRead > cap ⇒ truncated:true');
+        assert.equal(overRes.content.length, PEEK_CAP, 'content is clipped to exactly the cap');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('files/peek: 400-usage (missing + relative) and 404 error mapping', async () => {
+    await assert.rejects(client.peekFile(''), (e) => e instanceof ApiError && e.status === 400 && e.code === 'usage', 'missing path → 400 usage');
+    await assert.rejects(client.peekFile('relative/not/absolute.txt'), (e) => e instanceof ApiError && e.status === 400 && e.code === 'usage', 'relative path → 400 usage');
+    await assert.rejects(client.peekFile(join(tmpdir(), 'crtr-peek-does-not-exist-xyz', 'nope.txt')), (e) => e instanceof ApiError && e.status === 404 && e.code === 'not_found', 'nonexistent absolute path → 404 not_found');
+});
+// ---------------------------------------------------------------------------
+// A7 — emitted dist/api/index.js require-graph reaches zero dist/core/* /
+//      dist/clients/*. Static assertion against the EMITTED output — requires a
+//      prior `npm run build`.
+// ---------------------------------------------------------------------------
+test('A7: emitted dist/api/index.js import graph reaches no dist/core/* or dist/clients/*', () => {
+    const ROOT = fileURLToPath(new URL('../../../../../', import.meta.url)); // repo root
+    const entry = join(ROOT, 'dist', 'api', 'index.js');
+    if (!existsSync(entry)) {
+        assert.fail(`dist/api/index.js is missing — run \`npm run build\` before this test (A7 checks emitted output)`);
+    }
+    // Walk the transitive graph over LOCAL relative imports/exports only. Node
+    // built-ins and bare-specifier deps are irrelevant to the CLI/core purity
+    // boundary; any reach into dist/core or dist/clients would surface as a
+    // relative `../core/...` / `../clients/...` specifier resolving into those
+    // trees.
+    const spec = /(?:from|import)\s*['"](\.[^'"]+)['"]/g;
+    const seen = new Set();
+    const stack = [entry];
+    while (stack.length > 0) {
+        const file = stack.pop();
+        if (seen.has(file))
+            continue;
+        seen.add(file);
+        let src;
+        try {
+            src = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue; // a .d.ts-only or absent sibling — not part of the runtime graph
+        }
+        for (let m = spec.exec(src); m !== null; m = spec.exec(src)) {
+            stack.push(resolve(dirname(file), m[1]));
+        }
+    }
+    const leaks = [...seen].filter((f) => f.includes('/dist/core/') || f.includes('/dist/clients/'));
+    assert.deepEqual(leaks, [], `dist/api must not reach dist/core/* or dist/clients/* — leaked into:\n${leaks.join('\n')}`);
+    assert.ok(seen.size > 1, 'the graph walk actually followed dist/api imports (sanity)');
+});

package/dist/daemon/api/__tests__/full/b10-attach-modelauth.test.d.ts

@@ -0,0 +1 @@
+export {};