@shardflux/cli 0.24.0 → 0.24.1

package/dist/device-helper.js

@@ -1,5 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { DeviceExecutor, askConnectedAcp } from "./device-bridge.js";
+import { DeviceExecutor, askConnectedAcp, askDeviceApprover } from "./device-bridge.js";
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { allOrgs, allProjects } from "./account-scope.js";
 import { ConversationMirrorState, mirrorProjectConversations } from "./conversation-stash.js";
 import { FilesMirrorState, mirrorFilesOnce } from "./files-mirror.js";
 import { withTargetLock } from "./target-lock.js";
@@ -44,6 +46,10 @@ export async function runDeviceHelper(ctx, options = {}) {
         const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
         if (acp)
             return acp;
+        // The desktop app, while it runs, shows it as a Needs-you item (0.25.0+); else the menu bar or the service files.
+        const app = await askDeviceApprover(ctx.store.dir, approval, signal);
+        if (app)
+            return app;
         if (options.service)
             return askLocalDeviceApproval(ctx, approval);
         return new Promise(resolve => {
@@ -141,22 +147,60 @@ export async function runDeviceHelper(ctx, options = {}) {
                     await delay(wait, undefined, { signal }).catch(() => undefined);
                 }
             })();
+            // Registered for every project an agent may ask from (deviceProjects); one poll covers them all where the API
+            // lists by device (0.25.0+), else one per project.
+            const registered = new Map();
+            let all, deviceWide = true;
+            const take = (rows) => {
+                for (const r of rows) {
+                    if (r.device_id !== deviceId || working.has(r.id) || working.size >= 8)
+                        continue;
+                    const work = executor.execute(r).catch(report).finally(() => working.delete(r.id));
+                    working.set(r.id, work);
+                }
+            };
             while (!signal.aborted) {
                 try {
-                    for (const projectId of new Set(Object.values(localConversations(ctx)).map(r => r.project_id))) {
-                        await conversationClient(ctx).deviceRequests.heartbeat({ projectId, deviceId, leaseSeconds: 30 });
-                        let cursor;
-                        do {
-                            const page = await conversationClient(ctx).deviceRequests.list({ projectId, state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
-                            for (const r of page.data) {
-                                if (r.device_id !== deviceId || working.has(r.id) || working.size >= 8)
-                                    continue;
-                                const work = executor.execute(r).catch(report).finally(() => working.delete(r.id));
-                                working.set(r.id, work);
-                            }
-                            cursor = page.nextCursor ?? undefined;
-                        } while (cursor && !signal.aborted);
+                    if (!all || Date.now() - all.at > 300_000)
+                        all = { ids: await deviceProjects(ctx).catch(() => all?.ids ?? []), at: Date.now() };
+                    const projects = [...new Set([...Object.values(localConversations(ctx)).map(r => r.project_id), ...all.ids])];
+                    for (const projectId of projects) {
+                        if (Date.now() - (registered.get(projectId) ?? 0) < 10_000)
+                            continue;
+                        await conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 }).then(() => registered.set(projectId, Date.now()), (e) => {
+                            // A project this sign-in no longer reaches is skipped until the next listing, never the others.
+                            if (!(e instanceof ShardfluxApiError && [403, 404].includes(e.status)))
+                                throw e;
+                            registered.set(projectId, Date.now() + 290_000);
+                        });
+                    }
+                    let polled = false;
+                    if (deviceWide && registered.size) {
+                        try {
+                            let cursor;
+                            do {
+                                const page = await conversationClient(ctx).deviceRequests.list({ deviceId, state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
+                                take(page.data);
+                                cursor = page.nextCursor ?? undefined;
+                            } while (cursor && !signal.aborted);
+                            polled = true;
+                        }
+                        catch (e) {
+                            if (e instanceof ShardfluxApiError && [400, 422].includes(e.status))
+                                deviceWide = false;
+                            else
+                                throw e;
+                        }
                     }
+                    if (!polled)
+                        for (const projectId of projects) {
+                            let cursor;
+                            do {
+                                const page = await conversationClient(ctx).deviceRequests.list({ ...(projectId ? { projectId } : {}), state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
+                                take(page.data);
+                                cursor = page.nextCursor ?? undefined;
+                            } while (cursor && !signal.aborted);
+                        }
                     await executor.reap();
                 }
                 catch (e) {
@@ -185,3 +229,32 @@ export async function runDeviceHelper(ctx, options = {}) {
         await input.catch(() => undefined);
     }
 }
+/**
+ * The projects this device answers for besides its local conversations' (0.25.0+): the signed-in project (the API
+ * key's, or the default one), and with a person's own sign-in and no key, every project they can reach (at most 100).
+ * A home conversation, an Orchestrator master or a chat the desktop app started asks from these.
+ */
+export async function deviceProjects(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl), ids = new Set();
+    if (profile.project_id)
+        ids.add(profile.project_id);
+    if (profile.api_key?.project_id)
+        ids.add(profile.api_key.project_id);
+    const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || profile.api_key !== undefined;
+    const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || profile.session !== undefined;
+    if (key && !ids.size)
+        ids.add(''); // the key's own project: the API takes it from the key
+    if (!key && session) {
+        const account = ctx.account();
+        for (const org of await allOrgs(account)) {
+            for (const p of await allProjects(account, org.id)) {
+                ids.add(p.id);
+                if (ids.size >= 100)
+                    break;
+            }
+            if (ids.size >= 100)
+                break;
+        }
+    }
+    return [...ids];
+}

package/dist/drive-commands.d.ts

@@ -0,0 +1,25 @@
+import type { DriveFile, ModelTemplate, Shardflux, ShardfluxAccount } from '@shardflux/sdk';
+import type { Values } from './args.js';
+import type { Ctx, Handler } from './commands.js';
+/** A project API key is in use: SHARDFLUX_API_KEY, else the key `shard setup` saved for this API URL. */
+export declare const hasApiKey: (ctx: Ctx) => boolean;
+export interface ProjectScope {
+    client: Shardflux | ShardfluxAccount;
+    /** Undefined only when `needId` was false and the API key's own project is meant. */
+    projectId: string | undefined;
+}
+/**
+ * Who acts and in which project. `--project` acts as the signed-in person when there is a sign-in (their projects,
+ * by id or slug), else with the API key. Without it: the API key's own project, else the person's default project.
+ * `needId` false leaves the key's project unnamed (the API defaults to it), saving a lookup.
+ */
+export declare function projectScope(ctx: Ctx, values: Values, needId?: boolean): Promise<ProjectScope>;
+/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+export declare function driveTable(rows: readonly DriveFile[]): string;
+/**
+ * The model template as people read it: the primary provider and why, the connected accounts, then one row per role
+ * with what it runs and, for a role whose provider is out of usage, until when it waits and what the other provider
+ * would run instead.
+ */
+export declare function modelTemplateText(t: ModelTemplate): string;
+export declare const DRIVE_HANDLERS: Record<string, Handler>;

package/dist/drive-commands.js

@@ -0,0 +1,201 @@
+/**
+ * The project drive and the model template (0.25.0+): `shard drive ls|get|put|rm` and `shard models`,
+ * `shard models primary`. Both act in one project: the API key's own, or `--project`; a person signed in without a
+ * key acts in their default project (`shard projects use`), or the only one there is.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { encodeDrivePath } from '@shardflux/sdk';
+import { UUID } from "./args.js";
+import { resolveOrg, resolveProject } from "./account-scope.js";
+import { out, principal, readInput, str } from "./commands.js";
+import { AuthConfigError, UsageError } from "./errors.js";
+import { humanBytes } from "./files-mirror.js";
+import { json, table, time } from "./format.js";
+/** A drive file of up to 5 GiB is read into memory to send it with its SHA-256. */
+const MAX_PUT_BYTES = 5 * 1024 ** 3;
+const SHA256 = /^[0-9a-f]{64}$/i;
+/** A project API key is in use: SHARDFLUX_API_KEY, else the key `shard setup` saved for this API URL. */
+export const hasApiKey = (ctx) => Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+/**
+ * Who acts and in which project. `--project` acts as the signed-in person when there is a sign-in (their projects,
+ * by id or slug), else with the API key. Without it: the API key's own project, else the person's default project.
+ * `needId` false leaves the key's project unnamed (the API defaults to it), saving a lookup.
+ */
+export async function projectScope(ctx, values, needId = true) {
+    const given = str(values.project);
+    const signedIn = ctx.sessionSource() !== null;
+    if (signedIn && (given !== undefined || !hasApiKey(ctx))) {
+        const account = ctx.account();
+        return { client: account, projectId: (await resolveProject(ctx, account, values)).id };
+    }
+    const cloud = ctx.cloud();
+    if (given !== undefined) {
+        if (!UUID.test(given))
+            throw new UsageError(`--project with an API key takes the project id (got "${given}").`, 'or sign in to name projects by slug: shard auth login');
+        return { client: cloud, projectId: given };
+    }
+    if (!needId)
+        return { client: cloud, projectId: undefined };
+    return { client: cloud, projectId: ctx.apiKey().saved?.project_id ?? (await principal(ctx)).project_id };
+}
+/** A drive path checked as the SDK sends it: relative, no empty, `.` or `..` segments (exit 2 before any request). */
+function drivePath(path, what = 'drive path') {
+    try {
+        encodeDrivePath(path);
+    }
+    catch (err) {
+        if (err instanceof TypeError)
+            throw new UsageError(`${what}: ${err.message}`);
+        throw err;
+    }
+    return path;
+}
+/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+export function driveTable(rows) {
+    return table(['SIZE', 'SAVED', 'TYPE', 'PATH'], rows.map((f) => [humanBytes(f.size), time(f.created_at), f.content_type, f.path]));
+}
+const SOURCES = {
+    marked: 'the organization’s choice',
+    project: 'this project’s choice',
+    first_connected: 'connected first',
+};
+const ROLE_ORDER = ['master', 'builder', 'hard', 'light', 'reviewer'];
+const providerName = (p) => (p === 'claude' ? 'Claude' : 'Codex');
+/**
+ * The model template as people read it: the primary provider and why, the connected accounts, then one row per role
+ * with what it runs and, for a role whose provider is out of usage, until when it waits and what the other provider
+ * would run instead.
+ */
+export function modelTemplateText(t) {
+    const lines = [];
+    if (t.primary === null)
+        lines.push('Connect Claude or Codex to run tasks: shard agents accounts add claude (or codex).');
+    else
+        lines.push(`Primary: ${t.primary} (${t.primary_source ? SOURCES[t.primary_source] : 'connected first'})${t.secondary ? `, secondary: ${t.secondary}` : ''}`);
+    if (t.connected.length)
+        lines.push(`Connected: ${t.connected.map((c) => `${c.provider}${c.plan_type ? ` (${c.plan_type})` : ''}`).join(', ')}`);
+    if (t.task_harness !== null || t.attempt > 0)
+        lines.push(`Task: ${[t.task_harness ? `on ${t.task_harness}` : '', t.attempt > 0 ? `retry ${t.attempt}` : ''].filter(Boolean).join(', ')}`);
+    const rows = ROLE_ORDER.map((role) => {
+        const r = t.roles[role];
+        const effort = `${r.effort ?? 'default'}${r.planning_effort ? ` (plans ${r.planning_effort})` : ''}`;
+        const wait = r.wait ? `${time(r.wait.until)}${r.wait.alternative ? `, or now: ${r.wait.alternative.label}` : ''}` : '-';
+        return [role, r.harness, r.model, effort, wait];
+    });
+    return `${lines.join('\n')}\n\n${table(['ROLE', 'HARNESS', 'MODEL', 'EFFORT', 'WAITS UNTIL'], rows)}`;
+}
+function harnessOf(values) {
+    const h = str(values.harness);
+    if (h !== undefined && h !== 'claude' && h !== 'codex')
+        throw new UsageError(`--harness must be claude or codex (got "${h}").`);
+    return h;
+}
+function attemptOf(values) {
+    const a = str(values.attempt);
+    if (a === undefined)
+        return undefined;
+    if (!/^\d+$/.test(a) || Number(a) > 10)
+        throw new UsageError(`--attempt must be 0 for a first run, or 1 to 10 for a retry (got "${a}").`);
+    return Number(a);
+}
+export const DRIVE_HANDLERS = {
+    async 'drive ls'(ctx, values, [prefix]) {
+        const { client, projectId } = await projectScope(ctx, values);
+        const limitText = str(values.limit);
+        const limit = limitText === undefined ? undefined : Number(limitText);
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 1000))
+            throw new UsageError('--limit must be 1 to 1000.');
+        const rows = [];
+        const seen = new Set();
+        let cursor = str(values.cursor), next;
+        do {
+            const page = await client.drive.list(projectId, { ...(prefix ? { prefix } : {}), ...(limit ? { limit } : values.all === true ? { limit: 1000 } : {}), ...(cursor ? { cursor } : {}), signal: ctx.signal });
+            rows.push(...page.data);
+            next = page.nextCursor;
+            cursor = next ?? undefined;
+            if (values.all === true && cursor) {
+                if (seen.has(cursor))
+                    throw new UsageError('The drive listing repeated its cursor. Try again.');
+                seen.add(cursor);
+            }
+        } while (values.all === true && cursor);
+        out(ctx, rows.length ? driveTable(rows) : 'No files.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard drive ls${prefix ? ` ${prefix}` : ''} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'drive get'(ctx, values, [path]) {
+        drivePath(path);
+        const sha256 = str(values.sha256)?.toLowerCase();
+        if (sha256 !== undefined && !SHA256.test(sha256))
+            throw new UsageError('--sha256 takes the 64 hex characters of a version’s SHA-256 (shard drive ls --json shows them).');
+        const { client, projectId } = await projectScope(ctx, values);
+        const file = await client.drive.read(projectId, path, { ...(sha256 ? { sha256 } : {}), signal: ctx.signal });
+        const dest = str(values.out);
+        const meta = { path, sha256: file.sha256, size: file.size, content_type: file.contentType };
+        if (dest !== undefined) {
+            await writeFile(dest, file.bytes);
+            out(ctx, `Wrote ${path} to ${dest} (${humanBytes(file.size)}, sha256 ${file.sha256})\n`, { ...meta, out: dest });
+        }
+        else if (ctx.json) {
+            ctx.io.stdout.write(json({ ...meta, content_base64: Buffer.from(file.bytes).toString('base64') }));
+        }
+        else {
+            ctx.io.stdout.write(file.bytes);
+        }
+        return 0;
+    },
+    async 'drive put'(ctx, values, [local, target]) {
+        if (local === '-' && target === undefined)
+            throw new UsageError('Name the drive path when the file comes from standard input: shard drive put - <drive-path>');
+        const path = drivePath(target ?? basename(local), target === undefined ? `the file name "${basename(local)}"` : 'drive path');
+        const bytes = local === '-' ? await readInput(ctx, '-', MAX_PUT_BYTES, 'standard input') : await readFile(local).catch((e) => {
+            throw new UsageError(`cannot read "${local}" (${e.code === 'EISDIR' ? 'a folder; put its files one by one' : e.code ?? e.message})`);
+        });
+        const contentType = str(values['content-type']);
+        const { client, projectId } = await projectScope(ctx, values);
+        const file = await client.drive.save(projectId, path, bytes, { ...(contentType ? { contentType } : {}), signal: ctx.signal });
+        out(ctx, `Saved ${file.path} (${humanBytes(file.size)}, ${file.content_type})\nsha256 ${file.sha256}\n`, { file });
+        return 0;
+    },
+    async 'drive rm'(ctx, values, [path]) {
+        drivePath(path);
+        const { client, projectId } = await projectScope(ctx, values);
+        await client.drive.remove(projectId, path, { signal: ctx.signal });
+        out(ctx, `Removed ${path}\n`, { path, removed: true });
+        return 0;
+    },
+    async models(ctx, values) {
+        const harness = harnessOf(values), attempt = attemptOf(values);
+        const { client, projectId } = await projectScope(ctx, values, false);
+        const t = await client.modelTemplate.get({ ...(projectId ? { projectId } : {}), ...(harness ? { harness } : {}), ...(attempt !== undefined ? { attempt } : {}), signal: ctx.signal });
+        out(ctx, modelTemplateText(t), t);
+        return 0;
+    },
+    async 'models primary'(ctx, values, [choice]) {
+        const word = choice.toLowerCase();
+        if (!['claude', 'codex', 'clear'].includes(word))
+            throw new UsageError(`Choose claude, codex or clear (got "${choice}").`);
+        const provider = word === 'clear' ? null : word;
+        if (str(values.org) !== undefined && str(values.project) !== undefined)
+            throw new UsageError('Choose --org (the organization’s default) or --project (one project).');
+        let t, whose;
+        if (str(values.org) !== undefined) {
+            if (ctx.sessionSource() === null)
+                throw new AuthConfigError('The organization’s default is set by its owners and admins, signed in.', 'sign in: shard auth login (an API key sets its own project’s: shard models primary <claude|codex> without --org)');
+            const account = ctx.account();
+            const org = await resolveOrg(ctx, account, values);
+            t = await account.modelTemplate.setPrimary({ provider, organizationId: org.id, signal: ctx.signal });
+            whose = `${org.name}’s`;
+        }
+        else {
+            const { client, projectId } = await projectScope(ctx, values);
+            t = await client.modelTemplate.setPrimary({ provider, projectId: projectId, signal: ctx.signal });
+            whose = 'this project’s';
+        }
+        // The template that follows shows the primary now in effect and where it comes from.
+        out(ctx, `${provider ? `${providerName(provider)} is ${whose} primary.` : `Cleared ${whose} primary.`}\n${modelTemplateText(t)}`, t);
+        return 0;
+    },
+};

package/dist/handlers.js

@@ -1,6 +1,10 @@
 import { DEVICE_HANDLERS } from "./device-approvals.js";
+import { PROJECT_LINK_HANDLERS } from "./device-folders.js";
 import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
 import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
+import { BOARD_HANDLERS } from "./board-commands.js";
+import { TRANSCRIPT_HANDLERS } from "./conversation-transcript.js";
+import { ROUTER_HANDLERS } from "./router-commands.js";
 /**
  * Every command's handler, keyed by its path ("workspaces open", "auth login"): the project-key commands of
  * commands.ts and the account plane of account-commands.ts (0.5.0). args.test.ts checks that it matches COMMANDS.
@@ -26,4 +30,5 @@ import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
 import { MACHINE_SETUP_HANDLERS } from "./machine-setup.js";
 import { SETTINGS_HANDLERS } from "./client-settings.js";
 import { PROJECT_PREPARATION_HANDLERS } from "./project-preparation.js";
-export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS };
+import { DRIVE_HANDLERS } from "./drive-commands.js";
+export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...DRIVE_HANDLERS };

package/dist/main.js

@@ -371,6 +371,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;
+}