@visual-z/xeno 0.4.0 → 0.6.0

package/src/apps/ui/app.ts

@@ -25,7 +25,7 @@ import { pickerRows } from "../../core/model-picker.ts";
 import { modelKey } from "../../core/session-position.ts";
 import { flattenTree, type TreeFilter, type TreeNode } from "../../core/session-tree.ts";
 import { selectSessions, type SessionSort } from "../../core/session-browser.ts";
-import { DISPLAY_SETTINGS, mergeSettings, settingValue, settingValues } from "../../core/settings.ts";
+import { DISPLAY_SETTINGS, settingValue, settingValues } from "../../core/settings.ts";
 import { THINKING_LEVELS, asThinkingLevel, supportedThinkingLevels } from "../../core/thinking.ts";
 import { builtinTheme } from "../../core/theme.ts";
 import { projectTranscript, type TranscriptItem } from "../../core/transcript.ts";
@@ -38,10 +38,9 @@ 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";
@@ -50,7 +49,8 @@ import { projectTrust } from "../../store/trust.ts";
 import { discoverResources, setResourceOverride } from "../../store/resource-index.ts";
 import { nextResourceOverride } from "../../core/resource-selection.ts";
 import { archiveSession, renameSession, scanSessionRoots, sessionRoots } from "../../store/session-browser.ts";
-import { discoverThemes, removeModelThinkingOverride, selectedThemePath, watchTheme, writeUserSettings, loadUiResources } from "../../store/resources.ts";
+import { discoverThemes, removeModelThinkingOverride, selectedThemePath, watchTheme, loadUiResources } from "../../store/resources.ts";
+import { commitUserSettings } from "../preferences.ts";
 import { fuzzyMatch } from "../../tui/fuzzy.ts";
 import type { DialogSpec, ListAction } from "../../tui/ui/dialog.ts";
 import { keyPress, bound, type KeyPress } from "../../tui/ui/keys.ts";
