@synapsor/runner 1.6.2 → 1.6.4

package/docs/store-lifecycle.md

@@ -1,7 +1,8 @@
 # Store Lifecycle
 
 Synapsor Runner keeps local evidence, query audit, proposals, receipts, replay,
-and lifecycle events in a SQLite store.
+worker state, human-attention events, notification delivery state, and
+lifecycle events in a SQLite store.
 
 Default path:
 
@@ -143,6 +144,24 @@ event. The `lifecycle` command never does that; it only reports the most recent
 stored proof and approval linkage. See
 [Proposal And Evidence Freshness](proposal-evidence-freshness.md).
 
+## Human Attention And Delivery State
+
+The store records immutable attention events, coalesced incident projections,
+and sink-specific delivery attempts. Inspect them without copying an ID:
+
+```bash
+synapsor-runner attention show --store ./.synapsor/local.db
+synapsor-runner notifications status --store ./.synapsor/local.db --json
+```
+
+Acknowledgement changes only the attention projection. Notification replay
+requires a fresh verified signed-key or OIDC operator decision plus an explicit
+reason. That decision is bound to the exact delivery revision, requeues only
+the original redacted event, and appends an immutable
+`notification.replayed` audit event. Neither command approves, applies,
+reconciles, or repeats a source mutation. See
+[Human Attention And Notifications](human-attention-notifications.md).
+
 ## Server leases
 
 MCP server modes write a small lease file next to the store:

package/docs/supervised-automatic-apply.md

