@crouton-kit/crouter 0.3.65 → 0.3.67

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>;

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

@@ -0,0 +1,53 @@
+// transport-remote.ts — the Node-side remote exec transport for a
+// RemoteCanvasSource. POSTs a SourceRequest to a Blaxel preview endpoint's
+// `/__crtr/source` route (the SAME in-guest source-fulfillment endpoint the
+// browser/web transport already speaks), bearer-authed with the relay token.
+//
+// This is the ONLY way RemoteCanvasSource reaches the remote canvas: it never
+// reads a remote SQLite file, and it never invokes an in-guest command that
+// doesn't already exist. Every argv it sends is `crtr --json <existing
+// subcommand>` — read-only.
+/** The remote read plane crosses a network boundary — a stalled TCP connection
+ *  or a hung `/__crtr/source` handler must fail closed, not wedge `node
+ *  inspect`/`canvas browse`/attach forever. Low enough that a genuinely hung
+ *  endpoint surfaces as a failed read within one interactive frame, not a
+ *  silent hang. */
+const DEFAULT_TIMEOUT_MS = 5_000;
+export function createRemoteExec(previewEndpoint, relayToken, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    // A malformed stored token (control chars / non-Latin1 bytes) would throw
+    // from the Headers constructor with the invalid value IN the thrown
+    // message — validate up front so that never happens, and fail with a
+    // GENERIC message instead (Phase 3 review Minor 1: no token bytes may ever
+    // reach returned stderr). HTTP header values are ISO-8859-1; reject
+    // anything outside `/^[\x20-\x7e]+$/` (printable ASCII, no CR/LF/control).
+    const tokenValid = /^[\x20-\x7e]+$/.test(relayToken);
+    return async function exec(bin, args) {
+        if (!tokenValid) {
+            return { ok: false, stdout: '', stderr: 'remote source: invalid stored relay token' };
+        }
+        const req = { kind: 'exec', bin, args };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(new URL('/__crtr/source', previewEndpoint), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${relayToken}` },
+                body: JSON.stringify(req),
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            if (controller.signal.aborted) {
+                return { ok: false, stdout: '', stderr: `remote source: timeout after ${timeoutMs}ms` };
+            }
+            return { ok: false, stdout: '', stderr: 'remote source: network error' };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return { ok: false, stdout: '', stderr: `remote source: HTTP ${res.status} ${res.statusText}` };
+        return (await res.json());
+    };
+}

package/dist/daemon/crtrd.js

@@ -64,7 +64,7 @@ import { FAULT_QUIET_MS, readFault, recordFault } from '../core/runtime/fault.js
 import { fanDoctrineWake } from '../core/runtime/close.js';
 import { logger } from '../core/log.js';
 export { FAULT_QUIET_MS };
-import { isPidAlive, isRecordedPidAlive } from '../core/canvas/pid.js';
+import { isPidAlive, isRecordedPidAlive, recordedPidLiveness } from '../core/canvas/pid.js';
 import { reconcileBootLiveness } from '../core/canvas/boot.js';
 import { listLivePanes, tearDownNode } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
@@ -705,14 +705,24 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     // its turn is over, and the engine never exited — past the grace it kills the
     // engine so the dead-pid refresh branch below revives it fresh.
     //
-    // Liveness here is IDENTITY-aware, not a bare isPidAlive: on a heavily-
+    // Liveness here is IDENTITY-aware AND requires CONFIRMED alive, not a bare
+    // isPidAlive or the fail-open-to-alive boolean adapter: on a heavily-
     // forking host (esp. Linux, where low pids recycle fast) a just-dead
-    // broker's pid can be reused by an unrelated process before this tick
-    // runs, and a bare isPidAlive would report the STRANGER as "our broker
-    // alive" — clearing the grace clock forever and wedging revive (the
-    // recorded-pid-reuse hang). isRecordedPidAlive guards against that with
-    // the launch-time identity baseline (`row.pi_pid_identity`).
-    if (pid != null && isRecordedPidAlive(pid, row.pi_pid_identity)) {
+    // broker's pid can be reused by an unrelated process within milliseconds,
+    // AND the `ps` probe confirming identity can itself intermittently fail.
+    // Either misread as "alive" here doesn't just misreport this one tick — it
+    // clears `unhealthySince` (the grace clock), discarding the daemon's memory
+    // that the node had already been observed dead, so the VERY NEXT tick treats
+    // a dead-for-20s+ node as a brand-new first observation and restarts the
+    // whole grace window from scratch (the confirmed Round-2 crash-revive wedge:
+    // a single `probe-null` read on a Linux CI runner wedged
+    // broker-crash-teardown.test.ts's 'CRASH → grace-revive RESUME'). So only a
+    // POSITIVELY CONFIRMED-alive read (`recordedPidLiveness === 'alive'`) may
+    // clear the clock; `'dead'` AND `'indeterminate'` both fall through to the
+    // ordinary not-alive path below, which now CONTRIBUTES to the grace window
+    // instead of zeroing it — robust to a flicker, and still revives promptly
+    // once a node is truly gone for the full grace duration.
+    if (pid != null && recordedPidLiveness(pid, row.pi_pid_identity) === 'alive') {
         unhealthySince.delete(id);
         clearStrandedRelaunchState(id); // a live engine means the stranding resolved
         handleYieldStall(row, pid, now);

package/dist/types.d.ts

@@ -138,10 +138,10 @@ export interface ScopeConfig {
      *  entries at the same scope precedence as the rest of `ScopeConfig`. */
     kinds: Record<string, KindConfig>;
     /** Named remote-canvas targets for `crtr surface attach to <id> --canvas
-     *  <name>` (Phase 1 interim contract — hand-edited in config.json, no CLI
-     *  verbs yet; Phase 3 owns the real secret-store-backed `crtr canvas
-     *  config`/`crtr canvas use`). Unset via `sys config set` — not in
-     *  `TOP_LEVEL_KEYS`. */
+     *  <name>`, `crtr node inspect list/show --canvas <name>`, and `crtr canvas
+     *  browse --canvas <name>` — registered/managed via `crtr canvas config
+     *  add/list/show/remove` and selected durably via `crtr canvas use`. Unset
+     *  via `sys config set` — not in `TOP_LEVEL_KEYS`. */
     remoteCanvas: RemoteCanvasConfig;
     /** Extra env-var names/globs a scope explicitly admits across the broker
      *  spawn-env boundary (`buildBrokerEnv`, `core/runtime/spawn-env.ts`) — the
@@ -154,14 +154,17 @@ export interface ScopeConfig {
     };
 }
 /** One remote canvas target: where to relay-attach and how to find its
- *  bearer token. The token itself is NEVER stored here — only the name of an
- *  environment variable holding it, resolved at connect time by
- *  `resolveRemoteCanvasTarget` (`src/core/view/remote-canvas-target.ts`). */
+ *  bearer token. The token itself is NEVER stored here — only a ref into the
+ *  0600 secrets store, resolved at connect time by `resolveRemoteCanvasTarget`
+ *  (`src/core/view/remote-canvas-target.ts`) via `getRelayToken`
+ *  (`src/core/secrets.ts`). */
 export interface RemoteCanvasTarget {
     previewEndpoint: string;
-    /** Name of an environment variable holding the raw relay/bearer token —
-     *  NEVER the token itself. Resolved from process.env at connect time. */
-    relayTokenEnv: string;
+    /** Name/ref under which the raw token is stored in secrets.json — NEVER the
+     *  token itself. Resolved via `getRelayToken` (`core/secrets.ts`) at connect
+     *  time. Defaults to the target name at creation but is a distinct field so
+     *  a future rename doesn't orphan the secret. */
+    relayTokenRef: string;
     cpOrigin?: string;
 }
 export interface RemoteCanvasConfig {
@@ -176,6 +179,11 @@ export interface ScopeState {
     }>;
     last_self_check?: string;
     bootstrap_done?: boolean;
+    /** The name of the remote canvas target `crtr canvas use` last selected
+     *  (see `RemoteCanvasConfig`), or `null`/omitted for local. Read by
+     *  `resolveCanvasSource` (`core/canvas/source.ts`) as the durable fallback
+     *  when a command's own `--canvas` flag is absent. */
+    activeCanvas?: string | null;
 }
 export interface SubagentFrontmatter {
     name: string;
@@ -244,7 +252,7 @@ export declare const PROFILE_DIR = "profiles";
 export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export declare function defaultScopeConfig(): ScopeConfig;
 /** No remote canvas targets are configured out of the box — every one is
- *  hand-added to config.json (Phase 1 interim contract, see `RemoteCanvasConfig`). */
+ *  registered via `crtr canvas config add` (see `RemoteCanvasConfig`). */
 export declare function defaultRemoteCanvasConfig(): RemoteCanvasConfig;
 /** The builtin kind registry (spec §1.5): the built-in defaults for every
  *  top-level kind and its sub-persona kinds. `whenToUse`/`model` are the

package/dist/types.js

@@ -36,7 +36,7 @@ export function defaultScopeConfig() {
     };
 }
 /** No remote canvas targets are configured out of the box — every one is
- *  hand-added to config.json (Phase 1 interim contract, see `RemoteCanvasConfig`). */
+ *  registered via `crtr canvas config add` (see `RemoteCanvasConfig`). */
 export function defaultRemoteCanvasConfig() {
     return { targets: {} };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.65",
+  "version": "0.3.67",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",