@synapsor/runner 1.5.3 → 1.6.0

package/docs/schema-api-candidates.md

@@ -1,5 +1,26 @@
 # Reviewed Candidates From Prisma, Drizzle, And OpenAPI
 
+Runner 1.6.0 uses these same bounded static parsers as evidence in the
+whole-application [Auto Boundary](auto-boundary-and-scoped-explore.md) flow.
+The database catalog remains authoritative for database structure; Prisma,
+Drizzle, OpenAPI, and existing Synapsor definitions contribute deterministic
+names, relationships, and structured review evidence. None of them
+independently grant authority.
+
+For a fresh interactive staging project, prefer:
+
+```bash
+synapsor-runner start --from-env DATABASE_URL
+```
+
+That combines all detected structured sources into one disabled candidate
+graph, generation lock, and Workbench review. It never executes adopter code,
+samples source rows before activation, uses an LLM, or overwrites an active
+contract.
+
+The individual commands below remain useful for CI, focused review, and
+backward-compatible workflows.
+
 Use these generators after schema or API inspection when you want a review
 starting point without granting authority:
 
@@ -42,11 +63,17 @@ They do not decide which tenant or principal is authoritative, which fields are
 safe to expose, which writes are valid, business bounds, approval policy, or
 auto-approval. A field-name heuristic is not data classification.
 
-Review `generation-review.json` and `REVIEW.md`, replace every
+In the individual-generator path, review `generation-review.json` and
+`REVIEW.md`, replace every
 `review_required_*` placeholder, run the generated tests and a
 [Shadow study](shadow-studies.md), then deliberately copy reviewed definitions
 into an active contract through code review.
 
+In Auto Boundary, Workbench presents the unresolved scope, field, aggregate,
+relationship, privacy, and role-posture decisions together. Exact-digest
+activation enables only the reviewed local authoring boundary. Generated named
+capabilities still begin disabled and require their own activation.
+
 ## Input Safety
 
 Input is bounded to 2 MiB, 50 objects, 128 fields per object, and 200 generated

package/docs/security-boundary.md

@@ -39,17 +39,52 @@ The model does not receive:
 - contract activation tools;
 - approval tools;
 - commit/writeback tools;
+- MCP endpoint tokens, JWTs, refresh tokens, client secrets, or TLS keys;
 - trusted tenant or principal authority as ordinary model arguments.
 
+## Network transport and identity
+
+Local stdio is the preferred one-client path. The MCP client launches Runner and
+communicates over the child process's standard input/output, so Runner opens no
+network listener and HTTP authentication does not apply.
+
+A listening HTTP endpoint has no inherent client identity. Runner therefore
+requires Bearer authentication by default. On loopback or an explicitly
+single-tenant service, Bearer may carry one high-entropy opaque endpoint token;
+that token only answers "may this service call the endpoint?" and is not a user
+or tenant identity. Shared services require signed per-session JWTs, preferably
+RS256/ES256 from an external identity provider, with exact issuer,
+audience/resource, time, scope, tenant, and principal validation on every
+request. An MCP session ID only routes protocol state and never authenticates a
+caller.
+
+Non-loopback HTTP refuses to bind unless Runner owns TLS, an explicitly trusted
+TLS proxy protects the public and private hops, or an authenticated emergency
+cleartext break-glass mode is selected. TLS protects the channel; mTLS also
+authenticates a workload certificate but does not replace per-user/tenant claims
+in a shared service. Exact Origin and Host policy, request/session limits, and
+credential-pinned MCP sessions narrow browser, DNS-rebinding, exhaustion, and
+session-swap attacks.
+
+These controls remain independent: transport authentication permits endpoint
+access; verified session claims provide tenant/principal context; the contract
+authorizes semantic capabilities; database roles/RLS constrain the connection;
+operator identity authorizes activation, approval, apply, reconcile, and
+revert. See [HTTP MCP](http-mcp.md).
+
 Reviewed aggregate tools expose one scalar only. Their function, column,
 tenant key, optional equality selection, and minimum-group threshold are fixed
 in the contract; the model receives no predicate arguments or member rows.
 Suppression reduces single-record inference but does not replace statistical
 privacy review. See [Bounded Aggregate Reads](aggregate-reads.md).
 
