@shardflux/cli 0.24.1 → 0.28.0

package/dist/orchestrator-args.js

@@ -0,0 +1,64 @@
+const ORG = {
+    org: { type: 'string', value: '<id|slug>', description: 'Organization whose orchestrator it is (default: the saved one, shard orgs use, else your only organization). Slugs need your signed-in session.' },
+};
+const WHO = 'Your orchestrator is yours: one agent on its own Shardflux computer, the same on every device. Uses your signed-in session, or SHARDFLUX_API_KEY when it is set (a project key you created: a new orchestrator is filed under its project).';
+export const ORCHESTRATOR_COMMANDS = [
+    {
+        path: ['orchestrator', 'say'],
+        summary: 'Say something to your orchestrator; one of its threads hears each input at once (0.27.0+)',
+        positionals: [{ name: 'words', variadic: true, words: true, required: true }],
+        options: {
+            task: { type: 'string', value: '<task-id>', description: 'Point at a task (task_…).' },
+            report: { type: 'string', value: '<report-id>', description: 'Point at a report (rep_…).' },
+            'needs-you': { type: 'string', value: '<item-id>', description: 'Point at something that waits on you (perm_…, oq_…).' },
+            input: { type: 'string', value: '<input-id>', description: 'Point at an earlier input (in_…).' },
+            conversation: { type: 'string', value: '<conversation-id>', description: 'Point at a conversation (conv_…).' },
+            wait: { type: 'boolean', description: 'Follow it until it is done, merged, failed or waiting, then print what it became.' },
+            timeout: { type: 'string', value: '<duration>', description: 'With --wait: stop following after this long (default 10m). The input goes on.' },
+            ...ORG,
+        },
+        description: [
+            'Your exact words go to your orchestrator, with the row you point at. It answers at once: the input id and its state (queued, with its place in line; every input waits its turn in order). One of your orchestrator’s threads hears each input at once, all in parallel: a follow-up reaches the thread of the request it is about (the input reads merged), the row you point at reaches the thread of that row’s input, and anything new gets a thread of its own, which answers it, puts tasks on the board (shard board) or asks you something (shard needs-you, oq_…).',
+            '--wait follows it and prints its curated result: the answer’s headline and its points under their group headings (with when each happened) or its facts, a media line per file it shows (an image with its size in pixels), with their sources and follow-ups, the tasks it created, the line it waits on (a question names the shard needs-you answer command), or the input it was added to. Exit 6 when it failed (shard orchestrator retry sends it again), 5 when --timeout passed first.',
+            WHO,
+            'With --json: {input}, as it was stored, or with --wait as it ended.',
+        ].join('\n\n'),
+        examples: ['shard orchestrator say Lets check on our language model training progress --wait', 'shard orchestrator say --task task_h7g4d7tqyv2pz3a2npyo4rpgzq use postgres instead', 'shard orchestrator say "what is blocking pricing?" --wait --json'],
+    },
+    {
+        path: ['orchestrator', 'list'],
+        summary: 'List what you said to your orchestrator and what each became, newest first (0.27.0+)',
+        positionals: [],
+        options: { all: { type: 'boolean', description: 'Also list the inputs you dismissed.' }, ...ORG },
+        description: [
+            'One line per input: its id, its state (queued with its place in line, working, waiting with what it waits on, done, merged, failed), your words, and what it became (the answer’s headline, its tasks, the input it was added to, or why it failed). Inputs still in flight are always listed.',
+            WHO,
+            'With --json: {inputs, cursor}, every input as the API answered it.',
+        ].join('\n\n'),
+        examples: ['shard orchestrator list', 'shard orchestrator list --json | jq -r \'.inputs[] | select(.state=="done") | .answer.headline\''],
+    },
+    {
+        path: ['orchestrator', 'retry'],
+        summary: 'Send a failed input to your orchestrator again (0.27.0+)',
+        positionals: [{ name: 'input-id', required: true }],
+        options: ORG,
+        description: 'It goes back in line and a new thread takes it. Prints its id and state. Only a failed input is sent again.',
+    },
+    {
+        path: ['orchestrator', 'dismiss'],
+        summary: 'Take an input out of your orchestrator’s list on every device (0.27.0+)',
+        positionals: [{ name: 'input-id', required: true }],
+        options: ORG,
+        description: 'What it created stays on the board. shard orchestrator list --all still shows it; shard orchestrator restore brings it back.',
+    },
+    {
+        path: ['orchestrator', 'restore'],
+        summary: 'Bring a dismissed input back into your orchestrator’s list on every device (0.28.0+)',
+        positionals: [{ name: 'input-id', required: true }],
+        options: ORG,
+        description: [
+            'Undoes shard orchestrator dismiss: the input is listed again with what it became. Restoring an input that is not dismissed changes nothing. Questions the dismiss closed stay closed.',
+            'With --json: {input}.',
+        ].join('\n\n'),
+    },
+];

