@crouton-kit/crouter 0.3.65 → 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/runtime/revive-all.js

@@ -13,7 +13,7 @@
 // self-guards the double-spawn. The selection predicate (`isDisconnected`) is
 // pure so the scope rules are unit-testable without booting a single process.
 import { listNodes, getNode } from '../canvas/index.js';
-import { isPidAlive } from '../canvas/pid.js';
+import { recordedPidLiveness } from '../canvas/pid.js';
 import { reviveNode } from './revive.js';
 /** Statuses a node lands in DELIBERATELY: a worker that finished its own work
  *  (`done`) or a node a human closed/reaped (`canceled`). The daemon never
@@ -56,7 +56,13 @@ export function listDisconnected() {
     const out = [];
     for (const row of listNodes()) {
         const meta = getNode(row.node_id);
-        if (meta !== null && isDisconnected(meta, isPidAlive))
+        // IDENTITY-aware AND requires CONFIRMED alive: a bare isPidAlive would
+        // misread a recycled pi_pid as "engine running" and SKIP the node, so it
+        // never reaches reviveNode's own identity-aware double-launch guard
+        // (Round 2 of the pid-reuse-liveness fix, fold-in Major). `dead` OR
+        // `indeterminate` both count as disconnected/eligible here — only a
+        // positively confirmed-alive read is treated as "still connected".
+        if (meta !== null && isDisconnected(meta, (pid) => recordedPidLiveness(pid, meta.pi_pid_identity) === 'alive'))
             out.push(meta);
     }
     return out;

package/dist/core/runtime/revive.js

@@ -29,7 +29,7 @@ import { fanDoctrineWake } from './close.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings } from './kickoff.js';
 import { headlessBrokerHost } from './host.js';
-import { isRecordedPidAlive } from '../canvas/pid.js';
+import { recordedPidLiveness } from '../canvas/pid.js';
 import { reconcileBootLiveness } from '../canvas/boot.js';
 import { clearFault } from './fault.js';
 import { clearInjectedDocs } from '../substrate/injected-store.js';
@@ -89,14 +89,24 @@ export function reviveNode(nodeId, opts) {
     // actually matters, so it's safe to call on every revive regardless of
     // entry point (daemon tick, or a direct/manual `node lifecycle revive`).
     reconcileBootLiveness();
-    // Double-revive guard: the broker's isAlive is identity-aware liveness on
-    // pi_pid, so a node whose broker pid is still running (and CONFIRMED to
-    // still be that same broker, not a reused pid) was already revived by
-    // another path — re-launching would put a SECOND broker on the same
-    // session file. No-op. A bare isPidAlive would misread a reused pid (heavy
-    // forking, esp. Linux) as "still alive" and skip the relaunch forever.
+    // Double-revive guard: identity-aware liveness on pi_pid, requiring
+    // CONFIRMED alive — not the fail-open-to-alive boolean adapter. A node
+    // whose broker pid is CONFIRMED still running as that same broker (not a
+    // reused pid) was already revived by another path — re-launching would put
+    // a SECOND broker on the same session file. No-op. A bare isPidAlive would
+    // misread a reused pid (heavy forking, esp. Linux) as "still alive" and
+    // skip the relaunch forever; conversely, treating an INDETERMINATE read
+    // (can't confirm either way, e.g. a transient `ps` probe failure) as
+    // "alive" here would risk the opposite failure — silently skipping a
+    // needed relaunch and stranding the node with no engine. So this guard
+    // blocks ONLY on a positively confirmed-alive read; `dead` AND
+    // `indeterminate` both proceed to relaunch. We accept that tradeoff: an
+    // `indeterminate` read CAN come from a genuinely live broker whose identity
+    // `ps` probe transiently failed, so proceeding risks a rare double-launch —
+    // but stranding a truly-dead node with no engine is the worse failure, and
+    // recovering from it is far harder, so we bias toward relaunching.
     const live = getNode(nodeId) ?? meta;
-    if (isRecordedPidAlive(live.pi_pid, live.pi_pid_identity)) {
+    if (recordedPidLiveness(live.pi_pid, live.pi_pid_identity) === 'alive') {
         return {
             window: null,
             session: live.tmux_session ?? null,

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/substrate/on-read.js

@@ -58,6 +58,7 @@ import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
+import { userScopeRoot } from '../scope.js';
 import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, } from './index.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 // Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
@@ -156,16 +157,26 @@ function hasExplicitTrigger(doc) {
  *  `.crouter/memory/`, walking from the read file up to $HOME (or the
  *  filesystem root for a read outside $HOME), skipping junk ancestors. The
  *  user-global `~/.crouter/memory/` store is deliberately skipped: otherwise
- *  every file read under $HOME would surface unrelated user-wide preferences. */
+ *  every file read under $HOME would surface unrelated user-wide preferences.
+ *
+ *  The crouter home (`~/.crouter`, the user scope root) is skipped for the same
+ *  reason it is never a project scope root (scope.ts's `isProjectScopeDir`): it
+ *  is the user scope, not a project ancestor. Without this fence, reading any
+ *  canvas runtime artifact (`~/.crouter/canvas/nodes/.../reports|context/...`)
+ *  walks up THROUGH `~/.crouter` and would inject whatever lives at
+ *  `~/.crouter/.crouter/memory/` — e.g. a differently-scoped node whose cwd
+ *  resolved its project store there — leaking one node's private memory into
+ *  every unrelated node that reads a canvas file. */
 function positionalCandidates(absReadFile) {
     const out = [];
     const seenDocPaths = new Set();
     const home = realpathOrSelf(homedir());
+    const userRoot = realpathOrSelf(userScopeRoot());
     const fsRoot = parse(absReadFile).root;
     let dir = dirname(absReadFile);
     let depth = 0;
     while (true) {
-        if (dir !== home && !isJunkAncestor(dir)) {
+        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
             const memDir = join(dir, CRTR_DIR_NAME, 'memory');
             if (pathExists(memDir)) {
                 for (const file of safeWalkMd(memDir)) {

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

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