@north-light/crouter 0.3.154

package/dist/commands/cron.js

@@ -0,0 +1,524 @@
+// `crtr cron` — one scheduling primitive: run this bash, then.
+//
+//   crtr cron add     — arm a scheduled command (command on stdin)
+//   crtr cron list    — what is scheduled, with next fire and state
+//   crtr cron show    — one cron: full config plus its run history
+//   crtr cron run     — execute now, out of band; does not advance the schedule
+//   crtr cron pause   — stop firing without losing config or history
+//   crtr cron resume  — re-arm a paused cron
+//   crtr cron cancel  — remove one cron (idempotent)
+//
+// A cron is a bash command plus a clock: messaging a node, reviving one,
+// birthing one — all of it is `crtr node …` INSIDE the command. The CLI
+// resolves the time grammar client-side (parseWhen/parseCadence) and sends the
+// settled fire_at/recur/tz through
+// the crtrd API; this file reaches ZERO canvas state-store code (V-1).
+import { existsSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
+import { loadProfileManifest } from '../core/profiles/manifest.js';
+import { profilesStateBlock } from '../core/profiles/state-block.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+/** Canonicalize a profile operand (id OR manifest name) to its profile id so
+ *  every cron row and scope query speaks the same identity. Resolution errors
+ *  name the available profiles on this host. */
+function canonicalProfileId(raw) {
+    return loadProfileManifest(raw.trim()).profileId;
+}
+/** Build ParseOpts, including `tz` only when actually provided. */
+function parseOpts(now, tz) {
+    return tz !== undefined && tz.trim() !== '' ? { tz, now } : { now };
+}
+/** Map a time-grammar error (parseWhen/parseCadence) to the rendered error block. */
+function throwTimeError(e) {
+    const next = {
+        wake_in_past: 'Pick a future instant — a positive duration ("5m","2h") or an ISO time later than now.',
+        bad_when: 'Use a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").',
+        bad_cadence: 'Use a duration ("6h"), a 5-field cron ("0 9 * * *"), or an @alias ("@daily").',
+        unknown_zone: 'Pass --tz with an IANA zone name (e.g. "America/New_York").',
+        cadence_too_fast: 'Use a cadence of at least 60s (e.g. "1m","5m","1h").',
+    };
+    throw new InputError({ error: e.code, message: e.message, received: e.received, next: next[e.code] ?? 'Fix the time value and retry.' });
+}
+/** Parse a `--run-timeout` value — a small duration (`90s`, `5m`, `1h`) or
+ *  bare seconds — into whole seconds. */
+function parseRunTimeout(raw) {
+    const m = /^(\d+)(s|m|h)?$/.exec(raw.trim());
+    if (m === null) {
+        throw new InputError({
+            error: 'bad_run_timeout',
+            message: `"${raw}" is not a valid run timeout`,
+            field: 'run-timeout',
+            next: 'Use a duration like "90s", "5m", "1h", or bare seconds ("300").',
+        });
+    }
+    const n = Number(m[1]);
+    const mult = m[2] === 'h' ? 3600 : m[2] === 'm' ? 60 : 1;
+    const seconds = n * mult;
+    if (seconds <= 0) {
+        throw new InputError({ error: 'bad_run_timeout', message: 'run timeout must be positive', field: 'run-timeout', next: 'Use a positive duration, e.g. "5m".' });
+    }
+    return seconds;
+}
+/** The calling agent's profile, which is the scope every cron verb speaks in:
+ *  a profile-scoped cron lists and cancels within its profile, a global one is
+ *  canvas-home-wide. Outside a profile there is no scope to narrow to, so the
+ *  caller sees the whole canvas home. */
+function scopeQuery() {
+    const p = process.env['CRTR_PROFILE_ID'];
+    return p !== undefined && p.trim() !== '' ? { profile: canonicalProfileId(p) } : undefined;
+}
+/** Resolve the chosen-else-inherited cwd, and refuse one that is not a
+ *  directory NOW — the row is a snapshot, so a bad cwd would fail at every
+ *  fire instead of here. */
+function resolveCwd(raw) {
+    if (raw === undefined)
+        return process.cwd();
+    const abs = resolvePath(raw);
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+        throw new InputError({ error: 'bad_cwd', message: `${abs} is not a directory`, field: 'cwd', next: 'Pass --cwd with an existing directory, or omit it to inherit this one.' });
+    }
+    return abs;
+}
+/** Fold `--env KEY=VALUE` repetitions into the stored env JSON. */
+function resolveEnvJson(raw) {
+    const pairs = Array.isArray(raw) ? raw.map(String) : typeof raw === 'string' && raw !== '' ? [raw] : [];
+    if (pairs.length === 0)
+        return null;
+    const env = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        const key = eq === -1 ? '' : pair.slice(0, eq);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new InputError({ error: 'bad_env', message: `"${pair}" is not KEY=VALUE`, field: 'env', next: 'Pass --env KEY=VALUE (repeat the flag per variable); KEY must be a shell-legal name.' });
+        }
+        env[key] = pair.slice(eq + 1);
+    }
+    return JSON.stringify(env);
+}
+function requireCronId(input) {
+    const id = typeof input['cronId'] === 'string' ? input['cronId'].trim() : '';
+    if (id === '') {
+        throw new InputError({ error: 'missing_cron_id', message: 'a cron id is required', field: 'cron-id', next: 'Pass the cron id from `crtr cron list`.' });
+    }
+    return id;
+}
+/** Recent health for a `list` row: the most recent settled run in one phrase.
+ *  A failing cron is visible without a `cron show` per row. */
+function healthDisplay(last) {
+    if (last === null)
+        return 'never run';
+    const when = last.finished ?? '';
+    const outcome = last.exit_code === 0 ? 'ok' : last.exit_code === -1 ? 'TIMEOUT' : last.exit_code === null ? 'no exit' : `exit ${last.exit_code}`;
+    return when === '' ? outcome : `${outcome} ${when}`;
+}
+/** One run-log line for `show`/`run` rendering. */
+function renderRun(r) {
+    const exit = r.exit_code === null ? 'no exit' : r.exit_code === -1 ? 'TIMEOUT' : `exit ${r.exit_code}`;
+    const dur = r.duration_ms !== null ? `${r.duration_ms}ms` : '—';
+    return `- ${r.started} — ${exit}, ${dur} — ${r.delivered ?? '(no disposition recorded)'}`;
+}
+// ---------------------------------------------------------------------------
+// cron add
+// ---------------------------------------------------------------------------
+const addLeaf = defineLeaf({
+    name: 'add',
+    description: 'arm a scheduled command (bash on stdin; one of --at / --every)',
+    whenToUse: 'you need to arm a new bash schedule, rather than inspect or control an existing cron.',
+    help: {
+        name: 'cron add',
+        summary: 'arm a scheduled command',
+        params: [
+            { kind: 'stdin', name: 'command', required: true, constraint: "Arbitrary bash the daemon runs at each fire. Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Runs via `bash -c` in this cwd with $CRTR_CRON_ID, $CRTR_CRON_NAME, and $CRTR_RUN_ID in the env ($CRTR_ANCHOR too when anchored). The scheduler does not interpret it as a node action; a bash predicate can decide whether this fire acts, not arm a native predicate trigger." },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Agent-legible label — how the cron shows in `cron list`.' },
+            { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'One-shot: run the stored bash once at <when> — a duration ("90s","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", interpreted in --tz else host zone). Exactly one of --at / --every is required. The row is deleted after its run unless the run\'s disposition pauses it.' },
+            { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Recurring: run the stored bash at each cadence — a fixed interval ("6h" — first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required.' },
+            { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone (e.g. "America/New_York") for a bare-ISO --at or a calendar --every. Defaults to the host zone.' },
+            { kind: 'flag', name: 'on-output', type: 'enum', choices: ['silent', 'on-failure', 'always', 'on-change'], required: false, default: 'on-failure', constraint: 'What each run does with its output. silent: record in the run log, tell nobody — never escalate. on-failure (default): no success delivery; a failing run pauses the cron and spawns a node to deal with it. always: deliver stdout every run to --sink at --tier. on-change: deliver stdout only when it differs from the previous run\'s — the shape polling wants.' },
+            { kind: 'flag', name: 'sink', type: 'string', required: false, constraint: 'Where always/on-change stdout deliveries go: "node:<id>" (an existing node\'s inbox — must exist now; gone/finalized at fire time is a failure), "spawn:<kind>" (each delivered output creates a self-finishing node with stdout as kickoff — a managed child while its creator exists, otherwise a terminal parentless root), or "human" (the humanloop inbox). Required by always/on-change, rejected otherwise.' },
+            { kind: 'flag', name: 'tier', type: 'enum', choices: ['normal', 'urgent', 'critical'], required: false, default: 'normal', constraint: 'Inbox priority of a node-sink delivery.' },
+            { kind: 'flag', name: 'expires', type: 'string', required: false, constraint: 'Clock bound (same grammar as --at): the row is deleted once this instant passes. The self-limiting half of a poll-until pattern.' },
+            { kind: 'flag', name: 'anchor', type: 'string', required: false, constraint: 'Couple the cron\'s lifetime to a node: the row is deleted when that node is deleted. Without an anchor it outlives every node; it ends through its one-shot run, --expires, explicit cancellation, or self-cancellation from its bash.' },
+            { kind: 'flag', name: 'anchor-self', type: 'bool', required: false, constraint: 'Anchor to the calling node ($CRTR_NODE_ID). Errors outside a node.' },
+            { kind: 'flag', name: 'cancel-on-wake', type: 'bool', required: false, constraint: 'Also delete the row when the anchor node revives: use only when the cron belongs to that current dormancy, not for standing work. Requires an anchor; at most one cancel-on-wake cron per anchor — arming a second replaces the anchor’s pending one.' },
+            { kind: 'flag', name: 'run-timeout', type: 'string', required: false, default: '5m', constraint: 'Kill a run that exceeds this ("90s","5m","1h", or bare seconds). A timeout is a failure.' },
+            { kind: 'flag', name: 'overlap', type: 'enum', choices: ['skip', 'queue', 'replace'], required: false, default: 'skip', constraint: 'A fire landing while the previous run is still going. skip (default): log the skip, do not start a second run. queue: run once more after the current finishes (depth 1; further fires collapse). replace: kill the running instance and start fresh.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory every run executes in. Defaults to this one, must exist now, and is snapshotted onto the row — a cron never re-resolves its context.' },
+            { kind: 'flag', name: 'env', type: 'string', required: false, repeatable: true, constraint: 'KEY=VALUE added to every run\'s env (repeat per variable). Snapshotted at arm time; overlays the operational env, alongside $CRTR_CRON_ID/$CRTR_CRON_NAME/$CRTR_RUN_ID.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile the runs resolve config and credentials under, and — under --scope profile — the profile this cron lists and cancels within. A profile id or unique manifest name from the <profiles> list below; anything else is rejected. Defaults to the calling node\'s ($CRTR_PROFILE_ID).' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['profile', 'global'], required: false, constraint: 'Who lists and cancels this cron: profile (default when a profile is resolved) confines it to that profile; global makes it canvas-home-wide, visible from every profile.' },
+        ],
+        output: [
+            { name: 'cron_id', type: 'string', required: true, constraint: 'The armed cron — inspect with `cron show <cron_id>`, cancel with `cron cancel <cron_id>`.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The label as armed.' },
+            { name: 'fire_at', type: 'string', required: true, constraint: 'Next fire (UTC ISO).' },
+            { name: 'recur', type: 'string', required: true, constraint: 'Cadence display; "none" for a one-shot.' },
+        ],
+        outputKind: 'object',
+        dynamicState: () => profilesStateBlock(),
+        effects: [
+            'Arms one cron row (daemon-run; survives this process and every node).',
+            'Each fire runs the command via bash in this cwd and records a run-log entry.',
+            'A failing run (nonzero exit, timeout, undeliverable sink) pauses the cron and spawns a node to deal with it — unless --on-output silent.',
+        ],
+    },
+    run: async (input) => {
+        let command = typeof input['command'] === 'string' ? input['command'].trim() : '';
+        if (command === '')
+            command = (await readStdinRaw()).trim();
+        if (command === '') {
+            throw new InputError({ error: 'missing_command', message: 'no command on stdin', field: 'command', next: "Pipe the bash command on stdin (e.g. from a single-quoted heredoc)." });
+        }
+        const name = typeof input['name'] === 'string' ? input['name'].trim() : '';
+        if (name === '') {
+            throw new InputError({ error: 'missing_name', message: '--name is required', field: 'name', next: 'Pass --name <label>.' });
+        }
+        const at = typeof input['at'] === 'string' && input['at'] !== '' ? input['at'] : undefined;
+        const every = typeof input['every'] === 'string' && input['every'] !== '' ? input['every'] : undefined;
+        if ((at === undefined) === (every === undefined)) {
+            throw new InputError({
+                error: 'bad_schedule',
+                message: at === undefined ? 'one of --at / --every is required' : '--at and --every are mutually exclusive',
+                next: 'Pass exactly one: --at <when> for a one-shot, or --every <cadence> for a recurrence.',
+            });
+        }
+        const tz = typeof input['tz'] === 'string' && input['tz'] !== '' ? input['tz'] : undefined;
+        const now = new Date();
+        let fireAt;
+        let recur = null;
+        if (every !== undefined) {
+            const cad = parseCadence(every, parseOpts(now, tz));
+            if ('error' in cad)
+                throwTimeError(cad.error);
+            fireAt = cad.firstFireAt;
+            recur = cad.recur;
+        }
+        else {
+            const w = parseWhen(at, parseOpts(now, tz));
+            if ('error' in w)
+                throwTimeError(w.error);
+            fireAt = w.fireAt;
+        }
+        let expiresAt = null;
+        const expires = typeof input['expires'] === 'string' && input['expires'] !== '' ? input['expires'] : undefined;
+        if (expires !== undefined) {
+            const w = parseWhen(expires, parseOpts(now, tz));
+            if ('error' in w)
+                throwTimeError(w.error);
+            expiresAt = w.fireAt;
+        }
+        // Anchor coupling: --anchor <id> or --anchor-self; --cancel-on-wake rides one of them.
+        const anchorFlag = typeof input['anchor'] === 'string' && input['anchor'] !== '' ? input['anchor'] : undefined;
+        const anchorSelf = input['anchorSelf'] === true;
+        if (anchorFlag !== undefined && anchorSelf) {
+            throw new InputError({ error: 'bad_anchor', message: '--anchor and --anchor-self are mutually exclusive', next: 'Pass one anchor or the other.' });
+        }
+        let anchorNode = anchorFlag ?? null;
+        if (anchorSelf) {
+            const self = process.env['CRTR_NODE_ID'];
+            if (self === undefined || self === '') {
+                throw new InputError({ error: 'no_self_node', message: '--anchor-self requires a calling node ($CRTR_NODE_ID is unset)', next: 'Run from inside a node, or pass --anchor <node-id> explicitly.' });
+            }
+            anchorNode = self;
+        }
+        const cancelOnWake = input['cancelOnWake'] === true;
+        if (cancelOnWake && anchorNode === null) {
+            throw new InputError({ error: 'cancel_on_wake_needs_anchor', message: '--cancel-on-wake requires an anchor', next: 'Add --anchor <node-id> or --anchor-self.' });
+        }
+        const runTimeout = typeof input['runTimeout'] === 'string' && input['runTimeout'] !== '' ? parseRunTimeout(input['runTimeout']) : undefined;
+        // Execution context: chosen here, else inherited from this node, and
+        // snapshotted onto the row by the daemon either way.
+        const cwd = resolveCwd(typeof input['cwd'] === 'string' && input['cwd'] !== '' ? input['cwd'] : undefined);
+        const envJson = resolveEnvJson(input['env']);
+        const profileFlag = typeof input['profile'] === 'string' && input['profile'] !== '' ? input['profile'] : undefined;
+        const inherited = process.env['CRTR_PROFILE_ID'];
+        const profile = profileFlag !== undefined
+            ? canonicalProfileId(profileFlag)
+            : inherited !== undefined && inherited.trim() !== ''
+                ? canonicalProfileId(inherited)
+                : undefined;
+        const scopeFlag = input['scope'];
+        const scope = scopeFlag ?? (profile !== undefined ? 'profile' : 'global');
+        if (scope === 'profile' && profile === undefined) {
+            throw new InputError({ error: 'scope_needs_profile', message: '--scope profile names the profile this cron lists and cancels within, but no profile is resolved', field: 'profile', next: 'Pass --profile <id>, or use --scope global for a canvas-home-wide cron.' });
+        }
+        const createdBy = process.env['CRTR_NODE_ID'];
+        const dto = await cliClient()
+            .armCron({
+            name,
+            command,
+            fire_at: fireAt,
+            recur,
+            tz: tz ?? null,
+            created_by: createdBy !== undefined && createdBy !== '' ? createdBy : null,
+            cwd,
+            env_json: envJson,
+            profile: profile ?? null,
+            scope,
+            on_output: input['onOutput'] ?? 'on-failure',
+            sink: typeof input['sink'] === 'string' && input['sink'] !== '' ? input['sink'] : null,
+            tier: input['tier'] ?? 'normal',
+            expires_at: expiresAt,
+            anchor_node: anchorNode,
+            cancel_on_wake: cancelOnWake,
+            ...(runTimeout !== undefined ? { run_timeout_s: runTimeout } : {}),
+            overlap: input['overlap'] ?? 'skip',
+        })
+            .catch(rethrowAsCliError);
+        return { cron_id: dto.cron_id, name: dto.name, fire_at: dto.fire_at, recur: cadenceDisplay(dto.recur) };
+    },
+    render: (r) => {
+        const recur = String(r['recur']);
+        const cadence = recur === 'none' ? 'one-shot (row deleted after the run)' : recur;
+        return `Cron armed — ${String(r['name'])} (${String(r['cron_id'])}).\n\n- next fire: ${String(r['fire_at'])}\n- cadence: ${cadence}\n\nIt runs daemon-side; nothing more to do here. Inspect it with \`crtr cron show ${String(r['cron_id'])}\`; cancel any time with \`crtr cron cancel ${String(r['cron_id'])}\`.`;
+    },
+});
+// ---------------------------------------------------------------------------
+// cron list
+// ---------------------------------------------------------------------------
+const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'what is scheduled, with next fire and recent health',
+    whenToUse: 'you want to see every cron in scope — to find an id to show/cancel, to check what fires next and what is paused, or to spot one whose last run failed.',
+    help: {
+        name: 'cron list',
+        summary: 'every cron in scope, next-fire order',
+        params: [],
+        output: [
+            { name: 'crons', type: 'object[]', required: true, constraint: 'One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
+        ],
+        outputKind: 'object',
+        effects: [],
+    },
+    run: async () => {
+        const crons = await cliClient().listCrons(scopeQuery()).catch(rethrowAsCliError);
+        return {
+            crons: crons.map((c) => ({
+                cron_id: c.cron_id,
+                name: c.name,
+                fire_at: c.fire_at,
+                recur: cadenceDisplay(c.recur),
+                state: c.state,
+                on_output: c.on_output,
+                sink: c.sink,
+                expires_at: c.expires_at,
+                last_run: c.last_run,
+            })),
+        };
+    },
+    render: (r) => {
+        const crons = r['crons'];
+        if (crons.length === 0)
+            return 'No crons armed.';
+        const lines = crons.map((c) => {
+            const bits = [
+                `next ${c.fire_at}`,
+                c.recur === 'none' ? 'one-shot' : c.recur,
+                c.sink !== null ? `${c.on_output} → ${c.sink}` : c.on_output,
+                `last: ${healthDisplay(c.last_run)}`,
+            ];
+            if (c.expires_at !== null)
+                bits.push(`expires ${c.expires_at}`);
+            const marker = c.state === 'paused' ? ' [PAUSED — resume or cancel]' : '';
+            return `- ${c.name} (${c.cron_id}) — ${bits.join(', ')}${marker}`;
+        });
+        return `${crons.length} cron(s):\n\n${lines.join('\n')}`;
+    },
+});
+// ---------------------------------------------------------------------------
+// cron show
+// ---------------------------------------------------------------------------
+const showLeaf = defineLeaf({
+    name: 'show',
+    description: 'one cron: full config plus its run history',
+    whenToUse: 'you want to inspect one cron — its exact command and settings, and what its recent runs actually did (exit codes, output heads, where deliveries went). The run log is how you answer "did it silently stop working".',
+    help: {
+        name: 'cron show',
+        summary: 'one cron with its run-log ring',
+        params: [
+            { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to inspect (from `cron list`).' },
+        ],
+        output: [
+            { name: 'cron', type: 'object', required: true, constraint: 'The full cron config: command, schedule, snapshotted context (cwd, profile, scope, env var names — values stay server-side), disposition, sink, coupling, state.' },
+            { name: 'runs', type: 'object[]', required: true, constraint: 'The bounded run log, most recent first: started, exit_code (-1 = timeout kill), duration_ms, stdout/stderr heads, delivered (what the sink did, or why it did not).' },
+        ],
+        outputKind: 'object',
+        effects: [],
+    },
+    run: async (input) => {
+        const id = requireCronId(input);
+        const dto = await cliClient().showCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
+        return { cron: dto.cron, runs: dto.runs };
+    },
+    render: (r) => {
+        const c = r['cron'];
+        const runs = r['runs'];
+        const schedule = c.recur !== null ? cadenceDisplay(c.recur) : `one-shot at ${c.fire_at}`;
+        const lines = [
+            `# ${c.name} (${c.cron_id})${c.state === 'paused' ? ' — PAUSED' : ''}`,
+            '',
+            `- schedule: ${schedule}${c.tz !== null ? ` (tz ${c.tz})` : ''} — next fire ${c.fire_at}`,
+            `- disposition: ${c.on_output}${c.sink !== null ? ` → ${c.sink} (tier ${c.tier})` : ''}`,
+            `- context: cwd ${c.cwd}${c.profile !== null ? `, profile ${c.profile}` : ''}, scope ${c.scope}${c.env_keys.length > 0 ? `, env ${c.env_keys.join(', ')}` : ''}`,
+            `- run: timeout ${c.run_timeout_s}s, overlap ${c.overlap}${c.run_state === 'running' ? ' — a run is IN FLIGHT now' : ''}`,
+        ];
+        if (c.expires_at !== null)
+            lines.push(`- expires: ${c.expires_at}`);
+        if (c.anchor_node !== null)
+            lines.push(`- anchored to node ${c.anchor_node}${c.cancel_on_wake ? ' (canceled when it wakes)' : ''}`);
+        if (c.created_by !== null)
+            lines.push(`- created by node ${c.created_by}`);
+        lines.push('', '## Command', '', '```bash', c.command, '```', '', `## Runs (most recent first, last ${runs.length})`, '');
+        lines.push(...(runs.length > 0 ? runs.map(renderRun) : ['(no runs yet)']));
+        return lines.join('\n');
+    },
+});
+// ---------------------------------------------------------------------------
+// cron run
+// ---------------------------------------------------------------------------
+const runLeaf = defineLeaf({
+    name: 'run',
+    description: 'execute now, out of band — does not advance the schedule',
+    whenToUse: 'you need the stored command to execute now because its own behavior has not been exercised, or you fixed the command behind a paused cron. This is not a scheduled-delivery check: once `cron add` has armed a valid row, trust the clock and node delivery rather than firing it again for reassurance.',
+    help: {
+        name: 'cron run',
+        summary: 'fire one cron now, out of band, and report the settled run',
+        params: [
+            { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to run (from `cron list`).' },
+        ],
+        output: [
+            { name: 'exit_code', type: 'number', required: false, constraint: 'The run\'s exit code (-1 = timeout kill; null when the process failed to start).' },
+            { name: 'duration_ms', type: 'number', required: true, constraint: 'Wall-clock run time.' },
+            { name: 'stdout_head', type: 'string', required: false, constraint: 'Captured stdout (head).' },
+            { name: 'stderr_head', type: 'string', required: false, constraint: 'Captured stderr (head).' },
+            { name: 'delivered', type: 'string', required: true, constraint: 'What the sink did with the output, or why it did not.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Runs the command NOW (blocking this call until it settles) and records the run in the cron\'s run log.',
+            'Delivers per the cron\'s disposition; never advances the schedule, consumes a one-shot, or escalates a failure.',
+        ],
+    },
+    run: async (input) => {
+        const id = requireCronId(input);
+        // Size the request timeout to the cron's own run timeout (+ headroom):
+        // the default 30s client window would kill a legitimate long run.
+        const shown = await cliClient().showCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
+        const client = cliClient({ timeoutMs: shown.cron.run_timeout_s * 1000 + 15_000 });
+        const run = await client.runCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err));
+        return run;
+    },
+    render: (r) => {
+        const run = r;
+        const exit = run.exit_code === null ? 'no exit (process error)' : run.exit_code === -1 ? '-1 (TIMEOUT)' : String(run.exit_code);
+        const lines = [
+            `Run settled — exit ${exit}, ${run.duration_ms ?? '?'}ms.`,
+            '',
+            `- delivered: ${run.delivered ?? '(nothing recorded)'}`,
+        ];
+        if (run.stdout_head !== null)
+            lines.push('', '## stdout (head)', '', run.stdout_head);
+        if (run.stderr_head !== null)
+            lines.push('', '## stderr (head)', '', run.stderr_head);
+        return lines.join('\n');
+    },
+});
+// ---------------------------------------------------------------------------
+// cron pause / resume
+// ---------------------------------------------------------------------------
+const pauseLeaf = defineLeaf({
+    name: 'pause',
+    description: 'stop firing without losing config or history',
+    whenToUse: 'a cron should stop firing for now but its config and run history are worth keeping — a job under investigation, or a poll to silence temporarily. (A failing cron pauses itself.)',
+    help: {
+        name: 'cron pause',
+        summary: 'pause one cron',
+        params: [
+            { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to pause (from `cron list`).' },
+        ],
+        output: [
+            { name: 'cron_id', type: 'string', required: true, constraint: 'The paused cron.' },
+            { name: 'state', type: 'string', required: true, constraint: 'Always "paused".' },
+        ],
+        outputKind: 'object',
+        effects: ['Stops the cron firing until `cron resume`. An in-flight run settles normally; the row just stops being due.'],
+    },
+    run: async (input) => {
+        const id = requireCronId(input);
+        const dto = await cliClient().pauseCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
+        return { cron_id: dto.cron_id, state: dto.state };
+    },
+    render: (r) => `Cron ${String(r['cron_id'])} paused — it will not fire until \`crtr cron resume ${String(r['cron_id'])}\`.`,
+});
+const resumeLeaf = defineLeaf({
+    name: 'resume',
+    description: 're-arm a paused cron',
+    whenToUse: 'a paused cron should fire again — you fixed what made it fail (verify first with `cron run`), or its silence is over. A fire that came due while paused fires immediately on resume.',
+    help: {
+        name: 'cron resume',
+        summary: 'resume one paused cron',
+        params: [
+            { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to resume (from `cron list`).' },
+        ],
+        output: [
+            { name: 'cron_id', type: 'string', required: true, constraint: 'The resumed cron.' },
+            { name: 'state', type: 'string', required: true, constraint: 'Always "active".' },
+            { name: 'fire_at', type: 'string', required: true, constraint: 'Next fire — if already past, it fires on the next daemon tick.' },
+        ],
+        outputKind: 'object',
+        effects: ['Re-arms the cron. A past-due fire_at fires immediately (instant verification after un-wedging); a recurrence then advances naturally.'],
+    },
+    run: async (input) => {
+        const id = requireCronId(input);
+        const dto = await cliClient().resumeCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
+        return { cron_id: dto.cron_id, state: dto.state, fire_at: dto.fire_at };
+    },
+    render: (r) => `Cron ${String(r['cron_id'])} resumed — next fire ${String(r['fire_at'])} (if that is already past, it fires on the next tick).`,
+});
+// ---------------------------------------------------------------------------
+// cron cancel
+// ---------------------------------------------------------------------------
+const cancelLeaf = defineLeaf({
+    name: 'cancel',
+    description: 'remove one cron (idempotent)',
+    whenToUse: 'a scheduled command should stop firing — it is obsolete, wrong, or its purpose is served. Idempotent, so a script can safely self-cancel with `crtr cron cancel $CRTR_CRON_ID` even if a racing cancel got there first.',
+    help: {
+        name: 'cron cancel',
+        summary: 'remove one cron',
+        params: [
+            { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to remove (from `cron list`, or $CRTR_CRON_ID inside a run).' },
+        ],
+        output: [{ name: 'canceled', type: 'string', required: true, constraint: 'The removed (or already-absent) cron id.' }],
+        outputKind: 'object',
+        effects: ['Deletes the cron row and its run history; kills any in-flight run. A no-op if already gone.'],
+    },
+    run: async (input) => {
+        const id = requireCronId(input);
+        await cliClient()
+            .cancelCron(id, scopeQuery())
+            .catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
+        return { canceled: id };
+    },
+    render: (r) => `Cron ${String(r['canceled'])} canceled — it will not fire again.`,
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerCron() {
+    return defineBranch({
+        name: 'cron',
+        rootEntry: {
+            concept: 'one scheduling primitive — run this bash command, then',
+            desc: 'arm, inspect, and control scheduled bash commands the daemon runs on the clock',
+            useWhen: 'bash must run later or on a cadence, rather than waiting for a runtime-delivered wake.',
+        },
+        help: {
+            name: 'cron',
+            summary: 'scheduled bash commands, daemon-run',
+            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node, an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A bash predicate can gate whether a fire acts; cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
+        },
+        children: [addLeaf, listLeaf, showLeaf, runLeaf, pauseLeaf, resumeLeaf, cancelLeaf],
+    });
+}

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const dashboardLeaf: LeafDef;

package/dist/commands/dashboard.js

@@ -0,0 +1,80 @@
+// `crtr canvas dashboard` — canvas-wide visibility surface.
+//
+// Renders the subscription sub-DAG as an ASCII tree, optionally scoped to a
+// single root.  A human operator pastes the output into a terminal or pipes it
+// to a renderer; a machine consumer reads the structured `rows` array.
+//
+// Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliClient, cliCanvasSource } from './api-client.js';
+import { renderTreeFromSource, renderForestFromSource, dashboardRowsFromSource, dashboardRowsAllFromSource, enrichRowsFromSource, } from '../core/canvas/render-source.js';
+// ---------------------------------------------------------------------------
+// dashboard show — the main leaf
+// ---------------------------------------------------------------------------
+export const dashboardLeaf = defineLeaf({
+    name: 'dashboard',
+    description: 'render the canvas as a subscription tree',
+    whenToUse: 'you want the whole graph at a glance as a rendered tree — the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node\'s status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node\'s neighbors, and `canvas attention` to find which nodes are blocked on a human',
+    help: {
+        name: 'canvas dashboard',
+        summary: 'render the canvas as an ASCII subscription tree — scoped to a root or the full forest',
+        params: [
+            {
+                kind: 'flag',
+                name: 'root',
+                type: 'string',
+                required: false,
+                constraint: 'Node id to use as the tree root. Omit for the full forest (all canvas roots).',
+            },
+        ],
+        output: [
+            { name: 'tree', type: 'string', required: true, constraint: 'Multi-line ASCII tree.' },
+            { name: 'nodes', type: 'integer', required: true, constraint: 'Total node count in this view.' },
+            { name: 'rows', type: 'object[]', required: true, constraint: 'One per node: {node_id,name,status,kind,mode,ctx_tokens,asks}.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: queries canvas.db and node telemetry files.'],
+    },
+    run: async (input) => {
+        const rootId = input['root'];
+        const source = cliCanvasSource();
+        if (rootId !== undefined) {
+            // Scoped to a single root — validate the node exists (via the daemon API).
+            const node = await source.getNode(rootId);
+            if (node === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${rootId}`,
+                    next: 'List nodes with `crtr node inspect list` to find a valid id.',
+                });
+            }
+            const rows = await dashboardRowsFromSource(source, rootId);
+            return {
+                tree: await renderTreeFromSource(source, rootId),
+                nodes: rows.length,
+                rows,
+            };
+        }
+        // Full forest: all nodes on the canvas.
+        const allNodes = await source.listNodes();
+        // dashboardRowsAllFromSource is the cheap-boot builder: ctx_tokens/asks are 0
+        // and `name` is the handle only until enriched. The JSON consumer wants the
+        // real values, so fold the deferred fields in before emitting (the rendered
+        // TREE is unaffected). Ask counts are per-node: attention follows each human
+        // bridge's parent relation. The daemon's canvas snapshot carries that count
+        // (`attention_count`, server-side `enrichRows`), so read it straight off the
+        // roster.
+        const rows = await dashboardRowsAllFromSource(source);
+        const snapshot = await cliClient().canvasSnapshot();
+        const asks = {};
+        for (const n of snapshot.nodes)
+            asks[n.node_id] = n.attention_count;
+        await enrichRowsFromSource(source, rows, asks);
+        return {
+            tree: await renderForestFromSource(source),
+            nodes: allNodes.length,
+            rows,
+        };
+    },
+});

package/dist/commands/human/prompts.d.ts

@@ -0,0 +1,8 @@
+import type { DeckSource } from '@crouton-kit/humanloop';
+/** Humanloop's optional presentation label. Ticket identity and attribution
+ * come from the bridge node directory and parent relation, never ticket data. */
+export declare function sourceStamp(): Promise<DeckSource>;
+export declare const humanAsk: import("../../core/command.js").LeafDef;
+export declare const humanReview: import("../../core/command.js").LeafDef;
+export declare const humanNotify: import("../../core/command.js").LeafDef;
+export declare const humanShow: import("../../core/command.js").LeafDef;