@sigrun/sigrun 0.1.6 → 0.2.1

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
@@ -104,7 +121,7 @@ entrypoints:
 | Command | Behavior |
 |---|---|
 | `sigrun [--user <name>]` | Workstation mode: boot the harness + server **in-process** and launch the terminal UI against the loopback port — the server binds **loopback (`127.0.0.1`) only**, so the naive-identity API never answers the LAN. The agent dies with the TUI — when the TUI exits, server and harness shut down with it. |
-| `sigrun serve` | Headless: boot the API + web UI statics, no TUI. This is exactly the `npm start` / `src/index.ts` composition the Docker image and Helm chart run. Binds all interfaces (`0.0.0.0`) — the container default; workstation `sigrun` (run) binds loopback only. |
+| `sigrun serve` | Headless: boot the API + web UI statics, no TUI. This is exactly the `npm start` / `src/index.ts` composition the Docker image and Helm chart run. Binds all interfaces (`::`, the dual-stack wildcard — accepts IPv4 and IPv6; a v4-only `0.0.0.0` bind is unreachable on a dual-stack pod's IPv6 endpoint) — the container default; workstation `sigrun` (run) binds loopback only. |
 | `sigrun attach [--server <url>] [--user <name>]` | TUI only, against a harness it can reach — the remote-client mode (e.g. attaching to a cluster or tailnet deployment). |
 
 Resolution chains for `attach` (and for the workstation-mode user):
@@ -156,6 +173,7 @@ 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_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. |
@@ -265,8 +283,10 @@ list explicitly — explicit always wins, including `[]` on a non-
 loopback bind, which boots with a warning that any reachable client is
 trusted. The related env knobs: `SIGRUN_AUTH_TRUSTED_PROXIES` (CIDR
 csv), `SIGRUN_PROXY_SECRET` and `SIGRUN_API_TOKEN` (credentials —
-env-only, never in `settings.json`). Every auth setting is
-restart-required.
+env-only, never in `settings.json`). Every auth setting except
+`server.auth.sessionDays` is restart-required. `sessionDays` applies live to
+new sessions and has no core settings-section field; change it in the
+settings file or with `PATCH /v1/settings`.
 
 **Tokens.** API tokens are `sgr_`-prefixed secrets shown once at
 creation (the store keeps only SHA-256 digests) and are self-service:
@@ -275,7 +295,8 @@ an authenticated user lists and mints their own via
 admins may revoke anyone's). A token whose user was deleted is dead.
 A browser exchanges a token for a `sigrun_session` cookie at
 `POST /v1/auth/login` — invalid attempts are delayed and rate-limited —
-and `GET /v1/auth/whoami` returns the resolved principal.
+and `GET /v1/auth/whoami` returns the resolved principal. An IdP-signed-in
+user can mint their own API token for the TUI through the same token routes.
 
 **Proxy method (forward auth).** A trusted reverse proxy vouches for
 the caller through headers (Authelia's `Remote-*` defaults,
@@ -286,19 +307,166 @@ configurable) when the request comes from a peer inside
 proxy and nothing else: every peer in `trustedProxies` can forge any
 identity, including an admin.
 
