@shardflux/cli 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.13.3
+
+- `shard ./` seeds the workspace repository with the checked-out branch and its upstream only, not every local branch, tag and stash. When that history is still above 256 MiB, the workspace fetches the branch from origin with its own Git credentials and receives only the commits origin does not have yet. The workspace branch tracks its origin branch.
+- Cloud Claude sign-in merges the account into the workspace's `~/.claude.json` on its latest content, also when the platform delivers the new login to that workspace at the same moment.
+- A request the edge firewall refuses (`403 forbidden`, reason `edge_refused`, or a bare `403`) comes with a hint that sends the data through a command's stdin instead.
+- `shard <path> claude|codex` starts (or reattaches) that agent directly instead of opening the command center's start picker; with `--json` it starts the agent detached and prints the session.
+- `shard agents list` shows an agent this computer started in the last five minutes before the API's session list has picked it up, read from the agent's workspace.
+- `shard machine` prints a progress line for each long step of its first open: creating the machine VM, syncing Claude and Codex config, signing in to cloud Claude, starting the agent.
+- `shard agents targets <agent>` says what it configured where: the SSH host and the file it lives in (included from `~/.ssh/config`), and the Claude Desktop and Codex app entries with their files.
+- `shard machine save` and `shard template save` print one line naming the version being saved; `--wait` returns once that version is ready (or failed, exit 6 with `filesystem_save_failed`), with progress on stderr; `--timeout` bounds the wait (default 10 minutes). `shard machine` and `shard template` print one status line.
+- Git history above the first copy's 256 MiB limit fails with `repository_too_large` and its next step in the hint, not `internal_error`.
+- A `revision_mismatch` suggests `--expected-revision` only for the file commands that take it; elsewhere it says to run the same command again.
+- Config sync reports project entries keyed by paths on this computer (Codex `config.projects.*`) as one summary line.
+- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 8+).
+
+## 0.13.2
+
+- On macOS, `shard` starts the menu bar by itself (with launch at login) the first time it runs; `shard menubar stop` turns that off and `shard menubar start` turns it back on.
+
 ## 0.13.1
 
 - `npx @shardflux/cli` runs `shard` again: the package exposes one command. The Git remote helper that `shard` uses for agent branches runs from a private shim on the PATH of the git commands `shard` starts.

package/README.md

@@ -43,17 +43,16 @@ Bulk transfers batch writes automatically. Active transfers retain their byte po
 ## Install
 
 ```sh
-npm install -g @shardflux/cli
+npm i -g shardflux
 shard --help
 ```
 
