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): 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.md
index 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 merged
PR at the exact head. A merged manual claim with no PR at its exact head (a
reused branch, or a checkout left behind while the branch shipped from
elsewhere) 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 retain
the checkout because their complete content is not supported by the archive.
A held merged receipt names a recovery task when policy and source ownership
permit it; intentional human handoffs stay with their existing owner. The recovery
diff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.js
index 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, fo
const 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, fo
number: 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, { activeAge
skipped.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 live
diff --git a/server/services/branchReconcile.test.js b/server/services/branchReconcile.test.js
index 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.js
index 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.js
index 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 }] });