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): settle branch-reconcile holds for claim checkouts left behind (#12930)
[._.]/c7db3b68f76d
diff --git a/docs/features/chief-of-staff.md b/docs/features/chief-of-staff.mdindex de6e328510..ab3bb3b57c 100644--- a/docs/features/chief-of-staff.md+++ b/docs/features/chief-of-staff.md@@ -167,7 +167,13 @@ filesystem incarnation is required, or for a manual session the forge's mergedPR at the exact head. A merged manual claim with no PR at its exact head (areused branch, or a checkout left behind while the branch shipped fromelsewhere) retires once a GitHub read finds no open PR for the branch and the-checkout's directory, index and HEAD log have been untouched for an hour. Older records cannot release a reused claim. Initialized submodules currently retain+checkout's directory, index and HEAD log have been untouched for an hour. A+merged checkout under a review obligation whose open PR head has moved past it+(the delivery continues from another checkout) is archived and retired after+the same hour idle; an open PR at the checkout's own tip stays a live delivery.+After a claim checkout retires, its issue markers are never written; a GitHub+read showing the issue closed, or open with no `in-progress` label and no+assignee, settles the reservation report, and any other answer keeps it held. Older records cannot release a reused claim. Initialized submodules currently retainthe checkout because their complete content is not supported by the archive.A held merged receipt names a recovery task when policy and source ownershippermit it; intentional human handoffs stay with their existing owner. The recoverydiff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.jsindex bb4da787f5..7c32705b79 100644--- a/server/services/branchReconcile.js+++ b/server/services/branchReconcile.js@@ -33,7 +33,7 @@ import { execGh, ensureForgeReachable, getIssueDispatchHint } from './github.js'import { resolveForgeExecOptions } from './forgeExecOptions.js';import { isForgeNoAccessError, logForgeNoAccessOnce } from '../lib/forgeAccessErrors.js';import { issueNumberFromRef } from './issueReconcile.js';-import { forgeDispatchLabels } from '../lib/dispatchLabels.js';+import { forgeDispatchLabels, IN_PROGRESS_LABEL } from '../lib/dispatchLabels.js';import { getOriginInfo } from '../lib/gitRemote.js';import { githubRepoSpec, githubApiHost } from '../lib/workTracker.js';import { safeJSONParse, PATHS } from '../lib/fileUtils.js';@@ -298,7 +298,7 @@ async function getOpenPrsByHead(repoPath, providedOrigin, { forgeExec = null, foconst raw = await execGh(['pr', 'list', '--repo', repoSpec, '--state', 'open','--limit', String(PR_LIST_LIMIT),- '--json', 'number,headRefName,mergeable,isDraft,url'+ '--json', 'number,headRefName,headRefOid,mergeable,isDraft,url'], undefined, { cwd, env, backoffKey: repoSpec }).catch((err) => {if (isForgeNoAccessError(err)) {// Permanent until credentials change — one actionable line naming the@@ -322,7 +322,8 @@ async function getOpenPrsByHead(repoPath, providedOrigin, { forgeExec = null, fonumber: pr.number,mergeable: pr.mergeable || 'UNKNOWN',isDraft: pr.isDraft === true,- url: pr.url || ''+ url: pr.url || '',+ headRefOid: typeof pr.headRefOid === 'string' ? pr.headRefOid : null});}}@@ -1099,17 +1100,35 @@ export function describeIdleReconcilePark(skipped = [], heldLive = [], { wip = [// A local checkout can be retired without owning the global issue reservation.// Peer installs share a forge login, and a peer may reserve before its first// commit/push. Neither that login nor an absent remote branch proves release-// authority. Leave issue markers untouched and report their unverified state.-async function retainedClaimMarkers(repoPath, branch, { origin } = {}) {+// authority, so markers are never written here. A read that shows no+// reservation to own (a closed issue, or an open one with no claim label and+// no assignee) settles the report; anything else stays a visible hold.+async function retainedClaimMarkers(repoPath, branch, { origin, forgeExec = null } = {}) {const issue = /^claim\/issue-([1-9]\d*)$/.exec(branch)?.[1];if (!issue) return null;const target = origin === undefined ? await getOriginInfo(repoPath).catch(() => null) : origin;if (target && !githubRepoSpec(target)) return null;+ if (await claimIssueUnreserved(target, issue, forgeExec)) {+ console.log(`⏭️ branch-reconcile: issue #${issue} has no reservation left; markers untouched`);+ return null;+ }const hold = { branch, issue: Number(issue), reason: 'claim-reservation-owner-unverified', markerState: 'unknown', ownerState: 'unknown' };console.log(`🔒 branch-reconcile: issue #${issue} markers untouched; reservation owner/state unverified`);return hold;}+/** True only on a parsed forge answer; an unreadable issue keeps the hold. */+async function claimIssueUnreserved(target, issue, forgeExec) {+ const repoSpec = githubRepoSpec(target);+ if (!repoSpec || !forgeExec) return false;+ const raw = await execGh(['issue', 'view', issue, '--repo', repoSpec, '--json', 'state,labels,assignees'],+ undefined, { cwd: forgeExec.cwd, env: forgeExec.env }).catch(() => null);+ const view = safeJSONParse(raw, null);+ if (!view || !Array.isArray(view.labels) || !Array.isArray(view.assignees)) return false;+ if (view.state === 'CLOSED') return true;+ return view.state === 'OPEN' && view.assignees.length === 0 && !view.labels.some(label => label?.name === IN_PROGRESS_LABEL);+}+/*** Deterministically clean up fully-merged branches: remove the lingering* worktree, then delete the local branch. Safety gates (ALL must hold):@@ -1158,7 +1177,7 @@ export async function cleanupMerged(repoPath, defaultBranch, merged, { activeAgeskipped.push({ branch: b.branch, ...(b.worktreePath && { path: b.worktreePath }), ...failure });continue;}- const markerHold = await retainedClaimMarkers(repoPath, b.branch, { origin });+ const markerHold = await retainedClaimMarkers(repoPath, b.branch, { origin, forgeExec });if (markerHold) claimMarkersHeld.push(markerHold);cleaned.push(b.branch);}@@ -1462,7 +1481,7 @@ async function manualClaimShippedHold(repoPath, b, head, forgeAccount) {}/** Time since the checkout last changed: its directory, index or HEAD log. Null when unreadable. */-async function checkoutIdleMs(worktreePath) {+export async function checkoutIdleMs(worktreePath) {const gitDir = (await execGit(['rev-parse', '--absolute-git-dir'], worktreePath).catch(() => null))?.stdout?.trim();if (!gitDir) return null;const stamps = await Promise.all([worktreePath, join(gitDir, 'index'), join(gitDir, 'logs', 'HEAD')]@@ -1759,22 +1778,27 @@ export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSup? await resolveForgeExecOptions(repoPath, { forgeAccount }): null;// The early reaper may have deleted the branch before gather can see it.- // Report their global reservation separately, including during forge outages.- const claimMarkersHeld = [];- for (const entry of worktreeCleanup.reaped || []) {- if (!entry?.branchDeleted) continue;- const markerHold = await retainedClaimMarkers(repoPath, entry.branch, { origin });- if (markerHold) claimMarkersHeld.push(markerHold);- }+ // Report their global reservation separately, including during forge outages+ // (no issue read then, so each stays held).+ const readEarlyMarkerHolds = async (markerForge) => {+ const holds = [];+ for (const entry of worktreeCleanup.reaped || []) {+ if (!entry?.branchDeleted) continue;+ const markerHold = await retainedClaimMarkers(repoPath, entry.branch, { origin, forgeExec: markerForge });+ if (markerHold) holds.push(markerHold);+ }+ return holds;+ };if (forgeExec) {const forge = await ensureForgeReachable('branch-reconcile', {hostname: githubApiHost(origin.host),...(forgeExec?.customEnv ? { env: forgeExec.customEnv } : {}),});if (!forge.ok) {- return { defaultBranch: null, cleaned: cleanedWorktrees, inFlight: [], wip: [], skipped: [], claimMarkersHeld, forgeUnavailable: true, forgeStatus: forge.status };+ return { defaultBranch: null, cleaned: cleanedWorktrees, inFlight: [], wip: [], skipped: [], claimMarkersHeld: await readEarlyMarkerHolds(null), forgeUnavailable: true, forgeStatus: forge.status };}}+ const claimMarkersHeld = await readEarlyMarkerHolds(forgeExec);const defaultBranch = await getDefaultBranch(repoPath).catch(() => 'main') || 'main';// The gather needs origin's branch list to tell a shipped claim from a livediff --git a/server/services/branchReconcile.test.js b/server/services/branchReconcile.test.jsindex 61cf2cef40..e780757c2b 100644--- a/server/services/branchReconcile.test.js+++ b/server/services/branchReconcile.test.js@@ -373,7 +373,24 @@ describe('unverified issue reservations in reconcile', () => {expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('markers untouched'));expect(result.cleaned).toEqual(['claim/issue-42']);expect(result.claimMarkersHeld).toEqual([{ branch: 'claim/issue-42', issue: 42, reason: 'claim-reservation-owner-unverified', markerState: 'unknown', ownerState: 'unknown' }]);- expect(execGh.mock.calls.some(([args]) => args[0] === 'issue' || args[0] === 'api')).toBe(false);+ expect(execGh.mock.calls.some(([args]) => args[0] === 'api' || (args[0] === 'issue' && args[1] !== 'view'))).toBe(false);+ });++ it.each([+ [{ state: 'CLOSED', labels: [{ name: 'in-progress' }], assignees: [] }, false],+ [{ state: 'OPEN', labels: [], assignees: [] }, false],+ [{ state: 'OPEN', labels: [{ name: 'in-progress' }], assignees: [] }, true],+ [{ state: 'OPEN', labels: [], assignees: [{ login: 'example-peer' }] }, true],+ [{ state: 'OPEN' }, true],+ ])('reads the issue to settle a reservation nobody holds: %j', async (view, held) => {+ execGh.mockImplementation(async (args) => args[0] === 'issue' ? JSON.stringify(view) : '[]');+ vi.spyOn(console, 'log').mockImplementation(() => {});+ getOriginInfo.mockResolvedValue({ hasOrigin: true, host: 'github.com', fullName: 'example/app' });+ wt.reapMergedWorktrees.mockResolvedValue({ reaped: [{ branch: 'claim/issue-42', branchDeleted: true }], skipped: [] });+ git.getBranches.mockResolvedValue([]);+ const result = await reconcile('/repo');+ expect(result.claimMarkersHeld.map(hold => hold.issue)).toEqual(held ? [42] : []);+ expect(execGh.mock.calls.filter(([args]) => args[0] === 'issue').map(([args]) => args.slice(0, 2))).toEqual([['issue', 'view']]);});it('reports unverified reservations separately even when the forge is unavailable', async () => {diff --git a/server/services/branchReconcileRetirement.js b/server/services/branchReconcileRetirement.jsindex d7f9646bd4..57ac2c4023 100644--- a/server/services/branchReconcileRetirement.js+++ b/server/services/branchReconcileRetirement.js@@ -19,9 +19,12 @@ export async function prepareReconcileRetirements(app, result, deps = {}) {const prepare = deps.prepare || (await import('./heldCheckoutRecovery.js')).prepareInventoriedCheckoutRetirement;for (const branch of result.wip || []) {if (branch.completionPolicyReason !== 'pr-completion-review-required'- || branch.openPr || branch.liveOwnerReason || branch.worktreeDirty || branch.worktreeStatusUnavailable) continue;+ || branch.liveOwnerReason || branch.worktreeDirty || branch.worktreeStatusUnavailable) continue;+ if (branch.openPr && !staleBehindOpenPr(branch)) continue;const tree = result.worktreeInventory?.find(row => row.branch === branch.branch && row.path === branch.worktreePath);if (!tree || tree.managed !== true || tree.locked !== false || tree.head !== branch.tip) continue;+ // The open PR ships from another checkout; this one has idled behind it.+ if (branch.openPr && !(await isIdleCheckout(tree.path, deps))) continue;const release = { branch: tree.branch, path: tree.path, head: tree.head, locked: false, lockReason: tree.lockReason ?? null };// Every commit is already on the default branch, so no PR identity or owner// history is needed to prove nothing is lost: archive and retire it. The@@ -69,6 +72,22 @@ export async function prepareReconcileRetirements(app, result, deps = {}) {return { candidates, held, retired };}+/** A merged local copy whose open PR head moved on was left behind by the+ * delivery: everything it holds is on the default branch, and the PR's head is+ * not this checkout's. An open PR at this tip is the live delivery itself.+ */+function staleBehindOpenPr(branch) {+ const prHead = branch.openPr?.headRefOid;+ return branch.isMerged === true && !branch.openPr.isDraft+ && typeof prHead === 'string' && /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(prHead) && prHead !== branch.tip;+}++async function isIdleCheckout(path, deps) {+ const { checkoutIdleMs, SHIPPED_CLAIM_IDLE_MS } = await import('./branchReconcile.js');+ const idle = await (deps.checkoutIdleMs || checkoutIdleMs)(path).catch(() => null);+ return Number.isFinite(idle) && idle >= SHIPPED_CLAIM_IDLE_MS;+}+/** Re-read daemon authority at each automatic mutation boundary. Manual API* callers keep their existing operator-authorized contract.*/diff --git a/server/services/branchReconcileRetirement.test.js b/server/services/branchReconcileRetirement.test.jsindex c695780f12..c2c31747fd 100644--- a/server/services/branchReconcileRetirement.test.js+++ b/server/services/branchReconcileRetirement.test.js@@ -99,6 +99,8 @@ describe('historical completed-checkout review obligations', () => {[{ liveOwnerReason: 'claim-owner-active' }, {}],[{ completionPolicyReason: 'pr-completion-human-handoff' }, {}],[{ openPr: { isDraft: true } }, {}],+ [{ openPr: { isDraft: false, headRefOid: head } }, {}],+ [{ openPr: { isDraft: false, headRefOid: null } }, {}],[{ worktreeDirty: true }, {}],[{ worktreeStatusUnavailable: true }, {}],[{}, { locked: true }], [{}, { managed: false }], [{}, { head: 'b'.repeat(40) }],@@ -112,6 +114,25 @@ describe('historical completed-checkout review obligations', () => {expect(deps.retire).not.toHaveBeenCalled();});+ it('retires a merged checkout left idle behind its open PR, and keeps one still in use', async () => {+ const deps = setup();+ deps.retire = vi.fn(async () => ({ ok: true, branchDeleted: true, archiveDir: '/private/verified-archive' }));+ const behind = { isMerged: true, openPr: { isDraft: false, headRefOid: 'c'.repeat(40) } };+ deps.checkoutIdleMs = vi.fn(async () => 2 * 60 * 60 * 1000);+ expect(await prepareReconcileRetirements(app, scan(behind), deps)).toMatchObject({ retired: [expect.objectContaining({ head })], held: [] });+ expect(deps.checkoutIdleMs).toHaveBeenCalledWith(tree.path);+ expect(deps.retire).toHaveBeenCalledWith(expect.objectContaining({ release: expect.objectContaining({ head }) }),+ { beforeMutation: expect.any(Function), settleMergedReviewObligation: true });+ deps.retire.mockClear();+ for (const idle of [5 * 60 * 1000, null]) {+ deps.checkoutIdleMs = vi.fn(async () => idle);+ expect(await prepareReconcileRetirements(app, scan(behind), deps)).toMatchObject({ candidates: [], retired: [], held: [] });+ }+ expect(await prepareReconcileRetirements(app, scan({ ...behind, isMerged: false }), deps)).toMatchObject({ candidates: [], retired: [] });+ expect(deps.retire).not.toHaveBeenCalled();+ expect(deps.prepare).not.toHaveBeenCalled();+ });+it.each(['claim-owner-active', 'retirement-local-objects-missing', 'retirement-submodule-not-uninitialized', 'retirement-policy-not-legacy-completed'])('keeps a fresh preview refusal visible: %s', async reason => {const deps = setup(); deps.prepare.mockResolvedValue({ ok: false, reason });expect(await prepareReconcileRetirements(app, scan(), deps)).toMatchObject({ candidates: [], held: [{ branch: branch.branch, reason }] });