owlrunkit 0.18.3 → 0.18.4

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,9 @@ 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 STATUS_SCHEMA_V1 = "OwlCodaRunKitTeamProjectStatusV1";
+const STATUS_SCHEMA_V2 = "OwlCodaRunKitTeamProjectStatusV2";
 
 const DEFINITION_KEYS = [
   "schemaVersion",
@@ -92,6 +99,17 @@ 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",
+  ],
 });
 
 function canonical(value) {
@@ -122,6 +140,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 +205,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.`);
@@ -420,6 +482,135 @@ 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",
+        ].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"
+      ))) {
+        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 +625,20 @@ 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].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}, or ${EVENT_SCHEMA_V3}.`,
     );
   }
   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.`);
+  }
   safeIdentifier(value.eventId, "eventId");
   validateTimestamp(value.occurredAt);
   const workItemIds = new Set(definition.workItems.map(row => row.id));
@@ -455,6 +652,7 @@ function validateEventShape(value, definition) {
     "checkpoint_recorded",
     "handoff_recorded",
     "rework_returned",
+    "source_delivery_imported",
     "verification_deferred",
   ].includes(value.type)) {
     assertWorkItem(value.workItemId);
@@ -464,6 +662,7 @@ function validateEventShape(value, definition) {
     "checkpoint_recorded",
     "handoff_recorded",
     "rework_returned",
+    "source_delivery_imported",
   ].includes(value.type)) {
     safeIdentifier(value.assignmentId, "assignmentId");
   }
@@ -582,6 +781,89 @@ 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.");
+    }
   }
   return structuredClone(value);
 }
@@ -596,9 +878,11 @@ function projectEvents(definition, records) {
   const gatePasses = new Map();
   const verifications = new Map();
   const dataCandidates = [];
+  const sourceDeliveries = [];
   const seenAssignments = new Set();
   const seenReworks = new Set();
   const seenDecisions = new Set();
+  const seenDeliveries = new Set();
 
   for (const { event, ref } of records) {
     validateEventShape(event, definition);
@@ -692,6 +976,25 @@ 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 });
     }
   }
   return {
@@ -704,6 +1007,7 @@ function projectEvents(definition, records) {
     gatePasses,
     verifications,
     dataCandidates,
+    sourceDeliveries,
   };
 }
 
@@ -1031,6 +1335,9 @@ function projectStatus(definition, records, workspaceRoot = 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 activeHandoff = handoff
@@ -1038,7 +1345,16 @@ function projectStatus(definition, records, workspaceRoot = null) {
       && 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
+      ? latestEventFact(checkpoint, currentRework)
+      : latestFact;
+    const pendingHandoff = activeHandoff
+      && latestFact?.eventId === activeHandoff.eventId
+      && latestHandoffFact?.eventId === activeHandoff.eventId
       ? pendingHandoffProjection(activeHandoff)
       : null;
     const executionTruth = executionTruthFor(workspaceRoot, assignment);
@@ -1046,7 +1362,7 @@ 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 = checkpoint.state;
     if (executionTruth && (executionTruth.status !== "bound"
       || (executionTruth.lifecycle === "closed"
         && executionTruth.closeoutDecision !== "accepted"))) {
@@ -1075,6 +1391,7 @@ function projectStatus(definition, records, workspaceRoot = null) {
       ...(checkpoint ? [checkpoint.ref] : []),
       ...(handoff ? [handoff.ref] : []),
       ...(rework ? [rework.ref] : []),
+      ...sourceDeliveries.map(row => row.ref),
     ];
     const projectedRework = reworkProjection(
       currentRework,
@@ -1082,9 +1399,9 @@ 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 = projectedFact?.type === "rework_returned"
+      ? projectedFact.reason
+      : projectedFact?.summary ?? null;
     return {
       workItemId: item.id,
       title: item.title,
@@ -1098,17 +1415,18 @@ function projectStatus(definition, records, workspaceRoot = null) {
       executionTruth,
       dependencies: [...item.dependencies],
       unresolvedDependencies,
-      blockers: latestFact?.type === "checkpoint_recorded"
+      blockers: projectedFact?.type === "checkpoint_recorded"
         ? checkpoint.blockerRefs
         : unresolvedDependencies.map(id => `work-item:${id}`),
-      decisionRefs: latestFact?.type === "checkpoint_recorded" ? checkpoint.decisionRefs : [],
+      decisionRefs: projectedFact?.type === "checkpoint_recorded" ? checkpoint.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,
     };
@@ -1311,6 +1629,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 +1637,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 +1655,7 @@ function projectStatus(definition, records, workspaceRoot = null) {
     openDeferredVerificationIds,
     integrationGates,
     dataCandidates,
+    sourceDeliveries,
     projectTruthHash: sha256(canonical({ definition, events: records.map(row => row.event) })),
     authorizationGranted: false,
   };
@@ -1513,6 +1833,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;
 }
@@ -2155,7 +2487,28 @@ export function checkpointTeamProjectV1({
   };
 }
 
+function legacyWorkItemProjection(workItem) {
+  if (workItem === null) return null;
+  const { latestSourceDelivery: _latestSourceDelivery, ...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 +2516,7 @@ export function readTeamProjectStatusV1({ workspaceRoot }) {
   };
 }
 
-export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
+export function buildTeamProjectTakeoverV2({ workspaceRoot, agentId }) {
   safeIdentifier(agentId, "agentId");
   const loaded = loadProject(workspaceRoot);
   const status = projectStatus(loaded.definition, loaded.events, loaded.root);
@@ -2180,6 +2533,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 +2565,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 +2609,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 +2622,9 @@ export function buildTeamProjectTakeoverV1({ workspaceRoot, agentId }) {
     currentResponsibility: current,
     allResponsibilities: responsibilities,
     pendingHandoff,
+    staleHandoffs,
+    currentSourceDelivery,
+    sourceDeliveryDelta: deliveryDelta,
     lastAcceptedCheckpoint: lastCheckpoint
       ? {
           workItemId: lastCheckpoint.workItemId,
@@ -2265,6 +2647,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 +2688,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