@shardflux/cli 0.20.0 → 0.23.0

package/dist/commands.js

@@ -1,4 +1,5 @@
 import { agentReachability } from "./agent-reachability.js";
+import { findOrg, resolveOrg, sessionScopeWarnings, writeWarnings } from "./account-scope.js";
 import { vaultType, vaultValue, SECRET_SECURITY_NOTE } from "./vault.js";
 /**
  * Command implementations of the project-key commands (workspaces, files, operations, secrets, templates, usage).
@@ -18,10 +19,12 @@ import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePosi
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
 import { updateCheckDisabled } from "./update-check.js";
 import { withLiveAgents } from "./agent-live.js";
+import { codingAgentShell } from "./agent-setup.js";
+import { askInBrowser, askTimeout } from "./secret-ask.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { table, bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { table, bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, suspendProgressText, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -43,6 +46,8 @@ const cellOf = (ctx, ws) => ws.cell({
 });
 export const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
 const MAX_SECRET_VALUE_BYTES = 65_536;
+/** `files write --ask`: a secret file typed or pasted into the page (~/.npmrc, a key, a service-account JSON). */
+const MAX_ASKED_FILE_BYTES = 1024 * 1024;
 /** `files patch --content-file`: a patch request is at most 7 MiB; larger files go through `files write`. */
 const MAX_PATCH_CONTENT = 7 * 1024 * 1024;
 const STOPPED_AT = { max_matches: '--max matches', budget: 'its 10 s budget', max_bytes: '4 MiB of results' };
@@ -476,6 +481,45 @@ function feedbackSender(ctx) {
     const sessionConfigured = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
     return keyConfigured || !sessionConfigured ? ctx.cloud() : ctx.account();
 }
