witan-code 0.8.0__tar.gz → 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. {witan_code-0.8.0 → witan_code-0.9.0}/CHANGELOG.md +111 -0
  2. {witan_code-0.8.0 → witan_code-0.9.0}/PKG-INFO +36 -2
  3. {witan_code-0.8.0 → witan_code-0.9.0}/README.md +35 -1
  4. {witan_code-0.8.0 → witan_code-0.9.0}/docs/BRANCH_INDEXING.md +77 -1
  5. {witan_code-0.8.0 → witan_code-0.9.0}/pyproject.toml +2 -2
  6. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_cli_dispatch.py +28 -0
  7. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_config_targets.py +67 -0
  8. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_context.py +83 -2
  9. witan_code-0.9.0/tests/test_graph.py +85 -0
  10. witan_code-0.9.0/tests/test_indexer_scope.py +378 -0
  11. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/bridge.py +27 -10
  12. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/cli.py +22 -3
  13. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/config.py +47 -3
  14. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/context.py +52 -3
  15. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/extensions/pi/codegraph.ts +3 -2
  16. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/graph.py +47 -1
  17. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/indexer.py +155 -20
  18. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/server.py +1 -0
  19. witan_code-0.8.0/tests/test_graph.py +0 -23
  20. {witan_code-0.8.0 → witan_code-0.9.0}/.gitignore +0 -0
  21. {witan_code-0.8.0 → witan_code-0.9.0}/config/claude.json +0 -0
  22. {witan_code-0.8.0 → witan_code-0.9.0}/config/copilot.json +0 -0
  23. {witan_code-0.8.0 → witan_code-0.9.0}/config/pi.json +0 -0
  24. {witan_code-0.8.0 → witan_code-0.9.0}/docs/CLI_REFERENCE.md +0 -0
  25. {witan_code-0.8.0 → witan_code-0.9.0}/docs/EDGE_PRECISION_TIERS.md +0 -0
  26. {witan_code-0.8.0 → witan_code-0.9.0}/docs/PACKAGE_MAP.md +0 -0
  27. {witan_code-0.8.0 → witan_code-0.9.0}/docs/STAGE2_STITCHING.md +0 -0
  28. {witan_code-0.8.0 → witan_code-0.9.0}/docs/SYMBOL_FORMAT.md +0 -0
  29. {witan_code-0.8.0 → witan_code-0.9.0}/docs/SYMBOL_TABLE.md +0 -0
  30. {witan_code-0.8.0 → witan_code-0.9.0}/docs/USER_GUIDE.md +0 -0
  31. {witan_code-0.8.0 → witan_code-0.9.0}/install.sh +0 -0
  32. {witan_code-0.8.0 → witan_code-0.9.0}/tests/__init__.py +0 -0
  33. {witan_code-0.8.0 → witan_code-0.9.0}/tests/conftest.py +0 -0
  34. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_branches.py +0 -0
  35. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_bridge.py +0 -0
  36. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_cli_hooks.py +0 -0
  37. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_cli_output_format.py +0 -0
  38. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_config.py +0 -0
  39. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_crossrepo.py +0 -0
  40. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_edges.py +0 -0
  41. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_elicit.py +0 -0
  42. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_enrichment.py +0 -0
  43. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_hooks.py +0 -0
  44. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_indexer.py +0 -0
  45. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_languages.py +0 -0
  46. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_maintenance.py +0 -0
  47. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_package_map.py +0 -0
  48. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_remote_proxy.py +0 -0
  49. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_repo.py +0 -0
  50. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_server.py +0 -0
  51. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_setup.py +0 -0
  52. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_stitch.py +0 -0
  53. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_store.py +0 -0
  54. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_symbol_table.py +0 -0
  55. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_tasks.py +0 -0
  56. {witan_code-0.8.0 → witan_code-0.9.0}/tests/test_visualize.py +0 -0
  57. {witan_code-0.8.0 → witan_code-0.9.0}/uv.lock +0 -0
  58. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/__init__.py +0 -0
  59. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/__main__.py +0 -0
  60. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/bridge_extractors.py +0 -0
  61. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/edges.py +0 -0
  62. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/elicit.py +0 -0
  63. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/hooks.py +0 -0
  64. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/maintenance.py +0 -0
  65. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/output.py +0 -0
  66. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/package_map.py +0 -0
  67. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries/bridge.gq +0 -0
  68. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries/code_mutations.gq +0 -0
  69. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries/code_read.gq +0 -0
  70. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries/delete.gq +0 -0
  71. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries_ts/bash.scm +0 -0
  72. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries_ts/hcl.scm +0 -0
  73. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries_ts/python.scm +0 -0
  74. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries_ts/sql.scm +0 -0
  75. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries_ts/typescript.scm +0 -0
  76. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/queries_ts/yaml.scm +0 -0
  77. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/remote/__init__.py +0 -0
  78. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/remote/oidc.py +0 -0
  79. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/remote/proxy.py +0 -0
  80. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/repo.py +0 -0
  81. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/schema/bridge-schema.pg +0 -0
  82. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/schema/code-schema.pg +0 -0
  83. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/setup.py +0 -0
  84. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/skills/witan-code/SKILL.md +0 -0
  85. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/stitch.py +0 -0
  86. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/store.py +0 -0
  87. {witan_code-0.8.0 → witan_code-0.9.0}/witan_code/visualize.py +0 -0
