@shardflux/cli 0.20.0 → 0.23.0

package/dist/thread-on-computer.js

@@ -20,6 +20,7 @@ import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialIm
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { ensureCodexCloud, printCloudThread, submitCloudInitialPrompt } from "./codex-cloud.js";
 import { modelChoice } from "./agent-models.js";
+import { storedTitlePrefix } from "./client-settings.js";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
 /** A conversation still bound to its computer: not ended, archived or discarded (a settled `done` turn still is). */
@@ -168,9 +169,11 @@ export async function startThreadOn(ctx, values, path, explicitApp) {
     const commit = await targetHead(ws, target, ctx.signal);
     const baseBranch = target.base_branch ?? undefined;
     await uploadInitialImages(ws.cell(), images, ctx.signal);
+    // This computer's title marker (0.20.1+); without one the thread keeps its computer's conversation's.
+    const titlePrefix = storedTitlePrefix(ctx.store.dir);
     const response = await conversationClient(ctx).conversations.create({ projectId: target.project_id, repoRemote: target.repo_remote ?? ws.labels.repo_remote ?? '',
         harness: app, route: app === 'codex' && !nativeCodex ? 'codex-cloud' : 'terminal', mode: 'join', parentId: target.id, ...(review ? { joinMode: 'reviewer' } : {}),
-        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}), ...choice }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}), ...choice, ...(titlePrefix !== undefined ? { titlePrefix } : {}) }, { idempotencyKey: randomUUID(), signal: ctx.signal });
     let c = validateConversation({ ...response.conversation, restore: response.restore });
     rememberConversation(ctx, c, project.folder, false, baseBranch);
     store.save(projectKey, app);

package/dist/update.d.ts

