@visual-z/xeno 0.3.0 → 0.4.0

package/src/apps/ui/app.ts

@@ -36,7 +36,7 @@ import { attachImageBytes, attachImageFile } from "../../runtime/images.ts";
 import { readClipboard, writeClipboard, type ClipboardContent } from "../../runtime/clipboard.ts";
 import { highlightCode, transformMermaid, warmSyntaxLanguages } from "../../runtime/rich-text.ts";
 import { SOURCE_PROVIDERS } from "../../runtime/model-data.ts";
-import { SUBSCRIPTION_OPTIONS, loginGitHubCopilot, startCallbackServer, XENO_VERSION } from "../../runtime/oauth.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";
@@ -64,6 +64,7 @@ import { displayPath } from "../../tui/ui/paths.ts";
 import { approvalHeading, approvalItems, choiceFromValue } from "../approve.ts";
 import { completionAt, completionSources, commandEntries } from "../completions.ts";
 import { commandDefinition } from "../commands.ts";
+import { completionAction } from "../../core/completion-action.ts";
 import { expandInput } from "../input.ts";
 import type { TrustChoice } from "../project-trust.ts";
 import { describeError, firstLine } from "../render.ts";
@@ -79,6 +80,11 @@ import type { OAuthEffects, Ui } from "./surface.ts";
 import { styleTokens, terminalPalette, uiColors } from "./theme.ts";
 import { ImageCache } from "./image-cache.ts";
 import { ImageDraft } from "../image-draft.ts";
+import { sessionControl, type SessionControl, type ControlSnapshot } from "../../runtime/session-control.ts";
+import { controlModel } from "./control-model.ts";
+import { controlPanelLines, type ControlTab, type ControlFocus } from "../../tui/ui/control-panel.ts";
+import { programStatus } from "../../core/program-status.ts";
+import { ProgramStatusReporter } from "../../runtime/program-status.ts";
 import type { PictureSource } from "../../tui/ui/pictures.ts";
 import { DEFAULT_CELL } from "../../tui/ui/image-size.ts";
 import type { TerminalPalette } from "../../tui/ui/ink.ts";
