avtc-pi-featyard 1.1.0

package/src/shared/workflow-refs.ts

@@ -0,0 +1,253 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Orchestrator refs and closure-wrapping functions.
+ *
+ * Module-level refs that child modules need to access without creating
+ * circular imports back to the parent orchestrator.
+ *
+ * The parent orchestrator sets these refs during initialization.
+ * Child modules read them to access handler state.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { clearActiveFeatureEnv } from "../phases/env-sync.js";
+import { applyModelOverride, getLoopCountForPhase } from "../phases/phase-transitions.js";
+import type { SubstitutionResult } from "../prompts/skill-expansion.js";
+import * as skillExpansion from "../prompts/skill-expansion.js";
+import type { MutableRef } from "../shared/types.js";
+import type { IGuardrails } from "../shared/workflow-types.js";
+import { type FeatureSession, NO_ACTIVE_FEATURE_STATE } from "../state/feature-session.js";
+import {
+  clearFeatureStateCache,
+  DEFAULT_DIR,
+  type FeatureState,
+  stateFilePath as featureStateFilePath,
+} from "../state/feature-state.js";
+
+// Re-export SubstitutionResult for consumers
+export type { SubstitutionResult };
+
+/** Pass as `featureStateOverride` when no override is needed. */
+export const NO_FEATURE_STATE_OVERRIDE: FeatureState | null = null;
+/** Pass as `agentName` when no specific agent name is known. */
+export const NO_AGENT_NAME: string | null = null;
+
+/** Grouped refs for empty-loop tracking — all set together from compaction instance. */
+export interface EmptyLoopRefs {
+  getEmptyLoopsForSlug: (slug: string) => Record<string, number>;
+  incrementEmptyLoop: (slug: string, reviewerName: string) => void;
+  resetEmptyLoop: (slug: string, reviewerName: string) => void;
+  resetAllEmptyLoops: () => void;
+  isReviewerSkipped: (slug: string, reviewerName: string, threshold: number) => boolean;
+  getReviewerEmptyLoops: () => Record<string, Record<string, number>>;
+}
+
+/** Skill resolution ref — set from compaction instance. */
+export interface SkillResolutionRef {
+  getExpectedSkill: () => string | null;
+}
+
+// --- Module-level refs ---
+
+/** Handler reference — set by parent orchestrator during init */
+let _handlerRef: FeatureSession | null = null;
+
+/** Empty loop tracking refs — set as a group from compaction instance */
+let _emptyLoops: EmptyLoopRefs | null = null;
+
+/** Skill resolution ref — set from compaction instance */
+let _skillResolution: SkillResolutionRef | null = null;
+
+/** Agent state tracking ref */
+const _agentJustFinishedRef: MutableRef<boolean> = { value: false };
+
+/** Guardrails instance ref */
+let _guardrailsRef: IGuardrails | null = null;
+/** PhaseReady instance ref — for resetTracking access (test cleanup / fy:reset) */
+let _phaseReadyRef: import("../shared/workflow-types.js").IPhaseReady | null = null;
+let _getAutoAgentCallbackRef:
+  | (() => import("../kanban/auto-agent/auto-agent-state-machine.js").AutoAgentCallback | null)
+  | null = null;
+
+// --- Ref setters (called by parent orchestrator) ---
+
+export function setHandlerRef(handler: FeatureSession | null): void {
+  _handlerRef = handler;
+}
+
+/** Set empty-loop tracking refs from the compaction instance. */
+export function setEmptyLoopRefs(refs: EmptyLoopRefs | null): void {
+  _emptyLoops = refs;
+}
+
+/** Set skill resolution ref from the compaction instance. */
+export function setSkillResolutionRef(refs: SkillResolutionRef | null): void {
+  _skillResolution = refs;
+}
+
+export function setGuardrailsRef(ref: IGuardrails | null): void {
+  _guardrailsRef = ref;
+}
+
+export function setPhaseReadyRef(ref: import("../shared/workflow-types.js").IPhaseReady | null): void {
+  _phaseReadyRef = ref;
+}
+
+export function getPhaseReadyRef(): import("../shared/workflow-types.js").IPhaseReady | null {
+  return _phaseReadyRef;
+}
+
+export function setAutoAgentCallbackRef(
+  ref: (() => import("../kanban/auto-agent/auto-agent-state-machine.js").AutoAgentCallback | null) | null,
+): void {
+  _getAutoAgentCallbackRef = ref;
+}
+
+// --- Ref getters ---
+
+export function getHandlerRef(): FeatureSession | null {
+  return _handlerRef;
+}
+
+export function getActiveFeatureSlug(): string | null {
+  return _handlerRef?.getActiveFeatureSlug() ?? null;
+}
+
+export function getAgentJustFinishedRef(): MutableRef<boolean> {
+  return _agentJustFinishedRef;
+}
+
+export function getGuardrailsRef(): IGuardrails | null {
+  return _guardrailsRef;
+}
+
+// --- Test-only accessors ---
+
+/** @internal Returns the expected skill based on current workflow state */
+export function _getExpectedSkill(): string | null {
+  return _skillResolution?.getExpectedSkill() ?? null;
+}
+
+/** @internal Increment empty loop count for a reviewer */
+export function _incrementEmptyLoop(slug: string, reviewerName: string): void {
+  _emptyLoops?.incrementEmptyLoop(slug, reviewerName);
+}
+
+/** @internal Reset empty loop count for a specific reviewer */
+export function _resetEmptyLoop(slug: string, reviewerName: string): void {
+  _emptyLoops?.resetEmptyLoop(slug, reviewerName);
+}
+
+/** @internal Get empty loop counts for a feature slug */
+export function _getEmptyLoopsForSlug(slug: string): Record<string, number> {
+  return _emptyLoops?.getEmptyLoopsForSlug(slug) ?? {};
+}
+
+/** @internal Reset all empty loop tracking */
+export function _resetAllEmptyLoops(): void {
+  _emptyLoops?.resetAllEmptyLoops();
+}
+
+/** @internal Check if a reviewer should be skipped based on threshold */
+export function _isReviewerSkipped(slug: string, reviewerName: string, threshold: number): boolean {
+  return _emptyLoops?.isReviewerSkipped(slug, reviewerName, threshold) ?? false;
+}
+
+/** @internal Get all empty loop counts (for template substitution) */
+export function _getReviewerEmptyLoops(): Record<string, Record<string, number>> {
+  return _emptyLoops?.getReviewerEmptyLoops() ?? {};
+}
+
+/** @internal Get state file path for current active feature */
+export function getStateFilePath(): string | null {
+  const slug = getActiveFeatureSlug();
+  if (slug) {
+    return featureStateFilePath(slug, DEFAULT_DIR);
+  }
+  return null;
+}
+
+/** @internal Reset module-level state for testing */
+export function _resetFeatureState(): void {
+  _handlerRef?.setActiveFeatureState(NO_ACTIVE_FEATURE_STATE);
+  if (globalThis.__piWorkflowMonitor) {
+    globalThis.__piWorkflowMonitor.workflowInitiatedNewSession = undefined;
+    globalThis.__piWorkflowMonitor.newSessionMessage = undefined;
+    globalThis.__piWorkflowMonitor.modelOverrideRefs = { pi: undefined };
+    // Clear the background-archive sweep interval. _resetFeatureState is the per-test cleanup
+    // most test files invoke in afterEach; with isolate:false a 24h setInterval left on the bridge
+    // by one activation keeps the event loop alive and shifts timing for later tests (exposing
+    // pre-existing ordering races). Clearing it here ensures no activation leaks a timer across
+    // tests. (This function is test-only — no production caller)
+    if (globalThis.__piWorkflowMonitor.archiveTimer) {
+      clearInterval(globalThis.__piWorkflowMonitor.archiveTimer);
+      globalThis.__piWorkflowMonitor.archiveTimer = undefined;
+    }
+  }
+  resetRefs();
+  _guardrailsRef?.resetTracking();
+  _phaseReadyRef?.resetTracking();
+  clearActiveFeatureEnv();
+  clearFeatureStateCache();
+}
+
+// --- Closure-wrapping functions ---
+
+/** Substitute template variables in text using handler and empty-loops state */
+export function substituteTemplates(
+  text: string,
+  featureStateOverride: FeatureState | null,
+  agentName: string | null,
+): SubstitutionResult {
+  return skillExpansion.substituteTemplates(
+    text,
+    _handlerRef,
+    _emptyLoops?.getEmptyLoopsForSlug ?? null,
+    featureStateOverride,
+    _getAutoAgentCallbackRef ?? null,
+    agentName,
+  );
+}
+
+/** Expand skill command in text using handler and empty-loops state */
+export function expandSkillCommand(
+  text: string,
+  featureStateOverride: FeatureState | null,
+  agentName: string | null,
+): string {
+  return skillExpansion.expandSkillCommand(
+    text,
+    _handlerRef,
+    _emptyLoops?.getEmptyLoopsForSlug ?? null,
+    featureStateOverride,
+    _getAutoAgentCallbackRef ?? null,
+    agentName,
+  );
+}
+
+/** Get the review loop count for a given phase from feature state */
+export function resolveLoopIndex(stage: string): number {
+  return getLoopCountForPhase(_handlerRef?.getActiveFeatureState() ?? null, stage);
+}
+
+/** Apply model override for a given phase, resolving review loop index automatically */
+export async function applyModelOverrideForPhase(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  stage: string,
+): Promise<void> {
+  await applyModelOverride(pi, ctx, stage, resolveLoopIndex(stage));
+}
+
+/** Reset module-level refs (called by _resetFeatureState and tests) */
+export function resetRefs(): void {
+  _handlerRef = null;
+  _emptyLoops = null;
+  _skillResolution = null;
+  _guardrailsRef = null;
+  _phaseReadyRef = null;
+  _getAutoAgentCallbackRef = null;
+  _agentJustFinishedRef.value = false;
+}