-Trusted context comes from local configuration, environment bindings, or Cloud
-session context in Cloud mode. Tenant, principal, and authorization scope must
-not be accepted from the model as authority.
+Trusted context comes from operator-controlled process bindings for local or
+explicitly single-tenant use, verified signed HTTP claims for a shared service,
+or verified Cloud session context in Cloud mode. Tenant, principal, and
+authorization scope must not be accepted from the model as authority.
+Canonical `SESSION` content is rejected by Runner with
+`SESSION_BINDING_UNSUPPORTED`; Runner never aliases it to environment values,
+arbitrary headers, MCP metadata, or model arguments.
 
 With a shared credential, these checks are application-level enforcement and
 depend on Runner's fixed predicate implementation. Optional PostgreSQL RLS mode

package/docs/store-lifecycle.md

@@ -33,20 +33,108 @@ sqlite3 -readonly ./.synapsor/local.db '.tables'
 Do not mutate the database directly. Its internal tables may change between
 releases and are not a public storage API; use Runner commands for automation.
 
-## Inspect the ledger
+## Inspect one complete lifecycle
 
-| Question | Command |
+Start with no id:
+
+```bash
+synapsor-runner lifecycle --store ./.synapsor/local.db
+```
+
+`lifecycle`, `lifecycle show`, and `lifecycle show latest` are exact aliases.
+They choose the newest proposal deterministically by `created_at` descending,
+then proposal id as the tie-breaker. The default view answers:
+
+- what capability and business object the model requested;
+- which trusted tenant and principal scoped it;
+- approval state and progress;
+- whether a writeback job or intent exists;
+- the latest guarded outcome and whether the source changed;
+- replay and Cloud-link status; and
+- the next safe read-only or operator command.
+
+Use `--details` for one causal proposal-to-receipt/replay timeline, or `--json`
+for one stable `synapsor.lifecycle-view.v1` JSON document:
+
+```bash
+synapsor-runner lifecycle --details --store ./.synapsor/local.db
+synapsor-runner lifecycle --json --store ./.synapsor/local.db
+```
+
+The JSON is a domain view, not a dump of internal SQLite/PostgreSQL tables.
+Absent stages are represented explicitly as empty arrays or `null`; Runner
+does not fabricate a job, receipt, replay, or Cloud synchronization.
+
+### Browse and filter without copying ids
+
+```bash
+synapsor-runner lifecycle list --limit 20 --store ./.synapsor/local.db
+synapsor-runner lifecycle show --object invoice:INV-3001 --details --store ./.synapsor/local.db
+synapsor-runner lifecycle list --tenant acme --capability billing.propose_late_fee_waiver
+synapsor-runner lifecycle show --principal support-agent-17 --status applied
+```
+
+List/show support tenant, principal, capability, business object, status/state,
+and time-window filters. Filtered `show` selects the newest match and reports
+the total match count; use `lifecycle list` to browse all matches. List JSON
+uses `synapsor.lifecycle-list.v1`.
+
+### Start from any handle you already have
+
+```bash
+synapsor-runner lifecycle show wrp_... --details
+synapsor-runner lifecycle show ev_... --details
+synapsor-runner lifecycle show replay_... --details
+synapsor-runner lifecycle show wbj_... --details
+synapsor-runner lifecycle show wbi:wbj_... --details
+synapsor-runner lifecycle show receipt:42 --details
+synapsor-runner lifecycle show audit:17 --details
+```
+
+Runner resolves proposal, evidence, replay, writeback-job, writeback-intent,
+receipt, and query-audit handles to the owning proposal. Numeric receipt and
+query-audit ids require the `receipt:` or `audit:` namespace; a bare number is
+rejected rather than guessed.
+
+Lifecycle inspection is read-only. It does not contact the source database or
+Cloud, create a writeback job, acquire a worker lease, approve, apply, reconcile,
+retry, or synchronize anything. It applies the same tenant/principal visibility
+rules and secret/kept-out-field protections as the focused views.
+
+### Shared PostgreSQL runtime store
+
+For `storage.shared_postgres.mode = "runtime_store"`, pass the reviewed config:
+
+```bash
+synapsor-runner lifecycle --config ./synapsor.runner.json
+synapsor-runner lifecycle show --object invoice:INV-3001 --details \
+  --config ./synapsor.runner.json
+```
+
+Runner reuses the existing bounded read bridge to the authoritative shared
+ledger. It does not create or synchronize a persistent local mirror during
+inspection. Connection failures fail safely; the command never falls back to an
+unrelated local store.
+
+## Focused inspection commands
+
+The existing commands remain useful when you need one record type:
+
+| Question | Focused command |
 | --- | --- |