@@ -6,6 +6,117 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
7
7
  a MINOR bump may include breaking changes).
8
8
 
9
+ ## [0.9.0] - 2026-07-31
10
+
11
+ ### Added
12
+
13
+ - **`WITAN_CODE_INDEX_ROLE` — an explicit writer role for the shared
14
+ default-branch view.** On the deployed cluster a per-repo code graph is one
15
+ graph for the whole team, and its `main` view — the one every reader falls
16
+ back to — had no owner. It has one now: CI indexes the default branch,
17
+ everyone else reads it. Indexing a shared graph's default-branch view is
18
+ refused unless the process declares itself the writer
19
+ (`WITAN_CODE_INDEX_ROLE=ci`, or `index_role = "ci"` on a `[targets.<name>]`
20
+ block); an unrecognized value is an error rather than a silent demotion to
21
+ reader, which would freeze the shared view with nothing to explain it.
22
+ Authority is deliberately a **role, not a transport**: the CI indexer is
23
+ remote too, so the blanket "refuse writes when remote" that 0.8.1 shipped as
24
+ a down payment would have blocked the one writer the design depends on.
25
+ `_may_purge` now reads "not remote **or** designated writer" accordingly —
26
+ dropping rows for files deleted from the default branch is precisely CI's
27
+ job. Local stores are unaffected (one user, who is their writer), and branch
28
+ views stay writable by anyone: they are branch-scoped, so in-flight work
29
+ never lands on the shared view. That exemption is deliberate — per-user
30
+ branch views live *on* the shared graph, so isolated agents can see each
31
+ other's work as it happens. Two follow-ups that decision requires
32
+ (namespacing views per writer, and re-scoping the purge to "this actor owns
33
+ the view being written") are noted in the doc and not in this change. See
34
+ [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view).
35
+
36
+ ### Changed
37
+
38
+ - **The `inject-context` block now names a call instead of stating a
39
+ preference.** The old block ended with "prefer `code_search_symbol` /
40
+ `code_find_definition` / ... over grep", which measured badly: across 50
41
+ sessions in `agent-kit` that received it, the block was injected 248 times
42
+ and produced 5 `code_*` calls against 802 Grep/Read/Glob/Explore calls, with
43
+ 46 of the 50 sessions never calling a `code_*` tool at all. The cause is that
44
+ the `code_*` tools reach the agent **deferred** — name only, no schema, a
45
+ `ToolSearch` round-trip short of callable — in 50 of 50 of those sessions,
46
+ while Grep/Read/Glob are always loaded. Preferring a tool that is not in the
47
+ tool list is not an actionable instruction. The block now leads with the
48
+ `ToolSearch(query="+code_ find_definition callers impact")` that makes them
49
+ callable (the `+code_` form is used because `select:` needs the full
50
+ `mcp__<server>__` prefix, which depends on the user's MCP config), gives a
51
+ `code_find_definition` → `symbol_id` → `code_callers`/`code_impact` template
52
+ to fill in, reports how many *other* repos are indexed so an empty
53
+ `code_interface_*` result is not misread as "nothing consumes this", and
54
+ points at the `/witan-code` skill. Net cost is ~110 chars per prompt; a
55
+ regression test caps the whole block at 600.
56
+
57
+ ### Fixed
58
+
59
+ - **`branches --prune` no longer prunes a shared graph.** It deletes store
60
+ branches whose git branch is absent from *this machine's* refs — against a
61
+ graph shared by the team, "this checkout doesn't have that branch" and "that
62
+ branch is gone" are indistinguishable, so one user pruning would delete
63
+ another user's in-flight branch view. Now refused per-repo when the store is
64
+ remote, with the repo named. This is a **separate** check from the ADR-0005
65
+ guard added in 0.8.1: that one refuses `--prune` in remote MCP-*client* mode
66
+ (`WITAN_REMOTE_URL`), which is about where the read tools dispatch, whereas
67
+ cluster addressing is the data tier — either can be remote without the other.
68
+
69
+ ## [0.8.1] - 2026-07-31
70
+
71
+ ### Fixed
72
+
73
+ - **Nested checkouts are no longer indexed as part of the parent repo.** The
74
+ walk skipped `.git` *directories*, but a linked worktree or submodule marks
75
+ itself with a `.git` **file**, so `.claude/worktrees/<name>/` was descended
76
+ into and every file there was attributed to the parent repo — at a different
77
+ path, at whatever revision that worktree happened to be on. In this repo's
78
+ own store that was **732 of 990 indexed files (74%)**, spread across every
79
+ branch view. The practical damage was to `code_search_symbol` and friends:
80
+ a query returned the same function many times over with *different, older
81
+ signatures*, so reading the first hit gave a confidently wrong answer, and
82
+ `code_impact` inflated blast radius with callers that only exist on an
83
+ abandoned branch. Any subdirectory holding a `.git` entry is now skipped.
84
+ Indexing from *inside* a worktree is unaffected — only descending into one
85
+ from the parent is refused — so the hooks keep working on a branch.
86
+ - **A full-repo index now purges files the repo no longer has**, reported as
87
+ `purged=N`. Nothing removed a `CodeFile`/`Symbol` once written unless that
88
+ same file was re-indexed, so deletions leaked forever: this repo's store
89
+ still held `_detach.py` and its tests, moved out to `witan-core` several
90
+ releases ago. This is also what clears the worktree rows above — excluding a
91
+ path stops adding rows but cannot retract the ones already written, so
92
+ without it the fix would only have stopped the bleeding.
93
+
94
+ Purging never runs against a shared cluster graph (`is_remote`): there the
95
+ default branch is indexed by CI and everyone else gets a read-only view, so
96
+ one developer's working tree must not reconcile it for everybody. Inert
97
+ today — code stores are still local — and load-bearing once witan-code
98
+ addresses `--server`/`--graph`.
99
+
100
+ Membership is decided by the set of files just collected, **not** by whether
101
+ the file still exists on disk: a linked worktree's files are on disk and
102
+ still must go. Purging requires a confirmed git root and a full-repo target;
103
+ a subpath, a single file (the reindex hook), or a non-git directory never
104
+ purges — without a git root `base` falls back to the target directory, which
105
+ would make every stored path look stale.
106
+
107
+ ### Changed
108
+
109
+ - An unreadable directory now suppresses the purge for that run (and is
110
+ reported on stderr, counting toward `errors`). `os.walk` hands such a
111
+ directory to `onerror` and otherwise continues silently, so a subtree the
112
+ walk could not enter is indistinguishable from one that was deleted — which
113
+ would have taken its still-present files' rows with it. Indexing still
114
+ proceeds with whatever was readable; only the destructive half backs off.
115
+ - The file walk prunes as it goes (`os.walk`) instead of walking everything and
116
+ filtering afterwards, so `node_modules`/`.venv` subtrees are no longer
117
+ traversed in full. Collection order is now sorted, making a run reproducible.
118
+ - `code_reindex` returns a `purged` count alongside the existing counters.
119
+
9
120
  ## [0.8.0] - 2026-07-31
10
121
 
11
122
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: witan-code
3
- Version: 0.8.0
3
+ Version: 0.9.0
4
4
  Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
5
  Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
6
  Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -337,6 +337,7 @@ symlink alternative:
337
337
  | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
338
338
  | `WITAN_REPO` | — | override the detected repo slug |
339
339
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
340
+ | `WITAN_CODE_INDEX_ROLE` | `client` | `ci` designates this process the writer of a shared graph's default-branch view. Only meaningful against a shared cluster graph; local stores are unaffected. See [Branch indexing](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view) |
340
341
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
341
342
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
342
343
  | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
@@ -559,7 +560,11 @@ A Pi equivalent of all four lives in one extension,
559
560
  - **`witan-code inject-context`** (`UserPromptSubmit`) — prints a short status
560
561
  block: whether the current repo is indexed (file count, last-updated time),
561
562
  or that a background index from `session-init` is still running (checking
562
- the same lock path above), plus a nudge to prefer `code_*` tools over grep.
563
+ the same lock path above), how many *other* repos are indexed (so the agent
564
+ can tell "no cross-repo consumers" from "no cross-repo data"), and the
565
+ `ToolSearch` call that makes the `code_*` tools callable when the harness
566
+ delivers them deferred — followed by a `code_find_definition` →
567
+ `code_callers`/`code_impact` call template.
563
568
  Independent of `witan`'s own `inject-context` hook (no cross-package
564
569
  coupling) — register it alone for a witan-code-only install. Prints
