@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/ui/settings/manager.js

@@ -0,0 +1,256 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } 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 { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
+const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const MAX_DOCUMENT_BYTES = 256 * 1024;
+/**
+ * One profile's A1 settings: resolves the declaration table against the stored document,
+ * persists each accepted change atomically without discarding unknown keys, offers the
+ * grouped sections a surface presents, and routes every accepted change only to its
+ * owning backend, with agent settings reached through the engine settings port.
+ */
+export class OwnedSettingsManager {
+    #file;
+    #declarations;
+    #migrations;
+    #agent;
+    #agentProvider;
+    #listeners = new Set();
+    #hiddenAgentSettingIds;
+    #resolution;
+    #agentSnapshot = null;
+    #pending = new Map();
+    #restartEffective = new Map();
+    constructor(options) {
+        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`);
+        this.#declarations = options.declarations ?? OWNED_UI_SETTING_DECLARATIONS;
+        this.#migrations = options.migrations ?? OWNED_UI_SETTINGS_MIGRATIONS;
+        this.#agent = options.agent ?? null;
+        this.#agentProvider = options.agentProvider ?? null;
+        this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
+        this.#resolution = this.read();
+        for (const setting of this.#resolution.settings) {
+            if (setting.declaration.application === "restart")
+                this.#restartEffective.set(setting.declaration.id, setting.value);
+        }
+    }
+    get file() {
+        return this.#file;
+    }
+    get resolution() {
+        return this.#resolution;
+    }
+    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    read() {
+        let raw = null;
+        let unreadable = null;
+        try {
+            raw = readFileSync(this.#file, "utf8");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                unreadable = `${this.#file} 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`;
+            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`;
+        }
+        return resolveOwnedUiSettings({
+            declarations: this.#declarations,
+            migrations: this.#migrations,
+            document,
+            ...(unreadable === null ? {} : { unreadableDetail: unreadable }),
+            currentVersion: OWNED_UI_SETTINGS_VERSION,
+        });
+    }
+    async load() {
+        this.#resolution = this.read();
+        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 }).map(section => ({
+            ...section,
+            entries: section.entries.map(entry => entry.backend === "a1" && this.#restartEffective.has(entry.id)
+                ? { ...entry, effectiveValue: this.#restartEffective.get(entry.id) }
+                : entry),
+        }));
+    }
+    /**
+     * The value in effect for a declared setting, typed by its declaration. A restart-bound
+     * setting reads as the value the session started with until the next start.
+     */
+    value(id) {
+        return (this.valueOf(id) ?? OWNED_SETTING_DECLARATIONS[id].defaultValue);
+    }
+    /** The value in effect for any setting id, or null when nothing declares it. */
+    valueOf(id) {
+        return this.#restartEffective.get(id) ?? this.#resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
+    }
+    pendingValue(id) {
+        return this.#pending.get(id) ?? null;
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    async changeStructured(backend, id, value) {
+        if (backend !== "agent")
+            return failed("only an agent setting holds a structured value");
+        return await this.#changeAgentValue(id, value);
+    }
+    async change(backend, id, value) {
+        const entry = findOwnedUiSettingsEntry(this.sections(), id, backend);
+        if (entry === null)
+            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.#changeAgentValue(id, value);
+    }
+    #changeOwned(id, value) {
+        const outcome = this.#write(this.#resolution, id, value);
+        if (!outcome.stored)
+            return failed(outcome.failure ?? `${id} could not be stored`);
+        const previous = this.#resolution;
+        this.#resolution = this.read();
+        const previousSetting = previous.settings.find(setting => setting.declaration.id === id);
+        if (previousSetting?.declaration.application === "restart") {
+            this.#pending.set(id, value);
+            this.#notify();
+            return changed("deferred", "next-start", value, this.#restartEffective.get(id));
+        }
+        this.#pending.delete(id);
+        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) {
+        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);
+            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)}` };
+        }
+    }
+    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 {
+            // Invariant: the bridge 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.#hiddenAgentSettingIds);
+        this.#notify();
+        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, hidden) {
+    try {
+        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,
+            writeAdvertised,
+            failure: null,
+        };
+    }
+    catch (error) {
+        return { descriptors: [], writeAdvertised: false, failure: describe(error) };
+    }
+}
+function failed(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 isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,13 @@
+export interface OwnedUiSettingsMigration {
+    /** Version this migration produces. A migration from N-1 declares `to: N`. */
+    readonly to: number;
+    readonly description: string;
+    migrate(values: Readonly<Record<string, unknown>>): Record<string, unknown>;
+}
+/**
+ * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
+ * is the first stored shape.
+ */
+export declare const OWNED_UI_SETTINGS_MIGRATIONS: readonly OwnedUiSettingsMigration[];
+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

@@ -0,0 +1,74 @@
+import { OWNED_UI_SETTINGS_VERSION } from "./declarations.js";
+/**
+ * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
+ * is the first stored shape.
+ */
+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 };
+        },
+    }),
+    Object.freeze({
+        to: 4,
+        description: "Introduce contextual prompt suggestions with an enabled default.",
+        migrate(values) {
+            return { ...values };
+        },
+    }),
+    Object.freeze({
+        to: 5,
+        description: "Introduce the quit outro effect and duration with prototype defaults.",
+        migrate(values) {
+            return { ...values };
+        },
+    }),
+    Object.freeze({
+        to: 6,
+        description: "Move the disabled quit effect into the exit-animation toggle.",
+        migrate(values) {
+            // Invariant: a profile that chose off keeps quitting without an animation; the
+            // effect it stored is no longer a choice, so it resolves to the default.
+            if (values.quitEffect !== "off")
+                return { ...values };
+            const migrated = { ...values, quitAnimation: false };
+            delete migrated.quitEffect;
+            return migrated;
+        },
+    }),
+]);
+export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
+    const firstProduced = currentVersion - migrations.length + 1;
+    if (migrations.length > 0 && firstProduced < 2) {
+        throw new Error("owned UI settings migrations cannot produce a version below 2");
+    }
+    migrations.forEach((migration, index) => {
+        const expected = firstProduced + index;
+        if (migration.to !== expected) {
+            throw new Error(`owned UI settings migration ${index} produces version ${migration.to}, expected ${expected}`);
+        }
+        if (migration.description.trim().length === 0) {
+            throw new Error(`owned UI settings migration to version ${migration.to} has no description`);
+        }
+    });
+    const last = migrations.at(-1);
+    if (last && last.to !== currentVersion) {
+        throw new Error(`owned UI settings migrations end at version ${last.to}, expected ${currentVersion}`);
+    }
+}
+export function migrationsFrom(migrations, storedVersion) {
+    return migrations.filter(migration => migration.to > storedVersion);
+}

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

