@shardflux/cli 0.13.6 → 0.14.1

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.6';
+export const CLI_VERSION = '0.14.1';
 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).' },
@@ -139,10 +139,29 @@ const SECRET_PERMISSIONS = {
     'allow-project': { type: 'string', multiple: true, value: '<project-id>', description: 'Organization secrets: projects whose workspaces may use it (repeatable). Default: none until granted.' },
     'all-projects': { type: 'boolean', description: 'Organization secrets: every project of the organization may use it.' },
 };
+// Cloud agents: a VM is the coding template, then the machine, then the project template.
+const LAYER_HELP = {
+    machine: 'Your machine is what every cloud agent starts with: tools, credentials, dotfiles, browser logins, git identity, Claude/Codex settings and skills. "shard machine" opens its VM; change it there (or in any agent’s VM), then run "shard machine save". It is saved from an agent’s VM, so it always keeps Claude Code, Codex and the agent runtime.',
+    template: 'The project template is this repository’s layer: toolchains, dependencies, services and project secrets. Setup after "shard ./" saves it; "shard template save" saves the current agent VM’s project changes. It is saved from an agent’s VM; "shard templates" builds templates for your own app’s workspaces instead.',
+};
 const KEY_COMMANDS = [
+    { path: ['conversations', 'list'], summary: 'List project conversations', positionals: [], options: {
+            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, state: { type: 'string', value: '<state>', description: 'Conversation state.' },
+            parent: { type: 'string', value: '<id>', description: 'Children of this conversation.' }, limit: { type: 'string', value: '<count>', description: 'Page size.' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' }
+        } },
+    { path: ['conversations', 'resume'], summary: 'Resume a saved conversation in a fresh VM', positionals: [{ name: 'id', required: true }], options: {} },
+    { path: ['conversations', 'reader'], summary: 'Open a read-only project space reader', positionals: [{ name: 'project_id', required: true }], options: {} },
+    { path: ['conversations', 'get'], summary: 'Show a conversation and its current VM', positionals: [{ name: 'id', required: true }], options: {} },
+    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', required: true, variadic: true, words: true }], options: {} },
+    { path: ['conversations', 'wait'], summary: 'Wait for a result or question', positionals: [{ name: 'id', required: true }], options: {
+            until: { type: 'string', value: '<states>', description: 'Comma-separated conversation states.' }, timeout: { type: 'string', value: '<seconds>', description: 'Wait for 0..900 seconds (default 900).' }
+        } },
+    { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
+    { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
     ...['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], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {},
+            description: LAYER_HELP[level] },
+        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, description: LAYER_HELP[level], 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.' },
             } },
@@ -958,7 +977,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'init'],
         summary: 'Write a template.yaml that starts from a base template',
-        description: 'The file is the recipe v2 document: languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
+        description: 'For your own app’s workspaces (SDK/API). Cloud agents do not use it: their machine and project templates are saved from an agent’s VM with "shard machine save" and "shard template save", and a repository bound to another template is refused (template_not_agent_capable). The file is the recipe v2 document: languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
         positionals: [],
         options: {
             base: { type: 'string', value: '<slug[@version]>', description: 'Base template (required), e.g. ubuntu-24.04; without @version, the version open resolves to now.' },
@@ -970,7 +989,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'build'],
         summary: 'Build a template from template.yaml: upload its local files and folders, then build it',
-        description: 'Folders named by "from" are packed as a reproducible tar and uploaded with files unless the organization already has the same bytes. The version stays unpublished (test it with "shard templates test") unless --publish. Progress goes to stderr.',
+        description: 'For your own app’s workspaces (SDK/API). Cloud agents do not use it: their machine and project templates are saved from an agent’s VM with "shard machine save" and "shard template save", and a repository bound to another template is refused (template_not_agent_capable). Folders named by "from" are packed as a reproducible tar and uploaded with files unless the organization already has the same bytes. The version stays unpublished (test it with "shard templates test") unless --publish. Progress goes to stderr.',
         positionals: [{ name: 'file', required: true }],
         options: {
             slug: { type: 'string', value: '<slug>', description: 'Organization template to build into (default: the name of the directory holding the file). Created by the first build.' },
@@ -1080,7 +1099,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'draft', 'open'],
         summary: 'Open the draft of an organization template (a layered workspace to edit live)',
-        description: 'One live draft per template. Edit it with "shard ws exec|files ... <draft key>", capture states, open test instances, then publish it as the next version.',
+        description: 'For your own app’s workspaces (SDK/API). Cloud agents do not use it: their machine and project templates are saved from an agent’s VM with "shard machine save" and "shard template save", and a repository bound to another template is refused (template_not_agent_capable). One live draft per template. Edit it with "shard ws exec|files ... <draft key>", capture states, open test instances, then publish it as the next version.',
         positionals: [SLUG],
         options: {
             base: { type: 'string', value: '<slug@version>', description: 'Version to start from (default: the template’s latest published version; required for a new template).' },
@@ -1152,14 +1171,15 @@ 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, 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,
+    path: ['<path>'], summary: 'Start a conversation in its own cloud VM',
+    description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
+    positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: { ...AGENT_OPTIONS, new: { type: 'boolean', description: 'Start a new conversation.' }, resume: { type: 'boolean', description: 'Continue a conversation from this project.' } },
 };
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };
 const AGENT_COMMANDS = [
+    { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
     { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: { remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' } } },
-    ...['claude-desktop', 'codex-app', 'web'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
+    ...['claude-desktop', 'codex-app', 'web', 't3'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
     { path: ['ssh-proxy'], summary: 'Forward SSH standard IO to a managed workspace', positionals: [{ name: 'host', required: true }], options: {} },
     ...['worktree', 'merge', 'keep', 'discard', 'restore'].map((action) => ({
         path: ['agents', action], summary: { worktree: 'Open agent work in a local worktree', merge: 'Merge agent work into the current branch and clean up', keep: 'Keep agent work as a branch and clean up', discard: 'Delete an agent and its local work', restore: 'Restore archived work as a local branch within 30 days' }[action],
@@ -1169,12 +1189,13 @@ const AGENT_COMMANDS = [
             ...(action === 'keep' ? { push: { type: 'boolean', description: 'Push the kept branch to origin and open a PR when gh is installed.' } } : {}),
         },
     })),
-    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal>', description: 'Where to open the session (default terminal).' } } },
+    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|claude-desktop|codex-app|web|t3>', description: 'Where to open the session (default terminal).' } } },
     { path: ['agents', 'new'], summary: 'Start a session or a named agent', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
             name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
+            in: { type: 'string', value: '<terminal|claude-desktop|codex-app|t3>', description: 'Where to open the new agent (default terminal).' },
             like: { type: 'string', value: '<id|key>', description: 'Copy the workspace configuration onto a fresh disk.' },
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
@@ -1193,6 +1214,7 @@ const MENUBAR_COMMANDS = ['start', 'stop', 'status'].map(action => ({
 export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
     menubar: 'macOS menu bar app',
+    conversations: 'Project conversations, branches and messages',
     agents: 'Cloud agent sessions and copied credentials',
     auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
     'auth password': 'Change or reset your password',
@@ -1218,6 +1240,8 @@ const GROUPS = {
     templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff), develop them in a draft, and publish or archive versions',
 };
 const ALIASES = {
+    c: 'conversations',
+    conversation: 'conversations',
     ws: 'workspaces',
     workspace: 'workspaces',
     ops: 'operations',
@@ -1361,6 +1385,8 @@ function toParseArgsOptions(opts) {
  * returns help text for --help, bare groups and non-TTY bare `shard`.
  */
 export function parseCommandLine(argv, options = {}) {
+    if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
+        return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');
     const head = terminator < 0 ? argv : argv.slice(0, terminator);
     const leading = [];
@@ -1551,8 +1577,9 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'machine', 'template', 'agents', 'ssh-proxy', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
-    { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'ssh-proxy'] },
+    { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
+    { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
 ];
 export function topHelp() {
@@ -1575,7 +1602,19 @@ export function topHelp() {
         `  shard auth verify-email '<link from the email>'`,
         `  printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`,
         '  shard setup                                   # organization, project and an API key, saved',
-        '  shard ws open demo --template python-node-browser',
+        '  shard ./                                      # a cloud agent for this folder',
+        '  shard ws open demo --template python-node-browser   # or a workspace for your app (SDK/API)',
+        '',
+        'Cloud agents (Claude Code or Codex in its own VM, with your setup):',
+        '  shard ./                                      # a conversation on this folder’s repository: Claude Code in its own VM (shard ./ codex: Codex; --resume: a saved one)',
+        '  shard machine save                            # what every agent starts with: tools, logins, dotfiles, Claude/Codex config',
+        '  shard template save                           # this project: toolchains, dependencies, services, project secrets',
+        '  A VM is the coding template, then your machine, then the project template. Setup after shard ./ saves the',
+        '  project template; machine and project templates are always saved from an agent’s VM, so they keep Claude Code,',
+        '  Codex and the agent runtime. "shard templates" is for your own app’s workspaces, not for agents: a repository',
+        '  bound to such a template is refused (template_not_agent_capable).',
+        '  In the VM, Claude Code and Codex have Shardflux computer use next to their own tools: the shardflux-computer MCP',
+        '  server’s computer and computer_batch drive the VM’s desktop (start programs with DISPLAY=:1 setsid -f).',
         ...sections,
         '',
         'Aliases: ws = workspaces, ops = operations, org = orgs, keys = api-keys; "shard workspaces files|operations|executions ..." also works.',

package/dist/command-center-actions.js

@@ -8,6 +8,9 @@ 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";
+import { randomUUID } from 'node:crypto';
+import { prepareAgentMachine } from "./agent-machine.js";
+import { OperationFailedError } from '@shardflux/sdk';
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -19,7 +22,7 @@ export async function availableTargets(ctx) {
     if (code !== 0)
         throw new Error('open target detection failed');
     const result = JSON.parse(output);
-    return ['terminal', ...result.targets.filter(target => ['claude-desktop', 'codex-app', 'web'].includes(target) && HANDLERS[`agents open ${target}`])];
+    return ['terminal', ...result.targets.filter(target => ['claude-desktop', 'codex-app', 'web', 't3'].includes(target) && HANDLERS[`agents open ${target}`])];
 }
 export async function agentAction(ctx, action, values, args) {
     const { HANDLERS } = await import("./handlers.js");
@@ -42,19 +45,39 @@ export const CENTER_HANDLERS = {
         const source = await resolveWorkspace(ctx, ref);
         const key = `${source.labels.shard_project || source.key.split('/')[0]}/${name}`;
         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) };
+            agent_pty_name: source.labels.agent_pty_name || agentName(source.key, source.labels), t3_environment_id: randomUUID() };
         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 },
+        }).catch(async (error) => {
+            // Older cells can copy an external agent workspace and then fail their
+            // PTY-only repair. Keep the failure, but never leave the copy's T3 identity shared.
+            const forkError = error instanceof OperationFailedError ? error.operation.error : undefined;
+            const details = forkError?.details;
+            if (error instanceof OperationFailedError && error.operation.kind === 'fork' && error.errorCode === 'agent_fork_failed' && details && typeof details === 'object' && !Array.isArray(details) && 'workspace_state' in details && details.workspace_state === 'running' && error.operation.workspace_id) {
+                const child = await ctx.cloud().workspaces.get(error.operation.workspace_id);
+                if (child.key !== key || child.data.forked_from_workspace_id !== source.id || child.labels?.t3_environment_id !== labels.t3_environment_id)
+                    throw new Error(`Fork ${key} identity could not be reconciled: copied workspace does not match this fork`, { cause: error });
+                await prepareAgentMachine(ctx, child);
+                await ctx.cloud().workspaces.setRetention(child.id, { delete_after_idle_days: 7 });
+                if (ctx.json && forkError)
+                    forkError.details = { ...details, workspace_identity_reconciled: true };
+                else
+                    ctx.io.stderr.write(`Copied ${key} has its own T3 identity; fork operation ${error.operationId} still failed.\n`);
+            }
+            throw error;
         });
         const agent = result.operation.result?.agent;
         const receipt = agent && typeof agent === 'object' ? agent : undefined;
-        if (result.operation.state === 'succeeded' && (!receipt ||
+        const workspaceOnly = result.operation.result?.agent_fork_mode === 'workspace' && !agent;
+        if (result.operation.state === 'succeeded' && !workspaceOnly && (!receipt ||
             ['id', 'workspace_key', 'session_id'].some(field => typeof receipt[field] !== 'string' || !receipt[field]) ||
             receipt.workspace_key !== key || !['working', 'waiting'].includes(String(receipt.state)))) {
             throw new Error(`Fork ${key} has no independent agent session receipt`);
         }
+        if (result.operation.state === 'succeeded')
+            await prepareAgentMachine(ctx, result.workspace);
         await ctx.cloud().workspaces.setRetention(result.workspace.id, { delete_after_idle_days: 7 });
         if (agent)
             rememberLaunch(ctx, result.workspace.id, started);

package/dist/command-center.js

@@ -2,6 +2,8 @@ import { json } from "./format.js";
 import { UsageError } from "./errors.js";
 import { projectIdentity } from "./project-identity.js";
 import { AgentStateStore } from "./agent-state.js";
+import { installedTargets } from "./agent-targets.js";
+import { randomUUID } from 'node:crypto';
 import { agentAction, availableTargets } from "./command-center-actions.js";
 import { centerRows, loadCenter } from "./command-center-model.js";
 import { AnsiRenderer, renderCenter } from "./command-center-renderer.js";
@@ -259,11 +261,16 @@ export async function showCenter(ctx, scope, options = {}) {
             menu('Start here', [app, app === 'claude' ? 'codex' : 'claude'].map(app => ({ label: `Start ${app === 'claude' ? 'Claude' : 'Codex'} here`, run: () => dispatch('new', { path: scope.folder, app }, [], true) })));
             return;
         }
-        if (key === 'enter')
-            await dispatch('open', { app, project, in: 'terminal' }, [row.key], true);
+        if (key === 'enter') {
+            const target = new AgentStateStore(ctx.store.dir).target(project, ['terminal', ...installedTargets(ctx.io.env).targets]);
+            await dispatch('open', { app, project, in: target }, [row.key], true);
+        }
         else if (key === 'o') {
             const targets = await availableTargets(ctx);
-            menu('Open in…', targets.map(target => ({ label: target, run: () => dispatch('open', { app, project, in: target }, [row.key], true) })));
+            menu('Open in…', targets.map(target => ({ label: target, run: async () => {
+                    new AgentStateStore(ctx.store.dir).saveTarget(project, target);
+                    await dispatch('open', { app, project, in: target }, [row.key], true);
+                } })));
         }
         else if (key === 'n') {
             menu('New session', ['claude', 'codex'].map(app => ({ label: `${app === 'claude' ? 'Claude' : 'Codex'} (reattach if running)`, run: () => dispatch('new', { app, project }, [row.key], true) })));
@@ -310,8 +317,12 @@ 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 }, []);
+        return agentAction(ctx, 'new', { ...values, path, app, ...(values.new === true ? { name: `agent-${randomUUID().slice(0, 8)}` } : {}) }, []);
     const scope = path ? projectIdentity(path) : undefined;
+    if (scope && values.new === true) {
+        const target = new AgentStateStore(ctx.store.dir).target(scope.remote ?? scope.folder, ['terminal', ...installedTargets(ctx.io.env).targets]);
+        return agentAction(ctx, 'new', { ...values, path: scope.folder, name: `agent-${randomUUID().slice(0, 8)}`, in: target === 'web' ? 'terminal' : target }, []);
+    }
     if (ctx.json) {
         const data = await loadCenter(ctx);
         const rows = centerRows(data, scope);
@@ -319,5 +330,10 @@ export const commandCenter = async (ctx, values, [path, app]) => {
         ctx.io.stdout.write(json({ projects, workspaces: data.workspaces.filter(w => rows.some(r => r.workspace?.id === w.id)), agents: data.agents.filter(a => rows.some(r => r.agent?.id === a.id)) }));
         return 0;
     }
+    if (scope) {
+        const target = new AgentStateStore(ctx.store.dir).target(scope.remote ?? scope.folder, ['terminal', ...installedTargets(ctx.io.env).targets]);
+        if (target === 't3')
+            return agentAction(ctx, 'new', { ...values, path: scope.folder, in: target }, []);
+    }
     return showCenter(ctx, scope, { approvals: values.approvals === true, ...(app === 'claude' || app === 'codex' ? { app } : {}) });
 };

package/dist/conversation-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx, Handler } from './commands.js';
+export declare function conversationClient(ctx: Ctx): import("@shardflux/sdk").Shardflux | import("@shardflux/sdk").ShardfluxAccount;
+export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -0,0 +1,36 @@
+import { out, str } from "./commands.js";
+import { UsageError } from "./errors.js";
+export function conversationClient(ctx) {
+    const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
+    return key || !session ? ctx.cloud() : ctx.account();
+}
+export const CONVERSATION_HANDLERS = {
+    async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${r.conversation.title}: resumed.\n`, r); return 0; },
+    async 'conversations reader'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.spaceReader(id, { signal: ctx.signal }); out(ctx, `${r.workspace.workspace_key}\n`, r); return 0; },
+    async 'conversations list'(ctx, values) {
+        const state = str(values.state);
+        const page = await conversationClient(ctx).conversations.list({ projectId: str(values.project), state, parentId: str(values.parent), cursor: str(values.cursor), limit: values.limit ? Number(values.limit) : undefined });
+        out(ctx, page.data.map(c => `${c.id}\t${c.title}\t${c.state}\t${c.branch}`).join('\n') + '\n', page);
+        return 0;
+    },
+    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n`, c); return 0; },
+    async 'conversations send'(ctx, _values, [id, text]) { const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal }); out(ctx, `Message sent (${r.seq}).\n`, r); return 0; },
+    async 'conversations wait'(ctx, values, [id]) {
+        const seconds = values.timeout === undefined ? 900 : Number(values.timeout);
+        if (!Number.isInteger(seconds) || seconds < 0 || seconds > 900)
+            throw new UsageError('--timeout must be 0..900 seconds.');
+        const until = str(values.until)?.split(',');
+        const r = await conversationClient(ctx).conversations.wait(id, { until, timeoutSeconds: seconds, signal: ctx.signal });
+        out(ctx, 'timeout' in r ? 'Still working.\n' : `${r.conversation.title}: ${r.event.kind}\n${r.event.question ?? r.event.result?.summary ?? ''}\n`, r);
+        return 0;
+    },
+    async 'conversations land'(ctx, values, [id, action]) {
+        if (!['merge', 'pr', 'keep', 'discard'].includes(action))
+            throw new UsageError('Choose merge, pr, keep or discard.');
+        const r = await conversationClient(ctx).conversations.land(id, action, { into: str(values.into), signal: ctx.signal });
+        out(ctx, `${r.title}: ${r.landed.how}\n`, r);
+        return 0;
+    },
+    async 'conversations move'(ctx, _values, [id, to]) { const r = await conversationClient(ctx).conversations.move(id, to, { signal: ctx.signal }); out(ctx, `Move scheduled for the end of the turn.\n`, r); return 0; },
+};

package/dist/conversation-local-resume.d.ts

@@ -0,0 +1,8 @@
+import type { Ctx } from './commands.js';
+import type { Conversation } from './conversations.js';
+/** Native local continuation uses a worktree. It never checks out the saved branch in the user's main tree. */
+export declare function prepareLocalResume(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, c: Conversation, folder: string): Promise<{
+    folder: string;
+    argv: string[];
+}>;
+export declare function localResumeTerminal(ctx: Ctx, c: Conversation, folder: string): Promise<number>;

package/dist/conversation-local-resume.js

@@ -0,0 +1,56 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { conversationName } from "./conversations.js";
+import { gitRunner } from "./agent-git.js";
+import { transcriptDestination, rewriteTranscript } from "./conversation-stash.js";
+import { writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
+import { withTargetLock } from "./target-lock.js";
+/** Native local continuation uses a worktree. It never checks out the saved branch in the user's main tree. */
+export async function prepareLocalResume(ctx, c, folder) {
+    return withTargetLock(join(ctx.store.dir, 'conversation-worktree-lock'), async () => {
+        if (!c.harness_session_id || !['done', 'archived'].includes(c.state))
+            throw new UsageError('This conversation has no ended native session.');
+        const run = gitRunner(folder, { ...process.env, ...ctx.io.env }, ctx.signal), name = conversationName(c);
+        const root = join(folder, '.shard', 'worktrees', name);
+        // This ref was fetched before the handoff receipt. Missing work is an error, never an empty branch.
+        await run(['rev-parse', '--verify', `refs/remotes/shardflux/${name}^{commit}`]);
+        if (!existsSync(root)) {
+            mkdirSync(dirname(root), { recursive: true });
+            const exists = await run(['show-ref', '--verify', `refs/heads/${c.branch}`]).then(() => true, () => false);
+            await run(['-c', 'core.hooksPath=/dev/null', 'worktree', 'add', ...(exists ? [] : ['-b', c.branch]), root, exists ? c.branch : `refs/remotes/shardflux/${name}`]);
+            rememberConversationWorktree(ctx, c, folder, root);
+        }
+        else
+            checkConversationWorktree(ctx, c, folder, root);
+        const work = gitRunner(root, { ...process.env, ...ctx.io.env }, ctx.signal);
+        if (await work(['symbolic-ref', '--short', 'HEAD']) !== c.branch)
+            throw new UsageError('The local worktree belongs to another branch.');
+        if (c.harness === 'claude') {
+            const filename = `${c.harness_session_id}.jsonl`;
+            const source = transcriptDestination(c, folder, filename, ctx.io.env), dest = transcriptDestination(c, root, filename, ctx.io.env);
+            if (!existsSync(source))
+                throw new UsageError('Native transcript handoff is missing.');
+            if (!existsSync(dest))
+                writePrivateFile(dirname(dest), dest, Buffer.from(rewriteTranscript(readFileSync(source), folder, root)).toString('utf8'));
+            return { folder: root, argv: ['claude', '--resume', c.harness_session_id] };
+        }
+        return { folder: root, argv: ['codex', 'resume', c.harness_session_id, '--all', '-C', root] };
+    }, ctx.signal);
+}
+export async function localResumeTerminal(ctx, c, folder) {
+    if (!ctx.io.stdin.isTTY || ctx.json)
+        throw new UsageError('Native local resume requires a terminal.');
+    const launch = await prepareLocalResume(ctx, c, folder);
+    const child = spawn(launch.argv[0], launch.argv.slice(1), { cwd: launch.folder, env: { ...process.env, ...ctx.io.env }, stdio: 'inherit' });
+    return new Promise((resolve, reject) => {
+        const abort = () => child.kill('SIGTERM');
+        ctx.signal.addEventListener('abort', abort, { once: true });
+        child.once('error', e => { ctx.signal.removeEventListener('abort', abort); reject(e); });
+        child.once('exit', code => { ctx.signal.removeEventListener('abort', abort); resolve(code ?? 130); });
+        if (ctx.signal.aborted)
+            abort();
+    });
+}

package/dist/conversation-local.d.ts

@@ -0,0 +1,7 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Conversation } from './conversations.js';
+export declare function tryConversationLocally(ctx: Ctx, c: Conversation, folder: string): Promise<{
+    folder: string;
+    stop(): Promise<void>;
+}>;
+export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-local.js

@@ -0,0 +1,61 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { getConversation, resolveConversation, conversationWorkspace, localConversations } from "./conversations.js";
+import { ensureConversationWorktree, devicePort } from "./device-bridge.js";
+import { startProjectSync } from "./project-sync.js";
+import { projectIdentity } from "./project-identity.js";
+import { UsageError } from "./errors.js";
+import { out } from "./commands.js";
+import { join } from 'node:path';
+import { writePrivateFile } from "./credentials.js";
+export async function tryConversationLocally(ctx, c, folder) {
+    const ws = await conversationWorkspace(ctx, c), worktree = await ensureConversationWorktree(ctx, c, folder, ws);
+    const project = { ...projectIdentity(folder), folder: worktree };
+    const sync = await startProjectSync(ctx, ws, project, { root: c.worktree_path, agent: c.key.split('/').at(-1), seed: false });
+    const ports = [];
+    try {
+        for (const port of c.ports ?? [])
+            ports.push(await devicePort(ws, ws.cell(), 'port_forward', { remote_port: port, local_port: port }, ctx.signal));
+        return { folder: worktree, async stop() { try {
+                await sync.stop();
+            }
+            finally {
+                await Promise.all(ports.map(p => p.stop()));
+                ws.cell().close();
+            } } };
+    }
+    catch (e) {
+        await sync.stop();
+        await Promise.all(ports.map(p => p.stop()));
+        throw e;
+    }
+}
+export const CONVERSATION_HANDLERS = {
+    async 'conversations try'(ctx, values, [ref]) {
+        if (!ref)
+            throw new UsageError('Choose a conversation.');
+        const c = await resolveConversation(ctx, ref), record = localConversations(ctx)[c.id];
+        if (values.stop === true) {
+            const dir = join(ctx.store.dir, 'device-stops');
+            writePrivateFile(dir, join(dir, `${c.id}.json`), JSON.stringify({ api_url: ctx.apiUrl }) + '\n');
+            out(ctx, `Stopping local sync for ${c.key}.\n`, { conversation_id: c.id, stopping: true });
+            return 0;
+        }
+        const folder = typeof values.path === 'string' ? values.path : record?.folder;
+        if (!folder)
+            throw new UsageError('Use --path to name the local project checkout.');
+        const handle = await tryConversationLocally(ctx, c, folder);
+        out(ctx, `Trying ${c.key} in ${handle.folder}. Press Ctrl-C to stop sync.\n`, { conversation: c, folder: handle.folder });
+        try {
+            while (!ctx.signal.aborted) {
+                const next = await getConversation(ctx, c.id);
+                if (next.state === 'done' || next.state === 'archived' || next.workspace_id !== c.workspace_id)
+                    break;
+                await delay(1000, undefined, { signal: ctx.signal }).catch(() => undefined);
+            }
+        }
+        finally {
+            await handle.stop();
+        }
+        return 0;
+    },
+};

package/dist/conversation-router.d.ts

@@ -0,0 +1,12 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare const ROUTER_CONFIG = "/home/user/.config/shardflux/conversation-router.json";
+export declare function routerConfiguration(ctx: Pick<Ctx, 'apiUrl'>, ws: Workspace, commit: string, cwd?: string): {
+    api_url: string;
+    project_id: string;
+    repo_remote: string;
+    cwd: string;
+    base_commit: string;
+};
+/** CVE reads this config on every request; old guests keep their existing SSH path. */
+export declare function prepareDesktopRouter(ctx: Ctx, source: Workspace): Promise<Workspace>;

package/dist/conversation-router.js

@@ -0,0 +1,92 @@
+import { randomUUID } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { workspaceRepositoryPath, projectWorkspacePath, HISTORY_BUNDLE_LIMIT } from "./agent-repository.js";
+import { writeSyncBlob } from "./project-sync-transfer.js";
+import { UsageError } from "./errors.js";
+import { conversationClient } from "./conversation-commands.js";
+export const ROUTER_CONFIG = '/home/user/.config/shardflux/conversation-router.json';
+export function routerConfiguration(ctx, ws, commit, cwd = workspaceRepositoryPath(ws)) {
+    const remote = ws.labels.repo_remote || ws.labels.shard_repo_remote;
+    if (!ws.data.project_id || !remote || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(commit) || !cwd.startsWith('/home/user/'))
+        throw new UsageError('Project routing requires a project, repository and its actual commit.');
+    return { api_url: ctx.apiUrl, project_id: ws.data.project_id, repo_remote: remote, cwd, base_commit: commit };
+}
+/** CVE reads this config on every request; old guests keep their existing SSH path. */
+export async function prepareDesktopRouter(ctx, source) {
+    const cloud = conversationClient(ctx);
+    try {
+        await cloud.conversations.list({ projectId: source.data.project_id, limit: 1 });
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && (error.status === 404 || error.status === 503 && error.details?.reason === 'conversations_unavailable'))
+            return source;
+        throw error;
+    }
+    const cell = source.cell();
+    const probe = await cell.exec.run(['sf-agent', 'app-router-info'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal: ctx.signal });
+    if (probe.exitCode !== 0)
+        return source;
+    let info;
+    try {
+        info = JSON.parse(probe.stdout);
+    }
+    catch {
+        return source;
+    }
+    if (info.version !== 1)
+        return source;
+    const mounted = await cell.exec.run(['test', '-d', '/shardflux/project/git/hub.git'], { timeoutMs: 10_000, signal: ctx.signal });
+    if (mounted.exitCode !== 0)
+        return source;
+    const head = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), 'rev-parse', 'HEAD'], { timeoutMs: 10_000, signal: ctx.signal });
+    if (head.exitCode !== 0)
+        throw new UsageError('The project repository has no commit to route from.');
+    const commit = head.stdout.trim(), config = routerConfiguration(ctx, source, commit);
+    const project = source.key.split('/')[0], key = `${project}/router`;
+    let router = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+    if (router && (router.key !== key || router.data.project_id !== config.project_id || router.labels.shard_router !== 'project' || router.labels.repo_remote !== config.repo_remote))
+        throw new UsageError('The project router key belongs to another workspace.');
+    const created = !router;
+    const labels = { ...source.labels, shard_project: project, shard_router: 'project', agent: 'router', shard_agent: 'router', repo_remote: config.repo_remote, repo_path: projectWorkspacePath({ slug: project }) };
+    delete labels.shard_conversation;
+    delete labels.shard_branch;
+    if (!router)
+        router = await cloud.workspaces.open({ key, like: source.id, labels, wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
+    if (!router.ready)
+        await router.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    const destination = router.cell(), root = workspaceRepositoryPath(router);
+    const archive = `/tmp/shard-router-${randomUUID()}.bundle`;
+    try {
+        if (created) {
+            const packed = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), '-c', 'core.hooksPath=/dev/null', 'bundle', 'create', archive, 'HEAD'], { timeoutMs: 120_000, signal: ctx.signal });
+            if (packed.exitCode !== 0)
+                throw new Error(`Project router seed failed: ${packed.stderr.trim()}`);
+            const info = await cell.files.stat(archive);
+            if (info.size > HISTORY_BUNDLE_LIMIT)
+                throw new UsageError('Project router history exceeds the 256 MiB transfer bound.');
+            const bytes = await cell.files.read(archive, { length: info.size + 1 });
+            if (bytes.length !== info.size)
+                throw new Error('Project router history changed during copying.');
+            await writeSyncBlob(destination, archive, bytes);
+            await destination.files.mkdir(root, { parents: true });
+            const imported = await destination.exec.run(['sh', '-c', 'set -eu; git -C "$1" init -q; git -C "$1" -c core.hooksPath=/dev/null fetch -q "$2" HEAD:refs/heads/shardflux-router; git -C "$1" -c core.hooksPath=/dev/null checkout -q shardflux-router', 'sh', root, archive], { timeoutMs: 120_000, signal: ctx.signal });
+            if (imported.exitCode !== 0)
+                throw new Error(`Project router repository could not be prepared: ${imported.stderr.trim()}`);
+        }
+        const seed = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), '-c', 'core.hooksPath=/dev/null', 'push', '/shardflux/project/git/hub.git', `${commit}:refs/shard/router/seeds/${commit}`], { timeoutMs: 120_000, signal: ctx.signal });
+        if (seed.exitCode !== 0)
+            throw new Error(`Project router hub seed failed: ${seed.stderr.trim()}`);
+        await destination.files.mkdir('/home/user/.config/shardflux', { parents: true, mode: '0700' });
+        await destination.files.write(ROUTER_CONFIG, JSON.stringify({ ...config, cwd: root }) + '\n', { mode: '0600' });
+        return router;
+    }
+    catch (e) {
+        if (created)
+            await cloud.workspaces.delete(router.id).catch(() => undefined);
+        throw e;
+    }
+    finally {
+        await cell.files.remove(archive).catch(() => undefined);
+        await destination.files.remove(archive).catch(() => undefined);
+    }
+}

package/dist/conversation-stash.d.ts

@@ -0,0 +1,11 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Conversation, LocalConversation } from './conversations.js';
+export declare function rewriteTranscript(bytes: Uint8Array, remoteCwd: string, localCwd: string): Uint8Array;
+export declare function transcriptDestination(c: Conversation, folder: string, filename: string, env: Record<string, string | undefined>): string;
+/** Keep growing copies away from native session discovery until the control plane ends the conversation. */
+export declare function mirrorConversation(ctx: Ctx, record: LocalConversation, source: Workspace): Promise<void>;
+export declare function handoffConversation(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, c: Conversation, folder: string, dir: string, source?: Pick<Workspace, 'key'> | {
+    hub: string;
+}): Promise<void>;
+export declare function mirrorProjectConversations(ctx: Ctx, mirrored?: Map<string, string>): Promise<void>;