@shardflux/cli 0.24.1 → 0.28.0

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.
- */
-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/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 } : {}) };
 }
 /**

package/dist/task-land-hub.py

@@ -0,0 +1,165 @@
+"""Shardflux result landing on the project hub: runs in a VM of the project (shipped and started by the shard CLI,
+land.ts), next to the hub on shared storage.
+
+Input: one JSON object on stdin. Output: one JSON object on stdout (exit 0; "state" says what happened).
+
+  hub       the project hub (a bare repository)
+  result    the result branch (shard/<task id>): the master merged its workers' branches into it
+  sources   worker branches; when the result branch is missing they are merged into it here, each only when the merge
+            is clean (a conflict is the master's to resolve: state "conflict", stage "integrate")
+  default   the branch to land in (default: the hub's HEAD branch, else main or master)
+  title     for the merge commit's message
+
+The result commit T lands in the default branch D: a fast-forward when D is an ancestor of T, nothing when T is already
+in D, else a merge commit when the merge is clean (a conflict: state "conflict", stage "default"; nothing changes).
+Commits with no history in common (a result started from another repository than the one D holds, or two workers from
+different repositories) never merge: state "unrelated" with its stage, nothing changes. Unlike a conflict it does not
+clear by trying again. The
+hub's branches move only by `git push` from a temporary repository, never by force, so a branch someone else moved
+meanwhile is refused (stage "raced") instead of overwritten. Before answering "landed" it checks on the hub itself that
+T is contained in D, and which sources are contained in T.
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+IDENTITY = {'GIT_AUTHOR_NAME': 'Shardflux', 'GIT_AUTHOR_EMAIL': 'landing@shardflux.dev',
+            'GIT_COMMITTER_NAME': 'Shardflux', 'GIT_COMMITTER_EMAIL': 'landing@shardflux.dev'}
+
+
+class Fail(Exception):
+    def __init__(self, reason, message):
+        super().__init__(message)
+        self.reason = reason
+
+
+def git(cwd, *args, ok=(0,), data=None):
+    env = dict(os.environ, GIT_TERMINAL_PROMPT='0', LC_ALL='C', **IDENTITY)
+    p = subprocess.run(['git', '-c', 'core.hooksPath=/dev/null', *args], cwd=cwd, env=env, input=data,
+                       stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if p.returncode not in ok:
+        raise Fail('git', 'git %s failed (%d): %s' % (args[0], p.returncode, p.stderr.decode('utf-8', 'replace').strip()[-400:]))
+    return p
+
+
+def text(cwd, *args, **kw):
+    return git(cwd, *args, **kw).stdout.decode('utf-8', 'surrogateescape').strip()
+
+
+def tip(cwd, ref):
+    p = git(cwd, 'rev-parse', '-q', '--verify', ref + '^{commit}', ok=(0, 1, 128))
+    return p.stdout.decode().strip() if p.returncode == 0 else None
+
+
+def ancestor(cwd, a, b):
+    return git(cwd, 'merge-base', '--is-ancestor', a, b, ok=(0, 1)).returncode == 0
+
+
+def related(cwd, a, b):
+    """Whether a and b have any history in common (git finds a merge base)."""
+    return git(cwd, 'merge-base', a, b, ok=(0, 1)).returncode == 0
+
+
+def merge(repo, ours, theirs, message):
+    """A merge commit of theirs into ours when the merge is clean, else (None, conflicting paths)."""
+    r = git(repo, 'merge-tree', '--write-tree', '--name-only', '--no-messages', '-z', ours, theirs, ok=(0, 1))
+    parts = r.stdout.decode('utf-8', 'surrogateescape').split('\0')
+    if r.returncode == 1:
+        return None, sorted(set(p for p in parts[1:] if p))
+    tree = parts[0].strip()
+    return text(repo, 'commit-tree', tree, '-p', ours, '-p', theirs, '-m', message), []
+
+
+def push(repo, hub, sha, branch, old):
+    """Moves the hub's branch from old (None: create) to sha, never by force; False when it moved meanwhile."""
+    lease = '--force-with-lease=refs/heads/%s:%s' % (branch, old or '')
+    p = git(repo, 'push', '-q', '--no-verify', lease, hub, '%s:refs/heads/%s' % (sha, branch), ok=(0, 1))
+    return p.returncode == 0
+
+
+def default_branch(hub, wanted):
+    if wanted:
+        return wanted
+    head = git(hub, 'symbolic-ref', '-q', 'HEAD', ok=(0, 1)).stdout.decode().strip()
+    if head.startswith('refs/heads/') and tip(hub, head):
+        return head[len('refs/heads/'):]
+    for name in ('main', 'master'):
+        if tip(hub, 'refs/heads/' + name):
+            return name
+    return head[len('refs/heads/'):] if head.startswith('refs/heads/') else 'main'
+
+
+def land(a):
+    hub, result, title = a['hub'], a['result'], a.get('title') or a['result']
+    sources = [s for s in a.get('sources', []) if s and s != result]
+    into = default_branch(hub, a.get('default'))
+    work = tempfile.mkdtemp(prefix='shard-result-')
+    try:
+        git(work, 'init', '-q', '--bare')
+        wanted = [result, into] + sources
+        refs = ['+refs/heads/%s:refs/heads/%s' % (b, b) for b in wanted if tip(hub, 'refs/heads/' + b)]
+        if refs:
+            git(work, 'fetch', '-q', '--no-tags', hub, *refs)
+        have = {b: tip(work, 'refs/heads/' + b) for b in wanted}
+        before = have.get(into)
+        t, created = have.get(result), False
+        if not t:
+            # A master that did not merge its workers: merge them here, each only when it merges cleanly.
+            for s in sources:
+                st = have.get(s)
+                if not st:
+                    continue
+                if not t or ancestor(work, t, st):
+                    t = st
+                elif not ancestor(work, st, t):
+                    if not related(work, t, st):
+                        return {'state': 'unrelated', 'stage': 'integrate', 'into': into, 'source': s}
+                    t, conflicts = merge(work, t, st, 'Merge %s into %s' % (s, result))
+                    if not t:
+                        return {'state': 'conflict', 'stage': 'integrate', 'into': into, 'source': s, 'conflicts': conflicts}
+            if not t:
+                return {'state': 'missing', 'into': into, 'message': 'the project hub has no %s and no worker branch to make it from' % result}
+            if not push(work, hub, t, result, None):
+                return {'state': 'raced', 'stage': 'integrate', 'into': into, 'message': '%s appeared on the project hub meanwhile' % result}
+            created = True
+        if before and ancestor(work, t, before):
+            method, after = 'already', before
+        elif not before or ancestor(work, before, t):
+            method, after = ('created' if not before else 'ff'), t
+        else:
+            if not related(work, before, t):
+                # Another repository's branch (a project's hub holds every folder its people linked): the result still
+                # lands in its own folder; the sources it holds say which workers' work that is.
+                contained = [s for s in sources if have.get(s) and ancestor(work, have[s], t)]
+                return {'state': 'unrelated', 'stage': 'default', 'into': into, 'result': t, 'before': before, 'contained': contained}
+            after, conflicts = merge(work, before, t, 'Land %s (%s)' % (title, result))
+            if not after:
+                return {'state': 'conflict', 'stage': 'default', 'into': into, 'result': t, 'before': before, 'conflicts': conflicts}
+            method = 'merge'
+        if after != before and not push(work, hub, after, into, before):
+            return {'state': 'raced', 'stage': 'default', 'into': into, 'result': t, 'message': '%s moved on the project hub meanwhile' % into}
+        # Checked on the hub itself: the result is in the branch it landed in.
+        now = tip(hub, 'refs/heads/' + into)
+        if not now or not ancestor(hub, t, now):
+            raise Fail('unverified', '%s does not contain %s on the project hub after landing' % (into, t))
+        contained = [s for s in sources if have.get(s) and ancestor(hub, have[s], t)]
+        base = (text(hub, 'merge-base', before, t, ok=(0, 1)) or None) if before else None
+        return {'state': 'landed', 'into': into, 'before': before, 'after': now, 'result': t, 'method': method,
+                'created_result': created, 'contained': contained, 'merge_base': base}
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+def main():
+    try:
+        out = land(json.load(sys.stdin))
+    except Fail as e:
+        out = {'state': 'error', 'reason': e.reason, 'message': str(e)}
+    sys.stdout.write(json.dumps(out) + '\n')
+
+
+if __name__ == '__main__':
+    main()

package/dist/this-computer.d.ts

@@ -4,8 +4,10 @@ export declare const yourComputer: (platform?: NodeJS.Platform) => string;
 export declare const LINUX_DEFAULT_SHORTCUT = "<Alt><Shift>space";
 /** A GTK accelerator ("<Control><Shift>space") as the Linux app shows it ("Ctrl+Shift+Space"); shortcutLabel in its core.mjs. */
 export declare function acceleratorLabel(accelerator: string): string;
