Skip to content

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

fix: recover unbound pending merges at verified heads (#13227)

Adam Eivy6eacc4c17e52
diff --git a/server/services/agentWorkspacePrep.js b/server/services/agentWorkspacePrep.js
index 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 = result
const 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.js
index 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, findAdoptableWorktree
import { 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 worktre
expect(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.js
index 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, p
simplify: false,
// Marker flags consumed by the agent prompt + completion handler
reviewLoopFollowUp: 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, p
const 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, p
return { ...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, reviewTarget
const 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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 () => {