@nanmicoder/dsh-agent-teams 0.1.5 → 0.1.7

package/lib/tools.js

@@ -12,8 +12,10 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { join } from 'node:path';
 import { appendTeamEvent, captainSessionOf } from "./events.js";
-import { appendMailbox, archiveTeamDir, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, readMailbox, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
-import { deliverToMember, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, } from "./members.js";
+import { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
+import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, } from "./members.js";
+import { TERMINAL_TASK_STATUSES } from "./types.js";
+import { installTeamScheduler } from "./scheduler.js";
 /** The caller agent, or a loud failure for non-agent callers. */
 function requireCaptain(exec) {
     if (!exec.agent) {
@@ -99,6 +101,31 @@ function requireTask(team, taskId) {
     }
     return task;
 }
+function memberOpenTask(team, memberName, exceptTaskId) {
+    return team.tasks.find(task => task.id !== exceptTaskId
+        && task.assignee === memberName
+        && (task.status === 'claimed' || task.status === 'in_progress'));
+}
+async function waitForMemberIdle(ctx, member, signal) {
+    if (member.id === '')
+        return;
+    const live = ctx.agents.get(member.id);
+    if (live === undefined)
+        return;
+    if (signal.aborted)
+        throw signal.reason;
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(signal.reason ?? new Error('task reassignment was cancelled'));
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        await Promise.race([live.whenIdle(), aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
 /**
  * Deliver a durable member report at the captain's nearest model boundary.
  *
@@ -126,7 +153,9 @@ export function steerCaptainReport(captain, from, content) {
  * @param config - resolved tool config.
  */
 export function registerAgentTeamsTools(ctx, config) {
+    installRetiredMemberGuard(ctx, config.stateDir);
     const memberSelections = installMemberSelectionRuntime(ctx, config.stateDir);
+    const scheduler = installTeamScheduler(ctx, { stateDir: config.stateDir });
     ctx.tools.register(defineTool({
         name: 'agent_teams_create',
         description: 'Create a new AgentTeams team: you (the calling agent) become the captain. A captain leads one team at a time; create tasks and members afterwards with agent_teams_add_member and agent_teams_create_task.',
@@ -192,12 +221,13 @@ export function registerAgentTeamsTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_add_member',
-        description: 'Add a durable continuable member. By default it snapshots the captain\'s current LLM provider, model, and reasoning effort with no user prompt. Supply provider/model only for an explicitly requested role-specific route. The member waits for messages, works on assigned tasks, and can message the team.',
+        description: 'Add a durable continuable member. By default it snapshots the captain\'s current LLM route and effort. Supply provider/model only for an explicitly requested role-specific route; a changed provider or model automatically uses the target model\'s default effort. Set reasoning_effort only to request one of the target model\'s supported ids explicitly (or "default" to force its default). The member waits for messages, works on assigned tasks, and can message the team.',
         parameters: {
             name: { type: 'string', required: true, description: 'Unique member name inside the team.' },
             role: { type: 'string', description: 'Role of the member (e.g. researcher, engineer, reviewer).' },
             provider: { type: 'string', description: 'Optional LLM provider route. Use only when the user explicitly requests a different provider; requires model.' },
             model: { type: 'string', description: 'Optional model override. Omit for the captain\'s current model (or the configured memberModel default).' },
+            reasoning_effort: { type: 'string', description: 'Optional reasoning effort override: one of the target model\'s supported effort ids, or "default" to force its default. When omitted, the captain\'s effort is inherited only for the same provider/model; a changed route uses the target default.' },
         },
         output: {
             schema: {
@@ -222,7 +252,7 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(captain);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireCaptainTeam(workspace, config, captain);
-            return withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+            const created = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
                 const memberName = args.name.trim();
                 if (memberName === '')
@@ -241,6 +271,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     provider: args.provider,
                     model: args.model,
                     defaultModel: config.memberModel,
+                    reasoningEffort: args.reasoning_effort,
                 }, exec.signal);
                 const member = {
                     id: '',
@@ -254,7 +285,19 @@ export function registerAgentTeamsTools(ctx, config) {
                 };
                 await spawnMember(ctx, memberRuntime(config), memberSelections, selection, captain, fresh, member, config.stateDir, exec.signal);
                 fresh.members.push(member);
-                await writeTeam(stateRoot, fresh);
+                try {
+                    await writeTeam(stateRoot, fresh);
+                }
+                catch (error) {
+                    // The continuable child is already live, but the durable team record
+                    // never saw it. Retire the orphan so it disappears from subagent
+                    // listings and cannot be resumed, then surface the write failure.
+                    if (member.id !== '') {
+                        await recordRetiredMemberIds(stateRoot, [member.id]).catch(() => undefined);
+                        interruptMember(ctx, captain, member.id);
+                    }
+                    throw error;
+                }
                 appendTeamEvent(ctx, captainSessionOf(ctx, fresh.captainSessionId, captain.session), 'agent-teams/member-added', {
                     teamId: fresh.id,
                     memberId: member.id,
@@ -272,11 +315,13 @@ export function registerAgentTeamsTools(ctx, config) {
                     status: member.status,
                 };
             });
+            await scheduler.kickMember(workspace, team.id, created.member_name, captain);
+            return created;
         },
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_remove_member',
-        description: 'Remove a member from your team: interrupts its live turn (best effort) and marks it removed. Its mailbox and past task outputs stay on disk.',
+        description: 'Remove a member safely: revoke its current attempts, return all unfinished owned tasks to the shared pending pool, interrupt its live turn, and mark it removed.',
         parameters: {
             name: { type: 'string', required: true, description: 'Name of the member to remove.' },
         },
@@ -287,11 +332,12 @@ export function registerAgentTeamsTools(ctx, config) {
                 properties: {
                     member_name: { type: 'string', required: true },
                     status: { type: 'string', required: true },
+                    requeued_tasks: { type: 'array', items: { type: 'string' }, required: true },
                 },
             },
             render: (args, value) => [{
                     type: 'text',
-                    text: `Member "${value.member_name}" removed (status ${value.status}).`,
+                    text: `Member "${value.member_name}" removed (status ${value.status}); requeued tasks: ${value.requeued_tasks.join(', ') || 'none'}.`,
                 }],
         },
         async execute(args, exec) {
@@ -299,19 +345,36 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(captain);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireCaptainTeam(workspace, config, captain);
-            return withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+            const revoked = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
                 const member = requireMember(fresh, args.name);
-                if (member.id !== '')
-                    interruptMember(ctx, captain, member.id);
+                const requeued = [];
+                for (const task of fresh.tasks) {
+                    if (task.assignee !== member.name || task.status === 'completed')
+                        continue;
+                    invalidateTaskAttempt(task);
+                    task.reassigning = false;
+                    requeued.push(task.id);
+                }
                 member.status = 'removed';
                 await writeTeam(stateRoot, fresh);
                 appendTeamEvent(ctx, captainSessionOf(ctx, fresh.captainSessionId, captain.session), 'agent-teams/member-removed', {
                     teamId: fresh.id,
                     memberId: member.id,
                 });
-                return { member_name: member.name, status: member.status };
+                return { member: { ...member }, requeued };
             });
+            if (revoked.member.id !== '') {
+                await recordRetiredMemberIds(stateRoot, [revoked.member.id]);
+                interruptMember(ctx, captain, revoked.member.id);
+                await waitForMemberIdle(ctx, revoked.member, exec.signal);
+            }
+            await scheduler.kickTeam(workspace, team.id, captain);
+            return {
+                member_name: revoked.member.name,
+                status: revoked.member.status,
+                requeued_tasks: revoked.requeued,
+            };
         },
     }));
     ctx.tools.register(defineTool({
@@ -348,7 +411,7 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(captain);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireCaptainTeam(workspace, config, captain);
-            return withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+            const created = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
                 const dependencies = args.dependencies ?? [];
                 for (const dependency of dependencies) {
@@ -365,6 +428,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     status: 'pending',
                     assignee: args.assignee,
                     dependencies,
+                    attempt: 0,
                     createdAt: Date.now(),
                     updatedAt: Date.now(),
                 };
@@ -385,11 +449,120 @@ export function registerAgentTeamsTools(ctx, config) {
                     ...task.assignee !== undefined ? { assignee: task.assignee } : {},
                 };
             });
+            await scheduler.kickTeam(workspace, team.id, captain);
+            return created;
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'agent_teams_reassign_task',
+        description: 'Atomically retry, reassign, or let the captain take over any unfinished/failed task. The old attempt is revoked before its member is interrupted, so late updates cannot overwrite the new owner. Use assignee="captain" for captain takeover.',
+        parameters: {
+            task_id: { type: 'string', required: true, description: 'Task to retry/reassign.' },
+            assignee: { type: 'string', required: true, description: 'Active member name, or "captain" for captain takeover.' },
+            reason: { type: 'string', description: 'Why the task is being retried or reassigned.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    task_id: { type: 'string', required: true },
+                    previous_assignee: { type: 'string', required: true },
+                    assignee: { type: 'string', required: true },
+                    status: { type: 'string', required: true },
+                    attempt: { type: 'number', required: true },
+                    attempt_id: { type: 'string' },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Task ${value.task_id} reassigned ${value.previous_assignee || 'unassigned'} → ${value.assignee} (attempt ${value.attempt}, status ${value.status}${value.attempt_id ? `, attempt_id ${value.attempt_id}` : ''}).`,
+                }],
+        },
+        async execute(args, exec) {
+            const captain = requireCaptain(exec);
+            const workspace = workspaceOf(captain);
+            const stateRoot = stateRootOf(workspace, config);
+            const team = await requireCaptainTeam(workspace, config, captain);
+            const target = args.assignee.trim();
+            if (target === '')
+                throw new Error('reassignment assignee must not be empty');
+            const revoked = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
+                const task = requireTask(fresh, args.task_id);
+                if (task.status === 'completed')
+                    throw new Error(`completed task ${task.id} is immutable and cannot be reassigned`);
+                if (task.reassigning === true)
+                    throw new Error(`task ${task.id} is already being reassigned`);
+                const targetMember = target === CAPTAIN_KEY ? undefined : requireMember(fresh, target);
+                if (targetMember !== undefined) {
+                    const busy = memberOpenTask(fresh, targetMember.name, task.id);
+                    if (busy !== undefined) {
+                        throw new Error(`member "${targetMember.name}" is busy with ${busy.id}; finish or reassign it first`);
+                    }
+                }
+                const previousAssignee = task.assignee ?? '';
+                const previousMember = (task.status !== 'claimed' && task.status !== 'in_progress')
+                    || task.assignee === undefined || task.assignee === CAPTAIN_KEY
+                    ? undefined
+                    : fresh.members.find(member => member.name === task.assignee && member.status !== 'removed');
+                invalidateTaskAttempt(task, target, true);
+                await writeTeam(stateRoot, fresh);
+                return {
+                    previousAssignee,
+                    previousMember: previousMember === undefined ? undefined : { ...previousMember },
+                    handoffId: task.handoffId,
+                };
+            });
+            let quiescenceError;
+            if (revoked.previousMember !== undefined) {
+                interruptMember(ctx, captain, revoked.previousMember.id);
+                try {
+                    await waitForMemberIdle(ctx, revoked.previousMember, exec.signal);
+                }
+                catch (error) {
+                    quiescenceError = error;
+                }
+            }
+            await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
+                const task = requireTask(fresh, args.task_id);
+                if (task.handoffId !== revoked.handoffId || task.assignee !== target || task.reassigning !== true) {
+                    throw new Error(`task ${task.id} changed during reassignment; refusing to overwrite the newer state`);
+                }
+                task.reassigning = false;
+                if (quiescenceError === undefined && target === CAPTAIN_KEY)
+                    beginTaskAttempt(task, CAPTAIN_KEY);
+                await writeTeam(stateRoot, fresh);
+                appendTeamEvent(ctx, captain.session, 'agent-teams/task-updated', {
+                    teamId: fresh.id,
+                    taskId: task.id,
+                    status: task.status,
+                    assignee: task.assignee,
+                    ...args.reason === undefined ? {} : { output: `Reassigned: ${args.reason}` },
+                });
+            });
+            if (quiescenceError !== undefined)
+                throw quiescenceError;
+            if (target !== CAPTAIN_KEY)
+                await scheduler.kickMember(workspace, team.id, target, captain);
+            const current = await readTeam(stateRoot, team.id);
+            const task = current === undefined ? undefined : requireTask(current, args.task_id);
+            if (task === undefined)
+                throw new Error(`team "${team.name}" ended during reassignment`);
+            return {
+                task_id: task.id,
+                previous_assignee: revoked.previousAssignee,
+                assignee: task.assignee ?? '',
+                status: task.status,
+                attempt: task.attempt ?? 0,
+                ...task.attemptId === undefined ? {} : { attempt_id: task.attemptId },
+            };
         },
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_claim_task',
-        description: 'Claim a task for a member (or for yourself when you are the member). Blocked while any dependency is unfinished — the error lists the pending dependencies. The captain may claim on behalf of an assignee; a member may only claim tasks assigned to it (or unassigned).',
+        description: 'Claim one ready task for a member (or yourself). A member cannot own a second unfinished task. The returned attempt_id is required for that member\'s updates and becomes stale after retry/reassignment.',
         parameters: {
             task_id: { type: 'string', required: true, description: 'The task id to claim.' },
             assignee: { type: 'string', description: 'Member to claim for (captain only; defaults to the task\'s assignee).' },
@@ -402,11 +575,13 @@ export function registerAgentTeamsTools(ctx, config) {
                     task_id: { type: 'string', required: true },
                     status: { type: 'string', required: true },
                     assignee: { type: 'string', required: true },
+                    attempt: { type: 'number', required: true },
+                    attempt_id: { type: 'string' },
                 },
             },
             render: (args, value) => [{
                     type: 'text',
-                    text: `Task ${value.task_id} claimed by ${value.assignee} (status ${value.status}).`,
+                    text: `Task ${value.task_id} claimed by ${value.assignee} (attempt ${value.attempt}${value.attempt_id ? `, attempt_id ${value.attempt_id}` : ''}, status ${value.status}).`,
                 }],
         },
         async execute(args, exec) {
@@ -417,6 +592,9 @@ export function registerAgentTeamsTools(ctx, config) {
             return withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const { team: fresh, identity } = await requireFreshParticipant(stateRoot, team.id, caller.id);
                 const task = requireTask(fresh, args.task_id);
+                if (task.reassigning === true) {
+                    throw new Error(`task ${task.id} is being reassigned; wait for the handoff to finish`);
+                }
                 let assignee = task.assignee;
                 if (identity.kind === 'captain') {
                     if (args.assignee !== undefined) {
@@ -439,7 +617,13 @@ export function registerAgentTeamsTools(ctx, config) {
                     if (assignee === undefined || task.assignee !== assignee) {
                         throw new Error(`task ${task.id} is already claimed by "${task.assignee ?? 'nobody'}"`);
                     }
-                    return { task_id: task.id, status: task.status, assignee };
+                    return {
+                        task_id: task.id,
+                        status: task.status,
+                        assignee,
+                        attempt: task.attempt ?? 0,
+                        ...task.attemptId === undefined ? {} : { attempt_id: task.attemptId },
+                    };
                 }
                 const pending = unsatisfiedDependencies(fresh.tasks, task.dependencies);
                 if (pending.length > 0) {
@@ -451,9 +635,11 @@ export function registerAgentTeamsTools(ctx, config) {
                 if (assignee === undefined) {
                     throw new Error('claiming an unassigned task needs an assignee (claim on behalf of a member)');
                 }
-                task.status = 'claimed';
-                task.assignee = assignee;
-                task.updatedAt = Date.now();
+                const busy = memberOpenTask(fresh, assignee, task.id);
+                if (busy !== undefined) {
+                    throw new Error(`member "${assignee}" is busy with ${busy.id}; finish or reassign it first`);
+                }
+                const attemptId = beginTaskAttempt(task, assignee);
                 await writeTeam(stateRoot, fresh);
                 appendTeamEvent(ctx, captainSessionOf(ctx, fresh.captainSessionId, caller.session), 'agent-teams/task-updated', {
                     teamId: fresh.id,
@@ -461,13 +647,19 @@ export function registerAgentTeamsTools(ctx, config) {
                     status: task.status,
                     assignee: task.assignee,
                 });
-                return { task_id: task.id, status: task.status, assignee: task.assignee ?? '' };
+                return {
+                    task_id: task.id,
+                    status: task.status,
+                    assignee: task.assignee ?? '',
+                    attempt: task.attempt ?? 0,
+                    attempt_id: attemptId,
+                };
             });
         },
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_update_task',
-        description: 'Update a task\'s status and/or write its output. Transitions: claimed → in_progress → completed|failed|cancelled (pending may also be cancelled). The captain may update any task; a member may only update tasks assigned to it. Set output when completing or failing a task.',
+        description: 'Update a task status/output. Members must supply the current attempt_id returned by claim_task; stale attempts are rejected after takeover/reassignment. Terminal results are immutable. A captain must use reassign_task(assignee="captain") before updating member-owned work.',
         parameters: {
             task_id: { type: 'string', required: true, description: 'The task id to update.' },
             status: {
@@ -476,6 +668,7 @@ export function registerAgentTeamsTools(ctx, config) {
                 description: 'New status (in_progress, completed, failed, cancelled).',
             },
             output: { type: 'string', description: 'Result summary; set when completing or failing.' },
+            attempt_id: { type: 'string', description: 'Current execution capability returned by claim_task (required for members when present on the task).' },
         },
         output: {
             schema: {
@@ -485,11 +678,13 @@ export function registerAgentTeamsTools(ctx, config) {
                     task_id: { type: 'string', required: true },
                     status: { type: 'string', required: true },
                     output: { type: 'string' },
+                    attempt: { type: 'number', required: true },
+                    attempt_id: { type: 'string' },
                 },
             },
             render: (args, value) => [{
                     type: 'text',
-                    text: `Task ${value.task_id} → ${value.status}${value.output !== undefined ? `\nOutput: ${value.output}` : ''}`,
+                    text: `Task ${value.task_id} attempt ${value.attempt} → ${value.status}${value.output !== undefined ? `\nOutput: ${value.output}` : ''}`,
                 }],
         },
         async execute(args, exec) {
@@ -497,13 +692,35 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(caller);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireParticipantTeam(workspace, config, caller);
-            return withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+            const updated = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const { team: fresh, identity } = await requireFreshParticipant(stateRoot, team.id, caller.id);
                 const task = requireTask(fresh, args.task_id);
+                if (identity.kind === 'captain'
+                    && task.assignee !== undefined
+                    && task.assignee !== CAPTAIN_KEY) {
+                    throw new Error(`task ${task.id} is owned by member "${task.assignee}"; call agent_teams_reassign_task with assignee="captain" before takeover`);
+                }
                 if (identity.kind === 'member') {
                     if (task.assignee !== identity.name) {
                         throw new Error(`task ${task.id} is assigned to "${task.assignee ?? 'nobody'}", not you`);
                     }
+                    if (task.attemptId !== undefined && args.attempt_id !== task.attemptId) {
+                        throw new Error(`stale attempt for task ${task.id}: expected the current attempt_id; stop work and request fresh assignment`);
+                    }
+                }
+                if (TERMINAL_TASK_STATUSES.includes(task.status)) {
+                    const sameStatus = args.status === undefined || args.status === task.status;
+                    const sameOutput = args.output === undefined || args.output === task.output;
+                    if (!sameStatus || !sameOutput) {
+                        throw new Error(`terminal task ${task.id} is immutable; use agent_teams_reassign_task to retry failed/cancelled work`);
+                    }
+                    return {
+                        task_id: task.id,
+                        status: task.status,
+                        attempt: task.attempt ?? 0,
+                        ...task.attemptId === undefined ? {} : { attempt_id: task.attemptId },
+                        ...task.output !== undefined ? { output: task.output } : {},
+                    };
                 }
                 if (args.status !== undefined) {
                     const transition = transitionError(task.status, args.status);
@@ -525,9 +742,13 @@ export function registerAgentTeamsTools(ctx, config) {
                 return {
                     task_id: task.id,
                     status: task.status,
+                    attempt: task.attempt ?? 0,
+                    ...task.attemptId === undefined ? {} : { attempt_id: task.attemptId },
                     ...task.output !== undefined ? { output: task.output } : {},
                 };
             });
+            await scheduler.kickTeam(workspace, team.id, team.captainSessionId === caller.id ? caller : undefined);
+            return updated;
         },
     }));
     ctx.tools.register(defineTool({
@@ -569,7 +790,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     throw new Error(`agent_teams_send_message: "from" must be your own identity ("${from}"), not "${args.from}"`);
                 }
                 if (to === CAPTAIN_KEY) {
-                    const message = createMessage(from, CAPTAIN_KEY, args.content);
+                    const message = { ...createMessage(from, CAPTAIN_KEY, args.content), deliveryClaimedAt: Date.now() };
                     await appendMailbox(stateRoot, fresh.id, CAPTAIN_KEY, message);
                     appendTeamEvent(ctx, captainSessionOf(ctx, fresh.captainSessionId, caller.session), 'agent-teams/message-sent', {
                         teamId: fresh.id,
@@ -582,7 +803,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     return { kind: 'captain', fresh, identity, message, from };
                 }
                 const recipient = requireMember(fresh, to);
-                const message = createMessage(from, recipient.name, args.content);
+                const message = { ...createMessage(from, recipient.name, args.content), deliveryClaimedAt: Date.now() };
                 await appendMailbox(stateRoot, fresh.id, recipient.name, message);
                 appendTeamEvent(ctx, captainSessionOf(ctx, fresh.captainSessionId, caller.session), 'agent-teams/message-sent', {
                     teamId: fresh.id,
@@ -602,6 +823,12 @@ export function registerAgentTeamsTools(ctx, config) {
                 if (captain !== undefined && prepared.identity.kind === 'member') {
                     delivered = steerCaptainReport(captain, prepared.from, args.content) ? 'live' : 'mailbox';
                 }
+                if (delivered === 'live') {
+                    await withTeamLock(teamLockKey(stateRoot, prepared.fresh.id), () => (acknowledgeMailbox(stateRoot, prepared.fresh.id, CAPTAIN_KEY, [prepared.message.id])));
+                }
+                else {
+                    await withTeamLock(teamLockKey(stateRoot, prepared.fresh.id), () => (releaseMailboxDelivery(stateRoot, prepared.fresh.id, CAPTAIN_KEY, [prepared.message.id])));
+                }
                 return { message_id: prepared.message.id, from: prepared.from, to: CAPTAIN_KEY, delivered };
             }
             let delivered = 'mailbox';
@@ -612,6 +839,12 @@ export function registerAgentTeamsTools(ctx, config) {
                 const text = `AgentTeams state policy: inspect ${config.stateDir}/${prepared.fresh.id}/ read-only; never edit team.json or inbox files directly. Use agent_teams_* tools for team state.\n\n${senderText}`;
                 const accepted = await deliverToMember(ctx, captain, prepared.recipient.id, text, exec.signal);
                 delivered = accepted ? 'wake' : 'mailbox';
+                if (accepted) {
+                    await withTeamLock(teamLockKey(stateRoot, prepared.fresh.id), () => (acknowledgeMailbox(stateRoot, prepared.fresh.id, prepared.recipient.name, [prepared.message.id])));
+                }
+            }
+            if (delivered === 'mailbox') {
+                await withTeamLock(teamLockKey(stateRoot, prepared.fresh.id), () => (releaseMailboxDelivery(stateRoot, prepared.fresh.id, prepared.recipient.name, [prepared.message.id])));
             }
             return {
                 message_id: prepared.message.id,
@@ -634,6 +867,9 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(caller);
             const stateRoot = stateRootOf(workspace, config);
             const located = await requireParticipantTeam(workspace, config, caller);
+            if (located.captainSessionId === caller.id) {
+                await scheduler.kickTeam(workspace, located.id, caller);
+            }
             const { team, identity } = await withTeamLock(teamLockKey(stateRoot, located.id), () => requireFreshParticipant(stateRoot, located.id, caller.id));
             const activity = await memberActivity(ctx, team.captainSessionId);
             const members = team.members
@@ -653,6 +889,9 @@ export function registerAgentTeamsTools(ctx, config) {
                 status: task.status,
                 assignee: task.assignee ?? '',
                 dependencies: task.dependencies,
+                attempt: task.attempt ?? 0,
+                attempt_id: task.attemptId ?? '',
+                reassigning: task.reassigning === true,
                 ...task.output !== undefined ? { output: task.output } : {},
             }));
             const mailboxWarnings = [];
@@ -664,14 +903,14 @@ export function registerAgentTeamsTools(ctx, config) {
                 }
             };
             const captainInbox = identity.kind === 'captain'
-                ? await readMailbox(stateRoot, team.id, CAPTAIN_KEY, reportMalformed(CAPTAIN_KEY))
+                ? await readUnreadMailbox(stateRoot, team.id, CAPTAIN_KEY, reportMalformed(CAPTAIN_KEY))
                 : [];
             const memberInboxes = {};
             const visibleMembers = identity.kind === 'captain'
                 ? members
                 : members.filter((member) => member.name === identity.name);
             for (const member of visibleMembers) {
-                const messages = await readMailbox(stateRoot, team.id, member.name, reportMalformed(member.name));
+                const messages = await readUnreadMailbox(stateRoot, team.id, member.name, reportMalformed(member.name));
                 if (messages.length > 0) {
                     memberInboxes[member.name] = {
                         count: messages.length,
@@ -679,7 +918,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     };
                 }
             }
-            return {
+            const result = {
                 team_id: team.id,
                 team_name: team.name,
                 description: team.description ?? '',
@@ -695,6 +934,13 @@ export function registerAgentTeamsTools(ctx, config) {
                 mailbox_warnings: mailboxWarnings,
                 mailbox_warning_count: mailboxWarningCount,
             };
+            const acknowledged = identity.kind === 'captain'
+                ? captainInbox.map(message => message.id)
+                : await readUnreadMailbox(stateRoot, team.id, identity.name).then(messages => messages.map(message => message.id));
+            if (acknowledged.length > 0) {
+                await withTeamLock(teamLockKey(stateRoot, team.id), () => (acknowledgeMailbox(stateRoot, team.id, identity.kind === 'captain' ? CAPTAIN_KEY : identity.name, acknowledged)));
+            }
+            return result;
         },
     }));
     ctx.tools.register(defineTool({
@@ -720,12 +966,37 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(captain);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireCaptainTeam(workspace, config, captain);
-            await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+            const members = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
+                // Include previously removed members so deleting a pre-fix team also
+                // retires durable catalog entries left behind by remove_member.
+                const roster = fresh.members.map(member => ({ ...member }));
                 for (const member of fresh.members) {
-                    if (member.status !== 'removed' && member.id !== '')
-                        interruptMember(ctx, captain, member.id);
+                    if (member.status === 'removed')
+                        continue;
+                    member.status = 'removed';
+                    for (const task of fresh.tasks) {
+                        if (task.assignee === member.name && task.status !== 'completed')
+                            invalidateTaskAttempt(task);
+                    }
+                }
+                await writeTeam(stateRoot, fresh);
+                return roster;
+            });
+            await recordRetiredMemberIds(stateRoot, members.map(member => member.id));
+            for (const member of members) {
+                if (member.id === '')
+                    continue;
+                interruptMember(ctx, captain, member.id);
+            }
+            const quiescence = await Promise.allSettled(members.map(member => waitForMemberIdle(ctx, member, exec.signal)));
+            for (const result of quiescence) {
+                if (result.status === 'rejected') {
+                    ctx.logger.warn(`agent-teams: member did not quiesce cleanly before team archive: ${String(result.reason)}`);
                 }
+            }
+            await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
                 appendTeamEvent(ctx, captainSessionOf(ctx, fresh.captainSessionId, captain.session), 'agent-teams/team-deleted', {
                     teamId: fresh.id,
                 });
@@ -760,7 +1031,8 @@ function renderStatus(value) {
         ...team.tasks.map((task) => {
             const deps = task.dependencies.length > 0 ? ` (deps: ${task.dependencies.join(',')})` : '';
             const output = task.output !== undefined ? `\n      output: ${task.output.slice(0, 300)}` : '';
-            return `  - ${task.id} [${task.status}] ${task.subject} → ${task.assignee || 'unassigned'}${deps}${output}`;
+            const handoff = task.reassigning ? ' (reassigning)' : '';
+            return `  - ${task.id} [${task.status}] attempt ${task.attempt}${handoff} ${task.subject} → ${task.assignee || 'unassigned'}${deps}${output}`;
         }),
         `Captain inbox (${team.captain_inbox.length}):`,
         ...team.captain_inbox.map((message) => `  - [${message.from}] ${message.content.slice(0, 200)}`),

package/lib/types/client/ActivityPanel.d.ts

@@ -21,6 +21,7 @@ export interface ActivityMember {
     readonly id: string;
     readonly name: string;
     readonly role: string;
+    readonly status?: 'idle' | 'working' | 'removed';
     readonly activity: 'working' | 'idle' | 'unknown';
     readonly progress: number;
     readonly done: number;