@north-light/crouter 0.3.299 → 0.3.301

package/dist/commands/__tests__/node-message.test.js

@@ -1,14 +1,99 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { renderLeafArgv } from '../../core/help.js';
+import { PassThrough } from 'node:stream';
+import { parseArgv } from '../../core/command.js';
+import { renderBranch, renderLeafArgv } from '../../core/help.js';
 import { nodeMessage } from '../node/message.js';
+function messageLeaf(name) {
+    const leaf = nodeMessage.children.find((child) => child.kind === 'leaf' && child.name === name);
+    if (leaf === undefined || leaf.kind !== 'leaf')
+        assert.fail(`node message ${name} leaf is missing`);
+    return leaf;
+}
+async function withFakeStdin(fake, fn) {
+    const real = process.stdin;
+    Object.defineProperty(process, 'stdin', { value: fake, configurable: true });
+    try {
+        return await fn();
+    }
+    finally {
+        Object.defineProperty(process, 'stdin', { value: real, configurable: true });
+    }
+}
+function pipedStdin(body) {
+    const stdin = new PassThrough();
+    stdin.end(body);
+    return stdin;
+}
+test('node message help names the target flag in the family and both child rubrics', () => {
+    const rendered = renderBranch(nodeMessage.help);
+    assert.match(rendered, /targeted with `--to <node-id>` or `--self`/);
+    assert.match(rendered, /send[\s\S]*?whenToUse="a target chosen with `--to <node-id>` or `--self` should have information/);
+    assert.match(rendered, /request[\s\S]*?whenToUse="a target chosen with `--to <node-id>` or `--self` must hand back one answer/);
+});
 test('node message send help documents the reopen re-task semantics', () => {
-    const send = nodeMessage.children.find((child) => child.kind === 'leaf' && child.name === 'send');
-    if (send === undefined || send.kind !== 'leaf')
-        assert.fail('node message send leaf is missing');
-    const rendered = renderLeafArgv(send.help);
+    const rendered = renderLeafArgv(messageLeaf('send').help);
     assert.match(rendered, /--reopen/);
     assert.match(rendered, /Re-task the target: commits it resident and clears any finalization latch before delivery/);
     assert.match(rendered, /valid for live, parked, and finalized targets/);
     assert.match(rendered, /Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted/);
 });
+test('node message send explains a positional node id without a target flag', async () => {
+    const send = messageLeaf('send');
+    const nodeId = '3zl47w7d-mtqb57ts-74ea25fe';
+    await assert.rejects(() => send.run({ body: nodeId }), (error) => {
+        assert.equal(error.code, 'bad_target');
+        assert.equal(error.message, 'no target given — the message body is not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.');
+        return true;
+    });
+    const params = send.help.params;
+    if (params === undefined)
+        assert.fail('node message send input schema is missing');
+    await withFakeStdin(pipedStdin('A long message body.'), () => assert.rejects(() => parseArgv(params, [nodeId]), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'no target given — the positional argument is the message body, not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.');
+        return true;
+    }));
+});
+test('node message request gives the same no-target guidance', async () => {
+    const request = messageLeaf('request');
+    const nodeId = '3zl47w7d-mtqb57ts-74ea25fe';
+    await assert.rejects(() => request.run({ body: nodeId, outputSchema: '{}' }), (error) => {
+        assert.equal(error.code, 'bad_target');
+        assert.equal(error.message, 'no target given — the message body is not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.');
+        return true;
+    });
+    const params = request.help.params;
+    if (params === undefined)
+        assert.fail('node message request input schema is missing');
+    await withFakeStdin(pipedStdin('A long message body.'), () => assert.rejects(() => parseArgv(params, [nodeId]), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'no target given — the positional argument is the message body, not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.');
+        return true;
+    }));
+});
+test('a targeted node message keeps positional-body parsing and generic stdin conflicts', async () => {
+    const send = messageLeaf('send');
+    const params = send.help.params;
+    if (params === undefined)
+        assert.fail('node message send input schema is missing');
+    const parsed = await withFakeStdin(pipedStdin(''), () => parseArgv(params, ['message body', '--to', 'target-node']));
+    assert.equal(parsed['body'], 'message body');
+    assert.equal(parsed['to'], 'target-node');
+    const genericParams = [{ kind: 'stdin', name: 'body', required: false, constraint: 'body' }];
+    await withFakeStdin(pipedStdin('A long message body.'), () => assert.rejects(() => parseArgv(genericParams, ['message body']), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'both a positional argument ("message body") and piped stdin were provided for body');
+        assert.equal(error.details?.field, 'body');
+        assert.equal(error.details?.next, 'Pass exactly one: either the positional argument or piped stdin, not both.');
+        return true;
+    }));
+});

