@visual-z/xeno 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # xeno changelog
 
+## 0.8.0 — 2026-10-10
+
+xeno now proves completion with receipts, and proves the receipts test the change. Two changes need attention when upgrading:
+- Sessions saved by 0.7.x and earlier no longer open. They are left on disk unmodified; start a new session with `--fresh`.
+- A message no longer stops after 40 model requests by default. The stall watchdog ends a run that stops producing new evidence; pass `--max-turns N` for a hard cap.
+
+Verification-first (research doc appendix S):
+- `/goal <objective>` sets an explicit goal.
+  - The model drafts acceptance criteria in one read-only request: it may read the workspace, but cannot change it or run commands. You accept the criteria one by one.
+  - A draft that does not parse goes back to the model once with the reasons. A goal that cannot be checked here is reported with the model's reason, and no goal is set.
+  - Work continues until every accepted check has a fresh passing receipt.
+  - A check that fails the same way twice against an unchanged workspace is reported as possibly broken instead of being rerun. An accepted check is never rewritten.
+  - A reported blocker, a spent budget, the stall watchdog, or two goal checks answered without acting stop the loop and leave the goal active.
+  - `/goal` shows its status and `/goal clear` ends it.
+- Passing goal checks are counter-checked. Each one is re-run in a copy-on-write clone with the request's changes undone, including changes made by shell commands; the undo comes from a snapshot taken when the goal request starts. A check that still passes is named as not testing the change.
+- Guards: a command criterion with `"guard": true` protects what the goal must not break, such as "the tests are unchanged". It must pass before and after the work, and the counter-check expects it to pass without the changes too.
+  - Drafts propose guards, and the checklist and `/goal` mark them.
+  - A guard that held no longer counts as a check that does not test the change.
+- `--blind-checks <dir>` adds hidden checks from outside the workspace. They run on a clone of the final result after the goal's checks pass, and a pass the model could have seen is reported as exposed.
+- Every request now shows its evidence ladder in the sidebar and `/control`: ran, tests the change, independent, human accepted.
+- Without a contract, a request now reports `not_applicable`, `unchecked`, or `checked` after its last change, instead of a constant `unverified`.
+- A blocker reported by the model is listed but no longer changes the status or skips the completion check.
+- A failed `/resume` no longer leaves the current session's integrations closed.
+- xeno's state directory ignores itself, so `git status` and scope checks no longer see session files.
+
+From a session review (research doc appendix S.6):
+- There is no request cap per message by default, as in Claude Code, Codex, Gemini CLI and OpenCode. The stall watchdog stops a run after 12 exchanges without new evidence. `--max-turns N` and agent budgets still set a hard cap with a reserved final answer.
+- A command that exits nonzero but prints something new counts as progress. An exchange that repeats the previous one exactly earns nothing from output that only changes with timing.
+- A read, query or lsp call under a newly found subdirectory AGENTS.md runs, and the rules come with its result instead of costing a retry. Changes are still held back until the rules have been read. A batch of calls gets each file once.
+- grep and find skip git-ignored files inside a Git work tree and are no longer cut off after the first 20,000 files. A path that names an ignored directory is still searched.
+- A read too large for one result stops at a line boundary and names the next line. It no longer hides the middle while claiming the end of the file.
+- An out-of-range `yield_time_ms` is clamped to 100–30000 ms instead of refusing the command, and the receipt names the wait actually taken.
+- Exiting prints `resume with: xeno --resume <id>` instead of the session's full path when that id resolves from the current directory.
+
+Breaking:
+- Sessions written by earlier versions are refused with their location and are left unmodified. Start a new session with `--fresh`.
+- Full-snapshot workspace tracking is gone; journaled checkpoints are the only file history.
+
+Maintenance:
+- Evaluation code moved to `eval/` and out of the npm package (351 → 322 files) and the default gate.
+- The version now lives only in `package.json`.
+- Eight settings that nothing applied were removed.
+
 ## 0.7.2 — 2026-10-10
 
 - `/update` now installs the newer release when xeno was installed with bun or npm, instead of only printing the command. The status line shows the target version, elapsed time against a 3-minute limit and the package manager's latest output; success asks for a restart, and a failure gives the reason and the command to run by hand. Automatic checks still never install, and `xeno update --check` still only checks.

