@gotgenes/pi-permission-system 32.0.1 → 32.0.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [32.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.1...pi-permission-system-v32.0.2) (2026-09-11)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** keep a forwarded write when a file lock blocks the atomic rename ([d901116](https://github.com/gotgenes/pi-packages/commit/d9011165203b130675a3affd20a2792f7abd7105)), closes [#914](https://github.com/gotgenes/pi-packages/issues/914)
+* **pi-permission-system:** create a forwarding directory blocked by a transient file lock ([245683c](https://github.com/gotgenes/pi-packages/commit/245683c9153712d8991ceb21ece7884b2fb12f2a)), closes [#914](https://github.com/gotgenes/pi-packages/issues/914)
+
+### Documentation
+
+* **pi-permission-system:** record the transient filesystem retry ([eb7ab58](https://github.com/gotgenes/pi-packages/commit/eb7ab58cfd79d15de77bafa6afe8813e9dff7b72)), closes [#914](https://github.com/gotgenes/pi-packages/issues/914)
+
 ## [32.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.0...pi-permission-system-v32.0.1) (2026-09-11)
 
 

package/docs/troubleshooting.md

@@ -2,15 +2,16 @@
 
 ## Common Issues
 
-| Problem                                                           | Cause                                                             | Solution                                                                                                                                          |
-| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Config not applied (everything asks)                              | File not found or parse error                                     | Verify the global config at `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`); check for trailing commas |
-| Per-agent override not applied                                    | Frontmatter parsing issue                                         | Ensure `---` delimiters at file top; keep YAML simple; restart session                                                                            |
-| Tool blocked as unregistered                                      | Unknown tool name                                                 | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }`                                                                         |
-| `/skill:<name>` blocked                                           | Deny policy or confirmation unavailable                           | Check merged `skill` policy (global/project/agent layers). `ask` still requires UI or forwarded confirmation.                                     |
-| External file path blocked                                        | `external_directory` is `ask` without UI or `deny`                | Allow/ask the permission or keep file tools inside the active working directory.                                                                  |
-| Spurious external-path prompt for `cd <subdir> && grep … ../path` | Relative path was resolved against cwd instead of the `cd` target | Fixed in current version — paths after a leading `cd <subdir> &&` are resolved against the cd target, matching actual shell behavior.             |
-| Permission prompt is too verbose                                  | Generic extension tool input is large                             | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview.                                |
+| Problem                                                                                                 | Cause                                                                                   | Solution                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Config not applied (everything asks)                                                                    | File not found or parse error                                                           | Verify the global config at `~/.pi/agent/extensions/pi-permission-system/config.json` (respects `PI_CODING_AGENT_DIR`); check for trailing commas                                                                                                                           |
+| Per-agent override not applied                                                                          | Frontmatter parsing issue                                                               | Ensure `---` delimiters at file top; keep YAML simple; restart session                                                                                                                                                                                                      |
+| Tool blocked as unregistered                                                                            | Unknown tool name                                                                       | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }`                                                                                                                                                                                                   |
+| `/skill:<name>` blocked                                                                                 | Deny policy or confirmation unavailable                                                 | Check merged `skill` policy (global/project/agent layers). `ask` still requires UI or forwarded confirmation.                                                                                                                                                               |
+| External file path blocked                                                                              | `external_directory` is `ask` without UI or `deny`                                      | Allow/ask the permission or keep file tools inside the active working directory.                                                                                                                                                                                            |
+| Spurious external-path prompt for `cd <subdir> && grep … ../path`                                       | Relative path was resolved against cwd instead of the `cd` target                       | Fixed in current version — paths after a leading `cd <subdir> &&` are resolved against the cd target, matching actual shell behavior.                                                                                                                                       |
+| Permission prompt is too verbose                                                                        | Generic extension tool input is large                                                   | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview.                                                                                                                                                          |
+| Windows: `permission_forwarding.error — EPERM … rename` in the logs, and a subagent's tool call refused | An antivirus scanner or the search indexer held a transient handle on a forwarding file | The write is retried automatically for a short window. If it still fails, enable `debugLog` and look for `permission_forwarding.fs_retried` entries — their `attempts` and `code` say whether retrying is helping — then exclude the forwarding directory from the scanner. |
 
 ## Diagnostic Logging
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "32.0.1",
+  "version": "32.0.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/authority/forwarding-io.ts

@@ -29,6 +29,10 @@ import {
   type ForwardedSessionApproval,
   type PermissionForwardingLocation,
 } from "./permission-forwarding";
+import {
+  retryOnTransientFsError,
+  type TransientFsRetryRecord,
+} from "./transient-fs-retry";
 
 /** Valid `permissions:ui_prompt` source values, for tolerant request reads. */
 const UI_PROMPT_SOURCES = [
@@ -217,7 +221,14 @@ export function ensureDirectoryExists(
   description: string,
 ): boolean {
   try {
-    mkdirSync(path, { recursive: true, mode: OWNER_ONLY_DIRECTORY_MODE });
+    recordFsRetry(
+      logger,
+      "mkdir",
+      path,
+      retryOnTransientFsError(() => {
+        mkdirSync(path, { recursive: true, mode: OWNER_ONLY_DIRECTORY_MODE });
+      }),
+    );
     return true;
   } catch (error) {
     logPermissionForwardingError(
@@ -399,17 +410,51 @@ export function writeJsonFileAtomic(
   try {
     // `rename` preserves the temp file's mode, so setting it here is enough —
     // a response overwriting an existing file also comes through a fresh temp.
+    // The temp write is deliberately outside the retry: its failure shape is a
+    // write-denied directory, which no number of attempts resolves.
     writeFileSync(tempPath, JSON.stringify(value), {
       encoding: "utf-8",
       mode: OWNER_ONLY_FILE_MODE,
     });
-    renameSync(tempPath, filePath);
+    recordFsRetry(
+      logger,
+      "rename",
+      filePath,
+      retryOnTransientFsError(() => {
+        renameSync(tempPath, filePath);
+      }),
+    );
   } catch (error) {
     safeDeleteFile(logger, tempPath, "temporary permission-forwarding");
     throw error;
   }
 }
 
+/**
+ * Record a filesystem operation that only succeeded after retrying.
+ *
+ * Debug-only: a recovered write decided nothing, so it does not belong in the
+ * permission-decision record — but `attempts` and `code` are the whole
+ * diagnosis when a host keeps losing writes, and `debugLog` is exactly the
+ * switch a user reaching for that diagnosis turns on.
+ */
+function recordFsRetry(
+  logger: DebugReviewLogger | null,
+  operation: "rename" | "mkdir",
+  path: string,
+  record: TransientFsRetryRecord,
+): void {
+  if (record.attempts === 1) {
+    return;
+  }
+  logger?.debug("permission_forwarding.fs_retried", {
+    operation,
+    path,
+    attempts: record.attempts,
+    code: record.code,
+  });
+}
+
 export function readForwardedPermissionRequest(
   logger: DebugReviewLogger | null,
   filePath: string,

package/src/authority/transient-fs-retry.ts

@@ -0,0 +1,118 @@
+/**
+ * transient-fs-retry.ts — Survive a file lock that is about to clear.
+ *
+ * On Windows a `rename` or `mkdir` is not the POSIX operation of the same
+ * name: an antivirus scanner, the search indexer, or any other process holding
+ * a transient handle on a path fails the call with `EPERM`/`EBUSY`/`EACCES`.
+ * The forwarded-permission writes that ride on those calls are then simply
+ * lost — a child's request write becomes a refused tool call, and a serving
+ * heartbeat goes unpublished (#914).
+ *
+ * A few attempts a few milliseconds apart is enough for the common case. The
+ * decision lives here rather than at either call site so both inherit one
+ * errno set and one budget, and so it can be tested without a filesystem.
+ */
+
+/** Tuning seams, injected so a unit test asserts the backoff without sleeping. */
+export interface TransientFsRetryOptions {
+  delaysMs?: readonly number[];
+  sleep?: (ms: number) => void;
+}
+
+/** How an operation that eventually succeeded got there. */
+export interface TransientFsRetryRecord {
+  /** Attempts made, counting the first — `1` when it succeeded outright. */
+  attempts: number;
+  /** The transient errno that forced the retries, or `null` when there were none. */
+  code: string | null;
+}
+
+/**
+ * Run `operation`, retrying while a transient filesystem lock rejects it.
+ *
+ * Returns how it went, so the caller can record a recovery without this module
+ * having to know anything about logging. An error outside the transient set is
+ * rethrown immediately with no sleep, keeping a permanent `ENOTDIR`/`ENOENT`
+ * exactly as fast as it is today; an exhausted budget rethrows the last error,
+ * so every caller's existing `catch` keeps working unchanged.
+ */
+export function retryOnTransientFsError(
+  operation: () => void,
+  options?: TransientFsRetryOptions,
+): TransientFsRetryRecord {
+  const delaysMs = options?.delaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const sleep = options?.sleep ?? sleepBlocking;
+
+  let attempts = 0;
+  let code: string | null = null;
+
+  for (;;) {
+    try {
+      operation();
+      return { attempts: attempts + 1, code };
+    } catch (error) {
+      const transientCode = transientErrorCode(error);
+      if (transientCode === null || attempts >= delaysMs.length) {
+        throw error;
+      }
+      code = transientCode;
+      sleep(delaysMs[attempts] ?? 0);
+      attempts += 1;
+    }
+  }
+}
+
+// ── Module-private ─────────────────────────────────────────────────────────
+
+/**
+ * Three retries, 60 ms of blocking at worst.
+ *
+ * Sized against the two windows it has to fit inside: well under one
+ * `PERMISSION_FORWARDING_POLL_INTERVAL_MS` tick, so a retrying heartbeat write
+ * cannot push the serving node's timer into the next tick, and far under the
+ * grace a forwarding child waits out, so a parent retrying its own writes can
+ * never be the reason a child gives up on it.
+ */
+const DEFAULT_RETRY_DELAYS_MS: readonly number[] = [10, 20, 30];
+
+/**
+ * The errno values a transient lock produces on an otherwise-valid operation.
+ *
+ * This set is the platform gate: `process.platform` is unreadable in `src/`,
+ * and a POSIX host that produces one of these on a rename is in the same
+ * situation a Windows host is — worth one more attempt, and no worse off for
+ * it.
+ */
+const TRANSIENT_FS_ERROR_CODES: ReadonlySet<string> = new Set([
+  "EPERM",
+  "EBUSY",
+  "EACCES",
+]);
+
+/** The transient errno `error` carries, or `null` when retrying cannot help. */
+function transientErrorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return null;
+  }
+  const { code } = error as { code?: unknown };
+  return typeof code === "string" && TRANSIENT_FS_ERROR_CODES.has(code)
+    ? code
+    : null;
+}
+
+/**
+ * Block the calling thread for `ms`.
+ *
+ * Synchronous because every caller is: the heartbeat publish satisfies a
+ * `void` seam a timer drives. `Atomics.wait` on a never-notified buffer is the
+ * standard blocking sleep and is permitted on Node's main thread.
+ *
+ * The buffer is module-scoped — which persists across same-cwd session
+ * switches — and that is safe here precisely because nothing ever writes to
+ * it: every wait sees the initial zero and times out.
+ */
+const SLEEP_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+function sleepBlocking(ms: number): void {
+  Atomics.wait(SLEEP_BUFFER, 0, 0, ms);
+}