@crouton-kit/crouter 0.3.66 → 0.3.67

package/dist/core/canvas/render.js

@@ -15,6 +15,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
 import { jobDir, contextDir } from './paths.js';
 import { countAsks, asksForNodes } from './attention.js';
@@ -174,25 +175,24 @@ export function renderForest() {
     }
     return parts.join('\n\n');
 }
-async function nodeLineFromSource(source, nodeId, indent, connector) {
+async function nodeLineFromSource(source, nodeId, indent, connector, remote) {
     const node = await source.getNode(nodeId);
     if (node === null)
         return `${indent}${connector}? <missing meta: ${nodeId}>`;
-    const hanging = hangingFor(node);
+    const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
-    const tel = readNodeTelemetry(nodeId);
-    const ctx = fmtCtx(tel.tokens_in);
-    const asks = countAsks(nodeId);
+    const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(nodeId).tokens_in);
+    const asks = remote ? 0 : countAsks(nodeId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
 }
-async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out) {
+async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out, remote) {
     if (visited.has(nodeId))
         return;
     visited.add(nodeId);
     const connector = isLast ? '└─ ' : '├─ ';
-    out.push(await nodeLineFromSource(source, nodeId, indent, connector));
+    out.push(await nodeLineFromSource(source, nodeId, indent, connector, remote));
     const children = await source.subscriptionsOf(nodeId).catch(() => []);
     const childIndent = indent + (isLast ? '   ' : '│  ');
     for (let i = 0; i < children.length; i++) {
@@ -203,18 +203,18 @@ async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out)
             out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
             continue;
         }
