@jterrats/open-orchestra 1.0.16 → 1.0.18

package/docs/chat-audit-retention.md

@@ -0,0 +1,76 @@
+# Chat Audit, Retention, and Export
+
+`GH-498-CHAT-AUDIT-RETENTION` defines the compliance layer for workspace chat records.
+
+## Defaults
+
+- Local chat storage persists under `.agent-workflow/chat/v1`.
+- New threads and messages default to `redacted_only` retention and export policy.
+- Logical delete uses tombstones instead of physical removal so evidence actions remain auditable.
+- Export defaults to redacted output.
+
+## Export Scope
+
+The compliance/export layer supports three evidence scopes inside a tenant/workspace:
+
+- `thread`
+- `task`
+- `run`
+
+Exports produce:
+
+- JSON records suitable for machine processing and evidence attachment
+- Markdown suitable for human review and release evidence
+
+For local mode, exports are redacted-only. Even if future retention policies allow raw storage, export policy must explicitly allow raw export before any non-redacted content can leave the store.
+
+Restricted-data detections are export-safe only when represented as sanitized
+metadata. Export JSON and Markdown may include category, rule id, occurrence
+count, redaction marker, decision id, source message id, provider-egress
+decision, and raw-persistence decision. They must not include raw passwords,
+tokens, private keys, payment data, sensitive PII, request bodies, prompt
+samples, ciphertext blobs, wrapped keys, or KMS/vault internals.
+
+If an export encounters restricted values in legacy or future raw-allowed
+records, the export copy is reclassified and redacted before rendering. The
+stored record is not mutated by export, and the export audit event records only
+the sanitized restricted event summary.
+
+## Delete Behavior
+
+- Delete is logical, not physical.
+- Tombstoned threads and messages keep audit metadata.
+- Tombstoned content is not raw exportable.
+- Workspace isolation remains enforced by the chat storage path model and scope filtering.
+
+## Audit Trail
+
+Sensitive lifecycle actions append workflow events:
+
+- `CHAT_EXPORT_RECORDED`
+- `CHAT_DELETE_RECORDED`
+- restricted detections/blocks as sanitized restricted-data audit summaries
+
+Audit metadata should include:
+
+- requesting actor id and role
+- tenant and workspace
+- selected scope kind (`thread`, `task`, `run`)
+- affected task/run/thread identifiers
+- timestamps
+- affected thread/message counts
+- restricted event count and sanitized category/count/marker summaries when
+  restricted values are detected or blocked
+
+## SaaS vs Local
+
+Local mode uses workspace-local files and workflow events as the audit ledger.
+
+SaaS mode will need stronger policy inputs:
+
+- tenant-configured retention classes
+- export authorization policy
+- delete/legal-hold policy
+- centralized audit retention and access control
+
+This story keeps the contract and local behavior explicit so the SaaS implementation can reuse the same policy concepts without changing the chat domain model.

package/docs/chat-provider-provenance-ledger.md

@@ -0,0 +1,75 @@
+# Chat Provider Provenance Ledger
+
+## Purpose
+
+Chat provider provenance records who initiated model-backed work, where it
+belongs, which provider/model executed it, and the usage/cost metadata returned
+by the provider or runtime. The ledger supports SaaS tenant reporting, local
+debugging, budget gates, and audit review without exposing raw prompts or
+provider secrets.
+
+## Dimensions
+
+Each model provenance record is scoped by:
+
+- `tenantId`, `workspaceId`, `task`, `runId`, `phase`, and `sessionId` when
+  available.
+- `role`, `actor`, and `initiatedBy` to distinguish human, parent agent,
+  subagent, and system initiated requests.
+- `provider`, `model`, `requestId`, `responseId`, `promptId`, and
+  `finishReason`.
+- `inputTokens`, `outputTokens`, `estimatedCostUsd`, `usageSource`, and
+  `costSource`.
+
+Missing tenant/workspace metadata falls back to local aggregate buckets so
+existing local workflows remain compatible while SaaS calls can provide full
+scope.
+
+## Chat Message Contract
+
+Chat messages may carry provider metadata in `provenance` when the message is
+created from model output:
+
+- `provider`, `model`, `requestId`, and `responseId` identify the execution.
+- `inputTokens`, `outputTokens`, and `estimatedCostUsd` provide reporting
+  context.
+- `usageSource` and `costSource` indicate whether values came from the provider,
+  runtime, an estimate, or are unavailable.
+
+Persisted chat content remains governed by the existing redaction, retention,
+export, and delete policies. Provenance metadata must not contain raw prompts,
+secrets, authorization headers, provider base URLs, or unredacted sensitive
+payloads.
+
+## Budget And Policy Gates
+
+Budget checks read model provenance events and aggregate by total, role,
+provider, tenant, workspace, actor, initiator, and phase. Provider execution
+should run preflight budget and egress policy checks before model calls. Blocks
+and warnings should record safe metadata only.
+
+## Reporting Defaults
+
+Local usage reports include:
+
+- `totals`
+- `byRole`
+- `byProvider`
+- `byTenant`
+- `byWorkspace`
+- `byActor`
+- `byInitiator`
+- `byPhase`
+
+SaaS reporting can use the same shape for tenant/workspace dashboards. Cost
+values are estimates unless `costSource` is provider-backed pricing data.
+
+## Follow-Up Work
+
+- Wire public/chat API model responses through provider-backed execution once
+  response generation is in scope.
+- Add UI reporting for tenant/workspace usage when SaaS dashboards are ready.
+- Align export/delete behavior with GH-498 so evidence exports include safe
+  ledger metadata only.
+- Apply GH-507 restricted-data decisions before any raw sensitive data can be
+  retained or sent to providers.

