pi-better-harness 0.24.0 → 0.26.0

package/README.md

@@ -91,8 +91,17 @@ all original tool details in both modes and folds them again on the next toggle.
 `/tool-output normal` restores ordinary rendering. Error result bodies are also
 hidden in minimal mode and remain available when expanded.
 
-Normal mode is the default. The preference is saved in the current session,
-including resume/reload. This is a version-sensitive internal TUI adapter,
+Minimal mode also covers Harness tools: Subagents, Background Tasks, Goal, Plan,
+catalog inspection, and SSH. Compact calls retain the run or task ID, launch name
+and task, background command, goal action, or plan summary without showing result
+bodies. Finished calls fold into the same disclosure blocks as built-in tools;
+expanding them restores their original package renderers. Goal and Plan widgets
+and the background-work navigator are independent UI surfaces and remain visible.
+
+Normal mode is the initial default. Changing tool output saves the choice in
+global `settings.json` under `piBetterHarness.toolOutput`, as well as the current
+session. New sessions inherit it; resumed branches retain their own saved choice.
+This is a version-sensitive internal TUI adapter,
 tested with Pi 0.82.1, 0.99.1, and the bundled Pi 1.0.0 CLI; incompatible APIs
 produce a warning and leave ordinary output enabled. Print/RPC output and
 exported transcripts are unchanged.
@@ -108,13 +117,14 @@ pi -e ./packages/pi-better-harness/extensions/minimal-output/index.ts
 
 The bundled harness provides `/harness-settings`, using Pi's native settings
 list. It opens the settings screens of loaded Sandbox, Subagents, and Goal
-packages without duplicating their configuration. `/sandbox`, `/subagents
-settings`, and `/goal settings` remain available in standalone installations.
+packages without duplicating their configuration, plus the **Agents** shortcut
+to the `/agents` catalog. `/sandbox`, `/subagents settings`, `/agents`, and
+`/goal settings` remain available in standalone installations.
 Packages without a settings screen are not listed. Pi's `/settings` is unchanged.
 
 The hub includes **Tool output** when the bundled renderer extension is loaded.
-Changes apply immediately to the current session and do not save a global
-default. The hub also owns **Completions while busy**, shared by Subagents and Background
+Changes apply immediately and also save the default for future sessions.
+The hub also owns **Completions while busy**, shared by Subagents and Background
 Tasks. Choose **Wait until idle** (the default) or **Steer active run**. Changes
 apply immediately and autosave to the current session branch, including across
 reloads. Press **Ctrl+S** to save the current choice as your default for future
@@ -122,10 +132,22 @@ Pi sessions; changing a session afterward does not change that saved default.
 Saving a default leaves already-open sessions unchanged, including when
 navigating to a branch without a session override.
 The user default is stored in
-`<agent-dir>/extensions/pi-better-callback-preferences.json` and also applies
+`<agent-dir>/settings.json` under `piBetterHarness.callbacks` and also applies
 when either callback package is loaded standalone. The former
 `PI_BETTER_CALLBACK_WHILE_BUSY` environment variable is no longer supported.
 
+All Harness-owned defaults use the `piBetterHarness` section of global
+`~/.pi/agent/settings.json` (or `PI_CODING_AGENT_DIR/settings.json`): tool output,
+Subagents configuration, callback delivery, Goal controls, and Sandbox activation,
+permissions, and deny-rule templates. Existing preference files migrate on first
+use after validation; global choices take precedence, and old files remain intact.
+Updates preserve Pi's own settings and other packages' choices. SSH profiles,
+plans, run records, and role/agent definitions remain in their existing stores:
+they are session data or reusable definitions, not global UI defaults.
+In `/agents`, model and effort edits are session-local until Ctrl+S saves them
+to the user or project catalog definition. Saved catalog defaults also survive
+sessions and upgrades; they are not duplicated in global `settings.json`.
+
 Next-prompt inference is deferred pending safe public auth/header resolution in
 Pi's SDK. It is not loaded by the bundle, has no toggle or preference store in
 this version, and makes no auxiliary model requests. The integration blocker is

package/extensions/minimal-output/hook.ts