-| What did the model propose? | `synapsor-runner proposals show <proposal-id> --details` |
+| What did the model propose? | `synapsor-runner proposals show latest --details` |
 | What data supported it? | `synapsor-runner evidence list --proposal <proposal-id>` then `evidence show <evidence-id> --details` |
 | What query was run? | `synapsor-runner query-audit list --proposal <proposal-id>` |
-| Who approved or rejected it? | `synapsor-runner proposals show <proposal-id> --details` |
 | Did guarded writeback apply? | `synapsor-runner receipts list --proposal <proposal-id>` |
-| What happened end to end? | `synapsor-runner replay show --proposal <proposal-id> --details` |
+| What replay snapshot exists? | `synapsor-runner replay show latest --details` |
 | What happened to one object? | `synapsor-runner activity search --object invoice:INV-3001` |
 | What are the latest events? | `synapsor-runner events tail` |
 | How large is the store? | `synapsor-runner store stats --store ./.synapsor/local.db` |
 
+`proposals writeback-job` is intentionally absent from inspection examples:
+it materializes a job and is therefore an operator mutation, not a read-only
+view.
+
 ## Server leases
 
 MCP server modes write a small lease file next to the store:

package/docs/troubleshooting-first-run.md

@@ -12,6 +12,104 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Fresh Start Did Not Enter Auto Boundary
+
+Auto Boundary is the default only for a fresh interactive `start --from-env`
+with no existing config, selector, answers file, machine-output flag, or other
+automation input. This preserves every established 1.x route.
+
+Check the generated state:
+
+```bash
+synapsor-runner boundary status --json
+```
+
+To draft explicitly without prompts or a browser:
+
+```bash
+synapsor-runner boundary draft \
+  --from-env DATABASE_URL \
+  --schema public \
+  --project-root . \
+  --json
+```
+
+## Scoped Explore Is Not Advertised
+
+This is correct unless all authoring prerequisites pass. Explore is disabled by
+default and never appears in production, unknown-profile, shared HTTP, remote,
+or non-loopback `tools/list`.
+
+Check:
+
+```bash
+synapsor-runner boundary status --json
+synapsor-runner boundary diff --json
+synapsor-runner mcp status cursor --project
+```
+
+The exact boundary digest must be active, the profile must explicitly be
+`development` or `staging`, the generation lock and compiler/Spec versions
+must be current, and the inspected database role must still be SELECT-only,
+non-owner, non-superuser, and not `BYPASSRLS`. Runner also enforces a read-only
+transaction for every Explore call.
+
+A write-capable, owner, superuser, `BYPASSRLS`, or unverifiable credential may
+still inspect metadata with a warning. It cannot enable source-row Explore.
+Use a dedicated staging reader instead of weakening this check.
+
+## Cursor Has Production Tools Instead Of Authoring Tools
+
+Install the managed local authoring entry only after boundary activation:
+
+```bash
+synapsor-runner mcp install cursor \
+  --project \
+  --authoring \
+  --project-root . \
+  --yes
+```
+
+Authoring status reports exactly `app.describe_data` and `app.explore_data`.
+After Protect and exact-digest activation, replace that entry with the
+production config. The protected named capability remains available while
+Explore disappears:
+
+```bash
+synapsor-runner mcp install cursor \
+  --project \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --yes
+```
+
+## Boundary Became Stale After A Schema Or Grant Change
+
+Generated authority is bound to the schema, role, grants, ownership, RLS
+posture, compiler, and canonical Spec fingerprint:
+
+```bash
+synapsor-runner boundary diff --json
+```
+
+Additive fields receive no implicit authority. Breaking or posture drift fails
+closed only for lock-bound generated authority. Regenerate, review the semantic
+diff, and activate the new exact digest. Existing manually authored projects
+without a generation lock retain their previous behavior.
+
+## Aggregate Explore Suppressed Or Refused A Result
+
+Suppression and budget failures are security behavior, not query failures.
+Workbench shows the reviewed minimum cohort, maximum groups, response limits,
+and durable extraction/differencing budgets. You cannot widen them in a model
+argument.
+
+Use a larger legitimate cohort or protect a narrower reviewed question. Do not
+work around suppression with repeated slightly different filters: Runner
+records normalized redacted plan metadata and exhausts the differencing budget.
+Returned rows/groups, trusted tenant/principal values, credentials, and raw
+sensitive literals are not stored in the query audit.
+
 ## Safe Action Draft Does Not Appear As A Tool
 
 This is expected before activation. `start --action`, agent edits, `action

package/examples/auto-boundary-churn/README.md

@@ -0,0 +1,23 @@
+# Auto Boundary Churn Fixture
+
+This synthetic staging fixture is the measured Runner 1.6.0 golden path:
+PostgreSQL, Next.js, Prisma, Cursor-compatible local MCP, and the local
+Workbench.
+
+The database role is SELECT-only, non-owner, non-superuser, and subject to
+forced tenant/principal RLS. The data includes reviewed churn cohorts, a
+cross-tenant denial case, kept-out fields, and cohorts below the privacy
+threshold.
+
+Run the automated acceptance path from the repository root:
+
+```bash
+corepack pnpm test:auto-boundary-explore
+corepack pnpm test:auto-boundary-explore:packed
+```
+
+The packed gate uses only packed public artifacts for the complete journey:
+disabled whole-schema draft, digest activation, two Cursor authoring tools,
+privacy-suppressed weekly churn analysis, denial and differencing tests,
+Protect This Query, production Explore removal, and the surviving named
+capability. No source row is mutated.

package/examples/auto-boundary-churn/app/page.tsx

@@ -0,0 +1,8 @@
+export default function ChurnOverview() {
+  return (
+    <main>
+      <h1>Subscription churn review</h1>
+      <p>This synthetic staging application is used by the Synapsor Auto Boundary acceptance test.</p>
+    </main>
+  );
+}

package/examples/auto-boundary-churn/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: synapsor_auto_boundary
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "127.0.0.1:55460:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "test \"$(psql -U synapsor_admin -d synapsor_auto_boundary -tAc \"SELECT pg_postmaster_start_time() > initialized_at FROM public.synapsor_fixture_ready LIMIT 1\" 2>/dev/null | xargs)\" = t"]
+      interval: 1s
+      timeout: 3s
+      retries: 40
+    volumes:
+      - ./seed/postgres.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro

package/examples/auto-boundary-churn/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "synapsor-auto-boundary-churn",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev"
+  },
+  "dependencies": {
+    "@prisma/client": "^6.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "prisma": "^6.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/examples/auto-boundary-churn/prisma/schema.prisma

@@ -0,0 +1,36 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Account {
+  id                String       @id
+  tenantId          String       @map("tenant_id")
+  ownerId           String       @map("owner_id")
+  region            String
+  segment           String
+  customerEmail     String       @map("customer_email")
+  internalRiskScore Int          @map("internal_risk_score")
+  churnEvents       ChurnEvent[]
+
+  @@map("accounts")
+}
+
+model ChurnEvent {
+  id                  String   @id
+  tenantId            String   @map("tenant_id")
+  ownerId             String   @map("owner_id")
+  accountId           String   @map("account_id")
+  reasonCategory      String   @map("reason_category")
+  monthlyRevenueCents Int      @map("monthly_revenue_cents")
+  churnedAt           DateTime @map("churned_at") @db.Timestamptz(6)
+  privateNote         String   @map("private_note")
+  account             Account  @relation(fields: [accountId], references: [id])
+
+  @@index([tenantId, churnedAt])
+  @@map("churn_events")
+}

package/examples/auto-boundary-churn/seed/postgres.sql

@@ -0,0 +1,126 @@
+CREATE TABLE public.accounts (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  owner_id text NOT NULL,
+  region text NOT NULL CHECK (region IN ('east', 'north', 'south', 'west')),
+  segment text NOT NULL CHECK (segment IN ('enterprise', 'growth', 'startup')),
+  customer_email text NOT NULL,
+  internal_risk_score integer NOT NULL
+);
+
+CREATE TABLE public.churn_events (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  owner_id text NOT NULL,
+  account_id text NOT NULL REFERENCES public.accounts(id) ON DELETE RESTRICT,
+  reason_category text NOT NULL CHECK (reason_category IN ('onboarding', 'price', 'product', 'service')),
+  monthly_revenue_cents integer NOT NULL CHECK (monthly_revenue_cents >= 0),
+  churned_at timestamptz NOT NULL,
+  private_note text NOT NULL
+);
+
+CREATE INDEX churn_events_tenant_time_idx
+  ON public.churn_events(tenant_id, churned_at);
+
+WITH groups(prefix, tenant_id, owner_id, region, segment, reason_category, churned_at, group_size, revenue) AS (
+  VALUES
+    ('p1-west-price', 'acme', 'pm-1', 'west', 'growth', 'price', '2026-06-03T12:00:00Z'::timestamptz, 5, 12000),
+    ('p1-east-service', 'acme', 'pm-1', 'east', 'enterprise', 'service', '2026-06-10T12:00:00Z'::timestamptz, 5, 22000),
+    ('p1-north-product', 'acme', 'pm-1', 'north', 'startup', 'product', '2026-06-17T12:00:00Z'::timestamptz, 2, 5000),
+    ('p2-west-price', 'acme', 'pm-1', 'west', 'growth', 'price', '2026-07-08T12:00:00Z'::timestamptz, 10, 13000),
+    ('p2-east-service', 'acme', 'pm-1', 'east', 'enterprise', 'service', '2026-07-15T12:00:00Z'::timestamptz, 7, 23000),
+    ('p2-south-onboarding', 'acme', 'pm-1', 'south', 'startup', 'onboarding', '2026-07-22T12:00:00Z'::timestamptz, 5, 7000),
+    ('p2-north-product', 'acme', 'pm-1', 'north', 'startup', 'product', '2026-07-22T12:00:00Z'::timestamptz, 1, 6000),
+    ('other-west-price', 'globex', 'pm-2', 'west', 'enterprise', 'price', '2026-07-08T12:00:00Z'::timestamptz, 8, 99000)
+)
+INSERT INTO public.accounts (
+  id,
+  tenant_id,
+  owner_id,
+  region,
+  segment,
+  customer_email,
+  internal_risk_score
+)
+SELECT
+  prefix || '-' || item,
+  tenant_id,
+  owner_id,
+  region,
+  segment,
+  prefix || '-' || item || '@example.invalid',
+  900 + item
+FROM groups
+CROSS JOIN LATERAL generate_series(1, group_size) AS item;
+
+WITH groups(prefix, tenant_id, owner_id, reason_category, churned_at, group_size, revenue) AS (
+  VALUES
+    ('p1-west-price', 'acme', 'pm-1', 'price', '2026-06-03T12:00:00Z'::timestamptz, 5, 12000),
+    ('p1-east-service', 'acme', 'pm-1', 'service', '2026-06-10T12:00:00Z'::timestamptz, 5, 22000),
+    ('p1-north-product', 'acme', 'pm-1', 'product', '2026-06-17T12:00:00Z'::timestamptz, 2, 5000),
+    ('p2-west-price', 'acme', 'pm-1', 'price', '2026-07-08T12:00:00Z'::timestamptz, 10, 13000),
+    ('p2-east-service', 'acme', 'pm-1', 'service', '2026-07-15T12:00:00Z'::timestamptz, 7, 23000),
+    ('p2-south-onboarding', 'acme', 'pm-1', 'onboarding', '2026-07-22T12:00:00Z'::timestamptz, 5, 7000),
+    ('p2-north-product', 'acme', 'pm-1', 'product', '2026-07-22T12:00:00Z'::timestamptz, 1, 6000),
+    ('other-west-price', 'globex', 'pm-2', 'price', '2026-07-08T12:00:00Z'::timestamptz, 8, 99000)
+)
+INSERT INTO public.churn_events (
+  id,
+  tenant_id,
+  owner_id,
+  account_id,
+  reason_category,
+  monthly_revenue_cents,
+  churned_at,
+  private_note
+)
+SELECT
+  'event-' || prefix || '-' || item,
+  tenant_id,
+  owner_id,
+  prefix || '-' || item,
+  reason_category,
+  revenue,
+  churned_at,
+  'synthetic kept-out note ' || prefix || '-' || item
+FROM groups
+CROSS JOIN LATERAL generate_series(1, group_size) AS item;
+
+ALTER TABLE public.accounts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.accounts FORCE ROW LEVEL SECURITY;
+ALTER TABLE public.churn_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.churn_events FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY accounts_trusted_scope ON public.accounts
+  FOR SELECT
+  USING (
+    tenant_id = current_setting('app.tenant_id', true)
+    AND owner_id = current_setting('app.principal', true)
+  );
+
+CREATE POLICY churn_events_trusted_scope ON public.churn_events
+  FOR SELECT
+  USING (
+    tenant_id = current_setting('app.tenant_id', true)
+    AND owner_id = current_setting('app.principal', true)
+  );
+
+DO $$
+BEGIN
+  CREATE ROLE synapsor_churn_reader LOGIN PASSWORD 'synapsor_churn_reader_password';
+EXCEPTION WHEN duplicate_object THEN NULL;
+END
+$$;
+
+ALTER ROLE synapsor_churn_reader SET default_transaction_read_only = on;
+GRANT CONNECT ON DATABASE synapsor_auto_boundary TO synapsor_churn_reader;
+GRANT USAGE ON SCHEMA public TO synapsor_churn_reader;
+GRANT SELECT ON public.accounts, public.churn_events TO synapsor_churn_reader;
+
+-- The image entrypoint runs these statements under a temporary postmaster and
+-- then restarts PostgreSQL. Compose reports healthy only after that final
+-- postmaster starts, preventing first-client disconnects in CI.
+CREATE TABLE public.synapsor_fixture_ready (
+  initialized_at timestamptz NOT NULL
+);
+INSERT INTO public.synapsor_fixture_ready (initialized_at) VALUES (clock_timestamp());

package/examples/openai-agents-http/README.md

@@ -40,7 +40,7 @@ OpenAI Agents Streamable HTTP example smoke passed.
 export DATABASE_URL="<postgres-or-mysql-read-url>"
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="openai_agent_demo"
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
 npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
@@ -49,6 +49,10 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --alias-mode openai
 ```
 