package/src/shared/workflow-types.ts

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * DI interfaces for workflow-monitor module decomposition.
+ *
+ * Each module declares its cross-module dependencies as interfaces.
+ * The orchestrator creates modules in topological dependency order and injects them.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import type { getSettings } from "../settings/settings-ui.js";
+import type { FeatureSession } from "../state/feature-session.js";
+
+/** Shared context passed to all modules. */
+export interface ModuleContext {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+}
+
+/** Common phase-transition dependencies shared by PhaseReadyDeps and WorkflowCommandDeps (pi + handler + model override + review→UAT transition). */
+export interface WorkflowTransitionDeps {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>;
+  handleReviewToUatTransition: (
+    ctx: ExtensionContext,
+    slug: string,
+    settings: ReturnType<typeof getSettings>,
+    // Review-report context for the worth-notes merge. Non-null on the after-review path
+    // so the report + handoff + worth-notes pointer merge into ONE notify; null at the
+    // off/after-finish paths and non-loop call sites (no merge). Required (no-optional-params).
+    reportCtx: { report: string | null; level: "info" | "warning"; pointer: string | null } | null,
+  ) => Promise<void>;
+}
+
+/**
+ * Compaction module — tracks empty loops, agent-finished state, and reviewer skip logic.
+ * Written to by Guardrails (incrementEmptyLoop), PhaseReady (resetEmptyLoop, isReviewerSkipped),
+ * and AgentLifecycle (setAgentFinished). Read by SessionLifecycle (resetTracking).
+ */
+export interface ICompaction {
+  setAgentFinished(value: boolean): void;
+  incrementEmptyLoop(slug: string, reviewer: string): void;
+  resetEmptyLoop(slug: string, reviewer: string): void;
+  isReviewerSkipped(slug: string, reviewer: string, threshold: number): boolean;
+  resetTracking(): void;
+  /** Get empty loops for a specific slug (used by substituteTemplates) */
+  getEmptyLoopsForSlug(slug: string): Record<string, number>;
+  /** Reset all empty loops across all slugs */
+  resetAllEmptyLoops(): void;
+  /** Get all reviewer empty loops (used by tests and debug) */
+  getReviewerEmptyLoops(): Record<string, Record<string, number>>;
+  /** Resolve expected skill for current workflow phase */
+  getExpectedSkill(): string | null;
+  /**
+   * Recover from a FAILED compact: the agent's turn was aborted by ctx.compact(), so
+   * deliver the full follow-up resume (reusing the session_compact assembly — new-phase
+   * skill / task confirmation / todo details) + clear the re-entrancy guard. Injected into
+   * triggerContextCompact callers as the ctx.compact({onError}) handler.
+   */
+  recoverCompactFailure(): void;
+  /**
+   * session_compact handler body: clear any pending deferred follow-up, then deliver
+   * the stored follow-up for the compaction reason (or delegate to the subagent
+   * compact path). Called by events/session/session-compact.ts.
+   */
+  onSessionCompact(event: { reason: "manual" | "threshold" | "overflow" }): Promise<void>;
+  /**
+   * session_shutdown handler body: clear any pending deferred follow-up so a deferred
+   * inject never fires into a dead session. Called by events/session/session-shutdown.ts.
+   */
+  onSessionShutdown(): void;
+}
+
+/**
+ * Guardrails module — handles tool_call and tool_result guardrail checks,
+ * tracks verify-tests-passed state, pending violations, and branch tracking.
+ * Consumed by PhaseReady, SessionLifecycle, and the orchestrator.
+ */
+/** Per-tool tool_result advisory: warnings to prepend to the tool's output
+ * (TDD/process/pre-commit violations). */
+export interface ToolResultAdvisory {
+  warnings: string[];
+  /** Workflow state changed — the router persists + refreshes the widget. */
+  changed?: boolean;
+}
+
+/** Structural shape of a bash tool_result event (input.command + details.exitCode).
+ * The SDK exports only the ToolResultEvent union, not the bash-specific member. */
+export interface BashResultEvent {
+  input: Record<string, unknown>;
+  content: ReadonlyArray<{ type: string; text?: string }>;
+  details: { exitCode?: number } | unknown;
+}
+
+/** Per-tool tool_call decision: block the call with a reason, or allow; optionally
+ * signal that workflow state changed (router persists + refreshes the widget). */
+export interface ToolCallDecision {
+  /** Block the tool call with this reason; undefined/null to allow. */
+  block?: string;
+  /** Workflow state changed — the router persists + refreshes the widget. */
+  changed?: boolean;
+}
+
+export interface IGuardrails {
+  /** bash tool_call: fy-force-add block, publish gate, pre-commit discipline. */
+  onBashCall(event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallDecision>;
+  /** write/edit tool_call: TDD check, verify flag reset, phase-write-restriction, doc activation. */
+  onWriteEditCall(event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallDecision>;
+  /** phase_ready tool_call: subagent + implement-phase gating. */
+  onPhaseReadyCall(event: ToolCallEvent): ToolCallDecision;
+  /** task_ready_advance tool_call: subagent gating. */
+  onTaskReadyAdvanceCall(event: ToolCallEvent): ToolCallDecision;
+  /** read tool_result: log + record investigation. */
+  onReadResult(event: ToolResultEvent): ToolResultAdvisory;
+  /** write/edit tool_result: pending TDD violations + process warnings. */
+  onWriteEditResult(toolCallId: string): ToolResultAdvisory;
+  /** bash tool_result: record test outcome + verify flag, pending pre-commit warning. */
+  onBashResult(event: BashResultEvent, toolCallId: string): ToolResultAdvisory;
+  setVerifyTestsPassed(passed: boolean): void;
+  isVerifyTestsPassed(): boolean;
+  resetTracking(): void;
+  /** Complete a code-review loop from a phase_ready({issuesFound, cannotFix}) call:
+   *  record review history, track reviewer empty loops, then drive the loop
+   *  decision + (UAT/finish) transition. The counts come from the fy-review
+   *  skill. */
+  completeCodeReviewLoop(
+    ctx: ExtensionContext,
+    issuesFound: number,
+    cannotFixIssues: number,
+    falsePositives: number,
+  ): Promise<void>;
+}
+
+/**
+ * PhaseReady module — phase_ready tool handler.
+ * Design doc specifies this interface for DI consistency.
+ * Called by SessionLifecycle (resetTracking on fy:reset).
+ */
+export interface IPhaseReady {
+  resetTracking(): void;
+}
+
+/**
+ * SessionLifecycle module — the bodies of the session_start (state branch) and
+ * session_tree handlers as callable methods, plus the shared workflow reset.
+ * Pure domain logic (no pi.on registration); the events/session/ routers call these.
+ */
+export interface ISessionLifecycle {
+  /** session_start handler body (state branch). */
+  onSessionStart(event: unknown, ctx: ExtensionContext): Promise<void>;
+  /** session_tree handler body. */
+  onSessionTree(ctx: ExtensionContext): Promise<void>;
+  /** Shared reset logic used by /fy:reset, /resume session_start, and user-initiated /new. */
+  performWorkflowReset(): void;
+}
+
+/** Re-export ViolationType from the closure scope — used by escalation tracking. */
+export type ViolationType = "phase-write-restriction" | "tdd-write-order";
+
+/**
+ * AgentLifecycle module — the bodies of the agent_start and agent_end handlers as
+ * callable methods. agent_start re-arms the finish guardrail + signals a fresh
+ * agent turn; agent_end clears the guardrail, resets the phase_ready guard, flags
+ * the agent finished (for compaction), and notifies the auto-agent on non-retryable
+ * execution-phase errors. Pure domain logic (no pi.on registration); the
+ * events/agent/ routers call these.
+ */
+export interface IAgentLifecycle {
+  /** agent_start handler body. */
+  onAgentStart(): Promise<void>;
+  /** agent_end handler body. */
+  onAgentEnd(
+    event: { messages?: ReadonlyArray<{ role: string; stopReason?: string; errorMessage?: string }> },
+    ctx: ExtensionContext,
+  ): Promise<void>;
+  /** agent_settled handler body — pi will not continue automatically. */
+  onAgentSettled(): Promise<void>;
+}

package/src/snippets/vendored/subscribe-to-dialog-coordinator.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Dialog coordinator forwarding — drop-in integration with avtc-pi-ui-components DialogCoordinator.
+ *
+ * Copy this file into your extension's src/snippets/vendored/ directory, then:
+ *   1. Call subscribeToDialogCoordinator(pi) in your extension entry point
+ *   2. Call withCoordinator(fn) around any blocking ctx.ui.* call
+ *
+ * If avtc-pi-ui-components is not installed or the coordinator event never fires,
+ * all functions pass through (no-op).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared VALUE, stored on globalThis so it survives jiti `moduleCache: false` re-imports
+ * (which create distinct module instances and would otherwise split a module-level
+ * `let` between the setter in subscribeToDialogCoordinator() and the getter in
+ * withCoordinator()).
+ *
+ * `coordinator` is idempotent across subscribers — there is one DialogCoordinator,
+ * so one object. Listener unsubs are NOT shared: each subscribeToDialogCoordinator()
+ * call owns its own local closure unsubs.
+ */
+interface DialogCoordinatorForwardingState {
+  coordinator: { enqueueOrShow<T>(fn: () => Promise<T>): Promise<T> } | null;
+}
+const STATE_KEY = "__piDialogCoordinatorForwarding";
+type GlobalWithState = typeof globalThis & { [STATE_KEY]?: DialogCoordinatorForwardingState };
+function _state(): DialogCoordinatorForwardingState {
+  const g = globalThis as GlobalWithState;
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = { coordinator: null };
+  }
+  const state = g[STATE_KEY];
+  return state;
+}
+
+/**
+ * Reset module state — called during test cleanup.
+ */
+export function _resetState(): void {
+  _state().coordinator = null;
+}
+
+/**
+ * Subscribe to dialog-coordinator:ready event emitted by avtc-pi-ui-components.
+ * Call once per extension entry point.
+ *
+ * Reload-safe: session_shutdown fires before reload, cleaning all listeners.
+ */
+export function subscribeToDialogCoordinator(pi: ExtensionAPI): void {
+  if (!pi.events) return; // graceful no-op for incomplete test mocks
+
+  const unsubs: Array<() => void> = [];
+
+  // Listen for dialog-coordinator:ready (emitted by avtc-pi-ui-components in session_start)
+  unsubs.push(
+    pi.events.on("dialog-coordinator:ready", (data: unknown) => {
+      const api = data as {
+        coordinator?: { enqueueOrShow<T>(fn: () => Promise<T>): Promise<T> };
+      };
+      if (api?.coordinator && typeof api.coordinator.enqueueOrShow === "function") {
+        _state().coordinator = api.coordinator;
+      }
+    }),
+  );
+
+  // Reset on session shutdown (fires before reload) — clean ONLY this subscriber's
+  // EventBus listener (pi.on listeners are torn down by pi), then clear shared value
+  // (hygiene; provider re-emits on next session_start).
+  pi.on("session_shutdown", () => {
+    for (const unsub of unsubs) {
+      if (typeof unsub === "function") unsub();
+    }
+    unsubs.length = 0;
+    _state().coordinator = null;
+  });
+}
+
+/**
+ * Wrap an async UI call with dialog coordination.
+ * The call is serialized through the shared queue: if another dialog is currently
+ * showing, this call waits and is shown only after the active dialog resolves.
+ * If no coordinator is installed, the call is executed immediately (no-op).
+ *
+ * @param fn - Async function that blocks on user input (e.g. ctx.ui.select, ctx.ui.custom)
+ * @returns A promise that resolves with whatever `fn` returns.
+ */
+export async function withCoordinator<T>(fn: () => Promise<T>): Promise<T> {
+  const coordinator = _state().coordinator;
+  if (coordinator) {
+    return coordinator.enqueueOrShow(fn);
+  }
+  return fn();
+}

package/src/snippets/vendored/subscribe-to-notifications.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Notification forwarding — drop-in integration with pi-notification.
+ *
+ * Copy this file into your extension's src/snippets/vendored/ directory, then:
+ *   1. Call subscribeToNotificationApi(pi) in your extension entry point
+ *   2. Call requestAttention(source, detail) before any blocking UI call
+ *   3. Call the returned cancel function when unblocked
+ *
+ * If pi-notification is not installed, all functions are no-ops.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared VALUES, stored on globalThis so they survive jiti `moduleCache: false` re-imports
+ * (which create distinct module instances and would otherwise split module-level `let`
+ * variables between the setter in extension.ts and the getter in select-with-note.ts).
+ *
+ * Only idempotent VALUES live here — there is one provider (so one requestAttention fn)
+ * and one active session (so one lastMessage), observed identically by every
+ * subscriber. Listener unsubs are NOT shared: each subscribeToNotificationApi() call
+ * owns its own local closure unsubs, so multiple subscribers (ui-components,
+ * ask-user-question, featyard) don't clobber each other's cleanup.
+ */
+interface NotificationForwardingState {
+  requestAttention: ((source: string, detail?: string) => (() => void) | undefined) | null;
+  lastMessage: string;
+}
+const STATE_KEY = "__piNotificationForwarding";
+type GlobalWithState = typeof globalThis & { [STATE_KEY]?: NotificationForwardingState };
+function _state(): NotificationForwardingState {
+  const g = globalThis as GlobalWithState;
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = { requestAttention: null, lastMessage: "" };
+  }
+  const state = g[STATE_KEY];
+  return state;
+}
+
+/**
+ * Extract the last assistant text from a message_end event.
+ * Handles string content and array content (filters to text blocks, takes last).
+ * Returns empty string if no suitable text found.
+ */
+type MessageContentBlock = { type: string; text?: string };
+
+export function extractLastAssistantText(event: {
+  message?: { role?: string; content?: string | MessageContentBlock[] };
+}): string {
+  if (event.message?.role !== "assistant") return "";
+
+  const content = event.message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const textBlocks = content.filter((b): b is MessageContentBlock & { type: "text" } => b.type === "text");
+    const last = textBlocks[textBlocks.length - 1];
+    if (last) {
+      return last.text ?? "";
+    }
+  }
+  return "";
+}
+
+/**
+ * Get the last captured assistant message text.
+ * Returns empty string if no message has been captured yet.
+ */
+export function getLastMessage(): string {
+  return _state().lastMessage;
+}
+
+/**
+ * Reset module state — called on session shutdown and during test cleanup.
+ * Clears shared values; listener cleanup is each subscriber's own responsibility
+ * (via its session_shutdown handler).
+ */
+export function _resetNotificationState(): void {
+  const s = _state();
+  s.lastMessage = "";
+  s.requestAttention = null;
+}
+
+/**
+ * Subscribe to pi-notification:ready event and message_end events.
+ * Call once per extension entry point (all will set the same shared reference).
+ *
+ * Reload-safe: session_shutdown fires before reload, cleaning all listeners.
+ */
+export function subscribeToNotificationApi(pi: ExtensionAPI): void {
+  const unsubs: Array<() => void> = [];
+
+  const unsub = pi.events.on("pi-notification:ready", (data: unknown) => {
+    const api = data as {
+      requestAttention?: (source: string, detail?: string) => (() => void) | undefined;
+    };
+    if (typeof api.requestAttention === "function" && api.requestAttention) {
+      _state().requestAttention = api.requestAttention;
+    }
+  });
+  unsubs.push(unsub);
+
+  // Capture last assistant message for notification context.
+  // Note: pi.on (extension lifecycle events) returns void — these listeners are torn down
+  // by pi when it discards the extension runner on reload/session-end, so no manual unsub.
+  if (typeof pi.on === "function") {
+    pi.on("message_end", (event: { message?: { role?: string; content?: string | MessageContentBlock[] } }) => {
+      const text = extractLastAssistantText(event);
+      if (text) _state().lastMessage = text;
+    });
+  }
+
+  // Reset on session shutdown (fires before reload) — clean ONLY this subscriber's
+  // EventBus listener (pi.on listeners are torn down by pi), then clear shared values
+  // (hygiene; provider re-emits on next session_start).
+  pi.on("session_shutdown", () => {
+    for (const unsub of unsubs) unsub();
+    unsubs.length = 0;
+    const s = _state();
+    s.lastMessage = "";
+    s.requestAttention = null;
+  });
+}
+
+/**
+ * Request attention before blocking on user input.
+ * Returns a cancel function, or undefined if pi-notification is not installed.
+ */
+export function requestAttention(source: string, detail: string): (() => void) | undefined {
+  return _state().requestAttention?.(source, detail);
+}
+
+/**
+ * Wrap an async UI call with requestAttention/cancelAttention.
+ * If pi-notification is not installed, just calls the function directly.
+ *
+ * @param source - Who is requesting attention (e.g. "permission", "ask_user_question")
+ * @param detail - Optional detail (e.g. tool name, question summary)
+ * @param fn - Async function that blocks on user input
+ */
+export async function withAttention<T>(source: string, detail: string, fn: () => Promise<T>): Promise<T> {
+  const cancelAttention = requestAttention(source, detail);
+  try {
+    return await fn();
+  } finally {
+    cancelAttention?.();
+  }
+}