@shardflux/cli 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Device requests reach the right computer (0.25.0+): the background helper tells the API which conversations are
+  local to this computer (started or opened here), so their requests come here first, then to the computer you used
+  last, never to whichever was seen last. A project link with a first task (`project_link` with `brief`) reads the
+  start's whole JSON output; before, it failed with "Unexpected token '}'" although the conversation started.
+
+- `shard board` and `shard task show` show what a working task does now ("working (Fixing the login cookie)") and
+  what each working step does, next to the plain waiting line of a task that waits to start.
+- `shard transcribe <file>` (0.25.0+, SDK 0.28.0) prints what a recording says (WebM/Opus or PCM WAV from the file;
+  raw PCM with `--format pcm16 --sample-rate`); `--words` adds each word's start and end, `--json` prints the
+  transcript.
 - Faster conversation starts (0.24.1): the project's dependency fingerprint is read from Git's own file list instead of walking the whole folder, so ignored and untracked trees beside the project (agent worktrees, build output) no longer hold a start on **Getting your project…**. A folder with 1.2 million such files took 32 s per start; it now takes 0.3 s, with the same fingerprint.
 - A folder without Git that `shard` makes a repository of (a first chat, `shard projects link`) starts with its files as
   the first commit (0.25.0+; `.gitignore` respected, large media stay untracked), so a conversation starts from the
@@ -18,6 +28,26 @@
   could no longer open. Key and sign-in stores (`~/.ssh`, `~/.aws`, `.env` files, private keys) stay here. Up to 64
   files, 64 MiB in all, 16 MiB each; the command names what it brings and what stays, and `--json` adds `files` and
   `files_left`.
