@shardflux/cli 0.25.0 → 0.28.0

package/dist/device-bridge.js

@@ -16,6 +16,29 @@ 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";
+import { ownConversation } from "./agent-config-return.js";
+import { deviceApprovalMode, recordDeviceActivity, runsWithoutAsking } from "./device-mode.js";
+import { setTimeout as delay } from 'node:timers/promises';
+/**
+ * Posts a request's answer. An API before a linked folder's start point (train 47) refuses a link's commit and branch
+ * (422 validation_failed): the link is done, so it is posted again without them (staging 2026-10-17: the answer was
+ * refused and the request read as failed).
+ */
+export async function postResult(post, result) {
+    try {
+        await post(result, false);
+    }
+    catch (e) {
+        const project = result.project, status = e.status, code = e.code;
+        if (!project?.commit || !(status === 400 || status === 422 || code === 'validation_failed'))
+            throw e;
+        const older = { ...project };
+        delete older.commit;
+        delete older.branch;
+        // Another body, so its own idempotency key.
+        await post({ ...result, project: older }, true);
+    }
+}
 const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
 /**
@@ -203,9 +226,82 @@ export class DeviceExecutor {
     #ask;
     #deviceId;
     #handles = new Map();
+    /** Requests that run without asking (device-mode.ts), until their outcome is recorded. */
+    #auto = new Map();
+    #identity = { at: 0 };
     constructor(ctx, ask, deviceId) { this.#ctx = ctx; this.#ask = ask; this.#deviceId = deviceId; }
-    async result(r, result) {
-        await conversationClient(this.#ctx).deviceRequests.result(safeId(r.id), result, { idempotencyKey: `${this.#deviceId}:${r.id}:${result.state}`, signal: this.#ctx.signal });
+    /** A new device id for a new sign-in (device-helper.ts): requests for the old one are no longer this device's. */
+    set deviceId(id) { this.#deviceId = id; this.#identity = { at: 0 }; }
+    get deviceId() { return this.#deviceId; }
+    /** `again`: a second answer of the same state with another body (its own idempotency key). */
+    async result(r, result, again = '') {
+        // How a request that ran without asking ended is kept here first: it ran on this computer whether or not the
+        // answer reaches the API (a stopped helper, a network error).
+        const auto = this.#auto.get(r.id);
+        if (auto && result.state !== 'approved' && result.state !== 'running') {
+            this.#auto.delete(r.id);
+            recordDeviceActivity(this.#ctx.store.dir, { ...auto, at: new Date().toISOString(), state: result.state, ...(result.exit_code !== undefined ? { exit_code: result.exit_code } : {}) });
+        }
+        await conversationClient(this.#ctx).deviceRequests.result(safeId(r.id), result, { idempotencyKey: `${this.#deviceId}:${r.id}:${result.state}${again}`, signal: this.#ctx.signal });
+    }
+    /** This computer's person (the signed-in user, or who created its API key), checked every 10 minutes. */
+    async #me() {
+        if (Date.now() - this.#identity.at < 10 * 60_000)
+            return this.#identity.userId;
+        let userId = this.#ctx.store.profile(this.#ctx.apiUrl).session?.user?.id;
+        if (!userId) {
+            try {
+                const me = await conversationClient(this.#ctx).me();
+                userId = me.user?.id ?? me.api_key?.created_by_user_id ?? undefined;
+            }
+            catch { /* unknown: only conversations started here are this person's */ }
+        }
+        this.#identity = { at: Date.now(), ...(userId ? { userId } : {}) };
+        return userId;
+    }
+    /**
+     * Allow once by a grant, by this person's approval mode (device-mode.ts), or by asking. Only this person's own
+     * agents run without asking. Until they choose a mode, their first request asks for it (`choose_mode`), and a mode
+     * chosen while a request waits (the prompt, Settings, `shard device approvals`) takes the request by itself.
+     */
+    async #decide(r, c, approval, granted) {
+        if (granted)
+            return 'once';
+        const dir = this.#ctx.store.dir, me = await this.#me();
+        const mine = ownConversation(c, localConversations(this.#ctx), me);
+        const mode = deviceApprovalMode(dir, me);
+        const auto = (m) => {
+            this.#auto.set(r.id, { at: new Date().toISOString(), request_id: r.id, conversation_id: c.id, kind: r.kind, summary: approval.summary, mode: m, state: 'running',
+                ...(approval.conversation_title ? { conversation_title: approval.conversation_title } : {}), ...(approval.project_name ? { project_name: approval.project_name } : {}),
+                ...(approval.argv ? { argv: approval.argv } : {}), ...(approval.local_path ? { local_path: approval.local_path } : {}) });
+            recordDeviceActivity(dir, this.#auto.get(r.id));
+            return 'once';
+        };
+        if (mine && mode && runsWithoutAsking(mode, r.kind))
+            return auto(mode);
+        if (!mine)
+            return this.#ask(approval);
+        const stop = new AbortController();
+        let chosen;
+        const watch = (async () => {
+            while (!stop.signal.aborted) {
+                await delay(400, undefined, { signal: stop.signal }).catch(() => undefined);
+                const now = deviceApprovalMode(dir, me);
+                if (!stop.signal.aborted && now && runsWithoutAsking(now, r.kind)) {
+                    chosen = now;
+                    stop.abort();
+                }
+            }
+        })();
+        try {
+            const choice = await this.#ask(mode ? approval : { ...approval, choose_mode: true }, stop.signal).catch((e) => { if (chosen)
+                return 'once'; throw e; });
+            return chosen ? auto(chosen) : choice;
+        }
+        finally {
+            stop.abort();
+            await watch;
+        }
     }
     async execute(r) {
         const ctx = this.#ctx;
@@ -218,8 +314,10 @@ export class DeviceExecutor {
         const matching = Object.values(records).filter(record => record.project_id === r.project_id);
         const folders = new Set(matching.map(record => record.folder));
         const record = records[r.conversation_id] ?? (folders.size === 1 ? matching[0] : undefined);
+        // No folder of this conversation on this computer: a home conversation's command (an orchestrator thread asking the
+        // person's computer) runs in their home folder once they allow it; anything else is answered, never left waiting.
         if (!record || record.project_id !== r.project_id)
-            return; // No inferred local path for unknown projects.
+            return this.#unplaced(r);
         let c = await getConversation(ctx, r.conversation_id);
         if (c.project_id !== r.project_id)
             throw new Error('Device request project changed.');
@@ -227,7 +325,7 @@ export class DeviceExecutor {
         const requested = r.exec?.cwd_relative ?? r.files?.local_path_relative ?? '.';
         const target = devicePath(planned.path, requested), grants = new DeviceGrants(ctx.store.dir);
         target.outside ||= planned.outside;
-        const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask(deviceApproval(r, c, target, record.folder));
+        const choice = await this.#decide(r, c, deviceApproval(r, c, target, record.folder), grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside));
         if (choice === 'deny') {
             await this.result(r, { state: 'denied' });
             return;
@@ -331,6 +429,74 @@ export class DeviceExecutor {
                 ws?.cell().close();
         }
     }
+    /**
+     * A request whose conversation has no folder on this device (0.27.0+). A home conversation's exec runs in the home
+     * folder, or the ~/ or absolute directory it names, after the person allows this one request (never Always: commands
+     * never run under a grant). Everything else is refused with the reason, so its agent hears it instead of waiting forever.
+     */
+    async #unplaced(r) {
+        const ctx = this.#ctx, home = deviceHome(ctx), say = (state, message) => this.result(r, { state, 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 say('denied', e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (archived(c)) {
+            await say('denied', 'The conversation has ended.');
+            return;
+        }
+        if (r.kind !== 'exec' || !r.exec || c.home !== true) {
+            await say('denied', `This conversation has no folder on ${yourComputer()}: commands and file moves need its folder here (open the conversation on this computer), or a ~/ path for a file.`);
+            return;
+        }
+        let target;
+        try {
+            const requested = r.exec.cwd_relative && r.exec.cwd_relative !== '.' ? r.exec.cwd_relative : '~';
+            target = canonicalDevicePath(expandDevicePath(isDevicePath(requested) ? requested : `~/${requested}`, home));
+        }
+        catch (e) {
+            await say('denied', e instanceof Error ? e.message : String(e));
+            return;
+        }
+        const approval = { ...deviceApproval(r, c, { path: target, outside: true }, home),
+            summary: `Run on ${yourComputer()}: ${r.exec.argv.join(' ')} · in ${displayPath(target, home)}` };
+        let choice;
+        try {
+            choice = await this.#decide(r, c, approval, false);
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await say('denied', e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (ctx.signal.aborted)
+            return;
+        if (choice !== 'once') {
+            await this.result(r, { state: 'denied' });
+            return;
+        }
+        const current = await getConversation(ctx, r.conversation_id).catch(() => undefined);
+        if (!current || current.project_id !== c.project_id || archived(current)) {
+            await say('denied', 'The conversation changed or ended during device approval.');
+            return;
+        }
+        await this.result(r, { state: 'approved' });
+        await this.result(r, { state: 'running' });
+        try {
+            await this.result(r, await deviceExec(r.exec.argv, target, r.exec.timeout_seconds, ctx.signal));
+        }
+        catch (e) {
+            await say('failed', e instanceof Error ? e.message : String(e));
+        }
+    }
     /**
      * 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.
@@ -371,7 +537,7 @@ export class DeviceExecutor {
         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));
+            choice = await this.#decide(r, c, folderApproval(r, c, target, folder, home, remote), grants.allowsFolder(ctx.apiUrl, target, r.kind));
         }
         catch (e) {
             if (ctx.signal.aborted)
@@ -412,7 +578,7 @@ export class DeviceExecutor {
             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 }) };
+                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, seed: true }) };
             else {
                 const f = r.files;
                 if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))
@@ -445,7 +611,7 @@ export class DeviceExecutor {
                 }
                 result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : target };
             }
-            await this.result(r, result);
+            await postResult((answer, again) => this.result(r, answer, again ? ':older-api' : ''), result);
         }
         catch (e) {
             await this.result(r, { state: 'failed', stderr_b64: Buffer.from(e instanceof Error ? e.message : String(e)).toString('base64') });

package/dist/device-folders.d.ts

@@ -1,4 +1,5 @@
 import type { Ctx, Handler } from './commands.js';
+import type { HubSeed } from './project-hub-seed.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;
@@ -25,12 +26,15 @@ export declare function listDeviceDir(root: string, options?: {
     max_entries?: number;
     include_hidden?: boolean;
 }, signal?: AbortSignal): Promise<DirListing>;
+/** `commit` and `branch`: where work on it starts, in the project hub (an agent's link, 0.28.0+). */
 export interface LinkedProject {
     project_id: string;
     repo_remote: string;
     folder: string;
     name: string;
     conversation_id?: string;
+    commit?: string;
+    branch?: string;
 }
 type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string) => Promise<{
     id: string;
@@ -60,7 +64,8 @@ export declare function linkLocalProject(ctx: Ctx, path: string, options?: {
     brief?: string;
     harness?: 'claude' | 'codex';
     projectId?: string;
-}, start?: Starter): Promise<LinkedProject>;
+    seed?: boolean;
+}, start?: Starter, seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>): 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 {};

package/dist/device-folders.js

@@ -18,6 +18,7 @@ import { UsageError } from "./errors.js";
 import { ensureProjectGit } from "./project-git.js";
 import { normalizeRemote, projectIdentity } from "./project-identity.js";
 import { selectProject } from "./project-preparation.js";
+import { seedProjectHub } from "./project-hub-seed.js";
 export const FOLDER_KINDS = new Set(['dir_list', 'project_link']);
 /** An absolute or `~/…` path: one the device resolves on its own, outside any conversation's folder. */
 export function isDevicePath(path) { return isAbsolute(path) || path === '~' || path.startsWith('~/'); }
@@ -200,7 +201,7 @@ function lastLine(stderr) {
  * 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 async function linkLocalProject(ctx, path, options = {}, start = startFromFolder) {
+export async function linkLocalProject(ctx, path, options = {}, start = startFromFolder, seedHub = seedProjectHub) {
     const { folder } = projectIdentity(path);
     await ensureProjectGit(ctx, folder);
     const identity = projectIdentity(folder);
@@ -218,7 +219,10 @@ export async function linkLocalProject(ctx, path, options = {}, start = startFro
     if (!projectId)
         throw new UsageError('Choose your default project first: shard projects use <id|slug>.');
     const name = [...(identity.remote ? identity.slug : basename(folder))].slice(0, 200).join('') || identity.slug;
-    return { project_id: projectId, repo_remote: identity.remote ?? `file://${folder}`, folder, name, ...(conversationId ? { conversation_id: conversationId } : {}) };
+    // An agent's link: the folder as it is now goes to the project hub, so its work can start in the cloud at once.
+    const seed = options.seed ? await seedHub(ctx, folder, projectId) : null;
+    return { project_id: projectId, repo_remote: identity.remote ?? `file://${folder}`, folder, name, ...(conversationId ? { conversation_id: conversationId } : {}),
+        ...(seed ? { commit: seed.commit, ...(seed.branch ? { branch: seed.branch } : {}) } : {}) };
 }
 /** `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 const PROJECT_LINK_HANDLERS = {

package/dist/device-helper.d.ts

@@ -9,3 +9,11 @@ export declare function runDeviceHelper(ctx: Ctx, options?: {
  * A home conversation, an Orchestrator master or a chat the desktop app started asks from these.
  */
 export declare function deviceProjects(ctx: Ctx): Promise<string[]>;
+/** 409 `device_id_taken`: this device id is registered in a project by another identity (POST /v1/device-requests/heartbeat). */
+export declare function deviceIdTaken(e: unknown): boolean;
+/**
+ * A new device id for this computer, replacing `old` (0.27.0+). Local state stays: grants are kept by API and folder
+ * or project (device-bridge.ts DeviceGrants), the approval mode by person (device-mode.ts), and the twin's refs by the
+ * id that made them. The old id is kept in `device-id-history.json` (the last 20) for support.
+ */
+export declare function renewDeviceId(dir: string, old: string, projectId: string): string;

package/dist/device-helper.js

@@ -42,22 +42,24 @@ export async function runDeviceHelper(ctx, options = {}) {
         }
     })().finally(() => abort.abort());
     void input.catch(() => abort.abort());
-    const ask = async (approval) => {
-        const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
+    // `until` ends one question early: the person chose a mode that lets the request run by itself (device-mode.ts).
+    const ask = async (approval, until) => {
+        const asking = until ? AbortSignal.any([signal, until]) : signal;
+        const acp = await askConnectedAcp(ctx.store.dir, approval, asking);
         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);
+        const app = await askDeviceApprover(ctx.store.dir, approval, asking);
         if (app)
             return app;
         if (options.service)
-            return askLocalDeviceApproval(ctx, approval);
+            return askLocalDeviceApproval({ ...ctx, signal: asking }, approval);
         return new Promise(resolve => {
             const denied = () => { pending.delete(approval.request_id); resolve('deny'); };
-            signal.addEventListener('abort', denied, { once: true });
-            pending.set(approval.request_id, choice => { signal.removeEventListener('abort', denied); resolve(choice); });
+            asking.addEventListener('abort', denied, { once: true });
+            pending.set(approval.request_id, choice => { asking.removeEventListener('abort', denied); resolve(choice); });
             ctx.io.stdout.write(JSON.stringify(approval) + '\n');
-            if (signal.aborted)
+            if (asking.aborted)
                 denied();
         }).finally(() => { if (!signal.aborted)
             ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
@@ -74,6 +76,10 @@ export async function runDeviceHelper(ctx, options = {}) {
         writePrivateFile(ctx.store.dir, deviceFile, deviceId + '\n');
     }
     const executor = new DeviceExecutor(ctx, ask, deviceId);
+    // A device id another identity registered (an earlier API key `shard setup` replaced, another account) can never
+    // register for this one: a refusal gives this computer a new id (0.27.0+), at most once every 10 minutes, so a second
+    // sign-in change later renews again and a refusal right after a renewal stops (never a loop).
+    let renewedAt = 0;
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
     let mirroring, twin, returning, preparing, projects;
     try {
@@ -150,6 +156,7 @@ export async function runDeviceHelper(ctx, options = {}) {
             // 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();
+            const registrationFailures = new Map();
             let all, deviceWide = true, links = true;
             // This device's local conversations of a project (started here or opened here): their requests come here first.
             const linked = (projectId) => Object.values(localConversations(ctx)).filter(r => !r.handed_off && (!projectId || r.project_id === projectId))
@@ -176,13 +183,42 @@ export async function runDeviceHelper(ctx, options = {}) {
                         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) {
+                        const failed = registrationFailures.get(projectId);
+                        if (failed && (failed.next === null || Date.now() < failed.next))
+                            continue;
                         if (Date.now() - (registered.get(projectId) ?? 0) < 10_000)
                             continue;
-                        await beat(projectId).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);
+                        await beat(projectId).then(() => {
+                            registered.set(projectId, Date.now());
+                            registrationFailures.delete(projectId);
+                        }, (e) => {
+                            if (deviceIdTaken(e) && Date.now() - renewedAt > 600_000) {
+                                renewedAt = Date.now();
+                                const old = deviceId;
+                                deviceId = renewDeviceId(ctx.store.dir, old, projectId);
+                                executor.deviceId = deviceId;
+                                // Every project registers again under the new id, at once.
+                                registered.clear();
+                                registrationFailures.clear();
+                                report(new Error(`this computer's device id ${old} belongs to another sign-in (an earlier API key or account); it registers as ${deviceId} for this one.`));
+                                return;
+                            }
+                            // A refused registration belongs to this project alone. Repeating a
+                            // device identity conflict cannot repair it or hold every later project.
+                            const attempts = (failed?.attempts ?? 0) + 1;
+                            const permanent = e instanceof ShardfluxApiError && !e.retryable;
+                            const stopped = permanent || attempts >= 8;
+                            const wait = Math.min(300_000, 5000 * 2 ** Math.min(attempts - 1, 6));
+                            registrationFailures.set(projectId, { attempts, next: stopped ? null : Date.now() + wait });
+                            const message = e instanceof Error ? e.message : String(e);
+                            if (stopped) {
+                                const action = e instanceof ShardfluxApiError && e.details?.reason === 'device_id_taken'
+                                    ? 'Its device id was renewed moments ago and is refused again; restart the device helper.'
+                                    : 'Check connectivity or sign in again, then restart the device helper to retry.';
+                                report(new Error(`Device helper needs attention for project ${projectId || 'default'} after ${attempts} failed registrations: ${message} ${action}`));
+                            }
+                            else
+                                report(new Error(`Device registration for project ${projectId || 'default'} failed (attempt ${attempts}/8): ${message} Retrying in ${wait / 1000}s.`));
                         });
                     }
                     let polled = false;
@@ -269,3 +305,26 @@ export async function deviceProjects(ctx) {
     }
     return [...ids];
 }
+/** 409 `device_id_taken`: this device id is registered in a project by another identity (POST /v1/device-requests/heartbeat). */
+export function deviceIdTaken(e) {
+    return e instanceof ShardfluxApiError && e.status === 409 && e.details?.reason === 'device_id_taken';
+}
+/**
+ * A new device id for this computer, replacing `old` (0.27.0+). Local state stays: grants are kept by API and folder
+ * or project (device-bridge.ts DeviceGrants), the approval mode by person (device-mode.ts), and the twin's refs by the
+ * id that made them. The old id is kept in `device-id-history.json` (the last 20) for support.
+ */
+export function renewDeviceId(dir, old, projectId) {
+    const id = randomUUID(), historyFile = join(dir, 'device-id-history.json');
+    let history = [];
+    try {
+        const value = JSON.parse(readFileSync(historyFile, 'utf8'));
+        if (Array.isArray(value))
+            history = value;
+    }
+    catch { /* first one */ }
+    history = [...history, { id: old, replaced_at: new Date().toISOString(), replaced_by: id, project_id: projectId || null }].slice(-20);
+    writePrivateFile(dir, historyFile, JSON.stringify(history, null, 2) + '\n');
+    writePrivateFile(dir, join(dir, 'device-id'), id + '\n');
+    return id;
+}

package/dist/device-mode.d.ts

@@ -0,0 +1,44 @@
+export type DeviceApprovalMode = 'auto' | 'read' | 'ask';
+export declare const DEVICE_APPROVAL_MODES: readonly DeviceApprovalMode[];
+/**
+ * The mode before the person chooses one. `undefined`: nothing is decided for them; the first request asks which they
+ * want (the app's prompt, or one line from `shard`), and the app's onboarding asks too. 'auto' or 'ask' here chooses
+ * for everyone who has not.
+ */
+export declare const DEFAULT_DEVICE_APPROVALS: DeviceApprovalMode | undefined;
+/** The kinds that only read this computer: a folder listing, and a file copied to the conversation. */
+export declare const READ_KINDS: ReadonlySet<string>;
+export declare const MODE_LABELS: Record<DeviceApprovalMode, string>;
+/** The one line a person without the app reads when a request needs the choice ("this Mac" on macOS). */
+export declare const chooseLine: (platform?: NodeJS.Platform) => string;
+export interface DeviceSettings {
+    approvals?: DeviceApprovalMode;
+    chosen_at?: string;
+    /** Who chose it, when known: another person signed in on this computer chooses for themselves. */
+    user_id?: string;
+}
+export declare function readDeviceSettings(dir: string): DeviceSettings;
+/** This person's mode on this computer; undefined until they choose one (and DEFAULT_DEVICE_APPROVALS is unset). */
+export declare function deviceApprovalMode(dir: string, userId?: string): DeviceApprovalMode | undefined;
+export declare function setDeviceApprovalMode(dir: string, mode: string, userId?: string): DeviceSettings;
+/** Whether a request of this kind runs without asking under this mode (for the person's own agents). */
+export declare function runsWithoutAsking(mode: DeviceApprovalMode | undefined, kind: string): boolean;
+/** One line of what ran without asking: the start (`running`) and how it ended, folded by `request_id`. */
+export interface DeviceActivity {
+    at: string;
+    request_id: string;
+    conversation_id: string;
+    kind: string;
+    summary: string;
+    mode: DeviceApprovalMode;
+    state: 'running' | 'done' | 'failed' | 'denied';
+    conversation_title?: string;
+    project_name?: string;
+    argv?: string[];
+    local_path?: string;
+    exit_code?: number;
+    finished_at?: string;
+}
+export declare function recordDeviceActivity(dir: string, entry: DeviceActivity): void;
+/** What ran without asking, newest first: one entry per request with its latest state. */
+export declare function deviceActivity(dir: string, limit?: number): DeviceActivity[];

package/dist/device-mode.js

@@ -0,0 +1,119 @@
+/**
+ * How this computer answers its own agents (0.27.0+): the person chooses once, per device, whether their agents run
+ * things here without asking each time. Kept in `<config>/device-settings.json`; changed in the app's Settings or with
+ * `shard device approvals auto|read|ask`. Requests that ran without asking are kept in `<config>/device-activity.jsonl`
+ * (what ran, for which conversation, and how it ended), shown by the app and `shard device approvals`.
+ *
+ * - `ask`: every request asks (Allow once, or Always where a grant applies).
+ * - `read`: listing a folder and copying a file to a conversation run without asking; anything that changes this
+ *   computer (commands, files saved here, ports, linking a folder) asks. Commands are never classified by their text.
+ * - `auto`: every request from this person's own agents runs without asking.
+ *
+ * Only this person's own conversations run without asking (`ownConversation`): a teammate's request always asks.
+ */
+import { appendFileSync, lstatSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writePrivateFile, ensurePrivateDir } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { thisComputer } from "./this-computer.js";
+export const DEVICE_APPROVAL_MODES = ['auto', 'read', 'ask'];
+/**
+ * The mode before the person chooses one. `undefined`: nothing is decided for them; the first request asks which they
+ * want (the app's prompt, or one line from `shard`), and the app's onboarding asks too. 'auto' or 'ask' here chooses
+ * for everyone who has not.
+ */
+export const DEFAULT_DEVICE_APPROVALS = undefined;
+/** The kinds that only read this computer: a folder listing, and a file copied to the conversation. */
+export const READ_KINDS = new Set(['dir_list', 'files_pull']);
+export const MODE_LABELS = {
+    auto: 'Allow everything from my agents',
+    read: 'Allow reading, ask before changes',
+    ask: 'Ask every time',
+};
+/** The one line a person without the app reads when a request needs the choice ("this Mac" on macOS). */
+export const chooseLine = (platform = process.platform) => `Let your agents run things on ${thisComputer(platform)} without asking each time? Allow everything: shard device approvals auto · Ask each time: shard device approvals ask`;
+const SETTINGS = 'device-settings.json', ACTIVITY = 'device-activity.jsonl';
+export function readDeviceSettings(dir) {
+    const file = join(dir, SETTINGS);
+    try {
+        if (lstatSync(file).isSymbolicLink() || (statSync(file).mode & 0o077))
+            return {};
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        return DEVICE_APPROVAL_MODES.includes(value.approvals) ? value : { ...value, approvals: undefined };
+    }
+    catch {
+        return {};
+    }
+}
+/** This person's mode on this computer; undefined until they choose one (and DEFAULT_DEVICE_APPROVALS is unset). */
+export function deviceApprovalMode(dir, userId) {
+    const s = readDeviceSettings(dir);
+    if (s.approvals && !(s.user_id && userId && s.user_id !== userId))
+        return s.approvals;
+    return DEFAULT_DEVICE_APPROVALS;
+}
+export function setDeviceApprovalMode(dir, mode, userId) {
+    if (!DEVICE_APPROVAL_MODES.includes(mode))
+        throw new UsageError(`Unknown approval mode "${mode}": auto, read or ask.`);
+    const next = { ...readDeviceSettings(dir), approvals: mode, chosen_at: new Date().toISOString() };
+    if (userId)
+        next.user_id = userId;
+    else
+        delete next.user_id;
+    writePrivateFile(dir, join(dir, SETTINGS), JSON.stringify(next, null, 2) + '\n');
+    return next;
+}
+/** Whether a request of this kind runs without asking under this mode (for the person's own agents). */
+export function runsWithoutAsking(mode, kind) {
+    return mode === 'auto' || (mode === 'read' && READ_KINDS.has(kind));
+}
+const ACTIVITY_MAX_BYTES = 512 << 10, ACTIVITY_KEEP = 400;
+export function recordDeviceActivity(dir, entry) {
+    const file = join(dir, ACTIVITY);
+    try {
+        ensurePrivateDir(dir);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+        }
+        catch { /* first entry */ }
+        if (size > ACTIVITY_MAX_BYTES) {
+            const keep = readFileSync(file, 'utf8').split('\n').filter(Boolean).slice(-ACTIVITY_KEEP);
+            writePrivateFile(dir, file, keep.join('\n') + '\n');
+        }
+        appendFileSync(file, JSON.stringify(entry) + '\n', { mode: 0o600 });
+    }
+    catch { /* the request's own result still reaches its conversation */ }
+}
+/** What ran without asking, newest first: one entry per request with its latest state. */
+export function deviceActivity(dir, limit = 20) {
+    let text;
+    try {
+        if (lstatSync(join(dir, ACTIVITY)).isSymbolicLink())
+            return [];
+        text = readFileSync(join(dir, ACTIVITY), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of text.split('\n')) {
+        if (!line)
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!e || typeof e.request_id !== 'string')
+            continue;
+        const had = byId.get(e.request_id);
+        byId.delete(e.request_id);
+        byId.set(e.request_id, had ? { ...had, ...e, at: had.at, ...(e.state !== 'running' ? { finished_at: e.at } : {}) } : e);
+    }
+    return [...byId.values()].reverse().slice(0, limit);
+}

package/dist/drive-commands.d.ts

@@ -14,8 +14,8 @@ export interface ProjectScope {
  * `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;
+/** `drive ls` and `brain ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+export declare function driveTable(rows: readonly Pick<DriveFile, 'size' | 'created_at' | 'content_type' | 'path'>[]): 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

package/dist/drive-commands.js

@@ -51,7 +51,7 @@ function drivePath(path, what = 'drive path') {
     }
     return path;
 }
-/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+/** `drive ls` and `brain 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]));
 }