@shardflux/cli 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,9 +1,68 @@
 # Changelog
 
+## 0.13.0 (not yet published)
+
+- Start the native agent while supervised repository setup runs in the background; show per-step setup progress and one failed-step retry in the command center. Changed runtime, CI, workspace and dependency inputs queue the next template preparation.
+- `shard agents fork` returns the independent agent session after a full-state fork; preserve the inherited PTY when reopening.
+
+- `shard template` is now the project template command (status, save, rollback); platform template commands stay under `shard templates` (the `template` shorthand for them is removed). `shard agents config` is gone: config sync is automatic.
+- Keep cloud agent desktop target names prefixed with `[SF] `.
+- Private account machine and project filesystem status, save and rollback; managed agent login files remain excluded from captures.
+
+- Keep waiting agents reachable on their outbound connections for a bounded window with `--reachable 30m`; default 30 minutes, `0` off. Packet wakes remain parked time.
+
+- Renew opted-in credential relays without a laptop after expiry, ownership changes and guest restart; preserve issuer revocation and project scope.
+
+- One cloud Claude sign-in through the workspace terminal; sync reads only Codex, and sign-in failures appear in the command center.
+- Keep attached project sync reconnecting across repeated suspend/resume cycles. A healthy guest watch resets the consecutive-failure budget.
+
+- Browser logins, dotfiles and Claude/Codex config are saved as part of the machine; configure them normally inside the VM and use the same machine/template save and rollback commands there.
+
+- `shard agents credentials sync/status/forget` manages Claude cloud sign-in metadata and copied Codex files without printing contents.
+- Import secrets from hsec, 1Password, Bitwarden and Keychain without exposing values; approve browser fills in attached terminals with per-site vault choices.
+
+- Share a bounded Git bundle seed and `/home/user/<project-slug>` repository between project sync and extra-agent hidden refs; sync only the main agent, before its setup turn.
+- Add attached two-way project sync with bounded hash manifests, coalesced guest file watches, detached catch-up and preserved conflict copies.
+
+- Add managed SSH/Claude Desktop/Codex app targets, reversible target configuration, Remote Control URL opening, and a wake-on-connect `shard ssh-proxy` with API-pinned host keys.
+- Fetch and push Git smart protocol streams over workspace exec with the packaged `git-remote-shard` helper. Extra agents use hidden refs; `agents worktree`, `merge`, `keep [--push]`, `discard` and `restore` manage local work and workspace cleanup. Extra agent workspaces receive seven-day idle retention; startup housekeeping archives saved commits for 30 days.
+- Install and control the macOS menu bar app with `shard menubar start|stop|status --login on|off`; add its optional macOS package and a one-time command center hint.
+- Shared volume quotas use one account total; opening a new volume without a size defaults to 1 GiB.
+
+- Add the TTY cloud agent command center with attention sorting, scoped projects, live status, filtering, attach/return, new sessions and agents, fork, idle park, and PTY offset logs. Automation can use the same actions with JSON output.
+- Sync personal Claude/Codex configuration on project launch and agent attach; add `shard agents config sync|status --json`, workspace manifests, consented workspace MCP secrets and attachment-owned localhost tunnels.
+- Set up first-run projects and changed dependencies, select prepared versions, and show them with shard projects template.
+
+- Attach agents directly to their deterministic guest PTY; launch with exec only when needed and retain only the remembered app choice locally.
+
+- Add shard agents list with state/label filters, pagination and JSON output.
+
+- Start or reattach cloud agents with `shard <path> [codex]`, and attach with `shard agents open <agent> --in terminal`. Terminal resize and reconnect preserve PTY output offsets; Ctrl-] then d detaches.
+- Derive project keys and labels from normalized git remotes, remember the project app, and use project template bindings when available.
+- Add `shard volumes open <name>`, `workspaces open --like` and repeatable `--volume name:/path[:ro]`.
+- Add `shard status [--json]` with all workspaces, attachable volumes and agents when the API provides `/v1/agents`.
+
+## 0.12.0 (not yet published)
+
+
+- Add `cpu-service-fresh-inputs-v1` with `fresh_env_names`: fresh owned startup hooks/children consume allowed task values while immutable CPU initialization stays credential-free. Relevant or secret inputs retain ordinary startup.
+
+- Add explicit `pasteText` clipboard replacement with an application paste chord, LF-to-Return typing repair and unchanged screenshot settling.
+
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
-## 0.11.1 (not yet published)
+
+- Accept caller-supplied exact desktop pixel predicates without an environment gate. Completion uses the same frozen full frame encoded as PNG; pre-satisfied refusal and timeout return no success image. Omitted predicates retain 250 ms settling.
+- Preserve explicit `initialized_cpu` service declarations through template YAML build/export/edit transport, matching SDK0.17.0.
+
+- Follows SDK 0.17.0's new minor dependency range.
+- Add `shard files read-many` for one explicitly suspended sealed generation, with exact base64 bytes and explicit incomplete-envelope errors; it never wakes the workspace.
+- Git partial clone and indexing/checkout controls remain explicit Git arguments through `shard ws exec`. No new browser convenience command is added.
+
+- Batch reverse-tunnel writes and retry after stalled acknowledgements, keeping active transfers moving without duplicate traffic.
+
+## 0.11.1 — 2026-10-05
 
 - Batch reverse-tunnel writes and retry after stalled acknowledgements, keeping active transfers moving without duplicate traffic.
 