+/**
+ * An organization-level read (`shard usage`; 0.20.2+). The API key reads its own organization. Another organization
+ * (--org) answers 404 to a project key, so that read is made with the signed-in session, which sees every organization
+ * the person is in; without a session the error says which organization the key belongs to and how to switch. No key
+ * but a session: the session, for --org or the default organization.
+ */
+async function readOrg(ctx, orgFlag, read) {
+    const signedIn = ctx.sessionSource() !== null;
+    const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const bySession = async () => {
+        const account = ctx.account();
+        return read(account, (orgFlag !== undefined ? await findOrg(account, orgFlag) : await resolveOrg(ctx, account, {})).id);
+    };
+    if (!hasKey && signedIn)
+        return bySession();
+    if (orgFlag === undefined)
+        return read(ctx.cloud(), (await principal(ctx)).organization_id);
+    if (!UUID.test(orgFlag)) {
+        if (signedIn)
+            return bySession();
+        throw new UsageError('--org must be an organization id (UUID)', 'or sign in (shard auth login) to name it by slug');
+    }
+    try {
+        return await read(ctx.cloud(), orgFlag);
+    }
+    catch (err) {
+        if (!(err instanceof ShardfluxApiError && err.status === 404))
+            throw err;
+        const p = await principal(ctx);
+        // Retry only a cross-org read. A real 404 in the key's own org must keep its error and credential boundary.
+        if (p.organization_id === orgFlag)
+            throw err;
+        if (signedIn)
+            return bySession();
+        const envKey = ctx.apiKey().source === 'env';
+        const key = envKey ? `The API key in SHARDFLUX_API_KEY (${p.api_key.key_id})` : `The saved API key ${p.api_key.key_id}`;
+        throw new UsageError(`${key} belongs to organization ${p.organization_id}, so it cannot read organization ${orgFlag}.`, `sign in to read any of your organizations: shard auth login   (or switch the key: shard setup --org ${orgFlag} --new-key)${envKey ? '; after saving the new key, unset SHARDFLUX_API_KEY so shard uses it' : ''}`);
+    }
+}
 /** Contract bounds of the feedback context fields shard sends (characters). */
 const FEEDBACK_CONTEXT_MAX = { workspace: 200, 'request-id': 200, 'error-code': 100, command: 2000 };
 /**
@@ -879,7 +923,10 @@ export const KEY_HANDLERS = {
     },
     async whoami(ctx) {
         const p = await principal(ctx);
-        out(ctx, principalText(p), p);
+        // Signed in too (0.20.2+): distinguish departed defaults/keys from an accessible key in another default org.
+        const warnings = await sessionScopeWarnings(ctx, { keyId: p.api_key.key_id, source: ctx.apiKey().source, organizationId: p.organization_id, projectId: p.project_id });
+        writeWarnings(ctx, warnings);
+        out(ctx, principalText(p), warnings.length ? { ...p, warnings } : p);
         return 0;
     },
     async version(ctx, values) {
@@ -893,7 +940,16 @@ export const KEY_HANDLERS = {
         const category = oneOf(values, 'category', FEEDBACK_CATEGORIES);
         const context = feedbackContext(ctx, values);
         const message = await feedbackMessage(ctx, values, words);
-        const r = await feedbackSender(ctx).sendFeedback({ message, ...(category ? { category } : {}), context });
+        if (values.yes !== true) {
+            const { requestId, errorCode, ...fields } = context;
+            const preview = { message, category: category ?? 'other', context: { ...fields, ...(requestId ? { request_id: requestId } : {}), ...(errorCode ? { error_code: errorCode } : {}) } };
+            out(ctx, `Feedback preview for the Shardflux team (not sent):\n${json(preview)}Show the exact message and context to the user. Send the same content with --yes only after explicit authorization.\n`, {
+                sent: false, authorization_required: true, preview,
+                note: 'Not sent. Show the exact message and context to the user; use --yes only after explicit authorization.',
+            });
+            return 0;
+        }
+        const r = await feedbackSender(ctx).sendFeedback({ message, category: category ?? 'other', context });
         const human = r.duplicate
             ? `Already received: the same message was sent in the last 24 hours (feedback ${r.id}); not emailed again.\n`
             : `Sent to the Shardflux team (feedback ${r.id}). Thank you.\n`;
@@ -917,20 +973,18 @@ export const KEY_HANDLERS = {
             out(ctx, usageSeriesText(series), series);
             return 0;
         }
-        const org = str(values.org) ?? (await principal(ctx)).organization_id;
-        if (!UUID.test(org))
-            throw new UsageError(`--org must be an organization id (UUID)`);
+        const org = str(values.org);
         if (values.estimate === true) {
-            const estimate = await ctx.cloud().usage.estimate(org);
+            const estimate = await readOrg(ctx, org, (client, id) => client.usage.estimate(id));
             out(ctx, usageEstimateText(estimate), estimate);
             return 0;
         }
         if (values.series === true) {
-            const series = await ctx.cloud().usage.series(org, range);
+            const series = await readOrg(ctx, org, (client, id) => client.usage.series(id, range));
             out(ctx, usageSeriesText(series), series);
             return 0;
         }
-        const summary = await ctx.cloud().request('GET', `/v1/organizations/${encodeURIComponent(org)}/usage/summary`);
+        const summary = await readOrg(ctx, org, (client, id) => client.request('GET', `/v1/organizations/${encodeURIComponent(id)}/usage/summary`));
         out(ctx, usageText(summary), summary);
         return 0;
     },
@@ -1050,7 +1104,7 @@ export const KEY_HANDLERS = {
             })));
         }
         if (s.state === 'starting' || s.state === 'running') {
-            throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
+            throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}${s.error ? `: ${s.error}` : ''}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
         }
         const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false, canceled: s.canceled ?? false };
         if (!ctx.json && result.exitCode === null && !result.timedOut && !(result.termSignal !== null && result.termSignal > 0)) {
@@ -1067,7 +1121,7 @@ export const KEY_HANDLERS = {
         const s = await cellOf(ctx, ws).exec.cancel(sessionId, graceMs);
         const ended = s.state !== 'starting' && s.state !== 'running';
         const status = !ended ? `${s.state} (cancel sent)` : s.canceled ? `canceled${s.term_signal ? ` (signal ${s.term_signal})` : ''}` : `already ${s.state}${typeof s.exit_code === 'number' ? ` (exit code ${s.exit_code})` : ''}`;
-        out(ctx, `exec session ${s.session_id}: ${status}\n`, s);
+        out(ctx, `exec session ${s.session_id}: ${status}${s.error ? `: ${s.error}` : ''}${!ended || s.error?.startsWith('cancel accepted; execution drain') ? `; follow with: shard ws exec-read ${ref} ${s.session_id} --follow` : ''}\n`, s);
         return 0;
     },
     async 'workspaces exec-input'(ctx, values, [ref, sessionId, data]) {
@@ -1334,11 +1388,38 @@ export const KEY_HANDLERS = {
     },
     async 'files write'(ctx, values, [ref, path]) {
         const ifRev = ifRevision(values);
-        const data = await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
+        // --ask (0.20.1+): a secret file's contents come from the person, on a page shard opens; the agent never sees them.
+        const ask = values.ask === true;
+        if (ask && str(values.from) !== undefined)
+            throw new UsageError('use --ask or --from, not both');
+        const data = ask ? null : await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
         const ws = await resolveWorkspace(ctx, ref);
         fileFirstOnly(ws, ifRev !== undefined ? ['--if-revision'] : []);
         const cell = cellOf(ctx, ws);
-        const r = await cell.files.write(path, data, { append: values.append === true, createParents: values.parents !== false, ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) });
+        // A new file written from the page is the owner's only (0600); an existing file keeps its mode.
+        const write = (bytes) => cell.files.write(path, bytes, { append: values.append === true, createParents: values.parents !== false, ...(ask ? { mode: '0600' } : {}), ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) });
+        const r = data !== null ? await write(data) : (await askInBrowser(ctx, {
+            kind: 'file',
+            title: `Write ${path}`,
+            purpose: `Saved to ${path} in ${ws.key}. Your coding agent never sees it.`,
+            label: 'File contents',
+            submit: 'Save',
+            done: 'Saved',
+            failed: 'Not saved',
+            doing: `to type the contents of ${path}`,
+            maxBytes: MAX_ASKED_FILE_BYTES,
+            timeoutMs: askTimeout(values),
+            use: async (text) => {
+                // Text files end with a newline; the browser's text area drops a pasted one.
+                const bytes = Buffer.from(text.endsWith('\n') ? text : `${text}\n`, 'utf8');
+                try {
+                    return await write(bytes);
+                }
+                finally {
+                    bytes.fill(0);
+                }
+            },
+        })).result;
         // File-first: the tree revision the write published (or the current one when nothing changed), to chain --if-revision.
         const tree = treeRevisionAfter(ws, cell);
         out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}${tree !== null ? `, tree revision ${tree}` : ''}\n`, tree !== null ? { ...r, tree_revision: tree } : r);
@@ -2272,12 +2353,18 @@ export const KEY_HANDLERS = {
         const scope = scopeFlag(values);
         const perms = permissionParams(values, scope === null ? 'project' : 'organization', 'create');
         const description = str(values.description);
-        const value = await readSecretValue(ctx, values);
+        const value = await readSecretValue(ctx, values, name);
         const cloud = ctx.cloud();
-        const base = { name: name, value, ...(description !== undefined ? { description } : {}) };
-        const s = scope === null
-            ? await cloud.secrets.create((await principal(ctx)).project_id, { ...base, ...perms })
-            : await cloud.secrets.createOrganization(scope, { ...base, ...perms });
+        const project = scope === null ? (await principal(ctx)).project_id : null;
+        const create = (secret) => {
+            const base = { name: name, value: secret, ...(description !== undefined ? { description } : {}) };
+            return project !== null ? cloud.secrets.create(project, { ...base, ...perms }) : cloud.secrets.createOrganization(scope, { ...base, ...perms });
+        };
+        const s = value !== null ? await create(value) : await askSecretValue(ctx, values, {
+            title: `Add ${name}`,
+            purpose: `Saved to your ${project !== null ? 'project' : 'organization'}’s secrets as ${name}. Your coding agent never sees it.`,
+            name: name,
+        }, create);
         out(ctx, `Created ${s.scope} secret ${s.name} (${s.id}), version ${s.current_version}. The value is stored encrypted and is never shown.\n${secretDetail(s)}`, s);
         return 0;
     },
@@ -2326,9 +2413,14 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets rotate'(ctx, values, [ref]) {
-        const value = await readSecretValue(ctx, values);
+        const value = await readSecretValue(ctx, values, ref);
         const s = await resolveSecret(ctx, values, ref);
-        const r = await ctx.cloud().secrets.rotate(s.id, value);
+        const rotate = (secret) => ctx.cloud().secrets.rotate(s.id, secret);
+        const r = value !== null ? await rotate(value) : await askSecretValue(ctx, values, {
+            title: `New value for ${s.name}`,
+            purpose: `Replaces ${s.name} in your ${s.scope === 'project' ? 'project' : 'organization'}’s secrets; older values are erased. Your coding agent never sees it.`,
+            name: s.name,
+        }, rotate);
         out(ctx, `Rotated ${r.secret.name} to version ${r.version.version}; older values were erased. Processes that already read the old value keep it.\n`, r);
         return 0;
     },
@@ -2382,6 +2474,27 @@ export const KEY_HANDLERS = {
         out(ctx, operationDetail(op), op);
         return 0;
     },
+    async 'operations progress'(ctx, _values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError('<operation-id> must be a UUID');
+        const progress = await ctx.cloud().workspaces.suspendProgress(id, { signal: ctx.signal });
+        out(ctx, suspendProgressText(progress), { progress });
+        return 0;
+    },
+    async 'operations cancel'(ctx, values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError('<operation-id> must be a UUID');
+        if (values.wait === true) {
+            const operation = await waited(ctx, `Suspension cancellation for ${id} continues server side.`, () => ctx.cloud().workspaces.cancelSuspend(id, { signal: ctx.signal, timeoutMs: waitTimeout(values) }));
+            const progress = await ctx.cloud().workspaces.suspendProgress(id, { signal: ctx.signal });
+            out(ctx, suspendProgressText(progress), { operation, progress });
+        }
+        else {
+            const result = await ctx.cloud().workspaces.requestCancelSuspend(id, { signal: ctx.signal });
+            out(ctx, suspendProgressText(result.progress), result);
+        }
+        return 0;
+    },
     async 'operations wait'(ctx, values, [id]) {
         if (!UUID.test(id))
             throw new UsageError(`<operation-id> must be a UUID (got "${id}")`);
@@ -2474,12 +2587,26 @@ function permissionParams(values, scope, mode) {
     return out;
 }
 /**
- * The secret value from --from-file or standard input (never from arguments): UTF-8 text, one trailing
- * newline removed, 1..65536 bytes. Never echoed.
+ * 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).
  */
