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

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

@@ -1,46 +1,36 @@
-import type { AgentSettingsPort } from "../../contracts/agent-engine/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;
-    /** Agent-owned controls fixed by this product surface and therefore omitted. */
     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/ui/settings/session.js

@@ -1,9 +1,6 @@
+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;
@@ -23,21 +20,18 @@ export class OwnedUiSettingsSession {
     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();
+        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;
     }
@@ -45,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.#hiddenAgentSettingIds);
-        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);
@@ -73,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);
@@ -81,35 +58,39 @@ 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.#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)
@@ -118,29 +99,56 @@ export class OwnedUiSettingsSession {
 }
 async function snapshotOf(agent, hidden) {
     try {
-        const descriptors = (await agent.listSettings()).filter(descriptor => !hidden.has(descriptor.key));
-        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/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/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/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.

package/docs/architecture/project-structure.md

@@ -86,6 +86,20 @@ The repository has one root `package.json`, `package-lock.json`, TypeScript conf
 
 Build output mirrors the production namespaces directly under ignored `dist/`, without an intermediate `src/` directory; release and test evidence belongs in ignored `.artifacts/`; temporary agent work belongs in ignored `.worktrees/` and `.builds/`. Repository tooling is grouped under `scripts/governance`, `scripts/release`, `scripts/pi`, and `scripts/development`; the few root scripts are standalone maintenance or build commands. Package contents are selected by the root manifest. The Rust process guardian and console terminal-host proof live under `native/`; Cargo output is ignored. Third-party terminal parser sources are isolated under `native/terminal-host/vendor/` and are not owned application modules.
 
+## Development worktrees
+
+Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
+
+From the initial working directory, create and address a task worktree explicitly:
+
+```sh
+git fetch origin develop
+git worktree add --detach .worktrees/<task-id> origin/develop
+git -C .worktrees/<task-id> status
+```
+
+The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, move, or remove another session's worktree.
+
 ## Documentation and comments
 
 - README explains installation, commands, and current limitations.
@@ -93,7 +107,7 @@ Build output mirrors the production namespaces directly under ignored `dist/`, w
 - `docs/features` explains maintained user-facing behavior.
 - Operational and manual procedures live in focused runbooks under `docs`.
 - OpenSpec and Git carry planning and implementation history.
-- Source comments explain only non-obvious rationale, safety/security invariants, platform constraints, or public semantic contracts. Names, types, and decomposition explain normal control flow.
+- Source documentation follows the focused [code-documentation policy](code-documentation.md): owner-public class contracts are consistent, retained implementation comments state their intent, and names, types, and decomposition explain ordinary control flow.
 
 ## Terminal capability boundary
 

package/docs/architecture/ui-reference-provenance.md

@@ -29,7 +29,7 @@ its own `core` facade layer; A1 is a product, so the port adapts imports and kee
 | `ui-components/list-block.ts` — sticky scroll | `settings/impl.ts` — `stickyHeaderGroup`, `topPaddingRows`, `visibleRowCountAt`, `clampScrollForView` | Same reservation arithmetic and two-pass reveal. |
 | `ui-components/mouse.ts` | `core/panes/sgr-mouse.ts` | Same SGR decoding and per-call regex reset; A1 emits its own event shape. |
 | `ui-components/mouse.ts` — tracking sequences | `core/host/pi/providers/host-bridge-surface.ts` | Mouse modes only. A1 does not take the alternate screen, because the Pi TUI owns the screen A1 renders through. |
-| `features/owned-ui/settings-app.ts` — layout | `settings/impl.ts` — `settingsValueColumn`, `renderFieldLine`, footer and search rendering | Setting discovery is A1's own section model; presentation follows the reference. |
+| `features/owned-ui/settings-app.ts` — section layout, pointer controls, and scrolling | `settings/impl.ts` — `settingsValueColumn`, block navigation, sticky sections, and pointer hit regions | Setting discovery is A1's own A1/Agent section model. Section navigation and pointer-only numeric controls follow the A1 reference; explicit `/` search, ruled shared input, shortcut-derived hints, hidden description rows, configured wheel cadence, and distinct floating scalar menus are reviewed owned interactions. |
 
 ## Ported from the pinned engine
 
@@ -37,16 +37,36 @@ its own `core` facade layer; A1 is a product, so the port adapts imports and kee
 | --- | --- | --- |
 | `pi-engine-adapter/settings-integration.ts` — `SETTING_LABELS` | pinned Pi settings selector | Labels and descriptions transcribed so an owned screen reads as the vanilla route words it. Ids are mapped from the selector kebab-case to the exposed camelCase keys. |
 | `pi-engine/session-integration.ts` and `pi-components/shell-footer-status.ts` — steering queue | pinned Pi interactive mode `onSubmit` and `updatePendingMessagesDisplay` | Steering/follow-up uses `prompt(..., { streamingBehavior })`, allowing Pi to emit the accepted user row, while remaining steering rows preserve Pi's opening spacer, dim `Steering:` labels, dequeue hint, and order before `Working`. |
+| `ui-components/list-view.ts`, `dialog-panel.ts`, `value-menu.ts`, and `features/owned-ui/settings-app.ts` — setting presentation | pinned Pi `SettingsSelectorComponent`, Pi TUI `SettingsList`, `SelectList`, and `Input` at `0.84.2` | Cursor, selected label/value accents, unselected muted values, the 30-column label cap, dialog styling, notices, and narrow-width geometry retain pinned semantics. Scalar-menu placement and input remain shared, while A1/Agent grouping, pointer steppers, explicit `/` search, ruled shared input, shortcut-derived status hints, suppressed selected descriptions, `scrollbarSpeed`-driven wheel movement, and the dark floating menu with lighter active row and effective-value check mark are declared product-owned differences. Independent row evidence: `test/features/owned-ui/pinned-settings-presentation-parity.test.ts`; owned interaction evidence: `test/features/owned-ui/settings-app.test.ts`, `test/ui/components/value-menu.test.ts`, and `test/composition/settings-route-host.test.ts`. |
+| `features/owned-ui/project-trust-prompt.ts` — pre-resource selector | pinned Pi `cli/startup-ui.ts`, `cli/project-trust.ts`, and `core/project-trust.ts` at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Uses a fixed, dependency-bounded A1 startup selector rather than importing private CLI modules. It preserves selected-option accent, navigation/accept/reject/cancel semantics, fail-closed behavior, raw-mode restoration, clearing, cursor restoration, and parent-screen restoration before diagnostics. |
+| `pi-session-ui/session-shell-root.ts` and `session-shell.ts` — fullscreen exit | pinned Pi `InteractiveMode.formatResumeCommand()` and shutdown output at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Re-renders authoritative transcript components with semantic SGR intact, excludes inline-image control payloads and fullscreen-only chrome, restores the terminal first, then emits pinned dim `To resume this session:` wording with `a1`, compact session id, and conditional quoted `--session-dir`. |
+| `pi-tui-runtime/input-presentation-coordinator.ts` and custom-viewport dock reuse | pinned Pi TUI `TuiBase` input dispatch and immediate-render pending guard at `0.84.2` | Preserves each original terminal delivery and invokes the existing Pi handlers exactly once in order. Bare A1 alone drains finite-grammar text/edit/navigation bursts in one immediate event-loop opportunity so Pi's existing pending guard paints the newest state once; effectful, unknown, protocol, paste, and extension-owned input remains an immediate barrier. Geometry-stable dock frames reuse A1's established transcript viewport, while uncertain geometry and replacement-surface damage still fail closed. Independent evidence is under `test/support/input-responsiveness/`. |
+| `test/features/owned-ui/pi-raw-terminal-parity.ts` — parity normalization | pinned Pi public components/runtime at `0.84.2` | Only synchronized-output envelopes, absolute hyperlink targets, declared product/path substitutions, and nondeterministic timing may normalize. SGR roles/reset boundaries, rows, cursor operations, clearing, restoration, and write order remain authoritative; A1-generated JSON captures are diagnostics and cannot serve as pinned evidence. |
 
 ## Deliberate differences
 
-- **No alternate screen.** The reference owns its surface and can switch screens; A1 renders
-  through the pinned Pi TUI, so an owned screen is a full-viewport overlay instead.
+- **Owned in-session routes are overlays.** The A1 UI reference owns its surface and can switch screens; A1 renders in-session owned routes through the pinned Pi TUI as full-viewport overlays. The pre-resource trust selector is separate and uses a bounded alternate startup surface solely so every completion path can restore the untouched parent terminal before engine activation or a fail-closed diagnostic.
 - **Colour is a port, not an import.** The reference takes a Pi `Theme` directly. A1 defines
   `UiTheme` so the component layer never imports a Pi adapter and can be rendered plainly in
   tests.
 - **Settings content.** The reference aggregates per-extension settings files; A1 has one
   section for its own settings and one for the agent's, read through the engine settings port.
+- **Settings scalar-menu contrast.** The shared menu keeps reviewed placement, clipping, and
+  input behavior, but A1 uses its prior dark floating panel, lighter white-text active row,
+  and independent effective-value check mark because physical review rejected a menu that
+  blended into the settings rows.
+- **Spinner-backed progress punctuation.** Bare A1 resolves built-in and extension working
+  labels through `ui-components/progress-status.ts`, injected by
+  `pi-session-ui/session-shell-root.ts` into the shared `pi-components/shell-footer-status.ts`
+  spinner factory. The factory canonicalizes the visible progress marker once, to three ASCII
+  periods, without importing across the component-adapter boundary. Engine producers remain
+  semantic and the source-synchronized Pi status indicators, installed packages, `a1 pi`, and
+  vanilla Pi remain untouched.
+- **Keyboard presentation scheduling.** Pinned components, semantic key handling, and the
+  comparison profiles stay unchanged. Bare A1 adds one A1-owned event-loop-turn coordinator
+  before its fullscreen root and may omit only superseded visual states after every delivery
+  has already been applied in order. It does not debounce by wall clock, combine strings,
+  patch Pi TUI, or classify unknown extension/terminal data as safe.
 - **No viewport prototype or child-tree patches.** `ui/agent-view/user-prompt.ts` and the
   private-child traversal in `ui/agent-view/render.ts` were analyzed only for behavior. The
   destination renders source timestamps through an owned transcript adapter and derives sticky

package/docs/ci-release-runbook.md

@@ -12,6 +12,33 @@ GitHub Actions is the only automation platform. Three refs are protected:
 channel. The workflow starts at `03:17 UTC` for nightly development verification,
 or by explicit dispatch from `npm run develop` or `npm run release`.
 
+`.github/workflows/documentation-auto-merge.yml` is the only pull-request
+auto-merge authority. It runs trusted policy from `develop`; it never checks out or
+executes a pull request's code with its write token.
+
+`.github/workflows/merged-branch-cleanup.yml` owns branch deletion after a human or
+external actor closes a pull request. On the close event it checks out trusted
+default-branch policy and installs no pull-request dependencies. GitHub does not
+emit a new workflow event for a merge authored with the workflow `GITHUB_TOKEN`, so
+Documentation auto-merge also performs the same shared reconciliation synchronously
+after its own validated integration. Both paths delete only an unprotected same-
+repository topic ref whose live object still equals the merged pull request head SHA.
+An absent ref is success; fork, unmerged, advanced, protected, default, release-owned,
+or malformed refs are preserved and reported.
+
+`config/github-repository-governance.json` is the reviewed policy for repository
+settings, Actions defaults, security capabilities, environments, complete rulesets,
+protected refs, and workflow authority. Inspection is read-only by default:
+
+```sh
+node scripts/governance/check-github-repository-governance.mjs --check
+```
+
+Applying reviewed mutable drift is a separate maintainer operation requiring
+`--apply --confirm apply-a1-github-governance` and a matching post-apply read.
+Secrets and external npm trusted-publisher configuration are capability checks, not
+serialized credentials.
+
 `develop` is where work lands. `master` records what npm `latest` serves and is an
 effect of stable publication, not a trigger.
 
@@ -19,12 +46,67 @@ effect of stable publication, not a trigger.
 
 | Trigger | Validation and outcome |
 | --- | --- |
-| Pull request into `develop` | Fast required validation; docs/spec-only changes use strict OpenSpec validation |
+| Pull request into `develop` | Modular fast validation; changed/new source documentation is checked once, and rendering runs as `none`, `smoke`, or `full` from the exact impact |
 | `npm run develop` | Preview package gates on Windows, Linux, and macOS; an existing numbered preview is an early successful no-op |
-| Nightly at `03:17 UTC` | Complete non-physical suite on Windows, Linux, and macOS, every night |
+| Nightly at `03:17 UTC` | One full documentation review plus the complete non-physical suite on Windows, Linux, and macOS, every night |
 | `npm run release -- ...` | Complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master` |
 | `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
 
+## Impact-aware development validation
+
+`scripts/release/select-validation-impact.mjs` is the single pull-request selector. It records the complete merge-base-to-head name-status diff, changed/new documentation inputs, rendering dependency reasons, conservative fallbacks, and the exact head SHA in a machine-readable artifact. Missing history, unresolved rendering dependencies, unknown relevant inputs, or classifier failure select full rendering rather than silently skipping it.
+
+Ordinary type, architecture, unit/contract, and dist checks always run for code changes. Changed-file documentation and rendering run as independent parallel jobs. Rendered shell/component changes select `smoke`; viewport, scheduler, terminal adapter, evidence harness, package identity, and selector changes select `full`; unrelated changes select `none`. The aggregate accepts a skipped modular job only when the current selector requested the skip.
+
+Inspect local committed and worktree impact without running tests:
+
+```sh
+npm run select:validation-impact -- --include-worktree
+```
+
+Check documentation only for modified, added, copied, and renamed-to policy files:
+
+```sh
+npm run check:code-documentation:changed
+```
+
+Run the explicit complete documentation review used by nightly and complete regression:
+
+```sh
+npm run check:code-documentation
+```
+
+Rendering evidence captures each selected producer/mode/workload matrix once and reuses it for semantic, paint, parity, and damage assertions. A deliberate second `streamed-prose` capture remains only for determinism. Workflow summaries separate repository-gate timing from runner setup; wall-clock values diagnose runner/cache variance, while selected scopes, matrix captures, producer launches, documentation file counts, and full-scan counts are structural gates.
+
+## Pull request integration
+
+`Development validation required` remains the merge gate for every pull request.
+Documentation auto-merge reads the complete GitHub changed-file response and arms
+squash auto-merge for an eligible pull request while required validation is pending;
+branch protection prevents integration until `Development validation required`
+succeeds. If validation finishes before auto-merge can be armed and GitHub already
+reports the pull request clean, the reconciler squash-merges only the validated head
+SHA. Every current and renamed-from path must be under `openspec/**`, under
+`docs/**`, or exactly the root `README.md`. Eligible pull requests must use a
+non-draft branch in this repository and target `develop`.
+
+The exact allowlist covers maintained OpenSpec, architecture, feature, manual,
+runbook, and root README documentation. Other root Markdown files, `LICENSE`,
+`.gitignore`, source, tests, scripts, workflows, configuration, generated baselines,
+and mixed changes do not auto-merge. The guard also runs when a pull request changes
+or auto-merge is manually enabled; if any path is outside the allowlist, it disables
+auto-merge while leaving the pull request available for a later manual merge. Every
+docs-only change runs lightweight generated-governance consistency, so archiving an
+inventoried OpenSpec occurrence fails that pull request rather than a later code pull
+request. A legitimate generated baseline update remains outside the allowlist and
+follows the manually accepted mixed/code path.
+
+A specification request lands as an OpenSpec-only pull request. Implementation
+starts only after that specification merges and the maintainer explicitly requests
+it, in a fresh worktree and pull request based on updated `origin/develop`. Every
+code/operational pull request remains open after CI until the maintainer validates it
+locally and explicitly authorizes manual integration.
+
 ## Numbered development previews
 
 A merge or push to `develop` does not publish by itself. To request a deliberate
@@ -42,8 +124,7 @@ already exists it reports that version without dispatching package work. Otherwi
 it dispatches GitHub Actions, waits, and reports the published version. It never
 builds or uploads npm bytes from the workstation.
 
-Nightly resolves the same current `origin/develop` source. It always runs complete
-verification even if source has not changed. For a new number it packs once and
+Nightly resolves the same current `origin/develop` source. It runs one platform-independent full documentation review before the platform matrix, and the matrix records that prerequisite instead of repeating the scan four times. It always runs complete verification even if source has not changed. For a new number it packs once and
 runs the suite against that final-version tarball before publication. For an
 existing number it downloads the exact npm tarball and runs package/update gates
 against those registry bytes; publication is then a successful no-op.
@@ -92,6 +173,14 @@ Rules that do not bend:
 ## When something fails
 
 - **PR validation fails:** fix the code and push; do not mark a failed tier optional.
+- **Documentation auto-merge fails:** leave the pull request open, inspect its exact
+  changed-file classification, docs-sensitive inventory, and workflow permissions,
+  and never broaden the allowlist to make one pull request pass.
+- **Merged-branch cleanup fails:** inspect the bounded PR/ref/SHA disposition. Never
+  delete an advanced or protected ref merely because its name matches an old PR.
+- **Repository governance drifts:** run the read-only checker, review every reported
+  path, and use the confirmed apply mode only for an accepted mutable policy change.
+- **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
 - **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
 - **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
 - **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
@@ -104,6 +193,8 @@ and resolved review threads, but zero approving reviews. `master` and release ta
 are written only after publication and are protected from force-push, movement, and
 deletion.
 
-Do not add direct-push bypasses. Ruleset mutation remains a separate administrative
-operation: inspect with `node scripts/governance/check-github-rulesets.mjs`, and apply only
-with explicit maintainer confirmation.
+Do not add direct-push bypasses. Approval count, strict-base validation, repository
+merge methods, Actions allowance/SHA enforcement, Dependabot, and npm environment
+protection remain explicit maintainer decisions; governance automation does not
+silently change them. Repository mutation remains a separate confirmed administrative
+operation through `check-github-repository-governance.mjs`.

package/docs/manual-owned-ui-checkpoint.md

@@ -4,6 +4,8 @@ This checkpoint is user-controlled. Tests and coding agents must not launch or f
 
 ## Prepare an exact candidate
 
+For a checkout smoke test in Git Bash, build once and launch with `./scripts/dev` or `./scripts/dev pi`. Do not invoke `node scripts/development/dev-launch.mjs` or `node scripts/development/start-local.mjs` directly: that bypasses the color-preserving shell `exec` shape and can collapse the pinned 24-bit palette to Git Bash's 16 terminal colors. Run `node scripts/check-terminal-colour.mjs` first when color fidelity is in doubt; the first color block must differ from the terminal-palette cyan block.
+
 From the candidate checkout, pack once and install that tarball into a disposable prefix:
 
 ```powershell
@@ -46,6 +48,31 @@ Use the same terminal, working directory, dimensions, environment, and equivalen
 - [ ] Normal and error exits return a usable parent prompt.
 - [ ] Parent typing, cursor movement, Backspace, Delete, and submission work after exit.
 
-Report failures with bare-versus-comparison behavior, platform and terminal versions, exact command, reproducibility, and optional manually captured evidence.
+### Setting-controlled visual matrix
+
+Use equivalent values in bare A1 and the Pi comparison profile. Exercise both a wide frame and a narrow frame that forces wrapping/clipping.
+
+- [ ] `/settings`: selected cursor, label and value accent; unselected values muted; descriptions and hints dim; search uses `> ` with inverse cursor; scalar menus, numeric controls, warning-parts dialog, deferred notice, failed write, section spacing, clipping, and hidden-entry absence match their pinned semantic roles.
+- [ ] Transcript: toggle images and image width, thinking level/visibility, Mermaid mode, output padding, cache notices, warnings, auto-compaction, queue modes, command autocomplete, provider timeout/retry/error, and changelog collapse. Existing and streaming blocks must re-render without focus, selection, scroll, or queued-work loss.
+- [ ] Trust startup: from an undecided project, compare selected Trust/Do not trust rows, arrow navigation, Enter, Escape/Ctrl+C, clearing, cursor state, and restoration. No project extension/theme/prompt/skill may run before selection, and a fail-closed diagnostic must appear once on the restored parent rather than above a blank fullscreen frame.
+- [ ] Terminal lifecycle: toggle hardware cursor, clear-on-shrink, and terminal progress; resize smaller/larger; open/close selectors; select and copy transcript text; verify no duplicate rows, stale OSC progress, leaked mouse mode, misplaced cursor, or broken parent input.
+- [ ] Images: in Kitty or iTerm2 verify inline width and clipping; in Windows Terminal verify the textual fallback and absence of image protocol bytes without hiding `showImages`.
+- [ ] Fullscreen exit `transcript`: verify the parent is restored before styled user, assistant Markdown, thinking, tool, notice, warning, error, and spacing rows are printed. No overlay, draft, animation, scrollbar, or inline-image payload may appear.
+- [ ] Fullscreen exit `resume-hint`: verify only dim `To resume this session:` plus `a1 --session <compact-id>` is printed for the default directory. A custom directory must place quoted `--session-dir <dir>` before `--session`; the raw default `.jsonl` path must never print.
+
+Record acceptance with:
+
+```text
+A1 commit/tarball:
+Pi package: @earendil-works/pi-coding-agent 0.84.2
+OS/version:
+Terminal/version:
+Terminal dimensions (wide/narrow):
+Image protocol result:
+Settings values exercised:
+Outcome and any declared substitutions:
+```
+
+Report failures with bare-versus-comparison behavior, platform and terminal versions, exact command, dimensions, settings values, reproducibility, and optional manually captured evidence.
 
 For recovery, use `a1 pi`; do not use the removed `a1 ui` command. Manual acceptance can authorize an exact uncertified development preview after non-desktop gates pass. It does not certify stable presentation parity or platform support.

package/docs/manual-terminal-colour-check.md

@@ -29,9 +29,10 @@ leave the launch without a terminal on its input; the launcher says so and stops
 rather than opening a session that closes as it starts. Running `scripts/dev`
 from the shell is the direct path.
 
-A directly launched `node scripts/development/start-local.mjs` under Git Bash does not, and
-neither does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to
-the launch, not to either application.
+A directly launched `node scripts/development/dev-launch.mjs` or
+`node scripts/development/start-local.mjs` under Git Bash does not, and neither
+does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to the
+launch, not to either application.
 
 ## Checking a terminal