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

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. */
@@ -626,12 +626,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/tools.js

@@ -12,11 +12,12 @@ 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 { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, removeTeamDir, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, } from "./state.js";
-import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, validateMemberLlmSelections, } from "./members.js";
+import { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, removeTeamDir, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, normalizeBlankOptionalTaskFields, taskKindOf, } from "./state.js";
+import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, steerCaptainReport, validateMemberLlmSelections, } from "./members.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
 import { installTeamScheduler } from "./scheduler.js";
 import { resolveTeamProfile } from "./profiles.js";
+export { steerCaptainReport } from "./members.js";
 /** The caller agent, or a loud failure for non-agent callers. */
 function requireCaptain(exec) {
     if (!exec.agent) {
@@ -275,19 +276,6 @@ export async function haltTeamWork(input) {
         alreadyHalted: halted.alreadyHalted,
     };
 }
-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 {
-        // The plugin mailbox was persisted before this best-effort live delivery.
-        return false;
-    }
-}
 /** Context queued after the human rejects a staged plan. */
 export function stagedPlanDiscardContext(teamName) {
     return [
@@ -313,8 +301,8 @@ export function stagedPlanFeedbackContext(teamName) {
  */
 export function registerAgentTeamsTools(ctx, config) {
     installRetiredMemberGuard(ctx, config.stateDir);
-    const memberSelections = installMemberSelectionRuntime(ctx, config.stateDir);
     const scheduler = installTeamScheduler(ctx, { stateDir: config.stateDir, executionPrompt: config.executionPrompt });
+    const memberSelections = installMemberSelectionRuntime(ctx, config.stateDir, (workspace, teamId, memberName) => (scheduler.kickMember(workspace, teamId, memberName)));
     const updateStagedPlanBatch = async (captain, teamId, mutations, signal) => {
         if (mutations.length === 0)
             throw new Error('at least one staged plan operation is required');
@@ -586,10 +574,12 @@ export function registerAgentTeamsTools(ctx, config) {
                 throw new Error('team name must not be empty');
             const teamId = sanitizeKey(teamName);
             const staged = args.approval === 'required';
-            const profileName = args.profile?.trim();
-            if (args.profile !== undefined && profileName === '') {
-                throw new Error('AgentTeams profile name must not be empty');
-            }
+            // Some models materialize optional parameters as "" instead of omitting
+            // them (issue #99). The profile is optional, so treat a blank value
+            // exactly like an omitted one instead of failing every create call.
+            const profileName = args.profile !== undefined && args.profile.trim() !== ''
+                ? args.profile.trim()
+                : undefined;
             const created = await withTeamLock(captainLockKey(stateRoot, captain.id), async () => {
                 const current = await findTeamByParticipant(stateRoot, captain.id);
                 if (current !== undefined) {
@@ -927,6 +917,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     provider: selection.provider,
                     model: selection.model,
                     reasoningEffort: selection.reasoningEffort,
+                    ...selection.fallback === undefined ? {} : { fallback: selection.fallback },
                     executionPrompt: trimmedOptional(args.executionPrompt),
                     joinedAt: Date.now(),
                     status: 'idle',
@@ -1081,28 +1072,33 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(captain);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireCaptainTeam(workspace, config, captain);
+            // Some models materialize optional parameters as "" instead of omitting
+            // them (issue #105). Normalize blank optional fields to omitted before
+            // validation so a blank value can neither be rejected spuriously nor be
+            // persisted into team.json, where it would brick the team on reload.
+            const input = normalizeBlankOptionalTaskFields(args);
             const created = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
                 const gate = validateCreateTask(fresh, {
-                    subject: args.subject,
-                    description: args.description,
-                    dependencies: args.dependencies,
-                    assignee: args.assignee,
-                    kind: args.kind,
-                    round: args.round,
-                    objective: args.objective,
-                    inScope: args.inScope,
-                    outOfScope: args.outOfScope,
-                    acceptance: args.acceptance,
-                    verify: args.verify,
-                    deliverables: args.deliverables,
-                    nonGoals: args.nonGoals,
-                    reviewedTaskId: args.reviewedTaskId,
-                    sourceTaskId: args.sourceTaskId,
-                    sourceFindingIds: args.sourceFindingIds,
-                    coverageOf: args.coverageOf,
-                    resume: args.resume,
-                    resumeReason: args.resumeReason,
+                    subject: input.subject,
+                    description: input.description,
+                    dependencies: input.dependencies,
+                    assignee: input.assignee,
+                    kind: input.kind,
+                    round: input.round,
+                    objective: input.objective,
+                    inScope: input.inScope,
+                    outOfScope: input.outOfScope,
+                    acceptance: input.acceptance,
+                    verify: input.verify,
+                    deliverables: input.deliverables,
+                    nonGoals: input.nonGoals,
+                    reviewedTaskId: input.reviewedTaskId,
+                    sourceTaskId: input.sourceTaskId,
+                    sourceFindingIds: input.sourceFindingIds,
+                    coverageOf: input.coverageOf,
+                    resume: input.resume,
+                    resumeReason: input.resumeReason,
                 });
                 if (!gate.ok)
                     throw new Error(gate.error ?? 'create_task rejected by quality gates');
@@ -1128,11 +1124,11 @@ export function registerAgentTeamsTools(ctx, config) {
                     requireMember(fresh, args.assignee);
                 const kind = gate.kind ?? 'work';
                 const objective = kind === 'review' || kind === 'requirements'
-                    ? sanitizeReviewObjective(args.objective)
-                    : args.objective;
+                    ? sanitizeReviewObjective(input.objective)
+                    : input.objective;
                 const acceptance = kind === 'review' || kind === 'requirements'
-                    ? sanitizeReviewAcceptance(args.acceptance)
-                    : args.acceptance;
+                    ? sanitizeReviewAcceptance(input.acceptance)
+                    : input.acceptance;
                 const task = {
                     id: `t${fresh.taskSeq + 1}`,
                     subject: args.subject,
@@ -1146,16 +1142,16 @@ export function registerAgentTeamsTools(ctx, config) {
                     kind,
                     ...args.round === undefined ? {} : { round: args.round },
                     ...objective === undefined ? {} : { objective },
-                    ...args.inScope === undefined ? {} : { inScope: args.inScope },
-                    ...args.outOfScope === undefined ? {} : { outOfScope: args.outOfScope },
+                    ...input.inScope === undefined ? {} : { inScope: input.inScope },
+                    ...input.outOfScope === undefined ? {} : { outOfScope: input.outOfScope },
                     ...acceptance === undefined ? {} : { acceptance },
-                    ...args.verify === undefined ? {} : { verify: args.verify },
-                    ...args.deliverables === undefined ? {} : { deliverables: args.deliverables },
-                    ...args.nonGoals === undefined ? {} : { nonGoals: args.nonGoals },
-                    ...args.reviewedTaskId === undefined ? {} : { reviewedTaskId: args.reviewedTaskId },
-                    ...args.sourceTaskId === undefined ? {} : { sourceTaskId: args.sourceTaskId },
-                    ...args.sourceFindingIds === undefined ? {} : { sourceFindingIds: args.sourceFindingIds },
-                    ...args.coverageOf === undefined ? {} : { coverageOf: args.coverageOf },
+                    ...input.verify === undefined ? {} : { verify: input.verify },
+                    ...input.deliverables === undefined ? {} : { deliverables: input.deliverables },
+                    ...input.nonGoals === undefined ? {} : { nonGoals: input.nonGoals },
+                    ...input.reviewedTaskId === undefined ? {} : { reviewedTaskId: input.reviewedTaskId },
+                    ...input.sourceTaskId === undefined ? {} : { sourceTaskId: input.sourceTaskId },
+                    ...input.sourceFindingIds === undefined ? {} : { sourceFindingIds: input.sourceFindingIds },
+                    ...input.coverageOf === undefined ? {} : { coverageOf: input.coverageOf },
                 };
                 fresh.taskSeq += 1;
                 fresh.tasks.push(task);
@@ -1304,10 +1300,10 @@ export function registerAgentTeamsTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_claim_task',
-        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.',
+        description: 'Members claim their own ready task or read their existing attempt_id. Captains must use reassign_task to assign and wake a member; claim_task does not dispatch work. A member cannot own a second unfinished task. The returned attempt_id is required for 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).' },
+            assignee: { type: 'string', description: 'Deprecated: claim_task only supports a member claiming its own task. Captains must use reassign_task.' },
         },
         output: {
             schema: {
@@ -1339,9 +1335,11 @@ export function registerAgentTeamsTools(ctx, config) {
                 }
                 let assignee = task.assignee;
                 if (identity.kind === 'captain') {
-                    if (args.assignee !== undefined) {
-                        requireMember(fresh, args.assignee);
-                        assignee = args.assignee;
+                    // A captain may read the capability of its already-started takeover,
+                    // but must never create a member claim without dispatching it (#125).
+                    if (args.assignee !== undefined || task.assignee !== CAPTAIN_KEY
+                        || (task.status !== 'claimed' && task.status !== 'in_progress')) {
+                        throw new Error('claim_task is for members claiming their own task; captains must use agent_teams_reassign_task to assign and wake a member');
                     }
                 }
                 else {
@@ -1518,6 +1516,10 @@ export function registerAgentTeamsTools(ctx, config) {
                         ...task.output !== undefined ? { output: task.output } : {},
                     };
                 }
+                // Blank optional list entries (e.g. changedPaths:[""]) must not be
+                // persisted: hasValidQualityTaskFields rejects them on reload and
+                // would brick the whole team state (issue #105 class).
+                const input = normalizeBlankOptionalTaskFields(args);
                 const findings = parseFindings(args.findings);
                 const acceptanceResults = parseAcceptanceResults(args.acceptanceResults);
                 const commandsRun = parseCommandResults(args.commandsRun);
@@ -1526,7 +1528,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     output: args.output,
                     verdict: args.verdict,
                     findings,
-                    changedPaths: args.changedPaths,
+                    changedPaths: input.changedPaths,
                     acceptanceResults,
                     commandsRun,
                 });
@@ -1544,8 +1546,8 @@ export function registerAgentTeamsTools(ctx, config) {
                     task.verdict = args.verdict;
                 if (findings !== undefined)
                     task.findings = findings;
-                if (args.changedPaths !== undefined)
-                    task.changedPaths = args.changedPaths;
+                if (input.changedPaths !== undefined)
+                    task.changedPaths = input.changedPaths;
                 if (acceptanceResults !== undefined)
                     task.acceptanceResults = acceptanceResults;
                 if (commandsRun !== undefined)
@@ -1698,7 +1700,7 @@ export function registerAgentTeamsTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_status',
-        description: 'Team snapshot: members with live activity and tasks with status/assignee/dependencies/output. Captains also see every team mailbox; members see only their own inbox. Poll this to watch progress.',
+        description: 'Team snapshot: members with live activity and tasks with status/assignee/dependencies/output. Captains also see every team mailbox; members see only their own inbox. Use after mailbox progress deliveries or for an explicit status request. After dispatch, end your turn while members work; do not repeatedly poll.',
         parameters: {},
         output: {
             schema: { type: 'object', additionalProperties: true, properties: {} },
@@ -2065,7 +2067,9 @@ function parseFindings(value) {
             severity: raw['severity'],
             problem: raw['problem'],
             requiredFix: raw['requiredFix'],
-            ...typeof raw['file'] === 'string' ? { file: raw['file'] } : {},
+            // A blank optional file must be omitted, not persisted: durable-state
+            // validation requires non-empty optional strings (issue #105 class).
+            ...typeof raw['file'] === 'string' && raw['file'].trim() !== '' ? { file: raw['file'] } : {},
             ...typeof raw['line'] === 'number' ? { line: raw['line'] } : {},
             ...typeof raw['resolved'] === 'boolean' ? { resolved: raw['resolved'] } : {},
         };

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

@@ -81,7 +81,6 @@ export declare const zh: {
     'dependency.hint.pinned': string;
     'task.runningAria': string;
     'task.model': string;
-    'member.model': string;
     'task.detail.completed': string;
     'task.detail.noPrerequisite': string;
     'task.detail.ready': string;
@@ -275,7 +274,6 @@ export declare const en: {
     'dependency.hint.pinned': string;
     'task.runningAria': string;
     'task.model': string;
-    'member.model': string;
     'task.detail.completed': string;
     'task.detail.noPrerequisite': string;
     'task.detail.ready': string;

package/lib/types/harness-compat.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The audited Harness 0.1.2 subagent boundary. Keep version-specific shapes
+ * here: API presence alone is not a promise of support for future versions.
+ *
+ * Alpha.2 owns followup/registerContinuableSetup; Alpha.5 and rc.1 own a
+ * host-only FIFO queue and synchronous agent/session-start. Their public
+ * sendMessage instead steers a running Agent and must never carry team jobs.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+type Setup = (childCtx: Context) => () => void;
+/** Read child-owned history, excluding any descriptor inherited from a parent. */
+export declare function sessionOwnEvents(session: Session): readonly SessionEvent[];
+/** Install before the first request, including cold resume, with HMR cleanup. */
+export declare function installContinuableMemberSetup(ctx: Context, setup: Setup): void;
+/** Queue a distinct host-authored turn; never substitute model-message steer. */
+export declare function queueMemberPrompt(runtime: Context['subagents'], parent: Agent, childId: SessionId, content: ContentBlock[], signal: AbortSignal): Promise<MessageId>;
+/** Guard all resumable delivery paths, preserving the native service receiver. */
+export declare function guardSubagentDelivery(ctx: Context, isRetired: (sender: Agent, targetId: SessionId) => Promise<boolean>): void;
+export {};

package/lib/types/members.d.ts

@@ -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,7 +13,8 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { type Agent } from '@deepseek-ai/dsh-agent';
-import { type TeamMember, type TeamState } from './types.ts';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { type TeamMember, type TeamState, type TeamTask } from './types.ts';
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
 export declare const PERSONA_PROTOCOL_MAX_CHARS = 400;
 /** Runtime knobs for member spawning, resolved from plugin config. */
@@ -88,6 +89,18 @@ export declare function selectFallbackRoute(current: {
         model: string;
     };
 };
+/** Deliver a durable member report to the live captain at its next model step. */
+export declare function steerCaptainReport(captain: Pick<Agent, 'steer'>, from: string, content: string): boolean;
+interface FailedMemberAttempt {
+    readonly captainSessionId: string;
+    readonly memberId: string;
+    readonly task?: Pick<TeamTask, 'id' | 'attempt' | 'attemptId'>;
+}
+/** Record a final turn failure, never an intermediate request retry. */
+export declare function failMemberOpenAttempt(ctx: Context, stateRoot: string, teamId: string, memberName: string, failure: {
+    readonly code: string;
+    readonly message: string;
+}, fallbackSession: Session, observed: FailedMemberAttempt): Promise<boolean>;
 /**
  * Resolve one member's complete model selection. Ordinary members snapshot the
  * captain's current request route and reasoning effort. When provider or model
@@ -105,7 +118,7 @@ export declare function resolveMemberLlmSelection(ctx: Context, captain: Agent,
  * record. Legacy members without a complete saved route retain Harness's
  * descriptor provider/model behavior.
  */
-export declare function installMemberSelectionRuntime(ctx: Context, stateDir: string): MemberSelectionRuntime;
+export declare function installMemberSelectionRuntime(ctx: Context, stateDir: string, onFailureSettled?: (workspace: string, teamId: string, memberName: string) => Promise<void>): MemberSelectionRuntime;
 /**
  * The member's system prompt (persona), shadowing the deployment persona for
  * that child. Self-contained: it replaces the whole persona section.
@@ -168,12 +181,12 @@ export declare function interruptMember(ctx: Context, captain: Agent, childId: s
  *
  * 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 declare function installRetiredMemberGuard(ctx: Context, stateDir: string): void;
 /**
@@ -189,3 +202,4 @@ export declare function installRetiredMemberGuard(ctx: Context, stateDir: string
  * @returns child id → live activity.
  */
 export declare function memberActivity(ctx: Context, memberIds: readonly string[]): Map<string, 'running' | 'idle' | 'ready'>;
+export {};

package/lib/types/quality-gates.d.ts

@@ -128,6 +128,14 @@ export declare function resumeTeamState(team: TeamState, reason: string): Resume
 export declare function isReviewFinding(value: unknown): value is ReviewFinding;
 export declare function isAcceptanceResult(value: unknown): value is AcceptanceResult;
 export declare function isCommandResult(value: unknown): value is CommandResult;
+/**
+ * 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 declare function normalizeBlankOptionalTaskFields<T extends object>(task: T): T;
 export declare function hasValidQualityTaskFields(value: Record<string, unknown>): boolean;
 export declare function isTaskKind(value: unknown): value is TaskKind;
 export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;

package/lib/types/scheduler.d.ts

@@ -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 type { Context } from '@deepseek-ai/cordis';
@@ -42,6 +42,12 @@ export interface DispatchTicket {
     readonly attempt: number;
     readonly attemptId: string;
     readonly previousAssignee?: string;
+    /** True when this ticket rotates an unobserved durable open attempt. */
+    readonly recoveredOwned: boolean;
+    /** Original task generation, used to restore a failed automatic recovery. */
+    readonly previousStatus?: 'claimed' | 'in_progress';
+    readonly previousAttempt?: number;
+    readonly previousAttemptId?: string;
     readonly subject: string;
     readonly description?: string;
     readonly teamDescription?: string;

package/lib/types/state.d.ts

@@ -13,7 +13,7 @@
  * @module dsh-agent-teams/state
  */
 import { type TaskStatus, type TeamMessage, type TeamState, type TeamTask } from './types.ts';
-export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
+export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
 /** Mailbox key of the captain. */
 export declare const CAPTAIN_KEY = "captain";
 /**

package/lib/types/tools.d.ts

@@ -11,6 +11,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { type TeamState, type TeamTask } from './types.ts';
+export { steerCaptainReport } from './members.ts';
 /** Resolved plugin config consumed by the tools. */
 export interface ToolsConfig {
     /** State directory name under the captain's workspace. */
@@ -87,7 +88,6 @@ export declare function haltTeamWork(input: {
     cancelledTasks: number;
     alreadyHalted: boolean;
 }>;
-export declare function steerCaptainReport(captain: Pick<Agent, 'steer'>, from: string, content: string): boolean;
 /** Context queued after the human rejects a staged plan. */
 export declare function stagedPlanDiscardContext(teamName: string): string;
 /** Model-facing continuation that turns the review UI back into a conversation. */

package/lib/types/web-routes.d.ts

@@ -9,5 +9,11 @@ export interface WebRouteHost {
     }): () => void;
 }
 export type BrowserRequestGate = Pick<HostConnectionService, 'requestRejection'>;
+export declare class RequestBodyError extends Error {
+    readonly status: 400 | 413;
+    constructor(message: string, status: 400 | 413);
+}
+/** Bound memory while draining oversized requests so the route can return 413. */
+export declare function readJsonRequest(req: IncomingMessage, maxBytes?: number): Promise<Record<string, unknown>>;
 /** Raw WebServer routes do not inherit Connection's authentication fence. */
 export declare function authenticatedWebRoutes(server: WebRouteHost, connection: () => BrowserRequestGate | undefined): WebRouteHost;

package/lib/web-routes.js

@@ -1,3 +1,63 @@
+export class RequestBodyError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Bound memory while draining oversized requests so the route can return 413. */
+export async function readJsonRequest(req, maxBytes = 1_000_000) {
+    const raw = await new Promise((resolve, reject) => {
+        let size = 0;
+        let settled = false;
+        const chunks = [];
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            req.off('data', onData);
+            req.off('end', onEnd);
+            req.off('aborted', onAborted);
+            req.off('error', onError);
+            if (error) {
+                chunks.length = 0;
+                // IncomingMessage may still receive data; discard it without buffering.
+                req.once('error', () => { });
+                req.resume();
+                reject(error);
+            }
+            else {
+                resolve(Buffer.concat(chunks).toString('utf8'));
+            }
+        };
+        const onData = (chunk) => {
+            const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += part.length;
+            if (size > maxBytes)
+                finish(new RequestBodyError('request body is too large', 413));
+            else
+                chunks.push(part);
+        };
+        const onEnd = () => finish();
+        const onAborted = () => finish(new RequestBodyError('request body was aborted', 400));
+        const onError = () => finish(new RequestBodyError('invalid request body', 400));
+        req.on('data', onData);
+        req.once('end', onEnd);
+        req.once('aborted', onAborted);
+        req.once('error', onError);
+    });
+    let value;
+    try {
+        value = raw.trim() === '' ? {} : JSON.parse(raw);
+    }
+    catch {
+        throw new RequestBodyError('invalid JSON', 400);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new RequestBodyError('body must be an object', 400);
+    }
+    return value;
+}
 /** Raw WebServer routes do not inherit Connection's authentication fence. */
 export function authenticatedWebRoutes(server, connection) {
     return {