@visual-z/xeno 0.5.0 → 0.7.0

package/src/apps/ui/app.ts

@@ -29,6 +29,7 @@ import { DISPLAY_SETTINGS, settingValue, settingValues } from "../../core/settin
 import { THINKING_LEVELS, asThinkingLevel, supportedThinkingLevels } from "../../core/thinking.ts";
 import { builtinTheme } from "../../core/theme.ts";
 import { projectTranscript, type TranscriptItem } from "../../core/transcript.ts";
+import { DEFAULT_FULLSCREEN_EXIT_OUTPUT, sessionExitStatus } from "../../core/session-exit.ts";
 import { lastAssistantText } from "../../core/export.ts";
 import type { PermissionRequest } from "../../core/permissions.ts";
 import type { ApprovalChoice } from "../../runtime/tools.ts";
@@ -38,14 +39,16 @@ import { highlightCode, transformMermaid, warmSyntaxLanguages } from "../../runt
 import { SOURCE_PROVIDERS } from "../../runtime/model-data.ts";
 import { SUBSCRIPTION_OPTIONS, subscriptionById, loginGitHubCopilot, startCallbackServer, XENO_VERSION } from "../../runtime/oauth.ts";
 import { reportedCost } from "../../runtime/usage.ts";
-import { fetchLatestVersion } from "../../runtime/update-check.ts";
-import { installKind, updateNotice, updatePlan } from "../../core/update-check.ts";
+import { UpdateChecks } from "../update-check.ts";
+import { updateNotice } from "../../core/update-check.ts";
 import { isUpgrade } from "../../core/version.ts";
-import { packageLocation, readUpdateCache, writeUpdateCache } from "../../store/update-cache.ts";
 import type { Effort } from "../../runtime/model.ts";
 import { readNode, readCursor, setSessionLabel } from "../../store/log.ts";
 import { readNodeHistory } from "../../store/restore.ts";
-import { currentBranch } from "../../store/git-branch.ts";
+import { readGitStatus } from "../../store/git-status.ts";
+import type { GitStatus } from "../../core/git-status.ts";
+import { activityStatus } from "../../core/activity-status.ts";
+import { executionOutcome, type ExecutionOutcome } from "../../core/outcome.ts";
 import { projectTrust } from "../../store/trust.ts";
 import { discoverResources, setResourceOverride } from "../../store/resource-index.ts";
 import { nextResourceOverride } from "../../core/resource-selection.ts";
@@ -108,6 +111,11 @@ function samePalette(a: TerminalPalette, b: TerminalPalette | null): boolean {
   return b !== null && a.foreground === b.foreground && a.background === b.background && a.slots.every((slot, i) => slot === b.slots[i]);
 }
 