@@ -82,7 +82,7 @@ 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 type { ControlTab } 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";
@@ -177,8 +177,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. */
@@ -216,6 +217,10 @@ export class InteractiveApp implements Ui {
     this.screen = new Screen(renderer, this.colors(), () => this.keymap().byAction, {
       codeBlock: (code, language) => highlightCode(code, language, (token, text) => this.app.ui?.style.token?.(token, text) ?? ANSI.token?.(token, text) ?? text),
     });
+    this.screen.onControlAction = action => {
+      if (action === "interrupt") this.interrupt();
+      else this.track(async () => { if (action === "refresh") await this.refreshControl(); else this.acceptControlCriterion(); });
+    };
     this.imageDraft = new ImageDraft(this.screen.composer);
     this.extensions = new ExtensionHost({
       dialog: spec => this.screen.dialogs.push(spec),
@@ -320,7 +325,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();
   }
 
   /**
@@ -329,25 +334,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");
   }
@@ -389,7 +393,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;
@@ -590,7 +594,7 @@ export class InteractiveApp implements Ui {
    * per debounce window, one run at a time, and only while a surface shows it.
    */
   private requestDerived(): void {
-    if (this.disposed || this.screen.tier === "bare") return;
+    if (this.disposed || (this.screen.tier === "bare" && !this.screen.controlOpen)) return;
     if (this.derivedKey === this.derivedTarget()) return;
     if (this.derivedRun || this.derivedTimer) { this.derivedAgain = true; return; }
     // Throttle, not a pure debounce: the first change after a quiet spell refreshes at once,
@@ -604,23 +608,24 @@ export class InteractiveApp implements Ui {
     this.derivedLast = Date.now();
     const target = this.derivedTarget();
     this.derivedRun = (async () => {
+      const session = this.app.session;
       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;
+        if (this.disposed || 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();
+        this.screen.setControlModel(controlModel(snapshot));
       }
       catch {
         // Unavailable evidence cannot leave a stale verified goal visible.
+        if (this.disposed || this.app.session !== session) return;
         this.controlSnapshot = undefined;
-        if (this.screen.dialogs.top?.title === "Control panel") this.screen.dialogs.refresh();
+        this.screen.setControlModel(undefined);
       }
     })();
     await this.derivedRun;
@@ -636,6 +641,7 @@ export class InteractiveApp implements Ui {
   private onPaste(event: PasteEvent): void {
     const text = new TextDecoder().decode(event.bytes);
     if (this.screen.dialogs.open) { if (this.screen.dialogs.paste(text)) return; event.preventDefault(); return; }
+    this.screen.focusComposer();
     const paths = droppedImagePaths(text);
     if (paths) { event.preventDefault(); this.track(() => this.pasteClipboard({ files: paths })); }
   }
@@ -651,6 +657,7 @@ export class InteractiveApp implements Ui {
     if (bound(b, "app.exit", key) && !this.screen.dialogs.open && !this.screen.composer.text && !this.pendingImages.length) { this.requestShutdown(); return true; }
     if (bound(b, "app.suspend", key)) { this.suspend(); return true; }
     if (this.screen.dialogs.open) return this.screen.dialogs.key(key);
+    if (this.screen.handleControlKey(key)) return true;
     const composer = this.screen.composer;
     if (composer.completing) {
       if (key.chord === "up") { composer.moveCompletion(-1); return true; }
@@ -1039,6 +1046,7 @@ 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.screen.setControlModel(undefined);
     const detachInput = control.attachInput(phase => this.pullQueued(phase));
     const unsubscribe = control.subscribe(notice => {
       if (this.disposed) return;
@@ -1093,40 +1101,38 @@ export class InteractiveApp implements Ui {
 
   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;
+    if (!await this.refreshControl()) return;
+    this.screen.showControl(controlModel(this.controlSnapshot!), tab);
+    this.requestDerived();
+  }
+
+  private async refreshControl(): Promise<boolean> {
+    const control = sessionControl(this.app.session);
+    try {
+      const snapshot = await control.snapshot();
+      if (this.disposed || control !== sessionControl(this.app.session)) return false;
+      this.controlSnapshot = snapshot;
+      this.screen.setControlModel(controlModel(snapshot));
+      return true;
+    } catch (error) {
+      if (!this.disposed && control === sessionControl(this.app.session)) {
+        this.controlSnapshot = undefined;
+        this.screen.setControlModel(undefined);
+      }
+      throw error;
+    }
+  }
+
+  private acceptControlCriterion(): void {
+    const control = sessionControl(this.app.session), 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; }
+    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 => {
+        if (control !== sessionControl(this.app.session)) throw Error("Session changed; refresh the control panel");
+        await control.accept(goal.state.request.event, item.value);
+        await this.refreshControl();
       } });
   }
 
@@ -1192,37 +1198,17 @@ export class InteractiveApp implements Ui {
       keywords: `${row.model.provider} ${row.model.providerName}`, ...(row.current ? { hint: "● current" } : {}) }));
     items.push({ value: "login", label: "＋ Connect a provider…", section: "More", description: "subscription, API key, gateway or local server" });
     this.push({ kind: "list", title: `Model · ${rows.filter(row => row.model.ready).length} ready`, items, selected: current,
-      actions: [{ key: "ctrl+s", label: "save default", run: item => this.saveDefaultModel(item) }],
       onPick: async item => {
         if (item.value === "login") { this.openLogin(); return; }
         const spec = this.app.catalog.find(model => modelKey(model) === item.value);
         if (spec) await this.hooks.switchToModel(this.app, spec);
       } });
   }
-  private async saveDefaultModel(item: ListItem | undefined): Promise<void> {
-    const spec = item && this.app.catalog.find(model => modelKey(model) === item.value);
-    if (!spec || !this.app.ui) return;
-    const patch = { defaultModel: spec.id, defaultProvider: spec.provider };
-    await writeUserSettings(patch);
-    this.app.ui.userOverrides = { ...this.app.ui.userOverrides, ...patch };
-    this.app.ui.settings = { ...this.app.ui.settings, ...patch };
-    this.toast(`saved default model ${item.value}`, "success");
-  }
-
   openThinking(): void {
     const spec = this.app.providerConfig.spec, current = this.app.providerConfig.effort;
     this.push({ kind: "list", title: "Thinking", search: false, selected: current,
       items: THINKING_LEVELS.map(level => ({ value: level, label: level, disabled: !this.hooks.effortSupported(spec, level),
         ...(level === current ? { hint: "● current" } : !this.hooks.effortSupported(spec, level) ? { description: "not supported by this model" } : {}) })),
-      actions: [{ key: "ctrl+s", label: "save default", run: async item => {
-        const effort = item && asThinkingLevel(item.value);
-        if (!effort || !this.hooks.effortSupported(spec, effort) || !this.app.ui) return;
-        const patch = { modelThinkingLevels: { [modelKey(spec)]: effort } };
-        await writeUserSettings(patch);
-        this.app.ui.userOverrides = mergeSettings({ builtin: this.app.ui.userOverrides, user: patch });
-        this.app.ui.settings = mergeSettings({ builtin: this.app.ui.settings, user: patch });
-        this.toast(`saved default thinking ${effort}`, "success");
-      } }],
       onPick: async item => { const effort = asThinkingLevel(item.value) as Effort | undefined; if (effort) await this.hooks.applyThinking(this.app, effort, this); } });
   }
 
@@ -1273,10 +1259,9 @@ export class InteractiveApp implements Ui {
     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 });
-        if (this.app.ui) { this.app.ui.settings = { ...this.app.ui.settings, scopedModels: values }; this.app.ui.userOverrides = { ...this.app.ui.userOverrides, scopedModels: values }; }
+        const saved = await commitUserSettings(this.app, { scopedModels: values });
         this.app.args.models = ""; this.app.args.modelsExplicit = false;
-        this.toast(`saved ${values.length} scoped models`, "success");
+        if (saved) this.toast(`saved ${values.length} scoped models`, "success");
       } });
   }
 
