@shardflux/cli 0.20.0 → 0.22.0

package/dist/agent-commands.js

@@ -1,6 +1,7 @@
-import { linuxTerminalSession, openLinuxTerminal } from "./linux-terminal.js";
+import { linuxTerminalSession } from "./linux-terminal.js";
+import { attachable, currentTerminal, openShardInTerminal, referenceFolder, reportTerminalOpen, storedTerminal } from "./terminal-apps.js";
 import { repositoryName } from "./files-mirror.js";
-import { prepareSetupCache } from "./setup-cache.js";
+import { prepareSetupCache, recordSetupCacheFailure } from "./setup-cache.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
 import { agentReachability } from "./agent-reachability.js";
 import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
@@ -21,12 +22,14 @@ import { preflightProjectSeed, projectWorkspacePath, seedAgentRepository, worksp
 import { agentName } from "./agent-git.js";
 import { cloudClaudeLogin, ensureCloudClaude, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { progress } from "./progress.js";
+import { seedEvent, seedPhase } from "./seed-phases.js";
 import { rememberLaunch } from "./agent-live.js";
 import { prepareAgentMachine } from "./agent-machine.js";
 import { installedTargets } from "./agent-targets.js";
 import { openInFor } from "./t3-mode.js";
+import { storedTitlePrefix } from "./client-settings.js";
 import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
-import { submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
+import { guestFirstPrompt, INBOX_MAX_CHARS, submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
 import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationClient } from "./conversation-commands.js";
 import { conversationTerminal, reopenConversation } from "./conversation-terminal.js";
@@ -53,7 +56,8 @@ export async function projectTemplate(ctx, remote) {
     }
 }
 /** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
- * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
+ * with before the guest names it from its first prompt (a first prompt line or the conversation's title), and
+ * `launch.titlePrefix` the marker titles start with when this computer chose one ("" for none; 0.20.1+). */
 export async function agentPty(cell, app, agent, approvals, term, signal, place, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation, task, launch) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
@@ -81,7 +85,8 @@ export async function agentPty(cell, app, agent, approvals, term, signal, place,
     }
     // A model and effort choice reaches only a guest whose run accepts it (the caller checked).
     const started = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : []), ...runFlags(launch?.choice)], {
-        env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
+        // SF_TITLE_PREFIX: the chosen marker for a launch without a conversation record (a guest before it ignores it).
+        env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(launch?.titlePrefix !== undefined ? { SF_TITLE_PREFIX: launch.titlePrefix } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (started.exitCode !== 0)
         throw new Error(`agent launch failed: ${started.stderr.trim() || `exit ${started.exitCode}`}`);
@@ -122,7 +127,12 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         if (app === 'codex' && typeof values.initialPrompt === 'string') {
             await prepareInitialCodexProject(cell, cwd, `shard-${ptyName || agent}-${app}`);
         }
-        const credentialFill = await configureCredentialFill(ctx, ws);
+        // Credential fill serves the agent's later credential prompts: configured beside the first prompt, never before it.
+        const credentialFill = configureCredentialFill(ctx, ws).catch((error) => {
+            if (!ctx.signal.aborted)
+                ctx.io.stderr.write(`Credential fill is off for this session: ${error instanceof Error ? error.message : String(error)}\n`);
+            return false;
+        });
         // This command's --model/--effort, else the conversation's own (a relaunch keeps its model). A computer whose guest
         // predates the choice starts the agent with its defaults, and this command says so once.
         const help = runHelp(cell, app, ctx.signal), explicit = modelChoice(values, app);
@@ -131,16 +141,21 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
             ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
         const term = ctx.io.env.TERM && ctx.io.env.TERM !== 'dumb' ? ctx.io.env.TERM : 'xterm-256color';
-        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title), { ...(choice ? { choice } : {}), help });
+        const titlePrefix = storedTitlePrefix(ctx.store.dir);
+        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title), { ...(choice ? { choice } : {}), help, ...(titlePrefix !== undefined ? { titlePrefix } : {}) });
+        seedPhase('harness_launch');
+        // When the harness's terminal started, by the VM's clock (the guest may start it before this command asks).
+        if (session.created_at)
+            seedEvent('harness_started', Date.parse(session.created_at));
         // A new conversation's guest can start the agent before this command reaches it, so the launch above never ran.
         // Remember it either way: listing and `agents open` then read the guest until the projection lists the session.
         rememberLaunch(ctx, ws.id);
         // The real agent is running before any cache provisioning or mount wait.
