@north-light/crouter 0.3.231 → 0.3.233

package/dist/commands/node/bash.js

@@ -32,8 +32,6 @@ const nodeBashBackground = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
-            { name: 'backgrounded', type: 'number', required: true, constraint: 'Number of running bash commands handed off.' },
-            { name: 'job_ids', type: 'string[]', required: true, constraint: 'File-backed job ids now running independently of the agent tool call.' },
             { name: 'jobs', type: 'object[]', required: true, constraint: 'Per handed-off job {job_id, elapsed_ms} — the foreground elapsed time in milliseconds at the moment of handoff.' },
         ],
         outputKind: 'object',
@@ -53,14 +51,14 @@ const nodeBashBackground = defineLeaf({
                 ? `crtr: bash handed off · ${formatBashElapsed(elapsed[0].elapsed_ms)}`
                 : `crtr: bash handed off (${jobs.length})`;
         displayMessage(toast, pane);
-        return { node_id: id, backgrounded: jobs.length, job_ids: jobs.map((job) => job.jobId), jobs: elapsed };
+        return { node_id: id, jobs: elapsed };
     },
     render: (result) => {
-        if (result['backgrounded'] === 0)
-            return `No foreground bash command is running for ${result['node_id']}.`;
         const jobs = result['jobs'];
+        if (jobs.length === 0)
+            return `No foreground bash command is running for ${result['node_id']}.`;
         const oldestElapsedMs = Math.max(...jobs.map((job) => job.elapsed_ms));
-        return `Handed ${result['backgrounded']} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
+        return `Handed ${jobs.length} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
     },
 });
 const nodeBashList = defineLeaf({
@@ -126,7 +124,6 @@ const nodeBashKill = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
-            { name: 'job_id', type: 'string', required: true, constraint: 'The job that was stopped.' },
             { name: 'signaled', type: 'boolean', required: true, constraint: 'True when the process group was still alive and received SIGTERM.' },
         ],
         outputKind: 'object',
@@ -169,9 +166,9 @@ const nodeBashKill = defineLeaf({
             body: `Background bash job ${jobId} was stopped by the user before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
             tier: 'urgent',
         });
-        return { node_id: node.node_id, job_id: jobId, signaled: stopped.signaled };
+        return { node_id: node.node_id, signaled: stopped.signaled };
     },
-    render: (result) => `Canceled background bash job ${result['job_id']} for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
+    render: (result) => `Canceled a background bash job for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
 });
 export const nodeBash = defineBranch({
     name: 'bash',

package/dist/commands/node/create.js

@@ -2,13 +2,17 @@
 import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { mark } from '../../core/timing.js';
-import { parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
+import { OUTPUT_SCHEMA_CONSTRAINTS, OUTPUT_SCHEMA_TRANSPORT, parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
+import { MODEL_SPEC_FORMS, MODEL_SPEC_NEXT } from '../../core/runtime/model-selection.js';
 import { readMergedLaunchConfig } from '../../core/config.js';
 import { profilesStateBlock } from '../../core/profiles/state-block.js';
+import { resolveProfileOperand } from '../../core/profiles/manifest.js';
 import { stateBlock } from '../../core/help.js';
 import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+import { inTmux } from '../../core/runtime/placement-tmux.js';
 import { openSpawnViewer } from '../surface/node/placement.js';
 const YIELD_NUDGE_THRESHOLD = 100_000;
+const NODE_NEW_OUTPUT_SCHEMA_EFFECT = '--output-schema writes the accepted result to the node’s context/result.json and pushes it as the node’s final report.';
 const STD_CHILD_FOLLOW_UP = "Do not wait, poll, or duplicate this child's assignment in your own context — there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn — the wake brings you back.";
 /** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
  *  but when the SPAWNER is an orchestrator whose context has already grown past
@@ -68,33 +72,97 @@ export function kindsStateBlock() {
 }
 function nodeNewParams() {
     return [
-        { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message. Required unless --no-kickoff is given.' },
+        { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message.' },
         { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: "Persona kind. Defaults to the profile's default kind; `general` when the profile has none. The <kinds> list below names every top-level installable kind." },
         { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for hands-on work; orchestrator when the unit itself needs decomposition across children.' },
         { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the directory this command runs in for a root.' },
-        { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name. Defaults to the kind.' },
+        { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
         { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
         { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent resident root with no parent or subscription. Mutually exclusive with --worktree.' },
         { kind: 'flag', name: 'worktree', type: 'string', required: false, constraint: 'Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root.' },
         { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'Fork the new node from an existing node id, absolute session path, or partial pi session uuid.' },
-        { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Durable model override: provider/id; provider/tier where provider is anthropic|openai and tier is ultra|strong|medium|light; bare tier (ultra|strong|medium|light); or family alias (opus|sonnet|haiku).' },
-        { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or unique profile name. Omit to inherit the caller profile.' },
+        {
+            kind: 'flag',
+            name: 'model',
+            type: 'string',
+            required: false,
+            constraint: 'Durable model override. Omit unless the task or governing guidance requires a specific model.',
+            focusedHelp: {
+                whenToUse: 'Use only when the user, task, or governing agent guidance already requires a specific provider, model, capability tier, or family. Omit it for routine delegation: the selected persona kind and profile own normal model selection, and review personas may enforce a quality floor.',
+                value: `Accepted forms: ${MODEL_SPEC_FORMS}. Concrete provider/id requests must be registered. Portable provider/tier, bare-tier, and family-alias requests resolve through the configured model ladders.`,
+                effects: [
+                    'The resolved override is stored on the node and in its launch recipe, so future revives preserve it.',
+                    'A concrete provider/id pins that provider. Portable tiers and aliases preserve logical intent for runtime routing; a persona quality floor may raise a weaker request.',
+                ],
+            },
+        },
+        {
+            kind: 'flag',
+            name: 'profile',
+            type: 'string',
+            required: false,
+            constraint: 'Profile override. Use only when the task needs different project purview, memory, or environment; otherwise omit for normal inheritance or selection.',
+            focusedHelp: {
+                whenToUse: 'Use only when the work must run under a different profile because it needs that profile’s project purview, memory store, stored environment, or defaults. Do not use it merely to change the working directory, persona kind, model, or graph ownership; those have separate parameters.',
+                value: 'Pass a profile id or name from the <profiles> list below; a close-enough name resolves to the nearest profile and the choice is reported on stderr. Omit it inside a node to inherit the caller’s profile; outside a node, omission runs normal cwd-based profile selection.',
+                effects: [
+                    'The selected profile id is stored on the node and supplies its profile-scoped config, memory, environment, and injected bearings.',
+                    'It does not change the parent or subscription; --cwd separately pins the working directory.',
+                ],
+                dynamicState: () => profilesStateBlock(),
+            },
+        },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Hidden ambient context appended to injected bearings, never visible chat.' },
-        { kind: 'flag', name: 'no-kickoff', type: 'bool', required: false, constraint: 'With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator.' },
-        { kind: 'flag', name: 'output-schema', type: 'string', required: false, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. The node must submit a conforming result to finish.' },
+        // Hidden: an idle root is the rare shape, and the empty-prompt error names
+        // this flag at exactly the moment it is needed. Advertising it would tax
+        // every spawn with a capability almost no caller wants.
+        { kind: 'flag', name: 'no-kickoff', type: 'bool', required: false, hidden: true, constraint: 'With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator.' },
+        {
+            kind: 'flag',
+            name: 'output-schema',
+            type: 'string',
+            required: false,
+            constraint: 'Replace prose completion with a schema-constrained final result. Use only when its consumer requires fixed fields.',
+            focusedHelp: {
+                whenToUse: 'Use only when the node’s consumer needs a machine-checkable final object with fixed fields. Omit it for ordinary delegation or when a prose report is enough; structured output replaces the completion protocol, and an over-constrained schema can force retries.',
+                value: `Pass the JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} ${OUTPUT_SCHEMA_CONSTRAINTS}`,
+                effects: [
+                    'The node receives a terminal submit tool and cannot finish until submit accepts a result; it must not call `crtr push final` itself.',
+                    NODE_NEW_OUTPUT_SCHEMA_EFFECT,
+                    'The managed parent wakes through its existing subscription when the final report arrives; an independent root has no subscriber to wake.',
+                    'Successful submit removes the request and terminates the node.',
+                ],
+            },
+        },
     ];
 }
+/** A root's viewer opens from THIS process (openSpawnViewer), so the caller's
+ *  own tmux presence decides whether placement fields and the viewer effect can
+ *  ever apply. Outside tmux they are dead weight, so help omits them. `inTmux()`
+ *  is a bare env read — safe on the import-time help path. */
 function nodeNewOutput() {
     return [
         { name: 'node_id', type: 'string', required: true, constraint: 'New node id.' },
         { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
-        { name: 'status', type: 'string', required: true, constraint: 'Always "active".' },
-        { name: 'window', type: 'string', required: false, constraint: 'tmux window id when a viewer opens.' },
-        { name: 'session', type: 'string', required: false, constraint: 'tmux session when a viewer opens.' },
+        ...(inTmux()
+            ? [
+                { name: 'window', type: 'string', required: false, constraint: 'tmux window id when a viewer opens.' },
+                { name: 'session', type: 'string', required: false, constraint: 'tmux session when a viewer opens.' },
+            ]
+            : []),
         { name: 'follow_up', type: 'string', required: true, constraint: 'Managed child: continue unrelated work or stop; its final report wakes you. Root: hand it off; no report wakes you.' },
     ];
 }
+function nodeNewEffects() {
+    return [
+        'Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.',
+        'A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.',
+        '--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch.',
+        NODE_NEW_OUTPUT_SCHEMA_EFFECT,
+        ...(inTmux() ? ['--root opens a viewer for the new node in the current tmux session.'] : []),
+    ];
+}
 async function runNodeCreation(input) {
     const prompt = input['prompt'] ?? '';
     const noKickoff = input['noKickoff'] === true;
@@ -118,9 +186,13 @@ async function runNodeCreation(input) {
     const forkFrom = input['forkFrom'];
     const modelSpec = input['model']?.trim();
     if (modelSpec === '') {
-        throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Pass a provider/id, provider/tier where provider is anthropic|openai and tier is ultra|strong|medium|light, a bare tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku).' });
+        throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: `Run \`crtr node new --model -h\` and read the focused contract. ${MODEL_SPEC_NEXT}` });
     }
