@north-light/api 0.3.580 → 0.3.588

package/dist/commands/human.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerHuman(): BranchDef;

package/dist/commands/human.js

@@ -0,0 +1,63 @@
+// `crtr human` creates durable pages and review tickets for human decisions.
+//
+// Send optionally creates a reply bridge; review creation asks crtrd to create
+// a ticket, daemon-owned review, and companion. Show is passive display.
+import { defineBranch } from '../core/command.js';
+import { readConfig } from '../core/config.js';
+import { personHasSnapshot } from '../core/scoped-state/person-store.js';
+import { humanSend, humanShow } from './human/prompts.js';
+import { humanList, humanResolve, humanCancel } from './human/queue.js';
+import { humanReviewBranch } from './human/review.js';
+import { humanFeedbackBranch } from './human/feedback.js';
+import { humanComponents } from './human/components.js';
+import { humanRequestBranch } from './human/request.js';
+import { pageHelpText } from './human/shared.js';
+export function registerHuman() {
+    // `page_surface` marks a host whose human surface is a rendered page product
+    // rather than a terminal. Review and show are terminal-only: a review is a
+    // live editor session with anchored comments driven by a companion node, and
+    // show is a passive tmux live-watch. Such a host can render neither, so both
+    // leave the surface entirely instead of filing tickets nobody can open.
+    // Help still reflects an existing host setting, but a fresh host must not
+    // read settings that are not loaded just to render the command tree.
+    const pageSurface = personHasSnapshot() && readConfig('user').page_surface;
+    const pageHelp = pageHelpText(pageSurface);
+    const concept = pageSurface
+        ? 'human-in-the-loop decisions and structured pages'
+        : 'human-in-the-loop decisions, document review, and live display';
+    const durableRequests = '`request` publishes the same page with no bridge at all, for a caller that will have exited before the answer arrives: its outcome is read back or carried to a named local action.';
+    const ticketModel = pageSurface
+        ? `Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${durableRequests}`
+        : `Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${durableRequests} \`review\` is for live document review with anchored comments; \`show\` is a passive tmux live-watch rather than a ticket.`;
+    return defineBranch({
+        name: 'human',
+        extensible: true,
+        rootEntry: {
+            concept,
+            desc: pageSurface ? 'send, components, feedback, cancel, list' : 'send, review new/comment, show, cancel, list',
+            useWhen: pageHelp.rootUseWhen,
+        },
+        help: {
+            name: 'human',
+            summary: concept,
+            model: [
+                ticketModel,
+                pageHelp.brief,
+                pageHelp.authoring,
+                pageHelp.componentSelection.join('\n'),
+                'Props, response contracts, and the full component catalog: `crtr human components`; select with `crtr human components list`, then read one with `crtr human components show <component>`.',
+            ].join('\n\n'),
+        },
+        children: [
+            humanComponents,
+            humanSend(pageSurface),
+            ...(pageSurface ? [] : [humanReviewBranch]),
+            humanFeedbackBranch,
+            ...(pageSurface ? [] : [humanShow]),
+            humanRequestBranch,
+            humanCancel,
+            humanList,
+            humanResolve,
+        ],
+    });
+}

package/dist/commands/node/bash.d.ts

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

package/dist/commands/node/bash.js

