fix(app): make first-run setup fast, non-blocking, and configurable

[siracusa5]

Summary

• Fixes the first-run setup hang by indexing sources in background jobs and returning partial, explicitly marked graph results while work continues.
• Runs the engine in an isolated Electron utilityProcess, keeping folder walks, parsing, tokenization, and MCP work off the UI thread.
• Adds user-configurable indexing limits, a Files browser/editor, authenticated image/PDF previews, and safe typed-data Markdown rendering.
• Reconciles the branch with current main, including the GitHub source adapter and its tests.
• Updates the Mac app icon and the affected contributor, architecture, and manifest documentation.

Adversarial review fixes

• Removed the per-launch API bearer from renderer process arguments. The engine now sends it to the main process over its message port, and the sandboxed preload retrieves it through exact-window, exact-origin trusted IPC.
• Required an explicit trusted-command acknowledgement at the MCP mutation API, validated command/argument shapes, and made the no-shell spawn boundary explicit; direct manifests remain intentionally trusted MCP configuration.
• Prevented stale editor sessions from overwriting external disk edits by adding revision-aware saves with 409 Conflict responses.
• Prevented in-flight saves, file switches, sidebar navigation, and background refreshes from discarding or replacing an unsaved draft.
• Made settings changes refresh the resolved cascade and fixed a graph/resolve-all race that could leave a stale indexing banner behind.
• Added cooperative cancellation for timed-out, superseded, removed, and closed indexing jobs.
• Enforced safety ceilings on environment-based indexing limits while retaining small values for constrained and test environments.
• Bounded raw previews to 25 MB, restricted them to images/PDFs, streamed approved bytes, used the canonical guarded path, added nosniff/CSP headers, and forced direct SVG navigation to download.
• Stopped oversized request bodies from continuing to accumulate after rejection.
• Made the setup completion message distinguish a genuinely empty cascade from one still indexing.
• Updated the site lockfile to patched PostCSS and SVGO releases; production dependency audits for console, desktop, and site now report zero vulnerabilities.

Behavior changes worth a reviewer's attention

Reads are partial by design. /api/graph and /api/resolve-all return what is currently indexed and set indexing / indexingSources. Clients render available data and poll. Tests or clients that require a settled snapshot can pass ?wait=<ms>.

Add-source validation is deliberately cheap. Missing paths and non-directory paths fail immediately. Large folders are accepted quickly, then become visible source errors with an actionable Settings path if they exceed configured limits.

Settings precedence is manifest > environment > default. App changes therefore take effect rather than being silently shadowed by an inherited environment variable.

An unexpected engine exit is fatal. A loaded window cannot be pointed at a replacement loopback origin, so the app uses the same clean dialog-and-exit path as a boot failure.

Affected area

• Core engine / MCP / write path
• Console
• Desktop app
• Site and dependency lockfile
• Playground and local demo surfaces
• Docs / specs / contributor workflow
• Packs

Validation

• npm test — all 13 root suites pass
• npm run demo:verify
• Console: typecheck, 123 tests, production build
• Desktop: 34 unit tests, navigation, CLI-status, smoke, boot-failure smoke, and engine-isolation test
• Site: production build and install-page verification
• npm audit --omit=dev — zero production vulnerabilities in console, desktop, and site

The isolation test boots the real app against 2,500 temporary documents and fails if indexing stalls the Electron main loop. The setup robustness suite covers bounded walks, limit settings, partial reads, cancellation, editor revision conflicts, index refreshes, and usable-while-indexing behavior.

Compatibility

• No root npm dependencies were added.
• Root commands remain unchanged except for the added regression suite in npm test.
• The console Markdown path produces typed data and React text nodes; it has no HTML-string sink.
• Generated desktop icon artifacts are intentionally committed from the canonical brand source.

Two follow-ups remain intentionally out of scope: tokenizer initialization still blocks its isolated engine process once, and the Files view remains edit-only (no create/delete), matching the existing write posture.

[siracusa5]

Code review

Self-review of this branch, plus the critical CodeQL alert on the changed code. Seven issues found; all are fixed in b45f157. Four open observations are recorded at the end for a human to weigh — none of them block.

Security