@@ -0,0 +1,52 @@
+import type { AgentSettingApplicationBoundary, AgentSettingDescriptor, AgentSettingFlag } from "../../contracts/agent-engine/index.js";
+import type { OwnedUiSettingValue } from "./declarations.js";
+import type { OwnedUiSettingsResolution } from "./resolution.js";
+export type OwnedUiSettingsBackend = "a1" | "agent";
+export interface OwnedUiSettingsEntry {
+    readonly id: string;
+    /** Label to show, when its source provides one. Falls back to the id. */
+    readonly label: string | null;
+    readonly backend: OwnedUiSettingsBackend;
+    readonly description: string | null;
+    /** Present when the value is a scalar the surface can offer as a choice. */
+    readonly value: OwnedUiSettingValue | null;
+    /** 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. */
+    readonly structured: boolean;
+    /** Limits a numeric setting accepts, when the engine states them. */
+    readonly minimum: number | null;
+    readonly maximum: number | null;
+    /** Flags that surface offers, declared by the source rather than by the value. */
+    readonly flags: readonly AgentSettingFlag[];
+    readonly origin: "default" | "stored" | "engine";
+    readonly application: AgentSettingApplicationBoundary;
+}
+export interface OwnedUiSettingsSection {
+    readonly id: string;
+    readonly title: string;
+    readonly entries: readonly OwnedUiSettingsEntry[];
+    /** Set when the section could not be built; entries is then empty. */
+    readonly unavailableReason: string | null;
+    /** Set when the section is present but nothing in it can be changed here. */
+    readonly readOnlyReason: string | null;
+}
+export interface AgentSettingsSnapshot {
+    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. */
+    readonly failure: string | null;
+}
+export interface BuildOwnedUiSettingsSectionsInput {
+    readonly resolution: OwnedUiSettingsResolution;
+    /** Null when no engine is attached, which is not a failure. */
+    readonly agent: AgentSettingsSnapshot | null;
+}
+export declare const AGENT_SECTION_ID = "agent";
+export declare function buildOwnedUiSettingsSections(input: BuildOwnedUiSettingsSectionsInput): readonly OwnedUiSettingsSection[];
+export declare function findOwnedUiSettingsEntry(sections: readonly OwnedUiSettingsSection[], id: string, backend: OwnedUiSettingsBackend): OwnedUiSettingsEntry | null;

package/dist/ui/settings/sections.js