-async function readSecretValue(ctx, values) {
+async function readSecretValue(ctx, values, name) {
     const file = str(values['from-file']);
+    if (values.ask === true) {
+        if (file !== undefined)
+            throw new UsageError('use --ask or --from-file, not both');
+        return null;
+    }
+    const agentShell = codingAgentShell(ctx.io.env);
+    if (file === undefined && ctx.io.stdin.isTTY) {
+        if (agentShell)
+            return null;
+        return secretText(await ctx.input.secret(`${name} (typing is hidden): `, 'the secret value', 'pipe the value in, or use --ask'));
+    }
     const bytes = await readInput(ctx, file ?? '-', MAX_SECRET_VALUE_BYTES + 2, file === undefined ? 'secret value (standard input)' : '--from-file');
+    if (file === undefined && bytes.length === 0 && agentShell)
+        return null;
     let text;
     try {
         text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
@@ -2490,18 +2617,40 @@ async function readSecretValue(ctx, values) {
     finally {
         bytes.fill(0);
     }
+    return secretText(text);
+}
+/** A secret value as stored: one trailing newline removed, 1..65536 UTF-8 bytes, no NUL. */
+function secretText(value) {
+    let text = value;
     if (text.endsWith('\r\n'))
         text = text.slice(0, -2);
     else if (text.endsWith('\n'))
         text = text.slice(0, -1);
     if (text.length === 0)
-        throw new UsageError('the secret value is empty: pipe it on standard input or pass --from-file <file>');
+        throw new UsageError('the secret value is empty: pipe it on standard input, pass --from-file <file> or use --ask');
     if (Buffer.byteLength(text, 'utf8') > MAX_SECRET_VALUE_BYTES)
         throw new UsageError(`the secret value exceeds ${MAX_SECRET_VALUE_BYTES} bytes`);
     if (text.includes('\u0000'))
         throw new UsageError('the secret value must not contain NUL characters');
     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) {
+    const asked = await askInBrowser(ctx, {
+        kind: 'secret',
+        title: page.title,
+        purpose: page.purpose,
+        label: 'Value',
+        submit: 'Save',
+        done: 'Saved',
+        failed: 'Not saved',
+        doing: `to type ${page.name}`,
+        maxBytes: MAX_SECRET_VALUE_BYTES + 2,
+        timeoutMs: askTimeout(values),
+        use: (value) => save(secretText(value)),
+    });
+    return asked.result;
+}
 /** `<id|name>`: a UUID is tried as an id first; otherwise the live secret of that name in the scope (project, or --org). */
 async function resolveSecret(ctx, values, ref) {
     const cloud = ctx.cloud();

package/dist/conversation-commands.d.ts

@@ -5,4 +5,9 @@ export declare function questionLine(c: {
     state: string;
     question?: string | null;
 }, max?: number): string | undefined;
+/** A conversation's title as people read it: "New conversation" while it is still named by its generated id, before a
+ * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
+export declare function displayTitle(c: {
+    title: string;
+}): string;
 export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -11,17 +11,20 @@ export function questionLine(c, max = 100) {
     const text = c.state === 'needs_you' ? c.question?.replace(/\s+/g, ' ').trim() : undefined;
     return !text ? undefined : text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
 }
+/** A conversation's title as people read it: "New conversation" while it is still named by its generated id, before a
+ * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
+export function displayTitle(c) { return !c.title || /^(conv[-_])?[a-z0-9]{26}$/.test(c.title) ? 'New conversation' : c.title; }
 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 resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${displayTitle(r.conversation)}: 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 });
         // A conversation that needs you adds a fifth column: why (0.18.0+).
-        out(ctx, page.data.map(c => { const q = questionLine(c); return `${c.id}\t${c.title}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', page);
+        out(ctx, page.data.map(c => { const q = questionLine(c); return `${c.id}\t${displayTitle(c)}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', page);
         return 0;
     },
-    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
+    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${displayTitle(c)}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
     // A finished conversation whose VM was removed restores into a fresh one, then takes the message (APIs that do; 0.18.1+).
     async 'conversations send'(ctx, _values, [id, text]) {
         const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal });
@@ -34,14 +37,14 @@ export const CONVERSATION_HANDLERS = {
             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);
+        out(ctx, 'timeout' in r ? 'Still working.\n' : `${displayTitle(r.conversation)}: ${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);
+        out(ctx, `${displayTitle(r)}: ${r.landed.how}\n`, r);
         return 0;
     },
     async 'files pull'(ctx, _values, [conversation, path]) {

package/dist/conversation-terminal.d.ts

@@ -2,8 +2,13 @@ import type { Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
-/** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
-export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values, afterStart?: () => Promise<void> | undefined): Promise<number>;
+import type { ConversationSetup } from './project-template-setup.js';
+/**
+ * Every terminal entry point uses the durable conversation's native harness, worktree and session. A new conversation
+ * in a repository without a project template for its dependencies sets its worktree up once its agent has started
+ * (`setup`, 0.21.1+).
+ */
+export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values, afterStart?: () => Promise<void> | undefined, setup?: ConversationSetup): Promise<number>;
 /**
  * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
  * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the
@@ -17,7 +22,10 @@ export declare function reopenConversation(ctx: Ctx, c: Conversation, values: Va
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ * From a shell nobody types into (a coding agent's, or none) a terminal conversation opens in a new tab of the
+ * person's terminal app (0.20.1+, agents targets --terminal).
  */
 export declare const launchProjectCommand: Handler;
+export declare function forwardedFlags(values: Values): string[];
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export declare const launchConversationProject: Handler;

package/dist/conversation-terminal.js

@@ -1,4 +1,6 @@
 import { linuxTerminalSession } from "./linux-terminal.js";
+import { resolve } from 'node:path';
+import { attachable, handedToTerminal, openShardInTerminal, reportTerminalOpen } from "./terminal-apps.js";
 import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
@@ -7,11 +9,12 @@ import { modelChoice } from "./agent-models.js";
 import { terminal } from "./agent-commands.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
-import { prepareProjectTemplate } from "./project-template-setup.js";
+import { labelConversationSetup, prepareProjectTemplate, readConversationSetup } from "./project-template-setup.js";
 import { projectWorkspacePath, seedAgentRepository } from "./agent-repository.js";
 import { syncAgentConfig, syncAgentConfigAfterStart } from "./agent-config-sync.js";
 import { savedMachine } from "./filesystem-state.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
+import { ensureProjectGit } from "./project-git.js";
 import { UsageError } from "./errors.js";
 import { localResumeTerminal } from "./conversation-local-resume.js";
 import { agentReachability } from "./agent-reachability.js";
@@ -24,16 +27,21 @@ import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-comma
 import { openUrl } from "./browser.js";
 import { out } from "./commands.js";
 import { progress } from "./progress.js";
+import { seedPhase } from "./seed-phases.js";
 /** This computer's agent config, copied after the start; with a saved machine (which carries it) just the project memory. */
 const afterStartConfig = (ctx, ws, machine) => () => syncAgentConfigAfterStart(ctx, ws, machine ? { memoryOnly: true } : {});
-/** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
-export async function conversationTerminal(ctx, ws, c, project, values, afterStart) {
+/**
+ * Every terminal entry point uses the durable conversation's native harness, worktree and session. A new conversation
+ * in a repository without a project template for its dependencies sets its worktree up once its agent has started
+ * (`setup`, 0.21.1+).
+ */
+export async function conversationTerminal(ctx, ws, c, project, values, afterStart, setup) {
     if (c.route === 'codex-cloud')
         return openCodexConversation(ctx, c);
     await restoreConversationBinding(ctx, c, ws);
     // A thread on another conversation's computer has its own PTY there, never the VM's own (0.16.0+).
     const pty = ws.labels.shard_conversation && ws.labels.shard_conversation !== c.id ? conversationName(c) : undefined;
-    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c), ...(afterStart ? { afterStart } : {}) });
+    return terminal(ctx, ws, c.harness, conversationName(c), project, values, setup?.hash, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c), ...(afterStart ? { afterStart } : {}), ...(setup ? { setupLabelled: setup.labelled } : {}) });
 }
 /**
  * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
@@ -58,20 +66,59 @@ export async function reopenConversation(ctx, c, values) {
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ * From a shell nobody types into (a coding agent's, or none) a terminal conversation opens in a new tab of the
+ * person's terminal app (0.20.1+, agents targets --terminal).
  */
 export const launchProjectCommand = async (ctx, values, [path = './', explicit]) => {
     const named = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
+    // A terminal this CLI opened for it runs it there, never in yet another one (0.23.0+).
+    const typing = attachable(ctx.io), here = typing || ctx.json || handedToTerminal(ctx.io.env);
     if (values.resume !== true && values.review !== true) {
         const project = projectIdentity(path);
         const app = named === 'claude' || named === 'codex' ? named : new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);
-        const where = process.platform === 'linux' && ctx.io.stdin.isTTY ? 'terminal' : openInChoices(ctx, project.slug)[app];
+        const where = process.platform === 'linux' && typing ? 'terminal' : openInChoices(ctx, project.slug)[app];
         if (where === 't3')
             return launchT3(ctx, values, path, app);
         if (values.on === undefined && app === 'claude' && (where === 'claude-desktop' || where === 'web'))
             return startConversation(ctx, values, [path, ...(explicit ? [explicit] : [])], where);
+        if (!here && where === 'terminal')
+            return projectInTerminalApp(ctx, values, path, named);
     }
