@shardflux/cli 0.25.0 → 0.28.1

package/dist/device-approvals.js

@@ -6,6 +6,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { writePrivateFile } from "./credentials.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
+import { thisComputer } from "./this-computer.js";
+import { chooseLine, MODE_LABELS, deviceActivity, readDeviceSettings, setDeviceApprovalMode } from "./device-mode.js";
 const paths = (dir, id) => {
     if (!/^[a-zA-Z0-9_-]{1,96}$/.test(id))
         throw new UsageError('Invalid device request id.');
@@ -39,12 +41,19 @@ export function answerDeviceApproval(dir, id, choice) {
         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 }));
 }
+/** Config dirs whose helper printed the choose line (once per helper, not per request). */
+const toldChoice = new Set();
 /** Local user-owned files carry approvals; cloud data can never answer its own request. */
 export async function askLocalDeviceApproval(ctx, approval) {
     const file = paths(ctx.store.dir, approval.request_id), nonce = randomUUID();
     rmSync(file.answer, { force: true });
     writePrivateFile(join(ctx.store.dir, 'device-approvals'), file.pending, JSON.stringify({ ...approval, nonce, pid: process.pid }));
-    spawnSync('notify-send', ['--', 'Shardflux approval', `${approval.summary}\nReview: shard device requests`], { env: ctx.io.env, stdio: 'ignore', timeout: 2000 });
+    // Not chosen yet (device-mode.ts): one line with the exact commands; choosing one answers this request too.
+    if (approval.choose_mode && !toldChoice.has(ctx.store.dir)) {
+        toldChoice.add(ctx.store.dir);
+        ctx.io.stderr.write(`Device bridge: ${chooseLine()}\n`);
+    }
+    spawnSync('notify-send', ['--', 'Shardflux approval', `${approval.summary}\n${approval.choose_mode ? chooseLine() : 'Review: shard device requests'}`], { env: ctx.io.env, stdio: 'ignore', timeout: 2000 });
     try {
         while (!ctx.signal.aborted) {
             try {
@@ -62,10 +71,23 @@ export async function askLocalDeviceApproval(ctx, approval) {
         rmSync(file.answer, { force: true });
     }
 }
+const activityLine = (a) => `${a.at.slice(0, 16).replace('T', ' ')}  ${a.state}${a.exit_code !== undefined ? ` (exit ${a.exit_code})` : ''}  ${a.summary}${a.conversation_title ? `  · ${a.conversation_title}` : ''}\n`;
 export const DEVICE_HANDLERS = {
+    /** `shard device approvals [auto|read|ask]` (0.27.0+): how this computer answers your agents, and what ran without asking. */
+    'device approvals'(ctx, _values, [mode]) {
+        const settings = mode ? setDeviceApprovalMode(ctx.store.dir, mode, ctx.store.profile(ctx.apiUrl).session?.user?.id) : readDeviceSettings(ctx.store.dir);
+        const recent = deviceActivity(ctx.store.dir, 10);
+        if (ctx.json) {
+            ctx.io.stdout.write(json({ approvals: settings.approvals ?? null, chosen_at: settings.chosen_at ?? null, recent }));
+            return Promise.resolve(0);
+        }
+        const now = settings.approvals ? `Your agents on ${thisComputer()}: ${MODE_LABELS[settings.approvals]}.\n` : `Your agents on ${thisComputer()}: not chosen yet; each request asks.\n${chooseLine()}\n`;
+        ctx.io.stdout.write(now + (recent.length ? `Ran without asking:\n${recent.map(activityLine).join('')}` : ''));
+        return Promise.resolve(0);
+    },
     '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}` : ''}${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');
+        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('') + (requests.some(r => r.choose_mode) ? `${chooseLine()}\n` : '') : 'No device requests waiting for approval.\n');
         return Promise.resolve(0);
     },
     ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, values, [id]) => {

package/dist/device-bridge.d.ts

@@ -2,6 +2,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';
+import type { HubSeed } from './project-hub-seed.js';
 export type DeviceChoice = 'once' | 'always' | 'deny';
 export interface DeviceRequest {
     id: string;
@@ -62,8 +63,15 @@ export interface DeviceApproval {
     brief?: string;
     /** dir_list: how many levels below the folder are listed. */
     depth?: number;
+    /**
+     * 0.27.0+: this person has not chosen how this computer answers their agents (device-mode.ts). A surface that knows
+     * it asks that first ("Allow everything" / "Ask each time", saved with `shard device approvals auto|ask`): once the
+     * mode lets this request run, the helper takes it by itself and this approval goes away; with "Ask each time" the
+     * request is then answered as usual. A surface that predates it shows the approval as before.
+     */
+    choose_mode?: true;
 }
-type Result = {
+export type Result = {
     state: 'approved' | 'denied' | 'running' | 'done' | 'failed';
     exit_code?: number;
     stdout_b64?: string;
@@ -72,6 +80,12 @@ type Result = {
     dir?: DirListing;
     project?: LinkedProject;
 };
+/**
+ * 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 declare function postResult(post: (answer: Result, again: boolean) => Promise<void>, result: Result): Promise<void>;
 /** Resolve existing ancestors even before the conversation worktree is created. */
 export declare function devicePath(root: string, requested?: string): {
     path: string;
@@ -105,10 +119,17 @@ export declare function folderApproval(r: DeviceRequest, c: Conversation, target
 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>;
+export type DeviceAsk = (approval: DeviceApproval, signal?: AbortSignal) => Promise<DeviceChoice>;
 export declare class DeviceExecutor {
     #private;
-    constructor(ctx: Ctx, ask: (approval: DeviceApproval) => Promise<DeviceChoice>, deviceId: string);
-    result(r: DeviceRequest, result: Result): Promise<void>;
+    constructor(ctx: Ctx, ask: DeviceAsk, deviceId: string, options?: {
+        seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>;
+    });
+    /** 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: string);
+    get deviceId(): string;
+    /** `again`: a second answer of the same state with another body (its own idempotency key). */
+    result(r: DeviceRequest, result: Result, again?: string): Promise<void>;
     execute(r: DeviceRequest): Promise<void>;
     reap(): Promise<void>;
     close(): Promise<void>;
@@ -131,4 +152,3 @@ export declare function askConnectedAcp(dir: string, approval: DeviceApproval, s
  */
 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

@@ -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,89 @@ export class DeviceExecutor {
     #ask;
     #deviceId;
     #handles = new Map();
-    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 });
+    /** Requests that run without asking (device-mode.ts), until their outcome is recorded. */
+    #auto = new Map();
+    #identity = { at: 0 };
+    /** How an agent's folder link reaches the project hub (project-hub-seed.ts unless a test gives its own hub). */
+    #seedHub;
+    constructor(ctx, ask, deviceId, options = {}) {
+        this.#ctx = ctx;
+        this.#ask = ask;
+        this.#deviceId = deviceId;
+        this.#seedHub = options.seedHub;
+    }
+    /** 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 +321,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 +332,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 +436,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 +544,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 +585,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 }, undefined, this.#seedHub) };
             else {
                 const f = r.files;
                 if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))
@@ -445,7 +618,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[];