@sigrun/sigrun 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-29
+
+### Added
+- Parked-task visibility and recovery: pi-durable reports now reach logs,
+  metrics, alerts, and job status, and administrators can list and retry
+  parked tasks through the admin API.
+- Proxy identity links with case-insensitive matching, plus typed-username
+  normalization for `user add --proxy`, `link`, and `unlink`.
+- An optional chart `networkPolicy`, `OnboardingState.proxyIdentity.subject`,
+  the ProxyUnidentified screen, and the shared `./usernames` export.
+
+### Changed
+- Upgraded the Earendil runtime to pi-durable 1.4.0 (with chord and pi-ai
+  1.4.0), including durable schedule sleeps, retry backoffs that survive
+  restarts, and the crash-loop parked-task guard.
+- Extension shutdown now runs in parallel within a fixed budget, with the
+  chart's termination grace period matched to that budget.
+- The loader quarantines extensions whose declared Earendil peer range
+  excludes the host version instead of allowing an incompatible extension
+  to fail later at runtime.
+- `settings.compaction.modelOverrides` supports per-model compaction
+  settings while preserving environment-over-file precedence.
+- Proxy-only non-loopback boots refuse unvouched account creation, including
+  login and code paths, and mint no setup code there. Login derives from the
+  full email; boot sweeps orphaned proxy links, gates own-host peers, and
+  throttles proxy diagnostics.
+
+### Fixed
+- CLI empty-string identity values now mean "unset".
+
+### Breaking
+- When `SIGRUN_API_TOKEN` is set, `SIGRUN_API_TOKEN_USER` must be a valid
+  username key (the validation error includes a derivation suggestion). The
+  user value is validated only when the token is set.
+
+### Upgrade notes
+- **One-way storage migration:** the first 0.3.0 boot migrates the SQLite
+  durable schema to pi-durable 1.4.0's format. Before opening storage, boot
+  writes a crash-consistent snapshot beside the database named
+  `<storagePath>.pre-durable-schema-v<CURRENT>-<UTC stamp>.bak`. Snapshots
+  are never deleted automatically. If a needed snapshot cannot be written,
+  boot stops before migration. `SIGRUN_SKIP_MIGRATION_SNAPSHOT=1` is the
+  emergency opt-out for an operator with an independent backup.
+- **Rollback to 0.2.x (SQLite):** stop sigrun, restore the `.bak` over the
+  database file, remove the database's `-wal` and `-shm` sidecars, then
+  deploy 0.2.x. Anything committed after the upgrade is lost.
+- **JSONL storage:** there is no snapshot because its schema does not
+  change. A 0.2.x process nevertheless never resumes a task left `sleeping`
+  by 0.3.0, so rollback can strand that task.
+
+## [0.2.1] - 2026-10-28
+
+### Added
+- `GET /v1/meta` now reports the effective listener: `listener.host`,
+  `listener.port`, and `listener.families` — the address families the
+  live listener accepts, measured once at listen (the `::` wildcard
+  probes both loopbacks and reports exactly the families that connect;
+  a hostname bind reports the bound socket's family, never a concrete
+  peer address). Additive wire field: pre-upgrade servers omit
+  `listener`; clients consuming it must tolerate its absence.
+- `SIGRUN_LISTEN_HOST` is now honored as the environment equivalent of
+  the programmatic `serve({host})` option. One host value is resolved
+  at the serving boundary (`options.host` → `SIGRUN_LISTEN_HOST` → `::`)
+  and drives the bind AND both auth derivations — the previously split
+  defaults (the boot auth derivation's independent env read, and the
+  harness-side `0.0.0.0` fallback) are gone.
+- Proxy-auth rejections (401) now log one sanitized `warn` per rejected
+  request: the socket peer, the method, a short reason (`untrusted
+  proxy`, `missing or wrong shared secret`, `missing identity header`,
+  `untrusted identity source`), and the resolved route template — never
+  tokens, cookies, identity-header values, query strings, or the full
+  URL. Token-auth failures and successful proxy authentications stay
+  silent.
+- The normal core build now emits real `dist/blocks/**/*.d.ts`
+  declarations, including the `dist/blocks/index.d.ts` named by the
+  `@sigrun/sigrun/blocks` export. Pack/type-resolution coverage compiles
+  an external consumer against those declarations; extension consumers
+  no longer need an ambient block-module shim.
+
+### Fixed
+- Successful `PUT /v1/me/extensions/:slug/settings` writes now publish
+  through the same post-commit settings-change seam as section saves:
+  one per-user failure-fence clear, one observing-extension reconciliation,
+  and the extension slug plus changed body keys. Invalid, unknown, and
+  otherwise rejected writes publish nothing; repeated successful writes
+  retain the existing notification semantics.
+- `host.peekInteraction(conversationId, callId, context)`: a
+  non-consuming interaction inspection read beside
+  `snapshotInteraction`. It returns the same stored record projection
+  (secret values stay masked) but NEVER touches the one-shot raw-secret
+  delivery — safe to repeat for notifiers, outcome edits, and answer
+  correlation. `snapshotInteraction` remains the ONLY read that merges
+  and consumes an unread delivery, reserved for the interaction's
+  owning extension; its first-read/second-read semantics are unchanged.
+- `NotificationEvent` is now a discriminated union (shared base plus
+  `interaction.pending` / `job.failed` / `run.settled` variants), and
+  the `run.settled` variant carries a structured
+  `outcome: { status: "answered" } | { status: "unanswered"; reason: string }`
+  translated directly from the host event's existing `outcome`/`reason`
+  (no second answer read, no inferred status). The other variants do
+  not gain the field; exhaustive narrowing on `type` now typechecks.
+
+### Fixed (continued)
+- Restored per-user worker startup by placing the selected device paths
+  under read-only Landlock rules. Their ordinary I/O works, while
+  `/dev/shm` and writes outside workspace/home/tmp remain denied.
+- Preserved composer text and attachments when a slow conversation-meta
+  restore resolves after a local edit or clear. The interaction visual
+  drain now covers required secrets and multi-step forms, and the visual
+  e2e gate passes all 163 cases.
+
+### Changed
+- Settled-run notifications are truthful: an answered run keeps the
+  `"Reply ready"` title, while an unanswered run (model error, abort,
+  or a missing answer) is titled `"Run ended without a reply"` with the
+  settle reason appended to the body — a failed run no longer
+  masquerades as a ready reply. Recipient, dedup, and
+  `notifications.runSettled` gating are unchanged.
+
 ## [0.2.0] - 2026-10-27
 ### Added
 - Per-user extension surface (multi-user M2): lifecycle events carry the
