@north-light/crouter 0.3.318 → 0.3.320

package/dist/commands/cron.js

@@ -1,534 +1,11 @@
-// `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 { envNodeId, envProfileId } from '../shared/env.js';
-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, resolveProfileOperand } 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, manifest name, or nearest match) 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 resolveProfileOperand(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 profile scope for a cron route: an explicit selector overrides the
- *  calling agent's profile. Outside a profile there is no scope to narrow to,
- *  so the caller sees the whole canvas home. */
-function scopeQuery(profile) {
-    const p = typeof profile === 'string' && profile.trim() !== '' ? canonicalProfileId(profile) : envProfileId();
-    return p !== undefined && p.trim() !== '' ? { profile: 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. A run that must branch on canvas state should call `crtr --json <cmd>` and read the leaf's declared outputs, rather than parsing the prose output." },
-            { 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. Use this for a bash condition that only the local filesystem knows: if it exits 75, the next cadence re-checks it. A host platform can also re-check it early by calling the daemon\'s `POST /v1/crons/poke` endpoint.' },
-            { 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, constraint: 'What each run does with its output. Defaults to on-change for a node:<id> sink; otherwise on-failure. silent: record in the run log, tell nobody — never escalate. on-failure: 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: 'urgent', constraint: 'Inbox priority of a node-sink delivery. urgent (default): steers the target mid-turn, or wakes it when dormant — a fire is news the node asked for on a schedule, so it should land now. normal: waits for the running turn to settle. critical: aborts the running turn outright.' },
-            { 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. For a held one-shot (last run exited 75), expiry bounds the wait for eligibility — the row is deleted UNFIRED, never fired blind at expiry.' },
-            { 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 manifest name from the <profiles> list below; a close-enough name resolves to the nearest profile. 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 server-minted armed cron id — inspect with `cron show <cron_id>`, cancel with `cron cancel <cron_id>`.' },
-            { 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 = envNodeId();
-            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 = envProfileId();
-        const profile = profileFlag !== undefined
-            ? canonicalProfileId(profileFlag)
-            : inherited !== undefined && inherited.trim() !== ''
-                ? loadProfileManifest(inherited).profileId
-                : 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 = envNodeId();
-        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'],
-            sink: typeof input['sink'] === 'string' && input['sink'] !== '' ? input['sink'] : null,
-            tier: input['tier'] ?? 'urgent',
-            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, 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['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 with \`crtr cron cancel ${String(r['cron_id'])}\` from its profile, or pass \`--profile <profile>\` from another profile.`;
-    },
-});
-// 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), held (true after an exit-75 gate; a recurring row re-checks at fire_at or when a host platform calls `POST /v1/crons/poke`, while a one-shot needs that call or `crtr cron run <cron-id>`), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    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,
-                held: c.held,
-                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}`);
-            // The state cell derives from both fields: an active held row must never
-            // present as paused (paused is user-owned and blocks firing; held fires
-            // the moment a poke lands), and the held fact is never hidden.
-            const marker = c.state === 'paused'
-                ? c.held
-                    ? ' [PAUSED (held) — resume or cancel]'
-                    : ' [PAUSED — resume or cancel]'
-                : c.held
-                    ? c.recur === 'none'
-                        ? ` [HELD — last run exited 75; run manually with \`crtr cron run ${c.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`]`
-                        : ' [HELD — last run exited 75; re-checks at the next cadence or when a host platform calls `POST /v1/crons/poke`]'
-                    : '';
-            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: ['None. Read-only.'],
-    },
-    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) : c.held ? 'one-shot' : `one-shot at ${c.fire_at}`;
-        const tzPart = c.tz !== null ? ` (tz ${c.tz})` : '';
-        // A held row's next-fire is its BACKSTOP, not a promise: a daemon poke
-        // fires it earlier. A held one-shot has no clock slot at all — it waits
-        // for a poke until --expires deletes it (or forever, without one).
-        const scheduleLine = !c.held
-            ? `- schedule: ${schedule}${tzPart} — next fire ${c.fire_at}`
-            : c.recur !== null
-                ? `- schedule: ${schedule}${tzPart} — next re-check ${c.fire_at} (held — also re-checks when a host platform calls \`POST /v1/crons/poke\`; last run exited 75)`
-                : c.expires_at !== null
-                    ? `- schedule: ${schedule}${tzPart} — no scheduled re-check — expires ${c.expires_at} (held — run manually with \`crtr cron run ${c.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`; deleted unfired at expiry)`
-                    : `- schedule: ${schedule}${tzPart} — no scheduled re-check (held — run manually with \`crtr cron run ${c.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`)`;
-        const stateTag = c.state === 'paused' ? (c.held ? ' — PAUSED (held)' : ' — PAUSED') : c.held ? ' — HELD' : '';
-        const lines = [
-            `# ${c.name} (${c.cron_id})${stateTag}`,
-            '',
-            scheduleLine,
-            `- 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: [],
-        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);
-        await cliClient().pauseCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
-        return {};
-    },
-    render: () => 'Cron paused.'
-});
-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: '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 { fire_at: dto.fire_at };
-    },
-    render: (r) => `Cron 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).' },
-            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile scope to cancel within. Defaults to the calling node\'s profile; pass the profile id or manifest name for a cron armed under another profile.' },
-        ],
-        output: [],
-        outputKind: 'object',
-        dynamicState: () => profilesStateBlock(),
-        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);
-        const runId = process.env['CRTR_RUN_ID'];
-        await cliClient()
-            .cancelCron(id, {
-            ...scopeQuery(input['profile']),
-            ...(runId === undefined || runId === '' ? {} : { run_id: runId }),
-        })
-            .catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
-        return {};
-    },
-    render: () => 'Cron canceled.'
-});
-// 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 (its disposition defaults to on-change), 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 gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent — right when the recurrence is your polling cadence. Exit 75 holds the row. A held recurring row re-checks at its next natural slot, or when a host platform calls the daemon\'s `POST /v1/crons/poke` endpoint. A held one-shot has no scheduled re-check: it stays held until that endpoint is called, or you execute its bash explicitly with `crtr cron run <cron-id>` (which does not unhold or reschedule the row). A local filesystem condition does not call the daemon, so use --every for that condition or run the cron explicitly after it changes. Any other nonzero exit is a real failure and escalates per --on-output. Keep gate errors nonzero so a broken probe is loud instead of silently held. Beyond the exit-code contract, 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],
-    });
-}
+var L=Object.defineProperty;var o=(n,e)=>L(n,"name",{value:e,configurable:!0});import{envNodeId as E,envProfileId as P}from"../shared/env.js";import{existsSync as K,statSync as F}from"node:fs";import{resolve as W}from"node:path";import{defineBranch as M,defineLeaf as h}from"../core/command.js";import{InputError as c,readStdinRaw as Y}from"../core/io.js";import{parseWhen as D,parseCadence as H,cadenceDisplay as x}from"../core/wake.js";import{loadProfileManifest as B,resolveProfileOperand as Z}from"../core/profiles/manifest.js";import{profilesStateBlock as N}from"../core/profiles/state-block.js";import{cliClient as l,rethrowAsCliError as u}from"./api-client.js";function U(n){return Z(n.trim()).profileId}o(U,"canonicalProfileId");function k(n,e){return e!==void 0&&e.trim()!==""?{tz:e,now:n}:{now:n}}o(k,"parseOpts");function b(n){const e={wake_in_past:'Pick a future instant \u2014 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 c({error:n.code,message:n.message,received:n.received,next:e[n.code]??"Fix the time value and retry."})}o(b,"throwTimeError");function J(n){const e=/^(\d+)(s|m|h)?$/.exec(n.trim());if(e===null)throw new c({error:"bad_run_timeout",message:`"${n}" is not a valid run timeout`,field:"run-timeout",next:'Use a duration like "90s", "5m", "1h", or bare seconds ("300").'});const t=Number(e[1]),r=e[2]==="h"?3600:e[2]==="m"?60:1,i=t*r;if(i<=0)throw new c({error:"bad_run_timeout",message:"run timeout must be positive",field:"run-timeout",next:'Use a positive duration, e.g. "5m".'});return i}o(J,"parseRunTimeout");function f(n){const e=typeof n=="string"&&n.trim()!==""?U(n):P();return e!==void 0&&e.trim()!==""?{profile:e}:void 0}o(f,"scopeQuery");function V(n){if(n===void 0)return process.cwd();const e=W(n);if(!K(e)||!F(e).isDirectory())throw new c({error:"bad_cwd",message:`${e} is not a directory`,field:"cwd",next:"Pass --cwd with an existing directory, or omit it to inherit this one."});return e}o(V,"resolveCwd");function G(n){const e=Array.isArray(n)?n.map(String):typeof n=="string"&&n!==""?[n]:[];if(e.length===0)return null;const t={};for(const r of e){const i=r.indexOf("="),a=i===-1?"":r.slice(0,i);if(!/^[A-Za-z_][A-Za-z0-9_]*$/.test(a))throw new c({error:"bad_env",message:`"${r}" is not KEY=VALUE`,field:"env",next:"Pass --env KEY=VALUE (repeat the flag per variable); KEY must be a shell-legal name."});t[a]=r.slice(i+1)}return JSON.stringify(t)}o(G,"resolveEnvJson");function p(n){const e=typeof n.cronId=="string"?n.cronId.trim():"";if(e==="")throw new c({error:"missing_cron_id",message:"a cron id is required",field:"cron-id",next:"Pass the cron id from `crtr cron list`."});return e}o(p,"requireCronId");function Q(n){if(n===null)return"never run";const e=n.finished??"",t=n.exit_code===0?"ok":n.exit_code===-1?"TIMEOUT":n.exit_code===null?"no exit":`exit ${n.exit_code}`;return e===""?t:`${t} ${e}`}o(Q,"healthDisplay");function X(n){const e=n.exit_code===null?"no exit":n.exit_code===-1?"TIMEOUT":`exit ${n.exit_code}`,t=n.duration_ms!==null?`${n.duration_ms}ms`:"\u2014";return`- ${n.started} \u2014 ${e}, ${t} \u2014 ${n.delivered??"(no disposition recorded)"}`}o(X,"renderRun");const ee=h({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:!0,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. A run that must branch on canvas state should call `crtr --json <cmd>` and read the leaf's declared outputs, rather than parsing the prose output."},{kind:"flag",name:"name",type:"string",required:!0,constraint:"Agent-legible label \u2014 how the cron shows in `cron list`."},{kind:"flag",name:"at",type:"string",required:!1,constraint:`One-shot: run the stored bash once at <when> \u2014 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:!1,constraint:'Recurring: run the stored bash at each cadence \u2014 a fixed interval ("6h" \u2014 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. Use this for a bash condition that only the local filesystem knows: if it exits 75, the next cadence re-checks it. A host platform can also re-check it early by calling the daemon\'s `POST /v1/crons/poke` endpoint.'},{kind:"flag",name:"tz",type:"string",required:!1,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:!1,constraint:"What each run does with its output. Defaults to on-change for a node:<id> sink; otherwise on-failure. silent: record in the run log, tell nobody \u2014 never escalate. on-failure: 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 \u2014 the shape polling wants."},{kind:"flag",name:"sink",type:"string",required:!1,constraint:`Where always/on-change stdout deliveries go: "node:<id>" (an existing node's inbox \u2014 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 \u2014 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:!1,default:"urgent",constraint:"Inbox priority of a node-sink delivery. urgent (default): steers the target mid-turn, or wakes it when dormant \u2014 a fire is news the node asked for on a schedule, so it should land now. normal: waits for the running turn to settle. critical: aborts the running turn outright."},{kind:"flag",name:"expires",type:"string",required:!1,constraint:"Clock bound (same grammar as --at): the row is deleted once this instant passes. The self-limiting half of a poll-until pattern. For a held one-shot (last run exited 75), expiry bounds the wait for eligibility \u2014 the row is deleted UNFIRED, never fired blind at expiry."},{kind:"flag",name:"anchor",type:"string",required:!1,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:!1,constraint:"Anchor to the calling node ($CRTR_NODE_ID). Errors outside a node."},{kind:"flag",name:"cancel-on-wake",type:"bool",required:!1,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 \u2014 arming a second replaces the anchor\u2019s pending one."},{kind:"flag",name:"run-timeout",type:"string",required:!1,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:!1,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:!1,constraint:"Directory every run executes in. Defaults to this one, must exist now, and is snapshotted onto the row \u2014 a cron never re-resolves its context."},{kind:"flag",name:"env",type:"string",required:!1,repeatable:!0,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:!1,constraint:"Profile the runs resolve config and credentials under, and \u2014 under --scope profile \u2014 the profile this cron lists and cancels within. A profile id or manifest name from the <profiles> list below; a close-enough name resolves to the nearest profile. Defaults to the calling node's ($CRTR_PROFILE_ID)."},{kind:"flag",name:"scope",type:"enum",choices:["profile","global"],required:!1,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:!0,constraint:"The server-minted armed cron id \u2014 inspect with `cron show <cron_id>`, cancel with `cron cancel <cron_id>`."},{name:"fire_at",type:"string",required:!0,constraint:"Next fire (UTC ISO)."},{name:"recur",type:"string",required:!0,constraint:'Cadence display; "none" for a one-shot.'}],outputKind:"object",dynamicState:o(()=>N(),"dynamicState"),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 \u2014 unless --on-output silent."]},run:o(async n=>{let e=typeof n.command=="string"?n.command.trim():"";if(e===""&&(e=(await Y()).trim()),e==="")throw new c({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 t=typeof n.name=="string"?n.name.trim():"";if(t==="")throw new c({error:"missing_name",message:"--name is required",field:"name",next:"Pass --name <label>."});const r=typeof n.at=="string"&&n.at!==""?n.at:void 0,i=typeof n.every=="string"&&n.every!==""?n.every:void 0;if(r===void 0==(i===void 0))throw new c({error:"bad_schedule",message:r===void 0?"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 a=typeof n.tz=="string"&&n.tz!==""?n.tz:void 0,m=new Date;let d,$=null;if(i!==void 0){const s=H(i,k(m,a));"error"in s&&b(s.error),d=s.firstFireAt,$=s.recur}else{const s=D(r,k(m,a));"error"in s&&b(s.error),d=s.fireAt}let T=null;const R=typeof n.expires=="string"&&n.expires!==""?n.expires:void 0;if(R!==void 0){const s=D(R,k(m,a));"error"in s&&b(s.error),T=s.fireAt}const q=typeof n.anchor=="string"&&n.anchor!==""?n.anchor:void 0,A=n.anchorSelf===!0;if(q!==void 0&&A)throw new c({error:"bad_anchor",message:"--anchor and --anchor-self are mutually exclusive",next:"Pass one anchor or the other."});let g=q??null;if(A){const s=E();if(s===void 0||s==="")throw new c({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."});g=s}const C=n.cancelOnWake===!0;if(C&&g===null)throw new c({error:"cancel_on_wake_needs_anchor",message:"--cancel-on-wake requires an anchor",next:"Add --anchor <node-id> or --anchor-self."});const I=typeof n.runTimeout=="string"&&n.runTimeout!==""?J(n.runTimeout):void 0,z=V(typeof n.cwd=="string"&&n.cwd!==""?n.cwd:void 0),j=G(n.env),O=typeof n.profile=="string"&&n.profile!==""?n.profile:void 0,w=P(),y=O!==void 0?U(O):w!==void 0&&w.trim()!==""?B(w).profileId:void 0,S=n.scope??(y!==void 0?"profile":"global");if(S==="profile"&&y===void 0)throw new c({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 _=E(),v=await l().armCron({name:t,command:e,fire_at:d,recur:$,tz:a??null,created_by:_!==void 0&&_!==""?_:null,cwd:z,env_json:j,profile:y??null,scope:S,on_output:n.onOutput,sink:typeof n.sink=="string"&&n.sink!==""?n.sink:null,tier:n.tier??"urgent",expires_at:T,anchor_node:g,cancel_on_wake:C,...I!==void 0?{run_timeout_s:I}:{},overlap:n.overlap??"skip"}).catch(u);return{cron_id:v.cron_id,fire_at:v.fire_at,recur:x(v.recur)}},"run"),render:o(n=>{const e=String(n.recur),t=e==="none"?"one-shot (row deleted after the run)":e;return`Cron armed \u2014 ${String(n.cron_id)}.
+
+- next fire: ${String(n.fire_at)}
+- cadence: ${t}
+
+It runs daemon-side; nothing more to do here. Inspect it with \`crtr cron show ${String(n.cron_id)}\`; cancel with \`crtr cron cancel ${String(n.cron_id)}\` from its profile, or pass \`--profile <profile>\` from another profile.`},"render")}),ne=h({name:"list",description:"what is scheduled, with next fire and recent health",whenToUse:"you want to see every cron in scope \u2014 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:!0,constraint:"One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), held (true after an exit-75 gate; a recurring row re-checks at fire_at or when a host platform calls `POST /v1/crons/poke`, while a one-shot needs that call or `crtr cron run <cron-id>`), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered \u2014 null if it never ran)."}],outputKind:"object",effects:["None. Read-only."]},run:o(async()=>({crons:(await l().listCrons(f()).catch(u)).map(e=>({cron_id:e.cron_id,name:e.name,fire_at:e.fire_at,recur:x(e.recur),state:e.state,held:e.held,on_output:e.on_output,sink:e.sink,expires_at:e.expires_at,last_run:e.last_run}))}),"run"),render:o(n=>{const e=n.crons;if(e.length===0)return"No crons armed.";const t=e.map(r=>{const i=[`next ${r.fire_at}`,r.recur==="none"?"one-shot":r.recur,r.sink!==null?`${r.on_output} \u2192 ${r.sink}`:r.on_output,`last: ${Q(r.last_run)}`];r.expires_at!==null&&i.push(`expires ${r.expires_at}`);const a=r.state==="paused"?r.held?" [PAUSED (held) \u2014 resume or cancel]":" [PAUSED \u2014 resume or cancel]":r.held?r.recur==="none"?` [HELD \u2014 last run exited 75; run manually with \`crtr cron run ${r.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`]`:" [HELD \u2014 last run exited 75; re-checks at the next cadence or when a host platform calls `POST /v1/crons/poke`]":"";return`- ${r.name} (${r.cron_id}) \u2014 ${i.join(", ")}${a}`});return`${e.length} cron(s):
+
+${t.join(`
+`)}`},"render")}),re=h({name:"show",description:"one cron: full config plus its run history",whenToUse:'you want to inspect one cron \u2014 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:!0,constraint:"The cron to inspect (from `cron list`)."}],output:[{name:"cron",type:"object",required:!0,constraint:"The full cron config: command, schedule, snapshotted context (cwd, profile, scope, env var names \u2014 values stay server-side), disposition, sink, coupling, state."},{name:"runs",type:"object[]",required:!0,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:["None. Read-only."]},run:o(async n=>{const e=p(n),t=await l().showCron(e,f()).catch(r=>u(r,"Check the id against `crtr cron list`."));return{cron:t.cron,runs:t.runs}},"run"),render:o(n=>{const e=n.cron,t=n.runs,r=e.recur!==null?x(e.recur):e.held?"one-shot":`one-shot at ${e.fire_at}`,i=e.tz!==null?` (tz ${e.tz})`:"",a=e.held?e.recur!==null?`- schedule: ${r}${i} \u2014 next re-check ${e.fire_at} (held \u2014 also re-checks when a host platform calls \`POST /v1/crons/poke\`; last run exited 75)`:e.expires_at!==null?`- schedule: ${r}${i} \u2014 no scheduled re-check \u2014 expires ${e.expires_at} (held \u2014 run manually with \`crtr cron run ${e.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`; deleted unfired at expiry)`:`- schedule: ${r}${i} \u2014 no scheduled re-check (held \u2014 run manually with \`crtr cron run ${e.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`)`:`- schedule: ${r}${i} \u2014 next fire ${e.fire_at}`,m=e.state==="paused"?e.held?" \u2014 PAUSED (held)":" \u2014 PAUSED":e.held?" \u2014 HELD":"",d=[`# ${e.name} (${e.cron_id})${m}`,"",a,`- disposition: ${e.on_output}${e.sink!==null?` \u2192 ${e.sink} (tier ${e.tier})`:""}`,`- context: cwd ${e.cwd}${e.profile!==null?`, profile ${e.profile}`:""}, scope ${e.scope}${e.env_keys.length>0?`, env ${e.env_keys.join(", ")}`:""}`,`- run: timeout ${e.run_timeout_s}s, overlap ${e.overlap}${e.run_state==="running"?" \u2014 a run is IN FLIGHT now":""}`];return e.expires_at!==null&&d.push(`- expires: ${e.expires_at}`),e.anchor_node!==null&&d.push(`- anchored to node ${e.anchor_node}${e.cancel_on_wake?" (canceled when it wakes)":""}`),e.created_by!==null&&d.push(`- created by node ${e.created_by}`),d.push("","## Command","","```bash",e.command,"```","",`## Runs (most recent first, last ${t.length})`,""),d.push(...t.length>0?t.map(X):["(no runs yet)"]),d.join(`
+`)},"render")}),te=h({name:"run",description:"execute now, out of band \u2014 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:!0,constraint:"The cron to run (from `cron list`)."}],output:[{name:"exit_code",type:"number",required:!1,constraint:"The run's exit code (-1 = timeout kill; null when the process failed to start)."},{name:"duration_ms",type:"number",required:!0,constraint:"Wall-clock run time."},{name:"stdout_head",type:"string",required:!1,constraint:"Captured stdout (head)."},{name:"stderr_head",type:"string",required:!1,constraint:"Captured stderr (head)."},{name:"delivered",type:"string",required:!0,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:o(async n=>{const e=p(n),t=await l().showCron(e,f()).catch(a=>u(a,"Check the id against `crtr cron list`."));return await l({timeoutMs:t.cron.run_timeout_s*1e3+15e3}).runCron(e,f()).catch(a=>u(a))},"run"),render:o(n=>{const e=n,r=[`Run settled \u2014 exit ${e.exit_code===null?"no exit (process error)":e.exit_code===-1?"-1 (TIMEOUT)":String(e.exit_code)}, ${e.duration_ms??"?"}ms.`,"",`- delivered: ${e.delivered??"(nothing recorded)"}`];return e.stdout_head!==null&&r.push("","## stdout (head)","",e.stdout_head),e.stderr_head!==null&&r.push("","## stderr (head)","",e.stderr_head),r.join(`
+`)},"render")}),oe=h({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 \u2014 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:!0,constraint:"The cron to pause (from `cron list`)."}],output:[],outputKind:"object",effects:["Stops the cron firing until `cron resume`. An in-flight run settles normally; the row just stops being due."]},run:o(async n=>{const e=p(n);return await l().pauseCron(e,f()).catch(t=>u(t,"Check the id against `crtr cron list`.")),{}},"run"),render:o(()=>"Cron paused.","render")}),ie=h({name:"resume",description:"re-arm a paused cron",whenToUse:"a paused cron should fire again \u2014 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:!0,constraint:"The cron to resume (from `cron list`)."}],output:[{name:"fire_at",type:"string",required:!0,constraint:"Next fire \u2014 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:o(async n=>{const e=p(n);return{fire_at:(await l().resumeCron(e,f()).catch(r=>u(r,"Check the id against `crtr cron list`."))).fire_at}},"run"),render:o(n=>`Cron resumed \u2014 next fire ${String(n.fire_at)} (if that is already past, it fires on the next tick).`,"render")}),se=h({name:"cancel",description:"remove one cron (idempotent)",whenToUse:"a scheduled command should stop firing \u2014 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:!0,constraint:"The cron to remove (from `cron list`, or $CRTR_CRON_ID inside a run)."},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Profile scope to cancel within. Defaults to the calling node's profile; pass the profile id or manifest name for a cron armed under another profile."}],output:[],outputKind:"object",dynamicState:o(()=>N(),"dynamicState"),effects:["Deletes the cron row and its run history; kills any in-flight run. A no-op if already gone."]},run:o(async n=>{const e=p(n),t=process.env.CRTR_RUN_ID;return await l().cancelCron(e,{...f(n.profile),...t===void 0||t===""?{}:{run_id:t}}).catch(r=>u(r,"Check the id against `crtr cron list`.")),{}},"run"),render:o(()=>"Cron canceled.","render")});function ye(){return M({name:"cron",rootEntry:{concept:"one scheduling primitive \u2014 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 (its disposition defaults to on-change), 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 gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent \u2014 right when the recurrence is your polling cadence. Exit 75 holds the row. A held recurring row re-checks at its next natural slot, or when a host platform calls the daemon's `POST /v1/crons/poke` endpoint. A held one-shot has no scheduled re-check: it stays held until that endpoint is called, or you execute its bash explicitly with `crtr cron run <cron-id>` (which does not unhold or reschedule the row). A local filesystem condition does not call the daemon, so use --every for that condition or run the cron explicitly after it changes. Any other nonzero exit is a real failure and escalates per --on-output. Keep gate errors nonzero so a broken probe is loud instead of silently held. Beyond the exit-code contract, 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:[ee,ne,re,te,oe,ie,se]})}o(ye,"registerCron");export{ye as registerCron};