@sigrun/sigrun 0.1.5 → 0.2.0

package/dist/blocks/schema.js

@@ -307,7 +307,10 @@ const MeterBlock = Type.Object({
 const LogBlock = Type.Object({
     ...BlockBase,
     type: Type.Literal("log"),
-    lines: Type.Ref("Binding"),
+    // Literal lines are legal (ambient placement requires them — the
+    // ambient envelope carries no data document); placements that resolve
+    // bindings keep the binding form.
+    lines: Type.Union([Type.Ref("Binding"), Type.Array(Type.Ref("JsonValue"))]),
     follow: Type.Optional(Type.Boolean()),
     wrap: Type.Optional(Type.Boolean()),
     tones: Type.Optional(Type.Record(Type.String(), Type.Ref("Tone"))),
@@ -374,7 +377,10 @@ const BulkAction = Type.Object({
 const CollectionBlock = Type.Object({
     ...BlockBase,
     type: Type.Literal("collection"),
-    items: Type.Ref("Binding"),
+    // Literal rows are legal (ambient placement requires them — the
+    // ambient envelope carries no data document); placements that resolve
+    // bindings keep the binding form.
+    items: Type.Union([Type.Ref("Binding"), Type.Array(Type.Ref("JsonValue"))]),
     item: AnyObject,
     display: Type.Unsafe({
         type: "string",
@@ -445,6 +451,7 @@ const NumberField = Type.Object({
 const ToggleField = Type.Object({
     ...FieldBase,
     type: Type.Literal("toggle"),
+    default: Type.Optional(Type.Boolean()),
 });
 const ChoiceField = Type.Object({
     ...FieldBase,

package/dist/blocks/validate.js

@@ -142,9 +142,22 @@ function checkActionButtons(ctx, buttons, path) {
         checkAction(ctx, button.action, joinPath(bPath, "action"));
     });
 }
-/** Relative `./` bindings are legal only inside a card template (§4.2). */
+/**
+ * Bindings outside a card template (§4.2): relative `./` bindings are
+ * legal only inside an item template. In the AMBIENT placement, every
+ * binding (absolute or relative) outside an item template is rejected —
+ * the ambient envelope carries no data document, so a bound prop has
+ * nothing to resolve against and renders blank (the 2026-10-24 ruling's
+ * items rule, extended to every bindable prop).
+ */
 function checkBinding(ctx, binding, path) {
-    if (!ctx.itemTemplate && binding.$.startsWith("./")) {
+    if (ctx.itemTemplate)
+        return;
+    if (ctx.placement === "ambient") {
+        push(ctx, joinPath(path, "$"), `ambient surfaces carry literal content only (binding "${binding.$}" outside a collection item template)`);
+        return;
+    }
+    if (binding.$.startsWith("./")) {
         push(ctx, joinPath(path, "$"), `relative binding "${binding.$}" is only valid inside a collection item template`);
     }
 }
@@ -152,10 +165,12 @@ function checkBinding(ctx, binding, path) {
  * Any relative `./` binding on this node (§4.2): every prop value is
  * scanned — the binding-only props (`items`, `lines`, `nodes`, `rows`,
  * `series[].data`, `submitLabel`, `copy.text`) bind just like the
- * bindable literals, so a hardcoded prop list would miss them. Absolute
- * `/` bindings stay legal everywhere; relative ones only inside item
- * templates. `skip` names props whose own walk already reported (the
- * structural literals above carry their more precise message).
+ * bindable literals, so a hardcoded prop list would miss them. Outside
+ * ambient, absolute `/` bindings stay legal everywhere and relative
+ * ones only inside item templates; in ambient, every binding outside an
+ * item template fails (checkBinding). `skip` names props whose own walk
+ * already reported (the structural literals above carry their more
+ * precise message).
  */
 function checkNodeRelativeBindings(ctx, node, path, skip) {
     if (ctx.itemTemplate)
@@ -282,6 +297,35 @@ function checkBlock(ctx, node, path, rootDepth) {
         checkSchema(ctx, validator, node, path);
     // collection-specific rules
     if (type === "collection") {
+        // Controller ruling (2026-10-24): bindings are OUT of ambient
+        // placement — the ambient envelope carries no data document, so a
+        // bound `items` has nothing to resolve against. Literal rows only.
+        // (Reversible: extending the envelope with a data slot remains open.)
+        if (ctx.placement === "ambient" && isBinding(node.items)) {
+            // checkBinding's ambient branch fires for this prop too; the
+            // more specific collection wording wins, so skip `items` below.
+            push(ctx, joinPath(path, "items"), "ambient collections carry literal rows (items must not be a binding)");
+        }
+        // Ambient: bindables nested inside structural props are still
+        // bound nowhere (the no-data-document ruling). `groups`/`columns`
+        // sit in the structural skip set, so the generic binding walk
+        // never reaches their `title`/`label` bindables — walk them here.
+        if (ctx.placement === "ambient") {
+            const nestedBindables = [
+                ["groups", "title"],
+                ["columns", "label"],
+            ];
+            for (const [listProp, leafProp] of nestedBindables) {
+                const list = node[listProp];
+                if (!Array.isArray(list))
+                    continue;
+                list.forEach((entry, i) => {
+                    if (isRec(entry) && isBinding(entry[leafProp])) {
+                        checkBinding(ctx, entry[leafProp], joinPath(joinPath(joinPath(path, listProp), String(i)), leafProp));
+                    }
+                });
+            }
+        }
         const display = node.display;
         if (typeof display === "string" &&
             rules.collectionDisplays &&
@@ -350,9 +394,14 @@ function checkBlock(ctx, node, path, rootDepth) {
         if (!check.ok)
             push(ctx, joinPath(path, "src"), check.message);
     }
-    // bindable props: every relative `./` binding on the node (§4.2)
+    // bindable props: every relative `./` binding on the node (§4.2).
+    // `items` joins the skip set in ambient so the collection-specific
+    // message above stays the single error at its path.
     const structural = STRUCTURAL_LITERALS[type] ?? [];
-    checkNodeRelativeBindings(ctx, node, path, new Set(structural));
+    const skip = new Set(structural);
+    if (type === "collection" && ctx.placement === "ambient")
+        skip.add("items");
+    checkNodeRelativeBindings(ctx, node, path, skip);
     // onActivate carries an Action (§6.1): same rules as button actions
     if (node.onActivate !== undefined) {
         checkAction(ctx, node.onActivate, joinPath(path, "onActivate"));

package/dist/cli.js

@@ -49,6 +49,12 @@ import { Writable } from "node:stream";
 import { resolveStoreRoots, writeFileAtomic } from "./harness/stores.js";
 import { openIdentityStores } from "./harness/identity/index.js";
 import { pathToFileURL } from "node:url";
+import { effectiveMethods, loadConfig } from "./config.js";
+import { probeIsolation, runHelperProbe, selfTestHelper } from "./sandbox/availability.js";
+import { SettingsStore } from "./harness/settings.js";
+import { resolveHelper } from "./sandbox/helper.js";
+import { selfPackageRoot } from "./harness/packages.js";
+import { createAdmissionGuard } from "./harness/identity/users.js";
 import { serve } from "./serve.js";
 import { ACCENT_NAMES, PALETTE_NAMES, isAccentName, isPaletteName, } from "@sigrun/shared/themes";
 export const USAGE_TEXT = `usage: sigrun [--user <name>]
@@ -643,7 +649,7 @@ async function runProviderCommand(parsed, env, io, fetchImpl, readSecret) {
  *   secret exists only at create time);
  * - `token revoke` fails loud on an unknown id.
  */
-async function runIdentityCommand(parsed, env, io) {
+async function runIdentityCommand(parsed, env, io, isolationProbe) {
     const stores = openIdentityStores(resolveStoreRoots(env));
     if (parsed.command === "token") {
         switch (parsed.sub) {
@@ -679,6 +685,24 @@ async function runIdentityCommand(parsed, env, io) {
     }
     switch (parsed.sub) {
         case "add": {
+            const config = loadConfig(env, new SettingsStore({ dir: defaultConfigDir(env) }).read());
+            const coreRoot = selfPackageRoot();
+            const isolation = await isolationProbe({
+                platform: process.platform,
+                helper: coreRoot === undefined ? undefined : resolveHelper(env, coreRoot),
+                runProbe: runHelperProbe,
+                selfTest: selfTestHelper,
+            });
+            const methods = effectiveMethods(config.auth, "127.0.0.1");
+            stores.users.configureAdmission({
+                firstWorkspace: config.workspace.path,
+                admit: createAdmissionGuard({
+                    isolation,
+                    mode: config.isolation.mode,
+                    methods,
+                    proxySecretHeader: config.auth.proxy.secretHeader,
+                }),
+            });
             await stores.users.add({
                 user: parsed.user,
                 admin: parsed.admin ?? false,
@@ -850,7 +874,7 @@ export async function cliMain(argv, env = process.env, deps, io = {
             case "token":
             case "user": {
                 // The identity commands (Task 7): stores directly, server or not.
-                return await runIdentityCommand(parsed, env, io);
+                return await runIdentityCommand(parsed, env, io, realDeps.probeIsolation ?? probeIsolation);
             }
             case "provider": {
                 // The provider commands (release 0.1 Task 2b): API clients over

package/dist/config.js

@@ -148,6 +148,7 @@ export const DEFAULT_PROVIDER_REFRESH_MINUTES = 15;
  * defaulted — they exist only when env provides them.
  */
 export const DEFAULT_AUTH = {
+    sessionDays: 30,
     methods: undefined,
     proxy: {
         trustedProxies: [],
@@ -323,6 +324,40 @@ function parseDev(env) {
         return false;
     throw new Error(`SIGRUN_DEV must be "true" or "false" (or 1/0), got ${JSON.stringify(raw)}`);
 }
+/** Parse `SIGRUN_ISOLATION`; unset/empty lets the file/default tier apply. */
+function parseIsolationMode(env) {
+    const raw = env.SIGRUN_ISOLATION;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const mode = raw.trim().toLowerCase();
+    if (mode === "auto" || mode === "always" || mode === "off")
+        return mode;
+    throw new Error(`SIGRUN_ISOLATION must be "auto", "always", or "off", got ${JSON.stringify(raw)}`);
+}
+function parseIsolation(env, server) {
+    return {
+        mode: parseIsolationMode(env) ?? server?.mode ?? "auto",
+        osUsers: server?.osUsers ?? false,
+        workerIdleMinutes: server?.workerIdleMinutes ?? 10,
+    };
+}
+/**
+ * Parse `SIGRUN_SUPERVISED` (UI-blocks U4 Task 2, spec §13.3): the
+ * `parseDev` grammar exactly ("true"/"false"/1/0, strict otherwise —
+ * the env contract is the deploy's promise that a restart policy exists,
+ * so a fuzzy parse would lie about the failure mode).
+ */
+function parseSupervised(env) {
+    const raw = env.SIGRUN_SUPERVISED;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const lowered = raw.trim().toLowerCase();
+    if (lowered === "true" || lowered === "1")
+        return true;
+    if (lowered === "false" || lowered === "0")
+        return false;
+    throw new Error(`SIGRUN_SUPERVISED must be "true" or "false" (or 1/0), got ${JSON.stringify(raw)}`);
+}
 /**
  * Parse `SIGRUN_AUTH`: a csv of `token`/`proxy` (order preserved,
  * duplicates dropped), `none` ALONE as the empty list (authentication
@@ -398,6 +433,7 @@ function parseAuth(env, server) {
     const token = env.SIGRUN_API_TOKEN?.trim() || undefined;
     const secret = env.SIGRUN_PROXY_SECRET?.trim() || undefined;
     return {
+        sessionDays: server?.sessionDays ?? DEFAULT_AUTH.sessionDays,
         methods,
         proxy: {
             trustedProxies,
@@ -730,11 +766,15 @@ export function resolvedServerSection(config) {
         proxySection !== undefined ||
         config.auth.adminGroups.length > 0 ||
         config.auth.allowedHosts !== undefined ||
-        config.auth.allowedOrigins !== undefined
+        config.auth.allowedOrigins !== undefined ||
+        config.auth.sessionDays !== DEFAULT_AUTH.sessionDays
         ? {
             ...(config.auth.methods === undefined
                 ? {}
                 : { methods: [...config.auth.methods] }),
+            ...(config.auth.sessionDays === DEFAULT_AUTH.sessionDays
+                ? {}
+                : { sessionDays: config.auth.sessionDays }),
             ...(proxySection === undefined ? {} : { proxy: proxySection }),
             ...(config.auth.adminGroups.length > 0
                 ? { adminGroups: [...config.auth.adminGroups] }
@@ -765,6 +805,7 @@ export function resolvedServerSection(config) {
         ...(webui === undefined ? {} : { webui }),
         compaction: { ...config.compaction },
         memorySeam: { ...config.memorySeam },
+        isolation: { ...config.isolation },
         providers: { ...config.providers },
         ...(auth === undefined ? {} : { auth }),
         ...(metrics === undefined ? {} : { metrics }),
@@ -803,6 +844,7 @@ export function resolvedServerSection(config) {
  * | `SIGRUN_IDLE_THRESHOLD` | `memorySeam.idleThresholdMs` |
  * | `SIGRUN_WORKER_DEADLINE` | `memorySeam.workerDeadlineMs` |
  * | `SIGRUN_QUEUE_MAX` | `memorySeam.queueMax` |
+ * | `SIGRUN_ISOLATION` | `isolation.mode` |
  * | `SIGRUN_PROVIDER_REFRESH_MINUTES` | `providers.refreshIntervalMinutes` |
  * | `SIGRUN_BACKUP_*` | `backup` |
  * | `SIGRUN_MAX_UPLOAD_BYTES` | `maxUploadBytes` |
@@ -859,6 +901,9 @@ export function envServerSection(env) {
     });
     if (memorySeam !== undefined)
         section.memorySeam = memorySeam;
+    const isolationMode = parseIsolationMode(env);
+    if (isolationMode !== undefined)
+        section.isolation = { mode: isolationMode };
     const refreshIntervalMinutes = parseNonNegativeIntEnv(env, PROVIDER_REFRESH_MINUTES_ENV);
     if (refreshIntervalMinutes !== undefined) {
         section.providers = { refreshIntervalMinutes };
@@ -877,6 +922,12 @@ export function envServerSection(env) {
     const dev = parseDev(env);
     if (dev !== undefined)
         section.dev = dev;
+    // The supervised flag (§13.3) — the same bootstrap rule as dev:
+    // projected only when the env var is SET (a defaulted flag is never
+    // persisted; the deploy's restart posture is env intent, not state).
+    const supervised = parseSupervised(env);
+    if (supervised !== undefined)
+        section.supervised = supervised;
     return section;
 }
 /**
@@ -950,8 +1001,18 @@ export function effectiveServerSection(env, fileServer, config) {
         "memorySeam",
         "queueMax",
     ]);
+    emit("auth.sessionDays", config.auth.sessionDays, ["auth", "sessionDays"]);
+    emit("isolation.mode", config.isolation.mode, ["isolation", "mode"]);
+    emit("isolation.osUsers", config.isolation.osUsers, ["isolation", "osUsers"]);
+    emit("isolation.workerIdleMinutes", config.isolation.workerIdleMinutes, [
+        "isolation",
+        "workerIdleMinutes",
+    ]);
     emit("providers.refreshIntervalMinutes", config.providers.refreshIntervalMinutes, ["providers", "refreshIntervalMinutes"]);
     emit("dev", config.dev, ["dev"]);
+    // U4 §13.3: the supervised posture rides the effective block too —
+    // the settings surface's restart affordance reads one place.
+    emit("supervised", config.supervised, ["supervised"]);
     if (config.backup?.target === "path") {
         emit("backup.path", config.backup.path, ["backup", "path"]);
         emit("backup.staleAfterHours", config.backupStaleAfterHours, ["backup", "staleAfterHours"]);
@@ -1093,6 +1154,7 @@ export function loadConfig(env, settingsFile) {
         backupStaleAfterHours: server?.backup?.staleAfterHours ?? DEFAULT_BACKUP_STALE_AFTER_HOURS,
         compaction: parseCompaction(env, server?.compaction),
         memorySeam: parseMemorySeam(env, server?.memorySeam),
+        isolation: parseIsolation(env, server?.isolation),
         providers: {
             refreshIntervalMinutes: parseRefreshIntervalMinutes(env, server?.providers?.refreshIntervalMinutes),
         },
@@ -1101,6 +1163,10 @@ export function loadConfig(env, settingsFile) {
         // The development flag (§14.2/§14.4): strict env parse over the
         // file's `server.dev`, default false.
         dev: parseDev(env) ?? server?.dev ?? false,
+        // The supervised posture (§13.3): env over file over false. Only
+        // the chart and compose set the env; a file-set flag serves a
+        // hand-rolled systemd/supervisord deploy (same restart promise).
+        supervised: parseSupervised(env) ?? server?.supervised ?? false,
         // The jobs default timezone (§8.2): env over file over the process
         // TZ, validated loud (a bad name would otherwise crash the scheduler
         // at evaluation time instead of failing boot).

package/dist/extension.d.ts

@@ -35,12 +35,12 @@
 import type { AssistantMessage, Provider } from "@earendil-works/pi-ai";
 import type { ConversationDocToken, ConversationId, Cursor, EntryId, EntryQuery, EntryRecord, Extension, InputSubmissionDraft, JsonObject, ModelRef, Page, SubmissionId } from "@earendil-works/pi-durable";
 import type { Access, Sharing } from "@sigrun/shared/access";
-import type { AmbientBody, AmbientPlace, AmbientRecord } from "@sigrun/shared/ambient";
+import type { AmbientPlace, AmbientRecord } from "@sigrun/shared/ambient";
 import type { Action, DataOps, IconName, Tree } from "@sigrun/shared/blocks";
 import type { InteractionAnswer, InteractionRecord } from "@sigrun/shared/interactions";
 import type { JobSpec } from "@sigrun/shared/jobs";
-import type { ConversationSummary, ConversationViewWire, HealthStatus, ModelEntry, SessionMeta, SlashCommand, SubmissionRecordWire, ThinkingLevelWire, UserWire as DirectoryUserWire } from "@sigrun/shared/views";
-export type { Access, AmbientRecord, DirectoryUserWire, InteractionRecord, JobSpec, ModelEntry, Sharing, SlashCommand, };
+import type { AccountLinkWire, ConversationSummary, ConversationViewWire, HealthStatus, ModelEntry, SessionMeta, SlashCommand, SubmissionRecordWire, ThinkingLevelWire, UserWire as DirectoryUserWire } from "@sigrun/shared/views";
+export type { Access, AccountLinkWire, AmbientRecord, DirectoryUserWire, InteractionRecord, JobSpec, ModelEntry, Sharing, SlashCommand, };
 type JsonParams = JsonObject;
 type JsonParamValue = JsonParams[string];
 /**
@@ -63,6 +63,8 @@ export interface HandlerContext {
  */
 export type RunSettledEvent = {
     readonly conversationId: ConversationId;
+    /** The conversation owner at delivery; absent when the conversation is ownerless. */
+    readonly owner?: string;
     readonly inputs: readonly SubmissionId[];
     /** Text blocks of each input's entry (`pi.user`, or an expanded input's
      *  `sigrun.user.expanded` — the ADMITTED text), concatenated;
@@ -100,19 +102,24 @@ export type MemoryEventApi = {
 export type ExtensionLifecyclePayload = {
     conversationCreated: {
         readonly conversationId: ConversationId;
+        readonly owner?: string;
     };
     conversationForked: {
         readonly childId: ConversationId;
         readonly parentId: ConversationId;
         readonly at: EntryId;
+        /** The CHILD's owner at delivery; absent when the child is ownerless. */
+        readonly owner?: string;
     };
     conversationArchived: {
         readonly conversationId: ConversationId;
         readonly archived: boolean;
+        readonly owner?: string;
     };
     conversationIdle: {
         readonly conversationId: ConversationId;
         readonly idleMs: number;
+        readonly owner?: string;
     };
     /** Gateway C6: one terminal interaction transition — the payload mirrors
      *  the record's terminal envelope fields. */
@@ -121,6 +128,11 @@ export type ExtensionLifecyclePayload = {
         readonly callId: string;
         readonly kind: string;
         readonly status: "answered" | "skipped" | "expired" | "cancelled";
+        /** The answering user (C5 attribution), when a human answered. */
+        readonly answeredByUser?: string;
+        /** The STORED (masked-by-construction) answer values — render-safe. */
+        readonly answer?: Readonly<Record<string, unknown>>;
+        readonly owner?: string;
     };
 };
 /** A factory-result `runSettled` handler: called once per settled run, deadline-bounded. */
@@ -151,6 +163,17 @@ export type SigrunLifecycleHandlers = {
     readonly harnessShutdown?: ExtensionHarnessShutdownHandler;
     /** The user-removal transfer event; direct fan-out, not commit-derived. */
     readonly userDeleted?: ExtensionUserDeletedHandler;
+    /**
+     * UI-blocks U4 (spec §13.2): called after a settings write COMMITS —
+     * the keys are the flattened paths the write touched (core keys in
+     * the §13.1 dotted vocabulary, this extension's own top-level keys
+     * for a `settings/<slug>.json` write). Fired for BOTH scopes: a
+     * server-scope write notifies every loaded extension; an extension's
+     * own write notifies it (and every other extension — settings are
+     * shared operator surface). Errors are caught and logged; the write
+     * already succeeded and stays successful.
+     */
+    onSettingsChanged?(keys: readonly string[], user?: string): void | Promise<void>;
 };
 /**
  * The lifecycle event names a worker's `wakeOn` may declare.
@@ -182,6 +205,31 @@ export interface ExtensionWorker {
     /** The work; rejects (or overruns the worker deadline) to fail the run. */
     run(context: HandlerContext, wake?: WorkerWake): Promise<void>;
 }
+/** The command and extra environment/read rights for one per-user process. */
+export interface ServiceSpec {
+    readonly command: string;
+    readonly args: string[];
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+    readonly readPaths?: string[];
+}
+/** One factory-declared long-lived per-user service. */
+export interface UserService {
+    readonly name: string;
+    start(user: string, ctx: HandlerContext): Promise<ServiceSpec | undefined>;
+    readonly idleMinutes?: number;
+}
+/** A shared-stdio attachment to a running per-user service. */
+export interface ServiceHandle {
+    readonly stdin: WritableStream<Uint8Array>;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    readonly exited: Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    release(): void;
+}
 /** Three-state per-provider readiness: not configured, degraded, or ready. */
 export type ProviderReadinessStatus = "not_configured" | "degraded" | "ready";
 /** One readiness report: the status plus optional operator-facing detail. */
@@ -207,6 +255,42 @@ export interface ProviderContribution {
     /** The per-provider readiness tracker (`/v1/auth/check` reports it verbatim). */
     readonly readiness?: ReadinessTracker;
 }
+/** Core-owned state for one external login, with provider-private scratch data. */
+export type LoginFlow = {
+    state: string;
+    callbackUrl: string;
+    data: Record<string, string>;
+};
+/** The identity proof a login provider returns after its callback. */
+export type LoginResult = {
+    subject: string;
+    profile: {
+        username?: string;
+        name?: string;
+        email?: string;
+        emailVerified?: boolean;
+    };
+    groups?: string[];
+};
+/** One extension identity provider; core owns the flow, state and callback. */
+export interface LoginProviderContribution {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: string;
+    /** Provider-declared provisioning policy, enforced by core. */
+    readonly policy?: {
+        readonly autoProvision?: boolean;
+        readonly allowedGroups?: string[];
+        readonly allowedDomains?: string[];
+    };
+    begin(flow: LoginFlow, ctx: HandlerContext): Promise<{
+        redirectUrl: string;
+    }>;
+    complete(flow: LoginFlow, callback: {
+        query: Record<string, string>;
+        body?: unknown;
+    }, ctx: HandlerContext): Promise<LoginResult>;
+}
 /** One contributed webui bundle: a selection name plus the bundle root directory. */
 export interface WebuiBundleContribution {
     /** The selection key (`server.webui.bundle`); must match `^[a-z][a-z0-9_-]*$`. */
@@ -231,7 +315,9 @@ export interface Principal {
     readonly admin: boolean;
     /** True for the `SIGRUN_API_TOKEN` service principal. */
     readonly service: boolean;
-    readonly method: "none" | "token" | "proxy" | "host";
+    readonly method: "none" | "token" | "session" | "proxy" | "host";
+    /** The login provider that issued a session principal. */
+    readonly provider?: string;
 }
 /** One extension HTTP route, mounted at `/v1/ext/<slug>/<path>`. */
 export interface ExtensionRouteContribution {
@@ -564,10 +650,12 @@ export type ActionResult = {
 };
 /**
  * One declared surface (spec §7.1, verbatim shape): the placement is
- * the generic parameter — `"view"` or `"panel"` (the settings sections
- * of §13.3 are a separate workstream).
+ * the generic parameter — `"view"`, `"panel"`, or `"settings"` (the
+ * §13.3 settings sections adapt to settings-placement surfaces; the
+ * host builds those — extensions declare `SettingsSectionDef`s, never
+ * `SurfaceDef<"settings">` directly).
  */
-export interface SurfaceDef<P extends "view" | "panel"> {
+export interface SurfaceDef<P extends "view" | "panel" | "settings"> {
     /** Unique within the extension. */
     readonly id: string;
     readonly title: string;
@@ -577,22 +665,51 @@ export interface SurfaceDef<P extends "view" | "panel"> {
     readonly sharedData?: boolean;
     /** Channels refetch data on this interval while visible (min 5000). */
     readonly refreshMs?: number;
-    /** §7.3; default: canonical JSON of params. */
-    instanceKey?(params: JsonParams): string;
+    /** §7.3; default: canonical JSON of params. The principal argument
+     *  lets principal-owned surfaces isolate their revision/action identity. */
+    instanceKey?(params: JsonParams, principal: Principal): string;
     render(ctx: SurfaceContext): Promise<SurfaceRenderResult>;
     data?(ctx: SurfaceContext): Promise<SurfaceDataResult>;
     readonly actions?: Readonly<Record<string, (ctx: SurfaceContext, payload: JsonParamValue) => Promise<ActionResult>>>;
 }
 /**
- * The `surfaces` field of a factory result (spec §7.1): declared views
- * and panels. Ids are unique across BOTH lists (one namespace — the
- * loader enforces it).
+ * One declared settings section (spec §13.3, verbatim shape): a static
+ * `settings`-placement form bound to the extension's settings object
+ * (`settings/<slug>.json`). The host adapts it to a surface under the
+ * extension's own `/v1/ext/<slug>/surfaces/` mount — core's own
+ * sections use the same renderer, under the reserved `core` slug.
+ */
+export interface SettingsSectionDef {
+    /** Unique within the extension. */
+    readonly id: string;
+    readonly title: string;
+    readonly icon?: IconName;
+    /** A root `form` block; the placement is `settings` (spec §5.7). */
+    readonly form: Tree;
+    /** Declared secrets, rendered as `secret` fields backed by the §7.7 secrets routes. */
+    readonly secrets?: readonly {
+        key: string;
+        label: string;
+        help?: string;
+    }[];
+    /** Only admins see and edit it; default true for shared sections.
+     *  A user-scope section is visible to every signed-in user unless this
+     *  is explicitly true. */
+    readonly admin?: boolean;
+    /** `"user"` reads/writes the calling user's settings; absent/`"server"`
+     *  keeps the extension's shared settings file. */
+    readonly scope?: "server" | "user";
+}
+/**
+ * The `surfaces` field of a factory result (spec §7.1): declared views,
+ * panels, and settings sections. Ids are unique across ALL THREE lists
+ * (one namespace — the loader enforces it).
  */
 export interface SurfacesContribution {
     readonly views?: readonly SurfaceDef<"view">[];
     readonly panels?: readonly SurfaceDef<"panel">[];
-    /** §13.3 settings sections — a separate workstream; declared for shape stability. */
-    readonly settings?: readonly never[];
+    /** §13.3 settings sections (UI-blocks U4 Task 3). */
+    readonly settings?: readonly SettingsSectionDef[];
 }
 /** One wire part of a `host.conversations.submit` input array. */
 export type SubmissionInputPart = {
@@ -620,8 +737,38 @@ export type WhenBusyMode = NonNullable<InputSubmissionDraft["whenBusy"]>;
  * factory body.
  */
 export interface SigrunHost {
+    /**
+     * Publish tools for ONE user (multi-user M2). Only factory results that
+     * declared `perUserTools: true` may call this; other extensions throw
+     * `perUserTools not declared`. An empty list uninstalls the user's entry.
+     * Core wraps every tool with a committed-owner check at execute time.
+     */
+    readonly tools: {
+        setUserTools(user: string, tools: readonly import("@earendil-works/pi-durable").ToolRegistration[]): void;
+    };
+    /** Connect to one declared per-user service; core owns its process lifecycle. */
+    readonly services: {
+        connect(name: string, user: string, ctx: HandlerContext): Promise<ServiceHandle>;
+    };
     /** The scoped extension-stores handle (your secrets/settings sections + raw data/cache/state paths). */
     readonly stores: {
+        /** One directory user's secrets/settings/paths, still scoped to your slug. */
+        user(user: string): {
+            readonly secrets: {
+                get(key: string): Promise<string | undefined>;
+                set(key: string, value: string): Promise<void>;
+                delete(key: string): Promise<void>;
+            };
+            readonly settings: {
+                get(): Promise<Record<string, unknown>>;
+                set(value: Record<string, unknown>): Promise<void>;
+            };
+            readonly paths: {
+                readonly data: string;
+                readonly state: string;
+                readonly cache: string;
+            };
+        };
         /** Your section of secrets.json. */
         readonly secrets: {
             get(key: string): Promise<string | undefined>;
@@ -662,7 +809,7 @@ export interface SigrunHost {
         readonly maxRows?: number;
         readonly overflow?: "drop" | "wrap" | "summarize";
         readonly refreshMs?: number;
-        readonly body?: AmbientBody;
+        readonly body?: Tree;
         readonly details?: JsonObject;
     }, context: HandlerContext): Promise<void>;
     /** Clear one ambient surface (empty replacement; keeps ownership). */
@@ -729,6 +876,8 @@ export interface SigrunHost {
         configure(id: ConversationId, opts: {
             readonly model?: string;
             readonly thinking?: ThinkingLevelWire;
+            /** Exact extension selection; another user's `<slug>@<user>` entry is rejected. */
+            readonly extensions?: readonly string[];
         }): Promise<void>;
         /** Admit one manual compaction task (gateway C4, the compact route's op). */
         compact(id: ConversationId): Promise<void>;
@@ -782,6 +931,25 @@ export interface SigrunHost {
         list(): Promise<readonly DirectoryUserWire[]>;
         get(user: string): Promise<DirectoryUserWire | undefined>;
     };
+    /**
+     * External identities linked to directory users (multi-user §11.3): the
+     * one table for chat senders (`chat:<channel>`) and login subjects
+     * (`login:<slug>:<id>`), shared with the gateway.
+     *
+     * Core owns the file — extensions go through this surface, never
+     * `accounts.json` directly. One link per `(provider, subject)`: a
+     * re-link to the same user is a no-op returning the existing record, a
+     * link to a DIFFERENT user rejects with an `Error` whose message starts
+     * `account_link_conflict:` (the message never names the current
+     * holder — extensions match the prefix, as they do `command_not_found:`).
+     * An unknown user rejects `unknown user "<user>"`.
+     */
+    readonly accounts: {
+        lookup(provider: string, subject: string): Promise<AccountLinkWire | undefined>;
+        link(provider: string, subject: string, user: string, via: AccountLinkWire["via"]): Promise<AccountLinkWire>;
+        unlink(provider: string, subject: string): Promise<boolean>;
+        listForUser(user: string): Promise<readonly AccountLinkWire[]>;
+    };
     /**
      * Resolve one principal's access to one shared resource (the whole
      * sharing contract for extension-owned records — core stores nothing
@@ -841,12 +1009,18 @@ export interface SigrunHost {
  * begins reading each when its task lands.
  */
 export interface SigrunExtensionResult extends SigrunLifecycleHandlers {
+    /** Long-lived per-user sibling processes, launched and supervised by core. */
+    readonly userServices?: readonly UserService[];
+    /** Declare the per-user tool surface (`host.tools.setUserTools`). */
+    readonly perUserTools?: boolean;
     /** The pi-durable `Extension` to install; its declared name is the slug source. */
     readonly extension?: Extension;
     /** The contributor-only identity (required when contributing without an `extension`). */
     readonly name?: string;
     /** Provider contributions, merged into the boot model catalog (last-registered-wins, collisions recorded). */
     readonly providers?: readonly ProviderContribution[];
+    /** External identity providers; core qualifies ids as `login:<slug>:<id>`. */
+    readonly loginProviders?: readonly LoginProviderContribution[];
     /** Webui-bundle contributions; each `dir` anchors at the extension ENTRY's directory. */
     readonly webuiBundles?: readonly WebuiBundleContribution[];
     /** The surface's health producer, aggregated into `/v1/meta` `health` (any `"degraded"` degrades). */