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: quality snapshot publisher defers its merge while a claim holds repository admission (#10731)

Adam Eivyd37b6ebeec7c
diff --git a/server/services/appQualitySnapshotAdmission.test.js b/server/services/appQualitySnapshotAdmission.test.js
new file mode 100644
index 0000000000..9f70033659
--- /dev/null
+++ b/server/services/appQualitySnapshotAdmission.test.js
@@ -0,0 +1,176 @@
+import { it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { QUALITY_SNAPSHOT_BRANCH, publishAppQualitySnapshot, __resetQualitySnapshotPublishState } from './appQualitySnapshotFile.js';
+import { qualityFileFromWireSnapshot } from './appQualitySnapshotFormat.js';
+import { claimMergeAdmission } from './cosMergeAdmission.js';
+
+// The publisher's immediate merge shares the claim flow's REAL admission logic
+// over a synthetic runtime store: only the store and the git remote are doubled.
+const admissionState = vi.hoisted(() => ({ state: { agents: {}, mergeAdmissions: {} }, saveFails: false }));
+vi.mock('./cosState.js', async () => {
+ const { createFileWriteQueue } = await import('../lib/fileWriteQueue.js');
+ return {
+ withStateLock: createFileWriteQueue(),
+ loadState: async () => admissionState.state,
+ saveState: async state => {
+ if (admissionState.saveFails) throw new Error('state write failed');
+ admissionState.state = state;
+ },
+ readMergeAdmissionStateForSafetyCheck: async () => ({ trusted: true, ...structuredClone(admissionState.state) }),
+ };
+});
+vi.mock('../lib/gitRemote.js', () => ({
+ getOriginInfo: async path => (path === '/repos/unreadable' ? null
+ : { host: 'github.com', fullName: path === '/repos/other-app' ? 'example/other' : 'example/app' }),
+}));
+
+const app = { id: 'example-id', repoPath: '/repos/example-app' };
+const prUrl = 'https://github.com/example/app/pull/42';
+const glabUrl = 'https://gitlab.com/example/app/-/merge_requests/7';
+const measurements = [{
+ measurementId: 'b'.repeat(64), assessedAt: '2026-09-10T10:00:00Z',
+ report: { version: 1, category: 'security', score: 82, worstSeverity: 5, coverage: 'broad', confidence: 'high', scannedFiles: 12, totalFiles: 12 },
+}];
+const snapshot = { schemaVersion: 1, repository: 'a'.repeat(64), measurements };
+const missingShow = { exitCode: 1, stdout: '', stderr: 'missing' };
+
+// `onBranch` simulates the stable snapshot branch already carrying the file.
+const makeDeps = ({ glab = false, onBranch = false, mergeFails = false, ...overrides } = {}) => ({
+ git: {
+ isRepo: async () => true,
+ getRemote: async () => ({ origin: { fetch: '[email protected]:example/app.git' } }),
+ fetchOrigin: async () => true,
+ getDefaultBranch: async () => 'main',
+ execGit: vi.fn(async args => (onBranch && args[0] === 'show' && String(args[1]).includes(QUALITY_SNAPSHOT_BRANCH)
+ ? { exitCode: 0, stdout: qualityFileFromWireSnapshot(snapshot), stderr: '' }
+ : args[0] === 'show' || args[0] === 'rev-parse' ? missingShow : { exitCode: 0, stdout: '', stderr: '' })),
+ stageFiles: async () => true,
+ unstageFiles: async () => true,
+ commit: async () => ({ hash: 'abc1234' }),
+ createPR: vi.fn(async () => ({ success: true, url: glab ? glabUrl : prUrl, cli: glab ? 'glab' : 'gh' })),
+ mergePR: vi.fn(async () => (mergeFails ? { success: false, error: 'required status checks' } : { success: true })),
+ parsePullRequestUrl: () => ({ number: glab ? 7 : 42 }),
+ },
+ writeFile: vi.fn(async () => true),
+ buildQualitySnapshot: async () => snapshot,
+ mkdtemp: async () => '/tmp/portos-quality-test',
+ rm: async () => {},
+ addWorktree: vi.fn(async () => true),
+ execGlab: vi.fn(async () => ''),
+ queuePendingMerge: vi.fn(async () => true),
+ probePrForBranch: vi.fn(async () => (onBranch
+ ? { prState: 'OPEN', prUrl: glab ? glabUrl : prUrl, prNumber: glab ? 7 : 42, cli: glab ? 'glab' : 'gh', readable: true }
+ : { prState: null, readable: true })),
+ ...overrides,
+});
+
+const startClaim = async (agentId = 'parent') => {
+ admissionState.state.agents[agentId] = {
+ id: agentId, taskId: `task-${agentId}`, startedAt: '2026-01-01', status: 'running',
+ metadata: { sourceWorkspace: '/repos/example-app', claimPicksOwnBranch: true },
+ };
+ const lease = await claimMergeAdmission({ agentId, action: 'acquire' });
+ expect(lease.admitted).toBe(true);
+ return lease;
+};
+
+beforeEach(() => {
+ __resetQualitySnapshotPublishState();
+ admissionState.state = { agents: {}, mergeAdmissions: {} };
+ admissionState.saveFails = false;
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+afterEach(() => vi.restoreAllMocks());
+
+// Uniquely pins the #10731 contract: preparation and PR publication stay
+// concurrent with a claim, but nothing advances the default branch while the
+// claim's lease is live — and the PR remains recoverable afterwards.
+it('publishes the PR but defers every merge while a claim holds the repository lease (GitHub)', async () => {
+ const lease = await startClaim();
+ const deps = makeDeps();
+ expect(await publishAppQualitySnapshot(app, deps)).toEqual({
+ published: true, hash: 'abc1234', path: '.quality.json', prUrl, prNumber: 42,
+ merged: false, queuedMerge: true, deferredMerge: true,
+ });
+ expect(deps.writeFile).toHaveBeenCalled();
+ expect(deps.git.createPR).toHaveBeenCalled();
+ expect(deps.git.mergePR).not.toHaveBeenCalled();
+ expect(deps.queuePendingMerge).toHaveBeenCalledWith('example-id', expect.objectContaining({ prNumber: 42 }));
+ // The claim's own lease is untouched by the deferred publisher.
+ expect(await claimMergeAdmission({ agentId: 'parent', action: 'check', token: lease.token }))
+ .toMatchObject({ admitted: true });
+});
+
+it('defers the stable-branch reuse path without new measurements or merge calls', async () => {
+ await startClaim();
+ const deps = makeDeps({ onBranch: true });
+ expect(await publishAppQualitySnapshot(app, deps)).toMatchObject({
+ published: true, prNumber: 42, merged: false, queuedMerge: true, deferredMerge: true,
+ });
+ expect(deps.writeFile).not.toHaveBeenCalled();
+ expect(deps.addWorktree).not.toHaveBeenCalled();
+ expect(deps.git.mergePR).not.toHaveBeenCalled();
+});
+
+it('leaves a GitLab MR open (no immediate or auto-merge) and retries it once the claim releases', async () => {
+ const lease = await startClaim();
+ const deferred = makeDeps({ glab: true });
+ expect(await publishAppQualitySnapshot(app, deferred)).toMatchObject({
+ published: true, prNumber: 7, merged: false, queuedMerge: false, deferredMerge: true,
+ });
+ expect(deferred.execGlab).not.toHaveBeenCalled();
+ expect(deferred.queuePendingMerge).not.toHaveBeenCalled();
+
+ await claimMergeAdmission({ agentId: 'parent', action: 'release', token: lease.token, outcome: 'merged' });
+ // Same measurements, MR already on the stable branch: the unchanged body must
+ // not be skipped as 'no-changes' just because the earlier merge was deferred.
+ const retry = makeDeps({ glab: true, onBranch: true });
+ expect(await publishAppQualitySnapshot(app, retry)).toMatchObject({ published: true, prNumber: 7, merged: true });
+ expect(retry.execGlab).toHaveBeenCalledTimes(1);
+ expect(retry.execGlab).toHaveBeenCalledWith(
+ ['mr', 'merge', '7', '--yes', '--when-pipeline-succeeds=false'], '/repos/example-app', undefined, { rejectOnError: true },
+ );
+ expect(retry.writeFile).not.toHaveBeenCalled();
+});
+
+it('fails closed without touching another owner when ownership is unreadable or the repository is unknown', async () => {
+ // Unreadable ownership: an agent record that is not a plain object.
+ admissionState.state.mergeAdmissions['github.com/example/app'] = 'corrupt';
+ const unreadable = makeDeps();
+ expect(await publishAppQualitySnapshot(app, unreadable)).toMatchObject({ published: true, merged: false, deferredMerge: true });
+ expect(unreadable.git.mergePR).not.toHaveBeenCalled();
+ expect(admissionState.state.mergeAdmissions['github.com/example/app']).toBe('corrupt');
+
+ admissionState.state.mergeAdmissions = {};
+ const unknownRepo = makeDeps();
+ expect(await publishAppQualitySnapshot({ ...app, repoPath: '/repos/unreadable' }, unknownRepo))
+ .toMatchObject({ published: true, merged: false, deferredMerge: true });
+ expect(unknownRepo.git.mergePR).not.toHaveBeenCalled();
+
+ __resetQualitySnapshotPublishState();
+ admissionState.saveFails = true;
+ const writeFails = makeDeps();
+ expect(await publishAppQualitySnapshot(app, writeFails)).toMatchObject({ published: true, merged: false, deferredMerge: true });
+ expect(writeFails.git.mergePR).not.toHaveBeenCalled();
+ expect(admissionState.state.mergeAdmissions).toEqual({});
+});
+
+it('releases its own lease after a merge and after a refused merge, and never blocks another repository', async () => {
+ const merged = makeDeps();
+ expect(await publishAppQualitySnapshot(app, merged)).toMatchObject({ merged: true, queuedMerge: false });
+ expect(merged.git.mergePR).toHaveBeenCalledTimes(1);
+ expect(admissionState.state.mergeAdmissions).toEqual({});
+
+ __resetQualitySnapshotPublishState();
+ const refused = makeDeps({ mergeFails: true });
+ expect(await publishAppQualitySnapshot(app, refused)).toMatchObject({ merged: false, queuedMerge: true });
+ expect(refused.queuePendingMerge).toHaveBeenCalledTimes(1);
+ expect(admissionState.state.mergeAdmissions).toEqual({});
+
+ // A claim on one repository does not defer a different repository's snapshot.
+ await startClaim();
+ const other = makeDeps();
+ expect(await publishAppQualitySnapshot({ id: 'other-id', repoPath: '/repos/other-app' }, other))
+ .toMatchObject({ merged: true });
+ expect(other.git.mergePR).toHaveBeenCalledTimes(1);
+});
diff --git a/server/services/appQualitySnapshotFile.js b/server/services/appQualitySnapshotFile.js
index da7e0fe3a3..2d95daea30 100644
--- a/server/services/appQualitySnapshotFile.js
+++ b/server/services/appQualitySnapshotFile.js
@@ -16,7 +16,11 @@
* receive the file. The snapshot is numeric data only and cannot affect tests,
* so there is no reason to wait for CI; when branch protection still refuses
* the immediate merge the publisher falls back to the merge-on-green queue.
- * Reads never write. A v1 file or historical
+ * The immediate merge is the one step that advances the default branch, so it
+ * runs under this install's repository merge admission (`cosMergeAdmission.js`)
+ * like every other final merge: while a claim holds the lease the PR is left
+ * open and handed to the local pending-merge queue, which takes admission at
+ * its own later attempt. Reads never write. A v1 file or historical
* `quality-snapshot.json` is explicit legacy input.
*/
import { basename, join } from 'node:path';
@@ -295,7 +299,7 @@ async function landOrReuse(app, git, defaultBranch, deps, next, count, options =
if (!next) return skipped(app, 'invalid-evidence');
if (sameSnapshot(onBranch, next) && legacyOnBranch.status === 'absent') {
const reused = await reuseOpenSnapshotPr(app, git, defaultBranch, deps);
- if (reused.published) lastPublishedBody.set(app.repoPath, next);
+ if (reused.published) rememberPublished(app, next, reused);
return reused;
}
let result;
@@ -330,10 +334,18 @@ async function landOrReuse(app, git, defaultBranch, deps, next, count, options =
...options, leaseRetry: true,
});
}
- lastPublishedBody.set(app.repoPath, next);
+ rememberPublished(app, next, result);
return result;
}
+// A merge deferred by admission with nothing queued to land it (GitLab) must
+// stay retryable: remembering the body would turn the next unchanged cycle
+// into a 'no-changes' skip and strand the open PR.
+function rememberPublished(app, body, result) {
+ if (result.deferredMerge === true && result.queuedMerge !== true) return;
+ lastPublishedBody.set(app.repoPath, body);
+}
+
async function reuseOpenSnapshotPr(app, git, defaultBranch, deps) {
const probe = deps.probePrForBranch
|| (await import('./prProbe.js')).probePrForBranch;
@@ -347,7 +359,7 @@ async function reuseOpenSnapshotPr(app, git, defaultBranch, deps) {
return {
published: true, hash: null, path: APP_QUALITY_SNAPSHOT_FILENAME,
prUrl: found.prUrl, prNumber: found.prNumber,
- merged: outcome.merged === true, queuedMerge: outcome.queued === true,
+ ...mergeOutcomeFields(outcome),
};
}
return landExistingBranchPr(app, git, defaultBranch, deps);
@@ -363,7 +375,7 @@ async function landExistingBranchPr(app, git, defaultBranch, deps) {
return {
published: true, hash: null, path: APP_QUALITY_SNAPSHOT_FILENAME,
prUrl: created.url, prNumber: created.number,
- merged: outcome.merged === true, queuedMerge: outcome.queued === true,
+ ...mergeOutcomeFields(outcome),
};
}
@@ -414,7 +426,7 @@ async function landSnapshotPr(app, { body, count, defaultBranch, git, deps, mess
return {
published: true, hash, path: APP_QUALITY_SNAPSHOT_FILENAME,
prUrl: pr.url, prNumber: pr.number,
- merged: queued.merged === true, queuedMerge: queued.queued === true,
+ ...mergeOutcomeFields(queued),
};
};
@@ -505,21 +517,54 @@ function decoratePr(git, created) {
};
}
+const mergeOutcomeFields = outcome => ({
+ merged: outcome.merged === true,
+ queuedMerge: outcome.queued === true,
+ ...(outcome.deferred === true ? { deferredMerge: true } : {}),
+});
+
/**
* Merge a quality snapshot PR immediately: the change is numeric data only and
* cannot affect tests, so there is no reason to wait for CI. When branch
* protection still refuses the immediate merge, fall back to the merge-on-green
* queue (GitHub) or pipeline auto-merge (GitLab) so the PR still lands.
*
- * @returns {{merged: boolean, queued: boolean}} — exactly one is true on success.
+ * The immediate attempt needs this install's repository merge admission. When
+ * another owner holds it (or ownership cannot be verified) the merge is
+ * deferred: GitHub hands the PR to the local pending-merge queue, which takes
+ * admission at its own later attempt; GitLab's only queue is the forge's
+ * auto-merge, which cannot honor a local lease, so the MR stays open for the
+ * next publish cycle instead.
+ *
+ * @returns {{merged: boolean, queued: boolean, deferred?: boolean}} — merged
+ * and queued are never both true.
*/
async function mergeSnapshotPr(app, pr, deps, git) {
if (!pr?.url || !pr?.number) return { merged: false, queued: false };
- if (await tryImmediateMerge(app, pr, deps, git)) return { merged: true, queued: false };
+ const attempt = await withSnapshotMergeAdmission(app, deps, () => tryImmediateMerge(app, pr, deps, git));
+ if (attempt.deferred) {
+ const queued = pr.cli === 'glab' ? false : await queueMergeWhenGreenFallback(app, pr, deps);
+ return { merged: false, queued: queued === true, deferred: true };
+ }
+ if (attempt.result) return { merged: true, queued: false };
const queued = await queueMergeWhenGreenFallback(app, pr, deps);
return { merged: false, queued: queued === true };
}
+async function withSnapshotMergeAdmission(app, deps, work) {
+ const readOrigin = deps.getOriginInfo || (await import('../lib/gitRemote.js')).getOriginInfo;
+ const withAdmission = deps.withMergeAdmission
+ || (await import('./cosMergeAdmission.js')).withPendingMergeAdmission;
+ const origin = await readOrigin(app.repoPath).catch(() => null);
+ const admitted = await withAdmission(origin, work)
+ .catch(err => ({ admitted: false, reason: err?.message || 'admission-error' }));
+ if (admitted.admitted !== true) {
+ console.warn(`⏳ Quality snapshot merge deferred for app ${app.id}: ${admitted.reason || 'admission refused'}`);
+ return { deferred: true };
+ }
+ return { deferred: false, result: admitted.result === true };
+}
+
async function tryImmediateMerge(app, pr, deps, git) {
if (pr.cli === 'glab') {
const execGlab = deps.execGlab || (await import('./gitlab.js')).execGlab;
diff --git a/server/services/appQualitySnapshotFile.test.js b/server/services/appQualitySnapshotFile.test.js
index 8049ae036e..4b3764057f 100644
--- a/server/services/appQualitySnapshotFile.test.js
+++ b/server/services/appQualitySnapshotFile.test.js
@@ -52,6 +52,9 @@ const testDeps = (overrides = {}) => ({
rm: vi.fn(async () => {}),
addWorktree: vi.fn(async () => true),
queuePendingMerge: vi.fn(async () => true),
+ // Admission itself is pinned in appQualitySnapshotAdmission.test.js.
+ getOriginInfo: vi.fn(async () => ({ host: 'github.com', fullName: 'example/app' })),
+ withMergeAdmission: vi.fn(async (_origin, work) => ({ admitted: true, result: await work() })),
probePrForBranch: vi.fn(async () => ({ prState: null, prUrl: null, prNumber: null, readable: true })),
...overrides,
});