engineering-memory 1.7.0 → 1.9.0

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

@@ -3,9 +3,11 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { minimatch } from 'minimatch';
 import { endpoints } from '../config.js';
+import { RepositoryResolver } from '../project/repository.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { ApiResponseError, BackendUnavailableError, } from './api-client.js';
 import { assertSafeToPersist, normalizeRepositoryPaths } from './offline-outbox.js';
+import { BridgeRecoveryError } from './recovery-error.js';
 export const validationIds = [
     'format',
     'static_analysis',
@@ -54,6 +56,7 @@ export class BridgeService {
                 objective: input.objective,
                 taskKind: input.taskKind,
                 workItemKey: input.workItemKey,
+                workItemId: input.workItemId,
                 mode: input.mode,
                 knownRevisions: input.knownRevisions,
             }, repository.repoRoot);
@@ -71,19 +74,28 @@ export class BridgeService {
                     body: { repoFingerprint: repository.repoFingerprint },
                 });
                 const project = objectValue(resolved.data);
-                const projects = await this.dependencies.client.request(endpoints.projectList);
+                const restoreRequired = Boolean(project?.archivedAt);
+                const restoreGuidance = archivedProjectGuidance(project);
+                const projects = await this.dependencies.client.request(restoreRequired ? `${endpoints.projectList}?includeArchived=true` : endpoints.projectList);
                 return asJsonValue({
-                    projectBindingRequired: true,
+                    projectBindingRequired: !restoreRequired,
+                    restoreRequired,
                     candidate: project,
                     requestedProjectId: projectId,
                     repository: publicRepository(repository),
                     projects: projects.data,
                     outbox: { recoveredDeliveries, ...objectOrEmpty(outbox) },
+                    ...(restoreRequired ? restoreGuidance : {}),
                 });
             }
             if (!projectId) {
                 throw refuse('This repository has a marker that names no project, so there is nothing to bootstrap against.', 'project.resolve');
             }