@@ -1286,7 +1271,7 @@ export class InteractiveApp implements Ui {
     const entries: [string, string, string][] = [
       ["theme", "Theme", settings.theme ?? "dark"],
       ["thinking", "Thinking", this.app.providerConfig.effort],
-      ["defaultModel", "Default model", settings.defaultModel ? `${settings.defaultProvider}/${settings.defaultModel}` : "automatic"],
+      ["defaultModel", "Model", modelKey(this.app.providerConfig.spec)],
       ["modelThinkingLevels", "Model thinking defaults", `${Object.keys(settings.modelThinkingLevels ?? {}).length} configured`],
       ["steeringMode", "Steering delivery", settings.steeringMode ?? "one-at-a-time"],
       ["followUpMode", "Follow-up delivery", settings.followUpMode ?? "one-at-a-time"],
@@ -1334,9 +1319,7 @@ export class InteractiveApp implements Ui {
               ui.userOverrides = { ...ui.userOverrides, modelThinkingLevels: loaded.userOverrides.modelThinkingLevels ?? {} };
             } else {
               const patch = { modelThinkingLevels: { [item.value]: choice.value as Effort } };
-              await writeUserSettings(patch);
-              ui.settings = mergeSettings({ builtin: ui.settings, user: patch });
-              ui.userOverrides = mergeSettings({ builtin: ui.userOverrides, user: patch });
+              await commitUserSettings(this.app, patch);
             }
             this.screen.dialogs.pop(); this.openModelThinkingDefaults();
           } });

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/agent-profile.ts

