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

package/README.md

@@ -45,6 +45,18 @@ a1 pi                                   # vanilla Pi oracle: ~/.pi/agent
 Unsupported commands exit quietly without launching anything. The removed
 `update:<preview>` forms are not aliases; use `update --develop`.
 
+## Agent input
+
+The agent prompt and Settings search share one input component: neutral white
+bars and an undimmed arrow matching submitted prompts. Thinking-level color is
+shown on the level name in the status bar, not on the input bars.
+
+In bare A1, **Ctrl+L cycles the thinking level**. **Shift+Tab is unassigned** and
+performs no agent-input action, including while a suggestion is visible. Model
+selection has **no default shortcut**; use `/model`. Explicit keybinding overrides
+remain configurable, and `/hotkeys` shows the resolved bindings. The `a1 pi`
+comparison profile keeps its original presentation and shortcuts.
+
 ## Prompt suggestions
 
 Bare A1's `/settings` → Agent → Prompt suggestions controls faint next-prompt
@@ -53,6 +65,12 @@ with the selected model for eligible turns. Disabling it takes effect immediatel
 Tab accepts a suggestion as editable text; Enter submits it afterward. The setting
 remains stored in A1's profile, and `a1 pi` is unchanged.
 
+Suggestions use the selected model's lowest supported reasoning effort without
+changing your main thinking level. Clear next actions such as `archive it` are
+preferred when consistent with your intent; genuinely unclear cases can remain
+empty. [Private diagnostic capture](docs/architecture/prompt-suggestions.md)
+explains how to distinguish skipped, empty, rejected, and timed-out suggestions.
+
 ## Prompt history
 
 Bare A1 recalls recent unique prompts across sessions with Up/Down. History is
@@ -160,18 +178,29 @@ a1 update --develop 0.1.8-dev.107       # install that exact full preview versio
 ### Stable
 
 ```sh
-npm run release -- patch     # 0.1.1 -> 0.1.2
-npm run release -- minor     # 0.1.1 -> 0.2.0
-npm run release -- major     # 0.1.1 -> 1.0.0
-npm run release -- 0.4.0     # an exact version
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # an exact stable version
 ```
 
-The command lands the version on `develop` through a self-merging pull request,
-dispatches publication for that exact commit, and waits for success. CI validates
-the packed release on Windows, Linux, and macOS, publishes to npm `latest` with
-provenance, then writes the `v<version>` tag and the GitHub Release. `master`
-fast-forwards to the released commit, so it always points at what npm `latest`
-serves. A failed release leaves nothing behind: no tag, no GitHub Release, no
-moved branch.
+Run from the repository root on a clean `develop` matching `origin/develop`.
+A target is required; bare `npm run release` displays usage and releases nothing.
+`patch` promotes the current prerelease rather than skipping its stable version.
+
+The command prepares a version-only PR in an isolated detached worktree, prints
+its URL, and waits for you to validate and **merge it manually**. Neither this PR
+nor the next-development PR is auto-merged, and green CI alone does not advance
+the release. After the stable PR merges, the command dispatches publication for
+that exact authoritative commit and waits for success. CI validates the packed
+release on Windows, Linux, and macOS, publishes to npm `latest` with provenance,
+then writes the `v<version>` tag and GitHub Release and fast-forwards `master`.
+
+Only after confirmed publication of `0.1.8` does the command prepare the separate
+`0.1.9-dev` PR. It reports development reopened only after you manually merge that
+PR too. Work added to your checkout during either wait is preserved, not reset.
+If publication fails or is uncertain, no reopening PR is prepared. If publication
+succeeded but reopening failed, inspect the reported phase and PR; do not republish
+the immutable stable version.
 
 `docs/ci-release-runbook.md` has the full picture.

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

