@cassiomc1/forgeloop 1.9.0 → 1.10.0

package/src/core/advisory-context/service.js

@@ -0,0 +1,140 @@
+import path from "node:path";
+
+import {
+  normalizePortableText,
+  assertPortableContextSafe,
+} from "../portable-context.js";
+import {
+  ADVISORY_CONTEXT_LIMITS,
+  normalizeAdvisoryRecallOptions,
+} from "./constants.js";
+import {
+  normalizeAdvisoryContextResult,
+  resolveAdvisoryContextProvider,
+} from "./provider.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_QUERY_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+  E_PORTABLE_CONTEXT_INVALID,
+} from "../error-codes.js";
+
+function serviceError(code, message, cause) {
+  const error = new Error(message, cause !== undefined ? { cause } : undefined);
+  error.name = "AdvisoryContextServiceError";
+  error.code = code;
+  return error;
+}
+
+export async function recallAdvisoryContext({
+  target,
+  taskId,
+  providerName,
+  query,
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+  runtimeContext,
+} = {}) {
+  if (!target || typeof target !== "string") {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "Target project path is required for advisory recall",
+    );
+  }
+
+  if (!taskId || typeof taskId !== "string") {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "taskId is required for advisory recall",
+    );
+  }
+
+  if (!providerName || typeof providerName !== "string") {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "providerName is required for advisory recall",
+    );
+  }
+
+  let normalizedQuery;
+  try {
+    normalizedQuery = normalizePortableText(query, {
+      label: "advisory query",
+      maxLength: ADVISORY_CONTEXT_LIMITS.maxQueryChars,
+    });
+    assertPortableContextSafe(normalizedQuery, { label: "advisory query" });
+  } catch (err) {
+    if (err.code === E_PORTABLE_CONTEXT_INVALID) {
+      throw err;
+    }
+    throw serviceError(
+      E_ADVISORY_CONTEXT_QUERY_INVALID,
+      `Advisory context query is invalid: ${err.message}`,
+      err,
+    );
+  }
+
+  const effectiveOptions = normalizeAdvisoryRecallOptions({
+    limit,
+    maxItemChars,
+    maxTotalChars,
+    timeoutMs,
+  });
+
+  let provider;
+  try {
+    provider = await resolveAdvisoryContextProvider({
+      providers: runtimeContext?.advisoryContextProviders,
+      providerName,
+    });
+  } catch (err) {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      `Advisory context provider "${providerName}" failed validation: ${err.message}`,
+      err,
+    );
+  }
+
+  if (!provider) {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+      `Advisory context provider "${providerName}" is not registered in runtime context`,
+    );
+  }
+
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        serviceError(
+          E_ADVISORY_CONTEXT_TIMEOUT,
+          `Advisory recall from provider "${providerName}" timed out after ${effectiveOptions.timeoutMs}ms`,
+        ),
+      );
+    }, effectiveOptions.timeoutMs);
+  });
+
+  let rawResult;
+  try {
+    const recallPromise = Promise.resolve(
+      provider.recall({
+        projectPath: path.resolve(target),
+        taskId,
+        query: normalizedQuery,
+        ...effectiveOptions,
+      }),
+    );
+    rawResult = await Promise.race([recallPromise, timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  return normalizeAdvisoryContextResult(rawResult, {
+    provider,
+    taskId,
+    ...effectiveOptions,
+  });
+}

package/src/core/cli-command-definitions.js

@@ -1172,6 +1172,23 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Reads and verifies one immutable handoff snapshot.",
   }),
