@shardflux/cli 0.24.0 → 0.24.1

package/dist/board-args.js

@@ -0,0 +1,155 @@
+const PROJECT_FILTER = { project: { type: 'string', value: '<id>', description: 'Only this project.' } };
+const PROJECT = { project: { type: 'string', value: '<id>', description: 'The project (default: the API key’s).' } };
+const BUCKET_FLAGS = (verb) => ({
+    now: { type: 'boolean', description: `${verb} Now.` },
+    next: { type: 'boolean', description: `${verb} Next.` },
+    later: { type: 'boolean', description: `${verb} Later.` },
+});
+const ORDER = {
+    after: { type: 'string', value: '<task-id>', description: 'Place it right after this task of its bucket.' },
+    first: { type: 'boolean', description: 'Place it first in its bucket.' },
+};
+const MODES = 'ask sends every permission request to you (shard needs-you); routine approves tests, builds, reads and installs for you; trusted approves everything except deploys, pushes to main and spending.';
+export const BOARD_COMMANDS = [
+    {
+        path: ['board'],
+        summary: 'Show the board: what needs you, then every task in Now, Next and Later (0.25.0+)',
+        positionals: [],
+        options: { ...PROJECT_FILTER, follow: { type: 'boolean', short: 'f', description: 'Keep printing each change as it happens, until Ctrl-C.' } },
+        description: [
+            'One board on every device: what waits on you comes first, oldest first, each with its id (shard needs-you answer',
+            'takes it) and what is asked. Then the tasks of Now, Next and Later in order: id, state (queued, working, needs_you,',
+            'done, unverified, failed), title or your words, and project. Reading the board never wakes a computer.',
+            '',
+            '--follow keeps printing changes from the held feed: a changed task with its bucket (or deleted, cleared), a sealed',
+            'report with its evidence, what started or stopped waiting on you, the approval policy. --json prints the board;',
+            'with --follow, the board on the first line, then one feed answer per line.',
+        ].join('\n'),
+        examples: ['shard board', 'shard board --follow', `shard board --json | jq -r '.needs_you[] | "\\(.id)\\t\\(.ask)"'`],
+    },
+    {
+        path: ['task', 'add'],
+        summary: 'Add a task in your own words (0.25.0+)',
+        positionals: [{ name: 'words', variadic: true, words: true, required: true }],
+        options: {
+            ...PROJECT,
+            next: { type: 'boolean', description: 'Add it to Next (default: Now).' },
+            later: { type: 'boolean', description: 'Add it to Later.' },
+            home: { type: 'boolean', description: 'A personal task: it runs on the project’s machine home, without a repository.' },
+            after: { type: 'string', value: '<task-id>', description: 'Place it right after this task of its bucket (default: last).' },
+            first: { type: 'boolean', description: 'Place it first in its bucket.' },
+        },
+        description: 'Your words are kept exactly as you wrote them. The project’s master agent picks the task up and starts the work; its reports arrive on the board (shard task show). Prints the task id, its bucket and its state.',
+        examples: ['shard task add Fix the wake race in resume', 'shard task add --later "Try a shorter pricing headline"', 'shard task add --first Hotfix the login redirect'],
+    },
+    {
+        path: ['task', 'show'],
+        summary: 'Show a task, its plan and every report sealed for it (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: {},
+        description: 'Prints its title or your words, its state, bucket and project, your exact words, the plan with each step’s state, the conversations that work on it, then each report oldest first: milestone, title, outcome and evidence (tests 12/12, live probe 200, screenshot) with the command, URL or file behind each. --json returns {task, reports}.',
+        examples: ['shard task show task_h7g4d7tqyv2pz3a2npyo4rpgzq', 'shard task show task_h7g4d7tqyv2pz3a2npyo4rpgzq --json | jq ".reports[-1].evidence"'],
+    },
+    {
+        path: ['task', 'edit'],
+        summary: 'Edit, move, keep or clear a task (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: {
+            text: { type: 'string', value: '<words>', description: 'New words; its master hears the change.' },
+            title: { type: 'string', value: '<title>', description: 'A short title ("" removes it).' },
+            ...BUCKET_FLAGS('Move it to'),
+            ...ORDER,
+            keep: { type: 'boolean', description: 'Keep an agent’s suggestion as a task of your own.' },
+            clear: { type: 'boolean', description: 'Clear it from the board (--no-clear brings it back).' },
+        },
+        description: 'Moving a task (--now, --next, --later, --after, --first) sets the order its master works in. Prints the task as shard board lists it.',
+        examples: ['shard task edit task_h7g4d7tqyv2pz3a2npyo4rpgzq --first', 'shard task edit task_h7g4d7tqyv2pz3a2npyo4rpgzq --next --title "Wake race"', 'shard task edit task_h7g4d7tqyv2pz3a2npyo4rpgzq --keep'],
+    },
+    {
+        path: ['task', 'rm'],
+        summary: 'Delete a task; its master stops the work (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: {},
+        description: 'Its follow-ups go with it, on every device.',
+    },
+    {
+        path: ['task', 'steer'],
+        summary: 'Send steering words to a task’s master (0.25.0+)',
+        positionals: [{ name: 'id', required: true }, { name: 'words', variadic: true, words: true, required: true }],
+        options: {},
+        description: 'Your words go to the agent that runs the task, which adjusts its plan. The task keeps its own words.',
+        examples: ['shard task steer task_h7g4d7tqyv2pz3a2npyo4rpgzq use postgres instead'],
+    },
+    {
+        path: ['task', 'clear-done'],
+        summary: 'Clear every finished task from the board (0.25.0+)',
+        positionals: [],
+        options: PROJECT_FILTER,
+        description: 'Clears done and unverified tasks on every device. shard task show <id> still reads their reports.',
+    },
+    {
+        path: ['needs-you'],
+        summary: 'List what waits on you, oldest first (0.25.0+)',
+        positionals: [],
+        options: PROJECT_FILTER,
+        description: [
+            'Everything your agents wait on, across the board: permission requests (perm_…), questions (cq_…, ask_…),',
+            'credential requests (cred_…), finished work to land (land_…) and Later tasks to keep or clear (prune_…). Each line is',
+            'the id, what is asked, and the command, options or branch behind it. Answer with shard needs-you answer <id>.',
+            '--json returns {data}.',
+        ].join('\n'),
+        examples: ['shard needs-you', 'shard needs-you --json'],
+    },
+    {
+        path: ['needs-you', 'answer'],
+        summary: 'Answer something that waits on you (0.25.0+)',
+        positionals: [{ name: 'id', required: true }, { name: 'decision' }],
+        options: {
+            everywhere: { type: 'boolean', description: 'With always: the rule covers every project.' },
+            text: { type: 'string', value: '<answer>', description: 'Your answer to an agent’s question.' },
+            pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for an agent’s question in a permission request (repeatable for a multi-select question; "<question>=<option>" when it asks several).' },
+            keep: { type: 'string', multiple: true, value: '<task-id>', description: 'Later tasks: keep these (repeatable); the rest are cleared.' },
+        },
+        description: [
+            'One command for every kind:',
+            '  perm_…    allow (this once), always (also adds the always-allow rule for the project; --everywhere for every',
+            '            project) or deny; an agent’s question takes --pick',
+            '  cq_…      --text <answer>: the agent gets it as its next message',
+            '  ask_…     --text <answer>: the task’s master gets it',
+            '  cred_…    deny (the value goes through the credential request, sealed for its computer)',
+            '  land_…    land (the worker merges its branch and pushes it), keep (the branch stays) or discard',
+            '  prune_…   --keep <task-id> for each task to keep, keep for all of them, or discard to clear them',
+            'The agent goes on as soon as you answer.',
+        ].join('\n'),
+        examples: ['shard needs-you answer perm_01a1300c-0000-7000-8000-000000000001 always', 'shard needs-you answer ask_rep_66cbevz65m72ij7mbiyrw4xvdy --text "eu-north-1"', 'shard needs-you answer land_conv_id4zts6jxsqraju2pggr55n3tq land'],
+    },
+    {
+        path: ['approvals'],
+        summary: 'Show the approval mode and the always-allow rules your agents work under (0.25.0+)',
+        positionals: [],
+        options: {},
+        description: `The mode answers the permission requests of your board’s conversations before they reach you: ${MODES} A rule always allows a tool for commands (or paths, URLs) that start with its pattern. Prints the default mode, each project’s own mode, then each rule: its id, tool, pattern and project.`,
+    },
+    {
+        path: ['approvals', 'set'],
+        summary: 'Set the approval mode of a project or the default (0.25.0+)',
+        positionals: [{ name: 'mode', required: true }],
+        options: { ...PROJECT, default: { type: 'boolean', description: 'Set the default mode, for every project without a mode of its own.' } },
+        description: `${MODES} default puts the project back on the default mode. Requests already waiting that the new mode covers are answered at once.`,
+        examples: ['shard approvals set trusted', 'shard approvals set ask --project 01a1415f-759f-7fb0-9d56-973ed5d27465', 'shard approvals set default'],
+    },
+    {
+        path: ['approvals', 'allow'],
+        summary: 'Always allow a tool for commands that start with a pattern (0.25.0+)',
+        positionals: [{ name: 'tool', required: true }, { name: 'pattern', variadic: true, words: true, required: true }],
+        options: { ...PROJECT, everywhere: { type: 'boolean', description: 'Cover every project.' } },
+        description: 'The tool as the agent’s harness names it (Bash, WebFetch, Edit) and the command prefix, path or URL it allows: "shard approvals allow Bash pnpm test" allows pnpm test and pnpm test --watch; "" allows every use of the tool. Waiting requests the rule covers are answered at once. Prints the rule’s id, tool, pattern and project.',
+        examples: ['shard approvals allow Bash pnpm test', 'shard approvals allow WebFetch https://docs.shardflux.dev/'],
+    },
+    {
+        path: ['approvals', 'remove'],
+        summary: 'Remove an always-allow rule (0.25.0+)',
+        positionals: [{ name: 'rule-id', required: true }],
+        options: {},
+    },
+];

