engineering-memory 1.11.4 → 1.11.5

package/runtime/dist/src/runtime/bridge-service.js

@@ -1,3 +1,5 @@
+import { validWorktreePolicy } from './worktree-policy.js';
+import { resolveTaskBase } from './branch-preferences.js';
 import { randomUUID } from 'node:crypto';
 import { lstat, readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
@@ -29,6 +31,7 @@ export const validationIds = [
 ];
 export class BridgeService {
     dependencies;
+    poolAllocations = new Map();
     taskQueues = new Map();
     deferDeliveries;
     backgroundDeliveries = new Set();
@@ -39,6 +42,9 @@ export class BridgeService {
         this.dependencies = dependencies;
         this.deferDeliveries = dependencies.deferDeliveries ?? true;
     }
+    managesWorktrees() {
+        return Boolean(this.dependencies.worktreePool);
+    }
     async questionnaireAsk(input, previousDefinitions = []) {
         const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
         const { repoRoot: _repoRoot, preparation: _preparation, ...definition } = input;
@@ -198,6 +204,17 @@ export class BridgeService {
                 ? null
                 : await this.requireBranchDecision(repository, input.externalTaskId);
             const branch = decision?.branch;
+            const poolAllocation = decision && this.dependencies.worktreePool
+                ? await this.dependencies.worktreePool.find(projectId, input.externalTaskId, repository.repoRoot)
+                : null;
+            if (poolAllocation) {
+                if (poolAllocation.repoRoot !== repository.repoRoot)
+                    throw refuse('Bootstrap in the allocated repoRoot.', 'session.resume');
+                await this.dependencies.worktreePool.assertOwnership(projectId, repository.repoRoot, poolAllocation.generation);
+                if (!poolAllocation.taskId && (source?.sourceCommit ?? null) !== poolAllocation.baseCommit)
+                    throw refuse('The chosen task base changed before bootstrap. Preserve the intervening commit and use task.branch with a new externalTaskId to choose it explicitly, or resume this allocation only when its recorded base is checked out. No Git state was reset.', 'task.branch');
+                this.poolAllocations.set(repository.repoRoot, poolAllocation);
+            }
             const checkpointId = deterministicUuid('session.bootstrap', projectId, repository.repoFingerprint, input.externalTaskId);
             const response = await this.dependencies.client.request(endpoints.sessionBootstrap, {
                 method: 'POST',
@@ -241,6 +258,11 @@ export class BridgeService {
                 await this.dependencies.repositories.git
                     .branchStore(repository.repoRoot)
                     .bind(projectId, input.externalTaskId, task.id);
+            if (poolAllocation) {
+                await this.dependencies.worktreePool.bind(projectId, repository.repoRoot, poolAllocation.generation, task.id);
+                poolAllocation.taskId = task.id;
+                this.poolAllocations.set(repository.repoRoot, poolAllocation);
+            }
             const pointer = {
                 repoFingerprint: repository.repoFingerprint,
                 projectId,
@@ -248,6 +270,7 @@ export class BridgeService {
                 taskSlug: input.externalTaskId,
                 source: sourceFromContext(task.sourceContext),
                 worktreeId: sha256(repository.repoRoot),
+                ...(poolAllocation ? { worktreeGeneration: poolAllocation.generation } : {}),
                 ...(decision
                     ? { branch: typeof task.branch === 'string' ? task.branch : decision.branch }
                     : {}),
@@ -365,10 +388,57 @@ export class BridgeService {
                 (repository.projectId && repository.projectId !== projectId)) {
                 throw refuse('The live task belongs to a different project than the one this repository is bound to.', 'project.resolve');
             }
+            if (pointer?.worktreeGeneration && this.dependencies.worktreePool) {
+                const pool = this.dependencies.worktreePool;
+                const previous = await pool.find(projectId, taskSlug, repository.repoRoot);
+                if (previous && previous.repoRoot !== repository.repoRoot)
+                    return asJsonValue({
+                        worktreeResumeRequired: true,
+                        repoRoot: previous.repoRoot,
+                        taskSlug,
+                        sessionId,
+                        nextAction: 'Call session.resume from this returned repoRoot and use it for every subsequent command.',
+                    });
+                const sourceCommit = previous?.baseCommit ?? pointer.source?.sourceCommit;
+                if ((!sourceCommit && !(previous && previous.baseCommit === null && !previous.managed)) ||
+                    pointer.branch === undefined)
+                    throw refuse('The task branch and base must be restored before resuming its worktree.', 'worktree.reconcile');
+                const allocation = await pool.allocate({
+                    projectId,
+                    projectName: projectId,
+                    repoFingerprint: repository.repoFingerprint,
+                    repoRoot: repository.repoRoot,
+                    externalTaskId: taskSlug,
+                    branch: pointer.branch,
+                    baseCommit: sourceCommit ?? null,
+                    keepCurrent: previous ? !previous.managed : false,
+                    resume: true,
+                }, await this.poolPolicy());
+                await pool.bind(projectId, allocation.repoRoot, allocation.generation, pointer.taskId);
+                allocation.taskId = pointer.taskId;
+                this.poolAllocations.set(allocation.repoRoot, allocation);
+                const oldGeneration = pointer.worktreeGeneration;
+                pointer = {
+                    ...pointer,
+                    worktreeId: sha256(allocation.repoRoot),
+                    worktreeGeneration: allocation.generation,
+                };
+                await this.dependencies.activeContexts.save(pointer);
+                if (allocation.repoRoot !== repository.repoRoot)
+                    return asJsonValue({
+                        worktreeResumeRequired: true,
+                        repoRoot: allocation.repoRoot,
+                        taskSlug,
+                        sessionId,
+                        nextAction: 'Resume in this allocated directory before editing. The task branch has been preserved.',
+                    });
+                await this.dependencies.gate.rebindWorktreeOwnership(repository.repoRoot, pointer.taskId, oldGeneration, allocation.generation);
+            }
             if (pointer?.closeIntent) {
                 const recoveredClose = await this.retryCloseIntent(repository, pointer);
                 return asJsonValue({
                     backend: { close: recoveredClose },
+                    worktree: this.poolAllocations.get(repository.repoRoot) ?? null,
                     pendingQuestionnaires,
                     repository: publicRepository(repository),
                     localJournal: await this.dependencies.journal.load(projectId, taskSlug),
@@ -407,11 +477,16 @@ export class BridgeService {
                 throw refuse('The backend resumed the session without the task it belongs to.', 'session.resume');
             }
             await this.assertTaskWorktree(repository, backendTask, pointer);
-            if (backendTask.status === 'closed' || backendTask.status === 'abandoned') {
+            if ((backendTask.status === 'closed' || backendTask.status === 'abandoned') &&
+                !pointer?.worktreeGeneration) {
                 await this.dependencies.repositories.git
                     .branchStore(repository.repoRoot)
                     .release(backendTask.id);
             }
+            if (backendTask.status === 'closed' &&
+                pointer?.worktreeGeneration &&
+                this.dependencies.worktreePool)
+                await this.dependencies.worktreePool.delivery(projectId, repository.repoRoot, pointer.worktreeGeneration);
             let localJournal = await this.dependencies.journal.load(projectId, taskSlug);
             let pendingOutbox = await this.dependencies.outbox.listForTask(backendTask.id);
             const responseSource = this.dependencies.client.getResponseSource(response);
@@ -523,6 +598,9 @@ export class BridgeService {
                     taskSlug,
                     source: sourceFromContext(backendTask.sourceContext),
                     worktreeId: pointer?.worktreeId ?? sha256(repository.repoRoot),
+                    ...(pointer?.worktreeGeneration
+                        ? { worktreeGeneration: pointer.worktreeGeneration }
+                        : {}),
                     ...(typeof backendTask.branch === 'string'
                         ? { branch: backendTask.branch }
                         : pointer?.branch !== undefined
@@ -543,6 +621,7 @@ export class BridgeService {
             return asJsonValue({
                 backend,
                 repository: publicRepository(repository),
+                worktree: this.poolAllocations.get(repository.repoRoot) ?? null,
                 localJournal,
                 pendingQuestionnaires,
                 synchronization: {
@@ -572,11 +651,26 @@ export class BridgeService {
         });
     }
     async contextPrepareChange(input) {
+        const pointer = await this.dependencies.activeContexts.findBySessionId(input.sessionId);
+        if (!pointer)
+            return this.contextPrepareChangeUnlocked(input);
+        try {
+            return await this.taskExclusive(pointer.taskId, () => this.contextPrepareChangeUnlocked(input));
+        }
+        catch (error) {
+            return this.execute(async () => {
+                throw error;
+            });
+        }
+    }
+    async contextPrepareChangeUnlocked(input) {
         return await this.execute(async () => {
             const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
             const pointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (!pointer)
                 throw refuse('Resume this task before requesting a change lease.', 'session.resume');
+            if (!input.transitionToWrite)
+                await this.assertPoolPointer(repository, pointer);
             await this.recoverJournalOutbox(pointer.projectId, pointer.taskSlug);
             const outbox = await this.flushOutbox(pointer.taskId);
             const pendingOutbox = await this.dependencies.outbox.listForTask(pointer.taskId);
@@ -622,6 +716,12 @@ export class BridgeService {
                 const refreshed = await this.activeTaskSnapshot(pointer.taskId, pointer.projectId, repository.repoRoot);
                 transitionTaskVersion = refreshed.taskVersion;
             }
+            if (decision && this.dependencies.worktreePool) {
+                const allocation = this.poolAllocations.get(repository.repoRoot);
+                if (!allocation || allocation.externalTaskId !== pointer.taskSlug)
+                    throw refuse('Choose this task branch and use its allocated repoRoot before transitioning to write.', 'task.branch');
+                await this.dependencies.worktreePool.assertOwnership(pointer.projectId, repository.repoRoot, allocation.generation);
+            }
             const body = cleanJson({
                 sessionId: input.sessionId,
                 changedPaths,
@@ -683,7 +783,15 @@ export class BridgeService {
                         worktreeId: sha256(repository.repoRoot),
                         branch: typeof preparedTask?.branch === 'string' ? preparedTask.branch : decision.branch,
                         mode: 'write',
+                        ...(this.poolAllocations.get(repository.repoRoot)
+                            ? { worktreeGeneration: this.poolAllocations.get(repository.repoRoot).generation }
+                            : {}),
                     });
+                    const allocation = this.poolAllocations.get(repository.repoRoot);
+                    if (allocation && this.dependencies.worktreePool) {
+                        await this.dependencies.worktreePool.bind(preparedPointer.projectId, repository.repoRoot, allocation.generation, preparedPointer.taskId);
+                        allocation.taskId = preparedPointer.taskId;
+                    }
                 }
                 const preparedData = objectValue(response.data);
                 await this.seedResumeSnapshot(preparedPointer, {
@@ -803,6 +911,19 @@ export class BridgeService {
         return notices.filter((notice) => wanted.has(notice.resourceId));
     }
     async contextRefresh(input) {
+        const pointer = await this.dependencies.activeContexts.findBySessionId(input.sessionId);
+        if (!pointer)
+            return this.contextRefreshUnlocked(input);
+        try {
+            return await this.taskExclusive(pointer.taskId, () => this.contextRefreshUnlocked(input));
+        }
+        catch (error) {
+            return this.execute(async () => {
+                throw error;
+            });
+        }
+    }
+    async contextRefreshUnlocked(input) {
         return await this.execute(async () => {
             const pointer = await this.dependencies.activeContexts.findBySessionId(input.sessionId);
             const repoRoot = input.repoRoot;
@@ -816,6 +937,8 @@ export class BridgeService {
                 (repository.repoFingerprint !== pointer.repoFingerprint ||
                     (pointer.worktreeId && pointer.worktreeId !== sha256(repository.repoRoot))))
                 throw refuse('Refresh this session from its own repository and worktree.', 'session.resume');
+            if (pointer && repository && pointer.mode !== 'read_only')
+                await this.assertPoolPointer(repository, pointer);
             const source = repository
                 ? await this.checkoutSource(repository, pointer?.source)
                 : undefined;
@@ -923,8 +1046,10 @@ export class BridgeService {
         return this.execute(async () => {
             if (input.choice.mode !== 'greenfield')
                 throw refuse('Only the greenfield choice initializes Git. Use project.onboard for adoption or rework.', 'session.entry');
+            if (this.dependencies.worktreePool && !input.choice.gitPreferences?.development.answered)
+                throw refuse('Choose the planned development branch through the native onboarding form before initializing Git.', 'project.initialize');
             return asJsonValue({
-                ...(await new ProjectIntake().initialize(input.repoRoot)),
+                ...(await new ProjectIntake().initialize(input.repoRoot, input.choice.gitPreferences?.development.branch ?? undefined)),
                 onboarding: stored.data,
             });
         });
@@ -1682,6 +1807,159 @@ export class BridgeService {
             });
         });
     }
+    async worktreeTaskAllocation(input) {
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot);
+            const allocation = repository.projectId && this.dependencies.worktreePool
+                ? await this.dependencies.worktreePool.find(repository.projectId, input.externalTaskId, repository.repoRoot)
+                : null;
+            return asJsonValue({ allocation });
+        });
+    }
+    async projectGitPreferences(input) {
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd(), input.projectId);
+            if (!repository.projectId)
+                throw refuse('Bind a project before reading Git preferences.', 'project.resolve');
+            const response = await this.dependencies.client.request(endpoints.projectGitPreferences(repository.projectId));
+            return asJsonValue({
+                ...objectOrEmpty(objectValue(response.data)),
+                repoRoot: repository.repoRoot,
+                currentBranch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                currentCommit: repository.git.head,
+            });
+        });
+    }
+    async setProjectGitPreferences(projectId, body) {
+        return this.execute(async () => {
+            assertSafeToPersist(body);
+            return (await this.dependencies.client.request(endpoints.projectGitPreferences(projectId), { method: 'PUT', body })).data;
+        });
+    }
+    async worktreePolicy(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.worktreePolicy, input ? { method: 'PUT', body: input } : {});
+            if (!validWorktreePolicy(response.data))
+                throw refuse('The backend worktree policy is invalid.', 'worktree.policy');
+            await this.dependencies.worktreePolicy?.save(response.data);
+            return asJsonValue(response.data);
+        });
+    }
+    async poolPolicy(refresh = false) {
+        if (refresh) {
+            try {
+                const response = await this.dependencies.client.request(endpoints.worktreePolicy);
+                if (!validWorktreePolicy(response.data))
+                    throw refuse('The backend worktree policy is invalid.', 'worktree.policy');
+                await this.dependencies.worktreePolicy?.save(response.data);
+                return response.data;
+            }
+            catch (error) {
+                if (!isBackendUnavailableError(error))
+                    throw error;
+            }
+        }
+        if (!this.dependencies.worktreePolicy)
+            throw refuse('This client has no local worktree policy cache.', 'worktree.policy');
+        return this.dependencies.worktreePolicy.read();
+    }
+    async worktreeOperation(operation, input) {
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot);
+            const projectId = repository.projectId;
+            const pool = this.dependencies.worktreePool;
+            if (!projectId || !pool)
+                throw refuse('Resolve the project with a pool-capable client.', 'project.resolve');
+            if (operation === 'list')
+                return asJsonValue({ items: await pool.list(projectId, await this.poolPolicy()) });
+            if (operation === 'reconcile')
+                return asJsonValue({
+                    items: await pool.reconcile(projectId, repository.repoRoot, await this.poolPolicy()),
+                });
+            const entry = await pool.forPath(projectId, repository.repoRoot);
+            if (!entry ||
+                entry.externalTaskId !== input.externalTaskId ||
+                entry.generation !== input.generation)
+                throw refuse('Use the exact task, repoRoot and ownership generation returned on resume.', 'session.resume');
+            const perform = async () => {
+                if (operation === 'heartbeat')
+                    await pool.assertOwnership(projectId, repository.repoRoot, input.generation);
+                if (operation === 'pause') {
+                    await pool.pause(projectId, repository.repoRoot, input.generation);
+                    this.poolAllocations.delete(repository.repoRoot);
+                }
+                if (operation === 'release') {
+                    if (entry.taskId)
+                        await this.flushOutbox(entry.taskId);
+                    await pool.release(projectId, repository.repoRoot, input.generation, input.delivered === true);
+                    this.poolAllocations.delete(repository.repoRoot);
+                }
+                return asJsonValue({ operation, complete: true, repoRoot: repository.repoRoot });
+            };
+            return entry.taskId ? this.taskExclusive(entry.taskId, perform, false) : perform();
+        });
+    }
+    async pooledTaskBranch(repository, input) {
+        const pool = this.dependencies.worktreePool;
+        const projectId = repository.projectId;
+        const existing = await pool.find(projectId, input.externalTaskId, repository.repoRoot);
+        const preferences = (await this.dependencies.client.request(endpoints.projectGitPreferences(projectId))).data;
+        const git = this.dependencies.repositories.git;
+        let source;
+        if (existing)
+            source = { sourceCommit: existing.baseCommit };
+        else {
+            if (!input.decisionId || !input.base)
+                throw refuse('Choose the task base through the native task.branch questionnaire.', 'task.branch');
+            const decision = await this.questionnaireResume({
+                repoRoot: repository.repoRoot,
+                questionnaireId: input.decisionId,
+            });
+            const signature = sha256(stableStringify({
+                externalTaskId: input.externalTaskId,
+                base: input.base,
+                name: input.name ?? null,
+                keepCurrent: input.keepCurrent === true,
+                ...(input.decisionAttempt ? { decisionAttempt: input.decisionAttempt } : {}),
+            }));
+            if (!['task-branch-confirm-' + signature, 'task-branch-fallback-' + signature].includes(decision.questionnaireId) ||
+                decision.answer?.choice !== 'approve')
+                throw refuse('The task branch decision does not match the approved source and branch.', 'task.branch');
+            source = await resolveTaskBase(git, repository.repoRoot, input.base, preferences);
+        }
+        const allocation = await pool.allocate({
+            projectId,
+            projectName: preferences.projectName ?? projectId,
+            repoFingerprint: repository.repoFingerprint,
+            repoRoot: repository.repoRoot,
+            externalTaskId: input.externalTaskId,
+            branch: existing?.branch ?? input.name ?? (await git.currentBranch(repository.repoRoot)),
+            baseCommit: source.sourceCommit,
+            keepCurrent: input.keepCurrent,
+            resume: Boolean(existing),
+        }, await this.poolPolicy(true));
+        this.poolAllocations.set(allocation.repoRoot, allocation);
+        return asJsonValue({
+            ...allocation,
+            kept: !allocation.managed,
+            nextAction: 'Run every file, terminal, lifecycle and delivery operation from this repoRoot. Use task.heartbeat during long work. Pause before handing the task to another client.',
+        });
+    }
+    async assertPoolPointer(repository, pointer) {
+        const pool = this.dependencies.worktreePool;
+        if (!pool)
+            return;
+        const entry = await pool.forPath(pointer.projectId, repository.repoRoot);
+        if (!entry && !pointer.worktreeGeneration)
+            return; // existing unmanaged tasks retain their legacy reservation
+        const owned = this.poolAllocations.get(repository.repoRoot);
+        if (!entry ||
+            !owned ||
+            owned.generation !== pointer.worktreeGeneration ||
+            entry.externalTaskId !== pointer.taskSlug)
+            throw refuse('Resume this task to acquire its worktree before writing or delivering.', 'session.resume');
+        await pool.assertOwnership(pointer.projectId, repository.repoRoot, owned.generation);
+    }
     async taskBranch(input) {
         return await this.execute(async () => {
             const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
@@ -1694,10 +1972,15 @@ export class BridgeService {
                 input.externalTaskId.length > 160 ||
                 /[\r\n]/.test(input.externalTaskId))
                 throw refuse('Pass the exact externalTaskId of the task whose branch question was answered.', 'task.branch');
+            if (this.dependencies.worktreePool &&
+                (await this.dependencies.worktreePool.find(repository.projectId, input.externalTaskId, repository.repoRoot)))
+                return this.pooledTaskBranch(repository, input);
             if (Boolean(input.name) === (input.keepCurrent === true) ||
                 (input.worktreePath && !input.name))
                 throw refuse('Choose exactly one branch name or keepCurrent. A separate worktree also needs a branch name.', 'task.branch');
             assertSafeToPersist(cleanJson({ externalTaskId: input.externalTaskId, name: input.name }));
+            if (this.dependencies.worktreePool)
+                return this.pooledTaskBranch(repository, input);
             const git = this.dependencies.repositories.git;
             let target = repository;
             try {
@@ -1743,7 +2026,7 @@ export class BridgeService {
             catch (error) {
                 if (error instanceof BridgeRecoveryError)
                     throw error;
-                throw refuse(`${error instanceof Error ? error.message : String(error)} Retry task.branch for the selected task; use worktreePath to leave a busy or dirty checkout intact.`, 'task.branch');
+                throw refuse(`${error instanceof Error ? error.message : String(error)} Retry task.branch for the selected task; select a new branch so the managed pool preserves the busy or dirty checkout.`, 'task.branch');
             }
         });
     }
@@ -1766,10 +2049,10 @@ export class BridgeService {
             }
         }
         if (!record)
-            throw refuse(`Ask the branch question through the native questionnaire for task ${externalTaskId}, then call task.branch with that externalTaskId and a name or keepCurrent. For parallel work choose a separate worktreePath.`, 'task.branch');
+            throw refuse(`Ask the branch question through the native questionnaire for task ${externalTaskId}, then call task.branch with that externalTaskId and a name or keepCurrent. The managed pool allocates the separate worktree; use its returned repoRoot.`, 'task.branch');
         if (record.decision.projectId !== repository.projectId ||
             record.decision.externalTaskId !== externalTaskId)
-            throw refuse(`This worktree belongs to task ${record.decision.externalTaskId}. Use task.branch with worktreePath for ${externalTaskId}, then bootstrap in the returned directory.`, 'task.branch');
+            throw refuse(`This worktree belongs to task ${record.decision.externalTaskId}. Use task.branch to allocate a separate worktree for ${externalTaskId}, then bootstrap in the returned repoRoot.`, 'task.branch');
         const branch = await git.currentBranch(repository.repoRoot);
         if (branch !== record.decision.branch)
             throw refuse(`Task ${externalTaskId} selected ${record.decision.branch ?? 'detached HEAD'}, but this worktree is on ${branch ?? 'detached HEAD'}. Return to the selected branch with task.branch.`, 'task.branch');
@@ -1778,6 +2061,8 @@ export class BridgeService {
     async assertTaskWorktree(repository, task, pointer) {
         if (normalizeTaskMode(task.mode) === 'read_only')
             return;
+        if (pointer)
+            await this.assertPoolPointer(repository, pointer);
         if (pointer?.worktreeId && pointer.worktreeId !== sha256(repository.repoRoot))
             throw refuse('This task belongs to a different worktree. Resume and run its commands in the worktree selected for this task.', 'session.resume');
         const recorded = typeof task.branch === 'string' ? task.branch : pointer?.branch;
@@ -1797,9 +2082,15 @@ export class BridgeService {
                 if (!abandoned || abandoned.abandoned !== true) {
                     throw refuse('The backend did not record the abandonment, so the task is still open.', 'session.resume');
                 }
-                await this.dependencies.repositories.git
-                    .branchStore(repository.repoRoot)
-                    .release(input.taskId);
+                const allocation = this.poolAllocations.get(repository.repoRoot);
+                if (allocation && this.dependencies.worktreePool) {
+                    await this.dependencies.worktreePool.pause(allocation.projectId, allocation.repoRoot, allocation.generation);
+                    this.poolAllocations.delete(repository.repoRoot);
+                }
+                else
+                    await this.dependencies.repositories.git
+                        .branchStore(repository.repoRoot)
+                        .release(input.taskId);
                 const forgotten = await this.dependencies.activeContexts.forget(repository.repoFingerprint, input.taskId);
                 await this.dependencies.gate.invalidateTask(input.taskId);
                 return asJsonValue({
@@ -1852,6 +2143,27 @@ export class BridgeService {
                 readDiscoveryUnits(policy).length === 0) {
                 throw refuse('Project setup response is not policy-ready', 'project.setup');
             }
+            if (input.onboardingRequestKey &&
+                this.dependencies.onboarding &&
+                this.dependencies.worktreePool) {
+                const access = await this.dependencies.credentials.get('access-token');
+                const target = await canonicalPath(repository.repoRoot);
+                const choice = await this.dependencies.onboarding.get({
+                    principalHash: access ? principalFingerprint(access) : sha256('anonymous'),
+                    repoFingerprint: sha256('preparation:' + (process.platform === 'win32' ? target.toLowerCase() : target)),
+                    projectId: null,
+                }, input.onboardingRequestKey);
+                if (!choice?.gitPreferences)
+                    throw refuse('Read the saved onboarding choice and supply its original request key.', 'project.onboarding_status');
+                const current = (await this.dependencies.client.request(endpoints.projectGitPreferences(project.id))).data;
+                if (current.version === 0)
+                    await this.dependencies.client.request(endpoints.projectGitPreferences(project.id), {
+                        method: 'PUT',
+                        body: cleanJson({ expectedVersion: 0, ...choice.gitPreferences }),
+                    });
+                else if (stableStringify(current.branches) !== stableStringify(choice.gitPreferences))
+                    throw refuse('The project already has different shared branch preferences. Review them before changing the project settings.', 'project.git_preferences');
+            }
             const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, project.id, project.repoFingerprint);
             return asJsonValue({ ...data, marker: null, markerPath: null, bindingPath });
         });
@@ -2243,6 +2555,18 @@ export class BridgeService {
             const workItems = authenticated && state === 'bound' && projectId
                 ? await this.actionableWorkItems(projectId)
                 : [];
+            const gitPreferences = authenticated && state === 'bound' && projectId && this.dependencies.worktreePool
+                ? await this.projectGitPreferences({ repoRoot: repository.repoRoot, projectId })
+                : null;
+            const preferences = gitPreferences?.ok ? objectValue(gitPreferences.data) : null;
+            const unansweredBranches = preferences?.canManage === true
+                ? Object.entries(objectOrEmpty(objectValue(preferences.branches)))
+                    .filter(([, value]) => objectValue(value)?.answered === false)
+                    .map(([role]) => role)
+                : [];
+            const worktrees = authenticated && state === 'bound' && projectId && this.dependencies.worktreePool
+                ? await this.worktreeOperation('list', { repoRoot: repository.repoRoot })
+                : null;
             const taskSelectionRequired = liveTasks.length > 0 || workItems.length > 0;
             const pendingQuestionnaires = state !== 'disabled' ? await this.pendingQuestionnaires(repository.repoRoot) : [];
             return asJsonValue({
@@ -2253,6 +2577,16 @@ export class BridgeService {
                 liveTasks,
                 workItems,
                 taskSelectionRequired,
+                ...(worktrees ? { worktrees: worktrees.ok ? worktrees.data : worktrees.error } : {}),
+                ...(gitPreferences
+                    ? {
+                        gitPreferences: gitPreferences.ok ? gitPreferences.data : gitPreferences.error,
+                        unansweredBranchPreferences: unansweredBranches,
+                        branchPreferenceAction: unansweredBranches.length
+                            ? 'Ask only these unanswered shared branch preferences using native questionnaires and project.set_git_preferences. Other members choose only their task base.'
+                            : 'Existing answers remain valid, including explicit absence. Choose the task base through task.branch when starting development.',
+                    }
+                    : {}),
                 ...(state !== 'disabled' ? { pendingQuestionnaires } : {}),
                 client,
                 ...(incomplete && state === 'bound'
@@ -2777,6 +3111,8 @@ export class BridgeService {
             (repository.projectId && pointer.projectId !== repository.projectId)) {
             throw refuse('Active task snapshot does not match the repository project', 'session.resume');
         }
+        if (pointer.mode !== 'read_only')
+            await this.assertPoolPointer(repository, pointer);
         if ((await this.dependencies.outbox.list()).some((entry) => taskIdFromDeliverySafe(entry) === taskId)) {
             throw refuse('Pending task deliveries must be resolved before using the task snapshot', 'task.resolve_pending_delivery');
         }
@@ -3014,9 +3350,13 @@ export class BridgeService {
             taskChanges,
         });
         await this.dependencies.activeContexts.clearCloseIntent(repository.repoFingerprint, String(body.taskId));
-        await this.dependencies.repositories.git
-            .branchStore(repository.repoRoot)
-            .release(String(body.taskId));
+        const allocation = this.poolAllocations.get(repository.repoRoot);
+        if (allocation && this.dependencies.worktreePool)
+            await this.dependencies.worktreePool.delivery(allocation.projectId, repository.repoRoot, allocation.generation);
+        else
+            await this.dependencies.repositories.git
+                .branchStore(repository.repoRoot)
+                .release(String(body.taskId));
         return asJsonValue({
             ...closedTask,
             repository: publicRepository(repository),
@@ -3082,7 +3422,7 @@ export class BridgeService {
         }
         return pointer;
     }
-    async taskExclusive(taskId, action) {
+    async taskExclusive(taskId, action, renew = true) {
         const previous = this.taskQueues.get(taskId) ?? Promise.resolve();
         let release = () => undefined;
         const current = new Promise((resolvePromise) => {
@@ -3091,10 +3431,34 @@ export class BridgeService {
         const tail = previous.then(() => current);
         this.taskQueues.set(taskId, tail);
         await previous;
+        let heartbeat;
+        let heartbeatFailure;
         try {
-            return await action();
+            const allocation = await this.dependencies.worktreePool?.forTask(taskId);
+            if (allocation) {
+                const owned = this.poolAllocations.get(allocation.repoRoot);
+                if (!owned || owned.generation !== allocation.generation)
+                    throw refuse('Resume the task in its owned worktree before this operation.', 'session.resume');
+                await this.dependencies.worktreePool.assertOwnership(allocation.projectId, allocation.repoRoot, owned.generation);
+                const policy = await this.poolPolicy();
+                if (renew)
+                    heartbeat = setInterval(() => {
+                        void this.dependencies
+                            .worktreePool.assertOwnership(allocation.projectId, allocation.repoRoot, owned.generation)
+                            .catch((error) => {
+                            heartbeatFailure = error;
+                        });
+                    }, policy.heartbeatSeconds * 1000);
+                heartbeat?.unref();
+            }
+            const result = await action();
+            if (heartbeatFailure)
+                throw heartbeatFailure;
+            return result;
         }
         finally {
+            if (heartbeat)
+                clearInterval(heartbeat);
             release();
             if (this.taskQueues.get(taskId) === tail) {
                 this.taskQueues.delete(taskId);

package/runtime/dist/src/runtime/task-branch-store.js

@@ -92,7 +92,7 @@ export class TaskBranchStore {
     assertSame(current, requested) {
         if (current.projectId !== requested.projectId ||
             current.externalTaskId !== requested.externalTaskId) {
-            throw new BridgeRecoveryError(`This worktree belongs to task ${current.externalTaskId}. Resume that task, or call task.branch with worktreePath and a branch name for the new task.`, 'task.branch');
+            throw new BridgeRecoveryError(`This worktree belongs to task ${current.externalTaskId}. Resume that task, or call task.branch with a new task branch name to allocate a separate worktree.`, 'task.branch');
         }
         if (current.branch !== requested.branch) {
             throw new BridgeRecoveryError(`This task selected ${current.branch ?? 'detached HEAD'}. Return to that branch before continuing.`, 'task.branch');

package/runtime/dist/src/runtime/worktree-policy.js

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { readJson, writeJson } from '../utilities/files.js';
+import { BridgeRecoveryError } from './recovery-error.js';
+export function validWorktreePolicy(value) {
+    const p = value;
+    return Boolean(p &&
+        Number.isSafeInteger(p.version) &&
+        p.version >= 1 &&
+        Number.isSafeInteger(p.maxWorktrees) &&
+        p.maxWorktrees >= 1 &&
+        p.maxWorktrees <= 500 &&
+        Number.isSafeInteger(p.heartbeatSeconds) &&
+        p.heartbeatSeconds >= 5 &&
+        p.heartbeatSeconds <= 300 &&
+        Number.isSafeInteger(p.inactivitySeconds) &&
+        p.inactivitySeconds >= 60 &&
+        p.inactivitySeconds <= 86400 &&
+        p.inactivitySeconds >= p.heartbeatSeconds * 2);
+}
+export class WorktreePolicyCache {
+    stateRoot;
+    constructor(stateRoot) {
+        this.stateRoot = stateRoot;
+    }
+    async save(policy) {
+        if (!validWorktreePolicy(policy))
+            throw new BridgeRecoveryError('The backend returned an invalid worktree policy.', 'worktree.policy');
+        await writeJson(join(this.stateRoot, 'worktree-policy.json'), policy, this.stateRoot);
+    }
+    async read() {
+        const value = await readJson(join(this.stateRoot, 'worktree-policy.json'), this.stateRoot);
+        if (!validWorktreePolicy(value))
+            throw new BridgeRecoveryError('No valid cached worktree policy exists. Read worktree.policy while connected before allocating a worktree.', 'worktree.policy');
+        return value;
+    }
+}
+//# sourceMappingURL=worktree-policy.js.map