@synapsor/runner 1.5.0 → 1.5.4

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,52 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Safe Action Draft Does Not Appear As A Tool
+
+This is expected before activation. `start --action`, agent edits, `action
+validate`, and `action watch` can create or refresh only a disabled draft. They
+must not alter the active model-facing tools.
+
+Check status without exposing credentials:
+
+```bash
+synapsor-runner action status --json
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Open the secured Workbench, run the real source-unchanged staging Data PR
+preview, review the complete digest, and activate it there. There is
+intentionally no activation CLI command to hand to a coding agent.
+
+## Activated Tool Does Not Appear In Cursor
+
+Some MCP hosts do not refresh `tools/list` for a running stdio session. First
+confirm that Runner's active tool surface changed:
+
+```bash
+synapsor-runner action status --json
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Then reconnect or restart the project MCP server as directed by the Workbench.
+Do not work around a stale host session by adding approval, apply, activation,
+credentials, tenant values, or raw SQL to the Cursor configuration.
+
+## Safe Action Validation Reports Review Placeholders
+
+The composer fails closed while any `__REVIEW_*__` authority placeholder or
+dynamic TypeScript expression remains. Review the reported field and source,
+then make the authority explicit in the restricted `defineCapability({...})`
+object. Runner will not infer trusted tenant/principal bindings, hidden fields,
+write columns, bounds, conflict guards, approval, or executor authority from
+application code.
+
+Use the generated explanation and test manifest after validation. Do not edit
+digest-addressed files under `.synapsor/drafts/` or `.synapsor/active/`; edit
+the TypeScript source and validate again.
+
 ## Smoke Proposal Missing From Another Runner
 
 What happened:

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"]

package/examples/runner-fleet/README.md

@@ -2,8 +2,11 @@
 
 This synthetic fixture starts Postgres, MySQL, and two stateless Streamable
 HTTP Runner services. Both Runners share one bounded Postgres runtime ledger.
-The committed passwords and HS256 key are disposable local-demo values. Never
-reuse them outside this fixture.
+Each container generates a one-day self-signed certificate at startup so the
+non-loopback Runner listener exercises direct TLS rather than insecure HTTP.
+The committed database passwords and HS256 key are disposable local-demo
+values. Never reuse them outside this fixture; production should use a trusted
+certificate and asymmetric identity-provider tokens.
 
 From the repository root:
 
@@ -16,9 +19,9 @@ docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml ps
 Check both instances:
 
 ```bash
-curl --fail http://127.0.0.1:8871/healthz
-curl --fail http://127.0.0.1:8871/readyz
-curl --fail http://127.0.0.1:8872/readyz
+curl --fail --insecure https://127.0.0.1:8871/healthz
+curl --fail --insecure https://127.0.0.1:8871/readyz
+curl --fail --insecure https://127.0.0.1:8872/readyz
 ```
 
 The MCP endpoint requires a claim-bearing development JWT. Generate one for
