@synapsor/runner 1.0.0 → 1.1.0

package/docs/README.md

@@ -6,6 +6,16 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 01 Quickstart
 
+- Audit a deliberately risky database MCP surface without cloning the repo or
+  connecting a database:
+
+  ```bash
+  npx -y @synapsor/runner audit --example dangerous-db-mcp
+  ```
+
+  Then use [MCP Audit](mcp-audit.md) to inspect your own tool manifest, remote
+  MCP endpoint, or stdio server. The audit is useful independently of whether
+  you adopt Runner.
 - [README](../README.md): audit-first proof, no-database demo, safety diagram,
   and the shortest own-database path.
 - [Troubleshooting First Run](troubleshooting-first-run.md): common first-run
@@ -98,9 +108,12 @@ no-database demo, wire your database, then read deeper concepts.
 
 - [Current Scope](current-scope.md): compact v0.1 scope summary.
 - [Current Limitations](limitations.md): intentional safety limits.
-- [Production-Candidate Guide](production.md): single-node OSS deployment
-  scope, database roles, receipt grants, local ledger backup, restart behavior,
-  Docker/systemd shapes, TLS, and release-gate expectations.
+- [Production-Candidate Guide](production.md): single-node and bounded-fleet
+  OSS deployment scope, database roles, receipt grants, restart
+  behavior, Docker/systemd shapes, TLS, and release-gate expectations.
+- [Running A Small Runner Fleet](running-a-runner-fleet.md): tested two-Runner
+  topology, claim-bound sessions, pools, fleet rate limits, quorum, metrics,
+  dead letters, backup/restore/retention, and kill/recovery evidence.
 - [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
 - [OSS Runner Vs Synapsor Cloud](oss-vs-cloud.md): detailed product and
   operational boundary.

package/docs/capability-authoring.md

@@ -136,6 +136,7 @@ reviewed runner JSON capabilities. Current parity:
 | proposal `transition_guards` | `TRANSITION status ALLOW pending -> approved\|rejected` or `TRANSITION status FROM current_status ALLOW open -> closed` | 0.1.8 | Values are state strings; use `|` for multiple target states. |
 | proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | If omitted, DSL emits an explicit weak-guard acknowledgement. Prefer a real row-version column. |
 | proposal `approval` | `APPROVAL ROLE billing_lead` | 0.1 | Local mode records the required role; enforcement is still outside the model-facing MCP tool. |
+| proposal `approval.required_approvals` | `REQUIRE 2 APPROVALS` | 1.1 | Optional 1..10 distinct-reviewer quorum; defaults to 1. |
 | proposal `writeback` | `WRITEBACK DIRECT SQL`, `WRITEBACK APP HANDLER EXECUTOR name`, `WRITEBACK CLOUD WORKER`, `WRITEBACK NONE` | 0.1.7 | Handler URLs/tokens stay in `synapsor.runner.json`; contracts carry only the handler name. |
 | evidence options | `REQUIRE EVIDENCE` | 0.1 | Detailed evidence sources/handle prefixes are not expressible in DSL yet; use embedded JSON or generated contract JSON for those. |
 
@@ -285,7 +286,7 @@ surface.
     "late_fee_cents": { "minimum": 0, "maximum": 10000 }
   },
   "conflict_guard": { "column": "updated_at" },
-  "approval": { "mode": "human", "required_role": "billing_lead" }
+  "approval": { "mode": "human", "required_role": "billing_lead", "required_approvals": 2 }
 }
 ```
 

package/docs/current-scope.md

@@ -2,7 +2,7 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current `1.0` scope:
+Current `1.1` scope:
 
 - local semantic MCP tools for Postgres/MySQL-backed business actions;
 - schema inspection and guided config generation;
@@ -12,6 +12,9 @@ Current `1.0` scope:
 - app-owned `http_handler` and `command_handler` executors for richer approved
   business transactions;
 - stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
+- a bounded small-fleet shape with asymmetric claim-bound sessions, shared
+  Postgres review state, source pools, fleet rate limits, readiness, protected
+  metrics, verified quorum review, dead letters, and backup/restore/retention;
 
 Stable `1.x` compatibility covers the documented `synapsor-runner` binary,
 config schema version `1`, result envelope v2 with v1 opt-out, stdio/Streamable
@@ -26,4 +29,5 @@ Out of scope:
 - generic multi-row SQL writeback;
 - physical branching of external Postgres/MySQL;
 - self-hosted Synapsor Cloud;
+- unbounded or multi-region shared-ledger scale and a managed Runner fleet;
 - production SLA or compliance certification.

package/docs/dsl-reference.md

@@ -148,6 +148,7 @@ patched column. Values may be identifiers or quoted strings.
 
 ```sql
   APPROVAL ROLE billing_lead