@@ -0,0 +1,267 @@
+# Operator-Supervised Automatic Apply
+
+Synapsor separates two decisions that are often incorrectly combined:
+
+1. Who or what may approve a proposal?
+2. Who or what may execute an approved proposal?
+
+The model answers neither question. It supplies a bounded request through a
+reviewed capability. Human-reviewed policy may approve that exact immutable
+proposal, and a separately operated Runner worker may apply it only after
+revalidating the complete guarded-write boundary.
+
+Supervised automatic apply is additive and disabled by default. Upgrading does
+not start a worker, change existing `AUTO APPROVE` behavior, or apply an
+already-approved proposal.
+
+## The Four Supported Modes
+
+| Approval | Execution | Behavior |
+| --- | --- | --- |
+| Human | Manual | Default: a qualified operator approves and explicitly runs `apply`. |
+| Human | Supervised worker | A qualified operator approves; the trusted worker may apply. |
+| Policy auto-approval | Manual | Reviewed policy approves; an operator still runs `apply`. This is the legacy `AUTO APPROVE` behavior. |
+| Policy auto-approval | Supervised worker | Reviewed policy approves; an independently enabled worker may guardedly apply. |
+
+The default remains human approval plus manual apply.
+
+## Dual Opt-In
+
+Automatic execution requires both:
+
+1. Contract permission, included in the canonical contract digest.
+2. Deployment permission for the exact capability and exact active digest.
+
+Public DSL (Domain-Specific Language):
+
+```sql
+CREATE CAPABILITY billing.propose_small_credit
+  ...
+  AUTO APPROVE WHEN amount_cents <= 2500
+  LIMIT 20 PER DAY
+  ALLOW SUPERVISED WORKER APPLY;
+```
+
+The final clause compiles to:
+
+```json
+{
+  "execution": {
+    "supervised_worker": "allowed"
+  }
+}
+```
+
+That permission alone applies nothing. The operator must separately configure
+an exact deployment allowlist:
+
+```json
+{
+  "supervised_worker": {
+    "enabled": true,
+    "profile": "production",
+    "capabilities": [
+      {
+        "capability": "billing.propose_small_credit",
+        "contract_digest": "sha256:REPLACE_WITH_THE_ACTIVE_DIGEST",
+        "mode": "supervised_worker",
+        "concurrency": 1,
+        "queue_limit": 100,
+        "lease_seconds": 60,
+        "max_attempts": 5,
+        "proposal_ttl_seconds": 3600,
+        "rate_limit": {
+          "executions": 20,
+          "window_seconds": 60
+        },
+        "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+        "worker_identity": "billing_worker",
+        "control_role": "runner_operator",
+        "require_least_privilege_writer": true,
+        "writer_posture_fingerprint": "sha256:REPLACE_WITH_REVIEWED_POSTURE_DIGEST"
+      }
+    ]
+  }
+}
+```
+
+Use environment-variable names in config, never database URLs or credentials.
+Production also requires verified `signed_key` or `jwt_oidc` operator identity
+for worker controls.
+
+If either opt-in is absent, stale, revoked, or mismatched, the proposal remains
+unapplied. Enabling the worker globally does not enable another capability or a
+new contract version.
+
+## Initial Eligible Write Shapes
+
+The hardened supervised path is intentionally narrower than manual apply. It
+accepts only direct-SQL, single-row proposal capabilities whose complete effect
+Runner can validate:
+
+- `UPDATE` with trusted tenant scope and an exact non-weak conflict/version
+  guard;
+- `INSERT` with trusted tenant scope and a reviewed deterministic
+  deduplication key.
+
+It currently refuses:
+
+- `DELETE`;
+- reversible actions;
+- bounded-set and other multi-row writes;
+- app-owned executors or external effects;
+- arbitrary or model-generated SQL;
+- a missing trusted tenant boundary;
+- an unavailable receipt authority;
+- a shared, privileged, owner, `BYPASSRLS`, or otherwise unverifiable writer
+  when hardened posture is required.
+
+These operations remain available through their documented manual review/apply
+or app-owned executor paths. The narrower worker eligibility does not remove
+existing Runner write capabilities.
+
+## What The Worker Rechecks
+
+Immediately before leasing and applying, Runner rechecks:
+
+- proposal state, immutable hash, version, approval, expiry, and exact active
+  contract digest;
+- contract permission, deployment allowlist, worker identity, control state,
+  profile, generation lock, and current approval-policy snapshot;
+- trusted tenant and principal scope;
+- target row and required supporting-evidence freshness;
+- current source version and exact reviewed before-state;
+- operation, allowed columns, bounds, transitions, row count, and expected
+  effect;
+- approval and execution count/value limits under concurrency;
+- writer credential separation, least-privilege posture, grants, and
+  PostgreSQL RLS posture where configured;
+- operation identity, deduplication, receipt authority, and active lease.
+
+A policy-approved proposal does not gain permanent authority. If the target row
+or mandatory supporting evidence changes before execution, the worker fails
+closed with the established conflict/freshness outcome. A refreshed diff is a
+new proposal with a new hash and needs its own approval.
+
+Manual and supervised execution converge on the same guarded apply
+implementation. The queue is durable work coordination, not a second mutation
+engine.
+
+## Run And Operate The Worker
+
+Validate first:
+
+```bash
+synapsor-runner config validate --config ./synapsor.runner.json
+synapsor-runner doctor --config ./synapsor.runner.json
+```
+
+Run one supervised claim:
+
+```bash
+synapsor-runner worker run --supervised --once --yes \
+  --worker-id billing_worker \
+  --config ./synapsor.runner.json
+```
+
+Run continuously:
+
+```bash
+synapsor-runner worker run --supervised --yes \
+  --worker-id billing_worker \
+  --config ./synapsor.runner.json
+```
+
+Inspect without copying proposal IDs:
+
+```bash
+synapsor-runner worker status --config ./synapsor.runner.json
+synapsor-runner attention show --config ./synapsor.runner.json
+```
+
+Operator controls:
+
+```bash
+synapsor-runner worker pause --yes --config ./synapsor.runner.json
+synapsor-runner worker resume --yes --config ./synapsor.runner.json
+synapsor-runner worker drain --yes --config ./synapsor.runner.json
+
+synapsor-runner worker disable billing.propose_small_credit \
+  --digest sha256:EXACT_DIGEST --yes --config ./synapsor.runner.json
+synapsor-runner worker enable billing.propose_small_credit \
+  --digest sha256:EXACT_DIGEST --yes --config ./synapsor.runner.json
+synapsor-runner worker revoke billing.propose_small_credit \
+  --digest sha256:EXACT_DIGEST --yes --config ./synapsor.runner.json
+```
+
+`revoke` is terminal for that digest. Pause, drain, disable, and revoke stop new
+leasing but preserve queued proposals and durable history. They do not interrupt
+a transaction that already committed.
+
+Dead-letter recovery remains explicit and identity-verified:
+
+```bash
+synapsor-runner worker dead-letter list --config ./synapsor.runner.json
+synapsor-runner worker dead-letter show wrp_... --config ./synapsor.runner.json
+synapsor-runner worker dead-letter requeue wrp_... --retry-budget 3 --yes \
+  --config ./synapsor.runner.json --identity alice --identity-key ./alice.pem
+```
+
+Use the secured Workbench for the same queue, pause/drain, exact-digest,
+dead-letter, and reconciliation controls.
+
+## Retry And Crash Boundary
+
+Runner may retry only a classified transient failure with a proven non-commit
+outcome. Version conflict, stale authority, scope failure, limit failure,
+validation failure, and receipt mismatch do not retry automatically.
+
+Delivery may repeat; mutation must not. Worker leases are fenced, and source
+operation identity plus receipts prevent duplicate effects.
+
+When the database outcome is unknown, Runner does not guess:
+
+- source-receipt mode resolves a known committed operation from the source-side
+  receipt;
+- genuinely ambiguous runner-ledger outcomes enter
+  `reconciliation_required`;
+- automatic retry stops until a verified operator inspects and resolves the
+  established reconciliation record.
+
+This is safe retry and explicit ambiguity handling, not a claim of distributed
+exactly-once execution.
+
+## Optional Supervision-Health Gate
+
+An exact capability policy may name `required_attention_sinks`:
+
+```json
+{
+  "required_attention_sinks": ["operations"]
+}
+```
+
+When present, the worker leaves eligible work queued until every named,
+enabled sink has a healthy delivery record. Sink health never approves a
+proposal and never bypasses either execution opt-in. This gate is off unless a
+capability explicitly names required sinks.
+
+See [Human Attention And Notifications](human-attention-notifications.md) for
+quiet defaults, signed webhooks, routing, and the Workbench inbox.
+
+## Accurate Model-Facing Claim
+
+Without supervised execution:
+
+> This call creates a proposal and does not change the source database.
+
+With exact supervised execution enabled:
+
+> This call creates a proposal. If it satisfies the reviewed automatic-approval
+> policy, a separately trusted Runner worker may automatically apply it without
+> a per-request human click. The model cannot approve, apply, start the worker,
+> or change that policy.
+
+The model can therefore cause a bounded request to enter a pre-authorized
+production pipeline. It still cannot choose the authority, approve the
+proposal, control the worker, or commit a mutation directly.

