@crouton-kit/crouter 0.3.40 → 0.3.41

package/dist/clients/attach/chat-view.js

@@ -24,6 +24,7 @@ import { Container, Loader, Spacer, Text } from '@earendil-works/pi-tui';
 import { AssistantMessageComponent, BashExecutionComponent, BranchSummaryMessageComponent, CompactionSummaryMessageComponent, CustomMessageComponent, getMarkdownTheme, parseSkillBlock, SkillInvocationMessageComponent, ToolExecutionComponent, UserMessageComponent, } from '@earendil-works/pi-coding-agent';
 import { ContextMessageComponent } from './context-message.js';
 import { CRTR_OUTPUT_CUSTOM_TYPE, CrtrOutputMessageComponent, createCrtrBashToolDefinition, } from './crtr-output-render.js';
+import { CRTR_CYCLE_DIVIDER_CUSTOM_TYPE } from '../../core/runtime/session-cycles.js';
 /** customType stamped on the injected `<crtr-context>` bearings block (mirrors
  *  CONTEXT_INTRO_CUSTOM_TYPE in canvas-context-intro.ts — kept as a local literal
  *  so the viewer never imports the in-process extension). */
@@ -438,6 +439,16 @@ export class ChatView {
                         this.append(new CrtrOutputMessageComponent(this.userMessageText(message), this.toolOutputExpanded, this.crtrOutputTheme()));
                         break;
                     }
+                    // A refresh-yield cycle boundary (session-cycles.ts, synthetic — never
+                    // persisted): render as a dim rule rather than the generic custom-
+                    // message card, so scrolling through a multi-cycle node's full history
+                    // reads as one conversation with clear seams between cycles.
+                    if (message.customType === CRTR_CYCLE_DIVIDER_CUSTOM_TYPE) {
+                        this.append(new Spacer(1));
+                        this.append(new Text(this.dimStyle(`── ${this.userMessageText(message)} ──`), 1, 0));
+                        this.append(new Spacer(1));
+                        break;
+                    }
                     const component = new CustomMessageComponent(message, undefined, getMarkdownTheme());
                     component.setExpanded(this.toolOutputExpanded);
                     this.append(component);

package/dist/clients/web/server.js

@@ -7,8 +7,9 @@
 //   • POST /__crtr/source   → the source + command bridge: decode a SourceRequest
 //                             and run it through the LOCAL transport (exec/file/
 //                             http in this cwd). This serves views' READS and the
-//                             command WRITES (`crtr …` subprocesses). Lifted here
-//                             from the deleted `view serve`.
+//                             command WRITES (`crtr …` subprocesses via shelled-out
+//                             CLI). The bridge is the ONLY sanctioned writer to the
+//                             canvas; relay clients NEVER launch pi directly.
 //   • GET  /__crtr/events   → the SSE change-invalidation lane (events.ts).
 //   • WS   /node/<id>       → open that node's ALREADY-running broker `view.sock`
 //                             and relay frames VERBATIM both directions. The relay
@@ -43,12 +44,6 @@ import { runSourceRequest } from '../../core/view/bridge.js';
 import { startEventHub } from './events.js';
 import { createDevServer } from './dev-server.js';
 import { SOURCE_CACHE_TTL_MS, isCoalescableSourceRequest } from './source-cache.js';
-// ── Hearth product seam: model-auth lane (P3.3b, Silas-approved exception) ──
-// This is the ONLY Hearth-aware import in this file. All OAuth/status/start/
-// finish product logic lives in core/hearth/model-auth-guest.ts; this module
-// provides only routing + relay-token enforcement for the lane (see the route
-// block in startWebServer below).
-import { handleHearthModelAuthRequest } from '../../core/hearth/model-auth-guest.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** Candidate dirs to serve the shell SPA bundle from, in priority order: an
  *  explicit override, the compiled-module-relative `dist/web-client/` (what
@@ -381,8 +376,8 @@ export async function startWebServer(opts) {
     });
     // The SSE change lane — one hub, fanned to every connected EventSource.
     const eventHub = startEventHub();
