@north-light/crouter 0.3.263 → 0.3.270

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -337,7 +337,13 @@ test("picker and Alt+M choices each clear logical routing, and Alt+M / Shift+Tab
     const parent = h.spawnRoot('model durability parent');
     seedPool('anthropic', false);
     seedPool('openai-codex', false);
-    const pickerNode = await h.spawnHeadlessChild(parent, 'picker durability child', { model: 'openai/strong' });
+    const userConfigDir = join(h.agentHome, '.crouter');
+    const userConfigPath = join(userConfigDir, 'config.json');
+    mkdirSync(userConfigDir, { recursive: true });
+    writeFileSync(userConfigPath, JSON.stringify({
+        kinds: { 'test/logical-openai': { whenToUse: 'Logical OpenAI routing test.', model: 'openai/strong' } },
+    }));
+    const pickerNode = await h.spawnHeadlessChild(parent, 'picker durability child', { kind: 'test/logical-openai' });
     const pickerBefore = h.node(pickerNode);
     assert.deepEqual(pickerBefore.launch?.modelIntent, { family: 'openai', strength: 'strong' }, 'picker fixture starts from a logical launch preference');
     assert.equal(pickerBefore.launch?.env.CRTR_MODEL_INTENT, 'openai/strong');
@@ -358,7 +364,7 @@ test("picker and Alt+M choices each clear logical routing, and Alt+M / Shift+Tab
     // A separate logical launch reaches Alt+M with BOTH intent representations
     // still populated. This is the regression path: a user-selected ladder rung
     // must clear them before a restart can resolve the stale route over it.
-    const ladderNode = await h.spawnHeadlessChild(parent, 'ladder durability child', { model: 'openai/strong' });
+    const ladderNode = await h.spawnHeadlessChild(parent, 'ladder durability child', { kind: 'test/logical-openai' });
     const ladderBefore = h.node(ladderNode);
     assert.deepEqual(ladderBefore.launch?.modelIntent, { family: 'openai', strength: 'strong' }, 'Alt+M starts with durable logical modelIntent present');
     assert.equal(ladderBefore.launch?.env.CRTR_MODEL_INTENT, 'openai/strong', 'Alt+M starts with the launch environment intent present');
@@ -388,6 +394,7 @@ test("picker and Alt+M choices each clear logical routing, and Alt+M / Shift+Tab
     assert.equal(replay.argv[modelArg + 1], expected, 'the replayed model argument carries both choices');
     assert.equal(replay.env.CRTR_MODEL_INTENT, undefined, 'the stale logical intent is absent from the restarted broker environment');
     ladderCtrl.close();
+    rmSync(userConfigPath, { force: true });
 });
 test('reload_auth restores a newly authenticated personal route before the next idle prompt', { timeout: 30_000 }, async () => {
     const personal = { provider: 'personal-anthropic', id: 'claude-personal' };
@@ -398,6 +405,7 @@ test('reload_auth restores a newly authenticated personal route before the next
     const unauthenticatedProvider = join(h.home, 'fake-pi.unauthenticated-provider');
     mkdirSync(userConfigDir, { recursive: true });
     writeFileSync(userConfigPath, JSON.stringify({
+        kinds: { general: { whenToUse: 'General work.', model: 'anthropic/medium' } },
         modelRoutes: {
             personal: { family: 'anthropic', credentialSource: 'user', providerId: personal.provider, models: { ultra: personalSpec, strong: personalSpec, medium: personalSpec, light: personalSpec } },
             funded: { family: 'anthropic', credentialSource: 'northlight', providerId: funded.provider, models: { ultra: `${funded.provider}/${funded.id}:medium`, strong: `${funded.provider}/${funded.id}:medium`, medium: `${funded.provider}/${funded.id}:medium`, light: `${funded.provider}/${funded.id}:medium` } },
@@ -407,7 +415,7 @@ test('reload_auth restores a newly authenticated personal route before the next
     writeFileSync(unauthenticatedProvider, personal.provider);
     try {
         const parent = h.spawnRoot('auth route reconciliation parent');
-        const child = await h.spawnHeadlessChild(parent, 'auth route reconciliation child', { model: 'anthropic/medium' });
+        const child = await h.spawnHeadlessChild(parent, 'auth route reconciliation child');
         assert.deepEqual(model(child), funded, 'the logical request starts on the funded route while personal auth is absent');
         const controller = await kit.connectRaw(child, { read: true });
         controller.send({ type: 'hello', role: 'controller', client_id: 'auth-route-reconciliation' });
@@ -470,10 +478,16 @@ test('reload_auth restores a newly authenticated personal route before the next
 // subscription-pool occupancy (broker-sdk-wiring's scope).
 test('login re-drive → list_models self-heals (0a) and reload_auth resolves a model + fires the deferred kickoff', { timeout: 30_000 }, async () => {
     const noAuthSentinel = join(h.home, 'fake-pi.no-auth');
+    const userConfigDir = join(h.agentHome, '.crouter');
+    const userConfigPath = join(userConfigDir, 'config.json');
+    mkdirSync(userConfigDir, { recursive: true });
+    writeFileSync(userConfigPath, JSON.stringify({
+        kinds: { general: { whenToUse: 'General work.', model: 'anthropic/medium' } },
+    }));
     writeFileSync(noAuthSentinel, '1');
     try {
         const parent = h.spawnRoot('login re-drive parent');
-        const child = await h.spawnHeadlessChild(parent, 'login re-drive', { model: 'anthropic/medium' });
+        const child = await h.spawnHeadlessChild(parent, 'login re-drive');
         assert.equal(model(child), null, 'boots model-less under zero-auth');
         assert.equal(agentStartCount(child), 0, 'kickoff deferred at boot');
         const c = await attachUntil(child, 'controller', 'redrive-ctrl', (a) => a.welcome.role === 'controller', 'redrive controller admitted');
@@ -498,5 +512,6 @@ test('login re-drive → list_models self-heals (0a) and reload_auth resolves a
     }
     finally {
         rmSync(noAuthSentinel, { force: true });
+        rmSync(userConfigPath, { force: true });
     }
 });

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -79,7 +79,7 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
             },
         },
     });
-    reviveNode(manager, { resume: true, capacity: 'freeze' });
+    await reviveNode(manager, { resume: true, capacity: 'freeze' });
     await h.awaitBoot(manager);
     // A live managed child makes this unfocused terminal manager legitimately
     // awaiting, so its real stophook takes the idle-release branch.
@@ -172,7 +172,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
             },
         });
         subscribe(root, nodeId, true);
-        reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+        await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         assert.equal(h.fleet.has(nodeId), true, 'the revived broker is fleet-owned');
         const seenAt = 10_000;
@@ -223,7 +223,7 @@ test('a non-attending observer does not prevent unattended resident parking', {
         intent: 'idle-release',
     });
     updateNode(nodeId, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     const boot = await h.awaitBoot(nodeId);
     await attach.attach(nodeId, 'observer', 'system-observer-test', { attends: false });
     assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', nodeId, 'job', 'attach.json'), 'utf8')).viewers, 0, 'a non-attending hello is not persisted as human attendance');
@@ -268,7 +268,7 @@ test('a connected broker viewer keeps an obligation-free resident live', { timeo
             env: {},
         },
     });
-    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     const boot = await h.awaitBoot(nodeId);
     // awaitBoot returns on the boot proof, which is written BEFORE the broker's
     // own `persistAttachState()` lays down the truthful zero state. Writing our
@@ -311,7 +311,7 @@ test('the unattended park clock cancels an obligation-free terminal node and spa
     try {
         const boot = async (id) => {
             updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-            reviveNode(id, { resume: true, capacity: 'freeze' });
+            await reviveNode(id, { resume: true, capacity: 'freeze' });
             return (await h.awaitBoot(id)).pid;
         };
         const settled = h.fabricateBrokerNode({ id: 'terminal-no-work', parent: root, status: 'idle', intent: 'idle-release' });
@@ -378,7 +378,7 @@ test('a resident managed child parks without finalizing while a terminal child i
         subscribe(terminalManager, terminal, true);
         const boot = async (id) => {
             updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-            reviveNode(id, { resume: true, capacity: 'freeze' });
+            await reviveNode(id, { resume: true, capacity: 'freeze' });
             return (await h.awaitBoot(id)).pid;
         };
         const residentPid = await boot(resident);
@@ -439,7 +439,7 @@ test('an unattended resident awaiting a live child remains wakeable', { timeout:
                 env: {},
             },
         });
-        reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+        await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         const seenAt = 20_000;
         await h.tick(seenAt);

package/dist/core/__tests__/seam/held-deferred-human-prompt.test.js

@@ -42,7 +42,7 @@ test('a Jiti-loaded watcher prepends its held deferred batch to a native broker
             },
         },
     });
-    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     await h.awaitBoot(nodeId);
     const entry = appendInbox(nodeId, {
         from: 'child',

package/dist/core/__tests__/seam/memory-slash-node-relative-inventory.test.js

@@ -115,11 +115,28 @@ test('node-relative memory slash commands omit preview metadata and register inv
         assert.equal(loadedCommandPreview('/acceptance-independent first evidence', live.commands), undefined);
         assert.deepEqual(live.notifications, []);
         const sentContent = Object.fromEntries(live.sent.map((send) => [send.name, send.message.content]));
-        assert.deepEqual(sentContent, {
+        const invokedBody = {
             [COMMAND_NAMES[0]]: `Store evidence in ${join(home, 'nodes', nodeId, 'context', 'result.md')}.\n`,
             [COMMAND_NAMES[1]]: `Node ${nodeId} received evidence.\n`,
             [COMMAND_NAMES[2]]: 'Independent payload: evidence.\n',
-        });
+        };
+        // An invoked document is content delivery, so the FIRST invocation carries the
+        // same companions `crtr memory read` attaches: the listings that place the doc,
+        // plus every corpus doc its memory-read routes match. The doc being delivered is
+        // absent from its own listing because its exposure registers before they render.
+        const firstSent = sentContent[COMMAND_NAMES[0]];
+        assert.ok(firstSent.endsWith(invokedBody[COMMAND_NAMES[0]]), 'the expanded body ends the delivery');
+        const companions = firstSent.slice(0, firstSent.length - invokedBody[COMMAND_NAMES[0]].length);
+        assert.match(companions, /^<auto-loaded-context>\n[\s\S]*<\/auto-loaded-context>\n\n$/);
+        assert.ok(companions.includes('<memory-listing dir="workspace/workspace">\n'
+            + `[[workspace/workspace/${COMMAND_LOCALS[2]}]]: Acceptance fixture.\n`
+            + `[[workspace/workspace/${COMMAND_LOCALS[1]}]]: Acceptance fixture.\n`
+            + '</memory-listing>'), 'the invoked doc\'s own directory listing is attached as a block');
+        assert.ok(companions.includes('<memory-listing dir="workspace">\n[[workspace/workspace]]\n</memory-listing>'));
+        assert.match(companions, /<memory kind="knowledge" name="memory-read-orientation">/);
+        // The later invocations attach nothing: the first delivery already exposed them.
+        assert.equal(sentContent[COMMAND_NAMES[1]], invokedBody[COMMAND_NAMES[1]]);
+        assert.equal(sentContent[COMMAND_NAMES[2]], invokedBody[COMMAND_NAMES[2]]);
         for (const send of live.sent) {
             assert.deepEqual(send.message, {
                 customType: 'memory-slash-command',

package/dist/core/__tests__/seam/yield-refresh-transaction.test.js

@@ -73,11 +73,11 @@ test('yield-message survives one pre-session_start retry and clears on session_s
     // the retry still roots a fresh cycle carrying the note, never reopening the
     // old session. Driving reviveNode directly is exactly what focus's revive path
     // calls, minus a tmux pane this contract does not involve.
-    const focusRevive = reviveNode(id, { resume: true, capacity: 'freeze' });
+    const focusRevive = await reviveNode(id, { resume: true, capacity: 'freeze' });
     const focusPid = focusRevive.launch?.pid;
     assert.ok(focusPid != null, 'the competing focus invocation launches the replacement broker');
     assert.equal(focusRevive.resumed, false, 'refresh intent overrides this invocation\'s strict-resume request');
-    assert.equal(h.fleet.get(id)?.pid, focusPid, 'the focus invocation synchronously owns the authoritative fleet slot');
+    assert.equal(h.fleet.get(id)?.pid, focusPid, 'the focus invocation owns the authoritative fleet slot');
     // Registering the manual launch cancels the exit policy's deferred recovery.
     // Its pid must therefore be the successful observed boot, proving these
     // assertions belong to the contender above rather than an already-queued boot.

package/dist/core/broker-client/__tests__/transport-relay.test.js

@@ -61,7 +61,9 @@ test('RelayTransport dials crtrd attach with Authorization: Bearer <token>', asy
     const relay = await startMockRelay();
     const transport = new RelayTransport('node-auth', relay.target);
     await connectTransport(transport);
-    assert.equal(relay.requestUrls[0], '/v1/nodes/node-auth/attach');
+    // `wakeParked=1` is part of the dial contract: a person attached deliberately,
+    // so the bridge wakes an exact parked resident for this caller.
+    assert.equal(relay.requestUrls[0], '/v1/nodes/node-auth/attach?wakeParked=1');
     assert.equal(relay.authHeaders[0], 'Bearer test-token');
     transport.destroy();
     await relay.close();

package/dist/core/broker-client/transport-relay.js

@@ -14,7 +14,11 @@ function relayUrl(target, nodeId) {
     const url = new URL(target.previewEndpoint);
     url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
     url.pathname = `/v1/nodes/${encodeURIComponent(nodeId)}/attach`;
-    url.search = '';
+    // A person typed `crtr surface attach` at this node, so an exact parked
+    // resident is woken for it — the same thing the LOCAL attach ensure does for
+    // a direct attach. The bridge leaves a parked node parked without this, which
+    // is what a product page reconnecting its viewport wants.
+    url.search = '?wakeParked=1';
     url.hash = '';
     return url.toString();
 }

package/dist/core/canvas/__tests__/history-transcript.test.d.ts

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

package/dist/core/canvas/__tests__/history-transcript.test.js

@@ -0,0 +1,102 @@
+// history-transcript.test.ts — transcript artifacts carry the origin their
+// stamp recorded.
+//
+// The join is the fragile part: a stamp is physically written BEFORE the
+// message it describes, so correlation runs on the message's own epoch-ms
+// `timestamp` and never on tree position. Getting that wrong yields a corpus
+// where every origin silently reads `unknown` — which looks like a stamping
+// regression rather than a reader bug, so it is worth pinning.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode } from '../canvas.js';
+import { closeDb } from '../db.js';
+import { nodeDir, sessionPtrPath } from '../paths.js';
+import { nodeArtifacts, groupCorpus } from '../history.js';
+const NODE = 'test-transcript-node';
+function meta(id, cwd) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+function messageEntry(role, text, msgTs) {
+    return JSON.stringify({
+        type: 'message',
+        timestamp: new Date(msgTs).toISOString(),
+        message: { role, content: [{ type: 'text', text }], timestamp: msgTs },
+    });
+}
+function stampEntry(msgTs, origin) {
+    return JSON.stringify({
+        type: 'custom',
+        customType: 'crtr-stamp',
+        data: { v: 1, kind: 'message', payload: { msgTs, origin } },
+    });
+}
+/** A session file in the real on-disk shape: stamps precede their messages,
+ *  one inbound turn is unstamped, and an assistant turn sits between them. */
+function seedSession(home) {
+    const dir = nodeDir(NODE);
+    mkdirSync(dir, { recursive: true });
+    const file = join(home, 'session.jsonl');
+    writeFileSync(file, [
+        JSON.stringify({ type: 'custom', customType: 'crtr-stamp', data: { v: 1, kind: 'session', payload: { node: NODE, crtr: '0.0.0' } } }),
+        stampEntry(1000, { type: 'runtime', kind: 'wake', wake: { kind: 'schedule_revive', ownerId: null, armedAt: 'x' } }),
+        messageEntry('user', 'woken by cron', 1000),
+        JSON.stringify({ type: 'message', timestamp: new Date(1500).toISOString(), message: { role: 'assistant', content: [{ type: 'thinking', text: 'private' }, { type: 'toolCall', name: 'Bash' }], timestamp: 1500 } }),
+        stampEntry(2000, { type: 'runtime', kind: 'inbox', entries: [{ from: 'n1', fromName: 'child-node', kind: 'report', tier: 'normal' }] }),
+        messageEntry('user', 'a delivery', 2000),
+        messageEntry('user', 'no stamp for this one', 3000),
+    ].join('\n'), 'utf8');
+    writeFileSync(sessionPtrPath(NODE), file, 'utf8');
+}
+let home;
+let cwd;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-history-transcript-'));
+    cwd = mkdtempSync(join(tmpdir(), 'crtr-history-transcript-cwd-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+});
+after(() => {
+    closeDb();
+    for (const d of [home, cwd])
+        rmSync(d, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('a stamped message carries its origin; an unstamped one reads unknown', () => {
+    createNode(meta(NODE, cwd));
+    seedSession(home);
+    const arts = nodeArtifacts(NODE, ['transcript']);
+    assert.equal(arts.length, 4, 'every message entry becomes one artifact');
+    const origins = arts.map((a) => a.origin);
+    assert.deepEqual(origins, ['wake', undefined, 'inbox', 'unknown']);
+    // Origin is a property of ARRIVAL — a generated turn must not acquire one,
+    // which is what lets `--origin` exclude assistant turns without a role filter.
+    const assistant = arts.find((a) => a.role === 'assistant');
+    assert.equal(assistant?.origin, undefined);
+    // Sender attribution rides the inbox stamp's delivered entries.
+    assert.equal(arts[2]?.from, 'child-node');
+    // Private model reasoning stays out of the searchable body, matching every
+    // other human-facing transcript surface.
+    assert.ok(!assistant?.loadBody().includes('private'));
+    assert.ok(assistant?.loadBody().includes('Tool: Bash'));
+});
+test('grouping by origin counts arrivals only, and unknown is its own bucket', () => {
+    createNode(meta(NODE, cwd));
+    seedSession(home);
+    const groups = groupCorpus(nodeArtifacts(NODE, ['transcript']), 'origin');
+    assert.deepEqual(groups.map((g) => g.key).sort(), ['inbox', 'unknown', 'wake'], 'the assistant turn contributes no bucket');
+    assert.equal(groups.reduce((n, g) => n + g.count, 0), 3);
+});

package/dist/core/canvas/browse/app.d.ts

@@ -1,6 +1,6 @@
 import type { CanvasSource } from '../source.js';
 import { type BindingId, type BindingResolution, type RawTerminalInput } from '../../keybindings/index.js';
-declare const BROWSE_NAV_ACTIONS: readonly ["crtr.browse.quit", "crtr.browse.down", "crtr.browse.up", "crtr.browse.first", "crtr.browse.last", "crtr.browse.expand-or-child", "crtr.browse.collapse-or-parent", "crtr.browse.toggle-fold", "crtr.browse.tab-next", "crtr.browse.tab-previous", "crtr.browse.tab.1", "crtr.browse.tab.2", "crtr.browse.tab.3", "crtr.browse.tab.4", "crtr.browse.tab.5", "crtr.browse.close-subtree", "crtr.browse.sort", "crtr.browse.scope", "crtr.browse.profile", "crtr.browse.residents", "crtr.browse.preview", "crtr.browse.search", "crtr.browse.revive-now", "crtr.browse.focus", "crtr.browse.focus-background", "crtr.browse.yank-id"];
+declare const BROWSE_NAV_ACTIONS: readonly ["crtr.browse.quit", "crtr.browse.down", "crtr.browse.up", "crtr.browse.first", "crtr.browse.last", "crtr.browse.expand-or-child", "crtr.browse.collapse-or-parent", "crtr.browse.toggle-fold", "crtr.browse.tab-next", "crtr.browse.tab-previous", "crtr.browse.tab.1", "crtr.browse.tab.2", "crtr.browse.tab.3", "crtr.browse.tab.4", "crtr.browse.tab.5", "crtr.browse.close-subtree", "crtr.browse.sort", "crtr.browse.scope", "crtr.browse.profile", "crtr.browse.residents", "crtr.browse.preview", "crtr.browse.pin", "crtr.browse.search", "crtr.browse.revive-now", "crtr.browse.focus", "crtr.browse.focus-background", "crtr.browse.yank-id"];
 declare const BROWSE_SEARCH_ACTIONS: readonly ["crtr.browse.search.cancel", "crtr.browse.search.commit", "crtr.browse.search.delete", "crtr.browse.search.quit"];
 export declare function resolveBrowseNavAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_NAV_ACTIONS)[number] | null;
 export declare function resolveBrowseSearchAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_SEARCH_ACTIONS)[number] | null;

package/dist/core/canvas/browse/app.js

@@ -21,7 +21,8 @@ const BROWSE_NAV_ACTIONS = [
     'crtr.browse.expand-or-child', 'crtr.browse.collapse-or-parent', 'crtr.browse.toggle-fold',
     'crtr.browse.tab-next', 'crtr.browse.tab-previous', 'crtr.browse.tab.1', 'crtr.browse.tab.2',
     'crtr.browse.tab.3', 'crtr.browse.tab.4', 'crtr.browse.tab.5', 'crtr.browse.close-subtree', 'crtr.browse.sort',
-    'crtr.browse.scope', 'crtr.browse.profile', 'crtr.browse.residents', 'crtr.browse.preview', 'crtr.browse.search',
+    'crtr.browse.scope', 'crtr.browse.profile', 'crtr.browse.residents', 'crtr.browse.preview',
+    'crtr.browse.pin', 'crtr.browse.search',
     'crtr.browse.revive-now', 'crtr.browse.focus', 'crtr.browse.focus-background', 'crtr.browse.yank-id',
 ];
 const BROWSE_SEARCH_ACTIONS = [
@@ -40,14 +41,16 @@ export function resolveBrowseSearchAction(bindings, raw) {
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
-import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './render.js';
+import { renderFrame, detectColorCaps, headerHeight, previewLayout, PREVIEW_HEIGHT } from './render.js';
 import { writeClipboardTextEverywhere } from '../../clipboard-text.js';
 /** Viewport (body) height = total rows minus the header renderFrame draws (see
- *  render.ts headerHeight), the footer, and the preview panel when shown. Kept
- *  in lockstep with render.ts via the shared headerHeight/PREVIEW_HEIGHT. */
-function viewportHeight(rowsTotal, inputLine, previewOn) {
-    const rows = Math.max(8, rowsTotal);
-    const previewH = previewOn ? PREVIEW_HEIGHT : 0;
+ *  render.ts headerHeight), the footer, and the BOTTOM preview panel when that is
+ *  the layout in play. The side preview column costs columns, not rows, so it does
+ *  not shrink the viewport. Kept in lockstep with render.ts via the shared
+ *  headerHeight/previewLayout/PREVIEW_HEIGHT. */
+function viewportHeight(size, inputLine, previewOn) {
+    const rows = Math.max(8, size.rows);
+    const previewH = previewLayout(size.cols, previewOn).mode === 'bottom' ? PREVIEW_HEIGHT : 0;
     return Math.max(1, rows - headerHeight(inputLine) - 1 /* footer */ - previewH);
 }
 export async function runBrowse(opts) {
@@ -117,7 +120,7 @@ export async function runBrowse(opts) {
         cwdScope: null, // default: All dirs
         profileScope: launchProfileId,
         sort: 'attention', // default: attention ordering (attached/streaming/live first)
-        preview: true, // default ON (decision)
+        preview: false, // default OFF (decision) — `v` opens it for the hovered row
         residentsOnly: true, // default ON: hide one-shot workers (decision)
         pendingClose: null,
         flash: null,
@@ -218,7 +221,7 @@ export async function runBrowse(opts) {
         const size = getTerminalSize();
         const previewOn = state.preview && visible.length > 0;
         const inputMode = state.search || state.rename || state.message;
-        const viewport = viewportHeight(size.rows, inputMode, previewOn);
+        const viewport = viewportHeight(size, inputMode, previewOn);
         // Keep the cursor inside the viewport window.
         if (state.cursor < state.scrollOffset)
             state.scrollOffset = state.cursor;
@@ -708,7 +711,7 @@ export async function runBrowse(opts) {
             return;
         }
         // Pin or unpin in the local, view-only pin set.
-        if (input === 'f') {
+        if (action === 'crtr.browse.pin') {
             if (row !== undefined)
                 togglePin(row.id);
             scheduleFlush();

package/dist/core/canvas/browse/model.js

@@ -201,13 +201,28 @@ export function previewSnippet(query, text, width, maxLines) {
     // 2. Recompute highlight indices on the FINAL snippet string (no drift), then
     //    word-wrap with offset tracking and split the highlight into per-line cols.
     const hi = highlightIndices(query, snippet);
-    return wrapTracked(snippet, width, maxLines).map(({ text: lt, start }) => {
+    const wrapped = wrapTracked(snippet, width, maxLines);
+    const lines = wrapped.map(({ text: lt, start }) => {
         const lhi = new Set();
         for (const idx of hi)
             if (idx >= start && idx < start + lt.length)
                 lhi.add(idx - start);
         return { text: lt, hi: lhi };
     });
+    // 3. Mark a truncation. Without this the last line reads as the end of the text,
+    //    which is exactly the wrong impression for "where did this node leave off?".
+    const last = wrapped[wrapped.length - 1];
+    const lastLine = lines[lines.length - 1];
+    if (last !== undefined && lastLine !== undefined && last.start + last.text.length < snippet.length) {
+        const keep = Math.max(0, Math.min(lastLine.text.length, width - 1));
+        const text = lastLine.text.slice(0, keep);
+        const lhi = new Set();
+        for (const idx of lastLine.hi)
+            if (idx < keep)
+                lhi.add(idx);
+        lines[lines.length - 1] = { text: `${text}…`, hi: lhi };
+    }
+    return lines;
 }
 function shortId(id) {
     return id.slice(0, 8);

package/dist/core/canvas/browse/render.d.ts

@@ -2,10 +2,21 @@ import type { Tab, Tree, VisibleRow, SortMode } from './model.js';
 import { detectColorCaps, type ColorCaps } from '../../tui/draw.js';
 export { detectColorCaps };
 export type { ColorCaps };
-export declare const PROMPT_LINES = 3;
-export declare const REPLY_LINES = 3;
-export declare const PREVIEW_BODY: number;
+export declare const RECAP_LINES = 2;
+export declare const REPORT_LINES = 2;
+export declare const PREVIEW_BODY = 8;
 export declare const PREVIEW_HEIGHT: number;
+export type PreviewMode = 'none' | 'bottom' | 'side';
+/** Where the preview goes at this terminal width, and how the body splits.
+ *  `rowsW` is the width the row table draws into (full width unless `side`).
+ *  Exported so app.ts's viewport math can subtract preview ROWS only in `bottom`
+ *  mode — the side column costs columns, not rows. */
+export interface PreviewLayout {
+    mode: PreviewMode;
+    panelW: number;
+    rowsW: number;
+}
+export declare function previewLayout(cols: number, previewOn: boolean): PreviewLayout;
 export declare function headerHeight(inputLine: boolean): number;
 export interface RenderState {
     tree: Tree;
@@ -52,6 +63,15 @@ export interface RenderState {
      *  dead action. undefined/false = local, byte-identical footer. */
     readOnly?: boolean;
 }
+/** How the fixed PREVIEW_BODY budget is divided for one row: the optional blocks
+ *  take their two lines only when the node actually has them, and the remainder is
+ *  split between the ask and the reply (ask keeps the odd line). */
+export declare function previewAllocation(hasRecap: boolean, hasReport: boolean): {
+    recap: number;
+    ask: number;
+    reply: number;
+    report: number;
+};
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints
  * the screen in place. `caps` gates all hue (defaults to a no-color frame so