-Or run it without installing: `npx @shardflux/cli --help`. The unscoped
-[`shardflux`](https://www.npmjs.com/package/shardflux) package installs the same CLI as
-`shardflux` and `shard`; install one package or the other globally, not both.
+The [`shardflux`](https://www.npmjs.com/package/shardflux) package installs the `shard` command.
+Use `shard` for your projects, machine, templates and account.
 
 ## Quick start
 
-Start your coding agent on a local project (0.13.0+):
+Start your coding agent on a local project (0.13.2+):
 
 ```sh
 shard setup
@@ -63,7 +62,8 @@ shard ./
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
 The agent is usable immediately while setup prepares the project in the background. `shard` opens the command
-center for every project; `shard ./` returns to this project. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
+center for every project; `shard ./` returns to this project. On macOS the menu bar starts automatically the first
+time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
@@ -351,7 +351,7 @@ and the session renewals of step-up and password changes).
 `shard` tells you when a newer version exists, on stderr after the command's output:
 
 ```text
-@shardflux/cli 0.5.0 is outdated: 0.6.0 is available. Update: npm install -g @shardflux/cli@latest
+@shardflux/cli 0.5.0 is outdated: 0.6.0 is available. Update: npm i -g shardflux
 ```
 
 or that the API no longer supports it (`... is no longer supported by the Shardflux API (minimum
@@ -1114,12 +1114,12 @@ Use `shard ws computer paste-text <key> - --paste-chord shift+Insert --screensho
 
 Template services accept `initialized_cpu` with `compatibility`, `reset`, and `timeout_seconds`. Use `cpu-service-v1` for immutable initialization, or `cpu-service-fresh-inputs-v1` with `fresh_env_names` for values supplied at each open. Declare an unprivileged user and command readiness. Each open runs the reset script and its owned startup hooks before returning. Initialization-dependent and secret inputs use ordinary startup.
 
-### Waiting agent reachability (0.13.0+)
+### Waiting agent reachability (0.13.2+)
 
 Set `--reachable 30m` when opening a workspace to choose how long waiting agents stay reachable through connections they opened. See [reachability settings](https://docs.shardflux.dev/limits#cloud-agent-reachability). Incoming replies wake the parked workspace, which answers them and parks again. These wakes count as parked time; agent work counts as awake time.
 
 
-## Cloud agents (0.13.0+)
+## Cloud agents (0.13.2+)
 
 Run `shard ./` in your project to start Claude Code or Codex, usable immediately while setup runs in the background.
 Your **machine** carries credentials, tools, dotfiles, logins and agent config; the project's **template** carries
@@ -1127,6 +1127,9 @@ toolchains, dependencies, services and project secrets. Both are private filesys
 as ordinary files. Browser logins and Claude/Codex config belong to the machine. Set up tools and secrets normally inside the VM;
 your agent uses the same save/rollback commands there. Every agent starts from both. Save or roll back with `shard machine save|rollback` and
 `shard template save|rollback`; changed files reach running agents live, software at the next start.
+`shard machine save --wait` and `shard template save --wait` return once the new version is ready (0.13.3+).
+`shard ./ codex` (or `claude`) starts that agent directly; `shard agents targets <project>/<agent>` lists each
+connection it configured and the file it is in (0.13.3+).
 
 `shard agents fork` or `f` in the command center copies the whole running state into an independent workspace and
 conversation. Open in your terminal, Claude Desktop or the Codex app, and the terminal Claude conversation in

package/dist/agent-commands.d.ts

@@ -3,6 +3,6 @@ import type { Ctx, Handler } from './commands.js';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
-export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string): Promise<PtySession>;
+export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void): Promise<PtySession>;
 export declare const launchProject: Handler;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -15,7 +15,9 @@ import { startAgentConfigTunnels, syncAgentConfig } from "./agent-config-sync.js
 import { rememberGitAgent } from "./agent-git-commands.js";
 import { projectWorkspacePath, seedAgentRepository, workspaceRepositoryPath } from "./agent-repository.js";
 import { agentName } from "./agent-git.js";
-import { cloudClaudeLogin, ensureCloudClaude, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { progress } from "./progress.js";
+import { rememberLaunch } from "./agent-live.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export function disambiguatedSlug(slug, identity) {
@@ -37,7 +39,7 @@ export async function projectTemplate(ctx, remote) {
         throw error;
     }
 }
-export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName) {
+export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
@@ -55,6 +57,7 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
         if (!missing(error))
             throw error;
     }
+    onLaunch?.();
     const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
         env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
@@ -84,7 +87,8 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
     const tunnels = attach ? await startAgentConfigTunnels(ctx, ws) : null;
     try {
         const credentialFill = await configureCredentialFill(ctx, ws);
-        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name);
+        // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
+        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); });
         store.save(project, app);
         if (!attach) {
             ctx.io.stdout.write(json({ workspace: ws.data, session }));
@@ -212,8 +216,10 @@ export const AGENT_HANDLERS = {
             ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
         const projectKey = typeof values.project === 'string' ? values.project : ws.labels.repo_remote || ws.labels.shard_project || ws.key;
         const app = values.app ?? new AgentStateStore(ctx.store.dir).app(projectKey, ws.labels.app === 'codex' ? 'codex' : 'claude');
-        if (app === 'claude')
-            await ensureCloudClaude(ctx, ws);
+        if (app === 'claude' && !await cloudClaudeLogin(ctx)) {
+            progress(ctx, 'Signing in to cloud Claude (once per account)…');
+            await loginClaudeInWorkspace(ctx, ws);
+        }
         if (!ctx.json && values.detach !== true)
             requireTerminal(ctx);
         if (ws.labels.shard_layer !== 'machine' && !(await savedMachine(ctx))?.template)

package/dist/agent-config-files.js

@@ -1,5 +1,6 @@
 import { readFile, readdir, realpath, stat } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
+import { LOCAL_PATH_REASON } from "./agent-config-report.js";
 export const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
 export const text = (v) => typeof v === 'string' ? v : undefined;
 export const absent = (e) => e.code === 'ENOENT';
@@ -190,7 +191,7 @@ export function rewritePaths(value, home, remoteHome, files, issues, item) {
         const result = {};
         for (const [key, v] of Object.entries(value)) {
             if (key.startsWith('/') || key.startsWith('~/')) {
-                issues.push({ item: `${item}.${key}`, reason: 'local project path is not synced by agent config' });
+                issues.push({ item: `${item}.${key}`, reason: LOCAL_PATH_REASON });
                 continue;
             }
             const mapped = rewritePaths(v, home, remoteHome, files, issues, `${item}.${key}`);

package/dist/agent-config-report.d.ts

@@ -0,0 +1,8 @@
+import type { ConfigIssue } from './agent-config-files.js';
+export declare const LOCAL_PATH_REASON = "local project path is not synced by agent config";
+/**
+ * The human report of a config sync's skipped items. Per-project entries keyed by a laptop path (Codex
+ * `config.projects./Users/...`, Claude `projects./Users/...`) only describe this computer; they become one summary
+ * line per sync, and every other skipped item keeps its own line.
+ */
+export declare function configIssueLines(issues: ConfigIssue[]): string[];

package/dist/agent-config-report.js

@@ -0,0 +1,21 @@
+export const LOCAL_PATH_REASON = 'local project path is not synced by agent config';
+/**
+ * The human report of a config sync's skipped items. Per-project entries keyed by a laptop path (Codex
+ * `config.projects./Users/...`, Claude `projects./Users/...`) only describe this computer; they become one summary
+ * line per sync, and every other skipped item keeps its own line.
+ */
+export function configIssueLines(issues) {
+    const local = new Map();
+    const lines = [];
+    for (const issue of issues) {
+        const at = issue.reason === LOCAL_PATH_REASON ? issue.item.search(/\.(?:\/|~\/)/) : -1;
+        if (at > 0)
+            local.set(issue.item.slice(0, at), (local.get(issue.item.slice(0, at)) ?? 0) + 1);
+        else
+            lines.push(`Config skipped ${issue.item}: ${issue.reason}`);
+    }
+    const total = [...local.values()].reduce((a, b) => a + b, 0);
+    if (total)
+        lines.unshift(`Config kept ${total} project ${total === 1 ? 'entry' : 'entries'} for paths on this computer out of the VM (${[...local.keys()].join(', ')})`);
+    return lines;
+}

package/dist/agent-config-sync.js

@@ -6,6 +6,7 @@ import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { collectPlugins, collectUserFiles, object, readObject, readOptional, rewritePaths } from "./agent-config-files.js";
 import { digest, prepareMcp } from "./agent-config-mcp.js";
+import { configIssueLines } from "./agent-config-report.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
 const markerPath = '.config/shardflux/agent-config.json';
 const safePath = (path) => !path.split('/').some(p => !p || p === '.' || p === '..') &&
@@ -302,8 +303,8 @@ export async function syncAgentConfig(ctx, ws) {
     store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = manifest; doc.agent_config = all; });
     const result = { ...empty, copied: applied.copied, removed: applied.removed, skipped: issues, mcp, synced_at };
     if (!ctx.json) {
-        for (const issue of issues)
-            ctx.io.stderr.write(`Config skipped ${issue.item}: ${issue.reason}\n`);
+        for (const line of configIssueLines(issues))
+            ctx.io.stderr.write(`${line}\n`);
         for (const server of mcp)
             if (server.status !== 'copied')
                 ctx.io.stderr.write(`MCP ${server.app}/${server.name}: ${server.status}${server.reason ? ` (${server.reason})` : ''}\n`);

package/dist/agent-live.d.ts

@@ -0,0 +1,29 @@
+import type { Agent } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+/** One record of `sf-agent list`: the guest's own session table, PID-reconciled on every read. */
+interface GuestSession {
+    session_id: string;
+    app: 'claude' | 'codex';
+    state: Agent['state'];
+    since_unix_ms: number;
+    title: string;
+    remote_control_url: string;
+}
+/** Parses `sf-agent list` stdout; anything malformed yields no sessions rather than a wrong row. */
+export declare function guestSessions(stdout: string): GuestSession[];
+/** How long after a launch the listing may still miss it: the projection refreshes about once a minute. */
+export declare const LAUNCH_WINDOW_MS: number;
+/** Remembers that this computer started an agent in a workspace (a cold launch or a fork), for withLiveAgents. */
+export declare function rememberLaunch(ctx: Pick<Ctx, 'store'>, workspaceId: string, now?: number): void;
+/**
+ * GET /v1/agents is the cell's projection of each host's inventory, refreshed about once a minute, so an agent this
+ * computer started moments ago is not listed yet. For each running workspace where this computer started an agent in
+ * the last five minutes, after the newest session the listing has for it, read the guest's own table (`sf-agent list`,
+ * one short exec) and merge it: a guest row replaces the projected row with the same id. Nothing else is asked, so
+ * listing never keeps an idle workspace awake. A workspace whose guest cannot answer keeps its projected rows.
+ */
+export declare function withLiveAgents(ctx: Ctx, agents: Agent[], filter: {
+    state?: string;
+    labels: Record<string, string>;
+}, now?: number): Promise<Agent[]>;
+export {};

package/dist/agent-live.js

@@ -0,0 +1,82 @@
+import { AgentStateStore } from "./agent-state.js";
+const STATES = new Set(['working', 'waiting', 'exited']);
+/** Parses `sf-agent list` stdout; anything malformed yields no sessions rather than a wrong row. */
+export function guestSessions(stdout) {
+    let doc;
+    try {
+        doc = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!doc || typeof doc !== 'object')
+        return [];
+    const { ok, sessions } = doc;
+    if (ok !== true || !Array.isArray(sessions))
+        return [];
+    return sessions.filter((value) => {
+        if (!value || typeof value !== 'object')
+            return false;
+        const s = value;
+        return typeof s.session_id === 'string' && s.session_id.length > 0 && (s.app === 'claude' || s.app === 'codex') && typeof s.state === 'string' && STATES.has(s.state) &&
+            Number.isSafeInteger(s.since_unix_ms) && s.since_unix_ms > 0 && typeof s.title === 'string' && typeof s.remote_control_url === 'string';
+    });
+}
+/** How long after a launch the listing may still miss it: the projection refreshes about once a minute. */
+export const LAUNCH_WINDOW_MS = 5 * 60_000;
+/** Remembers that this computer started an agent in a workspace (a cold launch or a fork), for withLiveAgents. */
+export function rememberLaunch(ctx, workspaceId, now = Date.now()) {
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const launches = { ...(doc.agent_launches && typeof doc.agent_launches === 'object' ? doc.agent_launches : {}) };
+        for (const [id, at] of Object.entries(launches))
+            if (typeof at !== 'number' || now - at > LAUNCH_WINDOW_MS)
+                delete launches[id];
+        launches[workspaceId] = now;
+        doc.agent_launches = launches;
+    });
+}
+const running = (w) => !w.deleted_at && w.observed_state === 'running';
+/**
+ * GET /v1/agents is the cell's projection of each host's inventory, refreshed about once a minute, so an agent this
+ * computer started moments ago is not listed yet. For each running workspace where this computer started an agent in
+ * the last five minutes, after the newest session the listing has for it, read the guest's own table (`sf-agent list`,
+ * one short exec) and merge it: a guest row replaces the projected row with the same id. Nothing else is asked, so
+ * listing never keeps an idle workspace awake. A workspace whose guest cannot answer keeps its projected rows.
+ */
+export async function withLiveAgents(ctx, agents, filter, now = Date.now()) {
+    const launches = new AgentStateStore(ctx.store.dir).read().agent_launches;
+    const recent = Object.entries(launches ?? {}).filter(([id, at]) => typeof at === 'number' && now - at < LAUNCH_WINDOW_MS &&
+        agents.filter(a => a.workspace_id === id).every(a => Date.parse(a.since) < at));
+    if (!recent.length)
+        return agents;
+    const live = await Promise.all(recent.map(async ([id]) => {
+        try {
+            const ws = await ctx.cloud().workspaces.get(id);
+            const w = ws.data;
+            if (!running(w) || !Object.entries(filter.labels).every(([k, v]) => w.labels?.[k] === v))
+                return [];
+            const cell = ws.cell({ agentLabel: ctx.agentLabel });
+            const result = await cell.exec.run(['sf-agent', 'list'], { timeoutMs: 10_000, maxOutputBytes: 1 << 20, signal: ctx.signal });
+            if (result.exitCode !== 0)
+                return [];
+            return guestSessions(result.stdout).map(s => ({
+                id: `${w.id}:${s.session_id}`, workspace_id: w.id, workspace_key: w.workspace_key, app: s.app, state: s.state,
+                since: new Date(s.since_unix_ms).toISOString(), title: s.title, remote_control_url: s.remote_control_url, labels: w.labels,
+            }));
+        }
+        catch (error) {
+            // A deleted workspace, or a guest that cannot answer, has nothing to add.
+            if (ctx.signal.aborted)
+                throw error;
+            return [];
+        }
+    }));
+    const rows = live.flat().filter(row => !filter.state || row.state === filter.state);
+    if (!rows.length)
+        return agents;
+    const merged = new Map(agents.map(a => [a.id, a]));
+    for (const row of rows)
+        merged.set(row.id, { ...merged.get(row.id), ...row });
+    // The API's order: workspace, then session.
+    return [...merged.values()].sort((a, b) => a.workspace_id.localeCompare(b.workspace_id) || a.id.localeCompare(b.id));
+}

package/dist/agent-repository.d.ts

@@ -1,5 +1,7 @@
 import type { Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
+import { CodedError } from './errors.js';
+import type { SyncCell } from './project-sync-transfer.js';
 export declare function projectWorkspacePath(project: {
     slug: string;
 }): string;
@@ -11,3 +13,13 @@ export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: str
     root?: string;
     populate?: boolean;
 }): Promise<void>;
+/** History above this goes through the project's origin instead of the bounded files path. */
+export declare const HISTORY_BUNDLE_LIMIT: number;
+/** A history the first copy cannot carry (repository_too_large, 0.13.3+): the facts, and the next step as the hint. */
+export declare function tooLarge(message: string, hint: string, branch: string, origin: string | null): CodedError;
+/**
+ * Imports the checked-out branch's history into an empty workspace repository. Only HEAD, its branch and that branch's
+ * upstream are bundled: other branches, worktrees and stashes stay on this computer. When that is still above `limit`,
+ * the workspace fetches `origin` itself (with its own Git credentials) and receives only the commits origin lacks.
+ */
+export declare function importProjectHistory(cell: SyncCell, folder: string, root: string, head: string, branch: string, origin: string | null, signal?: AbortSignal, limit?: number): Promise<void>;

package/dist/agent-repository.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { CodedError } from "./errors.js";
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity } from "./project-identity.js";
 import { localManifest, projectGit } from "./project-sync-manifest.js";
@@ -34,6 +35,87 @@ export async function seedAgentRepository(ctx, ws, folder, options = {}) {
     await initializeProjectGit(cell, project.folder, root, ctx.signal, options.populate, retry, message => { ctx.io.stderr.write(`${message}\n`); });
     state.update(doc => { const seeds = (doc.git_seeding ?? {}); delete seeds[ws.id]; doc.git_seeding = seeds; });
 }
+/** History above this goes through the project's origin instead of the bounded files path. */
+export const HISTORY_BUNDLE_LIMIT = 256 << 20;
+async function optionalGit(folder, args, signal) {
+    try {
+        return (await projectGit(folder, args, signal)).trim();
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        return '';
+    }
+}
+const tail = (text) => text.trim().split('\n').slice(-3).join(' ').slice(-400);
+// Fetches one origin branch (or origin's HEAD) into an empty workspace repository and prints its commit.
+const FETCH_ORIGIN = 'set -eu; git init -q "$1"; case "$3" in HEAD) dst=refs/shard-sync/origin ;; *) dst="refs/remotes/origin/${3#refs/heads/}" ;; esac; ' +
+    'git -C "$1" -c core.hooksPath=/dev/null -c credential.interactive=false fetch -q --no-tags "$2" "+$3:$dst" >&2; git -C "$1" rev-parse --verify "$dst^{commit}"';
+// Applies an optional bundle of HEAD (plus its branch and upstream) and points the workspace HEAD at the laptop's.
+const APPLY_HISTORY = 'set -eu; git init -q "$1"; if [ -n "$2" ]; then git -C "$1" -c core.hooksPath=/dev/null fetch -q --update-head-ok "$2" HEAD:refs/shard-sync/initial ' +
+    '"+refs/heads/*:refs/heads/*" "+refs/tags/*:refs/tags/*" "+refs/remotes/*:refs/remotes/*"; fi; ' +
+    'if [ -n "$4" ]; then git -C "$1" symbolic-ref HEAD "$4"; else git -C "$1" update-ref --no-deref HEAD "$3"; fi; git -C "$1" update-ref HEAD "$3"; git -C "$1" read-tree HEAD; ' +
+    'for ref in refs/shard-sync/initial refs/shard-sync/origin; do if git -C "$1" rev-parse -q --verify "$ref" >/dev/null; then git -C "$1" update-ref -d "$ref"; fi; done';
+/** A history the first copy cannot carry (repository_too_large, 0.13.3+): the facts, and the next step as the hint. */
+export function tooLarge(message, hint, branch, origin) {
+    return new CodedError('repository_too_large', `${message}.`, hint, { limit_bytes: HISTORY_BUNDLE_LIMIT, branch, ...(origin ? { origin } : {}) });
+}
+/**
+ * Imports the checked-out branch's history into an empty workspace repository. Only HEAD, its branch and that branch's
+ * upstream are bundled: other branches, worktrees and stashes stay on this computer. When that is still above `limit`,
+ * the workspace fetches `origin` itself (with its own Git credentials) and receives only the commits origin lacks.
+ */
+export async function importProjectHistory(cell, folder, root, head, branch, origin, signal, limit = HISTORY_BUNDLE_LIMIT) {
+    const upstream = branch ? await optionalGit(folder, ['rev-parse', '--symbolic-full-name', `${branch.slice(11)}@{upstream}`], signal) : '';
+    const tracked = upstream.startsWith('refs/remotes/') ? upstream : '';
+    const tips = ['HEAD', ...(branch ? [branch] : []), ...(tracked ? [tracked] : [])];
+    const dir = await mkdtemp(join(tmpdir(), 'shard-sync-git-'));
+    const local = join(dir, 'history.bundle'), remote = `/tmp/shard-sync-${randomUUID()}.bundle`;
+    try {
+        await projectGit(folder, ['bundle', 'create', local, ...tips], signal);
+        let bundle = true;
+        if ((await stat(local)).size > limit) {
+            const name = branch ? branch.slice(11) : 'HEAD';
+            if (!origin)
+                throw tooLarge(`Git history of ${name} exceeds the 256 MiB sync limit and the project has no network origin the workspace can clone`, 'add an origin remote, then run shard again', name, origin);
+            const ref = upstream.startsWith('refs/remotes/origin/') ? `refs/heads/${upstream.slice(20)}` : 'HEAD';
+            const fetched = await cell.exec.run(['sh', '-c', FETCH_ORIGIN, 'shard-sync', root, origin, ref], { timeoutMs: 600_000, maxOutputBytes: 8192, env: { GIT_TERMINAL_PROMPT: '0' }, signal });
+            const base = fetched.stdout.trim();
+            if (fetched.exitCode !== 0 || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(base)) {
+                throw tooLarge(`Git history of ${name} exceeds the 256 MiB sync limit and the workspace could not fetch ${origin}: ${tail(fetched.stderr)}`, 'give the machine access to the repository (GitHub: run gh auth login in shard machine), then run shard again', name, origin);
+            }
+            // Commits origin already has are not sent again; a base this computer does not know falls back to its upstream.
+            const exclude = await optionalGit(folder, ['cat-file', '-t', base], signal) === 'commit' ? base : tracked;
+            if (!exclude)
+                throw tooLarge(`Git history of ${name} exceeds the 256 MiB sync limit and shares no known commit with ${origin}`, 'push the branch, then run shard again', name, origin);
+            let onOrigin = true;
+            try {
+                await projectGit(folder, ['merge-base', '--is-ancestor', head, exclude], signal);
+            }
+            catch (error) {
+                if (signal?.aborted || error.code !== 1)
+                    throw error;
+                onOrigin = false;
+            }
+            bundle = !onOrigin;
+            if (bundle) {
+                await rm(local, { force: true });
+                await projectGit(folder, ['bundle', 'create', local, ...tips.filter(tip => tip !== tracked), '--not', exclude], signal);
+                if ((await stat(local)).size > limit)
+                    throw tooLarge(`Commits of ${name} that ${origin} does not have exceed the 256 MiB sync limit`, 'push them, then run shard again', name, origin);
+            }
+        }
+        if (bundle)
+            await writeSyncBlob(cell, remote, await readFile(local));
+        const result = await cell.exec.run(['sh', '-c', APPLY_HISTORY, 'shard-sync', root, bundle ? remote : '', head, branch], { timeoutMs: 60_000, maxOutputBytes: 4096, signal });
+        if (result.exitCode !== 0)
+            throw new Error(`initial Git bundle failed: ${result.stderr.trim()}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+        await cell.files.remove(remote).catch(() => undefined);
+    }
+}
 async function initializeProjectGit(cell, folder, root, signal, populate = false, retry = false, report = () => undefined) {
     let top;
     try {
@@ -69,22 +151,8 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
                 throw error;
         }
         if (head && importHistory) {
-            const dir = await mkdtemp(join(tmpdir(), 'shard-sync-git-'));
-            const local = join(dir, 'history.bundle'), remote = `/tmp/shard-sync-${randomUUID()}.bundle`;
-            try {
-                await projectGit(folder, ['bundle', 'create', local, '--all'], signal);
-                if ((await stat(local)).size > 256 << 20)
-                    throw new Error('Git history bundle exceeds the 256 MiB sync limit');
-                await writeSyncBlob(cell, remote, await readFile(local));
-                const script = 'set -eu; git init -q "$1"; git -C "$1" -c core.hooksPath=/dev/null fetch -q --update-head-ok "$2" HEAD:refs/shard-sync/initial "+refs/heads/*:refs/heads/*" "+refs/tags/*:refs/tags/*"; if [ -n "$4" ]; then git -C "$1" symbolic-ref HEAD "$4"; else git -C "$1" update-ref --no-deref HEAD "$3"; fi; git -C "$1" update-ref HEAD "$3"; git -C "$1" read-tree HEAD; git -C "$1" update-ref -d refs/shard-sync/initial';
-                const result = await cell.exec.run(['sh', '-c', script, 'shard-sync', root, remote, head, branch], { timeoutMs: 60_000, maxOutputBytes: 4096, signal });
-                if (result.exitCode !== 0)
-                    throw new Error(`initial Git bundle failed: ${result.stderr.trim()}`);
-            }
-            finally {
-                await rm(dir, { recursive: true, force: true });
-                await cell.files.remove(remote).catch(() => undefined);
-            }
+            const remote = projectIdentity(folder).remote;
+            await importProjectHistory(cell, folder, root, head, branch, remote && !remote.startsWith('file:') ? remote : null, signal);
         }
         else if (importHistory) {
             const result = await cell.exec.run(['git', 'init', '-q', ...(branch.startsWith('refs/heads/') ? ['--initial-branch', branch.slice(11)] : []), root], { timeoutMs: 5000, signal });
@@ -111,6 +179,14 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
             const result = await cell.exec.run(['git', '-C', root, 'config', 'remote.origin.url', origin], { timeoutMs: 5000, signal });
             if (result.exitCode !== 0)
                 throw new Error('could not copy Git origin');
+            // The imported branch keeps tracking its origin branch, as on this computer.
+            const upstream = importHistory && branch ? await optionalGit(folder, ['rev-parse', '--symbolic-full-name', `${branch.slice(11)}@{upstream}`], signal) : '';
+            if (upstream.startsWith('refs/remotes/origin/'))
+                for (const [key, value] of [[`branch.${branch.slice(11)}.remote`, 'origin'], [`branch.${branch.slice(11)}.merge`, `refs/heads/${upstream.slice(20)}`]]) {
+                    const set = await cell.exec.run(['git', '-C', root, 'config', key, value], { timeoutMs: 5000, signal });
+                    if (set.exitCode !== 0)
+                        throw new Error('could not copy Git upstream');
+                }
         }
         // Ignore files must exist before the first remote scan; otherwise a
         // template's dependency outputs would look like agent-created source.

package/dist/agent-target-commands.js

@@ -5,6 +5,7 @@ import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
 import { out, resolveWorkspace } from "./commands.js";
 import { AgentTargets, installedTargets } from "./agent-targets.js";
+import { join, relative } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
@@ -134,14 +135,42 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions });
     return 0;
 };