-    // Same-origin allowlist: tokenless localhost pages keep the legacy guard,
-    // while a valid relay token can authorize remote Hearth route origins that would
+    // Same-origin allowlist: tokenless localhost pages are implicitly allowed,
+    // while a valid relay token can authorize remote/guest route origins that would
     // otherwise be rejected by originAllowed().
     let allowedOrigins = new Set();
     const originAllowed = (origin) => {
@@ -447,24 +442,6 @@ export async function startWebServer(opts) {
                 eventHub.addClient(res);
                 return;
             }
-            // ── Hearth product seam: model-auth lane ──
-            // Isolated per the P3.3a/P3.3b approved exception. ALL Hearth/OAuth logic
-            // lives in core/hearth/model-auth-guest.ts; this block is ONLY routing +
-            // the relay-token gate. CRITICAL: this lane uses the STRICT token-only
-            // predicate requestTokenMatches(req, token), never requestAllowed() —
-            // requestAllowed() also accepts a same-origin loopback request with NO
-            // token at all, which would make this lane tokenless on local/dev binds.
-            // Every /__hearth/model-auth/* request fails closed (401) without an
-            // exact relay-token match, even on loopback.
-            if (pathname.startsWith('/__hearth/model-auth/anthropic/')) {
-                if (!requestTokenMatches(req, token)) {
-                    res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' });
-                    res.end('relay token required\n');
-                    return;
-                }
-                void handleHearthModelAuthRequest(req, res);
-                return;
-            }
             // --dev: Vite middleware owns all remaining asset/HTML serving (incl. its
             // own SPA fallback). It is mounted AFTER the bridge + SSE checks above, so
             // those never fall through to Vite.

package/dist/clients/web/web-cmd.js

@@ -86,7 +86,7 @@ const webServeLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Binds a long-running HTTP+WebSocket server on the requested host and port and keeps serving until interrupted (ctrl+c / SIGTERM). Safe to run non-interactively (daemon-like): it prints the URL and serves.',
-            'Serves the shell SPA (static dist/web-client/, or Vite middleware under --dev), runs the POST /__crtr/source bridge (exec/file/http in this cwd), streams the GET /__crtr/events SSE change lane, and on a browser ws://HOST:<port>/node/<id> connection opens that node\'s running broker view.sock and relays frames VERBATIM both directions. Non-loopback binds require a token so the remote Hearth route is not an unauthenticated command surface.',
+            'Serves the shell SPA (static dist/web-client/, or Vite middleware under --dev), runs the POST /__crtr/source bridge (exec/file/http in this cwd), streams the GET /__crtr/events SSE change lane, and on a browser ws://HOST:<port>/node/<id> connection opens that node\'s running broker view.sock and relays frames VERBATIM both directions. Non-loopback binds require a token so the remote route is not an unauthenticated command surface.',
             'The relay NEVER spawns pi and NEVER writes any session — it only opens a socket to an already-running broker; if the broker is not running, the browser connection is closed with a clear reason. All graph mutations go through `crtr` subprocesses the bridge runs.',
         ],
     },

package/dist/commands/__tests__/revive-now-gate.test.js