+  "handoff-accept": Object.freeze({
+    name: "handoff-accept",
+    category: "task",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--handoff": Object.freeze({ targetKey: "handoffId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--handoff requires a handoff ID", description: "handoff identifier" }),
+      "--consumer-id": Object.freeze({ targetKey: "consumerId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--consumer-id requires a consumer ID", description: "consumer identifier accepting the handoff" }),
+      "--harness": Object.freeze({ targetKey: "harness", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--harness requires a harness name", description: "optional harness accepting the handoff" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit acceptance result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Accepts an immutable handoff exactly once in the task event ledger.",
+  }),
   "responsibility-set": Object.freeze({
     name: "responsibility-set",
     category: "scope",

package/src/core/command-executors.js

@@ -73,6 +73,7 @@ import { runWorkspaceStatus } from "../commands/workspace-status.js";
 import { runHandoffCreate } from "../commands/handoff-create.js";
 import { runHandoffList } from "../commands/handoff-list.js";
 import { runHandoffShow } from "../commands/handoff-show.js";
+import { runHandoffAccept } from "../commands/handoff-accept.js";
 import { runResponsibilitySet } from "../commands/responsibility-set.js";
 import { runResponsibilityStatus } from "../commands/responsibility-status.js";
 import { runVerifyScope } from "../commands/verify-scope.js";
@@ -236,6 +237,17 @@ export const COMMAND_EXECUTORS = {
     result: await runHandoffShow({ target, packageRoot, taskId: options.taskId, handoffId: options.handoffId }),
     exitCode: 0,
   }),
+  "handoff-accept": async ({ target, packageRoot, options }) => ({
+    result: await runHandoffAccept({
+      target,
+      packageRoot,
+      taskId: options.taskId,
+      handoffId: options.handoffId,
+      consumerId: options.consumerId,
+      harness: options.harness,
+    }),
+    exitCode: 0,
+  }),
   "responsibility-set": async ({ target, packageRoot, options }) => ({
     result: await runResponsibilitySet({
       target,

package/src/core/command-input.js

@@ -70,6 +70,8 @@ export function defaultCommandInputValues() {
     recipientHint: null,
     handoffNote: null,
     handoffId: null,
+    consumerId: null,
+    harness: null,
     responsibilityLabel: null,
     responsibilityAllowedPaths: [],
     responsibilityReadOnlyPaths: [],
@@ -148,13 +150,21 @@ export function validateForgeLoopCommandInput({ command, input, help = false } =
   if (options.compact === true && !["next", "task-show"].includes(command)) {
     throw inputError(`compact output is not valid for ${command}`);
   }
-  if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
+  if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "handoff-accept", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
     && !options.taskId) {
     throw inputError(`${command} requires --task`);
   }
   if (command === "handoff-show" && !help && !options.handoffId) {
     throw inputError("handoff-show requires --id");
   }
+  if (command === "handoff-accept" && !help) {
+    if (!options.handoffId) {
+      throw inputError("handoff-accept requires --handoff");
+    }
+    if (!options.consumerId) {
+      throw inputError("handoff-accept requires --consumer-id");
+    }
+  }
   if (command === "responsibility-set" && !help && !options.responsibilityLabel) {
     throw inputError("responsibility-set requires --label");
   }

package/src/core/continuity-lint.js

@@ -0,0 +1,89 @@
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+
+function finding(code, severity, field, itemId = null) {
+  return { code, severity, field, itemId };
+}
+
+function hasOperationalHints(continuity) {
+  return Boolean(
+    continuity.currentFocus
+    || continuity.remainingWork?.length
+    || continuity.knownIssues?.length
+    || continuity.changedAreas?.length
+    || continuity.inspectFirst?.length
+    || (typeof continuity.resumeNote === "string" && continuity.resumeNote.trim() !== ""),
+  );
+}
+
+export async function lintContinuity({ target, continuity, state } = {}) {
+  const findings = [];
+  if (!continuity || typeof continuity !== "object" || Array.isArray(continuity)) {
+    return { status: "PASS", findings };
+  }
+
+  const completedSteps = new Set(
+    Array.isArray(state?.completedSteps) ? state.completedSteps : [],
+  );
+
+  for (const [index, item] of (continuity.remainingWork ?? []).entries()) {
+    if (!item?.id) continue;
+    if (completedSteps.has(item.id)) {
+      findings.push(finding(
+        "CONTINUITY_REMAINING_ALREADY_COMPLETED",
+        "WARN",
+        `remainingWork[${index}]`,
+        item.id,
+      ));
+    }
+  }
+
+  if (continuity.currentFocus?.id && completedSteps.has(continuity.currentFocus.id)) {
+    findings.push(finding(
+      "CONTINUITY_FOCUS_ALREADY_COMPLETED",
+      "WARN",
+      "currentFocus",
+      continuity.currentFocus.id,
+    ));
+  }
+
+  const knownIssueIds = new Set(
+    (continuity.knownIssues ?? []).map((item) => item?.id).filter(Boolean),
+  );
+  for (const [index, item] of (continuity.remainingWork ?? []).entries()) {
+    if (item?.id && knownIssueIds.has(item.id)) {
+      findings.push(finding(
+        "CONTINUITY_ITEM_ROLE_CONFLICT",
+        "WARN",
+        `remainingWork[${index}]`,
+        item.id,
+      ));
+    }
+  }
+
+  if (typeof target === "string" && target.trim() !== "") {
+    for (const [index, inspectPath] of (continuity.inspectFirst ?? []).entries()) {
+      try {
+        await assertSafePath(target, inspectPath);
+        if (!(await fileExists(ensureWithin(target, inspectPath)))) {
+          findings.push(finding(
+            "CONTINUITY_INSPECT_PATH_MISSING",
+            "WARN",
+            `inspectFirst[${index}]`,
+          ));
+        }
+      } catch {
+        // Invalid or unsafe paths are rejected by continuity schema validation;
+        // lint never resolves an unchecked path or turns it into authority.
+      }
+    }
+  }
+
+  if (!hasOperationalHints(continuity)) {
+    findings.push(finding("CONTINUITY_EMPTY_HINT_SET", "INFO", "continuity"));
+  }
+
+  return {
+    status: findings.some((item) => item.severity === "WARN") ? "WARN" : "PASS",
+    findings,
+  };
+}

package/src/core/continuity-reconciliation.js

@@ -1,6 +1,7 @@
 import { canonicalFingerprint } from "./artifacts.js";
 import { assertContinuitySemantics, readContinuity } from "./continuity.js";
 import { WORK_TRANSITIONS } from "./protocol.js";
+import { lintContinuity } from "./continuity-lint.js";
 
 const RECONCILIATION_CODE = "E_CONTINUITY_RECONCILIATION_REQUIRED";
 
@@ -188,6 +189,7 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
         path: ".forgeloop/continuity.json",
         present: false,
         latestHandoff,
+        lint: { status: "PASS", findings: [] },
         diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
       };
     }
@@ -200,6 +202,15 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
       present: true,
       error: error.message,
       latestHandoff,
+      lint: {
+        status: "WARN",
+        findings: [{
+          code: error.code ?? "CONTINUITY_INVALID",
+          severity: "WARN",
+          field: "continuity",
+          itemId: null,
+        }],
+      },
     };
   }
 
@@ -229,6 +240,11 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
     fingerprint: continuityArtifact.fingerprint,
     continuity: continuityArtifact.value,
     latestHandoff,
+    lint: await lintContinuity({
+      target,
+      continuity: continuityArtifact.value,
+      state,
+    }),
     diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
   };
 }

package/src/core/continuity.js

@@ -9,7 +9,7 @@ import {
 } from "./artifacts.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { PROTOCOL_VERSION, WORK_PHASES } from "./protocol.js";
-import { assertSecretFree } from "./receipt.js";
+import { normalizePortableText, assertPortableContextSafe } from "./portable-context.js";
 import { getPackageRoot } from "./templates.js";
 import { taskArtifactPath } from "./task-paths.js";
 
@@ -37,16 +37,11 @@ function continuityError(code, message, artifacts = [CONTINUITY_PATH]) {
 }
 
 function nonEmptyString(value, label, maxLength) {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw continuityError("E_CONTINUITY_INVALID", `${label} must be a non-empty string`);
+  try {
+    return normalizePortableText(value, { label, maxLength });
+  } catch (error) {
+    throw continuityError("E_CONTINUITY_INVALID", error.message);
   }
-  if (value.length > maxLength) {
-    throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxLength}-character limit`);
-  }
-  if (/\p{Cc}/u.test(value)) {
-    throw continuityError("E_CONTINUITY_INVALID", `${label} contains control characters`);
-  }
-  return value;
 }
 
 function fingerprint(value, label) {
@@ -171,7 +166,11 @@ export function assertContinuitySemantics(input) {
       ? { resumeNote: nonEmptyString(input.resumeNote, "resumeNote", LIMITS.resumeNote) }
       : {}),
   };
-  assertSecretFree(normalized);
+  try {
+    assertPortableContextSafe(normalized);
+  } catch (error) {
+    throw continuityError("E_CONTINUITY_INVALID", error.message);
+  }
   return normalized;
 }
 

package/src/core/error-codes.js

@@ -105,6 +105,19 @@ export const E_STRUCTURAL_QUALITY_OBSERVATION_EPOCH_STALE = "E_STRUCTURAL_QUALIT
 export const E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE = "E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE";
 export const E_STRUCTURAL_QUALITY_REGRESSION = "E_STRUCTURAL_QUALITY_REGRESSION";
 
+export const E_ADVISORY_CONTEXT_PROVIDER_INVALID = "E_ADVISORY_CONTEXT_PROVIDER_INVALID";
+export const E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE = "E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE";
+export const E_ADVISORY_CONTEXT_QUERY_INVALID = "E_ADVISORY_CONTEXT_QUERY_INVALID";
+export const E_ADVISORY_CONTEXT_REQUEST_INVALID = "E_ADVISORY_CONTEXT_REQUEST_INVALID";
+export const E_ADVISORY_CONTEXT_RESULT_INVALID = "E_ADVISORY_CONTEXT_RESULT_INVALID";
+export const E_ADVISORY_CONTEXT_TIMEOUT = "E_ADVISORY_CONTEXT_TIMEOUT";
+export const E_ADVISORY_CONTEXT_OUTPUT_LIMIT = "E_ADVISORY_CONTEXT_OUTPUT_LIMIT";
+export const E_PORTABLE_CONTEXT_INVALID = "E_PORTABLE_CONTEXT_INVALID";
+export const E_HANDOFF_ACCEPTANCE_UNBOUND = "E_HANDOFF_ACCEPTANCE_UNBOUND";
+export const E_HANDOFF_STALE = "E_HANDOFF_STALE";
+export const E_HANDOFF_ALREADY_ACCEPTED = "E_HANDOFF_ALREADY_ACCEPTED";
+export const E_HANDOFF_ACCEPTANCE_INCONSISTENT = "E_HANDOFF_ACCEPTANCE_INCONSISTENT";
+
 const STRUCTURAL_QUALITY_ERROR_METADATA = Object.freeze(Object.fromEntries([
   [E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, "Correct structuralQuality mode, provider ID, budgets, floors, or optimization limits in .forgeloop/config.json."],
   [E_STRUCTURAL_QUALITY_PROVIDER_INVALID, "Use a provider implementing id, detect(input), and scan(input) with the documented normalized boundary."],
@@ -273,12 +286,100 @@ export const E_APPROVAL_ALREADY_RESOLVED = "E_APPROVAL_ALREADY_RESOLVED";
 export const E_TRAJECTORY_SCENARIO_INVALID = "E_TRAJECTORY_SCENARIO_INVALID";
 export const E_TRAJECTORY_REFERENCE_REQUIRED = "E_TRAJECTORY_REFERENCE_REQUIRED";
 
+const ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA = Object.freeze(Object.fromEntries([
+  [E_ADVISORY_CONTEXT_PROVIDER_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context provider configuration or interface implementation is invalid.",
+    safeResolution: "Use a provider implementing id, recall(input) with bounded query parameters; advisory context is optional.",
+  })],
+  [E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, Object.freeze({
+    code: E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Requested advisory context provider is not registered in runtime context.",
+    safeResolution: "Register the provider in runtime context before recall, or proceed without advisory context; provider failure never blocks canonical lifecycle.",
+  })],
+  [E_ADVISORY_CONTEXT_QUERY_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_QUERY_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context query failed portable-context validation or exceeded budget.",
+    safeResolution: "Provide a bounded query free of control characters and secret-like values.",
+  })],
+  [E_ADVISORY_CONTEXT_REQUEST_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_REQUEST_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context recall budgets are not finite integer values within the supported request contract.",
+    safeResolution: "Provide finite integer limit, maxItemChars, maxTotalChars, and timeoutMs values; oversized valid values are clamped to documented maxima.",
+  })],
+  [E_ADVISORY_CONTEXT_RESULT_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_RESULT_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context provider returned an invalid result structure.",
+    safeResolution: "Ensure provider returns items with string summary and optional title, sourceRef, observedAt, confidence.",
+  })],
+  [E_ADVISORY_CONTEXT_TIMEOUT, Object.freeze({
+    code: E_ADVISORY_CONTEXT_TIMEOUT,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context recall exceeded its execution timeout.",
+    safeResolution: "Use a responsive provider or increase timeout within limits; advisory context is optional.",
+  })],
+  [E_ADVISORY_CONTEXT_OUTPUT_LIMIT, Object.freeze({
+    code: E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context output exceeded the configured character or item limit.",
+    safeResolution: "Reduce query scope, limit items, or truncate oversized summaries at the provider.",
+  })],
+  [E_PORTABLE_CONTEXT_INVALID, Object.freeze({
+    code: E_PORTABLE_CONTEXT_INVALID,
+    category: "portable-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Text or object failed portable-context safety, character, or secret limits.",
+    safeResolution: "Ensure text is bounded, contains no control characters, and contains no secret-like values.",
+  })],
+  [E_HANDOFF_ACCEPTANCE_UNBOUND, Object.freeze({
+    code: E_HANDOFF_ACCEPTANCE_UNBOUND,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff snapshot lacks required workStateFingerprint binding.",
+    safeResolution: "Create a fresh handoff from the current ForgeLoop version before accepting it.",
+  })],
+  [E_HANDOFF_STALE, Object.freeze({
+    code: E_HANDOFF_STALE,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff snapshot has drifted from the current canonical task state or repository.",
+    safeResolution: "Create a new fresh handoff from the current task state instead of accepting a stale snapshot.",
+  })],
+  [E_HANDOFF_ALREADY_ACCEPTED, Object.freeze({
+    code: E_HANDOFF_ALREADY_ACCEPTED,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff was already accepted by a different consumer.",
+    safeResolution: "Create a new handoff for the new consumer; do not manually edit acceptance events.",
+  })],
+  [E_HANDOFF_ACCEPTANCE_INCONSISTENT, Object.freeze({
+    code: E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff acceptance disagrees with task event ledger history.",
+    safeResolution: "Verify ledger integrity and require a preceding valid HANDOFF_CREATED event.",
+  })],
+]));
+
 /**
  * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
  */
 export const PUBLIC_ERROR_CODES = Object.freeze({
   ...EXTENSION_PUBLIC_ERROR_CODES,
   ...STRUCTURAL_QUALITY_ERROR_METADATA,
+  ...ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA,
   E_PREFLIGHT_NOT_READY: Object.freeze({
     code: "E_PREFLIGHT_NOT_READY",
     category: "preflight",
@@ -1205,6 +1306,18 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_FAILURE_SIGNATURE_INVALID,
   E_STRATEGY_OSCILLATION,
   "E_TRACE_SNAPSHOT_INCONSISTENT",
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_QUERY_INVALID,
+  E_ADVISORY_CONTEXT_REQUEST_INVALID,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_PORTABLE_CONTEXT_INVALID,
+  E_HANDOFF_ACCEPTANCE_UNBOUND,
+  E_HANDOFF_STALE,
+  E_HANDOFF_ALREADY_ACCEPTED,
+  E_HANDOFF_ACCEPTANCE_INCONSISTENT,
 ]));
 
 /**

package/src/core/events.js

@@ -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) {
@@ -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/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),