@north-light/crouter 0.3.154

package/dist/clients/web/web-client/shared/protocol.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Shared wire types for the crouter web client/server split.
+ *
+ * The SPA imports the pi payload types it needs from this module — never from
+ * broker-protocol internals. The type-only re-exports below keep the web
+ * package's shared payload shapes in one place.
+ */
+export type { UserMessage, AssistantMessage, ToolResultMessage, TextContent, ToolCall, ImageContent, } from '@earendil-works/pi-ai';
+export type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+export type { RpcExtensionUIRequest, RpcExtensionUIResponse, RpcSessionState, } from '@earendil-works/pi-coding-agent';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { RpcSessionState } from '@earendil-works/pi-coding-agent';
+import type { DeterministicCommandExpansion } from '../../../../core/runtime/command-expansion.js';
+/**
+ * An `AgentMessage` enriched with a client-side origin tag.
+ * Only `role:'user'` messages can carry `origin:'inbox'`; all others leave
+ * `origin` undefined. `'human'` is reserved for future explicit human-origin
+ * tagging (currently unset — absence means human by default).
+ *
+ * Defined as an intersection (not `interface extends`) because `AgentMessage`
+ * is a union type and TypeScript does not allow extending unions.
+ */
+export type FoldedMessage = AgentMessage & {
+    /** Set to `'inbox'` when this user message is recognized as injected by the
+     *  canvas-inbox-watcher extension (a coalesced inbox digest). */
+    origin?: 'inbox' | 'human';
+};
+/** base session vs orchestrator. */
+export type NodeMode = 'base' | 'orchestrator';
+/** terminal (reaps when done) vs resident (root) node. */
+export type NodeLifecycle = 'terminal' | 'resident';
+/** Canvas lifecycle status. */
+export type NodeLifeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** broker-hosted (enterable) vs tmux-pane (shown, non-enterable). */
+export type HostKind = 'broker' | 'tmux';
+/** One row from `crtr canvas snapshot --json` — node identity + runtime, no chrome. */
+export interface NodeSummary {
+    node_id: string;
+    name: string;
+    /** Node kind (developer/explore/…) — open set. */
+    kind: string;
+    mode: NodeMode;
+    lifecycle: NodeLifecycle;
+    status: NodeLifeStatus;
+    cwd: string;
+    /** Spine parent node id, or null for a root. */
+    parent: string | null;
+    /** ISO-8601 creation timestamp. */
+    created: string;
+    host_kind: HostKind;
+    /** True iff `host_kind === 'broker'` (the web UI can open a live session). */
+    enterable: boolean;
+    /** Count of pending human asks (blocked-on-human indicator). */
+    attention_count: number;
+    /** Canvas cycle count for this node (revive/yield generations). Optional for
+     *  back-compat with snapshots produced before the field existed. */
+    cycles?: number;
+    /** ISO-8601 of the node's most recent work (session activity), distinct from
+     *  `created`. Optional/back-compat; falls back to `created` when absent. */
+    last_activity?: string;
+}
+/** input/output token burn, with cache reads where the provider reports them. */
+export interface TokenBurn {
+    input: number;
+    output: number;
+    cache?: number;
+}
+/** Live context-window usage. */
+export interface ContextUsage {
+    tokens: number;
+    window: number;
+    percent: number;
+}
+/** Coarse session stats for chrome (distinct from pi's full `SessionStats`). */
+export interface SessionStatsSummary {
+    turns: number;
+    user_messages: number;
+    assistant_messages: number;
+    cost?: number;
+}
+/** Viewer presence for a node — a truthful count of attached views. There is
+ *  no owner: every live interactive view is writable at the same time. */
+export interface Presence {
+    viewers: number;
+}
+/** Git working-tree change counts for the meta strip. */
+export interface GitStatus {
+    added: number;
+    modified: number;
+    deleted: number;
+    untracked: number;
+}
+/** `crtr node inspect show --json`'s node payload — `NodeSummary` plus the per-node chrome. */
+export interface NodeDetail extends NodeSummary {
+    branch: string | null;
+    model: string | null;
+    tokens: TokenBurn | null;
+    context: ContextUsage | null;
+    tool_calls: number | null;
+    stats: SessionStatsSummary | null;
+    presence: Presence | null;
+    /** True while a broker is live; false for a dormant (last-known) view. */
+    live: boolean;
+    /** Working-tree change counts for the meta strip (null when unavailable). */
+    git_status?: GitStatus | null;
+}
+/** A slash command in a node's palette (from the broker `get_commands` reply). */
+export interface Command {
+    name: string;
+    description: string;
+    source: 'builtin' | 'command' | 'template';
+    location?: 'user' | 'project' | 'path';
+    path?: string;
+    argument_hint?: string;
+    /** Raw file-template body used to disclose the exact expanded prompt before submission. */
+    template?: string;
+    /** Deterministic extension-command prompt expansion; absent for immediate UI,
+     * dynamic, and side-effect commands. */
+    expansion?: DeterministicCommandExpansion;
+}
+/** Metadata for one resolvable inline memory reference (design: inline memory
+ *  references). Hand-mirrored field-for-field from `RefMeta` in
+ *  `core/runtime/broker-protocol.ts` rather than imported — this module stays
+ *  free of any dependency on broker-protocol so it can be shared by both the
+ *  browser bundle and server-side code (browser convention, D11). `name` is
+ *  the canonical name a token resolves to and what `crtr memory read <name>`
+ *  expects; `scope` is the winning scope after precedence dedup (display
+ *  only). Metadata only — no document body or source path. */
+export interface RefMeta {
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+}
+/** `crtr canvas snapshot --json` body. */
+export interface CanvasSnapshot {
+    nodes: NodeSummary[];
+    /** ISO-8601. */
+    generated_at: string;
+}
+/** `crtr node new --json` success. */
+export interface SpawnResponse {
+    node_id: string;
+    name: string;
+    window?: string;
+    session?: string;
+    status: string;
+    follow_up: string;
+}
+/** `crtr node message send --json` success. */
+export interface MessageResponse {
+    mode: string;
+    armed: boolean;
+    target: string;
+    delivered?: boolean;
+    revived?: boolean;
+    guidance: string;
+}
+/** `crtr node lifecycle revive --json` success. */
+export interface ReviveResponse {
+    window: null;
+    session: string | null;
+    resumed: boolean;
+    ready: boolean;
+}
+/** `crtr node lifecycle close --json` success. */
+export interface CloseResponse {
+    closed: boolean;
+    node_id: string;
+    count: number;
+    closed_ids: string[];
+    spared: string[];
+}
+/** `crtr node new` body. Always headless; `root` toggles a resident node. */
+export interface SpawnRequest {
+    prompt: string;
+    kind: string;
+    mode?: NodeMode;
+    root?: boolean;
+    cwd?: string;
+    name?: string;
+    model?: string;
+    parent?: string;
+}
+/** `crtr node message send` body. */
+export interface MessageRequest {
+    body: string;
+    tier?: string;
+}
+/** `crtr node lifecycle revive` body. */
+export interface ReviveRequest {
+    fresh?: boolean;
+}
+/**
+ * The five resolution flows (design §5.2). humanloop's `InteractionKind` also
+ * has `review`; the deck loader normalizes it (and any unknown/absent kind)
+ * onto one of these five so a deck always renders through a known flow.
+ */
+export type DeckKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
+/** One option of a decision/validation interaction (humanloop InteractionOption). */
+export interface DeckOption {
+    id: string;
+    label: string;
+    /** The option's consequence/explanation (humanloop `description`). */
+    description?: string;
+}
+/** One interaction within a deck (humanloop Interaction, normalized for the web). */
+export interface DeckInteraction {
+    id: string;
+    title: string;
+    subtitle: string;
+    /** Markdown body (bodyPath already inlined by `crtr human deck`). */
+    body?: string;
+    kind: DeckKind;
+    options: DeckOption[];
+    multiSelect: boolean;
+    allowFreetext: boolean;
+    freetextLabel?: string;
+}
+/**
+ * A pending ask, ranked in the inbox list (design §5.2). Provenance carries
+ * private node routing and an optional authored source label for presentation.
+ */
+export interface DeckSummary {
+    /** Opaque, stable inbox-entry id (base64url of the interaction dir). */
+    id: string;
+    /** The interaction job id (basename of the interaction dir). */
+    job_id: string;
+    /** The first interaction's kind — the glyph + flow for the row. */
+    kind: DeckKind;
+    title: string;
+    subtitle: string;
+    /** ISO-8601 — when the ask started blocking (drives the wait duration + rank). */
+    blocked_since: string;
+    /** Humanloop's current claim owner, when a person/session is handling it. */
+    claim_owner?: string;
+    /** Authored display label: source sessionName, then askedBy. */
+    source_label?: string;
+    /** The conversation (spine root) this ask belongs to. */
+    conversation_id: string;
+    conversation_title: string;
+    /** The node that raised the ask. */
+    asking_node_id: string;
+    asking_node_name: string;
+    /** The asking node's cwd — sub-DAG scoping. */
+    cwd: string;
+    /** How many interactions the deck holds (a multi-question deck). */
+    interaction_count: number;
+}
+/** The full deck for a resolution flow (`crtr human deck <id> --json`). */
+export interface DeckDetail extends DeckSummary {
+    interactions: DeckInteraction[];
+}
+/** One interaction's answer (humanloop InteractionResponse). */
+export interface DeckAnswer {
+    id: string;
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    optionComments?: Record<string, string>;
+}
+/** `crtr human resolve <id> --json` body. */
+export interface ResolveDeckRequest {
+    responses: DeckAnswer[];
+}
+/** `crtr human resolve <id> --json` success. */
+export interface ResolveDeckResponse {
+    resolved: true;
+    job_id: string;
+    delivered: boolean;
+}
+/**
+ * Engine state carried in `snapshot.state` — pi's OWN `get_state` payload, not a
+ * mirror of it. `BrokerSnapshot['state']` is this same type, so the welcome frame
+ * passes through the SPA untranslated. The SPA's streaming/idle indicator reads
+ * `isStreaming` (spec C.10).
+ */
+export type SessionState = RpcSessionState;
+/** Fixed capability of one browser tab's session connection, stated by the
+ *  broker's `welcome`: `controller` is writable, `observer` is read-only. It is
+ *  a per-client capability, never ownership of a shared slot. */
+export type WebRole = 'observer' | 'controller';
+/** Upstream broker connectivity, surfaced to the tab (spec §6.2). */
+export type BrokerStatus = 'connected' | 'reconnecting' | 'down' | 'revived';
+/** Response payload to an extension dialog (`RpcExtensionUIResponse` minus id/type). */
+export type DialogResponseValue = {
+    value: string;
+} | {
+    confirmed: boolean;
+} | {
+    cancelled: true;
+};
+/**
+ * A typed content block within a view tab. Discriminated union of three
+ * block kinds: inline/sourced markdown, a KPI grid, and a bar-list chart.
+ */
+export type ViewBlock = {
+    kind: 'markdown';
+    source: {
+        node_id: string;
+        path: string;
+    } | {
+        inline: string;
+    };
+} | {
+    kind: 'kpis';
+    items: {
+        label: string;
+        value: string;
+        unit?: string;
+        sub?: string;
+    }[];
+} | {
+    kind: 'barlist';
+    title: string;
+    rows: {
+        label: string;
+        value: number;
+        max?: number;
+        note?: string;
+    }[];
+};

