summer-engine 2.3.0 → 2.6.0

package/dist/lib/async-op-lifecycle.js

@@ -0,0 +1,83 @@
+/**
+ * 0.5.34 Block E — async tool-lifecycle consumer for the CLI/MCP.
+ *
+ * Ported from the web orchestrator (publicsummerengine
+ * src/lib/bridge/async-op-lifecycle.ts) so the CLI speaks the SAME contract as
+ * the engine's responsive tool server (Block E):
+ *   - NEW path: `202 {requestId, status:"queued"}` -> long-poll
+ *     GET /api/ops/result?requestId=&wait=ms until terminal (done|failed|canceled).
+ *   - LEGACY path (dormant/older engine): a synchronous `200` with the full apply
+ *     result, exactly as before.
+ *
+ * It inspects the RESPONSE (status/body), not a flag, so it stays compatible with
+ * both an async and a synchronous engine. Pure + dependency-injected (now/sleep/
+ * pollOnce) so it is unit-tested without HTTP.
+ */
+const TERMINAL_STATUSES = new Set(["done", "failed", "canceled"]);
+export function isTerminalStatus(status) {
+    return status != null && TERMINAL_STATUSES.has(status);
+}
+/**
+ * Decide whether a POST /api/ops (or GET /api/snapshot/*) response is the new
+ * async ack (`202`) or the legacy synchronous result (`200`). Inspecting the HTTP
+ * status (not a flag) is what keeps this compatible with both engines.
+ */
+export function classifyOpsResponse(httpStatus, body) {
+    const b = (body ?? {});
+    const looksQueued = b.accepted === true && b.status === "queued" && typeof b.requestId === "string";
+    if (httpStatus === 202 || looksQueued) {
+        return { mode: "queued", requestId: String(b.requestId ?? "") };
+    }
+    return { mode: "legacy", legacyResult: body };
+}
+const TIMED_OUT_RESULT = {
+    status: "error",
+    error: "Tool timeout - Summer Engine may be unresponsive",
+    terminalState: "timed_out",
+    errorClass: "transient",
+};
+/**
+ * Drive an async op to a terminal result by polling. `pollOnce(waitMs)` performs
+ * one GET /api/ops/result (long-poll up to waitMs). Returns the engine's apply
+ * dict with terminalState/errorClass/appliedSeq merged on top, or a synthetic
+ * `timed_out` result if the budget is exhausted.
+ */
+export async function pollOpToTerminal(pollOnce, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const pollWaitMs = opts.pollWaitMs ?? 5000;
+    const pacingMs = opts.pacingMs ?? 250;
+    const noProgressMs = opts.noProgressTimeoutMs ?? opts.totalTimeoutMs;
+    const start = now();
+    let lastAdvanceAt = start;
+    let lastStatus;
+    let lastSeq = -1;
+    let lastProgress = "";
+    for (;;) {
+        const env = await pollOnce(pollWaitMs);
+        if (isTerminalStatus(env.status)) {
+            const out = { ...(env.result ?? {}) };
+            if (env.terminalState)
+                out.terminalState = env.terminalState;
+            if (env.errorClass)
+                out.errorClass = env.errorClass;
+            if (env.appliedSeq != null)
+                out.appliedSeq = env.appliedSeq;
+            return out;
+        }
+        const progressJson = env.progress != null ? JSON.stringify(env.progress) : "";
+        const seq = env.appliedSeq ?? -1;
+        const advanced = env.status !== lastStatus || seq !== lastSeq || progressJson !== lastProgress;
+        const t = now();
+        if (advanced) {
+            lastAdvanceAt = t;
+            lastStatus = env.status;
+            lastSeq = seq;
+            lastProgress = progressJson;
+        }
+        if (t - start >= opts.totalTimeoutMs || t - lastAdvanceAt >= noProgressMs) {
+            return { ...TIMED_OUT_RESULT };
+        }
+        await sleep(pacingMs);
+    }
+}

package/dist/lib/auth.d.ts

@@ -1,6 +1,8 @@
 export declare function getSummerDir(): string;
 export declare function getAuthToken(): Promise<string | null>;
 export declare function saveAuthToken(token: string): Promise<void>;
