npm - @crouton-kit/crouter - Versions diffs - 0.3.13 → 0.3.14 - Mend

@crouton-kit/crouter 0.3.13 → 0.3.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/dist/commands/__tests__/human.test.js +73 -2
package/dist/commands/human/queue.d.ts +1 -0
package/dist/commands/human/queue.js +89 -2
package/dist/commands/human/shared.d.ts +5 -0
package/dist/commands/human/shared.js +15 -0
package/dist/commands/human.js +4 -2
package/dist/commands/node.js +195 -24
package/dist/core/__tests__/passive-subscription.test.d.ts +1 -0
package/dist/core/__tests__/passive-subscription.test.js +141 -0
package/dist/core/__tests__/subcommand-tier.test.d.ts +1 -0
package/dist/core/__tests__/subcommand-tier.test.js +97 -0
package/dist/core/canvas/paths.d.ts +4 -0
package/dist/core/canvas/paths.js +6 -0
package/dist/core/command.js +40 -7
package/dist/core/feed/feed.js +11 -9
package/dist/core/feed/passive.d.ts +17 -0
package/dist/core/feed/passive.js +79 -0
package/dist/core/help.d.ts +45 -12
package/dist/core/help.js +42 -4
package/dist/core/runtime/demote.d.ts +14 -0
package/dist/core/runtime/demote.js +103 -0
package/dist/core/runtime/kickoff.d.ts +9 -0
package/dist/core/runtime/kickoff.js +19 -1
package/dist/core/runtime/launch.d.ts +12 -1
package/dist/core/runtime/launch.js +18 -2
package/dist/core/runtime/presence.d.ts +1 -18
package/dist/core/runtime/presence.js +7 -51
package/dist/core/runtime/promote.d.ts +4 -0
package/dist/core/runtime/promote.js +21 -6
package/dist/core/runtime/roadmap.d.ts +5 -4
package/dist/core/runtime/roadmap.js +9 -16
package/dist/core/runtime/spawn.js +7 -2
package/dist/core/runtime/tmux.d.ts +11 -12
package/dist/core/runtime/tmux.js +57 -26
package/dist/pi-extensions/canvas-commands.d.ts +34 -0
package/dist/pi-extensions/canvas-commands.js +100 -0
package/dist/pi-extensions/canvas-goal-capture.d.ts +18 -0
package/dist/pi-extensions/canvas-goal-capture.js +53 -0
package/dist/pi-extensions/canvas-passive-context.d.ts +32 -0
package/dist/pi-extensions/canvas-passive-context.js +114 -0
package/package.json +1 -1

package/dist/core/runtime/demote.js ADDED Viewed

