pi-orchestrator-config 4.27.0 → 4.28.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [4.28.0] - 2026-11-07
+
+- Settings backups are scoped to a TUI visit: `/pi-config-settings` takes one restore point per
+  session instead of one per changed value, so the state you opened the overlay with survives a
+  burst of edits. Writes outside the TUI (allowlist approval, browser save) still back up per
+  action, and a snapshot left by a crashed visit is promoted rather than overwritten.
+- The backup lock is a single `O_EXCL` file: a dead owner's lock is taken over atomically, an
+  orphaned lock clears inside the same save, and a save that genuinely cannot take the lock still
+  refuses instead of shifting the chain and losing another process's restore point.
+- `bash -n file` no longer asks for approval — a pure syntax check runs nothing. Expansions,
+  backticks, process substitution, `+` options, `--`, `-c`, quotes and backslashes still ask.
+- `rm -rf` on a literal path inside the project `.pi/tmp` or `~/.pi/tmp` skips approval, with the
+  exemption logged as a statement hash. The operand must name the scratch both as written and as
+  resolved; `..`, backslashes, globs, quoting, subshells and `sudo` all still ask.
+- A missing `HOME` no longer makes the dangerous-command gate throw instead of deciding.
+
 ## [4.27.0] - 2026-11-07
 
 - Settings writes keep a configurable history: the previous file is copied to `.bak.1` before every

package/extensions/orchestrator/enforcement-helpers.ts

