@playcraft/cli 0.1.45-beta → 0.1.47-beta

package/dist/commands/tools-batch.js

@@ -15,7 +15,6 @@ const messages = {
         requestRequired: 'Prompt creation requires a stable --client-request-id; reuse it when retrying the same request.',
         help: '\nUse --prompt with --workspace-id and a stable --client-request-id. The platform plans and generates independent Remix directories while preserving the source. An omitted count defaults to 3; maximum 10. --input also accepts existing structured drafts.\n',
         confirmation: 'Generation is queued. Read the batch status to track its results.',
-        review: 'This existing draft requires baseline approval in the browser.',
         sync: 'Apply the latest source snapshot to an existing batch',
         syncDone: 'Batch sync requested',
     },
@@ -31,7 +30,6 @@ const messages = {
         requestRequired: '使用 prompt 创建时必须提供稳定的 --client-request-id，重试同一请求时复用该标识。',
         help: '\n使用 --prompt、--workspace-id 和稳定的 --client-request-id。平台自动规划，在副本中生成独立 Remix，保持来源不变。未指定数量默认 3 个，最多 10 个。--input 也兼容现有结构化草案。\n',
         confirmation: '生成已排队，可查询批次状态追踪各项成果。',
-        review: '此历史草案需要在浏览器确认基准。',
         sync: '将来源最新快照同步到已有批次',
         syncDone: '已请求同步到批次',
     },
@@ -69,7 +67,7 @@ export function registerBatchCommands(tools) {
                 sourceWorkspaceId: opts.workspaceId, sourceDirectoryName: opts.sourceDirectory,
                 ...(opts.teamId ? { teamId: opts.teamId } : {}),
             });
-            console.log(opts.json ? JSON.stringify(result, null, 2) : `${t.created}: ${result.batchId}\n${result.manifest.autoStart ? t.confirmation : t.review}`);
+            console.log(opts.json ? JSON.stringify(result, null, 2) : `${t.created}: ${result.batchId}\n${t.confirmation}`);
         }
         catch (error) {
             handleError(error);

package/dist/workspace-runtime/{production → batch}/content-changes.js

@@ -1,6 +1,4 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-const execute = promisify(execFile);
+import { gitRead } from './git.js';
 const reference = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const excludedDirectories = new Set(['node_modules', 'dist', 'build', 'coverage', 'docs', 'test', 'tests', '__tests__']);
 const contentExtension = /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|s[ac]ss|less|json5?|ya?ml|xml|glsl|wgsl|vert|frag|lua|py|svg|png|jpe?g|webp|avif|gif|bmp|mp[34]|wav|ogg|m4a|webm|glb|gltf|fbx|obj|bin|atlas|woff2?|ttf|otf)$/i;
@@ -13,15 +11,11 @@ function contentPath(path) {
         return false;
     return contentExtension.test(name);
 }
