pi-orchestrator-config 4.26.0 → 4.27.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [4.27.0] - 2026-11-07
+
+- Settings writes keep a configurable history: the previous file is copied to `.bak.1` before every
+  write, older copies rotate up to `settings_backup_count` (default 5, range 0-20,
+  `PI_SETTINGS_BACKUP_COUNT`), and lowering the count prunes the extra copies. A write whose backup
+  cannot be made is refused rather than proceeding without a fallback.
+- A settings file that does not parse is never replaced: the save is refused
+  (`SettingsFileCorruptError`) and the file is left byte-identical, so a hand-repairable file cannot
+  be emptied by generated content.
+- Test processes can no longer write real settings: under `node:test`, writes outside the temp tree
+  are refused, checked against the **real** path so a symlinked `.pi` cannot reach a real project.
+- An unscoped `tool_name bash` memory rule is refused at write time and ignored at load time, so a
+  memory entry can neither block every command nor append a banner to every result. "always
+  ask_user before X" is promoted as an ordering verifier instead of a blanket warning.
+- Log fallbacks stay inside the project: `.pi/tmp/pi-logs` is tried before the home copy, and a
+  vanished working directory no longer throws while the fallback list is built.
+- The qodo-review prompt writes its context under `.pi/tmp`, not `/tmp`.
+
+## [4.26.1] - 2026-11-06
+
+- The tmp sweep carries no hardcoded control-file name list: it asks
+  `daemon-manager.isLiveLegacyDaemonFile()`, which owns the two legacy names, so a future daemon
+  writing to `.pi/run` can never require the sweep to be edited. A legacy `pidiff.port`/`pidiff.pid`
+  is kept only while its recorded PID is alive (`EPERM` counts as alive — another user's running
+  process), and a dead daemon's leftovers plus every `reload.*` marker are swept like any other
+  entry. Deleting a live daemon's lockfiles would make the next connect() spawn a duplicate on its
+  port.
+- A control file can no longer block or exhaust a session: `readLockfile` accepts only regular
+  files, so a project FIFO at `pidiff.port`/`pidiff.pid` is ignored, and the pid read is capped at
+  64 bytes so an oversized file is rejected without being read.
+
 ## [4.26.0] - 2026-11-06
 
 - Async `chain` mode: steps run in sequence and each step's result is substituted into `{previous}`,

package/extensions/orchestrator/enforcement-rules.ts

@@ -16,9 +16,12 @@ import {
   type EnforcementTrigger,
   type EnforcementAction,
 } from "./memory-scoring.js";
+import { createLogger } from "../shared/logger.js";
 import { readAllTopicEntries } from "./memory-tree.js";
 import { getSetting } from "./project-settings.js";
 
