pi-usereq 0.84.0 → 0.86.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.84.0)
+# PI-useReq/pi-usereq (0.86.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/command-report-entry.ts

@@ -0,0 +1,182 @@
+/**
+ * @file
+ * @brief Persists durable non-agentic command execution reports as custom session entries.
+ * @details Defines the stable custom-entry type, machine-readable report payload, builders for `req-references` outcome lines, and the pi guarded helpers that append the report entry and register its transcript renderer. Custom entries are stored in the session file, excluded from LLM context, rendered live through `entry_appended`, and re-rendered after any session restore, so transient UI-notification collapsing or chat rebuilds never lose the executed-commands outcome report. Runtime is O(n) in report-line count. Side effects are limited to session-entry persistence and renderer registration through the pi extension API.
+ */
+
+import type {
+  CustomEntry,
+  EntryRenderOptions,
+  EntryRenderer,
+  ExtensionAPI,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import { formatRuntimePathForDisplay } from "./path-context.js";
+import type { ReqReferencesCommandExecutionResult } from "./req-references-command.js";
+
+/**
+ * @brief Declares the stable custom-entry type used for durable command execution reports.
+ * @details Identifies `pi-usereq` report entries inside the persisted session file so interactive mode renders them through the registered entry renderer after reload, resume, fork, and session switches. Lookup complexity is O(1).
+ */
+export const COMMAND_REPORT_ENTRY_TYPE = "pi-usereq.command-report";
+
+/**
+ * @brief Describes one durable command execution report entry payload.
+ * @details Stores the originating slash-command name, the report severity, the terminal outcome, and the ordered per-operation outcome lines rendered in the transcript. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface CommandReportEntryData {
+  command: string;
+  level: "info" | "error";
+  outcome: "success" | "error";
+  lines: string[];
+}
+
+/**
+ * @brief Describes the loosely-typed pi runtime surface required for durable report entries.
+ * @details Narrows the extension API to the optional `registerEntryRenderer(...)` and `appendEntry(...)` methods consumed by the guarded report helpers so legacy hosts and offline harnesses without custom-entry support degrade silently instead of throwing. The interface is compile-time only and introduces no runtime cost.
+ */
+interface CommandReportEntryRegistrar {
+  registerEntryRenderer?: (
+    customType: string,
+    renderer: EntryRenderer<CommandReportEntryData>,
+  ) => void;
+  appendEntry?: (customType: string, data?: CommandReportEntryData) => void;
+}
+
+/**
+ * @brief Validates one loosely-typed payload as a command report entry payload.
+ * @details Accepts only payloads with a non-empty command string, the documented `info|error` level, the documented `success|error` outcome, and a string-only lines array so malformed session data never reaches the transcript renderer. Runtime is O(n) in line count. No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted payload.
+ * @return {boolean} `true` when the payload satisfies the report entry contract.
+ */
+function isCommandReportEntryData(value: unknown): value is CommandReportEntryData {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<CommandReportEntryData>;
+  return typeof candidate.command === "string"
+    && candidate.command.trim() !== ""
+    && (candidate.level === "info" || candidate.level === "error")
+    && (candidate.outcome === "success" || candidate.outcome === "error")
+    && Array.isArray(candidate.lines)
+    && candidate.lines.every((line) => typeof line === "string");
+}
+
+/**
+ * @brief Builds the ordered per-operation outcome lines for one completed `req-references` run.
+ * @details Emits one machine-readable line per executed operation — terminal outcome, references-file regeneration result, guarded git-commit result, and post-run repository cleanliness — so the durable report states exactly which commands ran and with which outcome. Runtime is O(n) in path length. No external state is mutated.
+ * @param[in] executionResult {ReqReferencesCommandExecutionResult} Per-operation outcome facts of the completed run.
+ * @return {string[]} Ordered report lines starting with the terminal outcome.
+ * @satisfies REQ-436, REQ-437, REQ-438
+ */
+export function buildReqReferencesCommandReportLines(
+  executionResult: ReqReferencesCommandExecutionResult,
+): string[] {
+  const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
+  return [
+    `outcome: success`,
+    `references file ${referencesDisplayPath}: ${
+      executionResult.referencesChanged ? "updated" : "already matched the generated content"
+    }`,
+    `git commit: ${
+      executionResult.commitCreated
+        ? `created "${executionResult.commitMessage}"`
+        : "skipped (references content matched HEAD)"
+    }`,
+    "repository: clean after run",
+  ];
+}
+
+/**
+ * @brief Builds the durable report entry payload for one completed `req-references` run.
+ * @details Pairs the invokable command name with the per-operation outcome lines and the `success` outcome. Runtime is O(n) in report-line count. No external state is mutated.
+ * @param[in] executionResult {ReqReferencesCommandExecutionResult} Per-operation outcome facts of the completed run.
+ * @return {CommandReportEntryData} Report entry payload for session persistence.
+ * @satisfies REQ-436, REQ-437, REQ-438
+ */
+export function buildReqReferencesCommandReportEntryData(
+  executionResult: ReqReferencesCommandExecutionResult,
+): CommandReportEntryData {
+  return {
+    command: "req-references",
+    level: "info",
+    outcome: "success",
+    lines: buildReqReferencesCommandReportLines(executionResult),
+  };
+}
+
+/**
+ * @brief Builds the durable report entry payload for one failed non-agentic command run.
+ * @details Records the invokable command name, the `error` outcome, and the surfaced failure diagnostic so failed runs keep their outcome evidence in the transcript. Runtime is O(n) in message length. No external state is mutated.
+ * @param[in] command {string} Invokable slash-command name that failed.
+ * @param[in] errorMessage {string} Surfaced failure diagnostic.
+ * @return {CommandReportEntryData} Report entry payload for session persistence.
+ */
+export function buildCommandReportErrorEntryData(
+  command: string,
+  errorMessage: string,
+): CommandReportEntryData {
+  return {
+    command,
+    level: "error",
+    outcome: "error",
+    lines: [`outcome: error`, `error: ${errorMessage}`],
+  };
+}
+
+/**
+ * @brief Appends one durable command report entry to the active session when the host supports custom entries.
+ * @details Probes the optional `pi.appendEntry(...)` surface before use so legacy hosts and offline harnesses without custom-entry support skip persistence silently; supported hosts persist the payload as a `custom` session entry that survives session restore while remaining excluded from LLM context. Runtime is O(1) plus delegated session-entry persistence. Side effects include session-file entry persistence on supported hosts.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in] data {CommandReportEntryData} Report entry payload to persist.
+ * @return {boolean} `true` when the entry was appended; `false` when the host lacks the custom-entry surface.
+ */
+export function appendCommandReportEntry(pi: ExtensionAPI, data: CommandReportEntryData): boolean {
+  const registrar = pi as ExtensionAPI & CommandReportEntryRegistrar;
+  if (typeof registrar.appendEntry !== "function") {
+    return false;
+  }
+  registrar.appendEntry(COMMAND_REPORT_ENTRY_TYPE, data);
+  return true;
+}
+
+/**
+ * @brief Renders one durable command report entry as a transcript component.
+ * @details Maps the report payload into a themed multi-line `Text` — header colored `error` for failed runs and `accent` otherwise, body lines colored `error` for failed runs and `muted` otherwise — and returns `undefined` for malformed payloads so the host transcript skips undisplayable entries. Runtime is O(n) in aggregate report-line length. No external state is mutated.
+ * @param[in] entry {CustomEntry<CommandReportEntryData>} Persisted custom report entry.
+ * @param[in] _options {EntryRenderOptions} Host render options; retained for renderer-signature compatibility.
+ * @param[in] theme {Theme} Active pi theme used for color tokens.
+ * @return {Component | undefined} Transcript component, or `undefined` when the payload is malformed.
+ */
+function renderCommandReportEntry(
+  entry: CustomEntry<CommandReportEntryData>,
+  _options: EntryRenderOptions,
+  theme: Theme,
+): Component | undefined {
+  if (!isCommandReportEntryData(entry.data)) {
+    return undefined;
+  }
+  const data = entry.data;
+  const isError = data.level === "error";
+  const headerColor = isError ? "error" : "accent";
+  const bodyColor = isError ? "error" : "muted";
+  const header = theme.fg(headerColor, `pi-usereq ${data.command}: execution report`);
+  const body = data.lines.map((line) => theme.fg(bodyColor, line)).join("\n");
+  return new Text(`${header}\n${body}`, 1, 0);
+}
+
+/**
+ * @brief Registers the durable command report transcript renderer when the host supports entry rendering.
+ * @details Probes the optional `pi.registerEntryRenderer(...)` surface before use so legacy hosts and offline harnesses without custom-entry rendering skip registration silently; supported hosts bind the renderer for `pi-usereq.command-report` entries so appended reports render in the live transcript and re-render after every session restore. Runtime is O(1). Side effects include entry-renderer registration on supported hosts.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @return {void} No return value.
+ */
+export function registerCommandReportEntryRenderer(pi: ExtensionAPI): void {
+  const registrar = pi as ExtensionAPI & CommandReportEntryRegistrar;
+  if (typeof registrar.registerEntryRenderer !== "function") {
+    return;
+  }
+  registrar.registerEntryRenderer(COMMAND_REPORT_ENTRY_TYPE, renderCommandReportEntry);
+}

package/src/core/notification-replay.ts

@@ -0,0 +1,112 @@
+/**
+ * @file
+ * @brief Persists deferred UI notifications across session rebinding for later replay.
+ * @details Stores non-agentic command-output notifications whose stale-context-safe delivery failed on one `globalThis` queue because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload` while the hosting process persists across those operations, so undeliverable payloads survive until a later `session_start` restores a live UI context. Runtime is O(1) per operation. Side effects are limited to process-scoped state mutation; no local or global configuration file is ever written.
+ */
+
+/**
+ * @brief Enumerates the `session_start` reasons that trigger deferred-notification replay.
+ * @details Covers the session-restoration boundaries where pi rebuilt the TUI and invalidated prior UI contexts: `new`, `resume`, `reload`, and `fork`. The `startup` reason starts one fresh host process whose process-scoped queue is empty by construction, so it is excluded from replay. Lookup complexity is O(1).
+ */
+const DEFERRED_NOTIFICATION_REPLAY_SESSION_START_REASONS = new Set([
+  "new",
+  "resume",
+  "reload",
+  "fork",
+]);
+
+/**
+ * @brief Describes one deferred notification queued for later replay.
+ * @details Pairs the exact notification message text with its original severity so the replayed delivery preserves the deferred payload without reparsing or reconstruction. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface DeferredNotificationRecord {
+  message: string;
+  level: "info" | "error";
+}
+
+/**
+ * @brief Defines the global property used for deferred-notification replay persistence.
+ * @details The property lives on `globalThis` because pi tears down and reloads extension modules on session switches while the host process persists, so the queue survives `/new`, `/resume`, `/fork`, `/reload`, and `req-reset` session restoration. Access complexity is O(1).
+ */
+const PI_USEREQ_NOTIFICATION_REPLAY_KEY = "__piUsereqDeferredNotificationReplay";
+
+/**
+ * @brief Describes the process-scoped deferred-notification replay state persisted across extension rebinds.
+ * @details Stores the ordered queue of undelivered notification payloads so a later `session_start` on one restored UI context can redeliver exactly the evidence that stale contexts dropped. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-439
+ */
+interface ProcessScopedNotificationReplayStore {
+  queue: DeferredNotificationRecord[];
+}
+
+/**
+ * @brief Returns the process-scoped deferred-notification replay store.
+ * @details Lazily initializes one `globalThis` record holding an empty queue so session rebinds reuse the accumulated deferred payloads instead of resetting them. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {ProcessScopedNotificationReplayStore} Mutable process-scoped replay store.
+ * @satisfies REQ-439
+ */
+function getProcessScopedNotificationReplayStore(): ProcessScopedNotificationReplayStore {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqDeferredNotificationReplay?: ProcessScopedNotificationReplayStore;
+  };
+  globalState[PI_USEREQ_NOTIFICATION_REPLAY_KEY] ??= { queue: [] };
+  return globalState[PI_USEREQ_NOTIFICATION_REPLAY_KEY]!;
+}
+
+/**
+ * @brief Queues one undeliverable notification for later replay.
+ * @details Appends the exact message plus severity to the tail of the process-scoped replay queue so the payload survives extension rebinding and can be redelivered on the next eligible `session_start`. Already-delivered notifications are never enqueued by contract, so replay can never duplicate them. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @param[in] message {string} Exact notification message text whose stale-context delivery failed.
+ * @param[in] level {"info" | "error"} Original notification severity preserved for the replayed delivery.
+ * @return {void} No return value.
+ * @satisfies REQ-439, REQ-442
+ */
+export function enqueueDeferredNotification(message: string, level: "info" | "error"): void {
+  getProcessScopedNotificationReplayStore().queue.push({ message, level });
+}
+
+/**
+ * @brief Returns a snapshot of the queued deferred notifications.
+ * @details Copies the queued records into one detached array so callers can inspect pending replay payloads without mutating the store. Runtime is O(n) in queued-record count. No external state is mutated.
+ * @return {DeferredNotificationRecord[]} Detached copy of the queued records in enqueue order.
+ * @satisfies REQ-439
+ */
+export function readDeferredNotifications(): DeferredNotificationRecord[] {
+  return [...getProcessScopedNotificationReplayStore().queue];
+}
+
+/**
+ * @brief Atomically removes and returns every queued deferred notification.
+ * @details Empties the process-scoped queue and returns the removed records in enqueue order so replay delivery owns each payload exactly once; payloads whose replay delivery fails stale again are re-enqueued by the deferred-delivery helper instead of remaining in this drain result. Runtime is O(n) in queued-record count. Side effect: clears process-scoped state.
+ * @return {DeferredNotificationRecord[]} Removed records in enqueue order.
+ * @satisfies REQ-440
+ */
+export function drainDeferredNotifications(): DeferredNotificationRecord[] {
+  const store = getProcessScopedNotificationReplayStore();
+  const drained = store.queue;
+  store.queue = [];
+  return drained;
+}
+
+/**
+ * @brief Clears every queued deferred notification.
+ * @details Resets the process-scoped queue to empty so stale deferred payloads never reach later sessions after explicit cleanup. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @return {void} No return value.
+ * @satisfies REQ-439
+ */
+export function clearDeferredNotifications(): void {
+  getProcessScopedNotificationReplayStore().queue = [];
+}
+
+/**
+ * @brief Tests whether one `session_start` event must trigger deferred-notification replay.
+ * @details Reads the loosely-typed `reason` field from the session-start payload and accepts exactly the documented restoration reasons `new`, `resume`, `reload`, and `fork`, excluding `startup` because one fresh host process starts with an empty process-scoped queue. Missing or unknown reasons degrade to `false`. Runtime is O(1). No external state is mutated.
+ * @param[in] event {unknown} Session-start payload forwarded by the pi lifecycle wrapper.
+ * @return {boolean} `true` when deferred notifications must be replayed for this session-start reason.
+ * @satisfies REQ-440
+ */
+export function shouldReplayDeferredNotificationsOnSessionStart(event: unknown): boolean {
+  const reason = (event as { reason?: unknown } | undefined)?.reason;
+  return typeof reason === "string"
+    && DEFERRED_NOTIFICATION_REPLAY_SESSION_START_REASONS.has(reason);
+}

