Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: recover unbound pending merges at verified heads (#13227)
Adam Eivy6eacc4c17e52
diff --git a/server/services/agentWorkspacePrep.js b/server/services/agentWorkspacePrep.jsindex 1eeab18623..c3f1e63dc4 100644--- a/server/services/agentWorkspacePrep.js+++ b/server/services/agentWorkspacePrep.js@@ -111,7 +111,7 @@ export { resolveTaskTargetBranch as resolveTaskExistingBranch } from '../lib/tas** @returns {Promise<{ worktreeInfo: object, adoptedFrom: string }|{ refused: string }|null>}*/-async function adoptWorktreeHoldingBranch({ agentId, workspacePath, branchName, preferredPath = null, taskId, allowLiveClaim = false, deepResume = false, adopt = true, reviewTarget = null, preserveLockfiles = false }) {+async function adoptWorktreeHoldingBranch({ agentId, workspacePath, branchName, preferredPath = null, taskId, allowLiveClaim = false, deepResume = false, adopt = true, reviewTarget = null, mergeGuardTarget = null, preserveLockfiles = false }) {// Fail CLOSED on an unreadable agent list: an empty protected set would read as// "nothing is running", which is the one wrong answer here — it would move a// live run's directory. The caller's timed pause is the safe outcome instead.@@ -150,6 +150,11 @@ async function adoptWorktreeHoldingBranch({ agentId, workspacePath, branchName,return null;}+ if (mergeGuardTarget) {+ const { validatePendingMergeRecovery } = await import('./pendingMergeRecovery.js');+ const refused = await validatePendingMergeRecovery({ target: mergeGuardTarget, workspacePath: holder.path, requireCheckout: true, launchTaskId: taskId });+ if (refused) return { refused };+ }if (reviewTarget) {const { validateCleanupReviewTarget } = await import('./cosMergeHandoff.js');const refused = await validateCleanupReviewTarget({ target: reviewTarget, workspacePath: holder.path, requireCheckout: true, launchTaskId: taskId });@@ -235,6 +240,7 @@ async function prepareRequestedWorktree({return { outcome: 'blocked', reason };}const reviewTarget = task.metadata?.cleanupReviewTarget;+ const mergeGuardTarget = task.metadata?.pendingMergeGuardTarget;const pinnedHead = existingBranch ? resolveTaskPinnedHead(task.metadata) : null;if (pinnedHead === '') {return refusePinnedAttach(task, workspacePath, `Task ${task.id} must attach at a reviewed head commit but records none; refusing to check out ${existingBranch}`);@@ -270,6 +276,7 @@ async function prepareRequestedWorktree({// can prove both. Releasing an idle sibling holder in place stays allowed.adopt: !pinnedHead,reviewTarget,+ mergeGuardTarget,preserveLockfiles: isolateDependencies,}): Promise.resolve(null);@@ -310,7 +317,7 @@ async function prepareRequestedWorktree({...(task.metadata?.existingBranch && task.metadata?.resumedFromAgentId ? { resumeBranch: existingBranch } : {}),// Fork coordinates select the remote head, independent of the local branch name.forkHead: forkHead || undefined,- expectedHeadSha: pinnedHead || reviewTarget?.headSha || undefined,+ expectedHeadSha: pinnedHead || reviewTarget?.headSha || mergeGuardTarget?.headSha || undefined,planId: task.metadata?.planId || undefined,linkDependencies: !isolateDependencies,});@@ -521,6 +528,17 @@ export async function prepareAgentWorkspace({ agentId, task, onPrepared = resultconst prepareAndRegister = async () => {const result = await prepareResolvedWorkspace({ agentId, task, workspacePath, resolvedApp, resolvedAppName, isReadOnly });+ if (result.outcome === 'ready' && task.metadata?.pendingMergeGuardTarget) {+ const { validatePendingMergeRecovery } = await import('./pendingMergeRecovery.js');+ const refused = await validatePendingMergeRecovery({ target: task.metadata.pendingMergeGuardTarget, workspacePath: result.workspacePath, requireCheckout: true, launchTaskId: task.id });+ if (refused) {+ await blockTask(task, refused, 'pr-head-moved');+ return onPrepared({ outcome: 'blocked', reason: refused });+ }+ task.metadata.pendingMergeGuardLaunchEvidence = task.metadata.pendingMergeGuardTarget;+ task.metadata.pendingMergeGuardTarget = undefined;+ result.cleanupReviewPinConsumed = true;+ }if (result.outcome === 'ready' && task.metadata?.cleanupReviewTarget) {const { validateCleanupReviewTarget } = await import('./cosMergeHandoff.js');const refused = await validateCleanupReviewTarget({ target: task.metadata.cleanupReviewTarget, workspacePath: result.workspacePath, requireCheckout: true, launchTaskId: task.id });@@ -557,6 +575,17 @@ export async function prepareAgentWorkspace({ agentId, task, onPrepared = result* @returns {Promise<object|null>} the blocked outcome, or null to proceed*/async function refuseUnsafeLaunchTarget({ task, workspacePath, isReadOnly }) {+ const guardTarget = task.metadata?.pendingMergeGuardTarget;+ if (guardTarget) {+ const { validatePendingMergeRecovery } = await import('./pendingMergeRecovery.js');+ const refused = guardTarget.repoPath !== workspacePath || resolveTaskTargetBranch(task.metadata) !== guardTarget.branch || isReadOnly || leavesPrForHuman(task)+ || resolvePrCompletion(task.metadata) !== guardTarget.prCompletion || isTruthyMeta(task.metadata?.reviewLoopLeaveOpen)+ ? 'recovery-target-task-changed' : await validatePendingMergeRecovery({ target: guardTarget, workspacePath, launchTaskId: task.id });+ if (refused) {+ await blockTask(task, refused, 'pr-head-moved');+ return { outcome: 'blocked', reason: refused };+ }+ }const recoveryTarget = task.metadata?.cleanupReviewTarget;if (recoveryTarget) {const { validateCleanupReviewTarget } = await import('./cosMergeHandoff.js');diff --git a/server/services/agentWorkspacePrep.test.js b/server/services/agentWorkspacePrep.test.jsindex 31c43082ef..d1e196f5bc 100644--- a/server/services/agentWorkspacePrep.test.js+++ b/server/services/agentWorkspacePrep.test.js@@ -12,6 +12,8 @@import { describe, it, expect, beforeEach, vi } from 'vitest';const recoveryCheck = vi.hoisted(() => vi.fn(async () => null));+const pendingGuardCheck = vi.hoisted(() => vi.fn(async () => null));+vi.mock('./pendingMergeRecovery.js', () => ({ validatePendingMergeRecovery: (...args) => pendingGuardCheck(...args) }));vi.mock('./cos.js', () => ({}));vi.mock('./cosMergeHandoff.js', () => ({ validateCleanupReviewTarget: (...args) => recoveryCheck(...args) }));const publication = vi.hoisted(() => ({ active: false, refuse: false }));@@ -107,7 +109,7 @@ import { PINNED_HEAD_MOVED, createWorktree, adoptWorktree, findAdoptableWorktreeimport { ensureDir, PATHS } from '../lib/fileUtils.js';import { creativeDirectorScratchCwd } from '../lib/spawnCwd.js';-beforeEach(() => { vi.clearAllMocks(); recoveryCheck.mockReset().mockResolvedValue(null); listWorktrees.mockResolvedValue([]); publication.active = publication.refuse = false; });+beforeEach(() => { vi.clearAllMocks(); recoveryCheck.mockReset().mockResolvedValue(null); pendingGuardCheck.mockReset().mockResolvedValue(null); listWorktrees.mockResolvedValue([]); publication.active = publication.refuse = false; });describe('prepareAgentWorkspace — Creative Director scratch cwd (#4650)', () => {it('pins a CD no-worktree task to an isolated scratch dir and skips the git pull', async () => {@@ -876,6 +878,44 @@ describe('prepareAgentWorkspace — the branch is checked out in another worktreexpect(recoveryCheck).not.toHaveBeenCalled();});+ it('pins a legacy pending-merge recovery checkout and consumes the pin only before registration', async () => {+ const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40), prCompletion: 'merge-on-green' };+ const task = followUpTask({ pendingMergeGuardTarget: target, prCompletion: 'merge-on-green' });+ createWorktree.mockReset().mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: target.branch });+ const registered = vi.fn(async result => {+ expect(task.metadata.pendingMergeGuardTarget).toBeUndefined();+ expect(task.metadata.pendingMergeGuardLaunchEvidence).toEqual(target);+ expect(result.cleanupReviewPinConsumed).toBe(true);+ return result;+ });+ expect((await prepareAgentWorkspace({ agentId: 'agent-new', task, onPrepared: registered })).outcome).toBe('ready');+ expect(createWorktree).toHaveBeenCalledWith('agent-new', PATHS.root, task.id, expect.objectContaining({ expectedHeadSha: target.headSha }));+ expect(pendingGuardCheck.mock.calls.map(([call]) => [call.workspacePath, call.requireCheckout])).toEqual([+ [PATHS.root, undefined], ['/mock/worktrees/agent-new', true],+ ]);+ expect(registered).toHaveBeenCalledOnce();+ });++ it('blocks a stale pending-merge target before touching its checkout', async () => {+ const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40), prCompletion: 'merge-on-green' };+ const task = followUpTask({ pendingMergeGuardTarget: target, prCompletion: 'merge-on-green' });+ pendingGuardCheck.mockResolvedValue('recovery-head-moved');+ expect((await prepareAgentWorkspace({ agentId: 'agent-new', task })).outcome).toBe('blocked');+ expect(createWorktree).not.toHaveBeenCalled();+ expect(task.metadata.pendingMergeGuardTarget).toEqual(target);+ });++ it('verifies a retained legacy checkout before adopting it for guard recovery', async () => {+ const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40), prCompletion: 'merge-on-green' };+ const task = followUpTask({ pendingMergeGuardTarget: target, prCompletion: 'merge-on-green' });+ findAdoptableWorktreeForBranch.mockResolvedValue({ path: '/mock/worktrees/agent-y', agentId: 'agent-y' });+ adoptWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-new', branchName: target.branch, adopted: true });+ expect((await prepareAgentWorkspace({ agentId: 'agent-new', task })).outcome).toBe('ready');+ expect(pendingGuardCheck.mock.calls.map(([call]) => call.workspacePath)).toEqual([PATHS.root, '/mock/worktrees/agent-y', '/mock/worktrees/agent-new']);+ expect(adoptWorktree).toHaveBeenCalledOnce();+ expect(createWorktree).not.toHaveBeenCalled();+ });+it('preserves the pin and holder when target drift is detected before adoption', async () => {const target = { version: 1, repoPath: PATHS.root, branch: 'cos/task-x/agent-y', headSha: 'a'.repeat(40) };const task = followUpTask({ cleanupReviewTarget: target });diff --git a/server/services/agentWorktreeCleanup.js b/server/services/agentWorktreeCleanup.jsindex 1bdab22dd6..4a51c086a3 100644--- a/server/services/agentWorktreeCleanup.js+++ b/server/services/agentWorktreeCleanup.js@@ -13,6 +13,7 @@ import { isLegacyDeepAudit } from '../lib/auditWorkflow.js';*/import { existsSync } from 'fs';+import { isDeepStrictEqual } from 'node:util';import { PORTOS_APP_ID } from '../lib/appIdentity.js';import { join } from 'path';import { emitLog } from './cosEvents.js';@@ -1109,10 +1110,18 @@ export async function releaseRetryHold({ agentId, task, success, agentMetadata }* whether an agent actually started or the task is still waiting (no slots,* daemon stopped, …) rather than guessing.*/-export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, prUrl, prBranch, forkHead = null, sourceWorkspace, prCompletion = PR_COMPLETIONS.REVIEW_THEN_MERGE, reviewers = DEFAULT_REVIEWERS, usernames = [], optionalReviewers = [], reviewerMaxRounds = {}, reviewStopMode = DEFAULT_REVIEW_STOP_MODE, reviewerApplies = false, reviewerModels = null, reviewerEfforts = null, leaveOpen = false, selfReview = false, dispatch = 'queue', reviewTarget = null }) {+export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, prUrl, prBranch, forkHead = null, sourceWorkspace, prCompletion = PR_COMPLETIONS.REVIEW_THEN_MERGE, reviewers = DEFAULT_REVIEWERS, usernames = [], optionalReviewers = [], reviewerMaxRounds = {}, reviewStopMode = DEFAULT_REVIEW_STOP_MODE, reviewerApplies = false, reviewerModels = null, reviewerEfforts = null, leaveOpen = false, selfReview = false, dispatch = 'queue', reviewTarget = null, mergeGuardTarget = null }) {if (!prUrl || !prBranch) return null;if (prCompletion === PR_COMPLETIONS.LEAVE_OPEN) return null;+ if (mergeGuardTarget) {+ const { validatePendingMergeRecovery } = await import('./pendingMergeRecovery.js');+ if (mergeGuardTarget.prUrl !== prUrl || mergeGuardTarget.branch !== prBranch+ || mergeGuardTarget.sourceTaskId !== originalTask?.id || mergeGuardTarget.sourceAgentId !== originalAgentId) return { blocked: 'Merge recovery identity changed' };+ const refused = await validatePendingMergeRecovery({ target: mergeGuardTarget, workspacePath: sourceWorkspace });+ if (refused) return { blocked: refused };+ }+if (reviewTarget) {const { validateCleanupReviewTarget } = await import('./cosMergeHandoff.js');if (reviewTarget.prUrl !== prUrl || reviewTarget.branch !== prBranch@@ -1125,7 +1134,7 @@ export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, p// spawn budget on every CI/conflict handoff and recursively nests its title.// The id hint also recovers receipts written before the marker was retained.if (isTruthyMeta(originalTask?.metadata?.reviewLoopFollowUp) || originalTask?.id?.startsWith('sys-rl-')) {- return resumeReviewLoopCoordinator(originalTask.id, prUrl, prBranch, reviewTarget);+ return resumeReviewLoopCoordinator(originalTask.id, prUrl, prBranch, reviewTarget, mergeGuardTarget);}const parsedPr = git.parsePullRequestUrl(prUrl);@@ -1297,6 +1306,7 @@ export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, psimplify: false,// Marker flags consumed by the agent prompt + completion handlerreviewLoopFollowUp: true,+ ...(mergeGuardTarget ? { pendingMergeGuardTarget: mergeGuardTarget } : {}),...(reviewTarget ? { cleanupReviewTarget: reviewTarget, resumeWorktreePath: reviewTarget.worktreePath } : {}),prCompletion,// Merge-only run: no reviewers, the prompt is a CI-gate-and-merge procedure.@@ -1358,6 +1368,13 @@ export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, pconst immediate = dispatch === 'immediate';const persisted = await addTask(followUpTask, 'internal', { raw: true, suppressDequeue: immediate });+ if (mergeGuardTarget) {+ const { getTaskById } = await import('./cosTaskStore.js');+ const saved = persisted?.id && await getTaskById(persisted.id).catch(() => null);+ if (!saved || !['pending', 'in_progress'].includes(saved.status)+ || !isDeepStrictEqual(saved.metadata?.pendingMergeGuardTarget ?? saved.metadata?.pendingMergeGuardLaunchEvidence, mergeGuardTarget)) return { deferred: true };+ }+// A duplicate rejection persisted NOTHING under `followUpTaskId` — an equivalent// follow-up is already queued under a different id. Return THAT record so a// caller reports (and force-spawns) the task that actually exists instead of the@@ -1391,7 +1408,7 @@ export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, preturn { ...followUpTask, dispatch: { started: true, reason: null } };}-async function resumeReviewLoopCoordinator(taskId, prUrl, prBranch, reviewTarget = null) {+async function resumeReviewLoopCoordinator(taskId, prUrl, prBranch, reviewTarget = null, mergeGuardTarget = null) {const { getTaskById } = await import('./cosTaskStore.js');const task = await getTaskById(taskId);if (!task || task.taskType !== 'internal' || !isTruthyMeta(task.metadata?.reviewLoopFollowUp)@@ -1422,6 +1439,7 @@ async function resumeReviewLoopCoordinator(taskId, prUrl, prBranch, reviewTargetconst result = await updateTask(taskId, {status: 'pending',metadata: { reviewLoopRecoveryReason: 'The handed-off PR needs fresh validation, review or conflict resolution',+ ...(mergeGuardTarget ? { pendingMergeGuardTarget: mergeGuardTarget } : {}),...(reviewTarget ? { cleanupReviewTarget: reviewTarget, resumeWorktreePath: reviewTarget.worktreePath } : {}) },}, 'internal', {expectedStatus: 'completed',diff --git a/server/services/cleanupAgentWorktree.test.js b/server/services/cleanupAgentWorktree.test.jsindex a93556766b..97a1b8632b 100644--- a/server/services/cleanupAgentWorktree.test.js+++ b/server/services/cleanupAgentWorktree.test.js@@ -1,4 +1,6 @@const recoveryCheck = vi.hoisted(() => vi.fn(async () => null));+const mergeRecoveryCheck = vi.hoisted(() => vi.fn(async () => null));+vi.mock('./pendingMergeRecovery.js', () => ({ validatePendingMergeRecovery: (...args) => mergeRecoveryCheck(...args) }));vi.mock('./cosMergeHandoff.js', () => ({ validateCleanupReviewTarget: (...args) => recoveryCheck(...args) }));vi.mock('./branchCompletionPolicy.js', () => ({ recordBranchCompletionPolicy: vi.fn() }));vi.mock('./cosClaimOwnership.js', () => ({ readClaimOwnershipAgents: vi.fn() }));@@ -1913,6 +1915,24 @@ describe('spawnReviewLoopFollowUp', () => {addTask.mockResolvedValue({ id: 'sys-rl-x' });forceSpawnTask.mockResolvedValue({ success: true });readClaimOwnershipAgents.mockResolvedValue([]);+ mergeRecoveryCheck.mockReset().mockResolvedValue(null);+ });++ it('transfers unbound merge custody only to a persisted task carrying the exact initial head', async () => {+ const originalTask = { id: 'source-task', metadata: { app: 'example' } };+ const target = { sourceAgentId: 'owner', sourceTaskId: originalTask.id, prUrl: 'https://github.com/o/r/pull/7', branch: 'feature', headSha: 'a'.repeat(40) };+ const request = { originalAgentId: 'owner', originalTask, prUrl: target.prUrl, prBranch: target.branch,+ sourceWorkspace: '/repo', prCompletion: 'merge-on-green', reviewers: [], mergeGuardTarget: target };+ getTaskById.mockResolvedValue({ id: 'sys-rl-x', status: 'pending', metadata: { pendingMergeGuardTarget: target } });+ expect((await spawnReviewLoopFollowUp(request)).metadata.pendingMergeGuardTarget).toEqual(target);+ // Auto-dequeue may already have consumed the verified initial pin.+ getTaskById.mockResolvedValue({ id: 'sys-rl-x', status: 'in_progress', metadata: { pendingMergeGuardLaunchEvidence: target } });+ expect((await spawnReviewLoopFollowUp(request)).metadata.pendingMergeGuardTarget).toEqual(target);+ addTask.mockResolvedValue({ id: 'existing', duplicate: true });+ getTaskById.mockResolvedValue({ id: 'existing', status: 'pending', metadata: {} });+ expect(await spawnReviewLoopFollowUp(request)).toEqual({ deferred: true });+ mergeRecoveryCheck.mockResolvedValue('recovery-head-moved');+ expect(await spawnReviewLoopFollowUp(request)).toEqual({ blocked: 'recovery-head-moved' });});it('pins a missing-review followup to its inspected owner and head without resetting the task budget', async () => {diff --git a/server/services/cosMergeHandoff.js b/server/services/cosMergeHandoff.jsindex 418474d8fc..621bd68159 100644--- a/server/services/cosMergeHandoff.js+++ b/server/services/cosMergeHandoff.js@@ -10,6 +10,7 @@* at the deferred merge instant, and it can merge before unenforced checks run.*/import { randomUUID } from 'node:crypto';+import { followUpRoster } from './mergeFollowUpPolicy.js';import { readFile } from 'node:fs/promises';import { resolve } from 'node:path';import { execGh } from './github.js';@@ -85,27 +86,6 @@ function reviewEvidenceAccepted({ status, head: reviewedHead }, head, policy, {return status === 'clean' && (allOptional || reviewedHead === head);}-async function followUpRoster(task, policy) {- if (policy !== PR_COMPLETIONS.REVIEW_THEN_MERGE) return { reviewers: [], usernames: [], optionalReviewers: [], reviewerMaxRounds: {} };- const [{ resolveReviewLoopOptions }, { normalizeReviewers }] = await Promise.all([- import('./codeReview.js'), import('../lib/validation.js'),- ]);- const metadata = { ...task.metadata };- if (isTruthyMeta(metadata.reviewLoopFollowUp)) {- for (const [key, saved] of Object.entries({ reviewers: 'reviewLoopReviewers', usernames: 'reviewLoopReviewerUsernames',- optionalReviewers: 'reviewLoopOptionalReviewers', reviewerMaxRounds: 'reviewLoopReviewerMaxRounds',- reviewStopMode: 'reviewLoopStopMode', reviewerModels: 'reviewLoopReviewerModels', reviewerEfforts: 'reviewLoopReviewerEfforts' })) {- if (Object.hasOwn(metadata, saved)) metadata[key] = metadata[saved];- }- }- const options = await resolveReviewLoopOptions(metadata, { normalize: normalizeReviewers });- return {- reviewers: options.reviewers, usernames: options.usernames,- optionalReviewers: options.optionalReviewers, reviewerMaxRounds: options.reviewerMaxRounds,- reviewStopMode: options.reviewStopMode, reviewerModels: options.reviewerModels, reviewerEfforts: options.reviewerEfforts,- };-}-/** Read-only target check shared by orphan review and its eventual workspace launch.* This is permission to inspect one head, never merge admission or proof of review.*/diff --git a/server/services/mergeFollowUpPolicy.js b/server/services/mergeFollowUpPolicy.jsnew file mode 100644index 0000000000..4f3e31fced--- /dev/null+++ b/server/services/mergeFollowUpPolicy.js@@ -0,0 +1,23 @@+import { PR_COMPLETIONS } from '../lib/prDisposition.js';+import { isTruthyMeta } from '../lib/metadataFlags.js';++export async function followUpRoster(task, policy) {+ if (policy !== PR_COMPLETIONS.REVIEW_THEN_MERGE) return { reviewers: [], usernames: [], optionalReviewers: [], reviewerMaxRounds: {} };+ const [{ resolveReviewLoopOptions }, { normalizeReviewers }] = await Promise.all([+ import('./codeReview.js'), import('../lib/validation.js'),+ ]);+ const metadata = { ...task.metadata };+ if (isTruthyMeta(metadata.reviewLoopFollowUp)) {+ for (const [key, saved] of Object.entries({ reviewers: 'reviewLoopReviewers', usernames: 'reviewLoopReviewerUsernames',+ optionalReviewers: 'reviewLoopOptionalReviewers', reviewerMaxRounds: 'reviewLoopReviewerMaxRounds',+ reviewStopMode: 'reviewLoopStopMode', reviewerModels: 'reviewLoopReviewerModels', reviewerEfforts: 'reviewLoopReviewerEfforts' })) {+ if (Object.hasOwn(metadata, saved)) metadata[key] = metadata[saved];+ }+ }+ const options = await resolveReviewLoopOptions(metadata, { normalize: normalizeReviewers });+ return {+ reviewers: options.reviewers, usernames: options.usernames,+ optionalReviewers: options.optionalReviewers, reviewerMaxRounds: options.reviewerMaxRounds,+ reviewStopMode: options.reviewStopMode, reviewerModels: options.reviewerModels, reviewerEfforts: options.reviewerEfforts,+ };+}diff --git a/server/services/pendingMergeGuard.js b/server/services/pendingMergeGuard.jsindex 969268b2b7..266c977975 100644--- a/server/services/pendingMergeGuard.js+++ b/server/services/pendingMergeGuard.js@@ -28,7 +28,7 @@ async function supportsPendingMergeGuard(repoPath) {return source !== null && source.includes("case '--guards-only':") && source.includes("case '--merged-with':");}-async function verifyCheckout(repoPath, worktreePath, branch, headSha) {+export async function verifyPendingMergeCheckout(repoPath, worktreePath, branch, headSha) {if (!worktreePath || resolve(repoPath) === resolve(worktreePath)) return false;const read = async (args, cwd = worktreePath) => (await execGit(args, cwd)).stdout.trim();const checked = await Promise.all([@@ -46,10 +46,11 @@ async function verifyCheckout(repoPath, worktreePath, branch, headSha) {/** Runs only on the handed-off, reviewed checkout, before acquiring admission. */export async function preparePendingMergeGuard({ app, entry, binding, prView, readDefault, env }) {if (!await supportsPendingMergeGuard(app.repoPath)) return { ok: true, evidence: null };- const worktreePath = binding?.worktreePath;+ if (!binding) return { ok: false, reason: 'merged-tree-recovery-required', evidence: { headSha: prView.headRefOid } };+ const worktreePath = binding.worktreePath;const headSha = binding?.headSha;if (!SHA.test(headSha || '') || prView.headRefOid !== headSha- || !await verifyCheckout(app.repoPath, worktreePath, entry.prBranch, headSha)) {+ || !await verifyPendingMergeCheckout(app.repoPath, worktreePath, entry.prBranch, headSha)) {return { ok: false, reason: 'merged-tree-checkout-unverified' };}if (!await supportsPendingMergeGuard(worktreePath)) return { ok: false, reason: 'merged-tree-command-unavailable' };@@ -81,7 +82,7 @@ export async function preparePendingMergeGuard({ app, entry, binding, prView, re...evidence, failedTest: failedTest ? summarizeMergeGuardOutput(failedTest) : null,} };}- if (!await verifyCheckout(app.repoPath, worktreePath, entry.prBranch, headSha)) {+ if (!await verifyPendingMergeCheckout(app.repoPath, worktreePath, entry.prBranch, headSha)) {return { ok: false, reason: 'merged-tree-checkout-changed', evidence };}return { ok: true, evidence };diff --git a/server/services/pendingMergeGuard.test.js b/server/services/pendingMergeGuard.test.jsindex 69f96a1668..eace4114cf 100644--- a/server/services/pendingMergeGuard.test.js+++ b/server/services/pendingMergeGuard.test.js@@ -55,6 +55,12 @@ if (base.trim() === 'strict' && ${fail}) {}describe('pending merged-tree validation', () => {+ it('requires checkout recovery for a supported repository without a handoff instead of bypassing guards', async () => {+ const { input, headSha } = await fixture();+ expect(await preparePendingMergeGuard({ ...input, binding: null })).toEqual({+ ok: false, reason: 'merged-tree-recovery-required', evidence: { headSha },+ });+ });it('fetches the live base, pins both full SHAs, and preserves the clean claim checkout', async () => {vi.stubEnv('PORTOS_API_TOKEN', 'example-secret-not-for-tests');const { input, git, worktreePath, headSha, baseSha } = await fixture();diff --git a/server/services/pendingMergeRecovery.js b/server/services/pendingMergeRecovery.jsnew file mode 100644index 0000000000..e1392914a1--- /dev/null+++ b/server/services/pendingMergeRecovery.js@@ -0,0 +1,85 @@+import { resolve } from 'node:path';+import { isDeepStrictEqual } from 'node:util';+import { PR_COMPLETIONS, leavesPrForHuman, resolvePrCompletion } from '../lib/prDisposition.js';+import { isTruthyMeta } from '../lib/metadataFlags.js';+import { claimCheckoutOwnerReason } from '../lib/claimContinuation.js';++// Legacy producers recorded a source, not a handed-off checkout. Recover their+// current authority instead of inventing a receipt or merging without guards.+export async function preparePendingMergeRecovery({ app, entry, headSha, launchTaskId = null }) {+ if (!/^[a-f0-9]{40}$/.test(headSha || '')) return { blocked: 'recovery-head-unreadable' };+ const { readClaimOwnershipAgents } = await import('./cosClaimOwnershipState.js');+ const agents = await readClaimOwnershipAgents();+ if (!agents || agents.some(agent => agent.taskId !== launchTaskId+ && (agent.id === entry.sourceAgentId || agent.taskId === entry.sourceTask?.id)+ && ['running', 'paused', 'orphaned', 'interrupted'].includes(agent.status))) return { deferred: true };+ const ignoreIds = agents.filter(agent => agent.taskId === launchTaskId).map(agent => agent.id);+ if (claimCheckoutOwnerReason({ branchName: entry.prBranch, sourceWorkspace: app.repoPath, agents, ignoreIds })) return { deferred: true };+ let task;+ const snapshot = !entry.sourceAgentId && entry.sourceTask?.id === `quality-snapshot-${app.id}`+ && entry.prBranch === 'portos/quality-snapshot';+ if (snapshot) {+ // The scheduled publisher has no agent task and deletes its temporary tree.+ // Its fixed producer policy is merge-on-green; never fabricate a task owner.+ task = entry.sourceTask;+ } else {+ const { getTaskById } = await import('./cosTaskStore.js');+ task = await getTaskById(entry.sourceTask?.id).catch(() => null);+ if (!task || task.metadata?.app !== app.id) return { blocked: 'recovery-owner-unreadable' };+ if (['pending', 'in_progress'].includes(task.status) && task.id !== launchTaskId) return { deferred: true };+ if (task.status !== 'completed' && !(task.id === launchTaskId && ['pending', 'in_progress'].includes(task.status))) return { blocked: 'recovery-owner-not-completed' };+ if (leavesPrForHuman(task) || isTruthyMeta(task.metadata?.readOnly) || isTruthyMeta(task.metadata?.reviewLoopLeaveOpen)+ || resolvePrCompletion(task.metadata) === PR_COMPLETIONS.LEAVE_OPEN) return { blocked: 'recovery-owner-policy-held' };+ }+ const policy = snapshot ? PR_COMPLETIONS.MERGE_ON_GREEN : resolvePrCompletion(task.metadata);+ const { followUpRoster } = await import('./mergeFollowUpPolicy.js');+ const roster = await followUpRoster(task, policy);+ const target = { version: 1, appId: app.id, repoPath: app.repoPath, prUrl: entry.prUrl,+ branch: entry.prBranch, headSha, sourceTaskId: task.id, sourceAgentId: entry.sourceAgentId || null,+ prCompletion: policy, roster };+ return { target, task, policy: { prCompletion: policy, ...roster } };+}++/** Rechecked before dispatch, before checkout, and before owner registration. */+export async function validatePendingMergeRecovery({ target, workspacePath, requireCheckout = false, launchTaskId = null }) {+ if (!target || target.version !== 1) return 'recovery-target-invalid';+ const { getAppById } = await import('./apps.js');+ const app = await getAppById(target.appId).catch(() => null);+ if (!app || app.repoPath !== target.repoPath) return 'recovery-app-changed';+ const entry = { prUrl: target.prUrl, prBranch: target.branch, sourceAgentId: target.sourceAgentId,+ sourceTask: { id: target.sourceTaskId, metadata: { app: app.id } } };+ const current = await preparePendingMergeRecovery({ app, entry, headSha: target.headSha, launchTaskId });+ if (current.blocked || current.deferred || !isDeepStrictEqual(current.target, target)) return current.blocked || 'recovery-owner-changed';+ const [{ getOriginInfo }, { parsePullRequestUrl }, { githubRepoSpec }, { resolveForgeExecOptions }, { execGh }, { repositoryKey }] = await Promise.all([+ import('../lib/gitRemote.js'), import('../lib/gitForge.js'), import('../lib/workTracker.js'),+ import('./forgeExecOptions.js'), import('./github.js'), import('./cosMergeAdmission.js'),+ ]);+ const origin = await getOriginInfo(app.repoPath).catch(() => null);+ const pr = parsePullRequestUrl(target.prUrl);+ if (!origin || !pr || repositoryKey({ host: pr.host, fullName: `${pr.owner}/${pr.repo}` }) !== repositoryKey(origin)) return 'recovery-repository-changed';+ const options = await resolveForgeExecOptions(app.repoPath, { forgeAccount: app.forgeAccount });+ const raw = await execGh(['pr', 'view', String(pr.number), '--repo', githubRepoSpec(origin),+ '--json', 'state,isDraft,isCrossRepository,headRefName,headRefOid'], undefined,+ { ...options, backoffKey: githubRepoSpec(origin) }).catch(() => null);+ let view;+ try { view = JSON.parse(raw); } catch { return 'recovery-pr-unreadable'; }+ if (view?.state !== 'OPEN' || view.isDraft !== false || view.isCrossRepository !== false+ || view.headRefName !== target.branch || view.headRefOid !== target.headSha) return 'recovery-head-moved';+ if (requireCheckout) {+ const { verifyPendingMergeCheckout } = await import('./pendingMergeGuard.js');+ if (!await verifyPendingMergeCheckout(app.repoPath, workspacePath, target.branch, target.headSha)) return 'recovery-checkout-changed';+ } else if (resolve(workspacePath) !== resolve(app.repoPath)) return 'recovery-repository-changed';+ // A policy edit or an owner starting during the forge reads wins the race.+ const latest = await preparePendingMergeRecovery({ app, entry, headSha: target.headSha, launchTaskId });+ if (!isDeepStrictEqual(latest.target, target)) return latest.blocked || 'recovery-owner-changed';+ if (launchTaskId) {+ const { getTaskById } = await import('./cosTaskStore.js');+ const launch = await getTaskById(launchTaskId).catch(() => null);+ if (!launch || !['pending', 'in_progress'].includes(launch.status) || leavesPrForHuman(launch)+ || isTruthyMeta(launch.metadata?.readOnly) || isTruthyMeta(launch.metadata?.reviewLoopLeaveOpen)+ || resolvePrCompletion(launch.metadata) !== target.prCompletion+ || launch.metadata?.reviewLoopPRUrl !== target.prUrl || launch.metadata?.reviewLoopPRBranch !== target.branch+ || !isDeepStrictEqual(launch.metadata?.pendingMergeGuardTarget, target)) return 'recovery-launch-task-changed';+ }+ return null;+}diff --git a/server/services/pendingMergeRecovery.test.js b/server/services/pendingMergeRecovery.test.jsnew file mode 100644index 0000000000..3b1266bda0--- /dev/null+++ b/server/services/pendingMergeRecovery.test.js@@ -0,0 +1,63 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++const state = vi.hoisted(() => ({ app: null, tasks: new Map(), agents: [], pr: null }));+const forge = vi.hoisted(() => vi.fn());+const checkout = vi.hoisted(() => vi.fn());+vi.mock('./apps.js', () => ({ getAppById: async () => state.app }));+vi.mock('./cosTaskStore.js', () => ({ getTaskById: async id => state.tasks.get(id) }));+vi.mock('./cosClaimOwnershipState.js', () => ({ readClaimOwnershipAgents: async () => state.agents }));+vi.mock('./forgeExecOptions.js', () => ({ resolveForgeExecOptions: async () => ({ env: { GH_TOKEN: 'fixture-account' } }) }));+vi.mock('./github.js', () => ({ execGh: (...args) => forge(...args) }));+vi.mock('../lib/gitRemote.js', () => ({ getOriginInfo: async () => ({ host: 'github.com', fullName: 'owner/repo' }) }));+vi.mock('./pendingMergeGuard.js', () => ({ verifyPendingMergeCheckout: (...args) => checkout(...args) }));+import { preparePendingMergeRecovery, validatePendingMergeRecovery } from './pendingMergeRecovery.js';++const headSha = 'a'.repeat(40);+const entry = { prUrl: 'https://github.com/owner/repo/pull/88', prBranch: 'claim/issue-1',+ sourceAgentId: 'owner', sourceTask: { id: 'source-task' } };+beforeEach(() => {+ state.app = { id: 'app1', repoPath: '/repo', forgeAccount: 'configured-account' };+ state.agents = [];+ state.tasks = new Map([['source-task', { id: 'source-task', status: 'completed', metadata: { app: 'app1', prCompletion: 'merge-on-green' } }]]);+ state.pr = { state: 'OPEN', isDraft: false, isCrossRepository: false, headRefName: entry.prBranch, headRefOid: headSha };+ forge.mockReset().mockImplementation(async () => JSON.stringify(state.pr));+ checkout.mockReset().mockResolvedValue(true);+});++describe('pending merge recovery admission', () => {+ it('binds dispatch and checkout launch to the same published head and persisted target', async () => {+ const { target } = await preparePendingMergeRecovery({ app: state.app, entry, headSha });+ expect(await validatePendingMergeRecovery({ target, workspacePath: '/repo' })).toBeNull();+ state.tasks.set('recovery-task', { id: 'recovery-task', status: 'pending', metadata: {+ prCompletion: target.prCompletion, pendingMergeGuardTarget: target,+ reviewLoopPRUrl: target.prUrl, reviewLoopPRBranch: target.branch,+ } });+ const launch = { target, workspacePath: '/worktree', requireCheckout: true, launchTaskId: 'recovery-task' };+ expect(await validatePendingMergeRecovery(launch)).toBeNull();+ expect(checkout).toHaveBeenCalledWith('/repo', '/worktree', target.branch, headSha);+ state.pr.headRefOid = 'b'.repeat(40);+ expect(await validatePendingMergeRecovery(launch)).toBe('recovery-head-moved');+ state.pr.headRefOid = headSha;+ state.tasks.get('recovery-task').metadata.pendingMergeGuardTarget = { ...target, headSha: 'b'.repeat(40) };+ expect(await validatePendingMergeRecovery(launch)).toBe('recovery-launch-task-changed');+ });++ it('withholds launch if the source policy changes during remote evidence reads', async () => {+ const { target } = await preparePendingMergeRecovery({ app: state.app, entry, headSha });+ forge.mockImplementation(async () => {+ state.tasks.get('source-task').metadata.prCompletion = 'leave-open';+ return JSON.stringify(state.pr);+ });+ expect(await validatePendingMergeRecovery({ target, workspacePath: '/repo' })).toBe('recovery-owner-policy-held');+ });++ it('recognizes only the scheduled snapshot producer as an ownerless source', async () => {+ const snapshot = { ...entry, sourceAgentId: null, sourceTask: { id: 'quality-snapshot-app1' }, prBranch: 'portos/quality-snapshot' };+ state.pr.headRefName = snapshot.prBranch;+ const { target } = await preparePendingMergeRecovery({ app: state.app, entry: snapshot, headSha });+ expect(target).toMatchObject({ sourceAgentId: null, sourceTaskId: 'quality-snapshot-app1', headSha });+ expect(await validatePendingMergeRecovery({ target, workspacePath: '/repo' })).toBeNull();+ expect(await preparePendingMergeRecovery({ app: state.app, entry: { ...snapshot, prBranch: 'other' }, headSha }))+ .toEqual({ blocked: 'recovery-owner-unreadable' });+ });+});diff --git a/server/services/prWatcher.js b/server/services/prWatcher.jsindex b14f0250a6..975a831938 100644--- a/server/services/prWatcher.js+++ b/server/services/prWatcher.js@@ -700,6 +700,9 @@ async function attemptAdmittedMerge(entry, binding, prView, ctx) {});if (!guard.ok) {const retained = { ...entry, mergedTreeGuard: { ...guard.evidence, reason: guard.reason } };+ if (guard.reason === 'merged-tree-recovery-required') {+ return { step: await recoverUnboundMerge(retained, prView, ctx) };+ }if (['merged-tree-validation-unavailable', 'merged-tree-default-branch-unavailable'].includes(guard.reason)) {return { step: await advanceTicks(ctx, entry, retained, binding, { reason: guard.reason }) };}@@ -737,6 +740,35 @@ async function attemptAdmittedMerge(entry, binding, prView, ctx) {return { assessed };}+// Legacy queue producers cannot supply a verified checkout. Transfer custody+// only after a pinned recovery is persisted; missing authority remains queued.+async function recoverUnboundMerge(entry, prView, ctx) {+ try {+ const { preparePendingMergeRecovery } = await import('./pendingMergeRecovery.js');+ const prepared = await preparePendingMergeRecovery({ app: ctx.app, entry, headSha: prView.headRefOid });+ if (prepared.deferred) return { outcome: entry, tally: { waiting: 1 } };+ let recovery = prepared;+ if (prepared.target) {+ const { spawnReviewLoopFollowUp } = await import('./agentWorktreeCleanup.js');+ recovery = await spawnReviewLoopFollowUp({ originalAgentId: entry.sourceAgentId || null,+ originalTask: prepared.task, prUrl: entry.prUrl, prBranch: entry.prBranch,+ sourceWorkspace: ctx.app.repoPath, ...prepared.policy, mergeGuardTarget: prepared.target });+ }+ if (recovery?.deferred) return { outcome: entry, tally: { waiting: 1 } };+ if (recovery?.blocked) {+ await notifyPendingMergeTimeout(ctx.app, entry, null,+ `PR #${entry.prNumber} needs a verified checkout before merged-tree validation: ${recovery.blocked}. The pending entry is retained for explicit owner recovery.`);+ return { outcome: { ...entry, recoveryBlocked: recovery.blocked }, tally: { waiting: 1 } };+ }+ if (!recovery?.id) return { outcome: entry, tally: { errors: 1 } };+ return { outcome: null, tally: { escalated: 1 } };+ } catch (error) {+ const { summarizeMergeGuardOutput } = await import('./pendingMergeGuard.js');+ console.error(`❌ Pending PR #${entry.prNumber} checkout recovery could not be persisted: ${summarizeMergeGuardOutput(error.message)}`);+ return { outcome: entry, tally: { errors: 1 } };+ }+}+// Merge a ready PR, otherwise spend a tick toward the budget.async function mergeOrSettle(entry, binding, prView, ctx) {const ready = isPendingMergeReady(prView);diff --git a/server/services/prWatcher.test.js b/server/services/prWatcher.test.jsindex 503a5e8dc4..588e6e1044 100644--- a/server/services/prWatcher.test.js+++ b/server/services/prWatcher.test.js@@ -76,6 +76,11 @@ vi.mock('./apps.js', () => ({}));const tasksById = vi.hoisted(() => new Map());+const recoveryAgents = vi.hoisted(() => ({ value: [] }));+vi.mock('./cosClaimOwnershipState.js', () => ({ readClaimOwnershipAgents: async () => recoveryAgents.value }));+vi.mock('./codeReview.js', () => ({ resolveReviewLoopOptions: async metadata => ({+ reviewers: metadata.reviewers || [], usernames: metadata.usernames || [], optionalReviewers: [], reviewerMaxRounds: {},+}) }));vi.mock('./cosTaskStore.js', () => ({getTaskById: async (id) => tasksById.get(id) ?? null,}));@@ -130,6 +135,7 @@ beforeEach(() => {getOriginInfoMock.mockReset();mockApps.clear();tasksById.clear();+ recoveryAgents.value = [];__resetSelfLoginCache();});@@ -670,6 +676,65 @@ describe('merge-only PR watcher', () => {return { app, evidence };};+ const legacy = (snapshot = false) => {+ const { app } = setup();+ app.pendingMergePrs = [pendingMerge(snapshot ? { sourceAgentId: null, prBranch: 'portos/quality-snapshot',+ sourceTask: { id: `quality-snapshot-${app.id}`, description: 'Publish PortOS quality snapshot', metadata: { app: app.id } } } : {})];+ tasksById.get('task-88').metadata.app = app.id;+ prepareGuardMock.mockResolvedValue({ ok: false, reason: 'merged-tree-recovery-required', evidence: { headSha: guard.headSha } });+ return app;+ };++ it.each([false, true])('recovers an unbound producer with a pinned checkout task before any merge (snapshot=%s)', async snapshot => {+ const app = legacy(snapshot);+ expect(await processPendingMergePrs(app)).toMatchObject({ escalated: 1, merged: 0 });+ expect(spawnReviewLoopFollowUpMock).toHaveBeenCalledWith(expect.objectContaining({+ prCompletion: 'merge-on-green', reviewers: [],+ mergeGuardTarget: expect.objectContaining({ headSha: guard.headSha, appId: app.id,+ sourceTaskId: snapshot ? `quality-snapshot-${app.id}` : 'task-88' }),+ }));+ expect(readPendingMergePrs(mockApps.get(app.id))).toEqual([]);+ expect(mergePrMock).not.toHaveBeenCalled();+ expect(admissionState.state.mergeAdmissions).toEqual({});+ });++ it('retains the queue while a completed source still has an active worker', async () => {+ const app = legacy();+ recoveryAgents.value = [{ id: 'agent-88', taskId: 'task-88', status: 'running' }];+ expect(await processPendingMergePrs(app)).toMatchObject({ waiting: 1 });+ expect(readPendingMergePrs(mockApps.get(app.id))).toHaveLength(1);+ expect(spawnReviewLoopFollowUpMock).not.toHaveBeenCalled();+ expect(mergePrMock).not.toHaveBeenCalled();+ });++ it('preserves the live source review policy and roster instead of the skinny queued metadata', async () => {+ const app = legacy();+ Object.assign(tasksById.get('task-88').metadata, { prCompletion: 'review-then-merge', reviewers: ['claude'], usernames: ['reviewer'] });+ await processPendingMergePrs(app);+ expect(spawnReviewLoopFollowUpMock).toHaveBeenCalledWith(expect.objectContaining({+ prCompletion: 'review-then-merge', reviewers: ['claude'], usernames: ['reviewer'],+ }));+ expect(mergePrMock).not.toHaveBeenCalled();+ });++ it('holds changed human completion policy without dispatching or merging', async () => {+ const app = legacy();+ tasksById.get('task-88').metadata.prCompletion = 'leave-open';+ await processPendingMergePrs(app);+ expect(readPendingMergePrs(mockApps.get(app.id))[0]).toMatchObject({ recoveryBlocked: 'recovery-owner-policy-held' });+ expect(spawnReviewLoopFollowUpMock).not.toHaveBeenCalled();+ expect(mergePrMock).not.toHaveBeenCalled();+ });++ it.each(['throw', 'unpersisted', 'deferred'])('retains queue custody when checkout recovery is %s', async outcome => {+ const app = legacy();+ if (outcome === 'throw') spawnReviewLoopFollowUpMock.mockRejectedValue(new Error('store unavailable'));+ else spawnReviewLoopFollowUpMock.mockResolvedValue(outcome === 'deferred' ? { deferred: true } : null);+ await processPendingMergePrs(app);+ expect(readPendingMergePrs(mockApps.get(app.id))[0]).toMatchObject({ mergedTreeGuard: { headSha: guard.headSha, reason: 'merged-tree-recovery-required' } });+ expect(mergePrMock).not.toHaveBeenCalled();+ });+it('retains a failing combined-tree receipt and log without taking admission or merging', async () => {const { app } = setup();prepareGuardMock.mockImplementation(async () => {