@timurproko/a1 0.1.8-dev.157 → 0.1.8-dev.182

package/README.md

@@ -78,6 +78,38 @@ npm run test:fast       # typecheck + fast suite (alias: npm test)
 npm run test:full       # complete non-physical suite
 ```
 
+Create every task worktree at `{working-dir}/.worktrees/<task-id>`, where
+`{working-dir}` is the session's initial working directory. For working directory
+`D:/Git/a1`, use `D:/Git/a1/.worktrees/<task-id>`—never a sibling such as
+`D:/Git/a1-<task-id>`. The primary worktree remains on `develop` for integration only.
+
+## Pull request integration
+
+Pull requests whose complete diff is only under `openspec/**`, under `docs/**`,
+exactly the root `README.md`, or a combination of those paths are automatically
+squash-merged after `Development validation required` succeeds. The automation
+reads the complete GitHub changed-file list, including both sides of renames, and
+runs only for trusted branches in this repository.
+
+Any other path makes the pull request code/operational. That includes source, tests,
+scripts, workflows, configuration, generated baselines, arbitrary root Markdown,
+and a mixed documentation-plus-code change. Those pull requests remain open after
+CI for local maintainer validation and explicit manual merge; automation disables
+auto-merge if it was armed. Documentation remains exempt from product builds and
+tests, but docs-sensitive generated governance and strict OpenSpec consistency are
+checked before integration.
+
+After any same-repository pull request into `develop` merges, trusted automation
+reconciles its remote topic branch. Human merges use the close-event workflow;
+documentation merges authored by `GITHUB_TOKEN` use a synchronous fallback because
+GitHub suppresses recursive workflow events. Both delete only an unprotected live
+ref that still equals the pull request's exact merged head SHA. Fork, advanced,
+reserved, protected, malformed, and unmerged refs are preserved and reported.
+
+Specification approval and implementation remain separate pull requests. An
+implementation starts from updated `origin/develop` only after its specification
+has merged and implementation was explicitly requested.
+
 ## Release
 
 Two channels, both published by CI from the exact bytes it validated — never from

package/bin/ui.js

@@ -12,13 +12,28 @@ assertSinglePiTuiModuleAtLaunch(fileURLToPath(new URL("..", import.meta.url)), m
 
 const { runSelectedInteractiveRuntime } = await import("../dist/features/launch/index.js");
 
+const launchArgs = process.argv.slice(2);
+let sessionPath;
+if (launchArgs.length > 0) {
+  if (launchArgs.length !== 2 || launchArgs[0] !== "--session" || launchArgs[1].trim().length === 0) {
+    throw new Error("Usage: a1 [--session <session-file>]");
+  }
+  sessionPath = launchArgs[1];
+}
+
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
   ownedUi: async (profileId, ownedSurfaces) => {
-    const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
+    const [{ createConsoleProjectTrustPrompt, runOwnedUi }, { composeOwnedUi }] = await Promise.all([
       import("../dist/features/owned-ui/index.js"),
       import("../dist/composition/index.js"),
     ]);
-    const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
+    const { application, settings } = await composeOwnedUi({
+      cwd: process.cwd(),
+      profileId,
+      ownedSurfaces,
+      projectTrustPrompt: createConsoleProjectTrustPrompt(),
+      ...(sessionPath === undefined ? {} : { sessionPath }),
+    });
     return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
   },
 }).then(

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

@@ -1,10 +1,12 @@
-import { type PiEngineAdapter } from "../integrations/pi/engine/index.js";
+import { type PiEngineAdapter, type PiProjectTrustPreflightPrompt } from "../integrations/pi/engine/index.js";
 import { OwnedUiSettingsSession } from "../ui/settings/index.js";
 import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
 export interface OwnedUiCompositionOptions {
     readonly cwd?: string;
     readonly terminal?: PresentationTerminalPort;
     readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+    /** Exact persisted session selected by the narrow `--session` launch form. */
