@shardflux/cli 0.23.1 → 0.24.1

package/dist/device-folders.js

@@ -0,0 +1,228 @@
+/**
+ * Folders on this device that a conversation's agent asks about (0.25.0+): `dir_list` lists one (names, kinds, sizes
+ * and Git remotes; never file contents), `project_link` makes one a project of yours, seeded from here, and
+ * `files_pull`/`files_push` with an absolute or `~/` local path move a file to or from anywhere on this device.
+ *
+ * Nothing runs before this device approves it. The choices are Allow once and Always for this folder. Always covers
+ * that kind of request for that folder and everything inside it, resolved through symlinks, from any of your
+ * conversations on this API: a path outside every such folder asks again, and `exec` never uses a folder grant.
+ */
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { lstat, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { out, str } from "./commands.js";
+import { readInitialPrompt } from "./initial-prompt.js";
+import { UsageError } from "./errors.js";
+import { ensureProjectGit } from "./project-git.js";
+import { normalizeRemote, projectIdentity } from "./project-identity.js";
+import { selectProject } from "./project-preparation.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('~/'); }
+export function deviceHome(ctx) { return ctx.io.env.HOME || homedir(); }
+export function expandDevicePath(path, home) {
+    if (/[\0\r\n]/.test(path))
+        throw new UsageError('Device path contains invalid characters.');
+    if (path === '~')
+        return resolve(home);
+    if (path.startsWith('~/'))
+        return resolve(home, path.slice(2));
+    if (!isAbsolute(path))
+        throw new UsageError('Device path must be absolute or start with ~/.');
+    return resolve(path);
+}
+/** Through every symlink of the part that exists; a path that does not exist yet keeps its missing tail. */
+export 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));
+}
+/** `/Users/me/code` as `~/code`: how a person reads their own folders. */
+export function displayPath(path, home) {
+    const h = resolve(home);
+    return path === h ? '~' : path.startsWith(h + sep) ? `~/${path.slice(h.length + 1)}` : path;
+}
+/** Never descended into: their contents are noise to a person choosing a folder, and unbounded. */
+const OPAQUE = new Set(['.git', 'node_modules', '.shard']);
+/** The listing must fit the result body (1 MiB); paths and remotes over the API's 1024 characters are left out. */
+const LISTING_BYTES = 900 << 10, NAME_MAX = 1024, GIT_LOOKUPS = 200;
+function gitRemote(dir, signal) {
+    return new Promise(resolveRemote => {
+        execFile('git', ['-C', dir, 'remote', 'get-url', 'origin'], { timeout: 5000, signal, encoding: 'utf8', env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout) => {
+            if (error || !stdout.trim()) {
+                resolveRemote(undefined);
+                return;
+            }
+            // normalizeRemote drops the transport's user and password: a listing never carries credentials.
+            try {
+                const remote = normalizeRemote(stdout.trim(), dir);
+                resolveRemote(remote.length <= NAME_MAX ? remote : undefined);
+            }
+            catch {
+                resolveRemote(undefined);
+            }
+        });
+    });
+}
+/** Names, kinds, sizes and Git remotes under `root`, breadth first, bounded in depth, count and bytes. */
+export async function listDeviceDir(root, options = {}, signal) {
+    const depth = Math.min(Math.max(options.depth ?? 1, 1), 3), max = Math.min(Math.max(options.max_entries ?? 500, 1), 2000);
+    if (!(await lstat(root)).isDirectory())
+        throw new UsageError('That path is not a folder.');
+    const entries = [], repos = [];
+    let truncated = false, bytes = 0, queue = [{ dir: root, rel: '', level: 1 }];
+    while (queue.length && !truncated) {
+        const next = [];
+        for (const { dir, rel, level } of queue) {
+            signal?.throwIfAborted();
+            let names;
+            try {
+                names = (await readdir(dir)).sort((a, b) => a.localeCompare(b));
+            }
+            catch {
+                continue;
+            } // an unreadable folder lists as itself
+            for (const name of names) {
+                if (!options.include_hidden && name.startsWith('.'))
+                    continue;
+                const path = rel ? `${rel}/${name}` : name, full = join(dir, name);
+                if (path.length > NAME_MAX) {
+                    truncated = true;
+                    continue;
+                }
+                let info;
+                try {
+                    info = await lstat(full);
+                }
+                catch {
+                    continue;
+                }
+                const kind = info.isSymbolicLink() ? 'symlink' : info.isDirectory() ? 'dir' : info.isFile() ? 'file' : 'other';
+                const entry = { path, kind, ...(kind === 'file' ? { size: info.size } : {}) };
+                bytes += JSON.stringify(entry).length + 80;
+                if (entries.length >= max || bytes > LISTING_BYTES) {
+                    truncated = true;
+                    break;
+                }
+                entries.push(entry);
+                if (kind !== 'dir')
+                    continue;
+                if (existsSync(join(full, '.git')) && repos.length < GIT_LOOKUPS)
+                    repos.push({ index: entries.length - 1, dir: full });
+                if (level < depth && !OPAQUE.has(name))
+                    next.push({ dir: full, rel: path, level: level + 1 });
+            }
+            if (truncated)
+                break;
+        }
+        queue = next;
+    }
+    // Git remotes are read eight at a time, each bounded: a folder of a hundred repositories lists in about a second.
+    const own = existsSync(join(root, '.git')) ? gitRemote(root, signal) : Promise.resolve(undefined);
+    for (let i = 0; i < repos.length; i += 8) {
+        await Promise.all(repos.slice(i, i + 8).map(async (repo) => { const remote = await gitRemote(repo.dir, signal); if (remote)
+            entries[repo.index].git_remote = remote; }));
+    }
+    const remote = await own;
+    return { path: root, entries, truncated, ...(remote ? { git_remote: remote } : {}) };
+}
+/**
+ * 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 const startFromFolder = (ctx, folder, harness, brief) => {
+    const node = ctx.runtime?.node ?? process.execPath, script = ctx.runtime?.script ?? process.argv[1];
+    if (!script)
+        return Promise.reject(new Error('The Shardflux CLI could not find itself to start the conversation.'));
+    return new Promise((resolveStart, reject) => {
+        const child = spawn(node, [script, 'agents', 'new', '--app', harness, '--path', folder, '--prompt-file', '-', '--json'], {
+            cwd: folder, stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1' },
+        });
+        const out = [], err = [];
+        const stop = () => child.kill('SIGTERM');
+        const timer = setTimeout(stop, 300_000);
+        ctx.signal.addEventListener('abort', stop, { once: true });
+        child.stdout.on('data', (b) => { if (out.length < 256)
+            out.push(b); });
+        child.stderr.on('data', (b) => { if (err.length < 64)
+            err.push(b); });
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', code => {
+            clearTimeout(timer);
+            ctx.signal.removeEventListener('abort', stop);
+            const text = Buffer.concat(out).toString('utf8');
+            try {
+                if (code !== 0)
+                    throw new Error(lastLine(Buffer.concat(err).toString('utf8')) || `The conversation did not start (exit ${code}).`);
+                const started = JSON.parse(text.trim().split('\n').at(-1));
+                const id = started.conversation?.id ?? started.workspace?.labels?.shard_conversation;
+                if (!id)
+                    throw new Error('The conversation did not start.');
+                resolveStart({ id, project_id: started.conversation?.project_id ?? started.workspace?.project_id ?? '' });
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        child.stdin.end(brief);
+    });
+};
+function lastLine(stderr) {
+    const text = stderr.trim();
+    try {
+        const doc = JSON.parse(text);
+        if (doc.error?.message)
+            return doc.error.message;
+    }
+    catch { /* plain text */ }
+    return text.split('\n').at(-1)?.slice(0, 2000) ?? '';
+}
+/**
+ * `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 async function linkLocalProject(ctx, path, options = {}, start = startFromFolder) {
+    const { folder } = projectIdentity(path);
+    await ensureProjectGit(ctx, folder);
+    const identity = projectIdentity(folder);
+    selectProject(ctx, folder);
+    const profile = ctx.store.profile(ctx.apiUrl);
+    let projectId = profile.project_id ?? profile.api_key?.project_id ?? options.projectId, conversationId;
+    if (options.brief) {
+        const started = await start(ctx, folder, options.harness ?? 'claude', options.brief);
+        conversationId = started.id;
+        projectId = started.project_id || projectId;
+    }
+    // An API key from the environment (the desktop app's sign-in) names its project only to the API.
+    if (!projectId && ctx.io.env.SHARDFLUX_API_KEY?.trim())
+        projectId = (await ctx.cloud().me()).api_key?.project_id;
+    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 } : {}) };
+}
+/** `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 = {
+    async 'projects link'(ctx, values, [path]) {
+        if (!path)
+            throw new UsageError('Choose a local folder: shard projects link <path>.');
+        const app = str(values.app);
+        if (app !== undefined && app !== 'claude' && app !== 'codex')
+            throw new UsageError('--app must be claude or codex.');
+        const brief = await readInitialPrompt(ctx, values);
+        const project = await linkLocalProject(ctx, expandDevicePath(isDevicePath(path) ? path : resolve(path), deviceHome(ctx)), { ...(brief ? { brief } : {}), ...(app ? { harness: app } : {}) });
+        out(ctx, `Linked ${displayPath(project.folder, deviceHome(ctx))} as ${project.name} (${project.repo_remote}); it is prepared in the background.\n${project.conversation_id ? `Started conversation ${project.conversation_id}.\n` : ''}`, { project });
+        return 0;
+    },
+};

package/dist/device-helper.d.ts

@@ -3,3 +3,9 @@ import type { Ctx } from './commands.js';
 export declare function runDeviceHelper(ctx: Ctx, options?: {
     service?: boolean;
 }): Promise<number>;
+/**
+ * The projects this device answers for besides its local conversations' (0.25.0+): the signed-in project (the API
+ * key's, or the default one), and with a person's own sign-in and no key, every project they can reach (at most 100).
+ * A home conversation, an Orchestrator master or a chat the desktop app started asks from these.
+ */
+export declare function deviceProjects(ctx: Ctx): Promise<string[]>;

