@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.259

package/dist/ui/components/visible-hyperlinks.js

@@ -0,0 +1,64 @@
+import { displayWidth } from "./text.js";
+const TOKENS = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|[^\u001b]+|\u001b/gu;
+const LINK = /^\u001b\]8;[^;\u0007\u001b]*;([^\u0007\u001b]*)(?:\u0007|\u001b\\)$/u;
+const SGR = /^\u001b\[[\d;:]*m$/u;
+const SEMANTIC_ZONE = /^\u001b\]133;[ABC](?:\u0007|\u001b\\)$/u;
+// Platform: this is a conservative cleanup detector, NOT a link-activation
+// parser. Hosts recognize URLs, domains and file-like labels without OSC 8.
+const CANDIDATE = /(?:[a-z][a-z\d+.-]*:\/\/[^\s<>"']+|www\.[^\s<>"']+|(?:[a-z]:[\\/]|\.{1,2}[\\/])[^\s<>"']+|[\p{L}\p{N}_-]+(?:\.\p{L}[\p{L}\p{N}_-]+)+(?:[\\/][^\s<>"']+)?)/giu;
+/**
+ * Reads final visible row geometry without decorating text. Candidate ranges
+ * only invalidate host-hover paint; they never invent an explicit link target.
+ */
+export function readVisibleHyperlinks(line, widthOf = displayWidth) {
+    const ranges = [];
+    let plain = "";
+    let column = 0;
+    let active;
+    let replaySafe = true;
+    const finish = () => {
+        if (active !== undefined && column > active.from) {
+            ranges.push({ from: active.from, to: column, target: active.target, kind: "explicit" });
+        }
+        active = undefined;
+    };
+    for (const match of line.matchAll(TOKENS)) {
+        const token = match[0];
+        if (token.startsWith("\u001b")) {
+            const link = LINK.exec(token);
+            if (link !== null) {
+                finish();
+                if (link[1])
+                    active = { from: column, target: link[1] };
+            }
+            else if (!SGR.test(token) && !SEMANTIC_ZONE.test(token))
+                replaySafe = false;
+        }
+        else {
+            if (/[\u0000-\u001f\u007f]/u.test(token))
+                replaySafe = false;
+            plain += token;
+            column += widthOf(token);
+        }
+    }
+    if (active !== undefined) {
+        replaySafe = false;
+        finish();
+    }
+    for (const match of plain.matchAll(CANDIDATE)) {
+        const from = widthOf(plain.slice(0, match.index));
+        const to = from + widthOf(match[0]);
+        if (!ranges.some(range => from < range.to && to > range.from)) {
+            ranges.push({ from, to, target: match[0], kind: "candidate" });
+        }
+    }
+    ranges.sort((left, right) => left.from - right.from);
+    return {
+        ranges,
+        replaySafe,
+        width: column,
+        // Rationale: a path with spaces or a wrapped host match may extend beyond
+        // the conservative candidate. Changes anywhere in that row invalidate it.
+        signature: ranges.length === 0 ? "" : JSON.stringify([ranges, plain]),
+    };
+}

package/dist/{src/foundation/owned-ui-settings → ui/settings}/declarations.d.ts

@@ -1,8 +1,15 @@
-export declare const OWNED_UI_SETTINGS_VERSION = 1;
+export declare const OWNED_UI_SETTINGS_VERSION = 3;
 export type OwnedUiSettingValue = string | number | boolean;
 export type OwnedUiSettingApplication = "live" | "restart";
 export interface OwnedUiSettingDeclaration {
     readonly id: string;
+    /** Optional presentation label; the id remains the persistence key. */
+    readonly label?: string;
+    /** Optional settings-screen group for related owned controls. */
+    readonly section?: {
+        readonly id: string;
+        readonly title: string;
+    };
     readonly description: string;
     readonly application: OwnedUiSettingApplication;
     readonly defaultValue: OwnedUiSettingValue;

package/dist/{src/foundation/owned-ui-settings → ui/settings}/declarations.js

@@ -1,13 +1,34 @@
-export const OWNED_UI_SETTINGS_VERSION = 1;
+export const OWNED_UI_SETTINGS_VERSION = 3;
 const MAX_ID_LENGTH = 64;
 const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
+const SCROLL_SECTION = Object.freeze({ id: "scroll", title: "Scroll" });
 export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
     Object.freeze({
-        id: "transcriptDensity",
-        description: "Vertical density of transcript content. Reserved for the custom-viewport milestone; no visible effect yet.",
+        id: "scrollbarAppearance",
+        label: "Scrollbar mode",
+        section: SCROLL_SECTION,
+        description: "When the session transcript scrollbar is visible.",
         application: "live",
-        defaultValue: "comfortable",
-        allowedValues: Object.freeze(["comfortable", "compact"]),
+        defaultValue: "auto",
+        allowedValues: Object.freeze(["auto", "always", "hidden"]),
+    }),
+    Object.freeze({
+        id: "scrollbarStyle",
+        label: "Scrollbar style",
+        section: SCROLL_SECTION,
+        description: "Visual weight of the session transcript scrollbar.",
+        application: "live",
+        defaultValue: "thin",
+        allowedValues: Object.freeze(["thin", "thick"]),
+    }),
+    Object.freeze({
+        id: "scrollbarSpeed",
+        label: "Speed",
+        section: SCROLL_SECTION,
+        description: "Distance moved by each session transcript wheel event.",
+        application: "live",
+        defaultValue: "normal",
+        allowedValues: Object.freeze(["normal", "fast", "high"]),
     }),
 ]);
 export function assertOwnedUiSettingDeclarations(declarations) {
@@ -19,6 +40,13 @@ export function assertOwnedUiSettingDeclarations(declarations) {
         if (seen.has(declaration.id))
             throw new Error(`duplicate owned UI setting id: ${declaration.id}`);
         seen.add(declaration.id);
+        if (declaration.label !== undefined && declaration.label.trim().length === 0) {
+            throw new Error(`owned UI setting has an empty label: ${declaration.id}`);
+        }
+        if (declaration.section !== undefined
+            && (declaration.section.id.trim().length === 0 || declaration.section.title.trim().length === 0)) {
+            throw new Error(`owned UI setting has an invalid section: ${declaration.id}`);
+        }
         if (declaration.description.trim().length === 0) {
             throw new Error(`owned UI setting has no description: ${declaration.id}`);
         }

package/dist/{src/foundation/owned-ui-settings → ui/settings}/migrations.d.ts

@@ -6,7 +6,7 @@ export interface OwnedUiSettingsMigration {
 }
 /**
  * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
- * is the first stored shape, so nothing precedes it and the list is empty.
+ * is the first stored shape.
  */
 export declare const OWNED_UI_SETTINGS_MIGRATIONS: readonly OwnedUiSettingsMigration[];
 export declare function assertOwnedUiSettingsMigrations(migrations: readonly OwnedUiSettingsMigration[], currentVersion?: number): void;

package/dist/{src/foundation/owned-ui-settings → ui/settings}/migrations.js

@@ -1,9 +1,28 @@
 import { OWNED_UI_SETTINGS_VERSION } from "./declarations.js";
 /**
  * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
- * is the first stored shape, so nothing precedes it and the list is empty.
+ * is the first stored shape.
  */
-export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([]);
+export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([
+    Object.freeze({
+        to: 2,
+        description: "Rename scrollbar speed high to fast.",
+        migrate(values) {
+            return values.scrollbarSpeed === "high"
+                ? { ...values, scrollbarSpeed: "fast" }
+                : { ...values };
+        },
+    }),
+    Object.freeze({
+        to: 3,
+        description: "Match Pi's auto scrollbar appearance name and ordering.",
+        migrate(values) {
+            return values.scrollbarAppearance === "hover"
+                ? { ...values, scrollbarAppearance: "auto" }
+                : { ...values };
+        },
+    }),
+]);
 export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
     const firstProduced = currentVersion - migrations.length + 1;
     if (migrations.length > 0 && firstProduced < 2) {

package/dist/{src/foundation/owned-ui-settings → ui/settings}/sections.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSettingApplicationBoundary, AgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
 import type { OwnedUiSettingValue } from "./declarations.js";
 import type { OwnedUiSettingsResolution } from "./resolution.js";
 export type OwnedUiSettingsBackend = "a1" | "agent";
@@ -9,8 +10,10 @@ export interface OwnedUiSettingsEntry {
     readonly description: string | null;
     /** Present when the value is a scalar the surface can offer as a choice. */
     readonly value: OwnedUiSettingValue | null;
-    /** Raw value as reported by its backend, for entries the surface can only display. */
+    /** Raw stored value as reported by its backend, for entries the surface can only display. */
     readonly rawValue: unknown;
+    readonly storedValue: unknown;
+    readonly effectiveValue: unknown;
     readonly editable: boolean;
     readonly choices: readonly OwnedUiSettingValue[] | null;
     /** True when the value is a structured object edited through its own surface. */
@@ -26,7 +29,7 @@ export interface OwnedUiSettingsEntry {
         readonly fallback: boolean;
     }[];
     readonly origin: "default" | "stored" | "engine";
-    readonly application: "live" | "restart" | "engine";
+    readonly application: AgentSettingApplicationBoundary;
 }
 export interface OwnedUiSettingsSection {
     readonly id: string;
@@ -38,23 +41,7 @@ export interface OwnedUiSettingsSection {
     readonly readOnlyReason: string | null;
 }
 export interface AgentSettingsSnapshot {
-    readonly descriptors: readonly {
-        readonly key: string;
-        readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
-        readonly writable: boolean;
-        readonly choices?: readonly unknown[];
-        readonly label?: string;
-        readonly description?: string;
-        readonly minimum?: number;
-        readonly maximum?: number;
-        readonly flags?: readonly {
-            readonly key: string;
-            readonly label: string;
-            readonly description: string;
-            readonly fallback: boolean;
-        }[];
-    }[];
-    readonly values: Readonly<Record<string, unknown>>;
+    readonly descriptors: readonly AgentSettingDescriptor[];
     /** Whether the engine advertises settings write capability at all. */
     readonly writeAdvertised: boolean;
     /** Set when the engine could not report its settings. */

package/dist/{src/foundation/owned-ui-settings → ui/settings}/sections.js

@@ -1,16 +1,19 @@
 export const AGENT_SECTION_ID = "agent";
 const BOOLEAN_CHOICES = Object.freeze([true, false]);
 export function buildOwnedUiSettingsSections(input) {
-    const ownedSection = {
-        id: "a1",
-        title: "A1",
-        entries: Object.freeze(input.resolution.settings.map(setting => ({
+    const grouped = new Map();
+    for (const setting of input.resolution.settings) {
+        const section = setting.declaration.section ?? { id: "a1", title: "A1" };
+        const group = grouped.get(section.id) ?? { title: section.title, entries: [] };
+        group.entries.push({
             id: setting.declaration.id,
-            label: null,
+            label: setting.declaration.label ?? null,
             backend: "a1",
             description: setting.declaration.description,
             value: setting.value,
             rawValue: setting.value,
+            storedValue: setting.value,
+            effectiveValue: setting.value,
             editable: true,
             structured: false,
             minimum: null,
@@ -18,12 +21,18 @@ export function buildOwnedUiSettingsSections(input) {
             flags: [],
             choices: setting.declaration.allowedValues,
             origin: setting.source,
-            application: setting.declaration.application,
-        }))),
+            application: setting.declaration.application === "restart" ? "next-start" : "live",
+        });
+        grouped.set(section.id, group);
+    }
+    const ownedSections = [...grouped].map(([id, group]) => ({
+        id,
+        title: group.title,
+        entries: Object.freeze(group.entries),
         unavailableReason: null,
         readOnlyReason: null,
-    };
-    return Object.freeze([ownedSection, agentSection(input.agent)]);
+    }));
+    return Object.freeze([...ownedSections, agentSection(input.agent)]);
 }
 export function findOwnedUiSettingsEntry(sections, id, backend) {
     for (const section of sections) {
@@ -41,10 +50,13 @@ function agentSection(snapshot) {
         return frozenSection(`Agent settings are unavailable: ${snapshot.failure}`, null, []);
     }
     if (snapshot.descriptors.length === 0) {
-        return frozenSection("The agent engine reported no settings", null, []);
+        return { id: AGENT_SECTION_ID, title: "Agent", entries: Object.freeze([]), unavailableReason: null, readOnlyReason: null };
     }
-    const entries = snapshot.descriptors.map(descriptor => {
-        const raw = Object.hasOwn(snapshot.values, descriptor.key) ? snapshot.values[descriptor.key] : null;
+    const presented = snapshot.writeAdvertised
+        ? snapshot.descriptors.filter(descriptor => descriptor.writable && descriptor.available)
+        : [];
+    const entries = presented.map(descriptor => {
+        const raw = descriptor.storedValue;
         return {
             id: descriptor.key,
             label: descriptor.label ?? null,
@@ -52,31 +64,28 @@ function agentSection(snapshot) {
             description: descriptor.description ?? null,
             value: scalar(raw),
             rawValue: raw,
-            // A structured value is editable through its own surface rather than a
-            // value menu, so it stays reachable instead of being reported as fixed.
-            editable: snapshot.writeAdvertised && descriptor.writable,
+            storedValue: descriptor.storedValue,
+            effectiveValue: descriptor.effectiveValue,
+            // Invariant: unavailable and non-writable descriptors are filtered before projection.
+            // Every presented structured value remains editable through its own surface.
+            editable: true,
             structured: descriptor.valueType === "json",
             minimum: descriptor.minimum ?? null,
             maximum: descriptor.maximum ?? null,
             flags: descriptor.flags ?? [],
-            // A boolean is a two-value choice even when the engine names no choices,
+            // Protocol: a boolean is a two-value choice even when the engine names no choices,
             // so it opens the same menu as any other enumerated setting.
             choices: descriptor.valueType === "boolean" ? BOOLEAN_CHOICES : choicesOf(descriptor.choices),
             origin: "engine",
-            application: "engine",
+            application: descriptor.application,
         };
     });
-    const readOnlyReason = snapshot.writeAdvertised
-        ? (entries.some(entry => entry.editable)
-            ? null
-            : "The agent engine reports no writable settings")
-        : "The agent engine does not support changing settings from this surface";
     return {
         id: AGENT_SECTION_ID,
         title: "Agent",
         entries: Object.freeze(entries),
         unavailableReason: null,
-        readOnlyReason,
+        readOnlyReason: null,
     };
 }
 function frozenSection(unavailableReason, readOnlyReason, entries) {

package/dist/{src/foundation/owned-ui-settings → ui/settings}/session.d.ts

@@ -1,44 +1,36 @@
-import type { AgentSettingsPort } from "../agent-engine-contracts/index.js";
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingsPort } from "../../contracts/agent-engine/index.js";
 import type { OwnedUiSettingValue } from "./declarations.js";
 import type { OwnedUiSettingsResolution } from "./resolution.js";
 import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
 import type { OwnedUiSettingsStore } from "./store.js";
 export interface OwnedUiSettingsChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
     readonly applied: boolean;
-    /** True when the value is stored but only takes effect on the next start. */
+    /** Compatibility projection for existing A1 restart-bound declarations. */
     readonly pendingRestart: boolean;
-    /** Present when the change could not be persisted; the surface must not show it as saved. */
+    readonly application: AgentSettingApplicationBoundary | null;
+    readonly storedValue: AgentJsonValue | null;
+    readonly effectiveValue: AgentJsonValue | null;
+    readonly limitationReason: string | null;
     readonly failure: string | null;
 }
 export interface OwnedUiSettingsSessionOptions {
     readonly store: OwnedUiSettingsStore;
-    /** Null when no engine is attached; the Agent section then reports itself unavailable. */
     readonly agent?: AgentSettingsPort | null;
-    /**
-     * Resolves the port at load time instead of construction time, for an engine
-     * whose runtime is not up yet. Takes precedence over `agent`.
-     */
     readonly agentProvider?: () => AgentSettingsPort | null;
+    readonly hiddenAgentSettingIds?: readonly string[];
 }
 export type OwnedUiSettingsListener = (session: OwnedUiSettingsSession) => void;
-/**
- * Holds the resolved settings for one owned UI session and routes every accepted
- * change to the backend that owns it: A1 settings to the A1 document, agent
- * settings to the engine settings port. Neither backend ever sees the other's value.
- */
+/** Routes every accepted setting change only to its owning backend. */
 export declare class OwnedUiSettingsSession {
     #private;
     constructor(options: OwnedUiSettingsSessionOptions);
     get resolution(): OwnedUiSettingsResolution;
-    /** Reads the engine's settings so the Agent section can be built. Never throws. */
     load(): Promise<void>;
     sections(): readonly OwnedUiSettingsSection[];
-    /** Resolved value of an A1 setting, or null when it is not declared. */
     value(id: string): OwnedUiSettingValue | null;
-    /** Value stored this session but not yet in effect, for a restart-required setting. */
     pendingValue(id: string): OwnedUiSettingValue | null;
     onChange(listener: OwnedUiSettingsListener): () => void;
-    /** Writes a structured value, which only an engine-backed setting can hold. */
     changeStructured(backend: OwnedUiSettingsBackend, id: string, value: Readonly<Record<string, unknown>>): Promise<OwnedUiSettingsChangeOutcome>;
     change(backend: OwnedUiSettingsBackend, id: string, value: OwnedUiSettingValue): Promise<OwnedUiSettingsChangeOutcome>;
 }

package/dist/{src/foundation/owned-ui-settings → ui/settings}/session.js

@@ -1,14 +1,12 @@
+import { assertAgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
 import { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
-/**
- * Holds the resolved settings for one owned UI session and routes every accepted
- * change to the backend that owns it: A1 settings to the A1 document, agent
- * settings to the engine settings port. Neither backend ever sees the other's value.
- */
+/** Routes every accepted setting change only to its owning backend. */
 export class OwnedUiSettingsSession {
     #store;
     #agent;
     #agentProvider;
     #listeners = new Set();
+    #hiddenAgentSettingIds;
     #resolution;
     #agentSnapshot = null;
     #pending = new Map();
@@ -16,26 +14,24 @@ export class OwnedUiSettingsSession {
         this.#store = options.store;
         this.#agent = options.agent ?? null;
         this.#agentProvider = options.agentProvider ?? null;
+        this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
         this.#resolution = options.store.read();
     }
     get resolution() {
         return this.#resolution;
     }
-    /** Reads the engine's settings so the Agent section can be built. Never throws. */
     async load() {
         this.#resolution = this.#store.read();
-        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
-        this.#agentSnapshot = agent === null ? null : await snapshotOf(agent);
+        const agent = this.#currentAgent();
+        this.#agentSnapshot = agent === null ? null : await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
     }
     sections() {
         return buildOwnedUiSettingsSections({ resolution: this.#resolution, agent: this.#agentSnapshot });
     }
-    /** Resolved value of an A1 setting, or null when it is not declared. */
     value(id) {
         return this.#resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
     }
-    /** Value stored this session but not yet in effect, for a restart-required setting. */
     pendingValue(id) {
         return this.#pending.get(id) ?? null;
     }
@@ -43,27 +39,10 @@ export class OwnedUiSettingsSession {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
-    /** Writes a structured value, which only an engine-backed setting can hold. */
     async changeStructured(backend, id, value) {
         if (backend !== "agent")
             return failed("only an agent setting holds a structured value");
-        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
-        if (agent === null)
-            return failed("no agent engine is attached");
-        if (!agent.capabilities.write || !agent.writeSetting) {
-            return failed("the agent engine does not support changing settings from this surface");
-        }
-        try {
-            await agent.writeSetting(id, value);
-            if (agent.capabilities.flush && agent.flush)
-                await agent.flush();
-        }
-        catch (error) {
-            return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
-        }
-        this.#agentSnapshot = await snapshotOf(agent);
-        this.#notify();
-        return { applied: true, pendingRestart: false, failure: null };
+        return await this.#changeAgentValue(id, value);
     }
     async change(backend, id, value) {
         const entry = findOwnedUiSettingsEntry(this.sections(), id, backend);
@@ -71,7 +50,7 @@ export class OwnedUiSettingsSession {
             return failed(`unknown ${backend} setting: ${id}`);
         if (!entry.editable)
             return failed(`${id} is not editable from this surface`);
-        return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgent(id, value);
+        return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
         const outcome = this.#store.write(this.#resolution, id, value);
@@ -79,66 +58,97 @@ export class OwnedUiSettingsSession {
             return failed(outcome.failure ?? `${id} could not be stored`);
         const previous = this.#resolution;
         this.#resolution = this.#store.read();
-        const declaration = previous.settings.find(setting => setting.declaration.id === id)?.declaration;
-        if (declaration?.application === "restart") {
+        const previousSetting = previous.settings.find(setting => setting.declaration.id === id);
+        if (previousSetting?.declaration.application === "restart") {
             this.#pending.set(id, value);
             this.#resolution = previous;
             this.#notify();
-            return { applied: false, pendingRestart: true, failure: null };
+            return changed("deferred", "next-start", value, previousSetting.value);
         }
         this.#pending.delete(id);
         this.#notify();
-        return { applied: true, pendingRestart: false, failure: null };
+        return changed("applied", "live", value, value);
     }
-    async #changeAgent(id, value) {
-        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
+    async #changeAgentValue(id, value) {
+        const agent = this.#currentAgent();
         if (agent === null)
             return failed("no agent engine is attached");
         if (!agent.capabilities.write || !agent.writeSetting) {
             return failed("the agent engine does not support changing settings from this surface");
         }
+        let result;
         try {
-            await agent.writeSetting(id, value);
-            if (agent.capabilities.flush && agent.flush)
-                await agent.flush();
+            // Invariant: the coordinator behind the port owns effect installation, persistence,
+            // flush, and rollback. A second surface-level flush would split authority.
+            result = await agent.writeSetting(id, value);
         }
         catch (error) {
             return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
         }
-        this.#agentSnapshot = await snapshotOf(agent);
+        this.#agentSnapshot = await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
-        return { applied: true, pendingRestart: false, failure: null };
+        return fromAgentOutcome(result);
+    }
+    #currentAgent() {
+        return this.#agentProvider === null ? this.#agent : this.#agentProvider();
     }
     #notify() {
         for (const listener of this.#listeners)
             listener(this);
     }
 }
-async function snapshotOf(agent) {
+async function snapshotOf(agent, hidden) {
     try {
-        const descriptors = await agent.listSettings();
-        const values = {};
-        for (const descriptor of descriptors) {
-            try {
-                values[descriptor.key] = await agent.readSetting(descriptor.key) ?? null;
-            }
-            catch {
-                values[descriptor.key] = null;
-            }
-        }
+        const listed = await agent.listSettings();
+        for (const descriptor of listed)
+            assertAgentSettingDescriptor(descriptor);
+        const writeAdvertised = agent.capabilities.write && typeof agent.writeSetting === "function";
+        const descriptors = listed.filter(descriptor => !hidden.has(descriptor.key) && writeAdvertised && descriptor.writable && descriptor.available);
         return {
             descriptors,
-            values,
-            writeAdvertised: agent.capabilities.write && typeof agent.writeSetting === "function",
+            writeAdvertised,
             failure: null,
         };
     }
     catch (error) {
-        return { descriptors: [], values: {}, writeAdvertised: false, failure: describe(error) };
+        return { descriptors: [], writeAdvertised: false, failure: describe(error) };
     }
 }
 function failed(failure) {
-    return { applied: false, pendingRestart: false, failure };
+    return {
+        status: "failed",
+        applied: false,
+        pendingRestart: false,
+        application: null,
+        storedValue: null,
+        effectiveValue: null,
+        limitationReason: null,
+        failure,
+    };
+}
+function changed(status, application, storedValue, effectiveValue) {
+    return {
+        status,
+        applied: status === "applied",
+        pendingRestart: status === "deferred" && application === "next-start",
+        application,
+        storedValue,
+        effectiveValue,
+        limitationReason: null,
+        failure: null,
+    };
+}
+function fromAgentOutcome(result) {
+    return {
+        status: result.status,
+        applied: result.status === "applied",
+        pendingRestart: result.status === "deferred" && result.application === "next-start",
+        application: result.application,
+        storedValue: result.storedValue,
+        effectiveValue: result.effectiveValue,
+        limitationReason: result.limitationReason,
+        failure: result.failure,
+    };
 }
 function describe(error) {
     return error instanceof Error ? error.message : String(error);

package/dist/{src/foundation/owned-ui-settings → ui/settings}/store.d.ts

@@ -13,6 +13,7 @@ export interface OwnedUiSettingsWriteOutcome {
     /** Present when the write failed; the caller must not report the change as saved. */
     readonly failure: string | null;
 }
+/** Resolves and atomically persists one profile's owned settings without discarding unknown keys. */
 export declare class OwnedUiSettingsStore {
     #private;
     constructor(options: OwnedUiSettingsStoreOptions);

package/dist/{src/foundation/owned-ui-settings → ui/settings}/store.js

@@ -5,6 +5,7 @@ import { OWNED_UI_SETTINGS_MIGRATIONS } from "./migrations.js";
 import { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
 const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DOCUMENT_BYTES = 256 * 1024;
+/** Resolves and atomically persists one profile's owned settings without discarding unknown keys. */
 export class OwnedUiSettingsStore {
     #file;
     #declarations;
@@ -76,7 +77,7 @@ export class OwnedUiSettingsStore {
                 rmSync(temporary, { force: true });
             }
             catch {
-                // A leftover temporary file is inert: read() only ever opens the target path.
+                // Security: a leftover temporary file is inert: read() only ever opens the target path.
             }
             return { stored: false, failure: `${this.#file} could not be written: ${describe(error)}` };
         }