@@ -58,11 +177,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   literal-content ruling.
 - Images (U7): an HMAC-signed proxy, a rebinding-safe fetcher, an LRU cache
   with `sharp` conversion, and CSP headers.
-- Core settings sections rebuilt on blocks (U4): one settings renderer for
-  webui and TUI, extension-declared sections, a `/v1/settings` sections
-  route, `pendingRestart` with an admin restart route, live/restart
-  metadata for every core key, label search, and
-  `settings.changed`/`onSettingsChanged`.
 
 ### Changed
 - Family versions move together to 0.2.0: `@sigrun/shared` 0.2.0
@@ -91,6 +205,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   distinguish Landlock denials from Yama or missing-capability conditions.
 
 ## [0.1.7] - 2026-10-24
+
+*Correction (2026-10-28): the original entry omitted substantial scope
+that shipped in this release — the U4 settings rebuild, the M3a
+account-link store and routes, and the accompanying `@sigrun/shared` /
+`@sigrun/tui` settings-surface work. Those entries are restored below;
+the Service-migration claim is also corrected (adding a secondary
+family while retaining the primary is an in-place patch, not a
+recreate).*
+
+### Added
+- Core settings sections rebuilt on blocks (U4): one settings renderer
+  for webui and TUI, extension-declared sections, a `/v1/settings`
+  sections route, `pendingRestart` with an admin restart route,
+  live/restart metadata for every core key, label search, and
+  `settings.changed`/`onSettingsChanged`. The shared and TUI packages
+  carry the matching settings-surface and settings-form work (live
+  surface revs, default-on toggle handling, roster-driven tool
+  defaults, walk-based search).
+- Account links (multi-user M3a): the core account-link store plus
+  routes to list and remove an account's linked external identities.
+
 ### Fixed
 - The deploy entry binds the dual-stack wildcard (`::`) instead of the
   IPv4-only `0.0.0.0`. On a dual-stack pod whose Service is IPv6-only
@@ -107,8 +242,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - The chart's main Service is `PreferDualStack` over `[IPv6, IPv4]`,
   so it advertises both pod addresses regardless of the cluster's
