@gotgenes/pi-permission-system 32.0.4 → 32.0.5

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.5](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.4...pi-permission-system-v32.0.5) (2026-09-16)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** tell the operator when a configured chain link is missing ([3662541](https://github.com/gotgenes/pi-packages/commit/3662541d4ebc555d54faf2934085d22b36ee618e)), closes [#861](https://github.com/gotgenes/pi-packages/issues/861)
+
+### Documentation
+
+* **pi-permission-system:** record the unregistered-link warning ([f70b1e3](https://github.com/gotgenes/pi-packages/commit/f70b1e3ce52a38744da2a07880878efb61dfae00)), closes [#861](https://github.com/gotgenes/pi-packages/issues/861)
+* **pi-permission-system:** state the resolved skip in the boundary test comment ([9cd18f1](https://github.com/gotgenes/pi-packages/commit/9cd18f1ef6bd8f9dbabf6fc6ce6b9dfa58d64764)), closes [#861](https://github.com/gotgenes/pi-packages/issues/861)
+
 ## [32.0.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.3...pi-permission-system-v32.0.4) (2026-09-16)
 
 

package/docs/configuration.md

@@ -226,9 +226,11 @@ Three invariants govern the chain:
 
 1. **Config order wins, never registration order.**
    The order in `authorizerChain` — not the order extensions happen to register in — fixes the security-relevant chain order.
-2. **A missing link is skipped fail-safe.**
-   A name with no registered link is skipped with a logged warning; the `ask` still reaches the terminal.
+2. **A missing link is skipped fail-safe, and you are told.**
+   A name with no registered link is skipped; the `ask` still reaches the terminal.
    Absence of a judge means *more* prompting, never less.
+   Because you asked for that judge and did not get it, the skip also raises a warning naming the link — once per session per name, beside the per-ask review record.
+   Three things leave the identical absence, so the warning names the likeliest and admits the others: the extension providing the link is not loaded in this session (a subagent child's `excludedExtensionPackages` does this), it failed to load, or it declined to register because it has no configuration of its own.
 3. **Registration alone grants no authority.**
    Installing a judge extension gives it nothing; a link decides nothing until you name it here (opt-in activation).
 
@@ -244,12 +246,12 @@ The subagent itself resolves no links (an extension cannot register one in a chi
 
 Three review-log records make the chain observable, all keyed by the ask's `requestId`:
 
-| Record                               | Meaning                                                                                                  |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `authorizer_chain_resolved`          | the links consulted on this ask, recorded before they run — a link that defers otherwise leaves no trace |
-| `authorizer_chain_delegated`         | the ask came from a relaying subagent node; the named links were deliberately not run here               |
-| `authorizer_chain_unregistered_link` | a configured name had no registered link — a real misconfiguration; the ask still reaches the terminal   |
-| `authorizer_link_vacant`             | a link was registered on a relaying node, which runs no chain — accepted and recorded, never consulted   |
+| Record                               | Meaning                                                                                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `authorizer_chain_resolved`          | the links consulted on this ask, recorded before they run — a link that defers otherwise leaves no trace                                               |
+| `authorizer_chain_delegated`         | the ask came from a relaying subagent node; the named links were deliberately not run here                                                             |
+| `authorizer_chain_unregistered_link` | a configured name had no registered link — a real misconfiguration; the ask still reaches the terminal, and the first skip of that name also warns you |
+| `authorizer_link_vacant`             | a link was registered on a relaying node, which runs no chain — accepted and recorded, never consulted                                                 |
 
 Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService(sessionId).registerAuthorizer(name, authorize)`, taking `sessionId` from that event's payload; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
 Registration returns a disposer, and only one link may hold a given name.

package/package.json

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

package/src/authority/authorizer-chain-audit.ts

@@ -0,0 +1,99 @@
+/**
+ * authorizer-chain-audit.ts — Report a configured `authorizerChain` link this
+ * node's registry could not resolve.
+ *
+ * Registrations are node-local (ADR 0012 decision 1), and a link produces a
+ * *verdict* rather than a fact, so live authority stays converged at the
+ * adjudicating node and a link is never inherited from an ancestor. A node that
+ * adjudicates locally therefore runs whatever links loaded in it, and skips the
+ * rest fail-safe (ADR 0007 §4 invariant 2) — the ask still reaches the
+ * terminal. That resolution is deliberate; its silence was not. The operator
+ * named a judge in config, did not get it, and the only trace was a line in a
+ * JSONL file.
+ *
+ * The two halves of the alarm fire at different rates on purpose, for two
+ * different readers. The review entry is the auditor's durable record and must
+ * be complete, so it is written for every skipped ask. The visible warning is
+ * for the operator about to answer the prompt the link should have answered, so
+ * it is latched: one per configured name, whose count is bounded by
+ * `authorizerChain.length`.
+ *
+ * A relaying node cannot reach this audit at all. `AuthorizerSelection` returns
+ * from `linksFor` before resolving anything, recording
+ * `authorizer_chain_delegated` instead — its ask is adjudicated one hop up
+ * (ADR 0007 §7), where an absent link is the design rather than a
+ * misconfiguration.
+ */
+
+/** The narrow log seam this audit needs (ISP): a durable record and a warning. */
+export interface AuthorizerChainAuditLog {
+  review(event: string, details?: Record<string, unknown>): void;
+  warn(message: string): void;
+}
+
+/** A configured chain link this node's registry could not resolve. */
+export interface UnregisteredLink {
+  /** The operator-configured name, exactly as written in `authorizerChain`. */
+  name: string;
+  /** The ask whose chain resolution skipped it. */
+  requestId: string;
+}
+
+/** The audit seam `AuthorizerSelection` drives when it skips a name (ISP). */
+export interface UnregisteredLinkAuditor {
+  auditUnregisteredLink(link: UnregisteredLink): void;
+}
+
+/**
+ * The agent-facing text for a configured link that is not registered here.
+ *
+ * Three causes leave the identical absence — the provider was excluded from
+ * this session's extensions, it failed to load, or it declined to register
+ * because it has no configuration of its own (the shape
+ * `@gotgenes/pi-permission-model-judge` uses to let an operator opt out
+ * per project). The message names the likeliest and admits the others, rather
+ * than accusing the operator of a contradiction it cannot prove.
+ *
+ * Every clause is a statement of what already happened. It deliberately does
+ * not claim later asks will skip the link too: registration is honored any time
+ * before an ask (ADR 0007 §4), so a link may yet arrive.
+ */
+export function unregisteredLinkMessage(name: string): string {
+  return (
+    `pi-permission-system: authorizerChain names "${name}", but no link with ` +
+    "that name is registered in this session, so this ask is being decided " +
+    "without it. Most often the extension providing the link is not loaded " +
+    "here (a subagent child's excludedExtensionPackages does this); it may " +
+    "also have failed to load, or declined to register because it has no " +
+    "configuration of its own. Every skipped ask is recorded in the " +
+    "permission review log as authorizer_chain_unregistered_link."
+  );
+}
+
+/**
+ * Records each skipped chain link, and warns the operator once per name.
+ *
+ * The latch is a plain field with no re-arm hook, because the extension factory
+ * is re-invoked per session generation — a `/new`, `/resume`, `/fork`, or
+ * `/import` switch builds a fresh audit. A `session_start` with
+ * `reason: "reload"` reuses this instance and deliberately does not re-warn for
+ * a name already reported; a name newly added to `authorizerChain` by that same
+ * reload has no entry yet, so it warns on its first skip.
+ */
+export class AuthorizerChainAudit implements UnregisteredLinkAuditor {
+  private readonly warned = new Set<string>();
+
+  constructor(private readonly log: AuthorizerChainAuditLog) {}
+
+  auditUnregisteredLink(link: UnregisteredLink): void {
+    this.log.review("authorizer_chain_unregistered_link", {
+      requestId: link.requestId,
+      name: link.name,
+    });
+    if (this.warned.has(link.name)) {
+      return;
+    }
+    this.warned.add(link.name);
+    this.log.warn(unregisteredLinkMessage(link.name));
+  }
+}

package/src/authority/authorizer-selection.ts

@@ -7,6 +7,7 @@ import {
   selectAuthorizer,
 } from "./authorizer";
 import { composeAuthorizerChain } from "./authorizer-chain";
+import type { UnregisteredLinkAuditor } from "./authorizer-chain-audit";
 import type { AuthorizerLookup } from "./authorizer-registry";
 import { encloseInDelegationEnvelope } from "./delegation-envelope";
 import type { PermissionPromptDecision } from "./permission-dialog";
@@ -61,6 +62,28 @@ export interface AdjudicationRole {
   adjudicatesLocally(): boolean;
 }
 
+/**
+ * Everything {@link AuthorizerSelection} is constructed with: the
+ * {@link AuthorizerSelectionDeps} `selectAuthorizer` itself needs, plus the
+ * collaborators only the class uses to resolve and run the chain.
+ *
+ * Named rather than left anonymous on the constructor because the test
+ * fixtures mirror it: an addition here is otherwise an addition in two places.
+ * `selectAuthorizer` keeps the narrower parameter type (ISP) — it resolves no
+ * links and must not see the chain collaborators.
+ */
+export type AuthorizerSelectionConstructorDeps = AuthorizerSelectionDeps & {
+  prompter: PermissionPrompterApi;
+  /** The session-scoped query injected into each chain link (ADR 0007 §3). */
+  getPermissionQuery: () => PermissionQuery;
+  /** Read-only lookup of registered links by name. */
+  authorizerRegistry: AuthorizerLookup;
+  /** The operator's configured link names, read live per ask. */
+  getAuthorizerChain: () => string[];
+  /** Told about each configured name the registry could not resolve. */
+  chainAudit: UnregisteredLinkAuditor;
+};
+
 /**
  * Context-owning selection root for the Authorizer spine.
  *
@@ -79,17 +102,7 @@ export class AuthorizerSelection
   private authority: SelectedAuthority | null = null;
   private relayTarget: PermissionForwardingTarget | null = null;
 
-  constructor(
-    private readonly deps: AuthorizerSelectionDeps & {
-      prompter: PermissionPrompterApi;
-      /** The session-scoped query injected into each chain link (ADR 0007 §3). */
-      getPermissionQuery: () => PermissionQuery;
-      /** Read-only lookup of registered links by name. */
-      authorizerRegistry: AuthorizerLookup;
-      /** The operator's configured link names, read live per ask. */
-      getAuthorizerChain: () => string[];
-    },
-  ) {}
+  constructor(private readonly deps: AuthorizerSelectionConstructorDeps) {}
 
   /**
    * Select the live authority for `ctx` and store it. The non-terminal
@@ -165,10 +178,11 @@ export class AuthorizerSelection
 
   /**
    * Resolve the operator's `authorizerChain` names to registered links, in
-   * config order (ADR 0007 invariant 1). An unregistered name is skipped with a
-   * warning (invariant 2 — more prompting, never less); each resolved link is
-   * wrapped in the bounded-delegation envelope so an `allow` on an excluded
-   * surface cannot exceed the operator's policy.
+   * config order (ADR 0007 invariant 1). An unregistered name is skipped
+   * fail-safe (invariant 2 — more prompting, never less) and handed to the
+   * chain audit, which records it and tells the operator once per name; each
+   * resolved link is wrapped in the bounded-delegation envelope so an `allow`
+   * on an excluded surface cannot exceed the operator's policy.
    *
    * The resolved names are recorded against the ask before any link runs — a
    * link that defers decides nothing and would otherwise leave no evidence it
@@ -184,10 +198,7 @@ export class AuthorizerSelection
     for (const name of configured) {
       const authorize = this.deps.authorizerRegistry.get(name);
       if (authorize === undefined) {
-        this.deps.logger.review("authorizer_chain_unregistered_link", {
-          requestId,
-          name,
-        });
+        this.deps.chainAudit.auditUnregisteredLink({ requestId, name });
         continue;
       }
       resolved.push(name);

package/src/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
 import { warmBashParser } from "#src/access-intent/bash/parser";
 import { buildResolvedIntentFromMatchValues } from "#src/access-intent/input-normalizer";
+import { AuthorizerChainAudit } from "#src/authority/authorizer-chain-audit";
 import {
   AuthorizerRegistry,
   ObservedAuthorizerRegistrar,
@@ -168,6 +169,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     // resolved in config order at activation.
     authorizerRegistry,
     getAuthorizerChain: () => configStore.current().authorizerChain ?? [],
+    // Records each configured name this node could not resolve, and tells the
+    // operator once per name — the ask is decided without the judge they
+    // asked for, and the review log alone never said so (#861).
+    chainAudit: new AuthorizerChainAudit(logger),
   });
 
   // Resolver composes the manager + session ruleset and owns the