Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix(cos): fence outside proofs without blocking forge waits (#13385)
[._.]/ Adam Eivy7283ec9074f6
diff --git a/docs/AGENT_API_KEY.md b/docs/AGENT_API_KEY.mdindex 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 PRhead, 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 reviewersare 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/externalThe app must already exist in the local app registry. The server verifies itsorigin 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, changedproof or unreadable state withholds admission. Fork PRs and detached/primarycheckouts are outside this bounded flow. Repository keys are shared with CoSparents and the pending-merge sweep, so all three contend on the same lease;diff --git a/server/routes/cosAgentRoutes.js b/server/routes/cosAgentRoutes.jsindex 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.jsindex 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.jsindex 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, tasconst 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.jsindex 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 } };}