-  default family. Converting an existing `SingleStack` Service is a
-  recreate (`spec.clusterIPs` is immutable).
+  default family. Adding a secondary family while retaining the
+  primary is an in-place patch (`spec.ipFamilies` gains the new
+  family); only changing the PRIMARY family requires recreation
+  (`spec.clusterIPs` is immutable). *Corrected 2026-10-28: the
+  original entry claimed every conversion is a recreate.*
 - `sigrun run` (workstation mode) still binds `127.0.0.1` only.
 
 ## [0.1.6] - 2026-10-24

package/README.md

@@ -1,11 +1,28 @@
 # Sigrun
 
-Sigrun is a durable personal-assistant harness built on
-[pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable):
-long-lived conversations over a SQLite store (surviving restarts, with
-resumable generation), an HTTP API plus web and terminal UIs, and an
-extension system that installs extra tools, providers, prompt sections,
-and capabilities at boot.
+Sigrun is a **durable, multi-user personal-assistant server** built on
+[pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable).
+One agent loop serves every surface — a web UI, a terminal UI, an HTTP
+API, and (via the gateway extension) chat channels — over long-lived
+conversations stored in SQLite.
+An extension model installs extra tools, providers, prompt sections,
+memory systems, and login providers at boot.
+
+**Why use it?** Conversations survive restarts and resume where they
+stopped; memory and integrations are extension-owned and individually
+replaceable; multi-user boundaries are explicit (real authentication plus
+a per-user execution jail); and it deploys as an npm package, a Docker
+compose reference, or a Helm chart. [`docs/why.md`](docs/why.md) is the
+longer rationale.
+
+**Status:** 0.x — useful and exercised, but extension and settings
+contracts can still evolve between minor releases. See
+[`SECURITY.md`](SECURITY.md) for the support, trust, and verification
+posture, and [`CONTRIBUTING.md`](CONTRIBUTING.md) to build and test.
+
+**Try it:** `npm i -g @sigrun/sigrun && sigrun run` — or jump to
+[Install](#install) and [Quickstart](#quickstart) for the model/credential
+setup every install needs.
 
 - **Durable** — conversations, submissions, and schedules live in one
   SQLite database (`SIGRUN_STORAGE_PATH`); a restart resumes where it
@@ -156,7 +173,9 @@ still override it per field.
 | `OPENAI_API_KEY` | string | — | `auth.json` (see below) | Credential for the env-driven OpenAI-compatible provider; the `auth.json` fallback after file entries. |
 | `OPENAI_BASE_URL` | URL | OpenAI | `defaultProvider.baseUrl` | Endpoint for the env-driven provider (any compatible host). |
 | `SIGRUN_PORT` | positive int | `3000` | `server.port` | HTTP listen port. |
+| `SIGRUN_LISTEN_HOST` | host | `::` | — | HTTP listen host — the environment equivalent of the programmatic `serve({host})` option (the option wins when both are set). One resolved value drives the bind AND the auth defaults: a loopback bind derives the no-auth workstation posture, any other bind derives `token` auth. `GET /v1/meta` reports the effective listener (`listener.host`/`port`/`families`). |
 | `SIGRUN_STORAGE_PATH` | path | `<dataDir>/sigrun.db` | `server.storagePath` | SQLite database location. Relative values resolve against the data root (absolute values verbatim; the cwd-relative `data/sigrun.db` default is retired). |
+| `SIGRUN_SKIP_MIGRATION_SNAPSHOT` | `1` | *(unset)* | — | Skip the automatic pre-migration SQLite snapshot when set to `1`. Emergency escape hatch for an operator who already has an independent backup; without it, a needed snapshot failure stops boot before the one-way durable schema migration. |
 | `SIGRUN_WORKSPACE_PATH` | path | `<dataDir>/workspace` | `server.workspacePath` | Root of the static local workspace every conversation's tools run against. The default rides the data root (chart/compose deploys set the path explicitly); it is never persisted on first boot. |
 | `SIGRUN_DATA_DIR` | path | `$XDG_DATA_HOME/sigrun` or `~/.local/share/sigrun` | `server.dataDir` | Data root (the DB default and extension data dirs). Env/file values win verbatim. |
 | `SIGRUN_CACHE_DIR` | path | `$XDG_CACHE_HOME/sigrun` or `~/.cache/sigrun` | `server.cacheDir` | Cache root (regenerable; never ensured at boot). Env/file values win verbatim. |
@@ -165,6 +184,7 @@ still override it per field.
 | — | — | *(none)* | `gitDir` is always `<configDir>/git` | Git extension checkouts clone here (pi layout). Not env-configurable. |
 | `SIGRUN_WEBUI_BUNDLE` | path | `webui/dist` | `server.webuiBundle` | Web UI bundle directory; explicit-but-missing = boot error, default-missing = API-only. |
 | `SIGRUN_CONFIG_DIR` | path | `~/.config/sigrun` | *env-only* | The settings file's own directory. |
+| `SIGRUN_API_TOKEN_USER` | username key | `sigrun` | *env-only* | User for `SIGRUN_API_TOKEN`. Must already be a valid username key (`^[a-z0-9][a-z0-9._-]*$`, at most 128 characters); invalid values fail boot with a derivation suggestion. Validated only when `SIGRUN_API_TOKEN` is non-empty. |
 | `SIGRUN_COMPACTION_ENABLED` | `true`/`false` | `true` | `server.compaction.enabled` | Context compaction on/off. |
 | `SIGRUN_COMPACTION_RESERVE_TOKENS` | positive int | `16384` | `server.compaction.reserveTokens` | Headroom reserved for the model's reply. |
 | `SIGRUN_COMPACTION_KEEP_RECENT_TOKENS` | positive int | `20000` | `server.compaction.keepRecentTokens` | Recent context retained verbatim through a compaction. |
@@ -174,6 +194,32 @@ still override it per field.
 | `SIGRUN_BACKUP_S3_PREFIX` | string | *(unset)* | `server.backup.s3.prefix` | Key prefix within the bucket. |
 | `SIGRUN_BACKUP_S3_ENDPOINT` | URL | AWS default | `server.backup.s3.endpoint` | Custom S3 endpoint (S3-compatible stores). |
 
+Per-model overrides: `server.compaction.modelOverrides` is a map keyed by
+the exact `provider/modelId` string pi-durable composes — note that a
+chain-shaped model id doubles the prefix. Use it when a small-window model
+must sit alongside the large-window default policy (lower
+`reserveTokens`/`keepRecentTokens`/`backgroundTokens`, or `enabled: false`
+for a model that must never compact):
+
+```jsonc
+"server": {
+  "compaction": {
+    "reserveTokens": 16384,
+    "modelOverrides": {
+      // Synthetic example: provider "bifrost", model id "bifrost/small-chat".
+      "bifrost/bifrost/small-chat": { "reserveTokens": 4096, "keepRecentTokens": 6000 }
+    }
+  }
+}
+```
+
+Each entry is a partial policy (the same fields and minimums as the parent
+block); unset fields inherit the global policy. Boot-time lifetime like the
+rest of compaction, and there is no env spelling. After the boot catalog
+refresh an override key that matches no known model logs one warning
+(`compaction override "<key>" matches no known model`) — never an error,
+since catalogs move.
+
 ### settings.json schema
 
 ```jsonc
@@ -200,7 +246,10 @@ still override it per field.
       "enabled": true,
       "reserveTokens": 16384,        // positive integer
       "keepRecentTokens": 20000,     // positive integer
-      "backgroundTokens": 32768      // non-negative integer (0 = off)
+      "backgroundTokens": 32768,     // non-negative integer (0 = off)
+      "modelOverrides": {            // per-model partial policies, keyed by exact provider/modelId
+        "bifrost/bifrost/small-chat": { "reserveTokens": 4096 }
+      }
     },
     "backup": { // target: { "path": "/backups" } XOR { "s3": { "bucket": "...", "prefix": "...", "endpoint": "..." } }
       "staleAfterHours": 36            // positive number: health.backup degrades past this marker age
@@ -289,6 +338,64 @@ configurable) when the request comes from a peer inside
 proxy and nothing else: every peer in `trustedProxies` can forge any
 identity, including an admin.
 
+**Which address to list.** `trustedProxies` must list the address the
+proxy **connects from**, as the pod sees it — not the proxy's own
+Service or DNS name. The same list also gates trust in
+`X-Forwarded-Host` (the Origin check) and `X-Forwarded-Proto` (the
+Secure-cookie decision): a peer outside the list cannot steer either.
+On a dual-stack cluster the Service may be reached over either family
+(the Service can be IPv6-first while the proxy still connects over
+IPv4), so list every address the proxy actually sources from.
+
+**Cilium Gateway API / Ingress.** The connect-from address is the
+per-node **Cilium ingress IP**, allocated from that node's pod CIDR —
+enumerate them with:
+
+```sh
+kubectl get ciliumnodes -o jsonpath='{..spec.ingress}'
+```
+
+Listing those addresses exactly is the tightest posture. Trusting the
+whole pod CIDR (e.g. `10.42.0.0/16`, `fd00:42::/64`) is acceptable
+**only together with a policy admitting the `ingress` entity** — the
+chart's `networkPolicy.enabled` option installs that
+CiliumNetworkPolicy, whose default also admits `host` for kubelet
+probes. Without it, any pod in the CIDR can forge
+identity headers directly to the Service. Note that the `ingress`
+entity covers **every Cilium gateway in the cluster**, so every route
+to sigrun must pass through forward auth; a gateway route that skips
+it is an open impersonation path.
+
+**Forward-auth header hygiene.** Forward auth must return **every
+identity header sigrun reads** on every authenticated response, and
+its upstream-header mode must **override, not append** — Envoy's
+`allowed_upstream_headers`, not `allowed_upstream_headers_to_append`.
+With append semantics a client can supply the headers forward auth
+omits and sigrun will read the client's copies.
+
+**Own-host peers (C5).** A trusted **range** never vouches for
+sigrun's own addresses — loopback or any local interface address —
+without the shared secret, because every local process shares those
+source addresses. An **exactly listed** local address (a bare address,
+or a `/32` / `/128` entry) does vouch, as an explicit operator
+decision, and boot logs a warning for each such entry when no shared
+secret is configured.
+
+**Rejection diagnostics.** Each rejection logs one sanitized line
+(subject to the throttle below) naming the socket peer, the method, a
+short reason, and the route, when known — never tokens, cookies, or
+identity-header values. The throttle emits one line per reason per 60 s,
+with `(N suppressed)` on the next line for that reason. The reasons:
+
+| Reason | Meaning |
+|---|---|
+| `untrusted proxy` | The socket peer is outside `trustedProxies`. |
+| `own-host peer without shared secret` | The peer is a local address trusted only through a range, and no shared secret is configured — see C5 above. |
+| `missing or wrong shared secret (<header> header)` | The named secret header was absent or did not match `SIGRUN_PROXY_SECRET`. |
+| `missing identity header (<header>)` | The proxy vouched but sent no user header — forward auth is not returning every identity header. |
+| `unusable identity claim` | The vouched username cannot be a directory user (403 `invalid_username`). |
+| `untrusted identity source` | The user does not exist and `autoProvision` is off (403 `user_not_provisioned`). |
+
 **Stored groups and group-derived admin.** `server.auth.adminGroups`
 lists groups (Authelia's `Remote-Groups`, for example) whose members act as
 admins. Core stores groups per authenticating source: `proxy` for validated
@@ -311,6 +418,106 @@ until then. Token and session requests only read the stored record; they
 never accept groups from the request. People-scoped conversation shares may
 also name groups, matched against the same stored groups.
 
+### Usernames
+
+Every external identity — proxy header, OIDC subject, invite claim,
+CLI argument — resolves to one **directory user key**. The key is the
+stable identifier: it names the user's storage directory
+(`<dataDir>/users/<user>`), their config directories, their per-user
+extension stores, and it appears in tool registrations as
+`<slug>@<user>`, split at the **first `@`**. The key pattern is
+therefore a safety rule, not a style choice:
+
+- lowercase letters, digits, `.`, `_`, `-` only, and no `/` against
+  traversal (case-insensitive filesystems would otherwise let `Alice`
+  and `alice` collide on one directory);
+- must start with a letter or digit (no leading `.` against hidden
+  paths or `..` keys);
+- no `@` — it is the tool-registration delimiter;
+- at most 128 characters, bounding key length for storage and tool
+  names.
+
+`deriveUsername(input)` maps any input onto that pattern: Unicode NFKD
+and strip combining marks, lowercase, `@` → `_`, every other disallowed
+character → `-` (no collapsing), strip leading non-alphanumerics,
+truncate to 128. Empty result → no usable key: proxy authentication
+refuses with 403 `invalid_username`, typed forms with 400, and login
+derivation falls back to the literal key `user`. The normative vectors:
+
+| Input | Key |
+|---|---|
+| `mikemacleod` | `mikemacleod` |
+| `Mike` | `mike` |
+| `mike@example.ca` | `mike_example.ca` |
+| `mike@example.com` | `mike_example.com` |
+| `Mike.Smith@Example.COM` | `mike.smith_example.com` |
+| `mike+test@example.com` | `mike-test_example.com` |
+| `José García` | `jose-garcia` |
+| `DOMAIN\mike` | `domain-mike` |
+| `Alice Smith` | `alice-smith` |
+| `.hidden` | `hidden` |
+| `mike.` | `mike.` (valid key, unchanged) |
+| `` (empty) | `undefined` (login: `user`) |
+| `@@@` | `undefined` (login: `user`) |
+
+Derivation is idempotent and every valid key is a fixed point. On the
+proxy path, a folded subject that is itself a valid key adopts the
+existing user with that key; a derived-key collision under login
+auto-provisioning takes the next free suffix instead.
+
+**Proxy uniqueness assumption (deployment requirement).** Proxy
+identity matching is case-insensitive: the proxy's usernames are
+assumed unique case-insensitively, so `Alice` and `alice` are the same
+person. Authelia/LDAP satisfy this. On a proxy where they are distinct
+accounts, `Alice` would resolve to `alice`'s account — including admin
+rights. Verify your identity source satisfies this before enabling the
+proxy method.
+
+**Derived vs typed collisions.** When a derived key is already taken
+(proxy auto-provisioning, login auto-provisioning), the next free
+suffix is chosen automatically: `alice`, then `alice-2`, `alice-3`,
+…. Typed names — `sigrun user add`, the invite claim form, the
+onboarding claim form — **refuse** with `username_taken` instead: an
+admin choosing a name never gets silently suffixed.
+
+**Login rule.** A new login user with no username claim derives from
+the **full email** (`mike@example.com` → `mike_example.com`), never
+just the local part. Existing linked users are unchanged — links are
+matched by exact subject, not by re-deriving the key.
+
+**Recipes.** Pre-provision a proxy user (and optionally grant admin):
+
+```sh
+sigrun user add alice --proxy Alice --admin
+```
+
+Link an additional proxy identity to an existing user:
+
+```sh
+sigrun user link alice --proxy alice.smith
+```
+
+**Crash-orphan repair.** If the process crashed between writing the
+user row and writing the proxy link, the user exists but cannot
+resolve. The boot sweep logs one line per orphan:
+
+```
+identity: proxy user "alice-2" has no proxy link; repair with: sigrun user link alice-2 --proxy <username>
+```
+
+Choose the repair that matches the intended owner:
+
+- If the orphaned `-2` user should own the identity, run the printed
+  `sigrun user link <key> --proxy <username>` command.
+- If the correct account already exists, delete the duplicate as an
+  admin with `DELETE /v1/users/alice-2?transferTo=alice`, where
+  `transferTo` names that existing account and receives its transferable
+  resources.
+
+These are alternatives, not a sequence: deleting a user also removes
+its links, so linking and then deleting the same `-2` user would undo
+the repair.
+
 ### External sign-in (OIDC and OAuth 2)
 
 The web sign-in screen lists configured external providers above the token
@@ -324,9 +531,9 @@ needed. Set `"builtinExtensions": {"oauth": false}` to disable it; like the
 other built-in toggles, this is restart-required. A configured extension
 whose package name is also `@sigrun/oauth` replaces the built-in. If the
 built-in cannot be resolved or loaded, it is quarantined without aborting
-boot. It remains separately installable through the normal `extensions`
-list (see [Extensions](#extensions)) for a deployment that wants it without
-the built-in. It is inert when its settings contain no valid providers.
+boot. Standalone installation outside the built-in is not a supported use
+case in 0.2; the package's type-only core dependency posture is accepted
+for this release. It is inert when its settings contain no valid providers.
 
 Create an OAuth/OIDC client at the identity service, with the redirect URI
 shown below. Configure providers in the extension's
@@ -462,6 +669,20 @@ admin) or by trusted-proxy auto-provision; admins can transfer or remove
 users (`PATCH`/`DELETE /v1/users/{user}` — deletion transfers their
 conversations).
 
+**Proxy-only onboarding.** On a proxy-only server bound beyond
+loopback, onboarding happens entirely **through the proxy**: the first
+claim and every later sign-in arrive as trusted proxy identities, no
+setup or invite codes apply (no setup code is minted, and an invite
+code cannot be redeemed without a vouch), and an unvouched
+account-creating request is refused with 403
+`proxy_identity_required`. A browser reaching sigrun without a trusted
+proxy identity sees a ProxyUnidentified screen instead of a token or
+setup-code form. As a deliberate, bounded exception,
+`/v1/auth/callback/:provider` still lets a login provider with
+`policy.autoProvision` create its own non-admin account on a proxy-only
+server, although the resulting session cannot authenticate because the
+token method is off.
+
 **Sharing.** Conversations are private to their owner by default. The
 owner can share one — household-wide or with named users and groups,
 `read` or `write` — through the web UI's ⋯ menu; `write`
@@ -556,8 +777,72 @@ identity-switch capabilities once (replace `<helper>` with its path):
 sudo setcap cap_setuid,cap_setgid+ep <helper>
 ```
 
-The helper's boot self-test verifies the switch. This mapping is unavailable
-in containers, whose entrypoint drops every capability.
+The helper's boot self-test verifies the switch. `SIGRUN_SANDBOX_HELPER`
+points sigrun at a helper binary at a non-default absolute path (it falls back
+to the installed location with one warning if the path does not exist), which is
+how a staged copy gets used.
+
+File capabilities only take effect when the capabilities they grant are
+already in the **caller's** bounding set: executing the capped helper needs
+`CAP_SETUID` and `CAP_SETGID` present in the process that launches it —
+`CAP_SETFCAP` alone only permits writing the xattr and is not enough. A root
+shell, or a host that runs sigrun as root and maps users to real OS accounts,
+normally satisfies this.
+
+This mapping is bare-metal only. The container entrypoint starts as the image's
+non-root `USER` and execs straight through (one uid for the whole container), so
+it holds no identity-switch capabilities to inherit — containers use the
+Landlock jail alone, which is where container multi-user isolation comes from.
+A root container start (`SIGRUN_UID=0`) does exist, but it is a mount-point
+ownership trampoline, not an `osUsers` enabler: it needs
+`CAP_CHOWN`/`CAP_SETUID`/`CAP_SETGID` for the chown-and-drop and still leaves
+you with a single container uid.
+
+#### If you insist on `osUsers` in a container — and why you shouldn't
+
+It is possible, and two of the three pieces need no image change. A capped
+helper can be staged at runtime on any writable path (a named volume, a
+`tmpfs`, a bind mount), and the caps come from the container's own flags:
+
+```yaml
+# the runtime half — no derived image required
+services:
+  sigrun:
+    user: "1000:1000"
+    cap_add: [SETUID, SETGID]   # bounding set for the helper's file caps
+    volumes:
+      - sigrun-data:/data
+      - helper:/opt/helper        # a writable path for the capped copy
+    # then, once per volume: copy the helper in, chmod 755, setcap
+    # cap_setuid,cap_setgid+ep under --cap-add SETFCAP, and point
+    # SIGRUN_SANDBOX_HELPER at it
+    security_opt:
+      - no-new-privileges:false   # REQUIRED — see below
+```
+
+The blocker is the third piece: **`osUser` maps to a login name**, resolved from
+`/etc/passwd`, so every user you want needs an account. The image ships exactly
+two non-root accounts (`node` and `nobody`). That is what forces either a
+derived image (`RUN useradd …` per user) or mounting a `passwd` file over
+`/etc/passwd` through a `subPath`, which is fragile and surprises tooling.
+
+And the default posture actively prevents it, three ways: `read_only: true`
+makes `setcap` on the image layer fail with "Read-only file system",
+`cap_drop: ALL` grants nothing, and `no-new-privileges: true` suppresses the
+file-capability gain on `execve` even when `SETUID`/`SETGID` are in the bounding
+set (the helper dies at its first privileged call). Enabling this therefore
+means adding capabilities **and** permitting privilege escalation — a
+deliberate threat-model relaxation, not a configuration tweak.
+
+The reason not to is structural rather than configurational: inside one
+container every `osUser` shares **one filesystem and one mount namespace**. You
+would gain per-process uids and Landlock's per-process confinement, but not the
+kernel-level user separation a host provides — because there is only one
+container boundary to separate. You would be paying a real security cost (an
+identity-switch capability held by the main process, privilege escalation
+permitted) for isolation the container boundary already substantially provides.
+Use the Landlock jail alone in containers; use `osUsers` on bare metal, where
+the accounts and the separation are real.
 
 ### Kernel integration runner controls
 
@@ -790,7 +1075,7 @@ a dashboard) are in
 
 ## Built-in extensions
 
