@nanmicoder/dsh-agent-teams 0.1.15 → 0.1.16-rc.3

package/lib/members.js

@@ -4,7 +4,7 @@
  *
  * Members are durable continuable subagents of the captain, so a member keeps
  * its conversation across turns and across harness restarts: the captain
- * wakes it with {@link ctx.subagents.followup}, it works through its turn
+ * queues its next turn through {@link deliverToMember}, it works through its turn
  * (updating team state through the `agent_teams_*` tools), and becomes idle
  * again. Its final assistant message is not readable programmatically, so the
  * member persists its report into the captain's mailbox and the task records,
@@ -13,23 +13,18 @@
  */
 import { installModelSelection } from '@deepseek-ai/dsh-agent';
 // Declaration merge only: makes ctx.subagents visible.
-import { foldSubagentDescriptor, SubagentError } from '@deepseek-ai/dsh-subagent';
-import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { foldSubagentDescriptor } from '@deepseek-ai/dsh-subagent';
+import { createUserMessage, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { join } from 'node:path';
-import { readRetiredMemberIds, readTeamSync, readTeam, withTeamLock, writeTeam } from "./state.js";
+import { guardSubagentDelivery, installContinuableMemberSetup, queueMemberPrompt, sessionOwnEvents } from "./harness-compat.js";
+import { acknowledgeMailbox, appendMailbox, CAPTAIN_KEY, createMessage, readRetiredMemberIds, readTeamSync, readTeam, releaseMailboxDelivery, withTeamLock, writeTeam } from "./state.js";
+import { appendTeamEvent, captainSessionOf } from "./events.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
+import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
 export const PERSONA_PROTOCOL_MAX_CHARS = 400;
 /** Captain-only AgentTeams tools hidden from newly spawned members. */
-const MEMBER_DENIED_TOOLS = [
-    'agent_teams_create',
-    'agent_teams_add_member',
-    'agent_teams_remove_member',
-    'agent_teams_reassign_task',
-    'agent_teams_create_task',
-    'agent_teams_resume',
-    'agent_teams_delete',
-];
+const MEMBER_DENIED_TOOLS = CAPTAIN_TOOL_NAMES;
 /**
  * Restore the SessionId brand on a value that round-tripped through the
  * durable team file. The brand is erased by JSON serialization; the value
@@ -74,6 +69,81 @@ export function selectFallbackRoute(current, fallback, failureCode, alreadySwitc
     }
     return { retry: true, switched: true, selection: fallback };
 }
+/** Deliver a durable member report to the live captain at its next model step. */
+export function steerCaptainReport(captain, from, content) {
+    try {
+        captain.steer(createUserMessage({
+            content: [{ type: 'text', text: `AgentTeams message from member ${from}:\n\n${content}` }],
+            source: { kind: 'plugin', plugin: 'dsh-agent-teams' },
+        }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Record a final turn failure, never an intermediate request retry. */
+export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName, failure, fallbackSession, observed) {
+    const summary = `${failure.message} (code ${failure.code})`;
+    const lockKey = `team:${stateRoot}:${teamId}`;
+    const prepared = await withTeamLock(lockKey, async () => {
+        const team = await readTeam(stateRoot, teamId);
+        if (team === undefined || team.halted === true || team.captainSessionId !== observed.captainSessionId)
+            return;
+        const member = team.members.find(candidate => candidate.name === memberName
+            && candidate.id === observed.memberId && candidate.status !== 'removed');
+        if (member === undefined)
+            return;
+        const task = team.tasks.find(candidate => candidate.assignee === memberName
+            && (candidate.status === 'claimed' || candidate.status === 'in_progress'));
+        // A reassign, completion, or recreated member may win the lock while the
+        // final error is queued. Only the capability observed at that event may fail.
+        if (task?.id !== observed.task?.id || task?.attemptId !== observed.task?.attemptId
+            || task?.attempt !== observed.task?.attempt)
+            return;
+        if (task === undefined && member.status !== 'working')
+            return;
+        if (task !== undefined) {
+            task.status = 'failed';
+            task.output = summary;
+            task.updatedAt = Date.now();
+        }
+        if (ctx.agents.get(brandedSessionId(member.id))?.status !== 'running')
+            member.status = 'idle';
+        const message = {
+            ...createMessage(memberName, CAPTAIN_KEY, task === undefined
+                ? `Member "${memberName}" hit an unrecoverable turn failure: ${summary}. No open attempt was owned.`
+                : `Member "${memberName}" hit an unrecoverable turn failure: ${summary}. Task ${task.id} ("${task.subject}") was marked failed; reassign it or retry when ready.`),
+            deliveryClaimedAt: Date.now(),
+        };
+        await writeTeam(stateRoot, team);
+        await appendMailbox(stateRoot, team.id, CAPTAIN_KEY, message);
+        if (task !== undefined) {
+            appendTeamEvent(ctx, captainSessionOf(ctx, team.captainSessionId, fallbackSession), 'agent-teams/task-updated', {
+                teamId, taskId: task.id, status: task.status, assignee: memberName, output: task.output,
+            });
+        }
+        appendTeamEvent(ctx, captainSessionOf(ctx, team.captainSessionId, fallbackSession), 'agent-teams/message-sent', {
+            teamId: team.id,
+            messageId: message.id,
+            from: memberName,
+            to: CAPTAIN_KEY,
+            content: message.content,
+            ts: message.ts,
+        });
+        return { captainSessionId: team.captainSessionId, message };
+    });
+    if (prepared === undefined)
+        return false;
+    // Use the same lease/acknowledgment contract as send_message, outside the
+    // team lock: steering can synchronously start another agent turn.
+    const captain = ctx.agents.get(brandedSessionId(prepared.captainSessionId));
+    const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content);
+    await withTeamLock(lockKey, () => delivered
+        ? acknowledgeMailbox(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id])
+        : releaseMailboxDelivery(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id]));
+    return true;
+}
 async function updateFallbackState(stateRoot, teamId, memberName, fallback, ctx) {
     await withTeamLock(`team:${stateRoot}:${teamId}`, async () => {
         const team = await readTeam(stateRoot, teamId);
@@ -99,12 +169,14 @@ function selectionFromMember(member) {
     const model = (member.activeModel ?? member.model).trim();
     if (provider === '' || model === '')
         return undefined;
-    const reasoningEffort = member.reasoningEffort?.trim();
+    // Effort ids belong to the original model. After a fallback, its own
+    // provider default remains authoritative, including after cold recovery.
+    const reasoningEffort = member.fallbackActive === true ? undefined : member.reasoningEffort?.trim();
     return {
         provider,
         model,
         ...reasoningEffort === undefined || reasoningEffort === '' ? {} : { reasoningEffort },
-        ...member.fallback === undefined ? {} : { fallback: member.fallback },
+        ...member.fallback === undefined || member.fallbackActive === true ? {} : { fallback: member.fallback },
     };
 }
 function modelSelection(selection) {
@@ -189,76 +261,128 @@ export async function resolveMemberLlmSelection(ctx, captain, request, signal) {
  * record. Legacy members without a complete saved route retain Harness's
  * descriptor provider/model behavior.
  */
-export function installMemberSelectionRuntime(ctx, stateDir) {
+export function installMemberSelectionRuntime(ctx, stateDir, onFailureSettled) {
     const pending = new Map();
-    ctx.subagents.registerContinuableSetup((childCtx) => {
+    installContinuableMemberSetup(ctx, (childCtx) => {
         const child = childCtx.agent;
         if (child === undefined)
             return () => undefined;
-        const suffix = child.session.events.slice(child.session.header.seedLength ?? 0);
-        const descriptor = foldSubagentDescriptor(suffix);
+        const descriptor = foldSubagentDescriptor(sessionOwnEvents(child.session));
         if (descriptor?.mode !== 'continuable' || !descriptor.label.startsWith(MEMBER_LABEL_PREFIX)) {
             return () => undefined;
         }
         const parentSessionId = child.session.header.parentSession;
         if (parentSessionId === undefined)
             return () => undefined;
+        const identity = descriptor.label.slice(MEMBER_LABEL_PREFIX.length);
+        const separator = identity.indexOf(':');
+        if (separator < 1 || separator === identity.length - 1)
+            return () => undefined;
+        const teamId = identity.slice(0, separator);
+        const memberName = identity.slice(separator + 1);
+        const workspace = child.session.header.cwd ?? process.cwd();
+        const stateRoot = join(workspace, stateDir);
         const key = pendingSelectionKey(parentSessionId, descriptor.label);
         let selection = pending.get(key);
         if (selection === undefined) {
-            const identity = descriptor.label.slice(MEMBER_LABEL_PREFIX.length);
-            const separator = identity.indexOf(':');
-            if (separator < 1 || separator === identity.length - 1)
-                return () => undefined;
-            const teamId = identity.slice(0, separator);
-            const memberName = identity.slice(separator + 1);
-            const workspace = child.session.header.cwd ?? process.cwd();
-            const team = readTeamSync(join(workspace, stateDir), teamId);
+            const team = readTeamSync(stateRoot, teamId);
             if (team?.captainSessionId !== parentSessionId)
                 return () => undefined;
             const durableMember = team.members.find(member => member.name === memberName);
             selection = selectionFromMember(durableMember);
-            // An old team record has no provider/reasoning snapshot. Its durable
-            // Harness descriptor still restores provider/model, so leave it alone.
-            if (selection === undefined)
-                return () => undefined;
-            if (descriptor.agentProvider !== durableMember?.provider || descriptor.agentModel !== durableMember?.model) {
+            if (selection !== undefined && (descriptor.agentProvider !== durableMember?.provider || descriptor.agentModel !== durableMember?.model)) {
                 throw new Error(`agent-teams: saved model route for member "${memberName}" does not match its subagent descriptor`);
             }
         }
+        let lastFailedTurn;
+        // Harness emits agent/error only after request recovery is exhausted. In
+        // particular, llm-retry's "always" policy calls downstream request-error
+        // listeners before it retries; that waterfall cannot declare a turn dead.
+        const disposeFailure = childCtx.on('agent/error', async (payload) => {
+            if (payload.agent.id !== child.id || payload.turn === lastFailedTurn)
+                return;
+            lastFailedTurn = payload.turn;
+            try {
+                // Capture the attempt synchronously at the event, before any lock wait
+                // can let a captain reassign it or replace the member/team generation.
+                const snapshot = readTeamSync(stateRoot, teamId);
+                if (snapshot?.captainSessionId !== parentSessionId)
+                    return;
+                const member = snapshot.members.find(item => item.id === child.id && item.name === memberName && item.status !== 'removed');
+                if (member === undefined)
+                    return;
+                const task = snapshot.tasks.find(item => item.assignee === memberName
+                    && (item.status === 'claimed' || item.status === 'in_progress'));
+                const failure = payload.error instanceof LlmError ? payload.error.failure : {
+                    code: 'UNKNOWN',
+                    message: payload.error instanceof Error ? payload.error.message : String(payload.error),
+                };
+                const recorded = await failMemberOpenAttempt(ctx, stateRoot, teamId, memberName, failure, child.session, {
+                    captainSessionId: parentSessionId, memberId: child.id, task,
+                });
+                if (!recorded)
+                    return;
+                // The final-error event precedes driver quiescence. Observe the real
+                // lifecycle and kick explicitly even if its idle event was missed.
+                // Never force an active Agent's status to idle or retry the failed task.
+                await child.whenIdle();
+                await withTeamLock(`team:${stateRoot}:${teamId}`, async () => {
+                    const team = await readTeam(stateRoot, teamId);
+                    const current = team?.members.find(item => item.id === child.id && item.name === memberName && item.status !== 'removed');
+                    if (team?.captainSessionId !== parentSessionId || current === undefined || child.status !== 'idle')
+                        return;
+                    if (current.status !== 'idle') {
+                        current.status = 'idle';
+                        await writeTeam(stateRoot, team);
+                    }
+                });
+                await onFailureSettled?.(workspace, teamId, memberName);
+            }
+            catch (error) {
+                ctx.logger.warn(`agent-teams: failed to record member turn failure: ${String(error)}`);
+            }
+        });
+        // Legacy teams still need failure reporting even without a saved route.
+        if (selection === undefined)
+            return disposeFailure;
         const selectionRef = { current: modelSelection(selection), assembled: undefined };
         const disposeSelection = installModelSelection(childCtx, selectionRef);
         const fallback = selection.fallback;
-        if (fallback === undefined)
-            return disposeSelection;
         let switched = false;
-        const disposeFallback = childCtx.on('agent/request-error', async (payload) => {
-            if (payload.agent.id !== child.id)
-                return undefined;
+        const disposeFallback = childCtx.on('agent/request-error', async (payload, next) => {
+            if (payload.agent.id !== child.id || payload.signal.aborted)
+                return next();
             const transition = selectFallbackRoute(selectionRef.current ?? { provider: selection.provider, model: selection.model }, fallback, payload.failure.code, switched);
-            if (!transition.retry)
-                return undefined;
-            switched = transition.switched;
-            selectionRef.current = transition.selection;
-            const workspace = child.session.header.cwd ?? process.cwd();
-            const identity = descriptor.label.slice(MEMBER_LABEL_PREFIX.length);
-            const separator = identity.indexOf(':');
-            if (separator > 0) {
-                const teamId = identity.slice(0, separator);
-                const memberName = identity.slice(separator + 1);
-                void updateFallbackState(join(workspace, stateDir), teamId, memberName, fallback, ctx).catch((error) => {
+            // selectFallbackRoute only retries when a fallback route exists; the
+            // explicit guard narrows that fact for the compiler.
+            if (fallback !== undefined && transition.retry) {
+                switched = transition.switched;
+                selectionRef.current = transition.selection;
+                // Request recovery repeats buildRequest inside the current step; it
+                // does not re-run prompt assembly. Override that captured route too,
+                // otherwise the authorized retry would hit the failed primary again.
+                selectionRef.assembled = transition.selection;
+                await updateFallbackState(stateRoot, teamId, memberName, fallback, ctx).catch((error) => {
                     ctx.logger.warn(`agent-teams: failed to persist fallback route: ${String(error)}`);
                 });
+                ctx.logger.warn(`agent-teams: member ${child.id} switching to fallback ${fallback.provider}/${fallback.model} after ${payload.failure.code}`);
+                return { kind: 'retry' };
             }
-            ctx.logger.warn(`agent-teams: member ${child.id} switching to fallback ${fallback.provider}/${fallback.model} after ${payload.failure.code}`);
-            return { kind: 'retry' };
+            return next();
         });
         return () => {
             disposeFallback();
             disposeSelection();
+            disposeFailure();
         };
     });
     return {
+        isPendingMember(agent) {
+            const parent = agent.session.header.parentSession;
+            const descriptor = foldSubagentDescriptor(sessionOwnEvents(agent.session));
+            return parent !== undefined && descriptor?.mode === 'continuable'
+                && pending.has(pendingSelectionKey(parent, descriptor.label));
+        },
         async withPending(parentSessionId, label, selection, operation) {
             const key = pendingSelectionKey(parentSessionId, label);
             if (pending.has(key)) {
@@ -387,6 +511,9 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
             agentOptions: {
                 provider: llmSelection.provider,
                 model: llmSelection.model,
+                ...llmSelection.reasoningEffort === undefined
+                    ? {}
+                    : { reasoningEffort: ReasoningEffortId(llmSelection.reasoningEffort) },
             },
             ...config.maxDepth !== undefined ? { maxDepth: config.maxDepth } : {},
         },
@@ -413,14 +540,11 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
  */
 export async function deliverToMember(ctx, captain, childId, text, signal) {
     try {
-        await ctx.subagents.followup(captain, brandedSessionId(childId), [{ type: 'text', text }], {
-            source: { kind: 'plugin', plugin: 'dsh-agent-teams' },
-            signal,
-        });
+        await queueMemberPrompt(ctx.subagents, captain, brandedSessionId(childId), [{ type: 'text', text }], signal);
         return true;
     }
     catch (error) {
-        ctx.logger.warn(`agent-teams: followup to member ${childId} failed: ${String(error)}`);
+        ctx.logger.warn(`agent-teams: prompt delivery to member ${childId} failed: ${String(error)}`);
         return false;
     }
 }
@@ -444,30 +568,18 @@ export function interruptMember(ctx, captain, childId) {
  *
  * Upstream `interrupt()` deliberately preserves continuable sessions and the
  * upstream seam exposes no targeted forget/retire method. The durable
- * AgentTeams index therefore rejects `followup()` before it can cold-resume a
+ * AgentTeams index therefore rejects every inbox delivery before it can cold-resume a
  * retired member. Catalog rows deliberately remain discoverable: Harness rc.8
  * uses the direct-child catalog to authorize historical transcript reads and
  * `openSubagent()`, so filtering those rows would make an archived member's
  * persisted conversation inaccessible. Exact ids keep unrelated subagents
- * untouched while the followup boundary still prevents further model turns.
+ * untouched while the delivery boundary still prevents further model turns.
  */
 export function installRetiredMemberGuard(ctx, stateDir) {
-    const runtime = ctx.subagents;
-    ctx.effect(() => {
-        const followup = runtime.followup;
-        const guardedFollowup = async (parent, childId, content, options) => {
-            const retired = await readRetiredMemberIds(join(parent.session.header.cwd ?? process.cwd(), stateDir));
-            if (retired.has(childId)) {
-                throw new SubagentError(`AgentTeams member "${childId}" was retired and cannot be resumed`, 'NOT_RESUMABLE');
-            }
-            return followup.call(runtime, parent, childId, content, options);
-        };
-        runtime.followup = guardedFollowup;
-        return () => {
-            if (runtime.followup === guardedFollowup)
-                runtime.followup = followup;
-        };
-    }, 'agent-teams: retired member guard');
+    guardSubagentDelivery(ctx, async (parent, childId) => {
+        const retired = await readRetiredMemberIds(join(parent.session.header.cwd ?? process.cwd(), stateDir));
+        return retired.has(childId);
+    });
 }
 /**
  * Snapshot the real driver activity for durable member ids.

package/lib/profiles.js

@@ -116,7 +116,7 @@ function formatProfileListingLine(entry) {
         ? 'captain planning'
         : countLabel(Array.isArray(entry.config.tasks) ? entry.config.tasks.length : 0, 'task');
     const counts = `(${countLabel(memberCount, 'member')}, ${graph})`;
-    const summary = protocolSummary(entry.config.protocol);
+    const summary = protocolSummary(entry.config.protocol) ?? protocolSummary(entry.config.description);
     return summary === undefined
         ? `- ${entry.name} ${counts}`
         : `- ${entry.name} ${counts}: ${summary}`;

package/lib/quality-gates.js

@@ -600,6 +600,51 @@ export function isCommandResult(value) {
         && (value['exitCode'] === undefined || (Number.isSafeInteger(value['exitCode'])))
         && (value['evidence'] === undefined || typeof value['evidence'] === 'string');
 }
+// Optional fields whose persisted values must be non-empty when present
+// (mirrors the checks in hasValidQualityTaskFields). Some models materialize
+// optional tool parameters as "" instead of omitting them (e.g. GPT-5.6
+// sending reviewedTaskId:"" or profile:""), which would otherwise be written
+// to team.json and then brick the whole team state on reload.
+const BLANK_SENSITIVE_STRING_FIELDS = ['objective', 'reviewedTaskId', 'sourceTaskId'];
+const BLANK_SENSITIVE_STRING_LIST_FIELDS = [
+    'inScope',
+    'outOfScope',
+    'acceptance',
+    'verify',
+    'deliverables',
+    'nonGoals',
+    'changedPaths',
+    'sourceFindingIds',
+    'coverageOf',
+];
+/**
+ * Normalize blank optional task fields to omitted ("blank means absent").
+ * Blank string scalars are deleted; string lists have blank entries filtered
+ * out, and a list that only contained blanks is omitted entirely. Non-blank
+ * values and every other field are passed through untouched, so durable-state
+ * validation stays strict.
+ */
+export function normalizeBlankOptionalTaskFields(task) {
+    const next = { ...task };
+    for (const key of BLANK_SENSITIVE_STRING_FIELDS) {
+        const value = next[key];
+        if (typeof value === 'string' && value.trim() === '')
+            delete next[key];
+    }
+    for (const key of BLANK_SENSITIVE_STRING_LIST_FIELDS) {
+        const value = next[key];
+        if (!Array.isArray(value))
+            continue;
+        const kept = value.filter((item) => !(typeof item === 'string' && item.trim() === ''));
+        if (kept.length === value.length)
+            continue;
+        if (kept.length === 0)
+            delete next[key];
+        else
+            next[key] = kept;
+    }
+    return next;
+}
 export function hasValidQualityTaskFields(value) {
     if (value['kind'] !== undefined && !TASK_KINDS.includes(value['kind']))
         return false;

package/lib/scheduler.js

@@ -8,7 +8,7 @@
  * the selected durable member. A resident member that becomes idle while it
  * still owns an open attempt is parked: only an explicit captain reassignment
  * may rotate that capability. Automatic retry is reserved for cold recovery,
- * when the durable owner is no longer resident in the live Agent registry.
+ * when this process has not observed the durable owner settle its open attempt.
  * @module dsh-agent-teams/scheduler
  */
 import { join } from 'node:path';
@@ -251,13 +251,11 @@ export function installTeamScheduler(ctx, config) {
                     if (currentMember === undefined || currentMember.id === '' || !isMemberAvailable(ctx, currentMember))
                         return undefined;
                     const owned = ownedOpenTask(fresh.tasks, currentMember.name);
-                    // A resident idle member can intentionally leave an attempt open
-                    // while waiting for guidance, or because the user paused its turn.
-                    // Re-dispatching here would revoke still-valid work on every idle
-                    // edge and every status kick. The idle observer remembers that exact
-                    // capability across normal continuable disposal; only an unobserved
-                    // durable capability (cold process recovery) or a legacy open task
-                    // with no capability is retried.
+                    // An idle edge observed by this scheduler parks the exact open
+                    // capability. Harness may dispose its AgentHandle after settlement,
+                    // so registry absence is not evidence that the owner was lost. Keep
+                    // the marker sticky across later kicks; only a durable attempt that
+                    // this process has not observed is eligible for one cold recovery.
                     const parkedAttemptId = parkedAttempts.get(currentMember.id);
                     const recoverOwned = owned !== undefined
                         && (owned.attemptId === undefined || owned.attemptId !== parkedAttemptId);
@@ -272,8 +270,18 @@ export function installTeamScheduler(ctx, config) {
                         return undefined;
                     }
                     const previousAssignee = task.assignee;
+                    const previousStatus = recoverOwned ? task.status : undefined;
+                    const previousAttempt = recoverOwned ? task.attempt : undefined;
+                    const previousAttemptId = recoverOwned ? task.attemptId : undefined;
                     const attemptId = beginTaskAttempt(task, currentMember.name);
-                    parkedAttempts.delete(currentMember.id);
+                    // A recovered generation is parked before delivery. This makes each
+                    // (member, attempt) recovery idempotent even if every status poll
+                    // sees a disposed handle. Fresh pending work remains unparked so a
+                    // genuinely lost first delivery can be recovered once.
+                    if (recoverOwned)
+                        parkedAttempts.set(currentMember.id, attemptId);
+                    else
+                        parkedAttempts.delete(currentMember.id);
                     currentMember.status = 'working';
                     await writeTeam(stateRoot, fresh);
                     const profileSeedId = taskProfileSeedId(task);
@@ -285,6 +293,10 @@ export function installTeamScheduler(ctx, config) {
                         attempt: task.attempt ?? 1,
                         attemptId,
                         previousAssignee,
+                        recoveredOwned: recoverOwned,
+                        ...previousStatus === undefined ? {} : { previousStatus },
+                        ...previousAttempt === undefined ? {} : { previousAttempt },
+                        ...previousAttemptId === undefined ? {} : { previousAttemptId },
                         subject: task.subject,
                         description: task.description,
                         teamDescription: fresh.description,
@@ -318,9 +330,22 @@ export function installTeamScheduler(ctx, config) {
                     const task = fresh.tasks.find(candidate => candidate.id === ticket.taskId);
                     if (task?.attemptId !== ticket.attemptId)
                         return;
-                    task.status = 'pending';
-                    task.assignee = ticket.previousAssignee;
-                    task.attemptId = undefined;
+                    if (ticket.recoveredOwned && ticket.previousStatus !== undefined && ticket.previousAttemptId !== undefined) {
+                        // Recovery delivery failed. Restore the durable generation instead
+                        // of returning it to pending, then keep it parked so later status
+                        // kicks cannot spend an unbounded sequence of fresh attempts.
+                        task.status = ticket.previousStatus;
+                        task.assignee = ticket.previousAssignee;
+                        task.attempt = ticket.previousAttempt;
+                        task.attemptId = ticket.previousAttemptId;
+                        parkedAttempts.set(ticket.memberId, ticket.previousAttemptId);
+                    }
+                    else {
+                        task.status = 'pending';
+                        task.assignee = ticket.previousAssignee;
+                        task.attemptId = undefined;
+                        parkedAttempts.delete(ticket.memberId);
+                    }
                     task.handoffId = undefined;
                     task.reassigning = false;
                     task.updatedAt = Date.now();

package/lib/state.js

@@ -17,8 +17,8 @@ import { readFileSync } from 'node:fs';
 import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { TERMINAL_TASK_STATUSES } from "./types.js";
-import { hasValidQualityTaskFields, isReviewPolicy } from "./quality-gates.js";
-export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from "./quality-gates.js";
+import { hasValidQualityTaskFields, isReviewPolicy, normalizeBlankOptionalTaskFields } from "./quality-gates.js";
+export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from "./quality-gates.js";
 /** Mailbox key of the captain. */
 export const CAPTAIN_KEY = 'captain';
 /** A crashed live-delivery attempt becomes retryable after this interval. */
@@ -37,15 +37,29 @@ export async function withTeamLock(key, fn) {
     const previous = locks.get(key) ?? Promise.resolve();
     let release;
     const gate = new Promise((resolve) => { release = resolve; });
-    locks.set(key, previous.then(() => gate));
+    const tail = previous.then(() => gate);
+    locks.set(key, tail);
     await previous;
     try {
         return await fn();
     }
     finally {
         release();
+        // Drop this key's queue entry once we are still its tail, so settled
+        // teams do not leave one resolved promise chained forever (the same
+        // cleanup discipline as the scheduler's serializeMember). A successor
+        // that already appended itself owns the map slot; keep its entry.
+        if (locks.get(key) === tail)
+            locks.delete(key);
     }
 }
+/**
+ * Keys with an in-process lock queue (held or waiting), snapshot for
+ * diagnostics and leak checks. The queue promises themselves stay private.
+ */
+export function teamLockQueueKeys() {
+    return [...locks.keys()];
+}
 /** Longest key emitted before truncating and appending a digest. */
 const MAX_KEY_LENGTH = 48;
 /** Short stable digest, used to keep otherwise-colliding keys distinct. */
@@ -228,13 +242,27 @@ export async function writeTeam(stateRoot, state) {
     await atomicWriteText(join(stateRoot, state.id, 'team.json'), JSON.stringify(state, null, 2));
 }
 /** Read the durable set of member session ids retired by remove/delete. */
+function parseRetiredMemberIds(raw) {
+    const parsed = JSON.parse(stripLeadingBom(raw));
+    if (!Array.isArray(parsed) || parsed.some(value => typeof value !== 'string' || value === '')) {
+        throw new Error('invalid AgentTeams retired member index');
+    }
+    return new Set(parsed);
+}
+/** Synchronous role hydration before the host's first prompt assembly. */
+export function readRetiredMemberIdsSync(stateRoot) {
+    try {
+        return parseRetiredMemberIds(readFileSync(join(stateRoot, RETIRED_MEMBERS_FILE), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return new Set();
+        throw error;
+    }
+}
 export async function readRetiredMemberIds(stateRoot) {
     try {
-        const parsed = JSON.parse(stripLeadingBom(await readFile(join(stateRoot, RETIRED_MEMBERS_FILE), 'utf8')));
-        if (!Array.isArray(parsed) || parsed.some(value => typeof value !== 'string' || value === '')) {
-            throw new Error('invalid AgentTeams retired member index');
-        }
-        return new Set(parsed);
+        return parseRetiredMemberIds(await readFile(join(stateRoot, RETIRED_MEMBERS_FILE), 'utf8'));
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
@@ -626,12 +654,17 @@ function coerceTeamState(value, expectedId) {
     const tasks = value['tasks'].map((task) => {
         if (!isRecord(task))
             return task;
-        if (task['profileSeedId'] !== undefined && (typeof task['profileSeedId'] !== 'string' || task['profileSeedId'].trim() === '')) {
-            const next = { ...task };
+        // Tolerate legacy dirty records instead of bricking the whole team on
+        // reload: blank optional fields written by older builds (or by models that
+        // materialize optionals as "") are normalized to omitted, matching the
+        // profileSeedId handling below and the tool-input normalization.
+        const cleaned = normalizeBlankOptionalTaskFields(task);
+        if (cleaned['profileSeedId'] !== undefined && (typeof cleaned['profileSeedId'] !== 'string' || cleaned['profileSeedId'].trim() === '')) {
+            const next = { ...cleaned };
             delete next['profileSeedId'];
             return next;
         }
-        return task;
+        return cleaned;
     });
     const coerced = { ...value, tasks };
     return isTeamState(coerced, expectedId) ? coerced : undefined;

package/lib/tool-names.js

@@ -0,0 +1,11 @@
+/** Stable business API names; exposure changes never rename these operations. */
+export const TEAM_TOOL_NAMES = [
+    'agent_teams_create', 'agent_teams_approve', 'agent_teams_edit_plan',
+    'agent_teams_add_member', 'agent_teams_remove_member', 'agent_teams_create_task',
+    'agent_teams_reassign_task', 'agent_teams_claim_task', 'agent_teams_update_task',
+    'agent_teams_send_message', 'agent_teams_status', 'agent_teams_resume', 'agent_teams_delete',
+];
+export const MEMBER_TOOL_NAMES = [
+    'agent_teams_claim_task', 'agent_teams_update_task', 'agent_teams_send_message', 'agent_teams_status',
+];
+export const CAPTAIN_TOOL_NAMES = TEAM_TOOL_NAMES.filter(name => !MEMBER_TOOL_NAMES.includes(name));