package/docs/context-runtime-preprocessing.md

@@ -0,0 +1,37 @@
+# Runtime Context Preprocessing
+
+Runtime subagent delegation builds a bounded preprocessed context bundle before
+rendering spawn prompts. The bundle is embedded in the runtime context manifest
+and is the default context a child runtime should use.
+
+## Reduction Contract
+
+Each file record includes:
+
+- `sourcePath`: workspace-relative source path.
+- `strategy`: `passthrough`, `schema-extraction`, `section-extraction`,
+  `head-tail-truncation`, or `missing`.
+- `originalSize`: original line and byte count.
+- `finalSize`: reduced line and byte count.
+- `omittedContentWarning`: explicit warning when content was reduced or missing.
+
+Delegates may cite full source paths from the bundle, but should avoid loading
+raw files unless the reduced context is insufficient for the assigned work.
+
+## Deterministic Strategies
+
+- Small files pass through unchanged.
+- TypeScript files prefer exported schema and contract declarations.
+- Markdown files prefer relevant sections based on task, role, phase, and
+  delegated ownership paths.
+- Other large files fall back to annotated head/tail truncation.
+
+## Configuration
+
+Runtime preprocessing defaults are line-based and can be configured with:
+
+- `OPEN_ORCHESTRA_RUNTIME_CONTEXT_MAX_LINES_PER_FILE`
+- `OPEN_ORCHESTRA_RUNTIME_CONTEXT_TOTAL_LINE_BUDGET`
+
+The runtime context pack remains available as supplemental search evidence. The
+preprocessed bundle is the prompt-local default.

package/docs/orchestra-mvp.md

@@ -46,7 +46,6 @@ updates still replace only that block.
 
 Open Orchestra should treat skills as demand-loaded capabilities. Main files such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, and `ORCHESTRA.md` should contain a compact index and activation rules, while detailed procedures live in skill files. See [skill-loading-strategy.md](skill-loading-strategy.md).
 
-
 ## Commands
 
 Use the installed CLI form in project documentation and automation:
@@ -270,11 +269,18 @@ Release go/no-go:
 - Confirm `orchestra release check --json` passes the package provenance gate,
   which runs `npm pack --dry-run --json` and rejects private workflow state,
   generated prompts, env files, and missing public package entry points.
+- Confirm `npm run package:validate` passes before publishing. This rebuilds the
+  package dry-run file list without lifecycle scripts and verifies the CLI bin,
+  compiled dist output, legacy and React web console assets, built site assets,
+  docs, rules, skills, package metadata, README, and changelog are included.
 - Confirm GitHub Actions CI is green for the latest pushed HEAD.
 - Confirm installed-package dogfooding passes on `ubuntu-latest`,
   `macos-latest`, and `windows-latest`.
 - Confirm `Create release tag`, site publish, and npm publish workflows are
   successful for the intended release commit.
