@visual-z/xeno 0.4.0 → 0.5.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";
@@ -50,7 +50,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 +83,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";
@@ -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),
@@ -590,7 +595,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 +609,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 +642,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 +658,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 +1047,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 +1102,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 +1199,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 +1260,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 +1272,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 +1320,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/core/completion-review.ts

@@ -59,24 +59,33 @@ export function requestCompletion(state: RequestState, remainingRequests: number
 
   const gaps: string[] = [];
   const acceptance = options?.acceptance ?? state.acceptance;
+  const missingCommands = acceptance?.status === "needs_work" ? acceptance.criteria.flatMap(item =>
+    item.kind === "command" && item.status !== "pass" ? [{ id: item.id, command: item.command, status: item.status }] : []) : [];
   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}`),
+    ...missingCommands.map(item => `${item.id}=${item.status}`),
     ...(acceptance.targets ?? []).filter(target => target.status !== "ready").map(target => `target ${target.id}=${target.status}`),
   ].join(", ")}`);
   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 finish;
+  // D11 / O.11: a declared command needs its exact receipt even when the
+  // request has no recorded edit. Compound shell success is not that receipt.
+  const next = missingCommands.length > 0
+    ? "Obtain a fresh successful receipt for each missing command. Run each command exactly as a separate invocation without adding other commands:\n" +
+      missingCommands.map(item => `- ${item.id}: ${JSON.stringify(item.command)}`).join("\n") +
+      "\nIf verification cannot run, report the specific blocker. "
+    : options?.taskAware && !state.changed
+      ? "Use original sources for research and full inputs for calculations; do not invent command evidence. Finish with the result or the specific blocker. "
+      : "Run the command that verifies the result, or finish with the specific blocker that prevents verification. ";
   return { action: "continue", guidance: {
     reason: "completion_review",
     sources: [state.request.event, final.source.event],
     text: `Harness completion check: ${gaps.join("; ")}. ` +
       `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. ") +
+      next + (acceptance?.criteria.some(item => item.kind === "human" && item.status !== "accepted") ? "Required human acceptance remains pending. " : "") +
       "This check runs once per request.",
   } };
 }

package/src/core/model-preferences.ts

@@ -0,0 +1,28 @@
+/** User selections become startup preferences; restored session state stays in the log (D8/Q.25). */
+import { recordRecent } from "./model-picker.ts";
+import { modelKey } from "./session-position.ts";
+import { settingsToWrite, type Settings } from "./settings.ts";
+import type { ThinkingLevel } from "./thinking.ts";
+
+interface ModelIdentity { readonly provider: string; readonly id: string }
+
+/** Keep the effective effort with its model, without changing another model's saved effort. */
+export function modelPreferencePatch(model: ModelIdentity, recent: readonly string[], effort: ThinkingLevel): Settings {
+  return { defaultProvider: model.provider, defaultModel: model.id, recentModels: recordRecent(recent, modelKey(model)),
+    modelThinkingLevels: { [modelKey(model)]: effort } };
+}
+
+export function thinkingPreferencePatch(model: ModelIdentity, effort: ThinkingLevel): Settings {
+  return { defaultThinking: effort, modelThinkingLevels: { [modelKey(model)]: effort } };
+}
+
+/** Patch only known preferences; retain future keys and nested fields not owned by this selection. */
+export function mergePreferenceJson(previous: Readonly<Record<string, unknown>>, patch: Settings): Record<string, unknown> {
+  const next = { ...previous, ...settingsToWrite(patch) };
+  for (const key of ["terminal", "images", "markdown", "modelThinkingLevels"] as const) {
+    if (patch[key] === undefined) continue;
+    const old = previous[key];
+    next[key] = { ...(old !== null && typeof old === "object" && !Array.isArray(old) ? old : {}), ...patch[key] };
+  }
+  return next;
+}

package/src/core/permissions.ts

@@ -3,8 +3,8 @@
  * call is allow / ask / deny.
  *
  * Approval is the last look at what is about to run, not a boundary.
- * Path tools are already confined to the workspace root; bash is not,
- * which is why bash defaults to ask and everything else to allow.
+ * Path tools are already confined to the workspace root; host commands
+ * are not, which is why shell entry points default to ask.
  *
  * This module must stay free of I/O, clocks, and randomness. The CLI
  * compiles flags and session memory into a rule list; this file only
@@ -75,8 +75,8 @@ export interface ToolSelection {
 export const ALLOW_TOOLS_FLAG = "--allow-tools";
 
 /**
- * Product default. bash asks because it is not confined to the workspace
- * root; every other built-in is allow because the path tools are.
+ * Product default. Shell entry points ask because their effects are not
+ * confined to the workspace root; path tools keep their own confinement.
  */
 export function defaultRules(): readonly PermissionRule[] {
   return [
@@ -91,9 +91,15 @@ export function defaultRules(): readonly PermissionRule[] {
 }
 
 /**
- * `--allow-tools` compiled to rules, in front of the defaults so they win.
+ * CLI opt-ins compiled to one process-scoped rule list. YOLO permits every
+ * tool; capability admission and path confinement still apply (D13).
+ * Neither this flag nor remembered approvals become a persisted policy.
  */
-export function rulesWithAllowTools(allowTools: readonly string[]): PermissionRule[] {
+export function rulesWithAllowTools(
+  allowTools: readonly string[],
+  options: { readonly yolo?: boolean } = {},
+): PermissionRule[] {
+  if (options.yolo === true) return [{ action: "allow" }];
   return [
     ...allowTools.map((tool) => ({ action: "allow" as const, tool })),
     ...defaultRules(),
@@ -109,7 +115,7 @@ export function ruleMatches(rule: PermissionRule, request: PermissionRequest): b
 /**
  * First matching rule wins. An empty list allows: the tool tests pass no
  * rules because they are testing the tool, not the gate. The CLI always
- * supplies defaultRules().
+ * supplies the current process's compiled policy.
  */
 export function decide(
   rules: readonly PermissionRule[],

package/src/core/settings.ts

@@ -17,7 +17,7 @@ export interface Settings {
   readonly defaultThinking?: string;
   readonly modelThinkingLevels?: Readonly<Record<string, ThinkingLevel>>;
   readonly scopedModels?: readonly string[];
-  /** provider/model keys, most recent first; the /model picker's first section. */
+  /** provider/model keys, most recent first; picker ordering and startup fallback for older settings. */
   readonly recentModels?: readonly string[];
   readonly steeringMode?: "all" | "one-at-a-time";
   readonly followUpMode?: "all" | "one-at-a-time";

package/src/runtime/catalog.ts

@@ -186,7 +186,8 @@ export type Selection =
 
 /**
  * `--model` wins, then `--provider`'s first model, then the settings file,
- * then the first model in the catalog that has a credential.
+ * then a usable recent selection from older settings, then the first model
+ * in the catalog that has a credential.
  *
  * The last step is what makes a fresh install work: someone who exported one
  * API key should get a working session without also having to learn the name
@@ -229,6 +230,12 @@ export function selectModel(
     if (preferred !== undefined) return { ok: true, spec: preferred };
   }
 
+  // Old pickers only persisted recent identities. Reuse one exactly, without fuzzy guesses (Q.25).
+  for (const key of settings.recentModels ?? []) {
+    const recent = catalog.find(model => modelKey(model) === key);
+    if (recent !== undefined && hasCredential(recent)) return { ok: true, spec: recent };
+  }
+
   const authenticated = catalog.find(hasCredential);
   if (authenticated !== undefined) return { ok: true, spec: authenticated };
 

package/src/runtime/oauth.ts

@@ -18,7 +18,7 @@ import { pollDeviceCode } from "./oauth-device.ts";
 import { parseDeviceAuthorization, parseOAuthTokens } from "../core/oauth-fields.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.4.0";
+export const XENO_VERSION = "0.5.0";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge

package/src/runtime/tools.ts

@@ -370,7 +370,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     description:
       "Read a file. Returns the contents with 1-indexed line numbers. " +
       "Optionally limit to an inclusive line range. Reports total lines and the next range; end beyond EOF is clamped. " +
-      "Returns read_handle and whole-file sha256 for version checks. Long lines and large previews retain an immutable artifact. Line ranges describe the selection; the observation receipt describes exactly what was visible. An unavailable artifact-recovery capability leaves a gap, not proof of full coverage.",
+      "Session remembers the whole-file version for later changes; no digest copying is needed. Returns read_handle and whole-file sha256 for selecting an explicit observation. Long lines and large previews retain an immutable artifact. Line ranges describe the selection; the observation receipt describes exactly what was visible. An unavailable artifact-recovery capability leaves a gap, not proof of full coverage.",
     input_schema: {
       type: "object",
       properties: {
@@ -384,14 +384,14 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: "write",
     access: "write", execution: "exclusive", branch: "write", run: toolWrite,
-    description: "Write a file, creating parent directories. Replaces existing content. Pass read_handle or expected_sha256 for an explicit version check; otherwise Session uses its last observed version. create_only requires absence. A conflict requires a fresh read. Identical content makes no change.",
+    description: "Write a file, creating parent directories. Replaces existing content. Normally omit read_handle and expected_sha256: Session checks its latest observed version. Without a prior observation, omission has no stale-version protection. To select a specific observation instead, pass its exact version receipt. create_only requires absence. A conflict requires a fresh read. Identical content makes no change.",
     input_schema: {
       type: "object",
       properties: {
         path: { type: "string" },
         content: { type: "string" },
-        read_handle: { type: "string", description: "Descriptor SHA from an observation of this file, workspace and host" },
-        expected_sha256: { type: "string", description: "Expected whole-file raw-byte SHA-256" },
+        read_handle: { type: "string", description: "Optional explicit descriptor SHA for this file, workspace and host; normally omit" },
+        expected_sha256: { type: "string", description: "Optional explicit whole-file raw-byte SHA-256; normally omit" },
         create_only: { type: "boolean", description: "Require that the target does not exist; excludes read_handle and expected_sha256" },
       },
       required: ["path", "content"],
@@ -400,14 +400,16 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: "edit",
     example: { path: "src/main.ts", old_string: "const size = 1;", new_string: "const size = 2;" },
-    guidance: [{ requires: ["read"], text: "Use read to obtain current text and a version receipt before an edit." }],
+    guidance: [{ requires: ["read"], text: "Use read to obtain current text before an edit; Session remembers its version automatically." }],
     access: "write", execution: "exclusive", branch: "write", run: toolEdit,
     description:
-      "Replace exact text in a file. old_string must match once unless replace_all is set; copy it from observed file content, " +
+      "Replace exact text in a file. Normally omit read_handle and expected_sha256: Session checks its latest observed version. " +
+      "Without a prior observation, omission has no stale-version protection. To select a specific observation instead, pass its exact version receipt. " +
+      "old_string must match once unless replace_all is set; copy it from observed file content, " +
       "including indentation (line numbers are not part of the file). For several changes to one file pass edits[], " +
       "each matched against the original; all apply or none do. If there is no exact match, a unique match that differs only in " +
       "trailing whitespace, quote or dash style is applied and flagged fuzzy. A failure shows the closest text in the file. " +
-      "Pass read_handle or expected_sha256 from a file observation to reject stale edits; when omitted, Session uses its last observed version. A conflict requires a fresh observation. A partial read handle checks the whole file version, not permission to edit unseen lines.",
+      "A conflict requires a fresh observation. A partial read handle checks the whole file version, not permission to edit unseen lines.",
     input_schema: {
       type: "object",
       properties: {
@@ -419,8 +421,8 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
           type: "object", required: ["old_string", "new_string"], properties: {
             old_string: { type: "string", minLength: 1 }, new_string: { type: "string" }, replace_all: { type: "boolean" },
           } } },
-        expected_sha256: { type: "string", description: "Observed whole-file version; mismatch leaves the file unchanged" },
-        read_handle: { type: "string", description: "Descriptor SHA from an observation of this file, workspace and host" },
+        expected_sha256: { type: "string", description: "Optional explicit whole-file raw-byte SHA-256; normally omit" },
+        read_handle: { type: "string", description: "Optional explicit descriptor SHA for this file, workspace and host; normally omit" },
       },
       required: ["path"],
     },

package/src/store/resources.ts

@@ -2,8 +2,8 @@
  * Discover and read UI resources: settings, theme, keybindings, skills,
  * prompt templates.
  *
- * I/O lives here; validation is core. A corrupt file is a diagnostic plus
- * a fallback, never a throw -- startup has to survive a missing comma.
+ * I/O lives here; validation is core. Reads diagnose corrupt files and fall
+ * back so startup survives a missing comma. Writes preserve them and report failure.
  *
  * Project-level files follow the same trust rule as `.xeno/settings.json`.
  * Theme and keymap are UI state and are not logged.
@@ -12,7 +12,9 @@
 import { readdir, readFile } from "node:fs/promises";
 import { watch } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { configDir, readJsonFile, writeJsonFile, settingsPath } from "./config.ts";
+import { configDir, readJsonFile } from "./config.ts";
+import { editUserSettings } from "./user-settings.ts";
+import { mergePreferenceJson } from "../core/model-preferences.ts";
 import { discoverResources, themeResourcePath, type ResourceIndex } from "./resource-index.ts";
 import { parseSkill, type Skill } from "../core/skills.ts";
 import { parsePromptTemplate, type PromptTemplate } from "../core/prompts.ts";
@@ -29,7 +31,6 @@ import {
 import {
   defaultSettings,
   mergeSettings,
-  settingsToWrite,
   type Settings,
 } from "../core/settings.ts";
 
@@ -90,28 +91,18 @@ export function selectedThemePath(index: ResourceIndex, name: string, noThemes =
 }
 
 export async function writeUserSettings(overrides: Partial<Settings>): Promise<void> {
-  const { value, error } = await readJsonFile<unknown>(settingsPath());
-  const prev =
-    error === null && typeof value === "object" && value !== null && !Array.isArray(value)
-      ? (value as { readonly [k: string]: unknown })
-      : {};
-  const next = { ...prev, ...settingsToWrite(overrides),
-    ...(overrides.terminal ? { terminal: { ...(typeof prev["terminal"] === "object" ? prev["terminal"] : {}), ...overrides.terminal } } : {}),
-    ...(overrides.modelThinkingLevels ? { modelThinkingLevels: { ...(typeof prev["modelThinkingLevels"] === "object" ? prev["modelThinkingLevels"] : {}), ...overrides.modelThinkingLevels } } : {}),
-    ...Object.fromEntries((["images", "markdown"] as const).filter(key => overrides[key]).map(key => [key, { ...(typeof prev[key] === "object" ? prev[key] : {}), ...overrides[key] }])),
-  };
-  await writeJsonFile(settingsPath(), next, false);
+  const patch = structuredClone(overrides);
+  await editUserSettings(previous => mergePreferenceJson(previous, patch));
 }
 
 /** Remove only the user's override; project defaults and unrelated keys retain their ownership. */
 export async function removeModelThinkingOverride(identity: string): Promise<void> {
-  const { value, error } = await readJsonFile<Record<string, unknown>>(settingsPath());
-  if (error) throw new Error(error);
-  if (!value || typeof value !== "object" || Array.isArray(value)) return;
-  const levels = value["modelThinkingLevels"];
-  if (!levels || typeof levels !== "object" || Array.isArray(levels)) return;
-  const next = Object.fromEntries(Object.entries(levels).filter(([key]) => key !== identity));
-  await writeJsonFile(settingsPath(), { ...value, modelThinkingLevels: next }, false);
+  await editUserSettings(previous => {
+    const levels = previous["modelThinkingLevels"];
+    if (!levels || typeof levels !== "object" || Array.isArray(levels)) return null;
+    const next = Object.fromEntries(Object.entries(levels).filter(([key]) => key !== identity));
+    return { ...previous, modelThinkingLevels: next };
+  });
 }
 
 export async function resolveTheme(spec: string, diagnostics: string[]): Promise<Theme> {

package/src/store/user-settings.ts

@@ -0,0 +1,30 @@
+/** One read/modify/replace owner prevents automatic selections from racing other settings (Q.25). */
+import { readFile } from "node:fs/promises";
+import { settingsPath } from "./config.ts";
+import { atomicWrite } from "./atomic.ts";
+import { serialized } from "./serial.ts";
+
+async function readSettings(path: string): Promise<Record<string, unknown>> {
+  let text: string;
+  try { text = await readFile(path, "utf8"); }
+  catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return {};
+    throw error;
+  }
+  let value: unknown;
+  try { value = JSON.parse(text); }
+  catch { throw new Error(`${path} is not valid JSON; repair it before saving settings`); }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must contain a settings object`);
+  return value as Record<string, unknown>;
+}
+
+export function editUserSettings(edit: (previous: Record<string, unknown>) => Record<string, unknown> | null): Promise<void> {
+  // Capture the destination before any await, including when another profile changes configDir().
+  const path = settingsPath();
+  // Packages and resource overrides already coordinate this file through serialized().
+  return serialized(path, async () => {
+    const next = edit(await readSettings(path));
+    if (next === null) return;
+    await atomicWrite(path, `${JSON.stringify(next, null, 2)}\n`);
+  });
+}

