docs(graphify): knowledge-graph codebase audit findings

[vibegui]

Summary

A one-off structural audit of the monorepo, generated by building a
graphify knowledge graph of the
code and sending targeted audit agents into the hotspots the graph surfaced.
Adds a single doc — GRAPHIFY_FINDINGS.md — with the findings below. No code
changes; the graph artifacts (27MB graph.json / 23MB graph.html) are
deliberately not committed to avoid permanent repo bloat (reproduction
steps are in the doc).

Method. The code graph is deterministic (tree-sitter AST, no LLM, nothing
left the machine): 2,764 files → 16,839 nodes / 44,925 edges, 99% of edges
EXTRACTED vs 1% INFERRED. The graph's affected/path/explain
traversals identified the load-bearing hubs and complexity hotspots; those
exact files were then read and audited. Every finding cites file:line.

The doc/PDF/image semantic layer (249 docs + 96 images) was not ingested —
the graphify claude extraction backend needs ANTHROPIC_API_KEY; only
community labeling used the local CLI. Re-run with a key to include it.

Architecture at a glance

The graph recovered Studio's shape from imports/calls alone. Largest labeled
communities: MCP UI Resources & Client Hooks (248), Dialog UI Components
(214), Tool IO Types (209), Tool Definition & OAuth Providers (166), MCP Proxy Factory (161). Load-bearing hubs are exactly the documented ones —
StudioContext (blast radius 152), defineTool() (imported by 143 tool
files), cn()/Button(). No direct circular imports. Codebase is heavily
UI-weighted.

🔴 High — real bug risk

1. Synchronous network git on the sandbox daemon request path — packages/sandbox/daemon/git/rebase-onto-base.ts:283,297,331,357
rebaseOntoBase() (via routes/git.ts:693) runs fetch/push --force/rebase through spawnSync (git-sync.ts:33). Violates CONTRIBUTING rule #1: freezes the single Bun event loop for seconds→30s, the /health probe misses, and Studio tears the sandbox down mid-rebase. gitAsync already exists (git/git-async.ts) — rebase was never migrated.

2. Uncapped synchronous file read in the daemon fs route — packages/sandbox/daemon/routes/fs.ts:173-174
readFileSync + .split("\n") with no size ceiling (images capped at 5MB, text isn't) blocks the loop twice. The branch-status.ts monitor (:215,244, on the fs.watch/poll path) and glob walk (:751,910) are also sync — while upload/download in the same file were already made async.

3. Permanent setup failures thrown as plain Error → automations re-fire forever — apps/mesh/src/api/routes/decopilot/dispatch-run.ts:974,1073,1092
"Model not allowed", "not allowed to write to thread", and async-research-model-in-wrong-slot throw plain Error, not PermanentRunError. The automation workflow (automations/dbos-workflow.ts:463) only deactivates on isPermanentRunError, so a cron automation pinned to a now-disallowed model fails identically every tick forever, burning a run each time.

🟠 Medium — security-adjacent & correctness

4. Full-access (*:*) MCP key leaked on aborted dispatch — dispatch-run.ts:347,358 (leak paths :1953,2013)
mintMcpEndpoint creates a {"*":["*"]} / 1h-TTL key before the payload-size and org-slug gates. On either failure the wildcard key is never revoked and stays live up to an hour.

5. SSO check does an uncached DB query on every authenticated request — apps/mesh/src/api/app.ts:1723 → storage/org-sso-config.ts:11
getByOrgId is an uncached selectFrom run for every org+user request, even when SSO isn't enforced (the common case). Fix: short-TTL cache like the adjacent memberRoleCache.

6. resolveOrgFromPath registered twice for the same hot route — app.ts:1698 and app.ts:1906
No early-return, so every /api/:org/files/* request does the org lookup + rebind twice. Delete L1906.

🟡 Complexity / simplification

7. 7 confirmed hand-rolled @decocms/std violations — SSE reconnect backoff without jitter (web/components/sandbox/hooks/sandbox-events-context.tsx:488 → exponentialBackoffWithJitter) + 6 Promise-wrapped setTimeout sleeps (cli/lib/port-wait.ts:32, sandbox/server/provider/agent-sandbox/client.ts:410,512, harnesses/decopilot/built-in-tools/cluster-research-job.ts:272, web/components/monaco/index.ts:71, web/components/sandbox/preview/preview.tsx:777) → sleep.

8. mountLegacy boilerplate copy-pasted 9× — app.ts L1747/1811/1817/1824/1912/1928/1954/1973/1989. Each hand-types a mountPath string that must match its mount arg; a stale copy silently mislabels deprecation logs. A mountLegacy(app, path, routes) helper removes the footgun.

9. Two un-cleared timers — app.ts:1644 (24h API-key setInterval never cleared → leaks stale-pool closures across dev HMR/tests; sibling sweeper is disposed) and app.ts:216 (rejectAfter 5s health-probe setTimeout never cleared).

🟢 Dead code

createDesktopSubtaskDispatcher (packages/harness/src/decopilot/built-in-tools/desktop-subtask-dispatcher.ts:48) — zero inbound edges, grep confirms 1 occurrence total. Genuinely dead.

Suggested order

1. Migrate rebase-onto-base.ts + routes/fs.ts + branch-status.ts off sync fs/spawn (feat: Genesis #1, chore: add agents #2).
2. Make the three setup failures PermanentRunError (Chore: migrate chat and agent-settings #3).
3. Revoke the leaked *:* key ([Bug] New Agents get created without any Core Tool available #4).
4. Batch the rest into a cleanup PR.

Testing notes

Docs-only change — no code touched, no tests affected. Findings are line-cited for follow-up PRs; nothing here is applied.

🤖 Generated with Claude Code

---

Summary by cubic

Adds GRAPHIFY_FINDINGS.md, a docs-only report from a graphify knowledge-graph audit of the monorepo. It surfaces high-risk sync git/file I/O on the sandbox daemon path, non-permanent automation errors that cause infinite retries, and a leaked wildcard MCP key, plus small cleanup items; graph artifacts are omitted with repro steps included, and no code is changed.

^{Written for commit 5013265. Summary will update on new commits.}