@@ -0,0 +1,103 @@
+// demote.ts — the "graduate this agent" action behind `crtr node demote`.
+//
+// Demote finishes the agent occupying a tmux pane and recycles that pane for
+// fresh work, in three steps:
+//
+//   1. Finalize — push the agent's last surfaced message as a `final` report so
+//      every subscriber/manager waiting on it is unblocked, and mark it done.
+//   2. Close    — kill the agent's pi (respawn-pane -k tears it down in place).
+//   3. Recycle  — boot a fresh resident root in that same pane (a new `crtr`).
+//
+// The agent's real conversation lives inside pi (not on disk), so the final
+// body is its newest report (which, on a natural stop, IS its last assistant
+// message) — falling back to a short note when it never reported.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getNode, updateNode } from '../canvas/index.js';
+import { reportsDir } from '../canvas/paths.js';
+import { pushFinal } from '../feed/feed.js';
+import { spawnNode } from './nodes.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { respawnPane, piCommand, paneLocation, nodeSession } from './tmux.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { getFocus, setFocus } from './presence.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+/** The agent's most recent surfaced message: the newest reports/*.md body with
+ *  its YAML frontmatter stripped. Empty string when the node never reported. */
+function lastReportBody(nodeId) {
+    try {
+        const dir = reportsDir(nodeId);
+        const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+        if (files.length === 0)
+            return '';
+        let newest = '';
+        let newestMs = -1;
+        for (const f of files) {
+            const ms = statSync(join(dir, f)).mtimeMs;
+            if (ms > newestMs) {
+                newestMs = ms;
+                newest = f;
+            }
+        }
+        const raw = readFileSync(join(dir, newest), 'utf8');
+        // Strip leading YAML frontmatter: ---\n …\n---\n<body>
+        const m = /^---\n[\s\S]*?\n---\n/.exec(raw);
+        return (m !== null ? raw.slice(m[0].length) : raw).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `demoted:false` when there is no pane to act on. */
+export async function demoteNode(nodeId, callerPane) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return { demoted: false, finalized: false, newRoot: null, delivered: [] };
+    const pane = callerPane ?? process.env['TMUX_PANE'];
+    if (pane === undefined || pane === '') {
+        return { demoted: false, finalized: false, newRoot: null, delivered: [] };
+    }
+    // 1. Finalize — fan the agent's last message out as a `final`, mark it done.
+    const body = lastReportBody(nodeId) ||
+        `Closed via demote — no final summary was authored by ${meta.name}.`;
+    let delivered = [];
+    let finalized = false;
+    try {
+        const res = await pushFinal(nodeId, body);
+        delivered = res.deliveredTo;
+        finalized = true;
+    }
+    catch { /* recycle the pane even if the report failed */ }
+    // The demoted node no longer holds a window — the pane is being reclaimed.
+    try {
+        updateNode(nodeId, { window: null, tmux_session: null });
+    }
+    catch { /* best-effort */ }
+    if (getFocus() === nodeId)
+        setFocus('');
+    // 2 + 3. Recycle — boot a fresh resident root in the SAME pane.
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const loc = paneLocation(pane);
+    const { launch } = buildLaunchSpec('general', 'base');
+    const root = spawnNode({
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: meta.cwd,
+        name: 'general',
+        parent: null,
+        launch,
+    });
+    if (loc !== null)
+        updateNode(root.node_id, { tmux_session: loc.session, window: loc.window });
+    const fresh = getNode(root.node_id);
+    const inv = buildPiArgv(fresh);
+    const env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), [FRONT_DOOR_ENV]: '1' };
+    const ok = respawnPane({ pane, cwd: meta.cwd, env, command: piCommand(inv.argv) });
+    return { demoted: ok, finalized, newRoot: root.node_id, delivered };
+}

package/dist/core/runtime/kickoff.d.ts CHANGED Viewed

