gentle-pi 2.6.3 → 2.7.0

package/README.md

@@ -140,8 +140,8 @@ Review the exact change, not a moving target. Native review keeps one candidate
 
 The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) brings a more persistent, inspectable Pi workspace:
 
-- **Shell:** registered worktrees survive reloads; `/gentle:changes` groups dirty roots with diffs, status, and line counts; fullscreen navigation, responsive sidebars, and cached frames stay live without unnecessary redraws.
-- **Agents and profiles:** the Agents view shows orchestrator/session hierarchy, retained completion, abort, and lost-exit history, parent-child handoff, and model, effort, and usage observability. Named `/gentle:profiles` atomically route the orchestrator independently from packaged and review roles.
+- **Shell:** `/gentle:changes` groups captured write/edit changes from the current agent session and its subagents, without startup repository scans; fullscreen navigation, sidebars, and mouse support stay available. See the [capture limits and shell-command coverage](docs/gentle-shell.md#what-appears-in-changes).
+- **Agents and profiles:** the Agents view shows orchestrator/session hierarchy, retained completion, abort, and lost-exit history, parent-child handoff, and model, effort, and usage observability. Named `/gentle:profiles` atomically route the orchestrator independently from packaged and review roles; applying one replaces the routing of every agent, and the panel shows the routing the runtime actually uses even when `models.json` is sparse.
 - **Control and recovery:** native SDD requires parent-confirmed preflight; native review supports intended-untracked selection, consent, and provider continuations. Subsystems install with explicit recovery guidance when npm lifecycle scripts were skipped; Pi Git installs are recognized globally; custom ask responses are opt-in. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
 
 ---

package/docs/gentle-shell.md

@@ -13,7 +13,7 @@ The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases
 - The Agents List and Details views preserve the orchestrator/session hierarchy and completion, abort, and lost-exit history. Parent-child queries and notifications have an explicit handoff path, while model, effort, and usage stay observable per task.
 - Named `/gentle:profiles` atomically route the orchestrator separately from packaged and review roles; see the [technical reference](readme-reference.md#agent-model-profiles) for the profile model.
 
-The source checkout currently prepares `gentle-pi` `2.6.3` with a package-local Gentle AI `v2.9.0` pin; this is not a claim that `2.6.3` is published.
+The source checkout currently prepares `gentle-pi` `2.7.0` with a package-local Gentle AI `v2.9.1` pin; this is not a claim that `2.7.0` is published.
 
 ## Shell interactions and runtime behavior
 
@@ -23,6 +23,8 @@ In fullscreen at 140 columns or wider, the right sidebar scrolls **✿ Gentle-Pi
 
 The rail reuses its last frame until something it paints changes, so silent frames stay cheap and live session state still lands on the next frame: a model switch, a new thinking level, context growth, session cost, session name and extension statuses all refresh the Status card without a redraw of the rest of the sidebar.
 
+The sidebar Status card also shows `Profile` in its Model section when the profiles store has a valid active marker. It follows profile changes on the next render. Missing, unreadable, or invalid stores leave the line hidden. The compact bottom bar is unchanged.
+
 The status bar replaces pi's three-line footer with a single line of segments:
 
 ```text
@@ -47,28 +49,38 @@ The prompt wraps pi's editor in a rounded frame with a petal that shows what the
 - The hint appears only while the editor is empty.
 - If another extension already installed a custom editor, Gentle Shell leaves it alone.
 
-Changes across this session's registered worktrees show up below the editor and as an aggregate `±N` next to the session branch in the bar:
+Changes shows **captured write/edit operations from this agent session and its owned subagents**. It does not scan the repository on startup, read all untracked files, or poll live files in the background. Fullscreen, the sidebar, and mouse interaction are unchanged.
 
 ```text
 ✎ 3 files · +42 −7 · extensions/gentle-shell.ts, lib/shell-bar.ts, tests/x.test.ts · /gentle:changes
 ```
 
-- Each registered root shows **all** dirty files: plain `git diff` against HEAD plus untracked files, including edits that predate this session. There are no baselines or file-level attribution filters.
-- The canonical session cwd root is included automatically. Successful standard `read`, `write`, `edit`, `grep`, `find`, and `ls` calls register their target worktree after completion. Failed calls, shell command text, and prose never register roots. Only roots sharing the session's Git common directory are accepted.
-- For opaque shell use or worktrees used earlier, call `session_worktree_register` with `{"path":"/path/to/worktree"}`. Registration is explicit, canonicalized, and deduplicated; unrelated dirty siblings remain invisible without an ignored-roots list.
-- The root registry persists in Pi custom entries (`gentle-pi.session-worktree/v1`). Exit/resume and `/reload` restore the same session UUID; `/tree` keeps roots session-wide. New sessions, `/fork`, and `/clone` ignore inherited registrations with another UUID. Clean roots stay registered but hidden until dirty; missing/prunable roots are skipped safely. Ephemeral `--no-session` runs cannot persist across exit.
-- Counts refresh after every tool call, at the end of each turn, and every 5 seconds in the background, so edits made from nvim or another agent show up without touching pi. `GENTLE_PI_SHELL_CHANGES_WATCH_MS` changes the interval; `off` leaves only the tool-driven refresh. Outside a git repository the widget stays hidden.
-- On narrow terminals the file list is dropped before the summary is truncated.
-
-`/gentle:changes` or `alt+g` opens the framed two-pane viewer. Dirty worktrees are accordion groups in the left pane, labeled with branch and directory basename (`detached` when there is no branch). Expand groups to reveal indented changed files; multiple groups can stay expanded. The right pane previews the selected file's lazy-loaded diff, or shows the selected group's full directory and summary. Clean, bare, missing, and prunable roots remain hidden; untracked-only roots are included.
-
-- `j`/`k` or up/down traverse visible groups and files, keeping the selection in view. On a group, `enter`, space, or right arrow toggles expansion. Left arrow or backspace moves a file selection to its parent, or collapses the selected group. `ctrl+j`/`ctrl+k` or `pgdn`/`pgup` scroll the diff; `esc` or `q` closes the overlay.
-- In fullscreen mode, left-click selects a visible file and loads its diff without opening the editor. Mouse wheels scroll the file list and selected diff independently; hovering does not select or open anything.
-- Opening, pressing `r`, and the background/overlay refresh cadence scan only registered roots. Worktree discovery supplies branch labels, never registration. No changes in registered roots means no widget and an informational notice instead of an overlay.
-- While the overlay is open, git is polled every 2 seconds, so edits made from nvim, another agent, or a checkout show up in place. Expansion and selection stick to the raw worktree root and file path across refreshes; a diff reloads when its counts move.
-- `GENTLE_PI_SHELL_CHANGES_KEY` rebinds the shortcut (pi key syntax, for example `ctrl+shift+g`); `off` disables it. On macOS, `alt+g` needs the terminal to send Option as Meta.
-- On a file row, `o` (or `enter`) opens the selected file in `$VISUAL` or `$EDITOR`, with the selected worktree as the editor's working directory, and returns to pi when the editor exits. Diff lookup and caches are also scoped to that root; identical relative filenames in other worktrees cannot share a diff.
-- Untracked files are diffed against an empty file so new files show their full content.
+### What appears in Changes
+
+- A worktree appears only after a captured successful mutation. Reading a file, opening a directory, registering a worktree, or launching a child is not mutation evidence.
+- Diffs compare the content observed before the agent's first captured operation with its latest captured result, not with HEAD. Consecutive agent edits combine; an agent revert removes its net change.
+- Edits from your editor or other sessions do not update these captured diffs. If an external or unobserved edit breaks continuity before the next agent operation on the same file, the file is marked **diff unavailable**, rather than mixing ownership.
+- Only worktrees in the coordinating session's Git clone are accepted. Child evidence is accepted only from an owned task with paired successful write/edit events and a matching target.
+- **Coverage is deliberately limited to write/edit tools.** Shell commands, custom mutation tools, failed/interrupted outcomes and children without the capture extension provide no attributed diff. A missing row does not mean the repository is clean or that no other changes occurred.
+
+### Bounds and session lifetime
+
+Capture reads only the named target, up to 64 KiB and 2,000 text lines. Binary, oversized, nonregular and unverifiable snapshots show unavailable counts, never fabricated zero-count proof. At most 256 operation identities and 4 MiB of serialized evidence are retained per session; reaching the limit produces a warning.
+
+Snapshots are stored locally in Pi custom entries (`gentle-pi.session-change/v1`), including bounded before/after source text. Exit/resume and reload restore captures only for the exact same session UUID. New sessions and forks do not inherit attribution from another UUID. Ephemeral `--no-session` runs do not persist after exit. Capturing remains active in headless children and when the visual shell is disabled.
+
+The separate `session_worktree_register` tool still registers canonical same-clone roots for coordination, but registration alone never adds files to Changes. Existing `gentle-pi.session-worktree/v1` entries do not establish file-level attribution.
+
+### Browse captured diffs
+
+`/gentle:changes` or `alt+g` opens the two-pane viewer. Worktrees are accordion groups on the left; selecting a file displays its captured diff on the right.
+
+- `j`/`k` or arrows navigate. On a group, Enter, Space or Right expands it; Left returns to its parent or collapses it. `ctrl+j/k` or Page Up/Down scroll the diff; Escape or `q` closes.
+- Fullscreen left-click selects files; mouse wheels scroll the file list and diff independently. Hover does not open files.
+- Opening, pressing `r`, and the overlay's refresh cadence consult only the captured session model. They never rescan Git or load the current file contents. Same-line-count edits invalidate the diff preview by content revision.
+- On a file, `o` or Enter opens the actual current file in `$VISUAL` or `$EDITOR`, with its worktree as cwd. Edits made there are external and are not attributed to the agent.
+- `GENTLE_PI_SHELL_CHANGES_KEY` rebinds the shortcut; `off` disables it. `GENTLE_PI_SHELL_CHANGES_POLL_MS` controls only the open overlay's in-memory refresh. `GENTLE_PI_SHELL_CHANGES_WATCH_MS` no longer enables filesystem polling.
+- No captured changes means no widget and an informational notice; it does not assert that the working tree is clean.
 
 Subscription usage shows in the bar after the cost, and `/gentle:usage` opens a panel with every window per provider:
 

package/docs/readme-reference.md

@@ -30,7 +30,7 @@ This reference preserves the detailed installation, configuration, SDD/OpenSpec,
 | **Skill creation workflow**    | Provides the `gentle-ai-skill-creator`/`gentle-ai-skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills. |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
 | **Bounded native review**      | Freezes one candidate, dispatches only controller-selected lenses, and records native authority. Review outcomes are informational; delivery follows ordinary repository policy. |
-| **Verified native runtime**    | The current source checkout provisions the exact package-local Gentle AI v2.9.0 runtime: signed, SHA-256-pinned release archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. |
+| **Verified native runtime**    | The current source checkout provisions the exact package-local Gentle AI v2.9.1 runtime: signed, SHA-256-pinned release archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Native pointer regions
@@ -67,7 +67,7 @@ The stable release is [`v2.6.0`](https://github.com/Gentleman-Programming/gentle
 
 ### Source checkout
 
-This checkout prepares `gentle-pi` `2.6.3`; it is source state, not a published release. Its package-local native runtime pin is Gentle AI `v2.9.0`, distinct from the published `v2.6.0` pairing.
+This checkout prepares `gentle-pi` `2.7.0`; it is source state, not a published release. Its package-local native runtime pin is Gentle AI `v2.9.1`, distinct from the published `v2.6.0` pairing.
 
 ### Pi compatibility
 
@@ -94,7 +94,7 @@ pi install npm:gentle-pi@2.6.0
 
 RDD remains opt-in. Enable it only through an explicit user decision with `/gentle:review-mode enable`; `status` lets you inspect the mode without changing it.
 
-The source checkout's RDD integration installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for source pin `v2.9.0`; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact `v2.9.0` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error. To recover explicitly, if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before changing to the installed `gentle-pi` package directory. Then run `node scripts/install-gentle-ai.mjs`. This invokes the package-owned installer without relying on a global binary or npm configuration change. A missing binary can result from skipped lifecycle scripts, but does not prove that lifecycle scripts were disabled.
+The source checkout's RDD integration installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for source pin `v2.9.1`; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact `v2.9.1` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error. To recover explicitly, if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before changing to the installed `gentle-pi` package directory. Then run `node scripts/install-gentle-ai.mjs`. This invokes the package-owned installer without relying on a global binary or npm configuration change. A missing binary can result from skipped lifecycle scripts, but does not prove that lifecycle scripts were disabled.
 
 Recommended companion packages:
 
@@ -250,13 +250,13 @@ flowchart TD
 
 VALIDATE is informational. Commit, push, PR, and release commands follow ordinary repository policy; RDD never authorizes, rewrites, consumes review state for, or blocks them. Dangerous-command safety and destructive-review consent remain independent.
 
-For the source checkout, native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v2.9.0 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v2` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, validate, and BIND-SDD request passes the same contract identifier. Negotiated envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
+For the source checkout, native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v2.9.1 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v2` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, validate, and BIND-SDD request passes the same contract identifier. Negotiated envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
 
 Contract `/v2` replaces the Base64 `candidate_diff` reviewer transport of `/v1` with immutable `base_tree`/`candidate_tree` plus an ordered `changed_path_manifest` and never an inline patch. `gentle-pi` negotiates `/v2` only, with no dual-lane fallback; the cutover landed as one atomic commit against gentle-ai v2.2.2 (tracked by the `migrate-review-integration-v2` change), and the `/v1` schemas stay packaged because the `/v2` schemas `$ref` into their fragments. This provider contract version is unrelated to Pi's own internal "compact-v2" review-authority naming used below — the shared digit is coincidental, not a version pairing.
 
 Target status owns `current_target`, `unrelated`, `ambiguous`, and `corrupted` applicability and returns one native action. Pi does not reconstruct ordinary authority from provider-private files or choose a lineage from repository-wide history. Restart recovery rebuilds only the derived candidate view from the native Git/content projection, including intended-untracked paths, symlinks, and immutable gitlink identities. Native failure envelopes retain their exact mutation outcome, replayability, required inputs, request digest, and next action. After an unknown or lost mutating result, Pi calls target status before any replay decision and returns only the provider-declared action.
 
-Once the source checkout's pinned gentle-ai runtime (currently v2.9.0) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
+Once the source checkout's pinned gentle-ai runtime (currently v2.9.1) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
 
 ### FINALIZE wrapper input
 
@@ -600,7 +600,7 @@ Profiles are named, switchable snapshots of the global agent-model routing from
 
 | Key     | Action                                                                 |
 | ------- | ---------------------------------------------------------------------- |
-| `enter` | Apply the selected profile live (writes `models.json`, reconciles agents, sets the orchestrator when the profile defines one). |
+| `enter` | Apply the selected profile live (writes `models.json`, replaces the routing of every agent, sets the orchestrator when the profile defines one). |
 | `c`     | Create a new, empty profile.                                           |
 | `s`     | Update the selected profile from the current routing (including the orchestrator currently set in `settings.json`). |
 | `d`     | Duplicate the selected profile.                                        |
@@ -612,11 +612,11 @@ Profiles are named, switchable snapshots of the global agent-model routing from
 | `pgup`/`pgdn`, `ctrl+j`/`ctrl+k` | Scroll the detail pane by a page.                                |
 | `esc`   | Close.                                                                 |
 
-Applying a profile writes `~/.pi/gentle-ai/models.json`, then reconciles agent frontmatter and `subagents.json` the same way `/gentle:models` does. The reconciliation happens on the next subagent launch, and that launch still routes with the previous routing — expect one launch of lag after switching. The active profile is persisted so `/gentle:profiles` reopens with the applied profile marked.
+Applying a profile writes `~/.pi/gentle-ai/models.json`, then reconciles agent frontmatter and `subagents.json` the same way `/gentle:models` does. A profile is a complete snapshot: every discoverable agent it omits returns to inherit, so routing materialized by a previous profile, by `/gentle:models`, or by a migration never survives a switch silently. The reconciliation happens on the next subagent launch, and that launch still routes with the previous routing — expect one launch of lag after switching. The active profile is persisted so `/gentle:profiles` reopens with the applied profile marked.
 
 A profile also carries the orchestrator under the reserved routing key `orchestrator`. Applying a profile that defines it writes `defaultProvider`, `defaultModel`, and `defaultThinkingLevel` to Pi's global `settings.json` (preserving every other key; an unreadable `settings.json` aborts that part and is reported instead of being overwritten). Applying a profile without an `orchestrator` entry never moves the orchestrator, and `s` snapshots the currently effective orchestrator together with the routing. `orchestrator` is reserved: it is not a subagent name, is never written to `subagents.json`, and is not counted as a role.
 
-When `profiles.json` is missing, the command seeds one profile named `current` captured from the existing `models.json`, marked active only when `models.json` has routing entries. Profiles or routing entries dropped by normalization are named in a warning instead of being lost silently.
+The panel's current routing, the `current` seed, and `s` all read the routing in effect: `models.json` where it has an entry, and otherwise the `subagents.json` model profile or frontmatter routing the runtime actually resolves for that agent. A sparse `models.json` therefore never hides routing that is still live. When `profiles.json` is missing, the command seeds one profile named `current` captured from that effective routing, marked active only when it has routing entries. Profiles or routing entries dropped by normalization are named in a warning instead of being lost silently.
 
 Saved globally at:
 

package/extensions/gentle-agents.ts

@@ -3,6 +3,7 @@ import { extractParentConfirmedSddPreflightContext, getPackageAssetOwner, isPare
 import { NativeReviewCliV216, NativeReviewCliError, createNodeExecFileAdapter, decodeNativeSddStatusV2, type NativeReviewCli, type NativeSddAcquireRequest, type NativeSddAttemptResult, type NativeSddSettleRequest } from "../lib/native-review-cli.ts";
 import { spawn } from "node:child_process";
 import { recordReviewMutation } from "../lib/review-reminder-receipt.ts";
+import { SESSION_CHANGE_RELAY } from "../lib/session-changes.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, type WorktreeResolver } from "../lib/session-worktree-registry.ts";
 import { existsSync, mkdirSync, readFileSync, lstatSync, realpathSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
@@ -885,6 +886,13 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 			const root = deps.resolveWorktree(tool.path, task.cwd)?.root;
 			const childRoot = deps.resolveWorktree(task.cwd, task.cwd)?.root;
 			if (!root || root !== childRoot || !worktrees.roots().includes(root)) return;
+			if (tool.evidence?.root === root) {
+				try {
+					let path = tool.path.replace(/^@/, "");
+					if (path === "~" || path.startsWith("~/")) path = os.homedir() + path.slice(1);
+					if (realpathSync(resolve(task.cwd, path)) === resolve(root, tool.evidence.path)) pi.events.emit(SESSION_CHANGE_RELAY, { sessionId: task.parentSessionId, evidence: { ...tool.evidence, id: `${task.id}:${tool.toolCallId}` } });
+				} catch { /* Missing or mismatched targets cannot supply session diffs. */ }
+			}
 			recordReviewMutation(pi, sessions, root, { source: "subagent", taskId: task.id, toolName: tool.toolName, toolCallId: tool.toolCallId });
 		},
 		onFinish: (task, observations) => {

package/extensions/gentle-ai.ts

@@ -2212,6 +2212,145 @@ function updateFrontmatterRouting(
 	return `---\n${lines.join("\n")}${body}`;
 }
 
+/**
+ * The routing an agent file currently carries, read the same way
+ * `updateFrontmatterRouting` writes it: top-level `model:` and `thinking:`
+ * frontmatter lines. Anything else is "no routing", not an error.
+ */
+function readFrontmatterRouting(content: string): AgentRoutingEntry | undefined {
+	if (!content.startsWith("---\n")) return undefined;
+	const endIndex = content.indexOf("\n---", 4);
+	if (endIndex === -1) return undefined;
+	const raw: Record<string, string> = {};
+	for (const line of content.slice(4, endIndex).split("\n")) {
+		if (line.startsWith("model:")) raw.model = line.slice("model:".length).trim();
+		else if (line.startsWith("thinking:")) raw.thinking = line.slice("thinking:".length).trim();
+	}
+	if (raw.model === undefined && raw.thinking === undefined) return undefined;
+	const entry = normalizeRoutingEntry(raw);
+	return entry && !isClearRoutingEntry(entry) ? entry : undefined;
+}
+
+function routingEntryFromModelProfile(value: unknown): AgentRoutingEntry | undefined {
+	if (!isRecord(value)) return undefined;
+	const entry = normalizeRoutingEntry({ model: value.model, thinking: value.effort });
+	return entry && !isClearRoutingEntry(entry) ? entry : undefined;
+}
+
+function readSubagentModelProfiles(path: string): Record<string, unknown> {
+	if (!existsSync(path)) return {};
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		return isRecord(parsed) && isRecord(parsed.model_profiles) ? parsed.model_profiles : {};
+	} catch {
+		return {};
+	}
+}
+
+async function readSubagentModelProfilesAsync(path: string): Promise<Record<string, unknown>> {
+	if (!(await pathExists(path))) return {};
+	try {
+		const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+		return isRecord(parsed) && isRecord(parsed.model_profiles) ? parsed.model_profiles : {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * The routing an agent is materialized with — what subagent launches actually
+ * resolve — regardless of what `models.json` records: the runtime reads
+ * `subagents.json` model profiles first and the agent frontmatter otherwise.
+ */
+function readMaterializedRoutingEntry(
+	cwd: string,
+	agent: AgentEntry,
+	profilesByPath: Map<string, Record<string, unknown>>,
+): AgentRoutingEntry | undefined {
+	const profilesPath = agentModelProfileConfigPath(cwd, agent.source);
+	let profiles = profilesByPath.get(profilesPath);
+	if (!profiles) {
+		profiles = readSubagentModelProfiles(profilesPath);
+		profilesByPath.set(profilesPath, profiles);
+	}
+	const fromProfile = routingEntryFromModelProfile(profiles[agent.name]);
+	if (fromProfile) return fromProfile;
+	if (!agent.filePath || !existsSync(agent.filePath)) return undefined;
+	try {
+		return readFrontmatterRouting(readFileSync(agent.filePath, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+async function readMaterializedRoutingEntryAsync(
+	cwd: string,
+	agent: AgentEntry,
+	profilesByPath: Map<string, Record<string, unknown>>,
+): Promise<AgentRoutingEntry | undefined> {
+	const profilesPath = agentModelProfileConfigPath(cwd, agent.source);
+	let profiles = profilesByPath.get(profilesPath);
+	if (!profiles) {
+		profiles = await readSubagentModelProfilesAsync(profilesPath);
+		profilesByPath.set(profilesPath, profiles);
+	}
+	const fromProfile = routingEntryFromModelProfile(profiles[agent.name]);
+	if (fromProfile) return fromProfile;
+	if (!agent.filePath || !(await pathExists(agent.filePath))) return undefined;
+	try {
+		return readFrontmatterRouting(await readFile(agent.filePath, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The routing in effect: `models.json` where it speaks, and the materialized
+ * stores the runtime resolves from for every discoverable agent it is silent
+ * about. A sparse `models.json` therefore never hides routing that is still
+ * live (#1012). Reading never writes.
+ */
+function readEffectiveModelConfig(cwd: string): AgentModelConfig {
+	const effective = cloneModelConfig(readModelConfig(cwd));
+	const profilesByPath = new Map<string, Record<string, unknown>>();
+	for (const agent of listDiscoverableAgents(cwd)) {
+		if (isProviderReviewRole(agent.name) || agent.name in effective) continue;
+		const entry = readMaterializedRoutingEntry(cwd, agent, profilesByPath);
+		if (entry) effective[agent.name] = entry;
+	}
+	return effective;
+}
+
+async function readEffectiveModelConfigAsync(cwd: string): Promise<AgentModelConfig> {
+	const effective = cloneModelConfig(await readModelConfigAsync(cwd));
+	const profilesByPath = new Map<string, Record<string, unknown>>();
+	for (const agent of await listDiscoverableAgentsAsync(cwd)) {
+		if (isProviderReviewRole(agent.name) || agent.name in effective) continue;
+		const entry = await readMaterializedRoutingEntryAsync(cwd, agent, profilesByPath);
+		if (entry) effective[agent.name] = entry;
+	}
+	return effective;
+}
+
+/**
+ * A profile is a complete routing snapshot: applying it must leave every
+ * discoverable agent it omits on inherit, not on whatever was materialized
+ * before. Padding the omitted agents with clear entries makes
+ * `applyModelConfig` remove their model profiles and frontmatter routing, the
+ * same way `/gentle:models` clears an agent set to inherit.
+ */
+async function withOmittedAgentsClearedAsync(
+	cwd: string,
+	config: AgentModelConfig,
+): Promise<AgentModelConfig> {
+	const completed = cloneModelConfig(config);
+	for (const agent of await listDiscoverableAgentsAsync(cwd)) {
+		if (isProviderReviewRole(agent.name) || agent.name in completed) continue;
+		completed[agent.name] = {};
+	}
+	return completed;
+}
+
 function parseAgentName(filePath: string): string | undefined {
 	let content: string;
 	try {
@@ -2457,6 +2596,9 @@ function updateSubagentModelProfileAtPath(
 		? { ...config.model_profiles }
 		: {};
 	const profile = modelProfileForRoutingEntry(entry);
+	// A write that would leave the profile as it is (including removing a
+	// profile that was never there) is not an update and touches no file.
+	if (JSON.stringify(modelProfiles[name]) === JSON.stringify(profile)) return false;
 	if (profile) {
 		if (options.preserveExisting && isRecord(modelProfiles[name])) return false;
 		modelProfiles[name] = profile;
@@ -2487,6 +2629,9 @@ async function updateSubagentModelProfileAtPathAsync(
 		? { ...config.model_profiles }
 		: {};
 	const profile = modelProfileForRoutingEntry(entry);
+	// A write that would leave the profile as it is (including removing a
+	// profile that was never there) is not an update and touches no file.
+	if (JSON.stringify(modelProfiles[name]) === JSON.stringify(profile)) return false;
 	if (profile) {
 		if (options.preserveExisting && isRecord(modelProfiles[name])) return false;
 		modelProfiles[name] = profile;
@@ -3660,7 +3805,7 @@ class ProfilesPanel implements OverlayComponent {
 			this.renderLine("Profile routing", width, "accent"),
 			...this.indentLines(this.routingLines(profileRows, widths), width),
 			"",
-			this.renderLine("Current routing (models.json)", width, "accent"),
+			this.renderLine("Current routing (effective)", width, "accent"),
 			...this.indentLines(this.routingLines(currentRows, widths), width),
 		];
 	}
@@ -3819,6 +3964,13 @@ async function runProfilesPanelAction(
 				if (routingWritten && previousActiveConfig !== undefined) {
 					try {
 						await writeModelConfigAsync(ctx.cwd, previousActiveConfig);
+						// Materialize the previous profile again with the same
+						// replacement semantics, so the failed profile's routes do not
+						// linger in subagents.json or the agent frontmatter.
+						await applyModelConfigAsync(
+							ctx.cwd,
+							await withOmittedAgentsClearedAsync(ctx.cwd, previousActiveConfig),
+						);
 					} catch {
 						restored = "";
 					}
@@ -3856,8 +4008,20 @@ async function runProfilesPanelAction(
 				);
 				return revertClaim(false);
 			}
-			const applyResult = await applySavedModelConfig(ctx);
-			if (applyResult.invalidPath) {
+			// models.json holds the profile as written; the padding with clear
+			// entries only drives materialization, so agents the profile omits
+			// return to inherit instead of keeping a previously materialized route.
+			let applyResult: { updated: number; skipped: number };
+			try {
+				applyResult = await applyModelConfigAsync(
+					ctx.cwd,
+					await withOmittedAgentsClearedAsync(ctx.cwd, normalized),
+				);
+			} catch (error) {
+				ctx.ui.notify(
+					`el Gentleman could not materialize profile "${result.name}": ${profilesErrorMessage(error)}`,
+					"warning",
+				);
 				return revertClaim(true);
 			}
 			let orchestratorNote = "";
@@ -3899,7 +4063,7 @@ async function runProfilesPanelAction(
 			}
 		}
 		case "update": {
-			const current = await readModelConfigAsync(ctx.cwd);
+			const current = await readEffectiveModelConfigAsync(ctx.cwd);
 			// A profile is a complete snapshot, so capturing the current routing also
 			// captures the orchestrator the routing is running under. A settings file
 			// that cannot be read leaves the snapshot without an orchestrator entry
@@ -4035,7 +4199,7 @@ async function handleProfilesCommand(ctx: ExtensionContext): Promise<void> {
 	}
 	let file: AgentProfilesFile;
 	if (read.status === "missing") {
-		file = bootstrapProfilesFile(await readModelConfigAsync(ctx.cwd));
+		file = bootstrapProfilesFile(await readEffectiveModelConfigAsync(ctx.cwd));
 		try {
 			writeProfilesFileSync(path, file);
 		} catch (error) {
@@ -4045,17 +4209,17 @@ async function handleProfilesCommand(ctx: ExtensionContext): Promise<void> {
 			);
 			return;
 		}
-		ctx.ui.notify(`el Gentleman seeded the "current" profile in ${path} from the saved model routing.`, "info");
+		ctx.ui.notify(`el Gentleman seeded the "current" profile in ${path} from the routing currently in effect.`, "info");
 	} else {
 		file = read.file;
 		reportProfilesDrops(ctx, path, read.drops);
 	}
 	let selectedName: string | undefined;
-	let result = await showProfilesPanel(ctx, file, await readModelConfigAsync(ctx.cwd), selectedName);
+	let result = await showProfilesPanel(ctx, file, await readEffectiveModelConfigAsync(ctx.cwd), selectedName);
 	while (result.type !== "close") {
 		selectedName = "name" in result ? result.name : undefined;
 		file = await runProfilesPanelAction(ctx, path, file, result);
-		result = await showProfilesPanel(ctx, file, await readModelConfigAsync(ctx.cwd), selectedName);
+		result = await showProfilesPanel(ctx, file, await readEffectiveModelConfigAsync(ctx.cwd), selectedName);
 	}
 }
 
@@ -7927,6 +8091,8 @@ async function executeReviewControllerOperation(
 /** @internal */
 export const __testing = {
 	resolveReviewModeGate,
+	readEffectiveModelConfig,
+	readEffectiveModelConfigAsync,
 	listAgentsFromDir,
 	listAgentsFromDirAsync,
 	listDiscoverableAgents,