@timurproko/a1 0.2.2-dev.611 → 0.2.3-dev.651

package/dist/cli/version-stats.js

@@ -20,14 +20,11 @@ export async function runVersionStats(options) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
         return 1;
     }
-    // Compatibility: match Pi's release behavior: stable builds print only their installed version.
-    // Development builds retain channel visibility for preview comparison and updates.
-    if (prerelease(installed) === null) {
-        output.stdout(`${installed}\n`);
-        return 0;
-    }
+    // Rationale: unlike Pi, stable builds also show the release channel head so users can see they are
+    // behind without starting a session. Only development builds show the preview channel.
     const remote = await queryDistTags(runner, options.fetcher ?? defaultRegistryFetcher);
-    output.stdout(`Current: ${installed}\nDevelop: ${remote.develop ?? "unavailable"}\nRelease: ${remote.release ?? "unavailable"}\n`);
+    const develop = prerelease(installed) === null ? "" : `Develop: ${remote.develop ?? "unavailable"}\n`;
+    output.stdout(`Current: ${installed}\n${develop}Release: ${remote.release ?? "unavailable"}\n`);
     if (remote.error)
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
     return 0;

package/dist/composition/owned-ui.d.ts

@@ -1,9 +1,11 @@
+import type { AvailableRelease, StartupReleaseCheckOptions } from "../foundation/release/latest-release.js";
 import type { SessionSelection } from "../foundation/lifecycle/session-selection.js";
 import type { PiEngineAdapter } from "../integrations/pi/engine/adapter.js";
 import type { PiProjectTrustPreflightPrompt } from "../integrations/pi/engine/project-trust-preflight.js";
 import type { PiSessionForkPrompt } from "../integrations/pi/engine/session-selection.js";
 import { OwnedSettingsManager } from "../ui/settings/manager.js";
 import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
