@pikku/core 0.12.72 → 0.12.77

package/CHANGELOG.md

@@ -1,3 +1,1174 @@
+## 0.12.77
+
+### Patch Changes
+
+- 3df4f95: Scaffold virtual user runs as RPCs, backed by a run store.
+
+  `pikku persona run` could already turn a declared persona loose on a running
+  stage, but only from a terminal, and the result only existed in that terminal's
+  output. There was no way for CI, a console, or a scheduled job to start a run —
+  and nothing kept what a run found, so this week's findings could not be compared
+  against last week's.
+
+  `scaffold.virtualUser` now generates two RPCs and the function behind them:
+  - `runVirtualUser({ persona, goals?, memory?, disposition?, budget?, seed? })
+-> { runId }`
+  - `getVirtualUserRun({ runId }) -> { status, findings, tally, memory, … }`
+
+  They are gated on separate scopes — `virtualUser:run` and `virtualUser:read` —
+  because an adversarial run's findings are working exploits carrying live ids,
+  which makes reading them the more sensitive of the two. Production refuses every
+  disposition but `accountable`, checked against the effective one so the
+  per-run override cannot smuggle another in.
+
+  **A run is not a workflow and not a queued job.** It explores, so no two
+  attempts take the same steps and there is nothing to replay; and the record
+  already carries the progress a queue would only be holding on the way to the
+  same place. `runVirtualUser` writes the record, dispatches without awaiting, and
+  returns the id. The cost is stated on the type: a restart mid-run strands a
+  record at `running`, so a run older than its budget window and still `running`
+  is dead rather than working.
+
+  `@pikku/core` gains `VirtualUserRunStore` (with `virtualUserRunStore` on
+  `CoreSingletonServices`), and `@pikku/kysely` ships
+  `KyselyVirtualUserRunStore`, which creates its own table on first use like the
+  audit sink — the runtime never needs it, so it arrives with the feature that
+  fills it rather than in every database.
+
+  Also in core: `prepareVirtualUserRun`, which derives the catalogue, intents,
+  scopes and reachable agents in one place. `pikku persona run` reads the
+  inspector state and the generated RPC reads `metaService`, and the two have to
+  agree — otherwise the same persona and seed explore a different API depending on
+  how the run was started. `personaScopes` moved here from the CLI for the same
+  reason and is still re-exported from its old home. `PRODUCTION_DISPOSITION` is
+  now exported from `@pikku/core/virtual-user`, which it should always have been.
+
+## 0.12.76
+
+### Patch Changes
+
+- 62ea4cc: The audit trail is now readable — in the generated meta, through an RPC, and as
+  a page in the console.
+
+  `audit: true` reaches `FunctionRuntimeMeta.audit` as its resolved form
+  (`{ durability }`), so which functions record anything is answerable without
+  running them. It is informational: the runner still resolves audit from the live
+  function config, so meta and runtime cannot disagree.
+
+  `AuditService` grows an optional read side — `query(AuditQuery)` and `facets()`.
+  Optional because a sink can legitimately be write-only: a queue producer that
+  hands events to another system has nothing to read back, and a reader that finds
+  these absent should say the trail is not readable here rather than that it is
+  empty. The two are very different answers to give someone auditing a system.
+
+  `KyselyAuditService` implements both, newest first with offset paging, filtered
+  by user, action and time window. Two things it now gets right that are easy to
+  get wrong: an empty filter array means "match nothing" rather than "no filter",
+  and results are read by physical _and_ camelCase key, because `CamelCasePlugin`
+  is on most pikku Kysely instances and renames result keys on the way out — the
+  mismatch does not throw, it returns a page of `undefined`. `init()` creates the
+  `audit` table for projects that do not migrate it themselves, from a new
+  exported `auditSchema` that stays out of `pikkuSchemas` because the runtime does
+  not need it.
+
+  The console addon exposes `console:getAudits` and `console:getAuditFilters`
+  behind a new `pikku:audit:read` scope, and forwards the application's `audit`
+  service into the addon's own services — without that last part every install
+  reported the trail as unreadable, whatever sink it had configured.
+
+  The console gets an Audit trail page: an infinite list filtered server-side by
+  user and action, and a row that opens the whole event, metadata rendered as a
+  JSON tree. Refused, unreadable and empty are three different screens, because
+  "you may not read this", "nobody can read this" and "nothing happened" are three
+  different facts.
+
+  Events name the person who caused them. The trail records a user id — the only
+  thing stable enough to record, since a name can change after the event — so
+  `getAudits` resolves those ids against better-auth's user directory at read
+  time, and the page shows the name while keeping the recorded id on the event.
+  The filter follows: pick a colleague by name, filter by the id. A scenario
+  actor is labelled as one, so synthetic traffic is not mistaken for real, and a
+  caller who was signed out shows the wire identity pikku resolved for them
+  rather than being credited to the system.
+
+  **Breaking, for anyone already reading `AuditEvent`:** `actor` is now
+  `userIdentity`, and its type `AuditActor` is `AuditUserIdentity`; `AuditQuery`
+  takes `userIds`/`orgId` in place of `actorUserIds`/`actorOrgId`, and
+  `AuditFacets` returns `userIds`. In pikku an _actor_ is a synthetic person a
+  scenario drives, flagged on the user row — so naming the causer of an event
+  `actor` made the synthetic case unsayable (`actor.actor === true`) and implied
+  every recorded action was a test. The overwhelming majority are ordinary
+  customers. The `audit` table follows: `actor_user_id` / `actor_org_id`
+  are now `user_id` / `org_id`, and a `pikku_user_id` column joins them so the
+  wire identity of a caller who never signed in survives the round trip — the
+  sink was dropping it, which left the console's Session field permanently
+  blank. A project that already migrated the table needs to rename the two
+  columns and add the third; `KyselyAuditService.init()` creates the new shape
+  for anyone who did not.
+
+- 9dddff8: Split a column's at-rest form out of its classification.
+
+  `security: 'encrypted'` sat beside `'secret'` as though the two were
+  alternatives, which made the field unanswerable: a token hash and a live bearer
+  token are both secret, one must never be encrypted — the digest _is_ the lookup
+  key — and the other must always be. A column now carries a second, independent
+  `form: 'plain' | 'hashed' | 'wrapped' | 'sealed'` saying how the bytes are held.
+
+  Declaring a form other than `plain` makes the column's INSERT/UPDATE type
+  nominal — `WrappedValue`, `SealedValue`, `HashedValue` — so a plain string no
+  longer compiles there and the only way to write the column is with something an
+  encrypt, seal or hash call produced. `envelopeEncrypt`, `envelopeRewrap` and
+  `wrapDEK` now return the brand, and a new `hashToken` produces `HashedValue`, so
+  the round trip needs no casts; `column-form.ts` exports deliberately-named
+  `unsafeAs*` assertions for backfills, fixtures and values sealed elsewhere.
+  Reads are unaffected — the brands widen to `string` and compose with the
+  classification brand as `Secret<WrappedValue>`.
+
+  `wrapped` and `sealed` stay distinct because a sealed value is one the
+  application cannot read back; storing one where the other belongs is a row
+  nobody can open.
+
+  A `secret` column that has not declared a form now warns (PKU483), and a form on
+  a non-text column warns and is dropped (PKU484). Both are warnings, so existing
+  projects keep migrating — `pikku db --fail-on-warn` opts into the ratchet, and
+  an explicit `form: 'plain'` is the acknowledgement that silences it. The legacy
+  `security: 'encrypted'` keeps working and now expands to the pair it always
+  meant, `secret` + `wrapped`.
+
+- 78b29f0: `SecretService` now returns a `SecretValue<T>` rather than the bare value, so a
+  vault secret cannot reach a sink by accident.
+
+  `SecretValue` is nominally typed, which means it is not assignable to `string`
+  (or to any other concretely-typed field). Every sink with a real type — a
+  database column, an email body, a session payload — rejects it with no lint
+  rule involved. The sinks typed `any`, `unknown`, or a free generic — the logger,
+  queue payloads, webhook and email inputs, and a function's own output — are
+  guarded with `Safe<T>`, which collapses a `SecretValue` found anywhere inside
+  `T`, however deeply nested, to `never`.
+
+  Unwrap deliberately at the point the secret reaches the wire:
+
+  ```ts
+  const secret = await secrets.getSecret('BETTER_AUTH_SECRET')
+  betterAuth({ secret: secret.reveal() })
+  ```
+
+  Two behaviours cover what types cannot see. Structured serialization redacts —
+  `JSON.stringify` and node's inspect both yield `[secret]`, so an audit or log
+  write stays honest without crashing the request. String coercion throws
+  `SecretCoercionError`, because a template literal is always a leak.
+
+  `AuditLog.write` is guarded the same way as the logger, since an audit event
+  carries `input` and `metadata` as `unknown` and nominality alone cannot stop a
+  secret landing in one.
+
+  `.reveal()` is the deliberate escape hatch, and what it hands back is an
+  ordinary string as far as every sink signature is concerned. **PKU953** closes
+  that gap: under `pikku all --security` the inspector reports a revealed secret
+  that flows into a logger, an audit, a queue, an email or a webhook — `console` included.
+
+  This also fixed a real one: `remote-addon-auth.ts` called `String(token)` on an
+  `unknown` and wrote the result straight into an `Authorization` header.
+
+## 0.12.75
+
+### Patch Changes
+
+- 32277d5: Make a voice conversation with an agent something a chat surface can turn on, rather than
+  something each consumer reassembles.
+
+  The server half already worked — `voiceInput` transcribed, `voiceOutput` synthesized a
+  sentence at a time, and the AG-UI mapper forwarded the audio. What was missing was the
+  turn's own words. The client sends audio, so only the server ever knows what was said,
+  and nothing carried that back: a spoken turn rendered as an empty user bubble followed by
+  an answer to a question nobody could see, and thread history recorded the base64 audio
+  blob instead of the transcript — megabytes of unreadable data in place of the only
+  readable record of the turn.
+
+  `voiceInput` now records what it heard, the stream emits it as a `transcript` event ahead
+  of the run (the reply starts within a few hundred milliseconds, and a question that
+  appears after its answer reads as the wrong question), and it reaches the browser as
+  `pikku:transcript`. Both run paths persist the transcribed message rather than the one
+  that arrived on the wire. `audio-delta` also carries the sentence it says, which is what
+  a barge-in needs to report the part the user actually heard — a reply cut off after "I'll
+  delete the staging database and" is answered very differently depending on whether the
+  model knows the sentence never landed.
+
+  `@pikku/voice-agents` gains the two things a voice UI needs and could not get: a live
+  input level, attached to the source rather than to a detector so it keeps reading on the
+  Silero path, and the microphone list — re-readable on demand, because device labels are
+  empty until permission is granted and nothing fires when it is. `VoiceSession` also
+  learned manual turn boundaries, so push-to-talk is a mode rather than a detector fought
+  to a standstill: holding the key through a three-second pause is someone thinking, and
+  any endpointer worth having would cut them off.
+
+  `<PikkuAgentChat voice />` puts a microphone beside the send button, promotes it to
+  primary when nothing is typed, and opens an indicator with a live level bar, a device
+  picker and a hold-to-record toggle. It plays the agent's speech, and cancels the run on
+  barge-in — talking over the agent should stop the bill, not just the sound.
+
+  Opt-in, because the component cannot check the two things it depends on: the agent has to
+  be wired with `voiceInput` for the audio to be understood and `voiceOutput` for anything
+  to come back.
+
+- ea8aabf: Serve `LocalContent` uploads and signed reads under Bun.
+
+  `LocalContent` hands the browser a `PUT <uploadUrlPrefix>/<key>` upload URL and a signed
+  `GET <assetUrlPrefix>/<key>` read URL, but it is a `ContentService` and cannot answer
+  either — something in the serving path has to. Only `@pikku/node-http-server` did. The
+  same project served under Bun handed out upload URLs that 404ed, with nothing naming the
+  cause: the config was accepted, the service was constructed, and the URLs looked right.
+
+  `@pikku/core` now exports `createLocalContentRequestHandler` from
+  `@pikku/core/services/local-content-request-handler` — the server half of `LocalContent`,
+  expressed in Web `Request`/`Response` so every runtime shares one implementation of the
+  signature check rather than each re-deriving it. It returns `null` for anything that is
+  not a content request, which is the caller's signal to carry on with its normal routing.
+
+  `PikkuBunServer` accepts `config.content` and a `contentSigningJWT` option, mirroring
+  `PikkuNodeHTTPServer`, and answers both prefixes ahead of static mounts and routing.
+  `BunServerRunner` was dropping `contentSigningJWT` on the floor, which silently disabled
+  signed asset reads for every Bun project even once the prefixes were served — the config
+  arrived, the service that verifies its signatures did not.
+
+  Signed reads are refused unless every claim matches, the path included: without that, a
+  signature minted for one asset would read any other.
+
+- 33e96ab: Make a CLI served over a channel typecheck in a real project.
+
+  Both of these are unreachable for a hand-written `wireChannel`, whose routes are usually
+  bare identifiers, and unavoidable for a CLI one, whose routes are command ids.
+
+  `ChannelsMap` emitted route and message keys unquoted. A command id is a kebab or dotted
+  name far more often than not — `app-smoke`, `registry.search`, `package.upgrade-pikku` —
+  and each one ends the property early, so the generated map is not parseable TypeScript at
+  all. One project's map came out with 107 syntax errors from a single CLI channel. Keys are
+  now quoted when they are not bare identifiers, and left alone when they are, so existing
+  generated output is unchanged.
+
+  `executeRawCLIViaChannel` typed its renderers `Record<string, CorePikkuCLIRender<any>>`,
+  whose services parameter defaults to `CoreServices`. The renderers a generated client
+  passes are the app's own, typed against its `SingletonServices`, and a function taking
+  those is not assignable to one taking `CoreServices` — so the generated client failed to
+  compile for any app that adds a service, which is every app.
+
+  Rather than widen the type, it now says what is actually true on that side of the socket:
+  a renderer running on the client gets a logger and nothing else, because there is no
+  service container there to resolve anything from. `CorePikkuCLIClientRender` and
+  `ClientCLIRenderServices` are new exports of `@pikku/core/cli/channel`. They are not
+  expressible as `CorePikkuCLIRender`, whose `Services` parameter is constrained to
+  `CoreSingletonServices` and so demands a `config`, `variables` and `secrets` the client
+  cannot invent. The one cast from the app's renderer type to that shape is localised to the
+  generated client, where it is sound: generation refuses to emit the file at all if a
+  renderer reaches for a service other than `logger`.
+
+- fd72e58: Drop `scenario.step` — a scenario step is now always a `given`, `when` or
+  `then`.
+
+  `step` rendered no keyword, which made it the phase to reach for whenever a
+  step did not obviously fit one of the three. That is exactly the step a reader
+  cannot check: a scenario is read by people deciding whether it describes the
+  behaviour they wanted, and a row that says what it does without saying whether
+  it is setup, action or claim tells them nothing to agree or disagree with. It
+  was also the escape hatch from the assertion lint — a scenario with no `then`
+  could be made to stop complaining by demoting its steps rather than by
+  asserting anything.
+
+  Replace `scenario.step(...)` with whichever of `given`, `when` or `then` the
+  step actually is. `then` is not a rename: it makes the step's bindings
+  witnesses rather than alternatives, so every declared surface runs and they
+  must agree.
+
+- fd72e58: Make personas a first-class surface rather than a detail of the test runner.
+
+  A persona is now read in three places — the knowledge base resolves `persona:`
+  URIs against it, scenarios cast it as an actor, and a virtual user runs as it —
+  so it gets its own page at `/personas` under a new **People** section in the
+  rail, alongside Users. The card is a profile: avatar, name, job title, computed
+  address, the system roles they hold, and how many scenarios cast them. Opening
+  one expands each role to the scopes it confers, which is the half of the picture
+  that explains a 403.
+
+  `definePersonas` takes an optional `avatarUrl` — any URL a browser can load.
+  Nothing is derived from the address: a persona's address is synthetic, so a
+  derived identicon would be the same shrug for everyone. Omitted, the console
+  keeps drawing the deterministic colour-and-icon avatar from the persona's id.
+
+- fd72e58: Read the actors that are not people on the personas page.
+
+  The platform — the app acting on itself, what `pikkuPlatformScenarioStep`
+  declares — now has a row of its own, alongside one per addon whose system a
+  step makes act. They sit behind a People / System / All filter that opens on
+  the people: a subject holds no roles and signs in as nobody, so leading with it
+  would put the rows nothing is authorized through above the ones that are.
+
+  The platform row is built in rather than derived. A project that has never
+  written a platform step still has a platform, and a card that appeared the
+  moment somebody declared their first step would read as a feature they had
+  switched on.
+
+  Also: PKU680 now counts `expectService`, `expectError` and `expectEventually`
+  as assertions. They are inline steps and carry no phase, so a scenario whose
+  only witness was a recorded service call was being told it never asserts.
+
+- 894b2f8: `defineScope` and `defineSystemRole` accumulate across call sites again. Only `definePersonas` is one-per-codebase.
+
+  The previous release made all three single-declaration constructs, which no project scaffolding user-admin could satisfy: the CLI generates a `defineScope` of its own in `user-admin.gen.ts` carrying the whole `admin` tree, and `@pikku/addon-console` spells the same tree out again, so a second hand-written declaration failed the build with PKU583 — and the losing file's scopes were dropped from the metadata rather than merged.
+
+  Exempting generated files would have reinstated exactly the ambiguity the rule removes, only for the files nobody can read the rule from. The real fix is for `admin` to be a default scope nobody declares, at which point the rule can come back for scopes and roles.
+
+  `definePersonas` is unaffected: nothing generates one, so its single call site stands.
+
+- dd19aa7: Drop `scopes` from sessionless functions, rename `selfAuthenticated`, and make both
+  escape hatches opt-in.
+
+  **`scopes` are gone from `pikkuSessionlessFunc`.** They are AND-ed and `verifyScopes`
+  fails closed on a session that does not exist, so every scope listed on a sessionless
+  function rejected the anonymous caller it exists to serve. `CorePikkuSessionlessFunctionConfig`
+  now states this once in core, and the generated `pikkuSessionlessFunc` / `pikkuVoidFunc`
+  configs derive from it — so the field is absent rather than subtracted.
+
+  `@pikku/addon-console`'s `installAddon` and `installOpenapiAddon` are now `pikkuFunc`.
+  Both set `auth: true` and `scopes: ['admin']`, and a test exercises that gate, so the
+  scopes were load-bearing — they only compiled as sessionless because the config accepted
+  a field it could not honour. No behaviour change: both already required a session.
+
+  **`selfAuthenticated` is now `permissionsInBody`.** It never described authentication:
+  what it records is that the permission check lives in the function body rather than in a
+  declared `permissions` entry.
+
+  **Both escape hatches must be opted into**, via a new `allow` block in
+  `pikku.config.json`:
+
+  ```json
+  "allow": { "permissionsInBody": true, "complexWorkflows": true }
+  ```
+
+  Unset means unavailable, and using the feature is a build error naming the flag that
+  would permit it — PKU576 for `permissionsInBody`, PKU643 for `pikkuWorkflowComplexFunc`.
+  Both trade something the tooling can inspect for something only a reader can verify: a
+  permission check buried in a body, or workflow steps that cannot be serialized into the
+  graph, replayed, or migrated. Both are occasionally right, and both are the path of least
+  resistance whenever the declarative form is merely inconvenient. Whoever owns the project
+  makes that call once, in writing, instead of every author making it silently at the call
+  site.
+
+  **PKU574's message no longer contradicts any of this.** Every function it reports is
+  sessionless — that is how the population is selected, not a finding — yet it opened by
+  reporting that they "require neither a session", then advised adding scopes. It now names
+  them as sessionless and recommends only gates an anonymous caller can meet:
+  `permissions`, `auth: true`, `wireAddon({ auth: true })`, or dropping `expose: true`.
+  `permissionsInBody` is deliberately absent from that list: a diagnostic should not
+  advertise its own escape hatch.
+
+- 50ec500: Make `defineScope`, `defineSystemRole` and `definePersonas` single-declaration constructs
+  — exactly one call site per codebase, the rule `pikkuBetterAuth` has always had.
+
+  Each of the three already takes a keyed object, so one call declares as many entries as
+  you like. Spreading the calls across files bought nothing and cost the thing that matters:
+  there was no answer to "where do I add a persona?", so downstream tooling and agents had
+  nowhere unambiguous to read from or append to. The only duplicate handling that existed
+  caught a narrow case — the same id declared twice with different content — and said
+  nothing about the same id declared twice in two files.
+
+  A second call now fails the build with `PKU583` (`defineScope`), `PKU584`
+  (`defineSystemRole`) or `PKU585` (`definePersonas`), naming both source files and saying
+  to declare them all in one call. A second call in the _same_ file is refused too: "the
+  file" is not an answer either when the file holds two calls.
+
+## 0.12.74
+
+### Patch Changes
+
+- 6a307f0: Fix four latent correctness bugs in the function, RPC and error runtimes, and
+  remove dead code from the workflow service surface.
+
+  `WorkflowService.getNodesWithoutSteps` is gone. It was declared on the abstract
+  service and implemented by all five storage backends, and nothing ever called
+  it — hence the non-core packages in this changeset, which only lose that method.
+
+  **An RPC could execute twice.** `RPCService.invoke`, its addon path, and
+  `rpcWithWire` each wrapped the _execution_ of a resolved function in a `try`
+  whose `catch` treated `RPCNotFoundError` as "not found locally" and re-dispatched
+  the call through `deploymentService`. A nested `rpc.invoke` to a missing name,
+  raised from inside an already-running function, therefore re-ran that function on
+  a remote instance after its local side effects had already committed. Resolution
+  is now separated from execution on all three paths, so only a genuinely
+  unresolvable name reaches the fallback. What escapes to callers is unchanged.
+
+  **`addonNamespace` leaked between sibling calls.** The function runner's
+  middleware path restored `rpc`, `functionId`, `audit` and `addonNamespace` after
+  an invocation; the non-middleware path restored the first three but not the
+  fourth. A call into an addon function with no middleware left the addon's
+  namespace on the wire, so subsequent sibling calls resolved the wrong
+  per-instance singletons and `credentialOverrides`.
+
+  **Errors registered on a subclass never resolved.** `misc.errors` was typed
+  `Map<PikkuError, ErrorDetails>` — instances — while `addError` stores
+  constructors, a mismatch hidden by its `error: any` parameter. The instance
+  lookup in `getErrorResponse` was consequently dead, and lookup fell through to a
+  scan comparing `constructor.name`, so a subclass of a registered error got no
+  status mapping at all. The map is now typed `Map<PikkuErrorConstructor, …>` and
+  lookup walks the prototype chain first. Name matching is retained, deliberately,
+  as the fallback that keeps error mapping working when two copies of
+  `@pikku/core` are installed.
+
+  **`createWeakUID` collided across instances.** The prefix was
+  `Date.now().toString(36)` evaluated at module load, so any two instances loading
+  the module in the same millisecond emitted identical `channelId` and `requestId`
+  sequences — reproducibly, not just in principle. It is now seeded lazily from
+  `crypto.randomUUID()`.
+
+  Also: `pikkuState` keys its global map with `Symbol.for` rather than `Symbol`, so
+  two copies of the package share registrations instead of silently getting
+  disjoint state; and the local channel upgrade path no longer keys its middleware
+  cache on the raw request path, which grew the cache without bound while the
+  cached value never varied by path.
+
+- afef587: Close eleven security weaknesses found in a review of `@pikku/core`. Most are
+  breaking, and two invalidate data or credentials already in the wild — read the
+  migration notes before upgrading.
+
+  **Breaking: AI agent thread ownership now fails closed.** Reading, listing,
+  resuming or approving an existing thread or run requires a resolved session
+  principal (`userId`, or `orgId` for `sessionScope: 'org'`), regardless of the
+  agent's `auth` setting. Previously a request without a session had no ownership
+  model at all: the caller-supplied `resourceId` was accepted as the ownership
+  key, so any caller could read or resume another party's thread by naming its
+  `resourceId`. Worse, `threadOwnerConstraint` returned `undefined` for a
+  sessionless caller, and `undefined` means _no filter_ rather than _no rows_ —
+  so `getAgentThreads` returned every thread in the deployment. It now returns
+  `string[]`, empty for a sessionless caller, which every storage backend already
+  treats as matching nothing. Sessionless agents still run one-shot conversations,
+  each with a fresh unguessable owner; what they lose is cross-request continuity.
+  Wire a session to restore it.
+
+  **Breaking: stored secrets and credentials must be re-entered.** `deriveKey` ran
+  a single unsalted round of SHA-256 over the passphrase and used the digest
+  directly as the AES-GCM key — roughly one hash per brute-force guess, with one
+  rainbow table working against every deployment. It is now PBKDF2-HMAC-SHA256 at
+  600,000 iterations over a random salt. There is no compatibility path: every
+  value held by the kysely, mongodb and redis secret services and the kysely
+  credential service becomes undecryptable. They fail loud, naming the key and
+  `key_version`, so the app hard-fails on first secret read until each is re-set.
+
+  The KEK salt is scoped to the key version and stored alongside it, rather than
+  per secret, so a bulk read costs one derivation instead of N — `getSecrets` over
+  50 secrets went from ~2.3s to ~48ms, and rotation from ~4.6s to ~94ms. This adds
+  a salt table (kysely), hash field (redis) or collection (mongodb), created
+  automatically on first use.
+
+  **Breaking: `PIKKU_REMOTE_SECRET` must be at least 32 characters.** The
+  remote-RPC session envelope moved from PBKDF2 to HKDF, which expands
+  high-entropy key material rather than stretching a low-entropy passphrase. That
+  took a remote hop from ~269ms to ~0.4ms — PBKDF2 was running twice per request —
+  but HKDF supplies no brute-force resistance, so the secret must carry the
+  entropy itself. A shorter secret now throws `WeakKeyMaterialError` at both ends.
+  Generate one with `openssl rand -base64 32` and roll it out to every service in
+  the mesh together: existing bearer tokens are format-incompatible, so a partial
+  rollout produces 401s until every instance is updated. The Cloudflare, Lambda
+  and Azure deployment services each hand-rolled a copy of `buildRemoteHeaders`
+  and now call the shared one, which is what keeps the two sides in step.
+
+  **Breaking: previously signed content URLs stop verifying.** `LocalContent`
+  signed only `{signedAt, expiresAt, notBefore}`, so a signature proved when a URL
+  was issued but never what it was issued for — any valid token was a skeleton
+  key, and swapping the pathname from a public thumbnail to a private document
+  still verified. The signature now binds the request path. Separately, the
+  verifier returned "valid" when no JWT service was wired, which is how
+  `pikku serve` ran: a forged `?signedAt=0&expiresAt=99999999999999` was accepted.
+  It now rejects with 403, `LocalContent` requires a `JWTService`, and
+  `pikku serve`/`pikku dev` mint an ephemeral per-process signing key so local
+  development works without shipping a fail-open path. In-flight signed URLs must
+  be re-issued.
+
+  **Request body size limits now apply to every adapter.** The `maxBodySize` cap
+  existed only in `PikkuFetchHTTPRequest`. The real hole was uWebSockets, which
+  drove `res.onData` itself and concatenated every chunk with no bound and nothing
+  downstream able to intervene; it now drops chunks past the limit and replies 413
+  before routing. Fastify delegates to its native `bodyLimit` (set only when
+  `maxBodySize` is configured, so fastify's stricter 1 MB default is never
+  loosened), and `PikkuExpressServer` feeds the limit into its body parsers. Two
+  paths can only reject rather than prevent, and are documented as such:
+  `express-middleware` mounted on your own app receives an already-parsed body, so
+  that deployment must bound its own parser; Next server actions bottom out at
+  `experimental.serverActions.bodySizeLimit`.
+
+  **Breaking: the console addon's privileged functions are gated by default.**
+  `wireAddon` gains a `scopes` option that applies to every function in the
+  addon's namespace, and the console scaffold now generates
+  `wireAddon({ name: 'console', package: '@pikku/addon-console', scopes: ['admin'] })`.
+  Previously the console's entire privileged surface — around 54 functions
+  including `credentialGet`, which returns a resolved OAuth token for an arbitrary
+  `userId`, `updateFunctionBody`, and `installAddon`, which shells out to a
+  package install — was protected only by an optional host-registered
+  `addGlobalPermission`. `resolveGlobalPermissions` returns `[]` when none is
+  registered and permission checking then no-ops, so an app that never registered
+  one served those functions to anyone, and with the template's default
+  `scaffold.rpc: "no-auth"` that meant unauthenticated. All of them now return 403
+  `MissingScopeError` without an `admin`, `admin:*` or `*` scope. **Regenerating
+  is required** — an app holding an old `console.gen.ts` stays open.
+  `installAddon` and `installOpenapiAddon` additionally declare their own
+  `auth: true, scopes: ['admin']`, and `getAgentThreads` now scopes its listing to
+  the session's own threads unless the caller holds admin.
+
+  Addon scopes are enforced in `runPikkuFunc` rather than at the RPC boundary,
+  because a wiring can reference an addon function directly — the inspector
+  records the addon's `packageName` on HTTP, channel, schedule, queue, CLI,
+  trigger, gateway and MCP wirings — and those paths never call `resolveNamespace`.
+  Enforcing at the RPC seam would have covered only the `namespace:function` form
+  while reading as complete.
+
+  **Breaking: `wireAddon`'s `auth` and `tags` now apply on direct wirings too.**
+  Both were read only by `resolveAddonFunction`, so they had exactly the hole
+  scopes had: `wireAddon({ name: 'console', package: '@pikku/addon-console', auth:
+true, tags: ['admin'] })` gated `rpc('console:credentialGet')` and gated nothing
+  at all on an HTTP route wired straight to `credentialGet`. A consumer who
+  reached for the documented way to lock an addon down got a control that was
+  silently inert on every wiring except one. Both now resolve in `runPikkuFunc`.
+  `auth` merges as an OR — `auth: false` from an addon is ignored on a direct
+  wiring, because an addon may require a session the wiring did not but must never
+  waive one it did. Addon tags resolve to concrete middleware against the **root**
+  tag groups before the call rather than being folded into the function's
+  inherited middleware: `addTagMiddleware('admin', …)` is written by the consuming
+  app and registers under the root package, whereas `combineMiddleware` would look
+  the tag up under the addon's own `packageName`, where it does not exist.
+
+  One consequence worth naming: an addon that wires `auth: true` and also runs its
+  own sessionless internal work — a scheduled task or queue worker inside the
+  addon calling a sibling function — is now gated where it previously was not,
+  because a bare `rpc('fn')` from inside the addon reaches `runPikkuFunc` with the
+  addon's `packageName` like any other call. This reverses a decision that
+  deliberately scoped the gate to the namespaced boundary; that reasoning held
+  only while the boundary was real, and a direct wiring can enter an addon without
+  crossing it, so "already inside" is not something the runtime can infer. Such an
+  addon should carry authorization on the function via
+  `pikkuFunc({ permissions })`, which has always been enforced on every path. A
+  follow-up will add execution provenance so an intra-addon call can be
+  distinguished from an external one and skip the addon-level check; that needs a
+  marker no caller outside the process can set, which is its own design problem
+  and does not belong in a security fix.
+
+  **Codegen now warns when an exposed function has no gate (PKU574).** The
+  generated `POST /rpc/:rpcName` dispatcher forwards to `rpc.exposed`, which
+  refuses anything without `expose: true` — but nothing checked whether the
+  target was gated, because a dispatcher cannot know what it dispatches to. The
+  console shipped ~54 privileged functions through that gap and the toolchain was
+  silent. The inspector now reports every function that is exposed, sessionless,
+  and carries no `auth`, `scopes` or `permissions` of its own and none from a
+  governing `wireAddon`. It is a `warn`, not a critical: `expose: true` on an
+  ungated sessionless function is correct for a genuinely public endpoint, so it
+  blocks a build only under `--fail-on-warn`.
+
+  Two pieces of metadata were missing for this to be answerable statically, and
+  both are now recorded. A `pikkuSessionlessFunc`'s own `auth: true` was read at
+  runtime but never written to function meta, so a self-gated function was
+  indistinguishable from an ungated one — `sessionless` carries the baseline, and
+  `auth` now carries the tightening. And `wireAddon`'s `scopes`, `auth` and `tags`
+  were not parsed at all: the inspector recorded the addon's `rpcEndpoint` and its
+  secret, variable and credential overrides, and dropped every one of its gates.
+  An addon whose gates are not statically knowable is treated as gated, because a
+  false positive on a correctly-secured addon costs more than the one case it
+  would catch.
+
+  **Breaking: an application's global permissions now apply inside addons.**
+  `resolveGlobalPermissions` read only the bucket matching the function's own
+  package, but the generated `addGlobalPermission` wrapper takes no package
+  argument and always registers under the root. An app-wide rule like "every
+  request needs a signed-in user" therefore stopped at the addon boundary, and the
+  bucket an addon's functions did read was one no host could write to — which is
+  why the console addon's recommended `addGlobalPermission([isAdmin],
+'@pikku/addon-console')` was never a gate anybody could actually install. A
+  function now resolves the root bucket and its own package's, root first.
+  Unioning is safe in a way nothing else here would be: globals AND, so adding the
+  root ones can only tighten. Package buckets stay one-way — a package's globals
+  never reach root functions, or an installed addon could gate the whole
+  application. Apps with both a root global and addon-provided functions will see
+  those functions gated where they previously were not.
+
+  **Codegen now records whether each HTTP route requires a session, and warns
+  about inert addon tags (PKU575).** Four separate things can demand a session —
+  the function's `sessionless`, its own `auth`, the route's (or its group's)
+  `auth`, and the addon it belongs to — and answering "which routes are open?"
+  meant joining all four by hand and knowing which wins. Each route's meta now
+  carries the resolved `requiresSession` alongside the route's own `auth`. Scopes
+  count as requiring one, since they are matched against the session's and fail
+  closed. Anything not statically knowable resolves to `true`, matching PKU574:
+  a route that looks stricter than it is costs less than one that looks open and
+  isn't. Separately, `wireAddon({ tags: ['admin'] })` reads like a gate and is
+  applied like one right up until no `addTagMiddleware('admin', …)` exists, at
+  which point it resolves to an empty list and gates nothing; that now warns.
+  Only addon tags are reported — a tag on a function is as likely to be
+  organizational, and warning about those would bury the case that matters.
+
+  **Object-shorthand permissions were missing from meta.** The inspector visited
+  `ts.PropertyAssignment` but not `ts.ShorthandPropertyAssignment`, so
+  `permissions: { canAdminOrg }` — enforced identically to the longhand form at
+  runtime, since `verifyPermissions` has a non-array branch — was recorded as _no
+  permissions at all_. That is the most dangerous direction for meta to be wrong
+  in: an audit reading it sees an open door where one is shut. It cost this review
+  a false IDOR report across ~35 billing and org functions before the source
+  contradicted the metadata.
+
+  **Functions that authorize in their own body can say so.** A webhook receiver
+  verifying a signature, or a handler redeeming a signed invite, is genuinely
+  closed while carrying no session, scope or permission — indistinguishable in
+  meta from one nobody remembered to gate, and so warned about forever by PKU574.
+  `selfAuthenticated: true` on the function config records the claim and silences
+  the warning for that function. It is declarative only: nothing at runtime reads
+  it and it grants nothing. Detection was rejected deliberately — inferring it
+  from the body means a function that _looks_ like it checks something silences
+  the warning while checking nothing, and a warning that is usually wrong stops
+  being read.
+
+  **Breaking: `scaffold.<feature>` is now `boolean | { auth?, path? }`, and `true`
+  means authenticated.** The old `'auth' | 'no-auth' | false` read like a
+  starter-file preference while being a live authorization decision, set three
+  directories from the functions it governed — the shape the console incident
+  took. A surface now becomes public only by writing `{ auth: false }`, so
+  omitting a field can never open anything: the failure mode of a forgotten flag
+  is a locked door. `{ path }` additionally overrides where the file is
+  generated, which previously could only be set for all features at once via
+  `pikkuDir`.
+
+  The legacy strings are **refused, not coerced**. `resolveScaffoldFeature` throws
+  naming the key and its replacement (`"rpc": "no-auth"` → `"rpc": { "auth":
+false }`), and it does so at config load, not downstream. An earlier design used
+  a bare `string` for the output path, under which `"no-auth"` would have parsed
+  as a file named `no-auth` and every unmigrated config would have silently
+  produced nonsense; the object form makes any string invalid, so the failure is
+  loud.
+
+  The collapse is deliberately not uniform in effect. For `rpc` the flag was a
+  blanket "no anonymous RPC in this app" set on a dispatcher that cannot know what
+  it dispatches to; for `userAdmin` it was redundant, since the generated
+  functions are already `pikkuFunc` with `scopes: ['admin:users:list']`. But for
+  `agent`, `workflow`, `events` and `scenarios` it is the only gate — those
+  generate real endpoints the app never authors — so `true` keeps them
+  authenticated rather than opening them as a side effect of a config cleanup.
+  `webhook` and `remoteRpc` have no auth dimension at all (`serialize-remote-rpc.ts`
+  hardcodes `auth: false`), so an `{ auth }` on them is ignored. The three
+  configs in this repo are migrated preserving their current behaviour exactly.
+
+  **Queue job identities are signed.** A job carried the producer's `pikkuUserId`
+  as a plain string and the worker resolved a session from it with no
+  verification, so write access to the queue backend was act-as-any-user. The
+  identity is now `pq1.<claim>.<hmac>`, HMAC-SHA256 over the claim and the
+  canonicalized job payload, keyed by HKDF expansion of a new
+  `PIKKU_QUEUE_IDENTITY_SECRET`. Producers opt in by wrapping their queue service
+  with `SignedQueueService`. This fails safe rather than closed: with no secret
+  configured the identity is dropped and jobs still process, warning once per
+  process, so no existing deployment breaks on upgrade — it simply loses queue
+  identity until the secret is set. The payload rather than the job id is bound
+  because SQS, Cloudflare Queues, Azure and the in-memory service all mint ids
+  after `add` returns.
+
+  **Workflow inline state is read from the run record.** `isInline` consulted a
+  process-local `Map`, while `WorkflowRun.inline` is durable. Any instance that
+  did not start a run disagreed with the record, so one instance could dispatch a
+  queued job for a workflow another was already executing in-process. It is now
+  async and resolves through the durable identity, cached only when a context
+  already exists so a passive reader allocates nothing. The same `Map` also leaked:
+  `nextStepKey` fabricated replay state on every step, and `releaseContext`
+  refused to free anything carrying it, so runs whose steps executed outside a
+  `beginReplay` bracket — the step-worker queue path — stranded their context and
+  step state for the process lifetime. Contexts are now released by an explicit
+  execution counter. Step ordinals reset per execution rather than accumulating
+  across step-worker invocations in one process, which makes step naming
+  independent of how work was distributed.
+
+  **Secret reads fail loud in every store.** `MongoDBSecretService.getSecrets`
+  skipped rows that failed to decrypt, and the redis equivalent dropped every
+  rejection via `Promise.allSettled`, including the "No KEK available for
+  key_version N" configuration error. Both now throw, naming the key and its key
+  version, matching the kysely behaviour. This matters most alongside the KEK
+  change above: without it, an upgrade surfaces as a partial secrets map and an
+  opaque downstream failure instead of an error naming the secret to re-enter.
+
+  **A second middleware registration for a pattern no longer erases the first.**
+  `addHTTPMiddleware`, `addTagMiddleware` and `addChannelMiddleware` groups are
+  keyed by pattern or tag and held one source file each, so a second file's call
+  overwrote the first's. Codegen emits its imports from what is stored, so the
+  losing file was never imported and its middleware never registered — the
+  runtime composes repeated registrations for a pattern happily, and only codegen
+  dropped one. Adding an unrelated `addHTTPMiddleware('*', …)` to an app was
+  enough to silently unregister the generated better-auth session bridge, which
+  fails open and gives no sign until a request arrives without a session. A group
+  now carries every registration made for it, and all of them are imported.
+
+- 8075f6a: Confine `SecretService` to the places an app is wired.
+
+  `secrets` is now omitted from the services every function, AI agent, workflow,
+  permission and wire receives, and the function runner replaces it with a
+  throwing accessor so a cast cannot reach past the type. It stays available in
+  `pikkuServices`, `pikkuWireServices`, addon service factories and middleware —
+  read a secret there, give it to a service, and have the function ask that
+  service.
+
+  Alongside it:
+  - `wireSecret` gains `allowedHosts`, refusing a secret attached to a host it was
+    not declared for. Permissive by default; strict via
+    `config.secrets.requireAllowedHosts`.
+  - `pikku-graph`'s `httpRequest` resolves and attaches its credential inside a new
+    `httpRequester` service instead of holding the plaintext in the function.
+  - New inspector diagnostics: `PKU950` (a `SecretService` exposed under another
+    service name), `PKU951` (a secret read that no `wireSecret` declares) and
+    `PKU952` (a secret read with a non-literal key).
+
+## 0.12.73
+
+### Patch Changes
+
+- c984df6: Give an agent's tools back the descriptions their authors wrote
+
+  A tool's description is what the model is told the tool does, and the main
+  thing it chooses between tools on. It was not reaching the model. `description`
+  is classed as a verbose field, so it is stripped from the metadata bundled into
+  the generated bootstrap — the copy `pikkuState('function', 'meta')` is built
+  from. `buildToolDefs` read the description from there, found it always
+  undefined, and fell through to the tool's own name. Every agent has been
+  choosing between bare identifiers. The same fallback was offering an addon's
+  MCP tools under their names, for the same reason.
+
+  Tool definitions now resolve descriptions through `metaService`, which reads
+  the verbose metadata and falls back to the minimal copy, so the authored text
+  is recovered wherever the generated `.pikku` directory is readable. Where it is
+  not — no `metaService`, or a deployment shipping only the stripped copy — a
+  tool falls back to its name, which is what it did before. Addon metadata is
+  likewise loaded verbose-first. `title` is no longer part of the chain: a title
+  labels a tool in a UI, it does not tell a model when to reach for it.
+
+  An addon has to ship the verbose file for any of this to reach it. `tsc` only
+  emits the JSON it sees imported and nothing imports the verbose meta, so the
+  bundled addons now copy it into `dist` explicitly.
+
+  `ref()` is resolved at build time. It used to be pushed through codegen as an
+  opaque string, so `ref('todos:doesNotExist')` generated cleanly and failed only
+  when the agent ran. The inspector now resolves each reference against the
+  project's functions, or — using the namespace-to-package mapping `wireAddon`
+  already provides — against the addon's own metadata, and reports an unwired
+  namespace (`PKU152`) or a missing function (`PKU153`) at codegen. An addon that
+  has not been built yet contributed no metadata and is skipped rather than
+  reported missing.
+
+  New `pikku --strict-meta` additionally fails the build on any agent tool with
+  no description (`PKU154`), including tools reached through an addon. It is off
+  by default, so nothing that builds today stops building; turn it on to hold a
+  project to the metadata its agents actually run on.
+
+- 63ff32b: Run a CLI's commands on the server, over the connection the client opened
+
+  A CLI that talks to a service has to ship the service's command tree, so the
+  two versions drift: the binary someone installed months ago still believes in
+  flags and commands the server has since changed. This makes the command tree
+  the server's, and leaves the client holding only a socket.
+
+  `wireCLI` gains `auth`, and a program wired with a channel entrypoint now
+  generates a `__raw` route: the client forwards argv untouched, the server
+  parses it, runs the command, and streams the output back as it happens. The
+  terminating frame carries the exit code, so a failed remote command still exits
+  non-zero locally. Renderers stay on the client and are matched by the command
+  id the server reports; an unrecognised command falls back to JSON rather than
+  failing.
+
+  Every channel gains `channel.remote(...)`: calling a function on the peer at
+  the other end of the connection and waiting for its answer. A channel is
+  otherwise fire-and-forget in both directions, so this is what reaches a peer
+  that has no address of its own — a CLI on a laptop, a browser tab, a sandbox
+  behind NAT. It is on `channel` rather than `rpc` because it is bound to one
+  connection: which peer answers is the socket the call goes out on, not
+  something the RPC map could resolve. Any `wireChannel` gets it — a client
+  registers what it is willing to answer to, and a name outside that list is
+  refused.
+
+  Requests are correlated by id, time out, and fail fast when the socket closes
+  rather than waiting out the timeout. Replies are taken off the socket ahead of
+  routing, so a channel needs no route for them and an answer can never be
+  mistaken for a new message; the transport is created on first use and released
+  when the channel closes, which is also what fails anything the departing peer
+  still owed an answer to. Channels that only flow one way — SSE, an agent's
+  output stream, a locally-run CLI — refuse the call outright instead of waiting
+  for an answer that was never going to come.
+
+  What a peer answers with is its word, so it is checked before a caller sees it
+  — against the schema codegen already generated from the function's declared
+  return type, the same one an agent tool or an HTTP response is checked against.
+  A capability is declared with `pikkuRemoteChannelFunc`, which takes the usual
+  `title` / `description` / `input` / `output` but no `func` — this side owns the
+  contract, the peer owns the body. It registers under its name like any other
+  function, so `channel.remote` is typed off the same generated map as
+  `rpc.remote` and no caller has to cast, and a local call throws rather than
+  missing: reaching it locally means a command asked the server for something
+  only a client knows. A client on an older build fails the call it answered
+  rather than the caller failing later somewhere with no reason to expect a bad
+  shape; a name with no declared contract is left alone. Both frame guards
+  validate the whole envelope rather than the action tag alone, and a failure
+  payload with a non-string name or message falls back rather than being attached
+  to an `Error`.
+
+  The arguments going the other way are checked too, against the schema for the
+  capability's declared input, before anything is registered or sent. That is not
+  a boundary — the peer runs the code and has to check what it was handed, and a
+  caller that meant harm would send arguments that pass. It catches drift, where a
+  server built against a newer capability signature calls a client that predates
+  it, and fails it here rather than inside someone else's process.
+
+  A channel-driven CLI command uses this to ask its caller for machine-local
+  facts mid-run — a git sha, a working tree, a local file. The CLI wire's own
+  channel is synthetic (it exists so a command can stream progress without
+  knowing where that goes), so it delegates `remote` to the connection the
+  command actually arrived on.
+
+  Because that runs code on someone's machine at a remote caller's request, the
+  capability map says what _can_ run and approval says whether a particular call
+  _should_. A capability may be declared `{ execute, needsApproval }`, sharing
+  `ApprovalPolicy` — `needsApproval` and `approvalDescriptionFn` — with
+  `AIAgentToolDef`, which has carried both since before channels could call back:
+  both are an allowlist of named callables invoked by something other than the
+  code that wrote them. The runtime around them is deliberately not shared, since
+  an agent suspends its run and resumes it later while a reverse call is a live
+  await with a person at the other end.
+
+  A capability written as a bare function is unclassified, and unclassified means
+  approval is required — the annotation nobody got round to writing is the one
+  most likely to matter, so it fails closed. Declare
+  `{ execute, needsApproval: false }` for a capability that may run unattended.
+  Nothing infers this: core cannot tell a read-only capability from a destructive
+  one, so `needsApproval: false` is the author asserting it, and the assertion is
+  the only thing standing between a remote caller and the machine.
+
+  The default is the opposite of `AIAgentToolDef`'s, where absence means "do not
+  ask" — a tool is written by the same people who run the server it executes on,
+  and a capability is not.
+
+  `executeRawCLIViaChannel` reads `--auto-approve` and
+  `--dangerously-auto-approve` out of argv (or `PIKKU_AUTO_APPROVE` /
+  `PIKKU_DANGEROUSLY_AUTO_APPROVE`) and strips them before argv reaches the
+  server — what may run on this machine is this machine's decision, and a flag
+  the server can see is one the server could act on. `--auto-approve` permits the
+  classified-safe set and refuses the rest; `--dangerously-auto-approve` permits
+  everything and says so once on stderr. Interactively the user is asked per
+  call, with `y` / `n` / `a`, where `a` is remembered for that one capability for
+  the rest of the run and never written to disk — widening it to the session
+  would quietly turn an interactive run into `--dangerously-auto-approve`. A run
+  with no terminal and no flag refuses rather than assuming yes, because CI is
+  exactly where an unattended `git push` would otherwise happen. The tiers are
+  meaningful here in a way they would not be for an agent: the caller is a
+  deterministic program whose source can be read, so "these calls are always
+  fine" is a claim someone can actually justify.
+
+  A peer that is asking a human sends a pending frame first, which stops the
+  caller's timeout. Without it any approval slower than the timeout would fail
+  the call and then discard the decision when it finally arrived. The call is
+  still failed the moment the socket drops — what actually happens when a peer
+  dies mid-prompt — and a peer that sends the frame dishonestly can do nothing
+  but keep its own call waiting. A refusal is sent as an answer, so a denied call
+  fails its command immediately rather than hanging.
+
+  Fixes found on the way, each of which broke this path:
+  - A websocket upgrade wrote middleware headers (CORS, on every request)
+    straight onto the socket, so the first bytes a client saw were headers rather
+    than `ws`'s `101` status line and the handshake failed to parse. Header
+    writes are now buffered and flushed behind a status line only when the
+    upgrade is actually being rejected.
+  - An upgrade socket had no error listener while the channel opened, so a client
+    that gave up mid-handshake took the whole server process down with an
+    unhandled `ECONNRESET`.
+  - `onConnect` and `onDisconnect` never saw the session established during the
+    upgrade, so a channel could not tell who had just connected.
+  - Setting the routing key on a channel result mutated the value in place, which
+    throws for a primitive under ESM strict mode.
+
+- ba6cc08: fix: stop leaking internal error detail and bound the request body size
+
+  HTTP error responses no longer forward an error's `payload` or its raw `message` for
+  registered 5xx errors — those responses carry the registered error message instead, so an
+  internal error that happens to hold a `payload` cannot leak it to the client. Errors
+  registered with a 4xx status keep their message and payload, and `exposeErrors` still
+  surfaces the full detail outside production.
+
+  `PikkuFetchHTTPRequest` now caps how much of a request body it buffers, rejecting the
+  declared `content-length` up front and measuring the stream as it arrives so a lying or
+  absent header cannot exhaust memory. Exceeding the limit throws `PayloadTooLargeError`
+  (413). The ceiling defaults to 10MB and is configurable via the new `maxBodySize` option on
+  the constructor and on `RunHTTPWiringOptions`.
+
+- d007191: `cors()` takes an `exposeHeaders` option.
+
+  Without `Access-Control-Expose-Headers` a cross-origin caller can read only the
+  CORS-safelisted response headers, so any header the client is meant to act on was
+  invisible to it. The cross-site session relay in `@pikku/better-auth` is the case that
+  surfaced it: the client cannot read `x-pikku-cross-site-set-cookie` off a cross-origin
+  response without being told it may.
+
+  Defaults to none, so nothing new is exposed unless it is named.
+
+- a7b26c5: rename the inspected declarations to `define*`: `wireScope` → `defineScope`, `wireSecret` → `defineSecret`, `wireVariable` → `defineVariable`, `wireCredential` → `defineCredential`
+
+  `wire*` meant two unrelated things. A transport wiring attaches a function to
+  something that can invoke it — `wireHTTP`, `wireChannel`, `wireScheduler`,
+  `wireQueueWorker` and the rest — and the thing it wires runs. These four wire
+  nothing: they are no-ops that exist only so the call typechecks, they are
+  tree-shaken out of the build, and their whole job is to be found by the
+  inspector's AST pass and turned into a type union. One word for both left the
+  declaration reading like a registration with a runtime.
+
+  So the vocabulary splits: **`wire*` is a transport, `define*` is an inspected
+  declaration.**
+
+  ```ts
+  import { defineScope } from '@pikku/core/scope'
+  import { defineSecret } from '@pikku/core/secret'
+  import { defineVariable } from '@pikku/core/variable'
+  import { defineCredential } from '@pikku/core/credential'
+
+  defineScope({ admin: { scopes: { invoices: { scopes: { create: {} } } } } })
+  ```
+
+  **Breaking:** no alias is kept. Rename the four call sites; the module subpaths
+  (`@pikku/core/scope`, `/secret`, `/variable`) are unchanged.
+
+  The inspector matches these by identifier text, so a stale `wire*` call is not a
+  type error — it is silently not extracted, and the generated union comes back
+  empty. That fails as "this scope isn't declared" on code that was fine a moment
+  ago, nowhere near the declaration. Grep for the old names rather than trusting a
+  clean build.
+
+  An addon published with `.pikku` output generated before this release re-exports
+  `wireSecret` from `@pikku/core/secret` and will not typecheck against this core
+  until it is rebuilt and republished.
+
+- 457cb25: Add `definePersonas()`: the people a project's scenarios and virtual users run
+  as, declared in code.
+
+  There used to be three names for two-and-a-bit things — an _actor_ in
+  `scenarios.actors`, a _persona_ in `scenarios.personas`, and a _virtual user_
+  declared separately against an actor. In practice almost every actor was its own
+  kind, so the second set carried no information and the third was a third place
+  for a name to drift. There is now one declaration:
+
+  ```ts
+  definePersonas({
+    shopper: {
+      name: 'Sam Shopper',
+      jobTitle: 'Shopper',
+      personality: 'Buys in a hurry and leaves tabs open',
+      roles: ['customer'],
+      disposition: 'careless',
+      goals: ['Buy something without reading anything'],
+      account: {},
+    },
+  })
+  ```
+
+  A persona is a person: what they are like, what they want, the roles they hold,
+  and **one** account they sign in with — `account: {}` plus `linkedAccounts` for
+  the rare case of more, modelled on how better-auth does linking. A persona with a
+  `disposition` is a virtual user; `runnable: false` marks someone who only ever
+  exists to be acted upon — banned, shared with, reset — and is never handed a
+  session.
+
+  **A persona names roles, never scopes.** Scopes come from `defineSystemRole()`
+  expansion, so the build fails if a persona names a role nobody declared, and
+  fails again if a role confers a scope no `defineScope` declares. Running one only
+  ever has to check that its roles are still valid.
+
+  **Addresses are computed, never declared.** `personaEmail(id, domain, runId)`
+  derives `<id>[+runId]@<domain>` from `scenarios.emailDomain`, so a seed, a
+  scenario run and a virtual-user run cannot disagree about who they are signing in
+  as. `scenarios.actors` and `scenarios.personas` are gone from
+  `pikku.config.json` — only `emailDomain` remains.
+
+  `actor` survives in exactly one place: the name of a **slot in a scenario step**,
+  which is the role a persona is cast in for that step. `pikkuVirtualUser()`,
+  `kind`, `grants` and the `actor` field are removed; the `actors` service is now
+  `personas`, and the CLI's `virtual-user` commands are now `pikku persona list` /
+  `pikku persona run`. `budget` and `allowApprovalRequired` moved to run flags —
+  how much you will spend today is not a fact about a person.
+
+  `@pikku/cucumber` drops its `Actor` class and `ActorDispatchContext`: a
+  hand-rolled cookie jar that a persona's own typed session replaces outright.
+
+- f7567ad: Add `defineSystemRole()`: roles that ship with the product, declared in code.
+
+  A system role is to a console-composed role what an AWS managed policy is to a
+  customer-managed one — the console may show and grant it, but not rename,
+  re-scope or delete it. The CLI extracts declarations by AST and generates a
+  `SystemRoleName` union, so naming a role that does not exist fails the build,
+  and a role granting a scope no `defineScope` declares fails it too.
+
+  Removal is additive on the same terms as `defineScope`: deleting a declaration
+  leaves an inert row rather than revoking everyone's grant mid-deploy.
+
+  `ScopeService` gains `syncSystemRoles`, `findStaleSystemRoles` and
+  `pruneSystemRoles`; `Role` gains `system` and `declared`. Implementations
+  enforce immutability through the shared `assertRoleIsMutable` /
+  `assertRoleNameAvailable` guards rather than each inventing the rule.
+
+- ba6cc08: Security hardening: removed the gopass secret service and stopped MCP internal errors leaking stack traces.
+
+  **Breaking:** `GopassSecretService` and the `@pikku/core/services/gopass-secrets` subpath export are gone. The service shelled out to the `gopass` binary and its key validation accepted `../`, so a caller-supplied key could traverse out of the configured prefix namespace and read secrets outside it. Rather than harden a shell-out that few projects used, the service is removed. Anyone importing it should implement `SecretService` against their own secret backend. Pre-0.13 breaking changes still ship as a patch.
+
+  MCP internal errors (JSON-RPC `-32603`) previously always attached `data: { message, stack }`, handing any MCP client an internal stack trace. That payload is now gated on `exposeErrors`, which defaults to `!isProduction()` — the same convention `handleHTTPError` already uses. In production a client receives a bare `Internal error` with no `message` and no `stack`; `RunMCPEndpointParams` accepts an explicit `exposeErrors` to override the default.
+
+- a2e21e5: Keep the persona runtime off the production barrels
+
+  `@pikku/core/services` exported `HttpPersona`, `createHttpPersonas` and
+  `readScenarioHttpResponse` as values, and `@pikku/core/workflow` exported
+  `readScenarioHttpResponse` and `postScenarioJson`. Both are barrels a production
+  server imports, and `http-personas` reaches the actor-flow conversation runner
+  and through it the agent runner — so signing-in-as-a-persona machinery sat in the
+  module graph of every app that imported services.
+
+  Tree-shaking only removes that if you bundle. An unbundled Node or Lambda deploy
+  loads whatever the graph names, which is the case this matters in.
+
+  The values now come from `@pikku/core/persona`, which is where the rest of the
+  persona API already lives. **Types stay exactly where they were** — `import type`
+  erases, so it costs a bundle nothing, and moving them would put core in a cycle
+  with the code that describes its own function types.
+
+  `serialize-personas` generates the new import, so a regenerated
+  `pikku-personas.gen.ts` picks it up with no edit. Anything importing these four
+  values from `@pikku/core/services` or `@pikku/core/workflow` changes the
+  specifier to `@pikku/core/persona`; the names and signatures are unchanged.
+
+  A test walks each barrel's value-import graph and fails if scenario runtime
+  reappears, so this cannot regress quietly.
+
+- 457cb25: Let a persona do a real job in production, and say where it may act.
+
+  A persona was only ever a test subject: something you pointed at a stage to find
+  out what the product does wrong. But the same declaration — a name, a job, the
+  roles it holds and what it is trying to get done — describes a teammate doing
+  the work for real, and nothing about the engine cared which one it was.
+
+  Four changes make that difference explicit and enforced.
+
+  **`environments` moves to the top level of `pikku.config.json`**, out from under
+  `scenarios`. It was never a scenario's anything: `persona run` targets one, and
+  now so does `persona sync`. An environment may be flagged `production: true` —
+  a flag rather than a reserved name, because projects call it `prod`, `live` or
+  `eu-prod`, and more than one environment can be production.
+
+  **A persona may name its `environments`.** Omitting them means every configured
+  environment _except_ the production ones, so nothing reaches production by being
+  forgotten. Naming a production environment requires `disposition: 'accountable'`.
+  The rule is checked twice, on purpose: the inspector refuses to generate a
+  declaration that breaks it, and sign-in re-checks against the environment
+  actually resolved — the build check trusts the file, and the run check does not
+  trust which artifact got deployed. An unresolved environment fails closed.
+
+  **`disposition: 'accountable'`** is that production disposition. It sits opposite
+  `adversarial` on the intent axis rather than the care axis: what it changes stays
+  changed, every call is recorded against its name, and it stops to ask rather than
+  acting and reporting afterwards. Alongside it, **agents now appear in a persona's
+  computed catalogue**, gated by the same scopes as the RPCs — an agent is reached
+  rather than declared, so a persona finds the specialists its roles unlock and
+  chooses between calling the API itself and handing the work over. That also fixes
+  a latent gap: `talkTo` was wired at the target but never advertised in the
+  instructions, so it was never used.
+
+  **`pikku persona sync <environment>`** provisions them: it creates each account
+  and applies the roles it declares, additively, and never revokes. Seeding is test
+  data and `db seed` does not run in production; a teammate doing a real job still
+  needs an account and its grants. It needs both halves of an environment — its API
+  to sign the person in, its database to write the grants — and `--dry-run` reports
+  who would be provisioned, with what, and why anyone was skipped.
+
+  In the console, a virtual user now says where it may act — the environments it
+  named, or the rule when it named none — and its dossier carries the `sync`
+  command alongside the `run` one, because the account is not a by-product of a
+  run. `accountable` reads as a disposition like the rest.
+
+- 86a50b9: scenario: replace `browser: true` + `func` with per-surface bindings on `pikkuScenarioStep`
+
+  A step now declares one implementation per surface it can be driven through:
+
+  ```ts
+  export const buysTheItem = pikkuScenarioStep<{ sku: string }, { orderId: string }>({
+    name: 'buysTheItem',
+    description: 'buys the item',
+    browser: async (services, data, { browser }) => { ... },
+    default: async (services, data, { rpc }) => { ... },
+  })
+  ```
+
+  `pikku scenario run --run browser|cli|default` picks which surface the run drives,
+  and the two phases resolve bindings differently:
+  - **Actions** (`given` / `when` / `step`) run exactly one binding — the run
+    surface if it has one, otherwise `default`. A step with neither now fails with
+    `ScenarioNoSurfaceBinding` instead of silently running server-side.
+  - **Assertions** (`then`) are witnesses, not alternatives: every declared binding
+    runs and they must agree. Two surfaces reporting different things fails the run
+    with `ScenarioWitnessDisagreement` rather than reporting a pass. An assertion
+    with no witness the run can execute at all fails with `ScenarioNoWitness` —
+    without it the step returns `undefined` and renders as a tick, reporting a pass
+    for something nobody checked.
+
+  A scenario written as a step ladder that never calls `then` is now a **PKU680**
+  critical. It proves only that nothing threw, so an assertion-free ladder of
+  browser-bound actions would score perfect coverage while checking nothing.
+
+  The report gains a surface-coverage line — `n/m steps ran on browser`, counted
+  over every step, so an action that fell back to the server lowers the ratio
+  rather than needing a footnote. That also makes surfaces comparable over one
+  denominator: a scenario is `4/4` on a default run and `3/4` on a browser one.
+  Assertions that fell back are named separately and gate `--strict`, since a
+  sentence claiming the actor saw something nobody looked at is a different problem
+  from an action taking a shortcut.
+
+  **Breaking:** `browser: true` and the third `B extends boolean` type argument are
+  gone. Rename `func` to `default` (or to `browser` where the step drove a browser)
+  and drop the type argument.
+
+- 0e0f6eb: Add virtual users: LLM-driven synthetic users that work a real stage in
+  character.
+
+  A scenario proves a path somebody thought of. A virtual user works the same
+  ground without the script — it signs in as a declared persona over the app's own
+  auth, is handed the scenarios' BDD prose and the schema of every endpoint it may
+  reach, and decides for itself what to do. It asserts nothing; a run produces
+  findings, and their absence only ever means "not this time, not with this seed".
+
+  There is nothing extra to declare. A persona with a `disposition` is a virtual
+  user, and running it is what makes it one — see the `definePersonas` changeset
+  for the declaration itself. Listing, describing or running one never loads the
+  app: the inspector reads the literal declaration, the CLI writes
+  `scopes/pikku-personas-meta.gen.json`, and `MetaService.getPersonasMeta()`
+  serves it.
+
+  **Dispositions are engine dials, not prose.** Each carries its own intent weights
+  (continue / suspend / resume / abandon), temperature, re-read and repeat rates,
+  and switches: `careless` puts things down and picks them up in the wrong order,
+  `newcomer` starts with no memory, `auditor` is never offered a mutation,
+  `adversarial` is shown the catalogue its roles do not cover — being offered a
+  call it should not be able to make is the test — while those roles stay live as
+  the oracle, so a success outside them is authorization drift rather than a pass.
+
+  **Nothing is retrieved against.** The whole reachable catalogue goes into the
+  instructions (~8k tokens on a 430-RPC project, cached for the run), because a
+  ranking function would make the user only as adventurous as the ranking and lose
+  exactly the endpoints worth stumbling into. Schema first: an endpoint must be
+  described before it may be called.
+
+  **No money in core.** The engine counts steps, calls, mutations and tokens; what
+  they cost is the app's to decide through `stop(tally)`.
+
+  CLI: `pikku persona list` and `pikku persona run <environment> [name]`, with
+  flags overriding a declaration for reproduction (`--seed`, `--steps`,
+  `--disposition`). Spending is a run flag too — `--steps`, `--mutations` and
+  `--duration` bound a run, because how much you will spend today is not a fact
+  about a person. Console: a Virtual Users screen beside Scenarios, built out of
+  core's own derivation functions so it shows a run's actual inputs rather than a
+  second implementation of them.
+
+  `dev-ai-runner` now ships its own `@pikku/ai-vercel` and
+  `@ai-sdk/openai-compatible` instead of requiring them from the project. Behind a
+  proxy one openai-compatible provider answers for every prefix, so there was never
+  a per-vendor package worth making somebody install; the project's copies still
+  win when it has them, and both load from the same place or neither does.
+
 ## 0.12.72
 
 ### Patch Changes