package/docs/troubleshooting-first-run.md

@@ -3,20 +3,59 @@
 Run the friendly doctor first:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner doctor --first-run
+npx -y @synapsor/runner doctor --first-run
 ```
 
 Use JSON for automation:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
-```
+npx -y @synapsor/runner doctor --first-run --json
+```
+
+## Guided Recovery Contract
+
+Runner 1.6.4 failures should tell you what failed, why the boundary stopped,
+what state remains, and one next action. Do not delete the project or add
+`--force` merely to recover.
+
+| Failure | State preserved | One next action |
+| --- | --- | --- |
+| Database connection or metadata inspection failed | Existing project/review files and source rows | Fix the URL/network without printing the credential, then rerun `npx -y @synapsor/runner start`. |
+| Read role is writable, owner, superuser, `BYPASSRLS`, or unverifiable | Disabled metadata draft; no source-row Explore | Supply a verifiably SELECT-only non-owner staging role, then rerun the same `start` command. |
+| Schema or project choice is ambiguous | Existing files; no authority activation | Rerun with the exact reviewed schema, for example `npx -y @synapsor/runner start --schema public`. |
+| Tenant or principal scope is unresolved | Conservative blocked resource decisions | Open the same Workbench URL and resolve the highlighted scope exception. |
+| Sensitive field remains unresolved | Field stays kept out; active tools unchanged | Open Workbench **Exceptions** and record one reviewed field decision. |
+| Row identifier is missing/composite/ambiguous | Resource remains blocked | Select a source-proven single-column primary/unique identity or keep the resource blocked. |
+| Trusted context environment is missing | Boundary and ledger remain intact; query did not run | Export the named tenant/principal variable locally, then rerun the displayed Try action. |
+| Generated output already exists | Existing files are not overwritten | Rerun the original `start` command and choose **Resume existing review**. |
+| Generation lock is stale | Existing active named capability and review history | Run `synapsor-runner boundary diff --json`, then choose **Rescan and review changes**. |
+| Config JSON is malformed | Config and source database are unchanged | Correct the reported file/line/column, then run `synapsor-runner config validate --config ./synapsor.runner.json --json`. |
+| Config mode is missing/invalid | Config and source database are unchanged | Set `mode` to `read_only`, `shadow`, `review`, or `cloud`, then rerun `synapsor-runner config validate --json`. |
+| Config contains an unknown field | Config and source database are unchanged | Remove or correct the reported JSON path, then rerun `synapsor-runner config validate --json`. |
+| Workbench port is occupied | Review files, ledger, and source database | Rerun `synapsor-runner ui --open`; the default selects a free loopback port. |
+| Workbench Ask is missing | Reviewed project remains usable through no-model Workbench/CLI/MCP | Use authenticated loopback Workbench with an explicit development/staging profile and at least one active reviewed tool. |
+| Ask provider/key fails | Boundary, no-model composer, and external MCP remain usable | Check the exported key name, provider/model access, and local DNS/TLS; then retry without changing authority. |
+| Ask says authority changed | Previous consent is invalid; active reviewed tools remain unchanged | Inspect the new tool/digest summary and acknowledge direct egress again. |
+| Writeback setup fails | Config and reviewed plan; transactional setup rolls back | Rerun `synapsor-runner writeback setup --profile staging --json` and review the reported prerequisite. |
+| Writer role/setup URL is missing | No DDL or grant was applied | Rerun the preview with `--writer-role <role> --setup-url-env <ADMIN_URL_ENV>`. |
+| No supported write candidate exists | Read boundary remains active; no write authority | Use **Add a safe action** on a writable base table with a proven identity/version field, or retain read-only mode. |
+| MCP client installation is unavailable | Project and reviewed authority; client config unchanged | Run `synapsor-runner mcp config --absolute-paths` and use the generic stdio snippet manually. |
+| Supervised work remains queued | Approved proposal and queue state; source unchanged | Run `synapsor-runner worker status --json`, then follow its exact digest, posture, policy, freshness, limit, pause, or required-sink finding. |
+| Required attention sink is unhealthy | Approved proposal remains queued; no source mutation | Repair the operator-owned sink, run `synapsor-runner notifications test --sink <id>`, then dispatch and let the worker revalidate from the beginning. |
+| Notification delivery is dead-lettered | Authoritative event and proposal state are preserved | Repair/test the sink, then run `synapsor-runner notifications replay latest --yes --reason "sink repaired"` with the configured verified operator identity; this resends only the redacted event. |
+| Apply outcome is UNKNOWN | Intent, receipt evidence, and queue state are preserved | Open the latest critical attention item and use the verified reconciliation flow; never rerun the mutation blindly. |
+
+For machine output, a process-level failure emits one redacted JSON object to
+stdout and diagnostics to stderr. `recovery.source_database_changed` is `null`
+when a generic exception cannot establish an operation-specific mutation
+outcome; inspect the durable receipt/reconciliation state rather than guessing.
 
 ## 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.
+Auto Boundary is the default only for a fresh interactive `start` with no
+existing config, selector, answers file, machine-output flag, or other
+automation input. An exported `DATABASE_URL` is implied; explicit connection
+and schema flags still win. This preserves every established 1.x route.
 
 Check the generated state:
 
@@ -58,6 +97,42 @@ 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.
 
+## Workbench Ask Is Missing Or Refused
+
+Ask is optional and follows a stricter local profile boundary. It appears only
+in authenticated loopback Workbench for explicit `development` or `staging`
+projects with at least one reviewed tool. Production, unknown, shared, remote,
+and non-loopback surfaces intentionally omit it.
+
+Normal Runner and MCP execution do not automatically source `.env`. Fresh
+interactive `start` may read a regular project `.env` only after explicit
+consent and keeps the selected database URL in that process. For the optional
+model provider, export the key in the same shell that launches Workbench, then
+select **Read an environment variable** and enter only the variable name. A
+session-only masked paste is also supported.
+
+Provider errors are redacted and do not disable the no-model composer:
+
+- `ASK_KEY_REQUIRED`: export the selected key or use the masked session paste;
+- `ASK_AUTHORITY_CHANGED`: review the current tools/digest and acknowledge
+  direct egress again;
+- `ASK_PROVIDER_UNAVAILABLE`: verify provider availability, key/model access,
+  and local DNS/TLS, then retry;
+- `ASK_PROVIDER_REDIRECT_REFUSED`: use the final fixed endpoint; Runner never
+  forwards credentials across redirects;
+- `ASK_PROVIDER_DESTINATION_REFUSED`: the host resolved to a private, special,
+  metadata, or otherwise disallowed remote address;
+- `ASK_REMOTE_HTTPS_REQUIRED`: remote custom endpoints require HTTPS; HTTP is
+  accepted only on loopback;
+- `ASK_TOOL_REQUIRED`: the provider answered from prose without using a
+  reviewed Synapsor tool;
+- `ASK_UNKNOWN_TOOL` or `ASK_OPERATOR_TOOL_REFUSED`: the provider requested
+  authority outside the displayed tool surface.
+
+Select **Clear** after a session to cancel active work and discard in-memory
+provider configuration/history. See [Workbench Ask With Your
+Model](workbench-ask.md).
+
 ## Cursor Has Production Tools Instead Of Authoring Tools
 
 Install the managed local authoring entry only after boundary activation:
@@ -292,13 +367,13 @@ Own-database MCP setup needs a reviewed config before serving tools.
 Fix:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --from-env DATABASE_URL --mode review --wizard
+npx -y @synapsor/runner init --from-env DATABASE_URL --mode review --wizard
 ```
 
 Or pass an example config:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 ## SQLite Store Missing
