@sigrun/sigrun 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +127,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 +155,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 +192,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,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. |
@@ -324,9 +342,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
@@ -556,8 +574,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 +872,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 +915,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
 {

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

package/dist/blocks/builders.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The typed builders (spec §14.1): one function per block and field,
+ * plus `bind(pointer)` and `tree(root)`. Builders return plain JSON —
+ * there is no runtime besides them.
+ *
+ * Each builder takes its block's props object and returns the block
+ * with the `type` literal stamped in. The literal is spread LAST, so a
+ * stray `type` inside a JavaScript caller's props object can never
+ * override it; TypeScript callers cannot pass one at all (`Props` omits
+ * it). The tree BLOCK builder is exported as `treeBlock`, keeping the
+ * `tree` name for the version-stamping root wrapper.
+ *
+ * `tree(root)` stamps {@link BLOCK_SET_VERSION} from the shared wire
+ * package — the version the SERVER validates against, which is why
+ * extensions import these builders from `@sigrun/sigrun/blocks` (the
+ * host-linked copy, spec §14.1) instead of bundling their own.
+ */
+import type { Binding, Block, CalloutBlock, Card, ChartBlock, ChoiceField, CollectionBlock, ColumnsBlock, DateField, DaterangeField, DatetimeField, DetailsBlock, DiffBlock, FieldsBlock, FileField, FormBlock, GridBlock, ImageBlock, ListField, LogBlock, LongtextField, MarkdownBlock, MeterBlock, NumberField, PageBlock, SectionBlock, SecretField, StackBlock, StatBlock, TextField, ToggleField, Tree, TreeBlock } from "@sigrun/shared/blocks";
+/** One block/field's props: the wire shape minus the `type` literal. */
+type Props<T> = Omit<T, "type">;
+/** `bind("/cards")` → `{ $: "/cards" }` — a pointer into the surface's data model (§4.2). */
+export declare function bind(pointer: string): Binding;
+/** Wrap a root block with the server's block-set version (§4.4). */
+export declare function tree(root: Block): Tree;
+export declare function page(props: Props<PageBlock>): PageBlock;
+export declare function stack(props: Props<StackBlock>): StackBlock;
+export declare function columns(props: Props<ColumnsBlock>): ColumnsBlock;
+export declare function grid(props: Props<GridBlock>): GridBlock;
+export declare function section(props: Props<SectionBlock>): SectionBlock;
+export declare function markdown(props: Props<MarkdownBlock>): MarkdownBlock;
+export declare function fields(props: Props<FieldsBlock>): FieldsBlock;
+export declare function stat(props: Props<StatBlock>): StatBlock;
+export declare function callout(props: Props<CalloutBlock>): CalloutBlock;
+export declare function image(props: Props<ImageBlock>): ImageBlock;
+export declare function chart(props: Props<ChartBlock>): ChartBlock;
+export declare function meter(props: Props<MeterBlock>): MeterBlock;
+export declare function log(props: Props<LogBlock>): LogBlock;
+/** The tree BLOCK builder (§5.3) — `tree` is the root wrapper. */
+export declare function treeBlock(props: Props<TreeBlock>): TreeBlock;
+export declare function diff(props: Props<DiffBlock>): DiffBlock;
+export declare function details(props: Props<DetailsBlock>): DetailsBlock;
+export declare function collection(props: Props<CollectionBlock>): CollectionBlock;
+/** The collection item template (§5.5.1) — a slot bundle, not a block. */
+export declare function card(props: Card): Card;
+export declare function form(props: Props<FormBlock>): FormBlock;
+export declare function text(props: Props<TextField>): TextField;
+export declare function longtext(props: Props<LongtextField>): LongtextField;
+export declare function number(props: Props<NumberField>): NumberField;
+export declare function toggle(props: Props<ToggleField>): ToggleField;
+export declare function choice(props: Props<ChoiceField>): ChoiceField;
+export declare function date(props: Props<DateField>): DateField;
+export declare function datetime(props: Props<DatetimeField>): DatetimeField;
+export declare function daterange(props: Props<DaterangeField>): DaterangeField;
+export declare function secret(props: Props<SecretField>): SecretField;
+export declare function file(props: Props<FileField>): FileField;
+export declare function list(props: Props<ListField>): ListField;
+export {};

package/dist/blocks/images.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Image source rules (spec §11.1): `asset:` paths, `data:` URLs of the
+ * four accepted MIME types (capped at 192 KiB of base64 text), and
+ * `https:` URLs. SVG and AVIF are never accepted (script payload; no
+ * TUI decoder), and `http:` URLs are rejected. The proxy that rewrites
+ * and fetches is U7; this module only validates.
+ */
+/** A source that passed the §11.1 rules. */
+export type ImageSourceOk = {
+    ok: true;
+    kind: "asset" | "data" | "https";
+};
+/** A source the §11.1 rules reject. */
+export type ImageSourceErr = {
+    ok: false;
+    message: string;
+};
+/** The result of checking one `src` value. */
+export type ImageSourceResult = ImageSourceOk | ImageSourceErr;
+/**
+ * Check one image `src` against the §11.1 source rules. Bindings
+ * (`{$: …}` objects) are not checked here — their resolved string is,
+ * where the data model holds one (the data-size limit already covers
+ * the byte cost).
+ */
+export declare function checkImageSource(src: string): ImageSourceResult;

package/dist/blocks/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@sigrun/sigrun/blocks` — the extension authoring surface for the
+ * block set (spec §14.1): the typed builders, the wire types, and
+ * `validateTree` (§14.2) so an extension can unit-test its trees
+ * against the same validation the server runs.
+ *
+ * Extensions import this subpath, never a bundled copy: the package is
+ * a `peerDependency: "*"` (see docs/extending.md) and
+ * `@sigrun/sigrun` is a HOST RUNTIME MODULE (src/harness/packages.ts)
+ * — the host links its own running copy into every extension packages
+ * dir, so `tree(...)` always stamps the server's
+ * {@link BLOCK_SET_VERSION}. The `exports` map points here at
+ * `dist/blocks/index.js` (never `src/`), which is what the built
+ * server ships.
+ */
+export * from "./builders.js";
+export { validateTree, validateData, VALID_PLACEMENTS, PLACEMENT_RULES, LIMITS, } from "./validate.js";
+export type { PlacementLimits, PlacementRule, ValidateDataResult, ValidateErr, ValidateOk, ValidateOptions, ValidateResult, ValidationError, } from "./validate.js";
+export { BLOCK_SET_VERSION } from "@sigrun/shared/blocks";
+export type * from "@sigrun/shared/blocks";

package/dist/blocks/limits.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The per-placement size limits of spec §4.5: max blocks per tree, and
+ * max UTF-8 bytes of the serialized JSON for the tree and the data.
+ *
+ * Over a limit the server rejects with `413 surface_too_large` naming
+ * the limit; `validateTree`/`validateData` surface the same error
+ * strings. A collection counts as one block however many items it
+ * binds, and a `data:` image URL counts toward whichever of the tree or
+ * the data holds it (the sizes are measured over the serialized JSON,
+ * so both hold by construction).
+ */
+import type { Placement } from "@sigrun/shared/blocks";
+/** One row of the §4.5 limits table. */
+export interface PlacementLimits {
+    /** Max blocks in one tree (a collection counts as one). */
+    readonly blocks: number;
+    /** Max UTF-8 bytes of the serialized tree JSON. */
+    readonly treeBytes: number;
+    /** Max UTF-8 bytes of the serialized data JSON. */
+    readonly dataBytes: number;
+}
+/** Spec §4.5, one row per placement. */
+export declare const LIMITS: Readonly<Record<Placement, PlacementLimits>>;
+/** UTF-8 byte length of a value's serialized JSON (spec §4.5 sizing). */
+export declare function jsonBytes(value: unknown): number;

package/dist/blocks/placements.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The placement rules of spec §5.7, as data: which blocks, which
+ * collection displays and which form fields each placement allows,
+ * plus the root-block and `page.sidebar` constraints the table carries.
+ *
+ * `validateTree` walks a tree against these rules; the tests pin the
+ * table's literal cells so this data cannot drift from the spec.
+ */
+/** One row of the §5.7 table. */
+export interface PlacementRule {
+    /** Blocks allowed anywhere in the tree. */
+    readonly blocks: ReadonlySet<string>;
+    /** The only legal root block type, when the placement pins it. */
+    readonly rootBlock?: "page" | "form";
+    /** Whether a root `page` may carry `sidebar` (panel: no). */
+    readonly pageSidebar: boolean;
+    /** Collection displays allowed (`undefined`: all five). */
+    readonly collectionDisplays?: readonly string[];
+    /** Field types allowed in `form` blocks. */
+    readonly fields: ReadonlySet<string>;
+}
+/** The placement names, kept local so this module has no imports. */
+type PlacementName = "view" | "panel" | "settings" | "chat" | "interaction" | "ambient";
+/** Spec §5.7, one row per placement. */
+export declare const PLACEMENT_RULES: Readonly<Record<PlacementName, PlacementRule>>;
+export {};

package/dist/blocks/schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The typebox wire schemas for every block and field (spec §5/§6.1),
+ * each compiled once into its own `Validator` (spec §14.2 validation).
+ *
+ * Design notes:
+ * - Schemas are the wire contract, so they deliberately do NOT set
+ *   `additionalProperties: false`: unknown props pass through and
+ *   channels ignore them (the block-set version governs what exists).
+ * - `Tone`, `IconName` and `Format` are enums/patterns built from the
+ *   shared constants; an unknown icon name fails here, at the icon
+ *   prop's own path.
+ * - Bindable props are `Union([literal, Binding])` throughout; the
+ *   literal-ness of STRUCTURAL props (`display`, `groups`, `reorder`,
+ *   `mode`, field `name`s, `columns`, handler names) is enforced by the
+ *   second walk in `validate.ts`, not the schema, so the error can say
+ *   "must be a literal" instead of an anyOf mismatch.
+ * - Child slots (`children`, `sidebar`, `main`, `detail`,
+ *   `columns[].block`, `collection.item`, `form` children, a field's
+ *   `list.item`, `page.switcher`, a bulk action's `form.root`) are
+ *   deliberately loose here (any object): `validate.ts` walks the tree
+ *   and validates every child node against ITS compiled validator, so
+ *   one broken block is one precise error instead of a union mismatch
+ *   per sibling branch.
+ * - `Compile` (typebox/compile) builds each validator; its errors are
+ *   read from `instancePath`, relative to the node the validator ran
+ *   against.
+ */
+import type { Validator } from "typebox/compile";
+/** One compiled validator per block type, keyed by its `type` literal. */
+export declare const BLOCK_VALIDATORS: ReadonlyMap<string, Validator>;
+/** One compiled validator per field type, keyed by its `type` literal. */
+export declare const FIELD_VALIDATORS: ReadonlyMap<string, Validator>;
+/** The compiled validator for `Action` objects (spec §6.1). */
+export declare const ACTION_VALIDATOR: Validator;
+/** The compiled validator for action buttons (spec §6.1). */
+export declare const ACTION_BUTTON_VALIDATOR: Validator;
+/** The compiled validator for a collection's card template (spec §5.5.1). */
+export declare const CARD_VALIDATOR: Validator;

package/dist/blocks/validate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `validateTree` (spec §14.2): every error with its JSON path and a
+ * plain message.
+ *
+ * Two passes:
+ * 1. The compiled typebox validators (`schema.ts`) check each node's
+ *    shape: the walk descends the tree, finds every block, field,
+ *    action, button and card template, and runs the matching compiled
+ *    validator against it. Instance paths (relative to the node) join
+ *    the walk's path, so one broken block is one precise error
+ *    (`root.main[2].text`), never a union mismatch per sibling.
+ * 2. The same walk checks what schemas cannot express: placements
+ *    (§5.7), the literal-ness of structural props (§4.2), handler names
+ *    (§6.1), relative bindings outside item templates (§4.2), ids
+ *    (§4.1), `turn` outside chat (§6.2), `open` schemes (§6.1), image
+ *    sources (§11.1), limits (§4.5), and the ambient one-line rule
+ *    (§9.2).
+ */
+import { type Placement, type Tree } from "@sigrun/shared/blocks";
+export { PLACEMENT_RULES } from "./placements.js";
+export { LIMITS } from "./limits.js";
+export type { PlacementRule } from "./placements.js";
+export type { PlacementLimits } from "./limits.js";
+/** The placements the block set defines (spec §3). */
+export declare const VALID_PLACEMENTS: readonly Placement[];
+/** One validation error: where and what (spec §14.2). */
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+/** Options for `validateTree`. */
+export interface ValidateOptions {
+    placement: Placement;
+    /**
+     * The surface's `actions` map keys (spec §6.1); when given, every
+     * handler-name prop must be in it. When omitted (chat), handler
+     * names are free labels.
+     */
+    handlers?: ReadonlySet<string>;
+    /** The server's block-set version; a mismatched tree is rejected (§4.4). */
+    serverV?: number;
+    /** For ambient trees: which `place` renders this body (§9.2 one-line rule). */
+    ambientPlace?: "status" | "footer" | "panel";
+}
+/** The ok result of `validateTree`: the tree, narrowed to the wire type. */
+export interface ValidateOk {
+    ok: true;
+    tree: Tree;
+}
+/** The failure result: every error found, each with its path. */
+export interface ValidateErr {
+    ok: false;
+    errors: ValidationError[];
+}
+/** `validateTree`'s result. */
+export type ValidateResult = ValidateOk | ValidateErr;
+/** The result of `validateData`. */
+export type ValidateDataResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+/**
+ * Validate a block tree against a placement (spec §14.2). Returns every
+ * error with its JSON path; on success, the narrowed tree.
+ */
+export declare function validateTree(tree: unknown, opts: ValidateOptions): ValidateResult;
+/**
+ * Validate a surface's data object: a JSON object within the placement's
+ * data-size limit (spec §4.5).
+ */
+export declare function validateData(data: unknown, placement: Placement): ValidateDataResult;

package/dist/extension.d.ts

@@ -349,14 +349,18 @@ export interface ExtensionCommandContribution {
         readonly notice?: string;
     } | void>;
 }
-/** One notification core delivers to every registered notifier (best-effort). */
-export interface NotificationEvent {
-    readonly type: "interaction.pending" | "job.failed" | "run.settled";
+/** The settled-run outcome: the notification-safe projection of the host
+ *  event's `outcome`/`reason` (status and reason only — no answer text). */
+export type RunSettledOutcome = {
+    readonly status: "answered";
+} | {
+    readonly status: "unanswered";
+    readonly reason: string;
+};
+/** Fields shared by every notification variant. */
+interface NotificationEventBase {
     readonly conversationId?: number;
     readonly jobId?: string;
-    /** Gateway C6: the pending record's id — set on `interaction.pending` only
-     *  (read the record via `host.snapshotInteraction`). */
-    readonly callId?: string;
     /** The recipient. */
     readonly user: string | undefined;
     readonly title: string;
@@ -364,6 +368,21 @@ export interface NotificationEvent {
     /** `${server.publicUrl}/#/c/<conversationId>` when `server.publicUrl` is set; absent otherwise. */
     readonly url?: string;
 }
