@gotgenes/pi-permission-system 26.0.0 → 26.2.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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)
+
+
+### Features
+
+* **pi-permission-system:** attribute absent-authority denials ([225412d](https://github.com/gotgenes/pi-packages/commit/225412d485e68e886b6e958b2f53a87f9ff6cf25)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** carry decision provenance across the forwarding boundary ([0dbf13f](https://github.com/gotgenes/pi-packages/commit/0dbf13f86c9f2d070e8b33eb4ffe808331c9185c)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** name the authorizer link that decided an ask ([8556724](https://github.com/gotgenes/pi-packages/commit/8556724e5453ee002b24c48bebaf4d96f6502fe5)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** record the decider on non-prompting resolutions ([5e24abf](https://github.com/gotgenes/pi-packages/commit/5e24abf6311d13928858e730b14a712e155f2bc2)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** record the human decider on prompted decisions ([9f540ba](https://github.com/gotgenes/pi-packages/commit/9f540ba285b546976432733fced08b9fe9dc973c)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+
+
+### Documentation
+
+* **pi-permission-system:** record decision provenance and mark Phase 13 Step 6 complete ([e2739e7](https://github.com/gotgenes/pi-packages/commit/e2739e7f188669ee4878bbe3732958d4e1c54cbd)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+
 ## [26.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.4.0...pi-permission-system-v26.0.0) (2026-08-16)
 
 

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.
@@ -54,8 +68,27 @@ None of them is reported as a user denial, because no user was ever asked.
 The two sides of the exchange are correlatable in the review log: the serving session writes `forwarded_permission.serving_started` with the id it polls, and the child writes `forwarded_permission.request_created` with the `targetSessionId` it forwarded to.
 When a forwarded request goes unanswered, comparing those two entries distinguishes a parent that was not polling from one polling a different session.
 
-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.
+When a forwarded request *is* answered, the child's own terminal entry names both which session answered and what within it decided.
+The serving node records its decider on the response — a rule of its own (with the surface, pattern, and origin that matched), the link that ruled, or the human who answered its dialog — and the child records it nested under a `forwarded` frame:
+
+```json
+{
+  "kind": "forwarded",
+  "responderSessionId": "019ff969-c34c-70be-9034-fae19c852932",
+  "decision": { "kind": "user", "via": "dialog" }
+}
+```
+
+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.
+
+### 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.0.0",
+  "version": "26.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/authority/approval-escalator.ts

@@ -19,10 +19,12 @@ 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,
   type ForwardedPermissionRequest,
+  type ForwardedPermissionResponse,
   type ForwardedPromptDisplay,
   type ForwardedSessionApproval,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
@@ -32,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";
@@ -96,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;
@@ -110,6 +111,9 @@ export interface ParentAuthorizerDeps {
  * `confirmationUnavailable` is what keeps this out of the "User denied …"
  * message (#719): a user who was never asked denied nothing. `denialReason`
  * names which path gave up, and the gate renders it to the model.
+ *
+ * The provenance record reuses that same string rather than restating it, so
+ * what the model is told and what the log attributes cannot drift (#726).
  */
 function abandon(denialReason: string): PermissionPromptDecision {
   return {
@@ -117,6 +121,31 @@ function abandon(denialReason: string): PermissionPromptDecision {
     state: "denied",
     confirmationUnavailable: true,
     denialReason,
+    decidedBy: { kind: "unavailable", reason: denialReason },
+  };
+}
+
+/**
+ * Adopt the responder's answer, recording the hop it came through.
+ *
+ * The requester's own terminal entry has to answer two questions, and they are
+ * different: *which session* answered, and *what within it* decided. Nesting
+ * keeps both rather than flattening the responder's source into this node's
+ * record, where it would read as a local decision (#726).
+ *
+ * A responder that sent no usable source yields `decision: null` — the hop is
+ * still a fact, and an older parent is not an error.
+ */
+function relayDecision(
+  response: ForwardedPermissionResponse,
+): PermissionPromptDecision {
+  return {
+    ...response,
+    decidedBy: {
+      kind: "forwarded",
+      responderSessionId: response.responderSessionId,
+      decision: response.decidedBy ?? null,
+    },
   };
 }
 
@@ -152,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;
 
@@ -335,6 +364,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
           this.logger,
           responsePath,
         );
+        const relayed = response ? relayDecision(response) : null;
         this.logger.review("forwarded_permission.response_received", {
           requestId,
           approved: response?.approved ?? null,
@@ -343,10 +373,11 @@ export class ParentAuthorizer implements TerminalAuthorizer {
           responderSessionId: response?.responderSessionId ?? null,
           targetSessionId,
           responsePath,
+          decidedBy: relayed?.decidedBy,
         });
         this.discardRequest(location, requestPath, responsePath);
         return (
-          response ??
+          relayed ??
           abandon("The parent session's permission response could not be read")
         );
       }
@@ -356,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(
@@ -390,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-chain.ts

@@ -1,10 +1,14 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { AuthorizerLog, PermissionQuery } from "#src/service";
 import type {
-  Authorizer,
   AuthorizerVerdict,
+  NamedAuthorizer,
   TerminalAuthorizer,
 } from "./authorizer";
-import { createDeniedPermissionDecision } from "./permission-dialog";
+import {
+  createDeniedPermissionDecision,
+  type PermissionPromptDecision,
+} from "./permission-dialog";
 
 /**
  * Compose the live-authority chain (ADR 0007): try each non-terminal `link`
@@ -12,9 +16,9 @@ import { createDeniedPermissionDecision } from "./permission-dialog";
  * context-selected `terminal` that always decides.
  *
  * The signature is the type-level terminal-cannot-defer invariant: `links` are
- * deferring {@link Authorizer}s while `terminal` is a {@link TerminalAuthorizer}
- * (returns a full decision), so a deferring link cannot occupy the terminal
- * slot.
+ * deferring {@link NamedAuthorizer}s while `terminal` is a
+ * {@link TerminalAuthorizer} (returns a full decision), so a deferring link
+ * cannot occupy the terminal slot.
  *
  * Each link is handed the session-scoped `query` and the review-log `log` at
  * `authorize` time (ADR 0007 §3) so it queries the deterministic engine at gate
@@ -24,7 +28,7 @@ import { createDeniedPermissionDecision } from "./permission-dialog";
  * ships until a link registers.
  */
 export function composeAuthorizerChain(
-  links: readonly Authorizer[],
+  links: readonly NamedAuthorizer[],
   terminal: TerminalAuthorizer,
   query: PermissionQuery,
   log: AuthorizerLog,
@@ -36,7 +40,7 @@ export function composeAuthorizerChain(
     async authorize(details) {
       for (const link of links) {
         const verdict = await link.authorize(details, query, log);
-        const decision = decideFromVerdict(verdict);
+        const decision = decideFromVerdict(link.name, verdict);
         if (decision) {
           return decision;
         }
@@ -47,16 +51,40 @@ export function composeAuthorizerChain(
   };
 }
 
-/** Map a link's decisive verdict to a decision; `defer` yields `null`. */
-function decideFromVerdict(verdict: AuthorizerVerdict) {
+/**
+ * Map a link's decisive verdict to a decision; `defer` yields `null`.
+ *
+ * The deciding link is named on the decision, not merely counted among the
+ * consulted set the selection already records: a link ahead of it that
+ * deferred decided nothing and must not be credited (#726).
+ */
+function decideFromVerdict(
+  name: string,
+  verdict: AuthorizerVerdict,
+): PermissionPromptDecision | null {
   switch (verdict.kind) {
     case "allow":
       // A link grant is non-persistent (state `approved`, never
       // `approved_for_session`), per ADR 0007's off-by-default envelope.
-      return { approved: true, state: "approved" } as const;
+      return {
+        approved: true,
+        state: "approved",
+        decidedBy: decidedByLink(name, "allow", null),
+      };
     case "deny":
-      return createDeniedPermissionDecision(verdict.reason);
+      return {
+        ...createDeniedPermissionDecision(verdict.reason),
+        decidedBy: decidedByLink(name, "deny", verdict.reason ?? null),
+      };
     case "defer":
       return null;
   }
 }
+
+function decidedByLink(
+  name: string,
+  verdict: "allow" | "deny",
+  reason: string | null,
+): DecisionSource {
+  return { kind: "authorizer", name, verdict, reason };
+}

package/src/authority/authorizer-selection.ts

@@ -2,8 +2,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { PermissionQuery } from "#src/service";
 import {
-  type Authorizer,
   type AuthorizerSelectionDeps,
+  type NamedAuthorizer,
   type SelectedAuthority,
   selectAuthorizer,
 } from "./authorizer";
@@ -93,7 +93,7 @@ export class AuthorizerSelection
   private linksFor(
     authority: SelectedAuthority,
     requestId: string,
-  ): Authorizer[] {
+  ): NamedAuthorizer[] {
     const configured = this.deps.getAuthorizerChain();
     if (configured.length === 0) {
       return [];
@@ -123,8 +123,8 @@ export class AuthorizerSelection
   private resolveConfiguredLinks(
     configured: readonly string[],
     requestId: string,
-  ): Authorizer[] {
-    const links: Authorizer[] = [];
+  ): NamedAuthorizer[] {
+    const links: NamedAuthorizer[] = [];
     const resolved: string[] = [];
     for (const name of configured) {
       const authorize = this.deps.authorizerRegistry.get(name);
@@ -136,7 +136,7 @@ export class AuthorizerSelection
         continue;
       }
       resolved.push(name);
-      links.push({ authorize: encloseInDelegationEnvelope(authorize) });
+      links.push({ name, authorize: encloseInDelegationEnvelope(authorize) });
     }
     if (resolved.length > 0) {
       this.deps.logger.review("authorizer_chain_resolved", {

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";
@@ -42,6 +42,19 @@ export interface Authorizer {
   ): Promise<AuthorizerVerdict>;
 }
 
+/**
+ * A resolved chain link together with the operator-configured name it came
+ * from.
+ *
+ * `AuthorizerRegistry` already keys links by name, and `AuthorizerSelection`
+ * has the name in scope when it resolves the operator's `authorizerChain`; the
+ * name is carried through composition so a decision record can say *which*
+ * link decided rather than only which links were consulted.
+ */
+export interface NamedAuthorizer extends Authorizer {
+  readonly name: string;
+}
+
 /**
  * The terminal link: on `ask`, rules on a single request and is told the
  * decision. Structurally cannot defer — it always returns a full
@@ -95,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;
@@ -132,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,
       }),