@north-light/crouter 0.3.154

package/dist/core/profiles/state-block.js

@@ -0,0 +1,16 @@
+// The `<profiles>` help state element — every leaf carrying a `--profile` flag
+// enumerates the accepted value set on that same leaf (command-surface rule),
+// so an agent never has to guess an id or take a `crtr profile list` hop.
+import { stateBlock } from '../help.js';
+import { listProfiles } from './manifest.js';
+/** A live `<profiles count=N>` state element — one `<profile_id> — <name>` line
+ *  per profile on this host. Soft-fails via the renderer like other state
+ *  blocks. */
+export function profilesStateBlock() {
+    const all = listProfiles();
+    const limit = 20;
+    const visible = all.slice(0, limit);
+    const lines = visible.map((p) => `${p.profileId} — ${p.manifest.name}`).join('\n');
+    const overflow = all.length > limit ? `${lines}\n… ${all.length - limit} more; use crtr profile list` : lines;
+    return stateBlock('profiles', { count: all.length }, overflow);
+}

package/dist/core/provider-management.d.ts

@@ -0,0 +1,12 @@
+/** The minimal shape of a Providers-panel row the removal router needs. */
+export interface RemovableProviderRow {
+    providerId: string;
+    name: string;
+    managed: boolean;
+    configured?: boolean;
+    label?: string;
+}
+/** Route a row's removal to the coordinated service (managed) or auth.json (non-managed) and
+ *  return the truthful panel notice. May throw (e.g. an unknown-subscription error) — callers
+ *  surface that as the notice. */
+export declare function removeProviderRow(agentDir: string, row: RemovableProviderRow): Promise<string>;

package/dist/core/provider-management.js

@@ -0,0 +1,22 @@
+// Removal routing for a Providers-panel row, kept in core (out of the TUI module) so both the
+// `crtr sys setup` panel and the regression suite exercise the exact same guard.
+//
+// A managed provider — whether an account row (has a label) or the provider header row (no label)
+// — MUST go through the coordinated removeManagedProvider, which owns
+// the rotation pool where every managed credential lives (a header removes every account). Only a
+// NON-managed configured provider deletes its raw auth.json credential; a raw auth.json delete on a
+// managed provider would leave the pool configured while the panel claims "Removed".
+import { join } from 'node:path';
+import { deleteAuthCredential } from './auth-file.js';
+import { removeManagedProvider } from './subscription-state.js';
+/** Route a row's removal to the coordinated service (managed) or auth.json (non-managed) and
+ *  return the truthful panel notice. May throw (e.g. an unknown-subscription error) — callers
+ *  surface that as the notice. */
+export async function removeProviderRow(agentDir, row) {
+    if (row.managed) {
+        await removeManagedProvider(row.providerId, row.label);
+        return row.label === undefined ? `Removed ${row.name}` : `Removed ${row.name} account`;
+    }
+    await deleteAuthCredential(row.providerId, join(agentDir, 'auth.json'));
+    return `Removed ${row.name}`;
+}

package/dist/core/render.d.ts

@@ -0,0 +1,12 @@
+import type { LeafHelp } from './help.js';
+import type { ErrorPayload } from './io.js';
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
+export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export declare function renderError(p: ErrorPayload): string;

package/dist/core/render.js