package/dist/board-commands.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The Orchestrator board (0.25.0+, SDK 0.28.0): `shard board` (with --follow), `shard task add|show|edit|rm|steer|
+ * clear-done`, `shard needs-you [answer]` and `shard approvals [set|allow|remove]`. The command table is board-args.ts.
+ *
+ * Every command uses the project API key (SHARDFLUX_API_KEY, else the saved one): its board is the key's project.
+ * Text output is one line per item, tab-separated, id first; --json prints the API's objects.
+ */
+import type { ApprovalPolicy, ApprovalRule, Board, BoardUpdate, NeedsYouAnswer, NeedsYouAnswered, NeedsYouItem, Task, TaskDetail, TaskReport } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
+/** A task as people read it: its title once it has one, else your words, on one line of at most `max` characters. */
+export declare function taskLabel(t: Pick<Task, 'title' | 'text'>, max?: number): string;
+/**
+ * One task as `shard board` lists it: id, state (with why it waits to start: "queued (Claude usage resets 15:00)"),
+ * title or words (a follow-up ↳, a suggestion marked), project.
+ */
+export declare function taskLine(t: Task): string;
+/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+export declare function needsLine(n: NeedsYouItem): string;
+/** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
+export declare function reportLine(r: TaskReport): string;
+/** The board as text: Needs you first (oldest first), then Now, Next and Later in their order. */
+export declare function boardText(b: Pick<Board, 'tasks' | 'needs_you'>): string;
+/** The approval policy on one line: the default, each project's own mode, the number of rules. */
+export declare function policyLine(p: ApprovalPolicy): string;
+/** One always-allow rule: id, tool, the pattern it allows, its project. */
+export declare function ruleLine(r: ApprovalRule): string;
+/** `shard approvals`: the default mode, each project's own mode, then each rule. */
+export declare function policyText(p: ApprovalPolicy): string;
+/**
+ * `shard board --follow`: the lines of each feed answer. A changed task is its board line plus its bucket (deleted,
+ * cleared once gone); a sealed report its report line; an item that started waiting on you its needs line, one that
+ * stopped `<id>\tresolved`; a policy change one line. After a reset the whole board is printed again.
+ */
+export declare class BoardFollower {
+    #private;
+    constructor(board: Pick<Board, 'needs_you'>);
+    next(u: BoardUpdate): string;
+}
+/** A feed answer as `board --follow --json` prints it: the API's fields (with `board` after a reset). */
+export declare function feedJson(u: BoardUpdate): Record<string, unknown>;
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+export declare function taskDetailText(d: TaskDetail): string;
+/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+export declare function itemKind(id: string): NeedsYouItem['kind'] | undefined;
+export interface AnswerInput {
+    word?: string | undefined;
+    text?: string | undefined;
+    picks: readonly string[];
+    keep: readonly string[];
+    everywhere: boolean;
+}
+/** Whether the answer needs the item itself: the questions of a permission request, every task of a prune prompt. */
+export declare const answerNeedsItem: (id: string, a: AnswerInput) => boolean;
+/**
+ * The API answer for item `id` from the command's words and options, checked before anything is sent: each kind takes
+ * its own (needs-you.ts). `item` is the waiting item when answerNeedsItem says it is needed; without it such an answer
+ * is only checked (its `answers` or `keep` come back empty).
+ */
+export declare function needsAnswer(id: string, a: AnswerInput, item?: NeedsYouItem): NeedsYouAnswer;
+/** What an answer did, in one line. */
+export declare function answeredText(r: NeedsYouAnswered, a: NeedsYouAnswer): string;
+export declare const BOARD_HANDLERS: Record<string, Handler>;