+  REQUIRE 2 APPROVALS
   AUTO APPROVE WHEN amount_cents <= 2500
   LIMIT 20 PER DAY
   LIMIT TOTAL 100000 PER DAY
@@ -158,6 +159,12 @@ patched column. Values may be identifiers or quoted strings.
 approval identity is operator-provided; enterprise identity/RBAC belongs to the
 Cloud boundary.
 
+`REQUIRE n APPROVALS` is optional and accepts 1 through 10. It compiles to the
+canonical `approval.required_approvals` field. The default is 1. Each slot
+requires a distinct verified subject; duplicate subjects fail with
+`APPROVER_ALREADY_COUNTED`. Apply/workers remain blocked until `n/N`, rejection
+is terminal, and policy auto-approval is deferred when `n > 1`.
+
 `AUTO APPROVE WHEN field <= non_negative_integer` is supported only for a
 numeric patched field and must follow `APPROVAL ROLE`. Its maximum cannot exceed
 the field's `BOUND`. Policy approval still does not apply the write.

package/docs/http-mcp.md

@@ -70,7 +70,9 @@ cors: disabled
 sessions: in-memory
 ```
 
-Use `/mcp` as the MCP endpoint. Health is available at `/healthz`.
+Use `/mcp` as the MCP endpoint. Cheap process liveness is available at
+`/healthz`; dependency readiness is available at `/readyz`. When separately
+enabled and authorized, OpenMetrics is available at `/metrics`.
 
 ## TLS And mTLS
 
@@ -147,6 +149,7 @@ variable name. It does not print token values or database URLs.
 ```bash
 curl -i http://127.0.0.1:8766/healthz
 curl -i http://127.0.0.1:8765/healthz
+curl -i http://127.0.0.1:8766/readyz
 ```
 
 The health endpoint is secret-free:

package/docs/limitations.md

@@ -1,6 +1,7 @@
 # Limitations
 
-Synapsor Runner is intentionally narrow in the current alpha.
+Synapsor Runner is intentionally narrow. Version 1.1 adds a bounded small-fleet
+shape; it does not claim Synapsor Cloud scale or an enterprise SLA.
 
 ## Supported
 
@@ -8,7 +9,13 @@ Synapsor Runner is intentionally narrow in the current alpha.
 - Local read and proposal tools.
 - Local SQLite evidence/proposal/query-audit/replay store by default.
 - Optional shared Postgres proposal/evidence/replay runtime store for MCP serving.
-- Human approval through CLI commands.
+- Asymmetric claim-bound Streamable HTTP sessions and explicit readiness.
+- Native Postgres/MySQL source pools and operational/fleet-wide rate limits.
+- Verified operator approval through CLI, optional distinct-reviewer quorum,
+  and shared local review UI reads.
+- Separately protected scrapeable metrics and dead-letter recovery commands.
+- Shared-ledger backup/digest verification, clean restore, and
+  archive-before-retention.
 - Public protocol objects:
   - `synapsor.change-set.v1`
   - `synapsor.writeback-job.v1`
@@ -56,7 +63,8 @@ truth for the model-facing tools.
 - Model-callable approval or commit tools.
 - Generic MCP firewall behavior.
 - Prompt-injection prevention.
-- High availability, SLA, compliance certification, or production support guarantee.
+- Unbounded/high-throughput or multi-region ledger scale.
+- Managed fleet, SLA, compliance certification, or production support guarantee.
 
 ## Important External Database Semantics
 
@@ -78,9 +86,15 @@ It does not mean external Postgres/MySQL time travel. Runner cannot reconstruct
 arbitrary historical rows that were never captured as evidence, and it does not
 provide `AS OF` queries over an external source.
 
-Local search is single-node SQLite search over the local runner store. It is
-useful for local/dev/staging usage. It is not a hosted central evidence ledger,
-not cross-runner aggregation, not RBAC/SSO, and not compliance retention.
+Local search uses SQLite by default. In `runtime_store` mode, CLI/UI reads can
+inspect one bounded shared Postgres ledger across a small fleet. This is still
+not a hosted central evidence service, organization RBAC/SSO, compliance
+retention system, or unbounded search engine. Each bridge operation serializes
+through an advisory lock and fails above configured `max_entries`.
+
+Only homogeneous 1.1 fleet operation is currently verified. Mixed 1.0/1.1
+rolling operation is not claimed. See [Running A Small Runner
+Fleet](running-a-runner-fleet.md).
 
 Use this wording:
 

package/docs/migrating-to-synapsor-spec.md

@@ -127,6 +127,27 @@ Then keep only local wiring in `synapsor.runner.json`.
 }
 ```
 
