docs: sync architecture/structure with v0.49 train (pattern-watch persistence, tool-registration modules, bridge path-aliases/error-contract)

Author: ualtinok

ARCHITECTURE.md

@@ -17,21 +17,21 @@
 **OpenCode integration layer:**
 - Purpose: Register tools, load config, and attach post-execution metadata.
 - Location: `packages/opencode-plugin/src/index.ts`
-- Contains: Plugin bootstrap, tool-surface selection, hoisting logic, disabled-tool filtering, session-directory management, RPC server (exposing a live WebSocket endpoint for TUI notification and status invalidation pushes), auto-update checker hook
+- Contains: Plugin bootstrap, tool-surface selection, tool registration map builder (`packages/opencode-plugin/src/tool-registration.ts`), hoisting logic, disabled-tool filtering, session-directory management, RPC server (exposing a live WebSocket endpoint for TUI notification and status invalidation pushes), auto-update checker hook
 - Depends on: `packages/opencode-plugin/src/config.ts`, `packages/opencode-plugin/src/tools/*.ts`, `packages/aft-bridge/`
 - Used by: OpenCode plugin loading through `@cortexkit/aft-opencode`
 
 **Pi integration layer:**
 - Purpose: Register tools, load config, and manage Pi host notifications.
 - Location: `packages/pi-plugin/src/index.ts`
-- Contains: Plugin bootstrap, tool-surface selection, hoisting logic, LSP auto-install (npm/github/project-relevance probes), `aft-status` command
+- Contains: Plugin bootstrap, tool-surface selection, tool registration helper (`packages/pi-plugin/src/tool-registration.ts`), hoisting logic, LSP auto-install (npm/github/project-relevance probes), `aft-status` command
 - Depends on: `packages/pi-plugin/src/config.ts`, `packages/pi-plugin/src/tools/*.ts`, `packages/pi-plugin/src/commands/*.ts`, `packages/aft-bridge/`
 - Used by: Pi coding agent through `@cortexkit/aft-pi`
 
 **Shared bridge layer:**
 - Purpose: Resolve or download the binary, start worker processes, manage ONNX runtime, format output, select and manage the transport pool, and forward requests. All harness adapters share this layer.
-- Location: `packages/aft-bridge/src/bridge.ts`, `packages/aft-bridge/src/pool.ts`, `packages/aft-bridge/src/subc-transport.ts`, `packages/aft-bridge/src/transport.ts`, `packages/aft-bridge/src/transport-factory.ts`, `packages/aft-bridge/src/resolver.ts`, `packages/aft-bridge/src/downloader.ts`, `packages/aft-bridge/src/onnx-runtime.ts`, `packages/aft-bridge/src/migration.ts`, `packages/aft-bridge/src/zoom-format.ts`
-- Contains: Transport factory routing selection (via user-tier `subc.connection_file`), subc client connection pooling, route caching per session-identity, background event subscriptions with independent reconnects, session bridge lifecycle, restart handling, version checks, binary discovery, binary download, ONNX runtime detection, storage migration, compact UI formatting, active logger, wait-aware transport budgets propagation (mapping `transportTimeoutMs` to route requests to avoid premature client-side timeouts during long command execution)
+- Location: `packages/aft-bridge/src/bridge.ts`, `packages/aft-bridge/src/pool.ts`, `packages/aft-bridge/src/subc-transport.ts`, `packages/aft-bridge/src/transport.ts`, `packages/aft-bridge/src/transport-factory.ts`, `packages/aft-bridge/src/resolver.ts`, `packages/aft-bridge/src/downloader.ts`, `packages/aft-bridge/src/onnx-runtime.ts`, `packages/aft-bridge/src/migration.ts`, `packages/aft-bridge/src/zoom-format.ts`, `packages/aft-bridge/src/path-aliases.ts`, `packages/aft-bridge/src/error-contract.ts`
+- Contains: Transport factory routing selection (via user-tier `subc.connection_file`), subc client connection pooling, route caching per session-identity, background event subscriptions with independent reconnects, session bridge lifecycle, restart handling, version checks, binary discovery, binary download, ONNX runtime detection, storage migration, compact UI formatting, active logger, wait-aware transport budgets propagation (mapping `transportTimeoutMs` to route requests to avoid premature client-side timeouts during long command execution), canonical path alias resolution (`packages/aft-bridge/src/path-aliases.ts`), and host-neutral error adaptation (`packages/aft-bridge/src/error-contract.ts`)
 - Depends on: Node child-process APIs, GitHub releases, `onnxruntime-node`, `@cortexkit/subc-client`
 - Used by: `packages/opencode-plugin/src/index.ts`, `packages/pi-plugin/src/index.ts`
 
