@shardflux/cli 0.25.0 → 0.28.0

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 { ORCHESTRATOR_HANDLERS } from "./orchestrator-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
@@ -25,11 +26,12 @@ import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
 import { THREAD_HANDLERS } from "./thread-on-computer.js";
 import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
-import { ACCOUNT_POOL_HANDLERS } from "./account-pool.js";
+import { ACCOUNT_POOL_HANDLERS, AGENT_MODELS_HANDLERS } from "./account-pool.js";
 import { MOVE_HANDLERS } from "./move.js";
 import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
 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, ...TRANSCRIBE_HANDLERS, ...DRIVE_HANDLERS };
+import { BRAIN_HANDLERS } from "./brain-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, ...ORCHESTRATOR_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...AGENT_MODELS_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, ...BRAIN_HANDLERS };

package/dist/land.d.ts

@@ -4,7 +4,7 @@ import type { TwinCell } from './worktree-twin.js';
 /** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
 export declare function hubScript(): string;
 export interface HubLanding {
-    state: 'landed' | 'conflict' | 'missing' | 'raced' | 'error';
+    state: 'landed' | 'conflict' | 'unrelated' | 'missing' | 'raced' | 'error';
     into: string;
     before?: string | null;
     after?: string;
@@ -61,8 +61,13 @@ export declare function folderBranch(folder: string, fallback: string): Promise<
  * edits stay, and the landed commit is checked to be on the branch.
  */
 export declare function landInFolder(cell: TwinCell, f: FolderInput): Promise<FolderLanding>;
-/** The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started. */
-export declare function linkedFolder(ctx: Pick<Ctx, 'store' | 'apiUrl'>, projectId: string, conversationId?: string): string | null;
+/** The repository a folder holds, as conversations started from it name it (its origin, else the folder itself). */
+export declare function folderRepository(folder: string): string | null;
+/**
+ * The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started.
+ * With `repository` (a project holds every folder its people linked), only a folder of that repository.
+ */
+export declare function linkedFolder(ctx: Pick<Ctx, 'store' | 'apiUrl'>, projectId: string, conversationId?: string, repository?: string): string | null;
 export declare const displayPath: (path: string) => string;
 export interface LandOutcome {
     landed: true;
@@ -96,7 +101,7 @@ export interface LandDeps {
         cell: TwinCell;
         close(): void;
     }>;
-    folder(projectId: string, conversationId?: string): string | null;
+    folder(projectId: string, conversationId?: string, repository?: string): string | null;
     device: string;
     stateDir: string;
     hub?: string;

package/dist/land.js

@@ -21,6 +21,7 @@ import { conversationClient } from "./conversation-commands.js";
 import { localConversations } from "./conversations.js";
 import { CodedError } from "./errors.js";
 import { selectedProjects } from "./project-preparation.js";
+import { projectIdentity } from "./project-identity.js";
 import { HUB_PATH, backupRoot, deviceId, git, gitText, inspectWorktree, landingRound, listWorktrees } from "./worktree-twin.js";
 import { projectHubCell } from "./worktree-twin-engine.js";
 let script;
@@ -84,9 +85,22 @@ export async function landInFolder(cell, f) {
         }
     }
 }
