@wardby/cli 0.5.3 → 0.7.0

package/docs/knowledge/overview-prisma.md

@@ -0,0 +1,72 @@
+---
+type: overview
+title: Durable data and migration boundaries
+description: Relational definitions and migrations persist identity, run lifecycle, accounting and integration state.
+tags: [database, schema, migrations]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:57.805Z }
+sources:
+  - id: run
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/schema.prisma#L327-L379
+  - id: proxy
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/schema.prisma#L807-L845
+  - id: notify
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql#L1-L47
+  - id: package
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/migrate.config.mjs#L1-L20
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["prisma/**"]
+  citations:
+    - id: run
+      repo: github:wardby/wardby
+      path: prisma/schema.prisma
+      lines: [327, 379]
+      symbol: Run
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:52761459ccb0f62de1ca181d8c506ad51ebfc470b56440eabd80e23c01d0699a
+    - id: proxy
+      repo: github:wardby/wardby
+      path: prisma/schema.prisma
+      lines: [807, 845]
+      symbol: CodingProxySession
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:992812db47e0a461bab6f9527a8e0d8bb9708b0452bbeba1d23169293532d338
+    - id: notify
+      repo: github:wardby/wardby
+      path: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql
+      lines: [1, 47]
+      symbol: wardby_viewer_notify
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:8c16b83ca66d420cd0ccc5824e496625baa8ebc6b1010a0721e4ac36d6419b93
+    - id: package
+      repo: github:wardby/wardby
+      path: prisma/migrate.config.mjs
+      lines: [1, 20]
+      symbol: default migration configuration
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:836356e707ee9b510637dbf067182af05fbb54f548dcdb84f9cbcb8eeeaffb48
+  confidence: high
+---
+
+Prisma defines the durable relational boundary shared by the control plane, executors, gateways and coding proxy. The schema contains agents and attachments, principals and grants, schedules, budgets, runs, accounting ledgers, repository and issue workflow state, authentication state and notification delivery records. Run carries execution ownership, heartbeat and pinned model terms; CodingRun and proxy tables specialize coding execution.[^run][^proxy]
+
+Persistence and consumption proceed through these steps:
+
+1. A deployment or [CLI bootstrap](overview-cli.md) applies migrations using its migration configuration. The packaged configuration resolves the shipped schema and migration directory without importing development-only configuration dependencies.
+2. [Core](overview-core.md) and [MCP](overview-mcp.md) write definitions, ownership and run transitions through transactions.
+3. [Executors and providers](overview-providers.md), the [native gateway](overview-sandbox.md) and [coding proxy](overview-coding-proxy.md) persist their own lifecycle and accounting records linked to runs.
+4. Database triggers publish selected changes to the [viewer](overview-surfaces.md). Notification failures are contained so observation cannot roll back an authoritative write.[^package][^run][^proxy][^notify]
+
+The database owns durable identity, accounting and recovery state; blob contents and worker workspaces live outside it. Runtime database privileges are supplied by [deployment modules](overview-deploy.md).
+
+**What to do:** follow [CLAUDE.md, Database / Prisma](../../CLAUDE.md#database--prisma--strict) for schema work. Review [nullable tool uniqueness](nullable-tool-uniqueness.md) and [viewer notification isolation](viewer-notify-write-isolation.md) for database behavior that the declarative schema alone does not convey.
+
+[^run]: prisma/schema.prisma, lines 327-379.
+
+[^proxy]: prisma/schema.prisma, lines 807-845.
+
+[^notify]: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql, lines 1-47.
+
+[^package]: prisma/migrate.config.mjs, lines 1-20.

package/docs/knowledge/overview-providers.md

@@ -0,0 +1,89 @@
+---
+type: overview
+title: Provider composition and routing
+description: Interfaces separate orchestration from concrete model, execution, identity, persistence and source-control adapters.
+tags: [providers, routing, composition]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:57.805Z }
+sources:
+  - id: registry
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/index.ts#L33-L47
+  - id: execution
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/executor/composition.ts#L87-L126
+  - id: model
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/llm/routing.ts#L67-L79
+  - id: vcs
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/vcs/routing.ts#L26-L53
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects:
+    [
+      "src/providers/index.ts",
+      "src/providers/llm/**",
+      "src/providers/auth/**",
+      "src/providers/storage/**",
+      "src/providers/vcs/**",
+      "src/providers/executor/**",
+      "src/providers/jobs/**",
+      "src/providers/datastore/**",
+      "src/providers/memory/**",
+      "src/providers/engine/**",
+      "src/providers/secrets/**",
+      "src/providers/email/**",
+      "src/providers/review-host/**",
+      "src/providers/issue-tracker/**",
+      "src/providers/chat/**",
+    ]
+  citations:
+    - id: registry
+      repo: github:wardby/wardby
+      path: src/providers/index.ts
+      lines: [33, 47]
+      symbol: ProviderRegistry
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:c78fde4ca7f425d997cece136728d75d49e6c8ada349a77cc4f29c0596e4b9c9
+    - id: execution
+      repo: github:wardby/wardby
+      path: src/providers/executor/composition.ts
+      lines: [87, 126]
+      symbol: buildConfiguredExecutor
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:68bdd107cd1d591a2ac700c253fa8449e7316347e48e23055fca286612685275
+    - id: model
+      repo: github:wardby/wardby
+      path: src/providers/llm/routing.ts
+      lines: [67, 79]
+      symbol: RoutingLlmProvider.entryFor / forRun
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:4b757bc28723803469e6625fb8ba7f9ca6d48cb496b669193d3fa4fb3023d475
+    - id: vcs
+      repo: github:wardby/wardby
+      path: src/providers/vcs/routing.ts
+      lines: [26, 53]
+      symbol: RoutingVcsProvider.target
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:338d5bc2f7ab53f490045d41a6db1639351fc50d958887c77afee4855d46cc6e
+  confidence: high
+---
+
+Provider interfaces are the dependencies passed to [core orchestration](overview-core.md). Adapters implement model access, jobs, execution, identity, secrets, blob storage, datastores, memory, engines and VCS; review-host, issue-tracker and chat registries support external workflows.[^registry]
+
+Composition and execution proceed through these steps:
+
+1. [Configuration](overview-config.md) chooses adapter kinds; composition roots construct implementations and hand them to core.
+2. Executor composition routes persisted run kinds between native execution, optional native sandbox execution and container execution. Coding launchers require a usable worker-image configuration.
+3. Model routing resolves a catalog entry for new work, then can bind an adapter to a run's stored entry. Source-control routing selects local or GitHub implementations from repository kind and refuses unconfigured kinds at use time.
+4. Jobs isolate [coding workers](overview-coding.md); model credentials and VCS finalization remain on the trusted side, while the [coding proxy](overview-coding-proxy.md) meters worker model traffic.[^execution][^model][^vcs]
+
+Adapters own external API translation, lifecycle handles and error semantics. [Prisma](overview-prisma.md) holds durable accounting and workflow state, while storage adapters hold blobs. [Deployment modules](overview-deploy.md) supply infrastructure and identities.
+
+**What to do:** review [blob error semantics](blob-not-found-semantics.md), [bounded artifact reads](bounded-file-descriptor.md), [staging failure isolation](workspace-staging-failure.md) and [private/shared datastore scoping](private-datastore-shared-boundary.md) before replacing an adapter. See [runtime architecture](../architecture-runtime.md) for the process model.
+
+[^registry]: src/providers/index.ts, lines 33-47.
+
+[^execution]: src/providers/executor/composition.ts, lines 87-126.
+
+[^model]: src/providers/llm/routing.ts, lines 67-79.
+
+[^vcs]: src/providers/vcs/routing.ts, lines 26-53.

