@north-light/crouter 0.3.220 → 0.3.222

package/dist/migrations/002-profile-project-memory.js

@@ -0,0 +1,71 @@
+// 002 — profile projects gain an explicit memory value. Historical manifests
+// stored `projects` as bare directory strings; the current contract is
+// `{ path, memory }`, where memory caps automatic boot/workspace-open
+// disclosure from that project's stores.
+//
+// Mapping: a string entry on the root profile becomes `preview` (root is an
+// aggregate identity — it points at everything and should not absorb every
+// project's full corpus), every other profile's string entries become
+// `content` (they were authored as that profile's own working context).
+// Root is classified ONLY by the fixed profile directory id: a manifest
+// `name` is mutable, so `name === 'root'` would misclassify a renamed profile.
+//
+// Mixed manifests converge: already-valid objects pass through byte-identical
+// and only string entries convert. Anything else — a non-array `projects`, a
+// non-string/non-object entry, an object without a path, an unknown memory
+// value — throws naming the file, because a guessed cap silently widens or
+// narrows what every node under that profile is shown.
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../api/dto/profiles.js';
+import { usage } from '../core/errors.js';
+/** Frozen copy of `ROOT_PROFILE_ID` (core/profiles/manifest.ts). Migrations
+ *  stay out of that module's import graph — its readers reject the very
+ *  manifests this lane exists to convert. */
+const ROOT_PROFILE_ID = 'root-00000000';
+function malformed(input, detail) {
+    return usage(`profile manifest cannot be migrated: ${detail}`, {
+        received: input.path,
+        field: 'projects',
+        next: `Fix ${input.path} by hand — every project entry is a string (pre-migration) or {"path": "/abs/dir", "memory": one of ${PROFILE_PROJECT_MEMORY_VALUES.join(', ')}} — then re-run \`crtr sys migrate\`.`,
+    });
+}
+function isMemory(value) {
+    return typeof value === 'string' && PROFILE_PROJECT_MEMORY_VALUES.includes(value);
+}
+export const profileProjectMemoryMigration = {
+    lane: 'profile-manifest',
+    description: 'profile projects carry an explicit memory value',
+    apply(input) {
+        const stored = input.raw['projects'];
+        if (!Array.isArray(stored)) {
+            throw malformed(input, `projects is ${stored === undefined ? 'missing' : typeof stored}, not an array`);
+        }
+        const legacyMemory = input.profileId === ROOT_PROFILE_ID ? 'preview' : 'content';
+        let converted = false;
+        const projects = stored.map((entry) => {
+            if (typeof entry === 'string') {
+                if (entry.trim() === '')
+                    throw malformed(input, 'a project entry is an empty path');
+                converted = true;
+                return { path: entry, memory: legacyMemory };
+            }
+            if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+                throw malformed(input, `a project entry is ${entry === null ? 'null' : typeof entry}`);
+            }
+            const { path, memory } = entry;
+            if (typeof path !== 'string' || path.trim() === '') {
+                throw malformed(input, `a project entry has no path: ${JSON.stringify(entry)}`);
+            }
+            if (!isMemory(memory)) {
+                throw malformed(input, `project ${path} has an unknown memory value: ${JSON.stringify(memory)}`);
+            }
+            // Byte-identical pass-through: an already-valid entry keeps whatever
+            // else it carries, so re-running plans no change.
+            return entry;
+        });
+        if (!converted)
+            return null;
+        // Spread preserves the manifest's stored key order, so the rewrite's diff
+        // is the projects array and nothing else.
+        return { ...input.raw, projects };
+    },
+};

package/dist/migrations/profile-manifests.d.ts