@@ -0,0 +1,112 @@
+export const AGENT_SECTION_ID = "agent";
+const BOOLEAN_CHOICES = Object.freeze([true, false]);
+export function buildOwnedUiSettingsSections(input) {
+    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: 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,
+            maximum: null,
+            flags: [],
+            choices: setting.declaration.allowedValues,
+            origin: setting.source,
+            application: setting.declaration.application === "restart" ? "next-start" : "live",
+        });
+        grouped.set(section.id, group);
+    }
+    const ownedAgentEntries = grouped.get(AGENT_SECTION_ID)?.entries ?? [];
+    grouped.delete(AGENT_SECTION_ID);
+    const ownedSections = [...grouped].map(([id, group]) => ({
+        id,
+        title: group.title,
+        entries: Object.freeze(group.entries),
+        unavailableReason: null,
+        readOnlyReason: null,
+    }));
+    const agent = agentSection(input.agent);
+    // Invariant: presentation grouping does not transfer ownership or engine availability to owned entries.
+    const combinedAgent = ownedAgentEntries.length === 0 ? agent : {
+        ...agent,
+        entries: Object.freeze([...agent.entries, ...ownedAgentEntries]),
+        unavailableReason: null,
+        readOnlyReason: null,
+    };
+    return Object.freeze([...ownedSections, combinedAgent]);
+}
+export function findOwnedUiSettingsEntry(sections, id, backend) {
+    for (const section of sections) {
+        const entry = section.entries.find(candidate => candidate.id === id && candidate.backend === backend);
+        if (entry)
+            return entry;
+    }
+    return null;
+}
+function agentSection(snapshot) {
+    if (snapshot === null) {
+        return frozenSection("Agent settings are unavailable because no agent engine is attached", null, []);
+    }
+    if (snapshot.failure !== null) {
+        return frozenSection(`Agent settings are unavailable: ${snapshot.failure}`, null, []);
+    }
+    if (snapshot.descriptors.length === 0) {
+        return { id: AGENT_SECTION_ID, title: "Agent", entries: Object.freeze([]), unavailableReason: null, readOnlyReason: 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,
+            backend: "agent",
+            description: descriptor.description ?? null,
+            value: scalar(raw),
+            rawValue: raw,
+            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 ?? [],
+            // 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: descriptor.application,
+        };
+    });
+    return {
+        id: AGENT_SECTION_ID,
+        title: "Agent",
+        entries: Object.freeze(entries),
+        unavailableReason: null,
+        readOnlyReason: null,
+    };
+}
+function frozenSection(unavailableReason, readOnlyReason, entries) {
+    return { id: AGENT_SECTION_ID, title: "Agent", entries: Object.freeze(entries), unavailableReason, readOnlyReason };
+}
+function scalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : null;
+}
+function choicesOf(choices) {
+    if (choices === undefined)
+        return null;
+    const scalars = choices.map(scalar).filter((choice) => choice !== null);
+    return scalars.length === choices.length ? Object.freeze(scalars) : null;
+}

package/docs/architecture/boundaries.md

@@ -9,41 +9,45 @@ 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
 
 - `lifecycle`: dependency-free launch-instance, process identity, state transition, outcome, and control-command contracts.
 - `process-containment`: artifact verification, OS-verifiable process inspection, containment adapters, and bounded graceful/forced cleanup; it owns no terminal content.
 - `launch-guardian`: one profile-neutral instance coordinator above runtime selection.
-- `workspace-contracts`: dependency-free multi-agent identity, capability, command/event/snapshot, terminal window/tab/pane/session topology, terminal-host, and recovery contracts.
-- `structured-agent-runtime`: planned typed event/command/snapshot runtime. It must not infer semantics from terminal text, own pseudoterminals, or reconstruct screens.
-- `native-host-protocol`: bounded typed local boundary for terminal-host identity, topology revisions, lifecycle, and recovery. Terminal bytes, per-event child input, and rendered cells are forbidden across it.
 - `protocol`: additive control handshake, bounded line framing, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
