@shardflux/cli 0.19.1 → 0.22.0

package/dist/machine-status.d.ts

@@ -0,0 +1,67 @@
+import type { AgentFilesystem } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import { type BuildQueue } from './filesystem-commands.js';
+import { type SaveFailure } from './errors.js';
+import { type SetupRecord } from './machine-setup.js';
+export type MachineRowState = 'ready' | 'saving' | 'failed' | 'none';
+/** too_large and timeout: the save's build; save_failed: any other build failure; setup_stopped: this computer's agent. */
+export type MachineFailure = 'too_large' | 'timeout' | 'save_failed' | 'setup_stopped';
+export interface MachineAction {
+    id: 'save' | 'retry' | 'setup';
+    title: 'Save again' | 'Retry' | 'Set up';
+    command: string[];
+}
+export interface MachineRow {
+    /** unknown: the check or response could not establish readiness; unavailable: the API has no machine route. */
+    state: MachineRowState | 'unknown' | 'unavailable';
+    /** The saved version in use; 0 when none is, null when the version could not be read. */
+    version: number | null;
+    /** One plain line of at most 80 characters. */
+    line: string;
+    reason?: MachineFailure;
+    /** The failure's full message. */
+    error?: string;
+    /** saving: the setup's agent (setup) or the save's build (save), with its version and place in the queue. */
+    progress?: {
+        phase: 'setup' | 'save';
+        version?: number;
+        queue?: BuildQueue;
+    };
+    action?: MachineAction;
+}
+/** `text` cut so that it and `suffix` fit one 80-character line. */
+export declare function fitLine(text: string, suffix?: string): string;
+/**
+ * A build failure as people say it: too large, out of time, or the build's own first sentence. The failure's code
+ * (0.21.1+, from an API that reports it) decides first: resource_limit is too large, named with the plan's disk when it
+ * is that limit.
+ */
+export declare function saveFailure(message: string, failure?: SaveFailure): {
+    reason: MachineFailure;
+    why: string;
+};
+/** What `machineRow` reads besides the machine: whether the failed save's VM is still there, and a build's queue. */
+export interface MachineRowFacts {
+    saveSourceExists?: boolean;
+    queue?: BuildQueue;
+}
+/** The row, from the API's machine and this computer's setup record (pure: the facts are read by `readMachineRow`). */
+export declare function machineRow(machine: AgentFilesystem, rec: SetupRecord | undefined, facts?: MachineRowFacts): MachineRow;
+/**
+ * The row for this account and computer: the machine (one API call), the setup record, and, only when they matter,
+ * whether a failed save's VM is still there and a saving build's queue. `machine` skips the first call when the caller
+ * has it.
+ */
+export declare function readMachineRow(ctx: Ctx, machine?: AgentFilesystem): Promise<MachineRow>;
+/**
+ * `setup --inspect`'s row: an API without machines reports unavailable; a check that fails says so on the row
+ * (state unknown) and never fails the report.
+ */
+export declare function inspectMachineRow(ctx: Ctx): Promise<MachineRow | null>;
+/**
+ * `machine setup --status` and a setup's result: this computer's record (runner, summary, attempts…) with the row's
+ * state and line. Saving reads as running for older apps; unknown and unavailable remain explicit.
+ */
+export declare function statusDoc(row: MachineRow, rec: SetupRecord | undefined): Record<string, unknown>;
+/** The row as the terminal shows it: its line, and for a failure or none the command that recovers it. */
+export declare function rowText(row: MachineRow): string;

package/dist/machine-status.js