+/** An Electron accelerator ("Alt+Shift+Space", the one app's desktop-app.json) as the person reads it. */
+export declare function electronAcceleratorLabel(accelerator: string, platform: NodeJS.Platform): string;
 /**
- * The launcher's shortcut as the person presses it: ⌥⇧Space on macOS (the menu bar's), the Linux app's configured one
- * on Linux, undefined elsewhere.
+ * The launcher's shortcut as the person presses it: the one app's (desktop-app.json in the config directory, 0.27.0+),
+ * else ⌥⇧Space on macOS (the menu bar app's) and the Linux app's configured one on Linux; undefined elsewhere.
  */
 export declare function launcherShortcut(configDir: string, platform?: NodeJS.Platform): string | undefined;

package/dist/this-computer.js

@@ -16,11 +16,29 @@ export function acceleratorLabel(accelerator) {
     const key = accelerator.replace(/<\w+>/g, '');
     return [...mods, key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1)].join('+');
 }
+/** An Electron accelerator ("Alt+Shift+Space", the one app's desktop-app.json) as the person reads it. */
+export function electronAcceleratorLabel(accelerator, platform) {
+    const parts = accelerator.split('+');
+    const key = parts.pop() ?? '';
+    if (platform === 'darwin') {
+        const symbols = { Control: '⌃', Ctrl: '⌃', Alt: '⌥', Option: '⌥', Shift: '⇧', Command: '⌘', Cmd: '⌘', CommandOrControl: '⌘', CmdOrCtrl: '⌘' };
+        const order = ['⌃', '⌥', '⇧', '⌘'];
+        return parts.map(p => symbols[p] ?? p).sort((a, b) => order.indexOf(a) - order.indexOf(b)).join('') + key;
+    }
+    const names = { Control: 'Ctrl', CommandOrControl: 'Ctrl', CmdOrCtrl: 'Ctrl', Command: 'Super', Cmd: 'Super', Super: 'Super', Meta: 'Super' };
+    return [...parts.map(p => names[p] ?? p), key].join('+');
+}
 /**
- * The launcher's shortcut as the person presses it: ⌥⇧Space on macOS (the menu bar's), the Linux app's configured one
- * on Linux, undefined elsewhere.
+ * The launcher's shortcut as the person presses it: the one app's (desktop-app.json in the config directory, 0.27.0+),
+ * else ⌥⇧Space on macOS (the menu bar app's) and the Linux app's configured one on Linux; undefined elsewhere.
  */
 export function launcherShortcut(configDir, platform = process.platform) {
+    try {
+        const app = JSON.parse(readFileSync(join(configDir, 'desktop-app.json'), 'utf8'));
+        if (typeof app.launcher_shortcut === 'string' && /^([A-Za-z]+\+)+\S+$/.test(app.launcher_shortcut) && (platform === 'darwin' || platform === 'linux'))
+            return electronAcceleratorLabel(app.launcher_shortcut, platform);
+    }
+    catch { /* the app has not written it (an older app, or none) */ }
     if (platform === 'darwin')
         return '⌥⇧Space';
     if (platform !== 'linux')

package/dist/thread-on-computer.js

@@ -19,7 +19,7 @@ import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from
 import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { ensureCodexCloud, printCloudThread, submitCloudInitialPrompt } from "./codex-cloud.js";
-import { modelChoice } from "./agent-models.js";
+import { liveModels, modelChoice } from "./agent-models.js";
 import { storedTitlePrefix } from "./client-settings.js";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
@@ -143,7 +143,7 @@ export async function startThreadOn(ctx, values, path, explicitApp) {
     const review = values.review === true;
     if (review && app === 'codex')
         throw new UsageError('--review starts a read-only Claude reviewer. A Codex thread on a computer works on its own branch; omit --review.');
-    const choice = modelChoice(values, app);
+    const choice = modelChoice(values, app, await liveModels(ctx, values, app));
     const name = str(values.name);
     if (name !== undefined && !/^[a-z0-9][a-z0-9-]{0,47}$/.test(name))
         throw new UsageError('--name must match ^[a-z0-9][a-z0-9-]{0,47}$');

package/dist/timing.js

@@ -53,13 +53,15 @@ export class TimingRecorder {
         return own && own.action !== 'token' ? own : this.last;
     }
 }
-/** A resume that booted the saved disk: files as of the suspend, every process restarted (never a null memory_restored). */
+/** A resume that booted its disk: files kept, every process restarted (never a null memory_restored). */
 function restartedProcesses(t) {
     return t.server?.resumePath === 'cold_boot' && t.server.memoryRestored === false;
 }
 /** Cold boot reasons the notice says in words (0.8.1+); any other reason is printed as the API sent it. */
 const COLD_BOOT_WORDS = {
     host_lost: 'the machine it ran on failed',
+    guest_unresponsive: 'the guest did not become ready after bounded restore attempts',
+    guest_filesystem: 'the filesystem was repaired offline',
 };
 /**
  * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without

package/dist/transcribe-commands.d.ts

@@ -0,0 +1,7 @@
+import type { Transcript } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
+/** What one transcription holds (the API's bound; past it the rest is not transcribed and `truncated` says so). */
+export declare const TRANSCRIBE_MAX_BYTES: number;
+/** The readable form: the text, then (with --words) one line per word with its start and end. */
+export declare function transcriptText(t: Transcript, words: boolean): string;
+export declare const TRANSCRIBE_HANDLERS: Record<string, Handler>;

package/dist/transcribe-commands.js

@@ -0,0 +1,84 @@
+/**
+ * `shard transcribe <file>` (0.25.0+): what a recording says, with each word's time, through @shardflux/sdk's
+ * `transcriptions.transcribe()` (GET /v1/transcriptions). The signed-in session or SHARDFLUX_API_KEY, like
+ * `shard route` and `shard ask`; the audio goes to the API only and is not kept.
+ */
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { ShardfluxApiError, audioFormatOf } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { EXIT, UsageError } from "./errors.js";
+import { inScope } from "./person-scope.js";
+/** What one transcription holds (the API's bound; past it the rest is not transcribed and `truncated` says so). */
+export const TRANSCRIBE_MAX_BYTES = 6 * 1024 * 1024;
+const FORMATS = ['webm', 'wav', 'pcm16'];
+const BY_EXTENSION = { '.webm': 'webm', '.weba': 'webm', '.wav': 'wav', '.wave': 'wav', '.pcm': 'pcm16', '.raw': 'pcm16' };
+const SAMPLE_RATES = [8000, 16000, 22050, 24000, 32000, 44100, 48000];
+/** `12.34` seconds as `0:12.34`. */
+const clock = (s) => `${Math.floor(s / 60)}:${(s % 60).toFixed(2).padStart(5, '0')}`;
+/** The readable form: the text, then (with --words) one line per word with its start and end. */
+export function transcriptText(t, words) {
+    const lines = [t.text || '(no speech)'];
+    if (t.truncated)
+        lines.push(`(only the first ${Math.round(t.duration)} s were transcribed)`);
+    if (words)
+        for (const w of t.words)
+            lines.push(`${clock(w.start)}  ${clock(w.end)}  ${w.w}`);
+    return `${lines.join('\n')}\n`;
+}
+export const TRANSCRIBE_HANDLERS = {
+    async transcribe(ctx, values, [file]) {
+        if (!file)
+            throw new UsageError('missing <file> for "shard transcribe"');
+        const named = str(values.format);
+        if (named !== undefined && !FORMATS.includes(named))
+            throw new UsageError(`--format must be one of ${FORMATS.join(', ')}`);
+        const rateText = str(values['sample-rate']);
+        const sampleRate = rateText === undefined ? undefined : Number(rateText);
+        if (sampleRate !== undefined && !SAMPLE_RATES.includes(sampleRate))
+            throw new UsageError(`--sample-rate must be one of ${SAMPLE_RATES.join(', ')}`);
+        const language = str(values.language);
+        if (language !== undefined && !/^[a-z]{2,3}$/.test(language))
+            throw new UsageError('--language must be an ISO 639-1 code such as en or fi');
+        const bytes = await readFile(file).catch((e) => {
+            throw new UsageError(`cannot read "${file}" (${e.code === 'EISDIR' ? 'a folder' : e.code ?? e.message})`);
+        });
+        const format = named ?? audioFormatOf(bytes) ?? BY_EXTENSION[extname(file).toLowerCase()];
+        if (!format)
+            throw new UsageError(`cannot tell the audio format of "${file}"`, 'pass --format webm|wav|pcm16 (WebM/Opus, PCM WAV or raw 16-bit mono)');
+        if (format === 'pcm16' && sampleRate === undefined)
+            throw new UsageError('raw pcm16 audio needs --sample-rate (for example 16000)');
+        if (format !== 'pcm16' && sampleRate !== undefined)
+            throw new UsageError('--sample-rate is only for --format pcm16');
+        if (bytes.length > TRANSCRIBE_MAX_BYTES)
+            ctx.io.stderr.write(`Only the first ${TRANSCRIBE_MAX_BYTES / 1024 / 1024} MB (and at most 120 s) of "${file}" is transcribed.\n`);
+        const audio = bytes.subarray(0, TRANSCRIBE_MAX_BYTES);
+        try {
+            const transcript = await inScope(ctx, values, (client, scope) => client.transcriptions.transcribe(audio, {
+                format,
+                ...(sampleRate === undefined ? {} : { sampleRate }),
+                ...(language === undefined ? {} : { language }),
+                ...scope,
+                signal: ctx.signal,
+                onEvent: (e) => {
+                    if (e.type === 'queued')
+                        ctx.io.stderr.write(`Queued: position ${e.position}, about ${Math.max(1, Math.round(e.expectedWaitMs / 1000))} s\n`);
+                },
+            }));
+            if (ctx.json)
+                out(ctx, '', transcript);
+            else
+                ctx.io.stdout.write(transcriptText(transcript, values.words === true));
+            return EXIT.ok;
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                return EXIT.interrupted;
+            if (err instanceof ShardfluxApiError && err.reason === 'cloud_transcription_off') {
+                ctx.io.stderr.write('Cloud transcription is not on for this organization (cloud_transcription_off).\n');
+                return EXIT.error;
+            }
+            throw err;
+        }
+    },
+};

package/dist/update.js

@@ -18,12 +18,14 @@ import { AgentStateStore } from "./agent-state.js";
 import { writePrivateFile } from "./credentials.js";
 import { CodedError } from "./errors.js";
 import { json } from "./format.js";
+import { macAppPackage, ONE_APP_ON_MAC } from "./mac-app.js";
 import { compareAppVersions, MenubarManager, packagedAppPath } from "./menubar.js";
 export const INSTALL_FILE = 'install.json';
 export const LAST_UPDATE_FILE = 'last-update.json';
 const LOCK_FILE = 'update.lock';
 const MCP = '@shardflux/mcp';
-const MENUBAR = '@shardflux/menubar-darwin';
+/** The npm package of the macOS app on this Mac: the menu bar app, or the one Shardflux app once it takes over. */
+const MENUBAR = macAppPackage();
 /** Finds the package directory of `pkg` above `script` and how it was installed. */
 export function detectInstall(script, pkg, platform = process.platform) {
     let real = script;
@@ -100,7 +102,7 @@ export function displayCommand(install, specs) {
 }
 /** Prefixes can contain spaces, quotes or shell substitutions. The actual install still uses argv. */
 const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
-const LABELS = { shardflux: 'shardflux', '@shardflux/cli': 'shard', '@shardflux/sdk': 'SDK', [MENUBAR]: 'menu bar', [MCP]: 'MCP server' };
+const LABELS = { shardflux: 'shardflux', '@shardflux/cli': 'shard', '@shardflux/sdk': 'SDK', [MENUBAR]: ONE_APP_ON_MAC ? 'Shardflux app' : 'menu bar', [MCP]: 'MCP server' };
 /** Every local piece and its status against the catalog. */
 export async function components(ctx, install, catalog, menubar = menubarManager(ctx)) {
     const local = [[ctx.distribution.package, ctx.distribution.version]];

package/dist/wait-status.d.ts

@@ -14,7 +14,7 @@ export declare function queueLine(e: Pick<Extract<ProgressEvent, {
     type: 'phase';
 }>, 'queuePosition' | 'scaleOut' | 'expectedReadyBy' | 'deadlineAt'>): string;
 /** A call waiting to be admitted, in words. */
-export declare function admissionLine(r: Pick<RetryRecord, 'reason' | 'queuePosition'>): string;
+export declare function admissionLine(r: Pick<RetryRecord, 'reason' | 'queuePosition' | 'retryAfterSeconds'>): string;
 /**
  * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
  * the queue, so a later queue prints again.

package/dist/wait-status.js

@@ -17,6 +17,8 @@ export function queueLine(e) {
 /** A call waiting to be admitted, in words. */
 export function admissionLine(r) {
     const position = r.queuePosition ? ` (position ${r.queuePosition})` : '';
+    if (r.reason === 'admission_queued')
+        return `queued for admission${position}${r.retryAfterSeconds != null ? `; retrying in ${r.retryAfterSeconds} s` : ''}`;
     if (r.reason === 'host_capacity')
         return `waiting for room on the workspace's host${position}`;
     if (r.reason === 'concurrent_workspaces')

package/dist/worktree-twin-engine.d.ts

@@ -119,6 +119,14 @@ export interface LoopDeps {
  * runs immediately. The first pass that succeeds after failures clears them too and runs again at once.
  */
 export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promise<void>;
+/**
+ * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
+ * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
+ */
+export declare function projectHubCell(ctx: Ctx, projectId: string, signal?: AbortSignal, agentLabel?: string): Promise<{
+    cell: TwinCell;
+    close(): void;
+}>;
 /** The device helper's twin. Nothing here asks the user anything. */
 export declare function runWorktreeTwin(ctx: Ctx, device: string, signal: AbortSignal): Promise<void>;
 export declare const TWIN_HANDLERS: Record<string, Handler>;

package/dist/worktree-twin-engine.js

@@ -500,13 +500,36 @@ function reachable(url) {
     });
 }
 const gone = (error) => error.status === 404 || error.details?.reason === 'workspace_deleted';
+const openCell = (ws, agentLabel) => {
+    const cell = ws.cell({ agentLabel });
+    return { cell, close: () => cell.close() };
+};
+/**
+ * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
+ * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
+ */
+export async function projectHubCell(ctx, projectId, signal, agentLabel = 'shard-twin') {
+    const client = conversationClient(ctx);
+    const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
+        .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+    for (const c of all) {
+        try {
+            const ws = await client.workspaces.get(c.workspace_id);
+            if (!ws.data.deleted_at && ws.ready)
+                return openCell(ws, agentLabel);
+        }
+        catch { /* another may be awake */ }
+    }
+    const reader = await client.conversations.spaceReader(projectId, { ...(signal ? { signal } : {}) });
+    const ws = await client.workspaces.get(reader.workspace.id);
+    if (!ws.ready)
+        await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, ...(signal ? { signal } : {}) });
+    return openCell(ws, agentLabel);
+}
 /** The device helper's twin. Nothing here asks the user anything. */
 export async function runWorktreeTwin(ctx, device, signal) {
     const client = () => conversationClient(ctx);
-    const open = (ws) => {
-        const cell = ws.cell({ agentLabel: 'shard-twin' });
-        return { cell, close: () => cell.close() };
-    };
+    const open = (ws) => openCell(ws, 'shard-twin');
     const engine = new TwinEngine({
         records: () => Object.values(localConversations(ctx)),
         conversations: async (projectId) => await listConversations(ctx, projectId),
@@ -539,24 +562,7 @@ export async function runWorktreeTwin(ctx, device, signal) {
                 await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal });
             return open(ws);
         },
-        hubCell: async (projectId) => {
-            // An awake VM of the project reads the hub without waking anything; else the project's small space reader.
-            const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
-                .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
-            for (const c of all) {
-                try {
-                    const ws = await client().workspaces.get(c.workspace_id);
-                    if (!ws.data.deleted_at && ws.ready)
-                        return open(ws);
-                }
-                catch { /* another may be awake */ }
-            }
-            const reader = await client().conversations.spaceReader(projectId, { signal });
-            const ws = await client().workspaces.get(reader.workspace.id);
-            if (!ws.ready)
-                await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal });
-            return open(ws);
-        },
+        hubCell: projectId => projectHubCell(ctx, projectId, signal),
         resume: async (c) => { await client().conversations.resume(c.id, { signal }); },
         land: async (c, action, into) => { await client().conversations.land(c.id, action, { into, signal }); },
         message: async (c, text) => { await client().conversations.send(c.id, text, { signal }); },