+    else if (!here)
+        return projectInTerminalApp(ctx, values, path, named);
     return launchConversationProject(ctx, values, [path, ...(explicit ? [explicit] : [])]);
 };
+/** Flags `shard ./` hands to the terminal tab that runs it; files become absolute paths (the tab starts in the project). */
+const NOT_FORWARDED = new Set(['json', 'api-url', 'agent-label', 'wake', 'wake-timeout', 'help', 'version', 'timing', 'reachable', 'claude', 'codex']);
+export function forwardedFlags(values) {
+    const flags = [];
+    for (const [key, value] of Object.entries(values)) {
+        if (NOT_FORWARDED.has(key) || value === undefined)
+            continue;
+        for (const v of Array.isArray(value) ? value : [value]) {
+            if (v === true)
+                flags.push(`--${key}`);
+            else if (v === false)
+                flags.push(`--no-${key}`);
+            else if (typeof v === 'string') {
+                if ((key === 'prompt-file' || key === 'image') && v === '-')
+                    throw new UsageError(`--${key} - reads standard input, which a new terminal tab cannot: pass a file, or start it detached with --json.`);
+                flags.push(`--${key}`, key === 'prompt-file' || key === 'image' ? resolve(v) : v);
+            }
+        }
+    }
+    return flags;
+}
+/** `shard ./` with its flags in a new tab of the person's terminal app, in the project folder: the tab owns the start,
+ * any sign-in and the attach, as if the person typed it there. */
+async function projectInTerminalApp(ctx, values, path, app) {
+    const result = await openShardInTerminal(ctx, ['./', ...(app ? [app] : []), ...forwardedFlags(values)], { cwd: resolve(path) });
+    if (!result.opened) {
+        throw new UsageError(`shard ./ opens Claude Code or Codex in a terminal, and none opened here${result.reason ? `: ${result.reason.replace(/\.$/, '')}` : ''}.`, 'ask your user to run shard ./ in their own terminal, or start the conversation detached: shard ./ --json --prompt "<task>" (shard ./ codex --json ... for Codex)');
+    }
+    reportTerminalOpen(ctx, result);
+    return 0;
+}
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export const launchConversationProject = (ctx, values, args) => startConversation(ctx, values, args);
 async function startConversation(ctx, values, [path = './', explicit], openIn) {
@@ -114,17 +161,31 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
     }
     if (app === 'codex' && !linuxTerminalSession(ctx, values))
         return launchCodexCloud(ctx, values, path, images);