package/dist/orchestrator-commands.d.ts

@@ -0,0 +1,43 @@
+import type { OrchestratorInput, OrchestratorSelection } from '@shardflux/sdk';
+import type { Values } from './args.js';
+import type { Handler } from './commands.js';
+/** --wait's default: how long `say --wait` follows an input before it stops (the input goes on). */
+export declare const SAY_WAIT_MS: number;
+/** The row the person points at, from --task, --report, --needs-you, --input and --conversation; undefined for none. */
+export declare function selectionOf(values: Values): OrchestratorSelection | undefined;
+/** An input's state with what explains it: "queued (2 in line)", "waiting (Waiting for your computer: list ~/code)". */
+export declare function stateLabel(i: OrchestratorInput): string;
+/** What an input became, in a few words: the answer's headline, its tasks, the input it went to, or why it failed. */
+export declare function becameText(i: OrchestratorInput): string;
+/** One input as `shard orchestrator list` prints it: id, state, your words, what it became. */
+export declare function inputLine(i: OrchestratorInput): string;
+/**
+ * When an answer's point happened, short and in this computer's local time: "14:02" today, "Oct 16 14:02" this year,
+ * else "2025-10-16 14:02". A time without an offset is the person's local time and prints as written.
+ */
+export declare function shortTime(at: string, now?: Date): string;
+/** An answer's body: its points under their group headings when the agent wrote points (0.27.0+), else its facts. */
+export declare function answerLines(answer: NonNullable<OrchestratorInput['answer']>, now?: Date): string[];
+/** One file an answer shows (0.27.0+): `  media: loss-curve.png (image, 1200×800, 84.0 KB)`, the size in pixels once known. */
+export declare function mediaLine(m: NonNullable<NonNullable<OrchestratorInput['answer']>['media']>[number]): string;
+/**
+ * What `say --wait` prints once an input is done, merged, failed or waiting: its curated result.
+ *
+ *   Training is 73% done, on pace to finish at 16:40
+ *     Moved
+ *     - Loss is down to 1.84: from 2.31 at step 5,000 (14:02)
+ *     - Checkpoint saved: at step 7,000
+ *     Still open
+ *     - Eval has not run: it starts after the last checkpoint
+ *     media: loss-curve.png (image, 1200×800, 84.0 KB)
+ *     Sources: train.log (~/code/lm-train/train.log), wandb.ai (https://wandb.ai/acme/lm)
+ *     Follow-ups: Check again in an hour
+ *   Tasks: task_… (shard task show <id>)
+ *
+ * An answer written as facts prints them as `  - <fact>` lines instead of the points. Each file the answer shows prints
+ * one media line after them (shard drive get <path> --sha256 <sha256> reads it; --json has both).
+ */
+export declare function resultText(i: OrchestratorInput, now?: Date): string;
+/** Where `say --wait` stops following: nothing more happens to the input, or it waits on you or your computer. */
+export declare const stopsWaiting: (i: OrchestratorInput) => boolean;
+export declare const ORCHESTRATOR_HANDLERS: Record<string, Handler>;

package/dist/orchestrator-commands.js

