baxian 2.0.1 → 2.0.3

package/dist/api/projects.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { isAbsolute, normalize } from 'node:path';
-import { ROOT_AGENT_ID, TASK_ACTIVE_STATUS_SET, TASK_OWNER_ROLES, TASK_TERMINAL_STATUS_SET, } from '../shared/index.js';
+import { TASK_ACTIVE_STATUS_SET, TASK_OWNER_ROLES, TASK_TERMINAL_STATUS_SET, } from '../shared/index.js';
 import { probeTmux, runPreflight } from '../agent/preflight.js';
 import { installTmux } from '../agent/tmux-install.js';
 import { createRunner, hostGroupKey, mayShareHostAccount, resolveAgentHost, } from '../agent/runner.js';
@@ -12,7 +12,7 @@ import { AGENT_STORE_NOOP } from '../state/agent-store.js';
 import { applyConfigHotReload, prepareConfigHotReload } from '../config/hot-reload.js';
 import { gitBindingBlockerDetails, gitBindingBlockers } from './platform-guard.js';
 import { safeDriverErrorText } from '../platform/git-driver.js';
-import { projectAfterDone, projectNeedsPlatformEntry, projectReviewMode } from '../config/validator.js';
+import { projectNeedsPlatformEntry } from '../config/validator.js';
 async function fixMissingTmux(projectId, entries, agents) {
     const runsById = new Map(agents.map(run => [run.agentId, run]));
     const groups = new Map();
@@ -102,6 +102,267 @@ function omitAgentsFromProject(config, projectId, removed) {
         }),
     };
 }
