pi-better-goal 0.8.1 → 0.8.3

package/README.md

@@ -18,9 +18,23 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
-- 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.
+- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (60s through 600s by default), followed by a sticky hold recoverable with `/goal resume` or `alt+g`. Conversation, changed callback results, and background drains do not reopen an exhausted hold. Delays saturate at Node's timer limit, and observed background drains reset non-held 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:
@@ -30,7 +44,7 @@ metadata:
   workflow-role: coordinator
 ```
 
-Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit (or use `/workflow clear` to release it manually). Completing an active goal also releases ownership.
+Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator, preserving its objective and incomplete status. Reinvoke the skill explicitly before `/goal resume`; automatic continuation cannot reacquire ownership. Unrelated ordinary Goals are unchanged. Completing an active goal also releases ownership.
 
 A skill that is only an alias of a coordinator declares the target instead of a role:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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"
   }
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { CustomEditor, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CustomEditor, ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { isKeyRelease, matchesKey } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
@@ -257,6 +257,7 @@ function formatGoal(
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
     settings,
+    ...(continuation?.blocked && goal.status === "active" ? ["Resume: /goal resume or alt+g"] : []),
     ...(goal.status === "paused"
       ? [agentResumable(goal, preferences.conversationalResume)
         ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
@@ -432,10 +433,11 @@ export default function (pi: ExtensionAPI): void {
     if (!isPokeable(goal)) {
       return;
     }
-    setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
+    const held = currentContinuationState(ctx, goal.goalId)?.blocked === true;
+    setGoal(goalWithStatus(goal, "paused", undefined, held ? undefined : "interrupt"), ctx, "runtime");
     notifyGoal(ctx, currentPermissionHold(ctx, goal.goalId).blockers.length > 0
       ? "Goal remains permission-held. Use /goal resume or alt+g for one same-scope retry."
-      : preferences.conversationalResume
+      : preferences.conversationalResume && !held
       ? 'Goal paused. Say "go" to resume it, or use /goal resume.'
       : "Goal paused. Use /goal resume or alt+g to resume it.");
   };
@@ -446,13 +448,20 @@ export default function (pi: ExtensionAPI): void {
     escapeAbortSuppression.execution === executionGeneration;
 
   /** Why a paused goal cannot become active again, or null when it can. */
-  const resumeBlocker = (goal: GoalSnapshot): string | null => {
+  const resumeBlocker = (goal: GoalSnapshot, ctx: ExtensionContext): string | null => {
     if (!goal.command && skillCommandName(goal.objective)) {
       return "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.";
     }
     if (goal.command && !commandAvailable(pi, goal.command)) {
       return `Cannot resume: /${goal.command.name} is no longer registered at its original source.`;
     }
+    if (goal.command?.source === "skill") {
+      const owner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
+      const activeOwner = getWorkflow(ctx);
+      if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) {
+        return `Reinvoke /${goal.command.name} before resuming its workflow goal.`;
+      }
+    }
     return null;
   };
 
@@ -469,7 +478,10 @@ export default function (pi: ExtensionAPI): void {
     if (!current || (current.status !== "paused" && !held)) {
       return { ok: false, message: "Only paused or no-progress-held goals can be resumed." };
     }
-    const blocker = resumeBlocker(current);
+    if (source === "tool" && currentContinuationState(ctx, current.goalId)?.blocked) {
+      return { ok: false, message: "Only /goal resume or alt+g can reopen a no-progress hold." };
+    }
+    const blocker = resumeBlocker(current, ctx);
     if (blocker) {
       return { ok: false, message: blocker };
     }
@@ -544,7 +556,7 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     if (currentPermissionHold(ctx, goal.goalId).blockers.length > 0) return;
-    if (kind === "continuation" && currentContinuationState(ctx, goal.goalId)?.blocked) {
+    if (currentContinuationState(ctx, goal.goalId)?.blocked) {
       return;
     }
     const signature = `${goal.goalId}:${kind}`;
@@ -575,6 +587,7 @@ export default function (pi: ExtensionAPI): void {
       const current = currentGoalSnapshot(ctx);
       return isPokeable(current) && current.goalId === goalId &&
         currentPermissionHold(ctx, goalId).blockers.length === 0 &&
+        !currentContinuationState(ctx, goalId)?.blocked &&
         continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
     };
     const goal = currentGoalSnapshot(ctx);
@@ -637,7 +650,8 @@ export default function (pi: ExtensionAPI): void {
     const goal = currentGoalSnapshot(ctx);
     const wakePlan = planBackgroundDrainWake(backgroundDrainTracker, goal, snapshot);
     backgroundDrainTracker = wakePlan.nextTracker;
-    if (isPokeable(goal) && wakePlan.wakeSignature && currentPermissionHold(ctx, goal.goalId).blockers.length === 0) {
+    if (isPokeable(goal) && wakePlan.wakeSignature && currentPermissionHold(ctx, goal.goalId).blockers.length === 0 &&
+        !currentContinuationState(ctx, goal.goalId)?.blocked) {
       // Persist external progress now: a foreground/callback turn may cancel its delayed wake.
       clearIdleContinuation();
       resetContinuationState(goal);
@@ -842,6 +856,36 @@ export default function (pi: ExtensionAPI): void {
     if (latestSnapshot) collectIfPossible();
   });
 
+  const changePreference = async (ctx: ExtensionCommandContext, key: keyof GoalPreferences, enabled: boolean): Promise<void> => {
+    const previous = preferences;
+    preferences = writeGoalPreference(key, enabled);
+    if (previous.autoContinue !== preferences.autoContinue) clearIdleContinuation();
+    syncResumeTool(getGoal(ctx));
+    applyStatus(ctx);
+    if (!previous.autoContinue && preferences.autoContinue) {
+      const snapshot = await publishSnapshot(ctx);
+      const goal = getGoal(ctx);
+      if (snapshot && isPokeable(goal) && !isForegroundBusy(ctx) && !snapshot.backgroundRunning) {
+        scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
+      }
+    }
+  };
+  const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
+    currentCtx = ctx;
+    if (ctx.hasUI && ctx.mode !== "rpc" && typeof ctx.ui.custom === "function") {
+      await ctx.ui.custom<void>((tui, theme, _kb, done) => createGoalSettingsPage(theme, {
+        get: () => ({ ...preferences }),
+        change: (key, enabled) => changePreference(ctx, key, enabled),
+      }, () => tui.requestRender(), () => done()));
+    } else {
+      ctx.ui.notify(`${formatPreferences(preferences)}\nPreferences: ${goalPreferencesPath()}`, "info");
+    }
+  };
+  const contribution = { id: "goal", label: "Goal", command: "/goal settings", open: openSettings };
+  const registerSettings = () => pi.events.emit("harness-settings:register", contribution);
+  const unsubscribeSettingsRequest = pi.events.on("harness-settings:request", registerSettings);
+  registerSettings();
+
   pi.registerCommand("goal", {
     description: "Create, inspect, pause, resume, clear, or complete the active goal; configure persistent goal settings",
     getArgumentCompletions: goalArgumentCompletions,
@@ -851,25 +895,8 @@ export default function (pi: ExtensionAPI): void {
       const current = getGoal(ctx);
 
       if (trimmed === "settings" || trimmed.startsWith("settings ")) {
-        const changePreference = async (key: keyof GoalPreferences, enabled: boolean): Promise<void> => {
-          const previous = preferences;
-          preferences = writeGoalPreference(key, enabled);
-          if (previous.autoContinue !== preferences.autoContinue) clearIdleContinuation();
-          syncResumeTool(getGoal(ctx));
-          applyStatus(ctx);
-          if (!previous.autoContinue && preferences.autoContinue) {
-            const snapshot = await publishSnapshot(ctx);
-            const goal = getGoal(ctx);
-            if (snapshot && isPokeable(goal) && !isForegroundBusy(ctx) && !snapshot.backgroundRunning) {
-              scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
-            }
-          }
-        };
-        if (trimmed === "settings" && ctx.hasUI && ctx.mode !== "rpc" && typeof ctx.ui.custom === "function") {
-          await ctx.ui.custom<void>((tui, theme, _kb, done) => createGoalSettingsPage(theme, {
-            get: () => ({ ...preferences }),
-            change: changePreference,
-          }, () => tui.requestRender(), () => done()));
+        if (trimmed === "settings") {
+          await openSettings(ctx);
           return;
         }
         const [, setting, mode, ...extra] = trimmed.split(/\s+/);
@@ -882,7 +909,7 @@ export default function (pi: ExtensionAPI): void {
           try {
             const key = setting === "auto-continue" ? "autoContinue"
               : setting === "conversational-resume" ? "conversationalResume" : "pauseOnEscape";
-            await changePreference(key, mode === "on");
+            await changePreference(ctx, key, mode === "on");
           } catch (error) {
             notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
             return;
@@ -1088,13 +1115,25 @@ export default function (pi: ExtensionAPI): void {
   pi.registerTool({
     name: "release_workflow",
     label: "Release Workflow",
-    description: "Release the active skill-owned workflow after its final handoff and completion audit.",
+    description: "Release the active skill-owned workflow after its final handoff and completion audit. Its bound active Goal pauses; explicitly reinvoke the skill before resuming that Goal.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = getWorkflow(ctx);
       if (!owner) return { content: [{ type: "text", text: "No workflow owns this session." }], details: { released: false } };
+      const goal = getGoal(ctx);
+      let resumeCommand: string | undefined;
+      if (goal?.status === "active" && goal.command?.source === "skill") {
+        const boundOwner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
+        if (boundOwner?.name === owner.name && boundOwner.path === owner.path) {
+          setGoal(goalWithStatus(goal, "paused"), ctx, "tool");
+          resumeCommand = goal.command.name;
+        }
+      }
       recordWorkflow(null);
-      return { content: [{ type: "text", text: `Released ${owner.name} workflow ownership.` }], details: { released: true, owner: owner.name } };
+      return {
+        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete. Reinvoke /${resumeCommand} before /goal resume.` : ""}` }],
+        details: { released: true, owner: owner.name, goalPaused: resumeCommand !== undefined },
+      };
     },
   });
 
@@ -1198,7 +1237,8 @@ export default function (pi: ExtensionAPI): void {
     // A paused goal stays paused while the user talks: the message is ordinary
     // conversation. Only /goal resume, the hotkey, or goal_resume resume it.
     const goal = getGoal(ctx);
-    if (goal?.status === "active" && currentPermissionHold(ctx, goal.goalId).blockers.length === 0) {
+    if (goal?.status === "active" && currentPermissionHold(ctx, goal.goalId).blockers.length === 0 &&
+        !currentContinuationState(ctx, goal.goalId)?.blocked) {
       executionGeneration += 1;
       clearIdleContinuation();
       lastAgentEvidence = null;
@@ -1230,6 +1270,9 @@ export default function (pi: ExtensionAPI): void {
     const questionInstruction = snapshot.backgroundRunning
       ? " A blocking user question (ask_user_question) holds this whole turn until the user answers, and background completions wait behind it. Harvest finished background results before asking, and ask only when the answer is needed to proceed."
       : "";
+    const heldInstruction = goal?.status === "active" && currentContinuationState(ctx, goal.goalId)?.blocked
+      ? "Automatic Goal continuation is held for no progress. Answer the current user message or inspect delivered background results without restarting autonomous Goal work. Only /goal resume or alt+g reopens this hold."
+      : "";
 
     if (owner) {
       if (!workflowAvailable(owner)) {
@@ -1253,7 +1296,8 @@ export default function (pi: ExtensionAPI): void {
             : "") +
           `Active workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
           (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
-          (questionInstruction ? `\n\n${questionInstruction.trim()}` : ""),
+          (questionInstruction ? `\n\n${questionInstruction.trim()}` : "") +
+          (heldInstruction ? `\n\n${heldInstruction}` : ""),
       };
     }
 
