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: branch-reconcile now removes or reports detached-HEAD worktrees at merged commits (#10825)

Adam Eivyb7a87bd5db75
diff --git a/server/services/branchReconcile.js b/server/services/branchReconcile.js
index 904db0452a..3ab288afd5 100644
--- a/server/services/branchReconcile.js
+++ b/server/services/branchReconcile.js
@@ -1017,7 +1017,7 @@ export async function gatherBranchState(repoPath, { defaultBranch, activeAgentId
export function describeIdleReconcilePark(skipped = [], heldLive = []) {
// Only worktree-* skips are a HOLD; 'not-merged-on-recheck' and 'cleanup-disabled'
// mean the branch was never eligible, so they must not read as pending work.
- const heldBackMerged = skipped.filter((s) => s.reason?.startsWith('worktree-'));
+ const heldBackMerged = skipped.filter((s) => !s.detached && s.reason?.startsWith('worktree-'));
const lifts = heldBackMerged.map((entry) => Date.parse(entry.retryAt)).filter(Number.isFinite);
const reason = heldLive.length
? 'branches-held-by-live-owners'
@@ -1336,6 +1336,96 @@ async function retireBranchNow(repoPath, b, { activeAgentIds = new Set(), staleC
return { ok: true, prepared };
}
+/**
+ * Gather every worktree whose HEAD is detached — a tree with no branch, which
+ * `gatherBranchState` (keyed by local branch) can never see. Only trees sitting
+ * at a commit already on the default branch are returned: that is the trash this
+ * exists for, and a detached tree at unmerged commits may be someone's work.
+ * The main checkout, bare and prunable entries are never gathered.
+ *
+ * @param {string} repoPath
+ * @param {string} defaultBranch
+ * @returns {Promise<{path:string, head:string|null, locked:boolean, worktreeAgeMs:number|null, dirtyPaths:string[]}[]>}
+ */
+export async function gatherDetachedWorktrees(repoPath, defaultBranch) {
+ const worktrees = await listWorktrees(repoPath).catch(() => []);
+ const detached = [];
+ for (const [index, entry] of worktrees.entries()) {
+ // git lists the main checkout first; the path check covers a caller whose list is not ordered.
+ if (index === 0 || entry.branch || entry.bare || entry.prunable || entry.path === repoPath || !entry.head) continue;
+ if (!await isCommitOnBranch(repoPath, entry.head, defaultBranch)) continue;
+ detached.push({
+ path: entry.path,
+ head: entry.head,
+ locked: Boolean(entry.locked),
+ worktreeAgeMs: await worktreeAgeMs(entry.path),
+ dirtyPaths: await worktreeDirtyPaths(entry.path),
+ });
+ }
+ return detached;
+}
+
+const isCommitOnBranch = (repoPath, sha, branch) =>
+ execGit(['merge-base', '--is-ancestor', sha, branch], repoPath, { ignoreExitCode: true })
+ .then((r) => r?.exitCode === 0)
+ .catch(() => false);
+
+/**
+ * Retire the detached worktrees `gatherDetachedWorktrees` found, with the same
+ * gate order as `retireBranchNow` (protection → still clean → remove), minus the
+ * branch deletion a detached tree does not have.
+ *
+ * A tree outside the managed roots is REPORTED, never removed (#10270): nothing
+ * about it proves its creator is finished, so the coordinator decides. A held
+ * tree inside the roots is `skipped` with its `worktree-*` reason; both are in
+ * `held` so the park log can name them.
+ *
+ * @param {string} repoPath
+ * @param {string} defaultBranch
+ * @param {object[]} detached - `gatherDetachedWorktrees`' entries
+ * @param {{ activeAgentIds?: Set<string>, claimOwners?: { agents: object[]|null } }} [opts]
+ * @returns {Promise<{cleaned:string[], skipped:object[], held:{path:string, head:string|null, reason:string, managed:boolean, retryAt?:string}[]}>}
+ */
+export async function reapDetachedWorktrees(repoPath, defaultBranch, detached, { activeAgentIds = new Set(), claimOwners } = {}) {
+ const cleaned = [];
+ const skipped = [];
+ const held = [];
+ const roots = reconcileWorktreeRoots(repoPath);
+ const hold = (tree, reason, retryAt) => {
+ const managed = reason !== 'worktree-unmanaged-location';
+ held.push({ path: tree.path, head: tree.head, reason, managed, ...(retryAt ? { retryAt } : {}) });
+ // `detached` keeps the entry out of describeIdleReconcilePark's merged-branch count.
+ if (managed) skipped.push({ branch: tree.path, path: tree.path, detached: true, reason, ...(retryAt ? { retryAt } : {}) });
+ };
+ for (const tree of detached) {
+ if (claimOwners !== undefined && !Array.isArray(claimOwners?.agents)) {
+ hold(tree, 'claim-ownership-unreadable');
+ continue;
+ }
+ const gate = {
+ path: tree.path, locked: tree.locked, activeAgentIds, ageMs: tree.worktreeAgeMs, roots,
+ };
+ const protectedReason = worktreeProtectionReason(gate);
+ if (protectedReason) {
+ hold(tree, protectedReason, worktreeProtectionExpiresAt(gate));
+ continue;
+ }
+ if (tree.dirtyPaths.length > 0 || await isWorktreeDirty(tree.path)) {
+ hold(tree, 'worktree-dirty');
+ continue;
+ }
+ // Re-verify at action time — the HEAD may have moved since the gather.
+ if (!await isCommitOnBranch(repoPath, tree.head, defaultBranch)) continue;
+ const removal = await forceRemoveWorktreeDir(repoPath, tree.path, { label: '🔀 branch-reconcile: remove detached worktree', log: 'all' });
+ if (!removal.removed) {
+ hold(tree, 'worktree-remove-failed');
+ continue;
+ }
+ cleaned.push(tree.path);
+ }
+ return { cleaned, skipped, held };
+}
+
/**
* Full Tier-1 reconcile: gather → classify → clean up merged + verified-superseded.
* Returns the in-flight set (branches needing an agent) for the scheduler to dispatch.
@@ -1465,7 +1555,11 @@ export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSup
const { cleaned: cleanedBranches, skipped } = cleanup
? await cleanupMerged(repoPath, defaultBranch, merged, { activeAgentIds, claimOwners, origin, forgeExec, forgeAccount })
: { cleaned: [], skipped: merged.map((m) => ({ branch: m.branch, reason: 'cleanup-disabled' })) };
- const cleaned = [...new Set([...cleanedWorktrees, ...cleanedBranches])];
+ // Detached worktrees have no branch, so nothing above can see them (#10825).
+ const detachedReap = cleanup
+ ? await reapDetachedWorktrees(repoPath, defaultBranch, await gatherDetachedWorktrees(repoPath, defaultBranch), { activeAgentIds, claimOwners })
+ : { cleaned: [], skipped: [], held: [] };
+ const cleaned = [...new Set([...cleanedWorktrees, ...cleanedBranches, ...detachedReap.cleaned])];
// Runs AFTER cleanupMerged on purpose: that step deletes merged local branches
// and leaves their `origin/*` counterpart behind, which is precisely the orphan
@@ -1490,7 +1584,9 @@ export async function reconcile(repoPath = PATHS.root, { cleanup = true, reapSup
// the coordinator prompt.
superseded: supersededReap.held,
wip,
- skipped: [...skipped, ...supersededReap.skipped],
+ skipped: [...skipped, ...supersededReap.skipped, ...detachedReap.skipped],
+ // Detached trees at merged commits that were NOT removed, managed or not.
+ detachedWorktrees: detachedReap.held,
orphanRemotes,
prStateUnavailable
};
@@ -1781,7 +1877,7 @@ async function dispatchHintLineForBranch(branchName, repoPath) {
* `appId` adds each branch's pre-mutation ownership recheck command.
* @returns {Promise<string>}
*/
-export async function formatInFlightForPrompt(inFlight, { defaultBranch, actions, branchesPerAgent, repoPath, appId } = {}) {
+export async function formatInFlightForPrompt(inFlight, { defaultBranch, actions, branchesPerAgent, repoPath, appId, detachedWorktrees = [] } = {}) {
// One gh round-trip per issue-derived branch — resolved in parallel (not
// inline in the loop below) so N branches cost one round-trip's latency,
// not N of them in series.
@@ -1830,5 +1926,15 @@ export async function formatInFlightForPrompt(inFlight, { defaultBranch, actions
})}`);
lines.push('');
});
+ // Detached trees outside the managed roots are never removed by the deterministic
+ // pass; the coordinator confirms nothing is using one, then removes it.
+ const unmanaged = detachedWorktrees.filter((d) => !d.managed);
+ if (unmanaged.length) {
+ lines.push(`Detached worktrees at commits already on \`${defaultBranch}\`, outside PortOS's managed roots (${unmanaged.length}):`, '');
+ for (const d of unmanaged) {
+ lines.push(`### Detached worktree \`${d.path}\``);
+ lines.push(`- Do: confirm nothing is using \`${d.path}\` (no running process, no uncommitted work), then run \`git worktree remove ${d.path}\` yourself.`, '');
+ }
+ }
return lines.join('\n');
}
diff --git a/server/services/branchReconcile.test.js b/server/services/branchReconcile.test.js
index 8a5ed91ea1..6da1827971 100644
--- a/server/services/branchReconcile.test.js
+++ b/server/services/branchReconcile.test.js
@@ -1789,6 +1789,82 @@ describe('reconcile — cached SUPERSEDED verdicts (#3842)', () => {
// worktree holding only that read as ABANDONED_WIP forever: cleanupMerged
// refused to delete a dirty tree, and every pass instead spent a coordinator run
// that came back "no real work product, a human should discard it".
+describe('reconcile — detached-HEAD worktrees (#10825)', () => {
+ const MAIN = { path: '/repo', head: 'aaa111', branch: 'refs/heads/main' };
+ const detachedTree = (path, extra = {}) => ({ path, head: 'bbb222', detached: true, ...extra });
+ // Only the ancestry probe cares about argv; status reads clean unless a test says otherwise.
+ const stubGit = ({ merged = true, dirty = false } = {}) => execGit.mockImplementation(async (args) => {
+ if (args[0] === 'merge-base') return { stdout: '', exitCode: merged ? 0 : 1 };
+ if (args[0] === 'status') return { stdout: dirty ? ' M src/a.js\n' : '', exitCode: 0 };
+ return { stdout: '', exitCode: 0 };
+ });
+
+ beforeEach(() => {
+ git.getBranches.mockResolvedValue([]);
+ execGh.mockResolvedValue('[]');
+ });
+
+ it('removes a clean managed detached tree at a merged commit and lists it in cleaned', async () => {
+ const path = '/repo/data/cos/worktrees/agent-1234abcd';
+ wt.listWorktrees.mockResolvedValue([MAIN, detachedTree(path)]);
+ stubGit();
+ const res = await reconcile('/repo');
+ expect(res.cleaned).toContain(path);
+ expect(wt.forceRemoveWorktreeDir).toHaveBeenCalledWith('/repo', path, expect.any(Object));
+ expect(res.detachedWorktrees).toEqual([]);
+ });
+
+ it.each([
+ ['locked', { locked: true }, false, 'worktree-locked'],
+ ['dirty', {}, true, 'worktree-dirty'],
+ ])('holds a %s managed detached tree with its worktree-* reason', async (_name, extra, dirty, reason) => {
+ const path = '/repo/data/cos/worktrees/some-tree';
+ wt.listWorktrees.mockResolvedValue([MAIN, detachedTree(path, extra)]);
+ stubGit({ dirty });
+ const res = await reconcile('/repo');
+ expect(wt.forceRemoveWorktreeDir).not.toHaveBeenCalled();
+ expect(res.skipped).toContainEqual(expect.objectContaining({ path, reason, detached: true }));
+ expect(res.detachedWorktrees).toContainEqual(expect.objectContaining({ path, reason }));
+ // Not double-counted as a merged BRANCH held back.
+ expect(describeIdleReconcilePark(res.skipped, []).heldBackMerged).toEqual([]);
+ });
+
+ it('holds a managed tree owned by a live agent', async () => {
+ const path = '/repo/data/cos/worktrees/agent-1234abcd';
+ wt.listWorktrees.mockResolvedValue([MAIN, detachedTree(path)]);
+ stubGit();
+ const res = await reconcile('/repo', { activeAgentIds: new Set(['agent-1234abcd']) });
+ expect(wt.forceRemoveWorktreeDir).not.toHaveBeenCalled();
+ expect(res.skipped[0]).toMatchObject({ path, detached: true, reason: expect.stringMatching(/^worktree-/) });
+ });
+
+ it('reports, never removes, a detached tree outside the managed roots — and renders it for the coordinator', async () => {
+ const path = '/tmp/example-validation-tree';
+ wt.listWorktrees.mockResolvedValue([MAIN, detachedTree(path)]);
+ stubGit();
+ const res = await reconcile('/repo');
+ expect(wt.forceRemoveWorktreeDir).not.toHaveBeenCalled();
+ expect(res.cleaned).toEqual([]);
+ expect(res.skipped).toEqual([]);
+ expect(res.detachedWorktrees).toEqual([expect.objectContaining({ path, managed: false, reason: 'worktree-unmanaged-location' })]);
+ const prompt = await formatInFlightForPrompt([], { defaultBranch: 'main', detachedWorktrees: res.detachedWorktrees });
+ expect(prompt).toContain(path);
+ expect(prompt).toContain(`git worktree remove ${path}`);
+ });
+
+ it('never gathers the main checkout or a detached tree at unmerged commits', async () => {
+ wt.listWorktrees.mockResolvedValue([
+ { path: '/repo', head: 'aaa111', detached: true },
+ detachedTree('/repo/data/cos/worktrees/unmerged-work'),
+ ]);
+ stubGit({ merged: false });
+ const res = await reconcile('/repo');
+ expect(wt.forceRemoveWorktreeDir).not.toHaveBeenCalled();
+ expect(res.detachedWorktrees).toEqual([]);
+ expect(res.skipped).toEqual([]);
+ });
+});
+
describe('reconcile — a worktree holding only PortOS runtime scratch', () => {
const BRANCH = 'cos/app-improve-pr-reviewer-x/agent-985a8c77';
const WORKTREE = '/repo/data/cos/worktrees/agent-985a8c77';
diff --git a/server/services/cosTaskPreStepBlocks.js b/server/services/cosTaskPreStepBlocks.js
index e0646b3c57..ff192781e0 100644
--- a/server/services/cosTaskPreStepBlocks.js
+++ b/server/services/cosTaskPreStepBlocks.js
@@ -495,6 +495,8 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskS
// log so "nothing actionable" doesn't read as "no branches exist".
const heldLive = (result.wip || []).filter((b) => b.liveOwnerReason);
const heldLiveSuffix = countSuffix(heldLive, 'branch(es) left to their live owners', (b) => b.liveOwnerReason);
+ // A detached worktree has no branch to list anywhere else, so name it here too.
+ const detachedSuffix = countSuffix(result.detachedWorktrees, 'detached worktree(s) held back', (d) => d.reason);
const allActionable = filterActionable(result.inFlight, actions);
const actionable = limitBranchesForAgent(allActionable, metadata.branchesPerAgent);
if (allActionable.length === 0) {
@@ -514,7 +516,7 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskS
// sees a park while real branches sit there (the same invisibility that hid
// the abandoned-worktree case).
const gatedSuffix = countSuffix(result.inFlight, 'in-flight branch(es) skipped by disabled action toggles', (b) => b.state);
- emitLog('info', `🔀 branch-reconcile parked for ${app.name}: nothing actionable (cleaned ${result.cleaned.length}${heldSuffix}${gatedSuffix}${heldLiveSuffix}${supersededSuffix})`, { appId: app.id });
+ emitLog('info', `🔀 branch-reconcile parked for ${app.name}: nothing actionable (cleaned ${result.cleaned.length}${heldSuffix}${gatedSuffix}${heldLiveSuffix}${supersededSuffix}${detachedSuffix})`, { appId: app.id });
return { skip: true };
}
// Convergence guards — no-progress, then the consecutive-dispatch cap. See
@@ -534,14 +536,15 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskS
actions,
branchesPerAgent: metadata.branchesPerAgent,
repoPath: app.repoPath,
- appId: app.id
+ appId: app.id,
+ detachedWorktrees: result.detachedWorktrees
}),
supersededBlock
].filter(Boolean).join('\n');
const batchSuffix = allActionable.length > actionable.length
? ` (selected ${actionable.length} of ${allActionable.length})`
: '';
- emitLog('info', `🔀 branch-reconcile dispatching for ${app.name}: ${actionable.length} in-flight branch(es)${batchSuffix}${heldLiveSuffix}${supersededSuffix}`, { appId: app.id, analysisType: taskType });
+ emitLog('info', `🔀 branch-reconcile dispatching for ${app.name}: ${actionable.length} in-flight branch(es)${batchSuffix}${heldLiveSuffix}${supersededSuffix}${detachedSuffix}`, { appId: app.id, analysisType: taskType });
return { skip: false, block };
}