@@ -110,7 +116,7 @@ export class InteractiveApp implements Ui {
   oauthEffects: OAuthEffects = { ...loginEffects };
   clipboardWriter: (text: string) => boolean | Promise<boolean> = writeClipboard;
   clipboardReader: () => Promise<ClipboardContent> = readClipboard;
-  /** Test seam for /login custom endpoints. */
+  /** Test seam for /provider custom endpoints. */
   connectFetch: ((input: string, init?: RequestInit) => Promise<Response>) | undefined;
   sessionName: string | null = null;
   queue: QueuedMessage[] = [];
@@ -138,6 +144,12 @@ export class InteractiveApp implements Ui {
   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;
+  private control: SessionControl | undefined;
+  private stopControl: (() => void) | undefined;
+  private controlSnapshot: ControlSnapshot | undefined;
+  private readonly program: ProgramStatusReporter | undefined;
+  private readonly stopOsc: (() => void) | undefined;
+  private programResult = false;
   private derivedKey = "";
   private derivedTimer: ReturnType<typeof setTimeout> | undefined;
   private derivedRun: Promise<void> | null = null;
@@ -191,10 +203,12 @@ export class InteractiveApp implements Ui {
   /** Set once the renderer is gone; late async work (timers, warmed grammars) must not touch it. */
   private disposed = false;
 
-  constructor(app: App, hooks: Hooks, renderer: CliRenderer) {
+  constructor(app: App, hooks: Hooks, renderer: CliRenderer, program?: ProgramStatusReporter) {
     this.app = app;
     this.hooks = hooks;
     this.renderer = renderer;
+    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.sessionName = app.args.sessionName || null;
@@ -274,22 +288,28 @@ export class InteractiveApp implements Ui {
   redraw(): void { this.paint(); }
 
   askSecret(title: string, label: string, hint: string): Promise<string | undefined> {
+    const control = sessionControl(this.app.session); control.setWaiting("auth");
     return new Promise(resolve => this.screen.dialogs.push({ kind: "form", title, label, secret: true, hint,
-      onSubmit: value => resolve(value), onCancel: () => resolve(undefined) }));
+      onSubmit: value => { control.setWaiting(null); resolve(value); },
+      onCancel: () => { control.setWaiting(null); resolve(undefined); } }));
   }
   confirm(title: string, message: string): Promise<boolean> {
-    return new Promise(resolve => this.screen.dialogs.push({ kind: "confirm", title, message, onAnswer: yes => resolve(yes) }));
+    const control = sessionControl(this.app.session); control.setWaiting("question");
+    return new Promise(resolve => this.screen.dialogs.push({ kind: "confirm", title, message, onAnswer: yes => { control.setWaiting(null); resolve(yes); } }));
   }
   waiting(title: string, lines: readonly string[], onCancel: () => void, pasteLabel?: string, onPaste?: (value: string) => void): () => void {
+    const control = sessionControl(this.app.session); control.setWaiting("auth");
+    const cancel = () => { control.setWaiting(null); onCancel(); };
     const spec: DialogSpec = pasteLabel && onPaste
-      ? { kind: "form", title, label: pasteLabel, secret: true, intro: lines, hint: "waiting for the browser · paste the redirect URL + enter · esc cancel", onSubmit: onPaste, onCancel }
-      : { kind: "busy", title, message: lines.join("\n"), onCancel };
+      ? { kind: "form", title, label: pasteLabel, secret: true, intro: lines, hint: "waiting for the browser · paste the redirect URL + enter · esc cancel", onSubmit: onPaste, onCancel: cancel }
+      : { kind: "busy", title, message: lines.join("\n"), onCancel: cancel };
     this.screen.dialogs.push(spec);
-    return () => this.screen.dialogs.remove(spec);
+    return () => { this.screen.dialogs.remove(spec); control.setWaiting(null); };
   }
 
   // ----------------------------------------------------------------- lifecycle
   async start(): Promise<void> {
+    this.program?.start();
     this.applyConfiguration();
     this.followTheme();
     void this.detectPalette();
@@ -341,7 +361,12 @@ export class InteractiveApp implements Ui {
     this.abort?.abort();
     this.closedResolve();
   }
-  interrupt(): void { this.abort?.abort(); this.returnQueueToEditor(); }
+  interrupt(): void {
+    this.abort?.abort();
+    const control = sessionControl(this.app.session);
+    if (control.activeTurnId) control.interrupt(control.activeTurnId);
+    this.returnQueueToEditor();
+  }
 
   async settle(): Promise<void> {
     await this.hooks.cancelPendingOAuth(this.app);
@@ -356,6 +381,8 @@ export class InteractiveApp implements Ui {
 
   dispose(): void {
     this.disposed = true;
+    this.stopControl?.();
+    this.stopOsc?.(); this.program?.close();
     clearTimeout(this.paintTimer); clearInterval(this.retryTimer); clearTimeout(this.derivedTimer); this.derivedTimer = undefined;
     this.stopThemeWatch?.();
     this.renderer.off("theme_mode", this.terminalThemeChanged);
@@ -376,6 +403,7 @@ export class InteractiveApp implements Ui {
 
   // --------------------------------------------------------------- transcript
   async syncTranscript(): Promise<void> {
+    this.bindControl();
     const session = this.app.session, dir = this.app.logDir, node = session.state.node;
     if (dir !== this.historyDir || node !== this.historyNode) {
       const history = await readNodeHistory(dir, node);
@@ -509,7 +537,7 @@ export class InteractiveApp implements Ui {
     const app = this.app, spec = app.providerConfig.spec, budget = this.budget();
     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 · /login"].filter(Boolean).join(" · ");
+    const extension = [this.extensions.status, app.credential.ok ? "" : "no provider · /provider"].filter(Boolean).join(" · ");
     return {
       version: XENO_VERSION, title: this.sessionName ?? this.prompt, workspace: displayPath(app.workspace, homedir()),
       workspaceShort: shortPath(displayPath(app.workspace, homedir())), branch: this.branch,
@@ -519,6 +547,11 @@ export class InteractiveApp implements Ui {
         cost: cost.kind === "usd" && cost.amount >= 0.005 ? `~$${cost.amount.toFixed(2)}` : cost.kind === "partial" && cost.known >= 0.005 ? `≥$${cost.known.toFixed(2)}` : null } } : {}),
       tools: { running: tools.filter(tool => tool.status === "pending").length, done: tools.filter(tool => tool.status === "ok").length, failed: tools.filter(tool => tool.status === "error").length },
       ...(this.derived ?? {}),
+      ...(this.controlSnapshot?.goal ? { goal: { text: this.controlSnapshot.goal.text,
+        status: this.controlSnapshot.goal.state.status,
+        execution: this.inflight ? "running" : this.controlSnapshot.goal.state.execution?.reason ?? "idle",
+        observations: this.controlSnapshot.goal.state.progress.observations.length,
+        retries: this.controlSnapshot.goal.state.progress.unchanged_retries.length } } : {}),
       files: this.files,
       resources: { contextFiles: app.loadedContext.agents.map(file => basename(file.path)), skills: app.slash?.skills.size ?? 0, extensions: app.extensions?.loaded.length ?? 0 },
       ...(extension ? { extension } : {}),
@@ -571,8 +604,24 @@ export class InteractiveApp implements Ui {
     this.derivedLast = Date.now();
     const target = this.derivedTarget();
     this.derivedRun = (async () => {
-      try { this.derived = handoffStatus(await this.app.session.previewHandoff()); this.derivedKey = target; }
-      catch { /* preview needs a readable log; the status keeps its last state */ }
+      try {
+        const session = this.app.session;
+        const derived = handoffStatus(await session.previewHandoff());
+        const snapshot = await sessionControl(session).snapshot(false);
+        if (this.app.session !== session) return;
+        this.derived = derived; this.controlSnapshot = snapshot; this.derivedKey = target;
+        // Idle acceptance changes have no model delta. Reconcile terminal attention
+        // with the same evidence projection that refreshes the visible goal.
+        if (!this.inflight) this.program?.update(programStatus({ running: false, waiting: snapshot.waiting,
+          ...(snapshot.goal?.state.execution ? { outcome: snapshot.goal.state.execution } : {}),
+          ...(snapshot.goal ? { goal: snapshot.goal.state.status } : {}) }));
+        if (this.screen.dialogs.top?.title === "Control panel") this.screen.dialogs.refresh();
+      }
+      catch {
+        // Unavailable evidence cannot leave a stale verified goal visible.
+        this.controlSnapshot = undefined;
+        if (this.screen.dialogs.top?.title === "Control panel") this.screen.dialogs.refresh();
+      }
     })();
     await this.derivedRun;
     this.derivedRun = null;
@@ -607,17 +656,19 @@ export class InteractiveApp implements Ui {
       if (key.chord === "up") { composer.moveCompletion(-1); return true; }
       if (key.chord === "down") { composer.moveCompletion(1); return true; }
       if (key.chord === "escape") { composer.setCompletion(undefined); return true; }
-      if (key.chord === "tab") { composer.acceptCompletion(); this.updateCompletion(); this.paint(); return true; }
-      if (key.chord === "enter" && /^\/\S*$/.test(composer.text)) {
+      if (key.chord === "tab" || key.chord === "enter") {
+        const kind = composer.completionView!.kind;
         const item = composer.acceptCompletion();
         if (item) {
-          const definition = commandDefinition(item.value.trim());
-          if (definition && "argumentHint" in definition && definition.argumentHint?.startsWith("<")) { this.updateCompletion(); return true; }
-          this.track(() => this.submit(item.value, "steering")); return true;
+          const definition = commandDefinition(composer.text);
+          const required = !!definition && "argumentHint" in definition && definition.argumentHint.startsWith("<");
+          if (completionAction(kind, key.chord, required) === "submit") {
+            const text = composer.text;
+            this.track(() => this.submit(text, "steering"));
+          } else { this.updateCompletion(); this.paint(); }
         }
+        return true;
       }
-      if (key.chord === "enter" && !composer.text.trimEnd().match(/^\/\S+\s*$/)) { composer.acceptCompletion(); this.updateCompletion(); return true; }
-      if (key.chord === "enter") { composer.setCompletion(undefined); }
     }
     if (bound(b, "app.palette", key)) { this.openPalette(); return true; }
     if (bound(b, "app.clear", key)) {
@@ -694,7 +745,7 @@ export class InteractiveApp implements Ui {
   async whenIdle(): Promise<void> {
     for (let round = 0; round < 50; round++) {
       const turn = this.turn, work = this.work.size;
-      await turn; await this.idle(); await this.app.session.whenIdle(); await this.app.extensions?.settle();
+      await turn; await this.control?.whenIdle().catch(() => {}); await this.idle(); await this.app.session.whenIdle(); await this.app.extensions?.settle();
       if (turn === this.turn && !this.inflight && work === this.work.size && !this.work.size) return;
     }
   }
@@ -743,12 +794,22 @@ 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.programResult = false;
+    this.program?.update(programStatus({ running: true }));
     this.executionKind = text.startsWith("!") ? "bash" : "model";
     this.paint();
     try {
       const sent = await this.hooks.run(this.app, text, this.abort.signal, this, images, skill);
+      if (!sent && !this.app.credential.ok) {
+        this.programResult = true; this.program?.update(programStatus({ running: false, waiting: "auth" }));
+      }
       if (sent && !this.abort.signal.aborted) await this.drainFollowUps();
+    } catch (error) {
+      this.programResult = true;
+      this.program?.update({ state: "error", msg: "Turn failed; inspect the session" });
+      throw error;
     } finally {
+      if (!this.programResult) this.program?.update(programStatus({ running: false }));
       await this.syncTranscript();
       this.abort = null;
       this.hooks.dropFileIndex(this.app.workspace);
@@ -956,13 +1017,117 @@ export class InteractiveApp implements Ui {
 
   // ---------------------------------------------------------------- approval
   ask(request: PermissionRequest): Promise<ApprovalChoice> {
+    this.program?.update(programStatus({ running: this.inflight, waiting: "permission" }));
     // While the dialog is open the pending call shows ◌: it is waiting on the person, not running.
     this.screen.messages.setWaiting(true);
-    const answered = (choice: ApprovalChoice) => { this.screen.messages.setWaiting(false); return choice; };
+    const present = (_id: string, resolve: (choice: ApprovalChoice) => void) => {
+      const spec: DialogSpec = { kind: "list", title: "Tool approval", search: false, tone: "warning", intro: approvalHeading(request).split("\n"),
+        items: approvalItems(request), onPick: item => resolve(choiceFromValue(item.value)), onCancel: () => resolve("deny") };
+      this.screen.dialogs.push(spec);
+      return () => { this.screen.messages.setWaiting(false); this.screen.dialogs.remove(spec); this.program?.update(programStatus({ running: this.inflight })); };
+    };
+    // Isolated skills and user shell commands retain their existing local approval lifecycle.
+    const control = sessionControl(this.app.session);
+    if (control.activeTurnId) return control.ask(request, present);
     return new Promise(resolve => {
-      this.screen.dialogs.push({ kind: "list", title: "Tool approval", search: false, tone: "warning", intro: approvalHeading(request).split("\n"),
-        items: approvalItems(request), onPick: item => resolve(answered(choiceFromValue(item.value))), onCancel: () => resolve(answered("deny")) });
+      let close: () => void;
+      close = present("local", choice => { close(); resolve(choice); });
+    });
+  }
+
+  private bindControl(): void {
+    const control = sessionControl(this.app.session);
+    if (this.control === control) return;
+    this.stopControl?.(); this.control = control; this.controlSnapshot = 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/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)
+        this.program?.update(programStatus({ running: control.busy, waiting: notice.params["waiting"] as ControlSnapshot["waiting"] }));
+      // 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"; }
+        if (notice.method === "turn/completed") {
+          this.inflight = false; this.executionKind = "idle"; this.clearStream();
+          const outcome = notice.params["outcome"] as import("../../core/outcome.ts").ExecutionOutcome | undefined;
+          this.turn = this.continueRemoteTurn(control, outcome).catch(error => this.notice(describeError(error), "error"));
+        }
+        if (notice.method === "turn/event") {
+          const event = notice.params["event"] as import("../../runtime/loop.ts").LoopEvent;
+          this.observeEvent(event);
+          if (event.kind === "text_delta" || event.kind === "thinking_delta") this.pushDelta(event.kind === "text_delta" ? "text" : "thinking", event.text ?? "");
+          else if (event.kind === "discard") this.discardStream();
+          else if (event.kind === "progress") { if (event.progress) this.pushProgress(event.progress); }
+          else this.track(() => this.syncTranscript());
+        }
+      }
+      if (notice.method !== "turn/event") { this.derivedKey = ""; this.requestDerived(); this.paint(); }
     });
+    this.stopControl = () => { detachInput(); unsubscribe(); };
+  }
+
+  private async continueRemoteTurn(control: SessionControl, outcome?: import("../../core/outcome.ts").ExecutionOutcome): Promise<void> {
+    // Completion is announced before the iterator releases execution. Follow-ups
+    // remain editor-owned until that release, preserving the existing queue contract.
+    await control.whenIdle().catch(() => {});
+    if (this.disposed || this.shutdownRequested || this.control !== control || this.inflight) return;
+    if (outcome?.status !== "completed") { this.returnQueueToEditor(); return; }
+    const batch = this.nextBatch("turn_end");
+    if (!batch.length) return;
+    this.queue = this.queue.filter(item => !batch.includes(item));
+    await this.runPromptTurn(batch.map(item => item.text).join("\n\n"), batch.flatMap(item => item.images ?? []));
+  }
+
+  observeEvent(event: import("../../runtime/loop.ts").LoopEvent): void {
+    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 } : {}) }));
+    if (event.kind === "stop_and_ask") this.program?.update(programStatus({ running: false, waiting: "question" }));
+  }
+
+  async openControl(tab: ControlTab = "goal"): Promise<void> {
+    this.bindControl();
+    this.controlSnapshot = await this.control!.snapshot();
+    const tabs: ControlTab[] = ["goal", "progress", "context"];
+    const lenses: ControlFocus[] = ["messages", "omitted", "history"];
+    let focus: ControlFocus = "messages", scroll = 0, total = 0;
+    this.screen.dialogs.push({ kind: "lines", title: "Control panel",
+      hint: "tab sections · ←→ lenses · ↑↓ scroll · r refresh · i interrupt · a accept",
+      render: width => {
+        if (!this.controlSnapshot) return ["Current evidence unavailable. Press r to refresh."];
+        const lines = controlPanelLines(controlModel(this.controlSnapshot), tab, width, focus);
+        const rows = Math.max(4, this.renderer.height - 14); total = lines.length;
+        scroll = Math.min(scroll, Math.max(0, total - rows));
+        return [...lines.slice(scroll, scroll + rows), ...(total > rows ? [`${scroll + 1}–${Math.min(total, scroll + rows)} / ${total} · ↑↓ scroll`] : [])];
+      },
+      handleKey: async key => {
+        if (key.name === "tab") { tab = tabs[(tabs.indexOf(tab) + 1) % tabs.length]!; scroll = 0; this.screen.dialogs.refresh(); return true; }
+        if (key.name === "up" || key.name === "down") { scroll = Math.max(0, Math.min(total - 1, scroll + (key.name === "down" ? 1 : -1))); this.screen.dialogs.refresh(); return true; }
+        if (tab === "context" && (key.name === "left" || key.name === "right")) {
+          focus = lenses[(lenses.indexOf(focus) + (key.name === "right" ? 1 : 2)) % 3]!; scroll = 0; this.screen.dialogs.refresh(); return true;
+        }
+        if (key.name === "r") { this.controlSnapshot = await sessionControl(this.app.session).snapshot(); this.screen.dialogs.refresh(); return true; }
+        if (key.name === "i") { this.interrupt(); return true; }
+        if (key.name === "a") {
+          const goal = this.controlSnapshot?.goal;
+          const criteria = goal?.state.acceptance?.criteria.filter(item => item.kind === "human" && item.status !== "pass" && item.status !== "accepted") ?? [];
+          if (this.inflight || !goal || !criteria.length) { this.toast("No human criterion ready for acceptance", "warning"); return true; }
+          this.screen.dialogs.push({ kind: "list", title: "Accept a human criterion", search: false,
+            items: criteria.map(item => ({ value: item.id, label: item.description, description: item.status })),
+            onPick: async item => {
+              await sessionControl(this.app.session).accept(goal.state.request.event, item.value);
+              this.controlSnapshot = await sessionControl(this.app.session).snapshot(); this.screen.dialogs.refresh();
+            } });
+          return true;
+        }
+        return false;
+      } });
   }
 
   // ----------------------------------------------------------------- palette
@@ -1062,7 +1227,7 @@ export class InteractiveApp implements Ui {
   }
 
   openLogin(method?: "oauth" | "api_key"): void {
-    const providers = [...new Set(this.app.catalog.map(model => model.provider))];
+    const providers = [...new Set(this.app.catalog.map(model => model.provider))].filter(provider => !subscriptionById(provider));
     const status = (provider: string): string => {
       const spec = this.app.catalog.find(model => model.provider === provider);
       const resolved = spec ? this.app.credentialOf(spec) : undefined;
@@ -1105,7 +1270,7 @@ export class InteractiveApp implements Ui {
     const ready = this.app.catalog.filter(spec => this.app.credentialOf(spec).ok);
     const configured = this.app.ui?.settings.scopedModels;
     const checked = configured ? ready.filter(spec => configured.some(pattern => pattern === modelKey(spec) || pattern === spec.id)).map(modelKey) : ready.map(modelKey);
-    this.push({ kind: "list", title: "Models to cycle with alt+m", multi: true, checked, empty: "No available models. Use /login to add a credential.",
+    this.push({ kind: "list", title: "Models to cycle with alt+m", multi: true, checked, empty: "No available models. Use /provider to add a credential.",
       items: ready.map(spec => ({ value: modelKey(spec), label: spec.id, description: spec.provider, section: SOURCE_PROVIDERS[spec.provider]?.name ?? spec.provider })),
       onSubmitChecked: async values => {
         await writeUserSettings({ scopedModels: values });
@@ -1318,10 +1483,15 @@ function noticeOf(id: string, after: number, lines: string[], tone: Tone): Notic
 export async function runInteractive(app: App, hooks: Hooks, releaseEarlyTty?: () => void, renderer?: CliRenderer): Promise<void> {
   const fullscreen = (app.ui?.settings.tuiMode ?? "fullscreen") !== "regular";
   releaseEarlyTty?.();
+  // Capture the real writer before OpenTUI owns stdout, so OSC never becomes transcript text.
+  const terminalWrite = process.stdout.write.bind(process.stdout);
   const r = renderer ?? await createCliRenderer({ screenMode: fullscreen ? "alternate-screen" : "main-screen", exitOnCtrlC: false, exitSignals: [],
     // Performance (refactor-tui-dock-layout DoD 9): no console capture, no stats, no hover tracking; bursts coalesce at 60 fps.
     consoleMode: "disabled", openConsoleOnError: false, useMouse: true, enableMouseMovement: false, gatherStats: false, memorySnapshotInterval: 0, targetFps: 60, maxFps: 60 });
-  const ui = new InteractiveApp(app, hooks, r);
+  const program = new ProgramStatusReporter({ write: text => { terminalWrite(text); }, id: `xeno-${process.pid}`,
+    tty: !renderer && process.stdout.isTTY === true, mode: process.env["XENO_PROGRAM_STATUS"] ?? "auto",
+    multiplexed: Boolean(process.env["TMUX"] || process.env["STY"]) });
+  const ui = new InteractiveApp(app, hooks, r, program);
   const previousSay = app.io.say;
   app.io.say = line => ui.notice(line);
   const stop = (code: number) => { process.exitCode = code; ui.requestShutdown(); };

package/src/apps/ui/control-model.ts

@@ -0,0 +1,26 @@
+import type { ControlSnapshot } from "../../runtime/session-control.ts";
+import type { ControlPanelModel } from "../../tui/ui/control-panel.ts";
+
+export function controlModel(snapshot: ControlSnapshot): ControlPanelModel {
+  const goal = snapshot.goal, state = goal?.state, context = snapshot.context;
+  const progress = (label: string, sources: readonly { node: number; event: string }[]) => ({ label, count: sources.length, sources: sources.map(source => `${source.node}/${source.event}`) });
+  return { thread: snapshot.threadId, turn: snapshot.activeTurnId ?? state?.request.event ?? null,
+    goal: goal?.text ?? "Send a request to establish a goal.", status: state?.status ?? "idle",
+    execution: snapshot.waiting ? `waiting for ${snapshot.waiting}` : snapshot.activeTurnId ? "running" : state?.execution?.reason ?? "idle",
+    gaps: goal?.gaps ?? [], checks: state?.commands.map(command => `${command.status} · exit ${command.exit} · ${command.command} · ${command.source.node}/${command.source.event}`) ?? [],
+    progress: state ? [
+      progress("New observations", state.progress.observations),
+      progress("Artifact changes", state.progress.artifact_changes),
+      progress("Acceptance advances", state.progress.acceptance_advances),
+      progress("New diagnostics", state.progress.new_diagnostics),
+      progress("Unchanged retries", state.progress.unchanged_retries),
+      progress("Unknown diagnostics", state.progress.unknown_diagnostics),
+    ] : [],
+    context: [`${context.used} tokens (${context.countKind}); ${context.messages.length} messages; ${context.policy}`,
+      ...Object.entries(context.components).map(([name, count]) => `${name}: ~${count}`),
+      ...context.messages.map(message => `#${message.index} ${message.role}: ${message.sources.join(", ")}`)],
+    omitted: context.omitted.map(event => `${event.id}: ${event.type} (original stays in log)`),
+    history: context.sections.filter(section => section.total > 0).map(section => `${section.section}: ${section.retained}/${section.total}` +
+      (section.recovery ? ` · history(${JSON.stringify(section.recovery)})` : "")),
+  };
+}

package/src/apps/ui/surface.ts

@@ -19,6 +19,7 @@ export interface TurnSurface {
   syncTranscript(): Promise<void>;
   pushProgress?(progress: NonNullable<LoopEvent["progress"]>): void;
   pullQueued?(phase: Phase): Promise<UserInput | null>;
+  observeEvent?(event: LoopEvent): void;
 }
 
 export interface Ui extends TurnSurface {
@@ -52,6 +53,7 @@ export interface Ui extends TurnSurface {
   openFork(): Promise<void>;
   openTree(): Promise<void>;
   openResources(): Promise<void>;
+  openControl(tab?: "goal" | "progress" | "context"): Promise<void>;
   openTrust(): Promise<void>;
   openAttachments(): void;
 

package/src/core/completion-action.ts

@@ -0,0 +1,20 @@
+import { assertNever } from "./exhaustive.ts";
+
+/** D19: confirmation follows the selected completion, never the unfinished draft. */
+export function completionAction(kind: "command" | "argument" | "path", key: "enter" | "tab", requiresArgument: boolean): "insert" | "submit" {
+  if (key === "tab") return "insert";
+  switch (kind) {
+    case "command": return requiresArgument ? "insert" : "submit";
+    case "argument": return "submit";
+    case "path": return "insert";
+    default: return assertNever(kind, "completion kind");
+  }
+}
+
+/** Match the parser's exact identity before discoverable prefixes and substrings. */
+export function commandCompletionRank(name: string, query: string): number {
+  const canonical = name.toLowerCase(), typed = query.toLowerCase();
+  if (canonical === typed) return 0;
+  if (canonical.startsWith(typed)) return 1;
+  return typed.length > 1 && canonical.includes(typed) ? 2 : Number.POSITIVE_INFINITY;
+}

package/src/core/completion-review.ts

@@ -12,8 +12,7 @@
  */
 import type { GuidanceEvent, LogEvent } from "./events.ts";
 import type { AcceptanceState } from "./acceptance.ts";
-import { changedPaths } from "./checkpoints.ts";
-import { resolveEvidence } from "./evidence.ts";
+import { deriveRequestState, type RequestState } from "./request-state.ts";
 
 /**
  * Wording that hands the task back instead of finishing it. Ported from
@@ -40,27 +39,28 @@ export function completionReview(
   remainingRequests: number,
   options?: { strictVerification?: boolean; acceptance?: AcceptanceState; taskAware?: boolean },
 ): Pick<GuidanceEvent, "reason" | "text" | "sources"> | null {
-  if (remainingRequests < 1) return null;
-  const start = events.findLastIndex((event) => event.t === "user");
-  if (start < 0) return null;
-  const current = events.slice(start);
-  if (current.some((event) => event.t === "guidance" && event.reason === "completion_review")) return null;
-  const final = current.findLast((event) => event.t === "assistant");
-  if (final?.t !== "assistant" || final.blocks.some((block) => block.type === "tool_use")) return null;
+  const state = deriveRequestState([{ node: 0, events }]);
+  const decision = state ? requestCompletion(state, remainingRequests, options) : { action: "finish" as const };
+  return decision.action === "continue" ? decision.guidance : null;
+}
+
+export type RequestCompletion = { action: "finish" } |
+  { action: "continue"; guidance: Pick<GuidanceEvent, "reason" | "text" | "sources"> };
 
-  const text = final.blocks.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n").trim();
-  const usedTools = current.some((event) => event.t === "tool_result");
-  const lastEdit = current.findLastIndex((event) => event.t === "tool_result" && event.effect?.kind === "edit" ||
-    event.t === "checkpoint" && event.phase === "applied" && changedPaths(event.changes).length > 0);
-  const verifiedAfter = lastEdit >= 0 && current.slice(lastEdit + 1)
-    .some((event) => event.t === "tool_result" && event.effect?.kind === "command" && event.effect.exit === 0 &&
-      resolveEvidence(current, { command: event.effect.cmd }).ok &&
-      (!options?.strictVerification || event.effect.gate !== undefined));
+/** Q23: loop termination and the public request view consume the same evidence. */
+export function requestCompletion(state: RequestState, remainingRequests: number,
+  options?: { strictVerification?: boolean; acceptance?: AcceptanceState; taskAware?: boolean }): RequestCompletion {
+  const finish = { action: "finish" as const };
+  if (remainingRequests < 1 || state.reviewed || state.status === "blocked") return finish;
+  const final = state.final;
+  if (!final || final.has_tools || state.execution?.reason !== "model_end" && state.execution?.reason !== "unknown") return finish;
+  const text = final.text;
+  const verifiedAfter = state.commands.some(command => command.status === "pass" && (!options?.strictVerification || command.gate !== undefined));
 
   const gaps: string[] = [];
-  if (usedTools && text.length === 0) gaps.push("the final reply is empty");
-  if (lastEdit >= 0 && !verifiedAfter && !options?.acceptance) gaps.push("files were changed but no command has succeeded since the last edit");
-  const acceptance = options?.acceptance;
+  const acceptance = options?.acceptance ?? state.acceptance;
+  if (state.used_tools && text.length === 0) gaps.push("the final reply is empty");
+  if (state.changed && !verifiedAfter && !acceptance) gaps.push("files were changed but no command has succeeded since the last edit");
   if (acceptance?.status === "needs_work") gaps.push(`declared acceptance criteria need evidence: ${[
     ...acceptance.criteria.filter(item => item.kind === "command" && item.status !== "pass").map(item => `${item.id}=${item.status}`),
     ...(acceptance.targets ?? []).filter(target => target.status !== "ready").map(target => `target ${target.id}=${target.status}`),
@@ -68,15 +68,15 @@ export function completionReview(
   if (text.length > 0 && looksLikeHandBack(text) && acceptance?.status !== "awaiting_human") gaps.push(options?.taskAware
     ? "the reply deferred the request; check whether authorized work remains or a specific blocker requires the user"
     : "the reply handed the task back instead of finishing it; no one will answer");
-  if (gaps.length === 0) return null;
-  return {
+  if (gaps.length === 0) return finish;
+  return { action: "continue", guidance: {
     reason: "completion_review",
-    sources: [current[0]!.id, final.id],
+    sources: [state.request.event, final.source.event],
     text: `Harness completion check: ${gaps.join("; ")}. ` +
-      `Re-read the original request (event ${current[0]!.id}) and check each requirement against evidence in this session. ` +
-      (options?.taskAware && lastEdit < 0
+      `Re-read the original request (event ${state.request.event}) and check each requirement against evidence in this session. ` +
+      (options?.taskAware && !state.changed
         ? "Use original sources for research and full inputs for calculations; do not invent command evidence. Required human acceptance remains pending. Finish with the result or the specific blocker. "
         : "Run the command that verifies the result, or finish with the specific blocker that prevents verification. ") +
       "This check runs once per request.",
-  };
+  } };
 }

package/src/core/control-protocol.ts

@@ -0,0 +1,62 @@
+/** Q24: the experimental wire contract and its validator share one schema. No SDK dependency (D13). */
+const text = { type: "string", minLength: 1, maxLength: 65536 } as const;
+const identity = { type: "string", minLength: 1, maxLength: 128 } as const;
+const object = (properties: Record<string, unknown>, required: readonly string[] = Object.keys(properties)) =>
+  ({ type: "object", properties, required, additionalProperties: false });
+const thread = { threadId: identity };
+const turn = { ...thread, turnId: identity };
+
+export const CONTROL_METHODS = {
+  initialize: object({ clientInfo: object({ name: identity, version: identity }) }),
+  initialized: object({}),
+  "thread/read": object(thread),
+  "thread/subscribe": object({ ...thread, after: object({ streamId: identity, sequence: { type: "integer", minimum: 0 } }) }, ["threadId"]),
+  "turn/start": object({ ...thread, input: text }),
+  "turn/steer": object({ ...turn, input: text }),
+  "turn/interrupt": object(turn),
+  "approval/respond": object({ ...turn, approvalId: identity, choice: { enum: ["once", "command", "tool", "deny"] } }),
+  "acceptance/accept": object({ ...thread, requestId: identity, criterionId: identity }),
+  "context/read": object({ ...thread, focus: { enum: ["messages", "omitted", "history"] }, offset: { type: "integer", minimum: 0 },
+    limit: { type: "integer", minimum: 1, maximum: 100 } }, ["threadId", "focus"]),
+  "item/list": object({ ...thread, after: object({ node: { type: "integer", minimum: 0 }, event: identity }),
+    limit: { type: "integer", minimum: 1, maximum: 100 } }, ["threadId"]),
+  "item/read": object({ ...thread, node: { type: "integer", minimum: 0 }, event: identity }),
+} as const;
+export const CONTROL_SCHEMA = { protocol: "xeno-control/0.1", experimental: true,
+  transport: "JSONL; JSON-RPC envelopes with jsonrpc omitted", methods: CONTROL_METHODS,
+  notifications: ["turn/started", "turn/event", "item/completed", "turn/completed", "turn/error", "turn/steeringQueued", "approval/request", "approval/resolved", "thread/statusChanged"],
+  recovery: "subscribe first, then use the returned snapshot cursor; gaps or a new streamId require a snapshot and paginated item/list, never replaying commands",
+  identity: "threadId hashes the resolved session directory path; turnId is the original user event ID; item identity is node plus event ID",
+  limits: { frameBytes: 1048576, queuedRequests: 32, outputBytes: 2097152 } } as const;
+
+export type RpcId = string | number;
+export type ControlRequest = { id?: RpcId; method: keyof typeof CONTROL_METHODS; params: Record<string, unknown> };
+export class ControlProtocolError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) { super(message); this.code = code; }
+}
+function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function matches(value: unknown, schemaValue: unknown): boolean {
+  const schema = schemaValue as Record<string, unknown>;
+  if (Array.isArray(schema["enum"])) return schema["enum"].includes(value);
+  if (schema["type"] === "string") return typeof value === "string" && value.length >= Number(schema["minLength"]) && value.length <= Number(schema["maxLength"]);
+  if (schema["type"] === "integer") return typeof value === "number" && Number.isSafeInteger(value) && value >= Number(schema["minimum"]) && (schema["maximum"] === undefined || value <= Number(schema["maximum"]));
+  if (schema["type"] === "object") {
+    if (!record(value)) return false;
+    const properties = schema["properties"] as Record<string, unknown>, required = schema["required"] as string[];
+    return required.every(key => Object.hasOwn(value, key)) && Object.keys(value).every(key => Object.hasOwn(properties, key) && matches(value[key], properties[key]));
+  }
+  return false;
+}
+export function parseControlRequest(value: unknown): ControlRequest {
+  if (!record(value) || typeof value["method"] !== "string" || Object.keys(value).some(key => !["id", "method", "params"].includes(key)))
+    throw new ControlProtocolError(-32600, "invalid request envelope");
+  const id = value["id"], method = value["method"];
+  if (id !== undefined && !(typeof id === "string" && id.length <= 128 || typeof id === "number" && Number.isSafeInteger(id)))
+    throw new ControlProtocolError(-32600, "invalid request id");
+  if (!Object.hasOwn(CONTROL_METHODS, method)) throw new ControlProtocolError(-32601, "unknown method");
+  const name = method as ControlRequest["method"], params = value["params"] ?? {};
+  if ((name === "initialized") !== (id === undefined)) throw new ControlProtocolError(-32600, "only initialized is a client notification");
+  if (!matches(params, CONTROL_METHODS[name])) throw new ControlProtocolError(-32602, `invalid parameters for ${name}`);
+  return { ...(id === undefined ? {} : { id }), method: name, params: params as Record<string, unknown> };
+}