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(cos): fence outside proofs without blocking forge waits (#13385)

[._.]/ Adam Eivy7283ec9074f6
diff --git a/docs/AGENT_API_KEY.md b/docs/AGENT_API_KEY.md
index 39bc153cd0..d3b4564dc6 100644
--- a/docs/AGENT_API_KEY.md
+++ b/docs/AGENT_API_KEY.md
@@ -81,7 +81,7 @@ leases, not a forge-side fence against a merge already in flight at expiry.
Before acquiring, finish all configured reviews, required CI for the exact PR
head, and this repository's combined-tree structural guards **outside** the
-lease. Keep the checked head and base SHAs. The worktree-private
+lease. Keep the checked head and base SHAs and the base branch name. The worktree-private
`portos-review-status` file must name that exact `REVIEW_HEAD` and the workflow's
`REVIEW_STATUS=clean`, or `optional-inconclusive` when all configured reviewers
are optional and unavailable. The latter records an attempted head, never a
@@ -97,6 +97,7 @@ Write the acquisition request to a private JSON file (mode `0600`). For example:
"worktreePath": "/example/repository-worktree",
"prUrl": "https://github.com/example/repo/pull/7",
"headSha": "1111111111111111111111111111111111111111",
+ "baseBranch": "main",
"baseSha": "2222222222222222222222222222222222222222"
}
```
@@ -108,7 +109,7 @@ node <portos-root>/scripts/portos-api.js post /api/cos/merge-admission/external
The app must already exist in the local app registry. The server verifies its
origin and the checkout's real Git common directory, separate linked checkout,
branch, identity, local review receipt, live same-repository open PR, head and
-base. An active/uncertain CoS owner, checkout lock, retirement fence, changed
+base branch/SHA. An active/uncertain CoS owner, checkout lock, retirement fence, changed
proof or unreadable state withholds admission. Fork PRs and detached/primary
checkouts are outside this bounded flow. Repository keys are shared with CoS
parents and the pending-merge sweep, so all three contend on the same lease;
diff --git a/server/routes/cosAgentRoutes.js b/server/routes/cosAgentRoutes.js
index 04daa96300..6071c4db62 100644
--- a/server/routes/cosAgentRoutes.js
+++ b/server/routes/cosAgentRoutes.js
@@ -46,6 +46,7 @@ const externalMergeAdmissionSchema = z.discriminatedUnion('action', [
z.object({
action: z.literal('acquire'), appId: z.string().min(1).max(200),
worktreePath: z.string().min(1).max(4096), prUrl: z.string().url().max(2048),
+ baseBranch: z.string().min(1).max(255),
headSha: z.string().regex(/^[a-f0-9]{40}$/), baseSha: z.string().regex(/^[a-f0-9]{40}$/),
}).strict(),
z.object({ action: z.literal('check'), token: z.string().uuid() }).strict(),
diff --git a/server/routes/cosExternalMergeAdmission.test.js b/server/routes/cosExternalMergeAdmission.test.js
index 00e53e128c..1a024443a0 100644
--- a/server/routes/cosExternalMergeAdmission.test.js
+++ b/server/routes/cosExternalMergeAdmission.test.js
@@ -23,7 +23,7 @@ vi.mock('../services/cosState.js', () => ({
}));
vi.mock('../services/apps.js', () => ({ getAppById: async id => fixture.apps[id] ?? null }));
vi.mock('../services/github.js', () => ({ execGh: async args => {
- await fixture.beforeForge?.();
+ await fixture.beforeForge?.(args[args.indexOf('--repo') + 1]);
return JSON.stringify(fixture.prs[args[args.indexOf('--repo') + 1]] ?? null);
} }));
vi.mock('../services/forgeExecOptions.js', () => ({ resolveForgeExecOptions: async cwd => ({ cwd, env: {} }) }));
@@ -64,7 +64,7 @@ async function makeRepository(name) {
await git(repoPath, 'worktree', 'add', '-b', 'feature', worktreePath);
const headSha = await git(worktreePath, 'rev-parse', 'HEAD');
const reviewFile = await git(worktreePath, 'rev-parse', '--path-format=absolute', '--git-path', 'portos-review-status');
- const input = { appId: name, worktreePath, prUrl: `https://github.com/example/${name}/pull/7`, headSha, baseSha: headSha };
+ const input = { appId: name, worktreePath, prUrl: `https://github.com/example/${name}/pull/7`, headSha, baseSha: headSha, baseBranch: 'main' };
return { repoPath, worktreePath, reviewFile, input, key: `github.com/example/${name}` };
}
@@ -153,11 +153,12 @@ describe('outside merge admission through the authenticated HTTP boundary', () =
});
});
- it.each(['head', 'base', 'repository', 'review', 'owner', 'checkout'])('withholds check when the %s proof changes and retains owned release', async mode => {
+ it.each(['head', 'base', 'base-branch', 'repository', 'review', 'owner', 'checkout'])('withholds check when the %s proof changes and retains owned release', async mode => {
const { body: granted } = await acquire();
expect(granted.admitted).toBe(true);
if (mode === 'head') fixture.prs[example.key].headRefOid = 'f'.repeat(40);
if (mode === 'base') fixture.prs[example.key].baseRefOid = 'f'.repeat(40);
+ if (mode === 'base-branch') fixture.prs[example.key].baseRefName = 'release';
if (mode === 'repository') fixture.apps.repo.repoPath = other.repoPath;
if (mode === 'review') await writeFile(example.reviewFile, `REVIEW_STATUS=clean\nREVIEW_HEAD=${'f'.repeat(40)}\n`);
if (mode === 'checkout') fixture.state.mergeAdmissions[example.key].target.checkoutIdentity = 'different-checkout';
@@ -167,6 +168,36 @@ describe('outside merge admission through the authenticated HTTP boundary', () =
expect((await release(granted.token)).body.released).toBe(true);
});
+ it('keeps forge waits outside the state queue and rejects intervening same-repository ownership', async () => {
+ const { claimMergeAdmission } = await import('../services/cosMergeAdmission.js');
+ fixture.state.agents.parent = { id: 'parent', taskId: 'task-parent', startedAt: '2026-01-01T00:00:00Z', status: 'running',
+ metadata: { sourceWorkspace: example.repoPath, claimPicksOwnBranch: true, claimBranches: ['claim/issue-99'] } };
+ persist();
+ let entered, resume;
+ const started = new Promise(resolve => { entered = resolve; });
+ const paused = new Promise(resolve => { resume = resolve; });
+ fixture.beforeForge = async repository => { if (repository === example.key) { entered(); await paused; } };
+ const pending = acquire().then(response => response);
+ await started;
+ try {
+ // These must settle while the outside network proof is still paused.
+ expect((await acquire(other)).body.admitted).toBe(true);
+ const cos = await claimMergeAdmission({ agentId: 'parent', action: 'acquire' });
+ expect(cos.admitted).toBe(true);
+ const busy = await acquire(example, { session: sessionB });
+ expect(busy.body).toMatchObject({ admitted: false, reason: 'owner-active-or-unverified' });
+ expect((await claimMergeAdmission({ agentId: 'parent', action: 'release', token: cos.token, outcome: 'leave-open' })).released).toBe(true);
+ } finally { resume(); }
+ expect((await pending).body).toMatchObject({ admitted: false, reason: 'lease-target-changed' });
+ expect(fixture.state.mergeAdmissions[example.key]).toBeUndefined();
+ });
+
+ it('rechecks local review evidence after the forge request returns', async () => {
+ fixture.beforeForge = () => writeFile(example.reviewFile, `REVIEW_STATUS=blocked\nREVIEW_HEAD=${example.input.headSha}\n`);
+ expect((await acquire()).body).toMatchObject({ admitted: false, reason: 'review-evidence-incomplete' });
+ expect(fixture.state.mergeAdmissions).toEqual({});
+ });
+
it('recovers an interrupted owner only after the bounded deadline and invalidates its token', async () => {
const { body: first } = await acquire();
expect((await acquire(example, { session: sessionB })).body.admitted).toBe(false);
diff --git a/server/services/cosMergeAdmission.js b/server/services/cosMergeAdmission.js
index fcddd05fb4..e1ebfcb789 100644
--- a/server/services/cosMergeAdmission.js
+++ b/server/services/cosMergeAdmission.js
@@ -27,6 +27,14 @@ const MERGE_ADMISSION_HISTORY_LIMIT = 25;
const MERGE_HANDOFF_RECEIPT_LIMIT = 25;
const serverOwner = randomUUID();
const sweepTokens = new Set();
+// Detect a same-repository acquire/release ABA while an outside forge proof is
+// in flight. A restart ends those in-flight requests, so revisions stay local.
+const repositoryRevisions = new Map();
+const revision = repository => repositoryRevisions.get(repository) ?? 0;
+async function saveLeaseState(state, save, repository) {
+ await save(state);
+ repositoryRevisions.set(repository, revision(repository) + 1);
+}
const refuse = (reason) => ({ admitted: false, reason, retryAfterMs });
export const repositoryKey = (origin) => origin?.host && origin?.fullName
? `${origin.host.replace(/^ssh\.github\.com$/i, 'github.com')}/${origin.fullName}`.toLowerCase()
@@ -37,7 +45,7 @@ const binding = (agent) => ({ agentId: agent.id, startedAt: agent.startedAt, tas
const sameAgent = (lease, agent) => agent?.id === lease.agentId && agent?.startedAt === lease.startedAt
&& agent?.taskId === lease.taskId;
const validExternalMergeTarget = (target) => isPlainObject(target)
- && ['appId', 'repoPath', 'worktreePath', 'gitDir', 'commonDir', 'checkoutIdentity', 'branch', 'prUrl'].every(key =>
+ && ['appId', 'repoPath', 'worktreePath', 'gitDir', 'commonDir', 'checkoutIdentity', 'branch', 'prUrl', 'baseBranch'].every(key =>
typeof target[key] === 'string' && target[key].length > 0)
&& /^[a-f0-9]{40}$/.test(target.headSha || '') && /^[a-f0-9]{40}$/.test(target.baseSha || '');
const validLease = (lease, repository) => isPlainObject(lease) && lease.repository === repository
@@ -182,7 +190,7 @@ async function admit(state, save, repository, owner, measure) {
const lease = { ...owner, repository, token: randomUUID(), acquiredAt: new Date().toISOString() };
state.mergeAdmissions[repository] = lease;
if (owner.kind === 'sweep') sweepTokens.add(lease.token);
- await save(state);
+ await saveLeaseState(state, save, repository);
return { admitted: true, token: lease.token, repository };
}
@@ -476,22 +484,20 @@ export async function claimMergeAdmission({ agentId, action, token, outcome }) {
lastMergeAdmission: released,
mergeAdmissionHistory: [...history, released].slice(-MERGE_ADMISSION_HISTORY_LIMIT),
} };
- await save(state);
+ await saveLeaseState(state, save, repository);
return { admitted: false, released: true, outcome };
}, ['acquire', 'check', 'release'].includes(action) ? action : 'unknown');
}
/** A verified operator session owns only the target validated by the server. */
export async function externalMergeAdmission(input, resolveOwner) {
- return transaction(async (state, save, measure) => {
+ const { action, token, outcome } = input;
+ const operation = ['acquire', 'check', 'release'].includes(action) ? `external-${action}` : 'unknown';
+ const validMap = state => Object.entries(state.mergeAdmissions).every(([key, held]) => validLease(held, key));
+ const prepared = await transaction(async (state, save, measure) => {
const externalOwner = await resolveOwner();
if (!/^[a-f0-9]{64}$/.test(externalOwner || '')) return refuse('external-owner-unverified');
- // Validate the whole map before looking up an opaque handle: corruption is
- // never evidence that a competing owner disappeared.
- if (Object.entries(state.mergeAdmissions).some(([key, held]) => !validLease(held, key))) {
- return refuse('lease-unreadable');
- }
- const { action, token, outcome } = input;
+ if (!validMap(state)) return refuse('lease-unreadable');
const owned = Object.values(state.mergeAdmissions).find(held => held.kind === 'external'
&& held.externalOwner === externalOwner && held.token === token);
if (action !== 'acquire' && !owned) return refuse('lease-owner-mismatch');
@@ -499,30 +505,53 @@ export async function externalMergeAdmission(input, resolveOwner) {
if (action === 'release') {
if (!MERGE_ADMISSION_OUTCOMES.includes(outcome)) return refuse('outcome-required');
delete state.mergeAdmissions[owned.repository];
- await save(state);
+ await saveLeaseState(state, save, owned.repository);
return { admitted: false, released: true, outcome };
}
if (action !== 'acquire' && action !== 'check') return refuse('action-invalid');
if (owned && expired(owned)) return refuse('lease-expired');
- const { inspectExternalMergeTarget } = await import('./externalMergeTarget.js');
- const proof = await measure('origin', () => inspectExternalMergeTarget(
- action === 'acquire' ? input : owned.target, Object.values(state.agents)));
- if (proof.reason) return refuse(proof.reason);
- if (await resolveOwner() !== externalOwner) return refuse('external-owner-changed');
- if (owned && expired(owned)) return refuse('lease-expired');
+ const requested = action === 'acquire' ? input : owned.target;
+ const pr = parsePullRequestUrl(requested.prUrl);
+ const repository = pr && repositoryKey({ host: pr.host, fullName: `${pr.owner}/${pr.repo}` });
+ if (!repository) return refuse('repository-unreadable');
+ const held = state.mergeAdmissions[repository];
+ // Busy repositories do no forge work. The final transaction repeats this
+ // decision after proof, including a revision fence for intervening holders.
+ if (held && !(held.kind === 'external' && held.externalOwner === externalOwner && !expired(held))
+ && !await measure('ownerRecovery', () => inactive(held, state))) return refuse('owner-active-or-unverified');
+ return { requested, repository, externalOwner, revision: revision(repository), agents: Object.values(state.agents) };
+ }, operation);
+ if (!prepared.requested) return prepared;
+ const { inspectExternalMergeTarget, inspectExternalMergeCheckout } = await import('./externalMergeTarget.js');
+ const proof = await inspectExternalMergeTarget(prepared.requested, prepared.agents);
+ if (proof.reason) return refuse(proof.reason);
+ const provedAt = clock.now();
+ return transaction(async (state, save, measure) => {
+ if (await resolveOwner() !== prepared.externalOwner) return refuse('external-owner-changed');
+ if (!validMap(state)) return refuse('lease-unreadable');
const { repository, target } = proof;
- if (owned && (repository !== owned.repository || JSON.stringify(target) !== JSON.stringify(owned.target))) {
- return refuse('lease-target-changed');
- }
- if (action === 'check') return { admitted: true, token, repository, headSha: target.headSha, baseSha: target.baseSha };
+ if (repository !== prepared.repository || revision(repository) !== prepared.revision) return refuse('lease-target-changed');
const held = state.mergeAdmissions[repository];
- if (held?.kind === 'external' && held.externalOwner === externalOwner && !expired(held)) {
+ if (action === 'check' && (held?.kind !== 'external' || held.externalOwner !== prepared.externalOwner || held.token !== token)) {
+ return refuse('lease-owner-mismatch');
+ }
+ if (action === 'check' && expired(held)) return refuse('lease-expired');
+ // Revalidate local registration, review and live CoS ownership after the
+ // network await. Neither a revoked credential nor a replaced checkout may
+ // spend the earlier proof; a queued proof also has a bounded lifetime.
+ const current = await measure('origin', () => inspectExternalMergeCheckout(target, Object.values(state.agents)));
+ if (current.reason) return refuse(current.reason);
+ if (JSON.stringify(current.target) !== JSON.stringify(target)) return refuse('lease-target-changed');
+ if (await resolveOwner() !== prepared.externalOwner) return refuse('external-owner-changed');
+ if (clock.now() - provedAt >= ADMISSION_QUEUE_TIMEOUT_MS) return refuse('external-proof-expired');
+ if (held?.kind === 'external' && held.externalOwner === prepared.externalOwner && !expired(held)) {
if (JSON.stringify(held.target) !== JSON.stringify(target)) return refuse('lease-target-changed');
- return { admitted: true, token: held.token, repository, headSha: target.headSha, baseSha: target.baseSha };
+ return { admitted: true, token: held.token, repository, headSha: target.headSha, baseSha: target.baseSha, baseBranch: target.baseBranch };
}
- const admission = await admit(state, save, repository, { kind: 'external', externalOwner, target }, measure);
- return admission.admitted ? { ...admission, headSha: target.headSha, baseSha: target.baseSha } : admission;
- }, ['acquire', 'check', 'release'].includes(input.action) ? `external-${input.action}` : 'unknown');
+ if (action === 'check') return refuse('lease-expired');
+ const admission = await admit(state, save, repository, { kind: 'external', externalOwner: prepared.externalOwner, target }, measure);
+ return admission.admitted ? { ...admission, headSha: target.headSha, baseSha: target.baseSha, baseBranch: target.baseBranch } : admission;
+ }, operation);
}
/** A sweep holds admission only around its final read/assessment/merge attempt. */
@@ -541,7 +570,7 @@ export async function withPendingMergeAdmission(origin, work) {
const lease = state.mergeAdmissions[repository];
if (!validLease(lease, repository) || lease.token !== admission.token) return refuse('lease-owner-mismatch');
delete state.mergeAdmissions[repository];
- await save(state);
+ await saveLeaseState(state, save, repository);
return { released: true };
}, 'sweep-release');
if (!released.released) console.error(`❌ Pending merge admission release withheld: ${released.reason}`);
diff --git a/server/services/externalMergeTarget.js b/server/services/externalMergeTarget.js
index 64986d1ce2..e8f3b00fd5 100644
--- a/server/services/externalMergeTarget.js
+++ b/server/services/externalMergeTarget.js
@@ -12,7 +12,7 @@ const refused = reason => ({ reason });
const canonical = path => typeof path === 'string' && isAbsolute(path) ? realpath(path).catch(() => null) : null;
const gitValue = async (path, args) => (await execGit(args, path, { timeout: 10000 }).catch(() => null))?.stdout?.trim();
-export async function inspectExternalMergeTarget(input, agents) {
+export async function inspectExternalMergeCheckout(input, agents) {
const [{ getAppById }, { repositoryKey }] = await Promise.all([import('./apps.js'), import('./cosMergeAdmission.js')]);
const app = await getAppById(input.appId).catch(() => null);
const [repoPath, worktreePath] = await Promise.all([canonical(app?.repoPath), canonical(input.worktreePath)]);
@@ -70,6 +70,20 @@ export async function inspectExternalMergeTarget(input, agents) {
if (review.head !== head || !['clean', 'optional-inconclusive'].includes(review.status)) {
return refused('review-evidence-incomplete');
}
+ return { repository, target: { appId: app.id, repoPath, worktreePath, gitDir, commonDir,
+ checkoutIdentity: `${identity.dev}:${identity.ino}`, branch, prUrl: input.prUrl,
+ headSha: head, baseSha: input.baseSha, baseBranch: input.baseBranch } };
+}
+
+// Network and credential probes must never occupy the shared CoS state queue.
+export async function inspectExternalMergeTarget(input, agents) {
+ const proof = await inspectExternalMergeCheckout(input, agents);
+ if (proof.reason) return proof;
+ const { repository, target } = proof;
+ const { repoPath, branch, headSha: head } = target;
+ const [{ getAppById }, { repositoryKey }] = await Promise.all([import('./apps.js'), import('./cosMergeAdmission.js')]);
+ const app = await getAppById(input.appId);
+ const pr = parsePullRequestUrl(input.prUrl);
const [{ execGh }, { resolveForgeExecOptions }] = await Promise.all([import('./github.js'), import('./forgeExecOptions.js')]);
const options = await resolveForgeExecOptions(repoPath, { forgeAccount: app.forgeAccount });
const raw = await execGh(['pr', 'view', String(pr.number), '--repo', `${pr.host}/${pr.owner}/${pr.repo}`,
@@ -80,9 +94,8 @@ export async function inspectExternalMergeTarget(input, agents) {
if (!actual || repositoryKey({ host: actual.host, fullName: `${actual.owner}/${actual.repo}` }) !== repository
|| actual.number !== pr.number || live.number !== pr.number || live.state !== 'OPEN'
|| live.isDraft !== false || live.isCrossRepository !== false || live.headRefName !== branch
- || live.headRefOid !== head || live.baseRefOid !== input.baseSha || !live.baseRefName || live.baseRefName === branch) {
+ || live.headRefOid !== head || live.baseRefOid !== input.baseSha || live.baseRefName !== input.baseBranch || live.baseRefName === branch) {
return refused('external-pr-changed');
}
- return { repository, target: { appId: app.id, repoPath, worktreePath, gitDir, commonDir,
- checkoutIdentity: `${identity.dev}:${identity.ino}`, branch, prUrl: live.url, headSha: head, baseSha: live.baseRefOid } };
+ return { repository, target: { ...target, prUrl: live.url } };
}