owlrunkit 0.18.3 → 0.19.0

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

@@ -12,6 +12,11 @@ import path from "node:path";
 
 import { validateLeaseOwnedPaths } from "./core-contract.mjs";
 import { inspectProjectControlState } from "./project-control-state.mjs";
+import { canonicalSourceFingerprint } from "./source-fingerprint.mjs";
+import {
+  quickSnapshotFingerprintValid,
+  validWorkspaceSnapshotShape,
+} from "../../packages/attest/src/quick-receipt-contract.mjs";
 import {
   assertAllowedKeys,
   isRecord,
@@ -24,7 +29,10 @@ const PROJECT_ROOT = ".owlcoda/runkit/project";
 const DEFINITION_SCHEMA = "OwlCodaRunKitTeamProjectDefinitionV1";
 const EVENT_SCHEMA = "OwlCodaRunKitTeamProjectEventV1";
 const EVENT_SCHEMA_V2 = "OwlCodaRunKitTeamProjectEventV2";
-const STATUS_SCHEMA = "OwlCodaRunKitTeamProjectStatusV1";
+const EVENT_SCHEMA_V3 = "OwlCodaRunKitTeamProjectEventV3";
+const EVENT_SCHEMA_V4 = "OwlCodaRunKitTeamProjectEventV4";
+const STATUS_SCHEMA_V1 = "OwlCodaRunKitTeamProjectStatusV1";
+const STATUS_SCHEMA_V2 = "OwlCodaRunKitTeamProjectStatusV2";
 
 const DEFINITION_KEYS = [
   "schemaVersion",
@@ -92,6 +100,30 @@ const EVENT_KEYS = Object.freeze({
     "sourceRef", "rights", "inputRef", "outputRef", "decisionRef",
     "verificationRefs", "outcomeRef", "version",
   ],
+  source_delivery_imported: [
+    "schemaVersion", "eventId", "type", "occurredAt", "deliveryId",
+    "projectId", "projectDefinitionSha256", "assignmentId", "workItemId",
+    "producerId", "targetWorkspaceRef",
+    "targetHead", "entrySnapshotRef", "entrySnapshotSha256",
+    "deliveryPacketSha256", "deliveryCandidateFingerprint",
+    "workspaceSnapshotFingerprint", "overlayStatus", "candidateFiles",
+    "changedPaths", "toolCachePaths", "dependencyEnvironmentPaths",
+    "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) {
@@ -122,6 +154,26 @@ function nullableString(value, label) {
   return nonEmptyString(value, label);
 }
 
+function sha256Ref(value, label) {
+  if (typeof value !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(value)) {
+    throw new Error(`${label} must be a canonical SHA-256 reference.`);
+  }
+  return value;
+}
+
+function safeSourcePath(value, label) {
+  if (typeof value !== "string"
+    || value.length === 0
+    || path.isAbsolute(value)
+    || path.win32.parse(value).root
+    || value.includes("\\")
+    || value.includes("\0")
+    || value.split("/").some(segment => !segment || segment === "." || segment === "..")) {
+    throw new Error(`${label} must be a safe repository-relative path.`);
+  }
+  return value;
+}
+
 function stringArray(value, label, { allowEmpty = true } = {}) {
   if (!Array.isArray(value)
     || (!allowEmpty && value.length === 0)
@@ -167,6 +219,30 @@ function withProjectLock(root, operation) {
   }
 }
 
+export function teamProjectDefinitionBindingV1(definition) {
+  const normalized = validateDefinition(definition);
+  return {
+    projectId: normalized.projectId,
+    projectDefinitionSha256: `sha256:${sha256(canonical(normalized))}`,
+  };
+}
+
+export function withTeamProjectControlLockV1({ workspaceRoot, operation }) {
+  if (typeof operation !== "function") {
+    throw new Error("Team project control operation must be a function.");
+  }
+  const loaded = loadProject(workspaceRoot);
+  return withProjectLock(loaded.projectRoot, () => {
+    const refreshed = loadProject(workspaceRoot);
+    return operation({
+      workspaceRoot: refreshed.root,
+      projectRoot: refreshed.projectRoot,
+      definition: structuredClone(refreshed.definition),
+      definitionBinding: teamProjectDefinitionBindingV1(refreshed.definition),
+    });
+  });
+}
+
 function uniqueIds(rows, label) {
   const ids = rows.map(row => safeIdentifier(row.id, `${label} id`));
   if (new Set(ids).size !== ids.length) throw new Error(`${label} ids must be unique.`);
@@ -381,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
     ? {
@@ -420,6 +512,140 @@ function reworkProjection(rework, attempt) {
     : null;
 }
 
+function sourceDeliveryProjection(delivery) {
+  return delivery
+    ? {
+        projectId: delivery.projectId,
+        projectDefinitionSha256: delivery.projectDefinitionSha256,
+        deliveryId: delivery.deliveryId,
+        workItemId: delivery.workItemId,
+        assignmentId: delivery.assignmentId,
+        producerId: delivery.producerId,
+        targetWorkspaceRef: delivery.targetWorkspaceRef,
+        targetHead: delivery.targetHead,
+        entrySnapshotRef: delivery.entrySnapshotRef,
+        entrySnapshotSha256: delivery.entrySnapshotSha256,
+        deliveryPacketSha256: delivery.deliveryPacketSha256,
+        deliveryCandidateFingerprint: delivery.deliveryCandidateFingerprint,
+        workspaceSnapshotFingerprint: delivery.workspaceSnapshotFingerprint,
+        overlayStatus: delivery.overlayStatus,
+        candidateFiles: delivery.candidateFiles.map(row => ({ ...row })),
+        candidatePaths: delivery.candidateFiles.map(row => row.path),
+        changedPaths: [...delivery.changedPaths],
+        toolCachePaths: [...delivery.toolCachePaths],
+        dependencyEnvironmentPaths: [...delivery.dependencyEnvironmentPaths],
+        unchangedPacketPaths: [...delivery.unchangedPacketPaths],
+        proven: [...delivery.proven],
+        notProven: [...delivery.notProven],
+        occurredAt: delivery.occurredAt,
+        truthRef: delivery.ref,
+        targetWritePerformed: false,
+        authorizationGranted: false,
+      }
+    : null;
+}
+
+function sourceDeliveryDelta(deliveries) {
+  const current = deliveries.at(-1) ?? null;
+  if (!current) return null;
+  const previous = deliveries.at(-2) ?? null;
+  if (!previous) {
+    return {
+      status: "first_delivery",
+      currentDeliveryId: current.deliveryId,
+      previousDeliveryId: null,
+      addedPaths: current.candidateFiles.map(row => row.path),
+      changedPaths: [],
+      removedPaths: [],
+      unchangedPaths: [],
+    };
+  }
+  const currentFiles = new Map(current.candidateFiles.map(row => [row.path, row.sha256]));
+  const previousFiles = new Map(previous.candidateFiles.map(row => [row.path, row.sha256]));
+  const allPaths = uniqueSorted([...currentFiles.keys(), ...previousFiles.keys()]);
+  const addedPaths = allPaths.filter(filePath => (
+    currentFiles.has(filePath) && !previousFiles.has(filePath)
+  ));
+  const removedPaths = allPaths.filter(filePath => (
+    !currentFiles.has(filePath) && previousFiles.has(filePath)
+  ));
+  const changedPaths = allPaths.filter(filePath => (
+    currentFiles.has(filePath)
+    && previousFiles.has(filePath)
+    && currentFiles.get(filePath) !== previousFiles.get(filePath)
+  ));
+  const unchangedPaths = allPaths.filter(filePath => (
+    currentFiles.has(filePath)
+    && previousFiles.has(filePath)
+    && currentFiles.get(filePath) === previousFiles.get(filePath)
+  ));
+  return {
+    status: addedPaths.length || removedPaths.length || changedPaths.length
+      ? "changed"
+      : "unchanged",
+    currentDeliveryId: current.deliveryId,
+    previousDeliveryId: previous.deliveryId,
+    addedPaths,
+    changedPaths,
+    removedPaths,
+    unchangedPaths,
+  };
+}
+
+function staleHandoffsForTakeover({ loaded, status, agentId, responsibilities }) {
+  const responsibilityIds = new Set(responsibilities.map(row => row.workItemId));
+  const pendingEventIds = new Set(status.workItems
+    .map(row => row.pendingHandoff?.eventId)
+    .filter(Boolean));
+  return loaded.events
+    .filter(({ event }) => (
+      event.type === "handoff_recorded"
+      && !pendingEventIds.has(event.eventId)
+      && (responsibilityIds.has(event.workItemId)
+        || event.fromAgentId === agentId
+        || event.toAgentId === agentId)
+    ))
+    .map(({ event, ref }) => {
+      const laterFacts = loaded.events.filter(row => (
+        row.event.workItemId === event.workItemId
+        && compareEventFacts(row.event, event) > 0
+        && [
+          "agent_assigned",
+          "checkpoint_recorded",
+          "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 === "upstream_reopened"
+        || row.event.type === "responsibility_transferred"
+      ))) {
+        reason = "superseded_by_assignment";
+      } else if (laterFacts.length > 0) {
+        reason = "superseded_by_later_work_fact";
+      }
+      return {
+        eventId: event.eventId,
+        truthRef: ref,
+        assignmentId: event.assignmentId,
+        workItemId: event.workItemId,
+        fromAgentId: event.fromAgentId,
+        toAgentId: event.toAgentId,
+        occurredAt: event.occurredAt,
+        reason,
+      };
+    })
+    .sort((left, right) => compareIdentifiers(left.eventId, right.eventId));
+}
+
 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)
@@ -434,14 +660,30 @@ 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].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} or ${EVENT_SCHEMA_V2}.`,
+      `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) {
     throw new Error(`rework_returned requires schemaVersion ${EVENT_SCHEMA_V2}.`);
   }
+  if (value.type === "source_delivery_imported" && value.schemaVersion !== EVENT_SCHEMA_V3) {
+    throw new Error(`source_delivery_imported requires schemaVersion ${EVENT_SCHEMA_V3}.`);
+  }
+  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));
@@ -455,6 +697,9 @@ function validateEventShape(value, definition) {
     "checkpoint_recorded",
     "handoff_recorded",
     "rework_returned",
+    "source_delivery_imported",
+    "upstream_reopened",
+    "responsibility_transferred",
     "verification_deferred",
   ].includes(value.type)) {
     assertWorkItem(value.workItemId);
@@ -464,6 +709,9 @@ function validateEventShape(value, definition) {
     "checkpoint_recorded",
     "handoff_recorded",
     "rework_returned",
+    "source_delivery_imported",
+    "upstream_reopened",
+    "responsibility_transferred",
   ].includes(value.type)) {
     safeIdentifier(value.assignmentId, "assignmentId");
   }
