@playcraft/cli 0.1.10 → 0.1.11

package/dist/workspace-runtime/codex/app-server.js

@@ -7,6 +7,7 @@ import { writePlaycraftCodexConfig } from './config-toml.js';
 import { createJsonRpcStdioClient } from './jsonrpc-stdio.js';
 import { projectNativeThread } from '@playcraft/common/cloud-workspace/runtime';
 import { collectedEvent, NativePreparationError } from './native-adapter.js';
+import { exportTranscript } from './transcripts.js';
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -68,6 +69,18 @@ export function createCodexAppServerAdapter(options) {
         for (const listener of collected)
             listener(event);
     }
+    function transcriptHome() {
+        if (!launcherSocket)
+            return { homeDir };
+        return {
+            homeDir,
+            launcher: {
+                socketPath: launcherSocket,
+                runtimeEpoch: executionEpoch,
+                cwd: options.config.workspaceMode === 'multi' ? '/home/playcraft-dev' : options.config.workspaceRoot,
+            },
+        };
+    }
     async function ensureStarted() {
         if (readyFlag && rpc)
             return;
@@ -272,6 +285,9 @@ export function createCodexAppServerAdapter(options) {
                 return undefined;
             }
         },
+        exportThread(input) {
+            return exportTranscript(transcriptHome(), input.threadId);
+        },
         async captureNativeCheckpoint(input) {
             const thread = threads.get(input.threadId);
             if (!thread || thread.sessionId !== input.sessionId)

package/dist/workspace-runtime/codex/transcripts.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { startLauncherProcess } from './launcher-client.js';
+export const TRANSCRIPT_MAX_BYTES = 64 * 1024 * 1024;
+const THREAD_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const TRANSCRIPT_PATH = /^sessions\/\d{4}\/\d{2}\/\d{2}\/rollout-[A-Za-z0-9_.-]{1,200}\.jsonl$/;
+const COMMAND_TIMEOUT_MS = 60_000;
+/**
+ * Reads the transcript Codex keeps for one thread. Codex appends to it while a turn runs, so a
+ * trailing partial line is dropped; what is returned always parses line by line.
+ */
+export async function exportTranscript(home, threadId) {
+    if (!THREAD_ID.test(threadId))
+        return undefined;
+    const found = home.launcher
+        ? await exportAsDeveloper(home.homeDir, home.launcher, threadId)
+        : await exportDirect(home.homeDir, threadId);
+    if (!found || !transcriptPathFor(found.path, threadId))
+        return undefined;
+    const end = found.body.lastIndexOf(0x0a);
+    if (end < 0)
+        return undefined;
+    return { path: found.path, body: found.body.subarray(0, end + 1) };
+}
+function transcriptPathFor(path, threadId) {
+    return TRANSCRIPT_PATH.test(path) && path.endsWith(`-${threadId}.jsonl`);
+}
+async function exportDirect(homeDir, threadId) {
+    const suffix = `-${threadId}.jsonl`;
+    for (const year of await names(join(homeDir, 'sessions'))) {
+        for (const month of await names(join(homeDir, 'sessions', year))) {
+            for (const day of await names(join(homeDir, 'sessions', year, month))) {
+                const directory = join('sessions', year, month, day);
+                const match = (await names(join(homeDir, directory))).find((name) => name.endsWith(suffix));
+                if (!match)
+                    continue;
+                const path = `${directory}/${match}`;
+                const absolute = join(homeDir, path);
+                if ((await stat(absolute)).size > TRANSCRIPT_MAX_BYTES)
+                    return undefined;
+                return { path, body: await readFile(absolute) };
+            }
+        }
+    }
+    return undefined;
+}
+async function exportAsDeveloper(homeDir, launcher, threadId) {
+    const limitKib = TRANSCRIPT_MAX_BYTES / 1024;
+    const outcome = await runAsDeveloper(launcher, [
+        `home=${quote(homeDir)}`,
+        `f=$(find "$home/sessions" -mindepth 4 -maxdepth 4 -type f -name ${quote(`rollout-*-${threadId}.jsonl`)} -size -${limitKib}k 2>/dev/null | head -n 1)`,
+        '[ -n "$f" ] || exit 3',
+        'printf \'%s\\n\' "${f#"$home"/}"',
+        'base64 -w 0 "$f"',
+    ].join('; '));
+    if (outcome.code !== 0)
+        return undefined;
+    const text = outcome.stdout.toString('utf8');
+    const newline = text.indexOf('\n');
+    if (newline < 0)
+        return undefined;
+    return { path: text.slice(0, newline), body: Buffer.from(text.slice(newline + 1).trim(), 'base64') };
+}
+async function runAsDeveloper(launcher, command) {
+    const child = await startLauncherProcess({
+        socketPath: launcher.socketPath,
+        processId: `transcript-${randomUUID()}`,
+        runtimeEpoch: launcher.runtimeEpoch,
+        argv: ['/usr/bin/bash', '-c', `{ ${command}; } </dev/null 2>/dev/null`],
+        cwd: launcher.cwd,
+        env: {},
+    });
+    child.stdin?.end();
+    const chunks = [];
+    child.stdout?.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+    const code = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            void child.stop().catch(() => undefined);
+            resolve(null);
+        }, COMMAND_TIMEOUT_MS);
+        child.onExit((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        });
+    });
+    return { code, stdout: Buffer.concat(chunks) };
+}
+async function names(directory) {
+    return readdir(directory).then((entries) => entries.sort(), () => []);
+}
+function quote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/workspace-runtime/previews/publish.js

