owlrunkit 0.17.1 → 0.18.0

package/scripts/runkit-contract/team-project.mjs

@@ -43,6 +43,7 @@ const WORK_ITEM_STATES = new Set([
   "completed",
   "failed",
 ]);
+const VERIFICATION_DISPOSITIONS = new Set(["verified", "no_longer_required"]);
 const EVENT_KEYS = Object.freeze({
   agent_assigned: [
     "schemaVersion", "eventId", "type", "occurredAt", "assignmentId",
@@ -71,6 +72,14 @@ const EVENT_KEYS = Object.freeze({
     "schemaVersion", "eventId", "type", "occurredAt", "gateId", "summary",
     "evidenceRefs",
   ],
+  verification_deferred: [
+    "schemaVersion", "eventId", "type", "occurredAt", "verificationId",
+    "workItemId", "ownerAgentId", "checkIds", "reason", "dueGateId",
+  ],
+  verification_closed: [
+    "schemaVersion", "eventId", "type", "occurredAt", "verificationId",
+    "disposition", "summary", "evidenceRefs", "decisionIds",
+  ],
   data_candidate_recorded: [
     "schemaVersion", "eventId", "type", "occurredAt", "candidateId",
     "sourceRef", "rights", "inputRef", "outputRef", "decisionRef",
@@ -109,7 +118,7 @@ function nullableString(value, label) {
 function stringArray(value, label, { allowEmpty = true } = {}) {
   if (!Array.isArray(value)
     || (!allowEmpty && value.length === 0)
-    || value.some(item => typeof item !== "string" || item.length === 0)
+    || value.some(item => typeof item !== "string" || item.trim().length === 0)
     || new Set(value).size !== value.length) {
     throw new Error(`${label} must be a unique string array${allowEmpty ? "" : " with at least one entry"}.`);
   }
@@ -187,6 +196,9 @@ function validateDefinition(value) {
   ]) {
     if (!Array.isArray(value[key])) throw new Error(`${label} list must be an array.`);
   }
+  if (value.workItems.length === 0) {
+    throw new Error("Team project definition requires at least one WorkItem.");
+  }
   const milestoneIds = uniqueIds(value.milestones, "Milestone");
   const workstreamIds = uniqueIds(value.workstreams, "Workstream");
   const workItemIds = uniqueIds(value.workItems, "Work item");
@@ -277,6 +289,15 @@ function validateDefinition(value) {
   };
 }
 
+export function normalizeTeamProjectDefinitionV1(definition) {
+  return validateDefinition(definition);
+}
+
+export function emptyTeamProjectTruthHashV1(definition) {
+  const normalized = validateDefinition(definition);
+  return sha256(canonical({ definition: normalized, events: [] }));
+}
+
 function readRegularJson(filePath, label) {
   const stat = lstatSync(filePath);
   if (stat.isSymbolicLink() || !stat.isFile() || realpathSync(filePath) !== filePath) {
@@ -291,8 +312,16 @@ function loadProject(workspaceRoot) {
   if (!existsSync(definitionPath)) throw new Error("Team project is not initialized.");
   const definition = validateDefinition(readRegularJson(definitionPath, "Team project definition"));
   const eventsRoot = path.join(rootPath, "events");
-  const events = existsSync(eventsRoot)
-    ? readdirSync(eventsRoot, { withFileTypes: true })
+  if (!existsSync(eventsRoot)) {
+    throw new Error("Team project event directory must be a regular directory without symlinks.");
+  }
+  const eventsStat = lstatSync(eventsRoot);
+  if (eventsStat.isSymbolicLink()
+    || !eventsStat.isDirectory()
+    || realpathSync(eventsRoot) !== eventsRoot) {
+    throw new Error("Team project event directory must be a regular directory without symlinks.");
+  }
+  const events = readdirSync(eventsRoot, { withFileTypes: true })
       .filter(entry => entry.name.endsWith(".json"))
       .map((entry) => {
         if (entry.isSymbolicLink() || !entry.isFile()) {
@@ -308,8 +337,7 @@ function loadProject(workspaceRoot) {
       .sort((left, right) => (
         left.event.occurredAt.localeCompare(right.event.occurredAt)
         || left.event.eventId.localeCompare(right.event.eventId)
-      ))
-    : [];
+      ));
   return { root, projectRoot: rootPath, definitionPath, definition, events };
 }
 
@@ -335,6 +363,34 @@ function eventRef(event) {
   return `project/events/${event.eventId}.json`;
 }
 
+function compareEventFacts(left, right) {
+  return left.occurredAt.localeCompare(right.occurredAt)
+    || left.eventId.localeCompare(right.eventId);
+}
+
+function latestEventFact(left, right) {
+  if (!left) return right;
+  if (!right) return left;
+  return compareEventFacts(left, right) >= 0 ? left : right;
+}
+
+function pendingHandoffProjection(handoff) {
+  return handoff
+    ? {
+        eventId: handoff.eventId,
+        truthRef: handoff.ref,
+        assignmentId: handoff.assignmentId,
+        workItemId: handoff.workItemId,
+        fromAgentId: handoff.fromAgentId,
+        toAgentId: handoff.toAgentId,
+        summary: handoff.summary,
+        evidenceRefs: [...handoff.evidenceRefs],
+        nextAction: handoff.nextAction,
+        occurredAt: handoff.occurredAt,
+      }
+    : null;
+}
+
 function validateTimestamp(value) {
   if (typeof value !== "string"
     || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)
@@ -360,8 +416,15 @@ function validateEventShape(value, definition) {
     safeIdentifier(id, "workItemId");
     if (!workItemIds.has(id)) throw new Error(`Team project event references unknown work item ${id}.`);
   };
-  if (["agent_assigned", "checkpoint_recorded", "handoff_recorded"].includes(value.type)) {
+  if ([
+    "agent_assigned",
+    "checkpoint_recorded",
+    "handoff_recorded",
+    "verification_deferred",
+  ].includes(value.type)) {
     assertWorkItem(value.workItemId);
+  }
+  if (["agent_assigned", "checkpoint_recorded", "handoff_recorded"].includes(value.type)) {
     safeIdentifier(value.assignmentId, "assignmentId");
   }
   if (value.type === "agent_assigned") {
@@ -397,6 +460,9 @@ function validateEventShape(value, definition) {
   } else if (value.type === "handoff_recorded") {
     safeIdentifier(value.fromAgentId, "fromAgentId");
     safeIdentifier(value.toAgentId, "toAgentId");
+    if (value.fromAgentId === value.toAgentId) {
+      throw new Error("fromAgentId and toAgentId must differ.");
+    }
     nonEmptyString(value.summary, "Handoff summary");
     stringArray(value.evidenceRefs, "Handoff evidenceRefs", { allowEmpty: false });
     nonEmptyString(value.nextAction, "Handoff nextAction");
@@ -418,6 +484,44 @@ function validateEventShape(value, definition) {
     if (!gateIds.has(value.gateId)) throw new Error(`Unknown integration gate ${value.gateId}.`);
     nonEmptyString(value.summary, "Integration gate summary");
     stringArray(value.evidenceRefs, "Integration gate evidenceRefs", { allowEmpty: false });
+  } else if (value.type === "verification_deferred") {
+    safeIdentifier(value.verificationId, "verificationId");
+    safeIdentifier(value.ownerAgentId, "ownerAgentId");
+    const checkIds = stringArray(
+      value.checkIds,
+      "Deferred verification checkIds",
+      { allowEmpty: false },
+    );
+    for (const checkId of checkIds) safeIdentifier(checkId, "checkId");
+    nonEmptyString(value.reason, "Deferred verification reason");
+    safeIdentifier(value.dueGateId, "dueGateId");
+    if (!gateIds.has(value.dueGateId)) {
+      throw new Error(`Unknown deferred verification gate ${value.dueGateId}.`);
+    }
+  } else if (value.type === "verification_closed") {
+    safeIdentifier(value.verificationId, "verificationId");
+    if (!VERIFICATION_DISPOSITIONS.has(value.disposition)) {
+      throw new Error("Deferred verification disposition is invalid.");
+    }
+    nonEmptyString(value.summary, "Deferred verification close summary");
+    const evidenceRefs = stringArray(
+      value.evidenceRefs,
+      "Deferred verification close evidenceRefs",
+    );
+    const decisionIds = stringArray(
+      value.decisionIds,
+      "Deferred verification close decisionIds",
+    );
+    for (const decisionId of decisionIds) safeIdentifier(decisionId, "decisionId");
+    if (value.disposition === "verified" && evidenceRefs.length === 0) {
+      throw new Error("Verified deferred verification requires evidence.");
+    }
+    if (value.disposition === "verified" && decisionIds.length > 0) {
+      throw new Error("Verified deferred verification must close with evidence, not decision IDs.");
+    }
+    if (value.disposition === "no_longer_required" && decisionIds.length === 0) {
+      throw new Error("No-longer-required deferred verification requires a resolved decision.");
+    }
   } else if (value.type === "data_candidate_recorded") {
     safeIdentifier(value.candidateId, "candidateId");
     nonEmptyString(value.sourceRef, "Data candidate sourceRef");
@@ -439,6 +543,7 @@ function projectEvents(definition, records) {
   const handoffs = new Map();
   const decisions = new Map();
   const gatePasses = new Map();
+  const verifications = new Map();
   const dataCandidates = [];
   const seenAssignments = new Set();
   const seenDecisions = new Set();
@@ -470,6 +575,34 @@ function projectEvents(definition, records) {
       decision.resolved = { ...event, ref };
     } else if (event.type === "integration_gate_passed") {
       gatePasses.set(event.gateId, { ...event, ref });
+    } else if (event.type === "verification_deferred") {
+      if (verifications.has(event.verificationId)) {
+        throw new Error(`Duplicate deferred verification ${event.verificationId}.`);
+      }
+      if (gatePasses.has(event.dueGateId)) {
+        throw new Error(
+          `Deferred verification cannot target integration gate ${event.dueGateId}; gate already passed.`,
+        );
+      }
+      verifications.set(event.verificationId, {
+        deferred: { ...event, ref },
+        closed: null,
+      });
+    } else if (event.type === "verification_closed") {
+      const verification = verifications.get(event.verificationId);
+      if (!verification || verification.closed) {
+        throw new Error(`Deferred verification ${event.verificationId} is not open.`);
+      }
+      if (event.disposition === "no_longer_required") {
+        for (const decisionId of event.decisionIds) {
+          if (!decisions.get(decisionId)?.resolved) {
+            throw new Error(
+              `No-longer-required deferred verification requires resolved decision ${decisionId}.`,
+            );
+          }
+        }
+      }
+      verification.closed = { ...event, ref };
     } else if (event.type === "data_candidate_recorded") {
       if (dataCandidates.some(row => row.candidateId === event.candidateId)) {
         throw new Error(`Duplicate data candidate ${event.candidateId}.`);
@@ -484,6 +617,7 @@ function projectEvents(definition, records) {
     handoffs,
     decisions,
     gatePasses,
+    verifications,
     dataCandidates,
   };
 }
@@ -539,25 +673,293 @@ function executionTruthFor(workspaceRoot, assignment) {
   };
 }
 
+function compareIdentifiers(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort(compareIdentifiers);
+}
+
+function sortWorkItemIds(ids, priority) {
+  return [...new Set(ids)].sort((left, right) => (
+    (priority.get(left) ?? Number.MAX_SAFE_INTEGER)
+      - (priority.get(right) ?? Number.MAX_SAFE_INTEGER)
+    || compareIdentifiers(left, right)
+  ));
+}
+
+function dominantGapCandidateOrder(status) {
+  const byId = new Map(status.workItems.map(row => [row.workItemId, row]));
+  const failed = status.workItems
+    .filter(row => row.status === "failed")
+    .map(row => row.workItemId)
+    .sort(compareIdentifiers);
+  const failedIds = new Set(failed);
+  const critical = status.criticalWorkItems
+    .filter(workItemId => (
+      byId.get(workItemId)?.status !== "completed"
+      && !failedIds.has(workItemId)
+    ));
+  const criticalIds = new Set([...failed, ...critical]);
+  const remaining = status.workItems
+    .filter(row => row.status !== "completed" && !criticalIds.has(row.workItemId))
+    .map(row => row.workItemId)
+    .sort(compareIdentifiers);
+  return [...failed, ...critical, ...remaining];
+}
+
+function unresolvedRootWorkItemIds(workItemId, byId, priority, visiting = new Set()) {
+  const row = byId.get(workItemId);
+  if (!row || visiting.has(workItemId)) return [workItemId];
+  const nextVisiting = new Set(visiting).add(workItemId);
+  const unresolved = row.unresolvedDependencies.filter(id => byId.has(id));
+  if (unresolved.length === 0) return [workItemId];
+  return sortWorkItemIds(
+    unresolved.flatMap(id => unresolvedRootWorkItemIds(id, byId, priority, nextVisiting)),
+    priority,
+  );
+}
+
+function openDecisionsForWorkItem(row, openDecisions) {
+  const decisionRefs = new Set([
+    ...row.decisionRefs,
+    ...row.blockers
+      .filter(ref => ref.startsWith("decision:"))
+      .map(ref => ref.slice("decision:".length)),
+  ]);
+  return openDecisions
+    .filter(decision => (
+      decisionRefs.has(decision.decisionId)
+      || decision.blockingWorkItemIds.includes(row.workItemId)
+    ))
+    .sort((left, right) => compareIdentifiers(left.decisionId, right.decisionId));
+}
+
+function workItemGapReason(row) {
+  if (row.status === "failed") {
+    return row.summary
+      ?? (row.executionTruth?.issues?.length > 0 ? "Execution truth is invalid." : null)
+      ?? "Work item failed.";
+  }
+  return row.blockers.length > 0 ? row.summary ?? "Work item is blocked." : null;
+}
+
+function nextActionForGap(gap, status) {
+  if (gap.kind === "decision") {
+    return { action: `Resolve ${gap.id}`, actorId: gap.agentId };
+  }
+  if (gap.kind === "deferred_verification") {
+    return { action: `Run deferred verification ${gap.id}`, actorId: gap.agentId };
+  }
+  if (gap.kind === "integration_gate") {
+    return { action: `Review integration gate ${gap.id}`, actorId: null };
+  }
+  if (gap.kind === "none") return { action: null, actorId: null };
+
+  const workItem = status.workItems.find(row => row.workItemId === gap.workItemId);
+  if (workItem?.pendingHandoff) {
+    return {
+      action: `Accept handoff ${gap.workItemId}`,
+      actorId: workItem.pendingHandoff.toAgentId,
+    };
+  }
+  if (!workItem?.agentId) return { action: `Assign ${gap.workItemId}`, actorId: null };
+  if (workItem.nextAction) {
+    return { action: workItem.nextAction, actorId: workItem.agentId };
+  }
+  if (workItem.status === "failed") {
+    return { action: `Rework ${gap.workItemId}`, actorId: workItem.agentId };
+  }
+  if (workItem.status === "verifying") {
+    return { action: `Verify ${gap.workItemId}`, actorId: workItem.agentId };
+  }
+  if (workItem.status === "ready_to_integrate") {
+    return { action: `Integrate ${gap.workItemId}`, actorId: workItem.agentId };
+  }
+  return { action: `Continue ${gap.workItemId}.`, actorId: workItem.agentId };
+}
+
+function singleLine(value) {
+  return String(value).replace(/\s+/gu, " ").trim();
+}
+
+function gapLabel(gap) {
+  if (gap.kind === "none") return "none";
+  if (gap.kind === "decision") return `decision ${gap.id} (${gap.title})`;
+  if (gap.kind === "deferred_verification") {
+    return `deferred verification ${gap.id}`;
+  }
+  if (gap.kind === "failed_work") return `failed work ${gap.workItemId} (${gap.title})`;
+  if (gap.kind === "work_item") return `work item ${gap.workItemId} (${gap.title})`;
+  return `integration gate ${gap.id} (${gap.title})`;
+}
+
+function buildProjectHeadline(gap, next) {
+  const owner = gap.agentId ?? next.actorId ?? "unassigned";
+  const blocker = gap.reason ?? "none";
+  const action = next.action ?? "none";
+  const normalizedAction = singleLine(action);
+  const actionTerminator = /[.!?。！？]$/u.test(normalizedAction) ? "" : ".";
+  return `Dominant gap: ${singleLine(gapLabel(gap))}; owner: ${singleLine(owner)}; `
+    + `blocker: ${singleLine(blocker)}; next: ${normalizedAction}${actionTerminator}`;
+}
+
+function deriveProjectDriverSummary(status) {
+  const byId = new Map(status.workItems.map(row => [row.workItemId, row]));
+  const priority = new Map(
+    dominantGapCandidateOrder(status).map((workItemId, index) => [workItemId, index]),
+  );
+  let gap = null;
+
+  for (const candidateId of dominantGapCandidateOrder(status)) {
+    const rootId = unresolvedRootWorkItemIds(candidateId, byId, priority)[0];
+    const root = byId.get(rootId);
+    if (!root) continue;
+    if (root.pendingHandoff) {
+      gap = {
+        kind: "work_item",
+        id: root.workItemId,
+        title: root.title,
+        workItemId: root.workItemId,
+        agentId: root.pendingHandoff.toAgentId,
+        reason: root.pendingHandoff.summary,
+        truthRefs: uniqueSorted(root.truthRefs),
+      };
+    } else if (openDecisionsForWorkItem(root, status.openDecisions).length > 0) {
+      const decisions = openDecisionsForWorkItem(root, status.openDecisions);
+      const decision = decisions[0];
+      gap = {
+        kind: "decision",
+        id: decision.decisionId,
+        title: decision.title,
+        workItemId: root.workItemId,
+        agentId: decision.ownerAgentId,
+        reason: decision.question,
+        truthRefs: uniqueSorted([...decision.truthRefs, ...root.truthRefs]),
+      };
+    } else {
+      gap = {
+        kind: root.status === "failed" ? "failed_work" : "work_item",
+        id: root.workItemId,
+        title: root.title,
+        workItemId: root.workItemId,
+        agentId: root.agentId,
+        reason: workItemGapReason(root),
+        truthRefs: uniqueSorted(root.truthRefs),
+      };
+    }
+    break;
+  }
+
+  if (!gap && status.workItems.every(row => row.status === "completed")) {
+    const firstUnpassedGate = status.integrationGates
+      .find(gate => gate.status !== "passed") ?? null;
+    const gateDecisions = firstUnpassedGate
+      ? status.openDecisions
+        .filter(decision => firstUnpassedGate.unresolvedDecisionIds.includes(decision.decisionId))
+        .sort((left, right) => compareIdentifiers(left.decisionId, right.decisionId))
+      : [];
+    if (gateDecisions.length > 0) {
+      const decision = gateDecisions[0];
+      gap = {
+        kind: "decision",
+        id: decision.decisionId,
+        title: decision.title,
+        workItemId: null,
+        agentId: decision.ownerAgentId,
+        reason: decision.question,
+        truthRefs: uniqueSorted([...decision.truthRefs, ...firstUnpassedGate.truthRefs]),
+      };
+    } else if (firstUnpassedGate?.unresolvedVerificationIds.length > 0) {
+      const verification = status.deferredVerifications.find(row => (
+        row.verificationId === firstUnpassedGate.unresolvedVerificationIds[0]
+      ));
+      gap = {
+        kind: "deferred_verification",
+        id: verification.verificationId,
+        title: `Deferred verification ${verification.verificationId}`,
+        workItemId: verification.workItemId,
+        agentId: verification.ownerAgentId,
+        reason: verification.reason,
+        truthRefs: uniqueSorted([
+          ...verification.truthRefs,
+          ...firstUnpassedGate.truthRefs,
+        ]),
+      };
+    } else if (firstUnpassedGate) {
+      gap = {
+        kind: "integration_gate",
+        id: firstUnpassedGate.gateId,
+        title: firstUnpassedGate.title,
+        workItemId: null,
+        agentId: null,
+        reason: "Integration gate has not passed.",
+        truthRefs: uniqueSorted(firstUnpassedGate.truthRefs),
+      };
+    } else if (status.openDecisions.length > 0) {
+      const decision = status.openDecisions[0];
+      gap = {
+        kind: "decision",
+        id: decision.decisionId,
+        title: decision.title,
+        workItemId: null,
+        agentId: decision.ownerAgentId,
+        reason: decision.question,
+        truthRefs: uniqueSorted(decision.truthRefs),
+      };
+    }
+  }
+
+  if (!gap) {
+    gap = {
+      kind: "none",
+      id: null,
+      title: null,
+      workItemId: null,
+      agentId: null,
+      reason: null,
+      truthRefs: uniqueSorted([
+        "project/definition.json",
+        ...status.integrationGates.flatMap(gate => gate.truthRefs),
+      ]),
+    };
+  }
+
+  const next = nextActionForGap(gap, status);
+  return {
+    headline: buildProjectHeadline(gap, next),
+    dominantGap: gap,
+    nextAction: next.action,
+    nextActorId: next.actorId,
+  };
+}
+
 function projectStatus(definition, records, workspaceRoot = null) {
   const state = projectEvents(definition, records);
   const completed = new Set();
   for (const [id, checkpoint] of state.checkpoints) {
     if (checkpoint.state === "completed") completed.add(id);
   }
-  const workItems = definition.workItems.map((item) => {
+  let workItems = definition.workItems.map((item) => {
     const assignment = state.assignments.get(item.id) ?? null;
     const checkpoint = state.checkpoints.get(item.id) ?? null;
     const handoff = state.handoffs.get(item.id) ?? null;
+    const latestFact = latestEventFact(checkpoint, handoff);
+    const activeHandoff = handoff
+      && handoff.assignmentId === assignment?.assignmentId
+      && handoff.fromAgentId === assignment?.agentId
+      ? handoff
+      : null;
+    const pendingHandoff = activeHandoff && latestFact?.eventId === activeHandoff.eventId
+      ? pendingHandoffProjection(activeHandoff)
+      : null;
     const executionTruth = executionTruthFor(workspaceRoot, assignment);
     const unresolvedDependencies = item.dependencies.filter(id => !completed.has(id));
     let status = "planned";
     if (assignment) status = unresolvedDependencies.length > 0 ? "waiting_dependency" : "active";
-    if (handoff && handoff.assignmentId === assignment?.assignmentId) status = "planned";
-    if (checkpoint) status = checkpoint.state;
-    if (status === "active" && checkpoint?.decisionRefs.some((id) => (
-      state.decisions.get(id)?.resolved === null
-    ))) status = "waiting_decision";
+    if (pendingHandoff) status = "planned";
+    if (latestFact?.type === "checkpoint_recorded") status = checkpoint.state;
     if (executionTruth && (executionTruth.status !== "bound"
       || (executionTruth.lifecycle === "closed"
         && executionTruth.closeoutDecision !== "accepted"))) {
@@ -598,18 +1000,20 @@ function projectStatus(definition, records, workspaceRoot = null) {
       executionTruth,
       dependencies: [...item.dependencies],
       unresolvedDependencies,
-      blockers: checkpoint?.blockerRefs ?? unresolvedDependencies.map(id => `work-item:${id}`),
-      decisionRefs: checkpoint?.decisionRefs ?? [],
+      blockers: latestFact?.type === "checkpoint_recorded"
+        ? checkpoint.blockerRefs
+        : unresolvedDependencies.map(id => `work-item:${id}`),
+      decisionRefs: latestFact?.type === "checkpoint_recorded" ? checkpoint.decisionRefs : [],
       progress: measured,
-      summary: checkpoint?.summary ?? handoff?.summary ?? null,
-      nextAction: checkpoint ? checkpoint.nextAction : (handoff?.nextAction ?? null),
+      summary: latestFact?.summary ?? null,
+      nextAction: latestFact?.nextAction ?? null,
+      pendingHandoff,
       lastCheckpointAt: checkpoint?.occurredAt ?? null,
-      evidenceRefs: checkpoint?.evidenceRefs ?? handoff?.evidenceRefs ?? [],
+      evidenceRefs: latestFact?.evidenceRefs ?? [],
       assignmentHistory: history,
       truthRefs,
     };
   });
-  const byId = new Map(workItems.map(row => [row.workItemId, row]));
   const openDecisions = [...state.decisions.values()]
     .filter(row => row.resolved === null)
     .map(row => ({
@@ -622,6 +1026,45 @@ function projectStatus(definition, records, workspaceRoot = null) {
       truthRefs: [row.opened.ref],
     }))
     .sort((left, right) => left.decisionId.localeCompare(right.decisionId));
+  const openDecisionIds = new Set(openDecisions.map(row => row.decisionId));
+  workItems = workItems.map((row) => {
+    const terminal = ["completed", "failed"].includes(row.status);
+    const currentDecisionIds = terminal
+      ? []
+      : openDecisionsForWorkItem(row, openDecisions).map(decision => decision.decisionId);
+    const checkpointDecisionIds = uniqueSorted([
+      ...row.decisionRefs,
+      ...row.blockers
+        .filter(ref => ref.startsWith("decision:"))
+        .map(ref => ref.slice("decision:".length)),
+    ]);
+    const staleDecisionRefs = checkpointDecisionIds.filter(id => !openDecisionIds.has(id));
+    const currentBlockers = row.blockers.filter(ref => (
+      !ref.startsWith("decision:") || openDecisionIds.has(ref.slice("decision:".length))
+    ));
+    for (const decisionId of currentDecisionIds) {
+      const blockerRef = `decision:${decisionId}`;
+      if (!currentBlockers.includes(blockerRef)) currentBlockers.push(blockerRef);
+    }
+    const underlyingStatus = row.assignmentId === null
+      ? "planned"
+      : row.unresolvedDependencies.length > 0 ? "waiting_dependency" : "active";
+    let status = row.status;
+    if (!row.pendingHandoff && !terminal) {
+      status = currentDecisionIds.length > 0
+        ? "waiting_decision"
+        : row.status === "waiting_decision" ? underlyingStatus : row.status;
+    }
+    return {
+      ...row,
+      status,
+      blockers: currentBlockers,
+      decisionRefs: row.decisionRefs.filter(id => openDecisionIds.has(id)),
+      summary: staleDecisionRefs.length > 0 ? null : row.summary,
+      nextAction: staleDecisionRefs.length > 0 ? null : row.nextAction,
+    };
+  });
+  const byId = new Map(workItems.map(row => [row.workItemId, row]));
   const resolvedDecisions = [...state.decisions.values()]
     .filter(row => row.resolved !== null)
     .map(row => ({
@@ -633,11 +1076,42 @@ function projectStatus(definition, records, workspaceRoot = null) {
     }))
     .sort((left, right) => left.decisionId.localeCompare(right.decisionId));
   const resolvedDecisionIds = new Set(resolvedDecisions.map(row => row.decisionId));
+  const gateOrder = new Map(
+    definition.integrationGates.map((gate, index) => [gate.id, index]),
+  );
+  const deferredVerifications = [...state.verifications.values()]
+    .map((row) => ({
+      verificationId: row.deferred.verificationId,
+      workItemId: row.deferred.workItemId,
+      ownerAgentId: row.deferred.ownerAgentId,
+      checkIds: [...row.deferred.checkIds],
+      reason: row.deferred.reason,
+      dueGateId: row.deferred.dueGateId,
+      status: row.closed ? "closed" : "open",
+      disposition: row.closed?.disposition ?? null,
+      summary: row.closed?.summary ?? null,
+      evidenceRefs: row.closed ? [...row.closed.evidenceRefs] : [],
+      decisionIds: row.closed ? [...row.closed.decisionIds] : [],
+      truthRefs: [row.deferred.ref, ...(row.closed ? [row.closed.ref] : [])],
+    }))
+    .sort((left, right) => (
+      gateOrder.get(left.dueGateId) - gateOrder.get(right.dueGateId)
+      || compareIdentifiers(left.verificationId, right.verificationId)
+    ));
+  const openDeferredVerifications = deferredVerifications.filter(row => row.status === "open");
+  const openDeferredVerificationIds = openDeferredVerifications
+    .map(row => row.verificationId);
   const integrationGates = definition.integrationGates.map((gate) => {
     const unresolvedWorkItemIds = gate.requiredWorkItemIds.filter(id => byId.get(id).status !== "completed");
     const unresolvedDecisionIds = gate.requiredDecisionIds.filter(id => !resolvedDecisionIds.has(id));
+    const gateVerifications = deferredVerifications.filter(row => row.dueGateId === gate.id);
+    const unresolvedVerificationIds = gateVerifications
+      .filter(row => row.status === "open")
+      .map(row => row.verificationId);
     const pass = state.gatePasses.get(gate.id) ?? null;
-    let status = unresolvedWorkItemIds.length === 0 && unresolvedDecisionIds.length === 0
+    let status = unresolvedWorkItemIds.length === 0
+      && unresolvedDecisionIds.length === 0
+      && unresolvedVerificationIds.length === 0
       ? "ready"
       : "blocked";
     if (pass) {
@@ -650,8 +1124,13 @@ function projectStatus(definition, records, workspaceRoot = null) {
       status,
       unresolvedWorkItemIds,
       unresolvedDecisionIds,
+      unresolvedVerificationIds,
       evidenceRefs: pass?.evidenceRefs ?? [],
-      truthRefs: ["project/definition.json", ...(pass ? [pass.ref] : [])],
+      truthRefs: [
+        "project/definition.json",
+        ...gateVerifications.flatMap(row => row.truthRefs),
+        ...(pass ? [pass.ref] : []),
+      ],
     };
   });
   const stateNames = [
@@ -666,7 +1145,10 @@ function projectStatus(definition, records, workspaceRoot = null) {
   const orderedCounts = { total: counts.total };
   for (const name of stateNames) orderedCounts[name] = counts[name];
   const readyQueue = workItems
-    .filter(row => row.status === "planned" && row.unresolvedDependencies.length === 0)
+    .filter(row => row.status === "planned"
+      && row.assignmentId === null
+      && row.pendingHandoff === null
+      && row.unresolvedDependencies.length === 0)
     .map(row => row.workItemId)
     .sort();
   const downstream = new Map(workItems.map(row => [row.workItemId, 0]));
@@ -732,10 +1214,11 @@ function projectStatus(definition, records, workspaceRoot = null) {
   });
   let overall = "planned";
   if (workItems.every(row => row.status === "completed")
-    && integrationGates.every(row => row.status === "passed")) overall = "completed";
+    && integrationGates.every(row => row.status === "passed")
+    && openDecisions.length === 0) overall = "completed";
   else if (openDecisions.length > 0 || workItems.some(row => row.status === "failed")) overall = "active_with_blockers";
-  else if (workItems.some(row => row.status !== "planned")) overall = "active";
-  return {
+  else if (workItems.some(row => row.status !== "planned" || row.pendingHandoff !== null)) overall = "active";
+  const status = {
     schemaVersion: STATUS_SCHEMA,
     status: "team_project_status",
     projectId: definition.projectId,
@@ -750,11 +1233,14 @@ function projectStatus(definition, records, workspaceRoot = null) {
     criticalWorkItems,
     openDecisions,
     resolvedDecisions,
+    deferredVerifications,
+    openDeferredVerificationIds,
     integrationGates,
     dataCandidates,
     projectTruthHash: sha256(canonical({ definition, events: records.map(row => row.event) })),
     authorizationGranted: false,
   };
+  return { ...status, ...deriveProjectDriverSummary(status) };
 }
 
 function validateEventAgainstState(event, definition, records, workspaceRoot) {
@@ -778,6 +1264,15 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
     if (!current && normalized.supersedesAssignmentId !== undefined) {
       throw new Error("supersedesAssignmentId has no current assignment.");
     }
+    const currentProjection = status.workItems.find(
+      row => row.workItemId === normalized.workItemId,
+    );
+    if (currentProjection?.pendingHandoff
+      && normalized.agentId !== currentProjection.pendingHandoff.toAgentId) {
+      throw new Error(
+        `Assignment must accept pending handoff target ${currentProjection.pendingHandoff.toAgentId}.`,
+      );
+    }
     for (const projected of status.workItems) {
       if (projected.workItemId === normalized.workItemId
         || projected.assignmentId === null
@@ -794,6 +1289,17 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
     if (!current || current.assignmentId !== normalized.assignmentId) {
       throw new Error("Checkpoint must bind the current assignment.");
     }
+    if (normalized.state !== "completed") {
+      const invalidatedGate = definition.integrationGates.find(gate => (
+        gate.requiredWorkItemIds.includes(normalized.workItemId)
+        && state.gatePasses.has(gate.id)
+      ));
+      if (invalidatedGate) {
+        throw new Error(
+          `Checkpoint cannot invalidate passed integration gate ${invalidatedGate.id}.`,
+        );
+      }
+    }
     const unresolved = status.workItems.find(row => row.workItemId === normalized.workItemId).unresolvedDependencies;
     if (normalized.state === "completed" && unresolved.length > 0) {
       throw new Error(`Completed checkpoint has unresolved dependencies: ${unresolved.join(", ")}.`);
@@ -824,6 +1330,10 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
     }
   } else if (normalized.type === "handoff_recorded") {
     const current = state.assignments.get(normalized.workItemId);
+    const projected = status.workItems.find(row => row.workItemId === normalized.workItemId);
+    if (["completed", "failed"].includes(projected?.status)) {
+      throw new Error("Handoff cannot target a completed or failed WorkItem.");
+    }
     if (!current
       || current.assignmentId !== normalized.assignmentId
       || current.agentId !== normalized.fromAgentId) {
@@ -834,8 +1344,35 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
   } else if (normalized.type === "decision_resolved") {
     const decision = state.decisions.get(normalized.decisionId);
     if (!decision || decision.resolved) throw new Error(`Decision ${normalized.decisionId} is not open.`);
+  } else if (normalized.type === "verification_deferred") {
+    if (state.verifications.has(normalized.verificationId)) {
+      throw new Error(`Deferred verification ${normalized.verificationId} already exists.`);
+    }
+    if (state.gatePasses.has(normalized.dueGateId)) {
+      throw new Error(
+        `Deferred verification cannot target integration gate ${normalized.dueGateId}; gate already passed.`,
+      );
+    }
+  } else if (normalized.type === "verification_closed") {
+    const verification = state.verifications.get(normalized.verificationId);
+    if (!verification || verification.closed) {
+      throw new Error(`Deferred verification ${normalized.verificationId} is not open.`);
+    }
+    if (normalized.disposition === "no_longer_required") {
+      for (const decisionId of normalized.decisionIds) {
+        const decision = state.decisions.get(decisionId);
+        if (!decision?.resolved) {
+          throw new Error(
+            `No-longer-required deferred verification requires resolved decision ${decisionId}.`,
+          );
+        }
+      }
+    }
   } else if (normalized.type === "integration_gate_passed") {
     const gate = status.integrationGates.find(row => row.gateId === normalized.gateId);
+    if (state.gatePasses.has(normalized.gateId)) {
+      throw new Error(`Integration gate ${normalized.gateId} has already passed.`);
+    }
     if (gate.status !== "ready") throw new Error(`Integration gate ${normalized.gateId} is not ready.`);
   } else if (normalized.type === "data_candidate_recorded") {
     if (state.dataCandidates.some(row => row.candidateId === normalized.candidateId)) {
@@ -846,11 +1383,11 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
 }
 
 export function initializeTeamProjectV1({ workspaceRoot, definition }) {
+  const normalized = validateDefinition(definition);
   if (!existsSync(workspaceRoot)) mkdirSync(workspaceRoot, { recursive: true });
   const { root, projectRoot: rootPath } = projectRoot(workspaceRoot);
   assertRealProjectTree(root, rootPath);
   assertRealProjectTree(root, path.join(rootPath, "events"));
-  const normalized = validateDefinition(definition);
   const definitionPath = path.join(rootPath, "definition.json");
   if (existsSync(definitionPath)) {
     const existing = readRegularJson(definitionPath, "Team project definition");
@@ -927,6 +1464,432 @@ export function appendTeamProjectEventV1({ workspaceRoot, event }) {
   });
 }
 
+export function assignTeamProjectV1({
+  workspaceRoot,
+  assignmentId,
+  occurredAt,
+  workItemId,
+  agentId,
+  supersedesAssignmentId,
+  executionRunId,
+  executionWorkItemId,
+}) {
+  safeIdentifier(assignmentId, "assignmentId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `assignment-${assignmentId}`,
+    type: "agent_assigned",
+    occurredAt,
+    assignmentId,
+    workItemId,
+    agentId,
+  };
+  if (supersedesAssignmentId !== undefined) {
+    event.supersedesAssignmentId = supersedesAssignmentId;
+  }
+  if (executionRunId !== undefined) event.executionRunId = executionRunId;
+  if (executionWorkItemId !== undefined) event.executionWorkItemId = executionWorkItemId;
+
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  if (recorded.resumed) {
+    const current = status.workItems.find(row => row.workItemId === workItemId);
+    if (current?.assignmentId !== assignmentId) {
+      throw new Error(
+        `Cannot resume historical/superseded assignment ${assignmentId}; `
+        + `current assignment=${current?.assignmentId ?? "none"}, `
+        + `current owner=${current?.agentId ?? "none"}.`,
+      );
+    }
+  }
+  return {
+    status: "team_project_assignment",
+    assignmentId,
+    workItemId,
+    agentId,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function handoffTeamProjectV1({
+  workspaceRoot,
+  handoffId,
+  occurredAt,
+  assignmentId,
+  workItemId,
+  fromAgentId,
+  toAgentId,
+  summary,
+  nextAction,
+  evidenceRefs,
+}) {
+  safeIdentifier(handoffId, "handoffId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `handoff-${handoffId}`,
+    type: "handoff_recorded",
+    occurredAt,
+    assignmentId,
+    workItemId,
+    fromAgentId,
+    toAgentId,
+    summary,
+    evidenceRefs,
+    nextAction,
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  const current = status.workItems.find(row => row.workItemId === workItemId);
+  const pending = current?.pendingHandoff ?? null;
+  if (recorded.resumed && (
+    current?.assignmentId !== assignmentId
+      || current?.agentId !== fromAgentId
+      || pending?.eventId !== event.eventId
+  )) {
+    throw new Error(
+      `Cannot resume historical/superseded handoff ${handoffId}; `
+      + `current assignment=${current?.assignmentId ?? "none"}, `
+      + `current owner=${current?.agentId ?? "none"}, `
+      + `current pending target=${pending?.toAgentId ?? "none"}.`,
+    );
+  }
+  return {
+    status: "team_project_handoff",
+    handoffId,
+    assignmentId,
+    workItemId,
+    fromAgentId,
+    toAgentId,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    pending: true,
+    targetNextAction: pending?.nextAction ?? nextAction,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    projectNextAction: status.nextAction,
+    projectNextActorId: status.nextActorId,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function openTeamProjectDecisionV1({
+  workspaceRoot,
+  decisionId,
+  occurredAt,
+  title,
+  question,
+  ownerAgentId,
+  blockingWorkItemIds,
+  options,
+}) {
+  safeIdentifier(decisionId, "decisionId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `decision-opened-${decisionId}`,
+    type: "decision_opened",
+    occurredAt,
+    decisionId,
+    title,
+    question,
+    ownerAgentId,
+    blockingWorkItemIds,
+    options,
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  if (recorded.resumed && !status.openDecisions.some(row => row.decisionId === decisionId)) {
+    const resolved = status.resolvedDecisions.some(row => row.decisionId === decisionId);
+    throw new Error(
+      `Cannot resume historical decision ${decisionId}; `
+      + (resolved ? "decision is already resolved." : "decision is not currently open."),
+    );
+  }
+  return {
+    status: "team_project_decision",
+    operation: "opened",
+    decisionId,
+    ownerAgentId,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function resolveTeamProjectDecisionV1({
+  workspaceRoot,
+  decisionId,
+  occurredAt,
+  resolution,
+  rationale,
+  evidenceRefs,
+}) {
+  safeIdentifier(decisionId, "decisionId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `decision-resolved-${decisionId}`,
+    type: "decision_resolved",
+    occurredAt,
+    decisionId,
+    resolution,
+    rationale,
+    evidenceRefs,
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  if (recorded.resumed && !status.resolvedDecisions.some(row => row.decisionId === decisionId)) {
+    throw new Error(`Cannot resume decision ${decisionId}; decision is not resolved.`);
+  }
+  return {
+    status: "team_project_decision",
+    operation: "resolved",
+    decisionId,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function deferTeamProjectVerificationV1({
+  workspaceRoot,
+  verificationId,
+  occurredAt,
+  workItemId,
+  ownerAgentId,
+  checkIds,
+  reason,
+  dueGateId,
+}) {
+  safeIdentifier(verificationId, "verificationId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `verification-deferred-${verificationId}`,
+    type: "verification_deferred",
+    occurredAt,
+    verificationId,
+    workItemId,
+    ownerAgentId,
+    checkIds,
+    reason,
+    dueGateId,
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  const verification = status.deferredVerifications.find(
+    row => row.verificationId === verificationId,
+  );
+  if (recorded.resumed && verification?.status !== "open") {
+    throw new Error(`Cannot resume closed deferred verification ${verificationId}.`);
+  }
+  const gate = status.integrationGates.find(row => row.gateId === dueGateId);
+  return {
+    status: "team_project_verification",
+    operation: "deferred",
+    verificationId,
+    verificationStatus: verification?.status ?? null,
+    dueGateId,
+    gateStatus: gate?.status ?? null,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    overall: status.overall,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    verificationCommandExecuted: false,
+    gitWritePerformed: false,
+    releaseWritePerformed: false,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function closeTeamProjectVerificationV1({
+  workspaceRoot,
+  verificationId,
+  occurredAt,
+  disposition,
+  summary,
+  evidenceRefs,
+  decisionIds,
+}) {
+  safeIdentifier(verificationId, "verificationId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `verification-closed-${verificationId}`,
+    type: "verification_closed",
+    occurredAt,
+    verificationId,
+    disposition,
+    summary,
+    evidenceRefs,
+    decisionIds,
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  const verification = status.deferredVerifications.find(
+    row => row.verificationId === verificationId,
+  );
+  if (verification?.status !== "closed" || verification.disposition !== disposition) {
+    throw new Error(`Cannot resume deferred verification close ${verificationId}.`);
+  }
+  const gate = status.integrationGates.find(row => row.gateId === verification.dueGateId);
+  return {
+    status: "team_project_verification",
+    operation: "closed",
+    verificationId,
+    verificationStatus: verification.disposition,
+    dueGateId: verification.dueGateId,
+    gateStatus: gate?.status ?? null,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    overall: status.overall,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    verificationCommandExecuted: false,
+    gitWritePerformed: false,
+    releaseWritePerformed: false,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function integrateTeamProjectV1({
+  workspaceRoot,
+  gateId,
+  occurredAt,
+  summary,
+  evidenceRefs,
+}) {
+  safeIdentifier(gateId, "gateId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `integration-gate-${gateId}`,
+    type: "integration_gate_passed",
+    occurredAt,
+    gateId,
+    summary,
+    evidenceRefs,
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  const gate = status.integrationGates.find(row => row.gateId === gateId);
+  return {
+    status: "team_project_integration",
+    gateId,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    gateStatus: gate?.status ?? null,
+    overall: status.overall,
+    projectTruthHash: status.projectTruthHash,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    gitWritePerformed: false,
+    releaseWritePerformed: false,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
+export function checkpointTeamProjectV1({
+  workspaceRoot,
+  checkpointId,
+  occurredAt,
+  assignmentId,
+  workItemId,
+  state,
+  summary,
+  completedUnits,
+  evidenceRefs = [],
+  blockerRefs = [],
+  decisionRefs = [],
+  nextAction = null,
+  sourceFingerprint,
+}) {
+  safeIdentifier(checkpointId, "checkpointId");
+  const event = {
+    schemaVersion: EVENT_SCHEMA,
+    eventId: `checkpoint-${checkpointId}`,
+    type: "checkpoint_recorded",
+    occurredAt,
+    assignmentId,
+    workItemId,
+    state,
+    summary,
+    ...(completedUnits === undefined ? {} : { completedUnits }),
+    evidenceRefs,
+    blockerRefs,
+    decisionRefs,
+    nextAction,
+    ...(sourceFingerprint === undefined ? {} : { sourceFingerprint }),
+  };
+  const recorded = appendTeamProjectEventV1({ workspaceRoot, event });
+  const status = readTeamProjectStatusV1({ workspaceRoot });
+  if (recorded.resumed) {
+    const loaded = loadProject(workspaceRoot);
+    const stateProjection = projectEvents(loaded.definition, loaded.events);
+    const currentAssignment = stateProjection.assignments.get(workItemId) ?? null;
+    const latestFact = latestEventFact(
+      stateProjection.checkpoints.get(workItemId) ?? null,
+      stateProjection.handoffs.get(workItemId) ?? null,
+    );
+    if (currentAssignment?.assignmentId !== assignmentId || latestFact?.eventId !== event.eventId) {
+      throw new Error(
+        `Cannot resume historical/superseded checkpoint ${checkpointId}; `
+        + `current assignment=${currentAssignment?.assignmentId ?? "none"}, `
+        + `current owner=${currentAssignment?.agentId ?? "none"}, `
+        + `latest fact=${latestFact?.eventId ?? "none"}.`,
+      );
+    }
+  }
+  return {
+    status: "team_project_checkpoint",
+    checkpointId,
+    assignmentId,
+    workItemId,
+    state,
+    eventId: recorded.eventId,
+    eventPath: recorded.eventPath,
+    eventSha256: recorded.eventSha256,
+    resumed: recorded.resumed,
+    projectTruthHash: status.projectTruthHash,
+    overall: status.overall,
+    nextAction: status.nextAction,
+    nextActorId: status.nextActorId,
+    authorizationGranted: false,
+    exitCode: 0,
+  };
+}
+
 export function readTeamProjectStatusV1({ workspaceRoot }) {
   const loaded = loadProject(workspaceRoot);
   return {
@@ -940,9 +1903,18 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
   const loaded = loadProject(workspaceRoot);
   const status = projectStatus(loaded.definition, loaded.events, loaded.root);
   const responsibilities = status.workItems.filter(row => row.agentId === agentId);
-  const current = responsibilities.find(row => !["completed", "failed"].includes(row.status))
+  const current = responsibilities.find(row => (
+    ["active", "verifying", "ready_to_integrate"].includes(row.status)
+    && row.pendingHandoff === null
+  ))
+    ?? responsibilities.find(row => !["completed", "failed"].includes(row.status))
     ?? responsibilities.at(-1)
     ?? null;
+  const pendingForCurrent = current?.pendingHandoff ?? null;
+  const pendingForAgent = status.workItems.find(row => (
+    row.pendingHandoff?.toAgentId === agentId
+  ))?.pendingHandoff ?? null;
+  const pendingHandoff = pendingForCurrent ?? pendingForAgent;
   const checkpoints = loaded.events
     .filter(row => row.event.type === "checkpoint_recorded"
       && responsibilities.some(item => item.workItemId === row.event.workItemId))
@@ -951,16 +1923,61 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
   const evidenceRefs = [...new Set([
     ...(lastCheckpoint?.evidenceRefs ?? []),
     ...(current?.evidenceRefs ?? []),
+    ...(pendingHandoff?.evidenceRefs ?? []),
   ])].sort();
+  const unresolvedDecisionsById = new Map();
+  for (const decision of status.openDecisions) {
+    if (decision.ownerAgentId === agentId
+      || (current && openDecisionsForWorkItem(current, [decision]).length > 0)) {
+      unresolvedDecisionsById.set(decision.decisionId, decision);
+    }
+  }
+  const unresolvedDecisions = [...unresolvedDecisionsById.values()]
+    .sort((left, right) => compareIdentifiers(left.decisionId, right.decisionId));
+  const ownedDecision = status.openDecisions.find(row => (
+    row.ownerAgentId === agentId
+      && status.dominantGap.kind === "decision"
+      && status.dominantGap.id === row.decisionId
+  )) ?? status.openDecisions.find(row => row.ownerAgentId === agentId) ?? null;
+  const blockingDecision = current
+    ? openDecisionsForWorkItem(current, status.openDecisions)[0] ?? null
+    : null;
+  const deferredVerifications = status.deferredVerifications.filter(row => (
+    row.status === "open" && row.ownerAgentId === agentId
+  ));
+  const ownedVerification = deferredVerifications[0] ?? null;
+  let nextAction = null;
+  if (pendingForAgent && !current) {
+    nextAction = pendingForAgent.nextAction;
+  } else if (pendingForCurrent) {
+    nextAction = `Waiting for ${pendingForCurrent.toAgentId} to accept ${pendingForCurrent.workItemId}.`;
+  } else if (ownedDecision) {
+    nextAction = `Resolve ${ownedDecision.decisionId}`;
+  } else if (blockingDecision) {
+    nextAction = `Waiting for ${blockingDecision.ownerAgentId} to resolve ${blockingDecision.decisionId}.`;
+  } else if (ownedVerification) {
+    nextAction = `Run deferred verification ${ownedVerification.verificationId}`;
+  } else if (current?.nextAction) {
+    nextAction = current.nextAction;
+  } else {
+    nextAction = current && !["completed", "failed"].includes(current.status)
+      ? `Continue ${current.workItemId}.`
+      : current ? null : status.readyQueue[0] ? `Take ${status.readyQueue[0]}.` : null;
+  }
   return {
     schemaVersion: "OwlCodaRunKitTeamProjectTakeoverV1",
     status: "team_project_takeover",
     projectId: status.projectId,
     objective: status.objective,
     overall: status.overall,
+    projectHeadline: status.headline,
+    dominantGap: status.dominantGap,
+    projectNextAction: status.nextAction,
+    projectNextActorId: status.nextActorId,
     agentId,
     currentResponsibility: current,
     allResponsibilities: responsibilities,
+    pendingHandoff,
     lastAcceptedCheckpoint: lastCheckpoint
       ? {
           workItemId: lastCheckpoint.workItemId,
@@ -972,15 +1989,11 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
           truthRef: lastCheckpoint.truthRef,
         }
       : null,
-    unresolvedDecisions: status.openDecisions.filter(row => (
-      current && row.blockingWorkItemIds.includes(current.workItemId)
-    )),
+    unresolvedDecisions,
+    deferredVerifications,
     dependencies: current?.unresolvedDependencies ?? [],
     evidenceRefs,
-    nextAction: current?.nextAction
-      ?? (current && !["completed", "failed"].includes(current.status)
-        ? `Continue ${current.workItemId}.`
-        : current ? null : status.readyQueue[0] ? `Take ${status.readyQueue[0]}.` : null),
+    nextAction,
     projectTruthHash: status.projectTruthHash,
     authorizationGranted: false,
     exitCode: 0,
@@ -988,21 +2001,47 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
 }
 
 export function formatTeamProjectStatusHumanV1(status) {
-  const agentLines = status.agents.length === 0
-    ? ["Agents: none assigned"]
-    : status.agents.map(agent => (
-      `Agent ${agent.agentId}: active=${agent.activeWorkItemIds.join(",") || "none"}; `
-      + `waiting=${agent.waitingWorkItemIds.join(",") || "none"}; `
-      + `completed=${agent.completedWorkItemIds.join(",") || "none"}`
-    ));
+  const nextAction = status.nextAction === null ? "none" : singleLine(status.nextAction);
   return [
-    `${status.projectId}: ${status.objective}`,
+    status.headline,
+    `Project: ${status.projectId} — ${singleLine(status.objective)}`,
     `State: ${status.overall}`,
     `Work: ${status.counts.completed}/${status.counts.total} completed; ${status.counts.active} active; ${status.counts.waiting_dependency + status.counts.waiting_decision} waiting`,
-    ...agentLines,
+    `Agents: ${status.agents.map(agent => agent.agentId).join(", ") || "none assigned"}`,
     `Open decisions: ${status.openDecisions.map(row => row.decisionId).join(", ") || "none"}`,
-    `Critical work: ${status.criticalWorkItems.join(", ") || "none"}`,
+    `Deferred verification: ${status.openDeferredVerificationIds.length} open${
+      status.openDeferredVerificationIds.length > 0
+        ? ` (${status.openDeferredVerificationIds.join(", ")})`
+        : ""
+    }`,
     `Ready queue: ${status.readyQueue.join(", ") || "none"}`,
+    `Next: ${nextAction}${status.nextActorId ? ` (owner ${status.nextActorId})` : ""}`,
+    "",
+  ].join("\n");
+}
+
+export function formatTeamProjectTakeoverHumanV1(takeover) {
+  const responsibility = takeover.currentResponsibility;
+  const agentNextAction = takeover.nextAction === null
+    ? "none"
+    : singleLine(takeover.nextAction);
+  const projectNextAction = takeover.projectNextAction === null
+    ? "none"
+    : singleLine(takeover.projectNextAction);
+  return [
+    takeover.projectHeadline,
+    `Project: ${takeover.projectId} — ${singleLine(takeover.objective)}`,
+    `Agent: ${takeover.agentId}`,
+    `Responsibility: ${responsibility?.workItemId ?? "none"}`,
+    `Open decisions: ${takeover.unresolvedDecisions.map(row => row.decisionId).join(", ") || "none"}`,
+    `Deferred verification: ${takeover.deferredVerifications
+      .map(row => row.verificationId).join(", ") || "none"}`,
+    `Pending handoff: ${takeover.pendingHandoff
+      ? `${takeover.pendingHandoff.fromAgentId} -> ${takeover.pendingHandoff.toAgentId} for ${takeover.pendingHandoff.workItemId}`
+      : "none"}`,
+    `Agent next: ${agentNextAction}`,
+    `Project next: ${projectNextAction}${takeover.projectNextActorId ? ` (owner ${takeover.projectNextActorId})` : ""}`,
+    `State: ${takeover.overall}`,
     "",
   ].join("\n");
 }