package/README.md

@@ -17,8 +17,8 @@ is ever summarized by a model, and nothing is ever rewritten in place.
 messages[]                             frozen system prefix + handoff + this node's events
 ```
 
-Version **0.7.2**. The on-disk session format will still change; `0.x` is that
-statement. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
+The on-disk session format will still change; `0.x` is that statement, and
+`xeno --version` reports the installed release. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
 
 ## Install
 
@@ -72,7 +72,7 @@ checks are reported separately from model accuracy.
 The explicit-policy follow-up separates segmented, continuous and adaptive context
 views. Its budget-limited result and negative cases are recorded in the same report;
 neither segmentation nor the experimental adaptive rule has established a quality advantage.
-`bun run scripts/compare-harness.ts smoke --output /absolute/new/smoke-directory`
+`bun run eval/scripts/compare-harness.ts smoke --output /absolute/new/smoke-directory`
 also exercises xeno-windowed, xeno-continuous and an installed Pi CLI with shared
 confined tools, without paid model calls. The comparison Pi CLI runs on Node through
 an isolated local tool bridge; xeno's providers use the pinned Pi AI runtime described below.
@@ -85,8 +85,8 @@ This checks a controlled configuration, not stock Pi or an official leaderboard.
 The new single-factor protocol separately compares tool profiles, the carried
 working set, and strict verification. It runs four isolated scenarios through
 real sessions and grades files, fresh command evidence, and pending human review.
-Use `bun scripts/eval-harness.ts smoke --output /absolute/new/eval-directory`,
-then `bun scripts/eval-harness.ts audit --output /absolute/new/eval-directory`.
+Use `bun eval/scripts/eval-harness.ts smoke --output /absolute/new/eval-directory`,
+then `bun eval/scripts/eval-harness.ts audit --output /absolute/new/eval-directory`.
 Smoke has no paid requests and reports synthetic usage. `plan` and `run` require
 the same explicit numeric `--budget`; inputs, source, schemas, model settings,
 and paired order are frozen before spending. Started directories cannot be
@@ -123,11 +123,34 @@ xeno [-m <model>] [--provider <name>] [--api-key <key>]
   verification state and diagnostic progress across segment cuts and restarts.
   Short tasks need no `note` calls to associate evidence. Without a declared
   acceptance contract, successful commands remain evidence rather than verified
-  task completion. Diagnostic novelty does not change the stall policy.
+  task completion. A command's new output counts as progress for the stall
+  watchdog whatever its exit code; an exchange that repeats the previous one
+  exactly earns none from output that only changes with timing.
+- `/goal <objective>` sets an explicit goal:
+  - The model first drafts acceptance criteria in a single read-only request: it may read the workspace (read, find, grep) but cannot change it or run commands. Each criterion is a command that should fail until the goal is done, a human check, or a guard.
+  - A guard (`"guard": true` on a command) protects what the goal must not break, such as "the test file is unchanged" or "only plan.md changed". It passes before the work and must still pass after it. Guards are marked in the checklist.
+  - A draft that does not parse goes back to the model once with the reasons. If the model says the goal cannot be checked in this workspace, it gives the reason and no goal is set.
+  - You accept the criteria one by one: a checklist in the TUI, or `/goal accept all|1,3` in line mode.
+  - Work then starts from the objective and continues automatically until every accepted criterion has a fresh passing receipt (and human criteria have your `/accept`).
+  - It stops early, with the goal still active, when the model reports a blocker, answers two goal checks without acting, a `--max-turns` budget runs out, or the stall watchdog fires.
+  - `/goal` shows the goal and the status of each criterion; `/goal clear` ends it.
+  - "Met" comes from receipts and your decisions, never from the model saying it is done.
+  - When the accepted checks pass, each one is counter-checked: it is re-run in a disposable copy-on-write clone of the workspace with this request's file changes undone.
+    - It reports whether the check fails without the changes (it tests them) or still passes (it does not).
+    - A guard is expected to pass there. If it does, it "held" and does not count against the evidence ladder. If it fails there, it "did not hold": the check actually tests the change, and it counts as such.
+    - If every check is a guard that held, the ladder says that no check tests the change.
+    - The undo comes from a snapshot taken when the goal request starts (a private Git directory and index; your HEAD, index and stash are untouched), so changes made by shell commands are undone too.
+    - If the starting state cannot be rebuilt exactly, the result is "unavailable", for example outside a Git work tree when a shell command wrote files that no checkpoint recorded.
+    - The real workspace is never touched, and the counter-check never blocks the goal.
+  - `--blind-checks <dir>` adds hidden checks: a directory outside the workspace holding `blind.json` (`{"version":1,"checks":[{"id","description","command"}]}`) and any fixtures.
+    - The checks are frozen when the session starts and never shown to the model.
+    - When the goal's checks pass, they run against a clone of the final workspace, with the directory copied in as `.xeno-blind/`.
+    - The whole log is scanned first, and a pass after the model named the directory or read one of its files is reported as `exposed`, not independent.
 - `/acceptance` shows declared command checks and human criteria. `/accept ID`
   records your acceptance of a human criterion; subsequent edits invalidate it.
   Use `--acceptance-file` or a trusted project's `.xeno/acceptance.json` with
   `{ "version": 1, "id": "task", "criteria": [{ "id": "tests", "kind": "command", "description": "tests pass", "command": "bun test" }] }`.
+  Add `"guard": true` to a command criterion that must keep passing rather than one that shows the work was done.
   The declaration is frozen in the session. A normal execution exit does not
   imply that human acceptance has been granted.
   A contract may additionally declare `targets`, each with `id`, `build`
@@ -372,7 +395,9 @@ Shipped, not planned:
   `branch`, `resolve`, `grep`, `find`, `ls`, `history`, `query`. `grep` / `find` use `rg` /
   `fd` when those binaries are on `PATH`, otherwise a TypeScript walk;
   both paths share one output format. They do not follow symlinks out of
-  the workspace.
+  the workspace. Inside a Git work tree they skip git-ignored files, as
+  Claude Code, OpenCode and Pi do; a path that names an ignored directory is
+  still searched.
 - `history` searches the active ancestry, retrieves original events, and pages
   immutable full observations. `query` filters and computes aggregates over
   complete CSV, JSON, JSONL or text files, with source hashes. It evaluates a
@@ -506,7 +531,9 @@ An empty `write_stdin` in an agent session waits for new output, command exit,
 hard timeout, cancellation or user steering. The process owner holds that wait;
 quiet commands do not consume model requests through periodic polling.
 Sending input and low-level process polling keep their bounded yield contract.
-For `--max-turns N`, budgets above one reserve the last request for a text answer.
+There is no request cap by default, as in Claude Code, Codex, Gemini CLI and
+OpenCode: the stall watchdog stops a run after 12 exchanges without new
+evidence. For `--max-turns N`, budgets above one reserve the last request for a text answer.
 Tools stay frozen and are disabled for that request, with host enforcement.
 Unsupported protocols or a failed final response use an evidence-based stop
 report inside the same budget. `/usage` labels provider durations as model time.
@@ -632,7 +659,7 @@ diagnostic and 100 consecutive derivations with retained state. The cost formula
 models input caching at the stated rates; it omits task quality and cannot prove
 30k/40k is globally optimal. These legacy bounds retain their 5k work floor.
 
-`scripts/ab-suite.ts` now separates node, replay, round-preserving truncation and
+`eval/scripts/ab-suite.ts` now separates node, replay, round-preserving truncation and
 observation masking. It uses a seeded shuffled schedule and includes output cost
 and failed outcomes. Historical A/B figures predate these corrections and cannot
 establish superiority over the corrected baselines. No new live-model result is

package/docs/foundations.md

@@ -71,7 +71,7 @@ apply_patch 参数为 `{patchText,expected_sha256?}`，语法使用 `*** Begin P
 
 format 参数为 `{paths:[...]}`，只执行配置中的 literal argv；`$FILE` 替换为绝对路径。每条命令经真实拥有者、审批、退出码与检查点执行，不会在 edit 后暗中格式化。读到新的文件版本后再生成后续编辑。
 