package/docs/knowledge/overview-sandbox.md

@@ -0,0 +1,83 @@
+---
+type: overview
+title: Native tool and worker isolation
+description: QuickJS evaluates user tools while a run-bound gateway retains privileged effects and native worker authority.
+tags: [sandbox, native, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:57.805Z }
+sources:
+  - id: tool
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/sandbox/user-tool.ts#L20-L46
+  - id: composition
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/composition.ts#L30-L92
+  - id: worker
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/worker.ts#L37-L100
+  - id: gateway
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/gateway-server.ts#L101-L139
+  - id: model
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/gateway-server.ts#L215-L241
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/sandbox/**", "src/native-worker/**"]
+  citations:
+    - id: tool
+      repo: github:wardby/wardby
+      path: src/sandbox/user-tool.ts
+      lines: [20, 46]
+      symbol: runUserToolCall
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:434c5356f9d2f11b7619a6c8aa38e652dc2425a550152ca00e7813f1764f7a0e
+    - id: composition
+      repo: github:wardby/wardby
+      path: src/native-worker/composition.ts
+      lines: [30, 92]
+      symbol: buildNativeSandboxExecutor
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:efd8be98646c541fd49bb8e5881b15e9e63c6419179113cebfc9d02b7e55c725
+    - id: worker
+      repo: github:wardby/wardby
+      path: src/native-worker/worker.ts
+      lines: [37, 100]
+      symbol: runNativeWorker
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:a5ecda1addcbf4acd895a94c3a1670e865342601d5d4028b9bd208119a51ad62
+    - id: gateway
+      repo: github:wardby/wardby
+      path: src/native-worker/gateway-server.ts
+      lines: [101, 139]
+      symbol: handle
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:75818d5d25ee6ecf6c77c802fc123a7f5f396589d4c99325bb37a9b2ec6fb43a
+    - id: model
+      repo: github:wardby/wardby
+      path: src/native-worker/gateway-server.ts
+      lines: [215, 241]
+      symbol: streamModel
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:d3122b8a90bb9b4345ed411b8ddc73fedb0ea9e979f069d1a2f1615ca3eb97dd
+  confidence: high
+---
+
+Native isolation has two layers: user tool bodies execute in QuickJS, and sandbox-mode native agents run their turn loop in a separate worker. The same user-tool function validates arguments and evaluates tool code against an explicitly supplied privileged host.[^tool]
+
+An isolated native run proceeds through these steps:
+
+1. Composition selects the Docker or Kubernetes launcher and optionally wraps it with a single-use warm-worker pool.
+2. The executor establishes a run-bound gateway session and delivers worker input through the launcher's isolation and delivery gates.
+3. The worker drives NativeEngine with model calls and privileged tool effects represented as gateway requests. User tools stay in local QuickJS; built-ins are served remotely.
+4. The gateway validates request shape, run identity and current drivability before serving operations; model calls are restricted to the run's model. Results return to [core settlement](overview-core.md), whose authoritative accounting comes from the trusted side.[^composition][^worker][^gateway][^model]
+
+The area owns worker protocol, sandbox bridges and launch lifecycle. Session, call and warm-worker ledgers live in [Prisma](overview-prisma.md). [Provider adapters](overview-providers.md) remain on the trusted side; [deployment](overview-deploy.md) supplies the network and container boundary. [Coding workers](overview-coding.md) use a separate execution protocol.
+
+**What to do:** preserve [warm input publication](warm-input-publication.md) and the [private/shared datastore boundary](private-datastore-shared-boundary.md) behind privileged effects. See [native sandbox](../native-sandbox.md) for configuration and isolation guarantees.
+
+[^tool]: src/sandbox/user-tool.ts, lines 20-46.
+
+[^composition]: src/native-worker/composition.ts, lines 30-92.
+
+[^worker]: src/native-worker/worker.ts, lines 37-100.
+
+[^gateway]: src/native-worker/gateway-server.ts, lines 101-139.
+
+[^model]: src/native-worker/gateway-server.ts, lines 215-241.

package/docs/knowledge/overview-surfaces.md

@@ -0,0 +1,83 @@
+---
+type: overview
+title: Viewer, observability and knowledge tooling
+description: Read projections, metrics and cited knowledge expose runtime state and architecture without owning execution.
+tags: [viewer, observability, knowledge, tooling]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:23:52.509Z }
+sources:
+  - id: viewer
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/viewer/http.ts#L109-L137
+  - id: events
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/viewer/event-bus.ts#L59-L113
+  - id: metrics
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/observability/metrics-server.ts#L21-L43
+  - id: knowledge
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/knowledge/check.ts#L68-L86
+  - id: fixtures
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/tools/codex-request-shape.ts#L48-L76
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/viewer/**", "src/observability/**", "src/knowledge/**", "src/tools/**"]
+  citations:
+    - id: viewer
+      repo: github:wardby/wardby
+      path: src/viewer/http.ts
+      lines: [109, 137]
+      symbol: createViewerApi.handle
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:03dea11ad42963e9244fcd1b0ecc870b56dd2c2f71524de88138dfe852fbdea5
+    - id: events
+      repo: github:wardby/wardby
+      path: src/viewer/event-bus.ts
+      lines: [59, 113]
+      symbol: createViewerEventBus
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:6a7a2ebbe033f611c7a94ab29f2fcdaf8c1957bf680a36e502406232d81a0301
+    - id: metrics
+      repo: github:wardby/wardby
+      path: src/observability/metrics-server.ts
+      lines: [21, 43]
+      symbol: startMetricsServer
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:19b994cd518149718981334eefc2beca5508501f131b2fab8b1f046764920700
+    - id: knowledge
+      repo: github:wardby/wardby
+      path: src/knowledge/check.ts
+      lines: [68, 86]
+      symbol: checkBundle
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:819ec7779ed8ce9529dfe3364d02936c31f88d98125ad3429094729510151bf1
+    - id: fixtures
+      repo: github:wardby/wardby
+      path: src/tools/codex-request-shape.ts
+      lines: [48, 76]
+      symbol: requestShape
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:e0dfb71fb14012af5b9a41cc893fda12418fd55e11a83ec1ca813c476a07cd79
+  confidence: high
+---
+
+These supporting surfaces turn authoritative state into operator views and engineering evidence. Viewer serves authenticated graph and run-detail projections plus live events; observability exposes Prometheus data; knowledge tooling parses, checks and selects cited concepts; developer tools record and compare provider request fixtures.[^viewer][^metrics][^knowledge][^fixtures]
+
+The main flows are:
+
+1. Viewer authenticates a request and requires admin:view before serving graph, run, infrastructure or event routes.
+2. A lazy Postgres LISTEN connection validates notifications and fans them out to subscribers. The SSE layer signals reconnection gaps so clients can refetch authoritative projections.
+3. The metrics listener exposes its supplied registry at a separate endpoint; the coding proxy supplies request observations.
+4. Knowledge checks parse each concept and compare citation hashes against repository content. Fixture-shape tooling summarizes request keys and types so SDK changes can be reviewed against proxy validation.[^viewer][^events][^metrics][^knowledge][^fixtures]
+
+The area owns API schemas, projections, stream subscriptions, metric registries and knowledge validation results. [Prisma](overview-prisma.md) owns durable run state and notification triggers. [MCP](overview-mcp.md) composes viewer authentication, the [proxy](overview-coding-proxy.md) supplies metering events, and [coding dispatch](overview-core.md) incorporates repository knowledge.
+
+**What to do:** preserve [viewer write isolation](viewer-notify-write-isolation.md); observation must not become a dependency of authoritative state changes. See [viewer API](../viewer-api.md), [observability](../observability.md), [architecture knowledge](../knowledge.md) and [Codex request compatibility](../coding-worker-isolation.md) for the owning guides.
+
+[^viewer]: src/viewer/http.ts, lines 109-137.
+
+[^events]: src/viewer/event-bus.ts, lines 59-113.
+
+[^metrics]: src/observability/metrics-server.ts, lines 21-43.
+
+[^knowledge]: src/knowledge/check.ts, lines 68-86.
+
+[^fixtures]: src/tools/codex-request-shape.ts, lines 48-76.

package/docs/knowledge/private-datastore-shared-boundary.md

@@ -0,0 +1,54 @@
+---
+type: invariant
+title: Private datastore wrappers must reject shared methods
+description: Prefix restrictions on private keys cannot authorize the provider shared-store methods.
+tags: [datastores, capabilities, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: deny
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/datastore/scoped.ts#L33-L52
+  - id: wiring
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/runner.ts#L1368-L1388
+  - id: shared
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/datastores.ts#L119-L151
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/providers/datastore/scoped.ts", "src/core/datastores.ts", "src/core/runner.ts", "src/sandbox/**"]
+  citations:
+    - id: deny
+      repo: github:wardby/wardby
+      path: src/providers/datastore/scoped.ts
+      lines: [33, 52]
+      symbol: scopeDatastore shared methods
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:ab019d2d34268011795717728e7d3a3f37b0e9c106c6f515b935abd4e94a8760
+    - id: wiring
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [1368, 1388]
+      symbol: createNativeRunTools.scopedHost
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:61bb446c6ed2a1fde4c53951680588ac75de28d6b3219eebb8ae801cd4438816
+    - id: shared
+      repo: github:wardby/wardby
+      path: src/core/datastores.ts
+      lines: [119, 151]
+      symbol: scopeSharedDatastoreAccessor
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:508ad8dbaa811b4528d626431b84eda9dd6fe5a2929ffc6005106c9b2eb23703
+  confidence: high
+---
+
+Private and shared datastore operations originate from the same provider interface but pass through different authorization wrappers. The runner gives a tool a private prefix-scoped datastore and a separately scoped shared accessor; forwarding shared methods through the private wrapper would bypass the shared accessor's bound-name and prefix checks.[^wiring][^shared]
+
+The private wrapper therefore rejects every shared method, including reads, even though those methods are unreachable through its current call sites. This prevents a future wiring change from silently inheriting the unscoped provider's shared-store authority.[^deny]
+
+**What to do:** retain the rejecting shared methods when extending the provider interface. Construct shared access through its dedicated accessor instead of treating private key prefixes as a grant on shared stores. The [native capabilities guide](../../help/native-capabilities.md) describes attachment scope; this concept records the consequence at the provider boundary. See [native isolation](overview-sandbox.md) and [providers](overview-providers.md).
+
+[^deny]: src/providers/datastore/scoped.ts, lines 33-52.
+
+[^wiring]: src/core/runner.ts, lines 1368-1388.
+
+[^shared]: src/core/datastores.ts, lines 119-151.

package/docs/knowledge/proxy-settlement-projections.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Proxy usage projections must not govern settlement
+description: Run totals are rebuilt from settled requests while per-model reporting failures are isolated by a savepoint.
+tags: [proxy, budgets, transactions]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: settle
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/coding-proxy/prisma-ledger.ts#L274-L309
+  - id: totals
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/coding-proxy/prisma-ledger.ts#L316-L369
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/providers/coding-proxy/prisma-ledger.ts", "deploy/gke/database-grants.sql"]
+  citations:
+    - id: settle
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/prisma-ledger.ts
+      lines: [274, 309]
+      symbol: complete
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:1e1afa8d2b3ac5786e85308f314d76d5cb955b81a05320bad70d37ab398026d1
+    - id: totals
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/prisma-ledger.ts
+      lines: [316, 369]
+      symbol: recomputeRunTotals
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:f43cf2ec538c24cd65f4a454e6940007226750e06b3cb3ee6668f6ffe2b48a06
+  confidence: high
+---
+
+Completion locks the session before changing the request. Totals are assigned from completed requests and estimated uncertain requests, rather than incremented; RunModelUsage is also rebuilt, but its write runs inside a savepoint and rolls back independently on failure.[^settle][^totals]
+
+**Why:** settling an uncertain request can replace an estimate with actual usage. Incrementing would count both, while allowing a reporting-table failure to abort the transaction would discard the authoritative settlement. Keep ledger and Run writes authoritative and the per-model projection best effort.
+
+[^settle]: src/providers/coding-proxy/prisma-ledger.ts, lines 274-309.
+
+[^totals]: src/providers/coding-proxy/prisma-ledger.ts, lines 316-369.

package/docs/knowledge/run-pricing-first-writer.md

@@ -0,0 +1,43 @@
+---
+type: invariant
+title: Pricing races must use the persisted winner
+description: Concurrent native attempts must reuse the catalog terms that won the conditional pricing write.
+tags: [pricing, concurrency, models]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: pin
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/run-pricing.ts#L45-L69
+  - id: adapter
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/llm/routing.ts#L74-L79
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/core/run-pricing.ts", "src/providers/llm/routing.ts", "src/core/runner.ts"]
+  citations:
+    - id: pin
+      repo: github:wardby/wardby
+      path: src/core/run-pricing.ts
+      lines: [45, 69]
+      symbol: pinNativeRunPricing
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:ceb81fd7d2aa2c29b19b333e93f3838a002aa45498f2b90f6d1aca1f6aed0385
+    - id: adapter
+      repo: github:wardby/wardby
+      path: src/providers/llm/routing.ts
+      lines: [74, 79]
+      symbol: RoutingLlmProvider.forRun
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:5511b7ed50630042519c07b0ef699eaa44cf10951933aeb1db69434f5160f278
+  confidence: high
+---
+
+[Model guidance](../models.md) already describes retaining a run's original catalog terms. The additional concurrency consequence is that two attempts can resolve different live entries before either pins the run. Pricing is written only while pricingVersion is null; an attempt that loses that write reads the stored terms back rather than using its local resolution.[^pin]
+
+The router can bind an adapter to the stored entry, so request shaping and prices stay coupled to the same terms.[^adapter]
+
+**What to do:** preserve both the conditional write and read-back when refactoring load or resume paths. An unconditional update can reprice an active run; ignoring the winning row can make an attempt's provider behavior disagree with durable accounting. See [core execution](overview-core.md).
+
+[^pin]: src/core/run-pricing.ts, lines 45-69.
+
+[^adapter]: src/providers/llm/routing.ts, lines 74-79.

package/docs/knowledge/schedule-claim-transaction.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Schedule deduplication belongs to the transaction
+description: A scheduler lease cannot replace the atomic schedule-window claim and run creation.
+tags: [scheduling, concurrency]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:22:57.651Z }
+sources:
+  - id: claim
+    url: https://github.com/wardby/wardby/blob/9c0f910f919dec4f1a2149bae78612cda41f6007/src/core/scheduler.ts#L50-L82
+  - id: lock
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/dispatch.ts#L667-L684
+wardby:
+  schema: 1
+  roles: [builder, reviewer, planner]
+  affects: ["src/core/scheduler.ts", "src/core/dispatch.ts"]
+  citations:
+    - id: claim
+      repo: github:wardby/wardby
+      path: src/core/scheduler.ts
+      lines: [50, 82]
+      symbol: claimDueRun
+      sha: 9c0f910f919dec4f1a2149bae78612cda41f6007
+      spanHash: sha256:1464539e5b1ac8acf09d9869aaab0fd7ce71ff9647384366537280c850de7b89
+    - id: lock
+      repo: github:wardby/wardby
+      path: src/core/dispatch.ts
+      lines: [667, 684]
+      symbol: dispatchRun
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:88f506bcf07c8b1df9dfd039c4a694fbdd658c9d93948eab6db9575626af0515
+  confidence: high
+---
+
+The scheduler rechecks the due window under an agent row lock, advances `lastScheduledAt`, and creates the run in the same dispatch transaction.[^claim][^lock]
+
+**Why:** the lease coordinates ticking processes, but cannot prevent overlapping claims within a process. Moving the schedule advance outside the transaction can consume a window without a run or admit the same window twice. Keep the claim and persistence together.
+
+[^claim]: src/core/scheduler.ts, lines 50-82.
+
+[^lock]: src/core/dispatch.ts, lines 667-684.

package/docs/knowledge/secret-entry-replica-contract.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Secret entry replicas must share token verification
+description: A shared outcome database cannot complete a secret-entry round trip when replicas use independent signing keys.
+tags: [mcp, secrets, configuration]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: key
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L139-L155
+  - id: codec
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L191-L202
+  - id: outcome
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/tools/secret-elicitation.ts#L79-L104
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/server.ts", "src/mcp/tools/secret-elicitation*"]
+  citations:
+    - id: key
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [139, 155]
+      symbol: loadRequestStateKey
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:09a8e266ca81faa6a3af750f87ab4b7892dba80a2fde187a3af16df22e3e8aa9
+    - id: codec
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [191, 202]
+      symbol: buildMcpServer
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:32779f2edf44c96fb4b295df8feceecaf9f9034c67513ac7074ad6423abf766b
+    - id: outcome
+      repo: github:wardby/wardby
+      path: src/mcp/tools/secret-elicitation.ts
+      lines: [79, 104]
+      symbol: recordOutcome
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:1733171e7240fc8f206a4c0b3a4e45a4e587c252a9f72e0a2d8fc25f2ceae9fd
+  confidence: high
+---
+
+Secret entry can mint a link, accept the browser submission, and poll the result on different HTTP replicas. Outcomes are stored in Postgres, but request-state verification still requires the same signing key on those replicas: `REQUEST_STATE_KEY` when set, otherwise a key each HTTP replica derives from the `SECRET_APP_KEY` they share (a stdio server keeps a random key of its own).[^key][^codec][^outcome]
+
+**What to do:** preserve both shared verification and shared outcome storage when scaling this flow. Database sharing alone leaves browser links unverifiable on another replica. [Secrets and tools](../tool-secrets.md) already describes browser entry; this concept records the replica contract.
+
+[^key]: src/mcp/server.ts, lines 139-155.
+
+[^codec]: src/mcp/server.ts, lines 191-202.
+
+[^outcome]: src/mcp/tools/secret-elicitation.ts, lines 79-104.

package/docs/knowledge/terminal-run-first-writer.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Terminal run state belongs to the first writer
+description: Run completion must conditionally write pending or running rows and read back the persisted winner.
+tags: [execution, recovery, concurrency]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:22:57.651Z }
+sources:
+  - id: states
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L460-L472
+  - id: finish
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L499-L516
+wardby:
+  schema: 1
+  roles: [builder, reviewer, planner]
+  affects: ["src/core/runner.ts", "src/core/reconciler.ts", "src/core/dispatch.ts"]
+  citations:
+    - id: states
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [460, 472]
+      symbol: DRIVABLE
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:77bd85d5b8025e9319afba8477923d068afa0e9bfaea46be28d68b2c41996e7b
+    - id: finish
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [499, 516]
+      symbol: finishRunClaimed
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:258b0ccb1bf328fef95a5e459858eb3f02ecc3d600f6ff4a7aae562a6416936c
+  confidence: high
+---
+
+`finishRunClaimed` restricts its update to pending or running rows, then reads the stored run even when its update lost the race.[^states][^finish] The step-ownership behavior is already described in [Durable executor](../security-deployment.md#durable-executor); this contract covers the terminal database write and its return value.
+
+**What to do:** preserve the status predicate and read-back when adding completion paths. An unconditional write can overwrite a completed or lost run; returning a locally assembled result can report an outcome that never became authoritative.
+
+[^states]: src/core/runner.ts, lines 460-472.
+
+[^finish]: src/core/runner.ts, lines 499-516.