pi-model-fallback 0.5.3 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.5.7] - 2026-10-19
+
+### Fixed
+
+- Remove the automatic `package.json` push release trigger restored in 0.5.6. Releases stay behind the explicit `release_authorized` dispatch so merged version bumps do not publish on merge, and publication is owned by the separate release lane.
+
+## [0.5.6] - 2026-10-19
+
+### Fixed
+
+- Restore automatic releases on a `package.json` version bump pushed to `main`; the manual **Auto Release** dispatch stays available with `release_authorized` checked.
+
+## [0.5.5] - 2026-10-19
+
+### Fixed
+
+- Serialize cooldown read-modify-write transactions across sessions and processes, publish state atomically, and coordinate reset and expiry pruning so cached snapshots cannot discard or resurrect other sessions' entries. Retry transient Windows sharing violations during atomic replacement.
+
+### Changed
+
+- Run CI on Windows as well as Ubuntu, and accept CRLF markdown when checking release docs.
+
+## [0.5.4] - 2026-10-16
+
+### Changed
+
+- Pin Pi SDK development dependencies to 1.2.0 and verify the extension against the actual Pi host runtime.
+
 ## [0.5.3] - 2026-10-12
 
 ### Changed

package/README.md

@@ -121,6 +121,8 @@ The extension stores:
 
 If the package is installed project-locally and the current project references it from `.pi/settings.json`, those files live under the project `.pi/` directory. Otherwise they live under the user agent directory.
 
+Cooldown updates re-read and merge the current state under a shared `proper-lockfile` lock, including across Pi processes. Reset uses the same lock. State is published by atomic replacement, so readers never see a partially written document; expired entries are ignored on read and removed during the next mutation. Lock acquisition is bounded (about two seconds of retries); a lock or write error is reported rather than overwriting state without the lock. A reset clears entries committed before it; a new failure committed afterward can create a new cooldown.
+
 ## Behavior notes
 
 - Successful responses do nothing.

package/docs/pi-sdk-compatibility.md