package/dist/commands/node/create.js

@@ -83,7 +83,7 @@ function nodeNewParams() {
         { 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: 'resident', type: 'bool', required: false, constraint: 'Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Applies to managed children and roots; roots default to resident.' },
+        { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Pass it ONLY when the user will open this node’s viewer pane and work with it back and forth; a child that only other nodes message stays terminal. Applies to managed children and roots; roots default to resident.' },
         { 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.' },
         {

package/dist/commands/node/lifecycle.js

@@ -3,6 +3,8 @@ import { envNodeId } from '../../shared/env.js';
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+import { contextDir } from '../../core/canvas/paths.js';
+import { DEFAULT_BASH_NICENESS, MAX_BASH_NICENESS, writeBashNiceness } from '../../core/bash-jobs.js';
 import { nodeReviveLeaf } from '../node-lifecycle-revive.js';
 import { assertKind, kindsStateBlock } from './create.js';
 import { MODEL_SPEC_FORMS } from '../../core/runtime/model-selection.js';
@@ -140,6 +142,7 @@ export const nodeConfig = defineLeaf({
             { 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.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Rename the node; if the node has a live window, also rename that viewer window.' },
+            { kind: 'flag', name: 'nice', type: 'int', required: false, constraint: `Scheduler niceness every command this node's bash tool starts at, 0–${MAX_BASH_NICENESS} (default ${DEFAULT_BASH_NICENESS}). ${DEFAULT_BASH_NICENESS} keeps the node's builds and test suites below the daemon, the brokers, the viewers, and the person's own shell; 0 lets them compete on equal terms with everything else on the host; ${MAX_BASH_NICENESS} makes them yield to it. Applies to the node's very next command, foreground and background alike.` },
             { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Repair-only replacement launch directory. Must be a non-empty absolute existing directory and used alone; the daemon accepts it only for a dormant, non-forked node with no open managed worktree whose recorded cwd is gone. Clears the saved Pi session, so the next revive starts fresh while durable node work remains.' },
         ],
         output: [
@@ -149,6 +152,7 @@ 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: 'nice', type: 'number', required: false, constraint: 'The new bash niceness, present only when --nice changed it.' },
             { name: 'cwd', type: 'string', required: false, constraint: 'The lexically resolved replacement directory, present only after a cwd repair.' },
         ],
         outputKind: 'object',
@@ -157,6 +161,7 @@ export const nodeConfig = defineLeaf({
             '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.',
             'A cwd repair writes only the lexically resolved cwd and clears saved Pi session pointers; the old transcript and durable node work remain untouched.',
+            'A niceness change is stored with the node\'s own bash-job state, so it takes effect on the next command without a revive and survives one.',
         ],
         dynamicState: () => kindsStateBlock(),
     },
@@ -169,7 +174,7 @@ export const nodeConfig = defineLeaf({
         // clean listing error, and re-validated server-side against the TARGET
         // node's scope as a backstop.
         const cwdSpec = input['cwd'];
-        if (cwdSpec !== undefined && ['model', 'kind', 'lifecycle', 'mode', 'name'].some((flag) => input[flag] !== undefined)) {
+        if (cwdSpec !== undefined && ['model', 'kind', 'lifecycle', 'mode', 'name', 'nice'].some((flag) => input[flag] !== undefined)) {
             throw new InputError({ error: 'cwd_not_exclusive', message: 'cwd repair cannot be combined with another config flag', field: 'cwd', next: 'Pass --cwd alone.' });
         }
         const modelSpec = input['model']?.trim();
@@ -180,6 +185,15 @@ export const nodeConfig = defineLeaf({
         const lifecycleSpec = input['lifecycle']?.trim();
         const modeSpec = input['mode']?.trim();
         const nameSpec = input['name'];
+        const niceSpec = input['nice'];
+        if (niceSpec !== undefined && (niceSpec < 0 || niceSpec > MAX_BASH_NICENESS)) {
+            throw new InputError({
+                error: 'bad_nice',
+                message: `niceness must be between 0 and ${MAX_BASH_NICENESS}: ${niceSpec}`,
+                field: 'nice',
+                next: `A negative niceness needs root, so pass 0–${MAX_BASH_NICENESS}.`,
+            });
+        }
         if (kindSpec !== undefined)
             assertKind(kindSpec);
         if (lifecycleSpec !== undefined && lifecycleSpec.toLowerCase() !== 'terminal' && lifecycleSpec.toLowerCase() !== 'resident') {
@@ -214,8 +228,17 @@ export const nodeConfig = defineLeaf({
             patch.cwd = cwdSpec;
             applied.push('cwd');
         }
+        // Niceness is node-local bash-lane state, not canvas state: it is stored
+        // beside this node's job dirs so the valve reads it when it starts the next
+        // command, rather than waiting for a launch recipe to be rebuilt.
+        if (niceSpec !== undefined) {
+            writeBashNiceness(contextDir(nodeId), niceSpec);
+            applied.push('nice');
+            if (applied.length === 1)
+                return { node_id: nodeId, nice: niceSpec };
+        }
         if (applied.length === 0) {
-            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name, --cwd.' });
+            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name, --nice, --cwd.' });
         }
         const detail = await cliClient()
             .patchConfig(nodeId, patch)
@@ -233,6 +256,8 @@ export const nodeConfig = defineLeaf({
             result.mode = detail.mode;
         if (applied.includes('name'))
             result.name = detail.name;
+        if (applied.includes('nice'))
+            result.nice = niceSpec;
         return result;
     },
     render: (r) => {
@@ -249,6 +274,8 @@ export const nodeConfig = defineLeaf({
             bits.push(`mode=${r['mode']}`);
         if (r['name'] !== undefined)
             bits.push(`name=${r['name']}`);
+        if (r['nice'] !== undefined)
+            bits.push(`nice=${r['nice']}`);
         return `Configured ${r['node_id']} — ${bits.join(', ')}`;
     },
 });

package/dist/commands/node/message.js

@@ -11,15 +11,16 @@ function requireNonBlankDiscriminant(input, name) {
         throw new InputError({ error: 'empty_discriminant', message: `--${flag} must contain non-whitespace text`, received: typeof value === 'string' ? value : String(value), field: flag, next: `Pass a non-empty --${flag} value, or omit the flag.` });
     }
 }
-async function resolveMsgTarget(input) {
+async function resolveMsgTarget(input, hasBody) {
     const to = input['to']?.trim();
     const self = input['self'] === true;
     const hasTo = to !== undefined && to !== '';
     if (hasTo === self) {
         throw new InputError({
             error: 'bad_target',
-            message: hasTo && self ? '--to and --self are mutually exclusive' : 'exactly one of --to or --self is required',
-            next: 'Pass --to <node-id> or --self.',
+            message: hasTo && self ? '--to and --self are mutually exclusive' : hasBody ? 'no target given — the message body is not a node id' : 'exactly one of --to or --self is required',
+            field: hasTo ? undefined : 'to',
+            next: hasTo ? 'Pass --to <node-id> or --self.' : hasBody ? 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.' : 'Pass --to <node-id> or --self.',
         });
     }
     if (self) {
@@ -41,9 +42,19 @@ function messageOutput() {
         { name: 'guidance', type: 'string', required: true, constraint: 'Immediate action confirmation.' },
     ];
 }
+function missingMessageTargetForBody(input) {
+    const to = input['to']?.trim();
+    if ((to !== undefined && to !== '') || input['self'] === true)
+        return undefined;
+    return {
+        message: 'no target given — the positional argument is the message body, not a node id',
+        field: 'to',
+        next: 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.',
+    };
+}
 function messageSendParams() {
     return [
-        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.' },
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.', positionalStdinConflict: missingMessageTargetForBody },
         { 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, except a terminal one, which has no later cycle to read it on and is raised to urgent.' },
@@ -53,7 +64,7 @@ function messageSendParams() {
 }
 function messageRequestParams() {
     return [
-        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.' },
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.', positionalStdinConflict: missingMessageTargetForBody },
         { 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. Every accepted tier may revive a dormant target, because the request must be answered; deferred is rejected for that reason.' },
@@ -68,10 +79,10 @@ 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 } = await resolveMsgTarget(input);
     const bodyRaw = input['body'];
     const body = bodyRaw !== undefined ? bodyRaw.trim() : undefined;
     const hasBody = body !== undefined && body !== '';
+    const { targetId } = await resolveMsgTarget(input, hasBody);
     const tierRaw = input['tier'];
     const hasTier = tierRaw !== undefined && tierRaw !== '';
     const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
@@ -107,7 +118,7 @@ async function runMessageEngine(input) {
 const nodeMessageSend = defineLeaf({
     name: 'send',
     description: 'deliver an inbox message to an existing node immediately',
-    whenToUse: 'a node that already exists should have information or new direction now — steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node’s pushes rather than this one delivery',
+    whenToUse: 'a target chosen with `--to <node-id>` or `--self` should have information or new direction now — steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node’s pushes rather than this one delivery',
     help: {
         name: 'node message send',
         summary: 'deliver an inbox message to an existing node immediately',
@@ -122,7 +133,7 @@ const nodeMessageSend = defineLeaf({
 const nodeMessageRequest = defineLeaf({
     name: 'request',
     description: 'deliver an immediate typed-output request to an existing node',
-    whenToUse: 'a node that already exists must hand back one answer in a shape you fix — a choice among options, a structured extraction, a verdict your own logic will branch on — or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target’s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent',
+    whenToUse: 'a target chosen with `--to <node-id>` or `--self` must hand back one answer in a shape you fix — a choice among options, a structured extraction, a verdict your own logic will branch on — or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target’s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent',
     help: {
         name: 'node message request',
         summary: 'deliver an immediate typed-output request to an existing node',
@@ -144,7 +155,7 @@ export const nodeMessage = defineBranch({
     help: {
         name: 'node message',
         summary: 'deliver one immediate inbox entry to an existing node',
-        model: 'Both children append one inbox entry to a node that already exists, targeted by id or --self, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
+        model: 'Both children append one inbox entry to a node that already exists, targeted with `--to <node-id>` or `--self`, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
     },
     children: [nodeMessageSend, nodeMessageRequest],
 });

package/dist/core/__tests__/human-action-delivery.test.js

@@ -5,7 +5,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { claimActionDelivery, enqueueActionDelivery, readActionDelivery, } from '../canvas/human-deliveries.js';
-import { actionDeliveryBackoffMs, actionDeliverySettlementForOutcome, deliverAction, } from '../../daemon/human/deliver-action.js';
+import { deliveryBackoffMs } from '../canvas/delivery-contract.js';
+import { deliverySettlementForOutcome } from '../../daemon/delivery/run-delivery.js';
+import { deliverAction } from '../../daemon/human/deliver-action.js';
 let home;
 const priorHome = process.env['CRTR_HOME'];
 beforeEach(() => {
@@ -25,14 +27,14 @@ after(() => {
     else
         process.env['CRTR_HOME'] = priorHome;
 });
-test('action delivery retries follow the durable backoff and exit boundary', () => {
-    assert.equal(actionDeliveryBackoffMs(1), 5_000);
-    assert.equal(actionDeliveryBackoffMs(2), 10_000);
-    assert.equal(actionDeliveryBackoffMs(3), 20_000);
-    assert.equal(actionDeliveryBackoffMs(11), 3_600_000);
-    assert.equal(actionDeliveryBackoffMs(100), 3_600_000);
+test('delivery retries follow the durable backoff and exit boundary', () => {
+    assert.equal(deliveryBackoffMs(1), 5_000);
+    assert.equal(deliveryBackoffMs(2), 10_000);
+    assert.equal(deliveryBackoffMs(3), 20_000);
+    assert.equal(deliveryBackoffMs(11), 3_600_000);
+    assert.equal(deliveryBackoffMs(100), 3_600_000);
     const now = 1_000_000;
-    const outcome = (exitCode, signal = null) => actionDeliverySettlementForOutcome({
+    const outcome = (exitCode, signal = null) => deliverySettlementForOutcome({
         exitCode,
         signal,
         timedOut: false,
@@ -50,14 +52,14 @@ test('action delivery retries follow the durable backoff and exit boundary', ()
     });
     assert.equal(outcome(79).state, 'pending');
     assert.equal(outcome(null, 'SIGTERM').state, 'pending');
-    assert.equal(actionDeliverySettlementForOutcome({
+    assert.equal(deliverySettlementForOutcome({
         exitCode: null,
         signal: null,
         timedOut: true,
         stderr: '',
     }, 1, now).state, 'pending');
     // The kill escalation's signal is the only way to tell the graceful term from the SIGKILL.
-    assert.deepEqual(actionDeliverySettlementForOutcome({
+    assert.deepEqual(deliverySettlementForOutcome({
         exitCode: null,
         signal: 'SIGKILL',
         timedOut: true,
@@ -67,7 +69,7 @@ test('action delivery retries follow the durable backoff and exit boundary', ()
         nextAttemptAt: now + 5_000,
         failure: { kind: 'timeout', signal: 'SIGKILL', stderr: 'stalled' },
     });
-    assert.equal(actionDeliverySettlementForOutcome({
+    assert.equal(deliverySettlementForOutcome({
         exitCode: null,
         signal: null,
         timedOut: false,

package/dist/core/__tests__/node-outcome.test.js

@@ -6,7 +6,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb, MIGRATIONS } from '../canvas/db.js';
 import { createNode, getRow } from '../canvas/canvas.js';
-import { armOutcomeDelivery, claimOutcomeDelivery, outcomeDeliveryBackoffMs, readOutcomeDelivery, recoverRunningOutcomeDeliveries, settleOutcomeDelivery, } from '../canvas/node-outcome-deliveries.js';
+import { armOutcomeDelivery, claimOutcomeDelivery, readOutcomeDelivery, recoverRunningOutcomeDeliveries, settleOutcomeDelivery, } from '../canvas/node-outcome-deliveries.js';
 import { transition } from '../runtime/lifecycle.js';
 import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
 import { pushFinal } from '../feed/feed.js';
@@ -153,11 +153,6 @@ test('outcome delivery state is fenced, recoverable, and follows the durable bac
         nextAttemptAt: readOutcomeDelivery('recover').nextAttemptAt,
         claimOwner: readOutcomeDelivery('recover').claimOwner,
     }, { state: 'pending', nextAttemptAt: recoveredAt, claimOwner: null });
-    assert.equal(outcomeDeliveryBackoffMs(1), 5_000);
-    assert.equal(outcomeDeliveryBackoffMs(2), 10_000);
-    assert.equal(outcomeDeliveryBackoffMs(3), 20_000);
-    assert.equal(outcomeDeliveryBackoffMs(11), 3_600_000);
-    assert.equal(outcomeDeliveryBackoffMs(100), 3_600_000);
 });
 test('v39 migrates a v38 database and backfills finalized and terminal rows', () => {
     const dbPath = join(home, 'v38.db');

package/dist/core/bash-jobs.d.ts

@@ -36,6 +36,28 @@ export declare function readJobPgid(contextDir: string, jobId: string): number |
 /** The optional human-readable job label. Jobs created before labels existed
  * have no file and deliberately project null. */
 export declare function readJobPurpose(contextDir: string, jobId: string): string | null;
+/** Scheduler niceness every command a node runs is started with. Agent work —
+ * builds, test suites, typechecks — sits below the daemon, the brokers, the
+ * viewers, and the person's own shell, so a fan-out of release builds cannot
+ * starve them: the scheduler only honors this under contention and it costs
+ * nothing on an idle host. */
+export declare const DEFAULT_BASH_NICENESS = 10;
+/** The politest priority the scheduler accepts. A NEGATIVE niceness (more
+ * priority than the broker itself) needs root: `nice` prints a permission error
+ * into the command's own log and runs it at the inherited priority anyway, so
+ * the override range stops at 0. */
+export declare const MAX_BASH_NICENESS = 19;
+/** Per-node override of the bash niceness, written by `crtr node config --nice`
+ * and read by the valve when it starts each command. Node-local like the job
+ * dirs beside it, so a change applies to the node's very next command without
+ * waiting for a revive. */
+export declare function bashNicenessPath(contextDir: string): string;
+/** The niceness this node's commands run at. Any missing, malformed, or
+ * out-of-range file reads as the default rather than an odd priority. */
+export declare function readBashNiceness(contextDir: string): number;
+/** Set the node's bash niceness. The caller owns validation; the store keeps
+ * one integer so the valve's read stays a single file read per command. */
+export declare function writeBashNiceness(contextDir: string, niceness: number): void;
 /** The auto-background cancel deadline (epoch ms), or undefined for a job with
  * no deadline (a deliberate handoff, or a legacy job dir). A non-finite or
  * malformed file reads as no deadline rather than an instant expiry. */

package/dist/core/bash-jobs.js

@@ -3,7 +3,7 @@
 // job.bg, while foreground completion renames it to job.done. The detached
 // supervisor can therefore outlive pi and still decide whether to report exit.
 import { randomBytes } from 'node:crypto';
-import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 const MAX_BASH_JOB_PURPOSE_BYTES = 280;
 /** A purpose is display text, never shell input. Keep the file-backed control
@@ -66,6 +66,43 @@ export function readJobPurpose(contextDir, jobId) {
         return null;
     }
 }
+/** Scheduler niceness every command a node runs is started with. Agent work —
+ * builds, test suites, typechecks — sits below the daemon, the brokers, the
+ * viewers, and the person's own shell, so a fan-out of release builds cannot
+ * starve them: the scheduler only honors this under contention and it costs
+ * nothing on an idle host. */
+export const DEFAULT_BASH_NICENESS = 10;
+/** The politest priority the scheduler accepts. A NEGATIVE niceness (more
+ * priority than the broker itself) needs root: `nice` prints a permission error
+ * into the command's own log and runs it at the inherited priority anyway, so
+ * the override range stops at 0. */
+export const MAX_BASH_NICENESS = 19;
+/** Per-node override of the bash niceness, written by `crtr node config --nice`
+ * and read by the valve when it starts each command. Node-local like the job
+ * dirs beside it, so a change applies to the node's very next command without
+ * waiting for a revive. */
+export function bashNicenessPath(contextDir) {
+    return join(bashJobsDir(contextDir), 'niceness');
+}
+/** The niceness this node's commands run at. Any missing, malformed, or
+ * out-of-range file reads as the default rather than an odd priority. */
+export function readBashNiceness(contextDir) {
+    try {
+        const n = Number(readFileSync(bashNicenessPath(contextDir), 'utf8').trim());
+        if (!Number.isInteger(n) || n < 0 || n > MAX_BASH_NICENESS)
+            return DEFAULT_BASH_NICENESS;
+        return n;
+    }
+    catch {
+        return DEFAULT_BASH_NICENESS;
+    }
+}
+/** Set the node's bash niceness. The caller owns validation; the store keeps
+ * one integer so the valve's read stays a single file read per command. */
+export function writeBashNiceness(contextDir, niceness) {
+    mkdirSync(bashJobsDir(contextDir), { recursive: true });
+    writeFileSync(bashNicenessPath(contextDir), `${Math.trunc(niceness)}\n`);
+}
 /** The auto-background cancel deadline (epoch ms), or undefined for a job with
  * no deadline (a deliberate handoff, or a legacy job dir). A non-finite or
  * malformed file reads as no deadline rather than an instant expiry. */

package/dist/core/canvas/delivery-contract.d.ts

@@ -0,0 +1,19 @@
+export interface DeliveryFailure {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exitCode?: number;
+    signal?: string;
+    message?: string;
+    stderr?: string;
+}
+export type DeliverySettlement = {
+    state: 'accepted';
+} | {
+    state: 'permanent_failed';
+    failure: DeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: DeliveryFailure;
+};
+/** Durable exponential retry delay for the attempt that just failed. */
+export declare function deliveryBackoffMs(attempt: number): number;

package/dist/core/canvas/delivery-contract.js

@@ -0,0 +1,8 @@
+// The durable contract shared by every retried delivery: what a failed attempt
+// records, how an attempt settles, and when the next attempt becomes due. The
+// canvas modules own the rows; `daemon/delivery/run-delivery.ts` owns the
+// process that produces these settlements.
+/** Durable exponential retry delay for the attempt that just failed. */
+export function deliveryBackoffMs(attempt) {
+    return Math.min(5_000 * 2 ** (attempt - 1), 3_600_000);
+}

package/dist/core/canvas/human-deliveries.d.ts

@@ -1,11 +1,6 @@
+import type { DeliveryFailure, DeliverySettlement } from './delivery-contract.js';
 export type ActionDeliveryState = 'pending' | 'running' | 'accepted' | 'permanent_failed';
-export interface ActionDeliveryFailure {
-    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
-    exitCode?: number;
-    signal?: string;
-    message?: string;
-    stderr?: string;
-}
+export type ActionDeliveryFailure = DeliveryFailure;
 export interface ActionDeliveryRecord {
     requestId: string;
     state: ActionDeliveryState;
@@ -37,16 +32,7 @@ export declare function readActionDelivery(requestId: string): ActionDeliveryRec
 export declare function dueActionDeliveries(now: number): ActionDeliveryRecord[];
 /** Atomically start one due delivery attempt. A null result lost the claim. */
 export declare function claimActionDelivery(requestId: string, now: number, claimOwner: string): ActionDeliveryRecord | null;
-export type ActionDeliverySettlement = {
-    state: 'accepted';
-} | {
-    state: 'permanent_failed';
-    failure: ActionDeliveryFailure;
-} | {
-    state: 'pending';
-    nextAttemptAt: number;
-    failure: ActionDeliveryFailure;
-};
+export type ActionDeliverySettlement = DeliverySettlement;
 /** Settle only the still-owned running attempt, so a stale process cannot overwrite a newer claim. */
 export declare function settleActionDelivery(requestId: string, attempt: number, claimOwner: string, settlement: ActionDeliverySettlement, now: number): boolean;
 /** A new daemon deliberately redelivers interrupted completions at least once. */

package/dist/core/canvas/node-outcome-deliveries.d.ts

@@ -1,14 +1,7 @@
+import type { DeliveryFailure, DeliverySettlement } from './delivery-contract.js';
 import { type NodeOutcomeKind, type TerminalReason } from './types.js';
 export type OutcomeDeliveryState = 'armed' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
-export interface OutcomeDeliveryFailure {
-    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
-    exitCode?: number;
-    signal?: string;
-    message?: string;
-    stderr?: string;
-}
-/** Durable exponential retry delay for the attempt that just failed. */
-export declare function outcomeDeliveryBackoffMs(attempt: number): number;
+export type OutcomeDeliveryFailure = DeliveryFailure;
 export interface OutcomeDeliveryRecord {
     nodeId: string;
     state: OutcomeDeliveryState;
@@ -61,16 +54,7 @@ export declare function armOutcomeDelivery(row: {
 export declare function readOutcomeDelivery(nodeId: string): OutcomeDeliveryRecord | null;
 export declare function dueOutcomeDeliveries(now: number): OutcomeDeliveryRecord[];
 export declare function claimOutcomeDelivery(nodeId: string, now: number, claimOwner: string): OutcomeDeliveryRecord | null;
-export type OutcomeDeliverySettlement = {
-    state: 'accepted';
-} | {
-    state: 'permanent_failed';
-    failure: OutcomeDeliveryFailure;
-} | {
-    state: 'pending';
-    nextAttemptAt: number;
-    failure: OutcomeDeliveryFailure;
-};
+export type OutcomeDeliverySettlement = DeliverySettlement;
 /** Settle only the still-owned running attempt, fencing stale delivery processes. */
 export declare function settleOutcomeDelivery(nodeId: string, attempt: number, claimOwner: string, settlement: OutcomeDeliverySettlement, now: number): boolean;
 export declare function recoverRunningOutcomeDeliveries(now: number): number;

package/dist/core/canvas/node-outcome-deliveries.js

@@ -3,10 +3,6 @@ import { openDb, withCanvasWrite } from './db.js';
 import { getNode } from './canvas.js';
 import { OUTCOME_PAYLOAD_MAX_BYTES } from './types.js';
 import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
-/** Durable exponential retry delay for the attempt that just failed. */
-export function outcomeDeliveryBackoffMs(attempt) {
-    return Math.min(5_000 * 2 ** (attempt - 1), 3_600_000);
-}
 function serializedPayload(payload) {
     if (payload === undefined)
         return null;

package/dist/core/command.js

@@ -503,7 +503,8 @@ export async function parseArgv(params, tokens, options) {
                 // whole invocation waiting for a close that will never come.
                 const piped = await peekStdinRaw();
                 if (piped.trim() !== '') {
-                    throw parseArgvError('bad_invocation', `both a positional argument ("${positionalValue}") and piped stdin were provided for ${stdinParam.name}`, positionalValue, stdinParam.name, `Pass exactly one: either the positional argument or piped stdin, not both.`);
+                    const conflict = stdinParam.positionalStdinConflict?.(result);
+                    throw parseArgvError('bad_invocation', conflict?.message ?? `both a positional argument ("${positionalValue}") and piped stdin were provided for ${stdinParam.name}`, positionalValue, conflict?.field ?? stdinParam.name, conflict?.next ?? `Pass exactly one: either the positional argument or piped stdin, not both.`);
                 }
                 result[flagNameToKey(stdinParam.name)] = positionalValue;
                 stdinWasSupplied = true; // positional supplying stdin counts as supplied

package/dist/core/help.d.ts

@@ -87,6 +87,13 @@ export interface StdinParam {
     /** Whether one positional token may supply stdin instead of a pipe. Defaults
      * to true for existing stdin-body leaves; false requires actual stdin. */
     allowPositional?: boolean;
+    /** Optional leaf-specific recovery when a positional stdin body collides with
+     * piped stdin. Return undefined to keep the generic collision error. */
+    positionalStdinConflict?: (input: Readonly<Record<string, unknown>>) => {
+        message: string;
+        field?: string;
+        next: string;
+    } | undefined;
 }
 /** --context-file PATH: reads and JSON-parses the file at PATH. */
 export interface ContextFileParam {

package/dist/core/keybindings/catalog.js

@@ -84,7 +84,7 @@ export const BINDING_CATALOG = Object.freeze([
     ...attachEntry('crtr.tmux.menu.attach.model-ladder.previous', 'crtr.attach.model-ladder.previous', 'Previous model', 'Move to the previous model ladder rung.', ['['], ['alt+shift+m']),
     ...attachEntry('crtr.tmux.menu.attach.command.inspect', 'crtr.attach.command.inspect', 'Inspect loaded command', 'Open the loaded slash command’s expanded prompt.', ['h'], ['alt+shift+h']),
     ...attachEntry('crtr.tmux.menu.attach.file-review', 'crtr.attach.file-review', 'Review a file', 'Open a line-anchored review of a file named in the transcript.', [], ['alt+shift+r']),
-    ...attachEntry('crtr.tmux.menu.attach.profile-files', 'crtr.attach.profile-files', 'Search profile files', 'Fuzzy-match path segments across the node family’s working directories, profile projects and memory, and ancestor crouter memory stores; Ctrl+Y copies a selected path.', ['f'], ['ctrl+f']),
+    ...attachEntry('crtr.tmux.menu.attach.profile-files', 'crtr.attach.profile-files', 'Search profile files', 'Fuzzy-match path segments across the node family’s working directories, their context and reports directories, profile projects and memory, and ancestor crouter memory stores; Ctrl+Y copies a selected path.', ['f'], ['ctrl+f']),
     ...attachEntry('crtr.tmux.menu.attach.search', 'crtr.attach.search', 'Search transcript', 'Search the transcript as it is currently displayed — folded tool output is not searched until it is unfolded.', ['/'], ['alt+/']),
     ...attachEntry('crtr.tmux.menu.attach.whip', 'crtr.attach.whip', 'Whip agent', 'Interrupt the agent and send a playful command.', ['w'], []),
     b('crtr.attach.scroll.up', 'Attach', 'Scroll up', 'Scroll the transcript one line up.', ['shift+up'], 'terminal', ATTACH_CONTEXTS),