@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/orchestration/host-sampling.mjs

@@ -0,0 +1,121 @@
+/**
+ * lib/orchestration/host-sampling.mjs — Phase 2 of host-subscription execution:
+ * construct-mcp drives the awaiting-host loop itself via MCP sampling
+ * (`sampling/createMessage`), instead of leaving each materialized prompt for
+ * the calling agent to execute and submit back through orchestration_task_result
+ * (the Phase 1 pickup loop, lib/orchestration/runtime.mjs submitHostTaskResult).
+ *
+ * Both phases share the exact same materialization (worker.mjs
+ * materializeTaskPrompt) and the exact same recording path
+ * (submitHostTaskResult) — sampling only changes WHO executes each prompt: the
+ * client's own model via the MCP sampling capability, called by this server,
+ * rather than the calling agent's own reasoning turn. A sampling-executed
+ * task is still host-reported (provenanceSource 'host-reported'), since the
+ * client, not Construct, ran the model — Construct only relayed the call.
+ *
+ * Verified against the installed SDK (@modelcontextprotocol/sdk@1.29.0,
+ * package.json declares ^1.12.0): Server#createMessage and
+ * Server#getClientCapabilities both exist (node_modules/@modelcontextprotocol/
+ * sdk/dist/esm/server/index.js) and are the accessors this module depends on.
+ * If a future SDK removes or renames either, resolveHostExecutionMode still
+ * degrades to 'pickup' (Phase 1) rather than a hard failure — sampling is
+ * additive, pickup is the primary path by design (Claude Code's own sampling
+ * support is unconfirmed at the time of writing; VS Code is the surface
+ * expected to exercise this path).
+ */
+
+import { submitHostTaskResult } from './runtime.mjs';
+
+// A specialist answer is a single turn, same ceiling the provider worker uses
+// for a non-reasoning call (worker.mjs MAX_OUTPUT_TOKENS) — kept independent
+// here since a client's sampling budget is negotiated per-request, not a
+// process-wide constant shared with the provider path.
+
+export const SAMPLING_MAX_TOKENS = 2048;
+
+/**
+ * Decide which loop drives an awaiting-host run's remaining tasks: the
+ * client-driven MCP sampling loop, or the Phase 1 pickup loop (the calling
+ * agent executes and submits manually). `auto` (the config default) prefers
+ * sampling only when the connected client actually declared the capability at
+ * initialize time; an explicit `sampling` request against a client that never
+ * declared it still falls back to pickup rather than issuing a request the
+ * client would reject.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]              loaded project config (orchestration.hostExecution)
+ * @param {object} [opts.clientCapabilities]   server.getClientCapabilities() result
+ * @returns {'sampling'|'pickup'}
+ */
+export function resolveHostExecutionMode({ config, clientCapabilities } = {}) {
+  const configured = config?.orchestration?.hostExecution || 'auto';
+  const samplingDeclared = Boolean(clientCapabilities?.sampling);
+  if (configured === 'pickup') return 'pickup';
+  if (configured === 'sampling' || configured === 'auto') return samplingDeclared ? 'sampling' : 'pickup';
+  return 'pickup';
+}
+
+function extractSamplingText(sampled) {
+  const content = sampled?.content;
+  if (Array.isArray(content)) {
+    return content.filter((c) => c?.type === 'text').map((c) => c.text || '').join('');
+  }
+  if (content?.type === 'text') return content.text || '';
+  return '';
+}
+
+/**
+ * Drive every `awaiting-host` task on a run through the client's MCP sampling
+ * capability, recording each result through submitHostTaskResult (the same
+ * path the Phase 1 pickup loop uses) so the run finalizes through the one
+ * honest terminal-status computation regardless of which phase closed it out.
+ *
+ * A sampling call that throws (client rejects, network drop, malformed
+ * response) stops the loop early rather than fabricating a result — the
+ * remaining tasks stay `awaiting-host` exactly as Phase 1 leaves them, so the
+ * run is still honestly resumable by a manual pickup loop or a later retry,
+ * never silently marked done with invented output.
+ *
+ * @param {object} opts
+ * @param {object} opts.server   the MCP Server instance (server.createMessage)
+ * @param {object} opts.run      the awaiting-host run (or any run with awaiting-host tasks)
+ * @param {string} opts.cwd
+ * @param {Record<string,string>} [opts.env]
+ * @returns {Promise<object>} the run after every reachable task was sampled and recorded
+ */
+export async function driveHostSamplingLoop({ server, run, cwd, env = process.env } = {}) {
+  let latestRun = run;
+  let task = (latestRun.tasks || []).find((t) => t.status === 'awaiting-host');
+
+  while (task) {
+    const { system = '', user = '' } = task.hostPrompt || {};
+    let sampled;
+    try {
+      sampled = await server.createMessage({
+        messages: [{ role: 'user', content: { type: 'text', text: user } }],
+        systemPrompt: system,
+        maxTokens: SAMPLING_MAX_TOKENS,
+        modelPreferences: { intelligencePriority: 0.6, speedPriority: 0.4, costPriority: 0.4 },
+      });
+    } catch (err) {
+      console.error(`[construct-mcp] sampling/createMessage failed for task ${task.id} on run ${latestRun.runId}: ${err.message}`);
+      break;
+    }
+
+    const output = extractSamplingText(sampled);
+    if (!output.trim()) {
+      console.error(`[construct-mcp] sampling/createMessage returned empty content for task ${task.id} on run ${latestRun.runId}; leaving it awaiting-host.`);
+      break;
+    }
+
+    const { run: updated, nextTask } = await submitHostTaskResult(
+      cwd, latestRun.runId, task.id,
+      { output, model: sampled.model || null, provider: 'mcp-sampling' },
+      { env },
+    );
+    latestRun = updated;
+    task = nextTask ? (updated.tasks || []).find((t) => t.id === nextTask.id) : null;
+  }
+
+  return latestRun;
+}

