@timurproko/a1 0.1.8-dev.544 → 0.1.8-dev.546

package/dist/integrations/pi/engine/session-runtime.js

@@ -9,6 +9,9 @@ import { DefaultPackageManager, VERSION } from "../startup-public.js";
 import { readOpenPullRequest, } from "./repository-pr.js";
 const execFileAsync = promisify(execFile);
 const PULL_REQUEST_REFRESH_MS = 60_000;
+const REPOSITORY_CONTEXT_POLL_MS = 5_000;
+const GIT_BRANCH_TIMEOUT_MS = 5_000;
+const GIT_BRANCH_MAX_BUFFER_BYTES = 4 * 1024;
 /**
  * The pinned Pi runtime and the session bound to it: creation through the runtime factory, the
  * session generation that stamps and invalidates events, the subscription that forwards session
@@ -22,6 +25,8 @@ export class PiEngineRuntime {
     #checkPackageUpdates;
     #pullRequestProbe;
     #pullRequestRefreshMs;
+    #repositoryContextPollMs;
+    #repositoryContextReader;
     #gitBranchReader;
     #cwd;
     #runtime;
@@ -31,15 +36,21 @@ export class PiEngineRuntime {
     #sessionBindingGeneration = 0;
     #sessionCommands;
     #compactionProgress = null;
+    #repositoryCwd;
     #gitBranch = null;
     #pullRequest = null;
-    #pullRequestTimer;
-    #pullRequestAbort;
+    #repositoryRefreshTimer;
+    #repositoryRefreshAbort;
+    #repositoryRefreshTask;
+    #repositoryRefreshPending = false;
+    #lastPullRequestProbeAt = null;
+    #repositoryRefreshEnabled = false;
     #disposed = false;
     constructor(options, ports) {
         this.#options = options;
         this.#ports = ports;
         this.#cwd = options.cwd;
+        this.#repositoryCwd = options.cwd;
         this.#runtimeFactory = options.createRuntime ?? createDefaultPiRuntime;
         this.#checkPackageUpdates = options.checkPackageUpdates
             ?? (options.createRuntime
@@ -47,6 +58,8 @@ export class PiEngineRuntime {
                 : settingsManager => checkDefaultPiPackageUpdates(this.#cwd, options.agentDir, settingsManager));
         this.#pullRequestProbe = options.pullRequestProbe ?? readOpenPullRequest;
         this.#pullRequestRefreshMs = options.pullRequestRefreshMs ?? PULL_REQUEST_REFRESH_MS;
+        this.#repositoryContextPollMs = options.repositoryContextPollMs ?? REPOSITORY_CONTEXT_POLL_MS;
+        this.#repositoryContextReader = options.repositoryContextReader ?? (async () => null);
         this.#gitBranchReader = options.gitBranchReader ?? readGitBranch;
     }
     get runtime() {
@@ -66,6 +79,9 @@ export class PiEngineRuntime {
     get cwd() {
         return this.#runtime?.cwd ?? this.#cwd;
     }
+    get repositoryCwd() {
+        return this.#repositoryCwd;
+    }
     get gitBranch() {
         return this.#gitBranch;
     }
@@ -91,7 +107,7 @@ export class PiEngineRuntime {
         });
         this.#runtime = runtime;
         this.#cwd = runtime.cwd ?? this.#cwd;
-        this.#gitBranch = await this.#gitBranchReader(this.#cwd);
+        this.#repositoryCwd = this.#cwd;
         this.#ports.started(runtime);
         runtime.setRebindSession(async (session) => {
             if (this.#ports.rebindBlocked())
@@ -104,7 +120,8 @@ export class PiEngineRuntime {
         }
         this.bindSession(runtime.session);
         await this.#announceChangelog(runtime.services.settingsManager);
-        this.#startPullRequestRefresh();
+        this.#repositoryRefreshEnabled = true;
+        this.#startRepositoryRefresh();
         return runtime;
     }
     /** Probe extension packages for updates after startup and report them as an informational diagnostic. */
