@shardflux/cli 0.28.0 → 0.28.2

package/dist/board-commands.js

@@ -1,4 +1,5 @@
-import { out, principal, str, strs } from "./commands.js";
+import { findOrg, resolveOrg } from "./account-scope.js";
+import { out, principal, str, strs, readSecretValue, askSecretValue } from "./commands.js";
 import { detailLine, pickAnswers } from "./conversation-commands.js";
 import { NotFoundError, UsageError } from "./errors.js";
 import { time } from "./format.js";
@@ -36,8 +37,8 @@ export function taskLine(t) {
  * request your orchestrator made to your computer while it was offline reads "Waiting for your computer: list ~/code".
  */
 export function needsLine(n) {
-    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
-    return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
+    const detail = n.credential?.kind === 'environment' ? [n.credential.name, n.credential.suggested_scope].filter(Boolean).join(' · ') : n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.map(o => n.option_details?.[o] ? `${o}: ${n.option_details[o]}` : o).join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
+    return `${n.id}\t${oneLine(n.ask, n.kind === 'question' || n.credential?.kind === 'environment' ? Infinity : 100)}${detail ? `\t${detail}` : ''}`;
 }
 /** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
 export function reportLine(r) {
@@ -140,7 +141,7 @@ export function taskDetailText(d) {
             if (r.outcome.trim())
                 lines.push(`  ${whole(r.outcome)}`);
             if (r.options?.length)
-                lines.push(`  Options: ${r.options.join(' / ')}`);
+                lines.push(`  Options: ${r.options.map(o => r.option_details?.[o] ? `${o}: ${r.option_details[o]}` : o).join(' / ')}`);
             if (r.evidence.length)
                 lines.push(`  Evidence: ${r.evidence.map(evidenceText).join('; ')}`);
             if (r.media.length)
@@ -166,8 +167,8 @@ function orderOf(values) {
     return first ? null : after;
 }
 // ---- needs you -------------------------------------------------------------------------------
-const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
-/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', acred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, acred_, land_, prune_, dev_); undefined for another id. */
 export function itemKind(id) {
     return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
 }
@@ -364,6 +365,45 @@ export const BOARD_HANDLERS = {
         return 0;
     },
     async 'needs-you answer'(ctx, values, [id, word]) {
+        if (values.credential === true) {
+            if (!id?.startsWith('acred_') || word !== undefined || values.text !== undefined || values.pick !== undefined || values.keep !== undefined || values.everywhere === true) {
+                throw new UsageError('Use --credential for an environment request, without a decision or chat answer.');
+            }
+            const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+            const scope = str(values.scope);
+            if (scope !== undefined && !['agents', 'project', 'conversation'].includes(scope))
+                throw new UsageError('--scope must be agents, project or conversation');
+            const signed = scope === 'agents' || !hasKey;
+            let cloud = signed ? ctx.account() : ctx.cloud();
+            let organizationId = str(values.org);
+            if (signed) {
+                const org = organizationId ? await findOrg(ctx.account(), organizationId) : await resolveOrg(ctx, ctx.account(), {});
+                organizationId = org.id;
+            }
+            // Inspect the request before reading a file, stdin or opening the secure page.
+            const item = (await cloud.needsYou.list({ ...(organizationId ? { organizationId } : {}), signal: ctx.signal })).find(n => n.id === id);
+            if (!item || item.kind !== 'credential' || item.credential?.kind !== 'environment' || !item.credential.name)
+                throw new NotFoundError('Nothing waits for that environment credential.');
+            const target = scope ?? item.credential.suggested_scope ?? 'project';
+            if (target === 'agents' && !signed) {
+                organizationId ??= (await principal(ctx)).organization_id;
+                cloud = ctx.account();
+                await findOrg(ctx.account(), organizationId);
+            }
+            const save = (value) => {
+                ctx.addSecret(value);
+                return cloud.needsYou.answer(id, { credential: { value, scope: target } }, { ...(organizationId ? { organizationId } : {}), signal: ctx.signal });
+            };
+            const value = await readSecretValue(ctx, values, item.credential.name);
+            const r = value !== null ? await save(value) : await askSecretValue(ctx, values, {
+                title: `Provide ${item.credential.name}`, purpose: item.credential.purpose ?? item.ask, name: item.credential.name,
+            }, save);
+            out(ctx, `Credential ${item.credential.name} is available (${target}).\n`, r);
+            return 0;
+        }
+        if (values.scope !== undefined || values.ask === true || values['from-file'] !== undefined || values.org !== undefined || values.timeout !== undefined) {
+            throw new UsageError('Use --credential for a secure environment credential answer.');
+        }
         const input = { word, text: str(values.text), picks: strs(values.pick), keep: strs(values.keep), everywhere: values.everywhere === true };
         const cloud = boardClient(ctx);
         // Land merges here (shard task land) and records itself after; the board only takes keep and discard.

package/dist/cli-proxy.d.ts

@@ -16,8 +16,7 @@ export declare const cliProxyTools: {
     inVm: () => boolean;
     kill: (pid: number) => void;
 };
-/** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
-export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+export { FORWARD_LABEL, forwarderPlistPath, refreshForwarderAgent } from './forwarder-refresh.js';
 /** Where every VM finds the hub info (the machine template carries it). */
 export declare const VM_HUB_INFO_PATH = "/home/user/.config/shardflux-cli-proxy.json";
 export interface LocalLogin {
@@ -151,7 +150,6 @@ export interface PlistOptions {
 }
 /** The launchd agent: `shard cli-proxy forward` at login, started again whenever it exits. */
 export declare function forwarderPlist(o: PlistOptions): string;
-export declare function forwarderPlistPath(home: string): string;
 /** Whether Shardflux's forwarder answers on 127.0.0.1:port, and for which hub. */
 export interface ForwarderIdentity {
     hub: string | null; /** `mac`: shard cli-proxy forward; `vm`: sf-agent cli-proxy-forward. */
@@ -168,16 +166,6 @@ export interface LaunchdDeps {
     identity?: () => Promise<ForwarderIdentity | null>;
     sleep?: (ms: number) => Promise<void>;
 }
-/**
- * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
- * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
- * one. Returns whether it was.
- */
-export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
-    run?: ProgramRunner;
-    uid?: number;
-    platform?: NodeJS.Platform;
-}): Promise<boolean>;
 /** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
 export declare function installForwarderAgent(ctx: Ctx, apiUrl: string, deps?: LaunchdDeps): Promise<string>;
 /**

package/dist/cli-proxy.js

@@ -47,7 +47,8 @@ export const cliProxyTools = {
     kill: (pid) => { process.kill(pid, 'SIGTERM'); },
 };
 /** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
-export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+import { FORWARD_LABEL, forwarderPlistPath, recordForwarder } from "./forwarder-refresh.js";
+export { FORWARD_LABEL, forwarderPlistPath, refreshForwarderAgent } from "./forwarder-refresh.js";
 /** Where every VM finds the hub info (the machine template carries it). */
 // Outside ~/.config/shardflux, which machines and templates never capture (the platform's per-VM state).
 export const VM_HUB_INFO_PATH = '/home/user/.config/shardflux-cli-proxy.json';
@@ -470,9 +471,6 @@ ${Object.entries(env).map(([k, v]) => `    <key>${k}</key>\n    <string>${xml(v)
 </plist>
 `;
 }
-export function forwarderPlistPath(home) {
-    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
-}
 /** Whether Shardflux's forwarder (this computer's, or a VM's sf-agent) answers on 127.0.0.1:port, and for which hub. */
 export async function forwarderIdentity(port = CLI_PROXY_PORT) {
     try {
@@ -492,29 +490,6 @@ export function inShardfluxVm() {
 }
 /** The forwarder that answers is this shard's (an update replaces the program, not the running process). */
 const current = (id) => id !== null && id.kind === 'mac' && id.version === CLI_VERSION;
-/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
-function recordForwarder(dir) {
-    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
-}
-/**
- * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
- * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
- * one. Returns whether it was.
- */
-export async function refreshForwarderAgent(env, dir, deps = {}) {
-    if ((deps.platform ?? process.platform) !== 'darwin')
-        return false;
-    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
-        return false;
-    const store = new AgentStateStore(dir);
-    const record = store.read().cli_proxy_forwarder;
-    if (record?.version === CLI_VERSION)
-        return false;
-    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
-    recordForwarder(dir);
-    await (deps.run ?? cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
-    return true;
-}
 /** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
 export async function installForwarderAgent(ctx, apiUrl, deps = {}) {
     const runtime = ctx.runtime;

package/dist/codex-cloud.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
+import { CodexAdmissionStoppedError, ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -311,6 +311,8 @@ export async function openCodexConversation(ctx, c, history) {
         if (task.state !== 'canceled')
             task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
     }
+    if (task.state === 'attention' && task.next_attempt_at === null)
+        throw new CodexAdmissionStoppedError(task);
     if (task.state === 'canceled')
         throw new UsageError('This conversation’s Codex executor was removed. Start a new Cloud conversation; its saved branch and history remain available.');
     if (task.state !== 'active' || !task.thread_id)

package/dist/commands.d.ts

@@ -152,4 +152,16 @@ export declare function withConversations(rows: import('@shardflux/sdk').Agent[]
     question?: string | null;
 }[] | null): ThreadRow[];
 export declare const KEY_HANDLERS: Record<string, Handler>;
+/**
+ * The secret value (never from arguments): --from-file, piped standard input, or a no-echo prompt on a terminal. Null
+ * when the person types it on the page shard opens instead (0.20.1+): --ask, or a coding agent's shell with nothing
+ * piped (a terminal there is not the person's).
+ */
+export declare function readSecretValue(ctx: Ctx, values: Values, name: string): Promise<string | null>;
+/** The secret's value from the page shard opens, handed straight to `save` (create or rotate); the page shows its outcome. */
+export declare function askSecretValue<T>(ctx: Ctx, values: Values, page: {
+    title: string;
+    purpose: string;
+    name: string;
+}, save: (value: string) => Promise<T>): Promise<T>;
 export {};

package/dist/commands.js

@@ -2345,17 +2345,20 @@ export const KEY_HANDLERS = {
         if (keychain && from !== 'keychain')
             throw new UsageError('--keychain applies to the keychain vault');
         const targets = secretNames(names.map(n => alias ?? n), '--as');
-        const project = (await principal(ctx)).project_id;
+        const agent = values.scope !== undefined ? await agentSecretContext(ctx, values) : null;
+        const project = agent ? null : (await principal(ctx)).project_id;
         const imported = [];
         for (const [i, name] of names.entries()) {
             const value = await vaultValue(from, name, { signal: ctx.signal, ...(keychain ? { keychain } : {}) });
             ctx.addSecret(value);
-            imported.push(await ctx.cloud().secrets.create(project, { name: targets[i], value }));
+            imported.push(agent ? await agent.cloud.secrets.createAgent(agent.target, { name: targets[i], value }) : await ctx.cloud().secrets.create(project, { name: targets[i], value }));
         }
         out(ctx, `Imported ${imported.map(s => s.name).join(', ')}. ${SECRET_SECURITY_NOTE}\n`, { data: imported, security_note: SECRET_SECURITY_NOTE });
         return 0;
     },
     async 'secrets create'(ctx, values, [name]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'create', name);
         if (!SECRET_NAME.test(name))
             throw new UsageError(`<name> must be an environment variable name like OPENAI_API_KEY (^[A-Z_][A-Z0-9_]*$), got "${name}"`);
         const scope = scopeFlag(values);
@@ -2377,6 +2380,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets list'(ctx, values) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'list', undefined);
         const cloud = ctx.cloud();
         const org = scopeFlag(values);
         const project = org === null ? (await principal(ctx)).project_id : null;
@@ -2404,11 +2409,15 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets get'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'get', ref);
         const s = await resolveSecret(ctx, values, ref);
         out(ctx, secretDetail(s), s);
         return 0;
     },
     async 'secrets update'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'update', ref);
         const s = await resolveSecret(ctx, values, ref);
         const params = { ...permissionParams(values, s.scope, 'update') };
         const description = str(values.description);
@@ -2421,6 +2430,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets rotate'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'rotate', ref);
         const value = await readSecretValue(ctx, values, ref);
         const s = await resolveSecret(ctx, values, ref);
         const rotate = (secret) => ctx.cloud().secrets.rotate(s.id, secret);
@@ -2433,6 +2444,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets versions'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'versions', ref);
         const s = await resolveSecret(ctx, values, ref);
         const limitText = str(values.limit);
         const page = await ctx.cloud().secrets.versions(s.id, limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {});
@@ -2440,6 +2453,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets delete'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'delete', ref);
         if (values.yes !== true)
             throw new UsageError('refusing to delete without --yes (the values are erased and the name is removed from every workspace binding)');
         const s = await resolveSecret(ctx, values, ref);
@@ -2448,6 +2463,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets access-log'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'access-log', ref);
         const outcome = str(values.outcome);
         if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
             throw new UsageError('--outcome must be granted, denied or failed');
@@ -2549,6 +2566,106 @@ function updateLine(u, d) {
     }
 }
 /** `--org <id>`: organization scope; null: the API key's project. */
+async function agentSecretContext(ctx, values) {
+    const scope = str(values.scope);
+    if (!['agents', 'project', 'conversation'].includes(scope ?? ''))
+        throw new UsageError('--scope must be agents, project or conversation');
+    const restrictions = ['tool', 'allow-workspace', 'any-workspace', 'allow-project', 'all-projects', 'clear-projects'];
+    if (restrictions.some(k => Array.isArray(values[k]) ? values[k].length > 0 : values[k] !== undefined && values[k] !== false))
+        throw new UsageError('Workspace tool permissions apply to workspace-bound secrets. Agent credentials use their agents, project or conversation scope.');
+    if (scope === 'agents' && (values.project !== undefined || values.conversation !== undefined))
+        throw new UsageError('--scope agents takes --org; use a local scope for --project or --conversation.');
+    if (scope === 'project' && values.conversation !== undefined)
+        throw new UsageError('Use --scope conversation with --conversation.');
+    const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const cloud = scope === 'agents' || !hasKey ? ctx.account() : ctx.cloud();
+    if (scope === 'agents') {
+        const account = ctx.account(), org = str(values.org);
+        const organization = org ? await findOrg(account, org) : await resolveOrg(ctx, account, {});
+        return { cloud, target: { scope, organizationId: organization.id } };
+    }
+    const localOrg = str(values.org);
+    if (localOrg !== undefined && !UUID.test(localOrg))
+        throw new UsageError('--org must be an organization id for a local credential.');
+    const organization = localOrg ? { organizationId: localOrg } : {};
+    if (scope === 'conversation') {
+        const conversationId = str(values.conversation);
+        if (!conversationId)
+            throw new UsageError('--conversation is required with --scope conversation');
+        return { cloud, target: { scope, conversationId, ...organization, ...(str(values.project) ? { projectId: str(values.project) } : {}) } };
+    }
+    const projectId = str(values.project) ?? (hasKey ? (await principal(ctx)).project_id : undefined);
+    if (!projectId)
+        throw new UsageError('--project is required with a signed-in session and --scope project');
+    return { cloud, target: { scope: 'project', projectId, ...organization } };
+}
+async function agentSecretCommand(ctx, values, action, ref) {
+    const { cloud, target } = await agentSecretContext(ctx, values);
+    if (action === 'list' && (values.limit !== undefined || values.cursor !== undefined || values['include-deleted'] === true))
+        throw new UsageError('Agent credential lists return all active names. Pagination and deleted-history flags apply to workspace-bound secrets.');
+    const describe = (r) => `${r.name} (${r.id}) · ${r.scope} · version ${r.current_version}\n`;
+    if (action === 'list') {
+        const data = await cloud.secrets.listAgents(target);
+        out(ctx, data.map(describe).join('') || 'No credentials.\n', { data });
+        return 0;
+    }
+    if (action === 'create') {
+        if (!SECRET_NAME.test(ref ?? ''))
+            throw new UsageError('Use an environment variable name for the credential.');
+        const value = await readSecretValue(ctx, values, ref), save = (value) => { ctx.addSecret(value); return cloud.secrets.createAgent(target, { name: ref, value, ...(str(values.description) !== undefined ? { description: str(values.description) } : {}) }); };
+        const r = value !== null ? await save(value) : await askSecretValue(ctx, values, { title: `Add ${ref}`, purpose: `Saved encrypted for your agents as ${ref}.`, name: ref }, save);
+        out(ctx, describe(r), r);
+        return 0;
+    }
+    const r = UUID.test(ref ?? '') ? await cloud.secrets.getAgent(ref) : (await cloud.secrets.listAgents(target)).find(r => r.name === ref);
+    if (!r)
+        throw new NotFoundError(`No credential named ${ref} in this scope.`);
+    // An id is still checked against the explicitly named target rather than silently operating in another scope.
+    if (r.scope !== target.scope || target.organizationId && r.organization_id !== target.organizationId || target.projectId && r.project_id !== target.projectId || target.conversationId && r.conversation_id !== target.conversationId)
+        throw new NotFoundError('That credential belongs to another scope.');
+    if (action === 'get') {
+        out(ctx, describe(r), r);
+        return 0;
+    }
+    if (action === 'update') {
+        const description = str(values.description);
+        if (description === undefined)
+            throw new UsageError('Pass --description to update an agent credential.');
+        const changed = await cloud.secrets.updateAgent(r.id, description);
+        out(ctx, describe(changed), changed);
+        return 0;
+    }
+    if (action === 'rotate') {
+        const value = await readSecretValue(ctx, values, r.name), save = (value) => { ctx.addSecret(value); return cloud.secrets.rotateAgent(r.id, value); };
+        const changed = value !== null ? await save(value) : await askSecretValue(ctx, values, { title: `New value for ${r.name}`, purpose: `Replaces the encrypted credential ${r.name}.`, name: r.name }, save);
+        out(ctx, describe(changed), changed);
+        return 0;
+    }
+    if (action === 'delete') {
+        if (values.yes !== true)
+            throw new UsageError('Pass --yes to erase this credential.');
+        await cloud.secrets.deleteAgent(r.id);
+        out(ctx, `Deleted ${r.name}.\n`, { deleted: true, id: r.id, name: r.name, scope: r.scope });
+        return 0;
+    }
+    if (action === 'versions') {
+        const limit = str(values.limit);
+        const page = await cloud.secrets.versions(r.id, limit ? { limit: parsePositiveInt(limit, 'limit', 200) } : {});
+        out(ctx, secretVersionTable(page.data), { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    }
+    if (action === 'access-log') {
+        const outcome = str(values.outcome), workspace = str(values.workspace), limit = str(values.limit);
+        if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
+            throw new UsageError('--outcome must be granted, denied or failed');
+        if (workspace !== undefined && !UUID.test(workspace))
+            throw new UsageError('--workspace must be a workspace id');
+        const page = await cloud.secrets.accessEvents(r.id, { ...(outcome ? { outcome: outcome } : {}), ...(workspace ? { workspaceId: workspace } : {}), ...(limit ? { limit: parsePositiveInt(limit, 'limit', 200) } : {}) });
+        out(ctx, JSON.stringify(page.data) + '\n', { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    }
+    throw new UsageError('Unknown credential action.');
+}
 function scopeFlag(values) {
     const org = str(values.org);
     if (org === undefined)
@@ -2599,7 +2716,7 @@ function permissionParams(values, scope, mode) {
  * when the person types it on the page shard opens instead (0.20.1+): --ask, or a coding agent's shell with nothing
  * piped (a terminal there is not the person's).
  */
-async function readSecretValue(ctx, values, name) {
+export async function readSecretValue(ctx, values, name) {
     const file = str(values['from-file']);
     if (values.ask === true) {
         if (file !== undefined)
@@ -2643,7 +2760,7 @@ function secretText(value) {
     return text;
 }
 /** The secret's value from the page shard opens, handed straight to `save` (create or rotate); the page shows its outcome. */
-async function askSecretValue(ctx, values, page, save) {
+export async function askSecretValue(ctx, values, page, save) {
     const asked = await askInBrowser(ctx, {
         kind: 'secret',
         title: page.title,

package/dist/conversations.d.ts

@@ -59,6 +59,8 @@ export interface Conversation {
     started_by?: {
         user_id: string;
     } | null;
+    orchestrator_conversation_id?: string | null;
+    orchestrator_input_id?: string | null;
 }
 export interface LocalConversation {
     api_url: string;

package/dist/conversations.js

@@ -250,7 +250,7 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     capture.catch(() => undefined);
     // The title marker this computer chose (`shard settings --title-prefix`, 0.20.1+); none sent means the platform's.
     const titlePrefix = storedTitlePrefix(ctx.store.dir);
-    const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
+    const response = await conversationClient(ctx).conversations.create({ fromConversationId: ctx.io.env.SF_CONVERSATION_ID, repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
         base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id,
         ...(titlePrefix !== undefined ? { titlePrefix } : {}),
         ...(movedIn ? { harnessSessionId: movedIn.session_id, ...(movedIn.title ? { title: movedIn.title.slice(0, 200) } : {}) } : {}) }, { idempotencyKey, signal: ctx.signal });

package/dist/device-bridge.d.ts

@@ -2,6 +2,7 @@ import type { CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { Conversation } from './conversations.js';
 import type { DirListing, LinkedProject } from './device-folders.js';
+import type { HubSeed } from './project-hub-seed.js';
 export type DeviceChoice = 'once' | 'always' | 'deny';
 export interface DeviceRequest {
     id: string;
@@ -121,7 +122,9 @@ export declare function deviceExec(argv: string[], cwd: string, timeoutSeconds?:
 export type DeviceAsk = (approval: DeviceApproval, signal?: AbortSignal) => Promise<DeviceChoice>;
 export declare class DeviceExecutor {
     #private;
-    constructor(ctx: Ctx, ask: DeviceAsk, deviceId: string);
+    constructor(ctx: Ctx, ask: DeviceAsk, deviceId: string, options?: {
+        seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>;
+    });
     /** A new device id for a new sign-in (device-helper.ts): requests for the old one are no longer this device's. */
     set deviceId(id: string);
     get deviceId(): string;

package/dist/device-bridge.js

@@ -229,7 +229,14 @@ export class DeviceExecutor {
     /** Requests that run without asking (device-mode.ts), until their outcome is recorded. */
     #auto = new Map();
     #identity = { at: 0 };
-    constructor(ctx, ask, deviceId) { this.#ctx = ctx; this.#ask = ask; this.#deviceId = deviceId; }
+    /** How an agent's folder link reaches the project hub (project-hub-seed.ts unless a test gives its own hub). */
+    #seedHub;
+    constructor(ctx, ask, deviceId, options = {}) {
+        this.#ctx = ctx;
+        this.#ask = ask;
+        this.#deviceId = deviceId;
+        this.#seedHub = options.seedHub;
+    }
     /** A new device id for a new sign-in (device-helper.ts): requests for the old one are no longer this device's. */
     set deviceId(id) { this.#deviceId = id; this.#identity = { at: 0 }; }
     get deviceId() { return this.#deviceId; }
@@ -578,7 +585,7 @@ export class DeviceExecutor {
             if (r.kind === 'dir_list')
                 result = { state: 'done', dir: await listDeviceDir(target, r.dir ?? {}, ctx.signal) };
             else if (r.kind === 'project_link')
-                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true }) };
+                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true, fromConversationId: r.conversation_id }, undefined, this.#seedHub) };
             else {
                 const f = r.files;
                 if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))

package/dist/device-folders.d.ts

@@ -36,7 +36,7 @@ export interface LinkedProject {
     commit?: string;
     branch?: string;
 }
-type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string) => Promise<{
+type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string, fromConversationId?: string) => Promise<{
     id: string;
     project_id: string;
 }>;
@@ -65,6 +65,7 @@ export declare function linkLocalProject(ctx: Ctx, path: string, options?: {
     harness?: 'claude' | 'codex';
     projectId?: string;
     seed?: boolean;
+    fromConversationId?: string;
 }, start?: Starter, seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>): Promise<LinkedProject>;
 /** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
 export declare const PROJECT_LINK_HANDLERS: Record<string, Handler>;

package/dist/device-folders.js

@@ -139,14 +139,14 @@ export async function listDeviceDir(root, options = {}, signal) {
  * working tree (uncommitted files too, .gitignore respected) seeds it while its VM boots, and the brief is its first
  * prompt. The brief goes in on standard input, never in a command line another user can read.
  */
-export const startFromFolder = (ctx, folder, harness, brief) => {
+export const startFromFolder = (ctx, folder, harness, brief, fromConversationId) => {
     const node = ctx.runtime?.node ?? process.execPath, script = ctx.runtime?.script ?? process.argv[1];
     if (!script)
         return Promise.reject(new Error('The Shardflux CLI could not find itself to start the conversation.'));
     return new Promise((resolveStart, reject) => {
         const child = spawn(node, [script, 'agents', 'new', '--app', harness, '--path', folder, '--prompt-file', '-', '--json'], {
             cwd: folder, stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1' },
+            env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1', ...(fromConversationId ? { SF_CONVERSATION_ID: fromConversationId } : {}) },
         });
         const out = [], err = [];
         let outBytes = 0;
@@ -209,7 +209,7 @@ export async function linkLocalProject(ctx, path, options = {}, start = startFro
     const profile = ctx.store.profile(ctx.apiUrl);
     let projectId = profile.project_id ?? profile.api_key?.project_id ?? options.projectId, conversationId;
     if (options.brief) {
-        const started = await start(ctx, folder, options.harness ?? 'claude', options.brief);
+        const started = await start(ctx, folder, options.harness ?? 'claude', options.brief, options.fromConversationId);
         conversationId = started.id;
         projectId = started.project_id || projectId;
     }

package/dist/format.js

@@ -83,6 +83,8 @@ export function workspaceState(w) {
         tags.push('session');
     if (w.deleted_at)
         tags.push(w.ended_reason ? `ended: ${w.ended_reason}` : 'deleted');
+    if (w.storage_recovery)
+        tags.push('files stored');
     return tags.length ? `${w.observed_state} (${tags.join(', ')})` : w.observed_state;
 }
 export function workspaceRow(w) {
@@ -230,6 +232,7 @@ export function workspaceDetail(w) {
         ['id', w.id],
         ['key', w.workspace_key],
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
+        ...(w.storage_recovery ? [['storage', w.storage_recovery.message]] : []),
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
         // Immutable paths (0.8.0): the template version whose immutable paths the workspace has mounted, when it has one.

package/dist/forwarder-refresh.d.ts

@@ -0,0 +1,15 @@
+import type { ProgramRunner } from './cli-proxy.js';
+export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+export declare function forwarderPlistPath(home: string): string;
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+export declare function recordForwarder(dir: string): void;
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
+    run?: ProgramRunner;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;

package/dist/forwarder-refresh.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+import { CLI_VERSION } from "./args.js";
+export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+export function forwarderPlistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
+}
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+export function recordForwarder(dir) {
+    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
+}
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export async function refreshForwarderAgent(env, dir, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'darwin')
+        return false;
+    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
+        return false;
+    const store = new AgentStateStore(dir);
+    const record = store.read().cli_proxy_forwarder;
+    if (record?.version === CLI_VERSION)
+        return false;
+    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
+    recordForwarder(dir);
+    await (deps.run ?? (await import("./cli-proxy.js")).cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
+    return true;
+}

package/dist/handler-loader.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from './commands.js';
+export declare const HANDLER_PATHS: string[];
+export declare function handlerFor(path: string): Promise<Handler | undefined>;