@shardflux/cli 0.28.0 → 0.28.2

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

@@ -97,7 +97,7 @@ 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;
     }>;

package/dist/land.js

@@ -127,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, r) => linkedFolder(ctx, p, c, r),
+    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);
@@ -228,7 +228,7 @@ export async function landTask(d, taskId, opts = {}) {
     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) => {
+        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);
     });
@@ -267,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/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)

package/dist/main.js

@@ -14,27 +14,17 @@ import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, aboutSeconds, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, GUIDE_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
-import { commandCenter } from "./command-center.js";
-import { launchProjectCommand } from "./conversation-terminal.js";
-import { runAcp } from "./acp.js";
 import { registerInstalledT3 } from "./t3-provider.js";
-import { refreshForwarderAgent } from "./cli-proxy.js";
-import { runAcpLogin } from "./acp-login.js";
-import { terminalOnboarding } from "./terminal-onboarding.js";
-import { codingAgentShell, setupGuideText } from "./agent-setup.js";
-import { agentSetupGuide } from "./account-commands.js";
-import { tryLinuxDesktop } from "./desktop-linux.js";
+import { codingAgentShell } from "./agent-shell.js";
 import { startLinuxHelper } from "./linux-helper.js";
-import { runDeviceHelper } from "./device-helper.js";
-import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
+import { housekeepingIfTracked, startupHousekeeping } from "./startup-housekeeping.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { recordInstall } from "./update.js";
 import { refreshMenubarInBackground, runMenubarRefresh } from "./menubar.js";
 import { NPM_CLIENTS, npmLatestAll, npmRegistry, withRegistryLatest } from "./registry.js";
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
 import { errorText, feedbackCommand, json, time } from "./format.js";
-import { HANDLERS } from "./handlers.js";
-import { SETUP_VM_ENV, setupGuard } from "./machine-setup.js";
+import { SETUP_VM_ENV, setupGuard } from "./machine-setup-guard.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
 import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
@@ -726,6 +716,7 @@ export async function run(argv, io, opts = {}) {
     };
     // Bare shard without a terminal (0.17.1+): the setup guide, read from local state only (never waits).
     if (parsed.command === GUIDE_COMMAND) {
+        const { setupGuideText, agentSetupGuide } = await import("./agent-setup.js");
         io.stdout.write(setupGuideText(agentSetupGuide(ctx)));
         return EXIT.ok;
     }
@@ -733,14 +724,24 @@ export async function run(argv, io, opts = {}) {
     const refused = setupGuard(io.env, command, parsed.values, parsed.positionals);
     if (refused)
         return report(new UsageError(refused));
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await tryLinuxDesktop(ctx) ? 0 : terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    // Load the selected interactive surface only after help/version and credential parsing. Plain commands do
+    // not need the terminal UI, ACP session machinery, device bridge or onboarding just to start.
+    const handler = parsed.command.path[0] === 'acp'
+        ? async (ctx) => parsed.values.login === true ? (await import("./acp-login.js")).runAcpLogin(ctx) : (await import("./acp.js")).runAcp(ctx)
+        : parsed.command.path[0] === 'device-helper'
+            ? async (ctx) => (await import("./device-helper.js")).runDeviceHelper(ctx, { service: parsed.values.service === true })
+            : command === 'menubar refresh' ? runMenubarRefresh
+                : parsed.command === PROJECT_COMMAND ? (await import("./conversation-terminal.js")).launchProjectCommand
+                    : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await (await import("./desktop-linux.js")).tryLinuxDesktop(ctx) ? 0 : (await import("./terminal-onboarding.js")).terminalOnboarding(ctx, values, { startHelper })
+                        : parsed.command === CENTER_COMMAND ? (await import("./command-center.js")).commandCenter
+                            : await (await import("./handler-loader.js")).handlerFor(parsed.command.path.join(' '));
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
     // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.
     if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward' && !io.env[SETUP_VM_ENV]) {
         // An updated shard restarts this computer's CLIProxyAPI forwarder on itself (a no-op unless the version changed).
-        await refreshForwarderAgent(io.env, ctx.store.dir).catch(() => false);
-        await housekeeping(ctx);
+        await import("./forwarder-refresh.js").then(({ refreshForwarderAgent }) => refreshForwarderAgent(io.env, ctx.store.dir)).catch(() => false);
+        await housekeepingIfTracked(ctx);
         startHelper();
     }
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));

package/dist/orchestrator-commands.js

@@ -6,7 +6,7 @@
  * a session) reaches the orchestrator of the member who created that key (person-scope.ts). Text output is one line
  * per input, tab-separated, id first; --json prints the API's objects.
  */
-import { inputSettled, ORCHESTRATOR_TEXT_MAX } from '@shardflux/sdk';
+import { inputSettled } from '@shardflux/sdk';
 import { parseDuration } from "./args.js";
 import { out, str } from "./commands.js";
 import { EXIT, UsageError } from "./errors.js";
