fix(orchestrator): require a real production service

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- Made contextual-orchestrator briefing requests fail closed unless an authenticated endpoint is configured. Deterministic generated text is restricted to explicit `SCOPEWEAVE_DEV=1`, message/provider responses are bounded and validated, and non-loopback HTTP transport is rejected.
 - Made `SCOPEWEAVE_JWT_SECRET` mandatory at startup and rejected weak or
   unexpanded placeholder values so production deployments fail closed.
 - Neutralized audit-log CSV formulas even when executable prefixes are hidden

docs/orchestrator-production.md

@@ -0,0 +1,68 @@
+# contextual-orchestrator Production Contract
+
+ScopeWeave delegates AI briefing work to `contextual-orchestrator`; it does not
+silently replace unavailable production inference with deterministic text.
+
+## Required environment
+
+```text
+ORCHESTRATOR_URL=https://orchestrator.example
+ORCHESTRATOR_TOKEN=<secret>
+ORCHESTRATOR_MODEL=contextual-orchestrator
+```
+
+`ORCHESTRATOR_URL` is a provider **origin**, not an arbitrary request URL. It
+must not contain user-info credentials, a non-root path, a query string, or a
+fragment. ScopeWeave owns the fixed `/v1/chat/completions` request path and keeps
+bearer credentials in `ORCHESTRATOR_TOKEN`; operator URL text therefore cannot
+silently alter request routing or mix endpoint authority with credentials.
+Custom ports remain valid because they are part of the origin.
+
+Production requests fail closed when the endpoint or bearer token is absent.
+Non-loopback HTTP endpoints are rejected, requests are bounded to 120 seconds,
+message count and content size are validated, provider payloads are not exposed
+in errors, and an empty or malformed assistant response is never reported as a
+successful briefing.
+
+Provider response bodies have a hard 1 MiB caller-side byte budget **while they
+are being read**. An oversized numeric `Content-Length` is rejected before body
+allocation; when the header is absent or inaccurate, the stream reader counts
+bytes incrementally, cancels the body as soon as the budget is exceeded, and
+never buffers an unbounded provider payload before applying the limit. Empty,
+non-stream-readable, malformed-length, non-JSON, oversized, or structurally
+invalid responses fail with stable operator-safe errors rather than exposing
+provider payload details.
+
+The deterministic adapter is available only when `SCOPEWEAVE_DEV=1` and the
+endpoint is absent. That variable must never be set in staging or production.
+
+## Orchestration responsibility
+
+ScopeWeave intentionally sends only a versioned OpenAI-compatible request to
+the orchestration service. Model selection, single-model versus multi-agent
+allocation, task decomposition, role-specific reasoning effort, recursion
+limits, access lists, synthesis, and verification belong to
+`contextual-orchestrator`, where they can be evaluated and evolved centrally.
+This separation is consistent with learned coordination research: Conductor
+learns task decompositions, worker assignments, communication topologies, and
+recursive test-time scaling; TRINITY adaptively assigns Thinker, Worker, and
+Verifier roles over multiple turns; Fugu operationalizes learned orchestration
+behind one model-compatible API.
+
+ScopeWeave therefore does not hard-code a local fake solver, fixed topology, or
+provider-specific bypass. Changes to orchestration policy require benchmarked
+ablation evidence in `contextual-orchestrator`, including single-model,
+parallel, sequential, hierarchical, recursive, and verifier-assisted paths.
+
+## APA 7th references
+
+Nielsen, S., Cetin, E., Schwendeman, P., Sun, Q., Xu, J., & Tang, Y. (2025).
+*Learning to orchestrate agents in natural language with the Conductor*.
+arXiv. https://doi.org/10.48550/arXiv.2512.04388
+
+Sakana AI. (2026). *Sakana Fugu: Multi-agent system as a model*.
+https://sakana.ai/fugu/
+
+Xu, J., Sun, Q., Schwendeman, P., Nielsen, S., Cetin, E., & Tang, Y. (2025).
+*TRINITY: An evolved LLM coordinator*. arXiv.
+https://doi.org/10.48550/arXiv.2512.04695

package.json

@@ -13,9 +13,9 @@
     "coverage": "npm run test:coverage",
     "server": "node server/server.mjs",
     "test:api": "node tests/api/auth-secret.test.mjs && node tests/api/smoke.mjs && node tests/api/ratelimit.test.mjs && node tests/api/attachment-status.test.mjs && node tests/api/session-revocation.test.mjs",