-    const profile = input['profile'];
+    // Resolved here rather than server-side so the closest-match notice lands on
+    // the caller's terminal instead of the daemon log, and so the daemon receives
+    // a durable id rather than a name it would have to interpret again.
+    const profileOperand = input['profile'];
+    const profile = profileOperand === undefined ? undefined : resolveProfileOperand(profileOperand).profileId;
     const situationalContextRaw = input['situationalContext']?.trim();
     const situationalContext = situationalContextRaw !== undefined && situationalContextRaw !== '' ? situationalContextRaw : undefined;
     const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
@@ -171,7 +243,6 @@ async function runNodeCreation(input) {
         name: detail.name,
         window: placement.window,
         session: placement.session,
-        status: detail.status,
         follow_up: root
             ? (noKickoff
                 ? 'Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.'
@@ -183,26 +254,22 @@ async function runNodeCreation(input) {
 export const nodeNew = defineLeaf({
     name: 'new',
     description: 'create and start a node immediately',
-    whenToUse: 'you need a managed child or independent root to start immediately',
+    whenToUse: 'a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel, a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose',
     tier: 'important',
     help: {
         name: 'node new',
         summary: 'create a node immediately and start its detached broker',
+        guide: 'The prompt is the child\u2019s entire brief: it wakes with this prompt, its persona, and ambient bearings \u2014 none of your conversation carries over. State the outcome and constraints. Pass an implementation plan only when it is already settled or necessary to preserve an approved decision; otherwise, let the child investigate and choose how. Give the reason along with the request: the larger goal this serves and what the child\'s output enables, so the child resolves ambiguity toward your intent instead of guessing. Name by absolute path every artifact the task depends on (a spec, an explore report, an earlier child\'s findings); the child inherits only the files the prompt names. When the report must carry something specific—findings inline, or paths to artifacts it wrote—say so in the prompt.',
         params: nodeNewParams(),
         output: nodeNewOutput(),
-        dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
+        dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
-        effects: [
-            'Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.',
-            'A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.',
-            '--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch. --output-schema writes nodes/<id>/output-schema.json. --no-kickoff starts an idle root without a first model turn.',
-            'An in-tmux root opens a viewer in the current tmux session. When auto_open_child_viewers is true, a managed child opens beside a live spawner viewer; false leaves it running in the background.',
-        ],
+        effects: nodeNewEffects(),
     },
     run: (input) => runNodeCreation(input),
     render: (r) => {
         const win = r['window'] ? ` in window ${r['window']}` : '';
-        const lines = [`Spawned "${r['name']}" (${r['node_id']}) — ${r['status']}${win}.`];
+        const lines = [`Spawned "${r['name']}" (${r['node_id']})${win}.`];
         if (r['session'])
             lines.push(`- session: ${r['session']}`);
         lines.push('', String(r['follow_up']));

package/dist/commands/node/inspect.js

@@ -4,7 +4,7 @@ import { InputError } from '../../core/io.js';
 import { isPidAlive } from '../../core/canvas/pid.js';
 import { fullName } from '../../core/canvas/labels.js';
 import { fuzzyMatch } from '../../core/canvas/browse/model.js';
-import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { resolveProfileOperand } from '../../core/profiles/manifest.js';
 import { profilesStateBlock } from '../../core/profiles/state-block.js';
 import { nodeSnapshotLeaf } from '../node-snapshot.js';
 import { nodeTranscriptLeaf } from '../node-transcript.js';
@@ -26,7 +26,7 @@ const nodeList = defineLeaf({
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (comma-separated for several). The <kinds> list below names every top-level installable kind; a registered sub-kind filters too by exact path even though it is not listed.' },
             { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'Filter by mode (comma-separated for several; accepted values: base, orchestrator).' },
             { kind: 'flag', name: 'lifecycle', type: 'string', required: false, constraint: 'Filter by lifecycle (comma-separated for several; accepted values: terminal, resident).' },
-            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Filter by profile. On the local canvas, accepts an exact profile id or a unique manifest name from the <profiles> list below. Against a remote canvas, pass the exact profile id carried by its node rows.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Filter by profile. On the local canvas, accepts a profile id or manifest name from the <profiles> list below, or a close-enough name that resolves to the nearest profile. Against a remote canvas, pass the exact profile id carried by its node rows.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Filter by the displayed node label (handle plus generated description) with the canvas browser’s case-insensitive fuzzy subsequence match.' },
             { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Filter to nodes pinned to this exact cwd (absolute path). Roster is canvas-wide (all cwds) by default.' },
             { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Graph scope: restrict to this node and its subscription descendants (the sub-DAG reachable downward — its reports, theirs, …). This is "one initiative / my subtree". ANDs with every attribute filter above, narrowing any of them to this subtree.' },
@@ -59,7 +59,7 @@ const nodeList = defineLeaf({
         // cannot resolve this machine's manifest names.
         const profileId = canvasSource instanceof RemoteCanvasSource
             ? profile
-            : profile === undefined ? undefined : loadProfileManifest(profile).profileId;
+            : profile === undefined ? undefined : resolveProfileOperand(profile).profileId;
         let scope;
         if (under !== undefined && under !== '') {
             if (await canvasSource.getNode(under).catch(rethrowAsCliError) === null) {

package/dist/commands/node/lifecycle.js

@@ -4,6 +4,7 @@ import { InputError } from '../../core/io.js';
 import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
 import { nodeReviveLeaf } from '../node-lifecycle-revive.js';
 import { assertKind, kindsStateBlock } from './create.js';
+import { MODEL_SPEC_FORMS } from '../../core/runtime/model-selection.js';
 import { closePane, paneExists, respawnPaneSync, viewerEnv, viewerPaneOf, nodeInPane } from '../surface/node/placement.js';
 const nodeRecycle = defineLeaf({
     name: 'recycle',
@@ -19,8 +20,6 @@ const nodeRecycle = defineLeaf({
         output: [
             { name: 'recycled', type: 'boolean', required: true, constraint: 'True when the pane was recycled into a fresh root.' },
             { name: 'node_id', type: 'string', required: false, constraint: 'The finished node.' },
-            { name: 'finalized', type: 'boolean', required: false, constraint: 'True when a final report was pushed to its subscribers.' },
-            { name: 'delivered', type: 'number', required: false, constraint: 'How many subscribers/managers received the final report.' },
             { name: 'new_root', type: 'string', required: false, constraint: 'The fresh root node booted into the pane.' },
         ],
         outputKind: 'object',
@@ -48,21 +47,19 @@ const nodeRecycle = defineLeaf({
         if (pane !== undefined && pane !== '') {
             paneRecycled = respawnPaneSync({ pane, cwd: detail.cwd, env: viewerEnv(), command: 'crtr' });
         }
-        return { recycled: paneRecycled, node_id: id, finalized: true, delivered: undefined, new_root: newRoot };
+        return { recycled: paneRecycled, node_id: id, new_root: newRoot };
     },
     render: (r) => {
         if (r['recycled'] !== true) {
             // A broker recycle that finalized + spawned a fresh root but whose new
             // broker never served its socket: the state DID change (node finished, root
             // born), only the viewer re-attach failed — say so, don't call it a no-op.
-            if (r['finalized'] === true && r['new_root']) {
+            if (r['new_root']) {
                 return `Finished ${r['node_id']} and spawned a fresh broker root (${r['new_root']}), but its viewer did not attach — the new broker did not come up. Re-focus the root to view it.`;
             }
             return `Recycle failed for ${r['node_id'] ?? '?'} — not in tmux, or no agent in this pane.`;
         }
-        const lines = [`Recycled the pane — finished ${r['node_id']}.`, `- finalized: ${r['finalized']}`];
-        if (r['finalized'] === true)
-            lines.push(`- delivered: ${r['delivered']}`);
+        const lines = [`Recycled the pane — finished ${r['node_id']}.`];
         if (r['new_root'])
             lines.push(`- new root: ${r['new_root']}`);
         return lines.join('\n');
@@ -83,7 +80,6 @@ const nodeClose = defineLeaf({
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to close. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
         ],
         output: [
-            { name: 'closed', type: 'boolean', required: true, constraint: 'True when the node (and its exclusive subtree) was closed.' },
             { name: 'node_id', type: 'string', required: false, constraint: 'The node that was closed — the cascade root.' },
             { name: 'count', type: 'number', required: false, constraint: 'How many nodes were closed (root + cascaded descendants).' },
             { name: 'closed_ids', type: 'string[]', required: false, constraint: 'All closed node ids, kill order (leaves first, root last).' },
@@ -107,11 +103,9 @@ const nodeClose = defineLeaf({
         const res = await cliClient()
             .closeNode(id)
             .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
-        return { closed: true, node_id: res.root, count: res.closed.length, closed_ids: res.closed, spared: res.spared };
+        return { node_id: res.root, count: res.closed.length, closed_ids: res.closed, spared: res.spared };
     },
     render: (r) => {
-        if (r['closed'] !== true)
-            return 'Close failed — no node found in this pane to close.';
         const spared = r['spared']?.length ?? 0;
         return `Closed ${r['node_id']} and its exclusive subtree — ${r['count']} node(s) closed${spared > 0 ? `, ${spared} spared (still managed from outside the subtree)` : ''}.`;
     },
@@ -119,6 +113,7 @@ const nodeClose = defineLeaf({
 // ---------------------------------------------------------------------------
 // node config — reconfigure a node's settings headlessly (model/lifecycle/kind/mode/name)
 // ---------------------------------------------------------------------------
+const NODE_CONFIG_MODEL_EFFECT = 'Model change first: a live broker switches immediately over its socket; a dormant node persists the durable model override and launch recipe for its next revive.';
 export const nodeConfig = defineLeaf({
     name: 'config',
     description: 'reconfigure a node\'s settings headlessly — model, lifecycle (terminal/resident), kind, mode, name',
@@ -129,7 +124,21 @@ export const nodeConfig = defineLeaf({
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Target node id. Defaults to the node in --pane, else CRTR_NODE_ID.' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to resolve the node from. Defaults to $TMUX_PANE.' },
-            { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Model spec: exact provider/id, capability tier (ultra|strong|medium|light), family alias (opus|sonnet|haiku), or a free-text substring when the broker is live. Dormant nodes require a provider/id, tier, or alias.' },
+            {
+                kind: 'flag',
+                name: 'model',
+                type: 'string',
+                required: false,
+                constraint: 'Durable model change. Omit unless the task or governing guidance requires a different model.',
+                focusedHelp: {
+                    whenToUse: 'Use only when intentionally changing this node’s durable model because the user, task, or governing agent guidance requires a specific provider, model, capability tier, or family. Omit it to keep the current model; do not use it merely to inspect available models or experiment with a live node.',
+                    value: `Accepted durable forms: ${MODEL_SPEC_FORMS}. A live broker also accepts a free-text substring matched against its loaded model registry; a dormant node cannot resolve a substring and requires a durable form.`,
+                    effects: [
+                        NODE_CONFIG_MODEL_EFFECT,
+                        'A concrete provider/id pins that provider. Portable tiers and aliases preserve logical intent for runtime routing; a persona quality floor may raise a weaker request.',
+                    ],
+                },
+            },
             { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Set lifecycle headlessly without closing the viewer. terminal owes a final and reaps when done; resident stays interactable while attached or awaiting something live.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here.' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator seeds a roadmap scaffold if absent.' },
@@ -142,11 +151,10 @@ export const nodeConfig = defineLeaf({
             { name: 'kind', type: 'string', required: false, constraint: 'The new kind, present only when --kind changed it.' },
             { name: 'mode', type: 'string', required: false, constraint: 'The new mode, present only when --mode changed it.' },
             { name: 'name', type: 'string', required: false, constraint: 'The new name, present only when --name changed it.' },
-            { name: 'applied', type: 'string[]', required: false, constraint: 'The fields that changed, in application order.' },
         ],
         outputKind: 'object',
         effects: [
-            'Model change first: live broker switches over its socket; dormant node persists the durable recipe (model_override + launch.model).',
+            NODE_CONFIG_MODEL_EFFECT,
             'Kind, mode, and lifecycle changes rebuild the launch spec from the fresh node meta; setting mode to orchestrator seeds a roadmap scaffold if absent.',
             'Name changes update the row and, when the node already has a live window, rename that viewer window to the new full name.',
         ],
@@ -162,7 +170,7 @@ export const nodeConfig = defineLeaf({
         // node's scope as a backstop.
         const modelSpec = input['model']?.trim();
         if (modelSpec === '') {
-            throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Pass a `provider/id`, a tier (ultra|strong|medium|light), an alias (opus|sonnet|haiku), or a substring.' });
+            throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Run `crtr node config --model -h` and read the focused contract before retrying.' });
         }
         const kindSpec = input['kind']?.trim();
         const lifecycleSpec = input['lifecycle']?.trim();
@@ -204,7 +212,7 @@ export const nodeConfig = defineLeaf({
         const detail = await cliClient()
             .patchConfig(nodeId, patch)
             .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
-        const result = { node_id: nodeId, applied };
+        const result = { node_id: nodeId };
         if (applied.includes('model'))
             result.model = detail.model_override ?? modelSpec;
         if (applied.includes('lifecycle'))
@@ -249,7 +257,6 @@ export const nodePromote = defineLeaf({
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The promoted node.' },
             { name: 'kind', type: 'string', required: true, constraint: 'The kind it now orchestrates as.' },
-            { name: 'mode', type: 'string', required: true, constraint: 'Now "orchestrator".' },
             { name: 'model', type: 'string', required: false, constraint: 'The model tier it now runs on, present only when you changed it with --model.' },
             { name: 'lifecycle', type: 'string', required: true, constraint: '"resident" if you passed --resident, else unchanged (typically "terminal").' },
             { name: 'roadmap_written', type: 'boolean', required: true, constraint: 'True if a roadmap scaffold was seeded by this call.' },
@@ -275,7 +282,6 @@ export const nodePromote = defineLeaf({
         return {
             node_id: detail.node_id,
             kind: detail.kind,
-            mode: detail.mode,
             lifecycle: detail.lifecycle,
             ...(model !== undefined && detail.model_override != null ? { model: detail.model_override } : {}),
             roadmap_written: detail.roadmap_written ?? false,
@@ -323,7 +329,6 @@ const nodeDemote = defineLeaf({
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The demoted node.' },
-            { name: 'lifecycle', type: 'string', required: true, constraint: 'Always "terminal" after a demote.' },
             { name: 'detached', type: 'boolean', required: false, constraint: 'True when --detach closed the agent\'s viewer pane (broker keeps running).' },
         ],
         outputKind: 'object',
@@ -343,9 +348,9 @@ const nodeDemote = defineLeaf({
             if (viewer !== undefined && viewer !== '' && paneExists(viewer))
                 detached = closePane(viewer);
         }
-        return { node_id: detail.node_id, lifecycle: detail.lifecycle, detached };
+        return { node_id: detail.node_id, detached };
     },
-    render: (r) => `Demoted ${r['node_id']} — lifecycle now ${r['lifecycle']} (in place)${r['detached'] === true ? ', viewer closed (broker still running off-screen)' : ''}.`,
+    render: (r) => `Demoted ${r['node_id']} — lifecycle now terminal (in place)${r['detached'] === true ? ', viewer closed (broker still running off-screen)' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node lifecycle — recycle, close, or demote a node
@@ -370,7 +375,7 @@ export const nodeYield = defineLeaf({
     help: {
         name: 'node yield',
         summary: 'request a fresh context window against your roadmap or original goal; mode stays unchanged unless --promote is passed',
-        guide: 'Persist anything needed after refresh and send any pending human question before invoking; in-flight asks survive the refresh.',
+        guide: 'Before invoking: (1) Bring `$CRTR_CONTEXT_DIR/roadmap.md` current — it, not the yield note, carries the goal into the fresh window. Keep its seeded sections (Goal, Exit criteria, Phases) and keep it short: strategy and present state only — what is settled, what remains, the current phase’s one-line status, plus dead ends worth not repeating. Delete completed items instead of marking them done; the roadmap should shrink as work completes. (2) Move anything worth remembering but not needed next window into memory (`crtr memory write -h`): node-local for lessons specific to this node’s task, the workspace store for lessons that would benefit other agents working here. (3) Send any pending human question; in-flight asks survive the refresh.',
         params: [
             { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'Also become an orchestrator as you refresh. Pass only when (1) the remaining work contains independent units that can run in parallel and (2) the task is large enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after coordination and synthesis. Task length, context exhaustion, sequential phases, or one helper are not enough; keep hands-on work in base mode and yield again as needed. Promote when coordinating and integrating children becomes your primary job. Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh. The <kinds> list below names every top-level available kind and when to choose it; a registered sub-kind is valid too by exact path but not listed here. Defaults to your current kind. With --promote it sets the orchestrator kind you become; without --promote it changes the kind while preserving your current mode.' },
@@ -379,17 +384,15 @@ export const nodeYield = defineLeaf({
             // `crtr node yield`; that invocation fails fast and surfaces yield's full help just in
             // time, at the point of use. Keep the note required rather than pre-documenting stdin
             // in kernel guidance.
-            { kind: 'stdin', name: 'message', required: true, constraint: 'A note to your future self — what to do the moment you wake fresh. Surfaced as <yield-message> in the next revive. Pass as a positional or pipe via heredoc.' },
+            { kind: 'stdin', name: 'message', required: true, constraint: 'A note to your future self — what you just tried, where things stand, and the first move on waking: enough to continue efficiently, no more. Durable strategy belongs in the roadmap, not here. Surfaced as <yield-message> in the next revive. Pass as a positional or pipe via heredoc.' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The yielding node.' },
-            { name: 'promoted', type: 'boolean', required: true, constraint: 'True iff you passed --promote.' },
             { name: 'model', type: 'string', required: false, constraint: 'The model tier your fresh revive will run on, present only when you changed it with --model.' },
-            { name: 'will_refresh', type: 'boolean', required: true, constraint: 'Always true: end your turn and you will revive fresh.' },
         ],
         dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
-        effects: ['Sets intent=refresh; the stophook shuts the process down on next stop and the daemon revives it fresh.', '--kind and/or --model durably reshape the node (kind respecialization, model-tier pin) before the refresh-revive; --promote additionally flips mode→orchestrator and seeds a roadmap scaffold — mode is otherwise left exactly as it was.'],
+        effects: ['The stophook shuts the process down on next stop and the daemon revives it fresh.', '--kind and/or --model durably reshape the node (kind respecialization, model-tier pin) before the refresh-revive; --promote additionally flips mode→orchestrator and seeds a roadmap scaffold — mode is otherwise left exactly as it was.'],
     },
     run: async (input) => {
         const id = process.env['CRTR_NODE_ID'];
@@ -410,6 +413,6 @@ export const nodeYield = defineLeaf({
         const detail = await cliClient()
             .yieldNode(id, { note: message, ...(kind !== undefined ? { kind } : {}), ...(model !== undefined ? { model } : {}), ...(doPromote ? { promote: true } : {}) })
             .catch((err) => rethrowAsCliError(err));
-        return { node_id: detail.node_id, promoted: doPromote, ...(model !== undefined && detail.model_override != null ? { model: detail.model_override } : {}), will_refresh: true };
+        return { node_id: detail.node_id, ...(model !== undefined && detail.model_override != null ? { model: detail.model_override } : {}) };
     },
 });

package/dist/commands/node/message.js

@@ -1,7 +1,7 @@
 // `crtr node message` — immediate inbox delivery and typed-output requests.
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
-import { parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
+import { OUTPUT_SCHEMA_CONSTRAINTS, OUTPUT_SCHEMA_TRANSPORT, parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
 import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
 function requireNonBlankDiscriminant(input, name) {
     const value = input[name];
@@ -36,29 +36,27 @@ async function resolveMsgTarget(input) {
 }
 function messageOutput() {
     return [
-        { name: 'target', type: 'string', required: true, constraint: 'self or the target node id.' },
-        { name: 'delivered', type: 'boolean', required: false, constraint: 'True when an inbox message was delivered.' },
         { name: 'revived', type: 'boolean', required: false, constraint: 'True when the target was revived.' },
         { name: 'guidance', type: 'string', required: true, constraint: 'Immediate action confirmation.' },
     ];
 }
 function messageSendParams() {
     return [
-        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --fresh, --output-schema, or --situational-context is supplied.' },
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.' },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node.' },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
-        { kind: 'flag', name: 'reopen', type: 'bool', required: false, constraint: 'Required to re-task a finalized target: clears its finalization latch before delivery. Rejected when the target is not finalized.' },
+        { kind: 'flag', name: 'reopen', type: 'bool', required: false, constraint: 'Re-task the target: commits it resident and clears any finalization latch before delivery. Valid for live, parked, and finalized targets.' },
     ];
 }
 function messageRequestParams() {
     return [
-        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --fresh, --output-schema, or --situational-context is supplied.' },
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.' },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node.' },
-        { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. Grants a one-off submit tool.' },
+        { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: `JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} The target answers through a constrained submit tool, then keeps working. ${OUTPUT_SCHEMA_CONSTRAINTS}` },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
         { kind: 'flag', name: 'reopen', type: 'bool', required: false, hidden: true, constraint: 'Clear a finalized target latch before delivery or fresh revive.' },
     ];
@@ -69,58 +67,39 @@ async function runMessageEngine(input) {
     if (situationalContextSupplied && situationalContextRaw === '') {
         throw new InputError({ error: 'empty_situational_context', message: '--situational-context must contain non-whitespace text', field: 'situational-context', next: 'Pass non-whitespace text, or omit --situational-context.' });
     }
-    const { targetId, isSelf } = await resolveMsgTarget(input);
+    const { targetId } = await resolveMsgTarget(input);
     const bodyRaw = input['body'];
     const body = bodyRaw !== undefined ? bodyRaw.trim() : undefined;
     const hasBody = body !== undefined && body !== '';
     const tierRaw = input['tier'];
     const hasTier = tierRaw !== undefined && tierRaw !== '';
-    const fresh = input['fresh'] === true;
     const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
     const outputSchema = outputSchemaParsed !== null ? JSON.stringify(outputSchemaParsed) : null;
     const hasSituational = situationalContextRaw !== undefined && situationalContextRaw !== '';
     const reopen = input['reopen'] === true;
-    if (fresh && (hasBody || hasTier || outputSchema !== null)) {
-        throw new InputError({ error: 'bad_fresh_combo', message: '--fresh cannot combine with a body, --tier, or --output-schema', next: 'Drop the conflicting input; --fresh is a revive, not a message.' });
-    }
     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 answer', field: 'tier', next: 'Use normal, urgent, or critical tier, or drop --output-schema.' });
     }
-    const target = isSelf ? 'self' : targetId;
     const senderFrom = process.env['CRTR_NODE_ID'];
     const client = cliClient();
-    let result;
-    if (fresh) {
-        const res = await client.sendMessage(targetId, {
-            body: '',
-            fresh: true,
-            ...(reopen ? { reopen: true } : {}),
-            ...(hasSituational ? { situational_context: situationalContextRaw } : {}),
-            ...(senderFrom !== undefined ? { from: senderFrom } : {}),
-        }).catch(rethrowAsCliError);
-        result = { target, revived: res.revived, guidance: `Fresh-revived ${isSelf ? 'yourself' : targetId} now.` };
-    }
-    else {
-        if (!hasBody && !hasSituational && outputSchema === null) {
-            throw new InputError({ error: 'empty_body', message: 'a message body is required unless --output-schema or --situational-context is supplied', field: 'body', next: 'Pass the message on stdin, or supply one of the documented alternatives.' });
-        }
-        const tier = (hasTier ? tierRaw : 'normal');
-        const res = await client.sendMessage(targetId, {
-            body: body ?? '',
-            tier,
-            ...(reopen ? { reopen: true } : {}),
-            ...(hasSituational ? { situational_context: situationalContextRaw } : {}),
-            ...(outputSchema !== null ? { output_schema: outputSchema } : {}),
-            ...(senderFrom !== undefined ? { from: senderFrom } : {}),
-        }).catch(rethrowAsCliError);
-        const guidance = res.revived
-            ? 'Delivered — the dormant target was revived to receive it.'
-            : tier === 'deferred'
-                ? "Delivered — held for the target's next natural cycle; not revived."
-                : 'Delivered.';
-        result = { target, delivered: true, revived: res.revived, guidance };
+    if (!hasBody && !hasSituational && outputSchema === null) {
+        throw new InputError({ error: 'empty_body', message: 'a message body is required unless --output-schema or --situational-context is supplied', field: 'body', next: 'Pass the message on stdin, or supply one of the documented alternatives.' });
     }
-    return result;
+    const tier = (hasTier ? tierRaw : 'normal');
+    const res = await client.sendMessage(targetId, {
+        body: body ?? '',
+        tier,
+        ...(reopen ? { reopen: true } : {}),
+        ...(hasSituational ? { situational_context: situationalContextRaw } : {}),
+        ...(outputSchema !== null ? { output_schema: outputSchema } : {}),
+        ...(senderFrom !== undefined ? { from: senderFrom } : {}),
+    }).catch(rethrowAsCliError);
+    const guidance = res.revived
+        ? 'Delivered — the dormant target was revived to receive it.'
+        : tier === 'deferred'
+            ? "Delivered — held for the target's next natural cycle; not revived."
+            : 'Delivered.';
+    return { revived: res.revived, guidance };
 }
 const nodeMessageSend = defineLeaf({
     name: 'send',
@@ -132,7 +111,7 @@ const nodeMessageSend = defineLeaf({
         params: messageSendParams(),
         output: messageOutput(),
         outputKind: 'object',
-        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery may revive a dormant target; deferred waits for its next natural cycle.', '--reopen clears a finalized target\'s finalization latch before delivery, allowing it to take a new mandate. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted.'],
+        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery may revive a dormant target; deferred waits for its next natural cycle.', '--reopen commits the target resident and clears any finalization latch before delivery, allowing it to take a new mandate; it is valid for live, parked, and finalized targets. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted.'],
     },
     run: (input) => runMessageEngine(input),
     render: (r) => String(r['guidance']),