@shardflux/cli 0.25.0 → 0.28.1

package/dist/orchestrator-commands.js

@@ -0,0 +1,260 @@
+/**
+ * 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 } 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"');
+        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,25 +1,15 @@
-import type { RouterResult, Shardflux, ShardfluxAccount } from '@shardflux/sdk';
-import type { Values } from './args.js';
-import type { Ctx, 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;
-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.
+ * `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).
  */
-export declare function inScope<T>(ctx: Ctx, values: Values, call: (client: Shardflux | ShardfluxAccount, scope: Scope) => Promise<T>): Promise<T>;
+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;
 /**
  * The readable form of a RouterResult: the kind and where it goes, then each part (a split's parts numbered, with
  * their titles).
@@ -29,5 +19,6 @@ export declare function inScope<T>(ctx: Ctx, values: Values, call: (client: Shar
  *        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 {};

package/dist/router-commands.js

@@ -1,67 +1,9 @@
-/**
- * `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.
- */
-import { ShardfluxApiError } from '@shardflux/sdk';
-import { UUID } from "./args.js";
-import { findOrg, resolveOrg, resolveProject } from "./account-scope.js";
+import { inScope } from "./person-scope.js";
 import { out, str } from "./commands.js";
 import { EXIT, UsageError } from "./errors.js";
 /** The API's bound on one input or question (characters). */
 export const BOARD_TEXT_MAX = 4000;
 const TASK_ID = /^[A-Za-z0-9_-]{1,64}$/;
-/** 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 });
-    }
-}
 function textOf(words, what, command) {
     const text = words.join(' ').trim();
     if (!text)
@@ -118,6 +60,8 @@ export function routeText(r, names) {
     }
     return `${lines.join('\n')}\n`;
 }
+/** The one-line notice `shard route` and `shard ask` print on stderr (also with --json, whose output stays the same). */
+export const deprecationNotice = (command) => `shard ${command} is deprecated; use shard orchestrator say <words> instead.\n`;
 const interrupted = (ctx, err) => {
     if (ctx.signal.aborted)
         return EXIT.interrupted;
@@ -125,6 +69,7 @@ const interrupted = (ctx, err) => {
 };
 export const ROUTER_HANDLERS = {
     async route(ctx, values, words) {
+        ctx.io.stderr.write(deprecationNotice('route'));
         const text = textOf(words, 'text', 'route');
         const selectedTaskId = taskOf(values);
         try {
@@ -144,6 +89,7 @@ export const ROUTER_HANDLERS = {
         }
     },
     async ask(ctx, values, words) {
+        ctx.io.stderr.write(deprecationNotice('ask'));
         const text = textOf(words, 'question', 'ask');
         const taskId = taskOf(values);
         const params = { text, ...(taskId === undefined ? {} : { taskId }), signal: ctx.signal };

package/dist/startup-housekeeping.d.ts

@@ -0,0 +1,5 @@
+import type { Ctx } from './commands.js';
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;
+/** Keep the command's already selected auth behavior, loading Git machinery only for tracked repositories. */
+export declare function housekeepingIfTracked(ctx: Pick<Ctx, 'io' | 'apiUrl' | 'signal' | 'store' | 'cloud'>): Promise<void>;

package/dist/startup-housekeeping.js

@@ -0,0 +1,30 @@
+import { Shardflux } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { resolveApiUrl } from "./args.js";
+import { UsageError } from "./errors.js";
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export async function startupHousekeeping(ctx) {
+    try {
+        const state = new AgentStateStore(ctx.store.dir).read();
+        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
+            return;
+        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
+        let cloud;
+        await (await import("./agent-git-commands.js")).housekeeping({ ...ctx, apiUrl, cloud: () => {
+                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
+                if (!key)
+                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
+                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
+            } });
+    }
+    catch (error) {
+        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+/** Keep the command's already selected auth behavior, loading Git machinery only for tracked repositories. */
+export async function housekeepingIfTracked(ctx) {
+    const repos = new AgentStateStore(ctx.store.dir).read().git_repositories;
+    if (!repos || !Object.keys(repos).length)
+        return;
+    await (await import("./agent-git-commands.js")).housekeeping(ctx);
+}

package/dist/t3-launch.js

@@ -8,7 +8,7 @@ import { agentReachability } from "./agent-reachability.js";
 import { conversationWorkspace, getConversation } from "./conversations.js";
 import { resolveOn } from "./thread-on-computer.js";
 import { ensureCloudClaude } from "./claude-cloud-login.js";
-import { modelChoice } from "./agent-models.js";
+import { liveModels, modelChoice } from "./agent-models.js";
 /**
  * A `t3_*` refusal raised once the workspace, conversation or thread exists names them (details.workspace_key,
  * conversation_id, t3_thread_id), so a client opens what exists instead of starting it again.
@@ -32,7 +32,7 @@ export async function t3ThreadRequest(ctx, values, app) {
         return undefined;
     }
     // The same choices as every other new thread (agent-models.ts); "default" leaves the agent's own.
-    const choice = modelChoice(values, app);
+    const choice = modelChoice(values, app, await liveModels(ctx, values, app));
     return { app, prompt, ...(choice.model ? { model: choice.model } : {}), ...(choice.effort ? { effort: choice.effort } : {}), ...(images.length ? { images } : {}) };
 }
 /**