@crouton-kit/crouter 0.3.66 → 0.3.67

package/dist/commands/__tests__/canvas-config.test.js

@@ -0,0 +1,107 @@
+// canvas-config.test.ts — `canvas config list`/`show` (`../canvas-config.ts`)
+// mask every target's token presence/fingerprint from a SINGLE preloaded
+// `SecretsStore`, never re-reading/reparsing `secrets.json` once per target
+// (Minor 1, Phase 3 review 3).
+//
+// Proving "reads secrets.json once, not per target" can't be done by spying —
+// this is a real ESM module (`node:test`'s `mock.method` cannot redefine a
+// non-configurable ESM export; confirmed empirically, not assumed). Instead
+// `secrets.json` is a real named pipe (FIFO) with exactly ONE writer that
+// delivers its payload once and then closes: a SECOND `readFileSync` on that
+// path blocks forever waiting for a writer that will never come. So `list`
+// across N>1 targets only resolves within the timeout if it reads the file
+// exactly once — the old per-target-read code would hang on the second
+// target's read and this test would time out.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { canvasConfigBranch } from '../canvas-config.js';
+import { updateConfig } from '../../core/config.js';
+import { readSecrets } from '../../core/secrets.js';
+import { InputError } from '../../core/io.js';
+function leaf(name) {
+    const found = (canvasConfigBranch.children ?? []).find((c) => c.name === name);
+    if (found === undefined || found.kind !== 'leaf')
+        throw new Error(`no leaf '${name}' under canvas config`);
+    return found;
+}
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-canvas-config-'));
+    process.env['HOME'] = home;
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+});
+test('list masks N targets from ONE secrets.json read — a per-target re-read would hang on the exhausted FIFO', async () => {
+    // Three registered targets, each with a stored token — a per-target
+    // re-read regression would need 3 successful reads of secrets.json.
+    updateConfig('user', (cfg) => {
+        cfg.remoteCanvas.targets['alpha'] = { previewEndpoint: 'https://a.example', relayTokenRef: 'alpha' };
+        cfg.remoteCanvas.targets['beta'] = { previewEndpoint: 'https://b.example', relayTokenRef: 'beta' };
+        cfg.remoteCanvas.targets['gamma'] = { previewEndpoint: 'https://c.example', relayTokenRef: 'gamma' };
+    });
+    const crouterDir = join(home, '.crouter');
+    mkdirSync(crouterDir, { recursive: true });
+    const secretsPath = join(crouterDir, 'secrets.json');
+    execFileSync('mkfifo', [secretsPath]);
+    const payload = JSON.stringify({ relayTokens: { alpha: 'tok-a', beta: 'tok-b', gamma: 'tok-c' } });
+    // A single writer: opens the FIFO, writes the payload once, and exits —
+    // there is no second writer, so a second reader blocks forever.
+    const writer = spawn('sh', ['-c', `printf '%s' '${payload}' > '${secretsPath}'`], { stdio: 'ignore' });
+    try {
+        const result = await Promise.race([
+            leaf('list').run({}),
+            new Promise((_resolve, reject) => setTimeout(() => reject(new Error('list did not resolve — a second secrets.json read is blocking on the exhausted FIFO (per-target re-read regression)')), 2000)),
+        ]);
+        const targets = result['targets'];
+        assert.equal(targets.length, 3);
+        const byName = Object.fromEntries(targets.map((t) => [t['name'], t]));
+        assert.equal(byName['alpha']?.['tokenStored'], true);
+        assert.equal(byName['beta']?.['tokenStored'], true);
+        assert.equal(byName['gamma']?.['tokenStored'], true);
+        assert.notEqual(byName['alpha']?.['fingerprint'], byName['beta']?.['fingerprint']);
+    }
+    finally {
+        writer.kill();
+        // Replace the FIFO with a plain file so later tests in this process (or a
+        // stray writer) don't wedge on it.
+        rmSync(secretsPath, { force: true });
+        writeFileSync(secretsPath, payload);
+    }
+});
+// --- Phase 3 review Major 2: `add --relay-token` must be stdin-only ---
+test('add rejects a literal (non-"-") --relay-token value with a generic error that never echoes the received secret', async () => {
+    const secret = 'some-literal-secret-value';
+    await assert.rejects(() => leaf('add').run({ name: 'literal-reject-test', preview: 'https://example.test', relayToken: secret, cp: undefined }), (err) => {
+        assert.ok(err instanceof InputError, `expected InputError, got ${err}`);
+        const serialized = JSON.stringify({ message: err.message, payload: err.payload });
+        assert.ok(!serialized.includes(secret), 'the thrown error must never interpolate the received relay-token value');
+        return true;
+    });
+});
+test('add with --relay-token - reads the raw token from stdin and stores it', async () => {
+    const realStdin = process.stdin;
+    const fakeStdin = Readable.from([Buffer.from('piped-stdin-token\n')]);
+    fakeStdin.isTTY = false;
+    Object.defineProperty(process, 'stdin', { value: fakeStdin, configurable: true });
+    try {
+        const result = await leaf('add').run({ name: 'stdin-add-test', preview: 'https://example.test', relayToken: '-', cp: undefined });
+        assert.equal(result['tokenStored'], true);
+        const secrets = readSecrets('user');
+        assert.equal(secrets.relayTokens['stdin-add-test'], 'piped-stdin-token');
+    }
+    finally {
+        Object.defineProperty(process, 'stdin', { value: realStdin, configurable: true });
+    }
+});

