feat: show contextual-orchestrator envelope fail-closed (v0.84.0)

AGENTS.md

@@ -37,9 +37,12 @@ reimplementing them:
   contract for calibrated measurement (`tepp_client.py`) -- never
   reimplement TEPP's model here.
 - [contextual-orchestrator](https://github.com/ContextualWisdomLab/contextual-orchestrator)
-  for LLM adjudication (`adjudication_client.py`) -- never call a raw LLM
+  for LLM adjudication (`adjudication_client.py`) and the buyer-facing
+  Orchestration port (`orchestrator_client.py`) -- never call a raw LLM
   API directly from this repo; go through the orchestrator so
   reasoning-effort allocation and cost attribution stay centralized.
+  A missing host or `invalid_mode` is fail-closed, never an invented
+  completion or a theta.
 
 Before adding a new dependency, check whether an existing org repo already
 does it (`gh repo list ContextualWisdomLab`).

ARCHITECTURE.md

@@ -66,6 +66,7 @@ flowchart LR
 | `adjudication_client.py` | Pluggable LLM-judgment channel (`Null` default, `ContextualOrchestrator` real impl) |
 | `image_content.py` | Pluggable vision channel: OCR + object recognition/tagging for embedded images (`Null` default, `OpenAiCompatibleVisionClient` real impl) |
 | `tepp_client.py` | TEPP's published `AnalysisRunRequest` wire contract, pluggable transport |
+| `orchestrator_client.py` | Fail-closed portable task envelope (`auto` structured / `verify` checked; never invent a completion or a theta) |
 | `rankweave_client.py` | Fail-closed RankWeave ranking port (`weighted_reciprocal_rank_fuse` in-process; never invent a fused score or a theta) |
 | `reconstruct.py` | The pipeline: group → candidate window → score → fuse → thread |
 | `lineage_persistence.py` | Flattens reconstruct trees into `post_lineage_edge` row specs (parent, child, fused_score) |
@@ -89,12 +90,11 @@ flowchart LR
 > `TaskOrchestrator.route_and_verify`, which as of this writing is still
 > an open, unmerged upstream PR
 > (`ContextualWisdomLab/contextual-orchestrator#149`). Until it merges,
-> the four adjudication/chat tests that exercise `mode="verify"` against
-> a real orchestrator fail with `invalid_mode` (the deployed `main` only
-> accepts `auto`/`route`/`conduct`) -- confirmed by reproducing the same
-> `400` directly against the orchestrator's own `/v1/chat/completions`,
-> not caused by anything in this repo. `mode="route"` (every other
-> pluggable client) is unaffected.
+> a live `verify` submit can return `invalid_mode` (deployed `main`
+> accepts `auto`/`route`/`conduct`). The buyer-facing Orchestration port
+> (ADR 0025) fail-closes that as `orchestrator_invalid_mode` and never
+> invents a completion or a 0.0 confidence. `mode="auto"` structured
+> consumers are unaffected.
 
 ## Design decisions worth naming
 
@@ -123,6 +123,13 @@ flowchart LR
   `RankWeaveNotAvailable`. `GET /api/rankings` then returns
   `rankweave_not_available` and an empty ranking list. Hidden posts
   are omitted from every channel. See ADR 0024.
+- **contextual-orchestrator is a fail-closed envelope, not a raw LLM.**
+  `orchestrator_client.py`'s default transport raises
+  `OrchestratorNotAvailable`. `GET /api/orchestration` then returns
+  `orchestrator_not_available` and an empty envelope list. Home GET
+  never POSTs a completion. `invalid_mode` is
+  `orchestrator_invalid_mode`, never a fabricated 0.0 confidence.
+  See ADR 0025.
 
 ## Standards and citations
 

CHANGELOG.d/0.84.0-orchestrator-fail-closed-envelope.md

@@ -0,0 +1,10 @@
+# 0.84.0 — Fail-closed contextual-orchestrator envelope
+
+## Added
+
+- Home Orchestration panel publishes the portable task envelope
+  (ADR 0025). After login with the host unset, Demo Analyst sees
+  **Orchestration · contextual-orchestrator not available**. When the
+  port is configured, the next actions are **Structured work uses auto**
+  and **Checked judgment uses verify**. Never invent a completion or a
+  theta.

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.84.0] - 2026-08-17
+
+### Added
+
+- Home Orchestration panel publishes the portable task envelope
+  (ADR 0025). After login with the host unset, Demo Analyst sees
+  **Orchestration · contextual-orchestrator not available**. When the
+  port is configured, the next actions are **Structured work uses auto**
+  and **Checked judgment uses verify**. Never invent a completion or a
+  theta.
+
 ## [0.75.0] - 2026-08-17
 
 ### Added

