@north-light/crouter 0.3.221 → 0.3.222

package/dist/core/runtime/prospective-inventory.js

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chatInventoryCommandRows, chatInventoryMemoryRows } from './chat-inventory-rows.js';
+import { FRONT_DOOR_ENV } from './front-door-env.js';
+const PREFLIGHT_TIMEOUT_MS = 15_000;
+function entryPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'prospective-inventory-cli.js');
+}
+function parseDocument(response) {
+    const parsed = JSON.parse(response.trim());
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('preflight output must be an object');
+    const record = parsed;
+    if (!Array.isArray(record['commands']) || !Array.isArray(record['memory_refs'])) {
+        throw new Error('preflight output must contain command and memory-ref arrays');
+    }
+    return {
+        commands: chatInventoryCommandRows(record['commands']),
+        memory_refs: chatInventoryMemoryRows(record['memory_refs']),
+    };
+}
+export function runProspectiveInventory(input) {
+    return new Promise((resolve, reject) => {
+        const env = {
+            ...process.env,
+            CRTR_PROFILE_ID: input.profileId ?? '',
+            [FRONT_DOOR_ENV]: '1',
+        };
+        delete env['CRTR_NODE_ID'];
+        const child = spawn(process.execPath, [entryPath()], {
+            cwd: input.cwd,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let response = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            reject(new Error('prospective inventory preflight timed out'));
+        }, PREFLIGHT_TIMEOUT_MS);
+        timer.unref?.();
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        const responseStream = child.stdio[3];
+        if (responseStream === null || responseStream === undefined || !('setEncoding' in responseStream)) {
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+            reject(new Error('prospective inventory preflight response channel unavailable'));
+            return;
+        }
+        responseStream.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        responseStream.on('data', (chunk) => { response += chunk; });
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const diagnostics = [stderr.trim(), stdout.trim()].filter(Boolean).join('\n');
+            if (code !== 0) {
+                reject(new Error(`prospective inventory preflight exited ${code ?? signal ?? 'unknown'}${diagnostics === '' ? '' : `: ${diagnostics}`}`));
+                return;
+            }
+            try {
+                resolve(parseDocument(response));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                reject(new Error(`${message}${diagnostics === '' ? '' : `: ${diagnostics}`}`));
+            }
+        });
+        child.stdin.end(JSON.stringify({ extensions: input.extensions }));
+    });
+}

package/dist/core/runtime/spawn.d.ts

@@ -88,7 +88,9 @@ export declare function resolveForkSource(value: string): string;
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
  *  root-profile prompt/default). */
-export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string): Promise<string | null>;
+export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string, options?: {
+    readOnlySelection?: boolean;
+}): Promise<string | null>;
 /** Reject a permanently invalid launch recipe against the registry that will
  * serve it. Registered-but-unauthenticated/cooling requests intentionally pass
  * this authoring check so broker policy for transient availability is unchanged. */

package/dist/core/runtime/spawn.js

@@ -13,7 +13,7 @@ import { accessSync, constants, cpSync, readdirSync, existsSync, rmSync } from '
 import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
-import { selectProfileForCwd } from '../profiles/select.js';
+import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
@@ -153,7 +153,7 @@ export function resolveForkSource(value) {
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
  *  root-profile prompt/default). */