+class AgentRemovalTransaction {
+    app;
+    targets;
+    operation;
+    owner;
+    ownerLabel;
+    originalStates = new Map();
+    rotatedClaims = new Map();
+    claimed = false;
+    committed = false;
+    constructor(app, targets, operation) {
+        this.app = app;
+        this.targets = targets;
+        this.operation = operation;
+        const ownerPrefix = operation === 'DELETE' ? 'deletion' : 'replacement';
+        this.owner = `${ownerPrefix}:${randomUUID()}`;
+        this.ownerLabel = ownerPrefix === 'deletion' ? 'deletion-owner' : 'replacement owner';
+    }
+    async claim() {
+        const outcome = await this.app.ctx.agentManager.scanOpenThenClaimDeletion(this.targets);
+        if (outcome.ok)
+            this.claimed = true;
+        return outcome;
+    }
+    async rotateClaims() {
+        for (const agentId of this.targets) {
+            const state = await this.app.ctx.agentStore.get(agentId);
+            this.originalStates.set(agentId, state);
+            const claim = await this.app.ctx.lockManager.claimOf(agentId);
+            if (claim && !state?.taskId) {
+                await this.rollbackClaims();
+                return { ok: false, code: 'locked', agentId };
+            }
+            if (claim && claim.taskId !== state.taskId) {
+                await this.rollbackClaims();
+                return { ok: false, code: 'stale-binding', agentId };
+            }
+            const deletionToken = randomUUID();
+            const original = claim ? { taskId: claim.taskId, token: claim.token } : null;
+            const acquired = await this.app.ctx.lockManager.rotateClaim(agentId, original ?? { unbound: true }, { taskId: this.owner, token: deletionToken });
+            if (!acquired) {
+                await this.rollbackClaims();
+                const code = original || this.operation === 'PUT' ? 'claim-changed' : 'locked';
+                return { ok: false, code, agentId };
+            }
+            this.rotatedClaims.set(agentId, { deletionToken, original });
+        }
+        return { ok: true };
+    }
+    async rollbackStateAndClaims() {
+        const failures = [];
+        const claimError = await this.rollbackClaimsForRetry();
+        if (claimError)
+            failures.push(claimError);
+        try {
+            await this.restoreStates();
+        }
+        catch (err) {
+            failures.push(err instanceof Error ? err : new Error(String(err)));
+        }
+        if (failures.length === 0)
+            return null;
+        return failures.length === 1
+            ? failures[0]
+            : new AggregateError(failures, 'Agent removal rollback failed');
+    }
+    async rollbackClaimsForRetry() {
+        try {
+            await this.rollbackClaims();
+            return null;
+        }
+        catch (err) {
+            return err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    async finalizeCommit(config, opts = {}) {
+        this.committed = true;
+        for (const agentId of this.targets)
+            this.app.ctx.agentManager.bumpDeletionGeneration(agentId);
+        const warnings = [];
+        for (const agentId of this.targets) {
+            try {
+                await this.app.ctx.agentStore.delete(agentId);
+            }
+            catch (err) {
+                const warning = this.operation === 'PUT'
+                    ? `old agent ${agentId} state delete failed post-commit: ${err instanceof Error ? err.message : String(err)}`
+                    : `agent ${agentId} state delete failed post-commit (reclaimable orphan state): ${err instanceof Error ? err.message : String(err)}`;
+                warnings.push(warning);
+                this.app.log.error({ err, agentId, targets: this.targets }, `${this.operation} /agents${this.operation === 'DELETE' ? ' Phase 3' : ''} ${warning}`);
+            }
+        }
+        await opts.beforeConfigSwitch?.(warnings);
+        const switchResult = switchCommittedAgentConfig(this.app, config, opts.divergenceTargets ?? this.targets, this.operation);
+        if (switchResult.warning)
+            warnings.push(switchResult.warning);
+        for (const agentId of this.targets) {
+            try {
+                await this.releaseClaim(agentId);
+            }
+            catch (err) {
+                const warning = this.operation === 'PUT'
+                    ? `replacement lock release for ${agentId} failed: ${err instanceof Error ? err.message : String(err)}`
+                    : `lock release for ${agentId} failed: ${err instanceof Error ? err.message : String(err)}`;
+                warnings.push(warning);
+                this.app.log.warn({ err, agentId }, `${this.operation} /agents ${this.operation === 'DELETE' ? 'Phase 3 lock release failed (post-commit)' : warning}`);
+            }
+            if (this.app.ctx.errorRecordStore) {
+                try {
+                    await this.app.ctx.errorRecordStore.purgeAgent(agentId);
+                }
+                catch (err) {
+                    const warning = `error history cleanup for ${agentId} failed: ${err instanceof Error ? err.message : String(err)}`;
+                    if (this.operation === 'PUT')
+                        warnings.push(warning);
+                    this.app.log.warn({ err, agentId }, this.operation === 'PUT' ? `PUT /agents ${warning}` : 'DELETE /agents errorRecordStore.purgeAgent failed');
+                }
+            }
+            if (this.app.ctx.petStore) {
+                try {
+                    await this.app.ctx.petStore.setAssignment(agentId, null);
+                }
+                catch (err) {
+                    const warning = `pet assignment cleanup for ${agentId} failed: ${err instanceof Error ? err.message : String(err)}`;
+                    if (this.operation === 'PUT')
+                        warnings.push(warning);
+                    this.app.log.warn({ err, agentId }, this.operation === 'PUT' ? `PUT /agents ${warning}` : 'DELETE /agents petStore.setAssignment(null) failed');
+                }
+            }
+        }
+        return { restartRequired: switchResult.restartRequired, warnings };
+    }
+    async releaseClaim(agentId) {
+        if (!(await this.settleClaim(agentId, false))) {
+            throw new Error(`${this.ownerLabel} claim changed before release`);
+        }
+    }
+    async finish() {
+        try {
+            if (this.rotatedClaims.size > 0) {
+                await this.settleClaims(!this.committed);
+            }
+        }
+        finally {
+            if (this.claimed) {
+                this.app.ctx.agentManager.releaseDeletionClaim(this.targets);
+                this.claimed = false;
+            }
+        }
+    }
+    async rollbackClaims() {
+        await this.settleClaims(true);
+    }
+    async settleClaims(restoreOriginal) {
+        const failures = [];
+        for (const agentId of [...this.rotatedClaims.keys()]) {
+            try {
+                if (!(await this.settleClaim(agentId, restoreOriginal))) {
+                    failures.push(new Error(`${agentId}: ${this.ownerLabel} claim no longer held; ` +
+                        (restoreOriginal ? 'original owner not restored' : 'claim not released')));
+                }
+            }
+            catch (err) {
+                failures.push(new Error(`${agentId}: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `lock ${restoreOriginal ? 'rollback' : 'release'} failed for ${failures.length} target(s)`);
+        }
+    }
+    async settleClaim(agentId, restoreOriginal) {
+        const rotated = this.rotatedClaims.get(agentId);
+        if (!rotated)
+            return true;
+        const settled = restoreOriginal && rotated.original
+            ? await this.app.ctx.lockManager.rotateClaim(agentId, { taskId: this.owner, token: rotated.deletionToken }, rotated.original)
+            : await this.app.ctx.lockManager.releaseIfOwner(agentId, this.owner, rotated.deletionToken);
+        if (settled)
+            this.rotatedClaims.delete(agentId);
+        return settled;
+    }
+    async restoreStates() {
+        const failures = [];
+        for (const agentId of this.targets) {
+            try {
+                const original = this.originalStates.get(agentId) ?? null;
+                if (!original) {
+                    await this.app.ctx.agentStore.delete(agentId);
+                    continue;
+                }
+                let lockToken = original.lockToken;
+                if (original.taskId) {
+                    const claim = await this.app.ctx.lockManager.claimOf(agentId);
+                    if (claim?.taskId === original.taskId) {
+                        lockToken = claim.token;
+                    }
+                    else if (claim === null) {
+                        lockToken = await this.app.ctx.lockManager.acquire(agentId, original.taskId) ?? undefined;
+                    }
+                    else {
+                        throw new Error(`lock is owned by ${claim.taskId}, expected ${original.taskId}`);
+                    }
+                    if (!lockToken || !(await this.app.ctx.lockManager.isOwner(agentId, original.taskId, lockToken))) {
+                        throw new Error(`could not restore exact task lock for ${original.taskId}`);
+                    }
+                }
+                await this.app.ctx.agentStore.set({
+                    ...original,
+                    ...(original.taskId ? { lockToken } : { lockToken: undefined }),
+                    paneId: undefined,
+                    updatedAt: new Date().toISOString(),
+                });
+            }
+            catch (err) {
+                failures.push(new Error(`${agentId}: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `Failed to roll back ${failures.length} agent removal state(s)`);
+        }
+    }
+}
+async function restoreAgentStateSnapshots(app, snapshots) {
+    const failures = [];
+    for (const [agentId, snapshot] of [...snapshots].reverse()) {
+        try {
+            if (snapshot)
+                await app.ctx.agentStore.set(snapshot);
+            else
+                await app.ctx.agentStore.delete(agentId);
+        }
+        catch (err) {
+            failures.push(new Error(`${agentId}: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    }
+    if (failures.length === 0)
+        return null;
+    return failures.length === 1
+        ? failures[0]
+        : new AggregateError(failures, `Failed to restore ${failures.length} agent state snapshot(s)`);
+}
+function switchCommittedAgentConfig(app, config, affectedAgentIds, operation) {
+    app.ctx.config = config;
+    try {
+        app.ctx.agentManager.replaceConfig(config);
+        app.ctx.tmuxProbePoller?.replaceConfig(config);
+        app.ctx.bootstrapPoller?.replaceConfig(config);
+        app.ctx.dispatchReconciler?.replaceConfig(config);
+        return { restartRequired: false };
+    }
+    catch (err) {
+        for (const agentId of affectedAgentIds) {
+            app.ctx.agentManager.retainTombstoneForDivergence(agentId);
+        }
+        app.log.fatal({ err, agentIds: affectedAgentIds }, `${operation} /agents in-memory config switch failed after disk commit; restart required`);
+        return {
+            restartRequired: true,
+            warning: 'in-memory config switch failed after disk commit; restart the server',
+        };
+    }
+}
 export async function projectRoutes(app) {
     app.get('/projects', async () => {
         return redactProjects(app.ctx.config.project);
@@ -136,22 +397,13 @@ export async function projectRoutes(app) {
         const entries = [];
         const checks = [];
         const gitPlatform = app.ctx.agentManager.agentGitPreflightContext(project.id);
-        const reviewMode = projectReviewMode(app.ctx.config, project);
-        const afterDone = projectAfterDone(app.ctx.config, project);
         for (const pair of project.agent) {
             for (const agent of pair) {
                 const host = resolveAgentHost(app.ctx.config.host, agent.host);
                 const runner = createRunner(agent.mode, host);
-                const agentGitPlatform = agent.role === 'research' && agent.workdir !== undefined
-                    ? undefined
-                    : gitPlatform;
                 entries.push({ agent, hostGroup: hostGroupKey(agent.mode, host), runner });
-                checks.push(runPreflight(runner, agent, project.repo, host, project.id, agentGitPlatform, {
-                    requireGitHubCli: reviewMode === 'server'
-                        && (agent.workdir === undefined
-                            || (agent.role === 'dev' && afterDone === 'pr')),
-                    requireGitPush: agent.role === 'dev'
-                        && (reviewMode === 'git' || afterDone !== null),
+                checks.push(runPreflight(runner, agent, project.repo, host, project.id, gitPlatform, {
+                    requireGitPush: agent.role === 'dev',
                 }).then(results => ({
                     agentId: agent.id,
                     mode: agent.mode,
@@ -160,7 +412,6 @@ export async function projectRoutes(app) {
             }
         }
         const agents = await Promise.all(checks);
-        // server 执行面手动诊断组：poller 未装配/零 agent 的部署也要能自证 merge/close 通道。
         let server;
         if (projectNeedsPlatformEntry(app.ctx.config, project)) {
             server = { results: await runServerHostChecks(app.ctx.agentManager, project.id) };
@@ -228,7 +479,7 @@ export async function projectRoutes(app) {
             return reply.status(500).send({ error: 'No config path configured' });
         }
         return withConfigLock(async () => {
-            const { id, repo, merge, specApproval, review, gitCli } = request.body ?? {};
+            const { id, repo, merge, specApproval, gitCli } = request.body ?? {};
             if (!id || typeof id !== 'string') {
                 return reply.status(400).send({ error: 'id must be a non-empty string' });
             }
@@ -243,7 +494,6 @@ export async function projectRoutes(app) {
                 repo,
                 merge: merge ?? null,
                 ...(specApproval !== undefined ? { specApproval } : {}),
-                ...(review !== undefined ? { review } : {}),
                 ...(gitCli !== undefined ? { gitCli } : {}),
                 agent: [],
             };
@@ -292,74 +542,61 @@ export async function projectRoutes(app) {
             return reply.status(500).send({ error: 'No config path configured' });
         }
         const { projectId } = request.params;
-        const body = request.body ?? {};
-        const { pairWith, ...agentInput } = body;
-        if (agentInput.role !== 'dev' && agentInput.role !== 'qa' && agentInput.role !== 'research') {
-            return reply.status(400).send({ error: 'role must be "dev", "qa", or "research"' });
+        const agents = request.body?.agents;
+        if (!Array.isArray(agents) || agents.length !== 2) {
+            return reply.status(400).send({ error: 'agents must contain exactly one dev and one qa agent' });
+        }
+        const dev = agents.find(agent => agent?.role === 'dev');
+        const qa = agents.find(agent => agent?.role === 'qa');
+        if (!dev || !qa || agents.some(agent => agent?.role !== 'dev' && agent?.role !== 'qa')) {
+            return reply.status(400).send({ error: 'agents must contain exactly one dev and one qa agent' });
         }
-        if (typeof agentInput.id !== 'string' || agentInput.id.trim().length === 0) {
-            return reply.status(400).send({ error: 'agent id is required' });
+        if (typeof dev.id !== 'string' || dev.id.trim() === ''
+            || typeof qa.id !== 'string' || qa.id.trim() === '') {
+            return reply.status(400).send({ error: 'both agent ids are required' });
         }
-        let creationToken = '';
+        if (dev.id === qa.id) {
+            return reply.status(409).send({ error: `Agent id "${dev.id}" is duplicated within the group` });
+        }
+        const creationTokens = new Map();
+        const warnings = [];
+        let restartRequired = false;
         const phase1Result = await withConfigLock(async () => {
             const project = app.ctx.config.project.find(p => p.id === projectId);
             if (!project) {
                 return reply.status(404).send({ error: `Project "${projectId}" not found` });
             }
-            const existsGlobally = app.ctx.config.project.some(p => p.agent.some(pair => pair.some(a => a.id === agentInput.id)));
-            if (existsGlobally) {
-                return reply.status(409).send({ error: `Agent id "${agentInput.id}" already exists` });
-            }
-            // A tombstone in flight (or retained after a DELETE memory-switch divergence) must block a
-            // same-id rebuild, else the fail-stop could be silently bypassed.
-            if (app.ctx.agentManager.isDeletionInFlight(agentInput.id)) {
-                return reply.status(409).send({
-                    error: `Agent id "${agentInput.id}" is being deleted (or its deletion diverged); retry later or restart the server`,
-                });
-            }
-            const workdirConflict = findConfiguredWorkdirConflict(app.ctx.config, agentInput);
-            if (workdirConflict) {
-                return reply.status(409).send({
-                    error: `Workdir "${normalize(agentInput.workdir)}" is already used by agent ` +
-                        `"${workdirConflict}" on the same host; different agents must not share a directory`,
-                });
-            }
-            if (agentInput.role !== 'dev') {
-                if (!pairWith) {
-                    return reply.status(400).send({ error: `pairWith required when role=${agentInput.role}` });
+            let workdirConfig = app.ctx.config;
+            for (const agentInput of [dev, qa]) {
+                const existsGlobally = app.ctx.config.project.some(p => p.agent.some(group => group.some(agent => agent.id === agentInput.id)));
+                if (existsGlobally) {
+                    return reply.status(409).send({ error: `Agent id "${agentInput.id}" already exists` });
                 }
-                const targetGroup = project.agent.find(group => group.some(agent => agent.id === pairWith && agent.role === 'dev')
-                    && !group.some(agent => agent.role === agentInput.role));
-                if (!targetGroup) {
-                    return reply.status(400).send({
-                        error: `pairWith "${pairWith}" must reference a dev group in this project that has no ${agentInput.role} yet`,
+                if (app.ctx.agentManager.isDeletionInFlight(agentInput.id)) {
+                    return reply.status(409).send({
+                        error: `Agent id "${agentInput.id}" is being deleted (or its deletion diverged); retry later or restart the server`,
                     });
                 }
-                const devState = await app.ctx.agentStore.get(pairWith);
-                if (devState?.creationToken) {
+                const workdirConflict = findConfiguredWorkdirConflict(workdirConfig, agentInput);
+                if (workdirConflict) {
                     return reply.status(409).send({
-                        error: `dev agent "${pairWith}" is being created; please retry later`,
+                        error: `Workdir "${normalize(agentInput.workdir)}" is already used by agent ` +
+                            `"${workdirConflict}" on the same host; different agents must not share a directory`,
                     });
                 }
+                workdirConfig = {
+                    ...workdirConfig,
+                    project: workdirConfig.project.map(p => p.id === projectId
+                        ? { ...p, agent: [...p.agent, [agentInput]] }
+                        : p),
+                };
             }
-            if (agentInput.role === 'dev' && pairWith) {
-                return reply.status(400).send({ error: 'pairWith is only valid for qa or research agents' });
-            }
-            const newProjects = app.ctx.config.project.map((p) => {
-                if (p.id !== projectId)
-                    return p;
-                if (agentInput.role === 'dev') {
-                    return { ...p, agent: [...p.agent, [agentInput]] };
-                }
-                const newAgent = p.agent.map(group => {
-                    if (group.some(agent => agent.id === pairWith && agent.role === 'dev')) {
-                        return [...group, agentInput];
-                    }
-                    return group;
-                });
-                return { ...p, agent: newAgent };
-            });
-            const merged = { ...app.ctx.config, project: newProjects };
+            const merged = {
+                ...app.ctx.config,
+                project: app.ctx.config.project.map(p => p.id === projectId
+                    ? { ...p, agent: [...p.agent, [dev, qa]] }
+                    : p),
+            };
             let validated;
             try {
                 validated = prepareConfig(merged);
@@ -370,104 +607,278 @@ export async function projectRoutes(app) {
                 }
                 throw err;
             }
-            await saveConfig(app.ctx.configPath, validated);
-            app.ctx.config = validated;
-            app.ctx.agentManager.replaceConfig(validated);
-            app.ctx.tmuxProbePoller?.replaceConfig(validated);
-            app.ctx.bootstrapPoller?.replaceConfig(validated);
-            app.ctx.dispatchReconciler?.replaceConfig(validated);
-            creationToken = randomUUID();
+            const stateSnapshots = new Map();
+            for (const agent of [dev, qa]) {
+                stateSnapshots.set(agent.id, await app.ctx.agentStore.get(agent.id));
+            }
             const now = new Date().toISOString();
-            await app.ctx.agentStore.set({
-                id: agentInput.id,
-                projectId,
-                creationToken,
-                updatedAt: now,
-            });
+            try {
+                for (const agent of [dev, qa]) {
+                    const creationToken = randomUUID();
+                    await app.ctx.agentStore.set({
+                        id: agent.id,
+                        projectId,
+                        creationToken,
+                        updatedAt: now,
+                    });
+                    creationTokens.set(agent.id, creationToken);
+                }
+            }
+            catch (err) {
+                creationTokens.clear();
+                const rollbackError = await restoreAgentStateSnapshots(app, stateSnapshots);
+                if (rollbackError) {
+                    app.log.error({ err: rollbackError, agentIds: [dev.id, qa.id] }, 'POST /agents state initialization rollback failed');
+                    return reply.status(500).send({
+                        error: `agent state initialization failed and staged state could not be restored safely: ${rollbackError.message}`,
+                    });
+                }
+                return reply.status(500).send({
+                    error: `agent state initialization failed; the group was not committed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            try {
+                await saveConfig(app.ctx.configPath, validated);
+            }
+            catch (err) {
+                creationTokens.clear();
+                const rollbackError = await restoreAgentStateSnapshots(app, stateSnapshots);
+                if (rollbackError) {
+                    app.log.error({ err: rollbackError, agentIds: [dev.id, qa.id] }, 'POST /agents config save state rollback failed');
+                    return reply.status(500).send({
+                        error: `config save failed and staged agent state could not be restored safely: ${rollbackError.message}`,
+                    });
+                }
+                return reply.status(500).send({
+                    error: `failed to persist agent group config; staged agent state was restored: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            const switchResult = switchCommittedAgentConfig(app, validated, [dev.id, qa.id], 'POST');
+            restartRequired = switchResult.restartRequired;
+            if (switchResult.warning) {
+                creationTokens.clear();
+                warnings.push(switchResult.warning);
+                return null;
+            }
             return null;
         });
         if (phase1Result)
             return phase1Result;
         if (reply.sent)
             return reply;
-        void app.ctx.agentManager
-            .startBootstrapAsync(agentInput.id, creationToken)
-            .catch((err) => {
-            app.log.error({ err, agentId: agentInput.id }, 'POST /agents startBootstrapAsync threw — should be impossible (it never throws)');
-        });
+        for (const [agentId, creationToken] of creationTokens) {
+            void app.ctx.agentManager.startBootstrapAsync(agentId, creationToken).catch((err) => {
+                app.log.error({ err, agentId }, 'POST /agents startBootstrapAsync threw — should be impossible');
+            });
+        }
         const storedProject = app.ctx.config.project.find(p => p.id === projectId);
-        const storedAgent = storedProject.agent.flat().find(a => a.id === agentInput.id);
+        const storedGroup = storedProject.agent.find(group => group.some(agent => agent.id === dev.id));
         return reply.status(201).send({
-            agent: storedAgent,
+            agents: storedGroup,
             runtimeStatus: 'pending',
-            restartRequired: false,
+            restartRequired,
+            ...(warnings.length ? { warnings } : {}),
         });
     });
-    app.delete('/projects/:projectId/agents/:agentId', async (request, reply) => {
+    app.put('/projects/:projectId/agents/:agentId', async (request, reply) => {
         if (!app.ctx.configPath) {
             return reply.status(500).send({ error: 'No config path configured' });
         }
         const { projectId, agentId } = request.params;
-        let targets = [];
-        const originalStates = new Map();
-        let originalConfigHash = '';
-        let validatedAfterRemove = null;
-        // Per-attempt deletion owner: phase 1 rotates every claim onto it (so a concurrent maintenance release with the old shared token fails owner-scoped); phase 3 releases it, rollback rotates back to the original.
-        const deletionOwner = `deletion:${randomUUID()}`;
-        const rotatedClaims = new Map();
-        const releaseDeletionClaims = async () => {
-            for (const [id, r] of rotatedClaims) {
-                await app.ctx.lockManager.releaseIfOwner(id, deletionOwner, r.deletionToken);
-            }
-            rotatedClaims.clear();
-        };
-        const rollbackClaims = async () => {
-            const failures = [];
-            const restored = [];
-            for (const [id, r] of rotatedClaims) {
-                try {
-                    const ok = r.original
-                        ? await app.ctx.lockManager.rotateClaim(id, { taskId: deletionOwner, token: r.deletionToken }, r.original)
-                        : await app.ctx.lockManager.releaseIfOwner(id, deletionOwner, r.deletionToken);
-                    if (ok)
-                        restored.push(id);
-                    else
-                        failures.push(`${id}: deletion-owner claim no longer held; original owner not restored`);
-                }
-                catch (err) {
-                    failures.push(`${id}: ${err instanceof Error ? err.message : String(err)}`);
-                }
+        const replacement = request.body;
+        if (!replacement || (replacement.role !== 'dev' && replacement.role !== 'qa')) {
+            return reply.status(400).send({ error: 'replacement role must be "dev" or "qa"' });
+        }
+        if (typeof replacement.id !== 'string' || replacement.id.trim() === '') {
+            return reply.status(400).send({ error: 'replacement agent id is required' });
+        }
+        if (replacement.id === agentId) {
+            return reply.status(400).send({ error: 'replacement agent id must differ from the current agent id' });
+        }
+        let bootstrap = null;
+        let replacementResult = null;
+        const phaseResult = await withConfigLock(async () => {
+            const project = app.ctx.config.project.find(p => p.id === projectId);
+            if (!project) {
+                return reply.status(404).send({ error: `Project "${projectId}" not found` });
             }
-            // Clear only successfully-restored entries; keep failed ones as evidence for the caller/finally.
-            for (const id of restored)
-                rotatedClaims.delete(id);
-            if (failures.length > 0) {
-                throw new AggregateError(failures.map(f => new Error(f)), `lock rollback failed for ${failures.length} target(s)`);
+            const group = project.agent.find(candidate => candidate.some(agent => agent.id === agentId));
+            const current = group?.find(agent => agent.id === agentId);
+            if (!group || !current) {
+                return reply.status(404).send({ error: `Agent "${agentId}" not found in project "${projectId}"` });
             }
-        };
-        const rollbackAndRelease = async () => {
-            let rollbackError = null;
-            // Rotate claims back to their original owners FIRST, so state restore sees the original claim.
+            if (replacement.role !== current.role) {
+                return reply.status(400).send({
+                    error: `replacement role must remain "${current.role}" so the group keeps one dev and one qa`,
+                });
+            }
+            const existsGlobally = app.ctx.config.project.some(p => p.agent.some(candidate => candidate.some(agent => agent.id === replacement.id)));
+            if (existsGlobally) {
+                return reply.status(409).send({ error: `Agent id "${replacement.id}" already exists` });
+            }
+            if (app.ctx.agentManager.isDeletionInFlight(replacement.id)) {
+                return reply.status(409).send({
+                    error: `Agent id "${replacement.id}" is being deleted (or its deletion diverged); retry later or restart the server`,
+                });
+            }
+            const workdirConflict = findConfiguredWorkdirConflict(app.ctx.config, replacement, new Set([agentId]));
+            if (workdirConflict) {
+                return reply.status(409).send({
+                    error: `Workdir "${normalize(replacement.workdir)}" is already used by agent ` +
+                        `"${workdirConflict}" on the same host; different agents must not share a directory`,
+                });
+            }
+            const nextConfig = {
+                ...app.ctx.config,
+                project: app.ctx.config.project.map(p => p.id === projectId
+                    ? {
+                        ...p,
+                        agent: p.agent.map(candidate => candidate.some(agent => agent.id === agentId)
+                            ? candidate.map(agent => agent.id === agentId ? replacement : agent)
+                            : candidate),
+                    }
+                    : p),
+            };
+            let validated;
             try {
-                await rollbackClaims();
+                validated = prepareConfig(nextConfig);
             }
             catch (err) {
-                rollbackError = err instanceof Error ? err : new Error(String(err));
+                if (err instanceof ConfigValidationError) {
+                    return reply.status(400).send({ error: 'Invalid config', details: err.errors });
+                }
+                throw err;
             }
+            const storedReplacement = validated.project
+                .find(candidate => candidate.id === projectId)
+                .agent.flat()
+                .find(agent => agent.id === replacement.id);
+            const removal = new AgentRemovalTransaction(app, [agentId], 'PUT');
             try {
-                await rollbackPerTargetState(app, targets, originalStates);
+                const deletion = await removal.claim();
+                if (!deletion.ok) {
+                    switch (deletion.code) {
+                        case 'active':
+                            return reply.status(409).send({
+                                error: `Agent "${deletion.agentId}" is still active on task ${deletion.taskId}; finish or cancel it before replacement.`,
+                            });
+                        case 'bootstrapping':
+                            return reply.status(409).send({
+                                error: `Agent "${deletion.agentId}" is bootstrapping; retry after bootstrap settles.`,
+                            });
+                        case 'referencing':
+                            return reply.status(409).send({
+                                error: `Agent "${agentId}" is referenced by open task ${deletion.taskId}; finish or cancel it before replacement.`,
+                            });
+                        case 'already-deleting':
+                            return reply.status(409).send({
+                                error: `Agent "${deletion.agentId}" deletion or replacement is already in progress.`,
+                            });
+                    }
+                }
+                const rotation = await removal.rotateClaims();
+                if (!rotation.ok) {
+                    switch (rotation.code) {
+                        case 'locked':
+                        case 'stale-binding':
+                            return reply.status(409).send({
+                                error: `Agent "${rotation.agentId}" is locked by another operation; retry replacement later.`,
+                            });
+                        case 'claim-changed':
+                            return reply.status(409).send({
+                                error: `Agent "${rotation.agentId}" lock changed; retry replacement.`,
+                            });
+                    }
+                }
+                try {
+                    await app.ctx.agentManager.cleanupRemovedAgentRuntime([agentId]);
+                }
+                catch (err) {
+                    const rollbackError = await removal.rollbackStateAndClaims();
+                    if (rollbackError) {
+                        app.log.error({ err: rollbackError, agentId }, 'PUT /agents replacement rollback failed');
+                        return reply.status(500).send({
+                            error: `runtime cleanup failed and the original agent state could not be restored safely: ${rollbackError.message}`,
+                        });
+                    }
+                    return reply.status(502).send({
+                        error: `runtime cleanup failed for ${agentId}; the original config, state, and lock were restored`,
+                        detail: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                try {
+                    await saveConfig(app.ctx.configPath, validated);
+                }
+                catch (err) {
+                    const rollbackError = await removal.rollbackStateAndClaims();
+                    if (rollbackError) {
+                        app.log.error({ err: rollbackError, agentId }, 'PUT /agents save rollback failed');
+                        return reply.status(500).send({
+                            error: `config save failed and the original agent state could not be restored safely: ${rollbackError.message}`,
+                        });
+                    }
+                    return reply.status(500).send({
+                        error: `failed to persist replacement config; the original agent state and lock were restored: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                }
+                const commitResult = await removal.finalizeCommit(validated, {
+                    divergenceTargets: [agentId, replacement.id],
+                    beforeConfigSwitch: async (warnings) => {
+                        const creationToken = randomUUID();
+                        try {
+                            await app.ctx.agentStore.set({
+                                id: replacement.id,
+                                projectId,
+                                creationToken,
+                                updatedAt: new Date().toISOString(),
+                            });
+                            bootstrap = { agentId: replacement.id, creationToken };
+                        }
+                        catch (err) {
+                            const warning = `replacement agent ${replacement.id} state initialization failed: ${err instanceof Error ? err.message : String(err)}`;
+                            warnings.push(warning);
+                            app.log.error({ err, agentId: replacement.id }, `PUT /agents ${warning}`);
+                        }
+                    },
+                });
+                if (commitResult.restartRequired)
+                    bootstrap = null;
+                replacementResult = {
+                    agent: storedReplacement,
+                    replaced: agentId,
+                    runtimeStatus: 'pending',
+                    restartRequired: commitResult.restartRequired,
+                    ...(commitResult.warnings.length ? { warnings: commitResult.warnings } : {}),
+                };
+                return null;
             }
-            catch (err) {
-                const restoreError = err instanceof Error ? err : new Error(String(err));
-                rollbackError = rollbackError
-                    ? new AggregateError([rollbackError, restoreError], 'Agent deletion rollback and lock release failed')
-                    : restoreError;
+            finally {
+                await removal.finish().catch((err) => {
+                    app.log.error({ err, agentId }, 'PUT /agents leftover replacement cleanup failed');
+                });
             }
-            return rollbackError;
-        };
-        let claimedTargets = [];
-        // True only after saveConfig commits: pre-commit escapes must rollback to the original owners; post-commit just releases.
-        let committed = false;
+        });
+        if (phaseResult)
+            return phaseResult;
+        if (reply.sent)
+            return reply;
+        if (bootstrap) {
+            const { agentId: replacementId, creationToken } = bootstrap;
+            void app.ctx.agentManager.startBootstrapAsync(replacementId, creationToken).catch((err) => {
+                app.log.error({ err, agentId: replacementId }, 'PUT /agents startBootstrapAsync threw — should be impossible');
+            });
+        }
+        return reply.send(replacementResult);
+    });
+    app.delete('/projects/:projectId/agents/:agentId', async (request, reply) => {
+        if (!app.ctx.configPath) {
+            return reply.status(500).send({ error: 'No config path configured' });
+        }
+        const { projectId, agentId } = request.params;
+        let targets = [];
+        let originalConfigHash = '';
+        let validatedAfterRemove = null;
+        const removalRef = { current: null };
         try {
             const phase1Result = await withConfigLock(async () => {
                 const project = app.ctx.config.project.find(p => p.id === projectId);
@@ -479,8 +890,9 @@ export async function projectRoutes(app) {
                     return reply.status(404).send({ error: `Agent "${agentId}" not found in project "${projectId}"` });
                 }
                 targets = app.ctx.agentManager.prepareRemoveTargets(agentId).targets.slice().sort();
-                // Scan + tombstone-claim run atomically under the manager's task lock, blocking a concurrent createTask/dispatchPendingTask from committing onto a target mid-delete.
-                const claim = await app.ctx.agentManager.scanActiveThenClaimDeletion(targets);
+                const transaction = new AgentRemovalTransaction(app, targets, 'DELETE');
+                removalRef.current = transaction;
+                const claim = await transaction.claim();
                 if (!claim.ok) {
                     switch (claim.code) {
                         case 'active':
@@ -494,7 +906,7 @@ export async function projectRoutes(app) {
                             });
                         case 'referencing':
                             return reply.status(409).send({
-                                error: `Agent "${agentId}" is referenced by active task ${claim.taskId}; ` +
+                                error: `Agent "${agentId}" is referenced by open task ${claim.taskId}; ` +
                                     `cancel or finish that task before deleting (would dangle its dev/QA/retry reference).`,
                             });
                         case 'already-deleting':
@@ -503,49 +915,23 @@ export async function projectRoutes(app) {
                             });
                     }
                 }
-                claimedTargets = targets.slice();
-                for (const id of targets) {
-                    const state = await app.ctx.agentStore.get(id);
-                    const claim = await app.ctx.lockManager.claimOf(id);
-                    const deletionToken = randomUUID();
-                    if (claim === null) {
-                        // No lock file (unbound, or a stale binding whose lock is gone): rotate from unbound == acquire.
-                        const ok = await app.ctx.lockManager.rotateClaim(id, { unbound: true }, { taskId: deletionOwner, token: deletionToken });
-                        if (!ok) {
-                            await rollbackClaims();
+                const rotation = await transaction.rotateClaims();
+                if (!rotation.ok) {
+                    switch (rotation.code) {
+                        case 'locked':
                             return reply.status(409).send({
-                                error: `Agent "${id}" is currently locked by another op; please retry later`,
+                                error: `Agent "${rotation.agentId}" is currently locked by another op; please retry later`,
+                            });
+                        case 'stale-binding':
+                            return reply.status(409).send({
+                                error: `Agent "${rotation.agentId}" has a stale task binding whose exclusive lock is owned by another ` +
+                                    `operation; retry after it finishes.`,
+                            });
+                        case 'claim-changed':
+                            return reply.status(409).send({
+                                error: `Agent "${rotation.agentId}" lock changed while claiming it for deletion; please retry.`,
                             });
-                        }
-                        rotatedClaims.set(id, { deletionToken, original: null });
-                        continue;
-                    }
-                    // A lock exists — only rotate it if it belongs to THIS agent's (now-terminal) task binding;
-                    // a lock owned by an unrelated live op must not be stolen.
-                    if (state?.taskId && claim.taskId !== state.taskId) {
-                        await rollbackClaims();
-                        return reply.status(409).send({
-                            error: `Agent "${id}" has a stale task binding whose exclusive lock is owned by another operation; retry after it finishes.`,
-                        });
-                    }
-                    if (!state?.taskId) {
-                        await rollbackClaims();
-                        return reply.status(409).send({
-                            error: `Agent "${id}" is currently locked by another op; please retry later`,
-                        });
-                    }
-                    const ok = await app.ctx.lockManager.rotateClaim(id, { taskId: claim.taskId, token: claim.token }, { taskId: deletionOwner, token: deletionToken });
-                    if (!ok) {
-                        await rollbackClaims();
-                        return reply.status(409).send({
-                            error: `Agent "${id}" lock changed while claiming it for deletion; please retry.`,
-                        });
                     }
-                    rotatedClaims.set(id, { deletionToken, original: { taskId: claim.taskId, token: claim.token } });
-                }
-                for (const id of targets) {
-                    const existing = await app.ctx.agentStore.get(id);
-                    originalStates.set(id, existing);
                 }
                 originalConfigHash = configHash(app.ctx.config);
                 const removeRequest = omitAgentsFromProject(app.ctx.config, projectId, targets);
@@ -553,7 +939,9 @@ export async function projectRoutes(app) {
                     validatedAfterRemove = prepareConfig(removeRequest);
                 }
                 catch (err) {
-                    await rollbackClaims();
+                    const rollbackError = await transaction.rollbackClaimsForRetry();
+                    if (rollbackError)
+                        throw rollbackError;
                     if (err instanceof ConfigValidationError) {
                         return reply.status(400).send({ error: 'Invalid config', details: err.errors });
                     }
@@ -571,9 +959,9 @@ export async function projectRoutes(app) {
             catch (err) {
                 const failures = err instanceof CleanupFailedError
                     ? err.failures
-                    : [{ agentId: agentId, step: 'runtime.cleanup', error: err }];
+                    : [{ agentId, step: 'runtime.cleanup', error: err }];
                 app.log.error({ failures, targets }, 'DELETE /agents cleanupRemovedAgentRuntime failed; rolling back state and locks');
-                const rollbackError = await withConfigLock(rollbackAndRelease);
+                const rollbackError = await withConfigLock(() => removalRef.current.rollbackStateAndClaims());
                 if (rollbackError) {
                     app.log.error({ err: rollbackError, targets }, 'DELETE /agents rollback failed');
                     return reply.status(500).send({
@@ -583,10 +971,14 @@ export async function projectRoutes(app) {
                 return reply.status(502).send({
                     error: `runtime cleanup failed for ${targets.join(',')}; agent state and exact task locks were restored. ` +
                         `Fix the underlying SSH / tmux / Workdir issue and retry DELETE.`,
-                    failures: failures.map(f => ({ agentId: f.agentId, step: f.step,
-                        error: f.error instanceof Error ? f.error.message : String(f.error) })),
+                    failures: failures.map(f => ({
+                        agentId: f.agentId,
+                        step: f.step,
+                        error: f.error instanceof Error ? f.error.message : String(f.error),
+                    })),
                 });
             }
+            const transaction = removalRef.current;
             const phase3Result = await withConfigLock(async () => {
                 const currentHash = configHash(app.ctx.config);
                 const rollbackBase = currentHash === originalConfigHash
@@ -597,7 +989,7 @@ export async function projectRoutes(app) {
                     validated = prepareConfig(rollbackBase);
                 }
                 catch (err) {
-                    const rollbackError = await rollbackAndRelease();
+                    const rollbackError = await transaction.rollbackStateAndClaims();
                     if (rollbackError) {
                         app.log.error({ err: rollbackError, targets }, 'DELETE /agents rollback after config validation failed');
                         return reply.status(500).send({
@@ -609,106 +1001,36 @@ export async function projectRoutes(app) {
                     }
                     throw err;
                 }
-                // Its only caller (saveConfig failure) runs before any state delete, so recovery is just rotating each claim back to its original owner.
-                const restoreForRetry = async () => {
-                    try {
-                        await rollbackClaims();
-                        return null;
-                    }
-                    catch (e) {
-                        return e instanceof Error ? e : new Error(String(e));
-                    }
-                };
-                // Step 1 — commit config (atomic saveConfig) BEFORE any state delete: a crash between the two would else leave config referencing an agent whose state is gone, behind a stuck deletion:<uuid> lock (unrecoverable wedge).
-                const warnings = [];
                 try {
                     await saveConfig(app.ctx.configPath, validated);
                 }
                 catch (err) {
                     app.log.error({ err, targets }, 'DELETE /agents Phase 3 saveConfig failed; releasing acquired locks (no state was deleted yet)');
-                    const restoreError = await restoreForRetry();
-                    if (restoreError) {
+                    const rollbackError = await transaction.rollbackClaimsForRetry();
+                    if (rollbackError) {
                         return reply.status(500).send({
-                            error: `failed to persist config and roll the deletion locks back safely: ${restoreError.message}`,
+                            error: `failed to persist config and roll the deletion locks back safely: ${rollbackError.message}`,
                         });
                     }
                     return reply.status(500).send({
                         error: 'failed to persist config after runtime cleanup; this attempt\'s locks were released and agent state left intact',
                     });
                 }
-                // Disk committed — point of no return. Bump the generation before any memory switch that could throw.
-                committed = true;
-                for (const id of targets)
-                    app.ctx.agentManager.bumpDeletionGeneration(id);
-                // Step 2 — delete agent state POST-commit (best-effort): config already dropped these agents, so a failure here leaves only reclaimable orphan state.
-                for (const id of targets) {
-                    try {
-                        await app.ctx.agentStore.delete(id);
-                    }
-                    catch (delErr) {
-                        const msg = `agent ${id} state delete failed post-commit (reclaimable orphan state): ${delErr instanceof Error ? delErr.message : String(delErr)}`;
-                        app.log.error({ err: delErr, agentId: id, targets }, `DELETE /agents Phase 3 ${msg}`);
-                        warnings.push(msg);
-                    }
-                }
-                // Step 3 — in-memory switch (never reverts; pollers cleared once). A throw here is a program bug: fail-stop by retaining the tombstone so nothing re-creates the id.
-                try {
-                    app.ctx.config = validated;
-                    app.ctx.agentManager.replaceConfig(validated);
-                    app.ctx.tmuxProbePoller?.replaceConfig(validated);
-                    app.ctx.bootstrapPoller?.replaceConfig(validated);
-                    app.ctx.dispatchReconciler?.replaceConfig(validated);
-                }
-                catch (err) {
-                    for (const id of targets)
-                        app.ctx.agentManager.retainTombstoneForDivergence(id);
-                    app.log.fatal({ err, targets }, 'DELETE /agents Phase 3 replaceConfig threw AFTER disk commit; tombstone retained, restart advised');
-                }
-                // Step 4 — owner-scoped release of the deletion-owner claims + best-effort side cleanup; past the commit point, failures are surfaced as warnings, never rolled back.
-                for (const id of targets) {
-                    const rotated = rotatedClaims.get(id);
-                    if (rotated) {
-                        try {
-                            await app.ctx.lockManager.releaseIfOwner(id, deletionOwner, rotated.deletionToken);
-                            rotatedClaims.delete(id);
-                        }
-                        catch (releaseErr) {
-                            warnings.push(`lock release for ${id} failed: ${releaseErr instanceof Error ? releaseErr.message : String(releaseErr)}`);
-                            app.log.warn({ err: releaseErr, agentId: id }, 'DELETE /agents Phase 3 lock release failed (post-commit)');
-                        }
-                    }
-                    if (app.ctx.errorRecordStore) {
-                        try {
-                            await app.ctx.errorRecordStore.purgeAgent(id);
-                        }
-                        catch (purgeErr) {
-                            app.log.warn({ err: purgeErr, agentId: id }, 'DELETE /agents errorRecordStore.purgeAgent failed');
-                        }
-                    }
-                    if (app.ctx.petStore) {
-                        try {
-                            await app.ctx.petStore.setAssignment(id, null);
-                        }
-                        catch (petErr) {
-                            app.log.warn({ err: petErr, agentId: id }, 'DELETE /agents petStore.setAssignment(null) failed');
-                        }
-                    }
-                }
-                return reply.send({ removed: targets, restartRequired: false, ...(warnings.length ? { warnings } : {}) });
+                const commitResult = await transaction.finalizeCommit(validated);
+                return reply.send({
+                    removed: targets,
+                    restartRequired: commitResult.restartRequired,
+                    ...(commitResult.warnings.length ? { warnings: commitResult.warnings } : {}),
+                });
             });
             return phase3Result;
         }
         finally {
-            // Leftover rotated claims (normal paths clear them): pre-commit escapes roll back to the original owners; releasing pre-commit would strand a lockless binding. Post-commit the agents are gone, so just release.
-            if (rotatedClaims.size > 0) {
-                const cleanup = committed ? releaseDeletionClaims() : rollbackClaims();
-                await cleanup.catch((err) => {
-                    app.log.error({ err, committed }, 'DELETE /agents: leftover deletion-claim cleanup failed');
+            if (removalRef.current) {
+                await removalRef.current.finish().catch((err) => {
+                    app.log.error({ err }, 'DELETE /agents leftover deletion-claim cleanup failed');
                 });
             }
-            if (claimedTargets.length > 0) {
-                app.ctx.agentManager.releaseDeletionClaim(claimedTargets);
-            }
         }
     });
     app.post('/projects/:projectId/agents/:agentId/resume', async (request, reply) => {
@@ -833,7 +1155,6 @@ export async function projectRoutes(app) {
         try {
             const result = await app.ctx.agentManager.ensureSession(agentId, 'runtime', { expectedGeneration: genAtEntry });
             const now = new Date().toISOString();
-            // Generation-gated: a DELETE→recreate during ensureSession leaves a NEW state, so an existing-only check would bind the stale paneId to the wrong incarnation.
             const paneCommit = await app.ctx.agentStore.update(agentId, (existing) => {
                 if (!existing
                     || app.ctx.agentManager.isDeletionInFlight(agentId)
@@ -842,7 +1163,6 @@ export async function projectRoutes(app) {
                 }
                 return { ...existing, paneId: result.paneId, updatedAt: now };
             });
-            // No-op ⇒ a DELETE→recreate raced ensureSession; fail closed rather than run stale retry cleanup against the new incarnation.
             if (paneCommit !== 'committed') {
                 if (maintenanceToken && acquiredMaintenanceLock) {
                     await app.ctx.lockManager.releaseIfOwner(agentId, maintenanceLockOwner, maintenanceToken);
@@ -878,7 +1198,7 @@ export async function projectRoutes(app) {
         return reply.send({ ok: true, agentId });
     });
 }
-function findConfiguredWorkdirConflict(config, candidate) {
+function findConfiguredWorkdirConflict(config, candidate, ignoredAgentIds = new Set()) {
     if (typeof candidate.workdir !== 'string'
         || candidate.workdir.trim() === ''
         || !isAbsolute(candidate.workdir)
@@ -890,14 +1210,6 @@ function findConfiguredWorkdirConflict(config, candidate) {
         return null;
     const candidatePath = normalize(candidate.workdir);
     const configured = [];
-    if (config.root) {
-        configured.push({
-            id: ROOT_AGENT_ID,
-            mode: config.root.mode,
-            host: resolveAgentHost(config.host, config.root.host),
-            workdir: config.root.workdir,
-        });
-    }
     for (const project of config.project) {
         for (const existing of project.agent.flat()) {
             if (!existing.workdir)
@@ -911,6 +1223,8 @@ function findConfiguredWorkdirConflict(config, candidate) {
         }
     }
     for (const existing of configured) {
+        if (ignoredAgentIds.has(existing.id))
+            continue;
         if (normalize(existing.workdir) === candidatePath
             && mayShareHostAccount(existing.mode, existing.host, candidate.mode, resolvedCandidateHost)) {
             return existing.id;
@@ -1000,7 +1314,6 @@ async function pendingCleanupAfterReplReady(app, agentId, takeover, maintenance)
         }
         catch (err) {
             app.log.error({ err, agentId, taskId }, 'restart/retry task prompt redispatch failed');
-            // Bound to the pre-restart task tuple: a successor pass rotated mid-replay must not be held.
             const held = await app.ctx.agentManager.holdReplayFailureIfCurrent(agentId, task, 'restart-redispatch-failed', `REPL restarted but the active task prompt could not be restored: ${err instanceof Error ? err.message : String(err)}`, {
                 phase: state?.status === 'awaiting_human' ? state.awaitingPhase : undefined,
                 since: state?.status === 'awaiting_human' ? state.awaitingSince : undefined,
@@ -1012,7 +1325,6 @@ async function pendingCleanupAfterReplReady(app, agentId, takeover, maintenance)
             return;
         }
     }
-    // Both fences ride inside the release itself: a hold or pass rotation landing after any pre-read survives.
     await app.ctx.agentManager.markAgentWaiting(agentId, taskId, {
         allowAwaitingHuman: true,
         clearAwaitingHuman: true,
@@ -1024,49 +1336,4 @@ async function pendingCleanupAfterReplReady(app, agentId, takeover, maintenance)
         },
     });
 }
-async function rollbackPerTargetState(app, targets, originalStates) {
-    const failures = [];
-    for (const id of targets) {
-        const original = originalStates.get(id) ?? null;
-        if (!original) {
-            try {
-                await app.ctx.agentStore.delete(id);
-            }
-            catch (err) {
-                failures.push(new Error(`delete transient state for ${id}: ${err instanceof Error ? err.message : String(err)}`));
-            }
-            continue;
-        }
-        try {
-            let lockToken = original.lockToken;
-            if (original.taskId) {
-                const claim = await app.ctx.lockManager.claimOf(id);
-                if (claim?.taskId === original.taskId) {
-                    lockToken = claim.token;
-                }
-                else if (claim === null) {
-                    lockToken = await app.ctx.lockManager.acquire(id, original.taskId) ?? undefined;
-                }
-                else {
-                    throw new Error(`lock is owned by ${claim.taskId}, expected ${original.taskId}`);
-                }
-                if (!lockToken || !(await app.ctx.lockManager.isOwner(id, original.taskId, lockToken))) {
-                    throw new Error(`could not restore exact task lock for ${original.taskId}`);
-                }
-            }
-            await app.ctx.agentStore.set({
-                ...original,
-                ...(original.taskId ? { lockToken } : { lockToken: undefined }),
-                paneId: undefined,
-                updatedAt: new Date().toISOString(),
-            });
-        }
-        catch (err) {
-            failures.push(new Error(`restore state for ${id}: ${err instanceof Error ? err.message : String(err)}`));
-        }
-    }
-    if (failures.length > 0) {
-        throw new AggregateError(failures, `Failed to roll back ${failures.length} agent deletion state(s)`);
-    }
-}
 //# sourceMappingURL=projects.js.map