@@ -202,8 +202,6 @@ export const ORCHESTRATOR_HANDLERS = {
         const text = words.join(' ');
         if (!text.trim())
             throw new UsageError('missing <words...> for "shard orchestrator say"');
-        if (text.length > ORCHESTRATOR_TEXT_MAX)
-            throw new UsageError(`your words are ${text.length} characters; one input takes up to ${ORCHESTRATOR_TEXT_MAX}`);
         const selection = selectionOf(values);
         const wait = values.wait === true;
         const timeoutMs = str(values.timeout) === undefined ? SAY_WAIT_MS : parseDuration(str(values.timeout), 'timeout');

package/dist/startup-housekeeping.d.ts

@@ -0,0 +1,5 @@
+import type { Ctx } from './commands.js';
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;
+/** Keep the command's already selected auth behavior, loading Git machinery only for tracked repositories. */
+export declare function housekeepingIfTracked(ctx: Pick<Ctx, 'io' | 'apiUrl' | 'signal' | 'store' | 'cloud'>): Promise<void>;

package/dist/startup-housekeeping.js

@@ -0,0 +1,30 @@
+import { Shardflux } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { resolveApiUrl } from "./args.js";
+import { UsageError } from "./errors.js";
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export async function startupHousekeeping(ctx) {
+    try {
+        const state = new AgentStateStore(ctx.store.dir).read();
+        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
+            return;
+        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
+        let cloud;
+        await (await import("./agent-git-commands.js")).housekeeping({ ...ctx, apiUrl, cloud: () => {
+                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
+                if (!key)
+                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
+                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
+            } });
+    }
+    catch (error) {
+        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+/** Keep the command's already selected auth behavior, loading Git machinery only for tracked repositories. */
+export async function housekeepingIfTracked(ctx) {
+    const repos = new AgentStateStore(ctx.store.dir).read().git_repositories;
+    if (!repos || !Object.keys(repos).length)
+        return;
+    await (await import("./agent-git-commands.js")).housekeeping(ctx);
+}

package/dist/t3-provider.js

@@ -3,13 +3,15 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { writePrivateFile } from "./credentials.js";
 import { withTargetLock } from "./target-lock.js";
-import { installedTargets } from "./agent-targets.js";
+import { applicationDirs, t3Apps } from "./agent-targets.js";
 import { t3ArchiveSupportsAcp } from "./t3-asar.js";
 const ID = 'shardflux';
 const provider = { driver: 'acpRegistry', displayName: 'Shardflux', enabled: true, config: { source: 'local', commandPath: 'shard', commandArgs: ['acp'] } };
 /** Every shard invocation registers the one installed T3 provider without adding terminal noise (macOS and Linux). */
 export async function registerInstalledT3(env, dir, signal, platform = process.platform) {
-    if (!installedTargets(env, platform).targets.includes('t3'))
+    // Registration only needs T3 presence; probing other apps or choosing a
+    // preferred T3 version would inspect unrelated bundles on every command.
+    if (!t3Apps(applicationDirs(env, platform), platform, env).length)
         return;
     try {
         await configureT3Provider(env, dir, false, signal);

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

@@ -123,7 +123,7 @@ export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promis
  * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
  * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
  */
-export declare function projectHubCell(ctx: Ctx, projectId: string, signal?: AbortSignal, agentLabel?: string): Promise<{
+export declare function projectHubCell(ctx: Ctx, projectId: string, signal?: AbortSignal, agentLabel?: string, workspaceIds?: readonly string[]): Promise<{
     cell: TwinCell;
     close(): void;
 }>;

package/dist/worktree-twin-engine.js

@@ -508,14 +508,17 @@ const openCell = (ws, agentLabel) => {
  * A VM of the project that reads the project hub: an awake one reads it without waking anything; else the project's
  * small space reader (woken). The twin lands from it when a conversation's VM is gone; `shard task land` merges there.
  */
-export async function projectHubCell(ctx, projectId, signal, agentLabel = 'shard-twin') {
+export async function projectHubCell(ctx, projectId, signal, agentLabel = 'shard-twin', workspaceIds) {
     const client = conversationClient(ctx);
-    const all = (await listConversations(ctx, projectId)).filter(c => !ended(c))
-        .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
-    for (const c of all) {
+    // A manual landing uses its own result's computer. Borrowing an unrelated thread races that person's deletion:
+    // staging 2026-10-17 cut off a real landing when a newer home thread's VM was deleted. If the result's computers
+    // are gone or asleep, the persistent space reader owns the operation instead; do not wake a finished agent.
+    const ids = workspaceIds ?? (await listConversations(ctx, projectId)).filter(c => !ended(c))
+        .sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? '')).map(c => c.workspace_id);
+    for (const id of new Set(ids)) {
         try {
-            const ws = await client.workspaces.get(c.workspace_id);
-            if (!ws.data.deleted_at && ws.ready)
+            const ws = await client.workspaces.get(id);
+            if (ws.data.project_id === projectId && !ws.data.deleted_at && ws.ready)
                 return openCell(ws, agentLabel);
         }
         catch { /* another may be awake */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -31,7 +31,12 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./bin": "./dist/bin.js"
+    "./bin": "./dist/bin.js",
+    "./main": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js",
+      "default": "./dist/main.js"
+    }
   },
   "files": [
     "dist",
@@ -48,7 +53,7 @@
     "snappyjs": "0.7.0",
     "ws": "8.22.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.30.0"
+    "@shardflux/sdk": "^0.30.2"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -60,10 +65,10 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-darwin-arm64": "0.9.1",
-    "@shardflux/desktop-darwin-x64": "0.9.1",
-    "@shardflux/desktop-linux-arm64": "0.9.1",
-    "@shardflux/desktop-linux-x64": "0.9.1"
+    "@shardflux/desktop-darwin-arm64": "0.9.3",
+    "@shardflux/desktop-darwin-x64": "0.9.3",
+    "@shardflux/desktop-linux-arm64": "0.9.3",
+    "@shardflux/desktop-linux-x64": "0.9.3"
   },
   "scripts": {
     "build": "node scripts/build.mjs",