@crouton-kit/crouter 0.3.40 → 0.3.42

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/attach/view-socket.d.ts

@@ -16,7 +16,8 @@ export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame
  *  broker on the same path. It gives up only when the node is genuinely gone:
  *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
  *  terminal — an idle-release node revives on its next inbox wake, so keep
- *  trying (the supervisor's own ~30s bound caps an indefinite wait). */
+ *  trying (the supervisor waits at a relaxed cadence for as long as the row
+ *  stays live). */
 export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
 export declare class BrokerUnavailableError extends Error {
     readonly nodeId: string;
@@ -45,6 +46,12 @@ export declare class ViewSocketClient extends EventEmitter {
      *  Resolved by the matching `data` frame / rejected by the matching `error`
      *  frame in {@link onData}, the request's timeout, or socket teardown. */
     private pending;
+    /** One redial fault line per reconnect EPISODE, not per attempt: the
+     *  supervisor redials for as long as the node can come back (a dormant node
+     *  may be gone for hours), so a per-attempt record would grow fault.log
+     *  without bound. Set on the first failed redial, reset on any successful
+     *  connect. */
+    private redialFaultRecorded;
     constructor(nodeId: string);
     private recordSocketFault;
     /** Issue a correlated read-op and resolve with the broker's `data` reply (or

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

@@ -38,7 +38,8 @@ const REQUEST_TIMEOUT_MS = 10_000;
  *  broker on the same path. It gives up only when the node is genuinely gone:
  *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
  *  terminal — an idle-release node revives on its next inbox wake, so keep
- *  trying (the supervisor's own ~30s bound caps an indefinite wait). */
+ *  trying (the supervisor waits at a relaxed cadence for as long as the row
+ *  stays live). */
 export function reconnectShouldGiveUp(row) {
     if (row === null)
         return true;
@@ -61,11 +62,22 @@ export class ViewSocketClient extends EventEmitter {
      *  Resolved by the matching `data` frame / rejected by the matching `error`
      *  frame in {@link onData}, the request's timeout, or socket teardown. */
     pending = new Map();
+    /** One redial fault line per reconnect EPISODE, not per attempt: the
+     *  supervisor redials for as long as the node can come back (a dormant node
+     *  may be gone for hours), so a per-attempt record would grow fault.log
+     *  without bound. Set on the first failed redial, reset on any successful
+     *  connect. */
+    redialFaultRecorded = false;
     constructor(nodeId) {
         super();
         this.nodeId = nodeId;
     }
     recordSocketFault(op, err) {
+        if (op === 'redial') {
+            if (this.redialFaultRecorded)
+                return;
+            this.redialFaultRecorded = true;
+        }
         const classified = classify('viewer↔broker', err);
         recordFault(this.nodeId, {
             link: 'viewer↔broker',
@@ -122,6 +134,7 @@ export class ViewSocketClient extends EventEmitter {
         const socket = createConnection(this.socketPath);
         this.socket = socket;
         socket.on('connect', () => {
+            this.redialFaultRecorded = false;
             clearFault(this.nodeId, { link: 'viewer↔broker' });
             this.emit('connect');
         });
@@ -148,6 +161,7 @@ export class ViewSocketClient extends EventEmitter {
                 if (settled)
                     return;
                 settled = true;
+                this.redialFaultRecorded = false;
                 clearFault(this.nodeId, { link: 'viewer↔broker' });
                 this.emit('connect');
                 resolve();

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/memory/shared.d.ts

@@ -12,9 +12,13 @@ export declare function scopeRank(scope: MemoryScope): number;
  *  always resolves. `--scope profile` is NEVER a default — it requires a
  *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
  *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
- *  `loadProfileManifest` (never a raw path join). Returns the absolute
- *  `<root>/memory` dir to write under. */
-export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string): {
+ *  `loadProfileManifest` (never a raw path join). `dirArg` (an explicit
+ *  `--dir <path>`) pins the EXACT project directory, cwd-free: the target is
+ *  `<dir>/.crouter/memory/`, scaffolded if absent, never the cwd-ancestor walk
+ *  — the way a profiled agent writes into any project in its purview, and the
+ *  only way to target a dir shadowed by an ancestor store. Returns the
+ *  absolute `<root>/memory` dir to write under. */
+export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string, dirArg?: string): {
     scope: MemoryScope;
     memoryDir: string;
 };

package/dist/commands/memory/shared.js

@@ -3,10 +3,12 @@
 // scope modules and build their documented output objects on top of the small
 // helpers here. Nothing in this file forks on kind or re-implements the
 // schema/gate/resolver — it only composes them.
-import { join } from 'node:path';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
-import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.js';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
 import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
@@ -29,9 +31,37 @@ export function scopeRank(scope) {
  *  always resolves. `--scope profile` is NEVER a default — it requires a
  *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
  *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
- *  `loadProfileManifest` (never a raw path join). Returns the absolute
- *  `<root>/memory` dir to write under. */
-export function resolveWriteTarget(scopeArg, profileArg) {
+ *  `loadProfileManifest` (never a raw path join). `dirArg` (an explicit
+ *  `--dir <path>`) pins the EXACT project directory, cwd-free: the target is
+ *  `<dir>/.crouter/memory/`, scaffolded if absent, never the cwd-ancestor walk
+ *  — the way a profiled agent writes into any project in its purview, and the
+ *  only way to target a dir shadowed by an ancestor store. Returns the
+ *  absolute `<root>/memory` dir to write under. */
+export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
+    if (dirArg !== undefined && dirArg !== '') {
+        if (scopeArg !== undefined && scopeArg !== 'project') {
+            throw usage(`--dir targets a project store and cannot combine with --scope ${scopeArg}`);
+        }
+        const abs = resolvePath(dirArg);
+        if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+            throw usage(`--dir does not exist or is not a directory: ${dirArg}`, {
+                received: dirArg,
+                next: 'Pass an existing project directory.',
+            });
+        }
+        let real = abs;
+        try {
+            real = realpathSync(abs);
+        }
+        catch {
+            /* fall back to the resolved path */
+        }
+        // The scaffold (mkdir of `.crouter/memory/`) happens at write time via the
+        // writer's ensureDir; drop the scope cache so this process's later
+        // resolves see the new root.
+        resetScopeCache();
+        return { scope: 'project', memoryDir: join(real, CRTR_DIR_NAME, 'memory') };
+    }
     let scope;
     if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile') {
         scope = scopeArg;

package/dist/commands/memory/write.js

@@ -13,7 +13,7 @@ export const writeLeaf = defineLeaf({
         guide: 'The body is the easy part; the craft is routing — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung down.\n\n' +
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
             'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
-            'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
+            'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ (`--dir <project-dir>` targets it exactly, from anywhere) and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can decide from that one line alone whether to spend the read. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
             'Find before write. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Validate after authoring.',
@@ -27,7 +27,8 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
             { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
             { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile.' },
+            { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Exact project directory to write under — targets `<dir>/.crouter/memory/` regardless of cwd or ancestor stores, scaffolding `.crouter/` there if absent. THE way to place a doc in a specific project’s store (e.g. another project in your profile’s purview) without cd’ing there, and the only way to target a dir shadowed by an ancestor store. Implies --scope project; rejects --scope user/profile.' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`; ignored for any other --scope.' },
             { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin, or passed as the bare positional after <name>.' },
         ],
@@ -50,7 +51,8 @@ export const writeLeaf = defineLeaf({
         const scopeArg = input['scope'];
         const profileArg = input['profile'];
         const body = input['body'] ?? '';
-        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg);
+        const dirArg = input['dir'];
+        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg, dirArg);
         const path = memoryFilePath(memoryDir, name);
         const created = !pathExists(path);
         // CREATE requires the read-routing line that becomes the preview — without

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;