@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/core/runtime/reset.js

@@ -22,7 +22,8 @@
 import { existsSync, rmSync } from 'node:fs';
 import { getNode, updateNode, setPresence, clearPid, setFocusOccupant, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, nodeDir, openDb, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { paneLocation, tearDownNode, focusOf } from './placement.js';
+import { hostFor } from './host.js';
+import { paneLocation, focusOf } from './placement.js';
 import { buildLaunchSpec } from './launch.js';
 import { roadmapPath } from './roadmap.js';
 import { spawnNode, newNodeId, nodeSession } from './nodes.js';
@@ -49,11 +50,12 @@ export function reapDescendants(rootId) {
         try {
             // Reap BEFORE tearing down the placement (the crash-safety invariant the
             // `cancel` event encodes): a non-supervised status + cleared intent first, so
-            // the daemon can't revive a descendant mid-teardown. tearDownNode then
-            // closes any focus row it held, kills its pane (pane-keyed), and nulls its
-            // LOCATION.
-            transition(id, 'cancel');
-            tearDownNode(id);
+            // the daemon can't revive a descendant mid-teardown. Teardown then routes
+            // through the Host seam (hostFor): a tmux node closes any focus row it held,
+            // kills its pane (pane-keyed), and nulls its LOCATION; a broker node sends
+            // the `shutdown` frame so its PROCESS exits and releases the .jsonl writer.
+            const m = transition(id, 'cancel');
+            hostFor(m).teardown(id);
             reaped.push(id);
         }
         catch {

package/dist/core/runtime/revive.d.ts

@@ -1,4 +1,5 @@
 import { type NodeMeta } from '../canvas/index.js';
+import type { WakeOrigin } from './bearings.js';
 import { type RespawnPaneOpts } from './placement.js';
 /** Pick the `--session` source for a revive. resume=true prefers the absolute
  *  session-file path (immune to cwd; pi opens it directly) and keeps the bare
@@ -25,6 +26,7 @@ export interface ReviveResult {
  */
 export declare function reviveNode(nodeId: string, opts: {
     resume: boolean;
+    wakeReason?: WakeOrigin;
 }): ReviveResult;
 /** Re-exec a node's pi FRESH in its EXISTING tmux pane (the refresh-yield
  *  path). Unlike `reviveNode`, this opens no new window: the pane's current pi

package/dist/core/runtime/revive.js

@@ -14,26 +14,15 @@
 //                  preferring the absolute session-file path (cwd-immune) over
 //                  the bare session id.
 //   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
-import { getNode, updateNode, setPresence, clearPid, fullName, } from '../canvas/index.js';
+import { getNode, updateNode, setPresence, clearPid, fullName, cancelDeadlinesFor, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings } from './kickoff.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { reviveIntoPlacement, reconcile, isNodePaneAlive, homeSessionOf, piCommand, respawnPane, } from './placement.js';
-import { nodeSession } from './nodes.js';
-/** signal-0 liveness probe for a pi pid (mirrors the daemon's isPidAlive). A
- *  null pid (legacy / never-booted) reads dead. */
-function pidAlive(pid) {
-    if (pid == null)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e.code === 'EPERM';
-    }
-}
+import { reconcile, piCommand, respawnPane, } from './placement.js';
+import { hostFor } from './host.js';
+import { nodeSession, childBackstageOf, rootOfSpine } from './nodes.js';
+import { isPidAlive } from '../canvas/pid.js';
 // ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
 // ---------------------------------------------------------------------------
@@ -73,7 +62,7 @@ export function reviveNode(nodeId, opts) {
     // frozen pane), so the guard gates on pi liveness too, not pane-existence alone.
     reconcile(nodeId);
     const live = getNode(nodeId) ?? meta;
-    if (isNodePaneAlive(nodeId) && pidAlive(live.pi_pid)) {
+    if (hostFor(live).isAlive(nodeId) && isPidAlive(live.pi_pid)) {
         return {
             window: live.window ?? null,
             session: live.tmux_session ?? nodeSession(),
@@ -98,8 +87,12 @@ export function reviveNode(nodeId, opts) {
         inv = buildPiArgv(meta, resume);
     }
     else {
+        // A fresh revive: drain the one-shot bearings, then build the kickoff. When
+        // a scheduled bare self-alarm drove this revive, opts.wakeReason carries the
+        // wake provenance so the kickoff leads with a <crtr-wake> block ("a timer
+        // woke you"); every other reviveNode caller passes nothing → no block.
         const bearings = drainBearings(meta);
-        inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings) });
+        inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings, opts.wakeReason) });
     }
     // Placement owns WHERE this revive lands (§1.4): resume into a live focus pane
     // if the node occupies one, else a fresh window in its home_session (the
