@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/advisor/evidence.ts

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import type { OcxParsedRequest } from "../types";
+import { contentText } from "./state";
+import { advisorEvidenceTool } from "./evidence-tool";
+
+export interface AdvisorRepairEvidence {
+  id: string;
+  command: string;
+  firstFailure: { message: number; exitCode: number; output: string };
+  repair: { message: number; tool: string };
+  repeatedFailure: { message: number; exitCode: number; output: string };
+}
+interface Validation { command: string; fingerprint: string; invokedAt: number }
+const digest = (value: string) => createHash("sha256").update(value).digest("hex");
+const excerpt = (text: string) => text.length <= 1600 ? text : `${text.slice(0, 800)}\n[output truncated]\n${text.slice(-800)}`;
+
+/** A deliberately small command grammar. No pipelines, substitutions or arbitrary scripts. */
+function validation(args: Record<string, unknown>, invokedAt: number): Validation | undefined {
+  const input = args.cmd ?? args.command;
+  const raw = Array.isArray(input) && input.every(value => typeof value === "string")
+    ? input.map(value => JSON.stringify(value)).join(" ") : input;
+  if (typeof raw !== "string" || raw.length > 4096 || /[\n\r;|<>`$]/.test(raw)) return;
+  let command = raw.trim();
+  let cwd = typeof (args.workdir ?? args.cwd) === "string" ? String(args.workdir ?? args.cwd) : "";
+  const cd = /^cd\s+("[^"]+"|'[^']+'|[^\s&]+)\s*&&\s*(.+)$/.exec(command);
+  if (cd) { cwd += `/${cd[1]!.replace(/^["']|["']$/g, "")}`; command = cd[2]!; }
+  if (command.includes("&")) return;
+  // Quoted arguments stay intact; metacharacters above are rejected even inside quotes.
+  const tokens = command.match(/"[^"]*"|'[^']*'|[^\s"']+/g);
+  if (!tokens || tokens.join(" ").replace(/\s+/g, " ") !== command.replace(/\s+/g, " ")) return;
+  const words = tokens.map(token => token.replace(/^["']|["']$/g, ""));
+  const executable = words[0]!.split(/[\\/]/).at(-1)!;
+  const rest = words.slice(1).join(" ");
+  const isValidation = /^(?:pytest|tsc|eslint)$/.test(executable)
+    || (/^(?:bun|npm|pnpm|yarn)$/.test(executable) && /^(?:(?:run\s+)?(?:test|typecheck|lint|check|build)(?:[\s:]|$)|(?:x|exec)\s+(?:tsc|eslint)(?:\s|$))/.test(rest))
+    || (/^python(?:3)?$/.test(executable) && /^-m pytest(?:\s|$)/.test(rest))
+    || (executable === "cargo" && /^(?:test|check|clippy|build)(?:\s|$)/.test(rest))
+    || (executable === "go" && /^(?:test|vet)(?:\s|$)/.test(rest));
+  if (!isValidation) return;
+  return { command: raw, fingerprint: digest(JSON.stringify([cwd, words])), invokedAt };
+}
+
+/** Shell envelope status only. Test prose such as "FAIL" is not an exit status. */
+function exitCode(text: string): number | undefined {
+  try {
+    const wrapped = text.indexOf("\nOutput:\n");
+    const raw: unknown = JSON.parse(wrapped >= 0 ? text.slice(wrapped + "\nOutput:\n".length) : text);
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      const record = raw as Record<string, unknown>;
+      const code = record.exit_code ?? record.exitCode;
+      if (typeof code === "number" && Number.isSafeInteger(code)) return code;
+    }
+  } catch { /* textual shell envelope */ }
+  const code = /^(?:Process exited with code|Process exit code:|Exit code:)\s*(-?\d+)\s*$/m.exec(text);
+  return code ? Number(code[1]) : undefined;
+}
+
+/** Reconstructed from paired tool calls/results after the latest user turn; no LLM or timers. */
+export function collectAdvisorRepairEvidence(parsed: OcxParsedRequest): AdvisorRepairEvidence | undefined {
+  const calls = new Map<string, { tool: string; args: Record<string, unknown>; invokedAt: number }>();
+  const sessions = new Map<string, Validation>();
+  const failures = new Map<string, { failure: AdvisorRepairEvidence["firstFailure"]; callId: string; repair?: AdvisorRepairEvidence["repair"] & { callId: string } }>();
+  let candidate: AdvisorRepairEvidence | undefined;
+  let candidateFingerprint: string | undefined;
+  const messages = parsed.context.messages;
+  let start = messages.findLastIndex(message => message.role === "user") + 1;
+  // Bounded work; a clipped prefix cannot establish a failure/repair sequence.
+  start = Math.max(start, messages.length - 512);
+  for (let i = start; i < messages.length; i++) {
+    const message = messages[i]!;
+    if (message.role === "assistant") {
+      for (const part of message.content) if (part.type === "toolCall") {
+        calls.set(part.id, { ...advisorEvidenceTool(part.name, part.arguments ?? {}), invokedAt: i + 1 });
+      }
+      continue;
+    }
+    if (message.role !== "toolResult") continue;
+    const call = calls.get(message.toolCallId);
+    if (!call) continue;
+    calls.delete(message.toolCallId); // A replayed result cannot stand in for another execution.
+    const output = contentText(message.content);
+    if (["apply_patch", "Write", "Edit", "write_file", "edit_file"].includes(call.tool) && !message.isError
+      && output.trim() && !/^(?:error|failed|failure)\b/i.test(output.trim())) {
+      for (const failure of failures.values()) if (call.invokedAt > failure.failure.message) failure.repair = { message: i + 1, tool: call.tool, callId: message.toolCallId };
+      continue;
+    }
+    let check: Validation | undefined;
+    if (["exec_command", "shell_command", "shell", "Bash", "bash"].includes(call.tool)) check = validation(call.args, call.invokedAt);
+    else if (call.tool === "write_stdin") check = sessions.get(String(call.args.session_id));
+    if (!check) continue;
+    const code = exitCode(output);
+    if (code === undefined) {
+      const session = /(?:Process running with session ID\s+|"session_id"\s*:\s*)(\d+)/.exec(output);
+      if (session) sessions.set(session[1]!, check);
+      continue;
+    }
+    if (call.tool === "write_stdin") sessions.delete(String(call.args.session_id));
+    if (code === 0) {
+      failures.delete(check.fingerprint);
+      if (candidateFingerprint === check.fingerprint) { candidate = undefined; candidateFingerprint = undefined; }
+      continue;
+    }
+    const failure = { message: i + 1, exitCode: code, output: excerpt(output) };
+    const earlier = failures.get(check.fingerprint);
+    if (earlier?.repair && check.invokedAt > earlier.repair.message) {
+      candidate = {
+        // Positions are prompt references only: history pruning must not mint a new event.
+        id: digest(JSON.stringify([check.fingerprint, earlier.callId, earlier.repair.callId, message.toolCallId])),
+        command: check.command,
+        firstFailure: earlier.failure, repair: { message: earlier.repair.message, tool: earlier.repair.tool }, repeatedFailure: failure,
+      };
+      candidateFingerprint = check.fingerprint;
+    }
+    failures.set(check.fingerprint, { failure, callId: message.toolCallId });
+  }
+  return candidate;
+}

package/src/advisor/runtime.ts

@@ -0,0 +1,353 @@
+/**
+ * The advisor request plan: what the optional subsystem registers into the core Responses path.
+ *
+ * Created PER REQUEST through the activated factory called by the sidecar planner — never
+ * at module load and never globally. All mutable state is request-scoped except the bounded
+ * task-scoped preflight ledger (src/advisor/state.ts).
+ *
+ * Responsibilities:
+ * - decide whether the advisor applies to this request (settings + capability of the path);
+ * - preflight: one automatic consultation ATTEMPT per task when the orientation evidence exists,
+ *   claimed atomically in the ledger and injected as user-role advisory data;
+ * - manual: back the synthetic `advisor` tool guard with real consultations through the routing
+ *   authority (loopback chat completion);
+ * - observability: one structured log line per consultation — proof that the advisor actually
+ *   ran (worker model, advisor model, trigger, duration, status, usage).
+ *
+ * Preflight injection transport: the runtime-owned instruction is fixed developer policy;
+ * all Advisor-generated bytes are a separate JSON-quoted user-role advisory message. Manual
+ * consultations remain paired tool results. No automatic path fabricates a tool call or
+ * places Advisor output in developer/system content. User-role advice can still contain
+ * hostile recommendations; the fixed policy tells the worker how to interpret that data.
+ */
+import type { OcxConfig, OcxParsedRequest } from "../types";
+import type { AdvisorPlan, AdvisorConsultOutcome } from "../server/responses/advisor-slot";
+import { createAdvisorGuard, MAX_ADVISOR_CONSULTATIONS_PER_REQUEST } from "../server/responses/advisor-slot";
+import { resolveAdvisorSettings, type AdvisorPolicy } from "./settings";
+import { consultAdvisor } from "./consult";
+import { buildAdvisorTool } from "./synthetic-tool";
+import { sanitizeLogMetadataString } from "../lib/redact";
+import {
+  advisorLedgerKey,
+  createAdvisorPreflightLedger,
+  hasOrientationEvidence,
+  historyHasManualAdvisorResult,
+  type AdvisorPreflightLedger,
+} from "./state";
+import { formatAdvisorAdvice, advisorPreflightMessages, formatAdvisorUnavailable } from "./context";
+import { advisorActivityStore, type AdvisorActivityStore, type AdvisorTrigger } from "./activity";
+import { createAdvisorTaskBudget, type AdvisorTaskBudget } from "./budget";
+import { collectAdvisorRepairEvidence, type AdvisorRepairEvidence } from "./evidence";
+
+/**
+ * Process-local task ledger. Bounded (entries + per-state TTL) in src/advisor/state.ts; one
+ * instance per process so the claim is atomic across concurrent requests. Not durable by design
+ * — see the documented restart limitation.
+ */
+const sharedPreflightLedger = createAdvisorPreflightLedger();
+
+export const ADVISOR_SHARED_LEDGER = sharedPreflightLedger;
+
+export interface AdvisorRuntimeDeps {
+  config: Pick<OcxConfig, "advisor" | "port" | "hostname" | "apiKeys" | "unauthenticatedLoopbackListener">;
+  /** Routed worker identity for logs and the advisor payload, e.g. "deepseek-chat (provider deepseek)". */
+  workerIdentity: string;
+  workerModelId: string;
+  abortSignal?: AbortSignal;
+  /** Test seam; production always self-fetches the resolved local destination. */
+  baseUrlOverride?: string;
+  /** Test seam; production uses the process-wide ledger. */
+  ledger?: AdvisorPreflightLedger;
+  budget?: AdvisorTaskBudget;
+  activities?: AdvisorActivityStore;
+  /** Deterministic clock seam for the ledger's TTL/cooldown arithmetic (tests only). */
+  now?: () => number;
+  /**
+   * Test seam: runs after a preflight claim is taken and before the consultation
+   * dispatch, so a test can revoke consent in the claim-to-outbound window.
+   */
+  afterPreflightClaim?: () => void;
+}
+
+export interface AdvisorRuntimePlan extends AdvisorPlan {
+  readonly policy: AdvisorPolicy;
+  readonly toolEnabled: boolean;
+  readonly tool: import("../types").OcxTool;
+  /**
+   * The automatic preflight pass. Returns true when advice was injected. A cancelled
+   * consultation injects nothing and leaves the task eligible for a later attempt.
+   */
+  preflightInject(parsed: OcxParsedRequest): Promise<boolean>;
+  /** Attach the stream guard for the synthetic tool to the parsed request. */
+  attachGuard(parsed: OcxParsedRequest): void;
+}
+
+export function createAdvisorRuntimePlan(deps: AdvisorRuntimeDeps): AdvisorRuntimePlan | null {
+  const initial = resolveAdvisorSettings(deps.config);
+  // A model is required before the synthetic tool exists. Consent is checked at every
+  // consultation against the live config, so an enabled advisor without current consent can
+  // still refuse a manual call in-band without sending task context. Disabled, or enabled
+  // with no model, stays off the path.
+  if (!initial.enabled || initial.model.trim() === "") return null;
+  const ledger = deps.ledger ?? sharedPreflightLedger;
+  const now = deps.now ?? (() => Date.now());
+  const budget = deps.budget ?? createAdvisorTaskBudget();
+  const activities = deps.activities ?? advisorActivityStore(deps.config);
+  // Management PUT mutates this same config object (`config.advisor = ...`). Re-resolving
+  // at dispatch is what makes a mid-request consent revocation stop outbound transfer.
+  const liveSettings = () => resolveAdvisorSettings(deps.config);
+
+  // Request-scoped state: born here, dies with the request. Never global.
+  const fingerprints = new Set<string>();
+  let preflightUsed = false;
+  let consultations = 0;
+  // Capture before automatic user-role advisory injection. Continuations belong to this
+  // original task; an injected advisory must never mint another spending allowance.
+  let identity: { preflight?: string; budget?: string } | undefined;
+  const identify = (parsed: OcxParsedRequest) => identity ??= {
+    preflight: advisorLedgerKey(parsed, deps.workerModelId),
+    budget: advisorLedgerKey(parsed, ""),
+  };
+
+  const taskKey = (parsed: OcxParsedRequest): string | undefined =>
+    identify(parsed).preflight;
+
+  const logConsultation = (
+    trigger: AdvisorTrigger,
+    outcome: { ok: boolean; cancelled?: boolean; durationMs: number; error?: string; usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number } },
+    advisorModel: string,
+  ): void => {
+    const usage = outcome.usage
+      ? ` usage=in=${outcome.usage.inputTokens ?? "?"} out=${outcome.usage.outputTokens ?? "?"}`
+      : "";
+    const status = outcome.ok ? "ok" : outcome.cancelled ? "cancelled" : "failed";
+    const errorNote = outcome.ok || outcome.cancelled
+      ? ""
+      : ` error=${sanitizeLogMetadataString(outcome.error ?? "unknown", 160) ?? "unknown"}`;
+    // One structured line per consultation: model ids, timing, and a bounded status. No prompt,
+    // no tool output, no capability.
+    console.warn(
+      `[advisor] consultation ${status} trigger=${trigger} worker=${deps.workerModelId}`
+      + ` advisor=${advisorModel} durationMs=${outcome.durationMs}${usage}${errorNote}`,
+    );
+  };
+
+  const runConsultation = async (
+    parsed: OcxParsedRequest,
+    reason: AdvisorTrigger,
+    question: string | undefined,
+    evidence?: AdvisorRepairEvidence,
+  ): Promise<AdvisorConsultOutcome> => {
+    const current = liveSettings();
+    if (!current.enabled || current.model.trim() === "") {
+      return {
+        ok: false,
+        isError: true,
+        blocked: "settings",
+        content: formatAdvisorUnavailable(
+          reason === "manual" ? "manual" : "preflight",
+          "advisor is not configured",
+        ),
+      };
+    }
+    // Consent is operator config. Task text, the worker, and the advisor cannot grant it.
+    // The live object is re-read here so a revocation after plan creation still blocks
+    // outbound transfer. No fingerprint, no ledger write, no fetch.
+    if (current.contextSharingConsent === null) {
+      console.warn(
+        `[advisor] consultation blocked trigger=${reason} reason=advisor_context_sharing_consent_required`,
+      );
+      return {
+        ok: false,
+        isError: true,
+        blocked: "consent",
+        content: formatAdvisorUnavailable(
+          "consent",
+          "advisor_context_sharing_consent_required",
+        ),
+      };
+    }
+    // Same-consultation dedup within this request: identical trigger + focus returns a
+    // non-advice outcome instead of a second expert call.
+    const fingerprint = `${reason}|${question ?? ""}|${evidence?.id ?? ""}`;
+    let result;
+    if (fingerprints.has(fingerprint)) {
+      result = {
+        ok: false,
+        advice: "",
+        advisorModel: current.model,
+        error: "duplicate consultation request (already consulted with this focus in this request)",
+        durationMs: 0,
+      };
+      return {
+        ok: false,
+        isError: true,
+        content: formatAdvisorUnavailable(reason === "manual" ? "manual" : "preflight", result.error),
+      };
+    }
+    if (deps.abortSignal?.aborted) return { ok: false, isError: true, cancelled: true, content: "" };
+    const budgetKey = identify(parsed).budget;
+    const requestCapped = consultations >= MAX_ADVISOR_CONSULTATIONS_PER_REQUEST;
+    if (requestCapped
+      || (current.policy === "adaptive" && budgetKey && !budget.reserve(budgetKey, current.maxConsultationsPerTask, now()).ok)) {
+      const id = activities.start({ trigger: reason, workerModel: deps.workerModelId, advisorModel: current.model, requestedEffort: current.effort }, now());
+      const blocked = requestCapped ? "limit" : "budget";
+      activities.finish(id, { status: "blocked", durationMs: 0, blockReason: blocked });
+      return { ok: false, isError: true, blocked, content: formatAdvisorUnavailable(blocked, requestCapped
+        ? "per-request consultation limit reached; no consultation sent"
+        : "task budget exhausted or unavailable; no consultation sent") };
+    }
+    consultations += 1;
+    fingerprints.add(fingerprint);
+    const startedAt = now();
+    const activityId = activities.start({ trigger: reason, workerModel: deps.workerModelId, advisorModel: current.model, requestedEffort: current.effort }, startedAt);
+    try {
+      result = await consultAdvisor(
+        {
+          parsed,
+          workerIdentity: deps.workerIdentity,
+          advisorModel: current.model,
+          reason,
+          ...(evidence ? { evidence } : {}),
+          ...(question !== undefined ? { question } : {}),
+        },
+        deps.config,
+        current.effort,
+        current.timeoutMs,
+        deps.abortSignal,
+        deps.baseUrlOverride,
+      );
+    } catch (error) {
+      activities.finish(activityId, { status: "failed", durationMs: Math.max(0, now() - startedAt) });
+      throw error;
+    }
+    activities.finish(activityId, {
+      status: result.ok ? "ok" : result.cancelled ? "cancelled" : "failed",
+      durationMs: result.durationMs, effectiveEffort: result.effectiveEffort ?? null,
+      ...(result.usage ? { usage: result.usage } : {}),
+    });
+    logConsultation(reason, result, current.model);
+
+    if (result.ok) {
+      // A genuine result suppresses further automatic consultation for the task. Manual success
+      // settles it too: a task the worker already had advised does not need a preflight attempt.
+      if (reason === "manual") {
+        const key = taskKey(parsed);
+        // A manual consultation owns no preflight claim; this records the FACT that the task was
+        // advised, which is true whichever consultation produced the advice.
+        if (key) ledger.markAdvised(key, now());
+      }
+      return {
+        ok: true,
+        isError: false,
+        content: formatAdvisorAdvice({
+          advisorModel: result.advisorModel,
+          reason,
+          advice: result.advice,
+          channel: reason === "manual" ? "manual" : "preflight",
+        }),
+      };
+    }
+    return {
+      ok: false,
+      isError: true,
+      ...(result.cancelled ? { cancelled: true } : {}),
+      content: formatAdvisorUnavailable(reason === "manual" ? "manual" : "preflight", result.error ?? "unavailable"),
+    };
+  };
+
+  const preflightInject = async (parsed: OcxParsedRequest): Promise<boolean> => {
+    const task = identify(parsed);
+    const current = liveSettings();
+    if (current.policy === "manual" || preflightUsed || deps.abortSignal?.aborted) return false;
+    // No consent, disabled, or no model: do not claim, do not inject, do not send task context.
+    if (!current.enabled || current.model.trim() === "" || current.contextSharingConsent === null) return false;
+    // A genuine MANUAL consultation already advised this task (verifiable tool-result
+    // provenance), or the task has no orientation evidence yet: skip.
+    // Adaptive automation needs a stable identity for its durable task budget. Legacy
+    // preflight keeps its documented identity-less, request-scoped behavior.
+    if (current.policy === "adaptive" && !task.budget) return false;
+    const evidence = current.policy === "adaptive" ? collectAdvisorRepairEvidence(parsed) : undefined;
+    const reason = evidence ? "repair_failure" : "preflight";
+    if (!evidence && (historyHasManualAdvisorResult(parsed) || !hasOrientationEvidence(parsed))) return false;
+
+    // Atomic claim. A client with a stable conversation identity participates in the
+    // process-global ledger, so concurrent requests for one task consult at most once and a
+    // settled task is not re-consulted. A client with NO stable identity stays out of the
+    // ledger on purpose: request-scoped dedup plus genuine in-history provenance are the only
+    // suppression it gets — fail-open, so two independent identity-less conversations can never
+    // suppress each other through a shared guess.
+    const baseKey = taskKey(parsed);
+    const key = evidence && baseKey ? `${baseKey}:repair:${evidence.id}` : baseKey;
+    let claimToken: string | undefined;
+    if (key) {
+      const claim = ledger.claim(key, now());
+      if (claim.state !== "claimed") return false;
+      claimToken = claim.token;
+    }
+    preflightUsed = true;
+    deps.afterPreflightClaim?.();
+
+    let outcome: AdvisorConsultOutcome;
+    try {
+      outcome = await runConsultation(parsed, reason, undefined, evidence);
+    } catch (error) {
+      if (key && claimToken) ledger.fail(key, claimToken, now());
+      console.warn(`[advisor] consultation failed trigger=${reason} worker=${deps.workerModelId} error=plan_threw`);
+      parsed.context.messages = [
+        ...parsed.context.messages,
+        {
+          role: "user",
+          content: "An automatic advisor consultation could not be completed. Continue with your own judgment.",
+          timestamp: Date.now(),
+        },
+      ];
+      void error;
+      return false;
+    }
+
+    if (outcome.blocked) {
+      // Operator revoked consent (or disabled the sidecar) after the claim: not a provider
+      // failure. Release so the task is not put on cooldown and nothing is injected.
+      if (key && claimToken) ledger.release(key, claimToken, now());
+      return false;
+    }
+    if (outcome.ok) {
+      if (key && claimToken) ledger.complete(key, claimToken, now());
+    } else if (outcome.cancelled) {
+      // Client cancellation is not a provider failure: no cooldown, the task may retry later.
+      if (key && claimToken) ledger.release(key, claimToken, now());
+      // Nothing to inject — the caller is gone or aborting; do not add noise to a live turn.
+      return false;
+    } else {
+      if (key && claimToken) ledger.fail(key, claimToken, now());
+    }
+
+    parsed.context.messages = [
+      ...parsed.context.messages,
+      ...advisorPreflightMessages(outcome.content),
+    ];
+    return outcome.ok;
+  };
+
+  const plan: AdvisorPlan = {
+    consult: (parsed, reason, question) => runConsultation(parsed, reason, question),
+    // The guard's own failure/limit text goes through the same runtime-owned, marker-neutralized
+    // formatter so no guard path can emit text that looks like a genuine advice wrapper.
+    formatUnavailable: (kind, error) => formatAdvisorUnavailable(kind, error),
+  };
+
+  return {
+    policy: initial.policy,
+    // The synthetic tool is only safe where the guard can intercept: run-turn adapters own their
+    // own loops, so they get preflight support but never the tool (documented limitation).
+    toolEnabled: initial.enabled,
+    tool: buildAdvisorTool(),
+    consult: plan.consult,
+    formatUnavailable: plan.formatUnavailable,
+    preflightInject,
+    attachGuard: parsed => {
+      parsed._advisorGuard = createAdvisorGuard(plan);
+    },
+  };
+}

package/src/advisor/settings.ts

@@ -0,0 +1,144 @@
+/**
+ * The single reader of `advisor` config.
+ *
+ * Nothing else reads the `advisor` key directly: the sidecar planner, the management API and the
+ * CLI all resolve through here, so they cannot disagree about defaults or validity. Type-only
+ * config import keeps this module free of runtime edges.
+ */
+import type { OcxConfig } from "../types";
+import { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION } from "./disclosure";
+
+export { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION };
+
+export type AdvisorPolicy = "manual" | "preflight" | "adaptive";
+
+export const ADVISOR_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"] as const;
+export type AdvisorEffort = (typeof ADVISOR_EFFORTS)[number];
+
+export const ADVISOR_POLICIES = ["manual", "preflight", "adaptive"] as const;
+
+export interface AdvisorSettings {
+  enabled: boolean;
+  model: string;
+  effort: AdvisorEffort;
+  policy: AdvisorPolicy;
+  timeoutMs: number;
+  /** Adaptive task budget, including manual calls. Stable task identity is required. */
+  maxConsultationsPerTask: number;
+  /**
+   * Current context-sharing consent, or null when absent, stale, or malformed.
+   * `enabled` does not imply this. Only the current version allows data transfer.
+   */
+  contextSharingConsent: typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION | null;
+  /** Where each resolved value came from, so the GUI/CLI can show real runtime state. */
+  sources: {
+    enabled: "default" | "configured";
+    model: "default" | "configured";
+    effort: "default" | "configured";
+    policy: "default" | "configured";
+    contextSharingConsent: "default" | "configured";
+  };
+}
+
+export const DEFAULT_ADVISOR_SETTINGS: Readonly<AdvisorSettings> = Object.freeze({
+  enabled: false,
+  model: "",
+  effort: "max",
+  policy: "manual",
+  timeoutMs: 120_000,
+  maxConsultationsPerTask: 3,
+  contextSharingConsent: null,
+  sources: Object.freeze({
+    enabled: "default",
+    model: "default",
+    effort: "default",
+    policy: "default",
+    contextSharingConsent: "default",
+  }),
+});
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isValidAdvisorEffort(value: unknown): value is AdvisorEffort {
+  return typeof value === "string" && (ADVISOR_EFFORTS as readonly string[]).includes(value);
+}
+
+export function isValidAdvisorPolicy(value: unknown): value is AdvisorPolicy {
+  return typeof value === "string" && (ADVISOR_POLICIES as readonly string[]).includes(value);
+}
+
+export function isValidAdvisorTaskLimit(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 3;
+}
+
+/** True only for the current context-sharing consent version. Anything else is not a grant. */
+export function isCurrentAdvisorContextSharingConsent(
+  value: unknown,
+): value is typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION {
+  return value === ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}
+
+/**
+ * Resolve advisor settings with conservative defaults for every absent or malformed field.
+ * A malformed block resolves to fully disabled defaults rather than throwing: the advisor is
+ * optional and must never take the request path down with it.
+ */
+export function resolveAdvisorSettings(config: Pick<OcxConfig, "advisor">): AdvisorSettings {
+  const raw: unknown = config.advisor;
+  if (!isRec(raw)) return { ...DEFAULT_ADVISOR_SETTINGS, sources: { ...DEFAULT_ADVISOR_SETTINGS.sources } };
+  const enabled = typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_ADVISOR_SETTINGS.enabled;
+  const model = typeof raw.model === "string" ? raw.model.trim() : DEFAULT_ADVISOR_SETTINGS.model;
+  const effort = isValidAdvisorEffort(raw.effort) ? raw.effort : DEFAULT_ADVISOR_SETTINGS.effort;
+  const policy = isValidAdvisorPolicy(raw.policy) ? raw.policy : DEFAULT_ADVISOR_SETTINGS.policy;
+  const timeoutRaw = raw.timeoutMs;
+  const timeoutMs = typeof timeoutRaw === "number" && Number.isFinite(timeoutRaw) && timeoutRaw >= 1_000
+    ? Math.min(Math.floor(timeoutRaw), 600_000)
+    : DEFAULT_ADVISOR_SETTINGS.timeoutMs;
+  // A present but non-current value (stale version, wrong type) resolves as no consent.
+  // The stored bytes are left untouched; this reader never writes an upgrade.
+  const consentConfigured = Object.prototype.hasOwnProperty.call(raw, "contextSharingConsent");
+  const contextSharingConsent = isCurrentAdvisorContextSharingConsent(raw.contextSharingConsent)
+    ? raw.contextSharingConsent
+    : null;
+  return {
+    enabled,
+    model,
+    effort,
+    policy,
+    timeoutMs,
+    maxConsultationsPerTask: isValidAdvisorTaskLimit(raw.maxConsultationsPerTask)
+      ? raw.maxConsultationsPerTask : DEFAULT_ADVISOR_SETTINGS.maxConsultationsPerTask,
+    contextSharingConsent,
+    sources: {
+      enabled: typeof raw.enabled === "boolean" ? "configured" : "default",
+      model: typeof raw.model === "string" && raw.model.trim() !== "" ? "configured" : "default",
+      effort: isValidAdvisorEffort(raw.effort) ? "configured" : "default",
+      policy: isValidAdvisorPolicy(raw.policy) ? "configured" : "default",
+      contextSharingConsent: consentConfigured ? "configured" : "default",
+    },
+  };
+}
+
+/**
+ * Whether a consultation may send task context. Requires the switch, a model, and the
+ * current context-sharing consent. `enabled` is not consent. A miss fails closed for the
+ * data transfer and leaves the worker request itself running.
+ */
+export function advisorRunnable(settings: AdvisorSettings): boolean {
+  return settings.enabled
+    && settings.model.trim() !== ""
+    && settings.contextSharingConsent === ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}
+
+/**
+ * Enabled, with a model, but without current consent. The management surface reports
+ * `advisor_context_sharing_consent_required` and the runtime sends no task context.
+ */
+export function advisorContextSharingBlocked(settings: AdvisorSettings): boolean {
+  return settings.enabled
+    && settings.model.trim() !== ""
+    && settings.contextSharingConsent !== ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}