-Four extensions are built into core — **codemode**, **MCP**, **tool
+Five extensions are built into core — **codemode**, **MCP**, **tool
 search**, **gateway**, and **OAuth login**. The first three mirror
 what pi 1.3.0 ships built-in; the gateway is sigrun's own channel-adapter
 engine; OAuth provides OIDC, GitHub, and Discord login providers. They
@@ -833,6 +1118,11 @@ default. They join the offered set when an enabled MCP server's
 The MCP servers themselves live in the MCP config file — the
 `@sigrun/ext-mcp` package's README documents its format, including each
 server's `exposure` and the `SIGRUN_MCP_CONFIG` override.
+**User-supplied MCP servers are remote-only in 0.2** (URL transport);
+a user-supplied stdio server fails loudly with a config error. Dynamic
+jailed per-user stdio services are a post-release feature — per-user
+services are declared statically by extensions (see
+docs/extending.md).
 
 ```jsonc
 {
@@ -988,6 +1278,34 @@ launcher) is not supervised either; there the callout says "Restart
 sigrun to apply" with no button. `GET /v1/meta` reports the posture
 (`supervised`).
 
+## Parked tasks
+
+A task cut off repeatedly without progress (a crash loop) is parked by
+pi-durable's restart limit: it shows `blocked` with reason
+`restart_limit` and does not run again until an administrator retries
+it. The `SigrunTaskParked` alert fires on this. Two admin-only
+endpoints inspect and recover parked tasks:
+
+- `GET /v1/admin/tasks?state=blocked` — lists blocked tasks with
+  `{id, kind, reason, conversationId, owner?, extension?}` per row
+  (owner is the conversation's session owner when it has one; extension
+  is the registered task definition's owner when known).
+- `POST /v1/admin/tasks/:id/retry` — re-runs a restart-parked task:
+  204 on success, 404 `unknown_task` for an unknown id, 409
+  `not_parked` for a task that isn't parked (including one blocked for
+  another reason, such as `missing_task`). A retried schedule job's
+  status returns to `waiting` as the task runs again.
+
+```sh
+# List blocked tasks (admin token).
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:3000/v1/admin/tasks?state=blocked"
+
+# Retry a parked task.
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  http://localhost:3000/v1/admin/tasks/7/retry
+```
+
 ## API sketch
 
 - `GET /v1/meta` — version, extensions, health, auth posture
@@ -997,6 +1315,8 @@ sigrun to apply" with no button. `GET /v1/meta` reports the posture
   differs from boot) and PATCH reports `{applied, pending}`.
 - `POST /v1/admin/restart` — graceful restart (admin, supervised
   deploys only; see Restarting).
+- `GET /v1/admin/tasks?state=blocked`, `POST /v1/admin/tasks/{id}/retry`
+  — parked-task inspection and recovery (admin; see Parked tasks).
 - `GET /v1/jobs`, `POST /v1/jobs`, `PATCH`/`DELETE /v1/jobs/{id}` —
   the jobs surface (see [Jobs](#jobs)); `POST /v1/jobs/{id}/run` fires
   now; `GET /v1/jobs/{id}/runs` and `GET /v1/jobs/{id}/revisions` are

package/dist/blocks/build-stamp.json

@@ -0,0 +1,13 @@
+{
+  "algorithm": "sha256",
+  "sources": {
+    "shared/src/blocks/index.ts": "ca37dbb56a4a1a05a40a0125a06d864b9a0671c70817c83a44dd0e3962999e30",
+    "src/blocks/builders.ts": "a0c9835aaeab871bc2548d4b8d4426849c60cdb0cb1b20142d3bbe11e8377005",
+    "src/blocks/images.ts": "2e1bd54546c9c1c5bf0cfe9b488aaffd7c37979ef84bae9789168275e63e202f",
+    "src/blocks/index.ts": "8878a2e2269572ebdecca2cf3b95fa67f144232d8a8fe4258b120948064d0520",
+    "src/blocks/limits.ts": "1e913f29167114e26bed6f8c1fd04c64b119ee1db3f4e9e2ae161ddf70578683",
+    "src/blocks/placements.ts": "fccda42669713d91dc78d025268ee127f926891cf383727c1e235a39b9f15c6f",
+    "src/blocks/schema.ts": "27dbc5cdf1152a16a75bfb1a70383f1a456999a41d393308c05079b41f087a83",
+    "src/blocks/validate.ts": "31b9fc78f569cceff229bd1f28bfc62e2f8da437684100e051104f059a1ca19f"
+  }
+}