@shardflux/cli 0.19.1 → 0.22.0

package/dist/agent-config-return.js

@@ -0,0 +1,724 @@
+/**
+ * User-level agent config written in a cloud VM comes back to this computer (0.20.0+): a skill, a memory, a command, an
+ * agent, an output style or a CLAUDE.md / AGENTS.md line that Claude or Codex saved in a conversation's VM.
+ *
+ * - The guest records the agent's changes at each turn end in the project space (sf-agent, agentconfig.go):
+ *   /shardflux/project/agent-config/<conversation>/state.json plus one blob per content hash.
+ * - The device helper reads that record when the conversation's turn ends and applies it here:
+ *   a new file is created; a file unchanged here since the VM's version is replaced; a file changed on both sides keeps
+ *   this computer's copy and gets the cloud's next to it (<name>.cloud.md); a deletion moves the file to the Trash.
+ * - Claude keys project memory by the project's absolute path: the VM's project folder maps to this computer's
+ *   checkout of the same conversation, and back (agent-config-sync.ts copies local memory into the VM).
+ * - Every action is a line in agent-config-return.jsonl in the config directory. With a saved machine the change is
+ *   also folded into the machine (written into the machine VM, then one machine save per batch), so new conversations
+ *   start with it; without one, the next config copy into a new VM carries this computer's copy.
+ */
+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 { 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;
+/** A machine fold waits for this much quiet after the last change, and saves the machine at most this often. */
+export const FOLD_QUIET_MS = 60_000;
+export const FOLD_INTERVAL_MS = 10 * 60_000;
+/** A machine VM someone is using is left alone this long before a pending fold goes ahead anyway. */
+export const FOLD_DEFER_MS = 30 * 60_000;
+// ---------------------------------------------------------------------------------------------------------------
+// Paths
+/** SKILL.md → SKILL.cloud.md, next to the user's own copy. */
+export function conflictCopyPath(file) {
+    const ext = extname(basename(file));
+    return join(dirname(file), `${basename(file, ext)}.cloud${ext}`);
+}
+/**
+ * `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 function decideReturn(local, cloud, known) {
+    if (!cloud)
+        return local === undefined ? 'unchanged' : known.has(local) ? 'trash' : 'keep';
+    if (local === cloud)
+        return 'unchanged';
+    if (local === undefined)
+        return 'create';
+    return known.has(local) ? 'overwrite' : 'conflict';
+}
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function validRecord(value, id) {
+    const r = value;
+    if (!r || typeof r !== 'object' || r.v !== 1 || r.conversation_id !== id || !Number.isSafeInteger(r.seq) || r.seq < 1)
+        return false;
+    if (typeof r.worktree !== 'string' || typeof r.project_root !== 'string' || !r.files || typeof r.files !== 'object' || Array.isArray(r.files))
+        return false;
+    return Object.values(r.files).every(f => f && typeof f === 'object' && (f.sha256 === '' || HASH.test(f.sha256)) && Array.isArray(f.history) && f.history.every(h => HASH.test(h))
+        && Number.isSafeInteger(f.size) && f.size >= 0 && f.size <= MAX_BYTES);
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Local files: atomic writes, the Trash, the journal and what was applied
+/** Moves a file to the user's Trash (macOS ~/.Trash, or the freedesktop Trash on Linux); never a hard delete. */
+export function moveToTrash(file, env) {
+    const home = env.HOME || homedir();
+    const linux = process.platform !== 'darwin';
+    const dir = linux ? join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'Trash') : join(home, '.Trash');
+    const files = linux ? join(dir, 'files') : dir;
+    mkdirSync(files, { recursive: true, mode: 0o700 });
+    const ext = extname(basename(file)), stem = basename(file, ext);
+    let name = basename(file);
+    for (let n = 2; existsSync(join(files, name)) || (linux && existsSync(join(dir, 'info', `${name}.trashinfo`))); n++)
+        name = `${stem} ${n}${ext}`;
+    if (linux) {
+        mkdirSync(join(dir, 'info'), { recursive: true, mode: 0o700 });
+        writeFileSync(join(dir, 'info', `${name}.trashinfo`), `[Trash Info]\nPath=${encodeURI(file)}\nDeletionDate=${new Date().toISOString().slice(0, 19)}\n`, { mode: 0o600 });
+    }
+    const dest = join(files, name);
+    try {
+        renameSync(file, dest);
+    }
+    catch (error) {
+        if (error.code !== 'EXDEV')
+            throw error;
+        copyFileSync(file, dest);
+        unlinkSync(file);
+    }
+    return dest;
+}
+/** Writes through a symlinked file (a CLAUDE.md linked from a dotfiles repository keeps its link). */
+function writeAtomic(file, bytes, mode) {
+    let target = file;
+    try {
+        if (lstatSync(file).isSymbolicLink())
+            target = realpathSync(file);
+    }
+    catch { /* absent */ }
+    mkdirSync(dirname(target), { recursive: true, mode: 0o755 });
+    const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(6).toString('hex')}.sf-tmp`);
+    const fd = openSync(tmp, 'wx', mode);
+    try {
+        for (let at = 0; at < bytes.length;)
+            at += writeSync(fd, bytes, at, bytes.length - at);
+        fsyncSync(fd);
+    }
+    catch (error) {
+        closeSync(fd);
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+    closeSync(fd);
+    chmodSync(tmp, mode);
+    try {
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+function localHash(file) {
+    try {
+        const info = statSync(file);
+        if (!info.isFile())
+            return 'not-a-file';
+        return sha(readFileSync(file));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+const stateFile = (dir) => join(dir, 'agent-config-return.json');
+export const journalFile = (dir) => join(dir, 'agent-config-return.jsonl');
+const blobDir = (dir) => join(dir, 'agent-config-return', 'blobs');
+export function readReturnState(dir) {
+    try {
+        const value = JSON.parse(readFileSync(stateFile(dir), 'utf8'));
+        if (value?.v === 1 && value.conversations)
+            return value;
+    }
+    catch { /* first run, or unreadable: start over; applying again is idempotent */ }
+    return { v: 1, conversations: {} };
+}
+function saveReturnState(dir, state) { writePrivateFile(dir, stateFile(dir), JSON.stringify(state) + '\n'); }
+function journal(dir, entry) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    appendFileSync(journalFile(dir), JSON.stringify({ at: new Date().toISOString(), ...entry }) + '\n', { mode: 0o600 });
+}
+const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
+async function readBlob(cell, path, file, signal) {
+    const parts = [];
+    for (let offset = 0; offset < file.size;) {
+        signal?.throwIfAborted();
+        const chunk = await cell.files.read(path, { offset, length: Math.min(READ_CHUNK, file.size - offset) });
+        if (!chunk.length)
+            break;
+        parts.push(chunk);
+        offset += chunk.length;
+    }
+    const bytes = Buffer.concat(parts);
+    if (sha(bytes) !== file.sha256)
+        throw new Error(`${path} does not match its recorded hash`);
+    return bytes;
+}
+/** Applies a conversation's record; returns what happened to each path that changed since the last application. */
+export async function applyAgentConfigReturn(cell, conversationId, options) {
+    let raw;
+    try {
+        raw = await cell.files.readText(`${RETURN_ROOT}/${conversationId}/state.json`);
+    }
+    catch (error) {
+        if (missing(error))
+            return { app: '', items: [] };
+        throw error;
+    }
+    const record = JSON.parse(raw);
+    if (!validRecord(record, conversationId))
+        throw new Error('agent config record is not valid');
+    const state = readReturnState(options.storeDir);
+    const applied = state.conversations[conversationId] ?? { seq: 0, files: {} };
+    if (applied.seq >= record.seq)
+        return { app: record.app, items: [], record };
+    const localRoot = options.folder ? memoryRoot(options.folder) : undefined;
+    const items = [];
+    let complete = false;
+    // What was applied stays applied and journalled when a later file fails; the next pass retries the rest.
+    try {
+        for (const vmPath of Object.keys(record.files).sort()) {
+            const file = record.files[vmPath];
+            if (applied.files[vmPath] === file.sha256)
+                continue;
+            const rel = localConfigPath(vmPath, record, localRoot);
+            if (!rel) {
+                items.push({ vm_path: vmPath, action: 'skipped', sha256: file.sha256, reason: returnablePath(vmPath) ? 'memory of a VM folder with no checkout on this computer' : 'not a path that travels' });
+                applied.files[vmPath] = file.sha256;
+                continue;
+            }
+            const path = join(options.home, rel);
+            const local = localHash(path);
+            if (local === 'not-a-file') {
+                items.push({ vm_path: vmPath, path, action: 'skipped', sha256: file.sha256, reason: 'not a regular file on this computer' });
+                applied.files[vmPath] = file.sha256;
+                continue;
+            }
+            // Only versions this file's own chain held: what that VM had (its baseline and earlier turns) and what the config
+            // copy sent it. A version another conversation wrote here is not one this VM's file was made from.
+            const known = new Set([...file.history, ...(options.sent?.[vmPath] ? [options.sent[vmPath]] : [])]);
+            const decision = decideReturn(local, file.sha256, known);
+            const blobPath = `${RETURN_ROOT}/${conversationId}/blobs/${file.sha256}`;
+            const mode = () => {
+                try {
+                    return statSync(path).mode & 0o777;
+                }
+                catch {
+                    return file.mode === '0700' ? 0o755 : 0o644;
+                }
+            };
+            const item = { vm_path: vmPath, path, action: 'unchanged', sha256: file.sha256, ...(local ? { local_sha256: local } : {}) };
+            if (decision === 'create' || decision === 'overwrite') {
+                const bytes = await readBlob(cell, blobPath, file, options.signal);
+                if (decision === 'overwrite')
+                    keepBackup(options.storeDir, path);
+                writeAtomic(path, bytes, mode());
+                item.action = decision === 'create' ? 'created' : 'updated';
+                storeBlob(options.storeDir, file.sha256, bytes);
+            }
+            else if (decision === 'conflict') {
+                const bytes = await readBlob(cell, blobPath, file, options.signal);
+                const copy = conflictCopyPath(path);
+                writeAtomic(copy, bytes, mode());
+                item.action = 'conflict';
+                item.copy = copy;
+                storeBlob(options.storeDir, file.sha256, bytes);
+            }
+            else if (decision === 'trash') {
+                item.trash = moveToTrash(path, options.env);
+                item.action = 'trashed';
+            }
+            else if (decision === 'keep') {
+                item.action = 'kept';
+                item.reason = 'changed on this computer; the cloud deleted it';
+            }
+            items.push(item);
+            applied.files[vmPath] = file.sha256;
+        }
+        complete = true;
+    }
+    finally {
+        if (complete)
+            applied.seq = record.seq;
+        state.conversations[conversationId] = { ...state.conversations[conversationId], ...applied };
+        saveReturnState(options.storeDir, state);
+        for (const item of items)
+            journal(options.storeDir, { conversation_id: conversationId, app: record.app, ...item });
+    }
+    return { app: record.app, items, record };
+}
+function keepBackup(storeDir, path) {
+    const dir = join(storeDir, 'agent-config-return', 'backups', new Date().toISOString().replace(/[:.]/g, '-'));
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    copyFileSync(path, join(dir, `${basename(path)}.${randomBytes(3).toString('hex')}`));
+    // Backups older than 14 days go.
+    const root = dirname(dir), cutoff = Date.now() - 14 * 86_400_000;
+    for (const name of readdirSync(root))
+        if (statSync(join(root, name)).mtimeMs < cutoff)
+            rmSync(join(root, name), { recursive: true, force: true });
+}
+/** The cloud's bytes, kept for a machine fold that runs later. */
+function storeBlob(storeDir, hash, bytes) {
+    const dir = blobDir(storeDir);
+    if (existsSync(join(dir, hash)))
+        return;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeAtomic(join(dir, hash), bytes, 0o600);
+}
+function readStoredBlob(storeDir, hash) {
+    try {
+        const bytes = readFileSync(join(blobDir(storeDir), hash));
+        return sha(bytes) === hash ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------
+// The one line the user sees
+function itemName(vmPath) {
+    let m;
+    if ((m = /^\.(?:claude|codex)\/skills\/([^/]+)\//.exec(vmPath)))
+        return { kind: 'skill', name: `the skill ${m[1]}` };
+    if ((m = /^\.claude\/commands\/(.+)\.md$/.exec(vmPath)))
+        return { kind: 'command', name: `the command /${m[1].replace(/\//g, ':')}` };
+    if ((m = /^\.codex\/prompts\/(.+)\.md$/.exec(vmPath)))
+        return { kind: 'prompt', name: `the prompt /${m[1]}` };
+    if ((m = /^\.claude\/agents\/(.+)\.md$/.exec(vmPath)))
+        return { kind: 'agent', name: `the agent ${m[1]}` };
+    if ((m = /^\.claude\/output-styles\/(.+)\.md$/.exec(vmPath)))
+        return { kind: 'style', name: `the output style ${m[1]}` };
+    if (MEMORY_PATH.test(vmPath))
+        return { kind: 'memory', name: 'a memory' };
+    if (vmPath === '.claude/CLAUDE.md')
+        return { kind: 'rule', name: 'your CLAUDE.md' };
+    if (vmPath === '.codex/AGENTS.md')
+        return { kind: 'rule', name: 'your AGENTS.md' };
+    return { kind: 'file', name: basename(vmPath) };
+}
+function list(names) {
+    const memories = names.filter(n => n === 'a memory').length;
+    const shown = [...new Set(names.filter(n => n !== 'a memory'))];
+    if (memories)
+        shown.push(memories === 1 ? 'a memory' : `${memories} memories`);
+    if (shown.length > 3)
+        return `${shown.slice(0, 2).join(', ')} and ${shown.length - 2} more`;
+    return shown.length > 1 ? `${shown.slice(0, -1).join(', ')} and ${shown[shown.length - 1]}` : shown[0] ?? '';
+}
+/**
+ * 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 function returnNotice(app, items, platform = process.platform) {
+    const who = app === 'codex' ? 'Codex' : 'Claude';
+    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);
+    const removed = items.filter(i => i.action === 'trashed').map(i => itemName(i.vm_path).name);
+    const both = items.filter(i => i.action === 'conflict');
+    const parts = [];
+    if (saved.length) {
+        const many = new Set(saved).size > 1 || saved.filter(n => n === 'a memory').length > 1 || /^\d/.test(list(saved));
+        parts.push(`${who} saved ${list(saved)} in the cloud: ${many ? 'they\'re' : 'it\'s'} on ${here} now`);
+    }
+    if (removed.length)
+        parts.push(`${parts.length ? 'removed' : `${who} removed`} ${list(removed)} in the cloud (moved to the Trash)`);
+    if (both.length) {
+        const first = both[0];
+        parts.push(`${parts.length ? 'changed' : `${who} changed`} ${list(both.map(i => itemName(i.vm_path).name))} in the cloud while you changed ${both.length === 1 ? 'it' : 'them'} here: both kept${both.length === 1 && first.copy ? ` (${basename(first.copy)})` : ''}`);
+    }
+    return parts.length ? parts.join('; ') : undefined;
+}
+// ---------------------------------------------------------------------------------------------------------------
+// The device helper's pass
+export class AgentConfigReturnState {
+    retries = new Map();
+    machine = { checkedAt: 0, saved: false };
+    /** The user signed in on this computer: the session's, or the creator of its API key (refreshed every 10 minutes). */
+    identity = { checkedAt: 0 };
+    folding;
+}
+const revisionOf = (c) => JSON.stringify([c.workspace_id, c.state, c.last_activity_at ?? null, c.ended_at, c.durable?.branch_sha ?? null]);
+/** A VM that can read the project space without waking anything: the conversation's own, then any awake one. */
+async function projectCell(ctx, c, all) {
+    for (const candidate of [c, ...all.filter(o => o.project_id === c.project_id && o.id !== c.id && !o.ended_at)]) {
+        try {
+            const ws = await conversationClient(ctx).workspaces.get(candidate.workspace_id);
+            if (!ws.data.deleted_at && ws.ready)
+                return ws;
+        }
+        catch { /* another may be awake */ }
+    }
+    // An ended conversation's last changes: the project's space reader (the transcript mirror wakes it for the same turn).
+    if (!c.ended_at)
+        return undefined;
+    const client = conversationClient(ctx);
+    const reader = await client.conversations.spaceReader(c.project_id, { signal: ctx.signal });
+    const ws = await client.workspaces.get(reader.workspace.id);
+    if (!ws.ready)
+        await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    return ws;
+}
+/** 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;
+/** 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) {
+    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
+ * 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 function localCheckout(c, records) {
+    if (records[c.id])
+        return records[c.id].folder;
+    if (!c.repo_remote)
+        return undefined;
+    return Object.values(records).filter(r => r.conversation.repo_remote === c.repo_remote)
+        .sort((a, b) => (b.conversation.created_at ?? '').localeCompare(a.conversation.created_at ?? ''))[0]?.folder;
+}
+/** This computer's user, or undefined when the API cannot say (an older API, a key without a known creator). */
+async function myUserId(ctx, state) {
+    if (Date.now() - state.identity.checkedAt < 10 * 60_000)
+        return state.identity.userId;
+    let userId;
+    try {
+        const me = await conversationClient(ctx).me();
+        userId = me.user?.id ?? me.api_key?.created_by_user_id ?? undefined;
+    }
+    catch { /* unknown: only conversations recorded here apply */ }
+    state.identity = { checkedAt: Date.now(), ...(userId ? { userId } : {}) };
+    return userId;
+}
+/**
+ * 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 function ownConversation(c, records, me) {
+    const by = c.started_by?.user_id;
+    return by ? !!me && by === me : !!records[c.id];
+}
+/**
+ * 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 async function returnAgentConfigs(ctx, records, all, state) {
+    let saved = readReturnState(ctx.store.dir);
+    // A turn that ended in the 10 minutes before this computer started applying (an update, a restart) still counts.
+    if (!saved.enabled_at) {
+        saved.enabled_at = Date.now() - 10 * 60_000;
+        saveReturnState(ctx.store.dir, saved);
+        saved = readReturnState(ctx.store.dir);
+    }
+    const items = [];
+    let app = '';
+    const manifests = (() => { try {
+        return configManifests(ctx);
+    }
+    catch {
+        return {};
+    } })();
+    const me = all.some(c => c.started_by?.user_id) ? await myUserId(ctx, state) : undefined;
+    // The turn that just ended first: one slow conversation (a reader to wake) never holds back a fresh one.
+    for (const c of [...all].sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''))) {
+        if (!ownConversation(c, records, me))
+            continue;
+        // A handed-off conversation ended before this pass; codex-cloud threads have no VM home.
+        if (records[c.id]?.handed_off || c.route === 'codex-cloud')
+            continue;
+        const revision = revisionOf(c);
+        if (saved.conversations[c.id]?.revision === revision)
+            continue;
+        if (!saved.conversations[c.id] && Date.parse(c.last_activity_at ?? c.created_at) < saved.enabled_at)
+            continue;
+        let retry = state.retries.get(c.id);
+        if (!retry || retry.revision !== revision) {
+            retry = { revision, failures: 0, retryAt: 0 };
+            state.retries.set(c.id, retry);
+        }
+        if (Date.now() < retry.retryAt)
+            continue;
+        try {
+            const ws = await projectCell(ctx, c, all);
+            if (!ws)
+                continue;
+            const cell = ws.cell({ wake: null });
+            try {
+                const sent = Object.values(manifests).find(m => m.workspace_id === c.workspace_id && m.api_url === ctx.apiUrl);
+                const result = await applyAgentConfigReturn(cell, c.id, { home: ctx.io.env.HOME || homedir(), storeDir: ctx.store.dir, env: ctx.io.env, signal: ctx.signal,
+                    folder: localCheckout(c, records), sent: Object.fromEntries(Object.entries(sent?.files ?? {}).map(([p, f]) => [p, f.hash])) });
+                if (result.items.length) {
+                    app ||= result.app;
+                    items.push(...result.items);
+                }
+                if (result.items.some(i => ['created', 'updated', 'trashed', 'conflict'].includes(i.action)))
+                    await queueMachineFold(ctx, state, result);
+            }
+            finally {
+                cell.close();
+            }
+            const next = readReturnState(ctx.store.dir);
+            next.conversations[c.id] = { ...(next.conversations[c.id] ?? { seq: 0, files: {} }), revision };
+            saveReturnState(ctx.store.dir, next);
+            state.retries.delete(c.id);
+        }
+        catch (error) {
+            if (ctx.signal.aborted)
+                break;
+            const backoff = Math.min(300_000, 5000 * 2 ** Math.min(retry.failures++, 6));
+            retry.retryAt = Date.now() + backoff;
+            ctx.io.stderr.write(`Agent config from ${c.id}: ${error instanceof Error ? error.message : String(error)} (retrying in ${backoff / 1000}s).\n`);
+        }
+    }
+    const line = returnNotice(app, items);
+    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')
+        state.folding = foldIntoMachine(ctx, state).then(() => undefined, (error) => {
+            ctx.io.stderr.write(`Agent config into the machine: ${error instanceof Error ? error.message : String(error)}\n`);
+        }).finally(() => { state.folding = undefined; });
+    return line;
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Folding into the saved machine
+/**
+ * The saved machine belongs to the organization: every member's new conversations start from it. A user's personal
+ * config goes into it only while that user is its only member (`members` 1); a shared machine, or an API that does not
+ * say, gets nothing.
+ */
+const personalMachine = (m) => !!m?.template && m.members === 1;
+async function hasSavedMachine(ctx, state) {
+    if (Date.now() - state.machine.checkedAt > 10 * 60_000) {
+        state.machine = { checkedAt: Date.now(), saved: personalMachine(await savedMachine(ctx)) };
+    }
+    return state.machine.saved;
+}
+/** Memory is per project and never part of the machine; everything else the machine delivers live. */
+export async function queueMachineFold(ctx, state, result) {
+    if (!result.record || !(await hasSavedMachine(ctx, state)))
+        return;
+    const saved = readReturnState(ctx.store.dir);
+    const queue = saved.machine_queue ?? {};
+    for (const item of result.items) {
+        if (MEMORY_PATH.test(item.vm_path) || !['created', 'updated', 'trashed', 'conflict'].includes(item.action))
+            continue;
+        const file = result.record.files[item.vm_path];
+        queue[item.vm_path] = { vm_path: item.vm_path, sha256: file.sha256, known: [...new Set([...file.history, ...(queue[item.vm_path] ? [queue[item.vm_path].sha256, ...queue[item.vm_path].known] : [])])], at: Date.now() };
+    }
+    saved.machine_queue = queue;
+    saveReturnState(ctx.store.dir, saved);
+}
+/**
+ * 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 async function foldIntoMachine(ctx, state, now = Date.now()) {
+    const saved = readReturnState(ctx.store.dir);
+    const queue = Object.values(saved.machine_queue ?? {});
+    if (!queue.length)
+        return 'nothing';
+    if (now - Math.max(...queue.map(e => e.at)) < FOLD_QUIET_MS || now - (saved.machine_folded_at ?? 0) < FOLD_INTERVAL_MS)
+        return 'waiting';
+    const cloud = ctx.cloud();
+    const machine = await cloud.machine.get({ signal: ctx.signal });
+    if (machine.template && !personalMachine(machine)) {
+        // A member joined since these were queued: the machine is shared now, and one user's config stays theirs.
+        const after = readReturnState(ctx.store.dir);
+        for (const entry of queue)
+            journal(ctx.store.dir, { machine: machine.organization_id, vm_path: entry.vm_path, action: 'machine_skipped', sha256: entry.sha256,
+                reason: `the machine is shared by ${machine.members ?? 'several'} members` });
+        delete after.machine_queue;
+        saveReturnState(ctx.store.dir, after);
+        return 'shared';
+    }
+    if (!machine.template || machine.state === 'building')
+        return 'waiting';
+    const existing = await cloud.workspaces.findByKey(`machine/${machine.organization_id}/v${machine.version}`, { includeDeleted: false, signal: ctx.signal });
+    if (existing?.data.observed_state === 'running' && now - (saved.machine_deferred_since ?? now) < FOLD_DEFER_MS) {
+        if (!saved.machine_deferred_since) {
+            saved.machine_deferred_since = now;
+            saveReturnState(ctx.store.dir, saved);
+        }
+        return 'deferred';
+    }
+    const { ws } = await openMachine({ ...ctx, io: { ...ctx.io, stderr: { write: () => true } } }, machine, { sync: false });
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    let changed = 0;
+    try {
+        for (const entry of queue) {
+            const path = `/home/user/${entry.vm_path}`;
+            let current;
+            try {
+                const info = await cell.files.stat(path, { revision: true });
+                current = info.type === 'file' ? info.revision ?? undefined : 'not-a-file';
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+            }
+            const decision = decideReturn(current, entry.sha256, new Set(entry.known));
+            if (decision === 'create' || decision === 'overwrite') {
+                const bytes = readStoredBlob(ctx.store.dir, entry.sha256);
+                if (!bytes)
+                    continue;
+                await cell.files.write(path, bytes, { createParents: true, mode: '0600' });
+                changed++;
+            }
+            else if (decision === 'trash') {
+                await cell.files.remove(path);
+                changed++;
+            }
+            journal(ctx.store.dir, { machine: machine.organization_id, vm_path: entry.vm_path, action: decision === 'create' ? 'machine_created' : decision === 'overwrite' ? 'machine_updated' : decision === 'trash' ? 'machine_removed' : decision === 'unchanged' ? 'machine_unchanged' : 'machine_kept', sha256: entry.sha256 });
+        }
+    }
+    finally {
+        cell.close();
+    }
+    let version;
+    if (changed)
+        version = (await cloud.machine.save({ workspaceId: ws.id }, { signal: ctx.signal })).pending?.version;
+    const after = readReturnState(ctx.store.dir);
+    for (const entry of queue)
+        if (after.machine_queue?.[entry.vm_path]?.at === entry.at)
+            delete after.machine_queue[entry.vm_path];
+    after.machine_folded_at = now;
+    delete after.machine_deferred_since;
+    saveReturnState(ctx.store.dir, after);
+    if (changed)
+        ctx.io.stderr.write(`${new Date().toISOString()} machine: ${changed} agent config file${changed === 1 ? '' : 's'} from the cloud folded in; version ${version ?? '?'} saving\n`);
+    return changed ? 'saved' : 'nothing';
+}