@gotgenes/pi-permission-system 10.2.0 → 10.3.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [10.3.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.3.0...pi-permission-system-v10.3.1) (2026-06-06)
+
+
+### Bug Fixes
+
+* share one PermissionManager and SessionRules across gate and RPC paths ([#337](https://github.com/gotgenes/pi-packages/issues/337)) ([7dd1e65](https://github.com/gotgenes/pi-packages/commit/7dd1e65493fa0061a3b84eb329457f939b953e0a))
+
+## [10.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.2.0...pi-permission-system-v10.3.0) (2026-06-05)
+
+
+### Features
+
+* add ConfigStore owning extension config state ([5941733](https://github.com/gotgenes/pi-packages/commit/5941733a67c0ad9aef3d3b2e5908a82e76ac8603))
+
 ## [10.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.1.0...pi-permission-system-v10.2.0) (2026-06-04)
 
 

package/package.json

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

package/src/config-modal.ts

@@ -5,6 +5,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type SettingItem, SettingsList } from "@earendil-works/pi-tui";
 
+import type { CommandConfigStore } from "./config-store";
 import {
   DEFAULT_EXTENSION_CONFIG,
   type PermissionSystemExtensionConfig,
@@ -12,11 +13,7 @@ import {
 import type { Ruleset } from "./rule";
 
 interface PermissionSystemConfigController {
-  getConfig(): PermissionSystemExtensionConfig;
-  setConfig(
-    next: PermissionSystemExtensionConfig,
-    ctx: ExtensionCommandContext,
-  ): void;
+  config: CommandConfigStore;
   getConfigPath(): string;
   /** Optional: returns the composed config-layer ruleset for origin display. */
   getComposedRules?(): Ruleset;
@@ -175,15 +172,15 @@ async function openSettingsModal(
   // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- ctx.ui.custom<void> is valid; rule does not allow void in generic fn call type args
   await ctx.ui.custom<void>(
     (_tui, _theme, _keybindings, done) => {
-      let current = controller.getConfig();
+      let current = controller.config.current();
       const settingsList = new SettingsList(
         buildSettingItems(current),
         10,
         getSettingsListTheme(),
         (id, newValue) => {
           current = applySetting(current, id, newValue);
-          controller.setConfig(current, ctx);
-          current = controller.getConfig();
+          controller.config.save(current, ctx);
+          current = controller.config.current();
           syncSettingValues(settingsList, current);
         },
         () => done(),
@@ -208,7 +205,7 @@ function handleArgs(
   if (normalized === "show") {
     const rules = controller.getComposedRules?.();
     ctx.ui.notify(
-      `permission-system: ${summarizeConfig(controller.getConfig(), rules)}`,
+      `permission-system: ${summarizeConfig(controller.config.current(), rules)}`,
       "info",
     );
     return true;
@@ -223,7 +220,7 @@ function handleArgs(
   }
 
   if (normalized === "reset") {
-    controller.setConfig(cloneDefaultConfig(), ctx);
+    controller.config.save(cloneDefaultConfig(), ctx);
     ctx.ui.notify("Permission system settings reset to defaults.", "info");
     return true;
   }

package/src/config-store.ts

@@ -0,0 +1,227 @@
+import {
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, normalize } from "node:path";
+import type {
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
+import {
+  getGlobalConfigPath,
+  getLegacyExtensionConfigPath,
+  getLegacyGlobalPolicyPath,
+  getLegacyProjectPolicyPath,
+} from "./config-paths";
+import { buildResolvedConfigLogEntry } from "./config-reporter";
+import {
+  DEFAULT_EXTENSION_CONFIG,
+  EXTENSION_ROOT,
+  normalizePermissionSystemConfig,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config";
+import type { ResolvedPolicyPaths } from "./policy-loader";
+import { syncPermissionSystemStatus } from "./status";
+
+/** Read-only view of the current config — for consumers that only read. */
+export interface ConfigReader {
+  current(): PermissionSystemExtensionConfig;
+}
+
+/**
+ * Narrow subset of `ConfigStore` that `PermissionSession` depends on.
+ *
+ * Using an interface rather than the concrete class avoids private-member
+ * coupling between the class and test doubles.
+ */
+export interface SessionConfigStore extends ConfigReader {
+  refresh(ctx?: ExtensionContext): void;
+  logResolvedPaths(cwd?: string): void;
+}
+
+/**
+ * Narrow subset of `ConfigStore` for the `/permission-system` command.
+ *
+ * Using an interface rather than the concrete class avoids private-member
+ * coupling between the class and test doubles.
+ */
+export interface CommandConfigStore extends ConfigReader {
+  save(
+    next: PermissionSystemExtensionConfig,
+    ctx: ExtensionCommandContext,
+  ): void;
+}
+
+/** Narrow logging sink — replaced by an injected logger in Step 3 (#336). */
+export interface ConfigStoreLogger {
+  writeDebugLog(event: string, details?: Record<string, unknown>): void;
+  writeReviewLog(event: string, details?: Record<string, unknown>): void;
+}
+
+/** Narrow view of the manager's resolved policy paths (for `logResolvedPaths`). */
+export interface ResolvedPolicyPathProvider {
+  getResolvedPolicyPaths(): ResolvedPolicyPaths;
+}
+
+export interface ConfigStoreDeps {
+  agentDir: string;
+  policyPaths: ResolvedPolicyPathProvider;
+  logger: ConfigStoreLogger;
+}
+
+/**
+ * Owns the mutable extension config and the operations that read/write it.
+ *
+ * Replaces the three `(runtime, …)` config free functions
+ * (`refreshExtensionConfig`, `saveExtensionConfig`, `logResolvedConfigPaths`)
+ * with methods that privately own `config` and `lastConfigWarning`.
+ *
+ * Implements {@link ConfigReader} so consumers that only read the current config
+ * can depend on the narrow interface rather than the full class.
+ */
+export class ConfigStore implements SessionConfigStore, CommandConfigStore {
+  private config: PermissionSystemExtensionConfig;
+  private lastConfigWarning: string | null = null;
+
+  constructor(private readonly deps: ConfigStoreDeps) {
+    this.config = { ...DEFAULT_EXTENSION_CONFIG };
+  }
+
+  /** Return the current extension config. */
+  current(): PermissionSystemExtensionConfig {
+    return this.config;
+  }
+
+  /**
+   * Reload merged config from disk.
+   *
+   * If `ctx` is provided, uses it to derive the cwd and sync UI status.
+   * Equivalent to `refreshExtensionConfig(runtime, ctx?)`.
+   */
+  refresh(ctx?: ExtensionContext): void {
+    const cwd = ctx?.cwd ?? null;
+    const mergeResult = loadAndMergeConfigs(
+      this.deps.agentDir,
+      cwd ?? "",
+      EXTENSION_ROOT,
+    );
+    const runtimeConfig = normalizePermissionSystemConfig(mergeResult.merged);
+    this.config = runtimeConfig;
+
+    if (ctx?.hasUI) {
+      syncPermissionSystemStatus(ctx, runtimeConfig);
+    }
+
+    const warning =
+      mergeResult.issues.length > 0 ? mergeResult.issues.join("\n") : undefined;
+
+    if (warning && warning !== this.lastConfigWarning) {
+      this.lastConfigWarning = warning;
+      ctx?.ui.notify(warning, "warning");
+    } else if (!warning) {
+      this.lastConfigWarning = null;
+    }
+
+    this.deps.logger.writeDebugLog("config.loaded", {
+      warning: warning ?? null,
+      debugLog: runtimeConfig.debugLog,
+      permissionReviewLog: runtimeConfig.permissionReviewLog,
+      yoloMode: runtimeConfig.yoloMode,
+    });
+  }
+
+  /**
+   * Save updated runtime knobs to the global config file, then update
+   * the current config and sync UI status.
+   *
+   * Equivalent to `saveExtensionConfig(runtime, next, ctx)`.
+   */
+  // Called via the CommandConfigStore interface from config-modal.ts — fallow cannot trace through interfaces.
+  // fallow-ignore-next-line unused-class-member
+  save(
+    next: PermissionSystemExtensionConfig,
+    ctx: ExtensionCommandContext,
+  ): void {
+    const normalized = normalizePermissionSystemConfig(next);
+    const globalPath = getGlobalConfigPath(this.deps.agentDir);
+
+    const existing = loadUnifiedConfig(globalPath);
+    const merged = {
+      ...existing.config,
+      debugLog: normalized.debugLog,
+      permissionReviewLog: normalized.permissionReviewLog,
+      yoloMode: normalized.yoloMode,
+    };
+
+    const tmpPath = `${globalPath}.tmp`;
+    try {
+      mkdirSync(dirname(globalPath), { recursive: true });
+      writeFileSync(tmpPath, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+      renameSync(tmpPath, globalPath);
+    } catch (error) {
+      try {
+        if (existsSync(tmpPath)) {
+          unlinkSync(tmpPath);
+        }
+      } catch {
+        // Ignore cleanup failures.
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(
+        `Failed to save permission-system config at '${globalPath}': ${message}`,
+        "error",
+      );
+      return;
+    }
+
+    this.config = normalized;
+    syncPermissionSystemStatus(ctx, normalized);
+    this.lastConfigWarning = null;
+
+    this.deps.logger.writeDebugLog("config.saved", {
+      debugLog: normalized.debugLog,
+      permissionReviewLog: normalized.permissionReviewLog,
+      yoloMode: normalized.yoloMode,
+    });
+  }
+
+  /**
+   * Write the resolved config path set to the review and debug logs.
+   *
+   * Equivalent to `logResolvedConfigPaths(runtime)`.
+   */
+  logResolvedPaths(cwd?: string): void {
+    const policyPaths = this.deps.policyPaths.getResolvedPolicyPaths();
+    const { agentDir } = this.deps;
+    const legacyGlobalPolicyDetected = existsSync(
+      getLegacyGlobalPolicyPath(agentDir),
+    );
+    const legacyProjectPolicyDetected = cwd
+      ? existsSync(getLegacyProjectPolicyPath(cwd))
+      : false;
+    const legacyExtConfigPath = getLegacyExtensionConfigPath(EXTENSION_ROOT);
+    const newGlobalPath = getGlobalConfigPath(agentDir);
+    const legacyExtensionConfigDetected =
+      normalize(legacyExtConfigPath) !== normalize(newGlobalPath) &&
+      existsSync(legacyExtConfigPath);
+    const entry = buildResolvedConfigLogEntry({
+      policyPaths,
+      legacyGlobalPolicyDetected,
+      legacyProjectPolicyDetected,
+      legacyExtensionConfigDetected,
+    });
+    this.deps.logger.writeReviewLog(
+      "config.resolved",
+      entry as unknown as Record<string, unknown>,
+    );
+    this.deps.logger.writeDebugLog(
+      "config.resolved",
+      entry as unknown as Record<string, unknown>,
+    );
+  }
+}

package/src/index.ts

@@ -1,8 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
+import { ConfigStore } from "./config-store";
 import { GateDecisionReporter } from "./decision-reporter";
+import { computeExtensionPaths } from "./extension-paths";
 import {
   PermissionForwarder,
   type PermissionForwarderDeps,
@@ -22,14 +25,9 @@ import { PermissionManager } from "./permission-manager";
 import { PermissionPrompter } from "./permission-prompter";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
-import {
-  createExtensionRuntime,
-  logResolvedConfigPaths,
-  refreshExtensionConfig,
-  saveExtensionConfig,
-} from "./runtime";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { createSessionLogger } from "./session-logger";
+import { SessionRules } from "./session-rules";
 import { isSubagentExecutionContext } from "./subagent-context";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./subagent-registry";
@@ -40,58 +38,85 @@ import {
 } from "./yolo-mode";
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
-  const runtime = createExtensionRuntime();
+  const agentDir = getAgentDir();
+  const paths = computeExtensionPaths(agentDir);
+  const permissionManager = new PermissionManager({ agentDir });
+  const sessionRules = new SessionRules();
   const subagentRegistry = getSubagentSessionRegistry();
   const formatterRegistry = new ToolInputFormatterRegistry();
   registerBuiltinToolInputFormatters(formatterRegistry);
 
+  // Forward reference: configStore is declared before the logger so the
+  // logger's getConfig thunk can close over the variable; assigned immediately
+  // after. Typed via cast so the closure compiles without assertions.
+  // The same null-at-init pattern used in the former createExtensionRuntime.
+  let configStore = null as unknown as ConfigStore;
+
+  // sessionNotify is a mutable holder so the logger's notify closure can
+  // reach the UI once PermissionSession is constructed. Starts as null;
+  // notify is a best-effort sink (no-op at factory-init when there is no UI).
+  let sessionNotify: PermissionSession | null = null;
+
+  const logger = createSessionLogger({
+    globalLogsDir: paths.globalLogsDir,
+    getConfig: () => configStore.current(),
+    notify: (message) =>
+      sessionNotify?.getRuntimeContext()?.ui.notify(message, "warning"),
+  });
+
+  configStore = new ConfigStore({
+    agentDir,
+    policyPaths: permissionManager,
+    logger: {
+      writeDebugLog: (e, d) => logger.debug(e, d),
+      writeReviewLog: (e, d) => logger.review(e, d),
+    },
+  });
+
   const forwardingDeps: PermissionForwarderDeps = {
-    forwardingDir: runtime.forwardingDir,
-    subagentSessionsDir: runtime.subagentSessionsDir,
+    forwardingDir: paths.forwardingDir,
+    subagentSessionsDir: paths.subagentSessionsDir,
     registry: subagentRegistry,
     events: pi.events,
     logger: {
-      writeReviewLog: runtime.writeReviewLog.bind(runtime),
-      writeDebugLog: runtime.writeDebugLog.bind(runtime),
+      writeReviewLog: (event, details) => logger.review(event, details),
+      writeDebugLog: (event, details) => logger.debug(event, details),
     },
-    writeReviewLog: runtime.writeReviewLog.bind(runtime),
+    writeReviewLog: (event, details) => logger.review(event, details),
     requestPermissionDecisionFromUi,
     shouldAutoApprove: () =>
-      shouldAutoApprovePermissionState("ask", runtime.config),
+      shouldAutoApprovePermissionState("ask", configStore.current()),
   };
   const forwarder = new PermissionForwarder(forwardingDeps);
 
   const prompter = new PermissionPrompter({
-    getConfig: () => runtime.config,
-    writeReviewLog: runtime.writeReviewLog.bind(runtime),
+    config: configStore,
+    writeReviewLog: (event, details) => logger.review(event, details),
     events: pi.events,
     forwarder,
   });
 
-  refreshExtensionConfig(runtime);
-
-  const sessionManager = new PermissionManager({ agentDir: runtime.agentDir });
+  configStore.refresh();
 
   const session = new PermissionSession(
-    runtime,
-    createSessionLogger(runtime),
+    paths,
+    logger,
     new ForwardingManager(
-      runtime.subagentSessionsDir,
+      paths.subagentSessionsDir,
       forwarder,
       subagentRegistry,
     ),
-    sessionManager,
+    permissionManager,
+    sessionRules,
+    configStore,
     {
-      refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
-      logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
-      getConfig: () => runtime.config,
       canRequestPermissionConfirmation: (ctx) =>
         canResolveAskPermissionRequest({
-          config: runtime.config,
+          config: configStore.current(),
           hasUI: ctx.hasUI,
           isSubagent: isSubagentExecutionContext(
             ctx,
-            runtime.subagentSessionsDir,
+            paths.subagentSessionsDir,
             subagentRegistry,
           ),
         }),
@@ -99,27 +124,29 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     },
   );
 
+  // Connect the notify sink now that session is available.
+  sessionNotify = session;
+
   registerPermissionSystemCommand(pi, {
-    getConfig: () => runtime.config,
-    setConfig: (next, ctx) => saveExtensionConfig(runtime, next, ctx),
-    getConfigPath: () => getGlobalConfigPath(runtime.agentDir),
+    config: configStore,
+    getConfigPath: () => getGlobalConfigPath(agentDir),
     getComposedRules: () =>
-      runtime.permissionManager.getComposedConfigRules(
-        runtime.lastKnownActiveAgentName ?? undefined,
+      permissionManager.getComposedConfigRules(
+        session.lastKnownActiveAgentName ?? undefined,
       ),
   });
 
   const rpcHandles = registerPermissionRpcHandlers(pi.events, {
-    getPermissionManager: () => runtime.permissionManager,
-    getSessionRules: () => runtime.sessionRules.getRuleset(),
-    getRuntimeContext: () => runtime.runtimeContext,
+    getPermissionManager: () => permissionManager,
+    getSessionRules: () => sessionRules.getRuleset(),
+    getRuntimeContext: () => session.getRuntimeContext(),
     requestPermissionDecisionFromUi,
-    writeReviewLog: runtime.writeReviewLog.bind(runtime),
+    writeReviewLog: (event, details) => logger.review(event, details),
   });
 
   const permissionsService = new LocalPermissionsService(
-    runtime.permissionManager,
-    runtime.sessionRules,
+    permissionManager,
+    sessionRules,
     formatterRegistry,
   );
 

package/src/permission-prompter.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PermissionSystemExtensionConfig } from "./extension-config";
+import type { ConfigReader } from "./config-store";
 import type { ApprovalRequester } from "./forwarded-permissions/permission-forwarder";
 import type { PermissionPromptDecision } from "./permission-dialog";
 import {
@@ -45,7 +45,7 @@ export interface PermissionPrompterApi {
  */
 export interface PermissionPrompterDeps {
   /** Read current config for yolo-mode check (called at prompt time). */
-  getConfig(): PermissionSystemExtensionConfig;
+  config: ConfigReader;
   /** Write structured entries to the permission review log. */
   writeReviewLog(event: string, details: Record<string, unknown>): void;
   /** Event bus used for UI prompt broadcasts. */
@@ -72,7 +72,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
     ctx: ExtensionContext,
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
-    if (shouldAutoApprovePermissionState("ask", this.deps.getConfig())) {
+    if (shouldAutoApprovePermissionState("ask", this.deps.config.current())) {
       this.writeReviewEntry("permission_request.auto_approved", details);
       return { approved: true, state: "approved", autoApproved: true };
     }

package/src/permission-session.ts

@@ -5,6 +5,7 @@ import {
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
 import type { AgentPrepSession } from "./agent-prep-session";
+import type { SessionConfigStore } from "./config-store";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
@@ -19,7 +20,7 @@ import type { SessionApproval } from "./session-approval";
 import type { SessionApprovalRecorder } from "./session-approval-recorder";
 import type { SessionLifecycleSession } from "./session-lifecycle-session";
 import type { SessionLogger } from "./session-logger";
-import { SessionRules } from "./session-rules";
+import type { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import {
   resolveToolPreviewLimits,
@@ -30,16 +31,9 @@ import type { PermissionCheckResult, PermissionState } from "./types";
 /**
  * Runtime operations that `PermissionSession` delegates to but does not own.
  *
- * Injected at construction time from the composition root (`index.ts`),
- * where the `ExtensionRuntime` is available.
+ * Injected at construction time from the composition root (`index.ts`).
  */
 export interface PermissionSessionRuntimeDeps {
-  /** Reload merged config from disk; optionally update the stored runtime context. */
-  refreshExtensionConfig(ctx?: ExtensionContext): void;
-  /** Write the resolved config path set to the review and debug logs. */
-  logResolvedConfigPaths(): void;
-  /** Read current extension config (called at query time). */
-  getConfig(): PermissionSystemExtensionConfig;
   /** Whether the current context can show an interactive permission prompt. */
   canRequestPermissionConfirmation(ctx: ExtensionContext): boolean;
   /** Prompt the user for a permission decision, log the outcome, and return it. */
@@ -61,7 +55,8 @@ export interface PermissionSessionRuntimeDeps {
  * - `ExtensionPaths` — immutable path constants
  * - `SessionLogger` — debug + review + warn
  * - `ForwardingController` — polling lifecycle
- * - `PermissionSessionRuntimeDeps` — config refresh + log delegates
+ * - `SessionConfigStore` — owns extension config; provides refresh, log, read
+ * - `PermissionSessionRuntimeDeps` — prompting + permission-confirmation bridge
  */
 export class PermissionSession
   implements
@@ -73,7 +68,6 @@ export class PermissionSession
     SessionLifecycleSession
 {
   private context: ExtensionContext | null = null;
-  private readonly sessionRules = new SessionRules();
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
   private toolsCacheKey: string | null = null;
@@ -84,6 +78,8 @@ export class PermissionSession
     readonly logger: SessionLogger,
     private readonly forwarding: ForwardingController,
     private readonly permissionManager: ScopedPermissionManager,
+    private readonly sessionRules: SessionRules,
+    private readonly configStore: SessionConfigStore,
     private readonly runtimeDeps: PermissionSessionRuntimeDeps,
   ) {}
 
@@ -260,17 +256,17 @@ export class PermissionSession
 
   /** Reload merged config from disk; optionally update the stored runtime context. */
   refreshConfig(ctx?: ExtensionContext): void {
-    this.runtimeDeps.refreshExtensionConfig(ctx);
+    this.configStore.refresh(ctx);
   }
 
   /** Write the resolved config path set to the review and debug logs. */
   logResolvedConfigPaths(): void {
-    this.runtimeDeps.logResolvedConfigPaths();
+    this.configStore.logResolvedPaths(this.context?.cwd);
   }
 
   /** Read current extension config. */
   get config(): PermissionSystemExtensionConfig {
-    return this.runtimeDeps.getConfig();
+    return this.configStore.current();
   }
 
   // ── Infrastructure paths ───────────────────────────────────────────────

package/src/permissions-service.ts

@@ -10,11 +10,9 @@ import type {
 /**
  * In-process implementation of the cross-extension {@link PermissionsService}.
  *
- * Constructed once in the composition root and backed by the runtime's
- * permission manager and session rules. Both injected instances are stable
- * for the lifetime of the factory — `runtime.permissionManager` is never
- * reassigned on the runtime object (only `PermissionSession` reassigns its
- * own internal copy), and `runtime.sessionRules` is `readonly`.
+ * Constructed once in the composition root and backed by the single shared
+ * `PermissionManager` and `SessionRules` instances that `PermissionSession`
+ * also uses — so service queries and gate-path approvals see the same state.
  */
 export class LocalPermissionsService implements PermissionsService {
   constructor(