-    "test:unit": "node tests/unit/analytics.test.mjs && node tests/unit/cpm.test.mjs && node tests/unit/baseline-compare.test.mjs && node tests/unit/workload.test.mjs && node tests/unit/cost-evm.test.mjs && node tests/unit/msproject.test.mjs && node tests/unit/auth-password.test.mjs && node tests/unit/editor-unsaved.test.mjs && node tests/unit/static-coverage-evidence.test.mjs && node tests/unit/dep-types.test.mjs && node tests/unit/weekly-report.test.mjs && node tests/unit/clearfolio.test.mjs && node tests/unit/clearfolio-adapter-mock-hmac.test.mjs && node tests/unit/sprint-stats.test.mjs && node tests/unit/burndown.test.mjs && node tests/unit/pm-analysis.test.mjs && node tests/unit/cloud-sync-security.test.mjs && node tests/unit/attachment-status.test.mjs && node tests/unit/clearfolio-status-signal.test.mjs && node tests/unit/coverage-script-contract.test.mjs",
-    "test:coverage": "c8 --all --include=app.js --include=cloud-sync.js --include=scripts/ci/static_coverage_evidence.mjs --include=server/attachment_status.mjs --include=server/app.mjs --include=server/auth.mjs --include=server/clearfolio.mjs --reporter=json --reporter=json-summary npm run test:coverage:cases",
-    "test:coverage:cases": "node tests/unit/coverage-script-contract.test.mjs && node tests/unit/attachment-status.test.mjs && node tests/unit/clearfolio-status-signal.test.mjs && node tests/unit/clearfolio-adapter-mock-hmac.test.mjs && node tests/unit/msproject.test.mjs && node tests/unit/auth-password.test.mjs && node tests/unit/editor-unsaved.test.mjs && node tests/unit/static-coverage-evidence.test.mjs && npm run test:api",
+    "test:unit": "node tests/unit/analytics.test.mjs && node tests/unit/cpm.test.mjs && node tests/unit/baseline-compare.test.mjs && node tests/unit/workload.test.mjs && node tests/unit/cost-evm.test.mjs && node tests/unit/msproject.test.mjs && node tests/unit/auth-password.test.mjs && node tests/unit/editor-unsaved.test.mjs && node tests/unit/static-coverage-evidence.test.mjs && node tests/unit/dep-types.test.mjs && node tests/unit/weekly-report.test.mjs && node tests/unit/clearfolio.test.mjs && node tests/unit/clearfolio-adapter-mock-hmac.test.mjs && node tests/unit/orchestrator.test.mjs && node tests/unit/orchestrator-coverage.test.mjs && node tests/unit/sprint-stats.test.mjs && node tests/unit/burndown.test.mjs && node tests/unit/pm-analysis.test.mjs && node tests/unit/cloud-sync-security.test.mjs && node tests/unit/attachment-status.test.mjs && node tests/unit/clearfolio-status-signal.test.mjs && node tests/unit/coverage-script-contract.test.mjs",
+    "test:coverage": "c8 --all --include=app.js --include=cloud-sync.js --include=scripts/ci/static_coverage_evidence.mjs --include=server/attachment_status.mjs --include=server/app.mjs --include=server/auth.mjs --include=server/clearfolio.mjs --include=server/orchestrator.mjs --reporter=json --reporter=json-summary npm run test:coverage:cases",
+    "test:coverage:cases": "node tests/unit/coverage-script-contract.test.mjs && node tests/unit/attachment-status.test.mjs && node tests/unit/clearfolio-status-signal.test.mjs && node tests/unit/clearfolio-adapter-mock-hmac.test.mjs && node tests/unit/orchestrator.test.mjs && node tests/unit/orchestrator-coverage.test.mjs && node tests/unit/msproject.test.mjs && node tests/unit/auth-password.test.mjs && node tests/unit/editor-unsaved.test.mjs && node tests/unit/static-coverage-evidence.test.mjs && npm run test:api",
     "test:e2e": "playwright test",
     "test:e2e:headed": "playwright test --headed",
     "test:e2e:cloud": "playwright install chromium && playwright test tests/e2e/cloud.spec.js",