@@ -0,0 +1,25 @@
+# Pi SDK 1.2.0 compatibility
+
+This package is verified with the frozen development/test versions:
+
+- `@earendil-works/pi-agent-core`: `1.2.0`
+- `@earendil-works/pi-ai`: `1.2.0`
+- `@earendil-works/pi-coding-agent`: `1.2.0`
+- `@earendil-works/pi-tui`: `1.2.0`
+
+These exact versions are dev/test pins. Public peer dependency ranges are
+unchanged; the package continues to require Pi 1.1 or later.
+
+The upstream [Pi SDK compatibility notes](https://github.com/eiei114/pi-extension-template/blob/main/docs/pi-sdk-compatibility.md)
+record the 1.2.0 `before_agent_start` message-type union and startup busy-state
+changes. This extension does not read user-only event fields, so no production
+API migration was needed. Tests now construct the current `messageType: "user"`
+event and account for sessions being busy while startup handlers run.
+
+From a repository checkout, run `npm run smoke:pi` to exercise the installed
+local Pi CLI and RPC host with this extension. The deterministic offline provider
+returns a source 429 and a successful fallback response; the harness also checks
+a handled invalid config, a second-process reload and feature response, clean
+shutdown, and the native host shell. It uses an isolated agent directory and
+makes no paid inference. `npm run ci` runs the smoke as well as typecheck, tests,
+and pack dry-run.

package/docs/usage.md

@@ -29,3 +29,5 @@ Cooldown defaults when a rule omits `cooldownMs`:
 `Retry-After` and `x-ratelimit-reset*` response headers override `cooldownMs` and those defaults.
 
 If `autoRetry` is disabled, the existing run is not automatically continued.
+
+Shared cooldown state uses a cross-process lock and atomic file replacement. Concurrent failures merge against the latest file, not a session's cached snapshot. Reset takes the same lock and can repair a malformed state file; it clears earlier commits, not failures committed afterward. Expired entries are ignored when selecting a model and cleaned up during the next state mutation. Lock/write failures are reported instead of performing an unlocked overwrite.

package/docs/verification/pi-sdk-smoke.json

@@ -0,0 +1,103 @@
+{
+  "schema_version": 1,
+  "verification_contract": "pi-sdk-behavior-v2",
+  "sdk_versions": {
+    "@earendil-works/pi-agent-core": "1.2.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0"
+  },
+  "platform": "win32",
+  "model_inference": "No paid inference; actual pinned Pi CLI/RPC, extension loader, lifecycle and fallback model runtime use a deterministic offline faux provider.",
+  "unhandled_errors": 0,
+  "extension_load_errors": 0,
+  "cases": [
+    {
+      "name": "extension_load",
+      "command": "npm run smoke:pi",
+      "exit_code": 0,
+      "passed": true,
+      "evidence": "{\"exit_code\":0,\"signal\":null,\"timed_out\":false,\"duration_ms\":1013,\"rpc_records\":[{\"type\":\"extension_ui_request\",\"id\":\"150821d3-944b-44d0-99e2-92a72920ec36\",\"method\":\"notify\",\"message\":\"Model fallback: enabled\\nAuto retry: enabled\\nConfig: <isolated-agent-dir>\\\\model-fallback\\\\config.json\\nState: <isolated-agent-dir>\\\\model-fallback\\\\state.json\\nRules: 1\\nConfig warnings: none\\nPersistent entries: 0\\nActive fallback: none\\nOriginal model: none\\nReason: none\",\"notifyType\":\"info\"},{\"id\":\"extension-load\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}}],\"stderr\":\"\",\"error\":null}",
+      "assertions": [
+        {
+          "id": "extension_registered",
+          "expected": "The actual Pi host handles the package's registered status command",
+          "observed": "{\"response\":{\"id\":\"extension-load\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}},\"notification\":{\"type\":\"extension_ui_request\",\"id\":\"150821d3-944b-44d0-99e2-92a72920ec36\",\"method\":\"notify\",\"message\":\"Model fallback: enabled\\nAuto retry: enabled\\nConfig: <isolated-agent-dir>\\\\model-fallback\\\\config.json\\nState: <isolated-agent-dir>\\\\model-fallback\\\\state.json\\nRules: 1\\nConfig warnings: none\\nPersistent entries: 0\\nActive fallback: none\\nOriginal model: none\\nReason: none\",\"notifyType\":\"info\"},\"exit_code\":0}",
+          "passed": true
+        }
+      ]
+    },
+    {
+      "name": "happy_path",
+      "command": "npm run smoke:pi",
+      "exit_code": 0,
+      "passed": true,
+      "evidence": "{\"exit_code\":0,\"signal\":null,\"timed_out\":false,\"duration_ms\":1014,\"rpc_records\":[{\"type\":\"extension_ui_request\",\"id\":\"f2cfe8b5-18e7-4054-8649-707c1224832e\",\"method\":\"setStatus\",\"statusKey\":\"model-fallback\"},{\"id\":\"happy-path\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"started\"}},{\"type\":\"message_end\",\"message\":{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Exercise the deterministic fallback response.\"}],\"timestamp\":1792131439674}},{\"type\":\"message_end\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"\"}],\"api\":\"pi-sdk-smoke-faux\",\"provider\":\"pi-sdk-smoke-source\",\"model\":\"source\",\"usage\":{\"input\":563,\"output\":0,\"cacheRead\":0,\"cacheWrite\":563,\"totalTokens\":1126,\"cost\":{\"input\":0,\"output\":0,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0}},\"stopReason\":\"error\",\"errorMessage\":\"Error: 429 deterministic smoke failure\",\"timestamp\":1792131439650,\"thinkingLevel\":\"off\"}},{\"type\":\"turn_end\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"\"}],\"api\":\"pi-sdk-smoke-faux\",\"provider\":\"pi-sdk-smoke-source\",\"model\":\"source\",\"usage\":{\"input\":563,\"output\":0,\"cacheRead\":0,\"cacheWrite\":563,\"totalTokens\":1126,\"cost\":{\"input\":0,\"output\":0,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0}},\"stopReason\":\"error\",\"errorMessage\":\"Error: 429 deterministic smoke failure\",\"timestamp\":1792131439650,\"thinkingLevel\":\"off\"},\"toolResults\":[]},{\"type\":\"extension_ui_request\",\"id\":\"8a3bc896-7b4d-4b0a-bcc2-83193ca06029\",\"method\":\"setStatus\",\"statusKey\":\"model-fallback\",\"statusText\":\"fallback:pi-sdk-smoke-target/target\"},{\"type\":\"extension_ui_request\",\"id\":\"919dd5a4-0993-4101-83c8-d29ecc31f3d5\",\"method\":\"notify\",\"message\":\"Model fallback: pi-sdk-smoke-source/source → pi-sdk-smoke-target/target (429). Future sessions preselect fallback until 2026-10-16T06:18:19.680Z.\",\"notifyType\":\"warning\"},{\"type\":\"message_end\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"pi-model-fallback-smoke-ok\"}],\"api\":\"pi-sdk-smoke-faux\",\"provider\":\"pi-sdk-smoke-target\",\"model\":\"target\",\"usage\":{\"input\":563,\"output\":7,\"cacheRead\":0,\"cacheWrite\":563,\"totalTokens\":1133,\"cost\":{\"input\":0,\"output\":0,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0}},\"stopReason\":\"stop\",\"timestamp\":1792131439650,\"thinkingLevel\":\"off\"}},{\"type\":\"turn_end\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"pi-model-fallback-smoke-ok\"}],\"api\":\"pi-sdk-smoke-faux\",\"provider\":\"pi-sdk-smoke-target\",\"model\":\"target\",\"usage\":{\"input\":563,\"output\":7,\"cacheRead\":0,\"cacheWrite\":563,\"totalTokens\":1133,\"cost\":{\"input\":0,\"output\":0,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0}},\"stopReason\":\"stop\",\"timestamp\":1792131439650,\"thinkingLevel\":\"off\"},\"toolResults\":[]},{\"type\":\"agent_settled\",\"aborted\":false}],\"stderr\":\"\",\"error\":null}",
+      "assertions": [
+        {
+          "id": "feature_response",
+          "expected": "The real Pi run handles a 429, persists the configured fallback, and returns the target response",
+          "observed": "{\"response\":{\"id\":\"happy-path\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"started\"}},\"source_error\":{\"type\":\"message_end\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"\"}],\"api\":\"pi-sdk-smoke-faux\",\"provider\":\"pi-sdk-smoke-source\",\"model\":\"source\",\"usage\":{\"input\":563,\"output\":0,\"cacheRead\":0,\"cacheWrite\":563,\"totalTokens\":1126,\"cost\":{\"input\":0,\"output\":0,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0}},\"stopReason\":\"error\",\"errorMessage\":\"Error: 429 deterministic smoke failure\",\"timestamp\":1792131439650,\"thinkingLevel\":\"off\"}},\"fallback_response\":{\"type\":\"message_end\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"pi-model-fallback-smoke-ok\"}],\"api\":\"pi-sdk-smoke-faux\",\"provider\":\"pi-sdk-smoke-target\",\"model\":\"target\",\"usage\":{\"input\":563,\"output\":7,\"cacheRead\":0,\"cacheWrite\":563,\"totalTokens\":1133,\"cost\":{\"input\":0,\"output\":0,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0}},\"stopReason\":\"stop\",\"timestamp\":1792131439650,\"thinkingLevel\":\"off\"}},\"fallback_notification\":{\"type\":\"extension_ui_request\",\"id\":\"919dd5a4-0993-4101-83c8-d29ecc31f3d5\",\"method\":\"notify\",\"message\":\"Model fallback: pi-sdk-smoke-source/source → pi-sdk-smoke-target/target (429). Future sessions preselect fallback until 2026-10-16T06:18:19.680Z.\",\"notifyType\":\"warning\"},\"agent_settled\":{\"type\":\"agent_settled\",\"aborted\":false},\"user_message_count\":1,\"persisted_state\":{\"source\":{\"provider\":\"pi-sdk-smoke-source\",\"model\":\"source\"},\"fallback\":{\"provider\":\"pi-sdk-smoke-target\",\"model\":\"target\"},\"status\":429,\"until\":\"2026-10-16T06:18:19.680Z\",\"createdAt\":\"2026-10-16T06:17:19.680Z\"},\"exit_code\":0}",
+          "passed": true
+        }
+      ]
+    },
+    {
+      "name": "error_path",
+      "command": "npm run smoke:pi",
+      "exit_code": 0,
+      "passed": true,
+      "evidence": "{\"exit_code\":0,\"signal\":null,\"timed_out\":false,\"duration_ms\":963,\"rpc_records\":[{\"type\":\"extension_ui_request\",\"id\":\"8ed2cb69-da08-4c3b-b9aa-3b2e042617c8\",\"method\":\"notify\",\"message\":\"Model fallback config error: Unsupported config version: 2.\",\"notifyType\":\"warning\"},{\"type\":\"extension_ui_request\",\"id\":\"739c37cd-366e-46fa-b25a-49c957448732\",\"method\":\"notify\",\"message\":\"Model fallback: enabled\\nAuto retry: enabled\\nConfig: <isolated-agent-dir>\\\\model-fallback\\\\config.json\\nState: <isolated-agent-dir>\\\\model-fallback\\\\state.json\\nRules: 1\\nConfig warnings: none\\nPersistent entries: 0\\nActive fallback: none\\nOriginal model: none\\nReason: none\",\"notifyType\":\"info\"},{\"id\":\"error-path\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}}],\"stderr\":\"\",\"error\":null}",
+      "assertions": [
+        {
+          "id": "handled_error",
+          "expected": "The actual extension reports a malformed config as a handled warning without crashing Pi",
+          "observed": "{\"response\":{\"id\":\"error-path\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}},\"warning\":{\"type\":\"extension_ui_request\",\"id\":\"8ed2cb69-da08-4c3b-b9aa-3b2e042617c8\",\"method\":\"notify\",\"message\":\"Model fallback config error: Unsupported config version: 2.\",\"notifyType\":\"warning\"},\"exit_code\":0}",
+          "passed": true
+        }
+      ]
+    },
+    {
+      "name": "reload_cleanup",
+      "command": "npm run smoke:pi",
+      "exit_code": 0,
+      "passed": true,
+      "evidence": "{\"exit_code\":0,\"signal\":null,\"timed_out\":false,\"duration_ms\":977,\"rpc_records\":[{\"type\":\"extension_ui_request\",\"id\":\"7eebdc06-9361-463d-8702-59b1fcf47520\",\"method\":\"notify\",\"message\":\"Model fallback: enabled\\nAuto retry: enabled\\nConfig: <isolated-agent-dir>\\\\model-fallback\\\\config.json\\nState: <isolated-agent-dir>\\\\model-fallback\\\\state.json\\nRules: 1\\nConfig warnings: none\\nPersistent entries: 0\\nActive fallback: none\\nOriginal model: none\\nReason: none\",\"notifyType\":\"info\"},{\"id\":\"reload-first\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}}],\"stderr\":\"\",\"error\":null}\n--- next Pi process ---\n{\"exit_code\":0,\"signal\":null,\"timed_out\":false,\"duration_ms\":943,\"rpc_records\":[{\"type\":\"extension_ui_request\",\"id\":\"c14e9202-6c27-45c0-ba9e-08befeff728a\",\"method\":\"notify\",\"message\":\"Model fallback: enabled\\nAuto retry: enabled\\nConfig: <isolated-agent-dir>\\\\model-fallback\\\\config.json\\nState: <isolated-agent-dir>\\\\model-fallback\\\\state.json\\nRules: 1\\nConfig warnings: none\\nPersistent entries: 0\\nActive fallback: none\\nOriginal model: none\\nReason: none\",\"notifyType\":\"info\"},{\"id\":\"reload-status\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}},{\"type\":\"extension_ui_request\",\"id\":\"f68c1ead-b99e-4ddd-a43b-e0eb798cbb35\",\"method\":\"notify\",\"message\":\"Model fallback: persistent state cleared; no remembered original model.\",\"notifyType\":\"info\"},{\"type\":\"extension_ui_request\",\"id\":\"f6e7f463-ffb9-4ac8-8cba-68a94653e32b\",\"method\":\"setStatus\",\"statusKey\":\"model-fallback\"},{\"id\":\"reload-feature\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}}],\"stderr\":\"\",\"error\":null}",
+      "assertions": [
+        {
+          "id": "reloaded_extension_registered",
+          "expected": "A second real Pi process reloads the extension and handles its registered status command",
+          "observed": "{\"response\":{\"id\":\"reload-status\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}},\"notification\":{\"type\":\"extension_ui_request\",\"id\":\"c14e9202-6c27-45c0-ba9e-08befeff728a\",\"method\":\"notify\",\"message\":\"Model fallback: enabled\\nAuto retry: enabled\\nConfig: <isolated-agent-dir>\\\\model-fallback\\\\config.json\\nState: <isolated-agent-dir>\\\\model-fallback\\\\state.json\\nRules: 1\\nConfig warnings: none\\nPersistent entries: 0\\nActive fallback: none\\nOriginal model: none\\nReason: none\",\"notifyType\":\"info\"},\"second_exit_code\":0}",
+          "passed": true
+        },
+        {
+          "id": "reloaded_feature_response",
+          "expected": "The reloaded second process executes reset and returns its package-specific handled response",
+          "observed": "{\"response\":{\"id\":\"reload-feature\",\"type\":\"response\",\"command\":\"prompt\",\"success\":true,\"data\":{\"disposition\":\"handled\"}},\"notification\":{\"type\":\"extension_ui_request\",\"id\":\"f68c1ead-b99e-4ddd-a43b-e0eb798cbb35\",\"method\":\"notify\",\"message\":\"Model fallback: persistent state cleared; no remembered original model.\",\"notifyType\":\"info\"}}",
+          "passed": true
+        },
+        {
+          "id": "clean_shutdown",
+          "expected": "Both actual Pi processes exit cleanly without unhandled, extension-load, or shutdown errors",
+          "observed": "{\"first_exit_code\":0,\"second_exit_code\":0,\"first_timed_out\":false,\"second_timed_out\":false,\"first_unhandled_error\":false,\"second_unhandled_error\":false,\"first_extension_load_error\":false,\"second_extension_load_error\":false}",
+          "passed": true
+        }
+      ]
+    },
+    {
+      "name": "host_shell",
+      "command": "npm run smoke:pi",
+      "exit_code": 0,
+      "passed": true,
+      "evidence": "{\"exit_code\":0,\"signal\":null,\"timed_out\":false,\"rpc_records\":[],\"stderr\":\"\",\"error\":null}",
+      "assertions": [
+        {
+          "id": "native_shell_boundary",
+          "expected": "The native host shell launches the locally pinned Pi CLI and returns exactly 1.2.0",
+          "observed": "{\"exit_code\":0,\"output\":\"1.2.0\",\"expected_version\":\"1.2.0\",\"stderr\":\"\",\"error\":null}",
+          "passed": true
+        }
+      ]
+    }
+  ]
+}

package/extensions/index.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -17,7 +16,7 @@ import {
   type RuleWarning,
 } from "../lib/config.js";
 import { parseReasonFromErrorMessage, parseStatusFromErrorMessage } from "../lib/error-status.js";
-import { emptyState, findActiveStateEntry, pruneExpiredState, readState, upsertStateEntry, validateStateShape, writeState, type FallbackState } from "../lib/state.js";
+import { findActiveStateEntry, readState, updateState, upsertStateEntry, writeState, type FallbackState } from "../lib/state.js";
 import { isRecord } from "../lib/internal.ts";
 import { modelFallbackPaths, readConfig, writeConfig, type ModelFallbackPaths } from "../lib/storage.js";
 
@@ -98,18 +97,9 @@ export default function modelFallback(pi: ExtensionAPI) {
   async function loadState(ctx: ExtensionContext): Promise<FallbackState | undefined> {
     try {
       syncPaths(ctx);
-      const statePath = paths.state;
-      if (!existsSync(statePath)) {
-        state = emptyState();
-        return state;
-      }
-
-      const before = validateStateShape(JSON.parse(await readFile(statePath, "utf8")));
-      const after = pruneExpiredState(before);
-      state = after;
-      if (JSON.stringify(before) !== JSON.stringify(after)) {
-        await writeState(statePath, after);
-      }
+      // Prune the snapshot for selection, but never write a stale read back over another session.
+      // Mutating transactions prune the current on-disk state while holding the state lock.
+      state = await readState(paths.state);
       return state;
     } catch (error) {
       ctx.ui.notify(`Model fallback state error: ${errorMessage(error)}`, "warning");
@@ -210,10 +200,11 @@ export default function modelFallback(pi: ExtensionAPI) {
       if (!ok) ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
       return false;
     }
-    const loadedState = state ?? (await loadState(ctx)) ?? emptyState();
     if (isCancelled()) return false;
-    state = upsertStateEntry(loadedState, { source, fallback: match.fallback, status, until, createdAt: now.toISOString(), ruleName: match.rule.name });
-    await writeState(paths.state, state);
+    state = await updateState(paths.state, (current) => isCancelled() ? current : upsertStateEntry(current, {
+      source, fallback: match.fallback, status, until, createdAt: now.toISOString(), ruleName: match.rule.name,
+    }));
+    if (isCancelled()) return false;
     ctx.ui.notify(`Model fallback: ${sourceKey} → ${activeFallbackKey} (${status}). Future sessions preselect fallback until ${until}.`, "warning");
     return true;
   }

package/lib/state.ts

@@ -1,9 +1,14 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import lockfile from "proper-lockfile";
 import { modelRefKey, type ModelRef } from "./config.ts";
-import { isRecord, readJsonIfExists, readModelRef, readNonEmptyString } from "./internal.ts";
+import { isNodeError, isRecord, readJsonIfExists, readModelRef, readNonEmptyString } from "./internal.ts";
 
 export const STATE_VERSION = 1;
+const WINDOWS_RENAME_RETRY_MS = 1000;
+const WINDOWS_RENAME_RETRY_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
 
 export interface FallbackStateEntry {
   source: ModelRef;
@@ -30,8 +35,75 @@ export async function readState(path: string, now = new Date()): Promise<Fallbac
 }
 
 export async function writeState(path: string, state: FallbackState): Promise<void> {
+  const next = validateStateShape(state);
+  // Explicit replacement (notably reset) must also be able to repair a corrupt old file.
+  await withStateLock(path, (target, checkLock) => publishState(target, next, checkLock));
+}
+
+/** Serialize the entire read/modify/publish transaction, including across Pi processes. */
+export async function updateState(path: string, update: (current: FallbackState) => FallbackState): Promise<FallbackState> {
+  return withStateLock(path, async (target, checkLock) => {
+    const next = validateStateShape(update(await readState(target)));
+    checkLock();
+    await publishState(target, next, checkLock);
+    return next;
+  });
+}
+
+async function withStateLock<T>(path: string, operation: (target: string, checkLock: () => void) => Promise<T>): Promise<T> {
   await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(validateStateShape(state), null, 2)}\n`, "utf8");
+  // Aliases of the same agent directory must share a lock (the state file may not exist yet).
+  const target = join(await realpath(dirname(path)), basename(path));
+  let compromised: Error | undefined;
+  const release = await lockfile.lock(target, {
+    realpath: false,
+    retries: { retries: 100, factor: 1, minTimeout: 20, maxTimeout: 20, randomize: false },
+    onCompromised: (error) => { compromised = error; },
+  });
+  const checkLock = () => { if (compromised) throw compromised; };
+  try {
+    checkLock();
+    return await operation(target, checkLock);
+  } finally {
+    await release();
+  }
+}
+
+async function publishState(path: string, state: FallbackState, checkLock: () => void): Promise<void> {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let created = false;
+  try {
+    const file = await open(temporary, "wx", 0o600);
+    created = true;
+    try {
+      await file.writeFile(`${JSON.stringify(state, null, 2)}\n`, "utf8");
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    // Readers see either the old complete document or the new one, never a partial write.
+    checkLock();
+    await replaceStateFile(temporary, path, checkLock);
+  } finally {
+    if (created) await rm(temporary, { force: true });
+  }
+}
+
+async function replaceStateFile(source: string, target: string, checkLock: () => void): Promise<void> {
+  // Windows can reject replacement while an unlocked reader briefly has the target open.
+  const deadline = Date.now() + WINDOWS_RENAME_RETRY_MS;
+  let retryDelayMs = 10;
+  for (;;) {
+    try {
+      await rename(source, target);
+      return;
+    } catch (error) {
+      if (process.platform !== "win32" || !isNodeError(error) || !WINDOWS_RENAME_RETRY_CODES.has(error.code ?? "") || Date.now() >= deadline) throw error;
+      await delay(retryDelayMs);
+      checkLock();
+      retryDelayMs = Math.min(retryDelayMs + 10, 100);
+    }
+  }
 }
 
 export function upsertStateEntry(state: FallbackState, entry: FallbackStateEntry): FallbackState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-model-fallback",
-  "version": "0.5.3",
+  "version": "0.5.7",
   "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,8 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "node --test tests/*.test.mjs",
-    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "smoke:pi": "node scripts/pi-sdk-smoke.mjs",
+    "ci": "npm run typecheck && npm test && npm run smoke:pi && npm run pack:check",
     "pack:check": "npm pack --dry-run"
   },
   "pi": {
@@ -50,13 +51,17 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^1.1.0",
-    "@earendil-works/pi-ai": "^1.1.0",
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-agent-core": "1.2.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@types/node": "^26.6.3",
+    "@types/proper-lockfile": "4.1.4",
     "jiti": "^2.7.0",
     "typebox": "latest",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "proper-lockfile": "4.1.2"
   }
 }