@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.226

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)}` };
         }

package/docs/architecture/boundaries.md

@@ -9,15 +9,15 @@ mutable a1 entry
   -> verified immutable release
   -> Node launch guardian and authenticated launch-instance registration
   -> native process guardian and per-instance containment
-  -> a1-ui runtime selection
-  -> owned UI or transparent Pi with inherited physical terminal handles
+  -> profile-aware owned-UI runtime selection
+  -> owned Pi-backed composition, with A1 surfaces enabled only for bare a1
 ```
 
-Launch-instance ownership is plural. The supervisor tracks any number of independently authenticated `a1`, `a1 pi`, and `a1 sandbox` instances and never uses one product-wide foreground mutex. Closing one instance closes only its verified process tree. Persisted rows alone do not prove liveness, and uncertainty never authorizes terminating an unrelated process.
+Launch-instance ownership is plural. The supervisor tracks any number of independently authenticated `a1` and `a1 pi` instances and never uses one product-wide foreground mutex. Closing one instance closes only its verified process tree. Persisted rows alone do not prove liveness, and uncertainty never authorizes terminating an unrelated process.
 
-Neither guardian reads ordinary terminal input, parses or relays runtime output, renders cells, infers frames, synthesizes terminal responses, or emits display control. Bare `a1` retains its owned UI authority. In explicit Pi profiles, Pi and the physical terminal retain direct terminal behavior. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
+Neither guardian reads ordinary terminal input, parses or relays runtime output, renders cells, infers frames, synthesizes terminal responses, or emits display control. Both profiles use the same owned rendering and input pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces and uses Pi's ordinary profile root. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
 
-Transparent mode has no A1-authoritative terminal surface, internal pane, virtual scrollback, inactive resident tab, or visual reconnection. A future feature that requires those properties must introduce and certify a separate composed-terminal authority; it must not weaken or silently intercept transparent mode.
+The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feature that requires resident arbitrary CLI sessions, internal tabs, terminal-state reconnection, or A1-authoritative scrollback must introduce and certify the separate composed-terminal authority rather than reactivating the retired transparent attachment path.
 
 ## Current module responsibilities
 
@@ -30,20 +30,20 @@ Transparent mode has no A1-authoritative terminal surface, internal pane, virtua
 - `protocol`: additive control handshake, bounded line framing, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
 - `storage`: SQLite migrations, prior-boot reconciliation, and plural launch-instance persistence. Legacy foreground rows are historical migration input and never authorize current ownership.
 - `supervisor`: endpoint identity, plural cohort ownership, per-instance reconciliation, and aggregate release shutdown coordination. It owns no terminal surface.
-- `transparent-terminal`: generic command resolution and direct inherited-handle child waiting below the outer launch guardian; it owns no supervisor lease.
+- `pi-engine-adapter`, `pi-component-adapter`, `pi-tui-runtime-adapter`, and `pi-session-ui-integration`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly. The session UI render root assembles semantic document and dock rows, while its focused viewport controller owns follow state, pointer routing, selection, and interaction timers. Owned-app route lifecycle belongs to the neutral `ui-apps` owner and is only hosted by the Pi session UI.
 - release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
 
 ## Dependency direction
 
 Terminal boundaries are application-agnostic. They may not select behavior from executable names, arguments, CLI-specific environment variables, or visible text. Production code may not import private Pi distribution APIs or use a Pi-specific terminal workaround.
 
-The transparent path has no PTY or terminal-emulator dependency. Reintroducing `node-pty`, xterm state, custom input encoders, mode/query trackers, cadence-derived frame inference, or renderer/projection code requires an approved capability change and cannot enter transparent mode. The Rust process guardian is a lifecycle-only native boundary and is independent from the held composed terminal host.
+The JavaScript product path has no PTY or terminal-emulator dependency. Reintroducing `node-pty`, xterm state, custom input encoders, mode/query trackers, cadence-derived frame inference, or renderer/projection code requires an approved capability change and cannot become a second terminal authority. The Rust process guardian is a lifecycle-only native boundary and is independent from the held composed terminal host.
 
-`scripts/check-architecture.mjs` enforces the structural parts of these boundaries. Cross-cutting rationale belongs here; implementation history belongs in Git and archived OpenSpec changes.
+`scripts/governance/check-architecture.mjs` enforces the structural parts of these boundaries. Cross-cutting rationale belongs here; implementation history belongs in Git and archived OpenSpec changes.
 
 ## Planned multi-agent boundaries
 
-The workspace feature may depend on workspace contracts and the structured/terminal-host foundations. Those foundations may depend only on dependency-free workspace contracts, never on product features, launch profiles, or each other unless an approved capability adds the dependency. Explicit launch profiles and transparent fallback may not import, initialize, launch, or connect to composed terminal-host infrastructure.
+The workspace feature may depend on workspace contracts and the structured/terminal-host foundations. Those foundations may depend only on dependency-free workspace contracts, never on product features, launch profiles, or each other unless an approved capability adds the dependency. Launch profiles do not import, initialize, launch, or connect to composed terminal-host infrastructure.
 
 Default future agents and composed hosts are children of the originating bare-`a1` launch instance and terminate when it closes. A process that survives command closure requires a separately approved explicit resident capability; durable identity or state recovery never implies an implicitly surviving process.