-**Group-derived admin (persisted).** `server.auth.adminGroups` lists
-the proxy groups (Authelia's `Remote-Groups`) whose members act as
-admins. The request pipeline computes the grant per request and
-writes it through to the user's directory record as `groupAdmin`
-whenever it differs — so host-side surfaces with no request headers
-(chat commands, channel adapters) see effective admin (`admin ||
-groupAdmin`), while `/v1/users` keeps `admin` as the stored flag the
-users-admin UI toggles and shows `groupAdmin` alongside. The grant
-moves only on proxy-authenticated requests while `adminGroups` is
-non-empty: removal from the admin group takes effect at that user's
-next web request. Group-derived admin never counts toward the
-last-admin guard — demoting or deleting the only stored admin is
-still refused.
+**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
+forward-auth headers and `login:<slug>:<id>` for an external login. Effective
+admin is the stored `admin` flag OR any stored group in `adminGroups`, so
+web, chat, and host-side checks agree. `/v1/users` keeps `admin` as the
+stored flag the users-admin UI toggles; its `groupAdmin` compatibility field
+is derived, never persisted, and is retained for one release. Group-derived
+admin never counts toward the last-admin guard — demoting or deleting the
+only stored admin is still refused.
+
+Login-provider groups participate in `server.auth.adminGroups`, so configure
+only providers whose group claims are administrator-controlled. A linked
+account's groups come from the provider at each sign-in; removing admin
+therefore requires changing the provider's claim or removing the link/user.
+
+Groups refresh only at that user's next login or proxy request. This
+staleness is deliberate: a group removal at the IdP does not take effect
+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.
+
+### External sign-in (OIDC and OAuth 2)
+
+The web sign-in screen lists configured external providers above the token
+form when the effective auth methods include `token`; `/v1/auth/providers`
+returns an empty list on proxy-only deployments because their completed
+sign-ins could not authenticate the resulting session. The TUI continues to
+use tokens. Login providers come from extensions.
+The reference implementation is **`@sigrun/oauth`, the fourth built-in
+extension**. It is bundled and loads by default, so no `extensions` entry is
+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. 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
+`<config-dir>/settings/oauth.json`; an administrator can edit that JSON in
+Settings → Extensions → oauth. Set `server.publicUrl` (or
+`SIGRUN_PUBLIC_URL`) to sigrun's externally reachable origin so callback
+URLs are stable; otherwise core derives one from the request.
+
+For a generic OIDC service — Authelia, Authentik, and Keycloak are examples
+of products this form fits, not service-specific presets — configure its
+issuer and client:
+
+```json
+{
+  "providers": [
+    {
+      "id": "company",
+      "label": "Company SSO",
+      "kind": "oidc",
+      "issuer": "https://idp.example.invalid",
+      "clientId": "sigrun",
+      "scopes": "openid profile email",
+      "usernameClaim": "preferred_username",
+      "groupsClaim": "groups",
+      "autoProvision": false,
+      "allowedGroups": ["staff"],
+      "allowedDomains": ["example.invalid"]
+    }
+  ]
+}
+```
+
+The extension uses OIDC discovery, authorization code with PKCE S256 and a
+nonce, and validates the ID token. `scopes`, `usernameClaim`, and
+`groupsClaim` shown above are the defaults. For this example, register
+`https://sigrun.example.invalid/v1/auth/callback/login:oauth:company` as
+the redirect URI (the provider id is qualified, not merely `company`).
+Production identity endpoints must use HTTPS; plain HTTP is restricted to
+loopback development and tests.
+
+Every provider needs a client secret named `<id>.clientSecret` in the
+**oauth extension secret store** — `company.clientSecret` here. Set it in
+Settings → Extensions → oauth (write-only), or as an administrator with
+`PUT /v1/extensions/oauth/secrets/company.clientSecret` and body
+`{"value":"<client-secret>"}`. Never put a client secret in
+`settings/oauth.json`. Extension settings are read at boot; restart after
+changing them. Secrets are re-read per use, so a rotated client secret
+applies to the next login without a restart.
+
+The GitHub and Discord presets replace issuer/endpoint discovery with their
+protocol endpoints and user field mappings:
+
+```json
+{
+  "providers": [
+    {
+      "id": "github",
+      "label": "GitHub",
+      "kind": "oauth2",
+      "preset": "github",
+      "clientId": "acme-github-client-id"
+    },
+    {
+      "id": "discord",
+      "label": "Discord",
+      "kind": "oauth2",
+      "preset": "discord",
+      "clientId": "acme-discord-client-id"
+    }
+  ]
+}
+```
+
+**Both presets require `clientId` in settings and a client secret in the
+extension secret store** (`github.clientSecret` and
+`discord.clientSecret`). Their redirect URIs end in
+`/v1/auth/callback/login:oauth:github` and
+`/v1/auth/callback/login:oauth:discord` on the same sigrun origin. GitHub
+uses only a primary, verified email; Discord uses its verified flag.
+Neither preset supplies groups. A malformed provider entry is skipped with
+a warning naming it; other valid entries still load.
+
+For another OAuth 2 service, use `kind: "oauth2"` with explicit
+`authorizeUrl`, `tokenUrl`, and `userinfoUrl`, plus `fields` mapping a
+required `subject` and optional `username`, `name`, `email`,
+`emailVerified`, and `groups` dot-separated response paths. `clientId`, its
+`<id>.clientSecret` secret, and the same optional policy fields apply.
+
+**First login never auto-links by username or email.** An unlinked subject
+on an unclaimed server needs the one-shot setup code and becomes the first
+admin. On a claimed server, `autoProvision: false` (the default) requires an
+invite code; `true` creates a non-admin user, optionally restricted by
+`allowedGroups` and `allowedDomains`. **These filters apply only when
+creating a new user by auto-provisioning** — not to an already-linked
+account's logins or to invite-based provisioning. A linked account keeps
+working; remove its link (or the user) to remove access. A domain match
+additionally requires `emailVerified === true` from the provider. Core
+enforces the M1 admission prerequisites: adding a second user is refused
+without available execution isolation and real `token` and/or `proxy`
+authentication. An external IdP is not itself a trusted proxy.
+
+### Browser sessions and account links
+
+A successful external sign-in creates a `sigrun_session` cookie backed by a
+revocable session record in the token store. `server.auth.sessionDays`
+controls its lifetime (default **30 days**, live for newly created
+sessions). An expired session is rejected as unknown (401) and its record
+is pruned on the next token-store write. Logout revokes the current
+session; users can also see and revoke sessions in their token list.
+
+A session has the user's normal rights, including creating that user's own
+API tokens for the TUI. **Revoking a session does not revoke API tokens
+created with it**; revoke those separately. Core does not store provider
+access or refresh tokens.
+
+Settings → Account links is the self-service panel for external identities.
+Connect starts the provider flow with `?link=1` while signed in; the
+identity is linked to the caller instead of creating another sign-in.
+Users can remove their own links and administrators can manage others'
+links. One `(provider, subject)` pair belongs to one user: a link is never
+re-pointed to a different user. The holder or an administrator must remove
+a conflicting old link first.
 
 **Onboarding (the first claim).** An unclaimed server serves
 `GET /v1/onboarding` + `POST /v1/onboarding/claim`. On a loopback bind
@@ -313,11 +481,195 @@ users (`PATCH`/`DELETE /v1/users/{user}` — deletion transfers their
 conversations).
 
 **Sharing.** Conversations are private to their owner by default. The
-owner can share one — household-wide or with named users, `read` or
-`write` — through the web UI's ⋯ menu or the TUI's `/share`; `write`
+owner can share one — household-wide or with named users and groups,
+`read` or `write` — through the web UI's ⋯ menu; `write`
 lets a recipient submit, answer, and fork, but only the owner can
 re-share. Household sharing defaults to `read`.
 
+### Per-user extensions and deletion
+
+Extensions can offer personal tools, settings, credentials, and services
+instead of only server-wide resources. Each conversation selects its
+owner's per-user tools, and core also checks the committed owner every
+time one executes: selecting another user's entry does not permit its
+use. Per-user services run as that user in their own service jail,
+sibling to the agent's worker. A credential supplied to a service never
+belongs in the agent workspace. See
+[`docs/extending.md`](docs/extending.md#per-user-stores) for the extension
+contract and `/v1/me` self-service routes.
+
+A user's extension secrets live in
+`<configDir>/user-secrets/<user>.json`, mode `0600`, with one section
+per extension slug. Their settings live under
+`<configDir>/user-settings/<user>/`; extension data, state, and cache
+have separate per-user paths. Login, sessions, and account linking are
+documented in [External sign-in](#external-sign-in-oidc-and-oauth-2) and
+[Browser sessions and account links](#browser-sessions-and-account-links).
+
+`DELETE /v1/users/{user}?transferTo={recipient}` requires an admin and
+another directory user as recipient. Core transfers conversations and
+owned resources, then revokes the departing user's tokens and account
+links, stops their worker and services, and removes their per-user tool
+entries. Extensions then receive `userDeleted` while the old record and
+secrets remain readable, so they can revoke external provider
+credentials. Finally core removes the directory record, per-user secrets,
+user-settings directory, and per-user cache directories.
+
+**Credentials belong to a person and never transfer.** Data and state
+stay for the extension to retain, move, or delete according to its own
+rules; core does not make that choice.
+
+## Multi-user execution isolation
+
+`server.isolation.mode` (or `SIGRUN_ISOLATION`) controls the execution jail:
+
+| Mode | Behavior |
+|---|---|
+| `auto` (default) | Turns isolation on when the directory has more than one user. Once active, it stays active until restart. |
+| `always` | Confines every user, including a lone admin. |
+| `off` | No jail; permitted only with at most one directory user. |
+
+A second user is refused when isolation is unavailable or `off`, and a
+multi-user server never falls back to unconfined execution. Multi-user also
+requires real authentication (`token` and/or `proxy`).
+
+Isolation requires Linux with Landlock ABI 6 or newer (Linux 6.12+) and the
+`sigrun-sandbox` helper. Debian 12's default 6.1 kernel does not qualify;
+bookworm-backports' 6.12 kernel does. Ubuntu 24.04's GA 6.8 kernel does not
+qualify; its HWE 7.0 kernel does. Check the running host with
+`sigrun-sandbox probe`. The container needs no extra capabilities: uid 1000,
+no capabilities, and `RuntimeDefault` seccomp are sufficient.
+
+**When isolation is on**, a user's agent can reach only their workspace,
+their grants, their home and temp directories, and read-only system paths.
+It cannot read sigrun's files or environment, other users' files, or signal
+processes outside its jail.
+
+The kernel boundary suite has not run yet; CI is its first execution.
+Isolation must therefore not be treated as kernel-verified from the unit
+suite alone.
+
+**Not covered:** extensions run inside sigrun with full access, like any
+installed package — install only extensions you trust. One user's agent can
+still exhaust CPU, memory, or disk. Outbound network is not restricted.
+macOS and Windows hosts run single-user only.
+
+**Shared MCP servers** hand every permitted user's agent the admin's
+credential for that service.
+
+**File modes are not the boundary.** Workers that share sigrun's uid are
+confined by Landlock alone; `0700` directories are hygiene.
+
+**Single-user servers** run the agent with full host access.
+
+**Every peer in `trustedProxies` can forge any identity**; with isolation
+on, the shared secret is required for that reason. Configure
+`server.auth.proxy.secretHeader` and the env-only `SIGRUN_PROXY_SECRET`.
+
+For bare-metal OS-account mappings, enable `server.isolation.osUsers` and
+set a directory record's `osUser`. Grant the installed helper only the
+identity-switch capabilities once (replace `<helper>` with its path):
+
+```sh
+sudo setcap cap_setuid,cap_setgid+ep <helper>
+```
+
+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
+
+The opt-in suite is `SIGRUN_SANDBOX_IT=1 npx vitest run test/sandbox-it`.
+The CI `sandbox-it` job requires Landlock ABI 6 before running it. Its
+`/proc` and ptrace cases also perform the same operation as the same uid
+from outside any jail. The run log states, per case, either **Landlock
+discriminating** (the outside operation succeeds) or **Yama/host-policy
+satisfied, not Landlock-discriminating** (the outside operation is denied
+too). The latter still checks the denial but does not claim Landlock caused
+it. The abstract-socket case requires a successful outside-jail connection.
+The `pkill -x node` case needs unprivileged user/PID namespaces and `nsenter`:
+its outside control kills only PID 1 of a disposable namespace, never the
+test runner or another host Node process. If namespaces are unavailable,
+the suite skips with that named reason.
+
+The `osUser` success case and the in-jail uid-switch discrimination require
+a **privileged runner** with `CAP_SETFCAP` and
+`SIGRUN_SANDBOX_IT_PRIVILEGED=1`. The suite grants only
+`cap_setuid,cap_setgid+ep` to a temporary helper copy and verifies an
+unjailed uid/gid switch before testing the jailed denial. Without that
+successful outside control, both tests skip with a named reason; they never
+claim to prove confinement. An ordinary CI runner without file-capability
+permission therefore leaves these two cases unproven. The suite never runs
+`sudo` itself.
+
+The per-user-service process tests use a separate real-helper-launched
+service fixture. They cover the sibling-jail `/proc` and ptrace boundary;
+the per-user service API and lifecycle are documented above.
+
 ## Backup
 
 Set a target (`SIGRUN_BACKUP_PATH` or `SIGRUN_BACKUP_S3_BUCKET`+`SIGRUN_BACKUP_S3_PREFIX`,
@@ -509,18 +861,31 @@ wins, env bootstraps). The author-facing contract — the store taxonomy,
 the directory map, the slug rule, the `host.stores` handle, uninstall
 and backup posture — is [`docs/extending.md`](docs/extending.md).
 
+**Building surfaces:** an extension can also contribute UI — views,
+panels, settings sections, chat and interaction cards, ambient status —
+as **block trees** rendered identically by the webui and the TUI. The
+typed builders come from `@sigrun/sigrun/blocks`; the placement table,
+block catalog, action kinds, access and `sharedData`, uploads, images,
+and three complete worked examples (a lanes board, a settings section,
+a dashboard) are in
+[`docs/extending.md`](docs/extending.md#building-surfaces).
+
 ## Built-in extensions
 
-Three extensions are built into core — **codemode**, **MCP**, and
-**tool search** — mirroring what pi 1.3.0 ships built-in. They load by
-default on every boot, with no settings entry, and resolve from core's
-own `node_modules` (they are core dependencies, never installed into
-the packages dir — `extensions` has nothing to install for them, unless
-a same-named package is deliberately installed to replace one; see
-below).
+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
+load by default on every boot, with no settings entry, and resolve from
+core's own `node_modules` (they are core dependencies, never installed
+into the packages dir — `extensions` has nothing to install for them,
+unless a same-named package is deliberately installed to replace one;
+see below).
 A default install therefore has pi's tool surface without configuring
 anything. On `GET /v1/extensions` they report under the names
-`codemode`, `sigrun-mcp`, and `tool-search`.
+`codemode`, `sigrun-mcp`, `tool-search`, `gateway`, and `oauth`.
+Configure OAuth providers in `settings/oauth.json`; see the
+`@sigrun/oauth` package README for provider settings and secrets.
 
 **The tools stay off until needed** (pi parity): `codemode` and
 `tool_search` are not in a new conversation's model-offered tool set by
@@ -534,10 +899,10 @@ default. They join the offered set when an enabled MCP server's
   automatic decision (auto-enable only narrows the default set, never a
   named list).
 - **Turning one off** — `"builtinExtensions": {"codemode": false,
-  "mcp": false, "toolSearch": false}`. Each defaults to `true`; each is
-  restart-required. A disabled built-in disappears from
-  `GET /v1/extensions` entirely — no row, not even a skipped one — and
-  its config is then ignored.
+  "mcp": false, "toolSearch": false, "gateway": false, "oauth": false}`.
+  Each defaults to `true`; each is restart-required. A disabled built-in
+  disappears from `GET /v1/extensions` entirely — no row, not even a
+  skipped one — and its config is then ignored.
 - **Replacing one** — installing a package that resolves to the same
   package name as a built-in replaces it: the installed copy loads, the
   built-in is skipped, boot logs one warning naming both, and
@@ -550,16 +915,23 @@ 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
 {
   "extensions": [ // configured extensions install + load as above
     "@acme/sigrun-ext-example@^0.1.0"
   ],
-  "builtinExtensions": { // all three default to true; restart required
+  "builtinExtensions": { // all five default to true; restart required
     "codemode": true,
     "mcp": true,
-    "toolSearch": false
+    "toolSearch": false,
+    "gateway": true,
+    "oauth": true
   }
 }
 ```
@@ -680,11 +1052,38 @@ In the web UI the Jobs panel (the clock icon in the header) lists jobs
 with a “Run now” button; in the TUI `/jobs` prints the table (name,
 next run, last outcome).
 
+## Restarting
+
+Restart-only settings (the registry marks every key `live` or
+`restart` — a `restart` key's stored write applies at the next boot)
+surface as `pendingRestart` on `GET /v1/settings`, and the settings
+panel lists them with a Restart button for admins. The button calls:
+
+- `POST /v1/admin/restart` — admin-only; runs the normal graceful
+  shutdown (SSE drains, in-flight runs reach a durable boundary and
+  resume after the restart — pi-durable's recovery) and exits 0, so the
+  deployment's supervisor brings the process back. Both channels show
+  "Restarting…" and reconnect when `/readyz` answers.
+
+The route exists ONLY when the server knows something restarts it:
+`server.supervised` (env `SIGRUN_SUPERVISED=1`, strict true/false)
+must be true, else 409 `not_supervised`. The Helm chart and
+`docker/docker-compose.yaml` set the env (both restart the container);
+the Dockerfile deliberately does NOT — a bare `docker run` without a
+restart policy would exit and stay down. `sigrun run` (the local TUI
+launcher) is not supervised either; there the callout says "Restart
+sigrun to apply" with no button. `GET /v1/meta` reports the posture
+(`supervised`).
+
 ## API sketch
 
 - `GET /v1/meta` — version, extensions, health, auth posture
   (`methods`, `claimed`), capabilities.
-- `GET`/`PATCH /v1/settings` — the settings file (see above).
+- `GET`/`PATCH /v1/settings` — the settings file (see above);
+  responses carry `pendingRestart` (restart keys whose stored value
+  differs from boot) and PATCH reports `{applied, pending}`.
+- `POST /v1/admin/restart` — graceful restart (admin, supervised
+  deploys only; see Restarting).
 - `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
@@ -697,9 +1096,13 @@ next run, last outcome).
 - `GET /v1/onboarding`, `POST /v1/onboarding/claim` — the unclaimed
   state and the first-user claim.
 - `POST /v1/auth/login`, `POST /v1/auth/logout`, `GET /v1/auth/whoami` —
-  the browser session and the resolved principal.
+  token sign-in, logout, and the resolved principal.
+- `GET /v1/auth/providers`, `GET /v1/auth/login/{provider}`,
+  `GET`/`POST /v1/auth/callback/{provider}` — external sign-in.
 - `GET`/`POST /v1/auth/tokens`, `DELETE /v1/auth/tokens/{id}` —
-  self-service API tokens.
+  self-service API tokens and browser sessions.
+- `GET /v1/auth/accounts`, `DELETE /v1/auth/accounts` — self-service
+  external-account links (administrators may manage another user's).
 - `GET /v1/users`, `PATCH`/`DELETE /v1/users/{user}`,
   `POST /v1/users/invites` — the user directory and invite codes
   (admin-gated).

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"
+  }
+}