-/** The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started. */
-export function linkedFolder(ctx, projectId, conversationId) {
-    const repo = (folder) => folder && existsSync(join(folder, '.git')) ? folder : null;
+/** The repository a folder holds, as conversations started from it name it (its origin, else the folder itself). */
+export function folderRepository(folder) {
+    try {
+        const id = projectIdentity(folder);
+        return id.remote ?? `file://${id.folder}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started.
+ * With `repository` (a project holds every folder its people linked), only a folder of that repository.
+ */
+export function linkedFolder(ctx, projectId, conversationId, repository) {
+    const repo = (folder) => folder && existsSync(join(folder, '.git')) && (!repository || folderRepository(folder) === repository) ? folder : null;
     const records = localConversations(ctx);
     const own = conversationId ? repo(records[conversationId]?.folder) : null;
     if (own)
@@ -113,7 +127,7 @@ function message(o) {
     return hub;
 }
 export function landDeps(ctx) {
-    return { client: conversationClient(ctx), hubCell: p => projectHubCell(ctx, p, ctx.signal, 'shard-land'), folder: (p, c) => linkedFolder(ctx, p, c),
+    return { client: conversationClient(ctx), hubCell: p => projectHubCell(ctx, p, ctx.signal, 'shard-land'), folder: (p, c, r) => linkedFolder(ctx, p, c, r),
         device: deviceId(ctx.store.dir), stateDir: ctx.store.dir, signal: ctx.signal };
 }
 async function land(d, l, onConflict) {
@@ -127,6 +141,19 @@ async function land(d, l, onConflict) {
             await onConflict(hub);
             throw new CodedError('land_conflict', `Not landed: ${list(hub.conflicts ?? [])} changed on both sides (${hub.stage === 'integrate' ? `${hub.source} and ${l.result}` : `${l.result} and ${hub.into}`}).`, 'its master merges them and asks to land again', { stage: hub.stage, into: hub.into, conflicts: hub.conflicts ?? [] });
         }
+        // The hub's default branch is another repository's (a project holds every folder its people linked): a result
+        // whose repository has its folder here lands in that folder, and the hub's default branch stays as it is.
+        // Awaited here: the computer that reads the hub closes in `finally` (staging 2026-10-17: returned unawaited, the
+        // landing was cut off mid-way, "Interrupted.").
+        if (hub.state === 'unrelated' && hub.stage === 'default' && l.repository && l.folder && hub.result)
+            return await ownFolder(d, vm.cell, l, hub);
+        // No history in common (started from another repository than the branch it lands in): it never clears by trying
+        // again, so it says what to do instead.
+        if (hub.state === 'unrelated') {
+            throw new CodedError('land_unrelated', hub.stage === 'integrate'
+                ? `Not landed: ${hub.source} and ${l.result} have no history in common; they were started from different repositories.`
+                : `Not landed: ${l.result} has no history in common with ${hub.into} on the project hub; it was started from another repository than the one ${hub.into} holds.`, 'land it from the folder of the repository it was started from, or start the task again from this project’s own folder', { stage: hub.stage, into: hub.into });
+        }
         if (hub.state === 'missing')
             throw new CodedError('land_nothing', `Nothing to land: the project hub has no ${l.result} yet.`, 'land after the work is done', { branch: l.result });
         if (hub.state !== 'landed')
@@ -149,6 +176,23 @@ async function land(d, l, onConflict) {
         vm.close();
     }
 }
+/** A result into the folder of its own repository only (the hub's default branch holds another repository). */
+async function ownFolder(d, cell, l, hub) {
+    const folder = l.folder, into = await folderBranch(folder, 'main');
+    const contained = l.sources.filter(s => hub.contained?.includes(s.branch)).map(s => s.conversation_id);
+    if (!into)
+        return { title: l.title, result: { branch: l.result, sha: hub.result }, hub: { into: '', sha: hub.result, method: 'folder' }, contained,
+            folder: { path: folder, display: displayPath(folder), into: '', state: 'skipped', reason: 'detached' } };
+    const f = await landInFolder(cell, { folder, into, name: l.name, title: l.title, branch: l.result, base: l.base ?? hub.result, device: d.device, stateDir: d.stateDir,
+        ...(d.hub ? { hub: d.hub } : {}), ...(d.quietMs !== undefined ? { quietMs: d.quietMs } : {}), ...(d.signal ? { signal: d.signal } : {}) });
+    if (f.state !== 'landed' && f.state !== 'already') {
+        // Nothing else holds it: a folder that could not take it yet is not a landing.
+        throw new CodedError('land_failed', f.state === 'conflict'
+            ? `Not landed yet: ${list(f.conflicts ?? [])} changed in ${displayPath(folder)} too since ${l.result} started.`
+            : `Not landed yet: ${displayPath(folder)} is busy (${f.reason ?? 'busy'}).`, f.state === 'conflict' ? 'commit or put aside those changes, and it lands' : 'it lands once the folder is quiet', { into, folder: displayPath(folder) });
+    }
+    return { title: l.title, result: { branch: l.result, sha: hub.result }, hub: { into, sha: f.sha ?? hub.result, method: 'folder' }, folder: { ...f, display: displayPath(f.path) }, contained };
+}
 /** What a landing did, for people: the line, then what was not recorded. */
 export function landedText(o) {
     return `${o.message}\n${o.recorded ? '' : `Not recorded on the board: ${o.record_error ?? 'unknown'}.\n`}`;
@@ -180,9 +224,11 @@ export async function landTask(d, taskId, opts = {}) {
         if (w.join_mode !== 'reviewer' && (w.changes?.commits ?? 0) > 0 && w.landed?.how !== 'discarded')
             workers.push(w);
     }
-    const folder = opts.path ?? d.folder(task.project_id);
+    // The repository the result is of: its workers' (or its master's), so it lands only in a folder of that repository.
+    const repository = workers.find(w => w.repo_remote)?.repo_remote ?? (task.master_id ? (await client.conversations.get(task.master_id).catch(() => null))?.repo_remote : undefined) ?? null;
+    const folder = opts.path ?? d.folder(task.project_id, undefined, repository ?? undefined);
     const done = await land(d, { projectId: task.project_id, title, name: taskId, result: resultBranch(taskId), sources: workers.map(w => ({ branch: w.branch, conversation_id: w.id })),
-        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder }, async (hub) => {
+        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder, repository }, async (hub) => {
         const what = hub.stage === 'integrate' ? `${hub.source} into ${resultBranch(taskId)}` : `${resultBranch(taskId)} into ${hub.into}`;
         await client.tasks.steer(taskId, `Land could not merge ${what}: ${list(hub.conflicts ?? [])} changed on both sides. Merge ${hub.into} from the project hub and every worker branch into ${resultBranch(taskId)}, resolve the conflicts so both changes work (ask the person only if the choice is theirs), run the tests, push ${resultBranch(taskId)} to the hub and seal done again.`, signal);
     });

package/dist/mac-app.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Which macOS app this CLI installs and updates. On (0.27.0+): the one Shardflux app from
+ * @shardflux/desktop-darwin-<arch>, which replaces the menu bar app (@shardflux/menubar-darwin) in place. The CLI's
+ * optionalDependencies carry the same packages (test/one-app.test.ts keeps the two in step): with the desktop package
+ * in the install, `shard`, its refresh and the running menu bar app's self-update replace the menu bar app with it.
+ */
+export declare const ONE_APP_ON_MAC = true;
+/** The npm package that carries the one Shardflux app for this Mac's CPU (it replaces @shardflux/menubar-darwin). */
+export declare const desktopDarwinPackage: (arch?: string) => string;
+/** The npm package that carries the macOS app this CLI installs and updates (see ONE_APP_ON_MAC). */
+export declare const macAppPackage: (arch?: string) => string;

package/dist/mac-app.js

@@ -0,0 +1,11 @@
+/**
+ * Which macOS app this CLI installs and updates. On (0.27.0+): the one Shardflux app from
+ * @shardflux/desktop-darwin-<arch>, which replaces the menu bar app (@shardflux/menubar-darwin) in place. The CLI's
+ * optionalDependencies carry the same packages (test/one-app.test.ts keeps the two in step): with the desktop package
+ * in the install, `shard`, its refresh and the running menu bar app's self-update replace the menu bar app with it.
+ */
+export const ONE_APP_ON_MAC = true;
+/** The npm package that carries the one Shardflux app for this Mac's CPU (it replaces @shardflux/menubar-darwin). */
+export const desktopDarwinPackage = (arch = process.arch) => `@shardflux/desktop-darwin-${arch === 'x64' ? 'x64' : 'arm64'}`;
+/** The npm package that carries the macOS app this CLI installs and updates (see ONE_APP_ON_MAC). */
+export const macAppPackage = (arch = process.arch) => ONE_APP_ON_MAC ? desktopDarwinPackage(arch) : '@shardflux/menubar-darwin';

package/dist/main.js

@@ -137,6 +137,8 @@ function hintFor(info, cred, file, command = '') {
         const current = typeof info.details?.current_revision === 'string' ? info.details.current_revision : 'unknown';
         return `the file changed since that revision (current revision: ${current}); read it again, then retry with --expected-revision ${current}`;
     }
+    if (reason === 'workspace_disk_full' || info.code === 'workspace_disk_full')
+        return 'free space with shard files delete <id|key> <path>, or run a cleanup command; retry the write after space is available';
     if (reason === 'edit_not_found')
         return `--old${index} does not occur in the file (it must match exactly, including whitespace)`;
     if (reason === 'edit_ambiguous')

package/dist/menubar.d.ts

@@ -30,12 +30,6 @@ export declare function compareAppVersions(left: string, right: string): number;
 export declare const SELF_UPDATING_APP = "0.3.2";
 /** CFBundleShortVersionString of a Shardflux app from its XML Info.plist, read without any tool (null: not readable). */
 export declare function plistVersion(app: string): string | null;
-/**
- * Whether any of these processes shows a window: the menu, the launcher, Settings, onboarding, an approval. The status
- * item itself (a strip at the top of the screen on the status layer, owned by the app before macOS 26) does not count.
- * Null when the probe could not answer: then nothing may be replaced.
- */
-export declare function windowsOpen(text: string): boolean | null;
 export declare function parseNativeStatus(text: string): NativeStatus;
 /**
  * The app's executables keep their execute permission (0.13.6+). @shardflux/menubar-darwin 0.1.1 and 0.1.2 reached npm
@@ -56,17 +50,15 @@ export declare class MenubarManager {
     get platform(): NodeJS.Platform;
     /** The version of the app this CLI's npm package carries (what `start` installs). */
     packagedVersion(): Promise<string>;
-    /** Whether the app shows any window (see windowsOpen); null when that could not be read. */
-    windowsOpen(pids: number[]): Promise<boolean | null>;
     status(configDir?: string): Promise<MenubarStatus>;
     stop(configDir?: string): Promise<MenubarStatus>;
     login(value: 'on' | 'off', configDir?: string): Promise<MenubarStatus>;
     start(configDir: string, apiUrl: string): Promise<MenubarStatus>;
     /**
      * Brings an installed app up to the one this CLI's npm package carries, without disturbing the person: nothing when
-     * the versions are equal (each swap of an ad-hoc signed app costs its privacy grants), the copy on disk alone when it
-     * is not running, and a running app only when it shows no window and no `shard update` runs. A running app that
-     * swaps itself in (SELF_UPDATING_APP or later) is left to do so: it also knows when it is in the middle of something.
+     * the versions are equal, the copy on disk alone when it is not running. A running app swaps itself in when it is
+     * idle (every app from SELF_UPDATING_APP on: the menu bar app, and the one Shardflux app that replaces it, which runs
+     * `shard menubar start` when nothing is open); an older running one is restarted unless a `shard update` runs.
      */
     refresh(configDir: string, apiUrl: string): Promise<{
         result: 'current' | 'not_installed' | 'installed' | 'restarted' | 'deferred' | 'busy';
@@ -79,8 +71,21 @@ export declare class MenubarManager {
 export declare function ensureMenubar(dir: string, apiUrl: string, manager?: MenubarManager, platform?: NodeJS.Platform): Promise<string | undefined>;
 /** How often a command may start a background refresh while the app is busy (a window open). */
 export declare const REFRESH_RETRY_MS: number;
-/** Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. */
-export declare function packagedAppPath(): string | null;
+/**
+ * Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. The links npm
+ * leaves out of the package are put back first (restorePackagedAppLinks), so the path is the complete, signed app.
+ */
+export declare function packagedAppPath(arch?: string): string | null;
+/**
+ * Puts back the symbolic links of the package's Shardflux.app that npm leaves out of a package (0.27.0+): an Electron
+ * app's frameworks are made of them (Versions/Current -> A, ...), and without them the app neither starts nor verifies.
+ * The package lists them in links.json; its postinstall restores them too, but pnpm and bun skip install scripts. Only
+ * relative links inside the app; a path that exists is left as it is. `missing`: links that could not be created.
+ */
+export declare function restorePackagedAppLinks(packageDir: string): {
+    restored: string[];
+    missing: string[];
+};
 export interface BackgroundRefreshOptions {
     dir: string;
     home: string;

package/dist/menubar.js

@@ -1,15 +1,16 @@
 import { desktopAccount } from "./desktop-account.js";
 import { execFile, spawn } from 'node:child_process';
-import { chmodSync, closeSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { chmodSync, closeSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, writeSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join, resolve as resolvePath, sep } from 'node:path';
 import { promisify } from 'node:util';
 import { compareVersions } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { LinuxDesktopManager, linuxDesktopPackage } from "./desktop-linux.js";
+import { macAppPackage } from "./mac-app.js";
 const execute = promisify(execFile);
 /**
  * Every native tool a default MenubarManager runs (plutil, codesign, xattr, open, the app's --control) goes through
@@ -56,35 +57,6 @@ export function plistVersion(app) {
         return null;
     }
 }
-const WINDOW_PROBE = `ObjC.import('CoreGraphics');
-function run(argv) {
-  const pids = argv.map(Number);
-  const list = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo($.kCGWindowListOptionOnScreenOnly, $.kCGNullWindowID))) || [];
-  return JSON.stringify(list.filter(w => pids.includes(w.kCGWindowOwnerPID)).map(w => ({ pid: w.kCGWindowOwnerPID, layer: w.kCGWindowLayer,
-    x: w.kCGWindowBounds.X, y: w.kCGWindowBounds.Y, width: w.kCGWindowBounds.Width, height: w.kCGWindowBounds.Height, alpha: w.kCGWindowAlpha })));
-}`;
-/**
- * Whether any of these processes shows a window: the menu, the launcher, Settings, onboarding, an approval. The status
- * item itself (a strip at the top of the screen on the status layer, owned by the app before macOS 26) does not count.
- * Null when the probe could not answer: then nothing may be replaced.
- */
-export function windowsOpen(text) {
-    let rows;
-    try {
-        rows = JSON.parse(text);
-    }
-    catch {
-        return null;
-    }
-    if (!Array.isArray(rows))
-        return null;
-    const windows = rows;
-    if (!windows.every(w => w && typeof w === 'object' && ['layer', 'y', 'width', 'height'].every(k => typeof w[k] === 'number')))
-        return null;
-    // A status item is a strip on the status layer at the top of the screen (39 pt high on a notched display).
-    const statusItem = (w) => w.layer === 25 && w.y <= 0 && w.height <= 50;
-    return windows.some(w => w.layer >= 0 && !statusItem(w) && (w.alpha ?? 1) > 0 && w.width > 1 && w.height > 1);
-}
 export function parseNativeStatus(text) {
     const value = JSON.parse(text);
     if (!value || typeof value !== 'object')
@@ -129,6 +101,8 @@ export class MenubarManager {
             const app = packagedAppPath();
             if (!app)
                 throw new UsageError('The macOS app package is missing. Reinstall shard with optional dependencies enabled, then run shard menubar start.');
+            if (restorePackagedAppLinks(dirname(app)).missing.length)
+                throw new UsageError(`The Shardflux app in ${dirname(app)} is incomplete and that folder is not writable. Reinstall shard (npm i -g shardflux), then run shard.`);
             return app;
         });
     }
@@ -150,17 +124,6 @@ export class MenubarManager {
         compareBundleVersions(version, version);
         return version;
     }
-    /** Whether the app shows any window (see windowsOpen); null when that could not be read. */
-    async windowsOpen(pids) {
-        if (!pids.length)
-            return false;
-        try {
-            return windowsOpen(await this.#run('/usr/bin/osascript', ['-l', 'JavaScript', '-e', WINDOW_PROBE, ...pids.map(String)]));
-        }
-        catch {
-            return null;
-        }
-    }
     /**
      * The app's --control for `configDir`: its pids are the app running for that config directory, wherever it runs from
      * (menu bar 0.8.4+, one app per config directory), and any app running from the installed bundle.
@@ -213,7 +176,9 @@ export class MenubarManager {
         const staged = join(stage, 'Shardflux.app'), backup = join(stage, 'previous.app');
         let committed = false, restored = false;
         try {
-            cpSync(source, staged, { recursive: true, dereference: false });
+            // Relative symlinks stay relative (an app's frameworks are made of them): Node's default rewrites them to absolute
+            // paths into the npm package, which breaks the bundle's seal and its helpers (0.27.0+).
+            cpSync(source, staged, { recursive: true, dereference: false, verbatimSymlinks: true });
             if (current.running)
                 await this.stop(configDir);
             if (current.installed)
@@ -265,9 +230,9 @@ export class MenubarManager {
     }
     /**
      * Brings an installed app up to the one this CLI's npm package carries, without disturbing the person: nothing when
-     * the versions are equal (each swap of an ad-hoc signed app costs its privacy grants), the copy on disk alone when it
-     * is not running, and a running app only when it shows no window and no `shard update` runs. A running app that
-     * swaps itself in (SELF_UPDATING_APP or later) is left to do so: it also knows when it is in the middle of something.
+     * the versions are equal, the copy on disk alone when it is not running. A running app swaps itself in when it is
+     * idle (every app from SELF_UPDATING_APP on: the menu bar app, and the one Shardflux app that replaces it, which runs
+     * `shard menubar start` when nothing is open); an older running one is restarted unless a `shard update` runs.
      */
     async refresh(configDir, apiUrl) {
         this.#requireMac();
@@ -280,7 +245,7 @@ export class MenubarManager {
         if (current.running) {
             if (compareAppVersions(from, SELF_UPDATING_APP) >= 0)
                 return { result: 'deferred', from, to };
-            if (updateRunning(configDir) || (await this.windowsOpen(current.pids)) !== false)
+            if (updateRunning(configDir))
                 return { result: 'busy', from, to };
             await this.start(configDir, apiUrl);
             return { result: 'restarted', from, to };
@@ -332,14 +297,59 @@ const REFRESH_MARK = 'menubar-refresh.json';
 const REFRESH_LOCK = 'menubar-refresh.lock';
 /** How often a command may start a background refresh while the app is busy (a window open). */
 export const REFRESH_RETRY_MS = 5 * 60_000;
-/** Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. */
-export function packagedAppPath() {
+/**
+ * Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. The links npm
+ * leaves out of the package are put back first (restorePackagedAppLinks), so the path is the complete, signed app.
+ */
+export function packagedAppPath(arch = process.arch) {
+    let dir;
     try {
-        return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');
+        dir = dirname(createRequire(import.meta.url).resolve(`${macAppPackage(arch)}/package.json`));
     }
     catch {
         return null;
     }
+    restorePackagedAppLinks(dir);
+    return join(dir, 'Shardflux.app');
+}
+/**
+ * Puts back the symbolic links of the package's Shardflux.app that npm leaves out of a package (0.27.0+): an Electron
+ * app's frameworks are made of them (Versions/Current -> A, ...), and without them the app neither starts nor verifies.
+ * The package lists them in links.json; its postinstall restores them too, but pnpm and bun skip install scripts. Only
+ * relative links inside the app; a path that exists is left as it is. `missing`: links that could not be created.
+ */
+export function restorePackagedAppLinks(packageDir) {
+    const restored = [], missing = [];
+    let spec;
+    try {
+        spec = JSON.parse(readFileSync(join(packageDir, 'links.json'), 'utf8'));
+    }
+    catch {
+        return { restored, missing };
+    }
+    const app = join(packageDir, 'Shardflux.app');
+    const links = spec.links;
+    for (const entry of Array.isArray(links) ? links : []) {
+        const [path, target] = Array.isArray(entry) ? entry : [];
+        if (typeof path !== 'string' || typeof target !== 'string' || !path || !target || isAbsolute(path) || isAbsolute(target))
+            continue;
+        const at = resolvePath(app, path);
+        if (!at.startsWith(app + sep) || !resolvePath(dirname(at), target).startsWith(app + sep))
+            continue;
+        try {
+            lstatSync(at);
+            continue;
+        }
+        catch { /* missing: put it back */ }
+        try {
+            symlinkSync(target, at);
+            restored.push(path);
+        }
+        catch {
+            missing.push(path);
+        }
+    }
+    return { restored, missing };
 }
 /**
  * Every `shard` command (0.15.2+): when the npm package carries a newer app than the installed one (two Info.plist

package/dist/orchestrator-args.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Your orchestrator's command table (0.27.0+, SDK 0.29.0): `shard orchestrator say|list|retry|dismiss`, and `restore`
+ * (0.28.0+, SDK 0.30.0). Pure data like
+ * args.ts, which merges it into COMMANDS; orchestrator-commands.ts has the handlers.
+ */
+import type { CommandSpec } from './args.js';
+export declare const ORCHESTRATOR_COMMANDS: CommandSpec[];

package/dist/orchestrator-args.js

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

package/dist/orchestrator-commands.d.ts

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