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
/**
* Repository-wide merge-instant admission for participating runs on this install.
* Sync, pregate, push and CI run outside the lease; it spans only the final
* verify-and-merge, so holds take seconds (#10803).
*/
import { resolveTaskTargetBranch, resolveTaskRemoteBranch } from '../lib/taskTargetBranch.js';
import { randomUUID } from 'node:crypto';
import { getOriginInfo } from '../lib/gitRemote.js';
import { isPlainObject } from '../lib/objects.js';
import { parsePullRequestUrl } from '../lib/gitForge.js';
import { isTruthyMeta } from '../lib/metadataFlags.js';
import { PR_COMPLETIONS, leavesPrForHuman, resolvePrCompletion } from '../lib/prDisposition.js';
import { repositoryCleanupMergeTarget } from '../lib/recoveryMergeTarget.js';
import { createEventLoopLagProbe, formatLoadAttribution, phaseGroup, roundMs, systemClock } from '../lib/eventLoopLagProbe.js';
const retryAfterMs = 5000;
export const ADMISSION_QUEUE_TIMEOUT_MS = 15_000;
// An agent lease covers only verify-and-merge. Past this deadline it is
// reclaimable even from a running owner: that holder's pinned merge
// (--match-head-commit) cannot land an unverified head, so the worst case is
// one redundant resync rather than a repository blocked behind a hung parent.
// This is not a forge-side fence: a merge request already in flight at the
// deadline may still land, with the same exposure as two CLEAN merges.
export const AGENT_LEASE_MAX_HOLD_MS = 5 * 60 * 1000;
export const MERGE_ADMISSION_OUTCOMES = ['merged', 'leave-open', 'resync'];
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()
: null;
const ownerPath = (agent) => agent?.metadata?.sourceWorkspace || agent?.sourceWorkspace
|| agent?.metadata?.workspacePath || agent?.workspacePath;
const binding = (agent) => ({ agentId: agent.id, startedAt: agent.startedAt, taskId: agent.taskId });
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', '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
&& typeof lease.token === 'string' && lease.token.length > 0 && Number.isFinite(Date.parse(lease.acquiredAt))
&& (lease.kind === 'agent'
? typeof lease.agentId === 'string' && typeof lease.startedAt === 'string' && typeof lease.taskId === 'string'
: lease.kind === 'external' ? /^[a-f0-9]{64}$/.test(lease.externalOwner || '') && validExternalMergeTarget(lease.target)
: lease.kind === 'sweep' && typeof lease.serverOwner === 'string' && Number.isInteger(lease.pid) && lease.pid > 0);
const expired = (lease) => ['agent', 'external'].includes(lease.kind) && Date.now() - Date.parse(lease.acquiredAt) >= AGENT_LEASE_MAX_HOLD_MS;
// A settled transaction is logged only at or above this duration; a deadline,
// pending or failed one always is. See docs/TROUBLESHOOTING.md for the fields.
export const SLOW_ADMISSION_MS = 1000;
let clock = systemClock;
let lagProbe = createEventLoopLagProbe({ clock });
/** Inject a deterministic clock and optional resource counters; `null` restores the system ones. */
export function __setMergeAdmissionClockForTests(next, resources) {
clock = next ?? systemClock;
lagProbe = createEventLoopLagProbe({ clock, resources });
}
const REPORTED_PHASES = ['queue', 'trustedState', 'stateLoad', 'origin', 'ownerRecovery', 'persistence'];
const REPORTED_STAGES = [['trustedState', 'read'], ['trustedState', 'parse'], ['persistence', 'prepare'],
['persistence', 'agents'], ['persistence', 'serialize'], ['persistence', 'write'], ['persistence', 'replace'], ['persistence', 'dirSync']];
const REPORTED_LAG_PHASES = ['queue', 'trustedState', 'persistence'];
// Per record, not per serialized map: the stored rows come back in insertion
// order, which a map that deleted and re-added an id does not keep.
function sameAgentRecords(cached, stored) {
const ids = Object.keys(cached ?? {});
return isPlainObject(cached) && ids.length === Object.keys(stored).length
&& ids.every((id) => Object.hasOwn(stored, id) && JSON.stringify(cached[id]) === JSON.stringify(stored[id]));
}
async function transaction(work, operation) {
// Lazy: almost every task-generator suite reaches prWatcher, even when no
// pending merge exists. Admission needs runtime state only on the merge path.
const { withStateLock, readMergeAdmissionStateForSafetyCheck, loadState, saveState } = await import('./cosState.js');
const queuedAt = clock.now();
// Each phase runs until the next begins; `phase.stage` names are its stages.
const span = lagProbe.begin('queue');
let started = false;
let cancelled = false;
let timerLateMs = 0;
// Only fixed operation/phase names and bounded numeric timings reach logs.
const report = (status) => {
const summary = status === 'pending' ? span.snapshot() : span.end();
if (status === 'settled' && summary.totalMs < SLOW_ADMISSION_MS) return;
// Same contract as claim ownership: a queue-timeout or pending report only appears during the
// event-loop stalls #12852 reopens on, so it stays on stderr; a slow settle is telemetry.
const log = status === 'failed' ? console.error : status === 'settled' ? console.log : console.warn;
const phases = REPORTED_PHASES.map((name) => `${name}Ms=${phaseGroup(summary, name).ms}`);
const stages = REPORTED_STAGES.map(([name, stage]) => `${stage}Ms=${summary.phases[`${name}.${stage}`]?.ms ?? 0}`);
const lag = REPORTED_LAG_PHASES.map((name) => `${name}LagMs=${phaseGroup(summary, name).lagMs}`);
log(`🚦 Merge admission operation=${operation} status=${status} phase=${summary.phase.split('.')[0]} phaseMs=${summary.phaseMs} totalMs=${summary.totalMs} ${phases.join(' ')} ${stages.join(' ')} loopLagMs=${summary.lagMs} loopLagMaxMs=${summary.lagMaxMs} ${lag.join(' ')} timerLateMs=${timerLateMs}${formatLoadAttribution(summary.load)}`);
};
const measure = async (name, fn) => {
span.mark(name);
return fn();
};
const stage = (name) => (sub) => span.mark(`${name}.${sub}`);
const overdue = () => roundMs(clock.now() - queuedAt - ADMISSION_QUEUE_TIMEOUT_MS);
return new Promise((resolve, reject) => {
const expire = () => {
cancelled = true;
report('queue-timeout');
resolve(refuse('state-queue-timeout'));
};
// A late timer is itself evidence of event-loop delay: record by how much.
const timer = clock.setTimer(() => {
timerLateMs = overdue();
if (!started) expire();
else report('pending');
}, ADMISSION_QUEUE_TIMEOUT_MS);
const queued = withStateLock(async () => {
// Check the clock as well: a delayed timer must not let an expired
// callback mutate a lease when the state queue resumes first.
if (cancelled) return;
if (clock.now() - queuedAt >= ADMISSION_QUEUE_TIMEOUT_MS) { timerLateMs = overdue(); expire(); return; }
started = true;
const snapshot = await measure('trustedState', () =>
readMergeAdmissionStateForSafetyCheck({ onStage: stage('trustedState') }).catch(() => null));
if (!snapshot?.trusted || !isPlainObject(snapshot.agents) || !isPlainObject(snapshot.mergeAdmissions)) {
return refuse('ownership-unreadable');
}
const state = await measure('stateLoad', loadState);
// A recovered/defaulted or externally replaced state is not proof of an
// empty ownership set. Do not let the cache overwrite contradictory disk.
if (!sameAgentRecords(state.agents, snapshot.agents)
|| JSON.stringify(state.mergeAdmissions ?? {}) !== JSON.stringify(snapshot.mergeAdmissions)) {
return refuse('ownership-stale');
}
// Copy before mutation: a failed atomic write must not admit from a cache
// that falsely remembers a successful grant/release.
const next = { ...state, agents: { ...state.agents }, mergeAdmissions: { ...snapshot.mergeAdmissions } };
return work(next, (value) => measure('persistence', () => saveState(value, { onStage: stage('persistence') })), measure);
});
// Once started, the queue owns the entire transaction through durable
// settlement. The deadline diagnoses a slow phase but cannot return a
// refusal while an unfenced acquire/release is still able to commit.
queued.then((result) => {
if (!cancelled) { report('settled'); resolve(result); }
}, (error) => {
if (!cancelled) { report('failed'); reject(error); }
}).finally(() => clock.clearTimer(timer));
});
}
async function inactive(lease, state) {
if (lease.kind === 'sweep') {
if (lease.serverOwner === serverOwner) return !sweepTokens.has(lease.token);
// Never expire on age: the sweep holds only its own bounded merge attempt.
// A different server incarnation is recoverable only once its process is
// proven absent.
try { process.kill(lease.pid, 0); return false; }
catch (err) { return err.code === 'ESRCH'; }
}
if (expired(lease)) return true;
// Outside sessions have no CoS lifecycle record. Only the same bounded hold
// deadline can recover an interrupted session, including across restarts.
if (lease.kind === 'external') return false;
let owner = state.agents[lease.agentId];
if (!owner) {
const { readAgentRecordOrUnreadable } = await import('./cosAgentLifecycle.js');
owner = await readAgentRecordOrUnreadable(lease.agentId);
}
return sameAgent(lease, owner) && owner.status === 'completed' && Number.isFinite(Date.parse(owner.completedAt));
}
async function admit(state, save, repository, owner, measure) {
const held = state.mergeAdmissions[repository];
if (Object.hasOwn(state.mergeAdmissions, repository)) {
if (!validLease(held, repository)) return refuse('lease-unreadable');
// Re-entry keeps a live token; an expired one is voided and re-minted below.
if (owner.kind === 'agent' && held.kind === 'agent' && held.agentId === owner.agentId && held.startedAt === owner.startedAt
&& held.taskId === owner.taskId && !expired(held)) {
return { admitted: true, token: held.token, repository };
}
if (!await measure('ownerRecovery', () => inactive(held, state))) return refuse('owner-active-or-unverified');
}
const lease = { ...owner, repository, token: randomUUID(), acquiredAt: new Date().toISOString() };
state.mergeAdmissions[repository] = lease;
if (owner.kind === 'sweep') sweepTokens.add(lease.token);
await saveLeaseState(state, save, repository);
return { admitted: true, token: lease.token, repository };
}
const TERMINAL_TASK_STATUSES = ['completed', 'failed', 'cancelled'];
// The persisted task this live agent runs, or null once it is absent or final.
async function liveTask(agent) {
const { getTaskById } = await import('./cosTaskStore.js');
const task = await getTaskById(agent.taskId).catch(() => null);
return task?.id === agent.taskId && !TERMINAL_TASK_STATUSES.includes(task.status) ? task : null;
}
// The registered checkout must still name this repository and have the
// assigned branch checked out; an unreadable checkout is not a match.
async function checkoutOnBranch(workspace, branch, repository) {
if (repositoryKey(await getOriginInfo(workspace).catch(() => null)) !== repository) return false;
const { execGit } = await import('../lib/execGit.js');
const checkout = await execGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], workspace).catch(() => null);
return checkout?.stdout?.trim() === branch;
}
// Review-loop authority comes from the registered launch AND its live internal
// task. Never accept a repository/branch from the admission request or PR prose.
async function verifiedReviewCoordinator(agent, repository) {
const target = agent.metadata?.reviewLoopMergeTarget;
if (!isPlainObject(target) || typeof target.branch !== 'string' || !target.branch) return false;
const task = await liveTask(agent);
const meta = task?.metadata;
if (!task || task.taskType !== 'internal'
|| !isTruthyMeta(meta?.reviewLoopFollowUp) || isTruthyMeta(meta?.reviewLoopLeaveOpen)
|| resolvePrCompletion(meta) === PR_COMPLETIONS.LEAVE_OPEN || agent.metadata?.prCompletionPolicy === PR_COMPLETIONS.LEAVE_OPEN
|| target.url !== meta?.reviewLoopPRUrl || target.branch !== meta?.reviewLoopPRBranch
|| resolveTaskRemoteBranch(meta) !== target.branch
|| agent.metadata?.worktreeBranch !== resolveTaskTargetBranch(meta) || !agent.metadata?.workspacePath) return false;
const pr = parsePullRequestUrl(target.url);
if (!pr || repositoryKey({ host: pr.host, fullName: `${pr.owner}/${pr.repo}` }) !== repository
|| String(meta.reviewLoopPRNumber) !== String(pr.number)
|| meta.reviewLoopPRHost !== pr.host || meta.reviewLoopPROwner !== pr.owner || meta.reviewLoopPRRepo !== pr.repo) return false;
if (target.detached) {
if (meta.forkHead || meta.reviewLoopForkTarget || target.fork || agent.metadata.isWorktree !== true
|| repositoryKey(await getOriginInfo(agent.metadata.workspacePath).catch(() => null)) !== repository) return false;
const { verifyDetachedReviewMergeTarget } = await import('./detachedReviewMergeTarget.js');
const headSha = await verifyDetachedReviewMergeTarget({ target,
workspacePath: agent.metadata.workspacePath, sourceWorkspace: agent.metadata.sourceWorkspace });
return headSha ? { headSha } : false;
}
if (!await checkoutOnBranch(agent.metadata.workspacePath, resolveTaskTargetBranch(meta), repository)) return false;
if (!meta.forkHead && !meta.reviewLoopForkTarget && !target.fork && !target.workspacePath) return true;
if (target.workspacePath !== agent.metadata.workspacePath || !agent.metadata.sourceWorkspace
|| agent.metadata.sourceWorkspace === target.workspacePath || target.fork?.url !== target.url) return false;
const { verifyForkReviewMergeTarget } = await import('./forkReviewMergeTarget.js');
const headSha = await verifyForkReviewMergeTarget({ target: target.fork, taskTarget: meta.reviewLoopForkTarget,
forkHead: meta.forkHead, sourceWorkspace: agent.metadata.sourceWorkspace,
workspacePath: target.workspacePath, branch: target.branch, localBranch: agent.metadata.worktreeBranch });
return headSha ? { headSha } : false;
}
// Generic PR delivery (#11435): an operator-configured task whose prompt told
// it to open AND merge its own PR from the worktree PortOS provisioned. The
// target is the spawn-time binding (that worktree and its head branch), never
// the request; the live task must still grant agent-owned delivery, and the
// checkout must still be that branch of this repository. A generic run cannot
// promote itself to claim authority: it admits only its own registered branch.
async function verifiedWorktreeDelivery(agent, repository) {
const meta = agent.metadata;
const target = meta?.prDeliveryTarget;
if (!isPlainObject(target) || typeof target.branch !== 'string' || !target.branch
|| typeof target.workspacePath !== 'string' || !target.workspacePath) return false;
const { PR_OPENED_BY } = await import('../lib/slashdoInvocation.js');
if (meta.isWorktree !== true || meta.configOpenPR !== true || meta.configClaimFlow
|| ![PR_OPENED_BY.AGENT_SLASHDO, PR_OPENED_BY.AGENT_INLINE].includes(meta.prOpenedBy)
|| meta.prCompletionPolicy === PR_COMPLETIONS.LEAVE_OPEN
|| meta.worktreeBranch !== target.branch || meta.workspacePath !== target.workspacePath
|| !meta.sourceWorkspace || meta.sourceWorkspace === target.workspacePath) return false;
const task = await liveTask(agent);
const taskMeta = task?.metadata;
if (!task || !isTruthyMeta(taskMeta?.openPR) || resolvePrCompletion(taskMeta) === PR_COMPLETIONS.LEAVE_OPEN
|| leavesPrForHuman(task) || isTruthyMeta(taskMeta?.reviewLoopFollowUp) || isTruthyMeta(taskMeta?.readOnly)
|| taskMeta?.forkHead) return false;
return checkoutOnBranch(target.workspacePath, target.branch, repository);
}
const isCleanupRecovery = (agent) => agent.metadata?.isRecovery === true
&& agent.metadata?.recoveryOrigin?.subsystem === 'repository-cleanup';
// Repository-cleanup recovery (#12251): lands the PR of the completed parent
// whose audit filed it. Its registered target must match the live task, and
// the parent must carry the server-written backlink to this task, branch and
// PR. Needs no checkout: the parent's worktree is usually already gone.
async function verifiedCleanupRecovery(agent, repository, agents) {
const meta = agent.metadata;
const target = meta.recoveryMergeTarget;
const { parentAgentId, parentTaskId } = meta.recoveryOrigin;
if (!isPlainObject(target) || !parentTaskId || meta.prCompletionPolicy === PR_COMPLETIONS.LEAVE_OPEN) return false;
const task = await liveTask(agent);
const live = repositoryCleanupMergeTarget(task);
if (!live || live.url !== target.url || live.branch !== target.branch || leavesPrForHuman(task)
|| isTruthyMeta(task.metadata.readOnly) || task.metadata.recoveryOrigin.parentAgentId !== parentAgentId
|| task.metadata.recoveryOrigin.parentTaskId !== parentTaskId) return false;
const pr = parsePullRequestUrl(target.url);
if (repositoryKey({ host: pr.host, fullName: `${pr.owner}/${pr.repo}` }) !== repository) return false;
let parent = agents[parentAgentId];
if (!parent) {
const { readAgentRecordOrUnreadable } = await import('./cosAgentLifecycle.js');
parent = await readAgentRecordOrUnreadable(parentAgentId);
}
const link = parent?.metadata?.repoStateRecoveries?.[target.branch] || parent?.metadata?.repoStateRecovery;
const parentBranches = [parent?.metadata?.worktreeBranch,
...(Array.isArray(parent?.metadata?.claimBranches) ? parent.metadata.claimBranches : []),
...(Array.isArray(parent?.metadata?.claimReleasedBranches) ? parent.metadata.claimReleasedBranches : [])];
if (!isPlainObject(parent) || parent.id !== parentAgentId || parent.taskId !== parentTaskId || parent.status !== 'completed'
|| !parentBranches.includes(target.branch) || parent.metadata.prCompletionPolicy === PR_COMPLETIONS.LEAVE_OPEN
|| !isPlainObject(link) || link.taskId !== agent.taskId || link.url !== target.url || link.branch !== target.branch
|| !parent.metadata.sourceWorkspace) return false;
return repositoryKey(await getOriginInfo(parent.metadata.sourceWorkspace).catch(() => null)) === repository;
}
// A source-checkout coordinator owns only its scheduler-assigned targets. A
// successful ownership check selects one target; acquire/check re-read all live
// holds under the state lock, so an old reservation cannot outlive a policy or
// checkout change. No caller-supplied admission fields participate in this proof.
async function verifiedReconcileCoordinator(agent, repository, agents) {
if (!agent.metadata?.reconcileMergeReservation) return false;
const { reconcileMergeTarget } = await import('../lib/claimContinuation.js');
const task = await liveTask(agent);
const proof = reconcileMergeTarget(agent, task, agent.metadata.reconcileMergeReservation);
if (!proof || repositoryKey(proof.assignment.origin) !== repository
|| !await checkoutOnBranch(proof.target.workspacePath, proof.target.branch, repository)) return false;
const { checkReconcileOwnership } = await import('./cosClaimOwnership.js');
const admission = await checkReconcileOwnership({ agentId: agent.id, appId: proof.assignment.appId,
branch: proof.target.branch, worktreePath: proof.target.workspacePath }, {
reserve: false, getAgents: async () => Object.values(agents),
getAppById: async (appId) => {
const { getAppById } = await import('./apps.js');
const app = await getAppById(appId);
return app?.repoPath === proof.assignment.repoPath ? app : null;
},
});
return admission.admitted ? { reconcileTarget: proof.target } : false;
}
// Claim parents carry their registered claim binding; every other participant
// must prove its registered target against live task and checkout state.
async function verifiedParticipant(agent, repository, agents) {
if (isTruthyMeta(agent.metadata?.claimPicksOwnBranch) || agent.metadata?.claimBranch) return true;
if (isCleanupRecovery(agent)) return verifiedCleanupRecovery(agent, repository, agents);
return await verifiedReviewCoordinator(agent, repository) || await verifiedWorktreeDelivery(agent, repository)
|| verifiedReconcileCoordinator(agent, repository, agents);
}
/**
* The registered run a pending-merge handoff may bind (#12247): the same live
* participant proof acquire uses, plus which branch that run owns and the
* registered checkout holding it (null for a claim run, which cuts its own).
* Nothing here is taken from the request. Fork review targets are refused —
* the coordinator merges same-repository heads only.
*/
export async function resolveMergeHandoffOwner(agentId) {
const { readMergeAdmissionStateForSafetyCheck } = await import('./cosState.js');
const snapshot = await readMergeAdmissionStateForSafetyCheck().catch(() => null);
if (!snapshot?.trusted || !isPlainObject(snapshot.agents)) return { refused: 'ownership-unreadable' };
const agent = snapshot.agents[agentId];
if (!agent || agent.id !== agentId || agent.status !== 'running' || !agent.startedAt || !agent.taskId) {
return { refused: 'handoff-owner-unverified' };
}
const repository = ownerPath(agent) ? repositoryKey(await getOriginInfo(ownerPath(agent)).catch(() => null)) : null;
if (!repository) return { refused: 'repository-unreadable' };
const task = await liveTask(agent);
if (!task) return { refused: 'handoff-owner-unverified' };
const meta = agent.metadata || {};
if (meta.reviewLoopMergeTarget?.fork || task.metadata?.forkHead) return { refused: 'fork-target-unsupported' };
const owner = { agent, task, repository };
if (isTruthyMeta(meta.claimPicksOwnBranch) || meta.claimBranch) {
const { ownsClaimBranch } = await import('../lib/claimContinuation.js');
return { ...owner, owns: (branch) => ownsClaimBranch(agent, branch), workspacePath: null };
}
if (await verifiedReviewCoordinator(agent, repository)) {
return { ...owner, owns: (branch) => branch === meta.reviewLoopMergeTarget.branch, workspacePath: meta.workspacePath };
}
if (await verifiedWorktreeDelivery(agent, repository)) {
return { ...owner, owns: (branch) => branch === meta.prDeliveryTarget.branch, workspacePath: meta.prDeliveryTarget.workspacePath };
}
const reconcile = await verifiedReconcileCoordinator(agent, repository, snapshot.agents);
if (reconcile) return { ...owner, owns: branch => branch === reconcile.reconcileTarget.branch,
workspacePath: reconcile.reconcileTarget.workspacePath };
return { refused: 'handoff-owner-unverified' };
}
/**
* Record that the pending-merge coordinator was handed exactly this PR head, on
* the run that handed it off. The post-merge gate audit (#12549) reads it to
* tell the coordinator's merge from an agent merging around admission.
*
* @returns {Promise<{ recorded: true }|{ recorded?: false, reason: string }>}
*/
export async function recordMergeHandoffReceipt({ agentId, receipt }) {
return transaction(async (state, save) => {
const agent = state.agents[agentId];
if (!agent || agent.id !== agentId) return { recorded: false, reason: 'handoff-owner-unverified' };
const prior = Array.isArray(agent.metadata?.mergeHandoffReceipts) ? agent.metadata.mergeHandoffReceipts : [];
state.agents[agentId] = { ...agent, metadata: { ...agent.metadata,
mergeHandoffReceipts: [...prior, receipt].slice(-MERGE_HANDOFF_RECEIPT_LIMIT) } };
await save(state);
return { recorded: true };
}, 'handoff-receipt');
}
/**
* Record that the pending-merge coordinator itself merged the head a receipt
* names. Only the coordinator's own merge call writes this; a PR that merely
* turns up MERGED (the run merged it around the queue) leaves the receipt
* unmarked, so the post-merge gate audit still sees that merge.
*
* @returns {Promise<{ marked: true }|{ marked?: false, reason: string }>}
*/
export async function markMergeHandoffMerged({ agentId, receiptId, headSha }) {
return transaction(async (state, save) => {
const agent = state.agents[agentId];
const receipts = Array.isArray(agent?.metadata?.mergeHandoffReceipts) ? agent.metadata.mergeHandoffReceipts : [];
if (!receipts.some((receipt) => receipt?.receiptId === receiptId && receipt.headSha === headSha)) {
return { marked: false, reason: 'receipt-unknown' };
}
const coordinatorMergedAt = new Date().toISOString();
state.agents[agentId] = { ...agent, metadata: { ...agent.metadata, mergeHandoffReceipts: receipts.map((receipt) =>
(receipt?.receiptId === receiptId ? { ...receipt, coordinatorMergedAt } : receipt)) } };
await save(state);
return { marked: true };
}, 'handoff-merged');
}
/** The ID is the registered parent, never a worker-child ID or a cwd PID. */
export async function claimMergeAdmission({ agentId, action, token, outcome }) {
return transaction(async (state, save, measure) => {
const agent = state.agents[agentId];
if (!agent || agent.id !== agentId || agent.status !== 'running' || !agent.startedAt || !agent.taskId) {
return refuse('claim-owner-unverified');
}
if (!ownerPath(agent)) return refuse('repository-unreadable');
const repository = repositoryKey(await measure('origin', () => getOriginInfo(ownerPath(agent)).catch(() => null)));
if (!repository) return refuse('repository-unreadable');
// Releasing an owned token must remain possible after merge deletes or
// switches the checkout. Acquire/check still require the assigned target.
const participant = action === 'release' ? true : await measure('origin', () => verifiedParticipant(agent, repository, state.agents));
if (!participant && isCleanupRecovery(agent)) {
return { admitted: false, reason: 'recovery-merge-target-unverified', retryable: false,
message: 'Leave the PR and branch intact and report this blocker: this recovery has no verified registered parent PR target. Retrying cannot change that; only a freshly filed recovery can.' };
}
if (!participant) {
const task = await liveTask(agent);
if (agent.metadata?.reviewLoopMergeTarget?.fork || (task?.taskType === 'internal'
&& isTruthyMeta(task.metadata?.reviewLoopFollowUp) && task.metadata?.forkHead)) {
return { admitted: false, reason: 'fork-review-target-unverified', retryable: false,
message: 'Leave the PR/worktree intact. Verify the live PR head, base, fork remote and upstream; old or changed targets require a fresh supported follow-up.' };
}
if (agent.metadata?.reviewLoopMergeTarget?.detached) {
return { admitted: false, reason: 'detached-review-target-unverified', retryable: false,
message: 'Leave the PR/worktree intact. A detached review checkout must match its registered launch head and live PR; create a fresh supported follow-up for a changed target.' };
}
return refuse('claim-owner-unverified');
}
if (action === 'acquire') {
if (Object.entries(state.mergeAdmissions).some(([key, held]) =>
!validLease(held, key) || (held.agentId === agentId && (!sameAgent(held, agent) || key !== repository)))) {
return refuse('lease-owner-mismatch');
}
const held = state.mergeAdmissions[repository];
if (participant.headSha && held?.agentId === agentId && !expired(held) && held.headSha !== participant.headSha) return refuse('lease-head-changed');
if (held?.agentId === agentId && !expired(held)
&& JSON.stringify(held.reconcileTarget) !== JSON.stringify(participant.reconcileTarget)) return refuse('lease-target-changed');
return admit(state, save, repository, { kind: 'agent', ...binding(agent),
...(participant.reconcileTarget ? { reconcileTarget: participant.reconcileTarget } : {}),
...(participant.headSha ? { headSha: participant.headSha } : {}) }, measure);
}
const lease = state.mergeAdmissions[repository];
if (!validLease(lease, repository) || lease.kind !== 'agent' || !sameAgent(lease, agent) || lease.token !== token) {
return refuse('lease-owner-mismatch');
}
// An expired holder must stop and re-acquire before merging; releasing
// its own still-unclaimed lease stays permitted.
if (action === 'check' && participant.headSha && lease.headSha !== participant.headSha) return refuse('lease-head-changed');
if (action === 'check' && JSON.stringify(lease.reconcileTarget) !== JSON.stringify(participant.reconcileTarget)) return refuse('lease-target-changed');
if (action === 'check') return expired(lease) ? refuse('lease-expired') : { admitted: true, token, repository };
if (action !== 'release' || !MERGE_ADMISSION_OUTCOMES.includes(outcome)) return refuse('outcome-required');
delete state.mergeAdmissions[repository];
// The post-merge gate audit (#12549) asks whether a lease was held at the
// instant a PR merged, so the interval outlives the lease. Bounded: a swarm
// parent cycles one lease per child PR.
const released = { repository, outcome, acquiredAt: lease.acquiredAt, releasedAt: new Date().toISOString() };
const history = Array.isArray(agent.metadata?.mergeAdmissionHistory) ? agent.metadata.mergeAdmissionHistory : [];
state.agents[agentId] = { ...agent, metadata: { ...agent.metadata,
lastMergeAdmission: released,
mergeAdmissionHistory: [...history, released].slice(-MERGE_ADMISSION_HISTORY_LIMIT),
} };
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) {
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');
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');
// Release remains possible after a merge or a changed/deleted checkout.
if (action === 'release') {
if (!MERGE_ADMISSION_OUTCOMES.includes(outcome)) return refuse('outcome-required');
delete state.mergeAdmissions[owned.repository];
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 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 (repository !== prepared.repository || revision(repository) !== prepared.revision) return refuse('lease-target-changed');
const held = state.mergeAdmissions[repository];
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, baseBranch: target.baseBranch };
}
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. */
export async function withPendingMergeAdmission(origin, work) {
const repository = repositoryKey(origin);
if (!repository) return refuse('repository-unreadable');
const admission = await transaction((state, save, measure) => admit(state, save, repository, {
kind: 'sweep', serverOwner, pid: process.pid,
}, measure), 'sweep-acquire');
if (!admission.admitted) return admission;
try {
return { admitted: true, result: await work() };
} finally {
try {
const released = await transaction(async (state, save) => {
const lease = state.mergeAdmissions[repository];
if (!validLease(lease, repository) || lease.token !== admission.token) return refuse('lease-owner-mismatch');
delete state.mergeAdmissions[repository];
await saveLeaseState(state, save, repository);
return { released: true };
}, 'sweep-release');
if (!released.released) console.error(`❌ Pending merge admission release withheld: ${released.reason}`);
} finally {
// The callback has stopped even if persistence failed. Keep the durable
// lease on disk; the next trusted transaction can prove this owner idle.
sweepTokens.delete(admission.token);
}
}
}