@@ -0,0 +1,60 @@
+// Regression for issue #115: `crtr canvas revive --now` rejected exactly the
+// provider-fault nodes the canvas dashboard flags as ⚠ "needs you"
+// (status-glyph.ts `faultDispositionText`), because the old gate required
+// `retry.disposition === 'auto'` — the one disposition "needs you" NEVER is.
+// Run with: node --import tsx/esm --test 'src/commands/__tests__/revive-now-gate.test.ts'
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { isNowEligibleFault } from '../revive.js';
+import { faultNeedsYou } from '../../core/canvas/status-glyph.js';
+function fault(over) {
+    return {
+        link: 'pi→provider',
+        op: 'generation turn',
+        kind: 'overloaded',
+        retry: { disposition: 'auto', by: 'daemon' },
+        message: 'boom',
+        since: new Date().toISOString(),
+        logPath: '/tmp/fault.log',
+        ...over,
+    };
+}
+test('null fault is never --now eligible', () => {
+    assert.equal(isNowEligibleFault(null), false);
+});
+test('daemon-owned auto retry is eligible (kick it early)', () => {
+    assert.equal(isNowEligibleFault(fault({ retry: { disposition: 'auto', by: 'daemon' } })), true);
+});
+test('client-owned auto retry (redialing) is refused — already being handled', () => {
+    assert.equal(isNowEligibleFault(fault({ retry: { disposition: 'auto', by: 'client' } })), false);
+});
+// The bug: exhausted-retry / immediate-fatal pi→provider faults render "needs
+// you" on the dashboard (faultNeedsYou === true) but the old gate rejected
+// them outright — no sanctioned recovery verb existed for exactly the nodes
+// the dashboard told the user to attend to.
+test('fatal pi→provider fault ("needs you") is now eligible', () => {
+    const f = fault({ retry: { disposition: 'fatal' } });
+    assert.equal(faultNeedsYou(f), true);
+    assert.equal(isNowEligibleFault(f), true);
+});
+test('manual pi→provider fault ("needs you") is eligible', () => {
+    const f = fault({ retry: { disposition: 'manual' } });
+    assert.equal(faultNeedsYou(f), true);
+    assert.equal(isNowEligibleFault(f), true);
+});
+test('a non-pi→provider fault (e.g. a daemon→node wedge) is refused — --now cannot clear it', () => {
+    const f = fault({ link: 'daemon→node', kind: 'wedged', retry: { disposition: 'manual' } });
+    assert.equal(isNowEligibleFault(f), false);
+});
+test('faultNeedsYou matches the gate for every disposition (no drift between dashboard and --now)', () => {
+    for (const disposition of ['auto', 'manual', 'fatal']) {
+        const f = fault({ retry: { disposition, by: 'daemon' } });
+        if (disposition === 'auto') {
+            assert.equal(faultNeedsYou(f), false);
+        }
+        else {
+            assert.equal(faultNeedsYou(f), true);
+            assert.equal(isNowEligibleFault(f), true);
+        }
+    }
+});

package/dist/commands/canvas-rebuild-index.js

@@ -1,10 +1,10 @@
 // `crtr canvas rebuild-index` — re-derive the node-table index from on-disk metas.
 //
 // canvas.db's node rows are a derived index over `nodes/<id>/meta.json`. When the
-// db is absent or stale relative to the metas — most concretely a Hearth guest
-// recreate-from-template, where node data lives on the durable Volume but
-// canvas.db lives on local disk that the recreate wipes — this verb rebuilds the
-// rows (identity columns) from the surviving metas via `rebuildIndex()`, so a
+// db is absent or stale relative to the metas — most concretely a remote/guest
+// deployment's recreate-from-template, where node data lives on a durable Volume
+// but canvas.db lives on local disk that the recreate wipes — this verb rebuilds
+// the rows (identity columns) from the surviving metas via `rebuildIndex()`, so a
 // subsequent `canvas revive` finds its node again.
 //
 // Fails loud if metas are present but the rebuild yields zero rows: a silent