@@ -0,0 +1,30 @@
+import type { ProfileManifestSnapshot, StateMigration } from './types.js';
+export interface ProfileManifestRunResult {
+    /** Profile manifests found under the profiles root. */
+    profiles: number;
+    /** One row per migration that rewrote a manifest, in registry order. */
+    applied: {
+        profileId: string;
+        path: string;
+        migration: string;
+    }[];
+    /** Post-migration manifest per readable profile, in scan order — coherent
+     *  under `dryRun`, where the same fold ran but nothing was written. */
+    snapshots: ProfileManifestSnapshot[];
+    /** Manifests left untouched because they are not valid JSON. Unreadable
+     *  bytes are not a structure this lane can convert, and failing the run over
+     *  one would block every other profile's convergence. */
+    skipped: {
+        profileId: string;
+        path: string;
+        error: string;
+    }[];
+}
+export declare function runProfileManifestMigrations(profilesRoot: string, opts: {
+    /** Held for the whole re-read/fold/write of one manifest — the same lock
+     *  add/remove take, so a concurrent mutation either lands before the
+     *  re-read or serializes after the write, never under it. */
+    withLock: <T>(profileId: string, fn: () => T) => T;
+    dryRun?: boolean;
+    migrations?: readonly StateMigration[];
+}): ProfileManifestRunResult;

package/dist/migrations/profile-manifests.js

@@ -0,0 +1,70 @@
+// The profile-manifest lane runner: fold every registered profile-manifest
+// migration over each stored `profile.json`, one profile at a time, under the
+// caller-supplied per-profile lock.
+//
+// This lane reads RAW BYTES. The current manifest reader treats a manifest
+// whose projects are not the current shape exactly like corrupt JSON, so a
+// pre-migration home has no readable profiles at all — every profile surface,
+// `listProfiles()` included, is blind until this lane has run. That is why the
+// runner enumerates the profiles root itself, why `crtr sys migrate` runs it
+// before any other profile read, and why its snapshots (not `listProfiles()`)
+// are what the rest of that command's discovery works from.
+//
+// The lock arrives as a callback rather than an import: a migration file may
+// not reach into the profile module, and a lane runner that did would be one
+// import away from the same blind reader.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJson } from '../core/fs-utils.js';
+import { STATE_MIGRATIONS } from './registry.js';
+/** Frozen copy of the generated-profile-id shape (core/profiles/manifest.ts),
+ *  so enumeration matches `listProfiles()`: a hand-made directory crtr can
+ *  never resolve is skipped here too, rather than failing the whole run. */
+const ID_SHAPE = /^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/;
+export function runProfileManifestMigrations(profilesRoot, opts) {
+    const migrations = (opts.migrations ?? STATE_MIGRATIONS).filter((m) => m.lane === 'profile-manifest');
+    const result = { profiles: 0, applied: [], snapshots: [], skipped: [] };
+    if (!existsSync(profilesRoot))
+        return result;
+    for (const dirent of readdirSync(profilesRoot, { withFileTypes: true })) {
+        if (!dirent.isDirectory())
+            continue;
+        const profileId = dirent.name;
+        if (!ID_SHAPE.test(profileId))
+            continue;
+        const path = join(profilesRoot, profileId, 'profile.json');
+        if (!existsSync(path))
+            continue;
+        result.profiles += 1;
+        opts.withLock(profileId, () => {
+            let raw;
+            try {
+                const parsed = JSON.parse(readFileSync(path, 'utf8'));
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                    throw new Error('manifest is not a JSON object');
+                }
+                raw = parsed;
+            }
+            catch (e) {
+                result.skipped.push({ profileId, path, error: (e instanceof Error ? e.message : String(e)).split('\n')[0] });
+                return;
+            }
+            let current = raw;
+            let changed = false;
+            for (const migration of migrations) {
+                const next = migration.apply({ profileId, path, raw: current });
+                if (next === null)
+                    continue;
+                current = next;
+                changed = true;
+                result.applied.push({ profileId, path, migration: migration.description });
+            }
+            if (changed && opts.dryRun !== true)
+                atomicWriteJson(path, current);
+            // Every migration guarantees a current manifest or throws, so the folded
+            // record is the post-migration contract by construction.
+            result.snapshots.push({ profileId, path, manifest: current });
+        });
+    }
+    return result;
+}

package/dist/migrations/registry.js

@@ -3,10 +3,11 @@
 //
 // Authoring contract (each migration is one file, `NNN-<desc>.ts`, appended
 // here in order):
-//   • Idempotent. A convergent migration re-runs on every `crtr sys migrate`,
-//     so applying it to an already-migrated store must plan zero changes. A
-//     journaled migration runs once per database via user_version, but its
-//     body must still tolerate a crash-resume re-run of any filesystem work.
+//   • Idempotent. A convergent or profile-manifest migration re-runs on every
+//     `crtr sys migrate`, so applying it to already-migrated state must plan
+//     zero changes. A journaled migration runs once per database via
+//     user_version, but its body must still tolerate a crash-resume re-run of
+//     any filesystem work.
 //   • Journaled filesystem steps are crash-resumable: fs writes happen outside
 //     the db transaction, so a step interrupted mid-fs-work must complete
 //     (never corrupt) when the chain re-runs it.
