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

14.5 KB
Raw Blame
/**
 * Claim-branch ownership outside the run that holds it (#10089).
 *
 * A claim run cuts its own `claim/…` checkout, so its registered workspace stays
 * the source repository and nothing on disk names the owner. Two calls close
 * that gap:
 *   - `updateClaimOwnership` — the claim run binds the concrete branch it is
 *     about to check out (an epic's child, a split slice, a picked issue), or
 *     releases one it hands off before it ends. The run's completion releases
 *     everything; nothing here infers inactivity.
 *   - `checkReconcileOwnership` — a branch-reconcile worker re-reads the live
 *     owners immediately before it edits, rebases, pushes, merges, moves or
 *     removes a checkout, because ownership can be acquired after the scan that
 *     dispatched it. Anything unreadable or changed refuses. When the caller
 *     names its agent, a successful check also RESERVES the branch on that run's
 *     record under the binding lock, so a claim run cannot bind or adopt it
 *     while the worker mutates it; the run's completion releases it.
 */
import { resolve } from 'path';
import { bindClaimBranch, releaseClaimBranch, reserveReconcileBranch, reconcileAssignedTarget, reconcileMergeTarget, claimCheckoutOwnerReason } from '../lib/claimContinuation.js';

import { withClaimOwnershipLock, readClaimOwnershipAgents, checkoutRetirementFenceReason } from './cosClaimOwnershipState.js';

const normalize = (p) => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
const samePath = (a, b) => typeof a === 'string' && typeof b === 'string' && normalize(a) === normalize(b);
const branchOf = (wt) => String(wt?.branch || '').replace(/^refs\/heads\//, '');

export { withClaimOwnershipLock, readClaimOwnershipAgents, checkoutRetirementFenceReason, reserveCheckoutRetirementFence, retireWithUnlockedArchive } from './cosClaimOwnershipState.js';

// Match merge admission's pre-start budget, across BOTH queues. A deadline is
// cancellation only until the state callback starts; afterwards it diagnoses
// pending work while both locks stay owned through real settlement.
export const CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS = 15_000;
const retryAfterMs = 5000;

async function ownershipTransaction(operation, done, work) {
  const { withStateLock, loadState, saveState } = await import('./cosState.js');
  const queuedAt = performance.now();
  let started = false;
  let cancelled = false;
  let phase = 'ownershipQueue';
  let phaseStartedAt = queuedAt;
  const timings = { ownershipQueue: 0, stateQueue: 0, ownerRead: 0, ownershipCheck: 0, persistence: 0 };
  const elapsed = since => Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.round(performance.now() - since)));
  const finishPhase = () => { timings[phase] = elapsed(phaseStartedAt); };
  const enter = name => { finishPhase(); phase = name; phaseStartedAt = performance.now(); };
  const report = status => {
    // A queue-timeout or pending report means the lock was held past its budget, which only happens
    // during the event-loop stalls #12852 reopens on — an anomaly, so it stays on stderr; settled is routine.
    const log = status === 'failed' ? console.error : status === 'settled' ? console.log : console.warn;
    log(`🔒 Claim ownership operation=${operation} status=${status} phase=${phase} phaseMs=${elapsed(phaseStartedAt)} totalMs=${elapsed(queuedAt)} ownershipQueueMs=${timings.ownershipQueue} stateQueueMs=${timings.stateQueue} ownerReadMs=${timings.ownerRead} ownershipCheckMs=${timings.ownershipCheck} persistenceMs=${timings.persistence}`);
  };
  const refuse = reason => ({ [done]: false, reason });
  return new Promise((resolve, reject) => {
    const expire = () => {
      cancelled = true;
      finishPhase();
      report('queue-timeout');
      resolve({ ...refuse(phase === 'ownershipQueue' ? 'ownership-queue-timeout' : 'state-queue-timeout'), retryAfterMs });
    };
    const fenced = () => {
      if (cancelled) return true;
      // A busy event loop can resume the queue before its overdue timer fires.
      if (performance.now() - queuedAt >= CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS) { expire(); return true; }
      return false;
    };
    const timer = setTimeout(() => {
      if (!started) expire();
      else report('pending');
    }, CLAIM_OWNERSHIP_QUEUE_TIMEOUT_MS);
    const queued = withClaimOwnershipLock(() => {
      if (fenced()) return;
      enter('stateQueue');
      return withStateLock(async () => {
        if (fenced()) return;
        started = true;
        enter('ownerRead');
        const agents = await readClaimOwnershipAgents();
        if (!agents) return refuse('ownership-unreadable');
        const state = await loadState();
        if (JSON.stringify(Object.values(state.agents ?? {})) !== JSON.stringify(agents)) return refuse('ownership-stale');
        // Do not alter loadState's shared pre-image before persistence starts.
        const next = { ...state, agents: { ...state.agents } };
        enter('ownershipCheck');
        return work(next, async () => {
          enter('persistence');
          await saveState(next);
        });
      });
    });
    queued.then(result => {
      if (!cancelled) { finishPhase(); report('settled'); resolve(result); }
    }, error => {
      if (!cancelled) { finishPhase(); report('failed'); reject(error); }
    }).finally(() => clearTimeout(timer));
  });
}