+            const bootstrapMode = persistedBootstrap.mode ?? 'write';
+            const decision = bootstrapMode === 'read_only'
+                ? null
+                : await this.requireBranchDecision(repository, input.externalTaskId);
+            const branch = decision?.branch;
             const checkpointId = deterministicUuid('session.bootstrap', projectId, repository.repoFingerprint, input.externalTaskId);
             const response = await this.dependencies.client.request(endpoints.sessionBootstrap, {
                 method: 'POST',
@@ -94,11 +106,13 @@ export class BridgeService {
                     objective: persistedBootstrap.objective,
                     taskKind: persistedBootstrap.taskKind,
                     workItemKey: persistedBootstrap.workItemKey,
+                    workItemId: persistedBootstrap.workItemId,
                     mode: persistedBootstrap.mode ?? 'write',
                     repoFingerprint: repository.repoFingerprint,
                     ...(input.mode === 'read_only'
                         ? { baselineDiffHash: repository.git.worktreeHash }
                         : {}),
+                    ...(decision ? { branch } : {}),
                     checkpointIdempotencyKey: checkpointId,
                     knownRevisions: persistedBootstrap.knownRevisions,
                 }),
@@ -120,11 +134,20 @@ export class BridgeService {
                 !isIsoTimestamp(checkpointPayload.createdAt)) {
                 throw refuse('The backend opened the session without the checkpoint the task is anchored to.', 'session.bootstrap');
             }
+            if (decision)
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .bind(projectId, input.externalTaskId, task.id);
             const pointer = {
                 repoFingerprint: repository.repoFingerprint,
                 projectId,
                 taskId: task.id,
                 taskSlug: input.externalTaskId,
+                worktreeId: sha256(repository.repoRoot),
+                ...(decision
+                    ? { branch: typeof task.branch === 'string' ? task.branch : decision.branch }
+                    : {}),
+                mode: normalizeTaskMode(task.mode),
                 sessionId: session.id,
                 lastSequence: numericSequence(task.lastSequence),
                 taskVersion: numericTaskVersion(task.lockVersion),
@@ -249,6 +272,12 @@ export class BridgeService {
                 backendSession.id !== sessionId) {
                 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') {
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .release(backendTask.id);
+            }
             let localJournal = await this.dependencies.journal.load(projectId, taskSlug);
             let pendingOutbox = await this.dependencies.outbox.list();
             const responseSource = this.dependencies.client.getResponseSource(response);
@@ -256,7 +285,7 @@ export class BridgeService {
                 ? await this.retryVerificationRecovery(repository, pointer, backend)
                 : null;
             if (recoveredVerification) {
-                pointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
+                pointer = await this.dependencies.activeContexts.loadForTask(repository.repoFingerprint, pointer.taskId);
             }
             let hydratedFromBackend = false;
             let mergedFromBackend = false;
@@ -358,6 +387,13 @@ export class BridgeService {
                     projectId,
                     taskId: backendTask.id,
                     taskSlug,
+                    worktreeId: pointer?.worktreeId ?? sha256(repository.repoRoot),
+                    ...(typeof backendTask.branch === 'string'
+                        ? { branch: backendTask.branch }
+                        : pointer?.branch !== undefined
+                            ? { branch: pointer.branch }
+                            : {}),
+                    mode: normalizeTaskMode(backendTask.mode),
                     sessionId,
                     lastSequence: resumedLastSequence,
                     taskVersion: resumedTaskVersion,
@@ -405,7 +441,7 @@ export class BridgeService {
             await this.recoverJournalOutbox();
             const outbox = await this.flushOutbox();
             const pendingOutbox = await this.dependencies.outbox.list();
-            const pointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
+            const pointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (pointer?.verificationIntent || pointer?.closeIntent) {
                 throw refuse('A verification or close intent from an earlier session is still unsettled, so a new lease would be taken against the wrong state.', 'session.resume');
             }
@@ -436,6 +472,10 @@ export class BridgeService {
                 ...input.changedPaths,
             ]);
             const baselineDiffHash = activeBaseline?.diffHash ?? repository.git.diffHash;
+            const decision = pointer &&
+                (input.transitionToWrite || (pointer.branch !== undefined && pointer.mode !== 'read_only'))
+                ? await this.requireBranchDecision(repository, pointer.taskSlug)
+                : null;
             let transitionTaskVersion;
             if (input.transitionToWrite) {
                 if (!pointer || pointer.sessionId !== input.sessionId) {
@@ -448,6 +488,7 @@ export class BridgeService {
                 sessionId: input.sessionId,
                 changedPaths,
                 baselineDiffHash,
+                ...(decision ? { branch: decision.branch } : {}),
                 ...(input.transitionToWrite
                     ? { transitionToWrite: true, expectedTaskVersion: transitionTaskVersion }
                     : {}),
@@ -492,8 +533,19 @@ export class BridgeService {
                     lastSequence: numericSequence(preparedTask.lastSequence),
                 }
                 : undefined);
-            const preparedPointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
+            const preparedPointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (preparedPointer) {
+                if (decision) {
+                    await this.dependencies.repositories.git
+                        .branchStore(repository.repoRoot)
+                        .bind(preparedPointer.projectId, preparedPointer.taskSlug, preparedPointer.taskId);
+                    await this.dependencies.activeContexts.save({
+                        ...preparedPointer,
+                        worktreeId: sha256(repository.repoRoot),
+                        branch: typeof preparedTask?.branch === 'string' ? preparedTask.branch : decision.branch,
+                        mode: 'write',
+                    });
+                }
                 const preparedData = objectValue(response.data);
                 await this.seedResumeSnapshot(preparedPointer, {
                     ...objectOrEmpty(response.data),
@@ -1003,6 +1055,7 @@ export class BridgeService {
                     });
                 }
                 const taskMode = normalizeTaskMode(snapshotTask.mode);
+                await this.assertTaskWorktree(repository, snapshotTask, pointer);
                 const resourceDiscoveryPolicy = readResourceDiscoveryPolicy(snapshot, activeLease);
                 const validations = normalizePersistentInput(input.validations, repository.repoRoot);
                 if (taskMode === 'read_only') {
@@ -1065,6 +1118,11 @@ export class BridgeService {
                     changedPaths: taskMode === 'read_only' ? [] : taskChangedPaths,
                     pathChanges: pathChangeManifest,
                     diffHash: repository.git.diffHash,
+                    ...(taskMode !== 'read_only'
+                        ? {
+                            branch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                        }
+                        : {}),
                     ...(taskMode === 'read_only' ? { worktreeHash: repository.git.worktreeHash } : {}),
                     validations,
                     pendingOutboxCount,
@@ -1098,6 +1156,9 @@ export class BridgeService {
                         repoFingerprint: repository.repoFingerprint,
                         repoRoot: repository.repoRoot,
                         diffHash: repository.git.diffHash,
+                        branch: typeof snapshotTask.branch === 'string'
+                            ? snapshotTask.branch
+                            : (pointer.branch ?? null),
                         taskVersion,
                         taskChanges,
                     });
@@ -1141,11 +1202,17 @@ export class BridgeService {
                 const taskChanges = pointer.changeBaseline
                     ? manifestDelta(pointer.changeBaseline.changedPaths, repository.git.changedPaths)
                     : [];
+                await this.assertTaskWorktree(repository, task, pointer);
                 const closeBody = {
                     taskId: input.taskId,
                     sessionId: pointer.sessionId,
                     expectedTaskVersion: numericTaskVersion(task.lockVersion),
                     diffHash: repository.git.diffHash,
+                    ...(normalizeTaskMode(task.mode) !== 'read_only'
+                        ? {
+                            branch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                        }
+                        : {}),
                 };
                 await this.dependencies.activeContexts.setCloseIntent(repository.repoFingerprint, {
                     body: closeBody,
@@ -1155,6 +1222,111 @@ export class BridgeService {
             });
         });
     }
+    async taskBranch(input) {
+        return await this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
+            const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
+            if (authentication)
+                return asJsonValue({ authentication });
+            if (!repository.projectId)
+                throw refuse('Resolve the project before choosing its task branch.', 'project.resolve');
+            if (!input.externalTaskId ||
+                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 (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 }));
+            const git = this.dependencies.repositories.git;
+            let target = repository;
+            try {
+                if (input.name)
+                    await git.validateBranch(repository.repoRoot, input.name);
+                if (input.worktreePath && input.name) {
+                    const targetRoot = await git.createWorktree(repository.repoRoot, input.name, input.worktreePath);
+                    target = await this.dependencies.repositories.resolve(targetRoot);
+                    if (target.projectId && target.projectId !== repository.projectId)
+                        throw refuse('The target worktree belongs to a different Engineering Memory project. Choose another worktreePath.', 'task.branch');
+                    if (!target.markerPath) {
+                        await new RepositoryResolver(git, repository.schemaVersion ?? 2).writeMarker(targetRoot, repository.projectId);
+                        target = await this.dependencies.repositories.resolve(targetRoot);
+                    }
+                }
+                const branch = input.name ?? (await git.currentBranch(target.repoRoot));
+                const store = git.branchStore(target.repoRoot);
+                await store.reserve({
+                    projectId: repository.projectId,
+                    externalTaskId: input.externalTaskId,
+                    branch,
+                });
+                if (input.name && (await git.currentBranch(target.repoRoot)) !== input.name) {
+                    try {
+                        if (await git.branchExists(target.repoRoot, input.name))
+                            await git.switchBranch(target.repoRoot, input.name);
+                        else
+                            await git.createBranch(target.repoRoot, input.name);
+                    }
+                    catch (error) {
+                        if ((await git.currentBranch(target.repoRoot)) !== input.name) {
+                            await store.cancelUnopened(repository.projectId, input.externalTaskId);
+                            throw error;
+                        }
+                    }
+                }
+                return asJsonValue({
+                    branch,
+                    kept: input.keepCurrent === true,
+                    repoRoot: target.repoRoot,
+                    externalTaskId: input.externalTaskId,
+                    nextAction: 'Use this repoRoot for session.bootstrap and every subsequent command for this task. The decision survives retries and restarts.',
+                });
+            }
+            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');
+            }
+        });
+    }
+    async requireBranchDecision(repository, externalTaskId) {
+        const git = this.dependencies.repositories.git;
+        const store = git.branchStore(repository.repoRoot);
+        let record = await store.read();
+        if (!record) {
+            const pointer = await this.dependencies.activeContexts.loadForSlug(repository.repoFingerprint, externalTaskId);
+            if (pointer?.worktreeId === sha256(repository.repoRoot) &&
+                pointer.mode !== 'read_only' &&
+                pointer.branch !== undefined) {
+                await store.reserve({
+                    projectId: pointer.projectId,
+                    externalTaskId,
+                    branch: pointer.branch,
+                    taskId: pointer.taskId,
+                });
+                record = await store.read();
+            }
+        }
+        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');
+        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');
+        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');
+        return record.decision;
+    }
+    async assertTaskWorktree(repository, task, pointer) {
+        if (normalizeTaskMode(task.mode) === 'read_only')
+            return;
+        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;
+        const current = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
+        if (recorded && current !== recorded)
+            throw refuse(`This task selected ${recorded}. Call task.branch with externalTaskId ${pointer?.taskSlug ?? String(task.externalTaskId)} and name ${recorded} before continuing.`, 'task.branch');
+    }
     async taskAbandon(input) {
         return await this.execute(async () => {
             return await this.taskExclusive(input.taskId, async () => {
@@ -1167,6 +1339,9 @@ 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 forgotten = await this.dependencies.activeContexts.forget(repository.repoFingerprint, input.taskId);
                 await this.dependencies.gate.invalidateTask(input.taskId);
                 return asJsonValue({
@@ -1224,11 +1399,59 @@ export class BridgeService {
         return await this.execute(async () => {
             const response = await this.dependencies.client.request(endpoints.projectMemberAdd(input.projectId), {
                 method: 'POST',
-                body: { email: input.email, role: input.role },
+                body: cleanJson({
+                    email: input.email,
+                    role: input.role,
+                    ...(input.discipline !== undefined ? { discipline: input.discipline } : {}),
+                }),
             });
             return asJsonValue({ membership: response.data });
         });
     }
+    async projectMemberList(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectMemberList(input.projectId));
+            return asJsonValue({ members: response.data });
+        });
+    }
+    async auditList(input) {
+        return await this.execute(async () => {
+            const query = new URLSearchParams();
+            if (input.organizationId) {
+                query.set('organizationId', input.organizationId);
+            }
+            if (input.projectId)
+                query.set('projectId', input.projectId);
+            if (input.beforeCreatedAt) {
+                query.set('beforeCreatedAt', input.beforeCreatedAt);
+            }
+            if (input.beforeId)
+                query.set('beforeId', input.beforeId);
+            if (input.limit !== undefined)
+                query.set('limit', String(input.limit));
+            const response = await this.dependencies.client.request(`${endpoints.auditList}?${query.toString()}`);
+            return asJsonValue({ page: response.data });
+        });
+    }
+    async organizationMemberUpsert(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.organizationMemberUpsert(input.organizationId), {
+                method: 'PUT',
+                body: cleanJson({
+                    email: input.email,
+                    role: input.role,
+                    discipline: input.discipline,
+                }),
+            });
+            return asJsonValue({ membership: response.data });
+        });
+    }
+    async organizationMemberList(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.organizationMemberList(input.organizationId));
+            return asJsonValue({ members: response.data });
+        });
+    }
     async organizationList() {
         return await this.execute(async () => {
             const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
@@ -1243,6 +1466,33 @@ export class BridgeService {
             });
         });
     }
