@withtruing/companion 0.13.3 → 0.14.1

package/dist/http-client.js

@@ -2,6 +2,7 @@
  * fetch (Node 20+, no dependency needed) — see package.json's engines field. */
 import { readFileSync } from 'node:fs';
 import { manifestHash } from './surface-mapper.js';
+import { WHOLE_READ_COMPANION_CAPABILITIES } from './whole-read-claims.js';
 const WHOAMI_TIMEOUT_MS = 15_000;
 const CLAIM_TIMEOUT_MS = 10_000;
 const HEARTBEAT_TIMEOUT_MS = 10_000;
@@ -9,6 +10,7 @@ const RESULT_TIMEOUT_MS = 60_000;
 const ERROR_REPORT_TIMEOUT_MS = 30_000;
 const PAIRING_TIMEOUT_MS = 15_000;
 const READINESS_TIMEOUT_MS = 10_000;
+const BUILD_RESULT_TIMEOUT_MS = 60_000;
 const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 if (typeof packageVersion !== 'string' || !packageVersion) {
     throw new Error('companion/package.json does not contain a version');
@@ -23,9 +25,25 @@ export const COMPANION_CAPABILITIES = [
     'schema-entities@1',
     'verify-automatic-surface@1',
     'map-module-expansion@1',
+    ...WHOLE_READ_COMPANION_CAPABILITIES,
 ];
-const capabilityHeaders = () => ({
-    'X-Companion-Capabilities': COMPANION_CAPABILITIES.join(','),
+export const CLAUDE_CLI_FAST_MODEL = 'claude-haiku-5-5';
+export const CODEX_FAST_MODEL = 'gpt-5.6-luna';
+export const WHOLE_READ_FAST_MODEL_CAPABILITY = 'whole-read-fast-model@';
+export const WHOLE_READ_BACKEND_CAPABILITY = 'whole-read-backend@';
+/** The one mapping from a connection's backend to the name the server freezes and the readiness report uses. */
+export function wholeReadBackendName(backend) {
+    if (backend === 'api-key')
+        return 'anthropic_api';
+    if (backend === 'cli')
+        return 'claude_cli';
+    return 'codex';
+}
+export const capabilityHeaders = (fastModel, backend) => ({
+    'X-Companion-Capabilities': [...COMPANION_CAPABILITIES,
+        ...(fastModel && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(fastModel)
+            ? [`${WHOLE_READ_FAST_MODEL_CAPABILITY}${fastModel}`] : []),
+        ...(backend && /^[a-z_]{1,32}$/.test(backend) ? [`${WHOLE_READ_BACKEND_CAPABILITY}${backend}`] : [])].join(','),
 });
 export class CompanionHttpError extends Error {
     status;
@@ -52,9 +70,16 @@ export class PairingHttpError extends Error {
 export class CompanionClient {
     url;
     token;
-    constructor(url, token) {
+    fastModelsByConnection;
+    backendsByConnection;
+    constructor(url, token, fastModelsByConnection = {}, backendsByConnection = {}) {
         this.url = url;
         this.token = token;
+        this.fastModelsByConnection = fastModelsByConnection;
+        this.backendsByConnection = backendsByConnection;
+    }
+    capabilityHeaders(connectionId) {
+        return capabilityHeaders(connectionId ? this.fastModelsByConnection[connectionId] : undefined, connectionId ? this.backendsByConnection[connectionId] : undefined);
     }
     request(path, timeoutMs, init) {
         return fetch(`${this.url}${path}`, {
@@ -82,6 +107,68 @@ export class CompanionClient {
     whoami() {
         return this.call('/api/companion/whoami', WHOAMI_TIMEOUT_MS);
     }
+    listBuildAssignments() {
+        return this.call('/api/companion/builds/assignments', CLAIM_TIMEOUT_MS, {
+            headers: this.capabilityHeaders(),
+        });
+    }
+    acceptBuildAssignment(assignment, report) {
+        return this.call(`/api/companion/builds/assignments/${encodeURIComponent(assignment.id)}/accept`, BUILD_RESULT_TIMEOUT_MS, {
+            method: 'POST',
+            headers: this.capabilityHeaders(assignment.connectionId),
+            body: JSON.stringify({
+                assignmentRevision: assignment.assignmentRevision,
+                canonicalRepository: assignment.canonicalRepository,
+                snapshotSha: assignment.snapshotSha,
+                ...report,
+            }),
+        });
+    }
+    claimBuildUnit(assignment, input) {
+        return this.call(`/api/companion/builds/${encodeURIComponent(assignment.buildId)}/claim`, CLAIM_TIMEOUT_MS, {
+            method: 'POST',
+            headers: this.capabilityHeaders(assignment.connectionId),
+            body: JSON.stringify({ assignmentId: assignment.id,
+                assignmentRevision: assignment.assignmentRevision, ...input }),
+        });
+    }
+    buildAttemptPath(claim) {
+        return `/api/companion/builds/${encodeURIComponent(claim.buildId)}`
+            + `/assignments/${encodeURIComponent(claim.assignmentId)}`
+            + `/units/${encodeURIComponent(claim.unitId)}/attempts/${encodeURIComponent(claim.attemptId)}`;
+    }
+    putBuildResultPage(claim, page) {
+        return this.call(`${this.buildAttemptPath(claim)}/pages`, BUILD_RESULT_TIMEOUT_MS, {
+            method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({
+                claimToken: claim.claimToken, controlRevision: claim.controlRevision,
+                assignmentRevision: claim.assignmentRevision, page,
+            }),
+        });
+    }
+    sealBuildResult(claim, value) {
+        return this.call(`${this.buildAttemptPath(claim)}/seal`, BUILD_RESULT_TIMEOUT_MS, {
+            method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({
+                claimToken: claim.claimToken, controlRevision: claim.controlRevision,
+                assignmentRevision: claim.assignmentRevision, ...value,
+            }),
+        });
+    }
+    acceptBuildResult(claim, value) {
+        return this.call(`${this.buildAttemptPath(claim)}/result`, BUILD_RESULT_TIMEOUT_MS, {
+            method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({
+                claimToken: claim.claimToken, controlRevision: claim.controlRevision,
+                assignmentRevision: claim.assignmentRevision, ...value,
+            }),
+        });
+    }
+    reportBuildError(claim, failure, usage) {
+        return this.call(`${this.buildAttemptPath(claim)}/error`, ERROR_REPORT_TIMEOUT_MS, {
+            method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({
+                claimToken: claim.claimToken, controlRevision: claim.controlRevision,
+                assignmentRevision: claim.assignmentRevision, failure, ...(usage === undefined ? {} : { usage }),
+            }),
+        });
+    }
     async githubToken(repo) {
         try {
             const response = await this.call('/api/companion/github-token', CLAIM_TIMEOUT_MS, { method: 'POST', body: JSON.stringify({ repo }) });
@@ -101,7 +188,7 @@ export class CompanionClient {
     claimNext(connectionId) {
         return this.call(connectionId
             ? `/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}`
-            : '/api/companion/tasks/next', CLAIM_TIMEOUT_MS, { headers: capabilityHeaders() });
+            : '/api/companion/tasks/next', CLAIM_TIMEOUT_MS, { headers: this.capabilityHeaders(connectionId) });
     }
     async claimNextInvestigation() {
         const response = await this.request('/api/companion/investigations/next', CLAIM_TIMEOUT_MS, {
@@ -182,14 +269,24 @@ export class CompanionClient {
             }),
         });
     }
-    heartbeat(taskId) {
-        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, HEARTBEAT_TIMEOUT_MS, { method: 'POST' });
+    heartbeatSurfaceMapping(job) {
+        return this.call(`/api/companion/surface-mappings/${encodeURIComponent(job.jobId)}/heartbeat`, HEARTBEAT_TIMEOUT_MS, {
+            method: 'POST',
+            headers: {
+                'X-Companion-Version': COMPANION_VERSION,
+                ...capabilityHeaders(),
+            },
+            body: JSON.stringify({ attempt: job.attempt, claimToken: job.claimToken }),
+        });
+    }
+    heartbeat(taskId, claimToken) {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, HEARTBEAT_TIMEOUT_MS, { method: 'POST', ...(claimToken ? { body: JSON.stringify({ claimToken }) } : {}) });
     }
-    reportResult(taskId, result, filesRead, snapshot) {
+    reportResult(taskId, result, filesRead, snapshot, claimToken) {
         return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/result`, RESULT_TIMEOUT_MS, {
             method: 'POST',
             headers: capabilityHeaders(),
-            body: JSON.stringify({ result, filesRead, ...(snapshot ? { snapshot } : {}) }),
+            body: JSON.stringify({ result, filesRead, ...(snapshot ? { snapshot } : {}), ...(claimToken ? { claimToken } : {}) }),
         });
     }
     reportGitRangeResult(taskId, result) {
@@ -199,8 +296,8 @@ export class CompanionClient {
         }
         return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/result`, RESULT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body });
     }
-    reportError(taskId, error) {
-        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/error`, ERROR_REPORT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({ error }) });
+    reportError(taskId, error, claimToken) {
+        return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/error`, ERROR_REPORT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body: JSON.stringify({ error, ...(claimToken ? { claimToken } : {}) }) });
     }
     reportInvestigationResult(investigationId, result) {
         return this.call(`/api/companion/investigations/${encodeURIComponent(investigationId)}/result`, RESULT_TIMEOUT_MS, { method: 'POST', headers: capabilityHeaders(), body: JSON.stringify(result) });

package/dist/investigation-reader.js

@@ -4,7 +4,7 @@ import { readFile, lstat, stat } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 import { listRepoFiles } from './local-scan.js';
-import { obtainRequestedSources } from './observed-sources.js';
+import { obtainRequestedSources, } from './observed-sources.js';
 import { scopeCovers, validateReaderResult } from './reader-result-contract.js';
 import { gitErrorMessage } from './sandbox.js';
 import { isUsageLimitError } from './usage-limit.js';
@@ -1152,7 +1152,7 @@ async function enumerateTrees(request, obtained) {
 }
 export async function runInvestigation(request, connections, callModel, reportDiagnostic = (diagnostic) => {
     console.error(formatInvestigationReaderDiagnostic(diagnostic));
-}, execution) {
+}, execution, sourceAcquisition) {
     if (request.policyVersion === 'policy-4' && !execution) {
         throw new MissingPolicy4ExecutionError();
     }
@@ -1160,7 +1160,7 @@ export async function runInvestigation(request, connections, callModel, reportDi
     let observedSources = [];
     let evidence = [];
     try {
-        obtained = await obtainRequestedSources(request, connections);
+        obtained = await obtainRequestedSources(request, connections, sourceAcquisition);
         observedSources = obtained.observedSources;
         if (obtained.unavailable) {
             return honestResult(request, observedSources, evidence, 'source_identity_unavailable', execution);
@@ -1173,17 +1173,20 @@ export async function runInvestigation(request, connections, callModel, reportDi
             if (!sandbox)
                 return honestResult(request, observedSources, evidence, 'files_unreadable', execution);
             const reads = await readSurfaceEvidence(request, sandbox);
+            obtained.assertAvailable();
             evidence = reads.map((read) => read.evidence);
             const retrievalReason = surfaceRetrievalReason(evidence);
             if (retrievalReason)
                 return honestResult(request, observedSources, evidence, retrievalReason, execution);
+            const assessments = await assessCompleteSurface(request, observedSources, reads, callModel, reportDiagnostic, execution);
+            obtained.assertAvailable();
             const result = {
                 investigationId: request.investigationId,
                 attempt: request.attempt,
                 resultKey: resultKeyFor(request),
                 observedSources,
                 evidence,
-                assessments: ensureAutomaticClaimShapes(request, await assessCompleteSurface(request, observedSources, reads, callModel, reportDiagnostic, execution)),
+                assessments: ensureAutomaticClaimShapes(request, assessments),
                 execution: { ...execution },
             };
             try {
@@ -1214,6 +1217,7 @@ export async function runInvestigation(request, connections, callModel, reportDi
                 schema: selectionSchema,
             });
             selected = filterSelectedPaths(selection, trees);
+            obtained.assertAvailable();
         }
         catch (error) {
             const treeFileCount = trees.reduce((count, tree) => count + tree.paths.length, 0);
@@ -1223,6 +1227,7 @@ export async function runInvestigation(request, connections, callModel, reportDi
             return honestResult(request, observedSources, evidence, 'no_plausible_path');
         }
         const reads = await readSelectedEvidence(request, selected, obtained.sandboxes);
+        obtained.assertAvailable();
         const budgeted = buildBudgetedAssessmentPrompt(request, reads);
         evidence = budgeted.reads.map((read) => read.evidence);
         if (budgeted.prompt === null) {
@@ -1257,6 +1262,7 @@ export async function runInvestigation(request, connections, callModel, reportDi
                 prompt: assessmentPrompt,
                 schema: assessmentResponseSchema,
             });
+            obtained.assertAvailable();
         }
         catch (error) {
             return honestResult(request, observedSources, evidence, reasonForModelFailure(error, 'assessment', assessmentPrompt, budgeted.reads.length, reportDiagnostic));
@@ -1293,11 +1299,11 @@ export async function runInvestigation(request, connections, callModel, reportDi
         await obtained?.cleanup();
     }
 }
-export async function runAndReportInvestigation(request, connections, callModel, report, reportDiagnostic, execution) {
+export async function runAndReportInvestigation(request, connections, callModel, report, reportDiagnostic, execution, sourceAcquisition) {
     if (request.policyVersion === 'policy-4' && !execution) {
         throw new MissingPolicy4ExecutionError();
     }
-    const result = await runInvestigation(request, connections, callModel, reportDiagnostic, execution);
+    const result = await runInvestigation(request, connections, callModel, reportDiagnostic, execution, sourceAcquisition);
     await report(result);
     return result;
 }

package/dist/managed-repo.js

@@ -8,6 +8,7 @@
  */
 import { spawn } from 'node:child_process';
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { lstat, realpath, rm } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { parseRemoteUrl } from './local-scan.js';
 export class ManagedRepoError extends Error {
@@ -84,6 +85,20 @@ export function labelFromCopyPath(repoPath) {
     const match = /^github\.com__(.+?)__(.+)$/.exec(basename(repoPath));
     return match ? `${match[1]}/${match[2]}` : basename(repoPath);
 }
+/** Reads a managed repository's durable identity, with the old label/path convention retained
+ *  only as a compatibility fallback for configs that have not entered the B38 migration yet. */
+export function configuredManagedRepository(connection) {
+    if (connection.repository) {
+        if (connection.repository.host !== 'github.com' || connection.repository.port !== null) {
+            throw new ManagedRepoError(NOT_GITHUB_MESSAGE);
+        }
+        return parseGitHubRepo(connection.repository.path);
+    }
+    return parseGitHubRepo(connection.label ?? labelFromCopyPath(connection.repoPath));
+}
+export function usesTemporaryManagedStorage(connection) {
+    return connection.managed === true && connection.repositoryStorage === 'temporary';
+}
 const MAX_CAPTURED_STDERR = 16_384;
 /** `stdio: 'inherit'` lets Git (and Git Credential Manager) talk to the person directly; stderr
  *  is still teed to the terminal and captured so a failure can be explained in one line. */
@@ -201,6 +216,10 @@ export function watchManagedCopy(repoPath, label, log, getToken) {
 export function forgetManagedCopies() {
     watchedCopies.clear();
 }
+/** Stops background reporting for one copy before its retirement starts. */
+export function forgetManagedCopy(repoPath) {
+    watchedCopies.delete(watchKey(repoPath));
+}
 async function tokenFrom(getToken) {
     if (!getToken)
         return null;
@@ -389,6 +408,119 @@ export async function removeManagedCopy(repoPath, reposDir) {
     rmSync(managedStatePath(target), { force: true });
     return true;
 }
+export class ManagedCopyRetirementError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'ManagedCopyRetirementError';
+    }
+}
+async function pathMissing(path) {
+    try {
+        await lstat(path);
+        return false;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        throw error;
+    }
+}
+function hasManagedCopyMarker(repoPath) {
+    try {
+        const marker = JSON.parse(readFileSync(managedStatePath(repoPath), 'utf8'));
+        return marker !== null
+            && typeof marker === 'object'
+            && !Array.isArray(marker)
+            && typeof marker.signInNeeded === 'boolean'
+            && typeof marker.lastUpdatedAt === 'string'
+            && Number.isFinite(Date.parse(marker.lastUpdatedAt));
+    }
+    catch {
+        return false;
+    }
+}
+function normalizedPath(path) {
+    const absolute = resolve(path);
+    return process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+}
+async function validateManagedCopyTargetPath(repoPath, reposDir, repo) {
+    const root = resolve(reposDir);
+    const target = resolve(repoPath);
+    if (normalizedPath(target) !== normalizedPath(managedCopyPath(root, repo))) {
+        throw new ManagedCopyRetirementError('cleanup_path_outside_root');
+    }
+    if (await pathMissing(root))
+        return 'missing';
+    const rootStats = await lstat(root);
+    if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+        throw new ManagedCopyRetirementError('cleanup_unsafe_link');
+    }
+    if (await pathMissing(target))
+        return 'missing';
+    const targetStats = await lstat(target);
+    if (!targetStats.isDirectory() || targetStats.isSymbolicLink()) {
+        throw new ManagedCopyRetirementError('cleanup_unsafe_link');
+    }
+    const [canonicalRoot, canonicalTarget] = await Promise.all([realpath(root), realpath(target)]);
+    if (normalizedPath(join(canonicalRoot, basename(target))) !== normalizedPath(canonicalTarget)) {
+        throw new ManagedCopyRetirementError('cleanup_path_outside_root');
+    }
+    return 'present';
+}
+/** Validates the old clone from independent companion records before deletion. The target must be
+ *  the one deterministic child for this identity, have the state marker written on clone, and
+ *  still be the top of the expected Git repository. */
+async function validateManagedCopyRetirement(repoPath, reposDir, repo) {
+    const target = resolve(repoPath);
+    const presence = await validateManagedCopyTargetPath(repoPath, reposDir, repo);
+    if (presence === 'missing')
+        return presence;
+    if (!hasManagedCopyMarker(target)) {
+        throw new ManagedCopyRetirementError('cleanup_marker_missing');
+    }
+    if (!(await isCopyOf(target, repo))) {
+        throw new ManagedCopyRetirementError('cleanup_identity_mismatch');
+    }
+    return 'present';
+}
+/** Retires one validated historical managed clone. `onValidated` durably records cleanup_pending
+ *  before the first delete. Validation is repeated afterwards to close the write/delete race. */
+export async function retireManagedCopy(options, dependencies = {}) {
+    const wait = dependencies.wait
+        ?? ((delayMs) => new Promise((resolveWait) => setTimeout(resolveWait, delayMs)));
+    const retryDelaysMs = dependencies.retryDelaysMs ?? [25, 50, 100, 200];
+    const removeTree = dependencies.removeTree ?? ((path) => rm(path, { recursive: true, force: false }));
+    const initial = await validateManagedCopyRetirement(options.repoPath, options.reposDir, options.repo);
+    if (initial === 'missing') {
+        rmSync(managedStatePath(options.repoPath), { force: true });
+        return { cleanupAttempts: 0 };
+    }
+    await options.onValidated();
+    await validateManagedCopyRetirement(options.repoPath, options.reposDir, options.repo);
+    forgetManagedCopy(options.repoPath);
+    await runGit(options.repoPath, ['worktree', 'prune']);
+    for (let attempt = 1; attempt <= 5; attempt += 1) {
+        try {
+            const presence = await validateManagedCopyTargetPath(options.repoPath, options.reposDir, options.repo);
+            if (presence === 'present')
+                await removeTree(options.repoPath);
+            if (!(await pathMissing(options.repoPath)))
+                throw new Error('cleanup_delete_failed');
+            rmSync(managedStatePath(options.repoPath), { force: true });
+            return { cleanupAttempts: attempt };
+        }
+        catch (error) {
+            if (error instanceof ManagedCopyRetirementError)
+                throw error;
+            if (attempt < 5) {
+                await wait(retryDelaysMs[Math.min(attempt - 1, retryDelaysMs.length - 1)] ?? 0);
+            }
+        }
+    }
+    throw new ManagedCopyRetirementError('cleanup_delete_failed');
+}
 export function relativeTime(iso, now = new Date()) {
     if (!iso)
         return 'not yet';

package/dist/observed-sources.js

@@ -1,7 +1,18 @@
 import { createSandbox } from './sandbox.js';
+import { RepositoryProviderError, } from './repository-provider.js';
+const isPrdSource = (source) => source.kind === 'prd';
+function unavailableSource(source, reason) {
+    return {
+        sourceEntryId: source.sourceEntryId,
+        role: source.role,
+        connectionId: source.connectionId,
+        sourceIdentity: `unavailable:${reason}`,
+        obtainedBy: 'unavailable',
+    };
+}
 /** Resolve every immutable identity before exposing any worktree for reading. This prevents an
  * earlier source from being inspected before a later required source proves unavailable. */
-export async function obtainRequestedSources(request, connections) {
+export async function obtainRequestedSources(request, connections, acquisition) {
     const sourceEntryIds = new Set();
     for (const source of request.requestedSources) {
         if (sourceEntryIds.has(source.sourceEntryId)) {
@@ -11,13 +22,123 @@ export async function obtainRequestedSources(request, connections) {
     }
     const observedSources = [];
     const sandboxes = new Map();
+    const leases = new Map();
+    const leasesByIdentity = new Map();
+    const verifiedSources = new Set();
     const cleanup = async () => {
-        const pending = [...sandboxes.values()];
+        const pending = acquisition
+            ? [...new Set(leases.values())].map((lease) => () => lease.release().then(() => undefined))
+            : [...sandboxes.values()].map((sandbox) => () => sandbox.cleanup());
         sandboxes.clear();
-        await Promise.all(pending.map((sandbox) => sandbox.cleanup()));
+        leases.clear();
+        leasesByIdentity.clear();
+        const results = await Promise.allSettled(pending.map((release) => release()));
+        const failure = results.find((result) => result.status === 'rejected');
+        if (failure)
+            throw failure.reason;
     };
+    if (acquisition) {
+        let failureCode = null;
+        try {
+            await acquisition.repositoryProvider.sweepRepositories();
+            for (const source of request.requestedSources) {
+                if (isPrdSource(source))
+                    continue;
+                const connection = connections.find((candidate) => candidate.connectionId === source.connectionId);
+                if (!connection) {
+                    failureCode = 'source_identity_unavailable';
+                    break;
+                }
+                try {
+                    const identityKey = JSON.stringify([source.connectionId, source.commit]);
+                    const lease = leasesByIdentity.get(identityKey)
+                        ?? await acquisition.repositoryProvider.acquireRepository({
+                            connection,
+                            target: { kind: 'snapshot', sha: source.commit },
+                            owner: acquisition.owner,
+                            signal: acquisition.signal,
+                        });
+                    if (lease.identities.connectionId !== source.connectionId
+                        || lease.identities.source !== `commit:${source.commit}`
+                        || lease.identities.target.kind !== 'snapshot'
+                        || lease.identities.target.sha !== source.commit) {
+                        await lease.release();
+                        throw new RepositoryProviderError('snapshot_unavailable');
+                    }
+                    leasesByIdentity.set(identityKey, lease);
+                    leases.set(source.sourceEntryId, lease);
+                    verifiedSources.add(source.sourceEntryId);
+                }
+                catch (error) {
+                    failureCode = error instanceof RepositoryProviderError ? error.code : 'snapshot_unavailable';
+                    break;
+                }
+            }
+            if (failureCode === null) {
+                for (const source of request.requestedSources) {
+                    if (isPrdSource(source))
+                        continue;
+                    const lease = leases.get(source.sourceEntryId);
+                    try {
+                        const checkout = await lease.checkout();
+                        sandboxes.set(source.sourceEntryId, {
+                            target: 'requested_commit',
+                            obtainedBy: 'sandbox_worktree',
+                            path: checkout.path,
+                            resolvedCommit: checkout.commit,
+                            sourceIdentity: `commit:${checkout.commit}`,
+                            cleanup: () => lease.release().then(() => undefined),
+                        });
+                    }
+                    catch (error) {
+                        failureCode = error instanceof RepositoryProviderError ? error.code : 'snapshot_unavailable';
+                        break;
+                    }
+                }
+            }
+            if (failureCode !== null)
+                await cleanup();
+            for (const source of request.requestedSources) {
+                if (isPrdSource(source)) {
+                    // B31 document identities are already immutable and use their own content delivery path.
+                    observedSources.push({ ...source });
+                    continue;
+                }
+                const sandbox = sandboxes.get(source.sourceEntryId);
+                observedSources.push(sandbox || verifiedSources.has(source.sourceEntryId)
+                    ? {
+                        sourceEntryId: source.sourceEntryId,
+                        role: source.role,
+                        connectionId: source.connectionId,
+                        sourceIdentity: sandbox?.sourceIdentity ?? `commit:${source.commit}`,
+                        obtainedBy: 'sandbox_worktree',
+                    }
+                    : unavailableSource(source, failureCode ?? 'source_identity_unavailable'));
+            }
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+        return {
+            observedSources,
+            sandboxes,
+            unavailable: failureCode !== null,
+            assertAvailable() {
+                if (acquisition.signal.aborted)
+                    throw new RepositoryProviderError('repository_lease_lost');
+                for (const lease of new Set(leases.values()))
+                    lease.assertLive();
+            },
+            cleanup,
+        };
+    }
     try {
         for (const source of request.requestedSources) {
+            if (isPrdSource(source)) {
+                observedSources.push({ ...source });
+                continue;
+            }
             const connection = connections.find((candidate) => candidate.connectionId === source.connectionId);
             if (!connection) {
                 observedSources.push({
@@ -59,22 +180,27 @@ export async function obtainRequestedSources(request, connections) {
     return {
         observedSources,
         sandboxes,
-        unavailable: observedSources.some((source) => source.obtainedBy === 'unavailable'),
+        unavailable: observedSources.some((source) => 'obtainedBy' in source && source.obtainedBy === 'unavailable'),
+        assertAvailable() { },
         cleanup,
     };
 }
 /** Obtain each requested immutable source, optionally inspect it while its worktree is alive, and
  * return the observed-source half of a reader result. Every created worktree is cleaned in a
  * finally block, including when the inspection callback crashes. */
-export async function buildObservedSources(request, connections, inspectSource = async () => { }) {
-    const obtained = await obtainRequestedSources(request, connections);
+export async function buildObservedSources(request, connections, inspectSource = async () => { }, acquisition) {
+    const obtained = await obtainRequestedSources(request, connections, acquisition);
     try {
         if (!obtained.unavailable) {
+            obtained.assertAvailable();
             for (const source of request.requestedSources) {
+                if (isPrdSource(source))
+                    continue;
                 const sandbox = obtained.sandboxes.get(source.sourceEntryId);
                 if (!sandbox)
                     throw new Error(`No sandbox obtained for ${source.sourceEntryId}`);
                 await inspectSource(source, sandbox);
+                obtained.assertAvailable();
             }
         }
         return obtained.observedSources;