-        const preparation = prepareSetupCache(ctx, ws).catch((error) => {
-            ctx.io.stderr.write(`Account setup cache unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
-        }).then(async () => {
+        const preparation = prepareSetupCache(ctx, ws).catch((error) => recordSetupCacheFailure(ctx, ws, error)).then(async () => {
             if (!setupHash)
                 return;
+            // A new conversation's VM carries the setup labels before its setup starts (0.21.1+).
+            await conversation?.setupLabelled;
             const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { cwd, timeoutMs: 30_000, maxOutputBytes: 4096, signal: ctx.signal });
             if (queued.exitCode !== 0)
                 throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
@@ -151,12 +166,22 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
             const text = values.initialPrompt;
             // A conversation's guest delivers the prompt itself when this terminal never showed its input box (0.19.1+).
             const queue = conversation ? () => conversationClient(ctx).conversations.send(conversation.id, text, { signal: ctx.signal }) : undefined;
-            delivery = await submitInitialPrompt(signal => cellConnector(cell, session.session_id)(0, signal), text, ws.key, ctx.signal, app, bytes => cell.pty.input(session.session_id, bytes), queue);
+            // The VM's guest types it where it can (0.21.1+); this terminal types it for an older guest. A harness the guest
+            // waited for without seeing its input box gets it through the inbox, not a second wait here.
+            const guest = await guestFirstPrompt(cell, session.session_id, app, text, ws.key, ctx.signal);
+            if (guest === 'submitted')
+                delivery = 'submitted';
+            else if (guest === 'not_ready' && queue && text.length <= INBOX_MAX_CHARS) {
+                await queue();
+                delivery = 'queued';
+            }
+            else
+                delivery = await submitInitialPrompt(signal => cellConnector(cell, session.session_id)(0, signal), text, ws.key, ctx.signal, app, bytes => cell.pty.input(session.session_id, bytes), queue);
         }
         // Work that must never delay the first prompt (the laptop's agent config, 0.19.0+) starts once the agent has it.
         const after = conversation?.afterStart?.();
         if (!attach) {
-            await preparation;
+            await Promise.all([preparation, credentialFill]);
             // conversation (0.16.0+): which conversation this session is, also when its computer hosts several threads.
             // model_choice (0.17.0+): the requested model and effort, and whether this thread started with them.
             ctx.io.stdout.write(json({ workspace: ws.data, session, ...(conversation ? { conversation: { id: conversation.id } } : {}), ...(delivery ? { initial_prompt: delivery === 'submitted' ? { submitted: true } : { submitted: false, queued: true } } : {}),
@@ -166,7 +191,7 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
         const attached = attachTerminal({
-            ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
+            ...(await credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
             io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id, { passive: true }),
             wake: (signal) => ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal }),
             asleep: () => workspaceAsleep(ws),
@@ -294,12 +319,54 @@ export async function launchProjectWith(ctx, values, [path = './', explicitApp],
     await prepareAgentMachine(ctx, ws);
     return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash);
 }
+/**
+ * Whether `agents open` hands the conversation to the person's terminal app (0.20.1+) rather than attaching here:
+ * `--in terminal` with --json (an app) or `--window`, any open from a shell nobody types into (a coding agent's, or no
+ * terminal), and `--in terminal` typed in a terminal other than the chosen one.
+ */
+function opensInTerminalApp(ctx, values) {
+    if (values.detach === true)
+        return false;
+    const here = attachable(ctx.io);
+    if (values.in === undefined)
+        return !ctx.json && !here;
+    if (values.in !== 'terminal')
+        return false;
+    if (ctx.json || !here || values.window === true)
+        return true;
+    const stored = storedTerminal(ctx.store.dir);
+    return !!stored && stored.id !== currentTerminal(ctx.io.env);
+}
+/** `shard agents open <ref>` (its attach, no --in) in a new tab of the person's terminal app, in the project folder. */
+async function openInTerminalApp(ctx, ref, values, extra = {}) {
+    const words = ['agents', 'open', ref, ...(typeof values.app === 'string' ? ['--app', values.app] : [])];
+    const result = await openShardInTerminal(ctx, words, { cwd: referenceFolder(ctx.store.dir, ctx.apiUrl, ref, ctx.io.env), window: values.window === true });
+    reportTerminalOpen(ctx, result, extra);
+    return 0;
+}
+/**
+ * `--in auto` for a terminal conversation: the person's terminal app (a tab there, 0.20.1+), or this terminal when it
+ * is the one they use. --json without a chosen terminal app keeps the command for an app to run (a menu bar before
+ * 0.20.1 opens Terminal with it).
+ */
+function terminalAuto(ctx, ws, opened, values) {
+    if (ctx.json && !storedTerminal(ctx.store.dir)) {
+        out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
+        return Promise.resolve(0);
+    }
+    const next = { ...values, in: 'terminal' };
+    if (opensInTerminalApp(ctx, next))
+        return openInTerminalApp(ctx, opened, next, { workspace: ws.data });
+    delete next.in;
+    return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
+}
 export const AGENT_HANDLERS = {
     async 'agents open'(ctx, values, [agent = 'main']) {
         if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
             throw new UsageError('--app must be claude or codex');
-        if (process.platform === 'linux' && !ctx.json && !ctx.io.stdin.isTTY && values.detach !== true && (values.in === undefined || values.in === 'terminal'))
-            return openLinuxTerminal(ctx, agent, typeof values.app === 'string' ? values.app : undefined);
+        // The person's terminal app (0.20.1+): before any cloud work, the new tab owns the attach, credentials and prompts.
+        if (opensInTerminalApp(ctx, values))
+            return openInTerminalApp(ctx, agent, values);
         let resolvedConversation;
         if (/^conv_[a-z0-9]{26}$/.test(agent)) {
             resolvedConversation = await getConversation(ctx, agent);
@@ -330,15 +397,9 @@ export const AGENT_HANDLERS = {
             }
             if (chosen === 'claude-desktop' && app === 'claude')
                 return openClaudeDesktopSession(ctx, ws, resolvedConversation);
-            if (chosen === 'terminal' && app === 'claude') {
-                if (ctx.json) {
-                    out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
-                    return 0;
-                }
-                const next = { ...values };
-                delete next.in;
-                return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
-            }
+            // A terminal app attaches to the conversation's own session, Claude Code's or Codex's (Codex 0.21.1+).
+            if (chosen === 'terminal' && (app === 'claude' || app === 'codex'))
+                return terminalAuto(ctx, ws, opened, values);
             const saved = chosen === 'codex-app' ? undefined : store.read().projects?.[project]?.target ??
                 (project.startsWith('file://') ? store.read().projects?.[new URL(project).pathname]?.target : undefined);
             // Codex's default open implementation owns Cloud/desktop routing. PAS-XB replaces that path; do not pin
@@ -360,14 +421,7 @@ export const AGENT_HANDLERS = {
             if (detected.clients.includes('claude-desktop')) {
                 return openClaudeDesktopSession(ctx, ws, resolvedConversation);
             }
-            if (ctx.json) {
-                // An app runs this in the person's terminal (the menu bar opens Terminal with it).
-                out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
-                return 0;
-            }
-            const next = { ...values };
-            delete next.in;
-            return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
+            return terminalAuto(ctx, ws, opened, values);
         }
         if (values.in !== undefined && values.in !== 'terminal') {
             const { HANDLERS } = await import("./handlers.js");

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

@@ -2,6 +2,8 @@ import type { CellClient } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { Conversation, LocalConversation } from './conversations.js';
 export declare const RETURN_ROOT = "/shardflux/project/agent-config";
+/** The latest agent-config line ({notice, at}), for the Linux app's top-bar panel (CLI 0.20.2+). */
+export declare const AGENT_CONFIG_NOTICE = "agent-config-notice.json";
 /** A machine fold waits for this much quiet after the last change, and saves the machine at most this often. */
 export declare const FOLD_QUIET_MS = 60000;
 export declare const FOLD_INTERVAL_MS: number;
@@ -116,8 +118,50 @@ export declare class AgentConfigReturnState {
 }
 /** How often the device helper looks for agent config to bring back: its own loop, never behind a files or transcript pass. */
 export declare const AGENT_CONFIG_POLL_MS = 2000;
-/** One pass of the device helper's own agent-config loop: list the account's conversations and apply what came back. */
-export declare function returnAgentConfigsOnce(ctx: Ctx, state: AgentConfigReturnState): Promise<string | undefined>;
+/** With none of this user's conversations active, the full listing backs off (doubling) to this. */
+export declare const AGENT_CONFIG_IDLE_MS = 60000;
+/** While backed off, one cheap request (`state=working`, usually empty) this often notices a turn starting anywhere. */
+export declare const AGENT_CONFIG_PROBE_MS = 10000;
+/** A conversation counts as active for this long after its last activity (a turn's start or end). */
+export declare const AGENT_CONFIG_ACTIVE_WINDOW_MS: number;
+/**
+ * A working conversation counts as active only this long after its last activity: one left "working" by a VM that went
+ * away (staging QA FE1: 60 such, all more than a day old) must not hold every computer at the fast cadence. A longer
+ * turn still comes back, at the idle cadence.
+ */
+export declare const AGENT_CONFIG_WORKING_WINDOW_MS: number;
+/** This user's conversations that are working (recently) or ended a turn within the active window. */
+export declare function activeConversations(all: Conversation[], records: Record<string, LocalConversation>, me: string | undefined, now?: number): Conversation[];
+export interface CadenceOptions {
+    activeMs: number;
+    idleMs: number;
+    probeMs: number;
+}
+export declare const CADENCE: CadenceOptions;
+/**
+ * When the next listing is due. Active (one of this user's conversations works or just ended a turn): every 2 s.
+ * Idle: the interval doubles to 60 s, with a cheap working-only probe every 10 s and a check of this computer's own
+ * conversation records each second; either snaps it back to 2 s at once.
+ */
+export declare class AgentConfigCadence {
+    readonly options: CadenceOptions;
+    interval: number;
+    fullAt: number;
+    probeAt: number;
+    recordsMtime: number;
+    constructor(options?: CadenceOptions);
+    /** After a full pass: active keeps 2 s, idle doubles toward the idle ceiling. */
+    listed(active: boolean, now?: number): void;
+    snap(): void;
+    fullDue(now?: number): boolean;
+    probeDue(now?: number): boolean;
+}
+/** One full pass: list the account's conversations, apply what came back; true while one of this user's is active. */
+export declare function returnAgentConfigsOnce(ctx: Ctx, state: AgentConfigReturnState): Promise<boolean>;
+/** The cheap probe: is any of this user's conversations working right now (one request, usually an empty page)? */
+export declare function workingProbe(ctx: Ctx, state: AgentConfigReturnState): Promise<boolean>;
+/** The device helper's agent-config loop: activity-driven cadence, its own backoff on errors, never another loop's. */
+export declare function runAgentConfigLoop(ctx: Ctx, state: AgentConfigReturnState, signal: AbortSignal, cadence?: AgentConfigCadence, tickMs?: number): Promise<void>;
 /**
  * This computer's checkout of a conversation's repository: the folder it was started from here, else the folder of
  * another conversation of the same repository started here. A Shardflux project can hold many repositories (staging

package/dist/agent-config-return.js

@@ -16,16 +16,20 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { appendFileSync, chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { setTimeout as delay } from 'node:timers/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { ShardfluxApiError } from '@shardflux/sdk';
-import { listConversations, localConversations } from "./conversations.js";
+import { conversationsUnavailable, listConversations, localConversations } from "./conversations.js";
 import { MEMORY_PATH, localConfigPath, memoryRoot, returnablePath } from "./agent-config-files.js";
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { configManifests } from "./agent-config-sync.js";
 import { savedMachine } from "./filesystem-state.js";
 import { openMachine } from "./filesystem-commands.js";
+import { thisComputer } from "./this-computer.js";
 export const RETURN_ROOT = '/shardflux/project/agent-config';
+/** The latest agent-config line ({notice, at}), for the Linux app's top-bar panel (CLI 0.20.2+). */
+export const AGENT_CONFIG_NOTICE = 'agent-config-notice.json';
 const HASH = /^[0-9a-f]{64}$/;
 const MAX_BYTES = 16 << 20;
 const READ_CHUNK = 8 << 20;
@@ -328,7 +332,7 @@ function list(names) {
  */
 export function returnNotice(app, items, platform = process.platform) {
     const who = app === 'codex' ? 'Codex' : 'Claude';
-    const here = platform === 'darwin' ? 'this Mac' : 'this computer';
+    const here = thisComputer(platform);
     // A memory's MEMORY.md index line is part of saving that memory, not a memory of its own.
     const memoryNotes = items.some(i => MEMORY_PATH.test(i.vm_path) && !i.vm_path.endsWith('/memory/MEMORY.md') && ['created', 'updated', 'trashed'].includes(i.action));
     const saved = items.filter(i => (i.action === 'created' || i.action === 'updated') && !(memoryNotes && i.vm_path.endsWith('/memory/MEMORY.md'))).map(i => itemName(i.vm_path).name);
@@ -379,9 +383,104 @@ async function projectCell(ctx, c, all) {
 }
 /** How often the device helper looks for agent config to bring back: its own loop, never behind a files or transcript pass. */
 export const AGENT_CONFIG_POLL_MS = 2000;
-/** One pass of the device helper's own agent-config loop: list the account's conversations and apply what came back. */
+/** With none of this user's conversations active, the full listing backs off (doubling) to this. */
+export const AGENT_CONFIG_IDLE_MS = 60_000;
+/** While backed off, one cheap request (`state=working`, usually empty) this often notices a turn starting anywhere. */
+export const AGENT_CONFIG_PROBE_MS = 10_000;
+/** A conversation counts as active for this long after its last activity (a turn's start or end). */
+export const AGENT_CONFIG_ACTIVE_WINDOW_MS = 5 * 60_000;
+/**
+ * A working conversation counts as active only this long after its last activity: one left "working" by a VM that went
+ * away (staging QA FE1: 60 such, all more than a day old) must not hold every computer at the fast cadence. A longer
+ * turn still comes back, at the idle cadence.
+ */
+export const AGENT_CONFIG_WORKING_WINDOW_MS = 60 * 60_000;
+/** This user's conversations that are working (recently) or ended a turn within the active window. */
+export function activeConversations(all, records, me, now = Date.now()) {
+    return all.filter(c => {
+        if (c.route === 'codex-cloud' || c.ended_at || !ownConversation(c, records, me))
+            return false;
+        const idle = now - Date.parse(c.last_activity_at ?? c.created_at);
+        return idle < (c.state === 'working' ? AGENT_CONFIG_WORKING_WINDOW_MS : AGENT_CONFIG_ACTIVE_WINDOW_MS);
+    });
+}
+export const CADENCE = { activeMs: AGENT_CONFIG_POLL_MS, idleMs: AGENT_CONFIG_IDLE_MS, probeMs: AGENT_CONFIG_PROBE_MS };
+/**
+ * When the next listing is due. Active (one of this user's conversations works or just ended a turn): every 2 s.
+ * Idle: the interval doubles to 60 s, with a cheap working-only probe every 10 s and a check of this computer's own
+ * conversation records each second; either snaps it back to 2 s at once.
+ */
+export class AgentConfigCadence {
+    options;
+    interval;
+    fullAt = 0;
+    probeAt = 0;
+    recordsMtime = 0;
+    constructor(options = CADENCE) { this.options = options; this.interval = options.activeMs; }
+    /** After a full pass: active keeps 2 s, idle doubles toward the idle ceiling. */
+    listed(active, now = Date.now()) {
+        this.fullAt = now;
+        this.probeAt = now;
+        this.interval = active ? this.options.activeMs : Math.min(this.options.idleMs, Math.max(this.options.activeMs, this.interval * 2));
+    }
+    snap() { this.interval = this.options.activeMs; this.fullAt = 0; }
+    fullDue(now = Date.now()) { return now - this.fullAt >= this.interval; }
+    probeDue(now = Date.now()) { return this.interval > this.options.probeMs && now - this.probeAt >= this.options.probeMs; }
+}
+/** One full pass: list the account's conversations, apply what came back; true while one of this user's is active. */
 export async function returnAgentConfigsOnce(ctx, state) {
-    return returnAgentConfigs(ctx, localConversations(ctx), await listConversations(ctx), state);
+    const records = localConversations(ctx), all = await listConversations(ctx);
+    await returnAgentConfigs(ctx, records, all, state);
+    const me = all.some(c => c.started_by?.user_id) ? await myUserId(ctx, state) : undefined;
+    return activeConversations(all, records, me).length > 0;
+}
+/** The cheap probe: is any of this user's conversations working right now (one request, usually an empty page)? */
+export async function workingProbe(ctx, state) {
+    const page = await conversationClient(ctx).conversations.list({ state: 'working', limit: 200 });
+    const working = page.data;
+    const me = working.some(c => c.started_by?.user_id) ? await myUserId(ctx, state) : undefined;
+    return activeConversations(working, localConversations(ctx), me).length > 0;
+}
+/** The device helper's agent-config loop: activity-driven cadence, its own backoff on errors, never another loop's. */
+export async function runAgentConfigLoop(ctx, state, signal, cadence = new AgentConfigCadence(), tickMs = 1000) {
+    let failures = 0, retryAt = 0;
+    const reported = new Set();
+    const agents = join(ctx.store.dir, 'agents.json');
+    while (!signal.aborted) {
+        const now = Date.now();
+        // A conversation started on this computer is recorded in agents.json: back to 2 s before its first turn ends.
+        try {
+            const m = statSync(agents).mtimeMs;
+            if (cadence.recordsMtime && m !== cadence.recordsMtime)
+                cadence.snap();
+            cadence.recordsMtime = m;
+        }
+        catch { /* none yet */ }
+        if (now >= retryAt) {
+            try {
+                if (cadence.fullDue(now))
+                    cadence.listed(await returnAgentConfigsOnce(ctx, state));
+                else if (cadence.probeDue(now)) {
+                    cadence.probeAt = now;
+                    if (await workingProbe(ctx, state))
+                        cadence.snap();
+                }
+                failures = 0;
+            }
+            catch (e) {
+                if (signal.aborted)
+                    break;
+                const wait = Math.min(300_000, 5000 * 2 ** Math.min(failures++, 6));
+                retryAt = Date.now() + wait;
+                const message = e instanceof Error ? e.message : String(e);
+                if (!conversationsUnavailable(e) && !reported.has(message)) {
+                    reported.add(message);
+                    ctx.io.stderr.write(`Agent config: ${message} (retrying in ${wait / 1000}s).\n`);
+                }
+            }
+        }
+        await delay(tickMs, undefined, { signal }).catch(() => undefined);
+    }
 }
 /**
  * This computer's checkout of a conversation's repository: the folder it was started from here, else the folder of
@@ -498,6 +597,13 @@ export async function returnAgentConfigs(ctx, records, all, state) {
     if (line) {
         ctx.io.stdout.write(JSON.stringify({ type: 'agent_config', notice: line }) + '\n');
         ctx.io.stderr.write(`${new Date().toISOString()} ${line}\n`);
+        // The Linux app reads the line here (its helper runs under systemd, whose standard output no app sees).
+        try {
+            writePrivateFile(ctx.store.dir, join(ctx.store.dir, AGENT_CONFIG_NOTICE), JSON.stringify({ notice: line, at: new Date().toISOString() }) + '\n');
+        }
+        catch (error) {
+            ctx.io.stderr.write(`Agent config notice: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
     }
     // SHARDFLUX_AGENT_CONFIG_FOLD=off holds machine folds (an operator testing that machine); the queue keeps them.
     if (!state.folding && ctx.io.env.SHARDFLUX_AGENT_CONFIG_FOLD !== 'off')

package/dist/agent-credentials.js

@@ -3,7 +3,8 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { json } from "./format.js";
 import { UsageError } from "./errors.js";
-import { loginClaudeInWorkspace, requireClaudeTerminal, cloudClaudeLogin } from "./claude-cloud-login.js";
+import { claudeTerminal, cloudClaudeLogin, loginClaudeInWorkspace } from "./claude-cloud-login.js";
+import { askTimeout } from "./secret-ask.js";
 import { resolveWorkspace } from "./commands.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 async function optionalFile(file) {
@@ -74,7 +75,10 @@ export const AGENT_CREDENTIAL_HANDLERS = {
             output(ctx, existing);
             return 0;
         }
-        requireClaudeTerminal(ctx);
+        // In a coding agent's shell, with --json, without a terminal or with --ask (0.20.1+): the claude.ai sign-in and a
+        // page for its code open in the browser. On a terminal the sign-in attaches to it.
+        const headless = values.ask === true || !claudeTerminal(ctx);
+        const timeoutMs = askTimeout(values);
         const project = projectIdentity('./');
         let ws;
         if (typeof values.workspace === 'string')
@@ -85,7 +89,7 @@ export const AGENT_CREDENTIAL_HANDLERS = {
             const current = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
             ws = await cloud.workspaces.open({ key, template: 'coding', labels: { ...current?.labels, ...projectLabels(project, 'main', 'claude') }, wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
         }
-        output(ctx, await loginClaudeInWorkspace(ctx, ws));
+        output(ctx, await loginClaudeInWorkspace(ctx, ws, headless ? { headless: { timeoutMs } } : {}));
         return 0;
     },
     'agents credentials sync': async (ctx) => { output(ctx, await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME ?? ctx.io.env.USERPROFILE, redact: (value) => ctx.addSecret(value) })); return 0; },

package/dist/agent-repository.d.ts

@@ -22,12 +22,21 @@ export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: str
     populate?: boolean;
     initialFiles?: readonly string[];
     onInitialFiles?: () => void;
+    changes?: Promise<LocalChanges>;
+    background?: (started: Promise<unknown>) => void;
+    beforeHistory?: Promise<unknown>;
 }): Promise<void>;
 /**
  * Above this (an estimate: the repository's packed and loose objects) the workspace fetches the history from origin as a
  * blobless partial clone, and receives only the commits origin lacks (0.19.0+). Below it, one small bundle is faster.
  */
 export declare const ORIGIN_FIRST_BYTES: number;