+    async workItemList(input) {
+        return await this.execute(async () => {
+            const query = new URLSearchParams();
+            if (input.status)
+                query.set('status', input.status);
+            if (input.priority)
+                query.set('priority', input.priority);
+            if (input.assigneeUserId) {
+                query.set('assigneeUserId', input.assigneeUserId);
+            }
+            if (input.includeArchived)
+                query.set('includeArchived', 'true');
+            const suffix = query.size > 0 ? `?${query.toString()}` : '';
+            const response = await this.dependencies.client.request(`${endpoints.workItemList(input.projectId)}${suffix}`);
+            return asJsonValue({
+                selectionRequired: true,
+                questionnaire: 'Select the project work item to run in this chat',
+                ...objectOrEmpty(response.data),
+            });
+        });
+    }
+    async workItemGet(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemGet(input.projectId, input.workItemId));
+            return asJsonValue({ workItem: response.data });
+        });
+    }
     async architecturePlan(input) {
         return await this.execute(async () => {
             const body = cleanJson(input);
@@ -1297,20 +1547,48 @@ export class BridgeService {
             return asJsonValue({ organization: response.data });
         });
     }
-    async projectList() {
+    async projectList(input = {}) {
         return await this.execute(async () => {
             const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
             if (authentication) {
                 return asJsonValue({ authentication });
             }
-            const response = await this.dependencies.client.request(endpoints.projectList);
+            const response = await this.dependencies.client.request(input.includeArchived
+                ? `${endpoints.projectList}?includeArchived=true`
+                : endpoints.projectList);
             return asJsonValue({
                 selectionRequired: true,
                 questionnaire: 'Select an existing project or choose new project setup',
                 projects: response.data,
+                ...(input.includeArchived
+                    ? {
+                        archivedProjectActions: (Array.isArray(response.data) ? response.data : [])
+                            .map((entry) => objectValue(entry))
+                            .filter((project) => Boolean(project?.archivedAt))
+                            .map((project) => archivedProjectGuidance(project)),
+                    }
+                    : {}),
             });
         });
     }
+    async projectArchive(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectArchive(input.projectId), {
+                method: 'DELETE',
+                body: { expectedVersion: input.expectedVersion },
+            });
+            return asJsonValue({ project: response.data, archived: true });
+        });
+    }
+    async projectRestore(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectRestore(input.projectId), {
+                method: 'POST',
+                body: { expectedVersion: input.expectedVersion },
+            });
+            return asJsonValue({ project: response.data, restored: true });
+        });
+    }
     async projectResolve(input) {
         return await this.execute(async () => {
             const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
@@ -1355,12 +1633,16 @@ export class BridgeService {
                 body: { repoFingerprint: repository.repoFingerprint },
             });
             const project = objectValue(response.data);
+            const restoreRequired = Boolean(project?.archivedAt);
+            const restoreGuidance = archivedProjectGuidance(project);
             return asJsonValue({
-                resolved: project !== null,
+                resolved: project !== null && !restoreRequired,
                 project,
                 markerPath: null,
                 repository: publicRepository(repository),
                 selectionRequired: project === null,
+                restoreRequired,
+                ...(restoreRequired ? restoreGuidance : {}),
             });
         });
     }
