@shardflux/cli 0.25.0 → 0.28.1

package/dist/device-mode.js

@@ -0,0 +1,119 @@
+/**
+ * How this computer answers its own agents (0.27.0+): the person chooses once, per device, whether their agents run
+ * things here without asking each time. Kept in `<config>/device-settings.json`; changed in the app's Settings or with
+ * `shard device approvals auto|read|ask`. Requests that ran without asking are kept in `<config>/device-activity.jsonl`
+ * (what ran, for which conversation, and how it ended), shown by the app and `shard device approvals`.
+ *
+ * - `ask`: every request asks (Allow once, or Always where a grant applies).
+ * - `read`: listing a folder and copying a file to a conversation run without asking; anything that changes this
+ *   computer (commands, files saved here, ports, linking a folder) asks. Commands are never classified by their text.
+ * - `auto`: every request from this person's own agents runs without asking.
+ *
+ * Only this person's own conversations run without asking (`ownConversation`): a teammate's request always asks.
+ */
+import { appendFileSync, lstatSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writePrivateFile, ensurePrivateDir } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { thisComputer } from "./this-computer.js";
+export const DEVICE_APPROVAL_MODES = ['auto', 'read', 'ask'];
+/**
+ * The mode before the person chooses one. `undefined`: nothing is decided for them; the first request asks which they
+ * want (the app's prompt, or one line from `shard`), and the app's onboarding asks too. 'auto' or 'ask' here chooses
+ * for everyone who has not.
+ */
+export const DEFAULT_DEVICE_APPROVALS = undefined;
+/** The kinds that only read this computer: a folder listing, and a file copied to the conversation. */
+export const READ_KINDS = new Set(['dir_list', 'files_pull']);
+export const MODE_LABELS = {
+    auto: 'Allow everything from my agents',
+    read: 'Allow reading, ask before changes',
+    ask: 'Ask every time',
+};
+/** The one line a person without the app reads when a request needs the choice ("this Mac" on macOS). */
+export const chooseLine = (platform = process.platform) => `Let your agents run things on ${thisComputer(platform)} without asking each time? Allow everything: shard device approvals auto · Ask each time: shard device approvals ask`;
+const SETTINGS = 'device-settings.json', ACTIVITY = 'device-activity.jsonl';
+export function readDeviceSettings(dir) {
+    const file = join(dir, SETTINGS);
+    try {
+        if (lstatSync(file).isSymbolicLink() || (statSync(file).mode & 0o077))
+            return {};
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        return DEVICE_APPROVAL_MODES.includes(value.approvals) ? value : { ...value, approvals: undefined };
+    }
+    catch {
+        return {};
+    }
+}
+/** This person's mode on this computer; undefined until they choose one (and DEFAULT_DEVICE_APPROVALS is unset). */
+export function deviceApprovalMode(dir, userId) {
+    const s = readDeviceSettings(dir);
+    if (s.approvals && !(s.user_id && userId && s.user_id !== userId))
+        return s.approvals;
+    return DEFAULT_DEVICE_APPROVALS;
+}
+export function setDeviceApprovalMode(dir, mode, userId) {
+    if (!DEVICE_APPROVAL_MODES.includes(mode))
+        throw new UsageError(`Unknown approval mode "${mode}": auto, read or ask.`);
+    const next = { ...readDeviceSettings(dir), approvals: mode, chosen_at: new Date().toISOString() };
+    if (userId)
+        next.user_id = userId;
+    else
+        delete next.user_id;
+    writePrivateFile(dir, join(dir, SETTINGS), JSON.stringify(next, null, 2) + '\n');
+    return next;
+}
+/** Whether a request of this kind runs without asking under this mode (for the person's own agents). */
+export function runsWithoutAsking(mode, kind) {
+    return mode === 'auto' || (mode === 'read' && READ_KINDS.has(kind));
+}
+const ACTIVITY_MAX_BYTES = 512 << 10, ACTIVITY_KEEP = 400;
+export function recordDeviceActivity(dir, entry) {
+    const file = join(dir, ACTIVITY);
+    try {
+        ensurePrivateDir(dir);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+        }
+        catch { /* first entry */ }
+        if (size > ACTIVITY_MAX_BYTES) {
+            const keep = readFileSync(file, 'utf8').split('\n').filter(Boolean).slice(-ACTIVITY_KEEP);
+            writePrivateFile(dir, file, keep.join('\n') + '\n');
+        }
+        appendFileSync(file, JSON.stringify(entry) + '\n', { mode: 0o600 });
+    }
+    catch { /* the request's own result still reaches its conversation */ }
+}
+/** What ran without asking, newest first: one entry per request with its latest state. */
+export function deviceActivity(dir, limit = 20) {
+    let text;
+    try {
+        if (lstatSync(join(dir, ACTIVITY)).isSymbolicLink())
+            return [];
+        text = readFileSync(join(dir, ACTIVITY), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of text.split('\n')) {
+        if (!line)
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!e || typeof e.request_id !== 'string')
+            continue;
+        const had = byId.get(e.request_id);
+        byId.delete(e.request_id);
+        byId.set(e.request_id, had ? { ...had, ...e, at: had.at, ...(e.state !== 'running' ? { finished_at: e.at } : {}) } : e);
+    }
+    return [...byId.values()].reverse().slice(0, limit);
+}

