Merge train round 3 B6: direct MCP calls in code mode, attested live startup health (#5925 #5977)

devlog/_plan/260927_merge_train_3/060_batch6.md

@@ -0,0 +1,34 @@
+# B6 — direct MCP calls in code mode, attested live startup health
+
+Base: `dev` `7d8459388c` (after B5 #6066). Branch `codex/train3-b6`.
+
+Previous D (B5): #5953 and #6027 landed with their review fixes; #5180 and the #4055 docs landed. Direction kept.
+
+| Item | Plan | Review |
+|---|---|---|
+| #5925 (mdwsk88) | Carry head `06fa8855b` as is. A routed provider's undeclared `mcp__<server>__<tool>` call is folded into the client's declared custom `exec` code-mode tool instead of failing the turn with a 502. | Kimi review LAND; dedicated security review of the undeclared-tool admission: BLOCKER no (recovery needs a client-declared custom `exec` and an actual routed conversion; arguments stay JSON data; explicit and namespaced declarations win). |
+| #5977 (RHODIZSECURITY) | Carry, then close the hold that kept it out of round 2: the server signs a local-read response with `LOCAL_ATTESTATION_PROOF_HEADER` over the request nonce, `fetchBoundLocalManagementRead` verifies it when a caller opts in, and `ocx status` opts in, so a listener that took the port cannot supply a `protected` startup verdict. | Kimi review: the bug is real on dev; the fix reuses the attestation already used by `/healthz` and system restart. |
+
+Held from this round's reviews, with reasons, for the outcome ledger: #4177 (no loop exists on dev; the rest is a
+feature), #4732 (perf rework against `snapshot-select.ts` and measurements needed from the author), #5539 (reverses
+test-locked behavior without a reproduction), #4961 (issue withholds a design), #4143 (needs the reporter's desktop
+routing details).
+
+## Build and evidence
+
+| Commit | What |
+|---|---|
+| `bee2ea4357` | #5925 carried (four commits squashed, author kept) |
+| `2a383cbc1f` | its layout entry moved onto a shared line (layout.json stays at 1993 lines) |
+| `f2727befa8` | #5977 carried; the author's noreply identity replaces the placeholder address on the commit |
+| `6341da9847` | #5977 response proof: the server signs local-read responses over the request nonce, the client verifies when asked, `ocx status` asks. New `tests/server/local-read-response-proof.test.ts` and a negative client test; both fail without the change |
+
+Security: #5925 dedicated review BLOCKER no. #5977's remaining hold is closed by `6341da9847`, which reuses the
+attestation that `/healthz` and system restart already use.
+
+Aside: #5925 shows no open review; #5977 shows two approvals from before the response-proof commit.
+
+Local proof at `6341da9847`: typecheck, structure and privacy exit 0; the seven local-read and status files plus the
+three #5925 files 122 pass. Directory runs: `tests/adapters` 2371 pass, 107 fail on this branch and 2369 pass, 107 fail
+on `dev` `7d8459388c` (same Anthropic cooldown and pool files, which pass alone), so the failures are pre-existing
+directory-run interference; `tests/responses` shows the 13 known `responses-compaction-recovery` failures.

docs-site/src/content/docs/guides/codex-integration.md

@@ -653,6 +653,15 @@ code-mode `exec` has the call converted into the matching `tools.<helper>(...)`
 `exec`. A catalog that genuinely declares the bare goal tool keeps it, and a catalog that declares
 neither the tool nor `exec` still rejects the call as undeclared.
 
+On routed conversions with a verified freeform code-mode `exec` catalog, structured calls
+sent directly to
+`mcp__<server>__<tool>` (including a provider-added `default.` prefix) are also
+wrapped as nested host-tool calls. This avoids a retry
+caused solely by a model omitting the `exec` wrapper. Explicitly declared MCP tools
+keep their normal behavior; an ordinary JSON function named `exec` does not enable
+this repair. Unknown tools still fail at the host. Tool-call records printed as
+ordinary answer text are not executed by this compatibility rule.
+
 For routed Responses turns, an explicit tool-enforcement policy also rejects client tool calls if
 the request's declared-tool catalog is unavailable. An empty declared catalog rejects every client
 tool call; Chat and Anthropic clients retain their own tool-validation responsibility.

docs-site/src/content/docs/reference/cli/lifecycle.md

@@ -185,6 +185,15 @@ opencodex wrote names a local port the running proxy does not serve. `ocx sync`
 immediately, and a running owner proxy may also re-point it on its own once nothing answers on that
 port. A sibling's status does not report it, because its routing names the proxy it runs beside.
 