@@ -1942,6 +1942,26 @@ export function isRmInProjectTmp(stmt: string, cwd: string): boolean {
 
   // Resolve and substitute PROJECT_TMP_DIR env var
   const projectTmpDir = path.join(cwd, ".pi", "tmp");
+  // The home scratch (~/.pi/tmp) is our own throwaway tree too: the logger fallback and build
+  // scratch tests write there. Same exemption as the project one, same literal-path guards.
+  // Two roots, and BOTH must match: the scratch path as written (which may itself be a symlink —
+  // `~/.pi/tmp` often points into a dotfiles checkout) and where that path really lives. Matching
+  // only the real root made a symlink's target trusted: with `~/.pi/tmp -> ~`, `rm -rf ~/.ssh`
+  // resolves beneath it and would skip approval without ever naming the scratch.
+  // Both resolutions live inside one try: `homedir()` itself can throw when HOME is unset or
+  // points nowhere, and this helper feeds the dangerous-command gate — an exception here would
+  // replace a decision with a crash instead of simply granting no exemption.
+  let lexicalHomeTmp: string | null = null;
+  let resolvedHomeTmp: string | null = null;
+  try {
+    lexicalHomeTmp = path.resolve(realpathSync(homedir()), ".pi", "tmp").replace(/\/+$/, "");
+    resolvedHomeTmp = realpathSync(lexicalHomeTmp);
+  } catch {
+    lexicalHomeTmp = null; // no home, or no scratch in it — nothing to match
+    resolvedHomeTmp = null;
+  }
+  const underHomeTmp = (pathname: string, root: string): boolean =>
+    pathname === root || pathname.startsWith(root + path.sep);
   let resolvedCwd: string | null;
   try {
     resolvedCwd = realpathSync(cwd);
@@ -1952,14 +1972,21 @@ export function isRmInProjectTmp(stmt: string, cwd: string): boolean {
   for (const p of paths) {
     // Substitute ${PROJECT_TMP_DIR} or $PROJECT_TMP_DIR
     const expanded = p.replace(/\$\{?PROJECT_TMP_DIR\}?/g, projectTmpDir);
+    // Refuse `..` outright. `path.resolve` collapses it LEXICALLY, while the kernel applies it to
+    // where a preceding symlink actually points — so `~/.pi/tmp/link/../.ssh/key` looks in-scratch
+    // here and deletes `~/.ssh/key` there. Nothing legitimate needs `..` in a scratch operand.
+    if (/(^|\/)\.\.($|\/)/.test(expanded)) return false;
+    // The shell removes backslashes before `rm` sees the path, so `\.\.` is `..` and `\*` is a
+    // glob that no literal-path check ever saw. A literal scratch path needs none of them.
+    if (expanded.includes("\\")) return false;
+    const lexical = path.resolve(cwd, expanded);
     let resolved: string;
     try {
       // Use realpathSync to resolve symlinks — prevents symlink traversal attacks
-      resolved = realpathSync(path.resolve(cwd, expanded));
+      resolved = realpathSync(lexical);
     } catch {
       // Path doesn't exist. For /tmp paths, validate the existing parent via realpathSync
       // to catch symlinked parents (e.g., /tmp/evil-link -> / where evil-link exists).
-      const lexical = path.resolve(cwd, expanded);
       if (lexical.startsWith("/tmp/") && lexical !== "/tmp" && lexical.length > 5) {
         // Block paths containing traversal sequences — even if they resolve under /tmp/,
         // they may have escaped and re-entered via ..
@@ -1980,6 +2007,19 @@ export function isRmInProjectTmp(stmt: string, cwd: string): boolean {
           // Parent also doesn't exist — safe (entire path is non-existent)
         }
         resolved = lexical;
+      } else if (resolvedHomeTmp !== null && lexicalHomeTmp !== null && underHomeTmp(lexical, lexicalHomeTmp)) {
+        // Non-existent path under the home scratch — validate the parent the same way.
+        if (expanded.includes("..")) return false;
+        const parentDir = path.dirname(lexical);
+        try {
+          const resolvedParent = realpathSync(parentDir);
+          if (!resolvedParent.startsWith(resolvedHomeTmp + path.sep) && resolvedParent !== resolvedHomeTmp) {
+            return false;
+          }
+        } catch {
+          // Parent also doesn't exist — safe
+        }
+        resolved = lexical;
       } else if (resolvedCwd !== null &&
         (lexical.startsWith(resolvedCwd + path.sep) || lexical === resolvedCwd) &&
         (lexical.includes(`${path.sep}.pi${path.sep}tmp${path.sep}`) ||
@@ -2012,7 +2052,12 @@ export function isRmInProjectTmp(stmt: string, cwd: string): boolean {
        resolved.endsWith(`${path.sep}.pi${path.sep}tmp`));
     const inSystemTmp = resolved.startsWith("/tmp/") && resolved !== "/tmp" && resolved.length > 5;
 
-    if (!inProjectTmp && !inSystemTmp) return false;
+    // The path as WRITTEN must name the scratch (a symlinked scratch cannot lend its target out),
+    // and its real location must stay inside the scratch (a symlink inside it cannot escape).
+    const inHomeTmp = lexicalHomeTmp !== null && resolvedHomeTmp !== null &&
+      underHomeTmp(lexical, lexicalHomeTmp) && underHomeTmp(resolved, resolvedHomeTmp);
+
+    if (!inProjectTmp && !inSystemTmp && !inHomeTmp) return false;
   }
 
   return true;

package/extensions/orchestrator/enforcement.ts

@@ -5,6 +5,7 @@
  * review state tracking and gitignore checks.
  */
 
+import { createHash } from "node:crypto";
 import { createLogger } from "../shared/logger.js";
 import { createBridgedUi } from "../shared/ui-bridge.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -27,6 +28,7 @@ import {
 } from "./enforcement-helpers.js";
 import {
   DANGEROUS,
+  isNoexecSyntaxCheck,
   dangerousPatternLabel,
   getCurrentBranch,
   isInsideGitWorkTree,
@@ -458,6 +460,16 @@ async function checkDangerousCommands(command: string, cwd: string, ctx: any): P
   const hasDangerous = statements.some((stmt) => {
     // Skip read-only commands with no dangerous subshells
     if (isReadOnlyStatement(stmt)) return false;
+    // `bash -n file` only parses: nothing executes, so there is nothing to approve. Logged —
+    // an exemption from the gate must leave a trail an operator can find.
+    if (isNoexecSyntaxCheck(stmt)) {
+      // Audit trail without content: a statement can carry paths, tokens or credentials, so the
+      // log records a short hash an operator can match, never the words themselves.
+      log.info("dangerous_gate_noexec_syntax_check", {
+        statementHash: createHash("sha256").update(stmt).digest("hex").slice(0, 12),
+      });
+      return false;
+    }
     return DANGEROUS.some((p) => p.test(stmt));
   });
   if (hasDangerous) {
@@ -497,9 +509,17 @@ async function checkDangerousCommands(command: string, cwd: string, ctx: any): P
 
     // Allow rm -rf targeting only .pi/tmp/ paths without confirmation
     const allRmInTmp = statements
-      .filter((stmt) => DANGEROUS.some((p) => p.test(stmt)) && !isReadOnlyStatement(stmt))
+      .filter((stmt) => DANGEROUS.some((p) => p.test(stmt)) && !isReadOnlyStatement(stmt) && !isNoexecSyntaxCheck(stmt))
       .every((stmt) => isRmInProjectTmp(stmt, cwd));
-    if (allRmInTmp) return undefined;
+    if (allRmInTmp) {
+      // Never exempt silently: the audit line carries a hash, not the statement (paths can be
+      // sensitive), matching the syntax-check exemption above.
+      log.info("dangerous_gate_rm_scratch_exempt", {
+        statements: statements.length,
+        statementHash: createHash("sha256").update(statements.join("\n")).digest("hex").slice(0, 12),
+      });
+      return undefined;
+    }
 
     // User-approved allowlist (issue #949): the gate identifies the DANGEROUS
     // STATEMENTS (split out of the chain, benign plumbing tails — descriptor
@@ -517,7 +537,7 @@ async function checkDangerousCommands(command: string, cwd: string, ctx: any): P
     const dangerousStmts = [
       ...new Set(
         statements
-          .filter((stmt) => DANGEROUS.some((p) => p.test(stmt)) && !isReadOnlyStatement(stmt))
+          .filter((stmt) => DANGEROUS.some((p) => p.test(stmt)) && !isReadOnlyStatement(stmt) && !isNoexecSyntaxCheck(stmt))
           .map((stmt) => normalizeDangerousStatement(stmt)),
       ),
     ];

package/extensions/orchestrator/git-helpers.ts

@@ -1154,6 +1154,44 @@ export function listUnmergedFiles(cwd?: string): { ok: boolean; files: string[]
   return { ok: true, files: [...files] };
 }
 
+/** `bash -n file`, `sh -n script`, `bash -x -n f` — the shell only PARSES: nothing is executed.
+ *  A syntax check is not a command to approve, so the gate must not treat it as running a shell.
+ *  Only an exact `-n` token counts; anything fuzzier stays dangerous. */
+export function isNoexecSyntaxCheck(statement: string): boolean {
+  const WRAPPERS =
+    /^(?:(?:[0-9]*>{1,2}|&>)\S*\s+)*(?:\s*(?:[A-Za-z_]\w*=\S*|(?:then|do|else|elif)\b|sudo(?:\s+-\S+(?:\s+\S+)?)*|rtk(?:\s+-\S+)*|(?:command|builtin|exec)\b|env(?:\s+(?:-\S+(?:\s+\S+)?|\S+=\S*))*|timeout\s+(?:-\S+(?:\s+\S+)?\s+)*\S+|nice(?:\s+(?:-\S+(?:\s+\S+)?))*|nohup\b)\s+)*/i;
+  const SHELL = /^(?:\S*\/)?(?:ba|da|z|k|c|tc|fi)?sh\b/i;
+  // The calling shell expands and word-splits before the syntax check runs: `$(...)` executes,
+  // `${IFS}` splits one token into several options (`bash -n${IFS}+n${IFS}-c …`), backticks run,
+  // and `<(...)`/`>(...)` execute. ANY `$` is refused outright — a legitimate `bash -n script.sh`
+  // never needs one. Quotes and backslashes go too: the CALLING shell removes them before Bash
+  // parses, so `bash -n '+n' script.sh` would hand Bash a `+n` option while this predicate saw a
+  // harmless operand.
+  if (/[$`'"\\]|<(?=\()|>(?=\()/.test(statement)) return false;
+  const rest = statement.replace(WRAPPERS, "").trim();
+  const shellMatch = SHELL.exec(rest);
+  if (!shellMatch) return false;
+  const tokens = rest.slice(shellMatch[0].length).trim().split(/\s+/).filter(Boolean);
+
+  // `-n` only counts in the shell's OWN leading option block, and only if nothing turns it back
+  // off. The invocation accepts the `set` options, so `+n` re-enables execution:
+  //   `bash script.sh -n`  — operand, the script runs
+  //   `bash -- -n`         — `--` ends the options; it runs a FILE called `-n`
+  //   `bash -n +n script`  — noexec is switched off again
+  let noexec = false;
+  for (const token of tokens) {
+    if (token === "--") break; // option terminator: everything after is an operand
+    // `+` options enable modes again (`+n`, `+o noexec`, …). Refusing ALL of them keeps this
+    // predicate from having to model the whole `set` option table.
+    if (token.startsWith("+")) return false;
+    if (!token.startsWith("-")) break; // first operand (script name or argument)
+    // `-c` takes the program text — whatever follows is executed as parsed, so never exempt it.
+    if (/^-[a-zA-Z]*c[a-zA-Z]*$/.test(token)) return false;
+    if (/^-[a-zA-Z]*n/.test(token)) noexec = true; // -n, -xn, -nx
+  }
+  return noexec;
+}
+
 export const DANGEROUS = [
   /\brm\s+(?:-[a-zA-Z]+\s+)*(-[a-zA-Z]*r[a-zA-Z]*|--recursive)/i,
   /\bsudo\b/i,

package/extensions/orchestrator/settings-tui-helpers.ts

@@ -3,7 +3,7 @@
  * No pi-coding-agent or pi-tui dependencies.
  */
 
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join as joinPath, resolve, sep } from "node:path";
 import stripJsonComments from "strip-json-comments";
@@ -313,6 +313,186 @@ export class SettingsBackupError extends Error {
   }
 }
 
+/** Depth of the interactive editing session (`/pi-config-settings`). While it is open the file
+ *  is snapshotted ONCE, on the first change: a user who adjusts five values must not rotate the
+ *  pre-visit state out of existence. Writes outside the TUI are discrete actions and keep their
+ *  own backup. */
+let editSessionDepth = 0;
+const backedUpInSession = new Set<string>();
+/** Files this visit CREATED: their pre-visit state is "absent", so backing up the first partial
+ *  version would misrepresent it. */
+const createdInSession = new Set<string>();
+/** Visit snapshots waiting to be promoted into the numbered chain when the visit closes. */
+const visitSnapshots = new Set<string>();
+
+/** A visit keeps its own copy, so an external save during the visit (which rotates the numbered
+ *  chain) cannot destroy the state the user opened the TUI with. The process id is part of the
+ *  name: two TUI processes editing one file must not overwrite each other's restore point. */
+function visitSnapshotPath(filePath: string): string {
+  return `${filePath}.bak.visit-${process.pid}`;
+}
+
+/** Serialize chain mutations across processes: rotating or promoting shifts `.bak.N` files, and a
+ *  concurrent writer interleaving between the shift and the rename would lose a restore point. */
+function withChainLock<T>(filePath: string, fn: () => T): T {
+  // The lock is ONE file created with O_EXCL: creating it IS owning it. Splitting that into
+  // mkdir-then-write-pid left a window where the directory existed with no owner, and a reader
+  // could steal a lock a live writer was still acquiring — both then shifted the chain.
+  const lockPath = `${filePath}.bak.lock`;
+  let locked = false;
+  try {
+    for (let attempt = 0; attempt < 100 && !locked; attempt++) {
+      try {
+        writeFileSync(lockPath, String(process.pid), { flag: "wx", mode: 0o600 });
+        locked = true;
+      } catch {
+        // Take over a lock only when its OWNER IS GONE. Age alone is not evidence: a paused or
+        // slow owner could resume and mutate the chain alongside this process.
+        let stale = false;
+        try {
+          const ownerPid = Number(readFileSync(lockPath, "utf-8").trim());
+          if (Number.isInteger(ownerPid) && ownerPid > 0) {
+            try {
+              process.kill(ownerPid, 0); // alive — leave it alone
+            } catch {
+              stale = true; // owner is gone
+            }
+          } else {
+            // Created but not yet written, or a crash mid-write. A live acquisition writes its pid
+            // immediately, so this grace never steals from a live writer, and it is far shorter
+            // than the retry budget — an orphaned lock clears inside the same save.
+            stale = Date.now() - statSync(lockPath).mtimeMs > 200;
+          }
+        } catch {
+          // Vanished between the failed create and this read — retry immediately.
+        }
+        if (stale) {
+          // Atomic steal: rename first, so exactly one of several racing writers claims the stale
+          // lock. Deleting in place let two writers remove each other's fresh lock.
+          const grave = `${lockPath}.stale-${process.pid}-${Date.now()}`;
+          try {
+            renameSync(lockPath, grave);
+            unlinkSync(grave);
+          } catch {
+            /* another writer claimed it — retry the acquisition */
+          }
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+    if (!locked) {
+      // NEVER mutate the chain without the lock: a concurrent shift-and-rename loses a restore
+      // point, which is worse than refusing the save.
+      log.error("settings_backup_lock_timeout", { filePath });
+      throw new SettingsBackupError(filePath, new Error("backup lock timeout"));
+    }
+    return fn();
+  } finally {
+    if (locked) {
+      try {
+        // Only release a lock we still own: if it was stolen, it now belongs to someone else.
+        if (readFileSync(lockPath, "utf-8").trim() === String(process.pid)) unlinkSync(lockPath);
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+}
+
+/** Promote one visit snapshot into the numbered chain (`.bak.1`), shifting older copies. */
+function promoteSnapshot(snapshotPath: string): void {
+  const filePath = snapshotPath.replace(/\.bak\.visit-\d+$/, "");
+  if (!existsSync(snapshotPath)) return;
+  withChainLock(filePath, () => promoteSnapshotLocked(snapshotPath, filePath));
+}
+
+function promoteSnapshotLocked(snapshotPath: string, filePath: string): void {
+  const count = backupCountFor(filePath);
+  if (count <= 0) {
+    unlinkSync(snapshotPath);
+    return;
+  }
+  const oldest = settingsBackupPath(filePath, count);
+  if (existsSync(oldest)) unlinkSync(oldest);
+  for (let slot = count - 1; slot >= 1; slot--) {
+    const from = settingsBackupPath(filePath, slot);
+    if (existsSync(from)) renameSync(from, settingsBackupPath(filePath, slot + 1));
+  }
+  renameSync(snapshotPath, settingsBackupPath(filePath, 1));
+}
+
+/** Snapshots left by a process that is gone are promoted instead of being overwritten by the next
+ *  visit — a crash must cost nothing. A snapshot owned by a LIVE process is left alone. */
+function reapStaleVisitSnapshots(filePath: string): void {
+  const dir = dirname(filePath);
+  const marker = `${basename(filePath)}.bak.visit-`;
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.startsWith(marker)) continue;
+    const pid = Number(name.slice(marker.length));
+    if (!Number.isInteger(pid)) continue;
+    // Skip only a snapshot THIS process owns: a pid can be reused, and a reused pid must not
+    // cause a crashed editor's copy to be silently overwritten.
+    if (pid === process.pid && visitSnapshots.has(joinPath(dir, name))) continue;
+    try {
+      process.kill(pid, 0);
+      continue; // owner still alive
+    } catch {
+      /* dead: fall through and promote its snapshot */
+    }
+    try {
+      promoteSnapshot(joinPath(dir, name));
+      log.info("settings_visit_snapshot_recovered", { filePath, pid });
+    } catch (e: any) {
+      log.warn("settings_visit_snapshot_recover_failed", { filePath, pid, error: e?.message });
+    }
+  }
+}
+
+/** Move each visit snapshot into `.bak.1` (shifting the chain), once, when the visit closes. */
+function promoteVisitSnapshots(): void {
+  const failed = new Set<string>();
+  for (const snapshot of [...visitSnapshots]) {
+    try {
+      promoteSnapshot(snapshot);
+    } catch (e: any) {
+      // Kept in the set so a retry can still promote it; if the process ends first, the next
+      // visit reaps it by pid.
+      failed.add(snapshot);
+      log.warn("settings_visit_snapshot_promote_failed", { snapshot, error: e?.message });
+    }
+  }
+  visitSnapshots.clear();
+  for (const snapshot of failed) visitSnapshots.add(snapshot);
+}
+
+export function beginSettingsEditSession(): void {
+  editSessionDepth++;
+}
+
+export function endSettingsEditSession(): void {
+  editSessionDepth = Math.max(0, editSessionDepth - 1);
+  if (editSessionDepth === 0) {
+    promoteVisitSnapshots();
+    backedUpInSession.clear();
+    createdInSession.clear();
+  }
+}
+
+/** True when this write should rotate a backup. Only the settings TUI asks for dedupe; a browser
+ *  save or an allowlist approval arriving mid-visit is a separate action and keeps its own
+ *  restore point. */
+function shouldBackUp(filePath: string, dedupe: boolean): boolean {
+  if (!dedupe || editSessionDepth === 0) return true;
+  if (createdInSession.has(filePath)) return false;
+  return !backedUpInSession.has(filePath);
+}
+
 /** Path of the newest previous-version copy kept next to a settings file. */
 export function settingsBackupPath(filePath: string, slot = 1): string {
   return `${filePath}.bak.${slot}`;
@@ -321,8 +501,11 @@ export function settingsBackupPath(filePath: string, slot = 1): string {
 /** Keep `count` previous versions: shift `.bak.N-1` → `.bak.N`, then current → `.bak.1`.
  *  A count of 0 disables backups. Failures never block the write — they only log. */
 function rotateSettingsBackups(filePath: string, count: number): void {
-  pruneExtraBackups(filePath, count);
   if (count <= 0) return;
+  withChainLock(filePath, () => rotateSettingsBackupsLocked(filePath, count));
+}
+
+function rotateSettingsBackupsLocked(filePath: string, count: number): void {
   try {
     const oldest = settingsBackupPath(filePath, count);
     if (existsSync(oldest)) unlinkSync(oldest);
@@ -339,7 +522,11 @@ function rotateSettingsBackups(filePath: string, count: number): void {
   }
 }
 
-export function writeSettingsFile(filePath: string, data: Record<string, unknown>): void {
+export function writeSettingsFile(
+  filePath: string,
+  data: Record<string, unknown>,
+  options: { dedupeBackup?: boolean } = {},
+): void {
   // Write directly to target file. Per issue spec: "comments are lost on write — acceptable
   // since the example.jsonc is the reference."
   const dir = dirname(filePath);
@@ -359,13 +546,40 @@ export function writeSettingsFile(filePath: string, data: Record<string, unknown
 
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
 
-  if (existsSync(filePath)) {
+  const existedBefore = existsSync(filePath);
+  if (!existedBefore && options.dedupeBackup === true && editSessionDepth > 0) {
+    // Created during this visit: nothing to restore to, and the first partial version is not the
+    // pre-visit state, so later writes in the same visit must not snapshot it.
+    createdInSession.add(filePath);
+  }
+
+  if (existedBefore) {
     // A corrupt file is recoverable by hand; a cleared one is not. Refuse rather than
     // overwrite — this is exactly how a project's settings were once emptied.
     if (readSettingsFile(filePath) === null) throw new SettingsFileCorruptError(filePath);
-    // Every touch keeps the previous bytes — `settings_backup_count` of them, newest at
-    // `.bak.1` — so a wrong write is always recoverable.
-    rotateSettingsBackups(filePath, backupCountFor(filePath));
+    // Keep the pre-change bytes — `settings_backup_count` of them, newest at `.bak.1`. Inside the
+    // settings TUI that happens once per visit, so editing several values keeps the state the user
+    // started from. Recorded only after a successful rotation, so a failed one is retried.
+    const count = backupCountFor(filePath);
+    // Pruning runs on EVERY write: lowering the retention during a visit must drop the slots
+    // above the new limit, and inside a visit only the rotation itself is deduped.
+    pruneExtraBackups(filePath, count);
+    if (options.dedupeBackup === true && editSessionDepth > 0) {
+      // Inside a visit the snapshot is the restore point; the chain is only touched at visit end.
+      if (shouldBackUp(filePath, true) && count > 0) {
+        try {
+          reapStaleVisitSnapshots(filePath);
+          copyFileSync(filePath, visitSnapshotPath(filePath));
+          backedUpInSession.add(filePath);
+          visitSnapshots.add(visitSnapshotPath(filePath));
+        } catch (e: any) {
+          log.error("settings_backup_failed", { filePath, error: e?.message });
+          throw new SettingsBackupError(filePath, e);
+        }
+      }
+    } else {
+      rotateSettingsBackups(filePath, count);
+    }
   }
   const content = JSON.stringify(data, null, 2) + "\n";
   const tmpPath = `${filePath}.${process.pid}.${Date.now().toString(36)}`;

package/extensions/orchestrator/settings-tui.ts

@@ -35,6 +35,8 @@ import {
   getFilePathForScope,
   readSettingsFile,
   writeSettingsFile,
+  beginSettingsEditSession,
+  endSettingsEditSession,
   registerSettingsTuiCommand,
   isSecretNoChange,
   resolveSecretPrefill,
@@ -373,7 +375,7 @@ function saveChange(key: string, value: unknown, scope: "project" | "global", cw
   }
   if (Object.keys(current).length === 0 && !existsSync(filePath)) return { ok: true };
   try {
-    writeSettingsFile(filePath, current);
+    writeSettingsFile(filePath, current, { dedupeBackup: true });
   } catch (e) {
     return { ok: false, reason: "write_error", error: e };
   }
@@ -390,7 +392,7 @@ function deleteFromScope(key: string, scope: "project" | "global", cwd: string):
   if (!(key in current)) return { ok: true };
   delete current[key];
   try {
-    writeSettingsFile(filePath, current);
+    writeSettingsFile(filePath, current, { dedupeBackup: true });
   } catch (e) {
     return { ok: false, reason: "write_error", error: e };
   }
@@ -655,11 +657,17 @@ async function openSettingsTui(ctx: ExtensionCommandContext, initialScope?: stri
   // Clear cached settings so TUI always shows fresh values
   clearSettingsCache();
 
-  await ctx.ui.custom<undefined>(
-    (tui, theme, _kb, done) =>
-      new SettingsOverlay(tui, theme, cwd, modelRegistry, editScope, done, (msg, level) => ctx.ui.notify(msg, level)),
-    OVERLAY_OPTS,
-  );
+  // One backup per visit, not per keystroke-saved value.
+  beginSettingsEditSession();
+  try {
+    await ctx.ui.custom<undefined>(
+      (tui, theme, _kb, done) =>
+        new SettingsOverlay(tui, theme, cwd, modelRegistry, editScope, done, (msg, level) => ctx.ui.notify(msg, level)),
+      OVERLAY_OPTS,
+    );
+  } finally {
+    endSettingsEditSession();
+  }
 }
 
 // ── Registration ────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.27.0",
+  "version": "4.28.0",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"