@cassiomc1/forgeloop 1.9.0 → 1.10.1

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/approvals.js

@@ -1,7 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 import { appendProtocolEvent } from "./events.js";
 import { canonicalFingerprint } from "./artifacts.js";
 import {
@@ -49,7 +49,7 @@ async function writeApprovalFile(target, taskId, approval) {
   const relPath = taskApprovalPath(taskId, approval.approvalId);
   await assertSafePath(target, relPath);
   const serialized = `${JSON.stringify(approval, null, 2)}\n`;
-  const activeTransaction = getActiveTaskTransaction();
+  const activeTransaction = (await getTaskTransaction(target));
   if (activeTransaction) {
     await activeTransaction.stageText(relPath, serialized);
   } else {

package/src/core/artifacts.js

@@ -5,7 +5,7 @@ import { assertSecretFree } from "./receipt.js";
 import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { getPackageRoot } from "./templates.js";
-import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 export const ARTIFACT_PATHS = Object.freeze({
   contract: ".forgeloop/current-contract.json",
@@ -76,7 +76,7 @@ export async function readJsonArtifact(
   }
 
   const artifactPath = ensureWithin(target, relativePath);
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   const stagedText = transaction ? await transaction.readText(relativePath) : null;
   if (stagedText === null && !(await fileExists(artifactPath))) {
     throw new ArtifactError(
@@ -124,7 +124,7 @@ export async function writeJsonArtifact(
   } catch (error) {
     throw artifactError("ARTIFACT_PATH_INVALID", relativePath, error);
   }
-  const activeTransaction = getActiveTaskTransaction();
+  const activeTransaction = (await getTaskTransaction(target));
   if (!activeTransaction && taskId && !dryRun) {
     return withTaskTransaction({ target, taskId, operation, packageRoot }, async () => (
       writeJsonArtifact(target, relativePath, value, schemaName, packageRoot, { dryRun, taskId, operation })

package/src/core/checks.js

@@ -134,36 +134,3 @@ export function assertCheckList(value, label = "checks", options = {}) {
   });
   return value;
 }
-
-function requiredChecksSatisfiedBy(checks, requiredValues, selector, { allowInferred = false } = {}) {
-  assertCheckList(checks);
-  if (!Array.isArray(requiredValues)) throw checkError("E_CHECK_INVALID", "required values must be an array");
-  const errors = [];
-  for (const value of requiredValues) {
-    const candidates = checks.filter((check) => selector(check) === value);
-    const check = candidates.find((candidate) => candidate.status === "passed"
-      && (allowInferred || candidate.evidenceKind === "OBSERVED"))
-      ?? candidates.find((candidate) => candidate.status === "passed")
-      ?? candidates[0];
-    if (!check) {
-      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is missing: ${value}`, [value]));
-      continue;
-    }
-    if (check.status !== "passed") {
-      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is not passed: ${value}`, [value]));
-      continue;
-    }
-    if (!allowInferred && check.evidenceKind !== "OBSERVED") {
-      errors.push(checkError("E_EVIDENCE_KIND_INVALID", `Required check must be observed: ${value}`, [value]));
-    }
-  }
-  return errors;
-}
-
-export function requiredChecksSatisfied(checks, requiredIds, options = {}) {
-  return requiredChecksSatisfiedBy(checks, requiredIds, (check) => check.id, options);
-}
-
-export function requiredChecksSatisfiedForRequirements(checks, requiredRequirements, options = {}) {
-  return requiredChecksSatisfiedBy(checks, requiredRequirements, (check) => check.requirement, options);
-}

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/completion.js

@@ -17,7 +17,7 @@ import { listActions } from "./actions.js";
 import { readConfig } from "./config.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { createCodeManifest, readCodeManifest, validateCodeManifestBindings, writeCodeManifest } from "./code-manifest.js";
-import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 import { validateStructuralQualityCheckProvenance } from "./structural-quality/service.js";
 
 async function attestationConfiguration(target, packageRoot, errors) {
@@ -856,7 +856,7 @@ async function runCompleteInternal({
 
 export async function runComplete(options = {}) {
   const taskId = options.taskId ?? null;
-  if (options.persist !== false && taskId && !getActiveTaskTransaction()) {
+  if (options.persist !== false && taskId && !(await getTaskTransaction(options.target))) {
     return withTaskTransaction({
       target: options.target,
       taskId,

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,
 ]));
 
 /**