@shardflux/cli 0.13.2 → 0.13.4

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.13.4
+
+- Cloud Claude sign-in and reopening the machine editor preserve existing workspace labels while updating their own labels.
+- `shard billing status` on the signup trial suggests `shard billing upgrade pro` when the live catalog offers Pro (the trial is 60 days of Pro from catalog live-v10); otherwise it points to `shard billing plans`.
+- Reuse an account-private setup cache across projects after the agent starts; report cache scope with `shard template --json`.
+- Machine and project filesystem status shows the current platform base and whether a rebase is pending.
+
+## 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 9+).
+
 ## 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.

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.
@@ -264,9 +264,9 @@ plan only when Stripe confirms the payment, so `--wait` polls until the subscrip
 open). An organization that already has a subscription changes plans in the billing portal: the
 command prints the portal URL instead (exit 0).
 
-On the signup trial (60 days at Developer limits, no card), `billing status` shows when it ends and
+On the signup trial (60 days of Pro, no card), `billing status` shows when it ends and
 what follows (0.6.2+): `plan  trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog ...)`, then
-`keep these limits after the trial: shard billing upgrade developer`. A subscription outranks the
+`keep these limits after the trial: shard billing upgrade pro` (0.13.4+). A subscription outranks the
 trial and ends it. The trial is granted, never bought, so `billing plans` leaves it out.
 
 `billing overage` shows and changes opt-in overage (owners and billing members). With it on,
@@ -283,7 +283,7 @@ already charged this period (`spend_cap_below_charges`); a plan without overage
 ```text
 $ shard billing overage on --cap 9
 Acme: overage is on, spend cap $9.00 per billing period ($1.00 to $9.00, the plan price).
-Rates past the allowances: $0.03 per RAM GiB-hour, $0.12 per CPU-hour, charged on the next invoice (this period: shard usage).
+Rates past the allowances: $0.015 per RAM GiB-hour, $0.04 per CPU-hour, charged on the next invoice (this period: shard usage).
 Saved (policy version 1).
 ```
 
@@ -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
@@ -828,12 +828,12 @@ amount:
 ```text
 overage          accruing (usage past the allowances is charged on the next invoice)
 spend cap        $9.00 (at most $9.00, the plan price)
-overage charges  $2.40 of $9.00 (26.67%), $6.60 left; billed on the next invoice
+overage charges  $1.10 of $9.00 (12.22%), $7.90 left; billed on the next invoice
 cap reached      2026-09-29 15:02:46Z (projected at this period's average use)
 
-OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE   AMOUNT
-ram_gib_hours  gib_hours  70              60      $0.03  $1.80
-cpu_hours      hours      5               5       $0.12  $0.60
+OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE    AMOUNT
+ram_gib_hours  gib_hours  70              60      $0.015  $0.90
+cpu_hours      hours      5               5       $0.04   $0.20
 ```
 
 `--json` prints the API's summary, with `spend_cap` and `exhausted_reason`. Owners and billing members turn overage on
@@ -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/account-commands.js

@@ -1403,12 +1403,15 @@ export const ACCOUNT_HANDLERS = {
         const account = ctx.account();
         const org = await resolveOrg(ctx, account, values);
         const s = await account.billing.subscription(org.id);
-        // The trial has Developer limits: Developer keeps them (a subscription outranks the trial and ends it).
+        // The trial has Pro's limits and allowances (catalog live-v10): Pro keeps them (a subscription outranks the trial and ends it).
+        // Name Pro only while the live catalog sells it; a catalog without Pro gets the general hint.
+        const trialToPro = !s.subscription && s.purchase_available && s.plan?.plan_key === 'trial'
+            && (await fetchBillingCatalog({ baseUrl: ctx.apiUrl, fetch: ctx.accountOptions().fetch ?? fetch }).catch(() => null))?.plans?.some((p) => p.plan_key === 'pro') === true;
         const next = s.subscription
             ? 'manage it: shard billing portal'
             : s.purchase_available
-                ? s.plan?.plan_key === 'trial'
-                    ? 'keep these limits after the trial: shard billing upgrade developer'
+                ? trialToPro
+                    ? 'keep these limits after the trial: shard billing upgrade pro'
                     : 'buy a plan: shard billing plans, then shard billing upgrade <plan>'
                 : '';
         out(ctx, `${billingStatusText(s, org)}${next ? `${next}\n` : ''}`, s);

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, deferSetup?: boolean): Promise<PtySession>;
 export declare const launchProject: Handler;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -1,3 +1,4 @@
+import { prepareSetupCache } from "./setup-cache.js";
 import { agentReachability } from "./agent-reachability.js";
 import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
 import { createHash } from 'node:crypto';
@@ -15,7 +16,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,11 +40,11 @@ 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, deferSetup = false) {
     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.
-    if (setupHash) {
+    if (setupHash && !deferSetup) {
         const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}) });
         if (queued.exitCode !== 0)
             throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
@@ -55,8 +58,9 @@ 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 } : {}),
+        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (launch.exitCode !== 0)
         throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
@@ -84,14 +88,26 @@ 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}…`); }, true);
+        // The real agent is running before any cache provisioning or mount wait.
+        const preparation = prepareSetupCache(ctx, ws).catch((error) => {
+            ctx.io.stderr.write(`Account setup cache unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        }).then(async () => {
+            if (!setupHash)
+                return;
+            const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { cwd, timeoutMs: 30_000, maxOutputBytes: 4096, signal: ctx.signal });
+            if (queued.exitCode !== 0)
+                throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
+        });
         store.save(project, app);
         if (!attach) {
+            await preparation;
             ctx.io.stdout.write(json({ workspace: ws.data, session }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
-        return await attachTerminal({
+        const attached = attachTerminal({
             ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
             io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id),
             wake: (signal) => ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal }),
@@ -104,8 +120,11 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
                     done();
             }),
         });
+        const [code] = await Promise.all([attached, preparation]);
+        return code;
     }
     finally {
+        cell.close();
         await tunnels?.stop();
     }
 }
@@ -212,8 +231,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-credentials.js

@@ -76,8 +76,15 @@ export const AGENT_CREDENTIAL_HANDLERS = {
         }
         requireClaudeTerminal(ctx);
         const project = projectIdentity('./');
-        const ws = typeof values.workspace === 'string' ? await resolveWorkspace(ctx, values.workspace)
-            : await ctx.cloud().workspaces.open({ key: `${project.slug}/main`, template: 'coding', labels: projectLabels(project, 'main', 'claude'), wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        let ws;
+        if (typeof values.workspace === 'string')
+            ws = await resolveWorkspace(ctx, values.workspace);
+        else {
+            const cloud = ctx.cloud();
+            const key = `${project.slug}/main`;
+            const current = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+            ws = await cloud.workspaces.open({ key, template: 'coding', labels: { ...current?.labels, ...projectLabels(project, 'main', 'claude') }, wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        }
         output(ctx, await loginClaudeInWorkspace(ctx, ws));
         return 0;
     },

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.