package/dist/commands/canvas-browse.js

@@ -7,6 +7,10 @@
 // Outside a TTY it prints the static forest and exits 0 (see runBrowse).
 import { defineLeaf } from '../core/command.js';
 import { runBrowse } from '../core/canvas/browse/app.js';
+import { resolveCanvasSource } from '../core/canvas/source.js';
+import { resolveRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+import { RemoteEventStream } from '../core/canvas/remote-event-stream.js';
+import { readState } from '../core/config.js';
 export const browseLeaf = defineLeaf({
     name: 'browse',
     description: 'open the interactive canvas navigator (tabs/tree/search)',
@@ -29,6 +33,13 @@ export const browseLeaf = defineLeaf({
                 required: false,
                 constraint: 'directory to scope the navigator to by default — only nodes spawned from this dir show until you toggle to All dirs (c). The /resume-node popup passes the launching node\'s cwd. Default: the invocation cwd.',
             },
+            {
+                kind: 'flag',
+                name: 'canvas',
+                type: 'string',
+                required: false,
+                constraint: 'Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`.',
+            },
         ],
         output: [],
         outputKind: 'object',
@@ -40,6 +51,20 @@ export const browseLeaf = defineLeaf({
     },
     run: async (input) => {
         const cwd = input['cwd'] ?? process.cwd();
-        await runBrowse({ returnPane: input['returnPane'], cwd });
+        const canvasName = input['canvas'];
+        const source = resolveCanvasSource({ canvasName });
+        // The EFFECTIVE remote target name — an explicit --canvas, or (mirroring
+        // resolveCanvasSource's own precedence) the durable `crtr canvas use`
+        // selection. Only a remote target needs an event stream; resolve its
+        // credentials ONCE here (not re-derived inside app.ts, which stays
+        // credential-agnostic).
+        const effectiveCanvasName = canvasName ?? readState('user').activeCanvas ?? undefined;
+        const eventStream = effectiveCanvasName !== undefined
+            ? (() => {
+                const { previewEndpoint, relayToken } = resolveRemoteCanvasTarget(effectiveCanvasName);
+                return new RemoteEventStream(previewEndpoint, relayToken);
+            })()
+            : undefined;
+        await runBrowse({ returnPane: input['returnPane'], cwd, source, eventStream });
     },
 });

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

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare const canvasConfigBranch: BranchDef;

package/dist/commands/canvas-config.js

@@ -0,0 +1,210 @@
+// `crtr canvas config` — register, list, inspect, and remove named remote
+// canvas targets (a preview endpoint + a relay token kept in the 0600
+// secrets store, never persisted to config.json or logged). `add` requires
+// `--relay-token -` (stdin-only) — a literal argv value is rejected with a
+// generic error (never echoing what was received, since it may be a real
+// secret) so the token can never land in shell history or process listings.
+// Selecting one for read commands is `crtr canvas use`, a sibling leaf, not a
+// child here.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { readConfig, updateConfig } from '../core/config.js';
+import { readSecrets, setRelayToken, deleteRelayToken, fingerprint } from '../core/secrets.js';
+const SCOPE = 'user';
+/** Masks one target's token presence/fingerprint from an ALREADY-loaded
+ *  `SecretsStore` — never re-reads/reparses `secrets.json` per target
+ *  (`list`/`show` load it once and pass it in here). */
+function maskedTarget(name, target, secrets) {
+    const token = secrets.relayTokens[target.relayTokenRef];
+    return {
+        name,
+        previewEndpoint: target.previewEndpoint,
+        relayTokenRef: target.relayTokenRef,
+        ...(target.cpOrigin ? { cpOrigin: target.cpOrigin } : {}),
+        tokenStored: token !== undefined && token !== '',
+        ...(token !== undefined && token !== '' ? { fingerprint: fingerprint(token) } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// canvas config add
+// ---------------------------------------------------------------------------
+const canvasConfigAdd = defineLeaf({
+    name: 'add',
+    description: 'register a remote canvas target (preview endpoint + relay token)',
+    whenToUse: 'wiring up a remote canvas so `node inspect`, `canvas browse`, or `surface attach --canvas` can read it \u2014 stores the preview endpoint in config.json and the raw relay token in the 0600 secrets store (never together, never persisted to config.json or logged). Re-running with the same name overwrites both.',
+    help: {
+        name: 'canvas config add',
+        summary: 'register (or overwrite) a named remote canvas target',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name \u2014 the id every other `canvas config`/`canvas use`/`--canvas` reference uses.' },
+            { kind: 'flag', name: 'preview', type: 'string', required: true, constraint: 'The Blaxel preview endpoint base URL (e.g. https://<hash>.preview.bl.run).' },
+            { kind: 'flag', name: 'relay-token', type: 'string', required: true, constraint: 'Must be exactly `-` — the raw token is read from stdin, never argv (keeps it out of shell history). Any other value is rejected.' },
+            { kind: 'flag', name: 'cp', type: 'string', required: false, constraint: 'Optional control-plane origin, when this target has one distinct from the preview endpoint.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The target name just registered.' },
+            { name: 'previewEndpoint', type: 'string', required: true, constraint: 'The stored preview endpoint.' },
+            { name: 'relayTokenRef', type: 'string', required: true, constraint: 'The secrets-store key the token was written under (equals name).' },
+            { name: 'cpOrigin', type: 'string', required: false, constraint: 'The stored control-plane origin, when --cp was given.' },
+            { name: 'tokenStored', type: 'boolean', required: true, constraint: 'Always true on success \u2014 confirms the token was written to the 0600 store.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes remoteCanvas.targets.<name> to config.json (previewEndpoint, relayTokenRef, cpOrigin).', 'Writes the raw token to the 0600 secrets store under relayTokenRef \u2014 never to config.json or stdout.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const previewEndpoint = input['preview'];
+        const rawFlag = input['relayToken'];
+        const cp = input['cp'];
+        if (rawFlag !== '-') {
+            throw new InputError({
+                error: 'invalid_relay_token_arg',
+                message: 'relay token must be piped on stdin — pass `--relay-token -`',
+                field: 'relay-token',
+                next: 'Re-run with `--relay-token -` and pipe the raw token on stdin (e.g. `echo "$TOKEN" | crtr canvas config add <name> --preview <url> --relay-token -`).',
+            });
+        }
+        const token = (await readStdinRaw()).trim();
+        if (token === '') {
+            throw new InputError({
+                error: 'empty_token',
+                message: 'relay token is empty',
+                field: 'relay-token',
+                next: 'Pass a non-empty token, or `--relay-token -` and pipe it on stdin.',
+            });
+        }
+        const target = { previewEndpoint, relayTokenRef: name, ...(cp ? { cpOrigin: cp } : {}) };
+        updateConfig(SCOPE, (cfg) => {
+            cfg.remoteCanvas.targets[name] = target;
+        });
+        setRelayToken(name, token, SCOPE);
+        return { name, previewEndpoint, relayTokenRef: name, ...(cp ? { cpOrigin: cp } : {}), tokenStored: true };
+    },
+    render: (r) => `Registered remote canvas target '${r['name']}' → ${r['previewEndpoint']} (token stored).`,
+});
+// ---------------------------------------------------------------------------
+// canvas config list
+// ---------------------------------------------------------------------------
+const canvasConfigList = defineLeaf({
+    name: 'list',
+    description: 'list registered remote canvas targets',
+    whenToUse: 'checking which remote canvas targets exist before `canvas use`/`--canvas <name>` \u2014 never prints a raw token, only a non-reversible fingerprint.',
+    help: {
+        name: 'canvas config list',
+        summary: 'list every registered remote canvas target (masked \u2014 no raw tokens)',
+        output: [
+            {
+                name: 'targets',
+                type: 'object[]',
+                required: true,
+                constraint: 'Each: {name, previewEndpoint, relayTokenRef, cpOrigin?, tokenStored, fingerprint?}. fingerprint is a non-reversible sha256 prefix, present only when a token is stored.',
+            },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads config.json and the secrets-store token presence/fingerprint (never the raw token).'],
+    },
+    run: async () => {
+        const cfg = readConfig(SCOPE);
+        const secrets = readSecrets(SCOPE);
+        const targets = Object.entries(cfg.remoteCanvas.targets).map(([name, t]) => maskedTarget(name, t, secrets));
+        return { targets };
+    },
+    render: (r) => {
+        const targets = r['targets'];
+        if (targets.length === 0)
+            return 'No remote canvas targets configured.';
+        return targets
+            .map((t) => `${t['name']} — ${t['previewEndpoint']} (${t['tokenStored'] ? `token ${t['fingerprint']}` : 'no token stored'})`)
+            .join('\n');
+    },
+});
+// ---------------------------------------------------------------------------
+// canvas config show
+// ---------------------------------------------------------------------------
+const canvasConfigShow = defineLeaf({
+    name: 'show',
+    description: 'show one registered remote canvas target',
+    whenToUse: 'inspecting a single remote canvas target\u2019s config \u2014 masked the same way as `list`.',
+    help: {
+        name: 'canvas config show',
+        summary: 'show one remote canvas target (masked \u2014 no raw token)',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The target name.' },
+            { name: 'previewEndpoint', type: 'string', required: true, constraint: 'The stored preview endpoint.' },
+            { name: 'relayTokenRef', type: 'string', required: true, constraint: 'The secrets-store key holding the token.' },
+            { name: 'cpOrigin', type: 'string', required: false, constraint: 'The stored control-plane origin, when this target has one distinct from the preview endpoint.' },
+            { name: 'tokenStored', type: 'boolean', required: true, constraint: 'Whether a token is currently stored under relayTokenRef.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const cfg = readConfig(SCOPE);
+        const target = cfg.remoteCanvas.targets[name];
+        if (target === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`.',
+            });
+        }
+        return maskedTarget(name, target, readSecrets(SCOPE));
+    },
+    render: (r) => `${r['name']} — ${r['previewEndpoint']} (${r['tokenStored'] ? `token ${r['fingerprint']}` : 'no token stored'})`,
+});
+// ---------------------------------------------------------------------------
+// canvas config remove
+// ---------------------------------------------------------------------------
+const canvasConfigRemove = defineLeaf({
+    name: 'remove',
+    description: 'remove a registered remote canvas target and its stored token',
+    whenToUse: 'decommissioning a remote canvas target \u2014 drops it from config.json and deletes its raw token from the secrets store.',
+    help: {
+        name: 'canvas config remove',
+        summary: 'remove a remote canvas target and its stored token',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
+        ],
+        output: [
+            { name: 'removed', type: 'string', required: true, constraint: 'The target name removed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes remoteCanvas.targets.<name> from config.json.', 'Deletes the stored token under relayTokenRef from the secrets store.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const cfg = readConfig(SCOPE);
+        const target = cfg.remoteCanvas.targets[name];
+        if (target === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`.',
+            });
+        }
+        updateConfig(SCOPE, (c) => {
+            delete c.remoteCanvas.targets[name];
+        });
+        deleteRelayToken(target.relayTokenRef, SCOPE);
+        return { removed: name };
+    },
+    render: (r) => `Removed remote canvas target '${r['removed']}'.`,
+});
+// ---------------------------------------------------------------------------
+// Export — mounted under `crtr canvas`
+// ---------------------------------------------------------------------------
+export const canvasConfigBranch = defineBranch({
+    name: 'config',
+    description: 'register/list/inspect/remove remote canvas targets',
+    whenToUse: 'setting up or auditing a remote canvas target (preview endpoint + relay token) before selecting one with `crtr canvas use`.',
+    help: {
+        name: 'canvas config',
+        summary: 'manage named remote canvas targets',
+        model: 'A remote canvas target is a preview endpoint + a relay token registered under a name. `add` registers one (token goes to the 0600 secrets store, never config.json); `list`/`show` display masked entries (fingerprint only, never the raw token); `remove` deletes both the config entry and the stored token. Select a target for read commands with `crtr canvas use <name>`, or back to local with `crtr canvas use --local`.',
+    },
+    children: [canvasConfigAdd, canvasConfigList, canvasConfigShow, canvasConfigRemove],
+});

package/dist/commands/canvas-use.d.ts

@@ -0,0 +1 @@
+export declare const canvasUseLeaf: import("../core/command.js").LeafDef;

package/dist/commands/canvas-use.js

@@ -0,0 +1,63 @@
+// `crtr canvas use` — durably select which canvas read commands
+// (`node inspect list/show`, `canvas browse`) default onto: a named remote
+// target, or back to local. A single leaf, not a branch — there is exactly
+// one decision here (pick a target, or go local), not a family of verbs.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { updateState } from '../core/config.js';
+import { getRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+const SCOPE = 'user';
+export const canvasUseLeaf = defineLeaf({
+    name: 'use',
+    description: 'select the durable default canvas for read commands (a remote target, or local)',
+    whenToUse: 'switching what `node inspect list/show` and `canvas browse` read from by default, without passing `--canvas <name>` on every invocation \u2014 select a remote target registered via `crtr canvas config add`, or switch back to local. A command\u2019s own `--canvas <name>` flag always overrides this for that one call.',
+    help: {
+        name: 'canvas use',
+        summary: 'select the durable default canvas (a registered remote target, or local) for read commands',
+        params: [
+            { kind: 'positional', name: 'name', required: false, constraint: 'A remote canvas target registered via `crtr canvas config add`. Mutually exclusive with --local; exactly one of the two is required.' },
+            { kind: 'flag', name: 'local', type: 'bool', required: false, constraint: 'Switch back to the local canvas. Mutually exclusive with <name>.' },
+        ],
+        output: [
+            { name: 'active', type: 'string', required: false, constraint: 'The now-active target name, or omitted/null for local.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes state.json\u2019s activeCanvas (user scope).'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const local = input['local'] === true;
+        if (name !== undefined && local) {
+            throw new InputError({
+                error: 'ambiguous_scope',
+                message: '<name> and --local are mutually exclusive',
+                next: 'Pass a target name to go remote, or --local to go local \u2014 not both.',
+            });
+        }
+        if (name === undefined && !local) {
+            throw new InputError({
+                error: 'missing_target',
+                message: 'nothing to select \u2014 pass a target name or --local',
+                next: 'Pass a target name (see `crtr canvas config list`) to go remote, or --local to go local.',
+            });
+        }
+        if (local) {
+            updateState(SCOPE, (s) => {
+                s.activeCanvas = null;
+            });
+            return { active: null };
+        }
+        if (getRemoteCanvasTarget(name, SCOPE) === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`, or register one with `crtr canvas config add`.',
+            });
+        }
+        updateState(SCOPE, (s) => {
+            s.activeCanvas = name;
+        });
+        return { active: name };
+    },
+    render: (r) => (r['active'] ? `Active canvas: ${r['active']}.` : 'Active canvas: local.'),
+});

package/dist/commands/canvas.js

@@ -17,6 +17,8 @@ import { canvasPruneLeaf } from './canvas-prune.js';
 import { canvasRebuildIndexLeaf } from './canvas-rebuild-index.js';
 import { historyBranch } from './canvas-history.js';
 import { issueNewLeaf } from './canvas-issue.js';
+import { canvasConfigBranch } from './canvas-config.js';
+import { canvasUseLeaf } from './canvas-use.js';
 export const issueBranch = defineBranch({
     name: 'issue',
     description: 'capture a quick todo/idea/bug into a GitHub issue (or a .todos/ note)',
@@ -40,8 +42,8 @@ export function registerCanvas() {
         help: {
             name: 'canvas',
             summary: 'observe and supervise the whole agent graph',
-            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL.',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches read commands (`node inspect`, `browse`) onto a configured remote target or back to local.',
         },
-        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
+        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf, canvasConfigBranch, canvasUseLeaf],
     });
 }

package/dist/commands/node.js

@@ -37,7 +37,8 @@ import { readMergedLaunchConfig } from '../core/config.js';
 import { listProfiles } from '../core/profiles/manifest.js';
 import { stateBlock } from '../core/help.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, contextDir, reportsDir, nodeArtifacts, readContextTokens, armTrigger, listTriggers, cancelTrigger, TriggerArmError, fullName, } from '../core/canvas/index.js';
-import { localCanvasSource } from '../core/canvas/source.js';
+import { resolveCanvasSource } from '../core/canvas/source.js';
+import { RemoteCanvasSource } from '../core/canvas/remote-canvas-source.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
 // off yielding than holding its fat window open for the child's result: the
 // child's finish revives it fresh against its roadmap, so a clean window absorbs
@@ -387,14 +388,15 @@ const nodeList = defineLeaf({
             { kind: 'flag', name: 'lifecycle', type: 'string', required: false, constraint: 'Filter by lifecycle (comma-separated for several; accepted values: terminal, resident).' },
             { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Filter to nodes pinned to this exact cwd (absolute path). Roster is canvas-wide (all cwds) by default.' },
             { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Graph scope: restrict to this node and its subscription descendants (the sub-DAG reachable downward — its reports, theirs, …). This is "one initiative / my subtree". ANDs with every attribute filter above, narrowing any of them to this subtree.' },
-            { kind: 'flag', name: 'hanging', type: 'bool', required: false, constraint: 'Only nodes PARKED on an active fault (live broker + marker when provider-owned). Use to find stuck/rate-limited nodes awaiting auto-revive.' },
+            { kind: 'flag', name: 'hanging', type: 'bool', required: false, constraint: 'Only nodes PARKED on an active fault (live broker + marker when provider-owned). Use to find stuck/rate-limited nodes awaiting auto-revive. Not supported against a --canvas remote target in this phase (returns no rows).' },
+            { kind: 'flag', name: 'canvas', type: 'string', required: false, constraint: 'Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`.' },
         ],
         output: [
             { name: 'nodes', type: 'object[]', required: true, constraint: 'Rows: {node_id, name, kind, mode, lifecycle, status, cwd, parent, created, hanging}. `hanging` is null normally, or {kind, message, since} when the node is PARKED on an active fault (rate-limit/overloaded/connection/other); the canvas-graph views render it with ⚠ + a countdown or state cue.' },
         ],
         outputKind: 'object',
         dynamicState: () => kindsStateBlock(),
-        effects: ['Read-only: queries canvas.db (+ an active-fault marker read).'],
+        effects: ['Read-only: queries canvas.db; locally also reads the active-fault marker (suppressed against a --canvas remote target).'],
     },
     run: async (input) => {
         const csv = (k) => {
@@ -410,7 +412,7 @@ const nodeList = defineLeaf({
         const hangingOnly = input['hanging'] === true;
         // Graph scope (--under): self + subscription descendants. Validate the anchor
         // so a typo'd id is a structured error, not a silently-empty roster.
-        const canvasSource = localCanvasSource;
+        const canvasSource = resolveCanvasSource({ canvasName: input['canvas'] });
         let scope;
         if (under !== undefined && under !== '') {
             if (await canvasSource.getNode(under) === null) {
@@ -433,11 +435,16 @@ const nodeList = defineLeaf({
         });
         // Enrich each row with its active-fault state. Daemon-owned provider faults
         // are suppressed when the broker pid is gone; manual/client faults stay
-        // visible until cleared.
-        const nodes = await Promise.all(rows.map(async (row) => {
-            const hanging = activeFaultForDisplay(row, await readFaultAsync(row.node_id));
-            return { ...row, hanging };
-        }));
+        // visible until cleared. Fault state is a LOCAL read, so a remote canvas's
+        // rows are never enriched with it — `hanging` is suppressed to null and
+        // --hanging returns no rows against a remote target.
+        const remote = canvasSource instanceof RemoteCanvasSource;
+        const nodes = remote
+            ? rows.map((row) => ({ ...row, hanging: null }))
+            : await Promise.all(rows.map(async (row) => {
+                const hanging = activeFaultForDisplay(row, await readFaultAsync(row.node_id));
+                return { ...row, hanging };
+            }));
         return { nodes: nodes.filter((n) => !hangingOnly || n.hanging !== null) };
     },
 });
@@ -456,6 +463,11 @@ async function enrichNeighborFromSource(source, ref) {
         active: ref.active,
     };
 }
+/** Symbol-keyed marker set on a remote-passthrough `node inspect show` result so
+ *  `render()` below can tell it came from a remote canvas without adding an
+ *  enumerable field — `JSON.stringify` (the `--json` path) skips symbol keys,
+ *  so this is invisible to machine output. */
+const REMOTE_SHOW_MARKER = Symbol('remote-show');
 const nodeShow = defineLeaf({
     name: 'show',
     description: 'show a node + its spine neighbors, artifacts, and drill-in pointers',
@@ -465,6 +477,7 @@ const nodeShow = defineLeaf({
         summary: 'show a node in depth — meta slice, named neighbors (reports/managers), artifact/trigger counts, and drill-in pointers (context dir, session file, children). The debugging entrypoint for one node.',
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id.' },
+            { kind: 'flag', name: 'canvas', type: 'string', required: false, constraint: 'Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`.' },
         ],
         output: [
             { name: 'node', type: 'object', required: true, constraint: 'The full node meta (system prompt + every telemetry field). The render surfaces a glanceable slice; `--json` carries the complete dump.' },
@@ -485,7 +498,23 @@ const nodeShow = defineLeaf({
     },
     run: async (input) => {
         const id = input['node'];
-        const canvasSource = localCanvasSource;
+        const canvasName = input['canvas'];
+        const canvasSource = resolveCanvasSource({ canvasName });
+        // Remote branch: `node inspect show` already computes this exact
+        // {node, reports, managers, artifacts, pending_triggers, paths, follow_up}
+        // shape in-guest — passthrough it verbatim rather than re-deriving
+        // artifacts/triggers/paths from LOCAL disk (which would be meaningless for
+        // a remote node id). The `render` below works unchanged on either branch
+        // since it only reads generic fields off the returned object.
+        if (canvasSource instanceof RemoteCanvasSource) {
+            const passthrough = await canvasSource.rawShow(id);
+            if (passthrough === null) {
+                throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list --canvas <name>`.' });
+            }
+            const result = passthrough;
+            result[REMOTE_SHOW_MARKER] = true;
+            return result;
+        }
         const node = await canvasSource.getNode(id);
         if (node === null) {
             throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
@@ -525,7 +554,8 @@ const nodeShow = defineLeaf({
         const node = r['node'];
         const id = String(node['node_id']);
         const pid = node['pi_pid'];
-        const alive = isPidAlive(pid) ? 'alive' : 'dead';
+        const isRemoteShow = Boolean(r[REMOTE_SHOW_MARKER]);
+        const alive = isRemoteShow ? 'remote (liveness not checked locally)' : (isPidAlive(pid) ? 'alive' : 'dead');
         const intent = node['intent'] ? `/${String(node['intent'])}` : '';
         const parts = [];
         // 1) Glanceable meta slice — the debug-critical fields, not the full dump.

package/dist/core/__tests__/remote-canvas-target.test.d.ts

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