@@ -28,8 +31,9 @@ the fixture only:
 node examples/runner-fleet/mint-dev-token.mjs acme local-agent
 ```
 
-The production path should use `jwt_asymmetric` with an explicit RS256/ES256
-allowlist and a trusted JWKS URL or public PEM. See
+`--insecure` is acceptable only for this synthetic self-signed fixture. The
+production path should use a trusted TLS chain and `jwt_asymmetric` with an
+explicit RS256/ES256 allowlist plus a trusted JWKS URL or public PEM. See
 [Running A Runner Fleet](../../docs/running-a-runner-fleet.md).
 
 Run the stronger automated verification instead of treating a green Compose

package/examples/runner-fleet/docker-compose.yml

@@ -46,11 +46,11 @@ services:
       SYNAPSOR_SESSION_JWT_SECRET: synthetic-fleet-session-secret-change-before-use-0001
       SYNAPSOR_METRICS_TOKEN: synthetic-fleet-metrics-token-change-before-use
     ports:
-      - "8871:8766"
+      - "127.0.0.1:8871:8766"
     volumes:
       - ./synapsor.runner.json:/config/synapsor.runner.json:ro
     healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      test: ["CMD-SHELL", "NODE_TLS_REJECT_UNAUTHORIZED=0 node -e \"fetch('https://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
       interval: 2s
       timeout: 5s
       retries: 30
@@ -66,11 +66,11 @@ services:
         condition: service_healthy
     environment: *runner_environment
     ports:
-      - "8872:8766"
+      - "127.0.0.1:8872:8766"
     volumes:
       - ./synapsor.runner.json:/config/synapsor.runner.json:ro
     healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      test: ["CMD-SHELL", "NODE_TLS_REJECT_UNAUTHORIZED=0 node -e \"fetch('https://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
       interval: 2s
       timeout: 5s
       retries: 30

package/examples/runner-fleet/mint-dev-token.mjs

@@ -9,7 +9,7 @@ const payload = {
   sub: subject,
   tenant_id: tenant,
   iss: "https://fleet.example.invalid",
-  aud: "synapsor-runner-fleet",
+  aud: "https://runner-fleet.example.invalid/mcp",
   iat: now,
   exp: now + 600,
 };

package/examples/runner-fleet/start-tls-runner.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+tls_dir="${SYNAPSOR_FLEET_TLS_DIR:-/tmp/synapsor-runner-tls}"
+mkdir -p "$tls_dir"
+chmod 700 "$tls_dir"
+
+openssl req -x509 -newkey rsa:2048 -sha256 -nodes -days 1 \
+  -subj "/CN=localhost" \
+  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \
+  -keyout "$tls_dir/server.key" \
+  -out "$tls_dir/server.crt" \
+  >/dev/null 2>&1
+chmod 600 "$tls_dir/server.key" "$tls_dir/server.crt"
+
+export SYNAPSOR_FLEET_TLS_CERT_PEM="$(<"$tls_dir/server.crt")"
+export SYNAPSOR_FLEET_TLS_KEY_PEM="$(<"$tls_dir/server.key")"
+
+exec node apps/runner/dist/cli.js "$@" \
+  --tls-cert-env SYNAPSOR_FLEET_TLS_CERT_PEM \
+  --tls-key-env SYNAPSOR_FLEET_TLS_KEY_PEM

package/examples/runner-fleet/synapsor.runner.json

@@ -36,11 +36,37 @@
     "provider": "jwt_hs256",
     "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
     "issuer": "https://fleet.example.invalid",
-    "audience": "synapsor-runner-fleet",
+    "audience": "https://runner-fleet.example.invalid/mcp",
     "tenant_claim": "tenant_id",
     "principal_claim": "sub",
     "clock_skew_seconds": 10
   },
+  "http_security": {
+    "deployment": "shared",
+    "oauth_resource": {
+      "resource": "https://runner-fleet.example.invalid/mcp",
+      "authorization_servers": ["https://fleet.example.invalid"],
+      "resource_name": "Synthetic Synapsor Runner fleet"
+    },
+    "allowed_hosts": [
+      "127.0.0.1:8766",
+      "127.0.0.1:8871",
+      "127.0.0.1:8872",
+      "localhost:8766",
+      "localhost:8871",
+      "localhost:8872"
+    ],
+    "limits": {
+      "max_request_bytes": 65536,
+      "max_header_bytes": 8192,
+      "max_sessions": 100,
+      "session_idle_timeout_seconds": 120,
+      "request_timeout_ms": 15000,
+      "headers_timeout_ms": 5000,
+      "keep_alive_timeout_ms": 5000,
+      "max_connections": 200
+    }
+  },
   "rate_limits": {
     "enabled": true,
     "default": { "requests": 20, "window_seconds": 60 },

package/examples/support-billing-agent/README.md

@@ -63,6 +63,21 @@ The demo proves:
 - the shadow report compares cases with authoritative human outcomes before the
   effect fixture checks the expected business change.
 
+The app-owned integration files make those two evaluation paths reusable:
+
+- `app/contract.ts` is the code-first TypeScript form of the reviewed late-fee
+  action and compiles to the same canonical spec as JSON/DSL;
+- `app/record-shadow-outcomes.mjs` records authoritative app outcomes through
+  `@synapsor/runner/shadow` without approval or source mutation;
+- `app/effect-adapter.mjs` emits one deterministic, propose-only result through
+  the provider-neutral command adapter;
+- `.github/workflows/effect-regression.yml` runs the effect check and uploads
+  JUnit output for relevant pull requests.
+
+This repository result is deterministic application evidence, not an external
+model benchmark. Use `--result-origin external-model` only when your adapter
+actually invokes a model.
+
 RLS is defense in depth, not a claim that a fully compromised Runner process is
 contained. A process that can choose arbitrary trusted context or replace the
 database credential remains outside this guarantee. Production deployments
@@ -107,6 +122,9 @@ Relevant files:
 - `scripts/run-demo.sh`
 - `scripts/run-evaluation.sh`
 - `app/README.md`
+- `app/contract.ts`
+- `app/record-shadow-outcomes.mjs`
+- `app/effect-adapter.mjs`
 - `shadow-study/cases.jsonl` and `shadow-study/outcomes.jsonl`: deterministic
   true-shadow reference data for agent-versus-authoritative-outcome reports.
 

package/examples/support-billing-agent/app/README.md

@@ -11,3 +11,9 @@ writeback with tenant, primary-key, allowed-column, idempotency, and
 For richer app actions, such as inserting a credit ledger row and emitting an
 event, use the app-owned handler examples in `../app-owned-writeback/` and
 `../mcp-postgres-billing-app-handler/`.
+
+`contract.ts` demonstrates the optional typed authoring frontend without
+changing the canonical contract. `record-shadow-outcomes.mjs` is the normal-app
+bridge for authoritative human outcomes. `effect-adapter.mjs` is a deterministic
+propose-only CI adapter; it receives a bounded fixture path and emits one
+canonical result. Neither helper approves, applies, or mutates the source.

package/examples/support-billing-agent/app/contract.ts

@@ -0,0 +1,28 @@
+import { defineCapability } from "@synapsor/runner/authoring";
+
+export const waiveLateFee = defineCapability({
+  name: "billing.propose_late_fee_waiver",
+  kind: "proposal",
+  context: "local_operator",
+  source: "app_postgres",
+  subject: { resource: "billing.invoice", primary_key: "id", tenant_key: "tenant_id" },
+  args: {
+    invoice_id: { type: "string", required: true, max_length: 128 },
+    reason: { type: "string", required: true, max_length: 500 },
+  },
+  lookup: { id_from_arg: "invoice_id" },
+  visible_fields: ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
+  kept_out_fields: ["card_token", "internal_risk_note"],
+  evidence: { required: true, query_audit: true },
+  max_rows: 1,
+  proposal: {
+    action: "waive_late_fee",
+    operation: { kind: "update" },
+    allowed_fields: ["late_fee_cents", "waiver_reason"],
+    patch: { late_fee_cents: { fixed: 0 }, waiver_reason: { from_arg: "reason" } },
+    numeric_bounds: { late_fee_cents: { minimum: 0, maximum: 10000 } },
+    conflict_guard: { column: "updated_at" },
+    approval: { mode: "human", required_role: "billing_lead" },
+    writeback: { mode: "direct_sql" },
+  },
+});

package/examples/support-billing-agent/app/effect-adapter.mjs

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+
+if (process.env.SYNAPSOR_EFFECT_MODE !== "propose_only") {
+  throw new Error("reference effect adapter requires SYNAPSOR_EFFECT_MODE=propose_only");
+}
+if (process.env.DATABASE_URL || process.env.SYNAPSOR_DATABASE_WRITE_URL) {
+  throw new Error("reference effect adapter must not receive database credentials");
+}
+const fixturePath = process.env.SYNAPSOR_EFFECT_FIXTURE_PATH;
+if (!fixturePath) throw new Error("SYNAPSOR_EFFECT_FIXTURE_PATH is required");
+const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+const expected = fixture.expected;
+
+process.stdout.write(`${JSON.stringify({
+  schema_version: "synapsor.effect-result.v1",
+  fixture_id: fixture.fixture_id,
+  capability_calls: expected.capability_calls.map((name) => ({ name })),
+  trusted_context: expected.trusted_context,
+  proposal: expected.proposal,
+  observed_fields: Object.keys(expected.proposal.diff ?? {}).sort(),
+  evidence: { mode: "fixture", new_source_reads: false },
+  source_database_changed: false,
+})}\n`);

package/examples/support-billing-agent/app/record-shadow-outcomes.mjs

@@ -0,0 +1,44 @@
+import { createShadowOutcomeRecorder } from "@synapsor/runner/shadow";
+
+const [storePath, studyId] = process.argv.slice(2);
+if (!storePath || !studyId) {
+  throw new Error("usage: node record-shadow-outcomes.mjs <store-path> <study-id>");
+}
+
+const recorder = createShadowOutcomeRecorder({
+  storePath,
+  studyId,
+  actor: "support_reference_app",
+  source: "support-app-audit",
+});
+try {
+  recorder.record({
+    requestId: "req-waiver-exact",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-3001",
+    disposition: "applied",
+    actualEffect: {
+      before: { late_fee_cents: 5500, waiver_reason: null },
+      after: { late_fee_cents: 0, waiver_reason: "courtesy waiver" },
+      patch: { late_fee_cents: 0, waiver_reason: "courtesy waiver" },
+    },
+    occurredAt: "2026-07-19T11:00:00.000Z",
+    reference: "ticket:SUP-184",
+    reason: "customer qualified",
+  });
+  recorder.record({
+    requestId: "req-waiver-rejected",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-REJECTED",
+    disposition: "rejected_no_action",
+    occurredAt: "2026-07-19T11:01:00.000Z",
+    reference: "ticket:SUP-REJECTED",
+    reason: "customer already received a courtesy waiver",
+  });
+} finally {
+  recorder.close();
+}
+
+process.stdout.write("Recorded 2 authoritative outcomes through @synapsor/runner/shadow.\n");

package/examples/support-billing-agent/scripts/run-evaluation.sh

@@ -23,10 +23,9 @@ corepack pnpm runner shadow case import \
   --input "$ROOT_DIR/examples/support-billing-agent/shadow-study/cases.jsonl" \
   --store "$STORE_PATH" >/dev/null
 
-corepack pnpm runner shadow outcome import \
-  --study sst_support_reference \
-  --input "$ROOT_DIR/examples/support-billing-agent/shadow-study/outcomes.jsonl" \
-  --store "$STORE_PATH" >/dev/null
+corepack pnpm build:runner-package >/dev/null
+node "$ROOT_DIR/examples/support-billing-agent/app/record-shadow-outcomes.mjs" \
+  "$STORE_PATH" sst_support_reference >/dev/null
 
 corepack pnpm runner shadow report \
   --study sst_support_reference \
@@ -54,7 +53,9 @@ NODE
 
 corepack pnpm runner effect run \
   --dataset "$ROOT_DIR/fixtures/effects/dataset.json" \
-  --results-dir "$ROOT_DIR/fixtures/effects/results" \
+  --adapter node \
+  --adapter-arg "$ROOT_DIR/examples/support-billing-agent/app/effect-adapter.mjs" \
+  --result-origin deterministic-application \
   --format json \
   --out "$EFFECT_PATH" >/dev/null
 

package/examples/support-plan-credit/README.md

@@ -15,7 +15,7 @@ policy-tier demonstration.
 ## Prerequisites
 
 - Docker
-- Node 22.5+
+- Node 22.13+
 - Port `55438` available
 
 Install the stable CLI once for the commands below:
@@ -50,6 +50,42 @@ network connection or connecting to a database. From a source checkout,
 `corepack pnpm verify:adoption` runs this boundary check plus the no-database
 quick demo and MCP config validation.
 
+## Clone And Validate The Same Safe Action
+
+The checked-in code-first action is
+[`synapsor/actions/support.propose_plan_credit.ts`](synapsor/actions/support.propose_plan_credit.ts).
+It is a reviewable frontend for the same canonical JSON contract, not another
+runtime format. Editing it cannot change active tools.
+
+After cloning the repository and installing dependencies, another developer can
+run the deterministic team gate without a database or Cloud account:
+
+```bash
+corepack pnpm install --frozen-lockfile
+corepack pnpm verify:safe-action-team
+```
+
+The verifier copies this example to a disposable directory, compiles the action
+only as a disabled draft, compares the regenerated boundary tests with the
+checked-in file, proves the config and active contract are unchanged, and emits
+text, JSON, and JUnit reports under `tmp/safe-action-team-ci/`. Its static gate
+covers the exact proposal effect, trusted scope, evidence requirement, approval
+policy, operator separation, kept-out fields, argument bounds, and conflict
+guard. It performs no approval, activation, source read, or source mutation.
+
+The same gate runs in
+[`safe-action-ci.yml`](https://github.com/Synapsor/Synapsor-Runner/blob/main/.github/workflows/safe-action-ci.yml).
+CI adds a disposable PostgreSQL service and runs the generated allowed-effect,
+cross-tenant-denial, and source-unchanged assertions. It uses an amount above
+the auto-approval threshold, performs no approval or apply, and requires source
+rows and source receipt state to remain equivalent before and after the live
+suite.
+For a real staging preview, each developer supplies their own
+`PLAN_CREDIT_POSTGRES_READ_URL`, `PLAN_CREDIT_POSTGRES_WRITE_URL`,
+`SYNAPSOR_TENANT_ID`, and `SYNAPSOR_PRINCIPAL` outside Git, then follows the
+Quick Start below. Cursor receives the same proposal-only tools; activation,
+approval, and apply remain outside the agent.
+
 ## Quick Start
 
 ```bash