@@ -0,0 +1,140 @@
+/**
+ * The account's cloud machine as one row (0.20.2+), the one source of truth that `shard machine setup --status`, `shard
+ * setup --inspect` (onboarding.machine) and a setup run's result report, and that the menu bar, the Linux app and the
+ * terminal onboarding show. The API's machine (GET /v1/machine: what is saved, saving or failed) decides; this
+ * computer's setup record (agents.json) adds only what the API cannot know: its agent is setting the machine up right
+ * now, or its last setup stopped before anything was saved.
+ *
+ * - ready: a version is saved and in use. saving: the setup's agent works, or a save builds (with its place in the
+ *   queue). failed: the newest save failed (its reason: too large, out of time, or the build's own message), or this
+ *   computer's setup stopped and no version was saved since it started. none: nothing saved and nothing under way.
+ * - A failed row has one plain line and one recovery: Save again (`shard machine save --wait`) when the save failed and
+ *   its machine VM is still there, else Retry (`shard machine setup --from-this-computer`).
+ */
+import { ShardfluxApiError, saveProgressText } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { machineSaveSource, pendingQueue } from "./filesystem-commands.js";
+import { gib, planDiskLimit } from "./errors.js";
+import { readRecord, readyLine, workingLine } from "./machine-setup.js";
+const LIMIT = 80;
+/** `text` cut so that it and `suffix` fit one 80-character line. */
+export function fitLine(text, suffix = '') {
+    const flat = text.replace(/\s+/g, ' ').trim(), room = LIMIT - suffix.length;
+    return (flat.length <= room ? flat : `${flat.slice(0, room - 1).trimEnd()}…`) + suffix;
+}
+/**
+ * A build failure as people say it: too large, out of time, or the build's own first sentence. The failure's code
+ * (0.21.1+, from an API that reports it) decides first: resource_limit is too large, named with the plan's disk when it
+ * is that limit.
+ */
+export function saveFailure(message, failure) {
+    const disk = planDiskLimit(failure);
+    if (disk)
+        return { reason: 'too_large', why: `over the plan’s ${gib(disk.limit)} disk` };
+    if (failure?.code === 'resource_limit')
+        return { reason: 'too_large', why: 'it’s too large' };
+    if (failure?.code === 'timeout')
+        return { reason: 'timeout', why: 'it ran out of time' };
+    if (/too[ _]large|exceed\w* (the |its )?(\w+ )?(max|size|limit|quota)|max_\w*bytes|disk (is )?full|no space|insufficient_disk|quota_exceeded|above the .*(GiB|MiB)/i.test(message))
+        return { reason: 'too_large', why: 'it’s too large' };
+    if (/exceeded its \d+ ?(second|s)\b|time ?out|timed out|ran past|took too long|deadline/i.test(message))
+        return { reason: 'timeout', why: 'it ran out of time' };
+    const first = message.replace(/\s+/g, ' ').trim().split(/(?<=[.!?])\s/)[0]?.replace(/[.!?]$/, '') ?? '';
+    // The API's own fallback ("Filesystem save failed. Open its build status…") adds nothing to "not saved".
+    return { reason: 'save_failed', why: /^(filesystem )?save failed$/i.test(first) ? '' : first };
+}
+const SAVE_AGAIN = { id: 'save', title: 'Save again', command: ['shard', 'machine', 'save', '--wait'] };
+const RETRY = { id: 'retry', title: 'Retry', command: ['shard', 'machine', 'setup', '--from-this-computer'] };
+const SET_UP = { id: 'setup', title: 'Set up', command: ['shard', 'machine', 'setup', '--from-this-computer'] };
+/** When the newest saved version was made (0 when none is). */
+const savedAt = (m) => Math.max(0, ...m.history.map(h => Date.parse(h.created_at)).filter(Number.isFinite));
+const inUse = (version) => (version > 0 ? ` · version ${version} stays in use` : ' · no saved version');
+/** The row, from the API's machine and this computer's setup record (pure: the facts are read by `readMachineRow`). */
+export function machineRow(machine, rec, facts = {}) {
+    const version = machine.version;
+    if (!Number.isSafeInteger(version) || version < 0)
+        return { state: 'unknown', version: null, line: 'Cloud machine readiness could not be confirmed: saved version unavailable' };
+    if (machine.state === 'building' && machine.pending) {
+        const q = facts.queue;
+        return { state: 'saving', version, line: fitLine(q ? `Saving machine v${machine.pending.version} · ${saveProgressText({ version: machine.pending.version, build_id: machine.pending.build_id, state: 'queued', queue: q })}` : `Saving machine v${machine.pending.version}…`, inUse(version)),
+            progress: { phase: 'save', version: machine.pending.version, ...(q ? { queue: q } : {}) } };
+    }
+    if (machine.state === 'building')
+        return { state: 'unknown', version, line: 'Cloud machine is saving; build progress is unavailable' };
+    if (rec?.state === 'running') {
+        return { state: 'saving', version, line: fitLine(rec.line || workingLine(rec.runner ?? 'claude')), progress: { phase: 'setup' } };
+    }
+    if (machine.state === 'failed') {
+        const message = machine.failure?.message || 'The API reported a failed save without build details.';
+        const { reason, why } = saveFailure(message, machine.failure);
+        return { state: 'failed', version, line: fitLine(`Cloud machine not saved${why ? `: ${why}` : ''}`, inUse(version)), reason, error: message,
+            action: facts.saveSourceExists === false ? RETRY : SAVE_AGAIN };
+    }
+    // A setup that stopped counts until a version is saved after it started (by its own save that outlived its wait, by
+    // Save again, or by hand).
+    const started = Date.parse(rec?.started_at ?? '');
+    if (rec?.state === 'failed' && (version === 0 || (Number.isFinite(started) && started > savedAt(machine)))) {
+        const error = rec.error ?? 'it didn’t finish';
+        return { state: 'failed', version, line: fitLine(`Cloud machine setup stopped: ${error}`, inUse(version)), reason: 'setup_stopped', error, action: RETRY };
+    }
+    if (machine.state === 'ready' && version > 0) {
+        const mine = rec?.state === 'ready' && rec.machine_version === version;
+        const line = mine ? (rec.line || (rec.summary ? readyLine(rec.summary, rec.summary.skills) : '')) : '';
+        return { state: 'ready', version, line: line ? fitLine(line, ` · version ${version}`) : `Cloud machine ready (version ${version})` };
+    }
+    if (machine.state !== 'empty' || version !== 0)
+        return { state: 'unknown', version, line: 'Cloud machine readiness could not be confirmed from this API response' };
+    return { state: 'none', version: 0, line: 'Cloud machine not set up yet', action: SET_UP };
+}
+/**
+ * The row for this account and computer: the machine (one API call), the setup record, and, only when they matter,
+ * whether a failed save's VM is still there and a saving build's queue. `machine` skips the first call when the caller
+ * has it.
+ */
+export async function readMachineRow(ctx, machine) {
+    const cloud = ctx.cloud();
+    machine ??= await cloud.machine.get({ signal: ctx.signal });
+    const rec = readRecord(new AgentStateStore(ctx.store.dir), ctx.apiUrl, machine.organization_id);
+    const facts = {};
+    if (machine.state === 'building' && machine.pending)
+        facts.queue = await pendingQueue(ctx, machine);
+    if (machine.state === 'failed' && machine.failure)
+        facts.saveSourceExists = await saveSourceExists(ctx, machine);
+    return machineRow(machine, rec, facts);
+}
+/** The VM `shard machine save` saves (machineSaveSource): Save again needs it; without it the setup runs again. */
+async function saveSourceExists(ctx, machine) {
+    try {
+        return !!(await machineSaveSource(ctx, machine));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `setup --inspect`'s row: an API without machines reports unavailable; a check that fails says so on the row
+ * (state unknown) and never fails the report.
+ */
+export async function inspectMachineRow(ctx) {
+    try {
+        return await readMachineRow(ctx);
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && (error.status === 404 || error.details?.reason === 'filesystem_unavailable'))
+            return { state: 'unavailable', version: null, line: 'This API does not report cloud machine readiness; update the server' };
+        return { state: 'unknown', version: null, line: fitLine(`Couldn’t check your cloud machine: ${error instanceof Error ? error.message : String(error)}`) };
+    }
+}
+/**
+ * `machine setup --status` and a setup's result: this computer's record (runner, summary, attempts…) with the row's
+ * state and line. Saving reads as running for older apps; unknown and unavailable remain explicit.
+ */
+export function statusDoc(row, rec) {
+    const state = row.state === 'saving' ? 'running' : row.state;
+    return { ...(rec ?? {}), state, line: state === 'none' ? null : row.line, error: row.state === 'failed' ? row.error ?? null : null,
+        machine_version: row.version, machine: row };
+}
+/** The row as the terminal shows it: its line, and for a failure or none the command that recovers it. */
+export function rowText(row) {
+    return row.action ? `${row.line}. ${row.action.title}: ${row.action.command.join(' ')}` : row.line;
+}

package/dist/main.js

@@ -12,7 +12,7 @@
  */
 import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
-import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
+import { SDK_VERSION, Shardflux, ShardfluxAccount, aboutSeconds, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, GUIDE_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
 import { launchProjectCommand } from "./conversation-terminal.js";
@@ -34,6 +34,7 @@ import { NPM_CLIENTS, npmLatestAll, npmRegistry, withRegistryLatest } from "./re
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
 import { errorText, feedbackCommand, json, time } from "./format.js";
 import { HANDLERS } from "./handlers.js";
+import { SETUP_VM_ENV, setupGuard } from "./machine-setup.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
 import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
@@ -71,10 +72,8 @@ function hintFor(info, cred, file, command = '') {
         return `keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'usage')
         return 'run "shard --help" or "shard <command> --help"';
-    if (info.code === 'filesystem_save_failed') {
-        const level = info.details?.level === 'template' ? 'template' : 'machine';
-        return `the version in use is unchanged; fix what the message names in ${level === 'machine' ? 'shard machine' : 'the project agent'}, then run shard ${level} save --wait again`;
-    }
+    if (info.code === 'filesystem_save_failed')
+        return info.fix;
     if (info.source === 'cell' && info.code === 'workspace_not_running')
         return 'open or resume the workspace first: shard workspaces open <key> --template <slug>';
     if (info.status === 401 && info.code === 'unauthenticated') {
@@ -112,6 +111,12 @@ function hintFor(info, cred, file, command = '') {
         if (quota)
             return quota;
     }
+    // 0.20.0+: builds past the plan's slots queue; only a full queue is refused (429, Retry-After).
+    if (info.code === 'rate_limited' && reasonOf(info) === 'template_build_queue_full') {
+        const queued = typeof info.details?.queued === 'number' ? info.details.queued : undefined;
+        const retry = info.retry_after_seconds ?? (typeof info.details?.retry_after_seconds === 'number' ? info.details.retry_after_seconds : undefined);
+        return `${queued ?? 'Several'} build${queued === 1 ? '' : 's'} already wait for your plan's build slots; nothing was started. Run the same command again${retry ? ` in ${aboutSeconds(retry)}` : ' when one finishes'}`;
+    }
     const policyHint = spendPolicyHint(info);
     if (policyHint)
         return policyHint;
@@ -343,6 +348,8 @@ const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
 // names the next step (upgrade, overage, the cap, the payment method), not a problem to report.
 const NO_NUDGE_CODES = new Set(['usage', 'terms_not_accepted', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended', 'allowance_exhausted']);
 const NO_NUDGE_REASONS = new Set([
+    // shard template delete with nothing saved (0.20.1+): the hint names the next step.
+    'filesystem_not_found',
     'revision_mismatch',
     'tree_revision_mismatch',
     'edit_not_found',
@@ -375,6 +382,9 @@ function nudges(info, command) {
     // A plan limit whose hint names the next step (0.9.0): busy working slots, or Retained state used up.
     if (info.code === 'quota_exceeded' && quotaHint(info) !== undefined)
         return false;
+    // A save the same VM cannot pass (0.21.1+), such as one larger than the plan's workspace disk: the hint names the fix.
+    if (info.code === 'filesystem_save_failed' && info.retryable === false)
+        return false;
     const reason = reasonOf(info);
     return !NO_NUDGE_CODES.has(info.code) && !(reason !== undefined && NO_NUDGE_REASONS.has(reason));
 }
@@ -466,12 +476,8 @@ export async function run(argv, io, opts = {}) {
         io.stdout.write(wantsJson ? json({ cli: CLI_VERSION, sdk: SDK_VERSION }) : `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`);
         return EXIT.ok;
     }
-    // shard ./ attaches Claude Code or Codex to this terminal: without one (or in a coding agent's shell) it says how to
-    // start the conversation instead of starting one nobody can see (0.17.1+: a usage error, before 0.17.1 its help).
-    if (parsed.command === PROJECT_COMMAND && !tty && !parsed.global.json) {
-        await startupHousekeeping({ io, store, signal });
-        return report(new UsageError('shard ./ opens Claude Code or Codex in a terminal, and this shell has none.', 'ask your user to run shard ./ in their own terminal, or start the conversation detached: shard ./ --json --prompt "<task>" (shard ./ codex --json ... for Codex)'));
-    }
+    // shard ./ attaches Claude Code or Codex to this terminal. Without one (or in a coding agent's shell) it opens in the
+    // person's chosen app (0.20.1+: a new tab of their terminal app, see launchProjectCommand), never one nobody can see.
     command = parsed.command.path.join(' ');
     let ctx;
     let updates = null;
@@ -678,7 +684,7 @@ export async function run(argv, io, opts = {}) {
         // `shard update` brings the app in itself; `shard update --check` (the menu bar of an app before 0.3.2 runs it every
         // 6 hours) is how such an app learns of a newer one with no action from the person.
         const updating = command === 'update' && parsed.values.check !== true;
-        if (opts.runtime && !updating && !['menubar', 'device-helper'].includes(parsed.command.path[0])) {
+        if (opts.runtime && !updating && !io.env[SETUP_VM_ENV] && !['menubar', 'device-helper'].includes(parsed.command.path[0])) {
             refreshMenubarInBackground({ dir: store.dir, home: io.env.HOME || homedir(), runtime: opts.runtime, env: { ...process.env, ...io.env } });
         }
         // The update check runs next to the command (not for `version`, which reports it itself).
@@ -712,11 +718,15 @@ export async function run(argv, io, opts = {}) {
         io.stdout.write(setupGuideText(agentSetupGuide(ctx)));
         return EXIT.ok;
     }
+    // The machine setup agent's own shard (0.20.0+): only exec, writes from standard input and reads on its machine VM.
+    const refused = setupGuard(io.env, command, parsed.values, parsed.positionals);
+    if (refused)
+        return report(new UsageError(refused));
     const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await tryLinuxDesktop(ctx) ? 0 : terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
     // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.
-    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward' && !io.env[SETUP_VM_ENV]) {
         // An updated shard restarts this computer's CLIProxyAPI forwarder on itself (a no-op unless the version changed).
         await refreshForwarderAgent(io.env, ctx.store.dir).catch(() => false);
         await housekeeping(ctx);

package/dist/move-worktrees-restore.py

@@ -0,0 +1,144 @@
+"""Restore an owned migration into an EMPTY folder; never overwrite continued work.
+
+The immutable archives retain original Git metadata. Only location pointers in the
+restored copy change. Can be run again with a new empty root for recovery.
+"""
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import shutil
+import subprocess
+import sys
+import tarfile
+
+manifest = Path(sys.argv[1]).resolve()
+plan = json.loads(manifest.read_text())
+root = Path(sys.argv[2]).absolute()
+if root.is_symlink() or (root.exists() and any(root.iterdir())):
+    raise ValueError("Restore requires a new empty folder; existing work was not replaced")
+root.mkdir(parents=True, exist_ok=True)
+
+def destination(target):
+    parts = PurePosixPath(target).parts
+    if target != "." and (target.startswith("/") or any(p in ("", "..") for p in parts)):
+        raise ValueError("Unsafe worktree destination")
+    return root if target == "." else root.joinpath(*parts)
+
+targets = {t["source"]: destination(t["target"]) for t in plan["trees"]}
+expected = plan["bytes"] + plan["files"] * 1024
+if shutil.disk_usage(root).free < expected:
+    raise ValueError(f"Restore requires at least {expected} free bytes on the target filesystem")
+
+def parents_safe(path, base):
+    parent = path.parent
+    while parent != base:
+        if parent.is_symlink():
+            raise ValueError("Archive parent is a symlink")
+        if parent == parent.parent:
+            raise ValueError("Archive escaped its root")
+        parent = parent.parent
+    if base.is_symlink():
+        raise ValueError("Archive root is a symlink")
+
+for i, tree in enumerate(plan["trees"]):
+    base = targets[tree["source"]]
+    base.mkdir(parents=True, exist_ok=True)
+    directories = []
+    with tarfile.open(manifest.parent / f"{i}.tar", "r:") as archive:
+        for member in archive:
+            parts = PurePosixPath(member.name).parts
+            if member.name in (".", "./"):
+                continue
+            if member.name.startswith("/") or any(p in ("", "..") for p in parts):
+                raise ValueError("Unsafe archive member")
+            path = base.joinpath(*parts)
+            parents_safe(path, base)
+            if member.isdir():
+                if path.is_symlink():
+                    raise ValueError("Archive directory is a symlink")
+                path.mkdir(parents=True, exist_ok=True)
+                directories.append((path, member.mode & 0o777, member.mtime))
+            elif member.issym():
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.symlink_to(member.linkname)
+            elif member.isreg() or member.islnk():
+                # Expand hard links: Git index/content is preserved, no link may escape.
+                path.parent.mkdir(parents=True, exist_ok=True)
+                with archive.extractfile(member) as src, path.open("xb") as out:
+                    shutil.copyfileobj(src, out, 1024 * 1024)
+                path.chmod(member.mode & 0o777)
+                os.utime(path, (member.mtime, member.mtime))
+            else:
+                raise ValueError("Special archive member is not supported")
+    # Read-only directory modes must be applied after writing their contents.
+    for path, mode, mtime in reversed(directories):
+        path.chmod(mode)
+        os.utime(path, (mtime, mtime))
+    for entry in tree["files"]:
+        path = base / entry["path"]
+        if "link" in entry:
+            if not path.is_symlink() or os.readlink(path) != entry["link"]:
+                raise ValueError(f"Symlink verification failed: {path}")
+            digest = hashlib.sha256(("symlink\0" + entry["link"]).encode()).hexdigest()
+        else:
+            if path.is_symlink() or not path.is_file() or path.stat().st_size != entry["size"]:
+                raise ValueError(f"File size/type verification failed: {path}")
+            sha = hashlib.sha256()
+            with path.open("rb") as src:
+                for chunk in iter(lambda: src.read(1024 * 1024), b""):
+                    sha.update(chunk)
+            digest = sha.hexdigest()
+            if path.stat().st_mode & 0o777 != entry["mode"]:
+                raise ValueError(f"File mode verification failed: {path}")
+        if digest != entry["sha256"]:
+            raise ValueError(f"File hash verification failed: {path}")
+
+common = targets[plan["main"]] / ".git"
+env = {**os.environ, "GIT_OPTIONAL_LOCKS": "0", "GIT_TERMINAL_PROMPT": "0"}
+def git(tree, *args):
+    return subprocess.run(["git", "-C", str(tree), "-c", "core.hooksPath=/dev/null", *args],
+                          env=env, check=True, stdout=subprocess.PIPE).stdout
+
+# Repair forward/back pointers without running checkout/reset or refreshing an index.
+for tree in plan["trees"]:
+    dest = targets[tree["source"]]
+    if tree["gitDir"] != plan["commonDir"]:
+        gitdir = common / Path(tree["gitDir"]).relative_to(plan["commonDir"])
+        (dest / ".git").write_text(f"gitdir: {gitdir}\n")
+        (gitdir / "gitdir").write_text(f"{dest / '.git'}\n")
+        (gitdir / "commondir").write_text(os.path.relpath(common, gitdir) + "\n")
+        worktree_config = gitdir / "config.worktree"
+        if worktree_config.exists():
+            subprocess.run(["git", "config", "--file", str(worktree_config), "core.worktree", str(dest)], check=True)
+git(targets[plan["main"]], "config", "core.worktree", str(targets[plan["main"]]))
+# External registered worktrees live in this private recovery area, outside the
+# selected checkout's tracked content. Hide only that explicit location.
+exclude = common / "info/exclude"
+exclude.parent.mkdir(parents=True, exist_ok=True)
+with exclude.open("a") as out:
+    out.write("\n/.shard/preserved-worktrees/\n")
+
+selected = targets[plan["selected"]]
+refs = git(selected, "for-each-ref", "--format=%(objectname) %(refname)").decode()
+if refs != plan["refs"]:
+    raise ValueError("Local refs did not survive migration")
+for tree in plan["trees"]:
+    dest = targets[tree["source"]]
+    if git(dest, "rev-parse", "HEAD").decode().strip() != tree["head"]:
+        raise ValueError(f"HEAD did not survive migration: {dest}")
+    status = git(dest, "status", "--porcelain=v1", "-z", "--untracked-files=all").decode()
+    if status != tree["status"]:
+        raise ValueError(f"Git status changed during migration: {dest}")
+
+# The platform tracks this conversation by its own branch; the original branch
+# and raw HEAD remain in refs/archives. Index and working bytes stay untouched.
+branch = plan["branch"]
+git(selected, "check-ref-format", branch)
+if any(line.endswith(" " + branch) for line in refs.splitlines()):
+    raise ValueError("Conversation branch collides with a preserved local ref")
+if "--defer-conversation-branch" not in sys.argv[3:]:
+    git(selected, "update-ref", branch, git(selected, "rev-parse", "HEAD").decode().strip())
+    git(selected, "symbolic-ref", "HEAD", branch)
+print(json.dumps({"worktrees": len(plan["trees"]), "files": plan["files"], "bytes": plan["bytes"],
+                  "root": str(root), "refs": len(refs.splitlines()), "status": "matched"}))

package/dist/move-worktrees.d.ts

@@ -0,0 +1,63 @@
+import type { SyncCell } from './project-sync-transfer.js';
+export interface MigrationFile {
+    path: string;
+    size: number;
+    mode: number;
+    sha256: string;
+    link?: string;
+}
+export interface MigrationTree {
+    source: string;
+    spellings: string[];
+    target: string;
+    head: string;
+    branch: string;
+    gitDir: string;
+    status: string;
+    files: MigrationFile[];
+    exclude: string[];
+}
+export interface WorktreeMigration {
+    version: 1;
+    selected: string;
+    commonDir: string;
+    main: string;
+    refs: string;
+    trees: MigrationTree[];
+    bytes: number;
+    files: number;
+    referenced: string[];
+}
+/** Git is the source of membership; sibling folders and symlink targets never expand the upload scope. */
+export declare function inspectWorktreeMigration(folder: string, transcript: Buffer, signal?: AbortSignal): Promise<WorktreeMigration | null>;
+/** Size/hash pass only after preserve-all is selected (ignored caches may be large). */
+export declare function captureWorktreeMigration(plan: WorktreeMigration, signal?: AbortSignal): Promise<void>;
+export declare function migrationScope(plan: WorktreeMigration): {
+    worktrees: {
+        path: string;
+        branch: string;
+        target: string;
+    }[];
+    referenced: string[];
+    local_refs: string[];
+    bytes: number;
+    files: number;
+    scope: string;
+    size_basis: string;
+};
+/** User refs a normal move leaves behind. Shardflux's own refs/shard/* (twin snapshots, land and agent refs) are rebuilt, never user work. */
+export declare function omittedLocalRefs(plan: WorktreeMigration): string[];
+/** Longest paths first, before replacing a parent. Message text and signed thinking keep the existing rewrite contract. */
+export declare function rewriteWorktreeTranscript(bytes: Buffer, plan: WorktreeMigration, root: string): Buffer;
+export interface MigrationResult {
+    snapshot: string;
+    bytes: number;
+    worktrees: number;
+    files: number;
+}
+/** Called instead of regular seeding: the guest starts only after its refs, index, bytes and statuses are checked. */
+export declare function preserveWorktreeMigration(cell: SyncCell, plan: WorktreeMigration, c: {
+    id: string;
+    branch: string;
+    worktree_path: string;
+}, signal?: AbortSignal): Promise<MigrationResult>;