+- `launch`: resolves the effective profile home and the history-specific data root. Composition uses its public path resolver to select `~/.a1/data` for history unless `A1_DATA_DIR` is explicit; global control/release/runtime/cache paths stay unchanged.
+- `prompt-history`: narrowly typed user-input retention in separate profile-owned databases under `~/.a1/data/history` (or `<A1_DATA_DIR>/history`), with bounded worker queues and no supervisor/control-store payloads. It receives a resolved root rather than importing launch-feature internals; it never probes, imports, or deletes the former platform-default history. The editor's owned history state machine remains inside the Pi component boundary; the session UI only coordinates snapshots and classified submissions.
+- `prompt-suggestions`: opt-in bounded diagnostic snapshots of neutral suggestion lifecycle metadata. Composition supplies an explicit local destination; this feature never imports Pi, generates suggestions, stores conversation text, or owns the editor. See [prompt suggestion diagnostics](prompt-suggestions.md).
 - `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.
-- release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
+- `pi-engine-adapter`, `pi-component-adapter`, and `pi-tui-runtime-adapter`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly.
+- `session-shell` (`src/app/session-shell`): the application layer that composes the feature owners, the UI foundations, and the three Pi adapters into the interactive session; only composition imports it. Its 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 session shell.
+- release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry. After an unsuccessful bare-A1 child exit, the bootstrap restores owned terminal modes; neither guardian emits terminal controls.
+- `terminal-cleanup`: bounded, idempotent emergency restoration and fatal-exit diagnostics for an explicitly owned terminal. It does not inspect commands, relay terminal input/output, or emulate terminal state. The owned UI installs its fatal boundary before terminal activation; packaged bootstrap and checkout launch provide the surviving-owner fallback. Fatal records retain at most ten 16 KiB records with trusted classifications and code locations, never prompts, attachments, raw input, credentials, or arbitrary exception messages.
 
 ## 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 multi-agent workspace feature, its dependency-free contracts, the structured-agent runtime, and the Node side of the terminal-host protocol were removed from `develop` while the multi-agent plan is on hold; their last state is preserved on the `archive/multi-agent-workspace` branch. A future implementation starts from the current codebase rather than from that copy. The boundary rules below remain the design intent for that work.
+
+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.
 

package/docs/architecture/code-documentation.md

@@ -0,0 +1,77 @@
+# Code documentation
+
+A1 treats source documentation as a contract, not as a coverage target. Names, types, and decomposition explain ordinary behavior. Comments remain only where removing them would hide a public responsibility, invariant, rationale, security property, platform constraint, compatibility boundary, protocol rule, concurrency rule, performance decision, or provenance fact.
+
+## Public class contracts
+
+Every first-party TypeScript class exposed through a production owner's public entry has exactly one JSDoc description at its declaration. The description states what the class owns and includes its material lifecycle or safety boundary when one exists.
+
+Do not add JSDoc solely because a function, type, constructor, property, or method is exported. Do not document a class by repeating its name or listing its methods. Private and protected members never use JSDoc.
+
+```ts
+/** Persists complete workspace views and recovery references through the control-store boundary. */
+export class WorkspaceStore {
+```
+
+## Implementation comments
+
+A retained implementation comment starts with the reason it exists:
+
+| Intent | Use |
+| --- | --- |
+| `Invariant:` | State or ordering that every implementation path must preserve |
+| `Rationale:` | A non-obvious choice among plausible alternatives |
+| `Security:` | Trust, ownership, cleanup, disclosure, or failure-safety boundary |
+| `Platform:` | Operating-system, terminal, filesystem, or toolchain behavior |
+| `Compatibility:` | Behavior intentionally matching or accepting another version or surface |
+| `Protocol:` | Wire, framing, input, encoding, or externally defined semantic rule |
+| `Concurrency:` | Race, serialization, cancellation, or event-loop ordering |
+| `Performance:` | Bounded work, caching, coalescing, or resource decision |
+| `Provenance:` | Source, generated authority, or adaptation origin |
+
+```ts
+// Security: an uncertain process identity never authorizes termination.
+// Platform: Windows Terminal encodes Ctrl+Backspace as a raw backspace byte.
+// Performance: finalized blocks cache by revision and width; live blocks always render.
+```
+
+A continuation line does not repeat the label. If no intent applies, remove the comment and make the code explain itself.
+
+## Forbidden forms
+
+The repository gate rejects:
+
+- missing or multiple contracts on owner-public first-party classes;
+- `<summary>` and `@summary` tags;
+- boilerplate class descriptions and method inventories;
+- JSDoc on private or protected members;
+- uncategorized implementation comments;
+- obvious commented-out code or control-flow narration;
+- `TODO` or `FIXME` without an issue number, issue URL, or tracker identifier;
+- `@ts-ignore` and suppression directives without a reason;
+- an unclassified tracked code path or synchronized source without provenance.
+
+Follow-up and suppression forms include their authority inline:
+
+```ts
+// TODO(#321): remove the compatibility path after the pinned upgrade.
+// @ts-expect-error -- the shipped JavaScript module has no declaration file
+```
+
+## Source roles
+
+The full style policy applies to first-party production TypeScript and to applicable comments in first-party tests, tooling, and native source. Native source does not receive TypeScript declaration requirements.
+
+Synchronized Pi source, native vendor trees, generated source, build output, and runtime artifacts are not rewritten to match first-party style. Their exclusion comes from the repository source-role classifier, not from a list of accepted violations. Synchronized source must remain covered by its source ledger or explicit provenance header.
+
+## Validation
+
+Run the focused check with:
+
+```sh
+npm run check:code-documentation
+```
+
+The check scans the complete tracked baseline and reports stable rule identifiers with path, line, column, and declaration symbol when available. It has no accepted-violation count or grandfather file. Fast pull-request validation runs the check, and full release validation inherits it through the fast tier.
+
+Focused governance tests use valid and invalid virtual sources to preserve each rule independently from the clean repository-baseline assertion. The gate validates deterministic structure and high-confidence anti-patterns; review remains responsible for the factual accuracy of retained prose.