@north-light/crouter 0.3.174 → 0.3.176

package/dist/commands/memory/write.js

@@ -9,23 +9,24 @@ import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memo
 export const writeLeaf = defineLeaf({
     name: 'write',
     description: 'create or update a memory document',
-    whenToUse: 'you are recording a new knowledge document or preference — or revising one that already exists. Writes memory/<name>.md at the resolved scope from the frontmatter flags plus a body piped on stdin. Identity is path-derived: if <name> already exists at the scope it is updated in place, otherwise it is created.',
+    whenToUse: 'you are recording a new knowledge document or preference, or revising one that already exists — an existing <name> at the resolved scope is updated in place, so revision is also this leaf.',
     help: {
         name: 'memory write',
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
-        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' +
+        guide: '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, 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' +
-            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\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 scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
-            'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". The `.` route surfaces the full operating guide in first-message context whenever cwd or a selected profile mounts that project store; its envelope name comes from the owning project directory unless the document already carries an explicit name. It is a front door, not a manual — keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
-            'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog. Every non-none file-read rung also requires at least one explicit applies-to route: `.` means project workspace/profile mount and is evaluated during first-message assembly; every other value is a glob evaluated only after a matching file is actually read. There is no positional fallback from where the memory file lives. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
-            'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the READER’s payoff — the consequence they secure for the task in front of them by spending the read — never what the document says, its rule, or why it should be obeyed. The trap most authors fall into is the DISGUISED restatement: a because-clause that reads like a benefit but is just the doc’s own thesis reworded as an outcome. It still fails. The test: if you could derive the because-clause by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad (naked restatement): "because only genuine first principles belong in taste memory." Bad (restatement in benefit’s clothing): "because keeping the test loop fast and free of speculative tests protects the development pace" — that is the doc’s rule in outcome costume, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." The stranger test: someone mid-task who has NOT read the doc must be able to decide from this one line alone whether the read is worth it. 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.\n\n' +
+            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
+            'The visibility rungs `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 fits in a single sentence — a one-line preference or a one-sentence knowledge fact — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
+            'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is scratch memory only this running node sees; it rides into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
+            'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". Its envelope name comes from the owning project directory unless the document already carries an explicit name. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
+            'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog; file-read visibility fires on the applies-to routes. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
+            'Write the routing line (--when-and-why-to-read) first, before storing anything. The test for its because-clause: if it can be derived by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" — the doc’s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. 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.\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' +
             'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name — the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc’s resolvable links alongside its body. There is no alias or label form.\n\n' +
-            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. This is the same layering the visibility rungs apply to boot cost, applied to the body itself. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
-            'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body that would make the existing document harder to route or use. 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. Run `crtr memory lint` — the frontmatter validator — after authoring.\n\n' +
-            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. The bar: if the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into, so a merely-plausible-sounding reason is not worth recording. It is maintainer-facing only and NEVER ships in a delivered surface (boot render, on-read injection, `memory read` content) — it lives in frontmatter, visible only via `memory read --frontmatter`. Omit it when you have no such gap to record; omitting the flag on an update always preserves whatever rationale already exists.',
+            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
+            'A directory INDEX earns existence only where the aggregate view beats the sum of per-file rungs. Two shapes pass: synthesis — an operating guide or the cluster’s mechanics, ordering, and relationships, content no single child can carry — and aggregated routing — one preview line covering a large cluster with one shared routing condition, children dropped to `name` or `none`. Otherwise skip the INDEX and let each doc’s own rung route it: frontmatter routing lines are self-maintaining, while an INDEX body describing its children is a hand-maintained copy that drifts. Never write an INDEX that restates child names, paraphrases their routing lines, fronts a small directory of sharply named docs, or summarizes children a reader should open.\n\n' +
+            'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is automatic on create and preserved on update. Run `crtr memory lint` after authoring.\n\n' +
+            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. If the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity: one segment, or several joined with `/` to nest the document under a directory and group it with related docs → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
@@ -34,7 +35,7 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help. Required when creating — there is no kind default; pick a rung explicitly.' },
             { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much surfaces through file context. Required when creating — there is no kind default. Every value except none also requires at least one applies-to route in the resulting document.' },
             { 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, repeatable: true, constraint: 'One explicit file-context route per occurrence. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. Required whenever file-read-visibility is not none.' },
+            { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. There is no positional fallback from where the memory file lives. Required whenever file-read-visibility is not none.' },
             { 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: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },

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/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/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/core/__tests__/branded-host-concurrency.test.js

@@ -35,7 +35,7 @@ test('concurrent processes reconcile one coherent branded host tuple', async ()
     assert.ok(deadOwner !== undefined);
     const abandonedLock = join(home, '.crouter', 'host.lock');
     mkdirSync(abandonedLock);
-    writeFileSync(join(abandonedLock, 'owner.json'), JSON.stringify({ pid: deadOwner, token: 'abandoned' }));
+    writeFileSync(join(abandonedLock, `owner.${deadOwner}.abandoned`), '');
     try {
         const moduleUrl = pathToFileURL(join(process.cwd(), 'src/core/runtime/branded-host.ts')).href;
         const results = await Promise.all(Array.from({ length: 4 }, () => reconcileInChild(home, moduleUrl)));

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -13,7 +13,7 @@ import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { renderOnReadDocs } from '../substrate/on-read.js';
+import { renderOnReadDocs } from '../substrate/on-read-node.js';
 let canvasHome;
 let fakeHome;
 let prevHomeEnv;

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -13,7 +13,7 @@ import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { renderOnReadDocs } from '../substrate/on-read.js';
+import { renderOnReadDocs } from '../substrate/on-read-node.js';
 import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../substrate/injected-store.js';
 const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
 let home;

package/dist/core/canvas/extensions.d.ts

@@ -1,4 +1,4 @@
-export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve"];
+export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result"];
 /** Structural shipped-hook identity: a canvas-hook stem directly under a
  * `pi-extensions` directory. A user's own extension elsewhere may share the
  * stem and is not shipped. */

package/dist/core/canvas/extensions.js

@@ -7,9 +7,15 @@ export const CANVAS_EXTENSION_NAMES = [
     'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
     'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
     'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
-    'canvas-bash-valve',
+    'canvas-bash-valve', 'canvas-preview-result',
 ];
 const HISTORICAL_CANVAS_EXTENSION_PREFIXES = [
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve',
+    ],
     [
         'canvas-inbox-watcher', 'canvas-stophook', 'canvas-recap',
         'canvas-goal-capture', 'canvas-passive-context', 'canvas-review-boundary',

package/dist/core/command-plugins/transport/http-invoke.js

@@ -17,7 +17,7 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { validateDeclaredResult } from './exec-invoke.js';
 import { CrtrError } from '../../errors.js';
-import { diag, writeStdout } from '../../io.js';
+import { diag, recordPreviewError, recordPreviewJsonLine, writeStdout } from '../../io.js';
 import { ExitCode } from '../../../types.js';
 // ---------------------------------------------------------------------------
 // Constants
@@ -420,6 +420,7 @@ async function requestStreaming(spec, plan) {
                 if (line.trim() === '')
                     continue; // drop blank records
                 framesEmitted = true;
+                recordPreviewJsonLine(line);
                 const ok = await writeStdout(line + '\n');
                 if (!ok) {
                     // Consumer closed the pipe (EPIPE) — stop cleanly, nothing to report.
@@ -434,6 +435,7 @@ async function requestStreaming(spec, plan) {
         // backend sent no trailing delimiter, so none is added).
         if (partial.trim() !== '') {
             framesEmitted = true;
+            recordPreviewJsonLine(partial);
             await writeStdout(partial);
         }
         return; // clean EOF → SUCCESS
@@ -444,7 +446,13 @@ async function requestStreaming(spec, plan) {
         if (framesEmitted) {
             // After a frame has been emitted: one concise stderr diagnostic + NETWORK
             // exit, and DO NOT throw (that would append an <error> to stdout).
-            diag(`crtr: ${label(spec)}: stream interrupted (${detail})`);
+            const message = `${label(spec)}: stream interrupted (${detail})`;
+            diag(`crtr: ${message}`);
+            recordPreviewError({
+                error: 'stream_interrupted',
+                message,
+                next: 'Retry the command to begin a fresh stream.',
+            });
             process.exitCode = ExitCode.NETWORK;
             return;
         }

package/dist/core/command.js

@@ -5,7 +5,7 @@
 // A plain array walk + a small flag parser is ~120 lines and has no surprising
 // edge cases.
 import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
-import { readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
+import { beginPreview, publishPreviewResult, readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
 import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { operationIdContext } from './events/operation-id.js';
@@ -614,6 +614,7 @@ export async function runCli(root, argv) {
         // below: `node` is now a reassignable `let` (the §5.1 retry re-walks it),
         // which TS re-widens to the node union across an `await`.
         const leaf = node;
+        beginPreview(path.join(' '));
         const params = leaf.help.params !== undefined ? leaf.help.params : [];
         let providedParams = new Set();
         let contextFilePaths = new Map();
@@ -628,6 +629,7 @@ export async function runCli(root, argv) {
         });
         const context = { providedParams, contextFilePaths };
         const result = await operationIdContext.fresh(() => leaf.run(input, context));
+        publishPreviewResult(result);
         if (result !== undefined && result !== null) {
             if (isJsonOutput()) {
                 emit(result);

package/dist/core/config.js

@@ -1,4 +1,3 @@
-import { mkdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
@@ -7,6 +6,7 @@ import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
 import { profileRoot } from './profiles/manifest.js';
+import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
 function configPathFor(root) {
@@ -54,34 +54,11 @@ export function readState(scope) {
         activeCanvas: existing.activeCanvas ?? null,
     };
 }
-const CONFIG_LOCK_TIMEOUT_MS = 5000;
-const CONFIG_LOCK_POLL_MS = 25;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
 function withConfigPathLock(path, run) {
     ensureDir(dirname(path));
-    const lockPath = `${path}.lock`;
-    const deadline = Date.now() + CONFIG_LOCK_TIMEOUT_MS;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
-            break;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            if (Date.now() > deadline)
-                throw new Error(`timed out waiting for config lock: ${path}`);
-            sleepSync(CONFIG_LOCK_POLL_MS);
-        }
-    }
-    try {
-        return run(path);
-    }
-    finally {
-        rmSync(lockPath, { recursive: true, force: true });
-    }
+    return withExclusiveDirectoryLock(`${path}.lock`, () => run(path), {
+        timeoutError: () => new Error(`timed out waiting for config lock: ${path}`),
+    });
 }
 function withConfigLock(scope, run) {
     const root = requireScopeRoot(scope);

package/dist/core/exclusive-lock.d.ts

@@ -0,0 +1,14 @@
+export interface ExclusiveLockOptions {
+    /** Grace before a lock that names no owner at all is cleared. */
+    staleMs?: number;
+    timeoutMs?: number;
+    /** The error thrown when the wait runs out, so callers keep their own remediation. */
+    timeoutError?: () => Error;
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: ExclusiveLockOptions): T;