@@ -0,0 +1,127 @@
+// Default stdout rendering: the result a leaf returns is written FOR the model
+// to act on, not as data to parse. Output is a continuation of the agent's
+// prompt — PLAIN MARKDOWN, no XML wrapper. Scalars list as `- name: value`
+// bullets in output-schema order, prose fields render as paragraphs, and arrays
+// become a count lead-in plus a markdown table (objects) or bullets (scalars).
+// The raw JSON object is still available behind the `--json` global for tooling.
+//
+// A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
+// output that leads with the outcome (see `node new`, `push`).
+// Everything else falls through to the schema-driven generic renderer here, so
+// every command obeys the markdown paradigm without a hand-written renderer.
+// `renderError` is the one sanctioned exception: a failure is a different domain
+// from a result, so it keeps its `<error>` block.
+// Field names whose value is prose the agent reads, not a scalar it keys on —
+// these always render as their own paragraph, never as a `- name: value` bullet.
+const PROSE_FIELDS = new Set([
+    'follow_up', 'digest', 'message', 'next', 'result', 'content', 'body', 'guide',
+    'summary', 'note', 'reason', 'detail', 'details', 'hint', 'instruction',
+    'instructions', 'prompt', 'roadmap', 'report', 'answer', 'response', 'text',
+]);
+/** Minimal attribute-value sanitization: values here are controlled (ids,
+ *  statuses, counts), so collapse quotes rather than entity-escape. */
+function attrEsc(s) {
+    return String(s).replace(/"/g, "'").replace(/\n/g, ' ');
+}
+function scalarStr(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (Array.isArray(v))
+        return v.map(scalarStr).join(', ');
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+/** A string field is prose when it is named as such, spans lines, or is long
+ *  enough that it reads as a sentence rather than an identifier. */
+function isProse(name, v) {
+    if (typeof v !== 'string')
+        return false;
+    if (PROSE_FIELDS.has(name))
+        return true;
+    return v.includes('\n') || v.length > 80;
+}
+/** Keep a value safe inside a markdown table cell: pipes would split columns,
+ *  newlines would break the row. */
+function cellEsc(v) {
+    return scalarStr(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+/** An array renders as a count lead-in followed by the collection: a markdown
+ *  table when every element is an object, plain bullets otherwise. */
+function renderArray(name, arr) {
+    if (arr.length === 0)
+        return `0 ${name}.`;
+    const lead = `${arr.length} ${name}:`;
+    const allObjects = arr.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x));
+    if (allObjects) {
+        const rows = arr;
+        const cols = [];
+        for (const r of rows)
+            for (const k of Object.keys(r))
+                if (!cols.includes(k))
+                    cols.push(k);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = rows.map((r) => `| ${cols.map((c) => cellEsc(r[c])).join(' | ')} |`).join('\n');
+        return `${lead}\n\n${head}\n${sep}\n${body}`;
+    }
+    const items = arr.map((x) => `- ${scalarStr(x)}`).join('\n');
+    return `${lead}\n${items}`;
+}
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
+export function renderResult(result, help) {
+    const order = help.output.map((f) => f.name);
+    for (const k of Object.keys(result))
+        if (!order.includes(k))
+            order.push(k);
+    const bullets = [];
+    const proseFields = [];
+    const arrays = [];
+    for (const name of order) {
+        const v = result[name];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            arrays.push(renderArray(name, v));
+            continue;
+        }
+        if (isProse(name, v)) {
+            proseFields.push({ name, text: v });
+            continue;
+        }
+        // Scalars and nested objects alike list as a bullet (objects via compact JSON).
+        bullets.push(`- ${name}: ${scalarStr(v)}`);
+    }
+    const parts = [];
+    if (bullets.length > 0)
+        parts.push(bullets.join('\n'));
+    // Label prose only when more than one block would otherwise blur together.
+    const labelProse = proseFields.length > 1;
+    for (const { name, text } of proseFields) {
+        parts.push(labelProse ? `**${name}:** ${text}` : text);
+    }
+    for (const block of arrays)
+        parts.push(block);
+    return parts.join('\n\n');
+}
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export function renderError(p) {
+    const lines = [p.message];
+    if (p.received !== undefined && p.received !== null && p.received !== '') {
+        lines.push(`received: ${scalarStr(p.received)}`);
+    }
+    if (p.field !== undefined)
+        lines.push(`field: ${p.field}`);
+    // Its own labeled line: a transport status is a fact about the call, not about
+    // the value the caller supplied.
+    if (p.http_status !== undefined)
+        lines.push(`http status: ${p.http_status}`);
+    lines.push(`Next: ${p.next}`);
+    return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
+}

package/dist/core/resolver.d.ts

@@ -0,0 +1,14 @@
+import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
+export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];
+export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
+export declare function listAllPlugins(): InstalledPlugin[];
+export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;
+export interface ParsedSkillQualifier {
+    scope?: Scope;
+    segments: string[];
+}
+export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
+export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
+export declare function listAllMarketplaces(): InstalledMarketplace[];
+export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;
+export declare function scopeRootsLabel(): string;

package/dist/core/resolver.js