565
570
  nothing when the repo has neither a store nor an index in flight.
@@ -573,9 +578,38 @@ Manual install: register the bare commands directly under the matching event
573
578
  in `settings.json` (see the linked README for the exact JSON) — there are no
574
579
  scripts to symlink.
575
580
 
581
+ ## What gets indexed
582
+
583
+ The walk skips the usual noise directories (`.git`, `node_modules`, `.venv`,
584
+ `__pycache__`, `dist`, `build`, the various caches) and — importantly — does
585
+ not descend into a **nested checkout**: any subdirectory containing a `.git`
586
+ entry belongs to a different repository. That covers linked worktrees
587
+ (`.claude/worktrees/<name>/`, where `.git` is a *file*, not a directory),
588
+ submodules, and plain clones dropped inside the tree. Their files are that
589
+ repo's; indexing them here would attribute them to this one and leave the
590
+ store serving stale copies of itself under a second set of paths.
591
+
592
+ Indexing *from inside* a worktree still works normally — only descending into
593
+ one from the parent is refused — so the hooks keep indexing while an agent
594
+ works on a branch.
595
+
576
596
  ## Incremental indexing
577
597
 
578
598
  Each `CodeFile` stores a sha256 `contentHash`. On reindex, if the hash is
579
599
  unchanged the file is skipped. Otherwise its `Symbol`s and `CodeFile` are