@@ -16,4 +17,8 @@
 //     This keeps the registry legal in every CLI leaf's import graph (the
 //     build's V-1 gate).
 import { surfacesFrontmatterMigration } from './001-surfaces-frontmatter.js';
-export const STATE_MIGRATIONS = [surfacesFrontmatterMigration];
+import { profileProjectMemoryMigration } from './002-profile-project-memory.js';
+export const STATE_MIGRATIONS = [
+    surfacesFrontmatterMigration,
+    profileProjectMemoryMigration,
+];

package/dist/migrations/types.d.ts

@@ -1,4 +1,5 @@
 import type { DatabaseSync } from 'node:sqlite';
+import type { ProfileManifest } from '../types.js';
 export interface JournaledMigration {
     lane: 'journaled';
     description: string;
@@ -19,7 +20,33 @@ export interface ConvergentMigration {
      *  runner filters no-op changes and performs the writes. */
     apply(store: StoreSnapshot, context?: ConvergentMigrationContext): DocChange[];
 }
-export type StateMigration = JournaledMigration | ConvergentMigration;
+/** One stored `profile.json` handed to the profile-manifest lane. */
+export interface ProfileManifestInput {
+    /** The immediate directory name under the profiles root. The only root
+     *  classifier a migration may key on — a manifest `name` is mutable. */
+    profileId: string;
+    /** Absolute path to the `profile.json`. */
+    path: string;
+    /** Parsed JSON exactly as stored, historical shapes included. */
+    raw: Record<string, unknown>;
+}
+export interface ProfileManifestMigration {
+    lane: 'profile-manifest';
+    description: string;
+    /** Pure planning: the full replacement record, or null when this manifest is
+     *  already current. A structure the migration cannot convert THROWS — the
+     *  run fails rather than persisting a guessed value. */
+    apply(input: ProfileManifestInput): Record<string, unknown> | null;
+}
+export type StateMigration = JournaledMigration | ConvergentMigration | ProfileManifestMigration;
+/** One profile's manifest after every profile-manifest migration folded —
+ *  the bytes on disk after a write run, and the bytes a write run WOULD have
+ *  produced under `--dry-run`. */
+export interface ProfileManifestSnapshot {
+    profileId: string;
+    path: string;
+    manifest: ProfileManifest;
+}
 /** One parsed markdown doc in a store snapshot. */
 export interface StoreDoc {
     /** Absolute file path. */

package/dist/migrations/types.js

@@ -1,11 +1,17 @@
-// State-migration shapes. Two lanes, split by which store owns the state:
+// State-migration shapes. Three lanes, split by which store owns the state:
 //
-//   journaled  — canvas-db state. Runs inside the db's ordered migration chain
-//                (core/canvas/db.ts appends these to MIGRATIONS), so each step
-//                gets the chain's BEGIN IMMEDIATE/COMMIT + user_version gating
-//                and runs exactly once per database.
-//   convergent — on-disk memory documents. No journal exists over a user's
-//                stores (files appear, sync in, get hand-edited), so these
-//                CONVERGE instead: every run re-scans and rewrites whatever
-//                still matches the old shape. `crtr sys migrate` is the runner.
+//   journaled        — canvas-db state. Runs inside the db's ordered migration
+//                      chain (core/canvas/db.ts appends these to MIGRATIONS), so
+//                      each step gets the chain's BEGIN IMMEDIATE/COMMIT +
+//                      user_version gating and runs exactly once per database.
+//   convergent       — on-disk memory documents. No journal exists over a user's
+//                      stores (files appear, sync in, get hand-edited), so these
+//                      CONVERGE instead: every run re-scans and rewrites whatever
+//                      still matches the old shape.
+//   profile-manifest — `~/.crouter/profiles/<id>/profile.json`. Converges like
+//                      the document lane, but each manifest folds under the same
+//                      per-profile lock add/remove take, and a structure the
+//                      migration cannot convert throws instead of being guessed.
+//
+// `crtr sys migrate` runs both on-disk lanes, profile manifests first.
 export {};

package/dist/pi-extensions/__tests__/canvas-structured-output.test.js

@@ -26,7 +26,7 @@ after(() => {
     else
         process.env['CRTR_NODE_ID'] = previous.nodeId;
 });
-test('optional submit fields remain optional through a strict provider tool schema', () => {
+test('strict provider schema stays portable while original constraints validate submit', async () => {
     home = mkdtempSync(join(tmpdir(), 'crtr-structured-output-'));
     process.env['CRTR_HOME'] = home;
     process.env['CRTR_NODE_ID'] = 'structured-output-test';
@@ -44,8 +44,14 @@ test('optional submit fields remain optional through a strict provider tool sche
                 },
                 required: ['summary'],
             },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                minItems: 2,
+                maxItems: 5,
+            },
         },
-        required: ['status', 'verification', 'details'],
+        required: ['status', 'verification', 'details', 'tags'],
     };
     writeOutputSchema('structured-output-test', 'oneoff', schema);
     let definition;
@@ -57,15 +63,26 @@ test('optional submit fields remain optional through a strict provider tool sche
     });
     assert.ok(definition, 'the pending request registers submit');
     const parameters = definition['parameters'];
-    assert.deepEqual(parameters.required, ['status', 'commit', 'verification', 'blocker', 'details']);
+    assert.deepEqual(parameters.required, ['status', 'commit', 'verification', 'blocker', 'details', 'tags']);
     assert.deepEqual(parameters.properties.commit, { anyOf: [{ type: 'string' }, { type: 'null' }] });
     assert.deepEqual(parameters.properties.blocker, { anyOf: [{ type: 'string' }, { type: 'null' }] });
     assert.equal(parameters.additionalProperties, false);
     assert.equal(parameters.properties.details.additionalProperties, false);
-    assert.deepEqual(schema.required, ['status', 'verification', 'details'], 'the stored request keeps its original optionality');
+    assert.equal(parameters.properties.tags['minItems'], undefined);
+    assert.equal(parameters.properties.tags['maxItems'], undefined);
+    assert.match(parameters.properties.tags['description'], /minItems: 2/);
+    assert.match(parameters.properties.tags['description'], /maxItems: 5/);
+    assert.deepEqual(schema.required, ['status', 'verification', 'details', 'tags'], 'the stored request keeps its original constraints');
     const [providerTool] = convertResponsesTools([definition], {
         strict: false,
         supportsStrictMode: true,
     });
     assert.equal(providerTool['strict'], true);
+    const execute = definition['execute'];
+    await assert.rejects(execute('call', {
+        status: 'done',
+        verification: 'verified',
+        details: { summary: 'ok' },
+        tags: ['only-one'],
+    }, new AbortController().signal), /must not have fewer than 2 items/);
 });