package/dist/clients/web/web-client/shared/protocol.js

@@ -0,0 +1,8 @@
+/**
+ * Shared wire types for the crouter web client/server split.
+ *
+ * The SPA imports the pi payload types it needs from this module — never from
+ * broker-protocol internals. The type-only re-exports below keep the web
+ * package's shared payload shapes in one place.
+ */
+export {};

package/dist/clients/web/web-cmd.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare function registerWeb(): BranchDef;

package/dist/clients/web/web-cmd.js

@@ -0,0 +1,141 @@
+// web-cmd.ts — the `crtr surface web` command leaf + registration.
+//
+// Starts the ONE long-running web dev shell (server.ts): a thin reverse proxy in
+// front of crtrd (spec §7.5). It serves the shell SPA, reverse-proxies the crtrd
+// REST API (`/v1/*`) and the attach WS upgrade (`ws://HOST:PORT/node/<id>` →
+// crtrd's `GET /v1/nodes/{id}/attach`) to crtrd's unix socket, plus the SSE
+// change lane (GET /__crtr/events) and web-push endpoints. It hosts NO canvas
+// writer — crtrd is the sole writer; the browser becomes the SAME protocol peer
+// as surface attach. The node is selected by the URL, so there is NO positional
+// node here.
+//
+// Command shape (plan §3.6): the CLI path-walker forbids a flat top-level leaf
+// (`defineRoot.subtrees` is `BranchDef[]`), so `web` is a BRANCH wrapping a
+// single leaf: `crtr surface web serve`.
+import { spawn } from 'node:child_process';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { startWebServer } from './server.js';
+const DEFAULT_PORT = 7878;
+/** Best-effort open of the default browser to `url` (the `--open` flag). Never
+ *  throws — a failed open just leaves the user to click the printed URL. */
+function openBrowser(url) {
+    const platform = process.platform;
+    const [cmd, args] = platform === 'darwin'
+        ? ['open', [url]]
+        : platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            /* no browser opener available — the printed URL is the fallback */
+        });
+        child.unref();
+    }
+    catch {
+        /* ignore */
+    }
+}
+const webServeLeaf = defineLeaf({
+    name: 'serve',
+    description: 'start the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
+    whenToUse: 'you want the crouter web UI in a browser instead of a tmux pane — watching the canvas and driving headless nodes from a page rather than a terminal surface. It is a dev shell that reverse-proxies crtrd (the API and the attach WS); crtrd must be running. Binds 127.0.0.1 by default; pass --host to bind elsewhere, in which case --token is required so the page can authorize. Pass --dev only if you are iterating on the shell itself (Vite HMR) rather than just running it. The node is picked in the browser via the URL, not on the command line; the server runs until ctrl+c.',
+    help: {
+        name: 'web serve',
+        summary: 'start the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
+        params: [
+            {
+                kind: 'flag',
+                name: 'port',
+                type: 'int',
+                required: false,
+                default: DEFAULT_PORT,
+                constraint: `TCP port to bind on 127.0.0.1. Default ${DEFAULT_PORT}.`,
+            },
+            {
+                kind: 'flag',
+                name: 'host',
+                type: 'string',
+                required: false,
+                default: '127.0.0.1',
+                constraint: 'TCP host to bind. Default 127.0.0.1. Non-loopback binds require --token.',
+            },
+            {
+                kind: 'flag',
+                name: 'token',
+                type: 'string',
+                required: false,
+                constraint: 'Bearer token for remote-capable proxy, SSE, and attach relay requests. Required for non-loopback binds.',
+            },
+            {
+                kind: 'flag',
+                name: 'open',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Auto-open the default browser to the served URL after the server starts.',
+            },
+            {
+                kind: 'flag',
+                name: 'dev',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Serve shell assets via a Vite dev server (middleware mode, HMR) instead of the prebuilt dist/web-client/ bundle. For contributors iterating on the shell or a builtin view. The bridge, SSE lane, and WS relay are identical in both modes.',
+            },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Binds a long-running HTTP+WebSocket server on the requested host and port and keeps serving until interrupted (ctrl+c / SIGTERM). Safe to run non-interactively (daemon-like): it prints the URL and serves.',
+            'Serves the shell SPA (static dist/web-client/, or Vite middleware under --dev), reverse-proxies the crtrd REST API (/v1/*) to crtrd\'s unix socket, streams the GET /__crtr/events SSE change lane, and on a browser ws://HOST:<port>/node/<id> connection tunnels the WS upgrade to crtrd\'s GET /v1/nodes/<id>/attach, relaying bytes VERBATIM both directions. Non-loopback binds require a token so the remote route is not an unauthenticated surface.',
+            'This process hosts NO canvas writer: it opens no canvas.db and spawns no bridge subprocess. Every write and every canvas read flows to crtrd (the sole writer) through the proxy and the attach tunnel; crtrd owns attach-implies-revive. crtrd must be running.',
+        ],
+    },
+    run: async (input) => {
+        const port = input['port'] ?? DEFAULT_PORT;
+        const host = input['host'] ?? '127.0.0.1';
+        const tokenRaw = input['token'];
+        const token = tokenRaw !== undefined && tokenRaw !== '' ? tokenRaw : undefined;
+        const open = input['open'] ?? false;
+        const dev = input['dev'] ?? false;
+        const server = await startWebServer({ port, host, token, dev });
+        const nodeUrlShape = `${server.url}/node/<id>`;
+        const browserUrl = token !== undefined ? `${server.url}?token=${encodeURIComponent(token)}` : server.url;
+        process.stdout.write(`crtr surface web serving on ${server.url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
+            `  open a node:  ${nodeUrlShape}\n` +
+            `  api proxy:    ${server.url}/v1/* → crtrd\n` +
+            `  events (SSE): GET  ${server.url}/__crtr/events\n` +
+            `  shell assets: ${dev ? 'Vite middleware (HMR)' : server.clientDir}\n` +
+            `  (ctrl+c to stop)\n`);
+        if (open)
+            openBrowser(browserUrl);
+        // Long-running: resolve only on a shutdown signal, tearing down cleanly.
+        await new Promise((resolveShutdown) => {
+            const shutdown = () => {
+                void server.close().then(() => resolveShutdown());
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+            process.once('SIGHUP', shutdown);
+        });
+        return;
+    },
+    render: () => '',
+});
+export function registerWeb() {
+    return defineBranch({
+        name: 'web',
+        rootEntry: {
+            concept: 'the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
+            desc: 'serve the crouter web UI for the canvas and headless nodes',
+            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes from a page. Binds 127.0.0.1 by default; a non-loopback bind requires a token so the page can authorize. The node is selected in the browser via the URL, not on the command line.',
+        },
+        help: {
+            name: 'web',
+            summary: 'serve the crouter web UI — the browser alternative to a tmux pane for the canvas and headless nodes',
+            model: 'The branch is a long-running browser surface, an alternative to a tmux pane. `serve` binds a host and port (loopback by default; --token required off-loopback) and runs until interrupted. The node is chosen in the browser via the URL, not on the command line; the server itself only hosts the surface and never spawns an engine.',
+        },
+        children: [webServeLeaf],
+    });
+}

package/dist/commands/__tests__/api-client-cold-start-diagnostic.test.d.ts

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

package/dist/commands/__tests__/api-client-cold-start-diagnostic.test.js

@@ -0,0 +1,96 @@
+// api-client-cold-start-diagnostic.test.ts — regression for issue #516:
+// `node inspect list`/etc used to surface a bare `daemon_unavailable` on a
+// cold-start timeout, discarding the real cause. `readColdStartDiagnostic`
+// (`../api-client.ts`) is what `cliClient()` wires into `CrtrClient` as
+// `coldStartDiagnostic` — this proves it reads a BOUNDED tail of crtrd.err
+// (never the whole file) and degrades to `undefined` (not a throw) when the
+// log is missing. The two tests below prove the READ itself is bounded (not
+// just the returned string) — the prior implementation `readFileSync`'d the
+// whole append-only log before slicing, which allocates/blocks unboundedly on
+// a runaway log. Node ESM snapshots named imports of builtins at load time
+// (mocking `node:fs` per-call does not reach `api-client.ts`'s own import
+// binding), so both tests exercise real I/O instead of spying on it: one
+// proves the read stays fast/cheap against a huge (sparse) file, the other
+// proves the byte offset the read starts from is exact.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { closeSync, ftruncateSync, mkdtempSync, openSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { COLD_START_DIAGNOSTIC_TAIL_BYTES, readColdStartDiagnostic } from '../api-client.js';
+let home;
+let previousHome;
+before(() => {
+    previousHome = process.env.CRTR_HOME;
+    home = mkdtempSync('/tmp/crtr-cold-start-diag-');
+    process.env.CRTR_HOME = home;
+});
+after(() => {
+    if (previousHome === undefined)
+        delete process.env.CRTR_HOME;
+    else
+        process.env.CRTR_HOME = previousHome;
+    rmSync(home, { recursive: true, force: true });
+});
+test('returns undefined when crtrd.err does not exist', () => {
+    assert.equal(readColdStartDiagnostic(), undefined);
+});
+test('returns undefined for an empty/whitespace-only crtrd.err', () => {
+    writeFileSync(join(home, 'crtrd.err'), '   \n\n  \n');
+    assert.equal(readColdStartDiagnostic(), undefined);
+});
+test('surfaces the tail of a real startup failure', () => {
+    writeFileSync(join(home, 'crtrd.err'), 'Error: listen EADDRINUSE: address already in use :::0\n');
+    const diagnostic = readColdStartDiagnostic();
+    assert.match(diagnostic ?? '', /EADDRINUSE/);
+});
+test('bounds the tail instead of leaking the whole log', () => {
+    const lines = Array.from({ length: 5_000 }, (_, i) => `line ${i}: ${'x'.repeat(80)}`);
+    writeFileSync(join(home, 'crtrd.err'), lines.join('\n'));
+    const diagnostic = readColdStartDiagnostic();
+    assert.ok(diagnostic !== undefined);
+    // Bounded on both axes: never the full 5,000-line log, and never unbounded bytes.
+    assert.ok(diagnostic.split('\n').length <= 21, 'at most 20 content lines plus the header');
+    assert.ok(diagnostic.length < 5_000, 'bounded well under the full log size');
+    // The tail keeps the MOST RECENT lines (the ones useful for a just-failed start).
+    assert.match(diagnostic, /line 4999/);
+    assert.doesNotMatch(diagnostic, /line 0:/);
+});
+test('bounds the READ itself — stays fast/cheap against a huge sparse log instead of materializing it whole', () => {
+    // A sparse 400MB file: `ftruncateSync` sets the logical size instantly
+    // without writing 400MB of real content, so creating it is cheap, but a
+    // `readFileSync` of the whole file would still have to MATERIALIZE all
+    // 400MB into a JS string — measurably (100ms+) slower than a bounded tail
+    // read (sub-millisecond). The marker sits inside the final
+    // `COLD_START_DIAGNOSTIC_TAIL_BYTES` so a correctly bounded read still
+    // surfaces it.
+    const path = join(home, 'crtrd.err');
+    const size = 400 * 1024 * 1024;
+    const marker = 'Error: EADDRINUSE (huge-log marker)\n';
+    const fd = openSync(path, 'w');
+    ftruncateSync(fd, size);
+    writeSync(fd, Buffer.from(marker), 0, marker.length, size - 200);
+    closeSync(fd);
+    const startedAt = performance.now();
+    const diagnostic = readColdStartDiagnostic();
+    const elapsedMs = performance.now() - startedAt;
+    assert.match(diagnostic ?? '', /EADDRINUSE \(huge-log marker\)/);
+    // A bounded 4KB read finishes in low single-digit ms; a whole-file
+    // `readFileSync` of 400MB measured ~150-175ms locally (and scales with log
+    // size, which is exactly the unbounded-resource bug) — 100ms leaves ample
+    // margin above the bounded read and below the whole-file read even on a
+    // slower CI runner.
+    assert.ok(elapsedMs < 100, `expected a bounded read well under 100ms, took ${elapsedMs.toFixed(2)}ms`);
+});
+test('bounds the READ itself — the tail window starts at an exact byte offset, not an in-memory slice', () => {
+    // Bytes immediately BEFORE the tail window must never be read at all, not
+    // just excluded from the output — place a sentinel there and one at the
+    // very start of the window, and prove only the latter survives.
+    const beforeSentinel = 'BEFORE-WINDOW-SENTINEL';
+    const afterSentinel = 'AFTER-WINDOW-SENTINEL';
+    const prefixFiller = 'p'.repeat(50_000 - beforeSentinel.length);
+    const tailFiller = 'q'.repeat(COLD_START_DIAGNOSTIC_TAIL_BYTES - afterSentinel.length);
+    writeFileSync(join(home, 'crtrd.err'), prefixFiller + beforeSentinel + afterSentinel + tailFiller);
+    const diagnostic = readColdStartDiagnostic() ?? '';
+    assert.match(diagnostic, /AFTER-WINDOW-SENTINEL/);
+    assert.doesNotMatch(diagnostic, /BEFORE-WINDOW-SENTINEL/);
+});

package/dist/commands/__tests__/canvas-config.test.d.ts

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