580
600
  deleted (as separate `delete.gq` calls — Omnigraph cannot mix deletes with
581
601
  inserts in one query) and then re-parsed and re-inserted.
602
+
603
+ A **full-repo** index additionally purges rows for files the repo no longer
604
+ has — deleted, or newly excluded by the rules above. Membership is decided by
605
+ the set of files just collected, not by whether the file still exists on disk:
606
+ a linked worktree's files are very much on disk, they simply aren't this
607
+ repo's. The count is reported as `purged=N` when non-zero. Purging requires a
608
+ confirmed git root; indexing a subpath, a single file (the reindex hook), a
609
+ directory that isn't a git checkout, or a directory the walk could not fully
610
+ read never purges.
611
+
612
+ Nor does a **shared cluster graph** (`is_remote`). There the default branch is
613
+ indexed by CI and everyone else reads it — reconciling it against one
614
+ developer's working tree (a sparse checkout, a stale one, uncommitted
615
+ deletions) would purge files for every other user of that graph.
@@ -305,6 +305,7 @@ symlink alternative:
305
305
  | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
306
306
  | `WITAN_REPO` | — | override the detected repo slug |
307
307
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
308
+ | `WITAN_CODE_INDEX_ROLE` | `client` | `ci` designates this process the writer of a shared graph's default-branch view. Only meaningful against a shared cluster graph; local stores are unaffected. See [Branch indexing](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view) |
308
309
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
309
310
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
310
311
  | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
@@ -527,7 +528,11 @@ A Pi equivalent of all four lives in one extension,
527
528
  - **`witan-code inject-context`** (`UserPromptSubmit`) — prints a short status
528
529
  block: whether the current repo is indexed (file count, last-updated time),
529
530
  or that a background index from `session-init` is still running (checking
530
- the same lock path above), plus a nudge to prefer `code_*` tools over grep.
531
+ the same lock path above), how many *other* repos are indexed (so the agent
532
+ can tell "no cross-repo consumers" from "no cross-repo data"), and the
533
+ `ToolSearch` call that makes the `code_*` tools callable when the harness
534
+ delivers them deferred — followed by a `code_find_definition` →
535
+ `code_callers`/`code_impact` call template.
531
536
  Independent of `witan`'s own `inject-context` hook (no cross-package
532
537
  coupling) — register it alone for a witan-code-only install. Prints
533
538
  nothing when the repo has neither a store nor an index in flight.
@@ -541,9 +546,38 @@ Manual install: register the bare commands directly under the matching event
541
546
  in `settings.json` (see the linked README for the exact JSON) — there are no
542
547
  scripts to symlink.
543
548
 
549
+ ## What gets indexed
550
+
551
+ The walk skips the usual noise directories (`.git`, `node_modules`, `.venv`,
552
+ `__pycache__`, `dist`, `build`, the various caches) and — importantly — does
553
+ not descend into a **nested checkout**: any subdirectory containing a `.git`
554
+ entry belongs to a different repository. That covers linked worktrees
555
+ (`.claude/worktrees/<name>/`, where `.git` is a *file*, not a directory),
556
+ submodules, and plain clones dropped inside the tree. Their files are that
557
+ repo's; indexing them here would attribute them to this one and leave the
558
+ store serving stale copies of itself under a second set of paths.
559
+
560
+ Indexing *from inside* a worktree still works normally — only descending into
561
+ one from the parent is refused — so the hooks keep indexing while an agent
562
+ works on a branch.
563
+
544
564
  ## Incremental indexing
545
565
 
546
566
  Each `CodeFile` stores a sha256 `contentHash`. On reindex, if the hash is
547
567
  unchanged the file is skipped. Otherwise its `Symbol`s and `CodeFile` are
548
568
  deleted (as separate `delete.gq` calls — Omnigraph cannot mix deletes with
549
569
  inserts in one query) and then re-parsed and re-inserted.
