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: skip dangling agent-index rows in branch completion policy reads (#11848)

Adam Eivy04f7cbc8bcee
diff --git a/server/services/branchCompletionPolicy.js b/server/services/branchCompletionPolicy.js
index 1946fd8260..de34356608 100644
--- a/server/services/branchCompletionPolicy.js
+++ b/server/services/branchCompletionPolicy.js
@@ -2,7 +2,7 @@
* Read the existing agent records, including archives; PR bodies, summaries and
* shared forge logins never authorize reconciliation. No parallel policy store.
*/
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
import { join, resolve } from 'node:path';
import { PATHS } from '../lib/fileUtils.js';
import { isPlainObject } from '../lib/objects.js';
@@ -14,40 +14,71 @@ const samePath = (a, b) => typeof a === 'string' && typeof b === 'string'
const held = 'pr-completion-human-handoff';
const unavailable = 'pr-completion-policy-unavailable';
+const unavailableBecause = cause => new Error(unavailable, { cause });
+
/** Read once per gather, freshly again at mutation. Missing old policy fields
* are unknown history, not invented leave-open instructions. Corrupt records
- * cannot establish that a known handoff has been released.
+ * cannot establish that a known handoff has been released. An unavailable read
+ * logs its cause here, once per read, because every caller collapses the
+ * rejection into the same per-branch reason. Any other failure is wrapped as
+ * the unavailable reason with that failure as its cause.
*/
export async function readBranchCompletionPolicies() {
+ return readPolicies().catch(error => {
+ const cause = error.cause ?? error;
+ console.warn(`⚠️ Branch completion policy unavailable: ${cause.code ? `${cause.code} ` : ''}${cause.message}`);
+ throw error.message === unavailable ? error : unavailableBecause(error);
+ });
+}
+
+async function readPolicies() {
const { readAgentsStateForSafetyCheck } = await import('./cosState.js');
const snapshot = await readAgentsStateForSafetyCheck();
- if (!snapshot.trusted || !isPlainObject(snapshot.agents)) throw new Error(unavailable);
+ if (!snapshot.trusted || !isPlainObject(snapshot.agents)) throw unavailableBecause(new Error('live agent state is untrusted'));
const agents = new Map(Object.entries(snapshot.agents));
- if ([...agents].some(([id, agent]) => !isPlainObject(agent) || agent.id !== id)) throw new Error(unavailable);
+ if ([...agents].some(([id, agent]) => !isPlainObject(agent) || agent.id !== id)) throw unavailableBecause(new Error('live agent state has a mismatched record'));
const dir = join(PATHS.cos, 'agents');
const raw = await readFile(join(dir, 'index.json'), 'utf8').catch(async error => {
if (error.code === 'ENOENT') {
const entries = await readdir(dir).catch(missing => { if (missing.code === 'ENOENT') return []; throw missing; });
- if (entries.some(entry => /^\d{4}-\d{2}-\d{2}$/.test(entry) || (entry.startsWith('agent-') && !agents.has(entry)))) throw new Error(unavailable);
+ if (entries.some(entry => /^\d{4}-\d{2}-\d{2}$/.test(entry) || (entry.startsWith('agent-') && !agents.has(entry)))) throw error;
return '{}';
}
throw error;
});
const index = JSON.parse(raw);
- if (!isPlainObject(index)) throw new Error(unavailable);
+ if (!isPlainObject(index)) throw unavailableBecause(new Error('agent index is not an object'));
const entries = Object.entries(index).filter(([id]) => !agents.has(id));
- // Bounded parallelism; never read transcripts or repair/archive records here.
+ const dangling = [];
+ // Bounded parallelism; never read transcripts or archive records here.
for (let offset = 0; offset < entries.length; offset += 50) {
await Promise.all(entries.slice(offset, offset + 50).map(async ([id, date]) => {
- if (!/^[A-Za-z0-9_-]+$/.test(id) || !/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new Error(unavailable);
- const agent = JSON.parse(await readFile(join(dir, date, id, 'metadata.json'), 'utf8'));
- if (!isPlainObject(agent) || (agent.id || agent.agentId) !== id) throw new Error(unavailable);
+ if (!/^[A-Za-z0-9_-]+$/.test(id) || !/^\d{4}-\d{2}-\d{2}$/.test(date)) throw unavailableBecause(new Error('agent index has a malformed row'));
+ const recordDir = join(dir, date, id);
+ const content = await readFile(join(recordDir, 'metadata.json'), 'utf8').catch(async error => {
+ // A row with no record directory at all is a legacy dangling pointer,
+ // not a record that exists but cannot be trusted: it holds no policy.
+ if (error.code === 'ENOENT' && await stat(recordDir).then(() => false, missing => missing.code === 'ENOENT')) return null;
+ throw error;
+ });
+ if (content === null) { dangling.push(id); return; }
+ const agent = JSON.parse(content);
+ if (!isPlainObject(agent) || (agent.id || agent.agentId) !== id) throw unavailableBecause(new Error('archived agent record id mismatch'));
agents.set(id, agent);
}));
}
+ if (dangling.length) dropDanglingIndexRows(dangling);
return [...agents.values()];
}
+// Fire-and-forget repair of the source; the read above already ignores these rows.
+function dropDanglingIndexRows(ids) {
+ import('./cosAgentIndex.js')
+ .then(({ removeDanglingAgentIndexEntries }) => removeDanglingAgentIndexEntries(ids))
+ .then(count => { if (count) console.log(`🧹 Dropped ${count} agent-index row(s) with no archive directory`); })
+ .catch(error => console.error(`❌ Failed to drop dangling agent-index rows: ${error.message}`));
+}
+
/** Exact repo/branch identity. A known PR receipt never applies to another PR
* on the same branch. Without a PR read (offline retirement), preserve it.
* Only a later, completed, explicit policy for this exact PR and current tip
diff --git a/server/services/branchCompletionPolicy.test.js b/server/services/branchCompletionPolicy.test.js
index 017f7a58c1..6ee2b0d0aa 100644
--- a/server/services/branchCompletionPolicy.test.js
+++ b/server/services/branchCompletionPolicy.test.js
@@ -34,6 +34,7 @@ vi.mock('./github.js', () => ({
}));
vi.mock('./cos.js', () => ({ addTask: async task => ({ ...parseTasksMarkdown(generateTasksMarkdown([task]))[0], taskType: 'internal' }), forceSpawnTask: vi.fn(), getAgents: async () => [], updateTask: vi.fn() }));
vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn() }));
+vi.mock('./cosAgentIndex.js', () => ({ removeDanglingAgentIndexEntries: vi.fn(async ids => ids.length) }));
vi.mock('./git.js', () => ({ parsePullRequestUrl, getBranches: async () => [{ name: 'feature/handoff', tracking: 'origin/feature/handoff' }], hasBranchMergeEvidence: async () => runtime.merged }));
vi.mock('./worktreeManager.js', () => ({ listWorktrees: async () => [], classifyWorktreeDirt: () => ({ hasRealChanges: false, realChangePaths: [] }) }));
@@ -42,6 +43,7 @@ import { buildAgentRegistration } from '../lib/agentRegistrationRecord.js';
import { readBranchCompletionHold, readBranchCompletionPolicies, recordBranchCompletionPolicy } from './branchCompletionPolicy.js';
import { gatherBranchState, classifyBranches, filterActionable, formatInFlightForPrompt } from './branchReconcile.js';
import { checkReconcileOwnership } from './cosClaimOwnership.js';
+import { removeDanglingAgentIndexEntries } from './cosAgentIndex.js';
const task = completion => ({ id: 'task-example', taskType: 'internal', metadata: { prCompletion: completion } });
function register(id, completion, startedAt = '2026-01-01T00:00:00Z', extra = {}) {
@@ -189,12 +191,34 @@ describe('completion policy across lifecycle and reconciliation boundaries', ()
expect(await readBranchCompletionHold({ repoPath: '/other', branch, prUrl, agents: Object.values(runtime.agents) })).toBeNull();
});
- it.each(['missing-index', 'corrupt-index', 'missing-record', 'untrusted-state'])('holds when policy storage is %s', async failure => {
- await mkdir(join(runtime.dir, 'agents', '2026-01-01'), { recursive: true });
+ it.each(['missing-index', 'corrupt-index', 'missing-record', 'corrupt-record', 'untrusted-state'])('holds when policy storage is %s', async failure => {
+ await mkdir(join(runtime.dir, 'agents', '2026-01-01', 'agent-present'), { recursive: true });
if (failure === 'corrupt-index') await writeFile(join(runtime.dir, 'agents', 'index.json'), 'broken');
- if (failure === 'missing-record') await writeFile(join(runtime.dir, 'agents', 'index.json'), JSON.stringify({ 'agent-missing': '2026-01-01' }));
+ if (failure.endsWith('-record')) await writeFile(join(runtime.dir, 'agents', 'index.json'), JSON.stringify({ 'agent-present': '2026-01-01' }));
+ if (failure === 'corrupt-record') await writeFile(join(runtime.dir, 'agents', '2026-01-01', 'agent-present', 'metadata.json'), '{broken');
if (failure === 'untrusted-state') runtime.trusted = false;
- await expect(readBranchCompletionPolicies()).rejects.toThrow();
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const error = await readBranchCompletionPolicies().catch(rejected => rejected);
+ expect(error.message).toBe('pr-completion-policy-unavailable');
+ expect(error.cause).toBeInstanceOf(Error);
+ expect(warn).toHaveBeenCalledTimes(1);
+ expect(warn.mock.calls[0][0]).toContain(error.cause.message);
+ warn.mockRestore();
expect(await recheck()).toEqual({ admitted: false, reason: 'pr-completion-policy-unavailable' });
+ expect(removeDanglingAgentIndexEntries).not.toHaveBeenCalled();
+ });
+
+ it('reads past an index row whose archive directory is gone and repairs the index', async () => {
+ register('agent-human', 'leave-open');
+ const date = '2026-01-01';
+ await mkdir(join(runtime.dir, 'agents', date, 'agent-human'), { recursive: true });
+ await writeFile(join(runtime.dir, 'agents', 'index.json'), JSON.stringify({ 'agent-human': date, 'agent-gone': '2026-02-01' }));
+ await writeFile(join(runtime.dir, 'agents', date, 'agent-human', 'metadata.json'), JSON.stringify(runtime.agents['agent-human']));
+ runtime.agents = {};
+ removeDanglingAgentIndexEntries.mockClear();
+ const policies = await readBranchCompletionPolicies();
+ expect(policies.map(agent => agent.id)).toEqual(['agent-human']);
+ await vi.waitFor(() => expect(removeDanglingAgentIndexEntries).toHaveBeenCalledWith(['agent-gone']));
+ expect(await recheck()).toEqual({ admitted: false, reason: 'pr-completion-human-handoff' });
});
});
diff --git a/server/services/cosAgentIndex.js b/server/services/cosAgentIndex.js
index a15ea32564..f75942cca3 100644
--- a/server/services/cosAgentIndex.js
+++ b/server/services/cosAgentIndex.js
@@ -14,7 +14,7 @@ import { withBackupAssetPublication } from '../lib/backupSnapshotBoundary.js';
import { readFile, writeFile, rename, readdir, rm, stat, cp } from 'fs/promises';
import { existsSync } from 'fs';
import { join } from 'path';
-import { AGENTS_DIR } from './cosState.js';
+import { AGENTS_DIR, withStateLock } from './cosState.js';
import { atomicWrite, ensureDir, safeJSONParse, tryReadFile } from '../lib/fileUtils.js';
import { repairCodexTaskSummary } from './codexSummaryRepair.js';
import {
@@ -158,6 +158,30 @@ export async function addAgentArchivesToIndex(pairs) {
return added;
}
+/**
+ * Drop index rows whose `<date>/<id>/` archive directory no longer exists
+ * (legacy rows left by retired whole-run age deletion). Absence is rechecked
+ * under the state lock against the live mapping, because archive writers create
+ * the directory before indexing it. Returns the number of rows removed.
+ */
+export async function removeDanglingAgentIndexEntries(ids) {
+ if (!Array.isArray(ids) || ids.length === 0) return 0;
+ return withBackupAssetPublication(() => withStateLock(async () => {
+ const idx = await loadAgentIndex();
+ const removed = [];
+ for (const id of new Set(ids)) {
+ const date = idx.get(id);
+ if (typeof date !== 'string' || existsSync(join(AGENTS_DIR, date, id))) continue;
+ idx.delete(id);
+ removed.push([id, date]);
+ }
+ if (!removed.length) return 0;
+ try { await saveAgentIndex(); }
+ catch (err) { for (const [id, date] of removed) idx.set(id, date); throw err; }
+ return removed.length;
+ }));
+}
+
// Resolve the correct directory for an agent (running = flat, completed = date bucket)
export function getAgentDir(agentId, dateString) {
if (dateString) return join(AGENTS_DIR, dateString, agentId);
diff --git a/server/services/cosAgentIndex.merge.test.js b/server/services/cosAgentIndex.merge.test.js
index 4c36c0f801..cb984c8595 100644
--- a/server/services/cosAgentIndex.merge.test.js
+++ b/server/services/cosAgentIndex.merge.test.js
@@ -19,7 +19,7 @@ vi.mock('./cosState.js', () => ({
}));
vi.mock('./domainUsage.js', () => ({ recordDomainUsage: vi.fn(async () => {}) }));
-import { addAgentArchivesToIndex, getAgentIdsForDates, loadAgentIndex } from './cosAgentIndex.js';
+import { addAgentArchivesToIndex, getAgentIdsForDates, loadAgentIndex, removeDanglingAgentIndexEntries } from './cosAgentIndex.js';
const INDEX_FILE = join(mockCosState.agentsDir, 'index.json');
@@ -104,3 +104,26 @@ describe('getAgentIdsForDates (#3501)', () => {
expect((await getAgentIdsForDates([])).size).toBe(0);
});
});
+
+describe('removeDanglingAgentIndexEntries (#11848)', () => {
+ beforeEach(async () => {
+ await rm(mockCosState.agentsDir, { recursive: true, force: true });
+ await mkdir(join(mockCosState.agentsDir, '2026-09-05', 'agent-kept'), { recursive: true });
+ await writeFile(INDEX_FILE, '{}');
+ await addAgentArchivesToIndex([
+ { agentId: 'agent-kept', date: '2026-09-05' },
+ { agentId: 'agent-gone', date: '2026-02-01' },
+ ]);
+ });
+ afterEach(async () => {
+ await rm(mockCosState.agentsDir, { recursive: true, force: true });
+ });
+
+ it('persists removal only for rows whose archive directory is still absent', async () => {
+ expect(await removeDanglingAgentIndexEntries(['agent-gone', 'agent-kept', 'agent-unknown'])).toBe(1);
+ const onDisk = JSON.parse(await readFile(INDEX_FILE, 'utf8'));
+ expect(onDisk).toEqual(expect.objectContaining({ 'agent-kept': '2026-09-05' }));
+ expect(onDisk['agent-gone']).toBeUndefined();
+ expect(await removeDanglingAgentIndexEntries(['agent-gone'])).toBe(0);
+ });
+});