+/**
+ * A Git step of the seed that writes the workspace repository's index, refs or config: run again, for up to ~5 s,
+ * while another Git process in the VM holds the lock (a conversation's agent starts as soon as its repository appears,
+ * and its own `git status` takes the index lock). Every step passed here is safe to repeat.
+ */
+export declare function runGitStep(cell: Pick<SyncCell, 'exec'>, argv: string[], options: Parameters<SyncCell['exec']['run']>[1] & object, attempts?: number): Promise<Awaited<ReturnType<SyncCell['exec']['run']>>>;
 /** The repository's object store size, an upper bound of any one branch's history bundle. Reads sizes only. */
 export declare function historyEstimate(folder: string, signal?: AbortSignal): Promise<number>;
 export declare const FETCH_ORIGIN: string;
@@ -39,7 +48,10 @@ export declare const CHECKOUT_HEAD: string;
  * from origin as a blobless partial clone (the workspace's own Git credentials), plus a bundle of the commits origin
  * lacks. Without a reachable origin the whole bundle is streamed in chunks: no history size refuses (0.19.0+).
  */
-export declare function importProjectHistory(cell: SyncCell, folder: string, root: string, head: string, branch: string, origin: string | null, signal?: AbortSignal, originFirst?: number, report?: (message: string) => void): Promise<{
+export declare function importProjectHistory(cell: SyncCell, folder: string, root: string, head: string, branch: string, origin: string | null, signal?: AbortSignal, originFirst?: number, report?: (message: string) => void, configure?: {
+    settings: string[];
+    excludes: string;
+}): Promise<{
     partial: string | null;
 }>;
 /**
@@ -47,11 +59,12 @@ export declare function importProjectHistory(cell: SyncCell, folder: string, roo
  * untracked files Git does not ignore, the .env files we always carry, Git LFS files (their content lives outside Git),
  * and deletions. Ignored files, nested repositories and submodule contents stay out.
  */
-export declare function localChanges(folder: string, signal?: AbortSignal): Promise<{
+export type LocalChanges = {
     copy: string[];
     remove: string[];
     skipped: {
         path: string;
         reason: string;
     }[];
-}>;
+};
+export declare function localChanges(folder: string, signal?: AbortSignal): Promise<LocalChanges>;