@@ -0,0 +1,390 @@
+// `crtr node bash` — file-backed background job controls.
+import { envNodeId } from '../../shared/env.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { ExitCode } from '../../types.js';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { backgroundRunningBashJobs, bashJobCommandLine, bashJobPaths, formatBashElapsed, isSafeBashJobId, jobStartedAtMs, newBashJobId, tailJobLog } from '../../core/bash-jobs.js';
+import { parseDurationMs } from '../../core/wake.js';
+import { cliClient, getNodeOrNull } from '../api-client.js';
+import { ApiError } from '../../api/index.js';
+import { PREVIEW_RESULT_PATH_ENV } from '../../core/preview-result-path.js';
+import { nodeInPane } from '../surface/node/placement.js';
+function resolveBashTarget(input, missingMessage) {
+    const pane = input['pane'] ?? process.env['TMUX_PANE'];
+    let id = input['node'];
+    if (id === undefined || id === '')
+        id = nodeInPane(pane);
+    if (id === undefined || id === '')
+        id = envNodeId();
+    if (id === undefined || id === '') {
+        throw new InputError({ error: 'no_node', message: missingMessage, next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+    }
+    return { id, pane };
+}
+/** Patch one of the node's running jobs; a job that is gone or already ended is the caller's error to read. */
+async function patchRunningJob(nodeId, jobId, request) {
+    try {
+        await cliClient().patchBashJob(nodeId, jobId, request);
+    }
+    catch (error) {
+        if (error instanceof ApiError && (error.status === 404 || error.status === 409)) {
+            throw new InputError({ error: 'not_running', message: `background job ${jobId} for ${nodeId} is not running`, next: 'List live jobs with `crtr node bash list`.' });
+        }
+        throw error;
+    }
+}
+const nodeBashRun = defineLeaf({
+    name: 'run',
+    description: 'start a shell command as a background job and return at once',
+    whenToUse: 'a command needs longer than one tool call — a test lane, a build, a soak — and you should be woken with its exit code instead of waiting, backgrounding with `&`, or polling a log',
+    tier: 'normal',
+    help: {
+        name: 'node bash run',
+        summary: 'start one shell command as a background job owned by the calling node and return before it finishes',
+        params: [
+            { kind: 'positional', name: 'command', required: true, constraint: 'The shell command, run by bash from the current directory with this process’s environment. The same refusals apply as for a bash tool call, judged on this command.' },
+            { kind: 'flag', name: 'quiet-ok', type: 'bool', required: false, constraint: 'Pass for a job that legitimately sits idle — `gh run watch`, `sleep`, waiting on a lock, a `docker build` whose work runs outside the process tree — so it gets no silence messages. Omit it for anything that should be making progress.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'The job object’s id; read or watch it with `crtr canvas`, stop it with `node bash kill`.' },
+            { name: 'log_path', type: 'string', required: true, constraint: 'File receiving the command’s combined stdout and stderr, capped at 10 MiB.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Works only inside a node’s bash tool call; the job belongs to the calling node.',
+            'Starts the command detached from this call, so it keeps running after the call and the turn end. A `timeout` around this leaf bounds only the launch, not the job.',
+            'Records the job as a canvas object; when the command exits, its watchers (the calling node by default) get an urgent `exited` push with the exit code and log path.',
+            'Sets no cancel deadline: the job runs to completion unless stopped with `node bash kill`.',
+            'A job whose processes use almost no CPU and write to no open file for 15 minutes messages the calling node about it, again at 30 and 60 minutes, then hourly; activity restarts the schedule and nothing is stopped. `--quiet-ok` turns these messages off.',
+            'Fails, with the job id and log path, if the job could not be recorded; the command is then running but will not message the node when it exits.',
+        ],
+    },
+    run: async (input) => {
+        const command = input['command'];
+        const nodeId = envNodeId();
+        const contextDir = process.env['CRTR_CONTEXT_DIR'];
+        if (nodeId === undefined || nodeId === '' || contextDir === undefined || contextDir === '') {
+            throw new InputError({ error: 'no_node', message: '`node bash run` starts a job for the calling node and works only inside a node’s bash tool', next: 'Run it from a node’s bash tool call.' });
+        }
+        const cwd = process.cwd();
+        const { bashCommandRefusal } = await import('../../core/bash-guard.js');
+        const refusal = bashCommandRefusal(command, cwd);
+        if (refusal !== null) {
+            throw new InputError({ error: 'refused', message: refusal, next: 'Run a different command.' });
+        }
+        // job.bg is written, and job.run never is: the supervisor may finish before
+        // this process records the job, and a job already marked as backgrounded is
+        // recorded and its exit published regardless.
+        const paths = bashJobPaths(contextDir, newBashJobId());
+        mkdirSync(paths.dir, { recursive: true });
+        writeFileSync(paths.cmdSh, command);
+        writeFileSync(paths.jobLog, '');
+        writeFileSync(paths.jobBg, '');
+        const { launchBashJobSupervisor } = await import('../../core/runtime/broker/bash-job-launch.js');
+        // The tool call's preview-result file belongs to that call, not to a job that outlives it.
+        const { [PREVIEW_RESULT_PATH_ENV]: _preview, ...env } = process.env;
+        try {
+            await launchBashJobSupervisor(nodeId, paths, contextDir, cwd, env);
+        }
+        catch (error) {
+            // A marked job nobody launched would be adopted by the daemon and never exit.
+            rmSync(paths.dir, { recursive: true, force: true });
+            throw error;
+        }
+        const { recordBackgroundedJob } = await import('../../core/runtime/broker/daemon-ops.js');
+        try {
+            await recordBackgroundedJob(nodeId, paths.jobId, { command });
+            if (input['quietOk'] === true)
+                await cliClient().patchBashJob(nodeId, paths.jobId, { quiet_ok: true });
+        }
+        catch (error) {
+            throw new InputError({
+                error: 'job_not_recorded',
+                message: `job ${paths.jobId} is running but could not be recorded (${error.message}); it will NOT message you when it exits. Log: ${paths.jobLog}`,
+                next: `Watch it with \`tail -f ${paths.jobLog}\`, or stop it with \`crtr node bash kill ${paths.jobId}\`.`,
+            }, ExitCode.GENERAL);
+        }
+        return { job_id: paths.jobId, log_path: paths.jobLog };
+    },
+    render: (result) => `[backgrounded as job ${result['job_id']}. It will interrupt you with a message when it exits. Watch: tail -f ${result['log_path']} ; stop: crtr node bash kill ${result['job_id']}]`,
+});
+const nodeBashBackground = defineLeaf({
+    name: 'background',
+    description: 'hand the focused node’s running bash command to its background job system',
+    whenToUse: 'the tmux prefix menu invokes this when a foreground bash command should stop blocking the agent immediately but keep running as a file-backed background job',
+    tier: 'hidden',
+    help: {
+        name: 'node bash background',
+        summary: 'hand every running foreground bash command for one node to its file-backed background job system',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose running bash command to background. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE. The prefix menu passes this for you.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { 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',
+        effects: ['Signals every foreground bash command currently running for the node to return from its tool call immediately while its detached supervisor keeps the command running.', 'Each handed-off command retains its log under the node context jobs directory and becomes a job object; when it exits, the job’s watchers (its node by default) get an urgent `exited` push carrying the exit code and log path.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash handoff');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobs = backgroundRunningBashJobs(node.paths.context_dir);
+        const now = Date.now();
+        const elapsed = jobs.map((job) => ({ job_id: job.jobId, elapsed_ms: now - (jobStartedAtMs(job.jobId) ?? now) }));
+        // No tmux toast. A tmux status-line message commandeers the whole client's
+        // status bar for seconds over an action the user just took deliberately;
+        // the viewer reports its own handoff in its own status line, which is where
+        // someone watching that pane is already looking.
+        return { node_id: id, jobs: elapsed };
+    },
+    render: (result) => {
+        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 ${jobs.length} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
+    },
+});
+const nodeBashList = defineLeaf({
+    name: 'list',
+    description: 'list a node’s live background bash jobs',
+    whenToUse: 'you need the ids, commands, and ages of your jobs that are still running',
+    help: {
+        name: 'node bash list',
+        summary: 'read every still-running background bash job owned by one node',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose background jobs to list. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+            { kind: 'flag', name: 'tail', type: 'int', required: false, default: 0, constraint: 'Include this many trailing log lines per job (0 = none). Read from the local log file, so it is available only on the machine that runs the job; elsewhere log_tail is null — use `node bash log` there.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, purpose, started_at, elapsed_ms, deadline_at, output_key, log_path, pgid, log_tail} for every live background job; log_path and log_tail are null when the job’s log is not on this machine (a job running in a sandbox, listed from outside it), and no tail is available from here (`node bash log` reads its stored output); purpose is a human-readable label or null; deadline_at is the auto-cancel time or null for a job that runs to completion.' },
+        ],
+        outputKind: 'object',
+        effects: ['Reads the node’s running job rows and, for log_tail, the local log files. Changes nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job list');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const now = Date.now();
+        const tail = Math.max(0, Math.trunc(Number(input['tail'] ?? 0)));
+        const dir = node.paths.context_dir;
+        const jobs = (await cliClient().listBashJobs(node.node_id)).map((job) => {
+            // The log file is on the machine that runs the job; a CLI on another machine (outside a sandbox) has no such
+            // file, and the output is then only in the blob store under output_key.
+            const localLog = bashJobPaths(dir, job.job_id).jobLog;
+            const logPath = existsSync(localLog) ? localLog : null;
+            return {
+                job_id: job.job_id,
+                command: job.command,
+                purpose: job.purpose,
+                started_at: job.started_at,
+                elapsed_ms: job.elapsed_ms,
+                deadline_at: job.deadline_at,
+                output_key: job.output_key,
+                log_path: logPath,
+                pgid: job.pgid,
+                log_tail: logPath === null ? null : tailJobLog(logPath, tail),
+            };
+        });
+        return { node_id: node.node_id, jobs };
+    },
+    render: (result) => {
+        const jobs = result['jobs'];
+        if (jobs.length === 0)
+            return `No background bash jobs for ${result['node_id']}.`;
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${bashJobCommandLine(job.command)}${job.purpose === null ? '' : `\n  purpose: ${job.purpose}`}${job.deadline_at === null ? '' : `\n  cancels at: ${job.deadline_at}`}\n  ${job.log_path === null ? `log: not on this machine (the job runs in a sandbox); read its output with \`crtr node bash log ${job.job_id} --node ${result['node_id']}\`` : `log: ${job.log_path}`}`).join('\n');
+    },
+});
+const nodeBashLog = defineLeaf({
+    name: 'log',
+    description: 'read a background bash job’s output from the blob store, from any machine',
+    whenToUse: 'a job has exited or been killed, or its sandbox is gone, and you need what it printed — the wake and the job object name this command; for a job still running on this machine, `tail -f` on its log file shows more recent output',
+    help: {
+        name: 'node bash log',
+        summary: 'read the stored output of one background bash job, last lines first bounded',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as named by the exit wake, `node bash list` or `node bash run`. Running and finished jobs both work.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID). A job another node started needs its owner here.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+            { kind: 'flag', name: 'tail', type: 'int', required: false, constraint: 'Return only this many trailing lines. Without it you get the last 256 KiB of output; either way at most 4 MiB.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The job.' },
+            { name: 'output', type: 'string', required: true, constraint: 'The stored output, empty when the job has written nothing yet. The broker uploads a running job’s output every couple of seconds, so it can trail the live log slightly.' },
+            { name: 'truncated', type: 'boolean', required: true, constraint: 'True when earlier output exists that the bound left out.' },
+        ],
+        outputKind: 'object',
+        effects: ['Reads the output chunks the job’s broker uploaded to the blob store through the daemon; never the local log file, so it works from any machine and after the job’s sandbox is deleted. Needs read access to the owning node. Changes nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        if (!isSafeBashJobId(jobId)) {
+            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id named by the exit wake or `crtr node bash list`.' });
+        }
+        const tail = input['tail'] === undefined ? undefined : Math.trunc(Number(input['tail']));
+        if (tail !== undefined && !(tail >= 1)) {
+            throw new InputError({ error: 'invalid_args', message: '--tail must be a positive number of lines', next: 'Pass --tail 50, or omit it for the last 256 KiB.' });
+        }
+        try {
+            const out = await cliClient().readBashJobOutput(node.node_id, jobId, tail === undefined ? {} : { tail_lines: tail });
+            return { node_id: node.node_id, job_id: out.job_id, output: out.output, truncated: out.truncated };
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.code === 'job_not_found') {
+                throw new InputError({ error: 'job_not_found', message: `no job ${jobId} owned by ${node.node_id}`, next: 'A job another node started needs its owner: pass --node <owner>.' });
+            }
+            throw error;
+        }
+    },
+    render: (result) => `${result['truncated'] === true ? '[earlier output omitted]\n' : ''}${String(result['output'])}`,
+});
+const nodeBashKill = defineLeaf({
+    name: 'kill',
+    description: 'stop one of a node’s background bash jobs',
+    whenToUse: 'a job you started is no longer wanted or is stuck, and it should stop now',
+    help: {
+        name: 'node bash kill',
+        summary: 'best-effort stop a background bash job and tell the owning node it was canceled',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when at least one observed supervisor-tree process received SIGTERM.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Snapshots the supervisor’s observable process tree, sends SIGTERM then SIGKILL to those processes, and cannot stop a descendant that detached and reparented before the snapshot.',
+            'Records the job’s exit so it stops showing as live, and ends its job object as killed; the job’s watchers (its node by default) get an urgent `killed` push.',
+        ],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        if (!isSafeBashJobId(jobId)) {
+            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id reported by `crtr node bash list`.' });
+        }
+        const stopped = await cliClient().stopBashJob(node.node_id, jobId);
+        return { node_id: node.node_id, signaled: stopped.signaled };
+    },
+    render: (result) => `Canceled a background bash job for ${result['node_id']}${result['signaled'] === true ? '' : ' (no observed job process was still running)'}.`,
+});
+const nodeBashQuiet = defineLeaf({
+    name: 'quiet',
+    description: 'mark a running background bash job as an expected wait so it sends no silence messages',
+    whenToUse: 'a silence message arrived for a job that is meant to sit idle',
+    help: {
+        name: 'node bash quiet',
+        summary: 'stop silence messages for one of a node’s live background bash jobs',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list or the silence message.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+        ],
+        outputKind: 'object',
+        effects: ['Marks the job’s row; the daemon sends no further silence messages for it. Signals nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        if (!isSafeBashJobId(jobId)) {
+            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id reported by `crtr node bash list`.' });
+        }
+        await patchRunningJob(node.node_id, jobId, { quiet_ok: true });
+        return { node_id: node.node_id };
+    },
+    render: (result) => `Background job for ${result['node_id']} will send no more silence messages.`,
+});
+const nodeBashExtend = defineLeaf({
+    name: 'extend',
+    description: 'claim an auto-backgrounded bash job so the daemon does not cancel it at its deadline',
+    whenToUse: 'a command that was moved to a job automatically is worth keeping past its cancel deadline — give it more time with --for, or let it run to completion with --keep',
+    help: {
+        name: 'node bash extend',
+        summary: 'move or clear the auto-cancel deadline on one of a node’s live background bash jobs',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list or the auto-background notice.' },
+            { kind: 'flag', name: 'for', type: 'string', required: false, constraint: 'New window from now before the job is canceled, as a duration (e.g. 90s, 10m, 1h30m). Mutually exclusive with --keep; give exactly one.' },
+            { kind: 'flag', name: 'keep', type: 'bool', required: false, constraint: 'Remove the deadline entirely so the job runs to completion. Mutually exclusive with --for; give exactly one.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'deadline_at', type: 'string', required: false, constraint: 'The job’s new auto-cancel time (ISO), or absent when --keep cleared the deadline so the job runs to completion.' },
+        ],
+        outputKind: 'object',
+        effects: ['Rewrites or clears the deadline on the job’s row. The daemon’s deadline lane reads it on its next scan. Signals nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        if (!isSafeBashJobId(jobId)) {
+            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id reported by `crtr node bash list`.' });
+        }
+        const forDuration = input['for'];
+        const keep = input['keep'] === true;
+        if (keep === (forDuration !== undefined && forDuration !== '')) {
+            throw new InputError({ error: 'invalid_args', message: 'give exactly one of --for <duration> or --keep', next: 'Extend by a window with --for 10m, or drop the deadline with --keep.' });
+        }
+        if (keep) {
+            await patchRunningJob(node.node_id, jobId, { keep: true });
+            return { node_id: node.node_id };
+        }
+        const durationMs = parseDurationMs(forDuration);
+        if (durationMs === null || durationMs <= 0) {
+            throw new InputError({ error: 'invalid_duration', message: `not a duration: ${forDuration}`, next: 'Use a value like 90s, 10m, or 1h30m.' });
+        }
+        const deadlineMs = Date.now() + durationMs;
+        await patchRunningJob(node.node_id, jobId, { deadline_at_ms: deadlineMs });
+        return { node_id: node.node_id, deadline_at: new Date(deadlineMs).toISOString() };
+    },
+    render: (result) => result['deadline_at'] === undefined
+        ? `Cleared the deadline — the background job will run to completion for ${result['node_id']}.`
+        : `Background job for ${result['node_id']} will be canceled at ${result['deadline_at']} unless extended again.`,
+});
+export const nodeBash = defineBranch({
+    name: 'bash',
+    description: 'start, list, read, stop, and extend your background bash jobs',
+    whenToUse: 'a command needs longer than one tool call — start it as a job and be woken with its exit code instead of using `&`, `nohup`, or a cron that polls a log — or you need to list, read the output of, stop, or extend the deadline of a job you already have',
+    help: {
+        name: 'node bash',
+        summary: 'start, list, read, stop, and extend background bash jobs owned by a node',
+        model: 'Every bash call runs under a detached supervisor with its output in a log file, so a command that outlives its call keeps running as a job: a canvas object its node owns, readable and watchable with `crtr canvas`. `run` starts a job on purpose and it is never auto-canceled. A job that shows no activity for 15 minutes messages its node, and is never stopped for it. A foreground command still running after 5 minutes is moved to a job automatically, with a cancel deadline unless `extend` claims it.',
+    },
+    children: [nodeBashRun, nodeBashBackground, nodeBashList, nodeBashLog, nodeBashKill, nodeBashQuiet, nodeBashExtend],
+});

package/dist/commands/node/create.d.ts

@@ -0,0 +1,6 @@
+/** 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
+ *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
+ *  the child's result. */
+export declare function childFollowUp(spawnerId: string | undefined): Promise<string>;
+export declare const nodeNew: import("../../core/command.js").LeafDef;