@shardflux/cli 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,6 +1,82 @@
 # Changelog
 
-## 0.19.0 (not yet published)
+## 0.20.0 (not yet published)
+
+- **A save waits in line instead of failing** when your plan's build slots are in use: `shard machine save` and `shard
+  template save` print where the build is (`machine: saving version 5; queued behind 3 builds · about 40 s; …`), with
+  `--wait` the line updates on stderr as builds ahead finish, and `--json` carries `queue` (`position`, `slots`,
+  `expected_wait_seconds`). A full queue (`rate_limited`, `template_build_queue_full`) says how long until a retry
+  (`hint: 10 builds already wait for your plan's build slots; nothing was started. Run the same command again in about
+  5 min`). Background rebases of your machine's projects no longer take your plan's slots.
+- **Your machine sets itself up from this computer** (`shard machine setup --from-this-computer`): your own Claude
+  Code (`claude -p`), else your Codex (`codex exec`), recreates this computer's development setup on your cloud machine
+  with no question asked: its CLIs and tools, language runtimes at the same versions, shell config and aliases that
+  make sense on Linux, git identity and editor-agnostic dotfiles. It runs on your own subscription, in about 10
+  minutes at most (`--timeout`), then shard copies your Claude and Codex config and saves the machine (`shard machine
+  save --wait`). `--json` prints what was added and one line for it (`Cloud machine ready: gh, Node 24, Python 3.13, 12
+  skills`); `SHARDFLUX_PROGRESS_FILE` gets one `{phase, line}` per step, as for a conversation start.
+- On this computer the agent may only read: Claude Code runs with only Read, Glob and Bash, in `dontAsk` mode, with
+  the read-only commands it needs (`brew list`, `ls`, `which`, `git config --global --get`, `<tool> --version`) and
+  `shard` on your machine VM pre-approved, and `~/.ssh`, `~/.aws`, keychains, `.env`, token and credential files
+  denied; no MCP servers, hooks or plugins of yours load. Codex runs in its workspace-write sandbox, confined to a
+  private temporary folder. Every `shard` the agent runs only reaches your machine VM: exec, file writes from standard
+  input and reads.
+- Without Claude Code or Codex on this computer, your cloud Claude sets it up inside the machine VM from a list of
+  this computer's tools and versions (names only).
+- When an agent can't finish (a usage limit, an expired sign-in, a sandbox that keeps `shard` from the machine, a
+  crash, its time box), the next one takes over: this computer's Claude Code, then its Codex, then your cloud Claude.
+  Each gets its own time box, all of them together twice it. The setup fails only when every one stopped, naming why
+  for each; `--json` and `--status` list the agents tried in `attempts`, and `summary.runner` names the one that set
+  the machine up. `--agent` runs exactly one.
+- It runs once per computer and account: `--if-needed` (what the apps and the terminal onboarding run right after
+  their Agents step) skips a machine already set up from this computer, and a second run never starts while one is
+  running. `shard machine setup --status --json` shows the last one; a failure is exit 6, `machine_setup_failed`,
+  retryable.
+- `shard agents accounts` and `shard agents usage` name Codex plans as ChatGPT does: Pro Lite and Pro Max (they read
+  Prolite and Promax).
+- Brings the Shardflux app for Ubuntu 0.1.5: the same machine setup line in onboarding and Settings as on the Mac, and
+  the menu names the first run's sample Daylight (0.1.4). The optional dependency on `@shardflux/desktop-linux-x64` /
+  `-arm64` is exactly 0.1.5.
+- What Claude or Codex saves at the user level in a cloud conversation comes back to this computer by itself: a skill,
+  a command, an agent, an output style, a memory, or a line in `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md`. Each turn
+  end, the conversation's VM records the agent's changes in the project space; the device helper the menu bar runs
+  applies them seconds after the turn ends, in a loop of its own every 2 s that never waits for the files mirror
+  (staging, 5 turns from another device: 1.8 s p50, 2.5 s max). A new file is created. A file you haven't changed
+  here since that VM's version is replaced. A file changed in both places (or one that another conversation's VM
+  started without) keeps yours and gets the cloud's version next to it
+  (`CLAUDE.cloud.md`). A file the agent deleted goes to the Trash. Every action is a line in
+  `agent-config-return.jsonl` in the config directory. Credentials, settings, plugin caches, marketplaces, transcripts
+  and history never travel, and neither do the claude.ai account's synced skills.
+- This holds for every conversation you started, wherever you started it: this computer, the phone, the web, T3 Code
+  or another computer. User-level config is personal: a conversation a teammate started in the same organization never
+  brings its skills, memories or CLAUDE.md lines here (with an API that records who started a conversation; with an
+  older one, only conversations started on this computer apply). The device helper reads each one's changes once per
+  turn; conversations idle since before it started applying are not read.
+- Project memory travels both ways. Claude keys memory by the project's folder: the VM's folder maps to this
+  computer's checkout of the same repository (the folder a conversation of that repository was started from here),
+  and a new conversation's VM gets this computer's memory for the project under its own folder, also when a saved
+  machine carries the rest of the config. Memory of a repository this computer has no checkout of stays in the cloud.
+- With a saved machine that only you use (its organization has one member), those changes are also written into the
+  machine and saved once per batch (after a minute without changes, at most every 10 minutes; a running machine VM gets
+  up to 30 minutes first), so new conversations start with them. A machine your organization's members share gets
+  none of one member's config. Without a saved machine, the next config copy into a new VM carries this computer's
+  copy.
+- The config copy's marker in the VM lists each file's hash, so the VM tells the copy's files from the agent's own
+  changes. A conflict copy (`*.cloud.md`) stays on this computer.
+
+## 0.19.1 (2026-10-11)
+
+- A first prompt is never lost to a slow or unusual start. `--prompt` / `--prompt-file` types the prompt only into the
+  agent's input box, never into one of its dialogs ("❯ 1. Yes"). If the terminal never shows the input box and
+  nothing was typed, the prompt goes to the conversation's own inbox, which delivers it once the agent reads input.
+  `--json` then reports `"initial_prompt": {"submitted": false, "queued": true}` instead of failing with
+  `initial_prompt_failed`.
+- Brings the Shardflux app for Ubuntu 0.1.3: Try it once never waits silently. A demo agent still waiting with nothing
+  said 45 s after its start gets its task once more through its conversation, and one line says so; still nothing
+  45 s later, one line says it hasn't started. The optional dependency on `@shardflux/desktop-linux-x64` / `-arm64` is
+  exactly 0.1.3.
+
+## 0.19.0 (2026-10-11)
 
 - A new conversation on an account without a saved machine gets its first prompt in seconds, whatever is in
   `~/.claude` and `~/.codex`. The prompt is typed first, and this computer's Claude and Codex config is copied into

package/README.md

@@ -275,7 +275,9 @@ Codex conversation gets its own VM)? `shard setup --guide` prints both paths wit
    once (a claude.ai link and a code). Codex: `codex login` on this computer. Then
    `shard setup --inspect --connect --json --apps claude,codex` (0.15.0+) checks both live, copies the Codex login and
    starts the account's Codex remote device.
-3. **Build the machine** every conversation starts from. Ask your user what it should carry: languages and runtimes,
+3. **Build the machine** every conversation starts from. `shard machine setup --from-this-computer --json` (0.20.0+)
+   has this computer's Claude Code or Codex recreate its tools, runtimes, shell, git identity and dotfiles there and
+   saves it. For the rest, ask your user what it should carry: languages and runtimes,
    CLIs and tools, dotfiles and shell, secrets and credentials, editor and agent config. Then
    `shard machine open --json` (0.17.1+) prints the machine VM's key; install with
    `shard ws exec <key> -- bash -lc '...'`, write dotfiles and secret files with
@@ -1348,8 +1350,18 @@ toolchains, dependencies, services and project secrets. Both are private filesys
 as ordinary files. Browser logins and Claude/Codex config belong to the machine. Set up tools and secrets normally inside the VM;
 your agent uses the same save/rollback commands there. An agent working from your computer builds the machine with
 `shard machine open` (0.17.1+): it creates or resumes the machine VM without attaching and prints its key for
-`shard ws exec` and `shard files write`. Every agent starts from both. Save or roll back with `shard machine save|rollback` and
+`shard ws exec` and `shard files write`. `shard machine setup --from-this-computer` (0.20.0+) does it for you: your own
+Claude Code (`claude -p`, else Codex) recreates this computer's CLIs and tools, language runtimes, shell config and
+aliases, git identity and dotfiles on the machine, on your subscription, then saves it. On this computer it only reads;
+`~/.ssh`, keychains, `.env`, token and credential files are never read. The apps and the first run start it once,
+right after you connect your agents. Every agent starts from both. Save or roll back with `shard machine save|rollback` and
 `shard template save|rollback`; changed files reach running agents live, software at the next start.
+
+Skills, commands, agents, output styles, memories and `CLAUDE.md` / `AGENTS.md` lines that Claude or Codex saves in a
+cloud conversation come back to this computer by themselves, seconds after the turn ends, and into your saved
+machine too (0.20.0+). A file you changed here at the same time keeps your version, with the cloud's next to it
+(`CLAUDE.cloud.md`); a deleted one goes to the Trash. Project memory follows the project both ways. The menu bar says
+what arrived in one line, and `agent-config-return.jsonl` in the config directory lists every change.
 `shard machine save --wait` and `shard template save --wait` return once the new version is ready (0.13.3+).
 Software installed under the home goes into the saved image, linked back at the same path; the save line names those
 folders, and `--json` carries `moved_to_image` (0.18.0+).

package/dist/account-pool.d.ts

@@ -10,6 +10,7 @@ import { CodedError } from './errors.js';
 import type { HubCloud } from './cli-proxy-hub.js';
 /** "in 2h 10m", "in 4d 8h", "in 41m"; "now" once passed. */
 export declare function resetIn(resetsAt: string | null, now: number): string | null;
+export declare const planName: (planType: string) => string;
 /** Account references: the id, `<provider>:<n>` (its place in the list, from 1), the email or the label. */
 export declare function findAccount(list: AgentAccountList, ref: string): AgentAccount;
 /** The compact list: one row per account, grouped by provider. */

package/dist/account-pool.js

@@ -33,7 +33,10 @@ export function resetIn(resetsAt, now) {
     return d > 0 ? `${d}d ${h}h` : h > 0 ? `${h}h ${m}m` : `${m}m`;
 }
 const pct = (w) => `${Math.round(w.used_percent)}%`;
-const plan = (a) => a.kind === 'api_key' ? 'API key' : a.plan_type ? a.plan_type.charAt(0).toUpperCase() + a.plan_type.slice(1) : '';
+/** The plan as its provider names it (apps/api/src/agent-accounts/model.ts PERSONAL_PLANS): "promax" is Pro Max, not Promax. */
+const PLAN_NAMES = { free: 'Free', go: 'Go', plus: 'Plus', pro: 'Pro', prolite: 'Pro Lite', promax: 'Pro Max', max: 'Max' };
+export const planName = (planType) => PLAN_NAMES[planType] ?? planType.charAt(0).toUpperCase() + planType.slice(1);
+const plan = (a) => a.kind === 'api_key' ? 'API key' : a.plan_type ? planName(a.plan_type) : '';
 const threads = (n) => `${n} ${n === 1 ? 'thread' : 'threads'}`;
 const name = (a) => a.email && a.label !== a.email ? `${a.label} (${a.email})` : a.label;
 function bar(used, width = 10) {

package/dist/agent-commands.js

@@ -28,6 +28,7 @@ import { openInFor } from "./t3-mode.js";
 import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
 import { 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";
 import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
@@ -145,8 +146,12 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
                 throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
         });
         store.save(project, app);
+        let delivery;
         if (typeof values.initialPrompt === 'string') {
-            await submitInitialPrompt(signal => cellConnector(cell, session.session_id)(0, signal), values.initialPrompt, ws.key, ctx.signal, app, bytes => cell.pty.input(session.session_id, bytes));
+            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);
         }
         // 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?.();
@@ -154,7 +159,7 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
             await preparation;
             // 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 } } : {}), ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}),
+            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 } } : {}),
                 ...(hasChoice(explicit) ? { model_choice: choiceReport(explicit, applied) } : {}) }));
             await after;
             return 0;

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,150 @@
+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";
+/** 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;
+/** 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>;
+/**
+ * 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 {};