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: keep a new agent's worktree from being reaped before the agent registers (#11775)

Adam Eivy2130544dda5e
diff --git a/server/services/agentSpawnDispatch.dispatching.test.js b/server/services/agentSpawnDispatch.dispatching.test.js
new file mode 100644
index 0000000000..41c46f5c2f
--- /dev/null
+++ b/server/services/agentSpawnDispatch.dispatching.test.js
@@ -0,0 +1,94 @@
+/** An agent's worktree exists before anything records its owner (#11775): the id
+ * must read as active for the whole dispatch and be released on every exit.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const f = vi.hoisted(() => ({ registerGate: null, prep: null }));
+vi.mock('./cos.js', () => ({ getConfig: async () => ({}), updateTask: async () => ({ ok: true }) }));
+vi.mock('./cosAgentLifecycle.js', () => ({
+ registerAgent: vi.fn(() => f.registerGate),
+ updateAgent: vi.fn(),
+}));
+vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn(), cosEvents: { emit: vi.fn() } }));
+vi.mock('./agentRunTracking.js', () => ({ createAgentRun: async () => ({ runId: 'run-example' }) }));
+vi.mock('../lib/fileUtils.js', async (importOriginal) => ({
+ ...await importOriginal(), ensureDir: vi.fn(), writeFileGuarded: vi.fn(),
+}));
+vi.mock('../lib/backupSnapshotBoundary.js', () => ({ withBackupAssetPublication: (work) => work() }));
+vi.mock('../lib/workTracker.js', async (importOriginal) => ({
+ ...await importOriginal(),
+ resolveRepoForgeTarget: async () => null,
+ repoIssueUrlBase: () => null,
+}));
+vi.mock('../lib/primaryCheckoutGuard.js', () => ({ capturePrimaryCheckoutState: async () => null }));
+vi.mock('./agentPromptBuilder.js', () => ({
+ buildAgentPrompt: async () => 'example prompt',
+ getAppWorkspace: async () => '/repos/example',
+ isClaimFlowTask: () => false,
+ promptOpensOwnPr: () => false,
+}));
+vi.mock('./workspaceContext.js', () => ({ snapshotOnRepoSwitch: vi.fn() }));
+vi.mock('./agentProviderResolution.js', () => ({
+ resolveAgentProviderAndModel: async () => ({
+ ok: true, provider: { id: 'example-cli', type: 'cli', command: 'codex' }, selectedModel: 'example-model', modelSelection: {},
+ }),
+}));
+vi.mock('./agentWorkspacePrep.js', () => ({ prepareAgentWorkspace: async () => f.prep }));
+vi.mock('./agentCliSpawning.js', () => ({
+ buildCliSpawnConfig: () => ({ command: 'codex', args: [] }),
+ isClaudeCliProvider: () => false,
+ isTuiProvider: () => false,
+ getClaudeSettingsEnv: async () => ({}),
+ spawnDirectly: vi.fn(async () => 'agent-x'),
+}));
+vi.mock('./agentTuiSpawning.js', () => ({ buildTuiSpawnConfig: vi.fn(), spawnTuiAgent: vi.fn() }));
+
+import { dispatchAgentRun } from './agentSpawnDispatch.js';
+import { getActiveAgentIds, protectedAgentIds, setUseRunner } from './agentState.js';
+import { spawnDirectly } from './agentCliSpawning.js';
+
+const task = { id: 'task-example', taskType: 'user', description: 'example', metadata: {} };
+const newContext = () => ({
+ task, agentId: 'agent-x', instanceId: 'instance-example', toolExecution: { id: 'exec-example' }, laneName: 'standard',
+ blockAndBail: vi.fn(async () => null),
+ cleanupOnError: vi.fn(async () => null),
+});
+const isProtected = () => getActiveAgentIds().includes('agent-x') && protectedAgentIds([]).has('agent-x');
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ setUseRunner(false);
+ f.registerGate = Promise.resolve();
+ f.prep = { outcome: 'ready', workspacePath: '/repos/example', worktreeInfo: null };
+});
+
+describe('dispatchAgentRun ownership window', () => {
+ it('protects the agent while registration is pending and releases once handed off', async () => {
+ let finishRegistration;
+ f.registerGate = new Promise((resolve) => { finishRegistration = resolve; });
+ const dispatched = dispatchAgentRun(newContext());
+ await vi.waitFor(() => expect(isProtected()).toBe(true));
+
+ finishRegistration();
+ await dispatched;
+ expect(spawnDirectly).toHaveBeenCalled();
+ expect(getActiveAgentIds()).not.toContain('agent-x');
+ });
+
+ it('releases the agent when workspace prep blocks the dispatch', async () => {
+ f.prep = { outcome: 'blocked', reason: 'no workspace' };
+ const context = newContext();
+ context.cleanupOnError.mockImplementation(async () => {
+ expect(isProtected()).toBe(true);
+ });
+ expect(await dispatchAgentRun(context)).toBeNull();
+ expect(context.cleanupOnError).toHaveBeenCalledWith('no workspace');
+ expect(getActiveAgentIds()).not.toContain('agent-x');
+ });
+
+ it('releases the agent when dispatch throws', async () => {
+ f.registerGate = Promise.reject(new Error('state write failed'));
+ await expect(dispatchAgentRun(newContext())).rejects.toThrow('state write failed');
+ expect(getActiveAgentIds()).not.toContain('agent-x');
+ });
+});
diff --git a/server/services/agentSpawnDispatch.js b/server/services/agentSpawnDispatch.js
index 47b209cd6b..7bf8944479 100644
--- a/server/services/agentSpawnDispatch.js
+++ b/server/services/agentSpawnDispatch.js
@@ -28,7 +28,7 @@ import { loadPublicReviewSpawnInput } from './publicReviewSpawnInput.js';
import { securityScanGrantFromArgs } from '../lib/securityScanEvidence.js';
import { registerAgent, updateAgent } from './cosAgentLifecycle.js';
import { createAgentRun } from './agentRunTracking.js';
-import { useRunner } from './agentState.js';
+import { clearAgentDispatching, markAgentDispatching, useRunner } from './agentState.js';
import { cloudSwarmThreadCapacity, localEndpointOfProvider, providerBaseUrl } from './cosLocalEndpointSlots.js';
import { describeLocalPromptBudget, planLocalPromptBudget } from '../lib/localPromptBudget.js';
import { resolveAgentProviderAndModel } from './agentProviderResolution.js';
@@ -39,7 +39,21 @@ import { cosEvents, emitLog } from './cosEvents.js';
const ROOT_DIR = PATHS.root;
const AGENTS_DIR = PATHS.cosAgents;
-export async function dispatchAgentRun(context, { spawnViaRunner } = {}) {
+// The agent's worktree is created inside this call but nothing records its owner
+// until `registerAgent`, and the spawn helpers add it to the process maps later
+// still. Holding the id as "dispatching" for the whole call (released on every
+// return and throw, including blockAndBail) keeps reapers off a tree that is
+// clean and at the default branch's HEAD — i.e. indistinguishable from merged.
+export async function dispatchAgentRun(context, opts) {
+ markAgentDispatching(context.agentId);
+ try {
+ return await runAgentDispatch(context, opts);
+ } finally {
+ clearAgentDispatching(context.agentId);
+ }
+}
+
+async function runAgentDispatch(context, { spawnViaRunner } = {}) {
const { task, agentId, laneName, toolExecution, instanceId } = context;
const config = await getConfig();
const resolution = await resolveAgentProviderAndModel(task);
diff --git a/server/services/agentState.dispatching.test.js b/server/services/agentState.dispatching.test.js
new file mode 100644
index 0000000000..ded675f2b5
--- /dev/null
+++ b/server/services/agentState.dispatching.test.js
@@ -0,0 +1,16 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { clearAgentDispatching, getActiveAgentIds, markAgentDispatching, protectedAgentIds } from './agentState.js';
+
+describe('agent dispatching ownership', () => {
+ afterEach(() => clearAgentDispatching('agent-x'));
+
+ it('reports a mid-dispatch agent as active and protected until it is cleared', () => {
+ markAgentDispatching('agent-x');
+ expect(getActiveAgentIds()).toContain('agent-x');
+ expect(protectedAgentIds([]).has('agent-x')).toBe(true);
+
+ clearAgentDispatching('agent-x');
+ expect(getActiveAgentIds()).not.toContain('agent-x');
+ expect(protectedAgentIds([]).has('agent-x')).toBe(false);
+ });
+});
diff --git a/server/services/agentState.js b/server/services/agentState.js
index 3ea84857c0..31928b112d 100644
--- a/server/services/agentState.js
+++ b/server/services/agentState.js
@@ -114,12 +114,21 @@ export const getSpawnedAgent = (pid) => spawnedAgentCommands.get(pid);
export let useRunner = false;
export const setUseRunner = (val) => { useRunner = val; };
-// Active agent IDs (direct-mode + runner-mode), for zombie/orphan detection.
+// Agents between worktree creation and `registerAgent` (Set<agentId>). The tree
+// exists seconds before any record names an owner, and a fresh agent branch sits
+// at the default branch's HEAD, so a reaper reads it as clean and merged. Listing
+// the id in `getActiveAgentIds()` hands every reaper that already consults it the
+// protection, without reordering branch-reconcile's MERGED-before-owner check.
+const dispatchingAgentIds = new Set();
+export const markAgentDispatching = (agentId) => { dispatchingAgentIds.add(agentId); };
+export const clearAgentDispatching = (agentId) => { dispatchingAgentIds.delete(agentId); };
+
+// Active agent IDs (direct-mode + runner-mode + mid-dispatch), for zombie/orphan detection.
// Lives here in the side-effect-free state module so callers (cleanup jobs,
// zombie sweeps) can read it without importing the heavier `subAgentSpawner.js`
// orchestrator (which re-exports the whole agent-lifecycle module graph).
// `subAgentSpawner` re-exports it for backward compatibility.
-export const getActiveAgentIds = () => [...activeAgents.keys(), ...runnerAgents.keys()];
+export const getActiveAgentIds = () => [...activeAgents.keys(), ...runnerAgents.keys(), ...dispatchingAgentIds];
/**
* Agent ids whose worktree must not be taken out from under them, from an
diff --git a/server/services/branchReconcile.ownership.test.js b/server/services/branchReconcile.ownership.test.js
index 4bfa544c86..e72ab9a9fe 100644
--- a/server/services/branchReconcile.ownership.test.js
+++ b/server/services/branchReconcile.ownership.test.js
@@ -55,6 +55,7 @@ vi.mock('./supersededLedger.js', async (importOriginal) => ({
}));
const { reconcile, cleanupMerged, reapSupersededBranches } = await import('./branchReconcile.js');
+const { clearAgentDispatching, getActiveAgentIds, markAgentDispatching } = await import('./agentState.js');
const { deleteMergedBranches } = await import('./git.js');
const DAY = 24 * 60 * 60 * 1000;
@@ -154,6 +155,25 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('branch-reconcile worktree ownership (re
expect(await branches()).toEqual(expect.arrayContaining(['claim/issue-12', 'claim/issue-13', 'claim/issue-14']));
});
+ it('holds a clean agent tree at the default HEAD while its dispatch is still registering (#11775)', async () => {
+ const root = join(repo, '.claude', 'worktrees');
+ await mkdir(root, { recursive: true });
+ const tree = await addTree(join(root, 'agent-dispatching'), 'agent/dispatching');
+ markAgentDispatching('agent-dispatching');
+ try {
+ const held = await reconcile(repo, { activeAgentIds: new Set(getActiveAgentIds()) });
+ expect(held.cleaned).not.toContain('agent/dispatching');
+ expect(held.skipped).toContainEqual(expect.objectContaining({ branch: 'agent/dispatching', reason: 'worktree-active-agent' }));
+ expect(existsSync(tree)).toBe(true);
+ } finally {
+ clearAgentDispatching('agent-dispatching');
+ }
+ // Once dispatch settles without registering an owner, the same tree is reaped.
+ const reaped = await reconcile(repo, { activeAgentIds: new Set(getActiveAgentIds()) });
+ expect(reaped.cleaned).toContain('agent/dispatching');
+ expect(existsSync(tree)).toBe(false);
+ });
+
it('leaves the operator-initiated merged-branch cleanup able to remove an unmanaged tree', async () => {
const loose = await addTree(join(external, 'loose'), 'loose-br', { ageMs: 30 * DAY });