@timurproko/a1 0.2.7-dev.1275 → 0.2.7-dev.1285

package/dist/cli/dispatch.js

@@ -20,6 +20,10 @@ export function cliUsage(capabilities) {
         "uninstall [--yes] [--purge]",
         "uninstall <source>",
         "list",
+        "worktree enter <branch> [--base <branch>]",
+        "worktree attach <path>",
+        "worktree detach",
+        "worktree list",
         "session worktrees",
         "session link-worktree <path>",
         "session unlink-worktree",
@@ -51,7 +55,13 @@ export function cliHelp(capabilities) {
         `  ${command} uninstall <source>`,
         `  ${command} list`,
         "",
-        "Session context:",
+        "Worktrees (successful enter/attach is authoritative; detach preserves files):",
+        `  ${command} worktree enter <branch> [--base <branch>]`,
+        `  ${command} worktree attach <path>`,
+        `  ${command} worktree detach`,
+        `  ${command} worktree list`,
+        "",
+        "Session context (compatibility aliases):",
         `  ${command} session worktrees`,
         `  ${command} session link-worktree <path>`,
         `  ${command} session unlink-worktree`,
@@ -123,6 +133,8 @@ export function parseCliCommand(arguments_, capabilities) {
     }
     if (command === "update")
         return parseUpdate(rest, capabilities.runningChannel ?? "stable");
+    if (command === "worktree")
+        return parseWorktree(rest);
     if (command === "session")
         return parseSessionContext(rest);
     if (command?.startsWith("update:"))
@@ -131,6 +143,20 @@ export function parseCliCommand(arguments_, capabilities) {
     // explicit, and a typo must never start an interactive or maintenance path.
     return { kind: "noop" };
 }
+function parseWorktree(rest) {
+    const [action, value, flag, base, extra] = rest;
+    if (action === "enter" && value !== undefined && !value.startsWith("-")
+        && (flag === undefined || (flag === "--base" && base !== undefined && !base.startsWith("-"))) && extra === undefined) {
+        return { kind: "session-context", request: { action: "enter-worktree", branch: value, ...(base === undefined ? {} : { base }) } };
+    }
+    if (action === "attach" && value !== undefined && flag === undefined) {
+        return { kind: "session-context", request: { action: "link-worktree", path: value } };
+    }
+    if ((action === "detach" || action === "list") && value === undefined) {
+        return { kind: "session-context", request: { action: action === "detach" ? "unlink-worktree" : "worktrees" } };
+    }
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic("worktree accepts enter <branch> [--base <branch>], attach <path>, detach, or list.") };
+}
 function parseSessionContext(rest) {
     const [action, value, extra] = rest;
     if (action === "link-worktree") {

package/dist/cli/packages.js

@@ -21,7 +21,7 @@ export async function runPackageCommand(request, environment) {
     const port = environment.createPort({
         profileRoot,
         cwd,
-        onProgress: progress => stdout(style.dim(`${progress.message}\n`)),
+        onProgress: progress => stdout((progress.severity === "warning" ? style.yellow : style.dim)(`${progress.message}\n`)),
         onDiagnostic: diagnostic => {
             stderr(`${style.yellow(diagnostic.message)}\n`);
             if (diagnostic.detail)
@@ -60,11 +60,27 @@ export function renderPackageOutcome(outcome, style = chalk) {
         case "remove":
             return `${style.green(`Removed ${outcome.source}`)}\n`;
         case "update":
-            return `${style.green(outcome.source === null ? "Updated packages" : `Updated ${outcome.source}`)}\n`;
+            return renderPackageUpdate(outcome, style);
         case "list":
             return renderPackageList(outcome, style);
     }
 }
+function renderPackageUpdate(outcome, style) {
+    const summary = outcome.updateSummary;
+    if (summary?.offline)
+        return `${style.yellow("Skipped package updates (offline mode)")}\n`;
+    const changes = summary?.changes ?? [];
+    if (changes.length > 0) {
+        const heading = `Updated ${changes.length} package${changes.length === 1 ? "" : "s"}:`;
+        return `${style.green(heading)}\n${changes.map(change => `  ${change}\n`).join("")}`;
+    }
+    if (summary?.warningCount) {
+        return `${style.yellow(outcome.source
+            ? `${outcome.source} was not updated, see the warnings above`
+            : "No packages were updated, see the warnings above")}\n`;
+    }
+    return `${style.green(outcome.source ? `${outcome.source} is already up to date` : "Packages are already up to date")}\n`;
+}
 function renderPackageList(outcome, style) {
     if (outcome.packages.length === 0)
         return `${style.dim("No packages installed.")}\n`;

package/dist/cli/session-context.js

@@ -16,7 +16,7 @@ export async function runSessionContextCommand(request, options = {}) {
         if (outcome.kind === "unlinked")
             stdout("Session worktree context cleared.\n");
         if (outcome.kind === "linked")
-            stdout(`Session worktree context linked: ${outcome.cwd}\n`);
+            stdout(`Session worktree context linked: ${outcome.cwd} (${outcome.branch})\n`);
         if (outcome.kind === "worktrees") {
             for (const entry of outcome.entries) {
                 // Compatibility: the primary agent is the only agent of a single-session runtime, so it stays unnamed.
@@ -44,7 +44,7 @@ function readIdentity(environment) {
 /** Known coordination failures must not expose internal paths or another session's identity. */
 function recoveryDetail(code) {
     const details = {
-        "worktree-claim-busy": "another mutation is still running; runtime registration retries automatically, so retry this link shortly",
+        "worktree-claim-busy": "coordination did not settle within the operation budget; no ownership was changed; retry this link shortly if the system remains busy",
         "worktree-legacy-recovery-required": "an older-format worktree lock requires safe recovery; stop all older A1 processes, move only session-worktree-claims/mutation.lock to a backup while stopped, then start the updated A1; keep all sessions and worktree claims",
         "worktree-coordination-unavailable": "worktree coordination is unavailable; repair or update this A1 installation, then retry",
         "worktree-coordination-io": "worktree coordination could not access its files; check A1 data-directory permissions and filesystem availability, then retry",
@@ -54,6 +54,10 @@ function recoveryDetail(code) {
         "session-runtime-stopped": "this shell belongs to a stopped runtime; resume in a running A1 session before linking",
         "worktree-active-in-another-session": "another live agent owns this worktree; use a different worktree or wait for its owner to release it",
         "worktree-owner-unverifiable": "worktree ownership cannot be verified; retain the claim and use another worktree rather than forcing recovery",
+        "worktree-primary-checkout": "attach a task worktree, not the primary checkout; use worktree enter to create one",
+        "worktree-git-locked": "Git has locked this worktree; retain it and ask its owner to release the lock",
+        "worktree-foreign-repository": "the selected worktree belongs to a different repository; the previous attachment was preserved",
+        "worktree-context-changed": "the attachment changed during the operation; no ownership was overridden",
     };
     return code === null ? undefined : details[code];
 }

package/dist/composition/owned-ui.js

@@ -17,22 +17,23 @@ import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/presentat
 import { createOwnedRouteHost } from "./settings-route-host.js";
 import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
 import { nativeHyperlinkStyle } from "../ui/components/spans.js";
-import { SessionRuntimeRegistry } from "./session-runtime-registry.js";
 import { bindAutomaticSessionNaming } from "./session-naming.js";
 import { deferStartupReleaseUpdateObservation, readPackageVersion, StartupReleaseNote } from "./startup-route.js";
 import { createOwnedSettingsManager, watchSharedSettings } from "./owned-settings.js";
 /** Production default: without an inspector the registry never registers; loaded lazily. */
 const inspectLiveProcessOnDemand = async (pid) => (await import("../foundation/lifecycle/process-liveness.js")).inspectLiveProcess(pid);
+/** Load coordination only when composing a session, not while evaluating the startup facade. */
+async function createSessionRuntimes(bare, inspectProcess) {
+    const { SessionRuntimeRegistry } = await import("./session-runtime-registry.js");
+    return new SessionRuntimeRegistry({ runtimeId: bare ? process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] : undefined, inspectProcess });
+}
 export async function composeOwnedUiApplication(options = {}) {
     return (await composeOwnedUi(options)).application;
 }
 export async function composeOwnedUi(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const productMode = options.productMode ?? "bare", bare = productMode === "bare";
-    const sessionRuntimes = new SessionRuntimeRegistry({
-        runtimeId: bare ? process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] : undefined,
-        inspectProcess: options.inspectProcess ?? inspectLiveProcessOnDemand,
-    });
+    const sessionRuntimes = await createSessionRuntimes(bare, options.inspectProcess ?? inspectLiveProcessOnDemand);
     const productPaths = resolveProductPaths();
     // Rationale: the manager reads the engine's settings port lazily, after the session exists.
     let backend;
@@ -46,12 +47,14 @@ export async function composeOwnedUi(options = {}) {
     const bareSettings = bare ? settings : null;
     // Invariant: process-wide engine state has one owner. The host installs the HTTP dispatcher, applies
     // the theme singletons, and announces startup notices once; every session is created through it.
-    const host = await (options.createEngineHost ?? createPiEngineHost)(engineHostOptions(options, productMode, bareSettings));
+    const host = await (options.createEngineHost ?? createPiEngineHost)(engineHostOptions(options, productMode, bareSettings, productPaths.runtimeDir));
     const sessionForkPrompt = options.sessionForkPrompt;
     try {
         backend = await host.create({
             cwd,
             ...(bare ? { repositoryContextReader: sessionRuntimes.readerFor(undefined) } : {}),
+            ...(bare && process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] !== undefined
+                ? { worktreeCwdReader: sessionRuntimes.toolReaderFor(undefined) } : {}),
             ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
             ...(options.sessionSelection === undefined ? {} : { sessionSelection: options.sessionSelection }),
             ...(sessionForkPrompt === undefined ? {} : { sessionForkPrompt }),
@@ -127,7 +130,7 @@ export async function composeOwnedUi(options = {}) {
     let presenter;
     try {
         const presenterOptions = {
-            presenters: createPiSessionPresenters(backend),
+            presenters: createPiSessionPresenters(backend, spinnerPresenterOptions(bareSettings)),
             engine: {
                 backend,
                 cwd: backend.identity.cwd,
@@ -201,6 +204,12 @@ export async function composeOwnedUi(options = {}) {
     };
     return { application, settings };
 }
+function spinnerPresenterOptions(settings) {
+    return settings === null ? {} : { spinner: {
+            snapshot: () => settings.value("spinnerStyle"),
+            onChange: (listener) => settings.onChange(() => listener()),
+        } };
+}
 /** The settings-driven ports only bare A1 receives: viewport, background, quit outro, suggestions, image limit, and skills. */
 function bareShellPorts(settings, generator, diagnostics) {
     const viewportSettings = {
@@ -235,10 +244,13 @@ function bareShellPorts(settings, generator, diagnostics) {
         },
     };
 }
-function engineHostOptions(options, productMode, settings) {
+function engineHostOptions(options, productMode, settings, runtimeDir) {
     const bare = productMode === "bare";
     return {
         productMode,
+        deliveryIncident: failure => {
+            void import("../foundation/terminal-cleanup/index.js").then(module => module.writeFatalDiagnostic(`${runtimeDir}/crashes`, "delivery", Object.assign(new Error(), { deliveryFailure: failure }), options.packageVersion)).catch(() => undefined);
+        },
         availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
         ...(bare ? { workflowHost: { reserveExport: async (id, format) => (await import("../foundation/lifecycle/user-exports.js")).reserveUserExport(id, format) } } : {}),
         announceStartupChangelog: !bare,

package/dist/composition/session-naming.js

@@ -6,7 +6,7 @@ export function bindAutomaticSessionNaming(backend, settings, bare) {
     const naming = new SessionNamingController({
         backend, naming: backend.naming,
         enabled: () => settings?.value("sessionAutoName") ?? true,
-        format: () => settings?.value("sessionNameFormat") ?? "kebab",
+        format: () => settings?.value("sessionNameFormat") ?? "sentence",
         withContext: async (consume, signal) => {
             const sessionId = backend.identity.currentHistorySessionId();
             const sessionFile = backend.identity.currentSessionFile();

package/dist/composition/session-runtime-registry.d.ts

@@ -16,6 +16,8 @@ export declare class SessionRuntimeRegistry {
         branch: string;
         revision: string;
     } | null>;
+    /** Strict tool cwd lookup: transient startup failure never redirects a write to primary. */
+    toolReaderFor(agentId: string | undefined): (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>;
     /** Drain publication before releasing claims; never republish after disposal. */
     dispose(): Promise<void>;
 }

package/dist/composition/session-runtime-registry.js

@@ -2,6 +2,7 @@
 export class SessionRuntimeRegistry {
     #options;
     #identities = new Map();
+    #activated = new Map();
     #abort = new AbortController();
     #owner = null;
     #timer = null;
@@ -15,7 +16,9 @@ export class SessionRuntimeRegistry {
             const { runtimeId, inspectProcess } = this.#options;
             if (this.#disposed || runtimeId === undefined || inspectProcess === undefined)
                 return null;
-            const identity = { sessionId, sessionFile };
+            const previous = this.#identities.get(agentId);
+            const identity = previous?.sessionId === sessionId && previous.sessionFile === sessionFile
+                ? previous : { sessionId, sessionFile };
             this.#identities.set(agentId, identity);
             // Invariant: initial activation or inspection failure must not disable retries.
             this.#arm();
@@ -23,25 +26,62 @@ export class SessionRuntimeRegistry {
                 const owner = await this.#ownerIdentity();
                 if (owner === null || !this.#current(agentId, identity))
                     return null;
-                const { activateSessionRepositoryContext, withSessionRepositoryObservation } = await import("../foundation/lifecycle/session-repository-context.js");
+                const { activateSessionRepositoryContext, readActiveSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
                 if (!this.#current(agentId, identity))
                     return null;
                 const options = {
+                    runtimeId,
                     signal: AbortSignal.any([signal, this.#abort.signal]),
                     inspectProcess,
                     ...(agentId === undefined ? {} : { agentId }),
                 };
-                const selected = await activateSessionRepositoryContext(identity, runtimeId, owner, options);
-                if (selected === null)
-                    return null;
-                return await withSessionRepositoryObservation(identity, context => {
+                if (this.#activated.get(agentId) !== identity) {
+                    await activateSessionRepositoryContext(identity, runtimeId, owner, options);
+                    if (!this.#current(agentId, identity))
+                        return null;
+                    this.#activated.set(agentId, identity);
+                }
+                try {
+                    const context = await readActiveSessionRepositoryContext(identity, options);
+                    if (context === null)
+                        return null;
                     if (context.branch === null)
                         throw new Error("associated branch unavailable");
                     return { cwd: context.cwd, branch: context.branch, revision: context.revision };
-                }, options);
+                }
+                catch (error) {
+                    const code = error instanceof Error && "code" in error ? error.code : null;
+                    if ((code === "session-runtime-unavailable" || code === "worktree-context-changed") && this.#current(agentId, identity)) {
+                        this.#activated.delete(agentId);
+                    }
+                    throw error;
+                }
             });
         };
     }
+    /** Strict tool cwd lookup: transient startup failure never redirects a write to primary. */
+    toolReaderFor(agentId) {
+        const read = this.readerFor(agentId);
+        return async (sessionId, sessionFile, signal) => {
+            const { retrySessionCoordination } = await import("../foundation/lifecycle/session-context-retry.js");
+            return await retrySessionCoordination(async () => {
+                signal.throwIfAborted();
+                if (this.#disposed || this.#options.runtimeId === undefined)
+                    throw new Error("worktree runtime is not active");
+                const context = await read(sessionId, sessionFile, signal);
+                if (this.#disposed)
+                    throw new Error("worktree runtime is not active");
+                const active = this.#activated.get(agentId);
+                if (active?.sessionId !== sessionId || active.sessionFile !== sessionFile) {
+                    throw Object.assign(new Error("worktree runtime registration is still recovering"), { code: "session-runtime-unavailable" });
+                }
+                if (context !== null)
+                    return context.cwd;
+                const { readSessionStartupRoot } = await import("../foundation/lifecycle/session-repository-context.js");
+                return await readSessionStartupRoot({ sessionId, sessionFile });
+            }, 8_000, signal);
+        };
+    }
     /** Drain publication before releasing claims; never republish after disposal. */
     async dispose() {
         this.#disposed = true;
@@ -82,7 +122,7 @@ export class SessionRuntimeRegistry {
     #arm() {
         if (this.#timer !== null)
             return;
-        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? 30_000);
+        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? 1_000);
         this.#timer.unref();
     }
     #queueRefresh() {
@@ -96,7 +136,7 @@ export class SessionRuntimeRegistry {
                 return;
             const { registerSessionRepositoryRuntime } = await import("../foundation/lifecycle/session-repository-context.js");
             for (const [agentId, identity] of this.#identities) {
-                if (!this.#current(agentId, identity))
+                if (!this.#current(agentId, identity) || this.#activated.get(agentId) === identity)
                     continue;
                 await registerSessionRepositoryRuntime(identity, runtimeId, owner, {
                     inspectProcess,

package/dist/composition/settings-route-host.js

@@ -92,6 +92,7 @@ async function loadReferenceSurface(settings, route, title, document, options) {
         id,
         title,
         document: content,
+        ...(route === "session" ? { presentation: "dialog" } : {}),
         scrollSettings: () => ({
             scrollbarAppearance: settings.value("scrollbarAppearance"),
             scrollbarStyle: settings.value("scrollbarStyle"),

package/dist/contracts/agent-engine/package-ports.d.ts

@@ -1,17 +1,6 @@
-/**
- * Extension packages are managed outside any session: the command that installs
- * one runs before the runtime exists, against a profile root chosen by the caller
- * rather than by whatever session happens to be open. So this port stands apart
- * from the session-scoped service ports and names only what a package operation
- * needs — a root, a source, and an outcome a caller can render without knowing
- * which engine performed it.
- */
+/** Non-interactive package operations use a caller-chosen profile root before any session exists. */
 export type AgentPackageOperation = "install" | "remove" | "update" | "refresh-models" | "list";
-/**
- * Why an operation ended, kept separate from the prose so callers can branch on
- * it. `not-found` is the one failure an engine can state structurally — the source
- * is not configured in this profile — rather than only in a message.
- */
+/** Status is separate from prose; not-found means the source is unconfigured. */
 export type AgentPackageStatus = "completed" | "not-found" | "failed";
 export interface AgentPackageDescriptor {
     readonly source: string;
@@ -25,10 +14,17 @@ export interface AgentPackageOutcome {
     readonly source: string | null;
     readonly packages: readonly AgentPackageDescriptor[];
     readonly detail: string | null;
+    /** Update facts distinguish a checked result from skipped or warned work. */
+    readonly updateSummary?: {
+        readonly offline: boolean;
+        readonly warningCount: number;
+        readonly changes: readonly string[];
+    };
 }
 export interface AgentPackageProgress {
     readonly operation: AgentPackageOperation;
     readonly message: string;
+    readonly severity?: "warning";
 }
 export interface AgentPackagesPort {
     readonly capabilities: {
@@ -57,4 +53,4 @@ export interface AgentPackagesPortInput {
     readonly onDiagnostic?: (diagnostic: AgentPackageDiagnostic) => void;
 }
 export declare function assertAgentPackagesPort(port: AgentPackagesPort): void;
-export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[]): AgentPackageOutcome;
+export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[], updateSummary?: AgentPackageOutcome["updateSummary"]): AgentPackageOutcome;

package/dist/contracts/agent-engine/package-ports.js

@@ -1,11 +1,4 @@
-/**
- * Extension packages are managed outside any session: the command that installs
- * one runs before the runtime exists, against a profile root chosen by the caller
- * rather than by whatever session happens to be open. So this port stands apart
- * from the session-scoped service ports and names only what a package operation
- * needs — a root, a source, and an outcome a caller can render without knowing
- * which engine performed it.
- */
+/** Non-interactive package operations use a caller-chosen profile root before any session exists. */
 export function assertAgentPackagesPort(port) {
     if (typeof port?.capabilities !== "object" || port.capabilities === null)
         throw new TypeError("packages port capabilities are required");
@@ -20,12 +13,15 @@ export function assertAgentPackagesPort(port) {
             throw new TypeError(`packages capability ${capability} must be explicit`);
     }
 }
-export function agentPackageOutcome(operation, status, detail, source, packages = []) {
+export function agentPackageOutcome(operation, status, detail, source, packages = [], updateSummary) {
     return Object.freeze({
         operation,
         status,
         source: source ?? null,
         packages: Object.freeze([...packages]),
         detail: detail ?? null,
+        ...(updateSummary === undefined ? {} : {
+            updateSummary: Object.freeze({ ...updateSummary, changes: Object.freeze([...updateSummary.changes]) }),
+        }),
     });
 }

package/dist/contracts/owned-ui/session-workflows.d.ts

@@ -47,6 +47,8 @@ export interface OwnedUiWorkflowRequest {
     readonly confirmed?: boolean;
     /** Recovery cwd selected after an import/resume source cwd is unavailable. */
     readonly cwdOverride?: string;
+    /** Explicit missing-folder recovery; cancellation never changes the active session. */
+    readonly cwdRecoveryChoice?: "continue" | "fork" | "cancel";
     /** Cancellation for an owned operation surface such as `/share`. */
     readonly signal?: AbortSignal;
     /** Progress label for that operation surface, e.g. when `/share` picks its upload destination. */
@@ -126,6 +128,10 @@ export interface OwnedUiWorkflowResult {
     readonly messages?: readonly OwnedUiWorkflowMessage[];
     readonly detail?: string;
     readonly selectorTitle?: string;
+    /** A missing-folder selector, distinct from ordinary workflow selection. */
+    readonly cwdRecovery?: {
+        readonly fallbackCwd: string;
+    };
     readonly options?: readonly OwnedUiWorkflowOption[];
     readonly presentation?: OwnedUiWorkflowPresentation;
 }

package/dist/contracts/owned-ui/shell-components.d.ts

@@ -14,9 +14,19 @@ export interface OwnedUiShellKeybindingsHost {
     reload(): void;
 }
 export interface OwnedUiShellComponentPort {
+    readonly ready?: Promise<void>;
     render(width: number): readonly string[];
+    /** Bounds scrollable replacement inputs within the dock. */
+    renderInDock?(width: number, maxHeight: number): readonly string[];
     invalidate(): void;
     handleInput?(data: string): void;
+    /** Pointer input in one-based component-local coordinates, when supported. */
+    handleLocalMouse?(event: {
+        readonly kind: "press" | "release" | "motion" | "wheel-up" | "wheel-down";
+        readonly button: number;
+        readonly column: number;
+        readonly row: number;
+    }): void;
     setFocused?(focused: boolean): void;
     dispose?(): void;
 }

package/dist/contracts/presentation/component.d.ts

@@ -2,6 +2,13 @@ export interface PresentationComponentPort {
     render(width: number): readonly string[];
     invalidate(): void;
     handleInput?(data: string): void;
+    /** Optional pointer input in one-based component-local coordinates. */
+    handleLocalMouse?(event: {
+        readonly kind: "press" | "release" | "motion" | "wheel-up" | "wheel-down";
+        readonly button: number;
+        readonly column: number;
+        readonly row: number;
+    }): void;
     setFocused?(focused: boolean): void;
     dispose?(): void;
 }

package/dist/contracts/presentation/index.d.ts

@@ -1,5 +1,6 @@
 import type { PresentationComponentPort } from "./component.js";
 export type { PresentationComponentPort, PresentationPointerSurface } from "./component.js";
+export type { ProgressSpinnerSource, ProgressSpinnerStyle } from "./progress-spinner.js";
 export { samePointerSurfaces } from "./component.js";
 export type { CanvasBackgroundStyle, ShellPresentationPorts, ThemeSource, UiTheme, UiThemeBackground, UiThemeToken } from "./theme.js";
 export type { TerminalComponentPort, TerminalDamageDecision, TerminalDamageDecisionReason, TerminalDamageFrameDescriptor, TerminalDamageFrameSafety, TerminalDamageOptions, TerminalDamagePort, TerminalHyperlinkInspection, TerminalInputCoordinationDecision, TerminalInputCoordinationScheduler, TerminalInputDiagnosticsEvent, TerminalInputDiagnosticsPhase, TerminalInputListener, TerminalInputListenerResult, TerminalInputSurfaceKind, TerminalLayoutEntry, TerminalLayoutNode, TerminalOverlayAnchor, TerminalOverlayHandle, TerminalOverlayMargin, TerminalOverlayOptions, TerminalOverlayUnfocusOptions, TerminalPointerSurface, TerminalPort, TerminalPreInputListener, TerminalProgramStatus, TerminalRuntimeFactory, TerminalRuntimeOptions, TerminalRuntimePort, TerminalRuntimeState, TerminalSizeValue, TerminalStopOptions, TerminalViewport, TerminalWheelScrollLines, } from "./terminal.js";
@@ -22,6 +23,8 @@ export declare const DIALOG_BACK_SHORTCUT_HINT: Readonly<{
 }>;
 /** Global inset inherited by every semantic row inside an A1-owned dialog frame. */
 export declare const DIALOG_CONTENT_PADDING_X = 1;
+/** Wraps choice navigation, leaving empty lists at a safe index. */
+export declare function wrapChoiceIndex(index: number, delta: number, count: number): number;
 export interface DialogFrameGeometry {
     readonly frameWidth: number;
     readonly contentPaddingX: number;

package/dist/contracts/presentation/index.js

@@ -6,6 +6,10 @@ export const DIALOG_CLOSE_SHORTCUT_HINT = Object.freeze({ key: "esc", action: "c
 export const DIALOG_BACK_SHORTCUT_HINT = Object.freeze({ key: "esc", action: "back" });
 /** Global inset inherited by every semantic row inside an A1-owned dialog frame. */
 export const DIALOG_CONTENT_PADDING_X = 1;
+/** Wraps choice navigation, leaving empty lists at a safe index. */
+export function wrapChoiceIndex(index, delta, count) {
+    return count > 0 ? ((index + delta) % count + count) % count : 0;
+}
 /** Shared full-width-rule/content-width geometry for string and component dialog renderers. */
 export function dialogFrameGeometry(width) {
     const frameWidth = Math.max(0, width);

package/dist/contracts/presentation/progress-palette.generated.d.ts

@@ -1,6 +1,6 @@
 /**
  * Generated by scripts/pi/sync-progress-palette.ts from A1's named accent projection
- * over pinned Pi 1.5.1 (MIT), commit dd30101cfc5b0609411dd80b6f93adbc14db14cf. Do not edit directly.
+ * over pinned Pi 1.5.2 (MIT), commit b4afdddf44e059c67ccf5097e5317d913521b470. Do not edit directly.
  */
 export declare const SHARED_PROGRESS_PALETTE: Readonly<{
     blue: {
@@ -8,20 +8,24 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
         light: {
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
     };
@@ -30,20 +34,24 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
         light: {
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
     };
@@ -52,20 +60,24 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
         light: {
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
     };
@@ -74,20 +86,24 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
         light: {
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
     };
@@ -96,20 +112,24 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
         light: {
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
     };
@@ -118,20 +138,24 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
         light: {
             truecolor: {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
             "256color": {
                 accent: string;
                 border: string;
+                selectedBg: string;
             };
         };
     };