@@ -1391,21 +1673,50 @@ export class BridgeService {
             const client = await this.clientUpdate(authenticated);
             const shipped = objectValue(objectValue(client)?.shippedKnowledge);
             const incomplete = shipped && (shipped.failure !== null || Number(shipped.live) < Number(shipped.expected));
+            const projectId = repository.projectId ?? decision?.projectId ?? null;
+            const liveTasks = authenticated && state === 'bound'
+                ? (await this.dependencies.activeContexts.list(repository.repoFingerprint)).map(describePointer)
+                : [];
+            const workItems = authenticated && state === 'bound' && projectId
+                ? await this.actionableWorkItems(projectId)
+                : [];
+            const taskSelectionRequired = liveTasks.length > 0 || workItems.length > 0;
             return asJsonValue({
                 authenticated,
                 repository: publicRepository(repository),
                 decision: state,
-                projectId: repository.projectId ?? decision?.projectId ?? null,
+                projectId,
+                liveTasks,
+                workItems,
+                taskSelectionRequired,
                 client,
-                ...(incomplete
+                ...(incomplete && state === 'bound'
                     ? {
                         shippedKnowledgeWarning: 'The backend is not serving all of the knowledge this release ships. Tell the user before relying on the rules: some are missing from the running server, so a review against them is incomplete. The counts and the reason are in client.shippedKnowledge.',
                     }
                     : {}),
-                nextAction: entryNextAction(authenticated, state),
+                nextAction: taskSelectionRequired
+                    ? 'Present the live runs and actionable project work items, then ask which one this chat should handle. Resume only the run they choose, or bootstrap a separate run with the chosen workItemId. Another live task never blocks opening this one.'
+                    : entryNextAction(authenticated, state),
             });
         });
     }