@@ -618,7 +624,7 @@ export const TWIN_HANDLERS = {
             ledger.setMode(project, action);
         }
         const mode = ledger.mode(project);
-        const text = mode === 'auto' ? 'Finished conversations land in your local branch automatically.' : mode === 'pr' ? 'Finished conversations open a pull request instead of landing locally.' : 'Automatic landing is off for this project.';
+        const text = !ledger.autoLand() ? 'Automatic landing is off on this computer: shard settings --auto-land on turns it back on.' : mode === 'auto' ? 'Finished conversations land in your local branch automatically.' : mode === 'pr' ? 'Finished conversations open a pull request instead of landing locally.' : 'Automatic landing is off for this project.';
         out(ctx, `${text}\n`, { project_id: project, landing: mode });
         return 0;
     },

package/dist/worktree-twin.d.ts

@@ -265,7 +265,9 @@ export interface TwinConversationState {
     last_error?: string;
     latency_ms?: number;
 }
+/** `auto_land: false` (`shard settings --auto-land off`, the desktop app's Settings switch): nothing lands on this computer. */
 interface TwinDoc {
+    auto_land?: boolean;
     landing?: Record<string, LandingMode>;
     conversations?: Record<string, TwinConversationState>;
 }
@@ -273,8 +275,12 @@ export declare class TwinLedger {
     readonly store: AgentStateStore;
     constructor(dir: string);
     read(): TwinDoc;
+    /** The project's landing, 'off' everywhere while this computer's switch is off. */
     mode(project: string): LandingMode;
     setMode(project: string, mode: LandingMode): void;
+    /** This computer's switch for every project (on unless turned off). */
+    autoLand(): boolean;
+    setAutoLand(on: boolean): void;
     conversation(id: string): TwinConversationState;
     patch(id: string, change: Partial<TwinConversationState>): void;
     forget(id: string): void;

package/dist/worktree-twin.js

@@ -726,8 +726,15 @@ export class TwinLedger {
     store;
     constructor(dir) { this.store = new AgentStateStore(dir); }
     read() { return this.store.read().worktree_twin ?? {}; }
-    mode(project) { return this.read().landing?.[project] ?? 'auto'; }
+    /** The project's landing, 'off' everywhere while this computer's switch is off. */
+    mode(project) { const doc = this.read(); return doc.auto_land === false ? 'off' : doc.landing?.[project] ?? 'auto'; }
     setMode(project, mode) { this.update(doc => { doc.landing = { ...doc.landing, [project]: mode }; }); }
+    /** This computer's switch for every project (on unless turned off). */
+    autoLand() { return this.read().auto_land !== false; }
+    setAutoLand(on) { this.update(doc => { if (on)
+        delete doc.auto_land;
+    else
+        doc.auto_land = false; }); }
     conversation(id) { return this.read().conversations?.[id] ?? {}; }
     patch(id, change) {
         this.update(doc => { doc.conversations = { ...doc.conversations, [id]: { ...doc.conversations?.[id], ...change } }; });