@gotgenes/pi-permission-system 26.1.0 → 26.2.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [26.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.1.0...pi-permission-system-v26.2.0) (2026-08-17)
+
+
+### Features
+
+* **pi-permission-system:** publish a serving heartbeat while draining the inbox ([2055e35](https://github.com/gotgenes/pi-packages/commit/2055e353e147af6738ddc23c2c755f56f8032f8b)), closes [#721](https://github.com/gotgenes/pi-packages/issues/721)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** fail fast when an out-of-process parent is not serving ([e190af9](https://github.com/gotgenes/pi-packages/commit/e190af9f06c49375432f19bb228e068ade01c912)), closes [#721](https://github.com/gotgenes/pi-packages/issues/721)
+
+
+### Documentation
+
+* **pi-permission-system:** document out-of-process forwarding liveness ([b5a50d5](https://github.com/gotgenes/pi-packages/commit/b5a50d535c97ca0ec388c5f482afb395e15289fa)), closes [#721](https://github.com/gotgenes/pi-packages/issues/721)
+
 ## [26.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.0.0...pi-permission-system-v26.1.0) (2026-08-17)
 
 

package/docs/configuration.md

@@ -97,20 +97,20 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 
 ## Runtime Knobs
 
-| Key                         | Default  | Description                                                                                                                                                                                          |
-| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debugLog`                  | `false`  | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                                                        |
-| `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings unredacted — see [Log file sensitivity](#log-file-sensitivity) |
-| `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                           |
-| `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                    |
-| `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose in-process parent is not draining its inbox gives up in ~2 s regardless.   |
-| `promptMaxRows`             | `24`     | Max rows a permission prompt renders before eliding its evidence. The request's own facts are never elided by this budget; `Ctrl+O` expands the prompt to the complete request.                      |
-| `promptFieldMaxWidth`       | `400`    | Max characters of any one field shown in a permission prompt. This is what bounds a single long field (a here-string command, say) that would otherwise fill the prompt through wrapping.            |
-| `reviewLogFieldMaxWidth`    | `1000`   | Max characters of any one value written to the review log. A longer value is stored shortened, marked with an ellipsis. Raise it to keep longer values; this is a length bound, not redaction.       |
-| `toolInputPreviewMaxLength` | —        | **Deprecated and ignored.** Superseded by `promptMaxRows` / `promptFieldMaxWidth`. Still accepted so an existing config is not rejected, but the value no longer applies; setting it logs a warning. |
-| `toolTextSummaryMaxLength`  | —        | **Deprecated and ignored.** Superseded by `promptMaxRows` / `promptFieldMaxWidth`. Still accepted so an existing config is not rejected, but the value no longer applies; setting it logs a warning. |
-| `piInfrastructureReadPaths` | `[]`     | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME`/`${HOME}` expansion and wildcard patterns (`*`, `?`).                                       |
-| `authorizerChain`           | `[]`     | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)).                           |
+| Key                         | Default  | Description                                                                                                                                                                                                                                  |
+| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugLog`                  | `false`  | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                                                                                                |
+| `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings unredacted — see [Log file sensitivity](#log-file-sensitivity)                                         |
+| `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                                                                   |
+| `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                                                            |
+| `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose parent is not draining its inbox gives up in ~2 s regardless, whether that parent runs in this process or its own. |
+| `promptMaxRows`             | `24`     | Max rows a permission prompt renders before eliding its evidence. The request's own facts are never elided by this budget; `Ctrl+O` expands the prompt to the complete request.                                                              |
+| `promptFieldMaxWidth`       | `400`    | Max characters of any one field shown in a permission prompt. This is what bounds a single long field (a here-string command, say) that would otherwise fill the prompt through wrapping.                                                    |
+| `reviewLogFieldMaxWidth`    | `1000`   | Max characters of any one value written to the review log. A longer value is stored shortened, marked with an ellipsis. Raise it to keep longer values; this is a length bound, not redaction.                                               |
+| `toolInputPreviewMaxLength` | —        | **Deprecated and ignored.** Superseded by `promptMaxRows` / `promptFieldMaxWidth`. Still accepted so an existing config is not rejected, but the value no longer applies; setting it logs a warning.                                         |
+| `toolTextSummaryMaxLength`  | —        | **Deprecated and ignored.** Superseded by `promptMaxRows` / `promptFieldMaxWidth`. Still accepted so an existing config is not rejected, but the value no longer applies; setting it logs a warning.                                         |
+| `piInfrastructureReadPaths` | `[]`     | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME`/`${HOME}` expansion and wildcard patterns (`*`, `?`).                                                                               |
+| `authorizerChain`           | `[]`     | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)).                                                                   |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
 No debug output is printed to the terminal.

package/docs/subagent-integration.md

@@ -35,7 +35,20 @@ For in-process child sessions, detection and forwarding use the event-driven reg
 ### When nobody answers
 
 A forwarded request is only useful if some session is draining the inbox it was written into.
-The polling session publishes the session id it polls, and an in-process child checks that its target is published before committing to a long wait.
+The polling session publishes the session id it polls, and a child checks that its target is published before committing to a long wait.
+
+The announcement goes out on two channels, because a child cannot always reach the same one.
+A child running inside its parent's process reads a process-global registry.
+A child running as a separate `pi` process (the `PI_SUBAGENT_PARENT_SESSION` path) shares no memory with its parent, so it reads a heartbeat record the serving session refreshes under `<agent dir>/sessions/permission-forwarding/serving/`, holding the served session id, the serving process id, and the time it was last refreshed.
+
+For an out-of-process target, four things count as "not draining":
+
+| What the child finds                              | What it means                                                                |
+| ------------------------------------------------- | ---------------------------------------------------------------------------- |
+| No record                                         | The parent exited, never served, or runs a version that does not publish one |
+| A record naming a process that is gone            | The parent was killed rather than shut down                                  |
+| A record nobody has refreshed for several seconds | The parent's process survives but has stopped polling                        |
+| A record for a different session id               | The child is forwarding somewhere nobody is listening                        |
 
 If the target is not draining its inbox, the child gives up after a two-second grace window rather than waiting out `forwardingTimeoutMs`, and the tool is blocked with:
 
@@ -47,6 +60,7 @@ permission requests.
 
 The grace window exists so a request that arrives while the parent is switching sessions is not abandoned in the gap.
 A target that *is* draining its inbox is waited on for the full `forwardingTimeoutMs`, however long the human takes to decide.
+That includes a parent whose human is still deliberating at an earlier forwarded prompt: it keeps refreshing its heartbeat throughout, so a second child does not read it as gone.
 
 Every other way the forwarding path can give up — an unresolvable parent session, forwarding directories that cannot be created, a request that cannot be written, an unreadable response, and the timeout itself — is reported the same way: as approval being unavailable, with a reason naming the specific failure.
 None of them is reported as a user denial, because no user was ever asked.
@@ -68,8 +82,13 @@ The serving node records its decider on the response — a rule of its own (with
 That is the difference between a human approving a subagent's request and the parent's policy approving it on their behalf — two outcomes that were previously indistinguishable in the log.
 An older parent that sends no decider yields `"decision": null`: the hop is still recorded, and the answer is still honored.
 
-This liveness signal is process-local, so it applies to in-process children only.
-A child running as a separate `pi` process (the `PI_SUBAGENT_PARENT_SESSION` path) cannot observe its parent's polling and still waits the full timeout.
+### Upgrading
+
+Upgrade the parent before relying on the out-of-process signal — in practice, restart the interactive session after upgrading the package.
+
+A parent session still running a version that predates the heartbeat publishes none, and a child on a version that expects one reads that absence as "not draining" and gives up in about two seconds.
+That only happens in the window where an upgrade lands while a parent session is already running, and it resolves as soon as that session restarts.
+Nothing needs to be edited, and in-process children are unaffected: parent and child there are the same running copy by construction.
 
 ---
 

package/package.json

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

package/src/authority/approval-escalator.ts

@@ -19,6 +19,7 @@ import {
   sleep,
   writeJsonFileAtomic,
 } from "#src/authority/forwarding-io";
+import type { TargetServingLookup } from "#src/authority/forwarding-liveness";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type ForwardedAccessFacts,
@@ -33,7 +34,6 @@ import {
   resolvePermissionForwardingTarget,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/authority/permission-forwarding";
-import type { ServingLookup } from "#src/authority/serving-registry";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { createPermissionRequestId } from "#src/permission-request-id";
 import { buildUiPrompt } from "#src/permission-ui-prompt";
@@ -97,8 +97,8 @@ export interface ParentAuthorizerDeps {
   forwardingDir: string;
   /** In-process subagent session registry for forwarding target resolution. */
   registry?: SubagentSessionRegistry;
-  /** Whether the resolved target is draining its inbox (in-process targets only). */
-  serving: ServingLookup;
+  /** Whether the resolved target is draining its inbox, on whichever channel can say. */
+  serving: TargetServingLookup;
   /** How long to wait for the target's answer, read live so config edits apply. */
   getTimeoutMs: () => number;
   logger: DebugReviewLogger;
@@ -181,7 +181,7 @@ function forwardableRequestId(requesterRequestId: string): string {
 export class ParentAuthorizer implements TerminalAuthorizer {
   private readonly forwardingDir: string;
   private readonly registry: SubagentSessionRegistry | undefined;
-  private readonly serving: ServingLookup;
+  private readonly serving: TargetServingLookup;
   private readonly getTimeoutMs: () => number;
   private readonly logger: DebugReviewLogger;
 
@@ -387,11 +387,17 @@ export class ParentAuthorizer implements TerminalAuthorizer {
         unservedSince !== null &&
         Date.now() - unservedSince >= PERMISSION_FORWARDING_SERVING_GRACE_MS
       ) {
+        const observation = this.serving.describe(target);
         this.logger.review("forwarded_permission.no_serving_session", {
           requestId,
           requesterSessionId: request.requesterSessionId,
           targetSessionId,
-          servingSessionIds: this.serving.servingIds(),
+          // Which channel answered, and what it saw: the difference between a
+          // parent that exited, one that was killed, and one polling under a
+          // different session id is the whole diagnosis of a stalled forward.
+          servingChannel: observation.channel,
+          servingState: observation.state,
+          servingSessionIds: observation.servingIds,
         });
         this.discardRequest(location, requestPath);
         return abandon(
@@ -421,21 +427,17 @@ export class ParentAuthorizer implements TerminalAuthorizer {
   /**
    * Track how long the target has looked unserved, or `null` while it looks fine.
    *
-   * Only an in-process target (`source: "registry"`) can be judged: a target in
-   * another process shares no serving registry with this one, so its absence
-   * from the registry says nothing (#719, follow-up in #721).
+   * Which channel can answer for this target is the judge's decision, not this
+   * one's: a target it cannot judge answers `null`, which resets the window
+   * exactly as "serving" does, so an unjudgeable target waits out the timeout.
    */
   private checkServingLiveness(
     target: PermissionForwardingTarget,
     unservedSince: number | null,
   ): number | null {
-    if (target.source !== "registry") {
-      return null;
-    }
-    if (this.serving.isServing(target.sessionId)) {
-      return null;
-    }
-    return unservedSince ?? Date.now();
+    return this.serving.isServing(target) === false
+      ? (unservedSince ?? Date.now())
+      : null;
   }
 
   /**

package/src/authority/authorizer.ts

@@ -1,10 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TargetServingLookup } from "#src/authority/forwarding-liveness";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type {
   PromptPreferences,
   requestPermissionDecision,
 } from "#src/authority/permission-prompt-component";
-import type { ServingLookup } from "#src/authority/serving-registry";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { PermissionEventBus } from "#src/permission-events";
 import type { AuthorizerLog, PermissionQuery } from "#src/service";
@@ -108,8 +108,8 @@ export interface AuthorizerSelectionDeps {
   forwardingDir: string;
   /** In-process subagent session registry for forwarding target resolution. */
   registry?: SubagentSessionRegistry;
-  /** Which sessions are draining a forwarded-permission inbox. */
-  servingRegistry: ServingLookup;
+  /** Whether a forwarding target is draining its inbox, on whichever channel can say. */
+  serving: TargetServingLookup;
   /** The forwarding timeout, read live so a config edit applies to the next ask. */
   getForwardingTimeoutMs: () => number;
   logger: DebugReviewLogger;
@@ -145,7 +145,7 @@ export function selectAuthorizer(
       terminal: new ParentAuthorizer(ctx, {
         forwardingDir: deps.forwardingDir,
         registry: deps.registry,
-        serving: deps.servingRegistry,
+        serving: deps.serving,
         getTimeoutMs: deps.getForwardingTimeoutMs,
         logger: deps.logger,
       }),

package/src/authority/forwarding-liveness.ts

@@ -0,0 +1,450 @@
+/**
+ * forwarding-liveness.ts — Is anyone draining a forwarded-permission inbox?
+ *
+ * The in-process answer already exists: a serving session marks itself in the
+ * process-global `ServingSessionRegistry`, and an in-process child abandons a
+ * target that has looked unmarked for the grace window instead of waiting out
+ * the full forwarding timeout (#719).
+ *
+ * A child spawned as a separate `pi` process shares no `globalThis` with its
+ * parent, so that mark is invisible to it and it keeps waiting the full ten
+ * minutes — every `ask` forwarded to a session that has already exited costs
+ * the whole timeout and ends in a denial nobody made (#735 scenario 1).
+ *
+ * The filesystem is the only channel those two processes share, so the serving
+ * session publishes a heartbeat there: one record per serving session,
+ * refreshed while it polls and withdrawn when it stops.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ensureDirectoryExists,
+  isErrnoCode,
+  logPermissionForwardingError,
+  safeDeleteFile,
+  writeJsonFileAtomic,
+} from "#src/authority/forwarding-io";
+import type { PermissionForwardingTarget } from "#src/authority/permission-forwarding";
+import {
+  encodeSessionIdForPath,
+  PERMISSION_FORWARDING_POLL_INTERVAL_MS,
+} from "#src/authority/permission-forwarding";
+import type {
+  ServingAnnouncer,
+  ServingLookup,
+} from "#src/authority/serving-registry";
+import type { DebugReviewLogger } from "#src/session-logger";
+
+/**
+ * How often a serving session rewrites its heartbeat — four poll ticks.
+ *
+ * Longer than the poll interval so `ForwardingManager` can announce on every
+ * tick without four filesystem writes a second, and short enough that a record
+ * deleted underneath its owner reappears well inside the grace window a
+ * forwarding child waits out before abandoning.
+ */
+export const SERVING_HEARTBEAT_REFRESH_MS =
+  4 * PERMISSION_FORWARDING_POLL_INTERVAL_MS;
+
+/**
+ * How long a heartbeat may go unrefreshed before its writer is presumed gone —
+ * five refreshes.
+ *
+ * Generous because a delayed Node timer is not a dead session, and because the
+ * case this threshold exists for (a process that is alive but no longer
+ * polling) is the rare one: an exited session withdraws its record and a killed
+ * one is caught by the recorded pid, neither of which waits for staleness.
+ */
+export const SERVING_HEARTBEAT_STALE_MS = 5 * SERVING_HEARTBEAT_REFRESH_MS;
+
+/** What a serving session publishes while it drains its forwarded-permission inbox. */
+export interface ServingHeartbeat {
+  sessionId: string;
+  /** The serving process, so a killed session is detectable without waiting out staleness. */
+  pid: number;
+  updatedAt: number;
+}
+
+/**
+ * How a session's heartbeat reads right now.
+ *
+ * Only `"alive"` means someone is draining the inbox. The other three are the
+ * ways a target can be unserved, kept apart because they are the diagnosis a
+ * stalled forward needs: `"absent"` is a session that exited (or never served,
+ * or runs a version that does not publish), `"dead_pid"` one that was killed,
+ * and `"stale"` one whose process survives but stopped polling.
+ */
+export type HeartbeatState = "alive" | "absent" | "stale" | "dead_pid";
+
+/**
+ * Read side of the heartbeat channel, consumed by a forwarding child.
+ *
+ * Separate from the announce seam because the two have no caller in common: a
+ * serving session only publishes, and a forwarding child only reads (ISP).
+ */
+export interface HeartbeatReader {
+  read(sessionId: string): HeartbeatState;
+  /** Every session whose record reads as alive, for the abandonment diagnostic. */
+  servingIds(): readonly string[];
+}
+
+/**
+ * Query-side seam: is the session a forwarding target names being drained?
+ *
+ * Keyed on the target rather than a session id because the answer depends on
+ * how the target was resolved. An in-process child and its parent share a
+ * `globalThis`, so the registry answers for them; an out-of-process pair shares
+ * only the filesystem; and a session that owns the inbox it is forwarding to is
+ * not a case either channel describes.
+ *
+ * Consolidating that into one collaborator is what keeps `ParentAuthorizer`
+ * from holding two lookups and re-deciding which one applies — the decision has
+ * one home, and a third channel would not reach the poll loop.
+ */
+export interface TargetServingLookup {
+  /** `true` serving, `false` not serving, `null` when the target carries no signal. */
+  isServing(target: PermissionForwardingTarget): boolean | null;
+  /** What the judge observed, for the review entry a child writes when it gives up. */
+  describe(target: PermissionForwardingTarget): ServingObservation;
+}
+
+/** What answered a liveness question, and what it saw. */
+export interface ServingObservation {
+  channel: "registry" | "heartbeat" | "none";
+  /** The heartbeat state behind a `"heartbeat"` answer; `null` on the other channels. */
+  state: HeartbeatState | null;
+  servingIds: readonly string[];
+}
+
+/** Constructor config for {@link ForwardingLivenessJudge}. */
+export interface ForwardingLivenessJudgeDeps {
+  /** Answers for a target the requester shares a process with. */
+  registry: ServingLookup;
+  /** Answers for a target in another process. */
+  heartbeats: HeartbeatReader;
+}
+
+/**
+ * Routes a liveness question to the channel that can answer it.
+ *
+ * The routing key is `PermissionForwardingTarget.source`, which the resolver
+ * already produces — so "in-process" is decided once, where the target is
+ * found, rather than re-derived here (#719).
+ */
+export class ForwardingLivenessJudge implements TargetServingLookup {
+  constructor(private readonly deps: ForwardingLivenessJudgeDeps) {}
+
+  isServing(target: PermissionForwardingTarget): boolean | null {
+    switch (target.source) {
+      case "registry":
+        return this.deps.registry.isServing(target.sessionId);
+      case "env":
+        return this.deps.heartbeats.read(target.sessionId) === "alive";
+      case "self":
+        return null;
+    }
+  }
+
+  describe(target: PermissionForwardingTarget): ServingObservation {
+    switch (target.source) {
+      case "registry":
+        return {
+          channel: "registry",
+          state: null,
+          servingIds: this.deps.registry.servingIds(),
+        };
+      case "env":
+        return {
+          channel: "heartbeat",
+          state: this.deps.heartbeats.read(target.sessionId),
+          servingIds: this.deps.heartbeats.servingIds(),
+        };
+      case "self":
+        return { channel: "none", state: null, servingIds: [] };
+    }
+  }
+}
+
+const SERVING_HEARTBEAT_DIRECTORY_NAME = "serving";
+
+/**
+ * Where serving heartbeats live: beside the `sessions/` tree, never inside it.
+ *
+ * A heartbeat under `sessions/<id>/` would make that session root permanently
+ * non-empty, entangling liveness with the request/response cleanup whose
+ * removal ordering already produced an ENOENT write loop (#398). Kept disjoint,
+ * that logic stays untouched and "who is serving" is a single directory read.
+ */
+export function servingHeartbeatDir(forwardingDir: string): string {
+  return join(forwardingDir, SERVING_HEARTBEAT_DIRECTORY_NAME);
+}
+
+/** The heartbeat record for `sessionId`, under {@link servingHeartbeatDir}. */
+export function servingHeartbeatPath(
+  forwardingDir: string,
+  sessionId: string,
+): string {
+  return join(
+    servingHeartbeatDir(forwardingDir),
+    `${encodeSessionIdForPath(sessionId)}.json`,
+  );
+}
+
+/** Constructor config for {@link ServingHeartbeatStore}. */
+export interface ServingHeartbeatStoreDeps {
+  forwardingDir: string;
+  logger: DebugReviewLogger;
+  /** Injected so the refresh throttle and staleness are testable without sleeping. */
+  now?: () => number;
+  /** The process to record. Injected so a test can publish a pid it controls. */
+  pid?: number;
+  /** Injected so a test can decide which pids are running. */
+  isProcessAlive?: (pid: number) => boolean;
+}
+
+/**
+ * Publishes this session's serving heartbeat to the filesystem.
+ *
+ * Satisfies the same {@link ServingAnnouncer} seam as `ServingSessionRegistry`,
+ * so `ForwardingManager` announces to both channels through one collaborator
+ * and neither knows the other exists.
+ *
+ * `markServing` is idempotent by that seam's contract and internally throttled,
+ * so the caller may announce on every poll tick. Nothing here throws: it runs
+ * from a timer, and a filesystem failure must degrade to the pre-existing
+ * timeout rather than break the poll loop.
+ */
+export class ServingHeartbeatStore
+  implements ServingAnnouncer, HeartbeatReader
+{
+  private readonly forwardingDir: string;
+  private readonly logger: DebugReviewLogger;
+  private readonly now: () => number;
+  private readonly pid: number;
+  private readonly isProcessAlive: (pid: number) => boolean;
+  private published: { sessionId: string; at: number } | null = null;
+  private hasSweptDeadRecords = false;
+
+  constructor(deps: ServingHeartbeatStoreDeps) {
+    this.forwardingDir = deps.forwardingDir;
+    this.logger = deps.logger;
+    this.now = deps.now ?? Date.now;
+    this.pid = deps.pid ?? process.pid;
+    this.isProcessAlive = deps.isProcessAlive ?? isRunningProcess;
+  }
+
+  /** Publish (or refresh) `sessionId`'s heartbeat. Throttled; never throws. */
+  markServing(sessionId: string): void {
+    const at = this.now();
+    if (this.isThrottled(sessionId, at)) {
+      return;
+    }
+
+    const directory = servingHeartbeatDir(this.forwardingDir);
+    if (
+      !ensureDirectoryExists(
+        this.logger,
+        directory,
+        "permission forwarding serving heartbeat",
+      )
+    ) {
+      return;
+    }
+    this.sweepDeadRecordsOnce();
+
+    const heartbeat: ServingHeartbeat = {
+      sessionId,
+      pid: this.pid,
+      updatedAt: at,
+    };
+    try {
+      writeJsonFileAtomic(
+        this.logger,
+        servingHeartbeatPath(this.forwardingDir, sessionId),
+        heartbeat,
+      );
+    } catch (error) {
+      logPermissionForwardingError(
+        this.logger,
+        `Failed to publish the serving heartbeat for session '${sessionId}'`,
+        error,
+      );
+      return;
+    }
+    this.published = { sessionId, at };
+  }
+
+  /** Withdraw `sessionId`'s heartbeat, leaving the directory for its siblings. */
+  clearServing(sessionId: string): void {
+    if (this.published?.sessionId === sessionId) {
+      this.published = null;
+    }
+    safeDeleteFile(
+      this.logger,
+      servingHeartbeatPath(this.forwardingDir, sessionId),
+      "permission forwarding serving heartbeat",
+    );
+  }
+
+  /** How `sessionId`'s heartbeat reads right now. */
+  read(sessionId: string): HeartbeatState {
+    const record = this.readRecord(
+      servingHeartbeatPath(this.forwardingDir, sessionId),
+    );
+    return record === null ? "absent" : this.classify(record);
+  }
+
+  /** Every session whose record reads as alive. */
+  servingIds(): readonly string[] {
+    const ids: string[] = [];
+    for (const { record } of this.listRecords()) {
+      if (record !== null && this.classify(record) === "alive") {
+        ids.push(record.sessionId);
+      }
+    }
+    return ids;
+  }
+
+  // ── Private methods ────────────────────────────────────────────────
+
+  /**
+   * Delete the records of processes that are provably gone, once per session.
+   *
+   * Without this the directory grows one record per session that was killed
+   * rather than shut down, forever. Bounded to a single directory read at the
+   * first announcement, and safe under pid reuse: a wrongly swept owner
+   * republishes within the refresh window, which is shorter than the grace a
+   * forwarding child waits out.
+   *
+   * Only a dead pid is proof. A record that is merely stale belongs to a
+   * process that still exists, and the reader already reports it as stale
+   * without anyone having to remove it.
+   */
+  private sweepDeadRecordsOnce(): void {
+    if (this.hasSweptDeadRecords) {
+      return;
+    }
+    this.hasSweptDeadRecords = true;
+    for (const { path, record } of this.listRecords()) {
+      if (record !== null && this.isProcessAlive(record.pid)) {
+        continue;
+      }
+      safeDeleteFile(
+        this.logger,
+        path,
+        "abandoned permission forwarding serving heartbeat",
+      );
+    }
+  }
+
+  /** Every published record, paired with its path; unusable ones read as `null`. */
+  private listRecords(): {
+    path: string;
+    record: ServingHeartbeat | null;
+  }[] {
+    const directory = servingHeartbeatDir(this.forwardingDir);
+    let names: string[];
+    try {
+      names = readdirSync(directory);
+    } catch {
+      return [];
+    }
+    return names
+      .filter((name) => name.endsWith(".json"))
+      .map((name) => {
+        const path = join(directory, name);
+        return { path, record: this.readRecord(path) };
+      });
+  }
+
+  /**
+   * Read a record, or `null` when it is missing or unusable.
+   *
+   * Silent by design: a forwarding child calls this on every poll tick, so a
+   * warning per unreadable read would flood the review log at four lines a
+   * second. The unusability is already reported once, as the `absent` state on
+   * the abandonment entry.
+   */
+  private readRecord(path: string): ServingHeartbeat | null {
+    try {
+      return asServingHeartbeat(JSON.parse(readFileSync(path, "utf-8")));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Which of the four states a well-formed record is in. */
+  private classify(record: ServingHeartbeat): HeartbeatState {
+    if (!this.isProcessAlive(record.pid)) {
+      return "dead_pid";
+    }
+    return this.now() - record.updatedAt >= SERVING_HEARTBEAT_STALE_MS
+      ? "stale"
+      : "alive";
+  }
+
+  /**
+   * Whether the record on disk is recent enough to leave alone.
+   *
+   * Time alone, with no existence probe: an existence check would cost a
+   * syscall on every poll tick to save at most one refresh window, and a record
+   * removed underneath its owner reappears inside the grace window anyway.
+   */
+  private isThrottled(sessionId: string, at: number): boolean {
+    return (
+      this.published !== null &&
+      this.published.sessionId === sessionId &&
+      at - this.published.at < SERVING_HEARTBEAT_REFRESH_MS
+    );
+  }
+}
+
+// ── Module-private helpers ────────────────────────────────────────────────
+
+/**
+ * Narrow a parsed record, or `undefined`.
+ *
+ * `pid` must be a positive integer specifically: `process.kill(0, 0)` addresses
+ * the caller's own process group and `kill(-n)` a foreign one, so a malformed
+ * record must be rejected before it can reach the liveness probe.
+ */
+function asServingHeartbeat(value: unknown): ServingHeartbeat | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const candidate = value as Partial<ServingHeartbeat>;
+  if (
+    typeof candidate.sessionId !== "string" ||
+    candidate.sessionId.length === 0 ||
+    typeof candidate.pid !== "number" ||
+    !Number.isInteger(candidate.pid) ||
+    candidate.pid <= 0 ||
+    typeof candidate.updatedAt !== "number" ||
+    !Number.isFinite(candidate.updatedAt)
+  ) {
+    return null;
+  }
+  return {
+    sessionId: candidate.sessionId,
+    pid: candidate.pid,
+    updatedAt: candidate.updatedAt,
+  };
+}
+
+/**
+ * Whether `pid` names a running process.
+ *
+ * Signal `0` performs the permission and existence checks without delivering
+ * anything. `EPERM` means the process exists under another user — reported as
+ * alive, the direction that falls back to the timeout rather than abandoning a
+ * request someone may still answer.
+ */
+function isRunningProcess(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isErrnoCode(error, "EPERM");
+  }
+}

package/src/authority/forwarding-manager.ts

@@ -65,6 +65,12 @@ export class ForwardingManager {
       return;
     }
     this.timer = setInterval(() => {
+      // Ahead of the processing guard: a session whose human is deliberating at
+      // a forwarded dialog holds `processInbox` open for as long as they take,
+      // and it is serving throughout. Refreshing behind the guard would let its
+      // announcement decay exactly when it is most demonstrably alive, and
+      // every other forwarding child would give up on it.
+      this.refreshServing();
       if (!this.context || this.processing) {
         return;
       }
@@ -107,6 +113,21 @@ export class ForwardingManager {
     });
   }
 
+  /**
+   * Re-announce the served session, keeping a decayable channel current.
+   *
+   * Separate from {@link announceServing} because that one detects a change to
+   * write its log line, and this one deliberately writes none — four review
+   * entries a second would drown the log the announcement exists to make
+   * readable.
+   */
+  private refreshServing(): void {
+    if (this.servingSessionId === null) {
+      return;
+    }
+    this.deps.serving.markServing(this.servingSessionId);
+  }
+
   /** Withdraw the published session, if any. */
   private withdrawServing(): void {
     const sessionId = this.servingSessionId;

package/src/authority/permission-forwarding.ts

@@ -201,7 +201,15 @@ export function normalizePermissionForwardingSessionId(
   return trimmed;
 }
 
-function encodeSessionIdForPath(sessionId: string): string {
+/**
+ * Make a session id safe to name a path segment.
+ *
+ * Exported because the forwarding tree has two layouts keyed by session id —
+ * `sessions/<id>/` and the serving-heartbeat records beside it — and a second
+ * encoding would be a silent way for the two to disagree about which file
+ * belongs to which session.
+ */
+export function encodeSessionIdForPath(sessionId: string): string {
   return encodeURIComponent(sessionId);
 }
 

package/src/authority/serving-registry.ts

@@ -35,10 +35,43 @@ export const SERVING_SESSION_REGISTRY_KEY = Symbol.for(
  * neither reads the store nor gains a query it has no business making (ISP).
  */
 export interface ServingAnnouncer {
+  /**
+   * Record that `sessionId` is polling its inbox.
+   *
+   * Idempotent, and called on every poll tick rather than once per session: an
+   * announcement that can decay (the filesystem heartbeat) has to be kept
+   * current, and one that cannot (this registry) costs a set insertion to say
+   * so again.
+   */
   markServing(sessionId: string): void;
   clearServing(sessionId: string): void;
 }
 
+/**
+ * Fan an announcement out to every channel a serving session publishes on.
+ *
+ * A session announces to the process-global registry (for its in-process
+ * children) and to the filesystem (for children in other processes). Composing
+ * them keeps `ForwardingManager` holding one collaborator, so adding or
+ * removing a channel never reaches the poll loop.
+ */
+export function composeServingAnnouncers(
+  ...announcers: readonly ServingAnnouncer[]
+): ServingAnnouncer {
+  return {
+    markServing(sessionId: string): void {
+      for (const announcer of announcers) {
+        announcer.markServing(sessionId);
+      }
+    },
+    clearServing(sessionId: string): void {
+      for (const announcer of announcers) {
+        announcer.clearServing(sessionId);
+      }
+    },
+  };
+}
+
 /**
  * Query-side seam: a forwarding child asks whether its target is draining.
  *

package/src/index.ts

@@ -8,11 +8,18 @@ import {
   ForwardedRequestServer,
   type ServingPolicy,
 } from "./authority/forwarded-request-server";
+import {
+  ForwardingLivenessJudge,
+  ServingHeartbeatStore,
+} from "./authority/forwarding-liveness";
 import { ForwardingManager } from "./authority/forwarding-manager";
 import { PERMISSION_FORWARDING_TIMEOUT_MS } from "./authority/permission-forwarding";
 import { requestPermissionDecision } from "./authority/permission-prompt-component";
 import { PermissionPrompter } from "./authority/permission-prompter";
-import { getServingSessionRegistry } from "./authority/serving-registry";
+import {
+  composeServingAnnouncers,
+  getServingSessionRegistry,
+} from "./authority/serving-registry";
 import { SubagentDetection } from "./authority/subagent-detection";
 import { subscribeSubagentLifecycle } from "./authority/subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./authority/subagent-registry";
@@ -111,6 +118,20 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const prompter = new PermissionPrompter({ logger });
 
+  // The filesystem half of the serving announcement. `servingRegistry` reaches
+  // an in-process child through `globalThis`; a child in its own process shares
+  // nothing but this directory, so the served session publishes a heartbeat
+  // there too (#721).
+  const servingHeartbeats = new ServingHeartbeatStore({
+    forwardingDir: paths.forwardingDir,
+    logger,
+  });
+  // The read side of both channels, routed by how the target was resolved.
+  const servingLiveness = new ForwardingLivenessJudge({
+    registry: servingRegistry,
+    heartbeats: servingHeartbeats,
+  });
+
   const authorizerSelection = new AuthorizerSelection({
     detection: subagentDetection,
     events: pi.events,
@@ -121,7 +142,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     requestPermissionDecision,
     forwardingDir: paths.forwardingDir,
     registry: subagentRegistry,
-    servingRegistry,
+    serving: servingLiveness,
     getForwardingTimeoutMs: () =>
       configStore.current().forwardingTimeoutMs ??
       PERMISSION_FORWARDING_TIMEOUT_MS,
@@ -177,7 +198,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     new ForwardingManager({
       detection: subagentDetection,
       forwarder: requestServer,
-      serving: servingRegistry,
+      serving: composeServingAnnouncers(servingRegistry, servingHeartbeats),
       logger,
     }),
     permissionManager,