@@ -582,6 +830,138 @@ function validateEventShape(value, definition) {
     stringArray(value.verificationRefs, "Data candidate verificationRefs");
     nullableString(value.outcomeRef, "Data candidate outcomeRef");
     nonEmptyString(value.version, "Data candidate version");
+  } else if (value.type === "source_delivery_imported") {
+    safeIdentifier(value.projectId, "External delivery projectId");
+    sha256Ref(value.projectDefinitionSha256, "External delivery projectDefinitionSha256");
+    const definitionBinding = teamProjectDefinitionBindingV1(definition);
+    if (value.projectId !== definitionBinding.projectId
+      || value.projectDefinitionSha256 !== definitionBinding.projectDefinitionSha256) {
+      throw new Error("External delivery project identity does not match current project truth.");
+    }
+    safeIdentifier(value.deliveryId, "deliveryId");
+    safeIdentifier(value.producerId, "producerId");
+    nonEmptyString(value.targetWorkspaceRef, "External delivery targetWorkspaceRef");
+    if (!path.isAbsolute(value.targetWorkspaceRef)) {
+      throw new Error("External delivery targetWorkspaceRef must be absolute.");
+    }
+    if (typeof value.targetHead !== "string"
+      || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(value.targetHead)) {
+      throw new Error("External delivery targetHead is invalid.");
+    }
+    if ((value.entrySnapshotRef === null) !== (value.entrySnapshotSha256 === null)) {
+      throw new Error("External delivery entry snapshot ref and hash must be supplied together.");
+    }
+    if (value.entrySnapshotRef !== null) {
+      nonEmptyString(value.entrySnapshotRef, "External delivery entrySnapshotRef");
+      sha256Ref(value.entrySnapshotSha256, "External delivery entrySnapshotSha256");
+    }
+    sha256Ref(value.deliveryPacketSha256, "External delivery packet hash");
+    if (typeof value.deliveryCandidateFingerprint !== "string"
+      || !/^[a-f0-9]{64}$/u.test(value.deliveryCandidateFingerprint)) {
+      throw new Error("External delivery candidate fingerprint is invalid.");
+    }
+    sha256Ref(value.workspaceSnapshotFingerprint, "External delivery workspace snapshot fingerprint");
+    if (!["candidate_only", "attested", "attested_with_non_source_changes"].includes(value.overlayStatus)) {
+      throw new Error("External delivery overlayStatus is invalid.");
+    }
+    if (!Array.isArray(value.candidateFiles) || value.candidateFiles.length === 0) {
+      throw new Error("External delivery candidateFiles must contain at least one file.");
+    }
+    const candidateFiles = value.candidateFiles.map((row) => {
+      assertAllowedKeys(row, "External delivery candidate file", ["path", "sha256"]);
+      const filePath = safeSourcePath(row.path, "External delivery candidate file path");
+      if (typeof row.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(row.sha256)) {
+        throw new Error(`External delivery candidate file hash is invalid: ${filePath}.`);
+      }
+      return { path: filePath, sha256: row.sha256 };
+    });
+    if (new Set(candidateFiles.map(row => row.path)).size !== candidateFiles.length
+      || canonical([...candidateFiles].sort((left, right) => (
+        compareIdentifiers(left.path, right.path)
+      )))
+        !== canonical(candidateFiles)) {
+      throw new Error("External delivery candidateFiles must be uniquely sorted by path.");
+    }
+    if (canonicalSourceFingerprint(Object.fromEntries(
+      candidateFiles.map(row => [row.path, row.sha256]),
+    )) !== value.deliveryCandidateFingerprint) {
+      throw new Error("External delivery candidate fingerprint does not match its file map.");
+    }
+    for (const [field, label] of [
+      ["changedPaths", "External delivery changedPaths"],
+      ["toolCachePaths", "External delivery toolCachePaths"],
+      ["dependencyEnvironmentPaths", "External delivery dependencyEnvironmentPaths"],
+      ["unchangedPacketPaths", "External delivery unchangedPacketPaths"],
+      ["outOfScopeSourcePaths", "External delivery outOfScopeSourcePaths"],
+    ]) {
+      const paths = stringArray(value[field], label);
+      for (const filePath of paths) safeSourcePath(filePath, label);
+      if (canonical([...paths].sort()) !== canonical(paths)) {
+        throw new Error(`${label} must be sorted.`);
+      }
+    }
+    if (value.outOfScopeSourcePaths.length !== 0) {
+      throw new Error("An imported external delivery cannot contain out-of-scope source paths.");
+    }
+    stringArray(value.proven, "External delivery proven statements", { allowEmpty: false });
+    stringArray(value.notProven, "External delivery notProven statements", { allowEmpty: false });
+    if (!validWorkspaceSnapshotShape(value.targetSnapshot)
+      || !quickSnapshotFingerprintValid(value.targetSnapshot)
+      || value.targetSnapshot.sourceFingerprint !== value.workspaceSnapshotFingerprint) {
+      throw new Error("External delivery targetSnapshot identity is invalid.");
+    }
+    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);
 }
@@ -592,13 +972,20 @@ 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();
   const dataCandidates = [];
+  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);
@@ -692,6 +1079,185 @@ function projectEvents(definition, records) {
         throw new Error(`Duplicate data candidate ${event.candidateId}.`);
       }
       dataCandidates.push({ ...event, ref });
+    } else if (event.type === "source_delivery_imported") {
+      if (seenDeliveries.has(event.deliveryId)) {
+        throw new Error(`Duplicate external source delivery ${event.deliveryId}.`);
+      }
+      const current = assignments.get(event.workItemId) ?? null;
+      if (current?.assignmentId !== event.assignmentId) {
+        throw new Error(
+          `External source delivery ${event.deliveryId} does not bind the current assignment.`,
+        );
+      }
+      const currentCheckpoint = checkpoints.get(event.workItemId) ?? null;
+      if (currentCheckpoint?.assignmentId === current.assignmentId
+        && ["completed", "failed"].includes(currentCheckpoint.state)) {
+        throw new Error(
+          `External source delivery ${event.deliveryId} cannot attach to terminal WorkItem truth.`,
+        );
+      }
+      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 {
@@ -700,10 +1266,13 @@ function projectEvents(definition, records) {
     checkpoints,
     handoffs,
     reworks,
+    reopens,
+    transfers,
     decisions,
     gatePasses,
     verifications,
     dataCandidates,
+    sourceDeliveries,
   };
 }
 
@@ -1020,25 +1589,79 @@ 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;
     const handoff = state.handoffs.get(item.id) ?? null;
     const rework = state.reworks.get(item.id) ?? null;
+    const sourceDeliveries = state.sourceDeliveries.filter(row => row.workItemId === item.id);
+    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
       ? handoff
       : null;
-    const pendingHandoff = activeHandoff && latestFact?.eventId === activeHandoff.eventId
+    const latestHandoffFact = latestEventFact(activeHandoff, latestSourceDeliveryFact);
+    const handoffSupersededByDelivery = activeHandoff
+      && latestFact?.eventId === activeHandoff.eventId
+      && latestHandoffFact?.eventId !== activeHandoff.eventId;
+    const projectedFact = handoffSupersededByDelivery
+      ? [effectiveCheckpoint, currentRework, currentReopen, currentTransfer]
+        .reduce((latest, fact) => latestEventFact(latest, fact), null)
+      : latestFact;
+    const pendingHandoff = activeHandoff
+      && latestFact?.eventId === activeHandoff.eventId
+      && latestHandoffFact?.eventId === activeHandoff.eventId
       ? pendingHandoffProjection(activeHandoff)
       : null;
     const executionTruth = executionTruthFor(workspaceRoot, assignment);
@@ -1046,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 (latestFact?.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"))) {
@@ -1056,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" };
@@ -1075,6 +1702,9 @@ 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(
       currentRework,
@@ -1082,9 +1712,13 @@ function projectStatus(definition, records, workspaceRoot = null) {
         ? assignmentEvents.findIndex(row => row.assignmentId === currentRework.assignmentId) + 1
         : null,
     );
-    const latestSummary = latestFact?.type === "rework_returned"
-      ? latestFact.reason
-      : latestFact?.summary ?? null;
+    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,
@@ -1098,19 +1732,23 @@ function projectStatus(definition, records, workspaceRoot = null) {
       executionTruth,
       dependencies: [...item.dependencies],
       unresolvedDependencies,
-      blockers: latestFact?.type === "checkpoint_recorded"
-        ? checkpoint.blockerRefs
+      blockers: checkpointLikeFact
+        ? checkpointLikeFact.blockerRefs
         : unresolvedDependencies.map(id => `work-item:${id}`),
-      decisionRefs: latestFact?.type === "checkpoint_recorded" ? checkpoint.decisionRefs : [],
+      decisionRefs: checkpointLikeFact ? checkpointLikeFact.decisionRefs : [],
       progress: measured,
       summary: latestSummary,
-      nextAction: latestFact?.nextAction ?? null,
+      nextAction: projectedFact?.nextAction ?? null,
       pendingHandoff,
       rework: projectedRework,
+      latestSourceDelivery,
       lastCheckpointAt: checkpoint?.occurredAt ?? null,
-      evidenceRefs: latestFact?.evidenceRefs ?? [],
+      evidenceRefs: projectedFact?.evidenceRefs ?? [],
       assignmentHistory: history,
       truthRefs,
+      ...(reopenFacts.length === 0
+        ? {}
+        : { invalidatedByReopenIds: invalidatingReopens.map(row => row.reopenId) }),
     };
   });
   const openDecisions = [...state.decisions.values()]
@@ -1311,6 +1949,7 @@ function projectStatus(definition, records, workspaceRoot = null) {
       truthRefs: [row.ref],
     };
   });
+  const sourceDeliveries = state.sourceDeliveries.map(sourceDeliveryProjection);
   let overall = "planned";
   if (workItems.every(row => row.status === "completed")
     && integrationGates.every(row => row.status === "passed")
@@ -1318,7 +1957,7 @@ function projectStatus(definition, records, workspaceRoot = null) {
   else if (openDecisions.length > 0 || workItems.some(row => row.status === "failed")) overall = "active_with_blockers";
   else if (workItems.some(row => row.status !== "planned" || row.pendingHandoff !== null)) overall = "active";
   const status = {
-    schemaVersion: STATUS_SCHEMA,
+    schemaVersion: STATUS_SCHEMA_V2,
     status: "team_project_status",
     projectId: definition.projectId,
     objective: definition.objective,
@@ -1336,6 +1975,7 @@ function projectStatus(definition, records, workspaceRoot = null) {
     openDeferredVerificationIds,
     integrationGates,
     dataCandidates,
+    sourceDeliveries,
     projectTruthHash: sha256(canonical({ definition, events: records.map(row => row.event) })),
     authorizationGranted: false,
   };
@@ -1474,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") {
@@ -1513,6 +2248,18 @@ function validateEventAgainstState(event, definition, records, workspaceRoot) {
     if (state.dataCandidates.some(row => row.candidateId === normalized.candidateId)) {
       throw new Error(`Data candidate ${normalized.candidateId} already exists.`);
     }
+  } else if (normalized.type === "source_delivery_imported") {
+    if (state.sourceDeliveries.some(row => row.deliveryId === normalized.deliveryId)) {
+      throw new Error(`External source delivery ${normalized.deliveryId} already exists.`);
+    }
+    const current = state.assignments.get(normalized.workItemId) ?? null;
+    if (current?.assignmentId !== normalized.assignmentId) {
+      throw new Error("External source delivery must bind the current assignment.");
+    }
+    const projected = status.workItems.find(row => row.workItemId === normalized.workItemId);
+    if (["completed", "failed"].includes(projected?.status)) {
+      throw new Error("External source delivery requires a non-terminal WorkItem.");
+    }
   }
   return normalized;
 }
@@ -1849,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,
@@ -2155,7 +3101,32 @@ export function checkpointTeamProjectV1({
   };
 }
 
+function legacyWorkItemProjection(workItem) {
+  if (workItem === null) return null;
+  const {
+    latestSourceDelivery: _latestSourceDelivery,
+    invalidatedByReopenIds: _invalidatedByReopenIds,
+    ...legacy
+  } = workItem;
+  return legacy;
+}
+
 export function readTeamProjectStatusV1({ workspaceRoot }) {
+  const loaded = loadProject(workspaceRoot);
+  const { sourceDeliveries: _sourceDeliveries, ...legacy } = projectStatus(
+    loaded.definition,
+    loaded.events,
+    loaded.root,
+  );
+  return {
+    ...legacy,
+    schemaVersion: STATUS_SCHEMA_V1,
+    workItems: legacy.workItems.map(legacyWorkItemProjection),
+    exitCode: 0,
+  };
+}
+
+export function readTeamProjectStatusV2({ workspaceRoot }) {
   const loaded = loadProject(workspaceRoot);
   return {
     ...projectStatus(loaded.definition, loaded.events, loaded.root),
@@ -2163,7 +3134,77 @@ export function readTeamProjectStatusV1({ workspaceRoot }) {
   };
 }
 
-export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
+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);
   const status = projectStatus(loaded.definition, loaded.events, loaded.root);
@@ -2180,6 +3221,29 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
     row.pendingHandoff?.toAgentId === agentId
   ))?.pendingHandoff ?? null;
   const pendingHandoff = pendingForCurrent ?? pendingForAgent;
+  const staleHandoffs = staleHandoffsForTakeover({
+    loaded,
+    status,
+    agentId,
+    responsibilities,
+  });
+  const latestStaleHandoff = [...staleHandoffs]
+    .sort(compareEventFacts)
+    .at(-1) ?? null;
+  const focusResponsibility = current
+    ?? (pendingHandoff
+      ? status.workItems.find(row => row.workItemId === pendingHandoff.workItemId) ?? null
+      : null)
+    ?? (latestStaleHandoff
+      ? status.workItems.find(row => row.workItemId === latestStaleHandoff.workItemId) ?? null
+      : null);
+  const focusedDeliveries = focusResponsibility
+    ? status.sourceDeliveries.filter(row => (
+        row.workItemId === focusResponsibility.workItemId
+      ))
+    : [];
+  const currentSourceDelivery = focusedDeliveries.at(-1) ?? null;
+  const deliveryDelta = sourceDeliveryDelta(focusedDeliveries);
   const checkpoints = loaded.events
     .filter(row => row.event.type === "checkpoint_recorded"
       && responsibilities.some(item => item.workItemId === row.event.workItemId))
@@ -2189,6 +3253,9 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
     ...(lastCheckpoint?.evidenceRefs ?? []),
     ...(current?.evidenceRefs ?? []),
     ...(pendingHandoff?.evidenceRefs ?? []),
+    ...(currentSourceDelivery ? [currentSourceDelivery.truthRef] : []),
+    ...(deliveryDelta?.previousDeliveryId ? [focusedDeliveries.at(-2).truthRef] : []),
+    ...staleHandoffs.map(row => row.truthRef),
   ])].sort();
   const unresolvedDecisionsById = new Map();
   for (const decision of status.openDecisions) {
@@ -2230,7 +3297,7 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
       : current ? null : status.readyQueue[0] ? `Take ${status.readyQueue[0]}.` : null;
   }
   return {
-    schemaVersion: "OwlCodaRunKitTeamProjectTakeoverV1",
+    schemaVersion: "OwlCodaRunKitTeamProjectTakeoverV2",
     status: "team_project_takeover",
     projectId: status.projectId,
     objective: status.objective,
@@ -2243,6 +3310,9 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
     currentResponsibility: current,
     allResponsibilities: responsibilities,
     pendingHandoff,
+    staleHandoffs,
+    currentSourceDelivery,
+    sourceDeliveryDelta: deliveryDelta,
     lastAcceptedCheckpoint: lastCheckpoint
       ? {
           workItemId: lastCheckpoint.workItemId,
@@ -2265,6 +3335,27 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
   };
 }
 
+export function buildTeamProjectTakeoverV1(input) {
+  const {
+    staleHandoffs: _staleHandoffs,
+    currentSourceDelivery: _currentSourceDelivery,
+    sourceDeliveryDelta: _sourceDeliveryDelta,
+    ...legacy
+  } = buildTeamProjectTakeoverV2(input);
+  const v2OnlyEvidenceRefs = new Set([
+    ..._staleHandoffs.map(row => row.truthRef),
+    ...readTeamProjectStatusV2({ workspaceRoot: input.workspaceRoot })
+      .sourceDeliveries.map(row => row.truthRef),
+  ]);
+  return {
+    ...legacy,
+    schemaVersion: "OwlCodaRunKitTeamProjectTakeoverV1",
+    currentResponsibility: legacyWorkItemProjection(legacy.currentResponsibility),
+    allResponsibilities: legacy.allResponsibilities.map(legacyWorkItemProjection),
+    evidenceRefs: legacy.evidenceRefs.filter(ref => !v2OnlyEvidenceRefs.has(ref)),
+  };
+}
+
 export function formatTeamProjectStatusHumanV1(status) {
   const nextAction = status.nextAction === null ? "none" : singleLine(status.nextAction);
   return [
@@ -2285,6 +3376,65 @@ export function formatTeamProjectStatusHumanV1(status) {
   ].join("\n");
 }
 
+export function formatTeamProjectStatusHumanV2(status) {
+  const nextAction = status.nextAction === null ? "none" : singleLine(status.nextAction);
+  const latestSourceDelivery = status.sourceDeliveries.at(-1) ?? null;
+  return [
+    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`,
+    `Agents: ${status.agents.map(agent => agent.agentId).join(", ") || "none assigned"}`,
+    `Open decisions: ${status.openDecisions.map(row => row.decisionId).join(", ") || "none"}`,
+    `Deferred verification: ${status.openDeferredVerificationIds.length} open${
+      status.openDeferredVerificationIds.length > 0
+        ? ` (${status.openDeferredVerificationIds.join(", ")})`
+        : ""
+    }`,
+    `Ready queue: ${status.readyQueue.join(", ") || "none"}`,
+    `Source deliveries: ${status.sourceDeliveries.length}${latestSourceDelivery
+      ? `; latest ${latestSourceDelivery.deliveryId} (${latestSourceDelivery.overlayStatus}, ${latestSourceDelivery.deliveryCandidateFingerprint})`
+      : ""}`,
+    `Next: ${nextAction}${status.nextActorId ? ` (owner ${status.nextActorId})` : ""}`,
+    "",
+  ].join("\n");
+}
+
+export function formatTeamProjectTakeoverHumanV2(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"}`,
+    `Handoffs: pending ${takeover.pendingHandoff
+      ? `${takeover.pendingHandoff.fromAgentId} -> ${takeover.pendingHandoff.toAgentId} for ${takeover.pendingHandoff.workItemId}`
+      : "none"}; stale ${takeover.staleHandoffs.length > 0
+      ? takeover.staleHandoffs.map(row => `${row.eventId} (${row.reason})`).join(", ")
+      : "none"}`,
+    `Candidate: ${takeover.currentSourceDelivery
+      ? `${takeover.currentSourceDelivery.deliveryId} (${takeover.currentSourceDelivery.overlayStatus}, ${takeover.currentSourceDelivery.deliveryCandidateFingerprint})`
+      : "none"}; delta ${takeover.sourceDeliveryDelta === null
+      ? "none"
+      : takeover.sourceDeliveryDelta.previousDeliveryId === null
+        ? `first delivery; added ${takeover.sourceDeliveryDelta.addedPaths.length}`
+        : `vs ${takeover.sourceDeliveryDelta.previousDeliveryId}; added ${takeover.sourceDeliveryDelta.addedPaths.length}, changed ${takeover.sourceDeliveryDelta.changedPaths.length}, removed ${takeover.sourceDeliveryDelta.removedPaths.length}, unchanged ${takeover.sourceDeliveryDelta.unchangedPaths.length}`}`,
+    `Agent next: ${agentNextAction}`,
+    `Project next: ${projectNextAction}${takeover.projectNextActorId ? ` (owner ${takeover.projectNextActorId})` : ""}`,
+    `State: ${takeover.overall}`,
+    "",
+  ].join("\n");
+}
+
 export function formatTeamProjectTakeoverHumanV1(takeover) {
   const responsibility = takeover.currentResponsibility;
   const agentNextAction = takeover.nextAction === null