feat(settings): detect stale writers with a revision, and announce raw changes

The remaining P1 from the #939 review, plus the P2 it shares a mechanism with.

Nothing carried a version, so two tabs editing one namespace silently
overwrote each other — reproduced as tab B's `reasoning` lost to tab A's
older draft. The seam's per-namespace write queue orders writes; it cannot
tell a fresh writer from one replaying a snapshot a predecessor superseded.

Each namespace now carries a monotonic `revision` over its RAW section. A
write may send `expectedRevision`, checked at the FRONT of the queue (not at
call time, which would race the very predecessor it guards against); a
mismatch rejects with `SettingsConflictError` → `settings-conflict` on the
wire, carrying both revisions. The editor captures the revision it opened at
and, on conflict, asks the user to reopen rather than replaying its snapshot.

The same counter fixes the missing broadcast. `settings/updated` is gated on
the resolved value — correct for consumers, wrong for configuration surfaces:
storing an override equal to the composition base leaves the resolved value
alone while changing what the document says (the field is now overridden, not
inherited) and moving every open editor's revision. `settings/document-updated
(ns, revision)` fires on any raw-section change, in-process or external, and
`host/settings-changed` now rides it.

That event also closes the stale model picker: editing a provider's `models`
changes no route, so `llm/adapters-updated` never fired and an open picker
kept serving the old catalog. A change to an exposed provider namespace now
emits `host/models-changed` too — that namespace holds the catalog.

Docs: both sides of the five touched README pairs, a type-equiv block for
`SettingsPathOp`, and an Agent Note recording what the plane exposes and who
may overwrite what. The deferred wire-redaction gaps (secrets behind
union/intersection/transform, `.default(...)` in the served envelope, schema
text in rejection messages, `new Function` rehydration, pi-ai's `headers`) are
recorded as TODO(settings-wire-redaction) and in Known Limitations rather than
half-fixed.

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -52,6 +52,7 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('settings-rejected'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-not-exposed'), message: z.string(), details: z.object({ ns: z.string() }) }),
+  z.object({ code: z.literal('settings-conflict'), message: z.string(), details: z.object({ ns: z.string(), expected: z.number(), actual: z.number() }) }),
   z.object({ code: z.literal('credential-rejected'), message: z.string(), details: z.object({ ref: z.string() }) }),
   z.object({ code: z.literal('title-invalid'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),

packages/host/apiproxy/src/api/rpc.ts

@@ -61,6 +61,12 @@ export interface RpcErrorDetailsMap {
    * it; the message names the namespace.
    */
   'settings-not-exposed': { ns: string }
+  /**
+   * A settings write carried an `expectedRevision` the namespace has already
+   * moved past: another writer (tab, editor, or an external file edit) landed
+   * first. The details carry both revisions so a client can re-read and retry.
+   */
+  'settings-conflict': { ns: string; expected: number; actual: number }
   /** A credential write was refused (read-only shadowing layer or storage failure); the message is the seam's own text. */
   'credential-rejected': { ref: string }
   'title-invalid': { sessionId: SessionId }

packages/host/apiproxy/src/api/settings.schema.ts

@@ -23,6 +23,7 @@ export const settingsNamespaceViewSchema = z.object({
   user: z.unknown().optional(),
   applies: z.union([z.literal('live'), z.literal('restart')]),
   secrets: z.array(settingsSecretViewSchema),
+  revision: z.number(),
 }) satisfies z.ZodType<Wire<SettingsNamespaceView>>
 
 /** settings.describe request payload. */
@@ -38,6 +39,7 @@ export const settingsDescribeValueSchema = z.object({
 export const settingsUpdateRequestSchema = z.object({
   ns: z.string().min(1),
   patch: z.record(z.string(), z.unknown()),
+  expectedRevision: z.number().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'settings.update'>>>
 
 /** settings.update response value: the namespace's new redacted view. */
@@ -47,6 +49,7 @@ export const settingsUpdateValueSchema = settingsNamespaceViewSchema satisfies z
 export const settingsReplaceRequestSchema = z.object({
   ns: z.string().min(1),
   section: z.record(z.string(), z.unknown()),
+  expectedRevision: z.number().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'settings.replace'>>>
 
 /** One path-addressed edit of settings.mutate. */
@@ -59,6 +62,7 @@ export const settingsPathOpSchema = z.discriminatedUnion('op', [
 export const settingsMutateRequestSchema = z.object({
   ns: z.string().min(1),
   ops: z.array(settingsPathOpSchema),
+  expectedRevision: z.number().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'settings.mutate'>>>
 
 /** settings.mutate response value: the namespace's new redacted view. */

packages/host/apiproxy/src/api/settings.ts

@@ -32,6 +32,12 @@ export interface SettingsNamespaceView {
   applies: 'live' | 'restart'
   /** Every schema-declared secret slot with its configured state. */
   secrets: SettingsSecretView[]
+  /**
+   * Monotonic revision of the raw user section this view was read at. Send it
+   * back as `expectedRevision` on a write so a stale editor is refused rather
+   * than silently overwriting a concurrent change.
+   */
+  revision: number
 }
 
 /**
@@ -59,7 +65,7 @@ export interface SettingsApi {
    * merge preserves the stored value. Responds with the namespace's new
    * redacted view; a schema or storage rejection is `settings-rejected`.
    */
-  update(request: RpcRequest<{ ns: string; patch: object }>): Promise<RpcResponse<SettingsNamespaceView>>
+  update(request: RpcRequest<{ ns: string; patch: object; expectedRevision?: number }>): Promise<RpcResponse<SettingsNamespaceView>>
 
   /**
    * Replace one namespace's user section wholesale — the removal/reset path a
@@ -68,7 +74,7 @@ export interface SettingsApi {
    * fold the descriptor's `user` layer (and re-supply any secret it wants to
    * keep) or accept the reset.
    */
-  replace(request: RpcRequest<{ ns: string; section: object }>): Promise<RpcResponse<SettingsNamespaceView>>
+  replace(request: RpcRequest<{ ns: string; section: object; expectedRevision?: number }>): Promise<RpcResponse<SettingsNamespaceView>>
 
   /**
    * Apply path-addressed edits to one namespace's user section, resolved
@@ -78,5 +84,7 @@ export interface SettingsApi {
    * returned cannot be deleted as a side effect. `replace` remains the
    * deliberate wholesale reset.
    */
-  mutate(request: RpcRequest<{ ns: string; ops: SettingsPathOpView[] }>): Promise<RpcResponse<SettingsNamespaceView>>
+  mutate(
+    request: RpcRequest<{ ns: string; ops: SettingsPathOpView[]; expectedRevision?: number }>,
+  ): Promise<RpcResponse<SettingsNamespaceView>>
 }