@north-light/crouter 0.3.175 → 0.3.177

package/dist/clients/inbox/controller.js

@@ -7,7 +7,8 @@ import { scanInbox } from '../../core/human/scan.js';
 import { watchInboxActivity } from '../../core/human/root.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from '../../core/human/claim.js';
 import { readTicketResult } from '../../core/human/tickets.js';
-import { clearProgress, deckPath, readJson } from '../../core/human/convention.js';
+import { clearProgress, deckPath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { DeckAdapter } from './deck-adapter.js';
 import { validateDeck } from '../../core/human/deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
@@ -258,7 +259,7 @@ export class InboxController {
         this.markDirty();
     }
     readDeck(dir) {
-        const deck = readJson(deckPath(dir));
+        const deck = readJsonOrNull(deckPath(dir));
         if (deck === null)
             return undefined;
         try {

package/dist/clients/inbox/deck-adapter.js

@@ -1,4 +1,5 @@
-import { progressPath, readJson } from '../../core/human/convention.js';
+import { progressPath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { mountPanel } from './tui/panel.js';
 /** Embeds the single deck renderer in a controller-owned rectangle. */
 export class DeckAdapter {
@@ -50,7 +51,7 @@ function notificationsAcknowledged(deck, responses) {
     });
 }
 function initialResponses(deck, dir) {
-    const saved = readJson(progressPath(dir))?.responses;
+    const saved = readJsonOrNull(progressPath(dir))?.responses;
     if (Array.isArray(saved))
         return saved;
     return deck.interactions.flatMap((interaction) => {

package/dist/clients/surfaces/host.d.ts

@@ -12,7 +12,7 @@ export interface SurfaceComponent extends Component {
     /** Consume wheel input when applicable. */
     handleWheel?(direction: 'up' | 'down', lines: number): boolean;
 }
-/** The identities used for mounted Phase 3 surfaces. */
+/** The identities used for mounted surfaces. */
 export type SurfaceId = 'inbox' | 'review';
 /** How long a notice stays up. */
 export interface SurfaceNoticeOptions {

package/dist/commands/api-client.d.ts

@@ -20,14 +20,14 @@ export declare function rethrowAsCliError(err: unknown, next?: string): never;
  *  404-only→null mapping as `ApiCanvasSource.orNull`, but returning the raw DTO
  *  and rethrowing non-404s as CLI errors rather than swallowing them. */
 export declare function getNodeOrNull(nodeId: string): Promise<NodeDetailDTO | null>;
-/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout
- *  (issue #516). Large enough to catch a real startup failure/stack trace,
+/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
+ *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI
  *  error message. */
 export declare const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4096;
 /** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
- *  cold-start timeout (issue #516: the prior bare message discarded the actual
- *  startup failure). Bounds the I/O itself — opens the file and reads only the
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
  *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
  *  never `readFileSync`-ing the whole append-only log — then decodes/filters
  *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
@@ -42,15 +42,14 @@ export declare function readColdStartDiagnostic(): string | undefined;
  *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
  *  §8). This is the ONLY CLI reference to `ensureDaemon`.
  *
- *  #508 follow-up: `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns
- *  crtrd and returns immediately, so the client's OWN `/healthz` poll is the
- *  only deadline the initiating CLI invocation actually waits on. That poll
- *  used to default to a fixed 10s window while `spawnDaemon`'s
- *  `verifyDaemonStartup` (which `ensureDaemon`'s spawn transitively awaits, in
- *  the detached child, on the SAME cold-start path) was widened to 20s for a
- *  slow-but-valid cold boot: a daemon that took 12s was a valid, verified
- *  startup, but the CLI process that triggered it still gave up and reported
- *  `daemon_unavailable` at 10s. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows (which
+ *  `ensureDaemon`'s spawn transitively awaits, in the detached child, on the
+ *  SAME cold-start path): a daemon that takes 12s is a valid, verified startup,
+ *  and a 10s client poll would still give up and report `daemon_unavailable`
+ *  against it. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
  *  here keeps the two in lockstep — one authoritative window, not two that can
  *  drift apart — without adding any retry/fallback poll loop. */
 export declare function cliClient(opts?: {

package/dist/commands/api-client.js

@@ -65,15 +65,15 @@ export async function getNodeOrNull(nodeId) {
 function autostartDisabled() {
     return process.env['CRTR_NO_DAEMON_AUTOSTART'] === '1' || process.argv.includes('--no-autostart');
 }
-/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout
- *  (issue #516). Large enough to catch a real startup failure/stack trace,
+/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
+ *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI
  *  error message. */
 export const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4_096;
 const COLD_START_DIAGNOSTIC_TAIL_LINES = 20;
 /** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
- *  cold-start timeout (issue #516: the prior bare message discarded the actual
- *  startup failure). Bounds the I/O itself — opens the file and reads only the
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
  *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
  *  never `readFileSync`-ing the whole append-only log — then decodes/filters
  *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
@@ -116,15 +116,14 @@ export function readColdStartDiagnostic() {
  *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
  *  §8). This is the ONLY CLI reference to `ensureDaemon`.
  *
- *  #508 follow-up: `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns
- *  crtrd and returns immediately, so the client's OWN `/healthz` poll is the
- *  only deadline the initiating CLI invocation actually waits on. That poll
- *  used to default to a fixed 10s window while `spawnDaemon`'s
- *  `verifyDaemonStartup` (which `ensureDaemon`'s spawn transitively awaits, in
- *  the detached child, on the SAME cold-start path) was widened to 20s for a
- *  slow-but-valid cold boot: a daemon that took 12s was a valid, verified
- *  startup, but the CLI process that triggered it still gave up and reported
- *  `daemon_unavailable` at 10s. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows (which
+ *  `ensureDaemon`'s spawn transitively awaits, in the detached child, on the
+ *  SAME cold-start path): a daemon that takes 12s is a valid, verified startup,
+ *  and a 10s client poll would still give up and report `daemon_unavailable`
+ *  against it. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
  *  here keeps the two in lockstep — one authoritative window, not two that can
  *  drift apart — without adding any retry/fallback poll loop. */
 export function cliClient(opts) {
@@ -140,7 +139,7 @@ export function cliClient(opts) {
             ensureDaemon();
         },
         // On a cold-start timeout, enrich the bare `daemon_unavailable` with the
-        // tail of crtrd's own stderr log (issue #516) instead of discarding it.
+        // tail of crtrd's own stderr log instead of discarding it.
         coldStartDiagnostic: readColdStartDiagnostic,
         coldStartPollWindowMs: DAEMON_VERIFY_WINDOW_MS,
     });
@@ -153,8 +152,8 @@ export function cliClient(opts) {
 // performs no lossy legacy reconstruction or invented local-presence values.
 // The attach viewer's recurring subtree walk (chrome/canvas-panels.ts + overlays/graph.ts
 // computeActivity/visitActivity) calls subscriptionsOf/subscribersOf once per
-// visited node on every poll tick; each call was previously its own
-// `GET /v1/nodes/:id` round trip just to read the edge list off the detail DTO.
+// visited node on every poll tick, and a `GET /v1/nodes/:id` per call just to
+// read the edge list off the detail DTO costs one round trip per visited node.
 // This short-TTL cache backs those two methods with the lean roster
 // (`GET /v1/canvas/roster`) instead — one shared fetch per TTL window covers
 // every topology walk in that window, comfortably under the attach viewer's 5s

package/dist/commands/chord.js

@@ -19,8 +19,7 @@ const pexec = promisify(execFile);
  *  here rather than importing node.ts's `nodeInPane` (which reaches openDb via the
  *  canvas accessors) so this dispatcher's import graph stays db-free. Under the
  *  headless-broker model every engine runs DETACHED (window=null), so the pane tag
- *  is the ONLY node handle — the window→node fallback in node.ts's variant only ever
- *  matched legacy in-pane engines, which no longer exist. A stale tag is ignored
+ *  is the ONLY node handle. A stale tag is ignored
  *  (the tagged node must still be live), validated through the daemon API. */
 async function nodeInPane(pane) {
     if (pane === undefined || pane === '')

package/dist/commands/human/queue.js

@@ -5,7 +5,8 @@ import { defineLeaf } from '../../core/command.js';
 import { ticketDir } from '../../core/human/root.js';
 import { scanInbox } from '../../core/human/scan.js';
 import { parseDeck } from '../../core/human/deck-schema.js';
-import { deckPath, isResolved, readJson, reviewPath } from '../../core/human/convention.js';
+import { deckPath, isResolved, reviewPath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { InputError } from '../../core/io.js';
 import { paginate } from '../../core/pagination.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
@@ -14,9 +15,9 @@ function toRef(n) {
     return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent, status: n.status };
 }
 /** The canvas roster, fetched ONCE per leaf run through the API and threaded
- *  into the sync provenance helpers below (they used to call `listNodes()`/
- *  `getNode()` synchronously; the API surface is async, so the fetch is hoisted
- *  to the leaf and the helpers read the pre-fetched array/map). */
+ *  into the sync provenance helpers below (the API surface is async, so the
+ *  fetch is hoisted to the leaf and the helpers read the pre-fetched
+ *  array/map). */
 async function fetchNodeRefs() {
     return (await cliClient().listNodes()).map(toRef);
 }
@@ -67,7 +68,7 @@ function summarizeTicket(summary, nodes, byId) {
         return null;
     const asking = askingNodeFor(jobId, byId);
     const conversation = resolveConversation(asking, nodes);
-    const interactionCount = summary.kind === 'deck' ? readJson(deckPath(summary.dir))?.interactions.length : undefined;
+    const interactionCount = summary.kind === 'deck' ? readJsonOrNull(deckPath(summary.dir))?.interactions.length : undefined;
     const sourceLabel = readableSourceLabel(summary.source);
     return {
         id: summary.id,

package/dist/commands/memory/find.js

@@ -155,9 +155,9 @@ export const findLeaf = defineLeaf({
         // Sort comparator MUST match keyOf exactly (score desc, then scope asc,
         // then name asc as the final deterministic identity component — the
         // candidate dedup keys on scope+name, so this pair is always unique).
-        // Equal-score hits from different scopes previously sorted by name alone
-        // while the cursor key ordered by scope first, so the array could disagree
-        // with its own keys and paginate() would silently skip a later item.
+        // Sorting equal-score hits from different scopes by name alone while the
+        // cursor key orders by scope first would let the array disagree with its
+        // own keys, and paginate() would silently skip a later item.
         hits.sort((a, b) => {
             if (b.score !== a.score)
                 return b.score - a.score;

package/dist/commands/node/create.js

@@ -71,7 +71,7 @@ function nodeNewParams() {
         { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message. Required unless --no-kickoff is given.' },
         { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind. The <kinds> list below names every top-level installable kind.' },
         { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for hands-on work; orchestrator when the unit itself needs decomposition across children.' },
-        { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the node is pinned to. Defaults to the caller cwd.' },
+        { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the profile home for a root (`crtr profile show <profile>`).' },
         { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name. Defaults to the kind.' },
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
         { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
@@ -106,7 +106,7 @@ async function runNodeCreation(input) {
     }
     const kind = input['kind'] ?? 'general';
     const mode = (input['mode'] ?? 'base');
-    const cwd = input['cwd'] ?? process.cwd();
+    const pinCwd = input['cwd']?.trim();
     const name = input['name'];
     const parent = input['parent'];
     const root = input['root'] === true;
@@ -140,7 +140,11 @@ async function runNodeCreation(input) {
     const detail = await cliClient().createNode({
         kind,
         mode,
-        cwd,
+        // The caller's directory is the profile-SELECTION context; where the node
+        // actually lands is resolved server-side (pin > spawner's cwd > profile
+        // home). Only `--cwd` pins.
+        cwd: process.cwd(),
+        ...(pinCwd !== undefined && pinCwd !== '' ? { pin_cwd: pinCwd } : {}),
         ...(name !== undefined ? { name } : {}),
         prompt,
         ...(root ? { root: true } : { parent: parentId ?? null }),

package/dist/commands/node/lifecycle.js

@@ -375,7 +375,7 @@ export const nodeYield = defineLeaf({
             { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'Also become an orchestrator as you refresh. Pass only when (1) the remaining work contains independent units that can run in parallel and (2) the task is large enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after coordination and synthesis. Task length, context exhaustion, sequential phases, or one helper are not enough; keep hands-on work in base mode and yield again as needed. Promote when coordinating and integrating children becomes your primary job. Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh. The <kinds> list below names every top-level available kind and when to choose it; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here. Defaults to your current kind. With --promote it sets the orchestrator kind you become; without --promote it changes the kind while preserving your current mode.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
-            // Deliberate fail-first contract (#395): builtin orchestration guidance shows bare
+            // Deliberate fail-first contract: builtin orchestration guidance shows bare
             // `crtr node yield`; that invocation fails fast and surfaces yield's full help just in
             // time, at the point of use. Keep the note required rather than pre-documenting stdin
             // in kernel guidance.

package/dist/commands/node-lifecycle-revive.d.ts

@@ -3,7 +3,7 @@ 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).
+ *  disposition that otherwise has NO sanctioned recovery verb.
  *  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

package/dist/commands/node-lifecycle-revive.js

@@ -40,7 +40,7 @@ import { waitForViewSocketReady } from '../core/runtime/view-socket.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).
+ *  disposition that otherwise has NO sanctioned recovery verb.
  *  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
@@ -143,7 +143,7 @@ export const nodeReviveLeaf = defineLeaf({
         // above) so it can't be used to nuke a healthy node. This whole path stays
         // LOCAL: the kick is a direct SIGTERM to the broker pid (there is no revive
         // API call), and the node detail comes from the daemon read (`getNode`). The
-        // reopen gate (#339) is NOT invoked here — --now targets a LIVE broker, and a
+        // reopen gate is NOT invoked here — --now targets a LIVE broker, and a
         // finalized node has none (its own live-pid check below refuses it anyway).
         if (now) {
             // The detail DTO projects `pi_pid_identity` (the launch-time process-identity
@@ -201,7 +201,7 @@ export const nodeReviveLeaf = defineLeaf({
             };
         }
         // Ordinary revive: the daemon relaunches the broker (the ONLY sanctioned
-        // launcher). Node-existence validation (`not_found`) and the #339 reopen gate
+        // launcher). Node-existence validation (`not_found`) and the reopen gate
         // are both enforced server-side in `handleRevive`; a thrown gate/not-found
         // error round-trips through `ApiError.details` and is reconstructed into the
         // identical `InputError` by the shared `apiErrorToCliError` (via

package/dist/commands/profile/list.js

@@ -4,7 +4,7 @@ import { listProfiles } from '../../core/profiles/manifest.js';
 export const listLeaf = defineLeaf({
     name: 'list',
     description: 'inventory every profile',
-    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, and last-used time. Reach for `profile show` once you have picked one, for its full project list.',
+    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, home directory, and last-used time. Reach for `profile show` once you have picked one, for its full project list.',
     help: {
         name: 'profile list',
         summary: 'every profile as JSONL, one line each, sorted by name then profile_id',
@@ -12,6 +12,7 @@ export const listLeaf = defineLeaf({
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
             { name: 'projects_count', type: 'int', required: true, constraint: 'Number of project directories on the manifest.' },
+            { name: 'home', type: 'string | null', required: true, constraint: 'Directory the profile\u2019s nodes are pinned to, or null when it owns no projects.' },
             { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
         ],
         outputKind: 'jsonl',
@@ -27,6 +28,7 @@ export const listLeaf = defineLeaf({
                 profile_id: profileId,
                 name: manifest.name,
                 projects_count: manifest.projects.length,
+                home: manifest.home,
                 last_used_at: manifest.last_used_at,
             });
         }

package/dist/commands/profile/new.js

@@ -28,7 +28,7 @@ export const newLeaf = defineLeaf({
                 name: 'project',
                 type: 'path',
                 required: false,
-                constraint: 'One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Singular — add more with `crtr profile project add` after creation.',
+                constraint: "One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Also becomes the profile's home — where its nodes are pinned. Singular — add more with `crtr profile project add` after creation.",
             },
         ],
         output: [
@@ -36,6 +36,7 @@ export const newLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'The manifest name as given.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'Resolved absolute project directories, in manifest order. Empty when --project was omitted.' },
+            { name: 'home', type: 'string | null', required: true, constraint: 'Directory the profile\u2019s nodes are pinned to — the initial project, or null when none was given.' },
             { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
@@ -56,6 +57,7 @@ export const newLeaf = defineLeaf({
                 name: manifest.name,
                 path: profileRoot(profileId),
                 projects: manifest.projects,
+                home: manifest.home,
                 created_at: manifest.created_at,
                 follow_up: `Root profile ensured. Spawn nodes under it with \`--profile ${profileId}\`, or widen its purview with \`crtr profile project add ${profileId} --dir <path>\`.`,
             };
@@ -68,6 +70,7 @@ export const newLeaf = defineLeaf({
             name: manifest.name,
             path: profileRoot(profileId),
             projects: manifest.projects,
+            home: manifest.home,
             created_at: manifest.created_at,
             follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile project add ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
         };

package/dist/commands/profile/project.js

@@ -1,13 +1,14 @@
 // `crtr profile project` — the project-purview sub-noun of `profile`. A
-// profile's `projects` list is what it can SEE (memory + config resolution).
-// These two verbs widen or narrow that list after creation; `crtr profile
-// show` reads it back.
+// profile's `projects` list is what it can SEE (memory + config resolution),
+// and its `home` — one of those dirs — is where its nodes actually run. These
+// two verbs widen or narrow that list after creation and re-point the home;
+// `crtr profile show` reads both back.
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { addProfileProject, removeProfileProject, loadProfileManifest } from '../../core/profiles/manifest.js';
 const addLeaf = defineLeaf({
     name: 'add',
     description: "add a project directory to a profile's purview",
-    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile.",
+    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile. Also the way to re-point the profile's home, with --home.",
     help: {
         name: 'profile project add',
         summary: "append a project directory to a profile's manifest, deduped by real path",
@@ -25,21 +26,32 @@ const addLeaf = defineLeaf({
                 required: true,
                 constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest is a no-op, not an error.',
             },
+            {
+                kind: 'flag',
+                name: 'home',
+                type: 'bool',
+                required: false,
+                constraint: "Also make this directory the profile's home — where every node under it is pinned unless the create passes an explicit --cwd. Defaults to the first project dir; pass this on an already-listed dir to re-point it.",
+            },
         ],
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'The updated, deduped project list in manifest order.' },
+            { name: 'home', type: 'string | null', required: true, constraint: "The profile's home directory after the change." },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',
-        effects: ["Appends to the profile manifest's `projects` array. Invalidates the process scope cache."],
+        effects: ["Appends to the profile manifest's `projects` array, and rewrites `home` when --home is given. Invalidates the process scope cache."],
     },
     run: async (input) => {
         const { profileId } = loadProfileManifest(input['profile']);
-        const { manifest } = addProfileProject(profileId, input['dir']);
+        const { manifest } = addProfileProject(profileId, input['dir'], {
+            home: input['home'] === true,
+        });
         return {
             profile_id: profileId,
             projects: manifest.projects,
+            home: manifest.home,
             follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
         };
     },
@@ -63,16 +75,17 @@ const removeLeaf = defineLeaf({
                 name: 'dir',
                 type: 'path',
                 required: true,
-                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk.',
+                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk. Removing the home dir re-points the home at the first remaining project.',
             },
         ],
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'The updated project list in manifest order.' },
+            { name: 'home', type: 'string | null', required: true, constraint: "The profile's home directory after the change." },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',
-        effects: ["Removes an entry from the profile manifest's `projects` array. Invalidates the process scope cache."],
+        effects: ["Removes an entry from the profile manifest's `projects` array, re-pointing `home` when that entry was it. Invalidates the process scope cache."],
     },
     run: async (input) => {
         const { profileId } = loadProfileManifest(input['profile']);
@@ -80,6 +93,7 @@ const removeLeaf = defineLeaf({
         return {
             profile_id: profileId,
             projects: manifest.projects,
+            home: manifest.home,
             follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
         };
     },
@@ -91,7 +105,7 @@ export const projectBranch = defineBranch({
     help: {
         name: 'profile project',
         summary: "manage a profile's project purview — the directories it resolves memory and config from",
-        model: "A profile's `projects` list is the set of directories it inherits memory and config from. `add` widens that purview by one directory (deduped by real path); `remove` narrows it. Read the current list with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
+        model: "A profile's `projects` list is the set of directories it inherits memory and config from, and its `home` — the first project unless `add --home` says otherwise — is the directory its nodes are pinned to. `add` widens that purview by one directory (deduped by real path) and optionally re-points the home; `remove` narrows it, re-pointing the home when it removed it. Read both back with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
     },
     children: [addLeaf, removeLeaf],
 });

package/dist/commands/profile/show.js

@@ -6,7 +6,7 @@ import { CONFIG_FILE } from '../../types.js';
 export const showLeaf = defineLeaf({
     name: 'show',
     description: "one profile's manifest in full",
-    whenToUse: "you need a profile's full project list, id, and timestamps — after `profile list` narrows to a name, or to inspect what a node's bearings named as its profile.",
+    whenToUse: "you need a profile's full project list, home directory, id, and timestamps — after `profile list` narrows to a name, to find where its nodes will run, or to inspect what a node's bearings named as its profile.",
     help: {
         name: 'profile show',
         summary: "print one profile's manifest plus its on-disk path and config.json location",
@@ -22,6 +22,7 @@ export const showLeaf = defineLeaf({
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'Absolute project directories, in manifest order.' },
+            { name: 'home', type: 'string | null', required: true, constraint: 'The directory every node under this profile is pinned to unless its create passes an explicit --cwd. Defaults to the first project; re-point it with `profile project add --home`. Null when the profile owns no projects (the root profile), in which case nodes fall back to the creating directory.' },
             { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
             { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
@@ -39,6 +40,7 @@ export const showLeaf = defineLeaf({
             profile_id: profileId,
             name: manifest.name,
             projects: manifest.projects,
+            home: manifest.home,
             created_at: manifest.created_at,
             last_used_at: manifest.last_used_at,
             path: profileRoot(profileId),

package/dist/commands/profile.js

@@ -23,14 +23,14 @@ export function registerProfile() {
     return defineBranch({
         name: 'profile',
         rootEntry: {
-            concept: 'an agent identity defined at the user root — a manifest naming project directories plus its own memory store',
+            concept: 'an agent identity defined at the user root — a manifest naming project directories and the home its nodes run in, plus its own memory store',
             desc: 'create, inspect, and manage profiles',
             useWhen: 'creating a new agent identity, inspecting or listing existing ones, changing a profile\u2019s project purview, pinning which profile a directory defaults to at startup, or managing a profile\u2019s stored env vars. Selecting a profile for a one-off run (`--profile`) lives elsewhere.',
         },
         help: {
             name: 'profile',
             summary: 'create, inspect, and manage profiles \u2014 agent identities with their own project purview and memory store',
-            model: '`new` creates one from a name (+ at most one initial `--project`). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
+            model: 'A profile owns a `home` — the first of its project dirs unless `project add --home` re-points it — and every node created under the profile is pinned there, so cwd selects the profile and the profile then supplies where its nodes run. Only `node new --cwd` (or inheriting a spawner already elsewhere, notably inside a managed worktree) overrides that; the root profile has no home, so nodes under it stay in the directory that created them. `new` creates one from a name (+ at most one initial `--project`, which becomes its home). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
         },
         children: [newLeaf, listLeaf, showLeaf, renameLeaf, deleteLeaf, projectBranch, defaultBranch, envBranch],
     });

package/dist/commands/push.js

@@ -73,7 +73,7 @@ function makeTierLeaf(tier) {
                 ...(tier === 'final'
                     ? [
                         'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
-                        'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close` (#327/#333); a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
+                        'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close`; a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
                     ]
                     : []),
             ],

package/dist/commands/surface/node/placement.d.ts

@@ -39,7 +39,7 @@ export declare function openSpawnViewer(nodeId: string, cwd: string, name: strin
  *  A `crtr surface attach` viewer self-tags its pane with the node it views
  *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
  *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
- *  re-plumbed CLI no longer reads canvas state to confirm the tagged node is
+ *  CLI does not read canvas state to confirm the tagged node is
  *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
  *  the pane is respawned. Callers that mutate then re-validate the id via the
  *  API (getNode 404 → clean error). */

package/dist/commands/surface/node/placement.js

@@ -111,7 +111,7 @@ export function openSpawnViewer(nodeId, cwd, name) {
  *  A `crtr surface attach` viewer self-tags its pane with the node it views
  *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
  *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
- *  re-plumbed CLI no longer reads canvas state to confirm the tagged node is
+ *  CLI does not read canvas state to confirm the tagged node is
  *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
  *  the pane is respawned. Callers that mutate then re-validate the id via the
  *  API (getNode 404 → clean error). */

package/dist/commands/surface-edit.js

@@ -33,6 +33,7 @@ import { isAbsolute, resolve } from 'node:path';
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { currentTmux, splitWindow, paneLocation, paneOfNode, } from '../core/runtime/placement-tmux.js';
+import { shellQuote } from '../shared/shell-quote.js';
 /** Resolve the pane the editor should open BESIDE — the pane that opened this
  *  command: explicit --pane, the caller's own $TMUX_PANE, the pane where THIS
  *  node is being watched (its `@crtr_node`-tagged pane, whatever viewer put it
@@ -57,10 +58,6 @@ function resolveTargetPane(explicit) {
     }
     return currentTmux()?.pane ?? null;
 }
-/** POSIX single-quote a shell word so paths survive spaces/specials. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /** The command the new pane runs. The pane INHERITS the tmux server environment
  *  (like every crtr chrome pane — the subagent viewer panes get theirs the same
  *  way), and a tmux server started from the human's interactive shell captured

package/dist/commands/sys/logs.js

@@ -3,7 +3,7 @@ import { isSafeNodeId } from '../../core/canvas/paths.js';
 import { usage } from '../../core/errors.js';
 import { validateOperationId } from '../../core/events/operation-id.js';
 import { readLogSnapshot } from '../../core/events/read.js';
-import { emitLine, isJsonOutput } from '../../core/io.js';
+import { emitLine, isJsonOutput, recordPreviewLine } from '../../core/io.js';
 const ISO_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/u;
 const MAX_PATTERN_BYTES = 4_096;
 function invalidFlag(flag, received, expected) {
@@ -116,8 +116,10 @@ export const sysLogsLeaf = defineLeaf({
             if (item.kind === 'event') {
                 if (json)
                     emitLine({ ...item.envelope });
-                else
+                else {
+                    recordPreviewLine({ ...item.envelope });
                     process.stdout.write(`${renderEvent(item.envelope)}\n`);
+                }
             }
             else if (!json) {
                 process.stdout.write(`RAW ${item.source} ${new Date(item.effectiveTsMs).toISOString()} ${JSON.stringify(item.content)}\n`);

package/dist/commands/sys/panels/panel.d.ts

@@ -7,9 +7,9 @@ export interface SetupPanel {
 type ThemeFgRole = "border" | "accent" | "dim" | "success" | "warning" | "muted" | "mdLink" | "mdLinkUrl";
 export declare const theme: {
     fg(role: ThemeFgRole, text: string): string;
-    /** A real filled selection band. `selectedBg` was previously an identity
-     *  function, which left the active tab and the active row with no background
-     *  at all — reverse video is the one background every terminal theme honours. */
+    /** A real filled selection band. An identity `selectedBg` would leave the
+     *  active tab and the active row with no background at all — reverse video is
+     *  the one background every terminal theme honours. */
     bg(_role: "selectedBg", text: string): string;
     bold(text: string): string;
 };

package/dist/commands/sys/panels/panel.js

@@ -23,9 +23,9 @@ export const theme = {
                 return ansiYellow(text);
         }
     },
-    /** A real filled selection band. `selectedBg` was previously an identity
-     *  function, which left the active tab and the active row with no background
-     *  at all — reverse video is the one background every terminal theme honours. */
+    /** A real filled selection band. An identity `selectedBg` would leave the
+     *  active tab and the active row with no background at all — reverse video is
+     *  the one background every terminal theme honours. */
     bg(_role, text) {
         return `\x1b[7m${text}\x1b[27m`;
     },