{"record":{"id":"e5ab91c6115424da","repo":"stablyai/orca","slug":"envelope-message","errorCode":null,"errorMessage":"${envelope.message}","messagePattern":"\\$\\{envelope\\.message\\}","errorType":"exception","errorClass":"CodexAppServerUnsupportedError","httpStatus":null,"severity":"warning","filePath":"src/main/codex/codex-app-server-grant-bridge.ts","lineNumber":136,"sourceCode":"  const lastLine = lines.at(-1)\n  let envelope: GrantEntryEnvelope | null = null\n  if (lastLine) {\n    try {\n      envelope = JSON.parse(lastLine) as GrantEntryEnvelope\n    } catch {\n      envelope = null\n    }\n  }\n  if (!envelope) {\n    throw new Error(\n      `codex trust-grant entry produced no result (exit ${spawned.status ?? 'unknown'})${\n        spawned.stderr ? `: ${spawned.stderr.trim().slice(0, 400)}` : ''\n      }`\n    )\n  }\n  if (!envelope.ok) {\n    if (envelope.unsupported) {\n      throw new CodexAppServerUnsupportedError(envelope.message)\n    }\n    if (envelope.errorName === 'CodexAppServerTimeoutError') {\n      throw new CodexAppServerTimeoutError(envelope.message)\n    }\n    throw new Error(envelope.message)\n  }\n  return envelope.result\n}\n","sourceCodeStart":118,"sourceCodeEnd":145,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/codex/codex-app-server-grant-bridge.ts#L118-L145","documentation":"Thrown as CodexAppServerUnsupportedError when the entry child returned a well-formed envelope with ok:false and unsupported:true. The unsupported flag is set by buildGrantEntryEnvelope only when the underlying error is a CodexAppServerUnsupportedError, meaning the spawned codex binary lacks the app-server subcommand or the specific RPC method (hooks/list, config/batchWrite). This is the typed, cacheable capability signal — the only error class the capability cache marks unsupported.","triggerScenarios":"The user's installed codex CLI predates the app-server subcommand; codex app-server exists but lacks hooks/list or config/batchWrite; the entry's runCodexAppServerSession classified an early exit as missing-subcommand via stderrIndicatesMissingAppServer and that bubbled up as unsupported through the envelope.","commonSituations":"User is on an old codex version; codex was installed via a package manager shipping a stale build; a CI environment pins an older codex; the capability cache was reset so the probe re-runs against an old binary.","solutions":["Upgrade the codex CLI to a version that ships the app-server subcommand and the hooks RPCs.","Confirm with: codex app-server --help (missing subcommand surfaces unsupported).","Let the capability cache record this result so repeated probes are suppressed — ensure isCodexAppServerUnsupportedError is the gate, not message matching.","If unsupported is expected and permanent for this host, keep the host on the managed-home lane (ensureRealHomeCodexHookState already falls back to 'unavailable')."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"// Probe capability once before granting:\n// codex app-server --help exit code / stderr tells you if the subcommand exists.\n// Cache the result so repeated grants skip the probe.","typeGuard":"import { isCodexAppServerUnsupportedError } from './codex-app-server-session'\n// isCodexAppServerUnsupportedError(error) === true for this error","tryCatchPattern":"try {\n  runCodexHookTrustGrantSessionSync(request)\n} catch (error) {\n  if (isCodexAppServerUnsupportedError(error)) {\n    // mark capability unsupported; stay on managed lane; do not retry eagerly\n    capabilityCache.setUnsupported(host, 'app-server')\n  } else {\n    throw error\n  }\n}","preventionTips":["Gate real-home hook install on a cached capability probe so old CLIs never reach the grant.","Treat unsupported as permanent (retry interval = Infinity) per getInstallRetryAfterMs.","Surface a clear 'upgrade codex' message to the user when unsupported is first detected.","Re-probe only after a codex version bump, not on every launch."],"tags":["codex","app-server","capability","unsupported","version-compat"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}