-        await walkTreeFromSource(source, child.node_id, childIndent, childIsLast, visited, out);
+        await walkTreeFromSource(source, child.node_id, childIndent, childIsLast, visited, out, remote);
     }
 }
 export async function renderTreeFromSource(source, rootId) {
+    const remote = source instanceof RemoteCanvasSource;
     const node = await source.getNode(rootId);
     if (node === null)
         return `? <missing node: ${rootId}>`;
-    const tel = readNodeTelemetry(rootId);
-    const ctx = fmtCtx(tel.tokens_in);
-    const asks = countAsks(rootId);
+    const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
+    const asks = remote ? 0 : countAsks(rootId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
-    const hanging = hangingFor(node);
+    const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     const out = [];
@@ -224,7 +224,7 @@ export async function renderTreeFromSource(source, rootId) {
     for (let i = 0; i < children.length; i++) {
         const child = children[i];
         const isLast = i === children.length - 1;
-        await walkTreeFromSource(source, child.node_id, '', isLast, visited, out);
+        await walkTreeFromSource(source, child.node_id, '', isLast, visited, out, remote);
     }
     return out.join('\n');
 }
@@ -468,14 +468,16 @@ export function dashboardRows(rootId) {
  *  a deterministic canvas-home path, so it tracks last-message recency without a meta
  *  read. Falls back to `created`'s epoch when a node never ran a turn (no telemetry).
  *  Never throws. */
-function sessionMtime(nodeId, created) {
-    try {
-        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
-        if (st !== undefined)
-            return st.mtimeMs;
-    }
-    catch {
-        /* fall through to created */
+function sessionMtime(nodeId, created, remote = false) {
+    if (!remote) {
+        try {
+            const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+            if (st !== undefined)
+                return st.mtimeMs;
+        }
+        catch {
+            /* fall through to created */
+        }
     }
     const t = Date.parse(created);
     return Number.isNaN(t) ? 0 : t;
@@ -500,11 +502,11 @@ function sessionMtime(nodeId, created) {
  */
 export function dashboardRowsAll() {
     const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
-    return listNodes().map((row) => dashboardRowFromNodeRow(row, focusedNodeIds));
+    return listNodes().map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, false));
 }
-function dashboardRowFromNodeRow(row, focusedNodeIds) {
+function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     const live = row.status === 'active' || row.status === 'idle';
-    const hanging = activeFaultForDisplay(row, readFault(row.node_id));
+    const hanging = remote ? null : activeFaultForDisplay(row, readFault(row.node_id));
     return {
         node_id: row.node_id,
         name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
@@ -516,15 +518,20 @@ function dashboardRowFromNodeRow(row, focusedNodeIds) {
         cwd: row.cwd,
         created: row.created,
         lifecycle: row.lifecycle,
-        mtimeMs: sessionMtime(row.node_id, row.created),
-        streaming: hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
+        mtimeMs: sessionMtime(row.node_id, row.created, remote),
+        streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
         hanging,
-        viewed: focusedNodeIds.has(row.node_id),
+        viewed: remote ? false : focusedNodeIds.has(row.node_id),
     };
 }
+/** A remote source provides only graph structure (the 8 CanvasSource methods);
+ *  every other per-node field below is a local disk/SQLite read and is suppressed
+ *  to a safe default for a remote source — `listFocuses()` (SQLite) is skipped
+ *  entirely rather than queried and discarded. */
 export async function dashboardRowsAllFromSource(source) {
-    const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
-    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds));
+    const remote = source instanceof RemoteCanvasSource;
+    const focusedNodeIds = remote ? new Set() : new Set(listFocuses().map((f) => f.node_id));
+    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
 }
 // ---------------------------------------------------------------------------
 // Lazy enrichment API — fold the expensive per-node reads into rows on demand,
@@ -565,16 +572,23 @@ export function enrichRows(rows) {
         row.enriched = true;
     }
 }
-export async function enrichRowsFromSource(source, rows) {
+/** Telemetry (ctx tokens) is a local disk read, so it is suppressed to 0 for a
+ *  remote source. Ask counts are suppressed to 0 UNLESS the caller supplies
+ *  `remoteAsks` — a pre-fetched `askCountsForView` map (one call per forest
+ *  root; the caller's job, since the right root set is a browse/snapshot
+ *  concern, not this per-row enrichment loop's). See `runBrowse`'s
+ *  `remoteAskCounts`, fetched once per snapshot rebuild, not per flush. */
+export async function enrichRowsFromSource(source, rows, remoteAsks) {
     const todo = rows.filter((r) => r.enriched !== true);
     if (todo.length === 0)
         return;
-    const asks = asksForNodes(todo.map((r) => r.node_id));
+    const remote = source instanceof RemoteCanvasSource;
+    const asks = remote ? (remoteAsks ?? {}) : asksForNodes(todo.map((r) => r.node_id));
     await Promise.all(todo.map(async (row) => {
         const meta = await source.getNode(row.node_id);
         if (meta !== null)
             row.name = fullName(meta);
-        row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
+        row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
         row.asks = asks[row.node_id] ?? 0;
         row.enriched = true;
     }));
@@ -595,14 +609,19 @@ export function loadPreview(row) {
     row.previewLoaded = true;
     return row;
 }
+/** goal (initial-prompt.md) and session parts are local disk reads — suppressed
+ *  to undefined for a remote source. */
 export async function loadPreviewFromSource(source, row) {
     if (row.previewLoaded === true)
         return row;
-    row.goal = readGoalText(row.node_id);
-    const meta = await source.getNode(row.node_id);
-    const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
-    row.prompts = prompts;
-    row.lastAssistant = lastAssistant;
+    const remote = source instanceof RemoteCanvasSource;
+    row.goal = remote ? undefined : readGoalText(row.node_id);
+    if (!remote) {
+        const meta = await source.getNode(row.node_id);
+        const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
+        row.prompts = prompts;
+        row.lastAssistant = lastAssistant;
+    }
     row.previewLoaded = true;
     return row;
 }

package/dist/core/canvas/source.d.ts

@@ -1,4 +1,5 @@
 import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+import type { Scope } from '../../types.js';
 export interface CanvasSource {
     getNode(nodeId: string): Promise<NodeMeta | null>;
     getRow(nodeId: string): Promise<NodeRow | null>;
@@ -24,3 +25,11 @@ export declare class LocalCanvasSource implements CanvasSource {
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }
 export declare const localCanvasSource: CanvasSource;
+/** The active read source for a command: an explicit `--canvas <name>` wins,
+ *  else the durable `crtr canvas use` selection (`ScopeState.activeCanvas`),
+ *  else local — byte-for-byte the same `localCanvasSource` singleton so a
+ *  caller with neither set sees zero behavior change. */
+export declare function resolveCanvasSource(opts?: {
+    canvasName?: string;
+    scope?: Scope;
+}): CanvasSource;

package/dist/core/canvas/source.js

@@ -1,5 +1,8 @@
 import { getNode, getRow, listNodes, subscriptionsOf, subscribersOf, view, hasActiveLiveSubscription, } from './canvas.js';
 import { asksForNodes } from './attention.js';
+import { readState } from '../config.js';
+import { resolveRemoteCanvasTarget } from '../view/remote-canvas-target.js';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
 export class LocalCanvasSource {
     async getNode(nodeId) {
         return getNode(nodeId);
@@ -27,3 +30,15 @@ export class LocalCanvasSource {
     }
 }
 export const localCanvasSource = new LocalCanvasSource();
+/** The active read source for a command: an explicit `--canvas <name>` wins,
+ *  else the durable `crtr canvas use` selection (`ScopeState.activeCanvas`),
+ *  else local — byte-for-byte the same `localCanvasSource` singleton so a
+ *  caller with neither set sees zero behavior change. */
+export function resolveCanvasSource(opts) {
+    const scope = opts?.scope ?? 'user';
+    const name = opts?.canvasName ?? readState(scope).activeCanvas ?? null;
+    if (!name)
+        return localCanvasSource;
+    const { previewEndpoint, relayToken } = resolveRemoteCanvasTarget(name, scope);
+    return new RemoteCanvasSource(previewEndpoint, relayToken);
+}

package/dist/core/config.js

@@ -38,6 +38,7 @@ export function readState(scope) {
         plugins: existing.plugins ?? {},
         last_self_check: existing.last_self_check,
         bootstrap_done: existing.bootstrap_done,
+        activeCanvas: existing.activeCanvas ?? null,
     };
 }
 export function writeConfig(scope, config) {
@@ -245,7 +246,7 @@ function mergeKinds(raw, base = defaultKindsConfig()) {
 }
 /** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
  *  null) rather than throwing — same rule `normalizeKindEntry` follows. A
- *  valid entry needs a non-empty `previewEndpoint` and `relayTokenEnv`; the
+ *  valid entry needs a non-empty `previewEndpoint` and `relayTokenRef`; the
  *  token itself is never stored here (see `RemoteCanvasTarget`). */
 function normalizeRemoteCanvasTarget(raw) {
     if (raw === null || typeof raw !== 'object')
@@ -253,9 +254,9 @@ function normalizeRemoteCanvasTarget(raw) {
     const r = raw;
     if (typeof r.previewEndpoint !== 'string' || r.previewEndpoint.trim() === '')
         return null;
-    if (typeof r.relayTokenEnv !== 'string' || r.relayTokenEnv.trim() === '')
+    if (typeof r.relayTokenRef !== 'string' || r.relayTokenRef.trim() === '')
         return null;
-    const out = { previewEndpoint: r.previewEndpoint, relayTokenEnv: r.relayTokenEnv };
+    const out = { previewEndpoint: r.previewEndpoint, relayTokenRef: r.relayTokenRef };
     if (typeof r.cpOrigin === 'string' && r.cpOrigin.trim() !== '')
         out.cpOrigin = r.cpOrigin;
     return out;

package/dist/core/runtime/__tests__/node-env.test.d.ts

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

package/dist/core/runtime/__tests__/node-env.test.js

@@ -0,0 +1,91 @@
+// Run with: node --import tsx/esm --test src/core/runtime/__tests__/node-env.test.ts
+//
+// Regression lock for the 0.3.62 roll regression: `nodeEnv()` (`../nodes.ts`)
+// is the ONLY place a broker child's deployment-layout path overrides
+// (CRTR_SOCK_DIR, CRTR_CANVAS_DB — siblings of CRTR_HOME in paths.ts) get from
+// ambient process.env into `inv.env`, the TRUSTED overlay `buildBrokerEnv`
+// applies on top of the default-deny spawn-env allowlist (spawn-env.ts, which
+// admits no ambient `CRTR_*`). Losing this propagation is exactly the 0.3.62
+// bug: the broker boots healthy but binds view.sock at the wrong path on a
+// Hearth guest (CRTR_SOCK_DIR=/run/crtr/socks, on tmpfs, separate from the
+// durable-volume node dir), so nothing that watches the real socket ever sees
+// it ready.
+import { test, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { nodeEnv } from '../nodes.js';
+function node(over = {}) {
+    return {
+        node_id: 'n1',
+        name: 'n1',
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        profile_id: null,
+        ...over,
+    };
+}
+const PATH_OVERRIDE_KEYS = ['CRTR_HOME', 'CRTR_SOCK_DIR', 'CRTR_CANVAS_DB', 'CRTR_SUBTREE'];
+let saved;
+before(() => {
+    saved = {};
+    for (const k of PATH_OVERRIDE_KEYS)
+        saved[k] = process.env[k];
+});
+beforeEach(() => {
+    for (const k of PATH_OVERRIDE_KEYS)
+        delete process.env[k];
+});
+afterEach(() => {
+    for (const k of PATH_OVERRIDE_KEYS)
+        delete process.env[k];
+});
+after(() => {
+    for (const k of PATH_OVERRIDE_KEYS) {
+        const v = saved[k];
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+});
+test('CRTR_SOCK_DIR is propagated from ambient env into the broker child env', () => {
+    process.env.CRTR_SOCK_DIR = '/run/crtr/socks';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_SOCK_DIR, '/run/crtr/socks');
+});
+test('CRTR_CANVAS_DB is propagated from ambient env into the broker child env (same latent-path class as CRTR_HOME)', () => {
+    process.env.CRTR_CANVAS_DB = '/mnt/shared/canvas.db';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_CANVAS_DB, '/mnt/shared/canvas.db');
+});
+test('both path overrides propagate together, alongside the existing CRTR_HOME propagation', () => {
+    process.env.CRTR_HOME = '/mnt/canvas-home';
+    process.env.CRTR_SOCK_DIR = '/run/crtr/socks';
+    process.env.CRTR_CANVAS_DB = '/mnt/shared/canvas.db';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_HOME, '/mnt/canvas-home');
+    assert.equal(env.CRTR_SOCK_DIR, '/run/crtr/socks');
+    assert.equal(env.CRTR_CANVAS_DB, '/mnt/shared/canvas.db');
+});
+test('unset ambient path overrides are omitted, never emitted as empty strings', () => {
+    // CRTR_SOCK_DIR/CRTR_CANVAS_DB/CRTR_HOME all deleted by beforeEach.
+    const env = nodeEnv(node());
+    assert.equal('CRTR_SOCK_DIR' in env, false);
+    assert.equal('CRTR_CANVAS_DB' in env, false);
+    assert.equal('CRTR_HOME' in env, false);
+});
+test('this is a narrow, named allowlist — an unrelated ambient CRTR_* var does NOT cross via nodeEnv', () => {
+    // Guards against "fix" drift toward spreading process.env wholesale: nodeEnv
+    // must keep naming each propagated key explicitly, not widen to any CRTR_*.
+    process.env.CRTR_SOME_UNRELATED_FLAG = 'leak-if-widened';
+    try {
+        const env = nodeEnv(node());
+        assert.equal('CRTR_SOME_UNRELATED_FLAG' in env, false);
+    }
+    finally {
+        delete process.env.CRTR_SOME_UNRELATED_FLAG;
+    }
+});

package/dist/core/runtime/nodes.js

@@ -76,6 +76,16 @@ export function nodeEnv(meta) {
     const home = process.env['CRTR_HOME'];
     if (home !== undefined && home !== '')
         env['CRTR_HOME'] = home;
+    // Propagate the deployment-layout path overrides (paths.ts siblings of
+    // CRTR_HOME) so the broker child binds its view.sock / opens canvas.db where
+    // every other process on this host looks. These are crtr-computed non-secret
+    // path config, same trust category as CRTR_HOME above — NOT a general
+    // CRTR_* allowlist weakening (spawn-env.ts's allowlist is untouched).
+    for (const key of ['CRTR_SOCK_DIR', 'CRTR_CANVAS_DB']) {
+        const v = process.env[key];
+        if (v !== undefined && v !== '')
+            env[key] = v;
+    }
     // Propagate the subtree-root node id. The broker uses it to group a subtree;
     // each launch site also emits the authoritative rootOfSpine(nodeId) over this
     // passthrough.

package/dist/core/secrets.d.ts

@@ -0,0 +1,25 @@
+import type { Scope } from '../types.js';
+/** The 0600 secrets store: raw relay/bearer tokens for `remoteCanvas.targets`,
+ *  kept OUT of `config.json` (which is not permission-hardened and is treated
+ *  as shareable/inspectable) and never logged. `crtr canvas config add
+ *  --relay-token -` is the ONLY accepted form — reads the raw token from
+ *  stdin; any other value is rejected with a generic error (never echoing
+ *  what was received). Keyed by `RemoteCanvasTarget.relayTokenRef`, never by
+ *  the target name directly, so a rename doesn't orphan the secret. */
+export interface SecretsStore {
+    relayTokens: Record<string, string>;
+}
+export declare function readSecrets(scope: Scope): SecretsStore;
+/** Writes secrets.json directly (never via `fs-utils.writeJson`, which has no
+ *  mode control) so the file is created 0600 from the first byte, then
+ *  `chmodSync`s belt-and-suspenders in case the file pre-existed with looser
+ *  permissions (e.g. hand-copied from another machine). */
+export declare function writeSecrets(scope: Scope, store: SecretsStore): void;
+export declare function getRelayToken(ref: string, scope: Scope): string | undefined;
+export declare function setRelayToken(ref: string, token: string, scope: Scope): void;
+export declare function deleteRelayToken(ref: string, scope: Scope): void;
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export declare function fingerprint(token: string): string;

package/dist/core/secrets.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { scopeRoot, requireScopeRoot } from './scope.js';
+import { ensureDir } from './fs-utils.js';
+const SECRETS_FILE = 'secrets.json';
+function secretsPathFor(root) {
+    return join(root, SECRETS_FILE);
+}
+export function readSecrets(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return { relayTokens: {} };
+    const p = secretsPathFor(root);
+    if (!existsSync(p))
+        return { relayTokens: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return { relayTokens: parsed.relayTokens ?? {} };
+    }
+    catch {
+        return { relayTokens: {} };
+    }
+}
+/** Writes secrets.json directly (never via `fs-utils.writeJson`, which has no
+ *  mode control) so the file is created 0600 from the first byte, then
+ *  `chmodSync`s belt-and-suspenders in case the file pre-existed with looser
+ *  permissions (e.g. hand-copied from another machine). */
+export function writeSecrets(scope, store) {
+    const root = requireScopeRoot(scope);
+    ensureDir(root);
+    const p = secretsPathFor(root);
+    writeFileSync(p, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(p, 0o600);
+}
+export function getRelayToken(ref, scope) {
+    return readSecrets(scope).relayTokens[ref];
+}
+export function setRelayToken(ref, token, scope) {
+    const s = readSecrets(scope);
+    s.relayTokens[ref] = token;
+    writeSecrets(scope, s);
+}
+export function deleteRelayToken(ref, scope) {
+    const s = readSecrets(scope);
+    delete s.relayTokens[ref];
+    writeSecrets(scope, s);
+}
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export function fingerprint(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+}

package/dist/core/view/__tests__/transport-remote.test.d.ts

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

package/dist/core/view/__tests__/transport-remote.test.js

@@ -0,0 +1,95 @@
+// transport-remote.test.ts — `createRemoteExec` (`../transport-remote.ts`), the
+// Node-side POST transport `RemoteCanvasSource` shells every remote read
+// through. Covers the one thing a bare `fetch(...)` with no
+// AbortController/timeout doesn't give you for free: a hung endpoint fails
+// CLOSED within a bound instead of wedging the caller forever. WITHOUT the
+// timeout, the "stalled endpoint" test below would hang past its own
+// assertion deadline (the promise the transport returns never settles).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { createRemoteExec } from '../transport-remote.js';
+function startStalledServer() {
+    return new Promise((resolve) => {
+        // Accept the connection but never write a response — the request just
+        // hangs, exactly what a wedged in-guest `/__crtr/source` handler looks
+        // like from the caller's side.
+        const server = createServer(() => { });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}
+test('a stalled endpoint returns a timeout failure within the configured bound instead of hanging forever', async () => {
+    const server = await startStalledServer();
+    const exec = createRemoteExec(server.url, 'tok', 100); // small timeout for the test
+    const started = Date.now();
+    // Race against a generous outer deadline: if the transport doesn't
+    // self-bound, this whole test times out instead of asserting cleanly —
+    // still proves the point, but assert explicitly for a clear failure message.
+    const result = await Promise.race([
+        exec('crtr', ['--json', 'node', 'inspect', 'list']),
+        new Promise((_resolve, reject) => setTimeout(() => reject(new Error('transport did not resolve within the outer deadline — no timeout is wired')), 2000)),
+    ]);
+    const elapsed = Date.now() - started;
+    assert.equal(result.ok, false);
+    assert.match(result.stderr, /timeout/i);
+    assert.ok(elapsed < 1000, `expected the timeout to fire near the configured 100ms bound, took ${elapsed}ms`);
+    await server.close();
+});
+test('a normal fast response is unaffected by the timeout wiring', async () => {
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
+        });
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const exec = createRemoteExec(`http://127.0.0.1:${port}`, 'tok', 5000);
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, true);
+    assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
+    await new Promise((r) => server.close(() => r()));
+});
+// --- Phase 3 review Minor 1: no token bytes may ever reach returned stderr ---
+test('an unreachable endpoint returns a flat generic network-error message, never the raw exception text', async () => {
+    const exec = createRemoteExec('http://127.0.0.1:1', 'valid-token-123');
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, false);
+    assert.equal(result.stderr, 'remote source: network error');
+});
+test('a malformed token (contains a newline) is rejected up front with a generic message, never reaching fetch/Headers', async () => {
+    const exec = createRemoteExec('http://127.0.0.1:1', 'bad\ntoken');
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, false);
+    assert.equal(result.stderr, 'remote source: invalid stored relay token');
+    assert.ok(!result.stderr.includes('bad\ntoken'));
+    assert.ok(!result.stderr.includes('bad'));
+});
+test('a valid token containing typical bearer-token punctuation (-, _, .) still round-trips against a real server', async () => {
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
+        });
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+    const exec = createRemoteExec(`http://127.0.0.1:${port}`, 'a1b2c3-real-token_ABC.789', 5000);
+    const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
+    assert.equal(result.ok, true);
+    assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
+    await new Promise((r) => server.close(() => r()));
+});

package/dist/core/view/remote-canvas-target.d.ts

@@ -1,3 +1,4 @@
-import type { Scope } from '../../types.js';
+import type { Scope, RemoteCanvasTarget } from '../../types.js';
 import type { RelayTarget } from '../../clients/attach/transport-relay.js';
+export declare function getRemoteCanvasTarget(name: string, scope?: Scope): RemoteCanvasTarget | undefined;
 export declare function resolveRemoteCanvasTarget(name: string, scope?: Scope): RelayTarget;

package/dist/core/view/remote-canvas-target.js

@@ -2,12 +2,17 @@
 // config entry (see `RemoteCanvasTarget`, `src/types.ts`) into a `RelayTarget`
 // ready for `RelayTransport` (`src/clients/attach/transport-relay.ts`).
 //
-// The raw bearer token NEVER lives in config or argv — only the name of an
-// environment variable holding it (`relayTokenEnv`), read here at connect
-// time. This is the Phase 1 interim contract; Phase 3 owns the real
-// secret-store-backed `crtr canvas config`/`crtr canvas use` CLI.
+// The raw bearer token NEVER lives in config.json — only a ref
+// (`relayTokenRef`) into the 0600 secrets store (`src/core/secrets.ts`),
+// resolved here at connect time via `getRelayToken`. Targets are registered
+// and the token stored via `crtr canvas config add` (`--relay-token -` reads
+// it from stdin, the preferred form to keep it out of shell history).
 import { usage } from '../errors.js';
 import { readConfig } from '../config.js';
+import { getRelayToken } from '../secrets.js';
+export function getRemoteCanvasTarget(name, scope = 'user') {
+    return readConfig(scope).remoteCanvas.targets[name];
+}
 export function resolveRemoteCanvasTarget(name, scope = 'user') {
     const cfg = readConfig(scope);
     const target = cfg.remoteCanvas.targets[name];
@@ -15,11 +20,11 @@ export function resolveRemoteCanvasTarget(name, scope = 'user') {
         const known = Object.keys(cfg.remoteCanvas.targets);
         throw usage(`no remote canvas target named '${name}'` +
             (known.length > 0 ? ` — configured: ${known.join(', ')}` : ' — none configured yet') +
-            `. Add remoteCanvas.targets.${name} to config.json (run \`crtr sys config path\`): {"previewEndpoint": "https://<hash>.preview.bl.run", "relayTokenEnv": "<ENV_VAR_NAME>"}.`);
+            `. Add one with \`crtr canvas config add ${name} --preview <url> --relay-token -\`.`);
     }
-    const relayToken = process.env[target.relayTokenEnv];
+    const relayToken = getRelayToken(target.relayTokenRef, scope);
     if (relayToken === undefined || relayToken === '') {
-        throw usage(`remote canvas target '${name}' needs its relay token in $${target.relayTokenEnv} — that environment variable is unset. Export it before running this command; the token is never read from config or argv.`);
+        throw usage(`target '${name}' has no stored relay token — add it with \`crtr canvas config add ${name} --relay-token -\`.`);
     }
     return { previewEndpoint: target.previewEndpoint, relayToken };
 }

package/dist/core/view/transport-remote.d.ts

@@ -0,0 +1,2 @@
+import type { RawResponse } from './contract.js';
+export declare function createRemoteExec(previewEndpoint: string, relayToken: string, timeoutMs?: number): (bin: string, args: string[]) => Promise<RawResponse>;