-/** A completed native turn is useful only when code, runtime configuration, or assets changed. */
-export async function requireProductionContentChanges(root, before, after) {
+/** A completed batch member must change code, runtime configuration, or assets. */
+export async function requireBatchContentChanges(root, before, after) {
     if (!reference.test(before) || !reference.test(after))
-        throw new Error('production_change_reference_invalid');
-    const { stdout } = await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root,
-        'diff', '--raw', '--no-abbrev', '--no-renames', '-z', before, after, '--'], {
-        timeout: 90_000, maxBuffer: 64 * 1024 * 1024,
-        env: { PATH: process.env.PATH, HOME: root, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
-    });
+        throw new Error('batch_change_reference_invalid');
+    const stdout = await gitRead(root, ['diff', '--raw', '--no-abbrev', '--no-renames', '-z', before, after, '--']);
     const records = stdout.split('\0'), paths = [];
     for (let index = 0; index + 1 < records.length; index += 2) {
         const [oldMode, newMode, oldBlob, newBlob] = records[index].slice(1).split(' ');
@@ -31,6 +25,6 @@ export async function requireProductionContentChanges(root, before, after) {
             paths.push(path);
     }
     if (!paths.length)
-        throw new Error('production_generation_no_content_change');
+        throw new Error('batch_generation_no_content_change');
     return paths;
 }

package/dist/workspace-runtime/batch/deliver.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { hashOperationPayload, sandboxBatchMemberDeliverSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { findExternalLocalReferences } from '../previews/single-file.js';
 import { workspaceRoot } from '../workspaces/registry.js';
+import { requireBatchContentChanges } from './content-changes.js';
 import { gitRead, gitWrite } from './git.js';
 import { groupExited, runProcessGroup, stopProcessGroup } from './processes.js';
 import { filesystemObjectStore, memberStatus, readMember, readStopMarker, serializeRun, writeMember, } from './records.js';
@@ -62,12 +63,15 @@ export async function deliverBatchMember(state, body, options) {
             directoryName: command.directoryName, phase: 'deliver', state: 'running', writersStopped: false, holding: true, stopRequested: false,
             processes: existing?.processes ?? [], sessionId: existing?.sessionId, operationId: existing?.operationId, commandHash: { ...existing?.commandHash, deliver: hash },
             snapshotDigest: existing?.snapshotDigest, branchName: existing?.branchName, updatedAt: new Date().toISOString(),
+            sourceCommit: existing?.sourceCommit ?? state.journal.getWorkspace(command.workspaceId)?.directories?.find(directory => directory.directoryName === command.directoryName)?.sourceCommit,
+            beforeTree: existing?.beforeTree,
         });
         const buildRoot = join(state.config.stateDir, 'batch-builds', `${command.runId}-${randomUUID()}`);
         try {
             const savedCommit = command.fromCommit ?? await saveExact(root);
             if (command.fromCommit)
                 await gitRead(root, ['cat-file', '-e', `${command.fromCommit}^{commit}`]);
+            await requireBatchContentChanges(root, record.sourceCommit ?? '', savedCommit);
             if (await readStopMarker(state, command.runId))
                 return memberStatus(await markStopped(state, command, record));
             let pushedCommit;
@@ -146,5 +150,6 @@ async function markStopped(state, command, existing) {
         holding: false, stopRequested: true, processes: existing?.processes ?? [], sessionId: existing?.sessionId, operationId: existing?.operationId,
         headCommit: existing?.headCommit, evidence: existing?.evidence, commandHash: existing?.commandHash, snapshotDigest: existing?.snapshotDigest,
         branchName: existing?.branchName, updatedAt: new Date().toISOString(),
+        sourceCommit: existing?.sourceCommit, beforeTree: existing?.beforeTree,
     });
 }

package/dist/workspace-runtime/batch/freeze.js