@@ -0,0 +1,130 @@
+/** R13 / D13: explicit role layers share tool, model, workflow and budget ownership. */
+import { isWorkflowMode, type WorkflowMode } from "./workflow-mode.ts";
+import { isToolProfile, parsePermissionRule, type PermissionRule, type ToolSelection } from "./permissions.ts";
+import { asThinkingLevel, type ThinkingLevel } from "./thinking.ts";
+
+export interface AgentProfile {
+  readonly name: string;
+  readonly description?: string;
+  readonly mode?: WorkflowMode;
+  readonly instructions?: string;
+  readonly model?: { readonly provider: string; readonly id: string; readonly thinking?: ThinkingLevel };
+  readonly tools?: ToolSelection;
+  readonly permissions?: readonly PermissionRule[];
+  /** maxTurns is a hard cap; timeBudgetMs retains the existing advisory semantics. */
+  readonly budget?: { readonly maxTurns?: number; readonly timeBudgetMs?: number };
+}
+export type AgentProfileField = Exclude<keyof AgentProfile, "name">;
+export interface AgentProfileSource { readonly kind: "builtin" | "user" | "project" | "cli"; readonly path?: string }
+export interface AgentProfileLayer { readonly source: AgentProfileSource; readonly profiles: readonly AgentProfile[] }
+export interface ResolvedAgentProfile {
+  readonly profile: AgentProfile;
+  readonly sources: readonly AgentProfileSource[];
+  readonly provenance: Readonly<Partial<Record<AgentProfileField, AgentProfileSource>>>;
+}
+export interface AgentProfileParse { readonly profiles: readonly AgentProfile[]; readonly diagnostics: readonly string[] }
+
+/** Named builtins are explicit selectable presets; they never fill missing fields in another role. */
+export function builtinAgentProfileLayer(): AgentProfileLayer {
+  return { source: { kind: "builtin" }, profiles: [{ name: "build", mode: "build", tools: { profile: "foundation" } }, { name: "plan", mode: "plan", tools: { profile: "foundation" } },
+    { name: "reviewer", mode: "plan", tools: { profile: "readonly" },
+      instructions: "Review current code for actionable defects. Cite concrete evidence and paths; do not edit the workspace." }] };
+}
+
+const FIELDS: readonly AgentProfileField[] = ["description", "mode", "instructions", "model", "tools", "permissions", "budget"];
+export function isAgentProfileName(value: string): boolean { return /^[a-z][a-z0-9_-]{0,63}$/.test(value); }
+function record(value: unknown, label: string, allowed: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error(`${label} must be an object`);
+  const obj = value as Record<string, unknown>;
+  const unknown = Object.keys(obj).find(key => !allowed.includes(key));
+  if (unknown) throw Error(`${label} has unknown field ${unknown}`);
+  return obj;
+}
+function text(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim() || value.includes("\0")) throw Error(`${label} must be a nonempty string`);
+  return value;
+}
+function strings(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim()) || new Set(value).size !== value.length) throw Error(`${label} must contain unique nonempty names`);
+  return [...value] as string[];
+}
+
+export function parseAgentProfile(value: unknown): AgentProfile {
+  const obj = record(value, "agent profile", ["name", ...FIELDS]);
+  const name = text(obj["name"], "agent name");
+  if (!isAgentProfileName(name)) throw Error("agent name must begin with a lowercase letter and contain only letters, digits, _ or - (max 64)");
+  const profile: { name: string; description?: string; mode?: WorkflowMode; instructions?: string;
+    model?: NonNullable<AgentProfile["model"]>; tools?: ToolSelection; permissions?: PermissionRule[]; budget?: NonNullable<AgentProfile["budget"]> } = { name };
+  if (obj["description"] !== undefined) profile.description = text(obj["description"], "agent description");
+  if (obj["instructions"] !== undefined) profile.instructions = text(obj["instructions"], "agent instructions");
+  if (obj["mode"] !== undefined) {
+    if (typeof obj["mode"] !== "string" || !isWorkflowMode(obj["mode"])) throw Error("agent mode must be build or plan");
+    profile.mode = obj["mode"];
+  }
+  if (obj["model"] !== undefined) {
+    const model = record(obj["model"], "agent model", ["provider", "id", "thinking"]);
+    const provider = text(model["provider"], "agent model provider"), id = text(model["id"], "agent model id");
+    const thinking = asThinkingLevel(model["thinking"]);
+    if (model["thinking"] !== undefined && thinking === undefined) throw Error("agent model thinking is invalid");
+    profile.model = { provider, id, ...(thinking !== undefined ? { thinking } : {}) };
+  }
+  if (obj["tools"] !== undefined) {
+    const tools = record(obj["tools"], "agent tools", ["profile", "only", "exclude", "none", "noBuiltin"]);
+    const selected: { profile?: NonNullable<ToolSelection["profile"]>; only?: string[]; exclude?: string[]; none?: boolean; noBuiltin?: boolean } = {};
+    if (tools["profile"] !== undefined) {
+      if (typeof tools["profile"] !== "string" || !isToolProfile(tools["profile"])) throw Error("agent tool profile is invalid");
+      selected.profile = tools["profile"];
+    }
+    if (tools["only"] !== undefined) selected.only = strings(tools["only"], "agent tools.only");
+    if (tools["exclude"] !== undefined) selected.exclude = strings(tools["exclude"], "agent tools.exclude");
+    for (const key of ["none", "noBuiltin"] as const) {
+      if (tools[key] !== undefined) { if (typeof tools[key] !== "boolean") throw Error(`agent tools.${key} must be boolean`); selected[key] = tools[key]; }
+    }
+    profile.tools = selected;
+  }
+  if (obj["permissions"] !== undefined) {
+    if (!Array.isArray(obj["permissions"])) throw Error("agent permissions must be an array");
+    profile.permissions = obj["permissions"].map(parsePermissionRule);
+  }
+  if (obj["budget"] !== undefined) {
+    const budget = record(obj["budget"], "agent budget", ["maxTurns", "timeBudgetMs"]);
+    const selected: { maxTurns?: number; timeBudgetMs?: number } = {};
+    for (const key of ["maxTurns", "timeBudgetMs"] as const) {
+      if (budget[key] !== undefined) {
+        if (!Number.isSafeInteger(budget[key]) || Number(budget[key]) < 1) throw Error(`agent budget.${key} must be a positive safe integer`);
+        selected[key] = Number(budget[key]);
+      }
+    }
+    profile.budget = selected;
+  }
+  return profile;
+}
+
+/** A malformed document contributes no partial authority. */
+export function parseAgentProfiles(value: unknown): AgentProfileParse {
+  try {
+    const obj = record(value, "agents document", ["profiles"]);
+    if (!Array.isArray(obj["profiles"])) throw Error("agents document profiles must be an array");
+    const profiles = obj["profiles"].map(parseAgentProfile);
+    if (new Set(profiles.map(profile => profile.name)).size !== profiles.length) throw Error("agents document contains duplicate profile names");
+    return { profiles, diagnostics: [] };
+  } catch (error) { return { profiles: [], diagnostics: [error instanceof Error ? error.message : "Invalid agents document"] }; }
+}
+
+/** Caller supplies low-to-high layers; whole-field replacement stays explainable. */
+export function resolveAgentProfile(name: string, layers: readonly AgentProfileLayer[]): ResolvedAgentProfile | null {
+  let profile: AgentProfile | undefined;
+  const sources: AgentProfileSource[] = [], provenance: Partial<Record<AgentProfileField, AgentProfileSource>> = {};
+  for (const layer of layers) {
+    const matching = layer.profiles.find(item => item.name === name);
+    if (!matching) continue;
+    const source = structuredClone(layer.source);
+    sources.push(source); profile = { ...profile, ...structuredClone(matching) };
+    for (const field of FIELDS) if (matching[field] !== undefined) provenance[field] = structuredClone(source);
+  }
+  return profile ? { profile, sources, provenance } : null;
+}
+
+export function agentProfileNames(layers: readonly AgentProfileLayer[]): string[] {
+  return [...new Set(layers.flatMap(layer => layer.profiles.map(profile => profile.name)))].sort();
+}