From ce3da867324e37d8f0e691ecfd0ca2d9d2ed3fc6 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 08:37:47 +0000
Subject: [PATCH 01/10] feat: extension-contributed settings and session
 lineage surfaces

Adds the generic pi-web vocabulary that multi-agent workflows need, without
teaching core anything about orchestration.

Extension settings platform:
- ctx.ui.web.registerSettings/getSettings, backed by a process-global
  active-schema registry so validation and rendering are independent of which
  session the browser happens to be viewing.
- Values persist under settings.extensions[id] as
  { schemaVersion, revision, values, backup? } and are carried through
  verbatim, so an unloaded extension never loses its configuration. This also
  fixes normalizeSettings silently dropping unknown top-level keys.
- Validated writes with an optimistic revision guard, bounded payloads,
  schemaVersion migration with a one-slot backup, and per-owner reset.
- A generic settings renderer: toggle/text/textarea/number/select/list, with
  accordion rows for repeaters, live model options (optionsSource: "models"),
  cross-field references (optionsFromField) rendered as a per-row default star,
  stable row ids, and inline accessible validation.

Session lineage and derived state:
- Session origin tracking, so sessions spawned by another session are indented
  under their parent in the drawer with a lineage glyph.
- A derived "waiting on spawned sessions" indicator (drawer, tab, status bar)
  with a single precedence rule: running > waiting > unread.
- Custom (extension-injected) messages render as notification cards, and cards
  link to referenced sessions from structured details. Tool result cards can
  surface the same session links.

Tests cover the store (verbatim preservation across unrelated patches, revision
conflicts, bounds, backup placement, reset, on-disk round trip) and the
descriptor validator (canonical schema identity, stable row ids, option and
cross-field reference checks, uniqueness, bounds).
---
 index.html                        |   1 +
 server.ts                         |  58 ++++-
 server/extensionSettings.ts       | 265 ++++++++++++++++++++
 server/extensions/webUi.ts        | 137 ++++++++++-
 server/session/projection.ts      |   1 +
 server/session/service.ts         |  12 +
 server/sessionUiState.ts          |  46 +++-
 server/settings.ts                | 193 ++++++++++++++-
 src/app/elements.ts               |   2 +
 src/app/icons.ts                  |   4 +-
 src/app/types.ts                  |  61 +++++
 src/extensions.ts                 |  68 +++++
 src/main.ts                       |   2 +
 src/messages/messageList.ts       | 104 +++++++-
 src/realtime/realtime.ts          |   8 +
 src/sessions/sessionDrawer.ts     | 206 +++++++++++++++-
 src/settings/extensionSettings.ts | 396 ++++++++++++++++++++++++++++++
 src/settings/settings.ts          |  30 ++-
 src/status/statusBar.ts           |  35 +++
 src/styles/base.css               |  64 +++++
 src/styles/composer.css           |   7 +
 src/styles/messages.css           |  75 ++++++
 src/styles/sessions.css           |  54 ++++
 src/styles/settings.css           | 166 +++++++++++++
 src/tools/toolCards.ts            |  54 ++++
 tests/extension-settings.test.ts  |  97 ++++++++
 tests/settings.test.ts            |  87 ++++++-
 27 files changed, 2207 insertions(+), 26 deletions(-)
 create mode 100644 server/extensionSettings.ts
 create mode 100644 src/settings/extensionSettings.ts
 create mode 100644 tests/extension-settings.test.ts

diff --git a/index.html b/index.html
index 65bb76d..198650f 100644
--- a/index.html
+++ b/index.html
@@ -326,6 +326,7 @@ <h3>Extensions</h3>
             <button id="extensionReloadButton" type="button">Retry extensions</button>
           </div>
         </section>
+        <div id="extensionSettingsContainer" class="extensionSettings"></div>
         <section id="tokenShareSection" class="settingsSection tokenShareSection" hidden>
           <h3>Token sharing</h3>
           <p class="settingsHint">Use Show QR or Copy link to open pi web on another trusted device with this browser’s saved token.</p>
diff --git a/server.ts b/server.ts
index 6273960..fd3ae80 100644
--- a/server.ts
+++ b/server.ts
@@ -9,7 +9,8 @@ import { getAgentDir, ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { createMockHarness } from "./server/mock.js";
 import { resolveBundledExtensionPaths, resolvePiWebExtensionPaths } from "./server/extensions.js";
 import { createSessionUiStateStore, defaultSessionUiState } from "./server/sessionUiState.js";
-import { createSettingsStore } from "./server/settings.js";
+import { ExtensionRevisionConflictError, ExtensionSettingsBoundsError } from "./server/settings.js";
+import { defaultSettingsValues, validateSettingsValues } from "./server/extensionSettings.js";
 import { findArtifactFile, isValidArtifactPath } from "./server/shared/artifacts.js";
 import { assertDirectory, createDirectory, listDirectories } from "./server/shared/fsList.js";
 import { gitCommitDetails, gitCwdFromRepoParam, gitDiff, gitLog, gitStatus, gitSync, isGitRepo, listGitRepos, readGitImage } from "./server/shared/git.js";
@@ -232,7 +233,6 @@ function envMs(name: string, fallback: number) {
 }
 
 const modelRuntime = await ModelRuntime.create();
-const settingsStore = createSettingsStore(process.env.PI_WEB_SETTINGS_FILE || join(getAgentDir(), "pi-web-settings.json"));
 const sessionUiStateStore = createSessionUiStateStore(process.env.PI_WEB_SESSION_UI_STATE_FILE || join(getAgentDir(), "pi-web-session-ui-state.json"));
 let sessionService: LocalSessionService;
 const sessionActivity = new SessionActivity((path) => sessionService?.sessionForPath(path));
@@ -371,6 +371,7 @@ sessionService = new LocalSessionService({
   globalCwd: () => piCwd,
   clientCount: () => realtimeHub.clientCount,
 });
+const settingsStore = sessionService.settingsStore;
 sessionService.subscribe((event) => {
   if (event.type === "shutdown") {
     mockPromptCorrelations.delete(event.sessionKey);
@@ -681,7 +682,7 @@ const server = createServer(async (req, res) => {
 
 
       if (method === "GET" && url.pathname === "/api/settings") {
-        return sendJson(res, 200, { ok: true, settings: await settingsStore.read() });
+        return sendJson(res, 200, { ok: true, settings: await settingsStore.read(), webSettingsSchemas: sessionService.settingsSchemas() });
       }
 
       if (method === "PATCH" && url.pathname === "/api/settings") {
@@ -699,6 +700,46 @@ const server = createServer(async (req, res) => {
         return sendJson(res, 200, { ok: true, status: await sessionService.reloadExtensions(resolveSessionId(body.sessionId)) });
       }
 
+      if (url.pathname.startsWith("/api/settings/extensions/")) {
+        const rest = url.pathname.slice("/api/settings/extensions/".length);
+        const isReset = rest.endsWith("/reset");
+        const ownerId = decodeURIComponent(isReset ? rest.slice(0, -"/reset".length) : rest);
+        const entry = sessionService.settingsSchemaEntry(ownerId);
+        if (!entry) return sendJson(res, 409, { ok: false, error: "extension not loaded" });
+
+        if (method === "POST" && isReset) {
+          const settings = await settingsStore.resetExtension(ownerId);
+          broadcast({ type: "settings_updated", settings });
+          try { entry.schema.onChange?.(defaultSettingsValues(entry.schema)); } catch { /* ignore */ }
+          return sendJson(res, 200, { ok: true, settings });
+        }
+
+        if (method === "PATCH" && !isReset) {
+          const body = await readBody(req) as { values?: unknown; expectedRevision?: unknown };
+          const { values, errors } = validateSettingsValues(entry.schema, body?.values, { modelOptions: sessionService.modelOptionTokens() });
+          if (errors.length) return sendJson(res, 422, { ok: false, errors });
+          try {
+            const settings = await settingsStore.patchExtension(ownerId, values, {
+              schemaVersion: entry.schema.schemaVersion,
+              expectedRevision: typeof body?.expectedRevision === "number" ? body.expectedRevision : undefined,
+            });
+            broadcast({ type: "settings_updated", settings });
+            try { entry.schema.onChange?.(values); } catch { /* ignore */ }
+            return sendJson(res, 200, { ok: true, settings, revision: settings.extensions?.[ownerId]?.revision ?? 0 });
+          } catch (error) {
+            if (error instanceof ExtensionRevisionConflictError) {
+              return sendJson(res, 409, { ok: false, error: "revision conflict", actualRevision: error.actualRevision });
+            }
+            if (error instanceof ExtensionSettingsBoundsError) {
+              return sendJson(res, 413, { ok: false, error: error.message });
+            }
+            throw error;
+          }
+        }
+
+        return sendJson(res, 405, { ok: false, error: "method not allowed" });
+      }
+
       if (method === "GET" && url.pathname === "/api/commands") {
         return sendJson(res, 200, { ok: true, commands: await sessionService.commands(resolveSessionId(url.searchParams.get("sessionId"))) });
       }
@@ -801,10 +842,19 @@ const server = createServer(async (req, res) => {
       }
 
       if (method === "POST" && (url.pathname === "/api/new-chat" || url.pathname === "/api/sessions/new")) {
-        const body = await readBody(req) as { cwd?: unknown; sessionId?: unknown };
+        const body = await readBody(req) as { cwd?: unknown; sessionId?: unknown; origin?: unknown };
         const baseState = await sessionService.create(resolveSessionId(body.sessionId), typeof body.cwd === "string" ? body.cwd : undefined);
         const state = await decorateServiceState(baseState);
         noteViewerLeaseFromRequest(req, await sessionService.require(state.sessionId));
+        const origin = body.origin && typeof body.origin === "object" ? body.origin as { sessionId?: unknown; kind?: unknown } : undefined;
+        if (origin && typeof origin.sessionId === "string" && origin.sessionId.trim() && state.sessionId) {
+          const sessionUiState = await sessionUiStateStore.setSessionOrigin(
+            state.sessionId,
+            origin.sessionId.trim(),
+            typeof origin.kind === "string" && origin.kind.trim() ? origin.kind.trim() : "spawn",
+          );
+          broadcast({ type: "session_ui_state_changed", sessionUiState });
+        }
         broadcast({ type: "state_changed", ...state });
         return sendJson(res, 200, { ok: true, ...state });
       }
diff --git a/server/extensionSettings.ts b/server/extensionSettings.ts
new file mode 100644
index 0000000..21cb278
--- /dev/null
+++ b/server/extensionSettings.ts
@@ -0,0 +1,265 @@
+/**
+ * Extension settings — canonical descriptor model + pure validation.
+ *
+ * Shared backbone for the generic pi-web extension-settings platform. Kept pure
+ * (no node/browser deps) so both the server (validation before persist) and the
+ * client (form rendering) can rely on the same contract. See
+ * `.pi/web/artifacts/worker-model-selection-plan.md` (Amendment 3).
+ */
+
+import type { JsonObject } from "./settings.js";
+
+export type FieldType = "toggle" | "text" | "textarea" | "number" | "select" | "list";
+
+export type SelectOption = { value: string; label?: string };
+
+export type FieldDescriptor = {
+  key: string;
+  type: FieldType;
+  label: string;
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  // number
+  min?: number;
+  max?: number;
+  // text / textarea
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string; // regex source, anchored implicitly by test()
+  // select
+  options?: SelectOption[];
+  optionsSource?: "models"; // dynamic; allowed set supplied at validation time
+  optionsFromField?: string; // "<listFieldKey>.<itemFieldKey>" cross-field reference
+  // list (repeater)
+  itemFields?: FieldDescriptor[];
+  minItems?: number;
+  maxItems?: number;
+  // per-column case-insensitive uniqueness inside a list
+  uniqueCaseInsensitive?: boolean;
+};
+
+export type SettingsSchema = {
+  id: string; // namespaced owner id
+  title: string;
+  schemaVersion: number;
+  fields: FieldDescriptor[];
+};
+
+export type ValidationError = { path: string; message: string };
+
+export type ValidateContext = {
+  /** Allowed values for `optionsSource: "models"` fields (canonical model tokens). */
+  modelOptions?: ReadonlySet<string>;
+};
+
+export type ValidateResult = { values: JsonObject; errors: ValidationError[] };
+
+/** Stable, function-free serialization for schema identity (R2.4). */
+export function canonicalSchemaKey(schema: SettingsSchema): string {
+  return stableStringify({
+    id: schema.id,
+    schemaVersion: schema.schemaVersion,
+    title: schema.title,
+    fields: schema.fields,
+  });
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined && typeof v !== "function")
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+let rowSeq = 0;
+function newRowId(): string {
+  rowSeq = (rowSeq + 1) % Number.MAX_SAFE_INTEGER;
+  return `r${Date.now().toString(36)}${rowSeq.toString(36)}`;
+}
+
+/** Default value for a single field. */
+function fieldDefault(field: FieldDescriptor): unknown {
+  if (field.default !== undefined) return field.default;
+  switch (field.type) {
+    case "toggle":
+      return false;
+    case "number":
+      return field.min ?? 0;
+    case "list":
+      return [];
+    default:
+      return "";
+  }
+}
+
+/** Fully-defaulted values object for a schema (used for empty state / reset). */
+export function defaultSettingsValues(schema: SettingsSchema): JsonObject {
+  const out: JsonObject = {};
+  for (const field of schema.fields) out[field.key] = fieldDefault(field);
+  return out;
+}
+
+function coerceScalar(field: FieldDescriptor, raw: unknown, path: string, errors: ValidationError[]): unknown {
+  switch (field.type) {
+    case "toggle":
+      return typeof raw === "boolean" ? raw : Boolean(raw);
+    case "number": {
+      const n = typeof raw === "number" ? raw : Number(raw);
+      if (!Number.isFinite(n)) {
+        errors.push({ path, message: `${field.label} must be a number` });
+        return typeof field.default === "number" ? field.default : (field.min ?? 0);
+      }
+      if (field.min !== undefined && n < field.min) errors.push({ path, message: `${field.label} must be ≥ ${field.min}` });
+      if (field.max !== undefined && n > field.max) errors.push({ path, message: `${field.label} must be ≤ ${field.max}` });
+      return n;
+    }
+    case "text":
+    case "textarea":
+    case "select": {
+      const s = typeof raw === "string" ? raw : raw === undefined || raw === null ? "" : String(raw);
+      const trimmed = field.type === "select" ? s.trim() : s;
+      if (field.required && !trimmed.trim()) errors.push({ path, message: `${field.label} is required` });
+      if (field.minLength !== undefined && trimmed.length < field.minLength) {
+        errors.push({ path, message: `${field.label} must be ≥ ${field.minLength} chars` });
+      }
+      if (field.maxLength !== undefined && trimmed.length > field.maxLength) {
+        errors.push({ path, message: `${field.label} must be ≤ ${field.maxLength} chars` });
+      }
+      if (field.pattern && trimmed) {
+        try {
+          if (!new RegExp(field.pattern).test(trimmed)) errors.push({ path, message: `${field.label} is invalid` });
+        } catch {
+          /* invalid pattern in descriptor — ignore */
+        }
+      }
+      return trimmed;
+    }
+    default:
+      return raw;
+  }
+}
+
+/** Resolve the allowed option set for a select field, if constrained. */
+function selectAllowed(
+  field: FieldDescriptor,
+  values: JsonObject,
+  ctx: ValidateContext | undefined,
+): ReadonlySet<string> | undefined {
+  if (field.options) return new Set(field.options.map((o) => o.value));
+  if (field.optionsSource === "models") return ctx?.modelOptions;
+  if (field.optionsFromField) {
+    const [listKey, itemKey] = field.optionsFromField.split(".");
+    const list = values[listKey];
+    if (!Array.isArray(list) || !itemKey) return new Set();
+    const set = new Set<string>();
+    for (const row of list) {
+      if (isRecord(row) && typeof row[itemKey] === "string") set.add(row[itemKey] as string);
+    }
+    return set;
+  }
+  return undefined;
+}
+
+/**
+ * Validate + coerce raw input against a schema. Never throws; returns coerced
+ * `values` (safe to persist even if `errors` is non-empty — the UI decides
+ * whether to block) plus accessible `{ path, message }` errors.
+ *
+ * Two-pass for lists: coerce all fields first (so `optionsFromField` can see the
+ * list), then validate cross-field references.
+ */
+export function validateSettingsValues(
+  schema: SettingsSchema,
+  input: unknown,
+  ctx?: ValidateContext,
+): ValidateResult {
+  const errors: ValidationError[] = [];
+  const src = isRecord(input) ? input : {};
+  const values: JsonObject = {};
+
+  // Pass 1: coerce every field to its shape.
+  for (const field of schema.fields) {
+    const raw = src[field.key];
+    if (field.type === "list") {
+      values[field.key] = coerceList(field, raw, field.key, errors);
+    } else if (field.type === "select") {
+      values[field.key] = coerceScalar(field, raw, field.key, errors); // option membership checked in pass 2
+    } else {
+      values[field.key] = coerceScalar(field, raw, field.key, errors);
+    }
+  }
+
+  // Pass 2: option membership (incl. cross-field), now that lists exist.
+  for (const field of schema.fields) {
+    if (field.type === "select") {
+      const allowed = selectAllowed(field, values, ctx);
+      const v = values[field.key];
+      if (allowed && typeof v === "string" && v && !allowed.has(v)) {
+        errors.push({ path: field.key, message: `${field.label} references an unavailable value` });
+      }
+    } else if (field.type === "list" && field.itemFields) {
+      const list = values[field.key] as JsonObject[];
+      list.forEach((row, i) => {
+        for (const item of field.itemFields!) {
+          if (item.type !== "select") continue;
+          const allowed = selectAllowed(item, values, ctx);
+          const v = row[item.key];
+          if (allowed && typeof v === "string" && v && !allowed.has(v)) {
+            errors.push({ path: `${field.key}[${i}].${item.key}`, message: `${item.label} references an unavailable value` });
+          }
+        }
+      });
+    }
+  }
+
+  return { values, errors };
+}
+
+function coerceList(field: FieldDescriptor, raw: unknown, path: string, errors: ValidationError[]): JsonObject[] {
+  const arr = Array.isArray(raw) ? raw : [];
+  const itemFields = field.itemFields ?? [];
+  const rows: JsonObject[] = arr.map((rawRow, i) => {
+    const row: JsonObject = {};
+    const rowSrc = isRecord(rawRow) ? rawRow : {};
+    // preserve/generate stable __id
+    row.__id = typeof rowSrc.__id === "string" && rowSrc.__id ? rowSrc.__id : newRowId();
+    for (const item of itemFields) {
+      row[item.key] = item.type === "list"
+        ? coerceList(item, rowSrc[item.key], `${path}[${i}].${item.key}`, errors)
+        : coerceScalar(item, rowSrc[item.key], `${path}[${i}].${item.key}`, errors);
+    }
+    return row;
+  });
+
+  if (field.minItems !== undefined && rows.length < field.minItems) {
+    errors.push({ path, message: `${field.label} needs at least ${field.minItems}` });
+  }
+  if (field.maxItems !== undefined && rows.length > field.maxItems) {
+    errors.push({ path, message: `${field.label} allows at most ${field.maxItems}` });
+  }
+
+  // per-column case-insensitive uniqueness
+  for (const item of itemFields) {
+    if (!item.uniqueCaseInsensitive) continue;
+    const seen = new Map<string, number>();
+    rows.forEach((row, i) => {
+      const v = row[item.key];
+      if (typeof v !== "string" || !v.trim()) return;
+      const norm = v.trim().toLowerCase();
+      if (seen.has(norm)) {
+        errors.push({ path: `${path}[${i}].${item.key}`, message: `${item.label} must be unique` });
+      } else {
+        seen.set(norm, i);
+      }
+    });
+  }
+
+  return rows;
+}
diff --git a/server/extensions/webUi.ts b/server/extensions/webUi.ts
index 11c8dc6..e97bdbb 100644
--- a/server/extensions/webUi.ts
+++ b/server/extensions/webUi.ts
@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
 import type { ExtensionUIDialogOptions, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import type { PiWebArtifactAction, PiWebFooter, PiWebGitTab, PiWebHeaderAction, PiWebUi } from "../../src/extensions.js";
+import type { PiWebArtifactAction, PiWebFooter, PiWebGitTab, PiWebHeaderAction, PiWebRegisterSettingsResult, PiWebSettingsRegistration, PiWebStoredSettings, PiWebUi } from "../../src/extensions.js";
+import type { createSettingsStore } from "../settings.js";
+import { canonicalSchemaKey, defaultSettingsValues, validateSettingsValues } from "../extensionSettings.js";
 
 export interface WebUiBridgeDependencies {
   emit(value: unknown): void;
@@ -9,6 +11,9 @@ export interface WebUiBridgeDependencies {
   createNewSession(cwd: string, previousSessionFile?: string): Promise<any>;
   sessionCwd(session: any): string;
   state(session: any): Record<string, unknown>;
+  settingsStore: ReturnType<typeof createSettingsStore>;
+  /** Allowed model tokens ("<provider>:<id>") for `optionsSource: "models"` fields. */
+  modelOptions(): Set<string>;
 }
 
 export function createWebUiBridge(deps: WebUiBridgeDependencies) {
@@ -54,6 +59,127 @@ const webHeaderActionStates = new WeakMap<object, WebHeaderActionState>();
 const webGitTabStates = new WeakMap<object, WebGitTabState>();
 const webArtifactActionStates = new WeakMap<object, WebArtifactActionState>();
 
+// Process-global extension-settings schema registry (R2.2): decoupled from any
+// one session. Values live in settingsStore (global); schemas are refcounted
+// across the live sessions that registered them.
+type RegisteredSettingsSchema = {
+  schema: PiWebSettingsRegistration;
+  canonicalKey: string;
+  refCount: number;
+};
+const activeSettingsSchemas = new Map<string, RegisteredSettingsSchema>();
+// Which owner ids each live session registered (for shutdown decrement).
+const sessionRegisteredSettings = new WeakMap<object, Set<string>>();
+
+function serializableSettingsSchema(schema: PiWebSettingsRegistration) {
+  const { migrate: _migrate, onChange: _onChange, ...rest } = schema;
+  return rest;
+}
+
+function activeSettingsSchemaList() {
+  return Array.from(activeSettingsSchemas.values()).map((e) => serializableSettingsSchema(e.schema));
+}
+
+function broadcastSettingsSchemas() {
+  deps.emit({ type: "web_settings_schemas_changed", webSettingsSchemas: activeSettingsSchemaList() });
+}
+
+async function migrateStoredSettings(
+  schema: PiWebSettingsRegistration,
+): Promise<{ migrated: boolean; usedBackup: boolean; error?: string }> {
+  const settings = await deps.settingsStore.read();
+  const stored = settings.extensions?.[schema.id];
+  if (!stored || stored.schemaVersion >= schema.schemaVersion) {
+    return { migrated: false, usedBackup: false };
+  }
+  const backup = { schemaVersion: stored.schemaVersion, values: stored.values };
+  const defaults = defaultSettingsValues(schema);
+  if (typeof schema.migrate === "function") {
+    try {
+      const migratedValues = await schema.migrate(stored.values, stored.schemaVersion);
+      const { values, errors } = validateSettingsValues(schema, migratedValues, { modelOptions: deps.modelOptions() });
+      if (errors.length) {
+        await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
+        return { migrated: false, usedBackup: true, error: `migration produced invalid values (${errors.length})` };
+      }
+      await deps.settingsStore.patchExtension(schema.id, values, { schemaVersion: schema.schemaVersion, backup });
+      return { migrated: true, usedBackup: false };
+    } catch (error) {
+      await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
+      return { migrated: false, usedBackup: true, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  // No migrate() provided: reset to defaults, keep a one-slot backup.
+  await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
+  return { migrated: false, usedBackup: true };
+}
+
+async function registerSessionSettings(
+  value: any,
+  schema: PiWebSettingsRegistration,
+): Promise<PiWebRegisterSettingsResult> {
+  if (!schema || typeof schema.id !== "string" || !Array.isArray(schema.fields)) {
+    return { registered: false, migrated: false, usedBackup: false, error: "invalid settings schema" };
+  }
+  const id = schema.id;
+  const canonical = canonicalSchemaKey(schema);
+  const existing = activeSettingsSchemas.get(id);
+  if (existing && existing.canonicalKey !== canonical) {
+    // First-registered wins; a divergent schema for the same id is rejected.
+    console.warn(`pi-web: settings id "${id}" already registered with a different schema; rejecting new registration.`);
+    return { registered: false, migrated: false, usedBackup: false, error: `settings id "${id}" already registered with a different schema` };
+  }
+
+  let migrated = false;
+  let usedBackup = false;
+  let error: string | undefined;
+  if (!existing) {
+    const result = await migrateStoredSettings(schema);
+    migrated = result.migrated;
+    usedBackup = result.usedBackup;
+    error = result.error;
+    activeSettingsSchemas.set(id, { schema, canonicalKey: canonical, refCount: 0 });
+  } else {
+    existing.schema = schema; // refresh callbacks to the latest registrant
+  }
+
+  const entry = activeSettingsSchemas.get(id)!;
+  const owned = sessionRegisteredSettings.get(value as object) ?? new Set<string>();
+  if (!owned.has(id)) {
+    entry.refCount += 1;
+    owned.add(id);
+    sessionRegisteredSettings.set(value as object, owned);
+  }
+  broadcastSettingsSchemas();
+  return { registered: true, migrated, usedBackup, error };
+}
+
+function releaseSessionSettings(value: any) {
+  const owned = sessionRegisteredSettings.get(value as object);
+  if (!owned) return;
+  let changed = false;
+  for (const id of owned) {
+    const entry = activeSettingsSchemas.get(id);
+    if (!entry) continue;
+    entry.refCount -= 1;
+    if (entry.refCount <= 0) {
+      activeSettingsSchemas.delete(id);
+      changed = true;
+    }
+  }
+  sessionRegisteredSettings.delete(value as object);
+  if (changed) broadcastSettingsSchemas();
+}
+
+async function getExtensionSettings(id: string): Promise<PiWebStoredSettings> {
+  const settings = await deps.settingsStore.read();
+  const stored = settings.extensions?.[id];
+  if (stored) return { schemaVersion: stored.schemaVersion, values: stored.values };
+  const entry = activeSettingsSchemas.get(id);
+  if (entry) return { schemaVersion: entry.schema.schemaVersion, values: defaultSettingsValues(entry.schema) };
+  return { schemaVersion: 0, values: {} };
+}
+
 function getWebFooterState(value: any): WebFooterState {
   const key = value as object;
   let state = webFooterStates.get(key);
@@ -247,6 +373,12 @@ function createPiWebUi(value: any): PiWebUi {
       }
       broadcastWebGitTabs(value);
     },
+    async registerSettings(schema) {
+      return registerSessionSettings(value, schema);
+    },
+    async getSettings(id) {
+      return getExtensionSettings(id);
+    },
   };
 }
 
@@ -509,5 +641,8 @@ async function bindWebExtensions(value: any) {
     invokeArtifactAction,
     invokeGitTab,
     respond,
+    settingsSchemas: activeSettingsSchemaList,
+    settingsSchemaEntry: (id: string) => activeSettingsSchemas.get(id),
+    releaseSessionSettings,
   };
 }
diff --git a/server/session/projection.ts b/server/session/projection.ts
index 81aa2a2..ac5c56f 100644
--- a/server/session/projection.ts
+++ b/server/session/projection.ts
@@ -108,6 +108,7 @@ export function simplifyMessage(
       toolName: m.toolName,
       toolArgs: args,
       isError: Boolean(m.isError),
+      ...(m.details !== undefined ? { details: m.details } : {}),
       text: textFromContent(m.content),
       timestamp: m.timestamp,
       raw: m,
diff --git a/server/session/service.ts b/server/session/service.ts
index 6eb1d72..3bf6d71 100644
--- a/server/session/service.ts
+++ b/server/session/service.ts
@@ -16,6 +16,7 @@ import { assertDirectory } from "../shared/fsList.js";
 import type { PiWebSession, PiWebSessionInfo } from "../types.js";
 import { createWebUiBridge } from "../extensions/webUi.js";
 import { ResilientResourceLoader } from "../extensions/resilientLoader.js";
+import { createSettingsStore } from "../settings.js";
 import type {
   BaseSessionStateDto,
   DeleteSessionResultDto,
@@ -163,6 +164,7 @@ export class LocalSessionService implements SessionService {
   private readonly pendingPromptCorrelations = new Map<string, PendingPromptCorrelation[]>();
   private readonly knownSessionCwds = new Set<string>();
   private readonly protectedSessionIds = new Set<string>();
+  readonly settingsStore = createSettingsStore(process.env.PI_WEB_SETTINGS_FILE || join(getAgentDir(), "pi-web-settings.json"));
   private readonly noSession = process.env.PI_WEB_NO_SESSION === "1";
   private readonly idleGraceMs = envMs("PI_WEB_SESSION_IDLE_GRACE_MS", 24 * 60 * 60 * 1000);
   private readonly viewerGraceMs = envMs("PI_WEB_VIEWER_LEASE_GRACE_MS", Math.min(30_000, this.idleGraceMs));
@@ -177,6 +179,8 @@ export class LocalSessionService implements SessionService {
       createNewSession: (cwd, previousSessionFile) => this.createNewLiveSession(cwd, previousSessionFile),
       sessionCwd: (session) => this.sessionCwd(session),
       state: (session) => this.projectState(session) as unknown as Record<string, unknown>,
+      settingsStore: this.settingsStore,
+      modelOptions: () => this.modelOptionTokens(),
     });
   }
 
@@ -232,6 +236,13 @@ export class LocalSessionService implements SessionService {
   }
   knownCwds() { return new Set([resolve(this.deps.globalCwd()), ...this.knownSessionCwds]); }
   webUiEntries(value: PiWebSession) { return this.webUiBridge.entries(value); }
+  settingsSchemas() { return this.webUiBridge.settingsSchemas(); }
+  settingsSchemaEntry(id: string) { return this.webUiBridge.settingsSchemaEntry(id); }
+  modelOptionTokens() {
+    return new Set(this.deps.modelRuntime.getAvailableSnapshot().flatMap((model) =>
+      model?.provider && model?.id ? [`${model.provider}:${model.id}`] : [],
+    ));
+  }
   projectState(value: PiWebSession): BaseSessionStateDto { return jsonSafe(projectSessionState(value, this.sessionCwd(value))); }
 
   private currentSession() {
@@ -800,6 +811,7 @@ export class LocalSessionService implements SessionService {
     catch (error) { console.warn(`Could not unsubscribe session before ${reason}:`, error); }
     try { (value as any).dispose?.(); }
     catch (error) { console.warn(`Could not dispose session after ${reason}:`, error); }
+    this.webUiBridge.releaseSessionSettings(value);
     this.liveSessions.delete(key);
     this.pendingPromptCorrelations.delete(key);
     if (this.liveById.get(sessionId) === value) this.liveById.delete(sessionId);
diff --git a/server/sessionUiState.ts b/server/sessionUiState.ts
index def2d9e..c0b6004 100644
--- a/server/sessionUiState.ts
+++ b/server/sessionUiState.ts
@@ -20,12 +20,25 @@ export type SessionUnreadState = {
   updatedAt: string;
 };
 
+/**
+ * Session creation provenance: records that `sessionId` was created by
+ * `originSessionId` (e.g. kind "spawn" for orchestrated workers, or future
+ * kinds like "continuation"). Written once at creation; immutable in spirit.
+ */
+export type SessionOrigin = {
+  sessionId: string;
+  originSessionId: string;
+  kind: string;
+  updatedAt: string;
+};
+
 export type SessionUiState = {
   version: 1;
   pinnedSessions: PinnedSession[];
   pinnedFolders: string[];
   sessionMarkers: SessionMarker[];
   sessionUnreadStates: SessionUnreadState[];
+  sessionOrigins: SessionOrigin[];
   selectedMarkerColor: SessionMarkerColorId;
   allowedMarkerColors: SessionMarkerColorId[];
 };
@@ -35,6 +48,7 @@ export type SessionUiStatePatch = Partial<{
   pinnedFolders: unknown;
   sessionMarkers: unknown;
   sessionUnreadStates: unknown;
+  sessionOrigins: unknown;
   selectedMarkerColor: unknown;
   allowedMarkerColors: unknown;
 }>;
@@ -54,6 +68,7 @@ export const defaultSessionUiState: SessionUiState = {
   pinnedFolders: [],
   sessionMarkers: [],
   sessionUnreadStates: [],
+  sessionOrigins: [],
   selectedMarkerColor: "blue",
   allowedMarkerColors: [],
 };
@@ -116,6 +131,16 @@ function normalizeSessionUnreadState(value: unknown): SessionUnreadState | undef
   return { sessionId, unreadAt, updatedAt };
 }
 
+function normalizeSessionOrigin(value: unknown): SessionOrigin | undefined {
+  if (!isRecord(value)) return undefined;
+  const sessionId = typeof value.sessionId === "string" ? value.sessionId.trim() : "";
+  const originSessionId = typeof value.originSessionId === "string" ? value.originSessionId.trim() : "";
+  const kind = typeof value.kind === "string" && value.kind.trim() ? value.kind.trim() : "spawn";
+  if (!sessionId || !originSessionId || sessionId === originSessionId) return undefined;
+  const updatedAt = typeof value.updatedAt === "string" && value.updatedAt.trim() ? value.updatedAt.trim() : new Date().toISOString();
+  return { sessionId, originSessionId, kind, updatedAt };
+}
+
 function uniqueBy<T>(items: T[], key: (item: T) => string) {
   const seen = new Set<string>();
   const result: T[] = [];
@@ -148,6 +173,10 @@ export function normalizeSessionUiState(value: unknown): SessionUiState {
     state.sessionUnreadStates = uniqueBy(value.sessionUnreadStates.map(normalizeSessionUnreadState).filter(Boolean) as SessionUnreadState[], (item) => item.sessionId);
   }
 
+  if (Array.isArray(value.sessionOrigins)) {
+    state.sessionOrigins = uniqueBy(value.sessionOrigins.map(normalizeSessionOrigin).filter(Boolean) as SessionOrigin[], (item) => item.sessionId);
+  }
+
   state.selectedMarkerColor = normalizeMarkerColor(value.selectedMarkerColor) || state.selectedMarkerColor;
   state.allowedMarkerColors = normalizeMarkerColors(value.allowedMarkerColors);
   return state;
@@ -173,6 +202,10 @@ export function applySessionUiStatePatch(current: SessionUiState, patch: unknown
     next.sessionUnreadStates = uniqueBy(patch.sessionUnreadStates.map(normalizeSessionUnreadState).filter(Boolean) as SessionUnreadState[], (item) => item.sessionId);
   }
 
+  if ("sessionOrigins" in patch && Array.isArray(patch.sessionOrigins)) {
+    next.sessionOrigins = uniqueBy(patch.sessionOrigins.map(normalizeSessionOrigin).filter(Boolean) as SessionOrigin[], (item) => item.sessionId);
+  }
+
   const selectedMarkerColor = normalizeMarkerColor(patch.selectedMarkerColor);
   if (selectedMarkerColor) next.selectedMarkerColor = selectedMarkerColor;
 
@@ -245,6 +278,16 @@ export function createSessionUiStateStore(file: string) {
     });
   }
 
+  async function setSessionOrigin(sessionId: string, originSessionId: string, kind = "spawn") {
+    const origin = normalizeSessionOrigin({ sessionId, originSessionId, kind });
+    if (!origin) return read();
+    return serializeWrite(async () => {
+      const current = await read();
+      const sessionOrigins = [origin, ...current.sessionOrigins.filter((item) => item.sessionId !== origin.sessionId)];
+      return writeState({ ...current, sessionOrigins });
+    });
+  }
+
   async function removeSession(sessionId: string) {
     return serializeWrite(async () => {
       const current = await read();
@@ -253,9 +296,10 @@ export function createSessionUiStateStore(file: string) {
         pinnedSessions: current.pinnedSessions.filter((item) => item.id !== sessionId),
         sessionMarkers: current.sessionMarkers.filter((item) => item.sessionId !== sessionId),
         sessionUnreadStates: current.sessionUnreadStates.filter((item) => item.sessionId !== sessionId),
+        sessionOrigins: current.sessionOrigins.filter((item) => item.sessionId !== sessionId && item.originSessionId !== sessionId),
       });
     });
   }
 
-  return { file, read, write, patch, markUnread, markRead, removeSession };
+  return { file, read, write, patch, markUnread, markRead, removeSession, setSessionOrigin };
 }
diff --git a/server/settings.ts b/server/settings.ts
index f8c8b4c..31f0154 100644
--- a/server/settings.ts
+++ b/server/settings.ts
@@ -6,6 +6,52 @@ export type PiWebModelSetting = {
   id: string;
 };
 
+/** A plain JSON object (no functions/undefined at the top level after round-trip). */
+export type JsonObject = Record<string, unknown>;
+
+/**
+ * Canonical persisted shape for one extension-owned settings record.
+ * `backup` lives OUTSIDE `values` so descriptor validation of user fields can
+ * never collide with it. `revision` powers the optimistic write guard.
+ */
+export type StoredExtensionSettings = {
+  schemaVersion: number;
+  revision: number;
+  values: JsonObject;
+  backup?: { schemaVersion: number; values: JsonObject };
+};
+
+export const extensionSettingsLimits = {
+  maxOwners: 32,
+  maxKeysPerOwner: 128,
+  /** Serialized bytes for one owner record (values + backup counted together). */
+  maxBytesPerOwner: 64 * 1024,
+} as const;
+
+/** Namespaced owner id: `<extensionName>.<schemaId>` (at least one dot). */
+const ownerIdPattern = /^[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)+$/;
+export function isValidExtensionOwnerId(id: unknown): id is string {
+  return typeof id === "string" && id.length <= 128 && ownerIdPattern.test(id);
+}
+
+export class ExtensionSettingsBoundsError extends Error {
+  constructor(public readonly ownerId: string, message: string) {
+    super(message);
+    this.name = "ExtensionSettingsBoundsError";
+  }
+}
+
+export class ExtensionRevisionConflictError extends Error {
+  constructor(
+    public readonly ownerId: string,
+    public readonly actualRevision: number,
+    public readonly expectedRevision: number,
+  ) {
+    super(`revision conflict for ${ownerId}: expected ${expectedRevision}, found ${actualRevision}`);
+    this.name = "ExtensionRevisionConflictError";
+  }
+}
+
 export type SessionMarkerColorId = "blue" | "purple" | "yellow" | "red" | "green";
 
 const sessionMarkerColors = new Set<SessionMarkerColorId>(["blue", "purple", "yellow", "red", "green"]);
@@ -33,6 +79,13 @@ export type PiWebSettings = {
     thinkingLevel?: string;
     sessionBucketColor?: SessionMarkerColorId;
   };
+  /**
+   * Extension-contributed settings, keyed by namespaced owner id. Carried
+   * through verbatim (bounds-only) so an absent/unregistered extension never
+   * loses its config. Field-level validation happens server-side against the
+   * live `activeSchemas` registry, not here.
+   */
+  extensions?: Record<string, StoredExtensionSettings>;
 };
 
 export type PiWebSettingsPatch = Partial<{
@@ -74,6 +127,119 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+function serializedBytes(value: unknown): number | undefined {
+  try {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string") return undefined;
+    return Buffer.byteLength(json);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Coerce one raw owner record into canonical shape, or undefined if unusable. */
+function normalizeStoredExtension(value: unknown): StoredExtensionSettings | undefined {
+  if (!isRecord(value) || !isRecord(value.values)) return undefined;
+  const record: StoredExtensionSettings = {
+    schemaVersion: Number.isFinite(value.schemaVersion) ? Number(value.schemaVersion) : 0,
+    revision: Number.isFinite(value.revision) ? Number(value.revision) : 0,
+    values: value.values,
+  };
+  if (isRecord(value.backup) && isRecord(value.backup.values)) {
+    record.backup = {
+      schemaVersion: Number.isFinite(value.backup.schemaVersion) ? Number(value.backup.schemaVersion) : 0,
+      values: value.backup.values,
+    };
+  }
+  // Bounds: drop the owner rather than corrupt it.
+  if (Object.keys(record.values).length > extensionSettingsLimits.maxKeysPerOwner) return undefined;
+  const bytes = serializedBytes(record);
+  if (bytes === undefined || bytes > extensionSettingsLimits.maxBytesPerOwner) return undefined;
+  return record;
+}
+
+/** Preserve-verbatim (bounds-only) normalization for the extensions blob. */
+export function normalizeExtensionSettings(value: unknown): Record<string, StoredExtensionSettings> | undefined {
+  if (!isRecord(value)) return undefined;
+  const out: Record<string, StoredExtensionSettings> = {};
+  let count = 0;
+  for (const [id, raw] of Object.entries(value)) {
+    if (count >= extensionSettingsLimits.maxOwners) break;
+    if (!isValidExtensionOwnerId(id)) continue;
+    const record = normalizeStoredExtension(raw);
+    if (!record) continue;
+    out[id] = record;
+    count += 1;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/** Throw if a to-be-written owner record would exceed bounds. */
+function assertOwnerWithinBounds(ownerId: string, record: StoredExtensionSettings): void {
+  if (Object.keys(record.values).length > extensionSettingsLimits.maxKeysPerOwner) {
+    throw new ExtensionSettingsBoundsError(ownerId, `too many keys (max ${extensionSettingsLimits.maxKeysPerOwner})`);
+  }
+  const bytes = serializedBytes(record);
+  if (bytes === undefined) {
+    throw new ExtensionSettingsBoundsError(ownerId, "values are not JSON-serializable");
+  }
+  if (bytes > extensionSettingsLimits.maxBytesPerOwner) {
+    throw new ExtensionSettingsBoundsError(ownerId, `too large (${bytes} > ${extensionSettingsLimits.maxBytesPerOwner} bytes)`);
+  }
+}
+
+/**
+ * Write validated `values` for one owner, bumping `revision`. Field validation
+ * is the caller's responsibility (done against the live schema). Optionally
+ * enforces an optimistic revision guard and/or writes a migration backup.
+ */
+export function applyExtensionValues(
+  current: PiWebSettings,
+  ownerId: string,
+  nextValues: JsonObject,
+  opts?: {
+    schemaVersion?: number;
+    expectedRevision?: number;
+    backup?: { schemaVersion: number; values: JsonObject };
+  },
+): PiWebSettings {
+  if (!isValidExtensionOwnerId(ownerId)) {
+    throw new ExtensionSettingsBoundsError(String(ownerId), "owner id must be namespaced (<ext>.<schema>)");
+  }
+  const next = cloneSettings(current);
+  const existing = next.extensions?.[ownerId];
+  if (
+    opts?.expectedRevision !== undefined &&
+    existing !== undefined &&
+    existing.revision !== opts.expectedRevision
+  ) {
+    throw new ExtensionRevisionConflictError(ownerId, existing.revision, opts.expectedRevision);
+  }
+  const record: StoredExtensionSettings = {
+    schemaVersion: opts?.schemaVersion ?? existing?.schemaVersion ?? 0,
+    revision: (existing?.revision ?? 0) + 1,
+    values: nextValues,
+  };
+  const backup = opts?.backup ?? existing?.backup;
+  if (backup) record.backup = backup;
+  assertOwnerWithinBounds(ownerId, record);
+  next.extensions = { ...(next.extensions ?? {}), [ownerId]: record };
+  if (Object.keys(next.extensions).length > extensionSettingsLimits.maxOwners) {
+    throw new ExtensionSettingsBoundsError(ownerId, `too many extension owners (max ${extensionSettingsLimits.maxOwners})`);
+  }
+  return normalizeSettings(next);
+}
+
+/** Drop one owner's stored record entirely (reset). */
+export function resetExtensionValues(current: PiWebSettings, ownerId: string): PiWebSettings {
+  const next = cloneSettings(current);
+  if (next.extensions && ownerId in next.extensions) {
+    delete next.extensions[ownerId];
+    if (Object.keys(next.extensions).length === 0) delete next.extensions;
+  }
+  return normalizeSettings(next);
+}
+
 function normalizeModel(value: unknown) {
   if (!isRecord(value)) return undefined;
   const provider = typeof value.provider === "string" ? value.provider.trim() : "";
@@ -130,6 +296,9 @@ export function normalizeSettings(value: unknown): PiWebSettings {
   const sessionBucketColor = normalizeSessionBucketColor(defaults?.sessionBucketColor);
   if (sessionBucketColor) settings.defaults.sessionBucketColor = sessionBucketColor;
 
+  const extensions = normalizeExtensionSettings(value.extensions);
+  if (extensions) settings.extensions = extensions;
+
   return settings;
 }
 
@@ -206,5 +375,27 @@ export function createSettingsStore(file: string) {
     return write(applySettingsPatch(await read(), value));
   }
 
-  return { file, read, write, patch };
+  return { file, read, write, patch, patchExtension, resetExtension };
+
+  /**
+   * Persist already-validated `values` for one extension owner. Field-level
+   * validation must be done by the caller against the live schema; this only
+   * enforces bounds + the optional revision guard, then writes.
+   */
+  async function patchExtension(
+    ownerId: string,
+    nextValues: JsonObject,
+    opts?: {
+      schemaVersion?: number;
+      expectedRevision?: number;
+      backup?: { schemaVersion: number; values: JsonObject };
+    },
+  ) {
+    return write(applyExtensionValues(await read(), ownerId, nextValues, opts));
+  }
+
+  /** Drop one owner's stored record (reset to unconfigured). */
+  async function resetExtension(ownerId: string) {
+    return write(resetExtensionValues(await read(), ownerId));
+  }
 }
diff --git a/src/app/elements.ts b/src/app/elements.ts
index a04caf3..c345192 100644
--- a/src/app/elements.ts
+++ b/src/app/elements.ts
@@ -81,6 +81,7 @@ export type AppElements = {
   extensionStatusDetails: HTMLDivElement;
   extensionReloadButton: HTMLButtonElement;
   settingsStatusEl: HTMLSpanElement;
+  extensionSettingsContainer: HTMLElement;
   tokenShareSection: HTMLElement;
   tokenShareQr: HTMLDivElement;
   tokenShareUrl: HTMLInputElement;
@@ -185,6 +186,7 @@ export function getAppElements(): AppElements {
     extensionStatusDetails: requiredElement<HTMLDivElement>("#extensionStatusDetails"),
     extensionReloadButton: requiredElement<HTMLButtonElement>("#extensionReloadButton"),
     settingsStatusEl: requiredElement<HTMLSpanElement>("#settingsStatus"),
+    extensionSettingsContainer: requiredElement<HTMLElement>("#extensionSettingsContainer"),
     tokenShareSection: requiredElement<HTMLElement>("#tokenShareSection"),
     tokenShareQr: requiredElement<HTMLDivElement>("#tokenShareQr"),
     tokenShareUrl: requiredElement<HTMLInputElement>("#tokenShareUrl"),
diff --git a/src/app/icons.ts b/src/app/icons.ts
index 0dce8e7..4c3f8ba 100644
--- a/src/app/icons.ts
+++ b/src/app/icons.ts
@@ -1,7 +1,8 @@
-import { ArrowLeft, Bookmark, Brain, Check, Copy, CornerDownRight, createElement, Flag, FolderTree, Funnel, GitBranch, GitFork, Info, KeyRound, Maximize2, Minimize2, Menu, MoreVertical, Paperclip, Pin, RotateCcw, Route, ScrollText, SendHorizontal, Settings, Square, SquarePen, Star, Trash2, X } from "lucide";
+import { ArrowLeft, Bell, Bookmark, Brain, Check, Copy, CornerDownRight, createElement, Flag, FolderTree, Funnel, GitBranch, GitFork, Hourglass, Info, KeyRound, Maximize2, Minimize2, Menu, MoreVertical, Paperclip, Pin, RotateCcw, Route, ScrollText, SendHorizontal, Settings, Square, SquarePen, Star, Trash2, X } from "lucide";
 
 const iconNodes = {
   "arrow-left": ArrowLeft,
+  bell: Bell,
   bookmark: Bookmark,
   brain: Brain,
   check: Check,
@@ -13,6 +14,7 @@ const iconNodes = {
   "git-branch": GitBranch,
   "git-fork": GitFork,
   info: Info,
+  hourglass: Hourglass,
   "key-round": KeyRound,
   menu: Menu,
   "more-vertical": MoreVertical,
diff --git a/src/app/types.ts b/src/app/types.ts
index 424018e..f9d266f 100644
--- a/src/app/types.ts
+++ b/src/app/types.ts
@@ -91,8 +91,46 @@ export type PiWebSettings = {
     thinkingLevel?: string;
     sessionBucketColor?: SessionMarkerColorId;
   };
+  extensions?: Record<string, StoredExtensionSettings>;
 };
 
+// --- Extension-contributed settings (generic platform), client mirror ---
+export type WebFieldType = "toggle" | "text" | "textarea" | "number" | "select" | "list";
+export type WebSelectOption = { value: string; label?: string };
+export type WebFieldDescriptor = {
+  key: string;
+  type: WebFieldType;
+  label: string;
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  options?: WebSelectOption[];
+  optionsSource?: "models";
+  optionsFromField?: string;
+  itemFields?: WebFieldDescriptor[];
+  minItems?: number;
+  maxItems?: number;
+  uniqueCaseInsensitive?: boolean;
+};
+export type WebSettingsSchema = {
+  id: string;
+  title: string;
+  schemaVersion: number;
+  fields: WebFieldDescriptor[];
+};
+export type StoredExtensionSettings = {
+  schemaVersion: number;
+  revision: number;
+  values: Record<string, unknown>;
+  backup?: { schemaVersion: number; values: Record<string, unknown> };
+};
+export type WebSettingsValidationError = { path: string; message: string };
+
 export type AttachedImage = {
   data?: string;
   mimeType?: string;
@@ -104,12 +142,14 @@ export type SessionMarkerColorId = "blue" | "purple" | "yellow" | "red" | "green
 export type SessionMarkerColor = { id: SessionMarkerColorId; label: string };
 export type SessionMarker = { sessionId: string; color: SessionMarkerColorId; note?: string; updatedAt: string };
 export type SessionUnreadState = { sessionId: string; unreadAt: string; updatedAt: string };
+export type SessionOrigin = { sessionId: string; originSessionId: string; kind: string; updatedAt: string };
 export type SessionUiState = {
   version: 1;
   pinnedSessions: PinnedSession[];
   pinnedFolders: string[];
   sessionMarkers: SessionMarker[];
   sessionUnreadStates: SessionUnreadState[];
+  sessionOrigins: SessionOrigin[];
   selectedMarkerColor: SessionMarkerColorId;
   allowedMarkerColors: SessionMarkerColorId[];
 };
@@ -128,6 +168,7 @@ export const defaultSessionUiState: SessionUiState = {
   pinnedFolders: [],
   sessionMarkers: [],
   sessionUnreadStates: [],
+  sessionOrigins: [],
   selectedMarkerColor: "blue",
   allowedMarkerColors: [],
 };
@@ -220,6 +261,21 @@ export function normalizeMarkerColors(value: unknown): SessionMarkerColorId[] {
   return result;
 }
 
+export function normalizeSessionOrigins(value: unknown): SessionOrigin[] {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set<string>();
+  const result: SessionOrigin[] = [];
+  for (const item of value) {
+    const sessionId = typeof item?.sessionId === "string" ? item.sessionId.trim() : "";
+    const originSessionId = typeof item?.originSessionId === "string" ? item.originSessionId.trim() : "";
+    if (!sessionId || !originSessionId || sessionId === originSessionId || seen.has(sessionId)) continue;
+    seen.add(sessionId);
+    const kind = typeof item?.kind === "string" && item.kind.trim() ? item.kind.trim() : "spawn";
+    result.push({ sessionId, originSessionId, kind, updatedAt: typeof item?.updatedAt === "string" ? item.updatedAt : new Date().toISOString() });
+  }
+  return result;
+}
+
 export function normalizeSessionUiState(value: unknown): SessionUiState {
   const raw = value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
   return {
@@ -228,6 +284,7 @@ export function normalizeSessionUiState(value: unknown): SessionUiState {
     pinnedFolders: normalizePinnedFolders(raw.pinnedFolders),
     sessionMarkers: normalizeSessionMarkers(raw.sessionMarkers),
     sessionUnreadStates: normalizeSessionUnreadStates(raw.sessionUnreadStates),
+    sessionOrigins: normalizeSessionOrigins(raw.sessionOrigins),
     selectedMarkerColor: normalizeMarkerColor(raw.selectedMarkerColor) || defaultSessionUiState.selectedMarkerColor,
     allowedMarkerColors: normalizeMarkerColors(raw.allowedMarkerColors),
   };
@@ -319,6 +376,7 @@ export type AppState = {
   pinnedFolders: string[];
   sessionMarkers: SessionMarker[];
   sessionUnreadStates: SessionUnreadState[];
+  sessionOrigins: SessionOrigin[];
   selectedMarkerColor: SessionMarkerColorId;
   collapsedSessionFolders: Set<string>;
   expandedSessionFolders: Set<string>;
@@ -326,6 +384,7 @@ export type AppState = {
   attachedImages: ImageAttachment[];
   editorExpanded: boolean;
   settings: PiWebSettings;
+  webSettingsSchemas: WebSettingsSchema[];
 };
 
 export const reconnectDelayMs = 1500;
@@ -424,6 +483,7 @@ export function createAppState(): AppState {
     pinnedFolders: [],
     sessionMarkers: readLegacySessionMarkers(),
     sessionUnreadStates: [],
+    sessionOrigins: [],
     selectedMarkerColor: readLegacySelectedMarkerColor() || defaultSessionUiState.selectedMarkerColor,
     collapsedSessionFolders: new Set(readCollapsedSessionFolders()),
     expandedSessionFolders: new Set(),
@@ -431,6 +491,7 @@ export function createAppState(): AppState {
     attachedImages: [],
     editorExpanded: defaultPiWebSettings.composer.expanded,
     settings: defaultPiWebSettings,
+    webSettingsSchemas: [],
   };
 }
 
diff --git a/src/extensions.ts b/src/extensions.ts
index 0f04b49..63812d5 100644
--- a/src/extensions.ts
+++ b/src/extensions.ts
@@ -100,6 +100,63 @@ export type PiWebGitTab = {
   render: (event?: PiWebGitTabEvent) => Promise<PiWebGitTabView> | PiWebGitTabView;
 };
 
+// --- Extension-contributed settings (generic platform) ---
+
+export type PiWebFieldType = "toggle" | "text" | "textarea" | "number" | "select" | "list";
+
+export type PiWebSelectOption = { value: string; label?: string };
+
+export type PiWebFieldDescriptor = {
+  key: string;
+  type: PiWebFieldType;
+  label: string;
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  /** number */
+  min?: number;
+  max?: number;
+  /** text / textarea */
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  /** select */
+  options?: PiWebSelectOption[];
+  optionsSource?: "models";
+  optionsFromField?: string; // "<listKey>.<itemKey>"
+  /** list (repeater) */
+  itemFields?: PiWebFieldDescriptor[];
+  minItems?: number;
+  maxItems?: number;
+  uniqueCaseInsensitive?: boolean;
+};
+
+export type PiWebSettingsSchema = {
+  id: string; // namespaced owner id: <extension>.<schema>
+  title: string;
+  schemaVersion: number;
+  fields: PiWebFieldDescriptor[];
+};
+
+export type PiWebStoredSettings = { schemaVersion: number; values: Record<string, unknown> };
+
+export type PiWebSettingsRegistration = PiWebSettingsSchema & {
+  /** Run when stored.schemaVersion < schemaVersion. Return migrated values. */
+  migrate?: (
+    oldValues: Record<string, unknown>,
+    oldVersion: number,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /** Called after a persisted change (this owner only), with the new values. */
+  onChange?: (values: Record<string, unknown>) => void;
+};
+
+export type PiWebRegisterSettingsResult = {
+  registered: boolean;
+  migrated: boolean;
+  usedBackup: boolean;
+  error?: string;
+};
+
 export type PiWebUi = {
   /**
    * Set or clear a pi-web footer region.
@@ -120,6 +177,17 @@ export type PiWebUi = {
 
   /** Set or clear a provider-specific tab in the built-in Git panel. */
   setGitTab(key: string, tab: PiWebGitTab | undefined): void;
+
+  /**
+   * Register a settings schema contributed by this extension. Idempotent per
+   * session (re-registering the same canonical schema just refreshes callbacks).
+   * Awaits any schema-version migration. Values persist globally and outlive the
+   * session; the live registration is torn down on session shutdown.
+   */
+  registerSettings(schema: PiWebSettingsRegistration): Promise<PiWebRegisterSettingsResult>;
+
+  /** Read this owner's persisted settings (defaults if unset). */
+  getSettings(id: string): Promise<PiWebStoredSettings>;
 };
 
 export type PiWebExtensionUIContext = ExtensionUIContext & {
diff --git a/src/main.ts b/src/main.ts
index 33f42f7..af35042 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -385,6 +385,7 @@ async function refreshState() {
   }
   sessionState.applySnapshot(data, { activate: true });
   syncActiveSessionIdHistoryState(state.currentSessionId);
+  statusBar.updateWaitingStatus(sessions.waitingInfoFor(state.currentSessionId || ""));
   const [settingsResult, modelsResult, messagesResult] = await Promise.allSettled([
     settings.refreshSettings(),
     modelSettings.refreshModels(),
@@ -452,6 +453,7 @@ sessions = createSessions({
   refreshMessages,
   refreshState,
   refreshSessionTitle: () => statusBar.refreshSessionTitle(),
+  onDerivedSessionStateChanged: () => statusBar.updateWaitingStatus(sessions.waitingInfoFor(state.currentSessionId || "")),
   clearMessages: () => {
     tools.clearActiveToolCards();
     messages.clear();
diff --git a/src/messages/messageList.ts b/src/messages/messageList.ts
index 19554d3..4482392 100644
--- a/src/messages/messageList.ts
+++ b/src/messages/messageList.ts
@@ -675,6 +675,102 @@ export function createMessageList(options: {
     return text.split(/\s+/).filter(Boolean).length;
   }
 
+  // ── Custom (extension-injected) message cards ───────────────────────────
+  // pi custom messages reach the LLM as user messages; here they render as a
+  // distinct notification card. `details` may carry structured session
+  // references (e.g. spawned workers) which render as link chips.
+
+  function prettyCustomType(customType: string) {
+    const text = (customType || "notification").replace(/[-_]+/g, " ").trim();
+    return text.charAt(0).toUpperCase() + text.slice(1);
+  }
+
+  function customDetailSessionRefs(details: unknown): Array<{ sessionId: string; name?: string; status?: string }> {
+    if (!details || typeof details !== "object") return [];
+    const refs: Array<{ sessionId: string; name?: string; status?: string }> = [];
+    const push = (value: unknown) => {
+      if (!value || typeof value !== "object") return;
+      const record = value as Record<string, unknown>;
+      const sessionId = typeof record.sessionId === "string" ? record.sessionId.trim() : "";
+      if (!sessionId) return;
+      refs.push({
+        sessionId,
+        name: typeof record.name === "string" && record.name.trim() ? record.name.trim() : undefined,
+        status: typeof record.status === "string" ? record.status : undefined,
+      });
+    };
+    const record = details as Record<string, unknown>;
+    if (Array.isArray(record.workers)) for (const worker of record.workers) push(worker);
+    else if (Array.isArray(record.sessions)) for (const item of record.sessions) push(item);
+    else push(record);
+    return refs;
+  }
+
+  function addCustomMessageCard(message: { text?: string; customType?: string; details?: unknown; isError?: boolean; raw?: any }) {
+    invalidatePendingRefreshes();
+    const text = String(message.text || "").trim();
+    const customType = message.customType || message.raw?.customType || "";
+    const details = message.details ?? message.raw?.details;
+    const sessionRefs = customDetailSessionRefs(details);
+
+    // Realtime projection can briefly emit a details-only copy of a custom
+    // worker event after its complete transcript entry has already rendered.
+    // Avoid leaving a duplicate, empty bordered strip in the conversation.
+    if (!text && sessionRefs.length) {
+      const refIds = new Set(sessionRefs.map((ref) => ref.sessionId));
+      const existing = Array.from(messagesEl.querySelectorAll<HTMLDivElement>(".customCard"))
+        .find((card) => (card.dataset.sessionRefs || "").split(",").some((id) => refIds.has(id)));
+      if (existing) return existing;
+    }
+
+    const div = document.createElement("div");
+    div.dataset.sessionRefs = sessionRefs.map((ref) => ref.sessionId).join(",");
+    const collapsible = shouldCollapseMessage(text);
+    div.className = `message custom customCard${collapsible ? " collapsible collapsed" : ""}${message.isError ? " error" : ""}`;
+
+    const header = document.createElement("div");
+    header.className = "customCardHeader";
+    header.append(iconElement("bell"));
+    const label = document.createElement("span");
+    label.className = "customCardLabel";
+    label.textContent = prettyCustomType(customType);
+    label.title = customType ? `Injected by extension (${customType})` : "Injected by extension";
+    header.append(label);
+
+    for (const ref of sessionRefs) {
+      const chip = document.createElement("a");
+      chip.className = `customCardSessionChip${ref.status === "error" ? " status-error" : ref.status === "aborted" ? " status-aborted" : ""}`;
+      chip.href = `/?sessionId=${encodeURIComponent(ref.sessionId)}`;
+      const statusIcon = ref.status === "error" ? "⚠" : ref.status === "aborted" ? "⏹" : "✓";
+      chip.textContent = `${statusIcon} ${ref.name || ref.sessionId.slice(-8)} ↗`;
+      chip.title = `Open session ${ref.sessionId}`;
+      header.append(chip);
+    }
+    div.append(header);
+
+    const body = document.createElement("div");
+    body.className = "body";
+    body.textContent = text;
+    if (text) markdown.renderAssistantMarkdown(body, text);
+    div.append(body);
+
+    if (collapsible) {
+      const toggle = document.createElement("button");
+      toggle.type = "button";
+      toggle.className = "messageToggle";
+      toggle.textContent = "Show more";
+      toggle.addEventListener("click", () => {
+        const collapsed = div.classList.toggle("collapsed");
+        toggle.textContent = collapsed ? "Show more" : "Show less";
+      });
+      div.append(toggle);
+    }
+
+    messagesEl.append(div);
+    scrollToBottom();
+    return div;
+  }
+
   function renderThinkingBody(body: HTMLElement, text: string) {
     body.replaceChildren();
     for (const segment of thinkingTextSegments(text)) {
@@ -995,10 +1091,10 @@ export function createMessageList(options: {
         return;
       }
       case "custom": {
-        const text = messageText(message);
-        if (!text) return;
-        const customType = message.customType.replace(/[^a-zA-Z0-9_-]+/g, "-");
-        addMessage("system", text, `custom${customType ? ` custom--${customType}` : ""}`, [], { entryId: message.entryId });
+        // Extension-injected custom messages render as a rich notification card
+        // (with session-link chips from `details`), not a plain system message.
+        // Non-display customs are already filtered out by the projection.
+        addCustomMessageCard(message);
         return;
       }
       default:
diff --git a/src/realtime/realtime.ts b/src/realtime/realtime.ts
index f575a14..e50d12e 100644
--- a/src/realtime/realtime.ts
+++ b/src/realtime/realtime.ts
@@ -736,6 +736,9 @@ export function createRealtime(options: {
         if (key && (!data.runtime?.isRunning || typeof data.runtime?.startedAt === "string")) terminalRuntimeSessions.delete(key);
         if (!data.sessionId) return;
         const transition = sessionState.replaceRuntime(String(data.sessionId), data.runtime);
+        // Any runtime change (including a spawned child's) can flip the
+        // current session's derived "waiting on spawned sessions" state.
+        status.updateWaitingStatus(sessions.waitingInfoFor(state.currentSessionId || ""));
         if (transition.isActive && transition.previous.isRunning && !transition.next.isRunning) {
           refreshMessages()
             .then(() => {
@@ -761,8 +764,13 @@ export function createRealtime(options: {
         settings.applySettings(data.settings);
         return;
       }
+      if (data.type === "web_settings_schemas_changed") {
+        settings.applyWebSettingsSchemas(data.webSettingsSchemas);
+        return;
+      }
       if (data.type === "session_ui_state_changed") {
         sessions.applySessionUiState(data.sessionUiState);
+        status.updateWaitingStatus(sessions.waitingInfoFor(state.currentSessionId || ""));
         return;
       }
       if (data.type === "extension_ui_request") {
diff --git a/src/sessions/sessionDrawer.ts b/src/sessions/sessionDrawer.ts
index 68cd46b..b96cd52 100644
--- a/src/sessions/sessionDrawer.ts
+++ b/src/sessions/sessionDrawer.ts
@@ -29,6 +29,7 @@ export type SessionsController = {
   renderCurrentSessionBucketButton: () => void;
   applySessionUiState: (value: unknown) => void;
   markSessionRead: (sessionId?: string) => Promise<void>;
+  waitingInfoFor: (sessionId: string) => { count: number; names: string[] } | undefined;
 };
 
 function formatRelativeTime(value: string) {
@@ -92,6 +93,17 @@ function shouldCloseDrawerAfterSessionSwitch() {
 const knownSessionCwdsStorageKey = "pi-web-known-session-cwds";
 const sessionDrawerOpenStorageKey = "pi-web-session-drawer-open";
 
+type SessionTimeField = "created" | "modified";
+type SessionTimeRange = "all" | "day" | "week" | "month" | "year";
+
+const sessionTimeRanges: Array<{ value: SessionTimeRange; label: string; milliseconds?: number }> = [
+  { value: "all", label: "All time" },
+  { value: "day", label: "Past 24 hours", milliseconds: 24 * 60 * 60 * 1000 },
+  { value: "week", label: "Past week", milliseconds: 7 * 24 * 60 * 60 * 1000 },
+  { value: "month", label: "Past month", milliseconds: 30 * 24 * 60 * 60 * 1000 },
+  { value: "year", label: "Past year", milliseconds: 365 * 24 * 60 * 60 * 1000 },
+];
+
 function readPersistedSessionDrawerOpen() {
   try {
     return localStorage.getItem(sessionDrawerOpenStorageKey) === "true";
@@ -138,6 +150,8 @@ export function createSessions(options: {
   refreshSessionTitle: () => Promise<void>;
   clearMessages: () => void;
   addMessage: (role: "system", text: string, extraClass?: string) => void;
+  /** Called whenever derived per-session state (e.g. waiting-on-spawned) may have changed. */
+  onDerivedSessionStateChanged?: () => void;
 }): SessionsController {
   const {
     state,
@@ -172,6 +186,8 @@ export function createSessions(options: {
   let sessionBarGestureInFlight = false;
   let sessionBarRenderQueued = false;
   let suppressTabClickUntil = 0;
+  let sessionTimeField: SessionTimeField = "modified";
+  let sessionTimeRange: SessionTimeRange = "all";
   type SessionRowTool = "pin" | SessionMarkerColorId;
   let selectedSessionRowTool: SessionRowTool = state.selectedMarkerColor;
 
@@ -433,6 +449,7 @@ export function createSessions(options: {
       renderSessionList(cachedSessions);
       renderSessionBar();
       updateSessionButtonUnread();
+      options.onDerivedSessionStateChanged?.();
     })().finally(() => { sessionRefreshPromise = undefined; });
     return sessionRefreshPromise;
   }
@@ -493,6 +510,7 @@ export function createSessions(options: {
     state.pinnedFolders = next.pinnedFolders;
     state.sessionMarkers = next.sessionMarkers;
     state.sessionUnreadStates = next.sessionUnreadStates;
+    state.sessionOrigins = next.sessionOrigins;
     syncCachedUnreadFromState();
     state.selectedMarkerColor = next.selectedMarkerColor;
     allowedMarkerColors.clear();
@@ -578,6 +596,55 @@ export function createSessions(options: {
     return Boolean(fallbackRunning || runtimeForSession(sessionId)?.isRunning);
   }
 
+  // ── Session origin (creation provenance) helpers ────────────────────────
+
+  function originParentOf(sessionId: string) {
+    return (state.sessionOrigins || []).find((item) => item.sessionId === sessionId)?.originSessionId;
+  }
+
+  function childSessionIdsOf(sessionId: string) {
+    return (state.sessionOrigins || []).filter((item) => item.originSessionId === sessionId).map((item) => item.sessionId);
+  }
+
+  function runningChildrenOf(sessionId: string) {
+    return childSessionIdsOf(sessionId).filter((childId) => {
+      const cached = cachedSessions.find((item) => item.id === childId);
+      return isSessionRunning(childId, Boolean(cached?.runtime?.isRunning));
+    });
+  }
+
+  /**
+   * Derived "waiting" state: session is idle but sessions it spawned are still
+   * running. Computed purely from origins + live runtimes — nothing to reset.
+   */
+  function waitingInfoFor(sessionId: string): { count: number; names: string[] } | undefined {
+    if (!sessionId || isSessionRunning(sessionId, Boolean(cachedSessions.find((item) => item.id === sessionId)?.runtime?.isRunning))) return undefined;
+    const running = runningChildrenOf(sessionId);
+    if (running.length === 0) return undefined;
+    const names = running.map((childId) => {
+      const cached = cachedSessions.find((item) => item.id === childId);
+      return (cached ? sessionTitle(cached) : "").replace(/^[⑂⤑]\s*/, "") || childId.slice(-8);
+    });
+    return { count: running.length, names };
+  }
+
+  /**
+   * Single precedence rule for per-session indicators: running > waiting >
+   * unread. Exactly one indicator is shown per session, everywhere (tab bar
+   * and drawer rows).
+   */
+  function sessionIndicator(sessionId: string, fallbacks: { running?: boolean; unread?: boolean }):
+    | { kind: "running" }
+    | { kind: "waiting"; waiting: { count: number; names: string[] } }
+    | { kind: "unread" }
+    | { kind: "none" } {
+    if (isSessionRunning(sessionId, Boolean(fallbacks.running))) return { kind: "running" };
+    const waiting = waitingInfoFor(sessionId);
+    if (waiting) return { kind: "waiting", waiting };
+    if (isSessionUnread(sessionId, Boolean(fallbacks.unread), Boolean(fallbacks.running))) return { kind: "unread" };
+    return { kind: "none" };
+  }
+
   function isSessionUnread(sessionId: string, fallbackUnread = false, fallbackRunning = false) {
     return Boolean(
       sessionId
@@ -654,13 +721,27 @@ export function createSessions(options: {
       .filter((color) => allowedMarkerColors.has(color));
   }
 
+  function selectedSessionTimeRange() {
+    return sessionTimeRanges.find((range) => range.value === sessionTimeRange) || sessionTimeRanges[0];
+  }
+
+  function matchesSessionTimeFilter(item: SessionInfo) {
+    const range = selectedSessionTimeRange();
+    if (!range.milliseconds) return true;
+    const value = Date.parse(item[sessionTimeField]);
+    return Number.isFinite(value) && value >= Date.now() - range.milliseconds;
+  }
+
   function renderSessionColorFilterButton() {
     if (!sessionColorFilterButton) return;
     const colors = sortedAllowedMarkerColors();
+    const timeRange = selectedSessionTimeRange();
     sessionColorFilterButton.textContent = "";
-    const active = colors.length > 0 || unreadFilterActive;
+    const timeFilterActive = sessionTimeRange !== "all";
+    const active = colors.length > 0 || unreadFilterActive || timeFilterActive;
     sessionColorFilterButton.classList.toggle("active", active);
     const parts = [
+      timeFilterActive ? `${sessionTimeField} ${timeRange.label.toLowerCase()}` : "all dates",
       colors.length === 0 ? "all colors allowed" : `colors: ${colors.map(markerColorLabel).join(", ")}`,
       unreadFilterActive ? "unread only" : "read and unread",
     ];
@@ -928,7 +1009,7 @@ export function createSessions(options: {
     closeOpenSessionColorFilterMenu();
 
     const menu = document.createElement("div");
-    menu.className = "sessionColorFilterMenu";
+    menu.className = "sessionColorFilterMenu sessionFilterMenu";
     menu.setAttribute("role", "menu");
 
     const title = document.createElement("div");
@@ -954,6 +1035,37 @@ export function createSessions(options: {
     unreadButton.append(unreadLabel);
     menu.append(unreadButton);
 
+    const timeTitle = document.createElement("div");
+    timeTitle.className = "sessionColorFilterTitle";
+    timeTitle.textContent = "Time";
+
+    const timeControls = document.createElement("div");
+    timeControls.className = "sessionTimeFilterControls";
+
+    const timeFieldSelect = document.createElement("select");
+    timeFieldSelect.className = "sessionTimeFilterSelect";
+    timeFieldSelect.setAttribute("aria-label", "Session date field");
+    for (const optionValue of ["created", "modified"] as const) {
+      const option = document.createElement("option");
+      option.value = optionValue;
+      option.textContent = optionValue === "created" ? "Created" : "Modified";
+      option.selected = sessionTimeField === optionValue;
+      timeFieldSelect.append(option);
+    }
+
+    const timeRangeSelect = document.createElement("select");
+    timeRangeSelect.className = "sessionTimeFilterSelect";
+    timeRangeSelect.setAttribute("aria-label", "Session time range");
+    for (const range of sessionTimeRanges) {
+      const option = document.createElement("option");
+      option.value = range.value;
+      option.textContent = range.label;
+      option.selected = sessionTimeRange === range.value;
+      timeRangeSelect.append(option);
+    }
+    timeControls.append(timeFieldSelect, timeRangeSelect);
+    menu.append(timeTitle, timeControls);
+
     const colorTitle = document.createElement("div");
     colorTitle.className = "sessionColorFilterTitle";
     colorTitle.textContent = "Marker colors";
@@ -991,6 +1103,17 @@ export function createSessions(options: {
       updateMenuState();
     });
 
+    timeFieldSelect.addEventListener("change", () => {
+      sessionTimeField = timeFieldSelect.value === "created" ? "created" : "modified";
+      renderSessionList(cachedSessions);
+    });
+
+    timeRangeSelect.addEventListener("change", () => {
+      const value = timeRangeSelect.value as SessionTimeRange;
+      sessionTimeRange = sessionTimeRanges.some((range) => range.value === value) ? value : "all";
+      renderSessionList(cachedSessions);
+    });
+
     for (const color of sessionMarkerColors) {
       const button = document.createElement("button");
       button.type = "button";
@@ -1412,7 +1535,8 @@ export function createSessions(options: {
     let activeTab: HTMLElement | undefined;
     const appendTab = (sessionId: string, label: string, cwd: string, options: { pinned: boolean; running?: boolean; unread?: boolean }) => {
       const isActive = currentId === sessionId;
-      const unread = isSessionUnread(sessionId, Boolean(options.unread), Boolean(options.running));
+      const indicator = sessionIndicator(sessionId, { running: options.running, unread: options.unread });
+      const unread = indicator.kind === "unread";
       const markerColor = colorForMarker(markerForSession(sessionId)?.color);
       const tab = document.createElement("div");
       tab.className = `sessionBarTab${isActive ? " active" : ""}${unread ? " unread" : ""}${options.running ? " running" : ""}${options.pinned ? " pinned" : " temporary"}${markerColor ? ` marked marker-${markerColor.id}` : ""}`;
@@ -1445,6 +1569,22 @@ export function createSessions(options: {
       labelEl.className = "sessionBarTabLabel";
       labelEl.textContent = label;
       open.append(labelEl);
+      if (indicator.kind === "waiting") {
+        const waiting = indicator.waiting;
+        const ribbon = document.createElement("span");
+        ribbon.className = "auroraRibbon";
+        ribbon.title = `Waiting on ${waiting.count} spawned session${waiting.count === 1 ? "" : "s"}: ${waiting.names.join(", ")}`;
+        ribbon.setAttribute("aria-label", ribbon.title);
+        tab.append(ribbon);
+      }
+      if (originParentOf(sessionId)) {
+        const lineage = document.createElement("span");
+        lineage.className = "sessionBarLineageGlyph";
+        lineage.textContent = "⑂";
+        lineage.title = "Spawned by another session";
+        lineage.setAttribute("aria-hidden", "true");
+        open.prepend(lineage);
+      }
       if (unread) {
         const unreadDot = document.createElement("span");
         unreadDot.className = "sessionUnreadDot sessionBarUnreadDot";
@@ -1673,13 +1813,14 @@ export function createSessions(options: {
     const query = sessionSearchInput?.value.trim().toLowerCase() || "";
     const matchesFilter = (item: SessionInfo) => {
       const marker = markerForSession(item.id);
+      if (!matchesSessionTimeFilter(item)) return false;
       if (allowedMarkerColors.size > 0 && !allowedMarkerColors.has(marker?.color as SessionMarkerColorId)) return false;
       if (unreadFilterActive && !isSessionUnread(item.id, Boolean(item.unread), Boolean(item.runtime?.isRunning))) return false;
       if (!query) return true;
       return [sessionTitle(item), item.cwd || "", item.firstMessage || ""]
         .some((value) => value.toLowerCase().includes(query));
     };
-    const filterActive = Boolean(query || allowedMarkerColors.size > 0 || unreadFilterActive);
+    const filterActive = Boolean(query || allowedMarkerColors.size > 0 || unreadFilterActive || sessionTimeRange !== "all");
     renderSessionColorFilterButton();
 
     const groups = new Map<string, SessionInfo[]>();
@@ -1771,14 +1912,17 @@ export function createSessions(options: {
         empty.className = "sessionEmpty";
         empty.textContent = query
           ? "No matching sessions in this folder."
-          : unreadFilterActive
+          : unreadFilterActive && sessionTimeRange === "all" && allowedMarkerColors.size === 0
             ? "No unread sessions in this folder."
-            : "No sessions in the selected colors.";
+            : sessionTimeRange === "all" && allowedMarkerColors.size > 0
+              ? "No sessions in the selected colors."
+              : "No sessions match these filters in this folder.";
         group.append(empty);
       }
 
       renderedItemCount += filteredItems.length;
-      for (const item of visibleItems) {
+      const orderedItems = orderItemsWithChildren(visibleItems);
+      for (const item of orderedItems) {
         group.append(buildSessionItem(item, cwd));
       }
 
@@ -1806,22 +1950,50 @@ export function createSessions(options: {
       empty.className = "sessionEmpty";
       empty.textContent = query
         ? "No matching sessions."
-        : unreadFilterActive
+        : unreadFilterActive && sessionTimeRange === "all" && allowedMarkerColors.size === 0
           ? "No unread sessions."
-          : "No sessions in the selected colors.";
+          : sessionTimeRange === "all" && allowedMarkerColors.size > 0
+            ? "No sessions in the selected colors."
+            : "No sessions match these filters.";
       elements.sessionListEl.append(empty);
     }
   }
 
+  /** Keep spawned children adjacent to (and after) their parent in the list. */
+  function orderItemsWithChildren(items: SessionInfo[]): SessionInfo[] {
+    if (!(state.sessionOrigins || []).length) return items;
+    const ids = new Set(items.map((item) => item.id));
+    const childrenByParent = new Map<string, SessionInfo[]>();
+    const deferred = new Set<string>();
+    for (const item of items) {
+      const parent = originParentOf(item.id);
+      if (parent && ids.has(parent)) {
+        childrenByParent.set(parent, [...(childrenByParent.get(parent) || []), item]);
+        deferred.add(item.id);
+      }
+    }
+    if (deferred.size === 0) return items;
+    const result: SessionInfo[] = [];
+    for (const item of items) {
+      if (deferred.has(item.id)) continue;
+      result.push(item);
+      for (const child of childrenByParent.get(item.id) || []) result.push(child);
+    }
+    return result;
+  }
+
   function buildSessionItem(item: SessionInfo, cwd: string): HTMLElement {
     // Use a div so we can have sibling buttons (navigate + actions) without nesting buttons
     const marker = markerForSession(item.id);
     const markerColor = colorForMarker(marker?.color);
     const pinned = isPinned(item.id);
-    const unread = isSessionUnread(item.id, Boolean(item.unread), Boolean(item.runtime?.isRunning));
+    const indicator = sessionIndicator(item.id, { running: item.runtime?.isRunning, unread: item.unread });
+    const unread = indicator.kind === "unread";
     const pinToolSelected = selectedSessionRowTool === "pin";
+    const waiting = indicator.kind === "waiting" ? indicator.waiting : undefined;
+    const isChild = Boolean(originParentOf(item.id));
     const row = document.createElement("div");
-    row.className = `sessionItem${item.isCurrent ? " current" : ""}${unread ? " unread" : ""}${pinned ? " pinned" : ""}${markerColor ? ` marked marker-${markerColor.id}` : ""}`;
+    row.className = `sessionItem${item.isCurrent ? " current" : ""}${unread ? " unread" : ""}${pinned ? " pinned" : ""}${markerColor ? ` marked marker-${markerColor.id}` : ""}${isChild ? " sessionItemChild" : ""}`;
     if (item.isCurrent) row.setAttribute("aria-current", "page");
 
     const markerButton = document.createElement("button");
@@ -1880,6 +2052,17 @@ export function createSessions(options: {
       spinner.setAttribute("aria-label", spinner.title);
       spinner.style.animationDelay = `-${Date.now() % 800}ms`;
       titleRow.append(spinner);
+    } else if (waiting) {
+      const pill = document.createElement("span");
+      pill.className = "sessionWaitingPill";
+      pill.title = `Waiting on ${waiting.count} spawned session${waiting.count === 1 ? "" : "s"}: ${waiting.names.join(", ")}`;
+      pill.setAttribute("aria-label", pill.title);
+      pill.append(iconElement("hourglass"));
+      const count = document.createElement("span");
+      count.className = "sessionWaitingCount";
+      count.textContent = String(waiting.count);
+      pill.append(count);
+      titleRow.append(pill);
     }
 
     const meta = document.createElement("span");
@@ -2040,5 +2223,6 @@ export function createSessions(options: {
     renderCurrentSessionBucketButton,
     applySessionUiState,
     markSessionRead,
+    waitingInfoFor,
   };
 }
diff --git a/src/settings/extensionSettings.ts b/src/settings/extensionSettings.ts
new file mode 100644
index 0000000..f7e99d4
--- /dev/null
+++ b/src/settings/extensionSettings.ts
@@ -0,0 +1,396 @@
+import type { ApiClient } from "../app/api.js";
+import type {
+  AppState,
+  WebFieldDescriptor,
+  WebSelectOption,
+  WebSettingsSchema,
+  WebSettingsValidationError,
+} from "../app/types.js";
+
+type ModelOption = { provider: string; id: string; name?: string };
+
+type Values = Record<string, unknown>;
+
+function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  props: Partial<HTMLElementTagNameMap[K]> & { class?: string } = {},
+  children: (Node | string)[] = [],
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag);
+  const { class: className, ...rest } = props as Record<string, unknown>;
+  if (className) node.className = String(className);
+  Object.assign(node, rest);
+  for (const child of children) node.append(typeof child === "string" ? document.createTextNode(child) : child);
+  return node;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function fieldDefault(field: WebFieldDescriptor): unknown {
+  if (field.default !== undefined) return field.default;
+  switch (field.type) {
+    case "toggle": return false;
+    case "number": return field.min ?? 0;
+    case "list": return [];
+    default: return "";
+  }
+}
+
+function defaultsFor(schema: WebSettingsSchema): Values {
+  const out: Values = {};
+  for (const f of schema.fields) out[f.key] = fieldDefault(f);
+  return out;
+}
+
+let rowSeq = 0;
+function newRowId(): string {
+  rowSeq += 1;
+  return `r${Date.now().toString(36)}${rowSeq.toString(36)}`;
+}
+
+function newRow(itemFields: WebFieldDescriptor[]): Values {
+  const row: Values = { __id: newRowId() };
+  for (const f of itemFields) row[f.key] = fieldDefault(f);
+  return row;
+}
+
+export type ExtensionSettingsController = {
+  render: () => void;
+};
+
+export function createExtensionSettings(options: {
+  container: HTMLElement;
+  api: ApiClient;
+  state: AppState;
+  fetchModels: () => Promise<ModelOption[]>;
+  setStatus: (message: string, isError?: boolean) => void;
+  notifyError: (message: string) => void;
+}): ExtensionSettingsController {
+  const { container, api, state, fetchModels, setStatus, notifyError } = options;
+
+  // Per-owner editable draft + last-seen errors, keyed by owner id.
+  const drafts = new Map<string, Values>();
+  const errors = new Map<string, WebSettingsValidationError[]>();
+  const openRows = new Set<string>();
+  let modelOptions: WebSelectOption[] | undefined;
+  let modelsLoading = false;
+
+  function storedFor(id: string) {
+    return state.settings.extensions?.[id];
+  }
+
+  function ensureDraft(schema: WebSettingsSchema): Values {
+    let draft = drafts.get(schema.id);
+    if (!draft) {
+      const stored = storedFor(schema.id)?.values;
+      draft = isRecord(stored) ? structuredClone(stored) : defaultsFor(schema);
+      drafts.set(schema.id, draft);
+    }
+    return draft;
+  }
+
+  function ensureModels() {
+    if (modelOptions || modelsLoading) return;
+    modelsLoading = true;
+    fetchModels().then((models) => {
+      modelOptions = models.map((m) => ({ value: `${m.provider}:${m.id}`, label: m.name ? `${m.name}` : `${m.provider}/${m.id}` }));
+      modelsLoading = false;
+      render();
+    }).catch(() => { modelsLoading = false; });
+  }
+
+  function optionsForSelect(field: WebFieldDescriptor, ownerDraft: Values): WebSelectOption[] {
+    if (field.options) return field.options;
+    if (field.optionsSource === "models") { ensureModels(); return modelOptions ?? []; }
+    if (field.optionsFromField) {
+      const [listKey, itemKey] = field.optionsFromField.split(".");
+      const list = ownerDraft[listKey];
+      if (!Array.isArray(list) || !itemKey) return [];
+      return list
+        .filter((r): r is Values => isRecord(r) && typeof r[itemKey] === "string" && Boolean((r[itemKey] as string).trim()))
+        .map((r) => ({ value: r[itemKey] as string }));
+    }
+    return [];
+  }
+
+  function errorAt(id: string, path: string): string | undefined {
+    return errors.get(id)?.find((e) => e.path === path)?.message;
+  }
+
+  function fieldRow(labelText: string, control: HTMLElement, descr: string | undefined, errText: string | undefined): HTMLElement {
+    const label = el("label", { class: "settingsField extSettingsField" });
+    label.append(el("span", {}, [labelText]));
+    label.append(control);
+    if (descr) label.append(el("span", { class: "settingsHint extSettingsHint" }, [descr]));
+    if (errText) {
+      const err = el("span", { class: "extSettingsError" }, [errText]);
+      err.setAttribute("role", "alert");
+      const ctrlId = control.id || `ext-${Math.random().toString(36).slice(2)}`;
+      control.id = ctrlId;
+      err.id = `${ctrlId}-err`;
+      control.setAttribute("aria-invalid", "true");
+      control.setAttribute("aria-describedby", err.id);
+      label.append(err);
+    }
+    return label;
+  }
+
+  // Render one scalar/select control bound to obj[field.key].
+  function scalarControl(id: string, field: WebFieldDescriptor, obj: Values, ownerDraft: Values, onStructural: () => void): HTMLElement {
+    const value = obj[field.key];
+    if (field.type === "toggle") {
+      const input = el("input", { type: "checkbox", checked: Boolean(value) });
+      input.addEventListener("change", () => { obj[field.key] = input.checked; });
+      const wrap = el("span", { class: "extSettingsToggle" }, [input]);
+      return wrap;
+    }
+    if (field.type === "select") {
+      const select = el("select");
+      const opts = optionsForSelect(field, ownerDraft);
+      select.append(el("option", { value: "" }, [field.required ? "Select…" : "— none —"]));
+      for (const o of opts) select.append(el("option", { value: o.value }, [o.label ?? o.value]));
+      select.value = typeof value === "string" ? value : "";
+      // keep an unavailable stored value visible
+      if (typeof value === "string" && value && select.value !== value) {
+        select.append(el("option", { value }, [`${value} (unavailable)`]));
+        select.value = value;
+      }
+      select.addEventListener("change", () => { obj[field.key] = select.value; });
+      return select;
+    }
+    if (field.type === "textarea") {
+      const ta = el("textarea", { value: typeof value === "string" ? value : "", rows: 3 });
+      if (field.maxLength) ta.maxLength = field.maxLength;
+      ta.addEventListener("input", () => { obj[field.key] = ta.value; });
+      return ta;
+    }
+    if (field.type === "number") {
+      const input = el("input", { type: "number", value: value === undefined ? "" : String(value) });
+      if (field.min !== undefined) input.min = String(field.min);
+      if (field.max !== undefined) input.max = String(field.max);
+      input.addEventListener("input", () => { obj[field.key] = input.value === "" ? undefined : Number(input.value); });
+      return input;
+    }
+    // text
+    const input = el("input", { type: "text", value: typeof value === "string" ? value : "" });
+    if (field.maxLength) input.maxLength = field.maxLength;
+    // a text field may feed a select's optionsFromField → re-render on commit
+    input.addEventListener("input", () => { obj[field.key] = input.value; });
+    input.addEventListener("change", () => { obj[field.key] = input.value; onStructural(); });
+    return input;
+  }
+
+  // A default-ref is a top-level select whose options come from a list column
+  // (optionsFromField). We render it as a per-row star toggle instead of a
+  // separate dropdown, and skip the standalone select.
+  type DefaultRef = { selectKey: string; itemKey: string };
+
+  function listControl(schema: WebSettingsSchema, field: WebFieldDescriptor, ownerDraft: Values, defaultRef?: DefaultRef): HTMLElement {
+    const wrap = el("div", { class: "extSettingsList" });
+    const rows = (Array.isArray(ownerDraft[field.key]) ? ownerDraft[field.key] : []) as Values[];
+    const itemFields = field.itemFields ?? [];
+    const rerender = () => render();
+    const titleField = itemFields.find((f) => f.type === "text");
+    const metaField = itemFields.find((f) => f.type === "select");
+    const defaultRowId = defaultRef
+      ? rows.find((r) => isRecord(r) && r[defaultRef.itemKey] === ownerDraft[defaultRef.selectKey] && r[defaultRef.itemKey] !== "")?.__id
+      : undefined;
+
+    rows.forEach((row, i) => {
+      if (!isRecord(row)) return;
+      if (typeof row.__id !== "string") row.__id = newRowId();
+      const rid = row.__id as string;
+      const open = openRows.has(rid);
+      const hasError = itemFields.some((f) => errorAt(schema.id, `${field.key}[${i}].${f.key}`));
+      const isDefault = Boolean(defaultRef) && ownerDraft[defaultRef!.selectKey] === row[defaultRef!.itemKey] && row[defaultRef!.itemKey] !== "";
+      const rowEl = el("div", { class: `extAccRow${open ? " open" : ""}${hasError ? " hasError" : ""}` });
+
+      const head = el("div", { class: "extAccHead" });
+      head.setAttribute("role", "button");
+      head.setAttribute("aria-expanded", String(open));
+      if (defaultRef) {
+        const star = el("button", { type: "button", class: `extAccStar${isDefault ? " on" : ""}`, title: isDefault ? "Default category" : "Make default" }, [isDefault ? "★" : "☆"]);
+        star.setAttribute("aria-pressed", String(isDefault));
+        star.addEventListener("click", (e) => { e.stopPropagation(); ownerDraft[defaultRef.selectKey] = row[defaultRef.itemKey]; rerender(); });
+        head.append(star);
+      }
+      const titleText = String((titleField && row[titleField.key]) || "").trim() || "(unnamed)";
+      head.append(el("span", { class: "extAccName" }, [titleText]));
+      if (metaField) {
+        const val = row[metaField.key];
+        const opts = optionsForSelect(metaField, ownerDraft);
+        const label = typeof val === "string" && val ? (opts.find((o) => o.value === val)?.label ?? val) : "—";
+        head.append(el("span", { class: "extAccMeta" }, [label]));
+      }
+      head.append(el("span", { class: "extAccChev" }, ["⌄"]));
+      head.addEventListener("click", () => { if (open) openRows.delete(rid); else openRows.add(rid); rerender(); });
+      rowEl.append(head);
+
+      if (open) {
+        const body = el("div", { class: "extAccBody" });
+        for (const item of itemFields) {
+          const ctrl = scalarControl(schema.id, item, row, ownerDraft, rerender);
+          // rename-follows-default: if this row is the default, keep the ref in sync live.
+          if (defaultRef && item.key === defaultRef.itemKey && rid === defaultRowId) {
+            ctrl.addEventListener("input", () => { ownerDraft[defaultRef.selectKey] = row[item.key]; });
+          }
+          body.append(fieldRow(item.label, ctrl, item.description, errorAt(schema.id, `${field.key}[${i}].${item.key}`)));
+        }
+        const actions = el("div", { class: "extAccRowActions" });
+        if (defaultRef) {
+          const mk = el("button", { type: "button", class: "extSettingsLink", disabled: isDefault }, [isDefault ? "★ Default" : "☆ Make default"]);
+          mk.addEventListener("click", () => { ownerDraft[defaultRef.selectKey] = row[defaultRef.itemKey]; rerender(); });
+          actions.append(mk);
+        }
+        const remove = el("button", { type: "button", class: "extSettingsLink danger" }, ["Delete"]);
+        remove.addEventListener("click", () => {
+          if (defaultRef && ownerDraft[defaultRef.selectKey] === row[defaultRef.itemKey]) ownerDraft[defaultRef.selectKey] = "";
+          rows.splice(i, 1); openRows.delete(rid); rerender();
+        });
+        actions.append(remove);
+        body.append(actions);
+        rowEl.append(body);
+      }
+      wrap.append(rowEl);
+    });
+
+    const listErr = errorAt(schema.id, field.key);
+    if (listErr) {
+      const e = el("span", { class: "extSettingsError" }, [listErr]);
+      e.setAttribute("role", "alert");
+      wrap.append(e);
+    }
+
+    const atMax = field.maxItems !== undefined && rows.length >= field.maxItems;
+    const singular = field.label.replace(/ies$/i, "y").replace(/s$/i, "");
+    const add = el("button", { type: "button", class: "extSettingsAdd", disabled: atMax }, [`+ Add ${singular.toLowerCase()}`]);
+    add.addEventListener("click", () => {
+      const r = newRow(itemFields);
+      rows.push(r);
+      ownerDraft[field.key] = rows;
+      openRows.add(r.__id as string); // open the new row for immediate editing
+      rerender();
+    });
+    wrap.append(add);
+    return wrap;
+  }
+
+  async function save(schema: WebSettingsSchema) {
+    const draft = ensureDraft(schema);
+    const expectedRevision = storedFor(schema.id)?.revision;
+    setStatus("Saving…");
+    try {
+      const res = await fetch(`/api/settings/extensions/${encodeURIComponent(schema.id)}`, {
+        method: "PATCH",
+        headers: api.headers(),
+        body: JSON.stringify({ values: draft, expectedRevision }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.status === 422 && Array.isArray(data.errors)) {
+        errors.set(schema.id, data.errors);
+        render();
+        setStatus(`Fix ${data.errors.length} field${data.errors.length === 1 ? "" : "s"}`, true);
+        return;
+      }
+      if (res.status === 409) {
+        errors.delete(schema.id);
+        drafts.delete(schema.id); // re-sync from server on next render
+        setStatus("Changed elsewhere — reloaded latest", true);
+        return;
+      }
+      if (!res.ok || data.ok === false) throw new Error(data.error || `HTTP ${res.status}`);
+      errors.delete(schema.id);
+      setStatus("Saved");
+      // state.settings gets refreshed via the settings_updated broadcast → applySettings
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      setStatus(msg, true);
+      notifyError(msg);
+    }
+  }
+
+  async function reset(schema: WebSettingsSchema) {
+    setStatus("Resetting…");
+    try {
+      const res = await fetch(`/api/settings/extensions/${encodeURIComponent(schema.id)}/reset`, { method: "POST", headers: api.headers() });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok || data.ok === false) throw new Error(data.error || `HTTP ${res.status}`);
+      drafts.delete(schema.id);
+      errors.delete(schema.id);
+      setStatus("Reset");
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      setStatus(msg, true);
+      notifyError(msg);
+    }
+  }
+
+  function renderSchema(schema: WebSettingsSchema): HTMLElement {
+    const draft = ensureDraft(schema);
+    const section = el("section", { class: "settingsSection extSettingsSection" });
+    section.append(el("h3", {}, [schema.title]));
+
+    // Detect default-ref selects (rendered as per-row stars on their list).
+    const defaultRefByList = new Map<string, DefaultRef>();
+    const skipSelectKeys = new Set<string>();
+    for (const f of schema.fields) {
+      if (f.type === "select" && f.optionsFromField) {
+        const [lk, ik] = f.optionsFromField.split(".");
+        if (lk && ik) { defaultRefByList.set(lk, { selectKey: f.key, itemKey: ik }); skipSelectKeys.add(f.key); }
+      }
+    }
+
+    for (const field of schema.fields) {
+      if (field.type === "select" && skipSelectKeys.has(field.key)) continue; // shown as row stars
+      if (field.type === "list") {
+        const group = el("div", { class: "extSettingsFieldGroup" });
+        group.append(el("span", { class: "extSettingsGroupLabel" }, [field.label]));
+        if (field.description) group.append(el("span", { class: "settingsHint extSettingsHint" }, [field.description]));
+        group.append(listControl(schema, field, draft, defaultRefByList.get(field.key)));
+        section.append(group);
+      } else {
+        const ctrl = scalarControl(schema.id, field, draft, draft, () => render());
+        section.append(fieldRow(field.label, ctrl, field.description, errorAt(schema.id, field.key)));
+      }
+    }
+    const actions = el("div", { class: "settingsActions" });
+    const saveBtn = el("button", { type: "button" }, ["Save"]);
+    saveBtn.addEventListener("click", () => void save(schema));
+    const resetBtn = el("button", { type: "button" }, ["Reset"]);
+    resetBtn.addEventListener("click", () => void reset(schema));
+    actions.append(saveBtn, resetBtn);
+    section.append(actions);
+    return section;
+  }
+
+  // "Data retained" card for owners with stored values but no live schema.
+  function renderRetained(id: string, valueCount: number): HTMLElement {
+    const section = el("section", { class: "settingsSection extSettingsSection extSettingsRetained" });
+    section.append(el("h3", {}, [id]));
+    section.append(el("p", { class: "settingsHint" }, [`Extension not loaded — ${valueCount} value${valueCount === 1 ? "" : "s"} retained. Load the extension to edit.`]));
+    return section;
+  }
+
+  function render() {
+    const schemas = state.webSettingsSchemas ?? [];
+    const registeredIds = new Set(schemas.map((s) => s.id));
+    container.replaceChildren();
+
+    for (const schema of schemas) container.append(renderSchema(schema));
+
+    const stored = state.settings.extensions ?? {};
+    for (const [id, rec] of Object.entries(stored)) {
+      if (registeredIds.has(id)) continue;
+      container.append(renderRetained(id, Object.keys(rec?.values ?? {}).length));
+    }
+
+    // Drop drafts for owners no longer present so a fresh open re-syncs.
+    for (const id of Array.from(drafts.keys())) {
+      if (!registeredIds.has(id)) drafts.delete(id);
+    }
+  }
+
+  return { render };
+}
diff --git a/src/settings/settings.ts b/src/settings/settings.ts
index 4874d5c..6b5b651 100644
--- a/src/settings/settings.ts
+++ b/src/settings/settings.ts
@@ -2,15 +2,17 @@ import type { ApiClient } from "../app/api.js";
 import { blurActiveEditableOnMobile } from "../app/focus.js";
 import type { AppElements } from "../app/elements.js";
 import { setIcon } from "../app/icons.js";
-import { defaultAccentColor, defaultLoadingAnimation, defaultPiWebSettings, normalizeMarkerColor, sessionMarkerColors, type AppState, type LoadingAnimation, type PiWebModelSetting, type PiWebSettings } from "../app/types.js";
+import { defaultAccentColor, defaultLoadingAnimation, defaultPiWebSettings, normalizeMarkerColor, sessionMarkerColors, type AppState, type LoadingAnimation, type PiWebModelSetting, type PiWebSettings, type WebSettingsSchema } from "../app/types.js";
 import { createQrSvg } from "../token/qr.js";
 import { createTokenShareUrl } from "../token/tokenShare.js";
 import type { RightPanelHandle, RightPanelManager } from "../layout/rightPanel.js";
+import { createExtensionSettings, type ExtensionSettingsController } from "./extensionSettings.js";
 
 export type SettingsController = {
   init: () => void;
   refreshSettings: () => Promise<void>;
   applySettings: (settings: PiWebSettings) => void;
+  applyWebSettingsSchemas: (schemas: WebSettingsSchema[]) => void;
 };
 
 type ExtensionLoadStatus = {
@@ -67,6 +69,9 @@ function normalizeSettings(value: unknown): PiWebSettings {
   const sessionBucketColor = normalizeMarkerColor(defaults?.sessionBucketColor);
   if (sessionBucketColor) settings.defaults.sessionBucketColor = sessionBucketColor;
 
+  // Carry the extension-settings blob through verbatim (server owns validation).
+  if (isRecord(value.extensions)) settings.extensions = value.extensions as PiWebSettings["extensions"];
+
   return settings;
 }
 
@@ -104,6 +109,7 @@ export function createSettings(options: {
   const expandedStorageKey = "pi-web-composer-expanded";
   let hasAppliedSettings = false;
   let settingsPanelHandle: RightPanelHandle | undefined;
+  let extSettings: ExtensionSettingsController | undefined;
 
   function updateQueueToggle() {
     const isSteer = state.queueMode === "steer";
@@ -223,6 +229,7 @@ export function createSettings(options: {
 
     updateQueueToggle();
     updateExpandedComposer();
+    extSettings?.render();
   }
 
   function setSettingsStatus(message: string, isError = false) {
@@ -406,6 +413,7 @@ export function createSettings(options: {
     const res = await fetch("/api/settings", { headers: api.headers() });
     if (!res.ok) throw new Error(await res.text());
     const data = await res.json();
+    if (Array.isArray(data.webSettingsSchemas)) state.webSettingsSchemas = data.webSettingsSchemas;
     applySettings(data.settings);
   }
 
@@ -457,6 +465,19 @@ export function createSettings(options: {
 
   function init() {
     populateBucketColorSelect(elements.settingDefaultBucketColorSelect);
+    extSettings = createExtensionSettings({
+      container: elements.extensionSettingsContainer,
+      api,
+      state,
+      fetchModels: async () => {
+        const res = await fetch("/api/models", { headers: api.headers() });
+        if (!res.ok) return [];
+        const data = await res.json().catch(() => ({}));
+        return Array.isArray(data.models) ? data.models : [];
+      },
+      setStatus: setSettingsStatus,
+      notifyError: (message) => addMessage("system", message, "error"),
+    });
     applySettings(state.settings);
 
     settingsPanelHandle = rightPanels?.register({
@@ -589,5 +610,10 @@ export function createSettings(options: {
     });
   }
 
-  return { init, refreshSettings, applySettings };
+  function applyWebSettingsSchemas(schemas: WebSettingsSchema[]) {
+    state.webSettingsSchemas = Array.isArray(schemas) ? schemas : [];
+    extSettings?.render();
+  }
+
+  return { init, refreshSettings, applySettings, applyWebSettingsSchemas };
 }
diff --git a/src/status/statusBar.ts b/src/status/statusBar.ts
index e936558..9472fa8 100644
--- a/src/status/statusBar.ts
+++ b/src/status/statusBar.ts
@@ -3,6 +3,7 @@ import type { AppElements } from "../app/elements.js";
 import type { AppState } from "../app/types.js";
 import { sessionRuntime, type SessionStateController } from "../app/sessionState.js";
 import { connectionLostDelayMs, reconnectDelayMs, reconnectNoticeDelayMs } from "../app/types.js";
+import { iconElement } from "../app/icons.js";
 
 
 export type StatusBar = {
@@ -15,6 +16,7 @@ export type StatusBar = {
   markActivityStart: (label?: string, startedAt?: string | number | Date, lastActivityAt?: string | number | Date) => void;
   markActivityProgress: (label?: string, lastActivityAt?: string | number | Date) => void;
   markActivityEnd: () => void;
+  updateWaitingStatus: (info: { count: number; names: string[] } | undefined) => void;
 };
 
 const activityQuietNoticeMs = 30_000;
@@ -241,6 +243,38 @@ export function createStatusBar(options: {
     elements.runtimeStatusEl.textContent = "";
     elements.runtimeStatusEl.title = "";
     elements.runtimeStatusEl.className = "runtimeStatus";
+    renderWaitingStatus();
+  }
+
+  // Derived "waiting on spawned sessions" indicator, shown in the runtime
+  // slot above the composer — but only while the session is otherwise idle:
+  // precedence is running > waiting. Static pulsing hourglass (accent, same
+  // color family as unread) + white text naming what it waits for.
+  let waitingInfo: { count: number; names: string[] } | undefined;
+
+  function clearWaitingRender() {
+    if (!elements.runtimeStatusEl.classList.contains("waiting")) return;
+    elements.runtimeStatusEl.hidden = true;
+    elements.runtimeStatusEl.textContent = "";
+    elements.runtimeStatusEl.title = "";
+    elements.runtimeStatusEl.className = "runtimeStatus";
+  }
+
+  function renderWaitingStatus() {
+    if (!waitingInfo || currentActivity()) return;
+    const names = waitingInfo.names.slice(0, 3).join(", ") + (waitingInfo.names.length > 3 ? "…" : "");
+    elements.runtimeStatusEl.className = "runtimeStatus waiting";
+    elements.runtimeStatusEl.textContent = "";
+    elements.runtimeStatusEl.append(iconElement("hourglass"), document.createTextNode(`Waiting on ${waitingInfo.count} spawned session${waitingInfo.count === 1 ? "" : "s"}: ${names}`));
+    elements.runtimeStatusEl.title = "This session stays usable while spawned sessions run — it will be woken automatically when they finish.";
+    elements.runtimeStatusEl.hidden = false;
+  }
+
+  function updateWaitingStatus(info: { count: number; names: string[] } | undefined) {
+    waitingInfo = info;
+    if (currentActivity()) return; // running indicator owns the slot
+    if (info) renderWaitingStatus();
+    else clearWaitingRender();
   }
 
   function scheduleConnectionStatus() {
@@ -339,5 +373,6 @@ export function createStatusBar(options: {
     markActivityStart,
     markActivityProgress,
     markActivityEnd,
+    updateWaitingStatus,
   };
 }
diff --git a/src/styles/base.css b/src/styles/base.css
index 7762568..da60fc1 100644
--- a/src/styles/base.css
+++ b/src/styles/base.css
@@ -72,3 +72,67 @@ body {
   overflow: hidden;
 }
 
+
+/* Waiting-on-spawned-sessions (session tabs): aurora ribbon.
+   Polychrome ribbon drifting along the tab's bottom edge — mobile-proof and
+   never competes with the tab's close/pin action slot. (The session drawer and
+   status bar use the hourglass + count instead.) */
+@keyframes auroraDrift {
+  0% { background-position: 0% 0; }
+  100% { background-position: 300% 0; }
+}
+.auroraRibbon {
+  position: absolute;
+  left: 0; right: 0; bottom: 0;
+  height: 14px;
+  z-index: 0;
+  pointer-events: none;
+  background: linear-gradient(90deg,
+    color-mix(in srgb, var(--accent) 72%, transparent),
+    color-mix(in srgb, #6fd7c2 60%, transparent),
+    color-mix(in srgb, var(--accent) 78%, transparent),
+    color-mix(in srgb, #8fb6ff 52%, transparent),
+    color-mix(in srgb, var(--accent) 72%, transparent));
+  background-size: 300% 100%;
+  -webkit-mask-image: linear-gradient(180deg, transparent, #000 92%);
+  mask-image: linear-gradient(180deg, transparent, #000 92%);
+  animation: auroraDrift 7s linear infinite;
+}
+
+/* Waiting-on-spawned-sessions: pulsing hourglass + count pill.
+   Shown in the session drawer row and the status bar (not on the bottom tabs).
+   Precedence: running > waiting > unread. */
+@keyframes waitingPulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: .4; }
+}
+.sessionWaitingPill {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  margin-left: 6px;
+  padding: 1px 6px 1px 4px;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--accent) 16%, transparent);
+  color: var(--accent);
+  font-size: 11px;
+  line-height: 1;
+  flex: 0 0 auto;
+}
+.sessionWaitingPill svg {
+  width: 12px;
+  height: 12px;
+  animation: waitingPulse 2s ease-in-out infinite;
+}
+.sessionWaitingCount { font-weight: 600; }
+.runtimeStatus.waiting svg {
+  width: 13px;
+  height: 13px;
+  vertical-align: middle;
+  margin-right: 5px;
+  animation: waitingPulse 2s ease-in-out infinite;
+}
+@media (prefers-reduced-motion: reduce) {
+  .sessionWaitingPill svg, .runtimeStatus.waiting svg { animation: none; }
+  .auroraRibbon { animation: none; }
+}
diff --git a/src/styles/composer.css b/src/styles/composer.css
index fae6d1d..6bd6b64 100644
--- a/src/styles/composer.css
+++ b/src/styles/composer.css
@@ -76,6 +76,13 @@
 .runtimeStatus.running { color: var(--accent); }
 .runtimeStatus.quiet { color: #facc15; }
 .runtimeStatus.stale { color: #fb923c; }
+.runtimeStatus.waiting {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--fg);
+  pointer-events: auto;
+}
 .contextMeterLabel {
   right: 0;
   display: none;
diff --git a/src/styles/messages.css b/src/styles/messages.css
index 1dad91f..e871408 100644
--- a/src/styles/messages.css
+++ b/src/styles/messages.css
@@ -573,3 +573,78 @@ body.artifactPreviewDocument {
   background: rgba(250, 204, 21, .14);
 }
 .message.error { border-color: var(--danger); color: #fecdd3; }
+/* Extension-injected messages, including orchestrator worker updates. */
+.message.customCard {
+  --message-bg: color-mix(in srgb, var(--accent) 4%, var(--panel));
+  align-self: flex-start;
+  flex: none; /* overflow:hidden zeroes the flex min-size; don't let the column squash the card */
+  box-sizing: border-box;
+  width: min(880px, calc(100% - 32px));
+  max-width: min(880px, calc(100% - 32px));
+  margin: 12px 16px;
+  padding: 11px 14px 12px;
+  overflow: hidden;
+  background: var(--message-bg);
+  border: 1px solid color-mix(in srgb, var(--accent) 26%, transparent);
+  border-radius: 12px;
+}
+.message.customCard.error {
+  border-color: color-mix(in srgb, var(--danger) 40%, transparent);
+}
+.message.customCard > .body {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+.customCardHeader {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: 7px;
+  font-size: 12px;
+  font-weight: 700;
+  color: color-mix(in srgb, var(--accent) 82%, var(--text));
+}
+.customCardHeader svg {
+  width: 13px;
+  height: 13px;
+  flex: 0 0 auto;
+}
+.customCardSessionChip {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  max-width: 100%;
+  padding: 1px 8px;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, var(--accent) 30%, transparent);
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  color: var(--text);
+  font-size: 11px;
+  font-weight: 600;
+  text-decoration: none;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.customCardSessionChip:hover {
+  background: color-mix(in srgb, var(--accent) 24%, transparent);
+}
+.customCardSessionChip.status-error {
+  border-color: color-mix(in srgb, var(--danger) 38%, transparent);
+  background: color-mix(in srgb, var(--danger) 10%, transparent);
+  color: var(--danger);
+}
+.customCardSessionChip.status-aborted {
+  border-color: color-mix(in srgb, var(--muted) 30%, transparent);
+  background: color-mix(in srgb, var(--muted) 9%, transparent);
+  color: var(--muted);
+}
+
+@media (max-width: 640px) {
+  .message.customCard {
+    width: calc(100% - 16px);
+    max-width: calc(100% - 16px);
+    margin: 8px;
+  }
+}
diff --git a/src/styles/sessions.css b/src/styles/sessions.css
index 4a0468f..1f8ef71 100644
--- a/src/styles/sessions.css
+++ b/src/styles/sessions.css
@@ -450,6 +450,7 @@
 
 /* ── Session item: pin + nav layout ── */
 .sessionItem {
+  position: relative;
   display: flex;
   flex-shrink: 0;
   width: 100%;
@@ -622,12 +623,41 @@
 .sessionColorFilterMenu {
   min-width: 150px;
 }
+.sessionFilterMenu {
+  min-width: 240px;
+  max-height: calc(100vh - 16px);
+  overflow-y: auto;
+}
 .sessionColorFilterTitle {
   color: var(--muted);
   font-size: 11px;
   font-weight: 700;
   padding: 6px 8px 4px;
 }
+.sessionTimeFilterControls {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1.35fr);
+  gap: 4px;
+  padding: 0 4px 4px;
+}
+.sessionTimeFilterSelect {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  height: 30px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--panel-2);
+  color: var(--text);
+  font: inherit;
+  font-size: 12px;
+  padding: 0 6px;
+}
+.sessionTimeFilterSelect:hover,
+.sessionTimeFilterSelect:focus-visible {
+  border-color: var(--accent);
+  outline: none;
+}
 .sessionColorFilterMenuItem {
   display: flex;
   align-items: center;
@@ -1140,3 +1170,27 @@ body.hasPinnedSessions .app {
     margin-bottom: 0;
   }
 }
+
+/* ── Derived "waiting on spawned sessions" chip + lineage indent ────────── */
+.sessionBarLineageGlyph {
+  flex: 0 0 auto;
+  margin-right: 3px;
+  font-size: 10px;
+  color: color-mix(in srgb, var(--muted) 80%, transparent);
+}
+.sessionItemChild {
+  margin-left: 18px;
+  width: calc(100% - 18px);
+  position: relative;
+}
+.sessionItemChild::before {
+  content: "";
+  position: absolute;
+  left: -10px;
+  top: 0;
+  bottom: 50%;
+  width: 8px;
+  border-left: 1px solid color-mix(in srgb, var(--muted) 35%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--muted) 35%, transparent);
+  border-bottom-left-radius: 6px;
+}
diff --git a/src/styles/settings.css b/src/styles/settings.css
index 1af5d2b..c436b29 100644
--- a/src/styles/settings.css
+++ b/src/styles/settings.css
@@ -455,3 +455,169 @@
 :root[data-density="compact"] .markdownBody table {
   margin-bottom: .55em;
 }
+
+/* --- Extension-contributed settings (generic renderer) --- */
+.extensionSettings {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+.extensionSettings:empty {
+  display: none;
+}
+.extSettingsFieldGroup {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.extSettingsGroupLabel {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text);
+}
+/* list-item + group fields stack label over control */
+.extSettingsSection .extSettingsField {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 5px;
+}
+.extSettingsField > span:first-child {
+  color: var(--muted);
+  font-size: 12px;
+}
+.extSettingsField input[type="text"],
+.extSettingsField input[type="number"],
+.extSettingsField textarea,
+.extSettingsField select {
+  width: 100%;
+  min-height: 34px;
+  border: 1px solid var(--border);
+  border-radius: 9px;
+  background: var(--panel);
+  color: var(--text);
+  padding: 6px 8px;
+  font: inherit;
+}
+.extSettingsField textarea {
+  resize: vertical;
+  min-height: 58px;
+  line-height: 1.4;
+}
+.extSettingsToggle {
+  display: inline-flex;
+}
+.extSettingsList {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+/* Accordion rows: collapsed one-line summary, expand to edit. */
+.extAccRow {
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: color-mix(in srgb, var(--panel) 80%, transparent);
+  overflow: hidden;
+}
+.extAccRow.hasError {
+  border-color: color-mix(in srgb, var(--danger, #e0563f) 55%, var(--border));
+}
+.extAccHead {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  padding: 9px 11px;
+  cursor: pointer;
+}
+.extAccStar {
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-size: 15px;
+  line-height: 1;
+  color: var(--muted);
+  padding: 0;
+  flex: 0 0 auto;
+}
+.extAccStar.on { color: var(--accent); }
+.extAccName {
+  font-weight: 600;
+  font-size: 13px;
+  color: var(--text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.extAccMeta {
+  margin-left: auto;
+  color: var(--muted);
+  font-size: 12px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 45%;
+}
+.extAccChev {
+  color: var(--muted);
+  transition: transform .15s ease;
+  flex: 0 0 auto;
+}
+.extAccRow.open .extAccChev { transform: rotate(180deg); }
+.extAccBody {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 4px 11px 11px;
+  border-top: 1px solid var(--border);
+}
+.extAccRowActions {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-top: 2px;
+}
+.extSettingsLink {
+  background: none;
+  border: none;
+  color: var(--muted);
+  cursor: pointer;
+  font-size: 12px;
+  padding: 2px 0;
+}
+.extSettingsLink:hover:not(:disabled) { color: var(--text); }
+.extSettingsLink:disabled { color: var(--accent); cursor: default; }
+.extSettingsLink.danger { color: var(--danger, #e0563f); }
+.extSettingsAdd {
+  align-self: flex-start;
+  border: 1px dashed var(--border);
+  border-radius: 9px;
+  background: none;
+  color: var(--text);
+  padding: 7px 12px;
+  font-size: 13px;
+  cursor: pointer;
+}
+.extSettingsAdd:hover:not(:disabled) {
+  border-color: color-mix(in srgb, var(--accent) 55%, var(--border));
+}
+.extSettingsAdd:disabled {
+  opacity: .5;
+  cursor: not-allowed;
+}
+.extSettingsHint {
+  font-size: 11.5px;
+  color: var(--muted);
+}
+.extSettingsError {
+  font-size: 12px;
+  color: var(--danger, #e0563f);
+}
+.extSettingsField input[aria-invalid="true"],
+.extSettingsField textarea[aria-invalid="true"],
+.extSettingsField select[aria-invalid="true"] {
+  border-color: var(--danger, #e0563f);
+}
+.extSettingsRetained h3 {
+  color: var(--muted);
+  font-weight: 500;
+}
diff --git a/src/tools/toolCards.ts b/src/tools/toolCards.ts
index 03cc714..53c9935 100644
--- a/src/tools/toolCards.ts
+++ b/src/tools/toolCards.ts
@@ -94,6 +94,58 @@ function addToolArgsDetails(card: HTMLDivElement, args?: Record<string, unknown>
   card.append(details);
 }
 
+function toolResultSessionRefs(toolName: string, result: unknown): Array<{ sessionId: string; name?: string; status?: string }> {
+  const refs: Array<{ sessionId: string; name?: string; status?: string }> = [];
+  const seen = new Set<string>();
+  const push = (sessionId?: string, name?: string, status?: string) => {
+    const id = typeof sessionId === "string" ? sessionId.trim() : "";
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    refs.push({ sessionId: id, name: name?.trim() || undefined, status });
+  };
+  const rec = result && typeof result === "object" ? result as Record<string, unknown> : {};
+  const details = (rec.details ?? (rec.raw as Record<string, unknown> | undefined)?.details) as unknown;
+  if (details && typeof details === "object") {
+    const d = details as Record<string, unknown>;
+    const items = Array.isArray(d.workers) ? d.workers : Array.isArray(d.sessions) ? d.sessions : [d];
+    for (const item of items) {
+      if (item && typeof item === "object") {
+        const r = item as Record<string, unknown>;
+        push(typeof r.sessionId === "string" ? r.sessionId : undefined,
+          typeof r.name === "string" ? r.name : undefined,
+          typeof r.status === "string" ? r.status : undefined);
+      }
+    }
+  }
+  // Fallback for the spawn tool: parse the session id from the result text
+  // (covers the live-stream path if details didn't ride along).
+  if (refs.length === 0 && toolName === "sessions_spawn") {
+    const text = textFromToolResult(result);
+    const re = /session\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(text))) push(m[1]);
+  }
+  return refs;
+}
+
+function addToolSessionChips(card: HTMLDivElement, toolName: string, result: unknown) {
+  if (toolName !== "sessions_spawn") return; // only the spawn card links to its worker
+  const refs = toolResultSessionRefs(toolName, result);
+  if (!refs.length) return;
+  const header = card.querySelector<HTMLElement>(".toolCardHeader");
+  if (!header) return;
+  const toggle = header.querySelector(".toolCardExpandToggle");
+  for (const ref of refs) {
+    const chip = document.createElement("a");
+    chip.className = `customCardSessionChip${ref.status === "error" ? " status-error" : ref.status === "aborted" ? " status-aborted" : ""}`;
+    chip.href = `/?sessionId=${encodeURIComponent(ref.sessionId)}`;
+    const statusIcon = ref.status === "error" ? "⚠" : ref.status === "aborted" ? "⏹" : "↗";
+    chip.textContent = `${statusIcon} ${ref.name || ref.sessionId.slice(-8)}`;
+    chip.title = `Open session ${ref.sessionId}`;
+    header.insertBefore(chip, toggle || null);
+  }
+}
+
 function addCardHeader(card: HTMLDivElement, title: string, subtitleText = "") {
   const header = document.createElement("div");
   header.className = "toolCardHeader";
@@ -446,6 +498,7 @@ export function createToolCards(messagesEl: HTMLDivElement, scrollToBottom: () =
     }
     addToolImagePreviews(card, result, apiHeaders);
     playToolCardStateTransition(card);
+    addToolSessionChips(card, toolName, result);
 
     scrollToBottom();
   }
@@ -459,6 +512,7 @@ export function createToolCards(messagesEl: HTMLDivElement, scrollToBottom: () =
     if (toolName === "edit" && args) renderEditDiff(card, args, result);
     else if (resultStr) addToolResultBody(card, resultStr);
     addToolImagePreviews(card, result, apiHeaders);
+    addToolSessionChips(card, toolName, result);
     messagesEl.append(card);
   }
 
diff --git a/tests/extension-settings.test.ts b/tests/extension-settings.test.ts
new file mode 100644
index 0000000..0d3f9bf
--- /dev/null
+++ b/tests/extension-settings.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import {
+  canonicalSchemaKey,
+  defaultSettingsValues,
+  validateSettingsValues,
+  type SettingsSchema,
+} from "../server/extensionSettings.js";
+
+const models = new Set(["anthropic:fast-1", "anthropic:smart-1"]);
+
+const schema: SettingsSchema = {
+  id: "demo-ext.categories",
+  title: "Categories",
+  schemaVersion: 1,
+  fields: [
+    {
+      key: "categories",
+      type: "list",
+      label: "Categories",
+      minItems: 0,
+      maxItems: 3,
+      itemFields: [
+        { key: "name", type: "text", label: "Name", required: true, maxLength: 24, uniqueCaseInsensitive: true },
+        { key: "model", type: "select", label: "Model", optionsSource: "models", required: true },
+        { key: "description", type: "textarea", label: "When to use", maxLength: 400 },
+      ],
+    },
+    { key: "defaultCategory", type: "select", label: "Default", optionsFromField: "categories.name" },
+  ],
+};
+
+function withCategories(names: Array<{ name: string; model?: string }>, defaultCategory = "") {
+  return {
+    categories: names.map(({ name, model }) => ({ name, model: model ?? "anthropic:fast-1", description: "" })),
+    defaultCategory,
+  };
+}
+
+describe("extension settings descriptors", () => {
+  it("produces a stable canonical key that ignores callbacks", () => {
+    const key = canonicalSchemaKey(schema);
+    expect(canonicalSchemaKey(JSON.parse(JSON.stringify(schema)))).toBe(key);
+    // Functions are not part of schema identity (R2.4).
+    expect(canonicalSchemaKey({ ...schema, migrate: () => ({}), onChange: () => undefined } as SettingsSchema)).toBe(key);
+    expect(canonicalSchemaKey({ ...schema, schemaVersion: 2 })).not.toBe(key);
+  });
+
+  it("derives defaults per field type", () => {
+    expect(defaultSettingsValues(schema)).toEqual({ categories: [], defaultCategory: "" });
+  });
+});
+
+describe("extension settings validation", () => {
+  it("accepts a valid configuration and assigns stable row ids", () => {
+    const first = validateSettingsValues(schema, withCategories([{ name: "Fast" }, { name: "Smart", model: "anthropic:smart-1" }], "Fast"), { modelOptions: models });
+    expect(first.errors).toEqual([]);
+
+    const rowId = (first.values.categories as Array<Record<string, unknown>>)[0].__id;
+    expect(typeof rowId).toBe("string");
+
+    // Re-validating preserves row identity so cross-field references survive edits.
+    const again = validateSettingsValues(schema, first.values, { modelOptions: models });
+    expect((again.values.categories as Array<Record<string, unknown>>)[0].__id).toBe(rowId);
+  });
+
+  it("flags a model that the registry does not offer", () => {
+    const result = validateSettingsValues(schema, withCategories([{ name: "Ghost", model: "openai:missing" }], "Ghost"), { modelOptions: models });
+    expect(result.errors.map((error) => error.path)).toContain("categories[0].model");
+  });
+
+  it("flags a default that references a missing category", () => {
+    const result = validateSettingsValues(schema, withCategories([{ name: "Fast" }], "Nope"), { modelOptions: models });
+    expect(result.errors.map((error) => error.path)).toContain("defaultCategory");
+  });
+
+  it("keeps the default valid when the referenced category is renamed alongside it", () => {
+    const result = validateSettingsValues(schema, withCategories([{ name: "Quick" }], "Quick"), { modelOptions: models });
+    expect(result.errors).toEqual([]);
+  });
+
+  it("rejects duplicate names case-insensitively", () => {
+    const result = validateSettingsValues(schema, withCategories([{ name: "Fast" }, { name: "fast" }], "Fast"), { modelOptions: models });
+    expect(result.errors.map((error) => error.path)).toContain("categories[1].name");
+  });
+
+  it("requires non-empty required text and honours item bounds", () => {
+    const blank = validateSettingsValues(schema, withCategories([{ name: "   " }]), { modelOptions: models });
+    expect(blank.errors.map((error) => error.path)).toContain("categories[0].name");
+
+    const tooMany = validateSettingsValues(
+      schema,
+      withCategories([{ name: "a" }, { name: "b" }, { name: "c" }, { name: "d" }], "a"),
+      { modelOptions: models },
+    );
+    expect(tooMany.errors.map((error) => error.path)).toContain("categories");
+  });
+});
diff --git a/tests/settings.test.ts b/tests/settings.test.ts
index 68c795d..155b266 100644
--- a/tests/settings.test.ts
+++ b/tests/settings.test.ts
@@ -2,7 +2,15 @@ import { afterEach, describe, expect, it } from "vitest";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { applySettingsPatch, createSettingsStore, normalizeSettings } from "../server/settings.js";
+import {
+  applyExtensionValues,
+  applySettingsPatch,
+  createSettingsStore,
+  ExtensionRevisionConflictError,
+  ExtensionSettingsBoundsError,
+  normalizeSettings,
+  resetExtensionValues,
+} from "../server/settings.js";
 
 let tempDirs: string[] = [];
 
@@ -63,3 +71,80 @@ describe("pi-web settings", () => {
     expect((await reloaded.read()).composer.queueMode).toBe("followUp");
   });
 });
+
+describe("extension-contributed settings", () => {
+  const OWNER = "demo-ext.prefs";
+
+  it("preserves extension values when unrelated settings are patched", async () => {
+    // Regression: normalizeSettings rebuilds known fields only, so an owner's
+    // values must be carried through verbatim even while its extension is absent.
+    const withValues = applyExtensionValues(normalizeSettings({}), OWNER, { tier: "fast" }, { schemaVersion: 3 });
+    const patched = applySettingsPatch(withValues, { appearance: { density: "compact" } });
+
+    expect(patched.appearance.density).toBe("compact");
+    expect(patched.extensions?.[OWNER]?.values).toEqual({ tier: "fast" });
+    expect(patched.extensions?.[OWNER]?.schemaVersion).toBe(3);
+  });
+
+  it("ignores extension values supplied through the generic patch path", () => {
+    const injected = applySettingsPatch(normalizeSettings({}), {
+      extensions: { "evil.owner": { schemaVersion: 1, revision: 1, values: { nope: true } } },
+    });
+    expect(injected.extensions?.["evil.owner"]).toBeUndefined();
+  });
+
+  it("persists nothing until an owner actually writes", () => {
+    expect(normalizeSettings({}).extensions).toBeUndefined();
+  });
+
+  it("bumps revision and rejects stale writes", () => {
+    const first = applyExtensionValues(normalizeSettings({}), OWNER, { n: 1 });
+    expect(first.extensions?.[OWNER]?.revision).toBe(1);
+
+    const second = applyExtensionValues(first, OWNER, { n: 2 }, { expectedRevision: 1 });
+    expect(second.extensions?.[OWNER]?.revision).toBe(2);
+
+    expect(() => applyExtensionValues(second, OWNER, { n: 3 }, { expectedRevision: 1 }))
+      .toThrow(ExtensionRevisionConflictError);
+  });
+
+  it("enforces bounds and namespaced owner ids", () => {
+    expect(() => applyExtensionValues(normalizeSettings({}), OWNER, { blob: "x".repeat(70 * 1024) }))
+      .toThrow(ExtensionSettingsBoundsError);
+    expect(() => applyExtensionValues(normalizeSettings({}), "nodots", { a: 1 }))
+      .toThrow(ExtensionSettingsBoundsError);
+  });
+
+  it("keeps the migration backup outside user values across a round trip", () => {
+    const withBackup = applyExtensionValues(normalizeSettings({}), OWNER, { fresh: true }, {
+      backup: { schemaVersion: 1, values: { legacy: true } },
+    });
+    const roundTripped = normalizeSettings(JSON.parse(JSON.stringify(withBackup)));
+
+    expect(roundTripped.extensions?.[OWNER]?.backup?.values).toEqual({ legacy: true });
+    expect(roundTripped.extensions?.[OWNER]?.values).toEqual({ fresh: true });
+  });
+
+  it("resets an owner without touching the rest of the settings", () => {
+    const withValues = applyExtensionValues(normalizeSettings({}), OWNER, { tier: "fast" });
+    const reset = resetExtensionValues(withValues, OWNER);
+    expect(reset.extensions).toBeUndefined();
+    expect(reset.appearance.accentColor).toBe(withValues.appearance.accentColor);
+  });
+
+  it("round-trips owner values through the store on disk", async () => {
+    const store = createSettingsStore(await tempFile());
+    await store.patchExtension(OWNER, { tier: "fast" }, { schemaVersion: 1 });
+
+    const reread = await store.read();
+    expect(reread.extensions?.[OWNER]?.values).toEqual({ tier: "fast" });
+
+    await store.patch({ composer: { queueMode: "followUp" } });
+    const afterUnrelated = await store.read();
+    expect(afterUnrelated.composer.queueMode).toBe("followUp");
+    expect(afterUnrelated.extensions?.[OWNER]?.values).toEqual({ tier: "fast" });
+
+    await store.resetExtension(OWNER);
+    expect((await store.read()).extensions?.[OWNER]).toBeUndefined();
+  });
+});

From f5f326a82b2883cabcc82a724ee9201dbb142434 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 08:37:47 +0000
Subject: [PATCH 02/10] feat: add session orchestration example extension and
 skill

Ships the multi-agent orchestration semantics as a userland pi-web extension
rather than core behaviour: sessions_spawn/status/read/prompt/abort plus a
zero-token background poller that delivers a wakeup when a worker goes idle, so
the parent never polls. Workers are ordinary, fully visible sessions.

Worker models come from user-authored categories (name, model, and "when to use"
prose) configured through the settings API. The category to model mapping stays
private to the config; the spawn tool resolves it fail-closed against the
worker's own registry and cleans up if resolution fails.

Documents the settings API and the orchestration example, and adds the companion
skill that teaches the delegation loop.
---
 docs/pi-web-extensions.md                     |  85 ++
 .../pi-web-extensions/session-orchestrator.ts | 968 ++++++++++++++++++
 .../session-orchestration/SKILL.md            | 119 +++
 3 files changed, 1172 insertions(+)
 create mode 100644 examples/pi-web-extensions/session-orchestrator.ts
 create mode 100644 examples/pi-web-skills/session-orchestration/SKILL.md

diff --git a/docs/pi-web-extensions.md b/docs/pi-web-extensions.md
index 99c335e..f810d18 100644
--- a/docs/pi-web-extensions.md
+++ b/docs/pi-web-extensions.md
@@ -188,6 +188,57 @@ Clear a Git panel tab by passing `undefined`:
 ctx.ui.web.setGitTab("github", undefined);
 ```
 
+## Settings API
+
+`ctx.ui.web.registerSettings(schema)` contributes a settings panel to pi-web's
+settings drawer. Core pi-web owns storage, validation, and rendering; the
+extension owns the schema and reacts to changes. Values are **global** (shared by
+every session) while the schema registration is **per session**, and they persist
+after the extension unloads.
+
+```ts
+pi.on("session_start", async (_event, ctx) => {
+  await ctx.ui.web.registerSettings({
+    id: "my-ext.prefs",          // namespaced: <extension>.<schema>
+    title: "My extension",
+    schemaVersion: 1,
+    fields: [
+      { key: "enabled", type: "toggle", label: "Enabled", default: true },
+      { key: "model", type: "select", label: "Model", optionsSource: "models" },
+    ],
+    onChange: (values) => applyPreferences(values),
+  });
+
+  const { values } = await ctx.ui.web.getSettings("my-ext.prefs");
+});
+```
+
+Field types are `toggle`, `text`, `textarea`, `number`, `select`, and `list`
+(a repeater with `itemFields`). Constraints include `required`, `min`/`max`,
+`minLength`/`maxLength`/`pattern`, `minItems`/`maxItems`, and
+`uniqueCaseInsensitive`. Validation errors render inline and are announced to
+screen readers.
+
+`select` options come from static `options`, from the live model registry with
+`optionsSource: "models"`, or from another field with
+`optionsFromField: "<listKey>.<itemKey>"`. When a top-level `select` references a
+list column this way, pi-web renders it as a per-row "default" star on that list
+instead of a separate dropdown. List rows carry a stable hidden `__id`, so
+renaming a row keeps references intact.
+
+Storage notes:
+
+- Values are stored under `extensions[id]` in pi-web settings as
+  `{ schemaVersion, revision, values, backup? }` and are carried through
+  verbatim, so an unloaded extension never loses its configuration.
+- Writes are validated against the live schema and use an optimistic `revision`
+  guard, so concurrent edits from two browsers cannot silently drop fields.
+- Bump `schemaVersion` and supply `migrate(oldValues, oldVersion)` to upgrade
+  stored values. A failed migration falls back to defaults and keeps a one-slot
+  `backup`.
+- Owners with stored values but no live registration render as a read-only
+  "data retained" card.
+
 ## Example: GitHub PRs and issues tab
 
 The repo includes an opt-in GitHub extension example at [`examples/pi-web-extensions/github-repo-panel.ts`](../examples/pi-web-extensions/github-repo-panel.ts). It adds a **GitHub** tab to the built-in Git drawer for repositories with GitHub remotes. The extension uses the `gh` CLI to list and view pull requests and issues.
@@ -247,3 +298,37 @@ cp examples/pi-web-extensions/git-footer.ts ~/.pi/web/extensions/git-footer.ts
 ```
 
 Reload pi-web resources with `/reload`, or restart pi-web if you are adding the extension while sessions are already live.
+
+## Example: multi-agent session orchestration
+
+The repo includes a session-orchestration extension at
+[`examples/pi-web-extensions/session-orchestrator.ts`](../examples/pi-web-extensions/session-orchestrator.ts).
+It lets one session spawn, monitor, steer, and interrupt other sessions, turning
+pi-web into a multi-agent workspace where each worker is a **normal, fully
+visible session** in the sidebar rather than a hidden subagent.
+
+It registers five tools — `sessions_spawn`, `sessions_status`, `sessions_read`,
+`sessions_prompt`, `sessions_abort` — and a zero-token background poller that
+delivers a wakeup message when a worker goes idle, so the parent never polls.
+Worker models are chosen from user-authored **categories** (name + "when to use"
+prose + a model) configured through the Settings API above; the concrete model
+mapping stays private to the config and the spawn tool resolves it fail-closed.
+
+pi-web renders the orchestration state generically: spawned sessions are
+indented under their parent in the session drawer, a waiting indicator shows
+while a session's workers run, wakeups render as notification cards, and both the
+spawn tool card and wakeup card link to the worker session.
+
+Install the extension into a pi-web extension directory, and the companion skill
+into a pi skills directory:
+
+```bash
+cp examples/pi-web-extensions/session-orchestrator.ts .pi/web/extensions/session-orchestrator.ts
+cp -r examples/pi-web-skills/session-orchestration ~/.pi/agent/skills/session-orchestration
+```
+
+The skill at
+[`examples/pi-web-skills/session-orchestration/SKILL.md`](../examples/pi-web-skills/session-orchestration/SKILL.md)
+teaches the delegation loop: what to delegate, how to write self-contained worker
+tasks, how to pick a category, and why ending your turn while workers run is
+correct.
diff --git a/examples/pi-web-extensions/session-orchestrator.ts b/examples/pi-web-extensions/session-orchestrator.ts
new file mode 100644
index 0000000..2b90dfa
--- /dev/null
+++ b/examples/pi-web-extensions/session-orchestrator.ts
@@ -0,0 +1,968 @@
+/**
+ * session-orchestrator — experimental pi-web extension
+ *
+ * Gives every pi-web session the same orchestration verbs a human has in the
+ * UI: spawn sibling sessions, check on them, read their transcripts, steer or
+ * interrupt them, and abort them. Workers are ordinary first-class pi-web
+ * sessions (full history, visible in the sidebar, resumable).
+ *
+ * Wakeups: after spawning/prompting a worker, the parent does NOT block. A
+ * background watcher (plain JS polling — zero tokens) injects a user message
+ * into the parent session when a worker goes idle, which starts a new parent
+ * turn. The parent can end its turn and "sleep" while workers run.
+ *
+ * Everything goes through the same local HTTP API the web UI uses.
+ *
+ * Reversible install: this lives in .pi/extensions/session-orchestrator/ —
+ * delete that directory (and .pi/skills/session-orchestration/) to remove the
+ * feature entirely. No AGENTS.md or server changes.
+ */
+
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const WORKER_MARKER = "[pi-web orchestrated worker]";
+const EXT_VERSION = "v9";
+const WAKEUP_CUSTOM_TYPE = "session-orchestrator";
+// Durable watch ledger: appended to the parent's session file so a freshly
+// re-materialized parent (server restart, /reload, idle disposal) can re-arm
+// its watchers or deliver catch-up wakeups. Resolved = wakeup was DELIVERED.
+const WATCH_ENTRY = "orchestrator-watch";
+const RESOLVED_ENTRY = "orchestrator-watch-resolved";
+const MAX_WORKERS = 4;
+const POLL_MS = 2500;
+const WAKEUP_SUMMARY_CHARS = 2000;
+
+// Generic extension-settings schema: user-authored worker model categories.
+// The `description` prose IS the routing guidance the orchestrator reads; the
+// concrete model stays private to config (never shown to the LLM). Empty config
+// is a virtual, unwritten "Default" resolved live to the worker's own model.
+const SETTINGS_ID = "session-orchestrator.workerModelCategories";
+const SETTINGS_SCHEMA = {
+  id: SETTINGS_ID,
+  title: "Worker model categories",
+  schemaVersion: 1,
+  fields: [
+    {
+      key: "categories",
+      type: "list",
+      label: "Categories",
+      description:
+        'Named model tiers the orchestrator can spawn workers on. Write the "When to use" prose as absolute guidance — it is the routing policy.',
+      minItems: 0,
+      maxItems: 4,
+      itemFields: [
+        { key: "name", type: "text", label: "Name", required: true, maxLength: 24, uniqueCaseInsensitive: true },
+        { key: "model", type: "select", label: "Model", optionsSource: "models", required: true },
+        { key: "description", type: "textarea", label: 'When to use', maxLength: 400 },
+      ],
+    },
+    {
+      key: "defaultCategory",
+      type: "select",
+      label: "Default category",
+      description: "Used when a spawn omits an explicit category.",
+      optionsFromField: "categories.name",
+    },
+  ],
+};
+
+const PORT = Number(process.env.PORT || 8787);
+const TOKEN = process.env.PI_WEB_TOKEN || "";
+const BASE = `http://127.0.0.1:${PORT}`;
+
+// ---------------------------------------------------------------------------
+// Global helpers: token parsing, resolution
+// ---------------------------------------------------------------------------
+
+/** Parse "<provider>:<id>" into { provider, id }. Split on FIRST colon only. */
+function parseToken(token: string): { provider: string; id: string } | null {
+  const idx = token.indexOf(":");
+  if (idx < 0) return null;
+  return { provider: token.slice(0, idx), id: token.slice(idx + 1) };
+}
+
+/** Determine if normalized id base matches (Bedrock inference-profile case). */
+function normalizeBedrockId(id: string): string {
+  // Extract base (e.g. "us.amazon.nova-2-lite-v1" from "us.amazon.nova-2-lite-v1:0")
+  return id.split(":")[0];
+}
+
+/** Resolution order per Amendment 6. Returns { match, substituted }. */
+function resolveModel(
+  canonicalToken: string,
+  registryModels: any[],
+  parentRegionPrefix: string,
+): { match: any; substituted: boolean } | null {
+  const canonical = parseToken(canonicalToken);
+  if (!canonical) return null;
+
+  const { provider, id } = canonical;
+
+  // 1. Exact {provider, id} match.
+  const exact = registryModels.find((m: any) => m.provider === provider && m.id === id);
+  if (exact) return { match: exact, substituted: false };
+
+  // 2. Same provider + same normalized base id + parent region prefix (Bedrock case).
+  if (parentRegionPrefix) {
+    const baseId = normalizeBedrockId(id);
+    const withPrefix = parentRegionPrefix + baseId.slice(baseId.match(/^(us|eu|au|apac|global)\./)  ?.[0]?.length || 0);
+    const candidate = registryModels.find(
+      (m: any) => m.provider === provider && normalizeBedrockId(m.id) === normalizeBedrockId(withPrefix),
+    );
+    if (candidate) return { match: candidate, substituted: true };
+  }
+
+  // 3. Else failure.
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Small HTTP client for the pi-web API (same API the browser UI uses)
+// ---------------------------------------------------------------------------
+
+async function api(method: string, path: string, body?: unknown): Promise<any> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: {
+      ...(TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {}),
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(20_000),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || json?.ok === false) {
+    throw new Error(`${method} ${path} failed (${res.status}): ${json?.error || "unknown error"}`);
+  }
+  return json;
+}
+
+function trunc(value: unknown, max: number): string {
+  const text = String(value ?? "").trim();
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1)}…`;
+}
+
+function shortId(id: string): string {
+  return id.length > 8 ? id.slice(-8) : id;
+}
+
+// ---------------------------------------------------------------------------
+// Transcript helpers (uses /api/messages simplified message shape)
+// ---------------------------------------------------------------------------
+
+async function fetchMessages(sessionId: string): Promise<any[]> {
+  const json = await api("GET", `/api/messages?sessionId=${encodeURIComponent(sessionId)}`);
+  return Array.isArray(json.messages) ? json.messages : [];
+}
+
+function lastAssistantText(messages: any[]): { text: string; isError: boolean } {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role === "assistant" && typeof m.text === "string" && m.text.trim()) {
+      return { text: m.text.trim(), isError: Boolean(m.isError) };
+    }
+  }
+  return { text: "", isError: false };
+}
+
+function shortArgs(args: Record<string, unknown> | undefined): string {
+  if (!args || typeof args !== "object") return "";
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(args)) {
+    parts.push(`${key}: ${trunc(typeof value === "string" ? value : JSON.stringify(value), 60)}`);
+    if (parts.join(", ").length > 140) break;
+  }
+  return trunc(parts.join(", "), 160);
+}
+
+function formatTranscript(messages: any[], tail: number): string {
+  const slice = messages.slice(-tail);
+  const lines: string[] = [];
+  if (messages.length > slice.length) lines.push(`… (${messages.length - slice.length} earlier entries omitted; increase tail to see more)`);
+  for (const m of slice) {
+    if (!m || typeof m !== "object") continue;
+    if (m.role === "user") {
+      lines.push(`[user] ${trunc(m.text, 400)}`);
+    } else if (m.role === "assistant") {
+      if (m.text) lines.push(`[assistant] ${trunc(m.text, 700)}`);
+      for (const call of m.toolCalls || []) {
+        lines.push(`  → ${call.toolName}(${shortArgs(call.args)})`);
+      }
+    } else if (m.role === "toolResult") {
+      lines.push(`  ${m.isError ? "✗" : "✓"} ${m.toolName}: ${trunc(m.text, 200)}`);
+    } else if (m.role === "bashExecution") {
+      lines.push(`  $ ${trunc(m.command, 160)}`);
+      if (m.output) lines.push(`    ${trunc(m.output, 200)}`);
+    }
+  }
+  return lines.join("\n") || "(no messages)";
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+export default function sessionOrchestrator(pi: ExtensionAPI) {
+  type Watched = {
+    id: string;
+    name: string;
+    sawRunning: boolean;
+    idlePolls: number;
+    errorPolls: number;
+    aborted: boolean;
+  };
+
+  const watched = new Map<string, Watched>();
+  let cachedConfig: { categories: any[]; defaultCategory: string } = { categories: [], defaultCategory: "" };
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let pollInFlight = false;
+  let selfSessionId = "";
+
+  // Capture our own session id whenever context is available; used to route
+  // wakeups through /api/prompt (the same battle-tested path the web UI uses
+  // for steering), which works both when the parent is idle and mid-turn.
+  function captureSelf(ctx: any) {
+    const id = ownSessionId(ctx);
+    if (id && id !== "unknown") selfSessionId = id;
+  }
+
+  function isWorkerSession(ctx: any): boolean {
+    try {
+      const entries = ctx.sessionManager?.getBranch?.() || [];
+      for (const entry of entries) {
+        if (entry?.type !== "message") continue;
+        const message = entry.message;
+        if (message?.role !== "user") continue;
+        const content = message.content;
+        const text = typeof content === "string"
+          ? content
+          : Array.isArray(content)
+            ? content.map((part: any) => (part?.type === "text" ? part.text : "")).join(" ")
+            : "";
+        return text.includes(WORKER_MARKER);
+      }
+    } catch {
+      // If we cannot tell, err on the side of allowing.
+    }
+    return false;
+  }
+
+  function ownSessionId(ctx: any): string {
+    try {
+      return String(ctx.sessionManager?.getSessionId?.() ?? ctx.sessionManager?.getId?.() ?? "unknown");
+    } catch {
+      return "unknown";
+    }
+  }
+
+  function ownCwd(ctx: any): string | undefined {
+    try {
+      const cwd = ctx.sessionManager?.getCwd?.();
+      return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function ensureTimer() {
+    if (!timer && watched.size > 0) timer = setInterval(() => void poll(), POLL_MS);
+  }
+
+  function stopTimerIfIdle() {
+    if (timer && watched.size === 0) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  }
+
+  function watch(id: string, name: string) {
+    watched.set(id, { id, name, sawRunning: false, idlePolls: 0, errorPolls: 0, aborted: false });
+    ensureTimer();
+  }
+
+  function unwatch(id: string) {
+    watched.delete(id);
+    stopTimerIfIdle();
+  }
+
+  function appendLedger(customType: string, childId: string, name?: string) {
+    try {
+      pi.appendEntry(customType, { childId, ...(name ? { name } : {}) });
+    } catch (error) {
+      console.error(`[session-orchestrator] could not append ${customType} entry: ${error instanceof Error ? error.message : error}`);
+    }
+  }
+
+  function markChildRead(childId: string) {
+    api("POST", "/api/session-ui-state/read", { sessionId: childId })
+      .catch((error) => console.error(`[session-orchestrator] could not mark child read: ${error instanceof Error ? error.message : error}`));
+  }
+
+  function outstandingWatches(ctx: any): Map<string, string> {
+    const watches = new Map<string, string>();
+    try {
+      for (const entry of ctx.sessionManager?.getBranch?.() || []) {
+        if (entry?.type !== "custom") continue;
+        const childId = typeof entry.data?.childId === "string" ? entry.data.childId : "";
+        if (!childId) continue;
+        if (entry.customType === WATCH_ENTRY) watches.set(childId, typeof entry.data?.name === "string" ? entry.data.name : childId.slice(-8));
+        else if (entry.customType === RESOLVED_ENTRY) watches.delete(childId);
+      }
+    } catch (error) {
+      console.error(`[session-orchestrator] could not read watch ledger: ${error instanceof Error ? error.message : error}`);
+    }
+    return watches;
+  }
+
+  // =========================================================================
+  // Tool builder and settings registration
+  // =========================================================================
+
+  function buildSpawnTool(ctx: any): any {
+    let description = [
+      "Spawn a new pi-web worker session and give it a task. The worker runs in the background as a normal, fully visible pi-web session.",
+      "Returns immediately with the worker's session id. When the worker goes idle you will receive a '🔔 [orchestrator]' user message containing its final output — do NOT poll for completion; do other, non-overlapping work or end your turn and wait.",
+      "Do not redo what you just delegated: after spawning, use judgement about whether you need to do work yourself at all. Doing it yourself is right when you need the answer to plan the next step, when the worker may fail or is slow and the check is cheap, or when there is genuinely complementary work (design, drafting, scaffolding, verifying a worker's claims). Otherwise end your turn — idling costs nothing and keeps the noisy exploration out of your context.",
+      "Write the task so it is self-contained (the worker has none of your context): include relevant file paths, constraints, and what evidence to report back (diffs, test output, findings with file:line).",
+    ];
+
+    let categoryDescription = "";
+    let hasConfig = false;
+    {
+      const values = cachedConfig || { categories: [], defaultCategory: "" };
+      const categories = Array.isArray(values.categories) ? values.categories : [];
+      const defaultCategory = values.defaultCategory || "";
+      if (categories.length > 0) {
+        hasConfig = true;
+        const categoryLines: string[] = [];
+        for (const cat of categories) {
+          if (cat && typeof cat === "object") {
+            const name = String(cat.name || "").trim();
+            const desc = String(cat.description || "").trim();
+            const isDefault = name === defaultCategory ? " (default)" : "";
+            const line = desc ? `• **${name}**${isDefault}: ${desc}` : `• **${name}**${isDefault}`;
+            categoryLines.push(line);
+          }
+        }
+        if (categoryLines.length > 0) {
+          categoryDescription = `Configured categories:\n${categoryLines.join("\n")}`;
+        }
+      }
+    }
+
+    if (!hasConfig) {
+      categoryDescription = "No categories are configured. The worker will use the session's default model. Configure categories in extension settings to choose specific models.";
+    }
+
+    description.push("");
+    description.push(categoryDescription);
+
+    const parameterDescription =
+      "Category name (from settings) that selects the worker's model. Defaults to the configured default category, or the session default if no config exists. Unknown category → error, nothing created; valid names are listed in the tool description.";
+
+    return {
+      name: "sessions_spawn",
+      label: "Spawn worker session",
+      description: description.join(" "),
+      promptSnippet: "Spawn a background worker session for a delegated task; completion arrives as a wakeup message",
+      promptGuidelines: [
+        "Use sessions_spawn to delegate noisy or parallelizable work (exploration, running tests, an isolated implementation step) to a worker session instead of doing it inline. After spawning, either do complementary work that does not duplicate what you delegated, or end your turn — a wakeup message arrives when the worker is done. Use judgement: re-doing a worker's task yourself is only worth it when you need the result to proceed, or the check is cheap and the worker may be wrong.",
+      ],
+      parameters: Type.Object({
+        name: Type.String({ description: "Short human-readable worker name, e.g. 'scout: auth flow' or 'fix lint'" }),
+        task: Type.String({ description: "Self-contained task prompt for the worker, including what to report back" }),
+        cwd: Type.Optional(Type.String({ description: "Working directory for the worker (defaults to this session's cwd)" })),
+        category: Type.Optional(Type.String({ description: parameterDescription })),
+      }),
+      execute: async (_toolCallId: string, params: any, _signal: any, _onUpdate: any, ctx: any) => {
+        if (isWorkerSession(ctx)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Refused: this session is itself an orchestrated worker (depth cap is 1). Report back to your parent instead of spawning sub-workers.",
+              },
+            ],
+            isError: true,
+            details: {},
+          };
+        }
+        if (watched.size >= MAX_WORKERS) {
+          return {
+            content: [{ type: "text", text: `Refused: already tracking ${watched.size} running workers (cap ${MAX_WORKERS}). Wait for a wakeup or abort one first.` }],
+            isError: true,
+            details: {},
+          };
+        }
+
+        const parentId = ownSessionId(ctx);
+        const parentCwd = ownCwd(ctx);
+
+        // ====================================================================
+        // Phase 1: Resolve category → canonical {provider, id} from config
+        // ====================================================================
+
+        let resolvedToken: { provider: string; id: string } | null = null;
+        let categoryName = params.category || "";
+        let validCategories: string[] = [];
+
+        try {
+          const web = ctx?.ui?.web;
+          if (web?.getSettings) {
+            const settings = await web.getSettings(SETTINGS_ID);
+            if (settings && typeof settings === "object") {
+              const values = settings.values || {};
+              cachedConfig = { categories: Array.isArray(values.categories) ? values.categories : [], defaultCategory: values.defaultCategory || "" };
+              const categories = Array.isArray(values.categories) ? values.categories : [];
+              const defaultCategory = values.defaultCategory || "";
+
+              // Empty config → virtual Default, skip resolution, use session default.
+              if (categories.length === 0) {
+                resolvedToken = null; // Signals: use session default
+              } else {
+                // Collect valid names.
+                for (const cat of categories) {
+                  if (cat && typeof cat === "object" && cat.name) {
+                    validCategories.push(String(cat.name));
+                  }
+                }
+
+                // Resolve category name.
+                if (!categoryName) {
+                  categoryName = defaultCategory;
+                }
+
+                if (!categoryName) {
+                  return {
+                    content: [
+                      {
+                        type: "text",
+                        text: `ERROR: category omitted and no default is configured. Valid categories: ${validCategories.join(", ") || "(none configured)"}. Set a default in extension settings or pass an explicit category name.`,
+                      },
+                    ],
+                    isError: true,
+                    details: { validCategories },
+                  };
+                }
+
+                // Find matching category.
+                const matching = categories.find(
+                  (cat: any) => cat && typeof cat === "object" && cat.name && String(cat.name).toLowerCase() === String(categoryName).toLowerCase(),
+                );
+                if (!matching || !matching.model) {
+                  return {
+                    content: [
+                      {
+                        type: "text",
+                        text: `ERROR: category "${categoryName}" not found or has no model configured. Valid categories: ${validCategories.join(", ") || "(none configured)"}`,
+                      },
+                    ],
+                    isError: true,
+                    details: { validCategories, categoryName },
+                  };
+                }
+
+                resolvedToken = parseToken(String(matching.model));
+                if (!resolvedToken) {
+                  return {
+                    content: [
+                      {
+                        type: "text",
+                        text: `ERROR: category "${categoryName}" model token is malformed (expected "<provider>:<id>", got "${matching.model}"). Check extension settings.`,
+                      },
+                    ],
+                    isError: true,
+                    details: { validCategories },
+                  };
+                }
+              }
+            }
+          }
+        } catch (error) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `ERROR: failed to read category config: ${error instanceof Error ? error.message : error}. Categories unavailable; please check extension settings.`,
+              },
+            ],
+            isError: true,
+            details: {},
+          };
+        }
+
+        // ====================================================================
+        // Phase 2: Create unprompted session
+        // ====================================================================
+
+        let sessionId = "";
+        try {
+          const created = await api("POST", "/api/new-chat", {
+            cwd: params.cwd || parentCwd,
+            ...(parentId && parentId !== "unknown" ? { origin: { sessionId: parentId, kind: "spawn" } } : {}),
+          });
+          sessionId = String(created.sessionId || "");
+          if (!sessionId) throw new Error("new-chat did not return a sessionId");
+        } catch (error) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `ERROR: failed to create worker session: ${error instanceof Error ? error.message : error}`,
+              },
+            ],
+            isError: true,
+            details: {},
+          };
+        }
+
+        const displayName = params.name;
+        await api("POST", "/api/session/name", { sessionId, name: displayName }).catch(() => {});
+
+        let modelNote = "";
+        let modelSummary = "session default";
+
+        // ====================================================================
+        // Phase 3: Resolve against worker's registry (if config provided)
+        // ====================================================================
+
+        if (resolvedToken) {
+          try {
+            const { models } = await api("GET", `/api/models?sessionId=${encodeURIComponent(sessionId)}`);
+            const registryModels = Array.isArray(models) ? models : [];
+
+            // Get parent region prefix for fallback.
+            let parentRegionPrefix = "";
+            try {
+              const parentState = await api("GET", `/api/state?sessionId=${encodeURIComponent(parentId)}`);
+              parentRegionPrefix = String(parentState?.model?.id || "").match(/^(us|eu|au|apac|global)\./)  ?.[0] || "";
+            } catch { /* best effort */ }
+
+            const resolution = resolveModel(
+              `${resolvedToken.provider}:${resolvedToken.id}`,
+              registryModels,
+              parentRegionPrefix,
+            );
+
+            if (!resolution) {
+              // Resolution failed → delete session and error.
+              await api("POST", "/api/sessions/delete", { sessionId }).catch(() => {});
+              const availableProviders = Array.from(new Set(registryModels.map((m: any) => m.provider)));
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `ERROR: configured model "${resolvedToken.provider}:${resolvedToken.id}" for category "${categoryName}" is not available in this session's registry. Available providers: ${availableProviders.join(", ") || "(none)"}. Valid categories for this spawn: ${validCategories.join(", ") || "(none configured)"}. Session ${sessionId} was created but then deleted (no orphan).`,
+                  },
+                ],
+                isError: true,
+                details: { sessionId, validCategories, categoryName, requestedModel: `${resolvedToken.provider}:${resolvedToken.id}`, availableProviders },
+              };
+            }
+
+            const { match, substituted } = resolution;
+
+            // ================================================================
+            // Phase 4: Set model on worker
+            // ================================================================
+
+            await api("POST", "/api/model", { sessionId, provider: match.provider, id: match.id });
+            modelNote = `category "${categoryName}" → model ${match.provider}/${match.id}`;
+            modelSummary = `${match.provider}/${match.id}`;
+
+            if (substituted) {
+              modelNote += ` (substituted region prefix from parent)`;
+            }
+          } catch (error) {
+            // Model resolution error → delete session and error.
+            await api("POST", "/api/sessions/delete", { sessionId }).catch(() => {});
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `ERROR: failed to resolve model for category "${categoryName}": ${error instanceof Error ? error.message : error}. Session ${sessionId} was created but then deleted (no orphan). Valid categories: ${validCategories.join(", ") || "(none configured)"}`,
+                },
+              ],
+              isError: true,
+              details: { sessionId, validCategories, categoryName },
+            };
+          }
+        }
+
+        // ====================================================================
+        // Phase 5: Dispatch task
+        // ====================================================================
+
+        const prompt = [
+          `${WORKER_MARKER} You are a worker session spawned by session ${parentId} to do one task. Work autonomously; the spawner cannot answer questions mid-task, so make reasonable assumptions and note them.`,
+          `When finished, end your final message with a concise report: what you did/found, files touched (with paths), and how you verified it. Do not spawn other sessions.`,
+          ``,
+          `TASK: ${params.task}`,
+        ].join("\n");
+        await api("POST", "/api/prompt", { sessionId, message: prompt });
+
+        watch(sessionId, params.name);
+        appendLedger(WATCH_ENTRY, sessionId, params.name);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Spawned worker "${params.name}" (session ${sessionId}, ${modelSummary}) [ext ${EXT_VERSION}]. It is running in the background as a normal pi-web session named "${displayName}". ${modelNote ? `Used ${modelNote}.` : ""} You'll receive a 🔔 wakeup message when it goes idle — do not poll. Continue other work, spawn more workers, or end your turn to wait.`,
+            },
+          ],
+          details: { sessionId, name: params.name, cwd: params.cwd || parentCwd, modelSummary } as Record<string, unknown>,
+        };
+      },
+    };
+  }
+
+  async function registerTools(ctx: any) {
+    try {
+      const web = ctx?.ui?.web;
+      if (web?.getSettings) {
+        const s = await web.getSettings(SETTINGS_ID);
+        if (s && typeof s === "object" && s.values) {
+          cachedConfig = {
+            categories: Array.isArray(s.values.categories) ? s.values.categories : [],
+            defaultCategory: s.values.defaultCategory || "",
+          };
+        }
+      }
+    } catch {}
+    pi.registerTool(buildSpawnTool(ctx));
+  }
+
+  pi.on("session_start", async (_event: any, ctx: any) => {
+    captureSelf(ctx);
+    void rearmFromLedger(ctx);
+    try {
+      const web = ctx?.ui?.web;
+      if (web?.registerSettings) {
+        await registerTools(ctx);
+        const result = await web.registerSettings({
+          ...SETTINGS_SCHEMA,
+          onChange: () => {
+            // Category config changed: rebuild tool to update description.
+            void registerTools(ctx);
+          },
+        });
+        if (result && result.registered === false && result.error) {
+          console.warn(`[session-orchestrator ${EXT_VERSION}] settings registration rejected: ${result.error}`);
+        }
+      }
+    } catch (error) {
+      console.warn(`[session-orchestrator ${EXT_VERSION}] settings registration failed:`, error);
+    }
+  });
+  pi.on("turn_start", (_event: any, ctx: any) => captureSelf(ctx));
+
+  /**
+   * On session (re)load: resume watching children that are still running, and
+   * deliver catch-up wakeups for children that finished while this session was
+   * not in memory (server restart, /reload, idle disposal).
+   */
+  async function rearmFromLedger(ctx: any) {
+    const outstanding = outstandingWatches(ctx);
+    for (const id of watched.keys()) outstanding.delete(id);
+    if (outstanding.size === 0) return;
+
+    const finished: { id: string; name: string; summary: { text: string; isError: boolean } }[] = [];
+    for (const [childId, name] of outstanding) {
+      try {
+        const state = await api("GET", `/api/state?sessionId=${encodeURIComponent(childId)}`);
+        const running = Boolean(state?.runtime?.isRunning) || Number(state?.runtime?.pendingMessageCount || 0) > 0;
+        if (running) {
+          watch(childId, name);
+          continue;
+        }
+        let summary = { text: "", isError: false };
+        try {
+          summary = lastAssistantText(await fetchMessages(childId));
+        } catch { /* best effort */ }
+        finished.push({ id: childId, name, summary });
+      } catch {
+        // Child gone (deleted?) — resolve so we don't retry forever.
+        appendLedger(RESOLVED_ENTRY, childId);
+      }
+    }
+    if (finished.length === 0) return;
+
+    const details = {
+      kind: "wakeup",
+      catchUp: true,
+      workers: finished.map((f) => ({ sessionId: f.id, name: f.name, status: f.summary.isError ? "error" : "idle" })),
+      stillRunning: Array.from(watched.values()).map((o) => ({ sessionId: o.id, name: o.name })),
+    };
+    const sections = finished.map((f) => [
+      `Worker "${f.name}" (session ${f.id}) finished while this session was offline.`,
+      f.summary.text
+        ? `${f.summary.isError ? "⚠️ Its last turn ENDED WITH AN ERROR (task likely incomplete):\n" : "Final message:\n"}${trunc(f.summary.text, WAKEUP_SUMMARY_CHARS)}`
+        : `(no final message captured)`,
+    ].join("\n"));
+    const ok = await deliverWakeup([
+      `🔔 [orchestrator] Catch-up: ${finished.length === 1 ? "a worker" : `${finished.length} workers`} finished while this session was not loaded.`,
+      ``,
+      sections.join("\n\n---\n\n"),
+      ``,
+      `You can inspect details with sessions_read, follow up or redirect with sessions_prompt, or continue with your task.`,
+    ].join("\n"), details);
+    if (ok) {
+      for (const f of finished) {
+        appendLedger(RESOLVED_ENTRY, f.id);
+        markChildRead(f.id);
+      }
+    }
+  }
+
+  /** Deliver a wakeup to this session. Returns true only if delivery succeeded. */
+  async function deliverWakeup(text: string, details?: Record<string, unknown>): Promise<boolean> {
+    // Preferred: pi custom message — typed, persisted, reaches the LLM as a
+    // user message, and carries structured details for the pi-web UI card.
+    try {
+      await pi.sendMessage(
+        { customType: WAKEUP_CUSTOM_TYPE, content: text, display: true, details },
+        { triggerTurn: true, deliverAs: "steer" },
+      );
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (/stale/i.test(message)) {
+        // This extension instance was replaced (e.g. /reload). The new
+        // instance re-arms from the persisted watch ledger and owns delivery
+        // now — falling back here would double-deliver. Go silent and stop.
+        console.error("[session-orchestrator] instance is stale after reload; stopping watcher (ledger hands off to the new instance)");
+        if (timer) clearInterval(timer);
+        timer = undefined;
+        watched.clear();
+        return false;
+      }
+      console.error(`[session-orchestrator] custom-message wakeup failed, falling back to /api/prompt: ${message}`);
+    }
+    if (selfSessionId) {
+      try {
+        await api("POST", "/api/prompt", { sessionId: selfSessionId, message: text, mode: "steer" });
+        return true;
+      } catch (error) {
+        console.error(`[session-orchestrator] wakeup via /api/prompt failed: ${error instanceof Error ? error.message : error}`);
+      }
+    }
+    try {
+      pi.sendUserMessage(text);
+      return true;
+    } catch {
+      try {
+        pi.sendUserMessage(text, { deliverAs: "steer" });
+        return true;
+      } catch (error) {
+        console.error(`[session-orchestrator] wakeup delivery failed entirely: ${error instanceof Error ? error.message : error}`);
+      }
+    }
+    return false;
+  }
+
+  async function poll() {
+    if (pollInFlight) return;
+    pollInFlight = true;
+    try {
+      const completed: { w: Watched; summary: { text: string; isError: boolean } }[] = [];
+      for (const w of Array.from(watched.values())) {
+        try {
+          const state = await api("GET", `/api/state?sessionId=${encodeURIComponent(w.id)}`);
+          const running = Boolean(state?.runtime?.isRunning ?? (state?.isStreaming || state?.isCompacting));
+          const pending = Number(state?.runtime?.pendingMessageCount || 0);
+          w.errorPolls = 0;
+          if (running || pending > 0) {
+            w.sawRunning = true;
+            w.idlePolls = 0;
+            continue;
+          }
+          w.idlePolls += 1;
+          // Fast tasks may finish between polls; if we never saw it running,
+          // wait a few polls before concluding it is done.
+          const settled = w.sawRunning ? w.idlePolls >= 1 : w.idlePolls >= 4;
+          if (!settled) continue;
+
+          unwatch(w.id);
+          let summary = { text: "", isError: false };
+          try {
+            summary = lastAssistantText(await fetchMessages(w.id));
+          } catch {
+            // Transcript fetch is best-effort.
+          }
+          completed.push({ w, summary });
+        } catch {
+          w.errorPolls += 1;
+          if (w.errorPolls >= 20) {
+            unwatch(w.id);
+            void (async () => {
+              const ok = await deliverWakeup(
+                `🔔 [orchestrator] Lost track of worker "${w.name}" (session ${w.id}): status polling kept failing (it may have been deleted). Check it with sessions_status or in the sidebar.`,
+                { kind: "wakeup", workers: [{ sessionId: w.id, name: w.name, status: "error" }] },
+              );
+              if (ok) appendLedger(RESOLVED_ENTRY, w.id);
+            })();
+          }
+        }
+      }
+
+      // Batch all completions from this poll cycle into ONE message. Sending
+      // two user messages back-to-back while the parent is idle races the
+      // turn-start and can drop the second message.
+      if (completed.length > 0) {
+        const stillRunning = Array.from(watched.values()).map((o) => `"${o.name}"`).join(", ");
+        const details = {
+          kind: "wakeup",
+          workers: completed.map(({ w, summary }) => ({
+            sessionId: w.id,
+            name: w.name,
+            status: w.aborted ? "aborted" : summary.isError ? "error" : "idle",
+          })),
+          stillRunning: Array.from(watched.values()).map((o) => ({ sessionId: o.id, name: o.name })),
+        };
+        const sections = completed.map(({ w, summary }) => [
+          `Worker "${w.name}" (session ${w.id}) is now ${w.aborted ? "stopped (aborted)" : "idle"}.`,
+          summary.text
+            ? `${summary.isError ? "⚠️ Its last turn ENDED WITH AN ERROR (task likely incomplete — inspect with sessions_read, then retry or fix):\n" : "Final message:\n"}${trunc(summary.text, WAKEUP_SUMMARY_CHARS)}`
+            : `(no final message captured)`,
+        ].join("\n"));
+        const ok = await deliverWakeup([
+          `🔔 [orchestrator] ${completed.length === 1 ? "A worker finished." : `${completed.length} workers finished.`}`,
+          ``,
+          sections.join("\n\n---\n\n"),
+          ``,
+          stillRunning ? `Still running: ${stillRunning}.` : `No other workers are running.`,
+          `You can inspect details with sessions_read, follow up or redirect with sessions_prompt, or continue with your task.`,
+        ].join("\n"), details);
+        if (ok) {
+          for (const { w } of completed) {
+            appendLedger(RESOLVED_ENTRY, w.id);
+            // The report was consumed by this session on the user's behalf —
+            // clear the child's unread dot via the normal read endpoint.
+            markChildRead(w.id);
+          }
+        }
+      }
+    } finally {
+      pollInFlight = false;
+    }
+  }
+
+  // =========================================================================
+  // Other tools (unchanged from original)
+  // =========================================================================
+
+  // -------------------------------------------------------------------------
+  // sessions_status
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "sessions_status",
+    label: "Worker session status",
+    description: "Get a one-line status (running/idle, model, cost, message counts) for worker sessions. With no ids, reports all workers spawned from this session that are still tracked. Prefer waiting for wakeup messages over calling this in a loop.",
+    promptSnippet: "Check status of spawned worker sessions",
+    parameters: Type.Object({
+      ids: Type.Optional(Type.Array(Type.String(), { description: "Session ids to check (defaults to all tracked workers)" })),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      const ids: string[] = params.ids?.length ? params.ids : Array.from(watched.keys());
+      if (ids.length === 0) {
+        return { content: [{ type: "text", text: "No tracked workers. (Workers you already received a wakeup for are untracked; pass their session id explicitly to check them.)" }], details: {} };
+      }
+      const lines: string[] = [];
+      for (const id of ids) {
+        try {
+          const state = await api("GET", `/api/state?sessionId=${encodeURIComponent(id)}`);
+          const running = Boolean(state?.runtime?.isRunning);
+          const stats = state?.stats || {};
+          const name = state?.sessionName || state?.sessionTitle || shortId(id);
+          const model = state?.model?.id || "?";
+          lines.push(`${running ? "⏳ RUNNING" : "✔ idle"} — "${name}" (${id}) — model ${model} — $${Number(stats.cost || 0).toFixed(2)} — ${Number(stats.assistantMessages || 0)} assistant msgs${state?.runtime?.pendingMessageCount ? ` — ${state.runtime.pendingMessageCount} queued` : ""}`);
+        } catch (error) {
+          lines.push(`? — ${id} — status unavailable (${error instanceof Error ? error.message : error})`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // sessions_read
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "sessions_read",
+    label: "Read worker transcript",
+    description: "Read the tail of a session's transcript (compact rendering: user/assistant text, tool calls one-line each). Use to review a worker's work or diagnose one that's going down the wrong path. Keep tails small — don't pull a worker's full process back into your context.",
+    promptSnippet: "Read the recent transcript of another session",
+    parameters: Type.Object({
+      id: Type.String({ description: "Session id" }),
+      tail: Type.Optional(Type.Number({ description: "How many trailing entries to include (default 20)" })),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      const messages = await fetchMessages(params.id);
+      const text = formatTranscript(messages, Math.max(1, Math.min(200, params.tail || 20)));
+      return { content: [{ type: "text", text }], details: { sessionId: params.id, totalMessages: messages.length } };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // sessions_prompt
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "sessions_prompt",
+    label: "Message worker session",
+    description: "Send a message to another session, exactly like a user typing into it. If it is mid-turn the message is delivered as steering after the current tool calls; set interrupt=true to abort its current turn first (use when it's going down the wrong path). You'll receive a wakeup when it next goes idle.",
+    promptSnippet: "Send a follow-up or steering message to a worker session (interrupt optional)",
+    parameters: Type.Object({
+      id: Type.String({ description: "Session id" }),
+      message: Type.String({ description: "The message to deliver" }),
+      interrupt: Type.Optional(Type.Boolean({ description: "Abort the session's current turn before delivering (default false)" })),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      if (params.interrupt) {
+        await api("POST", "/api/abort", { sessionId: params.id });
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+      await api("POST", "/api/prompt", { sessionId: params.id, message: params.message, mode: "steer" });
+      if (!watched.has(params.id)) {
+        let name = shortId(params.id);
+        try {
+          const state = await api("GET", `/api/state?sessionId=${encodeURIComponent(params.id)}`);
+          name = String(state?.sessionName || state?.sessionTitle || name).replace(/^[⑂⤑]\s*/, "");
+        } catch { /* best effort */ }
+        watch(params.id, name);
+        appendLedger(WATCH_ENTRY, params.id, name);
+      }
+      return { content: [{ type: "text", text: `${params.interrupt ? "Interrupted and redirected" : "Message delivered to"} session ${params.id}. You'll get a 🔔 wakeup when it goes idle.` }], details: {} };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // sessions_abort
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "sessions_abort",
+    label: "Abort worker session",
+    description: "Abort another session's current turn and stop tracking it. The session itself remains in the sidebar and can be resumed later with sessions_prompt.",
+    promptSnippet: "Abort a worker session's current turn",
+    parameters: Type.Object({
+      id: Type.String({ description: "Session id" }),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      await api("POST", "/api/abort", { sessionId: params.id });
+      unwatch(params.id);
+      appendLedger(RESOLVED_ENTRY, params.id);
+      return { content: [{ type: "text", text: `Aborted session ${params.id} and stopped tracking it.` }], details: {} };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  pi.on("session_shutdown", () => {
+    if (timer) clearInterval(timer);
+    timer = undefined;
+    watched.clear();
+  });
+}
diff --git a/examples/pi-web-skills/session-orchestration/SKILL.md b/examples/pi-web-skills/session-orchestration/SKILL.md
new file mode 100644
index 0000000..5184177
--- /dev/null
+++ b/examples/pi-web-skills/session-orchestration/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: session-orchestration
+description: Orchestrate pi-web worker sessions with the sessions_spawn / sessions_status / sessions_read / sessions_prompt / sessions_abort tools. Use when a task has noisy or parallelizable parts worth delegating to background worker sessions (exploration, running test suites, isolated implementation steps), or when the user asks you to delegate, parallelize, or spawn workers.
+---
+
+# Session orchestration
+
+You have tools that give you the same powers a human has in the pi-web UI:
+spawn sessions, watch them, message them, interrupt them. Workers are ordinary
+pi-web sessions — fully visible in the sidebar (indented under this session), with
+complete transcripts the user can open, watch, and even type into.
+
+## The core loop
+
+1. `sessions_spawn { name, task, category?, cwd? }` — returns immediately with a session id.
+2. Do other useful work that **does not overlap what you just delegated**, spawn more
+   workers, or **end your turn**.
+3. When a worker goes idle, a `🔔 [orchestrator]` user message arrives with its
+   final output. This starts a new turn for you if you were idle.
+4. Review, then either finish, `sessions_prompt` a follow-up, or spawn the next phase.
+
+Wakeups are durable: watches are persisted in your session file, so if this
+session is reloaded or the server restarts, watchers re-arm on load and any
+workers that finished in the meantime produce catch-up wakeups.
+
+**Never poll for completion.** Do not call `sessions_status` in a loop and do
+not sleep in bash while waiting. Wakeups are pushed to you. Ending your turn
+while workers run is correct and costs nothing; you will be woken.
+
+**Don't re-do what you just delegated.** The most common failure is spawning
+scouts and then immediately running the same greps, reads and inventories
+yourself — which burns tokens twice and dumps into your context exactly the
+noise delegation was meant to keep out. Use judgement about whether you should
+be working at all while workers run:
+
+- *Work yourself* when: you need a result now to plan the next step or write the
+  next worker's task; there is genuinely complementary work (design decisions,
+  drafting the deliverable, scaffolding files, setting up a worktree); or a
+  worker's claim is load-bearing and cheap to verify (one command, one file).
+- *End your turn* when: your only remaining moves are the tasks you handed out,
+  or your "parallel work" would mostly be reading things a worker will summarize
+  for you anyway. Waiting is a legitimate, cheap action.
+
+When in doubt, prefer ending the turn: you can always do the work after the
+wakeup, with the worker's findings in hand.
+
+## What to delegate (and what not to)
+
+Delegate when the *process* is much bigger than the *conclusion*:
+
+- Codebase exploration ("where is X handled? report file:line + 5-line summary")
+- Running test suites / builds / lint and triaging output
+- An isolated, well-specified implementation step
+- Anything you'd hate to have polluting your context afterwards
+
+Keep for yourself: decisions, design, anything needing the context you've
+accumulated with the user, and small quick edits (spawning has ~seconds of
+overhead and a worker starts with zero context).
+
+## Writing good worker tasks
+
+Workers know NOTHING about your conversation. In `task`, include:
+
+- Concrete goal, relevant paths, constraints, and what NOT to touch.
+- What evidence to report: findings with file:line, diffs/files touched, exact
+  test output. Ask for a compact report — you want conclusions, not narrative.
+- For risky/overlapping edits, give each worker a separate git worktree via
+  `cwd`, or make edits disjoint by construction.
+
+Choose the worker's model by **category**, deliberately. Categories are
+user-authored (name + "when to use" prose) and listed in the `sessions_spawn`
+tool description — pick by the sub-task's nature: a cheap/fast category for
+scouting and mechanical chores; a stronger category for real implementation.
+The prose in each category is the routing guidance — follow it. Omit `category`
+to use the configured default. If no categories are configured, the worker uses
+the session's default model. Never guess model ids; pass a category **name**.
+
+## Steering and reviewing
+
+- `sessions_status` — quick glance (running/idle, cost). Fine occasionally,
+  e.g. before ending a message to the user.
+- `sessions_read { id, tail }` — compact transcript tail. Use it to review
+  evidence or diagnose a struggling worker. Keep tails small; do not import a
+  worker's whole process into your context.
+- `sessions_prompt { id, message, interrupt? }` — follow up, or with
+  `interrupt: true` stop a worker that is going down the wrong path and
+  redirect it. Also works to re-engage a worker that already went idle.
+- `sessions_abort { id }` — stop a worker you no longer need.
+
+Trust evidence, not claims: a worker saying "done" is not done. Check its
+diff/test output (from the wakeup or `sessions_read`), or verify cheaply
+yourself.
+
+## Etiquette and limits
+
+- Depth cap: workers must not spawn sub-workers (`sessions_spawn` refuses).
+- At most 4 tracked workers at once; prefer 2–3 focused workers over a swarm.
+- The user sees every worker in the sidebar and may type into one directly —
+  that's fine and expected. Their instructions to a worker take precedence.
+- In your reply to the user after spawning, say which workers you started and
+  that you'll report when they finish.
+- If a wakeup arrives while you're mid-task, you may briefly acknowledge it
+  and defer handling until your current step is done.
+
+## Concrete example
+
+```
+sessions_spawn { name: "scout: session storage", category: "Fast",
+  task: "In <repo>, find where session files are written and rotated.
+         Report file:line for each write path plus a 5-line summary.
+         Read-only: do not modify anything." }
+sessions_spawn { name: "tests: baseline", category: "Fast",
+  task: "Run `npm test` in <repo>. Report pass/fail counts and the full
+         failure output for any failing test, nothing else." }
+-- end turn; wakeups arrive; then --
+sessions_spawn { name: "implement: rotation fix", category: "Smart",
+  task: "<self-contained spec built from scout findings>.
+         Run typecheck + affected tests; report the diff and test output." }
+```

From 1f5e23718855e8af4c7084f686ce0f389ddfd082 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 09:08:43 +0000
Subject: [PATCH 03/10] test: typecheck examples and cover the orchestration
 extension

Examples were outside tsconfig's include, so extension sources shipped
untypechecked. Add examples/**/*.ts to the typecheck surface and map the
self-referencing "@ashwin-pc/pi-web/extensions" specifier to src/extensions.ts
so examples resolve in-repo rather than against built output.

Enabling that guard surfaced real problems it had been hiding:
- session-orchestrator now uses PiWebExtensionAPI/PiWebExtensionContext instead
  of untyped contexts, which caught a dead getId() fallback, unchecked coercion
  of JSON-valued settings, and a schema literal that did not satisfy
  PiWebSettingsSchema. It also makes the async settings API impossible to misuse
  by accident: reading getSettings() without awaiting is now a type error.
- git-footer passed a spawn-only `stdio` option to execFile.
- recap called a SessionManager method that is now a standalone
  buildSessionContext() export, and used a discriminated auth result without
  narrowing it.

Extension coverage (24 tests): first-colon token parsing, exact-match before
region substitution and no arbitrary fallback, category menu that exposes names
and prose but never the model mapping, default-category selection, unknown
category and missing default erroring before anything is created, unavailable
model creating then deleting the unprompted session without dispatching work,
reported region substitution, virtual default leaving the worker on the session
model, recorded origin, worker marker in the dispatched task, depth cap, and the
concurrent worker cap.

Also fixes a regression: custom messages rendered as cards dropped the
custom--<type> class that plain custom messages expose, breaking existing
selectors and styling hooks. The e2e suite now also asserts the card renders
session-link chips from structured details.
---
 examples/pi-web-extensions/git-footer.ts      |   1 -
 examples/pi-web-extensions/recap.ts           |   4 +-
 .../pi-web-extensions/session-orchestrator.ts |  36 +-
 server/mock.ts                                |   2 +-
 src/messages/messageList.ts                   |   5 +-
 tests/e2e/custom-messages.spec.ts             |  22 ++
 tests/session-orchestrator.test.ts            | 345 ++++++++++++++++++
 tsconfig.json                                 |  16 +-
 8 files changed, 407 insertions(+), 24 deletions(-)
 create mode 100644 tests/session-orchestrator.test.ts

diff --git a/examples/pi-web-extensions/git-footer.ts b/examples/pi-web-extensions/git-footer.ts
index 54ab988..fc3f709 100644
--- a/examples/pi-web-extensions/git-footer.ts
+++ b/examples/pi-web-extensions/git-footer.ts
@@ -40,7 +40,6 @@ async function runGit(args: string[], cwd: string): Promise<GitResult> {
     const { stdout } = await execFileAsync("git", ["--no-optional-locks", ...args], {
       cwd,
       encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
       timeout: GIT_TIMEOUT_MS,
       killSignal: "SIGKILL",
     });
diff --git a/examples/pi-web-extensions/recap.ts b/examples/pi-web-extensions/recap.ts
index c1639ac..130970e 100644
--- a/examples/pi-web-extensions/recap.ts
+++ b/examples/pi-web-extensions/recap.ts
@@ -1,4 +1,5 @@
 import { generateSummary } from "@earendil-works/pi-coding-agent";
+import { buildSessionContext } from "@earendil-works/pi-coding-agent";
 import type { PiWebExtensionAPI, PiWebExtensionContext } from "@ashwin-pc/pi-web/extensions";
 
 const RECAP_INSTRUCTIONS = [
@@ -13,9 +14,10 @@ const RECAP_INSTRUCTIONS = [
 async function buildRecap(ctx: PiWebExtensionContext) {
   const model = ctx.model;
   if (!model) throw new Error("No model is configured for this session");
-  const messages = ctx.sessionManager.buildSessionContext().messages;
+  const messages = buildSessionContext(ctx.sessionManager.getBranch()).messages;
   if (!messages.length) throw new Error("This session has no messages to recap yet");
   const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) throw new Error(auth.error);
   const markdown = await generateSummary(messages, model, 4096, auth.apiKey, auth.headers, ctx.signal, RECAP_INSTRUCTIONS);
   return { markdown: markdown.trim() };
 }
diff --git a/examples/pi-web-extensions/session-orchestrator.ts b/examples/pi-web-extensions/session-orchestrator.ts
index 2b90dfa..56bf5d9 100644
--- a/examples/pi-web-extensions/session-orchestrator.ts
+++ b/examples/pi-web-extensions/session-orchestrator.ts
@@ -19,7 +19,7 @@
  */
 
 import { Type } from "typebox";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { PiWebExtensionAPI, PiWebExtensionContext, PiWebSettingsSchema } from "@ashwin-pc/pi-web/extensions";
 
 const WORKER_MARKER = "[pi-web orchestrated worker]";
 const EXT_VERSION = "v9";
@@ -38,7 +38,7 @@ const WAKEUP_SUMMARY_CHARS = 2000;
 // concrete model stays private to config (never shown to the LLM). Empty config
 // is a virtual, unwritten "Default" resolved live to the worker's own model.
 const SETTINGS_ID = "session-orchestrator.workerModelCategories";
-const SETTINGS_SCHEMA = {
+const SETTINGS_SCHEMA: PiWebSettingsSchema = {
   id: SETTINGS_ID,
   title: "Worker model categories",
   schemaVersion: 1,
@@ -76,20 +76,20 @@ const BASE = `http://127.0.0.1:${PORT}`;
 // ---------------------------------------------------------------------------
 
 /** Parse "<provider>:<id>" into { provider, id }. Split on FIRST colon only. */
-function parseToken(token: string): { provider: string; id: string } | null {
+export function parseToken(token: string): { provider: string; id: string } | null {
   const idx = token.indexOf(":");
   if (idx < 0) return null;
   return { provider: token.slice(0, idx), id: token.slice(idx + 1) };
 }
 
 /** Determine if normalized id base matches (Bedrock inference-profile case). */
-function normalizeBedrockId(id: string): string {
+export function normalizeBedrockId(id: string): string {
   // Extract base (e.g. "us.amazon.nova-2-lite-v1" from "us.amazon.nova-2-lite-v1:0")
   return id.split(":")[0];
 }
 
 /** Resolution order per Amendment 6. Returns { match, substituted }. */
-function resolveModel(
+export function resolveModel(
   canonicalToken: string,
   registryModels: any[],
   parentRegionPrefix: string,
@@ -204,7 +204,7 @@ function formatTranscript(messages: any[], tail: number): string {
 // Extension
 // ---------------------------------------------------------------------------
 
-export default function sessionOrchestrator(pi: ExtensionAPI) {
+export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   type Watched = {
     id: string;
     name: string;
@@ -223,12 +223,12 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
   // Capture our own session id whenever context is available; used to route
   // wakeups through /api/prompt (the same battle-tested path the web UI uses
   // for steering), which works both when the parent is idle and mid-turn.
-  function captureSelf(ctx: any) {
+  function captureSelf(ctx: PiWebExtensionContext) {
     const id = ownSessionId(ctx);
     if (id && id !== "unknown") selfSessionId = id;
   }
 
-  function isWorkerSession(ctx: any): boolean {
+  function isWorkerSession(ctx: PiWebExtensionContext): boolean {
     try {
       const entries = ctx.sessionManager?.getBranch?.() || [];
       for (const entry of entries) {
@@ -249,15 +249,15 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
     return false;
   }
 
-  function ownSessionId(ctx: any): string {
+  function ownSessionId(ctx: PiWebExtensionContext): string {
     try {
-      return String(ctx.sessionManager?.getSessionId?.() ?? ctx.sessionManager?.getId?.() ?? "unknown");
+      return String(ctx.sessionManager?.getSessionId?.() ?? "unknown");
     } catch {
       return "unknown";
     }
   }
 
-  function ownCwd(ctx: any): string | undefined {
+  function ownCwd(ctx: PiWebExtensionContext): string | undefined {
     try {
       const cwd = ctx.sessionManager?.getCwd?.();
       return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
@@ -320,7 +320,7 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
   // Tool builder and settings registration
   // =========================================================================
 
-  function buildSpawnTool(ctx: any): any {
+  function buildSpawnTool(ctx: PiWebExtensionContext): any {
     let description = [
       "Spawn a new pi-web worker session and give it a task. The worker runs in the background as a normal, fully visible pi-web session.",
       "Returns immediately with the worker's session id. When the worker goes idle you will receive a '🔔 [orchestrator]' user message containing its final output — do NOT poll for completion; do other, non-overlapping work or end your turn and wait.",
@@ -376,7 +376,7 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
         cwd: Type.Optional(Type.String({ description: "Working directory for the worker (defaults to this session's cwd)" })),
         category: Type.Optional(Type.String({ description: parameterDescription })),
       }),
-      execute: async (_toolCallId: string, params: any, _signal: any, _onUpdate: any, ctx: any) => {
+      execute: async (_toolCallId: string, params: any, _signal: any, _onUpdate: any, ctx: PiWebExtensionContext) => {
         if (isWorkerSession(ctx)) {
           return {
             content: [
@@ -414,9 +414,9 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
             const settings = await web.getSettings(SETTINGS_ID);
             if (settings && typeof settings === "object") {
               const values = settings.values || {};
-              cachedConfig = { categories: Array.isArray(values.categories) ? values.categories : [], defaultCategory: values.defaultCategory || "" };
+              cachedConfig = { categories: Array.isArray(values.categories) ? values.categories : [], defaultCategory: String(values.defaultCategory || "") };
               const categories = Array.isArray(values.categories) ? values.categories : [];
-              const defaultCategory = values.defaultCategory || "";
+              const defaultCategory = String(values.defaultCategory || "");
 
               // Empty config → virtual Default, skip resolution, use session default.
               if (categories.length === 0) {
@@ -619,7 +619,7 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
     };
   }
 
-  async function registerTools(ctx: any) {
+  async function registerTools(ctx: PiWebExtensionContext) {
     try {
       const web = ctx?.ui?.web;
       if (web?.getSettings) {
@@ -627,7 +627,7 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
         if (s && typeof s === "object" && s.values) {
           cachedConfig = {
             categories: Array.isArray(s.values.categories) ? s.values.categories : [],
-            defaultCategory: s.values.defaultCategory || "",
+            defaultCategory: String(s.values.defaultCategory || ""),
           };
         }
       }
@@ -635,7 +635,7 @@ export default function sessionOrchestrator(pi: ExtensionAPI) {
     pi.registerTool(buildSpawnTool(ctx));
   }
 
-  pi.on("session_start", async (_event: any, ctx: any) => {
+  pi.on("session_start", async (_event: unknown, ctx: PiWebExtensionContext) => {
     captureSelf(ctx);
     void rearmFromLedger(ctx);
     try {
diff --git a/server/mock.ts b/server/mock.ts
index c627d89..f5f53fe 100644
--- a/server/mock.ts
+++ b/server/mock.ts
@@ -512,7 +512,7 @@ export function createMockHarness(options: MockSessionOptions) {
           if (!(await waitForMockRun(150))) return;
           if (!(await waitForMockRun(500))) return;
           const timestamp = new Date().toISOString();
-          const visibleCustom = { role: "custom", customType: "probe", content: "hello from an extension", details: { source: "mock-extension" }, display: true, timestamp };
+          const visibleCustom = { role: "custom", customType: "probe", content: "hello from an extension", details: { source: "mock-extension", workers: [{ sessionId: "mock-worker-1", name: "mock worker", status: "ok" }] }, display: true, timestamp };
           appendMockMessage(visibleCustom);
           broadcastPiEvent({ type: "message_end", message: visibleCustom });
           if (!(await waitForMockRun(500))) return;
diff --git a/src/messages/messageList.ts b/src/messages/messageList.ts
index 4482392..462b56b 100644
--- a/src/messages/messageList.ts
+++ b/src/messages/messageList.ts
@@ -726,7 +726,10 @@ export function createMessageList(options: {
     const div = document.createElement("div");
     div.dataset.sessionRefs = sessionRefs.map((ref) => ref.sessionId).join(",");
     const collapsible = shouldCollapseMessage(text);
-    div.className = `message custom customCard${collapsible ? " collapsible collapsed" : ""}${message.isError ? " error" : ""}`;
+    // Keep the `custom--<type>` styling hook that plain custom messages expose,
+    // so extension-specific CSS and selectors keep working on the card form.
+    const typeClass = customType.replace(/[^a-zA-Z0-9_-]+/g, "-");
+    div.className = `message custom customCard${typeClass ? ` custom--${typeClass}` : ""}${collapsible ? " collapsible collapsed" : ""}${message.isError ? " error" : ""}`;
 
     const header = document.createElement("div");
     header.className = "customCardHeader";
diff --git a/tests/e2e/custom-messages.spec.ts b/tests/e2e/custom-messages.spec.ts
index 6a99f12..37cc8c4 100644
--- a/tests/e2e/custom-messages.spec.ts
+++ b/tests/e2e/custom-messages.spec.ts
@@ -25,3 +25,25 @@ test("renders custom and unknown committed messages without disrupting the live
   await expect(visibleCustom).toHaveCount(1);
   await expect(page.locator(".message.system", { hasText: "future message content" })).toHaveCount(1);
 });
+
+test("renders an extension custom message as a card that links to referenced sessions", async ({ page }) => {
+  await page.goto("/");
+  await page.locator("#prompt").fill("slow live message kinds");
+  await page.locator("#primaryButton").click();
+
+  // Custom messages render as a notification card, keeping the custom--<type> hook.
+  const card = page.locator(".message.customCard.custom--probe");
+  await expect(card).toHaveCount(1, { timeout: 5_000 });
+  await expect(card).toContainText("hello from an extension");
+  await expect(card.locator(".customCardLabel")).toHaveText("Probe");
+
+  // Structured `details` become chips that open the referenced session.
+  const chip = card.locator(".customCardSessionChip");
+  await expect(chip).toHaveCount(1);
+  await expect(chip).toContainText("mock worker");
+  await expect(chip).toHaveAttribute("href", /sessionId=mock-worker-1/);
+
+  await page.locator("#stopButton").click();
+  await expect(page.locator("#stopButton")).toBeHidden();
+  await expect(card.locator(".customCardSessionChip")).toHaveCount(1);
+});
diff --git a/tests/session-orchestrator.test.ts b/tests/session-orchestrator.test.ts
new file mode 100644
index 0000000..44cfacd
--- /dev/null
+++ b/tests/session-orchestrator.test.ts
@@ -0,0 +1,345 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import sessionOrchestrator, {
+  normalizeBedrockId,
+  parseToken,
+  resolveModel,
+} from "../examples/pi-web-extensions/session-orchestrator.js";
+
+// ---------------------------------------------------------------------------
+// Pure resolution helpers (Amendment 6 ordering)
+// ---------------------------------------------------------------------------
+
+describe("model token parsing", () => {
+  it("splits on the first colon so ids may contain colons", () => {
+    expect(parseToken("amazon-bedrock:amazon.nova-2-lite-v1:0")).toEqual({
+      provider: "amazon-bedrock",
+      id: "amazon.nova-2-lite-v1:0",
+    });
+  });
+
+  it("returns null when there is no provider separator", () => {
+    expect(parseToken("nova-2-lite")).toBeNull();
+  });
+
+  it("normalizes a bedrock id to its base", () => {
+    expect(normalizeBedrockId("us.anthropic.claude-x-v1:0")).toBe("us.anthropic.claude-x-v1");
+  });
+});
+
+describe("resolveModel", () => {
+  const registry = [
+    { provider: "anthropic", id: "fast-1" },
+    { provider: "amazon-bedrock", id: "us.anthropic.claude-x-v1:0" },
+  ];
+
+  it("prefers an exact provider/id match without substituting", () => {
+    const result = resolveModel("anthropic:fast-1", registry, "us.");
+    expect(result?.match).toEqual({ provider: "anthropic", id: "fast-1" });
+    expect(result?.substituted).toBe(false);
+  });
+
+  it("falls back to the parent region prefix only after an exact miss, and reports it", () => {
+    const result = resolveModel("amazon-bedrock:anthropic.claude-x-v1:0", registry, "us.");
+    expect(result?.match).toEqual({ provider: "amazon-bedrock", id: "us.anthropic.claude-x-v1:0" });
+    expect(result?.substituted).toBe(true);
+  });
+
+  it("does not substitute when the parent has no region prefix", () => {
+    expect(resolveModel("amazon-bedrock:anthropic.claude-x-v1:0", registry, "")).toBeNull();
+  });
+
+  it("never picks an arbitrary candidate from another provider", () => {
+    expect(resolveModel("openai:missing-1", registry, "us.")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sessions_spawn: create-unprompted -> resolve -> dispatch or delete
+// ---------------------------------------------------------------------------
+
+type Call = { method: string; path: string; body?: any };
+
+const FAST = { name: "Fast", model: "anthropic:fast-1", description: "Cheap scouting." };
+const SMART = { name: "Smart", model: "anthropic:smart-1", description: "Hard implementation work." };
+
+const registry = [
+  { provider: "anthropic", id: "fast-1", name: "Fast One" },
+  { provider: "anthropic", id: "smart-1", name: "Smart One" },
+];
+
+let calls: Call[];
+let tools: Map<string, any>;
+let handlers: Map<string, (event: any, ctx: any) => any>;
+let realFetch: typeof globalThis.fetch;
+
+function makeExtension() {
+  tools = new Map();
+  handlers = new Map();
+  const pi: any = {
+    registerTool: (tool: any) => tools.set(tool.name, tool),
+    on: (event: string, handler: any) => handlers.set(event, handler),
+    sendMessage: vi.fn(),
+    appendEntry: vi.fn(),
+  };
+  sessionOrchestrator(pi);
+  return pi;
+}
+
+function makeCtx(options: {
+  categories?: any[];
+  defaultCategory?: string;
+  worker?: boolean;
+  parentModelId?: string;
+} = {}) {
+  const branch = options.worker
+    ? [{ type: "message", message: { role: "user", content: [{ type: "text", text: "[pi-web orchestrated worker] You are a worker session spawned by session parent-1 to do one task." }] } }]
+    : [];
+  return {
+    sessionManager: {
+      getBranch: () => branch,
+      getSessionId: () => "parent-1",
+      getCwd: () => "/repo",
+    },
+    ui: {
+      web: {
+        registerSettings: vi.fn(async () => ({ registered: true, migrated: false, usedBackup: false })),
+        getSettings: vi.fn(async () => ({
+          schemaVersion: 1,
+          values: {
+            categories: options.categories ?? [],
+            defaultCategory: options.defaultCategory ?? "",
+          },
+        })),
+      },
+    },
+    __parentModelId: options.parentModelId ?? "fast-1",
+  };
+}
+
+/** Route pi-web API calls; `models` is the worker session's registry. */
+function stubFetch(options: { models?: any[]; parentModelId?: string; newChatFails?: boolean } = {}) {
+  let created = 0;
+  globalThis.fetch = (async (url: any, init: any = {}) => {
+    const method = String(init.method || "GET");
+    const path = String(url).replace(/^https?:\/\/[^/]+/, "");
+    const body = init.body ? JSON.parse(init.body) : undefined;
+    calls.push({ method, path, body });
+
+    let payload: any = { ok: true };
+    if (path === "/api/new-chat") {
+      created += 1;
+      payload = options.newChatFails ? { ok: false, error: "boom" } : { ok: true, sessionId: `worker-${created}` };
+    } else if (path.startsWith("/api/models")) {
+      payload = { ok: true, models: options.models ?? registry };
+    } else if (path.startsWith("/api/state")) {
+      payload = { ok: true, model: { provider: "anthropic", id: options.parentModelId ?? "fast-1" } };
+    } else if (path.startsWith("/api/messages")) {
+      payload = { ok: true, messages: [] };
+    }
+    return { ok: payload.ok !== false, status: payload.ok === false ? 500 : 200, json: async () => payload } as any;
+  }) as any;
+}
+
+function pathsFor(method: string) {
+  return calls.filter((call) => call.method === method).map((call) => call.path);
+}
+
+async function activate(ctx: any) {
+  await handlers.get("session_start")?.({}, ctx);
+  // Ignore activation traffic (settings registration, ledger re-arm) so each
+  // test asserts only on its own spawn flow.
+  calls.length = 0;
+}
+
+async function spawn(ctx: any, params: Record<string, unknown>) {
+  // sessions_spawn is (re)built from config on session_start, so activate first.
+  if (!tools.has("sessions_spawn")) await activate(ctx);
+  const tool = tools.get("sessions_spawn");
+  return tool.execute("call-1", params, undefined, undefined, ctx);
+}
+
+function resultText(result: any) {
+  return String(result?.content?.[0]?.text || "");
+}
+
+beforeEach(() => {
+  calls = [];
+  realFetch = globalThis.fetch;
+  stubFetch();
+  makeExtension();
+});
+
+afterEach(() => {
+  // Clears the background poll timer started by a successful spawn.
+  handlers.get("session_shutdown")?.({}, makeCtx());
+  globalThis.fetch = realFetch;
+  vi.restoreAllMocks();
+});
+
+describe("sessions_spawn tool surface", () => {
+  it("registers the orchestration tools", async () => {
+    await activate(makeCtx());
+    expect([...tools.keys()].sort()).toEqual([
+      "sessions_abort",
+      "sessions_prompt",
+      "sessions_read",
+      "sessions_spawn",
+      "sessions_status",
+    ]);
+  });
+
+  it("takes a category name rather than a model id", async () => {
+    await activate(makeCtx());
+    const properties = tools.get("sessions_spawn").parameters?.properties ?? {};
+    expect(Object.keys(properties)).toContain("category");
+    expect(Object.keys(properties)).not.toContain("model");
+  });
+
+  it("lists category names and prose in its description but never the model mapping", async () => {
+    const ctx = makeCtx({ categories: [FAST, SMART], defaultCategory: "Fast" });
+    await handlers.get("session_start")?.({}, ctx);
+
+    const description = tools.get("sessions_spawn").description as string;
+    expect(description).toContain("Fast");
+    expect(description).toContain("Cheap scouting.");
+    expect(description).toContain("Smart");
+    // The category -> model mapping stays private to the config.
+    expect(description).not.toContain("anthropic:fast-1");
+    expect(description).not.toContain("smart-1");
+  });
+
+  it("describes the session default when nothing is configured", async () => {
+    await handlers.get("session_start")?.({}, makeCtx());
+    expect(tools.get("sessions_spawn").description as string).toMatch(/no categories/i);
+  });
+});
+
+describe("sessions_spawn fail-closed resolution", () => {
+  it("dispatches on an exact category match after setting the model", async () => {
+    const ctx = makeCtx({ categories: [FAST, SMART], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Smart" });
+
+    expect(result.isError).toBeFalsy();
+    expect(pathsFor("POST")).toContain("/api/new-chat");
+    const modelCall = calls.find((call) => call.path === "/api/model");
+    expect(modelCall?.body).toMatchObject({ sessionId: "worker-1", provider: "anthropic", id: "smart-1" });
+    // Task dispatched only after the model was pinned.
+    expect(calls.findIndex((c) => c.path === "/api/model")).toBeLessThan(calls.findIndex((c) => c.path === "/api/prompt"));
+    expect(pathsFor("POST")).not.toContain("/api/sessions/delete");
+  });
+
+  it("uses the configured default when category is omitted", async () => {
+    const ctx = makeCtx({ categories: [FAST, SMART], defaultCategory: "Smart" });
+    const result = await spawn(ctx, { name: "scout", task: "look around" });
+
+    expect(result.isError).toBeFalsy();
+    expect(calls.find((call) => call.path === "/api/model")?.body).toMatchObject({ id: "smart-1" });
+  });
+
+  it("errors without creating a session when the category is unknown", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Ghost" });
+
+    expect(result.isError).toBe(true);
+    expect(resultText(result)).toContain("Fast"); // menu-on-miss
+    expect(calls).toHaveLength(0); // nothing created, nothing dispatched
+  });
+
+  it("errors without creating a session when no default is configured", async () => {
+    const ctx = makeCtx({ categories: [FAST] });
+    const result = await spawn(ctx, { name: "scout", task: "look around" });
+
+    expect(result.isError).toBe(true);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("deletes the unprompted session and dispatches nothing when the model is unavailable", async () => {
+    stubFetch({ models: [{ provider: "anthropic", id: "something-else" }] });
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Fast" });
+
+    expect(result.isError).toBe(true);
+    expect(pathsFor("POST")).toContain("/api/new-chat");
+    expect(calls.find((call) => call.path === "/api/sessions/delete")?.body).toMatchObject({ sessionId: "worker-1" });
+    expect(pathsFor("POST")).not.toContain("/api/prompt"); // no LLM work happened
+    expect(resultText(result)).toMatch(/deleted/i);
+  });
+
+  it("reports a region-prefix substitution instead of silently swapping models", async () => {
+    stubFetch({ models: [{ provider: "amazon-bedrock", id: "us.anthropic.claude-x-v1:0" }], parentModelId: "us.anthropic.other-v1:0" });
+    const category = { name: "Bedrock", model: "amazon-bedrock:anthropic.claude-x-v1:0", description: "Region-prefixed profile." };
+    const ctx = makeCtx({ categories: [category], defaultCategory: "Bedrock", parentModelId: "us.anthropic.other-v1:0" });
+
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Bedrock" });
+
+    expect(result.isError).toBeFalsy();
+    expect(calls.find((call) => call.path === "/api/model")?.body).toMatchObject({ id: "us.anthropic.claude-x-v1:0" });
+    expect(resultText(result)).toMatch(/substituted/i);
+  });
+
+  it("leaves the worker on the session default when no categories are configured", async () => {
+    const ctx = makeCtx();
+    const result = await spawn(ctx, { name: "scout", task: "look around" });
+
+    expect(result.isError).toBeFalsy();
+    expect(pathsFor("POST")).toContain("/api/new-chat");
+    expect(pathsFor("POST")).not.toContain("/api/model"); // virtual default: never pins a model
+    expect(pathsFor("POST")).toContain("/api/prompt");
+  });
+
+  it("records the parent as the spawned session's origin", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await spawn(ctx, { name: "scout", task: "look around" });
+
+    expect(calls.find((call) => call.path === "/api/new-chat")?.body).toMatchObject({
+      cwd: "/repo",
+      origin: { sessionId: "parent-1", kind: "spawn" },
+    });
+  });
+
+  it("passes an explicit cwd through to the worker", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await spawn(ctx, { name: "scout", task: "look around", cwd: "/other/tree" });
+
+    expect(calls.find((call) => call.path === "/api/new-chat")?.body).toMatchObject({ cwd: "/other/tree" });
+  });
+
+  it("sends the worker a self-contained task carrying the worker marker", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await spawn(ctx, { name: "scout", task: "inspect the drawer", category: "Fast" });
+
+    const prompt = String(calls.find((call) => call.path === "/api/prompt")?.body?.message || "");
+    expect(prompt).toContain("[pi-web orchestrated worker]");
+    expect(prompt).toContain("inspect the drawer");
+    expect(prompt).toContain("parent-1");
+  });
+
+  it("refuses to spawn from a worker session (depth cap)", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast", worker: true });
+    const result = await spawn(ctx, { name: "sub", task: "nested work" });
+
+    expect(result.isError).toBe(true);
+    expect(resultText(result)).toMatch(/depth cap/i);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("surfaces a creation failure without dispatching work", async () => {
+    stubFetch({ newChatFails: true });
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around" });
+
+    expect(result.isError).toBe(true);
+    expect(pathsFor("POST")).not.toContain("/api/prompt");
+  });
+
+  it("caps the number of concurrently tracked workers", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    for (let i = 0; i < 4; i += 1) {
+      const result = await spawn(ctx, { name: `worker-${i}`, task: "work" });
+      expect(result.isError).toBeFalsy();
+    }
+    const overflow = await spawn(ctx, { name: "worker-5", task: "work" });
+    expect(overflow.isError).toBe(true);
+    expect(resultText(overflow)).toMatch(/cap/i);
+  });
+});
diff --git a/tsconfig.json b/tsconfig.json
index a2dad92..8752af1 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -8,7 +8,19 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "noEmit": true
+    "noEmit": true,
+    "paths": {
+      "@ashwin-pc/pi-web/extensions": [
+        "./src/extensions.ts"
+      ]
+    }
   },
-  "include": ["server.ts", "supervisor.ts", "vite.config.ts", "src/**/*.ts", ".pi/extensions/**/*.ts"]
+  "include": [
+    "server.ts",
+    "supervisor.ts",
+    "vite.config.ts",
+    "src/**/*.ts",
+    ".pi/extensions/**/*.ts",
+    "examples/**/*.ts"
+  ]
 }

From ff66c3b6e010ea30206fb1ac971cac20af6812d0 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 09:49:57 +0000
Subject: [PATCH 04/10] fix: address independent review of the orchestration
 feature

Correctness
- Serialize every settings mutation through one promise chain so the optimistic
  revision guard actually holds; two concurrent writers can no longer both pass
  CAS, and a generic patch can no longer clobber a concurrent extension write.
  First writes must present revision 0, reset is revision-guarded, and the HTTP
  layer rejects a missing/negative/fractional revision. Atomic writes use a
  collision-proof temp filename.
- Rework the schema registry: the owner id is reserved synchronously before any
  await (so concurrent first registrations migrate exactly once and a divergent
  schema is rejected rather than replacing the incumbent), registrants are
  tracked per session instead of by refcount, a session that shuts down during
  migration is never registered, and a schema stays hidden from validation and
  transport until migration settles. Descriptors are structurally validated and
  owner ids must be namespaced before anything is reserved.
- Notify every live registrant with its own callback and session id, rather than
  letting the newest registration overwrite the single stored callback.
- Spawning is fail-closed on the remaining paths: a failed task dispatch now
  deletes the worker, cleanup failures are reported honestly instead of claiming
  "no orphan", and recording session lineage is best-effort so it cannot fail a
  request that already created a session.
- Keep the worker poller from re-arming or polling after shutdown, and retain a
  completed worker until its wakeup is actually delivered.

Layering
- Core no longer knows about the orchestrator: session-link chips are rendered
  from an explicit reference list in a tool result's `details` for any tool, with
  no tool-name check and no parsing of English result text. A bare `sessionId` is
  incidental metadata and renders nothing, so tools that merely echo a session id
  stay quiet. References are bounded, de-duplicated, length-capped and id-checked
  because `details` is untrusted persisted input, and both custom-message cards
  and tool cards now share one helper.
- Stop leaking the category-to-model mapping to the model: tool results and
  details name the category only, and report that a region substitution happened
  without naming the substituted model.

Settings UI
- Deleting a referenced row no longer silently clears the reference; the dangling
  reference surfaces as an inline validation error. Renames follow the reference
  reliably by resolving the referenced row through its stable id.
- Accordion headers are real buttons (keyboard operable), required fields expose
  required/aria-required, and list-level errors are associated via
  aria-describedby.
- Conflicts and resets re-render from the server response instead of leaving a
  stale draft behind a "reloaded latest" message.
- Retained data for an unloaded extension can be reset (reset needs stored data,
  not a live schema), and a failed migration is surfaced through the published
  schema so the UI can show it.

Scope
- Drop unrelated session time-filter work that rode along in the drawer diff.

Tests (257 unit, 28 files)
- Store: concurrent same-revision writes, generic patch racing an extension
  write, reset racing a write, first-write revision rule, and many rapid writes
  keeping gapless revisions with valid JSON on disk.
- Registry: migrate-once under concurrent registration, divergent-schema
  rejection, last-registrant lifecycle, notify-all-with-session-id, throwing
  onChange isolation, shutdown during migration, migration failure keeping a
  backup and surfacing the error, and hidden-until-ready.
- References: explicit-list-only rule, dedupe, caps, hostile ids, label
  sanitizing.
- Orchestrator: privacy of the mapping in results and details, dispatch-failure
  cleanup, honest cleanup reporting, no re-arm after shutdown, and retry when
  every wakeup delivery path fails.
---
 docs/pi-web-extensions.md                     |  35 ++-
 .../pi-web-extensions/session-orchestrator.ts | 201 +++++++++++-----
 server.ts                                     |  64 ++++--
 server/extensions/webUi.ts                    | 164 +++++++++----
 server/session/service.ts                     |   1 +
 server/settings.ts                            |  61 +++--
 src/app/sessionRefs.ts                        |  72 ++++++
 src/extensions.ts                             |   7 +-
 src/messages/messageList.ts                   |  31 +--
 src/sessions/sessionDrawer.ts                 |  86 +------
 src/settings/extensionSettings.ts             | 187 ++++++++++++---
 src/styles/sessions.css                       |  24 --
 src/tools/toolCards.ts                        |  63 ++---
 tests/extension-settings.test.ts              |  37 ++-
 tests/session-orchestrator.test.ts            | 131 ++++++++++-
 tests/session-refs.test.ts                    |  68 ++++++
 tests/settings.test.ts                        |  90 +++++++-
 tests/web-ui-settings.test.ts                 | 217 ++++++++++++++++++
 18 files changed, 1179 insertions(+), 360 deletions(-)
 create mode 100644 src/app/sessionRefs.ts
 create mode 100644 tests/session-refs.test.ts
 create mode 100644 tests/web-ui-settings.test.ts

diff --git a/docs/pi-web-extensions.md b/docs/pi-web-extensions.md
index f810d18..adc7083 100644
--- a/docs/pi-web-extensions.md
+++ b/docs/pi-web-extensions.md
@@ -206,7 +206,7 @@ pi.on("session_start", async (_event, ctx) => {
       { key: "enabled", type: "toggle", label: "Enabled", default: true },
       { key: "model", type: "select", label: "Model", optionsSource: "models" },
     ],
-    onChange: (values) => applyPreferences(values),
+    onChange: (values, info) => applyPreferences(values, info.sessionId),
   });
 
   const { values } = await ctx.ui.web.getSettings("my-ext.prefs");
@@ -237,7 +237,38 @@ Storage notes:
   stored values. A failed migration falls back to defaults and keeps a one-slot
   `backup`.
 - Owners with stored values but no live registration render as a read-only
-  "data retained" card.
+  "data retained" card. Their stored values can still be reset (reset needs only
+  stored data, not a live schema); editing requires the schema.
+- Every live registrant of an id is notified on change, each with its own
+  `onChange` and its own `info.sessionId`. The first registrant's descriptor is
+  canonical; a divergent schema for the same id is rejected.
+- If a migration fails, the stored values fall back to defaults, the previous
+  values are kept in `backup`, and the schema is published with a
+  `migrationError` so the UI can surface it.
+
+## Referencing sessions from extension output
+
+Extension output can point at other sessions, and pi-web renders those as links.
+This works the same way for custom messages and for tool results: put an explicit
+reference LIST in `details`.
+
+```ts
+pi.sendMessage({
+  customType: "my-ext",
+  content: "Background job finished",
+  details: { sessions: [{ sessionId, name: "job runner", status: "ok" }] },
+});
+```
+
+- Supported keys are `sessions`, `sessionRefs`, and `workers`; each entry is
+  `{ sessionId, name?, status? }`, where `status` may be `error` or `aborted` to
+  change the chip's glyph.
+- A **bare** `details.sessionId` is treated as incidental metadata and renders no
+  link, so a tool that merely echoes the session it acted on stays quiet. Linking
+  is opt-in.
+- Core caps rendering at 8 references per card, truncates labels, and requires
+  plausible session ids, because `details` is untrusted persisted input. No
+  extension or tool name is special-cased.
 
 ## Example: GitHub PRs and issues tab
 
diff --git a/examples/pi-web-extensions/session-orchestrator.ts b/examples/pi-web-extensions/session-orchestrator.ts
index 56bf5d9..033e48b 100644
--- a/examples/pi-web-extensions/session-orchestrator.ts
+++ b/examples/pi-web-extensions/session-orchestrator.ts
@@ -208,6 +208,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   type Watched = {
     id: string;
     name: string;
+    categoryName: string;
     sawRunning: boolean;
     idlePolls: number;
     errorPolls: number;
@@ -219,6 +220,12 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   let timer: ReturnType<typeof setInterval> | undefined;
   let pollInFlight = false;
   let selfSessionId = "";
+  let disposed = false;
+  let generation = 0;
+
+  function isActive(expectedGeneration = generation): boolean {
+    return !disposed && generation === expectedGeneration;
+  }
 
   // Capture our own session id whenever context is available; used to route
   // wakeups through /api/prompt (the same battle-tested path the web UI uses
@@ -267,7 +274,11 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   }
 
   function ensureTimer() {
-    if (!timer && watched.size > 0) timer = setInterval(() => void poll(), POLL_MS);
+    if (!isActive() || timer || watched.size === 0) return;
+    const timerGeneration = generation;
+    timer = setInterval(() => {
+      if (isActive(timerGeneration)) void poll(timerGeneration);
+    }, POLL_MS);
   }
 
   function stopTimerIfIdle() {
@@ -277,8 +288,9 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
     }
   }
 
-  function watch(id: string, name: string) {
-    watched.set(id, { id, name, sawRunning: false, idlePolls: 0, errorPolls: 0, aborted: false });
+  function watch(id: string, name: string, categoryName = "Unknown") {
+    if (!isActive()) return;
+    watched.set(id, { id, name, categoryName, sawRunning: false, idlePolls: 0, errorPolls: 0, aborted: false });
     ensureTimer();
   }
 
@@ -287,9 +299,9 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
     stopTimerIfIdle();
   }
 
-  function appendLedger(customType: string, childId: string, name?: string) {
+  function appendLedger(customType: string, childId: string, name?: string, categoryName?: string) {
     try {
-      pi.appendEntry(customType, { childId, ...(name ? { name } : {}) });
+      pi.appendEntry(customType, { childId, ...(name ? { name } : {}), ...(categoryName ? { categoryName } : {}) });
     } catch (error) {
       console.error(`[session-orchestrator] could not append ${customType} entry: ${error instanceof Error ? error.message : error}`);
     }
@@ -300,14 +312,35 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
       .catch((error) => console.error(`[session-orchestrator] could not mark child read: ${error instanceof Error ? error.message : error}`));
   }
 
-  function outstandingWatches(ctx: any): Map<string, string> {
-    const watches = new Map<string, string>();
+  async function cleanupCreatedSession(sessionId: string): Promise<boolean> {
+    try {
+      await api("POST", "/api/sessions/delete", { sessionId });
+      return true;
+    } catch (error) {
+      console.error(`[session-orchestrator] could not clean up worker ${sessionId}: ${error instanceof Error ? error.message : error}`);
+      return false;
+    }
+  }
+
+  function cleanupReport(sessionId: string, cleanedUp: boolean): string {
+    return cleanedUp
+      ? `Session ${sessionId} was created but then deleted (no orphan).`
+      : `Session ${sessionId} could not be deleted and may remain — please remove it.`;
+  }
+
+  function outstandingWatches(ctx: any): Map<string, { name: string; categoryName: string }> {
+    const watches = new Map<string, { name: string; categoryName: string }>();
     try {
       for (const entry of ctx.sessionManager?.getBranch?.() || []) {
         if (entry?.type !== "custom") continue;
         const childId = typeof entry.data?.childId === "string" ? entry.data.childId : "";
         if (!childId) continue;
-        if (entry.customType === WATCH_ENTRY) watches.set(childId, typeof entry.data?.name === "string" ? entry.data.name : childId.slice(-8));
+        if (entry.customType === WATCH_ENTRY) {
+          watches.set(childId, {
+            name: typeof entry.data?.name === "string" ? entry.data.name : childId.slice(-8),
+            categoryName: typeof entry.data?.categoryName === "string" ? entry.data.categoryName : "Unknown",
+          });
+        }
         else if (entry.customType === RESOLVED_ENTRY) watches.delete(childId);
       }
     } catch (error) {
@@ -421,6 +454,8 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
               // Empty config → virtual Default, skip resolution, use session default.
               if (categories.length === 0) {
                 resolvedToken = null; // Signals: use session default
+                categoryName = "Default";
+                validCategories = [categoryName];
               } else {
                 // Collect valid names.
                 for (const cat of categories) {
@@ -470,7 +505,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
                     content: [
                       {
                         type: "text",
-                        text: `ERROR: category "${categoryName}" model token is malformed (expected "<provider>:<id>", got "${matching.model}"). Check extension settings.`,
+                        text: `ERROR: the model configured for category "${categoryName}" is malformed. Check extension settings. Valid categories: ${validCategories.join(", ") || "(none configured)"}`,
                       },
                     ],
                     isError: true,
@@ -521,8 +556,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
         const displayName = params.name;
         await api("POST", "/api/session/name", { sessionId, name: displayName }).catch(() => {});
 
-        let modelNote = "";
-        let modelSummary = "session default";
+        let regionSubstituted = false;
 
         // ====================================================================
         // Phase 3: Resolve against worker's registry (if config provided)
@@ -548,17 +582,16 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
 
             if (!resolution) {
               // Resolution failed → delete session and error.
-              await api("POST", "/api/sessions/delete", { sessionId }).catch(() => {});
-              const availableProviders = Array.from(new Set(registryModels.map((m: any) => m.provider)));
+              const cleanedUp = await cleanupCreatedSession(sessionId);
               return {
                 content: [
                   {
                     type: "text",
-                    text: `ERROR: configured model "${resolvedToken.provider}:${resolvedToken.id}" for category "${categoryName}" is not available in this session's registry. Available providers: ${availableProviders.join(", ") || "(none)"}. Valid categories for this spawn: ${validCategories.join(", ") || "(none configured)"}. Session ${sessionId} was created but then deleted (no orphan).`,
+                    text: `ERROR: the model configured for category "${categoryName}" is not available in this worker's registry. Valid categories: ${validCategories.join(", ") || "(none configured)"}. ${cleanupReport(sessionId, cleanedUp)}`,
                   },
                 ],
                 isError: true,
-                details: { sessionId, validCategories, categoryName, requestedModel: `${resolvedToken.provider}:${resolvedToken.id}`, availableProviders },
+                details: { sessionId, validCategories, categoryName, cleanedUp },
               };
             }
 
@@ -569,24 +602,21 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
             // ================================================================
 
             await api("POST", "/api/model", { sessionId, provider: match.provider, id: match.id });
-            modelNote = `category "${categoryName}" → model ${match.provider}/${match.id}`;
-            modelSummary = `${match.provider}/${match.id}`;
-
-            if (substituted) {
-              modelNote += ` (substituted region prefix from parent)`;
-            }
+            regionSubstituted = substituted;
           } catch (error) {
-            // Model resolution error → delete session and error.
-            await api("POST", "/api/sessions/delete", { sessionId }).catch(() => {});
+            // Model resolution error → delete session and error. Keep the
+            // configured provider/id private from the model-facing result.
+            console.error(`[session-orchestrator] failed to configure worker category "${categoryName}": ${error instanceof Error ? error.message : error}`);
+            const cleanedUp = await cleanupCreatedSession(sessionId);
             return {
               content: [
                 {
                   type: "text",
-                  text: `ERROR: failed to resolve model for category "${categoryName}": ${error instanceof Error ? error.message : error}. Session ${sessionId} was created but then deleted (no orphan). Valid categories: ${validCategories.join(", ") || "(none configured)"}`,
+                  text: `ERROR: failed to configure the model for category "${categoryName}". Valid categories: ${validCategories.join(", ") || "(none configured)"}. ${cleanupReport(sessionId, cleanedUp)}`,
                 },
               ],
               isError: true,
-              details: { sessionId, validCategories, categoryName },
+              details: { sessionId, validCategories, categoryName, cleanedUp },
             };
           }
         }
@@ -601,19 +631,36 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           ``,
           `TASK: ${params.task}`,
         ].join("\n");
-        await api("POST", "/api/prompt", { sessionId, message: prompt });
+        try {
+          await api("POST", "/api/prompt", { sessionId, message: prompt });
+        } catch (error) {
+          console.error(`[session-orchestrator] failed to dispatch worker ${sessionId}: ${error instanceof Error ? error.message : error}`);
+          const cleanedUp = await cleanupCreatedSession(sessionId);
+          return {
+            content: [{ type: "text", text: `ERROR: failed to dispatch the task to worker session ${sessionId}; no work was dispatched. ${cleanupReport(sessionId, cleanedUp)}` }],
+            isError: true,
+            details: { sessionId, categoryName, cleanedUp },
+          };
+        }
 
-        watch(sessionId, params.name);
-        appendLedger(WATCH_ENTRY, sessionId, params.name);
+        watch(sessionId, params.name, categoryName || "Default");
+        appendLedger(WATCH_ENTRY, sessionId, params.name, categoryName || "Default");
 
         return {
           content: [
             {
               type: "text",
-              text: `Spawned worker "${params.name}" (session ${sessionId}, ${modelSummary}) [ext ${EXT_VERSION}]. It is running in the background as a normal pi-web session named "${displayName}". ${modelNote ? `Used ${modelNote}.` : ""} You'll receive a 🔔 wakeup message when it goes idle — do not poll. Continue other work, spawn more workers, or end your turn to wait.`,
+              text: `Spawned worker "${params.name}" (session ${sessionId}, category "${categoryName || "Default"}") [ext ${EXT_VERSION}]. It is running in the background as a normal pi-web session named "${displayName}".${regionSubstituted ? " A region prefix was substituted." : ""} You'll receive a 🔔 wakeup message when it goes idle — do not poll. Continue other work, spawn more workers, or end your turn to wait.`,
             },
           ],
-          details: { sessionId, name: params.name, cwd: params.cwd || parentCwd, modelSummary } as Record<string, unknown>,
+          details: {
+            sessionId,
+            name: params.name,
+            sessions: [{ sessionId, name: params.name }],
+            cwd: params.cwd || parentCwd,
+            categoryName: categoryName || "Default",
+            regionSubstituted,
+          } as Record<string, unknown>,
         };
       },
     };
@@ -664,31 +711,40 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
    * deliver catch-up wakeups for children that finished while this session was
    * not in memory (server restart, /reload, idle disposal).
    */
-  async function rearmFromLedger(ctx: any) {
+  async function rearmFromLedger(ctx: any, expectedGeneration = generation) {
+    if (!isActive(expectedGeneration)) return;
     const outstanding = outstandingWatches(ctx);
     for (const id of watched.keys()) outstanding.delete(id);
     if (outstanding.size === 0) return;
 
-    const finished: { id: string; name: string; summary: { text: string; isError: boolean } }[] = [];
-    for (const [childId, name] of outstanding) {
+    const finished: { id: string; name: string; categoryName: string; summary: { text: string; isError: boolean } }[] = [];
+    for (const [childId, worker] of outstanding) {
+      if (!isActive(expectedGeneration)) return;
       try {
         const state = await api("GET", `/api/state?sessionId=${encodeURIComponent(childId)}`);
+        if (!isActive(expectedGeneration)) return;
         const running = Boolean(state?.runtime?.isRunning) || Number(state?.runtime?.pendingMessageCount || 0) > 0;
         if (running) {
-          watch(childId, name);
+          watch(childId, worker.name, worker.categoryName);
           continue;
         }
         let summary = { text: "", isError: false };
         try {
-          summary = lastAssistantText(await fetchMessages(childId));
-        } catch { /* best effort */ }
-        finished.push({ id: childId, name, summary });
+          const messages = await fetchMessages(childId);
+          if (!isActive(expectedGeneration)) return;
+          summary = lastAssistantText(messages);
+        } catch {
+          if (!isActive(expectedGeneration)) return;
+          // Transcript fetch is best effort.
+        }
+        finished.push({ id: childId, name: worker.name, categoryName: worker.categoryName, summary });
       } catch {
+        if (!isActive(expectedGeneration)) return;
         // Child gone (deleted?) — resolve so we don't retry forever.
         appendLedger(RESOLVED_ENTRY, childId);
       }
     }
-    if (finished.length === 0) return;
+    if (!isActive(expectedGeneration) || finished.length === 0) return;
 
     const details = {
       kind: "wakeup",
@@ -708,17 +764,23 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
       sections.join("\n\n---\n\n"),
       ``,
       `You can inspect details with sessions_read, follow up or redirect with sessions_prompt, or continue with your task.`,
-    ].join("\n"), details);
+    ].join("\n"), details, expectedGeneration);
+    if (!isActive(expectedGeneration)) return;
     if (ok) {
       for (const f of finished) {
         appendLedger(RESOLVED_ENTRY, f.id);
         markChildRead(f.id);
       }
+    } else {
+      // Keep completed workers live in the watcher until a later poll can
+      // successfully deliver their wakeup.
+      for (const f of finished) watch(f.id, f.name, f.categoryName);
     }
   }
 
   /** Deliver a wakeup to this session. Returns true only if delivery succeeded. */
-  async function deliverWakeup(text: string, details?: Record<string, unknown>): Promise<boolean> {
+  async function deliverWakeup(text: string, details?: Record<string, unknown>, expectedGeneration = generation): Promise<boolean> {
+    if (!isActive(expectedGeneration)) return false;
     // Preferred: pi custom message — typed, persisted, reaches the LLM as a
     // user message, and carries structured details for the pi-web UI card.
     try {
@@ -726,14 +788,18 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
         { customType: WAKEUP_CUSTOM_TYPE, content: text, display: true, details },
         { triggerTurn: true, deliverAs: "steer" },
       );
+      if (!isActive(expectedGeneration)) return false;
       return true;
     } catch (error) {
+      if (!isActive(expectedGeneration)) return false;
       const message = error instanceof Error ? error.message : String(error);
       if (/stale/i.test(message)) {
         // This extension instance was replaced (e.g. /reload). The new
         // instance re-arms from the persisted watch ledger and owns delivery
         // now — falling back here would double-deliver. Go silent and stop.
         console.error("[session-orchestrator] instance is stale after reload; stopping watcher (ledger hands off to the new instance)");
+        disposed = true;
+        generation += 1;
         if (timer) clearInterval(timer);
         timer = undefined;
         watched.clear();
@@ -741,14 +807,18 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
       }
       console.error(`[session-orchestrator] custom-message wakeup failed, falling back to /api/prompt: ${message}`);
     }
+    if (!isActive(expectedGeneration)) return false;
     if (selfSessionId) {
       try {
         await api("POST", "/api/prompt", { sessionId: selfSessionId, message: text, mode: "steer" });
+        if (!isActive(expectedGeneration)) return false;
         return true;
       } catch (error) {
+        if (!isActive(expectedGeneration)) return false;
         console.error(`[session-orchestrator] wakeup via /api/prompt failed: ${error instanceof Error ? error.message : error}`);
       }
     }
+    if (!isActive(expectedGeneration)) return false;
     try {
       pi.sendUserMessage(text);
       return true;
@@ -763,14 +833,16 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
     return false;
   }
 
-  async function poll() {
-    if (pollInFlight) return;
+  async function poll(expectedGeneration = generation) {
+    if (!isActive(expectedGeneration) || pollInFlight) return;
     pollInFlight = true;
     try {
       const completed: { w: Watched; summary: { text: string; isError: boolean } }[] = [];
       for (const w of Array.from(watched.values())) {
+        if (!isActive(expectedGeneration)) return;
         try {
           const state = await api("GET", `/api/state?sessionId=${encodeURIComponent(w.id)}`);
+          if (!isActive(expectedGeneration)) return;
           const running = Boolean(state?.runtime?.isRunning ?? (state?.isStreaming || state?.isCompacting));
           const pending = Number(state?.runtime?.pendingMessageCount || 0);
           w.errorPolls = 0;
@@ -785,25 +857,30 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           const settled = w.sawRunning ? w.idlePolls >= 1 : w.idlePolls >= 4;
           if (!settled) continue;
 
-          unwatch(w.id);
           let summary = { text: "", isError: false };
           try {
-            summary = lastAssistantText(await fetchMessages(w.id));
+            const messages = await fetchMessages(w.id);
+            if (!isActive(expectedGeneration)) return;
+            summary = lastAssistantText(messages);
           } catch {
+            if (!isActive(expectedGeneration)) return;
             // Transcript fetch is best-effort.
           }
           completed.push({ w, summary });
         } catch {
+          if (!isActive(expectedGeneration)) return;
           w.errorPolls += 1;
           if (w.errorPolls >= 20) {
-            unwatch(w.id);
-            void (async () => {
-              const ok = await deliverWakeup(
-                `🔔 [orchestrator] Lost track of worker "${w.name}" (session ${w.id}): status polling kept failing (it may have been deleted). Check it with sessions_status or in the sidebar.`,
-                { kind: "wakeup", workers: [{ sessionId: w.id, name: w.name, status: "error" }] },
-              );
-              if (ok) appendLedger(RESOLVED_ENTRY, w.id);
-            })();
+            const ok = await deliverWakeup(
+              `🔔 [orchestrator] Lost track of worker "${w.name}" (session ${w.id}): status polling kept failing (it may have been deleted). Check it with sessions_status or in the sidebar.`,
+              { kind: "wakeup", workers: [{ sessionId: w.id, name: w.name, status: "error" }] },
+              expectedGeneration,
+            );
+            if (!isActive(expectedGeneration)) return;
+            if (ok) {
+              unwatch(w.id);
+              appendLedger(RESOLVED_ENTRY, w.id);
+            }
           }
         }
       }
@@ -812,7 +889,9 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
       // two user messages back-to-back while the parent is idle races the
       // turn-start and can drop the second message.
       if (completed.length > 0) {
-        const stillRunning = Array.from(watched.values()).map((o) => `"${o.name}"`).join(", ");
+        const completedIds = new Set(completed.map(({ w }) => w.id));
+        const activeWorkers = Array.from(watched.values()).filter((w) => !completedIds.has(w.id));
+        const stillRunning = activeWorkers.map((o) => `"${o.name}"`).join(", ");
         const details = {
           kind: "wakeup",
           workers: completed.map(({ w, summary }) => ({
@@ -820,7 +899,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
             name: w.name,
             status: w.aborted ? "aborted" : summary.isError ? "error" : "idle",
           })),
-          stillRunning: Array.from(watched.values()).map((o) => ({ sessionId: o.id, name: o.name })),
+          stillRunning: activeWorkers.map((o) => ({ sessionId: o.id, name: o.name })),
         };
         const sections = completed.map(({ w, summary }) => [
           `Worker "${w.name}" (session ${w.id}) is now ${w.aborted ? "stopped (aborted)" : "idle"}.`,
@@ -835,15 +914,19 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           ``,
           stillRunning ? `Still running: ${stillRunning}.` : `No other workers are running.`,
           `You can inspect details with sessions_read, follow up or redirect with sessions_prompt, or continue with your task.`,
-        ].join("\n"), details);
+        ].join("\n"), details, expectedGeneration);
+        if (!isActive(expectedGeneration)) return;
         if (ok) {
           for (const { w } of completed) {
+            unwatch(w.id);
             appendLedger(RESOLVED_ENTRY, w.id);
             // The report was consumed by this session on the user's behalf —
             // clear the child's unread dot via the normal read endpoint.
             markChildRead(w.id);
           }
         }
+        // On total delivery failure, leave every completed worker watched. The
+        // next normal poll interval retries without creating a tight loop.
       }
     } finally {
       pollInFlight = false;
@@ -860,7 +943,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   pi.registerTool({
     name: "sessions_status",
     label: "Worker session status",
-    description: "Get a one-line status (running/idle, model, cost, message counts) for worker sessions. With no ids, reports all workers spawned from this session that are still tracked. Prefer waiting for wakeup messages over calling this in a loop.",
+    description: "Get a one-line status (running/idle, category, cost, message counts) for worker sessions. With no ids, reports all workers spawned from this session that are still tracked. Prefer waiting for wakeup messages over calling this in a loop.",
     promptSnippet: "Check status of spawned worker sessions",
     parameters: Type.Object({
       ids: Type.Optional(Type.Array(Type.String(), { description: "Session ids to check (defaults to all tracked workers)" })),
@@ -877,8 +960,8 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           const running = Boolean(state?.runtime?.isRunning);
           const stats = state?.stats || {};
           const name = state?.sessionName || state?.sessionTitle || shortId(id);
-          const model = state?.model?.id || "?";
-          lines.push(`${running ? "⏳ RUNNING" : "✔ idle"} — "${name}" (${id}) — model ${model} — $${Number(stats.cost || 0).toFixed(2)} — ${Number(stats.assistantMessages || 0)} assistant msgs${state?.runtime?.pendingMessageCount ? ` — ${state.runtime.pendingMessageCount} queued` : ""}`);
+          const categoryName = watched.get(id)?.categoryName || "Unknown";
+          lines.push(`${running ? "⏳ RUNNING" : "✔ idle"} — "${name}" (${id}) — category "${categoryName}" — $${Number(stats.cost || 0).toFixed(2)} — ${Number(stats.assistantMessages || 0)} assistant msgs${state?.runtime?.pendingMessageCount ? ` — ${state.runtime.pendingMessageCount} queued` : ""}`);
         } catch (error) {
           lines.push(`? — ${id} — status unavailable (${error instanceof Error ? error.message : error})`);
         }
@@ -961,6 +1044,8 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   // Lifecycle
   // -------------------------------------------------------------------------
   pi.on("session_shutdown", () => {
+    disposed = true;
+    generation += 1;
     if (timer) clearInterval(timer);
     timer = undefined;
     watched.clear();
diff --git a/server.ts b/server.ts
index fd3ae80..4b2877d 100644
--- a/server.ts
+++ b/server.ts
@@ -703,28 +703,53 @@ const server = createServer(async (req, res) => {
       if (url.pathname.startsWith("/api/settings/extensions/")) {
         const rest = url.pathname.slice("/api/settings/extensions/".length);
         const isReset = rest.endsWith("/reset");
-        const ownerId = decodeURIComponent(isReset ? rest.slice(0, -"/reset".length) : rest);
+        let ownerId: string;
+        try {
+          ownerId = decodeURIComponent(isReset ? rest.slice(0, -"/reset".length) : rest);
+        } catch {
+          return sendJson(res, 400, { ok: false, error: "malformed owner id" });
+        }
         const entry = sessionService.settingsSchemaEntry(ownerId);
-        if (!entry) return sendJson(res, 409, { ok: false, error: "extension not loaded" });
+        // Reset only needs stored data, not a live schema, so configuration for
+        // an unloaded extension can still be cleared. Editing needs the schema.
+        const storedOwner = (await settingsStore.read()).extensions?.[ownerId];
+        if (!entry && !(isReset && storedOwner)) {
+          return sendJson(res, 409, { ok: false, error: "extension not loaded" });
+        }
 
         if (method === "POST" && isReset) {
-          const settings = await settingsStore.resetExtension(ownerId);
-          broadcast({ type: "settings_updated", settings });
-          try { entry.schema.onChange?.(defaultSettingsValues(entry.schema)); } catch { /* ignore */ }
-          return sendJson(res, 200, { ok: true, settings });
+          const body = await readBody(req) as { expectedRevision?: unknown };
+          if (typeof body?.expectedRevision !== "number" || !Number.isInteger(body.expectedRevision) || body.expectedRevision < 0) {
+            return sendJson(res, 400, { ok: false, error: "expectedRevision must be a non-negative integer" });
+          }
+          try {
+            const settings = await settingsStore.resetExtension(ownerId, body.expectedRevision);
+            broadcast({ type: "settings_updated", settings });
+            if (entry) sessionService.notifySettingsChanged(ownerId, defaultSettingsValues(entry.schema));
+            return sendJson(res, 200, { ok: true, settings });
+          } catch (error) {
+            if (error instanceof ExtensionRevisionConflictError) {
+              return sendJson(res, 409, { ok: false, error: "revision conflict", actualRevision: error.actualRevision });
+            }
+            throw error;
+          }
         }
 
         if (method === "PATCH" && !isReset) {
+          if (!entry) return sendJson(res, 409, { ok: false, error: "extension not loaded" });
           const body = await readBody(req) as { values?: unknown; expectedRevision?: unknown };
+          if (typeof body?.expectedRevision !== "number" || !Number.isInteger(body.expectedRevision) || body.expectedRevision < 0) {
+            return sendJson(res, 400, { ok: false, error: "expectedRevision must be a non-negative integer" });
+          }
           const { values, errors } = validateSettingsValues(entry.schema, body?.values, { modelOptions: sessionService.modelOptionTokens() });
           if (errors.length) return sendJson(res, 422, { ok: false, errors });
           try {
             const settings = await settingsStore.patchExtension(ownerId, values, {
               schemaVersion: entry.schema.schemaVersion,
-              expectedRevision: typeof body?.expectedRevision === "number" ? body.expectedRevision : undefined,
+              expectedRevision: body.expectedRevision,
             });
             broadcast({ type: "settings_updated", settings });
-            try { entry.schema.onChange?.(values); } catch { /* ignore */ }
+            sessionService.notifySettingsChanged(ownerId, values);
             return sendJson(res, 200, { ok: true, settings, revision: settings.extensions?.[ownerId]?.revision ?? 0 });
           } catch (error) {
             if (error instanceof ExtensionRevisionConflictError) {
@@ -847,16 +872,25 @@ const server = createServer(async (req, res) => {
         const state = await decorateServiceState(baseState);
         noteViewerLeaseFromRequest(req, await sessionService.require(state.sessionId));
         const origin = body.origin && typeof body.origin === "object" ? body.origin as { sessionId?: unknown; kind?: unknown } : undefined;
+        let originWarning: string | undefined;
         if (origin && typeof origin.sessionId === "string" && origin.sessionId.trim() && state.sessionId) {
-          const sessionUiState = await sessionUiStateStore.setSessionOrigin(
-            state.sessionId,
-            origin.sessionId.trim(),
-            typeof origin.kind === "string" && origin.kind.trim() ? origin.kind.trim() : "spawn",
-          );
-          broadcast({ type: "session_ui_state_changed", sessionUiState });
+          // Lineage is best-effort metadata: the session already exists, so a
+          // failure here must not fail the request (that would hide the new
+          // session's id from the caller and leak an unreachable session).
+          try {
+            const sessionUiState = await sessionUiStateStore.setSessionOrigin(
+              state.sessionId,
+              origin.sessionId.trim(),
+              typeof origin.kind === "string" && origin.kind.trim() ? origin.kind.trim() : "spawn",
+            );
+            broadcast({ type: "session_ui_state_changed", sessionUiState });
+          } catch (error) {
+            originWarning = error instanceof Error ? error.message : String(error);
+            console.warn(`Could not record session origin for ${state.sessionId}:`, error);
+          }
         }
         broadcast({ type: "state_changed", ...state });
-        return sendJson(res, 200, { ok: true, ...state });
+        return sendJson(res, 200, { ok: true, ...state, ...(originWarning ? { originWarning } : {}) });
       }
 
       if (method === "POST" && url.pathname === "/api/session/cwd") {
diff --git a/server/extensions/webUi.ts b/server/extensions/webUi.ts
index e97bdbb..dd29b22 100644
--- a/server/extensions/webUi.ts
+++ b/server/extensions/webUi.ts
@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { ExtensionUIDialogOptions, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { PiWebArtifactAction, PiWebFooter, PiWebGitTab, PiWebHeaderAction, PiWebRegisterSettingsResult, PiWebSettingsRegistration, PiWebStoredSettings, PiWebUi } from "../../src/extensions.js";
 import type { createSettingsStore } from "../settings.js";
+import { isValidExtensionOwnerId } from "../settings.js";
 import { canonicalSchemaKey, defaultSettingsValues, validateSettingsValues } from "../extensionSettings.js";
 
 export interface WebUiBridgeDependencies {
@@ -59,25 +60,69 @@ const webHeaderActionStates = new WeakMap<object, WebHeaderActionState>();
 const webGitTabStates = new WeakMap<object, WebGitTabState>();
 const webArtifactActionStates = new WeakMap<object, WebArtifactActionState>();
 
-// Process-global extension-settings schema registry (R2.2): decoupled from any
-// one session. Values live in settingsStore (global); schemas are refcounted
-// across the live sessions that registered them.
+// Process-global extension-settings schema registry: decoupled from any one
+// session. Values live in settingsStore (global). A schema stays registered
+// while at least one live session registers it, and every live registrant is
+// notified of changes with its own callback.
+type SettingsRegistrant = { schema: PiWebSettingsRegistration; sessionId: string };
 type RegisteredSettingsSchema = {
+  /** Canonical (first) registrant's schema: used for validation + transport. */
   schema: PiWebSettingsRegistration;
   canonicalKey: string;
-  refCount: number;
+  registrants: Map<object, SettingsRegistrant>;
+  /** Shared so concurrent first registrations migrate exactly once. */
+  migration: Promise<{ migrated: boolean; usedBackup: boolean; error?: string }>;
+  /** Only exposed once migration settled, so nothing validates mid-migration. */
+  ready: boolean;
+  migrationError?: string;
 };
 const activeSettingsSchemas = new Map<string, RegisteredSettingsSchema>();
-// Which owner ids each live session registered (for shutdown decrement).
-const sessionRegisteredSettings = new WeakMap<object, Set<string>>();
+// Sessions that shut down; a registration awaiting migration must not complete.
+const disposedSettingsSessions = new WeakSet<object>();
+
+const settingsFieldTypes = new Set(["toggle", "text", "textarea", "number", "select", "list"]);
+const settingsFieldKeyPattern = /^[A-Za-z0-9_]{1,64}$/;
+
+/** Structural validation of a contributed descriptor, before anything is reserved. */
+function settingsSchemaProblem(schema: PiWebSettingsRegistration, depth = 0, fields = schema?.fields): string | undefined {
+  if (depth === 0) {
+    if (!schema || typeof schema !== "object") return "schema must be an object";
+    if (!isValidExtensionOwnerId(schema.id)) return `settings id "${String(schema.id)}" must be namespaced as <extension>.<schema>`;
+    if (typeof schema.title !== "string" || !schema.title.trim()) return "schema.title is required";
+    if (!Number.isInteger(schema.schemaVersion) || schema.schemaVersion < 1) return "schema.schemaVersion must be a positive integer";
+  }
+  if (depth > 2) return "schema nesting is too deep";
+  if (!Array.isArray(fields) || fields.length === 0) return "schema.fields must be a non-empty array";
+  if (fields.length > 64) return "schema.fields has too many entries (max 64)";
+  const keys = new Set<string>();
+  for (const field of fields) {
+    if (!field || typeof field !== "object") return "each field must be an object";
+    if (!settingsFieldKeyPattern.test(String(field.key))) return `invalid field key "${String(field.key)}"`;
+    if (keys.has(field.key)) return `duplicate field key "${field.key}"`;
+    keys.add(field.key);
+    if (!settingsFieldTypes.has(String(field.type))) return `unsupported field type "${String(field.type)}" on "${field.key}"`;
+    if (typeof field.label !== "string" || !field.label.trim()) return `field "${field.key}" needs a label`;
+    if (field.type === "list") {
+      const nested = settingsSchemaProblem(schema, depth + 1, field.itemFields);
+      if (nested) return nested;
+    }
+    if (field.optionsFromField !== undefined) {
+      const [listKey, itemKey] = String(field.optionsFromField).split(".");
+      if (!listKey || !itemKey) return `field "${field.key}" has a malformed optionsFromField`;
+    }
+  }
+  return undefined;
+}
 
-function serializableSettingsSchema(schema: PiWebSettingsRegistration) {
-  const { migrate: _migrate, onChange: _onChange, ...rest } = schema;
-  return rest;
+function serializableSettingsSchema(entry: RegisteredSettingsSchema) {
+  const { migrate: _migrate, onChange: _onChange, ...rest } = entry.schema;
+  return entry.migrationError ? { ...rest, migrationError: entry.migrationError } : rest;
 }
 
 function activeSettingsSchemaList() {
-  return Array.from(activeSettingsSchemas.values()).map((e) => serializableSettingsSchema(e.schema));
+  return Array.from(activeSettingsSchemas.values())
+    .filter((entry) => entry.ready && entry.registrants.size > 0)
+    .map(serializableSettingsSchema);
 }
 
 function broadcastSettingsSchemas() {
@@ -118,56 +163,76 @@ async function registerSessionSettings(
   value: any,
   schema: PiWebSettingsRegistration,
 ): Promise<PiWebRegisterSettingsResult> {
-  if (!schema || typeof schema.id !== "string" || !Array.isArray(schema.fields)) {
-    return { registered: false, migrated: false, usedBackup: false, error: "invalid settings schema" };
+  const problem = settingsSchemaProblem(schema);
+  if (problem) {
+    console.warn(`pi-web: rejected settings registration: ${problem}`);
+    return { registered: false, migrated: false, usedBackup: false, error: problem };
   }
   const id = schema.id;
   const canonical = canonicalSchemaKey(schema);
-  const existing = activeSettingsSchemas.get(id);
-  if (existing && existing.canonicalKey !== canonical) {
-    // First-registered wins; a divergent schema for the same id is rejected.
-    console.warn(`pi-web: settings id "${id}" already registered with a different schema; rejecting new registration.`);
-    return { registered: false, migrated: false, usedBackup: false, error: `settings id "${id}" already registered with a different schema` };
+  const session = value as object;
+
+  // Reserve the id SYNCHRONOUSLY (before any await) so concurrent first
+  // registrations cannot both migrate or both claim the id.
+  let entry = activeSettingsSchemas.get(id);
+  if (entry && entry.canonicalKey !== canonical) {
+    const error = `settings id "${id}" is already registered with a different schema`;
+    console.warn(`pi-web: ${error}; rejecting new registration.`);
+    return { registered: false, migrated: false, usedBackup: false, error };
+  }
+  const reserved = !entry;
+  if (!entry) {
+    entry = {
+      schema,
+      canonicalKey: canonical,
+      registrants: new Map(),
+      migration: migrateStoredSettings(schema),
+      ready: false,
+    };
+    activeSettingsSchemas.set(id, entry);
   }
 
-  let migrated = false;
-  let usedBackup = false;
-  let error: string | undefined;
-  if (!existing) {
-    const result = await migrateStoredSettings(schema);
-    migrated = result.migrated;
-    usedBackup = result.usedBackup;
-    error = result.error;
-    activeSettingsSchemas.set(id, { schema, canonicalKey: canonical, refCount: 0 });
-  } else {
-    existing.schema = schema; // refresh callbacks to the latest registrant
+  const result = await entry.migration;
+  entry.ready = true;
+  if (result.error) {
+    entry.migrationError = result.error;
+    console.warn(`pi-web: settings migration for "${id}" fell back to defaults: ${result.error}`);
   }
 
-  const entry = activeSettingsSchemas.get(id)!;
-  const owned = sessionRegisteredSettings.get(value as object) ?? new Set<string>();
-  if (!owned.has(id)) {
-    entry.refCount += 1;
-    owned.add(id);
-    sessionRegisteredSettings.set(value as object, owned);
+  // The session may have shut down while migration was in flight; never
+  // register a dead session (and drop a reservation nobody else claimed).
+  if (disposedSettingsSessions.has(session)) {
+    if (reserved && entry.registrants.size === 0) activeSettingsSchemas.delete(id);
+    return { registered: false, migrated: result.migrated, usedBackup: result.usedBackup, error: "session shut down during registration" };
   }
+
+  entry.registrants.set(session, { schema, sessionId: String(value?.sessionId || "") });
   broadcastSettingsSchemas();
-  return { registered: true, migrated, usedBackup, error };
+  return { registered: true, migrated: result.migrated, usedBackup: result.usedBackup, error: result.error };
+}
+
+/** Notify every live registrant, each with its own callback and session id. */
+function notifySettingsChanged(id: string, values: Record<string, unknown>) {
+  const entry = activeSettingsSchemas.get(id);
+  if (!entry) return;
+  for (const registrant of entry.registrants.values()) {
+    try {
+      registrant.schema.onChange?.(values, { sessionId: registrant.sessionId });
+    } catch (error) {
+      console.warn(`pi-web: settings onChange for "${id}" threw:`, error);
+    }
+  }
 }
 
 function releaseSessionSettings(value: any) {
-  const owned = sessionRegisteredSettings.get(value as object);
-  if (!owned) return;
+  const session = value as object;
+  disposedSettingsSessions.add(session);
   let changed = false;
-  for (const id of owned) {
-    const entry = activeSettingsSchemas.get(id);
-    if (!entry) continue;
-    entry.refCount -= 1;
-    if (entry.refCount <= 0) {
-      activeSettingsSchemas.delete(id);
-      changed = true;
-    }
+  for (const [id, entry] of activeSettingsSchemas) {
+    if (!entry.registrants.delete(session)) continue;
+    changed = true;
+    if (entry.registrants.size === 0) activeSettingsSchemas.delete(id);
   }
-  sessionRegisteredSettings.delete(value as object);
   if (changed) broadcastSettingsSchemas();
 }
 
@@ -641,8 +706,13 @@ async function bindWebExtensions(value: any) {
     invokeArtifactAction,
     invokeGitTab,
     respond,
+    registerSettings: (session: any, schema: PiWebSettingsRegistration) => registerSessionSettings(session, schema),
     settingsSchemas: activeSettingsSchemaList,
-    settingsSchemaEntry: (id: string) => activeSettingsSchemas.get(id),
+    settingsSchemaEntry: (id: string) => {
+      const entry = activeSettingsSchemas.get(id);
+      return entry?.ready && entry.registrants.size > 0 ? entry : undefined;
+    },
+    notifySettingsChanged,
     releaseSessionSettings,
   };
 }
diff --git a/server/session/service.ts b/server/session/service.ts
index 3bf6d71..22ad2da 100644
--- a/server/session/service.ts
+++ b/server/session/service.ts
@@ -238,6 +238,7 @@ export class LocalSessionService implements SessionService {
   webUiEntries(value: PiWebSession) { return this.webUiBridge.entries(value); }
   settingsSchemas() { return this.webUiBridge.settingsSchemas(); }
   settingsSchemaEntry(id: string) { return this.webUiBridge.settingsSchemaEntry(id); }
+  notifySettingsChanged(id: string, values: Record<string, unknown>) { return this.webUiBridge.notifySettingsChanged(id, values); }
   modelOptionTokens() {
     return new Set(this.deps.modelRuntime.getAvailableSnapshot().flatMap((model) =>
       model?.provider && model?.id ? [`${model.provider}:${model.id}`] : [],
diff --git a/server/settings.ts b/server/settings.ts
index 31f0154..b6ee3cb 100644
--- a/server/settings.ts
+++ b/server/settings.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
@@ -208,12 +209,9 @@ export function applyExtensionValues(
   }
   const next = cloneSettings(current);
   const existing = next.extensions?.[ownerId];
-  if (
-    opts?.expectedRevision !== undefined &&
-    existing !== undefined &&
-    existing.revision !== opts.expectedRevision
-  ) {
-    throw new ExtensionRevisionConflictError(ownerId, existing.revision, opts.expectedRevision);
+  const actualRevision = existing?.revision ?? 0;
+  if (opts?.expectedRevision !== undefined && actualRevision !== opts.expectedRevision) {
+    throw new ExtensionRevisionConflictError(ownerId, actualRevision, opts.expectedRevision);
   }
   const record: StoredExtensionSettings = {
     schemaVersion: opts?.schemaVersion ?? existing?.schemaVersion ?? 0,
@@ -230,9 +228,17 @@ export function applyExtensionValues(
   return normalizeSettings(next);
 }
 
-/** Drop one owner's stored record entirely (reset). */
-export function resetExtensionValues(current: PiWebSettings, ownerId: string): PiWebSettings {
+/** Drop one owner's stored record entirely (reset), guarded by its current revision. */
+export function resetExtensionValues(
+  current: PiWebSettings,
+  ownerId: string,
+  expectedRevision: number,
+): PiWebSettings {
   const next = cloneSettings(current);
+  const existing = next.extensions?.[ownerId];
+  if (existing && existing.revision !== expectedRevision) {
+    throw new ExtensionRevisionConflictError(ownerId, existing.revision, expectedRevision);
+  }
   if (next.extensions && ownerId in next.extensions) {
     delete next.extensions[ownerId];
     if (Object.keys(next.extensions).length === 0) delete next.extensions;
@@ -348,8 +354,16 @@ export function applySettingsPatch(current: PiWebSettings, patch: unknown): PiWe
 
 export function createSettingsStore(file: string) {
   let cached: PiWebSettings | undefined;
+  let operationChain: Promise<void> = Promise.resolve();
 
-  async function read() {
+  /** Keep every store operation ordered; mutation read/apply/write sequences never interleave. */
+  function enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const result = operationChain.then(operation);
+    operationChain = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  async function readUnlocked() {
     if (cached) return cloneSettings(cached);
     try {
       cached = normalizeSettings(JSON.parse(await readFile(file, "utf-8")));
@@ -362,17 +376,26 @@ export function createSettingsStore(file: string) {
     return cloneSettings(cached);
   }
 
-  async function write(settings: PiWebSettings) {
-    cached = normalizeSettings(settings);
+  async function writeUnlocked(settings: PiWebSettings) {
+    const normalized = normalizeSettings(settings);
     await mkdir(dirname(file), { recursive: true });
-    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tmp, `${JSON.stringify(cached, null, 2)}\n`, "utf-8");
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
     await rename(tmp, file);
+    cached = normalized;
     return cloneSettings(cached);
   }
 
-  async function patch(value: unknown) {
-    return write(applySettingsPatch(await read(), value));
+  function read() {
+    return enqueue(readUnlocked);
+  }
+
+  function write(settings: PiWebSettings) {
+    return enqueue(() => writeUnlocked(settings));
+  }
+
+  function patch(value: unknown) {
+    return enqueue(async () => writeUnlocked(applySettingsPatch(await readUnlocked(), value)));
   }
 
   return { file, read, write, patch, patchExtension, resetExtension };
@@ -382,7 +405,7 @@ export function createSettingsStore(file: string) {
    * validation must be done by the caller against the live schema; this only
    * enforces bounds + the optional revision guard, then writes.
    */
-  async function patchExtension(
+  function patchExtension(
     ownerId: string,
     nextValues: JsonObject,
     opts?: {
@@ -391,11 +414,11 @@ export function createSettingsStore(file: string) {
       backup?: { schemaVersion: number; values: JsonObject };
     },
   ) {
-    return write(applyExtensionValues(await read(), ownerId, nextValues, opts));
+    return enqueue(async () => writeUnlocked(applyExtensionValues(await readUnlocked(), ownerId, nextValues, opts)));
   }
 
   /** Drop one owner's stored record (reset to unconfigured). */
-  async function resetExtension(ownerId: string) {
-    return write(resetExtensionValues(await read(), ownerId));
+  function resetExtension(ownerId: string, expectedRevision: number) {
+    return enqueue(async () => writeUnlocked(resetExtensionValues(await readUnlocked(), ownerId, expectedRevision)));
   }
 }
diff --git a/src/app/sessionRefs.ts b/src/app/sessionRefs.ts
new file mode 100644
index 0000000..0d8b6e6
--- /dev/null
+++ b/src/app/sessionRefs.ts
@@ -0,0 +1,72 @@
+/**
+ * Structured session references contributed by extensions.
+ *
+ * Any extension-provided `details` payload (custom messages, tool results) may
+ * reference other sessions so pi-web can render links to them. The contract is
+ * deliberately explicit and generic: a reference LIST (`sessionRefs`, `sessions`
+ * or `workers`) means "surface links to these sessions". A bare `sessionId`
+ * field is treated as incidental metadata, not a link request, so tools that
+ * merely echo the session they acted on do not sprout chips.
+ *
+ * Core stays generic here: no extension or tool name is special-cased.
+ */
+
+export type SessionRef = { sessionId: string; name?: string; status?: string };
+
+/** Bounds: extension details are untrusted input and may be persisted. */
+export const maxSessionRefs = 8;
+export const maxSessionRefLabel = 60;
+const sessionIdPattern = /^[A-Za-z0-9._:-]{1,100}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function cleanLabel(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const cleaned = value.replace(/[\u0000-\u001F\u007F]/g, "").trim();
+  return cleaned ? cleaned.slice(0, maxSessionRefLabel) : undefined;
+}
+
+/**
+ * Extract bounded, de-duplicated session references from an extension-provided
+ * `details` payload. Returns an empty array when nothing valid is referenced.
+ */
+export function sessionRefsFromDetails(details: unknown): SessionRef[] {
+  if (!isRecord(details)) return [];
+
+  const lists = [details.sessionRefs, details.sessions, details.workers].filter(Array.isArray) as unknown[][];
+  if (lists.length === 0) return [];
+
+  const refs: SessionRef[] = [];
+  const seen = new Set<string>();
+  for (const list of lists) {
+    for (const entry of list) {
+      if (refs.length >= maxSessionRefs) return refs;
+      if (!isRecord(entry)) continue;
+      const sessionId = typeof entry.sessionId === "string" ? entry.sessionId.trim() : "";
+      if (!sessionIdPattern.test(sessionId) || seen.has(sessionId)) continue;
+      seen.add(sessionId);
+      refs.push({
+        sessionId,
+        name: cleanLabel(entry.name),
+        status: typeof entry.status === "string" ? entry.status.slice(0, 24) : undefined,
+      });
+    }
+  }
+  return refs;
+}
+
+/** Shared presentation for a session-reference chip. */
+export function sessionRefChipText(ref: SessionRef): string {
+  const icon = ref.status === "error" ? "⚠" : ref.status === "aborted" ? "⏹" : "↗";
+  return `${icon} ${ref.name || ref.sessionId.slice(-8)}`;
+}
+
+export function sessionRefChipClass(ref: SessionRef): string {
+  return `customCardSessionChip${ref.status === "error" ? " status-error" : ref.status === "aborted" ? " status-aborted" : ""}`;
+}
+
+export function sessionRefHref(ref: SessionRef): string {
+  return `/?sessionId=${encodeURIComponent(ref.sessionId)}`;
+}
diff --git a/src/extensions.ts b/src/extensions.ts
index 63812d5..3db3c32 100644
--- a/src/extensions.ts
+++ b/src/extensions.ts
@@ -147,7 +147,12 @@ export type PiWebSettingsRegistration = PiWebSettingsSchema & {
     oldVersion: number,
   ) => Record<string, unknown> | Promise<Record<string, unknown>>;
   /** Called after a persisted change (this owner only), with the new values. */
-  onChange?: (values: Record<string, unknown>) => void;
+  /**
+   * Called after a persisted change to this owner's values. Every live
+   * registrant is notified with its own callback; `info.sessionId` identifies
+   * which session's registration is being notified.
+   */
+  onChange?: (values: Record<string, unknown>, info: { sessionId: string }) => void;
 };
 
 export type PiWebRegisterSettingsResult = {
diff --git a/src/messages/messageList.ts b/src/messages/messageList.ts
index 462b56b..59be5a9 100644
--- a/src/messages/messageList.ts
+++ b/src/messages/messageList.ts
@@ -6,6 +6,7 @@ import { attachImageActions } from "../components/imageActions.js";
 import type { MarkdownRenderer } from "../markdown/render.js";
 import { assistantErrorBody, cleanThinkingText, imageFileName, imagesFromRawContent, isRetryableAssistantError, messageText, normalizeAssistantError, shouldCollapseMessage, stripImagePathNote, thinkingTextSegments } from "./content.js";
 import { playToolCardEntry, playToolCardStateTransition } from "./entryAnimation.js";
+import { sessionRefChipClass, sessionRefChipText, sessionRefHref, sessionRefsFromDetails } from "../app/sessionRefs.js";
 
 export type AddToolHistoryCard = (toolName: string, isError: boolean, result: unknown, args?: Record<string, unknown>) => void;
 export type AddPendingToolCard = (toolCallId: string | undefined, toolName: string, args: Record<string, unknown>, startedAt?: string | number | Date) => void;
@@ -685,33 +686,12 @@ export function createMessageList(options: {
     return text.charAt(0).toUpperCase() + text.slice(1);
   }
 
-  function customDetailSessionRefs(details: unknown): Array<{ sessionId: string; name?: string; status?: string }> {
-    if (!details || typeof details !== "object") return [];
-    const refs: Array<{ sessionId: string; name?: string; status?: string }> = [];
-    const push = (value: unknown) => {
-      if (!value || typeof value !== "object") return;
-      const record = value as Record<string, unknown>;
-      const sessionId = typeof record.sessionId === "string" ? record.sessionId.trim() : "";
-      if (!sessionId) return;
-      refs.push({
-        sessionId,
-        name: typeof record.name === "string" && record.name.trim() ? record.name.trim() : undefined,
-        status: typeof record.status === "string" ? record.status : undefined,
-      });
-    };
-    const record = details as Record<string, unknown>;
-    if (Array.isArray(record.workers)) for (const worker of record.workers) push(worker);
-    else if (Array.isArray(record.sessions)) for (const item of record.sessions) push(item);
-    else push(record);
-    return refs;
-  }
-
   function addCustomMessageCard(message: { text?: string; customType?: string; details?: unknown; isError?: boolean; raw?: any }) {
     invalidatePendingRefreshes();
     const text = String(message.text || "").trim();
     const customType = message.customType || message.raw?.customType || "";
     const details = message.details ?? message.raw?.details;
-    const sessionRefs = customDetailSessionRefs(details);
+    const sessionRefs = sessionRefsFromDetails(details);
 
     // Realtime projection can briefly emit a details-only copy of a custom
     // worker event after its complete transcript entry has already rendered.
@@ -742,10 +722,9 @@ export function createMessageList(options: {
 
     for (const ref of sessionRefs) {
       const chip = document.createElement("a");
-      chip.className = `customCardSessionChip${ref.status === "error" ? " status-error" : ref.status === "aborted" ? " status-aborted" : ""}`;
-      chip.href = `/?sessionId=${encodeURIComponent(ref.sessionId)}`;
-      const statusIcon = ref.status === "error" ? "⚠" : ref.status === "aborted" ? "⏹" : "✓";
-      chip.textContent = `${statusIcon} ${ref.name || ref.sessionId.slice(-8)} ↗`;
+      chip.className = sessionRefChipClass(ref);
+      chip.href = sessionRefHref(ref);
+      chip.textContent = sessionRefChipText(ref);
       chip.title = `Open session ${ref.sessionId}`;
       header.append(chip);
     }
diff --git a/src/sessions/sessionDrawer.ts b/src/sessions/sessionDrawer.ts
index b96cd52..6861ee4 100644
--- a/src/sessions/sessionDrawer.ts
+++ b/src/sessions/sessionDrawer.ts
@@ -93,17 +93,6 @@ function shouldCloseDrawerAfterSessionSwitch() {
 const knownSessionCwdsStorageKey = "pi-web-known-session-cwds";
 const sessionDrawerOpenStorageKey = "pi-web-session-drawer-open";
 
-type SessionTimeField = "created" | "modified";
-type SessionTimeRange = "all" | "day" | "week" | "month" | "year";
-
-const sessionTimeRanges: Array<{ value: SessionTimeRange; label: string; milliseconds?: number }> = [
-  { value: "all", label: "All time" },
-  { value: "day", label: "Past 24 hours", milliseconds: 24 * 60 * 60 * 1000 },
-  { value: "week", label: "Past week", milliseconds: 7 * 24 * 60 * 60 * 1000 },
-  { value: "month", label: "Past month", milliseconds: 30 * 24 * 60 * 60 * 1000 },
-  { value: "year", label: "Past year", milliseconds: 365 * 24 * 60 * 60 * 1000 },
-];
-
 function readPersistedSessionDrawerOpen() {
   try {
     return localStorage.getItem(sessionDrawerOpenStorageKey) === "true";
@@ -186,8 +175,6 @@ export function createSessions(options: {
   let sessionBarGestureInFlight = false;
   let sessionBarRenderQueued = false;
   let suppressTabClickUntil = 0;
-  let sessionTimeField: SessionTimeField = "modified";
-  let sessionTimeRange: SessionTimeRange = "all";
   type SessionRowTool = "pin" | SessionMarkerColorId;
   let selectedSessionRowTool: SessionRowTool = state.selectedMarkerColor;
 
@@ -721,27 +708,13 @@ export function createSessions(options: {
       .filter((color) => allowedMarkerColors.has(color));
   }
 
-  function selectedSessionTimeRange() {
-    return sessionTimeRanges.find((range) => range.value === sessionTimeRange) || sessionTimeRanges[0];
-  }
-
-  function matchesSessionTimeFilter(item: SessionInfo) {
-    const range = selectedSessionTimeRange();
-    if (!range.milliseconds) return true;
-    const value = Date.parse(item[sessionTimeField]);
-    return Number.isFinite(value) && value >= Date.now() - range.milliseconds;
-  }
-
   function renderSessionColorFilterButton() {
     if (!sessionColorFilterButton) return;
     const colors = sortedAllowedMarkerColors();
-    const timeRange = selectedSessionTimeRange();
     sessionColorFilterButton.textContent = "";
-    const timeFilterActive = sessionTimeRange !== "all";
-    const active = colors.length > 0 || unreadFilterActive || timeFilterActive;
+    const active = colors.length > 0 || unreadFilterActive;
     sessionColorFilterButton.classList.toggle("active", active);
     const parts = [
-      timeFilterActive ? `${sessionTimeField} ${timeRange.label.toLowerCase()}` : "all dates",
       colors.length === 0 ? "all colors allowed" : `colors: ${colors.map(markerColorLabel).join(", ")}`,
       unreadFilterActive ? "unread only" : "read and unread",
     ];
@@ -1035,37 +1008,6 @@ export function createSessions(options: {
     unreadButton.append(unreadLabel);
     menu.append(unreadButton);
 
-    const timeTitle = document.createElement("div");
-    timeTitle.className = "sessionColorFilterTitle";
-    timeTitle.textContent = "Time";
-
-    const timeControls = document.createElement("div");
-    timeControls.className = "sessionTimeFilterControls";
-
-    const timeFieldSelect = document.createElement("select");
-    timeFieldSelect.className = "sessionTimeFilterSelect";
-    timeFieldSelect.setAttribute("aria-label", "Session date field");
-    for (const optionValue of ["created", "modified"] as const) {
-      const option = document.createElement("option");
-      option.value = optionValue;
-      option.textContent = optionValue === "created" ? "Created" : "Modified";
-      option.selected = sessionTimeField === optionValue;
-      timeFieldSelect.append(option);
-    }
-
-    const timeRangeSelect = document.createElement("select");
-    timeRangeSelect.className = "sessionTimeFilterSelect";
-    timeRangeSelect.setAttribute("aria-label", "Session time range");
-    for (const range of sessionTimeRanges) {
-      const option = document.createElement("option");
-      option.value = range.value;
-      option.textContent = range.label;
-      option.selected = sessionTimeRange === range.value;
-      timeRangeSelect.append(option);
-    }
-    timeControls.append(timeFieldSelect, timeRangeSelect);
-    menu.append(timeTitle, timeControls);
-
     const colorTitle = document.createElement("div");
     colorTitle.className = "sessionColorFilterTitle";
     colorTitle.textContent = "Marker colors";
@@ -1103,17 +1045,6 @@ export function createSessions(options: {
       updateMenuState();
     });
 
-    timeFieldSelect.addEventListener("change", () => {
-      sessionTimeField = timeFieldSelect.value === "created" ? "created" : "modified";
-      renderSessionList(cachedSessions);
-    });
-
-    timeRangeSelect.addEventListener("change", () => {
-      const value = timeRangeSelect.value as SessionTimeRange;
-      sessionTimeRange = sessionTimeRanges.some((range) => range.value === value) ? value : "all";
-      renderSessionList(cachedSessions);
-    });
-
     for (const color of sessionMarkerColors) {
       const button = document.createElement("button");
       button.type = "button";
@@ -1813,14 +1744,13 @@ export function createSessions(options: {
     const query = sessionSearchInput?.value.trim().toLowerCase() || "";
     const matchesFilter = (item: SessionInfo) => {
       const marker = markerForSession(item.id);
-      if (!matchesSessionTimeFilter(item)) return false;
       if (allowedMarkerColors.size > 0 && !allowedMarkerColors.has(marker?.color as SessionMarkerColorId)) return false;
       if (unreadFilterActive && !isSessionUnread(item.id, Boolean(item.unread), Boolean(item.runtime?.isRunning))) return false;
       if (!query) return true;
       return [sessionTitle(item), item.cwd || "", item.firstMessage || ""]
         .some((value) => value.toLowerCase().includes(query));
     };
-    const filterActive = Boolean(query || allowedMarkerColors.size > 0 || unreadFilterActive || sessionTimeRange !== "all");
+    const filterActive = Boolean(query || allowedMarkerColors.size > 0 || unreadFilterActive);
     renderSessionColorFilterButton();
 
     const groups = new Map<string, SessionInfo[]>();
@@ -1912,11 +1842,9 @@ export function createSessions(options: {
         empty.className = "sessionEmpty";
         empty.textContent = query
           ? "No matching sessions in this folder."
-          : unreadFilterActive && sessionTimeRange === "all" && allowedMarkerColors.size === 0
+          : unreadFilterActive
             ? "No unread sessions in this folder."
-            : sessionTimeRange === "all" && allowedMarkerColors.size > 0
-              ? "No sessions in the selected colors."
-              : "No sessions match these filters in this folder.";
+            : "No sessions in the selected colors.";
         group.append(empty);
       }
 
@@ -1950,11 +1878,9 @@ export function createSessions(options: {
       empty.className = "sessionEmpty";
       empty.textContent = query
         ? "No matching sessions."
-        : unreadFilterActive && sessionTimeRange === "all" && allowedMarkerColors.size === 0
+        : unreadFilterActive
           ? "No unread sessions."
-          : sessionTimeRange === "all" && allowedMarkerColors.size > 0
-            ? "No sessions in the selected colors."
-            : "No sessions match these filters.";
+          : "No sessions in the selected colors.";
       elements.sessionListEl.append(empty);
     }
   }
diff --git a/src/settings/extensionSettings.ts b/src/settings/extensionSettings.ts
index f7e99d4..e585f0c 100644
--- a/src/settings/extensionSettings.ts
+++ b/src/settings/extensionSettings.ts
@@ -119,6 +119,20 @@ export function createExtensionSettings(options: {
     return errors.get(id)?.find((e) => e.path === path)?.message;
   }
 
+  function addAriaDescription(control: HTMLElement, descriptionId: string): void {
+    const ids = new Set((control.getAttribute("aria-describedby") ?? "").split(/\s+/).filter(Boolean));
+    ids.add(descriptionId);
+    control.setAttribute("aria-describedby", Array.from(ids).join(" "));
+  }
+
+  function markRequired(control: HTMLElement, required: boolean | undefined): void {
+    if (!required) return;
+    control.setAttribute("aria-required", "true");
+    if (control instanceof HTMLInputElement || control instanceof HTMLSelectElement || control instanceof HTMLTextAreaElement) {
+      control.required = true;
+    }
+  }
+
   function fieldRow(labelText: string, control: HTMLElement, descr: string | undefined, errText: string | undefined): HTMLElement {
     const label = el("label", { class: "settingsField extSettingsField" });
     label.append(el("span", {}, [labelText]));
@@ -131,23 +145,38 @@ export function createExtensionSettings(options: {
       control.id = ctrlId;
       err.id = `${ctrlId}-err`;
       control.setAttribute("aria-invalid", "true");
-      control.setAttribute("aria-describedby", err.id);
+      addAriaDescription(control, err.id);
       label.append(err);
     }
     return label;
   }
 
-  // Render one scalar/select control bound to obj[field.key].
-  function scalarControl(id: string, field: WebFieldDescriptor, obj: Values, ownerDraft: Values, onStructural: () => void): HTMLElement {
+  // Render one scalar/select control bound to obj[field.key]. `onValueChanged`
+  // runs in the same event as the assignment, before a structural re-render.
+  function scalarControl(
+    id: string,
+    field: WebFieldDescriptor,
+    obj: Values,
+    ownerDraft: Values,
+    onStructural: () => void,
+    onValueChanged?: (value: unknown) => void,
+  ): HTMLElement {
     const value = obj[field.key];
+    const assign = (next: unknown) => {
+      obj[field.key] = next;
+      onValueChanged?.(next);
+    };
     if (field.type === "toggle") {
       const input = el("input", { type: "checkbox", checked: Boolean(value) });
-      input.addEventListener("change", () => { obj[field.key] = input.checked; });
+      markRequired(input, field.required);
+      input.addEventListener("change", () => { assign(input.checked); });
       const wrap = el("span", { class: "extSettingsToggle" }, [input]);
+      if (field.required) wrap.setAttribute("aria-required", "true");
       return wrap;
     }
     if (field.type === "select") {
       const select = el("select");
+      markRequired(select, field.required);
       const opts = optionsForSelect(field, ownerDraft);
       select.append(el("option", { value: "" }, [field.required ? "Select…" : "— none —"]));
       for (const o of opts) select.append(el("option", { value: o.value }, [o.label ?? o.value]));
@@ -157,62 +186,97 @@ export function createExtensionSettings(options: {
         select.append(el("option", { value }, [`${value} (unavailable)`]));
         select.value = value;
       }
-      select.addEventListener("change", () => { obj[field.key] = select.value; });
+      select.addEventListener("change", () => { assign(select.value); });
       return select;
     }
     if (field.type === "textarea") {
       const ta = el("textarea", { value: typeof value === "string" ? value : "", rows: 3 });
+      markRequired(ta, field.required);
       if (field.maxLength) ta.maxLength = field.maxLength;
-      ta.addEventListener("input", () => { obj[field.key] = ta.value; });
+      ta.addEventListener("input", () => { assign(ta.value); });
       return ta;
     }
     if (field.type === "number") {
       const input = el("input", { type: "number", value: value === undefined ? "" : String(value) });
+      markRequired(input, field.required);
       if (field.min !== undefined) input.min = String(field.min);
       if (field.max !== undefined) input.max = String(field.max);
-      input.addEventListener("input", () => { obj[field.key] = input.value === "" ? undefined : Number(input.value); });
+      input.addEventListener("input", () => { assign(input.value === "" ? undefined : Number(input.value)); });
       return input;
     }
     // text
     const input = el("input", { type: "text", value: typeof value === "string" ? value : "" });
+    markRequired(input, field.required);
     if (field.maxLength) input.maxLength = field.maxLength;
     // a text field may feed a select's optionsFromField → re-render on commit
-    input.addEventListener("input", () => { obj[field.key] = input.value; });
-    input.addEventListener("change", () => { obj[field.key] = input.value; onStructural(); });
+    input.addEventListener("input", () => { assign(input.value); });
+    input.addEventListener("change", () => { assign(input.value); onStructural(); });
     return input;
   }
 
   // A default-ref is a top-level select whose options come from a list column
   // (optionsFromField). We render it as a per-row star toggle instead of a
   // separate dropdown, and skip the standalone select.
-  type DefaultRef = { selectKey: string; itemKey: string };
+  type DefaultRef = { selectKey: string; itemKey: string; label: string; required?: boolean };
+
+  function domIdPart(value: string): string {
+    return value.replace(/[^a-zA-Z0-9_-]/g, "-");
+  }
 
   function listControl(schema: WebSettingsSchema, field: WebFieldDescriptor, ownerDraft: Values, defaultRef?: DefaultRef): HTMLElement {
     const wrap = el("div", { class: "extSettingsList" });
+    wrap.setAttribute("role", "group");
+    wrap.setAttribute("aria-label", field.label);
+    if (field.required) wrap.setAttribute("aria-required", "true");
     const rows = (Array.isArray(ownerDraft[field.key]) ? ownerDraft[field.key] : []) as Values[];
+    // Older persisted rows may predate ids; establish identity before resolving
+    // a value-based reference so the same row is tracked through its edit.
+    for (const row of rows) {
+      if (isRecord(row) && typeof row.__id !== "string") row.__id = newRowId();
+    }
     const itemFields = field.itemFields ?? [];
     const rerender = () => render();
     const titleField = itemFields.find((f) => f.type === "text");
     const metaField = itemFields.find((f) => f.type === "select");
-    const defaultRowId = defaultRef
+    // Resolve the referenced row once, before any edit. The stable id remains
+    // valid while input/change events update the row's referenced column.
+    const referencedRowIdBeforeEdit = defaultRef
       ? rows.find((r) => isRecord(r) && r[defaultRef.itemKey] === ownerDraft[defaultRef.selectKey] && r[defaultRef.itemKey] !== "")?.__id
       : undefined;
+    const referenceError = defaultRef ? errorAt(schema.id, defaultRef.selectKey) : undefined;
+    const referenceErrorId = `ext-${domIdPart(schema.id)}-${domIdPart(defaultRef?.selectKey ?? field.key)}-ref-err`;
 
     rows.forEach((row, i) => {
       if (!isRecord(row)) return;
-      if (typeof row.__id !== "string") row.__id = newRowId();
       const rid = row.__id as string;
       const open = openRows.has(rid);
       const hasError = itemFields.some((f) => errorAt(schema.id, `${field.key}[${i}].${f.key}`));
       const isDefault = Boolean(defaultRef) && ownerDraft[defaultRef!.selectKey] === row[defaultRef!.itemKey] && row[defaultRef!.itemKey] !== "";
       const rowEl = el("div", { class: `extAccRow${open ? " open" : ""}${hasError ? " hasError" : ""}` });
 
-      const head = el("div", { class: "extAccHead" });
-      head.setAttribute("role", "button");
+      const head = el("button", { type: "button", class: "extAccHead" });
+      // Preserve the former div header's layout against the app-wide button
+      // chrome while gaining native keyboard activation and focusability.
+      Object.assign(head.style, {
+        width: "100%",
+        height: "auto",
+        minHeight: "0",
+        border: "0",
+        borderRadius: "0",
+        background: "transparent",
+        color: "inherit",
+        font: "inherit",
+        textAlign: "left",
+      });
       head.setAttribute("aria-expanded", String(open));
       if (defaultRef) {
-        const star = el("button", { type: "button", class: `extAccStar${isDefault ? " on" : ""}`, title: isDefault ? "Default category" : "Make default" }, [isDefault ? "★" : "☆"]);
+        const star = el("button", { type: "button", class: `extAccStar${isDefault ? " on" : ""}`, title: isDefault ? `Default ${defaultRef.label}` : `Make default ${defaultRef.label}` }, [isDefault ? "★" : "☆"]);
         star.setAttribute("aria-pressed", String(isDefault));
+        if (defaultRef.required) star.setAttribute("aria-required", "true");
+        if (referenceError) {
+          star.setAttribute("aria-invalid", "true");
+          addAriaDescription(star, referenceErrorId);
+        }
         star.addEventListener("click", (e) => { e.stopPropagation(); ownerDraft[defaultRef.selectKey] = row[defaultRef.itemKey]; rerender(); });
         head.append(star);
       }
@@ -231,22 +295,34 @@ export function createExtensionSettings(options: {
       if (open) {
         const body = el("div", { class: "extAccBody" });
         for (const item of itemFields) {
-          const ctrl = scalarControl(schema.id, item, row, ownerDraft, rerender);
-          // rename-follows-default: if this row is the default, keep the ref in sync live.
-          if (defaultRef && item.key === defaultRef.itemKey && rid === defaultRowId) {
-            ctrl.addEventListener("input", () => { ownerDraft[defaultRef.selectKey] = row[item.key]; });
-          }
+          const followsReference = Boolean(defaultRef)
+            && item.key === defaultRef!.itemKey
+            && rid === referencedRowIdBeforeEdit;
+          const ctrl = scalarControl(
+            schema.id,
+            item,
+            row,
+            ownerDraft,
+            rerender,
+            followsReference ? (next) => { ownerDraft[defaultRef!.selectKey] = next; } : undefined,
+          );
           body.append(fieldRow(item.label, ctrl, item.description, errorAt(schema.id, `${field.key}[${i}].${item.key}`)));
         }
         const actions = el("div", { class: "extAccRowActions" });
         if (defaultRef) {
           const mk = el("button", { type: "button", class: "extSettingsLink", disabled: isDefault }, [isDefault ? "★ Default" : "☆ Make default"]);
+          if (defaultRef.required) mk.setAttribute("aria-required", "true");
+          if (referenceError) {
+            mk.setAttribute("aria-invalid", "true");
+            addAriaDescription(mk, referenceErrorId);
+          }
           mk.addEventListener("click", () => { ownerDraft[defaultRef.selectKey] = row[defaultRef.itemKey]; rerender(); });
           actions.append(mk);
         }
         const remove = el("button", { type: "button", class: "extSettingsLink danger" }, ["Delete"]);
         remove.addEventListener("click", () => {
-          if (defaultRef && ownerDraft[defaultRef.selectKey] === row[defaultRef.itemKey]) ownerDraft[defaultRef.selectKey] = "";
+          // Keep a deleted row's reference intact. Validation reports the
+          // dangling value on the referencing field for the user to resolve.
           rows.splice(i, 1); openRows.delete(rid); rerender();
         });
         actions.append(remove);
@@ -259,7 +335,18 @@ export function createExtensionSettings(options: {
     const listErr = errorAt(schema.id, field.key);
     if (listErr) {
       const e = el("span", { class: "extSettingsError" }, [listErr]);
+      e.id = `ext-${domIdPart(schema.id)}-${domIdPart(field.key)}-list-err`;
+      e.setAttribute("role", "alert");
+      wrap.setAttribute("aria-invalid", "true");
+      addAriaDescription(wrap, e.id);
+      wrap.append(e);
+    }
+    if (referenceError) {
+      const e = el("span", { class: "extSettingsError" }, [referenceError]);
+      e.id = referenceErrorId;
       e.setAttribute("role", "alert");
+      wrap.setAttribute("aria-invalid", "true");
+      addAriaDescription(wrap, e.id);
       wrap.append(e);
     }
 
@@ -277,9 +364,24 @@ export function createExtensionSettings(options: {
     return wrap;
   }
 
+  function applyResponseSettings(data: unknown): boolean {
+    if (!isRecord(data) || !isRecord(data.settings)) return false;
+    state.settings = data.settings as AppState["settings"];
+    return true;
+  }
+
+  async function reloadSettingsFromServer(): Promise<void> {
+    const res = await fetch("/api/settings", { headers: api.headers() });
+    const data: unknown = await res.json().catch(() => ({}));
+    if (!res.ok || !applyResponseSettings(data)) {
+      const message = isRecord(data) && typeof data.error === "string" ? data.error : `HTTP ${res.status}`;
+      throw new Error(message);
+    }
+  }
+
   async function save(schema: WebSettingsSchema) {
     const draft = ensureDraft(schema);
-    const expectedRevision = storedFor(schema.id)?.revision;
+    const expectedRevision = storedFor(schema.id)?.revision ?? 0;
     setStatus("Saving…");
     try {
       const res = await fetch(`/api/settings/extensions/${encodeURIComponent(schema.id)}`, {
@@ -296,14 +398,26 @@ export function createExtensionSettings(options: {
       }
       if (res.status === 409) {
         errors.delete(schema.id);
-        drafts.delete(schema.id); // re-sync from server on next render
+        drafts.delete(schema.id);
+        try {
+          // Current conflict responses only carry the latest revision. Prefer
+          // settings on the response when available, otherwise fetch them.
+          if (!applyResponseSettings(data)) await reloadSettingsFromServer();
+        } finally {
+          render();
+        }
         setStatus("Changed elsewhere — reloaded latest", true);
         return;
       }
       if (!res.ok || data.ok === false) throw new Error(data.error || `HTTP ${res.status}`);
       errors.delete(schema.id);
+      if (applyResponseSettings(data)) {
+        // Recreate from the canonical server response (trimmed/coerced values
+        // and the new revision) rather than waiting for a broadcast.
+        drafts.delete(schema.id);
+        render();
+      }
       setStatus("Saved");
-      // state.settings gets refreshed via the settings_updated broadcast → applySettings
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
       setStatus(msg, true);
@@ -314,11 +428,29 @@ export function createExtensionSettings(options: {
   async function reset(schema: WebSettingsSchema) {
     setStatus("Resetting…");
     try {
-      const res = await fetch(`/api/settings/extensions/${encodeURIComponent(schema.id)}/reset`, { method: "POST", headers: api.headers() });
+      const expectedRevision = storedFor(schema.id)?.revision ?? 0;
+      const res = await fetch(`/api/settings/extensions/${encodeURIComponent(schema.id)}/reset`, {
+        method: "POST",
+        headers: api.headers(),
+        body: JSON.stringify({ expectedRevision }),
+      });
       const data = await res.json().catch(() => ({}));
+      if (res.status === 409) {
+        errors.delete(schema.id);
+        drafts.delete(schema.id);
+        try {
+          if (!applyResponseSettings(data)) await reloadSettingsFromServer();
+        } finally {
+          render();
+        }
+        setStatus("Changed elsewhere — reloaded latest", true);
+        return;
+      }
       if (!res.ok || data.ok === false) throw new Error(data.error || `HTTP ${res.status}`);
+      if (!applyResponseSettings(data)) await reloadSettingsFromServer();
       drafts.delete(schema.id);
       errors.delete(schema.id);
+      render();
       setStatus("Reset");
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
@@ -338,7 +470,10 @@ export function createExtensionSettings(options: {
     for (const f of schema.fields) {
       if (f.type === "select" && f.optionsFromField) {
         const [lk, ik] = f.optionsFromField.split(".");
-        if (lk && ik) { defaultRefByList.set(lk, { selectKey: f.key, itemKey: ik }); skipSelectKeys.add(f.key); }
+        if (lk && ik) {
+          defaultRefByList.set(lk, { selectKey: f.key, itemKey: ik, label: f.label, required: f.required });
+          skipSelectKeys.add(f.key);
+        }
       }
     }
 
diff --git a/src/styles/sessions.css b/src/styles/sessions.css
index 1f8ef71..b34e3df 100644
--- a/src/styles/sessions.css
+++ b/src/styles/sessions.css
@@ -634,30 +634,6 @@
   font-weight: 700;
   padding: 6px 8px 4px;
 }
-.sessionTimeFilterControls {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) minmax(0, 1.35fr);
-  gap: 4px;
-  padding: 0 4px 4px;
-}
-.sessionTimeFilterSelect {
-  box-sizing: border-box;
-  width: 100%;
-  min-width: 0;
-  height: 30px;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  background: var(--panel-2);
-  color: var(--text);
-  font: inherit;
-  font-size: 12px;
-  padding: 0 6px;
-}
-.sessionTimeFilterSelect:hover,
-.sessionTimeFilterSelect:focus-visible {
-  border-color: var(--accent);
-  outline: none;
-}
 .sessionColorFilterMenuItem {
   display: flex;
   align-items: center;
diff --git a/src/tools/toolCards.ts b/src/tools/toolCards.ts
index 53c9935..c865b8f 100644
--- a/src/tools/toolCards.ts
+++ b/src/tools/toolCards.ts
@@ -1,6 +1,7 @@
 import hljs from "highlight.js/lib/common";
 import { renderEditDiff } from "../components/editDiff.js";
 import { textFromRawContent } from "../messages/content.js";
+import { sessionRefChipClass, sessionRefChipText, sessionRefHref, sessionRefsFromDetails } from "../app/sessionRefs.js";
 import { playToolCardEntry, playToolCardStateTransition } from "../messages/entryAnimation.js";
 import type { ApiHeaders } from "../app/api.js";
 
@@ -94,53 +95,27 @@ function addToolArgsDetails(card: HTMLDivElement, args?: Record<string, unknown>
   card.append(details);
 }
 
-function toolResultSessionRefs(toolName: string, result: unknown): Array<{ sessionId: string; name?: string; status?: string }> {
-  const refs: Array<{ sessionId: string; name?: string; status?: string }> = [];
-  const seen = new Set<string>();
-  const push = (sessionId?: string, name?: string, status?: string) => {
-    const id = typeof sessionId === "string" ? sessionId.trim() : "";
-    if (!id || seen.has(id)) return;
-    seen.add(id);
-    refs.push({ sessionId: id, name: name?.trim() || undefined, status });
-  };
-  const rec = result && typeof result === "object" ? result as Record<string, unknown> : {};
-  const details = (rec.details ?? (rec.raw as Record<string, unknown> | undefined)?.details) as unknown;
-  if (details && typeof details === "object") {
-    const d = details as Record<string, unknown>;
-    const items = Array.isArray(d.workers) ? d.workers : Array.isArray(d.sessions) ? d.sessions : [d];
-    for (const item of items) {
-      if (item && typeof item === "object") {
-        const r = item as Record<string, unknown>;
-        push(typeof r.sessionId === "string" ? r.sessionId : undefined,
-          typeof r.name === "string" ? r.name : undefined,
-          typeof r.status === "string" ? r.status : undefined);
-      }
-    }
-  }
-  // Fallback for the spawn tool: parse the session id from the result text
-  // (covers the live-stream path if details didn't ride along).
-  if (refs.length === 0 && toolName === "sessions_spawn") {
-    const text = textFromToolResult(result);
-    const re = /session\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi;
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(text))) push(m[1]);
-  }
-  return refs;
-}
-
-function addToolSessionChips(card: HTMLDivElement, toolName: string, result: unknown) {
-  if (toolName !== "sessions_spawn") return; // only the spawn card links to its worker
-  const refs = toolResultSessionRefs(toolName, result);
-  if (!refs.length) return;
+/**
+ * Render links to sessions that a tool result explicitly references via
+ * structured `details`. Generic: no tool name is special-cased and no result
+ * text is parsed. Safe to call repeatedly for the same card.
+ */
+function addToolSessionChips(card: HTMLDivElement, result: unknown) {
+  const record = result && typeof result === "object" ? result as Record<string, unknown> : {};
+  const details = record.details ?? (record.raw as Record<string, unknown> | undefined)?.details;
+  const refs = sessionRefsFromDetails(details);
   const header = card.querySelector<HTMLElement>(".toolCardHeader");
   if (!header) return;
+  // Reconcile rather than append: the live path updates a card that may already
+  // carry chips from an earlier partial result.
+  for (const existing of header.querySelectorAll(".customCardSessionChip")) existing.remove();
+  if (!refs.length) return;
   const toggle = header.querySelector(".toolCardExpandToggle");
   for (const ref of refs) {
     const chip = document.createElement("a");
-    chip.className = `customCardSessionChip${ref.status === "error" ? " status-error" : ref.status === "aborted" ? " status-aborted" : ""}`;
-    chip.href = `/?sessionId=${encodeURIComponent(ref.sessionId)}`;
-    const statusIcon = ref.status === "error" ? "⚠" : ref.status === "aborted" ? "⏹" : "↗";
-    chip.textContent = `${statusIcon} ${ref.name || ref.sessionId.slice(-8)}`;
+    chip.className = sessionRefChipClass(ref);
+    chip.href = sessionRefHref(ref);
+    chip.textContent = sessionRefChipText(ref);
     chip.title = `Open session ${ref.sessionId}`;
     header.insertBefore(chip, toggle || null);
   }
@@ -498,7 +473,7 @@ export function createToolCards(messagesEl: HTMLDivElement, scrollToBottom: () =
     }
     addToolImagePreviews(card, result, apiHeaders);
     playToolCardStateTransition(card);
-    addToolSessionChips(card, toolName, result);
+    addToolSessionChips(card, result);
 
     scrollToBottom();
   }
@@ -512,7 +487,7 @@ export function createToolCards(messagesEl: HTMLDivElement, scrollToBottom: () =
     if (toolName === "edit" && args) renderEditDiff(card, args, result);
     else if (resultStr) addToolResultBody(card, resultStr);
     addToolImagePreviews(card, result, apiHeaders);
-    addToolSessionChips(card, toolName, result);
+    addToolSessionChips(card, result);
     messagesEl.append(card);
   }
 
diff --git a/tests/extension-settings.test.ts b/tests/extension-settings.test.ts
index 0d3f9bf..43cc0c5 100644
--- a/tests/extension-settings.test.ts
+++ b/tests/extension-settings.test.ts
@@ -51,7 +51,7 @@ describe("extension settings descriptors", () => {
 });
 
 describe("extension settings validation", () => {
-  it("accepts a valid configuration and assigns stable row ids", () => {
+  it("accepts a valid reference with zero errors and assigns stable row ids", () => {
     const first = validateSettingsValues(schema, withCategories([{ name: "Fast" }, { name: "Smart", model: "anthropic:smart-1" }], "Fast"), { modelOptions: models });
     expect(first.errors).toEqual([]);
 
@@ -73,14 +73,39 @@ describe("extension settings validation", () => {
     expect(result.errors.map((error) => error.path)).toContain("defaultCategory");
   });
 
-  it("keeps the default valid when the referenced category is renamed alongside it", () => {
-    const result = validateSettingsValues(schema, withCategories([{ name: "Quick" }], "Quick"), { modelOptions: models });
-    expect(result.errors).toEqual([]);
+  it("reports a dangling reference when the referenced row is renamed without updating it", () => {
+    const initial = validateSettingsValues(schema, withCategories([{ name: "Fast" }], "Fast"), { modelOptions: models });
+    expect(initial.errors).toEqual([]);
+
+    const renamed = structuredClone(initial.values);
+    (renamed.categories as Array<Record<string, unknown>>)[0].name = "Quick";
+    const result = validateSettingsValues(schema, renamed, { modelOptions: models });
+
+    expect(result.values.defaultCategory).toBe("Fast");
+    expect(result.errors).toContainEqual({
+      path: "defaultCategory",
+      message: "Default references an unavailable value",
+    });
+  });
+
+  it("reports a dangling reference when the referenced row is deleted without clearing it", () => {
+    const initial = validateSettingsValues(schema, withCategories([{ name: "Fast" }, { name: "Smart" }], "Fast"), { modelOptions: models });
+    expect(initial.errors).toEqual([]);
+
+    const deleted = structuredClone(initial.values);
+    (deleted.categories as Array<Record<string, unknown>>).splice(0, 1);
+    const result = validateSettingsValues(schema, deleted, { modelOptions: models });
+
+    expect(result.values.defaultCategory).toBe("Fast");
+    expect(result.errors).toContainEqual({
+      path: "defaultCategory",
+      message: "Default references an unavailable value",
+    });
   });
 
-  it("rejects duplicate names case-insensitively", () => {
+  it("rejects referenced-column values that differ only in case", () => {
     const result = validateSettingsValues(schema, withCategories([{ name: "Fast" }, { name: "fast" }], "Fast"), { modelOptions: models });
-    expect(result.errors.map((error) => error.path)).toContain("categories[1].name");
+    expect(result.errors).toContainEqual({ path: "categories[1].name", message: "Name must be unique" });
   });
 
   it("requires non-empty required text and honours item bounds", () => {
diff --git a/tests/session-orchestrator.test.ts b/tests/session-orchestrator.test.ts
index 44cfacd..ad32c3a 100644
--- a/tests/session-orchestrator.test.ts
+++ b/tests/session-orchestrator.test.ts
@@ -72,13 +72,18 @@ let tools: Map<string, any>;
 let handlers: Map<string, (event: any, ctx: any) => any>;
 let realFetch: typeof globalThis.fetch;
 
-function makeExtension() {
+function makeExtension(options: { wakeupFails?: boolean } = {}) {
   tools = new Map();
   handlers = new Map();
   const pi: any = {
     registerTool: (tool: any) => tools.set(tool.name, tool),
     on: (event: string, handler: any) => handlers.set(event, handler),
-    sendMessage: vi.fn(),
+    sendMessage: options.wakeupFails
+      ? vi.fn(async () => { throw new Error("wakeup unavailable"); })
+      : vi.fn(),
+    sendUserMessage: options.wakeupFails
+      ? vi.fn(() => { throw new Error("user-message unavailable"); })
+      : vi.fn(),
     appendEntry: vi.fn(),
   };
   sessionOrchestrator(pi);
@@ -117,7 +122,14 @@ function makeCtx(options: {
 }
 
 /** Route pi-web API calls; `models` is the worker session's registry. */
-function stubFetch(options: { models?: any[]; parentModelId?: string; newChatFails?: boolean } = {}) {
+function stubFetch(options: {
+  models?: any[];
+  parentModelId?: string;
+  newChatFails?: boolean;
+  promptFails?: boolean;
+  wakeupPromptFails?: boolean;
+  deleteFails?: boolean;
+} = {}) {
   let created = 0;
   globalThis.fetch = (async (url: any, init: any = {}) => {
     const method = String(init.method || "GET");
@@ -135,6 +147,10 @@ function stubFetch(options: { models?: any[]; parentModelId?: string; newChatFai
       payload = { ok: true, model: { provider: "anthropic", id: options.parentModelId ?? "fast-1" } };
     } else if (path.startsWith("/api/messages")) {
       payload = { ok: true, messages: [] };
+    } else if (path === "/api/prompt" && (options.promptFails || (options.wakeupPromptFails && body?.sessionId === "parent-1"))) {
+      payload = { ok: false, error: "prompt failed" };
+    } else if (path === "/api/sessions/delete" && options.deleteFails) {
+      payload = { ok: false, error: "delete failed" };
     }
     return { ok: payload.ok !== false, status: payload.ok === false ? 500 : 200, json: async () => payload } as any;
   }) as any;
@@ -173,6 +189,7 @@ afterEach(() => {
   // Clears the background poll timer started by a successful spawn.
   handlers.get("session_shutdown")?.({}, makeCtx());
   globalThis.fetch = realFetch;
+  vi.useRealTimers();
   vi.restoreAllMocks();
 });
 
@@ -228,6 +245,28 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(pathsFor("POST")).not.toContain("/api/sessions/delete");
   });
 
+  it("returns only the category name after a successful spawn and keeps the model mapping private", async () => {
+    const ctx = makeCtx({ categories: [FAST, SMART], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "builder", task: "implement it", category: "Smart" });
+
+    const visibleResult = `${resultText(result)}\n${JSON.stringify(result.details)}`;
+    expect(result.details.sessions).toEqual([{ sessionId: "worker-1", name: "builder" }]);
+    expect(visibleResult).toContain("Smart");
+    expect(visibleResult).not.toContain("anthropic");
+    expect(visibleResult).not.toContain("smart-1");
+  });
+
+  it("reports status by category without exposing the concrete model id", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await spawn(ctx, { name: "scout", task: "look around", category: "Fast" });
+
+    const result = await tools.get("sessions_status").execute("status-1", {});
+    const visibleResult = `${resultText(result)}\n${JSON.stringify(result.details)}`;
+    expect(visibleResult).toContain('category "Fast"');
+    expect(visibleResult).not.toContain("anthropic");
+    expect(visibleResult).not.toContain("fast-1");
+  });
+
   it("uses the configured default when category is omitted", async () => {
     const ctx = makeCtx({ categories: [FAST, SMART], defaultCategory: "Smart" });
     const result = await spawn(ctx, { name: "scout", task: "look around" });
@@ -263,6 +302,23 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(calls.find((call) => call.path === "/api/sessions/delete")?.body).toMatchObject({ sessionId: "worker-1" });
     expect(pathsFor("POST")).not.toContain("/api/prompt"); // no LLM work happened
     expect(resultText(result)).toMatch(/deleted/i);
+    const visibleResult = `${resultText(result)}\n${JSON.stringify(result.details)}`;
+    expect(visibleResult).toContain("Fast");
+    expect(visibleResult).not.toContain("anthropic");
+    expect(visibleResult).not.toContain("fast-1");
+    expect(visibleResult).not.toContain("something-else");
+  });
+
+  it("reports that a session may remain when cleanup after resolution failure also fails", async () => {
+    stubFetch({ models: [], deleteFails: true });
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Fast" });
+
+    expect(result.isError).toBe(true);
+    expect(resultText(result)).toMatch(/may remain/i);
+    expect(resultText(result)).toMatch(/please remove it/i);
+    expect(resultText(result)).not.toMatch(/no orphan/i);
+    expect(result.details.cleanedUp).toBe(false);
   });
 
   it("reports a region-prefix substitution instead of silently swapping models", async () => {
@@ -332,6 +388,19 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(pathsFor("POST")).not.toContain("/api/prompt");
   });
 
+  it("deletes the worker and leaves it untracked when task dispatch fails", async () => {
+    stubFetch({ promptFails: true });
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Fast" });
+
+    expect(result.isError).toBe(true);
+    expect(resultText(result)).toMatch(/failed to dispatch/i);
+    expect(calls.filter((call) => call.path === "/api/prompt")).toHaveLength(1);
+    expect(calls.find((call) => call.path === "/api/sessions/delete")?.body).toEqual({ sessionId: "worker-1" });
+    const status = await tools.get("sessions_status").execute("status-1", {});
+    expect(resultText(status)).toMatch(/no tracked workers/i);
+  });
+
   it("caps the number of concurrently tracked workers", async () => {
     const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
     for (let i = 0; i < 4; i += 1) {
@@ -343,3 +412,59 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(resultText(overflow)).toMatch(/cap/i);
   });
 });
+
+describe("watcher lifecycle and wakeup retries", () => {
+  it("does not re-arm polling when a pending ledger re-arm finishes after shutdown", async () => {
+    vi.useFakeTimers();
+    let resolveState!: (response: any) => void;
+    const pendingState = new Promise<any>((resolve) => { resolveState = resolve; });
+    globalThis.fetch = (async (url: any, init: any = {}) => {
+      const method = String(init.method || "GET");
+      const path = String(url).replace(/^https?:\/\/[^/]+/, "");
+      calls.push({ method, path, body: init.body ? JSON.parse(init.body) : undefined });
+      if (path.startsWith("/api/state?sessionId=ledger-worker")) return pendingState;
+      return { ok: true, status: 200, json: async () => ({ ok: true }) } as any;
+    }) as any;
+
+    const ctx = makeCtx();
+    ctx.sessionManager.getBranch = () => [{
+      type: "custom",
+      customType: "orchestrator-watch",
+      data: { childId: "ledger-worker", name: "ledger worker", categoryName: "Fast" },
+    }];
+    await handlers.get("session_start")?.({}, ctx);
+    expect(calls.filter((call) => call.path.includes("ledger-worker"))).toHaveLength(1);
+
+    handlers.get("session_shutdown")?.({}, ctx);
+    resolveState({
+      ok: true,
+      status: 200,
+      json: async () => ({ ok: true, runtime: { isRunning: true, pendingMessageCount: 0 } }),
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(calls.filter((call) => call.path.includes("ledger-worker"))).toHaveLength(1);
+  });
+
+  it("keeps a completed worker watched and retries after every wakeup delivery path fails", async () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    stubFetch({ wakeupPromptFails: true });
+    const pi = makeExtension({ wakeupFails: true });
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await activate(ctx);
+    await spawn(ctx, { name: "scout", task: "look around", category: "Fast" });
+
+    await vi.advanceTimersByTimeAsync(10_000); // four idle polls settle a fast worker
+    expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+    expect(calls.filter((call) => call.path === "/api/state?sessionId=worker-1")).toHaveLength(4);
+
+    await vi.advanceTimersByTimeAsync(2_500);
+    expect(pi.sendMessage).toHaveBeenCalledTimes(2);
+    expect(calls.filter((call) => call.path === "/api/state?sessionId=worker-1")).toHaveLength(5);
+    const status = await tools.get("sessions_status").execute("status-1", {});
+    expect(resultText(status)).toContain("worker-1");
+  });
+});
diff --git a/tests/session-refs.test.ts b/tests/session-refs.test.ts
new file mode 100644
index 0000000..fb34b9a
--- /dev/null
+++ b/tests/session-refs.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { maxSessionRefLabel, maxSessionRefs, sessionRefChipText, sessionRefsFromDetails } from "../src/app/sessionRefs.js";
+
+describe("session references from extension details", () => {
+  it("reads explicit reference lists under any supported key", () => {
+    expect(sessionRefsFromDetails({ sessions: [{ sessionId: "a-1", name: "one" }] })).toEqual([
+      { sessionId: "a-1", name: "one", status: undefined },
+    ]);
+    expect(sessionRefsFromDetails({ workers: [{ sessionId: "b-2" }] })[0].sessionId).toBe("b-2");
+    expect(sessionRefsFromDetails({ sessionRefs: [{ sessionId: "c-3" }] })[0].sessionId).toBe("c-3");
+  });
+
+  it("ignores a bare sessionId, so incidental metadata does not become a link", () => {
+    // Tools that merely echo the session they acted on must not sprout chips;
+    // linking is opt-in via an explicit list.
+    expect(sessionRefsFromDetails({ sessionId: "a-1", name: "echoed" })).toEqual([]);
+  });
+
+  it("ignores payloads that are absent or not objects", () => {
+    for (const value of [undefined, null, "a-1", 42, [{ sessionId: "a-1" }]]) {
+      expect(sessionRefsFromDetails(value)).toEqual([]);
+    }
+  });
+
+  it("de-duplicates repeated session ids across lists", () => {
+    const refs = sessionRefsFromDetails({
+      sessions: [{ sessionId: "a-1", name: "first" }],
+      workers: [{ sessionId: "a-1", name: "again" }, { sessionId: "b-2" }],
+    });
+    expect(refs.map((ref) => ref.sessionId)).toEqual(["a-1", "b-2"]);
+    expect(refs[0].name).toBe("first");
+  });
+
+  it("caps how many references are rendered", () => {
+    const many = Array.from({ length: maxSessionRefs + 5 }, (_, i) => ({ sessionId: `s-${i}` }));
+    expect(sessionRefsFromDetails({ sessions: many })).toHaveLength(maxSessionRefs);
+  });
+
+  it("rejects implausible session ids instead of trusting extension input", () => {
+    const refs = sessionRefsFromDetails({
+      sessions: [
+        { sessionId: "" },
+        { sessionId: "   " },
+        { sessionId: "has space" },
+        { sessionId: "javascript:alert(1)" },
+        { sessionId: "../../etc/passwd" },
+        { sessionId: "x".repeat(200) },
+        { sessionId: "ok-1" },
+      ],
+    });
+    expect(refs.map((ref) => ref.sessionId)).toEqual(["ok-1"]);
+  });
+
+  it("truncates and sanitizes labels", () => {
+    const refs = sessionRefsFromDetails({
+      sessions: [{ sessionId: "a-1", name: `${"n".repeat(maxSessionRefLabel + 40)}` }, { sessionId: "b-2", name: "line\u0000break\u001F" }],
+    });
+    expect(refs[0].name).toHaveLength(maxSessionRefLabel);
+    expect(refs[1].name).toBe("linebreak");
+  });
+
+  it("labels a chip by name, falling back to a short id, with a status glyph", () => {
+    expect(sessionRefChipText({ sessionId: "abcdefghij", name: "scout" })).toBe("↗ scout");
+    expect(sessionRefChipText({ sessionId: "abcdefghij" })).toBe("↗ cdefghij");
+    expect(sessionRefChipText({ sessionId: "a-1", name: "x", status: "error" })).toBe("⚠ x");
+    expect(sessionRefChipText({ sessionId: "a-1", name: "x", status: "aborted" })).toBe("⏹ x");
+  });
+});
diff --git a/tests/settings.test.ts b/tests/settings.test.ts
index 155b266..80d3197 100644
--- a/tests/settings.test.ts
+++ b/tests/settings.test.ts
@@ -78,7 +78,7 @@ describe("extension-contributed settings", () => {
   it("preserves extension values when unrelated settings are patched", async () => {
     // Regression: normalizeSettings rebuilds known fields only, so an owner's
     // values must be carried through verbatim even while its extension is absent.
-    const withValues = applyExtensionValues(normalizeSettings({}), OWNER, { tier: "fast" }, { schemaVersion: 3 });
+    const withValues = applyExtensionValues(normalizeSettings({}), OWNER, { tier: "fast" }, { schemaVersion: 3, expectedRevision: 0 });
     const patched = applySettingsPatch(withValues, { appearance: { density: "compact" } });
 
     expect(patched.appearance.density).toBe("compact");
@@ -97,26 +97,34 @@ describe("extension-contributed settings", () => {
     expect(normalizeSettings({}).extensions).toBeUndefined();
   });
 
-  it("bumps revision and rejects stale writes", () => {
-    const first = applyExtensionValues(normalizeSettings({}), OWNER, { n: 1 });
+  it("requires revision zero for a guarded first write and rejects stale revisions", () => {
+    const first = applyExtensionValues(normalizeSettings({}), OWNER, { n: 1 }, { expectedRevision: 0 });
     expect(first.extensions?.[OWNER]?.revision).toBe(1);
 
+    expect(() => applyExtensionValues(normalizeSettings({}), OWNER, { n: 1 }, { expectedRevision: 1 }))
+      .toThrow(ExtensionRevisionConflictError);
+
     const second = applyExtensionValues(first, OWNER, { n: 2 }, { expectedRevision: 1 });
     expect(second.extensions?.[OWNER]?.revision).toBe(2);
 
     expect(() => applyExtensionValues(second, OWNER, { n: 3 }, { expectedRevision: 1 }))
       .toThrow(ExtensionRevisionConflictError);
+    expect(() => resetExtensionValues(second, OWNER, 1))
+      .toThrow(ExtensionRevisionConflictError);
+    expect(() => resetExtensionValues(second, OWNER, undefined as unknown as number))
+      .toThrow(ExtensionRevisionConflictError);
   });
 
   it("enforces bounds and namespaced owner ids", () => {
-    expect(() => applyExtensionValues(normalizeSettings({}), OWNER, { blob: "x".repeat(70 * 1024) }))
+    expect(() => applyExtensionValues(normalizeSettings({}), OWNER, { blob: "x".repeat(70 * 1024) }, { expectedRevision: 0 }))
       .toThrow(ExtensionSettingsBoundsError);
-    expect(() => applyExtensionValues(normalizeSettings({}), "nodots", { a: 1 }))
+    expect(() => applyExtensionValues(normalizeSettings({}), "nodots", { a: 1 }, { expectedRevision: 0 }))
       .toThrow(ExtensionSettingsBoundsError);
   });
 
   it("keeps the migration backup outside user values across a round trip", () => {
     const withBackup = applyExtensionValues(normalizeSettings({}), OWNER, { fresh: true }, {
+      expectedRevision: 0,
       backup: { schemaVersion: 1, values: { legacy: true } },
     });
     const roundTripped = normalizeSettings(JSON.parse(JSON.stringify(withBackup)));
@@ -126,15 +134,79 @@ describe("extension-contributed settings", () => {
   });
 
   it("resets an owner without touching the rest of the settings", () => {
-    const withValues = applyExtensionValues(normalizeSettings({}), OWNER, { tier: "fast" });
-    const reset = resetExtensionValues(withValues, OWNER);
+    const withValues = applyExtensionValues(normalizeSettings({}), OWNER, { tier: "fast" }, { expectedRevision: 0 });
+    const reset = resetExtensionValues(withValues, OWNER, 1);
     expect(reset.extensions).toBeUndefined();
     expect(reset.appearance.accentColor).toBe(withValues.appearance.accentColor);
   });
 
+  it("allows exactly one of two concurrent writes with the same expected revision", async () => {
+    const store = createSettingsStore(await tempFile());
+    await store.patchExtension(OWNER, { n: 1 }, { expectedRevision: 0 });
+
+    const results = await Promise.allSettled([
+      store.patchExtension(OWNER, { n: 2 }, { expectedRevision: 1 }),
+      store.patchExtension(OWNER, { n: 3 }, { expectedRevision: 1 }),
+    ]);
+
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    const rejected = results.find((result) => result.status === "rejected");
+    expect(rejected).toMatchObject({ status: "rejected", reason: expect.any(ExtensionRevisionConflictError) });
+    expect((await store.read()).extensions?.[OWNER]?.revision).toBe(2);
+  });
+
+  it("preserves both effects when a generic patch races an extension patch", async () => {
+    const store = createSettingsStore(await tempFile());
+
+    await Promise.all([
+      store.patch({ composer: { expanded: true } }),
+      store.patchExtension(OWNER, { tier: "fast" }, { schemaVersion: 1, expectedRevision: 0 }),
+    ]);
+
+    const stored = await store.read();
+    expect(stored.composer.expanded).toBe(true);
+    expect(stored.extensions?.[OWNER]?.values).toEqual({ tier: "fast" });
+    expect(stored.extensions?.[OWNER]?.revision).toBe(1);
+  });
+
+  it("keeps a coherent parseable record when reset races an extension patch", async () => {
+    const file = await tempFile();
+    const store = createSettingsStore(file);
+    await store.patchExtension(OWNER, { n: 1 }, { schemaVersion: 2, expectedRevision: 0 });
+
+    const results = await Promise.allSettled([
+      store.resetExtension(OWNER, 1),
+      store.patchExtension(OWNER, { n: 2 }, { schemaVersion: 2, expectedRevision: 1 }),
+    ]);
+
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    expect(results.find((result) => result.status === "rejected"))
+      .toMatchObject({ status: "rejected", reason: expect.any(ExtensionRevisionConflictError) });
+    const parsed = JSON.parse(await readFile(file, "utf-8"));
+    const record = parsed.extensions?.[OWNER];
+    expect(record === undefined || (
+      record.schemaVersion === 2 &&
+      record.revision === 2 &&
+      JSON.stringify(record.values) === JSON.stringify({ n: 2 })
+    )).toBe(true);
+  });
+
+  it("lands many rapid writes with gapless revisions and valid JSON", async () => {
+    const file = await tempFile();
+    const store = createSettingsStore(file);
+
+    for (let revision = 0; revision < 25; revision += 1) {
+      const saved = await store.patchExtension(OWNER, { n: revision + 1 }, { expectedRevision: revision });
+      expect(saved.extensions?.[OWNER]?.revision).toBe(revision + 1);
+    }
+
+    const parsed = JSON.parse(await readFile(file, "utf-8"));
+    expect(parsed.extensions[OWNER]).toMatchObject({ revision: 25, values: { n: 25 } });
+  });
+
   it("round-trips owner values through the store on disk", async () => {
     const store = createSettingsStore(await tempFile());
-    await store.patchExtension(OWNER, { tier: "fast" }, { schemaVersion: 1 });
+    await store.patchExtension(OWNER, { tier: "fast" }, { schemaVersion: 1, expectedRevision: 0 });
 
     const reread = await store.read();
     expect(reread.extensions?.[OWNER]?.values).toEqual({ tier: "fast" });
@@ -144,7 +216,7 @@ describe("extension-contributed settings", () => {
     expect(afterUnrelated.composer.queueMode).toBe("followUp");
     expect(afterUnrelated.extensions?.[OWNER]?.values).toEqual({ tier: "fast" });
 
-    await store.resetExtension(OWNER);
+    await store.resetExtension(OWNER, 1);
     expect((await store.read()).extensions?.[OWNER]).toBeUndefined();
   });
 });
diff --git a/tests/web-ui-settings.test.ts b/tests/web-ui-settings.test.ts
new file mode 100644
index 0000000..c693e4d
--- /dev/null
+++ b/tests/web-ui-settings.test.ts
@@ -0,0 +1,217 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createWebUiBridge } from "../server/extensions/webUi.js";
+import { createSettingsStore } from "../server/settings.js";
+import type { PiWebSettingsRegistration } from "../src/extensions.js";
+
+let tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })));
+  tempDirs = [];
+});
+
+async function makeBridge() {
+  const dir = await mkdtemp(join(tmpdir(), "pi-web-webui-"));
+  tempDirs.push(dir);
+  const settingsStore = createSettingsStore(join(dir, "settings.json"));
+  const emitted: unknown[] = [];
+  const bridge = createWebUiBridge({
+    emit: (value) => emitted.push(value),
+    clientCount: () => 1,
+    acquireWorkLease: () => () => undefined,
+    createNewSession: async () => ({}),
+    sessionCwd: () => "/repo",
+    state: () => ({}),
+    settingsStore,
+    modelOptions: () => new Set(["anthropic:fast-1"]),
+  });
+  return { bridge, settingsStore, emitted };
+}
+
+/** A fake pi-web session object; identity is what the registry keys on. */
+function makeSession(sessionId: string) {
+  return { sessionId } as any;
+}
+
+function schemaFor(id: string, extra: Partial<PiWebSettingsRegistration> = {}): PiWebSettingsRegistration {
+  return {
+    id,
+    title: "Demo",
+    schemaVersion: 1,
+    fields: [{ key: "tier", type: "text", label: "Tier" }],
+    ...extra,
+  };
+}
+
+async function register(bridge: any, session: any, schema: PiWebSettingsRegistration) {
+  return bridge.registerSettings(session, schema);
+}
+
+describe("extension settings registry", () => {
+  it("rejects a schema whose owner id is not namespaced", async () => {
+    const { bridge } = await makeBridge();
+    const result = await register(bridge, makeSession("s1"), schemaFor("nodots"));
+    expect(result.registered).toBe(false);
+    expect(result.error).toMatch(/namespaced/);
+    expect(bridge.settingsSchemas()).toHaveLength(0);
+  });
+
+  it("rejects structurally invalid descriptors before reserving the id", async () => {
+    const { bridge } = await makeBridge();
+    const bad = await register(bridge, makeSession("s1"), schemaFor("demo.x", { fields: [{ key: "a", type: "nope" as any, label: "A" }] }));
+    expect(bad.registered).toBe(false);
+    expect(bad.error).toMatch(/unsupported field type/);
+    // The id must remain claimable after a rejected registration.
+    const good = await register(bridge, makeSession("s2"), schemaFor("demo.x"));
+    expect(good.registered).toBe(true);
+  });
+
+  it("migrates once when two sessions register the same schema concurrently", async () => {
+    const { bridge, settingsStore } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+
+    const migrate = vi.fn(async () => ({ tier: "new" }));
+    const schema = schemaFor("demo.x", { schemaVersion: 2, migrate });
+
+    const [a, b] = await Promise.all([
+      register(bridge, makeSession("s1"), schema),
+      register(bridge, makeSession("s2"), schema),
+    ]);
+
+    expect(a.registered).toBe(true);
+    expect(b.registered).toBe(true);
+    expect(migrate).toHaveBeenCalledTimes(1);
+    expect(bridge.settingsSchemas()).toHaveLength(1);
+    expect((await settingsStore.read()).extensions?.["demo.x"]?.values).toEqual({ tier: "new" });
+  });
+
+  it("keeps the first schema when a divergent one claims the same id", async () => {
+    const { bridge } = await makeBridge();
+    await register(bridge, makeSession("s1"), schemaFor("demo.x"));
+    const divergent = await register(bridge, makeSession("s2"), schemaFor("demo.x", {
+      fields: [{ key: "other", type: "toggle", label: "Other" }],
+    }));
+
+    expect(divergent.registered).toBe(false);
+    expect(divergent.error).toMatch(/already registered/);
+    const [descriptor] = bridge.settingsSchemas() as any[];
+    expect(descriptor.fields[0].key).toBe("tier");
+  });
+
+  it("keeps a schema live until the last registrant shuts down", async () => {
+    const { bridge } = await makeBridge();
+    const first = makeSession("s1");
+    const second = makeSession("s2");
+    await register(bridge, first, schemaFor("demo.x"));
+    await register(bridge, second, schemaFor("demo.x"));
+
+    bridge.releaseSessionSettings(first);
+    expect(bridge.settingsSchemas()).toHaveLength(1); // still registered by s2
+
+    bridge.releaseSessionSettings(second);
+    expect(bridge.settingsSchemas()).toHaveLength(0);
+  });
+
+  it("notifies every live registrant with its own callback and session id", async () => {
+    const { bridge } = await makeBridge();
+    const firstChange = vi.fn();
+    const secondChange = vi.fn();
+    await register(bridge, makeSession("s1"), schemaFor("demo.x", { onChange: firstChange }));
+    await register(bridge, makeSession("s2"), schemaFor("demo.x", { onChange: secondChange }));
+
+    bridge.notifySettingsChanged("demo.x", { tier: "fast" });
+
+    expect(firstChange).toHaveBeenCalledWith({ tier: "fast" }, { sessionId: "s1" });
+    expect(secondChange).toHaveBeenCalledWith({ tier: "fast" }, { sessionId: "s2" });
+  });
+
+  it("stops notifying a registrant once its session shuts down", async () => {
+    const { bridge } = await makeBridge();
+    const goneChange = vi.fn();
+    const liveChange = vi.fn();
+    const gone = makeSession("s1");
+    await register(bridge, gone, schemaFor("demo.x", { onChange: goneChange }));
+    await register(bridge, makeSession("s2"), schemaFor("demo.x", { onChange: liveChange }));
+
+    bridge.releaseSessionSettings(gone);
+    bridge.notifySettingsChanged("demo.x", { tier: "fast" });
+
+    expect(goneChange).not.toHaveBeenCalled();
+    expect(liveChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("survives a throwing onChange without skipping other registrants", async () => {
+    const { bridge } = await makeBridge();
+    const good = vi.fn();
+    await register(bridge, makeSession("s1"), schemaFor("demo.x", { onChange: () => { throw new Error("boom"); } }));
+    await register(bridge, makeSession("s2"), schemaFor("demo.x", { onChange: good }));
+
+    expect(() => bridge.notifySettingsChanged("demo.x", { tier: "fast" })).not.toThrow();
+    expect(good).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not register a session that shut down while migration was in flight", async () => {
+    const { bridge, settingsStore } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+
+    const session = makeSession("s1");
+    let releaseMigration: () => void = () => undefined;
+    const gate = new Promise<void>((resolve) => { releaseMigration = resolve; });
+    const schema = schemaFor("demo.x", {
+      schemaVersion: 2,
+      migrate: async () => { await gate; return { tier: "new" }; },
+    });
+
+    const pending = register(bridge, session, schema);
+    bridge.releaseSessionSettings(session); // session dies mid-migration
+    releaseMigration();
+    const result = await pending;
+
+    expect(result.registered).toBe(false);
+    expect(result.error).toMatch(/shut down/);
+    expect(bridge.settingsSchemas()).toHaveLength(0); // no dead-session registration left behind
+  });
+
+  it("falls back to defaults and surfaces an error when migration throws", async () => {
+    const { bridge, settingsStore } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+
+    const result = await register(bridge, makeSession("s1"), schemaFor("demo.x", {
+      schemaVersion: 2,
+      migrate: async () => { throw new Error("bad migration"); },
+    }));
+
+    expect(result.registered).toBe(true);
+    expect(result.usedBackup).toBe(true);
+    expect(result.error).toMatch(/bad migration/);
+
+    const stored = (await settingsStore.read()).extensions?.["demo.x"];
+    expect(stored?.values).toEqual({ tier: "" });                  // defaults
+    expect(stored?.backup?.values).toEqual({ tier: "old" });        // original preserved
+    const [descriptor] = bridge.settingsSchemas() as any[];
+    expect(descriptor.migrationError).toMatch(/bad migration/);     // visible to the UI
+  });
+
+  it("hides a schema from validation and transport until migration settles", async () => {
+    const { bridge, settingsStore } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+
+    let releaseMigration: () => void = () => undefined;
+    const gate = new Promise<void>((resolve) => { releaseMigration = resolve; });
+    const pending = register(bridge, makeSession("s1"), schemaFor("demo.x", {
+      schemaVersion: 2,
+      migrate: async () => { await gate; return { tier: "new" }; },
+    }));
+
+    expect(bridge.settingsSchemas()).toHaveLength(0);
+    expect(bridge.settingsSchemaEntry("demo.x")).toBeUndefined();
+
+    releaseMigration();
+    await pending;
+    expect(bridge.settingsSchemas()).toHaveLength(1);
+    expect(bridge.settingsSchemaEntry("demo.x")).toBeDefined();
+  });
+});

From e59f049841e528fdf619aa5989820d61d3a6bbe3 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 11:00:15 +0000
Subject: [PATCH 05/10] fix: registry corner cases found by second review

Two defects sat in exactly the corner cases the previous fix claimed to handle,
and neither had a test. Both were reproduced empirically by the reviewer.

- A failed migration write permanently poisoned the owner id. The migration
  promise is shared by every concurrent registration of an id, so a rejecting
  store write (ENOSPC, bounds, EACCES) left the reservation in the map with
  ready=false forever: every later registration re-awaited the rejected promise
  and threw, instead of returning the documented { registered: false, error }.
  migrateStoredSettings now resolves with an error instead of rejecting, and
  registration additionally releases its reservation if the shared promise ever
  rejects, so the id stays usable.

- A disposed reserving session could delete the registry entry from under a
  concurrent live registrant. The reserver's post-migration cleanup ran while the
  second registration had not yet attached itself, so the entry was removed and
  the survivor was told registered: true while its schema stayed invisible to
  transport, validation and notification. Registrations now count themselves as
  in-flight before awaiting, cleanup only drops an entry with no registrants AND
  no pending registrations, and a registrant always attaches to the entry the
  registry currently holds.

Regression tests reproduce both sequences and fail against the pre-fix code
(verified by reverting each defence and re-running).

Also from the review:
- Never render an empty custom-message card; upstream drops text-less custom
  messages and the card form should too.
- Restore upstream's colour-filter menu sizing; removing the unrelated
  time-filter feature had left a widened menu class and rule behind.
- Warn instead of silently discarding a stored extension record that exceeds
  bounds on load, so losing user configuration is at least visible.
---
 server/extensions/webUi.ts    | 81 ++++++++++++++++++++++++-----------
 server/settings.ts            | 13 ++++--
 src/messages/messageList.ts   |  3 ++
 src/sessions/sessionDrawer.ts |  2 +-
 src/styles/sessions.css       |  5 ---
 tests/web-ui-settings.test.ts | 71 +++++++++++++++++++++++++++++-
 6 files changed, 140 insertions(+), 35 deletions(-)

diff --git a/server/extensions/webUi.ts b/server/extensions/webUi.ts
index dd29b22..0bb34a1 100644
--- a/server/extensions/webUi.ts
+++ b/server/extensions/webUi.ts
@@ -72,6 +72,8 @@ type RegisteredSettingsSchema = {
   registrants: Map<object, SettingsRegistrant>;
   /** Shared so concurrent first registrations migrate exactly once. */
   migration: Promise<{ migrated: boolean; usedBackup: boolean; error?: string }>;
+  /** Registrations awaiting migration; the entry must not be dropped under them. */
+  pending: number;
   /** Only exposed once migration settled, so nothing validates mid-migration. */
   ready: boolean;
   migrationError?: string;
@@ -129,34 +131,48 @@ function broadcastSettingsSchemas() {
   deps.emit({ type: "web_settings_schemas_changed", webSettingsSchemas: activeSettingsSchemaList() });
 }
 
+/**
+ * Migrate stored values for one owner. NEVER rejects: a store failure resolves
+ * with an `error` instead, because this promise is shared by every concurrent
+ * registration of the id — a rejection would poison the id until restart.
+ */
 async function migrateStoredSettings(
   schema: PiWebSettingsRegistration,
 ): Promise<{ migrated: boolean; usedBackup: boolean; error?: string }> {
-  const settings = await deps.settingsStore.read();
-  const stored = settings.extensions?.[schema.id];
-  if (!stored || stored.schemaVersion >= schema.schemaVersion) {
-    return { migrated: false, usedBackup: false };
-  }
-  const backup = { schemaVersion: stored.schemaVersion, values: stored.values };
-  const defaults = defaultSettingsValues(schema);
-  if (typeof schema.migrate === "function") {
-    try {
-      const migratedValues = await schema.migrate(stored.values, stored.schemaVersion);
-      const { values, errors } = validateSettingsValues(schema, migratedValues, { modelOptions: deps.modelOptions() });
-      if (errors.length) {
-        await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
-        return { migrated: false, usedBackup: true, error: `migration produced invalid values (${errors.length})` };
+  const describe = (error: unknown) => (error instanceof Error ? error.message : String(error));
+  try {
+    const settings = await deps.settingsStore.read();
+    const stored = settings.extensions?.[schema.id];
+    if (!stored || stored.schemaVersion >= schema.schemaVersion) {
+      return { migrated: false, usedBackup: false };
+    }
+    const backup = { schemaVersion: stored.schemaVersion, values: stored.values };
+    const defaults = defaultSettingsValues(schema);
+    if (typeof schema.migrate === "function") {
+      let migratedValues: Record<string, unknown> | undefined;
+      let migrateError: string | undefined;
+      try {
+        migratedValues = await schema.migrate(stored.values, stored.schemaVersion);
+      } catch (error) {
+        migrateError = describe(error);
+      }
+      if (migrateError === undefined && migratedValues !== undefined) {
+        const { values, errors } = validateSettingsValues(schema, migratedValues, { modelOptions: deps.modelOptions() });
+        if (errors.length === 0) {
+          await deps.settingsStore.patchExtension(schema.id, values, { schemaVersion: schema.schemaVersion, backup });
+          return { migrated: true, usedBackup: false };
+        }
+        migrateError = `migration produced invalid values (${errors.length})`;
       }
-      await deps.settingsStore.patchExtension(schema.id, values, { schemaVersion: schema.schemaVersion, backup });
-      return { migrated: true, usedBackup: false };
-    } catch (error) {
       await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
-      return { migrated: false, usedBackup: true, error: error instanceof Error ? error.message : String(error) };
+      return { migrated: false, usedBackup: true, error: migrateError };
     }
+    // No migrate() provided: reset to defaults, keep a one-slot backup.
+    await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
+    return { migrated: false, usedBackup: true };
+  } catch (error) {
+    return { migrated: false, usedBackup: false, error: describe(error) };
   }
-  // No migrate() provided: reset to defaults, keep a one-slot backup.
-  await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
-  return { migrated: false, usedBackup: true };
 }
 
 async function registerSessionSettings(
@@ -187,12 +203,27 @@ async function registerSessionSettings(
       canonicalKey: canonical,
       registrants: new Map(),
       migration: migrateStoredSettings(schema),
+      pending: 0,
       ready: false,
     };
     activeSettingsSchemas.set(id, entry);
   }
 
-  const result = await entry.migration;
+  // Count ourselves as in-flight BEFORE awaiting, so a concurrent registrant
+  // that gets disposed cannot delete this entry out from under us.
+  entry.pending += 1;
+  let result: { migrated: boolean; usedBackup: boolean; error?: string };
+  try {
+    result = await entry.migration;
+  } catch (error) {
+    // migrateStoredSettings is written not to reject; treat a rejection as a
+    // failed registration and release the reservation so the id stays usable.
+    const message = error instanceof Error ? error.message : String(error);
+    entry.pending -= 1;
+    if (entry.registrants.size === 0 && entry.pending === 0) activeSettingsSchemas.delete(id);
+    return { registered: false, migrated: false, usedBackup: false, error: message };
+  }
+  entry.pending -= 1;
   entry.ready = true;
   if (result.error) {
     entry.migrationError = result.error;
@@ -200,12 +231,14 @@ async function registerSessionSettings(
   }
 
   // The session may have shut down while migration was in flight; never
-  // register a dead session (and drop a reservation nobody else claimed).
+  // register a dead session (and drop a reservation nobody else is claiming).
   if (disposedSettingsSessions.has(session)) {
-    if (reserved && entry.registrants.size === 0) activeSettingsSchemas.delete(id);
+    if (entry.registrants.size === 0 && entry.pending === 0) activeSettingsSchemas.delete(id);
     return { registered: false, migrated: result.migrated, usedBackup: result.usedBackup, error: "session shut down during registration" };
   }
 
+  // Always attach to the entry the registry currently holds for this id.
+  if (activeSettingsSchemas.get(id) !== entry) activeSettingsSchemas.set(id, entry);
   entry.registrants.set(session, { schema, sessionId: String(value?.sessionId || "") });
   broadcastSettingsSchemas();
   return { registered: true, migrated: result.migrated, usedBackup: result.usedBackup, error: result.error };
diff --git a/server/settings.ts b/server/settings.ts
index b6ee3cb..3e23d4a 100644
--- a/server/settings.ts
+++ b/server/settings.ts
@@ -152,10 +152,17 @@ function normalizeStoredExtension(value: unknown): StoredExtensionSettings | und
       values: value.backup.values,
     };
   }
-  // Bounds: drop the owner rather than corrupt it.
-  if (Object.keys(record.values).length > extensionSettingsLimits.maxKeysPerOwner) return undefined;
+  // Bounds: drop the owner rather than corrupt it, but say so — silently losing
+  // a user's stored configuration is worse than a noisy log.
+  if (Object.keys(record.values).length > extensionSettingsLimits.maxKeysPerOwner) {
+    console.warn(`pi-web: ignoring stored extension settings with too many keys (max ${extensionSettingsLimits.maxKeysPerOwner})`);
+    return undefined;
+  }
   const bytes = serializedBytes(record);
-  if (bytes === undefined || bytes > extensionSettingsLimits.maxBytesPerOwner) return undefined;
+  if (bytes === undefined || bytes > extensionSettingsLimits.maxBytesPerOwner) {
+    console.warn(`pi-web: ignoring stored extension settings that are not serializable or exceed ${extensionSettingsLimits.maxBytesPerOwner} bytes`);
+    return undefined;
+  }
   return record;
 }
 
diff --git a/src/messages/messageList.ts b/src/messages/messageList.ts
index 59be5a9..483e56d 100644
--- a/src/messages/messageList.ts
+++ b/src/messages/messageList.ts
@@ -692,6 +692,9 @@ export function createMessageList(options: {
     const customType = message.customType || message.raw?.customType || "";
     const details = message.details ?? message.raw?.details;
     const sessionRefs = sessionRefsFromDetails(details);
+    // Nothing to show: upstream drops text-less custom messages, so do not
+    // leave an empty bordered strip in the conversation.
+    if (!text && sessionRefs.length === 0) return undefined;
 
     // Realtime projection can briefly emit a details-only copy of a custom
     // worker event after its complete transcript entry has already rendered.
diff --git a/src/sessions/sessionDrawer.ts b/src/sessions/sessionDrawer.ts
index 6861ee4..5105b48 100644
--- a/src/sessions/sessionDrawer.ts
+++ b/src/sessions/sessionDrawer.ts
@@ -982,7 +982,7 @@ export function createSessions(options: {
     closeOpenSessionColorFilterMenu();
 
     const menu = document.createElement("div");
-    menu.className = "sessionColorFilterMenu sessionFilterMenu";
+    menu.className = "sessionColorFilterMenu";
     menu.setAttribute("role", "menu");
 
     const title = document.createElement("div");
diff --git a/src/styles/sessions.css b/src/styles/sessions.css
index b34e3df..3483553 100644
--- a/src/styles/sessions.css
+++ b/src/styles/sessions.css
@@ -623,11 +623,6 @@
 .sessionColorFilterMenu {
   min-width: 150px;
 }
-.sessionFilterMenu {
-  min-width: 240px;
-  max-height: calc(100vh - 16px);
-  overflow-y: auto;
-}
 .sessionColorFilterTitle {
   color: var(--muted);
   font-size: 11px;
diff --git a/tests/web-ui-settings.test.ts b/tests/web-ui-settings.test.ts
index c693e4d..4c48c61 100644
--- a/tests/web-ui-settings.test.ts
+++ b/tests/web-ui-settings.test.ts
@@ -16,7 +16,20 @@ afterEach(async () => {
 async function makeBridge() {
   const dir = await mkdtemp(join(tmpdir(), "pi-web-webui-"));
   tempDirs.push(dir);
-  const settingsStore = createSettingsStore(join(dir, "settings.json"));
+  const realStore = createSettingsStore(join(dir, "settings.json"));
+  let failWrite = false;
+  /** Arm exactly one extension-write failure (used to simulate a bad disk). */
+  const armWriteFailure = () => { failWrite = true; };
+  const settingsStore = {
+    ...realStore,
+    patchExtension: (...args: Parameters<typeof realStore.patchExtension>) => {
+      if (failWrite) {
+        failWrite = false;
+        return Promise.reject(new Error("disk full"));
+      }
+      return realStore.patchExtension(...args);
+    },
+  } as typeof realStore;
   const emitted: unknown[] = [];
   const bridge = createWebUiBridge({
     emit: (value) => emitted.push(value),
@@ -28,7 +41,7 @@ async function makeBridge() {
     settingsStore,
     modelOptions: () => new Set(["anthropic:fast-1"]),
   });
-  return { bridge, settingsStore, emitted };
+  return { bridge, settingsStore, emitted, armWriteFailure };
 }
 
 /** A fake pi-web session object; identity is what the registry keys on. */
@@ -215,3 +228,57 @@ describe("extension settings registry", () => {
     expect(bridge.settingsSchemaEntry("demo.x")).toBeDefined();
   });
 });
+
+describe("extension settings registry — failure corner cases", () => {
+  it("keeps the owner id usable after a migration write fails", async () => {
+    // Regression: the migration promise is shared by every registration of an
+    // id, so a rejected store write used to poison that id until restart.
+    const { bridge, settingsStore, armWriteFailure } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+    armWriteFailure(); // the migration's write is the one that fails
+
+    const schema = schemaFor("demo.x", { schemaVersion: 2, migrate: async () => ({ tier: "new" }) });
+    const first = await register(bridge, makeSession("s1"), schema);
+    expect(first.error).toMatch(/disk full/);
+
+    // A later session must still be able to register the same id.
+    const second = await register(bridge, makeSession("s2"), schema);
+    expect(second.registered).toBe(true);
+    expect(bridge.settingsSchemas()).toHaveLength(1);
+  });
+
+  it("does not drop the entry when the reserving session dies while another is still registering", async () => {
+    // Regression: the disposed reserver deleted the entry while a concurrent
+    // registrant was still awaiting migration; that registrant was told it had
+    // registered while its schema stayed invisible forever.
+    const { bridge, settingsStore } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+
+    let releaseMigration: () => void = () => undefined;
+    const gate = new Promise<void>((resolve) => { releaseMigration = resolve; });
+    const schema = schemaFor("demo.x", {
+      schemaVersion: 2,
+      migrate: async () => { await gate; return { tier: "new" }; },
+    });
+
+    const reserver = makeSession("s1");
+    const joiner = makeSession("s2");
+    const reserverRegistration = register(bridge, reserver, schema);
+    const joinerRegistration = register(bridge, joiner, schema);
+
+    bridge.releaseSessionSettings(reserver); // reserver dies mid-migration
+    releaseMigration();
+
+    const [reserverResult, joinerResult] = await Promise.all([reserverRegistration, joinerRegistration]);
+    expect(reserverResult.registered).toBe(false);
+    expect(joinerResult.registered).toBe(true);
+
+    // The surviving registrant must be visible and notifiable.
+    expect(bridge.settingsSchemas()).toHaveLength(1);
+    expect(bridge.settingsSchemaEntry("demo.x")).toBeDefined();
+    const onChange = vi.fn();
+    await register(bridge, joiner, schemaFor("demo.x", { schemaVersion: 2, migrate: async () => ({ tier: "new" }), onChange }));
+    bridge.notifySettingsChanged("demo.x", { tier: "fast" });
+    expect(onChange).toHaveBeenCalled();
+  });
+});

From 97f92a858b2db4ab0e000e9985591b08f504f21a Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 11:05:30 +0000
Subject: [PATCH 06/10] fix: settings panel a11y and close the remaining test
 gaps

Settings panel (second review, non-blocking findings):
- The default-star button was nested inside the accordion header button, which
  is invalid HTML and breaks focus and screen-reader behaviour. Star and header
  are now siblings in a header row; the header remains the only element that
  toggles the accordion, the star toggles the default independently, and the
  inline header styles moved into CSS.
- The "data retained" card for an unloaded extension now offers Reset, so the
  server capability the docs advertise is actually reachable.
- A failed migration is now shown: WebSettingsSchema carries the published
  migrationError and the panel renders it as a role="alert" warning explaining
  that values were reset to defaults and the previous ones kept as a backup.

Test gaps the review flagged as unfalsifiable:
- tests/settings-endpoints.test.ts exercises the real HTTP server: PATCH and
  reset reject a missing, negative, fractional, non-numeric or NaN
  expectedRevision; conflicts report actualRevision; PATCH is refused without a
  live schema; a malformed percent-encoded owner id is a 400; and stored values
  for an unloaded extension can still be reset (with conflict detection).
- The orchestrator tests now serialize the whole registered tool definition and
  assert it is byte-identical when only a category's model changes, while
  changing on a name, prose or default-category edit, and stable across repeated
  registration. This is the prompt-cache stability acceptance test the spec asked
  for and previously only checked content, not stability.

Verified in a browser against an isolated settings file: no nested buttons, the
star does not expand the accordion, the header is a focusable button with
aria-expanded, required inputs and list role=group are present, and the retained
card's Reset works.
---
 src/app/types.ts                   |   1 +
 src/settings/extensionSettings.ts  |  54 ++++----
 src/styles/settings.css            |  39 +++++-
 tests/session-orchestrator.test.ts |  57 ++++++++
 tests/settings-endpoints.test.ts   | 210 +++++++++++++++++++++++++++++
 5 files changed, 329 insertions(+), 32 deletions(-)
 create mode 100644 tests/settings-endpoints.test.ts

diff --git a/src/app/types.ts b/src/app/types.ts
index f9d266f..c86b4e5 100644
--- a/src/app/types.ts
+++ b/src/app/types.ts
@@ -122,6 +122,7 @@ export type WebSettingsSchema = {
   title: string;
   schemaVersion: number;
   fields: WebFieldDescriptor[];
+  migrationError?: string;
 };
 export type StoredExtensionSettings = {
   schemaVersion: number;
diff --git a/src/settings/extensionSettings.ts b/src/settings/extensionSettings.ts
index e585f0c..50e91ca 100644
--- a/src/settings/extensionSettings.ts
+++ b/src/settings/extensionSettings.ts
@@ -254,21 +254,7 @@ export function createExtensionSettings(options: {
       const isDefault = Boolean(defaultRef) && ownerDraft[defaultRef!.selectKey] === row[defaultRef!.itemKey] && row[defaultRef!.itemKey] !== "";
       const rowEl = el("div", { class: `extAccRow${open ? " open" : ""}${hasError ? " hasError" : ""}` });
 
-      const head = el("button", { type: "button", class: "extAccHead" });
-      // Preserve the former div header's layout against the app-wide button
-      // chrome while gaining native keyboard activation and focusability.
-      Object.assign(head.style, {
-        width: "100%",
-        height: "auto",
-        minHeight: "0",
-        border: "0",
-        borderRadius: "0",
-        background: "transparent",
-        color: "inherit",
-        font: "inherit",
-        textAlign: "left",
-      });
-      head.setAttribute("aria-expanded", String(open));
+      const headRow = el("div", { class: "extAccHeadRow" });
       if (defaultRef) {
         const star = el("button", { type: "button", class: `extAccStar${isDefault ? " on" : ""}`, title: isDefault ? `Default ${defaultRef.label}` : `Make default ${defaultRef.label}` }, [isDefault ? "★" : "☆"]);
         star.setAttribute("aria-pressed", String(isDefault));
@@ -277,9 +263,11 @@ export function createExtensionSettings(options: {
           star.setAttribute("aria-invalid", "true");
           addAriaDescription(star, referenceErrorId);
         }
-        star.addEventListener("click", (e) => { e.stopPropagation(); ownerDraft[defaultRef.selectKey] = row[defaultRef.itemKey]; rerender(); });
-        head.append(star);
+        star.addEventListener("click", () => { ownerDraft[defaultRef.selectKey] = row[defaultRef.itemKey]; rerender(); });
+        headRow.append(star);
       }
+      const head = el("button", { type: "button", class: "extAccHead" });
+      head.setAttribute("aria-expanded", String(open));
       const titleText = String((titleField && row[titleField.key]) || "").trim() || "(unnamed)";
       head.append(el("span", { class: "extAccName" }, [titleText]));
       if (metaField) {
@@ -290,7 +278,8 @@ export function createExtensionSettings(options: {
       }
       head.append(el("span", { class: "extAccChev" }, ["⌄"]));
       head.addEventListener("click", () => { if (open) openRows.delete(rid); else openRows.add(rid); rerender(); });
-      rowEl.append(head);
+      headRow.append(head);
+      rowEl.append(headRow);
 
       if (open) {
         const body = el("div", { class: "extAccBody" });
@@ -425,19 +414,19 @@ export function createExtensionSettings(options: {
     }
   }
 
-  async function reset(schema: WebSettingsSchema) {
+  async function reset(id: string) {
     setStatus("Resetting…");
     try {
-      const expectedRevision = storedFor(schema.id)?.revision ?? 0;
-      const res = await fetch(`/api/settings/extensions/${encodeURIComponent(schema.id)}/reset`, {
+      const expectedRevision = storedFor(id)?.revision ?? 0;
+      const res = await fetch(`/api/settings/extensions/${encodeURIComponent(id)}/reset`, {
         method: "POST",
         headers: api.headers(),
         body: JSON.stringify({ expectedRevision }),
       });
       const data = await res.json().catch(() => ({}));
       if (res.status === 409) {
-        errors.delete(schema.id);
-        drafts.delete(schema.id);
+        errors.delete(id);
+        drafts.delete(id);
         try {
           if (!applyResponseSettings(data)) await reloadSettingsFromServer();
         } finally {
@@ -448,8 +437,8 @@ export function createExtensionSettings(options: {
       }
       if (!res.ok || data.ok === false) throw new Error(data.error || `HTTP ${res.status}`);
       if (!applyResponseSettings(data)) await reloadSettingsFromServer();
-      drafts.delete(schema.id);
-      errors.delete(schema.id);
+      drafts.delete(id);
+      errors.delete(id);
       render();
       setStatus("Reset");
     } catch (error) {
@@ -463,6 +452,14 @@ export function createExtensionSettings(options: {
     const draft = ensureDraft(schema);
     const section = el("section", { class: "settingsSection extSettingsSection" });
     section.append(el("h3", {}, [schema.title]));
+    if (schema.migrationError) {
+      const warning = el("div", { class: "extSettingsError extSettingsMigrationWarning" }, [
+        "Your stored settings were reset to defaults because migration failed. The previous values were kept as a backup. ",
+        schema.migrationError,
+      ]);
+      warning.setAttribute("role", "alert");
+      section.append(warning);
+    }
 
     // Detect default-ref selects (rendered as per-row stars on their list).
     const defaultRefByList = new Map<string, DefaultRef>();
@@ -494,7 +491,7 @@ export function createExtensionSettings(options: {
     const saveBtn = el("button", { type: "button" }, ["Save"]);
     saveBtn.addEventListener("click", () => void save(schema));
     const resetBtn = el("button", { type: "button" }, ["Reset"]);
-    resetBtn.addEventListener("click", () => void reset(schema));
+    resetBtn.addEventListener("click", () => void reset(schema.id));
     actions.append(saveBtn, resetBtn);
     section.append(actions);
     return section;
@@ -505,6 +502,11 @@ export function createExtensionSettings(options: {
     const section = el("section", { class: "settingsSection extSettingsSection extSettingsRetained" });
     section.append(el("h3", {}, [id]));
     section.append(el("p", { class: "settingsHint" }, [`Extension not loaded — ${valueCount} value${valueCount === 1 ? "" : "s"} retained. Load the extension to edit.`]));
+    const actions = el("div", { class: "settingsActions" });
+    const resetBtn = el("button", { type: "button" }, ["Reset"]);
+    resetBtn.addEventListener("click", () => void reset(id));
+    actions.append(resetBtn);
+    section.append(actions);
     return section;
   }
 
diff --git a/src/styles/settings.css b/src/styles/settings.css
index c436b29..d64828a 100644
--- a/src/styles/settings.css
+++ b/src/styles/settings.css
@@ -522,22 +522,41 @@
 .extAccRow.hasError {
   border-color: color-mix(in srgb, var(--danger, #e0563f) 55%, var(--border));
 }
-.extAccHead {
+.extAccHeadRow {
   display: flex;
   align-items: center;
   gap: 9px;
   padding: 9px 11px;
+}
+.extAccHead {
+  display: flex;
+  width: 100%;
+  height: auto;
+  min-width: 0;
+  min-height: 0;
+  flex: 1 1 auto;
+  align-items: center;
+  gap: 9px;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  color: inherit;
+  padding: 0;
+  font: inherit;
+  text-align: left;
   cursor: pointer;
 }
 .extAccStar {
-  background: none;
+  height: auto;
+  min-height: 0;
+  flex: 0 0 auto;
   border: none;
-  cursor: pointer;
-  font-size: 15px;
-  line-height: 1;
+  background: none;
   color: var(--muted);
   padding: 0;
-  flex: 0 0 auto;
+  font-size: 15px;
+  line-height: 1;
+  cursor: pointer;
 }
 .extAccStar.on { color: var(--accent); }
 .extAccName {
@@ -612,6 +631,14 @@
   font-size: 12px;
   color: var(--danger, #e0563f);
 }
+.extSettingsMigrationWarning {
+  border: 1px solid color-mix(in srgb, var(--danger, #e0563f) 55%, var(--border));
+  border-radius: 9px;
+  background: color-mix(in srgb, var(--danger, #e0563f) 10%, transparent);
+  padding: 8px 10px;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+}
 .extSettingsField input[aria-invalid="true"],
 .extSettingsField textarea[aria-invalid="true"],
 .extSettingsField select[aria-invalid="true"] {
diff --git a/tests/session-orchestrator.test.ts b/tests/session-orchestrator.test.ts
index ad32c3a..444729c 100644
--- a/tests/session-orchestrator.test.ts
+++ b/tests/session-orchestrator.test.ts
@@ -167,6 +167,11 @@ async function activate(ctx: any) {
   calls.length = 0;
 }
 
+function serializedSpawnDefinition() {
+  const { name, description, parameters } = tools.get("sessions_spawn");
+  return JSON.stringify({ name, description, parameters });
+}
+
 async function spawn(ctx: any, params: Record<string, unknown>) {
   // sessions_spawn is (re)built from config on session_start, so activate first.
   if (!tools.has("sessions_spawn")) await activate(ctx);
@@ -229,6 +234,58 @@ describe("sessions_spawn tool surface", () => {
     await handlers.get("session_start")?.({}, makeCtx());
     expect(tools.get("sessions_spawn").description as string).toMatch(/no categories/i);
   });
+
+  it("keeps the complete tool definition stable when only a category model changes", async () => {
+    await activate(makeCtx({ categories: [FAST, SMART], defaultCategory: "Fast" }));
+    const before = serializedSpawnDefinition();
+
+    await activate(makeCtx({
+      categories: [{ ...FAST, model: "openai:private-replacement" }, SMART],
+      defaultCategory: "Fast",
+    }));
+
+    expect(serializedSpawnDefinition()).toBe(before);
+  });
+
+  it("changes the complete tool definition when a category name changes", async () => {
+    await activate(makeCtx({ categories: [FAST, SMART], defaultCategory: "Smart" }));
+    const before = serializedSpawnDefinition();
+
+    await activate(makeCtx({ categories: [{ ...FAST, name: "Quick" }, SMART], defaultCategory: "Smart" }));
+
+    expect(serializedSpawnDefinition()).not.toBe(before);
+  });
+
+  it("changes the complete tool definition when category routing prose changes", async () => {
+    await activate(makeCtx({ categories: [FAST, SMART], defaultCategory: "Fast" }));
+    const before = serializedSpawnDefinition();
+
+    await activate(makeCtx({
+      categories: [{ ...FAST, description: "Use for fast, bounded repository searches." }, SMART],
+      defaultCategory: "Fast",
+    }));
+
+    expect(serializedSpawnDefinition()).not.toBe(before);
+  });
+
+  it("changes the complete tool definition when the default category changes", async () => {
+    await activate(makeCtx({ categories: [FAST, SMART], defaultCategory: "Fast" }));
+    const before = serializedSpawnDefinition();
+
+    await activate(makeCtx({ categories: [FAST, SMART], defaultCategory: "Smart" }));
+
+    expect(serializedSpawnDefinition()).not.toBe(before);
+  });
+
+  it("re-registers a byte-identical tool definition for identical config", async () => {
+    const config = { categories: [FAST, SMART], defaultCategory: "Fast" };
+    await activate(makeCtx(config));
+    const before = serializedSpawnDefinition();
+
+    await activate(makeCtx(config));
+
+    expect(serializedSpawnDefinition()).toBe(before);
+  });
 });
 
 describe("sessions_spawn fail-closed resolution", () => {
diff --git a/tests/settings-endpoints.test.ts b/tests/settings-endpoints.test.ts
new file mode 100644
index 0000000..f732e64
--- /dev/null
+++ b/tests/settings-endpoints.test.ts
@@ -0,0 +1,210 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { spawn, type ChildProcess } from "node:child_process";
+import { once } from "node:events";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+async function freePort() {
+  const server = createServer();
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const address = server.address();
+  server.close();
+  if (!address || typeof address === "string") throw new Error("Could not allocate port");
+  return address.port;
+}
+
+async function waitForServer(baseUrl: string) {
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`${baseUrl}/api/settings`);
+      if (response.ok) return;
+    } catch {
+      // retry
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`Server did not start: ${baseUrl}`);
+}
+
+function startServer(port: number, cwd: string, settingsFile: string, mock: boolean) {
+  const child = spawn(process.execPath, ["--import", "tsx", "server.ts"], {
+    env: {
+      ...process.env,
+      ...(mock ? { PI_WEB_MOCK: "1" } : { PI_WEB_NO_SESSION: "1" }),
+      PI_WEB_DEV: "1",
+      HOST: "127.0.0.1",
+      PORT: String(port),
+      PI_WEB_TOKEN: "",
+      PI_WEB_CWD: cwd,
+      PI_WEB_SETTINGS_FILE: settingsFile,
+      PI_WEB_SESSION_UI_STATE_FILE: join(cwd, "session-ui-state.json"),
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stderr?.on("data", (data) => process.stderr.write(data));
+  return child;
+}
+
+async function jsonRequest(baseUrl: string, path: string, method: string, body: unknown) {
+  const response = await fetch(`${baseUrl}${path}`, {
+    method,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+function rawRequest(port: number, path: string): Promise<{ status: number; body: unknown }> {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest({ host: "127.0.0.1", port, path, method: "PATCH" }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve({
+        status: res.statusCode || 0,
+        body: JSON.parse(Buffer.concat(chunks).toString()),
+      }));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+const OWNER = "test.settings";
+const OWNER_PATH = `/api/settings/extensions/${encodeURIComponent(OWNER)}`;
+const REVISION_ERROR = { ok: false, error: "expectedRevision must be a non-negative integer" };
+
+describe("extension settings HTTP endpoints with a live schema", () => {
+  let child: ChildProcess;
+  let baseUrl: string;
+  let port: number;
+  let workspace: string;
+
+  beforeAll(async () => {
+    workspace = await mkdtemp(join(tmpdir(), "pi-web-settings-endpoints-"));
+    const extensionsDir = join(workspace, ".pi", "web", "extensions");
+    await mkdir(extensionsDir, { recursive: true });
+    await writeFile(join(extensionsDir, "settings-test.js"), `
+export default function settingsTest(pi) {
+  pi.on("session_start", async (_event, ctx) => {
+    await ctx.ui.web.registerSettings({
+      id: "${OWNER}",
+      title: "Endpoint test settings",
+      schemaVersion: 1,
+      fields: [{ key: "label", type: "text", label: "Label" }],
+    });
+  });
+}
+`);
+
+    port = await freePort();
+    baseUrl = `http://127.0.0.1:${port}`;
+    child = startServer(port, workspace, join(workspace, "settings.json"), false);
+    await waitForServer(baseUrl);
+  }, 20_000);
+
+  afterAll(async () => {
+    child?.kill();
+    if (workspace) await rm(workspace, { recursive: true, force: true });
+  });
+
+  it("requires a non-negative integer expectedRevision for PATCH and reset", async () => {
+    const invalidBodies = [
+      {},
+      { expectedRevision: -1 },
+      { expectedRevision: 0.5 },
+      { expectedRevision: "0" },
+      { expectedRevision: Number.NaN }, // JSON serializes NaN as null.
+    ];
+    for (const body of invalidBodies) {
+      const patch = await jsonRequest(baseUrl, OWNER_PATH, "PATCH", { values: { label: "next" }, ...body });
+      expect(patch, `PATCH body ${JSON.stringify(body)}`).toEqual({ status: 400, body: REVISION_ERROR });
+
+      const reset = await jsonRequest(baseUrl, `${OWNER_PATH}/reset`, "POST", body);
+      expect(reset, `reset body ${JSON.stringify(body)}`).toEqual({ status: 400, body: REVISION_ERROR });
+    }
+  });
+
+  it("returns the actual revision when PATCH detects a conflict", async () => {
+    const first = await jsonRequest(baseUrl, OWNER_PATH, "PATCH", {
+      values: { label: "first" },
+      expectedRevision: 0,
+    });
+    expect(first.status).toBe(200);
+    expect(first.body).toMatchObject({ ok: true, revision: 1 });
+
+    const conflict = await jsonRequest(baseUrl, OWNER_PATH, "PATCH", {
+      values: { label: "stale" },
+      expectedRevision: 0,
+    });
+    expect(conflict).toEqual({
+      status: 409,
+      body: { ok: false, error: "revision conflict", actualRevision: 1 },
+    });
+  });
+
+  it("rejects PATCH when the requested extension has no live schema", async () => {
+    const result = await jsonRequest(baseUrl, "/api/settings/extensions/not-loaded.settings", "PATCH", {
+      values: {},
+      expectedRevision: 0,
+    });
+    expect(result).toEqual({ status: 409, body: { ok: false, error: "extension not loaded" } });
+  });
+
+  it("rejects a malformed percent-encoded owner id", async () => {
+    const result = await rawRequest(port, "/api/settings/extensions/%E0%A4%A");
+    expect(result).toEqual({ status: 400, body: { ok: false, error: "malformed owner id" } });
+  });
+});
+
+describe("extension settings reset HTTP endpoint without a live schema", () => {
+  let child: ChildProcess;
+  let baseUrl: string;
+  let workspace: string;
+
+  beforeAll(async () => {
+    workspace = await mkdtemp(join(tmpdir(), "pi-web-settings-unloaded-"));
+    const settingsFile = join(workspace, "settings.json");
+    await writeFile(settingsFile, JSON.stringify({
+      version: 1,
+      extensions: {
+        "stored.only": { schemaVersion: 1, revision: 3, values: { label: "saved" } },
+      },
+    }));
+    const port = await freePort();
+    baseUrl = `http://127.0.0.1:${port}`;
+    child = startServer(port, workspace, settingsFile, true);
+    await waitForServer(baseUrl);
+  }, 20_000);
+
+  afterAll(async () => {
+    child?.kill();
+    if (workspace) await rm(workspace, { recursive: true, force: true });
+  });
+
+  it("reports reset revision conflicts for stored settings whose extension is unloaded", async () => {
+    const result = await jsonRequest(baseUrl, "/api/settings/extensions/stored.only/reset", "POST", {
+      expectedRevision: 2,
+    });
+    expect(result).toEqual({
+      status: 409,
+      body: { ok: false, error: "revision conflict", actualRevision: 3 },
+    });
+  });
+
+  it("resets stored settings even when their extension is unloaded", async () => {
+    const result = await jsonRequest(baseUrl, "/api/settings/extensions/stored.only/reset", "POST", {
+      expectedRevision: 3,
+    });
+    expect(result.status).toBe(200);
+    expect(result.body).toMatchObject({ ok: true });
+    expect(result.body.settings.extensions?.["stored.only"]).toBeUndefined();
+
+    const persisted = await (await fetch(`${baseUrl}/api/settings`)).json();
+    expect(persisted.settings.extensions?.["stored.only"]).toBeUndefined();
+  });
+});

From c8b7c91cca25b637c614588cbec46794150564b4 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 12:00:22 +0000
Subject: [PATCH 07/10] fix: sessions could vanish from the drawer, and lineage
 could be wiped
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A cold review (no prior findings supplied, to avoid anchoring) found two real
defects in the lineage surfaces that two earlier reviews had missed.

Sessions disappearing from the drawer. orderItemsWithChildren only re-emitted
deferred children one level deep, so with origins C->B->A the grandchild C was
dropped from the rendered list entirely, and a 2-cycle (A->B, B->A) left no root
at all so BOTH sessions disappeared. Origins are client-asserted — /api/new-chat
records an origin without checking the parent exists or that the graph is
acyclic, and the session-ui-state PATCH accepts an arbitrary origins array — so
this is reachable without any bug in the bundled extension, and the bundled
extension's depth cap does not protect core. A session that still exists but
cannot be found in the primary navigation surface is close to data loss from the
user's point of view.

The ordering logic now walks descendants iteratively with a visited set, and
falls back to emitting anything the walk did not reach, so imperfect ordering is
the worst case and a session can never be dropped.

Lineage wiped by legacy-state migration. hasAnySessionUiState deliberately
ignored sessionOrigins, so a server holding only lineage looked "empty" to a
browser carrying legacy localStorage state; that browser then pushed its own
normalized state, which always includes sessionOrigins: [], and the patch path
replaces the array whenever the key is present — erasing every recorded origin.
Lineage now counts as state.

The drawer's derived logic had no tests at all, which is why both defects were
invisible. The rules that decide what a user sees are now a pure module
(src/sessions/lineage.ts): child ordering, the running > waiting > unread
precedence, and which spawned children are still running. 16 tests cover deep
chains, cycles, self-parenting, absent parents and de-duplication; reverting to
the one-level expansion fails five of them.

Also: warn when the stored owner list is truncated at the bounds limit, instead
of silently discarding owners beyond it.
---
 server/settings.ts            |   6 +-
 src/sessions/lineage.ts       | 110 ++++++++++++++++++++++++++++++
 src/sessions/sessionDrawer.ts |  36 ++++------
 tests/session-lineage.test.ts | 123 ++++++++++++++++++++++++++++++++++
 4 files changed, 252 insertions(+), 23 deletions(-)
 create mode 100644 src/sessions/lineage.ts
 create mode 100644 tests/session-lineage.test.ts

diff --git a/server/settings.ts b/server/settings.ts
index 3e23d4a..56e9901 100644
--- a/server/settings.ts
+++ b/server/settings.ts
@@ -171,7 +171,11 @@ export function normalizeExtensionSettings(value: unknown): Record<string, Store
   if (!isRecord(value)) return undefined;
   const out: Record<string, StoredExtensionSettings> = {};
   let count = 0;
-  for (const [id, raw] of Object.entries(value)) {
+  const entries = Object.entries(value);
+  if (entries.length > extensionSettingsLimits.maxOwners) {
+    console.warn(`pi-web: ignoring extension settings beyond the first ${extensionSettingsLimits.maxOwners} owners (${entries.length} stored)`);
+  }
+  for (const [id, raw] of entries) {
     if (count >= extensionSettingsLimits.maxOwners) break;
     if (!isValidExtensionOwnerId(id)) continue;
     const record = normalizeStoredExtension(raw);
diff --git a/src/sessions/lineage.ts b/src/sessions/lineage.ts
new file mode 100644
index 0000000..02be671
--- /dev/null
+++ b/src/sessions/lineage.ts
@@ -0,0 +1,110 @@
+/**
+ * Pure derived-state helpers for the session drawer.
+ *
+ * Extracted from the drawer so the rules that decide what a user sees — which
+ * sessions are listed, and which single indicator each one shows — are testable
+ * without a DOM. The drawer supplies the lookups; these functions hold the rules.
+ */
+
+export type LineageItem = { id: string };
+
+export type SessionIndicatorKind = "running" | "waiting" | "unread" | "none";
+
+/**
+ * Order a list so that sessions spawned by another session follow their parent.
+ *
+ * Handles arbitrarily deep lineage (a child of a child) and is defensive about
+ * malformed data: origins are client-asserted, so cycles are possible, and a
+ * session must NEVER disappear from the list because of them. Anything not
+ * reached by the walk is appended in its original relative order.
+ */
+export function orderItemsWithChildren<T extends LineageItem>(
+  items: T[],
+  parentOf: (id: string) => string | undefined,
+): T[] {
+  const ids = new Set(items.map((item) => item.id));
+  const childrenByParent = new Map<string, T[]>();
+  const deferred = new Set<string>();
+
+  for (const item of items) {
+    const parent = parentOf(item.id);
+    // Self-parenting and parents outside this list leave the item where it is.
+    if (!parent || parent === item.id || !ids.has(parent)) continue;
+    const siblings = childrenByParent.get(parent);
+    if (siblings) siblings.push(item);
+    else childrenByParent.set(parent, [item]);
+    deferred.add(item.id);
+  }
+  if (deferred.size === 0) return items;
+
+  const result: T[] = [];
+  const emitted = new Set<string>();
+
+  const emitWithDescendants = (root: T) => {
+    if (emitted.has(root.id)) return;
+    emitted.add(root.id);
+    result.push(root);
+    // Iterative depth-first walk: a stack, not one level of nesting, so
+    // grandchildren and deeper are never dropped.
+    const stack = [...(childrenByParent.get(root.id) ?? [])].reverse();
+    while (stack.length > 0) {
+      const child = stack.pop()!;
+      if (emitted.has(child.id)) continue; // cycle guard
+      emitted.add(child.id);
+      result.push(child);
+      const grandchildren = childrenByParent.get(child.id) ?? [];
+      for (let i = grandchildren.length - 1; i >= 0; i -= 1) stack.push(grandchildren[i]);
+    }
+  };
+
+  for (const item of items) {
+    if (deferred.has(item.id)) continue; // start from roots only
+    emitWithDescendants(item);
+  }
+
+  // Safety net: a pure cycle has no root, so nothing above would emit it.
+  // Losing a session from the drawer is far worse than imperfect ordering.
+  if (emitted.size !== items.length) {
+    for (const item of items) {
+      if (!emitted.has(item.id)) result.push(item);
+    }
+  }
+  return result;
+}
+
+/**
+ * Single precedence rule for per-session indicators: running > waiting > unread.
+ * Exactly one indicator is shown per session, everywhere (tabs and drawer rows).
+ */
+export function sessionIndicatorKind(state: {
+  running?: boolean;
+  waiting?: boolean;
+  unread?: boolean;
+}): SessionIndicatorKind {
+  if (state.running) return "running";
+  if (state.waiting) return "waiting";
+  if (state.unread) return "unread";
+  return "none";
+}
+
+/**
+ * Sessions this one spawned that are still running. A session is only "waiting"
+ * when it is itself idle: a running session shows its own progress instead.
+ */
+export function runningChildIdsOf(
+  sessionId: string,
+  origins: Array<{ sessionId: string; originSessionId: string }>,
+  isRunning: (id: string) => boolean,
+): string[] {
+  if (!sessionId) return [];
+  const seen = new Set<string>();
+  const running: string[] = [];
+  for (const origin of origins) {
+    if (origin.originSessionId !== sessionId) continue;
+    const childId = origin.sessionId;
+    if (!childId || childId === sessionId || seen.has(childId)) continue;
+    seen.add(childId);
+    if (isRunning(childId)) running.push(childId);
+  }
+  return running;
+}
diff --git a/src/sessions/sessionDrawer.ts b/src/sessions/sessionDrawer.ts
index 5105b48..b2022dc 100644
--- a/src/sessions/sessionDrawer.ts
+++ b/src/sessions/sessionDrawer.ts
@@ -6,6 +6,7 @@ import type { RightPanelHandle, RightPanelManager } from "../layout/rightPanel.j
 import type { AppState, SessionInfo, SessionMarkerColorId, SessionUiState } from "../app/types.js";
 import { sessionRuntime, type SessionStateController } from "../app/sessionState.js";
 import { defaultSessionUiState, normalizeSessionUiState, persistCollapsedSessionFolders, sessionFolderPreviewLimit, sessionMarkerColors, writeActiveSessionIdToUrl } from "../app/types.js";
+import { orderItemsWithChildren as orderLineage, runningChildIdsOf, sessionIndicatorKind } from "./lineage.js";
 
 export async function fetchSessionList(url: string, headers: HeadersInit, timeoutMs = 15_000) {
   const controller = new AbortController();
@@ -518,6 +519,9 @@ export function createSessions(options: {
       || value.pinnedFolders.length > 0
       || value.sessionMarkers.length > 0
       || value.sessionUnreadStates.length > 0
+      // Lineage counts as state: without it, a server holding ONLY origins looks
+      // "empty" and a legacy-localStorage push would wipe every recorded origin.
+      || (value.sessionOrigins?.length ?? 0) > 0
       || value.allowedMarkerColors.length > 0
       || value.selectedMarkerColor !== defaultSessionUiState.selectedMarkerColor;
   }
@@ -594,7 +598,7 @@ export function createSessions(options: {
   }
 
   function runningChildrenOf(sessionId: string) {
-    return childSessionIdsOf(sessionId).filter((childId) => {
+    return runningChildIdsOf(sessionId, state.sessionOrigins || [], (childId) => {
       const cached = cachedSessions.find((item) => item.id === childId);
       return isSessionRunning(childId, Boolean(cached?.runtime?.isRunning));
     });
@@ -625,10 +629,15 @@ export function createSessions(options: {
     | { kind: "waiting"; waiting: { count: number; names: string[] } }
     | { kind: "unread" }
     | { kind: "none" } {
-    if (isSessionRunning(sessionId, Boolean(fallbacks.running))) return { kind: "running" };
     const waiting = waitingInfoFor(sessionId);
-    if (waiting) return { kind: "waiting", waiting };
-    if (isSessionUnread(sessionId, Boolean(fallbacks.unread), Boolean(fallbacks.running))) return { kind: "unread" };
+    const kind = sessionIndicatorKind({
+      running: isSessionRunning(sessionId, Boolean(fallbacks.running)),
+      waiting: Boolean(waiting),
+      unread: isSessionUnread(sessionId, Boolean(fallbacks.unread), Boolean(fallbacks.running)),
+    });
+    if (kind === "waiting" && waiting) return { kind: "waiting", waiting };
+    if (kind === "running") return { kind: "running" };
+    if (kind === "unread") return { kind: "unread" };
     return { kind: "none" };
   }
 
@@ -1888,24 +1897,7 @@ export function createSessions(options: {
   /** Keep spawned children adjacent to (and after) their parent in the list. */
   function orderItemsWithChildren(items: SessionInfo[]): SessionInfo[] {
     if (!(state.sessionOrigins || []).length) return items;
-    const ids = new Set(items.map((item) => item.id));
-    const childrenByParent = new Map<string, SessionInfo[]>();
-    const deferred = new Set<string>();
-    for (const item of items) {
-      const parent = originParentOf(item.id);
-      if (parent && ids.has(parent)) {
-        childrenByParent.set(parent, [...(childrenByParent.get(parent) || []), item]);
-        deferred.add(item.id);
-      }
-    }
-    if (deferred.size === 0) return items;
-    const result: SessionInfo[] = [];
-    for (const item of items) {
-      if (deferred.has(item.id)) continue;
-      result.push(item);
-      for (const child of childrenByParent.get(item.id) || []) result.push(child);
-    }
-    return result;
+    return orderLineage(items, (id) => originParentOf(id));
   }
 
   function buildSessionItem(item: SessionInfo, cwd: string): HTMLElement {
diff --git a/tests/session-lineage.test.ts b/tests/session-lineage.test.ts
new file mode 100644
index 0000000..468f597
--- /dev/null
+++ b/tests/session-lineage.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { orderItemsWithChildren, runningChildIdsOf, sessionIndicatorKind } from "../src/sessions/lineage.js";
+
+type Item = { id: string };
+const items = (...ids: string[]): Item[] => ids.map((id) => ({ id }));
+const ids = (list: Item[]) => list.map((item) => item.id);
+
+/** Build a parent lookup from "child->parent" pairs. */
+function parentLookup(pairs: Array<[string, string]>) {
+  const map = new Map(pairs);
+  return (id: string) => map.get(id);
+}
+
+describe("orderItemsWithChildren", () => {
+  it("leaves the list untouched when nothing has a parent", () => {
+    const list = items("a", "b", "c");
+    expect(orderItemsWithChildren(list, () => undefined)).toBe(list);
+  });
+
+  it("moves a child directly after its parent", () => {
+    const list = items("a", "b", "child-of-a");
+    const ordered = orderItemsWithChildren(list, parentLookup([["child-of-a", "a"]]));
+    expect(ids(ordered)).toEqual(["a", "child-of-a", "b"]);
+  });
+
+  it("keeps multiple children after their parent in their original order", () => {
+    const list = items("a", "c1", "b", "c2");
+    const ordered = orderItemsWithChildren(list, parentLookup([["c1", "a"], ["c2", "a"]]));
+    expect(ids(ordered)).toEqual(["a", "c1", "c2", "b"]);
+  });
+
+  it("keeps a grandchild in the list and under its own parent", () => {
+    // Regression: one level of nesting used to be emitted, so a child of a
+    // child silently VANISHED from the drawer.
+    const list = items("a", "b", "c");
+    const ordered = orderItemsWithChildren(list, parentLookup([["b", "a"], ["c", "b"]]));
+    expect(ids(ordered)).toEqual(["a", "b", "c"]);
+    expect(ordered).toHaveLength(3);
+  });
+
+  it("keeps a deep lineage chain intact", () => {
+    const list = items("d", "c", "b", "a");
+    const ordered = orderItemsWithChildren(list, parentLookup([["b", "a"], ["c", "b"], ["d", "c"]]));
+    expect(ids(ordered)).toEqual(["a", "b", "c", "d"]);
+  });
+
+  it("never drops sessions when origins form a cycle", () => {
+    // Regression: a 2-cycle left no root, so BOTH sessions vanished. Origins are
+    // client-asserted, so this must degrade to imperfect order, never data loss.
+    const list = items("a", "b");
+    const ordered = orderItemsWithChildren(list, parentLookup([["a", "b"], ["b", "a"]]));
+    expect(ids(ordered).sort()).toEqual(["a", "b"]);
+  });
+
+  it("never drops sessions when a cycle sits below a real root", () => {
+    const list = items("root", "x", "y");
+    const ordered = orderItemsWithChildren(list, parentLookup([["x", "root"], ["y", "x"], ["x", "y"]]));
+    expect(ids(ordered).sort()).toEqual(["root", "x", "y"]);
+  });
+
+  it("ignores a session that claims itself as its parent", () => {
+    const list = items("a", "b");
+    const ordered = orderItemsWithChildren(list, parentLookup([["a", "a"]]));
+    expect(ids(ordered)).toEqual(["a", "b"]);
+  });
+
+  it("leaves a child in place when its parent is not in the list", () => {
+    const list = items("a", "orphan");
+    const ordered = orderItemsWithChildren(list, parentLookup([["orphan", "missing-parent"]]));
+    expect(ids(ordered)).toEqual(["a", "orphan"]);
+  });
+
+  it("emits every input exactly once for a mixed tree", () => {
+    const list = items("p1", "p2", "c1a", "c1b", "g1", "loner");
+    const ordered = orderItemsWithChildren(list, parentLookup([
+      ["c1a", "p1"], ["c1b", "p1"], ["g1", "c1a"],
+    ]));
+    expect(ids(ordered)).toEqual(["p1", "c1a", "g1", "c1b", "p2", "loner"]);
+    expect(new Set(ids(ordered)).size).toBe(list.length);
+  });
+});
+
+describe("sessionIndicatorKind", () => {
+  it("applies the precedence running > waiting > unread", () => {
+    expect(sessionIndicatorKind({ running: true, waiting: true, unread: true })).toBe("running");
+    expect(sessionIndicatorKind({ waiting: true, unread: true })).toBe("waiting");
+    expect(sessionIndicatorKind({ unread: true })).toBe("unread");
+    expect(sessionIndicatorKind({})).toBe("none");
+  });
+});
+
+describe("runningChildIdsOf", () => {
+  const origins = [
+    { sessionId: "child-running", originSessionId: "parent" },
+    { sessionId: "child-idle", originSessionId: "parent" },
+    { sessionId: "other-child", originSessionId: "someone-else" },
+  ];
+
+  it("returns only this session's still-running children", () => {
+    expect(runningChildIdsOf("parent", origins, (id) => id === "child-running")).toEqual(["child-running"]);
+  });
+
+  it("returns nothing when no child is running", () => {
+    expect(runningChildIdsOf("parent", origins, () => false)).toEqual([]);
+  });
+
+  it("ignores other parents' children", () => {
+    expect(runningChildIdsOf("parent", origins, () => true)).toEqual(["child-running", "child-idle"]);
+  });
+
+  it("de-duplicates repeated origin records and ignores self-parenting", () => {
+    const messy = [
+      { sessionId: "c", originSessionId: "parent" },
+      { sessionId: "c", originSessionId: "parent" },
+      { sessionId: "parent", originSessionId: "parent" },
+    ];
+    expect(runningChildIdsOf("parent", messy, () => true)).toEqual(["c"]);
+  });
+
+  it("returns nothing for an empty session id", () => {
+    expect(runningChildIdsOf("", origins, () => true)).toEqual([]);
+  });
+});

From ddd88579ae7707f279d64509a651aaf558843bfa Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 12:02:39 +0000
Subject: [PATCH 08/10] fix: settings validator, panel focus, and registry
 ownership
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the cold review.

Validator
- An optional number field could never be cleared: an empty input sends
  undefined, Number(undefined) is NaN, and the validator errored regardless of
  whether the field was required — a 422 the user could only escape by typing a
  value. Meanwhile an empty string coerced to 0, so the same "empty" input was
  sometimes an error and sometimes zero. Empty now means unset for optional
  fields; required and genuinely non-numeric values still error.
- A list value that was present but not an array was silently coerced to [],
  destroying stored rows with no error. Present-but-wrong-shape list values and
  list rows now produce validation errors at their path.

Settings panel
- Nested lists are rejected at registration, because the client cannot render
  them; if one still reaches the scalar renderer it now shows a disabled,
  read-only view instead of a text input that would have flattened the array to a
  string on the next save.
- The panel no longer steals the caret. It re-rendered on every settings_updated
  and every schema-list broadcast, and with the orchestrator installed the latter
  fires whenever a worker session spawns, so typing was interrupted routinely.
  Broadcast-driven renders are now skipped when the structural signature is
  unchanged and focus is inside the panel; explicit edits and save/reset still
  render.
- The schema-changed broadcast now only fires when the published list actually
  changes, so an additional session registering the same schema is silent.

Registry
- A stale in-flight registration could overwrite a different schema registered
  under the same id after a release, leaving two sessions both told they had
  registered while one entry became invisible and never received onChange. An
  entry with pending registrations is no longer deleted, and a late continuation
  re-checks ownership: it joins a matching replacement and refuses to overwrite a
  divergent one.
- Migration wrote without a revision guard, so a user reset that landed during a
  registration's migration was silently undone moments later. Migration writes now
  carry the revision from their own read and treat a conflict as "someone else
  acted, skip", still without ever rejecting the shared migration promise.

Also removed a dead pointer to a local planning artifact that is not in the repo.

Reverting either registry fix fails its regression test (verified by mutation).
---
 server/extensionSettings.ts       |  18 ++++-
 server/extensions/webUi.ts        | 123 +++++++++++++++++++---------
 src/settings/extensionSettings.ts |  49 +++++++++---
 tests/extension-settings.test.ts  |  70 ++++++++++++++++
 tests/web-ui-settings.test.ts     | 128 ++++++++++++++++++++++++++++++
 5 files changed, 337 insertions(+), 51 deletions(-)

diff --git a/server/extensionSettings.ts b/server/extensionSettings.ts
index 21cb278..548bd5d 100644
--- a/server/extensionSettings.ts
+++ b/server/extensionSettings.ts
@@ -3,8 +3,10 @@
  *
  * Shared backbone for the generic pi-web extension-settings platform. Kept pure
  * (no node/browser deps) so both the server (validation before persist) and the
- * client (form rendering) can rely on the same contract. See
- * `.pi/web/artifacts/worker-model-selection-plan.md` (Amendment 3).
+ * client (form rendering) can rely on the same descriptor, defaulting, and
+ * validation contract. Extension authors register namespaced schemas; pi-web
+ * renders those schemas and validates values before persistence. See
+ * `docs/pi-web-extensions.md`.
  */
 
 import type { JsonObject } from "./settings.js";
@@ -111,6 +113,12 @@ function coerceScalar(field: FieldDescriptor, raw: unknown, path: string, errors
     case "toggle":
       return typeof raw === "boolean" ? raw : Boolean(raw);
     case "number": {
+      const empty = raw === undefined || raw === null || raw === "";
+      if (empty) {
+        if (!field.required) return typeof field.default === "number" ? field.default : undefined;
+        errors.push({ path, message: `${field.label} must be a number` });
+        return typeof field.default === "number" ? field.default : (field.min ?? 0);
+      }
       const n = typeof raw === "number" ? raw : Number(raw);
       if (!Number.isFinite(n)) {
         errors.push({ path, message: `${field.label} must be a number` });
@@ -223,10 +231,16 @@ export function validateSettingsValues(
 }
 
 function coerceList(field: FieldDescriptor, raw: unknown, path: string, errors: ValidationError[]): JsonObject[] {
+  if (raw !== undefined && raw !== null && !Array.isArray(raw)) {
+    errors.push({ path, message: `${field.label} must be a list` });
+  }
   const arr = Array.isArray(raw) ? raw : [];
   const itemFields = field.itemFields ?? [];
   const rows: JsonObject[] = arr.map((rawRow, i) => {
     const row: JsonObject = {};
+    if (!isRecord(rawRow)) {
+      errors.push({ path: `${path}[${i}]`, message: `${field.label} item must be an object` });
+    }
     const rowSrc = isRecord(rawRow) ? rawRow : {};
     // preserve/generate stable __id
     row.__id = typeof rowSrc.__id === "string" && rowSrc.__id ? rowSrc.__id : newRowId();
diff --git a/server/extensions/webUi.ts b/server/extensions/webUi.ts
index 0bb34a1..f2b9a85 100644
--- a/server/extensions/webUi.ts
+++ b/server/extensions/webUi.ts
@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { ExtensionUIDialogOptions, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { PiWebArtifactAction, PiWebFooter, PiWebGitTab, PiWebHeaderAction, PiWebRegisterSettingsResult, PiWebSettingsRegistration, PiWebStoredSettings, PiWebUi } from "../../src/extensions.js";
 import type { createSettingsStore } from "../settings.js";
-import { isValidExtensionOwnerId } from "../settings.js";
+import { ExtensionRevisionConflictError, isValidExtensionOwnerId } from "../settings.js";
 import { canonicalSchemaKey, defaultSettingsValues, validateSettingsValues } from "../extensionSettings.js";
 
 export interface WebUiBridgeDependencies {
@@ -105,6 +105,7 @@ function settingsSchemaProblem(schema: PiWebSettingsRegistration, depth = 0, fie
     if (!settingsFieldTypes.has(String(field.type))) return `unsupported field type "${String(field.type)}" on "${field.key}"`;
     if (typeof field.label !== "string" || !field.label.trim()) return `field "${field.key}" needs a label`;
     if (field.type === "list") {
+      if (depth > 0) return `field "${field.key}": nested list fields are not supported`;
       const nested = settingsSchemaProblem(schema, depth + 1, field.itemFields);
       if (nested) return nested;
     }
@@ -127,8 +128,14 @@ function activeSettingsSchemaList() {
     .map(serializableSettingsSchema);
 }
 
-function broadcastSettingsSchemas() {
-  deps.emit({ type: "web_settings_schemas_changed", webSettingsSchemas: activeSettingsSchemaList() });
+function settingsSchemaListKey() {
+  return JSON.stringify(activeSettingsSchemaList());
+}
+
+function broadcastSettingsSchemasIfChanged(previousKey: string) {
+  const webSettingsSchemas = activeSettingsSchemaList();
+  if (JSON.stringify(webSettingsSchemas) === previousKey) return;
+  deps.emit({ type: "web_settings_schemas_changed", webSettingsSchemas });
 }
 
 /**
@@ -159,19 +166,39 @@ async function migrateStoredSettings(
       if (migrateError === undefined && migratedValues !== undefined) {
         const { values, errors } = validateSettingsValues(schema, migratedValues, { modelOptions: deps.modelOptions() });
         if (errors.length === 0) {
-          await deps.settingsStore.patchExtension(schema.id, values, { schemaVersion: schema.schemaVersion, backup });
+          await deps.settingsStore.patchExtension(schema.id, values, {
+            schemaVersion: schema.schemaVersion,
+            expectedRevision: stored.revision,
+            backup,
+          });
           return { migrated: true, usedBackup: false };
         }
         migrateError = `migration produced invalid values (${errors.length})`;
       }
-      await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
+      await deps.settingsStore.patchExtension(schema.id, defaults, {
+        schemaVersion: schema.schemaVersion,
+        expectedRevision: stored.revision,
+        backup,
+      });
       return { migrated: false, usedBackup: true, error: migrateError };
     }
     // No migrate() provided: reset to defaults, keep a one-slot backup.
-    await deps.settingsStore.patchExtension(schema.id, defaults, { schemaVersion: schema.schemaVersion, backup });
+    await deps.settingsStore.patchExtension(schema.id, defaults, {
+      schemaVersion: schema.schemaVersion,
+      expectedRevision: stored.revision,
+      backup,
+    });
     return { migrated: false, usedBackup: true };
   } catch (error) {
-    return { migrated: false, usedBackup: false, error: describe(error) };
+    const message = describe(error);
+    if (error instanceof ExtensionRevisionConflictError) {
+      return {
+        migrated: false,
+        usedBackup: false,
+        error: `migration skipped because settings changed concurrently: ${message}`,
+      };
+    }
+    return { migrated: false, usedBackup: false, error: message };
   }
 }
 
@@ -196,7 +223,6 @@ async function registerSessionSettings(
     console.warn(`pi-web: ${error}; rejecting new registration.`);
     return { registered: false, migrated: false, usedBackup: false, error };
   }
-  const reserved = !entry;
   if (!entry) {
     entry = {
       schema,
@@ -209,38 +235,60 @@ async function registerSessionSettings(
     activeSettingsSchemas.set(id, entry);
   }
 
-  // Count ourselves as in-flight BEFORE awaiting, so a concurrent registrant
-  // that gets disposed cannot delete this entry out from under us.
-  entry.pending += 1;
   let result: { migrated: boolean; usedBackup: boolean; error?: string };
-  try {
-    result = await entry.migration;
-  } catch (error) {
-    // migrateStoredSettings is written not to reject; treat a rejection as a
-    // failed registration and release the reservation so the id stays usable.
-    const message = error instanceof Error ? error.message : String(error);
+  while (true) {
+    // Count ourselves as in-flight BEFORE awaiting, so releasing the last
+    // registrant cannot drop this entry while this registration can still use it.
+    entry.pending += 1;
+    try {
+      result = await entry.migration;
+    } catch (error) {
+      // migrateStoredSettings is written not to reject; treat a rejection as a
+      // failed registration and release the reservation so the id stays usable.
+      const message = error instanceof Error ? error.message : String(error);
+      entry.pending -= 1;
+      if (entry.registrants.size === 0 && entry.pending === 0 && activeSettingsSchemas.get(id) === entry) {
+        activeSettingsSchemas.delete(id);
+      }
+      return { registered: false, migrated: false, usedBackup: false, error: message };
+    }
     entry.pending -= 1;
-    if (entry.registrants.size === 0 && entry.pending === 0) activeSettingsSchemas.delete(id);
-    return { registered: false, migrated: false, usedBackup: false, error: message };
-  }
-  entry.pending -= 1;
-  entry.ready = true;
-  if (result.error) {
-    entry.migrationError = result.error;
-    console.warn(`pi-web: settings migration for "${id}" fell back to defaults: ${result.error}`);
-  }
+    entry.ready = true;
+    if (result.error) {
+      entry.migrationError = result.error;
+      console.warn(`pi-web: settings migration for "${id}" did not complete: ${result.error}`);
+    }
 
-  // The session may have shut down while migration was in flight; never
-  // register a dead session (and drop a reservation nobody else is claiming).
-  if (disposedSettingsSessions.has(session)) {
-    if (entry.registrants.size === 0 && entry.pending === 0) activeSettingsSchemas.delete(id);
-    return { registered: false, migrated: result.migrated, usedBackup: result.usedBackup, error: "session shut down during registration" };
+    // The session may have shut down while migration was in flight; never
+    // register a dead session (and drop a reservation nobody else is claiming).
+    if (disposedSettingsSessions.has(session)) {
+      if (entry.registrants.size === 0 && entry.pending === 0 && activeSettingsSchemas.get(id) === entry) {
+        activeSettingsSchemas.delete(id);
+      }
+      return { registered: false, migrated: result.migrated, usedBackup: result.usedBackup, error: "session shut down during registration" };
+    }
+
+    const current = activeSettingsSchemas.get(id);
+    if (!current) {
+      // The id is still unclaimed, so this completed reservation may publish.
+      activeSettingsSchemas.set(id, entry);
+      break;
+    }
+    if (current === entry) break;
+    if (current.canonicalKey !== canonical) {
+      const error = `settings id "${id}" is now registered with a different schema`;
+      console.warn(`pi-web: ${error}; rejecting registration completed against a stale reservation.`);
+      return { registered: false, migrated: result.migrated, usedBackup: result.usedBackup, error };
+    }
+
+    // Another equivalent entry became canonical while this migration awaited.
+    // Join it (and await its shared migration) instead of overwriting it.
+    entry = current;
   }
 
-  // Always attach to the entry the registry currently holds for this id.
-  if (activeSettingsSchemas.get(id) !== entry) activeSettingsSchemas.set(id, entry);
+  const previousSchemaList = settingsSchemaListKey();
   entry.registrants.set(session, { schema, sessionId: String(value?.sessionId || "") });
-  broadcastSettingsSchemas();
+  broadcastSettingsSchemasIfChanged(previousSchemaList);
   return { registered: true, migrated: result.migrated, usedBackup: result.usedBackup, error: result.error };
 }
 
@@ -260,13 +308,12 @@ function notifySettingsChanged(id: string, values: Record<string, unknown>) {
 function releaseSessionSettings(value: any) {
   const session = value as object;
   disposedSettingsSessions.add(session);
-  let changed = false;
+  const previousSchemaList = settingsSchemaListKey();
   for (const [id, entry] of activeSettingsSchemas) {
     if (!entry.registrants.delete(session)) continue;
-    changed = true;
-    if (entry.registrants.size === 0) activeSettingsSchemas.delete(id);
+    if (entry.registrants.size === 0 && entry.pending === 0) activeSettingsSchemas.delete(id);
   }
-  if (changed) broadcastSettingsSchemas();
+  broadcastSettingsSchemasIfChanged(previousSchemaList);
 }
 
 async function getExtensionSettings(id: string): Promise<PiWebStoredSettings> {
diff --git a/src/settings/extensionSettings.ts b/src/settings/extensionSettings.ts
index 50e91ca..e5d9280 100644
--- a/src/settings/extensionSettings.ts
+++ b/src/settings/extensionSettings.ts
@@ -76,6 +76,7 @@ export function createExtensionSettings(options: {
   const openRows = new Set<string>();
   let modelOptions: WebSelectOption[] | undefined;
   let modelsLoading = false;
+  let lastRenderStructureKey: string | undefined;
 
   function storedFor(id: string) {
     return state.settings.extensions?.[id];
@@ -189,6 +190,24 @@ export function createExtensionSettings(options: {
       select.addEventListener("change", () => { assign(select.value); });
       return select;
     }
+    if (field.type === "list") {
+      let serialized: string;
+      try {
+        serialized = JSON.stringify(value, null, 2) ?? "[]";
+      } catch {
+        serialized = "(value could not be displayed)";
+      }
+      const placeholder = el("textarea", {
+        value: `Nested list editing is unavailable here.\n${serialized}`,
+        rows: 3,
+        disabled: true,
+        readOnly: true,
+        title: "Nested lists cannot be edited in this control",
+      });
+      placeholder.setAttribute("aria-disabled", "true");
+      placeholder.setAttribute("aria-readonly", "true");
+      return placeholder;
+    }
     if (field.type === "textarea") {
       const ta = el("textarea", { value: typeof value === "string" ? value : "", rows: 3 });
       markRequired(ta, field.required);
@@ -197,11 +216,11 @@ export function createExtensionSettings(options: {
       return ta;
     }
     if (field.type === "number") {
-      const input = el("input", { type: "number", value: value === undefined ? "" : String(value) });
+      const input = el("input", { type: "number", value: value === undefined || value === null ? "" : String(value) });
       markRequired(input, field.required);
       if (field.min !== undefined) input.min = String(field.min);
       if (field.max !== undefined) input.max = String(field.max);
-      input.addEventListener("input", () => { assign(input.value === "" ? undefined : Number(input.value)); });
+      input.addEventListener("input", () => { assign(input.value === "" ? undefined : input.valueAsNumber); });
       return input;
     }
     // text
@@ -235,7 +254,7 @@ export function createExtensionSettings(options: {
       if (isRecord(row) && typeof row.__id !== "string") row.__id = newRowId();
     }
     const itemFields = field.itemFields ?? [];
-    const rerender = () => render();
+    const rerender = () => render(true);
     const titleField = itemFields.find((f) => f.type === "text");
     const metaField = itemFields.find((f) => f.type === "select");
     // Resolve the referenced row once, before any edit. The stable id remains
@@ -381,7 +400,7 @@ export function createExtensionSettings(options: {
       const data = await res.json().catch(() => ({}));
       if (res.status === 422 && Array.isArray(data.errors)) {
         errors.set(schema.id, data.errors);
-        render();
+        render(true);
         setStatus(`Fix ${data.errors.length} field${data.errors.length === 1 ? "" : "s"}`, true);
         return;
       }
@@ -393,7 +412,7 @@ export function createExtensionSettings(options: {
           // settings on the response when available, otherwise fetch them.
           if (!applyResponseSettings(data)) await reloadSettingsFromServer();
         } finally {
-          render();
+          render(true);
         }
         setStatus("Changed elsewhere — reloaded latest", true);
         return;
@@ -404,7 +423,7 @@ export function createExtensionSettings(options: {
         // Recreate from the canonical server response (trimmed/coerced values
         // and the new revision) rather than waiting for a broadcast.
         drafts.delete(schema.id);
-        render();
+        render(true);
       }
       setStatus("Saved");
     } catch (error) {
@@ -430,7 +449,7 @@ export function createExtensionSettings(options: {
         try {
           if (!applyResponseSettings(data)) await reloadSettingsFromServer();
         } finally {
-          render();
+          render(true);
         }
         setStatus("Changed elsewhere — reloaded latest", true);
         return;
@@ -439,7 +458,7 @@ export function createExtensionSettings(options: {
       if (!applyResponseSettings(data)) await reloadSettingsFromServer();
       drafts.delete(id);
       errors.delete(id);
-      render();
+      render(true);
       setStatus("Reset");
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
@@ -483,7 +502,7 @@ export function createExtensionSettings(options: {
         group.append(listControl(schema, field, draft, defaultRefByList.get(field.key)));
         section.append(group);
       } else {
-        const ctrl = scalarControl(schema.id, field, draft, draft, () => render());
+        const ctrl = scalarControl(schema.id, field, draft, draft, () => render(true));
         section.append(fieldRow(field.label, ctrl, field.description, errorAt(schema.id, field.key)));
       }
     }
@@ -510,14 +529,22 @@ export function createExtensionSettings(options: {
     return section;
   }
 
-  function render() {
+  function render(force = false) {
     const schemas = state.webSettingsSchemas ?? [];
+    const stored = state.settings.extensions ?? {};
+    // Realtime broadcasts often carry no structural change (for example when
+    // another session registers the same schemas). Preserve the live controls
+    // in that case so an in-progress edit keeps its focus, caret and selection.
+    const structureKey = JSON.stringify({ schemas, ownerIds: Object.keys(stored).sort() });
+    const active = document.activeElement;
+    if (!force && structureKey === lastRenderStructureKey && active && container.contains(active)) return;
+
     const registeredIds = new Set(schemas.map((s) => s.id));
     container.replaceChildren();
+    lastRenderStructureKey = structureKey;
 
     for (const schema of schemas) container.append(renderSchema(schema));
 
-    const stored = state.settings.extensions ?? {};
     for (const [id, rec] of Object.entries(stored)) {
       if (registeredIds.has(id)) continue;
       container.append(renderRetained(id, Object.keys(rec?.values ?? {}).length));
diff --git a/tests/extension-settings.test.ts b/tests/extension-settings.test.ts
index 43cc0c5..291347e 100644
--- a/tests/extension-settings.test.ts
+++ b/tests/extension-settings.test.ts
@@ -119,4 +119,74 @@ describe("extension settings validation", () => {
     );
     expect(tooMany.errors.map((error) => error.path)).toContain("categories");
   });
+
+  it("accepts cleared optional numbers and keeps their persisted round trip stable", () => {
+    const numberSchema: SettingsSchema = {
+      id: "demo-ext.numbers",
+      title: "Numbers",
+      schemaVersion: 1,
+      fields: [
+        { key: "optional", type: "number", label: "Optional" },
+        { key: "withDefault", type: "number", label: "With default", default: 7 },
+      ],
+    };
+
+    for (const empty of [undefined, ""]) {
+      const first = validateSettingsValues(numberSchema, { optional: empty, withDefault: empty });
+      expect(first.errors).toEqual([]);
+      expect(first.values).toEqual({ optional: undefined, withDefault: 7 });
+
+      // Simulate JSON persistence, which omits the unset optional key.
+      const persisted = JSON.parse(JSON.stringify(first.values));
+      const again = validateSettingsValues(numberSchema, persisted);
+      expect(again.errors).toEqual([]);
+      expect(again.values).toEqual(first.values);
+    }
+  });
+
+  it("rejects empty and non-numeric required numbers", () => {
+    const numberSchema: SettingsSchema = {
+      id: "demo-ext.required-number",
+      title: "Required number",
+      schemaVersion: 1,
+      fields: [{ key: "count", type: "number", label: "Count", required: true }],
+    };
+
+    for (const value of [undefined, null, "", "not-a-number"]) {
+      const result = validateSettingsValues(numberSchema, { count: value });
+      expect(result.errors).toContainEqual({ path: "count", message: "Count must be a number" });
+    }
+  });
+
+  it("enforces number minimum and maximum for real numbers", () => {
+    const numberSchema: SettingsSchema = {
+      id: "demo-ext.bounded-number",
+      title: "Bounded number",
+      schemaVersion: 1,
+      fields: [{ key: "count", type: "number", label: "Count", min: 2, max: 5 }],
+    };
+
+    expect(validateSettingsValues(numberSchema, { count: 1 }).errors).toContainEqual({
+      path: "count",
+      message: "Count must be ≥ 2",
+    });
+    expect(validateSettingsValues(numberSchema, { count: 6 }).errors).toContainEqual({
+      path: "count",
+      message: "Count must be ≤ 5",
+    });
+    expect(validateSettingsValues(numberSchema, { count: 3 }).errors).toEqual([]);
+  });
+
+  it("rejects a present list value that is not an array", () => {
+    const result = validateSettingsValues(schema, { categories: "not-an-array", defaultCategory: "" }, { modelOptions: models });
+
+    expect(result.errors).toContainEqual({ path: "categories", message: "Categories must be a list" });
+    expect(result.values.categories).toEqual([]);
+  });
+
+  it("rejects a present list item that is not an object", () => {
+    const result = validateSettingsValues(schema, { categories: ["not-an-object"], defaultCategory: "" }, { modelOptions: models });
+
+    expect(result.errors).toContainEqual({ path: "categories[0]", message: "Categories item must be an object" });
+  });
 });
diff --git a/tests/web-ui-settings.test.ts b/tests/web-ui-settings.test.ts
index 4c48c61..47fa1bf 100644
--- a/tests/web-ui-settings.test.ts
+++ b/tests/web-ui-settings.test.ts
@@ -82,6 +82,29 @@ describe("extension settings registry", () => {
     expect(good.registered).toBe(true);
   });
 
+  it("rejects nested list fields that the client cannot render", async () => {
+    // Removing the server-side nested-list guard makes this registration
+    // succeed and exposes values the client cannot safely edit.
+    const { bridge } = await makeBridge();
+    const result = await register(bridge, makeSession("s1"), schemaFor("demo.x", {
+      fields: [{
+        key: "groups",
+        type: "list",
+        label: "Groups",
+        itemFields: [{
+          key: "members",
+          type: "list",
+          label: "Members",
+          itemFields: [{ key: "name", type: "text", label: "Name" }],
+        }],
+      }],
+    }));
+
+    expect(result.registered).toBe(false);
+    expect(result.error).toMatch(/nested list fields are not supported/);
+    expect(bridge.settingsSchemas()).toHaveLength(0);
+  });
+
   it("migrates once when two sessions register the same schema concurrently", async () => {
     const { bridge, settingsStore } = await makeBridge();
     await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
@@ -128,6 +151,30 @@ describe("extension settings registry", () => {
     expect(bridge.settingsSchemas()).toHaveLength(0);
   });
 
+  it("broadcasts only when the published schema list changes", async () => {
+    // Restoring an unconditional registration/release broadcast increases the
+    // counts below when an equivalent session joins or a non-last one leaves.
+    const { bridge, emitted } = await makeBridge();
+    const first = makeSession("s1");
+    const second = makeSession("s2");
+    const schema = schemaFor("demo.x");
+    const broadcasts = () => emitted.filter((event: any) => event?.type === "web_settings_schemas_changed") as any[];
+
+    await register(bridge, first, schema);
+    expect(broadcasts()).toHaveLength(1);
+    expect(broadcasts()[0].webSettingsSchemas).toHaveLength(1);
+
+    await register(bridge, second, schema);
+    expect(broadcasts()).toHaveLength(1); // identical published descriptor
+
+    bridge.releaseSessionSettings(first);
+    expect(broadcasts()).toHaveLength(1); // second keeps it published
+
+    bridge.releaseSessionSettings(second);
+    expect(broadcasts()).toHaveLength(2);
+    expect(broadcasts()[1].webSettingsSchemas).toHaveLength(0);
+  });
+
   it("notifies every live registrant with its own callback and session id", async () => {
     const { bridge } = await makeBridge();
     const firstChange = vi.fn();
@@ -230,6 +277,87 @@ describe("extension settings registry", () => {
 });
 
 describe("extension settings registry — failure corner cases", () => {
+  it("does not let an in-flight registration overwrite a divergent replacement", async () => {
+    // Removing the pending-release guard changes the canonical winner; restoring
+    // blind stale reattachment too lets both callers succeed while one is invisible.
+    const { bridge } = await makeBridge();
+    const first = makeSession("s1");
+    const joiner = makeSession("s2");
+    const divergent = makeSession("s3");
+    const joinerChange = vi.fn();
+    const divergentChange = vi.fn();
+    const canonical = schemaFor("demo.x", { onChange: joinerChange });
+
+    expect((await register(bridge, first, canonical)).registered).toBe(true);
+    const joining = register(bridge, joiner, canonical); // awaits the settled shared migration
+    bridge.releaseSessionSettings(first);
+    const diverging = register(bridge, divergent, schemaFor("demo.x", {
+      fields: [{ key: "other", type: "toggle", label: "Other" }],
+      onChange: divergentChange,
+    }));
+
+    const [joinResult, divergentResult] = await Promise.all([joining, diverging]);
+    expect(joinResult.registered).toBe(true);
+    expect(divergentResult.registered).toBe(false);
+    expect(divergentResult.error).toMatch(/different schema/);
+    expect(bridge.settingsSchemas()).toHaveLength(1);
+    expect((bridge.settingsSchemas() as any[])[0].fields[0].key).toBe("tier");
+    expect(bridge.settingsSchemaEntry("demo.x")).toBeDefined();
+
+    bridge.notifySettingsChanged("demo.x", { tier: "fast" });
+    expect(joinerChange).toHaveBeenCalledWith({ tier: "fast" }, { sessionId: "s2" });
+    expect(divergentChange).not.toHaveBeenCalled();
+  });
+
+  it("keeps same-schema registrations visible and notifiable across an in-flight release", async () => {
+    // Restoring pending-entry deletion plus blind continuation reattachment makes
+    // one successful same-schema registrant disappear from notifications.
+    const { bridge } = await makeBridge();
+    const first = makeSession("s1");
+    const second = makeSession("s2");
+    const third = makeSession("s3");
+    const secondChange = vi.fn();
+    const thirdChange = vi.fn();
+    const secondSchema = schemaFor("demo.x", { onChange: secondChange });
+    const thirdSchema = schemaFor("demo.x", { onChange: thirdChange });
+
+    expect((await register(bridge, first, secondSchema)).registered).toBe(true);
+    const secondRegistration = register(bridge, second, secondSchema);
+    bridge.releaseSessionSettings(first);
+    const thirdRegistration = register(bridge, third, thirdSchema);
+
+    const [secondResult, thirdResult] = await Promise.all([secondRegistration, thirdRegistration]);
+    expect(secondResult.registered).toBe(true);
+    expect(thirdResult.registered).toBe(true);
+    expect(bridge.settingsSchemas()).toHaveLength(1);
+    expect(bridge.settingsSchemaEntry("demo.x")).toBeDefined();
+
+    bridge.notifySettingsChanged("demo.x", { tier: "fast" });
+    expect(secondChange).toHaveBeenCalledWith({ tier: "fast" }, { sessionId: "s2" });
+    expect(thirdChange).toHaveBeenCalledWith({ tier: "fast" }, { sessionId: "s3" });
+  });
+
+  it("skips a migration write when a concurrent reset changes the revision", async () => {
+    // Removing expectedRevision from migration writes makes the migration
+    // silently recreate and overwrite the record reset inside migrate().
+    const { bridge, settingsStore } = await makeBridge();
+    await settingsStore.patchExtension("demo.x", { tier: "old" }, { schemaVersion: 1, expectedRevision: 0 });
+
+    const result = await register(bridge, makeSession("s1"), schemaFor("demo.x", {
+      schemaVersion: 2,
+      migrate: async () => {
+        await settingsStore.resetExtension("demo.x", 1);
+        return { tier: "migrated" };
+      },
+    }));
+
+    expect(result.registered).toBe(true);
+    expect(result.migrated).toBe(false);
+    expect(result.usedBackup).toBe(false);
+    expect(result.error).toMatch(/migration skipped.*changed concurrently/i);
+    expect((await settingsStore.read()).extensions?.["demo.x"]).toBeUndefined();
+  });
+
   it("keeps the owner id usable after a migration write fails", async () => {
     // Regression: the migration promise is shared by every registration of an
     // id, so a rejected store write used to poison that id until restart.

From b1594a9e9430ee38292e6b8486a8bd1c173aa06d Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 12:04:50 +0000
Subject: [PATCH 09/10] fix: wakeup durability, region residency, and
 fail-closed categories
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the cold review.

Wakeup durability. Re-arming watches from the ledger treated ANY error while
checking a child as "the child is gone", resolved the ledger entry and ended the
watch — permanently, with no wakeup and no message to the parent. But that check
runs exactly when the server is restarting or loaded, and the API client has a
20-second timeout, so an ordinary timeout or 5xx silently destroyed the durability
the skill advertises. Only a definitive 404 now resolves the entry; timeouts,
network failures and 5xx hand the child to the normal paced poll loop, which keeps
its existing error threshold and still delivers a "lost track" wakeup rather than
going quiet.

Region residency. The Bedrock inference-profile fallback stripped an existing
region prefix from the configured model id and substituted the parent's, so a
category deliberately pinned to eu.* could be silently retargeted to us.* — a
data-residency change the user never asked for, reported to the model only as "a
region prefix was substituted". A parent prefix is now only ADDED to an
unprefixed id; an explicit region is never replaced, and the spawn fails closed
instead.

Fail-closed categories. An explicitly requested category was silently ignored in
two paths — when the settings API was unavailable, and when no categories were
configured (where the name was overwritten with "Default") — contradicting the
documented "unknown category, nothing created". An explicit category that cannot
be resolved now errors and creates nothing; only an omitted category may fall back
to the session default.

Spawn cap. The worker cap was checked before several awaits, so parallel tool
calls could exceed it. Slots are now reserved synchronously and released in a
finally. The cap counts spawned workers only, not sessions attached via
sessions_prompt; the refusal message and skill state this.

Hygiene: the [ext vN] development marker is gone from anything the model sees (it
remains in developer logs), and the file header's install paths now match the
documented ones.

Reverting the durability guard or the region guard fails their tests (verified by
mutation).
---
 .../pi-web-extensions/session-orchestrator.ts | 229 ++++++++++--------
 .../session-orchestration/SKILL.md            |   4 +-
 tests/session-orchestrator.test.ts            | 146 ++++++++++-
 3 files changed, 277 insertions(+), 102 deletions(-)

diff --git a/examples/pi-web-extensions/session-orchestrator.ts b/examples/pi-web-extensions/session-orchestrator.ts
index 033e48b..22c7a20 100644
--- a/examples/pi-web-extensions/session-orchestrator.ts
+++ b/examples/pi-web-extensions/session-orchestrator.ts
@@ -13,9 +13,9 @@
  *
  * Everything goes through the same local HTTP API the web UI uses.
  *
- * Reversible install: this lives in .pi/extensions/session-orchestrator/ —
- * delete that directory (and .pi/skills/session-orchestration/) to remove the
- * feature entirely. No AGENTS.md or server changes.
+ * Reversible install: this lives at .pi/web/extensions/session-orchestrator.ts —
+ * delete that file (and ~/.pi/agent/skills/session-orchestration/) to remove
+ * the feature entirely. No AGENTS.md or server changes.
  */
 
 import { Type } from "typebox";
@@ -103,10 +103,12 @@ export function resolveModel(
   const exact = registryModels.find((m: any) => m.provider === provider && m.id === id);
   if (exact) return { match: exact, substituted: false };
 
-  // 2. Same provider + same normalized base id + parent region prefix (Bedrock case).
-  if (parentRegionPrefix) {
-    const baseId = normalizeBedrockId(id);
-    const withPrefix = parentRegionPrefix + baseId.slice(baseId.match(/^(us|eu|au|apac|global)\./)  ?.[0]?.length || 0);
+  // 2. For an unprefixed configured id only, add the parent's region prefix
+  // (Bedrock inference-profile case). An explicit configured region is a
+  // residency choice and must never be silently replaced with another one.
+  const baseId = normalizeBedrockId(id);
+  if (parentRegionPrefix && !/^(us|eu|au|apac|global)\./.test(baseId)) {
+    const withPrefix = parentRegionPrefix + baseId;
     const candidate = registryModels.find(
       (m: any) => m.provider === provider && normalizeBedrockId(m.id) === normalizeBedrockId(withPrefix),
     );
@@ -121,6 +123,13 @@ export function resolveModel(
 // Small HTTP client for the pi-web API (same API the browser UI uses)
 // ---------------------------------------------------------------------------
 
+class ApiError extends Error {
+  constructor(message: string, readonly status: number) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
 async function api(method: string, path: string, body?: unknown): Promise<any> {
   const res = await fetch(`${BASE}${path}`, {
     method,
@@ -133,7 +142,7 @@ async function api(method: string, path: string, body?: unknown): Promise<any> {
   });
   const json = await res.json().catch(() => ({}));
   if (!res.ok || json?.ok === false) {
-    throw new Error(`${method} ${path} failed (${res.status}): ${json?.error || "unknown error"}`);
+    throw new ApiError(`${method} ${path} failed (${res.status}): ${json?.error || "unknown error"}`, res.status);
   }
   return json;
 }
@@ -216,6 +225,10 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
   };
 
   const watched = new Map<string, Watched>();
+  // The spawn cap applies only to workers created by sessions_spawn. Sessions
+  // added to the watcher by sessions_prompt do not consume spawn capacity.
+  const spawnedWorkers = new Set<string>();
+  let reservedSpawnSlots = 0;
   let cachedConfig: { categories: any[]; defaultCategory: string } = { categories: [], defaultCategory: "" };
   let timer: ReturnType<typeof setInterval> | undefined;
   let pollInFlight = false;
@@ -296,12 +309,13 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
 
   function unwatch(id: string) {
     watched.delete(id);
+    spawnedWorkers.delete(id);
     stopTimerIfIdle();
   }
 
-  function appendLedger(customType: string, childId: string, name?: string, categoryName?: string) {
+  function appendLedger(customType: string, childId: string, name?: string, categoryName?: string, spawned?: boolean) {
     try {
-      pi.appendEntry(customType, { childId, ...(name ? { name } : {}), ...(categoryName ? { categoryName } : {}) });
+      pi.appendEntry(customType, { childId, ...(name ? { name } : {}), ...(categoryName ? { categoryName } : {}), ...(spawned !== undefined ? { spawned } : {}) });
     } catch (error) {
       console.error(`[session-orchestrator] could not append ${customType} entry: ${error instanceof Error ? error.message : error}`);
     }
@@ -328,8 +342,8 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
       : `Session ${sessionId} could not be deleted and may remain — please remove it.`;
   }
 
-  function outstandingWatches(ctx: any): Map<string, { name: string; categoryName: string }> {
-    const watches = new Map<string, { name: string; categoryName: string }>();
+  function outstandingWatches(ctx: any): Map<string, { name: string; categoryName: string; spawned: boolean }> {
+    const watches = new Map<string, { name: string; categoryName: string; spawned: boolean }>();
     try {
       for (const entry of ctx.sessionManager?.getBranch?.() || []) {
         if (entry?.type !== "custom") continue;
@@ -339,6 +353,9 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           watches.set(childId, {
             name: typeof entry.data?.name === "string" ? entry.data.name : childId.slice(-8),
             categoryName: typeof entry.data?.categoryName === "string" ? entry.data.categoryName : "Unknown",
+            // Legacy entries did not distinguish spawn from prompt watches;
+            // count them conservatively until a new typed entry is written.
+            spawned: typeof entry.data?.spawned === "boolean" ? entry.data.spawned : true,
           });
         }
         else if (entry.customType === RESOLVED_ENTRY) watches.delete(childId);
@@ -422,14 +439,19 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
             details: {},
           };
         }
-        if (watched.size >= MAX_WORKERS) {
+        const spawnSlotsInUse = spawnedWorkers.size + reservedSpawnSlots;
+        if (spawnSlotsInUse >= MAX_WORKERS) {
           return {
-            content: [{ type: "text", text: `Refused: already tracking ${watched.size} running workers (cap ${MAX_WORKERS}). Wait for a wakeup or abort one first.` }],
+            content: [{ type: "text", text: `Refused: already running or starting ${spawnSlotsInUse} spawned workers (spawn cap ${MAX_WORKERS}; sessions watched after sessions_prompt do not count). Wait for a wakeup or abort one first.` }],
             isError: true,
             details: {},
           };
         }
 
+        // Reserve synchronously, before category/settings/API awaits, so
+        // concurrent tool calls cannot all pass the cap check.
+        reservedSpawnSlots += 1;
+        try {
         const parentId = ownSessionId(ctx);
         const parentCwd = ownCwd(ctx);
 
@@ -438,94 +460,84 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
         // ====================================================================
 
         let resolvedToken: { provider: string; id: string } | null = null;
-        let categoryName = params.category || "";
+        const explicitCategory = typeof params.category === "string" && params.category.trim().length > 0;
+        let categoryName = explicitCategory ? params.category.trim() : "";
         let validCategories: string[] = [];
 
         try {
           const web = ctx?.ui?.web;
-          if (web?.getSettings) {
-            const settings = await web.getSettings(SETTINGS_ID);
-            if (settings && typeof settings === "object") {
-              const values = settings.values || {};
-              cachedConfig = { categories: Array.isArray(values.categories) ? values.categories : [], defaultCategory: String(values.defaultCategory || "") };
-              const categories = Array.isArray(values.categories) ? values.categories : [];
-              const defaultCategory = String(values.defaultCategory || "");
-
-              // Empty config → virtual Default, skip resolution, use session default.
-              if (categories.length === 0) {
-                resolvedToken = null; // Signals: use session default
-                categoryName = "Default";
-                validCategories = [categoryName];
-              } else {
-                // Collect valid names.
-                for (const cat of categories) {
-                  if (cat && typeof cat === "object" && cat.name) {
-                    validCategories.push(String(cat.name));
-                  }
-                }
-
-                // Resolve category name.
-                if (!categoryName) {
-                  categoryName = defaultCategory;
-                }
-
-                if (!categoryName) {
-                  return {
-                    content: [
-                      {
-                        type: "text",
-                        text: `ERROR: category omitted and no default is configured. Valid categories: ${validCategories.join(", ") || "(none configured)"}. Set a default in extension settings or pass an explicit category name.`,
-                      },
-                    ],
-                    isError: true,
-                    details: { validCategories },
-                  };
-                }
-
-                // Find matching category.
-                const matching = categories.find(
-                  (cat: any) => cat && typeof cat === "object" && cat.name && String(cat.name).toLowerCase() === String(categoryName).toLowerCase(),
-                );
-                if (!matching || !matching.model) {
-                  return {
-                    content: [
-                      {
-                        type: "text",
-                        text: `ERROR: category "${categoryName}" not found or has no model configured. Valid categories: ${validCategories.join(", ") || "(none configured)"}`,
-                      },
-                    ],
-                    isError: true,
-                    details: { validCategories, categoryName },
-                  };
-                }
-
-                resolvedToken = parseToken(String(matching.model));
-                if (!resolvedToken) {
-                  return {
-                    content: [
-                      {
-                        type: "text",
-                        text: `ERROR: the model configured for category "${categoryName}" is malformed. Check extension settings. Valid categories: ${validCategories.join(", ") || "(none configured)"}`,
-                      },
-                    ],
-                    isError: true,
-                    details: { validCategories },
-                  };
-                }
+          const settings = web?.getSettings ? await web.getSettings(SETTINGS_ID) : null;
+          if (settings && typeof settings === "object") {
+            const values = settings.values || {};
+            cachedConfig = { categories: Array.isArray(values.categories) ? values.categories : [], defaultCategory: String(values.defaultCategory || "") };
+            const categories = Array.isArray(values.categories) ? values.categories : [];
+            const defaultCategory = String(values.defaultCategory || "");
+
+            for (const cat of categories) {
+              if (cat && typeof cat === "object" && cat.name) validCategories.push(String(cat.name));
+            }
+
+            // An explicit category must resolve even when the configured list
+            // is empty. Only an omitted category gets the virtual Default.
+            if (categories.length === 0) {
+              if (explicitCategory) {
+                return {
+                  content: [{ type: "text", text: `ERROR: category "${categoryName}" not found. Valid categories: (none configured)` }],
+                  isError: true,
+                  details: { validCategories, categoryName },
+                };
+              }
+              categoryName = "Default";
+            } else {
+              if (!categoryName) categoryName = defaultCategory;
+              if (!categoryName) {
+                return {
+                  content: [{ type: "text", text: `ERROR: category omitted and no default is configured. Valid categories: ${validCategories.join(", ") || "(none configured)"}. Set a default in extension settings or pass an explicit category name.` }],
+                  isError: true,
+                  details: { validCategories },
+                };
+              }
+
+              const matching = categories.find(
+                (cat: any) => cat && typeof cat === "object" && cat.name && String(cat.name).toLowerCase() === String(categoryName).toLowerCase(),
+              );
+              if (!matching || !matching.model) {
+                return {
+                  content: [{ type: "text", text: `ERROR: category "${categoryName}" not found or has no model configured. Valid categories: ${validCategories.join(", ") || "(none configured)"}` }],
+                  isError: true,
+                  details: { validCategories, categoryName },
+                };
+              }
+
+              resolvedToken = parseToken(String(matching.model));
+              if (!resolvedToken) {
+                return {
+                  content: [{ type: "text", text: `ERROR: the model configured for category "${categoryName}" is malformed. Check extension settings. Valid categories: ${validCategories.join(", ") || "(none configured)"}` }],
+                  isError: true,
+                  details: { validCategories },
+                };
               }
             }
+          } else if (explicitCategory) {
+            return {
+              content: [{ type: "text", text: `ERROR: category "${categoryName}" cannot be resolved because category settings are unavailable. Valid categories: (none configured)` }],
+              isError: true,
+              details: { validCategories, categoryName },
+            };
+          } else {
+            categoryName = "Default";
           }
         } catch (error) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `ERROR: failed to read category config: ${error instanceof Error ? error.message : error}. Categories unavailable; please check extension settings.`,
-              },
-            ],
-            isError: true,
-            details: {},
-          };
+          if (explicitCategory) {
+            return {
+              content: [{ type: "text", text: `ERROR: failed to read category config: ${error instanceof Error ? error.message : error}. Category "${categoryName}" cannot be resolved; valid categories are unavailable.` }],
+              isError: true,
+              details: { validCategories, categoryName },
+            };
+          }
+          // With no explicit category, an unreadable settings API may safely
+          // fall back to the new session's default model.
+          categoryName = "Default";
         }
 
         // ====================================================================
@@ -643,14 +655,15 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           };
         }
 
+        spawnedWorkers.add(sessionId);
         watch(sessionId, params.name, categoryName || "Default");
-        appendLedger(WATCH_ENTRY, sessionId, params.name, categoryName || "Default");
+        appendLedger(WATCH_ENTRY, sessionId, params.name, categoryName || "Default", true);
 
         return {
           content: [
             {
               type: "text",
-              text: `Spawned worker "${params.name}" (session ${sessionId}, category "${categoryName || "Default"}") [ext ${EXT_VERSION}]. It is running in the background as a normal pi-web session named "${displayName}".${regionSubstituted ? " A region prefix was substituted." : ""} You'll receive a 🔔 wakeup message when it goes idle — do not poll. Continue other work, spawn more workers, or end your turn to wait.`,
+              text: `Spawned worker "${params.name}" (session ${sessionId}, category "${categoryName || "Default"}"). It is running in the background as a normal pi-web session named "${displayName}".${regionSubstituted ? " A region prefix was substituted." : ""} You'll receive a 🔔 wakeup message when it goes idle — do not poll. Continue other work, spawn more workers, or end your turn to wait.`,
             },
           ],
           details: {
@@ -662,6 +675,9 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
             regionSubstituted,
           } as Record<string, unknown>,
         };
+        } finally {
+          reservedSpawnSlots -= 1;
+        }
       },
     };
   }
@@ -716,6 +732,9 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
     const outstanding = outstandingWatches(ctx);
     for (const id of watched.keys()) outstanding.delete(id);
     if (outstanding.size === 0) return;
+    for (const [id, worker] of outstanding) {
+      if (worker.spawned) spawnedWorkers.add(id);
+    }
 
     const finished: { id: string; name: string; categoryName: string; summary: { text: string; isError: boolean } }[] = [];
     for (const [childId, worker] of outstanding) {
@@ -738,10 +757,18 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           // Transcript fetch is best effort.
         }
         finished.push({ id: childId, name: worker.name, categoryName: worker.categoryName, summary });
-      } catch {
+      } catch (error) {
         if (!isActive(expectedGeneration)) return;
-        // Child gone (deleted?) — resolve so we don't retry forever.
-        appendLedger(RESOLVED_ENTRY, childId);
+        if (error instanceof ApiError && error.status === 404) {
+          // A definitive not-found means the child is genuinely gone.
+          spawnedWorkers.delete(childId);
+          appendLedger(RESOLVED_ENTRY, childId);
+        } else {
+          // Timeouts, network failures, and 5xx responses are transient. Hand
+          // the outstanding ledger entry to the normal paced poller, which
+          // retries and eventually emits its existing "lost track" wakeup.
+          watch(childId, worker.name, worker.categoryName);
+        }
       }
     }
     if (!isActive(expectedGeneration) || finished.length === 0) return;
@@ -768,6 +795,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
     if (!isActive(expectedGeneration)) return;
     if (ok) {
       for (const f of finished) {
+        spawnedWorkers.delete(f.id);
         appendLedger(RESOLVED_ENTRY, f.id);
         markChildRead(f.id);
       }
@@ -1015,7 +1043,7 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
           name = String(state?.sessionName || state?.sessionTitle || name).replace(/^[⑂⤑]\s*/, "");
         } catch { /* best effort */ }
         watch(params.id, name);
-        appendLedger(WATCH_ENTRY, params.id, name);
+        appendLedger(WATCH_ENTRY, params.id, name, undefined, false);
       }
       return { content: [{ type: "text", text: `${params.interrupt ? "Interrupted and redirected" : "Message delivered to"} session ${params.id}. You'll get a 🔔 wakeup when it goes idle.` }], details: {} };
     },
@@ -1049,5 +1077,6 @@ export default function sessionOrchestrator(pi: PiWebExtensionAPI) {
     if (timer) clearInterval(timer);
     timer = undefined;
     watched.clear();
+    spawnedWorkers.clear();
   });
 }
diff --git a/examples/pi-web-skills/session-orchestration/SKILL.md b/examples/pi-web-skills/session-orchestration/SKILL.md
index 5184177..9556a11 100644
--- a/examples/pi-web-skills/session-orchestration/SKILL.md
+++ b/examples/pi-web-skills/session-orchestration/SKILL.md
@@ -94,7 +94,9 @@ yourself.
 ## Etiquette and limits
 
 - Depth cap: workers must not spawn sub-workers (`sessions_spawn` refuses).
-- At most 4 tracked workers at once; prefer 2–3 focused workers over a swarm.
+- At most 4 workers spawned by `sessions_spawn` may be running/tracked at once;
+  sessions merely watched after `sessions_prompt` do not consume spawn slots.
+  Prefer 2–3 focused workers over a swarm.
 - The user sees every worker in the sidebar and may type into one directly —
   that's fine and expected. Their instructions to a worker take precedence.
 - In your reply to the user after spawning, say which workers you started and
diff --git a/tests/session-orchestrator.test.ts b/tests/session-orchestrator.test.ts
index 444729c..0911737 100644
--- a/tests/session-orchestrator.test.ts
+++ b/tests/session-orchestrator.test.ts
@@ -48,6 +48,10 @@ describe("resolveModel", () => {
     expect(resolveModel("amazon-bedrock:anthropic.claude-x-v1:0", registry, "")).toBeNull();
   });
 
+  it("never replaces an explicit configured region prefix", () => {
+    expect(resolveModel("amazon-bedrock:eu.anthropic.claude-x-v1:0", registry, "us.")).toBeNull();
+  });
+
   it("never picks an arbitrary candidate from another provider", () => {
     expect(resolveModel("openai:missing-1", registry, "us.")).toBeNull();
   });
@@ -313,6 +317,13 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(visibleResult).not.toContain("smart-1");
   });
 
+  it("does not expose an extension version marker in spawn result text or details", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    const result = await spawn(ctx, { name: "scout", task: "look around" });
+
+    expect(`${resultText(result)}\n${JSON.stringify(result.details)}`).not.toMatch(/\[ext\s/i);
+  });
+
   it("reports status by category without exposing the concrete model id", async () => {
     const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
     await spawn(ctx, { name: "scout", task: "look around", category: "Fast" });
@@ -341,6 +352,27 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(calls).toHaveLength(0); // nothing created, nothing dispatched
   });
 
+  it("rejects an explicit category when the category config is empty", async () => {
+    const ctx = makeCtx();
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Ghost" });
+
+    expect(result.isError).toBe(true);
+    expect(resultText(result)).toMatch(/none configured/i);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("rejects an explicit category when getSettings is unavailable", async () => {
+    const ctx = makeCtx();
+    delete (ctx.ui.web as any).getSettings;
+    await activate(ctx);
+
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "Ghost" });
+
+    expect(result.isError).toBe(true);
+    expect(resultText(result)).toMatch(/settings are unavailable/i);
+    expect(calls).toHaveLength(0);
+  });
+
   it("errors without creating a session when no default is configured", async () => {
     const ctx = makeCtx({ categories: [FAST] });
     const result = await spawn(ctx, { name: "scout", task: "look around" });
@@ -378,7 +410,7 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(result.details.cleanedUp).toBe(false);
   });
 
-  it("reports a region-prefix substitution instead of silently swapping models", async () => {
+  it("adds the parent's region prefix to an unprefixed configured model", async () => {
     stubFetch({ models: [{ provider: "amazon-bedrock", id: "us.anthropic.claude-x-v1:0" }], parentModelId: "us.anthropic.other-v1:0" });
     const category = { name: "Bedrock", model: "amazon-bedrock:anthropic.claude-x-v1:0", description: "Region-prefixed profile." };
     const ctx = makeCtx({ categories: [category], defaultCategory: "Bedrock", parentModelId: "us.anthropic.other-v1:0" });
@@ -390,6 +422,19 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(resultText(result)).toMatch(/substituted/i);
   });
 
+  it("fails closed rather than replacing an explicit configured region", async () => {
+    stubFetch({ models: [{ provider: "amazon-bedrock", id: "us.anthropic.claude-x-v1:0" }], parentModelId: "us.anthropic.other-v1:0" });
+    const category = { name: "EU", model: "amazon-bedrock:eu.anthropic.claude-x-v1:0", description: "EU residency." };
+    const ctx = makeCtx({ categories: [category], defaultCategory: "EU" });
+
+    const result = await spawn(ctx, { name: "scout", task: "look around", category: "EU" });
+
+    expect(result.isError).toBe(true);
+    expect(pathsFor("POST")).not.toContain("/api/model");
+    expect(pathsFor("POST")).not.toContain("/api/prompt");
+    expect(pathsFor("POST")).toContain("/api/sessions/delete");
+  });
+
   it("leaves the worker on the session default when no categories are configured", async () => {
     const ctx = makeCtx();
     const result = await spawn(ctx, { name: "scout", task: "look around" });
@@ -468,9 +513,108 @@ describe("sessions_spawn fail-closed resolution", () => {
     expect(overflow.isError).toBe(true);
     expect(resultText(overflow)).toMatch(/cap/i);
   });
+
+  it("reserves spawn slots before awaits so concurrent calls cannot exceed the cap", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await activate(ctx);
+    const tool = tools.get("sessions_spawn");
+
+    const results = await Promise.all(Array.from({ length: 6 }, (_, index) =>
+      tool.execute(`call-${index}`, { name: `worker-${index}`, task: "work" }, undefined, undefined, ctx),
+    ));
+
+    expect(results.filter((result) => !result.isError)).toHaveLength(4);
+    expect(results.filter((result) => result.isError)).toHaveLength(2);
+    expect(calls.filter((call) => call.path === "/api/new-chat")).toHaveLength(4);
+  });
+
+  it("does not charge sessions_prompt watches against the spawn cap", async () => {
+    const ctx = makeCtx({ categories: [FAST], defaultCategory: "Fast" });
+    await activate(ctx);
+    for (let i = 0; i < 4; i += 1) {
+      await tools.get("sessions_prompt").execute("prompt", { id: `existing-${i}`, message: "continue" });
+    }
+
+    const result = await spawn(ctx, { name: "new worker", task: "work" });
+
+    expect(result.isError).toBeFalsy();
+    expect(pathsFor("POST")).toContain("/api/new-chat");
+  });
 });
 
 describe("watcher lifecycle and wakeup retries", () => {
+  it("keeps a ledger watch after a transient re-arm failure and later delivers its wakeup", async () => {
+    vi.useFakeTimers();
+    const pi = makeExtension();
+    let stateCalls = 0;
+    globalThis.fetch = (async (url: any, init: any = {}) => {
+      const method = String(init.method || "GET");
+      const path = String(url).replace(/^https?:\/\/[^/]+/, "");
+      calls.push({ method, path, body: init.body ? JSON.parse(init.body) : undefined });
+      if (path === "/api/state?sessionId=ledger-worker") {
+        stateCalls += 1;
+        if (stateCalls === 1) {
+          return { ok: false, status: 503, json: async () => ({ ok: false, error: "restarting" }) } as any;
+        }
+        return { ok: true, status: 200, json: async () => ({ ok: true, runtime: { isRunning: false, pendingMessageCount: 0 } }) } as any;
+      }
+      if (path === "/api/messages?sessionId=ledger-worker") {
+        return { ok: true, status: 200, json: async () => ({ ok: true, messages: [{ role: "assistant", text: "finished after restart" }] }) } as any;
+      }
+      return { ok: true, status: 200, json: async () => ({ ok: true }) } as any;
+    }) as any;
+
+    const ctx = makeCtx();
+    ctx.sessionManager.getBranch = () => [{
+      type: "custom",
+      customType: "orchestrator-watch",
+      data: { childId: "ledger-worker", name: "ledger worker", categoryName: "Fast", spawned: true },
+    }];
+    await handlers.get("session_start")?.({}, ctx);
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(pi.appendEntry).not.toHaveBeenCalledWith("orchestrator-watch-resolved", expect.anything());
+    const statusBefore = await tools.get("sessions_status").execute("status", {});
+    expect(resultText(statusBefore)).toContain("ledger-worker");
+
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+    expect(String(pi.sendMessage.mock.calls[0][0].content)).toContain("finished after restart");
+    expect(pi.appendEntry).toHaveBeenCalledWith("orchestrator-watch-resolved", { childId: "ledger-worker" });
+    expect(stateCalls).toBe(6); // re-arm failure + status check + four settled polls
+  });
+
+  it("resolves a ledger watch after a definitive not-found without polling forever", async () => {
+    vi.useFakeTimers();
+    const pi = makeExtension();
+    let stateCalls = 0;
+    globalThis.fetch = (async (url: any, init: any = {}) => {
+      const method = String(init.method || "GET");
+      const path = String(url).replace(/^https?:\/\/[^/]+/, "");
+      calls.push({ method, path, body: init.body ? JSON.parse(init.body) : undefined });
+      if (path === "/api/state?sessionId=missing-worker") {
+        stateCalls += 1;
+        return { ok: false, status: 404, json: async () => ({ ok: false, error: "session not found" }) } as any;
+      }
+      return { ok: true, status: 200, json: async () => ({ ok: true }) } as any;
+    }) as any;
+
+    const ctx = makeCtx();
+    ctx.sessionManager.getBranch = () => [{
+      type: "custom",
+      customType: "orchestrator-watch",
+      data: { childId: "missing-worker", name: "missing worker", categoryName: "Fast", spawned: true },
+    }];
+    await handlers.get("session_start")?.({}, ctx);
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(pi.appendEntry).toHaveBeenCalledWith("orchestrator-watch-resolved", { childId: "missing-worker" });
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(stateCalls).toBe(1);
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+  });
+
   it("does not re-arm polling when a pending ledger re-arm finishes after shutdown", async () => {
     vi.useFakeTimers();
     let resolveState!: (response: any) => void;

From b9aa50eb762fe2f399be6ae9f4002706969bf045 Mon Sep 17 00:00:00 2001
From: ashwin pc <ashwinpc@amazon.com>
Date: Sat, 1 Aug 2026 13:29:20 +0000
Subject: [PATCH 10/10] feat: open spawned sessions from a strip above the
 composer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

While a session waits on sessions it spawned, those sessions are now listed as
links directly above the composer, so a worker can be opened while it is still
working. Previously the waiting indicator named the workers as plain text inside
the context-meter button, which could not link anywhere — and putting links there
would have nested interactive content inside a button.

Every session link in the UI now switches session in place. The chips on wakeup
cards and tool cards were plain anchors, so clicking one triggered a full document
navigation: a complete app restart that refetched state, models and the whole
transcript. Opening a session server-side takes about two milliseconds, so all of
that latency was the reload. Chip construction is now one factory shared by the
wakeup cards, the tool cards and the new strip: a plain left click switches via
the same path the session tabs use, while modified and middle clicks still open a
new tab and the real href keeps keyboard access and "copy link" intact.

Spawned sessions are identified by name rather than an id fragment. Names arrived
for sessions that were not yet in the cached list — a worker is named immediately
after it is created, before any list refresh — and updateSessionName discarded
them, so links fell back to the last eight characters of the id. Names are now
remembered regardless of list membership, and discovering a new session schedules
a coalesced list refresh.

The strip keeps the existing precedence: it appears only while the session itself
is idle, because a running session shows its own progress instead. It occupies no
space when there is nothing to wait for, scrolls horizontally rather than wrapping,
and each entry carries a pulsing dot to show the worker is still going.

waitingInfoFrom is pure and tested (which children count, self-running
precedence, and the id fallback when a name is genuinely unknown).
---
 index.html                    |  1 +
 src/app/elements.ts           |  2 +
 src/app/sessionRefs.ts        | 30 ++++++++++++++
 src/main.ts                   |  5 ++-
 src/messages/messageList.ts   | 13 +++----
 src/sessions/lineage.ts       | 30 ++++++++++++++
 src/sessions/sessionDrawer.ts | 60 +++++++++++++++++++++++-----
 src/status/statusBar.ts       | 59 ++++++++++++++++++++--------
 src/styles/base.css           | 10 +----
 src/styles/composer.css       | 73 +++++++++++++++++++++++++++++++----
 src/tools/toolCards.ts        | 14 +++----
 tests/session-lineage.test.ts | 52 ++++++++++++++++++++++++-
 12 files changed, 289 insertions(+), 60 deletions(-)

diff --git a/index.html b/index.html
index 198650f..cd67131 100644
--- a/index.html
+++ b/index.html
@@ -341,6 +341,7 @@ <h3>Token sharing</h3>
       </aside>
 
       <section id="pendingMessages" class="pendingMessages" aria-label="Pending messages" aria-live="polite" hidden></section>
+      <section id="waitingSessions" class="waitingSessions" aria-label="Running spawned sessions" aria-live="polite" hidden></section>
       <form id="promptForm" class="composer">
         <button id="contextMeter" class="contextMeter unknown" type="button" aria-haspopup="dialog" aria-expanded="false" aria-controls="contextMeterPopover" title="Context usage unavailable">
           <span class="contextMeterTrack" aria-hidden="true"><span id="contextMeterFill" class="contextMeterFill"></span></span>
diff --git a/src/app/elements.ts b/src/app/elements.ts
index c345192..04465ce 100644
--- a/src/app/elements.ts
+++ b/src/app/elements.ts
@@ -80,6 +80,7 @@ export type AppElements = {
   extensionStatusMessage: HTMLParagraphElement;
   extensionStatusDetails: HTMLDivElement;
   extensionReloadButton: HTMLButtonElement;
+  waitingSessionsEl: HTMLElement;
   settingsStatusEl: HTMLSpanElement;
   extensionSettingsContainer: HTMLElement;
   tokenShareSection: HTMLElement;
@@ -185,6 +186,7 @@ export function getAppElements(): AppElements {
     extensionStatusMessage: requiredElement<HTMLParagraphElement>("#extensionStatusMessage"),
     extensionStatusDetails: requiredElement<HTMLDivElement>("#extensionStatusDetails"),
     extensionReloadButton: requiredElement<HTMLButtonElement>("#extensionReloadButton"),
+    waitingSessionsEl: requiredElement<HTMLElement>("#waitingSessions"),
     settingsStatusEl: requiredElement<HTMLSpanElement>("#settingsStatus"),
     extensionSettingsContainer: requiredElement<HTMLElement>("#extensionSettingsContainer"),
     tokenShareSection: requiredElement<HTMLElement>("#tokenShareSection"),
diff --git a/src/app/sessionRefs.ts b/src/app/sessionRefs.ts
index 0d8b6e6..aba0819 100644
--- a/src/app/sessionRefs.ts
+++ b/src/app/sessionRefs.ts
@@ -70,3 +70,33 @@ export function sessionRefChipClass(ref: SessionRef): string {
 export function sessionRefHref(ref: SessionRef): string {
   return `/?sessionId=${encodeURIComponent(ref.sessionId)}`;
 }
+
+/**
+ * Build a chip linking to a referenced session.
+ *
+ * The chip is a real anchor, so middle-click / cmd-click / "open in new tab" and
+ * keyboard activation all behave normally. When an in-app opener is supplied, a
+ * plain left click switches session in place instead of reloading the whole app —
+ * a full document navigation costs a complete app restart (state, models and
+ * transcript refetch) for what should be an instant switch.
+ */
+export function createSessionRefChip(
+  ref: SessionRef,
+  options: { className?: string; openSession?: (sessionId: string) => void } = {},
+): HTMLAnchorElement {
+  const chip = document.createElement("a");
+  chip.className = options.className ?? sessionRefChipClass(ref);
+  chip.href = sessionRefHref(ref);
+  chip.textContent = sessionRefChipText(ref);
+  chip.title = `Open session ${ref.sessionId}`;
+  const { openSession } = options;
+  if (openSession) {
+    chip.addEventListener("click", (event) => {
+      // Leave modified clicks and non-primary buttons to the browser.
+      if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0) return;
+      event.preventDefault();
+      openSession(ref.sessionId);
+    });
+  }
+  return chip;
+}
diff --git a/src/main.ts b/src/main.ts
index af35042..c234cc5 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -136,8 +136,8 @@ async function handleMessageAction(context: MessageActionContext) {
   }
 }
 
-messages = createMessageList({ messagesEl: elements.messagesEl, markdown, onMessageAction: handleMessageAction });
-const tools = createToolCards(elements.messagesEl, messages.scrollToBottom, api.headers);
+messages = createMessageList({ messagesEl: elements.messagesEl, markdown, onMessageAction: handleMessageAction, openSession: (sessionId) => void sessions.openSessionById(sessionId) });
+const tools = createToolCards(elements.messagesEl, messages.scrollToBottom, api.headers, (sessionId) => void sessions.openSessionById(sessionId));
 
 const webHeaderActions = createWebHeaderActions({
   container: elements.headerActionsEl,
@@ -429,6 +429,7 @@ statusBar = createStatusBar({
   sessionState,
   addMessage: messages.addMessage,
   refreshSessions: () => sessions.refreshSessions(),
+  openSession: (sessionId, cwd) => sessions.openSessionTab(sessionId, cwd),
   refreshState,
 });
 
diff --git a/src/messages/messageList.ts b/src/messages/messageList.ts
index 483e56d..4eac42c 100644
--- a/src/messages/messageList.ts
+++ b/src/messages/messageList.ts
@@ -6,7 +6,7 @@ import { attachImageActions } from "../components/imageActions.js";
 import type { MarkdownRenderer } from "../markdown/render.js";
 import { assistantErrorBody, cleanThinkingText, imageFileName, imagesFromRawContent, isRetryableAssistantError, messageText, normalizeAssistantError, shouldCollapseMessage, stripImagePathNote, thinkingTextSegments } from "./content.js";
 import { playToolCardEntry, playToolCardStateTransition } from "./entryAnimation.js";
-import { sessionRefChipClass, sessionRefChipText, sessionRefHref, sessionRefsFromDetails } from "../app/sessionRefs.js";
+import { createSessionRefChip, sessionRefsFromDetails } from "../app/sessionRefs.js";
 
 export type AddToolHistoryCard = (toolName: string, isError: boolean, result: unknown, args?: Record<string, unknown>) => void;
 export type AddPendingToolCard = (toolCallId: string | undefined, toolName: string, args: Record<string, unknown>, startedAt?: string | number | Date) => void;
@@ -244,11 +244,13 @@ function transcriptRuntimeState(messages: any[], isStreaming?: boolean): Transcr
 }
 
 export function createMessageList(options: {
+  /** Switch to a referenced session in place instead of reloading the app. */
+  openSession?: (sessionId: string) => void;
   messagesEl: HTMLDivElement;
   markdown: MarkdownRenderer;
   onMessageAction?: (context: MessageActionContext) => void | Promise<void>;
 }): MessageList {
-  const { messagesEl, markdown, onMessageAction } = options;
+  const { messagesEl, markdown, onMessageAction, openSession } = options;
   let streamingAssistant: HTMLDivElement | null = null;
   const streamingThinkingCards = new Map<string, HTMLDivElement>();
   const thinkingCardRawText = new WeakMap<HTMLDivElement, string>();
@@ -724,12 +726,7 @@ export function createMessageList(options: {
     header.append(label);
 
     for (const ref of sessionRefs) {
-      const chip = document.createElement("a");
-      chip.className = sessionRefChipClass(ref);
-      chip.href = sessionRefHref(ref);
-      chip.textContent = sessionRefChipText(ref);
-      chip.title = `Open session ${ref.sessionId}`;
-      header.append(chip);
+      header.append(createSessionRefChip(ref, { openSession }));
     }
     div.append(header);
 
diff --git a/src/sessions/lineage.ts b/src/sessions/lineage.ts
index 02be671..163f95a 100644
--- a/src/sessions/lineage.ts
+++ b/src/sessions/lineage.ts
@@ -108,3 +108,33 @@ export function runningChildIdsOf(
   }
   return running;
 }
+
+export type WaitingSession = { sessionId: string; name: string; cwd?: string };
+export type WaitingInfo = { count: number; names: string[]; sessions: WaitingSession[] };
+
+/**
+ * Derived "waiting on spawned sessions" state for one session: it is idle, but
+ * sessions it spawned are still running. Returns the running children so the UI
+ * can link to each of them, not merely name them.
+ */
+export function waitingInfoFrom(
+  sessionId: string,
+  origins: Array<{ sessionId: string; originSessionId: string }>,
+  lookups: {
+    isRunning: (id: string) => boolean;
+    selfRunning: boolean;
+    describe: (id: string) => { name?: string; cwd?: string };
+  },
+): WaitingInfo | undefined {
+  // A running session shows its own progress instead of what it is waiting for.
+  if (!sessionId || lookups.selfRunning) return undefined;
+  const running = runningChildIdsOf(sessionId, origins, lookups.isRunning);
+  if (running.length === 0) return undefined;
+
+  const sessions: WaitingSession[] = running.map((childId) => {
+    const described = lookups.describe(childId) || {};
+    const name = (described.name || "").trim() || childId.slice(-8);
+    return { sessionId: childId, name, cwd: described.cwd };
+  });
+  return { count: sessions.length, names: sessions.map((session) => session.name), sessions };
+}
diff --git a/src/sessions/sessionDrawer.ts b/src/sessions/sessionDrawer.ts
index b2022dc..6753d11 100644
--- a/src/sessions/sessionDrawer.ts
+++ b/src/sessions/sessionDrawer.ts
@@ -6,7 +6,7 @@ import type { RightPanelHandle, RightPanelManager } from "../layout/rightPanel.j
 import type { AppState, SessionInfo, SessionMarkerColorId, SessionUiState } from "../app/types.js";
 import { sessionRuntime, type SessionStateController } from "../app/sessionState.js";
 import { defaultSessionUiState, normalizeSessionUiState, persistCollapsedSessionFolders, sessionFolderPreviewLimit, sessionMarkerColors, writeActiveSessionIdToUrl } from "../app/types.js";
-import { orderItemsWithChildren as orderLineage, runningChildIdsOf, sessionIndicatorKind } from "./lineage.js";
+import { orderItemsWithChildren as orderLineage, runningChildIdsOf, sessionIndicatorKind, waitingInfoFrom, type WaitingInfo } from "./lineage.js";
 
 export async function fetchSessionList(url: string, headers: HeadersInit, timeoutMs = 15_000) {
   const controller = new AbortController();
@@ -30,7 +30,9 @@ export type SessionsController = {
   renderCurrentSessionBucketButton: () => void;
   applySessionUiState: (value: unknown) => void;
   markSessionRead: (sessionId?: string) => Promise<void>;
-  waitingInfoFor: (sessionId: string) => { count: number; names: string[] } | undefined;
+  waitingInfoFor: (sessionId: string) => WaitingInfo | undefined;
+  openSessionTab: (sessionId: string, cwd: string) => Promise<void>;
+  openSessionById: (sessionId: string) => Promise<void>;
 };
 
 function formatRelativeTime(value: string) {
@@ -159,6 +161,7 @@ export function createSessions(options: {
   } = options;
 
   let cachedSessions: SessionInfo[] = [];
+  const knownSessionNames = new Map<string, string>();
   let sessionRefreshPromise: Promise<void> | undefined;
   let closeSessionActionsMenu: (() => void) | undefined;
   let sessionPanelHandle: RightPanelHandle | undefined;
@@ -463,6 +466,10 @@ export function createSessions(options: {
 
   function updateSessionName(sessionId: string, name: string) {
     if (!sessionId) return;
+    // Remember the name even when the session is not in the cached list yet: a
+    // just-spawned session is named before it appears in a list refresh, and
+    // without this its links would fall back to showing a raw id fragment.
+    if (name) knownSessionNames.set(sessionId, name);
     let changed = false;
     cachedSessions = cachedSessions.map((session) => {
       if (session.id !== sessionId) return session;
@@ -471,7 +478,19 @@ export function createSessions(options: {
     });
     sessionState.applySnapshot({ sessionId, sessionName: name });
     if (changed && !elements.sessionDrawer.hidden) renderSessionList(cachedSessions);
+    else if (!changed) void refreshSessionsSoon(); // bring the new session into the list
     renderSessionBar();
+    options.onDerivedSessionStateChanged?.();
+  }
+
+  /** Coalesce list refreshes triggered by newly discovered sessions. */
+  let refreshSoonTimer: number | undefined;
+  function refreshSessionsSoon() {
+    if (refreshSoonTimer !== undefined) return;
+    refreshSoonTimer = window.setTimeout(() => {
+      refreshSoonTimer = undefined;
+      void refreshSessions();
+    }, 400);
   }
 
   function removeSession(sessionId: string) {
@@ -608,15 +627,23 @@ export function createSessions(options: {
    * Derived "waiting" state: session is idle but sessions it spawned are still
    * running. Computed purely from origins + live runtimes — nothing to reset.
    */
-  function waitingInfoFor(sessionId: string): { count: number; names: string[] } | undefined {
-    if (!sessionId || isSessionRunning(sessionId, Boolean(cachedSessions.find((item) => item.id === sessionId)?.runtime?.isRunning))) return undefined;
-    const running = runningChildrenOf(sessionId);
-    if (running.length === 0) return undefined;
-    const names = running.map((childId) => {
-      const cached = cachedSessions.find((item) => item.id === childId);
-      return (cached ? sessionTitle(cached) : "").replace(/^[⑂⤑]\s*/, "") || childId.slice(-8);
+  function waitingInfoFor(sessionId: string): WaitingInfo | undefined {
+    const self = cachedSessions.find((item) => item.id === sessionId);
+    return waitingInfoFrom(sessionId, state.sessionOrigins || [], {
+      selfRunning: isSessionRunning(sessionId, Boolean(self?.runtime?.isRunning)),
+      isRunning: (childId) => {
+        const cached = cachedSessions.find((item) => item.id === childId);
+        return isSessionRunning(childId, Boolean(cached?.runtime?.isRunning));
+      },
+      describe: (childId) => {
+        const cached = cachedSessions.find((item) => item.id === childId);
+        const cachedName = (cached ? sessionTitle(cached) : "").replace(/^[⑂⤑]\s*/, "");
+        return {
+          name: cachedName || knownSessionNames.get(childId) || "",
+          cwd: cached?.cwd,
+        };
+      },
     });
-    return { count: running.length, names };
   }
 
   /**
@@ -1191,6 +1218,17 @@ export function createSessions(options: {
     }
   }
 
+  /**
+   * Open a session knowing only its id: resolve its cwd from the cached list
+   * (falling back to the current one) and switch in place. This is what session
+   * links elsewhere in the UI use, so they never need a full page reload.
+   */
+  async function openSessionById(sessionId: string) {
+    if (!sessionId) return;
+    const cached = cachedSessions.find((item) => item.id === sessionId);
+    await openSessionTab(sessionId, cached?.cwd || state.currentCwd || "");
+  }
+
   function updateCurrentSessionPinButton() {
     if (!currentSessionPinButton) return;
     const currentId = state.currentSessionId;
@@ -2142,5 +2180,7 @@ export function createSessions(options: {
     applySessionUiState,
     markSessionRead,
     waitingInfoFor,
+    openSessionTab,
+    openSessionById,
   };
 }
diff --git a/src/status/statusBar.ts b/src/status/statusBar.ts
index 9472fa8..299cbb1 100644
--- a/src/status/statusBar.ts
+++ b/src/status/statusBar.ts
@@ -4,6 +4,8 @@ import type { AppState } from "../app/types.js";
 import { sessionRuntime, type SessionStateController } from "../app/sessionState.js";
 import { connectionLostDelayMs, reconnectDelayMs, reconnectNoticeDelayMs } from "../app/types.js";
 import { iconElement } from "../app/icons.js";
+import type { WaitingInfo } from "../sessions/lineage.js";
+import { createSessionRefChip } from "../app/sessionRefs.js";
 
 
 export type StatusBar = {
@@ -16,7 +18,7 @@ export type StatusBar = {
   markActivityStart: (label?: string, startedAt?: string | number | Date, lastActivityAt?: string | number | Date) => void;
   markActivityProgress: (label?: string, lastActivityAt?: string | number | Date) => void;
   markActivityEnd: () => void;
-  updateWaitingStatus: (info: { count: number; names: string[] } | undefined) => void;
+  updateWaitingStatus: (info: WaitingInfo | undefined) => void;
 };
 
 const activityQuietNoticeMs = 30_000;
@@ -52,8 +54,10 @@ export function createStatusBar(options: {
   addMessage: (role: "system", text: string, extraClass?: string) => void;
   refreshSessions: () => Promise<void>;
   refreshState: () => Promise<void>;
+  /** Switch to a spawned session in place (late-bound: sessions is created after). */
+  openSession?: (sessionId: string, cwd: string) => Promise<void> | void;
 }): StatusBar {
-  const { state, elements, api, sessionState, addMessage, refreshSessions, refreshState } = options;
+  const { state, elements, api, sessionState, addMessage, refreshSessions, refreshState, openSession } = options;
   const activityBySession = new Map<string, ActivityEntry>();
   let activityTimer: number | undefined;
 
@@ -250,29 +254,52 @@ export function createStatusBar(options: {
   // slot above the composer — but only while the session is otherwise idle:
   // precedence is running > waiting. Static pulsing hourglass (accent, same
   // color family as unread) + white text naming what it waits for.
-  let waitingInfo: { count: number; names: string[] } | undefined;
+  // Derived "waiting on spawned sessions" state, shown as a strip directly above
+  // the composer. Each spawned session is a link, so the user can jump straight
+  // into a worker while it runs. Only shown while this session is itself idle:
+  // precedence is running > waiting.
+  let waitingInfo: WaitingInfo | undefined;
 
   function clearWaitingRender() {
-    if (!elements.runtimeStatusEl.classList.contains("waiting")) return;
-    elements.runtimeStatusEl.hidden = true;
-    elements.runtimeStatusEl.textContent = "";
-    elements.runtimeStatusEl.title = "";
-    elements.runtimeStatusEl.className = "runtimeStatus";
+    elements.waitingSessionsEl.hidden = true;
+    elements.waitingSessionsEl.replaceChildren();
   }
 
   function renderWaitingStatus() {
     if (!waitingInfo || currentActivity()) return;
-    const names = waitingInfo.names.slice(0, 3).join(", ") + (waitingInfo.names.length > 3 ? "…" : "");
-    elements.runtimeStatusEl.className = "runtimeStatus waiting";
-    elements.runtimeStatusEl.textContent = "";
-    elements.runtimeStatusEl.append(iconElement("hourglass"), document.createTextNode(`Waiting on ${waitingInfo.count} spawned session${waitingInfo.count === 1 ? "" : "s"}: ${names}`));
-    elements.runtimeStatusEl.title = "This session stays usable while spawned sessions run — it will be woken automatically when they finish.";
-    elements.runtimeStatusEl.hidden = false;
+    const container = elements.waitingSessionsEl;
+    container.replaceChildren();
+
+    const label = document.createElement("span");
+    label.className = "waitingSessionsLabel";
+    label.append(iconElement("hourglass"));
+    const count = waitingInfo.count;
+    label.append(document.createTextNode(`Waiting on ${count} spawned session${count === 1 ? "" : "s"}`));
+    label.title = "This session stays usable while spawned sessions run — it will be woken automatically when they finish.";
+    container.append(label);
+
+    for (const session of waitingInfo.sessions) {
+      const chip = createSessionRefChip({ sessionId: session.sessionId, name: session.name }, {
+        className: "waitingSessionChip",
+        openSession: (sessionId) => { void openSession?.(sessionId, session.cwd || ""); },
+      });
+      chip.textContent = "";
+      const spinner = document.createElement("span");
+      spinner.className = "waitingSessionSpinner";
+      spinner.setAttribute("aria-hidden", "true");
+      chip.append(spinner, document.createTextNode(session.name));
+      chip.title = `Open ${session.name}`;
+      container.append(chip);
+    }
+    container.hidden = false;
   }
 
-  function updateWaitingStatus(info: { count: number; names: string[] } | undefined) {
+  function updateWaitingStatus(info: WaitingInfo | undefined) {
     waitingInfo = info;
-    if (currentActivity()) return; // running indicator owns the slot
+    if (currentActivity()) {
+      clearWaitingRender(); // the running indicator owns this slot
+      return;
+    }
     if (info) renderWaitingStatus();
     else clearWaitingRender();
   }
diff --git a/src/styles/base.css b/src/styles/base.css
index da60fc1..f7e9e64 100644
--- a/src/styles/base.css
+++ b/src/styles/base.css
@@ -125,14 +125,8 @@ body {
   animation: waitingPulse 2s ease-in-out infinite;
 }
 .sessionWaitingCount { font-weight: 600; }
-.runtimeStatus.waiting svg {
-  width: 13px;
-  height: 13px;
-  vertical-align: middle;
-  margin-right: 5px;
-  animation: waitingPulse 2s ease-in-out infinite;
-}
+
 @media (prefers-reduced-motion: reduce) {
-  .sessionWaitingPill svg, .runtimeStatus.waiting svg { animation: none; }
+  .sessionWaitingPill svg { animation: none; }
   .auroraRibbon { animation: none; }
 }
diff --git a/src/styles/composer.css b/src/styles/composer.css
index 6bd6b64..911a261 100644
--- a/src/styles/composer.css
+++ b/src/styles/composer.css
@@ -76,13 +76,7 @@
 .runtimeStatus.running { color: var(--accent); }
 .runtimeStatus.quiet { color: #facc15; }
 .runtimeStatus.stale { color: #fb923c; }
-.runtimeStatus.waiting {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-  color: var(--fg);
-  pointer-events: auto;
-}
+
 .contextMeterLabel {
   right: 0;
   display: none;
@@ -813,3 +807,68 @@ button:disabled:hover { border-color: var(--border); }
     inset 0 0 0 3px rgba(207, 137, 142, .2),
     inset 0 1px 0 rgba(255, 255, 255, .08);
 }
+
+/* Spawned sessions still running, shown directly above the composer. Each is a
+   link, so a worker can be opened while it works. Hidden entirely when idle, so
+   it costs no vertical space. */
+.waitingSessions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: nowrap;
+  overflow-x: auto;
+  scrollbar-width: none;
+  padding: 4px 10px;
+  margin: 0 auto;
+  width: min(var(--composer-max-width, 900px), 100%);
+  box-sizing: border-box;
+  font-size: 12px;
+  color: var(--muted);
+}
+.waitingSessions::-webkit-scrollbar { display: none; }
+.waitingSessions[hidden] { display: none; }
+.waitingSessionsLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  flex: 0 0 auto;
+  white-space: nowrap;
+}
+.waitingSessionsLabel svg {
+  width: 13px;
+  height: 13px;
+  animation: waitingPulse 2s ease-in-out infinite;
+}
+.waitingSessionChip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex: 0 0 auto;
+  max-width: 220px;
+  border: 1px solid color-mix(in srgb, var(--accent) 34%, var(--border));
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--accent) 10%, var(--panel));
+  color: var(--text);
+  text-decoration: none;
+  padding: 3px 10px 3px 8px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.waitingSessionChip:hover,
+.waitingSessionChip:focus-visible {
+  border-color: color-mix(in srgb, var(--accent) 70%, var(--border));
+  background: color-mix(in srgb, var(--accent) 18%, var(--panel));
+  outline: none;
+}
+.waitingSessionSpinner {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  flex: 0 0 auto;
+  background: var(--accent);
+  animation: waitingPulse 1.4s ease-in-out infinite;
+}
+@media (prefers-reduced-motion: reduce) {
+  .waitingSessionsLabel svg, .waitingSessionSpinner { animation: none; }
+}
diff --git a/src/tools/toolCards.ts b/src/tools/toolCards.ts
index c865b8f..6f105c1 100644
--- a/src/tools/toolCards.ts
+++ b/src/tools/toolCards.ts
@@ -1,7 +1,7 @@
 import hljs from "highlight.js/lib/common";
 import { renderEditDiff } from "../components/editDiff.js";
 import { textFromRawContent } from "../messages/content.js";
-import { sessionRefChipClass, sessionRefChipText, sessionRefHref, sessionRefsFromDetails } from "../app/sessionRefs.js";
+import { createSessionRefChip, sessionRefsFromDetails } from "../app/sessionRefs.js";
 import { playToolCardEntry, playToolCardStateTransition } from "../messages/entryAnimation.js";
 import type { ApiHeaders } from "../app/api.js";
 
@@ -100,6 +100,8 @@ function addToolArgsDetails(card: HTMLDivElement, args?: Record<string, unknown>
  * structured `details`. Generic: no tool name is special-cased and no result
  * text is parsed. Safe to call repeatedly for the same card.
  */
+let openSessionRef: ((sessionId: string) => void) | undefined;
+
 function addToolSessionChips(card: HTMLDivElement, result: unknown) {
   const record = result && typeof result === "object" ? result as Record<string, unknown> : {};
   const details = record.details ?? (record.raw as Record<string, unknown> | undefined)?.details;
@@ -112,12 +114,7 @@ function addToolSessionChips(card: HTMLDivElement, result: unknown) {
   if (!refs.length) return;
   const toggle = header.querySelector(".toolCardExpandToggle");
   for (const ref of refs) {
-    const chip = document.createElement("a");
-    chip.className = sessionRefChipClass(ref);
-    chip.href = sessionRefHref(ref);
-    chip.textContent = sessionRefChipText(ref);
-    chip.title = `Open session ${ref.sessionId}`;
-    header.insertBefore(chip, toggle || null);
+    header.insertBefore(createSessionRefChip(ref, { openSession: openSessionRef }), toggle || null);
   }
 }
 
@@ -357,7 +354,8 @@ function finalizePartialToolOutput(card: HTMLDivElement) {
 
 export function createToolCards(messagesEl: HTMLDivElement, scrollToBottom: () => void = () => {
   messagesEl.scrollTop = messagesEl.scrollHeight;
-}, apiHeaders?: ApiHeaders): ToolCards {
+}, apiHeaders?: ApiHeaders, openSession?: (sessionId: string) => void): ToolCards {
+  openSessionRef = openSession;
   const activeToolCards = new Map<string, HTMLDivElement>();
   const knownToolStartedAts = new Map<string, number>();
   const runningToolStates = new WeakMap<HTMLDivElement, { startedAt?: number; lastActivityAt: number; timer: number }>();
diff --git a/tests/session-lineage.test.ts b/tests/session-lineage.test.ts
index 468f597..3ba677d 100644
--- a/tests/session-lineage.test.ts
+++ b/tests/session-lineage.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { orderItemsWithChildren, runningChildIdsOf, sessionIndicatorKind } from "../src/sessions/lineage.js";
+import { orderItemsWithChildren, runningChildIdsOf, sessionIndicatorKind, waitingInfoFrom } from "../src/sessions/lineage.js";
 
 type Item = { id: string };
 const items = (...ids: string[]): Item[] => ids.map((id) => ({ id }));
@@ -121,3 +121,53 @@ describe("runningChildIdsOf", () => {
     expect(runningChildIdsOf("", origins, () => true)).toEqual([]);
   });
 });
+
+describe("waitingInfoFrom", () => {
+  const origins = [
+    { sessionId: "worker-1", originSessionId: "parent" },
+    { sessionId: "worker-2", originSessionId: "parent" },
+    { sessionId: "unrelated", originSessionId: "other" },
+  ];
+  const describe_ = (id: string) => ({ name: id === "worker-1" ? "scout: auth" : "tests: baseline", cwd: `/repo/${id}` });
+
+  it("returns each running child so the UI can link to it", () => {
+    const info = waitingInfoFrom("parent", origins, { selfRunning: false, isRunning: () => true, describe: describe_ });
+    expect(info?.count).toBe(2);
+    expect(info?.sessions).toEqual([
+      { sessionId: "worker-1", name: "scout: auth", cwd: "/repo/worker-1" },
+      { sessionId: "worker-2", name: "tests: baseline", cwd: "/repo/worker-2" },
+    ]);
+    expect(info?.names).toEqual(["scout: auth", "tests: baseline"]);
+  });
+
+  it("is undefined while the session itself is running", () => {
+    // Precedence: a running session shows its own progress, not what it awaits.
+    expect(waitingInfoFrom("parent", origins, { selfRunning: true, isRunning: () => true, describe: describe_ })).toBeUndefined();
+  });
+
+  it("is undefined when no spawned session is still running", () => {
+    expect(waitingInfoFrom("parent", origins, { selfRunning: false, isRunning: () => false, describe: describe_ })).toBeUndefined();
+  });
+
+  it("counts only children that are still running", () => {
+    const info = waitingInfoFrom("parent", origins, {
+      selfRunning: false,
+      isRunning: (id) => id === "worker-2",
+      describe: describe_,
+    });
+    expect(info?.sessions.map((s) => s.sessionId)).toEqual(["worker-2"]);
+  });
+
+  it("falls back to a short id when a child has no title yet", () => {
+    const info = waitingInfoFrom("parent", [{ sessionId: "abcdef123456", originSessionId: "parent" }], {
+      selfRunning: false,
+      isRunning: () => true,
+      describe: () => ({}),
+    });
+    expect(info?.sessions[0]).toEqual({ sessionId: "abcdef123456", name: "ef123456", cwd: undefined });
+  });
+
+  it("is undefined for an empty session id", () => {
+    expect(waitingInfoFrom("", origins, { selfRunning: false, isRunning: () => true, describe: describe_ })).toBeUndefined();
+  });
+});