@@ -16,6 +16,7 @@ interface ToolComponent {
   toolCallId: string;
   args: unknown;
   callRendererComponent?: Component;
+  getCallRenderer?(): unknown;
   expanded: boolean;
   isPartial?: boolean;
   result?: { isError?: boolean };
@@ -73,8 +74,58 @@ const TOOL_ICONS: Record<string, string> = {
   grep: "\u2315",
   find: "\u2316",
   ls: "\u2261",
+  subagent_spawn: "\u25c7",
+  subagent_spawn_batch: "\u25c7",
+  bg_task_spawn: "\u2318",
+  bg_task_watch: "\u2318",
+  bg_task: "\u2318",
+  update_goal: "\u25ce",
+  get_goal: "\u25ce",
+  goal_resume: "\u25ce",
+  update_plan: "\u2261",
+  get_plan: "\u2261",
+  remote_bash: "\u2318",
 };
 
+function harnessCallDetail(name: string, input: unknown): string | undefined {
+  const args = input && typeof input === "object" ? input as Record<string, unknown> : {};
+  const text = (value: unknown): string => typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  const joinDetails = (...values: unknown[]) => values.map(text).filter(Boolean).join(" \u00b7 ");
+  const host = () => {
+    const ssh = args.ssh && typeof args.ssh === "object" ? args.ssh as Record<string, unknown> : args;
+    return text(ssh.host) ? `${text(ssh.user) ? `${text(ssh.user)}@` : ""}${text(ssh.host)}` : "";
+  };
+  switch (name) {
+    case "subagent_spawn":
+      return joinDetails(args.agent ?? args.role, args.alias ?? args.name, args.prompt);
+    case "subagent_spawn_batch":
+      return joinDetails(args.batchName, `${Array.isArray(args.jobs) ? args.jobs.length : 0} jobs`);
+    case "subagent_result": case "subagent_output": case "subagent_stop":
+    case "bg_task_status": case "bg_task_log": case "bg_task_stop":
+      return text(args.id);
+    case "subagent_list": case "bg_task_list":
+      return joinDetails(Array.isArray(args.status) ? args.status.map(text).filter(Boolean).join(", ") : args.status,
+        args.all === true ? "all sessions" : "");
+    case "agents_catalog":
+      return joinDetails(args.action, args.id);
+    case "bg_task_spawn": case "bg_task_watch": case "bg_task": case "bg_status":
+      return joinDetails(args.action, args.id, args.name, host(), args.command ??
+        (Array.isArray(args.argv) ? args.argv.map(text).filter(Boolean).join(" ") : undefined));
+    case "update_goal":
+      return text(args.status);
+    case "goal_resume":
+      return text(args.reason);
+    case "get_goal": case "get_background_activity": case "release_workflow": case "get_plan":
+      return "";
+    case "remote_bash":
+      return joinDetails(host(), args.command);
+    case "ssh_profile": case "ssh_mux":
+      return joinDetails(args.action, host(), args.all === true ? "all hosts" : "");
+    default:
+      return undefined;
+  }
+}
+
 function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3): string[] {
   if (width <= 0) return [];
   // Render the call alone at a wider width so terminal wrapping becomes truncation.
@@ -90,8 +141,9 @@ function compactCall(component: ToolComponent, width: number, theme?: Theme, ind
   }
   const failed = component.result?.isError === true;
   const running = !component.result || component.isPartial;
-  const detail = text.startsWith(`${component.toolName} `) ? text.slice(component.toolName.length).trimStart()
-    : text === component.toolName ? "" : text;
+  const detail = (component.getCallRenderer?.() ? undefined : harnessCallDetail(component.toolName, component.args)) ??
+    (text.startsWith(`${component.toolName} `) ? text.slice(component.toolName.length).trimStart()
+      : text === component.toolName ? "" : text);
   const label = component.toolName === "bash" ? "Shell"
     : component.toolName.replace(/_/g, " ").replace(/^./, letter => letter.toUpperCase());
   const suffix = failed ? " (failed)" : running ? " (running)" : "";

package/extensions/minimal-output/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { installMinimalOutputHook, loadToolPrototype, type MinimalOutputHook } from "./hook.ts";
 import type { SettingsControl } from "../settings/registry.ts";
+import { readHarnessSetting, updateHarnessSetting } from "../shared-harness-settings.ts";
 
 const ENTRY = "pi-better-harness-tool-output";
 
@@ -8,6 +9,16 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   let hook: MinimalOutputHook | undefined;
   let enabled = false;
   let running = false;
+  let initialDefault: boolean | undefined;
+
+  function defaultEnabled(): boolean {
+    if (initialDefault !== undefined) return initialDefault;
+    const value = readHarnessSetting<{ version?: unknown; enabled?: unknown }>("toolOutput");
+    if (value !== undefined && (value?.version !== 1 || typeof value.enabled !== "boolean")) {
+      throw new Error("Invalid tool-output default in global settings.json.");
+    }
+    return initialDefault = value?.enabled === true;
+  }
 
   function status(ctx: ExtensionContext): void {
     ctx.ui.setStatus(ENTRY, enabled ? "tools: minimal" : undefined);
@@ -36,7 +47,11 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
 
   async function restore(ctx: ExtensionContext): Promise<void> {
     if (ctx.mode !== "tui") return;
-    enabled = false;
+    try { enabled = defaultEnabled(); }
+    catch (error) {
+      enabled = false;
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom" && entry.customType === ENTRY) {
         const data = entry.data as { version?: unknown; enabled?: unknown } | undefined;
@@ -59,6 +74,14 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     const data = { version: 1, enabled: value === "Minimal" };
     try { pi.appendEntry(ENTRY, data); }
     catch (error) { data.version = 0; data.enabled = enabled; throw error; }
+    try { updateHarnessSetting("toolOutput", () => ({ version: 1, enabled: data.enabled })); }
+    catch (error) {
+      data.version = 0;
+      data.enabled = enabled;
+      // The session entry may already be on disk; restore its prior effective value too.
+      pi.appendEntry(ENTRY, { version: 1, enabled });
+      throw error;
+    }
     enabled = data.enabled;
     if (enabled) collapseTools(ctx);
     hook!.setEnabled(enabled);
@@ -75,7 +98,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
   subscribe();
   register();
-  pi.on("session_start", async (_event, ctx) => { subscribe(); await restore(ctx); register(); });
+  pi.on("session_start", async (_event, ctx) => { initialDefault = undefined; subscribe(); await restore(ctx); register(); });
   pi.on("session_tree", async (_event, ctx) => { await restore(ctx); });
   pi.on("agent_start", () => { running = true; });
   pi.on("agent_settled", (_event, ctx) => {
@@ -91,6 +114,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     hook = undefined;
     enabled = false;
     running = false;
+    initialDefault = undefined;
   });
 
   pi.registerCommand("tool-output", {

package/extensions/settings/page.ts

@@ -23,7 +23,7 @@ export async function chooseHarnessSetting(ctx: any, links: SettingsLink[], sele
     } : undefined;
     const items: SettingItem[] = [
       ...(callbackSetting ? [callbackSetting] : []),
-      ...controls.map(control => ({ id: `setting:${control.id}`, label: control.label, currentValue: control.get(), description: "Session setting", values: control.values })),
+      ...controls.map(control => ({ id: `setting:${control.id}`, label: control.label, currentValue: control.get(), description: "User default", values: control.values })),
       ...links.map(link => ({ id: `link:${link.id}`, label: link.label, currentValue: link.command, description: "Open package settings", values: [link.command] })),
     ];
     const feedback = new Text("", 0, 0);
@@ -41,10 +41,10 @@ export async function chooseHarnessSetting(ctx: any, links: SettingsLink[], sele
       if (control) {
         const previous = control.get();
         changing = true;
-        report("Saving session setting...");
+        report("Saving setting...");
         Promise.resolve().then(() => control.change(value, ctx)).then(() => {
           list.updateValue(id, control.get());
-          report("Session setting saved.");
+          report("Setting saved.");
         }).catch(error => {
           list.updateValue(id, previous);
           report(error instanceof Error ? error.message : String(error), true);

package/extensions/shared-harness-settings.ts

@@ -0,0 +1,114 @@
+// Generated from packages/harness-settings/index.ts. Do not edit directly.
+import { existsSync, lstatSync, realpathSync, readFileSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// Match Pi's settings lock without depending on a private SDK import.
+const lockfile = createRequire(import.meta.url)("proper-lockfile") as {
+  lockSync(path: string, options: { realpath: boolean }): () => void;
+};
+const NAMESPACE = "piBetterHarness";
+export interface HarnessSettingsSeams { agentDir?: () => string }
+
+export function harnessSettingsPath(seams: HarnessSettingsSeams = {}): string {
+  return join((seams.agentDir ?? getAgentDir)(), "settings.json");
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a JSON object.`);
+  return value as Record<string, unknown>;
+}
+
+function readSettings(path: string): Record<string, unknown> {
+  try { return object(JSON.parse(readFileSync(path, "utf8")), `Settings at ${path}`); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function section(settings: Record<string, unknown>): Record<string, unknown> {
+  return Object.hasOwn(settings, NAMESPACE) ? object(settings[NAMESPACE], NAMESPACE) : {};
+}
+
+function acquire(path: string): () => void {
+  for (let attempt = 0; attempt < 10; attempt++) {
+    try { return lockfile.lockSync(path, { realpath: false }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ELOCKED" || attempt === 9) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  throw new Error(`Cannot lock settings at ${path}`);
+}
+
+function lockedRead(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const release = acquire(path);
+  try { return readSettings(path); } finally { release(); }
+}
+
+function writeDestination(path: string): string {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return path;
+    throw error;
+  }
+  // Keep managed dotfiles links intact. A dangling link fails rather than being replaced.
+  return stat.isSymbolicLink() ? realpathSync(path) : path;
+}
+
+function mutate<T>(seams: HarnessSettingsSeams, change: (values: Record<string, unknown>) => T): T {
+  const path = harnessSettingsPath(seams);
+  mkdirSync((seams.agentDir ?? getAgentDir)(), { recursive: true });
+  const release = acquire(path);
+  let pending: string | undefined;
+  try {
+    // Read inside the lock so another session's settings are never replaced by a stale snapshot.
+    const settings = readSettings(path);
+    const values = section(settings);
+    const result = change(values);
+    settings[NAMESPACE] = values;
+    const destination = writeDestination(path);
+    pending = `${destination}.${randomUUID()}.tmp`;
+    writeFileSync(pending, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(pending, destination);
+    return result;
+  } finally {
+    try { if (pending) rmSync(pending, { force: true }); } finally { release(); }
+  }
+}
+
+export function readHarnessSetting<T = unknown>(
+  key: string,
+  seams: HarnessSettingsSeams = {},
+  legacy?: { path: string; parse: (value: unknown) => T },
+): T | undefined {
+  const values = section(lockedRead(harnessSettingsPath(seams)));
+  if (Object.hasOwn(values, key)) return values[key] as T;
+  if (!legacy) return undefined;
+  let raw: string;
+  try { raw = readFileSync(legacy.path, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  const migrated = legacy.parse(JSON.parse(raw));
+  return mutate(seams, current => {
+    if (!Object.hasOwn(current, key)) current[key] = migrated;
+    return current[key] as T;
+  });
+}
+
+export function updateHarnessSetting<T>(
+  key: string, update: (current: unknown) => T, seams: HarnessSettingsSeams = {},
+): T {
+  return mutate(seams, values => {
+    const next = update(values[key]);
+    values[key] = next;
+    return next;
+  });
+}

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -58,5 +58,8 @@
     "typebox": "^1.1.38",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
   }
 }

package/node_modules/pi-better-background-tasks/src/shared-callback-batcher.ts

@@ -1,8 +1,12 @@
 // Generated from packages/callback-batcher/index.ts. Do not edit directly.
-import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  harnessSettingsPath,
+  readHarnessSetting,
+  updateHarnessSetting,
+  type HarnessSettingsSeams,
+} from "./shared-harness-settings.ts";
 
 export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
@@ -13,9 +17,7 @@ export interface CallbackSettingsContext {
   ui?: { notify(message: string, type: "error"): void };
 }
 
-export interface CallbackSettingsSeams {
-  agentDir?: () => string;
-}
+export type CallbackSettingsSeams = HarnessSettingsSeams;
 
 export interface CallbackSettings {
   mode: CallbackDeliveryMode;
@@ -36,7 +38,12 @@ function validCallbackPreferences(value: unknown): value is { version: 1; mode:
     && data.version === 1 && isDeliveryMode(data.mode);
 }
 
-function callbackPreferencesPath(seams: CallbackSettingsSeams): string {
+function parseCallbackPreferences(value: unknown): { version: 1; mode: CallbackDeliveryMode } {
+  if (!validCallbackPreferences(value)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
+  return value;
+}
+
+function legacyCallbackPreferencesPath(seams: CallbackSettingsSeams): string {
   return join((seams.agentDir ?? getAgentDir)(), "extensions", CALLBACK_PREFERENCES_FILE);
 }
 
@@ -64,41 +71,27 @@ function getSessionDefault(ctx: CallbackSettingsContext, seams: CallbackSettings
     if (ctx.sessionManager) defaults.set(ctx.sessionManager, { sessionId, mode });
     return { mode, source: "default" };
   };
-  const path = callbackPreferencesPath(seams);
-  let text: string;
+  const path = harnessSettingsPath(seams);
   try {
-    text = readFileSync(path, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return snapshot("hold");
-    throw new Error(`Cannot read callback default at ${path}: ${String(error)}`, { cause: error });
-  }
-  try {
-    const data: unknown = JSON.parse(text);
-    if (!validCallbackPreferences(data)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
-    return snapshot(data.mode);
+    const data = readHarnessSetting<{ version: 1; mode: CallbackDeliveryMode }>("callbacks", seams, {
+      path: legacyCallbackPreferencesPath(seams),
+      parse: parseCallbackPreferences,
+    });
+    return snapshot(data === undefined ? "hold" : parseCallbackPreferences(data).mode);
   } catch (error) {
-    throw new Error(`Invalid callback default at ${path}: ${String(error)}`, { cause: error });
+    const prefix = (error as NodeJS.ErrnoException).code ? "Cannot read" : "Invalid";
+    throw new Error(`${prefix} callback default at ${path}: ${String(error)}`, { cause: error });
   }
 }
 
 /** Saves only the future-session default; never changes the active branch or batcher. */
 export function saveCallbackDefault(mode: CallbackDeliveryMode, seams: CallbackSettingsSeams = {}): void {
   if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing saved.");
-  const dir = join((seams.agentDir ?? getAgentDir)(), "extensions");
-  const path = join(dir, CALLBACK_PREFERENCES_FILE);
-  const tmp = join(dir, `.${CALLBACK_PREFERENCES_FILE}.${randomUUID()}.tmp`);
-  let created = false;
+  const path = harnessSettingsPath(seams);
   try {
-    mkdirSync(dir, { recursive: true });
-    const fd = openSync(tmp, "wx", 0o600);
-    created = true;
-    try { writeFileSync(fd, `${JSON.stringify({ version: 1, mode })}\n`); }
-    finally { closeSync(fd); }
-    renameSync(tmp, path);
+    updateHarnessSetting("callbacks", () => ({ version: 1, mode }), seams);
   } catch (error) {
     throw new Error(`Cannot save callback default at ${path}: ${String(error)}`, { cause: error });
-  } finally {
-    if (created) rmSync(tmp, { force: true });
   }
 }
 

package/node_modules/pi-better-background-tasks/src/shared-harness-settings.ts

@@ -0,0 +1,114 @@
+// Generated from packages/harness-settings/index.ts. Do not edit directly.
+import { existsSync, lstatSync, realpathSync, readFileSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// Match Pi's settings lock without depending on a private SDK import.
+const lockfile = createRequire(import.meta.url)("proper-lockfile") as {
+  lockSync(path: string, options: { realpath: boolean }): () => void;
+};
+const NAMESPACE = "piBetterHarness";
+export interface HarnessSettingsSeams { agentDir?: () => string }
+
+export function harnessSettingsPath(seams: HarnessSettingsSeams = {}): string {
+  return join((seams.agentDir ?? getAgentDir)(), "settings.json");
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a JSON object.`);
+  return value as Record<string, unknown>;
+}
+
+function readSettings(path: string): Record<string, unknown> {
+  try { return object(JSON.parse(readFileSync(path, "utf8")), `Settings at ${path}`); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function section(settings: Record<string, unknown>): Record<string, unknown> {
+  return Object.hasOwn(settings, NAMESPACE) ? object(settings[NAMESPACE], NAMESPACE) : {};
+}
+
+function acquire(path: string): () => void {
+  for (let attempt = 0; attempt < 10; attempt++) {
+    try { return lockfile.lockSync(path, { realpath: false }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ELOCKED" || attempt === 9) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  throw new Error(`Cannot lock settings at ${path}`);
+}
+
+function lockedRead(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const release = acquire(path);
+  try { return readSettings(path); } finally { release(); }
+}
+
+function writeDestination(path: string): string {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return path;
+    throw error;
+  }
+  // Keep managed dotfiles links intact. A dangling link fails rather than being replaced.
+  return stat.isSymbolicLink() ? realpathSync(path) : path;
+}
+
+function mutate<T>(seams: HarnessSettingsSeams, change: (values: Record<string, unknown>) => T): T {
+  const path = harnessSettingsPath(seams);
+  mkdirSync((seams.agentDir ?? getAgentDir)(), { recursive: true });
+  const release = acquire(path);
+  let pending: string | undefined;
+  try {
+    // Read inside the lock so another session's settings are never replaced by a stale snapshot.
+    const settings = readSettings(path);
+    const values = section(settings);
+    const result = change(values);
+    settings[NAMESPACE] = values;
+    const destination = writeDestination(path);
+    pending = `${destination}.${randomUUID()}.tmp`;
+    writeFileSync(pending, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(pending, destination);
+    return result;
+  } finally {
+    try { if (pending) rmSync(pending, { force: true }); } finally { release(); }
+  }
+}
+
+export function readHarnessSetting<T = unknown>(
+  key: string,
+  seams: HarnessSettingsSeams = {},
+  legacy?: { path: string; parse: (value: unknown) => T },
+): T | undefined {
+  const values = section(lockedRead(harnessSettingsPath(seams)));
+  if (Object.hasOwn(values, key)) return values[key] as T;
+  if (!legacy) return undefined;
+  let raw: string;
+  try { raw = readFileSync(legacy.path, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  const migrated = legacy.parse(JSON.parse(raw));
+  return mutate(seams, current => {
+    if (!Object.hasOwn(current, key)) current[key] = migrated;
+    return current[key] as T;
+  });
+}
+
+export function updateHarnessSetting<T>(
+  key: string, update: (current: unknown) => T, seams: HarnessSettingsSeams = {},
+): T {
+  return mutate(seams, values => {
+    const next = update(values[key]);
+    values[key] = next;
+    return next;
+  });
+}

package/node_modules/pi-better-goal/README.md

@@ -21,6 +21,20 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (60s through 600s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
 - An observable-progress stall state for active goals.
 
+## Settings Storage
+
+Goal preferences are saved only in Pi's global `~/.pi/agent/settings.json` under
+`piBetterHarness.goal` (or `$PI_CODING_AGENT_DIR/settings.json` when overridden).
+The payload retains `version: 1` and the boolean `autoContinue`,
+`conversationalResume`, and `pauseOnEscape` fields; omitted controls default to
+`true`. Updates preserve other Pi settings and other `piBetterHarness` keys.
+
+On first read, an existing `extensions/pi-better-goal-preferences.json` in the
+agent directory is validated and migrated when the global Goal key is absent.
+An existing global key is authoritative, and subsequent changes write only
+`settings.json`. Invalid preferences report an error instead of being replaced
+with defaults.
+
 ## Skill-Owned Workflows
 
 Skills that own execution and their own task plan can opt in through `SKILL.md` frontmatter:

package/node_modules/pi-better-goal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",
@@ -69,6 +69,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
+    "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.1"
   }
 }