@nanmicoder/dsh-agent-teams 0.1.22 → 0.1.23

package/lib/scheduler.js

@@ -15,6 +15,8 @@ import { join } from 'node:path';
 import { deliverToMember } from "./members.js";
 import { isCurrentMail, mailboxPrompt } from "./mailbox.js";
 import { markMailboxDelivered, discardMailboxMessages, beginTaskAttempt, CAPTAIN_KEY, claimMailboxDelivery, findTeamByParticipant, invalidateTaskAttempt, readTeam, readPendingMailbox, releaseMailboxDelivery, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
+import { contractStaleness, isVerdictKind, taskKindOf, verdictScopePatterns } from "./quality-gates.js";
+import { digestWorkspacePaths, snapshotWorkspacePaths } from "./artifacts.js";
 /** Per-dependency output cap in the assignment prompt. */
 export const DEPENDENCY_OUTPUT_MAX_CHARS = 2_000;
 /** Combined dependency-output budget in the assignment prompt. */
@@ -120,13 +122,16 @@ function nextReadyTask(tasks, memberName) {
     return ready.find(task => task.assignee === memberName)
         ?? ready.find(task => task.assignee === undefined);
 }
-export function assignmentPrompt(ticket, stateDir, teamId) {
+export function assignmentPrompt(ticket, stateDir, teamId, workOrderWarnings = []) {
     const description = ticket.description === undefined ? '' : `\n\n${ticket.description}`;
     const seed = ticket.profileSeedId === undefined ? '' : ` [${ticket.profileSeedId}]`;
     const goal = ticket.teamDescription?.trim() || '(not provided)';
     const protocol = ticket.profileProtocol?.trim() || '(none)';
     const executionPrompt = ticket.executionPrompt?.trim();
     const kind = ticket.kind?.trim() || 'work';
+    const staleWorkOrder = workOrderWarnings.length === 0
+        ? ''
+        : `\nBefore you edit anything: this auto-generated work order was derived from a workspace that has since changed.\n${workOrderWarnings.map((warning) => `- ${warning}`).join('\n')}\nRe-read the cited files first, locate the code by content anchor rather than by any position, and report a blocker instead of editing a target that no longer exists.\n`;
     const contract = [
         `Kind: ${kind}${ticket.round === undefined ? '' : ` (round ${ticket.round})`}`,
         ticket.objective === undefined || ticket.objective === '' ? '' : `Objective: ${ticket.objective}`,
@@ -135,6 +140,7 @@ export function assignmentPrompt(ticket, stateDir, teamId) {
         ticket.acceptance === undefined || ticket.acceptance.length === 0 ? '' : `Acceptance: ${ticket.acceptance.join('; ')}`,
         ticket.verify === undefined || ticket.verify.length === 0 ? '' : `Verify: ${ticket.verify.join('; ')}`,
         ticket.reviewedTaskId === undefined ? '' : `Reviewed task: ${ticket.reviewedTaskId}`,
+        ticket.findingSourceTaskIds === undefined || ticket.findingSourceTaskIds.length === 0 ? '' : `Fixes findings of: ${ticket.findingSourceTaskIds.join(', ')}`,
     ].filter((line) => line !== '').join('\n');
     const structuredCompletion = ['implementation', 'repair', 'verification', 'integration'].includes(kind)
         ? `
@@ -161,7 +167,7 @@ Completed dependency results:
 ${formatDependencyOutputs(ticket.dependencyOutputs)}
 
 Task: ${ticket.taskId}${seed} — ${ticket.subject}${description}
-${contract === '' ? '' : `\nContract:\n${contract}\n`}
+${staleWorkOrder}${contract === '' ? '' : `\nContract:\n${contract}\n`}
 ${structuredCompletion}
 Attempt: ${ticket.attempt}
 Attempt id: ${ticket.attemptId}
@@ -286,6 +292,14 @@ export function installTeamScheduler(ctx, config) {
                         changedPaths: task.changedPaths, acceptanceResults: task.acceptanceResults, commandsRun: task.commandsRun,
                     } : undefined;
                     const attemptId = beginTaskAttempt(task, currentMember.name);
+                    // A verdict must be able to say which revision was on disk when it
+                    // started, so a review that runs while someone else edits the tree
+                    // cannot later claim to have judged stable bytes (issue #161).
+                    if (isVerdictKind(taskKindOf(task))) {
+                        const scope = verdictScopePatterns(fresh, task);
+                        if (scope.length > 0)
+                            task.verdictStartSnapshot = snapshotWorkspacePaths(workspace, scope);
+                    }
                     // 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
@@ -326,12 +340,17 @@ export function installTeamScheduler(ctx, config) {
                         ...task.acceptance === undefined ? {} : { acceptance: task.acceptance },
                         ...task.verify === undefined ? {} : { verify: task.verify },
                         ...task.reviewedTaskId === undefined ? {} : { reviewedTaskId: task.reviewedTaskId },
+                        ...task.findingSourceTaskIds === undefined ? {} : { findingSourceTaskIds: task.findingSourceTaskIds },
                         dependencyOutputs: collectCompletedDependencyOutputs(fresh.tasks, task.id, (message) => ctx.logger.warn(message)),
                     };
                 });
                 if (ticket === undefined)
                     return;
-                const prompt = assignmentPrompt(ticket, config.stateDir, team.id);
+                const taskForWarning = team.tasks.find((item) => item.id === ticket.taskId);
+                const workOrderStale = taskForWarning?.contractSnapshot === undefined
+                    ? []
+                    : contractStaleness(taskForWarning, digestWorkspacePaths(workspace, taskForWarning.contractSnapshot.artifacts.map((artifact) => artifact.path)));
+                const prompt = assignmentPrompt(ticket, config.stateDir, team.id, workOrderStale);
                 const signal = new AbortController().signal;
                 const accepted = config.dispatch === undefined
                     ? await deliverToMember(ctx, captain, ticket.memberId, prompt, signal)

package/lib/snapshot.js

@@ -10,6 +10,8 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { memberActivity } from "./members.js";
+import { canDeclareDelivery, describeQualityLoop, verdictAuditNotes } from "./quality-gates.js";
+import { auditTeamWorkspace } from "./workspace-audit.js";
 import { CAPTAIN_KEY, listArchivedTeamIds, readArchivedTeam, readUnreadMailbox, readTeam, taskDepthsById, taskVisualState, } from "./state.js";
 /** The current task of a member: its first unfinished owned task. */
 function currentTaskOf(memberName, tasks) {
@@ -85,6 +87,17 @@ export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state, opt
         };
     });
     const captainInbox = await readUnreadMailbox(stateRoot, state.id, CAPTAIN_KEY);
+    // The panel must reach the same delivery conclusion as the status tool, so
+    // it reads the same current bytes instead of trusting task records alone.
+    const audit = options.workspacePath === undefined ? undefined : auditTeamWorkspace(options.workspacePath, state);
+    const deliveryCheck = audit === undefined ? canDeclareDelivery(state) : canDeclareDelivery(state, audit);
+    const loop = audit === undefined ? describeQualityLoop(state) : describeQualityLoop(state, audit);
+    const staleById = new Map();
+    if (audit !== undefined) {
+        for (const note of verdictAuditNotes(state, audit)) {
+            staleById.set(note.taskId, [...staleById.get(note.taskId) ?? [], note.message]);
+        }
+    }
     return {
         workspace,
         teamId: state.id,
@@ -96,6 +109,11 @@ export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state, opt
             ? { planReviewState: state.planReviewState ?? 'awaiting_review' }
             : {},
         ...state.halted === true ? { halted: true } : {},
+        ...audit === undefined ? {} : {
+            loopState: loop.state,
+            deliverable: loop.deliverable,
+            delivery: { ok: deliveryCheck.ok, blockers: [...deliveryCheck.blockers], warnings: [...deliveryCheck.warnings] },
+        },
         members,
         tasks: tasks.map((task) => ({
             id: task.id,
@@ -110,6 +128,7 @@ export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state, opt
             ...task.kind === undefined ? {} : { kind: task.kind },
             ...task.round === undefined ? {} : { round: task.round },
             ...task.verdict === undefined ? {} : { verdict: task.verdict },
+            ...staleById.get(task.id) === undefined ? {} : { verdictStale: staleById.get(task.id).join('; ') },
             updatedAt: task.updatedAt,
         })),
         messageCount: captainInbox.length
@@ -146,7 +165,9 @@ export async function collectTeamsActivity(ctx, roots) {
                 const state = await readTeam(root.stateRoot, entry.name);
                 if (state === undefined)
                     continue;
-                snapshots.push(await assembleTeamSnapshot(ctx, root.stateRoot, root.workspace, state));
+                snapshots.push(await assembleTeamSnapshot(ctx, root.stateRoot, root.workspace, state, {
+                    ...root.workspacePath === undefined ? {} : { workspacePath: root.workspacePath },
+                }));
             }
             catch {
                 ctx.logger.warn(`agent-teams: skipped unreadable team state "${entry.name}" in workspace "${root.workspace}"`);

package/lib/state.js

@@ -16,9 +16,10 @@ import { createHash, randomUUID } from 'node:crypto';
 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, normalizeBlankOptionalTaskFields } from "./quality-gates.js";
-export { amendTaskContract, buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, isTaskRevision, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from "./quality-gates.js";
+import { FINDING_SEVERITIES, REVIEW_VERDICTS, TASK_KINDS, TERMINAL_TASK_STATUSES } from "./types.js";
+import { hasValidQualityTaskFields, isReviewPolicy, isValidFindingLine, normalizeBlankOptionalTaskFields } from "./quality-gates.js";
+import { teamLeadMatch } from "./lineage.js";
+export { amendTaskContract, buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, isTaskRevision, isValidFindingLine, normalizeBlankOptionalTaskFields, normalizeSentinelNumericTaskFields, 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. */
@@ -205,7 +206,7 @@ export async function readTeam(stateRoot, teamId) {
         const value = JSON.parse(stripLeadingBom(raw));
         const team = coerceTeamState(value, teamId);
         if (team === undefined) {
-            throw new Error(`invalid AgentTeams state in team "${teamId}"`);
+            throw new Error(`invalid AgentTeams state in team "${teamId}": ${describeTeamStateDefect(value, teamId)}`);
         }
         return team;
     }
@@ -231,7 +232,7 @@ export function readTeamSync(stateRoot, teamId) {
         const value = JSON.parse(stripLeadingBom(raw));
         const team = coerceTeamState(value, teamId);
         if (team === undefined) {
-            throw new Error(`invalid AgentTeams state in team "${teamId}"`);
+            throw new Error(`invalid AgentTeams state in team "${teamId}": ${describeTeamStateDefect(value, teamId)}`);
         }
         return team;
     }
@@ -297,9 +298,11 @@ export async function recordRetiredMemberIds(stateRoot, memberIds) {
  * Find the team owned by one captain session (at most one per captain).
  * @param stateRoot - resolved absolute state root directory.
  * @param captainSessionId - the owning session id.
+ * @param lead - durable lead identity of the calling session, when it may lead
+ *   through a fork chain; omitted keeps the exact-id contract.
  * @returns the team record, or undefined when the captain leads no team.
  */
-export async function findTeamByCaptain(stateRoot, captainSessionId) {
+export async function findTeamByCaptain(stateRoot, captainSessionId, lead) {
     let entries;
     try {
         entries = await readdir(stateRoot, { withFileTypes: true });
@@ -315,7 +318,8 @@ export async function findTeamByCaptain(stateRoot, captainSessionId) {
         if (!entry.isDirectory())
             continue;
         const team = await readTeam(stateRoot, entry.name);
-        if (team?.captainSessionId === captainSessionId) {
+        if (team !== undefined && (team.captainSessionId === captainSessionId
+            || (lead !== undefined && teamLeadMatch(team, lead)))) {
             if (found !== undefined && found.id !== team.id) {
                 throw new Error(`captain session leads multiple active teams ("${found.id}", "${team.id}"); archive one before continuing`);
             }
@@ -326,13 +330,15 @@ export async function findTeamByCaptain(stateRoot, captainSessionId) {
 }
 /**
  * Find the team in which one session is an active participant.
- * Captains match `captainSessionId`; members match their durable child session
- * id. Removed members no longer have access to team-scoped tools.
+ * Captains match `captainSessionId` — including a lead session that inherited
+ * it through a fork — and members match their durable child session id.
+ * Removed members no longer have access to team-scoped tools.
  * @param stateRoot - resolved absolute state root directory.
  * @param agentSessionId - calling captain/member session id.
+ * @param lead - durable lead identity of the calling session, when available.
  * @returns the team record, or undefined when the caller belongs to no team.
  */
-export async function findTeamByParticipant(stateRoot, agentSessionId) {
+export async function findTeamByParticipant(stateRoot, agentSessionId, lead) {
     let entries;
     try {
         entries = await readdir(stateRoot, { withFileTypes: true });
@@ -348,8 +354,9 @@ export async function findTeamByParticipant(stateRoot, agentSessionId) {
         if (!entry.isDirectory())
             continue;
         const team = await readTeam(stateRoot, entry.name);
-        const participates = team?.captainSessionId === agentSessionId
-            || team?.members.some((member) => member.id === agentSessionId && member.status !== 'removed') === true;
+        const participates = team !== undefined && (team.captainSessionId === agentSessionId
+            || (lead !== undefined && teamLeadMatch(team, lead))
+            || team.members.some((member) => member.id === agentSessionId && member.status !== 'removed'));
         if (participates && team !== undefined) {
             if (found !== undefined && found.id !== team.id) {
                 throw new Error(`agent session belongs to multiple active teams ("${found.id}", "${team.id}"); the target team is ambiguous`);
@@ -603,6 +610,36 @@ function isRecord(value) {
 function isOptionalString(value) {
     return value === undefined || typeof value === 'string';
 }
+/** Whether a value is a non-empty (non-blank) string. */
+function nonemptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/** Whether a value is an absent or non-blank string (a persisted id/name). */
+function isOptionalNonBlankString(value) {
+    return value === undefined || (typeof value === 'string' && value.trim() !== '');
+}
+/** Whether a value is a non-empty list of non-blank tool names. */
+function isToolNameList(value) {
+    return Array.isArray(value)
+        && value.length > 0
+        && value.every(name => typeof name === 'string' && name.trim() !== '');
+}
+/**
+ * Validate one persisted effective tool filter (#59). `deny` is part of the
+ * contract and never empty (the captain-only deny list is always included); an
+ * `allow` list, when present, is non-empty for the same reason. A wrong-typed
+ * or empty list is rejected instead of being silently accepted at the durable
+ * boundary — the same class of drift #188 fixed for team records.
+ */
+function isMemberToolFilter(value) {
+    if (!isRecord(value))
+        return false;
+    const allow = value['allow'];
+    const deny = value['deny'];
+    if (allow !== undefined && !isToolNameList(allow))
+        return false;
+    return isToolNameList(deny);
+}
 /** Whether a value is a finite timestamp/counter number. */
 function isFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value);
@@ -625,6 +662,9 @@ function isTeamMember(value) {
         && (value['executionPrompt'] === undefined || typeof value['executionPrompt'] === 'string')
         && (value['fallback'] === undefined || (isRecord(value['fallback']) && typeof value['fallback']['provider'] === 'string' && typeof value['fallback']['model'] === 'string'))
         && (value['fallbackActive'] === undefined || typeof value['fallbackActive'] === 'boolean')
+        // A member without a policy keeps the legacy shape: both fields stay absent.
+        && isOptionalNonBlankString(value['toolPolicy'])
+        && (value['toolFilter'] === undefined || isMemberToolFilter(value['toolFilter']))
         && isFiniteNumber(value['joinedAt'])
         && (value['status'] === 'idle' || value['status'] === 'working' || value['status'] === 'removed');
 }
@@ -683,7 +723,9 @@ function coerceTeamState(value, expectedId) {
         // 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.
+        // profileSeedId handling below and the tool-input normalization. The same
+        // pass drops out-of-contract numeric sentinels such as `line: -1`
+        // (issue #188), so an already-written bad record self-heals on read.
         const cleaned = normalizeBlankOptionalTaskFields(task);
         if (cleaned['profileSeedId'] !== undefined && (typeof cleaned['profileSeedId'] !== 'string' || cleaned['profileSeedId'].trim() === '')) {
             const next = { ...cleaned };
@@ -695,6 +737,230 @@ function coerceTeamState(value, expectedId) {
     const coerced = { ...value, tasks };
     return isTeamState(coerced, expectedId) ? coerced : undefined;
 }
+/**
+ * Name the first durable defect in a record `coerceTeamState` rejected. Before
+ * this, a rejected `team.json` surfaced only as
+ * `invalid AgentTeams state in team "x"` — no task, no field, no value — while
+ * every AgentTeams tool (read *and* write) failed at once, leaving an operator
+ * to bisect the file by hand (issue #188). The detail is computed only on the
+ * failure path, so the happy path keeps its existing cost.
+ * @param raw - the parsed record as read from disk, before coercion.
+ * @param expectedId - the team id the record was read for.
+ * @returns a `task "t2": findings[0].line -1 must be ...` style detail.
+ */
+export function describeTeamStateDefect(raw, expectedId) {
+    if (!isRecord(raw))
+        return 'record must be a JSON object';
+    if (!Array.isArray(raw['tasks'])) {
+        return raw['tasks'] === undefined ? 'tasks is missing' : `tasks must be an array (got ${typeof raw['tasks']})`;
+    }
+    const tasks = raw['tasks'].map((task) => isRecord(task) ? normalizeBlankOptionalTaskFields(task) : task);
+    for (const [index, task] of tasks.entries()) {
+        if (!isRecord(task))
+            return `tasks[${index}] must be an object`;
+        const label = typeof task['id'] === 'string' && task['id'] !== '' ? `task "${task['id']}"` : `tasks[${index}]`;
+        const detail = describeTaskDefect(task);
+        if (detail === undefined)
+            continue;
+        return `${label}: ${detail}`;
+    }
+    const ids = tasks.filter(isRecord).map((task) => task['id']);
+    if (ids.some((id) => typeof id !== 'string' || id === ''))
+        return 'a task id must be a non-empty string';
+    const seen = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            return `task "${id}": duplicated task id`;
+        seen.add(id);
+    }
+    if (raw['id'] !== expectedId)
+        return `id ${JSON.stringify(raw['id'])} must equal "${expectedId}"`;
+    if (typeof raw['name'] !== 'string' || raw['name'].trim() === '')
+        return 'name must be a non-empty string';
+    if (!isOptionalString(raw['description']))
+        return 'description must be a string';
+    if (raw['profile'] !== undefined && !isTeamProfileSnapshot(raw['profile']))
+        return 'profile is not a valid profile snapshot';
+    if (typeof raw['captainSessionId'] !== 'string' || raw['captainSessionId'] === '')
+        return 'captainSessionId must be a non-empty string';
+    if (!isFiniteNumber(raw['createdAt']))
+        return 'createdAt must be a finite number';
+    if (!Array.isArray(raw['members']))
+        return 'members must be an array';
+    const memberKeys = new Set();
+    const memberIds = new Set();
+    for (const [index, member] of raw['members'].entries()) {
+        if (!isTeamMember(member))
+            return `members[${index}] is not a valid member record`;
+        const key = sanitizeKey(member.name);
+        if (key === CAPTAIN_KEY)
+            return `members[${index}]: name "${member.name}" is reserved for the captain`;
+        if (memberKeys.has(key))
+            return `members[${index}]: name "${member.name}" is already used by another member`;
+        memberKeys.add(key);
+        if (member.id === '')
+            continue;
+        if (memberIds.has(member.id))
+            return `members[${index}]: id "${member.id}" is duplicated`;
+        memberIds.add(member.id);
+    }
+    if (!Number.isSafeInteger(raw['taskSeq']) || raw['taskSeq'] < 0)
+        return 'taskSeq must be an integer >= 0';
+    if (raw['phase'] !== undefined && raw['phase'] !== 'staged' && raw['phase'] !== 'running') {
+        return `phase ${JSON.stringify(raw['phase'])} must be "staged" or "running"`;
+    }
+    if (raw['planReviewState'] !== undefined
+        && raw['planReviewState'] !== 'awaiting_review'
+        && raw['planReviewState'] !== 'awaiting_feedback') {
+        return `planReviewState ${JSON.stringify(raw['planReviewState'])} is invalid`;
+    }
+    for (const key of ['approvedAt', 'haltedAt']) {
+        if (raw[key] !== undefined && !isFiniteNumber(raw[key]))
+            return `${key} must be a finite number`;
+    }
+    if (raw['halted'] !== undefined && typeof raw['halted'] !== 'boolean')
+        return 'halted must be a boolean';
+    if (raw['reviewPolicy'] !== undefined && !isReviewPolicy(raw['reviewPolicy']))
+        return 'reviewPolicy is invalid';
+    if (raw['escalated'] !== undefined && typeof raw['escalated'] !== 'boolean')
+        return 'escalated must be a boolean';
+    return 'record does not satisfy the durable team contract';
+}
+/** The first task-contract violation, or `undefined` when the task is valid. */
+function describeTaskDefect(task) {
+    if (typeof task['id'] !== 'string')
+        return 'id must be a string';
+    if (!isOptionalString(task['profileSeedId']))
+        return 'profileSeedId must be a string';
+    if (typeof task['profileSeedId'] === 'string' && task['profileSeedId'].trim() === '')
+        return 'profileSeedId must not be blank';
+    if (typeof task['subject'] !== 'string')
+        return 'subject must be a string';
+    if (!isOptionalString(task['description']))
+        return 'description must be a string';
+    const statuses = ['pending', 'claimed', 'in_progress', 'completed', 'failed', 'cancelled'];
+    if (!statuses.includes(task['status']))
+        return `status ${JSON.stringify(task['status'])} is invalid`;
+    if (!isOptionalString(task['assignee']))
+        return 'assignee must be a string';
+    if (!Array.isArray(task['dependencies']))
+        return 'dependencies must be an array';
+    if (!task['dependencies'].every((dependency) => typeof dependency === 'string'))
+        return 'dependencies must contain only strings';
+    if (!isOptionalString(task['output']))
+        return 'output must be a string';
+    if (task['attempt'] !== undefined && !(Number.isSafeInteger(task['attempt']) && task['attempt'] >= 0)) {
+        return `attempt ${JSON.stringify(task['attempt'])} must be an integer >= 0`;
+    }
+    if (!isOptionalString(task['attemptId']))
+        return 'attemptId must be a string';
+    if (!isOptionalString(task['handoffId']))
+        return 'handoffId must be a string';
+    if (!isOptionalString(task['handoffFromMemberId']))
+        return 'handoffFromMemberId must be a string';
+    if (task['reassigning'] !== undefined && typeof task['reassigning'] !== 'boolean')
+        return 'reassigning must be a boolean';
+    if (!isFiniteNumber(task['createdAt']))
+        return 'createdAt must be a finite number';
+    if (!isFiniteNumber(task['updatedAt']))
+        return 'updatedAt must be a finite number';
+    return describeQualityTaskDefect(task);
+}
+/** Mirror of `hasValidQualityTaskFields`, reporting the first failing field. */
+function describeQualityTaskDefect(task) {
+    if (task['kind'] !== undefined && !TASK_KINDS.includes(task['kind'])) {
+        return `kind ${JSON.stringify(task['kind'])} is invalid`;
+    }
+    if (task['verdict'] !== undefined && !REVIEW_VERDICTS.includes(task['verdict'])) {
+        return `verdict ${JSON.stringify(task['verdict'])} is invalid`;
+    }
+    if (task['round'] !== undefined && !(Number.isSafeInteger(task['round']) && task['round'] >= 1)) {
+        return `round ${JSON.stringify(task['round'])} must be an integer >= 1`;
+    }
+    for (const key of ['objective', 'reviewedTaskId', 'sourceTaskId']) {
+        if (task[key] !== undefined && !nonemptyString(task[key]))
+            return `${key} must be a non-empty string`;
+    }
+    if (task['reviewedAttempt'] !== undefined
+        && !(Number.isSafeInteger(task['reviewedAttempt']) && task['reviewedAttempt'] >= 0)) {
+        return `reviewedAttempt ${JSON.stringify(task['reviewedAttempt'])} must be an integer >= 0`;
+    }
+    const stringLists = ['inScope', 'outOfScope', 'acceptance', 'verify', 'deliverables', 'nonGoals', 'changedPaths', 'sourceFindingIds', 'coverageOf'];
+    for (const key of stringLists) {
+        const value = task[key];
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value))
+            return `${key} must be an array`;
+        const badIndex = value.findIndex((item) => !nonemptyString(item));
+        if (badIndex >= 0)
+            return `${key}[${badIndex}] must be a non-empty string`;
+    }
+    if (task['findings'] !== undefined) {
+        const findings = task['findings'];
+        if (!Array.isArray(findings))
+            return 'findings must be an array';
+        for (const [index, finding] of findings.entries()) {
+            const detail = describeFindingDefect(finding);
+            if (detail !== undefined)
+                return `findings[${index}].${detail}`;
+        }
+        const ids = findings.map((finding) => finding.id);
+        if (new Set(ids).size !== ids.length)
+            return 'findings ids must be unique';
+    }
+    if (task['acceptanceResults'] !== undefined) {
+        const results = task['acceptanceResults'];
+        if (!Array.isArray(results))
+            return 'acceptanceResults must be an array';
+        for (const [index, result] of results.entries()) {
+            if (!isRecord(result))
+                return `acceptanceResults[${index}] must be an object`;
+            if (!nonemptyString(result['criterion']))
+                return `acceptanceResults[${index}].criterion must be a non-empty string`;
+            if (result['status'] !== 'passed' && result['status'] !== 'failed')
+                return `acceptanceResults[${index}].status must be "passed" or "failed"`;
+            if (result['evidence'] !== undefined && typeof result['evidence'] !== 'string')
+                return `acceptanceResults[${index}].evidence must be a string`;
+        }
+    }
+    if (task['commandsRun'] !== undefined) {
+        const commands = task['commandsRun'];
+        if (!Array.isArray(commands))
+            return 'commandsRun must be an array';
+        for (const [index, command] of commands.entries()) {
+            if (!isRecord(command))
+                return `commandsRun[${index}] must be an object`;
+            if (!nonemptyString(command['command']))
+                return `commandsRun[${index}].command must be a non-empty string`;
+            if (command['status'] !== 'passed' && command['status'] !== 'failed')
+                return `commandsRun[${index}].status must be "passed" or "failed"`;
+        }
+    }
+    return undefined;
+}
+/** The first finding-contract violation, or `undefined` when the finding is valid. */
+function describeFindingDefect(finding) {
+    if (!isRecord(finding))
+        return 'must be an object';
+    if (!nonemptyString(finding['id']))
+        return 'id must be a non-empty string';
+    if (!FINDING_SEVERITIES.includes(finding['severity'])) {
+        return `severity ${JSON.stringify(finding['severity'])} is invalid`;
+    }
+    if (!nonemptyString(finding['problem']))
+        return 'problem must be a non-empty string';
+    if (!nonemptyString(finding['requiredFix']))
+        return 'requiredFix must be a non-empty string';
+    if (finding['file'] !== undefined && !nonemptyString(finding['file']))
+        return 'file must be a non-empty string';
+    if (finding['line'] !== undefined && !isValidFindingLine(finding['line'])) {
+        return `line ${JSON.stringify(finding['line'])} must be an integer >= 0 (omit it when there is no line number)`;
+    }
+    if (finding['resolved'] !== undefined && typeof finding['resolved'] !== 'boolean')
+        return 'resolved must be a boolean';
+    return undefined;
+}
 export function isTeamTask(value) {
     if (!isRecord(value))
         return false;