package/README.md

@@ -53,25 +53,20 @@ Or run it without installing: `npx @shardflux/cli --help`. The unscoped
 
 ## Quick start
 
-No account yet? One command (0.9.0+) creates it, signs you in and saves an API key: no browser, no
-password. With the Codex CLI signed in with ChatGPT on this machine, your email is verified by it.
+Start your coding agent on a local project (0.13.0+):
 
 ```sh
-shard signup                                  # or: shard signup --email you@example.com
-shard exec acme/demo --template default -- python3 -c 'print(40 + 2)'   # created on first use
-shard files write acme/demo /home/user/notes.txt --from notes.txt
-shard files read acme/demo /home/user/notes.txt
-shard ws suspend acme/demo --wait
+shard setup
+cd your-project
+shard ./
 ```
 
-With a key from the web app instead, skip the account steps:
+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).
 
-```sh
-export SHARDFLUX_API_KEY=sfk_...             # project API key from the Shardflux console
-shard login                                   # verify the key: organization, project, tools
-```
-
-`shard --help` lists every command, and every command has its own `--help`.
+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.
 
 ## Feedback: agents, use this while you work
 
@@ -1017,7 +1012,6 @@ shard operations wait <op> --durable      # the same for a suspend or fork you a
 
 Apache-2.0
 