+## 1.1 Approval Quorum
+
+Existing contracts remain valid and require one approval. To require distinct
+verified reviewers, add the optional canonical field:
+
+```json
+{
+  "proposal": {
+    "approval": {
+      "mode": "human",
+      "required_role": "billing_lead",
+      "required_approvals": 2
+    }
+  }
+}
+```
+
+The equivalent DSL is `REQUIRE 2 APPROVALS` after `APPROVAL ROLE
+billing_lead`. Runner 1.0 does not understand this new optional semantic field;
+use Runner/spec/DSL 1.1 together. Omitted fields preserve 1.0 behavior.
+
 ## Validate
 
 ```bash

package/docs/oss-vs-cloud.md

@@ -24,7 +24,7 @@ and investigation surfaces for enabled design-partner deployments.
 | Writeback | Guarded one-row update or app-owned executor | Cloud-linked jobs with local execution; managed production orchestration is future work |
 | MCP risk audit | Static local audit | Organization-wide continuous audit is future work |
 | Identity | Local operator boundary | Workspace RBAC where configured; SAML and SCIM are future work |
-| Operations | Customer-operated single node | Design-partner operation; no enterprise SLA in the current beta |
+| Operations | Customer-operated single node or bounded small fleet | Managed fleet remains Cloud work; no enterprise SLA in the current beta |
 
 ## What Stays Local
 

package/docs/production.md

@@ -14,10 +14,36 @@ MCP agent
 -> receipt/replay
 ```
 
-Use this only for bounded database workflows where you can accept a single-node
-local ledger and local/operator approval. Use Synapsor Cloud when you need HA,
-central audit, RBAC/SSO, multi-reviewer approvals, hosted retention, managed
-runners, policy packs, or production support/SLA.
+Use this only for bounded database workflows using either the default
+single-node SQLite ledger or the tested, serialized small-fleet Postgres
+runtime store. Use Synapsor Cloud when you need a managed fleet, hosted central
+audit, organization administration, SSO/SCIM, compliance retention, or a
+production support/SLA. See [Running A Small Runner
+Fleet](running-a-runner-fleet.md) for the exact OSS fleet guarantees and limits.
+
+## Audit The Agent-Facing Surface First
+
+Before configuring writeback or connecting a production-like database, audit
+the MCP tools the agent can see. Start with Runner's built-in risky database MCP
+example:
+
+```bash
+npx -y @synapsor/runner audit --example dangerous-db-mcp
+```
+
+Then audit the actual manifest, remote MCP endpoint, or stdio server you intend
+to expose:
+
+```bash
+synapsor-runner audit ./tools-list.json
+synapsor-runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN
+synapsor-runner audit 'stdio:node ./server.mjs'
+```
+
+Audit is a static risk review, not proof that an MCP server is secure. Treat
+generic SQL/query tools, model-controlled tenant or principal fields, and
+model-facing approval/apply tools as deployment blockers. See [MCP
+Audit](mcp-audit.md) for supported inputs, findings, and machine-readable output.
 
 ## Supported Scope
 
@@ -27,6 +53,11 @@ Production-candidate OSS scope:
 - trusted context from environment/session values, not model arguments;
 - local SQLite ledger for evidence, query audit, proposals, receipts, replay,
   and lifecycle events;
