@shardflux/cli 0.19.1 → 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-files.d.ts

@@ -35,3 +35,22 @@ export declare function marketplaceSource(entry: ObjectValue): string | undefine
 export declare function collectPlugins(home: string, issues: ConfigIssue[]): Promise<PluginPlan>;
 /** Only rewrite paths to files we actually send. Missing laptop paths are never made to look portable. */
 export declare function rewritePaths(value: unknown, home: string, remoteHome: string, files: ConfigFiles, issues: ConfigIssue[], item: string): unknown;
+/** A conflict copy this computer keeps next to the user's file never travels, in either direction. */
+export declare const CONFLICT_COPY: RegExp;
+/** The user-level agent config paths that travel back from a VM: never credentials, settings, plugins or history. */
+export declare function returnablePath(rel: string): boolean;
+export declare const MEMORY_PATH: RegExp;
+/** The project root Claude keys memory by: the repository's main checkout (worktrees share it), else the folder. */
+export declare function memoryRoot(folder: string): string;
+/** This computer's home-relative path for a VM path; undefined for memory of a VM folder that is not this project. */
+export declare function localConfigPath(rel: string, record: {
+    worktree: string;
+    project_root: string;
+}, localRoot: string | undefined): string | undefined;
+/** The VM path for a local memory path, the other way round (the config copy into a new VM). */
+export declare function vmMemoryPath(rel: string, localRoot: string, vmRoot: string): string | undefined;
+/** This computer's memory for a project folder, under its home-relative path (copied into a VM under the VM's). */
+export declare function collectMemory(home: string, folder: string, issues: ConfigIssue[]): Promise<{
+    root: string;
+    files: ConfigFiles;
+}>;

package/dist/agent-config-files.js