570
+
571
+ A **full-repo** index additionally purges rows for files the repo no longer
572
+ has — deleted, or newly excluded by the rules above. Membership is decided by
573
+ the set of files just collected, not by whether the file still exists on disk:
574
+ a linked worktree's files are very much on disk, they simply aren't this
575
+ repo's. The count is reported as `purged=N` when non-zero. Purging requires a
576
+ confirmed git root; indexing a subpath, a single file (the reindex hook), a
577
+ directory that isn't a git checkout, or a directory the walk could not fully
578
+ read never purges.
579
+
580
+ Nor does a **shared cluster graph** (`is_remote`). There the default branch is
581
+ indexed by CI and everyone else reads it — reconciling it against one
582
+ developer's working tree (a sparse checkout, a stale one, uncommitted
583
+ deletions) would purge files for every other user of that graph.
@@ -42,7 +42,83 @@ Branch stores are re-derivable caches, so lifecycle is deletion, not merge:
42
42
  is cheaper and always consistent; merging stale Lance rows is neither).
43
43
  * `witan-code branches [--prune]` lists omnigraph branches per store and
44
44
  deletes those whose git branch no longer exists (checked against
45
- `git for-each-ref`), plus `_detached`.
45
+ `git for-each-ref`), plus `_detached`. Pruning is a **local-store**
46
+ operation on both counts: it is refused in remote MCP-client mode (ADR
47
+ 0005) and refused against a remote store (below). On a shared graph one
48
+ machine's missing git ref is not evidence a branch is dead — it would
49
+ delete another user's in-flight view.
50
+
51
+ ## Who may write the shared default-branch view
52
+
53
+ On the deployed omnigraph cluster a per-repo code graph is **one graph for
54
+ the whole team**, so `main` — the view with no branch scoping, which every
55
+ reader falls back to — has no natural owner. It gets one explicitly: **CI
56
+ indexes the default branch, everyone else reads it.**
57
+
58
+ Writer authority is a **role, not a transport**. "Refuse writes when the
59
+ store is remote" cannot be applied unconditionally, because the CI indexer is
60
+ remote too and is the one actor that must write. So the role is declared:
61
+
62
+ ```
63
+ WITAN_CODE_INDEX_ROLE=ci # or index_role = "ci" on a [targets.<name>] block
64
+ ```
65
+
66
+ Values are `client` (the default — reads the shared view, never writes it)
67
+ and `ci`. An unrecognized value is an error rather than a silent
68
+ demotion to `client`, which would leave the shared view frozen with nothing
69
+ to explain it.
70
+
71
+ What the role gates (`witan_code.graph.check_writable`,
72
+ `witan_code.indexer._may_purge`):
73
+
74
+ | Write | Local store | Shared graph, `client` | Shared graph, `ci` |
75
+ |---|---|---|---|
76
+ | default-branch (`main`) view | ✅ | ❌ refused | ✅ |
77
+ | branch view (`--branch <b>`) | ✅ | ✅ | ✅ |
78
+ | stale-file purge | ✅ | ❌ | ✅ |
79
+ | `branches --prune` | ✅ | ❌ | ❌ |
80
+
81
+ Local stores are unaffected by the role: they have one user, who is their
82
+ writer.
83
+
84
+ ### Per-user branch views live on the shared graph
85
+
86
+ **Decided (2026-07-31).** In-flight branch views go on the shared cluster
87
+ graph, not in a local store queried alongside it. Isolated agents being able
88
+ to see each other's work *as it is being made* — rather than after a merge —
89
+ is a large part of what the shared service is for, and that only works if
90
+ the views are somewhere every reader can reach.
91
+
92
+ Branch views are therefore exempt from the default-view gate above: a
93
+ branch-scoped write cannot reach the view everyone falls back to, so it
94
+ needs no role. Anyone may write their own.
95
+
96
+ Two things this decision requires that are **not implemented yet**:
97
+
98
+ 1. **Branch views must be namespaced per writer.** `repo.store_branch()`
99
+ derives the view name from the git branch alone, so on a shared graph two
100
+ checkouts on `feature-x` write the *same* view and overwrite each other
101
+ with different working-tree states. Isolation and visibility are both
102
+ required, and they are not in tension: namespace the write key (the
103
+ writer's actor id alongside the branch), and keep reads able to enumerate
104
+ every view for a given branch. Layer 1 already keys in-flight work the
105
+ same way — `CodeBranch (repo, branch)` with `WorksOn`/`ForProject` edges
106
+ (below) — so the two layers should agree on the key.
107
+
108
+ 2. **Stale-file purging stays off for branch views until (1) lands.**
109
+ `_may_purge` refuses on a remote store for everyone but CI, branch views
110
+ included, so a developer's deleted files linger in their own view. That is
111
+ correct *today*: an un-namespaced shared branch view has no single
112
+ authoritative writer. Once views are namespaced it becomes wrong, and the
113
+ gate should be restated as "this actor owns the view being written" — of
114
+ which "CI owns `main`" is one case and "I own my own branch view" is the
115
+ other.
116
+
117
+ Reaping is consequently **server-side and mandatory**, not a client
118
+ convenience: branch sprawl is real under this decision, and no client can
119
+ tell whose branch views are still live — which is why `branches --prune` is
120
+ refused against a remote store above and stays that way. See
121
+ `tk-branch-cedar-gating-stale-code-graph-branch-reap-0c621c`.
46
122
 
47
123
  ## Bridge store
48
124
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "witan-code"
3
- version = "0.8.0"
3
+ version = "0.9.0"
4
4
  description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
5
5
  readme = "README.md"
6
6
  license = "BSD-3-Clause"
@@ -90,7 +90,7 @@ testpaths = ["tests"]
90
90
  packages = ["witan_code"]
91
91
 
92
92
  [tool.bumpversion]
93
- current_version = "0.8.0"
93
+ current_version = "0.9.0"
94
94
  allow_dirty = true
95
95
 
96
96
  [[tool.bumpversion.files]]
@@ -246,3 +246,31 @@ def test_branches_prune_is_refused_in_remote_mode(monkeypatch, capsys):
246
246
  cli_module.branches(prune=True)
247
247
 
248
248
  assert "does not share" in capsys.readouterr().out
249
+
250
+
251
+ def test_branches_prune_is_refused_against_a_shared_store(monkeypatch, capsys):
252
+ """Remote MCP dispatch and a remote STORE are independent: either can be
253
+ remote without the other. A shared graph's branches belong to every user
254
+ of it, so "this checkout has no such git branch" is not evidence the
255
+ branch is dead.
256
+ """
257
+ from witan_code import repo as repo_module
258
+
259
+ repo = "https://github.com/test/a"
260
+ srv = _stub(
261
+ code_indexed_branches=[{"repo": repo, "branches": ["main", "someone-elses"]}]
262
+ )
263
+ monkeypatch.setattr(cli_module, "_srv", lambda: srv)
264
+ monkeypatch.setattr(cli_module, "_is_remote", lambda: False)
265
+ monkeypatch.setattr(repo_module, "detect", lambda **_kw: repo)
266
+ monkeypatch.setattr(repo_module, "local_branches", lambda: frozenset({"mine"}))
267
+
268
+ def _boom(_name):
269
+ raise AssertionError("pruned a branch on a shared graph")
270
+
271
+ remote_client = SimpleNamespace(is_remote=True, delete_branch=_boom)
272
+ monkeypatch.setattr(cli_module, "_branch_client", lambda _repo: remote_client)
273
+
274
+ cli_module.branches(prune=True)
275
+
276
+ assert "refusing to prune a shared graph" in capsys.readouterr().out
@@ -310,3 +310,70 @@ def test_load_remote_config_from_target(monkeypatch, toml_file, tmp_path):
310
310
  assert cfg.url == "https://witan.example.org/mcp"
311
311
  assert cfg.oidc_audience == "witan"
312
312
  assert cfg.target_name == "hosted"
313
+
314
+
315
+ # ── index_role: who may write a shared graph's default-branch view ───────────
316
+
317
+
318
+ def _isolate_role(monkeypatch, toml_file, content: str = "") -> None:
319
+ monkeypatch.setenv("WITAN_CONFIG", toml_file(content))
320
+ monkeypatch.delenv("WITAN_TARGET", raising=False)
321
+ monkeypatch.delenv("WITAN_CODE_INDEX_ROLE", raising=False)
322
+ monkeypatch.setenv("WITAN_REPO", "https://github.com/mitodl/agent-kit")
323
+
324
+
325
+ def test_index_role_defaults_to_client(monkeypatch, toml_file):
326
+ """Writing a shared graph's default view is opt-in, never inherited."""
327
+ _isolate_role(monkeypatch, toml_file)
328
+
329
+ cfg = load()
330
+ assert cfg.index_role == "client"
331
+ assert cfg.is_designated_writer is False
332
+
333
+
334
+ def test_index_role_from_env(monkeypatch, toml_file):
335
+ _isolate_role(monkeypatch, toml_file)
336
+ monkeypatch.setenv("WITAN_CODE_INDEX_ROLE", "ci")
337
+
338
+ assert load().is_designated_writer is True
339
+
340
+
341
+ def test_index_role_from_target(monkeypatch, toml_file):
342
+ _isolate_role(
343
+ monkeypatch,
344
+ toml_file,
345
+ """
346
+ [targets.hosted]
347
+ index_role = "ci"
348
+ match_orgs = ["mitodl"]
349
+ """,
350
+ )
351
+
352
+ cfg = load()
353
+ assert cfg.target_name == "hosted"
354
+ assert cfg.is_designated_writer is True
355
+
356
+
357
+ def test_index_role_env_overrides_target(monkeypatch, toml_file):
358
+ _isolate_role(
359
+ monkeypatch,
360
+ toml_file,
361
+ """
362
+ [targets.hosted]
363
+ index_role = "ci"
364
+ match_orgs = ["mitodl"]
365
+ """,
366
+ )
367
+ monkeypatch.setenv("WITAN_CODE_INDEX_ROLE", "client")
368
+
369
+ assert load().is_designated_writer is False
370
+
371
+
372
+ def test_unknown_index_role_is_rejected(monkeypatch, toml_file):
373
+ """Not defaulted: a typo silently demoting the CI indexer to a reader
374
+ leaves the shared view frozen with nothing to explain it."""
375
+ _isolate_role(monkeypatch, toml_file)
376
+ monkeypatch.setenv("WITAN_CODE_INDEX_ROLE", "writer")
377
+
378
+ with pytest.raises(ValueError, match="Unknown index_role"):
379
+ load()
@@ -66,10 +66,73 @@ def test_inject_context_reports_indexed_store(tmp_path, monkeypatch):
66
66
 
67
67
  assert "https://github.com/test/cg" in text
68
68
  assert "3 files" in text
69
- assert "code_search_symbol" in text
69
+ assert "code_find_definition" in text
70
70
  assert "background reindex is currently running" not in text
71
71
 
72
72
 
73
+ def test_inject_context_names_the_toolsearch_unlock(tmp_path, monkeypatch):
74
+ """The block must name the call that makes `code_*` callable.
75
+
76
+ The tools reach the agent deferred (name only, no schema) in every measured
77
+ session, so a bare "prefer code_* over grep" points at tools that are not in
78
+ the tool list. The `+code_` query form is the one that works: `select:` needs
79
+ the full `mcp__<server>__` prefix, which depends on the user's MCP config.
80
+ """
81
+ monkeypatch.setenv("WITAN_REPO", "https://github.com/test/cg")
82
+ code_dir = tmp_path / "code"
83
+ monkeypatch.setenv("WITAN_CODE_DIR", str(code_dir))
84
+ _lock(tmp_path, monkeypatch, tmp_path / "project")
85
+
86
+ store = code_dir / "https_github.com_test_cg.omni"
87
+ store.mkdir(parents=True)
88
+ _stub_store_stats(monkeypatch)
89
+
90
+ text = context.inject_context()
91
+
92
+ assert "ToolSearch" in text
93
+ assert '"+code_ find_definition callers impact"' in text
94
+ assert "select:" not in text # would need a prefix the hook cannot know
95
+ assert "/witan-code" in text # the skill, per the task's direction 3
96
+
97
+
98
+ def test_inject_context_warns_when_no_other_repo_is_indexed(tmp_path, monkeypatch):
99
+ """Zero cross-repo coverage is the one thing an agent gets silently wrong."""
100
+ monkeypatch.setenv("WITAN_REPO", "https://github.com/test/cg")
101
+ code_dir = tmp_path / "code"
102
+ monkeypatch.setenv("WITAN_CODE_DIR", str(code_dir))
103
+ _lock(tmp_path, monkeypatch, tmp_path / "project")
104
+
105
+ store = code_dir / "https_github.com_test_cg.omni"
106
+ store.mkdir(parents=True)
107
+ _stub_store_stats(monkeypatch)
108
+
109
+ text = context.inject_context()
110
+
111
+ assert "No other repo is indexed" in text
112
+ assert "absence of data, not absence of consumers" in text
113
+
114
+
115
+ def test_inject_context_reports_cross_repo_coverage(tmp_path, monkeypatch):
116
+ monkeypatch.setenv("WITAN_REPO", "https://github.com/test/cg")
117
+ code_dir = tmp_path / "code"
118
+ monkeypatch.setenv("WITAN_CODE_DIR", str(code_dir))
119
+ _lock(tmp_path, monkeypatch, tmp_path / "project")
120
+
121
+ store = code_dir / "https_github.com_test_cg.omni"
122
+ store.mkdir(parents=True)
123
+ for other in (
124
+ "https_github.com_test_other.omni",
125
+ "https_github.com_test_third.omni",
126
+ ):
127
+ (code_dir / other).mkdir()
128
+ _stub_store_stats(monkeypatch)
129
+
130
+ text = context.inject_context()
131
+
132
+ assert "2 other repos indexed" in text # the current repo is not counted
133
+ assert "No other repo is indexed" not in text
134
+
135
+
73
136
  def test_inject_context_notes_in_progress_alongside_existing_store(
74
137
  tmp_path, monkeypatch
75
138
  ):
@@ -148,4 +211,22 @@ def test_inject_context_degrades_when_dir_stats_fails(tmp_path, monkeypatch):
148
211
  text = context.inject_context()
149
212
 
150
213
  assert "3 files." in text # no "last updated" clause, but not blanked either
151
- assert "code_search_symbol" in text
214
+ assert "code_find_definition" in text
215
+
216
+
217
+ def test_inject_context_block_stays_small(tmp_path, monkeypatch):
218
+ """Guard against creep: this is prepended to every prompt, forever.
219
+
220
+ Not a style preference — an extra 100 chars here is paid on every prompt of
221
+ every session in every repo that has witan-code installed.
222
+ """
223
+ monkeypatch.setenv("WITAN_REPO", "https://github.com/test/cg")
224
+ code_dir = tmp_path / "code"
225
+ monkeypatch.setenv("WITAN_CODE_DIR", str(code_dir))
226
+ _lock(tmp_path, monkeypatch, tmp_path / "project")
227
+
228
+ store = code_dir / "https_github.com_test_cg.omni"
229
+ store.mkdir(parents=True)
230
+ _stub_store_stats(monkeypatch)
231
+
232
+ assert len(context.inject_context()) < 600
@@ -0,0 +1,85 @@
1
+ """witan-code-subclass-specific OmnigraphClient tests.
2
+
3
+ The generic base machinery (_find_binary lookup order, OCC conflict surfacing,
4
+ admission-cap backoff) is covered in packages/witan-core/tests/test_omnigraph.py.
5
+ Here we only assert witan-code's own subclass tail: the setup-hint in the
6
+ binary-not-found message. (branch ops + bulk load are exercised against a real
7
+ store in test_branches.py / test_indexer.py.)
8
+ """
9
+
10
+ import shutil
11
+ from pathlib import Path
12
+ from types import SimpleNamespace
13
+
14
+ import pytest
15
+
16
+ from witan_code import config as cfg_module
17
+ from witan_code.graph import (
18
+ OmnigraphClient,
19
+ SharedGraphWriteRefused,
20
+ check_writable,
21
+ )
22
+
23
+
24
+ def test_find_binary_message_names_witan_code_setup(tmp_path, monkeypatch):
25
+ monkeypatch.setattr(shutil, "which", lambda name: None)
26
+ monkeypatch.setattr(Path, "home", lambda: tmp_path)
27
+
28
+ with pytest.raises(RuntimeError, match="witan-code setup"):
29
+ OmnigraphClient._find_binary()
30
+
31
+
32
+ # ── check_writable: who may write a shared graph's default-branch view ───────
33
+ #
34
+ # On the cluster, a per-repo code graph is one graph for the whole team and its
35
+ # default-branch view is indexed by CI. `branch is None` is what makes a write
36
+ # target that view.
37
+
38
+
39
+ def _cfg(role: str = cfg_module.INDEX_ROLE_CLIENT) -> cfg_module.Config:
40
+ return cfg_module.Config(
41
+ code_dir=Path("/code"),
42
+ author="test",
43
+ queries_dir=Path("/queries"),
44
+ schema_file=Path("/schema.pg"),
45
+ bridge_schema_file=Path("/bridge.pg"),
46
+ index_role=role,
47
+ )
48
+
49
+
50
+ def _check(*, remote: bool, branch: str | None, role: str) -> None:
51
+ check_writable(
52
+ client=SimpleNamespace(is_remote=remote),
53
+ branch=branch,
54
+ cfg=_cfg(role),
55
+ slug="https://github.com/test/a",
56
+ )
57
+
58
+
59
+ def test_local_store_writes_its_main_view_whatever_the_role():
60
+ """A local store has one user, who is its writer. The role is about the
61
+ shared graph and must not gate the single-machine case."""
62
+ _check(remote=False, branch=None, role=cfg_module.INDEX_ROLE_CLIENT)
63
+
64
+
65
+ def test_shared_default_branch_view_refused_without_the_writer_role():
66
+ with pytest.raises(SharedGraphWriteRefused, match="owned by CI"):
67
+ _check(remote=True, branch=None, role=cfg_module.INDEX_ROLE_CLIENT)
68
+
69
+
70
+ def test_designated_writer_may_write_the_shared_default_branch_view():
71
+ """The CI indexer is remote too — authority comes from the declared role,
72
+ so a blanket "refuse when remote" would block the one writer there is."""
73
+ _check(remote=True, branch=None, role=cfg_module.INDEX_ROLE_CI)
74
+
75
+
76
+ def test_shared_branch_view_is_not_the_default_view():
77
+ """A branch-scoped write is isolated from the view everyone reads, so it
78
+ is not what this gate is protecting."""
79
+ _check(remote=True, branch="feature-x", role=cfg_module.INDEX_ROLE_CLIENT)
80
+
81
+
82
+ def test_refusal_names_the_way_out():
83
+ with pytest.raises(SharedGraphWriteRefused) as excinfo:
84
+ _check(remote=True, branch=None, role=cfg_module.INDEX_ROLE_CLIENT)
85
+ assert "WITAN_CODE_INDEX_ROLE=ci" in str(excinfo.value)