README.md

@@ -43,7 +43,8 @@ this repo.
 
 The optional LLM-adjudication channel calls
 [contextual-orchestrator](https://github.com/ContextualWisdomLab/contextual-orchestrator)
-(`lineageweave/adjudication_client.py`). Tree assembly reuses
+(`lineageweave/adjudication_client.py` and the fail-closed
+Orchestration port in `orchestrator_client.py`). Tree assembly reuses
 [ThreadWeave](https://github.com/ContextualWisdomLab/ThreadWeave) (JWZ
 message threading) and channel fusion reuses
 [RankWeave](https://github.com/ContextualWisdomLab/RankWeave) (weighted

backend/app/main.py

@@ -55,6 +55,7 @@
 from lineageweave.post_summary import ContextualOrchestratorPostSummaryClient, NullPostSummaryClient
 from lineageweave.relation_verification import NullRelationVerificationClient, SearxngRelationVerificationClient
 from lineageweave.rankweave_client import build_rankweave_client
+from lineageweave.orchestrator_client import build_orchestrator_client
 
 from backend.app.activity_stream import (
     create_valkey_client,
@@ -242,6 +243,15 @@ def _rankweave_client():
     return build_rankweave_client(disabled=load_settings().rankweave_disabled)
 
 
+def _orchestrator_status_client():
+    """Fail-closed envelope unless URL and key are both set (ADR 0025)."""
+    settings = load_settings()
+    return build_orchestrator_client(
+        base_url=settings.orchestrator_base_url,
+        api_key=settings.orchestrator_api_key,
+    )
+
+
 def _can_see_post(account: CurrentAccount, post: asyncpg.Record) -> bool:
     """ABAC: public rows are visible; private rows require same-corp affiliation."""
     if post["visibility_code"] == "public":
@@ -1150,3 +1160,16 @@ async def read_rankings(
     return _rankweave_client().as_api_payload(
         posts, can_see_post=lambda _row: True
     )
+
+
+@app.get("/api/orchestration")
+async def read_orchestration(
+    account: CurrentAccount = Depends(get_current_account),
+) -> dict[str, Any]:
+    """Portable contextual-orchestrator envelope (ADR 0025).
+
+    Missing host or key is fail-closed. Never invents a completion, a
+    confidence, or a theta. Home GET does not POST a chat completion.
+    """
+    _require_post_read(account)
+    return _orchestrator_status_client().as_api_payload()

backend/tests/test_config.py

@@ -31,3 +31,11 @@ def test_rankweave_disabled_defaults_off(monkeypatch) -> None:
 def test_rankweave_disabled_flag_is_opt_in(monkeypatch) -> None:
     monkeypatch.setenv("RANKWEAVE_DISABLED", "1")
     assert load_settings().rankweave_disabled is True
+
+
+def test_orchestrator_credentials_default_empty(monkeypatch) -> None:
+    monkeypatch.delenv("ORCHESTRATOR_BASE_URL", raising=False)
+    monkeypatch.delenv("ORCHESTRATOR_API_KEY", raising=False)
+    settings = load_settings()
+    assert settings.orchestrator_base_url == ""
+    assert settings.orchestrator_api_key == ""

docs/adr/0025-orchestrator-fail-closed-envelope.md

@@ -0,0 +1,58 @@
+# ADR 0025 — Fail-closed contextual-orchestrator task envelope
+
+**Decision status:** Accepted
+**Date:** 2026-08-17
+
+## Context
+
+Issue #79 requires a versioned fail-closed REST adapter until reviewed
+upstream `contextual-orchestrator` main exposes the required portable
+task envelope. Structured extraction already requests `auto` (ADR 0013).
+Checked judgment (lineage adjudication, citation-bearing chat) still
+requests `verify`. Deployed upstream `main` accepts
+`auto` / `route` / `conduct`; `verify` can return `invalid_mode`
+until `ContextualWisdomLab/contextual-orchestrator#149` lands.
+
+A missing host, a missing key, or `invalid_mode` must not become an
+invented completion, a confidence of 0.0, or a TEPP theta. RankWeave
+status stays on ADR 0024. TEPP stays on #214. This slice does not
+bind demo Keycloak to production Keyverse.
+
+## Decision
+
+1. Consume the orchestrator only through `OrchestratorClient`. The
+   default transport raises `OrchestratorNotAvailable`.
+   `build_orchestrator_client` publishes the envelope only when both
+   `ORCHESTRATOR_BASE_URL` and `ORCHESTRATOR_API_KEY` are set.
+2. The portable envelope is closed (`additionalProperties` stay out):
+   `contract_version`, `task_kind`, `mode`, `reasoning_effort`,
+   `prompt_hash`, `access_list`. Structured work uses `auto` /
+   `medium`. Checked judgment uses `verify` / `high`.
+3. `GET /api/orchestration` (`post_read`) returns buyer status. Home
+   GET never POSTs `/v1/chat/completions`. An `invalid_mode` transport
+   error is `orchestrator_invalid_mode`, never a fabricated score.
+4. After login, Orchestration sits above Rankings. Unavailable copy is
+   **Orchestration · contextual-orchestrator not available**. An
+   accepted row names **Structured work uses auto** and
+   **Checked judgment uses verify**.
+
+## Consequences
+
+Demo compose without orchestrator credentials fail-closes on home.
+Wiring a live submit transport is additive. Adjudication still owns
+pair-wise `verify` calls; this port does not invent their verdicts.
+
+## References
+
+Omidvar, H., & Akhlaghi, V. (2026). *A communication-theoretic
+framework for LLM agents: Cost-aware adaptive reliability* [Preprint].
+arXiv. https://doi.org/10.48550/arXiv.2605.09121
+
+Tang, Y., Cetin, E., Xu, J., Sun, Q., Nielsen, S., Richard, V., Goda,
+H., Tymchenko, I., Nguyen, N., Lee, H., Ashiga, M., Kotyan, S.,
+Kuroki, S., & Clanuwat, T. (2026). *Sakana Fugu technical report*
+[Technical report]. arXiv. https://doi.org/10.48550/arXiv.2606.21228
+
+Contextual Wisdom Lab. (2026). *Contextual orchestrator* [Software
+documentation].
+https://github.com/ContextualWisdomLab/contextual-orchestrator

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "0.75.0",
+  "version": "0.84.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

frontend/src/App.test.tsx

@@ -65,6 +65,16 @@ describe("App, authenticated", () => {
         fused_rank: number;
       }[];
     };
+    orchestration?: {
+      status?: "accepted" | "unavailable";
+      status_reason?: string | null;
+      envelopes?: {
+        task_kind: string;
+        mode: string;
+        reasoning_effort: string;
+        next_action: string;
+      }[];
+    };
     chatUnavailable?: boolean;
     searchUnavailable?: boolean;
     verificationEvidenceUrl?: string | null;
@@ -228,6 +238,21 @@ describe("App, authenticated", () => {
           }),
         );
       }
+      if (url.endsWith("/api/orchestration")) {
+        const orchestration = options?.orchestration ?? {
+          status: "unavailable" as const,
+          status_reason: "orchestrator_not_available",
+          envelopes: [],
+        };
+        return Promise.resolve(
+          jsonResponse({
+            port: "contextual_orchestrator",
+            status: orchestration.status,
+            status_reason: orchestration.status_reason,
+            envelopes: orchestration.envelopes ?? [],
+          }),
+        );
+      }
       if (url.includes("/api/reports/compare/") && method === "GET") {
         return Promise.resolve(
           jsonResponse({
@@ -1273,6 +1298,47 @@ describe("App, authenticated", () => {
     expect(screen.queryByText("Pricing renegotiation: revised quote sent")).not.toBeInTheDocument();
   });
 
+  it("names orchestrator unavailability instead of inventing a completion", async () => {
+    stubBackend();
+    render(<App />);
+
+    expect(
+      await screen.findByText("Orchestration · contextual-orchestrator not available"),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("Structured work uses auto")).not.toBeInTheDocument();
+    expect(screen.queryByText("Checked judgment uses verify")).not.toBeInTheDocument();
+  });
+
+  it("names the accepted auto and verify envelopes without inventing a completion", async () => {
+    stubBackend({
+      orchestration: {
+        status: "accepted",
+        status_reason: null,
+        envelopes: [
+          {
+            task_kind: "structured",
+            mode: "auto",
+            reasoning_effort: "medium",
+            next_action: "Structured work uses auto",
+          },
+          {
+            task_kind: "checked_judgment",
+            mode: "verify",
+            reasoning_effort: "high",
+            next_action: "Checked judgment uses verify",
+          },
+        ],
+      },
+    });
+    render(<App />);
+
+    expect(await screen.findByText("Structured work uses auto")).toBeInTheDocument();
+    expect(screen.getByText("Checked judgment uses verify")).toBeInTheDocument();
+    expect(
+      screen.queryByText("Orchestration · contextual-orchestrator not available"),
+    ).not.toBeInTheDocument();
+  });
+
   it("opens an accepted ranking hit without inventing a fused score", async () => {
     stubBackend({
       rankings: {

frontend/src/App.tsx

@@ -25,6 +25,7 @@ import {
   fetchPeriodReportIndex,
   fetchPeriodReports,
   fetchPosts,
+  fetchOrchestration,
   fetchRankings,
   fetchRelatedEntity,
   fetchRelatedKeymen,
@@ -50,6 +51,7 @@ import {
   type PeriodReports,
   type PostLineage,
   type PostSummary,
+  type OrchestrationStatus,
   type RankingList,
   type RelatedNode,
   type VocEvidence,
@@ -1313,6 +1315,51 @@ function PostDetailPopup({
   );
 }
 
+function OrchestrationPanel({ accessToken }: { accessToken: string }) {
+  const [status, setStatus] = useState<OrchestrationStatus | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setError(null);
+    fetchOrchestration(accessToken)
+      .then(setStatus)
+      .catch((err) => setError(String(err)));
+  }, [accessToken]);
+
+  return (
+    <section className="popup-section lineage-home" aria-label="Orchestration">
+      <div className="lineage-home-header">
+        <h2>Orchestration</h2>
+        {status && (
+          <span className="post-badge">
+            {status.status === "accepted"
+              ? "contextual-orchestrator"
+              : `contextual-orchestrator · ${status.status_reason ?? "unavailable"}`}
+          </span>
+        )}
+      </div>
+      {error && <p className="error">{error}</p>}
+      {status === null && !error && <p>Loading orchestration...</p>}
+      {status && status.status === "unavailable" && (
+        <p className="popup-placeholder">Orchestration · contextual-orchestrator not available</p>
+      )}
+      {status && status.status === "accepted" && status.envelopes.length === 0 && (
+        <p className="popup-placeholder">No accepted orchestration envelope.</p>
+      )}
+      {status && status.envelopes.length > 0 && (
+        <ul className="ticket-list" aria-label="Accepted orchestration envelopes">
+          {status.envelopes.map((envelope) => (
+            <li key={envelope.task_kind} className="ticket-list-item">
+              <span className="ticket-title">{envelope.next_action}</span>
+              <span className="post-badge">{envelope.mode}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
+
 function RankingsPanel({
   accessToken,
   onSelectPost,
@@ -1689,6 +1736,7 @@ function PostList({ accessToken }: { accessToken: string }) {
 
   return (
     <>
+      <OrchestrationPanel accessToken={accessToken} />
       <RankingsPanel accessToken={accessToken} onSelectPost={setSelectedPostId} />
       <CalendarPanel accessToken={accessToken} onSelectPost={setSelectedPostId} />
       <ReportsPanel accessToken={accessToken} canRebuild={canRebuild} onSelectPost={setSelectedPostId} />

frontend/src/api.ts

@@ -515,3 +515,21 @@ export interface RankingList {
 export function fetchRankings(accessToken: string): Promise<RankingList> {
   return backendFetch("/api/rankings", accessToken);
 }
+
+export interface OrchestrationEnvelope {
+  task_kind: string;
+  mode: string;
+  reasoning_effort: string;
+  next_action: string;
+}
+
+export interface OrchestrationStatus {
+  port: string;
+  status: "accepted" | "unavailable";
+  status_reason: string | null;
+  envelopes: OrchestrationEnvelope[];
+}
+
+export function fetchOrchestration(accessToken: string): Promise<OrchestrationStatus> {
+  return backendFetch("/api/orchestration", accessToken);
+}