@shardflux/cli 0.24.1 → 0.28.0

package/dist/land.js

@@ -0,0 +1,284 @@
+/**
+ * Landing a result for real (0.25.0+): `shard task land <task>` and `shard conversations land <id> merge`.
+ *
+ * A board task has one result: its master merges its workers' branches into shard/<task id> on the project hub before it
+ * seals done (a master that did not is helped here: its workers' branches are merged into it when they merge cleanly).
+ * Landing then
+ *   1. merges the result into the project's default branch on the hub, in a VM of the project (task-land-hub.py): a
+ *      fast-forward, or a merge commit when the merge is clean, never by force; and checks there that the result
+ *      commit is contained in the branch;
+ *   2. brings it into the person's linked folder on this computer through the live twin's own landing
+ *      (worktree-twin.ts landingRound from the hub): the branch moves to the new commits, uncommitted edits stay, every
+ *      rewritten file is backed up first, and a Git operation in progress or a file being edited waits;
+ *   3. only then records it (POST /v1/tasks/{id}/land with the commit; for a conversation POST /land merge into the
+ *      branch). A conflict changes nothing: the task's master is asked to merge (a steer) and nothing is recorded.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+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;
+/** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
+export function hubScript() { return script ??= readFileSync(new URL('./task-land-hub.py', import.meta.url), 'utf8'); }
+/** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
+export async function landOnHub(cell, input, signal) {
+    const body = { hub: input.hub ?? HUB_PATH, result: input.result, sources: input.sources, title: input.title, ...(input.into ? { default: input.into } : {}) };
+    const r = await cell.exec.run(['python3', '-c', hubScript()], { stdin: JSON.stringify(body), timeoutMs: 300_000, maxOutputBytes: 1 << 20, ...(signal ? { signal } : {}) });
+    const line = r.stdout.trim().split('\n').at(-1) ?? '';
+    if (r.exitCode !== 0 || !line.startsWith('{'))
+        return { state: 'error', into: input.into ?? '', reason: 'script', message: `the landing script exited ${r.exitCode}: ${r.stderr.trim().slice(-400)}` };
+    return JSON.parse(line);
+}
+/** The branch to land in: the one checked out in the folder, else the hub's default branch when the folder has it. */
+export async function folderBranch(folder, fallback) {
+    const info = await inspectWorktree(folder);
+    const own = info.branch?.replace(/^refs\/heads\//, '');
+    if (own && !own.startsWith('shard/'))
+        return own;
+    const has = await git(folder, ['rev-parse', '-q', '--verify', `refs/heads/${fallback}^{commit}`], { ok: [0, 1, 128] });
+    return has.code === 0 ? fallback : null;
+}
+/**
+ * The result into the folder through the twin's landing (from the hub): the branch moves, the person's uncommitted
+ * edits stay, and the landed commit is checked to be on the branch.
+ */
+export async function landInFolder(cell, f) {
+    const deadline = Date.now() + (f.patienceMs ?? 20_000);
+    const target = (await listWorktrees(f.folder)).find(w => w.branch === `refs/heads/${f.into}`);
+    const repo = target?.root ?? f.folder;
+    for (let attempt = 0;; attempt++) {
+        const worktree = target ? await inspectWorktree(target.root) : null;
+        const o = await landingRound(cell, {
+            conversation: { id: f.name, name: f.name, title: f.title, summary: '', branch: f.branch, base_commit: f.base, worktree_path: '' },
+            into: f.into, mode: 'auto', device: f.device, repo, worktree, stateDir: f.stateDir, backupRoot: backupRoot(f.stateDir), fromHub: {},
+            ...(f.hub ? { hub: f.hub } : {}), ...(f.quietMs !== undefined ? { quietMs: f.quietMs } : {}), ...(f.signal ? { signal: f.signal } : {}),
+        });
+        const tip = async () => gitText(repo, ['rev-parse', `refs/heads/${f.into}`]);
+        switch (o.state) {
+            case 'landed': {
+                await o.confirmed.catch(() => undefined);
+                const landed = o.land.tip, now = await tip();
+                const on = await git(repo, ['merge-base', '--is-ancestor', landed, `refs/heads/${f.into}`], { ok: [0, 1] });
+                if (on.code !== 0)
+                    throw new CodedError('land_unverified', `${f.into} in ${f.folder} does not contain the landed commit ${landed.slice(0, 7)}.`);
+                return { path: f.folder, into: f.into, state: 'landed', sha: now, method: o.land.method ?? 'landed', files: o.applied.files.length, kept: o.applied.raced, backup: o.applied.backup };
+            }
+            case 'noop': return { path: f.folder, into: f.into, state: 'already', sha: await tip() };
+            case 'conflict': return { path: f.folder, into: f.into, state: 'conflict', conflicts: o.land.conflicts ?? [] };
+            case 'error': throw new CodedError('land_failed', `Could not land into ${f.folder}: ${o.land.message ?? o.land.reason ?? 'the landing failed'}.`);
+            case 'pr':
+            case 'deferred': return { path: f.folder, into: f.into, state: 'waiting', reason: o.state };
+            default: {
+                // paused (a Git operation), moved (the branch or a file changed while landing), busy (a file just saved).
+                const wait = o.state === 'busy' ? Math.min(o.waitMs ?? 1000, 3000) : o.state === 'moved' ? 200 : 1000;
+                if (Date.now() + wait > deadline || attempt >= 20)
+                    return { path: f.folder, into: f.into, state: 'waiting', reason: o.reason };
+                await delay(wait, undefined, f.signal ? { signal: f.signal } : {});
+            }
+        }
+    }
+}
+/** 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)
+        return own;
+    // A folder linked with `shard projects link` belongs to the signed-in project until its preparation names one.
+    const profile = ctx.store.profile(ctx.apiUrl), mine = profile.project_id ?? profile.api_key?.project_id;
+    const linked = selectedProjects(ctx).filter(p => (p.project_id ?? mine) === projectId).map(p => repo(p.folder)).find(Boolean);
+    if (linked)
+        return linked;
+    return Object.values(records).filter(r => r.project_id === projectId).map(r => repo(r.folder)).find(Boolean) ?? null;
+}
+export const displayPath = (path) => { const home = homedir(); return path === home ? '~' : path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path; };
+const short = (sha) => (sha ?? '').slice(0, 7);
+const list = (files) => files.length > 4 ? `${files.slice(0, 4).join(', ')} and ${files.length - 4} more` : files.join(', ');
+function message(o) {
+    const f = o.folder;
+    if (f && (f.state === 'landed' || f.state === 'already'))
+        return `Landed in ${f.display} · ${short(f.sha)}`;
+    const hub = `Landed in ${o.hub.into} on the project hub · ${short(o.hub.sha)}`;
+    if (f?.state === 'conflict')
+        return `${hub}. Not in ${f.display}: your commits on ${f.into} change ${list(f.conflicts ?? [])} too.`;
+    if (f?.state === 'waiting')
+        return `${hub}. ${f.display} gets it once it is not busy (${f.reason ?? 'busy'}).`;
+    return hub;
+}
+export function landDeps(ctx) {
+    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) {
+    const vm = await d.hubCell(l.projectId);
+    try {
+        const input = { result: l.result, sources: l.sources.map(s => s.branch), title: l.title, ...(d.hub ? { hub: d.hub } : {}) };
+        let hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'raced')
+            hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'conflict') {
+            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')
+            throw new CodedError('land_failed', `Could not land on the project hub: ${hub.message ?? hub.reason ?? hub.state}.`, 'try again in a moment', { stage: hub.stage ?? null });
+        const contained = l.sources.filter(s => hub.contained?.includes(s.branch)).map(s => s.conversation_id);
+        let folder = null;
+        if (l.folder) {
+            const into = await folderBranch(l.folder, hub.into);
+            if (!into)
+                folder = { path: l.folder, display: displayPath(l.folder), into: hub.into, state: 'skipped', reason: 'detached' };
+            else {
+                const f = await landInFolder(vm.cell, { folder: l.folder, into, name: l.name, title: l.title, branch: l.result, base: l.base ?? hub.merge_base ?? hub.before ?? hub.result,
+                    device: d.device, stateDir: d.stateDir, ...(d.hub ? { hub: d.hub } : {}), ...(d.quietMs !== undefined ? { quietMs: d.quietMs } : {}), ...(d.signal ? { signal: d.signal } : {}) });
+                folder = { ...f, display: displayPath(f.path) };
+            }
+        }
+        return { title: l.title, result: { branch: l.result, sha: hub.result }, hub: { into: hub.into, sha: hub.after, method: hub.method }, folder, contained };
+    }
+    finally {
+        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`}`;
+}
+const recordFailure = (error) => {
+    const e = error;
+    return e.status === 404 ? 'this API does not record task landings yet' : (e.message ?? String(error));
+};
+/** The task's current result: its master's latest final report, when it is done. */
+function currentResult(d) {
+    const own = d.task.master_id ? d.reports.filter(r => r.author_id === d.task.master_id) : d.reports;
+    const final = [...own].reverse().find(r => r.milestone === 'done' || r.milestone === 'failed' || r.milestone === 'planned');
+    return final?.milestone === 'done' ? final.id : null;
+}
+const resultBranch = (taskId) => `shard/${taskId}`;
+/** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
+export async function landTask(d, taskId, opts = {}) {
+    const client = d.client, signal = d.signal ? { signal: d.signal } : {};
+    const detail = await client.tasks.get(taskId, signal);
+    const task = detail.task, title = task.title ?? task.text.split('\n')[0].slice(0, 80);
+    const report = currentResult(detail);
+    if (!report || (task.state !== 'done' && task.state !== 'unverified'))
+        throw new CodedError('task_not_done', 'This task has no finished result to land yet.', 'land it after its master’s done report', { state: task.state });
+    const workers = [];
+    for (const c of task.conversations) {
+        if (c.role === 'master' || c.role === 'reviewer')
+            continue;
+        const w = await client.conversations.get(c.id);
+        if (w.join_mode !== 'reviewer' && (w.changes?.commits ?? 0) > 0 && w.landed?.how !== 'discarded')
+            workers.push(w);
+    }
+    // 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, 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);
+    });
+    let recorded = false, record_error;
+    try {
+        await client.tasks.recordLanding(taskId, { sha: done.result.sha, into: done.hub.into, branch: done.result.branch, reportId: report, conversationIds: done.contained }, signal);
+        recorded = true;
+    }
+    catch (error) {
+        record_error = recordFailure(error);
+        // An API without task landings (before train 41) keeps a land item per worker: the workers whose branches are in
+        // the landed commit are recorded as merged into the branch, which is true, so those items go.
+        if (error.status === 404 && done.contained.length) {
+            let all = true;
+            for (const id of done.contained) {
+                try {
+                    await client.conversations.land(id, 'merge', { into: done.hub.into, ...signal });
+                }
+                catch {
+                    all = false;
+                }
+            }
+            if (all) {
+                recorded = true;
+                record_error = undefined;
+            }
+        }
+    }
+    const { title: t, result, hub, folder: f } = done;
+    const o = { title: t, result, hub, folder: f, landed: true, task_id: taskId, recorded, ...(record_error ? { record_error } : {}) };
+    return { ...o, message: message(o) };
+}
+/** `shard conversations land <id> merge`: the conversation's branch into the default branch and its folder, then recorded. */
+export async function landConversation(d, id, opts = {}) {
+    const client = d.client;
+    const c = await client.conversations.get(id);
+    if (c.changes?.uncommitted)
+        throw new CodedError('uncommitted_changes', 'The conversation has uncommitted changes.', 'ask its agent to commit them, then land');
+    const folder = opts.path ?? d.folder(c.project_id, c.id);
+    const done = await land(d, { projectId: c.project_id, title: c.title || c.branch, name: c.name ?? c.branch.replace(/^shard\//, ''), result: c.branch, sources: [],
+        base: c.base_commit ?? null, folder }, () => Promise.resolve());
+    let recorded = false, record_error;
+    try {
+        await client.conversations.land(id, 'merge', { into: done.hub.into, ...(d.signal ? { signal: d.signal } : {}) });
+        recorded = true;
+    }
+    catch (error) {
+        record_error = recordFailure(error);
+    }
+    const { title: t, result, hub, folder: f } = done;
+    const o = { title: t, result, hub, folder: f, landed: true, conversation_id: id, recorded, ...(record_error ? { record_error } : {}) };
+    return { ...o, message: message(o) };
+}

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

@@ -66,7 +66,11 @@ function hintFor(info, cred, file, command = '') {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'operation_failed' && info.retryable) {
-        return info.details?.error_code === 'capacity_unavailable' ? 'nothing was started; run the same command again' : 'the operation may succeed if you retry it later.';
+        if (info.details?.error_code === 'capacity_unavailable') {
+            const retry = info.details.retry_after_seconds;
+            return `nothing was started; run the same command again${typeof retry === 'number' && retry > 0 ? ` after ${retry} s` : ''}`;
+        }
+        return 'the operation may succeed if you retry it later.';
     }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
@@ -133,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')
@@ -175,6 +181,8 @@ function allowanceHint(info) {
     const resets = typeof info.details?.resets_at === 'string' ? ` (the period resets ${time(info.details.resets_at)})` : '';
     switch (info.details?.reason) {
         case 'allowance_used':
+            if (info.details?.spend_cap === null)
+                return 'choose a paid plan: shard billing plans; overage is unavailable on the current plan';
             return `upgrade (shard billing plans), or turn on overage: shard billing overage on --cap <dollars>${resets}`;
         case 'spend_cap_reached':
             return `the spend cap is reached: raise it (shard billing overage cap <dollars>, at most the plan price) or upgrade${resets}`;

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/onboarding.d.ts

@@ -111,7 +111,7 @@ export declare function onboardingReport(ctx: Ctx, values: Values, platform?: No
         };
         conversation: {
             id: string;
-            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
             summary: string;
         } | null;
         commands: never[];
@@ -142,7 +142,7 @@ export declare function onboardingReport(ctx: Ctx, values: Values, platform?: No
         };
         conversation: {
             id: string;
-            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
             summary: string;
         } | null;
         commands: string[];
@@ -195,7 +195,7 @@ export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
     };
     conversation: {
         id: string;
-        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
         summary: string;
     } | null;
     commands: never[];
@@ -226,7 +226,7 @@ export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
     };
     conversation: {
         id: string;
-        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
         summary: string;
     } | null;
     commands: string[];

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[];