-启动从 Git 根到 cwd 加载目录规范。首次碰到目标文件的更深层 AGENTS.md / AGENTS.override.md 时，工具先返回带来源和 scope 的指令回执，原操作未执行；模型读到后可显式重试。回执追加到原始日志并按内容指纹去重，保留冻结前缀和旧事件。
+启动从 Git 根到 cwd 加载目录规范。首次碰到目标文件的更深层 AGENTS.md / AGENTS.override.md 时：read / query / lsp 照常执行，规范（带来源和 scope）附在同一个结果之后；write / edit / apply_patch / format 先返回指令回执，原操作未执行，模型读到后可显式重试。同一批调用里一份规范只下发一次，后到的修改只指向先附上规范的那次调用。规范追加到原始日志并按内容指纹去重，保留冻结前缀和旧事件。
 
 ## Diff、Review 与 LSP
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "license": "UNLICENSED",
   "type": "module",
   "description": "Segmented append-only agent log with pure context and handoff projections",
@@ -32,6 +32,8 @@
     "typecheck": "bun run scripts/typecheck.ts",
     "check": "bun run scripts/check-boundaries.ts",
     "gate": "bun test && bun run typecheck && bun run scripts/check-boundaries.ts",
+    "eval:test": "bun test ./eval/test",
+    "gate:full": "bun run gate && bun run eval:test",
     "verify-red": "bun run scripts/verify-red.ts",
     "regen-golden": "bun run scripts/regen-golden.ts",
     "measure": "bun run scripts/measure-handoff.ts",