@@ -1,12 +1,14 @@
-import { lstat, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { rm, writeFile } from 'node:fs/promises';
 import { statfs } from 'node:fs/promises';
 import { batchSourceFreezeResultSchema, batchSourceRemoteRef, sandboxBatchSourceFreezeRequestSchema, workspaceDiskAdmission, } from '@playcraft/common/cloud-workspace/runtime';
 import { stopBackgroundWriter } from '../processes/managed-writes.js';
 import { workspaceRoot } from '../workspaces/registry.js';
-import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
-import { archiveSource, captureIndependentSource } from './source-capture.js';
+import { gitRead } from './git.js';
+import { captureIndependentSource } from './source-capture.js';
 import { filesystemObjectStore, readSnapshot, serializeFreeze, sourceCacheDir, writeSnapshot, } from './records.js';
+import { assertSourceIdentity, readSourceCandidate, writeSourceCandidate } from './source-candidate.js';
+import { BatchSourceFreezeError, sourceFreezeError } from './source-failure.js';
+import { publishSourceCandidate } from './source-publish.js';
 async function usagePercent(path) {
     const disk = await statfs(path);
     if (disk.blocks <= 0)
@@ -27,76 +29,73 @@ async function stopManagedWriters(state, workspaceId, directoryName) {
         await state.journal.putManagedWrite({ ...write, stoppedAt: new Date().toISOString() });
     }
 }
-async function pushHiddenRef(cache, sourceRoot, remote, commit, ref) {
-    await copyCredentialHelpers(sourceRoot, cache);
-    try {
-        await gitWrite(cache, ['push', remote, `${commit}:${ref}`]);
-    }
-    catch {
-        throw new Error('batch_source_push_failed');
-    }
-    const remoteHash = (await gitWrite(cache, ['ls-remote', remote, ref]).catch(() => '')).slice(0, commit.length);
-    if (remoteHash !== commit)
-        throw new Error('batch_source_push_failed');
-}
 export async function freezeBatchSource(state, body, options) {
     const parsed = sandboxBatchSourceFreezeRequestSchema.safeParse(body);
     if (!parsed.success)
         throw new Error('invalid_batch_request');
     const request = parsed.data;
     return serializeFreeze(async () => {
-        const existing = await readSnapshot(state, request.batchId);
-        if (existing)
-            return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: existing });
-        const source = await workspaceRoot(state, request.workspaceId, request.sourceDirectoryName);
-        const percent = Math.min(100, Math.max(0, options?.usagePercent ?? await usagePercent(source)));
-        if (workspaceDiskAdmission(percent) === 'paused')
-            throw new Error('disk_admission_paused');
-        await stopManagedWriters(state, request.workspaceId, request.sourceDirectoryName);
-        const cache = sourceCacheDir(state, request.batchId);
-        await rm(cache, { recursive: true, force: true });
-        const captured = await captureIndependentSource(source, cache);
-        await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
-        const binding = state.journal.getWorkspace(request.workspaceId);
-        const frozenAt = new Date((await gitRead(cache, ['show', '-s', '--format=%cI', 'HEAD'])).trim()).toISOString();
-        const snapshot = {
-            batchId: request.batchId,
-            commitHash: captured.commitHash,
-            digest: captured.digest,
-            sourceWorkspaceId: request.workspaceId,
-            sourceDirectoryName: request.sourceDirectoryName,
-            frozenAt,
-        };
+        let candidate;
+        let source;
         try {
-            if (request.persist === 'remote_ref') {
-                if (!binding?.repositoryUrl)
-                    throw new Error('batch_source_push_failed');
-                const ref = batchSourceRemoteRef(request.batchId);
-                await pushHiddenRef(cache, source, binding.repositoryUrl, captured.commitHash, ref);
-                snapshot.remoteRef = ref;
+            const pending = await readSourceCandidate(state, request.batchId);
+            const existing = await readSnapshot(state, request.batchId);
+            if (existing) {
+                assertSourceIdentity(state, request, existing, pending);
+                return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: existing });
+            }
+            if (!pending && 'resumeOnly' in request && request.resumeOnly === true) {
+                throw await sourceFreezeError(state, request.batchId, { code: 'batch_source_candidate_lost', stage: 'capture', retryable: false, outcome: 'unknown' });
             }
+            if (pending)
+                assertSourceIdentity(state, request, pending.snapshot, pending);
+            source = await workspaceRoot(state, request.workspaceId, request.sourceDirectoryName);
+            if (pending)
+                candidate = pending;
             else {
-                const key = `workspaces/${request.workspaceId}/batches/${request.batchId}/source/${captured.digest}.json.gz`;
-                const store = options?.objectStore ?? filesystemObjectStore(state);
-                try {
-                    await store.put(key, await archiveSource(cache, captured));
-                }
-                catch (error) {
-                    if (error instanceof Error && error.message === 'batch_object_key_invalid')
-                        throw error;
-                    throw new Error('batch_source_upload_failed');
-                }
-                snapshot.artifactKey = key;
+                const percent = Math.min(100, Math.max(0, options?.usagePercent ?? await usagePercent(source)));
+                if (workspaceDiskAdmission(percent) === 'paused')
+                    throw new Error('disk_admission_paused');
+                await stopManagedWriters(state, request.workspaceId, request.sourceDirectoryName);
+                const cache = sourceCacheDir(state, request.batchId);
+                await rm(cache, { recursive: true, force: true });
+                const captured = await captureIndependentSource(source, cache);
+                await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
+                const binding = state.journal.getWorkspace(request.workspaceId);
+                const snapshot = {
+                    batchId: request.batchId, commitHash: captured.commitHash, digest: captured.digest,
+                    sourceWorkspaceId: request.workspaceId, sourceDirectoryName: request.sourceDirectoryName,
+                    frozenAt: new Date((await gitRead(cache, ['show', '-s', '--format=%cI', 'HEAD'])).trim()).toISOString(),
+                    ...(request.persist === 'remote_ref' ? { remoteRef: batchSourceRemoteRef(request.batchId) }
+                        : { artifactKey: `workspaces/${request.workspaceId}/batches/${request.batchId}/source/${captured.digest}.json.gz` }),
+                };
+                candidate = {
+                    version: 1, persist: request.persist, repositoryUrl: binding?.repositoryUrl ?? undefined, projectId: binding?.projectId,
+                    branchName: request.sourceDirectoryName === 'basic' ? binding?.branchName ?? undefined
+                        : binding?.directories?.find(directory => directory.directoryName === request.sourceDirectoryName)?.branchName ?? undefined,
+                    snapshot,
+                };
+                await writeSourceCandidate(state, candidate);
             }
         }
         catch (error) {
-            await rm(cache, { recursive: true, force: true });
-            await rm(`${cache}.digest`, { force: true });
-            throw error;
+            if (error instanceof BatchSourceFreezeError)
+                throw error;
+            const known = new Set(['disk_admission_paused', 'disk_usage_unavailable', 'batch_source_changed', 'batch_source_path_invalid',
+                'workspace_not_registered', 'batch_source_identity_mismatch', 'batch_source_snapshot_mismatch']);
+            const code = error instanceof Error && known.has(error.message) ? error.message : 'batch_source_capture_failed';
+            throw await sourceFreezeError(state, request.batchId, {
+                code, stage: 'capture', retryable: !['batch_source_path_invalid', 'batch_source_identity_mismatch', 'batch_source_snapshot_mismatch'].includes(code),
+                outcome: code === 'batch_source_identity_mismatch' || code === 'batch_source_snapshot_mismatch' ? 'unknown' : 'not_published',
+            }, error);
+        }
+        await publishSourceCandidate(state, candidate, source, options?.objectStore ?? filesystemObjectStore(state));
+        try {
+            await writeSnapshot(state, candidate.snapshot);
+        }
+        catch (error) {
+            throw await sourceFreezeError(state, request.batchId, { code: 'batch_source_verification_failed', stage: 'verify', retryable: true, outcome: 'unknown' }, error);
         }
-        if (!await lstat(join(cache, '.git')).catch(() => undefined))
-            throw new Error('batch_source_capture_failed');
-        await writeSnapshot(state, snapshot);
-        return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot });
+        return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: candidate.snapshot });
     });
 }