@@ -1264,7 +1308,7 @@ export default function (pi: ExtensionAPI): void {
     return {
       systemPrompt:
         `${event.systemPrompt}\n\n` +
-        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}${questionInstruction}` +
+        `Pi Better Goal active objective: ${goal.objective}. ${heldInstruction || "Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit."}${backgroundInstruction}${questionInstruction}` +
         (permissionPrompt ? `\n\n${permissionPrompt}` : ""),
     };
   });
@@ -1395,6 +1439,7 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     const previous = currentContinuationState(ctx, goal.goalId) ?? createContinuationState(goal.goalId);
+    if (previous.blocked) return;
     const repeated = previous.lastEvidenceSignature === evidence.signature;
     const noProgressRetries = repeated ? previous.noProgressRetries + 1 : 0;
     const blocked = repeated && noProgressRetries >= MAX_NO_PROGRESS_RETRIES;
@@ -1415,7 +1460,7 @@ export default function (pi: ExtensionAPI): void {
       if (ctx.hasUI) {
         ctx.ui.setStatus(EXTENSION_NAME, "waiting: no progress");
         ctx.ui.notify(
-          `Goal automatic continuation is waiting after ${noProgressRetries} identical retries (${evidence.summary}). New input or background activity will resume it.`,
+          `Goal automatic continuation is waiting after ${noProgressRetries} identical retries (${evidence.summary}). Use /goal resume or alt+g to resume it.`,
           "warning",
         );
       }
@@ -1425,6 +1470,8 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
+    if (typeof unsubscribeSettingsRequest === "function") unsubscribeSettingsRequest();
+
     executionGeneration += 1;
     sessionGeneration += 1;
     escapeAbortSuppression = undefined;

package/src/preferences.ts

@@ -1,6 +1,11 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
+import {
+  harnessSettingsPath,
+  readHarnessSetting,
+  updateHarnessSetting,
+  type HarnessSettingsSeams,
+} from "./shared-harness-settings.js";
 
 export interface GoalPreferences {
   autoContinue: boolean;
@@ -8,30 +13,33 @@ export interface GoalPreferences {
   pauseOnEscape: boolean;
 }
 
-export interface GoalPreferenceSeams {
-  agentDir?: () => string;
-}
+export interface GoalPreferenceSeams extends HarnessSettingsSeams {}
 
 export function goalPreferencesPath(seams: GoalPreferenceSeams = {}): string {
-  return join((seams.agentDir ?? getAgentDir)(), "extensions", "pi-better-goal-preferences.json");
+  return harnessSettingsPath(seams);
 }
 
 export function readGoalPreferences(seams: GoalPreferenceSeams = {}): GoalPreferences {
   const path = goalPreferencesPath(seams);
-  let raw: string;
+  const legacyPath = join((seams.agentDir ?? getAgentDir)(), "extensions", "pi-better-goal-preferences.json");
   try {
-    raw = readFileSync(path, "utf8");
+    const value = readHarnessSetting<unknown>("goal", seams, {
+      path: legacyPath,
+      parse: (value) => ({ version: 1, ...parseGoalPreferences(value, legacyPath) }),
+    });
+    return parseGoalPreferences(value, path);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return { autoContinue: true, conversationalResume: true, pauseOnEscape: true };
+    if (messageOf(error).startsWith("Goal preferences at ")) throw error;
+    if (error instanceof SyntaxError || /not valid JSON/.test(messageOf(error))) {
+      throw new Error(`Goal preferences at ${path} are not valid JSON: ${messageOf(error)}`);
     }
     throw new Error(`Goal preferences at ${path} could not be read: ${messageOf(error)}`);
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`Goal preferences at ${path} are not valid JSON: ${messageOf(error)}`);
+}
+
+function parseGoalPreferences(parsed: unknown, path: string): GoalPreferences {
+  if (parsed === undefined) {
+    return { autoContinue: true, conversationalResume: true, pauseOnEscape: true };
   }
   const value = parsed as Partial<GoalPreferences> & { version?: unknown } | null;
   if (value?.version !== 1 ||
@@ -53,19 +61,20 @@ export function writeGoalPreference(
   enabled: boolean,
   seams: GoalPreferenceSeams = {},
 ): GoalPreferences {
-  const preferences = { ...readGoalPreferences(seams), [key]: enabled };
+  // Migrate legacy preferences before updating the authoritative value under lock.
+  readGoalPreferences(seams);
   const path = goalPreferencesPath(seams);
-  const pending = `${path}.${process.pid}.tmp`;
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(pending, `${JSON.stringify({ version: 1, ...preferences }, null, 2)}\n`, "utf8");
-    renameSync(pending, path);
+    const { version: _version, ...preferences } = updateHarnessSetting("goal", (current) => ({
+      version: 1,
+      ...parseGoalPreferences(current, path),
+      [key]: enabled,
+    }), seams);
+    return preferences;
   } catch (error) {
+    if (messageOf(error).startsWith("Goal preferences at ")) throw error;
     throw new Error(`Goal preferences at ${path} could not be written: ${messageOf(error)}`);
-  } finally {
-    rmSync(pending, { force: true });
   }
-  return preferences;
 }
 
 function messageOf(error: unknown): string {

package/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;
+  });
+}