@gotgenes/pi-permission-system 28.0.1 → 29.1.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [29.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.0.0...pi-permission-system-v29.1.0) (2026-08-31)
+
+
+### Features
+
+* **pi-permission-system:** warn when a subagent child runs with no permission node ([223710f](https://github.com/gotgenes/pi-packages/commit/223710ff2ed81977161ba2a367deb81fe6c7f207)), closes [#792](https://github.com/gotgenes/pi-packages/issues/792)
+
+
+### Documentation
+
+* **pi-permission-system:** document the optional bound channel and the unguarded-child alarm ([9a16e1b](https://github.com/gotgenes/pi-packages/commit/9a16e1b09934ecdb529875b59f7649c50ccfd5b9)), closes [#792](https://github.com/gotgenes/pi-packages/issues/792)
+
+## [29.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v28.0.1...pi-permission-system-v29.0.0) (2026-08-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** `getRootPermissionsService()`, `publishRootPermissionsService()`, and `unpublishRootPermissionsService()` are removed. Resolve a node's service with `getPermissionsService(sessionId)`, taking `sessionId` from the `permissions:ready` payload (or from `ctx.sessionManager.getSessionId()` inside your own session handler). See docs/migration/0796-remove-process-root-slot.md.
+
+### Features
+
+* **pi-permission-system:** remove the deprecated process-root service accessor ([65cbbee](https://github.com/gotgenes/pi-packages/commit/65cbbee5b4d98a8f34e34b831ad4a33250735f7e)), closes [#796](https://github.com/gotgenes/pi-packages/issues/796)
+
+
+### Documentation
+
+* **pi-permission-system:** retire the process-root service slot from the docs ([649b1f0](https://github.com/gotgenes/pi-packages/commit/649b1f063a840e9a7c1f259ed03620a71624e55f)), closes [#796](https://github.com/gotgenes/pi-packages/issues/796)
+
 ## [28.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v28.0.0...pi-permission-system-v28.0.1) (2026-08-30)
 
 

package/README.md

@@ -209,6 +209,7 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
 | [docs/migration/0745-prompt-payload-contracts.md](docs/migration/0745-prompt-payload-contracts.md)                             | Prompt payload contracts (breaking) — the forwarded wire, the `ui_prompt` broadcast, and the deprecated preview caps |
 | [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound           |
 | [docs/migration/0794-keyed-service-locator.md](docs/migration/0794-keyed-service-locator.md)                                   | Keyed service locator (breaking) — `getPermissionsService(sessionId)`, and the repeating ready event                 |
+| [docs/migration/0796-remove-process-root-slot.md](docs/migration/0796-remove-process-root-slot.md)                             | Process-root slot removed (breaking) — `getRootPermissionsService()` and its publish/unpublish pair are gone         |
 
 ## Development
 

package/dist/public.d.ts

@@ -465,15 +465,12 @@ type ToolInputFormatter = (input: Record<string, unknown>) => string | undefined
  * accessors here read from the same `globalThis` slots the provider wrote to —
  * enabling direct, synchronous, type-safe function calls.
  *
- * There are two slots, because one process can host several **nodes** (one Pi
- * session runtime each — a root session and its in-process subagent children
- * all load their own instance of this extension):
- *
- * - A session-keyed map, written by every node under its own session id.
- *   `getPermissionsService(sessionId)` resolves the service whose
- *   registries that node's own gates and chain read (ADR 0012 decision 2).
- * - A single legacy slot holding the process root's service, read by the
- *   deprecated `getRootPermissionsService()`.
+ * The slot is a session-keyed map, because one process can host several
+ * **nodes** (one Pi session runtime each — a root session and its in-process
+ * subagent children all load their own instance of this extension). Every node
+ * writes under its own session id, and `getPermissionsService(sessionId)`
+ * resolves the service whose registries that node's own gates and chain read
+ * (ADR 0012 decision 2).
  *
  * Best practice: resolve per use rather than caching the reference — this
  * ensures resilience across `/reload` and load-order edge cases.
@@ -529,8 +526,7 @@ interface PermissionQuery {
 }
 /**
  * Public interface exposed to other extensions via
- * {@link getPermissionsService} (or the deprecated
- * {@link getRootPermissionsService}).
+ * {@link getPermissionsService}.
  *
  * Each instance belongs to one node, and its three registration surfaces are
  * read by that node alone: extractors and formatters by its own gates, chain
@@ -600,26 +596,6 @@ interface PermissionsService extends PermissionQuery {
      */
     registerAuthorizer(name: string, authorize: Authorizer["authorize"]): () => void;
 }
-/**
- * Store a `PermissionsService` in the legacy process-root slot, read by
- * `getRootPermissionsService()`.
- *
- * Called at `session_start` by the top-level (parent) instance only — an
- * in-process subagent child skips publishing so it cannot clobber the parent's
- * service. Overwrites any previously published service, which keeps `/reload`
- * working: a reloaded parent re-publishes its fresh service.
- */
-declare function publishRootPermissionsService(service: PermissionsService): void;
-/**
- * Retrieve the process root's published `PermissionsService`, or `undefined`
- * if the permission-system extension has not loaded (or has been unloaded).
- *
- * @deprecated Use {@link getPermissionsService} with the `sessionId`
- * from the `permissions:ready` payload. This accessor answers "the process
- * root's service", which is the wrong question in every node but the root.
- * Removal is deferred to a future major (ADR 0012 decision 7).
- */
-declare function getRootPermissionsService(): PermissionsService | undefined;
 /**
  * Publish `service` as the service of the node whose session is `sessionId`
  * (ADR 0012 decision 2 — node-locality).
@@ -647,27 +623,14 @@ declare function publishPermissionsService(sessionId: string, service: Permissio
 declare function getPermissionsService(sessionId: string): PermissionsService | undefined;
 /**
  * Remove the `sessionId` entry, but only when it still holds `service`
- * (identity compare-and-delete, like {@link unpublishRootPermissionsService}).
+ * (identity compare-and-delete).
  *
- * Scoping the delete to the publishing instance keeps a superseded `/reload`
- * generation's late shutdown from wiping the new generation's freshly
+ * Called during `session_shutdown` to avoid stale references after the node is
+ * torn down. Scoping the delete to the publishing instance keeps a superseded
+ * `/reload` generation's late shutdown from wiping the new generation's freshly
  * published service.
  */
 declare function unpublishPermissionsService(sessionId: string, service: PermissionsService): void;
-/**
- * Remove `service` from `globalThis`, but only when the current slot still
- * holds it (identity compare-and-delete).
- *
- * Called during `session_shutdown` to avoid stale references after the
- * extension is torn down. Scoping the delete to the publishing instance keeps
- * two cases correct:
- *
- * - An in-process subagent child never published the parent's service, so its
- *   shutdown is a no-op and the parent's slot survives.
- * - A superseded `/reload` generation no longer owns the slot, so its late
- *   shutdown cannot wipe the new generation's freshly published service.
- */
-declare function unpublishRootPermissionsService(service: PermissionsService): void;
 
-export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, getRootPermissionsService, publishPermissionsService, publishRootPermissionsService, unpublishPermissionsService, unpublishRootPermissionsService };
+export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
 export type { Authorizer, AuthorizerLog, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptAnnotation, PromptEvidence, PromptPayload, PromptPayloadKind, PromptPermissionDetails, PromptRequestFacts, PromptRequester, ToolInputFormatter };

package/docs/cross-extension-api.md

@@ -49,11 +49,9 @@ Each node therefore publishes its own service at `session_start`, into a `global
 Consumers call `getPermissionsService(sessionId)` to retrieve it — even though their `import()` loads a fresh module copy, the accessor reads from the shared `globalThis` slot.
 The session id arrives as a field on the `permissions:ready` broadcast, which each node emits at its own `session_start`, right after publishing — and again at that node's first `before_agent_start`, so a consumer whose own `session_start` ran later still hears it.
 
-`getRootPermissionsService()` remains, reading a separate legacy slot that holds the **process root's** service, but it is deprecated: in any node but the root it answers the wrong question, handing an in-process child the parent's service.
-Calling it emits a once-guarded Node `DeprecationWarning` (code `PI_PERMISSION_SYSTEM_DEP0001`); run with `--trace-deprecation` to locate your call site, or `--no-deprecation` to silence it.
-Removal is deferred to a future major release.
-
-Both accessors were renamed in the major that reclaimed `getPermissionsService` for the keyed locator; if you are upgrading from a release whose `getPermissionsService()` took no argument, see [migration/0794-keyed-service-locator.md](migration/0794-keyed-service-locator.md).
+That keyed map is the only service slot.
+A separate legacy slot once held the process root's service, read by a deprecated `getRootPermissionsService()`; both were removed, because in any node but the root that accessor answered the wrong question — handing an in-process child the parent's service.
+If you are upgrading from a release that had it, see [migration/0796-remove-process-root-slot.md](migration/0796-remove-process-root-slot.md); if you are upgrading from one whose `getPermissionsService()` took no argument, start with [migration/0794-keyed-service-locator.md](migration/0794-keyed-service-locator.md).
 
 All types below are directly importable and type-check with `tsc` out of the box.
 `@gotgenes/pi-permission-system`'s published `exports` resolve `import type { … }` to a self-contained, bundled declaration file with no internal module references, so a downstream `tsconfig.json` needs no special path configuration.
@@ -301,7 +299,7 @@ Best practice: resolve the service per use rather than caching the reference.
 The `import()` throws if the package is not installed.
 Wrap both in `try/catch` + `if` guard as shown in the Quick Start example.
 
-It also returns `undefined` when called with no session id at all — a shape TypeScript rejects but JavaScript reaches — rather than falling back to the process root's service, since answering with another node's service is the defect the keyed locator exists to prevent.
+It also returns `undefined` when called with no session id at all — a shape TypeScript rejects but JavaScript reaches — rather than guessing a node, since answering with another node's service is the defect the keyed locator exists to prevent.
 That call emits a once-guarded Node warning (code `PI_PERMISSION_SYSTEM_WARN0001`), because the guard above turns the missing service into a registration that silently never happens.
 It is deliberately not a `DeprecationWarning`: `--no-deprecation` does not silence it.
 

package/docs/guides/permission-frontmatter-for-subagent-extensions.md

@@ -149,7 +149,7 @@ try {
 
 Query the service belonging to the session whose policy you mean.
 Each session that loads the permission system publishes its own — a subagent child's config (and cwd) may differ from its parent's, so the parent's service is not a stand-in for the child's.
-The deprecated `getRootPermissionsService()` always answers with the process root's service, which is why it is the wrong call inside a child.
+That is why the session id is required: an accessor answering "the process root's service" would hand a child the parent's, and the one that did was removed.
 
 If `pi-permission-system` is not installed, `import()` throws; if that session has published no service yet (or has been unloaded), `getPermissionsService(sessionId)` returns `undefined`.
 Guard both cases as shown above.

package/docs/migration/0794-keyed-service-locator.md

@@ -22,7 +22,7 @@ Each node now publishes its own service under its own session id, and you resolv
 | Before                                 | After                                                              |
 | -------------------------------------- | ------------------------------------------------------------------ |
 | `getPermissionsService()`              | `getPermissionsService(sessionId)`                                 |
-| — (no equivalent)                      | `getRootPermissionsService()` — the old behavior, still deprecated |
+| — (no equivalent)                      | `getRootPermissionsService()` — the old behavior, deprecated       |
 | `publishPermissionsService(service)`   | `publishRootPermissionsService(service)`                           |
 | `unpublishPermissionsService(service)` | `unpublishRootPermissionsService(service)`                         |
 
@@ -89,3 +89,8 @@ Guard it with a stored dispose handle, as shown above, and release the handle on
 - The `permissions:ready`, `permissions:ui_prompt`, and `permissions:decision` payload shapes.
 - The process-root slot itself: a node that is not an in-process subagent child still publishes to it, so `getRootPermissionsService()` answers exactly as the old zero-arg accessor did.
   It remains deprecated (`PI_PERMISSION_SYSTEM_DEP0001`), and its removal is deferred to a later major.
+
+> [!NOTE]
+> That last bullet held only for this release.
+> The process-root slot, its accessor, and its publish/unpublish pair were removed in a later major — see [0796-remove-process-root-slot.md](0796-remove-process-root-slot.md).
+> If you are migrating from a pre-27.0.0 release, work through this guide first and that one second.

package/docs/migration/0796-remove-process-root-slot.md

@@ -0,0 +1,68 @@
+# Migration guide: the process-root service slot is removed
+
+Starting with the release that closes #796, the deprecated process-root service accessor and the `globalThis` slot behind it no longer exist.
+
+This is a **breaking change**.
+If your extension does not import `getRootPermissionsService`, `publishRootPermissionsService`, or `unpublishRootPermissionsService` from `@gotgenes/pi-permission-system`, nothing here affects you.
+
+## What was removed
+
+| Removed                                            | Replacement                                      |
+| -------------------------------------------------- | ------------------------------------------------ |
+| `getRootPermissionsService()`                      | `getPermissionsService(sessionId)`               |
+| `publishRootPermissionsService(service)`           | — (internal; a node publishes its own service)   |
+| `unpublishRootPermissionsService(service)`         | — (internal; a node unpublishes its own service) |
+| `PI_PERMISSION_SYSTEM_DEP0001` deprecation warning | — (the deprecated path is gone)                  |
+
+The `Symbol.for("@gotgenes/pi-permission-system:service")` slot is no longer written by any node.
+`Symbol.for("@gotgenes/pi-permission-system:session-services")` — the session-keyed map — is the only service slot.
+
+## What to change
+
+Resolve the service of the node whose behavior you mean to affect, keyed by its session id.
+The id arrives as a field on the `permissions:ready` payload; inside your own session handler, `ctx.sessionManager.getSessionId()` is the same value.
+
+```typescript
+import {
+  getPermissionsService,
+  PERMISSIONS_READY_CHANNEL,
+  type PermissionsReadyEvent,
+} from "@gotgenes/pi-permission-system";
+
+let dispose: (() => void) | undefined;
+
+pi.events.on(PERMISSIONS_READY_CHANNEL, (event) => {
+  const { sessionId } = event as PermissionsReadyEvent;
+  // Idempotent: ready may repeat, so a second emission must be a no-op.
+  if (dispose || !sessionId) return;
+  dispose = getPermissionsService(sessionId)?.registerAuthorizer(
+    "my-link",
+    authorize,
+  );
+});
+```
+
+If you are still on a zero-argument `getPermissionsService()` from a release before 27.0.0, migrate through [0794-keyed-service-locator.md](0794-keyed-service-locator.md) first — that release is where the accessor's signature changed.
+
+## Why the deprecation window closed
+
+[ADR 0012](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md) decision 7 deferred the removal until downstream consumers had migrated.
+`pi-permission-model-judge` 2.0.0 — the named migration case — registers through the keyed locator and floors its peer range at `>=27.0.0`, and no other known consumer reads the root slot.
+
+The removal is also narrower than a deprecation window's usual population suggests.
+`getRootPermissionsService` did not exist before 27.0.0: it is the name that release gave the old behavior when it reclaimed `getPermissionsService` for the keyed locator.
+So no consumer predating the deprecation can be calling it — every caller adopted the name after it was already marked deprecated, in preference to the keyed locator this guide's predecessor recommends.
+
+## What you will see if you miss a call site
+
+The export is gone, so TypeScript reports `TS2724` at your import and plain JavaScript throws `TypeError: getRootPermissionsService is not a function`.
+
+Calling `getPermissionsService()` with **no** argument still answers `undefined` and emits a once-guarded Node warning under code `PI_PERMISSION_SYSTEM_WARN0001`, naming the keyed call and the ready payload.
+That warning is deliberately not a `DeprecationWarning`, so `--no-deprecation` does not silence it: a registration that never landed is not something to hide.
+
+## What has not changed
+
+- The `PermissionsService` interface — the five methods and their signatures are untouched.
+- The keyed accessors `getPermissionsService` / `publishPermissionsService` / `unpublishPermissionsService`.
+- The `permissions:ready`, `permissions:ui_prompt`, and `permissions:decision` payload shapes and cadence.
+- Node-locality: a registration is still read only by the node it was made in, and an in-process subagent child still gets its own service.

package/docs/subagent-integration.md

@@ -16,13 +16,32 @@ An implementation that creates child sessions inside its own process (via `creat
 | `subagents:child:session-created` | `{ sessionId, parentSessionId? }` | After the child session is created, immediately before `bindExtensions()` |
 | `subagents:child:disposed`        | `{ sessionId }`                   | In the run's `finally`, on success and on error alike                     |
 
+A third channel is **optional**, and buys one diagnostic:
+
+| Channel                  | Payload                           | When                                                                |
+| ------------------------ | --------------------------------- | ------------------------------------------------------------------- |
+| `subagents:child:bound`  | `{ sessionId, parentSessionId? }` | After `bindExtensions()` resolves, and not at all when it throws    |
+
 The pre-bind ordering of `session-created` is **contract, not an implementation detail**.
 Emit it synchronously, on the same call stack, before `bindExtensions()`: this package's subscriber registers the child synchronously, and the registration must land before binding proceeds so the child's own instance can detect itself the moment it loads.
 An implementation that awaits between creating the session and emitting, or that emits after binding, breaks detection for every child it spawns.
 
-Both are fire-and-forget broadcasts.
+All are fire-and-forget broadcasts.
 Nothing is returned, nothing is awaited, and no reply travels back over the bus.
 
+#### The optional `bound` channel
+
+Emitting `subagents:child:bound` is not part of the obligation, and an implementation that never emits it is fully conformant.
+What it buys is the unguarded-child alarm described under [What this package does on both ends](#what-this-package-does-on-both-ends): without it, a child that loads no instance of this package runs every tool in its `tools:` allowlist ungated and nothing says so.
+
+The timing is the whole point, and it is the one moment that answers the question.
+`bindExtensions()` awaits the child's `session_start` emit, so when it resolves every child extension has initialized and this package's child instance — if it loaded at all — has published its service.
+Emit it there: after the `await`, on the success path only.
+A child whose binding threw never ran, so reporting it would be a false alarm about a session that does not exist.
+
+No other moment works.
+`session-created` fires before the child's extensions have loaded, and by `disposed` the child's `session_shutdown` has already withdrawn its service — so a healthy child looks identical to an unguarded one at both.
+
 ### Out-of-process implementations
 
 An implementation that spawns a child as its own `pi` process sets one environment variable at spawn:
@@ -72,7 +91,7 @@ The full condition, with a worked example, is documented where the setting lives
 
 The announcement is all an implementation provides; this section is what it buys.
 
-On the announcing side, this package subscribes to the child lifecycle (`src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session in the `SubagentSessionRegistry` on `subagents:child:session-created`, unregistering it on `subagents:child:disposed`.
+On the announcing side, this package subscribes to the child lifecycle (`src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session in the `SubagentSessionRegistry` on `subagents:child:session-created`, unregistering it on `subagents:child:disposed`, and auditing it on `subagents:child:bound`.
 Because the event bus dispatches synchronously, that registration completes before `bindExtensions()` proceeds.
 
 The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/authority/subagent-registry.ts`.
@@ -83,7 +102,10 @@ What the announcement enables:
 
 1. **Deterministic child detection** — `isSubagentExecutionContext()` hits the process-global registry on the first check for an in-process child, and reads the environment for one spawned as its own process, with a session-directory heuristic behind both.
 2. **Per-agent policy enforcement** - the permission system's `before_agent_start` handler resolves the agent name from the `<active_agent>` system-prompt tag and applies per-agent `permission:` frontmatter overrides.
-3. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
+3. **An unguarded child is announced** — when a child finishes binding without publishing a service of its own, it has no permission node: no `tool_call` gate, no tool filtering, no `permission:` frontmatter resolution, and no ask-forwarding.
+   The parent records a `child_node_absent` review entry for every such child and warns once per session.
+   The likeliest cause is the child's own configuration — `@gotgenes/pi-subagents` excluding this package under `excludedExtensionPackages` — and a failure to load this extension in the child leaves the identical absence, which the parent cannot tell apart, so the warning names both.
+4. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
    The parent approves or denies, and the child resumes.
    When the parent approves "for this session," it chooses a scope: **this subagent only** (the least-privilege default) records the grant on the requesting child, while **the whole session** records it on the serving parent so the parent and all its subagents resolve it without re-prompting.
 
@@ -162,7 +184,7 @@ Nothing needs to be edited, and in-process children are unaffected: parent and c
 
 ## Conformance of known implementations
 
-Conformance is a property of the announcement alone — whether an implementation emits the in-process events, or sets the out-of-process variable — not of the frontmatter vocabulary it offers for tool visibility.
+Conformance is a property of the announcement alone — whether an implementation emits the two in-process events, or sets the out-of-process variable — not of the frontmatter vocabulary it offers for tool visibility, and not of the optional `bound` channel.
 
 | Extension                                                                           | Shape      | Adopts the convention             | Visibility key                     |
 | ----------------------------------------------------------------------------------- | ---------- | --------------------------------- | ---------------------------------- |
@@ -177,6 +199,9 @@ Adopting the convention is a one-line change at their spawn site.
 
 The upstream `tintinweb/pi-subagents` (which `@gotgenes/pi-subagents` forks) publishes no `subagents:child:session-created` event, so its in-process children have neither deterministic detection nor `ask`-state forwarding.
 
+`@gotgenes/pi-subagents` is also the only implementation that emits the optional `subagents:child:bound` channel, so it is the only one whose unguarded children are announced.
+The others forfeit that alarm without forfeiting conformance.
+
 See [guides/permission-frontmatter-for-subagent-extensions.md](guides/permission-frontmatter-for-subagent-extensions.md) for the companion convention on `permission:` frontmatter, which implementations document rather than implement.
 
 ---

package/package.json

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

package/src/authority/child-node-audit.ts

@@ -0,0 +1,94 @@
+/**
+ * child-node-audit.ts — Report an in-process subagent child that runs with no
+ * permission node.
+ *
+ * Gating is node-local (ADR 0012 decision 1): each node loads its own instance
+ * of this extension and gates its own `tool_call`s. A child that loads none has
+ * no gate, no tool filtering, no `permission:` frontmatter resolution, and no
+ * ask-forwarding — every tool in its `tools:` allowlist runs ungated. The
+ * parent's own gating is unaffected, so without this audit the operator watches
+ * the permission system work and never learns the child is unguarded.
+ *
+ * The signal is publication: since #699 every node publishes its service under
+ * its own session id, and a subagent implementation announces the moment a
+ * child finished binding its extensions. A child that has published nothing by
+ * then has no node.
+ *
+ * The two halves of the alarm fire at different rates on purpose. The review
+ * entry is the durable record and must be complete, so it is written for every
+ * affected child. The visible warning is capped at one per parent session: the
+ * cause is a single line of configuration, and a parent that fans out ten
+ * children would otherwise emit ten identical warnings.
+ */
+
+/** Answers whether the node whose session is `sessionId` published a service. */
+export type NodePresenceLookup = (sessionId: string) => boolean;
+
+/** The narrow log seam this audit needs (ISP): a durable record and a warning. */
+export interface ChildNodeAuditLog {
+  review(event: string, details?: Record<string, unknown>): void;
+  warn(message: string): void;
+}
+
+/** Fields read from the child-bound announcement (ISP). */
+export interface BoundChild {
+  /** Child session id — the key its node would have published under. */
+  sessionId: string;
+  parentSessionId?: string;
+}
+
+/**
+ * The agent-facing text for an unguarded child.
+ *
+ * The parent cannot tell a deliberate exclusion from a load failure — both
+ * leave the identical absence — so the message names the likelier cause and
+ * admits the other in the same sentence.
+ */
+export function childNodeAbsentMessage(childSessionId: string): string {
+  return (
+    `pi-permission-system: subagent child session ${childSessionId} is ` +
+    "running with no permission node — this extension is not loaded in it, so " +
+    "its tool calls are not gated there. Most often the package is listed in " +
+    "pi-subagents' excludedExtensionPackages; a failure to load this extension " +
+    "in the child does the same. Further affected children are recorded in the " +
+    "permission review log as child_node_absent."
+  );
+}
+
+/** The audit seam the child-lifecycle subscription drives (ISP). */
+export interface BoundChildAuditor {
+  auditBoundChild(child: BoundChild): void;
+}
+
+/**
+ * Audits each child that finishes binding, and alarms on one with no node.
+ *
+ * The warn-once 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:
+ * the operator has already been told.
+ */
+export class ChildNodeAudit implements BoundChildAuditor {
+  private warned = false;
+
+  constructor(
+    private readonly hasNode: NodePresenceLookup,
+    private readonly log: ChildNodeAuditLog,
+  ) {}
+
+  auditBoundChild(child: BoundChild): void {
+    if (this.hasNode(child.sessionId)) {
+      return;
+    }
+    this.log.review("child_node_absent", {
+      childSessionId: child.sessionId,
+      parentSessionId: child.parentSessionId ?? null,
+    });
+    if (this.warned) {
+      return;
+    }
+    this.warned = true;
+    this.log.warn(childNodeAbsentMessage(child.sessionId));
+  }
+}

package/src/authority/subagent-detection.ts

@@ -1,5 +1,4 @@
 import {
-  isRegisteredSubagentChild,
   isSubagentExecutionContext,
   type SubagentDetectionContext,
 } from "#src/authority/subagent-context";
@@ -17,17 +16,6 @@ export interface SubagentDetector {
   isSubagent(ctx: SubagentDetectionContext): boolean;
 }
 
-/**
- * Narrow seam for the service-publication guard (#302): "is the current
- * session a registered in-process child?"
- *
- * `PermissionServiceLifecycle` depends on this single-method view so a
- * registered child never publishes over its parent's process-global slot.
- */
-export interface RegisteredChildDetector {
-  isRegisteredChild(ctx: SubagentDetectionContext): boolean;
-}
-
 /** Composition-root inputs for {@link SubagentDetection}. */
 export interface SubagentDetectionDeps {
   subagentSessionsDir: string;
@@ -44,9 +32,7 @@ export interface SubagentDetectionDeps {
  * individually. Delegates to the pure detection functions in
  * {@link ./subagent-context}, holding only the deps.
  */
-export class SubagentDetection
-  implements SubagentDetector, RegisteredChildDetector
-{
+export class SubagentDetection implements SubagentDetector {
   constructor(private readonly deps: SubagentDetectionDeps) {}
 
   isSubagent(ctx: SubagentDetectionContext): boolean {
@@ -57,10 +43,4 @@ export class SubagentDetection
       this.deps.registry,
     );
   }
-
-  isRegisteredChild(ctx: SubagentDetectionContext): boolean {
-    return this.deps.registry
-      ? isRegisteredSubagentChild(ctx, this.deps.registry)
-      : false;
-  }
 }

package/src/authority/subagent-lifecycle-events.ts

@@ -1,10 +1,16 @@
 /**
  * subagent-lifecycle-events.ts — Subscribe to @gotgenes/pi-subagents' child
- * lifecycle events and keep the SubagentSessionRegistry in sync.
+ * lifecycle events and dispatch each fact to its owner.
  *
  * @gotgenes/pi-subagents publishes its child-execution lifecycle on the Pi
  * event bus (ADR 0002): it no longer calls this package's service directly.
- * We register the child on `session-created` and unregister it on `disposed`.
+ * We register the child on `session-created`, audit it for a permission node on
+ * `bound`, and unregister it on `disposed`.
+ *
+ * The module subscribes to the announcement and hands each fact to its owner —
+ * the registry for the two registration events, the audit for `bound` — so the
+ * channel names and payload shapes of the whole contract stay declared in one
+ * place.
  *
  * The channel names and payload shapes are declared independently here (the two
  * packages must not depend on each other under jiti) and MUST match the
@@ -15,13 +21,25 @@
  * event bus dispatches listeners synchronously, so a synchronous handler lands
  * the registry entry before binding proceeds. Introducing an `await` before
  * `registry.register(...)` would break the pre-bind ordering.
+ *
+ * The `bound` handler carries no such requirement — nothing waits on it — but it
+ * must not make the other two async either, since they share this module.
  */
 
+import type { BoundChildAuditor } from "./child-node-audit";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
 /** Emitted by the core after session creation, before `bindExtensions()`. */
 export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
 
+/**
+ * Emitted by the core once the child's extensions have bound, after every child
+ * `session_start` handler has run — the one moment a parent can observe what
+ * those extensions installed. Optional: an implementation that never emits it
+ * is still conformant, and simply forfeits the unguarded-child alarm.
+ */
+export const SUBAGENT_CHILD_BOUND = "subagents:child:bound";
+
 /** Emitted by the core in the run's `finally` (success and error). */
 export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
 
@@ -37,6 +55,13 @@ interface ChildSessionCreatedEvent {
   parentSessionId?: string;
 }
 
+/** Fields read from the `bound` payload (ISP). */
+interface ChildBoundEvent {
+  /** Child session id — the key its node would have published under. */
+  sessionId: string;
+  parentSessionId?: string;
+}
+
 /** Fields read from the `disposed` payload (ISP). */
 interface ChildDisposedEvent {
   /** Child session id — the registry key. Must match the publisher. */
@@ -46,12 +71,13 @@ interface ChildDisposedEvent {
 /**
  * Subscribe to the subagent child lifecycle.
  *
- * @returns an unsubscribe that detaches both handlers (call during
+ * @returns an unsubscribe that detaches every handler (call during
  *          `session_shutdown`).
  */
 export function subscribeSubagentLifecycle(
   events: LifecycleEventBus,
   registry: SubagentSessionRegistry,
+  audit: BoundChildAuditor,
 ): () => void {
   const unsubCreated = events.on(SUBAGENT_CHILD_SESSION_CREATED, (data) => {
     const event = data as ChildSessionCreatedEvent;
@@ -60,6 +86,14 @@ export function subscribeSubagentLifecycle(
     });
   });
 
+  const unsubBound = events.on(SUBAGENT_CHILD_BOUND, (data) => {
+    const event = data as ChildBoundEvent;
+    audit.auditBoundChild({
+      sessionId: event.sessionId,
+      parentSessionId: event.parentSessionId,
+    });
+  });
+
   const unsubDisposed = events.on(SUBAGENT_CHILD_DISPOSED, (data) => {
     const event = data as ChildDisposedEvent;
     registry.unregister(event.sessionId);
@@ -67,6 +101,7 @@ export function subscribeSubagentLifecycle(
 
   return () => {
     unsubCreated();
+    unsubBound();
     unsubDisposed();
   };
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   ObservedAuthorizerRegistrar,
 } from "./authority/authorizer-registry";
 import { AuthorizerSelection } from "./authority/authorizer-selection";
+import { ChildNodeAudit } from "./authority/child-node-audit";
 import {
   ForwardedRequestServer,
   type ServingPolicy,
@@ -50,7 +51,7 @@ import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
 import { resolveRenderBudget } from "./presentation/dialog-renderer";
-import type { PermissionsService } from "./service";
+import { getPermissionsService, type PermissionsService } from "./service";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
@@ -259,22 +260,28 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   );
 
   // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
-  // sessions register/unregister without the core calling us (ADR 0002).
+  // sessions register/unregister without the core calling us (ADR 0002), and
+  // so a child that bound its extensions without loading one of ours is
+  // reported rather than silently ungated (#792). The lookup is a thunk over
+  // the locator, never a cached reference, per the guidance in service.ts.
+  const childNodeAudit = new ChildNodeAudit(
+    (sessionId) => getPermissionsService(sessionId) !== undefined,
+    logger,
+  );
   const unsubSubagentLifecycle = subscribeSubagentLifecycle(
     pi.events,
     subagentRegistry,
+    childNodeAudit,
   );
 
   // PermissionServiceLifecycle owns the process-global service publication:
-  // activate() publishes this node's service under its own session id (and to
-  // the legacy root slot unless this is a registered subagent child — see
-  // #302), then announces the node's session id and chain role on the ready
-  // channel; teardown() unsubscribes all session listeners and unpublishes.
+  // activate() publishes this node's service under its own session id, then
+  // announces the node's session id and chain role on the ready channel;
+  // teardown() unsubscribes all session listeners and unpublishes.
   // Deferred to session_start because both facts come from ctx, unavailable at
   // factory-init time.
   const serviceLifecycle = new PermissionServiceLifecycle(
     permissionsService,
-    subagentDetection,
     authorizerSelection,
     pi.events,
     [unsubSubagentLifecycle],

package/src/service-lifecycle.ts

@@ -1,13 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AdjudicationRole } from "./authority/authorizer-selection";
-import type { RegisteredChildDetector } from "./authority/subagent-detection";
 import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
 import {
   type PermissionsService,
   publishPermissionsService,
-  publishRootPermissionsService,
   unpublishPermissionsService,
-  unpublishRootPermissionsService,
 } from "./service";
 import { readSessionId } from "./session-identity";
 
@@ -35,18 +32,16 @@ export interface ReadyAnnouncer {
  *
  * - `activate` publishes the service under this node's own session id, so a
  *   sibling extension loaded into this node registers into the registries this
- *   node's gates and chain read. It additionally publishes to the legacy
- *   process-root slot unless this is a registered subagent child, which must
- *   not clobber its parent's slot (#302). Then it announces both facts a
- *   consumer needs — the session id and the chain role — on the ready channel,
- *   and re-arms the latch so the turn about to start announces once more.
+ *   node's gates and chain read. Then it announces both facts a consumer needs
+ *   — the session id and the chain role — on the ready channel, and re-arms the
+ *   latch so the turn about to start announces once more.
  * - `announceReady` is that second announcement: it fires at most once per
  *   activation cycle, so `permissions:ready` reaches a consumer whose own
  *   `session_start` ran after this node's (ADR 0012 decision 3). The channel's
  *   contract is therefore "at least once per session, and may repeat" —
  *   handlers must be idempotent.
  * - `teardown` runs all session-scoped subscription cleanups in order, then
- *   unpublishes from both slots. Each unpublish is identity-scoped, so a
+ *   unpublishes this node's entry. The unpublish is identity-scoped, so a
  *   superseded `/reload` generation cannot evict the fresh one.
  */
 export class PermissionServiceLifecycle
@@ -60,7 +55,6 @@ export class PermissionServiceLifecycle
 
   constructor(
     private readonly service: PermissionsService,
-    private readonly detection: RegisteredChildDetector,
     private readonly role: AdjudicationRole,
     private readonly events: PermissionEventBus,
     private readonly subscriptions: readonly (() => void)[],
@@ -75,9 +69,6 @@ export class PermissionServiceLifecycle
       publishPermissionsService(sessionId, this.service);
       this.publishedSessionId = sessionId;
     }
-    if (!this.detection.isRegisteredChild(ctx)) {
-      publishRootPermissionsService(this.service);
-    }
     this.emitReady(ctx);
   }
 
@@ -97,7 +88,6 @@ export class PermissionServiceLifecycle
       unpublishPermissionsService(this.publishedSessionId, this.service);
       this.publishedSessionId = null;
     }
-    unpublishRootPermissionsService(this.service);
   }
 
   /**

package/src/service.ts

@@ -7,15 +7,12 @@
  * accessors here read from the same `globalThis` slots the provider wrote to —
  * enabling direct, synchronous, type-safe function calls.
  *
- * There are two slots, because one process can host several **nodes** (one Pi
- * session runtime each — a root session and its in-process subagent children
- * all load their own instance of this extension):
- *
- * - A session-keyed map, written by every node under its own session id.
- *   `getPermissionsService(sessionId)` resolves the service whose
- *   registries that node's own gates and chain read (ADR 0012 decision 2).
- * - A single legacy slot holding the process root's service, read by the
- *   deprecated `getRootPermissionsService()`.
+ * The slot is a session-keyed map, because one process can host several
+ * **nodes** (one Pi session runtime each — a root session and its in-process
+ * subagent children all load their own instance of this extension). Every node
+ * writes under its own session id, and `getPermissionsService(sessionId)`
+ * resolves the service whose registries that node's own gates and chain read
+ * (ADR 0012 decision 2).
  *
  * Best practice: resolve per use rather than caching the reference — this
  * ensures resilience across `/reload` and load-order edge cases.
@@ -72,9 +69,6 @@ export type {
 } from "./presentation/prompt-payload";
 export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
 
-/** Process-global key for the legacy (process-root) service slot. */
-const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
-
 /** Process-global key for the session-keyed service map (ADR 0012 decision 2). */
 const SESSION_SERVICES_KEY = Symbol.for(
   "@gotgenes/pi-permission-system:session-services",
@@ -120,8 +114,7 @@ export interface PermissionQuery {
 
 /**
  * Public interface exposed to other extensions via
- * {@link getPermissionsService} (or the deprecated
- * {@link getRootPermissionsService}).
+ * {@link getPermissionsService}.
  *
  * Each instance belongs to one node, and its three registration surfaces are
  * read by that node alone: extractors and formatters by its own gates, chain
@@ -203,77 +196,13 @@ export interface PermissionsService extends PermissionQuery {
   ): () => void;
 }
 
-/**
- * Store a `PermissionsService` in the legacy process-root slot, read by
- * `getRootPermissionsService()`.
- *
- * Called at `session_start` by the top-level (parent) instance only — an
- * in-process subagent child skips publishing so it cannot clobber the parent's
- * service. Overwrites any previously published service, which keeps `/reload`
- * working: a reloaded parent re-publishes its fresh service.
- */
-export function publishRootPermissionsService(
-  service: PermissionsService,
-): void {
-  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
-}
-
-/**
- * Warned at most once per module copy, so a consumer hears it on its first
- * deprecated call and never again. Under jiti isolation each consumer
- * extension holds its own copy, so each hears it for its own call site.
- */
-let warnedDeprecatedAccessor = false;
-
-const DEPRECATED_ACCESSOR_WARNING =
-  "getRootPermissionsService() is deprecated: it answers with the process root's " +
-  "service, which is the wrong node in every node but the root — inside an " +
-  "in-process subagent child it hands back the parent's service, so a " +
-  "registration lands where the child's gates never read it and a policy " +
-  "query answers against the parent's config. Use " +
-  "getPermissionsService(sessionId) with the sessionId from the " +
-  "permissions:ready payload. See " +
-  "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/cross-extension-api.md";
-
-/**
- * Retrieve the process root's published `PermissionsService`, or `undefined`
- * if the permission-system extension has not loaded (or has been unloaded).
- *
- * @deprecated Use {@link getPermissionsService} with the `sessionId`
- * from the `permissions:ready` payload. This accessor answers "the process
- * root's service", which is the wrong question in every node but the root.
- * Removal is deferred to a future major (ADR 0012 decision 7).
- */
-export function getRootPermissionsService(): PermissionsService | undefined {
-  if (!warnedDeprecatedAccessor) {
-    warnedDeprecatedAccessor = true;
-    process.emitWarning(DEPRECATED_ACCESSOR_WARNING, {
-      type: "DeprecationWarning",
-      code: "PI_PERMISSION_SYSTEM_DEP0001",
-    });
-  }
-  return readRootService();
-}
-
-/**
- * The undeprecated read of the root slot, for this package's own lifecycle.
- *
- * `unpublishRootPermissionsService` must compare identities without warning the
- * host about a call the host did not make.
- */
-function readRootService(): PermissionsService | undefined {
-  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
-    | PermissionsService
-    | undefined;
-}
-
 /**
  * The process-global map of session id → that node's service, created on first
  * use.
  *
- * Backed by `globalThis` + `Symbol.for()` for the same reason the single slot
- * above is: each session's `ResourceLoader` builds its own jiti instance, so a
- * parent and its in-process child share no module state — only process globals.
+ * Backed by `globalThis` + `Symbol.for()` because each session's
+ * `ResourceLoader` builds its own jiti instance, so a parent and its in-process
+ * child share no module state — only process globals.
  */
 function sessionServices(): Map<string, PermissionsService> {
   const store = globalThis as Record<symbol, unknown>;
@@ -331,9 +260,7 @@ export function getPermissionsService(
 const MISSING_SESSION_ID_WARNING =
   "getPermissionsService() was called without a session id and answered " +
   "undefined. It resolves the service of one node, so it needs the sessionId " +
-  "from the permissions:ready payload: getPermissionsService(sessionId). To " +
-  "read the process root's service — what the zero-arg call used to do — use " +
-  "the deprecated getRootPermissionsService(). See " +
+  "from the permissions:ready payload: getPermissionsService(sessionId). See " +
   "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/cross-extension-api.md";
 
 /**
@@ -358,10 +285,11 @@ function warnMissingSessionId(): void {
 
 /**
  * Remove the `sessionId` entry, but only when it still holds `service`
- * (identity compare-and-delete, like {@link unpublishRootPermissionsService}).
+ * (identity compare-and-delete).
  *
- * Scoping the delete to the publishing instance keeps a superseded `/reload`
- * generation's late shutdown from wiping the new generation's freshly
+ * Called during `session_shutdown` to avoid stale references after the node is
+ * torn down. Scoping the delete to the publishing instance keeps a superseded
+ * `/reload` generation's late shutdown from wiping the new generation's freshly
  * published service.
  */
 export function unpublishPermissionsService(
@@ -373,26 +301,3 @@ export function unpublishPermissionsService(
     services.delete(sessionId);
   }
 }
-
-/**
- * Remove `service` from `globalThis`, but only when the current slot still
- * holds it (identity compare-and-delete).
- *
- * Called during `session_shutdown` to avoid stale references after the
- * extension is torn down. Scoping the delete to the publishing instance keeps
- * two cases correct:
- *
- * - An in-process subagent child never published the parent's service, so its
- *   shutdown is a no-op and the parent's slot survives.
- * - A superseded `/reload` generation no longer owns the slot, so its late
- *   shutdown cannot wipe the new generation's freshly published service.
- */
-export function unpublishRootPermissionsService(
-  service: PermissionsService,
-): void {
-  if (readRootService() !== service) {
-    return;
-  }
-  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
-  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
-}