+const tilde = (targets, file) => file.startsWith(`${targets.home}/`) ? `~/${relative(targets.home, file)}` : file;
+const targetLabel = (e) => `[SF] ${e.project} · ${e.agent}`;
+/** Where each managed connection of an entry lives: the SSH host block (and its Include), then each desktop app's file. */
+function configuredTargets(targets, e) {
+    return [
+        { target: 'ssh', label: 'SSH', file: targets.sshFile, name: e.host, detail: `(included from ${tilde(targets, join(targets.home, '.ssh', 'config'))}): ssh ${e.host}` },
+        ...(e.targets.includes('claude-desktop') ? [{ target: 'claude-desktop', label: 'Claude Desktop', file: targets.claudeFile, name: targetLabel(e), detail: `(sshConfigs: ${targetLabel(e)}); restart Claude Desktop, then pick it in Code's environment list` }] : []),
+        ...(e.targets.includes('codex-app') ? [{ target: 'codex-app', label: 'Codex app', file: targets.codexFile, name: targetLabel(e), detail: `(remoteConnections: ${targetLabel(e)}); restart Codex to import it` }] : []),
+    ];
+}
+function targetFiles(targets, entries) {
+    return [...new Set(entries.flatMap(e => configuredTargets(targets, e).map(c => c.file)))];
+}
 export const TARGET_HANDLERS = {
     'agents targets'(ctx, values, [ref]) {
         const detected = installedTargets(ctx.io.env);
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
+        const key = ref ? keyOf(ref) : undefined;
+        const before = values.remove === true ? targets.configure(undefined, ctx.apiUrl, []) : [];
         const entries = ref || values.remove === true
-            ? targets.configure(ref ? keyOf(ref) : undefined, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app'), values.remove === true)
+            ? targets.configure(key, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app'), values.remove === true)
             : [];
-        out(ctx, `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n${entries.map(e => e.host).join('\n')}${entries.length ? '\n' : ''}`, { ...detected, entries });
+        const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n`;
+        if (values.remove === true) {
+            const removed = before.filter(e => !entries.some(n => n.host === e.host));
+            out(ctx, removed.length ? `Removed ${removed.map(e => `${e.workspace} (${e.host})`).join(', ')} from ${targetFiles(targets, removed).map(f => tilde(targets, f)).join(', ')}\n` : 'No managed targets to remove.\n', { ...detected, entries, removed });
+            return Promise.resolve(0);
+        }
+        const entry = key ? entries.find(e => e.workspace === key) : undefined;
+        if (!entry) {
+            out(ctx, detection, { ...detected, entries });
+            return Promise.resolve(0);
+        }
+        const configured = configuredTargets(targets, entry);
+        out(ctx, `Configured ${entry.workspace} as SSH host ${entry.host}:\n${configured.map(c => `  ${c.label.padEnd(15)} ${tilde(targets, c.file)}${c.detail ? ` ${c.detail}` : ''}`).join('\n')}\n` +
+            ['claude-desktop', 'codex-app'].filter(t => !entry.targets.includes(t)).map(t => `  ${(t === 'claude-desktop' ? 'Claude Desktop' : 'Codex app').padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })) });
         return Promise.resolve(0);
     },
     'agents open claude-desktop': openTarget('claude-desktop'),

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.13.1";
+export declare const CLI_VERSION = "0.13.3";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.13.1';
+export const CLI_VERSION = '0.13.3';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -142,7 +142,10 @@ const SECRET_PERMISSIONS = {
 const KEY_COMMANDS = [
     ...['machine', 'template'].flatMap((level) => [
         { path: [level], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {} },
-        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, positionals: [], options: {} },
+        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, positionals: [], options: {
+                wait: { type: 'boolean', description: 'Return when the new version is ready (or failed), printing progress on stderr.' },
+                timeout: { type: 'string', value: '<duration>', description: 'With --wait: give up waiting after this long (default 10m). The save continues server side.' },
+            } },
         { path: [level, 'rollback'], summary: `Restore a saved ${level} version`, positionals: [], options: { to: { type: 'string', value: '<version>', description: 'Version to restore (default previous saved version).' } } },
     ]),
     { path: ['agents', 'list'], summary: 'List coding agent sessions.', positionals: [], options: {
@@ -1136,8 +1139,8 @@ const AGENT_OPTIONS = {
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
 export const PROJECT_COMMAND = {
-    path: ['<path>'], summary: 'Open the project’s cloud agent command center',
-    description: 'Claude is the default; add codex to use Codex. Detach with Ctrl-] then d; /exit ends the agent session.',
+    path: ['<path>'], summary: 'Open the project’s cloud agent command center, or start its agent directly with claude|codex',
+    description: 'Naming the app starts (or reattaches) that agent at once; with --json it starts detached and prints the session. Detach with Ctrl-] then d; /exit ends the agent session.',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: AGENT_OPTIONS,
 };
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };

package/dist/assisted-setup.d.ts

@@ -4,10 +4,12 @@ export interface SetupProgress {
     id: string;
     deps_hash: string;
     state: 'queued' | 'running' | 'checking' | 'saving' | 'ready' | 'failed';
+    /** required is false for a step the repository marked `required: false` in .shardflux/setup.yaml. */
     tasks: {
         name: string;
-        state: 'queued' | 'running' | 'ready' | 'failed';
+        state: 'queued' | 'running' | 'ready' | 'failed' | 'skipped';
         attempts: number;
+        required?: boolean;
         error?: {
             code: string;
             message: string;

package/dist/assisted-setup.js

@@ -67,7 +67,10 @@ export async function retrySetupStep(ctx, workspace, step) {
 export function setupLine(project, setup) {
     if (setup.state === 'ready')
         return undefined;
-    const failed = setup.tasks.find(task => task.state === 'failed' && task.error?.code !== 'setup_dependency_failed');
+    const failures = setup.tasks.filter(task => task.state === 'failed' && task.error?.code !== 'setup_dependency_failed');
+    // A step marked required: false does not hold back the save; it is the
+    // failure shown only when the job failed and no required step did.
+    const failed = failures.find(task => task.required !== false) ?? (setup.state === 'failed' ? failures[0] : undefined);
     if (failed)
         return `Setting up ${project}: ${failed.name} failed: ${failed.error?.message ?? 'No error receipt'}${failed.error?.retryable ? ' · r retries once' : ''}`;
     if (setup.state === 'saving')

package/dist/claude-cloud-login.d.ts

@@ -1,9 +1,15 @@
-import type { AgentCredentialMetadata, Workspace } from '@shardflux/sdk';
+import type { AgentCredentialMetadata, CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 export declare function requireClaudeTerminal(ctx: Ctx): void;
 export declare function cloudClaudeLogin(ctx: Ctx): Promise<AgentCredentialMetadata | undefined>;
 /** Parse only complete provider authorize links, including the native OSC-8 link. */
 export declare function claudeLoginUrls(output: string): string[];
+/**
+ * Put the signed-in account into the workspace's ~/.claude.json, keeping every other key. The platform's credential
+ * delivery writes the same file right after the upload, so a revision conflict re-reads and merges again; a file that
+ * already holds this account is left as it is.
+ */
+export declare function mergeClaudeAccount(cell: Pick<CellClient, 'files'>, oauthAccount: unknown, signal?: AbortSignal): Promise<void>;
 /** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
 export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace): Promise<AgentCredentialMetadata>;
 export declare function ensureCloudClaude(ctx: Ctx, ws: Workspace): Promise<void>;

package/dist/claude-cloud-login.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from 'node:util';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { openUrl } from "./browser.js";
@@ -42,6 +43,39 @@ function credentialFile(path, value, ctx) {
     ctx.addSecret(content_b64);
     return { path, mode: '0600', content_b64 };
 }
+/**
+ * Put the signed-in account into the workspace's ~/.claude.json, keeping every other key. The platform's credential
+ * delivery writes the same file right after the upload, so a revision conflict re-reads and merges again; a file that
+ * already holds this account is left as it is.
+ */
+export async function mergeClaudeAccount(cell, oauthAccount, signal) {
+    const path = '/home/user/.claude.json';
+    for (let attempt = 0; attempt < 5; attempt++) {
+        let document = {}, revision = 'absent';
+        try {
+            const current = await cell.files.readWithInfo(path);
+            document = JSON.parse(Buffer.from(current.data).toString());
+            if (!current.revision)
+                throw new UsageError('Claude account configuration has no safe content revision.');
+            revision = current.revision;
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'status' in error && error.status === 404))
+                throw error;
+        }
+        if (isDeepStrictEqual(document.oauthAccount, oauthAccount))
+            return;
+        try {
+            await cell.files.patch({ path, content: JSON.stringify({ ...document, oauthAccount }), expectedRevision: revision, mode: '0600', createParents: true }, { signal });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof ShardfluxApiError && error.status === 409 && error.details?.reason === 'revision_mismatch'))
+                throw error;
+        }
+    }
+    throw new UsageError('Claude account configuration kept changing in the workspace. Run shard agents credentials login claude again.');
+}
 /** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
 export async function loginClaudeInWorkspace(ctx, ws) {
     requireClaudeTerminal(ctx);
@@ -112,22 +146,10 @@ export async function loginClaudeInWorkspace(ctx, ws) {
         // persistence. An upload error requires a new cloud login, never guest refresh.
         await cell.files.remove(root, { recursive: true });
         const metadata = await api.put('claude', files, { loginId: claim.login_id });
+        complete = true; // stored: the login must not be canceled by a later local write failure
         const access = Object.fromEntries(['accessToken', 'expiresAt', 'scopes', 'subscriptionType', 'rateLimitTier'].filter(key => key in credential.claudeAiOauth).map(key => [key, credential.claudeAiOauth[key]]));
         await cell.files.write('/home/user/.claude/.credentials.json', JSON.stringify({ claudeAiOauth: access }), { mode: '0600', createParents: true });
-        let document = {}, revision = 'absent';
-        try {
-            const current = await cell.files.readWithInfo('/home/user/.claude.json');
-            document = JSON.parse(Buffer.from(current.data).toString());
-            if (!current.revision)
-                throw new UsageError('Claude account configuration has no safe content revision.');
-            revision = current.revision;
-        }
-        catch (error) {
-            if (!(error instanceof Error && 'status' in error && error.status === 404))
-                throw error;
-        }
-        await cell.files.patch({ path: '/home/user/.claude.json', content: JSON.stringify({ ...document, oauthAccount: config.oauthAccount }), expectedRevision: revision, mode: '0600', createParents: true }, { signal: ctx.signal });
-        complete = true;
+        await mergeClaudeAccount(cell, config.oauthAccount, ctx.signal);
         return metadata;
     }
     finally {

package/dist/command-center-actions.js

@@ -6,6 +6,7 @@ import { json } from "./format.js";
 import { UsageError } from "./errors.js";
 import { cellConnector, PtyOutputCursor } from "./agent-terminal.js";
 import { rememberGitAgent } from "./agent-git-commands.js";
+import { rememberLaunch } from "./agent-live.js";
 import { agentName as gitAgentName } from "./agent-git.js";
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
@@ -43,6 +44,7 @@ export const CENTER_HANDLERS = {
         const labels = { ...source.labels, shard_project: source.labels.shard_project || source.key.split('/')[0], agent: name,
             agent_pty_name: source.labels.agent_pty_name || agentName(source.key, source.labels) };
         const caps = workspaceCaps(values);
+        const started = Date.now();
         const result = await ctx.cloud().workspaces.fork(source.id, { key, labels, ...(caps ? { caps } : {}) }, {
             agentLabel: ctx.agentLabel, wait: values.wait === false ? false : { timeoutMs: waitTimeout(values), signal: ctx.signal },
         });
@@ -54,6 +56,8 @@ export const CENTER_HANDLERS = {
             throw new Error(`Fork ${key} has no independent agent session receipt`);
         }
         await ctx.cloud().workspaces.setRetention(result.workspace.id, { delete_after_idle_days: 7 });
+        if (agent)
+            rememberLaunch(ctx, result.workspace.id, started);
         await rememberGitAgent(ctx, result.workspace, './');
         out(ctx, `Forked ${key}: operation ${result.operation.id} ${result.operation.state}\n`, { workspace: result.workspace.data, operation: result.operation, ...(agent ? { agent } : {}) });
         return 0;

package/dist/command-center.js

@@ -6,7 +6,7 @@ import { agentAction, availableTargets } from "./command-center-actions.js";
 import { centerRows, loadCenter } from "./command-center-model.js";
 import { AnsiRenderer, renderCenter } from "./command-center-renderer.js";
 import { CenterKeys } from "./command-center-keys.js";
-import { menubarHint } from "./menubar.js";
+import { ensureMenubar } from "./menubar.js";
 import { MenubarManager } from "./menubar.js";
 import { homedir } from 'node:os';
 import { retrySetupStep } from "./assisted-setup.js";
@@ -17,7 +17,7 @@ export async function showCenter(ctx, scope, options = {}) {
     const { HANDLERS } = await import("./handlers.js");
     const extra = [['m', 'merge'], ['k', 'keep'], ['d', 'discard']].filter(([, command]) => HANDLERS[`agents ${command}`]);
     const view = { rows: [], selected: undefined, filter: '', message: 'Loading agents…', extraKeys: extra.map(([key, command]) => `${key} ${command}`) };
-    const hint = await menubarHint(ctx.store.dir, new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal }));
+    const hint = await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal }));
     if (hint)
         view.menubarHint = hint;
     const renderer = new AnsiRenderer(), keys = new CenterKeys();
@@ -308,6 +308,9 @@ export async function showCenter(ctx, scope, options = {}) {
     }
 }
 export const commandCenter = async (ctx, values, [path, app]) => {
+    // `shard <path> claude|codex` names the agent: start (or reattach) it without the picker; --json starts it detached.
+    if (path && (app === 'claude' || app === 'codex'))
+        return agentAction(ctx, 'new', { ...values, path, app }, []);
     const scope = path ? projectIdentity(path) : undefined;
     if (ctx.json) {
         const data = await loadCenter(ctx);

package/dist/commands.d.ts

@@ -79,7 +79,7 @@ export declare function openVolumes(values: readonly string[]): import('@shardfl
 export declare function workspaceCaps(values: Values): Caps | undefined;
 /** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds). */
 export declare function whenIdleSeconds(text: string): number;
-export declare function waitTimeout(values: Values): number;
+export declare function waitTimeout(values: Values, fallbackMs?: number): number;
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
  * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live

package/dist/commands.js

@@ -17,6 +17,7 @@ import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
 import { updateCheckDisabled } from "./update-check.js";
+import { withLiveAgents } from "./agent-live.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
@@ -174,9 +175,9 @@ export function whenIdleSeconds(text) {
         throw new UsageError(`--when-idle must be between 0s and 1h (got "${text}")`);
     return s;
 }
-export function waitTimeout(values) {
+export function waitTimeout(values, fallbackMs = DEFAULT_WAIT_MS) {
     const t = str(values.timeout);
-    return t === undefined ? DEFAULT_WAIT_MS : parseDuration(t, 'timeout');
+    return t === undefined ? fallbackMs : parseDuration(t, 'timeout');
 }
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
@@ -814,6 +815,9 @@ export const KEY_HANDLERS = {
             next = page.nextCursor;
             cursor = next ?? undefined;
         } while (values.all === true && cursor);
+        // A complete listing also shows sessions the projection has not picked up yet (agent-live.ts).
+        if (!next && !str(values.cursor))
+            rows.splice(0, rows.length, ...await withLiveAgents(ctx, rows, { ...(state ? { state } : {}), labels }));
         out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
         if (!ctx.json && next)
             ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);

package/dist/errors.d.ts

@@ -28,6 +28,16 @@ declare class HintedError extends Error {
 export declare class UsageError extends HintedError {
     name: string;
 }
+/**
+ * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
+ * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
+ */
+export declare class CodedError extends HintedError {
+    name: string;
+    readonly code: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, hint?: string, details?: Record<string, unknown>);
+}
 /** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
 export declare class AuthConfigError extends HintedError {
     name: string;

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { CheckoutTimeoutError, DurabilityLostError, ExecStartError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
+import { CheckoutTimeoutError, DurabilityLostError, ExecStartError, FilesystemSaveFailedError, FilesystemSaveTimeoutError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -36,6 +36,20 @@ class HintedError extends Error {
 export class UsageError extends HintedError {
     name = 'UsageError';
 }
+/**
+ * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
+ * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
+ */
+export class CodedError extends HintedError {
+    name = 'CodedError';
+    code;
+    details;
+    constructor(code, message, hint, details) {
+        super(message, hint);
+        this.code = code;
+        this.details = details;
+    }
+}
 /** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
 export class AuthConfigError extends HintedError {
     name = 'AuthConfigError';
@@ -180,6 +194,8 @@ export function describeError(err) {
         return { code: 'timeout', message: err.message, last_state: err.session.state, details: { session_id: err.session.session_id } };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
+    if (err instanceof CodedError)
+        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {
         return { code: 'timeout', message: `${err.message}; the checkout stays open (pay at its URL, then check with: shard billing status)`, last_state: err.checkout.status, details: { checkout_id: err.checkout.id, status: err.checkout.status, url: err.checkout.url } };
     }
@@ -190,6 +206,11 @@ export function describeError(err) {
         return { code: 'usage', message: err.message };
     if (err instanceof TemplateBuildTimeoutError)
         return { code: 'timeout', message: `${err.message}; follow it with: shard templates builds get ${err.build.id}`, last_state: err.build.state };
+    // machine/template save --wait (0.13.3+): the save ended without its version, or is still building at the deadline.
+    if (err instanceof FilesystemSaveFailedError)
+        return { code: 'filesystem_save_failed', message: err.message, retryable: true, details: { level: err.state.level, version: err.version } };
+    if (err instanceof FilesystemSaveTimeoutError)
+        return { code: 'timeout', message: `${err.message}; check with shard ${err.state.level}`, last_state: err.state.state, details: { level: err.state.level, version: err.version } };
     if (err instanceof TemplateUploadError)
         return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof AuthConfigError)
@@ -221,8 +242,10 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.usage;
     if (err instanceof AuthConfigError || err instanceof MfaPendingError)
         return EXIT.auth;
-    if (err instanceof TemplateBuildTimeoutError)
+    if (err instanceof TemplateBuildTimeoutError || err instanceof FilesystemSaveTimeoutError)
         return EXIT.timeout;
+    if (err instanceof FilesystemSaveFailedError)
+        return EXIT.operationFailed;
     if (err instanceof NotFoundError)
         return EXIT.notFound;
     if (err instanceof OperationTimeoutError || err instanceof CheckoutTimeoutError || isNamed(err, 'TimeoutError'))

package/dist/filesystem-commands.d.ts

@@ -1,2 +1,5 @@
+import type { AgentFilesystem } from '@shardflux/sdk';
 import type { Handler } from './commands.js';
+/** One line per status: what is in use and what is saving or failed. */
+export declare function filesystemLine(state: AgentFilesystem): string;
 export declare const FILESYSTEM_HANDLERS: Record<string, Handler>;

package/dist/filesystem-commands.js

@@ -1,16 +1,38 @@
+import { waitTimeout } from "./commands.js";
 import { UsageError } from "./errors.js";
 import { projectIdentity, normalizeRemote } from "./project-identity.js";
 import { AGENT_HANDLERS } from "./agent-commands.js";
 import { syncAgentConfig } from "./agent-config-sync.js";
+import { progress } from "./progress.js";
 function remote() {
     const project = projectIdentity('./');
     return { project, repoRemote: project.remote ?? normalizeRemote(`file://${project.folder}`) };
 }
+/** One line per status: what is in use and what is saving or failed. */
+export function filesystemLine(state) {
+    const current = state.version > 0 ? `version ${state.version}` : '';
+    if (state.state === 'building' && state.pending)
+        return `${state.level}: saving version ${state.pending.version}${current ? ` (${current} stays in use until it is ready)` : ''}`;
+    if (state.state === 'failed' && state.failure)
+        return `${state.level}: version ${state.failure.version} was not saved: ${state.failure.message}${current ? ` (${current} stays in use)` : ''}`;
+    if (current)
+        return `${state.level}: ${current} is ready`;
+    return state.level === 'machine' ? 'machine: nothing saved yet; change it in shard machine, then run shard machine save' : 'template: nothing saved yet; setup saves it after shard ./, or run shard template save';
+}
 function output(ctx, state) {
-    ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${state.level}: ${state.state}; version ${state.version}\n` +
-        (state.pending ? `Saving version ${state.pending.version}. Run shard ${state.level} --json for progress.\n` : '') +
-        (state.failure ? `${state.failure.message}\n` : '') +
-        (state.template ? `${state.template.slug}@${state.template.version}\n` : 'No saved version yet.\n'));
+    ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${filesystemLine(state)}\n`);
+    return 0;
+}
+/** Save output: one line naming the version being saved, or with --wait the saved version (progress on stderr). */
+async function saved(ctx, values, save, level) {
+    if (values.wait !== true && values.timeout !== undefined)
+        throw new UsageError('--timeout needs --wait');
+    const wait = values.wait === true ? { timeoutMs: waitTimeout(values, 600_000), onChange: (state) => { if (state.state === 'building' && state.pending)
+            progress(ctx, `Saving ${level} version ${state.pending.version}…`); } } : undefined;
+    const state = await save({ signal: ctx.signal, ...(wait ? { wait } : {}) });
+    if (ctx.json)
+        return output(ctx, state);
+    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved\n` : state.pending ? `${filesystemLine(state)}; shard ${level} shows when it is ready\n` : `${filesystemLine(state)}\n`);
     return 0;
 }
 const rollbackTo = (value) => {
@@ -28,21 +50,28 @@ export const FILESYSTEM_HANDLERS = {
         if (ctx.json || !ctx.io.stdin.isTTY)
             return output(ctx, state);
         const key = `machine/${state.organization_id}/v${state.version}`;
+        const existing = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+        if (!existing)
+            progress(ctx, `Creating your machine VM (${key}); the first open takes about a minute…`);
+        else if (existing.data.observed_state !== 'running')
+            progress(ctx, `Resuming your machine VM (${key})…`);
         const ws = await cloud.workspaces.open({ key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
             labels: { shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
             wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
-        if (state.version === 0)
+        if (state.version === 0) {
+            progress(ctx, 'Syncing your Claude and Codex config into the machine…');
             await syncAgentConfig(ctx, ws);
+        }
         return AGENT_HANDLERS['agents open'](ctx, {}, [ws.key]);
     },
-    async 'machine save'(ctx) {
+    async 'machine save'(ctx, values) {
         const cloud = ctx.cloud();
         const state = await cloud.machine.get({ signal: ctx.signal });
         const ws = await cloud.workspaces.findByKey(`machine/${state.organization_id}/v${state.version}`, { signal: ctx.signal }) ??
             (state.workspace_id ? await cloud.workspaces.get(state.workspace_id) : null);
         if (!ws)
             throw new UsageError('Open shard machine, change it, then run shard machine save');
-        return output(ctx, await cloud.machine.save({ workspaceId: ws.id }, { signal: ctx.signal }));
+        return saved(ctx, values, options => cloud.machine.save({ workspaceId: ws.id }, options), 'machine');
     },
     async 'machine rollback'(ctx, values) {
         return output(ctx, await ctx.cloud().machine.rollback({ to: rollbackTo(values.to) }, { signal: ctx.signal }));
@@ -50,12 +79,12 @@ export const FILESYSTEM_HANDLERS = {
     async template(ctx) {
         return output(ctx, await ctx.cloud().templates.getProject(remote().repoRemote, { signal: ctx.signal }));
     },
-    async 'template save'(ctx) {
+    async 'template save'(ctx, values) {
         const { project, repoRemote } = remote();
         const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
         if (!ws)
             throw new UsageError('Run shard ./ for this project before saving its template');
-        return output(ctx, await ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, { signal: ctx.signal }));
+        return saved(ctx, values, options => ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, options), 'template');
     },
     async 'template rollback'(ctx, values) {
         return output(ctx, await ctx.cloud().templates.rollbackProject({ repoRemote: remote().repoRemote, to: rollbackTo(values.to) }, { signal: ctx.signal }));

package/dist/main.js

@@ -46,7 +46,7 @@ export function abortableSleep(signal) {
 function reasonOf(info) {
     return typeof info.details?.reason === 'string' ? info.details.reason : undefined;
 }
-function hintFor(info, cred, file) {
+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) {
@@ -56,6 +56,10 @@ function hintFor(info, cred, file) {
         return `keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'usage')
         return 'run "shard --help" or "shard <command> --help"';
+    if (info.code === 'filesystem_save_failed') {
+        const level = info.details?.level === 'template' ? 'template' : 'machine';
+        return `the version in use is unchanged; fix what the message names in ${level === 'machine' ? 'shard machine' : 'the project agent'}, then run shard ${level} save --wait again`;
+    }
     if (info.source === 'cell' && info.code === 'workspace_not_running')
         return 'open or resume the workspace first: shard workspaces open <key> --template <slug>';
     if (info.status === 401 && info.code === 'unauthenticated') {
@@ -67,6 +71,10 @@ function hintFor(info, cred, file) {
             return `the API key saved in ${file} was revoked or expired; save a new one: shard setup --new-key`;
         return undefined;
     }
+    // The edge firewall answers before the API: the contract body (edge_refused), or a bare 403 from an edge without it.
+    if (reasonOf(info) === 'edge_refused' || (info.code === 'protocol_error' && info.status === 403)) {
+        return `the edge firewall refused the request before it reached Shardflux; send the data through a command's stdin instead, for example: shard ws exec <workspace> --stdin <local-file> -- sh -c 'cat > "$1"' sh <path>`;
+    }
     if (info.code === 'step_up_required')
         return STEP_UP_HINT;
     if (info.code === 'mfa_required')
@@ -94,6 +102,9 @@ function hintFor(info, cred, file) {
     const reason = info.details?.reason;
     const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
     if (reason === 'revision_mismatch') {
+        // Only file commands take --expected-revision; elsewhere (a sign-in, config sync) shard chose the revision itself.
+        if (!command.startsWith('files '))
+            return 'the file changed while shard was updating it; run the same command again';
         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}`;
     }
@@ -387,7 +398,7 @@ export async function run(argv, io, opts = {}) {
         }
         // An error that knows the command to continue with (an interrupted or still running execution) brings its own hint.
         const own = ownHint(err) ?? ((err instanceof InterruptedError || err instanceof ExecutionPendingError) && err.hint ? err.hint : undefined);
-        const hint = command === 'feedback' ? feedbackHint(info, own ?? hintFor(info, cred, store.file)) : (own ?? hintFor(info, cred, store.file));
+        const hint = command === 'feedback' ? feedbackHint(info, own ?? hintFor(info, cred, store.file, command)) : (own ?? hintFor(info, cred, store.file, command));
         // --timing on a failure: the failed call's timing (err.timing, else the last recorded), before the error; with
         // --json a `timing` field next to `error`.
         const timing = showTiming ? traces.forError(err) : null;

package/dist/menubar.d.ts

@@ -26,7 +26,8 @@ export declare class MenubarManager {
     login(value: 'on' | 'off'): Promise<MenubarStatus>;
     start(configDir: string, apiUrl: string): Promise<MenubarStatus>;
 }
-/** Only the command center consumes this hint. It reads status, never resolves or installs the optional package. */
-export declare function menubarHint(dir: string, manager?: MenubarManager): Promise<string | undefined>;
+/** On macOS, `shard` brings the menu bar up by itself (with launch at login) unless the user ran `shard menubar stop`.
+ *  It never fails the command center: a missing optional package or a refused start just leaves it off. */
+export declare function ensureMenubar(dir: string, apiUrl: string, manager?: MenubarManager, platform?: NodeJS.Platform): Promise<string | undefined>;
 export declare const MENUBAR_HANDLERS: Record<string, Handler>;
 export {};

package/dist/menubar.js

@@ -148,22 +148,28 @@ export class MenubarManager {
         throw new UsageError(`Shardflux did not start. Check ${join(configDir, 'menubar.log')}.`);
     }
 }
-/** Only the command center consumes this hint. It reads status, never resolves or installs the optional package. */
-export async function menubarHint(dir, manager = new MenubarManager()) {
-    if (process.platform !== 'darwin')
+/** On macOS, `shard` brings the menu bar up by itself (with launch at login) unless the user ran `shard menubar stop`.
+ *  It never fails the command center: a missing optional package or a refused start just leaves it off. */
+export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(), platform = process.platform) {
+    if (platform !== 'darwin')
         return undefined;
     const store = new AgentStateStore(dir);
-    if (store.read().menubar_hint_shown === true)
+    if (store.read().menubar_stopped === true)
         return undefined;
     try {
-        if ((await manager.status()).running)
+        const status = await manager.status();
+        if (status.running)
             return undefined;
+        const started = await manager.start(dir, apiUrl);
+        if (!started.running)
+            return undefined;
+        if (started.login !== 'on')
+            await manager.login('on').catch(() => undefined);
+        return 'Menu bar started · shard menubar stop to turn it off';
     }
     catch {
         return undefined;
     }
-    store.update(doc => { doc.menubar_hint_shown = true; });
-    return 'Menu bar: shard menubar start';
 }
 export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map(action => {
     const handler = async (ctx, values) => {
@@ -171,6 +177,12 @@ export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].m
             throw new UsageError('--login must be on or off.');
         const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
         let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop() : await manager.status();
+        // An explicit stop keeps `shard` from starting the menu bar again; an explicit start re-enables it.
+        if (action !== 'status')
+            new AgentStateStore(ctx.store.dir).update(doc => { if (action === 'stop')
+                doc.menubar_stopped = true;
+            else
+                delete doc.menubar_stopped; });
         if (values.login === 'on' || values.login === 'off')
             status = await manager.login(values.login);
         ctx.io.stdout.write(ctx.json ? json(status) : `Menu bar: ${status.running ? 'running' : 'stopped'}${status.installed ? ` · app ${status.version}` : ' · not installed'} · login ${status.login}\n`);

package/dist/progress.d.ts

@@ -0,0 +1,6 @@
+import type { Ctx } from './commands.js';
+/**
+ * One progress line on stderr before a step that can take a while (creating a VM, syncing config, signing in,
+ * starting an agent), so a long first run never looks hung. Silent with --json: stdout stays one document.
+ */
+export declare function progress(ctx: Pick<Ctx, 'json' | 'io'>, line: string): void;

package/dist/progress.js

@@ -0,0 +1,8 @@
+/**
+ * One progress line on stderr before a step that can take a while (creating a VM, syncing config, signing in,
+ * starting an agent), so a long first run never looks hung. Silent with --json: stdout stays one document.
+ */
+export function progress(ctx, line) {
+    if (!ctx.json)
+        ctx.io.stderr.write(`${line}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "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",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.18.0"
+    "@shardflux/sdk": "^0.18.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,7 +58,7 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.1.0"
+    "@shardflux/menubar-darwin": "^0.1.1"
   },
   "scripts": {
     "build": "node scripts/build.mjs",