package/dist/pi-extensions/canvas-structured-output.js

@@ -5,6 +5,7 @@
 // stop-guard will reprompt the node with an explicit error about the invalid file.
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { validateToolArguments } from '@earendil-works/pi-ai';
 import { emitEvent } from '../core/events/emit.js';
 import { publishBrokerReport } from '../core/runtime/broker/daemon-ops.js';
 import { outputResultPath, readOutputRequest, removeOutputSchema, } from '../core/runtime/structured-output.js';
@@ -30,6 +31,85 @@ function retireTool(pi) {
         /* best-effort; the execute handler is inert when no schema file exists */
     }
 }
+const STRICT_STRING_FORMATS = new Set([
+    'date-time', 'time', 'date', 'duration', 'email', 'hostname', 'uri', 'ipv4', 'ipv6', 'uuid',
+]);
+// Provider strict modes accept a structural subset; omitted constraints stay visible in descriptions.
+function providerStrictSchema(schema) {
+    const transform = (value) => {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return value;
+        const source = { ...value };
+        const take = (key) => {
+            const child = source[key];
+            delete source[key];
+            return child;
+        };
+        const transformed = {};
+        const ref = take('$ref');
+        if (ref !== undefined)
+            return { $ref: ref };
+        const defs = take('$defs');
+        if (defs !== null && typeof defs === 'object' && !Array.isArray(defs)) {
+            transformed['$defs'] = Object.fromEntries(Object.entries(defs).map(([name, definition]) => [name, transform(definition)]));
+        }
+        const type = take('type');
+        const anyOf = take('anyOf');
+        const oneOf = take('oneOf');
+        const allOf = take('allOf');
+        if (Array.isArray(anyOf))
+            transformed['anyOf'] = anyOf.map(transform);
+        else if (Array.isArray(oneOf))
+            transformed['anyOf'] = oneOf.map(transform);
+        else if (Array.isArray(allOf))
+            transformed['allOf'] = allOf.map(transform);
+        else if (type !== undefined)
+            transformed['type'] = type;
+        else
+            return value;
+        const description = take('description');
+        if (description !== undefined)
+            transformed['description'] = description;
+        const title = take('title');
+        if (title !== undefined)
+            transformed['title'] = title;
+        if (type === 'object') {
+            const properties = take('properties');
+            transformed['properties'] = properties !== null && typeof properties === 'object' && !Array.isArray(properties)
+                ? Object.fromEntries(Object.entries(properties).map(([name, property]) => [name, transform(property)]))
+                : {};
+            take('additionalProperties');
+            transformed['additionalProperties'] = false;
+            const required = take('required');
+            if (required !== undefined)
+                transformed['required'] = required;
+        }
+        else if (type === 'string') {
+            const format = take('format');
+            if (typeof format === 'string' && STRICT_STRING_FORMATS.has(format))
+                transformed['format'] = format;
+            else if (format !== undefined)
+                source['format'] = format;
+        }
+        else if (type === 'array') {
+            const items = take('items');
+            if (items !== undefined)
+                transformed['items'] = transform(items);
+            const minItems = take('minItems');
+            if (minItems === 0 || minItems === 1)
+                transformed['minItems'] = minItems;
+            else if (minItems !== undefined)
+                source['minItems'] = minItems;
+        }
+        if (Object.keys(source).length > 0) {
+            const existing = typeof transformed['description'] === 'string' ? transformed['description'] : '';
+            const constraints = `{${Object.entries(source).map(([key, child]) => `${key}: ${JSON.stringify(child)}`).join(', ')}}`;
+            transformed['description'] = existing === '' ? constraints : `${existing}\n\n${constraints}`;
+        }
+        return transformed;
+    };
+    return transform(schema);
+}
 function strictToolSchema(schema) {
     const transform = (value) => {
         if (Array.isArray(value))
@@ -61,7 +141,10 @@ function strictToolSchema(schema) {
         transformed['required'] = Object.keys(properties);
         return transformed;
     };
-    return transform(schema);
+    return providerStrictSchema(transform(schema));
+}
+function validateResult(value, schema) {
+    return validateToolArguments({ name: 'submit', description: '', parameters: schema }, { type: 'toolCall', id: 'structured-output', name: 'submit', arguments: value });
 }
 function omitStrictNulls(value, schema) {
     if (value === null || typeof value !== 'object' || Array.isArray(value) || schema === null || typeof schema !== 'object' || Array.isArray(schema))
@@ -156,7 +239,7 @@ export function registerCanvasStructuredOutput(pi) {
                             details: { submitted: false, reason: 'schema_replaced' },
                         };
                     }
-                    const result = omitStrictNulls(params, current.request.schema);
+                    const result = validateResult(omitStrictNulls(params, current.request.schema), current.request.schema);
                     const resultPath = outputResultPath(nodeId);
                     const json = JSON.stringify(result, null, 2);
                     mkdirSync(dirname(resultPath), { recursive: true });

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { BindingId } from './core/keybindings/catalog.js';
+import type { ProfileProject } from './api/dto/profiles.js';
 export type Scope = 'user' | 'project' | 'builtin';
 export declare const ExitCode: {
     readonly SUCCESS: 0;
@@ -94,6 +95,13 @@ export interface PluginManifest {
      *  crtr owns parse/help/render/errors and direct-spawns the plugin's one
      *  executable per leaf invocation. See `src/core/command-plugins/`. */
     commands?: string;
+    /** Plugin-root-relative path to a declarative hook manifest (`hooks.json`).
+     *  Must be declared together with `hookExecutable`; hooks are trusted local
+     *  code and are unavailable to endpoint archive plugins. */
+    hooks?: string;
+    /** Plugin-root-relative executable that dispatches declarations in `hooks`.
+     *  Must be a regular file with a POSIX executable permission bit. */
+    hookExecutable?: string;
     /** Bare-callable executables this plugin ships, keyed by the bare command
      *  name a node's bash sees. Each value is a PLUGIN-ROOT-relative path to a
      *  regular executable file when the effective set resolves. These are trusted
@@ -223,6 +231,10 @@ export interface PageComponentRegistration {
     /** A display-only product slot contributes no page response. */
     display?: boolean;
 }
+export interface HumanActionConfig {
+    argv: string[];
+    cwd: string;
+}
 /** The normalized product component catalog used to validate page slots. */
 export type ProductPageComponents = readonly PageComponentRegistration[];
 export interface ScopeConfig {
@@ -336,6 +348,10 @@ export interface ScopeConfig {
      *  the trusted local binary is materialized into the PATH-prepended shim dir
      *  by `core/runtime/bin-contributions.ts`. */
     bin?: Record<string, string>;
+    /** Named completion commands. Project scopes nearest to a creator's cwd
+     *  outrank farther project scopes, then user scope; plugins and profiles do
+     *  not contribute. Paths resolve against the declaring scope's authoring root. */
+    humanActions: Record<string, HumanActionConfig>;
 }
 /** One remote canvas target: where to relay-attach and how to find its
  *  bearer token. The token itself is NEVER stored here — only a ref into the
@@ -411,9 +427,9 @@ export interface InstalledMarketplace {
 }
 /** The on-disk manifest at `~/.crouter/profiles/<slug>-<id>/profile.json`
  *  (spec §2.1). A profile is an agent identity defined at the user root: it
- *  names N project directories and owns its own `memory/` store. `projects`
- *  are absolute, real-path-resolved directories in manifest order — the
- *  pointer set `findProjectScopeRoots` walks, after the node's own
+ *  names N project directories and owns its own `memory/` store. Project
+ *  `path`s are absolute, real-path-resolved directories in manifest order —
+ *  the pointer set `findProjectScopeRoots` walks, after the node's own
  *  cwd. `name` is the mutable display name (and the gateable `profile` subject
  *  field); `<slug>-<id>` in the directory name is the stable id and
  *  never changes on rename. See `src/core/profiles/manifest.ts` for every
@@ -422,10 +438,11 @@ export interface InstalledMarketplace {
 export interface ProfileManifest {
     schema_version: number;
     name: string;
-    projects: string[];
+    projects: ProfileProject[];
     /** The directory nodes under this profile are pinned to (see
-     *  `profileHome`). Normalized on read to the first project when the manifest
-     *  carries none, so a profile written before homes existed still has one. */
+     *  `profileHome`). Normalized on read to the first project's path when the
+     *  manifest carries none, so a profile written before homes existed still
+     *  has one. */
     home: string | null;
     /** ISO timestamp while the profile is inert; null (or absent on older manifests) means active. */
     paused_at: string | null;

package/dist/types.js

@@ -103,6 +103,7 @@ export function defaultScopeConfig() {
         remoteCanvas: defaultRemoteCanvasConfig(),
         spawnEnv: { allow: [] },
         bin: {},
+        humanActions: {},
     };
 }
 /** No remote canvas targets are configured out of the box — every one is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.220",
+  "version": "0.3.222",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.220",
+  "version": "0.3.222",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.220",
+      "version": "0.3.222",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/builtin-memory/00-runtime-base.md

@@ -1,55 +0,0 @@
----
-kind: preference
-when-and-why-to-read: When any node boots, this preference should be read so the node can participate safely in the live graph without losing work, user decisions, or the ability to resume.
-rationale: >-
-  The living-document paragraph ("Living documents") exists because agents default to appending — plans kept old+new versions side by side, answered Q&A sections stayed behind after the answer was folded in, findings docs grew contradicted layers (observed by Silas, 2026-07-08). The stale trail isn't neutral history; it keeps steering the next reader (the pink-elephant effect), measurably dulling the agent that consumes the doc. Orchestrators already had this discipline in the kernel; base workers, who author most artifacts, had nothing.
-
-  "Say what actually happens" exists because an approval request called a root a person had created an "attended root" — an invented category with no referent in the product, which forced Silas to halt the decision and ask what the term meant (2026-07-28). Agents coin taxonomies to compress a distinction; the reader pays by decoding a word that names nothing real.
-
-  "Waiting is a way to end a turn" lived in its own ungated all-node doc until 2026-07-28. Same gate, same audience, never independently readable — so the split bought no routing and cost a stub cross-reference in this file pointing at a section spliced a few hundred tokens later. Split it back out only if it ever needs a gate of its own.
-
-  The Mermaid line exists because the viewer's inline diagram affordance is otherwise invisible to an agent working from ordinary Markdown defaults.
-
-  An "Identity" section is deliberately absent, and the artifacts section carries no paths. The bearings message already states the node id, the context dir's absolute path, the `$CRTR_CONTEXT_DIR` env var, the address-by-absolute-path rule, the bare-`context/` trap, and the cwd — so a layer copy was pure duplication. It was also the only per-node text in the whole system-prompt block: the preference render interpolates `$CRTR_NODE_ID`/`$CRTR_CONTEXT_DIR`, which made every node's cached prompt prefix globally unique. Keep node-specific values out of this layer; bearings is where they belong.
-
-  Yield lives here because every node yields regardless of mode; promotion does not, because only the mode layers own that boundary — 04-base-worker for when a base node should promote, the kernel for how an orchestrator uses promotion — so restating it here duplicated the base-worker text for an audience that includes nodes it does not apply to.
-lint-ignore: length
-surfaces:
-  - on: boot
-    at: content
----
-
-You are a **node** in a live agent graph (the crtr canvas). This section is your operating protocol — it is true for every node regardless of role.
-
-## Artifacts
-An artifact you write to your context dir is shared by pointer: whatever carries it — a report, a reply, an ask — names its absolute path, never the full substance pasted in.
-
-## Living documents
-Every doc you keep — artifact, plan, findings, memory — is a living statement of what is true *now*, never a log of how it got that way. When something changes, rewrite the doc in place as if writing it fresh: fold an answer into the section it settles and delete the question, replace superseded findings, and never leave an old version beside the new one. Superseded text keeps steering whoever reads it — an audit trail in a working doc costs the next reader the very attention the doc exists to save.
-
-## Say what actually happens
-Everything you write — replies, reports, approval requests, artifacts, memory docs, comments — describes systems in concrete, existing product terms: the real command, the real event, the actual cause. When you need shorthand for a distinction, spell it out ("a root created by a person" vs "a root created by a cron job") instead of coining a label ("attended root"); an invented term makes the reader stop and decode a category the system does not actually have.
-
-## When blocked, want feedback, or need the user
-Don't guess at a decision a person should make. Run `crtr human send -h` and put the question to the user through the crouter human inbox, because a question posed as prose in a reply or report pings nobody while an ask lands on their screen and pushes the answer back to your inbox. An ask blocks on a person, so spend them well: resolve what the code, a tool, or a delegate can settle, and engage when intent is genuinely ambiguous, when approaches carry real tradeoffs, when scope or direction changes, when an action is irreversible or high-risk, or when finished work needs sign-off — a whole goal costs a handful of asks, not a stream.
-
-## When crtr itself misbehaves
-A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
-
-## Yield for a fresh window
-When your context is filling but the mandate isn't done, yield: you revive fresh as the same node with the same mandate, carrying a note to your future self.
-
-    crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
-
-Never yield carrying an unasked question: put anything you're still wondering for the user through `crtr human send` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.
-
-## Mermaid diagrams
-When visual structure would land faster than prose, use a Mermaid fence; the user's terminal viewer renders it inline.
-
-## Waiting is a way to end a turn
-
-When your goal is sound but your next step is blocked on something that has not happened yet — a child's report, the user, a CI run, tomorrow morning — you are **waiting**. Waiting is free: you end your turn, hold no window, and burn no compute, and the runtime brings you back the instant the thing you wait on happens.
-
-- **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
-- **For waits the runtime already knows — a child's report or the reply to your own human page — just stop.** Go dormant; the runtime wakes you when it lands. There is nothing to poll or verify, and a deadline set to "check in" on a delegate is unnecessary — children auto-wake you when they push.
-- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). Run `crtr cron -h` to schedule the matching bash action, or `crtr node wait deadline -h` when the desired contract is an inbox-versus-deadline race.