@@ -73,7 +73,7 @@
 **State and diagnostics layer:**
 - Purpose: Hold per-process mutable state for backups, checkpoints, file watching, call graph cache, LSP state, database storage, bash background tasks, cache freshness tracking, file-system locking, and root-keyed writer leases.
 - Location: `crates/aft/src/context.rs`, `crates/aft/src/backup.rs`, `crates/aft/src/checkpoint.rs`, `crates/aft/src/lsp/`, `crates/aft/src/db/`, `crates/aft/src/cache_freshness.rs`, `crates/aft/src/fs_lock.rs`, `crates/aft/src/bash_background/`, `crates/aft/src/callgraph_store/mod.rs`, `crates/aft/src/response_finalize.rs`, `crates/aft/src/artifact_owner.rs`, `crates/aft/src/readonly_artifacts.rs`, `crates/aft/src/root_cache.rs`, `crates/aft/src/legacy_partitions.rs`
-- Contains: `AppContext` with symlink path verification checks (recursively following chain hops to reject escaping paths), Windows verbatim path normalization via `canonicalize_normalized` to eliminate path comparison asymmetry, undo history, backup policies and disk-locking handlers, named checkpoints, watcher receiver, LSP manager, diagnostics store (which tracks and masks watcher-stale diagnostics for caching and pull reuse, and tracks newly-opened documents during pull diagnostics to automatically close them when the scoped collection drops while draining events to prevent queue buildup), document store, persistent database tables (backups, bash tasks, compression events, state, callgraph edges and nodes), cache-freshness tracker (which tracks file metadata and utilizes verification tickets to prevent race conditions during concurrent file invalidation between verify and completion steps), file-system lockfile, background task registry, PTY process pool, callgraph store background channels, main-loop pending responses registry, root-keyed writer leases and reader marker file coordination (protecting active reader processes from index removal), and legacy harness coexistence guards (refusing writes into legacy layout partitions and validating migration space thresholds), and `borrowed_index_cache` (which caches up to 4 read-only borrowed index search/semantic artifacts and resolved external git roots to optimize concurrent external search operations)
+- Contains: `AppContext` with symlink path verification checks (recursively following chain hops to reject escaping paths), Windows verbatim path normalization via `canonicalize_normalized` to eliminate path comparison asymmetry, undo history, backup policies and disk-locking handlers, named checkpoints, watcher receiver, LSP manager, diagnostics store (which tracks and masks watcher-stale diagnostics for caching and pull reuse, and tracks newly-opened documents during pull diagnostics to automatically close them when the scoped collection drops while draining events to prevent queue buildup), document store, persistent database tables (backups, bash tasks, pattern watches via `crates/aft/src/db/bash_watches.rs`, compression events, state, callgraph edges and nodes), cache-freshness tracker (which tracks file metadata and utilizes verification tickets to prevent race conditions during concurrent file invalidation between verify and completion steps), file-system lockfile, background task registry, PTY process pool, callgraph store background channels, main-loop pending responses registry, root-keyed writer leases and reader marker file coordination (protecting active reader processes from index removal), and legacy harness coexistence guards (refusing writes into legacy layout partitions and validating migration space thresholds), and `borrowed_index_cache` (which caches up to 4 read-only borrowed index search/semantic artifacts and resolved external git roots to optimize concurrent external search operations)
 - Depends on: `notify`, LSP transport helpers, Rust `RefCell`, SQLite (via `db/` and `callgraph_store/`), `serde`
 - Used by: All command handlers through `AppContext`
 

STRUCTURE.md

@@ -78,14 +78,14 @@ opencode-aft/
 - Key files: `crates/aft/src/executor/mod.rs`, `crates/aft/src/executor/tests.rs`
 
 **`crates/aft/src/bash_background/`:**
-- Purpose: Manage background bash tasks, PTY sessions, and output compression.
-- Contains: Process pool, PTY runtime, watchdog thread, persistence, buffer management
-- Key files: `crates/aft/src/bash_background/registry.rs`, `crates/aft/src/bash_background/process.rs`, `crates/aft/src/bash_background/pty_process.rs`, `crates/aft/src/bash_background/watchdog.rs`
+- Purpose: Manage background bash tasks, PTY sessions, async pattern watches, and output compression.
+- Contains: Process pool, PTY runtime, watchdog thread, persistence, buffer management, async pattern watches
+- Key files: `crates/aft/src/bash_background/registry.rs`, `crates/aft/src/bash_background/process.rs`, `crates/aft/src/bash_background/pty_process.rs`, `crates/aft/src/bash_background/watchdog.rs`, `crates/aft/src/bash_background/watches.rs`
 
 **`crates/aft/src/db/`:**
-- Purpose: Provide persistent SQLite-backed storage for backups, bash tasks, compression events, and state.
+- Purpose: Provide persistent SQLite-backed storage for backups, bash tasks, pattern watches, compression events, and state.
 - Contains: Database modules for each storage domain