@@ -21,6 +21,8 @@ export interface OwnedUiCompositionOptions {
      */
     readonly ownedSurfaces?: "on" | "off";
     readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
+    /** Explicit local diagnostic destination; ignored by comparison/settings-free compositions. */
+    readonly suggestionDiagnosticsPath?: string;
 }
 export interface OwnedUiComposition {
     readonly application: OwnedUiApplicationPort;

package/dist/composition/owned-ui.js

@@ -1,4 +1,6 @@
-import { PromptHistoryService } from "../features/prompt-history/index.js";
+import { SuggestionDiagnosticCapture } from "../features/prompt-suggestions/index.js";
+import { PRODUCT_IDENTITY } from "../product-identity.js";
+import { PromptHistoryService, PromptImageSidecar, resolvePromptHistoryPath } from "../features/prompt-history/index.js";
 import { resolvePromptHistoryDataDir } from "../features/launch/index.js";
 import { resolveProductPaths } from "../foundation/lifecycle/index.js";
 import { applyConfiguredPiTheme, getAvailablePiThemes, loadHistoryEditor } from "../integrations/pi/components/index.js";
@@ -39,19 +41,27 @@ export async function composeOwnedUi(options = {}) {
         snapshot: () => viewportSettingsSnapshot(settings),
         onChange: listener => settings.onChange(() => listener(viewportSettingsSnapshot(settings))),
     };
+    const diagnosticDestination = options.suggestionDiagnosticsPath ?? process.env[PRODUCT_IDENTITY.environment.suggestionDiagnostics];
+    const suggestionDiagnostics = settings !== null && ownedSurfaces && diagnosticDestination?.trim()
+        ? new SuggestionDiagnosticCapture({ enabled: true, destination: diagnosticDestination }) : null;
     const promptSuggestions = settings === null || !ownedSurfaces ? null : {
+        ...(suggestionDiagnostics === null ? {} : { diagnostics: suggestionDiagnostics }),
         generator: adapter,
         enabled: () => settings.value("promptSuggestions") !== false,
         onChange: (listener) => settings.onChange(() => listener(settings.value("promptSuggestions") !== false)),
     };
     const historyLimit = settings?.value("promptHistoryMaxItems");
-    const promptHistory = settings === null || !ownedSurfaces || settings.value("promptHistoryEnabled") === false ? null : {
+    const historyProfileLocation = settings === null || !ownedSurfaces || settings.value("promptHistoryEnabled") === false
+        ? null
+        : resolvePromptHistoryPath(resolvePromptHistoryDataDir(), adapter.agentDir);
+    const promptHistory = historyProfileLocation === null ? null : {
         limit: typeof historyLimit === "number" ? historyLimit : 100,
         store: new PromptHistoryService({
             dataDir: resolvePromptHistoryDataDir(),
             profileRoot: adapter.agentDir,
             limit: typeof historyLimit === "number" ? historyLimit : 100,
         }),
+        imageSidecar: new PromptImageSidecar(historyProfileLocation.imagesDir),
     };
     const shell = new OwnedUiSessionShell({
         backend: adapter,
@@ -68,7 +78,14 @@ export async function composeOwnedUi(options = {}) {
         start: () => shell.start(),
         flush: () => adapter.flushEvents(),
         waitUntilStopped: () => shell.waitUntilStopped(),
-        dispose: () => shell.dispose(),
+        dispose: async () => {
+            try {
+                await shell.dispose();
+            }
+            finally {
+                suggestionDiagnostics?.dispose();
+            }
+        },
     };
     return { application, settings };
 }

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

@@ -1,6 +1,8 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
+export * from "./transcript-lifecycle.js";
 export * from "./image-attachments.js";
 export * from "./prompt-suggestions.js";
+export * from "./suggestion-diagnostics.js";
 export * from "./prompt-history.js";
 export * from "./validation.js";

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

@@ -1,6 +1,8 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
+export * from "./transcript-lifecycle.js";
 export * from "./image-attachments.js";
 export * from "./prompt-suggestions.js";
+export * from "./suggestion-diagnostics.js";
 export * from "./prompt-history.js";
 export * from "./validation.js";

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

@@ -22,10 +22,16 @@ export interface OwnedUiPromptSuggestionRequest {
     readonly identity: OwnedUiPromptSuggestionIdentity;
     readonly signal: AbortSignal;
 }
-export interface OwnedUiPromptSuggestionResult {
+export type OwnedUiPromptSuggestionReasoning = "ordinary" | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "unavailable";
+export type OwnedUiPromptSuggestionResult = {
     readonly identity: OwnedUiPromptSuggestionIdentity;
-    readonly text: string | null;
-}
+} & ({
+    readonly outcome: "candidate";
+    readonly text: string;
+} | {
+    readonly outcome: "empty" | "rejected" | "provider-failure" | "unavailable" | "cancelled";
+    readonly text: null;
+});
 export type OwnedUiPromptSuggestionState = {
     readonly status: "idle";
 } | {
@@ -42,6 +48,8 @@ export type OwnedUiPromptSuggestionState = {
     readonly text: string;
 };
 export interface OwnedUiPromptSuggestionGeneratorPort {
+    /** Request-local policy; never changes the primary session's thinking setting. */
+    suggestionReasoningPolicy?(): OwnedUiPromptSuggestionReasoning;
     generate(request: OwnedUiPromptSuggestionRequest): Promise<OwnedUiPromptSuggestionResult>;
 }
 export type OwnedUiThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
@@ -130,6 +138,29 @@ export interface OwnedUiTranscriptImageReference {
     readonly byteLength: number;
     readonly source: "user" | "tool-result";
 }
+/** Argument generation and execution have distinct completion boundaries on one invocation. */
+export interface OwnedUiToolState {
+    readonly argsComplete: boolean;
+    readonly execution: "pending" | "running" | "succeeded" | "failed" | "aborted";
+}
+/** Vendor-neutral rendering metadata; text and image bytes are not duplicated here. */
+export type OwnedUiToolResultPart = {
+    readonly type: "text";
+    readonly start: number;
+    readonly end: number;
+} | {
+    readonly type: "image";
+    readonly imageIndex: number;
+};
+export interface OwnedUiToolRendering {
+    readonly arguments: unknown;
+    readonly result?: {
+        readonly content: readonly OwnedUiToolResultPart[];
+        readonly details?: unknown;
+    };
+    /** Visible bounded fallback, never a substitute operation outcome. */
+    readonly unavailable?: string;
+}
 export interface OwnedUiTranscriptBlock {
     readonly id: OwnedUiEntityId;
     readonly kind: OwnedUiTranscriptBlockKind;
@@ -138,6 +169,10 @@ export interface OwnedUiTranscriptBlock {
     readonly title: string | null;
     readonly text: string;
     readonly payload: unknown;
+    /** Tool-call message completion alone must not settle execution. */
+    readonly toolState?: OwnedUiToolState;
+    /** Authoritative renderer inputs, separate from diagnostic payloads. */
+    readonly toolRendering?: OwnedUiToolRendering;
     /** Bounded opaque references; image bytes remain in the session-scoped engine asset store. */
     readonly imageReferences?: readonly OwnedUiTranscriptImageReference[];
 }

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

@@ -31,6 +31,24 @@ export interface PromptHistoryPort {
     onFailure(listener: (code: PromptHistoryFailure) => void): () => void;
     close(): Promise<void>;
 }
+export interface PromptHistoryImageSidecarAttachment {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export interface PromptHistoryImageSidecarRecord {
+    readonly tag: string;
+    readonly data: string;
+    readonly mimeType: string;
+    readonly savedAt: string;
+}
+/** Per-profile durable payload store for image chip attachments referenced by history text.
+ * Writes MUST be idempotent and MUST NOT block a history row commit on failure; reads MUST
+ * treat every failure as "attachment unavailable" so rehydration silently strips the chip. */
+export interface PromptHistoryImageSidecarPort {
+    write(id: string, record: PromptHistoryImageSidecarRecord): void;
+    readAttachment(id: string): PromptHistoryImageSidecarAttachment | null;
+}
 export declare const PROMPT_HISTORY_MAX_ENTRY_BYTES: number;
 export declare const PROMPT_HISTORY_MAX_TEXT_BYTES: number;
 export declare const PROMPT_HISTORY_MAX_PENDING = 32;

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

@@ -1,3 +1,3 @@
-export declare const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = "[NEXT USER INPUT]\nPredict the one short response the user is most likely to type next.\nUse the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.\nReturn nothing when the next input is unclear, the previous response failed, or the user should assess or correct the result.\nDo not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.\nReturn only 2-12 words, except a natural one-word command or answer is allowed.";
+export declare const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = "[NEXT USER INPUT]\nPredict the one short response the user is most likely to type next.\nUse the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.\nPrefer a clearly offered next action consistent with the user's recent intent. An optional alternative alone does not make that continuation unclear.\nFor example, after the user accepted merged work, \"Say archive it\" with an optional \"let me test\" alternative favors: archive it.\nDo not favor archival if the user required testing first and that testing remains outstanding. Do not invent approval or select the first of equally unresolved choices.\nReturn nothing when the next input is genuinely unclear, the previous response failed, or required assessment or correction remains outstanding.\nDo not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.\nReturn only 2-12 words, except a natural one-word command or answer is allowed.";
 /** Converts untrusted model output into one inert, bounded user-voice candidate. */
 export declare function normalizePromptSuggestionCandidate(candidate: string | null | undefined): string | null;

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

@@ -1,7 +1,10 @@
 export const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = `[NEXT USER INPUT]
 Predict the one short response the user is most likely to type next.
 Use the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.
-Return nothing when the next input is unclear, the previous response failed, or the user should assess or correct the result.
+Prefer a clearly offered next action consistent with the user's recent intent. An optional alternative alone does not make that continuation unclear.
+For example, after the user accepted merged work, "Say archive it" with an optional "let me test" alternative favors: archive it.
+Do not favor archival if the user required testing first and that testing remains outstanding. Do not invent approval or select the first of equally unresolved choices.
+Return nothing when the next input is genuinely unclear, the previous response failed, or required assessment or correction remains outstanding.
 Do not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.
 Return only 2-12 words, except a natural one-word command or answer is allowed.`;
 const ALLOWED_SINGLE_WORDS = new Set([

package/dist/contracts/owned-ui/suggestion-diagnostics.d.ts

@@ -0,0 +1,22 @@
+import type { OwnedUiPromptSuggestionReasoning } from "./model.js";
+export declare const SUGGESTION_DECISION_REASONS: readonly ["disabled", "disposed", "early-conversation", "no-model", "failed-response", "incomplete-response", "tool-continuation", "replacement-input", "modal", "draft", "not-ready", "not-focused", "autocomplete", "prompt-mode", "presentation-unavailable", "ineligible", "stale-identity"];
+export type SuggestionDecisionReason = typeof SUGGESTION_DECISION_REASONS[number];
+export type SuggestionDecision = SuggestionDecisionReason | null;
+export declare const SUGGESTION_DIAGNOSTIC_EVENTS: readonly ["skipped", "started", "displayed", "empty", "rejected", "provider-failure", "unavailable", "timeout", "cancelled", "stale-result", "presentation-blocked", "late-result-discarded"];
+export type SuggestionDiagnosticEvent = typeof SUGGESTION_DIAGNOSTIC_EVENTS[number];
+/** Metadata only: never carry a session path, prompt, candidate, or raw error. */
+export interface SuggestionDiagnosticRecord {
+    readonly event: SuggestionDiagnosticEvent;
+    readonly reason?: SuggestionDecisionReason;
+    readonly session: number;
+    readonly run: number;
+    readonly response: number;
+    readonly request: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly reasoning: OwnedUiPromptSuggestionReasoning;
+    readonly elapsedMs: number;
+}
+export interface SuggestionDiagnosticObserver {
+    record(record: SuggestionDiagnosticRecord): void;
+}

package/dist/contracts/owned-ui/suggestion-diagnostics.js

@@ -0,0 +1,9 @@
+export const SUGGESTION_DECISION_REASONS = [
+    "disabled", "disposed", "early-conversation", "no-model", "failed-response", "incomplete-response",
+    "tool-continuation", "replacement-input", "modal", "draft", "not-ready", "not-focused",
+    "autocomplete", "prompt-mode", "presentation-unavailable", "ineligible", "stale-identity",
+];
+export const SUGGESTION_DIAGNOSTIC_EVENTS = [
+    "skipped", "started", "displayed", "empty", "rejected", "provider-failure", "unavailable",
+    "timeout", "cancelled", "stale-result", "presentation-blocked", "late-result-discarded",
+];

package/dist/contracts/owned-ui/transcript-lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { OwnedUiToolState, OwnedUiTranscriptBlock } from "./model.js";
+/** Compatibility for existing owned components/fixtures without explicit execution state. */
+export declare function transcriptToolState(block: OwnedUiTranscriptBlock): OwnedUiToolState | undefined;
+/** Within a session generation, reject obsolete phases as well as obsolete revisions. */
+export declare function acceptsTranscriptUpdate(current: OwnedUiTranscriptBlock, next: OwnedUiTranscriptBlock): boolean;

package/dist/contracts/owned-ui/transcript-lifecycle.js

@@ -0,0 +1,33 @@
+/** Compatibility for existing owned components/fixtures without explicit execution state. */
+export function transcriptToolState(block) {
+    if (block.kind !== "tool-call" && block.kind !== "tool-result")
+        return undefined;
+    if (block.toolState !== undefined)
+        return block.toolState;
+    const payload = typeof block.payload === "object" && block.payload !== null ? block.payload : {};
+    const isError = "isError" in payload && payload.isError === true;
+    const partial = "partialResult" in payload && payload.partialResult === true;
+    return {
+        argsComplete: block.status === "finalized" || "argsComplete" in payload && payload.argsComplete === true,
+        execution: block.kind === "tool-result"
+            ? block.status === "live" ? "running" : isError ? "failed" : "succeeded"
+            : partial ? "running" : "pending",
+    };
+}
+/** Within a session generation, reject obsolete phases as well as obsolete revisions. */
+export function acceptsTranscriptUpdate(current, next) {
+    if (current.id !== next.id || current.revision > next.revision)
+        return false;
+    const before = transcriptToolState(current);
+    const after = transcriptToolState(next);
+    if (before !== undefined && after !== undefined) {
+        const rank = (state) => state.execution === "pending" ? 0 : state.execution === "running" ? 1 : 2;
+        if (rank(after) < rank(before))
+            return false;
+        if (before.argsComplete && !after.argsComplete && rank(after) < 2)
+            return false;
+        // Compatibility: a legacy finalized call declaration only closed arguments. Actual result finality is a barrier.
+        return !(current.status === "finalized" && next.status === "live" && before.execution !== "pending");
+    }
+    return !(current.status === "finalized" && next.status === "live");
+}

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

@@ -14,6 +14,7 @@ const MAX_BADGES = 32;
 const MAX_STATUS_DIAGNOSTICS = 32;
 const MAX_ACTIVE_COMMANDS = 64;
 const IMAGE_REFERENCE_SOURCES = new Set(["user", "tool-result"]);
+const TOOL_EXECUTIONS = new Set(["pending", "running", "succeeded", "failed", "aborted"]);
 const BLOCK_KINDS = new Set([
     "user",
     "assistant",
@@ -185,7 +186,14 @@ export function assertOwnedUiPromptSuggestionRequest(request) {
 }
 export function assertOwnedUiPromptSuggestionResult(result) {
     assertOwnedUiPromptSuggestionIdentity(result.identity);
-    assertPromptSuggestionText(result.text, true);
+    if (result.outcome === "candidate") {
+        assertPromptSuggestionText(result.text, false);
+        if (!result.text.trim())
+            throw new TypeError("prompt-suggestion candidate is empty");
+    }
+    else if (!["empty", "rejected", "provider-failure", "unavailable", "cancelled"].includes(result.outcome) || result.text !== null) {
+        throw new TypeError("prompt-suggestion outcome is invalid");
+    }
 }
 export function assertOwnedUiPromptSuggestionState(state) {
     if (state.status === "idle")
@@ -270,7 +278,42 @@ export function assertOwnedUiTranscriptBlock(block) {
     assertNonNegativeInteger(block.revision, "owned-UI transcript block revision");
     assertOptionalText(block.title, "owned-UI transcript block title", MAX_LABEL_LENGTH);
     assertPossiblyEmptyText(block.text, "owned-UI transcript block text", MAX_TEXT_BYTES);
-    assertJsonValue(block.payload, "owned-UI transcript block payload", MAX_PAYLOAD_BYTES);
+    assertJsonValue(block.toolRendering === undefined ? block.payload : {
+        payload: block.payload, toolRendering: block.toolRendering,
+    }, "owned-UI transcript block payload", MAX_PAYLOAD_BYTES);
+    if (block.toolRendering !== undefined) {
+        if (block.kind !== "tool-call" && block.kind !== "tool-result")
+            throw new TypeError("owned-UI tool rendering requires a tool block");
+        assertJsonValue(block.toolRendering.arguments, "owned-UI tool arguments", MAX_PAYLOAD_BYTES);
+        if (block.toolRendering.unavailable !== undefined) {
+            assertBoundedText(block.toolRendering.unavailable, "owned-UI rendering fallback", MAX_MESSAGE_LENGTH);
+        }
+        if (block.toolRendering.result !== undefined) {
+            const result = block.toolRendering.result;
+            assertCollection(result.content, "owned-UI tool result parts", MAX_PAYLOAD_BYTES);
+            for (const part of result.content) {
+                if (part.type === "text") {
+                    assertIntegerInRange(part.start, 0, block.text.length, "owned-UI tool text start");
+                    assertIntegerInRange(part.end, part.start, block.text.length, "owned-UI tool text end");
+                }
+                else if (part.type === "image") {
+                    assertIntegerInRange(part.imageIndex, 0, (block.imageReferences?.length ?? 0) - 1, "owned-UI tool image index");
+                }
+                else
+                    throw new TypeError("owned-UI tool result part is invalid");
+            }
+        }
+    }
+    if (block.toolState !== undefined) {
+        if (block.kind !== "tool-call" && block.kind !== "tool-result")
+            throw new TypeError("owned-UI tool state requires a tool block");
+        if (typeof block.toolState.argsComplete !== "boolean")
+            throw new TypeError("owned-UI tool argument completion is invalid");
+        assertEnum(block.toolState.execution, TOOL_EXECUTIONS, "owned-UI tool execution state");
+        const settled = block.toolState.execution !== "pending" && block.toolState.execution !== "running";
+        if (settled !== (block.status === "finalized"))
+            throw new TypeError("owned-UI tool execution finality is inconsistent");
+    }
     if (block.imageReferences !== undefined) {
         assertCollection(block.imageReferences, "owned-UI transcript image references", 16);
         for (const reference of block.imageReferences) {

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

@@ -6,6 +6,14 @@ export interface PresentationComponentPort {
     setFocused?(focused: boolean): void;
     dispose?(): void;
 }
+/** A painted input surface in terminal coordinates (one-based, inclusive bounds). */
+export interface PresentationPointerSurface {
+    readonly component: PresentationComponentPort;
+    readonly columnStart: number;
+    readonly columnEnd: number;
+    readonly rowStart: number;
+    readonly rowEnd: number;
+}
 export interface PresentationEditorPort extends PresentationComponentPort {
     getText(): string;
     setText(text: string): void;

package/dist/features/owned-ui/settings-app.js

@@ -633,7 +633,7 @@ export class SettingsApp {
         const input = this.#filter;
         if (input === null)
             return [status];
-        return [...renderInputRow(input, width, { placeholder: SEARCH_PLACEHOLDER }).lines, status];
+        return [...renderInputRow(input, width, { placeholder: SEARCH_PLACEHOLDER, theme }).lines, status];
     }
 }
 /** The source's own wording when it has one, otherwise the id made readable. */

package/dist/features/prompt-history/image-sidecar.d.ts

@@ -0,0 +1,32 @@
+export interface PromptImageSidecarAttachment {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export interface PromptImageSidecarRecord {
+    readonly tag: string;
+    readonly data: string;
+    readonly mimeType: string;
+    readonly savedAt: string;
+}
+/** Extract every image chip identifier referenced by a recall text; identifiers are the hex bytes
+ * embedded in the tag by `PromptChipStore`. Ordering is left-to-right; duplicates are dropped. */
+export declare function collectImageChipIdentifiers(text: string): string[];
+/** Per-profile filesystem sidecar owning image chip payloads that survive a process restart.
+ * Writes are idempotent, reads are validated, and unlinks tolerate missing files. Callers must
+ * treat every failure as "the sidecar is unavailable"; that maps to the silent-strip contract. */
+export declare class PromptImageSidecar {
+    #private;
+    constructor(directory: string);
+    get directory(): string;
+    write(id: string, record: PromptImageSidecarRecord): void;
+    read(id: string): PromptImageSidecarRecord | null;
+    readAttachment(id: string): PromptImageSidecarAttachment | null;
+    /** Enumerate every sidecar identifier that currently has a file on disk. Ignores unrelated
+     * files silently; corrupt payloads are still listed so a caller sweep can reclaim them. */
+    list(): string[];
+    unlink(id: string): void;
+    /** Delete sidecars whose identifier is not present in `keep`. Used both by retention pruning
+     * of a specific row and by the store-open orphan sweep against every surviving row. */
+    sweep(keep: Iterable<string>): void;
+}

package/dist/features/prompt-history/image-sidecar.js

@@ -0,0 +1,130 @@
+import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, lstatSync } from "node:fs";
+import { posix, win32 } from "node:path";
+const IMAGE_TAG_PATTERN = /\[📷 screenshot-([a-f0-9]+)(?:-resized)?\]/gu;
+const IMAGE_FILENAME_PATTERN = /^([a-f0-9]+)\.json$/u;
+const MAX_SIDECAR_BYTES = 12 * 1024 * 1024;
+/** Extract every image chip identifier referenced by a recall text; identifiers are the hex bytes
+ * embedded in the tag by `PromptChipStore`. Ordering is left-to-right; duplicates are dropped. */
+export function collectImageChipIdentifiers(text) {
+    const seen = new Set();
+    IMAGE_TAG_PATTERN.lastIndex = 0;
+    for (;;) {
+        const match = IMAGE_TAG_PATTERN.exec(text);
+        if (match === null)
+            break;
+        seen.add(match[1]);
+    }
+    return [...seen];
+}
+/** Per-profile filesystem sidecar owning image chip payloads that survive a process restart.
+ * Writes are idempotent, reads are validated, and unlinks tolerate missing files. Callers must
+ * treat every failure as "the sidecar is unavailable"; that maps to the silent-strip contract. */
+export class PromptImageSidecar {
+    #directory;
+    constructor(directory) {
+        this.#directory = directory;
+    }
+    get directory() { return this.#directory; }
+    write(id, record) {
+        if (!isValidId(id))
+            return;
+        this.#ensureDirectory();
+        const target = this.#pathFor(id);
+        try {
+            // Concurrency: another process may have written the same id; a subsequent overwrite is
+            // idempotent because sidecar payloads are keyed to a chip tag whose id already collided.
+            const temporary = `${target}.tmp`;
+            writeFileSync(temporary, JSON.stringify(record), { encoding: "utf8", mode: 0o600, flag: "w" });
+            try {
+                if (process.platform !== "win32")
+                    chmodSync(temporary, 0o600);
+            }
+            catch { /* Compatibility: chmod is best-effort where the platform ignores it. */ }
+            renameSync(temporary, target);
+        }
+        catch {
+            // Security: sidecar write failures never propagate into shell diagnostics or history rows.
+        }
+    }
+    read(id) {
+        if (!isValidId(id))
+            return null;
+        try {
+            const target = this.#pathFor(id);
+            const status = lstatSync(target);
+            if (status.isSymbolicLink() || !status.isFile() || status.size > MAX_SIDECAR_BYTES)
+                return null;
+            const parsed = JSON.parse(readFileSync(target, "utf8"));
+            if (typeof parsed !== "object" || parsed === null)
+                return null;
+            const record = parsed;
+            if (typeof record.tag !== "string" || typeof record.data !== "string"
+                || typeof record.mimeType !== "string" || typeof record.savedAt !== "string"
+                || record.data.length === 0 || record.tag.length === 0 || record.mimeType.length === 0)
+                return null;
+            return { tag: record.tag, data: record.data, mimeType: record.mimeType, savedAt: record.savedAt };
+        }
+        catch {
+            return null;
+        }
+    }
+    readAttachment(id) {
+        const record = this.read(id);
+        if (record === null)
+            return null;
+        return Object.freeze({ type: "image", data: record.data, mimeType: record.mimeType });
+    }
+    /** Enumerate every sidecar identifier that currently has a file on disk. Ignores unrelated
+     * files silently; corrupt payloads are still listed so a caller sweep can reclaim them. */
+    list() {
+        try {
+            const entries = readdirSync(this.#directory, { withFileTypes: true });
+            const ids = [];
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                const match = IMAGE_FILENAME_PATTERN.exec(entry.name);
+                if (match !== null)
+                    ids.push(match[1]);
+            }
+            return ids;
+        }
+        catch {
+            return [];
+        }
+    }
+    unlink(id) {
+        if (!isValidId(id))
+            return;
+        try {
+            unlinkSync(this.#pathFor(id));
+        }
+        catch { /* Compatibility: ENOENT / EBUSY is indistinguishable from an already-reaped sidecar. */ }
+    }
+    /** Delete sidecars whose identifier is not present in `keep`. Used both by retention pruning
+     * of a specific row and by the store-open orphan sweep against every surviving row. */
+    sweep(keep) {
+        const survivors = new Set(keep);
+        for (const id of this.list()) {
+            if (!survivors.has(id))
+                this.unlink(id);
+        }
+    }
+    #ensureDirectory() {
+        try {
+            mkdirSync(this.#directory, { recursive: true, mode: 0o700 });
+            if (process.platform !== "win32")
+                chmodSync(this.#directory, 0o700);
+        }
+        catch {
+            // Compatibility: the directory may already exist with a different mode we cannot change.
+        }
+    }
+    #pathFor(id) {
+        const paths = process.platform === "win32" ? win32 : posix;
+        return paths.join(this.#directory, `${id}.json`);
+    }
+}
+function isValidId(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 64 && /^[a-f0-9]+$/u.test(value);
+}

package/dist/features/prompt-history/index.d.ts

@@ -1,2 +1,4 @@
 export { PromptHistoryService } from "./service.js";
 export { resolvePromptHistoryPath } from "./paths.js";
+export { PromptImageSidecar, collectImageChipIdentifiers } from "./image-sidecar.js";
+export type { PromptImageSidecarRecord, PromptImageSidecarAttachment } from "./image-sidecar.js";

package/dist/features/prompt-history/index.js

@@ -1,2 +1,3 @@
 export { PromptHistoryService } from "./service.js";
 export { resolvePromptHistoryPath } from "./paths.js";
+export { PromptImageSidecar, collectImageChipIdentifiers } from "./image-sidecar.js";

package/dist/features/prompt-history/paths.d.ts

@@ -1,4 +1,5 @@
 export declare function resolvePromptHistoryPath(dataDir: string, profileRoot: string, platform?: NodeJS.Platform): {
     path: string;
     profileId: string;
+    imagesDir: string;
 };

package/dist/features/prompt-history/paths.js

@@ -12,5 +12,6 @@ export function resolvePromptHistoryPath(dataDir, profileRoot, platform = proces
         normalized = normalized.replaceAll("\\", "/").toLowerCase();
     const digest = createHash("sha256").update(JSON.stringify([1, PRODUCT_IDENTITY.commandName, normalized])).digest("hex");
     const profileId = `${PRODUCT_IDENTITY.filesystem.temporaryPrefix}${digest}`;
-    return { path: paths.join(dataDir, "history", `${profileId}.sqlite3`), profileId };
+    const historyDir = paths.join(dataDir, "history");
+    return { path: paths.join(historyDir, `${profileId}.sqlite3`), profileId, imagesDir: paths.join(historyDir, `${profileId}-images`) };
 }