@@ -0,0 +1,136 @@
+import { join } from 'node:path';
+import { CONFIG_FILE } from '../types.js';
+import { readConfig } from './config.js';
+import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
+import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
+import { InputError } from './io.js';
+import { marketplacesDir, projectScopeRoot, scopeRoot, userScopeRoot, } from './scope.js';
+function pluginConfigForRoot(root) {
+    const cfg = readJsonIfExists(join(root, CONFIG_FILE));
+    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
+}
+export function listInstalledPluginsInRoot(scope, scopeRootPath) {
+    const dir = join(scopeRootPath, 'plugins');
+    if (!pathExists(dir))
+        return [];
+    const cfg = pluginConfigForRoot(scopeRootPath);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readPluginManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg[name];
+        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
+            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
+            version,
+        });
+    }
+    return out;
+}
+export function listInstalledPlugins(scope) {
+    // The builtin scope has no scopeRoot, so this returns [] — builtin content is
+    // the memory substrate, not plugins.
+    const root = scopeRoot(scope);
+    if (!root)
+        return [];
+    return listInstalledPluginsInRoot(scope, root);
+}
+export function listAllPlugins() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    scopes.push('builtin');
+    return scopes.flatMap(listInstalledPlugins);
+}
+export function findPluginByName(name, scope) {
+    if (scope) {
+        return listInstalledPlugins(scope).find((p) => p.name === name) ?? null;
+    }
+    for (const s of ['project', 'user', 'builtin'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
+        const match = listInstalledPlugins(s).find((p) => p.name === name);
+        if (match)
+            return match;
+    }
+    return null;
+}
+const SCOPE_QUALIFIERS = new Set(['user', 'project']);
+// Accepted identifier forms:
+//   <name>                         — bare name; scope-root first, then plugins
+//   <plugin>/<name>                — explicit plugin (plugin may contain slashes)
+//   <scope>/<name>                 — scope-root in a specific scope
+//   <scope>/<plugin>/<name>        — fully qualified
+export function parseSkillQualifier(raw) {
+    if (raw.includes(':')) {
+        const suggested = raw.replace(/:/g, '/');
+        throw new InputError({
+            error: 'invalid_qualifier',
+            message: "mixed separators ':' and '/' no longer supported; use slashes throughout",
+            received: raw,
+            field: 'name',
+            next: `Use ${suggested}.`,
+        });
+    }
+    const segments = raw.split('/');
+    if (SCOPE_QUALIFIERS.has(segments[0])) {
+        const scope = segments[0];
+        return { scope, segments: segments.slice(1) };
+    }
+    return { segments };
+}
+export function listInstalledMarketplaces(scope) {
+    const dir = marketplacesDir(scope);
+    if (!dir || !pathExists(dir))
+        return [];
+    const cfg = readConfig(scope);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readMarketplaceManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg.marketplaces[name];
+        const url = entry && entry.url !== undefined ? entry.url : '';
+        const ref = entry && entry.ref !== undefined ? entry.ref : 'main';
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            url,
+            ref,
+        });
+    }
+    return out;
+}
+export function listAllMarketplaces() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    return scopes.flatMap(listInstalledMarketplaces);
+}
+export function findMarketplaceByName(name, scope) {
+    if (scope) {
+        return listInstalledMarketplaces(scope).find((m) => m.name === name) ?? null;
+    }
+    for (const s of ['project', 'user']) {
+        if (s === 'project' && !projectScopeRoot())
+            continue;
+        const found = listInstalledMarketplaces(s).find((m) => m.name === name);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export function scopeRootsLabel() {
+    const proj = projectScopeRoot();
+    return proj ? `project=${proj}, user=${userScopeRoot()}` : `user=${userScopeRoot()}`;
+}

package/dist/core/runtime/__tests__/command-expansion.test.d.ts

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

package/dist/core/runtime/__tests__/command-expansion.test.js

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { expandDeterministicCommand, isDeterministicCommandExpansion, stripMarkdownComments } from '../command-expansion.js';
+test('slash-command expansion omits Markdown comments while preserving literal code examples', () => {
+    const body = [
+        '<!-- author-only $ARGUMENTS -->',
+        'Use $ARGUMENTS.',
+        '```html',
+        '<!-- literal example -->',
+        '```',
+        '`<!-- inline literal -->`',
+    ].join('\n');
+    assert.equal(expandDeterministicCommand({ kind: 'memory-slash', commandName: 'example', body }, 'topic'), 'Use topic.\n```html\n<!-- literal example -->\n```\n`<!-- inline literal -->`');
+    assert.equal(stripMarkdownComments('before <!-- hidden --> after'), 'before  after');
+    assert.equal(stripMarkdownComments('before\n<!-- hidden -->\nafter'), 'before\nafter');
+});
+test('deterministic expansion metadata accepts only the exact inert wire shape', () => {
+    assert.equal(isDeterministicCommandExpansion({ kind: 'memory-slash', commandName: 'dev', body: 'do it' }), true);
+    assert.equal(isDeterministicCommandExpansion({ kind: 'memory-slash', commandName: 'dev', body: 'do it', extra: true }), false);
+    assert.equal(isDeterministicCommandExpansion({ kind: 'memory-slash', commandName: 'dev', body: 1 }), false);
+    assert.equal(isDeterministicCommandExpansion({ kind: 'other', commandName: 'dev', body: 'do it' }), false);
+    assert.equal(isDeterministicCommandExpansion(Object.create({ kind: 'memory-slash', commandName: 'dev', body: 'do it' })), false);
+    assert.equal(isDeterministicCommandExpansion({ get kind() { return 'memory-slash'; }, commandName: 'dev', body: 'do it' }), false);
+    assert.equal(isDeterministicCommandExpansion(new Proxy({}, { getPrototypeOf() { throw new Error('hostile extension'); } })), false);
+});

package/dist/core/runtime/__tests__/engine-route.test.d.ts

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

package/dist/core/runtime/__tests__/engine-route.test.js

@@ -0,0 +1,36 @@
+// Run with: node --import tsx/esm --test src/core/runtime/__tests__/engine-route.test.ts
+//
+// Regression lock for resolveEngineRoute (broker.ts): the broker is
+// authoritative over prompt/follow_up routing against the LIVE session state.
+// m-C is the load-bearing case — a `follow_up` delivered to an IDLE session
+// used to be handed to pi's followUp(), whose queue only drains inside a
+// running agent loop, so the message was silently lost (observed live on the
+// northlight convo relay: queue_update, then nothing, message absent from the
+// session). An idle follow_up must run as a prompt.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveEngineRoute } from '../broker.js';
+const IMAGES = [{ type: 'image', data: 'aGk=', mimeType: 'image/png' }];
+test('m-C: follow_up on an IDLE session escalates to prompt (no streamingBehavior)', () => {
+    const route = resolveEngineRoute({ type: 'follow_up' }, false);
+    assert.deepEqual(route, { call: 'prompt', options: {} });
+});
+test('m-C: idle follow_up escalation carries images into PromptOptions', () => {
+    const route = resolveEngineRoute({ type: 'follow_up', images: IMAGES }, false);
+    assert.deepEqual(route, { call: 'prompt', options: { images: IMAGES } });
+});
+test('follow_up on a STREAMING session stays a true followUp (native queue)', () => {
+    const route = resolveEngineRoute({ type: 'follow_up', images: IMAGES }, true);
+    assert.deepEqual(route, { call: 'followUp' });
+});
+test('m-B: prompt on a STREAMING session gains streamingBehavior "steer"', () => {
+    const route = resolveEngineRoute({ type: 'prompt', images: IMAGES }, true);
+    assert.deepEqual(route, {
+        call: 'prompt',
+        options: { images: IMAGES, streamingBehavior: 'steer' },
+    });
+});
+test('prompt on an idle session passes through untouched', () => {
+    const route = resolveEngineRoute({ type: 'prompt' }, false);
+    assert.deepEqual(route, { call: 'prompt', options: {} });
+});

package/dist/core/runtime/__tests__/install-id-cache-scoping.test.d.ts

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

package/dist/core/runtime/__tests__/install-id-cache-scoping.test.js

@@ -0,0 +1,41 @@
+// install-id-cache-scoping.test.ts — regression for a real reviewed defect:
+// nodes.ts's lazy install-id cache (used by every in-process caller that
+// mints node ids without a full daemon boot, e.g. this test process) used to
+// be a single process-global value, even though openDb() deliberately
+// supports distinct concurrent CRTR_HOME values. Minting in home A, then
+// switching CRTR_HOME to a fresh home B, used to keep stamping A's install id
+// onto B's nodes. The lazy cache must be keyed by canvas-db identity so a
+// home switch can never leak one canvas's install id onto another's.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { closeDb } from '../../canvas/db.js';
+import { resolveInstallId } from '../../canvas/install-id.js';
+import { newNodeId } from '../nodes.js';
+let homeA;
+let homeB;
+before(() => {
+    homeA = mkdtempSync('/tmp/crtr-install-id-home-a-');
+    homeB = mkdtempSync('/tmp/crtr-install-id-home-b-');
+});
+beforeEach(() => {
+    closeDb();
+});
+after(() => {
+    closeDb();
+    rmSync(homeA, { recursive: true, force: true });
+    rmSync(homeB, { recursive: true, force: true });
+});
+test('newNodeId does not leak one CRTR_HOME\'s install id onto another after a home switch', () => {
+    process.env['CRTR_HOME'] = homeA;
+    const idFromA = newNodeId();
+    const installA = resolveInstallId();
+    assert.ok(idFromA.startsWith(`${installA}-`), 'a node minted in home A must be stamped with home A\'s install id');
+    closeDb();
+    process.env['CRTR_HOME'] = homeB;
+    const installB = resolveInstallId();
+    assert.notEqual(installB, installA, 'home A and home B must self-mint distinct install ids for this test to be meaningful');
+    const idFromB = newNodeId();
+    assert.ok(idFromB.startsWith(`${installB}-`), 'a node minted in home B after the switch must be stamped with home B\'s own install id, not the stale cached home A value');
+    assert.ok(!idFromB.startsWith(`${installA}-`), 'home B\'s minted id must never carry home A\'s install id');
+});

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,73 @@
+// Run with: node --import tsx/esm --test src/core/runtime/__tests__/node-env.test.ts
+//
+// Regression lock (0.3.62 roll regression class): `nodeEnv()` (`../nodes.ts`)
+// is the ONLY place a broker child's canvas-home path override (CRTR_HOME) and
+// subtree pointer (CRTR_SUBTREE) 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 makes a broker boot healthy but open a DIFFERENT canvas
+// than every other process on the host.
+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_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_HOME is propagated from ambient env into the broker child env', () => {
+    process.env.CRTR_HOME = '/mnt/canvas-home';
+    const env = nodeEnv(node());
+    assert.equal(env.CRTR_HOME, '/mnt/canvas-home');
+});
+test('unset ambient path overrides are omitted, never emitted as empty strings', () => {
+    // CRTR_HOME/CRTR_SUBTREE both deleted by beforeEach.
+    const env = nodeEnv(node());
+    assert.equal('CRTR_HOME' in env, false);
+    assert.equal('CRTR_SUBTREE' 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/__tests__/spawn-at-given-id.test.d.ts

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

package/dist/core/runtime/__tests__/spawn-at-given-id.test.js

@@ -0,0 +1,34 @@
+// spawn-at-given-id.test.ts — regression for the reviewed opaque-id-contract
+// violation (finding 3): the old validator required >=2 hyphen segments and
+// rejected a hyphen-less id outright, contradicting the design's "opaque,
+// never parsed for structure" ID scheme. Duplicate-rejection is covered by
+// spawn-worktree-id-conflict.test.ts (the actual reviewed defect); it is not
+// re-asserted here to avoid restating already-covered feature behavior.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { closeDb } from '../../canvas/db.js';
+import { getNode } from '../../canvas/canvas.js';
+import { spawnNode } from '../nodes.js';
+let home;
+before(() => {
+    home = mkdtempSync('/tmp/crtr-spawn-at-id-');
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+test('spawnNode({ nodeId }): a hyphen-less opaque id (no minimum segment count) is valid and spawns at the exact given id', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'remote42' });
+    assert.equal(meta.node_id, 'remote42');
+    assert.notEqual(getNode('remote42'), null);
+});
+test('spawnNode({ nodeId }): a charset-unsafe or oversized id is still rejected with a usage error before the canvas is touched', () => {
+    assert.throws(() => spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'BadID!' }), /invalid --node-id/);
+    assert.throws(() => spawnNode({ kind: 'general', cwd: '/tmp/work', nodeId: 'a'.repeat(129) }), /invalid --node-id/);
+});

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

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