@@ -55,6 +55,8 @@ export interface UpdateDeps {
 /** True when nothing is behind but the menu bar app, and the app the npm package carries is already that version. */
 export declare function onlyAppToSwap(pending: Component[], packagedApp: string | null): boolean;
 export declare function update(ctx: Ctx, values: Record<string, unknown>, deps?: UpdateDeps): Promise<number>;
+/** Keep an upgrade-stable alias only when it runs this exact Node (never another version from PATH). */
+export declare function stableNodePath(node: string, env: NodeJS.ProcessEnv): string;
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
 export declare function recordInstall(dir: string, runtime: Runtime, distribution: {
     package: string;

package/dist/update.js

@@ -9,9 +9,9 @@
  * macOS) and shows the outcome from last-update.json, also when the update replaced the app that started it.
  */
 import { spawn } from 'node:child_process';
-import { closeSync, existsSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
+import { accessSync, closeSync, constants, existsSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, sep } from 'node:path';
 import { clientVersionStatus, SDK_VERSION } from '@shardflux/sdk';
 import { CLI_VERSION } from "./args.js";
 import { AgentStateStore } from "./agent-state.js";
@@ -95,9 +95,11 @@ export function displayCommand(install, specs) {
         case 'bun': return `bun add -g ${specs.join(' ')}`;
         case 'volta': return `volta install ${specs.join(' ')}`;
         case 'npx': return `npx ${specs[0]}`;
-        default: return `npm install -g ${specs.join(' ')}`;
+        default: return `npm install -g${install.manager === 'npm' && install.prefix ? ` --prefix ${shellQuote(install.prefix)}` : ''} ${specs.join(' ')}`;
     }
 }
+/** Prefixes can contain spaces, quotes or shell substitutions. The actual install still uses argv. */
+const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
 const LABELS = { shardflux: 'shardflux', '@shardflux/cli': 'shard', '@shardflux/sdk': 'SDK', [MENUBAR]: 'menu bar', [MCP]: 'MCP server' };
 /** Every local piece and its status against the catalog. */
 export async function components(ctx, install, catalog, menubar = menubarManager(ctx)) {
@@ -106,7 +108,7 @@ export async function components(ctx, install, catalog, menubar = menubarManager
         local.push(['@shardflux/cli', CLI_VERSION]);
     local.push(['@shardflux/sdk', SDK_VERSION]);
     if (menubar.platform === 'darwin') {
-        const status = await menubar.status().catch(() => null);
+        const status = await menubar.status(ctx.store.dir).catch(() => null);
         if (status?.installed && status.version)
             local.push([MENUBAR, status.version]);
     }
@@ -225,12 +227,18 @@ export async function update(ctx, values, deps = {}) {
         const result = await run(argv, env, ctx.signal);
         if (result.code !== 0) {
             const denied = /\bEACCES\b|\bEPERM\b/.test(result.output);
-            const fix = denied ? `sudo ${command}` : command;
+            const home = ctx.io.env.HOME || homedir();
+            const userPrefix = join(home, '.local');
+            const recoverNpm = denied && install.manager === 'npm';
+            const fix = recoverNpm ? displayCommand({ ...install, prefix: userPrefix }, specs) : command;
             const message = denied
                 ? `${install.manager} cannot write to ${install.prefix ?? install.root}.`
                 : `${install.manager} failed: ${result.output.trim().split('\n').slice(-3).join(' ').slice(0, 400)}`;
             writeLastUpdate(ctx.store.dir, { status: 'failed', changes: [], message, command: fix });
-            throw new CodedError(denied ? 'update_permission_denied' : 'update_failed', message, `run: ${fix}`);
+            const hint = recoverNpm
+                ? `run: ${fix}; then use ${shellQuote(join(userPrefix, 'bin', 'shard'))} instead of the old global shard. This leaves npm config and PATH unchanged.`
+                : `run: ${fix}`;
+            throw new CodedError(denied ? 'update_permission_denied' : 'update_failed', message, hint);
         }
         // The new shard reports what is installed now.
         const after = await run([runtime.node, runtime.script, 'version', '--json'], { ...env, SHARDFLUX_NO_UPDATE_CHECK: '1' }, ctx.signal);
@@ -284,7 +292,7 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
         return { status: 'off' };
     if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
         return { status: 'off' };
-    const before = await menubar.status().catch(() => null);
+    const before = await menubar.status(ctx.store.dir).catch(() => null);
     if (!before?.installed)
         return { status: 'off' };
     if (runtime && run && env) {
@@ -298,9 +306,35 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
             return { status: 'current' };
         await menubar.start(ctx.store.dir, ctx.apiUrl);
     }
-    const after = await menubar.status().catch(() => null);
+    const after = await menubar.status(ctx.store.dir).catch(() => null);
     return after?.version && after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
 }
+/** Keep an upgrade-stable alias only when it runs this exact Node (never another version from PATH). */
+export function stableNodePath(node, env) {
+    let real;
+    try {
+        real = realpathSync(node);
+    }
+    catch {
+        return node;
+    }
+    const candidates = (env.PATH ?? '').split(':').filter(isAbsolute).map(dir => join(dir, 'node'));
+    // Homebrew's opt link also works when launchd's PATH has no Homebrew entry (including versioned formulae).
+    const brew = /^(.*)\/Cellar\/(node(?:@[^/]+)?)\/[^/]+\/bin\/node$/.exec(node);
+    if (brew)
+        candidates.push(join(brew[1], 'opt', brew[2], 'bin/node'), join(brew[1], 'bin/node'));
+    for (const candidate of candidates) {
+        try {
+            if (candidate.includes('/Cellar/'))
+                continue;
+            accessSync(candidate, constants.X_OK);
+            if (realpathSync(candidate) === real)
+                return candidate;
+        }
+        catch { /* missing alias: try the next one */ }
+    }
+    return node;
+}
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
 export function recordInstall(dir, runtime, distribution, env = {}) {
     let script = runtime.script;
@@ -328,7 +362,7 @@ export function recordInstall(dir, runtime, distribution, env = {}) {
     catch {
         menubarApp = null;
     }
-    const doc = { version: 1, node: runtime.node, script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION, ...(menubarApp ? { menubar_app: menubarApp } : {}) };
+    const doc = { version: 1, node: stableNodePath(runtime.node, env), script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION, ...(menubarApp ? { menubar_app: menubarApp } : {}) };
     const text = `${JSON.stringify(doc, null, 2)}\n`;
     try {
         if (readFileSync(join(dir, INSTALL_FILE), 'utf8') === text)

package/dist/worktree-twin.d.ts

@@ -1,5 +1,6 @@
 import type { CellClient } from '@shardflux/sdk';
 import { AgentStateStore } from './agent-state.js';
+import type { OutsideFile } from './large-media.js';
 /** A file the landing rewrites must be untouched this long first. */
 export declare const QUIET_MS = 2000;
 export declare const HUB_PATH = "/shardflux/project/git/hub.git";
@@ -49,10 +50,12 @@ export interface Snapshot {
     root: string;
     id: string;
     headTree: string;
+    /** Large untracked media left out of the tree (large-media.ts): a start carries them as files beside it (0.22.0+). */
+    outside: OutsideFile[];
 }
 /**
- * One snapshot commit of the worktree's working state (what `git add -A` sees, any file size; `.shard/` left out),
- * first parent HEAD. Kept as refs/shard/twin/<worktree id>; an unchanged state reuses it.
+ * One snapshot commit of the worktree's working state (what `git add -A` sees, any file size; `.shard/` and large
+ * untracked media left out), first parent HEAD. Kept as refs/shard/twin/<worktree id>; an unchanged state reuses it.
  */
 export declare function snapshotWorktree(info: WorktreeInfo, options: {
     device: string;
@@ -247,6 +250,8 @@ export interface TwinConversationState {
     seed?: string;
     seed_snapshot?: boolean;
     folder?: string;
+    /** Large untracked media the seed snapshot left out (large-media.ts): the copy seed's VM repository ignores them. */
+    outside?: string[];
     upto?: string;
     tip?: string;
     landed_revision?: string;
@@ -282,6 +287,7 @@ export declare function deviceId(stateDir: string): string;
 export interface TwinSeed {
     commit: string;
     snapshot: boolean;
+    outside?: OutsideFile[];
 }
 /**
  * The commit a new conversation starts from: HEAD when the worktree is clean (or landing is off, or the user's Git
@@ -306,4 +312,6 @@ export declare function twinCheckoutArgv(stateDir: string, conversation: {
     base_commit: string;
     worktree_path: string;
 }): string[];
+/** A gitignore line matching exactly this path from the worktree root (prepared-repository.py exclude_pattern). */
+export declare function excludePattern(path: string): string;
 export {};

package/dist/worktree-twin.js

@@ -18,6 +18,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { AgentStateStore } from "./agent-state.js";
 import { readSyncFileTo, writeSyncFileFrom } from "./project-sync-transfer.js";
+import { largeUntrackedMedia, outsideSpecs } from "./large-media.js";
 /** A file the landing rewrites must be untouched this long first. */
 export const QUIET_MS = 2000;
 export const HUB_PATH = '/shardflux/project/git/hub.git';
@@ -108,8 +109,8 @@ export const hubTwinRef = (device, id) => `refs/shard/twin/${device}/${id}`;
 const identity = (now) => ({ GIT_AUTHOR_NAME: 'Shardflux', GIT_AUTHOR_EMAIL: 'twin@shardflux.dev', GIT_COMMITTER_NAME: 'Shardflux', GIT_COMMITTER_EMAIL: 'twin@shardflux.dev',
     GIT_AUTHOR_DATE: `@${Math.floor(now.getTime() / 1000)} +0000`, GIT_COMMITTER_DATE: `@${Math.floor(now.getTime() / 1000)} +0000` });
 /**
- * One snapshot commit of the worktree's working state (what `git add -A` sees, any file size; `.shard/` left out),
- * first parent HEAD. Kept as refs/shard/twin/<worktree id>; an unchanged state reuses it.
+ * One snapshot commit of the worktree's working state (what `git add -A` sees, any file size; `.shard/` and large
+ * untracked media left out), first parent HEAD. Kept as refs/shard/twin/<worktree id>; an unchanged state reuses it.
  */
 export async function snapshotWorktree(info, options) {
     if (!info.head)
@@ -130,8 +131,10 @@ export async function snapshotWorktree(info, options) {
         }
         else
             await git(info.root, ['read-tree', info.head], { env, signal });
-        // Every file, whatever its size: Git stores large files as streamed loose objects.
-        const specs = ['.', ':(exclude).shard', ':(exclude,glob)**/.shard/**', ':(exclude,glob)**/*.shard-tmp-*'];
+        // Every file, whatever its size (Git stores large files as streamed loose objects), except untracked media: hashing
+        // and storing those cost seconds per snapshot (617 MB of media: 13.4 s), and they are not the user's code.
+        const outside = await largeUntrackedMedia(info.root, options.stateDir, id, signal);
+        const specs = ['.', ':(exclude).shard', ':(exclude,glob)**/.shard/**', ':(exclude,glob)**/*.shard-tmp-*', ...outsideSpecs(outside)];
         await git(info.root, ['add', '-A', '--ignore-errors', '--pathspec-from-file=-', '--pathspec-file-nul'], { env, input: specs.join('\0') + '\0', signal });
         const tree = await gitText(info.root, ['write-tree'], { env, signal });
         const headTree = await gitText(info.root, ['rev-parse', `${info.head}^{tree}`], { signal });
@@ -147,7 +150,7 @@ export async function snapshotWorktree(info, options) {
             commit = await gitText(info.root, ['commit-tree', tree, '-p', info.head, '-F', '-'], { env: identity(options.now ?? new Date()), input: message, signal });
             await git(info.root, ['update-ref', twinRef(id), commit], { signal });
         }
-        return { commit, tree, base: info.head, branch: info.branch, root: info.root, id, headTree };
+        return { commit, tree, base: info.head, branch: info.branch, root: info.root, id, headTree, outside };
     }
     finally {
         rmSync(index, { force: true });
@@ -162,7 +165,7 @@ export async function refTwin(repo, branch, device, now = new Date()) {
     const id = createHash('sha256').update(`${realpathSync(repo)}\0${branch}`).digest('hex').slice(0, 16);
     const commit = await gitText(repo, ['commit-tree', tree, '-p', base, '-F', '-'], { env: identity(now), input: `Shardflux twin of ${branch}\n\n${SNAPSHOT_TRAILER}: ${device}/${id}\nShardflux-Branch: ${branch}\n` });
     await git(repo, ['update-ref', twinRef(id), commit]);
-    return { commit, tree, base, branch, root: realpathSync(repo), id, headTree: tree };
+    return { commit, tree, base, branch, root: realpathSync(repo), id, headTree: tree, outside: [] };
 }
 async function rawDiff(cwd, a, b) {
     const parts = (await git(cwd, ['diff-tree', '-r', '-z', '--raw', '--no-renames', '--no-abbrev', a, b])).stdout.toString('utf8').split('\0');
@@ -771,10 +774,11 @@ export async function twinSeed(stateDir, folder, head, project) {
     if (info.head !== head || pauseReason(info))
         return { commit: head, snapshot: false };
     const snap = await snapshotWorktree(info, { device: deviceId(stateDir), stateDir });
-    return snap.tree === snap.headTree ? { commit: head, snapshot: false } : { commit: snap.commit, snapshot: true };
+    return snap.tree === snap.headTree ? { commit: head, snapshot: false, outside: snap.outside } : { commit: snap.commit, snapshot: true, outside: snap.outside };
 }
 export function rememberTwinSeed(stateDir, conversation, folder, seed, branch) {
-    new TwinLedger(stateDir).patch(conversation, { seed: seed.commit, seed_snapshot: seed.snapshot, folder, ...(branch ? { base_branch: branch } : {}) });
+    new TwinLedger(stateDir).patch(conversation, { seed: seed.commit, seed_snapshot: seed.snapshot, folder, ...(branch ? { base_branch: branch } : {}),
+        ...(seed.outside?.length ? { outside: seed.outside.map(f => f.path) } : {}) });
 }
 /** Carries a snapshot seed into the conversation's VM repository (one small bundle: the snapshot over HEAD). */
 export async function sendTwinSeed(stateDir, cell, conversation, folder, signal) {
@@ -804,5 +808,19 @@ export function twinCheckoutArgv(stateDir, conversation) {
     const state = new TwinLedger(stateDir).conversation(conversation.id);
     if (!state.seed_snapshot || state.seed !== conversation.base_commit)
         return ['git', '-C', conversation.worktree_path, 'checkout', '-B', conversation.branch, conversation.base_commit];
-    return ['sh', '-c', 'set -e; git -C "$1" checkout -q -B "$2" HEAD; git -C "$1" reset -q --mixed "$3"', 'shard-seed', conversation.worktree_path, conversation.branch, conversation.base_commit];
+    // The copy seed copied the large media the snapshot left out: its Git ignores them too, as the user's sees them
+    // (untracked), so an agent never commits them and landing never meets them (0.22.0+).
+    const ignore = state.outside?.length ? `${EXCLUDE_BEGIN}\n${state.outside.map(excludePattern).join('\n')}\n${EXCLUDE_END}\n` : '';
+    return ['sh', '-c', 'set -e; git -C "$1" checkout -q -B "$2" HEAD; git -C "$1" reset -q --mixed "$3"; if [ -n "$4" ]; then printf %s "$4" >> "$1/.git/info/exclude"; fi',
+        'shard-seed', conversation.worktree_path, conversation.branch, conversation.base_commit, ignore];
+}
+/** The block prepared-repository.py writes for the same files (EXCLUDE_BEGIN/END, exclude_pattern). */
+const EXCLUDE_BEGIN = '# shardflux: large files outside the snapshot (begin)', EXCLUDE_END = '# shardflux: (end)';
+/** A gitignore line matching exactly this path from the worktree root (prepared-repository.py exclude_pattern). */
+export function excludePattern(path) {
+    let s = [...path].map(c => '\\*?['.includes(c) ? `\\${c}` : c).join('');
+    if (s.startsWith('!') || s.startsWith('#'))
+        s = `\\${s}`;
+    const stripped = s.replace(/ +$/, '');
+    return `/${stripped}${'\\ '.repeat(s.length - stripped.length)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.20.0",
+  "version": "0.23.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.25.1"
+    "@shardflux/sdk": "^0.27.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,9 +58,9 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-linux-x64": "0.1.5",
-    "@shardflux/desktop-linux-arm64": "0.1.5",
-    "@shardflux/menubar-darwin": "^0.8.0"
+    "@shardflux/desktop-linux-x64": "0.1.10",
+    "@shardflux/desktop-linux-arm64": "0.1.10",
+    "@shardflux/menubar-darwin": "^0.8.5"
   },
   "scripts": {
     "build": "node scripts/build.mjs",