package/src/index.ts

@@ -168,7 +168,18 @@ import {
   writePersistedPromptCommandRuntimeState,
   type PersistedPromptCommandRuntimeApi,
 } from "./core/prompt-command-state.js";
+import {
+  drainDeferredNotifications,
+  enqueueDeferredNotification,
+  shouldReplayDeferredNotificationsOnSessionStart,
+} from "./core/notification-replay.js";
 import { ensureBundledResourcesAccessible, readBundledPromptDescription } from "./core/resources.js";
+import {
+  appendCommandReportEntry,
+  buildCommandReportErrorEntryData,
+  buildReqReferencesCommandReportEntryData,
+  registerCommandReportEntryRenderer,
+} from "./core/command-report-entry.js";
 import { ReqError } from "./core/errors.js";
 import {
   PI_USEREQ_STATUS_HOOK_NAMES,
@@ -1199,13 +1210,13 @@ function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusCo
 }
 
 /**
- * @brief Delivers one best-effort UI notification without failing on stale replacement contexts.
- * @details Attempts to use the supplied extension context for UI notification delivery and suppresses the documented stale-extension-context runtime error raised after session replacement, because prompt-orchestration closure can outlive the context that initiated the switch. Runtime is O(n) in message length. Side effects are limited to user notification delivery when the context is still active.
+ * @brief Delivers one best-effort UI notification, deferring the payload when the context is stale.
+ * @details Attempts to use the supplied extension context for UI notification delivery; when no context is available or pi raises the documented stale-extension-context error because the context was invalidated by session replacement or reload, the exact message plus severity is enqueued into the process-scoped deferred-notification replay store so one later eligible `session_start` can redeliver it on the restored context instead of losing the evidence. The payload is enqueued only on failed delivery, so already-delivered notifications are never replayed. Runtime is O(1). Side effects are limited to user notification delivery when the context is still active and process-scoped queue mutation when delivery fails.
  * @param[in] ctx {ExtensionContext | ExtensionCommandContext | undefined} Candidate UI context.
  * @param[in] message {string} Notification message.
  * @param[in] level {"info" | "error"} Notification severity.
- * @return {boolean} `true` when the notification was delivered and `false` when the context was already stale.
- * @satisfies REQ-280
+ * @return {boolean} `true` when the notification was delivered and `false` when delivery failed and the payload was deferred for replay.
+ * @satisfies REQ-280, REQ-439, REQ-442
  */
 function notifyContextSafely(
   ctx: (ExtensionContext | ExtensionCommandContext) | undefined,
@@ -1213,6 +1224,7 @@ function notifyContextSafely(
   level: "info" | "error",
 ): boolean {
   if (ctx === undefined) {
+    enqueueDeferredNotification(message, level);
     return false;
   }
   try {
@@ -1220,6 +1232,7 @@ function notifyContextSafely(
     return true;
   } catch (error) {
     if (isStaleExtensionContextError(error)) {
+      enqueueDeferredNotification(message, level);
       return false;
     }
     throw error;
@@ -1232,7 +1245,7 @@ function notifyContextSafely(
  * @param[in] statusController {PiUsereqStatusController} Mutable status controller supplying the latest normalized context-usage snapshot.
  * @param[in] ctx {(ExtensionContext | ExtensionCommandContext) | undefined} Candidate UI context for notification delivery.
  * @return {void} No return value.
- * @satisfies REQ-360, REQ-361, REQ-362, REQ-363, REQ-364, REQ-365
+ * @satisfies REQ-360, REQ-361, REQ-362, REQ-363, REQ-364, REQ-365, REQ-439, REQ-441
  */
 function notifyContextRetentionReminder(
   statusController: PiUsereqStatusController,
@@ -1494,7 +1507,7 @@ async function finalizeMatchedPromptSuccess(
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425, REQ-440
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -1529,6 +1542,12 @@ async function handleExtensionStatusEvent(
         "warning",
       );
     }
+    if (shouldReplayDeferredNotificationsOnSessionStart(event)) {
+      const deferredNotifications = drainDeferredNotifications();
+      for (const deferredNotification of deferredNotifications) {
+        notifyContextSafely(ctx, deferredNotification.message, deferredNotification.level);
+      }
+    }
   }
   if (hookName === "before_agent_start") {
     const requestForActivation = activePromptRequest ?? pendingPromptRequest;
@@ -3409,7 +3428,7 @@ function resolveReqResetPromptRequest(
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313
+ * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313, REQ-441
  */
 function registerReqResetCommand(
   pi: ExtensionAPI,
@@ -3480,11 +3499,11 @@ function registerReqResetCommand(
 
 /**
  * @brief Registers the specialized `req-references` slash command.
- * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, and emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, and user notifications.
+ * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, appends one durable `pi-usereq.command-report` session entry recording the executed operations with their outcomes so the report renders in the transcript and survives session restore, and emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, session-entry persistence, and user notifications.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-437, REQ-438
+ * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-436, REQ-437, REQ-438, REQ-441
  */
 function registerReqReferencesCommand(
   pi: ExtensionAPI,
@@ -3513,19 +3532,23 @@ function registerReqReferencesCommand(
         const executionResult = executeReqReferencesCommandExecution(executionPlan, config);
         setPiUsereqWorkflowState(statusController, "idle", ctx);
         const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
-        ctx.ui.notify(
+        appendCommandReportEntry(pi, buildReqReferencesCommandReportEntryData(executionResult));
+        notifyContextSafely(
+          ctx,
           executionResult.referencesChanged
             ? `req-references: Updated ${referencesDisplayPath}.`
             : `req-references: ${referencesDisplayPath} already matches the generated references content; no file update was needed.`,
           "info",
         );
-        ctx.ui.notify(
+        notifyContextSafely(
+          ctx,
           executionResult.commitCreated
             ? `req-references: Created commit ${executionResult.commitMessage}`
             : "req-references: Skipped the git commit because the references content already matched HEAD.",
           "info",
         );
-        ctx.ui.notify(
+        notifyContextSafely(
+          ctx,
           executionResult.referencesChanged && executionResult.commitCreated
             ? `SUCCESS: Updated ${referencesDisplayPath} and committed changes.`
             : `SUCCESS: req-references completed with a clean repository (${executionResult.referencesChanged ? "references updated" : "references unchanged"}; ${executionResult.commitCreated ? "commit created" : "commit skipped"}).`,
@@ -3537,7 +3560,8 @@ function registerReqReferencesCommand(
         statusController.state.activePromptRequest = undefined;
         setPiUsereqWorkflowState(statusController, "error", ctx);
         const message = error instanceof Error ? error.message : String(error);
-        ctx.ui.notify(message, "error");
+        appendCommandReportEntry(pi, buildCommandReportErrorEntryData("req-references", message));
+        notifyContextSafely(ctx, message, "error");
         throw error;
       }
     },
@@ -5345,13 +5369,14 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
+ * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, registers the durable `pi-usereq.command-report` transcript entry renderer, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
  * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325, REQ-326, REQ-327
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   writePersistedPromptCommandRuntimeApi(pi as unknown as PersistedPromptCommandRuntimeApi);
+  registerCommandReportEntryRenderer(pi);
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
   try {