@crouton-kit/crouter 0.3.65 → 0.3.67

package/dist/builtin-memory/05-kinds/developer/00-base.md

@@ -17,4 +17,4 @@ You are an implementation agent. Your job is to **implement this feature or chan
 
 Work directly. Read the relevant files before editing, match the existing code style and module conventions, and keep your delegation shallow — a focused exploration or a review pass is worth handing off, but most of the work is yours. Throw errors early; no silent fallbacks. Break things correctly rather than patching them badly; prefer clean, breaking changes over backwards-compat hacks in pre-production code.
 
-Done means **provably correct against the spec's acceptance criteria** — not "it builds," not "the tests pass." Green output proves the code ran, not that it does what was asked; check the result against each acceptance criterion yourself. On a load-bearing change, get it critiqued by something other than you before calling it done — spawn a reviewer on the diff and fold in what it finds. And if the change outgrows what one window can finish well — many files, several phases, a design that keeps moving — promote yourself into a developer orchestrator and decompose it rather than grinding past the edge of your context.
+Done means **provably correct against the spec's acceptance criteria** — not "it builds," not "the tests pass." Green output proves the code ran, not that it does what was asked; check the result against each acceptance criterion yourself. On a load-bearing change, get it critiqued by something other than you before calling it done — spawn a reviewer on the diff and fold in what it finds. But validate judiciously: a delegate's green report is settled evidence — don't re-run a suite or re-read a diff that already cleared its gate; check only what changed since. And if the change outgrows what one window can finish well — many files, several phases, a design that keeps moving — promote yourself into a developer orchestrator and decompose it rather than grinding past the edge of your context.

package/dist/builtin-memory/05-kinds/developer/01-orchestrator.md

@@ -12,4 +12,6 @@ Before you shape the roadmap, read `crtr memory read development` for the roadma
 
 Stay flexible, not waterfall. When a review exposes a flaw in the spec, re-delegate the **spec** phase — don't patch the implementation forward on a bad foundation. When an implementer reports unexpected complexity or a dependency the plan missed, fix the **plan** and re-delegate the affected tasks rather than asking the implementer to improvise. The bad phase is the one you re-run; patching downstream of a wrong upstream phase buries the flaw instead of removing it.
 
+Validate judiciously — trust the agent. A gate that already ran green is settled evidence: when a child reports its build clean, its suite passing, or a reviewer reports the diff read, take the report and move on — do not re-run the same suite, rebuild the same tree, or re-read the same code to reassure yourself. Attach each new check to what *changed* since the last green gate (the fix diff, the new tests), never the whole feature from scratch; re-verify a report only when it is internally inconsistent or contradicted by evidence, not on general suspicion. Redundant re-validation burns whole windows and adds no information — the second identical green proves nothing the first didn't.
+
 Post-implementation review is not one generic "review this" pass — it is several distinct perspectives, each its own assessment: does this **reuse** what the codebase already provides rather than reinventing it, is the **quality** sound, is it **efficient**, and are the **tests** real rather than green theatre. Hand each lens to its own reviewer so it assesses independently. Size the reviewer to the surface: a small focused diff goes to a single `review` worker; a whole feature's worth of files goes to a `review` orchestrator that fans the lenses across it and returns one verdict.

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/__tests__/provider-rotation.test.ts

@@ -1074,10 +1074,10 @@ test("treats a request timeout as transient: retries the SAME provider in place,
   }
 });
 