+    async actionableWorkItems(projectId) {
+        try {
+            const response = await this.dependencies.client.request(`${endpoints.workItemList(projectId)}?limit=100`);
+            const items = objectValue(response.data)?.items;
+            if (!Array.isArray(items))
+                return [];
+            const actionable = new Set(['backlog', 'ready', 'in_progress', 'in_review']);
+            return items.filter((entry) => {
+                const item = objectValue(entry);
+                return item ? actionable.has(String(item.status)) : false;
+            });
+        }
+        catch {
+            return [];
+        }
+    }
     async clientUpdate(authenticated) {
         const installed = this.dependencies.clientVersion;
         if (!authenticated) {
@@ -1929,6 +2240,7 @@ export class BridgeService {
             repoFingerprint: pointer.repoFingerprint,
             repoRoot: repository.repoRoot,
             diffHash: repository.git.diffHash,
+            branch: typeof backendTask?.branch === 'string' ? backendTask.branch : (pointer.branch ?? null),
             taskVersion,
             taskChanges: intent.taskChanges,
         });
@@ -1957,6 +2269,9 @@ export class BridgeService {
     }
     async deliverCloseIntent(repository, body, taskChanges, recoveredAfterResponseLoss) {
         const touchedContract = taskChanges.some((change) => /\.controller\.[tj]s$/.test(change.path));
+        const currentBranch = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
+        if (typeof body.branch === 'string' && body.branch !== currentBranch)
+            throw refuse(`Return to the branch ${body.branch} recorded in this close request before retrying.`, 'task.branch');
         let response;
         try {
             response = await this.dependencies.client.request(endpoints.taskClose, {
@@ -1982,11 +2297,19 @@ export class BridgeService {
             repoFingerprint: repository.repoFingerprint,
             repoRoot: repository.repoRoot,
             diffHash: String(body.diffHash),
+            branch: typeof closedTask.branch === 'string'
+                ? closedTask.branch
+                : typeof body.branch === 'string'
+                    ? body.branch
+                    : null,
             taskClosed: true,
             taskVersion: closedTaskVersion,
             taskChanges,
         });
         await this.dependencies.activeContexts.clearCloseIntent(repository.repoFingerprint, String(body.taskId));
+        await this.dependencies.repositories.git
+            .branchStore(repository.repoRoot)
+            .release(String(body.taskId));
         return asJsonValue({
             ...closedTask,
             repository: publicRepository(repository),
@@ -2107,7 +2430,7 @@ export class BridgeService {
                     kind: 'bridge_error',
                     message: error instanceof Error ? error.message : 'Bridge operation failed',
                     retryable: false,
-                    ...(error instanceof RefusalError ? { recovery: error.recovery } : {}),
+                    ...(error instanceof BridgeRecoveryError ? { recovery: error.recovery } : {}),
                 },
             };
         }
@@ -2300,6 +2623,26 @@ function objectValue(value) {
 function objectOrEmpty(value) {
     return objectValue(value ?? undefined) ?? {};
 }
+function archivedProjectGuidance(project) {
+    const projectId = typeof project?.id === 'string' ? project.id : null;
+    const expectedVersion = typeof project?.lockVersion === 'number' ? project.lockVersion : null;
+    if (project?.role === 'owner') {
+        return {
+            projectId,
+            expectedVersion,
+            requiredRole: 'owner',
+            recovery: 'project.restore',
+            nextAction: 'Call project.restore with this project id and lockVersion before continuing.',
+        };
+    }
+    return {
+        projectId,
+        expectedVersion,
+        requiredRole: 'owner',
+        recovery: 'project.member_list',
+        nextAction: 'Call project.member_list with this project id, identify an owner, and ask that owner to restore the archived project.',
+    };
+}
 function slugify(value) {
     return value
         .trim()
@@ -2404,15 +2747,8 @@ function isOfflineLeaseUsable(lease, sessionId, changedPaths, baselineDiffHash)
         return false;
     }
 }
-class RefusalError extends Error {
-    recovery;
-    constructor(message, recovery) {
-        super(message);
-        this.recovery = recovery;
-    }
-}
 function refuse(message, recovery) {
-    return new RefusalError(`${message} Recovery: call ${recovery}.`, recovery);
+    return new BridgeRecoveryError(message, recovery);
 }
 function short(value) {
     return typeof value === 'string' && value.length > 0 ? value.slice(0, 12) : 'none';

package/runtime/dist/src/runtime/principal-state.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { readJson, removeFile, writeJson } from '../utilities/files.js';
 import { sha256 } from '../utilities/hash.js';
+import { BridgeRecoveryError } from './recovery-error.js';
 export class PrincipalStateGuard {
     stateRoot;
     credentials;
@@ -31,7 +32,7 @@ export class PrincipalStateGuard {
                 return;
             }
             if ((await this.outbox.list()).length > 0) {
-                throw new Error('Pending offline work belongs to a different authenticated principal');
+                throw new BridgeRecoveryError('Pending offline work belongs to a different authenticated principal.', 'task.resolve_pending_delivery');
             }
             await this.clearPrincipalState();
             await writeJson(this.ownerPath, {
@@ -44,7 +45,7 @@ export class PrincipalStateGuard {
     async clearAfterLogout() {
         await this.exclusive(async () => {
             if ((await this.outbox.list()).length > 0) {
-                throw new Error('Pending offline work must be resolved before logout');
+                throw new BridgeRecoveryError('Pending offline work must be resolved before logout.', 'task.resolve_pending_delivery');
             }
             await this.clearPrincipalState();
             await this.credentials.clear();