@crouton-kit/crouter 0.3.43 → 0.3.45

package/dist/commands/memory/delete.d.ts

@@ -0,0 +1 @@
+export declare const deleteLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/delete.js

@@ -0,0 +1,77 @@
+import { existsSync, readdirSync, rmSync, rmdirSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound, usage } from '../../core/errors.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { MEMORY_SCOPES } from './shared.js';
+/** Remove the file's now-empty parent directories up to (never including) the
+ *  scope's `memory/` root, so deleting the last doc under an `area/` prefix
+ *  does not orphan an empty directory. Stops at the first non-empty ancestor.
+ *  `memoryRoot` is derived by walking up one dirname per name segment: a doc
+ *  named `a/b` sits at `<root>/a/b.md`, so its root is two dirnames above. */
+function pruneEmptyParents(filePath, nameSegments) {
+    let memoryRoot = filePath;
+    for (let i = 0; i < nameSegments; i += 1)
+        memoryRoot = dirname(memoryRoot);
+    let dir = dirname(filePath);
+    while (dir !== memoryRoot && dir.startsWith(memoryRoot) && existsSync(dir) && readdirSync(dir).length === 0) {
+        rmdirSync(dir);
+        dir = dirname(dir);
+    }
+}
+export const deleteLeaf = defineLeaf({
+    name: 'delete',
+    description: 'delete a memory document by name',
+    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the name exactly as `read` does (project stack > profile > user precedence, leaf-name fallback) and removes that file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`) — and refuses an ambiguous leaf name rather than guessing which doc to destroy; pass the full `area/topic` name or `--scope` to pin one.',
+    help: {
+        name: 'memory delete',
+        summary: 'resolve a path-derived name and remove that document from its scope store',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: precedence project stack > profile > user, with leaf-name fallback. A leaf that maps to genuinely different docs across scopes is rejected as ambiguous — pass the full name or --scope to disambiguate. May be scope-prefixed (`user/topic`) to pin the store directly.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before deleting. Use it to disambiguate a leaf name present at multiple scopes, or to assert which store you mean. builtin is not a choice — builtin docs ship with the package and cannot be deleted.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Path-derived name of the deleted document.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: user, project, or profile.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
+            { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success — the file was removed. A missing document fails with not_found instead.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command — browse what remains.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Permanently removes memory/<name>.md from the resolved scope store, and prunes any parent directories it leaves empty. Irreversible.',
+        ],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const scopeArg = input['scope'];
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw, scopeArg !== undefined ? { scope: scopeArg } : {});
+        }
+        catch (e) {
+            if (e instanceof CrtrError && e.code === 'not_found') {
+                throw notFound(`memory document not found: ${nameRaw}`, {
+                    memory: nameRaw,
+                    next: 'Run `crtr memory find <query>` to locate it, or `crtr memory list` to browse the inventory. If it exists at another scope, pass --scope.',
+                });
+            }
+            throw e; // ambiguous / usage propagate with their own recovery guidance
+        }
+        if (doc.plugin !== undefined) {
+            throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" — it is not a scope doc and cannot be deleted here. Manage plugin docs with \`crtr pkg\`. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, plugin: doc.plugin });
+        }
+        if (doc.scope === 'builtin') {
+            throw usage(`${doc.name} is a builtin document shipped with the package (read-only) — it cannot be deleted. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
+        }
+        rmSync(doc.path);
+        pruneEmptyParents(resolvePath(doc.path), doc.name.split('/').length);
+        return {
+            name: doc.name,
+            scope: doc.scope,
+            path: doc.path,
+            deleted: true,
+            follow_up: `Removed. Browse what remains with \`crtr memory list\`.`,
+        };
+    },
+});

package/dist/commands/memory/lint.js

@@ -68,6 +68,16 @@ export function lintSubstrateSchema(fm) {
     if (fm['file-read-visibility'] === 'none' && (appliesTo !== undefined || readWhen !== undefined)) {
         return 'dead on-read trigger: applies-to/read-when is set but file-read-visibility is `none` — raise the rung or drop the trigger';
     }
+    const slash = fm.slash;
+    if (slash !== undefined && typeof slash !== 'boolean') {
+        return `invalid slash: ${JSON.stringify(slash)} (expected a boolean)`;
+    }
+    // rationale (maintainer-facing gap this doc closes) is optional everywhere —
+    // no nagging when absent, just a type check when present.
+    const rationale = fm.rationale;
+    if (rationale !== undefined && typeof rationale !== 'string') {
+        return `invalid rationale: ${JSON.stringify(rationale)} (expected a string)`;
+    }
     return null;
 }
 /** Strict-parse one file; push a finding on a YAML error, then run the

package/dist/commands/memory/shared.js

@@ -158,6 +158,7 @@ const FRONTMATTER_ORDER = [
     'gate',
     'applies-to',
     'read-when',
+    'rationale',
     'origin',
 ];
 /** Provenance for a doc at the moment it is created: when, where, and which

package/dist/commands/memory/write.js

@@ -16,7 +16,8 @@ export const writeLeaf = defineLeaf({
             'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ (`--dir <project-dir>` targets it exactly, from anywhere) and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can decide from that one line alone whether to spend the read. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
-            'Find before write. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Validate after authoring.',
+            'Find before write. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Validate after authoring.\n\n' +
+            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. The bar: if the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into, so a merely-plausible-sounding reason is not worth recording. It is maintainer-facing only and NEVER ships in a delivered surface (boot render, on-read injection, `memory read` content) — it lives in frontmatter, visible only in the raw file or `memory read --frontmatter`. Omit it when you have no such gap to record; omitting the flag on an update always preserves whatever rationale already exists.',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity: one segment, or several joined with `/` to nest the document under a directory and group it with related docs → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
@@ -27,6 +28,8 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
             { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
             { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
+            { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
+            { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only in the raw file or `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },
             { 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.' },
             { 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`; ignored for any other --scope.' },
@@ -99,6 +102,9 @@ export const writeLeaf = defineLeaf({
         if (input['readWhen'] !== undefined) {
             frontmatter['read-when'] = coerceReadWhen(input['readWhen']);
         }
+        if (input['slash'] === true)
+            frontmatter['slash'] = true;
+        setIf('rationale', input['rationale']);
         writeText(path, serializeMemoryDoc(frontmatter, body));
         return {
             name,

package/dist/commands/memory.js

@@ -5,6 +5,7 @@ import { listLeaf } from './memory/list.js';
 import { readLeaf } from './memory/read.js';
 import { findLeaf } from './memory/find.js';
 import { writeLeaf } from './memory/write.js';
+import { deleteLeaf } from './memory/delete.js';
 import { originLeaf } from './memory/origin.js';
 import { lintLeaf } from './memory/lint.js';
 export function registerMemory() {
@@ -18,8 +19,8 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin — use it for new docs and frontmatter changes; for a quick body tweak, edit the `path` every leaf emits directly. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. `origin` derefs a doc back to its provenance — the node, conversation, and project that created it (the runtime stamps an `origin` block at write time; this reads it and resolves the node pointer to its live session + context dir). A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
+            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin — use it for new docs and frontmatter changes; for a quick body tweak, edit the `path` every leaf emits directly. `delete` removes a document by name (resolved as `read` resolves it) — the sanctioned way to retire one instead of rm-ing the markdown off disk. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. `origin` derefs a doc back to its provenance — the node, conversation, and project that created it (the runtime stamps an `origin` block at write time; this reads it and resolves the node pointer to its live session + context dir). A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
         },
-        children: [listLeaf, readLeaf, findLeaf, writeLeaf, originLeaf, lintLeaf],
+        children: [listLeaf, readLeaf, findLeaf, writeLeaf, deleteLeaf, originLeaf, lintLeaf],
     });
 }

package/dist/commands/node.js

@@ -13,6 +13,7 @@ import { spawnChild } from '../core/runtime/spawn.js';
 import { promote, requestYield } from '../core/runtime/promote.js';
 import { writeYieldMessage, readGoal } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
+import { parseOutputSchemaValue, writeOutputSchema } from '../core/runtime/structured-output.js';
 import { newNodeId } from '../core/runtime/nodes.js';
 import { readRoadmap, hasRoadmap, seedRoadmap } from '../core/runtime/roadmap.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
@@ -129,8 +130,9 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with). Mutually exclusive with --worktree.' },
             { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on `origin/main`; the child\'s cwd is pinned there, and it lands the work serially onto origin/main later with `crtr worktree close`. Mutually exclusive with --root.' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
-            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
+            { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Override the model the node runs on: exact `provider/id` (e.g. openai-codex/gpt-5.5), a `provider/tier` (anthropic|openai + ultra|strong|medium|light, e.g. openai/ultra — pin a specific model family, useful for spawning cross-family children), a bare capability TIER (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku). Must resolve to a concrete model OFFLINE — unlike `node config --model`, no live broker exists yet at spawn to free-text substring-search a registry. Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (root has none, so an uninherited child has none either). --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
+            { kind: 'flag', name: 'output-schema', type: 'string', required: false, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. The spawned node gets a `submit` tool shaped by this schema, must call it to finish, and the submitted JSON is written to the final report and context/result.json. Rejected with trigger flags in this version.' },
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'DEFER the birth to a one-shot clock trigger at this future time instead of spawning now — a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", host-local or in --tz). Required unless --every is given (the cadence then sets the first fire). Mutually exclusive with --when.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'SPAWN-CRON: re-birth a fresh node on this cadence — a duration ("6h","30m") or a 5-field cron / @alias ("0 9 * * *","@daily"). Combine with --at to anchor the first fire, then recur normally. Min cadence 60s. With --when, this instead sets the PREDICATE EVALUATION cadence (required), not a repeating birth.' },
             { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Arm a daemon-evaluated bash predicate instead of a clock trigger: exit 0 births the node once, non-zero leaves it armed for the next evaluation. Requires --every (eval cadence) and --timeout (wall-clock bound). Mutually exclusive with --at.' },
@@ -155,7 +157,7 @@ const nodeNew = defineLeaf({
         dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
         outputKind: 'object',
         effects: [
-            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on origin/main; the child closes it later with `crtr worktree close` before finishing. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
+            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on origin/main; the child closes it later with `crtr worktree close` before finishing. With --output-schema: writes nodes/<id>/output-schema.json in terminal mode; the node must call submit, which writes context/result.json and pushes final. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
             'Armed (--at/--every/--when): inserts one detached `new`/`node_birth` triggers row (node_id NULL, owner=you, parent/cwd resolved now); NO node and NO window exist until fire time. The daemon spawns from the stored recipe at fire time, re-deriving the launch spec live.',
         ],
     },
@@ -172,8 +174,18 @@ const nodeNew = defineLeaf({
         const root = input['root'] === true;
         const worktree = input['worktree'] === true;
         const forkFrom = input['forkFrom'];
-        const model = input['model'];
+        const modelSpec = input['model']?.trim();
+        if (modelSpec !== undefined) {
+            if (modelSpec === '') {
+                throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Pass a `provider/id`, a `provider/tier` (e.g. openai/ultra), a tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku).' });
+            }
+            if (!normalizeModel(modelSpec).includes('/')) {
+                throw new InputError({ error: 'unresolvable_model', message: `'${modelSpec}' does not resolve to a concrete model`, field: 'model', next: 'Pass an exact `provider/id` (e.g. openai-codex/gpt-5.5), a `provider/tier` (e.g. openai/ultra), a tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku) — a live-broker substring search (like `node config --model`) is not available at spawn.' });
+            }
+        }
+        const model = modelSpec;
         const profile = input['profile'];
+        const outputSchema = parseOutputSchemaValue(input['outputSchema']);
         const at = input['at']?.trim();
         const every = input['every']?.trim();
         const whenRaw = input['when'];
@@ -194,9 +206,14 @@ const nodeNew = defineLeaf({
         if (root && worktree) {
             throw new InputError({ error: 'worktree_root_conflict', message: '--worktree is mutually exclusive with --root', field: 'worktree', next: 'Drop either --root or --worktree.' });
         }
+        if (outputSchema !== null && triggered) {
+            throw new InputError({ error: 'output_schema_trigger_unsupported', message: '--output-schema is not supported with --at, --every, or --when in this version', field: 'output-schema', next: 'Spawn immediately with --output-schema, or drop --output-schema for the triggered spawn.' });
+        }
         if (!triggered) {
             try {
                 const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, worktree, forkFrom, model, profile });
+                if (outputSchema !== null)
+                    writeOutputSchema(res.node.node_id, 'terminal', outputSchema);
                 return {
                     node_id: res.node.node_id,
                     name: res.node.name,
@@ -712,7 +729,12 @@ const nodeConfig = defineLeaf({
                 throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, next: 'List nodes with `crtr node inspect list`.' });
             if (isBrokerLive(meta)) {
                 try {
-                    resolved = await setModelLive(nodeId, modelSpec);
+                    // Normalize tiers/aliases (opus, strong, anthropic/strong, …) through the
+                    // config ladder before the broker sees them — a bare alias sent raw falls
+                    // into the broker's registry substring search, where `opus` resolves to the
+                    // deprecated claude-3-opus-20240229 on catalog order. Concrete `provider/id`
+                    // specs and free-text substrings pass through unchanged.
+                    resolved = await setModelLive(nodeId, normalizeModel(modelSpec));
                 }
                 catch (err) {
                     throw new InputError({ error: 'switch_failed', message: `live model switch failed: ${err instanceof Error ? err.message : String(err)}`, next: 'Check the spec resolves (`provider/id`, tier, alias, or a substring of a registered model).' });
@@ -1016,11 +1038,12 @@ const nodeMsg = defineLeaf({
         name: 'node msg',
         summary: 'message a node now, or arm a trigger (clock or predicate) that messages/revives it later. No trigger flag → immediate inbox delivery (or immediate fresh revive with --fresh). --at/--every → clock trigger. --self --until → self-only deadline: fires whichever comes first, an inbox message or this time, and that outcome is what should change your next action. --when → daemon-evaluated predicate, fires once on exit 0',
         params: [
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Message body. Positional or stdin. Required for a plain or clock-triggered message and for --until. Forbidden with --fresh. Optional with --when — if omitted, the predicate\'s captured stdout becomes the body when it fires.' },
+            { kind: 'stdin', name: 'body', required: false, constraint: 'Message body. Positional or stdin. Required for a plain or clock-triggered message and for --until, unless --output-schema is present (then a default one-off structured-output request body is generated). Forbidden with --fresh. Optional with --when — if omitted, the predicate\'s captured stdout becomes the body when it fires.' },
             { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to/--self is required.' },
             { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node (CRTR_NODE_ID). Exactly one of --to/--self is required. Required for --until.' },
-            { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, constraint: 'Inbox delivery urgency: critical = interrupt + new turn; urgent = steer mid-turn; normal = follow-up; deferred = read on next cycle. Defaults to normal when omitted. Valid for a plain or --when inbox message (immediate or clock-triggered); forbidden with --fresh or --until (--until is always urgent).' },
-            { kind: 'flag', name: 'fresh', type: 'bool', required: false, constraint: 'Fresh-revive the target instead of delivering a message: no inbox entry, just a clean revive (resume:false). Valid alone (revives now) or with --at/--every (arms a clock-triggered fresh revive). Forbidden with a body, --tier, --until, or --when. Rejected if the target has no goal/roadmap on disk (would resume amnesiac).' },
+            { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, constraint: 'Inbox delivery urgency: critical = interrupt + new turn; urgent = steer mid-turn; normal = follow-up; deferred = read on next cycle. Defaults to normal when omitted. Valid for a plain or --when inbox message (immediate or clock-triggered); forbidden with --fresh or --until (--until is always urgent). With --output-schema, deferred is rejected because the target must wake to answer the one-off request.' },
+            { kind: 'flag', name: 'fresh', type: 'bool', required: false, constraint: 'Fresh-revive the target instead of delivering a message: no inbox entry, just a clean revive (resume:false). Valid alone (revives now) or with --at/--every (arms a clock-triggered fresh revive). Forbidden with a body, --tier, --until, --output-schema, or --when. Rejected if the target has no goal/roadmap on disk (would resume amnesiac).' },
+            { kind: 'flag', name: 'output-schema', type: 'string', required: false, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. Grants or replaces a one-off `submit` tool on the target; the target must submit before it can stop, then the result is written to context/result.json, pushed as an update report, and the tool is retired. Immediate messages only; rejected with trigger flags, --fresh, and --until.' },
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'Arm a one-shot clock trigger at this future time instead of acting now — a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", host-local or in --tz). Required unless --every is given (the cadence then sets the first fire). Mutually exclusive with --when.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Arm a recurring clock trigger on this cadence — a duration ("6h","30m") or a 5-field cron / @alias ("0 9 * * *","@daily"). Combine with --at to anchor the first fire, then recur normally. Min cadence 60s. With --when, this instead sets the PREDICATE EVALUATION cadence (required), not a repeating action.' },
             { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Arm a daemon-evaluated bash predicate instead of a clock trigger: exit 0 fires the message once, non-zero leaves it armed for the next evaluation. Requires --every (eval cadence) and --timeout (wall-clock bound). Mutually exclusive with --at, --fresh, and --until.' },
@@ -1044,7 +1067,7 @@ const nodeMsg = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Immediate inbox_message: appends a message entry to the target inbox.jsonl and best-effort revives the target if dormant.',
+            'Immediate inbox_message: appends a message entry to the target inbox.jsonl and best-effort revives the target if dormant. With --output-schema: also writes nodes/<target>/output-schema.json in oneoff mode before delivery.',
             'Immediate fresh_revive: revives the target now with no inbox entry (resume:false).',
             'Armed (--at/--every/--when/--until): inserts one triggers row; nothing fires/evaluates until the daemon\'s next pass. No pi spawn, no transition — end your turn separately to go dormant.',
             '--until upserts the node\'s single deadline trigger, replacing any prior.',
@@ -1069,6 +1092,7 @@ const nodeMsg = defineLeaf({
         const tz = input['tz'];
         const hasAt = at !== undefined && at !== '';
         const hasEvery = every !== undefined && every !== '';
+        const outputSchema = parseOutputSchemaValue(input['outputSchema']);
         // --- Validation per the approved flag matrix ---
         if (hasUntil && !isSelf) {
             throw new InputError({ error: 'until_self_only', message: '--until is self-only', field: 'until', next: 'Use --self, or drop --until.' });
@@ -1098,6 +1122,12 @@ const nodeMsg = defineLeaf({
         if (hasTz && !hasAt && !hasEvery && !hasUntil) {
             throw new InputError({ error: 'tz_needs_trigger', message: '--tz has no effect without --at, --every, or --until to parse it against', field: 'tz', next: 'Drop --tz, or pass --at/--every/--until.' });
         }
+        if (outputSchema !== null && (hasAt || hasEvery || hasWhen || hasUntil || fresh)) {
+            throw new InputError({ error: 'output_schema_msg_immediate_only', message: '--output-schema on node msg grants an immediate one-off request and cannot combine with --at, --every, --when, --until, or --fresh', field: 'output-schema', next: 'Deliver the one-off request immediately, or drop --output-schema for the trigger/fresh revive.' });
+        }
+        if (outputSchema !== null && tierRaw === 'deferred') {
+            throw new InputError({ error: 'output_schema_deferred_tier', message: '--output-schema cannot combine with --tier deferred because the target must wake and answer the one-off request', field: 'tier', next: 'Use normal, urgent, or critical tier, or drop --output-schema.' });
+        }
         const target = isSelf ? 'self' : targetId;
         // --- Deadline (--until): self-only, one-shot, urgent ---
         if (hasUntil) {
@@ -1265,19 +1295,24 @@ const nodeMsg = defineLeaf({
                 guidance: `Fresh-revived ${isSelf ? 'yourself' : targetId} now — it resumes a clean window re-reading its roadmap/disk.`,
             };
         }
-        if (!hasBody) {
-            throw new InputError({ error: 'empty_body', message: 'a message body is required (or --fresh / --when)', field: 'body', next: 'Pass the message after the target flags or on stdin.' });
+        if (!hasBody && outputSchema === null) {
+            throw new InputError({ error: 'empty_body', message: 'a message body is required (or --fresh / --when / --output-schema)', field: 'body', next: 'Pass the message after the target flags or on stdin, or pass --output-schema to grant a one-off structured-output request.' });
         }
         const targetMeta = getNode(targetId);
         if (targetMeta === null) {
             throw new InputError({ error: 'not_found', message: `no node: ${targetId}`, next: 'List nodes with `crtr node inspect list`.' });
         }
+        if (outputSchema !== null)
+            writeOutputSchema(targetId, 'oneoff', outputSchema);
         const tier = (hasTier ? tierRaw : 'normal');
         const from = process.env['CRTR_NODE_ID'] ?? 'human';
+        const messageBody = hasBody
+            ? body
+            : 'A one-off structured-output request has been granted. Call the `submit` tool with a result matching the requested schema before you stop; after submit succeeds, continue normally.';
         // A body over the preview bound spills to a ref file; appendInbox clips the
         // inline preview and the receiver dereferences the ref for the full text,
         // same as any other report.
-        appendInbox(targetId, { from, tier, kind: 'message', label: body.split('\n')[0].slice(0, 120), data: { body: body } });
+        appendInbox(targetId, { from, tier, kind: 'message', label: messageBody.split('\n')[0].slice(0, 120), data: { body: messageBody } });
         // A direct message wakes any node: if the target has no live window
         // (done/dead/idle-released), revive it so its inbox-watcher delivers this.
         let woke = false;

package/dist/core/__tests__/review-model-floor.test.js

@@ -30,3 +30,19 @@ test('explore remains cheap by default and may explicitly run light', () => {
     assert.equal(spec('explore'), normalizeModel('anthropic/light'));
     assert.equal(spec('explore', 'light'), normalizeModel('light'));
 });
+// `node new --model` widened to the full spec grammar (provider/tier, exact
+// provider/id, family alias) alongside the bare tier — the review floor must
+// still hold no matter which shape the requested model arrives in.
+test('review honors an explicit provider/tier override at or above its floor', () => {
+    assert.equal(spec('review', 'openai/ultra'), normalizeModel('openai/ultra'));
+});
+test('review still floors a provider/tier override below its floor', () => {
+    assert.equal(spec('review', 'openai/light'), normalizeModel('openai/strong'));
+});
+test('review passes an unrecognized concrete provider/id straight through, unfloored', () => {
+    // A fully concrete id that matches no ladder cell resolves to no known
+    // strength, so floorReviewModel trusts the explicit pin as-given rather than
+    // guessing — same trust boundary as `node config --model` on a dormant node.
+    const concrete = 'anthropic/claude-does-not-exist-9000';
+    assert.equal(spec('review', concrete), concrete);
+});

package/dist/core/memory-resolver.d.ts

@@ -22,6 +22,12 @@ export interface MemoryDoc {
     frontmatter: Record<string, unknown> | null;
     /** Document body, with the frontmatter block stripped. */
     body: string;
+    /** Set to the owning plugin's name when this doc is mounted from an installed
+     *  plugin (under `<pluginName>/`), undefined for a native scope doc. Plugin
+     *  docs surface within a source scope but live under the plugins dir and are
+     *  managed by `crtr pkg`, not writable/deletable as scope docs — consumers
+     *  that mutate the store gate on this. */
+    plugin?: string;
 }
 /** The memory-only scope union: the global `Scope` (`user|project|builtin`)
  *  plus `profile`. Confined to the memory resolver/list/read/write/render

package/dist/core/memory-resolver.js

@@ -164,7 +164,7 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
             continue;
         const name = `${plugin.name}/${derived}`;
         try {
-            docs.push(loadMemoryDoc(name, scope, file));
+            docs.push({ ...loadMemoryDoc(name, scope, file), plugin: plugin.name });
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];

package/dist/core/runtime/broker.js

@@ -1212,10 +1212,16 @@ export async function runBroker(nodeId) {
                     break;
                 const requested = parseModelSpec(frame.model);
                 let model;
+                let normalized;
                 try {
-                    // Accept both an exact `provider/id` (from the picker) and a free-text
-                    // query (`/model opus`) — resolveModelQuery falls back to a search match.
-                    model = resolveModelQuery(requested.modelSpec);
+                    // Tier/alias specs (`opus`, `strong`, `anthropic/strong`, …) MUST resolve
+                    // through the config ladder before touching the registry: the fuzzy
+                    // registry search rank-ties `opus` between claude-3-opus-20240229 and
+                    // claude-opus-4-8, and the deprecated 2024 model wins on catalog order.
+                    // Concrete `provider/id` specs and genuine substrings (`fable`) pass
+                    // through normalizeModel unchanged and take the exact/search path below.
+                    normalized = parseModelSpec(normalizeModel(requested.modelSpec));
+                    model = resolveModelQuery(normalized.modelSpec);
                 }
                 catch (err) {
                     // N2: registry.find should never throw on the real SDK, but a degenerate
@@ -1234,8 +1240,10 @@ export async function runBroker(nodeId) {
                 void session
                     .setModel(model)
                     .then(() => {
-                    if (requested.thinkingLevel !== undefined)
-                        session.setThinkingLevel(requested.thinkingLevel);
+                    // The caller's explicit `:thinking` wins; else the ladder cell's.
+                    const thinking = requested.thinkingLevel ?? normalized.thinkingLevel;
+                    if (thinking !== undefined)
+                        session.setThinkingLevel(thinking);
                     ackTo(client, 'set_model');
                     broadcastModelChanged();
                 })

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

@@ -8,6 +8,7 @@ export declare const CANVAS_GOAL_CAPTURE_PATH: string;
 export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
 export declare const CANVAS_CONTEXT_INTRO_PATH: string;
 export declare const CANVAS_DOC_SUBSTRATE_PATH: string;
+export declare const CANVAS_STRUCTURED_OUTPUT_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), recap (the per-node inactivity recap card — Haiku over the

package/dist/core/runtime/launch.js

@@ -16,9 +16,8 @@ import { nodeEnv } from './nodes.js';
 import { editorLabel } from '../canvas/index.js';
 import { nodeDir } from '../canvas/paths.js';
 // ---------------------------------------------------------------------------
-// The two canvas pi-extensions every node loads. They self-gate on the live
-// {kind,mode} env, so the worker→orchestrator polymorph flips hook behavior
-// with no respawn.
+// Canvas pi-extensions every node loads. They self-gate on node/runtime state,
+// so persona changes and per-node feature grants take effect without respawn.
 // ---------------------------------------------------------------------------
 function resolveExtension(name) {
     const here = dirname(fileURLToPath(import.meta.url)); // dist/core/runtime or src/core/runtime
@@ -36,6 +35,7 @@ export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
 export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
 export const CANVAS_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
 export const CANVAS_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate');
+export const CANVAS_STRUCTURED_OUTPUT_PATH = resolveExtension('canvas-structured-output');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), recap (the per-node inactivity recap card — Haiku over the
@@ -57,6 +57,7 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_PASSIVE_CONTEXT_PATH,
     CANVAS_CONTEXT_INTRO_PATH,
     CANVAS_DOC_SUBSTRATE_PATH,
+    CANVAS_STRUCTURED_OUTPUT_PATH,
 ];
 // ---------------------------------------------------------------------------
 // Two-axis model resolution: (provider × strength) → concrete `model:thinking`.

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

@@ -42,9 +42,12 @@ export interface SpawnChildOpts {
      *  a <crtr-wake> block is prepended to the kickoff so the newborn knows a clock
      *  birthed it. */
     wakeOrigin?: WakeOrigin;
-    /** Pin the node to a model TIER (ultra/strong/medium/light), overriding the
-     *  persona's declared default. Persisted to `meta.model_override` so it
-     *  survives polymorphs. Omit to use the persona default. */
+    /** Pin the node to a model spec — exact `provider/id`, `provider/tier`
+     *  (e.g. `openai/ultra`), bare tier (ultra/strong/medium/light), or family
+     *  alias (opus/sonnet/haiku) — overriding the persona's declared default.
+     *  The RAW spec is persisted to `meta.model_override` (buildLaunchSpec
+     *  re-normalizes through the current ladders on every revive/polymorph, so
+     *  ladder config edits keep propagating). Omit to use the persona default. */
     model?: string;
     /** Select the profile this node runs under — an exact profile id or a unique
      *  manifest name, validated through `loadProfileManifest`. Omit to INHERIT the

package/dist/core/runtime/stop-guard.js

@@ -17,8 +17,21 @@
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, hasPendingSelfTrigger, getNode } from '../canvas/index.js';
+import { hasPendingStructuredOutput, readOutputRequest } from './structured-output.js';
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
+function structuredOutputReprompt(nodeId) {
+    let schema = '{}';
+    try {
+        const request = readOutputRequest(nodeId);
+        if (request !== null)
+            schema = JSON.stringify(request.schema, null, 2);
+    }
+    catch {
+        /* keep a deterministic reprompt even if the schema file was corrupted */
+    }
+    return `You must call the \`submit\` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n\`\`\`json\n${schema}\n\`\`\``;
+}
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
  *  signals — the stophook supplies the signals and enacts the action. */
 export function evaluateStop(nodeId, signals) {
@@ -32,6 +45,12 @@ export function evaluateStop(nodeId, signals) {
     if (node !== null && (node.status === 'done' || node.status === 'dead' || node.status === 'canceled')) {
         return { action: 'allow', reason: 'finished' };
     }
+    // A pending structured-output request overrides every normal dormancy path:
+    // terminal mode must finish through submit, and one-off mode must answer the
+    // outstanding request before the node is freed to stop normally again.
+    if (hasPendingStructuredOutput(nodeId)) {
+        return { action: 'reprompt', reason: 'stalled', message: structuredOutputReprompt(nodeId) };
+    }
     // A RESIDENT node is interactable / human-driven and is never forced to submit
     // a final: stopping to go dormant is always legitimate (the inbox or the human
     // wakes it). Keyed on lifecycle, not parent — whether it has a parent doesn't

package/dist/core/runtime/structured-output.d.ts

@@ -0,0 +1,12 @@
+export type StructuredOutputMode = 'terminal' | 'oneoff';
+export interface StructuredOutputRequest {
+    mode: StructuredOutputMode;
+    schema: Record<string, unknown>;
+}
+export declare function outputSchemaPath(nodeId: string): string;
+export declare function outputResultPath(nodeId: string): string;
+export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;
+export declare function writeOutputSchema(nodeId: string, mode: StructuredOutputMode, schema: Record<string, unknown>): string;
+export declare function readOutputRequest(nodeId: string): StructuredOutputRequest | null;
+export declare function removeOutputSchema(nodeId: string): void;
+export declare function hasPendingStructuredOutput(nodeId: string): boolean;

package/dist/core/runtime/structured-output.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { nodeDir, contextDir } from '../canvas/paths.js';
+import { InputError } from '../io.js';
+export function outputSchemaPath(nodeId) {
+    return `${nodeDir(nodeId)}/output-schema.json`;
+}
+export function outputResultPath(nodeId) {
+    return `${contextDir(nodeId)}/result.json`;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function parseOutputSchemaValue(value) {
+    const raw = value?.trim();
+    if (raw === undefined || raw === '')
+        return null;
+    let text;
+    let source;
+    if (raw.startsWith('{')) {
+        text = raw;
+        source = 'inline JSON';
+    }
+    else {
+        const path = resolve(raw);
+        source = path;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'bad_output_schema',
+                message: `could not read output schema from ${path}: ${err.message}`,
+                field: 'output-schema',
+                next: 'Pass a readable JSON Schema file path, or inline JSON beginning with `{`.',
+            });
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} is not valid JSON: ${err.message}`,
+            field: 'output-schema',
+            next: 'Pass valid JSON whose top-level value is an object.',
+        });
+    }
+    if (!isObject(parsed)) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} must be a JSON object`,
+            field: 'output-schema',
+            next: 'Pass a JSON Schema object, not an array, string, number, boolean, or null.',
+        });
+    }
+    return parsed;
+}
+export function writeOutputSchema(nodeId, mode, schema) {
+    const path = outputSchemaPath(nodeId);
+    mkdirSync(dirname(path), { recursive: true });
+    const request = { mode, schema };
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`, 'utf8');
+    return path;
+}
+export function readOutputRequest(nodeId) {
+    const path = outputSchemaPath(nodeId);
+    if (!existsSync(path))
+        return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isObject(parsed))
+        return null;
+    const mode = parsed['mode'];
+    const schema = parsed['schema'];
+    if ((mode !== 'terminal' && mode !== 'oneoff') || !isObject(schema))
+        return null;
+    return { mode, schema };
+}
+export function removeOutputSchema(nodeId) {
+    const path = outputSchemaPath(nodeId);
+    try {
+        unlinkSync(path);
+    }
+    catch { /* already gone */ }
+}
+export function hasPendingStructuredOutput(nodeId) {
+    return existsSync(outputSchemaPath(nodeId));
+}