+const log = createLogger("enforcement");
+
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export interface EnforcedEntry {
@@ -84,6 +87,16 @@ export function loadEnforcedEntries(cwd: string, sessionId?: string): EnforcedEn
 
   for (const { hash, entry } of all) {
     if (!entry.trigger || !entry.action) continue;
+    // A `tool_name bash` rule fires on every command: block stops the session dead, warn
+    // buries every result under a banner. Both happened with entries already in the store,
+    // so the guard lives at load time as well as write time.
+    if (
+      entry.trigger.trim().toLowerCase() === "tool_name bash" &&
+      ["block", "warn"].includes(entry.action.trim().split(/\s+/)[0])
+    ) {
+      log.warn("enforcement_rule_unscoped_bash_ignored", { hash, action: entry.action });
+      continue;
+    }
 
     result.push({
       hash,

package/extensions/orchestrator/memory-promotion.ts

@@ -38,8 +38,10 @@ export const EVIDENCE_PROJECT_RULE = 5;
 const log = createLogger("memory");
 
 export interface InferredEnforcement {
-  trigger: EnforcementTrigger;
-  action: EnforcementAction;
+  /** A rule can be ordering-only: then the verifier is the enforcement and there is no
+   *  trigger/action pair to fire unconditionally. */
+  trigger?: EnforcementTrigger;
+  action?: EnforcementAction;
   actionCommand?: string;
   verifier?: string;
   confidence: "high" | "low";
@@ -94,9 +96,11 @@ export function inferMechanicalEnforcement(text: string): InferredEnforcement |
   if (askBefore?.[1]) {
     const cmd = askBefore[1].replace(/[.!]+$/, "").trim();
     if (cmd.length > 2 && cmd.length < 80) {
+      // The rule is about ORDER, so the verifier is the enforcement. A `bash_contains` warn
+      // would also fire after a compliant `ask_user` + command pair, which is exactly the
+      // noise this story keeps producing; and a bare `tool_name bash` is refused at write
+      // time and ignored at load time.
       return {
-        trigger: "tool_name bash" as EnforcementTrigger,
-        action: "warn",
         verifier: `tool_called ask_user before ${cmd}`,
         confidence: "high",
       };

package/extensions/orchestrator/memory-write.ts

@@ -105,6 +105,21 @@ function validateTrigger(trigger: string): string | null {
   return null;
 }
 
+/** A `tool_name bash` rule fires on EVERY command, so a block (or a warn) there can brick
+ *  the session instead of enforcing anything specific. Two of them did exactly that: one
+ *  blocked every bash call, the other printed a banner on every call. Such a rule is never
+ *  what the writer means — a bash rule has to name the command it is about. */
+export function unscopedBashRuleError(trigger: string, action: string | undefined): string | null {
+  if (trigger.trim().toLowerCase() !== "tool_name bash") return null;
+  const verb = (action ?? "").trim().split(/\s+/)[0];
+  if (verb !== "block" && verb !== "warn") return null;
+  log.warn("memory-write: unscoped bash trigger rejected", { trigger, action });
+  return (
+    `Refusing "${trigger}" with action "${verb}": it would apply to EVERY bash call. ` +
+    "Scope it to the command, e.g. 'bash_contains rm -rf /' or 'bash_regex ^git push'."
+  );
+}
+
 function validateAction(action: string): string | null {
   const validActions = ["block", "warn"];
   const isRunAfter = action.startsWith("run_after ");
@@ -2366,6 +2381,8 @@ export async function addMemoryEntry(cwd: string, input: AddMemoryInput): Promis
   if (input.trigger) {
     const err = validateTrigger(input.trigger);
     if (err) return { status: "rejected", message: err };
+    const unscoped = unscopedBashRuleError(input.trigger, input.action);
+    if (unscoped) return { status: "rejected", message: unscoped };
   }
   if (input.action) {
     const err = validateAction(input.action);

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

@@ -3,13 +3,14 @@
  * No pi-coding-agent or pi-tui dependencies.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join as joinPath } from "node:path";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, 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";
 import {
   type SettingsKeyDef,
   SETTINGS_KEYS,
+  getSetting,
   getSettingsPath,
   getGlobalSettingsPath,
 } from "./project-settings.js";
@@ -209,11 +210,163 @@ export function readSettingsFile(filePath: string): Record<string, unknown> | nu
   return null;
 }
 
+/** Thrown instead of writing when the target file cannot be parsed. A settings file that a
+ *  human can still repair by hand must never be replaced by generated content. */
+export class SettingsFileCorruptError extends Error {
+  constructor(readonly filePath: string) {
+    super(`refusing to overwrite unparseable settings file: ${filePath}`);
+    this.name = "SettingsFileCorruptError";
+    log.error("settings_write_refused_corrupt", { filePath });
+  }
+}
+
+/** `realpath` of the nearest path that exists, so a symlinked parent cannot hide the target. */
+function nearestRealPath(target: string): string {
+  const absolute = resolve(target);
+  const tail: string[] = [];
+  let current = absolute;
+  for (;;) {
+    try {
+      const real = realpathSync(current);
+      return tail.length > 0 ? joinPath(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return absolute;
+      tail.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+/** The cwd whose settings govern this file: the project root for a project file, and never a
+ *  project override for a global one. A removed cwd must not block a save. */
+function settingCwdFor(filePath: string): string | null {
+  const parent = dirname(filePath);
+  if (basename(parent) === ".pi") {
+    const root = dirname(parent);
+    if (root === homedir()) return null; // global file: no project scope applies
+    return root;
+  }
+  try {
+    return process.cwd();
+  } catch {
+    return null;
+  }
+}
+
+/** Backup retention for this file: project setting where a project owns it, env/default for
+ *  a global file — one project can never change another's retention. */
+function backupCountFor(filePath: string): number {
+  const def = SETTINGS_KEYS.settings_backup_count;
+  const fallback = Number(def?.default ?? 5);
+  const min = Number(def?.min ?? 0);
+  const max = Number(def?.max ?? 20);
+  // An out-of-range or non-integer value must not decide retention: `-1` would prune every
+  // backup and write none, and a huge value would rotate far past the documented limit.
+  const accept = (value: number): number | null =>
+    Number.isInteger(value) && value >= min && value <= max ? value : null;
+
+  // Validate the env value FIRST, for its diagnostic: `getSetting` substitutes the default
+  // before the range check can see it, so a malformed env var would otherwise be logged only
+  // on a global save and silently swallowed on a project one.
+  const raw = process.env.PI_SETTINGS_BACKUP_COUNT;
+  const envCount = raw !== undefined && raw.trim() !== "" ? accept(Number(raw)) : null;
+  if (raw !== undefined && raw.trim() !== "" && envCount === null) {
+    log.warn("settings_backup_count_invalid", { raw, min, max, fallback });
+  }
+
+  const cwd = settingCwdFor(filePath);
+  if (cwd !== null) {
+    const resolved = accept(Number(getSetting(cwd, "settings_backup_count")));
+    if (resolved !== null) return resolved;
+  }
+  return envCount ?? fallback;
+}
+
+/** Drop slots beyond the configured count, so lowering retention removes old copies. */
+function pruneExtraBackups(filePath: string, count: number): void {
+  const prefix = `${basename(filePath)}.bak.`;
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(dirname(filePath));
+  } catch (e: any) {
+    log.warn("settings_backup_prune_scan_failed", { filePath, error: e?.message });
+    return;
+  }
+  for (const name of entries) {
+    if (!name.startsWith(prefix)) continue;
+    const slot = Number(name.slice(prefix.length));
+    if (!Number.isFinite(slot) || slot <= count) continue;
+    try {
+      unlinkSync(joinPath(dirname(filePath), name));
+    } catch (e: any) {
+      log.warn("settings_backup_prune_failed", { filePath, slot: name, error: e?.message });
+    }
+  }
+}
+
+/** Thrown when the previous version could not be preserved, so nothing is written. */
+export class SettingsBackupError extends Error {
+  constructor(readonly filePath: string, readonly cause?: unknown) {
+    super(`refusing to write settings without a backup: ${filePath}`);
+    this.name = "SettingsBackupError";
+  }
+}
+
+/** 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}`;
+}
+
+/** 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;
+  try {
+    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));
+    }
+    copyFileSync(filePath, settingsBackupPath(filePath, 1));
+  } catch (e: any) {
+    // A write without its backup breaks the one guarantee this function exists for: if the
+    // new content is wrong there is nothing to fall back to.
+    log.error("settings_backup_failed", { filePath, error: e?.message });
+    throw new SettingsBackupError(filePath, e);
+  }
+}
+
 export function writeSettingsFile(filePath: string, data: Record<string, unknown>): 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);
+
+  // Refuse BEFORE touching the filesystem: creating the parent of a rejected path would
+  // change a location the write is not allowed to reach.
+  if (process.env.NODE_TEST_CONTEXT !== undefined) {
+    // Test processes may only write under the OS temp tree (same safety net the global
+    // settings path has): a test once wrote a project's real settings file. Compare the REAL
+    // paths — a lexical check passes for a fixture whose `.pi` links to a real project.
+    const real = nearestRealPath(filePath);
+    const tmpRoot = realpathSync(tmpdir());
+    if (real !== tmpRoot && !real.startsWith(tmpRoot + sep)) {
+      throw new Error(`test process refused to write settings outside the temp tree: ${real}`);
+    }
+  }
+
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  if (existsSync(filePath)) {
+    // 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));
+  }
   const content = JSON.stringify(data, null, 2) + "\n";
   const tmpPath = `${filePath}.${process.pid}.${Date.now().toString(36)}`;
   try {

package/extensions/orchestrator/tmp-cleanup.ts

@@ -15,6 +15,7 @@ import * as fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isLiveLegacyDaemonFile } from "../shared/daemon-manager.js";
 import { createLogger } from "../shared/logger.js";
 import { isPiOneshotInvocation } from "../shared/oneshot.js";
 import { getGlobalSettingsPath, getSettingDynamic, getSettingsPath, SETTINGS_KEYS } from "./project-settings.js";
@@ -29,21 +30,6 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 /** Defaults live in `settings-keys.json` only — never restated here. */
 export const DEFAULT_MAX_SIZE = String(SETTINGS_KEYS.project_tmp_max_size.default);
 export const DEFAULT_RETENTION_DAYS = Number(SETTINGS_KEYS.project_tmp_retention_days.default);
-/**
- * Transitional debris from pre-#1020 daemons: `.pi/tmp` was the control-file home
- * before `.pi/run`, so a daemon started before the upgrade still holds its pid/port and
- * reload handshake here, and the read-both fallback (#1025) needs these files to find it.
- * Sweeping them would make the next connect() miss the live daemon and spawn a duplicate
- * on the same port. Never deleted, whatever their age; the set disappears once no
- * pre-upgrade daemon remains.
- */
-export const TMP_PROTECTED_NAMES = new Set([
-  "pidiff.pid",
-  "pidiff.port",
-  "reload.flag",
-  "reload.done",
-  "reload.pending",
-]);
 /** Lives in `.pi/run`, never in the swept dir. */
 export const TMP_SWEEP_LOCK = ".tmp-sweep.lock";
 /** A crashed sweep would otherwise block every later session forever. */
@@ -171,7 +157,14 @@ export async function sweepProjectTmp(opts: TmpSweepOptions): Promise<TmpSweepRe
   let total = 0;
   for (const name of names) {
     const target = path.join(base, name);
-    if (!isInside(base, target) || TMP_PROTECTED_NAMES.has(name)) continue;
+    if (!isInside(base, target)) continue;
+    // One exemption, decided by the daemon layer: a pre-`.pi/run` daemon that is still ALIVE
+    // owns its lockfile here, and sweeping it makes the next connect() spawn a duplicate on
+    // that port. A dead daemon's leftovers are throwaway like everything else (#1020).
+    if (isLiveLegacyDaemonFile(base, name)) {
+      log.debug("tmp_sweep_kept_live_legacy_daemon", { tmpDir: base, name });
+      continue;
+    }
     let stat: fs.Stats;
     try {
       stat = await fsp.lstat(target);

package/extensions/shared/daemon-manager.ts

@@ -193,19 +193,36 @@ export function writeLockfile(lockDir: string, port: number, pid: number | null,
   } catch (e: any) { log(`writeLockfile error: ${e.message}`); }
 }
 
+/** A pid file holds digits and a newline; anything bigger is not one. */
+const MAX_PID_FILE_BYTES = 64;
+
+/** True for a path that exists and is a regular file. Lockfiles are never FIFOs, and reading
+ *  one would block the event loop, so every control-file read goes through this. */
+function isRegularFile(target: string): boolean {
+  try {
+    return fs.lstatSync(target).isFile();
+  } catch {
+    return false;
+  }
+}
+
 /** Read port from lockfile. Returns port number or null.
  *  `legacyDir` (`.pi/tmp`) is consulted only when the new dir has no lockfile:
- *  a daemon already running at upgrade time wrote its lockfile there (#1020). */
+ *  a daemon already running at upgrade time wrote its lockfile there (#1020).
+ *  Reading never moves or deletes anything — moving a live daemon's record is what the
+ *  sweep's liveness check exists to avoid. */
 export function readLockfile(lockDir: string, legacyDir?: string): { port: number; pid: number | null } | null {
   const read = (dir: string): { port: number; pid: number | null } | null => {
     try {
       const portFile = path.join(dir, "pidiff.port");
-      if (!fs.existsSync(portFile)) return null;
+      // Only a regular file is a lockfile: the dirs are project-controlled, and reading a
+      // FIFO here would block the event loop for the whole session.
+      if (!isRegularFile(portFile)) return null;
       const port = parseInt(fs.readFileSync(portFile, "utf-8").trim(), 10);
       if (isNaN(port)) return null;
       let pid: number | null = null;
       const pidFile = path.join(dir, "pidiff.pid");
-      if (fs.existsSync(pidFile)) {
+      if (isRegularFile(pidFile)) {
         pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
         if (isNaN(pid)) pid = null;
       }
@@ -215,6 +232,63 @@ export function readLockfile(lockDir: string, legacyDir?: string): { port: numbe
   return read(lockDir) ?? (legacyDir ? read(legacyDir) : null);
 }
 
+/** Read the pid from a lockfile, refusing anything but a regular file: the legacy dir is
+ *  project-controlled, and reading a FIFO there would block session startup. */
+function readLegacyPid(pidFile: string): number | null {
+  try {
+    const st = fs.lstatSync(pidFile);
+    if (!st.isFile()) {
+      log.debug("legacy_pid_not_a_regular_file", { pidFile });
+      return null;
+    }
+    // The file is project-controlled: a pid is a few bytes, so refuse anything larger rather
+    // than reading an arbitrary file into memory during session start.
+    if (st.size > MAX_PID_FILE_BYTES) {
+      log.debug("legacy_pid_file_too_large", { pidFile, size: st.size });
+      return null;
+    }
+    const pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
+    if (isNaN(pid) || pid <= 0) {
+      log.debug("legacy_pid_unparseable", { pidFile });
+      return null;
+    }
+    return pid;
+  } catch (e: any) {
+    log.debug("legacy_pid_unreadable", { pidFile, error: e?.message });
+    return null;
+  }
+}
+
+/** True when the legacy `.pi/tmp` lockfile belongs to a LIVE process. `EPERM` means the
+ *  process exists under another user, so it counts as alive — treating it as dead would let
+ *  the sweep delete a running daemon's files. */
+export function legacyLockfileOwnerAlive(legacyDir: string): boolean {
+  const pid = readLegacyPid(path.join(legacyDir, "pidiff.pid"));
+  if (pid === null) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e: any) {
+    if (e?.code === "EPERM") {
+      log.debug("legacy_daemon_owned_by_another_user", { pid });
+      return true;
+    }
+    log.debug("legacy_daemon_not_running", { pid, code: e?.code });
+    return false;
+  }
+}
+
+/** Control files a pre-`.pi/run` daemon owns inside the legacy dir. Private: the sweep asks
+ *  `isLiveLegacyDaemonFile`, so neither module keeps a second copy of the names (#1020). */
+const LEGACY_CONTROL_FILES = new Set(["pidiff.port", "pidiff.pid"]);
+
+/** True when `name` is a legacy control file whose owner is still alive — the sweep's only
+ *  exemption. A dead daemon's leftovers are ordinary throwaway. */
+export function isLiveLegacyDaemonFile(legacyDir: string, name: string): boolean {
+  if (!LEGACY_CONTROL_FILES.has(name)) return false;
+  return legacyLockfileOwnerAlive(legacyDir);
+}
+
 /** First lockfile port (in `dirs` order) whose daemon answers /api/health, or
  *  null. Exported for testing. */
 export async function findLiveLockfile(dirs: string[]): Promise<number | null> {

package/extensions/shared/file-logger.ts

@@ -133,7 +133,8 @@ function appendLine(filePath: string, line: string): void {
  * Append one physical line to ~/.pi/logs/<name>/<session>.log.
  * Never writes to console.* (chat UI leak).
  * Returns true on success.
- * On primary-path failure, tries os.tmpdir()/pi-logs/<name>.log once.
+ * On primary-path failure, tries `~/.pi/tmp/pi-logs` then `<cwd>/.pi/tmp/pi-logs`: both are
+ * swept by the tmp cleanup, and the home one still works when the checkout is read-only.
  */
 const LEVEL_ORDER: Record<string, number> = Object.assign(Object.create(null), { off: -1, debug: 0, info: 1, warn: 2, error: 3 });
 
@@ -214,13 +215,28 @@ export function writeFileLogLine(name: string, line: string): boolean {
     return true;
   } catch (primaryErr) {
     recordWriteError(primaryErr);
+    // Never the OS temp dir: `.pi/tmp` is what the tmp cleanup sweeps. The project comes
+    // first so its sweep owns the file; home is the second chance when the checkout is
+    // read-only or has been deleted under us.
+    const fallbackDirs: string[] = [];
     try {
-      const fallbackDir = path.join(os.tmpdir(), "pi-logs");
-      appendLine(path.join(fallbackDir, `${safe}.log`), line);
-      return true;
-    } catch (fallbackErr) {
-      recordWriteError(fallbackErr);
-      return false;
+      fallbackDirs.push(path.join(process.cwd(), ".pi", "tmp", "pi-logs"));
+    } catch {
+      /* cwd removed — the home fallback below still works */
     }
+    try {
+      fallbackDirs.push(path.join(os.homedir(), ".pi", "tmp", "pi-logs"));
+    } catch {
+      /* no home — nothing left to try */
+    }
+    for (const fallbackDir of fallbackDirs) {
+      try {
+        appendLine(path.join(fallbackDir, `${safe}.log`), line);
+        return true;
+      } catch (fallbackErr) {
+        recordWriteError(fallbackErr);
+      }
+    }
+    return false;
   }
 }

package/package.json

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

package/prompts/qodo-review.md

@@ -51,7 +51,7 @@ log in, refresh tools, or run any audit automatically.
 
 ## Attach session context
 
-Before each review, write a self-contained JSON context file under `/tmp`. Include:
+Before each review, write a self-contained JSON context file under `.pi/tmp/` (the project scratch dir the tmp sweep cleans — never `/tmp`). Include:
 
 - what this session changed and why;
 - key implementation decisions and their rationale;

package/settings-keys.json

@@ -645,5 +645,14 @@
     "min": 1,
     "max": 365,
     "group": "Cleanup"
+  },
+  "settings_backup_count": {
+    "description": "Previous versions of a settings file kept next to it before each write (0 disables backups)",
+    "type": "int",
+    "env": "PI_SETTINGS_BACKUP_COUNT",
+    "default": 5,
+    "min": 0,
+    "max": 20,
+    "group": "Settings"
   }
 }