@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/orchestration/worker.mjs

@@ -19,19 +19,81 @@
  * exercised end to end against a mock provider without a live key. Failures
  * surface as structured codes (PROVIDER_KEY_MISSING, PROVIDER_MODEL_UNRESOLVED,
  * PROVIDER_EXECUTION_FAILED) rather than opaque HTTP errors.
+ *
+ * Persona resolution (LMCP-E2): the persona system prompt is resolved ONLY
+ * through the pack registry (lib/packs/prompts.mjs resolvePersonaPrompt), with
+ * no fallback to reading specialists/prompts/ directly. Team/enterprise packs
+ * with a missing or malformed prompt already fail at pack load
+ * (lib/packs/loader.mjs); a team/enterprise run that somehow still reaches a
+ * miss is refused outright (PERSONA_UNAVAILABLE) rather than executed, so a
+ * governed run can never proceed silently under the wrong persona. Solo mode
+ * degrades visibly on a miss instead: the task result carries `degraded:
+ * 'persona-fallback'` and `personaAvailable: false` rather than a silent
+ * generic substitution.
+ *
+ * Execution provenance (LMCP-F1): every provider-executed task result also
+ * carries `specialistId` (the resolved `cx-<role>` id), `packId` (which pack
+ * in the registry declared the persona, or null on a solo-mode fallback),
+ * `promptVersion` (a 12-char sha256 prefix of the resolved persona body — the
+ * same fingerprint convention as lib/prompt-metadata.mjs), `toolGrants` (the
+ * specialist's declared claudeTools from the org registry, or `[]` when the
+ * registry has no entry for the role), and `executionState` (`executed` on a
+ * real persona, `degraded-executed` on the solo-mode fallback; a provider call
+ * that throws is caught and recorded `failed` by the caller, runtime.mjs). This
+ * answers who ran, under which prompt, with which grants — the basis for audit
+ * and evaluation — without requiring a reader to cross-reference the pack
+ * registry after the fact.
+ *
+ * Contract boundary (LMCP-F2): specialists/org/contracts/ declares, per role
+ * pair, the shape a handoff packet must carry (validatePacket,
+ * lib/specialist-contracts.mjs). A task opts into enforcement by carrying
+ * `task.packet` (its inbound handoff) and/or `task.outputPacket` (its
+ * produced result); a task without either stays unvalidated rather than
+ * being failed against a fabricated contract. An invalid input packet throws
+ * CONTRACT_VIOLATION_INPUT before any provider call (hard fail, same catch
+ * path as PROVIDER_KEY_MISSING); an invalid output never throws — real,
+ * already-paid-for model output rides the result with `contractStatus:
+ * 'contract-failed'` and `contractViolations` instead of being discarded.
+ * Every violation, input or output, is appended to the tamper-evident
+ * `.cx/contract-violations.jsonl` log (lib/contracts/violation-log.mjs).
  */
 
-import { readFileSync, existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveSecret } from '../providers/secret-resolver.mjs';
+import { createHash } from 'node:crypto';
+import { resolveSecretAsync } from '../providers/secret-resolver.mjs';
+import { resolveNonNegativeSetting } from '../env-config.mjs';
 import { webSearch } from '../mcp/tools/web-search.mjs';
 import { governWebResults } from '../mcp/tools/web-search-governance.mjs';
 import { roleHoldsWebCapability, resolveWebCapability } from './web-capability.mjs';
+import {
+  PROVIDER_ERROR_CODES,
+  classifyHttpFailure,
+  classifyContentOutcome,
+  extractChoiceMeta,
+  extractUsage,
+  findUnverifiedCitations,
+  isMalformedChoice,
+  isTimeoutError,
+  withProviderRetry,
+} from './provider-outcome.mjs';
+import { loadAllPacks } from '../packs/loader.mjs';
+import { resolvePersonaPrompt } from '../packs/prompts.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { getSpecialist } from '../registry/loader.mjs';
+import { validatePacket, getIncomingContracts, getOutgoingContracts } from '../specialist-contracts.mjs';
+import { logViolation } from '../contracts/violation-log.mjs';
 
 export const INLINE = 'inline';
 export const PROVIDER = 'provider';
-export const WORKER_BACKEND_SET = [INLINE, PROVIDER];
+export const HOST = 'host';
+export const WORKER_BACKEND_SET = [INLINE, PROVIDER, HOST];
+
+// LLM completion calls run seconds-to-minutes; openai-python and anthropic-sdk-python
+// both default the overall request timeout to 600s. 120s is a conservative floor that
+// clears real responses without over-committing before the full retry/backoff policy
+// (construct-5wkl AC#4) lands. Exported so tests assert the real default, not a copy.
+export const PROVIDER_TIMEOUT_DEFAULT_MS = 120000;
 
 const MAX_OUTPUT_TOKENS = 2048;
 
@@ -41,13 +103,28 @@ const MAX_OUTPUT_TOKENS = 2048;
 
 const REASONING_BUDGET_TOKENS = 1024;
 
+// Bounded retry policy (construct-5wkl AC#4): 3 total attempts (1 original +
+// 2 retries) with exponential backoff, applied only to transport-classified
+// retryable outcomes (rate limit, 5xx, timeout) — never to a content-policy
+// refusal or a malformed body. Configurable so a test or a constrained
+// environment can shrink the window without patching the module.
+
+function providerRetryOptions(env) {
+  return {
+    maxAttempts: resolveNonNegativeSetting(env, 'CONSTRUCT_PROVIDER_MAX_ATTEMPTS', 3),
+    baseDelayMs: resolveNonNegativeSetting(env, 'CONSTRUCT_PROVIDER_RETRY_BASE_MS', 250),
+  };
+}
+
 const HERE = dirname(fileURLToPath(import.meta.url));