package/lib/orchestration/policy-constants.mjs

@@ -0,0 +1,48 @@
+/**
+ * lib/orchestration/policy-constants.mjs — shared enums for orchestration
+ * routing policy.
+ *
+ * Extracted from lib/orchestration-policy.mjs (construct-rf26.10) so
+ * classification.mjs, gates.mjs, and flow-selection.mjs can each import the
+ * enums without importing the whole policy module (avoids a cycle back
+ * through orchestration-policy.mjs's re-export layer). orchestration-policy.mjs
+ * re-exports these unchanged for existing callers.
+ */
+
+export const EXECUTION_TRACKS = {
+  immediate: 'immediate',
+  focused: 'focused',
+  orchestrated: 'orchestrated',
+};
+
+export const INTENT_CLASSES = {
+  research: 'research',
+  implementation: 'implementation',
+  investigation: 'investigation',
+  evaluation: 'evaluation',
+  fix: 'fix',
+};
+
+// RFC-0004 §2: each intent class maps to the team that naturally owns that work.
+// The primary team drives ownership in teamRouting; specialist selection stays
+// flavor-driven. Domain refinements the RFC notes (investigation/fix can fall to
+// operations-group, research to product-group) layer on as the decision matrix
+// grows — the base mapping is deterministic so routing is testable.
+
+export const INTENT_TO_TEAM = Object.freeze({
+  research: 'strategy-team',
+  implementation: 'engineering-team',
+  investigation: 'engineering-team',
+  evaluation: 'quality-team',
+  fix: 'engineering-team',
+});
+
+export const WORK_CATEGORIES = {
+  visual: 'visual',
+  deep: 'deep',
+  quick: 'quick',
+  writing: 'writing',
+  analysis: 'analysis',
+};
+
+export const TERMINAL_STATES = ['DONE', 'BLOCKED', 'NEEDS_MAIN_INPUT'];