-
 ## Integration controls (0.7.0+)
 
 ```sh
@@ -1079,3 +1073,77 @@ exactly, and a workspace's own setting wins. With no policy, workspaces stay unt
 ## Workspace upgrade (0.11.0+)
 
 `shard ws upgrade <key>` keeps files and installed package files through one cold start. Memory and processes end. Use `--at next-resume` to schedule it without stopping the VM; `--json` returns the operation and its applied/scheduled result.
+
+From 0.12.0 this package follows SDK 0.17.0. For an explicit blobless clone, use `shard ws exec <key> -- git clone --filter=blob:none -- https://github.com/python/cpython.git /home/user/cpython`. Current checkout files are fetched now; historical blobs fetch from origin later. Plain and shallow clone defaults remain unchanged.
+
+### Sealed-file reads (0.12.0+)
+
+Additive: `shard files read-many <workspace> --path /file --path /other --generation <generation>` prints a sealed-generation JSON envelope with exact base64 bytes. Exit 1 means explicit missing/refused paths; exit 0 means every requested path succeeded. It never wakes or resumes the workspace.
+
+Use sealed-file reads for complete files from one suspended generation. If the generation changes, request a fresh read. See [lifecycle](https://docs.shardflux.dev/concepts/lifecycle) for the read contract.
+
+### Parallel Git checkout (0.12.0+)
+
+Set `parallelism` (1–16) to choose Git indexing threads and checkout workers for this clone. The `git_clone` tool forwards it; CLI callers use `git -c pack.threads=4 -c checkout.workers=4 clone ...` through `shard ws exec`.
+
+### Treeless Git clones (0.12.0+)
+
+Set `filter: "tree:0"` (Python: `filter="tree:0"`) to fetch the requested checkout and commit graph now, with historical trees and blobs fetched from origin as needed. CLI callers use `git clone --filter=tree:0` through `shard ws exec`. See [Git](https://docs.shardflux.dev/guides/agent-tools) for clone options.
+
+## Explicit pixel completion (0.12.0+)
+
+Pass the caller's predicate JSON in PREDICATE_JSON:
+
+```sh
+shard ws computer key acme/demo Return --screenshot result.png --pixel-predicate "$PREDICATE_JSON"
+```
+
+An unmatched condition exits 1 and writes no successful screenshot.
+
+Explicit predicates are enabled when supplied; no environment switch is required. Omitted predicates retain ordinary 250 ms settling.
+
+Require an appended lossless PNG and omit `settle_ms`. Digests cover row-major RGBA8 bytes including cursor pixels. The exact matched full frame is encoded and returned. A condition already satisfied before input refuses the batch unless `allow_pre_satisfied` explicitly allows that semantics. Timeout returns no success image; input may already have run, so inspect input results before retrying. Use a known, semantically unambiguous result. A pixel condition cannot certify unpainted backend state or infer completion from focus or quiet.
+
+## Exact text entry (0.12.0+)
+
+`pasteText` replaces the clipboard with UTF-8 text and sends the chosen paste chord. Use `shift+Insert` for xterm. Ordinary `type` sends line breaks as Return. Start with all keys released. Clipboard replacement remains in effect after cancellation; see [computer use](https://docs.shardflux.dev/guides/computer-use) for action results.
+
+Use `shard ws computer paste-text <key> - --paste-chord shift+Insert --screenshot after.png` with text on standard input. Leading-dash positional text goes after `--`.
+
+## Initialized CPU services (0.12.0+)
+
+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+)
+
+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+)
+
+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
+toolchains, dependencies, services and project secrets. Both are private filesystem templates and include secrets
+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 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
+claude.ai or mobile. Session titles start with `[SF] `. Waiting agents stay reachable on their own connections;
+see the [settings and billing reference](https://docs.shardflux.dev/limits#cloud-agent-reachability).
+Claude needs one cloud sign-in per account; Codex uses your copied login.
+
+Import project secrets from hsec, 1Password, Bitwarden or Keychain. Approve browser fills from the attached CLI or
+menu bar; remember a selected login for unattended work with automatic relay renewal. Bound secret values are
+redacted from command output and saved logs.
+
+Imported secrets: stored encrypted with AWS KMS; only this project's workspaces can load it, and every load is logged.
+Vault fills: sent end to end from your vault to the workspace; Shardflux only relays encrypted bytes.
+Remembered credentials: stored encrypted with AWS KMS and filled straight into the page; agents never see it, and every use is logged.
+
+[Start a cloud agent](https://docs.shardflux.dev/guides/cloud-agents) ·
+[Machine and template](https://docs.shardflux.dev/guides/machine-and-template) ·
+[Credentials](https://docs.shardflux.dev/guides/credentials)
+
+`shard templates` remains the platform template build and management group.

package/dist/account-args.js

@@ -378,6 +378,8 @@ export const ACCOUNT_COMMANDS = [
         options: { confirm: { type: 'string', value: '<email>', description: 'Your email address, typed out (required).' }, ...YES('the deletion') },
     },
     { path: ['account', 'cancel-deletion'], summary: 'Cancel a scheduled account deletion', positionals: [], options: {} },
+    { path: ['status'], summary: 'Show workspaces, agents and shared volumes', positionals: [], options: {} },
+    { path: ['volumes', 'open'], summary: 'Create or reuse a shared volume by name', positionals: [{ name: 'name', required: true }], options: { 'quota-gib': { type: 'string', value: '<GiB>', description: 'New volume quota (default 1 GiB).' }, ...VOLUME_WAIT } },
     // ---- project API key: egress and volumes ---------------------------------------------------------------
     {
         path: ['egress', 'get'],

package/dist/account-commands.js

@@ -1699,6 +1699,45 @@ export const ACCOUNT_HANDLERS = {
             ctx.io.stderr.write('more: shard volumes list --all\n');
         return 0;
     },
+    async status(ctx) {
+        const cloud = ctx.cloud();
+        const workspaces = [];
+        const volumes = [];
+        const agents = [];
+        let agentsAvailable = true;
+        const readAgents = async () => {
+            try {
+                let cursor = null;
+                do {
+                    const page = await cloud.request('GET', '/v1/agents', { query: { limit: 200, ...(cursor ? { cursor } : {}) } });
+                    agents.push(...page.data);
+                    cursor = page.next_cursor;
+                } while (cursor);
+            }
+            catch (err) {
+                if (!(err instanceof ShardfluxApiError && err.status === 404))
+                    throw err;
+                agentsAvailable = false;
+            }
+        };
+        await Promise.all([
+            (async () => { for await (const w of cloud.workspaces.listAll({ lifetime: 'any', purpose: 'any' }))
+                workspaces.push(w.data); })(),
+            (async () => { for await (const v of cloud.volumes.listAll({ includeOrgShared: true }))
+                volumes.push(v); })(), readAgents(),
+        ]);
+        const agentText = agentsAvailable
+            ? agents.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE'], agents.map((a) => [a.workspace_key, a.app, a.state, a.title])) : 'No agents.\n'
+            : 'Agents are unavailable on this API.\n';
+        out(ctx, `Workspaces\n${workspaces.length ? table(WORKSPACE_HEADERS, workspaces.map(workspaceRow)) : 'No workspaces.\n'}\nAgents\n${agentText}\nVolumes\n${volumes.length ? volumeTable(volumes) : 'No volumes.\n'}`, { workspaces, agents: agentsAvailable ? agents : null, volumes });
+        return 0;
+    },
+    async 'volumes open'(ctx, values, [name]) {
+        const quota = str(values['quota-gib']);
+        const r = await waitedVolume(ctx, () => ctx.cloud().volumes.open({ name: name, ...(quota ? { quotaGib: parsePositiveInt(quota, 'quota-gib', 65536) } : {}), wait: volumeWait(ctx, values) }));
+        out(ctx, `Volume ${r.volume.name} (${r.volume.id}) is ${r.volume.state}.\n${volumeDetail(r.volume)}`, r);
+        return 0;
+    },
     async 'volumes create'(ctx, values, [name]) {
         const quota = parsePositiveInt(need(values, 'quota-gib', '--quota-gib 20'), 'quota-gib', 100_000);
         const r = await waitedVolume(ctx, () => ctx.cloud().volumes.create({ name: name, quotaGib: quota, ...(values['org-shared'] === true ? { orgShared: true } : {}), wait: volumeWait(ctx, values) }));

package/dist/agent-commands.d.ts

@@ -0,0 +1,8 @@
+import type { CellClient, PtySession } from '@shardflux/sdk';
+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 const launchProject: Handler;
+export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -0,0 +1,223 @@
+import { agentReachability } from "./agent-reachability.js";
+import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
+import { createHash } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { UsageError } from "./errors.js";
+import { startProjectSync } from "./project-sync.js";
+import { AgentStateStore } from "./agent-state.js";
+import { attachTerminal, cellConnector } from "./agent-terminal.js";
+import { prepareProjectTemplate } from "./project-template-setup.js";
+import { projectIdentity, projectLabels } from "./project-identity.js";
+import { json } from "./format.js";
+import { resolveWorkspace } from "./commands.js";
+import { savedMachine } from "./filesystem-state.js";
+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";
+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) {
+    return `${slug.slice(0, 89)}-${createHash('sha256').update(identity).digest('hex').slice(0, 6)}`;
+}
+const missing = (error) => error instanceof ShardfluxApiError && error.status === 404;
+export async function projectTemplate(ctx, remote) {
+    if (!remote)
+        return 'coding';
+    try {
+        const binding = await ctx.cloud().request('GET', '/v1/project-templates', { query: { repo_remote: remote }, signal: ctx.signal });
+        if (typeof binding.template_slug !== 'string' || !binding.template_slug || !Number.isInteger(binding.version) || binding.version < 1)
+            throw new Error('project template response omitted a valid template_slug or version');
+        return `${binding.template_slug}@${binding.version}`;
+    }
+    catch (error) {
+        if (missing(error))
+            return 'coding';
+        throw error;
+    }
+}
+export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName) {
+    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) {
+        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}`}`);
+    }
+    try {
+        const session = await cell.pty.get(id);
+        if (active(session))
+            return session;
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+    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 } : {}),
+    });
+    if (launch.exitCode !== 0)
+        throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
+    let result;
+    try {
+        result = JSON.parse(launch.stdout);
+    }
+    catch {
+        throw new Error('agent launcher returned invalid JSON');
+    }
+    if (!result || result.pty_id !== id || !Number.isInteger(result.pid) || result.pid <= 0)
+        throw new Error('agent launcher omitted the expected PTY id or process id');
+    const session = await cell.pty.get(id);
+    if (!active(session))
+        throw new Error(`agent exited before attach: ${session.state}`);
+    return session;
+}
+async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = workspaceRepositoryPath(ws)) {
+    const store = new AgentStateStore(ctx.store.dir);
+    if (!ws.ready)
+        await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const attach = !(ctx.json || values.detach === true);
+    // Laptop-local MCP servers are reachable while a terminal is attached (L6); --json/--detach start no tunnels.
+    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);
+        store.save(project, app);
+        if (!attach) {
+            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({
+            ...(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 }),
+            invalidate: () => cell.tokens.invalidate(),
+            sleep: (ms, signal) => new Promise((resolve) => {
+                const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+                const timer = setTimeout(done, ms);
+                signal.addEventListener('abort', done, { once: true });
+                if (signal.aborted)
+                    done();
+            }),
+        });
+    }
+    finally {
+        await tunnels?.stop();
+    }
+}
+function requireTerminal(ctx) {
+    if (ctx.json || !ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode || !ctx.io.stdin.on)
+        throw new UsageError('agent terminal requires a TTY; use "shard agents list --json" to list sessions');
+}
+/** L2 registers this exact command name; absence keeps the launch independent of its merge order. */
+async function syncCredentials(ctx) {
+    const { HANDLERS } = await import("./handlers.js");
+    const sync = HANDLERS['agents credentials sync'];
+    if (sync) {
+        // The launcher reuses the registered sync command, keeping its metadata out of the terminal stream.
+        const code = await sync({ ...ctx, io: { ...ctx.io, stdout: { write: () => true } } }, {}, []);
+        if (code !== 0)
+            throw new Error('agent credentials sync failed');
+    }
+}
+export const launchProject = async (ctx, values, [path = './', explicitApp]) => {
+    if (explicitApp && explicitApp !== 'claude' && explicitApp !== 'codex')
+        throw new UsageError('agent app must be claude or codex');
+    let like = typeof values.like === 'string' ? await resolveWorkspace(ctx, values.like) : undefined;
+    const project = like ? { folder: path, slug: like.labels.shard_project || like.key.split('/')[0], remote: like.labels.repo_remote || null } : projectIdentity(path);
+    const projectKey = project.remote ?? (like ? project.slug : project.folder);
+    const store = new AgentStateStore(ctx.store.dir);
+    const app = explicitApp ?? store.app(projectKey, like?.labels.app === 'codex' ? 'codex' : 'claude');
+    const agent = typeof values.name === 'string' ? values.name : 'main';
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
+        throw new UsageError('agent name must match ^[a-z0-9][a-z0-9._-]{0,63}$');
+    if (agent !== 'main')
+        agentName(agent);
+    const labels = projectLabels(project, agent, app);
+    const cloud = ctx.cloud();
+    let existing = await cloud.workspaces.findByKey(`${project.slug}/${agent}`, { includeDeleted: false, signal: ctx.signal });
+    const owner = agent === 'main' ? existing : like ?? await cloud.workspaces.findByKey(`${project.slug}/main`, { includeDeleted: false, signal: ctx.signal });
+    if (owner && owner.labels.repo_remote !== undefined && owner.labels.repo_remote !== labels.repo_remote) {
+        // Two repositories with one name (acme/api, other/api): the later one gets the name plus a stable hash of its remote.
+        project.slug = disambiguatedSlug(project.slug, labels.repo_remote || project.folder);
+        labels.shard_project = project.slug;
+        existing = await cloud.workspaces.findByKey(`${project.slug}/${agent}`, { includeDeleted: false, signal: ctx.signal });
+    }
+    if (values.name !== undefined) {
+        if (existing)
+            throw new UsageError(`agent ${project.slug}/${agent} already exists`);
+        like ??= await cloud.workspaces.findByKey(`${project.slug}/main`, { includeDeleted: false, signal: ctx.signal }) ?? undefined;
+        if (!like)
+            throw new UsageError('a new agent needs the project main workspace; start the project first');
+    }
+    await syncCredentials(ctx);
+    const claudeReady = app === 'claude' ? await cloudClaudeLogin(ctx) : undefined;
+    if (app === 'claude' && !claudeReady)
+        requireClaudeTerminal(ctx);
+    if (!ctx.json && values.detach !== true)
+        requireTerminal(ctx);
+    // A `like` agent inherits the main workspace's template; only a project's own workspace prepares one (L7).
+    const prepared = like ? undefined : await prepareProjectTemplate(ctx, project, existing);
+    const ws = await cloud.workspaces.open({
+        ...agentReachability(values),
+        key: `${project.slug}/${agent}`, ...(like ? { like: like.id } : { template: prepared.template }),
+        labels: { ...existing?.labels, ...labels, ...prepared?.labels, repo_path: projectWorkspacePath(project) }, agentLabel: ctx.agentLabel,
+        ...(!existing && agent !== 'main' ? { retention: { delete_after_idle_days: 7 } } : {}),
+        wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal },
+    });
+    if (app === 'claude' && !claudeReady)
+        await loginClaudeInWorkspace(ctx, ws);
+    if (!(await savedMachine(ctx))?.template)
+        await syncAgentConfig(ctx, ws);
+    // Extra/like agents return work through hidden refs; only the main owns local sync.
+    const sync = agent === 'main' && !like ? await startProjectSync(ctx, ws, project) : undefined;
+    try {
+        if (!sync) {
+            await ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs }).files.mkdir(workspaceRepositoryPath(ws), { parents: true });
+            await seedAgentRepository(ctx, ws, project.folder, { populate: true });
+        }
+        await rememberGitAgent(ctx, ws, project.folder);
+        return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash, sync?.root);
+    }
+    finally {
+        await sync?.stop();
+    }
+};
+export const AGENT_HANDLERS = {
+    async 'agents open'(ctx, values, [agent = 'main']) {
+        if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
+            throw new UsageError('--app must be claude or codex');
+        if (values.in !== undefined && values.in !== 'terminal') {
+            const { HANDLERS } = await import("./handlers.js");
+            const target = typeof values.in === 'string' ? HANDLERS[`agents open ${values.in}`] : undefined;
+            if (!target)
+                throw new UsageError('--in must be an available open target');
+            return target(ctx, values, [agent]);
+        }
+        await syncCredentials(ctx);
+        let ws;
+        if (agent.includes('/'))
+            ws = await ctx.cloud().workspace(agent, { create: false }).open();
+        else {
+            const project = projectIdentity('./');
+            if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
+                throw new UsageError('agent must be a workspace key or an agent name');
+            ws = await ctx.cloud().workspace(`${project.slug}/${agent}`, { create: false }).open();
+        }
+        if (values.reachable !== undefined)
+            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 (!ctx.json && values.detach !== true)
+            requireTerminal(ctx);
+        if (ws.labels.shard_layer !== 'machine' && !(await savedMachine(ctx))?.template)
+            await syncAgentConfig(ctx, ws);
+        return terminal(ctx, ws, app, (ws.labels.agent ?? agent).split('/').at(-1), projectKey, values);
+    },
+};

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