@@ -344,7 +419,7 @@ Fix:
 
 ```bash
 export SYNAPSOR_DATABASE_READ_URL="<read-only-url>"
-npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json
+npx -y @synapsor/runner doctor --config synapsor.runner.json
 ```
 
 ## Read/Write Credential Split Failed
@@ -456,7 +531,7 @@ Fix:
 Regenerate the snippet:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp config claude-desktop \
+npx -y @synapsor/runner mcp config claude-desktop \
   --absolute-paths \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db

package/docs/use-your-own-database.md

@@ -10,9 +10,11 @@ model.
 Short path:
 
 ```bash
-export DATABASE_URL="postgresql://readonly_user:password@host:5432/app?sslmode=require"
-npx -y -p @synapsor/runner synapsor-runner start --from-env DATABASE_URL --schema public
+npx -y @synapsor/runner start
 ```
 
-Runner stores environment-variable names in `synapsor.runner.json`, not database
-URLs. Keep credentials in your shell, process manager, or secret manager.
+Paste a read-only URL into the hidden prompt, explicitly approve a regular
+project `.env` file for this process, or export `DATABASE_URL`. PostgreSQL
+defaults to `public`; explicit `--from-env`, `--schema`, and `--project-root`
+flags remain available and always win. Runner stores environment-variable names
+in `synapsor.runner.json`, not database URLs.