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: validate pending PortOS merges against the live default branch (#13227)

Adam Eivyfef93b248e6a
diff --git a/server/services/pendingMergeGuard.js b/server/services/pendingMergeGuard.js
new file mode 100644
index 0000000000..358a972d5a
--- /dev/null
+++ b/server/services/pendingMergeGuard.js
@@ -0,0 +1,79 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { promisify, stripVTControlCharacters } from 'node:util';
+import { execFile } from '../lib/childProcess.js';
+import { execGit } from '../lib/execGit.js';
+
+const run = promisify(execFile);
+const SHA = /^[0-9a-f]{40}$/;
+const SCRIPT = 'scripts/pregate.js';
+const readOptional = path => readFile(path, 'utf8').catch(error => {
+ if (error.code === 'ENOENT') return null;
+ throw error;
+});
+
+// Capability, not upstream slug: forks inherit the guard, ordinary managed apps
+// and older PortOS checkouts without merged-tree support keep their behavior.
+export async function supportsPendingMergeGuard(repoPath) {
+ const source = await readOptional(resolve(repoPath, SCRIPT));
+ return source !== null && source.includes("case '--guards-only':") && source.includes("case '--merged-with':");
+}
+
+async function verifyCheckout(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 [common, primaryCommon, head, ref, status] = await Promise.all([
+ read(['rev-parse', '--path-format=absolute', '--git-common-dir']),
+ read(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoPath),
+ read(['rev-parse', '--verify', 'HEAD^{commit}']),
+ read(['symbolic-ref', '--quiet', '--short', 'HEAD']),
+ read(['status', '--porcelain=v1', '--untracked-files=all']),
+ ]);
+ return common === primaryCommon && head === headSha && ref === branch && !status;
+}
+
+/** 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;
+ const headSha = binding?.headSha;
+ if (!SHA.test(headSha || '') || prView.headRefOid !== headSha
+ || !await verifyCheckout(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' };
+ const base = await readDefault();
+ if (!base || !SHA.test(base.sha) || prView.baseRefName !== base.name) {
+ return { ok: false, reason: 'merged-tree-default-branch-unverified' };
+ }
+ // Fetch the named ref, then pin the command to the fetched object. Concurrent
+ // fetches cannot silently replace the base whose evidence we record.
+ await execGit(['fetch', '--no-tags', 'origin', `refs/heads/${base.name}`], worktreePath, { env, timeout: 60000 });
+ const fetched = (await execGit(['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], worktreePath)).stdout.trim();
+ if (fetched !== base.sha) return { ok: false, reason: 'merged-tree-base-moved' };
+ const gitPath = (await execGit(['rev-parse', '--git-path', `portos-merged-guards-${headSha}-${base.sha}.log`], worktreePath)).stdout.trim();
+ const evidence = { headSha, baseSha: base.sha, baseBranch: base.name, logPath: resolve(worktreePath, gitPath) };
+ const result = await run(process.execPath, [SCRIPT, '--guards-only', '--merged-with', base.sha], {
+ cwd: worktreePath, env: { ...process.env, PORTOS_TEST_MEMO: 'off' },
+ timeout: 15 * 60 * 1000, maxBuffer: 16 * 1024 * 1024,
+ }).then(value => ({ ...value, ok: true }), error => ({
+ ok: false, stdout: error.stdout || '', stderr: error.stderr || error.message,
+ }));
+ await writeFile(evidence.logPath, `HEAD ${headSha}\nBASE ${base.sha}\n${result.stdout}\n${result.stderr}`, { mode: 0o600 });
+ if (!result.ok) {
+ const failedTest = stripVTControlCharacters(`${result.stdout}\n${result.stderr}`).match(/\bFAIL\s+([^\r\n]+)/)?.[1];
+ return { ok: false, reason: 'merged-tree-guards-failed', evidence: { ...evidence, failedTest: failedTest || null } };
+ }
+ if (!await verifyCheckout(app.repoPath, worktreePath, entry.prBranch, headSha)) {
+ return { ok: false, reason: 'merged-tree-checkout-changed', evidence };
+ }
+ return { ok: true, evidence };
+}
+
+/** Live reads happen inside admission; stale evidence never grants a merge. */
+export async function pendingMergeGuardCurrent(evidence, prView, readDefault) {
+ if (!evidence) return true;
+ if (prView.headRefOid !== evidence.headSha || prView.baseRefName !== evidence.baseBranch) return false;
+ const base = await readDefault();
+ return base?.name === evidence.baseBranch && base.sha === evidence.baseSha;
+}
diff --git a/server/services/pendingMergeGuard.test.js b/server/services/pendingMergeGuard.test.js
new file mode 100644
index 0000000000..1d53902ccc
--- /dev/null
+++ b/server/services/pendingMergeGuard.test.js
@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execGit } from '../lib/execGit.js';
+import { preparePendingMergeGuard, pendingMergeGuardCurrent } from './pendingMergeGuard.js';
+
+const roots = [];
+afterEach(async () => {
+ await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })));
+});
+
+async function fixture({ fail = false } = {}) {
+ const root = await mkdtemp(join(tmpdir(), 'pending-merge-guard-'));
+ roots.push(root);
+ const repoPath = join(root, 'repo');
+ const remote = join(root, 'remote');
+ const worktreePath = join(root, 'claim');
+ await mkdir(repoPath);
+ const git = async (args, cwd = repoPath) => (await execGit(args, cwd)).stdout.trim();
+ await git(['init', '-b', 'main']);
+ await mkdir(join(repoPath, 'scripts'));
+ await writeFile(join(repoPath, 'scripts/pregate.js'), `
+const { execFileSync } = require('node:child_process');
+for (const arg of process.argv.slice(2)) { switch (arg) {
+ case '--guards-only': break;
+ case '--merged-with': break;
+} }
+console.log(JSON.stringify({ args: process.argv.slice(2), memo: process.env.PORTOS_TEST_MEMO }));
+// Stand in for a structural guard which is red only on the combined inputs.
+const base = execFileSync('git', ['show', process.argv[4] + ':base-contract'], { encoding: 'utf8' });
+if (base.trim() === 'strict' && ${fail}) {
+ console.error('FAIL server/routeValidationConventions.test.js > combined route inventory');
+ process.exitCode = 1;
+}
+`);
+ await writeFile(join(repoPath, 'base-contract'), 'permissive');
+ const commit = async message => {
+ await git(['add', '.']);
+ await git(['-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-m', message]);
+ return git(['rev-parse', 'HEAD']);
+ };
+ await commit('initial');
+ await git(['clone', '--bare', repoPath, remote], root);
+ await git(['remote', 'add', 'origin', remote]);
+ await git(['worktree', 'add', '-b', 'claim/issue-1', worktreePath]);
+ const headSha = await git(['rev-parse', 'HEAD'], worktreePath);
+ await writeFile(join(repoPath, 'base-contract'), 'strict');
+ const baseSha = await commit('stricter base');
+ await git(['push', 'origin', 'main']);
+ return { repoPath, worktreePath, headSha, baseSha, git,
+ input: { app: { repoPath }, entry: { prBranch: 'claim/issue-1' }, binding: { headSha, worktreePath },
+ prView: { headRefOid: headSha, baseRefName: 'main' }, readDefault: async () => ({ name: 'main', sha: baseSha }) } };
+}
+
+describe('pending merged-tree validation', () => {
+ it('fetches the live base, pins both full SHAs, and preserves the clean claim checkout', async () => {
+ const { input, git, worktreePath, headSha, baseSha } = await fixture();
+ const result = await preparePendingMergeGuard(input);
+ expect(result).toMatchObject({ ok: true, evidence: { headSha, baseSha, baseBranch: 'main' } });
+ const log = await readFile(result.evidence.logPath, 'utf8');
+ expect(log).toContain(JSON.stringify({ args: ['--guards-only', '--merged-with', baseSha], memo: 'off' }));
+ expect(await git(['rev-parse', 'HEAD'], worktreePath)).toBe(headSha);
+ expect(await git(['status', '--porcelain'], worktreePath)).toBe('');
+ expect(await pendingMergeGuardCurrent(result.evidence, input.prView, input.readDefault)).toBe(true);
+ expect(await pendingMergeGuardCurrent(result.evidence, input.prView, async () => ({ name: 'main', sha: headSha }))).toBe(false);
+ expect(await pendingMergeGuardCurrent(result.evidence, { ...input.prView, headRefOid: baseSha }, input.readDefault)).toBe(false);
+ });
+
+ it('retains the failing structural test with exact merge inputs and does not alter the claim', async () => {
+ const { input, git, worktreePath, headSha, baseSha } = await fixture({ fail: true });
+ const result = await preparePendingMergeGuard(input);
+ expect(result).toMatchObject({ ok: false, reason: 'merged-tree-guards-failed', evidence: { headSha, baseSha } });
+ expect(await readFile(result.evidence.logPath, 'utf8')).toContain('FAIL server/routeValidationConventions.test.js > combined route inventory');
+ expect(await git(['rev-parse', 'HEAD'], worktreePath)).toBe(headSha);
+ expect(await git(['status', '--porcelain'], worktreePath)).toBe('');
+ });
+
+ it('refuses a dirty or wrong-head checkout before executing its guard', async () => {
+ const { input, worktreePath, baseSha } = await fixture();
+ const wrongHead = await preparePendingMergeGuard({ ...input, binding: { ...input.binding, headSha: baseSha } });
+ expect(wrongHead).toEqual({ ok: false, reason: 'merged-tree-checkout-unverified' });
+ await writeFile(join(worktreePath, 'uncommitted'), 'preserve me');
+ expect(await preparePendingMergeGuard(input)).toEqual({ ok: false, reason: 'merged-tree-checkout-unverified' });
+ expect(await readFile(join(worktreePath, 'uncommitted'), 'utf8')).toBe('preserve me');
+ });
+
+ it('leaves an ordinary managed app without the supported command unchanged', async () => {
+ const repoPath = await mkdtemp(join(tmpdir(), 'ordinary-managed-app-'));
+ roots.push(repoPath);
+ expect(await preparePendingMergeGuard({ app: { repoPath } })).toEqual({ ok: true, evidence: null });
+ });
+});
diff --git a/server/services/prWatcher.js b/server/services/prWatcher.js
index 7f1dd2d7fb..c0ab110a88 100644
--- a/server/services/prWatcher.js
+++ b/server/services/prWatcher.js
@@ -634,7 +634,7 @@ async function describeWithheldAssessment(assessment, expectedHeadSha) {
// Runs inside merge admission. Answers the merge attempt (or owner policy) plus
// the withheld-assessment evidence the settle path records.
-async function mergeAssessedHead(entry, binding, { app, origin, repoSpec, forgeExec }) {
+async function mergeAssessedHead(entry, binding, { app, origin, repoSpec, forgeExec }, guard) {
const currentPr = await readPendingPullRequest(repoSpec, entry.prNumber, forgeExec);
if (!currentPr || !isPendingMergeReady(currentPr)) {
return { merge: { success: false, error: 'Current head is not merge-ready' }, assessed: NOT_ASSESSED };
@@ -658,6 +658,14 @@ async function mergeAssessedHead(entry, binding, { app, origin, repoSpec, forgeE
// Re-read the durable owner's policy inside admission, after remote
// assessment and immediately before merge. Waiting CI is not authority to
// ignore a later manual hold or a changed review requirement.
+ if (assessment.ok && guard) {
+ const { pendingMergeGuardCurrent } = await import('./pendingMergeGuard.js');
+ const livePr = await readPendingPullRequest(repoSpec, entry.prNumber, forgeExec);
+ if (!livePr || !isPendingMergeReady(livePr) || !await pendingMergeGuardCurrent(guard, livePr,
+ () => readPendingDefault({ origin, repoSpec, forgeExec })).catch(() => false)) {
+ return { merge: { guardDeferred: true }, assessed };
+ }
+ }
const ownerPolicy = await currentHandoffOwnerPolicy(binding);
if (ownerPolicy) return { merge: ownerPolicy, assessed };
const merge = assessment.ok
@@ -670,17 +678,43 @@ async function mergeAssessedHead(entry, binding, { app, origin, repoSpec, forgeE
// Answers `{ step }` when the entry is finished this sweep, otherwise
// `{ assessed }` for the settle path.
-async function attemptAdmittedMerge(entry, binding, ctx) {
+async function readPendingDefault({ origin, repoSpec, forgeExec }) {
+ const name = await getDefaultBranch(repoSpec, forgeExec);
+ if (!name) return null;
+ const sha = await execGh(['api', '--hostname', githubApiHost(origin.host),
+ `repos/${origin.fullName}/git/ref/heads/${encodeURIComponent(name)}`, '--jq', '.object.sha'],
+ undefined, { ...forgeExec, backoffKey: repoSpec }).catch(() => null);
+ return sha ? { name, sha: sha.trim() } : null;
+}
+
+async function attemptAdmittedMerge(entry, binding, prView, ctx) {
+ const ownerPolicy = await currentHandoffOwnerPolicy(binding);
+ if (ownerPolicy) return { step: await holdForOwner(ctx.app, entry, binding, ownerPolicy.ownerBlocked) };
+ const { preparePendingMergeGuard } = await import('./pendingMergeGuard.js');
+ const guard = await preparePendingMergeGuard({ app: ctx.app, entry, binding, prView,
+ readDefault: () => readPendingDefault(ctx), env: ctx.forgeExec.env,
+ }).catch(() => ({ ok: false, reason: 'merged-tree-validation-unavailable' }));
+ if (!guard.ok) {
+ const retained = { ...entry, mergedTreeGuard: { ...guard.evidence, reason: guard.reason }, attention: guard.reason };
+ if (guard.reason === 'merged-tree-guards-failed') {
+ retained.recoveryBlocked = guard.reason;
+ await notifyPendingMergeTimeout(ctx.app, entry, null,
+ `PR #${entry.prNumber} failed merged-tree guards${guard.evidence?.failedTest ? `: ${guard.evidence.failedTest}` : ''}. Its receipt, checkout, and mergedTreeGuard log are retained. Repair and submit a fresh verified handoff.`);
+ }
+ return { step: { outcome: retained, tally: { waiting: 1 } } };
+ }
+ const retained = guard.evidence ? { ...entry, mergedTreeGuard: guard.evidence } : entry;
const { withPendingMergeAdmission, markMergeHandoffMerged } = await import('./cosMergeAdmission.js');
- const admitted = await withPendingMergeAdmission(ctx.origin, () => mergeAssessedHead(entry, binding, ctx));
+ const admitted = await withPendingMergeAdmission(ctx.origin, () => mergeAssessedHead(entry, binding, ctx, guard.evidence));
if (!admitted.admitted) {
console.log(`⏳ Pending merge deferred for PR #${entry.prNumber}: ${admitted.reason}`);
- return { step: { outcome: entry, tally: { waiting: 1 } } };
+ return { step: { outcome: retained, tally: { waiting: 1 } } };
}
const { merge, assessed } = admitted.result;
+ if (merge.guardDeferred) return { step: { outcome: retained, tally: { waiting: 1 } } };
if (merge.ownerDeferred || merge.ownerBlocked) {
- const retained = assessed.hold ? { ...entry, assessmentWithheld: assessed.hold } : entry;
- return { step: await holdForOwner(ctx.app, entry, binding, merge.ownerBlocked, retained) };
+ const held = assessed.hold ? { ...retained, assessmentWithheld: assessed.hold } : retained;
+ return { step: await holdForOwner(ctx.app, entry, binding, merge.ownerBlocked, held) };
}
if (merge.success) {
// The post-merge gate audit (#12549) exempts only a merge made here.
@@ -701,7 +735,7 @@ async function mergeOrSettle(entry, binding, prView, ctx) {
const cachedHold = ready ? await unchangedAssessmentHold(entry, prView) : null;
let assessed = { reason: cachedHold?.reason, hold: cachedHold };
if (ready && !cachedHold) {
- const attempt = await attemptAdmittedMerge(entry, binding, ctx);
+ const attempt = await attemptAdmittedMerge(entry, binding, prView, ctx);
if (attempt.step) return attempt.step;
assessed = attempt.assessed;
}
diff --git a/server/services/prWatcher.test.js b/server/services/prWatcher.test.js
index 9607205deb..50e25aad01 100644
--- a/server/services/prWatcher.test.js
+++ b/server/services/prWatcher.test.js
@@ -39,6 +39,12 @@ vi.mock('./untrustedContent.js', () => ({
screenUntrustedContent: (...args) => screenMock(...args),
getContributionAssessmentFingerprint: (...args) => fingerprintMock(...args),
}));
+const prepareGuardMock = vi.fn();
+const guardCurrentMock = vi.fn();
+vi.mock('./pendingMergeGuard.js', () => ({
+ preparePendingMergeGuard: (...args) => prepareGuardMock(...args),
+ pendingMergeGuardCurrent: (...args) => guardCurrentMock(...args),
+}));
const mergePrMock = vi.fn();
vi.mock('./git.js', () => ({
mergePR: (...args) => mergePrMock(...args),
@@ -114,6 +120,8 @@ beforeEach(() => {
ensureForgeReachableMock.mockReset();
ensureForgeReachableMock.mockResolvedValue({ ok: true, status: 'ok', detail: null, remedy: null });
mergePrMock.mockReset();
+ prepareGuardMock.mockReset().mockResolvedValue({ ok: true, evidence: null });
+ guardCurrentMock.mockReset().mockResolvedValue(true);
addNotificationMock.mockReset();
spawnReviewLoopFollowUpMock.mockReset();
addNotificationMock.mockResolvedValue({ id: 'notification-1' });
@@ -648,6 +656,80 @@ describe('merge-only PR watcher', () => {
expect(readPendingMergePrs(mockApps.get('app1'))).toEqual([]);
});
+ describe('merged-tree guard admission', () => {
+ const guard = { headSha: 'a'.repeat(40), baseSha: 'b'.repeat(40), baseBranch: 'main', logPath: '/example/guard.log' };
+ const handoff = { headSha: guard.headSha, repository: 'github.com/o/r', agentId: 'agent-88', taskId: 'task-88',
+ receiptId: 'receipt-88', prCompletion: 'merge-on-green' };
+ const setup = () => {
+ const app = pendingApp([pendingMerge({ handoff })]);
+ mockApps.set(app.id, app);
+ tasksById.set('task-88', { id: 'task-88', status: 'completed', metadata: { prCompletion: 'merge-on-green' } });
+ const evidence = installPendingEvidence();
+ evidence.pr.baseRefName = 'main';
+ return { app, evidence };
+ };
+
+ it('retains a failing combined-tree receipt and log without taking admission or merging', async () => {
+ const { app } = setup();
+ prepareGuardMock.mockImplementation(async () => {
+ expect(admissionState.state.mergeAdmissions).toEqual({});
+ return { ok: false, reason: 'merged-tree-guards-failed', evidence: guard };
+ });
+ await processPendingMergePrs(app);
+ const kept = readPendingMergePrs(mockApps.get(app.id))[0];
+ expect(kept).toMatchObject({ handoff, ticks: 0, mergedTreeGuard: { ...guard, reason: 'merged-tree-guards-failed' },
+ recoveryBlocked: 'merged-tree-guards-failed' });
+ expect(mergePrMock).not.toHaveBeenCalled();
+ expect(admissionState.state.mergeAdmissions).toEqual({});
+ expect(spawnReviewLoopFollowUpMock).not.toHaveBeenCalled();
+ await processPendingMergePrs(mockApps.get(app.id));
+ expect(prepareGuardMock).toHaveBeenCalledTimes(1);
+ expect(addNotificationMock).toHaveBeenCalledTimes(1);
+ });
+
+ it('runs the guard outside admission and merges the unchanged reviewed head inside it', async () => {
+ const { app } = setup();
+ prepareGuardMock.mockImplementation(async () => {
+ expect(admissionState.state.mergeAdmissions).toEqual({});
+ return { ok: true, evidence: guard };
+ });
+ guardCurrentMock.mockImplementation(async () => {
+ expect(Object.keys(admissionState.state.mergeAdmissions)).toHaveLength(1);
+ return true;
+ });
+ mergePrMock.mockResolvedValue({ success: true });
+ expect(await processPendingMergePrs(app)).toMatchObject({ merged: 1 });
+ expect(guardCurrentMock).toHaveBeenCalledWith(guard, expect.objectContaining({ headRefOid: guard.headSha }), expect.any(Function));
+ expect(mergePrMock).toHaveBeenCalledWith(app.repoPath, 88, { forgeAccount: 'other-account', expectedHeadSha: guard.headSha });
+ });
+
+ it('releases admission when the checked base moves and validates again before a later merge', async () => {
+ const { app } = setup();
+ prepareGuardMock.mockResolvedValue({ ok: true, evidence: guard });
+ guardCurrentMock.mockResolvedValueOnce(false).mockResolvedValueOnce(true);
+ mergePrMock.mockResolvedValue({ success: true });
+ expect(await processPendingMergePrs(app)).toMatchObject({ merged: 0, waiting: 1 });
+ expect(mergePrMock).not.toHaveBeenCalled();
+ expect(readPendingMergePrs(mockApps.get(app.id))[0]).toMatchObject({ handoff, mergedTreeGuard: guard, ticks: 0 });
+ expect(Object.values(admissionState.state.mergeAdmissions).every(lease => lease.status !== 'active')).toBe(true);
+ expect(await processPendingMergePrs(mockApps.get(app.id))).toMatchObject({ merged: 1 });
+ expect(prepareGuardMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('never merges a head changed during guard execution and preserves the receipt for fresh recovery', async () => {
+ const { app, evidence } = setup();
+ prepareGuardMock.mockImplementation(async () => {
+ evidence.pr.headRefOid = 'c'.repeat(40);
+ return { ok: true, evidence: guard };
+ });
+ await processPendingMergePrs(app);
+ expect(mergePrMock).not.toHaveBeenCalled();
+ expect(readPendingMergePrs(mockApps.get(app.id))[0].handoff).toEqual(handoff);
+ await processPendingMergePrs(mockApps.get(app.id));
+ expect(spawnReviewLoopFollowUpMock).toHaveBeenCalledWith(expect.objectContaining({ prCompletion: 'merge-on-green' }));
+ });
+ });
+
describe('a bound handoff receipt', () => {
const boundHandoff = {
headSha: 'a'.repeat(40), repository: 'github.com/o/r', agentId: 'agent-88', taskId: 'task-88',