@timurproko/a1 0.1.8-dev.332 → 0.1.8-dev.368

package/dist/integrations/pi/tui-runtime/overlay-geometry.js

@@ -0,0 +1,159 @@
+import { TuiAltScreen, isFocusable } from "#pi-tui";
+/** Observes public component renders in compositor order, without accessing renderer state. */
+export class OverlayGeometryTracker {
+    publish;
+    #frame = [];
+    #pending;
+    #columns = 0;
+    #rows = 0;
+    ports = new WeakMap();
+    constructor(publish) {
+        this.publish = publish;
+    }
+    invalidate() {
+        if (this.#frame === null)
+            return;
+        this.#frame = null;
+        this.publish(null);
+    }
+    begin(columns, rows) {
+        this.#columns = columns;
+        this.#rows = rows;
+        this.#pending = [];
+    }
+    record(component, options, width, height) {
+        if (this.#pending === undefined)
+            return;
+        const region = overlayPointerSurface(component, options, width, height, this.#columns, this.#rows);
+        if (region !== undefined)
+            this.#pending.push(region);
+    }
+    end() {
+        const next = this.#pending ?? [];
+        this.#pending = undefined;
+        if (this.#frame !== null && samePointerSurfaces(this.#frame, next))
+            return;
+        this.#frame = next;
+        this.publish(next);
+    }
+}
+/** The protected composition hook brackets the actual visible, focus-ordered overlay renders. */
+export class GeometryObservedAltScreen extends TuiAltScreen {
+    geometry;
+    #overlayComponents = new WeakMap();
+    get overlayFocused() {
+        return this.isOverlayFocused();
+    }
+    setFocus(component) {
+        super.setFocus(component === null ? null : this.#overlayComponents.get(component) ?? component);
+    }
+    showOverlay(component, options) {
+        // Compatibility: all overlay entries cross the public method, including the runtime's search
+        // dialog. Observe a wrapper, never replace a method on an installed component.
+        const geometry = this.geometry;
+        const port = geometry?.ports.get(component) ?? component;
+        const wrapper = {
+            get focused() { return isFocusable(component) && component.focused; },
+            set focused(value) { if (isFocusable(component))
+                component.focused = value; },
+            get wantsKeyRelease() { return component.wantsKeyRelease ?? false; },
+            render(width) {
+                const lines = component.render(width);
+                geometry?.record(port, options, width, lines.length);
+                return lines;
+            },
+            invalidate: () => component.invalidate(),
+            handleInput: data => component.handleInput?.(data),
+        };
+        this.#overlayComponents.set(component, wrapper);
+        geometry?.invalidate();
+        const handle = super.showOverlay(wrapper, options);
+        return {
+            hide: () => { geometry?.invalidate(); handle.hide(); this.#overlayComponents.delete(component); },
+            setHidden: hidden => {
+                if (hidden !== handle.isHidden())
+                    geometry?.invalidate();
+                handle.setHidden(hidden);
+            },
+            isHidden: () => handle.isHidden(),
+            focus: () => { geometry?.invalidate(); handle.focus(); },
+            unfocus: target => {
+                geometry?.invalidate();
+                if (target === undefined)
+                    handle.unfocus();
+                else
+                    handle.unfocus({ target: target.target === null ? null : this.#overlayComponents.get(target.target) ?? target.target });
+            },
+            isFocused: () => handle.isFocused(),
+        };
+    }
+    hideOverlay() {
+        this.geometry?.invalidate();
+        super.hideOverlay();
+    }
+    compositeOverlays(lines, width, height) {
+        this.geometry?.begin(width, height);
+        const result = super.compositeOverlays(lines, width, height);
+        this.geometry?.end();
+        return result;
+    }
+}
+/** Compare only geometry and ownership, never animation content or transcript position. */
+export function samePointerSurfaces(a, b) {
+    return a.length === b.length && a.every((surface, index) => {
+        const other = b[index];
+        return surface.component === other.component && surface.columnStart === other.columnStart
+            && surface.columnEnd === other.columnEnd && surface.rowStart === other.rowStart && surface.rowEnd === other.rowEnd;
+    });
+}
+/**
+ * Resolve the pinned public overlay options against the actual render width/height.
+ * The runtime still owns layout and painting. Independent terminal-cell tests certify
+ * this option-to-hit-region projection against its compositor, including clipping.
+ */
+export function overlayPointerSurface(component, options, width, renderedHeight, columns, rows) {
+    const opt = options ?? {};
+    const margin = typeof opt.margin === "number"
+        ? { top: opt.margin, right: opt.margin, bottom: opt.margin, left: opt.margin }
+        : opt.margin ?? {};
+    const top = Math.max(0, margin.top ?? 0);
+    const right = Math.max(0, margin.right ?? 0);
+    const bottom = Math.max(0, margin.bottom ?? 0);
+    const left = Math.max(0, margin.left ?? 0);
+    const availableHeight = Math.max(1, rows - top - bottom);
+    const availableWidth = Math.max(1, columns - left - right);
+    const limit = size(opt.maxHeight, rows);
+    const height = limit === undefined ? renderedHeight : Math.min(renderedHeight, Math.floor(Math.max(1, Math.min(limit, availableHeight))));
+    const anchor = opt.anchor ?? "center";
+    const anchorRow = anchor.startsWith("top-") ? top
+        : anchor.startsWith("bottom-") ? top + availableHeight - height
+            : top + Math.floor((availableHeight - height) / 2);
+    const anchorColumn = anchor.endsWith("-left") || anchor === "left-center" ? left
+        : anchor.endsWith("-right") || anchor === "right-center" ? left + availableWidth - width
+            : left + Math.floor((availableWidth - width) / 2);
+    const row = Math.max(top, Math.min(position(opt.row, top, availableHeight, height, anchorRow) + (opt.offsetY ?? 0), rows - bottom - height));
+    const column = Math.max(left, Math.min(position(opt.col, left, availableWidth, width, anchorColumn) + (opt.offsetX ?? 0), columns - right - width));
+    if (height <= 0 || row >= rows || column >= columns)
+        return undefined;
+    return {
+        component,
+        rowStart: row + 1,
+        rowEnd: Math.min(rows, row + height),
+        columnStart: column + 1,
+        columnEnd: Math.min(columns, column + width),
+    };
+}
+function size(value, extent) {
+    if (typeof value !== "string")
+        return value;
+    const match = /^(\d+(?:\.\d+)?)%$/.exec(value);
+    return match === null ? undefined : Math.floor(extent * Number(match[1]) / 100);
+}
+function position(value, margin, available, extent, anchor) {
+    if (value === undefined)
+        return anchor;
+    if (typeof value === "number")
+        return value;
+    const percent = size(value, Math.max(0, available - extent));
+    return percent === undefined ? margin + Math.floor((available - extent) / 2) : margin + percent;
+}

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-12T13:59:03.140Z",
+  "builtAt": "2026-09-13T13:11:55.967Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-12T13:58:54.058Z",
+  "builtAt": "2026-09-13T13:12:46.201Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-12T13:59:34.009Z",
+  "builtAt": "2026-09-13T13:12:19.326Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "15e00144629345d7f00b110494775b80c65e6e575e6758d88b533c25b57d35d5",
+    "sha256": "e6a7be98f08249e90a59466be1c132959a55a80830b000a660724da4d572887a",
     "size": 177664
   },
   "provenance": {

package/dist/product-identity.d.ts

@@ -1,4 +1,4 @@
-declare const ENVIRONMENT_KEYS: readonly ["configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "paneId", "probeTrace", "processGuardianPath", "profileHome", "runtimeDir", "startupTrace", "terminalSessionId"];
+declare const ENVIRONMENT_KEYS: readonly ["configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "paneId", "probeTrace", "processGuardianPath", "profileHome", "runtimeDir", "startupTrace", "suggestionDiagnostics", "terminalSessionId"];
 declare const FILESYSTEM_KEYS: readonly ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
 declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile"];
 declare const ENDPOINT_KEYS: readonly ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];

package/dist/product-identity.js

@@ -1,7 +1,7 @@
 import rawIdentity from "./product-identity.json" with { type: "json" };
 const ENVIRONMENT_KEYS = [
     "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint",
-    "paneId", "probeTrace", "processGuardianPath", "profileHome", "runtimeDir", "startupTrace", "terminalSessionId",
+    "paneId", "probeTrace", "processGuardianPath", "profileHome", "runtimeDir", "startupTrace", "suggestionDiagnostics", "terminalSessionId",
 ];
 const FILESYSTEM_KEYS = ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
 const STATE_KEYS = ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile"];

package/dist/product-identity.json

@@ -22,6 +22,7 @@
         "profileHome": "A1_PROFILE_HOME",
         "runtimeDir": "A1_RUNTIME_DIR",
         "startupTrace": "A1_STARTUP_TRACE",
+        "suggestionDiagnostics": "A1_SUGGESTION_DIAGNOSTICS",
         "terminalSessionId": "A1_TERMINAL_SESSION_ID"
     },
     "state": {

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

@@ -2,6 +2,7 @@ export * from "./dialog-panel.js";
 export * from "./frame.js";
 export * from "./label.js";
 export * from "./line-input.js";
+export * from "./prompt-input.js";
 export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";

package/dist/ui/components/index.js

@@ -2,6 +2,7 @@ export * from "./dialog-panel.js";
 export * from "./frame.js";
 export * from "./label.js";
 export * from "./line-input.js";
+export * from "./prompt-input.js";
 export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";

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

@@ -1,3 +1,4 @@
+import type { UiTheme } from "./theme.js";
 export type LineInputOutcome = {
     readonly kind: "editing";
 } | {
@@ -47,9 +48,6 @@ export declare class LineInput {
 }
 /** Applies one key to the input and reports whether the caller should commit. */
 export declare function handleLineInputKey(input: LineInput, data: string): LineInputOutcome;
-/** Draws the reference prompt rule foreground-only so underlying cells survive. */
-export declare function promptRule(width: number): string;
-export declare const PROMPT_GLYPH = "\u001B[38;2;154;160;166m\u276F\u001B[39m ";
 /**
  * The caret the reference draws: the cell under it is reversed rather than given
  * a colour of its own, so it reads as a block in whatever theme is in use.
@@ -60,6 +58,7 @@ export interface InputRowOptions {
     readonly placeholder?: string;
     /** Rules above and below, in the prompt's own grey. Default true. */
     readonly ruled?: boolean;
+    readonly theme?: Pick<UiTheme, "fg">;
 }
 export interface InputRow {
     /** The rows to draw, already padded to the width. */

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

@@ -1,4 +1,5 @@
 import { displayWidth, faint, truncateToWidth } from "./text.js";
+import { PromptInput } from "./prompt-input.js";
 const MAX_VALUE_LENGTH = 4_096;
 const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 /** Character class for a word boundary: 0 space, 1 word, 2 anything else. */
@@ -198,11 +199,6 @@ export function handleLineInputKey(input, data) {
     input.insert(data);
     return { kind: "editing" };
 }
-/** Draws the reference prompt rule foreground-only so underlying cells survive. */
-export function promptRule(width) {
-    return `\u001b[38;2;154;160;166m${"─".repeat(Math.max(0, width))}\u001b[39m`;
-}
-export const PROMPT_GLYPH = `\u001b[38;2;154;160;166m❯\u001b[39m `;
 /**
  * The caret the reference draws: the cell under it is reversed rather than given
  * a colour of its own, so it reads as a block in whatever theme is in use.
@@ -212,8 +208,8 @@ export function caretCell(text) {
 }
 /** The input row as the reference draws one, padded to exactly the width. */
 export function renderInputRow(input, width, options = {}) {
-    const inner = Math.max(0, width - 2);
-    const view = input.view(inner);
+    const presentation = new PromptInput(options.theme);
+    const view = input.view(Math.max(0, width - presentation.geometry(width).prefixWidth));
     const placeholder = options.placeholder ?? "";
     const empty = view.text.length === 0 && placeholder.length > 0;
     const before = view.text.slice(0, view.caretColumn);
@@ -224,17 +220,5 @@ export function renderInputRow(input, width, options = {}) {
     const body = empty
         ? `${caretCell(placeholder.slice(0, 1))}${faint(placeholder.slice(1))}`
         : `${before}${caretCell(under)}${after}`;
-    const plain = empty
-        ? placeholder
-        : `${view.text}${view.caretColumn >= view.text.length ? " " : ""}`;
-    const row = padVisible(truncateToWidth(`${PROMPT_GLYPH}${body}`, width), width, `❯ ${plain}`);
-    if (options.ruled === false)
-        return { lines: [row] };
-    const rule = promptRule(width);
-    return { lines: [rule, row, rule] };
-}
-/** Pads by visible width, so styling escapes do not shift the layout. */
-function padVisible(line, width, raw) {
-    const visible = displayWidth(raw);
-    return visible >= width ? line : line + " ".repeat(width - visible);
+    return { lines: presentation.render(width, () => ({ rows: [body] }), options.ruled) };
 }

package/dist/ui/components/mouse.d.ts

@@ -22,4 +22,4 @@ export interface RoutedMouseInput {
  * Routes every SGR report independently, preserving keyboard bytes and mouse
  * reports the caller does not claim even when they share one physical chunk.
  */
-export declare function routeMouseInput(data: string, claim: (event: PaneMouseEvent) => boolean): RoutedMouseInput;
+export declare function routeMouseInput(data: string, claim: (event: PaneMouseEvent, report: string) => boolean): RoutedMouseInput;

package/dist/ui/components/mouse.js

@@ -40,12 +40,13 @@ export function routeMouseInput(data, claim) {
     let output = "";
     let index = 0;
     let consumed = false;
-    SGR_PATTERN.lastIndex = 0;
-    for (let match = SGR_PATTERN.exec(data); match !== null; match = SGR_PATTERN.exec(data)) {
+    // Concurrency: reentrant routing may deliver a report to another component using this parser.
+    const pattern = new RegExp(SGR_PATTERN.source, "g");
+    for (let match = pattern.exec(data); match !== null; match = pattern.exec(data)) {
         output += data.slice(index, match.index);
         index = match.index + match[0].length;
         const event = toEvent(Number.parseInt(match[1] ?? "", 10), Number.parseInt(match[2] ?? "", 10), Number.parseInt(match[3] ?? "", 10), match[4] === "m");
-        if (event !== null && claim(event))
+        if (event !== null && claim(event, match[0]))
             consumed = true;
         else
             output += match[0];

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

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

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

@@ -0,0 +1,54 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+import { PLAIN_THEME } from "./theme.js";
+export const PROMPT_GLYPH = "❯ ";
+export const PROMPT_PREFIX_WIDTH = 2;
+export function promptRuleText(text) {
+    return `\u001b[38;2;154;160;166m${text}\u001b[39m`;
+}
+export function promptRule(width) {
+    return promptRuleText("─".repeat(Math.max(0, width)));
+}
+export function promptArrow(text, theme) {
+    return theme.fg("muted", text);
+}
+/** Composes shared input chrome around controller-owned body rows without owning editing state. */
+export class PromptInput {
+    theme;
+    metrics;
+    constructor(theme = PLAIN_THEME, metrics = { measure: displayWidth, truncate: truncateToWidth }) {
+        this.theme = theme;
+        this.metrics = metrics;
+    }
+    styleRule(text) { return promptRuleText(text); }
+    geometry(width, padding = 0) {
+        const prefixWidth = Math.min(PROMPT_PREFIX_WIDTH, Math.max(0, width));
+        // Compatibility: editor wrapping needs room for a two-cell grapheme plus its cursor cell.
+        // Lay out against a safe virtual width, then clip only at the shared frame boundary.
+        const innerWidth = Math.max(3 + padding * 2, width - prefixWidth);
+        const paddingX = Math.min(padding, Math.max(0, Math.floor((innerWidth - 1) / 2)));
+        const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+        return { prefixWidth, innerWidth, paddingX, contentWidth, layoutWidth: Math.max(1, contentWidth - (paddingX ? 0 : 1)) };
+    }
+    render(width, renderBody, ruled = true, padding = 0) {
+        if (width <= 0)
+            return [];
+        const { prefixWidth, innerWidth } = this.geometry(width, padding);
+        const body = renderBody(innerWidth);
+        const fit = (row) => {
+            const clipped = this.metrics.truncate(row, width);
+            return clipped + " ".repeat(Math.max(0, width - this.metrics.measure(clipped)));
+        };
+        const rows = body.rows.map((row, index) => fit(`${index === 0
+            ? promptArrow(PROMPT_GLYPH, this.theme)
+            : " ".repeat(prefixWidth)}${row}`));
+        const rule = (fragment) => fragment === undefined
+            ? promptRule(width)
+            : fit(fragment + promptRule(Math.max(0, width - this.metrics.measure(fragment))));
+        return [
+            ...(ruled ? [rule(body.topRule)] : []),
+            ...rows,
+            ...(ruled ? [rule(body.bottomRule)] : []),
+            ...(body.after ?? []).map(row => fit(`${" ".repeat(prefixWidth)}${row}`)),
+        ];
+    }
+}

package/docs/architecture/boundaries.md

@@ -30,6 +30,7 @@ The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feat
 - `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.
 - `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.

package/docs/architecture/history-editor-provenance.md

@@ -39,7 +39,11 @@ snapshot installation and observation methods preserve input and undo state,
 freeze an active browse cycle, and change caret placement only in that mode.
 The editor renders position/overflow in its existing border. The position label
 uses an injected neutral status-text style (`dim`), while the surrounding rules
-retain the active input-border color, as clarified during manual review. Recall temporarily
+retain the active input-border color, as clarified during manual review. The approved
+`show-autocomplete-above-prompt` review refinement omits the literal `History` title:
+`─── 1/100 ─…` keeps the same four-cell inset, count calculation, dim color, optional
+scroll-overflow suffix, and clipping. Core and shell regressions verify numbering,
+100-entry recall, draft restoration, and the absence of the title. Recall temporarily
 separates the draft's live paste backing from recalled literal text, restoring it
 on return; ordinary pinned mode remains source-equivalent.
 

package/docs/architecture/project-structure.md

@@ -14,6 +14,7 @@ src/
     launch/                        launch profiles, profile paths, and runtime selection
     owned-ui/                      owned screens, settings application, diagnostics, and runtime lifecycle
     prompt-history/                profile-isolated prompt retention and bounded SQLite worker lifecycle
+    prompt-suggestions/            opt-in bounded metadata capture and local diagnostic snapshots
     workspace/                     multi-agent presentation, reducer state, routing, and persistence orchestration
   contracts/
     agent-engine/                  dependency-free agent engine, session, package, and capability ports

package/docs/architecture/prompt-suggestions.md

@@ -0,0 +1,68 @@
+# Prompt suggestion reliability
+
+Bare A1 predicts a short next user input with one isolated request using the selected model. A clear offered action consistent with recent user intent, such as `archive it` after accepted merged work, is preferred over abstaining merely because optional testing was also offered. Required validation, conflicting intent, and unresolved choices still allow no suggestion. There is no quoted-text extraction fallback.
+
+## Request and editor boundaries
+
+The adapter resolves the lowest supported effort from the selected session model's available thinking levels, without changing the main thinking setting. Non-reasoning models omit reasoning controls; supported `off` also omits the optional reasoning argument, matching the model runtime's ordinary completion contract. Other supported efforts are supplied explicitly. Missing capabilities produce `unavailable`, not a guessed provider option. Provider mapping/clamping remains owned by the pinned model runtime; the diagnostic policy describes the applied request option, not inferred server-side computation.
+
+The controller retains the 15-second deadline, does not retry or switch models, and retires a timeout before aborting. A provider that ignores abort cannot revive retired text. A timely candidate remains private until matching settlement. Ghost text is not editor content, approval, or a submission: Tab accepts it into the editor, and Enter must be pressed separately to submit it. Typing, session/model replacement, continuation, or disabling suggestions invalidates unaccepted work. `a1 pi` does not install this feature.
+
+## Opt-in local diagnostics
+
+Set `A1_SUGGESTION_DIAGNOSTICS` to a **dedicated writable file** when launching bare A1. It is an explicit snapshot destination, not a log directory. The parent directory must already exist. The selected file is overwritten with the latest bounded snapshot; never select a session, source, credential, or other valuable file. Do not share one destination between running processes.
+
+For a repository checkout in Git Bash:
+
+```sh
+npm run build && A1_SUGGESTION_DIAGNOSTICS="$PWD/.artifacts/suggestion-diagnostics.json" ./scripts/dev
+```
+
+Create `.artifacts` first if it does not exist. For an installed release, use the same environment assignment before `a1`. The variable follows the ordinary launch environment; it adds no interactive flag, setting, footer row, or transcript message. SDK composition can supply `suggestionDiagnosticsPath` explicitly. Comparison or settings-free compositions ignore both paths.
+
+While that session is running, inspect the selected JSON file using a local editor or:
+
+```sh
+node -e 'const fs=require("node:fs"); console.table(JSON.parse(fs.readFileSync(process.argv[1],"utf8")).records)' .artifacts/suggestion-diagnostics.json
+```
+
+The `prompt-suggestion-diagnostics-v1` snapshot contains at most 128 metadata records and 64 KiB. Capture is off by default. Records include process-local session/run/response/request numbers, bounded provider/model identifiers, applied reasoning policy, elapsed milliseconds, event, and optional reason. They exclude conversation/candidate text, tool data, raw errors, credentials, and session/worktree paths. There is no upload. Older records are evicted, so a retained terminal event can outlive its evicted start event. `request: 0` means no request was started for that decision.
+
+| Event | Meaning |
+| --- | --- |
+| `skipped` | No request started; inspect `reason`. |
+| `started` | One generator request was initiated; reasoning may be `unavailable` for an injected generator without policy metadata. |
+| `displayed` | A current candidate was shown after settlement. |
+| `empty` | The provider returned no text; this does not reveal the model's private reason for abstaining. |
+| `rejected` | Returned content violated the candidate contract, contained tool calls, was truncated, or had invalid formatting/voice. |
+| `provider-failure` | Provider error/rejection; raw error details are intentionally omitted. |
+| `unavailable` | Model/runtime/capabilities or request identity were unavailable at the generator boundary. |
+| `timeout` | The controller's 15-second deadline expired. |
+| `cancelled` | Work was invalidated or aborted, including typing or continuation. |
+| `stale-result` | A result or settlement identity did not match its request. |
+| `presentation-blocked` | A valid candidate could not be shown; inspect `reason`. |
+| `late-result-discarded` | A retired request eventually resolved/rejected; this is not a second terminal outcome or request. |
+
+Eligibility/presentation reasons include `disabled`, `disposed`, `early-conversation`, `no-model`, `failed-response`, `incomplete-response`, `tool-continuation`, `replacement-input`, `modal`, `draft`, `not-ready`, `not-focused`, `autocomplete`, `prompt-mode`, and `stale-identity`. `ineligible` and `presentation-unavailable` cover injected ports without finer metadata. A missing suggestion alone is never evidence of timeout or intentional model abstention.
+
+Writes are asynchronous and coalesced: at most one write and one pending latest snapshot. Sink failures do not affect generation, input, or rendering and do not appear in the UI. An unwritable destination may therefore produce no file; check the destination locally rather than diagnosing the model from that absence. Disposal clears in-memory capture and pending writes; a write already in progress can finish. Exported local files remain until you remove them.
+
+To disable capture, omit/unset `A1_SUGGESTION_DIAGNOSTICS` before the next launch and remove the dedicated snapshot if no longer needed. This does not disable suggestions; `/settings` -> Agent -> Prompt suggestions controls generation independently.
+
+## Verification and evidence limits
+
+The focused tests cover the synthetic archive offer and required-testing/unresolved-choice counterexamples, unchanged primary thinking, typed outcomes, timeout/cancellation races, editor acceptance, and local privacy/bounds:
+
+```sh
+npx vitest run test/integrations/pi/session-ui/prompt-suggestion-controller.test.ts test/integrations/pi/engine/adapter.test.ts test/features/prompt-suggestions/diagnostics.test.ts test/contracts/owned-ui/contracts.test.ts test/integrations/pi/session-ui/session-shell.test.ts
+```
+
+A separate opt-in probe uses the profile's saved model/authentication with a scratch cwd, in-memory sessions/settings, disabled extensions/skills/prompts, and no tools. It performs five original-policy predictions, five revised-policy predictions, and one required-testing counterexample. This makes **11 provider requests** and can consume quota. Run only with explicit authorization:
+
+```sh
+RUN_PROMPT_SUGGESTION_PROVIDER_TEST=1 PROMPT_SUGGESTION_AGENT_DIR="C:/path/to/agent-profile" npx vitest run test/integrations/pi/engine/prompt-suggestion-provider.integration.test.ts
+```
+
+The probe reports outcome/latency summaries and archival-candidate counts, not raw text. It requires at least one revised archival continuation and rejects an archival continuation in the required-testing case. Five samples are a smoke comparison, not a statistical reliability guarantee. Missing credentials, model availability, or a successful real archival prediction leave provider acceptance pending; fake tests do not prove model quality.
+
+For manual review, use a harmless synthetic conversation with two assistant responses: establish that an imaginary change was tested, accepted, and merged, then ask for a closeout offer containing `Say archive it` with optional extra testing. Do not ask the agent to perform real archival to test ghost text. Keep main thinking high and the editor untouched while waiting, inspect the outcome snapshot, check Tab/Enter separately, and repeat with typing cancellation and suggestions disabled. Verify required testing is not treated as optional. Real latency, model abstention, and existing context-reconstruction limitations can still leave the editor empty.

package/docs/architecture/toolchain.md

@@ -71,7 +71,7 @@ Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node sc
 
 ## Publication
 
-One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release` explicitly requests stable publication after its version pull request merges. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
+One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release -- patch` explicitly requests stable publication after its version pull request is manually merged; it promotes a development version to its stable core. The following development-version pull request also requires manual merge. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
 
 `docs/ci-release-runbook.md` is the operational reference.
 

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

@@ -47,6 +47,29 @@ its own `core` facade layer; A1 is a product, so the port adapts imports and kee
 
 ## Deliberate differences
 
+- **Above-prompt autocomplete.** The accepted `show-autocomplete-above-prompt` change
+  moves the existing default-editor completion block above the prompt in bare A1.
+  `src/integrations/pi/components/upstream/components/owned-editor.ts` exposes its
+  border-inclusive body height using the existing atomic-aware layout boundary;
+  `shell-editor-autocomplete.ts` moves rows only after prefix/selection decoration
+  and adds one top line using the editor's current border-color function.
+  The accepted refinement (#343) restores this line instead of panel shading.
+  The user-approved review refinement in #344 moves the existing trailing counter
+  into that line without parentheses, at the history-label inset and in the same dim
+  color. The select-list `scrollInfo` callback identifies its final counter row;
+  private selection state and rendered-frame parsing are not used. Counter meaning
+  and visibility remain unchanged, and candidate ANSI styling/padding stay intact. The line is
+  included in the body offset, disappears with the menu, and is non-text chrome.
+  Theme/mode/resize tests verify matching line color and width; terminal background
+  replay verifies the menu has no added shading.
+  The session shell uses the resulting body offset for pointer routing. Neither
+  editor implementation, history mode, menu sizing, completion state, nor installed
+  Pi package changes. `a1 pi` remains below-prompt and byte-identical to the independently
+  run pinned editor in `test/integrations/pi/components/pinned-editor-input-parity.test.ts`.
+  Placement and whole-menu ANSI evidence is in `editor-autocomplete-placement.test.ts`;
+  shell checkpoint replay covers final cells, cursor rows, resizing, detached/streaming
+  transcripts, widgets, pointer selection, and extension-editor restoration. Physical
+  acceptance of the exact build remains required before merging the implementation.
 - **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