owlrunkit 0.18.4 → 0.19.0

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

@@ -30,6 +30,7 @@ const DEFINITION_SCHEMA = "OwlCodaRunKitTeamProjectDefinitionV1";
 const EVENT_SCHEMA = "OwlCodaRunKitTeamProjectEventV1";
 const EVENT_SCHEMA_V2 = "OwlCodaRunKitTeamProjectEventV2";
 const EVENT_SCHEMA_V3 = "OwlCodaRunKitTeamProjectEventV3";
+const EVENT_SCHEMA_V4 = "OwlCodaRunKitTeamProjectEventV4";
 const STATUS_SCHEMA_V1 = "OwlCodaRunKitTeamProjectStatusV1";
 const STATUS_SCHEMA_V2 = "OwlCodaRunKitTeamProjectStatusV2";
 
@@ -110,6 +111,19 @@ const EVENT_KEYS = Object.freeze({
     "unchangedPacketPaths", "outOfScopeSourcePaths", "targetSnapshot",
     "proven", "notProven", "targetWritePerformed", "authorizationGranted",
   ],
+  upstream_reopened: [
+    "schemaVersion", "eventId", "type", "occurredAt", "reopenId",
+    "assignmentId", "previousAssignmentId", "previousCheckpointEventId",
+    "workItemId", "triggerWorkItemId", "fromAgentId", "reviewerAgentId",
+    "toAgentId", "reason", "evidenceRefs", "nextAction",
+  ],
+  responsibility_transferred: [
+    "schemaVersion", "eventId", "type", "occurredAt", "transferId",
+    "assignmentId", "previousAssignmentId", "checkpointEventId",
+    "handoffEventId", "assignmentEventId", "workItemId", "fromAgentId",
+    "toAgentId", "state", "summary", "completedUnits", "evidenceRefs",
+    "blockerRefs", "decisionRefs", "nextAction", "sourceFingerprint",
+  ],
 });
 
 function canonical(value) {
@@ -443,6 +457,22 @@ function latestEventFact(left, right) {
   return compareEventFacts(left, right) >= 0 ? left : right;
 }
 
+function downstreamWorkItemIds(definition, workItemId, { includeRoot = false } = {}) {
+  const children = new Map(definition.workItems.map(row => [row.id, []]));
+  for (const row of definition.workItems) {
+    for (const dependency of row.dependencies) children.get(dependency).push(row.id);
+  }
+  const visited = new Set(includeRoot ? [workItemId] : []);
+  const queue = [...children.get(workItemId)];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (visited.has(current)) continue;
+    visited.add(current);
+    queue.push(...children.get(current));
+  }
+  return [...visited].sort(compareIdentifiers);
+}
+
 function pendingHandoffProjection(handoff) {
   return handoff
     ? {
@@ -585,13 +615,18 @@ function staleHandoffsForTakeover({ loaded, status, agentId, responsibilities })
           "handoff_recorded",
           "rework_returned",
           "source_delivery_imported",
+          "upstream_reopened",
+          "responsibility_transferred",
         ].includes(row.event.type)
       ));
       let reason = "superseded_by_current_truth";
       if (laterFacts.some(row => row.event.type === "handoff_recorded")) {
         reason = "redirected_by_later_handoff";
       } else if (laterFacts.some(row => (
-        row.event.type === "agent_assigned" || row.event.type === "rework_returned"
+        row.event.type === "agent_assigned"
+        || row.event.type === "rework_returned"
+        || row.event.type === "upstream_reopened"
+        || row.event.type === "responsibility_transferred"
       ))) {
         reason = "superseded_by_assignment";
       } else if (laterFacts.length > 0) {
@@ -625,9 +660,10 @@ function validateEventShape(value, definition) {
     throw new Error("Team project event type is invalid.");
   }
   assertAllowedKeys(value, `Team project event ${value.eventId ?? "unknown"}`, EVENT_KEYS[value.type]);
-  if (![EVENT_SCHEMA, EVENT_SCHEMA_V2, EVENT_SCHEMA_V3].includes(value.schemaVersion)) {
+  if (![EVENT_SCHEMA, EVENT_SCHEMA_V2, EVENT_SCHEMA_V3, EVENT_SCHEMA_V4]
+    .includes(value.schemaVersion)) {
     throw new Error(
-      `Team project event schemaVersion must be ${EVENT_SCHEMA}, ${EVENT_SCHEMA_V2}, or ${EVENT_SCHEMA_V3}.`,
+      `Team project event schemaVersion must be ${EVENT_SCHEMA}, ${EVENT_SCHEMA_V2}, ${EVENT_SCHEMA_V3}, or ${EVENT_SCHEMA_V4}.`,
     );
   }
   if (value.type === "rework_returned" && value.schemaVersion !== EVENT_SCHEMA_V2) {
@@ -639,6 +675,15 @@ function validateEventShape(value, definition) {
   if (value.schemaVersion === EVENT_SCHEMA_V3 && value.type !== "source_delivery_imported") {
     throw new Error(`${EVENT_SCHEMA_V3} is reserved for source_delivery_imported events.`);
   }
+  const eventV4Types = new Set(["upstream_reopened", "responsibility_transferred"]);
+  if (eventV4Types.has(value.type) && value.schemaVersion !== EVENT_SCHEMA_V4) {
+    throw new Error(`${value.type} requires schemaVersion ${EVENT_SCHEMA_V4}.`);
+  }
+  if (value.schemaVersion === EVENT_SCHEMA_V4 && !eventV4Types.has(value.type)) {
+    throw new Error(
+      `${EVENT_SCHEMA_V4} is reserved for upstream_reopened and responsibility_transferred events.`,
+    );
+  }
   safeIdentifier(value.eventId, "eventId");
   validateTimestamp(value.occurredAt);
   const workItemIds = new Set(definition.workItems.map(row => row.id));
@@ -653,6 +698,8 @@ function validateEventShape(value, definition) {
     "handoff_recorded",
     "rework_returned",
     "source_delivery_imported",
+    "upstream_reopened",
+    "responsibility_transferred",
     "verification_deferred",
   ].includes(value.type)) {
     assertWorkItem(value.workItemId);
@@ -663,6 +710,8 @@ function validateEventShape(value, definition) {
     "handoff_recorded",
     "rework_returned",
     "source_delivery_imported",
+    "upstream_reopened",
+    "responsibility_transferred",
   ].includes(value.type)) {
     safeIdentifier(value.assignmentId, "assignmentId");
   }
@@ -864,6 +913,55 @@ function validateEventShape(value, definition) {
     if (value.targetWritePerformed !== false || value.authorizationGranted !== false) {
       throw new Error("External delivery cannot grant authority or write the target workspace.");
     }
+  } else if (value.type === "upstream_reopened") {
+    safeIdentifier(value.reopenId, "reopenId");
+    safeIdentifier(value.previousAssignmentId, "previousAssignmentId");
+    safeIdentifier(value.previousCheckpointEventId, "previousCheckpointEventId");
+    assertWorkItem(value.triggerWorkItemId);
+    safeIdentifier(value.fromAgentId, "fromAgentId");
+    safeIdentifier(value.reviewerAgentId, "reviewerAgentId");
+    safeIdentifier(value.toAgentId, "toAgentId");
+    nonEmptyString(value.reason, "Upstream reopen reason");
+    stringArray(value.evidenceRefs, "Upstream reopen evidenceRefs", { allowEmpty: false });
+    nonEmptyString(value.nextAction, "Upstream reopen nextAction");
+  } else if (value.type === "responsibility_transferred") {
+    safeIdentifier(value.transferId, "transferId");
+    safeIdentifier(value.previousAssignmentId, "previousAssignmentId");
+    for (const [field, label] of [
+      ["checkpointEventId", "checkpointEventId"],
+      ["handoffEventId", "handoffEventId"],
+      ["assignmentEventId", "assignmentEventId"],
+    ]) safeIdentifier(value[field], label);
+    if (new Set([
+      value.eventId,
+      value.checkpointEventId,
+      value.handoffEventId,
+      value.assignmentEventId,
+    ]).size !== 4) {
+      throw new Error("Responsibility transfer fact IDs must be distinct.");
+    }
+    safeIdentifier(value.fromAgentId, "fromAgentId");
+    safeIdentifier(value.toAgentId, "toAgentId");
+    if (value.fromAgentId === value.toAgentId) {
+      throw new Error("Responsibility transfer Agents must differ.");
+    }
+    if (!["active", "waiting_dependency", "waiting_decision", "verifying", "ready_to_integrate"]
+      .includes(value.state)) {
+      throw new Error("Responsibility transfer state must be non-terminal.");
+    }
+    nonEmptyString(value.summary, "Responsibility transfer summary");
+    stringArray(value.evidenceRefs, "Responsibility transfer evidenceRefs", { allowEmpty: false });
+    stringArray(value.blockerRefs, "Responsibility transfer blockerRefs");
+    stringArray(value.decisionRefs, "Responsibility transfer decisionRefs");
+    nonEmptyString(value.nextAction, "Responsibility transfer nextAction");
+    if (value.completedUnits !== undefined
+      && (!Number.isSafeInteger(value.completedUnits) || value.completedUnits < 0)) {
+      throw new Error("Responsibility transfer completedUnits must be a non-negative integer.");
+    }
+    if (value.sourceFingerprint !== undefined
+      && !/^(?:sha256:)?[a-f0-9]{64}$/u.test(value.sourceFingerprint)) {
+      throw new Error("Responsibility transfer sourceFingerprint is invalid.");
+    }
   }
   return structuredClone(value);
 }
@@ -874,6 +972,8 @@ function projectEvents(definition, records) {
   const checkpoints = new Map();
   const handoffs = new Map();
   const reworks = new Map();
+  const reopens = new Map();
+  const transfers = new Map();
   const decisions = new Map();
   const gatePasses = new Map();
   const verifications = new Map();
@@ -881,8 +981,11 @@ function projectEvents(definition, records) {
   const sourceDeliveries = [];
   const seenAssignments = new Set();
   const seenReworks = new Set();
+  const seenReopens = new Set();
+  const seenTransfers = new Set();
   const seenDecisions = new Set();
   const seenDeliveries = new Set();
+  const seenFactIds = new Set(records.map(row => row.event.eventId));
 
   for (const { event, ref } of records) {
     validateEventShape(event, definition);
@@ -995,6 +1098,166 @@ function projectEvents(definition, records) {
       }
       seenDeliveries.add(event.deliveryId);
       sourceDeliveries.push({ ...event, ref });
+    } else if (event.type === "upstream_reopened") {
+      if (seenReopens.has(event.reopenId)) {
+        throw new Error(`Duplicate upstream reopen ${event.reopenId}.`);
+      }
+      if (seenAssignments.has(event.assignmentId)) {
+        throw new Error(`Duplicate assignmentId ${event.assignmentId}.`);
+      }
+      const current = assignments.get(event.workItemId) ?? null;
+      const checkpoint = checkpoints.get(event.workItemId) ?? null;
+      const affectedIds = downstreamWorkItemIds(
+        definition,
+        event.workItemId,
+        { includeRoot: true },
+      );
+      if (!current
+        || current.assignmentId !== event.previousAssignmentId
+        || current.agentId !== event.fromAgentId
+        || checkpoint?.eventId !== event.previousCheckpointEventId
+        || checkpoint.assignmentId !== current.assignmentId
+        || checkpoint.state !== "completed") {
+        throw new Error(
+          `Upstream reopen ${event.reopenId} does not bind the current completed WorkItem.`,
+        );
+      }
+      if (!downstreamWorkItemIds(definition, event.workItemId)
+        .includes(event.triggerWorkItemId)) {
+        throw new Error(
+          `Upstream reopen ${event.reopenId} trigger must be a transitive downstream WorkItem.`,
+        );
+      }
+      const triggerAssignment = assignments.get(event.triggerWorkItemId) ?? null;
+      if (triggerAssignment?.agentId !== event.reviewerAgentId) {
+        throw new Error(
+          `Upstream reopen ${event.reopenId} reviewer must own the trigger WorkItem.`,
+        );
+      }
+      const invalidatedGate = definition.integrationGates.find(gate => (
+        gatePasses.has(gate.id)
+        && gate.requiredWorkItemIds.some(id => affectedIds.includes(id))
+      ));
+      if (invalidatedGate) {
+        throw new Error(
+          `Upstream reopen cannot invalidate passed integration gate ${invalidatedGate.id}.`,
+        );
+      }
+      seenReopens.add(event.reopenId);
+      seenAssignments.add(event.assignmentId);
+      const assignment = {
+        schemaVersion: EVENT_SCHEMA,
+        eventId: `assignment-${event.assignmentId}`,
+        type: "agent_assigned",
+        occurredAt: event.occurredAt,
+        assignmentId: event.assignmentId,
+        supersedesAssignmentId: event.previousAssignmentId,
+        workItemId: event.workItemId,
+        agentId: event.toAgentId,
+        ref: `${ref}#assignment`,
+      };
+      assignments.set(event.workItemId, assignment);
+      assignmentHistory.get(event.workItemId).push(assignment);
+      reopens.set(event.workItemId, { ...event, affectedWorkItemIds: affectedIds, ref });
+    } else if (event.type === "responsibility_transferred") {
+      if (seenTransfers.has(event.transferId)) {
+        throw new Error(`Duplicate responsibility transfer ${event.transferId}.`);
+      }
+      if (seenAssignments.has(event.assignmentId)) {
+        throw new Error(`Duplicate assignmentId ${event.assignmentId}.`);
+      }
+      for (const factId of [
+        event.checkpointEventId,
+        event.handoffEventId,
+        event.assignmentEventId,
+      ]) {
+        if (seenFactIds.has(factId)) {
+          throw new Error(`Duplicate responsibility transfer fact ID ${factId}.`);
+        }
+      }
+      const current = assignments.get(event.workItemId) ?? null;
+      const currentCheckpoint = checkpoints.get(event.workItemId) ?? null;
+      const currentHandoff = handoffs.get(event.workItemId) ?? null;
+      const latestCurrentFact = [
+        currentCheckpoint,
+        currentHandoff,
+        reworks.get(event.workItemId) ?? null,
+        reopens.get(event.workItemId) ?? null,
+        transfers.get(event.workItemId) ?? null,
+        sourceDeliveries.filter(row => row.workItemId === event.workItemId).at(-1) ?? null,
+      ].reduce((latest, fact) => latestEventFact(latest, fact), null);
+      if (!current
+        || current.assignmentId !== event.previousAssignmentId
+        || current.agentId !== event.fromAgentId) {
+        throw new Error(
+          `Responsibility transfer ${event.transferId} does not bind the current assignment.`,
+        );
+      }
+      if (currentCheckpoint?.assignmentId === current.assignmentId
+        && ["completed", "failed"].includes(currentCheckpoint.state)) {
+        throw new Error("Responsibility transfer cannot target a terminal WorkItem.");
+      }
+      if (currentHandoff?.assignmentId === current.assignmentId
+        && currentHandoff.fromAgentId === current.agentId
+        && latestCurrentFact?.eventId === currentHandoff.eventId) {
+        throw new Error("Responsibility transfer cannot replace a pending handoff.");
+      }
+      const checkpoint = {
+        schemaVersion: EVENT_SCHEMA,
+        eventId: event.checkpointEventId,
+        type: "checkpoint_recorded",
+        occurredAt: event.occurredAt,
+        assignmentId: event.previousAssignmentId,
+        workItemId: event.workItemId,
+        state: event.state,
+        summary: event.summary,
+        ...(event.completedUnits === undefined ? {} : { completedUnits: event.completedUnits }),
+        evidenceRefs: [...event.evidenceRefs],
+        blockerRefs: [...event.blockerRefs],
+        decisionRefs: [...event.decisionRefs],
+        nextAction: event.nextAction,
+        ...(event.sourceFingerprint === undefined
+          ? {}
+          : { sourceFingerprint: event.sourceFingerprint }),
+        ref: `${ref}#checkpoint`,
+      };
+      const handoff = {
+        schemaVersion: EVENT_SCHEMA,
+        eventId: event.handoffEventId,
+        type: "handoff_recorded",
+        occurredAt: event.occurredAt,
+        assignmentId: event.previousAssignmentId,
+        workItemId: event.workItemId,
+        fromAgentId: event.fromAgentId,
+        toAgentId: event.toAgentId,
+        summary: event.summary,
+        evidenceRefs: [...event.evidenceRefs],
+        nextAction: event.nextAction,
+        ref: `${ref}#handoff`,
+      };
+      const assignment = {
+        schemaVersion: EVENT_SCHEMA,
+        eventId: event.assignmentEventId,
+        type: "agent_assigned",
+        occurredAt: event.occurredAt,
+        assignmentId: event.assignmentId,
+        supersedesAssignmentId: event.previousAssignmentId,
+        workItemId: event.workItemId,
+        agentId: event.toAgentId,
+        ref: `${ref}#assignment`,
+      };
+      for (const factId of [
+        event.checkpointEventId,
+        event.handoffEventId,
+        event.assignmentEventId,
+      ]) seenFactIds.add(factId);
+      seenTransfers.add(event.transferId);
+      seenAssignments.add(event.assignmentId);
+      checkpoints.set(event.workItemId, checkpoint);
+      handoffs.set(event.workItemId, handoff);
+      assignments.set(event.workItemId, assignment);
+      assignmentHistory.get(event.workItemId).push(assignment);
+      transfers.set(event.workItemId, { ...event, ref });
     }
   }
   return {
@@ -1003,6 +1266,8 @@ function projectEvents(definition, records) {
     checkpoints,
     handoffs,
     reworks,
+    reopens,
+    transfers,
     decisions,
     gatePasses,
     verifications,
@@ -1324,12 +1589,40 @@ function deriveProjectDriverSummary(status) {
   };
 }
 
-function projectStatus(definition, records, workspaceRoot = null) {
-  const state = projectEvents(definition, records);
+function affectingReopensForWorkItem(state, workItemId) {
+  return [...state.reopens.values()]
+    .filter(reopen => reopen.affectedWorkItemIds.includes(workItemId))
+    .sort(compareEventFacts);
+}
+
+function invalidatingReopensForWorkItem(state, workItemId) {
+  const checkpoint = state.checkpoints.get(workItemId) ?? null;
+  return affectingReopensForWorkItem(state, workItemId).filter(reopen => (
+    checkpoint?.state !== "completed" || compareEventFacts(checkpoint, reopen) <= 0
+  ));
+}
+
+function completedWorkItemIds(definition, state) {
   const completed = new Set();
-  for (const [id, checkpoint] of state.checkpoints) {
-    if (checkpoint.state === "completed") completed.add(id);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const item of definition.workItems) {
+      if (completed.has(item.id)) continue;
+      const checkpoint = state.checkpoints.get(item.id) ?? null;
+      if (checkpoint?.state !== "completed"
+        || invalidatingReopensForWorkItem(state, item.id).length > 0
+        || item.dependencies.some(id => !completed.has(id))) continue;
+      completed.add(item.id);
+      changed = true;
+    }
   }
+  return completed;
+}
+
+function projectStatus(definition, records, workspaceRoot = null) {
+  const state = projectEvents(definition, records);
+  const completed = completedWorkItemIds(definition, state);
   let workItems = definition.workItems.map((item) => {
     const assignment = state.assignments.get(item.id) ?? null;
     const checkpoint = state.checkpoints.get(item.id) ?? null;
@@ -1339,7 +1632,20 @@ function projectStatus(definition, records, workspaceRoot = null) {
     const latestSourceDeliveryFact = sourceDeliveries.at(-1) ?? null;
     const latestSourceDelivery = sourceDeliveryProjection(sourceDeliveries.at(-1) ?? null);
     const currentRework = rework?.assignmentId === assignment?.assignmentId ? rework : null;
-    const latestFact = latestEventFact(latestEventFact(checkpoint, handoff), currentRework);
+    const reopenFacts = affectingReopensForWorkItem(state, item.id);
+    const invalidatingReopens = invalidatingReopensForWorkItem(state, item.id);
+    const currentReopen = state.reopens.get(item.id)?.assignmentId === assignment?.assignmentId
+      ? state.reopens.get(item.id)
+      : null;
+    const currentTransfer = state.transfers.get(item.id)?.assignmentId === assignment?.assignmentId
+      ? state.transfers.get(item.id)
+      : null;
+    const effectiveCheckpoint = invalidatingReopens.length === 0 ? checkpoint : null;
+    let latestFact = [effectiveCheckpoint, handoff, currentRework, currentReopen, currentTransfer]
+      .reduce((latest, fact) => latestEventFact(latest, fact), null);
+    if (currentTransfer && latestFact?.occurredAt === currentTransfer.occurredAt) {
+      latestFact = currentTransfer;
+    }
     const activeHandoff = handoff
       && handoff.assignmentId === assignment?.assignmentId
       && handoff.fromAgentId === assignment?.agentId
@@ -1350,7 +1656,8 @@ function projectStatus(definition, records, workspaceRoot = null) {
       && latestFact?.eventId === activeHandoff.eventId
       && latestHandoffFact?.eventId !== activeHandoff.eventId;
     const projectedFact = handoffSupersededByDelivery
-      ? latestEventFact(checkpoint, currentRework)
+      ? [effectiveCheckpoint, currentRework, currentReopen, currentTransfer]
+        .reduce((latest, fact) => latestEventFact(latest, fact), null)
       : latestFact;
     const pendingHandoff = activeHandoff
       && latestFact?.eventId === activeHandoff.eventId
@@ -1362,7 +1669,11 @@ function projectStatus(definition, records, workspaceRoot = null) {
     let status = "planned";
     if (assignment) status = unresolvedDependencies.length > 0 ? "waiting_dependency" : "active";
     if (pendingHandoff) status = "planned";
-    if (projectedFact?.type === "checkpoint_recorded") status = checkpoint.state;
+    if (projectedFact?.type === "checkpoint_recorded") status = effectiveCheckpoint.state;
+    if (projectedFact?.type === "responsibility_transferred") status = projectedFact.state;
+    if (projectedFact?.type === "upstream_reopened") status = "active";
+    if (assignment && unresolvedDependencies.length > 0
+      && !["completed", "failed"].includes(status)) status = "waiting_dependency";
     if (executionTruth && (executionTruth.status !== "bound"
       || (executionTruth.lifecycle === "closed"
         && executionTruth.closeoutDecision !== "accepted"))) {
@@ -1372,7 +1683,7 @@ function projectStatus(definition, records, workspaceRoot = null) {
       ? {
           kind: "measured_units",
           unit: item.measurable.unit,
-          completed: checkpoint?.completedUnits ?? 0,
+          completed: effectiveCheckpoint?.completedUnits ?? 0,
           total: item.measurable.total,
         }
       : { kind: "state_only" };
@@ -1391,6 +1702,8 @@ function projectStatus(definition, records, workspaceRoot = null) {
       ...(checkpoint ? [checkpoint.ref] : []),
       ...(handoff ? [handoff.ref] : []),
       ...(rework ? [rework.ref] : []),
+      ...reopenFacts.map(row => row.ref),
+      ...(currentTransfer ? [currentTransfer.ref] : []),
       ...sourceDeliveries.map(row => row.ref),
     ];
     const projectedRework = reworkProjection(
@@ -1399,9 +1712,13 @@ function projectStatus(definition, records, workspaceRoot = null) {
         ? assignmentEvents.findIndex(row => row.assignmentId === currentRework.assignmentId) + 1
         : null,
     );
-    const latestSummary = projectedFact?.type === "rework_returned"
+    const latestSummary = ["rework_returned", "upstream_reopened"].includes(projectedFact?.type)
       ? projectedFact.reason
       : projectedFact?.summary ?? null;
+    const checkpointLikeFact = ["checkpoint_recorded", "responsibility_transferred"]
+      .includes(projectedFact?.type)
+      ? projectedFact
+      : null;
     return {
       workItemId: item.id,
       title: item.title,
@@ -1415,10 +1732,10 @@ function projectStatus(definition, records, workspaceRoot = null) {
       executionTruth,
       dependencies: [...item.dependencies],
       unresolvedDependencies,
-      blockers: projectedFact?.type === "checkpoint_recorded"
-        ? checkpoint.blockerRefs
+      blockers: checkpointLikeFact
+        ? checkpointLikeFact.blockerRefs
         : unresolvedDependencies.map(id => `work-item:${id}`),
-      decisionRefs: projectedFact?.type === "checkpoint_recorded" ? checkpoint.decisionRefs : [],
+      decisionRefs: checkpointLikeFact ? checkpointLikeFact.decisionRefs : [],
       progress: measured,
       summary: latestSummary,
       nextAction: projectedFact?.nextAction ?? null,
@@ -1429,6 +1746,9 @@ function projectStatus(definition, records, workspaceRoot = null) {
       evidenceRefs: projectedFact?.evidenceRefs ?? [],
       assignmentHistory: history,
       truthRefs,
+      ...(reopenFacts.length === 0
+        ? {}
+        : { invalidatedByReopenIds: invalidatingReopens.map(row => row.reopenId) }),
     };
   });
   const openDecisions = [...state.decisions.values()]
@@ -1794,6 +2114,101 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
         );
       }
     }
+  } else if (normalized.type === "upstream_reopened") {
+    if ([...state.reopens.values()].some(row => row.reopenId === normalized.reopenId)) {
+      throw new Error(`Upstream reopen ${normalized.reopenId} already exists.`);
+    }
+    if (state.assignmentHistory.get(normalized.workItemId).some(
+      row => row.assignmentId === normalized.assignmentId,
+    )) {
+      throw new Error(`Assignment ${normalized.assignmentId} already exists.`);
+    }
+    const current = state.assignments.get(normalized.workItemId) ?? null;
+    const checkpoint = state.checkpoints.get(normalized.workItemId) ?? null;
+    const projected = status.workItems.find(row => row.workItemId === normalized.workItemId);
+    if (projected?.status !== "completed"
+      || !current
+      || current.assignmentId !== normalized.previousAssignmentId
+      || current.agentId !== normalized.fromAgentId
+      || checkpoint?.eventId !== normalized.previousCheckpointEventId
+      || checkpoint.assignmentId !== current.assignmentId
+      || checkpoint.state !== "completed") {
+      throw new Error("reopen-upstream requires the current completed upstream WorkItem.");
+    }
+    const downstreamIds = downstreamWorkItemIds(definition, normalized.workItemId);
+    if (!downstreamIds.includes(normalized.triggerWorkItemId)) {
+      throw new Error("reopen-upstream trigger must be a transitive downstream WorkItem.");
+    }
+    const triggerAssignment = state.assignments.get(normalized.triggerWorkItemId) ?? null;
+    if (triggerAssignment?.agentId !== normalized.reviewerAgentId) {
+      throw new Error("reopen-upstream reviewer must own the trigger WorkItem.");
+    }
+    const affectedIds = [normalized.workItemId, ...downstreamIds];
+    const passedGate = definition.integrationGates.find(gate => (
+      state.gatePasses.has(gate.id)
+      && gate.requiredWorkItemIds.some(id => affectedIds.includes(id))
+    ));
+    if (passedGate) {
+      throw new Error(`reopen-upstream cannot invalidate passed integration gate ${passedGate.id}.`);
+    }
+    for (const otherProjection of status.workItems) {
+      if (otherProjection.workItemId === normalized.workItemId
+        || otherProjection.assignmentId === null
+        || ["completed", "failed"].includes(otherProjection.status)) continue;
+      const other = definition.workItems.find(row => row.id === otherProjection.workItemId);
+      if (pathsOverlap(workItem.ownedPaths, other.ownedPaths)) {
+        throw new Error(
+          `Owned paths overlap active assignment ${otherProjection.assignmentId}: ${normalized.workItemId} <> ${otherProjection.workItemId}.`,
+        );
+      }
+    }
+  } else if (normalized.type === "responsibility_transferred") {
+    if ([...state.transfers.values()].some(row => row.transferId === normalized.transferId)) {
+      throw new Error(`Responsibility transfer ${normalized.transferId} already exists.`);
+    }
+    if (state.assignmentHistory.get(normalized.workItemId).some(
+      row => row.assignmentId === normalized.assignmentId,
+    )) {
+      throw new Error(`Assignment ${normalized.assignmentId} already exists.`);
+    }
+    const current = state.assignments.get(normalized.workItemId) ?? null;
+    const projected = status.workItems.find(row => row.workItemId === normalized.workItemId);
+    if (!current
+      || current.assignmentId !== normalized.previousAssignmentId
+      || current.agentId !== normalized.fromAgentId) {
+      throw new Error("Responsibility transfer must bind the current assignment and Agent.");
+    }
+    if (["completed", "failed"].includes(projected?.status)) {
+      throw new Error("Responsibility transfer cannot target a terminal WorkItem.");
+    }
+    if (projected?.pendingHandoff !== null) {
+      throw new Error("Responsibility transfer cannot replace a pending handoff.");
+    }
+    const existingFactIds = new Set(records.flatMap(({ event }) => [
+      event.eventId,
+      ...(event.type === "responsibility_transferred"
+        ? [event.checkpointEventId, event.handoffEventId, event.assignmentEventId]
+        : []),
+    ]));
+    for (const factId of [
+      normalized.checkpointEventId,
+      normalized.handoffEventId,
+      normalized.assignmentEventId,
+    ]) {
+      if (existingFactIds.has(factId)) {
+        throw new Error(`Responsibility transfer fact ID ${factId} already exists.`);
+      }
+    }
+    if (workItem.measurable) {
+      if (normalized.completedUnits === undefined) {
+        throw new Error("Measured WorkItem transfer requires completedUnits.");
+      }
+      if (normalized.completedUnits > workItem.measurable.total) {
+        throw new Error("Responsibility transfer completedUnits exceeds measurable total.");
+      }
+    } else if (normalized.completedUnits !== undefined) {
+      throw new Error("Unmeasured WorkItem transfer cannot claim completedUnits.");
+    }
   } else if (normalized.type === "decision_opened") {
     if (state.decisions.has(normalized.decisionId)) throw new Error(`Decision ${normalized.decisionId} already exists.`);
   } else if (normalized.type === "decision_resolved") {
@@ -2181,6 +2596,205 @@ export function rejectAndReturnTeamProjectV1({
   });
 }
 
+export function reopenUpstreamTeamProjectV1({
+  workspaceRoot,
+  reopenId,
+  occurredAt,
+  upstreamWorkItemId,
+  triggerWorkItemId,
+  reviewerAgentId,
+  toAgentId,
+  reason,
+  nextAction,
+  evidenceRefs,
+}) {
+  safeIdentifier(reopenId, "reopenId");
+  const eventId = `upstream-reopened-${reopenId}`;
+  const assignmentId = `reopen-${reopenId}`;
+  const loaded = loadProject(workspaceRoot);
+  return withProjectLock(loaded.projectRoot, () => {
+    const refreshed = loadProject(workspaceRoot);
+    const existing = refreshed.events.find(row => row.event.eventId === eventId)?.event ?? null;
+    let event;
+    if (existing) {
+      event = {
+        schemaVersion: EVENT_SCHEMA_V4,
+        eventId,
+        type: "upstream_reopened",
+        occurredAt,
+        reopenId,
+        assignmentId,
+        previousAssignmentId: existing.previousAssignmentId,
+        previousCheckpointEventId: existing.previousCheckpointEventId,
+        workItemId: upstreamWorkItemId,
+        triggerWorkItemId,
+        fromAgentId: existing.fromAgentId,
+        reviewerAgentId,
+        toAgentId,
+        reason,
+        evidenceRefs,
+        nextAction,
+      };
+    } else {
+      const state = projectEvents(refreshed.definition, refreshed.events);
+      const current = state.assignments.get(upstreamWorkItemId) ?? null;
+      const checkpoint = state.checkpoints.get(upstreamWorkItemId) ?? null;
+      if (!current || !checkpoint) {
+        throw new Error("reopen-upstream requires an assigned, completed upstream WorkItem.");
+      }
+      event = {
+        schemaVersion: EVENT_SCHEMA_V4,
+        eventId,
+        type: "upstream_reopened",
+        occurredAt,
+        reopenId,
+        assignmentId,
+        previousAssignmentId: current.assignmentId,
+        previousCheckpointEventId: checkpoint.eventId,
+        workItemId: upstreamWorkItemId,
+        triggerWorkItemId,
+        fromAgentId: current.agentId,
+        reviewerAgentId,
+        toAgentId,
+        reason,
+        evidenceRefs,
+        nextAction,
+      };
+    }
+    const recorded = appendTeamProjectEventWithinLock(refreshed, event);
+    const projectedEvents = recorded.resumed
+      ? refreshed.events
+      : [...refreshed.events, { event, ref: `project/events/${event.eventId}.json` }];
+    const status = projectStatus(refreshed.definition, projectedEvents, refreshed.root);
+    const projectedState = projectEvents(refreshed.definition, projectedEvents);
+    const current = status.workItems.find(row => row.workItemId === upstreamWorkItemId) ?? null;
+    const reopen = projectedState.reopens.get(upstreamWorkItemId) ?? null;
+    if (current?.assignmentId !== assignmentId || reopen?.reopenId !== reopenId) {
+      throw new Error(
+        `Cannot resume historical/superseded upstream reopen ${reopenId}; `
+        + `current assignment=${current?.assignmentId ?? "none"}.`,
+      );
+    }
+    return {
+      status: "team_project_upstream_reopened",
+      reopenId,
+      assignmentId,
+      previousAssignmentId: event.previousAssignmentId,
+      previousCheckpointEventId: event.previousCheckpointEventId,
+      upstreamWorkItemId,
+      triggerWorkItemId,
+      fromAgentId: event.fromAgentId,
+      reviewerAgentId,
+      toAgentId,
+      invalidatedWorkItemIds: downstreamWorkItemIds(
+        refreshed.definition,
+        upstreamWorkItemId,
+        { includeRoot: true },
+      ),
+      eventId: recorded.eventId,
+      eventPath: recorded.eventPath,
+      eventSha256: recorded.eventSha256,
+      resumed: recorded.resumed,
+      projectTruthHash: status.projectTruthHash,
+      overall: status.overall,
+      nextAction: status.nextAction,
+      nextActorId: status.nextActorId,
+      gitWritePerformed: false,
+      releaseWritePerformed: false,
+      authorizationGranted: false,
+      exitCode: 0,
+    };
+  });
+}
+
+export function transferTeamProjectV1({
+  workspaceRoot,
+  transferId,
+  occurredAt,
+  assignmentId: previousAssignmentId,
+  workItemId,
+  fromAgentId,
+  toAgentId,
+  state,
+  summary,
+  completedUnits,
+  evidenceRefs = [],
+  blockerRefs = [],
+  decisionRefs = [],
+  nextAction,
+  sourceFingerprint,
+}) {
+  safeIdentifier(transferId, "transferId");
+  const eventId = `responsibility-transferred-${transferId}`;
+  const assignmentId = `transfer-${transferId}`;
+  const event = {
+    schemaVersion: EVENT_SCHEMA_V4,
+    eventId,
+    type: "responsibility_transferred",
+    occurredAt,
+    transferId,
+    assignmentId,
+    previousAssignmentId,
+    checkpointEventId: `transfer-checkpoint-${transferId}`,
+    handoffEventId: `transfer-handoff-${transferId}`,
+    assignmentEventId: `transfer-assignment-${transferId}`,
+    workItemId,
+    fromAgentId,
+    toAgentId,
+    state,
+    summary,
+    ...(completedUnits === undefined ? {} : { completedUnits }),
+    evidenceRefs,
+    blockerRefs,
+    decisionRefs,
+    nextAction,
+    ...(sourceFingerprint === undefined ? {} : { sourceFingerprint }),
+  };
+  const loaded = loadProject(workspaceRoot);
+  return withProjectLock(loaded.projectRoot, () => {
+    const refreshed = loadProject(workspaceRoot);
+    const recorded = appendTeamProjectEventWithinLock(refreshed, event);
+    const projectedEvents = recorded.resumed
+      ? refreshed.events
+      : [...refreshed.events, { event, ref: `project/events/${event.eventId}.json` }];
+    const status = projectStatus(refreshed.definition, projectedEvents, refreshed.root);
+    const projectedState = projectEvents(refreshed.definition, projectedEvents);
+    const current = status.workItems.find(row => row.workItemId === workItemId) ?? null;
+    const transfer = projectedState.transfers.get(workItemId) ?? null;
+    if (current?.assignmentId !== assignmentId || transfer?.transferId !== transferId) {
+      throw new Error(
+        `Cannot resume historical/superseded responsibility transfer ${transferId}; `
+        + `current assignment=${current?.assignmentId ?? "none"}.`,
+      );
+    }
+    const factRefs = ["checkpoint", "handoff", "assignment"]
+      .map(fragment => `project/events/${eventId}.json#${fragment}`);
+    return {
+      status: "team_project_transfer",
+      transferId,
+      assignmentId,
+      previousAssignmentId,
+      workItemId,
+      fromAgentId,
+      toAgentId,
+      state,
+      factRefs,
+      eventId: recorded.eventId,
+      eventPath: recorded.eventPath,
+      eventSha256: recorded.eventSha256,
+      resumed: recorded.resumed,
+      projectTruthHash: status.projectTruthHash,
+      overall: status.overall,
+      nextAction: status.nextAction,
+      nextActorId: status.nextActorId,
+      gitWritePerformed: false,
+      releaseWritePerformed: false,
+      authorizationGranted: false,
+      exitCode: 0,
+    };
+  });
+}
+
 export function openTeamProjectDecisionV1({
   workspaceRoot,
   decisionId,
@@ -2489,7 +3103,11 @@ export function checkpointTeamProjectV1({
 
 function legacyWorkItemProjection(workItem) {
   if (workItem === null) return null;
-  const { latestSourceDelivery: _latestSourceDelivery, ...legacy } = workItem;
+  const {
+    latestSourceDelivery: _latestSourceDelivery,
+    invalidatedByReopenIds: _invalidatedByReopenIds,
+    ...legacy
+  } = workItem;
   return legacy;
 }
 
@@ -2516,6 +3134,76 @@ export function readTeamProjectStatusV2({ workspaceRoot }) {
   };
 }
 
+export function readTeamProjectHandoffWaitV1({ workspaceRoot }) {
+  const { root, projectRoot: rootPath } = projectRoot(workspaceRoot);
+  if (!existsSync(path.join(rootPath, "definition.json"))) {
+    return {
+      completedHandoffs: 0,
+      unresolvedHandoffs: 0,
+      staleHandoffs: 0,
+      totalMs: 0,
+      averageMs: 0,
+      maxMs: 0,
+      samples: [],
+      inputRefs: [],
+    };
+  }
+  const loaded = loadProject(root);
+  const workFactTypes = new Set([
+    "agent_assigned",
+    "checkpoint_recorded",
+    "handoff_recorded",
+    "rework_returned",
+    "source_delivery_imported",
+    "upstream_reopened",
+    "responsibility_transferred",
+  ]);
+  const samples = [];
+  let unresolvedHandoffs = 0;
+  let staleHandoffs = 0;
+  const handoffs = loaded.events.filter(({ event }) => event.type === "handoff_recorded");
+  for (const { event, ref } of handoffs) {
+    const laterFacts = loaded.events.filter(({ event: later }) => (
+      later.workItemId === event.workItemId
+      && compareEventFacts(later, event) > 0
+      && workFactTypes.has(later.type)
+    ));
+    const accepted = laterFacts.find(({ event: later }) => (
+      later.type === "agent_assigned"
+      && later.supersedesAssignmentId === event.assignmentId
+      && later.agentId === event.toAgentId
+    ));
+    if (accepted) {
+      const durationMs = Date.parse(accepted.event.occurredAt) - Date.parse(event.occurredAt);
+      samples.push({
+        handoffEventId: event.eventId,
+        acceptedEventId: accepted.event.eventId,
+        workItemId: event.workItemId,
+        durationMs,
+        handoffRef: ref,
+        acceptedRef: accepted.ref,
+      });
+    } else if (laterFacts.length > 0) {
+      staleHandoffs += 1;
+    } else {
+      unresolvedHandoffs += 1;
+    }
+  }
+  const totalMs = samples.reduce((total, sample) => total + sample.durationMs, 0);
+  return {
+    completedHandoffs: samples.length,
+    unresolvedHandoffs,
+    staleHandoffs,
+    totalMs,
+    averageMs: samples.length === 0 ? 0 : Math.round(totalMs / samples.length),
+    maxMs: samples.length === 0 ? 0 : Math.max(...samples.map(sample => sample.durationMs)),
+    samples,
+    inputRefs: loaded.events
+      .filter(({ event }) => event.type === "handoff_recorded" || event.type === "agent_assigned")
+      .map(({ ref }) => ref),
+  };
+}
+
 export function buildTeamProjectTakeoverV2({ workspaceRoot, agentId }) {
   safeIdentifier(agentId, "agentId");
   const loaded = loadProject(workspaceRoot);