+- After publish, confirm the registry exposes the exact version from
+  `package.json` with
+  `npm view @jterrats/open-orchestra@$(node -p "require('./package.json').version") version`.
 - Confirm the npm publish workflow authenticates with either a maintainer
   `NPM_TOKEN` that has read-write access plus CI 2FA bypass for
   `@jterrats/open-orchestra`, or npm Trusted Publishing/OIDC configured with
@@ -405,7 +411,6 @@ orchestra workflow clarify-list --run <run-id>
   runs/
 ```
 
-
 ## Stable JSON Contracts
 
 The VS Code Control Center should consume stable JSON outputs instead of parsing human-readable text or duplicating file reads. Current UI-facing commands include:
@@ -496,6 +501,7 @@ The VS Code Control Center scaffold is under `extensions/vscode-open-orchestra`.
 `orchestra estimate` declares the three-mode effort baseline at story start. After the autonomous run completes, `orchestra benchmark` joins the declared estimate with the actual cycle time and quality signals automatically computed from the event log.
 
 Quality signals collected automatically:
+
 - `REVIEW_RECORDED` events → review count, blocking reviews (result=block or severity high/critical)
 - `EVIDENCE_ADDED` events → evidence artifact count
 - `LESSON_RECORDED` events → lesson count

package/docs/public-api-contract.md

@@ -0,0 +1,43 @@
+# Public API Contract
+
+The public `/api/v1` surface is owned by Open Orchestra. It exposes Orchestra
+DTOs and request semantics only; it must not expose provider ids, raw vendor
+payloads, provider credentials, or backend base URLs.
+
+## Workspace And Principal Isolation
+
+- Public API data must be isolated by project workspace.
+- Public API data must also be bound to a principal so threads and messages from
+  one user are not listed or read by another user in the same project.
+- The current `/api/v1` slice uses an explicit local-development auth adapter
+  that reads `x-orchestra-user-id` and optional `x-orchestra-user-name` headers.
+  This is not a production IAM mechanism; production deployments must replace
+  the adapter with session/API-key authentication before public exposure.
+- Routes pass a server-bound auth context into services. Tenant, workspace,
+  task, run, phase, session, actor, provider, model, and backend URL values from
+  the request body or query are rejected and are never authoritative.
+- Storage scope is computed server-side from the workspace root plus principal,
+  so users in the same workspace cannot list, read, or write each other's public
+  threads through `/api/v1`.
+
+## Bounds, Rate Limits, And Idempotency
+
+- Public JSON request bodies are bounded to 64 KiB.
+- Public string fields and headers are bounded before execution: thread titles,
+  message text, request ids, thread ids, cursors, idempotency keys, local-dev
+  principal ids, and display names all have explicit maximum lengths.
+- Side-effecting message writes require `Idempotency-Key`. Thread creation may
+  use `Idempotency-Key`; replays are scoped by workspace and authenticated
+  principal, and conflicts return the stable `idempotency_conflict` error code.
+- `/api/v1` currently enforces process-local per-principal rate limiting and
+  concurrent request admission. Durable, shared rate-limit and idempotency
+  storage is still required before a multi-process or public production rollout.
+- Rate limited requests return `rate_limited` with HTTP 429 and a sanitized
+  message.
+
+## Transport Security
+
+- Public deployments must terminate TLS 1.2+ at the Open Orchestra boundary.
+- Plain HTTP is acceptable only for local development on loopback interfaces.
+- Provider traffic, secrets, and backend topology remain internal and must not
+  be exposed through public API responses.

package/docs/release-test-matrix.md

@@ -65,20 +65,20 @@ GitHub Actions secret.
 
 ## Required Flows
 
-| Flow                   | Command                               | Evidence                                                                                                                                                               |
-| ---------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Source quality gate    | `npm run precommit`                   | lint, typecheck, secret scan, security audit, build, unit tests, workflow validation                                                                                   |
-| Secret scanning gate   | `npm run secret-scan`                 | Gitleaks scan with `.gitleaks.toml` when the binary is installed; lightweight fallback for offline local development                                                   |
-| Duplicate-code gate    | `npm run duplicates`                  | jscpd duplicate-code report with generated/runtime outputs excluded and collection-standards follow-up for duplicated domain lists                                     |
-| Task split guard       | `node --test test/task-split-assessment.test.js` | PO/BA functional oversize, Architect technical complexity, routine small-task non-blocking behavior, and markdown evidence rendering                                    |
-| Sonar quality gate     | GitHub Actions: `Sonar` or local SonarQube import | conditional quality gate for duplication, bugs, code smells, maintainability, coverage readiness, and security hotspots when a Sonar provider is configured           |
-| Browser E2E            | `npm run test:e2e`                    | Playwright checks map scenario acceptance criteria to visible UI state, API persistence, artifact attachment, responsive layout, and recovery behavior                 |
-| Installed package init | `npm run test:e2e:init`               | Installed CLI checks map scenario acceptance criteria to stdout, stderr, exit code, filesystem state, JSON contracts, evidence records, and release-readiness outcomes |
-| Runtime manual queue   | `npm run test:e2e:runtime`            | Temporary-workspace runtime checks prove manual spawn requests queue under delegate pressure and expose queued artifacts through runtime sessions                      |
-| Public site build      | `npm run site:build`                  | production site build                                                                                                                                                  |
-| Release readiness      | `orchestra release check --json`      | `releaseReadiness` and `gaReadiness` report                                                                                                                            |
-| Package contents       | `npm pack --dry-run --json`           | package file list and provenance check                                                                                                                                 |
-| Performance budgets    | `npm run performance:bench -- --json` | CLI and web API timings on a synthetic large workspace                                                                                                                 |
+| Flow                   | Command                                           | Evidence                                                                                                                                                               |
+| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Source quality gate    | `npm run precommit`                               | lint, typecheck, secret scan, security audit, build, unit tests, workflow validation                                                                                   |
+| Secret scanning gate   | `npm run secret-scan`                             | Gitleaks scan with `.gitleaks.toml` when the binary is installed; lightweight fallback for offline local development                                                   |
+| Duplicate-code gate    | `npm run duplicates`                              | jscpd duplicate-code report with generated/runtime outputs excluded and collection-standards follow-up for duplicated domain lists                                     |
+| Task split guard       | `node --test test/task-split-assessment.test.js`  | PO/BA functional oversize, Architect technical complexity, routine small-task non-blocking behavior, and markdown evidence rendering                                   |
+| Sonar quality gate     | GitHub Actions: `Sonar` or local SonarQube import | conditional quality gate for duplication, bugs, code smells, maintainability, coverage readiness, and security hotspots when a Sonar provider is configured            |
+| Browser E2E            | `npm run test:e2e`                                | Playwright checks map scenario acceptance criteria to visible UI state, API persistence, artifact attachment, responsive layout, and recovery behavior                 |
+| Installed package init | `npm run test:e2e:init`                           | Installed CLI checks map scenario acceptance criteria to stdout, stderr, exit code, filesystem state, JSON contracts, evidence records, and release-readiness outcomes |
+| Runtime manual queue   | `npm run test:e2e:runtime`                        | Temporary-workspace runtime checks prove manual spawn requests queue under delegate pressure and expose queued artifacts through runtime sessions                      |
+| Public site build      | `npm run site:build`                              | production site build                                                                                                                                                  |
+| Release readiness      | `orchestra release check --json`                  | `releaseReadiness` and `gaReadiness` report                                                                                                                            |
+| Package contents       | `npm run package:validate`                        | package file list includes bin, dist, web console, site assets, docs, rules, skills, metadata, and changelog                                                           |
+| Performance budgets    | `npm run performance:bench -- --json`             | CLI and web API timings on a synthetic large workspace                                                                                                                 |
 
 ## Network Policy
 

package/docs/restricted-fragment-storage-contract.md

@@ -0,0 +1,147 @@
+# Restricted Fragment Storage Contract
+
+`GH-510-RESTRICTED-FRAGMENT-STORAGE` defines the future storage envelope for
+retained restricted fragments. This contract does not enable retention by
+default and does not add a vault, KMS, or retrieval product surface.
+
+## Scope
+
+Restricted fragment storage is exceptional. It is allowed only when a future
+structured workflow has an approved product need, tenant policy, retention
+class, and security review. Ordinary chat persistence remains redacted-only.
+
+The following values must not be retained raw in transcripts, logs, exports,
+evidence, markdown handoffs, telemetry, or provider requests:
+
+- credentials, passwords, API keys, tokens, secrets, and signing material
+- payment card data, CVV, track data, and payment account identifiers
+- regulated or sensitive PII unless a future structured policy explicitly
+  authorizes encrypted retention
+
+## Storage Boundary
+
+Restricted fragments must be stored outside `.agent-workflow/chat/v1` transcript
+JSONL and outside ordinary chat message tables. Chat records may keep only a
+redacted shadow and a restricted-fragment reference.
+
+The redacted shadow is the only transcript-safe representation:
+
+- fragment id
+- tenant id, workspace id, and source message id
+- classification category and policy id
+- redaction marker and short sanitized summary
+- optional digest of canonical plaintext for dedupe or audit correlation
+- lifecycle status, created timestamp, expiry timestamp, and legal-hold flag
+
+The shadow must not contain raw plaintext, ciphertext, encrypted data keys,
+KMS key ids that reveal tenant topology, provider payloads, or debug samples.
+
+## Envelope Encryption
+
+Each retained fragment uses envelope encryption:
+
+1. A tenant root key is managed by an external KMS or vault.
+2. A workspace key-encryption context is derived from tenant id, workspace id,
+   retention class, and policy id.
+3. A fresh per-fragment data encryption key encrypts the fragment with
+   `AES-256-GCM` or a reviewed equivalent AEAD.
+4. The per-fragment data key is wrapped by the workspace key context.
+5. The ciphertext object stores only ciphertext metadata and the wrapped key
+   reference needed for an authorized decrypt operation.
+
+The envelope metadata must include:
+
+- envelope schema version
+- fragment id and redacted shadow id
+- algorithm, IV/nonce id, authentication tag id, and ciphertext digest
+- wrapped data-key id and key version
+- KMS provider alias and tenant/workspace key scope
+- classification category, retention class, policy id, and purpose
+- creation timestamp, expiry timestamp, and legal-hold flag
+
+The envelope metadata must not include raw plaintext, derived plaintext samples,
+complete provider prompts, route request bodies, or user-supplied secret names.
+
+## Audit Contract
+
+The append-only audit trail must record sanitized lifecycle events:
+
+- `restricted_fragment_detected`
+- `restricted_fragment_shadow_recorded`
+- `restricted_fragment_encrypted`
+- `restricted_fragment_decrypt_denied`
+- `restricted_fragment_restore_attempted`
+- `restricted_fragment_ciphertext_deleted`
+- `restricted_fragment_key_destroyed`
+- `restricted_fragment_crypto_shredded`
+- `restricted_fragment_backup_expiry_pending`
+
+Audit entries include tenant id, workspace id, fragment id, policy id, actor id,
+decision id, category, timestamps, and counts. They never include plaintext,
+ciphertext, wrapped key material, provider payloads, or request bodies.
+
+## Crypto-Shred
+
+Deleting a retained fragment requires both storage deletion and key destruction:
+
+1. mark the redacted shadow as deletion requested;
+2. hard-delete the ciphertext object and index entry;
+3. destroy or disable the fragment data-key binding so decrypt is impossible;
+4. record the KMS/vault destruction receipt or local equivalent;
+5. record backup expiry status because immutable backups may age out later;
+6. record a final `crypto_shredded` audit event.
+
+If raw restricted data was blocked and never persisted, delete reports
+`raw_not_persisted` instead of claiming a ciphertext deletion occurred.
+
+Crypto-shred is complete only when the active ciphertext object is gone and the
+key binding can no longer unwrap the fragment data key. Backups may still retain
+already-encrypted bytes until their retention windows expire, but those bytes
+must remain unrecoverable once key destruction is complete.
+
+## Restore Constraints
+
+Restore is denied by default. A future restore operation must require:
+
+- tenant and workspace authorization
+- policy allowing restore for the exact category and retention class
+- legal basis or break-glass reason
+- active key material that has not been crypto-shredded
+- append-only audit before and after the attempt
+
+Restore must fail closed when the fragment is expired, the key is destroyed, the
+legal hold conflicts with the request, the actor lacks authorization, or the
+policy does not allow raw recovery. Restored plaintext must be streamed only to
+the authorized consumer and must not be written back into transcripts, evidence,
+logs, exports, or provider prompts.
+
+## Export And Compliance
+
+Default chat export remains redacted-only. Export may include redacted shadows
+and audit summaries, but it must not include ciphertext blobs, wrapped keys,
+plaintext, KMS key material, or restoration receipts that expose internals.
+Telemetry, evidence compaction, support bundles, and Markdown reporting follow
+the same rule: only sanitized category, count, marker, decision, and lifecycle
+status data may leave the restricted-fragment boundary.
+
+Logical chat tombstones do not satisfy crypto-shred for retained fragments.
+Compliance delete must distinguish:
+
+- transcript tombstone only
+- `raw_not_persisted`
+- ciphertext hard delete
+- key destroyed
+- crypto-shred complete
+- backup expiry pending
+
+## Implementation Slices
+
+1. Add storage-agnostic domain types and validation for restricted fragment
+   shadows, envelopes, audit events, and delete results.
+2. Teach chat compliance exports to include redacted shadow summaries while
+   excluding ciphertext and wrapped-key metadata.
+3. Add a storage adapter interface for encrypted fragment object stores.
+4. Add a KMS/vault adapter interface for wrap, unwrap, disable, and destroy.
+5. Add delete orchestration that hard-deletes ciphertext before recording key
+   destruction and crypto-shred audit events.
+6. Add restore denial tests before any restore implementation exists.

package/docs/runtime-adapters.md

@@ -75,6 +75,20 @@ OpenAI/Codex provider models are provider-backed execution. `codex-cli` is a
 runtime-native parent session and never becomes a provider API fallback unless a
 future explicit hybrid policy records that decision as evidence.
 
+Before the wrapper creates a provider adapter or sends a request, it evaluates
+provider egress through the security policy boundary. Messages are classified
+through the shared classifier/redaction contract and treated as a `provider`
+sink. Restricted or unsafe-unredacted content is blocked before any provider
+call; only sanitized policy metadata may be recorded as evidence. Provider
+failure messages are sanitized before surfacing so backend base URLs,
+authorization headers, API keys, and token-shaped values are not exposed.
+
+Internal providers such as `ollama` are private-only. `OLLAMA_BASE_URL` must be
+server-configured and point at `localhost`, loopback, link-local, or RFC1918
+private-network IP addresses. Public DNS names and public IPs are rejected by
+policy. Use loopback for local development, or a private address reachable only
+inside the trusted deployment network.
+
 ## Init Modes
 
 Default project init keeps the current compact bootstrap behavior:
@@ -487,13 +501,26 @@ agent path and records that choice in phase provenance.
 
 When no task or role executor is configured and the default executor is
 `generic-runtime`, `auto` and strict `subagents` mode infer the active runtime
-from `OPEN_ORCHESTRA_ACTIVE_RUNTIME`, known parent-runtime environment markers,
-or managed runtime bootstrap files. Codex maps to `codex-cli`, Claude maps to
-`claude-cli`, Cursor maps to `cursor-cli`, Windsurf maps to `windsurf-agent`,
-and VS Code maps to `vscode-agent`.
-
-Explicit selections always take precedence in this order: `--runtime`, task
-override, role override, then `runtimePolicy.defaults.executor`. Automatic
+from `.agent-workflow/active-runtime.json`, then from `OPEN_ORCHESTRA_ACTIVE_RUNTIME`
+as a final fallback for non-hook environments (CI, scripts).
+
+`.agent-workflow/active-runtime.json` is the truthful signal of which AI runtime
+is currently driving the conversation. It is written by the active runtime's
+UserPromptSubmit hook on every session start. `orchestra init --target claude`
+configures Claude's `.claude/settings.json` hook to call
+`orchestra health --runtime claude-cli --json`; `--target cursor` configures the
+equivalent in `.cursor/rules/orchestra-health.mdc`. Manual-setup guidance for
+Codex/VS Code/Windsurf documents the same `orchestra health --runtime <id>`
+pattern that must run at session start. Each hook overwrites the file with its
+own runtime id, so "last writer wins" matches "current parent runtime".
+
+The persisted record has a 24h TTL. Records older than that are ignored and
+inference falls through to the next signal. Codex maps to `codex-cli`, Claude
+maps to `claude-cli`, Cursor maps to `cursor-cli`, Windsurf maps to
+`windsurf-agent`, and VS Code maps to `vscode-agent`.
+
+Explicit selections always take precedence in this order: `--runtime` flag,
+task override, role override, then `runtimePolicy.defaults.executor`. Automatic
 inference never rewrites `.agent-workflow/config.json`; it only affects the
 current planning decision. Set `workflow.phaseExecutionMode` to `single-agent`
 or configure `runtimePolicy.defaults.executor` to override inference for
@@ -501,6 +528,12 @@ deterministic local or CI runs. If `OPEN_ORCHESTRA_ACTIVE_RUNTIME` names an
 unknown runtime, workflow planning fails with supported values and the same
 override options instead of requiring hidden config edits.
 
+File-based inference (reading `target=` from `AGENTS.md`/`CLAUDE.md`/etc.) and
+per-tool environment detection (`CLAUDECODE`, `CODEX_THREAD_ID`,
+`CURSOR_TRACE_ID`, etc.) are intentionally **not** used: instruction files
+describe which runtimes the project supports, not which one is active right
+now, and per-tool env vars can coexist in nested or inherited sessions.
+
 Subagent spawning is fully asynchronous by default. A spawn request returns the
 `sessionId`, request artifact, prompt artifact, expected result artifact, status,
 next lifecycle commands, and quality warnings, then the parent agent should
@@ -519,6 +552,13 @@ workflow after capacity is released. Manual `runtime spawn-request` calls follow
 the same guardrails: `queue` materializes a queued request artifact and session,
 while `reject` fails before creating a delegation artifact.
 
+Default local runtime-native guardrails allow 3 concurrent delegated sessions
+and 3 spawns per task. The separate SaaS-capacity scheduler defaults to 3 active
+runtime leases, 25 queued requests, 2 active requests per provider, and 3 active
+requests per runtime within the evaluated platform, tenant, and workspace
+policies. Hosted deployments should override those thresholds per tenant and
+workspace before enabling runtime-native dispatch.
+
 For multi-squad work, the parent renders one spawn request per independent
 squad/role/phase. Each detached session is tracked independently by `sessionId`;
 completion order is intentionally non-deterministic. Release aggregation,

package/docs/runtime-capacity.md

@@ -0,0 +1,57 @@
+# Runtime Capacity Model
+
+Open Orchestra runtime capacity is modeled as a deterministic local-first
+contract. Local runs use the implicit `local/local/local-workspace` scope; SaaS
+mode requires every request, queue item, lease, event, and snapshot to carry
+tenant and workspace scope.
+
+## Core Concepts
+
+- `RuntimeCapacityScope`: platform, tenant, and workspace identity.
+- `RuntimeWorkloadClass`: interactive, workflow phase, runtime-native spawn,
+  provider-backed phase, background maintenance, or evidence processing.
+- `RuntimeCapacityUnit`: weighted runtime demand, currently enforced by
+  `concurrencyUnits` with optional budget and resource hints.
+- `RuntimeQuotaPolicy`: platform, tenant, and workspace active/queued limits,
+  provider/runtime caps, and queue/reject behavior.
+- `RuntimeWorkerRecord`: registered worker capabilities, tenant affinity,
+  regions, supported providers/runtimes/workload classes, health, capacity, and
+  isolation metadata.
+
+## Scheduler Decisions
+
+`RuntimeCapacityScheduler.schedule()` returns one typed decision:
+
+- `admitted`: a `RuntimeLease` was granted for a specific worker.
+- `queued`: quota or worker capacity can recover and the request is accepted
+  into a scoped queue.
+- `rejected`: the request is invalid or the configured policy does not allow
+  queueing.
+- `deferred`: no eligible worker is available and queueing is disabled.
+
+Evaluation is fail-closed: request validation, SaaS scope, platform quota,
+tenant quota, workspace quota, provider/runtime caps, then worker selection.
+Queue limits are enforced at platform, tenant, and workspace levels before a
+queue decision is returned.
+
+## Load Balancing
+
+Worker selection is constraint-first and score-second. Eligibility checks tenant
+affinity, denied tenants, workload class, runtime/provider support, region and
+data residency, health, heartbeat freshness, open circuits, and available
+capacity. Scoring is deterministic: available capacity, queue depth, failure
+count, region preference, health, and tenant affinity are sorted with worker id
+as the final tie breaker.
+
+## Isolation
+
+SaaS mode rejects missing tenant/workspace scope. Snapshots can be filtered by
+scope so tenant-facing queue evidence does not expose other tenants. Decision
+messages use stable reason codes and user-safe summaries rather than worker
+internals, queue depths from other tenants, paths, or provider details.
+
+## Current Boundary
+
+This story intentionally keeps capacity state in memory. Hosted queues,
+transactional worker leases, tenant-secret routing, and data residency
+persistence remain follow-up architecture and security work before SaaS release.