-- Key files: `crates/aft/src/db/mod.rs`, `crates/aft/src/db/backups.rs`, `crates/aft/src/db/bash_tasks.rs`, `crates/aft/src/db/compression_events.rs`, `crates/aft/src/db/state.rs`
+- Key files: `crates/aft/src/db/mod.rs`, `crates/aft/src/db/backups.rs`, `crates/aft/src/db/bash_tasks.rs`, `crates/aft/src/db/bash_watches.rs`, `crates/aft/src/db/compression_events.rs`, `crates/aft/src/db/state.rs`
 
 **`crates/aft/src/patch/`:**
 - Purpose: Implement patch parsing, sequence matching, fuzzy hunk matching, and update execution.
@@ -99,8 +99,8 @@ opencode-aft/
 
 **`packages/aft-bridge/`:**
 - Purpose: Ship the shared bridge transport layer used by both OpenCode and Pi plugins.
-- Contains: Transport factory routing selection (via user-tier `subc.connection_file`), subc client connection pooling, session lifecycle records caching (`SessionRecord` wrapping route entry and bg subscriptions), background event subscriptions, bridge lifecycle management, binary resolution, download, ONNX runtime detection, storage migration, compact formatting, zoom-format rendering
-- Key files: `packages/aft-bridge/src/bridge.ts`, `packages/aft-bridge/src/pool.ts`, `packages/aft-bridge/src/subc-transport.ts`, `packages/aft-bridge/src/transport.ts`, `packages/aft-bridge/src/transport-factory.ts`, `packages/aft-bridge/src/resolver.ts`, `packages/aft-bridge/src/downloader.ts`, `packages/aft-bridge/src/onnx-runtime.ts`, `packages/aft-bridge/src/migration.ts`
+- Contains: Transport factory routing selection (via user-tier `subc.connection_file`), subc client connection pooling, session lifecycle records caching (`SessionRecord` wrapping route entry and bg subscriptions), background event subscriptions, bridge lifecycle management, binary resolution, download, ONNX runtime detection, storage migration, compact formatting, zoom-format rendering, canonical path alias resolution, and host-neutral error adaptation
+- Key files: `packages/aft-bridge/src/bridge.ts`, `packages/aft-bridge/src/pool.ts`, `packages/aft-bridge/src/subc-transport.ts`, `packages/aft-bridge/src/transport.ts`, `packages/aft-bridge/src/transport-factory.ts`, `packages/aft-bridge/src/resolver.ts`, `packages/aft-bridge/src/downloader.ts`, `packages/aft-bridge/src/onnx-runtime.ts`, `packages/aft-bridge/src/migration.ts`, `packages/aft-bridge/src/path-aliases.ts`, `packages/aft-bridge/src/error-contract.ts`
 
 **`packages/aft-cli/`:**
 - Purpose: Provide a unified `npx @cortexkit/aft` CLI entry point for setup, doctor, and LSP management across all harnesses.
@@ -110,7 +110,7 @@ opencode-aft/
 **`packages/opencode-plugin/`:**
 - Purpose: Ship the OpenCode-facing package that resolves the binary and registers tools.
 - Contains: `src/` TypeScript sources, `src/tools/` tool definitions, `src/shared/` shared utilities, `src/hooks/` lifecycle hooks, `src/tui/` TUI plugin, `__tests__/` unit and e2e tests, package manifest
-- Key files: `packages/opencode-plugin/src/index.ts`, `packages/opencode-plugin/src/config.ts`, `packages/opencode-plugin/package.json`
+- Key files: `packages/opencode-plugin/src/index.ts`, `packages/opencode-plugin/src/config.ts`, `packages/opencode-plugin/src/tool-registration.ts`, `packages/opencode-plugin/package.json`
 
 **`packages/opencode-plugin/src/tools/`:**
 - Purpose: Group OpenCode tool definitions by capability area.
@@ -120,7 +120,7 @@ opencode-aft/
 **`packages/pi-plugin/`:**
 - Purpose: Ship the Pi coding-agent facing package that resolves the binary and registers tools.
 - Contains: `src/` TypeScript sources, `src/tools/` tool definitions, `src/commands/` Pi-specific commands, `src/dialogs/` Pi dialog handlers, `src/shared/` shared utilities, `__tests__/` unit and e2e tests
-- Key files: `packages/pi-plugin/src/index.ts`, `packages/pi-plugin/src/config.ts`, `packages/pi-plugin/src/types.ts`, `packages/pi-plugin/src/tools/hoisted.ts`
+- Key files: `packages/pi-plugin/src/index.ts`, `packages/pi-plugin/src/config.ts`, `packages/pi-plugin/src/tool-registration.ts`, `packages/pi-plugin/src/types.ts`, `packages/pi-plugin/src/tools/hoisted.ts`
 
 **`packages/pi-plugin/src/tools/`:**
 - Purpose: Group Pi tool definitions by capability area.