package/dist/workspace-runtime/batch/generate.js

@@ -5,6 +5,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { hashOperationPayload, operationScopeKey, sandboxBatchMemberGenerateSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { attachNativeCollector, executeOperation } from '../server/dispatch.js';
 import { workspaceRoot } from '../workspaces/registry.js';
+import { snapshotWorkspaceTree } from '../workspaces/git.js';
+import { requireBatchContentChanges } from './content-changes.js';
 import { bindMemberPolicy, memberExecutionPolicy } from './policy.js';
 import { groupExited, stopProcessGroup } from './processes.js';
 import { memberStatus, readMember, readStopMarker, serializeRun, writeMember } from './records.js';
@@ -83,12 +85,15 @@ export async function generateBatchMember(state, body) {
         const prior = state.journal.getOperation(turnKey.scopeKey);
         if (prior && prior.payloadHash !== turnKey.record.payloadHash)
             throw new Error('batch_command_conflict');
+        const sourceCommit = existing?.sourceCommit ?? state.journal.getWorkspace(command.workspaceId)?.directories?.find(directory => directory.directoryName === command.directoryName)?.sourceCommit;
+        const beforeTree = existing?.beforeTree ?? (prior ? sourceCommit : await snapshotWorkspaceTree(root));
         let record = await writeMember(state, {
             runId: command.runId, ownerFence: command.ownerFence, occupancyId: command.occupancyId, workspaceId: command.workspaceId,
             directoryName: command.directoryName, phase: 'generate', state: prior ? (prior.status === 'uncertain' ? 'unknown' : prior.status === 'completed' ? 'completed' : 'running') : 'running',
             writersStopped: false, holding: true, stopRequested: false, processes: existing?.processes ?? [], sessionId,
             operationId: prior?.operationId, commandHash: { ...existing?.commandHash, generate: hash },
             snapshotDigest: existing?.snapshotDigest, branchName: existing?.branchName, headCommit: existing?.headCommit,
+            sourceCommit, beforeTree,
             updatedAt: new Date().toISOString(),
         });
         if (prior)
@@ -172,8 +177,7 @@ async function finishGenerate(state, record, started, root, early) {
             return writeMember(state, { ...record, state: 'stopping', writersStopped: false, holding: true, operationId: started.operationId });
         if (await readStopMarker(state, record.runId))
             return stoppedRecord(state, record, record);
-        const head = await import('./git.js').then(git => git.gitRead(root, ['rev-parse', 'HEAD'])).then(value => value.trim()).catch(() => record.headCommit);
-        return writeMember(state, { ...record, state: 'completed', writersStopped: true, holding: true, operationId: started.operationId, headCommit: head, error: undefined });
+        return completeGeneration(state, { ...record, operationId: started.operationId }, root);
     }
     const writersStopped = await proveStopped(record);
     return writeMember(state, {
@@ -187,11 +191,27 @@ async function reconcileGenerate(state, record) {
     if (record.state === 'unknown' && session?.turnStatus === 'completed') {
         const writersStopped = await proveStopped(record);
         if (writersStopped && !await readStopMarker(state, record.runId)) {
-            return writeMember(state, { ...record, state: 'completed', writersStopped: true, holding: true, error: undefined });
+            const root = await workspaceRoot(state, record.workspaceId, record.directoryName);
+            return completeGeneration(state, record, root);
         }
     }
     return record;
 }
+async function completeGeneration(state, record, root) {
+    try {
+        const afterTree = await snapshotWorkspaceTree(root);
+        await requireBatchContentChanges(root, record.beforeTree ?? '', afterTree);
+        await requireBatchContentChanges(root, record.sourceCommit ?? '', afterTree);
+    }
+    catch (error) {
+        const code = error instanceof Error && /^[a-z0-9_]+$/.test(error.message) ? error.message : 'batch_generation_failed';
+        return writeMember(state, { ...record, state: 'failed', writersStopped: true, holding: false, error: code });
+    }
+    if (await readStopMarker(state, record.runId))
+        return stoppedRecord(state, record, record);
+    const head = await import('./git.js').then(git => git.gitRead(root, ['rev-parse', 'HEAD'])).then(value => value.trim()).catch(() => record.headCommit);
+    return writeMember(state, { ...record, state: 'completed', writersStopped: true, holding: true, headCommit: head, error: undefined });
+}
 async function stoppedRecord(state, command, existing) {
     if (existing)
         await proveStopped(existing);
@@ -201,5 +221,6 @@ async function stoppedRecord(state, command, existing) {
         stopRequested: true, processes: existing?.processes ?? [], sessionId: existing?.sessionId, operationId: existing?.operationId,
         headCommit: existing?.headCommit, evidence: existing?.evidence, commandHash: existing?.commandHash, snapshotDigest: existing?.snapshotDigest,
         branchName: existing?.branchName, updatedAt: new Date().toISOString(),
+        sourceCommit: existing?.sourceCommit, beforeTree: existing?.beforeTree,
     });
 }

package/dist/workspace-runtime/batch/occupancy.js

@@ -1,6 +1,6 @@
 import { listMembers } from './records.js';
 /** True while a member Run still holds the directory. Other sandbox write entries must refuse it. */
-export async function batchDirectoryHeld(state, workspaceId, directoryName) {
+export async function batchDirectoryHeld(state, workspaceId, directoryName = 'basic') {
     if (!workspaceId)
         return false;
     const members = await listMembers(state);

package/dist/workspace-runtime/batch/prepare.js

@@ -140,6 +140,7 @@ export async function prepareBatchMember(state, body, options) {
             workspaceId: command.workspaceId, directoryName: command.directoryName, phase: 'prepare', state: 'running',
             writersStopped: false, holding: true, stopRequested: false, processes: existing?.processes ?? [],
             commandHash: { ...existing?.commandHash, prepare: hash }, snapshotDigest: snapshot.digest, branchName: command.branchName,
+            sourceCommit: snapshot.commitHash, beforeTree: existing?.beforeTree,
             updatedAt: new Date().toISOString(),
         });
         const parent = await workspaceContainerRoot(state, command.workspaceId);
@@ -197,6 +198,7 @@ async function sealStopped(state, command, existing) {
         state: 'stopped', writersStopped: true, holding: false, stopRequested: true, processes: existing?.processes ?? [],
         sessionId: existing?.sessionId, operationId: existing?.operationId, headCommit: existing?.headCommit, evidence: existing?.evidence,
         commandHash: existing?.commandHash, snapshotDigest: existing?.snapshotDigest, branchName: existing?.branchName,
+        sourceCommit: existing?.sourceCommit, beforeTree: existing?.beforeTree,
         updatedAt: new Date().toISOString(),
     });
 }

package/dist/workspace-runtime/batch/routes.js

@@ -4,6 +4,7 @@ import { deliverBatchMember } from './deliver.js';
 import { freezeBatchSource } from './freeze.js';
 import { generateBatchMember } from './generate.js';
 import { prepareBatchMember } from './prepare.js';
+import { BatchSourceFreezeError } from './source-failure.js';
 const CLIENT_ERRORS = new Set([
     'occupancy_required', 'invalid_batch_request', 'batch_branch_invalid', 'stale_owner', 'disk_admission_paused',
     'batch_source_push_failed', 'batch_source_upload_failed', 'batch_source_changed', 'batch_source_path_invalid',
@@ -49,6 +50,8 @@ export async function dispatchBatchRoute(state, request, url) {
         return undefined;
     }
     catch (error) {
+        if (error instanceof BatchSourceFreezeError)
+            return { status: 409, body: { error: error.message, failure: error.failure } };
         const code = error instanceof Error && CLIENT_ERRORS.has(error.message) ? error.message : undefined;
         if (!code)
             throw error;

package/dist/workspace-runtime/batch/source-candidate.js

@@ -0,0 +1,86 @@
+import { randomUUID } from 'node:crypto';
+import { link, mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { batchSourceSnapshotRefSchema, } from '@playcraft/common/cloud-workspace/runtime';
+export function sourceCandidateFile(state, batchId) {
+    return join(state.config.stateDir, 'batch-source-candidates', `${batchId}.json`);
+}
+export async function readSourceCandidate(state, batchId) {
+    let body;
+    try {
+        body = await readFile(sourceCandidateFile(state, batchId), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let stored;
+    try {
+        stored = JSON.parse(body);
+    }
+    catch {
+        throw new Error('batch_source_snapshot_mismatch');
+    }
+    if (!stored || stored.version !== 1 || !['remote_ref', 'artifact'].includes(stored.persist)
+        || (stored.repositoryUrl !== undefined && typeof stored.repositoryUrl !== 'string')
+        || (stored.projectId !== undefined && stored.projectId !== null && typeof stored.projectId !== 'string')
+        || (stored.branchName !== undefined && typeof stored.branchName !== 'string'))
+        throw new Error('batch_source_snapshot_mismatch');
+    const parsed = batchSourceSnapshotRefSchema.safeParse(stored.snapshot);
+    if (!parsed.success)
+        throw new Error('batch_source_snapshot_mismatch');
+    const snapshot = parsed.data;
+    if (snapshot.batchId !== batchId)
+        throw new Error('batch_source_identity_mismatch');
+    return { ...stored, snapshot };
+}
+/** The immutable candidate is committed to disk before any request can publish its commit. */
+export async function writeSourceCandidate(state, candidate) {
+    const path = sourceCandidateFile(state, candidate.snapshot.batchId);
+    const directory = join(path, '..');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(candidate));
+        await handle.sync();
+        await handle.close();
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const existing = await readSourceCandidate(state, candidate.snapshot.batchId);
+            if (JSON.stringify(existing) !== JSON.stringify(candidate))
+                throw new Error('batch_source_identity_mismatch');
+        }
+        const folder = await open(directory, 'r');
+        try {
+            await folder.sync();
+        }
+        finally {
+            await folder.close();
+        }
+    }
+    finally {
+        await handle.close();
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+export function assertSourceIdentity(state, request, snapshot, candidate) {
+    const binding = state.journal.getWorkspace(request.workspaceId);
+    const branchName = request.sourceDirectoryName === 'basic' ? binding?.branchName
+        : binding?.directories?.find(directory => directory.directoryName === request.sourceDirectoryName)?.branchName;
+    if (snapshot.batchId !== request.batchId || snapshot.sourceWorkspaceId !== request.workspaceId
+        || snapshot.sourceDirectoryName !== request.sourceDirectoryName
+        || (request.persist === 'remote_ref' ? !snapshot.remoteRef || Boolean(snapshot.artifactKey) : !snapshot.artifactKey || Boolean(snapshot.remoteRef))
+        || (candidate && (candidate.persist !== request.persist || candidate.repositoryUrl !== (binding?.repositoryUrl ?? undefined)
+            || candidate.projectId !== binding?.projectId || candidate.branchName !== (branchName ?? undefined)
+            || candidate.snapshot.commitHash !== snapshot.commitHash || candidate.snapshot.digest !== snapshot.digest
+            || candidate.snapshot.frozenAt !== snapshot.frozenAt || candidate.snapshot.remoteRef !== snapshot.remoteRef
+            || candidate.snapshot.artifactKey !== snapshot.artifactKey))) {
+        throw new Error('batch_source_identity_mismatch');
+    }
+}

package/dist/workspace-runtime/batch/source-failure.js

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class BatchSourceFreezeError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.code);
+        this.failure = failure;
+        this.name = 'BatchSourceFreezeError';
+    }
+}
+/** Diagnostics keep the upstream reason without command arguments, authentication or remote addresses. */
+function redactedReason(error) {
+    const detail = error;
+    const text = typeof detail?.stderr === 'string' || typeof detail?.stdout === 'string'
+        ? `${typeof detail.stderr === 'string' ? detail.stderr : ''}\n${typeof detail.stdout === 'string' ? detail.stdout : ''}`
+        : typeof detail?.message === 'string' ? detail.message : 'unknown';
+    return text
+        .replace(/https?:\/\/[^\s<>"']+/gi, '<remote>')
+        .replace(/\b(Bearer|Basic)\s+[^\s,;"']+/gi, '$1 <redacted>')
+        .replace(/((?:password|token|secret|authorization|credential)\s*[:=]\s*)[^\s,;"']+/gi, '$1<redacted>')
+        .replace(/\b(?:gh[pousr]_|github_pat_|glpat-)[A-Za-z0-9_-]+/g, '<redacted>')
+        .slice(0, 16_384);
+}
+export async function sourceFreezeError(state, batchId, failure, cause) {
+    if (cause === undefined)
+        return new BatchSourceFreezeError(failure);
+    const diagnosticId = randomUUID();
+    const directory = join(state.config.stateDir, 'batch-source-diagnostics');
+    const detail = cause;
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(join(directory, `${diagnosticId}.json`), JSON.stringify({
+            diagnosticId, batchId, ...failure, recordedAt: new Date().toISOString(), reason: redactedReason(cause),
+            exitCode: typeof detail?.code === 'number' ? detail.code : undefined,
+            signal: typeof detail?.signal === 'string' && /^SIG[A-Z]+$/.test(detail.signal) ? detail.signal : undefined,
+        }), { mode: 0o600, flag: 'wx' });
+        return new BatchSourceFreezeError({ ...failure, diagnosticId });
+    }
+    catch {
+        return new BatchSourceFreezeError(failure);
+    }
+}

package/dist/workspace-runtime/batch/source-publish.js

@@ -0,0 +1,132 @@
+import { lstat, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
+import { archiveSource, digestFiles, readSourceFiles, restoreArchive } from './source-capture.js';
+import { sourceCacheDir } from './records.js';
+import { BatchSourceFreezeError, sourceFreezeError } from './source-failure.js';
+async function reject(state, candidate, code, stage, retryable, outcome, cause) {
+    throw await sourceFreezeError(state, candidate.snapshot.batchId, { code, stage, retryable, outcome }, cause);
+}
+async function verifyCache(cache, candidate) {
+    if ((await gitRead(cache, ['rev-parse', '--verify', 'HEAD']).catch(() => '')).trim() !== candidate.snapshot.commitHash)
+        return false;
+    return digestFiles(await readSourceFiles(cache)) === candidate.snapshot.digest;
+}
+function pushFailureCode(error) {
+    const detail = error;
+    return /not support[^\n]*(?:ref|push)|unsupported[^\n]*(?:ref|namespace)/i.test(`${detail?.stderr ?? ''}\n${detail?.stdout ?? ''}`)
+        ? 'batch_source_ref_unsupported' : 'batch_source_push_failed';
+}
+function definitelyRejected(error) {
+    const detail = error;
+    return /remote rejected|\[rejected\]|authentication failed|access denied|permission denied|not allowed|not support|hook declined|protected|returned error: (?:401|403)/i
+        .test(`${detail?.stderr ?? ''}\n${detail?.stdout ?? ''}`);
+}
+async function publishRemote(state, candidate, source) {
+    const { snapshot, repositoryUrl: remote } = candidate;
+    const cache = sourceCacheDir(state, snapshot.batchId);
+    if (!remote || !snapshot.remoteRef)
+        return reject(state, candidate, 'batch_source_push_failed', 'publish', false, 'not_published');
+    await mkdir(cache, { recursive: true, mode: 0o700 });
+    if (!await lstat(join(cache, '.git')).catch(() => undefined))
+        await gitWrite(cache, ['init', '--initial-branch', 'source']);
+    await copyCredentialHelpers(source, cache);
+    // All remote operations share the copied authentication, including read-only verification.
+    const remoteHash = async () => {
+        const output = await gitWrite(cache, ['ls-remote', '--refs', remote, snapshot.remoteRef]);
+        const rows = output.trim().split('\n').filter(Boolean).map(line => line.split(/\s+/));
+        if (rows.some(([hash, ref]) => !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(hash) || ref !== snapshot.remoteRef) || rows.length > 1) {
+            throw new Error('batch_source_remote_response_invalid');
+        }
+        return rows[0]?.[0];
+    };
+    let found;
+    try {
+        found = await remoteHash();
+    }
+    catch (error) {
+        return reject(state, candidate, 'batch_source_verification_failed', 'verify', true, 'unknown', error);
+    }
+    if (found && found !== snapshot.commitHash)
+        return reject(state, candidate, 'batch_source_ref_conflict', 'verify', false, 'unknown');
+    if (!found) {
+        if (!await verifyCache(cache, candidate))
+            return reject(state, candidate, 'batch_source_candidate_lost', 'capture', false, 'not_published');
+        let pushError;
+        try {
+            await gitWrite(cache, ['push', '--porcelain', remote, `${snapshot.commitHash}:${snapshot.remoteRef}`]);
+        }
+        catch (error) {
+            pushError = error;
+        }
+        try {
+            found = await remoteHash();
+        }
+        catch (error) {
+            const unsupported = pushError !== undefined && pushFailureCode(pushError) === 'batch_source_ref_unsupported';
+            return reject(state, candidate, pushError ? pushFailureCode(pushError) : 'batch_source_verification_failed', pushError ? 'publish' : 'verify', !unsupported, unsupported ? 'not_published' : 'unknown', pushError ?? error);
+        }
+        if (found && found !== snapshot.commitHash)
+            return reject(state, candidate, 'batch_source_ref_conflict', 'verify', false, 'unknown', pushError);
+        if (!found) {
+            const rejected = pushError !== undefined && definitelyRejected(pushError);
+            return reject(state, candidate, pushError ? pushFailureCode(pushError) : 'batch_source_verification_failed', pushError ? 'publish' : 'verify', !rejected, rejected ? 'not_published' : 'unknown', pushError);
+        }
+    }
+    if (!await verifyCache(cache, candidate)) {
+        try {
+            await gitWrite(cache, ['fetch', '--no-tags', remote, snapshot.remoteRef]);
+            if ((await gitRead(cache, ['rev-parse', 'FETCH_HEAD^{commit}'])).trim() !== snapshot.commitHash) {
+                return reject(state, candidate, 'batch_source_snapshot_mismatch', 'verify', false, 'unknown');
+            }
+            await gitWrite(cache, ['checkout', '--detach', snapshot.commitHash]);
+        }
+        catch (error) {
+            return reject(state, candidate, 'batch_source_verification_failed', 'verify', true, 'unknown', error);
+        }
+        if (!await verifyCache(cache, candidate))
+            return reject(state, candidate, 'batch_source_snapshot_mismatch', 'verify', false, 'unknown');
+    }
+    await writeFile(`${cache}.digest`, snapshot.digest, { mode: 0o600 });
+}
+async function publishArtifact(state, candidate, store) {
+    const { snapshot } = candidate;
+    const cache = sourceCacheDir(state, snapshot.batchId);
+    if (!snapshot.artifactKey)
+        return reject(state, candidate, 'batch_source_snapshot_mismatch', 'capture', false, 'not_published');
+    if (!await verifyCache(cache, candidate)) {
+        // A lost cache can only be restored from this candidate's already published archive.
+        try {
+            const archive = await store.get(snapshot.artifactKey);
+            await rm(cache, { recursive: true, force: true });
+            const restored = await restoreArchive(archive, cache, snapshot.digest);
+            if (restored.commitHash !== snapshot.commitHash)
+                return reject(state, candidate, 'batch_source_snapshot_mismatch', 'verify', false, 'unknown');
+        }
+        catch (error) {
+            return reject(state, candidate, 'batch_source_candidate_lost', 'capture', false, 'unknown', error);
+        }
+    }
+    else {
+        try {
+            await store.put(snapshot.artifactKey, await archiveSource(cache, snapshot));
+        }
+        catch (error) {
+            return reject(state, candidate, 'batch_source_upload_failed', 'publish', true, 'unknown', error);
+        }
+    }
+    await writeFile(`${cache}.digest`, snapshot.digest, { mode: 0o600 });
+}
+export async function publishSourceCandidate(state, candidate, source, store) {
+    try {
+        if (candidate.persist === 'remote_ref')
+            await publishRemote(state, candidate, source);
+        else
+            await publishArtifact(state, candidate, store);
+    }
+    catch (error) {
+        if (error instanceof BatchSourceFreezeError)
+            throw error;
+        throw await sourceFreezeError(state, candidate.snapshot.batchId, { code: 'batch_source_verification_failed', stage: 'verify', retryable: true, outcome: 'unknown' }, error);
+    }
+}