+- bounded shared Postgres runtime ledger for several claim-bound HTTP Runner
+  instances and verified reviewers;
+- asymmetric RS256/ES256 session authentication, readiness probes, separately
+  protected metrics, source pools, and fleet-wide rate limits;
+- distinct-reviewer approval quorum from the canonical contract;
 - direct guarded single-row `UPDATE` for simple approved edits;
 - app-owned `http_handler` or `command_handler` executors for richer approved
   business transactions;
@@ -37,8 +68,8 @@ Out of scope:
 - raw `execute_sql` or model-generated SQL;
 - generic direct `INSERT`, `DELETE`, `UPSERT`, DDL, or multi-row SQL writeback;
 - physical branching of external Postgres/MySQL;
-- workflow DAGs, auto-merge/settlement, RBAC/SSO, HA ledger, or compliance
-  retention;
+- workflow DAGs, auto-merge/settlement, hosted team administration, SSO/SCIM,
+  multi-region ledger replication, or compliance retention;
 - making prompt injection impossible.
 
 ## Database Roles
@@ -213,7 +244,8 @@ Mirror mode config:
       "mode": "mirror",
       "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
       "schema": "synapsor_runner",
-      "lock_timeout_ms": 10000
+      "lock_timeout_ms": 10000,
+      "max_entries": 10000
     }
   }
 }
@@ -241,7 +273,8 @@ synapsor-runner apply --all-approved --yes \
 
 When `storage.shared_postgres.mode` is `mirror`, `doctor` checks that the
 ledger URL environment variable is present and that `ledger_entries`,
-`proposal_locks`, and `worker_leases` exist in the configured schema. It reports
+`proposal_locks`, `worker_leases`, and `rate_limit_buckets` exist in the
+configured schema. It reports
 environment variable names and table readiness only; it does not print database
 URLs or initialize the schema.
 
@@ -286,6 +319,13 @@ long-running `worker run --yes` repeats bounded drain cycles under that lock
 and sleeps between idle polls, so multiple workers can share one Postgres ledger
 without holding the lock while idle.
 
+The current bridge loads a bounded snapshot and serializes each mutation. It
+fails closed above `max_entries`; it is not an unbounded scalable database
+engine. `proposals`, `evidence`, `query-audit`, `receipts`, `replay`,
+`activity`, `metrics`, worker status, and the local UI can read the same shared
+queue with `--config`. Back up, verify, restore, and archive-before-retention
+with the commands in [Running A Small Runner Fleet](running-a-runner-fleet.md).
+
 For unattended policy-approved queues, declare reviewed aggregate `LIMIT`
 clauses first, then use the explicit batch command:
 
@@ -426,6 +466,8 @@ synapsor-runner config validate --config synapsor.runner.json
 synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
 synapsor-runner doctor --config synapsor.runner.json --check-writeback
 synapsor-runner tools preview --config synapsor.runner.json --store ./.synapsor/local.db