package/dist/drive-commands.d.ts

@@ -14,8 +14,8 @@ export interface ProjectScope {
  * `needId` false leaves the key's project unnamed (the API defaults to it), saving a lookup.
  */
 export declare function projectScope(ctx: Ctx, values: Values, needId?: boolean): Promise<ProjectScope>;
-/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
-export declare function driveTable(rows: readonly DriveFile[]): string;
+/** `drive ls` and `brain ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+export declare function driveTable(rows: readonly Pick<DriveFile, 'size' | 'created_at' | 'content_type' | 'path'>[]): string;
 /**
  * The model template as people read it: the primary provider and why, the connected accounts, then one row per role
  * with what it runs and, for a role whose provider is out of usage, until when it waits and what the other provider

package/dist/drive-commands.js

@@ -51,7 +51,7 @@ function drivePath(path, what = 'drive path') {
     }
     return path;
 }
-/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+/** `drive ls` and `brain ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
 export function driveTable(rows) {
     return table(['SIZE', 'SAVED', 'TYPE', 'PATH'], rows.map((f) => [humanBytes(f.size), time(f.created_at), f.content_type, f.path]));
 }

package/dist/format.js

@@ -83,6 +83,8 @@ export function workspaceState(w) {
         tags.push('session');
     if (w.deleted_at)
         tags.push(w.ended_reason ? `ended: ${w.ended_reason}` : 'deleted');
+    if (w.storage_recovery)
+        tags.push('files stored');
     return tags.length ? `${w.observed_state} (${tags.join(', ')})` : w.observed_state;
 }
 export function workspaceRow(w) {
@@ -230,6 +232,7 @@ export function workspaceDetail(w) {
         ['id', w.id],
         ['key', w.workspace_key],
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
+        ...(w.storage_recovery ? [['storage', w.storage_recovery.message]] : []),
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
         // Immutable paths (0.8.0): the template version whose immutable paths the workspace has mounted, when it has one.

package/dist/forwarder-refresh.d.ts

@@ -0,0 +1,15 @@
+import type { ProgramRunner } from './cli-proxy.js';
+export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+export declare function forwarderPlistPath(home: string): string;
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+export declare function recordForwarder(dir: string): void;
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
+    run?: ProgramRunner;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;

package/dist/forwarder-refresh.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+import { CLI_VERSION } from "./args.js";
+export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+export function forwarderPlistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
+}
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+export function recordForwarder(dir) {
+    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
+}
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export async function refreshForwarderAgent(env, dir, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'darwin')
+        return false;
+    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
+        return false;
+    const store = new AgentStateStore(dir);
+    const record = store.read().cli_proxy_forwarder;
+    if (record?.version === CLI_VERSION)
+        return false;
+    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
+    recordForwarder(dir);
+    await (deps.run ?? (await import("./cli-proxy.js")).cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
+    return true;
+}

package/dist/handler-loader.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from './commands.js';
+export declare const HANDLER_PATHS: string[];
+export declare function handlerFor(path: string): Promise<Handler | undefined>;

package/dist/handler-loader.js

@@ -0,0 +1,43 @@
+// Exact command ownership, in the same override order as HANDLERS. The parity test catches additions
+// or moves without loading every command module during an ordinary command.
+const groups = [
+    [["projects sync list", "projects sync add", "projects sync pause", "projects sync remove", "projects sync run"], async () => (await import("./project-preparation.js")).PROJECT_PREPARATION_HANDLERS],
+    [["projects link"], async () => (await import("./device-folders.js")).PROJECT_LINK_HANDLERS],
+    [["move"], async () => (await import("./move.js")).MOVE_HANDLERS],
+    [["device approvals", "device requests", "device approve", "device deny"], async () => (await import("./device-approvals.js")).DEVICE_HANDLERS],
+    [["agents codex status", "agents codex enable", "agents codex disable"], async () => (await import("./codex-cloud.js")).CODEX_CLOUD_HANDLERS],
+    [["cli-proxy", "cli-proxy import", "cli-proxy export", "cli-proxy use", "cli-proxy forward"], async () => (await import("./cli-proxy.js")).CLI_PROXY_HANDLERS],
+    [["agents computers"], async () => (await import("./thread-on-computer.js")).THREAD_HANDLERS],
+    [["conversations resume", "conversations reader", "conversations list", "conversations feed", "conversations get", "conversations permissions", "conversations answer", "conversations watch", "conversations send", "conversations start", "conversations wait", "conversations land", "files pull", "conversations move", "conversations archive", "conversations unarchive", "conversations seen", "conversations delete"], async () => (await import("./conversation-commands.js")).CONVERSATION_HANDLERS],
+    [["orchestrator say", "orchestrator list", "orchestrator retry", "orchestrator dismiss", "orchestrator restore"], async () => (await import("./orchestrator-commands.js")).ORCHESTRATOR_HANDLERS],
+    [["board", "task add", "task show", "task edit", "task rm", "task steer", "task land", "task clear-done", "needs-you", "needs-you answer", "approvals", "approvals set", "approvals allow", "approvals remove"], async () => (await import("./board-commands.js")).BOARD_HANDLERS],
+    [["conversations transcript", "conversations events"], async () => (await import("./conversation-transcript.js")).TRANSCRIPT_HANDLERS],
+    [["conversations try"], async () => (await import("./conversation-local.js")).CONVERSATION_HANDLERS],
+    [["conversations landing"], async () => (await import("./worktree-twin-engine.js")).TWIN_HANDLERS],
+    [["secrets log", "credentials list", "credentials enable", "credentials approve", "credentials deny", "credentials forget"], async () => (await import("./credential-prompts.js")).CREDENTIAL_HANDLERS],
+    [["agents credentials login", "agents credentials sync", "agents credentials status", "agents credentials forget"], async () => (await import("./agent-credentials.js")).AGENT_CREDENTIAL_HANDLERS],
+    [["agents accounts", "agents accounts list", "agents accounts usage", "agents accounts add", "agents accounts remove", "agents accounts use", "accounts", "accounts list", "accounts usage", "accounts add", "accounts remove", "accounts use"], async () => (await import("./account-pool.js")).ACCOUNT_POOL_HANDLERS],
+    [["agents models"], async () => (await import("./account-pool.js")).AGENT_MODELS_HANDLERS],
+    [["agents list", "login", "whoami", "version", "feedback", "usage", "workspaces labels", "workspaces hint", "workspaces idle", "workspaces exec-start", "workspaces tunnel", "workspaces exec-read", "workspaces exec-cancel", "workspaces exec-input", "workspaces retention", "projects retention", "workspaces open", "workspaces list", "workspaces get", "workspaces inputs", "workspaces exec", "files read-many", "files read", "files write", "files delete", "files ls", "files stat", "files search", "files patch", "workspaces suspend", "workspaces resume", "workspaces delete", "workspaces close", "workspaces upgrade", "workspaces reset", "workspaces save-as-template", "workspaces changes", "templates list", "templates get", "templates init", "templates build", "templates export", "templates test", "templates builds list", "templates builds get", "templates builds log", "templates builds cancel", "templates languages", "templates packages search", "templates files", "templates diff", "templates draft open", "templates draft status", "templates draft state", "templates draft test", "templates draft publish", "templates draft discard", "workspaces fork", "workspaces resize", "workspaces sessions", "workspaces port expose", "workspaces port ls", "workspaces port close", "workspaces port token", "workspaces port link", "workspaces port callback", "workspaces computer status", "workspaces computer screenshot", "workspaces computer act", "workspaces computer click", "workspaces computer type", "workspaces computer paste-text", "workspaces computer key", "workspaces computer scroll", "workspaces computer move", "workspaces computer drag", "workspaces computer mouse-down", "workspaces computer mouse-up", "workspaces computer hold-key", "workspaces computer wait", "workspaces computer zoom", "workspaces computer cursor", "workspaces computer start", "workspaces computer stop", "workspaces computer stream", "workspaces computer enable", "workspaces computer disable", "workspaces computer inherit", "templates computer-use", "workspaces secrets", "secrets import", "secrets create", "secrets list", "secrets get", "secrets update", "secrets rotate", "secrets versions", "secrets delete", "secrets access-log", "operations list", "operations get", "operations progress", "operations cancel", "operations wait", "executions get"], async () => (await import("./commands.js")).KEY_HANDLERS],
+    [["auth register", "auth verify-email", "auth resend-verification", "auth login", "auth mfa", "auth status", "auth logout", "auth sessions", "auth step-up", "auth password change", "auth password reset", "auth password reset-confirm", "auth email change", "auth email confirm", "auth totp enroll", "auth totp confirm", "auth totp disable", "auth totp recovery-codes", "setup", "signup", "verify", "env", "orgs list", "orgs create", "orgs get", "orgs use", "orgs export", "orgs workspaces", "orgs deletion", "orgs delete", "projects list", "projects create", "projects get", "projects use", "api-keys list", "api-keys create", "api-keys revoke", "members list", "members set-role", "members remove", "invitations list", "invitations create", "invitations revoke", "invitations accept", "billing plans", "billing status", "billing upgrade", "billing portal", "billing invoices", "billing alerts", "billing overage", "audit list", "audit export", "account status", "account export", "account delete", "account cancel-deletion", "egress get", "egress set", "egress history", "egress clear", "volumes list", "status", "volumes open", "volumes create", "volumes get", "volumes delete", "volumes attachments", "volumes attach", "volumes detach", "templates publish", "templates archive"], async () => (await import("./account-commands.js")).ACCOUNT_HANDLERS],
+    [["agents open"], async () => (await import("./agent-commands.js")).AGENT_HANDLERS],
+    [["agents new", "agents fork", "agents park", "agents logs"], async () => (await import("./command-center-actions.js")).CENTER_HANDLERS],
+    [["agents targets", "agents terminal-run", "agents open claude-desktop", "agents open codex-app", "agents open t3", "agents open web", "ssh-proxy"], async () => (await import("./agent-target-commands.js")).TARGET_HANDLERS],
+    [["agents merge", "agents keep", "agents discard", "agents worktree", "agents restore"], async () => (await import("./agent-git-commands.js")).AGENT_GIT_HANDLERS],
+    [["menubar start", "menubar stop", "menubar status", "menubar account"], async () => (await import("./menubar.js")).MENUBAR_HANDLERS],
+    [["machine", "machine open", "machine save", "machine rollback", "template", "template save", "template rollback", "template delete"], async () => (await import("./filesystem-commands.js")).FILESYSTEM_HANDLERS],
+    [["machine setup"], async () => (await import("./machine-setup.js")).MACHINE_SETUP_HANDLERS],
+    [["settings"], async () => (await import("./client-settings.js")).SETTINGS_HANDLERS],
+    [["update"], async () => (await import("./update.js")).UPDATE_HANDLERS],
+    [["agents config-sync"], async () => (await import("./agent-config-sync.js")).AGENT_CONFIG_HANDLERS],
+    [["route", "ask"], async () => (await import("./router-commands.js")).ROUTER_HANDLERS],
+    [["transcribe"], async () => (await import("./transcribe-commands.js")).TRANSCRIBE_HANDLERS],
+    [["drive ls", "drive get", "drive put", "drive rm", "models", "models primary"], async () => (await import("./drive-commands.js")).DRIVE_HANDLERS],
+    [["brain ls", "brain get"], async () => (await import("./brain-commands.js")).BRAIN_HANDLERS],
+];
+const owners = new Map(groups.flatMap(([paths, load]) => paths.map(path => [path, load])));
+export const HANDLER_PATHS = [...owners.keys()];
+export async function handlerFor(path) {
+    const load = owners.get(path);
+    return load ? (await load())[path] : undefined;
+}

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;
@@ -92,11 +97,11 @@ export interface LandDeps {
         tasks: Pick<ReturnType<typeof conversationClient>['tasks'], 'get' | 'recordLanding' | 'steer'>;
         conversations: Pick<ReturnType<typeof conversationClient>['conversations'], 'get' | 'land'>;
     };
-    hubCell(projectId: string): Promise<{
+    hubCell(projectId: string, workspaceIds?: readonly string[]): Promise<{
         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,11 +127,11 @@ 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, ids) => projectHubCell(ctx, p, ctx.signal, 'shard-land', ids), 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);
+    const vm = await d.hubCell(l.projectId, l.workspaceIds);
     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);
@@ -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, workspaceIds: workers.map(w => w.workspace_id).filter(Boolean) }, 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);
     });
@@ -221,9 +267,10 @@ export async function landConversation(d, id, opts = {}) {
     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 repository = c.repo_remote ?? null;
+    const folder = opts.path ?? d.folder(c.project_id, c.id, repository ?? undefined);
     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());
+        base: c.base_commit ?? null, folder, repository, workspaceIds: [c.workspace_id] }, () => Promise.resolve());
     let recorded = false, record_error;
     try {
         await client.conversations.land(id, 'merge', { into: done.hub.into, ...(d.signal ? { signal: d.signal } : {}) });

package/dist/linux-helper.js

@@ -4,7 +4,6 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { CLI_VERSION } from "./args.js";
 import { writePrivateFile } from "./credentials.js";
-import { runDeviceHelper } from "./device-helper.js";
 export const HELPER_UNIT = 'shardflux-helper.service';
 export const helperUnitPath = (home) => join(home, '.config/systemd/user', HELPER_UNIT);
 const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '\\n').replaceAll('\r', '\\r') + '"';
@@ -83,6 +82,6 @@ export function startLinuxHelper(ctx) {
         writePrivateFile(ctx.store.dir, notice, '1\n');
     }
     const abort = new AbortController();
-    const work = runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true }).catch(() => undefined);
+    const work = import("./device-helper.js").then(({ runDeviceHelper }) => runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true })).catch(() => undefined);
     return async () => { abort.abort(); await work; };
 }

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/machine-setup-guard.d.ts

@@ -0,0 +1,9 @@
+import type { Values } from './args.js';
+type Env = Record<string, string | undefined>;
+export declare const SETUP_VM_ENV = "SHARDFLUX_MACHINE_SETUP_VM";
+/**
+ * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
+ * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
+ */
+export declare function setupGuard(env: Env, command: string, values: Values, positionals: string[]): string | undefined;
+export {};

package/dist/machine-setup-guard.js

@@ -0,0 +1,22 @@
+export const SETUP_VM_ENV = 'SHARDFLUX_MACHINE_SETUP_VM';
+/**
+ * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
+ * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
+ */
+export function setupGuard(env, command, values, positionals) {
+    const vm = env[SETUP_VM_ENV]?.trim();
+    if (!vm)
+        return undefined;
+    const allowed = ['workspaces exec', 'files write', 'files read', 'files ls', 'files stat', 'version'];
+    if (!allowed.includes(command))
+        return `machine setup runs only shard ws exec, files write and files read on ${vm}`;
+    if (command === 'version')
+        return undefined;
+    if (positionals[0] !== vm)
+        return `machine setup runs commands only on ${vm}`;
+    if (command === 'files write' && values.from !== undefined && values.from !== '-')
+        return 'machine setup writes files only from standard input (--from -)';
+    if (command === 'files read' && values.out !== undefined)
+        return 'machine setup reads files only to standard output';
+    return undefined;
+}

package/dist/machine-setup.d.ts

@@ -4,8 +4,7 @@ import { AgentStateStore } from './agent-state.js';
 import { type Values } from './args.js';
 export type Runner = 'claude' | 'codex' | 'cloud';
 type Env = Record<string, string | undefined>;
-/** Set for the local agent's processes: the `shard` it runs only reaches this machine VM (see `setupGuard`). */
-export declare const SETUP_VM_ENV = "SHARDFLUX_MACHINE_SETUP_VM";
+export { SETUP_VM_ENV, setupGuard } from './machine-setup-guard.js';
 export declare const DEFAULT_AGENT_TIMEOUT_MS: number;
 export interface ChildResult {
     code: number | null;
@@ -71,11 +70,6 @@ export declare const SECRET_PATHS: readonly ["~/.ssh/**", "~/.aws/**", "~/.azure
 export declare function claudeArgs(key: string, help: string): string[];
 /** `codex exec` argv: writes only in `workDir` (and temp folders), network on for `shard`, the task on standard input. */
 export declare function codexArgs(workDir: string, help: string): string[];
-/**
- * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
- * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
- */
-export declare function setupGuard(env: Env, command: string, values: Values, positionals: string[]): string | undefined;
 export interface Inventory {
     /** The home whose files were inventoried; a local agent's login shell can use a different home. */
     source_home?: string;
@@ -187,4 +181,3 @@ export declare function machineSetup(ctx: Ctx, values: Values, deps?: SetupDeps)
  */
 export declare function startMachineSetupInBackground(ctx: Ctx): boolean;
 export declare const MACHINE_SETUP_HANDLERS: Record<string, Handler>;
-export {};

package/dist/machine-setup.js

@@ -31,7 +31,8 @@ import { progress as stderrProgress } from "./progress.js";
 import { writeProgress } from "./seed-phases.js";
 import { parseDuration } from "./args.js";
 /** Set for the local agent's processes: the `shard` it runs only reaches this machine VM (see `setupGuard`). */
-export const SETUP_VM_ENV = 'SHARDFLUX_MACHINE_SETUP_VM';
+import { SETUP_VM_ENV } from "./machine-setup-guard.js";
+export { SETUP_VM_ENV, setupGuard } from "./machine-setup-guard.js";
 export const DEFAULT_AGENT_TIMEOUT_MS = 10 * 60_000;
 const SAVE_TIMEOUT_MS = 10 * 60_000;
 /**
@@ -228,27 +229,6 @@ export function codexArgs(workDir, help) {
         '-',
     ];
 }
-/**
- * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
- * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
- */
-export function setupGuard(env, command, values, positionals) {
-    const vm = env[SETUP_VM_ENV]?.trim();
-    if (!vm)
-        return undefined;
-    const allowed = ['workspaces exec', 'files write', 'files read', 'files ls', 'files stat', 'version'];
-    if (!allowed.includes(command))
-        return `machine setup runs only shard ws exec, files write and files read on ${vm}`;
-    if (command === 'version')
-        return undefined;
-    if (positionals[0] !== vm)
-        return `machine setup runs commands only on ${vm}`;
-    if (command === 'files write' && values.from !== undefined && values.from !== '-')
-        return 'machine setup writes files only from standard input (--from -)';
-    if (command === 'files read' && values.out !== undefined)
-        return 'machine setup reads files only to standard output';
-    return undefined;
-}
 function setupCapacity(ws) {
     const disk = ws.grants?.disk_gib;
     if (typeof disk !== 'number' || !Number.isFinite(disk) || disk <= 0)