package/lib/orchestration/provider-outcome.mjs

@@ -0,0 +1,197 @@
+/**
+ * lib/orchestration/provider-outcome.mjs — Typed provider outcome classification,
+ * bounded retry policy, and citation-grounding checks for the provider worker
+ * (construct-5wkl).
+ *
+ * A 2xx HTTP response is transport success, not task success: the body can
+ * still carry an empty answer, a content-policy refusal, or a reasoning-only
+ * response with nothing in the visible channel. This module turns both
+ * transport failures (rate limits, 5xx, timeouts) and content-shaped failures
+ * into the same stable, machine-readable code shape so
+ * lib/orchestration/worker.mjs can throw one error type that
+ * lib/orchestration/runtime.mjs's existing catch path already records as
+ * task.status='failed' with task.error.code — no runtime.mjs change needed.
+ */
+
+export const PROVIDER_ERROR_CODES = Object.freeze({
+  RATE_LIMITED: 'PROVIDER_RATE_LIMITED',
+  SERVER_ERROR: 'PROVIDER_SERVER_ERROR',
+  TIMEOUT: 'PROVIDER_TIMEOUT',
+  AUTH_ERROR: 'PROVIDER_AUTH_ERROR',
+  NO_CREDITS: 'PROVIDER_NO_CREDITS',
+  CONTENT_FILTERED: 'PROVIDER_CONTENT_FILTERED',
+  EMPTY_CONTENT: 'PROVIDER_EMPTY_CONTENT',
+  REASONING_ONLY: 'PROVIDER_REASONING_ONLY',
+  MALFORMED_RESPONSE: 'PROVIDER_MALFORMED_RESPONSE',
+  EXECUTION_FAILED: 'PROVIDER_EXECUTION_FAILED',
+});
+
+// Only genuinely transient, infrastructure-level conditions are retryable —
+// a content-policy refusal or a malformed body will not change on retry, and
+// retrying an auth failure just spends another call to fail the same way.
+
+const RETRYABLE_CODES = new Set([
+  PROVIDER_ERROR_CODES.RATE_LIMITED,
+  PROVIDER_ERROR_CODES.SERVER_ERROR,
+  PROVIDER_ERROR_CODES.TIMEOUT,
+]);
+
+export function isRetryableCode(code) {
+  return RETRYABLE_CODES.has(code);
+}
+
+// HTTP-status classification. OpenRouter, OpenAI, and Anthropic all use 429
+// for rate limiting and 5xx for upstream/provider errors; 401/403 are
+// credential problems no retry can fix; 402 is the insufficient-credits
+// status, which gets its own code so the remediation can steer the caller to
+// the credit-free host backend instead of another spend path. Anything else
+// keeps the prior generic code so existing callers/tests are unaffected.
+
+export function classifyHttpFailure(status) {
+  if (status === 429) return { code: PROVIDER_ERROR_CODES.RATE_LIMITED, retryable: true };
+  if (status >= 500 && status < 600) return { code: PROVIDER_ERROR_CODES.SERVER_ERROR, retryable: true };
+  if (status === 401 || status === 403) return { code: PROVIDER_ERROR_CODES.AUTH_ERROR, retryable: false };
+  if (status === 402) return { code: PROVIDER_ERROR_CODES.NO_CREDITS, retryable: false };
+  return { code: PROVIDER_ERROR_CODES.EXECUTION_FAILED, retryable: false };
+}
+
+// AbortSignal.timeout firing surfaces as a DOMException/Error named
+// TimeoutError or AbortError; timedFetch's own fallback throws a plain Error
+// with "timed out" in the message when a stub fetchImpl ignores the signal.
+
+export function isTimeoutError(err) {
+  if (!err) return false;
+  if (err.name === 'TimeoutError' || err.name === 'AbortError') return true;
+  return /timed out|ETIMEDOUT/i.test(String(err.message || ''));
+}
+
+// Normalizes an OpenAI/OpenRouter-shaped chat-completions body's first choice.
+// OpenRouter additionally reports native_finish_reason (the upstream model's
+// own value before OpenRouter's own normalization).
+
+export function extractChoiceMeta(data) {
+  const choice = data?.choices?.[0];
+  return {
+    message: choice?.message && typeof choice.message === 'object' ? choice.message : null,
+    finishReason: choice?.finish_reason ?? null,
+    nativeFinishReason: choice?.native_finish_reason ?? null,
+  };
+}
+
+export function extractUsage(data) {
+  const usage = data?.usage;
+  if (!usage || typeof usage !== 'object') return null;
+  const promptTokens = Number(usage.prompt_tokens ?? usage.input_tokens);
+  const completionTokens = Number(usage.completion_tokens ?? usage.output_tokens);
+  const totalTokens = Number(usage.total_tokens ?? (promptTokens + completionTokens));
+  if (!Number.isFinite(promptTokens) && !Number.isFinite(completionTokens) && !Number.isFinite(totalTokens)) return null;
+  return {
+    promptTokens: Number.isFinite(promptTokens) ? promptTokens : undefined,
+    completionTokens: Number.isFinite(completionTokens) ? completionTokens : undefined,
+    totalTokens: Number.isFinite(totalTokens) ? totalTokens : undefined,
+  };
+}
+
+// After a 2xx response, transport succeeded but the answer may still be
+// unusable. A content-policy refusal and a reasoning-only response (visible
+// answer empty, model reasoning non-empty, finish_reason length — the model
+// spent its entire output budget on reasoning tokens and never reached the
+// answer) are both distinguishable from a genuinely empty response.
+
+export function classifyContentOutcome({ content, finishReason, reasoning, wantsReasoning }) {
+  const text = typeof content === 'string' ? content.trim() : '';
+  const hasReasoning = typeof reasoning === 'string' && reasoning.trim().length > 0;
+
+  if (finishReason === 'content_filter') {
+    return { ok: false, code: PROVIDER_ERROR_CODES.CONTENT_FILTERED, retryable: false };
+  }
+  if (!text && wantsReasoning && hasReasoning) {
+    return { ok: false, code: PROVIDER_ERROR_CODES.REASONING_ONLY, retryable: false };
+  }
+  if (!text) {
+    return { ok: false, code: PROVIDER_ERROR_CODES.EMPTY_CONTENT, retryable: false };
+  }
+  return { ok: true };
+}
+
+// Malformed-choices guard: a 2xx body missing choices[0].message entirely is
+// not the same failure as an empty string answer — it means the provider's
+// response shape itself did not match what the caller expects.
+
+export function isMalformedChoice(data) {
+  const choice = data?.choices?.[0];
+  return !choice || typeof choice !== 'object' || !choice.message || typeof choice.message !== 'object';
+}
+
+// Exponential backoff with a fixed small ceiling — provider calls already run
+// seconds-to-minutes (PROVIDER_TIMEOUT_DEFAULT_MS), so the retry delay only
+// needs to clear a rate-limit window's typical reset granularity, not model
+// latency. attempt is 1-indexed (the delay before the 2nd, 3rd, ... call).
+
+export function computeBackoffMs(attempt, baseMs = 250) {
+  return baseMs * 2 ** Math.max(0, attempt - 1);
+}
+
+async function defaultSleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Retry wrapper: calls `attemptFn(attemptNumber)` up to `maxAttempts` times
+ * (1-indexed). `attemptFn` must throw an error carrying `.code` and
+ * `.retryable` (as produced by classifyHttpFailure/isTimeoutError callers) on
+ * failure. Retries only when `.retryable` is true and attempts remain;
+ * preserves the final error's full chain by attaching `.attempts` and
+ * `.retryCount` rather than replacing it, so the caller sees exactly what the
+ * last real attempt failed with (construct-5wkl AC#4).
+ */
+export async function withProviderRetry(attemptFn, { maxAttempts = 3, baseDelayMs = 250, sleep = defaultSleep } = {}) {
+  let lastErr;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const result = await attemptFn(attempt);
+      if (result && typeof result === 'object') result.retryCount = attempt - 1;
+      return result;
+    } catch (err) {
+      lastErr = err;
+      const canRetry = err?.retryable === true && attempt < maxAttempts;
+      if (!canRetry) {
+        if (err && typeof err === 'object') err.retryCount = attempt - 1;
+        throw err;
+      }
+      await sleep(computeBackoffMs(attempt, baseDelayMs));
+    }
+  }
+  throw lastErr;
+}
+
+// ── Evidence grounding (construct-5wkl AC#5) ─────────────────────────────────
+// A web-capable specialist's governed evidence (task.webEvidence, ADR-0050) is
+// the only citation source Construct has actually observed. Any URL the model
+// writes into its answer that does not appear in that governed evidence is
+// either fabricated outright or drawn from ungoverned model memory — either
+// way it is not verified evidence and must not be presented as such.
+
+const URL_PATTERN = /https?:\/\/[^\s)\]}"'<>]+/gi;
+
+function normalizeUrl(url) {
+  return String(url || '').trim().replace(/[.,;:!?)\]}'"]+$/, '').replace(/\/$/, '').toLowerCase();
+}
+
+export function extractCitedUrls(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const matches = text.match(URL_PATTERN) || [];
+  return [...new Set(matches.map(normalizeUrl))];
+}
+
+/**
+ * Returns the subset of URLs cited in `text` that do not appear among
+ * `evidenceUrls` (the governed web-evidence list). An empty return means every
+ * citation in the text traces to observed evidence.
+ */
+export function findUnverifiedCitations(text, evidenceUrls = []) {
+  const cited = extractCitedUrls(text);
+  if (!cited.length) return [];
+  const known = new Set((evidenceUrls || []).map(normalizeUrl));
+  return cited.filter((url) => !known.has(url));
+}

