@north-light/crouter 0.3.227 → 0.3.229

package/dist/commands/memory/write.js

@@ -1,8 +1,23 @@
+import { join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
-import { writeText, pathExists } from '../../core/fs-utils.js';
+import { ensureDir, realpathOrSelf, walkFiles, writeText } from '../../core/fs-utils.js';
+import { associateRepository } from '../../core/memory/repository-association.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, serializeMemoryDoc, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, planNewDocumentPlacement, resolveWriteSelector, requireMountedStore, buildOrigin, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, requireCanonicalName, selectorParam, parseRequestedExtensionChanges, applyExtensionChanges, serializeMemoryDoc, } from './shared.js';
+function emptyMemoryStore(memoryDir) {
+    return walkFiles(memoryDir, (name) => name.endsWith('.md') && name !== 'SKILL.md', (name) => name === '.crouter').length === 0;
+}
+function hasWorkspaceFrontDoor(surfaces) {
+    const workspaceOpen = surfaces.some((entry) => entry['on'] === 'workspace-open' && entry['at'] === 'content');
+    const readEntry = surfaces.some((entry) => {
+        if (entry['on'] !== 'read' || entry['at'] !== 'content')
+            return false;
+        const match = entry['match'];
+        return match === './**' || (Array.isArray(match) && match.includes('./**'));
+    });
+    return workspaceOpen && readEntry;
+}
 // A topic's memory set stays usable only when authors treat cohesion as a creation
 // gate; otherwise small corrections accumulate as overlapping leaves whose routing
 // lines cannot tell a future reader which one owns the topic.
@@ -12,24 +27,25 @@ export const writeLeaf = defineLeaf({
     whenToUse: 'you are recording a new knowledge document or preference that does not exist yet. Creation only — a name already taken at the resolved scope is an error, because revising a stored document goes through `crtr memory edit`, which requires a rationale and records the revision.',
     help: {
         name: 'memory write',
-        summary: 'create memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
+        summary: 'create a memory document at the resolved store from frontmatter flags + a stdin body',
         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, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
             GUIDE_SURFACES + '\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 workspace front door is an ordinary doc carrying the entry pair {on: workspace-open, at: content} plus {on: read, match: "./**", at: content}: it enters first-message context when cwd/profile mounts its project store and fires on any file read beneath the store’s owning dir. Target the exact project with --dir. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` enforces exactly one such doc per project store managed by the selected profile.\n\n' +
+            'A workspace front door is an ordinary doc carrying the entry pair {on: workspace-open, at: content} plus {on: read, match: "./**", at: content}: it enters first-message context when cwd/profile mounts its project store and fires on any file read beneath the store’s owning dir. Target the exact project with --dir. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` requires this front door on the repository-root guide for a repository managed by the selected profile; nested stores may carry ordinary guides without a missing-door finding.\n\n' +
             'Choose the hook — boot vs read. A boot entry rides the boot catalog every agent sees; a read entry fires only when a matching file is actually read. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it off boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so skip read entries and route it through boot instead.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything. ' + GUIDE_ROUTING_LINE + '\n\n' +
             GUIDE_PREDICATE_VOCABULARY + '\n\n' +
+            GUIDE_CANONICAL_NAMES + '\n\n' +
             GUIDE_DOC_LINKS + '\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. Give reference leaves no surfaces at all — the directory listing and the link from the main doc are how they are found, so any routing entry 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 delivery rung and its findings carry the split guidance.\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. Give reference leaves no surfaces at all — the directory listing and the link from the main doc are how they are found, so any routing entry just double-charges every boot or read for depth the graph already routes. State each fact once. Keep facts that affect action or judgment, including constraints, exceptions, numbers, and exact names. Remove known context, inferable conclusions, filler transitions, and examples that resolve no ambiguity. `crtr memory lint` caps body length by delivery rung and its findings carry the split guidance.\n\n' +
             'A directory needs no index doc: reading a directory name returns its listing — each member’s routing line — so never author a doc that merely lists, fronts, or paraphrases its siblings. Write a directory-level doc only for synthesis: an operating guide or the cluster’s mechanics, ordering, conditions, and relationships, content no single member can carry. Guided entrance into a topic is an ordinary member doc, found through the listing like any other.\n\n' +
             'Find before write. Prefer slightly expanding an existing document with `crtr memory edit`, 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 stamped here and preserved by every later revision. 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.\n\n' +
             'Revise an existing doc with `crtr memory edit`.',
         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. The name must be free at that scope: an existing one is an error naming `crtr memory edit`.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical identity. Project writes require `<namespace>/<local name>`; writing the namespace itself targets the repository-root document. A trailing `/INDEX` is invalid because directory documents answer at the directory name. The identity must be free in the selected exact store.' },
             overlayParam('kind', { required: true }),
             overlayParam('when-and-why-to-read', { required: true }),
             overlayParam('short-form'),
@@ -39,13 +55,13 @@ export const writeLeaf = defineLeaf({
             overlayParam('slash'),
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
             { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is written.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes to the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) — the nearest scope, seen only by this running node, requires a node context.' },
-            { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Exact project directory to write under — targets `<dir>/.crouter/memory/` regardless of cwd or ancestor stores, scaffolding `.crouter/` there if absent. THE way to place a doc in a specific project’s store (e.g. another project in your profile’s purview) without cd’ing there, and the only way to target a dir shadowed by an ancestor store. Implies --scope project; rejects --scope user/profile.' },
-            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`. Rejected (usage error) unless --scope profile is also selected \u2014 never silently ignored for another scope.' },
+            selectorParam('scope-write'),
+            selectorParam('dir'),
+            selectorParam('profile'),
             { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin only — this leaf already claims the one positional for NAME, so a second bare argv token is rejected, not silently accepted as the body.' },
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The full canonical document name written.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, profile, or node.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
@@ -57,7 +73,7 @@ export const writeLeaf = defineLeaf({
         outputKind: 'object',
         dynamicState: () => memoryExtensionFieldCatalogHelp('write'),
         effects: [
-            'Creates memory/<name>.md at the resolved scope with the given frontmatter fields + stdin body, and opens memory/.history/<name>.jsonl with a `create` record.',
+            'Creates the selected physical memory document with the given frontmatter fields + stdin body, and opens its mirrored `.history` sidecar with a `create` record. An empty repository-root store is initialized at its root namespace only when the ordinary workspace front door surfaces are supplied.'
         ],
     },
     run: async (input) => {
@@ -67,17 +83,41 @@ export const writeLeaf = defineLeaf({
         const profileArg = input['profile'];
         const body = input['body'] ?? '';
         const dirArg = input['dir'];
-        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg, dirArg);
-        const path = memoryFilePath(memoryDir, name);
-        const extensionChanges = parseRequestedExtensionChanges(input['extension'], undefined, memoryExtensionCatalogForDoc({ scope, path }));
-        // Create-only. Revision goes through `edit`, which requires a rationale and
-        // records the change — a write that still overwrote would be a standing
-        // bypass of the audit trail. The error is the migration path.
-        if (pathExists(path)) {
-            throw usage(`${name} already exists at ${scope} scope — revise it with \`crtr memory edit ${name} --rationale "<why this revision>"\`, which records the change. \`write\` only creates.`, { memory: name, scope, path });
+        const selector = resolveWriteSelector({ scope: scopeArg, profile: profileArg, dir: dirArg });
+        const { scope, memoryDir, store } = selector;
+        let initializing = false;
+        if (scope === 'project' && store.mountStatus !== 'ready' && dirArg !== undefined && emptyMemoryStore(memoryDir)) {
+            const association = associateRepository(realpathOrSelf(dirArg));
+            if (association.ok) {
+                if (association.association.ownerRelativePath !== '') {
+                    throw usage(`${dirArg} is a nested store in the repository rooted at ${association.association.repositoryRoot}; only the repository root declares a namespace`, {
+                        next: 'crtr memory write <namespace> --dir <repositoryRoot>, or crtr sys migrate --dir <repositoryRoot>',
+                    });
+                }
+                initializing = true;
+            }
+            else if (association.code === 'no-project-root') {
+                initializing = true;
+            }
+        }
+        if (scope === 'project' && store.mountStatus !== 'ready' && !initializing)
+            requireMountedStore(store);
+        let canonicalName;
+        let path;
+        if (initializing) {
+            canonicalName = requireCanonicalName(name);
+            path = join(memoryDir, 'INDEX.md');
+        }
+        else {
+            const placement = planNewDocumentPlacement(store, name);
+            canonicalName = placement.canonicalName;
+            path = placement.path;
         }
+        const extensionChanges = parseRequestedExtensionChanges(input['extension'], undefined, memoryExtensionCatalogForDoc({ scope, path }));
         const frontmatter = {};
         frontmatter['kind'] = kind;
+        if (initializing)
+            frontmatter['namespace'] = canonicalName;
         // Provenance is runtime-stamped ONCE, here — who/when/where authored this
         // doc. Every later revision preserves it, so it always points at the
         // conversation that created the doc, not the last one to touch it.
@@ -112,7 +152,17 @@ export const writeLeaf = defineLeaf({
             surfacesVal.some((e) => e !== null && typeof e === 'object' && e['on'] === 'workspace-open')) {
             throw usage('a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one — drop the entry or write to a project store');
         }
+        if (initializing) {
+            const surfaces = Array.isArray(surfacesVal) ? surfacesVal.filter((entry) => entry !== null && typeof entry === 'object') : [];
+            if (!hasWorkspaceFrontDoor(surfaces)) {
+                throw usage('empty project initialization requires the ordinary workspace front door: --surface \'{on: workspace-open, at: content}\' and --surface \'{on: read, match: "./**", at: content}\'', {
+                    memory: canonicalName,
+                    next: `Pass both front-door surfaces when initializing ${canonicalName} with --dir.`,
+                });
+            }
+        }
         const after = serializeMemoryDoc(frontmatter, body);
+        ensureDir(memoryDir);
         writeText(path, after);
         const logPath = historyLogPathFor(memoryDir, path);
         appendHistoryRecord(logPath, buildHistoryRecord({ op: 'create', before: '', after }));
@@ -121,6 +171,7 @@ export const writeLeaf = defineLeaf({
         // result or its collapsed viewer preview.
         const selectedKeys = [
             'kind',
+            ...(initializing ? ['namespace'] : []),
             ...(input['whenAndWhyToRead'] !== undefined ? ['when-and-why-to-read'] : []),
             ...(input['shortForm'] !== undefined ? ['short-form'] : []),
             ...(input['unlisted'] === true ? ['unlisted'] : []),
@@ -132,14 +183,14 @@ export const writeLeaf = defineLeaf({
         ];
         const selectedFrontmatter = selectedKeys.map((key) => ({ key, value: frontmatter[key] }));
         return {
-            name,
+            name: canonicalName,
             kind,
             scope,
             path,
             created: true,
             frontmatter: selectedFrontmatter,
             log_path: logPath,
-            follow_up: `Read it back with \`crtr memory read ${name}\`, revise it later with \`crtr memory edit ${name} --rationale "<why>"\`, or browse the inventory with \`crtr memory list\`.`,
+            follow_up: `Read it back with \`crtr memory read ${canonicalName}\`, revise it later with \`crtr memory edit ${canonicalName} --rationale "<why>"\`, or browse the inventory with \`crtr memory list\`.`,
         };
     },
 });

package/dist/commands/memory.js

@@ -18,12 +18,12 @@ export function registerMemory() {
         rootEntry: {
             concept: 'a memory document you read on demand — knowledge or a preference',
             desc: 'list, read, search, and write memory documents',
-            useWhen: 'durable knowledge and preferences shared across nodes and sessions — use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Names are path-derived crtr identifiers, not file paths — read docs through the command surface, never cat or find the markdown off disk.',
+            useWhen: 'durable knowledge and preferences shared across nodes and sessions — use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Every document has one canonical name, a crtr identifier rather than a file path — read docs through the command surface, never cat or find the markdown off disk.',
         },
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name — a directory name is a valid read target answering with its listing. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content). A selected profile widens the project stack to every project in its purview, and each of those relationships caps what its stores deliver to the boot and workspace-open events; `read`, find, listings, and file- and command-routed delivery see the full corpus regardless.',
+            model: 'One address per document: its canonical name, the store’s namespace composed with its store-local name. A repository declares that namespace once, as `namespace:` on the root `INDEX.md` of `<repository root>/.crouter/memory/`, and a store nested inside the repository composes under that namespace plus its own path from the repository root; user, profile, node, and builtin names carry no namespace, and an installed plugin’s documents mount under the plugin’s own name. Resolution is exact — a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail — so `find` is the discovery surface when you do not know a name and `list` browses the whole inventory. A trailing `INDEX` is never part of an address, so a directory may carry its own document: reading the directory name returns that body together with the directory’s immediate listing. Precedence — node > project stack > profile > user > builtin — picks the winner among documents sharing ONE canonical name; `--paths` reports every physical candidate behind a name, and `--dir <project>` reaches one exact store. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content). A selected profile widens the project stack to every project in its purview, and each of those relationships caps what its stores deliver to the boot and workspace-open events; `read`, find, listings, and file- and command-routed delivery see the full corpus regardless.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, moveLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
     });

package/dist/commands/node/create.d.ts

@@ -12,7 +12,7 @@ export declare function assertKind(kind: string): void;
  *
  *  Keep this block cheap and caller-agnostic: help should not depend on the
  *  running node's current persona env, which can lag after polymorph. Sub-kinds
- *  (e.g. `plan/reviewers/security`) are OMITTED here — `KindConfig.availableTo`
+ *  (e.g. `audit/security`) are OMITTED here — `KindConfig.availableTo`
  *  defaults to the sub-kind's own top-level ancestor, and this generic block has
  *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
  *  sub-kind (universally available) earns a place in this list. A direct launch

package/dist/commands/node/create.js

@@ -40,7 +40,7 @@ export function assertKind(kind) {
  *
  *  Keep this block cheap and caller-agnostic: help should not depend on the
  *  running node's current persona env, which can lag after polymorph. Sub-kinds
- *  (e.g. `plan/reviewers/security`) are OMITTED here — `KindConfig.availableTo`
+ *  (e.g. `audit/security`) are OMITTED here — `KindConfig.availableTo`
  *  defaults to the sub-kind's own top-level ancestor, and this generic block has
  *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
  *  sub-kind (universally available) earns a place in this list. A direct launch

package/dist/commands/node/inspect.js

@@ -23,7 +23,7 @@ const nodeList = defineLeaf({
         summary: 'list nodes on the canvas, filtered by any combination of attribute slices and a graph-scope (--under) that AND together',
         params: [
             { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter status (comma-separated for several; accepted values: active, idle, done, dead, canceled). NOTE: `active` means the engine process is live (never closed), NOT that the node is generating right now — an active node is usually dormant between turns. To tell working-vs-idle, check the pi session-file mtime or CPU, not status.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (comma-separated for several). The <kinds> list below names every top-level installable kind; a sub-kind (e.g. plan/reviewers/security) filters too even though it is not listed.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (comma-separated for several). The <kinds> list below names every top-level installable kind; a registered sub-kind filters too by exact path even though it is not listed.' },
             { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'Filter by mode (comma-separated for several; accepted values: base, orchestrator).' },
             { kind: 'flag', name: 'lifecycle', type: 'string', required: false, constraint: 'Filter by lifecycle (comma-separated for several; accepted values: terminal, resident).' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Filter by profile. On the local canvas, accepts an exact profile id or a unique manifest name from the <profiles> list below. Against a remote canvas, pass the exact profile id carried by its node rows.' },

package/dist/commands/node/lifecycle.js

@@ -131,7 +131,7 @@ export const nodeConfig = defineLeaf({
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to resolve the node from. Defaults to $TMUX_PANE.' },
             { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Model spec: exact provider/id, capability tier (ultra|strong|medium|light), family alias (opus|sonnet|haiku), or a free-text substring when the broker is live. Dormant nodes require a provider/id, tier, or alias.' },
             { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Set lifecycle headlessly without closing the viewer. terminal owes a final and reaps when done; resident stays interactable while attached or awaiting something live.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here.' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator seeds a roadmap scaffold if absent.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Rename the node; if the node has a live window, also rename that viewer window.' },
         ],
@@ -241,7 +241,7 @@ export const nodePromote = defineLeaf({
         name: 'node promote',
         summary: 'promote yourself to an orchestrator when worthwhile parallel delegation should make coordination your primary job; task duration, sequential phases, or one helper do not qualify. Mode only — lifecycle stays as-is unless you pass --resident',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
             { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it is never forced to submit a final, stays wakeable while attached or awaiting something live, and completes after the unattended grace otherwise. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model you run 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. An orchestrator steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
@@ -258,7 +258,7 @@ export const nodePromote = defineLeaf({
         ],
         dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
-        effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); --model durably pins the model tier; rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.', 'Your new-role guidance is injected automatically at the turn boundary by the persona injector — the command no longer returns it.'],
+        effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); --model durably pins the model tier; rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.', 'The next model request is gated on appending and persisting your new-role guidance. If a fresh context starts first, its rebuilt baseline carries the new role.'],
     },
     run: async (input) => {
         const id = input['node'] ?? process.env['CRTR_NODE_ID'];
@@ -327,7 +327,7 @@ const nodeDemote = defineLeaf({
             { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach closed the agent\'s viewer pane (broker keeps running).' },
         ],
         outputKind: 'object',
-        effects: ['Flips the node\'s lifecycle→terminal and rebuilds its launch spec so a future revive boots terminal — it stays focused and running, now owing a final up the spine.', 'The persona injector delivers the transition guidance at the next turn boundary (or on the node\'s next revive if it is dormant).', 'With --detach: closes the agent\'s viewer pane WITHOUT touching the broker engine — it keeps generating off-screen, reconnectable by a later `focus`.'],
+        effects: ['Flips the node\'s lifecycle→terminal and rebuilds its launch spec so a future revive boots terminal — it stays focused and running, now owing a final up the spine.', 'The next model request is gated on appending and persisting the role transition. If a fresh context starts first, its rebuilt baseline carries the new lifecycle.', 'With --detach: closes the agent\'s viewer pane WITHOUT touching the broker engine — it keeps generating off-screen, reconnectable by a later `focus`.'],
     },
     run: async (input) => {
         const pane = input['pane'] ?? process.env['TMUX_PANE'];
@@ -373,7 +373,7 @@ export const nodeYield = defineLeaf({
         guide: 'Persist anything needed after refresh and send any pending human question before invoking; in-flight asks survive the refresh.',
         params: [
             { 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: '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 registered sub-kind 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: builtin orchestration guidance shows bare
             // `crtr node yield`; that invocation fails fast and surfaces yield's full help just in

package/dist/commands/pkg/market-manage.js

@@ -147,11 +147,17 @@ export const marketRemove = defineLeaf({
         return { name, removed: true };
     },
 });
+/** Stage a fresh checkout beside the active root. A clone that fails throws
+ *  the git error: reporting the active revision as current would present a
+ *  failed refresh as an up-to-date one, which is how a checkout stays pinned
+ *  to a stale revision with nothing on screen to say so. */
 function stageGitRoot(url, ref, active, candidate) {
-    const result = gitSync(['clone', '--depth', '1', '--branch', ref, url, candidate]);
-    if (result.status !== 0) {
+    try {
+        clone(url, candidate, { depth: 1, ref });
+    }
+    catch (error) {
         removePath(candidate);
-        return undefined;
+        throw error;
     }
     return { active, candidate, previous: `${candidate}.previous` };
 }
@@ -195,21 +201,17 @@ async function updateMarketplaceTarget(target) {
         if (isGitRepo(target.root)) {
             const candidate = join(dirname(target.root), `.${target.name}.${process.pid}.${Date.now()}.candidate`);
             marketplaceCandidate = stageGitRoot(target.url, target.ref, target.root, candidate);
-            if (marketplaceCandidate !== undefined) {
-                cleanupRoots.push(candidate);
-                const candidateManifest = readMarketplaceManifest(candidate);
-                if (candidateManifest === null)
-                    throw notFound(`marketplace manifest not found in candidate checkout: ${candidate}/.crouter-marketplace/marketplace.json`);
-                manifest = candidateManifest;
-                if (currentSha(candidate) !== activeSha)
-                    stagedRoots.push(marketplaceCandidate);
-            }
-            else {
-                const activeManifest = readMarketplaceManifest(target.root);
-                if (activeManifest === null)
-                    throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
-                manifest = activeManifest;
-            }
+            cleanupRoots.push(candidate);
+            const candidateManifest = readMarketplaceManifest(candidate);
+            if (candidateManifest === null)
+                throw notFound(`marketplace manifest not found in candidate checkout: ${candidate}/.crouter-marketplace/marketplace.json`);
+            manifest = candidateManifest;
+            // The staged checkout replaces the active root even at an unchanged
+            // revision. The tree is package-owned content, not a working copy: an
+            // in-place edit to it (a memory migration reaching a plugin through its
+            // symlink, a hand edit) otherwise survives every update, and a revision
+            // comparison would call that drifted tree current.
+            stagedRoots.push(marketplaceCandidate);
         }
         else {
             const activeManifest = readMarketplaceManifest(target.root);
@@ -221,6 +223,8 @@ async function updateMarketplaceTarget(target) {
             if (isSymlink(plugin.root)) {
                 if (marketplaceCandidate === undefined)
                     continue;
+                // A symlinked plugin resolves through the marketplace root, so the root
+                // swap above already replaced its content.
                 const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
                 if (entry === undefined || !isMarketplaceRelativeSource(entry.source)) {
                     throw general(`marketplace candidate removes relative-source plugin "${plugin.name}" while it is installed`);
@@ -251,15 +255,12 @@ async function updateMarketplaceTarget(target) {
             const candidate = join(scopeRoot, 'tmp', `${plugin.name}.${process.pid}.${Date.now()}.candidate`);
             ensureDir(join(scopeRoot, 'tmp'));
             const staged = stageGitRoot(remote, branch, plugin.root, candidate);
-            if (staged === undefined)
-                continue;
             cleanupRoots.push(candidate);
             const candidateManifest = readPluginManifest(candidate);
             if (candidateManifest === null)
                 throw notFound(`plugin manifest not found in update candidate: ${candidate}/.crouter-plugin/plugin.json`);
             candidates.push(candidatePlugin(plugin, candidate, candidateManifest));
-            if (currentSha(candidate) !== currentSha(plugin.root))
-                stagedRoots.push(staged);
+            stagedRoots.push(staged);
         }
         for (const candidate of candidates) {
             await assertPluginCandidateValid(candidate.plugin.manifest, candidate.plugin.root, candidate.plugin.scope, candidate.scopeRoot, `${candidate.plugin.root}/.crouter-plugin/plugin.json`, candidates);
@@ -294,7 +295,7 @@ async function updateMarketplaceTarget(target) {
 }
 export const marketUpdate = defineLeaf({
     name: 'update',
-    description: 'pull latest marketplace source',
+    description: 'replace marketplace source with its latest revision',
     whenToUse: 'refreshing one named marketplace source from git, or all registered marketplace sources when no name is given; also updates installed plugins sourced from refreshed marketplaces',
     help: {
         name: 'pkg market update',
@@ -307,7 +308,7 @@ export const marketUpdate = defineLeaf({
             { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per marketplace processed: {name, updated, sha}.' },
         ],
         outputKind: 'object',
-        effects: ['Stages and validates marketplace and sourced-plugin revisions before atomically activating them. Updates installed plugin content/version for plugins sourced from refreshed marketplaces.'],
+        effects: ['Stages and validates marketplace and sourced-plugin revisions before atomically activating them, replacing each checkout even at an unchanged revision — local modifications inside those directories are discarded. `updated` reports whether the revision moved, not whether the checkout was replaced. Updates installed plugin content/version for plugins sourced from refreshed marketplaces.'],
     },
     run: async (input) => {
         const name = input['name'];

package/dist/commands/pkg/plugin-manage.d.ts

@@ -4,18 +4,34 @@ interface MarketplaceRef {
     marketplace: string;
     plugin: string;
 }
+interface InstallResult {
+    name: string;
+    scope: Scope;
+    path: string;
+    memory?: PluginMemoryReport;
+}
+/** Who owns the physical memory corpus a candidate gate converges. A `package`
+ * corpus is bytes this command owns — staged, or installed under the scope's
+ * plugins dir — so a failed activation still rolls the package back. A `linked`
+ * corpus is the caller's own directory the install keeps as a live link: the
+ * rewrite lands there, outlives a rejected install, and is never rolled back. */
+type PluginMemoryOwnership = 'package' | 'linked';
+interface PluginMemoryReport extends Record<string, unknown> {
+    /** Markdown documents the candidate's memory store holds. */
+    docs: number;
+    /** Store-relative documents this gate rewrote to reach exact canonical identity. */
+    migrated: string[];
+    /** The caller-owned directory converged in place, absent for a package corpus. */
+    linkedSource?: string;
+}
 /** Validate a package candidate before it gains an active plugin path. The
  * candidate namespace shadows any installed declaration of the same name. */
-export declare function assertPluginCandidateValid(manifest: PluginManifest, root: string, scope: Scope, scopeRootPath: string, where: string, candidates?: readonly HookPluginCandidate[]): Promise<void>;
+export declare function assertPluginCandidateValid(manifest: PluginManifest, root: string, scope: Scope, scopeRootPath: string, where: string, candidates?: readonly HookPluginCandidate[], ownership?: PluginMemoryOwnership): Promise<PluginMemoryReport | undefined>;
 export declare function isMarketplaceRelativeSource(source: string): boolean;
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`
  *  uses — refresh the source, resolve the entry, link/clone, register. */
-export declare function installFromMarketplace(ref: MarketplaceRef, scope: Scope): Promise<{
-    name: string;
-    scope: Scope;
-    path: string;
-}>;
+export declare function installFromMarketplace(ref: MarketplaceRef, scope: Scope): Promise<InstallResult>;
 export declare const pluginInstall: import("../../core/command.js").LeafDef;
 export declare const pluginRemove: import("../../core/command.js").LeafDef;
 export declare const pluginEnable: import("../../core/command.js").LeafDef;