package/src/tui/ui/control-panel.ts

@@ -1,5 +1,5 @@
 /** View-only data: apps owns the projection and actions, as required by D20. */
-import { clipText } from "./edge.ts";
+import { wrapPlain } from "../diff.ts";
 
 export type ControlPanelModel = {
   thread: string; turn: string | null; goal: string; status: string; execution: string; gaps: readonly string[];
@@ -10,14 +10,16 @@ export type ControlTab = "goal" | "progress" | "context";
 export type ControlFocus = "messages" | "omitted" | "history";
 
 export function controlPanelLines(model: ControlPanelModel, tab: ControlTab, width: number, focus: ControlFocus = "messages"): string[] {
-  const lines = [`${tab === "goal" ? "●" : "○"} Goal    ${tab === "progress" ? "●" : "○"} Progress    ${tab === "context" ? "●" : "○"} Context Lens`, "",
-    ...(tab === "goal" ? [model.goal, `Goal: ${model.status}`, `Execution: ${model.execution}`, "", ...model.gaps,
+  const lines = tab === "goal" ? [model.goal, `Goal: ${model.status}`, `Execution: ${model.execution}`, "", ...model.gaps,
       ...model.checks, "", `Thread ${model.thread}`, `Turn ${model.turn ?? "none"}`]
       : tab === "progress" ? ["Evidence for this request", ...model.progress.map(item => `${item.label}: ${item.count}`), "",
         "Counts describe observations, not a completion percentage.", ...model.checks,
         ...model.progress.flatMap(item => item.sources.map(source => `${item.label}: ${source}`))]
       : focus === "messages" ? ["Actual model context · ←/→ change lens", ...model.context]
         : focus === "omitted" ? ["Not replayed as messages · ←/→ change lens", ...(model.omitted.length ? model.omitted : ["No omitted events in this segment."])]
-          : ["Handoff retention and recovery · ←/→ change lens", ...(model.history.length ? model.history : ["No carried history in this segment."])])];
-  return lines.map(line => clipText(line.replace(/[\x00-\x1f\x7f-\x9f]/g, " "), Math.max(1, width)));
+          : ["Handoff retention and recovery · ←/→ change lens", ...(model.history.length ? model.history : ["No carried history in this segment."])];
+  // Unlike status chrome, evidence is inspectable content: every character must
+  // remain reachable by scrolling, including long source paths and CJK (Q24).
+  // A one-cell pane cannot show a wide glyph; its owner shows resize feedback.
+  return lines.flatMap(line => wrapPlain(line.replace(/[\x00-\x1f\x7f-\x9f]/g, " "), Math.max(2, width)));
 }