@shardflux/cli 0.24.0 → 0.25.0

package/dist/land.js

@@ -0,0 +1,238 @@
+/**
+ * Landing a result for real (0.25.0+): `shard task land <task>` and `shard conversations land <id> merge`.
+ *
+ * A board task has one result: its master merges its workers' branches into shard/<task id> on the project hub before it
+ * seals done (a master that did not is helped here: its workers' branches are merged into it when they merge cleanly).
+ * Landing then
+ *   1. merges the result into the project's default branch on the hub, in a VM of the project (task-land-hub.py): a
+ *      fast-forward, or a merge commit when the merge is clean, never by force; and checks there that the result
+ *      commit is contained in the branch;
+ *   2. brings it into the person's linked folder on this computer through the live twin's own landing
+ *      (worktree-twin.ts landingRound from the hub): the branch moves to the new commits, uncommitted edits stay, every
+ *      rewritten file is backed up first, and a Git operation in progress or a file being edited waits;
+ *   3. only then records it (POST /v1/tasks/{id}/land with the commit; for a conversation POST /land merge into the
+ *      branch). A conflict changes nothing: the task's master is asked to merge (a steer) and nothing is recorded.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { conversationClient } from "./conversation-commands.js";
+import { localConversations } from "./conversations.js";
+import { CodedError } from "./errors.js";
+import { selectedProjects } from "./project-preparation.js";
+import { HUB_PATH, backupRoot, deviceId, git, gitText, inspectWorktree, landingRound, listWorktrees } from "./worktree-twin.js";
+import { projectHubCell } from "./worktree-twin-engine.js";
+let script;
+/** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
+export function hubScript() { return script ??= readFileSync(new URL('./task-land-hub.py', import.meta.url), 'utf8'); }
+/** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
+export async function landOnHub(cell, input, signal) {
+    const body = { hub: input.hub ?? HUB_PATH, result: input.result, sources: input.sources, title: input.title, ...(input.into ? { default: input.into } : {}) };
+    const r = await cell.exec.run(['python3', '-c', hubScript()], { stdin: JSON.stringify(body), timeoutMs: 300_000, maxOutputBytes: 1 << 20, ...(signal ? { signal } : {}) });
+    const line = r.stdout.trim().split('\n').at(-1) ?? '';
+    if (r.exitCode !== 0 || !line.startsWith('{'))
+        return { state: 'error', into: input.into ?? '', reason: 'script', message: `the landing script exited ${r.exitCode}: ${r.stderr.trim().slice(-400)}` };
+    return JSON.parse(line);
+}
+/** The branch to land in: the one checked out in the folder, else the hub's default branch when the folder has it. */
+export async function folderBranch(folder, fallback) {
+    const info = await inspectWorktree(folder);
+    const own = info.branch?.replace(/^refs\/heads\//, '');
+    if (own && !own.startsWith('shard/'))
+        return own;
+    const has = await git(folder, ['rev-parse', '-q', '--verify', `refs/heads/${fallback}^{commit}`], { ok: [0, 1, 128] });
+    return has.code === 0 ? fallback : null;
+}
+/**
+ * The result into the folder through the twin's landing (from the hub): the branch moves, the person's uncommitted
+ * edits stay, and the landed commit is checked to be on the branch.
+ */
+export async function landInFolder(cell, f) {
+    const deadline = Date.now() + (f.patienceMs ?? 20_000);
+    const target = (await listWorktrees(f.folder)).find(w => w.branch === `refs/heads/${f.into}`);
+    const repo = target?.root ?? f.folder;
+    for (let attempt = 0;; attempt++) {
+        const worktree = target ? await inspectWorktree(target.root) : null;
+        const o = await landingRound(cell, {
+            conversation: { id: f.name, name: f.name, title: f.title, summary: '', branch: f.branch, base_commit: f.base, worktree_path: '' },
+            into: f.into, mode: 'auto', device: f.device, repo, worktree, stateDir: f.stateDir, backupRoot: backupRoot(f.stateDir), fromHub: {},
+            ...(f.hub ? { hub: f.hub } : {}), ...(f.quietMs !== undefined ? { quietMs: f.quietMs } : {}), ...(f.signal ? { signal: f.signal } : {}),
+        });
+        const tip = async () => gitText(repo, ['rev-parse', `refs/heads/${f.into}`]);
+        switch (o.state) {
+            case 'landed': {
+                await o.confirmed.catch(() => undefined);
+                const landed = o.land.tip, now = await tip();
+                const on = await git(repo, ['merge-base', '--is-ancestor', landed, `refs/heads/${f.into}`], { ok: [0, 1] });
+                if (on.code !== 0)
+                    throw new CodedError('land_unverified', `${f.into} in ${f.folder} does not contain the landed commit ${landed.slice(0, 7)}.`);
+                return { path: f.folder, into: f.into, state: 'landed', sha: now, method: o.land.method ?? 'landed', files: o.applied.files.length, kept: o.applied.raced, backup: o.applied.backup };
+            }
+            case 'noop': return { path: f.folder, into: f.into, state: 'already', sha: await tip() };
+            case 'conflict': return { path: f.folder, into: f.into, state: 'conflict', conflicts: o.land.conflicts ?? [] };
+            case 'error': throw new CodedError('land_failed', `Could not land into ${f.folder}: ${o.land.message ?? o.land.reason ?? 'the landing failed'}.`);
+            case 'pr':
+            case 'deferred': return { path: f.folder, into: f.into, state: 'waiting', reason: o.state };
+            default: {
+                // paused (a Git operation), moved (the branch or a file changed while landing), busy (a file just saved).
+                const wait = o.state === 'busy' ? Math.min(o.waitMs ?? 1000, 3000) : o.state === 'moved' ? 200 : 1000;
+                if (Date.now() + wait > deadline || attempt >= 20)
+                    return { path: f.folder, into: f.into, state: 'waiting', reason: o.reason };
+                await delay(wait, undefined, f.signal ? { signal: f.signal } : {});
+            }
+        }
+    }
+}
+/** The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started. */
+export function linkedFolder(ctx, projectId, conversationId) {
+    const repo = (folder) => folder && existsSync(join(folder, '.git')) ? folder : null;
+    const records = localConversations(ctx);
+    const own = conversationId ? repo(records[conversationId]?.folder) : null;
+    if (own)
+        return own;
+    // A folder linked with `shard projects link` belongs to the signed-in project until its preparation names one.
+    const profile = ctx.store.profile(ctx.apiUrl), mine = profile.project_id ?? profile.api_key?.project_id;
+    const linked = selectedProjects(ctx).filter(p => (p.project_id ?? mine) === projectId).map(p => repo(p.folder)).find(Boolean);
+    if (linked)
+        return linked;
+    return Object.values(records).filter(r => r.project_id === projectId).map(r => repo(r.folder)).find(Boolean) ?? null;
+}
+export const displayPath = (path) => { const home = homedir(); return path === home ? '~' : path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path; };
+const short = (sha) => (sha ?? '').slice(0, 7);
+const list = (files) => files.length > 4 ? `${files.slice(0, 4).join(', ')} and ${files.length - 4} more` : files.join(', ');
+function message(o) {
+    const f = o.folder;
+    if (f && (f.state === 'landed' || f.state === 'already'))
+        return `Landed in ${f.display} · ${short(f.sha)}`;
+    const hub = `Landed in ${o.hub.into} on the project hub · ${short(o.hub.sha)}`;
+    if (f?.state === 'conflict')
+        return `${hub}. Not in ${f.display}: your commits on ${f.into} change ${list(f.conflicts ?? [])} too.`;
+    if (f?.state === 'waiting')
+        return `${hub}. ${f.display} gets it once it is not busy (${f.reason ?? 'busy'}).`;
+    return hub;
+}
+export function landDeps(ctx) {
+    return { client: conversationClient(ctx), hubCell: p => projectHubCell(ctx, p, ctx.signal, 'shard-land'), folder: (p, c) => linkedFolder(ctx, p, c),
+        device: deviceId(ctx.store.dir), stateDir: ctx.store.dir, signal: ctx.signal };
+}
+async function land(d, l, onConflict) {
+    const vm = await d.hubCell(l.projectId);
+    try {
+        const input = { result: l.result, sources: l.sources.map(s => s.branch), title: l.title, ...(d.hub ? { hub: d.hub } : {}) };
+        let hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'raced')
+            hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'conflict') {
+            await onConflict(hub);
+            throw new CodedError('land_conflict', `Not landed: ${list(hub.conflicts ?? [])} changed on both sides (${hub.stage === 'integrate' ? `${hub.source} and ${l.result}` : `${l.result} and ${hub.into}`}).`, 'its master merges them and asks to land again', { stage: hub.stage, into: hub.into, conflicts: hub.conflicts ?? [] });
+        }
+        if (hub.state === 'missing')
+            throw new CodedError('land_nothing', `Nothing to land: the project hub has no ${l.result} yet.`, 'land after the work is done', { branch: l.result });
+        if (hub.state !== 'landed')
+            throw new CodedError('land_failed', `Could not land on the project hub: ${hub.message ?? hub.reason ?? hub.state}.`, 'try again in a moment', { stage: hub.stage ?? null });
+        const contained = l.sources.filter(s => hub.contained?.includes(s.branch)).map(s => s.conversation_id);
+        let folder = null;
+        if (l.folder) {
+            const into = await folderBranch(l.folder, hub.into);
+            if (!into)
+                folder = { path: l.folder, display: displayPath(l.folder), into: hub.into, state: 'skipped', reason: 'detached' };
+            else {
+                const f = await landInFolder(vm.cell, { folder: l.folder, into, name: l.name, title: l.title, branch: l.result, base: l.base ?? hub.merge_base ?? hub.before ?? hub.result,
+                    device: d.device, stateDir: d.stateDir, ...(d.hub ? { hub: d.hub } : {}), ...(d.quietMs !== undefined ? { quietMs: d.quietMs } : {}), ...(d.signal ? { signal: d.signal } : {}) });
+                folder = { ...f, display: displayPath(f.path) };
+            }
+        }
+        return { title: l.title, result: { branch: l.result, sha: hub.result }, hub: { into: hub.into, sha: hub.after, method: hub.method }, folder, contained };
+    }
+    finally {
+        vm.close();
+    }
+}
+/** What a landing did, for people: the line, then what was not recorded. */
+export function landedText(o) {
+    return `${o.message}\n${o.recorded ? '' : `Not recorded on the board: ${o.record_error ?? 'unknown'}.\n`}`;
+}
+const recordFailure = (error) => {
+    const e = error;
+    return e.status === 404 ? 'this API does not record task landings yet' : (e.message ?? String(error));
+};
+/** The task's current result: its master's latest final report, when it is done. */
+function currentResult(d) {
+    const own = d.task.master_id ? d.reports.filter(r => r.author_id === d.task.master_id) : d.reports;
+    const final = [...own].reverse().find(r => r.milestone === 'done' || r.milestone === 'failed' || r.milestone === 'planned');
+    return final?.milestone === 'done' ? final.id : null;
+}
+const resultBranch = (taskId) => `shard/${taskId}`;
+/** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
+export async function landTask(d, taskId, opts = {}) {
+    const client = d.client, signal = d.signal ? { signal: d.signal } : {};
+    const detail = await client.tasks.get(taskId, signal);
+    const task = detail.task, title = task.title ?? task.text.split('\n')[0].slice(0, 80);
+    const report = currentResult(detail);
+    if (!report || (task.state !== 'done' && task.state !== 'unverified'))
+        throw new CodedError('task_not_done', 'This task has no finished result to land yet.', 'land it after its master’s done report', { state: task.state });
+    const workers = [];
+    for (const c of task.conversations) {
+        if (c.role === 'master' || c.role === 'reviewer')
+            continue;
+        const w = await client.conversations.get(c.id);
+        if (w.join_mode !== 'reviewer' && (w.changes?.commits ?? 0) > 0 && w.landed?.how !== 'discarded')
+            workers.push(w);
+    }
+    const folder = opts.path ?? d.folder(task.project_id);
+    const done = await land(d, { projectId: task.project_id, title, name: taskId, result: resultBranch(taskId), sources: workers.map(w => ({ branch: w.branch, conversation_id: w.id })),
+        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder }, async (hub) => {
+        const what = hub.stage === 'integrate' ? `${hub.source} into ${resultBranch(taskId)}` : `${resultBranch(taskId)} into ${hub.into}`;
+        await client.tasks.steer(taskId, `Land could not merge ${what}: ${list(hub.conflicts ?? [])} changed on both sides. Merge ${hub.into} from the project hub and every worker branch into ${resultBranch(taskId)}, resolve the conflicts so both changes work (ask the person only if the choice is theirs), run the tests, push ${resultBranch(taskId)} to the hub and seal done again.`, signal);
+    });
+    let recorded = false, record_error;
+    try {
+        await client.tasks.recordLanding(taskId, { sha: done.result.sha, into: done.hub.into, branch: done.result.branch, reportId: report, conversationIds: done.contained }, signal);
+        recorded = true;
+    }
+    catch (error) {
+        record_error = recordFailure(error);
+        // An API without task landings (before train 41) keeps a land item per worker: the workers whose branches are in
+        // the landed commit are recorded as merged into the branch, which is true, so those items go.
+        if (error.status === 404 && done.contained.length) {
+            let all = true;
+            for (const id of done.contained) {
+                try {
+                    await client.conversations.land(id, 'merge', { into: done.hub.into, ...signal });
+                }
+                catch {
+                    all = false;
+                }
+            }
+            if (all) {
+                recorded = true;
+                record_error = undefined;
+            }
+        }
+    }
+    const { title: t, result, hub, folder: f } = done;
+    const o = { title: t, result, hub, folder: f, landed: true, task_id: taskId, recorded, ...(record_error ? { record_error } : {}) };
+    return { ...o, message: message(o) };
+}
+/** `shard conversations land <id> merge`: the conversation's branch into the default branch and its folder, then recorded. */
+export async function landConversation(d, id, opts = {}) {
+    const client = d.client;
+    const c = await client.conversations.get(id);
+    if (c.changes?.uncommitted)
+        throw new CodedError('uncommitted_changes', 'The conversation has uncommitted changes.', 'ask its agent to commit them, then land');
+    const folder = opts.path ?? d.folder(c.project_id, c.id);
+    const done = await land(d, { projectId: c.project_id, title: c.title || c.branch, name: c.name ?? c.branch.replace(/^shard\//, ''), result: c.branch, sources: [],
+        base: c.base_commit ?? null, folder }, () => Promise.resolve());
+    let recorded = false, record_error;
+    try {
+        await client.conversations.land(id, 'merge', { into: done.hub.into, ...(d.signal ? { signal: d.signal } : {}) });
+        recorded = true;
+    }
+    catch (error) {
+        record_error = recordFailure(error);
+    }
+    const { title: t, result, hub, folder: f } = done;
+    const o = { title: t, result, hub, folder: f, landed: true, conversation_id: id, recorded, ...(record_error ? { record_error } : {}) };
+    return { ...o, message: message(o) };
+}

package/dist/main.js

@@ -66,7 +66,11 @@ function hintFor(info, cred, file, command = '') {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'operation_failed' && info.retryable) {
-        return info.details?.error_code === 'capacity_unavailable' ? 'nothing was started; run the same command again' : 'the operation may succeed if you retry it later.';
+        if (info.details?.error_code === 'capacity_unavailable') {
+            const retry = info.details.retry_after_seconds;
+            return `nothing was started; run the same command again${typeof retry === 'number' && retry > 0 ? ` after ${retry} s` : ''}`;
+        }
+        return 'the operation may succeed if you retry it later.';
     }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
@@ -175,6 +179,8 @@ function allowanceHint(info) {
     const resets = typeof info.details?.resets_at === 'string' ? ` (the period resets ${time(info.details.resets_at)})` : '';
     switch (info.details?.reason) {
         case 'allowance_used':
+            if (info.details?.spend_cap === null)
+                return 'choose a paid plan: shard billing plans; overage is unavailable on the current plan';
             return `upgrade (shard billing plans), or turn on overage: shard billing overage on --cap <dollars>${resets}`;
         case 'spend_cap_reached':
             return `the spend cap is reached: raise it (shard billing overage cap <dollars>, at most the plan price) or upgrade${resets}`;
@@ -371,6 +377,9 @@ const NO_NUDGE_REASONS = new Set([
     // Inbound ports (0.9.0): the hint names the command to expose or close a port.
     'port_not_exposed',
     'port_limit',
+    // Permission requests (0.25.0+): answered already (here or where the agent runs), or its agent no longer waits.
+    'permission_answered',
+    'permission_canceled',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback

package/dist/move-files.d.ts

@@ -0,0 +1,39 @@
+import type { CellClient } from '@shardflux/sdk';
+import type { SessionHarness } from './local-sessions.js';
+export declare const VM_HOME = "/home/user";
+export interface SessionFile {
+    path: string;
+    bytes: number;
+    mode: number;
+    why: 'handed' | 'opened' | 'named';
+}
+export interface SessionFiles {
+    files: SessionFile[];
+    left: string[];
+}
+/** Absolute and home paths in free text: `@"/a b/c.md"`, `/x/y.md`, `~/notes.md`. */
+export declare function pathsIn(text: string): string[];
+/** What the transcript says the session was handed and opened, as spelled there (a `~/` path is not expanded yet). */
+export declare function sessionMentions(bytes: Buffer, harness: SessionHarness): {
+    handed: string[];
+    opened: string[];
+};
+/**
+ * The files to carry: regular files under `home`, outside every root (the moved checkout and the repository's other
+ * worktrees), not private, within the bounds. Handed files come first, then opened ones, then the ones a handed file
+ * names; `left` lists the ones past the bounds.
+ */
+export declare function sessionFiles(bytes: Buffer, harness: SessionHarness, home: string, roots: readonly string[]): SessionFiles;
+/** Where a carried file goes in the VM. */
+export declare const vmPath: (home: string, path: string) => string;
+/** `~/Downloads/handoff.md` for display. */
+export declare const homeSpelling: (home: string, path: string) => string;
+type FilesCell = Pick<CellClient, 'exec' | 'files'>;
+export declare function writeChunks(cell: Pick<FilesCell, 'files'>, path: string, bytes: Uint8Array, mode?: string): Promise<void>;
+/**
+ * Writes each file under the VM's home, then links this computer's home path to the VM's home when it is free there
+ * (`/Users/alex` → `/home/user`), so absolute paths in the history resolve. A VM without sudo keeps the home-relative
+ * copies; the link is a convenience, never a reason to fail the move.
+ */
+export declare function placeSessionFiles(cell: FilesCell, found: SessionFiles, home: string, signal?: AbortSignal): Promise<boolean>;
+export {};

package/dist/move-files.js

@@ -0,0 +1,167 @@
+/**
+ * Files a moved session used outside its project (0.25.0+): what the user handed it (an @-mention, a path typed in a
+ * prompt), what it opened with Read, Edit or Write, and the files a handed text file names (a handoff's own
+ * references). Each goes into the VM under its home at the same home-relative path, and the VM links this computer's
+ * home there, so a path the history names (/Users/alex/Downloads/handoff.md) opens in the cloud as it did here.
+ * Credential stores and keys are never carried; files past the bounds stay on this computer and are listed.
+ */
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+export const VM_HOME = '/home/user';
+const MAX_FILES = 64, FILE_BYTES = 16 << 20, TOTAL_BYTES = 64 << 20;
+/** A handed file is read for the paths it names when it is text of at most this size. */
+const NAMES_BYTES = 1 << 20;
+/** Claude Code tools whose input names a file the session opened. */
+const FILE_TOOLS = new Set(['Read', 'Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+/** Home-relative stores of keys and sign-ins: never carried, whatever the session read. */
+const PRIVATE = ['.ssh', '.aws', '.gnupg', '.password-store', '.azure', '.kube', '.docker', '.netrc', '.npmrc', '.pypirc',
+    '.git-credentials', '.config/gh', '.config/gcloud', '.config/shardflux', '.claude/.credentials.json', '.claude.json',
+    '.codex/auth.json', 'Library/Keychains', 'Library/Cookies'];
+const PRIVATE_NAME = /^(\.env(\..*)?|id_[a-z0-9]+(\.pub)?|.*\.(pem|key|p12|pfx|keychain-db))$/i;
+/** Absolute and home paths in free text: `@"/a b/c.md"`, `/x/y.md`, `~/notes.md`. */
+export function pathsIn(text) {
+    const out = new Set();
+    for (const m of text.matchAll(/["'`](~?\/[^"'`\n]+)["'`]|(?:^|[\s(@[])(~?\/[^\s"'`()<>[\]]+)/g))
+        out.add(m[1] ?? m[2].replace(/[.,;:!?]+$/, ''));
+    return [...out];
+}
+/** What the transcript says the session was handed and opened, as spelled there (a `~/` path is not expanded yet). */
+export function sessionMentions(bytes, harness) {
+    const handed = new Set(), opened = new Set();
+    for (const line of bytes.toString('utf8').split('\n')) {
+        let r;
+        try {
+            r = obj(JSON.parse(line));
+        }
+        catch {
+            continue;
+        }
+        if (harness === 'claude') {
+            const attachment = obj(r.attachment);
+            if (r.type === 'attachment' && attachment.type === 'file' && typeof attachment.filename === 'string')
+                handed.add(attachment.filename);
+            const message = obj(r.message);
+            if (r.type === 'user' && r.isMeta !== true && typeof message.content === 'string')
+                for (const p of pathsIn(message.content))
+                    handed.add(p);
+            if (r.type === 'assistant' && Array.isArray(message.content)) {
+                for (const block of message.content.map(obj)) {
+                    if (block.type !== 'tool_use' || !FILE_TOOLS.has(String(block.name)))
+                        continue;
+                    const input = obj(block.input), path = input.file_path ?? input.notebook_path;
+                    if (typeof path === 'string')
+                        opened.add(path);
+                }
+            }
+        }
+        else {
+            const p = obj(r.payload);
+            if (r.type !== 'response_item' || p.type !== 'message' || p.role !== 'user' || !Array.isArray(p.content))
+                continue;
+            // Codex's own context blocks (<environment_context>, <turn_aborted>) are user-role records the user never typed.
+            for (const item of p.content.map(obj))
+                if (item.type === 'input_text' && typeof item.text === 'string' && !item.text.startsWith('<'))
+                    for (const q of pathsIn(item.text))
+                        handed.add(q);
+        }
+    }
+    return { handed: [...handed], opened: [...opened] };
+}
+const inside = (root, path) => path === root || path.startsWith(root.endsWith('/') ? root : `${root}/`);
+const realOr = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return resolve(path);
+} };
+function isPrivate(home, path) {
+    const rel = relative(home, path);
+    return PRIVATE.some(p => rel === p || rel.startsWith(`${p}/`)) || rel.split('/').some(part => PRIVATE_NAME.test(part));
+}
+function isText(bytes) { return !bytes.subarray(0, 8192).includes(0); }
+/**
+ * The files to carry: regular files under `home`, outside every root (the moved checkout and the repository's other
+ * worktrees), not private, within the bounds. Handed files come first, then opened ones, then the ones a handed file
+ * names; `left` lists the ones past the bounds.
+ */
+export function sessionFiles(bytes, harness, home, roots) {
+    const realHome = realOr(home), realRoots = roots.map(realOr);
+    const expand = (p) => (p === '~' || p.startsWith('~/') ? home + p.slice(1) : p);
+    const files = [], left = [], seen = new Set();
+    let total = 0;
+    const consider = (spelled, why) => {
+        const path = resolve(expand(spelled));
+        if (!isAbsolute(expand(spelled)) || seen.has(path))
+            return undefined;
+        seen.add(path);
+        const real = realOr(path);
+        if (!inside(home, path) || !inside(realHome, real) || realRoots.some(root => inside(root, real)) || isPrivate(home, path) || isPrivate(realHome, real))
+            return undefined;
+        let st;
+        try {
+            st = statSync(real);
+        }
+        catch {
+            return undefined;
+        }
+        if (!st.isFile())
+            return undefined;
+        if (files.length >= MAX_FILES || st.size > FILE_BYTES || total + st.size > TOTAL_BYTES) {
+            left.push(path);
+            return undefined;
+        }
+        total += st.size;
+        const f = { path, bytes: st.size, mode: st.mode & 0o777, why };
+        files.push(f);
+        return f;
+    };
+    const { handed, opened } = sessionMentions(bytes, harness);
+    const given = handed.map(p => consider(p, 'handed')).filter((f) => !!f);
+    for (const p of opened)
+        consider(p, 'opened');
+    for (const f of given) {
+        if (f.bytes > NAMES_BYTES)
+            continue;
+        let text;
+        try {
+            text = readFileSync(f.path);
+        }
+        catch {
+            continue;
+        }
+        if (isText(text))
+            for (const p of pathsIn(text.toString('utf8')))
+                consider(p, 'named');
+    }
+    return { files, left };
+}
+/** Where a carried file goes in the VM. */
+export const vmPath = (home, path) => `${VM_HOME}/${relative(home, path)}`;
+/** `~/Downloads/handoff.md` for display. */
+export const homeSpelling = (home, path) => (inside(home, path) ? `~/${relative(home, path)}` : path);
+export async function writeChunks(cell, path, bytes, mode = '0600') {
+    if (!bytes.length) {
+        await cell.files.write(path, '', { mode });
+        return;
+    }
+    for (let at = 0; at < bytes.length; at += SYNC_CHUNK_BYTES)
+        await cell.files.write(path, bytes.subarray(at, at + SYNC_CHUNK_BYTES), { mode, append: at > 0 });
+}
+/**
+ * Writes each file under the VM's home, then links this computer's home path to the VM's home when it is free there
+ * (`/Users/alex` → `/home/user`), so absolute paths in the history resolve. A VM without sudo keeps the home-relative
+ * copies; the link is a convenience, never a reason to fail the move.
+ */
+export async function placeSessionFiles(cell, found, home, signal) {
+    for (const f of found.files) {
+        const target = vmPath(home, f.path);
+        await cell.files.mkdir(dirname(target), { parents: true });
+        await writeChunks(cell, target, readFileSync(f.path), `0${f.mode.toString(8)}`);
+    }
+    if (!found.files.length || home === VM_HOME)
+        return false;
+    const linked = await cell.exec.run(['sh', '-c', 'test -e "$1" || { sudo -n mkdir -p "$(dirname "$1")" && sudo -n ln -s "$2" "$1"; }', 'sh', home, VM_HOME], { timeoutMs: 10_000, ...(signal ? { signal } : {}) }).catch(() => null);
+    return linked?.exitCode === 0;
+}

package/dist/move.js

@@ -15,6 +15,7 @@
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { ShardfluxApiError } from '@shardflux/sdk';
@@ -31,13 +32,12 @@ import { conversationTerminal } from "./conversation-terminal.js";
 import { openInChoices } from "./t3-mode.js";
 import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
 import { openUrl } from "./browser.js";
-import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
 import { completeRecords, continuedAfter, findLocalSession, homeRelativeTranscript, listLocalSessions, readTranscript, recordCwd, rewriteSessionPaths, sessionState } from "./local-sessions.js";
 import { installDivergenceNotice, movedKey, movedSession, movedSessions, rememberMoved } from "./moved-sessions.js";
 import { captureWorktreeMigration, inspectWorktreeMigration, migrationScope, preserveWorktreeMigration, referencedWorktrees, rewriteWorktreeTranscript } from "./move-worktrees.js";
 import { interruptLocalTurn, MOVE_CONTINUATION, stopsLocalTurn } from "./move-interrupt.js";
 import { seedPhase } from "./seed-phases.js";
-const VM_HOME = '/home/user';
+import { homeSpelling, placeSessionFiles, sessionFiles, VM_HOME, writeChunks } from "./move-files.js";
 const SPACE = '/shardflux/project';
 /** A transcript above this moves with the repository's history bound. */
 const TRANSCRIPT_LIMIT = 256 << 20;
@@ -86,14 +86,6 @@ export async function waitForTurnEnd(ctx, s, env, pollMs = 1000) {
         await delay(pollMs, undefined, { signal: ctx.signal });
     }
 }
-async function writeChunks(cell, path, bytes) {
-    if (!bytes.length) {
-        await cell.files.write(path, '', { mode: '0600' });
-        return;
-    }
-    for (let at = 0; at < bytes.length; at += SYNC_CHUNK_BYTES)
-        await cell.files.write(path, bytes.subarray(at, at + SYNC_CHUNK_BYTES), { mode: '0600', append: at > 0 });
-}
 /**
  * The session's transcript in the conversation's VM: at its native path (where the harness resumes it) and, when the
  * project space is mounted, as the conversation's durable copy with the same checkpoint metadata the guest writes
@@ -252,6 +244,13 @@ export async function moveSession(ctx, values) {
         if (elsewhere.length && !ctx.json)
             ctx.io.stderr.write(`This session also worked in ${elsewhere.length === 1 ? 'another worktree' : `${elsewhere.length} other worktrees`} of this repository (${elsewhere.join(', ')}); ${elsewhere.length === 1 ? 'it stays' : 'they stay'} on this computer. shard move --preserve-all-worktrees copies every worktree.\n`);
     }
+    // Files it used outside the project (an @-mentioned ~/Downloads/handoff.md) go along at the same paths (0.25.0+).
+    const home = env.HOME || homedir();
+    const files = sessionFiles(bytes, s.harness, home, [folder, ...(plan?.trees.map(t => t.source) ?? []), ...elsewhere]);
+    if (!ctx.json && files.files.length)
+        ctx.io.stderr.write(`Bringing ${files.files.length === 1 ? 'a file' : `${files.files.length} files`} it used outside the project: ${files.files.map(f => homeSpelling(home, f.path)).join(', ')}\n`);
+    if (!ctx.json && files.left.length)
+        ctx.io.stderr.write(`Staying on this computer (past the move’s 64 files, 64 MiB): ${files.left.map(p => homeSpelling(home, p)).join(', ')}\n`);
     const sha256 = createHash('sha256').update(bytes).digest('hex');
     if (!ctx.json)
         ctx.io.stderr.write(`Moving ${s.harness === 'claude' ? 'Claude Code' : 'Codex'} session “${s.title}” to the cloud…\n`);
@@ -270,6 +269,7 @@ export async function moveSession(ctx, values) {
             // The workspace's cell handle is shared with the seed that follows: it stays open.
             beforeSeed: async (ws, c) => {
                 placed = await placeTranscript(ws.cell(), c, s, bytes, folder, ctx.signal, values['preserve-all-worktrees'] === true && plan ? plan : undefined);
+                await placeSessionFiles(ws.cell(), files, home, ctx.signal);
             },
         });
     }
@@ -303,7 +303,8 @@ export async function moveSession(ctx, values) {
     if (!attach) {
         const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
         await conversationTerminal(quiet, ws, c, place, { ...terminalValues, detach: true });
-        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}), ...(elsewhere.length ? { other_worktrees: elsewhere } : {}) });
+        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}), ...(elsewhere.length ? { other_worktrees: elsewhere } : {}),
+            ...(files.files.length ? { files: files.files.map(f => f.path) } : {}), ...(files.left.length ? { files_left: files.left } : {}) });
         return 0;
     }
     const where = openInChoices(ctx, project.slug)[s.harness];

package/dist/onboarding.d.ts

@@ -22,6 +22,7 @@ type CredentialRow = {
     app: string;
     status?: string;
     scope?: string;
+    fingerprint?: string | null;
     access?: {
         verdict: 'usable' | 'refused' | 'unknown';
         checked_at: string;
@@ -75,8 +76,11 @@ export interface T3SignInRow {
 export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform, startSignIn?: boolean, scope?: Values): Promise<Connection | null>;
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export declare function claudeConnection(row: CredentialRow | undefined): Omit<Connection, 'id' | 'picked' | 'found'>;
-/** Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected. */
-export declare function codexConnection(local: boolean, synced: boolean, connector: CodexConnectorView | null, health: CodexHealth): Omit<Connection, 'id' | 'picked' | 'found'>;
+/**
+ * Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected.
+ * `renewed`: this computer has a Codex login other than the one in the cloud (a new sign-in not copied yet).
+ */
+export declare function codexConnection(local: boolean, synced: boolean, connector: CodexConnectorView | null, health: CodexHealth, renewed?: boolean): Omit<Connection, 'id' | 'picked' | 'found'>;
 /**
  * The onboarding report, for an agent setting itself up from chat and for the menu bar app. It verifies every
  * connection live: the Shardflux account, Claude (Claude itself accepts the login) and Codex (the login is copied and
@@ -107,7 +111,7 @@ export declare function onboardingReport(ctx: Ctx, values: Values, platform?: No
         };
         conversation: {
             id: string;
-            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
             summary: string;
         } | null;
         commands: never[];
@@ -138,7 +142,7 @@ export declare function onboardingReport(ctx: Ctx, values: Values, platform?: No
         };
         conversation: {
             id: string;
-            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
             summary: string;
         } | null;
         commands: string[];
@@ -191,7 +195,7 @@ export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
     };
     conversation: {
         id: string;
-        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
         summary: string;
     } | null;
     commands: never[];
@@ -222,7 +226,7 @@ export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
     };
     conversation: {
         id: string;
-        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
         summary: string;
     } | null;
     commands: string[];