-    await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
-    const signedIn = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
-    if (!signedIn)
-        requireClaudeTerminal(ctx);
+    seedPhase('cli_start');
+    // Agent credentials and the Claude sign-in are checked beside the project's local work (its Git state and snapshot),
+    // and both pass before a VM is requested (0.21.1+).
+    const signIn = (async () => {
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+        const signed = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
+        if (!signed)
+            requireClaudeTerminal(ctx);
+        seedPhase('claude_login');
+        return signed;
+    })();
+    signIn.catch(() => undefined);
+    // Whether this conversation sets the project up: hashed from the files it starts from (in a Git repository, as its VM
+    // reads them), and asked while its VM starts.
+    await ensureProjectGit(ctx, project.folder);
+    const setup = readConversationSetup(ctx, project);
+    seedPhase('project_git');
     let created;
     try {
-        created = await createConversation(ctx, project.folder, app, 'terminal', undefined, choice);
+        created = await createConversation(ctx, project.folder, app, 'terminal', undefined, choice, undefined, setup, signIn);
     }
     catch (e) {
         if (!conversationsUnavailable(e))
             throw e;
+        const signedIn = await signIn;
         // Optional migration: preserve the native terminal on the old control plane, without reviving main sync.
         const name = `c-${randomUUID().slice(0, 12)}`;
         const prepared = await prepareProjectTemplate(ctx, project, undefined);
@@ -142,6 +203,9 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
         return terminal(ctx, ws, app, name, project.remote ?? project.folder, values, prepared.setupHash);
     }
     const { conversation: c, workspace: ws } = created;