@@ -6,6 +6,15 @@ export declare function readGoal(nodeId: string): string | null;
 /** Persist the spawning prompt as the node's goal. No-op for an empty prompt
  *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
 export declare function writeGoal(nodeId: string, text: string): void;
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export declare const REVIVE_KICKOFF_SENTINEL = "You have been revived fresh after a context refresh";
 /** The yield-message file — a short note `crtr node yield` records for the next
  *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
 export declare function yieldMessagePath(nodeId: string): string;

package/dist/core/runtime/kickoff.js CHANGED Viewed

@@ -41,6 +41,24 @@ export function writeGoal(nodeId, text) {
     mkdirSync(contextDir(nodeId), { recursive: true });
     writeFileSync(goalPath(nodeId), body + '\n', 'utf8');
 }
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export function captureGoalIfAbsent(nodeId, text) {
+    const existing = readGoal(nodeId);
+    if (existing !== null && existing.trim() !== '')
+        return false;
+    const body = text.trim();
+    if (body === '')
+        return false;
+    writeGoal(nodeId, body);
+    return true;
+}
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export const REVIVE_KICKOFF_SENTINEL = 'You have been revived fresh after a context refresh';
 /** The yield-message file — a short note `crtr node yield` records for the next
  *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
 export function yieldMessagePath(nodeId) {
@@ -112,7 +130,7 @@ export function buildReviveKickoff(meta) {
     // Consume the one-shot yield note first so it never shows in the dir listing.
     const yieldMsg = consumeYieldMessage(nodeId);
     const parts = [
-        'You have been revived fresh after a context refresh — your previous in-memory ' +
+        `${REVIVE_KICKOFF_SENTINEL} — your previous in-memory ` +
             'context is gone, by design. Everything below was just read from disk; it is your ' +
             'full bearings. Rebuild from it and continue toward your goal.',
     ];

package/dist/core/runtime/launch.d.ts CHANGED Viewed

@@ -2,9 +2,15 @@ import type { NodeMeta, LaunchSpec, Mode } from '../canvas/index.js';
 export declare const CANVAS_STOPHOOK_PATH: string;
 export declare const CANVAS_INBOX_WATCHER_PATH: string;
 export declare const CANVAS_NAV_PATH: string;
+export declare const CANVAS_GOAL_CAPTURE_PATH: string;
+export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
+export declare const CANVAS_COMMANDS_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
- *  graph chrome). All self-gate on CRTR_NODE_ID. */
+ *  graph chrome), goal-capture (persist the first user message as the goal),
+ *  passive-context (drain passive backlog as pre-text on the next message),
+ *  commands (the /promote slash-command). All self-gate on CRTR_NODE_ID.
+ *  goal-capture precedes passive-context so it reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
@@ -24,6 +30,11 @@ export interface PiInvocation {
     /** env to merge into the process. */
     env: Record<string, string>;
 }
+/** The pi session display name — the editor label in the top-left. Shows the
+ *  node's name plus its current mode so base vs orchestrator reads at a glance
+ *  (e.g. `developer (orchestrator)`). Recomputed from `meta.mode` on every
+ *  revive, so a base→orchestrator polymorph updates the label. */
+export declare function editorLabel(meta: NodeMeta): string;
 /** Construct the pi invocation for a node.
  *  - fresh start: pass `prompt` (the node's first user message), no resume.
  *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).

package/dist/core/runtime/launch.js CHANGED Viewed

@@ -27,13 +27,22 @@ function resolveExtension(name) {
 export const CANVAS_STOPHOOK_PATH = resolveExtension('canvas-stophook');
 export const CANVAS_INBOX_WATCHER_PATH = resolveExtension('canvas-inbox-watcher');
 export const CANVAS_NAV_PATH = resolveExtension('canvas-nav');
+export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
+export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
+export const CANVAS_COMMANDS_PATH = resolveExtension('canvas-commands');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
- *  graph chrome). All self-gate on CRTR_NODE_ID. */
+ *  graph chrome), goal-capture (persist the first user message as the goal),
+ *  passive-context (drain passive backlog as pre-text on the next message),
+ *  commands (the /promote slash-command). All self-gate on CRTR_NODE_ID.
+ *  goal-capture precedes passive-context so it reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
     CANVAS_STOPHOOK_PATH,
     CANVAS_INBOX_WATCHER_PATH,
     CANVAS_NAV_PATH,
+    CANVAS_GOAL_CAPTURE_PATH,
+    CANVAS_PASSIVE_CONTEXT_PATH,
+    CANVAS_COMMANDS_PATH,
 ];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */
@@ -59,6 +68,13 @@ export function buildLaunchSpec(kind, mode, opts = {}) {
     };
     return { launch, lifecycle: p.lifecycle, skills: p.skills };
 }