package/lib/orchestration/readiness.mjs

@@ -13,6 +13,25 @@ import { getInstalledVersion } from '../version.mjs';
 import { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION } from '../embedded-contract/contract-version.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
+import { resolveExecution } from '../embedded-contract/execution.mjs';
+import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
+import { resolveWorkerBackend } from './runtime.mjs';
+import { resolveWebCapability } from './web-capability.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
+
+// A run planned with no explicit backend only actually reaches the host worker
+// backend when TWO things are true: the call is MCP-originated (so
+// orchestration_run's own host-default applies at all — a bare CLI call keeps
+// the inline default) and a real host session is attached to receive the
+// materialized prompts and submit results back. `host-session` scope with a
+// named host is the strongest signal readiness has for the second condition —
+// a self-report or a bare local-probe/local-config check proves no live host is
+// on the other end of this call, so host execution would only ever produce an
+// abandoned awaiting-host run with nobody to submit results.
+
+function hostExecutionViability({ observationScope, host }) {
+  return observationScope === 'host-session' && Boolean(host);
+}
 
 export const ORCHESTRATION_READINESS_REASONS = Object.freeze([
   'attached',
@@ -23,6 +42,8 @@ export const ORCHESTRATION_READINESS_REASONS = Object.freeze([
   'capability_negotiation_failed',
   'version_mismatch',
   'tool_unlisted',
+  'model_unresolved',
+  'execution_degraded',
   'unknown',
 ]);
 
@@ -35,12 +56,14 @@ const NEXT_STEPS = Object.freeze({
   attached: 'Proceed: call orchestration_policy, then orchestration_run when policy indicates an orchestrated or focused run.',
   host_not_attached: 'Refresh the host adapter with `construct sync`, restart the host session, then rerun `construct orchestrate preflight --json` inside the target project.',
   server_unreachable: 'Run `construct doctor`, verify the generated MCP command points at this checkout, then rerun `construct sync` if the server path is stale.',
-  auth_unavailable: 'Configure the required Construct/provider credential, restart the host so its MCP process inherits it, then rerun preflight.',
+  auth_unavailable: 'Set CONSTRUCT_ORCHESTRATION_TOKEN or CONSTRUCT_DASHBOARD_TOKEN so the MCP process serving CONSTRUCT_ORCHESTRATION_URL inherits it, restart the host, then rerun preflight.',
   profile_mismatch: 'Check the active Construct scope/profile and host adapter selection, then rerun `construct sync` from the project root.',
-  capability_negotiation_failed: 'Restart the host session so MCP initialize/tools.list negotiation runs again; if it persists, attach the diagnostic bundle to GH #323.',
+  capability_negotiation_failed: 'Restart the host session so MCP initialize/tools.list negotiation runs again; if it persists, report the issue with the printed Diagnostic id at https://github.com/geraldmaron/construct/issues.',
   version_mismatch: 'Upgrade Construct and refresh adapters with `construct sync` so the host and server use compatible contract versions.',
   tool_unlisted: 'Refresh adapters with `construct sync`; if using a reduced local tool surface, ensure orchestration_run is reachable through the `call` gateway enum.',
-  unknown: 'Run `construct doctor` and attach the diagnostic bundle to GH #323.',
+  model_unresolved: 'Set CX_MODEL_REASONING/STANDARD/FAST, or configure a provider credential (e.g. ANTHROPIC_API_KEY, OPENROUTER_API_KEY), then rerun preflight.',
+  execution_degraded: 'Run `construct orchestrate preflight --json` and inspect the modelResolved/workerBackend/webMode fields to see which one degrades this env; a same-family-fallback or config-error there predicts the same degradation orchestration_run would report.',
+  unknown: 'Run `construct doctor` and report the issue with the printed Diagnostic id at https://github.com/geraldmaron/construct/issues.',
 });
 
 function normalizeList(values) {
@@ -65,13 +88,20 @@ function hasTool(tool, observed, reachable) {
   return observed.includes(tool) || reachable.includes(tool);
 }
 
+// An unresolved `op://vault/item/field` literal is a configured *reference*,
+// not a materialized credential — counting it as a present key would tell the
+// verdict chain a provider is usable when the secret was never actually read.
+function isMaterializedSecret(value) {
+  return Boolean(value) && !/^op:\/\//.test(String(value).trim());
+}
+
 function redactedEnvFacts(env) {
   return {
     hasRemoteOrchestrationUrl: Boolean(env.CONSTRUCT_ORCHESTRATION_URL),
     hasRemoteOrchestrationToken: Boolean(env.CONSTRUCT_ORCHESTRATION_TOKEN || env.CONSTRUCT_DASHBOARD_TOKEN),
-    hasOpenRouterKey: Boolean(env.OPENROUTER_API_KEY),
-    hasAnthropicKey: Boolean(env.ANTHROPIC_API_KEY),
-    hasOpenAiKey: Boolean(env.OPENAI_API_KEY),
+    hasOpenRouterKey: isMaterializedSecret(env.OPENROUTER_API_KEY),
+    hasAnthropicKey: isMaterializedSecret(env.ANTHROPIC_API_KEY),
+    hasOpenAiKey: isMaterializedSecret(env.OPENAI_API_KEY),
   };
 }
 
@@ -81,12 +111,19 @@ export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd
   const reachableTools = normalizeList(input.reachableTools ?? input.reachable_tools);
   const host = input.host ?? null;
   const sessionId = input.sessionId ?? input.session_id ?? null;
-  const observationScope = input.observationScope ?? input.observation_scope ?? (observedTools.length || reachableTools.length ? 'host-session' : 'local-config');
+  const observationScope = input.observationScope ?? input.observation_scope ?? (observedTools.length || reachableTools.length ? 'local-probe' : 'local-config');
   const probeError = input.probeError ?? input.probe_error ?? null;
-  const clientContractVersion = input.clientContractVersion ?? input.client_contract_version ?? CONTRACT_VERSION;
+  // No self-default to CONTRACT_VERSION: a caller that never reports its own
+  // contract version is unknown, not "assumed current" — assuming current
+  // made the version_mismatch check untrippable by construction.
+  const clientContractVersion = input.clientContractVersion ?? input.client_contract_version ?? null;
   const profileExpected = input.expectedProfile ?? input.expected_profile ?? null;
   const profileActual = input.actualProfile ?? input.actual_profile ?? null;
-  const authRequired = Boolean(input.authRequired ?? input.auth_required);
+  const envFacts = redactedEnvFacts(env);
+  // A configured CONSTRUCT_ORCHESTRATION_URL means orchestration_run WILL hit
+  // a remote that needs a token; auth is required by that fact alone, not
+  // only when a caller opts in with --auth-required.
+  const authRequired = Boolean(input.authRequired ?? input.auth_required ?? envFacts.hasRemoteOrchestrationUrl);
 
   const missingTools = requiredTools.filter((tool) => !hasTool(tool, observedTools, reachableTools));
   const constructVersion = getInstalledVersion()?.version || 'unknown';
@@ -98,15 +135,17 @@ export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd
   if (probeError) {
     reasonCode = 'server_unreachable';
     detail = String(probeError);
-  } else if (compareSemver(clientContractVersion, MIN_CLIENT_CONTRACT_VERSION) < 0) {
+  } else if (clientContractVersion && compareSemver(clientContractVersion, MIN_CLIENT_CONTRACT_VERSION) < 0) {
     reasonCode = 'version_mismatch';
     detail = `Client contract ${clientContractVersion} is older than minimum ${MIN_CLIENT_CONTRACT_VERSION}.`;
   } else if (profileExpected && profileActual && profileExpected !== profileActual) {
     reasonCode = 'profile_mismatch';
     detail = `Expected profile ${profileExpected}, observed ${profileActual}.`;
-  } else if (authRequired && !(env.CONSTRUCT_ORCHESTRATION_TOKEN || env.CONSTRUCT_DASHBOARD_TOKEN)) {
+  } else if (authRequired && !envFacts.hasRemoteOrchestrationToken) {
     reasonCode = 'auth_unavailable';
-    detail = 'A remote/team orchestration token is required but not configured.';
+    detail = envFacts.hasRemoteOrchestrationUrl
+      ? 'CONSTRUCT_ORCHESTRATION_URL is configured but CONSTRUCT_ORCHESTRATION_TOKEN/CONSTRUCT_DASHBOARD_TOKEN is not set.'
+      : 'A remote/team orchestration token is required but not configured.';
   } else if (observationScope === 'host-session' && observedTools.length === 0 && reachableTools.length === 0) {
     reasonCode = 'host_not_attached';
     detail = 'No observed MCP tools were provided for the active host session.';
@@ -115,7 +154,55 @@ export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd
     detail = `Missing required tool(s): ${missingTools.join(', ')}.`;
   }
 
+  // Attachment/version/auth/tool checks above answer liveness ("is the tool
+  // reachable?"). None of them predict whether orchestration_run on this same
+  // env would actually serve, so a green verdict here could still precede a
+  // "No model could be resolved" degradation. Resolve the identical serve
+  // path orchestration_run uses — model tiers, worker backend, web grant —
+  // env/config-local, no network calls, so a reason code already set above
+  // (a real liveness failure) is never overwritten by a serve-ability check.
+  const config = (() => { try { return loadProjectConfig(cwd, env).config || {}; } catch { return {}; } })();
+  const workerBackend = resolveWorkerBackend({ config });
+  const modelResolved = {};
+  let firstUnresolvedTier = null;
+  for (const tier of ['reasoning', 'standard', 'fast']) {
+    const resolved = resolveEmbeddedModel({ requestedTier: tier }, { env });
+    modelResolved[tier] = resolved.resolutionSource !== 'config-error';
+    if (!modelResolved[tier] && !firstUnresolvedTier) firstUnresolvedTier = tier;
+  }
+  const execData = resolveExecution({ requestedStrategy: 'orchestrated' }, { env, cwd });
+  const providerFamily = (execData.selectedProvider || '').replace(/^openrouter-.*/, 'openrouter');
+  // resolveWebCapability checks env.WEB_SEARCH_URL before ever looking at
+  // family, so a governed grant must not be skipped just because no LLM
+  // provider resolved — call it unconditionally and let it fall through to
+  // 'unavailable' on its own when neither WEB_SEARCH_URL nor family applies.
+  const webGrant = resolveWebCapability({ family: providerFamily, env });
+  const credentialMaterializable = execData.modelResolution?.requiresCredential === false || execData.selectedModel != null;
+
+  if (reasonCode === 'attached' && firstUnresolvedTier) {
+    reasonCode = 'model_unresolved';
+    const presentKeys = Object.entries({ anthropic: envFacts.hasAnthropicKey, openrouter: envFacts.hasOpenRouterKey, openai: envFacts.hasOpenAiKey })
+      .filter(([, present]) => present)
+      .map(([name]) => name);
+    const keyNote = presentKeys.length ? `Provider key(s) detected: ${presentKeys.join(', ')}.` : 'No provider key detected (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY).';
+    detail = `No model could be resolved for the ${firstUnresolvedTier} tier — orchestration_run would degrade on this env. ${execData.modelResolution?.error?.remediation || ''} ${keyNote}`.trim();
+  } else if (reasonCode === 'attached' && execData.degraded) {
+    reasonCode = 'execution_degraded';
+    detail = execData.degradationReason || 'The execution contract would degrade on this env.';
+  }
+
+  // A server-self-report catalog is a liveness-shaped fact ("the process
+  // exposes tools"), not a readiness-shaped one ("this session can serve
+  // orchestration_run") — disclose it on every verdict, pass or fail, rather
+  // than laundering it into an unqualified host-session pass. Applied last so
+  // a later-computed reasonCode/detail (model_unresolved, execution_degraded)
+  // never silently drops this caveat by overwriting `detail` above it.
+  if (observationScope === 'server-self-report') {
+    detail = `${detail} Derived from the server self-report catalog, not an observed host session; orchestration_run serve-ability for this session was not independently confirmed.`.trim();
+  }
+
   const verdict = reasonCode === 'attached' ? 'pass' : 'fail';
+  const hostExecutionViable = hostExecutionViability({ observationScope, host });
   const bundle = {
     diagnosticId,
     host,
@@ -133,7 +220,12 @@ export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd
     missingTools,
     reasonCode,
     detail,
-    env: redactedEnvFacts(env),
+    modelResolved,
+    credentialMaterializable,
+    workerBackend,
+    webMode: webGrant.mode,
+    hostExecutionViable,
+    env: envFacts,
   };
 
   return {
@@ -151,6 +243,15 @@ export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd
     constructVersion,
     contractVersion: CONTRACT_VERSION,
     minClientContractVersion: MIN_CLIENT_CONTRACT_VERSION,
+    modelResolved,
+    credentialMaterializable,
+    workerBackend,
+    webMode: webGrant.mode,
+    // Whether a run planned with no explicit worker_backend on THIS session
+    // would both default to (host) and have a real host attached to execute it
+    // — distinct from workerBackend, which reports the config-resolved
+    // backend a bare CLI/no-session check would predict.
+    hostExecutionViable,
     diagnosticBundle: bundle,
   };
 }