+import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
 export interface OwnedUiCompositionOptions {
     readonly cwd?: string;
     readonly terminal?: PresentationTerminalPort;
@@ -27,6 +29,11 @@ export interface OwnedUiCompositionOptions {
     readonly suggestionDiagnosticsPath?: string;
     /** Optional local metadata-only clipboard diagnostics; never enabled in comparison profiles. */
     readonly clipboardDiagnosticsPath?: string;
+    /** Deterministic release-note seams for composition tests. */
+    readonly packageVersion?: string;
+    readonly releaseNotes?: ReleaseNoteCatalog;
+    /** Startup release-availability seam; defaults to the throttled registry check. */
+    readonly checkForNewerRelease?: (options: StartupReleaseCheckOptions) => Promise<AvailableRelease | null>;
 }
 export interface OwnedUiComposition {
     readonly application: OwnedUiApplicationPort;

package/dist/composition/owned-ui.js

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { SuggestionDiagnosticCapture } from "../features/prompt-suggestions/diagnostics.js";
 import { PRODUCT_IDENTITY } from "../product-identity.js";
 import { PromptHistoryService } from "../features/prompt-history/service.js";
@@ -14,7 +15,7 @@ import { OwnedSettingsManager } from "../ui/settings/manager.js";
 import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/presentation-adapter.js";
 import { createOwnedRouteHost } from "./settings-route-host.js";
 import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
-import { readPinnedCommandChangelog } from "../integrations/pi/engine/changelog.js";
+import { nativeHyperlinkStyle } from "../ui/components/spans.js";
 export async function composeOwnedUiApplication(options = {}) {
     return (await composeOwnedUi(options)).application;
 }
@@ -27,6 +28,7 @@ export async function composeOwnedUi(options = {}) {
             cwd,
             availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
             settingsProductMode: ownedSurfaces ? "bare" : "comparison",
+            announceStartupChangelog: !ownedSurfaces,
             ...(ownedSurfaces ? {
                 repositoryContextReader: async (sessionId, sessionFile, signal) => await readSessionRepositoryContext({ sessionId, sessionFile }, { signal }),
             } : {}),
@@ -35,6 +37,7 @@ export async function composeOwnedUi(options = {}) {
             ...(options.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: options.sessionForkPrompt }),
             ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
         });
+    const productPaths = resolveProductPaths();
     const settings = options.profileId === undefined
         ? null
         : new OwnedSettingsManager({
@@ -42,16 +45,37 @@ export async function composeOwnedUi(options = {}) {
             profileId: options.profileId,
             agentProvider: () => adapter.settingsPort(),
         });
+    let releaseNotes = null;
+    let releaseNotesFailure;
+    if (ownedSurfaces) {
+        try {
+            releaseNotes = options.releaseNotes
+                ?? await import("../features/owned-ui/release-notes.js").then(module => module.readPackagedReleaseNotes());
+        }
+        catch (error) {
+            releaseNotesFailure = error;
+        }
+    }
+    const packageVersion = ownedSurfaces
+        ? options.packageVersion ?? await readPackageVersion()
+        : null;
+    const currentReleaseNote = packageVersion === null ? null : releaseNotes?.current(packageVersion) ?? null;
+    const releaseNoteClaim = currentReleaseNote === null || options.profileId === undefined
+        ? null
+        : await import("../features/owned-ui/release-note-state.js").then(module => module.claimReleaseNote({
+            configDir: productPaths.configDir, profileId: options.profileId, version: currentReleaseNote.version,
+        }));
     // Compatibility: bare A1 intentionally ships one visual target while its UI is being completed:
     // dark, regardless of terminal detection or a previously stored Pi theme. The
     // comparison profile keeps Pi's configured theme behavior and settings surface.
     applyConfiguredPiTheme(ownedSurfaces ? "dark" : adapter.configuredTheme());
-    // Rationale: the reference screens read the shell the composition is about to construct; a route
-    // cannot open before the shell exists, so the closure is settled by the time it runs.
+    // Rationale: Routes open only after shell construction.
     const references = {
         changelog: async (input) => {
-            const markdown = input?.document ?? await readPinnedCommandChangelog();
-            return { rows: width => renderPiShellChangelogLines(markdown, width) };
+            if (input?.document === undefined && releaseNotesFailure !== undefined)
+                throw releaseNotesFailure;
+            const markdown = input?.document ?? releaseNotes?.completeMarkdown ?? "No A1 release notes found.";
+            return { rows: width => renderPiShellChangelogLines(markdown, width).map(row => nativeHyperlinkStyle(row)) };
         },
         hotkeys: async () => {
             const presentation = shell.hotkeysPresentation();
@@ -73,6 +97,10 @@ export async function composeOwnedUi(options = {}) {
         enabled: () => settings.value("promptSuggestions"),
         onChange: (listener) => settings.onChange(() => listener(settings.value("promptSuggestions"))),
     };
+    const promptImages = settings === null || !ownedSurfaces ? null : {
+        limit: () => settings.value("promptImageLimit"),
+        onChange: (listener) => settings.onChange(listener),
+    };
     const skills = settings === null || !ownedSurfaces ? null : {
         presentation: () => settings.value("skillsPresentation"),
         // Rationale: one listener covers both the A1 presentation choice and the engine skill-command toggle.
@@ -95,12 +123,23 @@ export async function composeOwnedUi(options = {}) {
     const clipboardDiagnostics = settings !== null && ownedSurfaces && clipboardDestination?.trim()
         ? new ClipboardDiagnosticCapture(clipboardDestination) : null;
     let shell;
+    let releaseNoteAcknowledgement = null;
     try {
         shell = new OwnedUiSessionShell({
             engine: {
                 backend: adapter,
                 cwd: adapter.cwd,
                 ...(routeHost === null ? {} : { routeHost }),
+                ...(currentReleaseNote === null || releaseNoteClaim === null ? {} : {
+                    startupRoute: {
+                        route: "changelog",
+                        input: { document: currentReleaseNote.markdown },
+                        onClosed: () => {
+                            releaseNoteAcknowledgement ??= releaseNoteClaim.acknowledge();
+                            return releaseNoteAcknowledgement;
+                        },
+                    },
+                }),
                 ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
             },
             presentation: {
@@ -116,6 +155,7 @@ export async function composeOwnedUi(options = {}) {
                     paste: event => clipboardDiagnostics.paste(event),
                 } }),
             ...(promptSuggestions === null ? {} : { suggestions: promptSuggestions }),
+            ...(promptImages === null ? {} : { promptImages }),
             ...(skills === null ? {} : { skills }),
             ...(promptHistory === null ? {} : { history: {
                     ...promptHistory,
@@ -124,20 +164,41 @@ export async function composeOwnedUi(options = {}) {
         });
     }
     catch (error) {
+        await releaseNoteClaim?.release();
         clipboardDiagnostics?.dispose();
         suggestionDiagnostics?.dispose();
         throw error;
     }
+    // Rationale: pinned Pi's version check is unreachable because the owned shell never runs its
+    // InteractiveMode, so A1 checks its own channel. The result is never awaited on the startup path;
+    // settings are read here because the runner resolves them only just before start.
+    const announceNewerRelease = async () => {
+        const check = options.checkForNewerRelease
+            ?? (await import("../foundation/release/latest-release.js")).checkForNewerRelease;
+        const release = await check({
+            runningVersion: packageVersion ?? await readPackageVersion(),
+            configDir: productPaths.configDir,
+            interactive: process.stdout.isTTY === true,
+            ...(settings === null || !ownedSurfaces ? {} : { settingEnabled: settings.value("updateCheck") }),
+        });
+        if (release !== null)
+            adapter.announceReleaseUpdate(release);
+    };
     const application = {
         get disposed() { return adapter.disposed; },
-        start: () => shell.start(),
+        start: () => {
+            shell.start();
+            void announceNewerRelease().catch(() => undefined);
+        },
         flush: () => adapter.flushEvents(),
         waitUntilStopped: () => shell.waitUntilStopped(),
         dispose: async () => {
             try {
                 await shell.dispose();
+                await releaseNoteAcknowledgement?.catch(() => undefined);
             }
             finally {
+                await releaseNoteClaim?.release();
                 suggestionDiagnostics?.dispose();
                 clipboardDiagnostics?.dispose();
             }
@@ -145,6 +206,13 @@ export async function composeOwnedUi(options = {}) {
     };
     return { application, settings };
 }
+async function readPackageVersion() {
+    const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+    const version = manifest?.version;
+    if (typeof version !== "string")
+        throw new Error("A1 package version is unavailable");
+    return version;
+}
 function quitOutroSettingsSnapshot(settings) {
     return {
         enabled: settings.value("quitAnimation"),

package/dist/contracts/owned-ui/image-attachments.d.ts

@@ -1,5 +1,7 @@
 import type { OwnedUiImageAttachment } from "./model.js";
-export declare const MAX_PROMPT_IMAGES = 8;
+export declare const DEFAULT_PROMPT_IMAGE_LIMIT = 8;
+/** Absolute command boundary; the bare-A1 editor may choose a lower live limit. */
+export declare const MAX_PROMPT_IMAGES = 16;
 /** Owned clipboard text is bounded before transfer, normalization, or editor insertion. */
 export declare const MAX_CLIPBOARD_TEXT_BYTES: number;
 /** Limit applies to canonical ASCII base64, not decoded image bytes. */
@@ -11,7 +13,7 @@ declare const MESSAGES: {
     readonly "paste-busy": "Clipboard preparation is full (8 pending pastes).";
     readonly "paste-write-failed": "Paste skipped because the preceding copy failed.";
     readonly "image-size": "Image exceeds the 8 MiB encoded base64 limit. Reduce the image size and paste it again.";
-    readonly "image-count": "A prompt supports at most 8 images. Remove an attachment before adding another.";
+    readonly "image-count": "A prompt has too many images.";
     readonly "image-data": "Image data is invalid. Paste a valid image again.";
     readonly "image-mime": "Image MIME type is invalid. Paste a supported image again.";
     readonly "image-source-size": "Source image exceeds 20 MiB. Reduce the source size and paste it again.";
@@ -27,10 +29,11 @@ declare const MESSAGES: {
 /** Trusted, payload-free diagnostics for user-correctable attachment failures. */
 export declare class ImageAttachmentError extends TypeError {
     readonly code: keyof typeof MESSAGES;
-    constructor(code: keyof typeof MESSAGES);
+    readonly imageLimit: number | null;
+    constructor(code: keyof typeof MESSAGES, imageLimit?: number);
 }
 /** Checks encoded length before decoding or copying a clipboard payload. */
 export declare function assertImageEncodedSize(data: string): void;
 /** Final command admission also covers restored and deferred non-clipboard inputs. */
-export declare function assertPromptImages(images: readonly OwnedUiImageAttachment[]): void;
+export declare function assertPromptImages(images: readonly OwnedUiImageAttachment[], imageLimit?: number): void;
 export {};

package/dist/contracts/owned-ui/image-attachments.js

@@ -1,4 +1,6 @@
-export const MAX_PROMPT_IMAGES = 8;
+export const DEFAULT_PROMPT_IMAGE_LIMIT = 8;
+/** Absolute command boundary; the bare-A1 editor may choose a lower live limit. */
+export const MAX_PROMPT_IMAGES = 16;
 /** Owned clipboard text is bounded before transfer, normalization, or editor insertion. */
 export const MAX_CLIPBOARD_TEXT_BYTES = 16 * 1024 * 1024;
 /** Limit applies to canonical ASCII base64, not decoded image bytes. */
@@ -10,7 +12,7 @@ const MESSAGES = {
     "paste-busy": "Clipboard preparation is full (8 pending pastes).",
     "paste-write-failed": "Paste skipped because the preceding copy failed.",
     "image-size": "Image exceeds the 8 MiB encoded base64 limit. Reduce the image size and paste it again.",
-    "image-count": "A prompt supports at most 8 images. Remove an attachment before adding another.",
+    "image-count": "A prompt has too many images.",
     "image-data": "Image data is invalid. Paste a valid image again.",
     "image-mime": "Image MIME type is invalid. Paste a supported image again.",
     "image-source-size": "Source image exceeds 20 MiB. Reduce the source size and paste it again.",
@@ -26,9 +28,14 @@ const MESSAGES = {
 /** Trusted, payload-free diagnostics for user-correctable attachment failures. */
 export class ImageAttachmentError extends TypeError {
     code;
-    constructor(code) {
-        super(MESSAGES[code]);
+    imageLimit;
+    constructor(code, imageLimit = DEFAULT_PROMPT_IMAGE_LIMIT) {
+        assertPromptImageLimit(imageLimit);
+        super(code === "image-count"
+            ? `A prompt is limited to ${imageLimit} ${imageLimit === 1 ? "image" : "images"}. To change the limit /settings.`
+            : MESSAGES[code]);
         this.code = code;
+        this.imageLimit = code === "image-count" ? imageLimit : null;
         this.name = "ImageAttachmentError";
     }
 }
@@ -42,9 +49,10 @@ export function assertImageEncodedSize(data) {
 const VALIDATED_IMAGES = new WeakSet();
 const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 /** Final command admission also covers restored and deferred non-clipboard inputs. */
-export function assertPromptImages(images) {
-    if (!Array.isArray(images) || images.length > MAX_PROMPT_IMAGES)
-        throw new ImageAttachmentError("image-count");
+export function assertPromptImages(images, imageLimit = MAX_PROMPT_IMAGES) {
+    assertPromptImageLimit(imageLimit);
+    if (!Array.isArray(images) || images.length > imageLimit)
+        throw new ImageAttachmentError("image-count", imageLimit);
     for (const image of images) {
         if (!image || image.type !== "image")
             throw new ImageAttachmentError("image-data");
@@ -65,3 +73,8 @@ export function assertPromptImages(images) {
         }
     }
 }
+function assertPromptImageLimit(imageLimit) {
+    if (!Number.isSafeInteger(imageLimit) || imageLimit < 1 || imageLimit > MAX_PROMPT_IMAGES) {
+        throw new RangeError(`Prompt image limit must be an integer from 1 through ${MAX_PROMPT_IMAGES}`);
+    }
+}

package/dist/contracts/owned-ui/index.d.ts

@@ -3,7 +3,7 @@ export type { OwnedUiExtensionAutocompleteItem, OwnedUiExtensionAutocompleteProv
 export { OWNED_UI_CONTRACT_VERSION } from "./model.js";
 export type { OwnedUiBlockStatus, OwnedUiCommand, OwnedUiCommandOutcome, OwnedUiCorrelationId, OwnedUiCustomization, OwnedUiDiagnostics, OwnedUiDialog, OwnedUiEditorState, OwnedUiEntityId, OwnedUiEvent, OwnedUiFooterView, OwnedUiImageAttachment, OwnedUiLifecycle, OwnedUiModelInfo, OwnedUiOverlay, OwnedUiPromptSuggestionGeneratorPort, OwnedUiPromptSuggestionIdentity, OwnedUiPromptSuggestionReasoning, OwnedUiPromptSuggestionRequest, OwnedUiPromptSuggestionResult, OwnedUiPromptSuggestionState, OwnedUiQuitOutroSettings, OwnedUiQuitOutroSettingsPort, OwnedUiSessionId, OwnedUiSessionViewModel, OwnedUiSeverity, OwnedUiSlotId, OwnedUiSnapshot, OwnedUiStatusView, OwnedUiTerminalSurface, OwnedUiThinkingLevel, OwnedUiToolRendering, OwnedUiToolResultPart, OwnedUiToolState, OwnedUiTranscriptBlock, OwnedUiTranscriptBlockKind, OwnedUiTranscriptImageReference, OwnedUiUsageView, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, } from "./model.js";
 export { acceptsTranscriptUpdate, transcriptToolState } from "./transcript-lifecycle.js";
-export { ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
+export { DEFAULT_PROMPT_IMAGE_LIMIT, ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
 export { CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, normalizePromptSuggestionCandidate } from "./prompt-suggestions.js";
 export { canonicalPromptChipMatches, protectPromptChipWrapping, replaceCanonicalPromptChips } from "./prompt-chips.js";
 export type { PromptChipTextMatch, PromptChipWrapProtection } from "./prompt-chips.js";

package/dist/contracts/owned-ui/index.js

@@ -1,7 +1,7 @@
 export { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiExtensionUiPort, } from "./extension-ui.js";
 export { OWNED_UI_CONTRACT_VERSION } from "./model.js";
 export { acceptsTranscriptUpdate, transcriptToolState } from "./transcript-lifecycle.js";
-export { ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
+export { DEFAULT_PROMPT_IMAGE_LIMIT, ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
 export { CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, normalizePromptSuggestionCandidate } from "./prompt-suggestions.js";
 export { canonicalPromptChipMatches, protectPromptChipWrapping, replaceCanonicalPromptChips } from "./prompt-chips.js";
 export { SUGGESTION_DECISION_REASONS, SUGGESTION_DIAGNOSTIC_EVENTS } from "./suggestion-diagnostics.js";

package/dist/contracts/owned-ui/prompt-chips.d.ts

@@ -11,5 +11,5 @@ export interface PromptChipWrapProtection {
 export declare function canonicalPromptChipMatches(text: string): readonly PromptChipTextMatch[];
 /** Replaces only canonical prompt-chip labels while preserving every intervening source byte. */
 export declare function replaceCanonicalPromptChips(text: string, replacement: (match: PromptChipTextMatch) => string): string;
-/** Protects fitting chip labels for Markdown wrapping and restores their exact visible source text. */
-export declare function protectPromptChipWrapping(text: string): PromptChipWrapProtection;
+/** Protects chip labels for wrapping, optionally presents a derived label, and removes all sentinels. */
+export declare function protectPromptChipWrapping(text: string, present?: (chip: string) => string): PromptChipWrapProtection;

package/dist/contracts/owned-ui/prompt-chips.js

@@ -12,20 +12,23 @@ export function replaceCanonicalPromptChips(text, replacement) {
         text: value, start: offset, end: offset + value.length,
     }));
 }
-/** Protects fitting chip labels for Markdown wrapping and restores their exact visible source text. */
-export function protectPromptChipWrapping(text) {
+/** Protects chip labels for wrapping, optionally presents a derived label, and removes all sentinels. */
+export function protectPromptChipWrapping(text, present = identity) {
     const matches = canonicalPromptChipMatches(text);
     if (matches.length === 0)
         return { text, restore: identity };
     const spaceMarker = unusedPrivateMarker(text);
     const boundaryMarker = unusedZeroWidthMarker(text);
+    const boundary = `${boundaryMarker} `;
     let protectedText = "", cursor = 0;
     for (const match of matches) {
         protectedText += text.slice(cursor, match.start);
-        // Rationale: adjacent chips need a temporary break opportunity or Markdown treats the complete run as one word.
-        if (match.start === cursor && cursor > 0)
-            protectedText += `${boundaryMarker} `;
-        protectedText += match.text.replaceAll(" ", spaceMarker);
+        // Rationale: temporary break opportunities keep each chip independent from adjacent chips or prose.
+        if (match.start > 0 && match.start !== cursor && !/\s/u.test(text[match.start - 1]))
+            protectedText += boundary;
+        protectedText += present(match.text).replaceAll(" ", spaceMarker);
+        if (match.end < text.length && !/\s/u.test(text[match.end]))
+            protectedText += boundary;
         cursor = match.end;
     }
     protectedText += text.slice(cursor);

package/dist/features/owned-ui/project-trust-prompt.js

@@ -2,6 +2,13 @@ import { EMERGENCY_TERMINAL_RESET } from "../../foundation/terminal-cleanup/term
 const ENTER_ALTERNATE_SCREEN = "\u001b[?1049h";
 const HIDE_CURSOR = "\u001b[?25l";
 const CLEAR_HOME = "\u001b[2J\u001b[H";
+const HOME = "\u001b[H";
+const ERASE_LINE_END = "\u001b[K";
+const ERASE_BELOW = "\u001b[J";
+const BEGIN_SYNC = "\u001b[?2026h";
+const END_SYNC = "\u001b[?2026l";
+const REQUEST_CURSOR_POSITION = "\u001b[6n";
+const CURSOR_POSITION_REPORT = /^\u001b\[(\d+);(\d+)R/u;
 const ACCENT = "\u001b[38;2;138;190;183m";
 const MUTED = "\u001b[38;2;128;128;128m";
 const DIM = "\u001b[38;2;102;102;102m";
@@ -32,6 +39,8 @@ export function createConsoleProjectTrustPrompt(options = {}) {
         const wasRaw = input.isRaw === true;
         let selected = 0;
         let restored = false;
+        // Protocol: the parent screen's cursor, reported before the first frame moves it.
+        let origin;
         const restore = () => {
             if (restored)
                 return;
@@ -39,6 +48,21 @@ export function createConsoleProjectTrustPrompt(options = {}) {
             input.setRawMode?.(wasRaw);
             output.write(`${CLEAR_HOME}${EMERGENCY_TERMINAL_RESET}`);
         };
+        // Protocol: a resolved bare selection hands the alternate screen to the shell, which
+        // enters it again. Leaving it here would show the parent screen until the shell's first
+        // frame. The shell's own enter saves the cursor, so park it where the parent had it and
+        // its leave restores the parent position. Without a position report, restore instead.
+        const handOff = () => {
+            if (renderBareDialog === undefined || origin === undefined) {
+                restore();
+                return;
+            }
+            if (restored)
+                return;
+            restored = true;
+            input.setRawMode?.(wasRaw);
+            output.write(`${BEGIN_SYNC}${CLEAR_HOME}\u001b[${origin.row};${origin.column}H${END_SYNC}`);
+        };
         const render = () => {
             const width = Math.max(renderBareDialog ? 1 : 20, output.columns ?? 80);
             const rows = Math.max(1, output.rows ?? 24);
@@ -52,12 +76,17 @@ export function createConsoleProjectTrustPrompt(options = {}) {
                 "",
                 `${DIM}↑/↓${MUTED} to navigate  ${DIM}Enter${MUTED} to select  ${DIM}Esc${MUTED} to cancel${RESET_FG}`,
             ]).map(line => clipAnsiSafe(line, width));
-            const padding = renderBareDialog === undefined ? "" : "\n".repeat(Math.max(0, rows - lines.length));
-            output.write(`${CLEAR_HOME}${padding}${lines.join("\n")}`);
+            const padded = renderBareDialog === undefined
+                ? lines : [...Array(Math.max(0, rows - lines.length)).fill(""), ...lines];
+            // Rationale: overwrite in place within one synchronized frame; clearing first flickers.
+            output.write(`${BEGIN_SYNC}${HOME}${padded.map(line => `${line}${ERASE_LINE_END}`).join("\n")}${ERASE_BELOW}${END_SYNC}`);
         };
         try {
             output.write(`${ENTER_ALTERNATE_SCREEN}${HIDE_CURSOR}`);
             input.setRawMode?.(true);
+            // Invariant: entering the alternate screen keeps the cursor, so this reports the parent's.
+            if (renderBareDialog !== undefined)
+                output.write(REQUEST_CURSOR_POSITION);
             render();
             return await new Promise((resolve, reject) => {
                 let settled = false;
@@ -66,7 +95,7 @@ export function createConsoleProjectTrustPrompt(options = {}) {
                         return;
                     settled = true;
                     cleanup();
-                    restore();
+                    handOff();
                     resolve(value);
                 };
                 const fail = (error) => {
@@ -81,6 +110,13 @@ export function createConsoleProjectTrustPrompt(options = {}) {
                 const onData = (chunk) => {
                     const data = chunk.toString();
                     for (let index = 0; index < data.length;) {
+                        const report = origin === undefined && renderBareDialog !== undefined
+                            ? CURSOR_POSITION_REPORT.exec(data.slice(index)) : null;
+                        if (report !== null) {
+                            origin = { row: Number(report[1]), column: Number(report[2]) };
+                            index += report[0].length;
+                            continue;
+                        }
                         if (data.startsWith("\u001b[A", index)) {
                             selected = (selected - 1 + choices.length) % choices.length;
                             index += 3;

package/dist/features/owned-ui/release-note-state.d.ts

@@ -0,0 +1,13 @@
+export interface ReleaseNoteClaim {
+    readonly version: string;
+    acknowledge(): Promise<void>;
+    release(): Promise<void>;
+}
+export interface ReleaseNoteStateOptions {
+    readonly configDir: string;
+    readonly profileId: string;
+    readonly version: string;
+    readonly now?: () => number;
+}
+/** Claims one stable note across concurrent sessions and acknowledges it only after presentation closes. */
+export declare function claimReleaseNote(options: ReleaseNoteStateOptions): Promise<ReleaseNoteClaim | null>;

package/dist/features/owned-ui/release-note-state.js

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import semver from "semver";
+const STATE_VERSION = 1;
+const MAX_STATE_BYTES = 4096;
+const CLAIM_MAX_AGE_MS = 60 * 60_000;
+const PROFILE = /^[a-z][a-z0-9-]{0,63}$/u;
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+/** Claims one stable note across concurrent sessions and acknowledges it only after presentation closes. */
+export async function claimReleaseNote(options) {
+    if (!PROFILE.test(options.profileId))
+        throw new Error("release-note profile is invalid");
+    if (!STABLE.test(options.version) || semver.valid(options.version) !== options.version)
+        return null;
+    const directory = resolve(options.configDir, "release-notes");
+    const statePath = join(directory, `${options.profileId}.json`);
+    const claimPath = join(directory, `${options.profileId}.claim.json`);
+    const acknowledged = await readAcknowledged(statePath);
+    if (acknowledged !== null && semver.gte(acknowledged, options.version))
+        return null;
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const now = options.now ?? Date.now;
+    const token = randomUUID();
+    const claim = { version: STATE_VERSION, token, release: options.version, claimedAt: now() };
+    if (!await createClaim(claimPath, claim)) {
+        if (!await staleClaim(claimPath, now()))
+            return null;
+        await rm(claimPath, { force: true });
+        if (!await createClaim(claimPath, claim))
+            return null;
+    }
+    let settled = false;
+    const ownsClaim = async () => {
+        try {
+            const current = await boundedJson(claimPath);
+            return current.token === token;
+        }
+        catch {
+            return false;
+        }
+    };
+    const release = async () => {
+        if (settled)
+            return;
+        settled = true;
+        if (await ownsClaim())
+            await rm(claimPath, { force: true });
+    };
+    return Object.freeze({
+        version: options.version,
+        acknowledge: async () => {
+            if (settled || !await ownsClaim())
+                return;
+            const prior = await readAcknowledged(statePath);
+            const version = prior !== null && semver.gt(prior, options.version) ? prior : options.version;
+            const temporary = `${statePath}.${process.pid}.${token}.tmp`;
+            await writeFile(temporary, `${JSON.stringify({ version: STATE_VERSION, acknowledged: version }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+            await rename(temporary, statePath);
+            settled = true;
+            await rm(claimPath, { force: true });
+        },
+        release,
+    });
+}
+async function readAcknowledged(path) {
+    try {
+        const value = await boundedJson(path);
+        if (value.version !== STATE_VERSION || typeof value.acknowledged !== "string"
+            || !STABLE.test(value.acknowledged) || semver.valid(value.acknowledged) !== value.acknowledged)
+            return null;
+        return value.acknowledged;
+    }
+    catch (error) {
+        return error?.code === "ENOENT" ? null : null;
+    }
+}
+async function boundedJson(path) {
+    const info = await stat(path);
+    if (!info.isFile() || info.size > MAX_STATE_BYTES)
+        throw new Error("release-note state is invalid");
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function createClaim(path, value) {
+    try {
+        const handle = await open(path, "wx", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+async function staleClaim(path, now) {
+    try {
+        const value = await boundedJson(path);
+        return typeof value.claimedAt !== "number" || !Number.isFinite(value.claimedAt) || now - value.claimedAt > CLAIM_MAX_AGE_MS;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/features/owned-ui/release-notes.d.ts

@@ -0,0 +1,10 @@
+export interface PackagedReleaseNote {
+    readonly version: string;
+    readonly markdown: string;
+}
+export interface ReleaseNoteCatalog {
+    readonly releases: readonly PackagedReleaseNote[];
+    readonly completeMarkdown: string;
+    current(version: string): PackagedReleaseNote | null;
+}
+export declare function readPackagedReleaseNotes(path?: URL): Promise<ReleaseNoteCatalog>;