@timurproko/a1 0.1.8-dev.157 → 0.1.8-dev.182

package/dist/integrations/pi/engine/settings-effects.d.ts

@@ -0,0 +1,55 @@
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingChangeOutcome, AgentSettingOwner } from "../../../contracts/agent-engine/index.js";
+export type PiSettingKey = "autoCompact" | "showImages" | "imageWidthCells" | "autoResizeImages" | "blockImages" | "enableSkillCommands" | "steeringMode" | "followUpMode" | "transport" | "httpIdleTimeoutMs" | "thinkingLevel" | "theme" | "hideThinkingBlock" | "mermaidRenderingMode" | "showCacheMissNotices" | "collapseChangelog" | "enableInstallTelemetry" | "quietStartup" | "defaultProjectTrust" | "doubleEscapeAction" | "treeFilterMode" | "showHardwareCursor" | "editorPaddingX" | "outputPad" | "autocompleteMaxVisible" | "clearOnShrink" | "showTerminalProgress" | "tuiMode" | "fullscreenExitOutput" | "fullscreenScrollbar" | "warnings";
+export interface PiSettingEffectDefinition {
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    /** Bare A1 deliberately replaces this Pi behavior and therefore cannot apply it. */
+    readonly bareLimitation?: string;
+}
+/**
+ * Reviewed effect authority for every generated Pi setting. Presentation remains
+ * generated; this table states who must make each accepted value observable.
+ */
+export declare const PI_SETTING_EFFECTS: Readonly<Record<PiSettingKey, PiSettingEffectDefinition>>;
+export interface PiSettingEffectHandler {
+    /** Install one value in the active owner. Handlers must be idempotent and reversible. */
+    apply(value: AgentJsonValue): void | Promise<void>;
+}
+export type PiSettingOwnerHandlers = Partial<Record<PiSettingKey, PiSettingEffectHandler>>;
+export interface PiSettingStorageOperation {
+    readonly key: PiSettingKey;
+    read(): AgentJsonValue;
+    validate(value: AgentJsonValue): void;
+    write(value: AgentJsonValue): void;
+}
+export interface PiSettingsCoordinatorOptions {
+    readonly productMode?: "bare" | "comparison";
+    readonly flush: () => Promise<void>;
+    readonly drainErrors?: () => readonly {
+        readonly error: Error;
+    }[];
+}
+/**
+ * One transactional authority for Pi setting validation, active effects,
+ * persistence, durability, rollback, and owner lifecycle.
+ */
+export declare class PiSettingsCoordinator {
+    #private;
+    constructor(operations: readonly PiSettingStorageOperation[], options: PiSettingsCoordinatorOptions);
+    bindOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
+    unbindOwner(owner: AgentSettingOwner, keys?: readonly PiSettingKey[]): void;
+    definition(key: PiSettingKey): PiSettingEffectDefinition;
+    storedValue(key: PiSettingKey): AgentJsonValue;
+    effectiveValue(key: PiSettingKey): AgentJsonValue;
+    limitationReason(key: PiSettingKey): string | null;
+    available(key: PiSettingKey): boolean;
+    validate(key: PiSettingKey, value: AgentJsonValue): void;
+    apply(key: PiSettingKey, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    flush(): Promise<void>;
+    rollback(key: PiSettingKey, value: AgentJsonValue): Promise<void>;
+}
+export declare function settingsEffectInventoryDrift(presented: readonly string[], reviewed?: readonly string[]): {
+    readonly unmapped: readonly string[];
+    readonly stale: readonly string[];
+    readonly duplicated: readonly string[];
+};

package/dist/integrations/pi/engine/settings-effects.js

@@ -0,0 +1,229 @@
+const PRODUCT_FIXED = {
+    theme: "Bare A1 uses its product-fixed dark owned theme",
+    quietStartup: "Bare A1 owns startup composition and does not expose Pi startup suppression",
+    tuiMode: "Bare A1 uses its product-fixed custom fullscreen viewport",
+    fullscreenScrollbar: "Bare A1 replaces Pi's scrollbar with declared A1 viewport settings",
+    enableInstallTelemetry: "Bare A1 does not run Pi's install/update telemetry lifecycle",
+};
+/**
+ * Reviewed effect authority for every generated Pi setting. Presentation remains
+ * generated; this table states who must make each accepted value observable.
+ */
+export const PI_SETTING_EFFECTS = Object.freeze({
+    autoCompact: { application: "live", owner: "agent" },
+    showImages: { application: "live", owner: "shell" },
+    imageWidthCells: { application: "live", owner: "shell" },
+    autoResizeImages: { application: "live", owner: "agent" },
+    blockImages: { application: "live", owner: "agent" },
+    enableSkillCommands: { application: "live", owner: "shell" },
+    steeringMode: { application: "live", owner: "agent" },
+    followUpMode: { application: "live", owner: "agent" },
+    transport: { application: "live", owner: "agent" },
+    httpIdleTimeoutMs: { application: "live", owner: "agent" },
+    thinkingLevel: { application: "live", owner: "agent" },
+    theme: { application: "live", owner: "shell", bareLimitation: PRODUCT_FIXED.theme },
+    hideThinkingBlock: { application: "live", owner: "shell" },
+    mermaidRenderingMode: { application: "live", owner: "shell" },
+    showCacheMissNotices: { application: "live", owner: "shell" },
+    collapseChangelog: { application: "next-start", owner: "startup" },
+    enableInstallTelemetry: { application: "next-start", owner: "installation", bareLimitation: PRODUCT_FIXED.enableInstallTelemetry },
+    quietStartup: { application: "next-start", owner: "startup", bareLimitation: PRODUCT_FIXED.quietStartup },
+    defaultProjectTrust: { application: "next-start", owner: "startup" },
+    doubleEscapeAction: { application: "live", owner: "shell" },
+    treeFilterMode: { application: "live", owner: "shell" },
+    showHardwareCursor: { application: "live", owner: "terminal" },
+    editorPaddingX: { application: "live", owner: "shell" },
+    outputPad: { application: "live", owner: "shell" },
+    autocompleteMaxVisible: { application: "live", owner: "shell" },
+    clearOnShrink: { application: "live", owner: "terminal" },
+    showTerminalProgress: { application: "live", owner: "terminal" },
+    tuiMode: { application: "next-session", owner: "shell", bareLimitation: PRODUCT_FIXED.tuiMode },
+    fullscreenExitOutput: { application: "current-exit", owner: "shutdown" },
+    fullscreenScrollbar: { application: "live", owner: "shell", bareLimitation: PRODUCT_FIXED.fullscreenScrollbar },
+    warnings: { application: "live", owner: "agent" },
+});
+/**
+ * One transactional authority for Pi setting validation, active effects,
+ * persistence, durability, rollback, and owner lifecycle.
+ */
+export class PiSettingsCoordinator {
+    #operations;
+    #handlers = new Map();
+    #state = new Map();
+    #productMode;
+    #flushStorage;
+    #drainErrors;
+    constructor(operations, options) {
+        this.#operations = new Map(operations.map(operation => [operation.key, operation]));
+        this.#productMode = options.productMode ?? "bare";
+        this.#flushStorage = options.flush;
+        this.#drainErrors = options.drainErrors;
+        for (const operation of operations) {
+            const stored = operation.read();
+            this.#state.set(operation.key, { stored, effective: stored, inconsistentReason: null });
+        }
+    }
+    bindOwner(owner, handlers) {
+        const bound = [];
+        for (const [candidate, handler] of Object.entries(handlers)) {
+            if (handler === undefined)
+                continue;
+            const key = candidate;
+            const definition = PI_SETTING_EFFECTS[key];
+            if (definition === undefined)
+                throw new Error(`unknown Pi setting effect: ${key}`);
+            if (definition.owner !== owner)
+                throw new Error(`${key} belongs to ${definition.owner}, not ${owner}`);
+            if (this.#productMode === "bare" && definition.bareLimitation !== undefined) {
+                throw new Error(`${key} is product-fixed in bare A1`);
+            }
+            this.#handlers.set(key, handler);
+            bound.push(key);
+        }
+        return () => this.unbindOwner(owner, bound);
+    }
+    unbindOwner(owner, keys) {
+        const candidates = keys ?? [...this.#handlers.keys()];
+        for (const key of candidates)
+            if (PI_SETTING_EFFECTS[key].owner === owner)
+                this.#handlers.delete(key);
+    }
+    definition(key) {
+        return PI_SETTING_EFFECTS[key];
+    }
+    storedValue(key) {
+        const operation = this.#requireOperation(key);
+        const stored = operation.read();
+        const state = this.#requireState(key);
+        state.stored = stored;
+        return stored;
+    }
+    effectiveValue(key) {
+        return this.#requireState(key).effective;
+    }
+    limitationReason(key) {
+        const definition = PI_SETTING_EFFECTS[key];
+        if (this.#productMode === "bare" && definition.bareLimitation !== undefined)
+            return definition.bareLimitation;
+        const inconsistent = this.#requireState(key).inconsistentReason;
+        if (inconsistent !== null)
+            return inconsistent;
+        if (!this.#handlers.has(key))
+            return `${definition.owner} effect is not bound for ${definition.application} application`;
+        return null;
+    }
+    available(key) {
+        return this.limitationReason(key) === null;
+    }
+    validate(key, value) {
+        this.#requireOperation(key).validate(value);
+    }
+    async apply(key, value) {
+        const operation = this.#requireOperation(key);
+        operation.validate(value);
+        const definition = PI_SETTING_EFFECTS[key];
+        const previousStored = operation.read();
+        const state = this.#requireState(key);
+        const previousEffective = state.effective;
+        const limitationReason = this.limitationReason(key);
+        if (limitationReason !== null) {
+            return outcome("unavailable", definition.application, previousStored, previousEffective, null, limitationReason);
+        }
+        const handler = this.#handlers.get(key);
+        if (definition.application !== "live") {
+            try {
+                operation.write(value);
+                await this.flush();
+                state.stored = value;
+                return outcome("deferred", definition.application, value, previousEffective, null, null);
+            }
+            catch (error) {
+                const failure = await this.#restorePersistence(operation, previousStored, error);
+                state.stored = operation.read();
+                return outcome("failed", definition.application, state.stored, previousEffective, failure, null);
+            }
+        }
+        try {
+            await handler.apply(value);
+        }
+        catch (error) {
+            return outcome("failed", definition.application, previousStored, previousEffective, describe(error), null);
+        }
+        state.effective = value;
+        try {
+            operation.write(value);
+            await this.flush();
+            state.stored = value;
+            state.inconsistentReason = null;
+            return outcome("applied", definition.application, value, value, null, null);
+        }
+        catch (error) {
+            const persistenceFailure = await this.#restorePersistence(operation, previousStored, error);
+            try {
+                await handler.apply(previousEffective);
+                state.effective = previousEffective;
+                state.stored = operation.read();
+                return outcome("failed", definition.application, state.stored, previousEffective, persistenceFailure, null);
+            }
+            catch (rollbackError) {
+                state.stored = operation.read();
+                state.inconsistentReason = `rollback failed after ${persistenceFailure}: ${describe(rollbackError)}`;
+                return outcome("failed", definition.application, state.stored, state.effective, state.inconsistentReason, state.inconsistentReason);
+            }
+        }
+    }
+    async flush() {
+        await this.#flushStorage();
+        const errors = this.#drainErrors?.() ?? [];
+        if (errors.length > 0)
+            throw new Error(errors.map(value => value.error.message).join("; "));
+    }
+    async rollback(key, value) {
+        const handler = this.#handlers.get(key);
+        if (handler === undefined)
+            throw new Error(`cannot roll back unbound setting: ${key}`);
+        await handler.apply(value);
+        this.#requireState(key).effective = value;
+    }
+    async #restorePersistence(operation, previous, cause) {
+        const original = describe(cause);
+        try {
+            operation.write(previous);
+            await this.flush();
+            return original;
+        }
+        catch (rollbackError) {
+            return `${original}; persistence rollback failed: ${describe(rollbackError)}`;
+        }
+    }
+    #requireOperation(key) {
+        const operation = this.#operations.get(key);
+        if (operation === undefined)
+            throw new Error(`setting is unavailable: ${key}`);
+        return operation;
+    }
+    #requireState(key) {
+        const state = this.#state.get(key);
+        if (state === undefined)
+            throw new Error(`setting state is unavailable: ${key}`);
+        return state;
+    }
+}
+export function settingsEffectInventoryDrift(presented, reviewed = Object.keys(PI_SETTING_EFFECTS)) {
+    const reviewedSet = new Set(reviewed);
+    const presentedSet = new Set(presented);
+    const counts = new Map();
+    for (const key of reviewed)
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    return {
+        unmapped: presented.filter(key => !reviewedSet.has(key)),
+        stale: reviewed.filter(key => !presentedSet.has(key)),
+        duplicated: [...counts].filter(([, count]) => count > 1).map(([key]) => key),
+    };
+}
+function outcome(status, application, storedValue, effectiveValue, failure, limitationReason) {
+    return { status, application, storedValue, effectiveValue, failure, limitationReason };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/integrations/pi/engine/settings-integration.d.ts

@@ -1,43 +1,28 @@
 import type { SettingsManager } from "@earendil-works/pi-coding-agent";
-import type { AgentJsonValue, AgentSettingDescriptor, AgentSettingsPort } from "../../../contracts/agent-engine/index.js";
-/**
- * Values only the running engine knows: the themes installed on this machine and
- * the thinking levels this session supports. The boundary asks for them as it is
- * read, so no layer above has to know they are not fixed.
- */
+import type { AgentJsonValue, AgentSettingChangeOutcome, AgentSettingDescriptor, AgentSettingOwner, AgentSettingsPort } from "../../../contracts/agent-engine/index.js";
+import { type PiSettingOwnerHandlers } from "./settings-effects.js";
+/** Values only the running engine knows. */
 export interface PiSettingsProviders {
     readonly themes?: () => readonly string[];
     readonly thinkingLevels?: () => readonly string[];
+    readonly productMode?: "bare" | "comparison";
 }
-/**
- * The engine stores a theme as one string with two forms: a theme's name, or a
- * `light/dark` pair meaning "follow the terminal". That grammar is the engine's,
- * so it is parsed and composed here and reaches the surfaces above as ordinary
- * settings — a theme entry that offers `automatic`, and, while automatic, one
- * entry per terminal appearance.
- */
 export declare const AUTOMATIC_THEME = "automatic";
 interface AutomaticTheme {
     readonly light: string;
     readonly dark: string;
 }
-/** A stored theme is automatic when it names one theme per terminal appearance. */
 export declare function parseAutomaticTheme(stored: string): AutomaticTheme | null;
-/**
- * The settings A1 exposes: the ones the engine presents. Kept as the engine's
- * own inventory rather than a list beside it, so a setting it adds or renames
- * shows up as a named test failure instead of quietly going missing.
- */
 export declare const EXPOSED_SETTING_KEYS: readonly string[];
-/**
- * What has drifted between the settings the engine presents and the settings A1
- * maps to its API: the ones A1 has not caught up with, and the ones it kept
- * after the engine dropped them. Either is a build failure with a name in it.
- */
 export declare function settingsInventoryDrift(presented: readonly string[], mapped: readonly string[]): {
     readonly unmapped: readonly string[];
     readonly stale: readonly string[];
 };
+/**
+ * Pi settings boundary backed by the transactional settings coordinator. The
+ * generated metadata owns presentation while the reviewed effect registry owns
+ * timing, availability, and active behavior.
+ */
 export declare class PiSettingsIntegration implements AgentSettingsPort {
     #private;
     private readonly settings;
@@ -46,10 +31,13 @@ export declare class PiSettingsIntegration implements AgentSettingsPort {
         flush: boolean;
     };
     constructor(settings: SettingsManager, providers?: PiSettingsProviders);
+    bindOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
+    unbindOwner(owner: AgentSettingOwner): void;
     listSettings(): Promise<readonly AgentSettingDescriptor[]>;
     readSetting(key: string): Promise<AgentJsonValue | undefined>;
-    writeSetting(key: string, value: AgentJsonValue): Promise<void>;
-    writeSettingNow(key: string, value: AgentJsonValue): void;
+    writeSetting(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    /** Shared route used by the pinned selector and owned settings surface. */
+    writeSettingNow(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
     flush(): Promise<void>;
 }
 export {};

package/dist/integrations/pi/engine/settings-integration.js

@@ -1,18 +1,10 @@
 import piSettingsMetadata from "./pi-settings-metadata.json" with { type: "json" };
-/**
- * The engine stores a theme as one string with two forms: a theme's name, or a
- * `light/dark` pair meaning "follow the terminal". That grammar is the engine's,
- * so it is parsed and composed here and reaches the surfaces above as ordinary
- * settings — a theme entry that offers `automatic`, and, while automatic, one
- * entry per terminal appearance.
- */
+import { PI_SETTING_EFFECTS, PiSettingsCoordinator, settingsEffectInventoryDrift, } from "./settings-effects.js";
 export const AUTOMATIC_THEME = "automatic";
-/** The themes an automatic setting names for each terminal appearance. */
 const LIGHT_APPEARANCE_THEME = "light";
 const DARK_APPEARANCE_THEME = "dark";
 const THEME_KEY = "theme";
 const THINKING_KEY = "thinkingLevel";
-/** A stored theme is automatic when it names one theme per terminal appearance. */
 export function parseAutomaticTheme(stored) {
     const at = stored.indexOf("/");
     if (at < 0 || stored.indexOf("/", at + 1) >= 0)
@@ -21,24 +13,8 @@ export function parseAutomaticTheme(stored) {
     const dark = stored.slice(at + 1).trim();
     return light.length > 0 && dark.length > 0 ? { light, dark } : null;
 }
-/**
- * How the engine presents these settings — wording, order, and the flags a
- * dialog-backed setting offers — generated from its own source by
- * `npm run update:pi-settings-metadata` and verified by a governance test, so a
- * Pi upgrade cannot silently reword or reorder what A1 shows.
- */
 const PRESENTATION = piSettingsMetadata;
-/**
- * The settings A1 exposes: the ones the engine presents. Kept as the engine's
- * own inventory rather than a list beside it, so a setting it adds or renames
- * shows up as a named test failure instead of quietly going missing.
- */
 export const EXPOSED_SETTING_KEYS = PRESENTATION.presented;
-/**
- * What has drifted between the settings the engine presents and the settings A1
- * maps to its API: the ones A1 has not caught up with, and the ones it kept
- * after the engine dropped them. Either is a build failure with a name in it.
- */
 export function settingsInventoryDrift(presented, mapped) {
     const has = new Set(mapped);
     const engine = new Set(presented);
@@ -47,62 +23,87 @@ export function settingsInventoryDrift(presented, mapped) {
         stale: mapped.filter(key => !engine.has(key)),
     };
 }
-/** What the engine offers for a setting, as the strings it words them with. */
 function offered(key) {
     return PRESENTATION.settings[key]?.values ?? [];
 }
-/**
- * The same, read as the numbers a numeric setting stores. Only for a setting
- * whose list is its whole domain: where the engine offers a few numbers but
- * accepts any within a range, the range governs and the list is only shortcuts.
- */
 function offeredNumbers(key) {
     return offered(key).map(value => Number.parseInt(value, 10)).filter(value => Number.isSafeInteger(value));
 }
+/**
+ * Pi settings boundary backed by the transactional settings coordinator. The
+ * generated metadata owns presentation while the reviewed effect registry owns
+ * timing, availability, and active behavior.
+ */
 export class PiSettingsIntegration {
     settings;
     capabilities = { write: true, flush: true };
     #operations;
     #providers;
+    #coordinator;
     constructor(settings, providers = {}) {
         this.settings = settings;
         this.#providers = providers;
-        this.#operations = new Map(operations(settings).map(operation => [operation.descriptor.key, operation]));
-        if (this.#operations.size !== EXPOSED_SETTING_KEYS.length || EXPOSED_SETTING_KEYS.some(key => !this.#operations.has(key))) {
-            throw new Error("Pi settings integration does not cover every A1-exposed setting");
+        const mapped = operations(settings, providers);
+        this.#operations = new Map(mapped.map(operation => [operation.key, operation]));
+        const presentationDrift = settingsInventoryDrift(EXPOSED_SETTING_KEYS, mapped.map(operation => operation.key));
+        const effectDrift = settingsEffectInventoryDrift(EXPOSED_SETTING_KEYS);
+        if (presentationDrift.unmapped.length > 0 || presentationDrift.stale.length > 0
+            || effectDrift.unmapped.length > 0 || effectDrift.stale.length > 0 || effectDrift.duplicated.length > 0) {
+            throw new Error([
+                `unmapped operations: ${presentationDrift.unmapped.join(", ")}`,
+                `stale operations: ${presentationDrift.stale.join(", ")}`,
+                `unmapped effects: ${effectDrift.unmapped.join(", ")}`,
+                `stale effects: ${effectDrift.stale.join(", ")}`,
+                `duplicated effects: ${effectDrift.duplicated.join(", ")}`,
+            ].join("; "));
         }
+        this.#coordinator = new PiSettingsCoordinator(mapped, {
+            productMode: providers.productMode ?? "bare",
+            flush: () => settings.flush(),
+            drainErrors: () => settings.drainErrors(),
+        });
+    }
+    bindOwner(owner, handlers) {
+        return this.#coordinator.bindOwner(owner, handlers);
+    }
+    unbindOwner(owner) {
+        this.#coordinator.unbindOwner(owner);
     }
     async listSettings() {
         const rank = (key) => {
             const at = PRESENTATION.order.indexOf(key);
             return at < 0 ? PRESENTATION.order.length : at;
         };
-        const listed = [...this.#operations.values()]
+        return [...this.#operations.values()]
             .map(operation => {
-            const key = operation.descriptor.key;
+            const key = operation.key;
             const wording = PRESENTATION.settings[key];
             const flags = PRESENTATION.dialogs[key];
             const bounds = PRESENTATION.bounds[key];
-            return {
+            const limitationReason = this.#coordinator.limitationReason(key);
+            const descriptor = {
                 ...operation.descriptor,
+                application: PI_SETTING_EFFECTS[key].application,
+                owner: PI_SETTING_EFFECTS[key].owner,
+                available: limitationReason === null,
+                limitationReason,
+                writable: limitationReason === null,
+                storedValue: this.#coordinator.storedValue(key),
+                effectiveValue: this.#coordinator.effectiveValue(key),
                 ...(bounds === undefined ? {} : bounds),
                 ...(wording === undefined ? {} : { label: wording.label, description: wording.description }),
                 ...(flags === undefined ? {} : { flags }),
             };
+            return this.#resolved(descriptor);
         })
-            .map(descriptor => this.#resolved(descriptor))
             .sort((left, right) => rank(left.key) - rank(right.key));
-        // Following the terminal is one choice on the theme itself, not two further
-        // settings: the pair behind it is the engine's grammar, not a reader's task.
-        return listed;
     }
-    /** Overlays the values a setting can only offer once something is running. */
     #resolved(descriptor) {
         if (descriptor.key === THEME_KEY) {
             const themes = this.#themes();
             if (themes.length === 0)
                 return descriptor;
-            return { ...descriptor, valueType: "enum", writable: true, resolvedWhenRead: true, choices: [AUTOMATIC_THEME, ...themes] };
+            return { ...descriptor, valueType: "enum", resolvedWhenRead: true, choices: [AUTOMATIC_THEME, ...themes] };
         }
         if (descriptor.key === THINKING_KEY) {
             const levels = this.#providers.thinkingLevels?.() ?? [];
@@ -115,53 +116,24 @@ export class PiSettingsIntegration {
     #themes() {
         return this.#providers.themes?.() ?? [];
     }
-    #storedTheme() {
-        const stored = this.#operations.get(THEME_KEY)?.read();
-        return typeof stored === "string" ? stored : "";
-    }
     async readSetting(key) {
-        if (key === THEME_KEY) {
-            const pair = parseAutomaticTheme(this.#storedTheme());
-            return pair === null ? this.#operations.get(key)?.read() : AUTOMATIC_THEME;
-        }
-        return this.#operations.get(key)?.read();
+        return isPiSettingKey(key) && this.#operations.has(key) ? this.#coordinator.storedValue(key) : undefined;
     }
-    async writeSetting(key, value) { this.writeSettingNow(key, value); }
-    writeSettingNow(key, value) {
-        if (typeof value === "string" && key === THEME_KEY) {
-            this.#writeTheme(value);
-            return;
-        }
-        const operation = this.#operations.get(key);
-        if (!operation)
+    async writeSetting(key, value) {
+        if (!isPiSettingKey(key) || !this.#operations.has(key))
             throw new Error(`setting is unavailable: ${key}`);
-        operation.write(value);
+        return await this.#coordinator.apply(key, value);
     }
-    /**
-     * Writes the theme in the engine's own grammar. Following the terminal is
-     * stored as the pair the engine reads for it, made of the themes named for
-     * each appearance when they are installed; where they are not, the theme
-     * already in use stands for both, so the setting still round-trips.
-     */
-    #writeTheme(value) {
-        const theme = this.#operations.get(THEME_KEY);
-        if (!theme)
-            throw new Error(`setting is unavailable: ${THEME_KEY}`);
-        if (value !== AUTOMATIC_THEME) {
-            theme.write(value);
-            return;
-        }
-        if (parseAutomaticTheme(this.#storedTheme()) !== null)
-            return;
-        const installed = this.#themes();
-        const current = this.#storedTheme();
-        const light = installed.includes(LIGHT_APPEARANCE_THEME) ? LIGHT_APPEARANCE_THEME : current;
-        const dark = installed.includes(DARK_APPEARANCE_THEME) ? DARK_APPEARANCE_THEME : current;
-        theme.write(`${light}/${dark}`);
+    /** Shared route used by the pinned selector and owned settings surface. */
+    async writeSettingNow(key, value) {
+        return await this.writeSetting(key, value);
+    }
+    async flush() {
+        await this.#coordinator.flush();
     }
-    async flush() { await this.settings.flush(); }
 }
-function operations(settings) {
+function operations(settings, providers) {
+    const themes = () => providers.themes?.() ?? [];
     return [
         bool("autoCompact", () => settings.getCompactionEnabled(), value => settings.setCompactionEnabled(value)),
         bool("showImages", () => settings.getShowImages(), value => settings.setShowImages(value)),
@@ -173,12 +145,8 @@ function operations(settings) {
         choice("followUpMode", offered("followUpMode"), () => settings.getFollowUpMode(), value => settings.setFollowUpMode(value)),
         choice("transport", offered("transport"), () => settings.getTransport(), value => settings.setTransport(value)),
         numberSetting("httpIdleTimeoutMs", () => settings.getHttpIdleTimeoutMs(), value => settings.setHttpIdleTimeoutMs(value), 0),
-        // The engine reads these from the running session rather than declaring them,
-        // so they arrive through the runtime provider rather than from its source.
         choice("thinkingLevel", ["off", "minimal", "low", "medium", "high", "xhigh"], () => settings.getDefaultThinkingLevel() ?? "medium", value => settings.setDefaultThinkingLevel(value)),
-        // The raw setting, not the resolved theme: the engine hides the automatic
-        // pair behind getTheme, and the pair is the thing A1 presents parts of.
-        stringSetting("theme", () => settings.getThemeSetting() ?? "default", value => settings.setTheme(value)),
+        themeSetting(settings, themes),
         bool("hideThinkingBlock", () => settings.getHideThinkingBlock(), value => settings.setHideThinkingBlock(value)),
         choice("mermaidRenderingMode", offered("mermaidRenderingMode"), () => settings.getMermaidRenderingMode(), value => settings.setMermaidRenderingMode(value)),
         bool("showCacheMissNotices", () => settings.getShowCacheMissNotices(), value => settings.setShowCacheMissNotices(value)),
@@ -201,33 +169,59 @@ function operations(settings) {
     ];
 }
 function bool(key, read, write) {
-    return { descriptor: { key, valueType: "boolean", writable: true }, read, write(value) { if (typeof value !== "boolean")
-            invalid(key); write(value); } };
+    return operation(key, "boolean", read, value => { if (typeof value !== "boolean")
+        invalid(key); }, value => write(value));
 }
 function numberSetting(key, read, write, minimum) {
     const declared = PRESENTATION.bounds[key];
     const low = declared?.minimum ?? minimum;
     const high = declared?.maximum;
+    return operation(key, "number", read, value => {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < low || (high !== undefined && value > high))
+            invalid(key);
+    }, value => write(value));
+}
+function jsonObject(key, read, write) {
+    const boundedRead = () => Object.fromEntries(Object.entries(read()).filter((entry) => typeof entry[1] === "boolean"));
+    return operation(key, "json", boundedRead, value => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            invalid(key);
+    }, write);
+}
+function choice(key, choices, read, write) {
     return {
-        descriptor: { key, valueType: "number", writable: true },
-        read,
-        write(value) {
-            if (typeof value !== "number" || !Number.isSafeInteger(value) || value < low || (high !== undefined && value > high))
-                invalid(key);
-            write(value);
-        },
+        ...operation(key, "enum", read, value => { if (!choices.includes(value))
+            invalid(key); }, write),
+        descriptor: { key, valueType: "enum", choices },
     };
 }
-function stringSetting(key, read, write) {
-    return { descriptor: { key, valueType: "string", writable: true }, read, write(value) { if (typeof value !== "string" || value.length === 0)
-            invalid(key); write(value); } };
+function themeSetting(settings, themes) {
+    const raw = () => settings.getThemeSetting() ?? "default";
+    const read = () => parseAutomaticTheme(raw()) === null ? raw() : AUTOMATIC_THEME;
+    return operation(THEME_KEY, "string", read, value => {
+        if (typeof value !== "string" || value.length === 0)
+            invalid(THEME_KEY);
+    }, value => {
+        const selected = value;
+        if (selected !== AUTOMATIC_THEME) {
+            settings.setTheme(selected);
+            return;
+        }
+        if (parseAutomaticTheme(raw()) !== null)
+            return;
+        const installed = themes();
+        const current = raw();
+        const light = installed.includes(LIGHT_APPEARANCE_THEME) ? LIGHT_APPEARANCE_THEME : current;
+        const dark = installed.includes(DARK_APPEARANCE_THEME) ? DARK_APPEARANCE_THEME : current;
+        settings.setTheme(`${light}/${dark}`);
+    });
 }
-function jsonObject(key, read, write) {
-    return { descriptor: { key, valueType: "json", writable: true }, read: () => Object.fromEntries(Object.entries(read()).filter((entry) => typeof entry[1] === "boolean")), write(value) { if (!value || typeof value !== "object" || Array.isArray(value))
-            invalid(key); write(value); } };
+function operation(key, valueType, read, validate, write) {
+    return { key, descriptor: { key, valueType }, read, validate, write };
 }
-function choice(key, choices, read, write) {
-    return { descriptor: { key, valueType: "enum", writable: true, choices }, read, write(value) { if (!choices.includes(value))
-            invalid(key); write(value); } };
+function isPiSettingKey(key) {
+    return Object.hasOwn(PI_SETTING_EFFECTS, key);
+}
+function invalid(key) {
+    throw new TypeError(`setting value is invalid: ${key}`);
 }
-function invalid(key) { throw new TypeError(`setting value is invalid: ${key}`); }