@@ -29,7 +29,7 @@ function countOnDiskMetas() {
 export const canvasRebuildIndexLeaf = defineLeaf({
     name: 'rebuild-index',
     description: 're-derive node rows in canvas.db from on-disk nodes/<id>/meta.json',
-    whenToUse: 'canvas.db is missing or stale relative to the on-disk node metas and you need its node rows re-derived — most concretely after a Hearth guest recreate-from-template, where node data survives on the durable Volume but canvas.db (local disk) was wiped, so a `canvas revive` would otherwise find no row. Identity columns are rebuilt from each meta; runtime columns (status/intent/pi_pid/window/tmux) take their quiescent defaults, and subscribes_to edges are left intact',
+    whenToUse: 'canvas.db is missing or stale relative to the on-disk node metas and you need its node rows re-derived — most concretely after a remote/guest deployment\'s recreate-from-template, where node data survives on a durable Volume but canvas.db (local disk) was wiped, so a `canvas revive` would otherwise find no row. Identity columns are rebuilt from each meta; runtime columns (status/intent/pi_pid/window/tmux) take their quiescent defaults, and subscribes_to edges are left intact',
     help: {
         name: 'canvas rebuild-index',
         summary: 're-derive canvas.db node rows from on-disk metas; fails loud if metas exist but yield no rows',

package/dist/commands/node-snapshot.js

@@ -7,6 +7,7 @@ import { getNode } from '../core/canvas/index.js';
 import { sessionPtrPath } from '../core/canvas/paths.js';
 import { SessionManager } from '../core/runtime/broker-sdk.js';
 import { BUILTIN_SLASH_COMMANDS } from '../core/runtime/pi-vendored.js';
+import { cycleAwareMessages } from '../core/runtime/session-cycles.js';
 function resolveSessionFile(nodeId, metaFile) {
     if (typeof metaFile === 'string' && metaFile !== '' && existsSync(metaFile))
         return metaFile;
@@ -95,7 +96,14 @@ export const nodeSnapshotLeaf = defineLeaf({
             copyFileSync(sessionFile, copy);
             const manager = SessionManager.open(copy);
             const context = manager.buildSessionContext();
-            const messages = context.messages;
+            // Every prior refresh-yield cycle lives in this SAME `.jsonl` as a sibling
+            // branch (session-cycles.ts) — replay them ahead of the live cycle's
+            // context so a dormant node's snapshot reads as one continuous
+            // conversation, matching the broker's live welcome snapshot.
+            // Cast: the real SDK's `SessionEntry.data` is `unknown`, narrower than
+            // `CycleSessionManagerLike`'s structural read of the `crtr-cycle` marker's
+            // `{cycle, fromLeaf}` shape (see the matching cast in broker.ts).
+            const messages = cycleAwareMessages(manager);
             const sessionId = manager.getSessionId();
             const sessionName = manager.getSessionName();
             const snapshot = {

package/dist/commands/node.js

@@ -23,6 +23,7 @@ import { readFaultAsync } from '../core/runtime/fault.js';
 import { activeFaultForDisplay } from '../core/canvas/render.js';
 import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane, currentTmux, getPaneOption, renameWindow } from '../core/runtime/placement.js';
 import { buildLaunchSpec, normalizeModel } from '../core/runtime/launch.js';
+import { WorktreeError } from '../core/worktree.js';
 import { closeNode } from '../core/runtime/close.js';
 import { isBrokerLive, setModelLive, persistDormantModel } from '../core/runtime/model-swap.js';
 import { appendInbox } from '../core/feed/inbox.js';
@@ -36,7 +37,7 @@ import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf
 // the result instead of this bloated one. Below the steering bands (130k+) on
 // purpose — catch it at spawn, before the window is critically full.
 const YIELD_NUDGE_THRESHOLD = 100_000;
-const STD_CHILD_FOLLOW_UP = "Do not wait or poll on this child — there is no result to await and stopping will not strand you. You're auto-subscribed, so its finish wakes you on its own. Two moves only: continue other independent work right now, or stop and end your turn — the wake brings you back.";
+const STD_CHILD_FOLLOW_UP = "Do not wait, poll, or duplicate this child's assignment in your own context — there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn — the wake brings you back.";
 /** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
  *  but when the SPAWNER is an orchestrator whose context has already grown past
  *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
@@ -51,7 +52,12 @@ export function childFollowUp(spawnerId) {
     if (ctxTokens === null || ctxTokens < YIELD_NUDGE_THRESHOLD)
         return STD_CHILD_FOLLOW_UP;
     const k = Math.round(ctxTokens / 1000);
-    return `Child spawned — you're auto-subscribed, so its finish wakes you on its own; never wait or poll. But you're an orchestrator already carrying ~${k}k of context: rather than hold this window open for the result, checkpoint context/roadmap.md and \`crtr node yield\` now. Yielding ends this turn, and the child's completion then revives you fresh against your roadmap — let that clean revive absorb the result instead of this bloated context.`;
+    return `Child spawned — you're auto-subscribed, so its finish wakes you on its own; never wait, poll, or duplicate the child's assignment in your own context. But you're an orchestrator already carrying ~${k}k of context: rather than hold this window open for the result, checkpoint context/roadmap.md and \`crtr node yield\` now. Yielding ends this turn, and the child's completion then revives you fresh against your roadmap — let that clean revive absorb the result instead of this bloated context.`;
+}
+function mapWorktreeError(err) {
+    if (!(err instanceof WorktreeError))
+        return null;
+    return new InputError({ error: err.code, message: err.message, next: err.next });
 }
 /** Validate a `--kind` against the installed personas; throws a listing InputError. */
 function assertKind(kind) {
@@ -120,7 +126,8 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Dir the node is pinned to. Defaults to the caller cwd, resolved now — for a triggered spawn it must still exist at fire time or the spawn fails loud.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
             { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node (CRTR_NODE_ID).' },
-            { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with).' },
+            { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with). Mutually exclusive with --worktree.' },
+            { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on `origin/main`; the child\'s cwd is pinned there, and it lands the work serially onto origin/main later with `crtr worktree close`. Mutually exclusive with --root.' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (root has none, so an uninherited child has none either). --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
@@ -143,12 +150,12 @@ const nodeNew = defineLeaf({
             { name: 'next_eval_at', type: 'string', required: false, constraint: 'The next predicate-evaluation instant (always "now" at arm time), present only for an armed --when trigger.' },
             { name: 'timeout_at', type: 'string', required: false, constraint: 'Absolute UTC wall-clock bound, present only for an armed --when trigger.' },
             { name: 'recur', type: 'string', required: false, constraint: 'Cadence display ("every 6h", cron, or eval cadence for --when), present only when --every was given.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller. Spawned now: the child runs independently and its finish wakes you on its own, so never wait or poll on it — either pick up other work now or end your turn (an orchestrator already deep in context is instead steered to `crtr node yield`). Armed: no node exists yet — inspect/cancel via `crtr node triggers list`/`cancel <id>`, then pick up other work or end your turn.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller. Spawned now: the child runs independently and its finish wakes you on its own, so never wait, poll, or duplicate its assignment — either pick up other independent work now or end your turn (an orchestrator already deep in context is instead steered to `crtr node yield`). Armed: no node exists yet — inspect/cancel via `crtr node triggers list`/`cancel <id>`, then pick up other work or end your turn.' },
         ],
         dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
         outputKind: 'object',
         effects: [
-            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
+            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on origin/main; the child closes it later with `crtr worktree close` before finishing. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
             'Armed (--at/--every/--when): inserts one detached `new`/`node_birth` triggers row (node_id NULL, owner=you, parent/cwd resolved now); NO node and NO window exist until fire time. The daemon spawns from the stored recipe at fire time, re-deriving the launch spec live.',
         ],
     },
@@ -163,6 +170,7 @@ const nodeNew = defineLeaf({
         const name = input['name'];
         const parent = input['parent'];
         const root = input['root'] === true;
+        const worktree = input['worktree'] === true;
         const forkFrom = input['forkFrom'];
         const model = input['model'];
         const profile = input['profile'];
@@ -183,19 +191,30 @@ const nodeNew = defineLeaf({
         if (hasTz && !hasAt && !hasEvery) {
             throw new InputError({ error: 'tz_needs_clock', message: '--tz has no effect without --at or --every to parse it against', field: 'tz', next: 'Drop --tz, or pass --at/--every.' });
         }
+        if (root && worktree) {
+            throw new InputError({ error: 'worktree_root_conflict', message: '--worktree is mutually exclusive with --root', field: 'worktree', next: 'Drop either --root or --worktree.' });
+        }
         if (!triggered) {
-            const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, model, profile });
-            return {
-                node_id: res.node.node_id,
-                name: res.node.name,
-                window: res.window ?? undefined,
-                session: res.session ?? undefined,
-                status: res.node.status,
-                armed: false,
-                follow_up: root
-                    ? "Independent root spawned — it is NOT under you. You are not subscribed, so its finish will NOT wake you and it does not hold you alive; it carries spawned_by=you for lineage only. Inside tmux it opened a viewer in your current session (the client switched to it) so it can be driven directly. Hand it off and move on — you will not be notified of its progress."
-                    : childFollowUp(parent ?? process.env['CRTR_NODE_ID']),
-            };
+            try {
+                const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, worktree, forkFrom, model, profile });
+                return {
+                    node_id: res.node.node_id,
+                    name: res.node.name,
+                    window: res.window ?? undefined,
+                    session: res.session ?? undefined,
+                    status: res.node.status,
+                    armed: false,
+                    follow_up: root
+                        ? "Independent root spawned — it is NOT under you. You are not subscribed, so its finish will NOT wake you and it does not hold you alive; it carries spawned_by=you for lineage only. Inside tmux it opened a viewer in your current session (the client switched to it) so it can be driven directly. Hand it off and move on — do not duplicate its assignment; you will not be notified of its progress."
+                        : childFollowUp(parent ?? process.env['CRTR_NODE_ID']),
+                };
+            }
+            catch (err) {
+                const mapped = mapWorktreeError(err);
+                if (mapped !== null)
+                    throw mapped;
+                throw err;
+            }
         }
         if (hasWhen && hasAt) {
             throw new InputError({ error: 'bad_when_combo', message: '--when cannot combine with --at', next: 'A trigger is either clock-driven (--at/--every) or predicate-driven (--when).' });
@@ -219,6 +238,7 @@ const nodeNew = defineLeaf({
             parent: recipeParent,
             ...(name !== undefined ? { name } : {}),
             ...(root ? { root: true } : {}),
+            ...(worktree ? { worktree: true } : {}),
             ...(forkFrom !== undefined ? { forkFrom } : {}),
             ...(model !== undefined ? { model } : {}),
             ...(profile !== undefined ? { profile } : {}),

package/dist/commands/push.js

@@ -12,6 +12,7 @@ import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError, readStdinRaw } from '../core/io.js';
 import { push } from '../core/feed/feed.js';
 import { getNode, subscribersOf } from '../core/canvas/index.js';
+import { hasOpenManagedWorktree } from '../core/worktree.js';
 function requireCallerNode() {
     const id = process.env['CRTR_NODE_ID'];
     if (id === undefined || id.trim() === '') {
@@ -96,6 +97,13 @@ function makeTierLeaf(tier) {
                 if (node !== null && node.status !== 'active' && node.status !== 'idle') {
                     throw alreadyFinalizedError(node.status);
                 }
+                if (node !== null && hasOpenManagedWorktree(node)) {
+                    throw new InputError({
+                        error: 'open_managed_worktree',
+                        message: 'This node still owns an open managed worktree — `push final` is blocked until it is closed.',
+                        next: 'Commit the remaining work in the worktree, run `crtr worktree close`, then rerun `crtr push final`.',
+                    });
+                }
                 // A RESIDENT node with no subscribers is human-driven and has no one to
                 // submit a canonical result to: `push final` fans to subscribers, and a
                 // resident root conversation has none. Finishing it would shut its

package/dist/commands/revive.d.ts

@@ -1,2 +1,12 @@
 import type { LeafDef } from '../core/command.js';
+import type { Fault } from '../core/runtime/fault.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export declare function isNowEligibleFault(fault: Fault | null): boolean;
 export declare const reviveLeaf: LeafDef;

package/dist/commands/revive.js

@@ -3,8 +3,10 @@
 // Bypasses the daemon: directly relaunches the broker engine for a node that is
 // done, idle, or dead. Default behavior resumes the saved pi conversation by its
 // absolute session-file path (--session <path>) when that .jsonl still exists,
-// else falls through to a fresh launch; pass --fresh to force a clean pi session
-// against the context dir.
+// else falls through to a fresh launch. `--fresh` skips the true resume: if the
+// `.jsonl` already exists it CYCLES in place instead (same file, a fresh
+// `crtr-cycle` branch — `resumed:false`), and only starts a genuinely clean
+// session when no `.jsonl` exists yet (also `resumed:false`).
 //
 // `--all` sweeps EVERY disconnected node (engine not running, resumable session)
 // in one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
@@ -19,6 +21,22 @@ import { getNode, fullName } from '../core/canvas/index.js';
 import { isPidAlive } from '../core/canvas/pid.js';
 import { readFault } from '../core/runtime/fault.js';
 import { isBusy } from '../core/runtime/busy.js';
+import { faultNeedsYou } from '../core/canvas/status-glyph.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export function isNowEligibleFault(fault) {
+    if (fault === null || fault.link !== 'pi→provider')
+        return false;
+    if (faultNeedsYou(fault))
+        return true;
+    return fault.retry.by === 'daemon';
+}
 // ---------------------------------------------------------------------------
 // revive node
 // ---------------------------------------------------------------------------
@@ -50,7 +68,7 @@ export const reviveLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'When set, start a clean pi session (no --session). Default: resume the saved conversation. Ignored with --all (which always resumes).',
+                constraint: 'When set, do NOT do a true resume. If the node already has a session `.jsonl`, this instead CYCLES it in place — reuses that SAME file, resets the tree leaf, and roots a fresh `crtr-cycle` branch (a clean-context restart that still carries the file\'s history, output `resumed:false`). Only when no `.jsonl` exists yet does this start a genuinely brand-new session (also `resumed:false`). Default (no --fresh): a true resume — replays the existing `.jsonl` as-is (`resumed:true`). Ignored with --all (which always resumes).',
             },
             {
                 kind: 'flag',
@@ -58,7 +76,7 @@ export const reviveLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'On-demand kick of an active-fault node (parked on a provider-owned fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s instead of waiting out the auto-recovery grace. Only valid for a node that has a live daemon-owned auto provider fault and a live pid. Mutually exclusive with --all/--fresh.',
+                constraint: 'On-demand kick of an active-fault node (parked on a `pi→provider` fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s. Valid for a live `pi→provider` fault that is either a daemon-owned auto retry (kicks it early), or ANY fault the canvas dashboard flags "needs you" (e.g. exhausted retries, an auth fault you just fixed) — that disposition otherwise has no recovery verb. Mutually exclusive with --all/--fresh.',
             },
             // --force is a DELIBERATELY UNDOCUMENTED confirmation gate for --all (hidden
             // from -h; see FlagParam.hidden). Silas's intent (2026-06-13): a mass revive
@@ -80,7 +98,7 @@ export const reviveLeaf = defineLeaf({
         output: [
             { name: 'window', type: 'string', required: false, constraint: 'Always null — the revived broker is headless and opens no tmux window. Kept for caller back-compat.' },
             { name: 'session', type: 'string', required: false, constraint: 'The node\'s last live location session, or null — the headless broker has no tmux session of its own.' },
-            { name: 'resumed', type: 'boolean', required: false, constraint: 'True when pi was told to --session the saved conversation. Single-node revive only.' },
+            { name: 'resumed', type: 'boolean', required: false, constraint: 'True ONLY for a true resume (the existing `.jsonl` replayed as-is). False for a --fresh revive, whether that landed as an in-place CYCLE (an existing `.jsonl` reused with a fresh `crtr-cycle` branch — pi is still told --session, but this is not a resume) or a genuinely fresh launch (no `.jsonl` existed). Single-node revive only.' },
             { name: 'ready', type: 'boolean', required: false, constraint: 'True when the revived broker\'s view.sock accepted a connection before return — the node is immediately attachable/drivable. Single-node revive only.' },
             { name: 'mode', type: 'string', required: false, constraint: '"preview" (the --all candidate list, nothing launched), "revived" (the --all sweep ran), or absent for a single-node revive.' },
             { name: 'candidates', type: 'string', required: false, constraint: '--all preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
@@ -145,8 +163,8 @@ export const reviveLeaf = defineLeaf({
         // reviveNode would no-op the double-launch guard) — SIGTERM it so the daemon's
         // ordinary crash→grace→resume path recovers it on the saved session, the same
         // thing the daemon does at the auto-recovery grace, just on demand. Gated on
-        // a live pid and a daemon-owned provider fault so it can't be used to nuke a
-        // healthy node.
+        // a live pid and an eligible pi→provider fault (`isNowEligibleFault` above) so
+        // it can't be used to nuke a healthy node.
         if (now) {
             const pid = meta.pi_pid;
             const stall = readFault(nodeId);
@@ -157,11 +175,11 @@ export const reviveLeaf = defineLeaf({
                     next: 'Revive a dormant node with `crtr canvas revive ' + nodeId + '` (no --now).',
                 });
             }
-            if (stall === null || stall.link !== 'pi→provider' || stall.retry.by !== 'daemon' || stall.retry.disposition !== 'auto') {
+            if (!isNowEligibleFault(stall)) {
                 throw new InputError({
                     error: 'not_hanging',
-                    message: `${nodeId} is live but not an active daemon-owned provider fault — --now refuses to SIGTERM a healthy node.`,
-                    next: 'Use --now only on a node the canvas shows as hanging (⚠). For a routine relaunch, omit --now.',
+                    message: `${nodeId} is live but has no pi→provider fault eligible for --now (either healthy, or a client-owned retry / non-provider fault already being handled elsewhere) — --now refuses to SIGTERM a node that isn't stuck on a kickable provider fault.`,
+                    next: 'Use --now only on a node the canvas shows as hanging (⚠) with a `pi→provider` fault. For a routine relaunch, omit --now.',
                 });
             }
             // The daemon never kills a BUSY engine (its verdict paths all return 'leave'

package/dist/commands/sys/__tests__/setup-core.test.js

@@ -0,0 +1,19 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { resolveBundledPiCliPath } from '../../../core/runtime/pi-cli.js';
+test('resolveBundledPiCliPath uses crouter bundled pi instead of a standalone pi on PATH', () => {
+    const prevPath = process.env.PATH;
+    process.env.PATH = '';
+    try {
+        const cliPath = resolveBundledPiCliPath();
+        assert.equal(existsSync(cliPath), true);
+        assert.match(cliPath, /@earendil-works[\/]pi-coding-agent[\/]dist[\/]cli\.js$/);
+    }
+    finally {
+        if (prevPath === undefined)
+            delete process.env.PATH;
+        else
+            process.env.PATH = prevPath;
+    }
+});

package/dist/commands/sys/doctor.js

@@ -71,7 +71,7 @@ function faultRemediation(fault) {
         auth: 're-authenticate',
         protocol: 'fix the protocol mismatch',
         other: 'fix the underlying issue',
-        wedged: 'read `crtr memory read wedged-child-on-runaway-bash` and, if a runaway subprocess is to blame, kill the subprocess (not the node)',
+        wedged: 'read `crtr memory read wedged-child-on-runaway-bash` — if a runaway subprocess is to blame, kill it (not the node); if the broker had no subprocess, the daemon already SIGTERM-kicked it to resume on its own (recheck node status; nudge it if it came back idle)',
     };
     const progress = fault.retry.disposition === 'auto'
         ? fault.retry.by === 'client'

package/dist/commands/sys/setup-core.js

@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { builtinPiPackageDir } from '../../core/scope.js';
 import { readJsonIfExists } from '../../core/fs-utils.js';
+import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
 const PACKAGE_COPY = {
     'crtr-extensions': {
         name: 'pi-crtr-extensions',
@@ -285,8 +286,8 @@ function runShellCommand(command) {
         throw new Error(`command failed: ${command}`);
     }
 }
-function installPiPackage(source) {
-    const result = spawnSync('pi', ['install', source], { stdio: 'inherit' });
+function installPiPackage(source, piCliPath = resolveBundledPiCliPath()) {
+    const result = spawnSync(process.execPath, [piCliPath, 'install', source], { stdio: 'inherit' });
     if (result.status !== 0) {
         throw new Error(`pi install failed: ${source}`);
     }

package/dist/commands/sys/setup.js

@@ -506,7 +506,7 @@ export const sysSetupLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Opens a pi-tui wizard that collects companion package installs, system dependency installs, and an Exa API key.',
-            'Runs pi installs for the selected bundled packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
+            'Runs the bundled pi CLI to install the selected companion packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
         ],
     },
     run: async () => {

package/dist/commands/worktree.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../core/command.js';
+export declare function registerWorktree(): BranchDef;