AGENTS.md@packages/kb-plugin/src/server git:20260911.49bcd3bA

Immutable. This exact content is served forever at /api/v1/blob/a6120a7a3b24d98f.

# DOX — packages/kb-plugin/src/server

Files in this directory. One row per source file. See change: add-kb-folder-slot.

| File | Purpose |
|------|---------|
| `index.ts` | Server entry `registerPlugin`. Mounts `/api/kb/*` routes via `mountKbRoutes`. Consumes host service `host.knownFolderCwds` for cwd validation; falls back to session cwds. See change: add-kb-folder-slot. Registers a `plugin_action` handler: `reindex` → `registry.start(cwd,()=>reindexAll(cwd))`; `config.set` → `applyConfigPatch(cwd,patch)` (+ optional reindex); both guarded by `isAllowedCwd` (same allow-list as routes), dispatching the SAME cores (no HTTP re-entry). See change: fix-plugin-action-fanout-and-handlers. |
| `job-registry.ts` | `KbJobRegistry`. Per-cwd reindex coalescing. `start` sets running synchronously; concurrent start coalesced onto in-flight promise. `statusFor` → `idle|running|error`. Failed job retains `error`; later success clears to idle. See change: add-kb-folder-slot. |
| `kb-routes.ts` | `mountKbRoutes(fastify, {knownCwds, registry})`. Routes GET `/api/kb/stats`, POST `/api/kb/reindex`, GET/PUT `/api/kb/config`. Reuses `loadConfig`/`SqliteFtsStore`/`indexSource`/`validateConfig`. Validates cwd ∈ knownCwds (403 else, 400 missing); `canonPath` realpath-canonicalizes BOTH sides (symlink match); `mainCheckoutPath` (was `worktreeMainPath`) anchors admission on shared `checkoutRoots({cwd, timeout:200}).mainCheckout` and keeps it ONLY when `isBoundCheckout(main, roots.commonDir, {timeout:200})` — binding re-resolves the candidate and requires the same common dir, so a repository-local `core.worktree` naming an unrelated KNOWN folder cannot admit an unknown cwd. 200ms × up to 10 SYNC probes (5 resolve + 5 bind) holds the superseded single-2000ms worst-case event-loop block; timeout → no result → reject, never admit. A request cwd with a `.git` SEGMENT is rejected BEFORE both admission paths (incl. the direct known-folder match) — an AUTHORIZATION consumer must judge the verbatim `core.worktree` the resolver returns. Breadth preserved (`/repo/src` admitted via `/repo`). Submodule resolves to its OWN checkout → no superproject inheritance; worktree-of-bare → `null` → 403; `--separate-git-dir` no longer admitted via the unrelated dir holding its git dir (closed over-admission). See change: add-git-checkout-root-resolver; widen-containment-to-resolved-checkout. `countStale` reads `dox-staleness.json` (source-file drift only). `applyConfigPatch` merges path fields over project file, validateConfig then atomic tmp+rename write; sparse merged object persisted (untouched fields round-trip). Reindex session-less (no pi session). POST reindex NON-BLOCKING: registers job, attaches `promise.catch(fastify.log.error)` synchronously, returns `202 {status:"running",jobId}` immediately (never awaits walk / no 500 body); walk failure surfaces via `/stats` `jobStatus:"error"`+`lastError`. Exports `isAllowedCwd(cwd,known)` (pure cwd guard, refactored out of `rejectCwd`), `reindexAll`, `applyConfigPatch`, `projectConfigPath` for reuse by the plugin_action handler. See change: add-kb-folder-slot; fix-kb-index-feedback; fix-kb-worktree-cwd-guard; fix-plugin-action-fanout-and-handlers. |