codegraph-adapter: read the index only through the in-process read-only handle

Goal

archctx reads CodeGraph's index through one path: the in-process read-only SDK handle (CodeGraph.openSync(root, { readOnly: true })). The query paths that spawn the CodeGraph CLI, copy a snapshot or parse CLI text output go away. Building the index (codegraph init, codegraph sync) stays with CodeGraph's own commands.

This is after 0.14.0 (#541). It is not part of that release.

Why

The CodeGraph dependency stays. Import edges, call edges, symbol declarations and callees are the code-facts half of the product (constraints check, refactor scan, flow selectors and selector evidence, state machine and docs anchors, capability docs, architecture debt), and CodeGraph is the authority for them across 30+ languages. What costs us is how we read it. Recent issues trace to the CLI and snapshot paths, not to the index:

ci: constraints CLI test sees .git/index rewritten on main since #543 #544 / fix(codegraph-adapter): read CodeGraph status without refreshing the git index (#544) #545 and codegraph sync in flows check rewrites .git/index (GIT_OPTIONAL_LOCKS) #547 / fix(codegraph-adapter): run every CodeGraph child without git index locks (#547) #554: codegraph status and codegraph sync run git status in the checkout and rewrite .git/index unless GIT_OPTIONAL_LOCKS=0 is set.
state-machine anchors: digest covers the anchored symbol only, not its local callees #539 design: withExistingCodeGraphSnapshot copies the sources, .git and the database (113 MB here), runs codegraph --version and status, and spawns a Node child. That is 3.25-3.98 s for one query, which is over the 3 s edit-time budget on its own. The read-only handle that feat(state-machines): cover a symbol anchor's direct callees in its digest (#539) #550 uses adds 92-214 ms cold, with no spawn and no git.
The CLI provider parses query / impact text output on a best-effort basis.

Current read paths (main at the time of writing)

packages/local-runtime/codegraph-adapter/src/:

CLI spawn for reads:
- CodeGraphCliProvider query (index.ts:149) and impact (:164)
- repositoryImportPairs through query -k import (:1967)
- readProjectionCodeGraphStatus through status -j (:1038)
- --version (:916, :1517)
Snapshot copy: withExistingCodeGraphSnapshot (:1213, including the git config, filter and hooksPath pinning at :1276-1319) and snapshot-query.ts (a spawned Node child running QUERY_SCRIPT, :225).
Already in-process: openCodeGraphSymbolReader (:1669) and the selector index factory (:1810).
Build, which stays: sync (:102, :951).

Scope

A read-only design pass first, with no code changes. Its output is a design summary and, if a durable rule changes, an ADR draft. It answers:
- Whether the read-only SDK handle provides every fact the CLI and snapshot paths provide today: import nodes and edges with the current limits, impact at the depths in use, the readiness and staleness facts that status -j gives, and the version. Name any gap. A gap is not filled with local parsing.
- Why the snapshot path exists. The git filter and hooksPath pinning suggests it isolates CodeGraph's git calls from repository-configured code. State whether reading the index in-process, which runs no git, keeps that guarantee or makes it unnecessary.
- Which runtime loads the SDK in each caller (Bun daemon, Node CLI, packaged CLI), and why snapshot-query.ts spawns Node today.
- The readiness check without codegraph status: for example the per-file content-hash test that feat(state-machines): cover a symbol anchor's direct callees in its digest (#539) #550 uses, and its cost on this repository and on repo-harness.
- Measured timings before and after, for checkpoint, complete and constraints check.
Then implementation slices, as the design splits them.

Boundaries

No fallback to the CLI read path. A missing or unopenable index fails closed with the existing failure codes (AC_CODE_FACTS_UNAVAILABLE, index-missing, index-open-failed, index-stale).
No local parser or regex to re-derive code facts.
init and sync stay CLI. The GIT_OPTIONAL_LOCKS=0 child environment stays on them.
The CodeGraph version pin (REQUIRED_CODEGRAPH_VERSION) stays the one version authority.
A contract or schema change needs its own decision in the design summary.

Out of scope

colbymchenry/codegraph#3280 (#567): the Windows init crash in CodeGraph's bundled node.exe. init stays CLI, so this work does not fix it.

Seat: advisor t12

Decision (owner, in pane t12, 2026-11-13, relayed by advisor t12): "批准". This was the reply to the proposed next cut. #574 starts now with scope step 1, the read-only design pass. It changes no code. Its output is a design summary that answers the five questions above, plus an ADR draft if a durable rule changes. The orchestrator and the advisor review the summary jointly before any implementation slice opens. #576 stays queued after #574.

Seat: orchestrator t7

Joint review of the #574 design pass (orchestrator + advisor), 2026-11-13. The design summary and the ADR-0058 draft are agreed in substance, with these positions.

Recommendation. One adapter-owned, in-process, read-only CodeGraph read session for every code-facts read. Freshness comes from CodeGraph's own content-hash test, and imports from getNodesByKind("import"). The snapshot path, its Node child and the CLI query/status/--version reads are deleted. init and sync stay CLI under GIT_OPTIONAL_LOCKS=0.
Measured on main f381b51 against a prototype. Outputs are identical. Reads run no git status or git diff.

Command arch-context repo-harness

complete 7.80 → 3.09 s 10.29 → 5.64 s

checkpoint 0.93 → 0.40 s 1.56 → 1.11 s

constraints check 1.11 → 0.59 s 1.32 → 0.96 s
Freshness uses named provider-internal modules (scanDirectory, hashContent, readBoundedSourceSync, oversizeStamp, EXTRACTION_VERSION), with the ADR-0002 amendment. A contract test pins the module paths and export names, so a provider bump fails at test time and never at runtime. ADR-0058 states that a public git-free change API from colbymchenry/codegraph replaces these calls when it ships. An upstream request is to be drafted, and posting it needs owner authorization. The alternative, getChangedFiles, runs git status, which brings back the filter and hook exposure that the design removes.
ADR-0058 Decision 3 names the closed list of git commands a read may run: ls-files, rev-parse, check-ignore and config --get core.excludesFile.
Runtime R1. Node is the supported runtime for reads. Under Bun on macOS, a read without WAL sidecars fails closed with index-open-failed. Before S1 merges, CI runs the real-index suite under Node on all three OSes, Windows included.
Contracts. C1, C2 (an additive index-open-failed failure reason), C4, C5 and C7 are accepted as recommended.
Owner decisions needed before the matching slice:
- C3: the three code-facts-snapshot-* reasons are removed in the same release, as a listed contracts break. That release is 0.15.0, a minor. This replaces the summary's "keep for one minor".
- C6: buildTaskContext uses findRelevantContext for the files and searchNodes for the query nodes. This is one listed output change, and it is off every timed path.
Slices. All slices write codegraph-adapter/src/index.ts, so they serialize: ADR → S1 → S2+S3 (merged into one slice) → S4 → S5 → S6.
- S1, S2+S3 and S4 are High.
- S5 and S6 are Medium.
- S1 may run in parallel with the 0.14.1 work (docs apply: the v4 re-baseline refuses a v3 manifest that has minimumRendererVersion #579, projection: repo-harness/v1 renders 20 agent-context regions into root AGENTS.md and CLAUDE.md #580) once the owner accepts ADR-0058, because their write scopes are disjoint. Nothing from codegraph-adapter: read the index only through the in-process read-only handle #574 merges into 0.14.x.
Follow-ups filed outside this issue: the duplicate codegraph sync in complete, and the 10x import-limit ceiling.

Seat: orchestrator t7

Decision (owner, pane t12, 2026-11-13, relayed by advisor t12) on ADR-0058 and the #574 contract points:

ADR-0058 is accepted.
C3: the three code-facts-snapshot-* failure reasons are removed in 0.15.0, as a listed contracts break with no unreachable residue.
C6: buildTaskContext uses findRelevantContext for the files and searchNodes for the query nodes. The one-time output change goes in the 0.15.0 release notes.
The upstream request for a public git-free change API was posted under the owner's authorization: Feature request: a public, git-free way to read pending changes from a read-only handle colbymchenry/codegraph#3287. Decision 7 keeps its replacement clause and links #3287.

#586 now flips its status to accepted, adds the #3287 link in the same commit, and merges on green CI. S1 starts when it merges. S1 writes only codegraph-adapter, so it runs in parallel with #579 and #580. It goes into 0.15.0, so it does not merge before the 0.14.1 release candidate does.

Seat: orchestrator t7

docs(adr): accept ADR-0058 and link colbymchenry/codegraph#3287 (#574)

docs(adr): ADR-0058 reads CodeGraph code facts only through the in-pr…

ADR-0058 merged as 86b0bff (#586). S1 (High) is dispatched to Pi seat t2k4, the design seat, on branch feat/574-s1-read-session from 86b0bff. Its write scope is codegraph-adapter, plus the two additive C2 contract edits. S1 goes into 0.15.0, and its merge is held until the 0.14.1 release candidate merges.

Seat: orchestrator t7

Joint decision (orchestrator + advisor), 2026-11-13, on the #574 S1 fork.

Findings from the S1 writer.

The CodeGraph writer deletes the -wal/-shm sidecars when it closes. After any codegraph init or sync, Bun on macOS, which uses the system SQLite, cannot open the index read-only. About 80 Bun tests then fail closed with index-open-failed, and CI runs Bun shards on macos-15.
architecture-debt-code-facts.ts:23,35 still passes binary, and fake-binary readiness tests depend on it.

A. S1's scope widens to the two architecture-debt-code-facts.ts call sites and the fake-binary tests. The binary option is removed entirely; a dead option would be compatibility code. Those tests move to the injected opener or a real index, and the PR lists them. Test files that #580 owns are edited only after #580 merges. S1 is merge-held until the 0.14.1 release candidate merges.

B. Bun on darwin loads a SQLite that allows read-only opens, through one dev-runtime module.

Probe first. The preload is pushed on a draft PR. The macos-15 Bun shards show whether /opt/homebrew/opt/sqlite or /usr/local/opt/sqlite exists on the runner. The same run shows whether the Linux and Windows Bun shards pass without the preload. If the library is missing on CI, the work stops: installing it is a change to the required CI definition, which belongs to the owner. There is no silent skip and no darwin-skip.
One module. Database.setCustomSQLite lives in one small dev-runtime module. It resolves the library from a closed list of paths and throws with an install hint when none exists. The package boundary audit must show that the module never reaches the npm tarball.
The test preload and the dev CLI both import it. That covers bunfig.toml and bin/archctx under Bun on darwin. The read path stays one: the same SDK calls, with only the SQLite library that Bun loads differing. That is runtime configuration, not a second read path. The packaged product runs on Node and is unchanged.

Seat: orchestrator t7

Joint decision (orchestrator + advisor), 2026-11-13, on the #574 S1 draft probe (#589, run 43396375811).

Findings, each with evidence on #589.

The macos-15 runner has Homebrew SQLite, so no workflow change is needed.
R1 holds. Node's read-only open succeeds after a sync and creates the WAL sidecars.
The macOS failures come from a stale bun.lock bin entry. It points node_modules/.bin/archctx at cli/src/main.ts, which has a Bun shebang, so the "installed" CLI and the daemon it starts run under Bun with no preload.
The Windows failures are EBUSY in test cleanup, not timeouts. Bun releases the database file only when GC finalizes cached statements, and the gate now opens the index in-process.

Scope widening, each narrowed:

1a. The daemon spawn forwards process.execArgv only when the parent runs under Bun (process.versions.bun). Under Node nothing new is passed, so the product path is unchanged and flags such as --inspect never reach the daemon.
1b. The stale bin entry is fixed by regenerating bun.lock with bun install from the corrected state, never by hand-editing it. The frozen-lockfile install in CI must pass. S1 regenerates the lockfile after it rebases onto the 0.14.1 release, because the release slice also touches bun.lock.
2a. The read session's close() runs Bun.gc(true) only when process.versions.bun is set and process.platform is win32. A comment at the call names the cause: Bun keeps cached statements until GC finalizes them. Node is untouched.

Seat: orchestrator t7

feat(codegraph-adapter): read-session tests, Node integration, Bun ru…

fix(codegraph-adapter): release the Bun handle before GC on Windows (#…

Joint decision (orchestrator + advisor), 2026-11-13, on parallelizing the remaining issues. The owner asked in pane t12: "近7个issues，还有多久才能收完？能不能并行".

0.14.1 (0.14.1: unblock the repo-harness archctx 0.14 pin (#579, #580) #583, release: prepare archctx 0.14.1 #582) is in flight and finishes first. main stays frozen until the release candidate chore(release): prepare archctx 0.14.1 (#582) #591 merges. codegraph-adapter: read the index only through the in-process read-only handle #574 S1 (feat(codegraph-adapter): one in-process read-only read session (#574 S1) #589) merges after 0.14.1 is published.
Started now, in parallel, in files codegraph-adapter: read the index only through the in-process read-only handle #574 does not touch:
- context: capabilities.json links 31 module pages that do not exist #592, Low. Regenerate .ai/context/capabilities.json from its authority; do not hand-edit the 31 paths. The worker names the generating command. If the generator lives in aimpact-inc/repo-harness, that is a boundary question back to the orchestrator and advisor. Write scope: .ai/context/ only.
- ledger read mode: validateModel has no parity with YAML validation (schemas, topology, state machines) #576, High: one GPT review plus one Opus review. One model validator over a set of model files, called by both the YAML store and the ledger read path. It is not a second validator patched up to parity, and there is no compatibility path. Write scope: runtime-daemon index.ts (validateLedgerModelFiles and its caller) and model-store-yaml validateModel.
codegraph-adapter: read the index only through the in-process read-only handle #574 split. Right after S1 merges, a move-only slice S1b (Medium, one GPT review) splits codegraph-adapter/src/index.ts by responsibility: readiness and status, import population, projection handshake, snapshot, CLI provider. Behavior does not change. Then S2+S3, S4 and S5 run in parallel, each in its own module, and S6 comes last.
complete: codegraph sync runs twice per complete #584 and codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585 fold into codegraph-adapter: read the index only through the in-process read-only handle #574 S2+S3.
- complete: codegraph sync runs twice per complete #584's projection-sync half is S3 code.
- complete: codegraph sync runs twice per complete #584's half at runtime-daemon/src/index.ts:791 lands only after ledger read mode: validateModel has no parity with YAML validation (schemas, topology, state machines) #576 merges, because ledger read mode: validateModel has no parity with YAML validation (schemas, topology, state machines) #576 writes that file. One writer per file applies by file, not by region.
- codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585: measure memory at 64k import nodes. Raise the limit if that is safe. Otherwise keep the deterministic importNodeLimitExceeded and close codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585 with the measurement.

Seat: orchestrator t7

fix(codegraph-adapter): release every in-process Bun handle before GC…

feat(codegraph-adapter): one in-process read-only read session (#574 S1)

feat(codegraph-adapter): read-session tests, Node integration, Bun ru…

fix(codegraph-adapter): release the Bun handle before GC on Windows (#…

Joint decision (orchestrator + advisor), 2026-11-14, on running the #574 slices in parallel after S1b (#596). Each file has one writer.

Seat A: S2, then S3, as two PRs in sequence.
- S2 (Medium) owns:
  - codegraph-adapter/src/import-population.ts;
  - runtime-daemon refactor-scan.ts and capability-dependencies.ts;
  - the import tests.
  It folds in codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585: measure peak RSS and wall time on a synthetic index with 64k import nodes, with the limit at 50k and at 64k. Raise the limit to 64k only if the cost is acceptable. The PR states the headroom: about 8x to about 10x repo-harness. codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585 closes from these numbers.
- S3 (High) owns:
  - projection-handshake.ts and selector-index.ts, where the selector opens read-only (C7);
  - runtime-daemon projection-service.ts, projection-apply.ts and index.ts, which takes complete: codegraph sync runs twice per complete #584, the double sync.
  S3 keeps the signature of loadCapabilityCodeGraphProjectionInputs and does not edit flow-selector-check.ts.
Seat B: S4 (High). It deletes snapshot.ts and snapshot-query.ts, and moves ref-impact-facts.ts and the whole of flow-selector-check.ts onto the read session. It applies C3: the three snapshot reasons are removed from failure.ts and from the schemas, fixtures and docs that list them. In this phase S4 also owns codegraph-adapter index.ts, scripts/codegraph-selector-node-integration.mjs and docs/runbooks/ref-impact.md.
Seat C: S5 (High). It owns cli-provider.ts, split into a CLI builder and SDK reads (C6: findRelevantContext plus searchNodes), and the tests codegraph-adapter.test.ts and codegraph-adapter/test/refactor-baseline.test.ts.
Files no slice owns. read-session.ts, test/real-index.ts and test/read-provider-fixture.ts have no owner; a change to any of them is a boundary question. Any change S2, S3 or S5 needs in index.ts or failure.ts is also a boundary question. It is folded into S4's PR or lands after S4 merges.
Release notes. The S4 (C3) and S5 (C6) PRs each add a "Release note (0.15.0)" line to their PR body. The orchestrator collects these lines on this issue for the 0.15.0 checklist.

Seat: orchestrator t7

refactor(codegraph-adapter): split index.ts by responsibility (#574 S…

S1b merged as 6efd32a (#596). Per 574#issuecomment-6862827660, three slices are dispatched in parallel from 6efd32a, each in its own worktree:

S2 (Medium, with the codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585 measurement): Pi seat t2kw, branch feat/574-s2-import-population. S3 follows in the same seat after S2 merges.
S4 (High): Pi seat t2kx, branch feat/574-s4-delete-snapshot.
S5 (High): Pi seat t2ky, branch feat/574-s5-sdk-provider.

Seat: orchestrator t7

Joint decision (orchestrator + advisor), 2026-11-14, on three boundary questions from the S2 writer.

Q1. Moving capabilityImportGraphs onto the read session.

S2 edits the call sites in selector-index.ts and projection-handshake.ts. Those are S3 files, but the same seat does S3 after S2, so no two writers run at once.
The import-graph cases in capability-projection-inputs.test.ts (7 cases, a file S4 also edits) and in codegraph-adapter/test/refactor-baseline.test.ts (4 cases, a file S5 also edits) get a scoped exception to one-writer-per-file:
- S2's PR lists the cases it edits by name;
- S4 and S5 do not touch those cases;
- whichever PR merges later does a merge-only sync from main, verified with merge-tree and recorded on the PR;
- a textual conflict goes back to the later writer, never to a hand merge.

Q2. S2 adds one export line to codegraph-adapter index.ts for packagedCodeGraphRuntimeDigest. S4 is told.

Q3 (#585). The default import-node limit rises from 50 000 to 64 000.

Measured on a synthetic index with 64k import nodes (in-process read, Node 24, three runs each), the 64k limit costs +6.4 % wall time and +1.2 % peak RSS over 50k.
main's CLI read took 1.6-2.2 s and spawned a child of about 600 MiB.
The headroom moves from about 8x to about 10x repo-harness.
S2 also updates the stale defaults in the cli main.ts:4014 help text and docs/spec.md:227-228.

Seat: orchestrator t7

refactor(codegraph-adapter): keep index.ts to the snapshot re-export …

Joint decision (orchestrator + advisor), 2026-11-14, on #597 (S5) round-1 F1, the impact edge kinds. This amends the design.

Callers and callees are typed calls and instantiates edges. Type references appear only in affectedPaths, from getImpactRadius. They are not counted as callers or callees. This replaces the design summary's "typed calls/references edges".

Why: NormalizedEdge.kind has no references value. Counting references would mislabel them as calls, the same defect that got the old trail parser deleted. Adding a kind would change the contract for a surface that no production code calls.
Test: S5 adds a real-index case where a type reference appears in affectedPaths and not in callers.

S6 scope addition. getImpact, getCallers and getCallees have no production caller. Only CodeGraphAdapter's own wrappers (index.ts:158-169) and tests use them. They are still part of the published CodeFactsPort in archctx-contracts (ports.ts:130-132), and the impact capability is asserted at index.ts:192. Under the owner's no-dead-code and no-compatibility rule, S6 removes this unused impact surface from:

the port;
the adapter;
the provider capability list;
cli-provider.ts.

This is a listed contracts break for 0.15.0.

Seat: orchestrator t7

状态更新：本文是提交前快照。S2/S5 未提交代码现已 commit/push，S4 已补建 Draft PR；最新换机入口见后续交接。不再需要手动传输 source patch。以下保留当时观察与待决事项。

换机交接快照 — 2026-11-14 10:13 Asia/Taipei

由用户要求读取 Herdr 的 archctx 其他 pane 后整理。来源：hc ls/get/read、本机各 worktree 的 Git 状态、git ls-remote、GitHub issue/PR 与 Actions 回读。本文是交接记录，不是新的 Joint decision 或 acceptance。未启动实现、提交、push、merge、发布或停掉原 pane。

先看这三点

当前主线是本 issue 的 S2/S3/S4/S5/S6。远端 main = 6efd32ad1e2448e7f4e1dd9b69d6dcd23c5c9284（S1b refactor(codegraph-adapter): split index.ts by responsibility (#574 S1b) #596）；主 checkout 干净。
S2 的全部实现、S5 的 round-2 修复仍只在原机器未提交的 worktree 中。只 clone/fetch GitHub 会漏掉它们。 下表和后文给出位置及 patch 校验值；迁移这些改动前保留原机器和 worktree。
多个 pane 停在额度错误，不能把 done/error/idle 当作接受或完成。S5 远端旧 head 的 CI 绿，但 round-1 acceptance 仍有 FAIL，round-2 尚未提交/复审。

Pane、分支与可恢复状态

Pane	职责/状态	代码与远端事实
`t7`	orchestrator，`error`；Claude weekly limit，屏幕显示 Nov 15 06:00 Asia/Taipei 自动继续等待	最新已落盘决策见下方链接；原 pane 仍存活，换机后需协调旧座位恢复，避免双写
`t12`	advisor，`done`	最近已同意 S2 边界例外、S5 F1 设计修订，以及 S6 删除无生产调用者的 impact port
`t2kw`	S2 writer，`error`；Aimpact credit balance too low	`/private/tmp/arch-context-wt-574-s2`；分支 `feat/574-s2-import-population`；HEAD 仍为 `6efd32ad`；17 个 tracked 文件未提交，+446/-420；远端无该分支，无 PR
`t2kx`	S4 writer，`done`，实际在等 3 个边界答复	`/private/tmp/arch-context-wt-574-s4`；`feat/574-s4-delete-snapshot`；本地干净；远端已存在 `be07d5f2c5235f71cedffd46d3f745220b94687e`；尚无 PR
`t2ky`	S5 writer，`error`；Aimpact credit balance too low	`/private/tmp/arch-context-wt-574-s5`；`feat/574-s5-sdk-provider`；PR #597 远端仍是 `f14b6a8d2c44005e80f4a0e5d419c06c11a6555b`；round-2 两文件未提交，+89/-28
`t2kz`	GPT reviewer，`idle`	round-1 FAIL；`/private/tmp/arch-context-gk-597`，detached `f14b6a8d`
`t2m0`	Opus reviewer，`done`	round-1 PASS with 5 P3；`/private/tmp/arch-context-rv-597`，detached 同一 head
`t2m1`	Pi，`idle`，turn 0	同 review worktree；未观察到任务结果
`t2kb`	之前的 harness 升级工作，`done`	不属于 #574 writer；pane 曾报告 repo-harness 0.32.0、archctx 0.13.0 pin。这是该 pane 的历史结果，不代表新机器安装状态
`t2m2`	本次交接整理	只读核对与写交接评论

已决定的边界，接手时沿用

并行分工：S2 Medium，合并后同一 seat 再做 S3 High；S4/S5 High 并行；最后 S6。S3 不改 flow-selector-check.ts，该文件归 S4。
S2 边界与 64k 决策：S2 可改 selector-index.ts / projection-handshake.ts 的调用处，及 index.ts 的一行 packagedCodeGraphRuntimeDigest export。共享测试仅允许 S2 改 7 个 capability import-graph cases 与 4 个 refactor-baseline import cases；S4/S5 不碰这些 cases。后合并者 merge-only 同步 main，用 merge-tree 核实并记录；冲突交回后合并的 writer。
codegraph-adapter: the 50 000 import-node read limit is reached at about 8x repo-harness #585 并入 S2：上限 50,000 → 64,000；已记录测量 +6.4% wall / +1.2% peak RSS，headroom 约 8x → 10x。advisor 指出 SDK 本来加载全部 import nodes，该上限限制覆盖范围，不限制加载内存；本轮不删除上限。
S5 F1 设计修订与 S6 impact 清理：callers/callees 只含 calls/instantiates；type references 仅出现在 affectedPaths。S6 删除 port、adapter、capability list、provider 中没有生产调用者的 getImpact/getCallers/getCallees，列为 0.15.0 contracts break。
ADR-0058 已接受；读路径使用单一 in-process read-only session，无 CLI/snapshot fallback；init/sync 仍为 CLI。C3 删除三个 snapshot failure reasons，C6 的 context/digest 一次性改变都需 0.15.0 release note。旧 design-summary 中 “references edges”、旧分工、旧 Bun pin 及 C3 保留一版等描述以 issue 后续决策为准。

S2：代码已写，广范围测试实际已结束，但没提交

Pane 报告：typecheck clean；affected suites 997 pass、0 fail（998 tests）；Node selector integration verified。本次直接读到 /tmp/s2-585/full.log 末尾：

1893 pass
0 fail
Ran 1893 tests across 118 files. [747.51s]
EXIT 0

对应命令：bun test --timeout 120000 packages/surfaces packages/contracts packages/core tests。它不是整个仓库的单一全量验收，也不是远端 CI。本次未重跑测试，日志未绑定 immutable commit；接手在最终 head 上补齐所需验证。

未提交文件覆盖：docs/spec.md；adapter 的 import-population.ts/index.ts/projection-handshake.ts/selector-index.ts 及四个 import tests；runtime-daemon 的 architecture-debt-code-facts.ts/capability-dependencies.ts/refactor-scan.ts 及 architecture-debt test；CLI main.ts/constraints.test.ts/deps.test.ts；scripts/architecture-projection-axr3-semantic-pilot-readback.ts。

测量脚本和日志在 /tmp/s2-585/{driver.ts,driver-main.ts,time.txt,full.log}。下一步是保全改动/证据，检查最终 diff 与 test budget，提交 S2 PR；S3 另起一包，不能把 S2 已动过两处调用点视为 S3 完成。

S4：可直接从远端恢复，三个问题仍未决

最新 head be07d5f2 上，writer 报告 typecheck clean、163 tests pass/0 fail、Node integration verified、package-boundary audit pass。3380 pass 的 full suite 在前一 head cde03718，不要当成新 head 的全量证明。本次未重跑。

待新 orchestrator + advisor 处理并记录：

test/real-index.ts 原属 unowned；当前提交已把 pinned Node/SDK runtime 放成该文件私有 codeGraphNodeRuntime()（+15/-4）。writer 推荐确认此方案，另两个选项是新 test helper 或保留 production export。
surfaces/cli/src/main.ts:950-951 的 flows help 仍写 disposable private snapshots / unsupported-layout / over-limit snapshots；决定由 S4 改两行还是留给 S6。注意 S2 同时写同一 main.ts 的 import-limit help，需先协调文件 ownership。
brief 的 “no git config” 与 ADR-0058 Decision 3 允许的 config --get core.excludesFile 冲突。writer 的 assertions 验证 ADR allow-list，另加 ref impact 自身的 ls-tree/cat-file/log；请求确认，而不是要求删掉合法行为或削弱 assertions。

S4 已只删 index.ts 的 snapshot re-export block；flow-selector-check.ts 直接 import ready-index-read.ts，Node integration 分别 bundle 两个入口。未动 S2 的 7 个 import cases。答复后才开 High PR，补 release note、逐项 assertion 变化说明与 review。

S5 / #597：round-2 本地通过部分验证，远端仍是 round-1

GPT round-1 FAIL：P1 F1 设计/coverage，P2 F2 provider-load/close error mapping。
Opus round-1 PASS / 5 P3。
远端 f14b6a8d 的 Verify run 43500333159 completed/success。这不覆盖本地 round-2，也不覆盖 acceptance FAIL。
round-2 范围（原 brief /tmp/arch-context-orchestrator/rv597/round2.txt）：真实 type-reference case；provider-load → codegraph-unavailable、close 不覆盖原 read error；读中 index 变化 → retryable refusal；精确固定 union/tie-break order；修正 fault-injection 用词。impact port 删除留 S6。
本地只修改 packages/local-runtime/codegraph-adapter/src/cli-provider.ts 和 packages/local-runtime/codegraph-adapter/test/codegraph-adapter.test.ts。pane 报告 typecheck 完成，adapter 120 pass/0 fail；其余 affected suites 902 pass/0 fail（903 tests）；Node integration verified。mutation check 用旧 source 配新 tests 得到 22 pass/2 fail。
PR body 尚未更新，修复未 commit/push，round-2 review 未运行。 上述为 pane 证据；部分命令经过 grep/tail，没有独立 test 进程 exit receipt。本次不把它升级为最终验收。

S3 / S6 接续清单

S3 尚未开始独立实现：projection handshake / read-only selector；吸收 #584 的 complete duplicate sync；保持 post-sync freshness fail closed，不引入跨命令 cache，不修改 S4 的 flows 文件。

S6 在 S2–S5 后：删除残留 read CLI API/timeout/parser；更新 projection runbook 和 ADR-0054 gate 说明；provider-internal module contract bump guard；package boundary audit；S1 后续清单的 Darwin SQLite selector、Bun execArgv、live-writer/WAL coverage，以及 provider read-only open 改写 .codegraph/.gitignore 的 ADR/upstream 处置；最后加入已决定的 impact port 删除。沿用已落地覆盖，避免重复添加测试。

换机入口与未传输代码校验

新机器先读本评论、上面决策、仓库 AGENTS.md 与 docs/adr/ADR-0058-codegraph-reads-in-process-read-only.md，从远端 fetch S4/S5。环境按仓库 pin：Bun 1.4.4；此次 writer 记录 Node v24.22.1、CodeGraph 1.6.2。本机临时 PATH shim 不是可移植依赖。

S2/S5 尚未传输：在原机器分别导出 git -C <worktree> diff --binary HEAD，在新机器对应相同 base/head 的干净 worktree 先 git apply --check 再应用。当前 git status --short 未见 untracked；若交接时状态变化，需重新清点。导出的 patch SHA-256（本次快照）：

S2：22d2a9e22036bd5a099b6ea526d8b9373db985dcab11e4ab57acccdacfd3df7e；base 6efd32ad1e2448e7f4e1dd9b69d6dcd23c5c9284。
S5：b423cad04c977b8a76ec259ba5c75707777cec9363ec8064b85e16b37df7db34；base f14b6a8d2c44005e80f4a0e5d419c06c11a6555b。

还需携带必要测量/验证文件：/tmp/s2-585/、/tmp/arch-context-orchestrator/d574/design-summary.md、s2s5/task-s2.txt / task-s4.txt / task-s5.txt、rv597/round2.txt。这些是本机路径，不是 GitHub 附件；本评论已提取关键决策和待办，设计原稿必须结合后续 issue amendments 阅读。不要复制 SQLite/WAL/runtime state 充当可移植源代码。

下一刀：先保全并迁移 S2/S5 未提交改动。原因：这是仅靠 GitHub clone 无法恢复的唯一代码缺口。入口：上述两个 worktree 的 binary diff 与 SHA-256；新机器核对相同 base 和 patch 后即可接续，不需要重做已完成实现。

记录者：Codex t2m2，按 owner 本轮交接请求。

换机交接已更新：代码全部可从 GitHub 恢复

用户补充授权：把未提交改动提交到 PR，并说明情况，供新机器接续。现已完成 commit/push，并用 git ls-remote 回读确认；以下取代上一份交接中“代码仅在原机器”的状态。

Slice	PR	远端 head	状态与接手点
S2	#598	`2de1f7238bac3e49847e0b0ff49ac3b13d5e0929`	Draft；17 文件原样保存；Medium acceptance、assertion review、当前 head CI 待完成；S2 之后另做 S3
S4	#599	`be07d5f2c5235f71cedffd46d3f745220b94687e`	Draft；原已推送成果补建 PR，未改代码；三个未决问题写入 PR，处理后 High review
S5	#597	`d59c8f83cead0f1dcf311d281b2b2ba1745e426b`	Draft；round-2 两文件修复已保存；PR body 已更新；新 head round-2 review / CI 待完成

三份 worktree 均干净、对应远端 head 一致。main 保持 6efd32ad1e2448e7f4e1dd9b69d6dcd23c5c9284。没有 merge / release / deployment。 原 panes 没有被关闭，旧 orchestrator 屏幕有额度恢复后自动继续的等待，接手时须协调它，避免双写。

本次新增的验证证据

Bun 1.4.4，Node v24.22.1；commit 没有改变测试时的内容：

S2：bun run typecheck + module-import-pairs / capability-import-graph-limit / capability-projection-inputs / refactor-baseline 四文件 → 51 pass、0 fail、exit 0。
S5：bun run typecheck + bun test --timeout 60000 packages/local-runtime/codegraph-adapter → 120 pass、0 fail、exit 0。
两份 git diff --check 均通过。没有复跑旧 full suite，也没有把旧 head 的 CI / acceptance 挪到新 head。
S2 test budget exception 已记录在 feat(codegraph-adapter): in-process import reads (#574 S2) #598：tests +322 / product +119，2.71:1，新增 test files 0。S5：+248 / +187，1.33:1，新增 0。S4 统一口径：+127 / +114，1.12:1，新增 test helper 1。

新机器直接接手

在新机器的独立 worktree 中执行相应 gh pr checkout 598、gh pr checkout 599 或 gh pr checkout 597，核对上表 SHA。无需从旧机器另传 S2/S5 source patch。按仓库 pin 安装依赖；不要复制 node_modules、SQLite/WAL 或 runtime state。

决策与 pending 问题已在前一条交接和三个 PR body 持久记录；本机临时 benchmark scripts/logs 仍是旧机器的辅助证据，关键数字、执行命令和证据限制已经写进 PR。恢复代码与继续 implementation 不依赖这些临时文件。不是原始日志归档完成的声明。

下一刀：接续 #597 新 head 的 round-2 review。原因：修复代码与本次 targeted checks 已保存，剩下的是上一轮 FAIL 的验收闭环。入口：PR #597 的 current handoff / verification 与两份 round-1 receipt；只评本次修复及受影响边界即可，S6 impact 删除不并入这轮。

记录者：Codex t2m2，按 owner 本轮 commit/PR 交接授权。

repo-harness issue claim
Status: active
Role: coordinator
Agent: claude-code (claude-opus-5-5), orchestrator seat t366 on the new machine
Branch: main
Scope: coordinator and integrator of #574 after the machine switch (574#issuecomment-6870096533): S5 #597 round-2 review, S2 #598 acceptance, the S4 #599 decisions, then S3 and S6 dispatch, acceptance and merge in the agreed order
Not in scope: implementing any slice; the old machine's seats

Owner decision, 2026-11-14, pane t366: take the #574 orchestrator seat in t366; post the advisor's JD-1..JD-4 on #574; the owner stops the old orchestrator t7 (old machine) before its auto-resume at 2026-11-15 06:00 Asia/Taipei. t7 posts nothing more on #574 after this claim.

Seat: orchestrator t366

Joint decision (orchestrator + advisor), 2026-11-14, on the merge order of the remaining #574 slices and the three S4 (#599) boundary questions. The owner approved posting it in pane t366.

JD-1. Merge order: S5 #597 → S2 #598 → S4 #599. S3 is dispatched after S2 merges.

Why: git merge-tree on the current heads (597 d59c8f8, 598 2de1f72, 599 be07d5f): S5+S4 merge clean; S5+S2 conflict in codegraph-adapter/test/refactor-baseline.test.ts; S2+S4 conflict in codegraph-adapter/test/capability-projection-inputs.test.ts. S2 conflicts with both, so it should not become the base that the other two sync onto twice. S5 is closest to PASS. S2 second keeps the S2 → S3 → S6 critical path short. S4 last because it still has open decisions.
Each later merger does a merge-only sync from main, per 574#issuecomment-6864071747. The conflicts go back to that slice's writer seat and are recorded on its PR, not hand-merged.

JD-2. S4 Q1 (test/real-index.ts, private codeGraphNodeRuntime(), +15/-4): accepted.

Why: a test-only helper; no production export is kept for tests. S4 gets this file for this change. S5 uses real-index.ts but does not edit it, and S5+S4 merge clean.

JD-3. S4 Q2 (cli/src/main.ts:950-951, the flows help still describes snapshots): S4 fixes it in #599.

Why: the help describes the behavior S4 deletes, and the retired path goes in the same PR. S4 gets the case "flows" help block (main.ts:945-952) as a region exception, the same shape as 574#issuecomment-6864071747. S2 edits only main.ts:4014 (CLI_DEPS_HELP.imports).
The new text names the read-only session and drops "unsupported-layout or over-limit snapshots".

JD-4. S4 Q3 ("no git config" in the brief vs ADR-0058 Decision 3): the ADR wins.

Why: ADR-0058 Decision 3 allows exactly ls-files, rev-parse, check-ignore and config --get core.excludesFile. The accepted ADR is the durable authority; the brief paraphrased it. The writer's git-spy allow-list stays.
Ref impact's own ls-tree / cat-file / log are ref-impact reads, not CodeGraph reads. The S4 reviewers check that the spy keeps the two apart and does not widen the CodeGraph read allow-list.

Applies to: #597, #598, #599, and S3/S6 dispatch.

Seat: orchestrator t366

repo-harness issue claim
Status: active
Role: writer
Slot: S4 (PR #599)
Agent: claude-code worker-important seat on the new machine, dispatched by orchestrator t366
Runtime: claude
Model: claude-opus
Branch: feat/574-s4-delete-snapshot
Scope: finish S4 on #599 from head be07d5f per the joint decision 574#issuecomment-6870240303: keep the test-local codeGraphNodeRuntime() in test/real-index.ts (JD-2); fix the case "flows" help block in cli/src/main.ts:945-952 (JD-3); keep the ADR-0058 git-spy allow-list and keep ref impact's own reads separate from it (JD-4); map each deleted assertion to its retained coverage in the PR body; update the PR body to the final state; own the PR head and its fix rounds
Not in scope: S2's main.ts:4014 and the S2 shared test cases (574#issuecomment-6864071747); S6 cleanup; merging; any sync with main before the coordinator asks for it (S4 merges last per JD-1)
Coordinator: #574 (comment)
Dispatch reading: claude normal (45% left), codex hyper (91% left); route important_deep -> worker-important (claude opus medium)

The original S4 writer pane t2kx is on the old machine and is not resumed; this seat takes the writer and head-owner role of #599 from the pushed head be07d5f (handoff record 574#issuecomment-6870096533).

Seat: orchestrator t366

feat(codegraph-adapter): SDK-backed provider reads (#574 S5) (#597)

S5 merged as d63dfad (#597). It passed the round-2 High review: GPT PASS (597#issuecomment-6870578770) and Opus PASS (597#issuecomment-6870590484). The round-1 threads were closed under 597#issuecomment-6870663834. Three P3s from round 2 join the S6 scope:

GPT N1: error-boundary coverage siblings, with close-attempt counting.
Opus F1: one shared codegraph-unavailable FailureError helper for cli-provider.ts and repository-code-facts.ts.
Opus F2: a test row for close throwing after a good read. It overlaps N1.

Joint decision (orchestrator + advisor), 2026-11-14, on the #598 (S2) round-1 GPT finding GK598-2 (598#issuecomment-6870612718), the S2 scope in codegraph-adapter/test/capability-projection-inputs.test.ts.

Decision. The one-writer exception of 574#issuecomment-6864071747 for S2 in this file grows. Besides the 7 import-graph cases, S2 also owns:
- the shared seedWorkspace / fakeCli setup;
- the combined case "measures import edges and exact node-v2 selector evidence in one index pass";
- the case "selector proof is stable under unrelated fanout and fails closed for missing or ambiguous identities";
- evidenceFor in the selector-only built-in suite, and its six built-in cases.
Why. The round-1 reviewer found these edits to be setup/signature adaptations for the in-process read session that keep the selector semantic assertions. Confining the diff to the 7 cases would mean keeping the retired CLI setup alive only for tests.
S4 (refactor(codegraph-adapter): remove snapshots (#574 S4) #599) does not edit these regions. The existing conflict in this file resolves in S4's merge-only sync, because S4 merges last (JD-1). The sync is verified with merge-tree and recorded on refactor(codegraph-adapter): remove snapshots (#574 S4) #599. The four refactor-baseline import cases keep their own exception.
Next. S2's round 2 (GPT) reviews the GK598-1 fix and S2's merge-only sync from main d63dfada (the refactor-baseline conflict). GK598-2 is settled by this decision.

Applies to: #598, #599.

Seat: orchestrator t366

repo-harness issue claim
Status: active
Role: writer
Slot: S2 (PR #598)
Agent: claude-code worker-important seat on the new machine, dispatched by orchestrator t366
Runtime: claude
Model: claude-opus
Branch: feat/574-s2-import-population
Scope: round-1 fix round of #598 from head 2de1f72: fix GK598-1 (598#issuecomment-6870612718). Then do the merge-only sync from main d63dfad (S5 merged) and resolve the refactor-baseline.test.ts conflict. The S2 boundary is 574#issuecomment-6864071747 as extended by 574#issuecomment-6870685494. This seat owns the PR head and its fix rounds.
Not in scope: S4's regions (real-index.ts, main.ts:945-952, its ref-impact/flows files); S3 (dispatched after S2 merges); S6; merging
Coordinator: #574 (comment)
Dispatch reading: claude normal (45% left), codex hyper (91% left); route important_deep -> worker-important (claude opus medium)

The original S2 writer pane t2kw is on the old machine and is not resumed. This seat takes the writer and head-owner role of #598 from the pushed head 2de1f72 (handoff record 574#issuecomment-6870096533).

Seat: orchestrator t366

fix(cli): describe the ADR-0058 read-only session in flows help (#574 …

Navigation Menu

Repository navigation

codegraph-adapter: read the index only through the in-process read-only handle #574

Goal

Why

Current read paths (main at the time of writing)

Scope

Boundaries

Out of scope

21 remaining items

换机交接快照 — 2026-11-14 10:13 Asia/Taipei

先看这三点

Pane、分支与可恢复状态

已决定的边界，接手时沿用

S2：代码已写，广范围测试实际已结束，但没提交

S4：可直接从远端恢复，三个问题仍未决

S5 / #597：round-2 本地通过部分验证，远端仍是 round-1

S3 / S6 接续清单

换机入口与未传输代码校验

换机交接已更新：代码全部可从 GitHub 恢复

本次新增的验证证据

新机器直接接手

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Command	arch-context	repo-harness
`complete`	7.80 → 3.09 s	10.29 → 5.64 s
`checkpoint`	0.93 → 0.40 s	1.56 → 1.11 s
`constraints check`	1.11 → 0.59 s	1.32 → 0.96 s

codegraph-adapter: read the index only through the in-process read-only handle #574

Description

Goal

Why

Current read paths (main at the time of writing)

Scope

Boundaries

Out of scope

Activity

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

21 remaining items

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 13, 2026

Ancienttwo commented on Nov 14, 2026

换机交接快照 — 2026-11-14 10:13 Asia/Taipei

先看这三点

Pane、分支与可恢复状态

已决定的边界，接手时沿用

S2：代码已写，广范围测试实际已结束，但没提交

S4：可直接从远端恢复，三个问题仍未决

S5 / #597：round-2 本地通过部分验证，远端仍是 round-1

S3 / S6 接续清单

换机入口与未传输代码校验

Ancienttwo commented on Nov 14, 2026

换机交接已更新：代码全部可从 GitHub 恢复

本次新增的验证证据

新机器直接接手

Ancienttwo commented on Nov 14, 2026

Ancienttwo commented on Nov 14, 2026

Ancienttwo commented on Nov 14, 2026

Ancienttwo commented on Nov 14, 2026

Ancienttwo commented on Nov 14, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions