@crouton-kit/crouter 0.3.42 → 0.3.44

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';
@@ -131,6 +132,7 @@ const nodeNew = defineLeaf({
             { 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: '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.',
         ],
     },
@@ -174,6 +176,7 @@ const nodeNew = defineLeaf({
         const forkFrom = input['forkFrom'];
         const model = input['model'];
         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 +197,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 +720,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 +1029,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 +1058,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 +1083,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 +1113,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 +1286,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__/pid-zombie.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/pid-zombie.test.js

@@ -0,0 +1,42 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/pid-zombie.test.ts
+//
+// Regression cover for the zombie-broker revive bug: `kill(pid, 0)` reports a
+// ZOMBIE process (exited, awaiting reap by its parent) as perfectly alive —
+// its pid is still occupied in the process table. A broker's spawning process
+// that never gets to process its SIGCHLD (the real-world trigger: `bootRoot`'s
+// foreground attach session used to block its OWN event loop for the whole
+// session via a synchronous `spawnSync`, so it could never reap its detached
+// broker child in real time — see the async-spawn fix in runtime/spawn.ts)
+// leaves that broker a zombie indefinitely. The daemon's revive guard reads
+// liveness through `isPidAlive(pi_pid)` alone (`revive.ts`), so misreading a
+// zombie as alive wedges the relaunch forever. `isPidAlive` must classify a
+// genuine zombie as dead.
+//
+// Fabricates a REAL zombie: spawn a child with no exit listener, then starve
+// THIS process's own event loop with a synchronous busy-wait spanning the
+// child's exit — mirroring exactly how a blocking spawnSync parks the parent's
+// loop past a child's death, before any assertion ever runs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { isPidAlive } from '../canvas/pid.js';
+test('isPidAlive reads a genuine zombie process as dead, not alive', () => {
+    const child = spawn('/bin/sh', ['-c', 'exit 0'], { detached: true, stdio: 'ignore' });
+    const pid = child.pid;
+    assert.ok(pid != null, 'child must have a pid');
+    child.unref(); // no exit listener attached — nothing reaps it while the loop is starved below
+    // Busy-wait SYNCHRONOUSLY (no `await`/timer — starving the event loop, not
+    // just delaying it) long enough for the child to exit and the kernel to
+    // mark it a zombie, before this process's SIGCHLD handling ever gets a turn.
+    const deadline = Date.now() + 400;
+    while (Date.now() < deadline) { /* starve the loop */ }
+    assert.equal(isPidAlive(pid), false, 'a zombie pid must read as dead, not alive');
+    // Best-effort cleanup: signaling an already-zombied pid is a harmless no-op
+    // (it's already dead) — the zombie self-clears once this test process exits
+    // and the orphan is reparented to init, same as every other fixture in this
+    // suite; nothing here relies on that timing for the assertion above.
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+});

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

@@ -1,6 +1,17 @@
-/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
- *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
- *  ours — still alive. A null/undefined pid (legacy / never-booted) reads dead. */
+/** True if a process with `pid` is currently alive (signal-0 probe) AND not a
+ *  zombie. `kill(pid, 0)` throws ESRCH when the process is gone; EPERM means
+ *  it exists but isn't ours — still alive (a foreign process is never OUR
+ *  zombie, so the `isZombie` check is skipped for that branch — see below). A
+ *  null/undefined pid (legacy / never-booted) reads dead.
+ *
+ *  The zombie check matters because EVERY broker this module supervises is
+ *  spawned `detached: true` by crtr itself (`headlessBrokerHost.launch`) — a
+ *  dead broker whose spawning process hasn't reaped it yet is a zombie, and
+ *  `kill(pid, 0)` alone reports it as alive, wedging the daemon's revive guard
+ *  (`isPidAlive(pi_pid)`, `revive.ts`) forever: the daemon never revives an
+ *  already-live-looking row, so a refreshed/crashed node whose broker zombied
+ *  out under a long-lived spawning process (see `isZombie`'s doc) never comes
+ *  back on its own. */
 export declare function isPidAlive(pid: number | null | undefined): boolean;
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of

package/dist/core/canvas/pid.js

@@ -9,19 +9,56 @@
 // placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
- *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
- *  ours — still alive. A null/undefined pid (legacy / never-booted) reads dead. */
+/** Is `pid` a ZOMBIE (exited, awaiting reap by its parent)? `kill(pid, 0)`
+ *  reports a zombie as a perfectly normal alive process — its PID is still
+ *  occupied in the process table — so callers relying on that signal-0 probe
+ *  alone (see `isPidAlive`) misread a dead broker as alive forever whenever
+ *  its spawning process never reaps it (crouton-labs zombie-broker bug: the
+ *  front door's foreground attach session parks its OWN event loop for the
+ *  whole session — see `bootRoot` in runtime/spawn.ts — so it can't process
+ *  the SIGCHLD that would otherwise reap its detached broker child in real
+ *  time). `ps -o stat=` reports a leading `Z` for a zombie on BOTH BSD ps
+ *  (macOS) and procps-ng (Linux), so one portable probe covers both platforms
+ *  without a Linux-only `/proc` special case. Best-effort: any probe failure
+ *  (spawn error, no matching row, non-zero exit) reads as NOT a zombie —
+ *  fail-open, matching this module's other guards; a probe failure must never
+ *  be misread as proof of death (a live pid IS alive; only a positive `Z`
+ *  read says otherwise). */
+function isZombie(pid) {
+    try {
+        const r = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return false;
+        return r.stdout.trim().charAt(0) === 'Z';
+    }
+    catch {
+        return false;
+    }
+}
+/** True if a process with `pid` is currently alive (signal-0 probe) AND not a
+ *  zombie. `kill(pid, 0)` throws ESRCH when the process is gone; EPERM means
+ *  it exists but isn't ours — still alive (a foreign process is never OUR
+ *  zombie, so the `isZombie` check is skipped for that branch — see below). A
+ *  null/undefined pid (legacy / never-booted) reads dead.
+ *
+ *  The zombie check matters because EVERY broker this module supervises is
+ *  spawned `detached: true` by crtr itself (`headlessBrokerHost.launch`) — a
+ *  dead broker whose spawning process hasn't reaped it yet is a zombie, and
+ *  `kill(pid, 0)` alone reports it as alive, wedging the daemon's revive guard
+ *  (`isPidAlive(pi_pid)`, `revive.ts`) forever: the daemon never revives an
+ *  already-live-looking row, so a refreshed/crashed node whose broker zombied
+ *  out under a long-lived spawning process (see `isZombie`'s doc) never comes
+ *  back on its own. */
 export function isPidAlive(pid) {
     if (pid == null)
         return false;
     try {
         process.kill(pid, 0);
-        return true;
     }
     catch (e) {
         return e.code === 'EPERM';
     }
+    return !isZombie(pid);
 }
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of

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.js

@@ -9,7 +9,7 @@
 //                terminal background worker by default; with `root`, an
 //                INDEPENDENT resident root (no subscription back to the spawner,
 //                provenance via spawned_by) brought forefront for direct driving.
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { readdirSync, existsSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
 import { homedir } from 'node:os';
@@ -151,8 +151,23 @@ export async function bootRoot(opts) {
         throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
     }
     const attachEnv = { ...process.env, ...viewerSplitEnv() };
-    const r = spawnSync('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
-    process.exit(r.status ?? 0);
+    // Async, NOT spawnSync: a synchronous spawn would park THIS process's own
+    // event loop for the whole attach session (which legitimately runs for
+    // hours) — starving it of the SIGCHLD delivery it needs to reap its OWN
+    // detached broker child (recorded above via `recordPid`). A refresh/crash
+    // mid-session would then leave that broker a zombie for as long as the user
+    // stays attached, which `isPidAlive` misread as "alive" and blocked the
+    // daemon's relaunch (the exact bug this fixes). An async spawn keeps this
+    // process's loop ticking throughout, so the broker's already-registered
+    // `exit` listener (`headlessBrokerHost.launch`) actually gets to run and
+    // reap it in real time; `stdio: 'inherit'` still hands the child the TTY
+    // directly, so this is a behavior-neutral swap for the foreground session.
+    const attachChild = spawn('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
+    const code = await new Promise((resolveCode) => {
+        attachChild.once('exit', (exitCode) => resolveCode(exitCode ?? 0));
+        attachChild.once('error', () => resolveCode(1));
+    });
+    process.exit(code);
 }
 /** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
  *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be