@@ -33,6 +33,12 @@ export async function previewWorkspaceRoot(state, operation) {
     if (!operation.workspaceId || !/^[A-Za-z0-9_-]+$/.test(operation.operationId)) {
         throw new PreviewFailure('invalid_preview_publish');
     }
+    if (operation.sessionId !== undefined) {
+        const session = state.journal.getSession(operation.sessionId);
+        if (!session || (state.config.workspaceMode === 'multi' && session.workspaceId !== operation.workspaceId)) {
+            throw new PreviewFailure('session_workspace_mismatch');
+        }
+    }
     return workspaceRoot(state, operation.workspaceId);
 }
 /** Tracks a background publish so tests and shutdown can wait for it. */
@@ -55,6 +61,9 @@ export async function recoverInterruptedPreviews(journal) {
 }
 export async function runPreviewPublish(state, operation, root) {
     const workspaceId = operation.workspaceId;
+    const scope = operation.sessionId === undefined
+        ? {}
+        : { sessionId: operation.sessionId, clientRequestId: operation.clientRequestId };
     const outputDir = join(root, OUTPUT_FOLDER, operation.operationId);
     const output = { log: '' };
     try {
@@ -73,6 +82,7 @@ export async function runPreviewPublish(state, operation, root) {
         const source = await sourceRevision(root);
         const reserved = previewReservationSchema.parse(await postControl(state, '/runtime/internal/preview-reservations', {
             workspaceId,
+            ...scope,
             operationId: operation.operationId,
             contentDigest,
             contentMd5,
@@ -81,6 +91,8 @@ export async function runPreviewPublish(state, operation, root) {
             dirty: source.dirty,
             cliVersion: state.config.cliVersion,
         }));
+        if (reserved.sessionId !== operation.sessionId)
+            throw new PreviewFailure('preview_scope_mismatch');
         if (!reserved.alreadyUploaded) {
             const uploaded = await fetch(reserved.uploadUrl, {
                 method: 'PUT',
@@ -99,11 +111,16 @@ export async function runPreviewPublish(state, operation, root) {
         }
         const published = previewPublishResultSchema.parse(await postControl(state, '/runtime/internal/preview-completions', {
             workspaceId,
+            ...scope,
             operationId: operation.operationId,
             artifactId: reserved.artifactId,
             expectedPublishRevision: reserved.expectedPublishRevision,
             logTail: tail(output.log),
         }));
+        if (published.sessionId !== operation.sessionId || published.previewId !== reserved.previewId ||
+            published.artifactId !== reserved.artifactId) {
+            throw new PreviewFailure('preview_scope_mismatch');
+        }
         if (published.status === 'conflict')
             throw new PreviewFailure('publish_conflict');
         return published;
@@ -113,6 +130,7 @@ export async function runPreviewPublish(state, operation, root) {
         if (code !== 'publish_conflict') {
             await postControl(state, '/runtime/internal/preview-failures', {
                 workspaceId,
+                ...scope,
                 operationId: operation.operationId,
                 error: code,
                 logTail: tail(output.log || (error instanceof Error ? error.message : '')),

package/dist/workspace-runtime/server/dispatch.js

@@ -5,9 +5,10 @@ import { randomUUID } from 'node:crypto';
 import { checkpointRecordSchema, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
 import { NativePreparationError } from '../codex/native-adapter.js';
 import { disposeTerminalHost } from './terminal-host.js';
-import { captureWorkspaceTree, materializeSnapshot, publishFileSnapshot, } from '../workspaces/file-snapshot.js';
+import { captureWorkspaceTree, liveTreeDigest, materializeSnapshot, publishFileSnapshot, } from '../workspaces/file-snapshot.js';
+import { objectStoreHeaders, oneSaveAtATime, rememberFileCheckpoint, unchangedCheckpoint, workspaceSaves, } from '../workspaces/checkpoint-saves.js';
 import { InvalidWorkspacePathError, resolveWorkspaceFile, restoreWorkspaceFiles, snapshotWorkspaceFiles, writeWorkspaceFile, } from '../workspaces/files.js';
-import { GitWorkspaceError, commitWorkspaceGit, discardWorkspaceGit, pushWorkspaceGit, stageWorkspaceGit, unstageWorkspaceGit, } from '../workspaces/git.js';
+import { GitWorkspaceError, bundleUnpushedCommits, commitWorkspaceGit, discardWorkspaceGit, pushWorkspaceGit, stageWorkspaceGit, unstageWorkspaceGit, } from '../workspaces/git.js';
 import { ParameterEditError } from '../workspaces/json5-edit.js';
 import { patchWorkspaceParameters, readWorkspaceParameters } from '../workspaces/parameters.js';
 import { previewFailureCode, previewWorkspaceRoot, runPreviewPublish, trackPreviewPublish, } from '../previews/publish.js';
@@ -80,7 +81,8 @@ async function executeScopedOperation(state, scopeKey, operation, payload) {
         return persist(state, scopeKey, transitionOperation(current, 'failed', { error: 'workspace_not_ready' }));
     }
     if (operation.kind === 'checkpoint.create') {
-        return executeCheckpoint(state, scopeKey, current, payload);
+        const workspaceId = current.workspaceId ?? String(asRecord(payload).workspaceId ?? 'workspace');
+        return oneSaveAtATime(state, workspaceId, () => executeCheckpoint(state, scopeKey, current, payload));
     }
     if (operation.kind === 'checkpoint.restore') {
         return executeRestore(state, scopeKey, current, payload);
@@ -288,9 +290,9 @@ async function executeApproval(state, scopeKey, operation, payload) {
 }
 async function executeCheckpoint(state, scopeKey, operation, payload) {
     const body = asRecord(payload);
-    const checkpointId = typeof body.checkpointId === 'string' && body.checkpointId.trim()
-        ? body.checkpointId.trim()
-        : `ckpt_${randomUUID()}`;
+    // Only a save without a requested identity may answer with an earlier, unchanged checkpoint.
+    const requested = typeof body.checkpointId === 'string' && body.checkpointId.trim() !== '';
+    const checkpointId = requested ? String(body.checkpointId).trim() : `ckpt_${randomUUID()}`;
     if (!/^[a-zA-Z0-9_-]{1,128}$/.test(checkpointId) || state.journal.getCheckpoint(checkpointId)) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'checkpoint_id_conflict' }));
     }
@@ -321,8 +323,29 @@ async function executeCheckpoint(state, scopeKey, operation, payload) {
     const revisions = state.journal.fileRevisions(revisionScope(state, operation.workspaceId));
     let files;
     let published;
+    // A standalone workspace has no remote, so all of its `.git` is kept. A project workspace's packs
+    // come back with a new clone; what the remote lacks goes into the unpushed bundle.
+    const standalone = state.journal.getWorkspace(workspaceId)?.targetKind === 'standalone';
+    if (!standalone) {
+        // Without a fresh bundle the loose objects still hold commits made since the last repack.
+        await bundleUnpushedCommits(root).catch(() => undefined);
+    }
+    const tree = await captureWorkspaceTree(root, previousFilePaths(state), revisions, undefined, {
+        git: standalone ? 'full' : 'local',
+    });
+    // Transcripts only matter where another instance can read them back.
+    const transcripts = state.config.fileObjectStoreUrl ? await captureTranscripts(state, operation.workspaceId) : [];
+    const digest = liveTreeDigest(tree, transcripts);
+    if (!requested && tree.status === 'complete') {
+        const stillActive = await activeManagedWrites(state, workspaceId);
+        if (stillActive.length === 0) {
+            const captured = await captureNativeSessions(state, operation.workspaceId);
+            const previous = unchangedCheckpoint(state, workspaceId, digest, captured.sessions);
+            if (previous)
+                return finishUnchanged(state, scopeKey, operation, previous);
+        }
+    }
     if (state.config.fileObjectStoreUrl) {
-        const tree = await captureWorkspaceTree(root, previousFilePaths(state), revisions);
         const stillActive = await activeManagedWrites(state, workspaceId);
         if (stillActive.length > 0) {
             return finishBestEffort(state, scopeKey, operation, checkpointId, workspaceId, createdAt, stillActive.map((item) => item.source));
@@ -334,6 +357,10 @@ async function executeCheckpoint(state, scopeKey, operation, payload) {
                 workspaceId,
                 generation: state.config.generation,
                 tree,
+                native: transcripts,
+                uploaded: workspaceSaves(state, workspaceId).uploaded,
+                uploadedTranscripts: workspaceSaves(state, workspaceId).transcripts,
+                headers: objectStoreHeaders(state, state.config.fileObjectStoreUrl),
             });
         }
         catch {
@@ -393,8 +420,26 @@ async function executeCheckpoint(state, scopeKey, operation, payload) {
     await state.journal.setFileCheckpointId(checkpointId);
     if (nativeReady)
         await state.journal.setConsistentCheckpointId(checkpointId);
+    if (tree.status === 'complete') {
+        await rememberFileCheckpoint(state, workspaceId, { checkpointId, digest, sessions: captured.sessions });
+    }
     return finishCheckpoint(state, scopeKey, operation, checkpoint, []);
 }
+/**
+ * Nothing changed since the last file checkpoint: the save reports that checkpoint again and
+ * writes no new one, so periodic saves of an idle workspace cost one read of the tree.
+ */
+async function finishUnchanged(state, scopeKey, operation, checkpoint) {
+    const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted', { checkpointId: checkpoint.checkpointId }));
+    return persist(state, scopeKey, transitionOperation(accepted, 'completed', {
+        checkpointId: checkpoint.checkpointId,
+        checkpointKind: checkpoint.kind,
+        checkpointConsistent: checkpoint.consistent === true,
+        ...(checkpoint.manifestKey ? { snapshotManifestKey: checkpoint.manifestKey } : {}),
+        ...(checkpoint.checksum ? { snapshotChecksum: checkpoint.checksum } : {}),
+        ...(checkpoint.snapshotStatus ? { snapshotStatus: checkpoint.snapshotStatus } : {}),
+    }));
+}
 async function executeRestore(state, scopeKey, operation, payload) {
     const body = asRecord(payload);
     const checkpointId = String(body.checkpointId ?? operation.checkpointId ?? '');
@@ -808,6 +853,22 @@ async function finishCheckpoint(state, scopeKey, operation, checkpoint, activeWr
         ...(checkpoint.snapshotStatus ? { snapshotStatus: checkpoint.snapshotStatus } : {}),
     }));
 }
+/** Transcripts of the workspace's resumable threads. A thread whose file cannot be read is left out. */
+async function captureTranscripts(state, workspaceId) {
+    const native = state.native;
+    if (!native?.exportThread)
+        return [];
+    const captured = [];
+    for (const session of workspaceSessions(state, workspaceId)) {
+        if (session.recoverability !== 'native')
+            continue;
+        const capturedAt = new Date().toISOString();
+        const file = await native.exportThread({ threadId: session.threadId }).catch(() => undefined);
+        if (file)
+            captured.push({ sessionId: session.sessionId, threadId: session.threadId, capturedAt, ...file });
+    }
+    return captured;
+}
 async function captureNativeSessions(state, workspaceId) {
     const live = workspaceSessions(state, workspaceId);
     const sessions = [];

package/dist/workspace-runtime/workspaces/checkpoint-saves.js

@@ -0,0 +1,79 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Local copies kept per workspace. Older ones are removed; the remote snapshots stay. */
+const LOCAL_COPIES_KEPT = 3;
+const saves = new WeakMap();
+/** Kept in memory: after a restart the first save writes a new checkpoint and uploads again. */
+export function workspaceSaves(state, workspaceId) {
+    let byWorkspace = saves.get(state);
+    if (!byWorkspace) {
+        byWorkspace = new Map();
+        saves.set(state, byWorkspace);
+    }
+    let entry = byWorkspace.get(workspaceId);
+    if (!entry) {
+        entry = { uploaded: new Set(), transcripts: new Map(), local: [], queue: Promise.resolve() };
+        byWorkspace.set(workspaceId, entry);
+    }
+    return entry;
+}
+/**
+ * Saves of one workspace run one after another. Overlapping saves (the page's timer, Runtime's
+ * save after a change, the Save button) would otherwise finish in any order, and the last to finish
+ * becomes the recovery point even when it captured the older tree.
+ */
+export function oneSaveAtATime(state, workspaceId, run) {
+    const entry = workspaceSaves(state, workspaceId);
+    const next = entry.queue.then(run, run);
+    entry.queue = next.then(() => undefined, () => undefined);
+    return next;
+}
+export function sessionsKey(sessions) {
+    return JSON.stringify([...sessions]
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId))
+        .map((item) => [item.sessionId, item.nativeThreadId ?? null, item.nativeDurableTurnId ?? null, item.recoverability]));
+}
+/**
+ * The checkpoint a save can answer with instead of writing a new one: same files on disk, same
+ * native session state, and the journal still has it.
+ */
+export function unchangedCheckpoint(state, workspaceId, digest, sessions) {
+    const last = workspaceSaves(state, workspaceId).last;
+    if (!last || last.digest !== digest || last.sessions !== sessionsKey(sessions))
+        return undefined;
+    const checkpoint = state.journal.getCheckpoint(last.checkpointId);
+    return checkpoint?.workspaceId === workspaceId ? checkpoint : undefined;
+}
+export async function rememberFileCheckpoint(state, workspaceId, saved) {
+    const entry = workspaceSaves(state, workspaceId);
+    entry.last = { checkpointId: saved.checkpointId, digest: saved.digest, sessions: sessionsKey(saved.sessions) };
+    entry.local.push(saved.checkpointId);
+    // The journal's current file and consistent checkpoints keep their copy until they are replaced.
+    const kept = new Set([state.journal.fileCheckpointId(), state.journal.consistentCheckpointId()]);
+    const removable = entry.local
+        .slice(0, Math.max(0, entry.local.length - LOCAL_COPIES_KEPT))
+        .filter((checkpointId) => !kept.has(checkpointId));
+    entry.local = entry.local.filter((checkpointId) => !removable.includes(checkpointId));
+    for (const checkpointId of removable) {
+        await rm(join(state.config.stateDir, 'file-checkpoints', checkpointId), { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * The control credential goes only to Runtime's own object endpoint, never to another store.
+ */
+export function objectStoreHeaders(state, storeUrl) {
+    try {
+        if (new URL(storeUrl).origin !== new URL(state.config.callbackUrl).origin)
+            return {};
+    }
+    catch {
+        return {};
+    }
+    return {
+        authorization: `Bearer ${state.config.controlToken}`,
+        'playcraft-env': state.config.environment,
+        'x-playcraft-runtime-id': state.config.runtimeId,
+        'x-playcraft-generation': String(state.config.generation),
+        'x-playcraft-runtime-epoch': String(state.runtimeEpoch),
+    };
+}

package/dist/workspace-runtime/workspaces/file-snapshot.js

@@ -1,7 +1,75 @@
 import { chmod, lstat, mkdir, readdir, readFile, readlink, realpath, rm, symlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { fileSnapshotDigest, fileSnapshotManifestKey, fileSnapshotManifestSchema, fileSnapshotObjectKey, hashSnapshotBytes, isDisposableBackupPath, putObjectBytes, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { fileSnapshotDigest, fileSnapshotManifestKey, fileSnapshotContentKey, nativeTranscriptKey, fileSnapshotManifestSchema, hashSnapshotBytes, isDisposableBackupPath, putObjectBytes, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { UNPUSHED_BUNDLE, addBundleObjects, repositoryResolves } from './git.js';
 const SKIP_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
+/** Build output, caches and scratch folders, at any depth: regenerated, so not kept in storage. */
+const UNSTORED_DIRECTORY_NAMES = new Set([
+    'dist',
+    'dist-all',
+    'coverage',
+    '.vite',
+    '.cache',
+    '.turbo',
+    '.parcel-cache',
+    '.sass-cache',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    'tmp',
+    '.tmp',
+    '.temp',
+]);
+/** Scratch and cache files, at any depth. */
+const UNSTORED_FILE = /(?:\.tmp|\.log|\.tsbuildinfo|^\.eslintcache)$/;
+/**
+ * At the workspace root: the preview build's output, the builder's scratch folder, and skill
+ * artifacts the sandbox pulls from the registry by `.playcraft/skills.lock.json`.
+ */
+const UNSTORED_ROOT_DIRECTORIES = [
+    '.playcraft-preview-out/',
+    '.playcraft-temp/',
+    '.playcraft/skills/',
+    'ta-workspace/logs/',
+];
+/**
+ * Recordings, frames and reports the template's verify and record scripts write again on each run.
+ * The ring JSON evidence the build gate reads stays, as do the agent-edited profile and catalogs.
+ */
+const UNSTORED_RUN_OUTPUT = [
+    /^recordings\/(?:.+\.(?:mp4|webm)$|\.tmp-[^/]+\/|focus\/|clean\/)/,
+    /^validate\/(?:[^/]+\.md$|(?:ring\d+\/)?frames\/|ring\d+\/[^/]+\.mp4$)/,
+];
+/**
+ * Whether a path goes to checkpoint storage. Credentials, lock files, build output, caches and
+ * scratch files stay in the instance: its local copy keeps them, so restoring inside the instance
+ * does not remove them.
+ */
+export function keptInStorage(path) {
+    if (isDisposableBackupPath(path))
+        return false;
+    if (path.startsWith('.git/'))
+        return true;
+    if (UNSTORED_ROOT_DIRECTORIES.some((prefix) => path.startsWith(prefix)))
+        return false;
+    if (UNSTORED_RUN_OUTPUT.some((pattern) => pattern.test(path)))
+        return false;
+    const segments = path.split('/');
+    if (UNSTORED_FILE.test(segments[segments.length - 1]))
+        return false;
+    return !segments.slice(0, -1).some((segment) => UNSTORED_DIRECTORY_NAMES.has(segment));
+}
+/**
+ * Under `.git/`, what a `local` capture leaves to the remote: packs and their indexes, submodule
+ * repositories (`git submodule update` fetches them again), LFS objects, and template hooks.
+ */
+const REMOTE_GIT_DIRECTORIES = new Set([
+    '.git/objects/pack',
+    '.git/objects/info',
+    '.git/modules',
+    '.git/lfs',
+    '.git/hooks',
+]);
 const READ_ATTEMPTS = 3;
 const realIo = {
     async readdir(path) {
@@ -13,13 +81,28 @@ const realIo = {
     readFile,
     readlink,
 };
-export async function captureWorkspaceTree(root, previousPaths, revisions, io = realIo) {
+export async function captureWorkspaceTree(root, previousPaths, revisions, io = realIo, options = {}) {
     const entries = [];
     const files = [];
     const bodies = new Map();
     const seen = new Set();
     let status = 'complete';
-    await walk(root, root, io, revisions, entries, files, bodies, seen, () => {
+    const skip = (relativePath, name, directory) => {
+        if (name === '.' || name === '..')
+            return true;
+        if (directory && name === '.git')
+            return !(options.git && relativePath === '.git');
+        // A submodule's `.git` file points into `.git/modules`, which is not kept either.
+        if (!directory && name === '.git' && relativePath !== '.git')
+            return true;
+        if (directory && SKIP_DIRECTORY_NAMES.has(name))
+            return true;
+        if (directory && options.git === 'local' && REMOTE_GIT_DIRECTORIES.has(relativePath))
+            return true;
+        // Git's own lock files only exist while a command runs and must not come back with a restore.
+        return !directory && relativePath.startsWith('.git/') && name.endsWith('.lock');
+    };
+    await walk(root, root, io, revisions, entries, files, bodies, seen, skip, () => {
         status = 'incomplete';
     });
     for (const path of [...previousPaths].sort((left, right) => left.localeCompare(right))) {
@@ -62,6 +145,12 @@ export async function materializeRemoteSnapshot(root, entries) {
         if (hashSnapshotBytes(body) !== entry.contentHash)
             throw new Error('snapshot_mismatch');
     }
+    if (applicable.some((entry) => entry.path === '.git/HEAD')) {
+        const bundle = applicable.find((entry) => entry.path === UNPUSHED_BUNDLE && entry.kind === 'file');
+        if (bundle)
+            await addBundleObjects(rootReal, Buffer.from(bundle.contentBase64 ?? '', 'base64'));
+        await clearClonedGitMetadata(rootReal);
+    }
     for (const entry of applicable) {
         const target = resolve(rootReal, ...entry.path.split('/'));
         const rel = relative(rootReal, target);
@@ -85,50 +174,100 @@ export async function materializeRemoteSnapshot(root, entries) {
         if (entry.mode !== undefined)
             await chmod(target, entry.mode);
     }
-    let repositoryReady = false;
-    try {
-        const git = await lstat(join(rootReal, '.git'));
-        repositoryReady = git.isDirectory() && !git.isSymbolicLink();
-    }
-    catch {
-        repositoryReady = false;
-    }
     return {
         skipped,
         directoryReady: true,
-        repositoryReady,
+        repositoryReady: await repositoryResolves(rootReal),
         environmentReady: false,
     };
 }
+/**
+ * The snapshot's `.git` replaces the one a new clone made, objects aside: a ref the clone wrote
+ * would otherwise outrank the snapshot's packed refs.
+ */
+async function clearClonedGitMetadata(rootReal) {
+    const gitDir = join(rootReal, '.git');
+    const info = await lstat(gitDir).catch(() => undefined);
+    if (!info?.isDirectory())
+        return;
+    for (const name of await readdir(gitDir)) {
+        if (name !== 'objects')
+            await rm(join(gitDir, name), { recursive: true, force: true });
+    }
+}
+/**
+ * Content goes to the workspace's shared objects, keyed by hash. A hash in `uploaded` was stored by
+ * this process before and is not sent again; hashes stored now are added to it. The manifest still
+ * lists every stored file, so each snapshot restores on its own. Paths not `keptInStorage` are left
+ * out of both the objects and the manifest.
+ */
 export async function publishFileSnapshot(input) {
-    for (const entry of input.tree.entries) {
+    const stored = new Set();
+    const entries = input.tree.entries.filter((entry) => keptInStorage(entry.path));
+    for (const entry of entries) {
         if (entry.kind !== 'file' || !entry.contentHash)
             continue;
+        if (input.uploaded?.has(entry.contentHash) || stored.has(entry.contentHash))
+            continue;
         const body = input.tree.bodies.get(entry.path);
         if (!body || hashSnapshotBytes(body) !== entry.contentHash)
             throw new Error('snapshot_body_missing');
-        await putObjectBytes(input.baseUrl, fileSnapshotObjectKey(input.workspaceId, input.generation, input.snapshotId, entry.contentHash), body, 'cli');
+        await putObjectBytes(input.baseUrl, fileSnapshotContentKey(input.workspaceId, entry.contentHash), body, 'cli', input.headers);
+        stored.add(entry.contentHash);
+    }
+    const native = [];
+    for (const transcript of input.native ?? []) {
+        const contentHash = hashSnapshotBytes(transcript.body);
+        if (input.uploadedTranscripts?.get(transcript.path) !== contentHash) {
+            await putObjectBytes(input.baseUrl, nativeTranscriptKey(input.workspaceId, transcript.path), transcript.body, 'cli', input.headers);
+            input.uploadedTranscripts?.set(transcript.path, contentHash);
+        }
+        native.push({
+            sessionId: transcript.sessionId,
+            threadId: transcript.threadId,
+            path: transcript.path,
+            contentHash,
+            size: transcript.body.byteLength,
+            capturedAt: transcript.capturedAt,
+        });
     }
-    const digest = fileSnapshotDigest(input.tree.entries);
+    const digest = fileSnapshotDigest(entries);
     const manifest = fileSnapshotManifestSchema.parse({
         snapshotId: input.snapshotId,
         workspaceId: input.workspaceId,
         generation: input.generation,
         status: input.tree.status,
-        entries: input.tree.entries,
+        entries,
         digest,
+        objectLayout: 'workspace',
+        ...(native.length > 0 ? { native } : {}),
     });
     const manifestKey = fileSnapshotManifestKey(input.workspaceId, input.generation, input.snapshotId);
-    await putObjectBytes(input.baseUrl, manifestKey, Buffer.from(JSON.stringify(manifest)), 'cli');
+    await putObjectBytes(input.baseUrl, manifestKey, Buffer.from(JSON.stringify(manifest)), 'cli', input.headers);
+    for (const hash of stored)
+        input.uploaded?.add(hash);
     return { manifestKey, checksum: digest, status: input.tree.status };
 }
-async function walk(rootReal, current, io, revisions, entries, files, bodies, seen, markIncomplete) {
+/**
+ * Digest of what is on disk now, without the deletions recorded against the previous snapshot.
+ * Transcripts count too: a turn that only talked still changes what a restore can resume.
+ */
+export function liveTreeDigest(tree, native = []) {
+    const files = fileSnapshotDigest(tree.entries.filter((entry) => entry.kind !== 'deleted'));
+    if (native.length === 0)
+        return files;
+    const transcripts = native
+        .map((item) => `${item.sessionId}:${item.threadId}:${item.path}:${hashSnapshotBytes(item.body)}`)
+        .sort();
+    return hashSnapshotBytes(Buffer.from([files, ...transcripts].join('\n')));
+}
+async function walk(rootReal, current, io, revisions, entries, files, bodies, seen, skip, markIncomplete) {
     const listed = await io.readdir(current);
     for (const entry of listed) {
-        if (entry.name === '.' || entry.name === '..' || SKIP_DIRECTORY_NAMES.has(entry.name))
-            continue;
         const child = join(current, entry.name);
         const relativePath = toPosixRelative(rootReal, child);
+        if (skip(relativePath, entry.name, entry.isDirectory()))
+            continue;
         if (!workspaceRelativePathSchema.safeParse(relativePath).success) {
             markIncomplete();
             continue;
@@ -145,7 +284,7 @@ async function walk(rootReal, current, io, revisions, entries, files, bodies, se
             continue;
         }
         if (entry.isDirectory()) {
-            await walk(rootReal, child, io, revisions, entries, files, bodies, seen, markIncomplete);
+            await walk(rootReal, child, io, revisions, entries, files, bodies, seen, skip, markIncomplete);
             continue;
         }
         if (!entry.isFile())

package/dist/workspace-runtime/workspaces/git.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { lstat, readFile, realpath, stat, unlink } from 'node:fs/promises';
+import { lstat, mkdir, readFile, realpath, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { WORKSPACE_FILE_CONTENT_MAX, gitDiffSchema, gitFileContentSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -245,6 +245,96 @@ export async function pushWorkspaceGit(root, boundBranch) {
     catch { /* Preserve uncertainty; never replay a write automatically. */ }
     throw new GitWorkspaceError('git_push_outcome_unknown', 'git_push_outcome_unknown');
 }
+const UNPUSHED_DIRECTORY = '.git/playcraft';
+export const UNPUSHED_BUNDLE = `${UNPUSHED_DIRECTORY}/unpushed.bundle`;
+const UNPUSHED_TIPS = `${UNPUSHED_DIRECTORY}/unpushed.tips`;
+/**
+ * Keeps a bundle of the commits on local branches and the latest stash that no remote-tracking
+ * branch holds, so a backup without the packs still has them. It is rewritten only when one of
+ * those refs moves, and removed when nothing is unpushed. Without remote-tracking refs there is no
+ * baseline, and the whole history is left out rather than bundled.
+ */
+export async function bundleUnpushedCommits(root) {
+    const rootReal = await realpath(root);
+    const marker = await lstat(join(rootReal, '.git')).catch(() => undefined);
+    if (!marker?.isDirectory())
+        return;
+    const tips = await git(rootReal, [
+        'for-each-ref', '--format=%(objectname) %(refname)', 'refs/heads', 'refs/remotes', 'refs/stash',
+    ]);
+    const tipsPath = join(rootReal, UNPUSHED_TIPS);
+    if ((await readFile(tipsPath, 'utf8').catch(() => undefined)) === tips)
+        return;
+    const refs = tips.split('\n').map((line) => line.split(' ')[1]).filter((ref) => Boolean(ref));
+    const local = ['--branches', ...(refs.includes('refs/stash') ? ['refs/stash'] : [])];
+    const unpushed = refs.some((ref) => ref.startsWith('refs/remotes/'))
+        ? Number.parseInt((await git(rootReal, ['rev-list', '--count', ...local, '--not', '--remotes'], 60000)).trim(), 10)
+        : 0;
+    const bundlePath = join(rootReal, UNPUSHED_BUNDLE);
+    await mkdir(join(rootReal, UNPUSHED_DIRECTORY), { recursive: true, mode: 0o700 });
+    if (unpushed > 0) {
+        // The `.lock` name keeps a half-written bundle out of any snapshot.
+        const temp = `${bundlePath}.lock`;
+        try {
+            await git(rootReal, ['bundle', 'create', temp, ...local, '--not', '--remotes'], 120000);
+            await rename(temp, bundlePath);
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    }
+    else {
+        await rm(bundlePath, { force: true });
+    }
+    await writeFile(tipsPath, tips, { mode: 0o600 });
+}
+/**
+ * Adds a bundle's objects to the repository. `unbundle` walks history from the current refs, so this
+ * runs on the fresh clone before the snapshot's refs, which point at these very commits, replace its
+ * own. It fails when the remote lost the commits the bundle was built on; `repositoryResolves` then
+ * reports what is missing.
+ */
+export async function addBundleObjects(root, body) {
+    const rootReal = await realpath(root);
+    const marker = await lstat(join(rootReal, '.git')).catch(() => undefined);
+    if (!marker?.isDirectory())
+        return;
+    const temp = join(rootReal, '.git', 'playcraft-restore.bundle.lock');
+    try {
+        await writeFile(temp, body, { mode: 0o600 });
+        await gitAllowFail(rootReal, ['bundle', 'unbundle', temp], 120000);
+    }
+    catch {
+        /* Reported by repositoryResolves. */
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+/** Whether HEAD and the index resolve to objects the repository holds. */
+export async function repositoryResolves(root) {
+    const rootReal = await realpath(root);
+    const marker = await lstat(join(rootReal, '.git')).catch(() => undefined);
+    if (!marker?.isDirectory())
+        return false;
+    try {
+        // Snapshots hold files only; Git does not recognise a repository whose refs folder is gone.
+        for (const directory of ['refs/heads', 'refs/tags', 'objects']) {
+            await mkdir(join(rootReal, '.git', directory), { recursive: true, mode: 0o755 });
+        }
+        const head = await gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD^{tree}']);
+        if (head.code === 0) {
+            const index = await gitAllowFail(rootReal, ['diff-index', '--cached', '--quiet', 'HEAD'], 60000);
+            return index.code === 0 || index.code === 1;
+        }
+        // Before the first commit there is no branch to resolve.
+        const branches = await gitAllowFail(rootReal, ['for-each-ref', '--count=1', 'refs/heads']);
+        return branches.code === 0 && branches.stdout.trim() === '';
+    }
+    catch {
+        return false;
+    }
+}
 export async function ensureWorkspaceGit(root) {
     const rootReal = await realpath(root);
     if (!(await gitMarkerExists(rootReal))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "type": "module",
   "engines": {
@@ -48,8 +48,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.10",
-    "@playcraft/common": "^0.1.10",
+    "@playcraft/build": "^0.1.11",
+    "@playcraft/common": "^0.1.11",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",