package/dist/board-commands.js

@@ -0,0 +1,395 @@
+import { out, principal, str, strs } from "./commands.js";
+import { detailLine, pickAnswers } from "./conversation-commands.js";
+import { NotFoundError, UsageError } from "./errors.js";
+import { time } from "./format.js";
+import { progress } from "./progress.js";
+const BUCKETS = ['now', 'next', 'later'];
+const BUCKET_TITLES = { now: 'Now', next: 'Next', later: 'Later' };
+const MODES = ['ask', 'routine', 'trusted'];
+/** The board's client: the project API key's. */
+const boardClient = (ctx) => ctx.cloud();
+const oneLine = (s, max) => {
+    const line = s.replace(/\s+/g, ' ').trim();
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+};
+/** A task as people read it: its title once it has one, else your words, on one line of at most `max` characters. */
+export function taskLabel(t, max = 80) {
+    return oneLine(t.title?.trim() || t.text, max);
+}
+/**
+ * One task as `shard board` lists it: id, state (with why it waits to start: "queued (Claude usage resets 15:00)"),
+ * title or words (a follow-up ↳, a suggestion marked), project.
+ */
+export function taskLine(t) {
+    const state = `${t.state}${t.waiting?.message.trim() ? ` (${oneLine(t.waiting.message, 60)})` : ''}`;
+    const label = `${t.parent_task_id ? '↳ ' : ''}${taskLabel(t)}${t.suggested ? ' (suggested)' : ''}`;
+    return `${t.id}\t${state}\t${label}\t${t.project_id}${t.home ? ' (home)' : ''}`;
+}
+/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+export function needsLine(n) {
+    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : '';
+    return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
+}
+/** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
+export function reportLine(r) {
+    const labels = r.evidence.map((e) => e.label).join(', ');
+    return `${r.id}\t${r.milestone}\t${oneLine(r.title, 100)}${labels ? `\t${labels}` : ''}`;
+}
+/** The board as text: Needs you first (oldest first), then Now, Next and Later in their order. */
+export function boardText(b) {
+    const parts = [];
+    if (b.needs_you.length)
+        parts.push(['Needs you', ...b.needs_you.map(needsLine)].join('\n'));
+    for (const bucket of BUCKETS) {
+        const tasks = b.tasks.filter((t) => t.bucket === bucket && !t.deleted_at && !t.cleared_at).sort((x, y) => x.position - y.position);
+        if (tasks.length)
+            parts.push([BUCKET_TITLES[bucket], ...tasks.map(taskLine)].join('\n'));
+    }
+    return parts.length ? `${parts.join('\n\n')}\n` : 'Nothing on the board yet: shard task add <words> adds a task.\n';
+}
+/** The approval policy on one line: the default, each project's own mode, the number of rules. */
+export function policyLine(p) {
+    const projects = Object.entries(p.projects).map(([id, mode]) => `; ${id}: ${mode}`).join('');
+    return `${p.default}${projects}${p.rules.length ? `; ${p.rules.length} rule${p.rules.length === 1 ? '' : 's'}` : ''}`;
+}
+/** One always-allow rule: id, tool, the pattern it allows, its project. */
+export function ruleLine(r) {
+    return `${r.id}\t${r.tool}\t${r.pattern || '(every use)'}\t${r.project_id ?? 'every project'}`;
+}
+/** `shard approvals`: the default mode, each project's own mode, then each rule. */
+export function policyText(p) {
+    return [`Default: ${p.default}`, ...Object.entries(p.projects).map(([id, mode]) => `Project ${id}: ${mode}`), ...p.rules.map(ruleLine)].join('\n') + '\n';
+}
+/**
+ * `shard board --follow`: the lines of each feed answer. A changed task is its board line plus its bucket (deleted,
+ * cleared once gone); a sealed report its report line; an item that started waiting on you its needs line, one that
+ * stopped `<id>\tresolved`; a policy change one line. After a reset the whole board is printed again.
+ */
+export class BoardFollower {
+    #waiting;
+    constructor(board) {
+        this.#waiting = new Set(board.needs_you.map((n) => n.id));
+    }
+    next(u) {
+        if (u.reset) {
+            this.#waiting = new Set(u.board.needs_you.map((n) => n.id));
+            return `\n${boardText(u.board)}`;
+        }
+        const lines = [];
+        if (u.needs_you) {
+            const now = new Set(u.needs_you.map((n) => n.id));
+            for (const n of u.needs_you)
+                if (!this.#waiting.has(n.id))
+                    lines.push(needsLine(n));
+            for (const id of this.#waiting)
+                if (!now.has(id))
+                    lines.push(`${id}\tresolved`);
+            this.#waiting = now;
+        }
+        for (const t of u.tasks)
+            lines.push(`${taskLine(t)}\t${t.deleted_at ? 'deleted' : t.cleared_at ? 'cleared' : t.bucket}`);
+        for (const r of u.reports)
+            lines.push(reportLine(r));
+        if (u.policy)
+            lines.push(`Approvals: ${policyLine(u.policy)}`);
+        return lines.length ? `${lines.join('\n')}\n` : '';
+    }
+}
+/** A feed answer as `board --follow --json` prints it: the API's fields (with `board` after a reset). */
+export function feedJson(u) {
+    const page = { ...u };
+    delete page.nextCursor;
+    delete page.held;
+    return page;
+}
+const evidenceText = (e) => {
+    const behind = e.detail ?? e.path;
+    return behind ? `${e.label} (${detailLine(behind, 60)})` : e.label;
+};
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+export function taskDetailText(d) {
+    const t = d.task;
+    const titled = Boolean(t.title?.trim());
+    const lines = [titled ? oneLine(t.title, 200) : oneLine(t.text.split('\n').find((l) => l.trim()) ?? t.text, 200)];
+    lines.push([`${t.state}${t.waiting?.message.trim() ? ` (${oneLine(t.waiting.message, 120)})` : ''}`, t.bucket, `${t.project_id}${t.home ? ' (home)' : ''}`, ...(t.suggested ? ['suggested'] : []), ...(t.deleted_at ? ['deleted'] : t.cleared_at ? ['cleared'] : [])].join('\t'));
+    // Your words exactly, when the first line does not already show them whole.
+    if (titled || t.text.trim() !== lines[0])
+        lines.push('', t.text);
+    if (t.plan) {
+        lines.push('', `Plan: ${t.plan.summary}`);
+        for (const s of t.plan.steps)
+            lines.push(`  ${s.id}\t${s.state}\t${oneLine(s.text, 100)}${s.evidence.length ? `\t${s.evidence.join(', ')}` : ''}`);
+    }
+    if (t.conversations.length)
+        lines.push('', `Conversations: ${t.conversations.map((c) => `${c.id} (${c.role}${c.step_id ? ` ${c.step_id}` : ''})`).join(', ')}`);
+    if (d.reports.length) {
+        lines.push('', 'Reports');
+        for (const r of d.reports) {
+            lines.push(`${r.id}\t${r.milestone}\t${time(r.sealed_at)}\t${oneLine(r.title, 120)}`);
+            if (r.outcome.trim())
+                lines.push(`  ${oneLine(r.outcome, 200)}`);
+            if (r.options?.length)
+                lines.push(`  Options: ${r.options.join(' / ')}`);
+            if (r.evidence.length)
+                lines.push(`  Evidence: ${r.evidence.map(evidenceText).join('; ')}`);
+            if (r.media.length)
+                lines.push(`  Media: ${r.media.map((m) => `${m.name} (${m.path})`).join(', ')}`);
+            if (r.landed)
+                lines.push(`  Landed: ${r.landed.how} ${r.landed.ref}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** --now, --next or --later (one at most); undefined when none was given. */
+function bucketOf(values) {
+    const chosen = BUCKETS.filter((b) => values[b] === true);
+    if (chosen.length > 1)
+        throw new UsageError('Choose one of --now, --next or --later.');
+    return chosen[0];
+}
+/** --after <task-id> or --first (null: first); undefined when neither was given. */
+function orderOf(values) {
+    const after = str(values.after), first = values.first === true;
+    if (after !== undefined && first)
+        throw new UsageError('Choose --after <task-id> or --first.');
+    return first ? null : after;
+}
+// ---- needs you -------------------------------------------------------------------------------
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', cred: 'credential', land: 'land', prune: 'prune' };
+/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+export function itemKind(id) {
+    return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
+}
+/** The answer words: allow, always and deny (or the API's names), land, keep and discard. */
+const WORDS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny', land: 'land', keep: 'keep', discard: 'discard' };
+/** Whether the answer needs the item itself: the questions of a permission request, every task of a prune prompt. */
+export const answerNeedsItem = (id, a) => a.picks.length > 0 || (itemKind(id) === 'prune' && a.word?.toLowerCase() === 'keep');
+/**
+ * The API answer for item `id` from the command's words and options, checked before anything is sent: each kind takes
+ * its own (needs-you.ts). `item` is the waiting item when answerNeedsItem says it is needed; without it such an answer
+ * is only checked (its `answers` or `keep` come back empty).
+ */
+export function needsAnswer(id, a, item) {
+    const kind = item?.kind ?? itemKind(id);
+    const decision = a.word === undefined ? undefined : WORDS[a.word.toLowerCase().replace(/-/g, '_')];
+    const only = (allowed, message) => {
+        const given = ['text', 'picks', 'keep', 'everywhere'].filter((k) => (k === 'text' ? a.text !== undefined : k === 'everywhere' ? a.everywhere : a[k].length > 0));
+        if (given.some((k) => !allowed.includes(k)))
+            throw new UsageError(message);
+    };
+    switch (kind) {
+        case 'permission': {
+            const message = 'Choose allow, always or deny (an agent’s question takes --pick <option>).';
+            only(['picks', 'everywhere'], message);
+            if (a.picks.length) {
+                if (a.word !== undefined)
+                    throw new UsageError('Answer the question with --pick, or decline it with deny, not both.');
+                if (a.everywhere)
+                    throw new UsageError('--everywhere goes with always.');
+                if (!item)
+                    return { answers: {} };
+                return { answers: pickAnswers({ questions: (item.permission?.questions ?? []) }, a.picks) };
+            }
+            if (decision !== 'allow_once' && decision !== 'allow_always' && decision !== 'deny')
+                throw new UsageError(message);
+            if (a.everywhere && decision !== 'allow_always')
+                throw new UsageError('--everywhere goes with always.');
+            return decision === 'allow_always' ? { decision, scope: a.everywhere ? 'everywhere' : 'project' } : { decision };
+        }
+        case 'question': {
+            const message = 'Answer the question with --text <answer>.';
+            only(['text'], message);
+            if (a.word !== undefined || !a.text?.trim())
+                throw new UsageError(message);
+            return { text: a.text };
+        }
+        case 'credential':
+            only([], 'Provide the value through the credential request, sealed for its computer; deny declines it here.');
+            if (decision !== 'deny')
+                throw new UsageError('Provide the value through the credential request, sealed for its computer; deny declines it here.');
+            return { decision };
+        case 'land':
+            only([], 'Choose land, keep or discard.');
+            if (decision !== 'land' && decision !== 'keep' && decision !== 'discard')
+                throw new UsageError('Choose land, keep or discard.');
+            return { decision };
+        case 'prune': {
+            const message = 'Choose --keep <task-id> for each task to keep, keep for all of them, or discard to clear them.';
+            only(['keep'], message);
+            if (a.keep.length) {
+                if (a.word !== undefined)
+                    throw new UsageError(message);
+                return { keep: [...new Set(a.keep)] };
+            }
+            if (decision === 'discard')
+                return { keep: [] };
+            if (decision === 'keep')
+                return { keep: item?.prune ? [...item.prune.task_ids] : [] };
+            throw new UsageError(message);
+        }
+        default: {
+            // An id of a kind this shard does not know yet: what was given goes to the API, which says what it takes.
+            const answer = {};
+            if (decision)
+                answer.decision = decision;
+            if (a.text !== undefined)
+                answer.text = a.text;
+            if (a.keep.length)
+                answer.keep = [...a.keep];
+            if (a.everywhere)
+                answer.scope = 'everywhere';
+            return answer;
+        }
+    }
+}
+const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied', land: 'Landing', keep: 'Kept', discard: 'Discarded' };
+/** What an answer did, in one line. */
+export function answeredText(r, a) {
+    const item = r.item;
+    if (a.answers)
+        return `Answered: ${Object.values(a.answers).map((v) => (Array.isArray(v) ? v.join(', ') : v)).join('; ')}\n`;
+    if (item.kind === 'prune' && a.keep) {
+        const all = item.prune?.task_ids.length ?? a.keep.length;
+        return a.keep.length === all ? `Kept all ${all} Later tasks.\n` : `Kept ${a.keep.length} of ${all} Later tasks; the rest are cleared.\n`;
+    }
+    if (item.kind === 'question')
+        return `Answered: ${oneLine(item.ask, 100)}\n`;
+    const what = item.kind === 'land' ? item.land?.branch ?? oneLine(item.ask, 100) : oneLine(item.ask, 100).replace(/\?$/, '');
+    return `${ANSWERED[a.decision ?? ''] ?? 'Answered'}: ${what}${r.rule_id ? ` (rule ${r.rule_id})` : ''}\n`;
+}
+// ---- handlers --------------------------------------------------------------------------------
+const projectScope = (values) => (str(values.project) !== undefined ? { projectId: str(values.project) } : {});
+export const BOARD_HANDLERS = {
+    // The board, or with --follow the board and then each change until Ctrl-C (the SDK's watch over the held feed,
+    // from the board's own cursor: nothing between the read and the first wait is missed).
+    async board(ctx, values) {
+        const cloud = boardClient(ctx), scope = projectScope(values);
+        const board = await cloud.board.get({ ...scope, signal: ctx.signal });
+        if (values.follow !== true) {
+            out(ctx, boardText(board), board);
+            return 0;
+        }
+        ctx.io.stdout.write(ctx.json ? `${JSON.stringify(board)}\n` : boardText(board));
+        progress(ctx, 'Following the board. Ctrl-C stops.');
+        const follower = new BoardFollower(board);
+        for await (const u of cloud.board.watch({ ...scope, cursor: board.cursor, signal: ctx.signal })) {
+            ctx.io.stdout.write(ctx.json ? `${JSON.stringify(feedJson(u))}\n` : follower.next(u));
+        }
+        return 0;
+    },
+    async 'task add'(ctx, values, words) {
+        const text = words.join(' ');
+        if (!text.trim())
+            throw new UsageError('missing <words...> for "shard task add"');
+        if (values.next === true && values.later === true)
+            throw new UsageError('Choose --next or --later.');
+        const bucket = values.later === true ? 'later' : values.next === true ? 'next' : undefined;
+        const after = orderOf(values);
+        const task = await boardClient(ctx).tasks.create({ text, ...projectScope(values), ...(values.home === true ? { home: true } : {}), ...(bucket ? { bucket } : {}), ...(after !== undefined ? { after } : {}) }, { signal: ctx.signal });
+        out(ctx, `${task.id}\t${task.bucket}\t${task.state}\n`, { task });
+        return 0;
+    },
+    async 'task show'(ctx, _values, [id]) {
+        const detail = await boardClient(ctx).tasks.get(id, { signal: ctx.signal });
+        out(ctx, taskDetailText(detail), detail);
+        return 0;
+    },
+    async 'task edit'(ctx, values, [id]) {
+        const p = {};
+        const text = str(values.text), title = str(values.title);
+        if (text !== undefined) {
+            if (!text.trim())
+                throw new UsageError('--text needs words.');
+            p.text = text;
+        }
+        if (title !== undefined)
+            p.title = title.trim() ? title : null;
+        const bucket = bucketOf(values), after = orderOf(values);
+        if (bucket)
+            p.bucket = bucket;
+        if (after !== undefined)
+            p.after = after;
+        if (values.keep === true)
+            p.suggested = false;
+        if (typeof values.clear === 'boolean')
+            p.cleared = values.clear;
+        if (Object.keys(p).length === 0)
+            throw new UsageError('Nothing to change: give --text, --title, --now, --next, --later, --after, --first, --keep or --clear.');
+        const task = await boardClient(ctx).tasks.update(id, p, { signal: ctx.signal });
+        out(ctx, `${taskLine(task)}\n`, { task });
+        return 0;
+    },
+    async 'task rm'(ctx, _values, [id]) {
+        const task = await boardClient(ctx).tasks.delete(id, { signal: ctx.signal });
+        out(ctx, `Deleted: ${taskLabel(task)}\n`, { task });
+        return 0;
+    },
+    async 'task steer'(ctx, _values, [id, ...words]) {
+        const text = words.join(' ');
+        if (!text.trim())
+            throw new UsageError('missing <words...> for "shard task steer"');
+        const task = await boardClient(ctx).tasks.steer(id, text, { signal: ctx.signal });
+        out(ctx, `Steered: ${taskLabel(task)}\n`, { task });
+        return 0;
+    },
+    async 'task clear-done'(ctx, values) {
+        const cleared = await boardClient(ctx).tasks.clearDone(projectScope(values), { signal: ctx.signal });
+        out(ctx, cleared.length ? `Cleared ${cleared.length} finished task${cleared.length === 1 ? '' : 's'}.\n` : 'No finished tasks to clear.\n', { cleared });
+        return 0;
+    },
+    async 'needs-you'(ctx, values) {
+        const data = await boardClient(ctx).needsYou.list({ ...projectScope(values), signal: ctx.signal });
+        out(ctx, data.length ? `${data.map(needsLine).join('\n')}\n` : 'Nothing waits on you.\n', { data });
+        return 0;
+    },
+    async 'needs-you answer'(ctx, values, [id, word]) {
+        const input = { word, text: str(values.text), picks: strs(values.pick), keep: strs(values.keep), everywhere: values.everywhere === true };
+        const cloud = boardClient(ctx);
+        // Checked first, so a wrong combination is a usage error before any request.
+        let answer = needsAnswer(id, input);
+        if (answerNeedsItem(id, input)) {
+            const item = (await cloud.needsYou.list({ signal: ctx.signal })).find((n) => n.id === id);
+            if (!item)
+                throw new NotFoundError('Nothing waits on you there any more.', 'shard needs-you lists what does', { reason: 'needs_you_not_found' });
+            answer = needsAnswer(id, input, item);
+        }
+        const r = await cloud.needsYou.answer(id, answer, { signal: ctx.signal });
+        out(ctx, answeredText(r, answer), r);
+        return 0;
+    },
+    async approvals(ctx) {
+        const policy = await boardClient(ctx).approvals.getPolicy({ signal: ctx.signal });
+        out(ctx, policyText(policy), policy);
+        return 0;
+    },
+    async 'approvals set'(ctx, values, [word]) {
+        const w = word.toLowerCase();
+        if (w !== 'default' && !MODES.includes(w))
+            throw new UsageError('Choose ask, routine or trusted (default puts the project back on the default mode).');
+        const mode = w === 'default' ? null : w, project = str(values.project);
+        if (values.default === true && project !== undefined)
+            throw new UsageError('Choose --project <id> or --default.');
+        if (values.default === true && mode === null)
+            throw new UsageError('--default takes ask, routine or trusted.');
+        const cloud = boardClient(ctx);
+        const params = values.default === true ? { default: mode } : { projects: { [project ?? (await principal(ctx)).project_id]: mode } };
+        const policy = await cloud.approvals.setPolicy(params, { signal: ctx.signal });
+        out(ctx, policyText(policy), policy);
+        return 0;
+    },
+    async 'approvals allow'(ctx, values, [tool, ...pattern]) {
+        const project = str(values.project), everywhere = values.everywhere === true;
+        if (project !== undefined && everywhere)
+            throw new UsageError('Choose --project <id> or --everywhere.');
+        if (!tool.trim())
+            throw new UsageError('Name the tool, such as Bash, WebFetch or Edit.');
+        const rule = await boardClient(ctx).approvals.addRule({ tool: tool, pattern: pattern.join(' '), ...(everywhere ? { projectId: null } : project !== undefined ? { projectId: project } : {}) }, { signal: ctx.signal });
+        out(ctx, `${ruleLine(rule)}\n`, rule);
+        return 0;
+    },
+    async 'approvals remove'(ctx, _values, [id]) {
+        const policy = await boardClient(ctx).approvals.removeRule(id, { signal: ctx.signal });
+        out(ctx, `Removed ${id}.\n`, policy);
+        return 0;
+    },
+};