package/src/apps/cli.ts

@@ -24,6 +24,8 @@ import { sessionControl } from "../runtime/session-control.ts";
 import { listenControl } from "./control-transport.ts";
 import { runAppServer } from "./app-server.ts";
 import { runManualUpdate } from "./update-check.ts";
+import { XENO_VERSION } from "../runtime/version.ts";
+import { closeAppSession } from "./session-lifecycle.ts";
 import { runAcpServer } from "./acp-server.ts";
 import { runReview, reviewScopeFromText } from "./review.ts";
 
@@ -42,8 +44,7 @@ try {
     printCliHelp();
   } else if (args.version) {
     if (args.extensionArgv) throw new Error("Unknown flags for --version");
-    const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json() as { version: string };
-    console.log(pkg.version);
+    console.log(XENO_VERSION);
   } else if (args.exportFile) {
     if (args.extensionArgv) throw new Error("Unknown flags for offline export");
     console.log(`Exported ${await exportHtmlFile(args.exportFile, args.prompt || undefined, args.workspace)}`);
@@ -70,7 +71,7 @@ try {
     } else if (reviewMode) {
       input.restore();
       try { await runReview(app, reviewScopeFromText(args.prompt)); }
-      finally { await app.session.dispose(); await app.extensions?.dispose(); }
+      finally { await closeAppSession(app); }
     } else {
       if (args.print) {
         // With a prompt already given, stdin is optional context: wait briefly for it.

package/src/apps/commands.ts

@@ -31,6 +31,8 @@ export type Command =
   | { kind: "branches"; action?: "wait" | "cancel" | "status"; node?: number }
   | { kind: "processes" }
   | { kind: "accept"; criterion: string }
+  | { kind: "goal"; action: "status" } | { kind: "goal"; action: "clear" } | { kind: "goal"; action: "accept"; pick: string }
+  | { kind: "goal"; action: "set"; objective: string }
   | { kind: "model"; pattern?: string }
   | { kind: "scoped-models" }
   | { kind: "login"; provider?: string }
@@ -85,6 +87,7 @@ export const COMMANDS = [
   { name: "branches", description: "Inspect or join owned background work", argumentHint: "[wait|cancel|status node]", busy: "idle" },
   { name: "processes", description: "Show process observations and available handles", busy: "run" },
   { name: "accept", description: "Record your acceptance of a human criterion", argumentHint: "<criterion ID>", busy: "idle" },
+  { name: "goal", description: "Set a goal: the model drafts checks, you accept them, work continues until they pass", argumentHint: "<objective> | clear | accept all|1,3", busy: "idle" },
   { name: "export", description: "Export HTML or JSONL", argumentHint: "[file]", busy: "idle" },
   { name: "import", description: "Import a portable JSONL session", argumentHint: "<file>", busy: "idle" },
   { name: "debug", description: "Write local terminal diagnostics", argumentHint: "[file]", busy: "run" },
@@ -213,6 +216,11 @@ export function parseCommand(input: string, catalog?: SlashCatalog): Command {
         ? { kind: "branches", action, node } : { kind: "unknown", input: text };
     }
     case "/accept": return { kind: "accept", criterion: arg };
+    case "/goal":
+      if (!arg) return { kind: "goal", action: "status" };
+      if (arg === "clear") return { kind: "goal", action: "clear" };
+      if (rest[0] === "accept") return { kind: "goal", action: "accept", pick: rest.slice(1).join(" ") };
+      return { kind: "goal", action: "set", objective: arg };
     case "/model":
       return arg.length > 0 ? { kind: "model", pattern: arg } : { kind: "model" };
     case "/provider":

package/src/apps/goal-flow.ts

@@ -0,0 +1,70 @@
+/**
+ * The drafting half of /goal shared by the line shell and the TUI (S.2 / S.5):
+ * one read-only request, then the reply parsed into candidate criteria.
+ * Nothing here decides what is accepted; that is the user's pick.
+ */
+import { draftReply, GOAL_DRAFT_RETRIES, goalDraftRequest, goalDraftRetry, parseGoalDraft } from "../core/goal.ts";
+import type { AcceptanceCriterion } from "../core/acceptance.ts";
+import type { RequestOptions } from "../runtime/loop.ts";
+import type { App } from "./startup.ts";
+
+export type PendingGoal = { objective: string; draft: string; criteria: AcceptanceCriterion[] };
+
+/**
+ * Runs the draft request and reads the candidates from its reply; null when
+ * there is nothing to accept. `runDraft` answers false for a draft that was
+ * not sent or was cancelled. A draft that does not validate goes back to the
+ * model once with the parser's reasons (GOAL_DRAFT_RETRIES); a reported
+ * blocker is an answer and does not.
+ */
+export async function draftGoal(app: App, objective: string,
+  runDraft: (prompt: string, options: RequestOptions) => Promise<boolean>): Promise<PendingGoal | null> {
+  const C = app.io.palette;
+  let prompt = goalDraftRequest(objective);
+  for (let attempt = 0; ; attempt++) {
+    const mark = app.session.state.events.at(-1)?.id;
+    if (!await runDraft(prompt, { readOnly: true })) return null;
+    const events = app.session.state.events;
+    // Only what this run recorded. A segment cut meanwhile removes the mark, and then the whole segment is new.
+    const reply = draftReply(events.slice(events.findIndex(event => event.id === mark) + 1));
+    if (!reply) { app.io.say(C.yellow("  the goal draft produced no reply; the goal was not set")); return null; }
+    const parsed = parseGoalDraft(reply.text);
+    for (const error of parsed.errors) app.io.say(C.yellow(`  draft ${error}`));
+    if (parsed.errors.length > 0 && !parsed.blocked && attempt < GOAL_DRAFT_RETRIES) {
+      app.io.say(C.dim("  the draft goes back to the model once to be corrected"));
+      prompt = goalDraftRetry(parsed.errors);
+      continue;
+    }
+    if (parsed.criteria.length === 0) {
+      app.io.say(C.yellow(parsed.blocked ? `  the model says this goal cannot be checked here: ${parsed.blocked}. The goal was not set`
+        : "  the draft has no usable criteria; the goal was not set. Run /goal again or rephrase the objective"));
+      return null;
+    }
+    return { objective, draft: reply.id, criteria: parsed.criteria };
+  }
+}
+
+/**
+ * One drafted criterion as the user decides on it, the same in the line shell
+ * and the TUI checklist: what runs, and whether it is a guard -- a check that
+ * must keep passing rather than one that shows the work was done (S.7).
+ */
+export function criterionSummary(item: AcceptanceCriterion): string {
+  return item.kind === "human" ? `human · ${item.description}` : `${item.guard ? "guard · " : ""}${item.command} · ${item.description}`;
+}
+
+/** `all`, or 1-based positions such as `1,3`. Unknown positions are refused, never skipped. */
+export function pickCriteria(criteria: readonly AcceptanceCriterion[], pick: string): { ok: true; ids: string[] } | { ok: false; error: string } {
+  const text = pick.trim();
+  if (text === "all") return { ok: true, ids: criteria.map(item => item.id) };
+  const positions = text.split(/[\s,]+/).filter(Boolean);
+  if (positions.length === 0) return { ok: false, error: "name the criteria to accept: /goal accept all, or /goal accept 1,3" };
+  const ids: string[] = [];
+  for (const position of positions) {
+    const index = Number(position);
+    if (!Number.isSafeInteger(index) || index < 1 || index > criteria.length) return { ok: false, error: `no drafted criterion ${position}` };
+    const id = criteria[index - 1]!.id;
+    if (!ids.includes(id)) ids.push(id);
+  }
+  return { ok: true, ids };
+}

package/src/apps/render.ts

@@ -170,8 +170,6 @@ export function formatEvent(
     case "turn_start":
     case "branch_start":
     case "branch_done":
-    case "snapshot_failed":
-    case "undeclared_change":
     case "text_delta":
     case "thinking_delta":
     case "discard":

package/src/apps/session-hub.ts

@@ -6,6 +6,7 @@ import { readCursor, writeCursor } from "../store/log.ts";
 import { SessionHub } from "../runtime/session-hub.ts";
 import { sessionControl, type SessionControl } from "../runtime/session-control.ts";
 import { openSessionFor, sessionDirFor, type App } from "./startup.ts";
+import { appSessionFields, closeAppSession } from "./session-lifecycle.ts";
 import { interactiveHooks } from "./shell.ts";
 import { parseMcpServers } from "../core/mcp-config.ts";
 import { reloadAppResources } from "./resources.ts";
@@ -68,9 +69,8 @@ export function createAppSessionHub(initial: App): SessionHub {
         askSlot: {}, catalog: initial.catalog, auth: initial.auth, credentialOf: initial.credentialOf, effects: initial.effects,
         interactive: false, projectTrusted: initial.projectTrusted === true, settings: initial.ui?.settings ?? {},
         fallback: initial.providerConfig });
-      const app: App = { ...initial, args, ...opened, loadedContext: opened.resources.loadedContext, ui: opened.resources.ui,
-        slash: opened.resources.slash, extensions: opened.resources.extensions, resources: opened.resources.index,
-        foundation: opened.resources.foundation, projectTrusted: opened.resources.trusted, askSlot: opened.session.config.tools.askSlot ?? {} };
+      const app: App = { ...initial, args, ...appSessionFields(opened), logDir, askSlot: opened.session.config.tools.askSlot ?? {} };
+      if (!opened.resources.foundation) delete app.foundation;
       const control: SessionControl = sessionControl(app.session);
       try {
       app.askSlot.current = request => control.ask(request);
@@ -79,7 +79,7 @@ export function createAppSessionHub(initial: App): SessionHub {
       apps.set(control.threadId, app);
       return control;
       } catch (error) {
-        await app.session.dispose().catch(() => {}); await app.extensions?.dispose().catch(() => {}); throw error;
+        await closeAppSession(app).catch(() => {}); throw error;
       }
       };
       const result = construct();
@@ -89,7 +89,8 @@ export function createAppSessionHub(initial: App): SessionHub {
     },
     dispose: async control => {
       const app = apps.get(control.threadId);
-      await control.session.dispose(); await app?.extensions?.dispose(); apps.delete(control.threadId);
+      if (app) await closeAppSession(app); else await control.session.dispose();
+      apps.delete(control.threadId);
     },
   });
 }

package/src/apps/session-lifecycle.ts

@@ -0,0 +1,64 @@
+/**
+ * The one place an App gains, swaps and drops its session.
+ *
+ * Startup, the line and full-screen shells, and the app-server hub each used
+ * to carry their own copy of this: the field mapping from an opened session,
+ * the paired session/extension shutdown, and the swap. The copies drifted --
+ * resource reload restored released integrations on failure while a session
+ * switch did not, so a refused /resume left the current session's services
+ * closed (refactor-session-lifecycle).
+ */
+import type { App, openSessionFor } from "./startup.ts";
+
+type Opened = Awaited<ReturnType<typeof openSessionFor>>;
+type SessionFields = Pick<App, "session" | "providerConfig" | "credential" | "workspace" | "blobDir" | "system" | "loadedContext" |
+  "slash" | "ui" | "resources" | "projectTrusted" | "extensions" | "foundation">;
+
+/** Everything an App holds that belongs to its current session, from one opened session. */
+export function appSessionFields(opened: Opened): SessionFields {
+  return {
+    session: opened.session, providerConfig: opened.providerConfig, credential: opened.credential,
+    workspace: opened.workspace, blobDir: opened.blobDir, system: opened.system,
+    loadedContext: opened.resources.loadedContext, slash: opened.resources.slash, ui: opened.resources.ui,
+    resources: opened.resources.index, projectTrusted: opened.resources.trusted,
+    extensions: opened.resources.extensions,
+    ...(opened.resources.foundation ? { foundation: opened.resources.foundation } : {}),
+  };
+}
+
+/** Session first: its last events may still reach extension hooks. */
+export async function closeAppSession(app: Pick<App, "session" | "extensions">): Promise<void> {
+  await app.session.dispose();
+  await app.extensions?.dispose();
+}
+
+/**
+ * Moves an App to the session at `logDir`, or leaves it exactly as it was.
+ *
+ * The new session opens before the current one closes, so a refused or broken
+ * target never strands the user without a session. Integrations are released
+ * first because a new generation must not overlap an unresolved callback of
+ * the current one (Q.13); every failure after that restores them, the same
+ * rule reloadAppResources follows.
+ */
+export async function switchAppSession(app: App, logDir: string, open: (app: App, logDir: string) => Promise<Opened>): Promise<void> {
+  app.session.cancel();
+  await app.session.whenIdle();
+  const extensions = app.extensions;
+  if (extensions && !await extensions.releaseIntegrations()) {
+    extensions.restoreIntegrations();
+    throw Error("An integration still owns unfinished work or unconfirmed cleanup. Wait for it to settle before switching sessions");
+  }
+  let opened: Opened;
+  try { opened = await open(app, logDir); }
+  catch (error) { extensions?.restoreIntegrations(); throw error; }
+  try { await closeAppSession(app); }
+  catch (error) {
+    // The current session could not close cleanly; do not also strand the new one.
+    await closeAppSession({ session: opened.session, extensions: opened.resources.extensions }).catch(() => {});
+    extensions?.restoreIntegrations();
+    throw error;
+  }
+  Object.assign(app, appSessionFields(opened), { logDir });
+  if (!opened.resources.foundation) delete app.foundation;
+}