pi-orchestrator-config 4.26.1 → 4.27.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

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/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.1",
+  "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"
   }
 }