@nklisch/pi-enhanced 0.4.3 → 0.5.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-7-encapsulation.md

@@ -1,173 +0,0 @@
-# Phase 7: Encapsulation and dependency narrowing
-
-Every mutable state bag became a class, every dependency bag narrowed to what its consumer uses, every callback became either a method on a collaborator or an event on an observable.
-
-## AgentManager decomposition
-
-AgentManager was decomposed in three steps to untangle record management, concurrency control, and execution orchestration.
-
-### Step 1: Record state machine (#98, #102)
-
-Extracted status-transition methods (`markRunning`, `markCompleted`, `markAborted`, `markSteered`, `markError`, `markStopped`, `resetForResume`) onto `AgentRecord`.
-Replaced scattered field writes across 6 sites with encapsulated transition methods.
-Issue #102 consolidated test `AgentRecord` construction into a shared factory.
-
-### Step 2: Parent snapshot (#99)
-
-Replaced live `ctx: ExtensionContext` capture in `SpawnArgs` with an immutable `ParentSnapshot` data object.
-The snapshot is taken once at spawn time; queued agents execute against frozen state rather than a potentially stale session reference.
-`runAgent()` accepts `ParentSnapshot` instead of `ctx`.
-`pi: ExtensionAPI` was removed from `SpawnArgs` - `runAgent()` accepts a `ShellExec` function instead.
-
-### Step 3: Session-event observation (#100)
-
-Replaced three-layer callback threading with direct session subscriptions.
-`record-observer.ts` subscribes to the session to update record statistics (tool uses, lifetime usage, compaction count).
-`ui/ui-observer.ts` subscribes to the session to stream UI state (active tools, response text, turn count).
-`SpawnOptions` and `RunOptions` dropped all `on*` callback fields except `onSessionCreated` (which delivers the session object to enable external subscriptions).
-
-### Realized impact
-
-| Metric                            | Before | After                   |
-| --------------------------------- | ------ | ----------------------- |
-| `SpawnOptions` callback fields    | 6      | 1 (`onSessionCreated`)  |
-| `RunOptions` callback fields      | 6      | 1 (`onSessionCreated`)  |
-| Callback layers                   | 3      | 0 (direct subscription) |
-| Live `ctx` references in queue    | 1      | 0 (snapshot)            |
-| Scattered status-transition sites | 6      | 1 (state machine)       |
-
-## Encapsulation roadmap
-
-Phase 7 encapsulated mutable state into classes, replaced callbacks with semantic components, and narrowed dependency bags.
-
-Each step was sequenced so it made the next step easier.
-
-### Resolved smells
-
-All nine smells identified at the start of Phase 7 were resolved:
-
-| Smell                      | Resolution                                                                                                                                 |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| Global mutable state       | `AgentTypeRegistry` class (#108); `reloadCustomAgents` callback removed from dep bags                                                      |
-| Closure bag as class       | `NotificationManager` class (#116); `pendingNudges` and timer state are private fields                                                     |
-| Mutable state bag          | `AgentActivityTracker` class (#110); transition methods replace external writes                                                            |
-| Settings relay             | `SettingsManager` class (#109); 6 callback fields collapsed to one object                                                                  |
-| Post-construction mutation | `ExecutionState`, `WorktreeState`, `NotificationState` collaborators (#111); stats behind mutation methods                                 |
-| Fire-and-forget callbacks  | `AgentManagerObserver` interface (#112); one observer object replaces 3 closure lambdas                                                    |
-| Duplicate `SpawnOptions`   | Internal type renamed to `AgentSpawnConfig` (#113); public `SpawnOptions` unchanged                                                        |
-| Type dumping ground        | `NotificationDetails`, `ParentSnapshot`, `EnvInfo` moved to their natural modules (#116); narrow subsets defined                           |
-| Wide dependency bags       | `AgentToolDeps` 9 → 6, `AgentMenuDeps` 8 → 7 (#114); `emitEvent` removed; description text derived from registry; `agentActivity` narrowed |
-
-### Step A: Extract state into classes (foundation, parallel)
-
-These three extractions are independent and can proceed in any order.
-Each eliminates a category of global/closure state and gives orphaned callbacks a natural home.
-
-#### A1. AgentTypeRegistry class (#108)
-
-Wrapped the module-scoped `agents` Map and free functions in `agent-types.ts` into an injectable class.
-`reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`; replaced by `registry.reload()`.
-`DEFAULT_AGENT_NAMES` moved from `types.ts` to the registry.
-
-#### A2. SettingsManager class (#109, #118)
-
-Encapsulated settings load/save/apply cycle into `SettingsManager` (in `settings.ts`).
-Owns `defaultMaxTurns`, `graceTurns`, `maxConcurrent` with normalizing property accessors.
-Added `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` - each owns the full consequence chain: normalize → set in memory → notify callback → persist → emit event → return toast.
-The 6 settings-related fields in `AgentMenuDeps` collapsed to `settings: AgentMenuSettings`.
-
-#### A3. AgentActivityTracker class (#110)
-
-Wrapped the 7-field mutable `AgentActivity` interface in an `AgentActivityTracker` class (`src/ui/agent-activity-tracker.ts`).
-`ui-observer.ts` calls transition methods; consumers use read-only accessors.
-The shared map on `SubagentRuntime` is `Map<string, AgentActivityTracker>`.
-
-### Step B: Split AgentRecord lifecycle state (#111)
-
-Split post-construction mutation into phase-specific collaborators, each born complete:
-
-- **`ExecutionState`** (`session`, `outputFile`) - constructed in `onSessionCreated`.
-- **`WorktreeState`** (`path`, `branch`, `cleanupResult`) - constructed at worktree setup.
-- **`NotificationState`** (`toolCallId`, `resultConsumed`) - constructed by `AgentManager.spawn()` when `toolCallId` is provided.
-- **`pendingSteers`** moved to `Map<string, string[]>` on `AgentManager`.
-- Stats encapsulated behind mutation methods with read-only getters.
-- `AgentRecordInit` trimmed from 19 optional fields to 4 construction-time fields.
-
-### Step C: Replace AgentManager callbacks with observer (#112)
-
-`AgentManagerObserver` interface replaces `onStart`/`onComplete`/`onCompact`.
-`index.ts` constructs one observer object instead of 3 closure lambdas.
-`AgentManagerOptions` drops from 9 → 7 fields.
-
-### Step D: Disambiguate SpawnOptions and narrow dependency bags
-
-#### D1. Disambiguate SpawnOptions (#113)
-
-Internal `SpawnOptions` in `agent-manager.ts` renamed to `AgentSpawnConfig`.
-Public `SpawnOptions` in `service.ts` unchanged.
-
-#### D2. Narrow AgentToolDeps and AgentMenuDeps (#114)
-
-| Bag             | Before   | After | How                                                                                                         |
-| --------------- | -------- | ----- | ----------------------------------------------------------------------------------------------------------- |
-| `AgentToolDeps` | 9 fields | 6     | `emitEvent` → observer; `typeListText`/`availableTypesText` derived from registry; `agentActivity` narrowed |
-| `AgentMenuDeps` | 8 fields | 7     | Dead `emitEvent` removed; `agentActivity` narrowed to read-only `AgentActivityReader`                       |
-
-### Step E: Decompose large files and relocate types
-
-#### E1. Split agent-tool.ts foreground/background (#115)
-
-Extracted `foreground-runner.ts` (~175 lines) and `background-spawner.ts` (~116 lines).
-`agent-tool.ts` reduced from 579 → 411 lines.
-
-#### E2. Type housekeeping (#116)
-
-- Moved `NotificationDetails`, `ParentSnapshot`, `EnvInfo` to their natural modules.
-- Converted `createNotificationSystem` closure to `NotificationManager` class.
-- Converted `ConversationViewer` constructor from 7 positional parameters to `ConversationViewerOptions` bag.
-- Defined `AgentIdentity` and `AgentPromptConfig` narrow subsets; `buildAgentPrompt` narrowed to `AgentPromptConfig`.
-
-### Phase 7 results
-
-| Metric                                     | Before | After |
-| ------------------------------------------ | ------ | ----- |
-| Module-scoped mutable state                | 1      | 0     |
-| Closure-bag "classes"                      | 2      | 0     |
-| Externally-mutated state bags              | 2      | 0     |
-| `AgentManagerOptions` fields               | 9      | 7     |
-| `AgentToolDeps` fields                     | 9      | 6     |
-| `AgentMenuDeps` fields                     | 13     | 7     |
-| `SpawnOptions` callback fields             | 6      | 1     |
-| `RunOptions` callback fields               | 6      | 1     |
-| Callbacks threaded through deps            | 8      | 0     |
-| Types in `types.ts` without a natural home | 4      | 0     |
-
-### Dependency graph
-
-```mermaid
-flowchart LR
-    A1["A1: Registry"] --> D2["D2: Narrow deps"]
-    A2["A2: Settings"] --> A2b["A2b: Apply"] --> D2
-    A3["A3: Activity Tracker"] --> D2
-    B["B: Record lifecycle"] --> D2
-    B --> C["C: Observer"] --> D1["D1: SpawnOptions"] --> D2
-    D2 --> E1["E1: agent-tool split"]
-    A1 --> E2["E2: Type housekeeping"]
-```
-
-## Related issues
-
-- #98 — Record state machine
-- #99 — Parent snapshot
-- #100 — Session-event observation
-- #102 — Consolidated test AgentRecord construction
-- #108 — AgentTypeRegistry class
-- #109 — SettingsManager class
-- #110 — AgentActivityTracker class
-- #111 — Split AgentRecord lifecycle state
-- #112 — Replace AgentManager callbacks with observer
-- #113 — Disambiguate SpawnOptions
-- #114 — Narrow AgentToolDeps and AgentMenuDeps
-- #115 — Split agent-tool.ts foreground/background
-- #116 — Type housekeeping
-- #118 — SettingsManager apply methods

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-8-testability.md

@@ -1,103 +0,0 @@
-# Phase 8: Testability, display extraction, and menu decomposition
-
-Eliminated `vi.mock()` module mocking in the two most fragile test suites by injecting IO-touching collaborators; consolidated shared test fixtures; extracted display helpers into a reusable module; decomposed the largest UI file.
-
-Steps G and H eliminated 11 of the original 12 `vi.mock()` calls in the runner tests, removing fragile call-sequence assertions in favour of injected stubs.
-Step G resolved `session-config.test.ts`; Step H resolved both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`.
-
-The display and menu improvements were identified during Phase 7 but deferred because they did not gate encapsulation work.
-The display extraction unblocked menu decomposition.
-
-## Test pain points (resolved)
-
-| Symptom                                                       | Resolution                                                     |
-| ------------------------------------------------------------- | -------------------------------------------------------------- |
-| 7 `vi.mock()` calls in `agent-runner.test.ts`                 | Step H (#133): injected `RunnerIO` stubs                       |
-| 7 `vi.mock()` calls in `agent-runner-extension-tools.test.ts` | Step H (#133): same                                            |
-| 52 `as any` casts across test suite                           | Step I (#134): reduced to 15                                   |
-| 3× duplicated `mockSession()`                                 | Step F (#131): shared `createMockSession()` in `test/helpers/` |
-| 3× duplicated `makeDeps()`                                    | Step F (#131): shared `createToolDeps()` in `test/helpers/`    |
-
-The well-designed test suites - `agent-manager.test.ts` (1 mock, DI via `AgentRunner` interface), `notification.test.ts` (0 mocks, pure functions + DI), and `agent-tool.test.ts` (0 mocks, tests via deps bag) - confirmed the pattern: modules that accept collaborators through injection produce resilient tests; modules that import collaborators directly produce fragile mock-heavy tests.
-
-## Step F: Shared test fixtures (#131)
-
-Consolidated duplicated mock factories into `test/helpers/`.
-
-1. `createMockSession()` - subscribable event bus with `emit()` helper; replaced 3 hand-rolled copies.
-2. `createToolDeps()` - builds `AgentToolDeps` with sensible defaults and override support; replaced 3 `makeDeps()` copies.
-3. `makeRecord()` - `AgentRecord` factory with sensible defaults; replaced scattered inline construction.
-4. `STUB_CTX` - shared stub `ExtensionContext` constant; centralised unavoidable bridge casts.
-
-Impact: reduced test boilerplate; single source of truth for mock shapes; changes to dep interfaces propagate automatically.
-
-## Step G: Inject IO collaborators into session-config (#132)
-
-`assembleSessionConfig` now accepts `io: AssemblerIO` as a required parameter.
-`index.ts` constructs the real `AssemblerIO` from direct imports via the `RunnerIO.assemblerIO` field (wired in Step H).
-`session-config.test.ts` injects stubs - all 4 `vi.mock()` calls eliminated, assertions shifted to `SessionConfig` output properties.
-
-## Step H: Inject SDK boundary into agent-runner (#133)
-
-`runAgent()` now accepts `io: RunnerIO` as a required parameter bundling all IO collaborators: `detectEnv`, `getAgentDir`, `createResourceLoader`, `deriveSessionDir`, `createSessionManager`, `createSettingsManager`, `createSession`, and `assemblerIO`.
-
-`createAgentRunner(io: RunnerIO): AgentRunner` factory captures the boundary at construction time so `AgentManager` and the `AgentRunner` interface remain unchanged.
-`index.ts` constructs the real `RunnerIO` from Pi SDK imports and sibling modules.
-
-Impact: all 7 `vi.mock()` calls eliminated from both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected stubs; SDK imports moved to the extension entry point.
-
-## Step I: Reduce `as any` casts in tests (#134)
-
-Reduced `as any` count from 93 to 15 (plus 13 explicit `as unknown as T` bridge casts).
-
-Production changes:
-
-- `ResourceLoaderOptions.appendSystemPromptOverride` typed to match `DefaultResourceLoaderOptions`; `createResourceLoader` factory cast removed from `index.ts`.
-- `CreateSessionOptions.settingsManager` / `RunnerIO.createSettingsManager` typed as `SettingsManager`.
-- `WidgetLike` interface in `runtime.ts` narrows the widget field.
-- Local `ToolCallContent` / `BashExecutionMessage` type guards replace `as any` duck-typing in `conversation-viewer.ts` and `agent-runner.ts`.
-- `textResult()` return no longer casts `details as any`.
-- `toAgentSession()` helper and `STUB_CTX` constant centralise unavoidable bridge casts.
-
-Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred - requires `AgentManager.spawn` to accept `ParentSnapshot` directly), 2 `print-mode.test.ts` (same ExtensionContext/API pattern), 2 private-field test access, 1 `createSession` SDK bridge in `index.ts`, 1 `foreground-runner.ts` `AgentToolResult<any>` detail, 1 `stub-ctx.ts` comment.
-
-## Step J: Extract display helpers (#135)
-
-`ui/display.ts` now contains all pure formatters, display helpers, constants, and shared types (`Theme`, `AgentDetails`).
-`agent-widget.ts` dropped from 522 → ~340 lines.
-All consumer modules (menu, tools, renderer, conversation viewer) import from `ui/display.ts` directly.
-`test/agent-widget.test.ts` renamed to `test/display.test.ts`.
-
-## Step K: Decompose agent-menu.ts (#136)
-
-`agent-menu.ts` (668 lines) decomposed into four modules:
-
-1. `ui/agent-file-ops.ts` - `AgentFileOps` interface (`exists`, `read`, `write`, `remove`, `ensureDir`, `findAgentFile`) + `FsAgentFileOps` production implementation.
-2. `ui/agent-config-editor.ts` - `showAgentDetail` with edit/delete/reset/eject/disable/enable transitions (~200 lines).
-3. `ui/agent-creation-wizard.ts` - AI-generation and manual-form creation paths (~250 lines).
-4. `ui/agent-menu.ts` - menu orchestration, agent listing, running-agent viewer, settings form (~300 lines).
-
-Impact: `agent-menu.ts` dropped from 668 → 296 lines; extracted modules receive `AgentFileOps` via injection; `vi.mock("node:fs")` eliminated from `agent-menu.test.ts`.
-
-## Step dependencies
-
-```mermaid
-flowchart LR
-    subgraph testability["Testability track"]
-        F["F: Shared fixtures"] --> G["G: session-config IO"] --> H["H: agent-runner SDK"] --> I["I: Reduce as-any"]
-    end
-    subgraph display["Display track"]
-        J["J: Display extraction"] --> K["K: Menu decomposition"]
-    end
-```
-
-The two tracks are independent and can proceed in parallel.
-
-## Related issues
-
-- #131 — Shared test fixtures
-- #132 — Inject IO collaborators into session-config
-- #133 — Inject SDK boundary into agent-runner
-- #134 — Reduce as-any casts in tests
-- #135 — Extract display helpers
-- #136 — Decompose agent-menu.ts

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-9-observation-ctx.md

@@ -1,122 +0,0 @@
-# Phase 9: Observation consolidation, ctx elimination, and remaining mocks
-
-Target: consolidate the dual observation model so stats live in one place; remove `ExtensionContext` from all internal APIs; eliminate remaining `vi.mock()` calls and `as any` casts; split widget rendering from lifecycle; apply dependency bag convention.
-
-## Current smells
-
-| Smell                                             | Location                                                                  | Evidence                                                                                                                       | Severity |
-| ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
-| `execute` does config resolution for its callees  | `agent-tool.ts` (145-line `execute`)                                      | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep | Medium   |
-| ~~Wide `ctx` in menu handlers~~                   | ~~`agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts`~~ | Resolved by #146: `MenuUI` interface introduced; 42 `ctx as any` casts eliminated across 5 test files                          | Done     |
-| ~~Direct SDK import in `conversation-viewer.ts`~~ | ~~`conversation-viewer.test.ts`~~                                         | Resolved by #147: `wrapText` injected via `ConversationViewerOptions`; `vi.mock("@earendil-works/pi-tui")` eliminated          | Done     |
-| ~~Widget mixes rendering, lifecycle, and state~~  | ~~`agent-widget.ts` (370 lines)~~                                         | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                         | Done     |
-| `deps.` prefix noise in function bodies           | remaining modules across tools, UI, service-adapter                       | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line      | Low      |
-
-## Dependency bag convention
-
-Applied incrementally as each step touches a module:
-
-- **≤4 fields** - accept as plain parameters; drop the interface.
-- **≥5 fields** - keep a named interface but destructure in the function signature (`{ manager, widget }: ForegroundDeps`) so the function body uses bare names, not `deps.foo`.
-
-This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
-
-## Step L: Consolidate observation model (#144)
-
-Removed `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
-UI consumers read stats from `AgentRecord` instead of the tracker.
-The UI observer retains event subscriptions for re-render triggers but no longer accumulates stats independently.
-
-Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
-The 15+ callsites that navigate `record.execution?.session` simplify to `record.session`.
-
-Apply the dependency bag convention to touched modules: `NotificationDeps` (4 fields) becomes plain parameters on `NotificationManager` constructor.
-
-Impact: eliminates dual counting; removes `??` fallback pattern from widget and conversation viewer; hides `ExecutionState` structure from consumers.
-
-## Step M: Decompose execute and push ExtensionContext to the boundary (#145)
-
-Extracted config resolution into `resolveSpawnConfig` (pure function in `spawn-config.ts`).
-Injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` so `execute` no longer reads `ctx` beyond `ctx.ui` (already delegated to `widget.setUICtx`).
-`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
-`service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
-`foreground-runner` and `background-spawner` receive `ResolvedSpawnConfig` + domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
-
-Dissolved `ForegroundDeps`, `BackgroundDeps`, and `AdapterDeps` into plain parameters.
-`AgentToolDeps` is destructured in the `createAgentTool` signature.
-
-After this step, `ExtensionContext` appears only in:
-
-- `index.ts` closures (wired at extension startup)
-- `service-adapter.ts` (cross-extension boundary)
-- Menu handlers (addressed by Step N)
-
-Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
-
-## Step N: Narrow UI context for menu handlers (#146)
-
-Defined `MenuUI` interface (exported from `agent-menu.ts`) with `select`, `confirm`, `input`, `notify`, `editor`, and `custom` methods — the exact subset `ctx.ui` methods used by menu handlers.
-All inner functions in `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts` now accept `(ui: MenuUI)` instead of `(ctx: ExtensionContext)`.
-`index.ts` passes `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)` to the handler.
-
-`AgentMenuManager.spawnAndWait` and `WizardManager.spawnAndWait` both accept `ParentSnapshot` (enabled by Step M).
-Creation wizard threads `parentSnapshot` from `showCreateWizard(ui, parentSnapshot)` → `showGenerateWizard(ui, parentSnapshot, targetDir)` → `manager.spawnAndWait(parentSnapshot, ...)`.
-
-Applied the dependency bag convention:
-
-- `AgentConfigEditorDeps` (4 fields), `GetResultDeps` (4 fields), `SteerToolDeps` (4 fields) dissolved into plain parameters.
-- `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) kept as interfaces, destructured in the function signature.
-
-After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures and `service-adapter.ts` (cross-extension bridge).
-
-Impact: eliminated 42 `ctx as any` casts across 5 test files (`agent-menu.test.ts`: 8, `agent-config-editor.test.ts`: 20, `agent-creation-wizard.test.ts`: 14); tests construct plain `MenuUI`-shaped objects with no cast.
-
-## Step O: Inject text wrapping into ConversationViewer (#147)
-
-Accepted `wrapText: (text: string, width: number) => string[]` via `ConversationViewerOptions`.
-`agent-menu.ts` passes the real `wrapTextWithAnsi` import at the `ConversationViewer` construction site.
-Tests inject a stub or the real function directly via options — no module-level mock needed.
-
-Applied the dependency bag convention: `ConversationViewerOptions` is now destructured in the constructor signature.
-
-Impact: eliminated the hoisted `vi.mock("@earendil-works/pi-tui")` from `conversation-viewer.test.ts`; 1 test deleted (mock-mechanism sentinel); net −1 test.
-
-## Step P: Split AgentWidget rendering (#148)
-
-Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
-The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
-Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
-
-## Step dependencies
-
-```mermaid
-flowchart LR
-    subgraph observation["Observation track"]
-        L["L: Consolidate observation #144"] --> P["P: Split widget rendering #148"]
-    end
-    subgraph ctx["ctx elimination track"]
-        M["M: Decompose execute / push ctx #145"] --> N["N: Narrow UI context #146"]
-    end
-    O["O: Inject text wrapping #147"]
-```
-
-The three tracks are independent of each other.
-
-## Projected impact
-
-| Metric                             | Before                   | After                    |
-| ---------------------------------- | ------------------------ | ------------------------ |
-| `vi.mock()` calls remaining        | 4                        | 1 (`print-mode.test.ts`) |
-| `as any` casts remaining           | 45                       | ~5                       |
-| Independent tool-use counters      | 2                        | 1                        |
-| `record.execution?.` traversals    | 15+                      | 0                        |
-| `ExtensionContext` in domain types | 1 (`AgentManager.spawn`) | 0                        |
-| `deps.` prefix accesses            | ~124                     | 0                        |
-
-## Related issues
-
-- #144 — Consolidate observation model
-- #145 — Decompose execute and push ExtensionContext to boundary
-- #146 — Narrow UI context for menu handlers
-- #147 — Inject text wrapping into ConversationViewer
-- #148 — Split AgentWidget rendering

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0001-deferred-patches.md

@@ -1,80 +0,0 @@
----
-status: superseded
-date: 2026-05-11
----
-
-# 0001 — Deferred fork patches and upstream-PR strategy
-
-## Status
-
-Superseded by [`docs/architecture/architecture.md`](../architecture/architecture.md), which commits to a hard fork with material scope reduction (scheduling removal, `SubagentsAPI` boundary, `index.ts` decomposition).
-The original rationale below remains useful context.
-
-## Context
-
-This fork was created to land three pieces of work identified during RepOne issue [#442](https://github.com/Tiny-IG-Software/repone/issues/442):
-
-1. **Peer-dep rename** — `@mariozechner/pi-*` → `@earendil-works/pi-*`.
-2. **Patch 2 — Re-activate extension tools post-`bindExtensions`** (Spike 3 finding).
-3. **Patch 3 — Inject `<active_agent>` tag** (Spike 4 finding).
-
-A fourth piece of work was scoped during the same spike round but deferred:
-
-- **Patch 1 — Mirror parent's `additionalExtensionPaths` (and siblings) into the child's `DefaultResourceLoader`** (Spike 2 finding).
-
-This ADR records why Patch 1 was deferred and the strategy for upstream PRs back to [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
-
-## Decision
-
-### Patch 1 is deferred
-
-The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`.
-The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
-
-During planning for this fork, two implementation constraints surfaced:
-
-1. The parent's `DefaultResourceLoader.additionalExtensionPaths` is **private** — no public getter on `ExtensionContext`.
-2. The parent's CLI flags (e.g., `pi -e <path>`) are parsed in `main.js` and not surfaced through any extension API.
-
-A working patch would have to either:
-
-- Accept new fields in `RunOptions` so callers supply the paths explicitly, **or**
-- Reach into `process.argv` to re-resolve `-e`/`--extensions` flags from the child's perspective.
-
-Neither matches the production need.
-For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration.
-The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
-
-We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream.
-A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
-
-### Upstream PRs are open
-
-All three divergences now have upstream PRs, opened after production validation in RepOne:
-
-1. **Peer-dep migration** — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (`fix(deps)!: migrate from deprecated @mariozechner/pi-* to @earendil-works/pi-*`)
-2. **Post-bind re-filter** — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72) (`fix(agent-runner): re-filter active tools after bindExtensions so extension tools land in child`)
-3. **Active-agent tag** — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73) (`feat(prompts): inject <active_agent name="..."/> tag for permission resolution`)
-
-If these land upstream, upstream gains the peer-dep fix and the two RepOne patches.
-However, the fork now diverges intentionally beyond those patches — see [`docs/architecture/architecture.md`](../architecture/architecture.md) for the full scope of planned changes.
-
-## Consequences
-
-### Positive
-
-- The fork's diff against upstream stays minimal — three patches plus tooling alignment.
-- We avoid landing a speculative Patch 1 that would need rework if upstream's `ExtensionContext` API changes.
-- Production evidence strengthened the upstream PRs.
-
-### Negative
-
-- The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands.
-  We accept this because no consumer in scope uses that pattern.
-
-### Operational
-
-- Upstream PRs are open and linked above.
-  If merged, upstream gains the three patches, but the fork continues independently with broader architectural changes per [`docs/architecture/architecture.md`](../architecture/architecture.md).
-- The architecture document governs the fork's direction going forward; this ADR's original "thin-patch" framing no longer describes the fork's trajectory.
-- When Patch 1 is eventually added, it should be a separate ADR in `docs/decisions/` with its own follow-up.