@@ -108,9 +101,14 @@ export function reviveNode(nodeId, opts) {
     // around it (the crash-safety ordering, unchanged). THIS is the bug-kill: a
     // non-focused background revive can no longer new-window into a user session.
     transition(nodeId, 'revive');
-    const placed = reviveIntoPlacement(nodeId, {
-        command: piCommand(inv.argv),
-        env: inv.env,
+    // Cancel-on-wake (design §6.4, AC-E1): every revive-for-any-reason (an inbox
+    // event, a different wake, a manual focus) drops this node's pending deadline,
+    // so the deadline always belongs to the dormancy being left. Writes only the
+    // wakeups table, after the atomic transition above. (reviveInPlace's
+    // transition('boot') needs NO hook — a refresh is the same node continuing,
+    // not leaving a dormancy.)
+    cancelDeadlinesFor(nodeId);
+    const placed = hostFor(meta).launch(nodeId, inv, {
         cwd: meta.cwd,
         name: fullName(meta),
         resuming,
@@ -150,14 +148,16 @@ export function reviveInPlace(nodeId, pane, respawn = respawnPane) {
     // then build purely.
     const bearings = drainBearings(meta);
     const inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings) });
-    // CRTR_ROOT_SESSION is the backstage this node's CHILDREN spawn into — it must
-    // be the durable REVIVE-HOME (home_session), NOT the pane's live `session`. A
-    // FOCUSED child's pane is in a USER session (focus taints meta.tmux_session),
-    // so sourcing it from `session` would land any child it spawns in the user's
-    // session, re-tainting that child's home_session (A-MAJOR-1). home_session is
-    // the taint-immune backstage `crtr` for a child; for a root it equals its own
-    // session, so this is behavior-preserving there.
-    const env = { ...inv.env, CRTR_ROOT_SESSION: homeSessionOf(nodeId) };
+    // CRTR_ROOT_SESSION is the backstage this node's CHILDREN spawn into — NOT the
+    // pane's live `session`. A FOCUSED child's pane is in a USER session (focus
+    // taints meta.tmux_session), so sourcing it from `session` would land any
+    // child it spawns in the user's session, re-tainting that child's
+    // home_session (A-MAJOR-1). childBackstageOf is the taint-immune backstage:
+    // home_session for a managed child, but `nodeSession()` for a ROOT (whose
+    // home_session may itself be a user session it adopted via the inline front
+    // door — sourcing children from it would re-point the root's whole subtree
+    // into the user's session on every refresh-yield).
+    const env = { ...inv.env, CRTR_ROOT_SESSION: childBackstageOf(nodeId), CRTR_SUBTREE: rootOfSpine(nodeId) };
     const ok = respawn({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
     if (!ok) {
         throw new Error(`reviveInPlace: respawn-pane dispatch failed for ${nodeId}`);
@@ -199,11 +199,11 @@ export function relaunchRootInPane(nodeId, pane) {
     }
     // No prompt, no resume → a brand-new root conversation at cycle 0.
     const inv = buildPiArgv(meta, {});
-    // Source CRTR_ROOT_SESSION from the durable REVIVE-HOME (home_session), the
-    // same taint-immunity rule as reviveInPlace. relaunchRootInPane runs only on a
-    // root, whose home_session IS its own session, so this is behavior-preserving
-    // — it keeps both in-pane revive paths sourced identically.
-    const env = { ...inv.env, CRTR_ROOT_SESSION: homeSessionOf(nodeId), [FRONT_DOOR_ENV]: '1' };
+    // Source CRTR_ROOT_SESSION from childBackstageOf, the same backstage rule as
+    // reviveInPlace. relaunchRootInPane runs only on a root, whose children must
+    // flow to the shared backstage `nodeSession()` — never the root's own adopted
+    // user session — so both in-pane revive paths stay sourced identically.
+    const env = { ...inv.env, CRTR_ROOT_SESSION: childBackstageOf(nodeId), CRTR_SUBTREE: rootOfSpine(nodeId), [FRONT_DOOR_ENV]: '1' };
     const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
     if (!ok) {
         throw new Error(`relaunchRootInPane: respawn-pane dispatch failed for ${nodeId}`);

package/dist/core/runtime/spawn.d.ts

@@ -1,3 +1,4 @@
+import { type WakeOrigin } from './bearings.js';
 import { type NodeMeta, type Mode } from '../canvas/index.js';
 export interface BootRootOpts {
     cwd: string;
@@ -27,6 +28,17 @@ export interface SpawnChildOpts {
      *  new session for the child — the source is untouched — then `prompt` is the
      *  next message. A one-shot at birth; the child resumes its own session after. */
     forkFrom?: string;
+    /** Set ONLY by the daemon when a `spawn`/spawn-cron wake births this node: the
+     *  provenance of the timer that fired (see WakeOrigin). In-memory only — it is
+     *  NOT part of the stored recipe (the daemon spreads it in at fire time via
+     *  `spawnChild({ ...recipe, wakeOrigin })`); `node new` never sets it. When set,
+     *  a <crtr-wake> block is prepended to the kickoff so the newborn knows a clock
+     *  birthed it. */
+    wakeOrigin?: WakeOrigin;
+    /** Which HOST launches + supervises this node: a tmux pane (default) or the
+     *  headless broker. Persisted as `host_kind` at birth (resolved from
+     *  `--headless` / the `headless` config default by the caller). */
+    hostKind?: 'tmux' | 'broker';
 }
 /** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
  *  A live node id resolves to its captured session FILE (absolute, cwd-immune),
@@ -38,6 +50,13 @@ export interface SpawnChildResult {
     window: string | null;
     session: string;
 }
+/** Resolve who a spawn is attributed to. A managed child needs a spine parent
+ *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
+ *  does not: it is top-level by definition and the spawner identity is
+ *  provenance only — a human shell with no CRTR_NODE_ID is a legitimate root
+ *  spawner (regression: `crtr node new --root` from outside a node used to
+ *  throw here). */
+export declare function resolveSpawner(parent: string | undefined, ctxNodeId: string | null, root: boolean): string | null;
 /** Spawn a node from a live node. By default a managed terminal worker in a
  *  background window, with the spawner auto-subscribed (active) via spawnNode.
  *  With `root`: an independent resident root — parent=null, NO subscription back

package/dist/core/runtime/spawn.js

@@ -10,16 +10,17 @@
 //                provenance via spawned_by) brought forefront for direct driving.
 import { spawnSync } from 'node:child_process';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession } from './nodes.js';
+import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession, rootOfSpine } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
-import { seedMemory, seedUserMemory, seedProjectMemory } from './memory.js';
 import { generateSessionName } from './naming.js';
-import { installMenuBinding, installNavBindings } from './tmux-chrome.js';
+import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
+import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
 import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
 import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
+import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** Create a root node and bring up its pi. Returns the node; for 'inline' this
  *  only returns after pi exits (it took over the terminal). */
@@ -57,8 +58,8 @@ export function bootRoot(opts) {
     // Every node window — root or child — lives in the one shared session.
     const session = nodeSession();
     ensureSession(session, opts.cwd);
-    // Make the Alt+C action menu + Alt+] / Alt+[ nav keys live on this server
-    // (idempotent, in-tmux only).
+    // Make the Alt+C action menu + Alt+] / Alt+[ node-nav keys + Alt+V then ]/[
+    // view-nav chord live on this server (idempotent, in-tmux only).
     if (inTmux()) {
         try {
             installMenuBinding();
@@ -68,6 +69,10 @@ export function bootRoot(opts) {
             installNavBindings();
         }
         catch { /* best-effort */ }
+        try {
+            installViewNavBindings();
+        }
+        catch { /* best-effort */ }
     }
     // inline: the root's pi takes over THIS terminal, so its own window stays
     // where the user is (its tmux_session tracks that real pane so supervision
@@ -93,7 +98,7 @@ export function bootRoot(opts) {
     }
     const withSession = getNode(meta.node_id);
     const inv = buildPiArgv(withSession, { prompt: opts.prompt });
-    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
+    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, CRTR_SUBTREE: rootOfSpine(meta.node_id), [FRONT_DOOR_ENV]: '1' };
     const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
     process.exit(r.status ?? 0);
 }
@@ -120,6 +125,19 @@ export function resolveForkSource(value) {
     // Not a known node — treat as a bare/partial pi session id for pi to resolve.
     return v;
 }
+/** Resolve who a spawn is attributed to. A managed child needs a spine parent
+ *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
+ *  does not: it is top-level by definition and the spawner identity is
+ *  provenance only — a human shell with no CRTR_NODE_ID is a legitimate root
+ *  spawner (regression: `crtr node new --root` from outside a node used to
+ *  throw here). */
+export function resolveSpawner(parent, ctxNodeId, root) {
+    const spawner = parent ?? ctxNodeId ?? null;
+    if (!root && spawner === null) {
+        throw new Error('spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent');
+    }
+    return spawner;
+}
 /** Spawn a node from a live node. By default a managed terminal worker in a
  *  background window, with the spawner auto-subscribed (active) via spawnNode.
  *  With `root`: an independent resident root — parent=null, NO subscription back
@@ -131,11 +149,8 @@ export function spawnChild(opts) {
     }
     catch { /* daemon is best-effort */ }
     const ctx = currentNodeContext();
-    const spawner = opts.parent ?? ctx.nodeId;
-    if (spawner === null || spawner === undefined) {
-        throw new Error('spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent');
-    }
     const root = opts.root === true;
+    const spawner = resolveSpawner(opts.parent, ctx.nodeId ?? null, root);
     const mode = opts.mode ?? 'base';
     // Lifecycle keys on ROOT-ness only, independent of mode: an independent root
     // (or `--root`) is resident (a conversation that persists, woken by inbox/
@@ -156,9 +171,15 @@ export function spawnChild(opts) {
         name: opts.name ?? opts.kind,
         description: generateSessionName(opts.prompt),
         // A root has no spine parent (top-level, nobody subscribes); it still
-        // records spawned_by=spawner. A child's parent IS its manager.
+        // records spawned_by=spawner when a node (not a human shell) spawned it.
+        // A child's parent IS its manager.
         parent: root ? null : spawner,
-        spawnedBy: root ? spawner : undefined,
+        spawnedBy: root ? (spawner ?? undefined) : undefined,
+        // Persist the RAW fork reference (not the resolved path) as provenance, so
+        // the boot intro can detect this is a fork and re-assert the node's own
+        // identity over the source's copied-in conversation.
+        forkFrom: opts.forkFrom,
+        hostKind: opts.hostKind,
         launch,
     });
     // Persist the task as the child's goal for a fresh revive to re-read.
@@ -168,6 +189,19 @@ export function spawnChild(opts) {
     // — not in buildPiArgv — so a bad reference fails the spawn loudly before any
     // window opens, rather than after pi is already booting.
     const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
+    // A fork inherits the SOURCE node's entire first-person conversation, so the
+    // identity re-assertion must ride the STRONGEST channel too, not only the
+    // session-start bearings (a trailing custom_message the model weighs only by
+    // recency). Prepend it to the kickoff PROMPT — the message that actually
+    // triggers the fork's first turn, so the model acts on "you are node X, a
+    // FORK of <source>, NOT them" as live instruction. When the daemon births this
+    // node from a scheduled `spawn` wake, the <crtr-wake> provenance block leads
+    // (so "a timer birthed you" precedes the task) — mirroring the fork-identity
+    // prepend. Only the pi argv prompt is reframed; the persisted goal (writeGoal
+    // above) keeps the raw task.
+    const wakeBlock = opts.wakeOrigin !== undefined ? `${buildWakeBearings(opts.wakeOrigin)}\n\n` : '';
+    const idBlock = forkFrom !== undefined ? `${buildIdentityAssertion(meta.node_id)}\n\n` : '';
+    const kickoff = `${wakeBlock}${idBlock}${opts.prompt}`;
     // A child created DIRECTLY as an orchestrator (mode='orchestrator') boots
     // with the orchestrator persona but bypasses promote(), which is where a
     // roadmap scaffold would normally be seeded. Lay one down here (goal
@@ -176,14 +210,8 @@ export function spawnChild(opts) {
     if (mode === 'orchestrator' && !hasRoadmap(meta.node_id)) {
         seedRoadmap(meta.node_id, { goal: opts.prompt.trim() });
     }
-    // Born an orchestrator ⇒ also lay down its three scoped long-term memory
-    // stores, the companions to the roadmap: user-global (key-less), project
-    // (keyed off the child's cwd), and node-local. Each guarded against clobber.
-    if (mode === 'orchestrator') {
-        seedUserMemory();
-        seedProjectMemory(opts.cwd);
-        seedMemory(meta.node_id);
-    }
+    // (The three scoped long-term memory stores are seeded for EVERY node at birth
+    // in spawnNode — no orchestrator-gated seeding needed here.)
     // A managed CHILD lands in the shared global session: inherited from the
     // parent's CRTR_ROOT_SESSION, else the default node session. A --root spawned
     // from inside tmux instead opens its window in the CALLER'S CURRENT session,
@@ -205,8 +233,33 @@ export function spawnChild(opts) {
     // backstage, never a user session — this is what keeps a background revive
     // off the user's screen (the focus taint cannot reach it).
     updateNode(meta.node_id, { home_session: session });
-    const inv = buildPiArgv(meta, { prompt: opts.prompt, forkFrom });
-    const env = { ...inv.env, CRTR_ROOT_SESSION: childSession, [FRONT_DOOR_ENV]: '1' };
+    const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
+    // Belt-and-suspenders backstage routing emitted at EVERY launch site: the
+    // authoritative CRTR_ROOT_SESSION (this subtree's shared backstage) +
+    // CRTR_SUBTREE (this node's spine root). Hoisted ABOVE the host branch so the
+    // broker launch and the tmux command consume ONE authoritative env — the
+    // broker host merges inv.env, so a --headless --root broker would otherwise
+    // inherit the SPAWNER's subtree id via the lossy nodeEnv passthrough (review
+    // reuse MINOR-2). FRONT_DOOR is added per-consumer below (the broker host sets
+    // it itself; the tmux env const adds it).
+    inv.env = { ...inv.env, CRTR_ROOT_SESSION: childSession, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
+    // Birth LAUNCH branch on the PERSISTED host_kind (set at birth by spawnNode).
+    // A broker birth diverts AWAY from the tmux pane: the headless broker host
+    // launches a detached broker process (which records its own pid as pi_pid via
+    // the stophook) and returns placement fields all null — so we open NO tmux
+    // window and write NO tmux placement (presence stays null for a broker). The
+    // tmux path below is left completely UNCHANGED (byte-identical) for every
+    // non-broker spawn. Mirrors reviveNode's `hostFor(meta).launch(...)` shape.
+    if (meta.host_kind === 'broker') {
+        const placed = headlessBrokerHost.launch(meta.node_id, inv, {
+            cwd: meta.cwd,
+            name: fullName(meta),
+            resuming: false,
+        });
+        const saved = getNode(meta.node_id);
+        return { node: saved, window: placed.window, session: placed.session };
+    }
+    const env = { ...inv.env, [FRONT_DOOR_ENV]: '1' };
     const command = piCommand(inv.argv);
     // openNodeWindow now returns {window, pane}; pane is unused until the
     // placement layer lands, so destructure the window and proceed unchanged.

package/dist/core/runtime/stop-guard.d.ts

@@ -6,7 +6,7 @@ export interface StopSignals {
 }
 export type StopAction = {
     action: 'allow';
-    reason: 'awaiting' | 'finished' | 'escalated' | 'dormant';
+    reason: 'awaiting' | 'scheduled' | 'finished' | 'escalated' | 'dormant';
 } | {
     action: 'reprompt';
     reason: 'stalled';

package/dist/core/runtime/stop-guard.js

@@ -16,7 +16,7 @@
 //                      Also fine.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
-import { hasActiveLiveSubscription, getNode } from '../canvas/index.js';
+import { hasActiveLiveSubscription, hasPendingSelfWake, getNode } from '../canvas/index.js';
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
@@ -35,6 +35,11 @@ export function evaluateStop(nodeId, signals) {
     if (node !== null && node.lifecycle === 'resident') {
         return { action: 'allow', reason: 'dormant' };
     }
+    // A terminal node with a pending self-scheduled wakeup is legitimately
+    // waiting on the clock: the daemon's wakeup sweep resumes it when the wake
+    // fires, so it should idle-release rather than busy-wait holding pi/window.
+    if (hasPendingSelfWake(nodeId))
+        return { action: 'allow', reason: 'scheduled' };
     // A terminal node holding something live to wake it is legitimately awaiting.
     if (hasActiveLiveSubscription(nodeId))
         return { action: 'allow', reason: 'awaiting' };

package/dist/core/runtime/tmux-chrome.d.ts

@@ -1 +1 @@
-export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';
+export { installMenuBinding, installNavBindings, installViewNavBindings, sendKeysEnter } from './tmux.js';

package/dist/core/runtime/tmux-chrome.js

@@ -1,4 +1,4 @@
 // tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
 // The ONLY non-placement module allowed to import the tmux driver, per the
 // §5.1 lint. Re-exports the menu/nav/send-keys verbs callers (spawn, chord) need.
-export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';
+export { installMenuBinding, installNavBindings, installViewNavBindings, sendKeysEnter } from './tmux.js';

package/dist/core/runtime/tmux.d.ts

@@ -96,6 +96,26 @@ export declare function paneLocation(pane: string): {
  *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
  *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
 export declare function paneExists(pane: string): boolean;
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export declare function listLivePanes(): Set<string> | null;
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Used to preserve a view monitor's cwd across a
+ *  view-cycle respawn so project-scoped views still resolve. Null if tmux fails. */
+export declare function paneCurrentPath(pane: string): string | null;
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
+ *  view-nav cycle can read it back and switch to the next/prev view in place.
+ *  Best-effort; never throws. */
+export declare function setPaneOption(pane: string, name: string, value: string): boolean;
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export declare function getPaneOption(pane: string, name: string): string | undefined;
 /** Relocate a pane into another session as its own window WITHOUT killing the
  *  process in it — `break-pane -d` moves the pane out of its current window (the
  *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
@@ -197,3 +217,11 @@ export declare function installMenuBinding(): boolean;
  *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
  */
 export declare function installNavBindings(): boolean;
+/** Bind Alt+V → (], [) to the view-monitor cycle. `M-v` enters the private
+ *  `crtr-view` key table (switch-client -T), then ] cycles next / [ cycles prev.
+ *  Best-effort; false if any of the three binds fail. Deliberately distinct from
+ *  installNavBindings' bare Alt+]/Alt+[ (node cycle): the two cycles coexist on
+ *  the same server — brackets alone walk the node graph, Alt+V-then-bracket flips
+ *  view monitors. The bracket keys are bound in the private table, so they NEVER
+ *  shadow the user's root ]/[ and carry no CSI-introducer ambiguity. */
+export declare function installViewNavBindings(): boolean;

package/dist/core/runtime/tmux.js

@@ -191,6 +191,39 @@ export function paneExists(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}']);
     return r.ok && r.stdout === pane;
 }
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export function listLivePanes() {
+    const r = tmux(['list-panes', '-a', '-F', '#{pane_id}']);
+    if (!r.ok)
+        return null;
+    return new Set(r.stdout.split('\n').filter((p) => p !== ''));
+}
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Used to preserve a view monitor's cwd across a
+ *  view-cycle respawn so project-scoped views still resolve. Null if tmux fails. */
+export function paneCurrentPath(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_current_path}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
+ *  view-nav cycle can read it back and switch to the next/prev view in place.
+ *  Best-effort; never throws. */
+export function setPaneOption(pane, name, value) {
+    return tmux(['set-option', '-p', '-t', pane, name, value]).ok;
+}
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export function getPaneOption(pane, name) {
+    const r = tmux(['show-options', '-p', '-t', pane, '-q', '-v', name]);
+    return r.ok ? r.stdout : undefined;
+}
 /** Relocate a pane into another session as its own window WITHOUT killing the
  *  process in it — `break-pane -d` moves the pane out of its current window (the
  *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
@@ -375,12 +408,13 @@ export function installMenuBinding() {
         // a whole-canvas picker (incl. dormant nodes) and revives the choice via
         // `crtr node focus` — the only sync-safe open (routes through reviveNode).
         { name: 'resume node', key: 'r', cmd: `send-keys -t '#{pane_id}' '/resume-node' Enter` },
-        // `d` demotes the agent to TERMINAL in place: no finalize, no kill — it keeps
-        // running where it is, and because it is now terminal it is forced to push a
-        // final up the spine when it finishes. `D` ALSO detaches it to the background
-        // `crtr` session (frees the pane; the pi keeps generating). Neither ends it.
-        { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node lifecycle terminal --pane '#{pane_id}' >/dev/null 2>&1"` },
-        { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node lifecycle terminal --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
+        // `d` runs `node demote`: flip the agent to TERMINAL in place — no finalize,
+        // no kill — it keeps running where it is, and because it is now terminal it
+        // is forced to push a final up the spine when it finishes. `D` runs `node
+        // demote --detach`, which ALSO detaches it to the background `crtr` session
+        // (frees the pane; the pi keeps generating). Neither ends it.
+        { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}' >/dev/null 2>&1"` },
+        { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node demote --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
         // Close cascades down the subscribes_to spine (kills the subtree's windows,
         // marks them canceled); revivable. Output discarded — the keypress just acts.
         { name: 'close agent + subtree', key: 'x', cmd: `run-shell "crtr node close --pane '#{pane_id}' >/dev/null 2>&1"` },
@@ -455,3 +489,43 @@ export function installNavBindings() {
     ]).ok;
     return next && prev;
 }
+// ---------------------------------------------------------------------------
+// View-nav bindings — Alt+V then ] / [ cycle the view hosted in a MONITOR pane
+// to the next/prev available view, in place. A VIEW-PREFIXED CHORD, not a bare
+// Alt pair: Alt+V switches into a private one-shot `crtr-view` key table, then
+// ] (next) / [ (prev) fire the cycle — mirroring node cycle's bracket DIRECTION
+// grammar (Alt+] next / Alt+[ prev) while NAMESPACING the brackets so they can
+// never shadow root bindings. This is collision-proof: only ONE root key (M-v)
+// is claimed, and bare Alt pairs are a minefield in real configs (e.g. Alt+,/. 
+// and Alt+]/.[ commonly bound to window/pane nav). The bracket lives in the
+// private table, so it also sidesteps the M-[ vs CSI-introducer ambiguity that
+// dogs installNavBindings' Alt+[. Each key shells `crtr view cycle`, passing the
+// active pane; cycle reads the pane's @crtr_view tag and respawns it on the
+// next/prev view. Output discarded so the keypress never pops a results view.
+// Installed at root boot alongside the node nav + Alt+C menu.
+//
+// NOTE: `M-v` is a GLOBAL root binding — it intercepts Alt+V in every pane/app
+// (e.g. swallowed from the pi editor), the same tradeoff crtr already takes for
+// M-c / M-] / M-[. Intended: crtr owns a small set of Alt chords server-wide.
+// ---------------------------------------------------------------------------
+/** Bind Alt+V → (], [) to the view-monitor cycle. `M-v` enters the private
+ *  `crtr-view` key table (switch-client -T), then ] cycles next / [ cycles prev.
+ *  Best-effort; false if any of the three binds fail. Deliberately distinct from
+ *  installNavBindings' bare Alt+]/Alt+[ (node cycle): the two cycles coexist on
+ *  the same server — brackets alone walk the node graph, Alt+V-then-bracket flips
+ *  view monitors. The bracket keys are bound in the private table, so they NEVER
+ *  shadow the user's root ]/[ and carry no CSI-introducer ambiguity. */
+export function installViewNavBindings() {
+    const enter = tmux([
+        'bind-key', '-n', 'M-v', 'switch-client', '-T', 'crtr-view',
+    ]).ok;
+    const next = tmux([
+        'bind-key', '-T', 'crtr-view', ']', 'run-shell',
+        `crtr view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    const prev = tmux([
+        'bind-key', '-T', 'crtr-view', '[', 'run-shell',
+        `crtr view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    return enter && next && prev;
+}

package/dist/core/scope.d.ts

@@ -1,5 +1,7 @@
 import type { Scope } from '../types.js';
 export declare function builtinSkillsRoot(): string;
+export declare function builtinViewsRoot(): string;
+export declare function builtinMemoryRoot(): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
 export declare function projectScopeRoot(startDir?: string): string | null;
@@ -9,6 +11,15 @@ export declare function ensureProjectScopeRoot(startDir?: string): string;
 export declare function pluginsDir(scope: Scope): string | null;
 export declare function marketplacesDir(scope: Scope): string | null;
 export declare function scopeSkillsDir(scope: Scope): string | null;
+/** Where substrate memory documents live per scope. Builtin memory is the
+ *  special case — its own package dir (builtinMemoryRoot, a sibling of
+ *  builtin-skills), NOT scopeRoot('builtin')/memory — mirroring viewsDir's
+ *  builtin handling. User and project memory live at scopeRoot(scope)/memory. */
+export declare function scopeMemoryDir(scope: Scope): string | null;
+/** Where view definition dirs live per scope. Builtin views sit directly under
+ *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
+ *  matching the loader's `<root>/<name>/view.mjs` resolution. */
+export declare function viewsDir(scope: Scope): string | null;
 export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
 export declare function listScopes(scopeArg: string | undefined): Scope[];
 export declare function resetScopeCache(): void;