Critical — the Markdown renderer built an HTML string and handed it to dangerouslySetInnerHTML. File content is untrusted input, so this was a hand-rolled sanitizer feeding an injection sink. The escaping ordering was correct as far as I could test it, but "my sanitizer looks right" is the argument that ages badly, and it is almost certainly what CodeQL flagged.

Replaced rather than defended: markdown.ts now parses to typed data and never emits HTML; components/Markdown.tsx renders that data as React elements. Document text reaches the DOM as text nodes, so it cannot be markup by construction. dangerouslySetInnerHTML no longer appears anywhere in the codebase, and the escaping helper is gone with it. URL filtering stays, since a javascript: href is dangerous even inside a properly created element.

Markdown.test.tsx asserts against a real DOM that a <script> payload creates no script element, an onerror payload creates no img element, and a crafted link title cannot add an attribute.

I could not read the alert body directly — there is no code-scanning tool in this environment and the alerts page requires auth — so the mapping to the CodeQL rule is inferred. If the alert survives this push it is something else (most likely js/path-injection on the layer file APIs, which are guarded by the pre-existing assertInsideRoot realpath check and were flagged only because the code moved in this PR).

Correctness

The index went stale — the worst bug here. Editing a file updated /api/resolve but not /api/graph or /api/resolve-all. A file edit does not change the manifest, so the index key was unchanged and the pre-edit snapshot was reused indefinitely. Edits made outside the app never appeared at all, which is a regression from the previous read-on-every-request behavior. Confirmed by experiment before fixing:

-- after in-app edit:      /api/resolve → EDITED     /api/resolve-all → ORIGINAL
-- after external edit:    /api/resolve → EXTERNAL   /api/resolve-all → ORIGINAL

Writes now invalidate the affected layer, and disk-backed layers are watched (debounced) so external edits and new files land on their own. The previous snapshot keeps serving during a re-index, so nothing blinks empty.

Infinite loop on nested inline markup. parseInline recursed on a module-level /g regex, so the inner call reset lastIndex and the outer scan restarted from zero forever. Any nested emphasis or link inside a link would hang the renderer. Caught by the new tests (the suite hung), now pinned by an explicit regression test.

**bold *with italic* inside** did not parse — the strong pattern could not span a single asterisk, so it fell back to literal asterisks.

Polynomial backtracking in the table-divider regex ([\s:|-]+\|[\s:|-]* — the delimiter is inside the repeated class). Rewritten to a single unambiguous class, with a timing test on a 4,000-character divider.

UX

A failed background poll left the "Indexing…" banner running forever with nothing left to clear it — which reads as exactly the hang this branch removes. Transient failures now retry with backoff, then stop claiming work is in flight.

Tests

A fixture collision — new freshness assertions wrote into a folder a later test counted documents in, making that test order-dependent. Given its own folder.

Test coverage otherwise looks sound to me: the two headline claims are measured rather than asserted (/api/graph answering in ~6ms mid-index; main-loop lag ~30ms isolated vs ~694ms sharing the loop), and the isolation threshold sits between the two measurements so it genuinely fails if the work moves back.

Open observations — not fixed, for a human call

1. Index memory is now resident. Snapshots hold every parsed concept for the life of the process; previously they were per-request and collected. The 1,500-document fixture indexes to ~861k tokens of retained text — order tens of MB, and roughly linear in corpus size. It sits in the engine process now so it cannot take the UI down, and maxDocFiles bounds it, but a large real corpus is worth measuring before release.
2. CLOSE_GRACE_MS (15s) is shorter than the default source budget (30s). When the adapter set is rebuilt, an in-flight index holding the old adapters can have its MCP child killed at 15s even though its budget allows 30. Narrow — it needs an MCP source indexing longer than 15s while an unrelated manifest edit lands — and the entry is usually discarded anyway, but the two constants should probably be related rather than independent.
3. fs.watch recursion is platform-dependent. macOS (the desktop target) and Windows watch recursively; Linux does not, so a nested external edit is missed there. Writes through the API always invalidate explicitly, so the watcher is a convenience rather than the only path to freshness — noted in the code.
4. The ~800ms tokenizer init is still a synchronous block, now inside the engine process at boot rather than on the UI thread. Harmless where it is; it would matter if the engine ever needed to answer during startup.

---

Generated by Claude Code