+When a live proxy has already passed the identity/liveness check, `ocx status` prefers that process's
+attested startup-health report for restart safety and service viability. This avoids false negatives
+from a shell-local service-manager probe that lacks the running service's manager environment. The
+live report is schema-validated; if it is unavailable or malformed, status falls back to the local
+service and shim diagnostics. `ocx doctor` uses the same live-first rule for its **Codex restart safety**
+section, so the two commands should agree on restart protection. If you are diagnosing a discrepancy,
+compare the reported live startup verdict with the local service details rather than treating the shell
+probe as more authoritative.
+
 Human output also includes an **OAuth health** block after the OAuth logins summary: `OAuth health:
 ok` when every known account is healthy, or `OAuth health: warning` with one redacted line per
 non-healthy account (provider, masked account id, status such as reauthentication required, rate or

scripts/test-layout/layout.json

@@ -173,7 +173,7 @@
     "cli-kiro-auto-selection.test.ts": "cli", "codebuddy-live-models.test.ts": "providers", "kiro-auto-selection.test.ts": "providers/kiro", "kiro-quota-metrics.test.ts": "providers/kiro", "management-provider-request-pacing.test.ts": "server",
     "desktop-supervised-restart.test.ts": "clients", "cli-restart-handoff.test.ts": "cli",
     "restart-replacement.test.ts": "server", "deepseek-artifact-tool-schema.test.ts": "providers",
-    "client-config-export-output-limit.test.ts": "config", "responses-skills-snapshot.test.ts": "responses",
+    "client-config-export-output-limit.test.ts": "config", "responses-skills-snapshot.test.ts": "responses", "responses-code-mode-mcp-direct.test.ts": "responses", "local-read-response-proof.test.ts": "server",
     "openai-chat-serialized-tool-call-scaling.test.ts": "adapters/openai",
     "openai-chat-tool-call-id-remint.test.ts": "adapters/openai",
     "coding-agent-json-lines-scaling.test.ts": "providers",

src/bridge/response-json.ts

@@ -86,6 +86,8 @@ function buildResponseJSONWithBudget(
     toolNsMap?: Map<string, { namespace: string; name: string; freeform?: true }>;
     /** Request-visible tool names. Required for client calls when enforcement is explicitly enabled. */
     declaredToolNames?: ReadonlySet<string>;
+    /** Bare custom declarations; unlike freeformToolNames, excludes foreign namespace children. */
+    bareCustomToolNames?: ReadonlySet<string>;
     /** See `bridgeToResponsesSSE`: enforcement is separate from normalization (#4735). */
     enforceDeclaredToolNames?: boolean;
     /** Declared parameter schema per tool name; repairs integral-float integer args (#1611). */
@@ -451,7 +453,7 @@ function buildResponseJSONWithBudget(
           rememberReasoningForCall(e.id, rawReasoningForNextToolCall, replayCacheScope);
         }
         flushToolCall();
-        const effectiveName = normalizeDeclaredToolName(e.name, options?.declaredToolNames);
+        const effectiveName = normalizeDeclaredToolName(e.name, options?.declaredToolNames, undefined, options?.bareCustomToolNames);
         if (
           (options?.enforceDeclaredToolNames === true || options?.declaredToolNames != null)
           && options?.enforceDeclaredToolNames !== false

src/bridge/sse.ts

@@ -101,6 +101,8 @@ export function bridgeToResponsesSSE(
     onUsage?: (usage: OcxUsage | undefined) => void;
     /** Request-visible tool names. Required for client calls when enforcement is explicitly enabled. */
     declaredToolNames?: ReadonlySet<string>;
+    /** Bare custom declarations; unlike freeformToolNames, excludes foreign namespace children. */
+    bareCustomToolNames?: ReadonlySet<string>;
     /**
      * Whether `declaredToolNames` is an authorization boundary this proxy enforces, or only the
      * catalog used to normalize provider-invented names back to declared ones.
@@ -1013,7 +1015,7 @@ export function bridgeToResponsesSSE(
                 rememberReasoningForCall(event.id, rawReasoningForNextToolCall, replayCacheScope);
               }
               if (currentToolCall) closeCurrentToolCall();
-              const effectiveName = normalizeDeclaredToolName(event.name, options?.declaredToolNames);
+              const effectiveName = normalizeDeclaredToolName(event.name, options?.declaredToolNames, undefined, options?.bareCustomToolNames);
               const codeModeHelperName = effectiveName === "exec" && event.name !== effectiveName
                 ? event.name
                 : undefined;

src/cli/doctor.ts

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics } from "../config";
 import { readPid } from "../config/process-state";
-import { probeUncleanExitState } from "./status";
+import { fetchLiveStartupHealth, probeUncleanExitState, selectStatusStartupHealth } from "./status";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { BUN_RUNTIME_SOURCES } from "../lib/bun-runtime";
@@ -1354,7 +1354,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     diagnoseCodexShim(),
     serviceTokenPresent,
   );
-  const startup = collectStartupHealth(doctorConfig);
+  // Use the same attested live startup verdict as `ocx status` when the proxy is already
+  // identity-verified. A shell-local systemd probe can be a false negative for a system-wide
+  // service because the shell does not inherit the manager-owned environment.
+  const live = await findLiveProxy({
+    configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
+  });
+  const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
+  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig));
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
@@ -1393,12 +1400,6 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     }
   }
 
-  // #618: identity-verified liveness first so pid-file absence does not hide a live service.
-  // Reuse the diagnostics config already loaded above so doctor stays read-only on malformed JSON.
-  const live = await findLiveProxy({
-    configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
-  });
-
   // Mirrors `ocx status` through the same comparison rather than a second implementation:
   // two diagnostics disagreeing about whether an install is stale is worse than one (#2701).
   // No extra probe -- findLiveProxy already carried the version back.

src/cli/status.ts

@@ -31,6 +31,8 @@ import { tokenCollidesWithAdmin } from "../lib/admin-secrets";
 export { proxyHealthFailureReason, isConnectionRefused, isUncleanExitEvidence, probeUncleanExitState } from "./status-probes";
 export type { ListenTarget } from "./status-probes";
 import { checkProxyHealth, probeUncleanExitState, type ListenTarget } from "./status-probes";
+import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
+import { fetchBoundLocalManagementRead } from "../server/local-management-read-client";
 
 /**
  * The state of the data-plane admission secret the SERVICE will use. State only -- never the value.
@@ -235,6 +237,84 @@ function statusDashboardUrl(config: StatusListenConfig, hostname: string | undef
   return `http://${dashboardHostname}:${port}/`;
 }
 
+const STARTUP_HEALTH_BOOLEAN_FIELDS = [
+  "routingInjected", "localRoutingDependency", "autostartEnabled", "rebootSafe",
+  "serviceInstalled", "serviceViable", "serviceEnabled", "serviceRunning",
+  "serviceStale", "serviceConflict", "shimInstalled", "shimHealthy",
+  "serviceSupported", "diagnosticStale",
+] as const;
+
+export async function fetchLiveStartupHealth(
+  live: NonNullable<Awaited<ReturnType<typeof findLiveProxy>>>,
+  deps: Parameters<typeof fetchBoundLocalManagementRead>[2] = {},
+): Promise<StartupHealth | null> {
+  const result = await fetchBoundLocalManagementRead(
+    live, LOCAL_MANAGEMENT_READ_PATHS.startupHealth, { timeoutMs: 1_500, ...deps, requireResponseProof: true },
+  );
+  if (result.kind !== "response" || !result.response.ok) return null;
+  let payload: unknown;
+  try { payload = await result.response.json(); } catch { return null; }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const row = payload as Record<string, unknown>;
+  if (row.status !== "native" && row.status !== "protected" && row.status !== "at-risk") return null;
+  if (row.protection !== "service" && row.protection !== "shim" && row.protection !== "none") return null;
+  if (row.routingKind !== "native" && row.routingKind !== "opencodex-local"
+    && row.routingKind !== "custom-local" && row.routingKind !== "custom-remote" && row.routingKind !== "unknown") return null;
+  if (row.shimCoverage !== "full" && row.shimCoverage !== "cli-only" && row.shimCoverage !== "none") return null;
+  if (typeof row.platform !== "string") return null;
+  if (row.recommendedCommand !== null && typeof row.recommendedCommand !== "string") return null;
+  if (!row.commands || typeof row.commands !== "object" || Array.isArray(row.commands)) return null;
+  for (const key of ["installService", "repairService", "installShim", "restoreNative"] as const) {
+    if (typeof (row.commands as Record<string, unknown>)[key] !== "string") return null;
+  }
+  if (row.routingAdoption !== undefined) {
+    if (!row.routingAdoption || typeof row.routingAdoption !== "object" || Array.isArray(row.routingAdoption)) return null;
+    const adoption = row.routingAdoption as Record<string, unknown>;
+    if (adoption.adoption !== "not-applicable" && adoption.adoption !== "adopted"
+      && adoption.adoption !== "pending-client-restart" && adoption.adoption !== "unknown") return null;
+    if (adoption.injectedAtMs !== null && typeof adoption.injectedAtMs !== "number") return null;
+    if (typeof adoption.observedClients !== "number" || !Array.isArray(adoption.staleClients)) return null;
+    for (const client of adoption.staleClients) {
+      if (!client || typeof client !== "object" || Array.isArray(client)) return null;
+      const row = client as Record<string, unknown>;
+      if (typeof row.pid !== "number" || typeof row.startedAtMs !== "number") return null;
+    }
+  }
+  for (const key of STARTUP_HEALTH_BOOLEAN_FIELDS) if (typeof row[key] !== "boolean") return null;
+  return payload as StartupHealth;
+}
+
+/** Prefer an attested live verdict and evaluate the local fallback only when live state is absent. */
+export function selectStatusStartupHealth(
+  liveStartup: StartupHealth | null,
+  fallback: () => StartupHealth,
+): StartupHealth {
+  return liveStartup ?? fallback();
+}
+
+/** Build the service summary from the same startup source that `ocx status` selected. */
+export function statusServiceSummary(
+  liveStartup: StartupHealth | null,
+  service: Pick<ReturnType<typeof diagnoseService>, "installed" | "summary">,
+  live: boolean,
+): string {
+  if (liveStartup) {
+    if (liveStartup.protection === "service" && liveStartup.serviceViable) {
+      return `running under the live managed service (logs: ${serviceLogPath()})`;
+    }
+    const state = [
+      liveStartup.serviceInstalled ? "installed" : "absent",
+      liveStartup.serviceRunning ? "running" : "not running",
+      liveStartup.serviceViable ? "viable" : "not viable",
+    ].join(", ");
+    const action = liveStartup.recommendedCommand ? `; run '${liveStartup.recommendedCommand}'` : "";
+    return `live startup reports service ${state}${action} (logs: ${serviceLogPath()})`;
+  }
+  return service.installed && !live
+    ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'`
+    : service.summary;
+}
+
 /**
  * The hub block, or null when this machine is not a hub.
  *
@@ -666,20 +746,19 @@ export async function collectStatus(): Promise<CliStatusView> {
     hostname: config.hostname,
   });
   const bunRuntime = durableBunRuntime();
+  const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
   const service = diagnoseService();
   // A service can be registered and still not serve: the manager reports the job
-  // either way. `live` was already identity-probed a few lines above, so cross-check
-  // rather than print registration as if it were service.
-  const serviceSummary = service.installed && !live
-    ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'`
-    : service.summary;
+  // either way. When the identity-probed live proxy provides an attested startup verdict,
+  // prefer it over a shell-local service-manager probe that lacks the service environment.
+  const serviceSummary = statusServiceSummary(liveStartup, service, Boolean(live));
   const codexShim = diagnoseCodexShim();
   const codexShimSummary = codexShim.summary;
-  const startup = collectStartupHealth(config, {
+  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(config, {
     service,
     shim: codexShim,
     routingKind: getCodexRoutingKind(),
-  });
+  }));
   const codexPlugins = diagnoseCodexBundledPlugins();
   const lastClamp = loadLastEffortClamp();
   const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime);

src/responses/code-mode-helper-compat.ts

@@ -3,13 +3,16 @@ import {
   normalizeApplyPatchDelimiters,
   unwrapFreeformToolInput,
 } from "./apply-patch-envelope";
-import { declaresCodeModeExec } from "../types/tools";
+import { declaresCodeModeExec, isCodeModeMcpDirectName } from "../types/tools";
 import { parseCodeModeShellInput } from "./code-mode-shell-input";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+/** A nested host tool reachable as `tools.<name>` when the flattened name is one identifier. */
+const CODE_MODE_IDENTIFIER_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
 /**
  * Convert a nested Code Mode helper call into unified-exec JavaScript.
  *
@@ -95,6 +98,16 @@ export function compileCodeModeHelperInput(
   if (helperName === "create_goal" || helperName === "get_goal" || helperName === "update_goal") {
     return `const result = await tools.${helperName}(${JSON.stringify(args)});\ntext(result);`;
   }
+  if (isCodeModeMcpDirectName(helperName)) {
+    // Direct `mcp__<server>__<tool>` call under a code-mode catalog: the emitted name IS the
+    // nested host tool's name, so compile to the same `tools.<name>(args)` the model could
+    // have written. Dot access when the name is a clean identifier (the common case); bracket
+    // access otherwise, so a hyphenated server name still addresses the same tool.
+    const target = CODE_MODE_IDENTIFIER_NAME.test(helperName)
+      ? `tools.${helperName}`
+      : `tools[${JSON.stringify(helperName)}]`;
+    return `const result = await ${target}(${JSON.stringify(args)});\ntext(result);`;
+  }
   return `const result = await tools.exec_command(${JSON.stringify(args)});\ntext(result);`;
 }
 

src/responses/custom-tool-compat.ts

@@ -76,7 +76,7 @@ export function routedCustomToolTargetName(
   if (wireName === undefined) return undefined;
   if (names.has(wireName)) return wireName;
   if (!isPlainObject(value) || typeof value.namespace === "string") return undefined;
-  const normalized = normalizeDeclaredToolName(wireName, declaredNames);
+  const normalized = normalizeDeclaredToolName(wireName, declaredNames, undefined, names);
   return normalized !== wireName && names.has(normalized) ? normalized : undefined;
 }