@timurproko/a1 0.2.7-dev.746 → 0.2.7-dev.767

package/dist/ui/components/line-input.d.ts

@@ -56,7 +56,7 @@ export declare function caretCell(text: string): string;
 export interface InputRowOptions {
     /** Shown quietly while nothing has been typed, with the caret on its first cell. */
     readonly placeholder?: string;
-    /** Rules above and below, in the prompt's own grey. Default true. */
+    /** Theme-border rules. */
     readonly ruled?: boolean;
     /** Prompt marker including any following spacing. Defaults to the shared prompt glyph. */
     readonly promptGlyph?: string;

package/dist/ui/components/prompt-input.d.ts

@@ -1,9 +1,10 @@
 import { type UiTheme } from "./theme.js";
 export declare const PROMPT_GLYPH = "\u276F ";
 export declare const PROMPT_PREFIX_WIDTH = 2;
-export declare function promptRuleText(text: string): string;
-export declare function promptRule(width: number): string;
-export declare function promptArrow(text: string, theme: Pick<UiTheme, "fg">): string;
+type RuleTheme = Pick<UiTheme, "fg">;
+export declare function promptRuleText(text: string, theme: RuleTheme): string;
+export declare function promptRule(width: number, theme: RuleTheme): string;
+export declare function promptArrow(text: string, theme: RuleTheme): string;
 export interface PromptInputBody {
     readonly rows: readonly string[];
     /** Semantic border fragments retain editor history and scroll annotations. */
@@ -19,9 +20,9 @@ export interface PromptInputMetrics {
 }
 /** Composes shared input chrome around controller-owned body rows without owning editing state. */
 export declare class PromptInput {
-    readonly theme: Pick<UiTheme, "fg">;
+    readonly theme: RuleTheme;
     readonly metrics: PromptInputMetrics;
-    constructor(theme?: Pick<UiTheme, "fg">, metrics?: PromptInputMetrics);
+    constructor(theme?: RuleTheme, metrics?: PromptInputMetrics);
     styleRule(text: string): string;
     geometry(width: number, padding?: number, promptGlyph?: string): {
         prefixWidth: number;
@@ -32,3 +33,4 @@ export declare class PromptInput {
     };
     render(width: number, renderBody: (innerWidth: number) => PromptInputBody, ruled?: boolean, padding?: number, promptGlyph?: string): string[];
 }
+export {};

package/dist/ui/components/prompt-input.js

@@ -2,11 +2,11 @@ import { displayWidth, truncateToWidth } from "./text.js";
 import { PLAIN_THEME } from "./theme.js";
 export const PROMPT_GLYPH = "❯ ";
 export const PROMPT_PREFIX_WIDTH = 2;
-export function promptRuleText(text) {
-    return `\u001b[38;2;154;160;166m${text}\u001b[39m`;
+export function promptRuleText(text, theme) {
+    return theme.fg("border", text);
 }
-export function promptRule(width) {
-    return promptRuleText("─".repeat(Math.max(0, width)));
+export function promptRule(width, theme) {
+    return promptRuleText("─".repeat(Math.max(0, width)), theme);
 }
 export function promptArrow(text, theme) {
     return theme.fg("muted", text);
@@ -16,7 +16,7 @@ export class PromptInput {
     theme;
     metrics;
     constructor(theme = PLAIN_THEME, metrics = { measure: displayWidth, truncate: truncateToWidth }) { this.theme = theme; this.metrics = metrics; }
-    styleRule(text) { return promptRuleText(text); }
+    styleRule(text) { return promptRuleText(text, this.theme); }
     geometry(width, padding = 0, promptGlyph = PROMPT_GLYPH) {
         const prefixWidth = Math.min(this.metrics.measure(promptGlyph), Math.max(0, width));
         // Compatibility: editor wrapping needs room for a two-cell grapheme plus its cursor cell.
@@ -43,8 +43,8 @@ export class PromptInput {
             ? promptArrow(promptGlyph, this.theme)
             : " ".repeat(prefixWidth)}${row}`));
         const rule = (fragment) => fragment === undefined
-            ? promptRule(width)
-            : fit(fragment + promptRule(Math.max(0, width - this.metrics.measure(fragment))));
+            ? promptRule(width, this.theme)
+            : fit(fragment + promptRule(Math.max(0, width - this.metrics.measure(fragment)), this.theme));
         return [
             ...(ruled ? [rule(body.topRule)] : []),
             ...rows,

package/dist/ui/settings/declarations.d.ts

@@ -1,4 +1,4 @@
-export declare const OWNED_UI_SETTINGS_VERSION = 14;
+export declare const OWNED_UI_SETTINGS_VERSION = 15;
 export type OwnedUiSettingValue = string | number | boolean;
 export type OwnedUiSettingApplication = "live" | "restart";
 export interface OwnedUiSettingDeclaration {
@@ -171,11 +171,47 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
             id: "generic";
             title: "Generic";
         }>;
-        description: "Keep bare A1 running when its terminal closes and reattach on the next launch. Resident tabs have no stop command yet; turning this off prevents new resident launches but does not stop an existing tab.";
+        description: "Keep bare A1 running when its terminal closes and reattach on the next launch. Turning this off prevents new resident launches but does not stop existing tabs.";
         application: "restart";
         defaultValue: false;
         allowedValues: readonly [true, false];
     }>;
+    readonly tabsMaxConcurrentStarts: Readonly<{
+        id: "tabsMaxConcurrentStarts";
+        label: "Concurrent tab starts";
+        section: Readonly<{
+            id: "generic";
+            title: "Generic";
+        }>;
+        description: "Maximum A1 tabs started together. Starts remain spaced to protect shared profile files.";
+        application: "restart";
+        defaultValue: 2;
+        allowedValues: readonly [1, 2, 3, 4, 5, 6, 7, 8];
+    }>;
+    readonly tabsUnresponsiveRestartSeconds: Readonly<{
+        id: "tabsUnresponsiveRestartSeconds";
+        label: "Unresponsive tab restart";
+        section: Readonly<{
+            id: "generic";
+            title: "Generic";
+        }>;
+        description: "Seconds of continuously healthy supervision without a tab heartbeat before A1 restarts that tab.";
+        application: "restart";
+        defaultValue: 120;
+        allowedValues: readonly [60, 120, 300, 600];
+    }>;
+    readonly tabsStallNoticeSeconds: Readonly<{
+        id: "tabsStallNoticeSeconds";
+        label: "Tab stall notice";
+        section: Readonly<{
+            id: "generic";
+            title: "Generic";
+        }>;
+        description: "Seconds without model or tool progress before a working tab shows a stall notice; A1 never kills a stalled tab automatically.";
+        application: "restart";
+        defaultValue: 300;
+        allowedValues: readonly [120, 300, 600, 1800];
+    }>;
 }>;
 export type OwnedSettingId = keyof typeof OWNED_SETTING_DECLARATIONS;
 /** The value type a setting's declaration allows: a literal union for a choice, `number` for a stepped range. */

package/dist/ui/settings/declarations.js

@@ -1,4 +1,4 @@
-export const OWNED_UI_SETTINGS_VERSION = 14;
+export const OWNED_UI_SETTINGS_VERSION = 15;
 const UI_ACCENT_COLOR_CHOICES = Object.freeze([
     "purple", "blue", "cyan", "green", "orange", "pink",
 ]);
@@ -128,11 +128,38 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         id: "residentTabs",
         label: "Resident tabs",
         section: GENERIC_SECTION,
-        description: "Keep bare A1 running when its terminal closes and reattach on the next launch. Resident tabs have no stop command yet; turning this off prevents new resident launches but does not stop an existing tab.",
+        description: "Keep bare A1 running when its terminal closes and reattach on the next launch. Turning this off prevents new resident launches but does not stop existing tabs.",
         application: "restart",
         defaultValue: false,
         allowedValues: Object.freeze([true, false]),
     }),
+    tabsMaxConcurrentStarts: Object.freeze({
+        id: "tabsMaxConcurrentStarts",
+        label: "Concurrent tab starts",
+        section: GENERIC_SECTION,
+        description: "Maximum A1 tabs started together. Starts remain spaced to protect shared profile files.",
+        application: "restart",
+        defaultValue: 2,
+        allowedValues: Object.freeze([1, 2, 3, 4, 5, 6, 7, 8]),
+    }),
+    tabsUnresponsiveRestartSeconds: Object.freeze({
+        id: "tabsUnresponsiveRestartSeconds",
+        label: "Unresponsive tab restart",
+        section: GENERIC_SECTION,
+        description: "Seconds of continuously healthy supervision without a tab heartbeat before A1 restarts that tab.",
+        application: "restart",
+        defaultValue: 120,
+        allowedValues: Object.freeze([60, 120, 300, 600]),
+    }),
+    tabsStallNoticeSeconds: Object.freeze({
+        id: "tabsStallNoticeSeconds",
+        label: "Tab stall notice",
+        section: GENERIC_SECTION,
+        description: "Seconds without model or tool progress before a working tab shows a stall notice; A1 never kills a stalled tab automatically.",
+        application: "restart",
+        defaultValue: 300,
+        allowedValues: Object.freeze([120, 300, 600, 1800]),
+    }),
 });
 /** The declarations in declaration order, for resolution, persistence, and the settings screen. */
 export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze(Object.values(OWNED_SETTING_DECLARATIONS));

package/dist/ui/settings/index.d.ts

@@ -1,10 +1,12 @@
 export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
 export type { OwnedSettingId, OwnedSettingValueOf, OwnedUiSettingApplication, OwnedUiSettingDeclaration, OwnedUiSettingValue } from "./declarations.js";
-export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
-export type { OwnedUiSettingsMigration } from "./migrations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom, normalizeOwnedUiSettingsValues, } from "./migrations.js";
+export type { OwnedUiSettingsCompatibilityResult, OwnedUiSettingsMigration } from "./migrations.js";
 export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, resolveResidentTabsSetting, settingValue } from "./resolution.js";
 export type { OwnedUiResolvedSetting, OwnedUiSettingSource, OwnedUiSettingsDocument, OwnedUiSettingsNotice, OwnedUiSettingsNoticeCode, OwnedUiSettingsResolution, ResolveOwnedUiSettingsInput, } from "./resolution.js";
 export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
 export type { AgentSettingsSnapshot, BuildOwnedUiSettingsSectionsInput, OwnedUiSettingsBackend, OwnedUiSettingsEntry, OwnedUiSettingsSection, } from "./sections.js";
 export { OwnedSettingsManager } from "./manager.js";
 export type { OwnedSettingsManagerOptions, OwnedUiSettingsChangeOutcome, OwnedUiSettingsListener } from "./manager.js";
+export { assertProfileSettingsNamespaceAvailable, readProfileSettingsNamespace, repairProfileSettingsDocument, updateProfileSettingsNamespace, } from "./profile-document.js";
+export type { ProfileSettingsNamespaceRead, ProfileSettingsNamespaceUpdate } from "./profile-document.js";

package/dist/ui/settings/index.js

@@ -1,5 +1,6 @@
 export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
-export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom, normalizeOwnedUiSettingsValues, } from "./migrations.js";
 export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, resolveResidentTabsSetting, settingValue } from "./resolution.js";
 export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
 export { OwnedSettingsManager } from "./manager.js";
+export { assertProfileSettingsNamespaceAvailable, readProfileSettingsNamespace, repairProfileSettingsDocument, updateProfileSettingsNamespace, } from "./profile-document.js";

package/dist/ui/settings/manager.d.ts

@@ -4,9 +4,15 @@ import { type OwnedUiSettingsMigration } from "./migrations.js";
 import { type OwnedUiSettingsResolution } from "./resolution.js";
 import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
 export interface OwnedSettingsManagerOptions {
-    /** A1 configuration root. Settings live under `<configDir>/settings/`. */
-    readonly configDir: string;
+    /** Selected global agent profile containing the shared `settings.json`. */
+    readonly profileDir?: string;
+    /** Compatibility alias for SDK/tests that supplied the former root option. */
+    readonly configDir?: string;
     readonly profileId: string;
+    /** Product namespace; defaults to profileId for generic and hermetic consumers. */
+    readonly namespace?: string;
+    /** Former product configuration root, consulted only while the namespace is absent. */
+    readonly legacyConfigDir?: string;
     readonly declarations?: readonly OwnedUiSettingDeclaration[];
     readonly migrations?: readonly OwnedUiSettingsMigration[];
     readonly agent?: AgentSettingsPort | null;
@@ -37,7 +43,7 @@ export declare class OwnedSettingsManager {
     constructor(options: OwnedSettingsManagerOptions);
     get file(): string;
     get resolution(): OwnedUiSettingsResolution;
-    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    /** Reads and resolves the product namespace. Never throws: every failure becomes a notice. */
     read(): OwnedUiSettingsResolution;
     load(): Promise<void>;
     sections(): readonly OwnedUiSettingsSection[];

package/dist/ui/settings/manager.js

@@ -1,10 +1,11 @@
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { assertAgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
 import { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, } from "./declarations.js";
-import { OWNED_UI_SETTINGS_MIGRATIONS } from "./migrations.js";
-import { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
+import { OWNED_UI_SETTINGS_MIGRATIONS, normalizeOwnedUiSettingsValues, } from "./migrations.js";
+import { parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
 import { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
+import { readProfileSettingsNamespace, repairProfileSettingsDocument, updateProfileSettingsNamespace, } from "./profile-document.js";
 const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DOCUMENT_BYTES = 256 * 1024;
 /**
@@ -15,6 +16,8 @@ const MAX_DOCUMENT_BYTES = 256 * 1024;
  */
 export class OwnedSettingsManager {
     #file;
+    #legacyFile;
+    #namespace;
     #declarations;
     #migrations;
     #agent;
@@ -30,7 +33,14 @@ export class OwnedSettingsManager {
         if (!PROFILE_ID_PATTERN.test(options.profileId)) {
             throw new Error(`owned UI settings profile id is not a bounded slug: ${options.profileId}`);
         }
-        this.#file = path.join(path.resolve(options.configDir), "settings", `${options.profileId}.json`);
+        const profileDir = options.profileDir ?? options.configDir;
+        if (profileDir === undefined)
+            throw new Error("owned UI settings require a profile directory");
+        this.#file = path.join(path.resolve(profileDir), "settings.json");
+        this.#legacyFile = options.legacyConfigDir === undefined
+            ? null
+            : path.join(path.resolve(options.legacyConfigDir), "settings", `${options.profileId}.json`);
+        this.#namespace = options.namespace ?? options.profileId;
         this.#declarations = options.declarations ?? OWNED_UI_SETTING_DECLARATIONS;
         this.#migrations = options.migrations ?? OWNED_UI_SETTINGS_MIGRATIONS;
         this.#agent = options.agent ?? null;
@@ -49,24 +59,59 @@ export class OwnedSettingsManager {
     get resolution() {
         return this.#resolution;
     }
-    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    /** Reads and resolves the product namespace. Never throws: every failure becomes a notice. */
     read() {
+        try {
+            repairProfileSettingsDocument(this.#file);
+        }
+        catch {
+            // Compatibility: recovery is opportunistic; unreadable-document handling stays authoritative.
+        }
+        const shared = readProfileSettingsNamespace(this.#file, this.#namespace);
+        if (shared.status === "available") {
+            if (Buffer.byteLength(JSON.stringify(shared.value), "utf8") > MAX_DOCUMENT_BYTES) {
+                return this.#resolveNamespace(null, `${this.#file} contains a ${this.#namespace} namespace exceeding the ${MAX_DOCUMENT_BYTES}-byte settings limit`);
+            }
+            return this.#resolveCompatibleNamespace(shared.value);
+        }
+        if (shared.status === "invalid")
+            return this.#resolveNamespace(null, shared.detail);
+        return this.#readLegacy();
+    }
+    #resolveCompatibleNamespace(values) {
+        const compatibility = normalizeOwnedUiSettingsValues(values);
+        return compatibility.values === null
+            ? this.#resolveNamespace(null, compatibility.failure ?? "product settings compatibility failed")
+            : this.#resolveNamespace(compatibility.values);
+    }
+    #resolveNamespace(values, unreadableDetail) {
+        return resolveOwnedUiSettings({
+            declarations: this.#declarations,
+            migrations: [],
+            document: values === null ? null : { version: OWNED_UI_SETTINGS_VERSION, values },
+            ...(unreadableDetail === undefined ? {} : { unreadableDetail }),
+            currentVersion: OWNED_UI_SETTINGS_VERSION,
+        });
+    }
+    #readLegacy() {
+        if (this.#legacyFile === null)
+            return this.#resolveNamespace(null);
         let raw = null;
         let unreadable = null;
         try {
-            raw = readFileSync(this.#file, "utf8");
+            raw = readFileSync(this.#legacyFile, "utf8");
         }
         catch (error) {
             if (!isMissing(error))
-                unreadable = `${this.#file} could not be read: ${describe(error)}`;
+                unreadable = `${this.#legacyFile} could not be read: ${describe(error)}`;
         }
         if (raw !== null && Buffer.byteLength(raw, "utf8") > MAX_DOCUMENT_BYTES) {
-            unreadable = `${this.#file} exceeds the ${MAX_DOCUMENT_BYTES}-byte settings limit and was ignored`;
+            unreadable = `${this.#legacyFile} exceeds the ${MAX_DOCUMENT_BYTES}-byte settings limit and was ignored`;
             raw = null;
         }
         const document = raw === null ? null : parseOwnedUiSettingsDocument(raw);
         if (raw !== null && document === null && unreadable === null) {
-            unreadable = `${this.#file} is not a valid settings document and was ignored`;
+            unreadable = `${this.#legacyFile} is not a valid settings document and was ignored`;
         }
         return resolveOwnedUiSettings({
             declarations: this.#declarations,
@@ -126,7 +171,7 @@ export class OwnedSettingsManager {
         return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
-        const outcome = this.#write(this.#resolution, id, value);
+        const outcome = this.#write(id, value);
         if (!outcome.stored)
             return failed(outcome.failure ?? `${id} could not be stored`);
         const previous = this.#resolution;
@@ -141,35 +186,34 @@ export class OwnedSettingsManager {
         this.#notify();
         return changed("applied", "live", value, value);
     }
-    // Invariant: the resolved form is written with `id` set to `value` and undeclared keys preserved.
-    // Concurrency: a temporary sibling is renamed over the target, so an interrupted write leaves
-    // either the complete previous document or the complete new one.
-    #write(resolution, id, value) {
+    // Invariant: only non-default declared values and unknown product properties are stored.
+    // Concurrency: the namespace updater rereads current JSON while holding Pi's compatible lock.
+    #write(id, value) {
         const declaration = this.#declarations.find(candidate => candidate.id === id);
         if (!declaration)
             return { stored: false, failure: `unknown owned UI setting: ${id}` };
         if (!declaration.allowedValues.includes(value)) {
             return { stored: false, failure: `value ${JSON.stringify(value)} is not allowed for ${id}` };
         }
-        const current = documentFrom(resolution);
-        const next = {
-            version: OWNED_UI_SETTINGS_VERSION,
-            values: { ...current.values, [id]: value },
-        };
-        const temporary = `${this.#file}.${process.pid}.tmp`;
         try {
-            mkdirSync(path.dirname(this.#file), { recursive: true, mode: 0o700 });
-            writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-            renameSync(temporary, this.#file);
+            updateProfileSettingsNamespace(this.#file, this.#namespace, current => {
+                let latest = this.#readLegacy();
+                if (current !== null) {
+                    const compatibility = normalizeOwnedUiSettingsValues(current);
+                    if (compatibility.values === null)
+                        throw new Error(compatibility.failure ?? "product settings compatibility failed");
+                    latest = this.#resolveNamespace(compatibility.values);
+                }
+                const next = compactValues(latest);
+                if (value === declaration.defaultValue)
+                    delete next[id];
+                else
+                    next[id] = value;
+                return Object.keys(next).length === 0 ? null : next;
+            });
             return { stored: true, failure: null };
         }
         catch (error) {
-            try {
-                rmSync(temporary, { force: true });
-            }
-            catch {
-                // 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)}` };
         }
     }
@@ -254,6 +298,14 @@ function fromAgentOutcome(result) {
         failure: result.failure,
     };
 }
+function compactValues(resolution) {
+    const values = { ...resolution.preserved };
+    for (const setting of resolution.settings) {
+        if (setting.value !== setting.declaration.defaultValue)
+            values[setting.declaration.id] = setting.value;
+    }
+    return values;
+}
 function isMissing(error) {
     return typeof error === "object" && error !== null && error.code === "ENOENT";
 }

package/dist/ui/settings/migrations.d.ts

@@ -9,5 +9,11 @@ export interface OwnedUiSettingsMigration {
  * is the first stored shape.
  */
 export declare const OWNED_UI_SETTINGS_MIGRATIONS: readonly OwnedUiSettingsMigration[];
+export interface OwnedUiSettingsCompatibilityResult {
+    readonly values: Readonly<Record<string, unknown>> | null;
+    readonly failure: string | null;
+}
+/** Shape-selected compatibility for the metadata-free product object. */
+export declare function normalizeOwnedUiSettingsValues(source: Readonly<Record<string, unknown>>): OwnedUiSettingsCompatibilityResult;
 export declare function assertOwnedUiSettingsMigrations(migrations: readonly OwnedUiSettingsMigration[], currentVersion?: number): void;
 export declare function migrationsFrom(migrations: readonly OwnedUiSettingsMigration[], storedVersion: number): readonly OwnedUiSettingsMigration[];

package/dist/ui/settings/migrations.js

@@ -111,7 +111,32 @@ export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([
             return { ...values };
         },
     }),
+    Object.freeze({
+        to: 15,
+        description: "Introduce the bounded concurrent resident-tab start limit.",
+        migrate(values) {
+            return { ...values };
+        },
+    }),
 ]);
+/** Shape-selected compatibility for the metadata-free product object. */
+export function normalizeOwnedUiSettingsValues(source) {
+    const values = { ...source };
+    // Compatibility: "high" is valid again, so the old speed meaning is ambiguous without legacy metadata.
+    if (values.scrollbarAppearance === "hover")
+        values.scrollbarAppearance = "auto";
+    if (values.accentColor === "default")
+        values.accentColor = "purple";
+    if (values.quitEffect === "off") {
+        if (Object.hasOwn(values, "quitAnimation") && values.quitAnimation !== false) {
+            return { values: null, failure: "legacy quitEffect conflicts with quitAnimation" };
+        }
+        values.quitAnimation = false;
+    }
+    delete values.quitEffect;
+    delete values.quitEffectDurationMs;
+    return { values, failure: null };
+}
 export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
     const firstProduced = currentVersion - migrations.length + 1;
     if (migrations.length > 0 && firstProduced < 2) {

package/dist/ui/settings/profile-document.d.ts

@@ -0,0 +1,26 @@
+export type ProfileSettingsNamespaceRead = {
+    readonly status: "missing";
+    readonly value: null;
+} | {
+    readonly status: "available";
+    readonly value: Readonly<Record<string, unknown>>;
+} | {
+    readonly status: "invalid";
+    readonly value: null;
+    readonly detail: string;
+};
+export type ProfileSettingsNamespaceUpdate = (current: Readonly<Record<string, unknown>> | null) => Readonly<Record<string, unknown>> | null;
+/** Refuse an injected namespace already claimed by the surrounding root schema. */
+export declare function assertProfileSettingsNamespaceAvailable(namespace: string, rootSettingKeys: readonly string[]): void;
+/** Read one product-owned root object without exposing unrelated profile settings. */
+export declare function readProfileSettingsNamespace(file: string, namespace: string): ProfileSettingsNamespaceRead;
+/**
+ * Remove bounded leading noise only when the remaining bytes are one complete root object.
+ * The repair is silent and uses the same lock and atomic replacement path as namespace writes.
+ */
+export declare function repairProfileSettingsDocument(file: string): boolean;
+/**
+ * Replace one root namespace through the lock protocol used by pinned Pi.
+ * The updater receives bytes reread while locked, so unrelated concurrent writes survive.
+ */
+export declare function updateProfileSettingsNamespace(file: string, namespace: string, update: ProfileSettingsNamespaceUpdate): void;

package/dist/ui/settings/profile-document.js

@@ -0,0 +1,164 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/;
+const MAX_RECOVERABLE_PREFIX_BYTES = 256;
+/** Refuse an injected namespace already claimed by the surrounding root schema. */
+export function assertProfileSettingsNamespaceAvailable(namespace, rootSettingKeys) {
+    assertNamespace(namespace);
+    if (rootSettingKeys.includes(namespace))
+        throw new Error(`profile settings namespace collides with a root setting: ${namespace}`);
+}
+/** Read one product-owned root object without exposing unrelated profile settings. */
+export function readProfileSettingsNamespace(file, namespace) {
+    assertNamespace(namespace);
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { status: "missing", value: null };
+        return { status: "invalid", value: null, detail: `${file} could not be read: ${describe(error)}` };
+    }
+    const root = parseRoot(raw);
+    if (root === null)
+        return { status: "invalid", value: null, detail: `${file} is not a valid settings object` };
+    if (!Object.hasOwn(root, namespace))
+        return { status: "missing", value: null };
+    const value = root[namespace];
+    if (!isRecord(value)) {
+        return { status: "invalid", value: null, detail: `${file} contains a non-object ${namespace} settings namespace` };
+    }
+    return { status: "available", value: Object.freeze({ ...value }) };
+}
+/**
+ * Remove bounded leading noise only when the remaining bytes are one complete root object.
+ * The repair is silent and uses the same lock and atomic replacement path as namespace writes.
+ */
+export function repairProfileSettingsDocument(file) {
+    if (!existsSync(file))
+        return false;
+    const release = acquireLock(file);
+    try {
+        if (!existsSync(file))
+            return false;
+        const raw = readFileSync(file, "utf8");
+        if (parseRoot(raw) !== null)
+            return false;
+        const root = parseRootAfterLeadingNoise(raw);
+        if (root === null)
+            return false;
+        replaceRoot(file, root);
+        return true;
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Replace one root namespace through the lock protocol used by pinned Pi.
+ * The updater receives bytes reread while locked, so unrelated concurrent writes survive.
+ */
+export function updateProfileSettingsNamespace(file, namespace, update) {
+    assertNamespace(namespace);
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const release = acquireLock(file);
+    try {
+        const root = existsSync(file) ? parseRoot(readFileSync(file, "utf8")) : {};
+        if (root === null)
+            throw new Error(`${file} is not a valid settings object`);
+        const existing = root[namespace];
+        if (existing !== undefined && !isRecord(existing)) {
+            throw new Error(`${file} contains a non-object ${namespace} settings namespace`);
+        }
+        const nextNamespace = update(existing === undefined ? null : Object.freeze({ ...existing }));
+        const nextRoot = { ...root };
+        if (nextNamespace === null || Object.keys(nextNamespace).length === 0)
+            delete nextRoot[namespace];
+        else
+            nextRoot[namespace] = { ...nextNamespace };
+        replaceRoot(file, nextRoot);
+    }
+    finally {
+        release();
+    }
+}
+function acquireLock(file) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return lockfile.lockSync(file, { realpath: false });
+        }
+        catch (error) {
+            if (attempt >= 9 || !isLocked(error))
+                throw error;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+        }
+    }
+}
+function replaceRoot(file, root) {
+    let temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(root, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        renameSync(temporary, file);
+        temporary = null;
+    }
+    finally {
+        if (temporary !== null) {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch {
+                // Invariant: failed temporary cleanup cannot make the target document authoritative.
+            }
+        }
+    }
+}
+function parseRoot(raw) {
+    return parseRootValue(stripBom(raw));
+}
+function parseRootAfterLeadingNoise(raw) {
+    const withoutBom = stripBom(raw);
+    const start = withoutBom.indexOf("{");
+    if (start <= 0)
+        return null;
+    const prefix = withoutBom.slice(0, start);
+    if (Buffer.byteLength(prefix, "utf8") > MAX_RECOVERABLE_PREFIX_BYTES || prefix.trim().length === 0)
+        return null;
+    try {
+        JSON.parse(prefix);
+        return null;
+    }
+    catch {
+        return parseRootValue(withoutBom.slice(start));
+    }
+}
+function parseRootValue(raw) {
+    try {
+        const value = JSON.parse(raw);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stripBom(raw) {
+    return raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertNamespace(namespace) {
+    if (!NAMESPACE_PATTERN.test(namespace))
+        throw new Error(`profile settings namespace is invalid: ${namespace}`);
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isLocked(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ELOCKED";
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}