+    readonly sessionPath?: string;
     /**
      * A1 profile whose settings this session reads and writes. Omitted keeps the
      * session settings-free, which is what the pinned comparison paths use.
@@ -15,6 +17,7 @@ export interface OwnedUiCompositionOptions {
      * use the same composition with those surfaces withheld.
      */
     readonly ownedSurfaces?: "on" | "off";
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
 }
 export interface OwnedUiComposition {
     readonly application: OwnedUiApplicationPort;

package/dist/composition/owned-ui.js

@@ -1,6 +1,6 @@
 import { resolveProductPaths } from "../foundation/lifecycle/index.js";
 import { applyConfiguredPiTheme, getAvailablePiThemes } from "../integrations/pi/components/index.js";
-import { createPiEngineAdapter } from "../integrations/pi/engine/index.js";
+import { createPiEngineAdapter, } from "../integrations/pi/engine/index.js";
 import { OwnedUiSessionShell } from "../integrations/pi/session-ui/index.js";
 import { OwnedUiSettingsSession, OwnedUiSettingsStore } from "../ui/settings/index.js";
 import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/index.js";
@@ -12,16 +12,19 @@ export async function composeOwnedUi(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const adapter = options.createPiAdapter
         ? await options.createPiAdapter()
-        : await createPiEngineAdapter({ cwd, availableThemes: () => getAvailablePiThemes().map(theme => theme.name) });
+        : await createPiEngineAdapter({
+            cwd,
+            availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
+            settingsProductMode: options.ownedSurfaces === "off" ? "comparison" : "bare",
+            ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
+            ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
+        });
     const ownedSurfaces = options.ownedSurfaces !== "off";
     const settings = options.profileId === undefined
         ? null
         : new OwnedUiSettingsSession({
             store: new OwnedUiSettingsStore({ configDir: resolveProductPaths().configDir, profileId: options.profileId }),
             agentProvider: () => adapter.settingsPort(),
-            ...(ownedSurfaces ? {
-                hiddenAgentSettingIds: ["tuiMode", "theme", "fullscreenScrollbar", "quietStartup"],
-            } : {}),
         });
     // Bare A1 intentionally ships one visual target while its UI is being completed:
     // dark, regardless of terminal detection or a previously stored Pi theme. The

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

@@ -1,4 +1,4 @@
-import type { AgentJsonValue, AgentModelDescriptor, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
+import type { AgentJsonValue, AgentModelDescriptor, AgentSettingChangeOutcome, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
 export interface AgentModelPort {
     readonly capabilities: {
         readonly selection: boolean;
@@ -26,7 +26,7 @@ export interface AgentSettingsPort {
     };
     listSettings(): Promise<readonly AgentSettingDescriptor[]>;
     readSetting(key: string): Promise<AgentJsonValue | undefined>;
-    writeSetting?(key: string, value: AgentJsonValue): Promise<void>;
+    writeSetting?(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
     flush?(): Promise<void>;
 }
 export interface AgentResourcesPort {

package/dist/contracts/agent-engine/domain-validation.js

@@ -52,10 +52,28 @@ export function assertAgentUsage(value) { for (const amount of [value.inputToken
     nonNegative(amount, "usage token count"); if (value.cost !== null && (!(typeof value.cost === "number") || !Number.isFinite(value.cost) || value.cost < 0))
     throw new TypeError("usage cost is invalid"); }
 export function assertAgentModelDescriptor(value) { id(value.providerId, "model provider id"); id(value.modelId, "model id"); text(value.displayName, "model display name"); nonNegative(value.contextWindow, "model context window"); unique(value.thinkingLevels, undefined, "model thinking levels"); }
-export function assertAgentSettingDescriptor(value) { id(value.key, "setting key"); if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType) || typeof value.writable !== "boolean")
-    throw new TypeError("setting descriptor is invalid"); if (value.choices)
-    for (const choice of value.choices)
-        json(choice, "setting choice"); }
+export function assertAgentSettingDescriptor(value) {
+    id(value.key, "setting key");
+    if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType)
+        || typeof value.writable !== "boolean"
+        || !["live", "next-session", "next-start", "current-exit"].includes(value.application)
+        || !["agent", "shell", "terminal", "startup", "shutdown", "installation"].includes(value.owner)
+        || typeof value.available !== "boolean"
+        || !(value.limitationReason === null || typeof value.limitationReason === "string")) {
+        throw new TypeError("setting descriptor is invalid");
+    }
+    json(value.storedValue, "stored setting value");
+    json(value.effectiveValue, "effective setting value");
+    if ((value.available && value.limitationReason !== null)
+        || (!value.available && (value.limitationReason === null || value.limitationReason.length === 0))) {
+        throw new TypeError("setting descriptor availability is contradictory");
+    }
+    if (value.writable && !value.available)
+        throw new TypeError("unavailable setting cannot be writable");
+    if (value.choices)
+        for (const choice of value.choices)
+            json(choice, "setting choice");
+}
 export function assertAgentResourceDescriptor(value) { id(value.id, "resource id"); if (!["command", "prompt", "skill", "extension", "other"].includes(value.kind))
     throw new TypeError("resource kind is invalid"); text(value.label, "resource label"); json(value.metadata, "resource metadata"); }
 export function assertAgentThemeDescriptor(value) { id(value.id, "theme id"); text(value.label, "theme label"); if (!value.tokens || typeof value.tokens !== "object" || Object.values(value.tokens).some(token => typeof token !== "string"))

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

@@ -48,10 +48,27 @@ export interface AgentModelDescriptor {
     readonly contextWindow: number;
     readonly thinkingLevels: readonly string[];
 }
+export type AgentSettingApplicationBoundary = "live" | "next-session" | "next-start" | "current-exit";
+export type AgentSettingOwner = "agent" | "shell" | "terminal" | "startup" | "shutdown" | "installation";
+export interface AgentSettingChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly application: AgentSettingApplicationBoundary;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
+    readonly failure: string | null;
+    readonly limitationReason: string | null;
+}
 export interface AgentSettingDescriptor {
     readonly key: string;
     readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
+    /** A setting is writable only when its declared owner/effect is available. */
     readonly writable: boolean;
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    readonly available: boolean;
+    readonly limitationReason: string | null;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
     readonly choices?: readonly AgentJsonValue[];
     /** Label the engine shows for this setting, when it has one. */
     readonly label?: string;

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

@@ -91,6 +91,12 @@ export interface OwnedUiOverlay {
     readonly modal: boolean;
     readonly payload: unknown;
 }
+export interface OwnedUiTranscriptImageReference {
+    readonly assetId: OwnedUiEntityId;
+    readonly mimeType: string;
+    readonly byteLength: number;
+    readonly source: "user" | "tool-result";
+}
 export interface OwnedUiTranscriptBlock {
     readonly id: OwnedUiEntityId;
     readonly kind: OwnedUiTranscriptBlockKind;
@@ -99,6 +105,8 @@ export interface OwnedUiTranscriptBlock {
     readonly title: string | null;
     readonly text: string;
     readonly payload: unknown;
+    /** Bounded opaque references; image bytes remain in the session-scoped engine asset store. */
+    readonly imageReferences?: readonly OwnedUiTranscriptImageReference[];
 }
 export type OwnedUiSlotId = "theme" | "transcript-block" | "tool-card" | "editor" | "status" | "command" | "selector" | "dialog" | "overlay" | "layout";
 export interface OwnedUiCustomization {

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

@@ -14,6 +14,7 @@ const MAX_QUEUE = 32;
 const MAX_BADGES = 32;
 const MAX_STATUS_DIAGNOSTICS = 32;
 const MAX_ACTIVE_COMMANDS = 64;
+const IMAGE_REFERENCE_SOURCES = new Set(["user", "tool-result"]);
 const BLOCK_KINDS = new Set([
     "user",
     "assistant",
@@ -225,6 +226,16 @@ export function assertOwnedUiTranscriptBlock(block) {
     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);
+    if (block.imageReferences !== undefined) {
+        assertCollection(block.imageReferences, "owned-UI transcript image references", 16);
+        for (const reference of block.imageReferences) {
+            assertId(reference.assetId, "owned-UI transcript image asset id");
+            if (!/^image\/[a-z0-9.+-]+$/i.test(reference.mimeType))
+                throw new TypeError("owned-UI transcript image MIME type is invalid");
+            assertIntegerInRange(reference.byteLength, 1, 20 * 1024 * 1024, "owned-UI transcript image byte length");
+            assertEnum(reference.source, IMAGE_REFERENCE_SOURCES, "owned-UI transcript image source");
+        }
+    }
 }
 export function assertOwnedUiEditorState(editor) {
     assertPossiblyEmptyText(editor.text, "owned-UI editor text", MAX_TEXT_BYTES);

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

@@ -1,4 +1,5 @@
 export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
+export * from "./project-trust-prompt.js";
 export * from "./settings-app.js";

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

@@ -1,4 +1,5 @@
 export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
+export * from "./project-trust-prompt.js";
 export * from "./settings-app.js";

package/dist/features/owned-ui/project-trust-prompt.d.ts

@@ -0,0 +1,20 @@
+import type { Readable, Writable } from "node:stream";
+export interface OwnedProjectTrustPromptRequest {
+    readonly cwd: string;
+    readonly defaultDecision: "ask" | "always" | "never";
+}
+export type OwnedProjectTrustPrompt = (request: OwnedProjectTrustPromptRequest) => Promise<boolean | null>;
+export interface ConsoleProjectTrustPromptOptions {
+    readonly input?: Readable & {
+        readonly isTTY?: boolean;
+    };
+    readonly output?: Writable & {
+        readonly isTTY?: boolean;
+    };
+}
+/**
+ * Minimal pre-session surface. It depends only on the parent terminal and fixed
+ * A1 wording, so no project setting, theme, extension, prompt, or skill can
+ * execute before the decision.
+ */
+export declare function createConsoleProjectTrustPrompt(options?: ConsoleProjectTrustPromptOptions): OwnedProjectTrustPrompt;

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

@@ -0,0 +1,32 @@
+import { createInterface } from "node:readline/promises";
+/**
+ * Minimal pre-session surface. It depends only on the parent terminal and fixed
+ * A1 wording, so no project setting, theme, extension, prompt, or skill can
+ * execute before the decision.
+ */
+export function createConsoleProjectTrustPrompt(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    return async ({ cwd }) => {
+        if (input.isTTY !== true || output.isTTY !== true) {
+            throw new Error("an interactive terminal is unavailable");
+        }
+        const reader = createInterface({ input, output, terminal: true });
+        try {
+            output.write(`\nA1 found project-local settings or executable resources in:\n${cwd}\n`);
+            output.write("Trusting permits project settings, skills, prompts, packages, themes, and extensions to load.\n");
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                const answer = (await reader.question("Trust this project for this and future launches? [y/N] ")).trim().toLowerCase();
+                if (answer === "y" || answer === "yes")
+                    return true;
+                if (answer === "" || answer === "n" || answer === "no")
+                    return false;
+                output.write("Enter y or n.\n");
+            }
+            return null;
+        }
+        finally {
+            reader.close();
+        }
+    };
+}

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

@@ -323,7 +323,7 @@ export class SettingsApp {
         if (typeof shown === "number")
             return;
         if (!entry.editable || entry.choices === null || entry.choices.length === 0) {
-            this.#notice = `${labelOf(entry)} cannot be changed here`;
+            this.#notice = entry.limitationReason ?? `${labelOf(entry)} cannot be changed here`;
             return;
         }
         const current = shown === null ? 0 : Math.max(0, entry.choices.indexOf(shown));
@@ -456,7 +456,7 @@ export class SettingsApp {
             return;
         const entry = row.value;
         if (!entry.editable) {
-            this.#notice = `${labelOf(entry)} cannot be changed here`;
+            this.#notice = entry.limitationReason ?? `${labelOf(entry)} cannot be changed here`;
             return;
         }
         const shown = this.#shownValue(entry);
@@ -470,7 +470,7 @@ export class SettingsApp {
         }
         const choices = entry.choices;
         if (choices === null || choices.length === 0) {
-            this.#notice = `${labelOf(entry)} cannot be changed here`;
+            this.#notice = entry.limitationReason ?? `${labelOf(entry)} cannot be changed here`;
             return;
         }
         const current = shown === null ? -1 : choices.indexOf(shown);
@@ -486,15 +486,22 @@ export class SettingsApp {
         // 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;
+            }
+            if (outcome.status === "unavailable" || outcome.limitationReason !== null) {
+                this.#pending.delete(key);
+                this.#notice = outcome.limitationReason ?? `${labelOf(entry)} is unavailable`;
                 return;
             }
             // 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. */
@@ -571,9 +578,13 @@ export class SettingsApp {
     /** 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);
+        const value = !entry.available
+            ? `unavailable — ${entry.limitationReason ?? "effect is unavailable"}`
+            : entry.structured
+                ? CONFIGURE
+                : shown === null
+                    ? describeRaw(entry.rawValue)
+                    : effectiveDisplay(entry, shown);
         const range = rangeOf(entry);
         return {
             key: `${entry.backend}:${entry.id}`,
@@ -648,6 +659,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";

package/dist/integrations/pi/components/shell-components.d.ts

@@ -2,5 +2,6 @@ export * from "./shell-shared-facade.js";
 export * from "./shell-editor-autocomplete.js";
 export * from "./shell-selectors-dialogs.js";
 export * from "./shell-presenters-transcript.js";
+export * from "./shell-presenters-info.js";
 export * from "./shell-footer-status.js";
 export * from "./shell-extension-ui.js";

package/dist/integrations/pi/components/shell-components.js

@@ -2,5 +2,6 @@ export * from "./shell-shared-facade.js";
 export * from "./shell-editor-autocomplete.js";
 export * from "./shell-selectors-dialogs.js";
 export * from "./shell-presenters-transcript.js";
+export * from "./shell-presenters-info.js";
 export * from "./shell-footer-status.js";
 export * from "./shell-extension-ui.js";

package/dist/integrations/pi/components/shell-editor-autocomplete.js

@@ -158,6 +158,16 @@ export function createPiShellEditor(options) {
         setSubmitHandler: handler => { submitHandler = handler; },
         setInterruptHandler: handler => { interruptHandler = handler; },
         setAutocompleteCommands,
+        setPaddingX(padding) {
+            editor.setPaddingX(padding);
+            editor.invalidate();
+            tui.requestRender();
+        },
+        setAutocompleteMaxVisible(maxVisible) {
+            editor.setAutocompleteMaxVisible(maxVisible);
+            editor.invalidate();
+            tui.requestRender();
+        },
         addAutocompleteProvider(factory) {
             if (typeof factory !== "function")
                 throw new TypeError("extension autocomplete factory must be a function");

package/dist/integrations/pi/components/shell-footer-status.js

@@ -71,16 +71,17 @@ export function createPiShellStatus(view, runtime) {
     ensureTheme();
     const statusUi = createTuiFacade(runtime ?? { getColumns: () => 80, getRows: () => 24, requestRender() { } });
     let workingOverride;
-    let component = statusComponent(view, statusUi, workingOverride);
-    let signature = statusSignature(view, workingOverride);
+    let outputPad = PINNED_PI_LAYOUT.outputPad;
+    let component = statusComponent(view, statusUi, workingOverride, outputPad);
+    let signature = statusSignature(view, workingOverride, outputPad);
     const rebuild = () => {
-        const nextSignature = statusSignature(view, workingOverride);
+        const nextSignature = statusSignature(view, workingOverride, outputPad);
         if (nextSignature === signature)
             return;
         if (component !== undefined && "dispose" in component && typeof component.dispose === "function")
             component.dispose();
         signature = nextSignature;
-        component = statusComponent(view, statusUi, workingOverride);
+        component = statusComponent(view, statusUi, workingOverride, outputPad);
     };
     return {
         render: width => component?.render(width) ?? [],
@@ -93,6 +94,10 @@ export function createPiShellStatus(view, runtime) {
             workingOverride = message;
             rebuild();
         },
+        setOutputPad(padding) {
+            outputPad = padding;
+            rebuild();
+        },
         dispose() {
             if (component !== undefined && "dispose" in component && typeof component.dispose === "function")
                 component.dispose();
@@ -121,19 +126,19 @@ export function createPiQueuedInputStatus(submissions, presentation = "pinned")
         },
     };
 }
-function statusComponent(view, ui, workingOverride) {
+function statusComponent(view, ui, workingOverride, outputPad) {
     if (view.lifecycle === "busy")
         return new WorkingStatusIndicator(ui, workingOverride ?? view.status.workingMessage ?? "Working...");
     if (view.lifecycle === "failed") {
-        return new Text(piTheme().fg("error", view.status.diagnostics.at(-1) ?? "Session failed"), PINNED_PI_LAYOUT.outputPad, 0);
+        return new Text(piTheme().fg("error", view.status.diagnostics.at(-1) ?? "Session failed"), outputPad, 0);
     }
     if (view.status.workingMessage !== null) {
-        return new Text(piTheme().fg("muted", view.status.workingMessage), PINNED_PI_LAYOUT.outputPad, 0);
+        return new Text(piTheme().fg("muted", view.status.workingMessage), outputPad, 0);
     }
     return undefined;
 }
-function statusSignature(view, workingOverride) {
-    return `${view.lifecycle}\u0000${workingOverride ?? ""}\u0000${view.status.workingMessage ?? ""}\u0000${view.status.diagnostics.at(-1) ?? ""}`;
+function statusSignature(view, workingOverride, outputPad) {
+    return `${outputPad}\u0000${view.lifecycle}\u0000${workingOverride ?? ""}\u0000${view.status.workingMessage ?? ""}\u0000${view.status.diagnostics.at(-1) ?? ""}`;
 }
 function queuedInputText(submissions, presentation) {
     if (submissions.length === 0)

package/dist/integrations/pi/components/shell-presenters-info.d.ts

@@ -0,0 +1,36 @@
+import { type PiShellComponentPort } from "./shell-shared-facade.js";
+export interface PiShellSessionInfoPresentation {
+    readonly sessionName?: string;
+    readonly stats: {
+        readonly sessionFile?: string;
+        readonly sessionId: string;
+        readonly userMessages: number;
+        readonly assistantMessages: number;
+        readonly toolCalls: number;
+        readonly toolResults: number;
+        readonly totalMessages: number;
+        readonly tokens: {
+            readonly input: number;
+            readonly output: number;
+            readonly cacheRead: number;
+            readonly cacheWrite: number;
+            readonly total: number;
+        };
+        readonly cost: number;
+    };
+    readonly cacheWaste: {
+        readonly missedTokens: number;
+        readonly missedCost: number;
+        readonly missCount: number;
+    };
+    readonly usageBreakdown: readonly {
+        readonly key: string;
+        readonly cost: number;
+        readonly tokens: number;
+    }[];
+}
+export declare function renderPiShellStatusText(message: string, width: number, outputPad?: 0 | 1): readonly string[];
+export declare function createPiShellSessionInfo(presentation: PiShellSessionInfoPresentation): PiShellComponentPort;
+export declare function createPiShellCollapsedChangelog(): PiShellComponentPort;
+export declare function createPiShellChangelog(markdown: string): PiShellComponentPort;
+export declare function createPiShellHotkeys(): PiShellComponentPort;

package/dist/integrations/pi/components/shell-presenters-info.js

@@ -0,0 +1,78 @@
+import { DynamicBorder, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "#pi-tui";
+import { KeybindingsManager } from "./upstream/adjacent/core/keybindings.js";
+import { PINNED_PI_LAYOUT, piTheme } from "./theme.js";
+import { componentPort, ensureTheme, formatSessionTokens } from "./shell-shared-facade.js";
+export function renderPiShellStatusText(message, width, outputPad = PINNED_PI_LAYOUT.outputPad) {
+    ensureTheme();
+    return new Text(piTheme().fg("dim", message), outputPad, 0).render(width);
+}
+export function createPiShellSessionInfo(presentation) {
+    ensureTheme();
+    const { stats, sessionName, cacheWaste, usageBreakdown } = presentation;
+    let info = `${piTheme().bold("Session Info")}\n\n`;
+    if (sessionName)
+        info += `${piTheme().fg("dim", "Name:")} ${sessionName}\n`;
+    info += `${piTheme().fg("dim", "File:")} ${stats.sessionFile ?? "In-memory"}\n${piTheme().fg("dim", "ID:")} ${stats.sessionId}\n\n`;
+    info += `${piTheme().bold("Messages")}\n${piTheme().fg("dim", "Total:")} ${stats.totalMessages}\n${piTheme().fg("dim", "User:")} ${stats.userMessages}\n`;
+    info += `${piTheme().fg("dim", "Assistant:")} ${stats.assistantMessages}\n${piTheme().fg("dim", "Tools:")} ${stats.toolCalls} calls, ${stats.toolResults} results\n\n`;
+    info += `${piTheme().bold("Tokens")}\n`;
+    const { input, cacheRead, cacheWrite } = stats.tokens;
+    const promptTokens = input + cacheRead + cacheWrite;
+    info += `${piTheme().fg("dim", "Input:")} ${promptTokens.toLocaleString()}\n`;
+    if (promptTokens > 0 && (cacheRead > 0 || cacheWrite > 0)) {
+        info += `  ${piTheme().fg("dim", "Cached:")} ${cacheRead.toLocaleString()} ${piTheme().fg("dim", `(${((cacheRead / promptTokens) * 100).toFixed(1)}%)`)}\n`;
+        const written = cacheWrite > 0 ? ` ${piTheme().fg("dim", `(${cacheWrite.toLocaleString()} written to cache)`)}` : "";
+        info += `  ${piTheme().fg("dim", "Uncached:")} ${(input + cacheWrite).toLocaleString()}${written}\n`;
+    }
+    info += `${piTheme().fg("dim", "Output:")} ${stats.tokens.output.toLocaleString()}\n${piTheme().fg("dim", "Total:")} ${stats.tokens.total.toLocaleString()}\n`;
+    if (stats.cost > 0 || cacheWaste.missedTokens > 0) {
+        info += `\n${piTheme().bold("Cost")}\n${piTheme().fg("dim", "Total:")} $${stats.cost.toFixed(3)}`;
+        if (usageBreakdown.length > 1)
+            for (const entry of usageBreakdown)
+                info += `\n  ${piTheme().fg("dim", `${entry.key}:`)} $${entry.cost.toFixed(3)} ${piTheme().fg("dim", `(${formatSessionTokens(entry.tokens)} tokens)`)}`;
+        if (cacheWaste.missedTokens > 0) {
+            const detail = `${cacheWaste.missedTokens.toLocaleString()} tokens, ${cacheWaste.missCount === 1 ? "1 miss" : `${cacheWaste.missCount} misses`}`;
+            info += cacheWaste.missedCost >= 0.0001 ? `\n${piTheme().fg("dim", "Cache Re-billed:")} $${cacheWaste.missedCost.toFixed(3)} ${piTheme().fg("dim", `(${detail})`)}` : `\n${piTheme().fg("dim", "Cache Re-billed:")} ${detail}`;
+        }
+    }
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(info, 1, 0));
+    return componentPort(container);
+}
+export function createPiShellCollapsedChangelog() {
+    ensureTheme();
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    container.addChild(new DynamicBorder());
+    container.addChild(new Text(`${piTheme().bold(piTheme().fg("accent", "What's New"))}\n${piTheme().fg("muted", "Run /changelog to view the full release notes.")}`, 1, 0));
+    container.addChild(new DynamicBorder());
+    return componentPort(container);
+}
+export function createPiShellChangelog(markdown) {
+    ensureTheme();
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    container.addChild(new DynamicBorder());
+    container.addChild(new Text(piTheme().bold(piTheme().fg("accent", "What's New")), 1, 0));
+    container.addChild(new Spacer(1));
+    container.addChild(new Markdown(markdown.trim() || "No changelog entries found.", 1, 1, getMarkdownTheme()));
+    container.addChild(new DynamicBorder());
+    return componentPort(container);
+}
+export function createPiShellHotkeys() {
+    ensureTheme();
+    const keys = new KeybindingsManager();
+    const display = (action) => keys.getKeys(action).map(key => key.split("+").map(part => part.charAt(0).toUpperCase() + part.slice(1)).join("+")).join("/");
+    const row = (actions, description) => `| ${actions.map(action => `\`${display(action)}\``).join(" / ")} | ${description} |`;
+    const markdown = ["**Navigation**", "| Key | Action |", "|-----|--------|", row(["tui.editor.cursorUp", "tui.editor.cursorDown", "tui.editor.cursorLeft", "tui.editor.cursorRight"], "Move cursor / browse history"), row(["tui.editor.cursorWordLeft", "tui.editor.cursorWordRight"], "Move by word"), row(["tui.editor.cursorLineStart"], "Start of line"), row(["tui.editor.cursorLineEnd"], "End of line"), row(["tui.editor.jumpForward"], "Jump forward to character"), row(["tui.editor.jumpBackward"], "Jump backward to character"), row(["tui.editor.pageUp", "tui.editor.pageDown"], "Scroll by page"), "", "**Editing**", "| Key | Action |", "|-----|--------|", row(["tui.input.submit"], "Send message"), row(["tui.input.newLine"], `New line${process.platform === "win32" ? " (Ctrl+Enter on Windows Terminal)" : ""}`), row(["tui.editor.deleteWordBackward"], "Delete word backwards"), row(["tui.editor.deleteWordForward"], "Delete word forwards"), row(["tui.editor.deleteToLineStart"], "Delete to start of line"), row(["tui.editor.deleteToLineEnd"], "Delete to end of line"), row(["tui.editor.yank"], "Paste the most-recently-deleted text"), row(["tui.editor.yankPop"], "Cycle through the deleted text after pasting"), row(["tui.editor.undo"], "Undo"), "", "**Other**", "| Key | Action |", "|-----|--------|", row(["tui.input.tab"], "Path completion / accept autocomplete"), row(["app.interrupt"], "Cancel autocomplete / abort streaming"), row(["app.clear"], "Clear editor (first) / exit (second)"), row(["app.exit"], "Exit (when editor is empty)"), row(["app.suspend"], "Suspend to background"), row(["app.thinking.cycle"], "Cycle thinking level"), row(["app.model.cycleForward", "app.model.cycleBackward"], "Cycle models"), row(["app.model.select"], "Open model selector"), row(["app.tools.expand"], "Toggle tool output expansion"), row(["app.thinking.toggle"], "Toggle thinking block visibility"), row(["app.editor.external"], "Edit message in external editor"), row(["app.message.copy"], "Copy last assistant message"), row(["app.message.followUp"], "Queue follow-up message"), row(["app.message.dequeue"], "Restore queued messages"), row(["app.clipboard.pasteImage"], "Paste image or text from clipboard"), "| `/` | Slash commands |", "| `!` | Run bash command |", "| `!!` | Run bash command (excluded from context) |"].join("\n");
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    container.addChild(new DynamicBorder());
+    container.addChild(new Text(piTheme().bold(piTheme().fg("accent", "Keyboard Shortcuts")), 1, 0));
+    container.addChild(new Spacer(1));
+    container.addChild(new Markdown(markdown, 1, 1, getMarkdownTheme()));
+    container.addChild(new DynamicBorder());
+    return componentPort(container);
+}