+/** The pi session display name — the editor label in the top-left. Shows the
+ *  node's name plus its current mode so base vs orchestrator reads at a glance
+ *  (e.g. `developer (orchestrator)`). Recomputed from `meta.mode` on every
+ *  revive, so a base→orchestrator polymorph updates the label. */
+export function editorLabel(meta) {
+    return `${meta.name} (${meta.mode})`;
+}
 /** Construct the pi invocation for a node.
  *  - fresh start: pass `prompt` (the node's first user message), no resume.
  *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
@@ -69,7 +85,7 @@ export function buildPiArgv(meta, opts = {}) {
     for (const ext of spec?.extensions ?? CANVAS_EXTENSIONS) {
         argv.push('-e', ext);
     }
-    argv.push('-n', meta.name);
+    argv.push('-n', editorLabel(meta));
     if (opts.resumeSessionId !== undefined)
         argv.push('--resume', opts.resumeSessionId);
     if (spec?.model !== undefined)

package/dist/core/runtime/presence.d.ts CHANGED Viewed

@@ -31,25 +31,8 @@ export declare function focusNode(nodeId: string): {
  *
  *  Falls back to window focus when there is no caller pane (not inside tmux) or
  *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export declare function focusNodeInPlace(nodeId: string, callerPane?: string): {
+export declare function focusNodeInPlace(nodeId: string, callerPane?: string, callerNodeId?: string): {
     focused: boolean;
     session: string | null;
     inPlace: boolean;
 };
-/** Send a node's running pi OUT of the caller's pane and into a window in the
- *  shared global session, leaving a fresh shell where it was — the pane
- *  "becomes a terminal" and the agent keeps running, detached, in the
- *  background. The inverse of `focusNodeInPlace`; reversible via `node focus`.
- *
- *  Mechanism: open a shell window in the global session, then swap that shell
- *  pane INTO the caller's pane — tmux exchanges the two panes, so the node's pi
- *  pane lands in the shell's window (global session) and the shell lands in the
- *  caller's pane. The node's meta is re-pointed to the new window so the daemon
- *  keeps supervising it.
- *
- *  Best-effort; `demoted:false` when not in tmux or any tmux step fails. */
-export declare function demoteNode(nodeId: string, callerPane?: string): {
-    demoted: boolean;
-    session: string | null;
-    window: string | null;
-};

package/dist/core/runtime/presence.js CHANGED Viewed

@@ -19,7 +19,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { join } from 'node:path';
 import { crtrHome, getNode, updateNode } from '../canvas/index.js';
-import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane, openShellWindow, closeWindow, ensureSession, nodeSession } from './tmux.js';
+import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane } from './tmux.js';
 // ---------------------------------------------------------------------------
 // Focus pointer
 // ---------------------------------------------------------------------------