/**
 * @param {{ agentId: string, action: 'bind'|'release', branch: string }} input
 * @returns {Promise<{ bound: true, branch: string }|{ released: true, branch: string }|{ bound?: false, released?: false, reason: string }>}
 */
export async function updateClaimOwnership({ agentId, action, branch }) {
  const done = action === 'bind' ? 'bound' : 'released';
  const { cosEvents } = await import('./cosEvents.js');
  return ownershipTransaction(action === 'bind' ? 'bind' : 'release', done, async (state, save) => {
    const agent = state.agents?.[agentId];
    if (!agent || agent.id !== agentId) return { [done]: false, reason: 'owner-unknown' };
    const repoPath = agent.sourceWorkspace || agent.metadata?.sourceWorkspace || agent.workspacePath || agent.metadata?.workspacePath;
    if (!repoPath) return { [done]: false, reason: 'ownership-unreadable' };
    // Binding a checkout that is mid-archive would hand it to a run that the
    // retirement then removes; releasing a branch never needs the fence.
    const fenced = action === 'bind' && checkoutRetirementFenceReason({ repoPath, branch });
    if (fenced) return { [done]: false, reason: fenced };
    const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
    return withCheckoutPublication(repoPath, async () => {
      const patch = action === 'bind' ? bindClaimBranch(agent, branch, Object.values(state.agents)) : releaseClaimBranch(agent, branch);
      if (patch.refused) return { [done]: false, reason: patch.refused };
      const updated = { ...agent, metadata: { ...agent.metadata, ...patch } };
      if (action === 'bind') {
        const { captureCheckoutSeeds } = await import('./completedCheckoutEvidence.js');
        try { updated.metadata.checkoutSeeds = await captureCheckoutSeeds(updated); }
        catch { return { [done]: false, reason: 'checkout-seed-unavailable' }; }
      }
      state.agents[agentId] = updated;
      await save();
      cosEvents.emit('agent:updated', state.agents[agentId]);
      return { [done]: true, branch };
    }).catch(error => {
      if (error.code === 'CHECKOUT_RETIREMENT_RESERVED') return { [done]: false, reason: 'checkout-retirement-reserved' };
      throw error;
    });
  });
}

/**
 * Whether a branch-reconcile worker may mutate `branch` right now. Admits only
 * when the checkout it was dispatched at still holds the branch and no live
 * owner (agent, lock, or registered/possible claim run) holds it.
 *
 * With `agentId` the admission is also an acquire: under the same lock `bind`
 * takes, the branch is recorded on that coordinator's run record, so every other
 * caller (claim `bind`, continuation, adoption, a later reconcile scan) sees a
 * live owner until the run ends or releases it. Without `agentId` the answer is
 * read-only. A named run that is not a live registered agent is refused: the
 * reservation could not be recorded.
 *
 * @param {{ appId: string, branch: string, prUrl?: string, worktreePath?: string, agentId?: string }} input
 * @param {object} [deps] - injected for tests
 * @returns {Promise<{ admitted: true }|{ admitted: false, reason: string }>}
 */
