@shardflux/cli 0.23.1 → 0.24.1

package/dist/conversations.d.ts

@@ -39,6 +39,9 @@ export interface Conversation {
     base_branch?: string | null;
     role?: string;
     join_mode?: string | null;
+    /** A conversation on the machine's home, without a repository (0.25.0+, APIs that return it): its `repo_remote`,
+     * `branch` and `base_commit` are empty and its agent runs in `/home/user`. */
+    home?: boolean;
     /** The model and effort its harness starts with; null is the agent's own default (0.17.0+, APIs that keep them). */
     model?: string | null;
     effort?: string | null;
@@ -118,8 +121,8 @@ export declare function resolveConversation(ctx: Ctx, ref: string, folder?: stri
 /** Re-resolve the binding on every attach: a move changes the VM, never the conversation identity. */
 export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promise<Workspace>;
 /**
- * A thread on an existing computer (a join) is prepared by that computer's guest: its worktree, then its harness. Waits
- * until the guest confirms it (the conversation no longer carries restore instructions), within the wake timeout.
+ * A start its guest prepares (GUEST_PREPARED): its worktree, then its harness. Waits until the guest confirms it (the
+ * conversation no longer carries those restore instructions), within the wake timeout.
  */
 export declare function waitThreadReady(ctx: Ctx, c: Conversation, pollMs?: number): Promise<Conversation>;
 export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;

package/dist/conversations.js

@@ -24,7 +24,8 @@ import { recordSetupIntent } from "./project-template-setup.js";
 export const conversationEnded = (c) => !!c.ended_at || c.state === 'archived' || c.landed?.how === 'discarded' || (c.route === 'codex-cloud' && c.state === 'done');
 export const conversationName = (c) => {
     const name = c.key.split('/').at(-1);
-    if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== `shard/${name}`)
+    // A home conversation has no repository, so no branch.
+    if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== (c.home === true ? '' : `shard/${name}`))
         throw new Error('Conversation returned an invalid branch or name');
     return name;
 };