-export async function resolveProfileId(explicit, spawner, cwd) {
+export async function resolveProfileId(explicit, spawner, cwd, options = {}) {
     if (explicit === null)
         return null;
     if (explicit !== undefined && explicit !== '') {
@@ -161,7 +161,9 @@ export async function resolveProfileId(explicit, spawner, cwd) {
     }
     if (spawner !== null)
         return getNode(spawner)?.profile_id ?? null;
-    return selectProfileForCwd(cwd);
+    return options.readOnlySelection === true
+        ? selectProfileForCwdReadOnly(cwd)
+        : selectProfileForCwd(cwd);
 }
 function requestFromLaunch(launch) {
     const intent = launch.modelIntent === undefined

package/dist/core/substrate/on-read.js

@@ -48,27 +48,6 @@ function attr(s) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-function gitRootOf(p) {
-    let d = p;
-    const root = parse(d).root;
-    while (true) {
-        if (pathExists(`${d}${sep}.git`))
-            return d;
-        if (d === root)
-            return null;
-        const parent = dirname(d);
-        if (parent === d)
-            return null;
-        d = parent;
-    }
-}
-function disp(p) {
-    const root = gitRootOf(p);
-    if (!root)
-        return p;
-    const rel = relative(root, p);
-    return rel === '' ? '.' : rel;
-}
 function isJunkAncestor(dir) {
     return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
 }
@@ -184,16 +163,26 @@ function docContentKey(doc) {
         return null;
     return `content-sha256:${createHash('sha256').update(body).digest('hex')}`;
 }
+// Two shapes: element-with-body means the content is here; self-closing means
+// it is not — a preview carries its routing line as `readWhen` metadata so the
+// one-liner can never be mistaken for the document's content. No disk path:
+// agents address memory by name through the command surface, and the explicit
+// read leaf already returns `path`.
 function renderDocEnvelope(doc, rung) {
     if (rung === 'none')
         return null;
-    let body = '';
-    if (rung === 'content')
-        body = doc.body.trim();
-    else if (rung === 'preview')
-        body = previewLine(doc);
-    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" src="${attr(disp(doc.path))}"`;
-    return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
+    let attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}"`;
+    if (rung === 'content') {
+        const body = doc.body.trim();
+        if (body !== '')
+            return `<memory ${attrs}>\n${body}\n</memory>`;
+    }
+    else if (rung === 'preview') {
+        const pl = previewLine(doc);
+        if (pl !== '')
+            attrs += ` readWhen="${attr(pl)}"`;
+    }
+    return `<memory ${attrs} />`;
 }
 /** Render candidates at their matched rungs, gate-checked and deduped against
  *  the transcript set (higher rungs pierce lower; a delivery records at its

package/dist/core/substrate/render-node.d.ts

@@ -1,6 +1,7 @@
 import type { InjectedDocs } from './injected-store.js';
-/** The system-prompt `<memory kind="preference">` block for `nodeId`: assemble
- *  the node's subject from the canvas-db, render the pure block, then swap the
+/** The system-prompt substrate splice for `nodeId` — shipped-layer protocol
+ *  prose followed by the `<memory kind="preference">` block: assemble
+ *  the node's subject from the canvas-db, render the pure splice, then swap the
  *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
  *  so agents don't paste it into the non-expanding Write tool (see
  *  interpolateNodePaths). A null subject (unknown id) still renders the

package/dist/core/substrate/render-node.js

@@ -8,8 +8,9 @@
 import { interpolateNodePaths } from '../canvas/paths.js';
 import { assembleNodeSubject } from './subject.js';
 import { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
-/** The system-prompt `<memory kind="preference">` block for `nodeId`: assemble
- *  the node's subject from the canvas-db, render the pure block, then swap the
+/** The system-prompt substrate splice for `nodeId` — shipped-layer protocol
+ *  prose followed by the `<memory kind="preference">` block: assemble
+ *  the node's subject from the canvas-db, render the pure splice, then swap the
  *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
  *  so agents don't paste it into the non-expanding Write tool (see
  *  interpolateNodePaths). A null subject (unknown id) still renders the

package/dist/core/substrate/render.js

@@ -183,9 +183,16 @@ function compareTreePosition(a, b) {
     }
     return as.length - bs.length;
 }
+/** A doc the running agent can revise through `crtr memory edit`: any native
+ *  scope-store doc (user/profile/project/node). Shipped docs — builtin and
+ *  plugin-mounted — are not editable from a node; the preference render treats
+ *  them as operating protocol, not memory (see buildPreferencesBlock). */
+function isAgentEditable(doc) {
+    return doc.scope !== 'builtin' && doc.plugin === undefined;
+}
 /** STEP 2 — split deduped `winners` by rung and render each group in its
  *  display order: `content` docs first, as clean prose (general→specific,
- *  then tree position, then filename — no tree chrome, no name label); every
+ *  then tree position, then filename — no tree chrome); every
  *  other winner (preview/name/hidden-bootless) folds into ONE catalog tree
  *  exactly as before. `nodeLocalSet` marks which winners came from the
  *  node-local store (ranked most-specific in content ordering); omit it for a
@@ -489,37 +496,62 @@ function buildSubPersonaMenu(kind) {
         lines.join('\n'));
 }
 // ---------------------------------------------------------------------------
-// 1. Preferences — `<memory kind="preference">` (system prompt).
+// 1. Preferences — protocol prose + `<memory kind="preference">` (system prompt).
 // ---------------------------------------------------------------------------
-/** The system-prompt memory block: the always-present memory-usage guidance,
- *  then (when any are eligible) the `kind: preference` docs GROUPED by rung —
- *  content-rung docs first as clean prose (general→specific), then the
- *  preview/name catalog tree. ALWAYS returns a non-empty `<memory
- *  kind="preference">` block — the guidance frame is unconditional, so the
- *  system-prompt splice is never empty even when no preference is eligible. */
+/** The system-prompt substrate splice, TWO parts in one string.
+ *
+ *  1. The operating protocol: shipped (builtin/plugin) content-rung bodies as
+ *     bare prose, plus the sub-persona menu. No memory envelope — the protocol
+ *     is the rules of the node's world, and wrapping it as recalled "memory:
+ *     preference" content gave it softer epistemic status than the
+ *     instructions it is; the intro/outro sentences ("how the user wants you
+ *     to behave", "update the preference") were also false of it.
+ *  2. The `<memory kind="preference">` block: the always-present memory-usage
+ *     guidance, then (when any are eligible) each agent-editable doc wrapped
+ *     `<preference name="…">…</preference>` — the name is the edit handle the
+ *     outro's update directive needs — then the preview/name catalog tree.
+ *     Every frame sentence is true of everything inside it.
+ *
+ *  Ordering across the two parts is unchanged from the single-block render
+ *  (shipped→editable was already the scope sort), so the shared cache prefix
+ *  across nodes is preserved. ALWAYS returns a non-empty splice — the guidance
+ *  frame is unconditional, so it is never empty even when no preference is
+ *  eligible. */
 function buildPreferencesBlock(subject, seen) {
-    let body = MEMORY_USAGE_GUIDANCE;
     let contentDocs = [];
     let tree = '';
+    let protocol = '';
+    let memBody = MEMORY_USAGE_GUIDANCE;
     if (subject !== null) {
         const winners = selectWinners(subject, 'preference');
         seedBootDelivery(seen, winners);
         const grouped = renderGrouped(winners, 'preferences');
         contentDocs = grouped.contentDocs;
         tree = grouped.tree;
+        const shipped = contentDocs
+            .filter((d) => !isAgentEditable(d))
+            .map((d) => d.body.trim())
+            .filter((b) => b !== '');
+        const editable = contentDocs
+            .filter((d) => isAgentEditable(d))
+            .map((d) => {
+            const b = d.body.trim();
+            return b === '' ? '' : `<preference name="${d.name}">\n${b}\n</preference>`;
+        })
+            .filter((b) => b !== '');
         const subPersonaMenu = buildSubPersonaMenu(subject.kind);
-        if (grouped.contentProse !== '' || grouped.tree !== '' || subPersonaMenu !== '') {
-            body += `\n\n${PREFERENCES_INTRO}`;
-            if (grouped.contentProse !== '')
-                body += `\n\n${grouped.contentProse}`;
-            if (subPersonaMenu !== '')
-                body += `\n\n${subPersonaMenu}`;
-            if (grouped.tree !== '')
-                body += `\n\n${grouped.tree}`;
-            body += `\n\n${PREFERENCES_OUTRO}`;
+        protocol = [...shipped, ...(subPersonaMenu === '' ? [] : [subPersonaMenu])].join('\n\n');
+        if (editable.length > 0 || tree !== '') {
+            memBody += `\n\n${PREFERENCES_INTRO}`;
+            if (editable.length > 0)
+                memBody += `\n\n${editable.join('\n\n')}`;
+            if (tree !== '')
+                memBody += `\n\n${tree}`;
+            memBody += `\n\n${PREFERENCES_OUTRO}`;
         }
     }
-    return { block: `<memory kind="preference">\n${body}\n</memory>`, contentDocs, tree };
+    const memoryBlock = `<memory kind="preference">\n${memBody}\n</memory>`;
+    return { block: protocol === '' ? memoryBlock : `${protocol}\n\n${memoryBlock}`, contentDocs, tree };
 }
 export function renderPreferencesForSubject(subject, seen) {
     return buildPreferencesBlock(subject, seen);

package/dist/core/substrate/schema.d.ts

@@ -14,7 +14,7 @@ export declare function rungAtLeast(r: Rung, min: Rung): boolean;
  *  authored rung against its project relationship's cap. */
 export declare function minRung(a: Rung, b: Rung): Rung;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
- *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  directory display name). `00-runtime-base/00-authoring` -> `runtime-base/authoring`; `spine` (no
  *  prefix) is unchanged. */
 export declare function normalizeNameSegment(segment: string): string;
 /** Normalize a full slash-separated path-derived doc name by stripping the
@@ -111,6 +111,10 @@ export interface SubstrateDoc extends SubstrateSchema {
     name: string;
     /** The scope this doc resolved from. */
     scope: MemoryScope;
+    /** Owning plugin name when the doc is mounted from an installed plugin;
+     *  undefined for a native scope doc. Shipped (builtin/plugin) docs and
+     *  agent-editable scope docs render differently at boot (see renderGrouped). */
+    plugin?: string;
     /** Absolute path to the source .md. */
     path: string;
     /** Document body, frontmatter stripped. */

package/dist/core/substrate/schema.js

@@ -43,18 +43,18 @@ export function minRung(a, b) {
 // ---------------------------------------------------------------------------
 // Display-name normalization — the optional `NN-` ordering pin. A doc's
 // physical path may carry a two-digit numeric prefix on a file or directory
-// segment (`00-runtime-base.md`, `01-spine/`) purely to pin structural order
+// segment (`00-runtime-base/`, `01-spine/`) purely to pin structural order
 // against natural sort (design: builtin prompt corpus, used sparingly). The
 // prefix is NEVER part of the doc's identity: every identity-facing surface —
 // MemoryDoc.name, direct lookup, leaf fallback, `crtr memory read`/`list`,
 // prompt render, on-read display — derives from the NORMALIZED segments, so
-// `00-runtime-base` displays/dedups/resolves as `runtime-base`. When a doc
+// `00-runtime-base/00-authoring` displays/dedups/resolves as `runtime-base/authoring`. When a doc
 // sets an explicit frontmatter `name`, that normalized name wins instead of
 // the path-derived fallback. Only the physical path keeps the prefix.
 // ---------------------------------------------------------------------------
 const NUMERIC_PREFIX_RE = /^\d{2}-/;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
- *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  directory display name). `00-runtime-base/00-authoring` -> `runtime-base/authoring`; `spine` (no
  *  prefix) is unchanged. */
 export function normalizeNameSegment(segment) {
     return segment.replace(NUMERIC_PREFIX_RE, '');
@@ -142,7 +142,7 @@ export function parseSubstrateDoc(doc) {
     const schema = parseSubstrateFrontmatter(doc.frontmatter);
     if (schema === null)
         return null;
-    return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body, projectMemory: doc.projectMemory };
+    return { ...schema, name: doc.name, scope: doc.scope, plugin: doc.plugin, path: doc.path, body: doc.body, projectMemory: doc.projectMemory };
 }
 /** The kind a doc resolves to for `--kind` filtering/matching: the substrate
  *  kind when the frontmatter parses as a valid substrate doc, else the raw

package/dist/core/user-settings.d.ts

@@ -326,6 +326,10 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
         surface: "specialized";
         owner: string;
     };
+    humanActions: {
+        surface: "specialized";
+        owner: string;
+    };
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export declare const SCOPE_CONFIG_KEYS: (keyof ScopeConfig)[];

package/dist/core/user-settings.js

@@ -389,6 +389,7 @@ export const CONFIG_SETTINGS_COVERAGE = {
     remoteCanvas: { surface: 'specialized', owner: 'canvas config commands' },
     spawnEnv: { surface: 'specialized', owner: 'spawn environment allow-list' },
     bin: { surface: 'specialized', owner: 'bare-binary contributions on every node PATH' },
+    humanActions: { surface: 'specialized', owner: 'scope-configured human completion actions' },
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export const SCOPE_CONFIG_KEYS = Object.keys(CONFIG_SETTINGS_COVERAGE);

package/dist/daemon/api/__tests__/profile-launch-gates.test.js

@@ -1,16 +1,17 @@
 import { after, afterEach, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, getNode, listNodes } from '../../../core/canvas/canvas.js';
 import { closeDb } from '../../../core/canvas/db.js';
 import { CrtrError } from '../../../core/errors.js';
-import { createProfile, loadProfileManifest, pauseProfile, setProfileDefaultKind } from '../../../core/profiles/manifest.js';
+import { createProfile, loadProfileManifest, pauseProfile, profileManifestPath, ROOT_PROFILE_ID, setProfileDefaultKind } from '../../../core/profiles/manifest.js';
 import { resetScopeCache } from '../../../core/scope.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
+import { resolveLaunchTarget } from '../../../core/runtime/launch-target.js';
 import { spawnNode } from '../../../core/runtime/nodes.js';
-import { handleCreate, resolveCreateKind } from '../handlers/nodes.js';
+import { handleConfig, handleCreate, resolveCreateKind } from '../handlers/nodes.js';
 const previousCrtrHome = process.env['CRTR_HOME'];
 const previousHome = process.env.HOME;
 let home = '';
@@ -101,6 +102,54 @@ test('the birth gate refuses a paused profile for a daemon-side spawn', () => {
     });
     assert.equal(listNodes().length, beforeRows);
 });
+test('prospective root selection stays read-only before the root profile is scaffolded', async () => {
+    const manifestPath = profileManifestPath(ROOT_PROFILE_ID);
+    assert.equal(existsSync(manifestPath), false);
+    const target = await resolveLaunchTarget({ root: true, cwd }, { readOnlyProfileSelection: true });
+    assert.equal(target.profileId, ROOT_PROFILE_ID);
+    assert.equal(target.profile, null);
+    assert.equal(target.kind, 'general');
+    assert.equal(target.cwd, cwd);
+    assert.equal(existsSync(manifestPath), false);
+});
+test('target-scoped prospective validation does not rescope node writes', async () => {
+    mkdirSync(join(cwd, '.crouter'), { recursive: true });
+    writeFileSync(join(cwd, '.crouter', 'config.json'), JSON.stringify({
+        kinds: { 'target-only': { whenToUse: 'Only in this project.' } },
+    }));
+    const target = await resolveLaunchTarget({ root: true, cwd, kind: 'target-only' }, { readOnlyProfileSelection: true });
+    assert.equal(target.kind, 'target-only');
+    const create = {
+        method: 'POST',
+        path: '/v1/nodes',
+        params: {},
+        query: new URLSearchParams(),
+        body: { root: true, profile: null, cwd, kind: 'target-only' },
+    };
+    await assert.rejects(() => handleCreate(create), /unknown kind: target-only/);
+    const id = 'ambient-kind-write';
+    createNode({
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent: null,
+        profile_id: null,
+    });
+    const patch = {
+        method: 'PATCH',
+        path: `/v1/nodes/${id}/config`,
+        params: { id },
+        query: new URLSearchParams(),
+        body: { kind: 'target-only' },
+    };
+    await assert.rejects(() => handleConfig(patch), /unknown kind: target-only/);
+    assert.equal(getNode(id)?.kind, 'general');
+});
 test('create kind resolves from the profile default when omitted', () => {
     const profile = createProfile('default kind', [{ path: cwd, memory: 'content' }]);
     setProfileDefaultKind(profile.profileId, 'developer');

package/dist/daemon/api/handlers/human-requests.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const humanRequestRoutes: RouteTable;