@@ -161,7 +178,10 @@ export class PiEngineRuntime {
         // Invariant: the subscription is live before the adapter rebuilds its state so the extension
         // rebind that finishes the rebuild cannot emit an event nobody is listening to.
         this.#subscribe();
+        this.#resetRepositoryRefresh();
         this.#ports.sessionReplaced(session);
+        if (this.#repositoryRefreshEnabled)
+            this.#startRepositoryRefresh();
     }
     /** Stop forwarding the current session's events and open a new generation; overload recovery resumes or abandons it. */
     suspend() {
@@ -201,50 +221,126 @@ export class PiEngineRuntime {
     /** Unsubscribe, stop observing compaction, and dispose the runtime; the session reference is kept for final reads. */
     async dispose() {
         this.#disposed = true;
-        if (this.#pullRequestTimer !== undefined)
-            clearTimeout(this.#pullRequestTimer);
-        this.#pullRequestTimer = undefined;
-        this.#pullRequestAbort?.abort();
-        this.#pullRequestAbort = undefined;
+        this.#repositoryRefreshEnabled = false;
+        if (this.#repositoryRefreshTimer !== undefined)
+            clearTimeout(this.#repositoryRefreshTimer);
+        this.#repositoryRefreshTimer = undefined;
+        this.#repositoryRefreshPending = false;
+        this.#repositoryRefreshAbort?.abort();
+        const repositoryRefreshTask = this.#repositoryRefreshTask;
         this.#unsubscribe?.();
         this.#unsubscribe = undefined;
         this.#compactionProgress?.dispose();
         this.#compactionProgress = null;
+        await repositoryRefreshTask;
         await this.#runtime?.dispose();
     }
-    #startPullRequestRefresh() {
-        if (this.#gitBranch === null || this.#disposed || this.#ports.disposed())
+    #startRepositoryRefresh() {
+        if (!this.#repositoryRefreshEnabled || this.#disposed || this.#ports.disposed())
+            return;
+        if (this.#repositoryRefreshTask !== undefined) {
+            this.#repositoryRefreshPending = true;
             return;
-        void this.#refreshPullRequest();
+        }
+        const task = this.#refreshRepositoryMetadata();
+        this.#repositoryRefreshTask = task;
+        const settled = () => {
+            if (this.#repositoryRefreshTask === task)
+                this.#repositoryRefreshTask = undefined;
+            if (!this.#repositoryRefreshPending)
+                return;
+            this.#repositoryRefreshPending = false;
+            this.#startRepositoryRefresh();
+        };
+        void task.then(settled, settled);
     }
-    async #refreshPullRequest() {
-        const branch = this.#gitBranch;
-        if (branch === null || this.#pullRequestAbort !== undefined || this.#disposed || this.#ports.disposed())
+    #resetRepositoryRefresh() {
+        if (this.#repositoryRefreshTimer !== undefined)
+            clearTimeout(this.#repositoryRefreshTimer);
+        this.#repositoryRefreshTimer = undefined;
+        this.#repositoryRefreshAbort?.abort();
+        this.#repositoryCwd = this.#cwd;
+        this.#gitBranch = null;
+        this.#pullRequest = null;
+        this.#lastPullRequestProbeAt = null;
+    }
+    async #refreshRepositoryMetadata() {
+        if (this.#repositoryRefreshAbort !== undefined || this.#disposed || this.#ports.disposed())
             return;
         const controller = new AbortController();
-        this.#pullRequestAbort = controller;
-        let next = null;
+        const generation = this.#sessionBindingGeneration;
+        this.#repositoryRefreshAbort = controller;
+        let associatedContext = null;
+        const manager = this.#session?.sessionManager;
+        const sessionId = manager?.getSessionId?.();
+        const sessionFile = manager?.getSessionFile?.();
         try {
-            next = await this.#pullRequestProbe(this.#cwd, branch, controller.signal);
+            if (typeof sessionId === "string" && sessionId.length > 0 && typeof sessionFile === "string" && sessionFile.length > 0) {
+                try {
+                    associatedContext = await this.#repositoryContextReader(sessionId, sessionFile, controller.signal);
+                }
+                catch {
+                    associatedContext = null;
+                }
+            }
+            const nextCwd = associatedContext?.cwd ?? this.#cwd;
+            let nextBranch = associatedContext?.branch ?? null;
+            if (associatedContext === null) {
+                try {
+                    nextBranch = await this.#gitBranchReader(nextCwd, controller.signal);
+                }
+                catch {
+                    nextBranch = null;
+                }
+            }
+            const metadataChanged = nextCwd !== this.#repositoryCwd || nextBranch !== this.#gitBranch;
+            const remoteDue = metadataChanged || this.#lastPullRequestProbeAt === null
+                || Date.now() - this.#lastPullRequestProbeAt >= this.#pullRequestRefreshMs;
+            if (remoteDue) {
+                let nextPullRequest = null;
+                try {
+                    nextPullRequest = nextBranch === null
+                        ? null
+                        : await this.#pullRequestProbe(nextCwd, nextBranch, controller.signal);
+                }
+                catch {
+                    nextPullRequest = null;
+                }
+                if (controller.signal.aborted || generation !== this.#sessionBindingGeneration || this.#disposed || this.#ports.disposed())
+                    return;
+                const changed = nextCwd !== this.#repositoryCwd
+                    || nextBranch !== this.#gitBranch
+                    || !samePullRequest(this.#pullRequest, nextPullRequest);
+                this.#repositoryCwd = nextCwd;
+                this.#gitBranch = nextBranch;
+                this.#pullRequest = nextPullRequest;
+                this.#lastPullRequestProbeAt = Date.now();
+                if (changed)
+                    this.#ports.emitView();
+            }
         }
         catch {
-            next = null;
+            if (!controller.signal.aborted && generation === this.#sessionBindingGeneration && !this.#disposed && !this.#ports.disposed()) {
+                const changed = this.#repositoryCwd !== this.#cwd || this.#gitBranch !== null || this.#pullRequest !== null;
+                this.#repositoryCwd = this.#cwd;
+                this.#gitBranch = null;
+                this.#pullRequest = null;
+                this.#lastPullRequestProbeAt = Date.now();
+                if (changed)
+                    this.#ports.emitView();
+            }
         }
         finally {
-            if (this.#pullRequestAbort === controller)
-                this.#pullRequestAbort = undefined;
+            if (this.#repositoryRefreshAbort === controller)
+                this.#repositoryRefreshAbort = undefined;
         }
-        if (controller.signal.aborted || this.#disposed || this.#ports.disposed())
+        if (controller.signal.aborted || generation !== this.#sessionBindingGeneration || this.#disposed || this.#ports.disposed())
             return;
-        if (!samePullRequest(this.#pullRequest, next)) {
-            this.#pullRequest = next;
-            this.#ports.emitView();
-        }
-        this.#pullRequestTimer = setTimeout(() => {
-            this.#pullRequestTimer = undefined;
-            void this.#refreshPullRequest();
-        }, this.#pullRequestRefreshMs);
-        this.#pullRequestTimer.unref?.();
+        this.#repositoryRefreshTimer = setTimeout(() => {
+            this.#repositoryRefreshTimer = undefined;
+            this.#startRepositoryRefresh();
+        }, this.#repositoryContextPollMs);
+        this.#repositoryRefreshTimer.unref?.();
     }
     #subscribe() {
         const session = this.#session;
@@ -296,9 +392,16 @@ async function checkDefaultPiPackageUpdates(cwd, agentDir, settingsManager) {
 function samePullRequest(left, right) {
     return left?.number === right?.number && left?.url === right?.url;
 }
-async function readGitBranch(cwd) {
+async function readGitBranch(cwd, signal) {
     try {
-        const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { cwd, windowsHide: true });
+        const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+            cwd,
+            windowsHide: true,
+            timeout: GIT_BRANCH_TIMEOUT_MS,
+            maxBuffer: GIT_BRANCH_MAX_BUFFER_BYTES,
+            signal,
+            encoding: "utf8",
+        });
         const branch = stdout.trim();
         return branch.length > 0 ? branch : null;
     }

package/dist/integrations/pi/engine/transcript-projection.js

@@ -2,6 +2,39 @@ import { toolRenderingInput } from "./tool-rendering.js";
 import { TranscriptImageAssets } from "./transcript-image-assets.js";
 import { acceptsTranscriptUpdate, transcriptToolState } from "../../../contracts/owned-ui/index.js";
 import { assistantContent, contentImageCount, isRecord, jsonSummary, messageFallbackKey, retainCompletedArguments, sameBlockContent, sanitizeJson, stringValue, textFromContent } from "./message-values.js";
+const IMAGE_DIMENSION_NOTE = /^\[Image: original \d+x\d+, displayed at \d+x\d+\. Multiply coordinates by \d+(?:\.\d+)? to map to original image\.\]$/u;
+const IMAGE_CONVERSION_NOTE = /^\[Image converted from image\/[a-z0-9.+-]+ to image\/[a-z0-9.+-]+\.\]$/iu;
+const IMAGE_OMISSION_NOTE = /^\[Image omitted: could not be (?:converted to a supported inline image format|resized below the inline image size limit)\.\]$/u;
+function isImageProcessingHint(line) {
+    return IMAGE_DIMENSION_NOTE.test(line) || IMAGE_CONVERSION_NOTE.test(line) || IMAGE_OMISSION_NOTE.test(line);
+}
+function userPresentation(content) {
+    const imageCount = contentImageCount(content);
+    if (imageCount === 0)
+        return undefined;
+    const lines = textFromContent(content).split("\n");
+    const retainedHints = [];
+    let dimensionCount = 0;
+    let hintStart = lines.length;
+    while (hintStart > 0) {
+        const line = lines[hintStart - 1];
+        if (!isImageProcessingHint(line))
+            break;
+        if (IMAGE_DIMENSION_NOTE.test(line))
+            dimensionCount++;
+        else
+            retainedHints.unshift(line);
+        hintStart--;
+    }
+    if (dimensionCount === 0 || dimensionCount > imageCount)
+        return undefined;
+    lines.splice(hintStart);
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (retainedHints.length > 0)
+        lines.push("", ...retainedHints);
+    return { visibleText: lines.join("\n") };
+}
 /**
  * The transcript as the owned UI sees it: Pi's session messages and tool events projected into
  * ordered, revisioned blocks. The projection owns block identity (message and tool ids that stay
@@ -122,6 +155,7 @@ export class PiTranscriptProjection {
             return [];
         const baseId = this.#messageBlockId(message, fallbackIndex, status, occurrence);
         if (message.role === "user") {
+            const presentation = userPresentation(message.content);
             return [{
                     id: baseId,
                     kind: "user",
@@ -129,6 +163,7 @@ export class PiTranscriptProjection {
                     revision: this.nextRevision(baseId),
                     title: "User",
                     text: textFromContent(message.content),
+                    ...(presentation === undefined ? {} : { userPresentation: presentation }),
                     imageReferences: this.imageReferences(message.content, "user"),
                     payload: {
                         role: "user",

package/dist/integrations/pi/startup-public.manifest.json

@@ -16,6 +16,8 @@
     "dist/integrations/pi/components/upstream/adjacent/core/keybindings.js",
     "dist/integrations/pi/components/upstream/components/earendil-announcement.js",
     "dist/integrations/pi/components/upstream/components/extension-editor.js",
+    "dist/integrations/pi/components/upstream/components/extension-input.js",
+    "dist/integrations/pi/components/upstream/components/extension-selector.js",
     "dist/integrations/pi/components/upstream/components/scoped-models-selector.js",
     "dist/integrations/pi/components/upstream/components/session-selector.js",
     "dist/integrations/pi/components/upstream/components/status-indicator.js",

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-22T19:10:19.352Z",
+  "builtAt": "2026-09-22T23:31:15.773Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-22T19:10:09.829Z",
+  "builtAt": "2026-09-22T23:30:53.377Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-22T19:10:51.843Z",
+  "builtAt": "2026-09-22T23:31:43.770Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "cdef023b39a9328a308f1bcb293d2345240fb063af044e7948154113a3746c73",
+    "sha256": "57ed4829927f81b1cb638ffafa7a5b3832537284aa343c0eb0ef70592ed671d3",
     "size": 177664
   },
   "provenance": {

package/dist/product-identity.d.ts

@@ -1,6 +1,6 @@
 declare const ENVIRONMENT_KEYS: readonly ["clipboardDiagnostics", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "paneId", "probeTrace", "processGuardianPath", "prFooterPreview", "profileHome", "runtimeDir", "startupTrace", "suggestionDiagnostics", "terminalSessionId"];
 declare const FILESYSTEM_KEYS: readonly ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
-declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile"];
+declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile", "sessionRepositoryDirectory"];
 declare const ENDPOINT_KEYS: readonly ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];
 declare const MANIFEST_KEYS: readonly ["releaseFilename", "packageFilename"];
 declare const PROTOCOL_KEYS: readonly ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "promptHistorySchema", "releaseCohortSchema", "updateJournalSchema"];

package/dist/product-identity.js

@@ -4,7 +4,7 @@ const ENVIRONMENT_KEYS = [
     "paneId", "probeTrace", "processGuardianPath", "prFooterPreview", "profileHome", "runtimeDir", "startupTrace", "suggestionDiagnostics", "terminalSessionId",
 ];
 const FILESYSTEM_KEYS = ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
-const STATE_KEYS = ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile"];
+const STATE_KEYS = ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile", "sessionRepositoryDirectory"];
 const ENDPOINT_KEYS = ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];
 const MANIFEST_KEYS = ["releaseFilename", "packageFilename"];
 const PROTOCOL_KEYS = ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "promptHistorySchema", "releaseCohortSchema", "updateJournalSchema"];

package/dist/product-identity.json

@@ -32,7 +32,8 @@
         "unixControlDirectory": "a1",
         "developmentDirectory": "a1-development",
         "piAgentProfile": ".a1/agent",
-        "piVanillaProfile": ".pi/agent"
+        "piVanillaProfile": ".pi/agent",
+        "sessionRepositoryDirectory": "session-repositories"
     },
     "endpoint": {
         "windowsPipeStem": "a1",

package/dist/ui/components/dialog-panel.d.ts

@@ -1,3 +1,4 @@
+import { type ShortcutHintEntry } from "./shortcut-hints.js";
 import type { UiTheme } from "./theme.js";
 /**
  * The panel a value with parts is edited in: at the foot of the screen, over the
@@ -15,7 +16,7 @@ export interface DialogPanelState {
     /** The row in hand. */
     readonly index: number;
     /** How to change it, in the words the engine uses. */
-    readonly hint: string;
+    readonly hint: string | readonly ShortcutHintEntry[];
 }
 /** Where the panel sits, for reading a pointer against its rows. */
 export interface DialogPanelFrame {

package/dist/ui/components/dialog-panel.js

@@ -1,3 +1,4 @@
+import { renderShortcutHints, shortcutHintsText } from "./shortcut-hints.js";
 import { displayWidth, truncateToWidth } from "./text.js";
 const LABEL_COLUMN_CAP = 30;
 /** The column values start at: past the widest label, capped so one long name cannot push them off. */
@@ -25,13 +26,17 @@ export function renderDialogPanel(state, width, theme) {
         return pad(truncateToWidth(painted, width), width, raw);
     });
     const description = state.rows[state.index]?.description ?? "";
+    const hint = typeof state.hint === "string"
+        ? theme.fg("dim", `  ${state.hint}`)
+        : renderShortcutHints(state.hint, theme, 2);
+    const plainHint = typeof state.hint === "string" ? `  ${state.hint}` : shortcutHintsText(state.hint, 2);
     return [
         rule,
         ...rows,
         "",
         pad(truncateToWidth(theme.fg("dim", `  ${description}`), width), width, `  ${description}`),
         "",
-        pad(truncateToWidth(theme.fg("dim", `  ${state.hint}`), width), width, `  ${state.hint}`),
+        pad(truncateToWidth(hint, width), width, plainHint),
         rule,
     ];
 }

package/dist/ui/components/index.d.ts

@@ -22,6 +22,8 @@ export { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyLineContent, selecti
 export type { SelectionCopyPrompt, SelectionCopyRow, SelectionCopySnapshot } from "./selection-copy.js";
 export { ScrollbarRails, isThumbRow, scrollForThumbRow, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarReservesSpace, scrollbarSelectionRows, scrollbarWheelRows, } from "./scrollbar.js";
 export type { RailPointer, RailPosition, ScrollbarAppearance, ScrollbarGeometry, ScrollbarInput, ScrollbarPresentation, ScrollbarPresentationInput, ScrollbarSpeed, ScrollbarStyle, } from "./scrollbar.js";
+export { renderShortcutHints } from "./shortcut-hints.js";
+export type { ShortcutHintEntry } from "./shortcut-hints.js";
 export { GLOBAL_SCOPE, ShortcutRegistry, assembleShortcuts, assertNoShortcutConflicts } from "./shortcuts.js";
 export type { ShortcutConflict, ShortcutDeclaration, ShortcutRegistryResult } from "./shortcuts.js";
 export { backgroundSgrSpan, heldNativeHyperlinkStyle, hyperlinkSgrSpan, hyperlinkTargetAtColumn, nativeHyperlinkStyle, overlaySpan } from "./spans.js";

package/dist/ui/components/index.js

@@ -11,6 +11,7 @@ export { progressStatusText } from "./progress-status.js";
 export { FrameCache, RENDER_REVISION_KINDS, RenderRevisionTracker, ZERO_REVISIONS, normalizeRevisions, revisionsEqual } from "./revision.js";
 export { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyLineContent, selectionCopyRowText } from "./selection-copy.js";
 export { ScrollbarRails, isThumbRow, scrollForThumbRow, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarReservesSpace, scrollbarSelectionRows, scrollbarWheelRows, } from "./scrollbar.js";
+export { renderShortcutHints } from "./shortcut-hints.js";
 export { GLOBAL_SCOPE, ShortcutRegistry, assembleShortcuts, assertNoShortcutConflicts } from "./shortcuts.js";
 export { backgroundSgrSpan, heldNativeHyperlinkStyle, hyperlinkSgrSpan, hyperlinkTargetAtColumn, nativeHyperlinkStyle, overlaySpan } from "./spans.js";
 export { readVisibleHyperlinks } from "./visible-hyperlinks.js";

package/dist/ui/components/shortcut-hints.d.ts

@@ -0,0 +1,7 @@
+import { type SemanticShortcutHint } from "../../contracts/presentation/index.js";
+import type { UiTheme } from "./theme.js";
+export type ShortcutHintEntry = SemanticShortcutHint;
+/** Returns an unstyled modal instruction row for width-aware clipping. */
+export declare function shortcutHintsText(entries: readonly ShortcutHintEntry[], indent?: number): string;
+/** Paints one modal instruction row without decorative separator glyphs. */
+export declare function renderShortcutHints(entries: readonly ShortcutHintEntry[], theme: Pick<UiTheme, "fg">, indent?: number): string;

package/dist/ui/components/shortcut-hints.js

@@ -0,0 +1,12 @@
+import { renderSemanticShortcutHints, } from "../../contracts/presentation/index.js";
+/** Returns an unstyled modal instruction row for width-aware clipping. */
+export function shortcutHintsText(entries, indent = 0) {
+    return renderSemanticShortcutHints(entries, { key: text => text, action: text => text }, indent);
+}
+/** Paints one modal instruction row without decorative separator glyphs. */
+export function renderShortcutHints(entries, theme, indent = 0) {
+    return renderSemanticShortcutHints(entries, {
+        key: text => theme.fg("dim", text),
+        action: text => theme.fg("muted", text),
+    }, indent);
+}

package/dist/ui/components/shortcuts.d.ts

@@ -4,6 +4,7 @@
  * assembled, and any listing is generated from the same declarations — so a
  * listed shortcut is one dispatch would actually invoke.
  */
+import type { ShortcutHintEntry } from "./shortcut-hints.js";
 export interface ShortcutDeclaration {
     /** Key token, for example `up`, `shift+down`, `ctrl+c`, or a literal character. */
     readonly key: string;
@@ -52,6 +53,7 @@ export declare class ShortcutRegistry<Action extends string = string> {
      * the same declarations dispatch reads, so a key cannot be described here and
      * bound to something else, or bound and never mentioned.
      */
+    hintEntries(scope: string): readonly ShortcutHintEntry[];
     hint(scope: string, separator?: string): string;
     /** The listing, derived from the declarations dispatch reads. */
     list(scope?: string): readonly ShortcutDeclaration[];

package/dist/ui/components/shortcuts.js

@@ -60,7 +60,7 @@ export class ShortcutRegistry {
      * the same declarations dispatch reads, so a key cannot be described here and
      * bound to something else, or bound and never mentioned.
      */
-    hint(scope, separator = " · ") {
+    hintEntries(scope) {
         const shown = new Map();
         for (const declaration of this.#declarations) {
             if (declaration.hint === undefined)
@@ -70,7 +70,10 @@ export class ShortcutRegistry {
             if (!shown.has(declaration.hint.keys))
                 shown.set(declaration.hint.keys, declaration.hint.does);
         }
-        return [...shown].map(([keys, does]) => `${keys} ${does}`).join(separator);
+        return Object.freeze([...shown].map(([key, action]) => ({ key, action })));
+    }
+    hint(scope, separator = " · ") {
+        return this.hintEntries(scope).map(({ key, action }) => `${key} ${action}`).join(separator);
     }
     /** The listing, derived from the declarations dispatch reads. */
     list(scope) {

package/dist/ui/components/transcript-viewport.d.ts

@@ -101,7 +101,7 @@ export interface TranscriptViewportFrameDescriptor {
     readonly transientRowCount: number;
     /** Flexible rows inserted before the bottom-aligned live status while content fits. */
     readonly transientAlignmentGapRows: number;
-    /** Live status rows at the end of the transient suffix. */
+    /** Bottom-aligned transient rows. */
     readonly bottomAlignedTailRowCount: number;
     /** Visible rows owned by the currently streaming transcript block. */
     readonly liveTailRows: number;

package/docs/ci-release-runbook.md

@@ -46,7 +46,7 @@ effect of stable publication, not a trigger.
 
 | Trigger | Validation and outcome |
 | --- | --- |
-| Pull request into `develop` | Bounded PR-cadence validation; changed/new source documentation is checked once, rendering runs as `none`, `smoke`, or `full`, and exhaustive owners are reported as deferred |
+| Pull request into `develop` | Bounded PR-cadence validation; changed/new source documentation is checked once, rendering runs as `none`, `smoke`, or `full`, exhaustive owners are reported as deferred, and only a trusted-CI-created failed-Full-regression repair adds PR-attached complete regression |
 | `npm run develop` | Preview package gates on Windows, Linux, and macOS; an existing numbered preview is an early successful no-op |
 | Nightly at `03:17 UTC` | One full documentation review plus the complete non-physical suite on Windows, Linux, and macOS, every night |
 | `npm run release -- ...` | Stamps the requested stable version on the open `develop` source, runs the complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master`; one reopening PR follows |
@@ -60,9 +60,9 @@ effect of stable publication, not a trigger.
 
 Ordinary type, architecture, unit/contract, and dist checks always run for code changes. Changed-file documentation and rendering run as independent parallel jobs. Rendered shell/component changes select `smoke`; viewport, scheduler, terminal adapter, evidence harness, package identity, and selector changes select `full`; unrelated changes select `none`. The aggregate accepts a skipped modular job only when the current selector requested the skip.
 
-Integration owners declare one cadence in `config/integration-owners.json`. Impact mode selects affected `pull-request` owners: a changed production path selects its coarse owner, a changed test selects its owner, and a changed file under `test/support/` or `test/fixtures/` selects the owners of the retained tests that import it directly or through other support files (the selection lists those tests as its `shared-support` reason). A support file that no retained test imports, or a test tree the scanner cannot read, falls back to every owner the shared rule declares and records `shared-support-declared`; an invalidator, unknown operational path, or manual Development dispatch selects every `pull-request` owner. An implementation-bound PR body does not force conservative selection; it only removes the documentation-only and version-only shortcuts. The modular matrix itself is derived from the selection by `scripts/release/validation-matrix.mjs`, so inactive jobs are not scheduled at all rather than checking out and exiting early. `exhaustive` owners are never silently skipped or reported as passed: impact and aggregate evidence list them as cadence-deferred, and malformed cadence blocks selection. Full regression and nightly/stable release still execute both cadence classes.
+Integration owners declare one cadence in `config/integration-owners.json`. Impact mode selects affected `pull-request` owners: a changed production path selects its coarse owner, a changed test selects its owner, and a changed file under `test/support/` or `test/fixtures/` selects the owners of the retained tests that import it directly or through other support files (the selection lists those tests as its `shared-support` reason). A support file that no retained test imports, or a test tree the scanner cannot read, falls back to every owner the shared rule declares and records `shared-support-declared`; an invalidator, unknown operational path, or manual Development dispatch selects every `pull-request` owner. An implementation-bound PR body does not force conservative selection; it only removes the documentation-only and version-only shortcuts. The modular matrix itself is derived from the selection by `scripts/release/validation-matrix.mjs`, so inactive jobs are not scheduled at all rather than checking out and exiting early. `exhaustive` owners are never silently skipped or reported as passed: impact and aggregate evidence list them as cadence-deferred, and malformed cadence blocks selection. Full regression and nightly/stable release still execute both cadence classes. PR-attached Full regression is selected only when base policy verifies an `openspec-ci` App-authored candidate, its generated repair identity, and every qualifying failed Full regression source field in `regression-provenance.json` against GitHub's read-only workflow-run record. Release/publishing, shared-support, prerequisite, build, validation-authority, unknown-path, label, Release-only repair, and successful-run persistent-overrun changes retain bounded ordinary validation. Planning-only generated repair drafts remain exempt; eligible implementation drafts receive native lane feedback without integration authority.
 
-The real three-release `update-predecessor` scenario is exhaustive because four fresh npm installations dominated recent PR critical paths, and `update-performance` is exhaustive because its assertion is wall-clock timing on a shared runner; the update path's deterministic contracts stay on pull requests through `pi-release-resume` and `package-contracts`. PR validation retains deterministic predecessor command, lifecycle, fault, fixture, materialization, warmup, package, and update contracts. This permits a real published-history incompatibility or update slowdown to reach `develop` before the next exhaustive run detects it. `.github/workflows/full-regression.yml` runs every night at `02:47 UTC` against the `develop` tip with every owner and enforced budgets, independent of publication, so such a regression shows as a failed Full regression run the next morning; nightly publication's own complete validation still blocks publication. For a high-risk release/update change, dispatch Full regression before merge instead of adding an exhaustive owner back to ordinary Development.
+The real three-release `update-predecessor` scenario is exhaustive because four fresh npm installations dominated recent PR critical paths, and `update-performance` is exhaustive because its assertion is wall-clock timing on a shared runner; the update path's deterministic contracts stay on pull requests through `pi-release-resume` and `package-contracts`. PR validation retains deterministic predecessor command, lifecycle, fault, fixture, materialization, warmup, package, and update contracts. This permits a real published-history incompatibility or update slowdown to reach `develop` before the next exhaustive run detects it. `.github/workflows/full-regression.yml` runs every night at `02:47 UTC` against the `develop` tip with every owner and enforced budgets, independent of publication, so such a regression shows as a failed Full regression run the next morning; nightly publication's own complete validation still blocks publication. For diagnosis on any other candidate, dispatch standalone Full regression; labels and high-risk release/update impact do not add it to PR checks or change owner cadence.
 
 Development outcomes report each owner/scope invocation separately while sharing authenticated build/package preparation. The aggregate reports setup, scope, job, aggregate-processing, total runner, and runner-critical-path durations. The acceptance targets are at most eight minutes of runner critical path and five minutes for one PR-required scope; an over-target result remains unmet without retries, timeout increases, workload reduction, or mutable installation caches. Hosted queue time is reported separately when available and is not counted as test execution.
 
@@ -106,7 +106,9 @@ node scripts/release/report-resource-sensitive-validation.mjs --repeats 3 --outp
 
 ## Pull request integration
 
-`Development validation required` remains the merge gate for every pull request. For applicable code changes, it requires the dedicated Defender-enabled exact-package startup lane on Windows Node 22. Development validation (including manual dispatch) does not schedule a Windows Node 24 startup lane. The Node 22 lane retains the complete package-install, image preparation/package, and durable-history checks plus startup evidence artifacts. A missing, cancelled, failed, or unexpectedly skipped required startup result still blocks the aggregate; documentation-only, version-only, and draft exemptions are unchanged.
+`Development validation required` remains the merge gate for every pull request. A trusted base-controlled selector binds current PR metadata, merge base, exact head, target, paths (including renamed-from and deleted repair history), and selection identity. When selected, the same PR run calls `.github/workflows/full-regression-shared.yml` and requires Windows 2025 Node 22/24, Ubuntu 24.04 Node 24, and macOS 15 Node 24 plus their exact-run outcome envelopes. Failed, cancelled, missing, stale, mismatched, or unexpectedly skipped work blocks the stable aggregate. Standalone `.github/workflows/full-regression.yml` retains its name, schedule, dispatch, non-cancelling behavior, and non-publishing authority; its result cannot substitute for selected PR evidence.
+
+For applicable code changes, it requires the dedicated Defender-enabled exact-package startup lane on Windows Node 22. Development validation (including manual dispatch) does not schedule a Windows Node 24 startup lane. The Node 22 lane retains the complete package-install, image preparation/package, and durable-history checks plus startup evidence artifacts. A missing, cancelled, failed, or unexpectedly skipped required startup result still blocks the aggregate; documentation-only, version-only, and draft exemptions are unchanged.
 
 | Startup runtime | Development validation (PR or manual) | Development preview (`npm run develop`) | Nightly and stable publication | Manual Full regression |
 | --- | --- | --- | --- | --- |
@@ -115,13 +117,13 @@ node scripts/release/report-resource-sensitive-validation.mjs --repeats 3 --outp
 
 Each selected startup lane runs the package-install scenarios once: a failed budget remains failed and is never retried to obtain a warmed result. The budgets are the ones the `a1-shell` capability declares (2 seconds after an update and on a warm launch, 2.5 seconds with no live supervisor); development validation, development previews, nightly publication, and Full regression record an overrun as a warning and are judged by the three-run persistent-overrun verdict, while stable publication fails on it (see `STARTUP_BUDGET_ENFORCEMENT` in [validation](validation.md)). The publication lane set comes from `scripts/release/publication-validation-matrix.mjs`: a numbered preview validates on the Windows, Linux, and macOS Node 24 lanes, and nightly covers the same head on Windows Node 22 within a day. Node 24 runtime support, other PR jobs, Defender, and publication gates are unchanged. Full validation retains every deferred startup, image, and history test through its existing suite owners.
 
-The trade-off is delayed detection: a Node-24-specific regression can reach `develop` before nightly catches it, and the same is true for a real published-predecessor regression. A green bounded PR check does not certify Node 24 or real historical predecessor execution, and nightly failure still blocks its publication. When deferred feedback is needed before nightly, explicitly request the non-publishing Full regression workflow for the desired branch or tag:
+The trade-off is delayed detection: a Node-24-specific regression can reach `develop` before nightly catches it, and the same is true for a real published-predecessor regression. A green bounded PR check does not certify Node 24 or real historical predecessor execution, and nightly failure still blocks its publication. For an unselected candidate or diagnosis, explicitly request the non-publishing standalone Full regression workflow for the desired branch or tag:
 
 ```sh
 gh workflow run full-regression.yml --ref <branch-or-tag>
 ```
 
-Record the run's resolved source SHA and package evidence; do not substitute an unrelated historical green run for current-head acceptance. This full run is a deliberate additional operation, not an automatic step for every PR.
+Record the run's resolved source SHA and package evidence; do not substitute an unrelated historical green run for current-head acceptance. This standalone run is a deliberate additional operation, not an automatic step for every PR and not selected PR authority.
 
 Documentation auto-merge reads the complete GitHub changed-file response and arms
 squash auto-merge for an eligible pull request while required validation is pending;
@@ -250,7 +252,7 @@ Rules that do not bend:
 
 - **PR validation fails:** fix the code and push; do not mark a failed PR-cadence tier optional. If real predecessor history is needed, run Full regression rather than changing the exhaustive result into PR success.
 - **Nightly startup budget overruns:** a single overrun on Full regression or nightly publication is a warning in the run summary, not a failure; the triage judges the key across the three most recent `develop` runs and opens a `package-startup` candidate only when all three overran. Stable publication still fails on one overrun; rerun it with the measured phases in hand.
-- **Nightly regression fails:** the triage workflow opens or refreshes a draft `fix/nightly-regression-<date>` pull request whose body and change carry the evidence; start the fix there. Reproduce from the listed tests or commands on the failed lane, fix without weakening assertions, budgets, timeouts, or coverage, then dispatch `gh workflow run full-regression.yml --ref fix/nightly-regression-<date>` on the completed fix head and record the run in the change's design evidence before hand-off; ordinary PR validation does not run the exhaustive owners the nightly failed on. A day whose failed scope set differs from every open candidate opens a new one. A Full regression dispatched on a candidate's own branch is that candidate's proof; its failures never open another candidate. A failure with no candidate means the triage workflow itself failed; read its run summary and dispatch it with the failed run id and `dry_run` off.
+- **Nightly regression fails:** the triage workflow opens or refreshes a draft `fix/nightly-regression-<date>` pull request whose body and change carry the evidence and whose `regression-provenance.json` binds the source run; start the fix there. A failed Full regression source created by `openspec-ci` selects PR-attached Full regression, while a Release-only failure or successful-run persistent overrun retains ordinary PR validation. Reproduce from the listed tests or commands on the failed lane and fix without weakening assertions, budgets, timeouts, or coverage. Record focused implementation evidence and pre-finalization observations in the change, then require `Development validation required` and, when selected, PR-attached Full regression on the finalized exact head. Put final run/head/selection in Actions and handoff rather than making another evidence-recording commit. Standalone dispatch remains diagnostic; numbered-package nightly recovery is independent. A day whose failed scope set differs from every open candidate opens a new one. A Full regression dispatched on a candidate's own branch is that candidate's proof but never selected PR authority; its failures never open another candidate. A failure with no candidate means the triage workflow itself failed; read its run summary and dispatch it with the failed run id and `dry_run` off.
 - **Nightly exhaustive predecessor validation fails:** treat the focused PR result as insufficient, keep publication blocked, and repair the incompatibility without reducing predecessor count, timeouts, or exact-package isolation.
 - **Documentation auto-merge fails:** leave the pull request open, inspect its exact
   changed-file classification, docs-sensitive inventory, and workflow permissions,

package/docs/openspec-archive-automation.md

@@ -17,6 +17,12 @@ Version-1 and version-2 deliveries and their existing comments, acceptance PRs,
 7. **Manual merge accepts:** after the stable protected aggregate succeeds, an authorized human reviews and manually merges the exact validated head. That single action means the listed scenarios are accepted and explicitly authorizes integration. Auto-merge, merge queue, Apps, bots, and documentation reconciliation are forbidden.
 8. **Verify and clean:** trusted post-merge policy derives `Archived` and reports `accepted-and-archived` from committed bytes and immutable GitHub provenance without editing the accepted PR body. It publishes no lifecycle branch or PR. Shared exact-head remote cleanup may delete the unchanged topic ref; local cleanup remains separately ownership-controlled: the agent parks the worktree with `handoff` at step 7, and the next session's `sweep` removes it once the merge, archive, and remote-ref evidence verify (see [local cleanup](local-worktree-cleanup.md)).
 
+### Complete-regression evidence ordering
+
+PR-attached Full regression is selected only for a repair that the trusted triage created from a failed Full regression: base policy verifies the immutable `openspec-ci` App author, generated candidate identity, and `regression-provenance.json`. Human-authored lookalikes, publishing or validation-authority changes, labels, Release-only repairs, and successful-run persistent-overrun candidates retain bounded ordinary validation. Planning-only generated repair drafts remain lightweight. Eligible implementation drafts expose all four native lane checks without becoming mergeable. Finish substantive implementation tasks, focused evidence, pre-finalization observations, and known-gap disposition before marking ready. The finalized head then receives new full evidence, required by `Development validation required` alongside the existing gates.
+
+The final exact-head run is a handoff gate, not a task requiring a future run ID in committed `design.md`. Keep final head/run/selection identity in Actions outcomes and the maintainer handoff; do not invalidate successful evidence with an extra recording commit. Changed code, acceptance/body metadata, selection labels, or target baseline requires fresh evidence. A selected PR success removes the additional mandatory Full regression dispatch, but a standalone/manual run never substitutes for selected PR checks. Before deployment, existing separate-dispatch obligations remain. Neither PR validation nor manual regression proves numbered-package nightly publication recovery.
+
 The implementation, synchronized canonical specs, conditional acceptance record, and archive therefore reach `develop` atomically. Closing the PR unmerged integrates none of them.
 
 ## Draft PR body