@@ -60,7 +61,8 @@ export async function conversationPtyId(cell, c, signal) {
     return typeof recorded === 'string' && MANAGED_PTY.test(recorded) && recorded.endsWith(`-${c.harness}`) ? recorded : derived;
 }
 export function validateConversation(c) {
-    if (!c || !/^conv_[a-z0-9]{26}$/.test(c.id) || !c.project_id || !c.workspace_id || !c.worktree_path?.startsWith('/home/user/') || /[\0\r\n]/.test(c.worktree_path) || !['claude', 'codex'].includes(c.harness))
+    const worktree = c?.home === true ? c.worktree_path === '/home/user' : c?.worktree_path?.startsWith('/home/user/');
+    if (!c || !/^conv_[a-z0-9]{26}$/.test(c.id) || !c.project_id || !c.workspace_id || !worktree || /[\0\r\n]/.test(c.worktree_path) || !['claude', 'codex'].includes(c.harness))
         throw new Error('Conversation response omitted its identity or binding');
     conversationName(c);
     return c;
@@ -156,14 +158,19 @@ export async function conversationWorkspace(ctx, c) {
     return ws;
 }
 /**
- * A thread on an existing computer (a join) is prepared by that computer's guest: its worktree, then its harness. Waits
- * until the guest confirms it (the conversation no longer carries restore instructions), within the wake timeout.
+ * Starts its computer's guest prepares by itself, never this command: a thread on an existing computer (a join), a
+ * conversation started from the project hub (0.25.0+) and one on the machine's home (0.25.0+).
+ */
+const GUEST_PREPARED = new Set(['join', 'hub', 'home']);
+/**
+ * A start its guest prepares (GUEST_PREPARED): its worktree, then its harness. Waits until the guest confirms it (the
+ * conversation no longer carries those restore instructions), within the wake timeout.
  */
 export async function waitThreadReady(ctx, c, pollMs = 1000) {
     const deadline = Date.now() + ctx.wakeTimeoutMs;
     for (;;) {
         const current = await getConversation(ctx, c.id);
-        if (!current.restore || current.restore.kind !== 'join')
+        if (!current.restore || !GUEST_PREPARED.has(current.restore.kind))
             return current;
         if (current.state === 'done' || current.state === 'archived' || current.ended_at)
             throw new UsageError('This thread ended before it started.');
@@ -181,7 +188,7 @@ export async function restoreConversationBinding(ctx, c, ws) {
     if (!c.restore || c.restore.kind === 'new')
         return;
     // Threads on an existing computer (0.16.0+): its guest prepares them, never this command.
-    if (c.restore.kind === 'join') {
+    if (GUEST_PREPARED.has(c.restore.kind)) {
         await waitThreadReady(ctx, c);
         return;
     }
@@ -192,10 +199,13 @@ export async function restoreConversationBinding(ctx, c, ws) {
             throw new Error(`Reviewer restore failed: ${review.stderr.trim()}`);
         return;
     }
-    await cell.files.mkdir(c.worktree_path, { parents: true });
-    const init = await cell.exec.run(['git', '-C', c.worktree_path, 'init'], { timeoutMs: 30_000, signal: ctx.signal });
-    if (init.exitCode !== 0)
-        throw new Error(`Conversation restore could not initialize its repository: ${init.stderr.trim()}`);
+    // A home conversation runs in /home/user without a repository: its guest restores only its transcript.
+    if (c.home !== true && c.restore.home !== true) {
+        await cell.files.mkdir(c.worktree_path, { parents: true });
+        const init = await cell.exec.run(['git', '-C', c.worktree_path, 'init'], { timeoutMs: 30_000, signal: ctx.signal });
+        if (init.exitCode !== 0)
+            throw new Error(`Conversation restore could not initialize its repository: ${init.stderr.trim()}`);
+    }
     const result = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);

package/dist/default-volume-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+export declare function defaultVolumeCommand(ctx: Ctx, values: Values, args: string[], action: 'attach' | 'detach'): Promise<number | undefined>;

package/dist/default-volume-commands.js

@@ -0,0 +1,35 @@
+import { NotFoundError, UsageError } from "./errors.js";
+import { projectIdentity, normalizeRemote } from "./project-identity.js";
+export async function defaultVolumeCommand(ctx, values, args, action) {
+    if (values.machine !== true && values.template !== true) {
+        if (values.path !== undefined)
+            throw new UsageError('--path requires --template');
+        return undefined;
+    }
+    if (values.machine === true && values.template === true)
+        throw new UsageError('Choose --machine or --template');
+    if (args.length !== 1)
+        throw new UsageError(`Use shard volumes ${action} --machine <volume> or --template <volume>`);
+    if (values.machine === true && values.path !== undefined)
+        throw new UsageError('--path requires --template');
+    const cloud = ctx.cloud();
+    const project = values.template === true ? projectIdentity(typeof values.path === 'string' ? values.path : '.') : undefined;
+    const api = project ? cloud.templates.projectVolumes(project.remote ?? normalizeRemote(`file://${project.folder}`)) : cloud.machine.volumes;
+    const options = { signal: ctx.signal };
+    let result;
+    if (action === 'attach') {
+        if (typeof values.mount !== 'string')
+            throw new UsageError('--mount /mnt/data is required');
+        const ref = args[0];
+        result = await api.attach({ ...(/^[a-f0-9-]{36}$/i.test(ref) ? { volumeId: ref } : { name: ref }), mountPath: values.mount, mode: values['read-only'] === true ? 'ro' : 'rw' }, options);
+    }
+    else {
+        const list = await api.list(options), v = list.volumes.find(v => v.volume_id === args[0] || v.name === args[0]);
+        if (!v)
+            throw new NotFoundError(`Default volume ${args[0]} was not found`);
+        result = await api.detach(v.volume_id, options);
+    }
+    ctx.io.stdout.write(ctx.json ? JSON.stringify(result) + '\n' : `${values.template === true ? 'template' : 'machine'}: ${result.volumes.map(v => `${v.name} at ${v.mount_path} (${v.mode})`).join(', ') || 'no default volumes'}\n` +
+        result.live.map(v => `${v.workspace_id}: ${v.status}${v.reason ? ` (${v.reason})` : ''}\n`).join(''));
+    return 0;
+}

package/dist/device-approvals.js

@@ -34,7 +34,8 @@ export function answerDeviceApproval(dir, id, choice) {
     const pending = pendingDeviceApprovals(dir).find(p => p.request_id === id);
     if (!pending)
         throw new UsageError('That request is no longer waiting for approval. Run shard device requests.');
-    if (choice === 'always' && pending.outside)
+    // A folder request's Always is that folder's grant (device-folders.ts); other access outside the conversation folder is once only.
+    if (choice === 'always' && pending.outside && pending.scope !== 'folder')
         throw new UsageError('Access outside the conversation folder must be approved once.');
     writePrivateFile(join(dir, 'device-answers'), paths(dir, id).answer, JSON.stringify({ nonce: pending.nonce, choice }));
 }
@@ -64,12 +65,12 @@ export async function askLocalDeviceApproval(ctx, approval) {
 export const DEVICE_HANDLERS = {
     'device requests'(ctx) {
         const requests = pendingDeviceApprovals(ctx.store.dir);
-        ctx.io.stdout.write(ctx.json ? json({ requests }) : requests.length ? requests.map(r => `${r.request_id}: ${r.summary}\n  Project: ${r.project_name ?? r.project_id}; conversation: ${r.conversation_title ?? r.conversation_id}\n  Local: ${r.local_path ?? '(none)'}; remote: ${r.remote_path ?? '(none)'}${r.argv ? `\n  Command: ${JSON.stringify(r.argv)}` : ''}${r.local_port ? `\n  Ports: ${r.local_port} → ${r.remote_port}` : ''}\n  shard device approve ${r.request_id} | shard device deny ${r.request_id}\n`).join('') : 'No device requests waiting for approval.\n');
+        ctx.io.stdout.write(ctx.json ? json({ requests }) : requests.length ? requests.map(r => `${r.request_id}: ${r.summary}\n  Project: ${r.project_name ?? r.project_id}; conversation: ${r.conversation_title ?? r.conversation_id}\n  Local: ${r.local_path ?? '(none)'}; remote: ${r.remote_path ?? '(none)'}${r.argv ? `\n  Command: ${JSON.stringify(r.argv)}` : ''}${r.local_port ? `\n  Ports: ${r.local_port} → ${r.remote_port}` : ''}${r.repo_remote ? `\n  Repository: ${r.repo_remote}` : ''}${r.brief ? `\n  First message: ${r.brief.split('\n')[0].slice(0, 200)}` : ''}\n  shard device approve ${r.request_id}${r.scope === 'folder' ? ` [--always: for ${r.folder}]` : ''} | shard device deny ${r.request_id}\n`).join('') : 'No device requests waiting for approval.\n');
         return Promise.resolve(0);
     },
     ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, values, [id]) => {
             answerDeviceApproval(ctx.store.dir, id, action === 'approve' ? values.always === true ? 'always' : 'once' : 'deny');
-            ctx.io.stdout.write(ctx.json ? json({ request_id: id, choice: action === 'approve' && values.always ? 'always' : action }) : `Device request ${id}: ${action === 'approve' ? values.always ? 'allowed for project' : 'approved once' : 'denied'}.\n`);
+            ctx.io.stdout.write(ctx.json ? json({ request_id: id, choice: action === 'approve' && values.always ? 'always' : action }) : `Device request ${id}: ${action === 'approve' ? values.always ? 'always allowed' : 'approved once' : 'denied'}.\n`);
             return Promise.resolve(0);
         }])),
 };

package/dist/device-bridge.d.ts

@@ -1,6 +1,7 @@
 import type { CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { Conversation } from './conversations.js';
+import type { DirListing, LinkedProject } from './device-folders.js';
 export type DeviceChoice = 'once' | 'always' | 'deny';
 export interface DeviceRequest {
     id: string;
@@ -8,7 +9,7 @@ export interface DeviceRequest {
     conversation_id: string;
     state: string;
     device_id: string | null;
-    kind: 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally';
+    kind: 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally' | 'dir_list' | 'project_link';
     exec?: {
         argv: string[];
         cwd_relative?: string;
@@ -23,6 +24,17 @@ export interface DeviceRequest {
         remote_port: number;
         local_port: number;
     };
+    dir?: {
+        path: string;
+        depth?: number;
+        max_entries?: number;
+        include_hidden?: boolean;
+    };
+    link?: {
+        path: string;
+        brief?: string;
+        harness?: 'claude' | 'codex';
+    };
 }
 export interface DeviceApproval {
     type: 'approval';
@@ -39,6 +51,17 @@ export interface DeviceApproval {
     conversation_title?: string;
     local_port?: number;
     remote_port?: number;
+    /**
+     * 'folder' (0.25.0+): Always is offered and covers `folder` and everything inside it for this kind (device-folders.ts).
+     * `outside` stays true, so a surface that predates folder grants offers Allow once only.
+     */
+    scope?: 'folder';
+    folder?: string;
+    /** project_link: the repository the folder's Git origin names (null without one) and the first prompt, when one starts. */
+    repo_remote?: string | null;
+    brief?: string;
+    /** dir_list: how many levels below the folder are listed. */
+    depth?: number;
 }
 type Result = {
     state: 'approved' | 'denied' | 'running' | 'done' | 'failed';
@@ -46,6 +69,8 @@ type Result = {
     stdout_b64?: string;
     stderr_b64?: string;
     files_artifact?: string;
+    dir?: DirListing;
+    project?: LinkedProject;
 };
 /** Resolve existing ancestors even before the conversation worktree is created. */
 export declare function devicePath(root: string, requested?: string): {
@@ -61,6 +86,10 @@ export declare class DeviceGrants {
         kinds: string[];
     }>;
     allows(api: string, project: string, root: string, kind: string, outside: boolean): boolean;
+    /** A folder grant (0.25.0+): Always for `root` and everything inside it, for one kind of request. */
+    folderKey(api: string, root: string): string;
+    allowsFolder(api: string, target: string, kind: string): boolean;
+    saveFolder(api: string, root: string, kind: string): Promise<void>;
     save(api: string, project: string, root: string, kind: string): Promise<void>;
 }
 export declare function deviceSummary(r: DeviceRequest, platform?: NodeJS.Platform): string;
@@ -69,6 +98,10 @@ export declare function deviceApproval(r: DeviceRequest, c: Conversation, target
     path: string;
     outside: boolean;
 }, folder: string): DeviceApproval;
+/** A request on a folder anywhere on this device: the folder kinds, and file moves named by an absolute or ~/ path. */
+export declare function folderRequest(r: DeviceRequest): boolean;
+/** What a folder request's approval shows: the canonical path, the folder Always would cover, and what will happen. */
+export declare function folderApproval(r: DeviceRequest, c: Conversation, target: string, folder: string, home: string, remote?: string | null, platform?: NodeJS.Platform): DeviceApproval;
 export declare function tryLocallyAction(r: DeviceRequest): 'start' | 'stop' | null;
 export declare function ensureConversationWorktree(ctx: Ctx, c: Conversation, folder: string, ws?: Workspace): Promise<string>;
 export declare function deviceExec(argv: string[], cwd: string, timeoutSeconds?: number, signal?: AbortSignal): Promise<Result>;
@@ -90,4 +123,12 @@ export declare function serveAcpDeviceApprovals(dir: string, id: string, ask: (a
     stop(): Promise<void>;
 }>;
 export declare function askConnectedAcp(dir: string, approval: DeviceApproval, signal: AbortSignal): Promise<DeviceChoice | null>;
+/**
+ * The desktop app's approval hop (0.25.0+): while it runs it serves `<config dir>/device-approver.sock` (or, when that
+ * path is too long for a socket, `/tmp/sf-device-<uid>/<hash>-approver.sock`) and shows each approval as a Needs-you
+ * item. One line in (the DeviceApproval JSON), one line out (`{"choice":"once|always|deny"}`). No app, a socket that is
+ * not this user's own, or one that closes without an answer: null, and the next surface asks.
+ */
+export declare function approverSocket(dir: string): string;
+export declare function askDeviceApprover(dir: string, approval: DeviceApproval, signal: AbortSignal): Promise<DeviceChoice | null>;
 export {};

package/dist/device-bridge.js

@@ -15,20 +15,16 @@ import { conversationClient } from "./conversation-commands.js";
 import { withTargetLock } from "./target-lock.js";
 import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
 import { yourComputer } from "./this-computer.js";
+import { canonicalDevicePath, deviceHome, displayPath, expandDevicePath, FOLDER_KINDS, isDevicePath, linkLocalProject, listDeviceDir } from "./device-folders.js";
 const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
+/**
+ * A request belongs to its conversation, not to a turn: it is answered while the conversation exists, between turns
+ * (done) and as a turn ends too (0.25.0+); only an archived (or deleted) conversation refuses it.
+ */
+const archived = (c) => c.state === 'archived';
 const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
     throw new Error('Invalid device request identity'); return value; };
-function canonicalDevicePath(target) {
-    let ancestor = target;
-    while (!existsSync(ancestor)) {
-        const parent = dirname(ancestor);
-        if (parent === ancestor)
-            throw new UsageError('Device path is unavailable.');
-        ancestor = parent;
-    }
-    return resolve(realpathSync(ancestor), relative(ancestor, target));
-}
 /** Resolve existing ancestors even before the conversation worktree is created. */
 export function devicePath(root, requested = '.') {
     if (/[\0\r\n]/.test(requested))
@@ -60,6 +56,30 @@ export class DeviceGrants {
         const grant = this.read()[this.key(api, project)];
         return !outside && grant?.root === realpathSync(root) && Array.isArray(grant.kinds) && grant.kinds.includes(kind);
     }
+    /** A folder grant (0.25.0+): Always for `root` and everything inside it, for one kind of request. */
+    folderKey(api, root) { return JSON.stringify(['folder', api, root]); }
+    allowsFolder(api, target, kind) {
+        return Object.entries(this.read()).some(([key, grant]) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(key);
+            }
+            catch {
+                return false;
+            }
+            return Array.isArray(parsed) && parsed.length === 3 && parsed[0] === 'folder' && parsed[1] === api && typeof grant?.root === 'string' && parsed[2] === grant.root
+                && Array.isArray(grant.kinds) && grant.kinds.includes(kind) && inside(grant.root, target);
+        });
+    }
+    async saveFolder(api, root, kind) {
+        if (kind === 'exec')
+            throw new UsageError('Commands never run under a folder grant.');
+        await withTargetLock(join(dirname(this.file), 'device-grants-lock'), () => {
+            const all = this.read(), key = this.folderKey(api, root);
+            all[key] = { root, kinds: [...new Set([...(all[key]?.root === root ? all[key].kinds : []), kind])] };
+            writePrivateFile(dirname(this.file), this.file, JSON.stringify(all) + '\n');
+        });
+    }
     async save(api, project, root, kind) {
         await withTargetLock(join(dirname(this.file), 'device-grants-lock'), () => {
             const all = this.read(), key = this.key(api, project), canonical = realpathSync(root);
@@ -70,6 +90,10 @@ export class DeviceGrants {
 }
 export function deviceSummary(r, platform = process.platform) {
     const yours = yourComputer(platform);
+    if (r.kind === 'dir_list')
+        return `List ${r.dir?.path} on ${yours}: names, sizes and Git remotes, no file contents.`;
+    if (r.kind === 'project_link')
+        return `Make ${r.link?.path} a project and copy its files to the cloud${r.link?.brief ? ', then start a conversation there' : ''}.`;
     if (tryLocallyAction(r))
         return tryLocallyAction(r) === 'stop' ? 'Stop this conversation’s local sync and ports.' : 'Try this conversation in an isolated local worktree with two-way sync and localhost ports.';
     if (r.kind === 'exec')
@@ -88,6 +112,23 @@ export function deviceApproval(r, c, target, folder) {
         ...(r.port ? { local_port: r.port.local_port, remote_port: r.port.remote_port } : {}),
     };
 }
+/** A request on a folder anywhere on this device: the folder kinds, and file moves named by an absolute or ~/ path. */
+export function folderRequest(r) {
+    return FOLDER_KINDS.has(r.kind) || ((r.kind === 'files_pull' || r.kind === 'files_push') && !!r.files && isDevicePath(r.files.local_path_relative));
+}
+/** What a folder request's approval shows: the canonical path, the folder Always would cover, and what will happen. */
+export function folderApproval(r, c, target, folder, home, remote, platform = process.platform) {
+    const shown = displayPath(target, home), yours = yourComputer(platform);
+    const summary = r.kind === 'dir_list' ? `List ${shown} on ${yours}: names, sizes and Git remotes, no file contents.`
+        : r.kind === 'project_link' ? `Make ${shown} a project and copy its files to the cloud (uncommitted changes too; .gitignore respected)${r.link?.brief ? ', then start a conversation there' : ''}.`
+            : r.kind === 'files_pull' ? `Share with conversation: ${shown} → ${r.files?.remote_path}` : `Save on ${yours}: ${r.files?.remote_path} → ${shown}`;
+    return {
+        type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id, summary, outside: true, scope: 'folder', folder,
+        kind: r.kind, local_path: target, project_name: basename(folder), conversation_title: c.title || conversationName(c),
+        ...(r.files ? { remote_path: r.files.remote_path } : {}), ...(r.dir ? { depth: r.dir.depth ?? 1 } : {}),
+        ...(r.kind === 'project_link' ? { repo_remote: remote ?? null, ...(r.link?.brief ? { brief: r.link.brief } : {}) } : {}),
+    };
+}
 export function tryLocallyAction(r) {
     if (r.kind === 'try_locally')
         return 'start';
@@ -171,6 +212,8 @@ export class DeviceExecutor {
         safeId(r.id);
         if (r.state !== 'pending' || r.device_id !== this.#deviceId)
             return;
+        if (folderRequest(r))
+            return this.#folder(r);
         const records = localConversations(ctx);
         const matching = Object.values(records).filter(record => record.project_id === r.project_id);
         const folders = new Set(matching.map(record => record.folder));
@@ -199,7 +242,7 @@ export class DeviceExecutor {
         if (devicePath(record.folder, join('.shard', 'worktrees', conversationName(c))).path !== planned.path || devicePath(planned.path, requested).path !== target.path)
             throw new Error('Device path changed during approval.');
         const current = await getConversation(ctx, r.conversation_id);
-        if (current.project_id !== c.project_id || current.branch !== c.branch || current.state === 'done' || current.state === 'archived')
+        if (current.project_id !== c.project_id || current.branch !== c.branch || archived(current))
             throw new Error('The conversation changed or ended during device approval.');
         c = current;
         await this.result(r, { state: 'approved' });
@@ -214,7 +257,7 @@ export class DeviceExecutor {
             if (root !== planned.path || devicePath(root, requested).path !== target.path)
                 throw new Error('Device path changed during preparation.');
             const prepared = await getConversation(ctx, c.id);
-            if (prepared.project_id !== c.project_id || prepared.workspace_id !== c.workspace_id || prepared.branch !== c.branch || prepared.state === 'done' || prepared.state === 'archived')
+            if (prepared.project_id !== c.project_id || prepared.workspace_id !== c.workspace_id || prepared.branch !== c.branch || archived(prepared))
                 throw new Error('The conversation changed or ended during device preparation.');
             const cell = ws.cell();
             let result;
@@ -270,6 +313,8 @@ export class DeviceExecutor {
                 result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : relative(root, target.path) };
             }
             else {
+                if (r.kind !== 'port_forward' && r.kind !== 'port_reverse')
+                    throw new UsageError('Unknown device request kind.');
                 if (!r.port || ![r.port.local_port, r.port.remote_port].every(p => Number.isInteger(p) && p > 0 && p <= 65535))
                     throw new UsageError('Device ports must be 1–65535.');
                 const handle = await devicePort(ws, cell, r.kind, r.port, ctx.signal);
@@ -286,6 +331,129 @@ export class DeviceExecutor {
                 ws?.cell().close();
         }
     }
+    /**
+     * A folder anywhere on this device (device-folders.ts). Every outcome is answered, so a request is never asked twice:
+     * denied before it was approved, failed after.
+     */
+    async #folder(r) {
+        const ctx = this.#ctx, home = deviceHome(ctx), deny = (message) => this.result(r, { state: 'denied', stderr_b64: Buffer.from(message).toString('base64') });
+        let c;
+        try {
+            c = await getConversation(ctx, r.conversation_id);
+            if (c.project_id !== r.project_id)
+                throw new Error('Device request project changed.');
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await deny(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (archived(c)) {
+            await deny('The conversation has ended.');
+            return;
+        }
+        const requested = r.dir?.path ?? r.link?.path ?? r.files?.local_path_relative ?? '';
+        const resolveTarget = () => canonicalDevicePath(expandDevicePath(requested, home));
+        let target, folder, remote = null;
+        try {
+            target = resolveTarget();
+            folder = r.kind === 'files_pull' || r.kind === 'files_push' ? canonicalDevicePath(dirname(target)) : target;
+            if (r.kind === 'project_link') {
+                const { projectIdentity } = await import("./project-identity.js");
+                remote = projectIdentity(target).remote;
+            }
+        }
+        catch (e) {
+            await deny(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        const grants = new DeviceGrants(ctx.store.dir);
+        let choice;
+        try {
+            choice = grants.allowsFolder(ctx.apiUrl, target, r.kind) ? 'once' : await this.#ask(folderApproval(r, c, target, folder, home, remote));
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await deny(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (ctx.signal.aborted)
+            return;
+        if (choice !== 'once' && choice !== 'always') {
+            await this.result(r, { state: 'denied' });
+            return;
+        }
+        if (choice === 'always')
+            await grants.saveFolder(ctx.apiUrl, folder, r.kind);
+        // Re-read after the approval, before claiming or touching data: a symlink swapped meanwhile is a different path.
+        let now;
+        try {
+            now = resolveTarget();
+        }
+        catch {
+            now = '';
+        }
+        if (now !== target) {
+            await deny('Device path changed during approval.');
+            return;
+        }
+        const current = await getConversation(ctx, r.conversation_id).catch(() => undefined);
+        if (!current || current.project_id !== c.project_id || archived(current)) {
+            await deny('The conversation changed or ended during device approval.');
+            return;
+        }
+        await this.result(r, { state: 'approved' });
+        await this.result(r, { state: 'running' });
+        let ws;
+        try {
+            let result;
+            if (r.kind === 'dir_list')
+                result = { state: 'done', dir: await listDeviceDir(target, r.dir ?? {}, ctx.signal) };
+            else if (r.kind === 'project_link')
+                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id }) };
+            else {
+                const f = r.files;
+                if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))
+                    throw new UsageError('Device transfer requires an absolute VM path.');
+                const max = f.max_bytes ?? LIMIT;
+                if (!Number.isSafeInteger(max) || max < 1 || max > LIMIT)
+                    throw new UsageError('Device transfer maximum is 256 MiB.');
+                ws = await conversationWorkspace({ ...ctx, signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(30_000)]) }, current);
+                const cell = ws.cell();
+                if (r.kind === 'files_pull') {
+                    const info = await stat(target);
+                    if (!info.isFile() || info.size > max)
+                        throw new UsageError('Local transfer file exceeds the requested size or is not a file.');
+                    const bytes = await readFile(target);
+                    if (bytes.length > max)
+                        throw new UsageError('Local transfer file grew during reading.');
+                    await writeSyncBlob(cell, f.remote_path, bytes);
+                }
+                else {
+                    const info = await cell.files.stat(f.remote_path);
+                    if (info.type !== 'file' || info.size > max)
+                        throw new UsageError('VM transfer file exceeds the requested size or is not a file.');
+                    const bytes = await cell.files.read(f.remote_path, { length: max + 1 });
+                    if (bytes.length > max || bytes.length !== info.size)
+                        throw new UsageError('VM transfer file changed during reading.');
+                    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+                    if (await realpath(dirname(target)) !== folder)
+                        throw new Error('Transfer folder changed during the transfer.');
+                    await writeFile(target, bytes, { mode: 0o600, flag: 'wx' }); // An existing file needs a fresh explicit request, never a silent clobber.
+                }
+                result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : target };
+            }
+            await this.result(r, result);
+        }
+        catch (e) {
+            await this.result(r, { state: 'failed', stderr_b64: Buffer.from(e instanceof Error ? e.message : String(e)).toString('base64') });
+        }
+        finally {
+            ws?.cell().close();
+        }
+    }
     async reap() {
         for (const [id, handle] of this.#handles) {
             const c = await getConversation(this.#ctx, handle.conversation);
@@ -323,8 +491,24 @@ export async function devicePort(ws, cell, kind, ports, signal) {
     await new Promise((resolveListen, reject) => { server.once('error', reject); server.listen(ports.local_port, '127.0.0.1', resolveListen); });
     let stopping;
     const abort = () => { void stop().catch(() => undefined); };
-    const stop = () => stopping ??= (async () => { signal.removeEventListener('abort', abort); for (const socket of peers)
-        socket.destroy(); await Promise.all([...handles].map(h => h.close())); await new Promise(resolveClose => server.close(() => resolveClose())); cell.close(); })();
+    const stop = () => stopping ??= (async () => {
+        signal.removeEventListener('abort', abort);
+        for (const socket of peers)
+            socket.destroy();
+        let failure;
+        await Promise.all([...handles].map(async (handle) => {
+            try {
+                await handle.close();
+            }
+            catch (error) {
+                failure ??= { error };
+            }
+        }));
+        await new Promise(resolveClose => server.close(() => resolveClose()));
+        cell.close();
+        if (failure)
+            throw failure.error;
+    })();
     signal.addEventListener('abort', abort, { once: true });
     if (signal.aborted)
         abort();
@@ -419,3 +603,46 @@ export async function askConnectedAcp(dir, approval, signal) {
         } });
     });
 }
+/**
+ * The desktop app's approval hop (0.25.0+): while it runs it serves `<config dir>/device-approver.sock` (or, when that
+ * path is too long for a socket, `/tmp/sf-device-<uid>/<hash>-approver.sock`) and shows each approval as a Needs-you
+ * item. One line in (the DeviceApproval JSON), one line out (`{"choice":"once|always|deny"}`). No app, a socket that is
+ * not this user's own, or one that closes without an answer: null, and the next surface asks.
+ */
+export function approverSocket(dir) {
+    const path = join(dir, 'device-approver.sock');
+    if (Buffer.byteLength(path) < 100)
+        return path;
+    return join('/tmp', `sf-device-${process.getuid?.() ?? 'user'}`, `${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 20)}-approver.sock`);
+}
+export async function askDeviceApprover(dir, approval, signal) {
+    const path = approverSocket(dir), uid = process.getuid?.();
+    try {
+        const socket = lstatSync(path), parent = lstatSync(dirname(path));
+        if (!socket.isSocket() || parent.isSymbolicLink() || !parent.isDirectory() || (parent.mode & 0o077) || (uid !== undefined && (socket.uid !== uid || parent.uid !== uid)))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return new Promise((resolveChoice, reject) => {
+        const socket = createConnection(path);
+        let text = '';
+        const abort = () => { socket.destroy(); reject(signal.reason instanceof Error ? signal.reason : new Error('Device approval interrupted')); };
+        signal.addEventListener('abort', abort, { once: true });
+        socket.on('connect', () => socket.write(JSON.stringify(approval) + '\n'));
+        socket.on('data', bytes => { text += String(bytes); if (text.length > 1024)
+            socket.destroy(); });
+        socket.once('error', () => { signal.removeEventListener('abort', abort); resolveChoice(null); });
+        socket.once('close', () => {
+            signal.removeEventListener('abort', abort);
+            try {
+                const choice = JSON.parse(text.split('\n')[0]).choice;
+                resolveChoice(['once', 'always', 'deny'].includes(choice) ? choice : null);
+            }
+            catch {
+                resolveChoice(null);
+            }
+        });
+    });
+}

package/dist/device-folders.d.ts

@@ -0,0 +1,58 @@
+import type { Ctx, Handler } from './commands.js';
+export declare const FOLDER_KINDS: Set<string>;
+/** An absolute or `~/…` path: one the device resolves on its own, outside any conversation's folder. */
+export declare function isDevicePath(path: string): boolean;
+export declare function deviceHome(ctx: Pick<Ctx, 'io'>): string;
+export declare function expandDevicePath(path: string, home: string): string;
+/** Through every symlink of the part that exists; a path that does not exist yet keeps its missing tail. */
+export declare function canonicalDevicePath(target: string): string;
+/** `/Users/me/code` as `~/code`: how a person reads their own folders. */
+export declare function displayPath(path: string, home: string): string;
+export interface DirListing {
+    path: string;
+    entries: {
+        path: string;
+        kind: 'file' | 'dir' | 'symlink' | 'other';
+        size?: number;
+        git_remote?: string;
+    }[];
+    truncated: boolean;
+    git_remote?: string;
+}
+/** Names, kinds, sizes and Git remotes under `root`, breadth first, bounded in depth, count and bytes. */
+export declare function listDeviceDir(root: string, options?: {
+    depth?: number;
+    max_entries?: number;
+    include_hidden?: boolean;
+}, signal?: AbortSignal): Promise<DirListing>;
+export interface LinkedProject {
+    project_id: string;
+    repo_remote: string;
+    folder: string;
+    name: string;
+    conversation_id?: string;
+}
+type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string) => Promise<{
+    id: string;
+    project_id: string;
+}>;
+/**
+ * A new chat in `folder`, started the way `shard agents new --path` starts one, in its own process: the folder's
+ * working tree (uncommitted files too, .gitignore respected) seeds it while its VM boots, and the brief is its first
+ * prompt. The brief goes in on standard input, never in a command line another user can read.
+ */
+export declare const startFromFolder: Starter;
+/**
+ * `folder` becomes one of your projects: the repository its Git origin names (else the folder itself), in your
+ * project on this API. It is selected for background preparation, so its files are in the cloud before the next chat,
+ * and kept as this device's live copy: what conversations started from it finish lands back in it. With `brief`, a
+ * conversation starts there at once. A folder without Git gets a repository, as a new chat from it does.
+ */
+export declare function linkLocalProject(ctx: Ctx, path: string, options?: {
+    brief?: string;
+    harness?: 'claude' | 'codex';
+    projectId?: string;
+}, start?: Starter): Promise<LinkedProject>;
+/** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
+export declare const PROJECT_LINK_HANDLERS: Record<string, Handler>;
+export {};