@@ -0,0 +1,23 @@
+export type ConfigIssue = {
+    item: string;
+    reason: string;
+};
+export type ConfigFile = {
+    content: Buffer;
+    mode: string;
+};
+export type ConfigFiles = Map<string, ConfigFile>;
+export type ObjectValue = Record<string, unknown>;
+export declare const object: (v: unknown) => ObjectValue;
+export declare const text: (v: unknown) => string | undefined;
+export declare const absent: (e: unknown) => boolean;
+export declare function readOptional(file: string): Promise<Buffer | undefined>;
+export declare function readObject(file: string): Promise<ObjectValue | undefined>;
+/** Dereference skill symlinks, including ones shared from another local directory, but never traverse a cycle. */
+export declare function collectTree(source: string, dest: string, files: ConfigFiles, issues: ConfigIssue[], parents?: Set<string>): Promise<void>;
+export declare function collectUserFiles(home: string, issues: ConfigIssue[]): Promise<ConfigFiles>;
+export declare function macBinary(bytes: Buffer): boolean;
+/** Preserve v2 install metadata and user-scope records, and copy just the trees needed to load them on Linux. */
+export declare function collectPlugins(home: string, remoteHome: string, files: ConfigFiles, issues: ConfigIssue[]): Promise<Set<string>>;
+/** Only rewrite paths to files we actually send. Missing laptop paths are never made to look portable. */
+export declare function rewritePaths(value: unknown, home: string, remoteHome: string, files: ConfigFiles, issues: ConfigIssue[], item: string): unknown;