+curl --fail http://127.0.0.1:8766/healthz
+curl --fail http://127.0.0.1:8766/readyz
 ```
 
 Doctor reports should be redacted by default before sharing. They must not

package/docs/release-notes.md

@@ -10,7 +10,25 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
-## Unreleased
+## 1.1.0 (prepared, not published)
+
+### Bounded Small-Fleet Runtime
+
+- Fixes claim/context authority conflicts before serving and keeps
+  object-filtered receipts/activity scoped to the requested object.
+- Adds asymmetric session/operator identity, readiness, protected HTTP
+  metrics, bounded native source pools, and shared fleet rate limits.
+- Adds portable distinct-reviewer quorum in the OSS canonical spec and DSL.
+  Existing 1.0 contracts still default to one approval. Cloud/C++ enforcement
+  of this optional field is not claimed until independently verified there.
+- Adds bounded shared-ledger CLI/UI review, startup-safe schema migration,
+  dead-letter recovery, backup/restore/retention, and tested worker recovery
+  before write and after durable commit.
+- Adds [Running A Small Runner Fleet](running-a-runner-fleet.md) and the
+  `corepack pnpm test:fleet` synthetic two-Runner verification.
+
+Prepared package versions: `@synapsor/spec@1.1.0`,
+`@synapsor/dsl@1.1.0`, and `@synapsor/runner@1.1.0`.
 
 ## 1.0.0
 

package/docs/release-policy.md

@@ -85,6 +85,27 @@ versioning. Breaking changes require a new major version, except for security
 fixes that close a vulnerability while preserving the safest possible
 compatibility path.
 
+## 1.1 Fleet Gate
+
+Do not publish `1.1.0` until all 1.0 gates remain green and the local synthetic
+fleet verifier proves:
+
+- claim/context contradictions fail before serving;
+- two claim-bound Runners preserve tenant isolation and one active proposal;
+- shared fixed-window rate limits reject with `retry_after_ms`;
+- distinct verified reviewers satisfy canonical quorum and apply remains
+  blocked before `N/N`;
+- Postgres/MySQL pool acquisition and queue limits fail fast;
+- worker termination before write and after commit recovers without a duplicate
+  effect;
+- backup digest, clean restore, and archive-before-retention preserve active
+  records;
+- `/healthz`, `/readyz`, and separately authorized `/metrics` expose no secrets
+  or business object/principal labels.
+
+Run `corepack pnpm test:fleet`. Only homogeneous 1.1 fleet operation is part of
+this gate; mixed-minor operation must be tested before it is claimed.
+
 ## Stable Compatibility Promise
 
 Starting with `1.0.0`, Synapsor Runner keeps these public surfaces compatible

package/docs/runner-config-reference.md

@@ -35,6 +35,9 @@ Unknown keys fail when `strict` is true (the default).
 | `policies` | No | Embedded reviewed policies; contract policies merge into the same catalog. |
 | `approvals` | No | Local approval overrides. |
 | `operator_identity` | No | Verified operator identity and apply-role wiring for approve/reject/apply. |
+| `session_auth` | HTTP claims | HS256 development or asymmetric RS256/ES256 session-token verification. |
+| `rate_limits` | No | Operational fixed-window limits; fleet-wide only with shared `runtime_store`. |
+| `metrics` | No | Separately authorized scrapeable HTTP metrics. Disabled by default. |
 | `executors` | No | App-owned writeback wiring. |
 | `cloud` | Cloud mode | Scoped Cloud adapter configuration. |
 
@@ -58,7 +61,8 @@ Unknown keys fail when `strict` is true (the default).
       "mode": "mirror",
       "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
       "schema": "synapsor_runner",
-      "lock_timeout_ms": 10000
+      "lock_timeout_ms": 10000,
+      "max_entries": 10000
     }
   }
 }
@@ -85,10 +89,17 @@ ledger by restoring into a temporary local store under the Postgres advisory
 lock, running the existing mutation, and syncing back. Long-running worker
 processes repeat bounded drain cycles and release the advisory lock while idle.
 
+The bridge loads at most `max_entries` ledger records per operation. The default
+is 10,000; valid values are 100 through 100,000. It fails closed with
+`POSTGRES_RUNTIME_STORE_CAPACITY_EXCEEDED` above the bound. Reviewer CLI reads
+and the local UI use the same shared queue. This is a serialized small-fleet
+design, not an unbounded high-throughput primary store.
+
 `synapsor-runner doctor --config ./synapsor.runner.json` checks shared Postgres
 wiring when this block is present: the URL env var must be set, and the
-configured schema must already contain `ledger_entries`, `proposal_locks`, and
-`worker_leases`. Doctor reports env var names and table readiness only; it does
+configured schema must already contain `ledger_entries`, `proposal_locks`,
+`worker_leases`, and `rate_limit_buckets`. Doctor reports env var names and
+table readiness only; it does
 not print database URLs or create the schema.
 
 ## Sources
@@ -115,6 +126,13 @@ timeout. `ssl` carries adapter-specific reviewed SSL options when used.
 
 A contract's `SOURCE billing_postgres` must exactly match a `sources` key.
 
+Long-running servers reuse native driver pools. Optional `pool` keys are
+`max_connections` (default 10), `connection_timeout_ms` (3000),
+`idle_timeout_ms` (30000), `queue_timeout_ms` (5000), and `queue_limit`
+(default `max(10, max_connections * 4)`). Queue overflow returns
+`SOURCE_POOL_QUEUE_FULL`; acquisition timeout returns `SOURCE_POOL_TIMEOUT`.
+One-shot CLI commands close their pools.
+
 ## Trusted context
 
 ```json