+export declare function getCloudToken(): Promise<string | null>;
+export declare function saveCloudToken(token: string): Promise<void>;
 export declare function getUserInfo(): Promise<{
     id: string;
     email: string;

package/dist/lib/auth.js

@@ -24,6 +24,19 @@ export async function saveAuthToken(token) {
     await ensureSummerDir();
     await writeFile(join(SUMMER_DIR, "auth-token"), token, { encoding: "utf-8", mode: 0o600 });
 }
+export async function getCloudToken() {
+    try {
+        const token = await readFile(join(SUMMER_DIR, "cloud-token"), "utf-8");
+        return token.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCloudToken(token) {
+    await ensureSummerDir();
+    await writeFile(join(SUMMER_DIR, "cloud-token"), token, { encoding: "utf-8", mode: 0o600 });
+}
 export async function getUserInfo() {
     try {
         const data = await readFile(join(SUMMER_DIR, "user.json"), "utf-8");

package/dist/lib/cloud/api.d.ts

@@ -0,0 +1,79 @@
+import type { CloudManifest } from "./types.js";
+export declare class CloudApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+export interface PresignedBlob {
+    sha256: string;
+    status: "exists" | "upload" | "quota_exceeded" | "too_large";
+    uploadId?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    message?: string;
+}
+export interface RemoteManifest {
+    version: number;
+    rulesVersion: number;
+    manifest: CloudManifest;
+}
+/**
+ * Every server interaction goes through this interface so tests can run the
+ * full sync pipeline against an in-memory double (no network, no server).
+ */
+export interface CloudApi {
+    createCloudProject(body: {
+        projectId: string;
+    } | {
+        name: string;
+    }): Promise<{
+        projectId: string;
+        headVersion: number;
+    }>;
+    getCloudProject(projectId: string): Promise<{
+        projectId: string;
+        headVersion: number;
+        rulesVersion: number;
+    }>;
+    checkBlobs(projectId: string, hashes: string[]): Promise<{
+        missing: string[];
+    }>;
+    presignBlobs(projectId: string, blobs: Array<{
+        sha256: string;
+        size: number;
+    }>): Promise<{
+        blobs: PresignedBlob[];
+    }>;
+    completeBlobs(projectId: string, uploads: Array<{
+        sha256: string;
+        uploadId: string;
+    }>): Promise<{
+        uploads: Array<{
+            sha256: string;
+            status: string;
+        }>;
+    }>;
+    presignGet(projectId: string, hashes: string[]): Promise<{
+        urls: Record<string, string>;
+        missing: string[];
+    }>;
+    getManifest(projectId: string, version?: number): Promise<RemoteManifest>;
+    commitManifest(projectId: string, body: {
+        baseVersion: number;
+        manifestSha256: string;
+        syncId: string;
+        rulesVersion: number;
+    }): Promise<{
+        version: number;
+    }>;
+    restoreVersion(projectId: string, body: {
+        toVersion: number;
+        baseVersion: number;
+        syncId: string;
+    }): Promise<{
+        version: number;
+    }>;
+}
+export declare function getCloudApi(): CloudApi;
+export declare function setCloudApiForTests(api: CloudApi | null): void;

package/dist/lib/cloud/api.js

@@ -0,0 +1,107 @@
+import { getCloudToken } from "../auth.js";
+import { parseManifest } from "./manifest.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+export class CloudApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+async function cloudFetch(path, init = {}) {
+    const token = await getCloudToken();
+    if (!token) {
+        throw new CloudApiError(401, "unauthorized", "Run: summer login");
+    }
+    const res = await fetch(`${GATEWAY_URL}${path}`, {
+        ...init,
+        headers: {
+            ...(init.body ? { "content-type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+            authorization: `Bearer ${token}`,
+        },
+    });
+    if (!res.ok) {
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            // ignore
+        }
+        const error = body?.error ?? {};
+        throw new CloudApiError(res.status, error.code ?? "request_failed", error.message ?? `Cloud request failed (${res.status})`, error);
+    }
+    return (await res.json());
+}
+const realCloudApi = {
+    async createCloudProject(body) {
+        return cloudFetch("/api/cloud/projects", { method: "POST", body: JSON.stringify(body) });
+    },
+    async getCloudProject(projectId) {
+        return cloudFetch(`/api/cloud/projects/${projectId}`);
+    },
+    async checkBlobs(projectId, hashes) {
+        return cloudFetch("/api/cloud/blobs/check", {
+            method: "POST",
+            body: JSON.stringify({ projectId, hashes }),
+        });
+    },
+    async presignBlobs(projectId, blobs) {
+        return cloudFetch("/api/cloud/blobs/presign", {
+            method: "POST",
+            body: JSON.stringify({ projectId, blobs }),
+        });
+    },
+    async completeBlobs(projectId, uploads) {
+        return cloudFetch("/api/cloud/blobs/complete", {
+            method: "POST",
+            body: JSON.stringify({ projectId, uploads }),
+        });
+    },
+    async presignGet(projectId, hashes) {
+        return cloudFetch("/api/cloud/blobs/presign-get", {
+            method: "POST",
+            body: JSON.stringify({ projectId, hashes }),
+        });
+    },
+    async getManifest(projectId, version) {
+        const suffix = version !== undefined ? `?version=${version}` : "";
+        const meta = await cloudFetch(`/api/cloud/projects/${projectId}/manifest${suffix}`);
+        if (meta.version === 0) {
+            return {
+                version: 0,
+                rulesVersion: meta.rulesVersion ?? 1,
+                manifest: { schemaVersion: 1, projectId, rulesVersion: meta.rulesVersion ?? 1, files: {} },
+            };
+        }
+        const res = await fetch(meta.url);
+        if (!res.ok)
+            throw new CloudApiError(res.status, "manifest_download_failed", "Could not download manifest");
+        const bytes = Buffer.from(await res.arrayBuffer());
+        return { version: meta.version, rulesVersion: meta.rulesVersion, manifest: parseManifest(bytes, projectId) };
+    },
+    async commitManifest(projectId, body) {
+        return cloudFetch(`/api/cloud/projects/${projectId}/commit`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    },
+    async restoreVersion(projectId, body) {
+        return cloudFetch(`/api/cloud/projects/${projectId}/restore-version`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    },
+};
+let activeApi = realCloudApi;
+export function getCloudApi() {
+    return activeApi;
+}
+export function setCloudApiForTests(api) {
+    activeApi = api ?? realCloudApi;
+}

package/dist/lib/cloud/apply.d.ts

@@ -0,0 +1,32 @@
+import type { ConflictSetWriter } from "./conflicts.js";
+import type { DiffPlan } from "./diff.js";
+import type { CloudManifest, LocalFileStat } from "./types.js";
+export interface ApplyContext {
+    /** Staged blob path per sha256 (downloaded and hash-verified). */
+    staged: Map<string, string>;
+    /** Actual on-disk byte-name path per NFC manifest key (from the walk). */
+    diskPathByKey: Map<string, string>;
+    /** Pre-image stats captured at hash time for the apply-time stat check. */
+    statByKey: Map<string, LocalFileStat>;
+    /** Conflict set writer; losing bytes are preserved through it. */
+    conflicts: ConflictSetWriter;
+    /** Base manifest (for the project.godot 3-way merge). */
+    base: CloudManifest | null;
+    /** Called once before the first destructive apply (modify or delete). */
+    onBeforeDestructive: () => Promise<void>;
+}
+export interface ApplyResult {
+    /** Paths written or deleted on disk (for the engine rescan). */
+    appliedPaths: string[];
+    notices: string[];
+    /** Local hashes preserved as conflict losers (pushed to R2 by the caller). */
+    preservedLocalHashes: Map<string, string>;
+}
+/**
+ * Two-phase pull, phase 2 (spec 8.7). Fixed order: renames first (case-only
+ * renames as two-step), then writes (project.godot and *.tscn last), then
+ * deletes. Every write is an atomic rename from staging; every modify or
+ * delete is preceded by exactly one full-tree checkpoint and a pre-image
+ * stat check that routes drifted files to conflicts instead of overwriting.
+ */
+export declare function applyRemotePlan(projectRoot: string, plan: DiffPlan, remote: CloudManifest, context: ApplyContext): Promise<ApplyResult>;

package/dist/lib/cloud/apply.js

@@ -0,0 +1,294 @@
+import { chmod, copyFile, lstat, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { basename, dirname, join } from "path";
+import { containedProjectPath } from "./containment.js";
+import { mergeProjectGodot } from "./project-godot-merge.js";
+import { casefoldKey } from "./validate-path.js";
+const RENAME_RETRIES = 7;
+const RENAME_BACKOFF_MS = 50;
+/**
+ * Two-phase pull, phase 2 (spec 8.7). Fixed order: renames first (case-only
+ * renames as two-step), then writes (project.godot and *.tscn last), then
+ * deletes. Every write is an atomic rename from staging; every modify or
+ * delete is preceded by exactly one full-tree checkpoint and a pre-image
+ * stat check that routes drifted files to conflicts instead of overwriting.
+ */
+export async function applyRemotePlan(projectRoot, plan, remote, context) {
+    const result = { appliedPaths: [], notices: [], preservedLocalHashes: new Map() };
+    const decisionByPath = new Map(plan.decisions.map((d) => [d.path, d]));
+    let writes = [...plan.pullPaths, ...plan.conflictPaths].filter((path) => remote.files[path]);
+    let deletes = [...plan.deleteLocalPaths];
+    if (!writes.length && !deletes.length)
+        return result;
+    // Checkpoint before ANY destructive apply (spec 11): a modify of an
+    // existing file or a delete.
+    let checkpointed = false;
+    const ensureCheckpoint = async () => {
+        if (checkpointed)
+            return;
+        checkpointed = true;
+        await context.onBeforeDestructive();
+    };
+    for (const path of writes) {
+        if (await pathExistsOnDisk(projectRoot, path, context)) {
+            await ensureCheckpoint();
+            break;
+        }
+    }
+    if (!checkpointed && deletes.length)
+        await ensureCheckpoint();
+    // Phase: renames. A delete-local plus pull pair with the same content hash
+    // and casefold-equal keys is a case-only rename, executed as a two-step
+    // rename so case-insensitive volumes never lose the file (spec 8.7).
+    const renamed = await applyCaseOnlyRenames(projectRoot, plan, remote, context, decisionByPath, result);
+    writes = writes.filter((path) => !renamed.has(path));
+    deletes = deletes.filter((path) => !renamed.has(path));
+    // Phase: writes, with project.godot and *.tscn last so a partially
+    // hydrated project is never scanned with dangling scene dependencies.
+    const stagedUseCount = new Map();
+    for (const path of writes) {
+        const hash = remote.files[path].sha256;
+        stagedUseCount.set(hash, (stagedUseCount.get(hash) ?? 0) + 1);
+    }
+    writes.sort((a, b) => writeOrderRank(a) - writeOrderRank(b) || (a < b ? -1 : a > b ? 1 : 0));
+    for (const path of writes) {
+        const decision = decisionByPath.get(path);
+        const remoteFile = remote.files[path];
+        const isConflict = plan.conflictPaths.includes(path);
+        // Pre-image stat check (spec 8.7): a file that changed between diff and
+        // apply is routed to conflicts instead of being blindly overwritten.
+        const drifted = await driftedSinceDiff(projectRoot, path, context);
+        if (isConflict || drifted) {
+            await preserveLoser(projectRoot, path, decision, remoteFile.sha256, context, result, drifted && !isConflict);
+        }
+        if (path === "project.godot" && isConflict) {
+            const merged = await mergeProjectGodotFromContext(projectRoot, path, decision, remote, context, result);
+            if (merged) {
+                result.appliedPaths.push(path);
+                continue;
+            }
+        }
+        const stagedPath = context.staged.get(remoteFile.sha256);
+        if (!stagedPath)
+            throw new Error(`Missing staged blob for ${path} (${remoteFile.sha256})`);
+        const remaining = stagedUseCount.get(remoteFile.sha256) - 1;
+        stagedUseCount.set(remoteFile.sha256, remaining);
+        await placeFromStaging(projectRoot, path, stagedPath, remaining > 0, context);
+        result.appliedPaths.push(path);
+    }
+    // Phase: deletes.
+    const survivingFold = new Map();
+    for (const key of Object.keys(remote.files))
+        survivingFold.set(casefoldKey(key), key);
+    for (const path of deletes) {
+        const decision = decisionByPath.get(path);
+        const onDisk = context.diskPathByKey.get(path) ?? join(projectRoot, path);
+        // Pre-image check: a delete target edited since the diff is row 14 now
+        // (edit beats delete); keep the local file and surface it.
+        if (await driftedSinceDiff(projectRoot, path, context)) {
+            result.notices.push(`${path}: changed during sync; kept local file (edit beats delete)`);
+            continue;
+        }
+        // Inode-gated casefold skip (spec 8.7): a delete whose casefolded path
+        // equals a surviving manifest key is skipped only when a samefile check
+        // proves both names map to one on-disk file.
+        const survivor = survivingFold.get(casefoldKey(path));
+        if (survivor && survivor !== path) {
+            if (await isSameFile(onDisk, join(projectRoot, survivor))) {
+                continue;
+            }
+        }
+        if (decision?.local?.sha256) {
+            result.preservedLocalHashes.set(decision.local.sha256, onDisk);
+        }
+        await rm(onDisk, { force: true });
+        result.appliedPaths.push(path);
+    }
+    for (const path of plan.keepLocalPaths) {
+        result.notices.push(`${path}: deleted in cloud but edited here; keeping local file (edit beats delete)`);
+    }
+    for (const path of plan.restoredRemotePaths) {
+        result.notices.push(`${path}: deleted here but edited in cloud; restored the cloud file (edit beats delete)`);
+    }
+    return result;
+}
+function writeOrderRank(path) {
+    if (path === "project.godot")
+        return 2;
+    if (path.endsWith(".tscn"))
+        return 1;
+    return 0;
+}
+async function pathExistsOnDisk(projectRoot, path, context) {
+    const onDisk = context.diskPathByKey.get(path) ?? join(projectRoot, path);
+    try {
+        await lstat(onDisk);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function driftedSinceDiff(projectRoot, path, context) {
+    const recorded = context.statByKey.get(path);
+    if (!recorded)
+        return false;
+    const onDisk = context.diskPathByKey.get(path) ?? join(projectRoot, path);
+    try {
+        const info = await lstat(onDisk, { bigint: true });
+        return Number(info.size) !== recorded.size || info.mtimeNs.toString() !== recorded.mtimeNs;
+    }
+    catch {
+        return false; // Gone since the diff; nothing to preserve.
+    }
+}
+async function preserveLoser(projectRoot, path, decision, remoteSha256, context, result, drifted) {
+    const onDisk = context.diskPathByKey.get(path) ?? join(projectRoot, path);
+    const localSha = decision?.local?.sha256;
+    const preserved = await context.conflicts.preserve(path, {
+        localSha256: localSha,
+        remoteSha256,
+        winner: "remote",
+        note: drifted ? "changed between diff and apply" : undefined,
+    }, onDisk);
+    if (preserved) {
+        if (localSha)
+            result.preservedLocalHashes.set(localSha, join(context.conflicts.setDir, path));
+        result.notices.push(`${path}: cloud version won; your bytes are preserved (summer cloud conflicts restore ${path})`);
+        // Sidecar bytes ride inside the conflict set for reference, never as a
+        // second conflict copy in the scanned tree (spec 8.4).
+        for (const suffix of [".import", ".uid"]) {
+            const sidecar = `${path}${suffix}`;
+            const sidecarOnDisk = context.diskPathByKey.get(sidecar) ?? join(projectRoot, sidecar);
+            await context.conflicts.preserve(sidecar, { winner: "remote", sidecar: true }, sidecarOnDisk);
+        }
+    }
+}
+async function mergeProjectGodotFromContext(projectRoot, path, decision, remote, context, result) {
+    const baseHash = context.base?.files[path]?.sha256;
+    const baseStaged = baseHash ? context.staged.get(baseHash) : undefined;
+    const remoteStaged = context.staged.get(remote.files[path].sha256);
+    const onDisk = context.diskPathByKey.get(path) ?? join(projectRoot, path);
+    if (!remoteStaged)
+        return false;
+    let baseText = "";
+    let localText = "";
+    let remoteText = "";
+    try {
+        baseText = baseStaged ? await readFile(baseStaged, "utf8") : "";
+        localText = await readFile(onDisk, "utf8");
+        remoteText = await readFile(remoteStaged, "utf8");
+    }
+    catch {
+        return false; // Fall through to whole-file remote-wins via the caller.
+    }
+    const merged = mergeProjectGodot(baseText, localText, remoteText);
+    if (merged.fallback) {
+        result.notices.push("project.godot: could not parse all three versions; cloud file won whole-file, local copy preserved");
+        return false;
+    }
+    for (const losing of merged.losingValues) {
+        const where = losing.section ? `[${losing.section}] ` : "";
+        result.notices.push(`project.godot: ${where}${losing.key}: cloud value won; local value was: ${losing.localValue}`);
+    }
+    const target = await containedProjectPath(projectRoot, path);
+    const tmp = join(dirname(target), `.${basename(target)}.summer-cloud-tmp`);
+    await writeFile(tmp, merged.merged, "utf8");
+    await renameWithRetry(tmp, target);
+    return true;
+}
+/**
+ * Atomic placement from staging (spec 8.7): clear a read-only attribute on
+ * the destination, then rename from staging into place (same volume). When
+ * the same blob lands at several paths, all but the last use copy.
+ */
+async function placeFromStaging(projectRoot, path, stagedPath, keepStaged, context) {
+    const target = await containedProjectPath(projectRoot, path);
+    await clearReadOnly(target);
+    // The walker's byte-name map may point at an NFD or different-case name for
+    // this key; replace that exact on-disk file so we never strand a twin.
+    const onDisk = context.diskPathByKey.get(path);
+    if (onDisk && onDisk !== target) {
+        await clearReadOnly(onDisk);
+        await rm(onDisk, { force: true });
+    }
+    if (keepStaged) {
+        const tmp = join(dirname(target), `.${basename(target)}.summer-cloud-tmp`);
+        await copyFile(stagedPath, tmp);
+        await renameWithRetry(tmp, target);
+    }
+    else {
+        await renameWithRetry(stagedPath, target);
+    }
+}
+async function clearReadOnly(path) {
+    try {
+        const info = await stat(path);
+        if ((info.mode & 0o200) === 0) {
+            await chmod(path, info.mode | 0o200);
+        }
+    }
+    catch {
+        // Missing file: nothing to clear.
+    }
+}
+/** Windows retry ladder (spec 8.7): EPERM/EBUSY/EACCES, 50 ms doubling, 7 tries. */
+async function renameWithRetry(from, to) {
+    let delay = RENAME_BACKOFF_MS;
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            const retryable = code === "EPERM" || code === "EBUSY" || code === "EACCES";
+            if (!retryable || attempt >= RENAME_RETRIES - 1)
+                throw err;
+            await sleep(delay);
+            delay *= 2;
+        }
+    }
+}
+async function applyCaseOnlyRenames(projectRoot, plan, remote, context, decisionByPath, result) {
+    const done = new Set();
+    const deleteByFold = new Map();
+    for (const path of plan.deleteLocalPaths)
+        deleteByFold.set(casefoldKey(path), path);
+    for (const pullPath of plan.pullPaths) {
+        const oldPath = deleteByFold.get(casefoldKey(pullPath));
+        if (!oldPath || oldPath === pullPath)
+            continue;
+        const oldDecision = decisionByPath.get(oldPath);
+        const remoteFile = remote.files[pullPath];
+        if (!remoteFile || oldDecision?.local?.sha256 !== remoteFile.sha256)
+            continue;
+        if (await driftedSinceDiff(projectRoot, oldPath, context))
+            continue;
+        const source = context.diskPathByKey.get(oldPath) ?? join(projectRoot, oldPath);
+        const target = await containedProjectPath(projectRoot, pullPath);
+        const tmp = join(dirname(target), `.${basename(target)}.summer-cloud-rename-tmp`);
+        try {
+            await renameWithRetry(source, tmp);
+            await renameWithRetry(tmp, target);
+        }
+        catch {
+            continue; // Fall back to download-and-delete handling for this pair.
+        }
+        done.add(pullPath);
+        done.add(oldPath);
+        result.appliedPaths.push(pullPath);
+    }
+    return done;
+}
+async function isSameFile(a, b) {
+    try {
+        const [ia, ib] = await Promise.all([stat(a, { bigint: true }), stat(b, { bigint: true })]);
+        return ia.dev === ib.dev && ia.ino === ib.ino;
+    }
+    catch {
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/cloud/checkpoint.d.ts

@@ -0,0 +1,26 @@
+export interface CheckpointResult {
+    ref: string;
+    commit: string;
+}
+export declare function summerGitDir(projectRoot: string): string;
+export declare function isGitAvailable(): Promise<boolean>;
+export declare function checkpointStamp(date?: Date): string;
+/**
+ * Full-tree SummerGit checkpoint before any destructive apply (spec 11).
+ * Plumbing only: stage all into a private index, write-tree, commit-tree,
+ * update-ref. Keeps the last KEEP_CHECKPOINTS refs.
+ */
+export declare function createCheckpoint(projectRoot: string, projectId: string): Promise<CheckpointResult>;
+export declare function listCheckpoints(projectRoot: string, projectId: string): Promise<string[]>;
+export interface CheckpointRestoreResult {
+    ref: string;
+    restoredFiles: string[];
+    /** Files present on disk but not in the checkpoint; restore does not delete them. */
+    extraneousFiles: string[];
+}
+/**
+ * Restores a checkpoint's bytes (spec 11). checkout-index restores bytes but
+ * does not delete files a bad sync ADDED, so the result lists extraneous
+ * files for the user or agent to remove.
+ */
+export declare function restoreCheckpoint(projectRoot: string, projectId: string, refOrStamp: string, currentTrackedFiles: readonly string[]): Promise<CheckpointRestoreResult>;