@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

package/dist/{src/features → features}/owned-ui/settings-app.js

@@ -1,4 +1,4 @@
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, PROMPT_GLYPH, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderStatusLine, renderListRow, renderNote, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, promptRule, caretCell, blockRowSpan, displayWidth, faint, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, selectableIndexes, } from "../../foundation/ui-components/index.js";
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderListRow, renderNote, renderStatusLine, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
 export const SETTINGS_APP_ID = "settings";
 export const SETTINGS_ROUTE = "settings";
 const SCOPE = SETTINGS_APP_ID;
@@ -29,6 +29,7 @@ SETTINGS_SHORTCUTS.declare({ key: "left", scope: DIALOG_SCOPE, description: "Cha
 SETTINGS_SHORTCUTS.declare({ key: "right", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts" }, "part-change");
 SETTINGS_SHORTCUTS.declare({ key: "up", scope: DIALOG_SCOPE, description: "Previous part", section: "Parts" }, "part-previous");
 SETTINGS_SHORTCUTS.declare({ key: "down", scope: DIALOG_SCOPE, description: "Next part", section: "Parts" }, "part-next");
+assertNoShortcutConflicts(SETTINGS_SHORTCUTS.assemble());
 const KEYS = {
     "\u001b[A": "up",
     "\u001b[B": "down",
@@ -56,6 +57,8 @@ export class SettingsApp {
     #session;
     #selectedKey;
     #scroll = 0;
+    // Invariant: keyboard navigation requests visibility once; pointer scrolling then stays free.
+    #selectionNeedsReveal = true;
     #reveal;
     #notice = null;
     #filter = null;
@@ -63,19 +66,15 @@ export class SettingsApp {
     #structured = null;
     #loading = true;
     #interruptArmed = false;
-    /** Values requested but not yet reflected by the source, keyed by entry. */
+    // Invariant: pending values remain visible until the source reflects them.
     #pending = new Map();
     #footerHeight = 1;
-    /** Column the dialog's values start at, so a label stays a label. */
     #dialogValueColumn = 0;
-    /** Screen row the dialog panel starts on, for pointer hits. */
     #panelTop = 0;
     #panelTopForFrame = 0;
-    /** Row key under the pointer, and where each row was drawn last frame. */
     #hoverKey = null;
     #hoverRegion = "label";
     #frameRows = [];
-    /** Where the value menu was drawn last frame, for hit testing. */
     #menuFrame = null;
     constructor(session) {
         this.#session = session;
@@ -90,15 +89,19 @@ export class SettingsApp {
         const theme = host.theme ?? PLAIN_THEME;
         this.#interruptArmed = host.interruptArmed;
         const rows = this.#rows();
+        const selected = indexOfKey(rows, this.#selectedKey);
         const footer = this.#footerLines(rect.width, theme);
         this.#footerHeight = footer.length;
         this.#panelTopForFrame = Math.max(0, rect.height - footer.length);
         this.#panelTop = this.#panelTopForFrame;
         const bodyHeight = Math.max(0, rect.height - footer.length);
-        const selected = indexOfKey(rows, this.#selectedKey);
-        this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
+        if (this.#selectionNeedsReveal) {
+            this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
+            this.#selectionNeedsReveal = false;
+        }
         this.#reveal = undefined;
         const layout = layoutList(rows, bodyHeight, this.#scroll);
+        this.#scroll = layout.scroll;
         const contentWidth = Math.max(0, rect.width - RAIL_COLUMNS);
         const valueColumn = this.#valueColumn(rows);
         const geometry = scrollbarGeometry({
@@ -121,14 +124,13 @@ export class SettingsApp {
             for (const index of layout.rowIndexes) {
                 const row = rows[index];
                 if (row !== undefined && row.kind === "element") {
+                    const view = this.#viewRow(row.value);
                     this.#frameRows.push({
-                        key: `${row.value.backend}:${row.value.id}`,
+                        key: view.key,
                         screenRow: body.length,
                         valueColumn,
-                        valueWidth: row.value.structured
-                            ? CONFIGURE.length
-                            : row.value.value === null ? 0 : displayWidth(displayValue(row.value.value)),
-                        stepper: isStepper(row.value),
+                        valueWidth: displayWidth(view.value),
+                        stepper: view.stepper !== undefined,
                     });
                 }
                 body.push(this.#renderRow(row, index === selected, contentWidth, valueColumn, theme));
@@ -148,7 +150,8 @@ export class SettingsApp {
             return this.#menuKey(data);
         if (this.#filter !== null)
             return this.#filterKey(data);
-        const action = SETTINGS_SHORTCUTS.resolve(KEYS[data] ?? data, SCOPE);
+        const key = KEYS[data] ?? data;
+        const action = SETTINGS_SHORTCUTS.resolve(key, SCOPE);
         if (action === null)
             return { consumed: false };
         const rows = this.#rows();
@@ -186,11 +189,14 @@ export class SettingsApp {
             }
             case "first":
             case "last": {
-                // End lands on the very last setting, not on the head of its section.
+                // Invariant: End lands on the very last setting, not on the head of its section.
                 const selectable = selectableIndexes(rows);
                 const target = action === "last" ? selectable.at(-1) : selectable[0];
-                if (target !== undefined)
-                    this.#jump(rows, target);
+                if (target !== undefined) {
+                    this.#select(rows, target);
+                    if (action === "first")
+                        this.#scroll = 0;
+                }
                 return { consumed: true };
             }
             case "previous-value":
@@ -208,7 +214,7 @@ export class SettingsApp {
             const overRow = menuRowAt(frame, event.row - 1, event.column);
             const overMenu = overRow !== null;
             if (event.kind === "motion") {
-                // The menu owns the pointer, but the row it came from is still the thing
+                // Invariant: the menu owns the pointer, but the row it came from is still the thing
                 // being changed, so its value keeps reading as the one under the pointer.
                 // Only a dialog that takes the screen puts that out.
                 const hadHover = this.#hoverKey !== menu.anchorKey || this.#hoverRegion !== "value";
@@ -227,7 +233,7 @@ export class SettingsApp {
             if (event.kind !== "press")
                 return { consumed: true, render: false };
             if (overRow === null) {
-                // A press anywhere else dismisses the menu rather than acting through it.
+                // Invariant: a press anywhere else dismisses the menu rather than acting through it.
                 this.#menu = null;
                 return { consumed: true };
             }
@@ -239,7 +245,7 @@ export class SettingsApp {
         }
         const open = this.#structured;
         if (open !== null) {
-            // The panel owns the pointer while it is open; its flag rows are the targets.
+            // Invariant: the panel owns the pointer while it is open; its flag rows are the targets.
             // The panel's rows begin one line below its rule.
             const panel = { firstRow: this.#panelTop + 1, rows: open.flags.length, valueColumn: this.#dialogValueColumn };
             const row = event.row - 1 - panel.firstRow;
@@ -253,7 +259,7 @@ export class SettingsApp {
             }
             if (event.kind === "press") {
                 open.index = row;
-                // Pointing at the label picks the row; the value is what changes it,
+                // Rationale: pointing at the label picks the row; the value is what changes it,
                 // exactly as in the list behind the dialog.
                 const key = open.flags[row] ?? "";
                 const width = displayWidth((open.record[key] ?? false) ? "true" : "false");
@@ -263,6 +269,15 @@ export class SettingsApp {
             }
             return { consumed: true, render: false };
         }
+        if (event.kind === "wheel-up" || event.kind === "wheel-down") {
+            // Invariant: the whole list pane owns wheel scrolling, including blank space beside
+            // short labels. It must not depend on finding an item under the pointer.
+            if (event.row < 1 || event.row > this.#panelTopForFrame)
+                return { consumed: false };
+            const distance = scrollbarWheelRows(this.#scrollbarSpeed());
+            this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? distance : -distance));
+            return { consumed: true };
+        }
         const row = this.#frameRows.find(candidate => candidate.screenRow === event.row - 1);
         const previousKey = this.#hoverKey;
         const previousRegion = this.#hoverRegion;
@@ -277,7 +292,7 @@ export class SettingsApp {
             const rows = this.#rows();
             const index = rows.findIndex(candidate => rowKey(candidate) === row.key);
             if (index >= 0) {
-                // The pointer acts where it points; the arrow belongs to the keyboard.
+                // Rationale: the pointer acts where it points; the arrow belongs to the keyboard.
                 this.#notice = null;
                 if (this.#hoverRegion === "minus")
                     this.#cycle(rows, index, -1);
@@ -288,10 +303,6 @@ export class SettingsApp {
             }
             return { consumed: true };
         }
-        if (event.kind === "wheel-up" || event.kind === "wheel-down") {
-            this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? 3 : -3));
-            return { consumed: true };
-        }
         const changed = previousKey !== this.#hoverKey || previousRegion !== this.#hoverRegion;
         return { consumed: event.kind !== "motion", render: changed };
     }
@@ -305,7 +316,7 @@ export class SettingsApp {
             return;
         }
         const shown = this.#shownValue(entry);
-        // A number is stepped, not picked from a list: it has its own two controls,
+        // Rationale: a number is stepped, not picked from a list: it has its own two controls,
         // and pointing at it is not a request for anything else.
         if (typeof shown === "number")
             return;
@@ -314,16 +325,12 @@ export class SettingsApp {
             return;
         }
         const current = shown === null ? 0 : Math.max(0, entry.choices.indexOf(shown));
-        // Nothing is highlighted until the pointer or a key picks a row, so opening
-        // the menu does not flash a highlight the reader did not ask for.
-        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: -1 };
+        // Compatibility: pinned SelectList opens on the value currently in effect.
+        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: current };
     }
-    /**
-     * A structured setting is a set of flags, so it opens as its own list rather
-     * than as a value menu: each row names one flag and toggles it in place.
-     */
+    // Rationale: a structured setting opens as its own flag list rather than a value menu.
     #openStructured(entry) {
-        // The flags come from the declaration, not from the stored value: an unset
+        // Invariant: the flags come from the declaration, not from the stored value: an unset
         // flag still has a row, showing the default the source would apply.
         if (entry.flags.length === 0) {
             this.#notice = `${labelOf(entry)} has nothing to configure`;
@@ -337,7 +344,7 @@ export class SettingsApp {
             const value = stored[flag.key];
             record[flag.key] = typeof value === "boolean" ? value : flag.fallback;
         }
-        // The dialog takes the screen: the row it was opened from stops being the
+        // Invariant: the dialog takes the screen: the row it was opened from stops being the
         // thing under the pointer, so it stops looking like it.
         this.#hoverKey = null;
         this.#hoverRegion = "label";
@@ -385,7 +392,7 @@ export class SettingsApp {
             return { consumed: true };
         }
         if (key === "up" || key === "down") {
-            // The keyboard starts from the value in effect rather than from the top.
+            // Compatibility: the keyboard starts from the value in effect rather than from the top.
             menu.index = menu.index < 0
                 ? menu.current
                 : Math.min(menu.choices.length - 1, Math.max(0, menu.index + (key === "down" ? 1 : -1)));
@@ -403,9 +410,20 @@ export class SettingsApp {
         if (input === null)
             return { consumed: false };
         const key = KEYS[data];
+        if (key === "home" || key === "end") {
+            const rows = this.#rows();
+            const selectable = selectableIndexes(rows);
+            const target = key === "end" ? selectable.at(-1) : selectable[0];
+            if (target !== undefined) {
+                this.#select(rows, target);
+                if (key === "home")
+                    this.#scroll = 0;
+            }
+            return { consumed: true };
+        }
         if (key === "up" || key === "down" || key === "shift+up" || key === "shift+down") {
             const rows = this.#rows();
-            // Nothing found means nothing to move through; the key is still swallowed
+            // Rationale: nothing found means nothing to move through; the key is still swallowed
             // rather than typed into the search.
             if (selectableIndexes(rows).length === 0)
                 return { consumed: true, render: false };
@@ -437,7 +455,7 @@ export class SettingsApp {
         }
         const shown = this.#shownValue(entry);
         if (typeof shown === "number") {
-            // At the end of the range there is nothing to say: the arrow already reads
+            // Rationale: at the end of the range there is nothing to say: the arrow already reads
             // as unavailable, so a message would only repeat it.
             const next = steppedValue(rangeOf(entry), shown, delta);
             if (next !== null)
@@ -458,25 +476,38 @@ export class SettingsApp {
     }
     #apply(entry, value) {
         const key = `${entry.backend}:${entry.id}`;
-        // Shown immediately so the row never lags a keypress, and so the next press
+        // Invariant: shown immediately so the row never lags a keypress, and so the next press
         // steps from here rather than from a value the source has not caught up to.
         this.#pending.set(key, value);
         void this.#session.change(entry.backend, entry.id, value).then(outcome => {
-            if (outcome.failure !== null) {
+            if (outcome.failure !== null || outcome.status === "failed") {
                 this.#pending.delete(key);
-                this.#notice = `Could not save ${labelOf(entry)}: ${outcome.failure}`;
+                this.#notice = `Could not save ${labelOf(entry)}: ${outcome.failure ?? "the effect failed"}`;
                 return;
             }
-            // A later press may have moved on; only the last request clears itself.
+            if (outcome.status === "unavailable" || outcome.limitationReason !== null) {
+                this.#pending.delete(key);
+                this.#notice = outcome.limitationReason ?? `${labelOf(entry)} is unavailable`;
+                return;
+            }
+            // Concurrency: a later press may have moved on; only the last request clears itself.
             if (this.#pending.get(key) === value)
                 this.#pending.delete(key);
-            this.#notice = outcome.pendingRestart ? `${labelOf(entry)} applies on the next start` : null;
+            this.#notice = outcome.status === "deferred" && outcome.application !== null
+                ? `${labelOf(entry)} is stored and applies ${applicationLabel(outcome.application)}`
+                : null;
         });
     }
-    /** What the row shows: the value asked for if one is outstanding, else the source's. */
     #shownValue(entry) {
         return this.#pending.get(`${entry.backend}:${entry.id}`) ?? entry.value;
     }
+    #scrollbarSpeed() {
+        const entry = this.#session.sections()
+            .flatMap(section => section.entries)
+            .find(candidate => candidate.backend === "a1" && candidate.id === "scrollbarSpeed");
+        const value = entry === undefined ? this.#session.value("scrollbarSpeed") : this.#shownValue(entry);
+        return isScrollbarSpeed(value) ? value : "normal";
+    }
     #jump(rows, target) {
         this.#select(rows, target);
         this.#reveal = blockRowSpan(rows, target);
@@ -485,6 +516,7 @@ export class SettingsApp {
         if (index < 0)
             return;
         this.#selectedKey = rowKey(rows[index]);
+        this.#selectionNeedsReveal = true;
         this.#notice = null;
     }
     #rows() {
@@ -494,7 +526,7 @@ export class SettingsApp {
             || labelOf(entry).toLowerCase().includes(needle);
         const rows = [];
         for (const section of this.#session.sections()) {
-            // A section named by the search is what the reader asked for, so it arrives
+            // Rationale: a section named by the search is what the reader asked for, so it arrives
             // whole rather than narrowed to the entries that happen to repeat its name.
             const named = needle.length > 0 && section.title.toLowerCase().includes(needle);
             const entries = named ? section.entries : section.entries.filter(matches);
@@ -510,7 +542,7 @@ export class SettingsApp {
             if (section.readOnlyReason !== null && (needle.length === 0 || named)) {
                 rows.push({ kind: "note", group: section.id, text: section.readOnlyReason });
             }
-            // Presented in the order the source reports, which is the order the
+            // Invariant: presented in the order the source reports, which is the order the
             // pinned engine shows and is neither declaration order nor alphabetical.
             for (const entry of entries) {
                 rows.push({
@@ -543,18 +575,18 @@ export class SettingsApp {
         const hovered = this.#hoverKey === key;
         return renderListRow(this.#viewRow(entry), { selected, hovered, region: this.#hoverRegion }, valueColumn, width, theme);
     }
-    /** What the list view needs to draw a setting: its words, and where it can go. */
     #viewRow(entry) {
         const shown = this.#shownValue(entry);
         const value = entry.structured
             ? CONFIGURE
-            : shown === null ? describeRaw(entry.rawValue) : displayValue(shown);
+            : shown === null
+                ? describeRaw(entry.rawValue)
+                : effectiveDisplay(entry, shown);
         const range = rangeOf(entry);
         return {
             key: `${entry.backend}:${entry.id}`,
             label: labelOf(entry),
             value,
-            ...(entry.origin === "default" ? { suffix: "(default)" } : {}),
             ...(typeof shown === "number" && entry.editable ? { stepper: stepperEnds(range, shown) } : {}),
         };
     }
@@ -578,13 +610,12 @@ export class SettingsApp {
         this.#menuFrame = frame;
         return renderValueMenu(lines, state, frame, theme);
     }
-    /** What the panel needs to present a structured setting's parts. */
     #dialogLines(open, width, theme) {
         const rows = open.flags.map(key => {
             const declared = open.entry.flags.find(flag => flag.key === key);
             return {
                 label: declared?.label ?? humanizeLabel(key),
-                // The engine writes these as the booleans they are rather than as yes/no.
+                // Protocol: the engine writes these as the booleans they are rather than as yes/no.
                 value: (open.record[key] ?? false) ? "true" : "false",
                 ...(declared?.description === undefined ? {} : { description: declared.description }),
             };
@@ -597,14 +628,12 @@ export class SettingsApp {
         const open = this.#structured;
         if (open !== null)
             return this.#dialogLines(open, width, theme);
-        // The hint is the declarations, so a key cannot be described here and bound
-        // to something else.
-        const hint = this.#interruptArmed ? "press ctrl+c again to exit A1" : SETTINGS_SHORTCUTS.hint(SCOPE);
+        const hint = this.#interruptArmed ? "press ctrl+c again to exit a1" : SETTINGS_SHORTCUTS.hint(SCOPE);
         const status = renderStatusLine({ hint, report: this.#notice }, width, theme);
         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. */
@@ -624,6 +653,23 @@ function displayValue(value) {
         return value ? "yes" : "no";
     return String(value);
 }
+function effectiveDisplay(entry, stored) {
+    const effective = entry.effectiveValue;
+    if (effective === stored)
+        return displayValue(stored);
+    const shownEffective = typeof effective === "string" || typeof effective === "number" || typeof effective === "boolean"
+        ? displayValue(effective)
+        : describeRaw(effective);
+    return `${displayValue(stored)} (effective ${shownEffective}; ${applicationLabel(entry.application)})`;
+}
+function applicationLabel(application) {
+    switch (application) {
+        case "live": return "live";
+        case "next-session": return "in the next session";
+        case "next-start": return "on the next start";
+        case "current-exit": return "when the current session exits";
+    }
+}
 function describeRaw(value) {
     if (value === null || value === undefined)
         return "unset";
@@ -631,3 +677,6 @@ function describeRaw(value) {
         return Array.isArray(value) ? `${value.length} items` : "structured value";
     return String(value);
 }
+function isScrollbarSpeed(value) {
+    return value === "normal" || value === "fast" || value === "high";
+}

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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { posix, win32 } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export function resolvePromptHistoryPath(dataDir, profileRoot, platform = process.platform) {
+    const paths = platform === "win32" ? win32 : posix;
+    if (!paths.isAbsolute(dataDir) || !paths.isAbsolute(profileRoot) || dataDir.includes("\0") || profileRoot.includes("\0"))
+        throw new TypeError("History requires absolute roots");
+    let normalized = paths.normalize(profileRoot);
+    if (normalized.length > paths.parse(normalized).root.length)
+        normalized = normalized.replace(/[\\/]+$/, "");
+    if (platform === "win32")
+        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}`;
+    const historyDir = paths.join(dataDir, "history");
+    return { path: paths.join(historyDir, `${profileId}.sqlite3`), profileId, imagesDir: paths.join(historyDir, `${profileId}-images`) };
+}