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: bound completion replay storage and settle cleanup stages

[._.]/ Adam Eivy64033490eec5
diff --cc server/services/agentCompletionCleanup.js
index e7e22a659c,4fba114620..60415d3db4
--- a/server/services/agentCompletionCleanup.js
+++ b/server/services/agentCompletionCleanup.js
@@@ -1,3 -1,3 +1,5 @@@
++import { createHash } from 'node:crypto';
++import { storeCompletionData, readCompletionData, completionReplayInput } from './agentCompletionData.js';
/**
* Agent Completion Cleanup
*
@@@ -343,114 -344,39 +345,133 @@@ export async function runAgentCompletio
* entry point from its own source of truth.
*/
async function runCompletionCleanupSteps(context, { onStepError }) {
- const onFailure = STEP_FAILURE_HANDLERS[onStepError];
- if (!onFailure) throw new Error(`Unknown completion-cleanup step error policy: ${onStepError}`);
- const runStep = (name, step) => step().catch(err => onFailure(err, name, context));
- await runStep('JIRA hand-off', () => completeJiraHandOff(context));
- await runStep('Plan question notification', () => notifyPlanQuestionIfNeeded(context));
- await runStep('Pipeline progression', () => handlePipelineProgression(context.task, context.agentId, context.effectiveSuccess));
- await runStep('Creative Director completion', () => advanceCreativeDirectorIfNeeded(context));
+ if (!Object.values(STEP_ERROR_POLICY).includes(onStepError)) throw new Error(`Unknown completion-cleanup step error policy: ${onStepError}`);
+ if (cleanupRuns.has(context.agentId)) return cleanupRuns.get(context.agentId);
+ const run = performCompletionCleanupSteps(context, onStepError);
+ cleanupRuns.set(context.agentId, run);
+ try { return await run; } finally { cleanupRuns.delete(context.agentId); }
+}
+
+async function performCompletionCleanupSteps(context, onStepError) {
+ const state = context.agentState;
+ const durable = state?.status === 'completed' && typeof state.startedAt === 'string';
++ if (durable && ['completed', 'failed', 'abandoned'].includes(state.metadata?.completionCleanup?.status)) return;
+ const stages = { ...state?.metadata?.completionCleanup?.stages };
+ const { recordCompletionCleanup } = durable ? await import('./cosAgentLifecycle.js') : {};
+ const persist = async patch => {
+ if (durable && !await recordCompletionCleanup(context.agentId, state.startedAt, patch)) throw new Error('completion-cleanup-write-unverified');
+ };
+ // A crash after terminal ingestion but before any step leaves this exact
+ // continuation on disk. Replays do not rerun completed external side effects.
- await persist({ version: 1, status: 'pending', startedAt: state?.startedAt,
- context: state?.metadata?.completionCleanup?.context || {
- task: context.task, effectiveSuccess: context.effectiveSuccess, prOwnership: context.prOwnership,
- prClaimVerified: context.prClaimVerified, branchProvenEmpty: context.branchProvenEmpty, outputBuffer: context.outputBuffer,
- } });
++ const priorReplay = state?.metadata?.completionCleanup?.replay;
++ const replayInput = durable && priorReplay ? await readCompletionData(state, priorReplay)
++ : state?.metadata?.completionCleanup?.context || completionReplayInput(context);
++ const replay = durable ? priorReplay || await storeCompletionData(state, 'replay', replayInput) : undefined;
++ context = { ...context, ...replayInput };
++ await persist({ version: 1, status: 'pending', startedAt: state?.startedAt, replay, context: undefined });
+ let firstError;
+ const runStep = async (key, name, step, retryable = false) => {
+ const prior = stages[key];
+ if (prior?.status === 'done') return prior.value;
- if (prior && !retryable) return; // An uncertain external hand-off needs its owning service's evidence.
++ if (prior && !retryable) {
++ if (prior.status === 'running') {
++ stages[key] = { ...prior, status: 'abandoned', reason: 'external-handoff-unverified' };
++ await persist({ stages: { [key]: stages[key] } });
++ }
++ return; // Unknown external effects are terminal here, never republished.
++ }
+ try {
+ stages[key] = { status: 'running', retryable };
+ await persist({ stages: { [key]: stages[key] } });
+ const value = await step();
+ const held = (key === 'worktree' && Array.isArray(value) && value.length > 0)
+ || (key === 'sentinel' && auditEvidencePending(context));
+ stages[key] = { status: held ? 'held' : 'done', retryable: false, ...(value !== undefined && { value }) };
+ await persist({ stages: { [key]: stages[key] } });
+ return value;
+ } catch (err) {
+ const deferred = ['checkout-capture-pending', 'checkout-retirement-pending',
+ 'completion-sentinel-generation-pending', 'completion-sentinel-generation-changed'].includes(err.message);
+ if (!deferred) firstError ||= err;
+ stages[key] = { status: deferred ? 'held' : 'failed', retryable: deferred || retryable, reason: err.message };
+ await persist({ stages: { [key]: stages[key] } }).catch(() => {});
+ emitLog(deferred ? 'info' : 'warn', `${name} ${deferred ? 'deferred' : 'failed'} for ${context.agentId}: ${err.message}`,
+ { agentId: context.agentId, taskId: context.task?.id });
+ }
+ };
+ // Durable ingestion and its continuation are sufficient to acknowledge this
+ // exact signal. An unrelated hand-off failure must not leave it as Git dirt.
+ if (['completed', 'failed'].includes(state?.status)) {
+ await runStep('sentinel', 'Completion sentinel removal', () => removeCompletionSentinel(context), true);
+ }
- const deliveryContext = { ...context,
- effectiveSuccess: state?.metadata?.completionCleanup?.context?.effectiveSuccess ?? context.effectiveSuccess };
++ const deliveryContext = context;
+ await runStep('jira', 'JIRA hand-off', () => {
+ if (context.task?.metadata?.jiraTicketId && state?.metadata?.checkoutCapture?.status === 'pending') throw new Error('checkout-capture-pending');
+ return completeJiraHandOff(deliveryContext);
+ }, stages.jira?.reason === 'checkout-capture-pending');
+ await runStep('notification', 'Plan question notification', () => notifyPlanQuestionIfNeeded(context));
+ const waitForRepository = () => {
+ if (state?.metadata?.checkoutCapture?.status === 'pending') throw new Error('checkout-capture-pending');
+ if (state?.result?.cleanupPending === true
+ && (state.metadata?.repoStateVerification?.status !== 'completed'
+ || state.metadata?.completionCleanup?.stages?.worktree?.verifiedBy !== 'repository-preservation-receipt')) throw new Error('checkout-retirement-pending');
+ };
+ await runStep('pipeline', 'Pipeline progression', () => {
+ if (context.task?.metadata?.pipeline?.status === 'running') waitForRepository();
+ return handlePipelineProgression(context.task, context.agentId, deliveryContext.effectiveSuccess);
+ }, ['checkout-capture-pending', 'checkout-retirement-pending'].includes(stages.pipeline?.reason));
+ await runStep('creative', 'Creative Director completion', () => {
+ if (context.task?.metadata?.creativeDirector) waitForRepository();
+ return advanceCreativeDirectorIfNeeded(deliveryContext);
+ }, ['checkout-capture-pending', 'checkout-retirement-pending'].includes(stages.creative?.reason));
// A terminal rejection is not proof that its audit artifacts were consumed.
// Keep the checkout and original signal available for explicit recovery.
const preserveAuditEvidence = auditEvidencePending(context);
if (preserveAuditEvidence) {
emitLog('warn', `Audit disposition incomplete for ${context.agentId}; preserving worktree and completion evidence`, { agentId: context.agentId });
}
- const cleanupWarnings = preserveAuditEvidence ? [] : await runStep('Worktree cleanup', () => completeWorktreeCleanup(context));
- await runStep('Cleanup warning reporting', () => reportWorktreeCleanupWarnings({ ...context, cleanupWarnings }));
- // Last, and never fatal under either policy: a janitorial `rm` that hits EPERM
- // must not be able to abort the worktree cleanup and pipeline hand-off above.
- //
- // Gated on the record actually reaching an outcome. `finalizeAgent` runs
- // `persistCompletionSummary` and `resolveFailedTaskUpdate` BEFORE it
- // dispatches the output hook and calls `completeAgent`; a throw in either
- // leaves the record `running`, and the orphan sweep's recovery hook is then
- // what salvages the run — for a programmatic-I/O type the sentinel IS the
- // deliverable it reads (an LI proposal, an issue-filing payload). Both
- // spawners run this from a `finally`, so they reach here on exactly that
- // path. An unreadable record counts as not-over: leaving the file for the
- // stale sweep is the recoverable direction, destroying a deliverable is not.
- // `failed` is an outcome too: left behind in a preserved worktree, the sentinel
- // reads as uncommitted work and blocks every later merged-worktree cleanup.
- if (['completed', 'failed'].includes(context.agentState?.status)) {
- await removeCompletionSentinel(context)
- .catch(err => emitLog('warn', `Completion sentinel removal failed for ${context.agentId}: ${err.message}`, { agentId: context.agentId }));
+ const cleanupWarnings = preserveAuditEvidence ? [] : await runStep('worktree', 'Worktree cleanup', async () => {
+ if (state?.metadata?.checkoutCapture?.status === 'pending') throw new Error('checkout-capture-pending');
+ if (await completionSentinelPresent(context.agentId, state?.metadata?.workspacePath)) throw new Error('completion-sentinel-generation-pending');
+ return completeWorktreeCleanup(context);
+ },
+ !stages.worktree || stages.worktree.retryable === true);
+ if (['done', 'held'].includes(stages.worktree?.status)) {
+ await runStep('report', 'Cleanup warning reporting', () => reportWorktreeCleanupWarnings({ ...context, cleanupWarnings }));
+ }
- await persist({ status: Object.values(stages).every(stage => stage.status === 'done') && !preserveAuditEvidence ? 'completed' : 'pending' });
++ const unfinished = preserveAuditEvidence || Object.values(stages).some(stage => stage.status === 'held'
++ || (stage.status === 'failed' && stage.retryable) || stage.status === 'running');
++ const failed = Object.values(stages).some(stage => ['failed', 'abandoned'].includes(stage.status));
++ await persist({ status: unfinished ? 'pending' : failed ? 'failed' : 'completed' });
+ if (firstError && onStepError === STEP_ERROR_POLICY.PROPAGATE) throw firstError;
+}
+
+/** Late completion callbacks replay only durable unfinished cleanup, never the
+ * provider result, output hook, task verdict or a completed external hand-off.
+ */
+export async function replayAgentCompletionCleanup(agentState) {
+ const receipt = agentState?.metadata?.completionCleanup;
- if (agentState?.status !== 'completed' || receipt?.version !== 1 || receipt.status === 'completed') return;
- const saved = receipt.context;
- if (!saved || receipt.startedAt !== agentState.startedAt || saved.task?.id !== agentState.taskId) return;
++ if (agentState?.status !== 'completed' || receipt?.version !== 1 || receipt.status !== 'pending') return;
++ const { recordCompletionCleanup } = await import('./cosAgentLifecycle.js');
++ let saved;
++ try { saved = receipt.replay ? await readCompletionData(agentState, receipt.replay) : receipt.context; }
++ catch {
++ await recordCompletionCleanup(agentState.id, agentState.startedAt, { reason: 'completion-replay-unavailable' });
++ return;
++ }
++ if (!saved || receipt.startedAt !== agentState.startedAt || saved.task?.id !== agentState.taskId) {
++ await recordCompletionCleanup(agentState.id, agentState.startedAt, { status: 'abandoned', reason: 'completion-context-unavailable' });
++ return;
+ }
+ if (agentState.metadata.checkoutCapture?.status === 'pending') {
+ const lifecycle = await import('./cosAgentLifecycle.js');
+ if (await lifecycle.retryCompletionCheckoutCapture(agentState.id).catch(() => false)) {
+ agentState = await lifecycle.getAgentRecord(agentState.id);
+ }
+ }
+ return runCompletionCleanupSteps({ ...saved,
+ prOwnership: saved.prOwnership || resolveRunnerPrOwnership({ task: saved.task, agent: {}, agentState }),
+ agentId: agentState.id, agentState }, { onStepError: STEP_ERROR_POLICY.LOG_AND_CONTINUE });
}
function resolveRunnerPrOwnership({ task, agent, agentState }) {
@@@ -633,11 -562,8 +654,18 @@@ export async function removeCompletionS
if (typeof agentId !== 'string' || doneSentinelName(agentId) === DONE_SENTINEL_NAME) return;
const workspace = agentState?.metadata?.workspacePath || agent?.workspacePath || null;
if (!workspace) return;
- // `rmGuarded`, like the stale-sentinel sweep that deletes these same files.
- await rmGuarded(resolveDoneSentinelPath(workspace, agentId), { force: true });
+ const receipt = agentState?.metadata?.completionSentinel;
+ // No sentinel is harmless. An occupied marker without ingestion evidence is
+ // not acknowledged, even for a completed record predating this protocol.
+ if (!receipt && !await tryReadFile(resolveDoneSentinelPath(workspace, agentId))) return;
++ const payload = agentState?.metadata?.completionSentinelData;
++ if (payload) {
++ const contents = await readCompletionData(agentState, payload);
++ if (typeof contents !== 'string' || createHash('sha256').update(contents).digest('hex') !== receipt?.sha256) {
++ throw new Error('completion-ingestion-data-unverified');
++ }
++ }
+ await acknowledgeCompletionSentinel({ agentId, workspace, receipt });
}
async function completeWorktreeCleanup({ agentId, task, effectiveSuccess, prOwnership, outputBuffer, prClaimVerified, branchProvenEmpty }) {
diff --cc server/services/agentCompletionCleanup.replay.test.js
index 01ea709383,0000000000..85bf0daf56
mode 100644,000000..100644
--- a/server/services/agentCompletionCleanup.replay.test.js
+++ b/server/services/agentCompletionCleanup.replay.test.js
@@@ -1,188 -1,0 +1,212 @@@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, readFile, rm, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { materializeGitRepo } from '../lib/gitTestRepo.js';
+import { execGit } from '../lib/execGit.js';
+
- const fixture = vi.hoisted(() => ({ recordPath: null, failWrite: false }));
++const fixture = vi.hoisted(() => ({ recordPath: null, runRoot: null, failWrite: false }));
++vi.mock('./cosAgentIndex.js', () => ({ getAgentDir: id => join(fixture.runRoot, id) }));
+vi.mock('./cos.js', () => ({}));
+vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn() }));
+vi.mock('./cosTaskStore.js', () => ({ updateTask: vi.fn(async () => ({})), addTask: vi.fn(), reviveBlockedTask: vi.fn() }));
+vi.mock('./cosTaskGenerator.js', () => ({ checkStagePrecondition: () => ({ passed: true }) }));
+vi.mock('./cosAgentLifecycle.js', () => ({
+ getAgent: async () => JSON.parse(await readFile(fixture.recordPath, 'utf8')),
+ updateAgent: vi.fn(),
+ recordCompletionCleanup: async (_id, startedAt, patch) => {
+ if (fixture.failWrite) throw new Error('synthetic durable write failure');
+ const agent = JSON.parse(await readFile(fixture.recordPath, 'utf8'));
+ if (agent.status !== 'completed' || agent.startedAt !== startedAt) return false;
+ const prior = agent.metadata.completionCleanup || {};
+ agent.metadata.completionCleanup = { ...prior, ...patch, stages: { ...prior.stages, ...patch.stages } };
++ if (['completed', 'failed', 'abandoned'].includes(agent.metadata.completionCleanup.status)) {
++ delete agent.metadata.completionCleanup.context; delete agent.metadata.completionCleanup.replay;
++ }
+ await writeFile(fixture.recordPath, JSON.stringify(agent));
+ return true;
+ },
+}));
+vi.mock('./jira.js', () => ({}));
+vi.mock('./git.js', () => ({}));
+vi.mock('./codeReview.js', () => ({ resolveReviewLoopOptions: async () => ({}) }));
+vi.mock('./agentWorktreeCleanup.js', () => ({ cleanupAgentWorktree: vi.fn(async () => []), releaseRetryHold: vi.fn(async () => ({})), spawnMergeRecoveryTask: vi.fn(async () => ({ id: 'existing-recovery' })) }));
+vi.mock('./creativeDirector/completionHook.js', () => ({ handleCreativeDirectorCompletion: vi.fn() }));
+vi.mock('./brainTaskThreads.js', () => ({ ensureTaskThread: vi.fn() }));
+
+import { runAgentCompletionCleanup, replayAgentCompletionCleanup } from './agentCompletionCleanup.js';
++import { storeCompletionData, readCompletionData } from './agentCompletionData.js';
+import { readCompletionSentinel } from './agentCompletionSentinel.js';
+import { cleanupAgentWorktree } from './agentWorktreeCleanup.js';
+import { handleCreativeDirectorCompletion } from './creativeDirector/completionHook.js';
+import { updateTask, addTask } from './cosTaskStore.js';
+
+describe('durable post-ingestion cleanup replay', () => {
+ let root;
+ let workspace;
+ let marker;
+ const task = { id: 'task-one', taskType: 'user', metadata: {} };
+ const saved = async () => JSON.parse(await readFile(fixture.recordPath, 'utf8'));
+ const finish = (ownedTask = task) => runAgentCompletionCleanup({ agentId: 'agent-one', task: ownedTask,
+ agent: {}, effectiveSuccess: true, outputBuffer: 'Delivered summary' });
+
+ beforeEach(async () => {
+ vi.clearAllMocks();
+ fixture.failWrite = false;
+ root = await mkdtemp(join(tmpdir(), 'portos-completion-replay-'));
++ fixture.runRoot = join(root, 'runs');
+ workspace = join(root, 'repo');
+ await materializeGitRepo(workspace);
+ marker = join(workspace, '.agent-done-agent-one');
+ const contents = JSON.stringify({ summary: 'Delivered summary', payload: { result: 'original payload' } });
+ await writeFile(marker, contents);
+ fixture.recordPath = join(root, 'agent.json');
+ const evidence = await readCompletionSentinel('agent-one', workspace);
+ await writeFile(fixture.recordPath, JSON.stringify({ id: 'agent-one', taskId: task.id, status: 'completed',
+ startedAt: '2026-01-01T00:00:00Z', result: { success: true }, metadata: { workspacePath: workspace,
+ completionSentinel: evidence.receipt, completionSentinelContents: contents,
+ completionCleanup: { version: 1, status: 'pending', stages: {} } } }));
+ cleanupAgentWorktree.mockReset().mockResolvedValue([]);
+ updateTask.mockReset().mockResolvedValue({});
+ handleCreativeDirectorCompletion.mockReset().mockResolvedValue({});
+ });
+ afterEach(async () => { await rm(root, { recursive: true, force: true, maxRetries: 3 }); });
+
+ it('acknowledges durable ingestion and runs eligible Git cleanup despite pipeline failure, preserving its failed stage', async () => {
+ const head = (await execGit(['rev-parse', 'HEAD'], workspace)).stdout;
+ updateTask.mockResolvedValueOnce({ error: 'pipeline unavailable' });
+ cleanupAgentWorktree.mockImplementationOnce(async () => {
+ expect((await execGit(['status', '--porcelain'], workspace)).stdout).toBe('');
+ expect((await saved()).metadata.completionSentinelContents).toContain('original payload');
+ return [];
+ });
+ const pipelineTask = { ...task, metadata: { pipeline: { id: 'pipeline-one', status: 'running', currentStage: 0,
+ stageResults: [], stages: [{ name: 'Only stage' }] } } };
+ await expect(finish(pipelineTask)).rejects.toThrow('pipeline unavailable');
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(1);
+ const record = await saved();
- expect(record.metadata.completionCleanup).toMatchObject({ status: 'pending', stages: {
++ expect(record.metadata.completionCleanup).toMatchObject({ status: 'failed', stages: {
+ sentinel: { status: 'done' }, pipeline: { status: 'failed', retryable: false }, worktree: { status: 'done' },
+ } });
+ expect(record.result.success).toBe(true);
++ expect(record.metadata.completionCleanup).not.toHaveProperty('context');
++ expect(record.metadata.completionCleanup).not.toHaveProperty('replay');
+ await replayAgentCompletionCleanup(record);
+ expect(updateTask).toHaveBeenCalledTimes(1); // Unknown external hand-off is not republished.
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(1);
+ expect((await execGit(['rev-parse', 'HEAD'], workspace)).stdout).toBe(head);
+ });
+
+ it('holds pending repository delivery without throwing and advances configured chains once after verification', async () => {
+ const record = await saved();
+ record.result = { success: false, cleanupPending: true, executionSuccess: true };
+ record.metadata.repoStateVerification = { status: 'pending' };
+ await writeFile(fixture.recordPath, JSON.stringify(record));
+ const pipelineTask = { ...task, metadata: { creativeDirector: { projectId: 'synthetic-project' },
+ pipeline: { id: 'pipeline-one', status: 'running', currentStage: 0, stageResults: [], stages: [{ name: 'Only stage' }] } } };
+ await finish(pipelineTask); // A designed hold must not create an unsettled maintenance failure.
+ expect(updateTask).not.toHaveBeenCalled();
+ expect(handleCreativeDirectorCompletion).not.toHaveBeenCalled();
+ expect((await saved()).metadata.completionCleanup.stages).toMatchObject({
+ pipeline: { status: 'held', retryable: true, reason: 'checkout-retirement-pending' },
+ creative: { status: 'held', retryable: true, reason: 'checkout-retirement-pending' } });
+ const transferred = await saved();
+ transferred.metadata.repoStateVerification = { status: 'completed', reasons: ['cleanup-transferred-to-recovery'] };
+ await writeFile(fixture.recordPath, JSON.stringify(transferred));
+ await replayAgentCompletionCleanup(await saved());
+ expect(updateTask).not.toHaveBeenCalled();
+ expect(handleCreativeDirectorCompletion).not.toHaveBeenCalled();
+ const verified = await saved();
+ verified.metadata.repoStateVerification = { status: 'completed' };
+ verified.metadata.completionCleanup.stages.worktree.verifiedBy = 'repository-preservation-receipt';
+ await writeFile(fixture.recordPath, JSON.stringify(verified));
+ await Promise.all([replayAgentCompletionCleanup(await saved()), replayAgentCompletionCleanup(await saved())]);
+ expect(updateTask).toHaveBeenCalledTimes(1);
+ expect(handleCreativeDirectorCompletion).toHaveBeenCalledTimes(1);
+ expect(handleCreativeDirectorCompletion).toHaveBeenCalledWith(pipelineTask, 'agent-one', true);
+ expect((await saved()).metadata.completionCleanup.status).toBe('completed');
+ });
+
+ it('persists an asynchronous chain failure without suppressing acknowledged cleanup or blindly publishing again', async () => {
+ handleCreativeDirectorCompletion.mockRejectedValueOnce(new Error('chain write unavailable'));
+ await expect(finish({ ...task, metadata: { creativeDirector: { projectId: 'synthetic-project' } } })).rejects.toThrow('chain write unavailable');
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(1);
+ expect((await saved()).metadata.completionCleanup.stages.creative).toMatchObject({ status: 'failed', retryable: false });
+ await replayAgentCompletionCleanup(await saved());
+ expect(handleCreativeDirectorCompletion).toHaveBeenCalledTimes(1);
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(1);
+ });
+
+ it('finishes an acknowledgement interrupted after quarantine without deleting a newer canonical marker', async () => {
+ const record = await saved();
+ const held = `${marker}.ack-${record.metadata.completionSentinel.sha256}`;
+ record.metadata.completionCleanup = { version: 1, status: 'pending', startedAt: record.startedAt,
+ context: { task, effectiveSuccess: true, prOwnership: { taskOpenPR: false, agentOpensOwnPr: false } },
+ stages: { sentinel: { status: 'running', retryable: true } } };
+ await writeFile(fixture.recordPath, JSON.stringify(record));
+ await rename(marker, held); // Crash boundary: durable ingestion exists; ACK has not committed.
+ await writeFile(marker, 'a newer completion generation');
+ await replayAgentCompletionCleanup(await saved());
+ expect(await readFile(marker, 'utf8')).toBe('a newer completion generation');
+ await expect(readFile(held)).rejects.toMatchObject({ code: 'ENOENT' });
+ expect((await saved()).metadata.completionCleanup).toMatchObject({ status: 'pending', stages: { sentinel: { status: 'done' },
+ worktree: { status: 'held', reason: 'completion-sentinel-generation-pending' } } });
+ expect(cleanupAgentWorktree).not.toHaveBeenCalled();
+ });
+
+ it('replays only the failed worktree stage after restart and preserves a newer marker across duplicate callbacks', async () => {
+ cleanupAgentWorktree.mockRejectedValueOnce(new Error('transient Git read'));
+ await expect(finish()).rejects.toThrow('transient Git read');
+ expect((await saved()).metadata.completionCleanup.stages.worktree).toMatchObject({ status: 'failed', retryable: true });
+ // Reloading the JSON record models the completed-record callback after restart.
+ await Promise.all([replayAgentCompletionCleanup(await saved()), replayAgentCompletionCleanup(await saved())]);
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(2);
+ expect((await saved()).metadata.completionCleanup.status).toBe('completed');
+ await writeFile(marker, 'new generation must survive');
+ await Promise.all([replayAgentCompletionCleanup(await saved()), replayAgentCompletionCleanup(await saved())]);
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(2);
+ expect(await readFile(marker, 'utf8')).toBe('new generation must survive');
+ await replayAgentCompletionCleanup(await saved());
+ expect(cleanupAgentWorktree).toHaveBeenCalledTimes(2);
+ expect(addTask).not.toHaveBeenCalled();
+ });
+
++ it('refuses acknowledgement when its run-bound ingestion artifact is corrupt, retaining the original marker and checkout', async () => {
++ const record = await saved();
++ record.metadata.completionSentinelData = await storeCompletionData(record, 'sentinel', record.metadata.completionSentinelContents);
++ delete record.metadata.completionSentinelContents;
++ await writeFile(fixture.recordPath, JSON.stringify(record));
++ const reference = record.metadata.completionSentinelData;
++ await writeFile(join(fixture.runRoot, record.id, 'completion', `sentinel-${reference.sha256}.json`), 'corrupt');
++ await expect(finish()).rejects.toThrow('completion-data-size-changed');
++ expect(await readFile(marker, 'utf8')).toContain('original payload');
++ expect(cleanupAgentWorktree).not.toHaveBeenCalled();
++ expect((await saved()).metadata.completionCleanup).toMatchObject({ status: 'pending', stages: {
++ sentinel: { status: 'failed', retryable: true }, worktree: { status: 'held' },
++ } });
++ await expect(readCompletionData(record, reference)).rejects.toThrow('completion-data-size-changed');
++ });
++
+ it('retains the marker if durable continuation persistence fails', async () => {
+ fixture.failWrite = true;
+ await expect(finish()).rejects.toThrow('synthetic durable write failure');
+ expect(await readFile(marker, 'utf8')).toContain('original payload');
+ expect(cleanupAgentWorktree).not.toHaveBeenCalled();
+ });
+
+ it('keeps a service cleanup warning pending rather than treating a queued recovery as retirement', async () => {
+ cleanupAgentWorktree.mockResolvedValue(['CI failed; original branch and checkout retained']);
+ await finish();
+ expect((await saved()).metadata.completionCleanup).toMatchObject({ status: 'pending', stages: { worktree: { status: 'held' } } });
+ });
+
+ it('never acknowledges a replacement or sends its checkout to cleanup', async () => {
+ await writeFile(marker, 'replacement generation');
+ await finish();
+ expect(await readFile(marker, 'utf8')).toBe('replacement generation');
+ expect(cleanupAgentWorktree).not.toHaveBeenCalled();
+ expect((await saved()).metadata.completionCleanup).toMatchObject({ status: 'pending', stages: {
+ sentinel: { status: 'held' }, worktree: { status: 'held', reason: 'completion-sentinel-generation-pending' },
+ } });
+ });
+});
diff --cc server/services/agentCompletionData.js
index 0000000000,0000000000..ab8edae307
new file mode 100644
--- /dev/null
+++ b/server/services/agentCompletionData.js
@@@ -1,0 -1,0 +1,68 @@@
++/** Large replay inputs stay in the private run directory, never hot agent JSON. */
++import { constants } from 'node:fs';
++import { mkdir, lstat, open, chmod } from 'node:fs/promises';
++import { join } from 'node:path';
++import { createHash } from 'node:crypto';
++import { atomicWrite } from '../lib/fileCore.js';
++import { assertNotRealDataWrite } from '../lib/testDataIsolation.js';
++
++const MAX_BYTES = 64 * 1024 * 1024;
++const kinds = new Set(['replay', 'sentinel']);
++const hash = bytes => createHash('sha256').update(bytes).digest('hex');
++const lease = stat => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].map(String).join(':');
++const validRun = agent => /^[A-Za-z0-9_-]+$/.test(agent?.id || '') && Number.isFinite(Date.parse(agent.startedAt));
++async function directory(agent) {
++ if (!validRun(agent)) throw new Error('completion-data-run-unverified');
++ const { getAgentDir } = await import('./cosAgentIndex.js');
++ return join(getAgentDir(agent.id), 'completion');
++}
++
++export async function storeCompletionData(agent, kind, value) {
++ if (!validRun(agent)) throw new Error('completion-data-run-unverified');
++ if (!kinds.has(kind)) throw new Error('completion-data-kind-invalid');
++ const bytes = Buffer.from(JSON.stringify({ version: 1, agentId: agent.id, startedAt: agent.startedAt, kind, value }));
++ if (bytes.length > MAX_BYTES) throw new Error('completion-data-too-large');
++ const dir = await directory(agent);
++ assertNotRealDataWrite(dir, 'completion replay data');
++ await mkdir(dir, { recursive: true, mode: 0o700 });
++ const stat = await lstat(dir);
++ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('completion-data-directory-unverified');
++ await chmod(dir, 0o700);
++ const reference = { version: 1, kind, bytes: bytes.length, sha256: hash(bytes) };
++ const path = join(dir, `${kind}-${reference.sha256}.json`);
++ const existing = await lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
++ if (existing) await readCompletionData(agent, reference);
++ else {
++ // The enclosing private directory protects bytes while atomicWrite fsyncs
++ // and publishes them; its usual new-file mode is narrowed afterward too.
++ await atomicWrite(path, bytes);
++ await chmod(path, 0o600);
++ await readCompletionData(agent, reference);
++ }
++ return reference;
++}
++
++export async function readCompletionData(agent, reference) {
++ if (reference?.version !== 1 || !kinds.has(reference.kind) || !/^[a-f0-9]{64}$/.test(reference.sha256 || '')
++ || !Number.isInteger(reference.bytes) || reference.bytes < 1 || reference.bytes > MAX_BYTES) throw new Error('completion-data-reference-invalid');
++ const path = join(await directory(agent), `${reference.kind}-${reference.sha256}.json`);
++ const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
++ try {
++ const before = await file.stat({ bigint: true });
++ if (!before.isFile() || before.size !== BigInt(reference.bytes)) throw new Error('completion-data-size-changed');
++ const bytes = await file.readFile();
++ const after = await file.stat({ bigint: true });
++ const current = await lstat(path, { bigint: true });
++ if (lease(before) !== lease(after) || lease(before) !== lease(current) || hash(bytes) !== reference.sha256) throw new Error('completion-data-changed');
++ const parsed = JSON.parse(bytes);
++ if (parsed.version !== 1 || parsed.agentId !== agent.id || parsed.startedAt !== agent.startedAt || parsed.kind !== reference.kind) throw new Error('completion-data-run-changed');
++ return parsed.value;
++ } finally { await file.close(); }
++}
++
++/** Preserve arbitrary pipeline/reviewer metadata in the run artifact, but omit
++ * unrelated task-level prompt/output/history fields from the replay input. */
++export const completionReplayInput = ({ task, effectiveSuccess, prOwnership, prClaimVerified, branchProvenEmpty, outputBuffer }) => ({
++ task: { id: task?.id, taskType: task?.taskType, description: task?.description, priority: task?.priority, metadata: task?.metadata },
++ effectiveSuccess, prOwnership, prClaimVerified, branchProvenEmpty, outputBuffer,
++});
diff --cc server/services/agentCompletionRetirement.integration.test.js
index 1dbbe0dce5,0000000000..d98e5c7784
mode 100644,000000..100644
--- a/server/services/agentCompletionRetirement.integration.test.js
+++ b/server/services/agentCompletionRetirement.integration.test.js
@@@ -1,168 -1,0 +1,174 @@@
+/** No-inventory completion must retain one exact obligation through execution release and real preservation. */
+import { afterEach, afterAll, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, readFile, writeFile, rm, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { materializeGitRepo } from '../lib/gitTestRepo.js';
+import { execGit } from '../lib/execGit.js';
+import { makePathsProxy, lazyTempDataRoot, cleanupTempDataRoots } from '../lib/mockPathsDataRoot.js';
+const fixture = vi.hoisted(() => ({ root: null, app: null, forge: null, task: null, agents: {}, schedule: null, raceTaskEdit: false }));
+vi.mock('../lib/paths.js', async original => makePathsProxy(await original(), { dataRoot: () => lazyTempDataRoot('portos-completion-retirement-state-') }));
+vi.mock('./cos.js', () => ({}));
+vi.mock('./domainUsage.js', () => ({ recordDomainUsage: async () => {} }));
+vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn(), cosEvents: { emit: vi.fn() } }));
+vi.mock('./apps.js', () => ({ getAppById: async id => id === fixture.app?.id ? fixture.app : null }));
+vi.mock('./branchReconcileRetirement.js', async original => ({ ...await original(), assertAutomaticRetirementAllowed: async () => {} }));
+vi.mock('./branchReconcile.js', async original => ({ ...await original(), listRemoteHeads: async () => new Map() }));
+vi.mock('./heldCheckoutReview.js', async original => ({ ...await original(), readRetirementForgeEvidence: async () => fixture.forge }));
+vi.mock('./prProbe.js', async original => ({ ...await original(), probePrForBranch: async () => ({ readable: true,
+ prState: fixture.forge ? 'MERGED' : 'OPEN', prUrl: 'https://github.com/example/repo/pull/42', prNumber: 42, cli: 'gh' }) }));
+vi.mock('./prWatcher.js', () => ({ readPendingMergePrs: () => [] }));
+vi.mock('./cosTaskStore.js', () => ({
+ getTaskById: async () => JSON.parse(await readFile(join(fixture.root, 'task.json'), 'utf8')),
+ getAllTasks: async () => ({ user: { tasks: [fixture.task] }, cos: { tasks: [] } }),
+ updateTask: async (_id, patch, _type, { expectedStatus, expectedMetadata } = {}) => {
+ const current = JSON.parse(await readFile(join(fixture.root, 'task.json'), 'utf8'));
+ if (fixture.raceTaskEdit && patch.metadata?.deliveryRecovery === 'cleanup') {
+ fixture.raceTaskEdit = false; current.metadata.updatedAt = 'concurrent-human-edit';
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(current));
+ }
+ if ((expectedStatus && current.status !== expectedStatus)
+ || Object.entries(expectedMetadata || {}).some(([key, value]) => current.metadata?.[key] !== value)) return { statusChanged: true, task: current };
+ fixture.task = current;
+ fixture.task = { ...fixture.task, ...patch, metadata: { ...fixture.task.metadata, ...patch.metadata } };
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(fixture.task)); return fixture.task;
+ }, addTask: async () => { throw new Error('unexpected cognitive recovery'); },
+}));
+vi.mock('./cosState.js', async () => ({
+ AGENTS_DIR: join((await import('../lib/paths.js')).PATHS.cos, 'agents'),
+ loadState: async () => ({ agents: fixture.agents, stats: {} }),
+ saveState: async state => { fixture.agents = state.agents; await writeFile(join(fixture.root, 'agents-state.json'), JSON.stringify(state)); },
+ withStateLock: work => work(), readAgentsStateForSafetyCheck: async () => ({ trusted: true, agents: fixture.agents }),
+}));
+vi.mock('./branchCompletionPolicy.js', async original => ({ ...await original(), readBranchCompletionPolicies: async () => Object.values(fixture.agents) }));
+vi.mock('./taskScheduleStore.js', async original => ({ ...await original(), loadSchedule: async () => fixture.schedule,
+ updateSchedule: async mutate => { const output = await mutate(fixture.schedule);
+ await writeFile(join(fixture.root, 'schedule.json'), JSON.stringify(fixture.schedule)); return output.result; },
+}));
+const { verifyAgentRepoState, sweepRepoStateVerifications } = await import('./agentRepoStateVerification.js');
+const { bindCompletionTaskDispatch, prepareCompletionTaskHandoff } = await import('./agentCompletionTaskHandoff.js');
+const { completeAgent, getAgentRecord } = await import('./cosAgentLifecycle.js');
+const { getBranchReconcileOutcome } = await import('./taskSchedule.js');
+const { activeAgents } = await import('./agentState.js');
+const { PATHS } = await import('../lib/paths.js');
+const { cosEvents } = await import('./cosEvents.js');
+afterAll(cleanupTempDataRoots);
+let scratch;
+afterEach(async () => { activeAgents.clear(); if (scratch) await rm(scratch, { recursive: true, force: true, maxRetries: 3 }); });
+describe('completion to archive retirement (real Git and persisted service state)', () => {
- it('rotates beyond ten persisted pending handoffs even when repository verification finished earlier', async () => {
++ it('drains context-less legacy handoffs instead of sweeping nonretryable failures forever', async () => {
+ scratch = await mkdtemp(join(tmpdir(), 'portos-completion-sweep-'));
+ fixture.root = PATHS.data; await mkdir(fixture.root, { recursive: true });
+ fixture.task = { id: 'sweep-task', taskType: 'user', status: 'completed', metadata: {} };
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(fixture.task));
+ fixture.agents = Object.fromEntries(Array.from({ length: 11 }, (_, index) => {
+ const id = `sweep-agent-${index}`;
+ return [id, { id, taskId: fixture.task.id, status: 'completed', startedAt: '2020-01-01T00:00:00.000Z',
+ result: { success: false }, metadata: { repoStateVerification: { status: 'completed', checkedAt: '2020-01-01T00:00:01.000Z' },
+ completionCleanup: { version: 1, status: 'pending', updatedAt: new Date(1600000000000 + index).toISOString(),
+ stages: { pipeline: { status: 'failed', retryable: false, reason: 'external-state-unknown' } } } } }];
+ }));
+ const waiting = fixture.agents['sweep-agent-10'].metadata.completionCleanup.updatedAt;
+ expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 10, pendingAtStart: 11 });
+ fixture.agents = JSON.parse(await readFile(join(fixture.root, 'agents-state.json'), 'utf8')).agents;
+ expect(fixture.agents['sweep-agent-10'].metadata.completionCleanup.updatedAt).toBe(waiting);
- expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 10, pendingAtStart: 11 });
++ expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 1, pendingAtStart: 1 });
+ fixture.agents = JSON.parse(await readFile(join(fixture.root, 'agents-state.json'), 'utf8')).agents;
+ expect(fixture.agents['sweep-agent-10'].metadata.completionCleanup.lastAttemptAt).toEqual(expect.any(String));
+ expect(fixture.agents['sweep-agent-10'].metadata.completionCleanup.stages.pipeline).toMatchObject({ status: 'failed', retryable: false });
++ expect(fixture.agents['sweep-agent-10'].metadata.completionCleanup.status).toBe('abandoned');
++ expect(await sweepRepoStateVerifications()).toMatchObject({ checked: 0, pendingAtStart: 0 });
+ expect(fixture.task.status).toBe('completed');
+ });
+
+ it.each(['unchanged', 'changed-dispatch', 'concurrent-task-edit', 'claim-reacquired'])('recovers the missing task handoff after restart with exact task CAS (%s)', async scenario => {
+ const changed = scenario !== 'unchanged';
+ fixture.raceTaskEdit = false;
+ cosEvents.emit.mockClear();
+ scratch = await mkdtemp(join(tmpdir(), 'portos-completion-retirement-'));
+ fixture.root = PATHS.data; await mkdir(fixture.root, { recursive: true });
+ await materializeGitRepo(join(scratch, 'repo'));
+ const repo = await realpath(join(scratch, 'repo'));
+ const path = join(repo, '.claude', 'worktrees', 'completion'); const branch = 'claim/issue-42';
+ await execGit(['worktree', 'add', '-b', branch, path, 'main'], repo);
+ await writeFile(join(path, 'feature.txt'), 'delivered original\n');
+ await execGit(['add', 'feature.txt'], path); await execGit(['commit', '-m', 'deliver original'], path);
+ const head = (await execGit(['rev-parse', 'HEAD'], path)).stdout.trim();
+ const startedAt = new Date(Date.now() - 1000).toISOString();
+ const running = { id: `agent-completion-${scenario}`, taskId: `task-completion-${scenario}`, status: 'running', startedAt, output: [],
+ metadata: { isWorktree: true, sourceWorkspace: repo, workspacePath: path, worktreeBranch: branch, prCompletionPolicy: 'review-then-merge' } };
+ await execGit(['merge', '--ff-only', branch], repo);
+ const defaultHead = (await execGit(['rev-parse', 'HEAD'], repo)).stdout.trim();
+ await writeFile(join(repo, '.git', 'info', 'exclude'), 'ignored.txt\n');
+ await writeFile(join(path, 'ignored.txt'), 'private preserved bytes\n');
+ fixture.forge = { repository: 'github.com/example/repo', prUrl: 'https://github.com/example/repo/pull/42', prHead: head, changeBase: (await execGit(['rev-parse', `${head}^`], repo)).stdout.trim(), firstCommit: head,
+ mergeCommit: defaultHead, defaultBranch: 'main', defaultHead, remoteHead: null, changedPaths: ['feature.txt'] };
+ fixture.app = { id: 'app-completion', repoPath: repo }; fixture.schedule = { tasks: {}, executions: {} };
+ fixture.task = { id: running.taskId, taskType: 'user', status: 'in_progress', metadata: { app: fixture.app.id, openPR: true,
+ prCompletion: 'review-then-merge', claimedBy: 'fixture-instance', claimedAt: startedAt, totalSpawnCount: 1,
+ lastSpawnedAt: startedAt, updatedAt: startedAt } };
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(fixture.task));
+ fixture.agents = { [running.id]: running };
+ activeAgents.set(running.id, { task: fixture.task });
+ expect(await bindCompletionTaskDispatch(running.id, fixture.task)).toBe(true);
+ expect(await prepareCompletionTaskHandoff(await getAgentRecord(running.id), { hookDelivery: { selectedPaths: ['feature.txt'] } })).toBe(true);
+ const agent = await completeAgent(running.id, { success: true, executionSuccess: true, requireCheckoutSettlement: true });
+ expect(agent.result).toMatchObject({ success: false, cleanupPending: true, executionSuccess: true });
+ expect(agent.metadata.completedCheckouts).toHaveLength(1);
+ await completeAgent(running.id, { success: true, executionSuccess: true, requireCheckoutSettlement: true });
+ expect(cosEvents.emit.mock.calls.filter(([event]) => event === 'agent:completed')).toHaveLength(1);
+ // Crash after terminal agent durability, BEFORE the normal task update.
+ expect(JSON.parse(await readFile(join(fixture.root, 'task.json'), 'utf8')).metadata.deliveryRecovery).toBeUndefined();
+ fixture.agents = JSON.parse(await readFile(join(fixture.root, 'agents-state.json'), 'utf8')).agents;
+ fixture.task = JSON.parse(await readFile(join(fixture.root, 'task.json'), 'utf8'));
+ if (scenario === 'concurrent-task-edit') fixture.raceTaskEdit = true;
+ if (scenario === 'claim-reacquired') {
+ // prepareAgentSpawn reclaims before registration or a fresh spawn stamp.
+ const { buildClaim } = await import('./cosTaskClaim.js');
+ Object.assign(fixture.task.metadata, buildClaim('fixture-instance'));
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(fixture.task));
+ }
+ if (scenario === 'changed-dispatch') {
+ fixture.task.metadata.totalSpawnCount++;
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(fixture.task));
+ }
+ const verify = () => verifyAgentRepoState({ agentId: agent.id, agentState: fixture.agents[agent.id], task: fixture.task, success: false, prExpected: true });
+ expect(await getBranchReconcileOutcome(fixture.app.id)).toBeNull(); activeAgents.set(agent.id, { task: fixture.task });
+ if (changed) {
+ activeAgents.delete(agent.id); // No competing registered owner exists yet.
+ expect(await verify()).toMatchObject({ verified: false, skipReason: 'cleanup-owner-changed' });
+ expect(fixture.task.metadata.deliveryRecovery).toBeUndefined();
+ expect((await getAgentRecord(agent.id)).metadata.repoStateVerification.status).toBe('pending');
+ expect((await execGit(['rev-parse', 'HEAD'], path)).stdout.trim()).toBe(head);
+ expect(await readFile(join(path, 'ignored.txt'), 'utf8')).toBe('private preserved bytes\n');
+ expect(await getBranchReconcileOutcome(fixture.app.id)).toBeNull();
+ return;
+ }
+ expect(await verify()).toMatchObject({ verified: false, skipReason: 'completion-execution-active' });
+ expect(fixture.task.metadata).toMatchObject({ deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: running.id,
+ hookDelivery: { selectedPaths: ['feature.txt'] } });
+ const pending = await getBranchReconcileOutcome(fixture.app.id); expect(pending.retirementObligations).toHaveLength(1);
+ const obligation = pending.retirementObligations[0]; expect(obligation).toMatchObject({ path, branch, head });
+ expect(fixture.task.status).toBe('in_progress');
+ fixture.schedule = JSON.parse(await readFile(join(fixture.root, 'schedule.json'), 'utf8')); activeAgents.delete(agent.id);
+ const { buildRenewal } = await import('./cosTaskClaim.js');
+ Object.assign(fixture.task.metadata, buildRenewal(fixture.task.metadata, 'fixture-instance'));
+ await writeFile(join(fixture.root, 'task.json'), JSON.stringify(fixture.task));
+ const results = await Promise.all([verify(), verify()]); expect(results).toMatchObject([{ verified: true, skipReason: null }, { verified: true, skipReason: null }]);
+ const outcome = await getBranchReconcileOutcome(fixture.app.id); expect(outcome.retirementObligations).toEqual([]);
+ expect(outcome.retired).toHaveLength(1); const receipt = outcome.retired[0];
+ expect(receipt).toMatchObject({ path, branch, head, branchDeleted: true });
+ expect(await readFile(join(receipt.archiveDir, 'files', 'ignored.txt'), 'utf8')).toBe('private preserved bytes\n');
+ const restored = join(scratch, 'restored.git'); await execGit(['init', '--bare', restored], scratch);
+ await execGit(['bundle', 'unbundle', join(receipt.archiveDir, 'commits.bundle')], restored);
+ expect((await execGit(['show', `${head}:feature.txt`], restored)).stdout).toBe('delivered original\n');
+ expect((await execGit(['worktree', 'list', '--porcelain'], repo)).stdout).not.toContain(path);
+ expect((await execGit(['rev-parse', '--verify', `refs/heads/${branch}`], repo, { ignoreExitCode: true })).exitCode).not.toBe(0);
+ expect(JSON.parse(await readFile(join(fixture.root, 'task.json'), 'utf8')).status).toBe('completed');
+ await verify(); expect((await getBranchReconcileOutcome(fixture.app.id)).retired).toHaveLength(1);
- });
++ // This public-boundary scenario makes 182 real Git calls across capture,
++ // fresh reviews, archive verification, retirement and independent restore.
++ // Measured wall time reaches 29s before host contention; keep its own budget
++ // separate from the default 30s unit budget without weakening any proof.
++ }, 60_000);
+});
diff --cc server/services/agentFinalization.js
index 2ddc4b0607,0ae51664d6..156e4f35a8
--- a/server/services/agentFinalization.js
+++ b/server/services/agentFinalization.js
@@@ -1,5 -1,3 +1,6 @@@
++import { storeCompletionData, completionReplayInput } from './agentCompletionData.js';
+import { prepareCompletionTaskHandoff, recoverCompletionTaskHandoff } from './agentCompletionTaskHandoff.js';
+import { hasClaimCheckoutBindings } from './completedCheckoutEvidence.js';
import { isLegacyDeepAudit } from '../lib/auditWorkflow.js';
import { retryHoldMetadata, isDeliveryCleanupHeld } from '../lib/taskRetryHold.js';
import { PR_COMPLETIONS, resolvePrCompletion, PR_MISSING_CATEGORY, prClaimWasVerified } from '../lib/prDisposition.js';
@@@ -1968,18 -1966,9 +1969,22 @@@ export async function finalizeAgent(
// completeAgentRun writes its own runs/<id>/metadata.json (separate lock),
// so its place in the chain is purely about progress reporting on partial
// failure.
- await completeAgent(agentId, { ...completionRecord({
+ await stampLiExecutionVerdict(taskUpdate, task, { success: deliverySuccess, validationPassed, errorAnalysis: deliveryVerdict.errorAnalysis });
- await updateAgent(agentId, { metadata: { completionCleanup: cleanupOwner?.metadata?.completionCleanup || { version: 1, status: 'pending', stages: {},
- context: { task, effectiveSuccess: deliverySuccess, outputBuffer,
- prClaimVerified: prClaimWasVerified(prEvidence.cleanupEvidence), branchProvenEmpty: prEvidence.branchProvenEmpty } } } });
++ const priorCleanup = cleanupOwner?.metadata?.completionCleanup;
++ const settledCleanup = ['completed', 'failed', 'abandoned'].includes(priorCleanup?.status);
++ const replay = priorCleanup?.replay || (!settledCleanup && cleanupOwner?.startedAt ? await storeCompletionData(cleanupOwner, 'replay', completionReplayInput({ task,
++ effectiveSuccess: deliverySuccess, outputBuffer,
++ prClaimVerified: prClaimWasVerified(prEvidence.cleanupEvidence), branchProvenEmpty: prEvidence.branchProvenEmpty })) : undefined);
++ await updateAgent(agentId, { metadata: { completionCleanup: { ...cleanupOwner?.metadata?.completionCleanup,
++ version: 1, status: priorCleanup?.status || 'pending', stages: priorCleanup?.stages || {}, replay, context: undefined } } });
+ if (cleanupEligible) await prepareCompletionTaskHandoff(await getAgentRecord(agentId),
+ Object.fromEntries(Object.entries(taskUpdate.metadata || {}).filter(([key, value]) =>
+ key !== 'privateSecurityScope' && JSON.stringify(value) !== JSON.stringify(preHookTask.metadata?.[key]))));
+ const completedAgent = await completeAgent(agentId, { ...completionRecord({
task, verdict: deliveryVerdict, hookResult, fidelity, executionInterruption, exitCode, duration, outputBuffer, validationPassed,
}), executionSuccess, taskOutcome,
+ requireCheckoutSettlement: deliverySuccess && taskUpdate.status === 'completed' && cleanupEligible
+ && resolvePrCompletion(task.metadata) === PR_COMPLETIONS.REVIEW_THEN_MERGE,
...(['task-approval', 'task-recovery-exhausted'].includes(taskUpdate.metadata?.blockedCategory)
|| taskUpdate.metadata?.retryPendingCleanup === agentId || taskUpdate.metadata?.deliveryRecoveryAgentId === agentId
? { deliveryRecoveryOwned: true } : {}),
@@@ -2362,7 -2347,6 +2367,8 @@@ async function persistCompletionSummary
&& existing.metadata.taskSummary.trim()) return taskOutcome;
}
await updateAgent(agentId, { metadata: {
- ...(ingested ? { completionSentinel: ingested.receipt, completionSentinelContents: ingested.contents } : {}),
++ ...(ingested ? { completionSentinel: ingested.receipt, completionSentinelData: await storeCompletionData(
++ existingRecord || await getAgentRecord(agentId), 'sentinel', ingested.contents), completionSentinelContents: undefined } : {}),
taskSummary: summary,
taskSummarySource: source,
taskOutcome,
diff --cc server/services/agentFinalization.outputHooks.test.js
index 92ec52c1cb,92ec52c1cb..7598dc75ed
--- a/server/services/agentFinalization.outputHooks.test.js
+++ b/server/services/agentFinalization.outputHooks.test.js
@@@ -1,3 -1,3 +1,6 @@@
++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);
vi.mock('../lib/fileUtils.js', async importOriginal => {
const actual = await importOriginal();
return { ...actual, tryReadFile: vi.fn(actual.tryReadFile) };
@@@ -23,7 -23,7 +26,7 @@@ vi.mock('./codeReview.js', async (impor
getGoalFidelityConfig: vi.fn(async () => null),
}));
--import { beforeEach, describe, expect, it, vi } from 'vitest';
++import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
@@@ -323,6 -323,6 +326,32 @@@ describe('recovery output-hook dispatc
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.'],
diff --cc server/services/agentRepoStateVerification.js
index 8b615e492c,8b84c619c6..d4cd92914e
--- a/server/services/agentRepoStateVerification.js
+++ b/server/services/agentRepoStateVerification.js
@@@ -1,9 -1,7 +1,10 @@@
-import { readRetirementCheckoutIdentity } from '../lib/retirementCheckoutObservation.js';
+import { recoverCompletionTaskHandoff } from './agentCompletionTaskHandoff.js';
import { MANAGED_WORKTREE_CLEANUP_CONTRACT } from '../lib/mergeGateContract.js';
import { processAuditFingerprint } from '../lib/persistentMindProcessAudit.js';
+import { completionSentinelPresent } from './agentCompletionSentinel.js';
+import { hasClaimCheckoutBindings } from './completedCheckoutEvidence.js';
- import { sameRetirementCheckout } from '../lib/reconcileRetirementEvidence.js';
++import { readRetirementCheckoutIdentity } from '../lib/retirementCheckoutObservation.js';
+ import { sameRetirementObservation } from '../lib/reconcileRetirementEvidence.js';
/**
* Agent Repo-State Verification
*
@@@ -728,13 -685,8 +731,13 @@@ async function prepareRecoveryRetiremen
const outcome = await recordBranchReconcileOutcome(app.id, { status: 'incomplete', reason: 'retirement-review-pending',
retirementObligations: [{ ...release, reason: 'retirement-review-pending' }],
nextAction: 'Review this exact checkout through the retirement API; require its verified archive receipt.' });
- const obligation = outcome?.retirementObligations?.find(row => sameRetirementCheckout(row, release));
+ const obligation = outcome?.retirementObligations?.find(row => sameRetirementObservation(row, release));
if (!obligation?.createdAt) return { reason: 'retirement-obligation-unavailable' };
+ // Terminal ingestion releases the registry verdict before every spawn path
+ // has finished teardown. Preserve the durable obligation until its exact
+ // execution owner has actually left the local active maps.
+ const { getActiveAgentIds } = await import('./agentState.js');
+ if (getActiveAgentIds().includes(agentId)) return { reason: 'completion-execution-active' };
if (release.locked) {
await recordBranchReconcileOutcome(app.id, { status: 'incomplete', reason: 'retirement-worktree-locked',
nextAction: 'Keep the checkout locked; its owner must explicitly release it before another preview.' });
diff --cc server/services/completedCheckoutEvidence.js
index 88237964be,8686fae571..b9f6ea27a7
--- a/server/services/completedCheckoutEvidence.js
+++ b/server/services/completedCheckoutEvidence.js
@@@ -40,14 -31,14 +40,14 @@@ async function filesystemIdentity(path
return { dev: String(stat.dev), ino: String(stat.ino), birthtimeNs: String(stat.birthtimeNs) };
}
--export async function readCompletedCheckoutIdentity({ repoPath, branch, path, head, worktrees = null, repoCommon = null }) {
++export async function readCompletedCheckoutIdentity({ repoPath, branch, path, head, worktrees = null, repoCommon = null, allowLocked = false }) {
const { listWorktrees } = await import('./worktreeManager.js');
const repository = await realpath(repoPath);
const checkout = await realpath(path);
if (checkout === repository || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(head || '')) return null;
const trees = worktrees || await listWorktrees(repository);
const holders = trees.filter(tree => shortBranch(tree.branch) === branch);
- if (holders.length !== 1 || holders[0].locked === true || await realpath(holders[0].path) !== checkout || holders[0].head !== head) return null;
- if (holders.length !== 1 || await realpath(holders[0].path) !== checkout || holders[0].head !== head) return null;
++ if (holders.length !== 1 || (!allowLocked && holders[0].locked === true) || await realpath(holders[0].path) !== checkout || holders[0].head !== head) return null;
const pointer = await filesystemIdentity(join(checkout, '.git'), 'file');
const gitdir = await realpath((await execGit(['rev-parse', '--absolute-git-dir'], checkout)).stdout.trim());
const administration = await filesystemIdentity(gitdir, 'directory');
diff --cc server/services/completedCheckoutEvidence.test.js
index 4e1d93e898,fac558fd5c..e4fa639551
--- a/server/services/completedCheckoutEvidence.test.js
+++ b/server/services/completedCheckoutEvidence.test.js
@@@ -4,7 -4,7 +4,7 @@@ import { tmpdir } from 'node:os'
import { join } from 'node:path';
import { execGit } from '../lib/execGit.js';
import { materializeGitRepo } from '../lib/gitTestRepo.js';
--import { captureCompletedCheckouts, hasCompletedCheckoutEvidence } from './completedCheckoutEvidence.js';
++import { captureCompletedCheckouts, hasCompletedCheckoutEvidence, readCompletedCheckoutIdentity } from './completedCheckoutEvidence.js';
describe('completed claim checkout evidence', () => {
let scratch, repoPath, path, head, agent;
@@@ -47,6 -46,6 +47,15 @@@
expect(await captureCompletedCheckouts({ ...agent, metadata: { isWorktree: true, workspacePath: repoPath, worktreeBranch: branch } }, { success: true })).toEqual([]);
});
++ it('allows a scoped identity fact-read of a locked checkout without changing default capture refusal or its lock', async () => {
++ await execGit(['worktree', 'lock', '--reason', 'owned operator checkout', path], repoPath);
++ expect(await readCompletedCheckoutIdentity(target())).toBeNull();
++ const identity = await readCompletedCheckoutIdentity({ ...target(), allowLocked: true });
++ expect(identity).toMatchObject({ branch, head, incarnation: { pointer: { ino: expect.any(String) } } });
++ expect(await captureCompletedCheckouts(agent, { success: true })).toEqual([]);
++ expect((await execGit(['worktree', 'list', '--porcelain'], repoPath)).stdout).toContain('locked owned operator checkout');
++ });
++
it('rejects a new checkout reusing the completed branch, path and exact head', async () => {
const receipts = await captureCompletedCheckouts(agent, { success: true });
expect(receipts).toHaveLength(1);
diff --cc server/services/cosAgentLifecycle.js
index 20d1e00371,11e3a546b1..621ac983fe
--- a/server/services/cosAgentLifecycle.js
+++ b/server/services/cosAgentLifecycle.js
@@@ -249,72 -243,6 +249,77 @@@ async function updateCompletionReceipt(
}));
}
+/** A terminal run keeps independent post-ingestion obligations in its existing
+ * durable record, including after the record moved to its archive bucket.
+ */
+export async function recordCompletionCleanup(agentId, startedAt, patch) {
+ let matched = false;
+ const saved = await updateCompletionReceipt(agentId, (metadata, agent) => {
+ if (agent.startedAt !== startedAt) return metadata;
+ matched = true;
+ const prior = metadata.completionCleanup || { version: 1, stages: {} };
- return { ...metadata, completionCleanup: { ...prior, ...patch,
- stages: { ...prior.stages, ...patch.stages }, updatedAt: new Date().toISOString() } };
++ const completionCleanup = { ...prior, ...patch,
++ stages: { ...prior.stages, ...patch.stages }, updatedAt: new Date().toISOString() };
++ if (['completed', 'failed', 'abandoned'].includes(completionCleanup.status)) {
++ delete completionCleanup.context;
++ delete completionCleanup.replay;
++ }
++ return { ...metadata, completionCleanup };
+ });
+ return saved && matched;
+}
+
+/** Retry capture ONLY against preterminal snapshots. Unknown originals remain
+ * explicit holds; a completed record can never discover a replacement by name.
+ */
+export async function retryCompletionCheckoutCapture(agentId) {
+ const { withClaimOwnershipLock, readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');
+ const { claimCheckoutOwner } = await import('../lib/claimContinuation.js');
+ const { readCompletedCheckoutIdentity, captureSeededCompletionCheckouts } = await import('./completedCheckoutEvidence.js');
+ return withClaimOwnershipLock(async () => {
+ const agent = await getAgentRecord(agentId);
+ const pending = agent?.metadata?.checkoutCapture;
+ if (agent?.status !== 'completed' || pending?.status !== 'pending') return false;
+ const owners = await readClaimOwnershipAgents().catch(() => null);
+ const { readBranchCompletionPolicies } = await import('./branchCompletionPolicy.js');
+ const history = await readBranchCompletionPolicies({ repairIndex: false }).catch(() => null);
+ if (!Array.isArray(owners) || !Array.isArray(history)) return false;
+ const bound = hasClaimCheckoutBindings(agent.metadata) ? agent.metadata.claimBranches : [agent.metadata?.worktreeBranch];
+ const seeds = (agent.metadata?.checkoutSeeds || []).filter(seed => Array.isArray(bound) && bound.includes(seed.branch));
+ const targets = seeds.length ? seeds : pending.unknown === false ? pending.targets : null;
+ if (!targets?.length) return false;
+ for (const target of targets) {
+ if (target.agentId !== agentId || target.startedAt !== agent.startedAt
+ || claimCheckoutOwner({ branchName: target.branch, holderPath: target.path, sourceWorkspace: target.repoPath, agents: owners })) return false;
+ for (const other of history) {
+ if ((other.id || other.agentId) === agentId) continue;
+ const meta = other.metadata || {};
+ const branches = [meta.worktreeBranch, ...(meta.claimBranches || []), ...(meta.claimReleasedBranches || [])];
+ if (!branches.includes(target.branch)) continue;
+ const repository = await realpath(meta.sourceWorkspace || meta.workspacePath || '').catch(() => null);
+ if (repository !== target.repoPath) continue;
+ if (!Number.isFinite(Date.parse(other.startedAt)) || Date.parse(other.startedAt) >= Date.parse(agent.startedAt)) return false;
+ }
+ if (seeds.length) continue;
+ if (!Number.isFinite(Date.parse(target.capturedAt)) || Date.parse(target.capturedAt) < Date.parse(agent.startedAt)
+ || Date.parse(target.capturedAt) > Date.parse(agent.completedAt)) return false;
+ const current = await readCompletedCheckoutIdentity(target).catch(() => null);
+ const expected = { repoPath: target.repoPath, branch: target.branch, path: target.path, head: target.head, incarnation: target.incarnation };
+ if (!current || JSON.stringify(current) !== JSON.stringify(expected)) return false;
+ }
+ const captured = seeds.length ? await captureSeededCompletionCheckouts(agent).catch(() => null) : targets;
+ if (!captured?.length) return false;
+ let recorded = false;
+ const saved = await updateCompletionReceipt(agentId, (metadata, current) => {
+ if (current.startedAt !== agent.startedAt || JSON.stringify(metadata.checkoutCapture) !== JSON.stringify(pending)
+ || JSON.stringify(metadata.checkoutSeeds) !== JSON.stringify(agent.metadata.checkoutSeeds)) return metadata;
+ recorded = true;
+ return { ...metadata, checkoutCapture: { status: 'captured', retriedAt: new Date().toISOString() }, completedCheckouts: captured };
+ });
+ return saved && recorded;
+ });
+}
+
export async function completeAgent(agentId, result = {}) {
const existing = await getAgentRecord(agentId);
if (existing?.metadata?.taskAnalysisType === 'security' && existing.metadata.useRunner) {
@@@ -378,36 -294,18 +383,31 @@@
}
}
+ // The execution can end before repository preservation is complete. Keep
+ // the original task owned by deterministic recovery until exact receipts
+ // settle it; never turn a queued cleanup into delivery success.
+ if (result.requireCheckoutSettlement === true && completedCheckouts?.length && result.success === true) {
+ result = { ...result, success: false, executionSuccess: result.executionSuccess ?? true,
+ cleanupPending: true, deliveryRecoveryOwned: true,
+ taskOutcome: { status: 'incomplete', reason: 'Code delivery completed; exact checkout preservation and retirement are pending.',
+ recovery: { mode: 'cleanup' } } };
+ }
+ const { requireCheckoutSettlement: _requireCheckoutSettlement, ...persistedResult } = result;
+ result = persistedResult;
+
++ const cleanup = agent.metadata?.completionCleanup;
++ const cleanupContext = cleanup?.replay || cleanup?.context;
++ const metadata = { ...agent.metadata,
++ completionCleanup: { version: 1, stages: {}, ...cleanup, startedAt: agent.startedAt,
++ status: cleanupContext ? cleanup.status || 'pending' : 'abandoned',
++ ...(!cleanupContext && { reason: 'completion-context-unavailable' }) },
++ ...(completedCheckouts ? { checkoutCapture: checkoutCapture || { status: 'captured' } } : {}),
++ ...((result.success || result.cleanupPending === true) && (agent.metadata?.isWorktree || hasClaimCheckoutBindings(agent.metadata))
++ ? { repoStateVerification: { status: 'pending' } } : {}),
++ };
state.agents[agentId] = {
-- ...state.agents[agentId],
-- status: 'completed',
-- completedAt: new Date().toISOString(),
-- // Success-criteria validation verdict (issue #2344): normalize to an
-- // explicit null sentinel when a completion path didn't declare/evaluate a
-- // machine-checkable criterion, so persisted telemetry never conflates
-- // "not declared" with "declared and failed" (false). Distinct from
-- // result.success (the runner's exit-code verdict).
-- result: { validationPassed: null, ...result },
- metadata: { ...state.agents[agentId].metadata,
- completionCleanup: { version: 1, status: 'pending', stages: {}, ...state.agents[agentId].metadata?.completionCleanup, startedAt: agent.startedAt },
- ...(completedCheckouts ? { checkoutCapture: checkoutCapture || { status: 'captured' } } : {}),
- },
- ...((result.success || result.cleanupPending === true) && (state.agents[agentId].metadata?.isWorktree || hasClaimCheckoutBindings(state.agents[agentId].metadata))
- ? { metadata: { ...state.agents[agentId].metadata,
- completionCleanup: { version: 1, status: 'pending', stages: {}, ...state.agents[agentId].metadata?.completionCleanup, startedAt: agent.startedAt }, checkoutCapture: checkoutCapture || { status: 'captured' },
- repoStateVerification: { status: 'pending' } } } : {}),
- ...((result.success || result.cleanupPending === true) && (state.agents[agentId].metadata?.isWorktree || state.agents[agentId].metadata?.claimPicksOwnBranch)
- ? { metadata: { ...state.agents[agentId].metadata, repoStateVerification: { status: 'pending' } } } : {}),
++ ...agent, status: 'completed', completedAt: new Date().toISOString(),
++ result: { validationPassed: null, ...result }, metadata,
};
if (completedCheckouts) state.agents[agentId].metadata = { ...state.agents[agentId].metadata, completedCheckouts };
diff --cc server/services/cosAgentLifecycle.test.js
index 04b7d9ab52,86f20434c1..69ba54d3f0
--- a/server/services/cosAgentLifecycle.test.js
+++ b/server/services/cosAgentLifecycle.test.js
@@@ -95,7 -93,7 +95,7 @@@ vi.mock('../lib/paths.js', async (impor
dataRoot: () => lazyTempDataRoot('portos-cos-lifecycle-'),
}));
- import { getAgent, getAgentPrompt, createAgentOutputBatcher, completeAgent, retryCompletionCheckoutCapture, recordRepoStateVerification, reserveRepoCleanupRecovery, recordRepoCleanupRecovery, recordCleanupOutcome, updateAgent, registerAgent, cleanupZombieAgents, filterLiveAgentIds, readAgentRecordOrUnreadable, deleteAgent, AGENT_RECORD_UNREADABLE, AGENT_OUTPUT_TAIL_LINES } from './cosAgentLifecycle.js';
-import { getAgent, getAgentPrompt, createAgentOutputBatcher, completeAgent, recordRepoStateVerification, reserveRepoCleanupRecovery, recordRepoCleanupRecovery, recordCleanupOutcome, updateAgent, registerAgent, cleanupZombieAgents, filterLiveAgentIds, readAgentRecordOrUnreadable, deleteAgent, AGENT_RECORD_UNREADABLE, AGENT_OUTPUT_TAIL_LINES } from './cosAgentLifecycle.js';
++import { getAgent, getAgentPrompt, createAgentOutputBatcher, completeAgent, recordCompletionCleanup, retryCompletionCheckoutCapture, recordRepoStateVerification, reserveRepoCleanupRecovery, recordRepoCleanupRecovery, recordCleanupOutcome, updateAgent, registerAgent, cleanupZombieAgents, filterLiveAgentIds, readAgentRecordOrUnreadable, deleteAgent, AGENT_RECORD_UNREADABLE, AGENT_OUTPUT_TAIL_LINES } from './cosAgentLifecycle.js';
import { saveState, loadState, readAgentsStateForSafetyCheck } from './cosState.js';
import { recordDomainUsage } from './domainUsage.js';
import { cosEvents } from './cosEvents.js';
@@@ -560,6 -556,6 +560,7 @@@ describe('completeAgent idempotence (#3
const result = await completeAgent(agentId, { success, cleanupPending: !success });
expect(result.result.success).toBe(success);
expect(result.metadata.repoStateVerification.status).toBe('pending');
++ expect(result.metadata.completionCleanup).toMatchObject({ status: 'abandoned', reason: 'completion-context-unavailable' });
expect(result.metadata.completedCheckouts).toEqual([receipt]);
const archived = JSON.parse(await readFile(join(mockCosState.agentsDir, result.completedAt.slice(0, 10), agentId, 'metadata.json'), 'utf8'));
expect(archived.metadata.completedCheckouts).toEqual([receipt]);
@@@ -567,7 -563,7 +568,24 @@@
expect(captureCompletedCheckouts).toHaveBeenCalledTimes(1);
});
- it('completes without checkout authority when capture fails or the claim fails', async () => {
++ it('drops replay inputs from durable terminal ledgers without erasing independent preservation holds', async () => {
++ const id = 'claim-terminal-ledger';
++ const startedAt = '2026-01-01T00:00:00Z';
++ mockCosState.state.agents[id] = { id, status: 'running', startedAt, output: [], metadata: {
++ claimPicksOwnBranch: true, completionCleanup: { version: 1, status: 'pending',
++ context: { task: { id: 'original' }, outputBuffer: 'large legacy output' },
++ replay: { version: 1, kind: 'replay', bytes: 123, sha256: 'a'.repeat(64) }, stages: {} } } };
++ const completed = await completeAgent(id, { success: true });
++ expect(await recordCompletionCleanup(id, startedAt, { status: 'failed', stages: {
++ pipeline: { status: 'failed', retryable: false, reason: 'external-state-unknown' } } })).toBe(true);
++ const archived = JSON.parse(await readFile(join(mockCosState.agentsDir, completed.completedAt.slice(0, 10), id, 'metadata.json'), 'utf8'));
++ expect(archived.metadata.completionCleanup.status).toBe('failed');
++ expect(archived.metadata.completionCleanup).not.toHaveProperty('context');
++ expect(archived.metadata.completionCleanup).not.toHaveProperty('replay');
++ expect(archived.metadata.repoStateVerification.status).toBe('pending');
++ });
++
+ it('records transient capture failure as a durable unknown obligation without rerunning finalization', async () => {
const agentId = 'claim-capture-failed';
mockCosState.state.agents[agentId] = { id: agentId, status: 'running', metadata: { claimPicksOwnBranch: true }, output: [] };
captureCompletedCheckouts.mockRejectedValueOnce(new Error('checkout unreadable'));