@@ -199,20 +235,33 @@ shape without guessing which state should change.
 Copy the matching template from [`mcp-client-examples/`](mcp-client-examples/):
 
 - Claude Desktop: `claude-desktop.json`
+- Claude Code: `claude-code.sh`
+- Codex: `codex.config.toml`
 - Cursor project/global: `cursor-project.mcp.json`, `cursor-global.mcp.json`
+- VS Code: `vscode.mcp.json`
 - OpenAI Agents SDK: stdio and Streamable HTTP TypeScript examples
-- generic MCP: stdio and Streamable HTTP JSON examples
+- LangChain/LangGraph: `langchain.mjs`
+- Google ADK: `google-adk.py`
+- LlamaIndex: `llamaindex.py`
+- generic MCP: stdio and Streamable HTTP JSON and JavaScript examples
+
+See [Client And Framework Recipes](../../docs/client-recipes.md) for current
+official references, exact proposal input, evidence labels, and the mechanical
+verification gate.
 
 For Streamable HTTP, run:
 
 ```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+
 synapsor-runner mcp serve \
   --transport streamable-http \
   --alias-mode openai \
   --host 127.0.0.1 \
   --port 8766 \
   --config examples/support-plan-credit/synapsor.runner.json \
-  --store ./tmp/support-plan-credit/local.db
+  --store ./tmp/support-plan-credit/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
 The OpenAI client receives `support__inspect_customer` and
@@ -220,6 +269,8 @@ The OpenAI client receives `support__inspect_customer` and
 tool metadata and results. For Claude, Cursor, or generic MCP clients, omit
 `--alias-mode openai` to expose `support.inspect_customer` and
 `support.propose_plan_credit`. Approval and apply remain outside MCP.
+The HTTP client reads the same opaque endpoint token from its protected
+environment; no token value belongs in the checked-in recipe.
 
 ## How The Policy Is Governed