@@ -1,5 +1,7 @@
+import { execFileSync } from 'node:child_process';
 import { readFile, readdir, realpath, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
+import { claudeProjectName } from "./local-sessions.js";
 import { LOCAL_PATH_REASON } from "./agent-config-report.js";
 export const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
 export const text = (v) => typeof v === 'string' ? v : undefined;
@@ -54,6 +56,9 @@ export async function collectTree(source, dest, files, issues, parents = new Set
         }
     }
     else if (info.isFile()) {
+        // A conflict copy (<name>.cloud.md) is this computer's to resolve; it never travels (0.20.0+).
+        if (CONFLICT_COPY.test(basename(dest)))
+            return;
         if (info.size > maxFileBytes) {
             issues.push({ item: dest, reason: 'file exceeds the 16 MiB config sync limit' });
             return;
@@ -189,3 +194,67 @@ export function rewritePaths(value, home, remoteHome, files, issues, item) {
     }
     return value;
 }
+// ---------------------------------------------------------------------------------------------------------------
+// Paths that travel back from a VM, and project memory on both sides (0.20.0+, agent-config-return.ts)
+const RETURN_PATH = /^(?:\.claude\/CLAUDE\.md|\.codex\/AGENTS\.md|\.claude\/(?:skills|commands|agents|output-styles)\/.+|\.claude\/projects\/[^/]+\/memory\/.+|\.codex\/(?:prompts|skills)\/.+)$/;
+const EXCLUDED = new Set(['.git', '.in_use', 'node_modules', '__pycache__', '.DS_Store', '.credentials.json', 'auth.json', 'projects',
+    'transcripts', 'history.jsonl', 'logs', 'cache', 'caches', '.env']);
+/** A conflict copy this computer keeps next to the user's file never travels, in either direction. */
+export const CONFLICT_COPY = /\.cloud(?:\.[A-Za-z0-9]+)?$/;
+/** The user-level agent config paths that travel back from a VM: never credentials, settings, plugins or history. */
+export function returnablePath(rel) {
+    // The claude.ai account's skills (.claude/skills/synced) and Codex's bundled ones: each computer's agent syncs those.
+    if (!RETURN_PATH.test(rel) || rel.startsWith('.codex/skills/.system/') || rel.startsWith('.claude/skills/synced/'))
+        return false;
+    const parts = rel.split('/');
+    if (parts.some(p => !p || p === '.' || p === '..'))
+        return false;
+    for (const part of parts.slice(rel.startsWith('.claude/projects/') ? 4 : 2)) {
+        if (EXCLUDED.has(part) || part.startsWith('.env.') || part.endsWith('.sf-sync'))
+            return false;
+    }
+    return !CONFLICT_COPY.test(parts[parts.length - 1]);
+}
+export const MEMORY_PATH = /^\.claude\/projects\/([^/]+)\/memory\/(.+)$/;
+/** The project root Claude keys memory by: the repository's main checkout (worktrees share it), else the folder. */
+export function memoryRoot(folder) {
+    try {
+        const common = execFileSync('git', ['-C', folder, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (basename(common) === '.git')
+            return dirname(common);
+    }
+    catch { /* not a repository */ }
+    return folder;
+}
+/** This computer's home-relative path for a VM path; undefined for memory of a VM folder that is not this project. */
+export function localConfigPath(rel, record, localRoot) {
+    if (!returnablePath(rel))
+        return undefined;
+    const memory = MEMORY_PATH.exec(rel);
+    if (!memory)
+        return rel;
+    if (!localRoot)
+        return undefined;
+    const names = new Set([record.project_root, record.worktree].filter(Boolean).map(claudeProjectName));
+    return names.has(memory[1]) ? `.claude/projects/${claudeProjectName(localRoot)}/memory/${memory[2]}` : undefined;
+}
+/** The VM path for a local memory path, the other way round (the config copy into a new VM). */
+export function vmMemoryPath(rel, localRoot, vmRoot) {
+    const memory = MEMORY_PATH.exec(rel);
+    return memory && memory[1] === claudeProjectName(localRoot) ? `.claude/projects/${claudeProjectName(vmRoot)}/memory/${memory[2]}` : undefined;
+}
+/** This computer's memory for a project folder, under its home-relative path (copied into a VM under the VM's). */
+export async function collectMemory(home, folder, issues) {
+    const root = memoryRoot(folder), files = new Map();
+    const path = `.claude/projects/${claudeProjectName(root)}/memory`;
+    try {
+        await stat(join(home, path));
+    }
+    catch (error) {
+        if (absent(error))
+            return { root, files };
+        throw error;
+    }
+    await collectTree(join(home, path), path, files, issues);
+    return { root, files };
+}

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

@@ -0,0 +1,194 @@
+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;
+/** A machine VM someone is using is left alone this long before a pending fold goes ahead anyway. */
+export declare const FOLD_DEFER_MS: number;
+export interface ReturnedFile {
+    sha256: string;
+    mode?: string;
+    size: number;
+    history: string[];
+    at: string;
+}
+export interface ReturnRecord {
+    v: 1;
+    conversation_id: string;
+    workspace_id: string;
+    app: string;
+    home: string;
+    worktree: string;
+    project_root: string;
+    seq: number;
+    updated_at: string;
+    files: Record<string, ReturnedFile>;
+    skipped?: Record<string, string>;
+}
+export type ReturnAction = 'created' | 'updated' | 'conflict' | 'trashed' | 'kept' | 'unchanged' | 'skipped';
+export interface ReturnItem {
+    vm_path: string;
+    path?: string;
+    action: ReturnAction;
+    sha256: string;
+    local_sha256?: string;
+    copy?: string;
+    trash?: string;
+    reason?: string;
+}
+/** SKILL.md → SKILL.cloud.md, next to the user's own copy. */
+export declare function conflictCopyPath(file: string): string;
+export type Decision = 'unchanged' | 'create' | 'overwrite' | 'conflict' | 'trash' | 'keep';
+/**
+ * `local` is this computer's content hash (undefined: no file), `cloud` the VM's ('' when the agent deleted it), and
+ * `known` every version the VM side held or was sent: when the local file is one of them, it has not changed here
+ * since, and the cloud's version may replace it.
+ */
+export declare function decideReturn(local: string | undefined, cloud: string, known: ReadonlySet<string>): Decision;
+export declare function validRecord(value: unknown, id: string): value is ReturnRecord;
+/** Moves a file to the user's Trash (macOS ~/.Trash, or the freedesktop Trash on Linux); never a hard delete. */
+export declare function moveToTrash(file: string, env: Record<string, string | undefined>): string;
+export interface FoldEntry {
+    vm_path: string;
+    sha256: string;
+    known: string[];
+    at: number;
+}
+interface ReturnStateFile {
+    v: 1;
+    /** Per conversation: the record sequence applied, and the API revision last read (a restart reads nothing again). */
+    conversations: Record<string, {
+        seq: number;
+        revision?: string;
+        files: Record<string, string>;
+    }>;
+    /** When this computer started applying, less 10 minutes (ms): conversations idle since before then are not read. */
+    enabled_at?: number;
+    machine_queue?: Record<string, FoldEntry>;
+    machine_deferred_since?: number;
+    machine_folded_at?: number;
+}
+export declare const journalFile: (dir: string) => string;
+export declare function readReturnState(dir: string): ReturnStateFile;
+export type ReturnCell = {
+    files: Pick<CellClient['files'], 'read' | 'readText'>;
+};
+export interface ApplyOptions {
+    home: string;
+    storeDir: string;
+    env: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    /** This computer's checkout of the conversation's project (memory maps to it). */
+    folder?: string;
+    /** Hashes the config copy sent to that VM, by VM path. */
+    sent?: Record<string, string>;
+}
+export interface ApplyResult {
+    app: string;
+    items: ReturnItem[];
+    record?: ReturnRecord;
+}
+/** Applies a conversation's record; returns what happened to each path that changed since the last application. */
+export declare function applyAgentConfigReturn(cell: ReturnCell, conversationId: string, options: ApplyOptions): Promise<ApplyResult>;
+/**
+ * One line for a batch: "Claude saved the skill deploy-checks in the cloud: it's on this Mac now". Undefined when
+ * nothing reached this computer (an unchanged or skipped path says nothing).
+ */
+export declare function returnNotice(app: string, items: ReturnItem[], platform?: NodeJS.Platform): string | undefined;
+export declare class AgentConfigReturnState {
+    readonly retries: Map<string, {
+        revision: string;
+        failures: number;
+        retryAt: number;
+    }>;
+    machine: {
+        checkedAt: number;
+        saved: boolean;
+    };
+    /** The user signed in on this computer: the session's, or the creator of its API key (refreshed every 10 minutes). */
+    identity: {
+        checkedAt: number;
+        userId?: string;
+    };
+    folding?: Promise<void>;
+}
+/** 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;
+/** 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
+ * QA FE1: 31 in one project), so the project never decides. Undefined when there is none (a conversation started on
+ * the phone, the web, T3 or another computer for a repository this computer never opened): its user-level files still
+ * apply, its project memory has nowhere to go.
+ */
+export declare function localCheckout(c: Conversation, records: Record<string, LocalConversation>): string | undefined;
+/**
+ * User-level config is personal. A conversation that names who started it applies only when that is this computer's
+ * user, wherever it started; a teammate's never does. One that does not (an older API, a conversation from before it
+ * was recorded) applies only when this computer started it.
+ */
+export declare function ownConversation(c: Pick<Conversation, 'id' | 'started_by'>, records: Record<string, LocalConversation>, me: string | undefined): boolean;
+/**
+ * Called by the transcript mirror's pass with the conversations it listed: every conversation of this computer's user
+ * (ownConversation), wherever it started (this computer, the phone, the web, T3, another computer). Each one's record is
+ * read once per turn (its revision; a restart reads nothing again) and applied. Conversations idle since before this
+ * computer started applying are never read. One notice line per pass, on the device helper's stdout for the menu bar.
+ */
+export declare function returnAgentConfigs(ctx: Ctx, records: Record<string, LocalConversation>, all: Conversation[], state: AgentConfigReturnState): Promise<string | undefined>;
+/** Memory is per project and never part of the machine; everything else the machine delivers live. */
+export declare function queueMachineFold(ctx: Ctx, state: AgentConfigReturnState, result: ApplyResult): Promise<void>;
+/**
+ * Writes the queued changes into the machine VM under the same rules (a machine copy changed since is kept) and saves
+ * the machine once for the batch, after a quiet period and at most every FOLD_INTERVAL_MS. A machine VM that is running
+ * (someone may be changing it) is left alone for up to FOLD_DEFER_MS.
+ */
+export declare function foldIntoMachine(ctx: Ctx, state: AgentConfigReturnState, now?: number): Promise<'saved' | 'waiting' | 'nothing' | 'deferred' | 'shared'>;
+export {};