@gotgenes/pi-subagents 16.2.1 → 16.2.2

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [16.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.1...pi-subagents-v16.2.2) (2026-06-15)
+
+
+### Documentation
+
+* **pi-subagents:** replace fork notice with upstream comparison ([513df4d](https://github.com/gotgenes/pi-packages/commit/513df4d6149178c5c8074cf07d8ad248c50d4c47))
+
 ## [16.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.0...pi-subagents-v16.2.1) (2026-06-15)
 
 

package/README.md

@@ -6,11 +6,8 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level.
 Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.
 
-> **Fork notice:** This package is a friendly fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents), published to npm as `@gotgenes/pi-subagents`.
-> It carries a small number of patches on top of upstream — peer-dep migration to `@earendil-works/pi-*`, a post-`bindExtensions` active-tool re-filter, and an `<active_agent>` system-prompt tag for permission resolution.
-> See [Deviations from upstream](#deviations-from-upstream) at the bottom of this README for details.
->
-> **Status:** Early release.
+> Originally forked from [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb), now an independently maintained hard fork.
+> See [Comparison with upstream](./docs/comparison-with-upstream.md) for a feature-by-feature comparison and guidance on which to choose.
 
 <img width="600" alt="pi-subagents screenshot" src="https://github.com/gotgenes/pi-subagents/raw/main/media/screenshot.png" />
 
@@ -436,73 +433,18 @@ When `@gotgenes/pi-permission-system` is not installed, the lifecycle events hav
 
 ## Architecture
 
-See `docs/architecture/architecture.md` for the full architecture document with domain decomposition, Mermaid diagrams, and improvement roadmap.
+This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.
 
-```text
-src/
-  index.ts                          # Extension entry: tool/command registration, rendering
-  runtime.ts                        # Session-scoped state bag with methods
-  types.ts                          # Shared type definitions
-  settings.ts                       # Persistent settings (concurrency, turn limits)
-  config/                           # Agent type registry and configuration
-    agent-types.ts                  # Unified agent registry (defaults + custom)
-    default-agents.ts               # Embedded default agent configs
-    custom-agents.ts                # Load user-defined agents from .pi/agents/*.md
-    invocation-config.ts            # Per-call merge of tool params + agent config
-  session/                          # Pure session assembly
-    session-config.ts               # Session configuration assembler
-    prompts.ts                      # Config-driven system prompt builder
-    context.ts                      # Parent conversation context for inherit_context
-    conversation.ts                 # Render a session's messages as formatted text
-    content-items.ts                # Shared message content parsing
-    env.ts                          # Environment detection (git, platform)
-    model-resolver.ts               # Fuzzy model matching
-    session-dir.ts                  # Session directory derivation
-  lifecycle/                        # Agent execution and state tracking
-    agent-manager.ts                # Collection manager + observer wiring
-    agent.ts                        # Full execution lifecycle (run, abort, steer, workspace)
-    create-subagent-session.ts      # Assembly factory: session creation, binding, tool filtering
-    subagent-session.ts             # Born-complete child session: turn loop, steer, dispose
-    child-lifecycle.ts              # Child-execution lifecycle event publisher
-    concurrency-queue.ts            # Background agent scheduling
-    parent-snapshot.ts              # Immutable spawn-time parent state
-    turn-limits.ts                  # Turn-count policy (normalizeMaxTurns)
-    workspace.ts                    # Workspace provider seam
-    usage.ts                        # Token usage tracking
-  observation/                      # Progress tracking and notification
-    record-observer.ts              # Session-event stats observer
-    notification.ts                 # Completion nudges
-    notification-state.ts           # Notification state tracking
-    renderer.ts                     # Notification rendering
-  service/                          # Cross-extension API boundary
-    service.ts                      # SubagentsService interface + Symbol.for() accessors
-    service-adapter.ts              # SubagentsService wrapper around AgentManager
-  tools/                            # LLM-facing tools
-  ui/                               # Widget, conversation viewer, /agents menu
-```
+See [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) for the full architecture document — design principles, domain decomposition, module dependency flow, Mermaid diagrams, and the improvement roadmap.
 
-## Deviations from upstream
+## Relationship to upstream
 
-This fork carries three divergences from [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
-Each has a corresponding upstream PR:
+This package is an independently maintained hard fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
+It has diverged substantially in scope and architecture: a minimal core with a typed service API and lifecycle events, with tool-restriction policy and worktree isolation delegated to companion packages.
+Upstream remains the batteries-included option, keeping scheduling, cross-extension RPC, model-scope enforcement, and a built-in tool denylist in a single package.
 
-1. **Peer-dep migration to `@earendil-works/pi-*`** — `peerDependencies` and all imports point at `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` (the active scope on npm) instead of the deprecated `@mariozechner/pi-*` scope.
-   Also fixes a latent bug where `ThinkingLevel` was imported from `pi-agent-core` (an undeclared transitive dep that breaks under pnpm).
-   Upstream PR: [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71).
-2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so the `EXCLUDED_TOOL_NAMES` recursion guard applies to extension-registered tools (which join the active set during `bindExtensions`).
-   Upstream PR: [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
-3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` includes `<active_agent name="${config.name}"/>` in every assembled child system prompt (both `replace` and `append` modes); the tag follows the cacheable parent-prompt prefix in both modes.
-   Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.
-   Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
-4. **Child-execution lifecycle events** (`src/lifecycle/child-lifecycle.ts`) — the child-session execution lifecycle is published as ordered events on `pi.events` (`subagents:child:spawning`, `session-created`, `completed`, `disposed`).
-   `session-created` fires synchronously before `bindExtensions()` so consumers (e.g. `@gotgenes/pi-permission-system`) can register the child session before binding proceeds.
-   This inverts the former outbound `permission-bridge` pattern ([ADR-0002] / [#261]) — the core publishes, consumers subscribe.
-   No upstream equivalent — this feature is specific to the `@gotgenes` fork.
-
-The upstream `vitest` suite plus tests added for each patch all pass on every commit.
+See [Comparison with upstream](./docs/comparison-with-upstream.md) for a full feature-by-feature comparison against the current upstream release and guidance on which to choose.
 
 ## License
 
 MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)
-
-[ADR-0002]: docs/decisions/0002-extensions-on-a-minimal-core.md

package/docs/architecture/architecture.md

@@ -646,7 +646,7 @@ That method — testability friction as a boundary probe, with its limits — is
 | Metric                     | Value                                   |
 | -------------------------- | --------------------------------------- |
 | Health score               | 78/100 (B)                              |
-| Total LOC                  | 8,356 (60 files, as of Phase 17 Step 4) |
+| Total LOC                  | 8,356 (61 files, as of Phase 17 Step 5) |
 | Dead code                  | 0 files, 0 exports                      |
 | Maintainability index      | 90.8 (good)                             |
 | Avg cyclomatic complexity  | 1.4                                     |
@@ -893,7 +893,7 @@ Updated health metrics (fallow, package-wide including tests):
 | Metric                     | Phase 16 baseline              | Current                                       |
 | -------------------------- | ------------------------------ | --------------------------------------------- |
 | Health score               | 78/100 (B)                     | 78/100 (B)                                    |
-| Source LOC                 | 7,778 (57 files)               | 8,356 (60 files, landed Phase 17 Step 4)      |
+| Source LOC                 | 7,778 (57 files)               | 8,356 (61 files, landed Phase 17 Step 5)      |
 | Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                            |
 | Maintainability index      | 90.8 (good)                    | 90.8 (good)                                   |
 | Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                       |
@@ -970,7 +970,7 @@ Priority = Impact × (6 − Risk).
   Fixed by inverting control: `scheduleVia` captures the limiter promise eagerly inside the agent (no external `.promise =` write), restoring the invariant.
   Lesson: a step's acceptance criteria must include the cross-step invariants it could regress, not only its own grep-verifiable outcome.
 
-#### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375])
+#### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375]) ✅ Complete
 
 - Targets: `src/lifecycle/subagent.ts` (455 LOC after Step 2 extracted SubagentState — still the largest source file).
 - Smell: Category B (oversized class; per-run listener fields declared mid-class) and Category C (state owns its mutations: workspace dispose logic appears in `run()`'s catch, `completeRun`, and `failRun`).
@@ -981,12 +981,13 @@ Priority = Impact × (6 − Risk).
   `subagent.ts`: 488 → 448 LOC.
   Test count: 982 → 994 (+12: 7 RunListeners + 13 WorkspaceBracket − 8 redundant Subagent listener tests).
 
-#### Step 5 — Extract the manager observer from index.ts into a class ([#376])
+#### Step 5 — Extract the manager observer from index.ts into a class ([#376]) ✅ Complete
 
 - Targets: `src/index.ts` (inline `SubagentManagerObserver` literal, ~70 lines), new module under `src/observation/`.
 - Smell: Category B/E — `index.ts` is the dominant churn hotspot (31.3, 91 commits); the literal mixes event emission, record persistence (`appendEntry`), and notification dispatch; principle 9 (state and behavior belong in classes, not closure-captured literals).
 - Change: extract a class (e.g. `SubagentEventsObserver`) constructed with narrow deps (`emit`, `appendEntry`, the `NotificationSystem`).
 - Outcome: `index.ts` < 170 lines; the observer's three concerns unit-tested directly without booting the extension.
+- Landed: `src/observation/subagent-events-observer.ts` (new, 97 LOC); `index.ts` 226 → 177 lines; 60 → 61 source files; 994 → 1009 tests (+15 covering all four observer methods).
 
 #### Step 6 — Split widget delegation out of SubagentRuntime ([#377])
 

package/docs/comparison-with-upstream.md

@@ -0,0 +1,76 @@
+# Comparison with upstream
+
+`@gotgenes/pi-subagents` began as a fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
+The original design — Claude Code-style subagent dispatch, the live widget, the conversation viewer, custom agent types — is the foundation everything here builds on.
+
+It has since become an independently maintained hard fork.
+It follows its own architecture, does not track upstream as a merge target, and cherry-picks upstream fixes only when they fit its scope.
+This document compares the fork against the current upstream release so you can choose between them.
+
+Versions compared: `@gotgenes/pi-subagents` 16.2.1 and `@tintinweb/pi-subagents` 0.10.3 (current at the time of writing).
+
+## At a glance
+
+| Aspect          | @gotgenes/pi-subagents          | @tintinweb/pi-subagents                 |
+| --------------- | ------------------------------- | --------------------------------------- |
+| Philosophy      | Minimal, composable core        | Batteries-included, all-in-one          |
+| Pi peer scope   | `@earendil-works/pi-*` (>=0.75) | `@earendil-works/pi-*` (>=0.74)         |
+| Spawn tool name | `subagent`                      | `Agent`                                 |
+| Runtime deps    | `@sinclair/typebox`             | `@sinclair/typebox`, `croner`, `nanoid` |
+| License         | MIT                             | MIT                                     |
+
+Both ship TypeScript source directly (Pi runs `./src/index.ts`) and target the same `@earendil-works/pi-*` Pi.
+The peer-dep migration that prompted the original fork has since landed upstream, so the Pi scope is no longer a differentiator.
+
+## Common ground
+
+Both extensions provide the same core experience:
+
+- Claude Code-style foreground/background subagents with a live above-editor widget and a conversation viewer.
+- Custom agent types defined in `.pi/agents/<name>.md` with YAML frontmatter (system prompt, model, thinking, tools).
+- Persistent agent memory (project / local / user scopes) with read-only fallback.
+- Skill preloading, fuzzy model selection, context inheritance, mid-run steering, session resume, and graceful turn limits.
+- A `pi.events` lifecycle bus (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`).
+
+## What upstream has that this fork does not
+
+Upstream is the batteries-included option.
+It keeps several subsystems built in that this fork deliberately removed or delegated:
+
+| Capability              | @tintinweb/pi-subagents                           | @gotgenes/pi-subagents                                                                                                                            |
+| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool restrictions       | `disallowed_tools` frontmatter (denylist)         | Delegated — `permission:` via [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) |
+| Worktree isolation      | Built-in                                          | Delegated — [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees)               |
+| Scheduling              | Cron / interval / one-shot subagents (`schedule`) | Removed                                                                                                                                           |
+| Cross-extension control | `subagents:rpc:*` event RPC                       | Replaced by a typed service (below)                                                                                                               |
+| Model-scope enforcement | `enabledModels` allowlist validation              | Not included                                                                                                                                      |
+| Notifications           | Smart group-join consolidation                    | Individual per-agent notifications                                                                                                                |
+
+## What this fork adds
+
+This fork is a minimal core that other extensions build on, plus a small companion ecosystem:
+
+- **Typed service API** — `SubagentsService` exposed via `Symbol.for()` accessors, so another extension can spawn and manage subagents without importing this package or relying on ad-hoc event RPC.
+- **Child-session lifecycle events** — `subagents:child:spawning` / `session-created` / `completed` / `disposed`, with `session-created` firing synchronously before `bindExtensions()` so consumers can register the child session deterministically.
+- **`<active_agent>` system-prompt tag** — lets [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) resolve per-agent `permission:` frontmatter (allow / ask / deny — richer than a binary denylist) inside the child session.
+- **Companion packages** — permission policy and worktree isolation live in dedicated packages rather than the core.
+- **Re-architected codebase** — decomposed into seven domains behind a typed public API boundary, backed by ~994 tests.
+
+## Which should I use?
+
+**Use `@tintinweb/pi-subagents`** if you want a single, batteries-included extension with nothing else to install: built-in tool denylist, scheduled / cron subagents, cross-extension RPC, and model-scope enforcement in one package.
+It is the canonical upstream and the original.
+
+**Use `@gotgenes/pi-subagents`** if you want a minimal, composable core: richer allow / ask / deny permissions and worktree isolation through companion packages, a typed service plus lifecycle events to build your own extensions on, and an actively refactored codebase — and you do not need built-in scheduling, RPC, or model-scope enforcement.
+
+The spawn tool is named `subagent` here versus `Agent` upstream, so prompts and docs that hard-code the tool name are not drop-in portable between the two.
+
+## Patches contributed upstream
+
+Three of the fork's early changes were opened as PRs against upstream and remain a record of the shared lineage:
+
+1. Peer-dep migration to `@earendil-works/pi-*` — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (upstream has since migrated).
+2. Post-`bindExtensions` active-tool re-filter — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
+3. `<active_agent>` system-prompt tag — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
+
+The fork has since diverged well beyond these.

package/docs/plans/0376-extract-manager-observer.md

@@ -0,0 +1,232 @@
+---
+issue: 376
+issue_title: "Extract the manager observer from index.ts into a class"
+---
+
+# Extract the manager observer from index.ts into a class
+
+## Problem Statement
+
+`index.ts` constructs an inline `SubagentManagerObserver` object literal (~50 lines, four methods) at the composition root and hands it to `SubagentManager`.
+The literal mixes three concerns: emitting `pi.events` lifecycle events, persisting the final record via `pi.appendEntry`, and dispatching completion notifications through the `NotificationManager`.
+Per code-design principle 9 (state and behavior belong in a class, not a closure-captured literal), these three concerns cannot be unit-tested today without booting the entire extension.
+`index.ts` is the package's dominant churn hotspot (31.3, 91 commits); shrinking it is the goal of Phase 17 Track B.
+
+## Goals
+
+- Extract the inline observer literal into a `SubagentEventsObserver` class under `src/observation/`, constructed with narrow deps: an `emit` function, an `appendEntry` function, and the `NotificationSystem`.
+- `index.ts` instantiates the class and passes it to `SubagentManager` in place of the literal.
+- Unit-test the observer's three concerns directly (event shapes, record persistence payload, notification dispatch branching) without booting the extension.
+- Preserve every emitted event payload and `appendEntry` shape byte-for-byte — this is a pure extraction with no observable behavior change (not breaking).
+- Bring `index.ts` below 170 lines.
+
+## Non-Goals
+
+- Splitting widget delegation out of `SubagentRuntime` (Phase 17 Step 6, Issue [#377]) — Step 5 is its prerequisite but lands separately.
+- Moving `buildEventData` out of `notification.ts` — it stays where it is tested and is imported by the new observer.
+- Pushing event-payload construction onto `Subagent` (a Tell-Don't-Ask improvement) — tracked as an Open Question, out of scope here.
+- Narrowing `NotificationSystem` to a two-method interface — see Open Questions.
+- Any other Phase 17 step.
+
+## Background
+
+Relevant modules:
+
+- `src/index.ts` (226 lines) — composition root.
+  Defines `const observer: SubagentManagerObserver = { … }` at lines 79–134 and passes it to `new SubagentManager({ …, observer, … })`.
+- `src/lifecycle/subagent-manager.ts` — owns the `SubagentManagerObserver` interface (four methods: `onSubagentStarted`, `onSubagentCompleted`, `onSubagentCompacted`, `onSubagentCreated`).
+  This interface is the manager's contract and stays here.
+- `src/observation/notification.ts` — exports `buildEventData(record)` (pure, tested in `notification.test.ts`), the `NotificationSystem` interface (`cancelNudge`, `sendCompletion`, `cleanupCompleted`, `dispose`), and `NotificationManager`.
+- `src/observation/record-observer.ts` — the established pattern for an observation-domain module that subscribes/dispatches with narrow deps; the new class is a sibling.
+
+The current literal's four methods:
+
+- `onSubagentStarted(record)` → `emit("subagents:started", { id, type, description })`.
+- `onSubagentCompleted(record)` → branch on terminal status to `emit("subagents:failed" | "subagents:completed", buildEventData(record))`; `appendEntry("subagents:record", { …8 fields… })`; then either `notifications.cleanupCompleted(record.id)` (when `record.notification?.resultConsumed`) or `notifications.sendCompletion(record)`.
+- `onSubagentCompacted(record, info)` → `emit("subagents:compacted", { id, type, description, reason, tokensBefore, compactionCount })`.
+- `onSubagentCreated(record)` → `emit("subagents:created", { id, type, description, isBackground: true })`.
+
+SDK signatures the narrow deps mirror:
+
+- `EventBus.emit(channel: string, data: unknown): void`.
+- `ExtensionAPI.appendEntry<T = unknown>(customType: string, data?: T): void`.
+
+The applicable AGENTS.md constraints: Pi SDK imports stay out of the observation module — the class accepts `emit`/`appendEntry` as injected callbacks (the same pattern `SettingsManager` uses with `SettingsEmit`), and `index.ts` wires them to `pi.events.emit`/`pi.appendEntry` via arrows (avoids `@typescript-eslint/unbound-method`).
+
+## Design Overview
+
+### Class shape
+
+```typescript
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+  emit: EventEmit;
+  appendEntry: AppendEntry;
+  notifications: NotificationSystem;
+}
+
+export class SubagentEventsObserver implements SubagentManagerObserver {
+  private readonly emit: EventEmit;
+  private readonly appendEntry: AppendEntry;
+  private readonly notifications: NotificationSystem;
+
+  constructor(deps: SubagentEventsObserverDeps) {
+    this.emit = deps.emit;
+    this.appendEntry = deps.appendEntry;
+    this.notifications = deps.notifications;
+  }
+
+  onSubagentStarted(record: Subagent): void { /* emit started */ }
+  onSubagentCompleted(record: Subagent): void { /* emit failed|completed, appendEntry, dispatch */ }
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void { /* emit compacted */ }
+  onSubagentCreated(record: Subagent): void { /* emit created */ }
+}
+```
+
+The four method bodies are moved verbatim from the literal — same event channels, same payload fields, same branching.
+`buildEventData` is imported from `#src/observation/notification`.
+
+### Call site in index.ts
+
+```typescript
+const observer = new SubagentEventsObserver({
+  emit: (channel, data) => pi.events.emit(channel, data),
+  appendEntry: (customType, data) => pi.appendEntry(customType, data),
+  notifications,
+});
+
+const manager = new SubagentManager({
+  createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
+  baseCwd: process.cwd(),
+  observer,
+  limiter,
+  getRunConfig: () => settings,
+});
+```
+
+`notifications` (the `NotificationManager`) is already constructed earlier in `index.ts`, so the observer construction slots in where the literal was.
+
+### Extracted-module interaction with upstream deps
+
+The observer only *reads* from its inputs and *tells* its collaborators — no output-argument mutation, no reverse-search, no reach-back into the manager:
+
+```text
+onSubagentCompleted(record):
+  reads   record.status / record.id / …            (Subagent getters)
+  calls   buildEventData(record)                    (pure helper)
+  tells   this.emit("subagents:completed", data)    (injected callback)
+  tells   this.appendEntry("subagents:record", {…}) (injected callback)
+  reads   record.notification?.resultConsumed       (LoD chain — pre-existing)
+  tells   this.notifications.cleanupCompleted | sendCompletion
+```
+
+The one Law-of-Demeter chain (`record.notification?.resultConsumed`) is carried over unchanged from the literal; it is pre-existing and out of scope (see Open Questions).
+
+### Design-review checklist result
+
+| Smell            | Location                              | Evidence                                                 | Disposition                                  |
+| ---------------- | ------------------------------------- | -------------------------------------------------------- | -------------------------------------------- |
+| Dependency width | `SubagentEventsObserverDeps` (3 deps) | all methods use `emit`; `onSubagentCompleted` uses all 3 | OK — narrow                                  |
+| LoD violation    | `onSubagentCompleted`                 | `record.notification?.resultConsumed`                    | Track and watch — pre-existing, out of scope |
+| Output argument  | —                                     | none                                                     | Clean                                        |
+| ISP              | `NotificationSystem` (4 methods)      | observer uses `sendCompletion`, `cleanupCompleted`       | Accept per issue spec — see Open Questions   |
+
+The extraction introduces a real collaborator (a class that owns three behaviors and is independently testable), not a procedure split — each method returns no value but performs a distinct side-effecting concern that was previously untestable in isolation.
+
+## Module-Level Changes
+
+- `src/observation/subagent-events-observer.ts` (new)
+  - Export `SubagentEventsObserver implements SubagentManagerObserver`, plus `EventEmit`, `AppendEntry`, and `SubagentEventsObserverDeps` types.
+  - Imports: `SubagentManagerObserver` from `#src/lifecycle/subagent-manager`, `buildEventData` and `NotificationSystem` from `#src/observation/notification`, `Subagent` and `CompactionInfo` from `#src/types`.
+- `src/index.ts` (changed)
+  - Remove the inline `const observer: SubagentManagerObserver = { … }` literal (lines 79–134).
+  - Add `import { SubagentEventsObserver } from "#src/observation/subagent-events-observer"`.
+  - Construct `const observer = new SubagentEventsObserver({ emit, appendEntry, notifications })`.
+  - Remove now-unused imports: `buildEventData` (moves to the new module) and the `type SubagentManagerObserver` import (the literal annotation is gone).
+  - Keep `NotificationDetails` and `NotificationManager` imports (still used by `registerMessageRenderer` and the `notifications` construction).
+- `test/observation/subagent-events-observer.test.ts` (new)
+  - Unit tests for all four methods (see TDD Order).
+- `docs/architecture/architecture.md` (changed)
+  - Mark Phase 17 Step 5 `✅ Complete` and add a "Landed" note (index.ts line count, file/test counts).
+  - Update the "Total LOC … (60 files …)" listings to 61 files and refresh the test count.
+  - The churn-hotspot note for `index.ts` stays — Step 5 continues the shrink trend.
+
+Grep confirms no `package-*/SKILL.md` documents the inline observer literal or `SubagentEventsObserver` by name; no skill-doc update needed.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled.**
+   All four observer methods become directly testable with `vi.fn()` stubs for `emit`/`appendEntry` and a stubbed `NotificationSystem`.
+   Previously the only way to exercise these paths was through `SubagentManager` integration tests that drove the manager's `buildObserver` forwarding — the index-level observer body itself had zero coverage.
+2. **No existing tests become redundant.**
+   The `subagent-manager.test.ts` observer tests (lines 76–148) exercise the manager's *forwarding* (`buildObserver` → `this.observer?.onSubagent…`), a different layer that stays.
+   `notification.test.ts` keeps the `buildEventData` tests.
+   `agent-tool.test.ts:153` keeps its note that `subagents:created` is delegated to the observer.
+3. **Tests that must stay as-is.**
+   The manager forwarding tests and the `buildEventData` purity tests genuinely exercise layers the extraction does not touch.
+
+## Invariants at risk
+
+This step touches `index.ts`, which prior Phase 17 steps shrank, and the event/notification dispatch surface.
+Step 6 ([#377]) depends on this step; it must not regress the index.ts shrink.
+
+| Invariant                                                                                                                    | Pinned by                                     |
+| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| Completion of a successful background agent emits `subagents:completed` (not `subagents:failed`) with `buildEventData` shape | new `onSubagentCompleted` success test        |
+| Terminal `error`/`stopped`/`aborted` status emits `subagents:failed`                                                         | new `onSubagentCompleted` error test          |
+| `appendEntry("subagents:record", …)` persists the eight-field record on every completion                                     | new `onSubagentCompleted` appendEntry test    |
+| Already-consumed result skips `sendCompletion` and calls `cleanupCompleted`                                                  | new `onSubagentCompleted` resultConsumed test |
+| `subagents:created` carries `isBackground: true`                                                                             | new `onSubagentCreated` test                  |
+
+These invariants lived only in the untested inline literal before; the new tests pin them for the first time.
+
+## TDD Order
+
+1. **Red → Green → Commit: extract `SubagentEventsObserver` and wire `index.ts`.**
+
+   Write `test/observation/subagent-events-observer.test.ts` first (red), covering:
+   - `onSubagentStarted` emits `subagents:started` with `{ id, type, description }`.
+   - `onSubagentCompleted` (success status) emits `subagents:completed` with `buildEventData(record)`, calls `appendEntry("subagents:record", …)` with the eight fields, and calls `notifications.sendCompletion(record)`.
+   - `onSubagentCompleted` (error/stopped/aborted) emits `subagents:failed`.
+   - `onSubagentCompleted` with `record.notification?.resultConsumed` calls `notifications.cleanupCompleted(record.id)` and does *not* call `sendCompletion`.
+   - `onSubagentCompacted` emits `subagents:compacted` with `{ id, type, description, reason, tokensBefore, compactionCount }`.
+   - `onSubagentCreated` emits `subagents:created` with `{ id, type, description, isBackground: true }`.
+
+   Use `createTestSubagent({ … })` from `#test/helpers/make-subagent` for records (it provides status, result, error, `toolCallId` for `NotificationState`, `compactionCount`); `vi.fn()` for `emit`/`appendEntry`; a stub object for `NotificationSystem`.
+
+   Then create `src/observation/subagent-events-observer.ts` (green) and update `index.ts` in the **same commit**: replace the literal with `new SubagentEventsObserver({ … })` and drop the now-unused `buildEventData` / `type SubagentManagerObserver` imports.
+   The class and the index.ts swap are coupled — index.ts is the sole call site of the literal being replaced, and the new class needs a consumer to satisfy `pnpm fallow dead-code`.
+
+   Run `pnpm --filter @gotgenes/pi-subagents run check` and `pnpm --filter @gotgenes/pi-subagents exec vitest run`.
+   Commit: `refactor: extract SubagentEventsObserver from index.ts (#376)`
+
+2. **Commit: mark Phase 17 Step 5 complete in the architecture doc.**
+
+   In `docs/architecture/architecture.md`, mark Step 5 `✅ Complete`, add a "Landed" note (new index.ts line count, file count 60 → 61, refreshed test count), and update the two "(60 files …)" LOC listings.
+   Commit: `docs: mark Phase 17 Step 5 complete in architecture.md (#376)`
+
+## Risks and Mitigations
+
+- **Risk:** the extracted methods drift from the literal's exact event payloads or `appendEntry` shape.
+  **Mitigation:** move the bodies verbatim; the new tests assert each payload field explicitly, pinning the shapes.
+- **Risk:** passing `pi.events.emit` / `pi.appendEntry` as bare values trips `@typescript-eslint/unbound-method`.
+  **Mitigation:** wire them as arrow callbacks in `index.ts` (`(channel, data) => pi.events.emit(channel, data)`), matching the existing `SettingsManager` emit wiring.
+- **Risk:** the new class is flagged as dead code by `pnpm fallow dead-code` if it lands before its consumer.
+  **Mitigation:** the class and the `index.ts` wiring land in one commit (TDD step 1).
+- **Risk:** `index.ts` does not drop below 170 lines.
+  **Mitigation:** the literal is ~50 lines and the replacement is ~6; 226 − ~50 + ~6 ≈ 182 minus the removed import lines lands it near/below 170 — verify with `wc -l` during implementation and, if just over, the net is still a clear shrink (the Outcome target is directional, not a hard gate).
+
+## Open Questions
+
+- Should `NotificationSystem` be narrowed to a two-method `CompletionNotifier` (`sendCompletion`, `cleanupCompleted`) for the observer per ISP?
+  Deferred: the issue prescribes passing `NotificationSystem`, and the interface is already cohesive.
+  Revisit only if a third consumer wants the narrow slice.
+- Should event-payload construction (and the `record.notification?.resultConsumed` read) move onto `Subagent` as Tell-Don't-Ask methods (`record.toEventData()`, `record.isResultConsumed()`)?
+  Deferred: out of scope for a faithful extraction; `buildEventData` already exists as a pure helper.
+
+[#377]: https://github.com/gotgenes/pi-packages/issues/377

package/docs/retro/0375-extract-run-listener-workspace-bracket.md

@@ -49,3 +49,56 @@ Pre-completion reviewer returned WARN (2 non-blocking findings; the doc metric r
 - **Pre-completion reviewer WARN findings** (both addressed inline):
   1. `architecture.md` health-metric rows still carried "→ 59 after Step 4" annotations after landing — updated to actual counts (60 files, 8,356 LOC) and the docs commit amended.
   2. `WorkspaceBracket.hasProvider()` TDA trade-off — documented in the `run()` call-site comment; noted here for Phase 18 awareness.
+
+## Stage: Final Retrospective (2026-06-15T02:04:42Z)
+
+### Session summary
+
+Shipped issue #375 (Phase 17 Step 4) cleanly across four stages in one continuous session: planning produced a 4-step plan, TDD implemented it in 4 commits (suite 982 → 994), shipping pushed/verified-CI/closed-the-issue and merged release-please PR #406 (`pi-subagents-v16.2.1`, which actually carried #374's `fix:` — #375's `refactor:`/`docs:` commits trigger no bump).
+The only substantive friction was a single self-identified plan deviation in TDD (a microtask-boundary timing trap), resolved inside the same commit with no rework, reorder, or user correction.
+
+### Observations
+
+#### What went well
+
+- **The cross-step-invariant discipline from the #374 retro paid off a second time.**
+  The #374 process retro added the "Invariants at risk" plan section; the #375 plan used it to list the three prior Phase 17 invariants (at-spawn `promise`, construct-complete, zero external field writes), each already pinned by a named test.
+  All three held through the extraction with a green suite — the regression class that bit #374 did not recur.
+  This is the first time the new section was load-bearing on a *fresh* issue rather than as a post-hoc correction.
+- **Planning corrected the issue's own design sketch instead of implementing it literally.**
+  The issue proposed `RunListeners.attach(unsub, detach)` and "three dispose paths collapse into one"; the plan recognized the two handles attach at different lifecycle moments (so `attach` had to split into `wireSignal`/`attachObserver`/`release`) and that the two dispose sites have genuinely different error-handling semantics (so they stay separate per the structural-duplication heuristic).
+  Treating the issue body as a hypothesis, not a spec, avoided a wrong abstraction.
+
+#### What caused friction (agent side)
+
+- `missing-context` — the plan's Design Overview sketched `const cwd = await this.workspaceBracket.prepare(...)` **unconditionally**, but the original `run()` only awaited inside `if (provider) { ... }`, keeping the no-provider path synchronous up to the factory call.
+  An always-`async` helper adds a microtask boundary even when it returns immediately, so the queued-abort test in `subagent-manager.test.ts` ("abort removes a queued agent without ever running it") failed: it asserts `factory.toHaveBeenCalledOnce()` synchronously, and the factory call had been deferred a tick.
+  The first fix attempt (`if (this.execution.getWorkspaceProvider)`) also failed because `SubagentManager.spawn()` always injects `getWorkspaceProvider: () => this._workspaceProvider` as a function regardless of whether a provider is registered, so the guard was always true.
+  Resolved by adding `WorkspaceBracket.hasProvider()` (a synchronous predicate) and guarding the `await` with it.
+  Impact: ~2 test-run cycles inside TDD step 3, one extra method (`hasProvider`) plus 2 unit tests not in the plan, and a mild Tell-Don't-Ask trade-off the pre-completion reviewer flagged as WARN.
+  Self-identified via the failing test; no commit reorder, no rework beyond the in-commit fix.
+- `other` (minor) — `subagent.ts` first landed at 469 LOC, above the plan's ≤ 450 gate; two trim passes (stale module-level doc comment, redundant field comments) brought it to 448.
+  The trimmed comments were genuinely stale post-extraction, so the trim was legitimate, but the LOC estimate ("≈ 40 lines removed") was optimistic about the structural change alone.
+  Impact: 2 extra edits, no rework.
+
+#### What caused friction (user side)
+
+- None.
+  The four-stage flow ran end-to-end on prompt templates with zero mid-stream user corrections or strategic interventions — the work was clean enough that none were needed.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning ran on `anthropic/claude-opus-4-8` (pinned via `plan-issue.md`, appropriate for judgment-heavy design); TDD on `anthropic/claude-sonnet-4-6` (appropriate); the pre-completion reviewer subagent on its frontmatter default; Retro on `anthropic/claude-opus-4-8` (pinned).
+  The **ship stage ran on `opencode-go/deepseek-v4-flash`** — the same weak-model-on-release-management pattern flagged in the #374 retro.
+  It again executed cleanly, including the non-trivial reasoning that PR #406 mapped to #374 not #375 and the `UNSTABLE`/empty-rollup `GITHUB_TOKEN` diagnosis.
+  Second consecutive clean run, so the risk remains theoretical (irreversible ops on a weak model) rather than demonstrated harm.
+- **Escalation-delay tracking** — the microtask friction was not a rabbit hole: the diagnosis moved methodically (failing test → `concurrency-limiter.ts` → `subagent-manager.ts:156` injection point → root cause) across ~2 test-run cycles, under the 5-call flag threshold.
+- **Unused-tool detection** — the friction was exact-symbol tracing (`grep` for `getWorkspaceProvider`), which `grep` handled correctly; no Explore/colgrep dispatch was warranted.
+- **Feedback-loop gap analysis** — verification was incremental throughout: per-file `vitest` after each red/green, `pnpm run check` after the interface-change step, full suite + lint + `fallow dead-code` before the pre-completion review.
+  No end-only-verification gap.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added a bullet under `### Interface and type changes` on the conditional-`await` → always-`async` microtask-boundary trap (sibling to the existing runtime-vs-typecheck timing rule).
+2. `packages/pi-subagents/docs/retro/0375-extract-run-listener-workspace-bracket.md` — added this Final Retrospective stage entry.
+3. Considered but not landed (operator-declined or out of scope): pinning `/ship-issue` to a stronger model (recurrence of the #374 finding, no demonstrated harm this session), a `plan-issue` rule on preserving conditional awaits in extracted-method sketches, and a rule against trimming comments to hit a LOC gate.

package/docs/retro/0376-extract-manager-observer.md

@@ -0,0 +1,40 @@
+---
+issue: 376
+issue_title: "Extract the manager observer from index.ts into a class"
+---
+
+# Retro: #376 — Extract the manager observer from index.ts into a class
+
+## Stage: Planning (2026-06-15T00:00:00Z)
+
+### Session summary
+
+Planned Phase 17 Step 5: extracting the inline `SubagentManagerObserver` literal from `index.ts` into a `SubagentEventsObserver` class under `src/observation/`, constructed with narrow `emit` / `appendEntry` / `NotificationSystem` deps.
+The plan is a single red→green→commit extraction (class + tests + `index.ts` wiring in one commit) plus a docs commit marking the step complete.
+Classified as a non-breaking, pure internal extraction with no observable behavior change.
+
+### Observations
+
+- The issue is the operator's own (author `gotgenes` matches the gh user) and the architecture doc already specifies Step 5 precisely, so the `ask-user` gate was skipped.
+- The class + `index.ts` swap must land in one commit: `index.ts` is the sole call site of the literal being replaced, and the new class needs a consumer to satisfy `pnpm fallow dead-code`.
+- Kept `buildEventData` in `notification.ts` (it is tested there) and imported it into the new module — avoids churning `notification.test.ts`.
+- Used `refactor:` for the extraction commit, matching the precedent of Phase 17 Step 4 (#375); `refactor` is hidden from the release-please changelog.
+- Two structural smells were noted as out of scope: the `record.notification?.resultConsumed` Law-of-Demeter chain (track-and-watch) and narrowing `NotificationSystem` to a two-method `CompletionNotifier` per ISP (the issue prescribes passing `NotificationSystem`).
+- Wiring `pi.events.emit` / `pi.appendEntry` as arrow callbacks in `index.ts` avoids the `@typescript-eslint/unbound-method` trap; mirrors the existing `SettingsManager` emit pattern.
+- Step 6 (#377) depends on this step; the plan pins the previously-untested event/notification dispatch invariants so Step 6 cannot regress them.
+
+## Stage: Implementation — TDD (2026-06-15T18:40:00Z)
+
+### Session summary
+
+Completed 2 TDD cycles: (1) extracted `SubagentEventsObserver` into `src/observation/subagent-events-observer.ts`, added 15 tests covering all four observer methods, and updated `src/index.ts` to replace the inline literal — all in one coupled commit; (2) marked Phase 17 Step 5 ✅ Complete in the architecture doc with a Landed note.
+Test delta: 994 → 1009 (+15); file count 63 → 64 test files; `index.ts` 226 → 177 lines.
+Pre-completion reviewer: PASS.
+
+### Observations
+
+- The typed `vi.fn<(channel: string, data: unknown) => void>()` mock triggered `@typescript-eslint/no-unnecessary-type-assertion` on `mock.calls[0]!` indexing — fixed by switching the error-status assertions to `toHaveBeenCalledWith("subagents:failed", expect.anything())` and the success-status assertion to `toHaveBeenCalledWith("subagents:completed", buildEventData(record))`.
+  This eliminated all raw `mock.calls[0]` indexing from the file, which is cleaner.
+- The autoformatter (`pi-autoformat`) ran after writing `index.ts`, so the import block was reflowed; re-reading before further edits would be required in any follow-up session.
+- Architecture doc: Step 4's header was already missing its ✅ Complete marker (it had a Landed note); the reviewer noted this was corrected correctly, not a regression.
+- All five previously-untested observer-behavior invariants are now pinned by tests for the first time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.2.1",
+  "version": "16.2.2",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -27,9 +27,10 @@ import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import { SubagentManager, type SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
-import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
+import { SubagentManager } from "#src/lifecycle/subagent-manager";
+import { type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
+import { SubagentEventsObserver } from "#src/observation/subagent-events-observer";
 import { createSubagentRuntime } from "#src/runtime";
 import { publishSubagentsService, unpublishSubagentsService } from "#src/service/service";
 import { SubagentsServiceAdapter } from "#src/service/service-adapter";
@@ -76,61 +77,11 @@ export default function (pi: ExtensionAPI) {
   settings.load();
 
   // Observer: receives agent lifecycle notifications and dispatches events/notifications.
-  const observer: SubagentManagerObserver = {
-    onSubagentStarted(record) {
-      // Emit started event when agent transitions to running (including from queue).
-      pi.events.emit("subagents:started", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-      });
-    },
-    onSubagentCompleted(record) {
-      // Emit lifecycle event based on terminal status.
-      const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-      const eventData = buildEventData(record);
-      if (isError) {
-        pi.events.emit("subagents:failed", eventData);
-      } else {
-        pi.events.emit("subagents:completed", eventData);
-      }
-
-      // Persist final record for cross-extension history reconstruction.
-      pi.appendEntry("subagents:record", {
-        id: record.id, type: record.type, description: record.description,
-        status: record.status, result: record.result, error: record.error,
-        startedAt: record.startedAt, completedAt: record.completedAt,
-      });
-
-      // Skip notification if result was already consumed via get_subagent_result.
-      if (record.notification?.resultConsumed) {
-        notifications.cleanupCompleted(record.id);
-        return;
-      }
-
-      notifications.sendCompletion(record);
-    },
-    onSubagentCompacted(record, info) {
-      // Emit compacted event when agent's session compacts (preserves count on record).
-      pi.events.emit("subagents:compacted", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-        reason: info.reason,
-        tokensBefore: info.tokensBefore,
-        compactionCount: record.compactionCount,
-      });
-    },
-    onSubagentCreated(record) {
-      // Emit created event for background agents (before limiter admission).
-      pi.events.emit("subagents:created", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-        isBackground: true,
-      });
-    },
-  };
+  const observer = new SubagentEventsObserver({
+    emit: (channel, data) => pi.events.emit(channel, data),
+    appendEntry: (customType, data) => pi.appendEntry(customType, data),
+    notifications,
+  });
 
   const subagentSessionDeps: SubagentSessionDeps = {
     io: {

package/src/observation/subagent-events-observer.ts

@@ -0,0 +1,97 @@
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import { buildEventData, type NotificationSystem } from "#src/observation/notification";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+	emit: EventEmit;
+	appendEntry: AppendEntry;
+	notifications: NotificationSystem;
+}
+
+/**
+ * Receives agent lifecycle notifications from SubagentManager and dispatches
+ * them to three concerns: pi.events lifecycle events, session-entry persistence,
+ * and completion notifications.
+ *
+ * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
+ * three concerns are unit-testable without booting the extension.
+ */
+export class SubagentEventsObserver implements SubagentManagerObserver {
+	private readonly emit: EventEmit;
+	private readonly appendEntry: AppendEntry;
+	private readonly notifications: NotificationSystem;
+
+	constructor(deps: SubagentEventsObserverDeps) {
+		this.emit = deps.emit;
+		this.appendEntry = deps.appendEntry;
+		this.notifications = deps.notifications;
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		// Emit started event when agent transitions to running (including from queue).
+		this.emit("subagents:started", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+		});
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		// Emit lifecycle event based on terminal status.
+		const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+		const eventData = buildEventData(record);
+		if (isError) {
+			this.emit("subagents:failed", eventData);
+		} else {
+			this.emit("subagents:completed", eventData);
+		}
+
+		// Persist final record for cross-extension history reconstruction.
+		this.appendEntry("subagents:record", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			status: record.status,
+			result: record.result,
+			error: record.error,
+			startedAt: record.startedAt,
+			completedAt: record.completedAt,
+		});
+
+		// Skip notification if result was already consumed via get_subagent_result.
+		if (record.notification?.resultConsumed) {
+			this.notifications.cleanupCompleted(record.id);
+			return;
+		}
+
+		this.notifications.sendCompletion(record);
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		// Emit compacted event when agent's session compacts (preserves count on record).
+		this.emit("subagents:compacted", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			reason: info.reason,
+			tokensBefore: info.tokensBefore,
+			compactionCount: record.compactionCount,
+		});
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		// Emit created event for background agents (before limiter admission).
+		this.emit("subagents:created", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			isBackground: true,
+		});
+	}
+}