@@ -99,7 +99,7 @@ export function focusNode(nodeId) {
  *
  *  Falls back to window focus when there is no caller pane (not inside tmux) or
  *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export function focusNodeInPlace(nodeId, callerPane) {
+export function focusNodeInPlace(nodeId, callerPane, callerNodeId) {
     const meta = getNode(nodeId);
     // Always write the pointer so the dashboard reflects intent even on failure.
     setFocus(nodeId);
@@ -140,59 +140,15 @@ export function focusNodeInPlace(nodeId, callerPane) {
         catch { /* best-effort */ }
         // The caller is the node running this focus (its pi process owns callerPane).
         // Its pane moved to the target's old window, so re-point its window there.
-        const callerNodeId = process.env['CRTR_NODE_ID'];
-        if (callerNodeId !== undefined && callerNodeId.trim() !== '' && callerNodeId !== nodeId) {
+        // Prefer an explicit id (the `node cycle` tmux binding runs outside any pi,
+        // so CRTR_NODE_ID is unset there) and fall back to the env for `node focus`.
+        const cnid = callerNodeId ?? process.env['CRTR_NODE_ID'];
+        if (cnid !== undefined && cnid.trim() !== '' && cnid !== nodeId) {
             try {
-                updateNode(callerNodeId, { window });
+                updateNode(cnid, { window });
             }
             catch { /* best-effort */ }
         }
     }
     return { focused: ok, session, inPlace: true };
 }
-// ---------------------------------------------------------------------------
-// Demote — detach the agent in the caller's pane to the background
-// ---------------------------------------------------------------------------
-/** Send a node's running pi OUT of the caller's pane and into a window in the
- *  shared global session, leaving a fresh shell where it was — the pane
- *  "becomes a terminal" and the agent keeps running, detached, in the
- *  background. The inverse of `focusNodeInPlace`; reversible via `node focus`.
- *
- *  Mechanism: open a shell window in the global session, then swap that shell
- *  pane INTO the caller's pane — tmux exchanges the two panes, so the node's pi
- *  pane lands in the shell's window (global session) and the shell lands in the
- *  caller's pane. The node's meta is re-pointed to the new window so the daemon
- *  keeps supervising it.
- *
- *  Best-effort; `demoted:false` when not in tmux or any tmux step fails. */
-export function demoteNode(nodeId, callerPane) {
-    const meta = getNode(nodeId);
-    if (meta === null)
-        return { demoted: false, session: null, window: null };
-    const pane = callerPane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
-    if (pane === undefined || pane === '') {
-        return { demoted: false, session: meta.tmux_session ?? null, window: meta.window ?? null };
-    }
-    const session = nodeSession();
-    ensureSession(session, meta.cwd);
-    const shell = openShellWindow({ session, name: meta.name, cwd: meta.cwd });
-    if (shell === null)
-        return { demoted: false, session, window: meta.window ?? null };
-    // Swap the fresh shell into the caller's pane; the node's pi pane is exchanged
-    // out into the shell's window (now living in the global session).
-    const ok = swapPaneInPlace(shell.pane, pane);
-    if (!ok) {
-        closeWindow(shell.window);
-        return { demoted: false, session, window: meta.window ?? null };
-    }
-    // The node's pi now occupies the shell window; re-point its meta there so
-    // liveness checks resolve the right window.
-    try {
-        updateNode(nodeId, { tmux_session: session, window: shell.window });
-    }
-    catch { /* best-effort */ }
-    // The caller pane reverted to a terminal — if this node held focus, clear it.
-    if (getFocus() === nodeId)
-        setFocus('');
-    return { demoted: true, session, window: shell.window };
-}

package/dist/core/runtime/promote.d.ts CHANGED Viewed

@@ -4,6 +4,10 @@ export interface PromoteResult {
     /** Orchestration guidance to surface into the node's current context now. */
     guidance: string;
     roadmapWritten: boolean;
+    /** Absolute path to the node's roadmap doc (context/roadmap.md). */
+    roadmapPath: string;
+    /** Absolute path to the node's goal doc (context/initial-prompt.md). */
+    goalPath: string;
 }
 /** Promote a node to resident orchestrator, optionally specializing its kind
  *  (e.g. a `general` worker becoming a `developer.orchestrator`). Idempotent:

package/dist/core/runtime/promote.js CHANGED Viewed

@@ -19,7 +19,8 @@ import { loadKernel, loadPersona } from '../personas/index.js';
 import { resolveSkill } from '../resolver.js';
 import { readText } from '../fs-utils.js';
 import { parseFrontmatter } from '../frontmatter.js';
-import { hasRoadmap, seedRoadmap, readRoadmap } from './roadmap.js';
+import { hasRoadmap, seedRoadmap, readRoadmap, roadmapPath } from './roadmap.js';
+import { readGoal, goalPath } from './kickoff.js';
 /** Load a skill's body text by name, or null if it can't be resolved. Used to
  *  inline a kind's roadmap-shaping skill into the promotion guidance dump. */
 function loadSkillBody(name) {
@@ -43,16 +44,21 @@ function orchestrationGuidance(nodeId, kind) {
         : undefined;
     const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
+    const rmPath = roadmapPath(nodeId);
+    const goal = readGoal(nodeId);
     const parts = [
         `You are now a RESIDENT ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
         'Your job is to manage context and delegate — not to do the goal yourself.',
         '',
         kernel,
     ];
+    if (goal !== null && goal.trim() !== '') {
+        parts.push('', `--- Your goal (${goalPath(nodeId)}) ---`, '', goal.trim());
+    }
     if (skillBody) {
         parts.push('', `--- How to shape a ${kind} roadmap (skill: ${roadmapSkill}) ---`, '', skillBody);
     }
-    parts.push('', 'Your roadmap scaffold (`context/roadmap.md`) — author it now: state the goal, exit criteria, scope assumptions, and the phase skeleton, using the approach above:', '', roadmap, '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
     return parts.join('\n');
 }
 /** Promote a node to resident orchestrator, optionally specializing its kind
@@ -71,15 +77,24 @@ export function promote(nodeId, opts = {}) {
     // nodeEnv reads meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for
     // the live process's children too.
     const { launch } = buildLaunchSpec(targetKind, 'orchestrator');
-    // Seed a roadmap scaffold if absent so the file exists for a refresh. The
-    // node fills in the goal/body next, guided by the kind skill dumped below.
+    // Seed a barebones roadmap scaffold if absent so the file exists for a
+    // refresh. Pre-fill its Goal from the node's goal doc when present (set at
+    // spawn, or captured from the first user message); the node fleshes out the
+    // body next, guided by the kind skill dumped below.
     let roadmapWritten = false;
     if (!hasRoadmap(nodeId)) {
-        seedRoadmap(nodeId);
+        const goal = readGoal(nodeId);
+        seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
         roadmapWritten = true;
     }
     const meta = updateNode(nodeId, { kind: targetKind, lifecycle: 'resident', mode: 'orchestrator', launch });
-    return { meta, guidance: orchestrationGuidance(nodeId, targetKind), roadmapWritten };
+    return {
+        meta,
+        guidance: orchestrationGuidance(nodeId, targetKind),
+        roadmapWritten,
+        roadmapPath: roadmapPath(nodeId),
+        goalPath: goalPath(nodeId),
+    };
 }
 /** Request a refresh-yield: discard in-memory context and revive fresh against
  *  the roadmap. A *terminal* node that yields is choosing to persist — it

package/dist/core/runtime/roadmap.d.ts CHANGED Viewed

@@ -1,10 +1,11 @@
 export declare function roadmapPath(nodeId: string): string;
 export declare function hasRoadmap(nodeId: string): boolean;
 export declare function readRoadmap(nodeId: string): string | null;
-/** Seed a fresh roadmap SCAFFOLD. No goal is required — promotion lays this
- *  down so the file exists for a refresh, and the owner authors the goal +
- *  body as its next act (guided by its kind's roadmap skill). `goal`/
- *  `exitCriteria` are optional overrides. Idempotent only if you intend it —
+/** Seed a fresh, EXTREMELY BAREBONES roadmap scaffold — just the section
+ *  skeleton with one-line prompts. Promotion lays this down so the file exists
+ *  for a refresh; the owner fleshes it out as its next act (guided by its
+ *  kind's roadmap skill). `goal`/`exitCriteria` pre-fill those sections when
+ *  known (e.g. from the node's goal doc). Idempotent only if you intend it —
  *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
 export declare function seedRoadmap(nodeId: string, opts?: {
     goal?: string;

package/dist/core/runtime/roadmap.js CHANGED Viewed

@@ -20,32 +20,25 @@ export function readRoadmap(nodeId) {
     const p = roadmapPath(nodeId);
     return existsSync(p) ? readFileSync(p, 'utf8') : null;
 }
-/** Seed a fresh roadmap SCAFFOLD. No goal is required — promotion lays this
- *  down so the file exists for a refresh, and the owner authors the goal +
- *  body as its next act (guided by its kind's roadmap skill). `goal`/
- *  `exitCriteria` are optional overrides. Idempotent only if you intend it —
+/** Seed a fresh, EXTREMELY BAREBONES roadmap scaffold — just the section
+ *  skeleton with one-line prompts. Promotion lays this down so the file exists
+ *  for a refresh; the owner fleshes it out as its next act (guided by its
+ *  kind's roadmap skill). `goal`/`exitCriteria` pre-fill those sections when
+ *  known (e.g. from the node's goal doc). Idempotent only if you intend it —
  *  call sites guard on hasRoadmap to avoid clobbering an evolved map. */
 export function seedRoadmap(nodeId, opts = {}) {
     const dir = contextDir(nodeId);
     mkdirSync(dir, { recursive: true });
     const body = `# Roadmap
-<!-- frozen core: set once, rarely changes -->
 ## Goal
-${opts.goal?.trim() ?? '- (state the high-level goal you now own — write this as your first act)'}
+${opts.goal?.trim() ?? '(the goal you now own)'}
 ## Exit criteria
-${opts.exitCriteria?.trim() ?? '- (define what "done" looks like)'}
+${opts.exitCriteria?.trim() ?? '(what "done" looks like)'}
-<!-- evolving body: keep this current as you learn scope + intent -->
-## Scope assumptions / non-goals
-- (record what's out of scope and what's settled — e.g. "reuse existing auth", "security isn't a concern here" — so children inherit the framing)
-## Strategy / phases
-- (your high-level shape of how you reach the goal; the ordered phases from here to done, the current one carrying a one-line status. Each phase can become a child whose own roadmap is that phase)
-## Active context
-- (the context/ files currently relevant to the work, by path; none yet)
+## Phases
+(ordered phases from here to done; the current one carries a one-line status)
 `;
     writeFileSync(roadmapPath(nodeId), body);
     return body;

package/dist/core/runtime/spawn.js CHANGED Viewed

@@ -11,7 +11,7 @@ import { FRONT_DOOR_ENV } from './front-door.js';
 import { spawnNode, currentNodeContext } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, } from './tmux.js';
+import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, installNavBindings, } from './tmux.js';
 import { updateNode, getNode } from '../canvas/index.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** Create a root node and bring up its pi. Returns the node; for 'inline' this
@@ -43,12 +43,17 @@ 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 live on this server (idempotent, in-tmux only).
+    // Make the Alt+C action menu + Alt+] / Alt+[ nav keys live on this server
+    // (idempotent, in-tmux only).
     if (inTmux()) {
         try {
             installMenuBinding();
         }
         catch { /* best-effort */ }
+        try {
+            installNavBindings();
+        }
+        catch { /* best-effort */ }
     }
     if (opts.placement === 'session') {
         updateNode(meta.node_id, { tmux_session: session });

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

@@ -39,18 +39,6 @@ export interface OpenWindowOpts {
  *  `-a` also keeps node windows off index 0, which is reserved for the optional
  *  dashboard. */
 export declare function openNodeWindow(opts: OpenWindowOpts): string | null;
-/** Open a background window running a plain login shell (no pi) and return its
- *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
- *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
- *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
-export declare function openShellWindow(opts: {
-    session: string;
-    name: string;
-    cwd: string;
-}): {
-    window: string;
-    pane: string;
-} | null;
 /** Bring a node's window forefront. Switches client across roots when needed. */
 export declare function focusWindow(session: string, window: string): boolean;
 /** Close a node's window (drop it from the UI). */
@@ -63,6 +51,12 @@ export declare function paneOfWindow(session: string, window: string): string |
  *  are not, so the node→window mapping must be re-derived from the pane. Returns
  *  null if the pane is gone or tmux fails. */
 export declare function windowOfPane(pane: string): string | null;
+/** The session + window a pane currently lives in. Used by demote to place the
+ *  recycled root's meta on the pane it respawns into. Null if tmux fails. */
+export declare function paneLocation(pane: string): {
+    session: string;
+    window: string;
+} | null;
 /** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
  *  caller's window active, so the target's pane appears where the caller is
  *  rather than navigating the client off to the target's window. The caller's
@@ -105,3 +99,8 @@ export declare function selectWindow(session: string, window: string): boolean;
 export declare function switchClient(session: string): boolean;
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
 export declare function installMenuBinding(): boolean;
+/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
+ *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
+ *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
+ */
+export declare function installNavBindings(): boolean;