@@ -161,6 +179,35 @@ the active secret first, then the previous secret. Existing MCP sessions remain
 bound to the exact token fingerprint, so clients cannot swap tenant/principal
 identity inside an initialized session.
 
+For networked deployments prefer asymmetric public-key verification:
+
+```json
+{
+  "session_auth": {
+    "provider": "jwt_asymmetric",
+    "algorithms": ["RS256"],
+    "jwks_url_env": "SYNAPSOR_SESSION_JWKS_URL",
+    "issuer": "https://identity.example",
+    "audience": "synapsor-runner",
+    "tenant_claim": "tenant_id",
+    "principal_claim": "sub",
+    "clock_skew_seconds": 30,
+    "jwks_cache_seconds": 600,
+    "jwks_cooldown_seconds": 30,
+    "fetch_timeout_ms": 3000,
+    "max_response_bytes": 1048576
+  }
+}
+```
+
+`jwt_asymmetric` requires an explicit `RS256`/`ES256` allowlist and exactly one
+public-key source: `jwks_url_env`, `public_key_env`, or `public_key_path`.
+JWKS selection uses `kid`; unknown keys get one controlled refresh. Fetches are
+timeout/size bounded and do not follow redirects. Private JWK fields are
+rejected. Every effective named context in an `http_claims` server must bind
+tenant and principal from claims; environment/static contradictions fail with
+`TRUSTED_CONTEXT_PROVIDER_CONFLICT` before serving.
+
 ## Contracts and embedded capabilities
 
 ```json
@@ -215,6 +262,48 @@ from reviewed DSL `LIMIT` clauses, not an unreviewed local override. A tripped
 limit falls back to human review and is recorded in the ledger.
 `approvals.disable_auto_approval: true` disables local policy auto-approval
 without changing the reviewed contract. Approval never becomes an MCP tool.
+Portable `approval.required_approvals` defaults to `1` and accepts `1..10`.
+Distinct verified subjects fill quorum slots; one subject cannot count twice.
+A rejection is terminal. Policy auto-approval is deferred when quorum is
+greater than one.
+
+## Rate limits
+
+```json
+{
+  "rate_limits": {
+    "enabled": true,
+    "default": { "requests": 60, "window_seconds": 60 },
+    "capabilities": {
+      "billing.propose_refund": { "requests": 10, "window_seconds": 60 }
+    }
+  }
+}
+```
+
+Rules are fixed-window deployment controls keyed by trusted tenant plus
+reviewed capability. There is no separate burst allowance: all configured
+requests may arrive immediately, but the next request is rejected until the
+aligned window resets. They are process-local with SQLite and fleet-wide/atomic
+with shared `runtime_store`. `RATE_LIMITED` includes `retry_after_ms` to that
+reset boundary, records a counter, and creates no proposal. Rate limits are
+runtime wiring and never portable contract fields.
+
+## HTTP metrics
+
+```json
+{
+  "metrics": {
+    "enabled": true,
+    "token_env": "SYNAPSOR_METRICS_TOKEN"
+  }
+}
+```
+
+`/metrics` is disabled by default. Non-loopback exposure requires a separate
+metrics token; the MCP bearer does not authorize metrics. Labels are bounded to
+trusted tenant, capability, source, engine, and readiness component. Object
+IDs, principals, URLs, tokens, and raw errors are never labels.
 
 ## Operator identity
 
@@ -257,6 +346,15 @@ subject, timestamp, roles, signature, and integrity hash into the approval
 ledger. `apply_roles` independently gates writeback. The local browser UI
 refuses approval/rejection in signed-key mode so it cannot bypass this check.
 
+For OIDC-style operator identity, use `provider: "jwt_oidc"` with the same
+asymmetric public-key options as session auth, plus one token source:
+`token_env`, `token_file_env`, or `token_stdin: true`. With stdin, pipe or paste
+one token and close stdin; combine it with `--yes` so confirmation does not
+compete for the stream. Also configure `roles_claim`, `subject_claim`, and an
+`attestation_secret_env` containing at least 32 bytes. Runner persists verified
+subject/roles/issuer/key ID and an attested decision proof, never the bearer
+token. Tokens must not be passed as command-line arguments.
+
 ## Cloud mode
 
 Cloud mode omits local sources/capabilities and requires: