@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/task-cli/cli.js

@@ -0,0 +1,773 @@
+import { productName } from '../home/display.js';
+import { commandText } from '../home/command.js';
+import { productEnv } from '../core/product-env.js';
+import { randomUUID } from 'node:crypto';
+import { open as openFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { controlLocation } from '../contract/index.js';
+import { apiRunSchema, archiveFinishedResponseSchema, cancelResponseSchema, finishResponseSchema, messageResponseSchema, runRecordSchema, runStatusSchema, } from '../contract/index.js';
+import { changesPayloadSchema } from '../contract/index.js';
+import { pendingAskOf } from '../contract/index.js';
+import { asksQuestion } from '../contract/index.js';
+import { runHistoryContextSchema } from '../contract/index.js';
+import { skillSchema } from '../contract/index.js';
+import { openUrl } from '../open-url.js';
+import { RUNNER_IDS } from '../core/agent-runner.js';
+import { runnerFlag, skillFlagIssue, skillTaskSteps } from '../workflows/types.js';
+import { discoverCockpit } from './discovery.js';
+import { handoffUrl, invalidResponse, refuse, request, TaskCliError, threadUrl } from './http.js';
+import { projectListRow, projectStatus } from './projections.js';
+import { DEFAULT_WAIT_UNTIL, readLog, requestRunSummaries, waitForRuns } from './watch.js';
+/**
+ * `cez task` — start, watch and steer cockpit tasks from a terminal or a bot (#504, spec
+ * 2026-09-24-cez-task-cli). A thin JSON client over the cockpit's own run routes: one JSON
+ * object per invocation, and an exit code a caller can branch on without parsing a status.
+ */
+export const EXIT = { ok: 0, failed: 1, refused: 2, timeout: 3, usage: 64 };
+const COMMON = {
+    url: { type: 'string', help: '<origin>          Cockpit to use instead of discovery (also CEZ_URL).' },
+    repo: { type: 'string', help: '<dir>            Checkout whose cockpit to find (default: cwd).' },
+    help: { type: 'boolean', help: '                 Show help; needs no cockpit.' },
+};
+const STATUS_VALUES = runStatusSchema.options.join(', ');
+const TASK_TEXT_MAX_CHARS = 100_000;
+const DEFAULT_TIMEOUT_SECONDS = 600;
+const MAX_TIMEOUT_SECONDS = 1_800;
+const TIMEOUT_FLAG = { type: 'string', help: `<1-${MAX_TIMEOUT_SECONDS}>  Give up after this many seconds (default ${DEFAULT_TIMEOUT_SECONDS}).` };
+/** Shared by `wait`, `start --wait` (#553) and `log --follow` (#931): attention is the default, settled the opt-in. */
+const UNTIL_FLAG = { type: 'string', help: '<attention|settled> attention (default): stop when the task needs you or ends; settled: terminal status only.' };
+export const OPERATIONS = {
+    start: {
+        args: "--task-file <path|-> | '<task>'",
+        description: 'Start a task in the cockpit serving this checkout.',
+        positionals: [0, 1],
+        flags: {
+            'task-file': { type: 'string', help: '<path|->     Read the task from a file, or stdin with -.' },
+            'request-id': { type: 'string', help: '<UUID>     Retry-safe id; reuse it when retrying this start.' },
+            workflow: { type: 'string', help: '<name>       Workflow (default quick-task).' },
+            skill: { type: 'string', help: '<name>          Run one discovered skill instead of a workflow.' },
+            runner: { type: 'string', help: `<id>           ${RUNNER_IDS.join(' | ')}.` },
+            backend: { type: 'string', help: '<id>          Alias of --runner.' },
+            model: { type: 'string', help: '<model>         Model override.' },
+            effort: { type: 'string', help: '<level>       Reasoning effort.' },
+            autonomous: { type: 'boolean', help: '         Never park for input; run to completion.' },
+            'archive-when-done': { type: 'boolean', help: '  Archive after Done (default off); with --auto-merge-pr, merge first.' },
+            'auto-merge-pr': { type: 'boolean', help: '      Merge the task PR after Done when current-head CI and GitHub rules pass (default off); may mark a draft ready.' },
+            'no-worktree': { type: 'boolean', help: '      Run in the repo working tree, not a worktree.' },
+            'no-workers': { type: 'boolean', help: `       Do not let this task start or resume ${productName('Cezar')} workers (default on).` },
+            'no-messaging': { type: 'boolean', help: '     Block new peer-task messages; worker messages and replies to earlier requests stay (default on).' },
+            wait: { type: 'boolean', help: '               Then wait until the task needs you or ends (see wait).' },
+            until: UNTIL_FLAG,
+            'timeout-seconds': TIMEOUT_FLAG,
+            notify: { type: 'boolean', help: '             POST status changes to the project webhook (default when it has one).' },
+            'no-notify': { type: 'boolean', help: '          Do not notify the project webhook.' },
+        },
+    },
+    list: {
+        args: '',
+        description: 'List tasks, newest first: currentStepId when running, pullRequestUrl when done/review, error when failed (first line, 200 characters including … when cut). Workers are left out; address one by id.',
+        positionals: [0, 0],
+        flags: {
+            status: { type: 'string', help: `<s>[,<s>…]     Only these statuses: ${STATUS_VALUES}.` },
+            limit: { type: 'string', help: '<n>             At most n rows (default 20).' },
+            all: { type: 'boolean', help: '                Include archived tasks.' },
+            full: { type: 'boolean', help: '               Print contract ApiRun rows.' },
+        },
+    },
+    status: {
+        args: '<id>',
+        description: 'Show one task, including handoffUrl (the handoff endpoint) and the full error when set.',
+        positionals: [1, 1],
+        flags: { full: { type: 'boolean', help: '               Print the contract ApiRun.' } },
+    },
+    log: {
+        args: '<id>',
+        description: "Print a task's recent transcript as JSON lines, oldest first.",
+        positionals: [1, 1],
+        flags: {
+            since: { type: 'string', help: '<seq>           Only events after this seq.' },
+            'max-chars': { type: 'string', help: '<n>        Keep the newest lines within n characters (default 8000).' },
+            follow: { type: 'boolean', help: '             Keep streaming until the task needs you or ends (see wait), or the timeout.' },
+            until: UNTIL_FLAG,
+            'timeout-seconds': TIMEOUT_FLAG,
+        },
+    },
+    wait: {
+        args: '<id>...',
+        description: 'Block until the tasks need you (default) or settle; exit 0 done/review/attention, 1 failed/cancelled, 3 timeout.',
+        positionals: [1, 32],
+        flags: {
+            mode: { type: 'string', help: '<any|all>        Return on the first task or on all of them (default all).' },
+            until: UNTIL_FLAG,
+            'timeout-seconds': TIMEOUT_FLAG,
+        },
+    },
+    send: {
+        args: "<id> '<text>' | <id> --text-file <path|->",
+        description: 'Human input: steer or answer a task. Delivered to a live session, queued before it starts, resumed from a closed session with --resume (examples below).',
+        positionals: [1, 2],
+        flags: {
+            'text-file': { type: 'string', help: '<path|->     Read the text from a file, or stdin with -.' },
+            resume: { type: 'boolean', help: '             Reopen a closed session with this text.' },
+            notify: { type: 'boolean', help: '             Also turn the project webhook on for this task.' },
+        },
+    },
+    notify: {
+        args: "<id> [--message '<note>' | --message-file <path|->]",
+        description: 'Hand a task to the project webhook (on), or stop notifying it (--off). A worker is refused: notify its parent.',
+        positionals: [1, 1],
+        flags: {
+            off: { type: 'boolean', help: '                Stop notifying the webhook about this task.' },
+            message: { type: 'string', help: "'<note>'       Note for the webhook's task.subscribed delivery." },
+            'message-file': { type: 'string', help: '<path|->  Read the note from a file, or stdin with -.' },
+        },
+    },
+    stop: { args: '<id>', description: 'Cancel a task.', positionals: [1, 1], flags: {} },
+    finish: { args: '<id>', description: 'Close a waiting session as done.', positionals: [1, 1], flags: {} },
+    archive: { args: '<id>', description: 'Archive a task.', positionals: [1, 1], flags: {} },
+    unarchive: { args: '<id>', description: 'Restore an archived task.', positionals: [1, 1], flags: {} },
+    'archive-finished': { args: '', description: 'Archive finished tasks (scheduled runs and owned workers excluded).', positionals: [0, 0], flags: {} },
+    diff: {
+        args: '<id>',
+        description: "Show a task's changes.",
+        positionals: [1, 1],
+        flags: { stat: { type: 'boolean', help: '               Per-file counts instead of the patch.' } },
+    },
+    open: {
+        args: '<id>',
+        description: "Print (and open) a task's thread URL.",
+        positionals: [1, 1],
+        flags: { 'no-open': { type: 'boolean', help: '         Print the URL only.' } },
+    },
+};
+/**
+ * The clear contract (#553, #609), printed on every command a bot reads a run's state from.
+ * `attention` and `attentionLabel` come from the cockpit's own attention function (the
+ * contract's `deriveAttention`), so what the CLI says a run needs is what Needs You shows.
+ */
+const ATTENTION_HELP_OPERATIONS = new Set(['start', 'wait', 'status', 'list', 'log']);
+const ATTENTION_HELP = [
+    'Attention — when a task needs you:',
+    '  status, list, wait and log --follow carry `attention` (the cockpit bucket) and',
+    '  `attentionLabel` (its phrase), derived by the same function as the cockpit\'s Needs You.',
+    '  Read those, not the raw status:',
+    '  - `waiting` is attention even when no question is pending (a finished turn parks the task);',
+    '    a pending question also shows as `question` on status, its context as `questionContext`.',
+    '  - `waiting` on its own open PR or timer wait (attentionLabel "waiting for CI", "waiting for merge" or "monitoring")',
+    '    is neither settled nor attention: the agent is still watching what it registered. attention: running.',
+    '  - a task parked on its own workers ("waiting on 2 workers") is attention: none; keep waiting.',
+    '  - a task held by a provider usage limit ("usage limit, resumes <ISO time>") is attention: none;',
+    '    it resumes itself at that time.',
+    '  - attention: waiting | error | permission ends a wait or a follow; attentionLabel says why',
+    '    ("needs you", "needs review", "failed").',
+    '  --until attention (default) stops when the task needs you or ends. --until settled is the',
+    '  opt-in for autonomous runs and bots that want terminal state only (done/review/failed/cancelled).',
+    commandText('  cez task wait <id>                   # default: stops when the task needs you'),
+    commandText('  cez task wait <id> --until settled   # terminal status only'),
+    commandText("  cez task start '…' --wait            # returns as soon as the agent parks for follow-up"),
+    commandText("  cez task start '…' --wait --autonomous --until settled   # runs to completion, then returns"),
+    commandText('  cez task log <id> --follow             # default: stops when the task needs you'),
+    commandText('  cez task log <id> --follow --until settled   # streams until a terminal status'),
+    '',
+];
+function usage() {
+    return { operations: Object.entries(OPERATIONS).map(([name, op]) => ({ name, synopsis: commandText(`cez task ${name} ${op.args}`).trim() })) };
+}
+function usageError(error, detail = {}) {
+    throw new TaskCliError(EXIT.usage, { code: 'invalid_input', error, ...detail, usage: usage() });
+}
+export function taskHelp(operation) {
+    const names = operation ? [operation] : Object.keys(OPERATIONS);
+    const flags = new Map();
+    for (const name of names)
+        for (const [flag, spec] of Object.entries(OPERATIONS[name].flags))
+            flags.set(flag, spec);
+    for (const [flag, spec] of Object.entries(COMMON))
+        flags.set(flag, spec);
+    return [
+        `${productName('cezar')} task — start, watch and steer cockpit tasks from the terminal`, '', 'Usage:',
+        commandText('  cez task [--url <origin> | --repo <dir>] <operation> …'),
+        ...names.flatMap((name) => {
+            const op = OPERATIONS[name];
+            return [commandText(`  cez task ${name} ${op.args}`).trimEnd(), `    ${op.description}`];
+        }), '', 'Options:',
+        ...[...flags].map(([flag, spec]) => `  --${flag} ${spec.help}`), '',
+        ...(names.some((name) => ATTENTION_HELP_OPERATIONS.has(name)) ? ATTENTION_HELP : []),
+        ...(names.includes('start') ? [
+            'Safe task input (file or stdin):',
+            commandText('  cez task start --task-file task.md'),
+            commandText("  cez task start --task-file - <<'EOF'"),
+            commandText('Fix the `cez task` docs; keep $(example) literal.'),
+            'EOF', '',
+            'POSIX shells expand backticks and $() in double-quoted arguments',
+            'before the CLI receives the text. Do not put raw backticks in double-quoted task arguments.',
+            'Use --task-file PATH or --task-file - with a quoted heredoc delimiter as above.',
+            commandText("For short tasks, a single-quoted positional argument still works: cez task start 'Fix the typo'."), '',
+        ] : []),
+        ...(names.includes('send') ? [
+            'Send — steer, answer or reopen:',
+            '  delivery: delivered means the live session accepted the text; queued means it is saved',
+            '  for a task that has not started; resumed means --resume reopened a closed session.',
+            '  Steer while running:',
+            commandText("    cez task send <id> 'Use the retry helper instead'"),
+            '  Answer a pending question after wait ends with attention: waiting, or status shows question:',
+            commandText("    cez task send <id> 'Use option A'"),
+            '  Reopen a settled session:',
+            commandText("    cez task send <id> --resume '…'"),
+            '  Without --resume a closed session returns delivery: not-delivered and a next command.',
+            '  Use --text-file <path|-> for multi-line or shell-sensitive text; --text-file - reads stdin.',
+            commandText('  See the safe task input / quoting note in cez task start --help; the same shell rules apply.'),
+            '',
+        ] : []),
+        'Commands find the running cockpit that serves this checkout (ports 4321-4370) and print JSON.',
+        `notify: with a task webhook set in ${controlLocation('general')}, start notifies it unless --no-notify;`,
+        'the webhook gets task.status, task.question and task.subscribed POSTs.',
+        'Exit codes: 0 ok (wait/start --wait: done, review, or stopped for attention) · 1 task failed/cancelled',
+        'or message not delivered · 2 no cockpit or refused · 3 timed out · 64 usage error.',
+    ].join('\n');
+}
+async function readStdin() {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buffer.length;
+        if (size > TASK_TEXT_MAX_CHARS * 4)
+            usageError('stdin is larger than the 100000-character limit');
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, size).toString('utf8');
+}
+async function readTextFile(path) {
+    let handle;
+    try {
+        handle = await openFile(path, 'r');
+    }
+    catch {
+        usageError(`cannot read ${path}`);
+    }
+    try {
+        const buffer = Buffer.alloc(TASK_TEXT_MAX_CHARS * 4 + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > TASK_TEXT_MAX_CHARS * 4)
+            usageError(`${path} is larger than the 100000-character limit`);
+        return buffer.subarray(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** A positional, or `--*-file <path|->`; never both, never empty. */
+async function textArgument(io, operation, positional, file, what) {
+    if (positional !== undefined && file !== undefined)
+        usageError(`${operation} takes the ${what} as an argument or a file, not both`);
+    const text = file === undefined ? positional : file === '-' ? await (io.stdin ?? readStdin)() : await readTextFile(file);
+    if (text === undefined || !text.trim())
+        usageError(`${operation} is missing the ${what}`);
+    if (text.length > TASK_TEXT_MAX_CHARS)
+        usageError(`${what} is longer than ${TASK_TEXT_MAX_CHARS} characters`);
+    return text;
+}
+/** Every `--flag` before the operation must be COMMON; a value is `--flag=value` or the next token. */
+function leadingOptions(argv) {
+    // Only COMMON belongs before the operation. Keep the operation's existing strict
+    // parseArgs path below, including its handling of positionals and repeated flags.
+    const leading = {};
+    let index = 0;
+    while (argv[index]?.startsWith('-')) {
+        const token = argv[index];
+        const equals = token.indexOf('=');
+        const option = equals === -1 ? token : token.slice(0, equals);
+        const flag = option === '-h' ? 'help' : option.startsWith('--') ? option.slice(2) : option;
+        if (!Object.hasOwn(COMMON, flag)) {
+            usageError(`unknown option '${option}' before the operation; only --url, --repo and --help go there`);
+        }
+        if (leading[flag] !== undefined)
+            usageError(`duplicate option '--${flag}'`);
+        if (COMMON[flag].type === 'boolean') {
+            if (equals !== -1)
+                usageError(`option '${option}' does not take a value`);
+            leading[flag] = true;
+        }
+        else {
+            const value = equals === -1 ? argv[++index] : token.slice(equals + 1);
+            if (value === undefined || value === '' || value.startsWith('--'))
+                usageError(`option '${option}' requires a value`);
+            leading[flag] = value;
+        }
+        index += 1;
+    }
+    return { leading, index };
+}
+/** The operation's strict parseArgs path: only its flags plus COMMON, positionals allowed. */
+function strictParse(name, argv, index, operation) {
+    const options = Object.fromEntries(Object.entries({ ...operation.flags, ...COMMON }).map(([flag, spec]) => [flag, { type: spec.type, ...(spec.multiple ? { multiple: true } : {}) }]));
+    try {
+        return parseArgs({ args: argv.slice(index + 1), options, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        usageError(`${name}: ${error instanceof Error ? error.message : 'invalid arguments'}`);
+    }
+}
+/** Leading COMMON options fill gaps only: a same-named operation flag already present is a duplicate. */
+function applyLeading(values, leading) {
+    for (const [flag, value] of Object.entries(leading)) {
+        if (values[flag] !== undefined)
+            usageError(`duplicate option '--${flag}'`);
+        values[flag] = value;
+    }
+}
+function parseOperation(argv) {
+    const { leading, index } = leadingOptions(argv);
+    const name = argv[index];
+    if (name === undefined)
+        usageError('missing operation');
+    const operation = OPERATIONS[name];
+    if (!operation)
+        usageError(`unknown operation '${name}'`);
+    const parsed = strictParse(name, argv, index, operation);
+    const values = parsed.values;
+    applyLeading(values, leading);
+    if (!values.help) {
+        const [min, max] = operation.positionals;
+        if (parsed.positionals.length < min)
+            usageError(`${name} is missing a positional`);
+        if (parsed.positionals.length > max)
+            usageError(`${name} has an extra argument`);
+    }
+    return { name, values, positionals: parsed.positionals };
+}
+function positiveInt(value, flag, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !/^\d+$/.test(value) || Number(value) < 1 || Number(value) > max) {
+        usageError(`--${flag} must be an integer from 1 to ${max}`);
+    }
+    return Number(value);
+}
+function nonNegativeInt(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !/^\d+$/.test(value))
+        usageError(`--${flag} must be a non-negative integer`);
+    return Number(value);
+}
+function timeoutMs(values) {
+    return (positiveInt(values['timeout-seconds'], 'timeout-seconds', MAX_TIMEOUT_SECONDS) ?? DEFAULT_TIMEOUT_SECONDS) * 1_000;
+}
+function oneOf(value, flag, allowed, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || !allowed.includes(value))
+        usageError(`--${flag} must be one of ${allowed.join(', ')}`);
+    return value;
+}
+function waitUntil(values) {
+    return oneOf(values.until, 'until', ['settled', 'attention'], DEFAULT_WAIT_UNTIL);
+}
+function waitMode(values) {
+    return oneOf(values.mode, 'mode', ['any', 'all'], 'all');
+}
+function listLimit(values) {
+    return positiveInt(values.limit, 'limit', 1_000) ?? 20;
+}
+function logSince(values) {
+    return nonNegativeInt(values.since, 'since') ?? 0;
+}
+function logMaxChars(values) {
+    return positiveInt(values['max-chars'], 'max-chars', 1_000_000) ?? 8_000;
+}
+function statuses(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const list = value.split(',').map((entry) => entry.trim()).filter(Boolean);
+    const invalid = list.find((entry) => !runStatusSchema.safeParse(entry).success);
+    if (invalid)
+        usageError(`unknown status '${invalid}'; one of ${STATUS_VALUES}`);
+    return new Set(list);
+}
+/** Every flag check `execute` makes, run up front so a bad flag never waits on discovery. */
+function validateFlags(name, values) {
+    if (name === 'start') {
+        const issue = skillFlagIssue({
+            skill: values.skill,
+            workflow: values.workflow,
+        });
+        if (issue)
+            usageError(issue);
+        const runner = runnerFlag({ runner: values.runner, backend: values.backend });
+        if (runner.issue)
+            usageError(runner.issue);
+        if (values.notify && values['no-notify'])
+            usageError('--notify and --no-notify cannot be used together');
+        if (values.until !== undefined && !values.wait)
+            usageError('--until needs --wait');
+    }
+    if (name === 'log' && values.until !== undefined && !values.follow)
+        usageError('--until needs --follow');
+    // Strict parseArgs gives each flag only to the operations that list it.
+    if (values.off && (values.message !== undefined || values['message-file'] !== undefined))
+        usageError('--off takes no note');
+    statuses(values.status);
+    listLimit(values);
+    waitMode(values);
+    waitUntil(values);
+    logSince(values);
+    logMaxChars(values);
+    if (name === 'wait' || name === 'log' || values.wait)
+        timeoutMs(values);
+}
+async function getRun(cockpit, id) {
+    const result = await request(cockpit, `/runs/${encodeURIComponent(id)}`);
+    if (result.status !== 200)
+        refuse(result);
+    const run = apiRunSchema.safeParse(result.data);
+    return run.success ? run.data : invalidResponse('run');
+}
+/** `list --full` prints contract `ApiRun` rows, so it alone still reads every full record. */
+async function listRuns(cockpit) {
+    const result = await request(cockpit, '/runs');
+    if (result.status !== 200)
+        refuse(result);
+    const runs = apiRunSchema.array().safeParse(result.data);
+    return runs.success ? runs.data : invalidResponse('run list');
+}
+/**
+ * Workers are steer targets of their parent, not tasks ops follows (#635): the list leaves them
+ * out, and subscribing one to the webhook is refused with the parent to subscribe instead. Every
+ * other id-addressed operation still reaches a worker.
+ */
+function workerParent(run) {
+    return run.delegation?.role === 'worker' ? run.delegation.parentRunId : undefined;
+}
+async function refuseWorkerNotify(cockpit, id) {
+    const parentId = workerParent(await getRun(cockpit, id));
+    if (parentId !== undefined) {
+        usageError(commandText(`task ${id} is a worker of task ${parentId}; notify the parent instead: cez task notify ${parentId}`), { parentId });
+    }
+}
+/** The latest valid unanswered question, from the same derivation the cockpit renders. */
+async function pendingQuestion(cockpit, id) {
+    const result = await request(cockpit, `/runs/${encodeURIComponent(id)}/history-context`);
+    const context = runHistoryContextSchema.safeParse(result.data);
+    return result.status === 200 && context.success ? pendingAskOf(context.data.contextEvents) : undefined;
+}
+/** The boolean start flags, each sent only when given, so an absent flag keeps the server default. */
+function startToggles(values) {
+    return {
+        ...(values.autonomous ? { autonomous: true } : {}),
+        ...(values['archive-when-done'] ? { archiveWhenDone: true } : {}),
+        ...(values['auto-merge-pr'] ? { autoMergePr: true } : {}),
+        ...(values['no-worktree'] ? { worktree: false } : {}),
+        ...(values['no-workers'] ? { allowWorkers: false } : {}),
+        ...(values['no-messaging'] ? { allowMessaging: false } : {}),
+    };
+}
+async function start(cockpit, io, values, task, print) {
+    const waitMs = values.wait ? timeoutMs(values) : undefined;
+    const requestId = values['request-id'] ?? randomUUID();
+    const skill = values.skill;
+    const { runner } = runnerFlag({ runner: values.runner, backend: values.backend });
+    // `--notify` is an explicit opt-in the server may refuse (no webhook: 400 with a hint). The
+    // implicit default only opts in where the project has a webhook, so a bot on a fresh project
+    // is never blocked (#589).
+    const notify = values['no-notify'] ? false : values.notify ? true : cockpit.hasWebhook ? true : undefined;
+    let warning;
+    if (skill !== undefined) {
+        // Discovery is advisory: the catalog can change before a queued run executes. The server
+        // handles missing skills with a plain prompt, and idempotent retries still go to POST /runs.
+        const unverified = `could not check whether skill "${skill}" is available; the run may use the plain prompt`;
+        try {
+            const catalog = await request(cockpit, '/skills?wait=1');
+            if (catalog.status === 200) {
+                const skills = skillSchema.array().safeParse(catalog.data);
+                warning = skills.success
+                    ? skills.data.some((entry) => entry.name === skill)
+                        ? undefined
+                        : `skill "${skill}" is not currently available; the run may use the plain prompt`
+                    : unverified;
+            }
+            else {
+                warning = unverified;
+            }
+        }
+        catch {
+            warning = unverified;
+        }
+    }
+    const result = await request(cockpit, '/runs', {
+        body: {
+            task,
+            ...(skill === undefined
+                ? { workflow: values.workflow ?? 'quick-task' }
+                : { steps: skillTaskSteps(skill) }),
+            runner,
+            model: values.model,
+            effort: values.effort,
+            ...startToggles(values),
+            notify,
+            clientRequestId: requestId,
+        },
+    });
+    if (result.status !== 200 && result.status !== 201)
+        refuse(result);
+    const run = runRecordSchema.safeParse(result.data);
+    if (!run.success)
+        invalidResponse('start');
+    const started = {
+        id: run.data.id,
+        url: threadUrl(cockpit, run.data.id),
+        status: run.data.status,
+        created: result.status === 201,
+        requestId,
+        notify: run.data.notify === true,
+        warning,
+        branch: run.data.branch,
+    };
+    if (waitMs === undefined) {
+        print(started);
+        return EXIT.ok;
+    }
+    const waited = await waitForRuns(cockpit, [run.data.id], { mode: 'all', until: waitUntil(values), timeoutMs: waitMs, pollMs: io.pollMs });
+    const final = waited.runs[0];
+    print({ ...started, ...final, until: waited.until, timedOut: waited.timedOut });
+    return waited.exitCode;
+}
+async function setNotify(cockpit, id, notify, message) {
+    const result = await request(cockpit, `/runs/${encodeURIComponent(id)}/notify`, {
+        body: { notify, message },
+    });
+    if (result.status !== 200)
+        refuse(result);
+    const run = runRecordSchema.safeParse(result.data);
+    return run.success ? run.data : invalidResponse('notify');
+}
+async function send(cockpit, values, id, text, print) {
+    const path = `/runs/${encodeURIComponent(id)}`;
+    if (values.notify)
+        await refuseWorkerNotify(cockpit, id);
+    // Before the message, so the status change it causes is already reported.
+    const notified = values.notify ? { notify: (await setNotify(cockpit, id, true, undefined)).notify === true } : {};
+    const delivered = await request(cockpit, `${path}/messages`, { body: { text } });
+    if (delivered.status === 200) {
+        const answer = messageResponseSchema.safeParse(delivered.data);
+        if (!answer.success)
+            invalidResponse('message');
+        const delivery = 'delivered' in answer.data ? 'delivered' : 'queued' in answer.data ? 'queued' : 'deferred';
+        print({ id, delivery, ...notified });
+        return EXIT.ok;
+    }
+    const closed = delivered.status === 409 && delivered.data?.error === 'session closed';
+    if (!closed)
+        refuse(delivered);
+    if (!values.resume) {
+        print({ id, delivery: 'not-delivered', reason: 'session closed', next: commandText(`cez task send ${id} '…' --resume`), ...notified });
+        return EXIT.failed;
+    }
+    const resumed = await request(cockpit, `${path}/continue`, { body: { text } });
+    if (resumed.status !== 200)
+        refuse(resumed);
+    print({ id, delivery: 'resumed', ...notified });
+    return EXIT.ok;
+}
+async function notify(cockpit, id, values, text, print) {
+    // --off stays open so a subscription made before this guard can still be undone.
+    if (!values.off)
+        await refuseWorkerNotify(cockpit, id);
+    const run = await setNotify(cockpit, id, !values.off, text);
+    print({ id, notify: run.notify === true, ...(text === undefined ? {} : { message: true }) });
+    return EXIT.ok;
+}
+async function wait(cockpit, io, values, positionals, print) {
+    const mode = waitMode(values);
+    const waited = await waitForRuns(cockpit, positionals, { mode, until: waitUntil(values), timeoutMs: timeoutMs(values), pollMs: io.pollMs });
+    print({ until: waited.until, runs: waited.runs, timedOut: waited.timedOut });
+    return waited.exitCode;
+}
+async function log(cockpit, id, io, values) {
+    const since = logSince(values);
+    const maxChars = logMaxChars(values);
+    // An unknown run is the history route's 404, passed through. Without --follow the replay
+    // ends at its boundary; the deadline is only a backstop there.
+    return readLog(cockpit, id, {
+        afterSeq: since, maxChars, follow: values.follow === true, until: waitUntil(values),
+        deadline: Date.now() + (values.follow ? timeoutMs(values) : 45_000),
+        print: (line) => io.stdout(line),
+    });
+}
+async function status(cockpit, id, values, print) {
+    const run = await getRun(cockpit, id);
+    if (values.full) {
+        print(run);
+        return EXIT.ok;
+    }
+    const question = asksQuestion(run) ? await pendingQuestion(cockpit, id) : undefined;
+    print({ ...projectStatus(run, threadUrl(cockpit, id), question), handoffUrl: handoffUrl(cockpit, id) });
+    return EXIT.ok;
+}
+async function list(cockpit, values, print) {
+    const wanted = statuses(values.status);
+    const limit = listLimit(values);
+    const listed = (runs) => runs
+        .filter((run) => workerParent(run) === undefined)
+        .filter((run) => values.all || !run.archived)
+        .filter((run) => !wanted || wanted.has(run.status))
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    // Without --all, archived runs are dropped above, so the windowed list (#864) has every row
+    // this prints; --all needs every archived run there is.
+    const summaries = () => requestRunSummaries(cockpit, undefined, values.all ? {} : { archived: 'recent' });
+    const runs = values.full ? listed(await listRuns(cockpit)) : listed(await summaries());
+    print({ runs: runs.slice(0, limit).map((run) => (values.full ? run : projectListRow(run))), total: runs.length });
+    return EXIT.ok;
+}
+async function stop(cockpit, path, id, print) {
+    const result = await request(cockpit, `${path}/cancel`, { body: {} });
+    const answer = cancelResponseSchema.safeParse(result.data);
+    if (result.status !== 200)
+        refuse(result);
+    if (!answer.success)
+        invalidResponse('cancel');
+    print({ id, cancelled: answer.data.cancelled });
+    return EXIT.ok;
+}
+async function finish(cockpit, path, id, print) {
+    const result = await request(cockpit, `${path}/finish`, { body: {} });
+    if (result.status !== 200)
+        refuse(result);
+    if (!finishResponseSchema.safeParse(result.data).success)
+        invalidResponse('finish');
+    print({ id, finished: true });
+    return EXIT.ok;
+}
+async function archive(cockpit, path, name, id, print) {
+    const archived = name === 'archive';
+    const result = await request(cockpit, `${path}/archive`, { body: { archived } });
+    if (result.status !== 200)
+        refuse(result);
+    const run = runRecordSchema.safeParse(result.data);
+    if (!run.success)
+        invalidResponse('archive');
+    print({ id: run.data.id, archived: run.data.archived === true });
+    return EXIT.ok;
+}
+async function archiveFinished(cockpit, print) {
+    const result = await request(cockpit, '/runs/archive-finished', { method: 'POST' });
+    if (result.status !== 200)
+        refuse(result);
+    const answer = archiveFinishedResponseSchema.safeParse(result.data);
+    if (!answer.success)
+        invalidResponse('archive-finished');
+    print(answer.data);
+    return EXIT.ok;
+}
+async function diff(cockpit, path, id, values, print) {
+    if (values.stat) {
+        const result = await request(cockpit, `${path}/changes`);
+        if (result.status !== 200)
+            refuse(result);
+        const changes = changesPayloadSchema.safeParse(result.data);
+        if (!changes.success)
+            invalidResponse('changes');
+        print({ id, stat: changes.data.stat, files: changes.data.files.map((file) => ({ path: file.path, status: file.status, adds: file.adds, dels: file.dels })) });
+        return EXIT.ok;
+    }
+    const result = await request(cockpit, `${path}/diff`);
+    if (result.status !== 200)
+        refuse(result);
+    print({ id, diff: typeof result.data === 'string' ? result.data : invalidResponse('diff') });
+    return EXIT.ok;
+}
+async function open(cockpit, io, id, values, print) {
+    const run = await getRun(cockpit, id);
+    const url = threadUrl(cockpit, run.id);
+    if (!values['no-open'])
+        (io.open ?? openUrl)(url);
+    print({ id: run.id, url, opened: !values['no-open'] });
+    return EXIT.ok;
+}
+/** One helper per operation, so this switch stays a dispatcher under the complexity limit. */
+async function execute(name, cockpit, io, values, positionals, text, print) {
+    const id = positionals[0];
+    const path = `/runs/${encodeURIComponent(id)}`;
+    switch (name) {
+        case 'start':
+            return start(cockpit, io, values, text, print);
+        case 'send':
+            return send(cockpit, values, id, text, print);
+        case 'notify':
+            return notify(cockpit, id, values, text, print);
+        case 'wait':
+            return wait(cockpit, io, values, positionals, print);
+        case 'log':
+            return log(cockpit, id, io, values);
+        case 'status':
+            return status(cockpit, id, values, print);
+        case 'list':
+            return list(cockpit, values, print);
+        case 'stop':
+            return stop(cockpit, path, id, print);
+        case 'finish':
+            return finish(cockpit, path, id, print);
+        case 'archive':
+        case 'unarchive':
+            return archive(cockpit, path, name, id, print);
+        case 'archive-finished':
+            return archiveFinished(cockpit, print);
+        case 'diff':
+            return diff(cockpit, path, id, values, print);
+        case 'open':
+            return open(cockpit, io, id, values, print);
+        default:
+            return usageError(`unknown operation '${name}'`);
+    }
+}
+export const AGENT_TASK_SEND_REMEDY = commandText("cez message progress <task-id> '<text>' --id <message-UUID> (needs task messaging on)");
+function refuseAgentSend(name, env) {
+    if (name === 'send' && productEnv('TASK_ID', env)?.trim()) {
+        throw new TaskCliError(EXIT.usage, {
+            code: 'invalid_input',
+            error: commandText('cez task send is human input. An agent inside a task cannot use it to message another task.'),
+            next: AGENT_TASK_SEND_REMEDY,
+        });
+    }
+}
+export async function runTaskCommand(argv, env, io = { stdout: (line) => console.log(line) }) {
+    const print = (value) => io.stdout(JSON.stringify(value));
+    try {
+        if (argv.length === 1 && (argv[0] === '-h' || argv[0] === '--help')) {
+            io.stdout(taskHelp());
+            return EXIT.ok;
+        }
+        const { name, values, positionals } = parseOperation(argv);
+        if (values.help) {
+            io.stdout(taskHelp(name));
+            return EXIT.ok;
+        }
+        refuseAgentSend(name, env);
+        // Input is judged before any cockpit is looked for: a usage error is exit 64 whether or not
+        // a cockpit is running, and stdin is read once, here.
+        const text = name === 'start'
+            ? await textArgument(io, 'start', positionals[0], values['task-file'], 'task')
+            : name === 'send'
+                ? await textArgument(io, 'send', positionals[1], values['text-file'], 'text')
+                : values.message !== undefined || values['message-file'] !== undefined
+                    ? await textArgument(io, 'notify', values.message, values['message-file'], 'note')
+                    : undefined;
+        validateFlags(name, values);
+        const cockpit = await (io.discover ?? discoverCockpit)({
+            url: values.url ?? (productEnv('URL', env)?.trim() || undefined),
+            repoDir: resolve(values.repo ?? process.cwd()),
+        });
+        return await execute(name, cockpit, io, values, positionals, text, print);
+    }
+    catch (error) {
+        if (error instanceof TaskCliError) {
+            print(error.body);
+            return error.exitCode;
+        }
+        print({ code: 'internal', error: error instanceof Error ? error.message : String(error) });
+        return EXIT.refused;
+    }
+}
+//# sourceMappingURL=cli.js.map