+- 0.25.0 (pending): Allowance hints respect unavailable overage; operation errors retain the service’s recovery message and retry delay.
+
+- Landing that lands (0.25.0+): `shard task land <task>` merges a finished task's result (`shard/<task id>`, where its
+  master merged its workers' branches; when a master did not, their branches are merged into it here when they merge
+  cleanly) into the project's default branch on the project hub, a fast-forward or a clean merge commit, never by
+  force; brings it into your folder on this computer the way finished conversations land (your branch moves, your
+  uncommitted edits stay, rewritten files are backed up first); checks the commit is in the branch; and only then
+  records it on the board (`Landed in ~/code/best-todo · 3f2a1c9`). A conflict changes nothing and asks the task's
+  master to merge (`land_conflict`). `shard needs-you answer land_… land` does the same, and
+  `shard conversations land <id> merge` now lands the conversation's branch the same way before it records it (before,
+  both only recorded a landing). `--path <folder>` picks the folder; `--json` returns `{landed, result, hub, folder,
+  recorded, message}`.
+
+- `shard conversations delete <id> --yes` (`shard c delete`, 0.25.0+, SDK 0.28.0) deletes a conversation everywhere at
+  once: its agent stops, its computer is deleted (a computer other conversations share stays for them), and its
+  messages, transcript and branch go with it, on every device. Without `--yes` it is refused before any request, as
+  every deletion is. `--json` prints the API's answer, `{id, deleted, deleted_at, operation}`; deleting it again answers
+  the same. The person who started it (or created the API key that did) and organization owners and admins delete
+  conversations. `shard conversations feed` shows a deleted conversation once as `<id>  Deleted conversation  deleted`.
+- ACP input recovery (0.25.0): temporary guest-agent interruptions use bounded backoff with the same native input identity. The editor retains its running turn; permanent errors and unverified receipts still require loading the session.
 
 - Tunnel recovery (0.24.1, SDK 0.27.3): a foreground reverse tunnel replaces its guest helper automatically when replay is lost. Existing TCP peers reset; fresh connections reach the new listener. SSH and device port-forward connections close cleanly for a new connection instead of looping on an unrecoverable cursor.
 - Folders on this computer (0.25.0+): an agent can list a folder here (`dir_list`: names, kinds, sizes and Git
@@ -87,7 +117,6 @@
   `codex_sign_in_required` and that line. The Codex remote device is never restarted for a sign-in (its Cloud threads
   keep running), and one starting again with the new login reads as connecting.
 
-
 - `shard conversations start` starts a conversation without a folder: from the project hub (`--repo`, `--branch`), or with `--home` a coordinator on your machine that spawns threads in the project's repositories. `--app`, `--model`, `--effort`, `--title`, `--project`; `--prompt` sends the first message, with `--file` attachments. Prints the conversation's id, key and state (`--json`: the conversation, its workspace and the message).
 
 - `shard conversations send <id> <text> --file <path>` (repeatable, up to 20 files of 64 MiB each) puts each file in the conversation's computer before the message, which lists their paths, and prints `Attached <path>` for each. The text may be left out when files are attached, and unquoted words are sent as one message.

package/README.md

@@ -1,5 +1,7 @@
 # @shardflux/cli: `shard`
 
+For error codes, retry timing, and plan recovery, see the [error reference](https://docs.shardflux.dev/reference/errors).
+
 Historical template file lists: reads queue checksum-verified reconstruction when a cold list is absent from the SQL cache. TypeScript SDK 0.27.0+ / Python 0.23.0+ wait full Retry-After for retryable API 409 file_list_indexing on GET/HEAD within the admission timeout. Template objects and version history stay available.
 
 Plan-derived API budgets (0.23.0+, SDK 0.27.0): `--json` error output includes `rate_limit` and `retry_after_seconds`; the text hint names the shared scope and delay. API request pacing follows the SDK admission timeout and preserves the request body. Reuse workspace credentials and reduce status polling when the returned budget asks for a delay.
@@ -705,6 +707,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `usage [--org <id>] [--estimate \| --series \| --workspace <id\|key>] [--from T] [--to T] [--granularity hour\|day] [--meter M]` | Usage summary for the current period: plan, meters and allowances. `--estimate`: the bill so far and projected allowance use; `--series`: usage over time; `--workspace`: one workspace's usage over time (0.5.0+). The summary includes the [overage](#usage-and-overage) block (0.5.1+). |
 | `feedback [--yes] [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Preview feedback; `--yes` sends after explicit user authorization (0.22.0+). See [Feedback](#feedback-preview-and-user-approval). |
 | `route [--task ID] [--org O] [--project P] <text...>`, `ask [--task ID] [--org O] [--project P] <question...>` | The board's input bar (0.25.0+): where a line of input goes (its project or your home; a task, a question or a steer, split per task), and a quick question about your work, answered as it is written. |
+| `conversations delete <id> --yes` (`c delete`) | Delete a conversation everywhere at once (0.25.0+): its agent stops, its computer is deleted, and its messages, transcript and branch go with it. `--json` prints `{id, deleted, deleted_at, operation}`. See [Conversations](#conversations). |
 | `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--mode processful\|file-first] [--cpu-millis N --memory-mib N --disk-gib N] [--allocation-mode fixed\|elastic] [--memory-held N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. `--mode file-first` (0.5.0+) opens a [file-first workspace](#file-first-workspaces); the default is processful for a new key and the stored mode for an existing one. `--allocation-mode elastic` (0.8.0+): [elastic memory](#elastic-memory-080). |
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
 | `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
@@ -1620,6 +1623,17 @@ Conversation JSON includes `join_mode` and the worktree used by reviewers and wo
 
 `shard conversations resume <id>` continues a saved conversation in a fresh VM under the same identity (0.14.0+). `shard ./ --resume` uses this same path. `shard conversations reader <project-id>` opens a small read-only workspace for saved branches and transcripts; the Mac transcript mirror opens it automatically when no project VM is live. Adaptive idle reclaims the reader.
 
+`shard conversations delete <id> --yes` (0.25.0+) deletes a conversation everywhere at once: its agent stops, its
+computer is deleted (a computer other conversations share stays for them), and its messages, transcript and branch go
+with it, on every device. From then on it leaves every list and reads not found; `shard c feed` shows it once as
+`deleted`. The person who started it and organization owners and admins delete conversations. `--json` prints the
+API's answer: `{id, deleted, deleted_at, operation}`, where `operation` is the deletion of its computer.
+
+```sh
+shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
+# Deleted: conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
+```
+
 ### Route input and ask about your work (0.25.0+)
 
 `shard route` reads a line of input the way the board's input bar does: which project it belongs to (or your home),
@@ -1646,6 +1660,24 @@ prints the API's object: the route (`kind`, `parts`, `task_ref`, `uncertain`,
 `needs_work`, `sources`, …). An answer that needs work ends with "Make it a task?". Neither starts work or wakes a
 computer.
 
+### Transcribe a recording (0.25.0+)
+
+`shard transcribe <file>` prints what a recording says. `--words` adds each word with its start and end; `--json`
+prints the transcript (`text`, `words` with `w`, `start` and `end` in seconds, `language`, `duration`).
+
+```sh
+shard transcribe note.webm
+# Take this sidebar, and move it over here, then make the header a bit taller, and change that color to blue.
+shard transcribe hello.wav --words
+# Move this button over here, then make that panel a little wider.
+# 0:00.00  0:00.18  Move
+# 0:00.18  0:00.44  this
+# …
+```
+
+WebM/Opus and PCM WAV are read from the file; raw 16-bit mono PCM takes `--format pcm16 --sample-rate 16000`.
+`--language en` names the language when you know it. Up to 120 s of audio. Signed in, or with `SHARDFLUX_API_KEY`.
+
 ### Permission requests (0.25.0+)
 
 When a conversation's agent asks before it runs a tool (Claude Code, Codex or an ACP agent), the conversation is
@@ -1731,11 +1763,15 @@ changes the words (`--text`, and the task's master hears it), the title (`--titl
 (`--clear`; `--no-clear` brings it back). `shard task steer <id> <words...>` sends steering words to the task's master,
 `shard task rm <id>` deletes the task, and `shard task clear-done` clears every finished one. `shard task show <id>`
 prints the task, its plan and each report: milestone, outcome and evidence (`tests 12/12 (pnpm test)`).
+`shard task land <id>` lands a finished task: its result (the branch `shard/<task id>`, where its master merged its
+workers' branches) goes into the project's default branch and into your folder on this computer the way finished
+conversations land there (your uncommitted edits stay), and the board shows it shipped once the commit is in the
+branch: `Landed in ~/code/best-todo · 3f2a1c9`.
 
 **Needs you.** `shard needs-you` lists permission requests, questions, credential requests, finished work to land and
 Later tasks to keep, oldest first. `shard needs-you answer <id>` answers any of them: `allow`, `always` (also adds the
 always-allow rule for the project; `--everywhere` for every project) or `deny` for a permission request, `--pick` for an
-agent's question in one, `--text` for a question, `land`, `keep` or `discard` for finished work, and `--keep <task-id>`
+agent's question in one, `--text` for a question, `land` (as `shard task land`), `keep` or `discard` for finished work, and `--keep <task-id>`
 (or `keep`, `discard`) for Later tasks. The agent goes on as soon as you answer.
 
 **Approvals.** The approval mode answers your agents' permission requests before they reach you: `ask` sends every one

package/dist/acp-journal.js

@@ -90,6 +90,28 @@ export class AcpJournal {
     }
     #wanted() { return !this.#signal.aborted && !this.rpc.closed && this.#paused === 0 && (this.rpc.busy || this.#cursor.prompt_id !== undefined); }
     async #deliver(inputId, message) {
+        let failures = 0;
+        const started = performance.now();
+        while (true) {
+            this.#signal.throwIfAborted();
+            try {
+                return await this.#deliverOnce(inputId, message);
+            }
+            catch (error) {
+                // Guest restarts can refuse a new input command while its native
+                // supervisor keeps running. Its persisted receipt deduplicates this
+                // exact input id, including a command accepted before the refusal.
+                // An unverified receipt or a permanent error still stops delivery.
+                if (!(error instanceof ShardfluxApiError) || !error.retryable)
+                    throw error;
+                const remaining = RECONNECT_BUDGET_MS - (performance.now() - started);
+                if (remaining <= 0)
+                    throw new Error('ACP input reconnect timed out; load this session to continue.', { cause: error });
+                await delay(Math.min(reattachDelayMs(error, ++failures), remaining), undefined, { signal: this.#signal });
+            }
+        }
+    }
+    async #deliverOnce(inputId, message) {
         const dir = `/home/user/.local/share/shardflux/acp/${this.#conversation}`;
         const payload = Buffer.from(`{"mode":"input","input_id":${JSON.stringify(inputId)},"message":${message}}\n`);
         if (payload.length <= ONE_SHOT_INPUT) {
@@ -133,7 +155,7 @@ export class AcpJournal {
         finally {
             await this.#cell.exec.cancel(session.session_id, 0).catch(() => undefined);
         }
-        // Never resend an uncertain mutation. Its stable input identity is fenced by CVB before provider stdin.
+        // Retries retain inputId: CVB persists its receipt before provider stdin.
     }
     start() {
         this.#initial ??= this.#replay().then(() => { this.#ready = true; this.#follow(); }).catch(error => { this.rpc.close(error instanceof Error ? error : new Error(String(error))); throw error; });

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.24.1";
+export declare const CLI_VERSION = "0.25.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -14,7 +14,7 @@ import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { BOARD_COMMANDS } from "./board-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.24.1';
+export const CLI_VERSION = '0.25.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -156,7 +156,7 @@ const KEY_COMMANDS = [
     { path: ['conversations', 'feed'], summary: 'Print project conversations as they change', positionals: [], options: {
             project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, org: { type: 'string', value: '<id|slug>', description: 'Signed in: every project of this organization you work in (0.25.0+).' }, cursor: { type: 'string', value: '<cursor>', description: 'Continue after this feed cursor (--json prints it with each change).' }
         },
-        description: 'Prints each conversation the moment it changes, until interrupted: "<id>  <title>  <state>", and why it needs you when it does; --json prints one {conversation, cursor} object per line. With an API key: its project. Signed in without a key: every project you work in, on one cursor (0.25.0+); --org follows one organization’s projects and uses your sign-in when you have one.',
+        description: 'Prints each conversation the moment it changes, until interrupted: "<id>  <title>  <state>", and why it needs you when it does; a deleted conversation shows once as "<id>  Deleted conversation  deleted" (0.25.0+); --json prints one {conversation, cursor} object per line. With an API key: its project. Signed in without a key: every project you work in, on one cursor (0.25.0+); --org follows one organization’s projects and uses your sign-in when you have one.',
         examples: ['shard c feed', 'shard c feed --org acme --json'] },
     { path: ['conversations', 'resume'], summary: 'Resume a saved conversation in a fresh VM', positionals: [{ name: 'id', required: true }], options: {} },
     { path: ['conversations', 'reader'], summary: 'Open a read-only project space reader', positionals: [{ name: 'project_id', required: true }], options: {} },
@@ -194,8 +194,18 @@ const KEY_COMMANDS = [
     { path: ['conversations', 'events'], summary: 'Follow a conversation live: state, transcript, reply text and tool calls (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {},
         description: 'Streams the conversation until Ctrl-C, one line per event: state changes, new transcript lines and tool calls, with the reply written as the agent streams it. With --json: one event per line, {"type":"conversation"|"transcript"|"delta","id":…} with the conversation, the transcript lines or the ACP session updates.',
         examples: ['shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln', 'shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --json | jq -c \'select(.type=="delta")\''] },
-    { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
+    { path: ['conversations', 'land'], summary: 'Land a conversation’s work: merge lands it for real; pr, keep and discard record the decision', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: {
+            into: { type: 'string', value: '<ref>', description: 'pr: the PR URL; keep: the branch (merge always lands in the project’s default branch).' },
+            path: { type: 'string', value: '<folder>', description: 'merge: the folder to land in (default: where the conversation started on this computer).' }
+        },
+        description: 'merge (0.25.0+) merges the conversation’s branch into the project’s default branch on the project hub (a fast-forward, or a merge commit when it is clean), brings it into your folder on this computer the way finished conversations land (your uncommitted edits stay), checks the commit is in the branch, and only then records it. pr, keep and discard record what was decided.',
+        examples: ['shard conversations land conv_k3m5q7s2u4w6y3b5d7f2h4j6ln merge', 'shard conversations land conv_k3m5q7s2u4w6y3b5d7f2h4j6ln discard'] },
     { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
+    { path: ['conversations', 'delete'], summary: 'Delete a conversation everywhere: its computer, messages, transcript and branch (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {
+            yes: { type: 'boolean', description: 'Required: confirm the deletion.' }
+        },
+        description: 'Deletes the conversation on every device at once: its agent stops and its computer is deleted (a computer other conversations share stays for them), its messages, transcript and permission requests go with it, and its branch and transcript copy leave the project space. From then on it leaves every list and reads not found. The person who started it (or created the API key that did) or an organization owner or admin deletes it; deleting it again answers the same. --json prints {id, deleted, deleted_at, operation}: operation is the deletion of its computer, null when other conversations share it.',
+        examples: ['shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes', 'shard conversations delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes --json'] },
     { path: ['conversations', 'landing'], summary: 'Show or set how finished conversations reach this checkout', positionals: [{ name: 'mode' }, { name: 'backup' }], options: {
             path: { type: 'string', value: '<path>', description: 'Local project checkout (default the current directory).' }
         },
@@ -1461,6 +1471,24 @@ const ROUTER_COMMANDS = [
         },
         examples: ['shard ask what is the healthz work doing right now', 'shard ask --task task_healthzhealthzhealthzhealt "is it done?"', 'shard ask "what is blocking the pricing page?" --json'],
     },
+    {
+        path: ['transcribe'],
+        summary: 'Turn a recording into text, with each word’s start and end (0.25.0+)',
+        description: [
+            'Sends the audio to Shardflux speech to text and prints what it says. WebM/Opus (a browser recording) and PCM WAV are recognized from the file; raw 16-bit mono PCM needs --format pcm16 and --sample-rate. Up to 120 s of audio.',
+            'Uses your signed-in session, or SHARDFLUX_API_KEY when it is set. The audio is not kept.',
+            'Prints the text; --words adds one line per word with its start and end. With --json: the transcript (text, words with w, start and end in seconds, language, duration, truncated).',
+        ].join('\n\n'),
+        positionals: [{ name: 'file', required: true }],
+        options: {
+            format: { type: 'string', value: '<webm|wav|pcm16>', description: 'The audio format (default: from the file).' },
+            'sample-rate': { type: 'string', value: '<hz>', description: 'Samples per second of raw pcm16 audio (8000 to 48000).' },
+            language: { type: 'string', value: '<code>', description: 'ISO 639-1 code of the language spoken (default: detected).' },
+            words: { type: 'boolean', description: 'Print each word with its start and end.' },
+            org: { type: 'string', value: '<id|slug>', description: 'Organization to transcribe in when you are in several (default: the saved one, shard orgs use, else your only organization).' },
+        },
+        examples: ['shard transcribe note.webm', 'shard transcribe meeting.wav --words', 'shard transcribe mic.pcm --format pcm16 --sample-rate 16000 --json'],
+    },
 ];
 /** The project a drive or models command acts in (0.25.0+). */
 const PROJECT_SCOPE = {
@@ -1927,7 +1955,7 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'board', 'task', 'needs-you', 'approvals', 'route', 'ask', 'drive', 'models', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'board', 'task', 'needs-you', 'approvals', 'route', 'ask', 'transcribe', 'drive', 'models', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },

package/dist/board-args.js

@@ -80,6 +80,22 @@ export const BOARD_COMMANDS = [
         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', 'land'],
+        summary: 'Land a finished task: its result into your folder and the project’s default branch (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: { path: { type: 'string', value: '<folder>', description: 'The folder to land in (default: the project’s folder on this computer, if any).' } },
+        description: [
+            'A task has one result: the branch shard/<task id>, where its master merged its workers’ branches. Landing merges it',
+            'into the project’s default branch on the project hub (a fast-forward, or a merge commit when the merge is clean),',
+            'then brings it into your folder on this computer the way finished conversations land there: your branch moves to the',
+            'new commits, your uncommitted edits stay, and every file it rewrites is backed up first (shard conversations landing',
+            'backups). Only after the commit is checked to be in the branch is the landing recorded on the board, so the task',
+            'reads shipped. A conflict changes nothing: the task’s master is asked to merge and the task asks to land again.',
+            '--json returns {landed, result, hub, folder, recorded, message}.',
+        ].join('\n'),
+        examples: ['shard task land task_h7g4d7tqyv2pz3a2npyo4rpgzq', 'shard task land task_h7g4d7tqyv2pz3a2npyo4rpgzq --path ~/code/best-todo --json'],
+    },
     {
         path: ['task', 'clear-done'],
         summary: 'Clear every finished task from the board (0.25.0+)',
@@ -117,7 +133,8 @@ export const BOARD_COMMANDS = [
             '  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',
+            '  land_…    land (as shard task land: the result into your folder and the default branch), 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'),

package/dist/board-commands.d.ts

@@ -10,8 +10,8 @@ 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.
+ * One task as `shard board` lists it: id, state (with why it waits to start, "queued (Getting its computer ready)", or
+ * what it does now, "working (Fixing the login cookie)"), 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. */

package/dist/board-commands.js

@@ -3,6 +3,7 @@ import { detailLine, pickAnswers } from "./conversation-commands.js";
 import { NotFoundError, UsageError } from "./errors.js";
 import { time } from "./format.js";
 import { progress } from "./progress.js";
+import { landDeps, landTask, landedText } from "./land.js";
 const BUCKETS = ['now', 'next', 'later'];
 const BUCKET_TITLES = { now: 'Now', next: 'Next', later: 'Later' };
 const MODES = ['ask', 'routine', 'trusted'];
@@ -16,12 +17,17 @@ const oneLine = (s, max) => {
 export function taskLabel(t, max = 80) {
     return oneLine(t.title?.trim() || t.text, max);
 }
+/** Why a task waits to start, or what a working one does now: "Getting its computer ready", "Fixing the login cookie". */
+function stateNote(t, max) {
+    const note = t.waiting?.message.trim() || (t.state === 'working' ? t.activity?.trim() : '') || '';
+    return note ? ` (${oneLine(note, 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.
+ * One task as `shard board` lists it: id, state (with why it waits to start, "queued (Getting its computer ready)", or
+ * what it does now, "working (Fixing the login cookie)"), 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 state = `${t.state}${stateNote(t, 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)' : ''}`;
 }
@@ -111,14 +117,14 @@ 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'));
+    lines.push([`${t.state}${stateNote(t, 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(', ')}` : ''}`);
+            lines.push(`  ${s.id}\t${s.state}\t${oneLine(s.text, 100)}${s.now?.trim() ? `\t(${oneLine(s.now, 80)})` : ''}${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(', ')}`);
@@ -332,6 +338,11 @@ export const BOARD_HANDLERS = {
         out(ctx, `Steered: ${taskLabel(task)}\n`, { task });
         return 0;
     },
+    async 'task land'(ctx, values, [id]) {
+        const o = await landTask(landDeps(ctx), id, { path: str(values.path) });
+        out(ctx, landedText(o), o);
+        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 });
@@ -345,6 +356,12 @@ export const BOARD_HANDLERS = {
     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);
+        // Land merges here (shard task land) and records itself after; the board only takes keep and discard.
+        if (itemKind(id) === 'land' && word?.toLowerCase() === 'land') {
+            const o = await landTask(landDeps(ctx), id.replace(/^land_/, ''), {});
+            out(ctx, landedText(o), o);
+            return 0;
+        }
         // Checked first, so a wrong combination is a usage error before any request.
         let answer = needsAnswer(id, input);
         if (answerNeedsItem(id, input)) {

package/dist/conversation-commands.js

@@ -9,6 +9,7 @@ import { modelChoice } from "./agent-models.js";
 import { storedTitlePrefix } from "./client-settings.js";
 import { PtyOutputCursor, passiveUnavailable, sleepingAttach } from "./agent-terminal.js";
 import { progress } from "./progress.js";
+import { landConversation, landDeps, landedText } from "./land.js";
 import { UUID } from "./args.js";
 import { findOrg } from "./account-scope.js";
 export function conversationClient(ctx) {
@@ -224,8 +225,9 @@ export const CONVERSATION_HANDLERS = {
         const { client, organizationId } = await listScope(ctx, values);
         let cursor = str(values.cursor);
         for await (const c of client.conversations.watch({ projectId: str(values.project), organizationId, cursor, signal: ctx.signal, onCursor: next => { cursor = next; } })) {
-            const q = questionLine(c);
-            ctx.io.stdout.write(ctx.json ? JSON.stringify({ conversation: c, cursor }) + '\n' : `${c.id}\t${displayTitle(c)}\t${c.state}${q ? `\t${q}` : ''}\n`);
+            // A deleted conversation comes once, its content cleared: its line says deleted (0.25.0+).
+            const q = questionLine(c), line = c.deleted_at ? `${c.id}\tDeleted conversation\tdeleted` : `${c.id}\t${displayTitle(c)}\t${c.state}${q ? `\t${q}` : ''}`;
+            ctx.io.stdout.write(ctx.json ? JSON.stringify({ conversation: c, cursor }) + '\n' : `${line}\n`);
         }
         return 0;
     },
@@ -360,6 +362,12 @@ export const CONVERSATION_HANDLERS = {
     async 'conversations land'(ctx, values, [id, action]) {
         if (!['merge', 'pr', 'keep', 'discard'].includes(action))
             throw new UsageError('Choose merge, pr, keep or discard.');
+        // merge lands for real (land.ts) and records only after the commit is in the branch; the others record a decision.
+        if (action === 'merge') {
+            const o = await landConversation(landDeps(ctx), id, { path: str(values.path) });
+            out(ctx, landedText(o), o);
+            return 0;
+        }
         const r = await conversationClient(ctx).conversations.land(id, action, { into: str(values.into), signal: ctx.signal });
         out(ctx, `${displayTitle(r)}: ${r.landed.how}\n`, r);
         return 0;
@@ -370,4 +378,12 @@ export const CONVERSATION_HANDLERS = {
         return 0;
     },
     async 'conversations move'(ctx, _values, [id, to]) { const r = await conversationClient(ctx).conversations.move(id, to, { signal: ctx.signal }); out(ctx, `Move scheduled for the end of the turn.\n`, r); return 0; },
+    // Everywhere at once, its computer included (0.25.0+); refused without --yes, as every deletion is. --json: the API's answer.
+    async 'conversations delete'(ctx, values, [id]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to delete without --yes (the conversation, its computer, messages, transcript and branch are deleted everywhere)');
+        const r = await conversationClient(ctx).conversations.delete(id, { signal: ctx.signal });
+        out(ctx, `Deleted: ${r.id}\n`, r);
+        return 0;
+    },
 };

package/dist/conversations.d.ts

@@ -17,7 +17,8 @@ export interface Conversation {
     worktree_path: string;
     branch: string;
     base_commit: string;
-    state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived';
+    /** `deleted`: the one feed delivery of a deleted conversation (0.25.0+). */
+    state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived' | 'deleted';
     created_at: string;
     ended_at: string | null;
     landed?: {

package/dist/device-folders.d.ts

@@ -42,6 +42,14 @@ type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: st
  * prompt. The brief goes in on standard input, never in a command line another user can read.
  */
 export declare const startFromFolder: Starter;
+/**
+ * The conversation `shard agents new --json` started, from its whole output: one pretty-printed JSON document
+ * (format.ts json), never its last line (staging 2026-10-16: the last line is `}`).
+ */
+export declare function startedConversation(stdout: string): {
+    id: string;
+    project_id: string;
+};
 /**
  * `folder` becomes one of your projects: the repository its Git origin names (else the folder itself), in your
  * project on this API. It is selected for background preparation, so its files are in the cloud before the next chat,

package/dist/device-folders.js

@@ -148,10 +148,11 @@ export const startFromFolder = (ctx, folder, harness, brief) => {
             env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1' },
         });
         const out = [], err = [];
+        let outBytes = 0;
         const stop = () => child.kill('SIGTERM');
         const timer = setTimeout(stop, 300_000);
         ctx.signal.addEventListener('abort', stop, { once: true });
-        child.stdout.on('data', (b) => { if (out.length < 256)
+        child.stdout.on('data', (b) => { if ((outBytes += b.length) <= 8 << 20)
             out.push(b); });
         child.stderr.on('data', (b) => { if (err.length < 64)
             err.push(b); });
@@ -163,11 +164,7 @@ export const startFromFolder = (ctx, folder, harness, brief) => {
             try {
                 if (code !== 0)
                     throw new Error(lastLine(Buffer.concat(err).toString('utf8')) || `The conversation did not start (exit ${code}).`);
-                const started = JSON.parse(text.trim().split('\n').at(-1));
-                const id = started.conversation?.id ?? started.workspace?.labels?.shard_conversation;
-                if (!id)
-                    throw new Error('The conversation did not start.');
-                resolveStart({ id, project_id: started.conversation?.project_id ?? started.workspace?.project_id ?? '' });
+                resolveStart(startedConversation(text));
             }
             catch (error) {
                 reject(error instanceof Error ? error : new Error(String(error)));
@@ -176,6 +173,17 @@ export const startFromFolder = (ctx, folder, harness, brief) => {
         child.stdin.end(brief);
     });
 };
+/**
+ * The conversation `shard agents new --json` started, from its whole output: one pretty-printed JSON document
+ * (format.ts json), never its last line (staging 2026-10-16: the last line is `}`).
+ */
+export function startedConversation(stdout) {
+    const started = JSON.parse(stdout);
+    const id = started.conversation?.id ?? started.workspace?.labels?.shard_conversation;
+    if (!id)
+        throw new Error('The conversation did not start.');
+    return { id, project_id: started.conversation?.project_id ?? started.workspace?.project_id ?? '' };
+}
 function lastLine(stderr) {
     const text = stderr.trim();
     try {

package/dist/device-helper.js

@@ -150,7 +150,18 @@ export async function runDeviceHelper(ctx, options = {}) {
             // Registered for every project an agent may ask from (deviceProjects); one poll covers them all where the API
             // lists by device (0.25.0+), else one per project.
             const registered = new Map();
-            let all, deviceWide = true;
+            let all, deviceWide = true, links = true;
+            // This device's local conversations of a project (started here or opened here): their requests come here first.
+            const linked = (projectId) => Object.values(localConversations(ctx)).filter(r => !r.handed_off && (!projectId || r.project_id === projectId))
+                .sort((a, b) => (b.conversation.created_at ?? '').localeCompare(a.conversation.created_at ?? '')).slice(0, 500).map(r => r.conversation.id);
+            const beat = (projectId) => conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30, ...(links ? { conversationIds: linked(projectId) } : {}) })
+                .catch((e) => {
+                // An API before device links (0.25.0+ clients) refuses the list: register without it from then on.
+                if (!links || !(e instanceof ShardfluxApiError && [400, 422].includes(e.status)))
+                    throw e;
+                links = false;
+                return conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 });
+            });
             const take = (rows) => {
                 for (const r of rows) {
                     if (r.device_id !== deviceId || working.has(r.id) || working.size >= 8)
@@ -167,7 +178,7 @@ export async function runDeviceHelper(ctx, options = {}) {
                     for (const projectId of projects) {
                         if (Date.now() - (registered.get(projectId) ?? 0) < 10_000)
                             continue;
-                        await conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 }).then(() => registered.set(projectId, Date.now()), (e) => {
+                        await beat(projectId).then(() => registered.set(projectId, Date.now()), (e) => {
                             // A project this sign-in no longer reaches is skipped until the next listing, never the others.
                             if (!(e instanceof ShardfluxApiError && [403, 404].includes(e.status)))
                                 throw e;

package/dist/errors.js

@@ -266,7 +266,8 @@ export function describeError(err) {
         // details.reason: the operation error's reason (e.g. the scheduler's no_ready_hosts), printed after the message.
         const opDetails = err.operation.error?.details;
         const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
-        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
+        const retryAfter = typeof opDetails === 'object' && opDetails !== null ? opDetails.retry_after_seconds : undefined;
+        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}), ...(typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0 ? { retry_after_seconds: retryAfter } : {}) };
         // A suspend-when-idle canceled workspace_active (0.7.0+): the workspace was in use and keeps running.
         const message = err.workspaceActive ? `${err.message}: the workspace was in use, so the suspend-when-idle was canceled; it keeps running` : err.message;
         return { code: 'operation_failed', message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };

package/dist/format.js

@@ -448,7 +448,7 @@ const hoursText = (h) => String(Math.round(h * 100) / 100);
  * while the GPU is stopped (cap_state gpu_blocked), why and what brings it back. Workspaces keep running meanwhile.
  * Nothing without `gpu` (plans without GPU-hours).
  */
-function gpuLines(gpu, resetsAt) {
+function gpuLines(gpu, resetsAt, overageAvailable) {
     if (!isObject(gpu) || typeof gpu.used_hours !== 'number')
         return [];
     const included = typeof gpu.included_hours === 'number' ? gpu.included_hours : null;
@@ -470,6 +470,10 @@ function gpuLines(gpu, resetsAt) {
             rows.push(['GPU', `stopped (spend_cap_reached): workspaces keep running; raise the spend cap (shard billing overage cap <dollars>), or wait for the reset${resets}`]);
             break;
         default:
+            if (!overageAvailable) {
+                rows.push(['GPU', 'stopped (allowance_used): workspaces keep running; choose a paid plan (shard billing plans); overage is unavailable on the current plan']);
+                break;
+            }
             rows.push(['GPU', `stopped (allowance_used): workspaces keep running; turn on overage (shard billing overage on --cap <dollars>), upgrade (shard billing plans), or wait for the reset${resets}`]);
     }
     return rows;
@@ -507,7 +511,7 @@ export function usageText(summary) {
         head.push(['retained state', 'used up: new workspaces and forks are refused (delete workspaces you no longer need, or upgrade)']);
     }
     const resetsAt = isObject(s.period) ? [s.period.resets_at, s.period.end].find((t) => typeof t === 'string') : undefined;
-    head.push(...gpuLines(s.gpu, resetsAt));
+    head.push(...gpuLines(s.gpu, resetsAt, !(isObject(s.spend_cap) && s.spend_cap.available === false)));
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
             head.push([k.replace(/_/g, ' '), scalar(v)]);

package/dist/handlers.js

@@ -5,6 +5,7 @@ import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
 import { BOARD_HANDLERS } from "./board-commands.js";
 import { TRANSCRIPT_HANDLERS } from "./conversation-transcript.js";
 import { ROUTER_HANDLERS } from "./router-commands.js";
+import { TRANSCRIBE_HANDLERS } from "./transcribe-commands.js";
 /**
  * Every command's handler, keyed by its path ("workspaces open", "auth login"): the project-key commands of
  * commands.ts and the account plane of account-commands.ts (0.5.0). args.test.ts checks that it matches COMMANDS.
@@ -31,4 +32,4 @@ import { MACHINE_SETUP_HANDLERS } from "./machine-setup.js";
 import { SETTINGS_HANDLERS } from "./client-settings.js";
 import { PROJECT_PREPARATION_HANDLERS } from "./project-preparation.js";
 import { DRIVE_HANDLERS } from "./drive-commands.js";
-export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...DRIVE_HANDLERS };
+export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...TRANSCRIBE_HANDLERS, ...DRIVE_HANDLERS };