+/** One notification core delivers to every registered notifier (best-effort). */
+export type NotificationEvent = NotificationEventBase & ({
+    readonly type: "interaction.pending";
+    /** Gateway C6: the pending record's id — set on `interaction.pending` only
+     *  (inspect it via `host.peekInteraction`; the OWNING extension's
+     *  delivery read is `host.snapshotInteraction`). */
+    readonly callId?: string;
+} | {
+    readonly type: "job.failed";
+} | {
+    readonly type: "run.settled";
+    /** Whether the run answered or not (model error, abort, …), with
+     *  the wire reason verbatim. Never infer success from the body. */
+    readonly outcome: RunSettledOutcome;
+});
 /** One notifier transport (ntfy, Signal, web push — core ships none). */
 export interface NotifierContribution {
     readonly name: string;
@@ -800,7 +819,22 @@ export interface SigrunHost {
     }): Promise<boolean>;
     /** Mark a pending interaction expired/cancelled/skipped (extension-owned semantics). */
     settleInteraction(conversationId: ConversationId, callId: string, status: "skipped" | "expired" | "cancelled", context: HandlerContext): Promise<boolean>;
-    /** Read one interaction record (the poll loop's read). */
+    /**
+     * Inspect one interaction record WITHOUT consuming anything: returns
+     * the same stored projection as {@link SigrunHost.snapshotInteraction}
+     * (secret values stay `SECRET_MASK`), but never touches the one-shot
+     * secret-delivery `take` path. Safe to repeat; neither extends nor
+     * shortens secret TTL; creates, settles, and mutates nothing. Use for
+     * inspection/rendering (notifiers, outcome edits, correlation).
+     */
+    peekInteraction(conversationId: ConversationId, callId: string, context: HandlerContext): Promise<Readonly<InteractionRecord> | undefined>;
+    /**
+     * The OWNING extension's delivery read: the first applicable read of
+     * an answered secret record merges its raw secret values back ONCE;
+     * subsequent reads see the stored mask. Inspection-only callers must
+     * use {@link SigrunHost.peekInteraction} instead — a consuming read
+     * by a non-owner silently destroys the owner's one-shot delivery.
+     */
     snapshotInteraction(conversationId: ConversationId, callId: string, context: HandlerContext): Promise<Readonly<InteractionRecord> | undefined>;
     /** Fully replace one ambient surface's state (write = replacement); the key must be unowned or yours. */
     setAmbient(conversationId: ConversationId, record: {