+The operator must provision that same opaque value to the authorized client.
+It is endpoint access for this loopback/single-service example, not user or
+tenant identity. Do not put it in source code or the client config.
+
 ## Terminal 2: Run The Agent
 
 ```bash
@@ -58,7 +62,7 @@ pip install -r requirements.txt
 
 export OPENAI_API_KEY="..."
 export SYNAPSOR_RUNNER_HTTP_URL="http://127.0.0.1:8766/mcp"
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+read -rsp "Provisioned Synapsor endpoint token: " SYNAPSOR_MCP_ACCESS_TOKEN; printf '\n'; export SYNAPSOR_MCP_ACCESS_TOKEN
 export SYNAPSOR_INVOICE_ID="INV-3001"
 
 python agent.py
@@ -74,5 +78,7 @@ Expected behavior:
 - no SQL/write/approval tool is exposed to the model;
 - evidence/query audit are saved in the local Runner store.
 
-For production-like deployment, keep HTTP MCP behind private networking/TLS,
-bearer auth, and rate limits. See [HTTP MCP](../../docs/http-mcp.md).
+For production-like deployment, non-loopback HTTP requires Runner TLS or an
+explicitly trusted TLS proxy. A shared user/tenant service uses a short-lived
+signed access token from an external identity provider rather than distributing
+one opaque token. See [HTTP MCP](../../docs/http-mcp.md).

package/examples/openai-agents-http/agent.py

@@ -13,14 +13,14 @@ except ImportError as exc:
 
 
 async def main() -> None:
-    required = ["OPENAI_API_KEY", "SYNAPSOR_RUNNER_HTTP_URL", "SYNAPSOR_RUNNER_HTTP_TOKEN"]
+    required = ["OPENAI_API_KEY", "SYNAPSOR_RUNNER_HTTP_URL", "SYNAPSOR_MCP_ACCESS_TOKEN"]
     missing = [name for name in required if not os.environ.get(name)]
     if missing:
         raise SystemExit(f"Missing required environment variables: {', '.join(missing)}")
 
     invoice_id = os.environ.get("SYNAPSOR_INVOICE_ID", "INV-3001")
     mcp_url = os.environ["SYNAPSOR_RUNNER_HTTP_URL"]
-    token = os.environ["SYNAPSOR_RUNNER_HTTP_TOKEN"]
+    token = os.environ["SYNAPSOR_MCP_ACCESS_TOKEN"]
 
     async with MCPServerStreamableHttp(
         params={

package/examples/runner-fleet/Dockerfile

@@ -1,11 +1,16 @@
 FROM node:22-bookworm-slim
 
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends openssl \
+  && rm -rf /var/lib/apt/lists/*
+
 RUN corepack enable && corepack prepare pnpm@10.14.0 --activate
 
 WORKDIR /app
 COPY . .
 RUN corepack pnpm install --frozen-lockfile \
-  && corepack pnpm build:runner-package
+  && corepack pnpm build:runner-package \
+  && chmod +x examples/runner-fleet/start-tls-runner.sh
 
-ENTRYPOINT ["node", "apps/runner/dist/cli.js"]
+ENTRYPOINT ["examples/runner-fleet/start-tls-runner.sh"]
 CMD ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]