@cassiomc1/forgeloop 1.9.0 → 1.10.1

package/src/core/events.js

@@ -11,7 +11,7 @@ import { PROTOCOL_VERSION } from "./protocol.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 
 import { taskArtifactPath } from "./task-paths.js";
-import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 import { assertDiagnosisDetails } from "./diagnosis-model.js";
 import {
@@ -160,6 +160,16 @@ export function validateKnownEventDetails(event) {
       }
       assertFingerprint(event.details.digest, "HANDOFF_CREATED details.digest");
       return;
+    case "HANDOFF_ACCEPTED":
+      if (!event.details || typeof event.details !== "object" || Array.isArray(event.details)
+        || typeof event.details.handoffId !== "string" || !/^handoff-[A-Za-z0-9_-]+$/.test(event.details.handoffId)
+        || typeof event.details.handoffDigest !== "string"
+        || typeof event.details.consumerId !== "string" || !event.details.consumerId.trim()
+        || (event.details.harness !== undefined && (typeof event.details.harness !== "string" || !event.details.harness.trim()))) {
+        throw protocolError("E_EVENT_INVALID", "HANDOFF_ACCEPTED requires a valid handoffId, handoffDigest, and consumerId");
+      }
+      assertFingerprint(event.details.handoffDigest, "HANDOFF_ACCEPTED details.handoffDigest");
+      return;
     case "RESPONSIBILITY_SET":
       assertStructuredArtifactEvent(event, ["responsibilityFingerprint"], "RESPONSIBILITY_SET");
       if (typeof event.details.label !== "string" || !event.details.label) {
@@ -301,7 +311,7 @@ export function buildProtocolEvent(input, { checkpoint } = {}) {
 }
 
 export async function previewProtocolEvent(target, input, packageRoot, options = {}) {
-  const activeTransaction = getActiveTaskTransaction();
+  const activeTransaction = (await getTaskTransaction(target));
   if (!activeTransaction) {
     return withTaskTransaction({
       target,
@@ -327,7 +337,7 @@ export async function readEvents(target, packageRoot, options = {}) {
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   await assertSafePath(target, relPath);
   const eventsPath = ensureWithin(target, relPath);
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   if (transaction) {
     const stagedText = await transaction.readText(relPath);
     if (stagedText !== null) return parseEventsText(stagedText, relPath, packageRoot);
@@ -345,7 +355,7 @@ export async function readEventTail(target, packageRoot, options = {}) {
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   await assertSafePath(target, relPath);
   const eventsPath = ensureWithin(target, relPath);
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   if (transaction) {
     const stagedText = await transaction.readText(relPath);
     if (stagedText !== null) {
@@ -401,7 +411,7 @@ async function parseEventsText(text, relPath, packageRoot) {
 }
 
 export async function appendProtocolEvent(target, input, packageRoot, options = {}) {
-  const activeTransaction = getActiveTaskTransaction();
+  const activeTransaction = (await getTaskTransaction(target));
   if (typeof input?.taskId !== "string" || !input.taskId) throw protocolError("E_EVENT_INVALID", "event taskId is required");
   if (typeof input?.event !== "string" || !input.event) throw protocolError("E_EVENT_INVALID", "event type is required");
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
@@ -513,6 +523,8 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
   const seen = new Set();
   let lastMilestone = -1;
   const milestoneCounts = new Map();
+  const createdHandoffs = new Map();
+  const acceptedHandoffs = new Set();
   for (const [index, event] of events.entries()) {
     if (event.seq !== index + 1) {
       errors.push({ code: "E_EVENT_INVALID", message: `event sequence must be ${index + 1}` });
@@ -584,6 +596,26 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
     if (event.event === "COMPLETION_REJECTED" && !seen.has("VERIFICATION_STARTED")) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion rejected before verification started" });
     }
+    if (event.event === "HANDOFF_CREATED") {
+      if (event.details?.handoffId) {
+        createdHandoffs.set(event.details.handoffId, event.details.digest);
+      }
+    }
+    if (event.event === "HANDOFF_ACCEPTED") {
+      const hId = event.details?.handoffId;
+      if (hId) {
+        if (acceptedHandoffs.has(hId)) {
+          errors.push({ code: "E_HANDOFF_ALREADY_ACCEPTED", message: `duplicate HANDOFF_ACCEPTED for handoffId ${hId}` });
+        } else {
+          acceptedHandoffs.add(hId);
+          if (!createdHandoffs.has(hId)) {
+            errors.push({ code: "E_HANDOFF_ACCEPTANCE_INCONSISTENT", message: `HANDOFF_ACCEPTED has no preceding HANDOFF_CREATED for handoffId ${hId}` });
+          } else if (createdHandoffs.get(hId) !== event.details?.handoffDigest) {
+            errors.push({ code: "E_HANDOFF_ACCEPTANCE_INCONSISTENT", message: `HANDOFF_ACCEPTED digest mismatch for handoffId ${hId}` });
+          }
+        }
+      }
+    }
   }
   validateLegacyRecoveryMigrations(events, errors, {
     allowUnmigratedLegacyRecoveryEvents: options?.allowUnmigratedLegacyRecoveryEvents === true,

package/src/core/execution-profile-context.js

@@ -112,6 +112,7 @@ export function projectExecutionProfileContext({
   route,
   state,
   nextAction,
+  runtimeContext,
 } = {}) {
   if (typeof taskId !== "string" || !taskId) throw contextError("E_TASK_REQUIRED", "taskId is required");
   if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
@@ -126,6 +127,18 @@ export function projectExecutionProfileContext({
   const profile = route.executionProfile ? assertExecutionProfile(route.executionProfile) : legacyExecutionProfile();
   const resolvedProfile = profile.resolved;
   const policy = getExecutionProfileContextPolicy(resolvedProfile);
+  const available = [...OPTIONAL_CONTEXT_BY_PROFILE[resolvedProfile]];
+  const advisoryProviders = runtimeContext?.advisoryContextProviders;
+  const hasAdvisory = Boolean(
+    advisoryProviders && (
+      advisoryProviders instanceof Map
+        ? advisoryProviders.size > 0
+        : Object.keys(advisoryProviders).length > 0
+    ),
+  );
+  if (hasAdvisory && !available.includes("advisory-context")) {
+    available.push("advisory-context");
+  }
   return {
     schemaVersion: 1,
     protocolVersion: 1,
@@ -140,7 +153,7 @@ export function projectExecutionProfileContext({
     verificationRequirements: verificationRequirements(contract),
     contextPolicy: policy,
     optionalContext: {
-      available: [...OPTIONAL_CONTEXT_BY_PROFILE[resolvedProfile]],
+      available,
       loaded: [],
     },
     invariants: { ...PROFILE_INVARIANTS },
@@ -173,5 +186,6 @@ export async function buildExecutionProfileContext({
     route: routeArtifact.value,
     state,
     nextAction,
+    runtimeContext,
   });
 }

package/src/core/execution-profile.js

@@ -66,24 +66,37 @@ function contractCollections(contract) {
 
 function contractSignals(contract) {
   const collections = contractCollections(contract);
+  const obligations = [];
+  const types = new Set();
+  function collect(requirement) {
+    if (typeof requirement === "string") obligations.push(requirement);
+    else if (requirement && typeof requirement === "object") {
+      if (typeof requirement.text === "string") obligations.push(requirement.text);
+      types.add(requirement.type);
+      if (Array.isArray(requirement.requirements)) requirement.requirements.forEach(collect);
+    }
+  }
+  collections.successCriteria.forEach(collect);
+  if (Array.isArray(contract?.verification)) contract.verification.forEach(collect);
   const riskText = collections.risks.join(" ").toLowerCase();
+  // Constraints and stop conditions describe boundaries, not obligations.
+  // Declared route risks remain authoritative even when a constraint excludes
+  // an operation; do not try to interpret prose negation as authorization.
   const allText = [
     ...collections.deliverables,
-    ...collections.successCriteria,
-    ...collections.constraints,
-    ...collections.stopConditions,
+    ...obligations,
   ].join(" ").toLowerCase();
   const combinedText = `${riskText} ${allText}`;
   const signals = {
     secrets: /\bsecrets?\b|\bcredentials?\b|\bpasswords?\b|\bprivate keys?\b/.test(combinedText),
     personalData: /\bpersonal[- ]data\b|\bpii\b|\bsensitive data\b/.test(combinedText),
-    publication: /\bpublication\b|\bpublish(?:ing|ed)?\b|\bdeploy(?:ment|ed)?\b/.test(combinedText),
+    publication: types.has("PUBLICATION") || /\bpublication\b|\bpublish(?:ing|ed)?\b|\bdeploy(?:ment|ed)?\b/.test(combinedText),
     destructive: /\bdestructive\b|\birreversible\b|\bdrop database\b|\bdelete production\b/.test(combinedText),
     migration: /\bmigration\b|\bmigrate\b|\bschema change\b|\birreversible persistence\b/.test(combinedText),
     payment: /\bpayments?\b|\bcheckout\b|\bbilling\b/.test(combinedText),
     externalMutation: /\bexternal mutation\b|\bmutate(?:s|d)? external\b|\bpublish(?:ing|ed)?\b/.test(combinedText),
     authoritySensitiveExternalMutation: /\bauthority[- ]sensitive\b|\bhost[- ]authorized external\b|\bexternal mutation requiring authority\b/.test(combinedText),
-    broadProductionValidation: /\bbroad production validation\b|\bproduction validation\b|\bvalidate in production\b/.test(combinedText),
+    broadProductionValidation: types.has("PRODUCTION_READINESS") || /\bbroad production validation\b|\bproduction validation\b|\bvalidate in production\b/.test(combinedText),
   };
   return signals;
 }

package/src/core/filesystem.js

@@ -73,11 +73,27 @@ export function ensureWithin(root, relativePath) {
   return path.join(root, normalized);
 }
 
+function normalizeWindowsPathForComparison(value) {
+  const lowerValue = value.toLowerCase();
+  let normalized = value;
+  if (lowerValue.startsWith("\\\\?\\unc\\")) {
+    normalized = `\\\\${value.slice(8)}`;
+  } else if (lowerValue.startsWith("\\\\.\\unc\\")) {
+    normalized = `\\\\${value.slice(8)}`;
+  } else if (lowerValue.startsWith("\\\\?\\")) {
+    normalized = value.slice(4);
+  } else if (lowerValue.startsWith("\\\\.\\")) {
+    normalized = value.slice(4);
+  }
+  return path.win32.normalize(normalized).toLowerCase();
+}
+
 export function isPathWithin(root, candidate, { platform = process.platform } = {}) {
   const pathApi = platform === "win32" ? path.win32 : path;
   const normalizeForComparison = (value) => {
-    const normalized = pathApi.normalize(value);
-    return platform === "win32" ? normalized.toLowerCase() : normalized;
+    return platform === "win32"
+      ? normalizeWindowsPathForComparison(value)
+      : pathApi.normalize(value);
   };
   const relative = pathApi.relative(
     normalizeForComparison(root),

package/src/core/handoff-acceptance.js

@@ -0,0 +1,277 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { assertStateIdentity } from "./completion-relationships.js";
+import { compareRepositoryFingerprint, readCanonicalHandoff } from "./handoff.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "./repository.js";
+import { withTaskTransaction } from "./transaction.js";
+import { getPackageRoot } from "./templates.js";
+import {
+  normalizePortableText,
+  assertPortableContextSafe,
+} from "./portable-context.js";
+import {
+  E_HANDOFF_ACCEPTANCE_UNBOUND,
+  E_HANDOFF_STALE,
+  E_HANDOFF_ALREADY_ACCEPTED,
+  E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+} from "./error-codes.js";
+
+function acceptanceError(code, message) {
+  const error = new Error(message);
+  error.name = "HandoffAcceptanceError";
+  error.code = code;
+  return error;
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+export function resolveHandoffAcceptance(input = {}, legacyHandoff) {
+  const projection = Array.isArray(input)
+    ? { events: input, handoff: legacyHandoff }
+    : input;
+  const {
+    events = [],
+    handoff,
+    ledgerValid = true,
+    ledgerErrors = [],
+  } = projection ?? {};
+
+  if (ledgerValid !== true) {
+    return {
+      status: "INCONSISTENT",
+      reasonCodes: uniqueSorted(ledgerErrors.map((error) => typeof error === "string" ? error : error?.code)),
+    };
+  }
+
+  if (!handoff?.state?.workStateFingerprint) {
+    return { status: "UNBOUND" };
+  }
+
+  const acceptedEvents = (events ?? []).filter(
+    (e) => e.event === "HANDOFF_ACCEPTED" && e.details?.handoffId === handoff.handoffId,
+  );
+
+  if (acceptedEvents.length === 0) {
+    return { status: "OPEN" };
+  }
+
+  if (acceptedEvents.length > 1) {
+    return { status: "INCONSISTENT" };
+  }
+
+  const accepted = acceptedEvents[0];
+  if (accepted.details?.handoffDigest !== handoff.artifactDigest) {
+    return { status: "INCONSISTENT" };
+  }
+
+  return {
+    status: "ACCEPTED",
+    consumerId: accepted.details?.consumerId,
+    ...(accepted.details?.harness ? { harness: accepted.details.harness } : {}),
+    acceptedAt: accepted.at,
+  };
+}
+
+export async function readHandoffAcceptanceLedger(target, packageRoot = getPackageRoot(), { taskId } = {}) {
+  try {
+    return await validateEventLedger(target, packageRoot, { taskId });
+  } catch (error) {
+    return {
+      valid: false,
+      events: [],
+      errors: [{
+        code: error.code ?? "E_EVENT_INVALID",
+        message: error.message,
+      }],
+    };
+  }
+}
+
+export async function acceptCanonicalHandoff(target, {
+  taskId,
+  handoffId,
+  consumerId,
+  harness,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  if (!target || typeof target !== "string") {
+    throw acceptanceError("E_TARGET_REQUIRED", "target path is required");
+  }
+  if (!taskId || typeof taskId !== "string") {
+    throw acceptanceError("E_TASK_REQUIRED", "taskId is required");
+  }
+  if (!handoffId || typeof handoffId !== "string") {
+    throw acceptanceError("E_HANDOFF_INVALID", "handoffId is required");
+  }
+
+  const normalizedConsumerId = normalizePortableText(consumerId, {
+    label: "consumerId",
+    maxLength: 128,
+  });
+  assertPortableContextSafe(normalizedConsumerId, { label: "consumerId" });
+
+  const normalizedHarness = harness !== undefined
+    ? normalizePortableText(harness, {
+      label: "harness",
+      maxLength: 64,
+      optional: true,
+    })
+    : null;
+  if (normalizedHarness) {
+    assertPortableContextSafe(normalizedHarness, { label: "harness" });
+  }
+
+  return withTaskTransaction(
+    {
+      target,
+      taskId,
+      packageRoot,
+      operation: "handoff-accept",
+      recordCommitEvent: true,
+    },
+    async () => {
+      const { value: handoff } = await readCanonicalHandoff(target, {
+        taskId,
+        handoffId,
+        packageRoot,
+      });
+
+      if (!handoff.state?.workStateFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_UNBOUND,
+          "Handoff snapshot is unbound (lacks state.workStateFingerprint); create a fresh handoff",
+        );
+      }
+
+      const currentState = await readWorkState(target, { packageRoot, taskId });
+      if (!currentState) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Canonical work state is unavailable for handoff acceptance",
+        );
+      }
+
+      const currentWorkStateFingerprint = canonicalFingerprint(currentState);
+      if (currentWorkStateFingerprint !== handoff.state.workStateFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current work state has drifted from handoff workStateFingerprint",
+        );
+      }
+
+      const contract = await readContract(target, packageRoot, { taskId });
+      const route = await readPersistedRoute(target, packageRoot, { taskId });
+      try {
+        assertStateIdentity({ contract, route, state: currentState });
+      } catch (error) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          `Current canonical task artifacts are not coherent with one another: ${error.message}`,
+        );
+      }
+      if (contract.fingerprint !== handoff.state.contractFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current contract fingerprint has drifted from handoff contractFingerprint",
+        );
+      }
+      if ((route.fingerprint ?? null) !== (handoff.state.routeFingerprint ?? null)) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current route fingerprint has drifted from handoff routeFingerprint",
+        );
+      }
+
+      const repositoryFingerprint = await currentRepositoryFingerprint(target);
+      if (compareRepositoryFingerprint(handoff.state.repositoryFingerprint, repositoryFingerprint) === "MISMATCH") {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current repository branch or HEAD has drifted from handoff snapshot",
+        );
+      }
+
+      const changedPaths = await currentChangedPaths(target);
+      const currentList = [...new Set((changedPaths ?? []).map((p) => p.replaceAll("\\", "/")))].sort();
+      const handoffList = [...new Set((handoff.state.changedPaths ?? []).map((p) => p.replaceAll("\\", "/")))].sort();
+      if (JSON.stringify(currentList) !== JSON.stringify(handoffList)) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current changed paths have drifted from handoff snapshot",
+        );
+      }
+
+      const ledgerResult = await validateEventLedger(target, packageRoot, { taskId });
+      if (!ledgerResult.valid) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+          "Task event ledger is invalid",
+        );
+      }
+
+      const events = ledgerResult.events;
+      const createdEvent = events.find(
+        (e) => e.event === "HANDOFF_CREATED" && e.details?.handoffId === handoffId,
+      );
+      if (!createdEvent || createdEvent.details?.digest !== handoff.artifactDigest) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+          "No matching HANDOFF_CREATED event with matching digest found in ledger",
+        );
+      }
+
+      const existingAccepted = events.filter(
+        (e) => e.event === "HANDOFF_ACCEPTED" && e.details?.handoffId === handoffId,
+      );
+
+      if (existingAccepted.length > 0) {
+        const prev = existingAccepted[0];
+        if (prev.details?.consumerId === normalizedConsumerId) {
+          return {
+            accepted: true,
+            idempotent: true,
+            handoffId,
+            consumerId: normalizedConsumerId,
+            harness: prev.details?.harness ?? null,
+            acceptedAt: prev.at,
+          };
+        }
+        throw acceptanceError(
+          E_HANDOFF_ALREADY_ACCEPTED,
+          `Handoff ${handoffId} has already been accepted by consumer "${prev.details?.consumerId}"`,
+        );
+      }
+
+      const eventDetails = {
+        handoffId,
+        handoffDigest: handoff.artifactDigest,
+        consumerId: normalizedConsumerId,
+        ...(normalizedHarness ? { harness: normalizedHarness } : {}),
+      };
+
+      const appended = await appendProtocolEvent(
+        target,
+        {
+          taskId,
+          event: "HANDOFF_ACCEPTED",
+          details: eventDetails,
+        },
+        packageRoot,
+        { taskId },
+      );
+
+      return {
+        accepted: true,
+        idempotent: false,
+        handoffId,
+        consumerId: normalizedConsumerId,
+        harness: normalizedHarness ?? null,
+        acceptedAt: appended.at,
+      };
+    },
+  );
+}

package/src/core/handoff.js

@@ -2,12 +2,13 @@ import { randomUUID } from "node:crypto";
 import { readdir } from "node:fs/promises";
 
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { assertSecretFree } from "./receipt.js";
+import { assertPortableContextSafe, normalizePortableText } from "./portable-context.js";
 import { appendProtocolEvent } from "./events.js";
-import { currentChangedPaths } from "./repository.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "./repository.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { readWorkState } from "./work-state.js";
+import { assertStateIdentity } from "./completion-relationships.js";
 import { resolveTaskClaimState } from "./task-claim-state.js";
 import { readContinuity } from "./continuity.js";
 import { getPackageRoot } from "./templates.js";
@@ -26,12 +27,13 @@ function handoffError(code, message, artifacts = []) {
   return error;
 }
 
-function optionalText(value, label) {
+function optionalText(value, label, maxLength = 2000) {
   if (value === undefined || value === null) return null;
-  if (typeof value !== "string" || value.trim() === "") {
+  try {
+    return normalizePortableText(value, { label, maxLength, optional: true });
+  } catch (error) {
     throw handoffError("E_HANDOFF_INVALID", `${label} must be a non-empty string when provided`);
   }
-  return value;
 }
 
 function pathList(value) {
@@ -43,8 +45,22 @@ function handoffWithoutDigest(value) {
   return body;
 }
 
+export function compareRepositoryFingerprint(expected, current) {
+  const expectedUnavailable = !expected || (expected.branch === null && expected.head === null);
+  const currentUnavailable = !current || (current.branch === null && current.head === null);
+  if (expectedUnavailable && currentUnavailable) return "NOT_VERIFIED";
+  if (expectedUnavailable !== currentUnavailable) return "MISMATCH";
+  return expected.branch === current.branch && expected.head === current.head
+    ? "MATCH"
+    : "MISMATCH";
+}
+
 export function validateHandoffDigest(handoff) {
-  assertSecretFree(handoff);
+  try {
+    assertPortableContextSafe(handoff);
+  } catch (error) {
+    throw handoffError("E_HANDOFF_INVALID", error.message);
+  }
   if (typeof handoff?.artifactDigest !== "string"
     || handoff.artifactDigest !== canonicalFingerprint(handoffWithoutDigest(handoff))) {
     throw handoffError("E_HANDOFF_TAMPERED", "Handoff artifact digest does not match its canonical content");
@@ -73,17 +89,33 @@ export async function buildCanonicalHandoff(target, {
   createdAt = new Date().toISOString(),
 } = {}) {
   if (!taskId) throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "taskId is required to build a handoff");
-  const [state, contract, route, claims, changedPaths, continuity] = await Promise.all([
+  const [state, contract, route, claims, changedPaths, continuity, repositoryFingerprint] = await Promise.all([
     readWorkState(target, { packageRoot, taskId }),
     readContract(target, packageRoot, { taskId }),
     readPersistedRoute(target, packageRoot, { taskId }),
     resolveTaskClaimState(target, { packageRoot, taskId }),
     currentChangedPaths(target),
     currentContinuity(target, packageRoot, taskId),
+    currentRepositoryFingerprint(target),
   ]);
   if (!state || !contract || !route || changedPaths === null || !claims.valid) {
     throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "Canonical task state, route, claims, and changed paths are required for a handoff");
   }
+  try {
+    assertStateIdentity({ contract, route, state });
+  } catch (error) {
+    throw handoffError(
+      "E_HANDOFF_STATE_UNAVAILABLE",
+      `Canonical task artifacts are not coherent for handoff creation: ${error.message}`,
+      error.artifacts ?? [],
+    );
+  }
+  if (compareRepositoryFingerprint(state.repositoryFingerprint, repositoryFingerprint) === "MISMATCH") {
+    throw handoffError(
+      "E_HANDOFF_STATE_UNAVAILABLE",
+      "Canonical repository fingerprint has drifted from current repository state",
+    );
+  }
   const checkItems = [...(state.checks ?? [])];
   const executionRefs = pathList(checkItems.map((check) => check.executionRef).filter(Boolean));
   const checkIds = pathList(checkItems.map((check) => check.id).filter(Boolean));
@@ -101,9 +133,10 @@ export async function buildCanonicalHandoff(target, {
       phase: WORK_PHASES.includes(state.phase) ? state.phase : "UNKNOWN",
       revision: state.revision ?? 0,
       verificationCycle: state.verificationCycle ?? 1,
+      workStateFingerprint: canonicalFingerprint(state),
       contractFingerprint: contract.fingerprint,
       routeFingerprint: route.fingerprint ?? null,
-      repositoryFingerprint: state.repositoryFingerprint ?? { branch: null, head: null },
+      repositoryFingerprint,
       writeClaims: pathList(claims.effectiveWriteClaims ?? []),
       changedPaths: pathList(changedPaths),
     },

package/src/core/integration-invocation-policy.js

@@ -42,7 +42,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
   "record-terminal-result", "complete",
   "record-intervention", "record-hypothesis-disposition",
   "usage-record",
-  "workspace-bind", "handoff-create", "responsibility-set", "verify-scope", "attestation-create",
+  "workspace-bind", "handoff-create", "handoff-accept", "responsibility-set", "verify-scope", "attestation-create",
 ]));
 
 const STATIC_RISK_CLASSES = Object.freeze({
@@ -189,10 +189,27 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         explicitRebinding: false,
       },
       canonicalHandoffs: {
-        version: 1,
+        version: 2,
         supported: true,
         immutable: true,
         lifecycleAuthority: false,
+        evidenceAuthority: false,
+        exactlyOnceAcceptance: true,
+        acceptanceLedgerBacked: true,
+        acceptanceCommand: "handoff-accept",
+        acceptanceStatuses: ["OPEN", "ACCEPTED", "UNBOUND", "INCONSISTENT"],
+      },
+      advisoryContextProviders: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        integrationApiOnly: true,
+        lazy: true,
+        optIn: true,
+        persistedByForgeLoop: false,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        executable: false,
       },
       responsibilityConstraints: {
         version: 1,

package/src/core/integration-resources.js

@@ -14,6 +14,7 @@ import { readJsonArtifact } from "./artifacts.js";
 import { taskDirectory } from "./task-paths.js";
 import { resolveWorkspaceBindingStatus } from "./workspace-binding.js";
 import { listCanonicalHandoffs } from "./handoff.js";
+import { readHandoffAcceptanceLedger, resolveHandoffAcceptance } from "./handoff-acceptance.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { readVerificationScope } from "./verification-scope.js";
 import { resolveAttestationStatus } from "./attestation.js";
@@ -196,7 +197,26 @@ export async function readForgeLoopIntegrationResource(uri, {
   }
   if (uri === "task/handoffs") {
     const handoffs = await listCanonicalHandoffs(projectPath, { packageRoot, taskId });
-    return { uri, taskId, data: { taskId, count: handoffs.length, handoffs } };
+    const ledger = await readHandoffAcceptanceLedger(projectPath, packageRoot, { taskId });
+    const projectedHandoffs = handoffs.map((handoff) => {
+      const resolved = resolveHandoffAcceptance({
+        events: ledger.events,
+        handoff,
+        ledgerValid: ledger.valid,
+        ledgerErrors: ledger.errors,
+      });
+      return {
+        ...handoff,
+        acceptance: {
+          status: resolved.status,
+          consumerId: resolved.consumerId ?? null,
+          harness: resolved.harness ?? null,
+          acceptedAt: resolved.acceptedAt ?? null,
+          ...(resolved.reasonCodes ? { reasonCodes: [...resolved.reasonCodes] } : {}),
+        },
+      };
+    });
+    return { uri, taskId, data: { taskId, count: projectedHandoffs.length, handoffs: projectedHandoffs } };
   }
   if (uri === "task/responsibility") {
     return { uri, taskId, data: await resolveResponsibilityStatus(projectPath, { packageRoot, taskId }) };