@@ -0,0 +1,262 @@
+/**
+ * Your orchestrator (0.27.0+, SDK 0.29.0): `shard orchestrator say` (with --wait), `list`, `retry` and `dismiss`, and
+ * `restore` (0.28.0+, SDK 0.30.0), through @shardflux/sdk's `orchestrator` namespace. The command table is orchestrator-args.ts.
+ *
+ * The signed-in session reaches the person's orchestrator; SHARDFLUX_API_KEY in the environment (or a saved key without
+ * a session) reaches the orchestrator of the member who created that key (person-scope.ts). Text output is one line
+ * per input, tab-separated, id first; --json prints the API's objects.
+ */
+import { inputSettled, ORCHESTRATOR_TEXT_MAX } from '@shardflux/sdk';
+import { parseDuration } from "./args.js";
+import { out, str } from "./commands.js";
+import { EXIT, UsageError } from "./errors.js";
+import { humanBytes } from "./files-mirror.js";
+import { inScope } from "./person-scope.js";
+import { progress } from "./progress.js";
+/** --wait's default: how long `say --wait` follows an input before it stops (the input goes on). */
+export const SAY_WAIT_MS = 10 * 60_000;
+const oneLine = (s, max) => {
+    const line = s.replace(/\s+/g, ' ').trim();
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+};
+/** The selection flags and the API's id shape for each. */
+const POINTERS = [
+    ['task', 'task_id', /^task_[a-z2-7]{26}$/, 'task_…'],
+    ['report', 'report_id', /^rep_[a-z2-7]{26}$/, 'rep_…'],
+    ['needs-you', 'needs_you_id', /^[a-z]{2,6}_[A-Za-z0-9_-]{1,80}$/, 'perm_…, oq_…'],
+    ['input', 'input_id', /^in_[a-z2-7]{26}$/, 'in_…'],
+    ['conversation', 'conversation_id', /^conv_[a-z2-7]{26}$/, 'conv_…'],
+];
+/** The row the person points at, from --task, --report, --needs-you, --input and --conversation; undefined for none. */
+export function selectionOf(values) {
+    const selection = {};
+    for (const [flag, field, pattern, example] of POINTERS) {
+        const v = str(values[flag]);
+        if (v === undefined)
+            continue;
+        if (!pattern.test(v))
+            throw new UsageError(`--${flag} must be an id (${example})`);
+        selection[field] = v;
+    }
+    return Object.keys(selection).length ? selection : undefined;
+}
+/** An input's state with what explains it: "queued (2 in line)", "waiting (Waiting for your computer: list ~/code)". */
+export function stateLabel(i) {
+    if (i.state === 'queued')
+        return i.waiting ? `queued (${oneLine(i.waiting.message, 80)})` : i.queue_position ? `queued (${i.queue_position} in line)` : 'queued';
+    if (i.state === 'waiting' && i.waiting)
+        return `waiting (${oneLine(i.waiting.message, 80)})`;
+    return i.state;
+}
+/** What an input became, in a few words: the answer's headline, its tasks, the input it went to, or why it failed. */
+export function becameText(i) {
+    if (i.state === 'merged' && i.merged_into)
+        return `added to ${i.merged_into}`;
+    if (i.state === 'failed' && i.error)
+        return oneLine(i.error.message, 100);
+    const parts = [];
+    if (i.answer)
+        parts.push(oneLine(i.answer.headline, 100));
+    if (i.task_ids.length)
+        parts.push(`${i.task_ids.length} task${i.task_ids.length === 1 ? '' : 's'}: ${i.task_ids.join(', ')}`);
+    return parts.join('; ');
+}
+/** One input as `shard orchestrator list` prints it: id, state, your words, what it became. */
+export function inputLine(i) {
+    const became = becameText(i);
+    return `${i.id}\t${stateLabel(i)}\t${oneLine(i.text, 60)}${became ? `\t${became}` : ''}`;
+}
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const two = (n) => String(n).padStart(2, '0');
+/**
+ * When an answer's point happened, short and in this computer's local time: "14:02" today, "Oct 16 14:02" this year,
+ * else "2025-10-16 14:02". A time without an offset is the person's local time and prints as written.
+ */
+export function shortTime(at, now = new Date()) {
+    const d = new Date(at);
+    if (!Number.isFinite(d.getTime()))
+        return at;
+    const clock = `${two(d.getHours())}:${two(d.getMinutes())}`;
+    if (d.getFullYear() !== now.getFullYear())
+        return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${clock}`;
+    if (d.getMonth() !== now.getMonth() || d.getDate() !== now.getDate())
+        return `${MONTHS[d.getMonth()]} ${d.getDate()} ${clock}`;
+    return clock;
+}
+/** An answer's body: its points under their group headings when the agent wrote points (0.27.0+), else its facts. */
+export function answerLines(answer, now = new Date()) {
+    if (!answer.points?.length)
+        return answer.facts.map((f) => `  - ${f}`);
+    const lines = [];
+    let group;
+    for (const p of answer.points) {
+        if (p.group !== group && p.group)
+            lines.push(`  ${p.group}`);
+        group = p.group;
+        // A point the agent wrote without a lead is its words alone; every word prints, however long.
+        const words = p.lead ? `${p.lead}${p.detail ? `: ${p.detail}` : ''}` : p.detail ?? '';
+        lines.push(`  - ${words}${p.at ? ` (${shortTime(p.at, now)})` : ''}`);
+    }
+    return lines;
+}
+/** One file an answer shows (0.27.0+): `  media: loss-curve.png (image, 1200×800, 84.0 KB)`, the size in pixels once known. */
+export function mediaLine(m) {
+    return `  media: ${m.name} (${[m.kind, ...(m.width && m.height ? [`${m.width}×${m.height}`] : []), humanBytes(m.size)].join(', ')})`;
+}
+/**
+ * What `say --wait` prints once an input is done, merged, failed or waiting: its curated result.
+ *
+ *   Training is 73% done, on pace to finish at 16:40
+ *     Moved
+ *     - Loss is down to 1.84: from 2.31 at step 5,000 (14:02)
+ *     - Checkpoint saved: at step 7,000
+ *     Still open
+ *     - Eval has not run: it starts after the last checkpoint
+ *     media: loss-curve.png (image, 1200×800, 84.0 KB)
+ *     Sources: train.log (~/code/lm-train/train.log), wandb.ai (https://wandb.ai/acme/lm)
+ *     Follow-ups: Check again in an hour
+ *   Tasks: task_… (shard task show <id>)
+ *
+ * An answer written as facts prints them as `  - <fact>` lines instead of the points. Each file the answer shows prints
+ * one media line after them (shard drive get <path> --sha256 <sha256> reads it; --json has both).
+ */
+export function resultText(i, now = new Date()) {
+    const lines = [];
+    if (i.answer) {
+        lines.push(i.answer.headline);
+        lines.push(...answerLines(i.answer, now));
+        for (const m of i.answer.media ?? [])
+            lines.push(mediaLine(m));
+        if (i.answer.sources.length)
+            lines.push(`  Sources: ${i.answer.sources.map((s) => (s.label === s.ref ? s.label : `${s.label} (${s.ref})`)).join(', ')}`);
+        if (i.answer.actions.length)
+            lines.push(`  Follow-ups: ${i.answer.actions.map((a) => a.label).join(' / ')}`);
+    }
+    if (i.task_ids.length)
+        lines.push(`Tasks: ${i.task_ids.join(', ')} (shard task show <id>)`);
+    if (i.state === 'merged')
+        lines.push(`Added to ${i.merged_into}: its thread has your words.`);
+    if (i.state === 'failed') {
+        lines.push(`Failed: ${i.error?.message ?? 'its thread stopped.'}`);
+        if (i.error?.retryable !== false)
+            lines.push(`Send it again: shard orchestrator retry ${i.id}`);
+    }
+    if (i.state === 'waiting' && i.waiting) {
+        lines.push(i.waiting.message);
+        const asked = i.question_ids.at(-1);
+        if (i.waiting.for === 'you' && asked)
+            lines.push(`Answer it: shard needs-you answer ${asked} --text <answer>`);
+        if (i.waiting.for === 'computer')
+            lines.push('It runs when your computer is back (the Shardflux app open).');
+    }
+    if (!lines.length)
+        lines.push(i.state === 'done' ? 'Done.' : stateLabel(i));
+    return `${lines.join('\n')}\n`;
+}
+/** Where `say --wait` stops following: nothing more happens to the input, or it waits on you or your computer. */
+export const stopsWaiting = (i) => inputSettled(i) || i.state === 'waiting';
+const orgOnly = (scope) => (scope.organizationId ? { organizationId: scope.organizationId } : {});
+/**
+ * Follows input `id` until it stops waiting (stopsWaiting), `timeoutMs` passes, or Ctrl-C: a plain read, then the SDK's
+ * watch from its cursor, so no change between them is missed. Progress lines (its place in line, working) go to stderr.
+ */
+async function follow(ctx, client, scope, first, timeoutMs) {
+    let last = first, shown = '';
+    const show = (i) => {
+        const line = i.state === 'queued' ? `Queued${i.queue_position ? `: ${i.queue_position} in line` : ''}${i.waiting ? ` (${i.waiting.message})` : ''}` : i.state === 'working' ? 'Working' : '';
+        if (line && line !== shown)
+            progress(ctx, line);
+        shown = line;
+    };
+    const page = await client.orchestrator.inputs({ ...orgOnly(scope), signal: ctx.signal });
+    last = page.inputs?.find((i) => i.id === first.id) ?? last;
+    if (stopsWaiting(last))
+        return { input: last, timedOut: false };
+    show(last);
+    const abort = new AbortController();
+    const stop = () => abort.abort();
+    ctx.signal.addEventListener('abort', stop, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; abort.abort(); }, timeoutMs);
+    try {
+        for await (const u of client.orchestrator.watch({ ...orgOnly(scope), cursor: page.cursor, signal: abort.signal })) {
+            last = u.inputs.find((i) => i.id === first.id) ?? last;
+            if (stopsWaiting(last))
+                return { input: last, timedOut: false };
+            show(last);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.signal.removeEventListener('abort', stop);
+    }
+    return { input: last, timedOut };
+}
+const idOf = (id) => {
+    if (!id || !/^in_[a-z2-7]{26}$/.test(id))
+        throw new UsageError('Name the input by its id (in_…): shard orchestrator list shows them.');
+    return id;
+};
+export const ORCHESTRATOR_HANDLERS = {
+    async 'orchestrator say'(ctx, values, words) {
+        const text = words.join(' ');
+        if (!text.trim())
+            throw new UsageError('missing <words...> for "shard orchestrator say"');
+        if (text.length > ORCHESTRATOR_TEXT_MAX)
+            throw new UsageError(`your words are ${text.length} characters; one input takes up to ${ORCHESTRATOR_TEXT_MAX}`);
+        const selection = selectionOf(values);
+        const wait = values.wait === true;
+        const timeoutMs = str(values.timeout) === undefined ? SAY_WAIT_MS : parseDuration(str(values.timeout), 'timeout');
+        if (!wait && str(values.timeout) !== undefined)
+            throw new UsageError('--timeout goes with --wait.');
+        return inScope(ctx, values, async (client, scope) => {
+            const input = await client.orchestrator.say(text, { ...orgOnly(scope), ...(selection ? { selection } : {}), signal: ctx.signal });
+            if (!wait) {
+                out(ctx, `${input.id}\t${stateLabel(input)}\n`, { input });
+                return EXIT.ok;
+            }
+            progress(ctx, `Sent: ${input.id}`);
+            let followed;
+            try {
+                followed = await follow(ctx, client, scope, input, timeoutMs);
+            }
+            catch (err) {
+                if (ctx.signal.aborted)
+                    return EXIT.interrupted;
+                throw err;
+            }
+            if (ctx.signal.aborted && !followed.timedOut && !stopsWaiting(followed.input))
+                return EXIT.interrupted;
+            const end = followed.input;
+            if (followed.timedOut) {
+                out(ctx, `${end.id}\t${stateLabel(end)}\n`, { input: end });
+                ctx.io.stderr.write(`Still ${end.state} after ${Math.round(timeoutMs / 1000)} s; it goes on: shard orchestrator list shows it.\n`);
+                return EXIT.timeout;
+            }
+            out(ctx, resultText(end), { input: end });
+            return end.state === 'failed' ? EXIT.operationFailed : EXIT.ok;
+        });
+    },
+    async 'orchestrator list'(ctx, values) {
+        const page = await inScope(ctx, values, (client, scope) => client.orchestrator.inputs({ ...orgOnly(scope), signal: ctx.signal }));
+        const shown = (page.inputs ?? []).filter((i) => values.all === true || !i.dismissed_at);
+        const human = shown.length ? `${shown.map(inputLine).join('\n')}\n` : 'Nothing to show yet: shard orchestrator say <words> sends your orchestrator something.\n';
+        out(ctx, human, { inputs: page.inputs ?? [], cursor: page.cursor });
+        return EXIT.ok;
+    },
+    async 'orchestrator retry'(ctx, values, [id]) {
+        const input = await inScope(ctx, values, (client, scope) => client.orchestrator.retry(idOf(id), { ...orgOnly(scope), signal: ctx.signal }));
+        out(ctx, `${input.id}\t${stateLabel(input)}\n`, { input });
+        return EXIT.ok;
+    },
+    async 'orchestrator dismiss'(ctx, values, [id]) {
+        const input = await inScope(ctx, values, (client, scope) => client.orchestrator.dismiss(idOf(id), { ...orgOnly(scope), signal: ctx.signal }));
+        out(ctx, `Dismissed: ${oneLine(input.text, 80)}\n`, { input });
+        return EXIT.ok;
+    },
+    async 'orchestrator restore'(ctx, values, [id]) {
+        const input = await inScope(ctx, values, (client, scope) => client.orchestrator.restore(idOf(id), { ...orgOnly(scope), signal: ctx.signal }));
+        out(ctx, `Restored: ${oneLine(input.text, 80)}\n`, { input });
+        return EXIT.ok;
+    },
+};

package/dist/person-scope.d.ts

@@ -0,0 +1,20 @@
+import type { Shardflux, ShardfluxAccount } from '@shardflux/sdk';
+import type { Values } from './args.js';
+import type { Ctx } from './commands.js';
+export interface BoardClient {
+    client: Shardflux | ShardfluxAccount;
+    /** The signed-in session: the organization's whole board. */
+    session: boolean;
+}
+/** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
+export declare function boardClient(ctx: Ctx): BoardClient;
+export interface Scope {
+    organizationId?: string;
+    projectId?: string;
+}
+/**
+ * Runs `call` in the board's scope. With the session and no --org/--project: the saved default organization, else the
+ * only one; when the person is in several and none is saved (422), or the saved one is gone (404), the error lists
+ * theirs and names the fix (resolveOrg), and an organization that resolves is used.
+ */
+export declare function inScope<T>(ctx: Ctx, values: Values, call: (client: Shardflux | ShardfluxAccount, scope: Scope) => Promise<T>): Promise<T>;

package/dist/person-scope.js

@@ -0,0 +1,61 @@
+/**
+ * Which client and scope a person's command uses (0.25.0+): the signed-in session reads every project of an
+ * organization; SHARDFLUX_API_KEY in the environment (or a saved key without a session) reads that key's project. Used
+ * by `shard orchestrator`, `shard transcribe`, `shard route` and `shard ask`.
+ */
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { UUID } from "./args.js";
+import { findOrg, resolveOrg, resolveProject } from "./account-scope.js";
+import { str } from "./commands.js";
+import { UsageError } from "./errors.js";
+/** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
+export function boardClient(ctx) {
+    if (!ctx.io.env.SHARDFLUX_API_KEY?.trim() && ctx.sessionSource() !== null)
+        return { client: ctx.account(), session: true };
+    return { client: ctx.cloud(), session: false };
+}
+/** --org / --project as ids (slugs resolved with the session); with neither, the saved default organization. */
+async function scopeOf(ctx, values, b) {
+    const org = str(values.org), project = str(values.project);
+    if (!b.session) {
+        for (const [flag, v] of [['--org', org], ['--project', project]]) {
+            if (v !== undefined && !UUID.test(v))
+                throw new UsageError(`${flag} must be an id (UUID) with a project API key`, 'or sign in (shard auth login) to name it by slug');
+        }
+        return { scope: { ...(org === undefined ? {} : { organizationId: org }), ...(project === undefined ? {} : { projectId: project }) }, defaulted: false };
+    }
+    const account = b.client;
+    const scope = {};
+    if (org !== undefined)
+        scope.organizationId = UUID.test(org) ? org : (await findOrg(account, org)).id;
+    if (project !== undefined)
+        scope.projectId = UUID.test(project) ? project : (await resolveProject(ctx, account, values)).id;
+    if (org !== undefined || project !== undefined)
+        return { scope, defaulted: false };
+    const saved = ctx.store.profile(ctx.apiUrl).organization_id;
+    return { scope: saved ? { organizationId: saved } : {}, defaulted: true };
+}
+/**
+ * Runs `call` in the board's scope. With the session and no --org/--project: the saved default organization, else the
+ * only one; when the person is in several and none is saved (422), or the saved one is gone (404), the error lists
+ * theirs and names the fix (resolveOrg), and an organization that resolves is used.
+ */
+export async function inScope(ctx, values, call) {
+    const b = boardClient(ctx);
+    const { scope, defaulted } = await scopeOf(ctx, values, b);
+    try {
+        return await call(b.client, scope);
+    }
+    catch (err) {
+        if (!b.session || !defaulted || !(err instanceof ShardfluxApiError))
+            throw err;
+        const several = err.status === 422 && scope.organizationId === undefined && /organization/i.test(err.message);
+        const gone = err.status === 404 && scope.organizationId !== undefined;
+        if (!several && !gone)
+            throw err;
+        const org = await resolveOrg(ctx, b.client, {});
+        if (org.id === scope.organizationId)
+            throw err;
+        return call(b.client, { organizationId: org.id });
+    }
+}

package/dist/project-hub-seed.d.ts

@@ -0,0 +1,20 @@
+import type { Ctx } from './commands.js';
+import type { TwinCell } from './worktree-twin.js';
+import { projectHubCell } from './worktree-twin-engine.js';
+/** Where work on a linked folder starts: this commit (in the project hub), on the folder's branch. */
+export interface HubSeed {
+    commit: string;
+    branch: string | null;
+}
+/** Copies `commit` and its history from `folder` into the hub, kept under `ref`, unless the hub holds it already. */
+export declare function sendToHub(cell: TwinCell, folder: string, commit: string, ref: string, opts?: {
+    hub?: string;
+    vmTmp?: string;
+    signal?: AbortSignal;
+}): Promise<void>;
+/** The folder's start point in project `projectId`'s hub, through a computer of the project that reads the hub. */
+export declare function seedProjectHub(ctx: Ctx, folder: string, projectId: string, opts?: {
+    open?: typeof projectHubCell;
+    hub?: string;
+    vmTmp?: string;
+}): Promise<HubSeed>;

package/dist/project-hub-seed.js

@@ -0,0 +1,59 @@
+/**
+ * A linked folder's start point in the project hub (0.28.0+). When an agent links a folder of the person's (a device's
+ * project_link), the folder as it is now (its commit, with uncommitted files as a snapshot commit on top, as a chat
+ * started from it begins) is copied into the project hub. Work on it can then start in the cloud with no conversation
+ * of that folder yet: a task names the repository, the branch and this commit, and its master checks the commit out
+ * of the hub. The hub keeps it under refs/shard/seed/link-<folder id>; nothing else in the hub moves.
+ */
+import { randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { UsageError } from "./errors.js";
+import { writeSyncFileFrom } from "./project-sync-transfer.js";
+import { HUB_PATH, git, inspectWorktree, twinSeed, worktreeId } from "./worktree-twin.js";
+import { projectHubCell } from "./worktree-twin-engine.js";
+/** Copies `commit` and its history from `folder` into the hub, kept under `ref`, unless the hub holds it already. */
+export async function sendToHub(cell, folder, commit, ref, opts = {}) {
+    const hub = opts.hub ?? HUB_PATH;
+    const run = (...args) => cell.exec.run(['git', `--git-dir=${hub}`, '-c', 'gc.auto=0', ...args], { timeoutMs: 300_000, ...(opts.signal ? { signal: opts.signal } : {}) });
+    const holds = async () => (await run('cat-file', '-e', `${commit}^{commit}`)).exitCode === 0;
+    if (await holds()) {
+        const r = await run('update-ref', ref, commit);
+        if (r.exitCode !== 0)
+            throw new Error(`the project hub could not keep the folder's commit: ${r.stderr.trim().slice(-400)}`);
+        return;
+    }
+    const tmpRef = `refs/shard/seed-tmp/${randomUUID()}`, local = join(tmpdir(), `shard-hub-seed-${randomUUID()}.bundle`), remote = `${opts.vmTmp ?? '/tmp'}/shard-hub-seed-${randomUUID()}.bundle`;
+    await git(folder, ['update-ref', tmpRef, commit]);
+    try {
+        await git(folder, ['bundle', 'create', '-q', local, tmpRef]);
+        await writeSyncFileFrom(cell, remote, local, opts.signal);
+        const r = await run('fetch', '-q', '--no-tags', remote, `+${tmpRef}:${ref}`);
+        if (r.exitCode !== 0)
+            throw new Error(`the project hub could not take the folder: ${r.stderr.trim().slice(-400)}`);
+    }
+    finally {
+        await git(folder, ['update-ref', '-d', tmpRef], { ok: [0, 1] });
+        await rm(local, { force: true });
+        await cell.files.remove(remote).catch(() => undefined);
+    }
+    if (!await holds())
+        throw new Error('the project hub does not hold the folder after copying it');
+}
+/** The folder's start point in project `projectId`'s hub, through a computer of the project that reads the hub. */
+export async function seedProjectHub(ctx, folder, projectId, opts = {}) {
+    const open = opts.open ?? projectHubCell;
+    const info = await inspectWorktree(folder);
+    if (!info.head)
+        throw new UsageError('Commit this folder once before linking it.');
+    const seed = await twinSeed(ctx.store.dir, folder, info.head, projectId);
+    const vm = await open(ctx, projectId, ctx.signal, 'shard-link');
+    try {
+        await sendToHub(vm.cell, folder, seed.commit, `refs/shard/seed/link-${worktreeId(folder)}`, { signal: ctx.signal, ...(opts.hub ? { hub: opts.hub } : {}), ...(opts.vmTmp ? { vmTmp: opts.vmTmp } : {}) });
+    }
+    finally {
+        vm.close();
+    }
+    return { commit: seed.commit, branch: info.branch?.replace(/^refs\/heads\//, '') || null };
+}

package/dist/registry.d.ts

@@ -1,7 +1,7 @@
 import type { RegistryOptions } from '@shardflux/sdk';
 export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
 /** The npm packages whose versions `shard update` compares. */
-export declare const NPM_CLIENTS: readonly ["shardflux", "@shardflux/cli", "@shardflux/sdk", "@shardflux/mcp", "@shardflux/menubar-darwin"];
+export declare const NPM_CLIENTS: readonly string[];
 /** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
 export declare function npmRegistry(env: Record<string, string | undefined>): string;
 /** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */

package/dist/registry.js

@@ -4,9 +4,10 @@
  * `hold` (see withRegistryLatest).
  */
 import { npmLatest, registryFromEnv } from '@shardflux/sdk';
+import { macAppPackage } from "./mac-app.js";
 export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
 /** The npm packages whose versions `shard update` compares. */
-export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', '@shardflux/menubar-darwin'];
+export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', ...new Set([macAppPackage('arm64'), macAppPackage('x64')])];
 /** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
 export function npmRegistry(env) {
     return registryFromEnv(env, 'npm');

package/dist/router-commands.d.ts

@@ -1,14 +1,15 @@
-import type { RouterResult, Shardflux, ShardfluxAccount } from '@shardflux/sdk';
-import type { Ctx, Handler } from './commands.js';
+/**
+ * `shard route` and `shard ask` (0.25.0+): the board's input bar from a terminal, through @shardflux/sdk's
+ * `router.route()` and `questions.stream()` / `questions.ask()`. The signed-in session reads every project of an
+ * organization; SHARDFLUX_API_KEY in the environment (or a saved key without a session) reads that key's project.
+ *
+ * Deprecated since 0.27.0: each prints a one-line notice on stderr naming
+ * `shard orchestrator say`, which sends the input to the person's orchestrator agent (orchestrator-commands.ts).
+ */
+import type { RouterResult } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
 /** The API's bound on one input or question (characters). */
 export declare const BOARD_TEXT_MAX = 4000;
-interface BoardClient {
-    client: Shardflux | ShardfluxAccount;
-    /** The signed-in session: the organization's whole board. */
-    session: boolean;
-}
-/** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
-export declare function boardClient(ctx: Ctx): BoardClient;
 /**
  * The readable form of a RouterResult: the kind and where it goes, then each part (a split's parts numbered, with
  * their titles).
@@ -18,5 +19,6 @@ export declare function boardClient(ctx: Ctx): BoardClient;
  *        fix the hero image on the landing page
  */
 export declare function routeText(r: RouterResult, names: ReadonlyMap<string, string>): string;
+/** The one-line notice `shard route` and `shard ask` print on stderr (also with --json, whose output stays the same). */
+export declare const deprecationNotice: (command: "route" | "ask") => string;
 export declare const ROUTER_HANDLERS: Record<string, Handler>;
-export {};