+/** Only the endpoint host is chrome; credentials, query and path stay out of it. */
+function endpointHost(baseUrl: string | undefined): string | null {
+  try { return baseUrl ? new URL(baseUrl).host : null; } catch { return null; }
+}
+
 export class InteractiveApp implements Ui {
   readonly app: App;
   readonly screen: Screen;
@@ -142,6 +150,11 @@ export class InteractiveApp implements Ui {
   private retryTimer: ReturnType<typeof setInterval> | undefined;
   private bashDecoder = new TextDecoder();
   private branch: string | null;
+  private git: GitStatus | null = null;
+  private gitRun: Promise<void> | undefined;
+  private gitAgain = false;
+  private attention: ControlSnapshot["waiting"] = null;
+  private lastOutcome: ExecutionOutcome | undefined;
   private paintTimer: ReturnType<typeof setTimeout> | undefined;
   /** Handoff-derived status (sidebar / top bar), refreshed single-flight and debounced (DoD 9). */
   private derived: ReturnType<typeof handoffStatus> | undefined;
@@ -178,8 +191,9 @@ export class InteractiveApp implements Ui {
   };
   /** Decoded pictures shared by every node that shows them (feat-tui-inline-images). */
   private readonly images = new ImageCache(() => this.app.blobDir);
-  /** The background update check's request, aborted on close so quitting never waits on the registry. */
-  private readonly updateRequest = new AbortController();
+  /** Shared update requests are aborted on close so quitting never waits on the registry. */
+  private readonly updateChecks = new UpdateChecks();
+  private manualUpdateRequested = false;
   /** The terminal finished answering capability queries: picture support may have changed. */
   private readonly capabilitiesChanged = (): void => this.applyPictures();
   /** What the terminal reported (OSC 4/10/11); null until it answers, or forever if it never does. */
@@ -211,7 +225,7 @@ export class InteractiveApp implements Ui {
     this.program = program;
     this.stopOsc = program ? renderer.subscribeOsc(sequence => program.receive(sequence)) : undefined;
     this.closed = new Promise(resolve => { this.closedResolve = resolve; });
-    this.branch = currentBranch(app.workspace);
+    this.branch = null;
     this.sessionName = app.args.sessionName || null;
     this.thinkingExpanded = app.ui?.settings.hideThinkingBlock === false;
     this.screen = new Screen(renderer, this.colors(), () => this.keymap().byAction, {
@@ -325,7 +339,7 @@ export class InteractiveApp implements Ui {
     this.requestDerived();
     this.paint(true);
     // Never awaited: startup and exit do not wait on the network (feat-update-check DoD 3).
-    void this.checkForUpdate();
+    void this.checkForUpdateOnStartup();
   }
 
   /**
@@ -334,25 +348,24 @@ export class InteractiveApp implements Ui {
    * and is shown now only while the session is still empty, so it never
    * interrupts work. xeno names the update command and never runs it.
    */
-  private async checkForUpdate(): Promise<void> {
+  private async checkForUpdateOnStartup(): Promise<void> {
     try {
-      const location = packageLocation();
-      const install = installKind(location.root, location.git);
-      const cache = await readUpdateCache();
-      const plan = updatePlan({ current: XENO_VERSION, now: Date.now(), cache, env: process.env, offline: this.app.args.offline === true,
-        enabled: this.app.ui?.settings.updateCheck, install });
-      if (plan.notice && !this.disposed && !this.inflight) this.notice(plan.notice);
-      if (!plan.check) return;
-      const latest = await fetchLatestVersion(process.env["npm_config_registry"], { signal: this.updateRequest.signal });
-      // Quitting cut the request short: that is no answer, so the next start asks again.
-      if (this.disposed) return;
-      // A failed attempt is recorded too, so a closed network is not retried on every start.
-      const known = latest ?? cache?.latest;
-      await writeUpdateCache({ checkedAt: Date.now(), ...(known ? { latest: known } : {}) });
-      if (!plan.notice && latest && isUpgrade(latest, XENO_VERSION) && this.emptySession()) this.notice(updateNotice(latest, XENO_VERSION, install));
+      const { input, plan } = await this.updateChecks.prepare({ offline: this.app.args.offline === true, enabled: this.app.ui?.settings.updateCheck });
+      if (plan.notice && !this.manualUpdateRequested && !this.disposed && !this.inflight) this.notice(plan.notice);
+      if (!plan.check || this.manualUpdateRequested) return;
+      const latest = await this.updateChecks.refresh(input);
+      if (!this.manualUpdateRequested && !plan.notice && latest && isUpgrade(latest, XENO_VERSION) && this.emptySession()) this.notice(updateNotice(latest, XENO_VERSION, input.install));
     } catch { /* an update hint is never worth an error */ }
   }
 
+  checkForUpdate(): void {
+    // The explicit action owns its result even when it joins a startup request.
+    this.manualUpdateRequested = true;
+    void this.updateChecks.manual({ offline: this.app.args.offline === true }, text => {
+      if (!this.disposed) this.notice(text);
+    }).catch(() => { if (!this.disposed) this.notice("Could not check for xeno updates. Try /update again.", "error"); });
+  }
+
   private emptySession(): boolean {
     return !this.disposed && !this.inflight && !this.transcriptItems.some(item => item.kind === "user" || item.kind === "assistant" || item.kind === "tool" || item.kind === "shell");
   }
@@ -394,7 +407,7 @@ export class InteractiveApp implements Ui {
     this.renderer.off("palette", this.paletteChanged);
     this.renderer.off("selection", this.selectionFinished);
     this.renderer.off("capabilities", this.capabilitiesChanged);
-    this.updateRequest.abort();
+    this.updateChecks.cancel();
     this.images.dispose();
     this.screen.dispose();
     delete this.app.askSlot.current;
@@ -418,7 +431,7 @@ export class InteractiveApp implements Ui {
         // A different session: its notices, queue and draft attachments do not carry over.
         if (this.historyDir) { this.notices = []; this.queue = []; this.imageDraft.reset(); this.screen.dialogs.clear(); }
         this.clearStream();
-        this.branch = currentBranch(this.app.workspace);
+        void this.refreshGit();
         this.sessionName = (await readCursor(dir))?.name ?? this.sessionName;
         this.thinkingExpanded = this.app.ui?.settings.hideThinkingBlock === false;
         void this.refreshFileIndex();
@@ -459,7 +472,8 @@ export class InteractiveApp implements Ui {
     } else {
       this.stopRetry();
       if (progress.kind === "tool") this.live.tools.set(progress.id, { name: progress.name, arguments: progress.arguments });
-      else this.live.output = `${this.live.output}${progress.text}`.slice(-64 * 1024);
+      else if (progress.kind === "output") this.live.output = `${this.live.output}${progress.text}`.slice(-64 * 1024);
+      else this.live.output = progress.active ? `Waiting for process ${progress.session} · Esc to interrupt` : "";
     }
     this.paint();
   }
@@ -543,9 +557,19 @@ export class InteractiveApp implements Ui {
     const t = app.session.totals, cost = reportedCost(t, spec.price);
     const tools = items.filter(item => item.kind === "tool");
     const extension = [this.extensions.status, app.credential.ok ? "" : "no provider · /provider"].filter(Boolean).join(" · ");
+    const pending = tools.find(tool => tool.status === "pending");
+    const phase = this.executionKind === "bash" || pending ? "tool" : this.live.text ? "streaming" : this.live.thinking ? "thinking" : "connecting";
+    const activity = activityStatus({ running: this.inflight, waiting: this.attention ?? (!app.credential.ok ? "auth" : null), queued: this.queue.length, phase,
+      ...(pending ? { tool: pending.name } : this.executionKind === "bash" ? { tool: "bash" } : {}),
+      ...(this.lastOutcome ? { outcome: this.lastOutcome } : this.controlSnapshot?.goal?.state.execution ? { outcome: this.controlSnapshot.goal.state.execution } : {}),
+      ...(this.controlSnapshot?.goal ? { goal: this.controlSnapshot.goal.state.status } : {}),
+      ...(this.live.retryUntil ? { retry: { attempt: this.live.retryAttempt, seconds: (this.live.retryUntil - Date.now()) / 1000 } } : {}) });
     return {
       version: XENO_VERSION, title: this.sessionName ?? this.prompt, workspace: displayPath(app.workspace, homedir()),
       workspaceShort: shortPath(displayPath(app.workspace, homedir())), branch: this.branch,
+      mode: { yolo: app.args.yolo, workflow: app.session.config.tools.workflowMode ?? "build" },
+      provider: { name: spec.provider, api: spec.api, host: endpointHost(spec.baseUrl), role: app.args.role?.profile.name ?? app.args.agent ?? null, ready: app.credential.ok },
+      activity, git: this.git,
       ...(budget ? { context: { used: budget.used, trigger: budget.trigger, estimated: budget.estimated, segment: app.session.state.node, ...(spec.contextWindow ? { window: spec.contextWindow } : {}) } } : {}),
       ...(t.requests ? { usage: { input: t.prompt_tokens, output: t.output_tokens, cacheRate: t.cache_hit_rate,
         // Under half a cent reads as $0.00, which says nothing (OpenCode #15903; Grok's status line hides it the same way).
@@ -569,6 +593,18 @@ export class InteractiveApp implements Ui {
     this.renderer.setTerminalTitle(title);
   }
 
+  private async refreshGit(): Promise<void> {
+    if (this.disposed) return;
+    if (this.gitRun) { this.gitAgain = true; return; }
+    const workspace = this.app.workspace;
+    this.gitRun = (async () => {
+      const status = await readGitStatus(workspace);
+      if (!this.disposed && this.app.workspace === workspace) { this.git = status; this.branch = status?.branch ?? null; this.paint(); }
+    })();
+    try { await this.gitRun; }
+    finally { this.gitRun = undefined; if (this.gitAgain) { this.gitAgain = false; void this.refreshGit(); } }
+  }
+
   private liveStream(): LiveStream | undefined {
     const l = this.live;
     if (!l.thinking && !l.text && !l.tools.size && !l.output && l.bash === null && !l.retryUntil) return undefined;
@@ -794,7 +830,8 @@ export class InteractiveApp implements Ui {
     const shell = command.text.startsWith("!");
     const images = shell ? [] : input.images;
     if (shell) this.imageDraft.insertImages(input.images);
-    if (this.inflight) { this.queue.push({ kind: shell ? "followup" : kind, text: command.text, ...(images.length ? { images } : {}) }); this.paint(); return; }
+    if (this.inflight) { this.queue.push({ kind: shell ? "followup" : kind, text: command.text, ...(images.length ? { images } : {}) });
+      if (!shell && kind === "steering") this.app.session.wakeProcessWaits(); this.paint(); return; }
     this.turn = this.runPromptTurn(command.text, images, command.skill).catch(error => this.notice(describeError(error), "error"));
     this.paint();
   }
@@ -802,6 +839,7 @@ export class InteractiveApp implements Ui {
   private async runPromptTurn(text: string, images: readonly ImageRef[] = [], skill?: import("../../core/skills.ts").Skill): Promise<void> {
     this.abort = new AbortController();
     this.inflight = true;
+    this.lastOutcome = undefined;
     this.programResult = false;
     this.program?.update(programStatus({ running: true }));
     this.executionKind = text.startsWith("!") ? "bash" : "model";
@@ -814,16 +852,18 @@ export class InteractiveApp implements Ui {
       if (sent && !this.abort.signal.aborted) await this.drainFollowUps();
     } catch (error) {
       this.programResult = true;
+      this.lastOutcome = executionOutcome("execution_error");
       this.program?.update({ state: "error", msg: "Turn failed; inspect the session" });
       throw error;
     } finally {
+      if (this.abort?.signal.aborted && !this.lastOutcome) this.lastOutcome = executionOutcome("cancelled");
       if (!this.programResult) this.program?.update(programStatus({ running: false }));
       await this.syncTranscript();
       this.abort = null;
       this.hooks.dropFileIndex(this.app.workspace);
       this.inflight = false;
       this.executionKind = "idle";
-      this.branch = currentBranch(this.app.workspace);
+      void this.refreshGit();
       this.clearStream();
       this.requestDerived();
       this.paint();
@@ -955,7 +995,7 @@ export class InteractiveApp implements Ui {
     this.runExtensionAction(async () => { try { await action(); } finally { this.sessionTransition = false; } });
   }
   deliverExtension(text: string, kind: QueueKind): void {
-    if (this.inflight) { this.queue.push({ kind, text }); this.paint(); }
+    if (this.inflight) { this.queue.push({ kind, text }); if (kind === "steering") this.app.session.wakeProcessWaits(); this.paint(); }
     else this.turn = this.runPromptTurn(text).catch(error => this.notice(describeError(error), "error"));
   }
 
@@ -994,10 +1034,12 @@ export class InteractiveApp implements Ui {
     const requested = terminal?.imageProtocol ?? "auto";
     const resolution = this.renderer.resolution;
     const effective = resolveImageRenderProtocol(requested, this.renderer.capabilities, resolution !== null);
-    const show = terminal?.showImages !== false && (requested !== "auto" || effective !== "blocks");
+    const show = terminal?.showImages !== false && effective !== "blocks";
+    const reason = terminal?.showImages === false ? "preview off" : requested === "sixel" && resolution === null ? "waiting for terminal resolution" : "terminal graphics unavailable";
     const cell = resolution && this.renderer.terminalWidth > 0 && this.renderer.terminalHeight > 0
       ? { width: resolution.width / this.renderer.terminalWidth, height: resolution.height / this.renderer.terminalHeight } : DEFAULT_CELL;
-    return { mode: show ? "picture" : "chip", protocol: requested, cell, widthCells: terminal?.imageWidthCells ?? 60, load: sha => this.images.load(sha) };
+    return { mode: show ? "picture" : "chip", protocol: effective, cell, widthCells: terminal?.imageWidthCells ?? 60,
+      ...(!show ? { reason } : {}), load: sha => this.images.loadResult(sha) };
   }
   private applyPictures(): void {
     if (this.disposed) return;
@@ -1047,18 +1089,23 @@ export class InteractiveApp implements Ui {
     const control = sessionControl(this.app.session);
     if (this.control === control) return;
     this.stopControl?.(); this.control = control; this.controlSnapshot = undefined;
+    this.attention = null; this.lastOutcome = undefined;
     this.screen.setControlModel(undefined);
     const detachInput = control.attachInput(phase => this.pullQueued(phase));
     const unsubscribe = control.subscribe(notice => {
       if (this.disposed) return;
-      if (notice.method === "turn/started") this.program?.update(programStatus({ running: true }));
+      if (notice.method === "turn/started") { this.lastOutcome = undefined; this.program?.update(programStatus({ running: true })); }
       if (notice.method === "turn/error") {
+        this.lastOutcome = executionOutcome("execution_error");
         this.programResult = true; this.program?.update({ state: "error", msg: "Turn failed; inspect the session" });
         this.track(() => this.syncTranscript());
       }
       if (notice.method === "approval/request") this.program?.update(programStatus({ running: true, waiting: "permission" }));
-      if (notice.method === "thread/statusChanged" && "waiting" in notice.params)
+      if (notice.method === "thread/statusChanged" && "waiting" in notice.params) {
+        this.attention = notice.params["waiting"] as ControlSnapshot["waiting"];
         this.program?.update(programStatus({ running: control.busy, waiting: notice.params["waiting"] as ControlSnapshot["waiting"] }));
+      }
+      if (notice.method === "turn/completed") this.lastOutcome = notice.params["outcome"] as ExecutionOutcome | undefined;
       // A remote client drives the same Session; local turns already have the shell's stream adapter.
       if (!this.abort) {
         if (notice.method === "turn/started") { this.inflight = true; this.executionKind = "model"; }
@@ -1094,6 +1141,7 @@ export class InteractiveApp implements Ui {
   }
 
   observeEvent(event: import("../../runtime/loop.ts").LoopEvent): void {
+    if (event.outcome) this.lastOutcome = event.outcome;
     if (event.kind === "done" || event.kind === "stop_and_ask") this.programResult = true;
     if (event.kind === "done") this.program?.update(programStatus({ running: false,
       ...(event.outcome ? { outcome: event.outcome } : {}), ...(event.request ? { goal: event.request.status } : {}) }));
@@ -1502,20 +1550,23 @@ export async function runInteractive(app: App, hooks: Hooks, releaseEarlyTty?: (
       app.io.say = previousSay;
       process.off("SIGTERM", terminate); process.off("SIGHUP", hangup); process.off("uncaughtException", crash); process.off("unhandledRejection", crash); process.off("exit", lastResort);
     }
-    if (!renderer && fullscreen) printExit(app);
+    if (!renderer && fullscreen) await printExit(app);
   }
 }
 
-/** After leaving the alternate screen: the conversation as plain text, then how to come back. */
-function printExit(app: App): void {
-  const mode = app.ui?.settings.fullscreenExitOutput ?? "transcript";
+/** Restore the shell with a bounded status and resume entry; full replay is explicit. */
+async function printExit(app: App): Promise<void> {
+  const history = await readNodeHistory(app.logDir, app.session.state.node);
+  const events = history.ok ? history.nodes.flatMap(part => part.events) : app.session.state.events;
+  const mode = app.ui?.settings.fullscreenExitOutput ?? DEFAULT_FULLSCREEN_EXIT_OUTPUT;
   if (mode === "transcript") {
-    for (const item of projectTranscript(app.session.state.events)) {
+    for (const item of projectTranscript(events)) {
       if (item.kind === "user") process.stdout.write(`\n❯ ${item.text}\n`);
       else if (item.kind === "assistant") process.stdout.write(`\n${item.text}\n`);
       else if (item.kind === "tool") process.stdout.write(`  ⏺ ${item.name}${item.result ? item.result.ok ? "" : " (failed)" : " (pending)"}\n`);
     }
   }
+  process.stdout.write(`\n  ${history.ok ? sessionExitStatus(events) : "session saved · history unavailable; inspect before continuing"}\n`);
   process.stdout.write(`\n  resume with: xeno --session ${JSON.stringify(app.logDir)}\n`);
 }
 

package/src/apps/ui/image-cache.ts

@@ -8,20 +8,28 @@
  * its pixels, and memory is returned once the last node goes.
  *
  * Bytes come from the blob store, which checks the hash; a missing or
- * corrupt blob, or one that will not decode, resolves to null and the view
- * names the picture instead of drawing it.
+ * corrupt blob, or one that will not decode, has a typed failure so the view
+ * retains the caption and shows the actual preparation error.
  */
-import { NativeImage } from "@opentui/core";
+import { NativeImage, imageInfo } from "@opentui/core";
 import { getBlobBytes } from "../../store/blobs.ts";
+import { modelImageDimensions, MAX_IMAGE_SOURCE_BYTES, MAX_IMAGE_SOURCE_PIXELS } from "../../core/image-limits.ts";
+import type { PictureLoad } from "../../tui/ui/pictures.ts";
 
-/** Decoded RGBA kept for reuse. 64 MiB is in line with Grok's and pi's image budgets; assumed, not measured here. */
+/** Two full previews fit; mounted ImageRenderables retain their own references. */
 export const IMAGE_CACHE_BYTES = 64 * 1024 * 1024;
-
-interface Entry { readonly image: Promise<NativeImage | null>; bytes: number }
+/** Bounds failed entries and queued requests as well as successful pixels. */
+export const IMAGE_CACHE_ENTRIES = 128;
+/** Limit simultaneous native allocations; remaining admitted loads wait in the bounded cache. */
+const IMAGE_DECODE_CONCURRENCY = 2;
+interface Entry { readonly result: Promise<PictureLoad>; bytes: number; settled: boolean }
 
 export class ImageCache {
   private readonly entries = new Map<string, Entry>();
   private used = 0;
+  private active = 0;
+  private closed = false;
+  private readonly waiting: (() => void)[] = [];
   private readonly blobDir: () => string;
   private readonly budget: number;
 
@@ -34,45 +42,80 @@ export class ImageCache {
   get size(): number { return this.used; }
   get count(): number { return this.entries.size; }
 
-  load(sha256: string): Promise<NativeImage | null> {
+  async load(sha256: string): Promise<NativeImage | null> {
+    const result = await this.loadResult(sha256);
+    return result.kind === "ready" ? result.image : null;
+  }
+
+  loadResult(sha256: string): Promise<PictureLoad> {
+    if (this.closed) return Promise.resolve({ kind: "error", reason: "closed" });
     const hit = this.entries.get(sha256);
     if (hit) {
       // Most recently used goes last; eviction starts from the front.
       this.entries.delete(sha256); this.entries.set(sha256, hit);
-      return hit.image;
+      return hit.result;
     }
-    const entry: Entry = { image: this.decode(sha256), bytes: 0 };
+    if (this.entries.size >= IMAGE_CACHE_ENTRIES) {
+      const oldest = [...this.entries].find(([, entry]) => entry.settled);
+      if (oldest) this.drop(oldest[0], oldest[1]);
+      else return Promise.resolve({ kind: "error", reason: "busy" });
+    }
+    // Capture the blob owner before awaiting: session switches cannot redirect an in-flight read.
+    const entry: Entry = { result: this.decode(this.blobDir(), sha256), bytes: 0, settled: false };
     this.entries.set(sha256, entry);
-    void entry.image.then(native => {
-      if (this.entries.get(sha256) !== entry) return;
-      entry.bytes = native ? native.width * native.height * 4 : 0;
+    void entry.result.then(result => {
+      entry.settled = true;
+      if (this.entries.get(sha256) !== entry) { if (result.kind === "ready") result.image.dispose(); return; }
+      entry.bytes = result.kind === "ready" ? result.image.width * result.image.height * 4 : 0;
       this.used += entry.bytes;
-      this.evict(sha256);
+      for (const [sha, old] of this.entries) {
+        if (this.used <= this.budget) break;
+        if (sha !== sha256 && old.settled) this.drop(sha, old);
+      }
     });
-    return entry.image;
+    return entry.result;
   }
 
-  private async decode(sha256: string): Promise<NativeImage | null> {
+  private async decode(dir: string, sha: string): Promise<PictureLoad> {
+    if (this.active >= IMAGE_DECODE_CONCURRENCY) await new Promise<void>(resolve => this.waiting.push(resolve));
+    else this.active++;
+    if (this.closed) return { kind: "error", reason: "closed" };
+    let native: NativeImage | undefined;
     try {
-      const bytes = await getBlobBytes(this.blobDir(), sha256);
-      return bytes ? await NativeImage.load(bytes) : null;
-    } catch { return null; }
+      let bytes: Uint8Array | null;
+      try { bytes = await getBlobBytes(dir, sha, MAX_IMAGE_SOURCE_BYTES); }
+      catch (error) { return { kind: "error", reason: error instanceof RangeError ? "limit" : "corrupt" }; }
+      if (!bytes) return { kind: "error", reason: "missing" };
+      if (bytes.length > MAX_IMAGE_SOURCE_BYTES) return { kind: "error", reason: "limit" };
+      const info = imageInfo(bytes);
+      if (info.width * info.height > MAX_IMAGE_SOURCE_PIXELS) return { kind: "error", reason: "limit" };
+      native = await NativeImage.load(bytes);
+      const target = modelImageDimensions(native);
+      if (target.width !== native.width || target.height !== native.height) {
+        const resized = native.resize(target); native.dispose(); native = resized;
+      }
+      if (this.closed) return { kind: "error", reason: "closed" };
+      if (native.width * native.height * 4 > this.budget) return { kind: "error", reason: "limit" };
+      const image = native; native = undefined;
+      return { kind: "ready", image };
+    } catch { return { kind: "error", reason: "decode" }; }
+    finally {
+      native?.dispose();
+      const next = this.waiting.shift();
+      if (next) next(); else this.active--;
+    }
   }
 
-  /** Drop least recently used entries until the budget holds, never the one just loaded. */
-  private evict(keep: string): void {
-    for (const [sha, entry] of this.entries) {
-      if (this.used <= this.budget) break;
-      if (sha === keep) continue;
-      this.entries.delete(sha);
-      this.used -= entry.bytes;
-      void entry.image.then(native => native?.dispose());
-    }
+  private drop(sha: string, entry: Entry): void {
+    this.entries.delete(sha); this.used -= entry.bytes;
+    void entry.result.then(result => { if (result.kind === "ready") result.image.dispose(); });
   }
 
   dispose(): void {
-    for (const entry of this.entries.values()) void entry.image.then(native => native?.dispose());
+    this.closed = true;
+    for (const entry of this.entries.values()) if (entry.settled) void entry.result.then(result => { if (result.kind === "ready") result.image.dispose(); });
     this.entries.clear();
     this.used = 0;
+    this.waiting.splice(0).forEach(resolve => resolve());
   }
 }

package/src/apps/ui/surface.ts

@@ -34,6 +34,7 @@ export interface Ui extends TurnSurface {
   /** Notices and documents in the message stream. */
   notice(text: string, tone?: "info" | "success" | "warning" | "error"): void;
   showDocument(title: string, text: string): void;
+  checkForUpdate(): void;
   toast(text: string, tone?: "info" | "success" | "warning" | "error"): void;
   redraw(): void;
 

package/src/apps/update-check.ts

@@ -0,0 +1,71 @@
+/** Shared lifecycle for automatic hints and explicit checks; policy remains in core (D16). */
+import { installKind, manualUpdateResult, updateDisabled, updatePlan, type UpdateInput } from "../core/update-check.ts";
+import { packageLocation, readUpdateCache, writeUpdateCache } from "../store/update-cache.ts";
+import { fetchLatestVersion } from "../runtime/update-check.ts";
+import { XENO_VERSION } from "../runtime/oauth.ts";
+
+export interface UpdateOptions {
+  readonly offline?: boolean;
+  readonly enabled?: boolean | undefined;
+}
+
+export class UpdateChecks {
+  private readonly controller = new AbortController();
+  private pending: Promise<string | null> | undefined;
+  private manualTask: Promise<number> | undefined;
+
+  async prepare(options: UpdateOptions, manual = false) {
+    const location = packageLocation();
+    const input: UpdateInput = { current: XENO_VERSION, now: Date.now(), cache: await readUpdateCache(), env: process.env,
+      offline: options.offline === true, enabled: options.enabled, install: installKind(location.root, location.git), manual };
+    return { input, plan: updatePlan(input), disabled: updateDisabled(input) };
+  }
+
+  /** One request and one cache write even when a manual check joins startup's request. */
+  refresh(input: UpdateInput): Promise<string | null> {
+    if (this.pending) return this.pending;
+    const pending = (async () => {
+      const latest = await fetchLatestVersion(input.env["npm_config_registry"], { signal: this.controller.signal });
+      if (!this.controller.signal.aborted) {
+        const known = latest ?? input.cache?.latest;
+        await writeUpdateCache({ checkedAt: Date.now(), ...(known ? { latest: known } : {}) });
+      }
+      return latest;
+    })().finally(() => { if (this.pending === pending) this.pending = undefined; });
+    this.pending = pending;
+    return pending;
+  }
+
+  manual(options: UpdateOptions, say: (text: string) => void): Promise<number> {
+    if (this.manualTask) return this.manualTask;
+    const task = this.runManual(options, say).finally(() => { if (this.manualTask === task) this.manualTask = undefined; });
+    this.manualTask = task;
+    return task;
+  }
+
+  private async runManual(options: UpdateOptions, say: (text: string) => void): Promise<number> {
+    const { input, plan, disabled } = await this.prepare(options, true);
+    if (this.controller.signal.aborted) return 130;
+    if (!plan.check) {
+      say(input.install === "checkout" ? `Source checkout: xeno ${input.current}. Use git pull to update this checkout.`
+        : `Update check skipped: ${disabled ?? "check unavailable"} (xeno ${input.current}).`);
+      return input.install === "checkout" ? 0 : 1;
+    }
+    say(`Checking for xeno updates (current ${input.current})...`);
+    const latest = await this.refresh(input);
+    if (this.controller.signal.aborted) return 130;
+    const result = manualUpdateResult(latest, input.current, input.install);
+    say(result.text);
+    return result.status === "failed" ? 1 : 0;
+  }
+
+  cancel(): void { this.controller.abort(); }
+}
+
+/** A standalone command has no UI lifecycle to own cancellation. */
+export async function runManualUpdate(options: UpdateOptions, say: (text: string) => void): Promise<number> {
+  const checks = new UpdateChecks(), cancel = () => checks.cancel();
+  process.once("SIGINT", cancel); process.once("SIGTERM", cancel);
+  try { return await checks.manual(options, say); }
+  finally { checks.cancel(); process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
+}

package/src/apps/workflow.ts

@@ -0,0 +1,58 @@
+/** D5/D6: the app changes capabilities only through the live session's checkpoint owner. */
+import { isWorkflowMode, workflowInstructions, type WorkflowMode } from "../core/workflow-mode.ts";
+import { sessionControl } from "../runtime/session-control.ts";
+import { sessionToolCatalog, type App } from "./startup.ts";
+
+export type WorkflowApp = Pick<App, "args" | "session" | "extensions" | "system">;
+
+export async function setAppWorkflow(app: WorkflowApp, mode: WorkflowMode): Promise<boolean> {
+  if (!isWorkflowMode(mode)) throw Error("workflow mode must be build or plan");
+  const session = app.session, previousMode = session.config.tools.workflowMode;
+  const current = previousMode ?? app.args.workflow ?? "build";
+  return sessionControl(session).withIdleChange(async () => {
+    const previousProfile = session.config.agentProfile, name = previousProfile?.name ?? app.args.agent;
+    const nextProfile = name ? { name, workflowExplicit: true } : undefined;
+    const args = structuredClone(app.args), previousScope = session.config.workflowToolProfile;
+    const promote = mode === "plan" && args.tools === undefined && !args.noTools && args.toolProfile === undefined;
+    if (promote) args.toolProfile = "foundation";
+    const nextScope = args.toolProfile === "foundation" ? "foundation" as const : undefined;
+    const metadataChanged = JSON.stringify(previousProfile) !== JSON.stringify(nextProfile) || previousScope !== nextScope;
+    if (mode === current && !metadataChanged && !promote) {
+      app.args.workflow = mode; app.args.cliFlags = [...new Set([...app.args.cliFlags ?? [], "--workflow"])];
+      return false;
+    }
+    const oldInstruction = workflowInstructions(current), nextInstruction = workflowInstructions(mode);
+    // Replace only a complete harness paragraph: user context and all other frozen bytes survive.
+    const paragraphs = session.config.frozen.system.split("\n\n");
+    const index = paragraphs.indexOf(oldInstruction);
+    if (index >= 0) paragraphs[index] = nextInstruction; else paragraphs.push(nextInstruction);
+    const system = mode === current ? session.config.frozen.system : paragraphs.join("\n\n");
+    const catalog = sessionToolCatalog({ ...args, workflow: mode }, app.extensions, session.config.frozen.tools);
+    // The persisted checkpoint owns the admission mode as well as declarations, including cold restore.
+    session.config.tools.workflowMode = mode;
+    if (nextProfile) session.config.agentProfile = nextProfile;
+    if (nextScope) session.config.workflowToolProfile = nextScope; else delete session.config.workflowToolProfile;
+    try {
+      const changed = await session.reloadResources(mode === current && !promote ? session.config.frozen : { ...session.config.frozen, system, tools: catalog.schemas }, undefined, undefined, metadataChanged);
+      if (mode !== current || promote) session.config.tools.deferredTools = catalog.deferred;
+      args.workflow = mode; args.cliFlags = [...new Set([...args.cliFlags ?? [], "--workflow"])]; app.args = args; app.system = system;
+      return changed;
+    } catch (error) {
+      if (previousMode === undefined) delete session.config.tools.workflowMode;
+      else session.config.tools.workflowMode = previousMode;
+      if (previousProfile === undefined) delete session.config.agentProfile;
+      else session.config.agentProfile = previousProfile;
+      if (previousScope === undefined) delete session.config.workflowToolProfile;
+      else session.config.workflowToolProfile = previousScope;
+      throw error;
+    }
+  });
+}
+
+export function bindAppWorkflow(app: WorkflowApp): void {
+  const session = app.session;
+  sessionControl(session).configureWorkflow = async mode => {
+    if (app.session !== session) throw Error("this session is no longer attached to the app");
+    await setAppWorkflow(app, mode);
+  };
+}

package/src/core/activity-status.ts

@@ -0,0 +1,28 @@
+/** A finer view of OSC status, derived from the same runtime facts (D11). */
+import { programStatus, type ProgramStatus } from "./program-status.ts";
+import type { ExecutionOutcome } from "./outcome.ts";
+
+export interface ActivityFacts {
+  readonly running: boolean;
+  readonly waiting?: "permission" | "question" | "auth" | null;
+  readonly outcome?: ExecutionOutcome;
+  readonly goal?: string;
+  readonly phase?: "connecting" | "thinking" | "streaming" | "tool";
+  readonly tool?: string;
+  readonly retry?: { readonly attempt: number; readonly seconds: number };
+  readonly queued: number;
+}
+export interface ActivityStatus { readonly state: ProgramStatus["state"]; readonly label: string; readonly detail: string; readonly queued: number }
+
+export function activityStatus(facts: ActivityFacts): ActivityStatus {
+  const status = programStatus(facts), queued = Math.max(0, Math.floor(facts.queued));
+  const view = (label: string, detail = status.msg ?? ""): ActivityStatus => ({ state: status.state, label, detail, queued });
+  if (status.state === "blocked") return view(status.kind === "auth" ? "Sign in required" : status.kind === "permission" ? "Awaiting approval" : "Awaiting input");
+  if (status.state === "error") return view("Failed");
+  if (!facts.running) return view(status.state === "done" ? "Turn finished" : facts.outcome?.status === "cancelled" ? "Cancelled" : "Ready");
+  if (facts.retry) return view("Retrying", `attempt ${facts.retry.attempt} · ${Math.max(0, Math.ceil(facts.retry.seconds))}s`);
+  if (facts.phase === "tool") return view("Running tool", facts.tool ?? "Tool execution");
+  if (facts.phase === "thinking") return view("Thinking");
+  if (facts.phase === "streaming") return view("Responding");
+  return view("Connecting", "Waiting for the first response");
+}