package/dist/device-helper.js

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

package/dist/drive-commands.d.ts

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

package/dist/drive-commands.js

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

package/dist/filesystem-commands.js

@@ -41,7 +41,8 @@ async function templateSource(ctx, project) {
 export function filesystemLine(state) {
     const rebase = state.rebase_deferred ? ', follows your machine on next use' : state.rebase_pending ? ', rebase pending' : '';
     const base = state.platform_base ? `; platform ${state.platform_base.slug}@${state.platform_base.version}${rebase}` : '';
-    return usageLine(state) + base + (state.cache_scope ? `; cache: ${state.cache_scope}` : '');
+    const volumes = state.volumes?.length ? `; volumes: ${state.volumes.map(v => `${v.name} at ${v.mount_path} (${v.mode})`).join(', ')}` : '';
+    return usageLine(state) + base + volumes + (state.cache_scope ? `; cache: ${state.cache_scope}` : '');
 }
 function usageLine(state) {
     const current = state.version > 0 ? `version ${state.version}` : '';

package/dist/handlers.js

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

package/dist/local-sessions.d.ts

@@ -20,7 +20,7 @@ export interface LocalSession {
 export interface SessionState {
     /** A process has the session open right now. */
     running: boolean;
-    /** working: a turn is in progress (never cut off); idle: between turns, or no process is running it. */
+    /** working: a turn is in progress; idle: between turns, or no process is running it. */
     turn: 'working' | 'idle';
     pid?: number;
 }
@@ -46,6 +46,12 @@ export declare function workingDirectory(recent: Rec[], fallback: string): strin
 /** Whether the transcript's last turn is still running, from its records (see the module comment). */
 export declare function claudeTurnFromRecords(records: Rec[]): 'working' | 'idle';
 export declare function codexTurnFromRecords(records: Rec[]): 'working' | 'idle';
+/** The actual writer, never a guessed PID from the transcript. Codex TUI's writer may be its shared daemon. */
+export declare function sessionProcessPid(s: Pick<LocalSession, 'harness' | 'session_id' | 'file'>, env: Env): number | undefined;
+/** The selected thread's last started turn, from its native rollout (Codex 0.160.0). */
+export declare function sessionTurnId(s: Pick<LocalSession, 'file'>): string | undefined;
+/** Re-read the registry immediately before signalling: a PID reused after a session exits belongs to someone else. */
+export declare function sameClaudeProcess(s: Pick<LocalSession, 'session_id'>, env: Env, pid: number): boolean;
 /**
  * Whether a session worked in `folder` (or below it): any working directory its records name (0.20.2+; before, only
  * the first). A session started in a scratch folder that went on in a repository is listed under the repository too.