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
import { makePathsProxy, lazyTempDataRoot, cleanupTempDataRoots } from '../lib/mockPathsDataRoot.js';
vi.mock('../lib/paths.js', async original => makePathsProxy(await original(), { dataRoot: () => lazyTempDataRoot('portos-finalization-output-') }));
afterAll(cleanupTempDataRoots);
const mergedTarget = vi.hoisted(() => ({
getOriginInfo: vi.fn(),
probeChangeRequestState: vi.fn(),
}));
vi.mock('../lib/gitRemote.js', () => ({ getOriginInfo: mergedTarget.getOriginInfo }));
vi.mock('./prProbe.js', () => ({ probeChangeRequestState: mergedTarget.probeChangeRequestState }));
const claimVerifier = vi.hoisted(() => ({ verifyClaimDisposition: vi.fn() }));
vi.mock('./claimDisposition.js', () => claimVerifier);
vi.mock('../lib/fileUtils.js', async importOriginal => {
const actual = await importOriginal();
return { ...actual, tryReadFile: vi.fn(actual.tryReadFile) };
});
import { tryReadFile } from '../lib/fileUtils.js';
const deep = vi.hoisted(() => ({ checkpointDeepAudit: vi.fn(async () => ({ id: 'deep-1', complete: false, reason: 'Checkpoint partial' })), settleDeepAuditDelivery: vi.fn(async () => ({ id: 'deep-1', complete: false, reason: 'Checkpoint partial' })) }));
vi.mock('./deepAudit.js', () => deep);
vi.mock('../lib/gitCommitProbe.js', () => ({ committedDuringRun: vi.fn(async () => false) }));
vi.mock('./appQuality.js', () => ({ recordAuditQuality: vi.fn(async () => true) }));
import { recordAuditQuality } from './appQuality.js';
// Hoisted doubles rather than static imports: the audit path reaches both modules
// lazily, and importing them here would drag their subtrees into this suite's closure.
const appsRegistry = vi.hoisted(() => ({ getAppById: vi.fn(async () => null) }));
vi.mock('./apps.js', () => appsRegistry);
const snapshotFile = vi.hoisted(() => ({ publishAppQualitySnapshot: vi.fn(async () => ({ published: true, hash: 'abc1234' })) }));
vi.mock('./appQualitySnapshotFile.js', () => snapshotFile);
// The goal-fidelity gate (#5994) reaches a local model at completion. Pinned OFF
// here so these tests exercise the path they are about without depending on the
// developer's own reviewer settings — and so a machine that HAS a local reviewer
// configured never has its suite dispatch a real review request.
vi.mock('./codeReview.js', async (importOriginal) => ({
...(await importOriginal()),
getGoalFidelityConfig: vi.fn(async () => null),
}));
import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
vi.mock('./cosAgentLifecycle.js', () => ({
getAgent: vi.fn(),
getAgentRecord: vi.fn(async () => null),
updateAgent: vi.fn(),
completeAgent: vi.fn(),
}));
vi.mock('./taskTypeHooks.js', () => ({
canRunTaskOutputHookWithoutPayload: vi.fn(() => true),
getTaskOutputHook: vi.fn(),
getTaskOutputPayloadPredicate: vi.fn(async () => null),
declaresNoCommitCriterion: vi.fn(() => false),
isClaimFlowDispatch: vi.fn(() => false),
isProgrammaticIoTaskType: vi.fn(() => true),
resolveTaskHookType: vi.fn(task => task?.metadata?.analysisType || null),
}));
import { getAgent, getAgentRecord, updateAgent, completeAgent } from './cosAgentLifecycle.js';
import { canRunTaskOutputHookWithoutPayload, declaresNoCommitCriterion, getTaskOutputHook, isProgrammaticIoTaskType } from './taskTypeHooks.js';
import {
finalizeAgent,
retireDeadAgent,
dispatchRecoveredTaskOutputHook,
dispatchTaskOutputHookOnce,
} from './agentFinalization.js';
vi.mock('./cosTaskStore.js', () => ({
updateTask: vi.fn(async () => ({})),
getTaskById: vi.fn(async () => null),
addTask: vi.fn(async () => ({ id: 'investigation-test' })),
}));
vi.mock('./investigationTaskProducer.js', () => ({
investigationCircuitOpen: vi.fn(() => false),
noteInvestigationFiled: vi.fn(),
readAllTasksFlat: vi.fn(async () => []),
recentInvestigationCreations: vi.fn(() => []),
}));
vi.mock('./agentErrorAnalysis.js', async importOriginal => {
const actual = await importOriginal();
return { ...actual, resolveFailedTaskUpdate: vi.fn(actual.resolveFailedTaskUpdate) };
});
vi.mock('./agentRunTracking.js', () => ({ completeAgentRun: vi.fn(async () => null) }));
vi.mock('./agentCompletion.js', () => ({ processAgentCompletion: vi.fn(async () => null) }));
vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn(), cosEvents: { emit: vi.fn(), on: vi.fn() } }));
import { emitLog } from './cosEvents.js';
vi.mock('./taskSchedule.js', () => ({
recordTaskTypeFailure: vi.fn(async () => null),
recordTaskTypeSuccess: vi.fn(async () => null),
recordRecommendedAudits: vi.fn(async () => null),
}));
import { updateTask, addTask, getTaskById } from './cosTaskStore.js';
import { completeAgentRun } from './agentRunTracking.js';
import { processAgentCompletion } from './agentCompletion.js';
import { MAX_TASK_RETRIES, resolveFailedTaskUpdate } from './agentErrorAnalysis.js';
const __dirname = dirname(fileURLToPath(import.meta.url));
const MANAGEMENT_SOURCE = readFileSync(join(__dirname, 'agentManagement.js'), 'utf8');
const LIFECYCLE_SOURCE = readFileSync(join(__dirname, 'agentLifecycle.js'), 'utf8');
const TASK = {
id: 'sys-example',
taskType: 'internal',
metadata: {
analysisType: 'example-output-hook',
app: 'app-example',
repoPath: '/example/repo',
},
};
describe('recovery output-hook dispatch (#3182)', () => {
let persistedAgent;
let hook;
beforeEach(() => {
vi.clearAllMocks();
persistedAgent = {
id: 'agent-example',
status: 'running',
startedAt: '2026-09-10T00:00:00Z',
metadata: {},
};
getAgent.mockImplementation(async () => persistedAgent);
getAgentRecord.mockImplementation(async () => persistedAgent);
updateAgent.mockImplementation(async (_agentId, updates) => {
persistedAgent = {
...persistedAgent,
metadata: { ...persistedAgent.metadata, ...updates.metadata },
};
return persistedAgent;
});
hook = vi.fn().mockResolvedValue({ recorded: true });
getTaskOutputHook.mockResolvedValue(hook);
});
it('awaits the scheduled outcome ledger and finishes even when that write fails', async () => {
const { recordTaskTypeSuccess, recordTaskTypeFailure } = await import('./taskSchedule.js');
let rejectLedger;
recordTaskTypeSuccess.mockReturnValueOnce(new Promise((_resolve, reject) => { rejectLedger = reject; }));
const completion = finalizeAgent({
agentId: persistedAgent.id, task: TASK, success: true, exitCode: 0,
duration: 1000, outputBuffer: '',
});
await vi.waitFor(() => expect(recordTaskTypeSuccess).toHaveBeenCalledWith('example-output-hook', 'app-example'));
expect(updateTask).toHaveBeenCalledWith(TASK.id, expect.objectContaining({ status: 'completed', metadata: expect.objectContaining({ taskOutcome: { status: 'completed', reason: 'The task delivery criteria passed.' } }) }), 'internal');
expect(processAgentCompletion).not.toHaveBeenCalled();
rejectLedger(new Error('ledger write failed'));
await expect(completion).resolves.toMatchObject({ success: true });
expect(recordTaskTypeFailure).not.toHaveBeenCalled();
expect(processAgentCompletion).toHaveBeenCalledWith(persistedAgent.id, TASK, true, '');
expect(emitLog).toHaveBeenCalledWith('warn', expect.stringContaining('ledger write failed'), expect.any(Object));
});
it('records an unparseable scheduled output as a failure but excludes ad-hoc and terminated tasks', async () => {
const { recordTaskTypeSuccess, recordTaskTypeFailure } = await import('./taskSchedule.js');
hook.mockResolvedValueOnce({ recorded: false, reason: 'unparseable-response' });
await finalizeAgent({ agentId: persistedAgent.id, task: TASK, success: true, exitCode: 0, duration: 1000, outputBuffer: '' });
expect(recordTaskTypeFailure).toHaveBeenCalledWith('example-output-hook', 'app-example', { errorCategory: 'unparseable-response' });
expect(recordTaskTypeSuccess).not.toHaveBeenCalled();
recordTaskTypeFailure.mockClear();
await finalizeAgent({ agentId: 'ad-hoc', task: { id: 'ad-hoc-task', taskType: 'user', metadata: {} }, success: true, outputBuffer: '' });
await finalizeAgent({ agentId: 'terminated', task: TASK, success: false, terminatedByUser: true, outputBuffer: '' });
expect(recordTaskTypeFailure).not.toHaveBeenCalled();
expect(recordTaskTypeSuccess).not.toHaveBeenCalled();
});
it('persists scanner limits independently of successful assessment delivery and completion replay', async () => {
const scanner = { version: 1, status: 'time-limit', model: 'example-model', effort: 'low', auth: 'chatgpt',
maxCostUsd: null, estimatedCostUsd: null, timeLimitSeconds: 600, exitCode: 130,
artifacts: { findings: true, coverage: false } };
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security', prCompletion: 'draft' } };
persistedAgent.metadata.executionInterruption = { category: 'content-refusal', source: 'provider' };
tryReadFile.mockResolvedValueOnce(`Delivered a fix.\nSCANNER_STATUS_JSON: ${JSON.stringify(scanner)}`);
const args = { agentId: 'agent-scanner', task, success: true, workspacePath: '/worktree' };
await dispatchTaskOutputHookOnce(args);
expect(persistedAgent.metadata).toMatchObject({ securityScan: { ...scanner, source: 'agent-report' },
auditAssessment: { status: 'recorded' }, executionInterruption: { category: 'content-refusal' } });
await dispatchTaskOutputHookOnce(args);
expect(persistedAgent.metadata.securityScan.status).toBe('time-limit');
});
it("lands the code-quality lane's ranked next audits on the execution record (#12085)", async () => {
const { recordRecommendedAudits } = await import('./taskSchedule.js');
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'code-quality' } };
tryReadFile.mockResolvedValueOnce('Filed 2 issues.\n## Recommended next audits\n1. better-structural-drift — drifted registries: server/lib\n2. ux — buried action: client/src\nQUALITY_AUDIT_JSON: {}');
await dispatchTaskOutputHookOnce({ agentId: 'agent-triage', task, success: true, workspacePath: '/worktree' });
expect(recordRecommendedAudits).toHaveBeenCalledWith('code-quality', 'app-example', [
'better-structural-drift — drifted registries: server/lib',
'ux — buried action: client/src',
]);
expect(persistedAgent.metadata).toMatchObject({ auditAssessment: { status: 'recorded' } });
});
it('captures audit telemetry on the shared completion path without waiving fix-mode delivery criteria', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'better-complexity' } };
await expect(dispatchTaskOutputHookOnce({ agentId: 'agent-audit', task, success: true, workspacePath: '/worktree' }))
.resolves.toEqual({ ran: false, auditAssessment: { status: 'recorded' } });
expect(recordAuditQuality).toHaveBeenCalledWith({ task, taskType: 'better-complexity', agentId: 'agent-audit', success: true, workspacePath: '/worktree', assessedAt: persistedAgent.startedAt });
expect(hook).not.toHaveBeenCalled();
expect(updateAgent).toHaveBeenCalledWith('agent-audit', { metadata: { auditAssessment: { status: 'recorded' } } });
});
it('fails audit delivery with retained actionable rows even when its quality assessment succeeded', async () => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'audit-disposition-final-'));
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security', auditDispositionVersion: '1' } };
const report = { version: 1, findings: [{ key: 'example-boundary', title: 'Example authority gap', path: 'server/routes/example.js',
severity: 8, confidence: 'high', evidence: 'Synthetic mounted request crossed the boundary.', classification: 'actionable',
disposition: { kind: 'unresolved', reason: 'Issue creation failed: tracker unavailable.' } }] };
try {
tryReadFile.mockImplementation(async path => (await import('node:fs/promises')).readFile(path, 'utf8').catch(() => null));
await writeFile(join(workspacePath, '.agent-done-agent-disposition-final'), JSON.stringify({
summary: `Delivered a coherent fix.\nAUDIT_FINDINGS_JSON: ${JSON.stringify(report)}`,
}));
await finalizeAgent({ agentId: 'agent-disposition-final', task, success: true, exitCode: 0, duration: 1000,
workspacePath, outputBuffer: 'Completed assessment and one fix' });
expect(persistedAgent.metadata.auditFindings.report).toEqual(report);
expect(completeAgent).toHaveBeenCalledWith('agent-disposition-final', expect.objectContaining({
success: false, auditAssessment: { status: 'recorded' },
auditDisposition: expect.objectContaining({ status: 'incomplete', unresolved: 1 }),
completionReason: 'audit-disposition-incomplete',
}));
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'blocked' }), 'internal');
expect(addTask).not.toHaveBeenCalled();
// A saved score cannot waive a missing final register on recovery replay.
await rm(join(workspacePath, '.agent-done-agent-disposition-final'));
await expect(dispatchRecoveredTaskOutputHook({ agentId: 'agent-disposition-final', task, success: true, workspacePath }))
.resolves.toMatchObject({ auditDisposition: { status: 'incomplete', unresolved: 1 } });
} finally {
await rm(workspacePath, { recursive: true, force: true });
tryReadFile.mockReset();
}
});
it('saves the assessment when scanner diagnostic persistence fails', async () => {
const scanner = { version: 1, status: 'time-limit', model: null, effort: null, auth: 'unknown',
maxCostUsd: null, estimatedCostUsd: null, timeLimitSeconds: 600, exitCode: null,
artifacts: { findings: null, coverage: null } };
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security', prCompletion: 'draft' } };
tryReadFile.mockResolvedValueOnce(`SCANNER_STATUS_JSON: ${JSON.stringify(scanner)}`);
updateAgent.mockRejectedValueOnce(new Error('diagnostic storage unavailable'));
await expect(dispatchTaskOutputHookOnce({ agentId: 'agent-diagnostic-failure', task, success: true, workspacePath: '/worktree' }))
.resolves.toMatchObject({ auditAssessment: { status: 'recorded' } });
expect(recordAuditQuality).toHaveBeenCalledWith(expect.objectContaining({ task, success: true }));
expect(persistedAgent.metadata.auditAssessment).toEqual({ status: 'recorded' });
expect(emitLog).toHaveBeenCalledWith('warn', expect.stringContaining('Scanner diagnostics were not saved'), expect.any(Object));
});
// Landing the app's `.quality.json` PR is opt-in and runs outside the request
// lifecycle, so it must never fire for an un-opted app nor fail a completion.
// Each dispatch needs its own agent id — dispatchTaskOutputHookOnce caches by id.
it.each(['draft', 'leave-open'])('retains measurements without publishing snapshots for %s, on completion', async prCompletion => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security', prCompletion } };
appsRegistry.getAppById.mockResolvedValue({ id: 'app-example', repoPath: '/repo', publishQualitySnapshot: true });
snapshotFile.publishAppQualitySnapshot.mockClear();
await dispatchTaskOutputHookOnce({ agentId: `review-only-${prCompletion}`, task, success: true, workspacePath: '/worktree' });
expect(recordAuditQuality).toHaveBeenCalledWith(expect.objectContaining({ task, success: true }));
expect(snapshotFile.publishAppQualitySnapshot).not.toHaveBeenCalled();
await dispatchRecoveredTaskOutputHook({ agentId: persistedAgent.id, task, success: true });
expect(snapshotFile.publishAppQualitySnapshot).not.toHaveBeenCalled();
});
it('commits a repo snapshot only for an opted-in app that just recorded a measurement', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'better-complexity' } };
let run = 0;
const dispatch = () => { persistedAgent.metadata = {}; return dispatchTaskOutputHookOnce({ agentId: `agent-snapshot-${run += 1}`, task, success: true, workspacePath: '/worktree' }); };
const optedIn = { id: 'app-example', repoPath: '/repo/example-app', publishQualitySnapshot: true };
appsRegistry.getAppById.mockResolvedValue(optedIn);
await expect(dispatch()).resolves.toEqual({ ran: false, auditAssessment: { status: 'recorded' } });
expect(snapshotFile.publishAppQualitySnapshot).toHaveBeenCalledWith(optedIn);
for (const app of [{ ...optedIn, publishQualitySnapshot: false }, { ...optedIn, publishQualitySnapshot: 'true' },
{ id: 'app-example' }, null]) {
snapshotFile.publishAppQualitySnapshot.mockClear();
appsRegistry.getAppById.mockResolvedValue(app);
await dispatch();
expect(snapshotFile.publishAppQualitySnapshot).not.toHaveBeenCalled();
}
// A missing or invalid report records nothing, so there is nothing new to publish.
appsRegistry.getAppById.mockResolvedValue(optedIn);
recordAuditQuality.mockResolvedValueOnce(false);
await dispatch();
expect(snapshotFile.publishAppQualitySnapshot).not.toHaveBeenCalled();
// A locked index or an unreadable registry must not fail the completion.
snapshotFile.publishAppQualitySnapshot.mockRejectedValueOnce(new Error('index.lock exists'));
await expect(dispatch()).resolves.toEqual({ ran: false, auditAssessment: { status: 'recorded' } });
appsRegistry.getAppById.mockRejectedValueOnce(new Error('registry unreadable'));
await expect(dispatch()).resolves.toEqual({ ran: false, auditAssessment: { status: 'recorded' } });
for (const reason of ['index.lock exists', 'registry unreadable']) {
expect(emitLog).toHaveBeenCalledWith('error', `❌ Quality snapshot publish failed for app app-example: ${reason}`, { appId: 'app-example' });
}
});
it('records assessment failure independently and allows recovery to persist it later', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security' } };
recordAuditQuality.mockRejectedValueOnce(new Error('storage unavailable'));
const first = await dispatchTaskOutputHookOnce({ agentId: 'audit-recovery', task, success: true, workspacePath: '/worktree' });
expect(first).toEqual({ ran: false, auditAssessment: { status: 'persistence-failed' } });
expect(persistedAgent.metadata.auditAssessment.status).toBe('persistence-failed');
await expect(dispatchRecoveredTaskOutputHook({ agentId: 'audit-recovery', task, success: true, workspacePath: '/worktree' }))
.resolves.toEqual({ ran: false, auditAssessment: { status: 'recorded' } });
expect(persistedAgent.metadata.auditAssessment.status).toBe('recorded');
recordAuditQuality.mockClear();
await dispatchRecoveredTaskOutputHook({ agentId: 'audit-recovery', task, success: true });
expect(recordAuditQuality).not.toHaveBeenCalled();
});
it('retains a saved result when an older failure marker survived a metadata write error', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security' } };
persistedAgent.metadata.auditAssessment = { status: 'persistence-failed' };
persistedAgent.result = { auditAssessment: { status: 'recorded' } };
await expect(dispatchRecoveredTaskOutputHook({ agentId: 'saved-result', task, success: true }))
.resolves.toEqual({ ran: false, auditAssessment: { status: 'recorded' } });
expect(recordAuditQuality).not.toHaveBeenCalled();
});
it.each([false, true])('preserves legacy learning results while enforcing explicit delivery=%s', async explicit => {
isProgrammaticIoTaskType.mockImplementation(type => type !== 'security');
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security' } };
recordAuditQuality.mockResolvedValueOnce(false);
await finalizeAgent({ agentId: 'audit-final', task, success: true, exitCode: 0, duration: 1000,
workspacePath: '/missing-audit-worktree', startedAt: Date.now() - 1000, outputBuffer: 'Audit complete',
finalSummary: explicit ? JSON.stringify({ summary: 'Invented audit report.', taskOutcome: { status: 'completed', reason: 'Invented completion claim.' } }) : null });
expect(completeAgent).toHaveBeenCalledWith('audit-final', expect.objectContaining({
success: !explicit, executionSuccess: true, validationPassed: false,
taskOutcome: explicit ? { status: 'incomplete', reason: 'Delivery checks did not pass.' } : null, auditAssessment: { status: 'not-recorded' },
}));
isProgrammaticIoTaskType.mockReturnValue(true);
});
it('keeps exact large ingestion and replay bytes in run artifacts rather than hot agent metadata', async () => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const { readCompletionData } = await import('./agentCompletionData.js');
const workspacePath = await mkdtemp(join(tmpdir(), 'completion-large-ingestion-'));
const payload = 'payload-'.repeat(150000);
const outputBuffer = 'provider-output-'.repeat(100000);
const sentinel = JSON.stringify({ summary: 'Delivered.', payload });
try {
await writeFile(join(workspacePath, '.agent-done-agent-example'), sentinel);
await finalizeAgent({ agentId: 'agent-example', task: { ...TASK, prompt: payload, history: payload },
success: true, exitCode: 0, duration: 1000, workspacePath, outputBuffer });
expect(JSON.stringify(persistedAgent.metadata).length).toBeLessThan(15000);
expect(JSON.parse(JSON.stringify(persistedAgent.metadata))).not.toHaveProperty('completionSentinelContents');
expect(JSON.parse(JSON.stringify(persistedAgent.metadata.completionCleanup))).not.toHaveProperty('context');
expect(await readCompletionData(persistedAgent, persistedAgent.metadata.completionSentinelData)).toBe(sentinel);
const replay = await readCompletionData(persistedAgent, persistedAgent.metadata.completionCleanup.replay);
expect(replay.outputBuffer).toBe(outputBuffer);
expect(replay.task.id).toBe(TASK.id);
expect(replay.task).not.toHaveProperty('prompt');
expect(replay.task).not.toHaveProperty('history');
await expect(readCompletionData({ ...persistedAgent, startedAt: '2020-01-01T00:00:00Z' },
persistedAgent.metadata.completionCleanup.replay)).rejects.toThrow('completion-data-run-changed');
} finally { await rm(workspacePath, { recursive: true, force: true }); }
});
it.each([
['markdown checkpoint', 'Reviewed this batch. Deep coverage remains incomplete.', 'Reviewed this batch. Deep coverage remains incomplete.'],
['structured checkpoint', JSON.stringify({ summary: 'Saved a partial checkpoint.', payload: null }), 'Saved a partial checkpoint.'],
['missing summary', null, null],
['terminal result fallback', null, 'Explicit terminal result.', 'Explicit terminal result.'],
['sentinel precedence', 'Saved checkpoint.', 'Saved checkpoint.', 'Provider terminal response.'],
['fenced valid envelope', '```json\n{"summary":"Fenced completion."}\n```', 'Fenced completion.'],
['fenced malformed envelope', '```json\n{"summary":\n```', null],
['malformed envelope', '{"summary":', null],
['invalid summary', JSON.stringify({ summary: { text: 'not a string' } }), null],
])('persists only explicit completion text for a resumed Deep %s', async (_label, sentinel, expected, finalSummary = null) => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'completion-summary-'));
try {
if (sentinel !== null) await writeFile(join(workspacePath, '.agent-done-summary-example'), sentinel);
const task = { ...TASK, metadata: { ...TASK.metadata, auditDepth: 'deep', simplify: false } };
await finalizeAgent({ agentId: 'summary-example', task, success: true, exitCode: 0,
duration: 1000, workspacePath, finalSummary, outputBuffer: 'Thinking: inspect files\nexec\npython command output' });
expect(persistedAgent.metadata.taskSummary).toBe(expected);
expect(persistedAgent.metadata.simplifySummary).toBeNull();
expect(deep.checkpointDeepAudit).toHaveBeenCalled();
} finally {
await rm(workspacePath, { recursive: true, force: true });
}
});
it.each(['blocked', 'incomplete', 'completed', 'no-action-needed'])('persists explicit %s delivery independently of a zero exit', async (status) => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'task-outcome-'));
const taskOutcome = { status, reason: 'Invented prerequisite or delivery evidence.' };
const held = ['blocked', 'incomplete'].includes(status);
const task = { ...TASK, metadata: { ...TASK.metadata } };
try {
await writeFile(join(workspacePath, '.agent-done-agent-example'), JSON.stringify({ summary: 'Invented final report.', taskOutcome, payload: { result: 'example' } }));
const result = await finalizeAgent({ agentId: 'agent-example', runId: 'run-example', task, success: true,
exitCode: 0, duration: 1000, workspacePath, outputBuffer: '' });
expect(result).toMatchObject({ success: !held, taskOutcome });
expect(completeAgent).toHaveBeenCalledWith('agent-example', expect.objectContaining({ executionSuccess: true, success: !held, taskOutcome }));
expect(completeAgentRun).toHaveBeenCalledWith('run-example', '', 0, 1000, held ? expect.objectContaining({ category: `task-${status}` }) : undefined, held ? false : null, { executionSuccess: true, taskOutcome });
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: held ? 'in_progress' : 'completed', metadata: expect.objectContaining({ taskOutcome }) }), task.taskType);
expect(persistedAgent.metadata.taskOutcome).toEqual(taskOutcome);
expect(processAgentCompletion).toHaveBeenCalledWith('agent-example', task, !held, '');
} finally {
await rm(workspacePath, { recursive: true, force: true });
}
});
const reviewTask = () => ({ id: TASK.id, taskType: 'internal', status: 'in_progress', metadata: {
reviewLoopFollowUp: true, reviewLoopPRUrl: 'https://github.com/atomantic/PortOS/pull/123',
reviewLoopPRBranch: 'fix/example', failureCount: 2,
} });
it.each(['normal', 'restart'])('completes a verified merged review target without retrying during %s completion', async mode => {
isProgrammaticIoTaskType.mockReturnValue(false);
mergedTarget.getOriginInfo.mockResolvedValue({ host: 'github.com', fullName: 'atomantic/PortOS' });
mergedTarget.probeChangeRequestState.mockResolvedValue({ readable: true, prState: 'MERGED' });
const task = reviewTask();
const reported = { status: mode === 'normal' ? 'blocked' : 'incomplete', reason: 'The target is merged; corrections are tracked separately and the checkout is preserved.' };
persistedAgent.metadata.workspacePath = '/example/repo';
persistedAgent.metadata.taskOutcome = reported;
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
const result = mode === 'normal'
? await finalizeAgent({ agentId: 'agent-example', runId: 'run-example', task, success: true,
exitCode: 0, duration: 1000, workspacePath: '/example/repo', outputBuffer: '',
finalSummary: JSON.stringify({ summary: reported.reason, taskOutcome: reported }) })
: await retireDeadAgent({ agent: persistedAgent, task, success: true, exitCode: 0, duration: 1000 });
expect(mergedTarget.probeChangeRequestState).toHaveBeenCalledWith('/example/repo', { number: 123, branch: 'fix/example' });
expect(result).toMatchObject({ success: true, taskOutcome: { status: 'no-action-needed' } });
if (mode === 'normal') expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'completed',
metadata: expect.objectContaining({ failureCount: 2, taskOutcome: expect.objectContaining({ status: 'no-action-needed' }) }) }), 'internal');
expect(completeAgent).toHaveBeenCalledWith('agent-example', expect.objectContaining({ success: true, validationPassed: true,
taskOutcome: expect.objectContaining({ status: 'no-action-needed' }) }));
expect(persistedAgent.metadata).toMatchObject({ taskOutcomeSource: 'forge-verification', reportedTaskOutcome: reported });
expect(resolveFailedTaskUpdate).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
if (mode === 'normal') expect(processAgentCompletion).toHaveBeenCalledWith('agent-example', task, true, '');
else expect(result.deliveryHeld).toBe(false);
});
it.each([
{ name: 'an open target', state: { readable: true, prState: 'OPEN' } },
{ name: 'a closed unmerged target', state: { readable: true, prState: 'CLOSED' } },
{ name: 'an unreadable target', state: { readable: false, prState: null } },
{ name: 'a different repository', meta: { reviewLoopPRUrl: 'https://github.com/another/project/pull/123' } },
{ name: 'a leave-open policy', meta: { reviewLoopLeaveOpen: true } },
{ name: 'an ordinary task', meta: { reviewLoopFollowUp: false } },
{ name: 'a failed process', execution: { success: false, exitCode: 1 } },
{ name: 'a provider safety refusal', execution: { executionInterruption: { category: 'content-refusal' } } },
])('does not replace a blocked outcome for $name', async ({ state, meta, execution }) => {
isProgrammaticIoTaskType.mockReturnValue(false);
mergedTarget.getOriginInfo.mockResolvedValue({ host: 'github.com', fullName: 'atomantic/PortOS' });
mergedTarget.probeChangeRequestState.mockResolvedValue(state || { readable: true, prState: 'MERGED' });
const task = reviewTask();
Object.assign(task.metadata, meta);
const reported = { status: 'blocked', reason: 'An unmet prerequisite remains.' };
const result = await finalizeAgent({ agentId: 'agent-example', task, success: true, exitCode: 0,
duration: 1000, workspacePath: '/example/repo', outputBuffer: '', ...execution,
finalSummary: JSON.stringify({ summary: reported.reason, taskOutcome: reported }) });
expect(result).toMatchObject({ success: false, taskOutcome: reported });
expect(updateTask).not.toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'completed' }), 'internal');
});
it('retains explicit approval with choices instead of retrying', async () => {
const taskOutcome = { status: 'blocked', reason: 'Continuing would exceed the authorized budget.',
recovery: { mode: 'approval', options: ['Increase the budget and retry.', 'Keep the work stopped.'] } };
await finalizeAgent({ agentId: 'agent-example', task: TASK, success: true, exitCode: 0,
finalSummary: JSON.stringify({ summary: 'Budget decision needed.', taskOutcome }) });
expect(updateTask).toHaveBeenLastCalledWith(TASK.id, expect.objectContaining({ status: 'blocked',
metadata: expect.objectContaining({ blockedCategory: 'task-approval',
blockedReason: expect.stringContaining('1. Increase the budget and retry.') }) }), TASK.taskType);
expect(addTask).not.toHaveBeenCalled();
});
it('persists the LI execution verdict in the same public completion task write', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
const task = { ...TASK, metadata: { ...TASK.metadata, liProposal: {
appId: 'app-example', slug: 'example-proposal', scope: 'repo',
} } };
await finalizeAgent({ agentId: persistedAgent.id, task, success: true, exitCode: 0, outputBuffer: '' });
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'completed', metadata: expect.objectContaining({
liExecution: expect.objectContaining({ appId: 'app-example', slug: 'example-proposal', success: true }),
}) }), 'internal');
});
it.each(['normal', 'recovered'])('parks a runtime prerequisite through %s public completion without a provider retry', async mode => {
isProgrammaticIoTaskType.mockReturnValue(false);
const task = { id: TASK.id, taskType: 'internal', status: 'in_progress', metadata: {
isInvestigation: true, totalSpawnCount: 3, failureCount: 1, lastSpawnedAt: '2026-09-10T00:00:00Z',
} };
persistedAgent.taskId = task.id;
persistedAgent.metadata.completionTaskDispatch = { taskId: task.id, taskType: 'internal',
expected: ['claimedBy', 'claimedAt', 'lastSpawnedAt', 'totalSpawnCount'].map(key => [key, task.metadata[key] ?? null]) };
getTaskById.mockResolvedValueOnce(task);
mergedTarget.getOriginInfo.mockResolvedValue({ isGithub: true, host: 'github.com', fullName: 'example/PortOS' });
const github = await import('./github.js');
const git = await import('../lib/execGit.js');
const forge = vi.spyOn(github, 'execGh').mockImplementation(async args => JSON.stringify(args[0] === 'pr'
? { state: 'MERGED', url: 'https://github.com/example/PortOS/pull/123', headRefOid: 'a'.repeat(40), mergeCommit: { oid: 'c'.repeat(40) }, baseRefName: 'main' }
: { defaultBranchRef: { name: 'main' } }));
const gitRead = vi.spyOn(git, 'execGit').mockResolvedValue({ stdout: 'd'.repeat(40), exitCode: 0 });
const taskOutcome = { status: 'blocked', reason: 'Update preflight refuses this active investigation; boot is stale.',
recovery: { mode: 'runtime', prUrl: 'https://github.com/example/PortOS/pull/123', requiredCommit: 'a'.repeat(40) } };
try {
persistedAgent.metadata.taskOutcome = taskOutcome;
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
const order = [];
updateTask.mockImplementationOnce(async () => { order.push('prerequisite'); return {}; });
completeAgent.mockImplementationOnce(async () => { order.push('terminal'); return null; });
// The dispatcher increments counters after the agent receives this snapshot.
const staleTask = { ...task, status: 'pending', metadata: { ...task.metadata, totalSpawnCount: 2, lastSpawnedAt: undefined } };
const result = mode === 'normal'
? await finalizeAgent({ agentId: persistedAgent.id, task: staleTask, success: true, exitCode: 0,
finalSummary: JSON.stringify({ summary: taskOutcome.reason, taskOutcome }) })
: await retireDeadAgent({ agent: persistedAgent, task: staleTask, success: true, exitCode: 0 });
expect(result).toMatchObject({ success: false, taskOutcome });
expect(order).toEqual(['prerequisite', 'terminal']);
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'blocked', metadata: expect.objectContaining({
blockedCategory: 'runtime-verification', failureCount: 1, totalSpawnCount: 3,
runtimeVerification: expect.objectContaining({ taskId: task.id, agentId: persistedAgent.id, integratedCommit: 'c'.repeat(40) }),
}) }), 'internal', expect.objectContaining({ expectedStatus: 'in_progress' }));
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'blocked' }), 'internal', {
expectedStatus: 'in_progress',
expectedTask: { description: task.description, priority: task.priority, metadata: task.metadata },
recoveryOwner: { id: persistedAgent.id, startedAt: persistedAgent.startedAt },
expectedMetadata: { claimedBy: task.metadata.claimedBy, claimedAt: task.metadata.claimedAt,
lastSpawnedAt: task.metadata.lastSpawnedAt, totalSpawnCount: task.metadata.totalSpawnCount },
});
expect(completeAgent).toHaveBeenCalledWith(persistedAgent.id, expect.objectContaining({ success: false, deliveryRecoveryOwned: true }));
expect(resolveFailedTaskUpdate).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
} finally { forge.mockRestore(); gitRead.mockRestore(); }
});
it('stops recovered runtime finalization when its conditional prerequisite write loses ownership', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
const task = { id: TASK.id, taskType: 'internal', status: 'in_progress', metadata: { totalSpawnCount: 1 } };
persistedAgent.taskId = task.id;
persistedAgent.metadata.completionTaskDispatch = { taskId: task.id, taskType: 'internal',
expected: ['claimedBy', 'claimedAt', 'lastSpawnedAt', 'totalSpawnCount'].map(key => [key, task.metadata[key] ?? null]) };
getTaskById.mockResolvedValueOnce(task);
persistedAgent.metadata.taskOutcome = { status: 'blocked', reason: 'The running fix remains unverified.',
recovery: { mode: 'runtime', prUrl: 'https://github.com/example/PortOS/pull/123', requiredCommit: 'a'.repeat(40) } };
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
updateTask.mockResolvedValueOnce({ statusChanged: true });
await expect(retireDeadAgent({ agent: persistedAgent, task,
success: true, exitCode: 0 })).rejects.toThrow('task ownership changed');
expect(completeAgent).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
});
it.each(['worktree', 'pinned-claim'])('hands %s cleanup-only work to completion recovery without another agent or success claim', async mode => {
const taskOutcome = { status: 'incomplete', reason: 'Verified delivery; owner still holds checkout.', recovery: { mode: 'cleanup' } };
isProgrammaticIoTaskType.mockReturnValue(false);
persistedAgent.metadata = mode === 'worktree' ? { isWorktree: true }
: { isWorktree: false, claimPicksOwnBranch: false, claimBranch: 'claim/issue-42', claimBranches: ['claim/issue-42'] };
try {
await finalizeAgent({ agentId: 'agent-example', task: { id: TASK.id, taskType: 'user', metadata: {} },
success: true, exitCode: 0, finalSummary: JSON.stringify({ summary: 'Cleanup handed off.', taskOutcome }) });
expect(updateTask).toHaveBeenLastCalledWith(TASK.id, expect.objectContaining({ status: 'in_progress',
metadata: expect.objectContaining({ deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-example' }) }), 'user');
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ success: false, cleanupPending: true }));
expect(addTask).not.toHaveBeenCalled();
} finally { isProgrammaticIoTaskType.mockReturnValue(true); }
});
it.each(['saved', 'pinned-claim'])('retains a %s cleanup handoff when its run is recovered after a crash', async mode => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'cleanup-restart-'));
isProgrammaticIoTaskType.mockReturnValue(false);
const taskOutcome = { status: 'incomplete', reason: 'Only preservation remains.', recovery: { mode: 'cleanup' } };
const task = { ...TASK, status: 'in_progress', description: 'Preserve the delivered checkout.', priority: 'MEDIUM', metadata: { ...TASK.metadata, ...(mode === 'saved'
? { deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-example' } : {}) } };
persistedAgent.metadata = { workspacePath, ...(mode === 'saved' ? { isWorktree: true }
: { isWorktree: false, claimPicksOwnBranch: false, claimBranch: 'claim/issue-42', claimBranches: ['claim/issue-42'] }) };
try {
await writeFile(join(workspacePath, '.agent-done-agent-example'), JSON.stringify({ taskOutcome }));
await retireDeadAgent({ agent: persistedAgent, task, success: mode === 'pinned-claim', exitCode: mode === 'pinned-claim' ? 0 : 1, duration: 1000 });
expect(updateTask).toHaveBeenLastCalledWith(TASK.id, expect.objectContaining({ status: 'in_progress',
metadata: expect.objectContaining({ deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: 'agent-example' }) }), TASK.taskType, {
expectedStatus: 'in_progress',
expectedTask: { description: task.description, priority: task.priority, metadata: task.metadata },
recoveryOwner: { id: 'agent-example', startedAt: '2026-09-10T00:00:00Z' },
});
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ success: false, cleanupPending: true }));
} finally {
isProgrammaticIoTaskType.mockReturnValue(true);
await rm(workspacePath, { recursive: true, force: true });
}
});
it('stops repeated delivery recovery at the existing budget with concrete choices', async () => {
const taskOutcome = { status: 'incomplete', reason: 'Validation remains red.' };
await finalizeAgent({ agentId: 'agent-example', task: { ...TASK, metadata: { ...TASK.metadata, failureCount: MAX_TASK_RETRIES - 1 } },
success: true, exitCode: 0, finalSummary: JSON.stringify({ summary: 'Retained failed work.', taskOutcome }) });
expect(updateTask).toHaveBeenLastCalledWith(TASK.id, expect.objectContaining({ status: 'blocked',
metadata: expect.objectContaining({ blockedCategory: 'task-recovery-exhausted',
blockedReason: expect.stringContaining('Options:') }) }), TASK.taskType);
expect(addTask).not.toHaveBeenCalled();
});
it.each(['normal', 'restart'].flatMap(mode => ['not-planned', 'operator-closed'].map(disposition => [mode, disposition])))
('settles a selected claim no-op during %s completion from a verified %s disposition', async (mode, disposition) => {
isProgrammaticIoTaskType.mockReturnValue(false);
const task = { id: 'claim-example', taskType: 'user', metadata: { app: 'app-example', claimFlow: true, claimTarget: '42' } };
const taskOutcome = { status: 'no-action-needed', reason: 'Selected issue no longer requires a change.' };
const claimDisposition = { status: 'verified', taskId: task.id, issues: [{ issue: 42, disposition }] };
persistedAgent.taskId = task.id;
persistedAgent.metadata.taskOutcome = taskOutcome;
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
claimVerifier.verifyClaimDisposition.mockResolvedValue(claimDisposition);
try {
if (mode === 'normal') await finalizeAgent({ agentId: persistedAgent.id, task, success: true, exitCode: 0,
finalSummary: JSON.stringify({ summary: 'Claim stood down.', taskOutcome }) });
else await retireDeadAgent({ agent: persistedAgent, task, success: true, exitCode: 0, duration: 100 });
expect(claimVerifier.verifyClaimDisposition).toHaveBeenLastCalledWith(expect.objectContaining({ task,
agent: expect.objectContaining({ id: persistedAgent.id, taskId: task.id }), reportedOutcome: taskOutcome, success: true }));
expect(completeAgent).toHaveBeenLastCalledWith(persistedAgent.id, expect.objectContaining({ success: true,
validationPassed: true, taskOutcome, claimDisposition }));
expect(hook).not.toHaveBeenCalled();
expect(addTask).not.toHaveBeenCalled();
if (mode === 'normal') expect(updateTask).toHaveBeenLastCalledWith(task.id,
expect.objectContaining({ status: 'completed', metadata: expect.objectContaining({ taskOutcome }) }), task.taskType);
} finally { isProgrammaticIoTaskType.mockReturnValue(true); }
});
it.each(['normal', 'restart'])('keeps an unreadable tracker unverified during %s completion even with a saved validation pass', async mode => {
isProgrammaticIoTaskType.mockReturnValue(false);
const task = { id: 'claim-example', taskType: 'user', metadata: { app: 'app-example', claimFlow: true, claimTarget: '42' } };
const taskOutcome = { status: 'no-action-needed', reason: 'Agent says done.' };
persistedAgent.taskId = task.id;
persistedAgent.result = { validationPassed: true };
persistedAgent.metadata.taskOutcome = taskOutcome;
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
claimVerifier.verifyClaimDisposition.mockRejectedValue(new Error('Invented forge outage'));
try {
if (mode === 'normal') await finalizeAgent({ agentId: persistedAgent.id, task, success: true, exitCode: 0,
finalSummary: JSON.stringify({ summary: 'Claim stood down.', taskOutcome }) });
else await retireDeadAgent({ agent: persistedAgent, task, success: true, exitCode: 0, duration: 100 });
expect(completeAgent).toHaveBeenLastCalledWith(persistedAgent.id, expect.objectContaining({ success: false,
validationPassed: null, taskOutcome: { status: 'incomplete', reason: 'The reported no-action-needed result was not verified.' },
claimDisposition: { status: 'unverified', reason: 'tracker-unavailable' } }));
} finally { isProgrammaticIoTaskType.mockReturnValue(true); }
});
it('preserves a failed delivery gate during claim no-op recovery', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
const task = { id: 'claim-example', taskType: 'user', metadata: { claimFlow: true, claimTarget: '42' } };
persistedAgent.taskId = task.id;
persistedAgent.result = { validationPassed: false };
persistedAgent.metadata.taskOutcome = { status: 'no-action-needed', reason: 'Issue was closed.' };
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
claimVerifier.verifyClaimDisposition.mockResolvedValue({ status: 'verified' });
try {
await retireDeadAgent({ agent: persistedAgent, task, success: true, exitCode: 0, duration: 100 });
expect(completeAgent).toHaveBeenLastCalledWith(persistedAgent.id, expect.objectContaining({ success: false,
validationPassed: false, taskOutcome: { status: 'incomplete', reason: 'Delivery checks did not pass.' } }));
} finally { isProgrammaticIoTaskType.mockReturnValue(true); }
});
it('accepts a coordinator no-op whose commit criterion was never declared', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
declaresNoCommitCriterion.mockReturnValue(true);
const taskOutcome = { status: 'no-action-needed', reason: 'Inventory was already drained.' };
const task = { id: 'reconcile-example', taskType: 'internal', metadata: { analysisType: 'branch-reconcile', app: 'app-example' } };
try {
await finalizeAgent({ agentId: 'agent-example', task, success: true, exitCode: 0, outputBuffer: '',
finalSummary: JSON.stringify({ summary: 'Nothing left to reconcile.', taskOutcome }) });
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({
success: true, executionSuccess: true, validationPassed: null, taskOutcome,
}));
expect(updateTask).toHaveBeenLastCalledWith(task.id, expect.objectContaining({
status: 'completed', metadata: expect.objectContaining({ taskOutcome }),
}), 'internal');
expect(addTask).not.toHaveBeenCalled();
} finally {
isProgrammaticIoTaskType.mockReturnValue(true);
declaresNoCommitCriterion.mockReturnValue(false);
}
});
it('keeps a failed delivery gate ahead of a coordinator no-op', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
declaresNoCommitCriterion.mockReturnValue(true);
const task = { id: 'reconcile-example', taskType: 'internal', metadata: { analysisType: 'branch-reconcile' } };
persistedAgent.taskId = task.id;
persistedAgent.result = { validationPassed: false };
persistedAgent.metadata.taskOutcome = { status: 'no-action-needed', reason: 'Inventory was already drained.' };
persistedAgent.metadata.taskOutcomeSource = 'terminal-result';
try {
await retireDeadAgent({ agent: persistedAgent, task, success: true, exitCode: 0, duration: 100 });
expect(completeAgent).toHaveBeenLastCalledWith(persistedAgent.id, expect.objectContaining({
success: false, validationPassed: false,
taskOutcome: { status: 'incomplete', reason: 'Delivery checks did not pass.' },
}));
} finally {
isProgrammaticIoTaskType.mockReturnValue(true);
declaresNoCommitCriterion.mockReturnValue(false);
}
});
it('holds an unverified no-op', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
try {
const task = { id: 'user-example', taskType: 'user', metadata: {} };
await finalizeAgent({ agentId: 'agent-example', task, success: true, exitCode: 0, outputBuffer: '',
finalSummary: JSON.stringify({ summary: 'Invented no-op.', taskOutcome: { status: 'no-action-needed', reason: 'No changes made.' } }) });
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ executionSuccess: true, success: false,
taskOutcome: { status: 'incomplete', reason: 'The reported no-action-needed result was not verified.' } }));
} finally {
isProgrammaticIoTaskType.mockReturnValue(true);
}
});
it('leaves legacy prose as unknown delivery when the agent has no saved outcome', async () => {
isProgrammaticIoTaskType.mockReturnValue(false);
try {
const task = { id: 'user-example', taskType: 'user', metadata: {} };
await finalizeAgent({ agentId: 'agent-example', task, success: true, exitCode: 0, outputBuffer: '',
finalSummary: 'Status: BLOCKED - invented contradictory instructions' });
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ executionSuccess: true, taskOutcome: null }));
} finally {
isProgrammaticIoTaskType.mockReturnValue(true);
}
});
it('replays verified no-op recovery after terminal persistence fails without repeating its hook', async () => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'verified-noop-replay-'));
const taskOutcome = { status: 'no-action-needed', reason: 'Invented verified no-op.' };
persistedAgent.metadata.workspacePath = workspacePath;
hook.mockResolvedValue({ accepted: true });
completeAgent.mockRejectedValueOnce(new Error('invented persistence failure'));
const finish = () => retireDeadAgent({ agent: persistedAgent, task: TASK, success: true, exitCode: 0, duration: 1000 });
try {
await writeFile(join(workspacePath, '.agent-done-agent-example'), JSON.stringify({ taskOutcome }));
await expect(finish()).rejects.toThrow('invented persistence failure');
await expect(finish()).resolves.toEqual({ success: true, taskOutcome, deliveryHeld: false });
expect(hook).toHaveBeenCalledOnce();
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ success: true, validationPassed: true, taskOutcome }));
} finally { await rm(workspacePath, { recursive: true, force: true }); }
});
it.each([null, 'Invented terminal report.'])('retains an outcome-only sentinel on repeat finalization after cleanup with finalSummary=%s', async finalSummary => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'outcome-replay-'));
const sentinelPath = join(workspacePath, '.agent-done-agent-example');
const taskOutcome = { status: 'blocked', reason: 'Invented prerequisite remains unmet.' };
const finish = (finalSummary = null) => finalizeAgent({ agentId: 'agent-example', task: TASK, success: true,
exitCode: 0, duration: 1000, workspacePath, finalSummary, outputBuffer: '' });
try {
await writeFile(sentinelPath, JSON.stringify({ taskOutcome }));
await finish();
await rm(sentinelPath);
await finish(finalSummary);
expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ success: false, executionSuccess: true, taskOutcome }));
expect(updateTask).toHaveBeenLastCalledWith(TASK.id, expect.objectContaining({ status: 'in_progress', metadata: expect.objectContaining({ taskOutcome }) }), TASK.taskType);
expect(persistedAgent.metadata.taskSummary).toBe(finalSummary);
} finally { await rm(workspacePath, { recursive: true, force: true }); }
});
it.each(['sentinel', 'terminal-result', 'legacy'])('retains only authoritative %s summaries on repeat finalization after cleanup', async (source) => {
const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
const { tmpdir } = await import('node:os');
const workspacePath = await mkdtemp(join(tmpdir(), 'completion-replay-'));
const sentinelPath = join(workspacePath, '.agent-done-summary-replay');
persistedAgent.id = 'summary-replay';
const task = { ...TASK, metadata: { ...TASK.metadata, auditDepth: 'deep' } };
const finish = (finalSummary = null) => finalizeAgent({ agentId: 'summary-replay', task, success: true,
exitCode: 0, duration: 1000, workspacePath, finalSummary, outputBuffer: 'exec: tool output' });
try {
if (source === 'legacy') {
persistedAgent.metadata.taskSummary = 'Old heuristic tool transcript';
} else {
if (source === 'sentinel') await writeFile(sentinelPath, 'Saved partial completion.');
await finish(source === 'terminal-result' ? 'Saved partial completion.' : null);
expect(persistedAgent.metadata).toMatchObject({ taskSummary: 'Saved partial completion.', taskSummarySource: source });
await rm(sentinelPath, { force: true });
}
await finish();
expect(persistedAgent.metadata.taskSummary).toBe(source === 'legacy' ? null : 'Saved partial completion.');
expect(persistedAgent.metadata.taskSummarySource).toBe(source === 'legacy' ? null : source);
} finally {
await rm(workspacePath, { recursive: true, force: true });
}
});
it('finishes extended Deep with an honest partial summary through ordinary completion without ledger gates', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security', auditDepth: 'deep', auditWorkflow: 'extended-v1', simplify: false } };
recordAuditQuality.mockResolvedValue(true);
await finalizeAgent({ agentId: 'extended-summary', task, success: true, exitCode: 0, duration: 1000,
workspacePath: '/example/repo', finalSummary: 'Investigated high-risk paths and fixed two coherent defects. Coverage remains partial.', outputBuffer: 'tool transcript' });
expect(deep.checkpointDeepAudit).not.toHaveBeenCalled();
expect(deep.settleDeepAuditDelivery).not.toHaveBeenCalled();
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'completed', metadata: expect.objectContaining({ taskOutcome: null }) }), expect.anything());
expect(persistedAgent.metadata.taskSummary).toContain('Coverage remains partial');
expect(persistedAgent.metadata.taskSummarySource).toBe('terminal-result');
});
it('parks a failed Deep attempt without the normal automatic retry path', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security', auditDepth: 'deep' } };
await finalizeAgent({ agentId: 'deep-failed', task, success: false, exitCode: 1, duration: 1000,
workspacePath: '/example/repo', startedAt: Date.now() - 1000, outputBuffer: 'Context exhausted',
errorAnalysis: { type: 'transient', retryable: true, error: 'context exhausted' } });
expect(resolveFailedTaskUpdate).not.toHaveBeenCalled();
expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'in_progress', metadata: expect.objectContaining({ retryPendingCleanup: expect.any(String) }) }), expect.anything());
expect(deep.checkpointDeepAudit).toHaveBeenCalledWith(expect.objectContaining({ success: false }));
});
it('distinguishes a clean execution with no usable assessment from a failed execution', async () => {
const task = { ...TASK, metadata: { ...TASK.metadata, analysisType: 'security' } };
recordAuditQuality.mockResolvedValue(false);
await expect(dispatchTaskOutputHookOnce({ agentId: 'audit-no-report', task, success: true, workspacePath: '/worktree' }))
.resolves.toEqual({ ran: false, auditAssessment: { status: 'not-recorded' } });
await expect(dispatchTaskOutputHookOnce({ agentId: 'audit-execution-failed', task, success: false, workspacePath: '/worktree' }))
.resolves.toEqual({ ran: false, auditAssessment: { status: 'not-attempted' } });
recordAuditQuality.mockResolvedValue(true);
});
it.each([
['orphan cleanup', false],
['post-restart completion', true],
])('runs a registered processTaskOutput hook for %s with no stale sentinel payload', async (_path, success) => {
const result = await dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success,
});
expect(result).toEqual({ ran: true, outcome: { recorded: true } });
expect(hook).toHaveBeenCalledOnce();
expect(hook).toHaveBeenCalledWith(expect.objectContaining({
agentId: persistedAgent.id,
task: TASK,
appId: 'app-example',
success,
payload: null,
workspacePath: null,
}));
expect(updateAgent).toHaveBeenCalledWith(
persistedAgent.id,
{ metadata: { outputHookDispatchedAt: expect.any(String), outputHookValidationPassed: expect.any(Boolean) } },
);
});
it('deduplicates concurrent normal/recovery completion and persists the gate', async () => {
let finishHook;
hook.mockReturnValueOnce(new Promise(resolve => { finishHook = resolve; }));
const normal = dispatchTaskOutputHookOnce({
agentId: persistedAgent.id,
task: TASK,
success: true,
workspacePath: '/example/worktree',
});
const recovery = dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: false,
});
expect(recovery).toBe(normal);
await vi.waitFor(() => expect(hook).toHaveBeenCalledOnce());
finishHook({ recorded: true });
await expect(normal).resolves.toEqual({ ran: true, outcome: { recorded: true } });
await expect(dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: false,
})).resolves.toMatchObject({ ran: false, alreadyDispatched: true });
expect(hook).toHaveBeenCalledOnce();
});
it('keeps a timed-out hook recoverable until the original dispatch settles', async () => {
vi.useFakeTimers();
let finishHook;
hook.mockReturnValueOnce(new Promise(resolve => { finishHook = resolve; }));
const original = dispatchTaskOutputHookOnce({
agentId: persistedAgent.id,
task: TASK,
success: true,
});
await vi.advanceTimersByTimeAsync(5 * 60_000);
await expect(original).resolves.toEqual({ ran: false, timedOut: true });
expect(updateAgent).not.toHaveBeenCalled();
expect(dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: false,
})).toBe(original);
finishHook({ recorded: true });
await vi.waitFor(() => expect(updateAgent).toHaveBeenCalledWith(
persistedAgent.id,
{ metadata: { outputHookDispatchedAt: expect.any(String), outputHookValidationPassed: expect.any(Boolean) } },
));
vi.useRealTimers();
await expect(dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: false,
})).resolves.toMatchObject({ ran: false, alreadyDispatched: true });
expect(hook).toHaveBeenCalledOnce();
});
it('does not dispatch after finalizeAgent persisted the explicit hook marker', async () => {
persistedAgent.metadata.outputHookDispatchedAt = new Date().toISOString();
await expect(dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: false,
})).resolves.toMatchObject({ ran: false, alreadyDispatched: true });
expect(hook).not.toHaveBeenCalled();
});
it('still dispatches for an agent completed early by terminate/kill before finalizeAgent', async () => {
persistedAgent.status = 'completed';
await expect(dispatchTaskOutputHookOnce({
agentId: persistedAgent.id,
task: TASK,
success: false,
})).resolves.toEqual({ ran: true, outcome: { recorded: true } });
expect(hook).toHaveBeenCalledOnce();
});
it('does not persist a dispatch marker when recovery has no registered hook', async () => {
getTaskOutputHook.mockResolvedValueOnce(null);
await expect(dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: false,
})).resolves.toEqual({ ran: false });
expect(updateAgent).not.toHaveBeenCalled();
});
it('does not invoke a payload-dependent hook when recovery cannot read a sentinel', async () => {
canRunTaskOutputHookWithoutPayload.mockReturnValueOnce(false);
await expect(dispatchRecoveredTaskOutputHook({
agentId: persistedAgent.id,
task: TASK,
success: true,
})).resolves.toEqual({ ran: false, recoveryPayloadUnavailable: true });
expect(hook).not.toHaveBeenCalled();
expect(updateAgent).not.toHaveBeenCalled();
});
it('reads a live completion from task.metadata.repoPath but denies a recovery run that fallback', async () => {
await dispatchTaskOutputHookOnce({ agentId: 'agent-live', task: TASK, success: true });
expect(hook).toHaveBeenCalledWith(expect.objectContaining({ workspacePath: '/example/repo' }));
persistedAgent.metadata = {};
canRunTaskOutputHookWithoutPayload.mockReturnValueOnce(false);
await expect(dispatchRecoveredTaskOutputHook({ agentId: 'agent-recovered', task: TASK, success: true }))
.resolves.toEqual({ ran: false, recoveryPayloadUnavailable: true });
expect(hook).toHaveBeenCalledOnce();
});
});
describe('recovery path wiring (#3182, #8440)', () => {
// Both recovery paths (the orphan sweep in agentManagement.js and post-restart
// recovery in agentLifecycle.js) call the shared `retireDeadAgent` (#8440) for
// this step list now, so the ordering guard moved to pin ITS body instead of
// each caller's inlined copy.
it('both recovery paths retire through the shared retireDeadAgent', () => {
const sweepStart = MANAGEMENT_SOURCE.indexOf('async function runCleanupOrphanedAgents');
const sweepBody = MANAGEMENT_SOURCE.slice(sweepStart, sweepStart + 12_000);
expect(sweepBody).toMatch(/await retireDeadAgent\(/);
const recoveryStart = LIFECYCLE_SOURCE.indexOf('Completing untracked agent');
const recoveryBody = LIFECYCLE_SOURCE.slice(recoveryStart, recoveryStart + 2_000);
expect(recoveryBody).toMatch(/await retireDeadAgent\(/);
});
});
// #6124: the escalation the old `hookRejected && success` guard could not reach.
// The pr-reviewer stage that produced no output exited NON-zero with no captured
// error, so the run was already `success === false` and the permanent verdict
// never applied — the task consumed its retries and the pipeline re-spawned.
describe('permanent output-hook rejection (#6124)', () => {
beforeEach(() => {
vi.clearAllMocks();
getAgent.mockResolvedValue({ id: 'agent-rejected', metadata: {} });
updateAgent.mockResolvedValue(null);
getTaskOutputHook.mockResolvedValue(async () => ({
accepted: false, permanent: true, reason: 'output-missing', message: 'No parseable output',
}));
});
const finish = (errorAnalysis, metadata = {}) => finalizeAgent({
agentId: 'agent-rejected',
task: { ...TASK, metadata: { ...TASK.metadata, ...metadata } },
runId: 'run-rejected', success: false, exitCode: 1, duration: 1000,
outputBuffer: '', errorAnalysis,
});
it('blocks an already-failed unknown run and records failure for cleanup and run history', async () => {
expect(await finish({ category: 'unknown' })).toMatchObject({ success: false });
expect(updateTask).toHaveBeenCalledWith(TASK.id, expect.objectContaining({
status: 'blocked', metadata: expect.objectContaining({ blockedCategory: 'output-missing' }),
}), 'internal');
expect(completeAgent).toHaveBeenCalledWith('agent-rejected', expect.objectContaining({
success: false, completionReason: 'output-missing', error: 'No parseable output',
errorAnalysis: expect.objectContaining({ permanent: true, origin: 'task-output-hook' }),
}));
expect(completeAgentRun).toHaveBeenCalledWith('run-rejected', '', 1, 1000,
expect.objectContaining({ category: 'output-missing', permanent: true }), false, expect.objectContaining({ executionSuccess: false, taskOutcome: { status: 'incomplete', reason: 'Delivery checks did not pass.' } }));
expect(addTask).not.toHaveBeenCalled();
// The task's retry decision is resolved once, against the final verdict —
// not once for the run's own failure and again for the escalation (#9645).
expect(resolveFailedTaskUpdate).toHaveBeenCalledTimes(1);
});
it('leaves a named failure on its ordinary retry path', async () => {
await finish({ category: 'rate-limit', message: 'Try later' });
expect(updateTask).toHaveBeenCalledWith(TASK.id, expect.objectContaining({
status: 'in_progress', metadata: expect.objectContaining({ lastErrorCategory: 'rate-limit' }),
}), 'internal');
expect(completeAgent).toHaveBeenCalledWith('agent-rejected', expect.objectContaining({
error: 'Try later', completionReason: 'rate-limit',
errorAnalysis: { category: 'rate-limit', message: 'Try later' },
}));
expect(resolveFailedTaskUpdate).toHaveBeenCalledTimes(1);
});
it('does not re-resolve an already-blocked task or duplicate its investigation', async () => {
await finish({ category: 'unknown' }, { failureCount: MAX_TASK_RETRIES - 1 });
expect(updateTask).toHaveBeenCalledWith(TASK.id, expect.objectContaining({ status: 'blocked' }), 'internal');
expect(resolveFailedTaskUpdate).toHaveBeenCalledTimes(1);
expect(addTask).toHaveBeenCalledTimes(1);
});
});