@pennixrv/trellis 0.7.2-beta.0 → 0.7.2-beta.3

package/dist/commands/teamwork/coordinator.js

@@ -4,10 +4,13 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { isTaskPhaseId, parseTaskWorkflowState, } from "@pennixrv/trellis-core/task";
 import { assertCoordinationTransition, readTeamworkEvents, readCoordinationState, recordCoordinationEvent, } from "@pennixrv/trellis-core/teamwork";
-import { TeammateReportReadError, cleanupSettledTeamworkArtifacts, readTeammateReport, writeTeammateQueueFact, writeTeammateClaim, writeTeammateDisposition, validateTeamworkPlan, } from "./artifact.js";
+import { TeammateReportReadError, readTeammateReport, writeTeammateQueueFact, writeTeammateClaim, writeTeammateDisposition, validateTeamworkPlan, } from "./artifact.js";
 import { assertTeammateAdapterContract, assertTeammateHostCapability, } from "./teammate-adapters.js";
 import { effectiveTeammateCapacity, resolveTeammateRuntimeConfig, } from "./teammate-config.js";
 import { readProcessIdentity } from "./process-identity.js";
+import { withLock } from "./store/lock.js";
+export class TeamworkPolicyChangedError extends Error {
+}
 export function assertTeamworkPlanCurrent(plan, taskRoot) {
     const taskFile = path.join(taskRoot, "task.json");
     const stat = fs.lstatSync(taskFile);
@@ -49,7 +52,7 @@ function terminalReceiptFromProjection(plan, projection) {
         return mismatch("does not match the frozen plan");
     if (batch.planHash !== plan.planHash)
         return mismatch("does not match the frozen plan");
-    if (batch.state !== "ALL_ACCEPTED" && batch.state !== "SETTLED_WITH_FAILURE")
+    if (!["AWAITING_REVIEW", "ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(batch.state))
         mismatch("is not terminal");
     const effectiveCapacity = batch.effectiveCapacity;
     if (typeof effectiveCapacity !== "number" ||
@@ -88,9 +91,10 @@ function terminalReceiptFromProjection(plan, projection) {
     const assignments = plan.assignments.map((assignment) => {
         const projected = assignmentById.get(assignment.assignmentId);
         if (!projected ||
-            (projected.state !== "ACCEPTED" && projected.state !== "FINAL_FAILED"))
+            !["AWAITING_REVIEW", "ACCEPTED", "FINAL_FAILED"].includes(projected.state))
             return mismatch(`assignment '${assignment.assignmentId}' is not settled`);
-        if (projected.state === "ACCEPTED") {
+        if (projected.state === "ACCEPTED" ||
+            projected.state === "AWAITING_REVIEW") {
             const acceptedAttempt = attempts.find((attempt) => attempt.attemptId === projected.attemptId &&
                 attempt.assignmentId === assignment.assignmentId);
             if (acceptedAttempt?.state !== "REPORT_SUBMITTED")
@@ -101,9 +105,11 @@ function terminalReceiptFromProjection(plan, projection) {
             status: projected.state,
         };
     });
-    const status = assignments.every((item) => item.status === "ACCEPTED")
-        ? "ALL_ACCEPTED"
-        : "SETTLED_WITH_FAILURE";
+    const status = assignments.some((item) => item.status === "AWAITING_REVIEW")
+        ? "AWAITING_REVIEW"
+        : assignments.every((item) => item.status === "ACCEPTED")
+            ? "ALL_ACCEPTED"
+            : "SETTLED_WITH_FAILURE";
     if (batch.state !== status)
         mismatch("terminal state disagrees with its assignment dispositions");
     const retryCounts = Object.fromEntries(plan.assignments.flatMap((assignment) => {
@@ -160,6 +166,7 @@ function reconciliationReceipt(plan, projection, capacity) {
 async function recordRecoveryReconciliation(input) {
     const { plan, cwd, by, existingState, projection, capacity, reason } = input;
     if (existingState !== "RECONCILIATION_REQUIRED" &&
+        existingState !== "AWAITING_REVIEW" &&
         existingState !== "ALL_ACCEPTED" &&
         existingState !== "SETTLED_WITH_FAILURE") {
         await appendTransition({
@@ -212,7 +219,8 @@ async function recoverExistingBatch(input) {
         sessionId: input.plan.sessionId,
         cwd: input.cwd,
     });
-    if (existing.state === "ALL_ACCEPTED" ||
+    if (existing.state === "AWAITING_REVIEW" ||
+        existing.state === "ALL_ACCEPTED" ||
         existing.state === "SETTLED_WITH_FAILURE") {
         let receipt;
         try {
@@ -229,10 +237,10 @@ async function recoverExistingBatch(input) {
         const receipts = events.filter((event) => event.kind === "coordination" &&
             event.batchId === input.plan.batchId &&
             event.action === "receipt_recorded" &&
+            event.payload?.status === receipt.status &&
             event.payload?.status !== "RECONCILIATION_REQUIRED");
-        if (receipts.length > 1 ||
-            (receipts.length === 1 &&
-                !isDeepStrictEqual(receipts[0]?.payload, receipt))) {
+        if (receipts.length > 0 &&
+            !isDeepStrictEqual(receipts.at(-1)?.payload, receipt)) {
             return recordRecoveryReconciliation({
                 ...input,
                 existingState: existing.state,
@@ -356,7 +364,7 @@ export async function runTeamworkCoordinator(input) {
     });
     const settled = existing.batches.find((batch) => batch.batchId === plan.batchId);
     if (settled &&
-        ["ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(settled.state)) {
+        ["AWAITING_REVIEW", "ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(settled.state)) {
         let terminal = false;
         try {
             terminalReceiptFromProjection(plan, existing);
@@ -973,7 +981,7 @@ export async function runTeamworkCoordinator(input) {
         await release(activeWork);
         final.set(assignment.assignmentId, "FINAL_FAILED");
     }
-    async function accept(activeWork) {
+    async function submit(activeWork) {
         const { assignment, context, retryCount } = activeWork;
         try {
             assertTeamworkPlanCurrent(plan, input.taskRoot);
@@ -982,26 +990,13 @@ export async function runTeamworkCoordinator(input) {
             await fail(activeWork, `task phase changed before report acceptance: ${error instanceof Error ? error.message : String(error)}`, false);
             return;
         }
-        writeTeammateDisposition({
-            taskRoot: input.taskRoot,
-            briefPath: assignment.briefPath,
-            identity: {
-                taskId: plan.taskId,
-                batchId: plan.batchId,
-                assignmentId: assignment.assignmentId,
-                attemptId: context.attemptId,
-                teammateId: context.teammateId,
-            },
-            sourceDigest: assignment.sourceDigest,
-            status: "accepted",
-        });
         await appendTransition({
             sessionId: plan.sessionId,
             by,
             batchId: plan.batchId,
             entity: "assignment",
             id: assignment.assignmentId,
-            state: "ACCEPTED",
+            state: "AWAITING_REVIEW",
             states: assignmentStates,
             assignmentId: assignment.assignmentId,
             attemptId: context.attemptId,
@@ -1009,7 +1004,7 @@ export async function runTeamworkCoordinator(input) {
             retryCount,
         });
         await release(activeWork);
-        final.set(assignment.assignmentId, "ACCEPTED");
+        final.set(assignment.assignmentId, "AWAITING_REVIEW");
     }
     async function complete(activeWork, allowRetry = true) {
         const { assignment, context, retryCount } = activeWork;
@@ -1048,28 +1043,15 @@ export async function runTeamworkCoordinator(input) {
             });
         }
         catch (error) {
-            if (error instanceof TeammateReportReadError && error.kind !== "missing")
-                throw error;
-            await fail(activeWork, error instanceof Error ? error.message : String(error), allowRetry);
+            await fail(activeWork, error instanceof Error ? error.message : String(error), error instanceof TeammateReportReadError && error.kind === "missing"
+                ? allowRetry
+                : false);
             return;
         }
         if (context.launch.reportVersion === 2 && report.schemaVersion !== 2) {
             await fail(activeWork, "report schema_version must match the frozen result contract (2)", allowRetry);
             return;
         }
-        if (report.status === "blocked") {
-            await fail(activeWork, `teammate reported blocked: ${report.evidence[0]?.summary ?? "blocker evidence missing"}`, false);
-            return;
-        }
-        if (report.status !== "complete") {
-            await fail(activeWork, `teammate reported ${report.status}`, allowRetry);
-            return;
-        }
-        if (input.runtime.validateReport &&
-            !(await input.runtime.validateReport(context, report))) {
-            await fail(activeWork, "report rejected by acceptance contract", allowRetry);
-            return;
-        }
         try {
             assertTeamworkPlanCurrent(plan, input.taskRoot);
         }
@@ -1135,7 +1117,7 @@ export async function runTeamworkCoordinator(input) {
             teammateId: context.teammateId,
             retryCount,
         });
-        await accept(activeWork);
+        await submit(activeWork);
     }
     async function settle() {
         await appendTransition({
@@ -1147,15 +1129,8 @@ export async function runTeamworkCoordinator(input) {
             state: "SETTLING",
             states: batchStates,
         });
-        const cleanupFailures = cleanupSettledTeamworkArtifacts({
-            taskRoot: input.taskRoot,
-            assignments: plan.assignments,
-        });
-        if (cleanupFailures.length > 0) {
-            return reconcile(`Teamwork batch cleanup failed: ${cleanupFailures.join("; ")}`);
-        }
-        const accepted = plan.assignments.every((assignment) => final.get(assignment.assignmentId) === "ACCEPTED");
-        const status = accepted ? "ALL_ACCEPTED" : "SETTLED_WITH_FAILURE";
+        const pendingReview = plan.assignments.some((assignment) => final.get(assignment.assignmentId) === "AWAITING_REVIEW");
+        const status = pendingReview ? "AWAITING_REVIEW" : "SETTLED_WITH_FAILURE";
         await appendTransition({
             sessionId: plan.sessionId,
             by,
@@ -1165,29 +1140,7 @@ export async function runTeamworkCoordinator(input) {
             state: status,
             states: batchStates,
         });
-        const receipt = {
-            schemaVersion: 1,
-            batchId: plan.batchId,
-            status,
-            assignments: plan.assignments.map((assignment) => ({
-                assignmentId: assignment.assignmentId,
-                status: final.get(assignment.assignmentId) ?? "FINAL_FAILED",
-            })),
-            capacity,
-            retryCounts,
-            evaluationGroups: [
-                ...new Set(plan.assignments
-                    .map((assignment) => assignment.evaluationGroup?.id)
-                    .filter((id) => id !== undefined)),
-            ].map((id) => ({
-                id,
-                status: plan.assignments
-                    .filter((assignment) => assignment.evaluationGroup?.id === id)
-                    .every((assignment) => final.get(assignment.assignmentId) === "ACCEPTED")
-                    ? "COMPLETE"
-                    : "INCOMPLETE",
-            })),
-        };
+        const receipt = terminalReceiptFromProjection(plan, await readCoordinationState({ sessionId: plan.sessionId, cwd }));
         await appendAction({
             sessionId: plan.sessionId,
             by,
@@ -1230,8 +1183,26 @@ export async function runTeamworkCoordinator(input) {
             catch (error) {
                 if (!assignmentStates.has(assignment.assignmentId) ||
                     assignmentStates.get(assignment.assignmentId) === "QUEUED") {
-                    await failPending(`launch preflight failed before dispatch: ${error instanceof Error ? error.message : String(error)}`);
-                    return;
+                    const reason = `launch preflight failed before dispatch: ${error instanceof Error ? error.message : String(error)}`;
+                    if (error instanceof TeamworkPolicyChangedError) {
+                        await failPending(reason);
+                        return;
+                    }
+                    pending.shift();
+                    await appendTransition({
+                        sessionId: plan.sessionId,
+                        by,
+                        batchId: plan.batchId,
+                        entity: "assignment",
+                        id: assignment.assignmentId,
+                        assignmentId: assignment.assignmentId,
+                        state: "FINAL_FAILED",
+                        states: assignmentStates,
+                        retryCount,
+                        payload: { reason, dispatched: false },
+                    });
+                    final.set(assignment.assignmentId, "FINAL_FAILED");
+                    continue;
                 }
                 throw error;
             }
@@ -1451,9 +1422,10 @@ export async function assertTeamworkReceiptDurable(plan, receipt, cwd) {
     const receipts = events.filter((event) => event.kind === "coordination" &&
         event.batchId === plan.batchId &&
         event.action === "receipt_recorded" &&
+        event.payload?.status === receipt.status &&
         event.payload?.status !== "RECONCILIATION_REQUIRED");
-    if (receipts.length !== 1 ||
-        !isDeepStrictEqual(receipts[0]?.payload, expected))
+    if (receipts.length === 0 ||
+        !isDeepStrictEqual(receipts.at(-1)?.payload, expected))
         throw new Error(`batch '${plan.batchId}' has no matching durable receipt event`);
 }
 /** Retire uncertain work only from associated terminal or process-birth evidence. */
@@ -1470,7 +1442,7 @@ export async function reconcileTeamworkBatch(input) {
     const resolving = events.some((event) => event.kind === "coordination" &&
         event.batchId === plan.batchId &&
         event.action === "reconciliation_resolved");
-    if (["ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(batch.state)) {
+    if (["AWAITING_REVIEW", "ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(batch.state)) {
         const receipt = terminalReceiptFromProjection(plan, projection);
         if (input.execute) {
             const recovered = await recoverExistingBatch({
@@ -1507,23 +1479,34 @@ export async function reconcileTeamworkBatch(input) {
             ? started.payload?.processIdentity
             : undefined;
         let exited = false;
+        let identityUnknown = true;
         if (typeof pid === "number" &&
             Number.isSafeInteger(pid) &&
             pid > 0 &&
             typeof birth === "string" &&
             birth.startsWith(`${pid}:`)) {
             const current = readProcessIdentity(pid);
-            if (current)
+            if (current) {
                 exited = current !== birth;
+                identityUnknown = false;
+            }
             else {
                 try {
                     process.kill(pid, 0);
                 }
                 catch (error) {
-                    exited = error.code === "ESRCH";
+                    const code = error.code;
+                    exited = code === "ESRCH";
+                    identityUnknown = code !== "ESRCH";
                 }
             }
         }
+        if (!exited &&
+            identityUnknown &&
+            input.execute &&
+            input.confirmUnknownProcessExit &&
+            input.reason?.trim())
+            exited = true;
         if (!exited)
             blockers.push(`Attempt ${attempt.attemptId} lacks confirmed process exit; preserve its lease`);
     }
@@ -1629,7 +1612,13 @@ export async function reconcileTeamworkBatch(input) {
         entity: "batch",
         action: "reconciliation_resolved",
         reason: input.reason,
-        idempotencyKey: `${plan.batchId}:reconciled`,
+        ...(input.confirmUnknownProcessExit
+            ? { payload: { confirmedUnknownProcessExit: true } }
+            : {}),
+        idempotencyKey: `${plan.batchId}:reconciled:${crypto
+            .createHash("sha256")
+            .update(input.reason ?? "")
+            .digest("hex")}`,
     });
     if (batch.state !== "SETTLING")
         await appendTransition({
@@ -1672,10 +1661,144 @@ export async function reconcileTeamworkBatch(input) {
 export async function readSettledTeamworkReceipt(plan, cwd) {
     const state = await readCoordinationState({ sessionId: plan.sessionId, cwd });
     const batch = state.batches.find((entry) => entry.batchId === plan.batchId);
-    if (!batch || !["ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(batch.state))
+    if (!batch ||
+        !["AWAITING_REVIEW", "ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(batch.state))
         return undefined;
     const receipt = terminalReceiptFromProjection(plan, state);
     await assertTeamworkReceiptDurable(plan, receipt, cwd);
     return receipt;
 }
+/** Main-agent review starts only after the CLI has drained the entire batch. */
+export async function reviewTeamworkReport(input) {
+    const { plan, taskRoot, cwd } = input;
+    if (!input.reason.trim())
+        throw new Error("Review requires an explicit reason");
+    const assignment = plan.assignments.find((item) => item.assignmentId === input.assignmentId);
+    if (!assignment)
+        throw new Error("Review assignment is not in the frozen plan");
+    return withLock(path.join(taskRoot, "teammates", `${plan.batchId}.review.lock`), async () => {
+        assertTeamworkPlanCurrent(plan, taskRoot);
+        const projection = await readCoordinationState({
+            sessionId: plan.sessionId,
+            cwd,
+        });
+        const batch = projection.batches.find((item) => item.batchId === plan.batchId);
+        if (!batch ||
+            !["AWAITING_REVIEW", "ALL_ACCEPTED", "SETTLED_WITH_FAILURE"].includes(batch.state))
+            throw new Error("Review requires the entire batch to be collected first");
+        terminalReceiptFromProjection(plan, projection);
+        const work = projection.assignments.find((item) => item.batchId === plan.batchId &&
+            item.assignmentId === assignment.assignmentId);
+        if (!work?.attemptId || !work.teammateId)
+            throw new Error("Review has no matching report attempt");
+        readTeammateReport({
+            taskRoot,
+            briefPath: assignment.briefPath,
+            attemptId: work.attemptId,
+            identity: {
+                taskId: plan.taskId,
+                batchId: plan.batchId,
+                assignmentId: assignment.assignmentId,
+                teammateId: work.teammateId,
+                planHash: plan.planHash,
+                phaseId: plan.phaseId,
+                taskRouteRevision: plan.taskRouteRevision,
+                inputRevision: plan.inputRevision,
+            },
+            sourceDigest: assignment.sourceDigest,
+        });
+        const reportFile = path.join(taskRoot, path.dirname(assignment.briefPath), "attempts", work.attemptId, "report.json");
+        const reportSha256 = crypto
+            .createHash("sha256")
+            .update(fs.readFileSync(reportFile))
+            .digest("hex");
+        if (reportSha256 !== input.reportSha256)
+            throw new Error("Review report digest does not match the inspected report");
+        const state = input.decision === "accepted" ? "ACCEPTED" : "FINAL_FAILED";
+        if (work.state !== "AWAITING_REVIEW" && work.state !== state)
+            throw new Error("Report already has a different final disposition");
+        const by = input.by ?? "main";
+        writeTeammateDisposition({
+            taskRoot,
+            briefPath: assignment.briefPath,
+            identity: {
+                taskId: plan.taskId,
+                batchId: plan.batchId,
+                assignmentId: assignment.assignmentId,
+                attemptId: work.attemptId,
+                teammateId: work.teammateId,
+            },
+            sourceDigest: assignment.sourceDigest,
+            status: input.decision,
+            reason: input.reason,
+            review: {
+                plan_hash: plan.planHash,
+                phase_id: plan.phaseId,
+                task_route_revision: plan.taskRouteRevision,
+                input_revision: plan.inputRevision,
+                report_sha256: reportSha256,
+                acceptance: assignment.acceptance,
+                by,
+            },
+        });
+        if (work.state === "AWAITING_REVIEW")
+            await appendTransition({
+                sessionId: plan.sessionId,
+                cwd,
+                by,
+                batchId: plan.batchId,
+                entity: "assignment",
+                id: assignment.assignmentId,
+                assignmentId: assignment.assignmentId,
+                attemptId: work.attemptId,
+                teammateId: work.teammateId,
+                retryCount: work.retryCount,
+                state,
+                states: new Map([[assignment.assignmentId, work.state]]),
+                payload: {
+                    reason: input.reason,
+                    reportSha256,
+                    planHash: plan.planHash,
+                    acceptance: assignment.acceptance,
+                },
+            });
+        let updated = await readCoordinationState({
+            sessionId: plan.sessionId,
+            cwd,
+        });
+        const remaining = updated.assignments.filter((item) => item.batchId === plan.batchId);
+        if (batch.state === "AWAITING_REVIEW" &&
+            !remaining.some((item) => item.state === "AWAITING_REVIEW")) {
+            await appendTransition({
+                sessionId: plan.sessionId,
+                cwd,
+                by,
+                batchId: plan.batchId,
+                entity: "batch",
+                id: plan.batchId,
+                state: remaining.every((item) => item.state === "ACCEPTED")
+                    ? "ALL_ACCEPTED"
+                    : "SETTLED_WITH_FAILURE",
+                states: new Map([[plan.batchId, batch.state]]),
+            });
+            updated = await readCoordinationState({
+                sessionId: plan.sessionId,
+                cwd,
+            });
+        }
+        const receipt = terminalReceiptFromProjection(plan, updated);
+        await appendAction({
+            sessionId: plan.sessionId,
+            cwd,
+            by,
+            batchId: plan.batchId,
+            entity: "batch",
+            action: "receipt_recorded",
+            id: `${plan.batchId}:review:${crypto.createHash("sha256").update(JSON.stringify(receipt)).digest("hex")}`,
+            payload: { ...receipt },
+        });
+        await assertTeamworkReceiptDurable(plan, receipt, cwd);
+        return receipt;
+    });
+}
 //# sourceMappingURL=coordinator.js.map