Repository navigation
tracking(cleanup): monthly scavenger sweep — 2026-09 #4726
Description
We would rather Maka did not grow heavier than it needs to be, so this opens a monthly scavenger sweep. A new one starts on the first of each month. This round runs from 2026-09-04; the next is 2026-10-01.
Maka carries about 576,000 lines of product code and 486,000 lines of test code. Very little of that is wrong. A lot of it is more than it needs to be: two implementations of one rule, a fixture rebuilt in twenty files, a 7,000-line module that grew one honest commit at a time. None of it is anyone's fault and none of it will be fixed by a rewrite. It gets fixed by someone taking one area for one month and leaving it smaller than they found it.
How to claim:
- Choose an area below, or a smaller piece of one — good refactors are welcome at any size — and check that nobody else is already on it.
- Open a new issue describing the redundancy or the weight you mean to remove, with a plan detailed enough to argue with.
- Comment on this month's issue with a link to that issue.
Areas are drawn along package and directory lines, so two claimants never need to coordinate. One person can hold several. A claim that stops moving for a long time is released, and its area goes back on the board.
What counts as done
Every claim ends in one or more pull requests that state a measured result. "Simplified X" is not a result. These are:
- a rule that had two implementations now has one, and the second is deleted;
- a type, helper or fixture that existed in N places now exists once;
- a module over 2,000 lines is split along a seam that already existed in it, with no behaviour change;
- dead code removed, with the search that proves nothing reaches it;
- a debt counter in
apps/desktop/renderer-architecture.jsongoes down.
Not results: renaming things, reformatting, moving files without reducing anything, replacing a clear loop with a clever one, or deleting a test.
Part A — product code
| # | Area | Scope | Size | Where to start |
|---|---|---|---|---|
| A1 | Storage · session metadata | packages/storage/src/sqlite-session-metadata-store.ts and its callers |
7,288 lines in one file | The largest file in the repository. The read face and the write face barely touch. |
| A2 | Storage · runtime store and policy | sqlite-runtime-store.ts, runtime-policy/, agent-run-store.ts |
~11,000 lines | Three files above 2,000 lines each. |
| A3 | Storage · everything else | the remaining 118 top-level files | ~44,000 lines | 121 files sit flat at the top level with almost no grouping. |
| A4 | Runtime · session kernel | session-manager.ts, runtime-kernel.ts |
9,005 lines | Two cores that grew together. |
| A5 | Runtime · provider backend | ai-sdk-backend.ts, model-*.ts |
~8,000 lines | 4,930 lines in one file, changed constantly. |
| A6 | Runtime · tool runtime | tool-runtime.ts, computer-use-tools.ts |
6,881 lines | Two files near 3,000 lines. |
| A7 | Runtime · everything else | the remaining ~250 files | ~90,000 lines | Compaction, context, permissions. Large enough to split further — say so when claiming. |
| A8 | Runtime Host · server coordinators | packages/runtime-host/src/server/, 130 files |
~50,000 lines | Several coordinators above 2,000 lines. |
| A9 | Runtime Host · everything else | peer mesh, client, protocol, operator | ~50,000 lines | peer-mesh/node.ts is 2,426 lines. |
| A10 | Core | packages/core/src, 157 files |
51,620 lines | Types and contracts. Simplification here pays out in every other area. |
| A11 | Desktop · main process | apps/desktop/src/main/, 190 files |
56,280 lines | Updates, Host boot, IPC. |
| A12 | Desktop · renderer | apps/desktop/src/renderer/, 393 files across 11 feature slices |
85,685 lines | The renderer ratchet already records per-file debt, so results here are countable without argument. |
| A13 | CLI and TUI | packages/cli/src, 91 files |
42,375 lines | pi-tui-runner.ts is 4,238 lines. |
| A14 | UI component library | packages/ui/src, 129 files |
31,019 lines | composer.tsx is 2,180 lines. |
| A15 | Preload and bridge | apps/desktop/src/preload/, 16 files |
6,566 lines | preload.ts alone is 3,754 lines and is the only channel between main and renderer. Narrowing it pays on both sides. |
| A16 | Architecture documents | docs/architecture/, 31 files |
— | Several are kept in two languages, and drift between a document and its implementation has been found more than once. Reconcile or retire. |
Part B — test code
Tests are 486,000 lines across 1,942 files. In packages/runtime there is more test than source. This half needs its own rules, because the obvious way to make a test suite smaller is to make it prove less.
| # | Area | Scope | Size | Where to start |
|---|---|---|---|---|
| T1 | Runtime backend and kernel tests | ai-sdk-backend.test.ts (16,206), session-manager.test.ts (14,887) |
31,000 lines in two files | Both are over three times the size of what they test. |
| T2 | Runtime · remaining tests | 229 files | ~106,000 lines | Test-to-source ratio 1.22, the highest in the repository. |
| T3 | Runtime Host coordinator tests | root-turn-coordinator (6,451), message-coordinator (4,041), host-kernel (3,848) and neighbours |
~30,000 lines | 21 fixture files here; much of the setup repeats. |
| T4 | Runtime Host · remaining tests | ~170 files | ~74,000 lines | |
| T5 | Storage tests and fixtures | 112 files including 28 fixtures | 50,578 lines | The most fixture-heavy package; table setup is rebuilt repeatedly. |
| T6 | CLI and TUI tests | pi-tui-runner.test.ts (10,499), pi-transcript.test.ts (5,187) |
41,784 lines | |
| T7 | Desktop tests | 290 files across main and renderer | 80,576 lines | |
| T8 | End-to-end, stories and scripts | e2e 37 files (7,423), stories 16 files (10,171), scripts/*.test.mjs 44 files (12,375) |
~30,000 lines | e2e flakiness is a standing cost; three separate flakes surfaced in one week of recent work. |
packages/core and packages/ui have ratios of 0.40 and 0.31 and are thin rather than heavy, so their tests stay with A10 and A14 rather than becoming their own areas.
Acceptance for Part B
The same measured-result rule applies, with three additions, because a smaller suite is not automatically a better one.
- Coverage may not fall. A deleted test is only a result when a named other test already proves the same thing, and the claim says which.
- Every test touched must fail without the code it tests. Remove the implementation line, watch it go red, put it back. Say in the pull request that this was done. This is not ceremony: in recent work three new tests passed against the unchanged code because a fixture default happened to satisfy them, and a reviewer found it rather than the author.
- Prefer driving the real entry point. A test that hands a value directly to an internal function still passes when the call site that produces that value is deleted. Where that is cheap to fix, fix it.
Rules
- One pull request per coherent change, not per area. A 4,000-line file does not need to be finished in one pass.
- No behaviour change. If you find a bug, open an issue and keep it out of the cleanup pull request.
- Existing gates decide the argument:
renderer-architecture, the protocol epoch check, ASF headers, lint, format, typecheck. - If an area turns out to be two areas, say so here rather than quietly widening the claim.
Carry-over
Areas nobody claims roll into next month's issue, along with whatever the current round leaves unfinished.
简体中文
我们并不希望 Maka 在非必要情况下变得过于臃肿，所以现在发起 每月进行一次的清道夫行动。 每月一号开新的一份。本轮从 2026-09-04 开始，下一轮 2026-10-01。
Maka 现在有约 57.6 万行产品代码和 48.6 万行测试代码。其中错的很少，多余的不少：同一条规则有两处实现，同一个夹具在二十个文件里各建一遍，一个七千行的模块是靠一次次诚实的提交长出来的。这不怪谁，也不会被一次重写解决。它只会被这样解决：有人认领一个板块，做一个月，走的时候让它比来时更小。
认领方式如下：
1、选择你想认领的板块（也可能是比 issue 中划分的板块更小的范围，我们欢迎各种级别的优秀重构），并确认没有其他人在处理
2、开启一个新的 issue，描述清楚现在想解决的冗余/臃肿部分，并提出详细的处理方案
3、在当前月开启的 issue 下评论并链接到你的设计 issue
对于认领但是长久没有推进的工作，我们会取消认领，并重新放开相关部分的可认领状态
怎样算做完
每次认领最终落成一个或多个 PR，PR 里要写出可度量的结果。"简化了 X"不是结果。下面这些是：
- 一条规则原本有两处实现，现在只剩一处，另一处被删除；
- 一个类型、辅助函数或夹具原本存在于 N 处，现在只有一处；
- 一个两千行以上的模块，沿着它本来就存在的接缝拆开，行为不变；
- 删除死代码，并给出"没有任何路径能到达它"的检索证据；
apps/desktop/renderer-architecture.json里的某个债务计数下降。
不算结果：改名、重排格式、只挪文件而不减少任何东西、把清楚的循环换成聪明的写法、删测试。
第一部分 · 产品代码
| # | 板块 | 范围 | 规模 | 从哪下手 |
|---|---|---|---|---|
| A1 | 存储 · 会话元数据 | packages/storage/src/sqlite-session-metadata-store.ts 及其调用方 |
单文件 7,288 行 | 全仓最大的文件，读面和写面几乎不相干 |
| A2 | 存储 · 运行时存储与策略 | sqlite-runtime-store.ts、runtime-policy/、agent-run-store.ts |
约 11,000 行 | 三个 2,000 行以上的文件 |
| A3 | 存储 · 其余 | 顶层剩余 118 个文件 | 约 44,000 行 | 121 个文件平铺在顶层，几乎没有分组 |
| A4 | Runtime · 会话内核 | session-manager.ts、runtime-kernel.ts |
9,005 行 | 两个一起长大的核心 |
| A5 | Runtime · 供应商后端 | ai-sdk-backend.ts、model-*.ts |
约 8,000 行 | 单文件 4,930 行，改动最频繁 |
| A6 | Runtime · 工具运行时 | tool-runtime.ts、computer-use-tools.ts |
6,881 行 | 两个接近 3,000 行的文件 |
| A7 | Runtime · 其余 | 剩余约 250 个文件 | 约 90,000 行 | 压缩、上下文、权限。大到应当再切分，认领时请说明 |
| A8 | Runtime Host · server 协调器 | packages/runtime-host/src/server/，130 个文件 |
约 50,000 行 | 多个 2,000 行以上的 coordinator |
| A9 | Runtime Host · 其余 | peer mesh、client、protocol、operator | 约 50,000 行 | peer-mesh/node.ts 2,426 行 |
| A10 | Core | packages/core/src，157 个文件 |
51,620 行 | 类型与契约层，这里的简化会外溢到其他所有板块 |
| A11 | Desktop · 主进程 | apps/desktop/src/main/，190 个文件 |
56,280 行 | 更新、Host 引导、IPC |
| A12 | Desktop · 渲染层 | apps/desktop/src/renderer/，393 个文件、11 个 feature 切片 |
85,685 行 | 已有渲染层债务台账逐文件记账，成果无需争辩即可计量 |
| A13 | CLI 与 TUI | packages/cli/src，91 个文件 |
42,375 行 | pi-tui-runner.ts 4,238 行 |
| A14 | UI 组件库 | packages/ui/src，129 个文件 |
31,019 行 | composer.tsx 2,180 行 |
| A15 | 预加载与桥接 | apps/desktop/src/preload/，16 个文件 |
6,566 行 | 仅 preload.ts 就 3,754 行，是主进程与渲染层之间唯一的通道，收窄它两边都受益 |
| A16 | 架构文档 | docs/architecture/，31 篇 |
— | 其中多篇维护中英两份，文档与实现漂移已不止一次被发现。要么对齐，要么退役 |
第二部分 · 测试代码
测试有 1,942 个文件、48.6 万行。在 packages/runtime 里，测试比源码还多。这一半需要自己的规则，因为让测试套件变小最省事的办法，就是让它少证明一些东西。
| # | 板块 | 范围 | 规模 | 从哪下手 |
|---|---|---|---|---|
| T1 | Runtime 后端与内核测试 | ai-sdk-backend.test.ts（16,206）、session-manager.test.ts（14,887） |
两个文件 31,000 行 | 都是被测源文件的三倍以上 |
| T2 | Runtime · 其余测试 | 229 个文件 | 约 106,000 行 | 测源比 1.22，全仓最高 |
| T3 | Runtime Host 协调器测试 | root-turn-coordinator（6,451）、message-coordinator（4,041）、host-kernel（3,848）及邻近文件 |
约 30,000 行 | 这里有 21 个夹具文件，大量准备代码重复 |
| T4 | Runtime Host · 其余测试 | 约 170 个文件 | 约 74,000 行 | |
| T5 | 存储测试与夹具 | 112 个文件，含 28 个夹具 | 50,578 行 | 夹具最重的包，建表准备被反复重建 |
| T6 | CLI 与 TUI 测试 | pi-tui-runner.test.ts（10,499）、pi-transcript.test.ts（5,187） |
41,784 行 | |
| T7 | Desktop 测试 | 主进程与渲染层共 290 个文件 | 80,576 行 | |
| T8 | 端到端、stories 与脚本 | e2e 37 个文件（7,423）、stories 16 个（10,171）、scripts/*.test.mjs 44 个（12,375） |
约 30,000 行 | e2e 抖动是长期成本，近期一周的工作里就撞上三种不同的抖动 |
packages/core 与 packages/ui 的测源比只有 0.40 和 0.31，属于偏薄而非偏重，因此它们的测试并入 A10 与 A14，不单列板块。
第二部分的验收
同样要求可度量的结果，另加三条，因为更小的套件并不自动等于更好的套件。
- 覆盖不得下降。 删掉一个测试只有在"另一个具名测试已经证明同一件事"时才算结果，并且要在 PR 里点名是哪一个。
- 动过的每个测试，去掉它所测的实现后必须失败。 把那行实现删掉，看它变红，再放回去，并在 PR 里说明做过这一步。这不是仪式：近期就出现过三个新测试在未改动的代码上照样通过，因为夹具默认值恰好满足了它们，而且是评审发现的，不是作者。
- 优先驱动真实入口。 一个把值直接喂给内部函数的测试，在产生这个值的调用点被删掉之后依然会通过。凡是修起来不贵的，就修。
规则
- 一个 PR 对应一处自洽的改动，而不是一个板块一个 PR。四千行的文件不必一次改完。
- 不改变行为。发现 bug 就单独开 issue，别混进清理 PR。
- 争议由现有门禁裁决：
renderer-architecture、协议 epoch 检查、ASF 头、lint、format、typecheck。 - 如果发现某个板块其实是两个板块，请在这里说明，而不是悄悄扩大认领范围。
顺延
无人认领的板块顺延到下个月那一份，本轮未做完的部分同样顺延。
Activity
testikun commentedon Sep 4, 2026
Hi @Joob1n, thank you for organizing this cleanup sweep.
If this area is still available, I’d like to take A6 — Runtime · tool runtime (
tool-runtime.tsandcomputer-use-tools.ts).This area is a good fit for my recent work and learning around the runtime and tool paths, including Auto tool selection (#3705), sandbox negotiation across continuations (#4308), and bounded foreground subagent tool routing (#4701). These changes have helped me become familiar with the tool registration, availability, execution, and continuation flows.
My plan is to begin with a focused inventory of duplicated responsibilities and existing module seams, then open a dedicated cleanup issue describing the specific problems, proposed boundaries, and measurable before/after outcomes. I will keep each PR behavior-preserving, focused on one coherent change, and backed by coverage-preserving tests.
I am also aware that #4308 and #4701 currently touch
tool-runtime.ts. I will avoid their continuation, sandbox-negotiation, and subagent-routing paths when selecting the first cleanup slice, and I will rebase or coordinate if any overlap remains.Please let me know if you have any concerns or would prefer a narrower starting scope. I will link the dedicated cleanup issue here once it is ready. Thank you!
Joob1n commentedon Sep 4, 2026
Thanks @testikun, and A6 is available.
Before you start cutting, please open the planning issue and link it here. That is step 2 for a reason: the plan is where we agree the change is worth making, before there is a diff to argue about. Your inventory of duplicated responsibilities and seams is exactly what it should carry, with the before/after numbers you expect.
Noting the #4308 / #4701 overlap you raised — sounds right, and the plan is a good place to name the first slice.
testikun commentedon Sep 6, 2026
@Joob1n A06 planning is tracked in #4909 — Tool Runtime refactoring discussion and implementation plan. The first implementation slice is #4908. The planning issue records the overall analysis, target architecture, staged boundaries, and measured behavior-preserving cleanup approach.
orangeCatDeveloper commentedon Sep 7, 2026
Claiming part of T1 — Runtime backend and kernel tests, scoped to
packages/runtime/src/__tests__/ai-sdk-backend.test.ts(checked: no existing claim; #3909 covers the source file, not the tests).Planning issue: #4945 — carries the measured inventory (181 repeated backend-fixture instances → 1) and the two-PR plan with the Part B acceptance mapping.
PR 1 (fixture-only dedup, net −976 lines, runtime leaf count unchanged at 222) is up as #4946. PR 2 (scenario consolidation, +1 leaf with per-guard fault evidence) follows after PR 1 merges.
DaBestCode commentedon Sep 8, 2026
Claiming part of A15 — Preload and bridge, scoped only to extracting the diagnostics bridge from apps/desktop/src/preload/preload.ts.
Planning issue: #5004
The proposed change preserves the public bridge and IPC behavior, removes at least 130 lines from the 3,890-line preload composition root, and gives diagnostics projection and validation one independently testable owner.
Totoro-qaq commentedon Sep 8, 2026
@Joob1n Claiming a focused part of A9 — Runtime Host / peer mesh, scoped to the existing control-message types and object codecs in
peer-mesh/node.ts.Planning issue: #5005. Implementation PR: #5006.
The extraction reduces
node.tsfrom 3,103 to 2,835 lines and adds a 317-line internal codec module. Aggregate production code grows by 49 lines; the measured result is a large-module seam extraction, not net deletion. The moved declarations are AST-equivalent, public exports and wire formats are unchanged, and node retains framing, timeouts, connection admission and lifecycle state.The original 28 integration cases remain unchanged, with nine new codec test groups and ten detected implementation mutations. Local verification and its boundaries are recorded in the issue and PR.
refactor(runtime): name the tool-call data boundary and share the cal…
daierenao commentedon Sep 15, 2026
Claiming part of A16 — Architecture documents, scoped to one bilingual pair (checked: no existing A16 claim; search for "A16" on this thread returns only the area row):
docs/architecture/windows-sandbox-rfc-v1.mddocs/architecture/windows-sandbox-rfc-v1.zh-CN.mdPlanning issue: #5338.
The pair declares
translation_status: syncedfrom heading lockstep, which is not a semantic check. The Chinese counterpart is missing four Current/deferred claims (including the §6.5 lifecycle-evidence sentence). One PR reconciles those claims and the counterpart links. The rest ofdocs/architecture/stays on the board.Serialization: #3952 is open and edits both RFC files for Glob/junction policy (last activity 2026-09-01). This slice does not take that policy; it patches current
main.colaforniaw commentedon Sep 16, 2026
Claiming part of A14 — UI component library: the tool-call detail rendering in packages/ui/src/tool-activity.tsx and packages/ui/src/tool-activity/.
Planning issue: #5403.
(Checked: no existing A14 claim in this thread.)
refactor(runtime): name the tool-call data boundary and share the cal…
testikun commentedon Sep 18, 2026
Claiming A04 — Runtime session kernel, scoped to
packages/runtime/src/session-manager.tsandpackages/runtime/src/runtime-kernel.ts.Research and implementation coordination: #5491.
The pinned baseline is
5b9db1ce8: 5,738 + 3,644 = 9,382 lines. The objective is to reduce repeated implementations and clarify the existing owners, with net production-code reduction across all affected modules, including new helpers and adapters. File splitting alone will not count as completion.I will first compare the current paths with Maka's architecture blogs, Codex, and the requested
bug-superman/claude-codereference, then publish the ownership map, deletion ledger, preservation checks, and bounded PR sequence. Each proposed abstraction will undergo an ablation review before it becomes part of the plan.#3908 is related existing work: its former claimant has explicitly withdrawn and posted
untake. #5491 links that history and will coordinate the broader A04 pair without creating a competing SessionManager implementation. The active permission, Plan, Regenerate, and voice changes touching these files remain with their current authors.Automated coordination comment by OpenAI Codex on behalf of
testikun, who requested this claim and research.refactor(runtime): extract tool-call argument projections (#4937)
github-actions commentedon Oct 19, 2026
This issue has had no human activity for 30 days and has been marked stale. It will be closed in 30 days unless someone comments.
If the issue is still current, please confirm it against the latest
mainand add any information that would help move it forward. Assigned issues and issues labelledpinnedare exempt from this policy.