export async function checkReconcileOwnership(input, deps = {}) {
  const { appId, branch, prUrl, worktreePath, agentId } = input;
  const getAppById = deps.getAppById ?? (await import('./apps.js')).getAppById;
  const listWorktrees = deps.listWorktrees ?? (await import('./worktreeManager.js')).listWorktrees;
  const getAgents = deps.getAgents ?? readClaimOwnershipAgents;
  const readCompletionHold = deps.readCompletionHold ?? (await import('./branchCompletionPolicy.js')).readBranchCompletionHold;
  const getActiveAgentIds = deps.getActiveAgentIds ?? (await import('./agentState.js')).getActiveAgentIds;
  const { buildActiveOwnerIds, resolveLiveOwnerReason } = await import('./branchReconcile.js');

  const app = await getAppById(appId).catch(() => null);
  const repoPath = app?.repoPath;
  if (!repoPath) return { admitted: false, reason: 'app-unknown' };
  // The git read stays outside the lock; only the agent registry — the half a
  // concurrent bind changes — is re-read where the reservation is decided.
  const worktrees = await listWorktrees(repoPath).catch(() => null);
  const holder = Array.isArray(worktrees) ? worktrees.find(wt => branchOf(wt) === branch) || null : null;

  const admit = async () => {
    const agents = await getAgents().catch(() => null);
    if (!Array.isArray(worktrees) || !Array.isArray(agents)) return { admitted: false, reason: 'ownership-unreadable' };
    const completionHold = await readCompletionHold({ repoPath, branch, prUrl }).catch(() => 'pr-completion-policy-unavailable');
    if (completionHold) return { admitted: false, reason: completionHold };
    if (worktreePath && !samePath(holder?.path, worktreePath)) return { admitted: false, reason: 'holder-changed' };
    const fenced = checkoutRetirementFenceReason({ repoPath, branch, path: holder?.path || null });
    if (fenced) return { admitted: false, reason: fenced };
    const others = agentId ? agents.filter((a) => a?.id !== agentId) : agents;
    const reason = resolveLiveOwnerReason({
      branch, path: holder?.path || null, locked: Boolean(holder?.locked),
      activeAgentIds: buildActiveOwnerIds(new Set(getActiveAgentIds().filter((id) => id !== agentId)), others),
    }) || claimCheckoutOwnerReason({ branchName: branch, holderPath: holder?.path || null, sourceWorkspace: repoPath, agents: others });
    return reason ? { admitted: false, reason } : { admitted: true };
  };
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  if (!agentId || deps.reserve === false) return withCheckoutPublication(repoPath, admit)
    .catch(() => ({ admitted: false, reason: 'checkout-retirement-reserved' }));

  const { cosEvents } = await import('./cosEvents.js');
  // Decided inside the lock a bind takes, so no bind can land between
  // "admitted" and "reserved".
  return ownershipTransaction('reserve', 'admitted', async (state, save) => withCheckoutPublication(repoPath, async () => {
    const admission = await admit();
    if (!admission.admitted) return admission;
    const agent = state.agents?.[agentId];
    if (!agent || agent.id !== agentId) return { admitted: false, reason: 'owner-unknown' };
    let reservation = null;
    if (agent.metadata?.reconcileAssignment) {
      const { getTaskById } = await import('./cosTaskStore.js');
      const task = await getTaskById(agent.taskId).catch(() => null);
      const proof = reconcileAssignedTarget(agent, task, { branch, workspacePath: holder?.path || null }, { bindCheckout: true });
      const { getOriginInfo } = await import('../lib/gitRemote.js');
      const origin = await getOriginInfo(repoPath).catch(() => null);
      if (!proof || proof.assignment.appId !== appId || !samePath(proof.assignment.repoPath, repoPath)
        || origin?.host !== proof.assignment.origin.host || origin?.fullName !== proof.assignment.origin.fullName) {
        return { admitted: false, reason: 'reconcile-target-unverified' };
      }
      const reconcileReservations = [...(agent.metadata.reconcileReservations || []).filter(target => target.branch !== branch),
        { branch, workspacePath: proof.target.workspacePath }];
      const reservedAgent = { ...agent, metadata: { ...agent.metadata, reconcileReservations } };
      reservation = { reconcileReservations,
        reconcileMergeReservation: reconcileMergeTarget(reservedAgent, task, proof.target)?.target || null };
    }
    const patch = { ...reserveReconcileBranch(agent, branch), ...reservation };
    if (!Object.keys(patch).length) return admission;
    if (patch.refused) return { admitted: false, reason: patch.refused };
    state.agents[agentId] = { ...agent, metadata: { ...agent.metadata, ...patch } };
    await save();
    cosEvents.emit('agent:updated', state.agents[agentId]);
    return admission;
  }).catch(() => ({ admitted: false, reason: 'checkout-retirement-reserved' })));
}

/** Read-only snapshot publication gate. Registered review work remains owned
 * even between checkouts; neither an absent process nor a missing tree releases
 * it. The safety reader must not default corrupt runtime state to an empty list.
 */
export async function checkSnapshotPublicationOwnership({ appId, branch, prUrl }, deps = {}) {
  const readAgents = deps.readAgentsStateForSafetyCheck
    || (await import('./cosState.js')).readAgentsStateForSafetyCheck;
  const snapshot = await readAgents().catch(() => null);
  if (snapshot?.trusted !== true || !snapshot.agents || typeof snapshot.agents !== 'object' || Array.isArray(snapshot.agents)) {
    return { admitted: false, reason: 'ownership-unreadable' };
  }
  const entries = Object.entries(snapshot.agents);
  if (entries.some(([id, agent]) => !agent || agent.id !== id || !['running', 'paused', 'completed'].includes(agent.status))) {
    return { admitted: false, reason: 'ownership-unreadable' };
  }
  const agents = entries.map(([, agent]) => agent);
  if (prUrl && agents.some(agent => agent.status !== 'completed'
    && agent.metadata?.reviewLoopMergeTarget?.url === prUrl
    && agent.metadata.reviewLoopMergeTarget.branch === branch)) {
    return { admitted: false, reason: 'review-owner-active' };
  }
  return checkReconcileOwnership({ appId, branch, prUrl }, { ...deps, getAgents: async () => agents });
}