-const PROMPTS_DIR = join(HERE, '..', '..', 'specialists', 'prompts');
+const PACKAGE_ROOT = resolve(HERE, '..', '..');
 
-function providerError(code, reason, remediation) {
+function providerError(code, reason, remediation, { retryable = false, meta = null } = {}) {
   const err = new Error(reason);
   err.code = code;
   err.remediation = remediation;
+  err.retryable = retryable;
+  if (meta) err.providerMeta = meta;
   return err;
 }
 
@@ -70,6 +147,86 @@ function classifyWorkerProvider(provider, model) {
   return 'openrouter';
 }
 
+// ── Contract boundary (LMCP-F2) ──────────────────────────────────────────────
+// specialists/org/contracts/ declares, per producer→consumer pair, the shape a
+// handoff packet must carry (validatePacket, lib/specialist-contracts.mjs). The
+// worker is the last place a specialist runs before its output leaves
+// Construct's control, so it is the enforcement point: an invalid input packet
+// must never reach a model call (wasted spend, garbage propagated downstream),
+// and an invalid output must never look identical to a conforming one. Both
+// sides are opt-in on the task (`task.packet` / `task.outputPacket`) — a task
+// that carries no packet has not adopted a structured handoff yet, and skipping
+// validation for it (rather than failing closed on absence) is what keeps every
+// pre-F2 caller's happy path unchanged.
+
+// A role's input contract is the one where it is the CONSUMER (what it must
+// receive); ambiguity (zero or multiple matches) is not this bead's job to
+// resolve silently, so callers wanting a specific contract set
+// `task.inputContractId` explicitly. Symmetrically, its output contract is the
+// one where it is the PRODUCER, and runtime.mjs already resolves that id onto
+// `task.handoffContract` (buildTasks, LMCP-F1) — reused here rather than
+// re-deriving it.
+
+function resolveInputContractId(task) {
+  if (task?.inputContractId) return task.inputContractId;
+  const role = `cx-${String(task?.role || '').replace(/^cx-/, '')}`;
+  const incoming = getIncomingContracts(role);
+  return incoming.length === 1 ? incoming[0].id : null;
+}
+
+function resolveOutputContractId(task) {
+  if (task?.outputContractId) return task.outputContractId;
+  if (task?.handoffContract) return task.handoffContract;
+  const role = `cx-${String(task?.role || '').replace(/^cx-/, '')}`;
+  const outgoing = getOutgoingContracts(role);
+  return outgoing.length === 1 ? outgoing[0].id : null;
+}
+
+/**
+ * Validate a task's incoming handoff packet before any provider call. Throws
+ * CONTRACT_VIOLATION_INPUT (hard fail, blocks execution) when a packet is
+ * present, a contract resolves, and the packet fails shape validation. A task
+ * with no packet or no resolvable contract stays unvalidated: fabricating a
+ * contract id to fail an unopted-in task against would turn absence of data
+ * into a manufactured violation, so that case is the pre-F2 caller's status
+ * quo rather than a new failure mode.
+ */
+export function validateInputPacket(task, { cwd = process.cwd() } = {}) {
+  if (task?.packet == null) return { checked: false };
+  const contractId = resolveInputContractId(task);
+  if (!contractId) return { checked: false };
+
+  const result = validatePacket(contractId, task.packet, 'input');
+  if (result.ok) return { checked: true, ok: true, contractId };
+
+  logViolation(contractId, 'input', result.missing, task.packet, { verdict: 'CONTRACT_VIOLATION', repoRoot: cwd });
+  throw providerError(
+    'CONTRACT_VIOLATION_INPUT',
+    `Handoff packet for ${task?.role} fails contract '${contractId}': missing ${result.missing.join(', ')}`,
+    'Repair the producer packet to include the missing fields, or update the contract definition if the requirement is wrong.',
+  );
+}
+
+/**
+ * Validate a task's output packet against its role's output contract after a
+ * provider call. Never throws — a contract-failed output is recorded and
+ * reported to the caller (per policy the caller marks the task), rather than
+ * discarding real, already-paid-for model output. A task with no output
+ * packet or no resolvable contract is not validated (same opt-in rule as
+ * validateInputPacket).
+ */
+export function validateOutputPacket(task, { cwd = process.cwd() } = {}) {
+  if (task?.outputPacket == null) return { checked: false, contractStatus: 'unchecked' };
+  const contractId = resolveOutputContractId(task);
+  if (!contractId) return { checked: false, contractStatus: 'unchecked' };
+
+  const result = validatePacket(contractId, task.outputPacket, 'output');
+  if (result.ok) return { checked: true, contractStatus: 'ok', contractId };
+
+  logViolation(contractId, 'output', result.missing, task.outputPacket, { verdict: 'CONTRACT_VIOLATION', repoRoot: cwd });
+  return { checked: true, contractStatus: 'contract-failed', contractId, violations: result.missing };
+}
+
 const WORKER_KEY_VAR = {
   anthropic: 'ANTHROPIC_API_KEY',
   openai: 'OPENAI_API_KEY',
@@ -90,7 +247,17 @@ const WORKER_PROVIDER_LABEL = {
 // empty text. (Source: claude-api skill — extended/adaptive thinking; ADR-0030.)
 
 function anthropicThinkingConfig(model) {
-  const adaptive = /(opus-4-(?:[6-9]|\d\d)|sonnet-4-(?:[6-9]|\d\d))/i.test(model || '');
+  // Version-agnostic: parse family-major-minor instead of enumerating version
+  // ranges, so a newly released model never silently falls back to the legacy
+  // budget form (which adaptive-only models reject with a 400). Modern ids put
+  // the family first (claude-opus-4-8); legacy ids put the version first
+  // (claude-3-5-sonnet) and never match the modern pattern, and any unmatched
+  // id is a post-4.6 family that ships adaptive-first.
+  const m = String(model || '').toLowerCase();
+  const ver = m.match(/(?:opus|sonnet|haiku)-(\d+)(?:[.-](\d+))?/);
+  const adaptive = ver
+    ? Number(ver[1]) > 4 || (Number(ver[1]) === 4 && Number(ver[2] ?? 0) >= 6)
+    : !/claude-3/.test(m);
   return adaptive
     ? { type: 'adaptive', display: 'summarized' }
     : { type: 'enabled', budget_tokens: REASONING_BUDGET_TOKENS };
@@ -102,21 +269,123 @@ function anthropicThinkingConfig(model) {
 // hermetic switch: a caller that injects its own env (embedded callers, tests)
 // suppresses file/rc discovery so a developer's real key never bleeds into a run.
 
-function resolveKey(varName, env, allowAmbient) {
-  return resolveSecret(varName, { env, allowAmbient });
+async function resolveKey(varName, env, allowAmbient) {
+  return resolveSecretAsync(varName, { env, allowAmbient });
 }
 
-// The persona prompt is the specialist's system context. It lives in
-// specialists/prompts/cx-<role>.md; absent that file, a minimal role-named system
-// prompt keeps the backend functional rather than failing on a missing persona.
+// Cached per process, keyed by deployment mode + project cwd: loadAllPacks
+// reads and validates every manifest tier from disk (including the per-project
+// .cx/packs/ tier), which per-task would be wasted work across a
+// multi-specialist run. _resetPackRegistryCache exists for tests that vary
+// either dimension.
 
-function loadPersona(role) {
+const packRegistryCache = new Map();
+
+// ADR-0055 prompt resolution order: project packs before user packs, both
+// before builtin. mergePackTiers dedupes by pack id but does not reorder
+// distinct packs across tiers, so the merged list is re-sorted here before a
+// role lookup walks it — a project pack's prompt for a role must win over a
+// builtin pack's prompt for the same role, not just over another version of
+// the same pack id.
+
+const PACK_TIER_RANK = { project: 0, user: 1, builtin: 2, unknown: 3 };
+
+function sortByTierPrecedence(packs) {
+  return [...packs].sort((a, b) => (PACK_TIER_RANK[a._tier] ?? 3) - (PACK_TIER_RANK[b._tier] ?? 3));
+}
+
+function getPackRegistry(deploymentMode, env, cwd) {
+  const cacheKey = `${deploymentMode}::${cwd}`;
+  if (packRegistryCache.has(cacheKey)) return packRegistryCache.get(cacheKey);
+  const { packs, errors } = loadAllPacks({ deploymentMode, env, rootDir: cwd, packageRoot: PACKAGE_ROOT });
+  const registry = { packs: sortByTierPrecedence(packs), errors };
+  packRegistryCache.set(cacheKey, registry);
+  return registry;
+}
+
+/**
+ * Internal: clear the cached pack registry. Test-only.
+ */
+export function _resetPackRegistryCache() {
+  packRegistryCache.clear();
+}
+
+// The persona prompt is the specialist's system context, resolved ONLY through
+// the pack registry (LMCP-E2) — no fallback to reading specialists/prompts/
+// directly, so a pack boundary violation cannot bypass hard-fail validation
+// done at load time. Team/enterprise packs with a missing prompt already fail
+// at pack load (lib/packs/loader.mjs); PERSONA_UNAVAILABLE here is the
+// defense-in-depth refusal if one somehow still reaches this call. Solo mode
+// returns a visible degraded marker instead of executing under a silently
+// substituted generic persona.
+
+// promptVersion is a content fingerprint, not a semantic version — it changes the
+// instant the resolved persona body changes (pack edit, tier override, fallback vs
+// real prompt) so two traces can be diffed for "did the same prompt actually run."
+// Matches the sha256-prefix convention lib/prompt-metadata.mjs already uses for
+// telemetry so a promptVersion string means the same thing everywhere in the repo.
+
+function hashPromptVersion(content) {
+  return createHash('sha256').update(String(content || '')).digest('hex').slice(0, 12);
+}
+
+function loadPersona(role, { env = process.env, deploymentMode = getDeploymentMode(env), cwd = process.cwd() } = {}) {
   const slug = String(role || '').replace(/^cx-/, '');
-  const file = join(PROMPTS_DIR, `cx-${slug}.md`);
+  const specialistId = `cx-${slug}`;
+  const { packs, errors } = getPackRegistry(deploymentMode, env, cwd);
+
+  if ((deploymentMode === 'team' || deploymentMode === 'enterprise') && errors.length > 0) {
+    throw providerError(
+      'PERSONA_UNAVAILABLE',
+      `Pack registry failed to load under ${deploymentMode} mode: ${errors.join('; ')}`,
+      'Fix the named prompt file or manifest, or set orchestration.workerBackend to "inline".',
+    );
+  }
+
+  const resolved = resolvePersonaPrompt(specialistId, { packs, packageRoot: PACKAGE_ROOT });
+  if (resolved.found) {
+    return {
+      content: resolved.content,
+      available: true,
+      specialistId,
+      packId: resolved.packId ?? 'unknown',
+      promptVersion: hashPromptVersion(resolved.content),
+    };
+  }
+
+  if (deploymentMode === 'team' || deploymentMode === 'enterprise') {
+    throw providerError(
+      'PERSONA_UNAVAILABLE',
+      `No pack in the registry declares a prompt for 'cx-${slug}' under ${deploymentMode} mode.`,
+      'Add the specialist prompt to a pack manifest, or set orchestration.workerBackend to "inline".',
+    );
+  }
+
+  const fallbackContent = `You are the ${slug} specialist. Execute your part of the request within your role and return your result directly.`;
+  return {
+    content: fallbackContent,
+    available: false,
+    specialistId,
+    packId: null,
+    promptVersion: hashPromptVersion(fallbackContent),
+  };
+}
+
+// Tool grants are the specialist's declared claudeTools string (org registry,
+// specialists/org/**) — the least-privilege surface OWASP GenAI excessive-agency
+// audits need per actor. A role the registry does not know (fallback persona,
+// custom pack-only role) reports an empty grant list rather than throwing, since
+// absence of a registry entry does not mean absence of an execution.
+
+function resolveToolGrants(specialistId, { cwd = process.cwd() } = {}) {
   try {
-    if (existsSync(file)) return readFileSync(file, 'utf8');
-  } catch { /* unreadable persona falls back to the minimal prompt */ }
-  return `You are the ${slug} specialist. Execute your part of the request within your role and return your result directly.`;
+    const spec = getSpecialist(specialistId, { rootDir: cwd });
+    const raw = spec?.claudeTools;
+    if (typeof raw !== 'string' || !raw.trim()) return [];
+    return raw.split(',').map((t) => t.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
 }
 
 function buildUserPrompt({ task, run }) {
@@ -126,6 +395,40 @@ function buildUserPrompt({ task, run }) {
   return `Request: ${summary}${reason}${handoff}\n\nDo your part of this request as the ${String(task?.role || '').replace(/^cx-/, '')} specialist. Return your result directly.`;
 }
 
+/**
+ * Materialize the specialist prompt (persona + user turn) and provenance a task
+ * would run under, without calling any model. Shared by the provider executor
+ * (which then hands the result to a real model call) and the host worker
+ * backend (which hands the same result to the calling host to execute in its
+ * own session) — a host and a provider must never see two different prompts
+ * for the same task (LMCP host-execution).
+ *
+ * @param {object} opts
+ * @param {object} opts.task
+ * @param {object} opts.run
+ * @param {string} [opts.cwd]
+ * @param {Record<string,string>} [opts.env]
+ * @returns {{system:string, user:string, specialistId:string, packId:string|null,
+ *   promptVersion:string, toolGrants:string[], personaAvailable:boolean, degraded?:string}}
+ */
+export function materializeTaskPrompt({ task, run, cwd = process.cwd(), env = process.env } = {}) {
+  const deploymentMode = run?.execution?.deploymentMode || getDeploymentMode(env);
+  const persona = loadPersona(task?.role, { env, deploymentMode, cwd });
+  const system = persona.content;
+  const user = buildUserPrompt({ task, run });
+  const toolGrants = resolveToolGrants(persona.specialistId, { cwd });
+  return {
+    system,
+    user,
+    specialistId: persona.specialistId,
+    packId: persona.packId,
+    promptVersion: persona.promptVersion,
+    toolGrants,
+    personaAvailable: persona.available,
+    ...(persona.available ? {} : { degraded: 'persona-fallback' }),
+  };
+}
+
 async function bodyExcerpt(res) {
   try {
     return (await res.text()).slice(0, 200);
@@ -157,7 +460,54 @@ function timedFetch(fetchImpl, url, opts, timeoutMs) {
   ]);
 }
 
-async function callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning, timeoutMs }) {
+function remediationForCode(code, label, keyVar) {
+  if (code === PROVIDER_ERROR_CODES.RATE_LIMITED) return `${label} rate-limited this request and retries were exhausted; wait before retrying, or switch tiers/providers.`;
+  if (code === PROVIDER_ERROR_CODES.SERVER_ERROR) return `${label} returned a server error and retries were exhausted; retry later or switch providers.`;
+  if (code === PROVIDER_ERROR_CODES.AUTH_ERROR) return `Verify ${keyVar} is a valid, current credential for ${label}, or re-run with worker_backend "host" to execute specialists in the calling session with no provider key at all.`;
+  if (code === PROVIDER_ERROR_CODES.NO_CREDITS) return `${label} reports insufficient credits (HTTP 402). Add credits, or re-run with worker_backend "host" — the calling agent executes each specialist prompt in its own session at no API cost.`;
+  return `Verify the model id and ${keyVar}, or set orchestration.workerBackend to "inline".`;
+}
+
+// One transport call, wrapped in the bounded retry policy (construct-5wkl
+// AC#4): a rate limit, a 5xx, or a timeout each classify as retryable and get
+// re-attempted with backoff; anything else (auth failure, 4xx) fails on the
+// first attempt. Returns the parsed JSON body plus elapsedMs/retryCount so the
+// caller can attach provider metadata regardless of whether content
+// classification later succeeds or fails.
+
+async function postJsonRetryable(fetchImpl, url, headers, body, timeoutMs, { label, keyVar, env }) {
+  const startedAt = Date.now();
+  const { maxAttempts, baseDelayMs } = providerRetryOptions(env);
+  const data = await withProviderRetry(async () => {
+    let res;
+    try {
+      res = await timedFetch(fetchImpl, url, { method: 'POST', headers, body: JSON.stringify(body) }, timeoutMs);
+    } catch (err) {
+      if (isTimeoutError(err)) {
+        throw providerError(PROVIDER_ERROR_CODES.TIMEOUT, `${label} specialist execution timed out after ${timeoutMs}ms`, `${label} did not respond in time and retries were exhausted; raise CONSTRUCT_PROVIDER_TIMEOUT_MS or switch providers.`, { retryable: true });
+      }
+      throw err;
+    }
+    if (!res.ok) {
+      const { code, retryable } = classifyHttpFailure(res.status);
+      throw providerError(code, `${label} specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, remediationForCode(code, label, keyVar), { retryable });
+    }
+    return res.json();
+  }, { maxAttempts, baseDelayMs });
+  return { data, elapsedMs: Date.now() - startedAt, retryCount: data.retryCount ?? 0 };
+}
+
+// Anthropic's own stop-reason vocabulary (end_turn/max_tokens/stop_sequence/
+// tool_use/refusal) maps onto the shared content-outcome codes so
+// classifyContentOutcome can treat every provider family the same way.
+
+function normalizeAnthropicStopReason(stopReason) {
+  if (stopReason === 'max_tokens') return 'length';
+  if (stopReason === 'refusal') return 'content_filter';
+  return stopReason ?? null;
+}
+
+async function callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning, timeoutMs, env }) {
   const thinking = reasoning ? anthropicThinkingConfig(model) : null;
   const body = {
     model: model.replace(/^anthropic\//, ''),
@@ -166,78 +516,113 @@ async function callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning
     messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
   };
   if (thinking) body.thinking = thinking;
-  const res = await timedFetch(fetchImpl, 'https://api.anthropic.com/v1/messages', {
-    method: 'POST',
-    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
-    body: JSON.stringify(body),
-  }, timeoutMs);
-  if (!res.ok) {
-    throw providerError('PROVIDER_EXECUTION_FAILED', `Anthropic specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set orchestration.workerBackend to "inline".');
+  const { data, elapsedMs, retryCount } = await postJsonRetryable(
+    fetchImpl, 'https://api.anthropic.com/v1/messages',
+    { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body, timeoutMs, { label: 'Anthropic', keyVar: 'ANTHROPIC_API_KEY', env },
+  );
+
+  if (!Array.isArray(data.content)) {
+    throw providerError(PROVIDER_ERROR_CODES.MALFORMED_RESPONSE, 'Anthropic response is missing content blocks', 'Retry, or set orchestration.workerBackend to "inline".', {
+      meta: { provider: 'anthropic', model, elapsedMs, retryCount },
+    });
   }
-  const data = await res.json();
-  const blocks = data.content || [];
+  const blocks = data.content;
   const output = blocks.filter((b) => b && b.type === 'text').map((b) => b.text).join('');
   const thought = blocks.filter((b) => b && b.type === 'thinking').map((b) => b.thinking || '').join('').trim();
-  return { output, reasoning: thought };
+  const finishReason = normalizeAnthropicStopReason(data.stop_reason);
+  const usage = data.usage ? {
+    promptTokens: data.usage.input_tokens,
+    completionTokens: data.usage.output_tokens,
+    totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+  } : null;
+  const meta = {
+    provider: 'anthropic', model, finishReason, nativeFinishReason: data.stop_reason ?? null, usage,
+    elapsedMs, retryCount, reasoningRequested: Boolean(reasoning), reasoningReturned: Boolean(thought),
+  };
+  const outcome = classifyContentOutcome({ content: output, finishReason, reasoning: thought, wantsReasoning: reasoning });
+  if (!outcome.ok) {
+    throw providerError(outcome.code, `Anthropic returned no usable answer (${outcome.code}, finish_reason=${finishReason})`, contentOutcomeRemediation(outcome.code), { retryable: outcome.retryable, meta });
+  }
+  return { output, reasoning: thought, meta };
 }
 
-async function callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning, timeoutMs }) {
+async function callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning, timeoutMs, env }) {
   const body = {
     model: model.replace(/^openrouter\//, ''),
-    max_tokens: MAX_OUTPUT_TOKENS,
+    // Reasoning tokens draw from the same completion budget on OpenRouter as
+    // the visible answer — without the extra headroom a reasoning-heavy model
+    // can spend the entire budget on reasoning and return empty content
+    // (construct-5wkl AC#6), mirroring the Anthropic thinking-budget headroom.
+    max_tokens: reasoning ? MAX_OUTPUT_TOKENS + REASONING_BUDGET_TOKENS : MAX_OUTPUT_TOKENS,
     messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
   };
   // Enable reasoning when wanted; explicitly exclude it otherwise — some models
   // (e.g. Gemini) return reasoning by default, which would leak in hidden mode.
   // An empty `{}` is a no-op on OpenRouter; `{enabled:true}` is the on switch.
   body.reasoning = reasoning ? { enabled: true } : { exclude: true };
-  const res = await timedFetch(fetchImpl, 'https://openrouter.ai/api/v1/chat/completions', {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/geraldmaron/construct' },
-    body: JSON.stringify(body),
-  }, timeoutMs);
-  if (!res.ok) {
-    throw providerError('PROVIDER_EXECUTION_FAILED', `OpenRouter specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set orchestration.workerBackend to "inline".');
-  }
-  const data = await res.json();
-  const message = data.choices?.[0]?.message || {};
-  return { output: message.content || '', reasoning: reasoning ? extractOpenRouterReasoning(message) : '' };
+  const { data, elapsedMs, retryCount } = await postJsonRetryable(
+    fetchImpl, 'https://openrouter.ai/api/v1/chat/completions',
+    { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/geraldmaron/construct' },
+    body, timeoutMs, { label: 'OpenRouter', keyVar: 'OPENROUTER_API_KEY', env },
+  );
+  return finishOpenAiStyleCall(data, { provider: 'openrouter', model, elapsedMs, retryCount, reasoning, label: 'OpenRouter' });
 }
 
-async function callCopilot({ model, system, user, fetchImpl, timeoutMs }) {
+async function callCopilot({ model, system, user, fetchImpl, timeoutMs, env }) {
   const { getCopilotToken, copilotApiHeaders, COPILOT_API_BASE } = await import('../providers/copilot-auth.mjs');
   const token = await getCopilotToken({ fetchImpl });
-  const res = await timedFetch(fetchImpl, `${COPILOT_API_BASE}/chat/completions`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${token}`, 'content-type': 'application/json', ...copilotApiHeaders() },
-    body: JSON.stringify({
-      model: model.replace(/^github-copilot\//, ''),
-      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
-    }),
-  }, timeoutMs);
-  if (!res.ok) {
-    throw providerError('PROVIDER_EXECUTION_FAILED', `GitHub Copilot specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Run `construct creds login copilot`, or set orchestration.workerBackend to "inline".');
+  const { data, elapsedMs, retryCount } = await postJsonRetryable(
+    fetchImpl, `${COPILOT_API_BASE}/chat/completions`,
+    { Authorization: `Bearer ${token}`, 'content-type': 'application/json', ...copilotApiHeaders() },
+    { model: model.replace(/^github-copilot\//, ''), messages: [{ role: 'system', content: system }, { role: 'user', content: user }] },
+    timeoutMs, { label: 'GitHub Copilot', keyVar: 'a Copilot login', env },
+  );
+  return finishOpenAiStyleCall(data, { provider: 'github-copilot', model, elapsedMs, retryCount, reasoning: false, label: 'GitHub Copilot' });
+}
+
+async function callOpenAI({ model, apiKey, system, user, fetchImpl, timeoutMs, env }) {
+  const { data, elapsedMs, retryCount } = await postJsonRetryable(
+    fetchImpl, 'https://api.openai.com/v1/chat/completions',
+    { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+    { model: model.replace(/^openai\//, ''), messages: [{ role: 'system', content: system }, { role: 'user', content: user }] },
+    timeoutMs, { label: 'OpenAI', keyVar: 'OPENAI_API_KEY', env },
+  );
+  return finishOpenAiStyleCall(data, { provider: 'openai', model, elapsedMs, retryCount, reasoning: false, label: 'OpenAI' });
+}
+
+function contentOutcomeRemediation(code) {
+  if (code === PROVIDER_ERROR_CODES.CONTENT_FILTERED) return 'The provider refused on content-policy grounds; rephrase the task or route it to a different model — retrying the same request will not help.';
+  if (code === PROVIDER_ERROR_CODES.REASONING_ONLY) return 'The model spent its entire output budget on reasoning and returned no visible answer; this should not recur now that the reasoning budget reserves headroom for the answer, but if it does, raise the output-token ceiling.';
+  if (code === PROVIDER_ERROR_CODES.EMPTY_CONTENT) return 'The provider returned a 2xx response with no usable answer content; retry, or switch providers/models.';
+  return 'Retry, or set orchestration.workerBackend to "inline".';
+}
+
+// Shared tail for every OpenAI-shaped (choices[0].message) response:
+// OpenRouter, OpenAI, and GitHub Copilot all use this shape. Malformed-choice,
+// finish_reason, usage, and reasoning-only classification are identical across
+// the three; only the reasoning-extraction source differs (OpenRouter alone
+// returns a `reasoning`/`reasoning_details` field).
+
+function finishOpenAiStyleCall(data, { provider, model, elapsedMs, retryCount, reasoning, label }) {
+  if (isMalformedChoice(data)) {
+    throw providerError(PROVIDER_ERROR_CODES.MALFORMED_RESPONSE, `${label} response is missing choices[0].message`, 'Retry, or set orchestration.workerBackend to "inline".', {
+      meta: { provider, model, elapsedMs, retryCount },
+    });
   }
-  const data = await res.json();
-  const message = data.choices?.[0]?.message || {};
-  return { output: message.content || '', reasoning: '' };
-}
-
-async function callOpenAI({ model, apiKey, system, user, fetchImpl, timeoutMs }) {
-  const res = await timedFetch(fetchImpl, 'https://api.openai.com/v1/chat/completions', {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
-    body: JSON.stringify({
-      model: model.replace(/^openai\//, ''),
-      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
-    }),
-  }, timeoutMs);
-  if (!res.ok) {
-    throw providerError('PROVIDER_EXECUTION_FAILED', `OpenAI specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENAI_API_KEY, or set orchestration.workerBackend to "inline".');
+  const { message, finishReason, nativeFinishReason } = extractChoiceMeta(data);
+  const output = message.content || '';
+  const thought = provider === 'openrouter' && reasoning ? extractOpenRouterReasoning(message) : '';
+  const usage = extractUsage(data);
+  const meta = {
+    provider, model, finishReason, nativeFinishReason, usage, elapsedMs, retryCount,
+    reasoningRequested: Boolean(reasoning), reasoningReturned: Boolean(thought),
+  };
+  const outcome = classifyContentOutcome({ content: output, finishReason, reasoning: thought, wantsReasoning: reasoning });
+  if (!outcome.ok) {
+    throw providerError(outcome.code, `${label} returned no usable answer (${outcome.code}, finish_reason=${finishReason})`, contentOutcomeRemediation(outcome.code), { retryable: outcome.retryable, meta });
   }
-  const data = await res.json();
-  const message = data.choices?.[0]?.message || {};
-  return { output: message.content || '', reasoning: '' };
+  return { output, reasoning: thought, meta };
 }
 
 // ── Web-capable specialist execution (ADR-0050) ──────────────────────────────
@@ -411,18 +796,18 @@ async function runNativeOpenRouter({ model, apiKey, system, user, fetchImpl, tim
 // Single-shot honest fallback: no web tool, the no-web clause appended to the system
 // prompt so the specialist refuses rather than fabricates.
 
-async function runHonestNoWeb({ family, model, apiKey, system, user, fetchImpl, timeoutMs }) {
+async function runHonestNoWeb({ family, model, apiKey, system, user, fetchImpl, timeoutMs, env }) {
   const honestSystem = system + NO_WEB_CLAUSE;
-  if (family === 'github-copilot') return callCopilot({ model, system: honestSystem, user, fetchImpl, timeoutMs });
-  if (family === 'anthropic') return callAnthropic({ model, apiKey, system: honestSystem, user, fetchImpl, reasoning: false, timeoutMs });
-  if (family === 'openai') return callOpenAI({ model, apiKey, system: honestSystem, user, fetchImpl, timeoutMs });
-  return callOpenRouter({ model, apiKey, system: honestSystem, user, fetchImpl, reasoning: false, timeoutMs });
+  if (family === 'github-copilot') return callCopilot({ model, system: honestSystem, user, fetchImpl, timeoutMs, env });
+  if (family === 'anthropic') return callAnthropic({ model, apiKey, system: honestSystem, user, fetchImpl, reasoning: false, timeoutMs, env });
+  if (family === 'openai') return callOpenAI({ model, apiKey, system: honestSystem, user, fetchImpl, timeoutMs, env });
+  return callOpenRouter({ model, apiKey, system: honestSystem, user, fetchImpl, reasoning: false, timeoutMs, env });
 }
 
 async function runWebCapableTask({ family, model, apiKey, system, user, fetchImpl, env, timeoutMs, now, defaultClaim }) {
   const grant = resolveWebCapability({ family, env });
-  const maxRounds = Number(env.CONSTRUCT_WORKER_TOOL_ROUNDS) || 4;
-  const loopCap = Number(env.CONSTRUCT_WORKER_WEB_LOOP_CAP) || maxRounds;
+  const maxRounds = resolveNonNegativeSetting(env, 'CONSTRUCT_WORKER_TOOL_ROUNDS', 4);
+  const loopCap = resolveNonNegativeSetting(env, 'CONSTRUCT_WORKER_WEB_LOOP_CAP', maxRounds);
 
   if (grant.mode === 'governed') {
     if (family === 'anthropic') {
@@ -450,8 +835,8 @@ async function runWebCapableTask({ family, model, apiKey, system, user, fetchImp
   }
 
   // host-delegated and unavailable both mean this worker cannot fetch: answer honestly.
-  const r = await runHonestNoWeb({ family, model, apiKey, system, user, fetchImpl, timeoutMs });
-  return { output: r.output, reasoning: '', webCapability: grant.mode === 'host-delegated' ? 'host-delegated' : 'unavailable', webEvidence: [], webCalls: 0, webSearchRequests: 0 };
+  const r = await runHonestNoWeb({ family, model, apiKey, system, user, fetchImpl, timeoutMs, env });
+  return { output: r.output, reasoning: '', meta: r.meta, webCapability: grant.mode === 'host-delegated' ? 'host-delegated' : 'unavailable', webEvidence: [], webCalls: 0, webSearchRequests: 0 };
 }
 
 /**
@@ -467,16 +852,33 @@ async function runWebCapableTask({ family, model, apiKey, system, user, fetchImp
  * @param {string} [opts.chainOfThought] reasoning disclosure mode: `hidden` (default,
  *        no reasoning requested) | `surface` | `telemetry_only` (both request and
  *        return the model's reasoning for the caller to display or record)
- * @returns {Promise<{output:string, reasoning:string, model:string, provider:string, characters:number}>}
+ * @param {string} [opts.cwd]           project root, for project-tier pack resolution (.cx/packs/)
+ * @returns {Promise<{output:string, reasoning:string, model:string, provider:string, characters:number,
+ *   personaAvailable:boolean, degraded?:string, specialistId:string, packId:string|null,
+ *   promptVersion:string, toolGrants:string[], executionState:string, contractStatus:string,
+ *   contractId?:string, contractViolations?:string[]}>}
  */
-export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch, chainOfThought = 'hidden' } = {}) {
+export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch, chainOfThought = 'hidden', cwd = process.cwd() } = {}) {
   if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider worker backend selected but no model resolved.', 'Configure the model tier registry so a model resolves, or set orchestration.workerBackend to "inline".');
   if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider execution.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
 
-  const timeoutMs = Number(env.CONSTRUCT_PROVIDER_TIMEOUT_MS) || 200;
+  // Packet validation runs before any model call: an invalid handoff must never
+  // reach the provider (LMCP-F2). Throws CONTRACT_VIOLATION_INPUT, caught by
+  // the same path that already handles PROVIDER_KEY_MISSING etc.
+  validateInputPacket(task, { cwd });
+
+  // The shared resolver honors an explicit 0 (near-instant abort) and falls back to the
+  // minute-scale default for unset/empty/garbage/negative values — a bare `Number(env)`
+  // would turn "abc" into NaN and every real provider call would abort immediately.
+  const timeoutMs = resolveNonNegativeSetting(env, 'CONSTRUCT_PROVIDER_TIMEOUT_MS', PROVIDER_TIMEOUT_DEFAULT_MS);
   const family = classifyWorkerProvider(provider, model);
-  const system = loadPersona(task?.role);
-  const user = buildUserPrompt({ task, run });
+  // The same materialization the host worker backend uses (LMCP host-execution):
+  // persona + user turn + provenance, resolved once here and handed to the model
+  // call below — a provider-executed task and a host-executed task run under
+  // byte-identical prompts for the same task.
+  const prompt = materializeTaskPrompt({ task, run, cwd, env });
+  const system = prompt.system;
+  const user = prompt.user;
   const wantsReasoning = chainOfThought !== 'hidden';
   const webCapable = roleHoldsWebCapability(task?.role);
   const now = Date.now();
@@ -486,7 +888,7 @@ export async function runTaskViaProvider({ task, run, model, provider = null, en
   let apiKey = null;
   if (family !== 'github-copilot') {
     const keyVar = WORKER_KEY_VAR[family];
-    apiKey = resolveKey(keyVar, env, env === process.env);
+    apiKey = await resolveKey(keyVar, env, env === process.env);
     if (!apiKey) {
       throw providerError('PROVIDER_KEY_MISSING', `No API key for ${WORKER_PROVIDER_LABEL[family]} specialist execution.`, `Set ${keyVar} (a value or an op:// reference), or set orchestration.workerBackend to "inline".`);
     }
@@ -494,27 +896,64 @@ export async function runTaskViaProvider({ task, run, model, provider = null, en
 
   let output;
   let reasoning;
+  let meta = null;
   let web = null;
   if (webCapable) {
     const defaultClaim = String(run?.request?.summary || run?.request || task?.reason || 'the subject under research').slice(0, 200);
     web = await runWebCapableTask({ family, model, apiKey, system, user, fetchImpl, env, timeoutMs, now, defaultClaim });
-    ({ output, reasoning } = web);
+    ({ output, reasoning, meta } = web);
   } else if (family === 'github-copilot') {
-    ({ output, reasoning } = await callCopilot({ model, system, user, fetchImpl, timeoutMs }));
+    ({ output, reasoning, meta } = await callCopilot({ model, system, user, fetchImpl, timeoutMs, env }));
   } else {
     const call = family === 'anthropic' ? callAnthropic
       : family === 'openai' ? callOpenAI
         : callOpenRouter;
-    ({ output, reasoning } = await call({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning, timeoutMs }));
+    ({ output, reasoning, meta } = await call({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning, timeoutMs, env }));
   }
 
   const text = output || '';
+  const toolGrants = prompt.toolGrants;
+  // executionState is task-scoped here: the provider call above either returned
+  // (this function only reaches this line on success) or threw (the caller,
+  // runtime.mjs executeTaskViaProvider, catches it and records 'failed' itself).
+  // A degraded persona still genuinely executed the model call, so it is
+  // 'degraded-executed' rather than 'failed' — the run did not fail, the
+  // specialist prompt it ran under was the visible fallback.
+  const executionState = prompt.personaAvailable ? 'executed' : 'degraded-executed';
+
+  // Output validation runs after the provider call and never throws: a
+  // contract-failed output is still real, already-paid-for model output, so it
+  // rides the result with contractStatus rather than being discarded
+  // (LMCP-F2). Checked only when the task opted in via task.outputPacket.
+  const outputCheck = validateOutputPacket(task, { cwd });
+
+  // Evidence grounding (construct-5wkl AC#5): a web-capable specialist's only
+  // observed evidence is its own governed webEvidence (ADR-0050 trust/Admiralty
+  // labeling). A URL cited in the answer that is not among that evidence was
+  // never actually retrieved through Construct's governed path — either
+  // fabricated or recalled from ungoverned model memory — so the output is
+  // downgraded with a warning rather than presented as verified evidence.
+  const evidenceUrls = web?.webEvidence ? web.webEvidence.map((e) => e?.url).filter(Boolean) : null;
+  const unverifiedCitations = evidenceUrls ? findUnverifiedCitations(text, evidenceUrls) : [];
+
   return {
     output: text,
     reasoning: wantsReasoning ? (reasoning || '') : '',
     model,
     provider: family,
     characters: text.length,
+    personaAvailable: prompt.personaAvailable,
+    specialistId: prompt.specialistId,
+    packId: prompt.packId,
+    promptVersion: prompt.promptVersion,
+    toolGrants,
+    executionState,
+    contractStatus: outputCheck.contractStatus,
+    ...(outputCheck.checked ? { contractId: outputCheck.contractId } : {}),
+    ...(outputCheck.contractStatus === 'contract-failed' ? { contractViolations: outputCheck.violations } : {}),
+    ...(prompt.degraded ? { degraded: prompt.degraded } : {}),
     ...(web ? { webCapability: web.webCapability, webEvidence: web.webEvidence || [], webCalls: web.webCalls || 0, webSearchRequests: web.webSearchRequests || 0 } : {}),
+    ...(unverifiedCitations.length ? { evidenceStatus: 'unverified-citations', unverifiedCitations } : {}),
+    ...(meta ? { providerMeta: meta } : {}),
   };
 }