-// Regression: when a transient blip never recovers, the turn must end with a clear,
-// actionable error instead of spinning forever or silently rotating a healthy credential
-// away to a fallback provider that was never the actual problem.
-test("ends the turn without rotating once the transient retry budget is exhausted", async () => {
+// Once the in-place transient retry budget is exhausted, the failure is surfaced to the
+// user AND the credential is rotated away: the struggling credential cools down briefly and
+// the turn continues on the fallback provider, rather than hard-failing.
+test("surfaces the transient error and rotates to the fallback once the in-place retry budget is exhausted", async () => {
   resetRotationState();
   writeLadderConfig();
   helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
@@ -1085,6 +1085,10 @@ test("ends the turn without rotating once the transient retry budget is exhauste
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
   ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
+  const notifications: Array<{ message: string; level: string }> = [];
+  ctx.ui.notify = (message: string, level: string) => {
+    notifications.push({ message, level });
+  };
   const streamedModels: any[] = [];
   const sleepCalls: number[] = [];
   rotationModule.__setSleepForTest(async (ms) => {
@@ -1093,8 +1097,12 @@ test("ends the turn without rotating once the transient retry budget is exhauste
   rotationModule.__setStreamForProviderForTest((model) => {
     streamedModels.push(model);
     return (async function* () {
-      // 503 with no retry-after header is transient by STATUS, not just by message.
-      yield { type: "error", error: Object.assign(new Error("Service Unavailable"), { status: 503 }) };
+      if (model.provider === "anthropic") {
+        // 503 with no retry-after header is transient by STATUS, not just by message.
+        yield { type: "error", error: Object.assign(new Error("Service Unavailable"), { status: 503 }) };
+        return;
+      }
+      yield { type: "text_delta", text: "hello from codex fallback" };
     })() as any;
   });
 
@@ -1108,13 +1116,17 @@ test("ends the turn without rotating once the transient retry budget is exhauste
     const emitted = [] as any[];
     for await (const event of stream) emitted.push(event);
 
-    assert.deepEqual(setModelCalls, []);
-    assert.deepEqual(streamedModels.map((m) => m.provider), ["anthropic", "anthropic", "anthropic"]);
+    // Retried the same anthropic credential in place (3 attempts) then rotated to codex.
+    assert.equal(streamedModels.filter((m) => m.provider === "anthropic").length, 3);
     assert.deepEqual(sleepCalls, [250, 750]);
-    assert.equal(emitted.length, 1);
-    assert.equal(emitted[0].type, "error");
-    assert.match(emitted[0].error.errorMessage, /transient error after 3 attempts/);
-    assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 0);
+    assert.deepEqual(setModelCalls.map((m) => m.provider), ["openai-codex"]);
+    // The turn was served on the fallback, never failed with a terminal error.
+    assert.ok(emitted.some((e) => e.type === "text_delta"));
+    assert.ok(!emitted.some((e) => e.type === "error"));
+    // The user was told about the transient failure AND that it rotated.
+    assert.ok(notifications.some((n) => /transient error after 3 attempts/.test(n.message) && /rotating/i.test(n.message)));
+    // The struggling anthropic credential was cooled down so rotation moved on.
+    assert.ok(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil > Date.now());
   } finally {
     rotationModule.__setStreamForProviderForTest(undefined);
     rotationModule.__setSleepForTest(undefined);

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.ts

@@ -47,17 +47,23 @@ const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
 // not a wait. Cap at the same window as our own default rate-limit backoff.
 const SOLE_PROVIDER_MAX_WAIT_MS = DEFAULT_RATE_LIMIT_BACKOFF_MS;
 // Short in-place retry budget for a transient network/5xx blip on the SAME credential
-// (#122): a couple of quick retries, no cooldown, no rotation to another credential or
-// provider. Once this budget is exhausted the turn ends with an actionable error.
+// (#122): a couple of quick retries, no cooldown. Once this budget is exhausted we no
+// longer hard-fail the turn -- we surface the error and rotate (see TRANSIENT_ROTATE below).
 const TRANSIENT_RETRY_BACKOFFS_MS = [250, 750];
+// After the in-place transient retry budget is exhausted, rotate instead of failing: the
+// credential itself is probably healthy (this is a provider-side blip like "overloaded"),
+// so cool it down only briefly -- long enough to rotate to another credential / fallback
+// provider, short enough that it comes back quickly if it was the only option.
+const TRANSIENT_ROTATE_COOLDOWN_MS = 60 * 1000;
 
 let runtimeContext: ExtensionContext | undefined;
 let extensionAPI: ExtensionAPI | undefined;
 
 type AttemptResult = {
-  result: "success" | "rate_limited" | "fatal";
+  result: "success" | "rate_limited" | "transient_exhausted" | "fatal";
   retryAfterMs?: number;
   attemptAt: number;
+  attempts?: number;
   classification?: ProviderErrorClassification;
 };
 
@@ -466,21 +472,16 @@ async function streamProviderAttempt(
       return { result: "rate_limited", retryAfterMs: requestedRetryAfterMs, attemptAt, classification };
     }
 
-    // Transient: retry the SAME credential/provider in place -- no cooldown, no rotation.
+    // Transient: retry the SAME credential/provider in place first -- no cooldown for the
+    // quick in-place budget.
     const backoffMs = TRANSIENT_RETRY_BACKOFFS_MS[attempt - 1];
     if (backoffMs === undefined) {
-      // Exhausted the short in-place retry budget: surface a clear terminal error rather
-      // than spinning forever or silently rotating a healthy credential away.
-      bufferedEvents.push({
-        type: "error",
-        reason: "error",
-        error: toAssistantError(
-          model,
-          `${getProviderLabel(providerId)} "${credential.label}" hit a transient error after ${attempt} attempts (${classification.reason})`,
-        ),
-      });
-      flush();
-      return { result: "fatal", attemptAt, classification };
+      // In-place retry budget exhausted. Rather than hard-failing the turn, hand back a
+      // transient-exhausted result so the caller surfaces the error to the user AND rotates
+      // to another credential / fallback provider. Nothing is emitted into the stream here:
+      // the buffered (pre-content) events are discarded exactly like the rate-limit path, so
+      // the rotation target streams a clean turn.
+      return { result: "transient_exhausted", attemptAt, classification, attempts: attempt };
     }
     logRotation(
       `${getProviderLabel(providerId)} subscription "${credential.label}" hit a transient error (${classification.reason}, status=${classification.status ?? "n/a"}); retrying same credential in ${backoffMs}ms (attempt ${attempt + 1})`,
@@ -599,6 +600,30 @@ async function runManagedProvider(
       logRotation(
         `${getProviderLabel(providerId)} subscription "${freshCredential.label}" rate-limited (status=${result.classification?.status ?? "n/a"}, reason=${result.classification?.reason ?? "unclassified"}, ${retryAfterPart}); cooling down for ${Math.ceil(cooldownMs / 1000)}s, trying next credential`,
       );
+      // Surface the rotation to the user too (parity with the transient-exhausted path), so a
+      // rate-limit-driven credential/provider switch is visible rather than silent.
+      runtimeContext?.ui.notify?.(
+        `${getProviderLabel(providerId)} "${freshCredential.label}" rate-limited (cooling down ${Math.ceil(cooldownMs / 1000)}s); rotating to another credential/provider.`,
+        "warn",
+      );
+      continue;
+    }
+
+    if (result.result === "transient_exhausted") {
+      // The credential is likely healthy -- this was a provider-side transient blip (e.g.
+      // "overloaded") that survived the in-place retries. Surface it to the user and rotate:
+      // cool the credential down briefly so this loop (and the pool-exhaustion logic below)
+      // moves on to the next credential / fallback provider instead of failing the turn.
+      const reason = result.classification?.reason ?? "transient error";
+      markSubscriptionRateLimited(providerId, freshCredential.label, TRANSIENT_ROTATE_COOLDOWN_MS, result.attemptAt);
+      runtimeContext?.ui.notify?.(
+        `${getProviderLabel(providerId)} "${freshCredential.label}" hit a transient error after ${result.attempts ?? 1} attempts (${reason}); rotating to another credential/provider.`,
+        "warn",
+      );
+      logRotation(
+        `${getProviderLabel(providerId)} subscription "${freshCredential.label}" transient error exhausted (reason=${reason}, status=${result.classification?.status ?? "n/a"}); cooling down ${Math.ceil(TRANSIENT_ROTATE_COOLDOWN_MS / 1000)}s and rotating`,
+      );
+      setStatus(formatStatusLine(providerId));
       continue;
     }
 

package/dist/clients/attach/__tests__/attach-chrome-remote.test.d.ts

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

package/dist/clients/attach/__tests__/attach-chrome-remote.test.js

@@ -0,0 +1,371 @@
+// attach-chrome-remote.test.ts — the safe-defaults contract for the attach
+// chrome (buildCanvasPanelLines + GraphOverlay) when the `canvasSource` is a
+// RemoteCanvasSource, i.e. `crtr surface attach --canvas <name>`.
+//
+// Adversarial, not merely a clean-machine assertion (mirrors
+// core/canvas/__tests__/render-remote.test.ts): BEFORE rendering, this test
+// seeds real, CONFLICTING local state for node id `a` — a poisoned telemetry
+// reading (context tokens + a live-activity cue), an active fault, a local
+// tmux focus, and a broker attach.json marking it human-watched — every
+// historically-broken local read the remote suppression in nav-model.ts is
+// supposed to bypass. If the production suppression ever regressed back to
+// consulting local disk/SQLite for a remote id, the rendered lines below would
+// carry the poisoned tokens/glyph/background instead of the safe defaults, so
+// a clean-machine run could never mask the regression.
+//
+// Also proves the read-only contract: GraphOverlay's Enter/m/x key handlers
+// must no-op against a remote graph row instead of shelling local
+// `crtr node focus` / `crtr node lifecycle close`.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RemoteCanvasSource } from '../../../core/canvas/remote-canvas-source.js';
+import { createNode } from '../../../core/canvas/canvas.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { openFocusRow } from '../../../core/canvas/focuses.js';
+import { jobDir } from '../../../core/canvas/paths.js';
+import { recordFault } from '../../../core/runtime/fault.js';
+import { BG_ATTACHED } from '../../../core/canvas/nav-model.js';
+import { dispatchSlashCommand, slashCommandList } from '../slash-commands.js';
+import { resolveInitialMode, requestModeSwitch, tagAttachPane, untagAttachPane, reapOnDetach, } from '../attach-cmd.js';
+import { buildCanvasPanelLines } from '../canvas-panels.js';
+import { GraphOverlay } from '../graph-overlay.js';
+function startMockCrtrServer(route) {
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                const bodyText = Buffer.concat(chunks).toString('utf8');
+                const parsed = JSON.parse(bodyText);
+                const result = route(parsed.args);
+                res.writeHead(result.status ?? 200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify(result.body), stderr: '' }));
+            });
+        });
+        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())),
+            });
+        });
+    });
+}
+function meta(id, extra) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...extra,
+    };
+}
+function show(node, reports, managers) {
+    return {
+        node,
+        reports: reports.map((id) => ({ node_id: id, name: id, kind: 'general', status: 'active', active: true })),
+        managers: managers.map((id) => ({ node_id: id, name: id, kind: 'general', status: 'active', active: true })),
+        artifacts: { report: 0, doc: 0, roadmap: 0 },
+        pending_triggers: 0,
+        paths: { context_dir: '/tmp/context', reports_dir: '/tmp/reports', session_file: null },
+        follow_up: '',
+    };
+}
+const IDENTITY_PALETTE = {
+    accent: (s) => s,
+    active: (s) => s,
+    info: (s) => s,
+    muted: (s) => s,
+    faint: (s) => s,
+    border: (s) => s,
+    bold: (s) => s,
+    error: (s) => s,
+    warning: (s) => s,
+    bashMode: (s) => s,
+    bashModeAlt: (s) => s,
+    surface: (s) => s,
+};
+/** A fake `TUI` carrying just what `GraphOverlay` touches: `showOverlay` (a
+ *  no-op handle) and `requestRender`. GraphOverlay's key handlers only shell
+ *  `crtr` (via execFile) and toggle local overlay/handle state — they never
+ *  reach into the real TUI beyond these two calls. */
+function fakeTui() {
+    let renders = 0;
+    const tui = {
+        showOverlay: () => ({
+            hide: () => { },
+            setHidden: () => { },
+            isHidden: () => false,
+            focus: () => { },
+            unfocus: () => { },
+            isFocused: () => true,
+        }),
+        requestRender: () => { renders++; },
+    };
+    return { tui, renderCount: () => renders };
+}
+let home;
+let localCwd;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-attach-chrome-remote-'));
+    localCwd = mkdtempSync(join(tmpdir(), 'crtr-attach-chrome-remote-cwd-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(localCwd, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+/** Seed conflicting local state for node id `a` — every local read the
+ *  attach-chrome remote suppression is supposed to bypass. */
+function seedPoisonedLocalState() {
+    createNode(meta('a', { cwd: localCwd }));
+    // A local focus — poisons focusedNodeIds()/isAttached's fast path.
+    openFocusRow('poison-focus', null, null, 'a');
+    // A broker attach.json — poisons isAttached's slow path.
+    writeFileSync(join(jobDir('a'), 'attach.json'), JSON.stringify({ viewers: 1 }));
+    // An active, manually-retried fault — poisons nodeGlyph's hanging overlay.
+    recordFault('a', {
+        link: 'viewer↔broker',
+        op: 'poison',
+        kind: 'other',
+        retry: { disposition: 'manual' },
+        message: 'POISON FAULT — local read leaked into remote attach chrome',
+    });
+    // Local telemetry — poisons tokensCell + activityCell.
+    writeFileSync(join(jobDir('a'), 'telemetry.json'), JSON.stringify({
+        context_tokens: 999_999,
+        last_activity: 'POISON ACTIVITY — local read leaked into remote attach chrome',
+    }));
+}
+test('buildCanvasPanelLines suppresses every local-read adornment for a RemoteCanvasSource, even with conflicting local state for the same node id', async () => {
+    seedPoisonedLocalState();
+    const rootMeta = meta('root');
+    const aMeta = meta('a'); // the REMOTE node's meta — unrelated to the poisoned local NodeMeta above
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            const id = args[4];
+            if (id === 'root')
+                return { body: show(rootMeta, ['a'], []) };
+            if (id === 'a')
+                return { body: show(aMeta, [], ['root']) };
+        }
+        return { status: 500, body: {} };
+    });
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    // 'root' has 'a' as a live report → row('a') renders into `reports`.
+    const { reports } = await buildCanvasPanelLines('root', {}, IDENTITY_PALETTE, source);
+    assert.equal(reports.length, 1);
+    const line = reports[0];
+    assert.ok(!line.includes('1000k'), `local telemetry (999999 tokens) must not leak into a remote row: ${line}`);
+    assert.ok(!line.includes('POISON'), `poisoned local text must never appear in a remote row: ${line}`);
+    assert.ok(!line.includes('⚠'), `a local active fault must not surface as the hanging glyph on a remote row: ${line}`);
+    assert.ok(!line.includes(BG_ATTACHED), `a local focus/attach must not paint a remote row as attached: ${line}`);
+    await server.close();
+});
+test('GraphOverlay suppresses every local-read adornment for a RemoteCanvasSource AND makes Enter/m/x no-ops, even with conflicting local state for the same node id', async () => {
+    seedPoisonedLocalState();
+    const rootMeta = meta('root');
+    const aMeta = meta('a');
+    const server = await startMockCrtrServer((args) => {
+        if (args[1] === 'node' && args[2] === 'inspect' && args[3] === 'show') {
+            const id = args[4];
+            if (id === 'root')
+                return { body: show(rootMeta, ['a'], []) };
+            if (id === 'a')
+                return { body: show(aMeta, [], ['root']) };
+        }
+        return { status: 500, body: {} };
+    });
+    const source = new RemoteCanvasSource(server.url, 'tok');
+    const { tui } = fakeTui();
+    const overlay = new GraphOverlay(tui, 'root', () => ({}), IDENTITY_PALETTE, source);
+    overlay.open();
+    // buildSnapshot() is async (chased through the mock server); poll for it to land.
+    for (let i = 0; i < 100 && overlay.snapshot === undefined; i++) {
+        await new Promise((r) => setImmediate(r));
+    }
+    assert.notEqual(overlay.snapshot, undefined, 'snapshot never built');
+    const lines = overlay.render(100).join('\n');
+    assert.ok(!lines.includes('1000k'), `local telemetry must not leak into the remote graph overlay: ${lines}`);
+    assert.ok(!lines.includes('POISON'), `poisoned local text must never appear in the remote graph overlay: ${lines}`);
+    assert.ok(!lines.includes('⚠'), `a local active fault must not surface as the hanging glyph in the remote graph overlay: ${lines}`);
+    assert.ok(!lines.includes(BG_ATTACHED), `a local focus/attach must not paint a remote row as attached in the graph overlay: ${lines}`);
+    // Footer hint must drop the focus/kill/mgr hints in remote mode.
+    assert.ok(!lines.includes('kill'), `remote overlay footer must not advertise kill: ${lines}`);
+    assert.ok(!lines.includes('focus') && !lines.includes('mgr'), `remote overlay footer must not advertise focus/mgr: ${lines}`);
+    // Enter must NOT close the overlay (a local `close()` is the observable
+    // effect of a real `focusTarget` dispatch) — it must no-op instead.
+    overlay.handleInput('\r');
+    assert.equal(overlay.isOpen(), true, 'Enter must not act (close) on a remote graph row');
+    // x must NOT arm the y/n kill confirm — render() would show it in the hint.
+    overlay.handleInput('x');
+    const afterX = overlay.render(100).join('\n');
+    assert.ok(!afterX.includes('y/n'), `x must not arm a kill confirm on a remote graph row: ${afterX}`);
+    // m must NOT close the overlay either (it would focusTarget the manager).
+    overlay.handleInput('m');
+    assert.equal(overlay.isOpen(), true, 'm must not act (close) on a remote graph row');
+    await server.close();
+});
+// ---------------------------------------------------------------------------
+// Phase 3 review 2 — the ENCLOSING attach viewer (slash commands, pane tag,
+// detach-reap, Alt+M mode-switch), not just the GraphOverlay/panel rendering
+// the fix above already covers. Same adversarial shape: seed colliding LOCAL
+// state for the remote node id `a`, then assert the remote path never touches
+// it — and, symmetrically, that the LOCAL path is byte-for-byte unchanged
+// (every guard below defaults to acting exactly as before when `remote` is
+// `false`).
+// ---------------------------------------------------------------------------
+function fakeSlashContext(remote, nodeId) {
+    const notices = [];
+    const sent = [];
+    const ctx = {
+        send: (frame) => sent.push(frame),
+        notify: (m) => notices.push(m),
+        cwd: '/tmp/does-not-matter',
+        // Explicit empty string (not `undefined`) so promoteNode/openContext's
+        // `ctx.nodeId ?? process.env['CRTR_NODE_ID']` fallback can NEVER pick up
+        // this test process's own real CRTR_NODE_ID (this test runs INSIDE a live
+        // crtr node) — the local-mode assertions below must reach the real
+        // no-node-id early return, never an accidental real `crtr node promote`
+        // against ourselves.
+        nodeId: '',
+        remote,
+    };
+    return { ctx, notices, sent };
+}
+test('slash autocomplete structurally omits the local-only native canvas commands (/promote, /resume-node, /context) in remote mode, and keeps them in local mode', () => {
+    const remoteNames = slashCommandList(undefined, true).map((c) => c.name);
+    assert.ok(!remoteNames.includes('promote'), `remote autocomplete must not offer /promote: ${remoteNames.join(',')}`);
+    assert.ok(!remoteNames.includes('resume-node'), `remote autocomplete must not offer /resume-node: ${remoteNames.join(',')}`);
+    assert.ok(!remoteNames.includes('context'), `remote autocomplete must not offer /context: ${remoteNames.join(',')}`);
+    // Remote-safe canvas commands stay offered.
+    assert.ok(remoteNames.includes('graph'), 'remote autocomplete must still offer /graph (already remote-safe)');
+    assert.ok(remoteNames.includes('view'), 'remote autocomplete must still offer /view (self-contained popup)');
+    // Local (remote=false, the default) is unchanged — all five canvas commands.
+    const localNames = slashCommandList().map((c) => c.name);
+    for (const name of ['graph', 'promote', 'resume-node', 'view', 'context']) {
+        assert.ok(localNames.includes(name), `local autocomplete must still offer /${name}: ${localNames.join(',')}`);
+    }
+});
+test('dispatchSlashCommand no-ops /promote, /resume-node, /context in remote mode instead of shelling a local crtr command', () => {
+    const { ctx, notices, sent } = fakeSlashContext(true, 'a');
+    for (const cmd of ['/promote', '/resume-node', '/context', '/promote orchestrator']) {
+        notices.length = 0;
+        const handled = dispatchSlashCommand(cmd, ctx);
+        assert.equal(handled, true, `${cmd} must be handled (native, never forwarded to the engine as a prompt)`);
+        assert.equal(notices.length, 1, `${cmd} must notify exactly once (the remote-unsafe notice), got: ${JSON.stringify(notices)}`);
+        assert.match(notices[0], /not available for a remote attach/, `${cmd} must notify the remote-unsafe message, not proceed into its local handler: ${notices[0]}`);
+    }
+    assert.equal(sent.length, 0, 'no command frame must ever be sent for a gated remote canvas command');
+    // /graph and /view are UNaffected by the remote gate (graph is already
+    // remote-safe via GraphOverlay's own `remote` handling; view is self-
+    // contained). Neither reaches the remote-unsafe notice.
+    notices.length = 0;
+    ctx.onGraph = () => notices.push('graph-toggled');
+    dispatchSlashCommand('/graph', ctx);
+    assert.deepEqual(notices, ['graph-toggled'], '/graph must still work normally in remote mode');
+});
+test('dispatchSlashCommand leaves the LOCAL (non-remote) path for /promote, /resume-node, /context byte-for-byte unchanged', () => {
+    const { ctx, notices } = fakeSlashContext(false, '');
+    // No TMUX in this test process (a headless `node --test` run), so
+    // /resume-node and /context hit their OWN "needs tmux" notices — proving
+    // dispatch reached their real local handlers, not our new remote gate.
+    const savedTmux = process.env['TMUX'];
+    const savedTmuxPane = process.env['TMUX_PANE'];
+    delete process.env['TMUX'];
+    delete process.env['TMUX_PANE'];
+    try {
+        notices.length = 0;
+        dispatchSlashCommand('/promote', ctx);
+        assert.deepEqual(notices, ['/promote: no node to promote (viewer has no node id)']);
+        notices.length = 0;
+        dispatchSlashCommand('/resume-node', ctx);
+        assert.deepEqual(notices, ['/resume-node needs tmux']);
+        notices.length = 0;
+        dispatchSlashCommand('/context', ctx);
+        assert.deepEqual(notices, ['/context needs tmux']);
+    }
+    finally {
+        if (savedTmux !== undefined)
+            process.env['TMUX'] = savedTmux;
+        else
+            delete process.env['TMUX'];
+        if (savedTmuxPane !== undefined)
+            process.env['TMUX_PANE'] = savedTmuxPane;
+        else
+            delete process.env['TMUX_PANE'];
+    }
+});
+test('resolveInitialMode/requestModeSwitch never touch the local mode-switch read/write for a remote attach, and are unchanged for local', () => {
+    let reads = 0;
+    const readMode = (_cwd, _nodeId) => {
+        reads++;
+        return 'plan'; // poisoned value — must never surface for remote
+    };
+    assert.equal(resolveInitialMode('/tmp/cwd', 'a', true, readMode), 'normal', 'remote must always start normal');
+    assert.equal(reads, 0, 'remote must never read the local mode-switch current file');
+    assert.equal(resolveInitialMode('/tmp/cwd', 'a', false, readMode), 'plan', 'local must read through unchanged');
+    assert.equal(reads, 1, 'local must call the injected local reader exactly once');
+    let writes = 0;
+    let lastWrite;
+    const writeRequest = (cwd, nodeId, mode) => {
+        writes++;
+        lastWrite = { cwd, nodeId, mode };
+    };
+    const remoteOk = requestModeSwitch('/tmp/cwd', 'a', true, 'spec', writeRequest);
+    assert.equal(remoteOk, false, 'remote Alt+M must no-op (return false)');
+    assert.equal(writes, 0, 'remote must never write the local mode-switch request file');
+    const localOk = requestModeSwitch('/tmp/cwd', 'a', false, 'spec', writeRequest);
+    assert.equal(localOk, true, 'local Alt+M must still write through');
+    assert.equal(writes, 1, 'local must call the injected local writer exactly once');
+    assert.deepEqual(lastWrite, { cwd: '/tmp/cwd', nodeId: 'a', mode: 'spec' });
+});
+test('tagAttachPane/untagAttachPane never tag/untag the pane for a remote attach, and are unchanged for local', () => {
+    let calls = [];
+    const setOpt = (pane, name, value) => {
+        calls.push([pane, name, value]);
+    };
+    calls = [];
+    tagAttachPane(true, '%3', 'a', setOpt);
+    assert.deepEqual(calls, [], 'remote must never tag the pane with @crtr_node');
+    calls = [];
+    tagAttachPane(false, '%3', 'a', setOpt);
+    assert.deepEqual(calls, [['%3', '@crtr_node', 'a']], 'local tag must still fire unchanged');
+    calls = [];
+    untagAttachPane(true, '%3', setOpt);
+    assert.deepEqual(calls, [], 'remote must never untag the pane');
+    calls = [];
+    untagAttachPane(false, '%3', setOpt);
+    assert.deepEqual(calls, [['%3', '@crtr_node', '']], 'local untag must still fire unchanged');
+    // No pane resolved (outside tmux) — unaffected either way.
+    calls = [];
+    tagAttachPane(false, undefined, 'a', setOpt);
+    assert.deepEqual(calls, [], 'no pane to tag when outside tmux');
+});
+test('reapOnDetach never reaps a local node for a remote attach even on an id collision, and is unchanged for local', () => {
+    let reaped = [];
+    const reap = (nodeId) => {
+        reaped.push(nodeId);
+    };
+    reaped = [];
+    reapOnDetach(true, 'a', reap);
+    assert.deepEqual(reaped, [], 'remote detach must never reap a local node, even one colliding with the remote id');
+    reaped = [];
+    reapOnDetach(false, 'a', reap);
+    assert.deepEqual(reaped, ['a'], 'local detach-reap must still fire unchanged');
+});

package/dist/clients/attach/__tests__/attach-remote-readonly.test.d.ts

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