+    const signedIn = await signIn;
+    const setupStart = labelConversationSetup(ctx, ws, c.worktree_path, await setup);
+    seedPhase('setup_label');
     if (values.computer === true)
         await ws.setComputerUse(true);
     await uploadInitialImages(ws.cell(), images, ctx.signal);
@@ -152,17 +216,18 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
     // Without a saved machine the laptop's Claude and Codex config is copied in, after the agent has its first prompt.
     const afterStart = afterStartConfig(ctx, ws, !!(await savedMachine(ctx))?.template);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+    seedPhase('menubar');
     if (openIn) {
         // The agent starts detached in its VM; the conversation then opens in Claude Desktop or claude.ai (Remote Control).
         const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
-        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true }, afterStart);
+        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true }, afterStart, setupStart);
         if (openIn === 'claude-desktop')
             return openClaudeDesktopSession(ctx, ws, c);
         const url = await remoteControlUrl(ctx, ws, c);
-        if (!ctx.json && !openUrl(url, ctx.io.env))
+        if (!ctx.json && !(await openUrl(url, ctx.io.env)))
             throw new Error(`could not open ${url}`);
         out(ctx, `${url}\n`, { target: 'web', workspace: ws.data, conversation_id: c.id, url });
         return 0;
     }
-    return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values, afterStart);
+    return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values, afterStart, setupStart);
 }