sidegraph 0.15.0__tar.gz → 0.16.0__tar.gz

{sidegraph-0.15.0 → sidegraph-0.16.0}/.github/workflows/ci.yml

@@ -130,7 +130,7 @@ jobs:
           interpreter="$environment/bin/python"
           constraints=()
           if [ "$SDK_PAIR" = minimum ]; then
-            constraints=(fastmcp==3.4.2 mcp==1.24.0)
+            constraints=(fastmcp==3.4.2 mcp==1.30.0)
           fi
           uv pip install --python "$interpreter" "$wheel" pytest "${constraints[@]}"
           mkdir -p "$RUNNER_TEMP/sdk-check"
@@ -188,6 +188,7 @@ jobs:
           uv run pytest -q --junitxml="$env:RUNNER_TEMP/windows-core.xml" `
             tests/test_store_mutation_guard.py `
             tests/test_store_mutation_immediate.py tests/test_store_cross_process_mutations.py `
+            tests/test_hook_contention.py tests/test_retrieval_seeds.py `
             tests/test_portable_json.py tests/test_bootstrap_descriptor_cleanup.py `
             tests/test_server_result_contract.py tests/test_server_invocation_policy.py `
             tests/test_verify_git_stdin.py tests/test_seed_paths_portable.py `
@@ -197,6 +198,7 @@ jobs:
             tests/test_hot_index_facts.py `
             tests/test_delivery_evidence.py tests/test_delivery_stats.py tests/test_delivery_surfaces.py `
             tests/test_git_output_utf8.py `
+            tests/test_health_check_skill.py `
             $privateTests `
             tests/test_installed_wheel_smoke.py
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

{sidegraph-0.15.0 → sidegraph-0.16.0}/CHANGELOG.md

@@ -7,6 +7,42 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-10-20
+
+See [Using Sidegraph 0.16](docs/guides/using-0.16.md) for update, compatibility, and
+limitation notes.
+
+### Security
+
+- Raise the minimum MCP Python SDK to 1.30.0, which includes the upstream fix for
+  [GHSA-84m7-p3x7-pcfv](https://github.com/advisories/GHSA-84m7-p3x7-pcfv). The supported
+  SDK major remains 1.
+
+### Added
+
+- Add `/sidegraph:health-check`, a read-only installation report with six evidence sections
+  and prioritized manual recommendations. It uses an already identified Python interpreter
+  and skips doctor and stats paths when an existing SQLite index is unsafe to open.
+
+### Changed
+
+- Hook-owned SQLite handles now refuse lock contention immediately across session, stop,
+  tool-use and subagent entry paths. SessionStart's dedupe remains best-effort under overlap;
+  its graph, filesystem and Git work is outside this lock-wait bound.
+- Retrieval and file listings reuse a lazy, per-call descriptor lookup, avoiding repeated
+  full entity scans while preserving seed selection and rendered output.
+- `sidegraph-compact` reports distinct hot files retained when their content is not fully
+  represented in the immutable archive, with warnings that distinguish extra fields from
+  shared-value or structure differences.
+
+### Fixed
+
+- `list_domains` now bounds its complete MCP text response and reports matched, returned and
+  omitted counts with whole rows. Its provisional return shape changes from a bare list to a
+  JSON-text envelope; exact domain-id and query filters can retrieve rows left out by the cap.
+- `sidegraph-stats` withholds anchor health counts while a fresh index's binding statuses await
+  `sidegraph-sync`, while keeping the record inventory and reach figures available.
+
 ## [0.15.0] — 2026-10-18
 
 ### Added

{sidegraph-0.15.0 → sidegraph-0.16.0}/CLAUDE.md

@@ -13,7 +13,7 @@ task-aware retrieval + decision memory riding on the engine's entity graph.
 continuing participant in the project. A core feature must preserve, organize, or deliver
 accumulated project understanding. Document search by itself is not the product.
 
-Sidegraph is pre-1.0 (v0.15.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.16.0) — the full loop (capture, ratification, mistakes-first
 retrieval, refactor-surviving re-anchoring, semantic docs layer, mind-model domains, and the
 facts evidence layer) ships and is exercised end-to-end, but interfaces may still move before
 a stable release. See

{sidegraph-0.15.0 → sidegraph-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.15.0
+Version: 0.16.0
 Summary: Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine.
 Project-URL: Homepage, https://github.com/SantyagoSeaman/sidegraph
 Project-URL: Repository, https://github.com/SantyagoSeaman/sidegraph
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.13
 Requires-Dist: anyio>=4
 Requires-Dist: fastmcp<4,>=3.4.2
-Requires-Dist: mcp<2,>=1.24
+Requires-Dist: mcp<2,>=1.30
 Requires-Dist: pydantic>=2.9
 Requires-Dist: python-ulid>=3.0
 Description-Content-Type: text/markdown

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/README.md

@@ -26,6 +26,7 @@ If the repository already has ADRs or specs, use the
 ## Operate and maintain it
 
 - [Migrate an existing store to Sidegraph 0.14](guides/migrating-to-0.14.md).
+- [Check a Sidegraph installation](guides/health-check.md).
 - [Survive refactors and heal anchors](guides/surviving-refactors.md).
 - [Read what Sidegraph tells you when it needs attention](guides/troubleshooting.md).
 - [Run CI and scheduled maintenance](guides/ci-cd-maintenance.md).

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/concepts/mind-model.md

@@ -131,9 +131,11 @@ this matters in practice beyond an ordinary rename: freeing a community that a d
 still claims (give the successor no matching `path_prefixes`/`seed_anchors` instead of
 carrying the old rule forward).
 
-**Listing.** `list_domains(status=None)` returns every domain in the store — optionally
-filtered to one status — with membership/lineage counts (`member_count`, `seed_anchor_count`,
-`parent_slug`/`child_slugs`); it's the general "show me all domains" answer `list_proposed`
+**Listing.** `list_domains(status=None)` searches every status and returns whole domain rows
+inside a bounded JSON-text envelope, with counts and a hint when filters or output limits omit
+rows. Narrow by exact domain ids or query terms to reach a row from an omitted listing. Rows
+include membership/lineage fields (`member_count`, `seed_anchor_count`, `parent_slug` and
+`child_slugs`); this is the general "show me all domains" answer `list_proposed`
 (proposed-only) and `list_domain_candidates` (unclaimed-only) don't cover.
 
 ## How domains relate to engine communities

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/concepts/retrieval.md

@@ -103,6 +103,12 @@ an empty list with an explanatory `"note"` key — everything store-derived (`do
 takes the seeds as `files` and `entities`): given what the agent is about to touch, return a compact slice of structure *and* memory, memory ranked so the things
 most likely to save it from a repeat mistake come first.
 
+Within one retrieval or file-list call, descriptor resolution shares a lazy, operation-scoped
+lookup of parsed entities. It preserves the existing exact-path, pathless adoption, ambiguity,
+and winner rules while avoiding a full entity-table parse for each graph node. The lookup is
+discarded after the call; a later call sees entity changes. This is a performance-only change:
+seed selection, record ranking, budgets, and rendered output are unchanged.
+
 ### Seeds
 
 A `Seed` is either:

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/getting-started/installation.md

@@ -24,18 +24,18 @@ installs a non-editable wheel outside the checkout, checks its package bytes aga
 artifact, runs a CLI, and exchanges real MCP stdio messages in a Unicode/spaced directory.
 The exact selection is in [the CI workflow](../../.github/workflows/ci.yml).
 
-Separately, each release candidate runs real Claude Code and Codex sessions with the
+For the 0.14.0 release-candidate campaign, real Claude Code and Codex sessions ran with the
 installed plugin, in fresh host profiles, on Windows Server 2022 x64 and macOS 15 arm64,
-each with Python 3.13 and 3.14. Each run is the full plugin session for both hosts: the
+each with Python 3.13 and 3.14. Each run was the full plugin session for both hosts: the
 plugin's MCP server, `SessionStart` context, records before a Read, a bundled skill, a
 subagent brief, the `Stop` capture prompt, capture and ratification, and recall in a fresh
-session. The project folder and host profile paths contain a non-ASCII character.
+session. The project folder and host profile paths contained a non-ASCII character.
 
 **0.14.0 publication gate:** Claude Code 2.1.296 and Codex CLI 0.162.1 on all four cells
 above, including a Windows 3.14 cell with PowerShell 7 unavailable for preflight and both
 real host sessions. Windows 3.13 retains PowerShell 7; its launcher checks also cover 5.1.
-Stable publication requires the full gate to pass without a known-issue exception. The
-README's blue badges summarize release acceptance, rather than live workflow status or
+Stable publication of 0.14.0 required the full gate to pass without a known-issue exception.
+The README's blue badges summarize release acceptance, rather than live workflow status or
 support for every published version. Muse and OpenCode have the narrower coverage in
 their installation guides and are outside this native matrix.
 
@@ -45,14 +45,15 @@ with Git for Windows installed; they do not establish support for Windows hosts
 remains outside these checks.
 See [Windows](#windows) before installing a host plugin.
 
-Package dependencies support `fastmcp>=3.4.2,<4` and `mcp>=1.24,<2`. Major SDK upgrades
+Package dependencies support `fastmcp>=3.4.2,<4` and `mcp>=1.30,<2`. Major SDK upgrades
 require a separate compatibility review; an unlocked package install may resolve newer
 versions within those bounds than the development lockfile.
 
 ### Windows
 
-The native checks above cover the tested release, not every published version. On
-Windows they cover the full plugin session; WSL is not a separate CI target.
+Current native CI covers selected core/MCP checks, wheel installation, CLI execution, and
+MCP stdio paths; WSL is not a separate CI target. Full Windows plugin sessions were exercised
+in the historical 0.14.0 release-candidate campaign described above.
 
 **Version requirement:** releases before 0.12.0 can stall a native Windows write: a Git
 child inherits the MCP stdin pipe and holds the write until the request times out (see

sidegraph-0.16.0/docs/guides/health-check.md

@@ -0,0 +1,66 @@
+# Check a Sidegraph installation
+
+Use `/sidegraph:health-check` to collect one read-only report for the current repository.
+It covers plugin wiring, runtime versions, Graphify, store integrity, anchor advisories, and
+inventory and usage. `UNKNOWN` means the evidence could not be established; it remains a
+warning and never becomes a clean result.
+
+## Runtime requirement
+
+The skill runs its local `scripts/collect.py` helper with `-B` under an already identified
+Python interpreter. In a development checkout, the supported paths are:
+
+```bash
+"<project>/.venv/bin/python" -B "<skill-directory>/scripts/collect.py" --project "<launch-directory>" --host claude
+```
+
+For Codex, pass `--host codex`; use `unknown` when the attached host is not known. On Windows,
+use the existing `<project>/.venv/Scripts/python.exe`. Installed use requires a
+known interpreter from attached host launch metadata or metadata for an identified Sidegraph
+environment. The collector does not guess a Python on `PATH`, run an unknown Sidegraph
+executable, or use `uv`/`uvx` as its launcher. If no suitable interpreter is known, the skill
+shows all six sections as limited, includes safe static evidence already available, lists
+manual recommendations, and stops. The same fallback applies when the helper exits nonzero,
+prints error JSON, or cannot import required inspection helpers; show only the error class and
+do not echo exception text. Cached package files alone do not authorize provisioning.
+
+The skill resolves the Git root to select the interpreter, then passes the original launch
+directory as `--project` so Claude plugin-scope checks retain the launch context. The optional
+`--store`, `--graph`, and `--plugin-root` arguments are for
+paths already known to the host or user; the collector does not search unrelated profiles.
+
+## Evidence and limits
+
+The report separates the collector package, plugin manifest, optional PATH installation,
+Graphify-recorded engine version, and any already observed active MCP evidence. Static
+registration is not proof that a running server answered. The workflow never starts a server
+or calls retrieval tools to test connectivity.
+
+The collector fingerprints the canonical store, index and sidecars, settings, plugin
+manifests, graph inputs, and actual Git index around its process. This is a stable-source
+check, not an atomic snapshot; concurrent writes make preservation evidence unstable without
+identifying which process changed it. Host hooks surrounding tool invocation are outside the
+collector's preservation boundary.
+
+If the index is absent, canonical-only doctor curation still runs, and index-dependent
+findings and stats are marked skipped. If an existing index has WAL/SHM sidecars, an
+unrecognized header, an unreadable header, or a nonempty rollback journal, all doctor
+advisory and stats paths that could open it are skipped. A regular rollback-mode index allows
+the existing doctor and stats checks to run. Cold or stale index qualifications are retained.
+
+The six report sections distinguish contract violations from advisory findings and missing
+coverage. Inventory counts come from canonical readers. Pending age is unknown for malformed
+record identifiers. Usage reports summarize recorded activity only; delivery counts do not
+show usefulness, prevented errors, or saved time. Records on unmerged or remote-only branches
+are not exhaustively checked.
+
+## Manual follow-up
+
+Recommendations are prioritized and deduplicated, with a reason, explicit scope, argv, working
+directory, and environment for a manual command or skill to run after the report. Render argv
+with the attached shell's native quoting; paths are never embedded into shell snippets. The
+health check never executes recommendations. Ordinary doctor and stats reads
+outside this collector can create SQLite sidecars for a WAL database, so inspect such an
+index separately after the writing session. Ending a session does not guarantee a persistent
+journal-mode change. Do not recommend an upgrade from an unknown version or install the
+optional PATH CLI solely because it is absent.

sidegraph-0.16.0/docs/guides/using-0.16.md

@@ -0,0 +1,45 @@
+# Using Sidegraph 0.16
+
+Sidegraph 0.16.0 adds bounded full-domain listings, honest uncomputed stats, a read-only
+installation health report, lower repeated descriptor-lookup cost, immediate refusal of hook
+SQLite lock contention, and clearer reporting of retained hot files during compaction. See the
+[changelog](../../CHANGELOG.md#0160--2026-10-20) for details.
+
+## Update
+
+For a CLI installed from the public repository's `main`, run:
+
+```bash
+uv tool upgrade sidegraph
+```
+
+For a PyPI version pin, install or upgrade to the exact release:
+
+```bash
+uv tool install --upgrade sidegraph==0.16.0
+```
+
+For host plugins, update the marketplace package and installed plugin using the
+[host installation instructions](../getting-started/installation.md), then start a new session
+so the MCP server and hooks use the released version. Public plugin manifests intentionally
+follow `main`; an explicit release-candidate pin stays pinned until you change it.
+
+## Stores and changed responses
+
+Existing stores from 0.15 remain compatible. This release adds no canonical store format
+migration.
+
+`list_domains` now returns a provisional JSON text envelope with `matched`, `returned`, `omitted`,
+`domains`, and `hint`, instead of a bare list. Read rows from `domains`; use the counts and hint
+to see whether the response was bounded and how to narrow it.
+
+Run `/sidegraph:health-check` for a read-only report about plugin wiring, runtime versions,
+Graphify, store integrity, anchor advisories, and recorded inventory and usage. Missing evidence
+stays `UNKNOWN`; an unsafe existing SQLite index causes checks that might open it to be skipped.
+
+## Limits
+
+Retrieval can still include off-task records, and this release does not measure whether delivered
+memory helped or saved time. It adds no task-query ranking or full-pool recall claim, and it does
+not change active-store compaction behavior. Health-report usage counts describe recorded
+activity, not usefulness.

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/reference/cli.md

@@ -1091,30 +1091,45 @@ before removing the now-redundant hot files leaves those as harmless leftover du
 run detects and removes them without writing a second, duplicate segment — counted separately
 in the output as "leftover hot file(s)".
 
-**A hot file that differs from its archived copy.** Compact keeps a hot file whose content
-differs from what it just archived, for example one holding a key the archive line lacks
-(written by a newer Sidegraph), and prints a `DIFFERENT content` warning on stderr. The record
-is still counted in `compacted N record(s)`, because it is in the new segment; its hot file is
-not removed. The warning repeats on every later compact and store open, and `sidegraph-verify`
-reports `duplicate-ulid` for the pair until a Sidegraph version that knows the key compacts it,
-or you restore the hot file and remove the segment by hand.
+**A hot file that differs from its archived copy.** Compact keeps both copies and prints a
+`DIFFERENT content` warning on stderr. When ignoring hot-only fields makes the shared content
+match, the warning says those extra fields are not represented in the archive and that a newer
+Sidegraph may have written them; that is an observed shape, not proof of which version wrote it.
+If shared values or structures differ, the warning says to compare both copies. The record is
+still counted in `compacted N record(s)`, because it is in the new segment; its hot file is not
+removed. Output also reports `kept K hot file(s): their content is not fully represented in the
+archive`, including on later compact runs that have no new records to archive. `sidegraph-verify`
+continues to report `duplicate-ulid` while both copies remain. Upgrading alone is not promised to
+reconcile an existing immutable archive entry. Back up the store, run `sidegraph-verify --db
+<store-dir>`, compare both copies against known-good history, and retain both until you establish
+an information-preserving reconciliation. For a fresh candidate in `--dry-run`, the warning
+compares the hot file with the prospective archive payload; no second copy has been published yet.
 
 **`--dry-run` output:** one line per candidate — `<ulid>  <kind>  <status>  <title>` — or a bare
 `nothing to compact` if there is nothing eligible at all (no candidates, nothing age-filtered
-out, no leftovers). Otherwise: `would compact N record(s) (X decisions, Y domains); Z skipped
-(not terminal enough)`; if `--older-than` excluded any domains outright (no terminal timestamp
-to check), an additional line reports `M domain(s) excluded: terminal age unknown`; if a prior
-interrupted run left redundant hot files behind, an additional line reports `would also remove
-K leftover hot file(s) already durably archived by a prior, interrupted compact run`.
+out, no leftovers, and no mismatched hot files). Otherwise: `would compact N record(s) (X
+decisions, Y domains); Z skipped (not terminal enough)`; if `--older-than` excluded any domains
+outright (no terminal timestamp to check), an additional line reports `M domain(s) excluded:
+terminal age unknown`; if a prior interrupted run left redundant hot files behind, an additional
+line reports `would also remove K leftover hot file(s) already durably archived by a prior,
+interrupted compact run`; and mismatches add `would keep K hot file(s): their content is not fully
+represented in the archive`. Dry-run compares fresh candidates as well as archived leftovers and
+writes no canonical file, archive segment or digest. `--older-than` filters fresh candidates;
+already archived leftovers remain eligible for cleanup or retention regardless of their current
+hot status or age. Opening the store may still initialize or
+migrate it, or rebuild `index.db`.
 
 **Real-run output:** when there was nothing to do at all, a single line —
 `nothing to compact` (bare), or `nothing to compact; Z skipped (not terminal enough)` and/or
-`; M domain(s) excluded: terminal age unknown` appended when either applies. Otherwise:
+`; M domain(s) excluded: terminal age unknown` appended when either applies. A positive kept
+count bypasses that no-op line. Otherwise:
 `compacted N record(s) into <segment_path> (X decisions, Y domains); Z skipped (not terminal
-enough)` — or `compacted 0 record(s); Z skipped (not terminal enough)` when only leftover
-cleanup happened and no new segment was written — followed by an `M domain(s) excluded:
-terminal age unknown` line and/or a `cleaned up K leftover hot file(s) from an interrupted
-prior compact run` line, each only when applicable.
+enough)` — or `compacted 0 record(s); Z skipped (not terminal enough)` when kept hot files or
+leftover cleanup remain and no new segment was written — followed by an `M domain(s) excluded:
+terminal age unknown` line, a `cleaned up K leftover hot file(s) from an interrupted prior
+compact run` line, and/or `kept K hot file(s): their content is not fully represented in the
+archive`, each only when applicable. `compacted N` counts new archive entries; `kept K` counts
+distinct hot files retained after comparison.
 
 **Exit code:** `0` on success, including a no-op run and every `--dry-run` that completes.
 Returns `1` before touching the store if `--older-than` is negative (`--older-than must be >= 0
@@ -1771,6 +1786,13 @@ Lines the report will not invent:
   no figure derived from the records: MEMORY and ANCHORS read `not shown: the index is behind
   the store files`, and REACH says which of its figures are not counted. The journal-derived
   lines are unaffected. `--json` carries `"index_stale": true` and `null` for those figures.
+- **Binding statuses not computed.** A fresh index can still have binding statuses waiting for
+  `sidegraph-sync` after reload. In that state, ANCHORS reads `not computed for current graph →
+  sidegraph-sync`; no anchor counts are shown, while MEMORY and REACH inventory remain available.
+  `--json` carries `"anchors": null`, `"binding_statuses_computed": false` and
+  `"index_stale": false`. When both conditions apply, canonical file staleness takes precedence
+  in the text; `binding_statuses_computed` is false without implying that volatile state alone
+  caused the omission.
 - **Budget and abandoned counts not recorded.** Once the report is past the floor above, when
   the window holds no render-journal record, the budget lines are replaced by the single line
   `budget and tried-and-abandoned counts: not recorded yet`. A zero there would read as a

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/reference/hooks.md

@@ -14,6 +14,11 @@ before it reads stdin or opens the store, so typing `--help` never runs a hook.
 without arguments. For wiring them into `.claude/settings.json`, see
 [`getting-started/claude-code-setup.md`](../getting-started/claude-code-setup.md).
 
+Hook-owned SQLite connections use a zero-second busy timeout, so a lock held by another
+Sidegraph writer is refused immediately at the database layer. This bounds SQLite lock waits;
+graph loading, filesystem work, transcript parsing and Git still contribute to whole-hook time.
+Other `Store`, hot-index and read-only-index callers retain their existing defaults.
+
 ## The command guard
 
 The wiring commands in the plugin manifests and the setup recipes end with a shell guard:
@@ -145,8 +150,9 @@ Behavior:
    60 seconds of the recorded one, before or after it, is a duplicate (the hook registered
    twice on one host, for example the plugin and a hand-written project hook), and it prints
    `{}` and returns before anything below runs. The check is a read that takes no write lock,
-   so a duplicate does not wait behind another process's write transaction. A start that is not a duplicate decides again and stamps the ledger in one write
-   transaction, so two copies of the hook firing together for one session inject the map once.
+   so a readable, already-stamped duplicate exits immediately. A start that is not a duplicate
+   decides again and stamps the ledger in one write transaction. Stamping remains best-effort:
+   if overlapping copies both encounter a busy write, both may emit the standing map.
    If the store cannot be opened, the hook does not print `{}` (see
    [A store that cannot open](#a-store-that-cannot-open)): memory is off for the session and the
    person is told. Only a lock another process holds keeps the silent `{}`.
@@ -483,7 +489,7 @@ lines only.
   host (different session ids, so the duplicate guard in step 1 does not apply) do not both
   send it. If the write itself fails, the notice is sent anyway: a duplicate is better than
   silence. When the failure is a lock another process holds, the hook stops writing for that
-  start (every further write would wait out the same busy timeout) and sends the remaining due
+  start (further writes are refused promptly too) and sends the remaining due
   notices unclaimed.
 - A check that ran and found nothing deletes its row, so a problem that returns after a fix is
   reported at once. Only a row that exists is deleted, so a start with nothing recorded makes no
@@ -783,8 +789,9 @@ repairs it, the hook keeps printing `{}`. `Store` repairs some of these and refu
   re-checks the record files before each call, but it keeps the connection it opened, so a deleted
   `index.db` stays gone for it until it restarts.
 
-A write that cannot get the index's write lock within 1 s (a rebuild is running) is dropped, and
-the hook then makes no further write in that run, so a call waits at most about 1 s.
+Hook-owned writes refuse the index lock immediately. A refused hot write is dropped, and the
+hook makes no further hot write in that run. SQLite contention does not set a whole-hook latency
+target; unrelated startup, graph and filesystem work can still take time.
 
 Two consequences are visible:
 
@@ -1077,8 +1084,8 @@ spawn), and one `retrieval_shows` bump each. Nothing is journaled without a sess
 64 KB for each text document the brief names, and one records query for each file the brief names
 that has anchored records, stopping at the sixth file that has any (each shown file costs at least
 one line), then one write transaction for the journal rows. This path used to be read-only: while
-another process holds the write lock, that write can wait out the one-second busy timeout before
-the spawn proceeds, and a failed write is swallowed (the brief is still delivered). It loads
+another process holds the write lock, the optional journal write now refuses immediately, and a
+failed write is swallowed (the brief is still delivered). It loads
 nothing beyond the standard library, like the rest of this hook.
 
 **Not tested.**

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/reference/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP tools reference
 
-Twenty-four tools, all defined in [`src/sidegraph/server.py`](../../src/sidegraph/server.py) and
+Twenty-five tools, all defined in [`src/sidegraph/server.py`](../../src/sidegraph/server.py) and
 exposed by the `sidegraph-mcp` stdio server (`FastMCP("sidegraph")`). The server holds one
 process-wide `Store` (path resolved via `$SIDEGRAPH_DIR`, same precedence the CLI and hooks
 use — see [`configuration.md`](configuration.md#store-path-resolution)) and a best-effort
@@ -19,24 +19,26 @@ server without host identity: the session id stays null and retrievals are journ
 
 ## Transport and protocol compatibility
 
-`sidegraph-mcp` is a local **stdio** server started by an MCP client. Standard input and
-standard output carry protocol messages; diagnostics go to standard error. The console
-entry point does not provide an HTTP listener or an HTTP authorization configuration.
+`sidegraph-mcp` defaults to a local **stdio** server started by an MCP client. Standard input
+and standard output carry protocol messages; diagnostics go to standard error. FastMCP
+transport settings can select HTTP, but Sidegraph supplies no separate HTTP authorization
+configuration.
 Configure the working directory and `SIDEGRAPH_DIR` for the repository the server should
 use; see [configuration](configuration.md#path-resolution-semantics).
 
 Git commands for provenance, initiative, ratification identity and graph checks receive
 EOF on standard input, keeping subprocesses separate from the MCP protocol stream.
 
-The development lockfile selects FastMCP 3.4.2 and MCP Python SDK 1.28.1. Supported package
-dependencies are `fastmcp>=3.4.2,<4` and `mcp>=1.24,<2`. The locked stack
+The development lockfile selects FastMCP 3.4.2 and MCP Python SDK 1.30.0. Supported package
+dependencies are `fastmcp>=3.4.2,<4` and `mcp>=1.30,<2`. The locked stack
 uses the `initialize` / `notifications/initialized` lifecycle and negotiates protocol
 versions through **2025-11-25**. The server reports Sidegraph's package version in
 `serverInfo.version`; that is separate from the negotiated protocol version.
 
 The [2026-07-28 MCP specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning)
 also describes a newer discovery lifecycle. The locked stack does not implement
-`server/discover`: a client must support the legacy initialization flow to use this
+`server/discover`; the installed MCP 1.30.0 server returns JSON-RPC `-32602` (`Invalid request
+parameters`) for that request. A client must support the legacy initialization flow to use this
 release. A request for a newer version during `initialize` can receive `2025-11-25`;
 the client must check that it supports the returned version.
 
@@ -59,15 +61,16 @@ counting or rendering those as separate answers.
 **Every listing tool is bounded.** The host replaces an answer over its limit with a notice
 (Claude Code: a warning above 10,000 tokens, an "exceeds maximum allowed tokens" notice above
 25,000 tokens by default, and a result saved to a file above 50,000 characters). So
-`retrieve_decisions`, `list_facts`, `get_entity_history`, `drill_down`, `list_domain_candidates`
-and `list_proposed` take `budget_chars` (default 24,000, maximum 40,000), the first four also
-`limit` (default 25, maximum 100; `list_domain_candidates` keeps its own `limit`), and each
-says what it left out and how to narrow. `get_task_context`, `query_structure`,
+`retrieve_decisions`, `list_facts`, `get_entity_history`, `drill_down`, `list_domain_candidates`,
+`list_proposed` and `list_domains` are bounded and say what they left out and how to narrow.
+All seven take `budget_chars` (default 24,000, maximum 40,000). `retrieve_decisions`,
+`list_facts`, `get_entity_history`, `drill_down` and `list_domains` take `limit` (default 25,
+maximum 100); `list_domain_candidates` keeps its own `limit`. `get_task_context`, `query_structure`,
 `query_decisions` and `list_proposed` never return more than 40,000 characters: a cut names
 the sections it removed in a closing note, and the advice at the end of the answer (how the
 seeds were read, what is not in the graph, the supersede hint, the drift legend) is kept.
-`list_domains`, `verify_store`, `sync_anchors` and `find_entity` are sized by the number of
-domains, findings or name candidates, not by accumulated memory, and stay unbounded. In Codex
+`verify_store`, `sync_anchors` and `find_entity` are sized by the number of findings or name
+candidates, not by accumulated memory, and stay unbounded. In Codex
 the host-side knob is `mcp_servers.<id>.tools.<tool>.output_token_limit` (its default is not
 documented).
 
@@ -1198,21 +1201,37 @@ key instead of erroring.
 ## `list_domains`
 
 ```python
-list_domains(status: str | None = None) -> list[dict]
+list_domains(
+    status: str | None = None,
+    query: str | None = None,
+    ids: list[str] | None = None,
+    limit: int = 25,
+    budget_chars: int = 24000,
+) -> ToolResult
 ```
 
-The full-listing counterpart to `list_proposed` (proposed-only) and `list_domain_candidates`
-(unclaimed-only) — the tool that actually answers "show me all domains". `status`, when given,
-filters to one of `"proposed"`/`"accepted"`/`"dropped"`/`"superseded"`; omitted (the default)
-returns every domain regardless of status. Read-only — writes nothing, ever; safe to call
-repeatedly.
-
-**Returns:** a list sorted by `slug`, one dict per domain: `{"id": str, "slug": str, "title":
-str, "summary": str, "status": str, "member_count": int, "path_prefixes": list[str],
-"seed_anchor_count": int, "parent_slug": str | None, "child_slugs": list[str]}`.
-`member_count` is `len(domain.communities)`: the number of communities whose every node
-is in the domain (0 until `ratify`/`sidegraph-sync` resolves a freshly proposed domain). `parent_slug`/`child_slugs` reflect the FULL domain set regardless of the
-`status` filter, so a filtered call still reports accurate lineage.
+The bounded, full-listing counterpart to `list_proposed` (proposed-only) and
+`list_domain_candidates` (unclaimed-only). `status`, when given, filters to one of
+`"proposed"`/`"accepted"`/`"dropped"`/`"superseded"`; omitted returns every status.
+`ids` matches exact domain ids (`Domain.domain_id`, the row's `id`, never its slug).
+`query` is case-insensitive whitespace-separated AND terms searched across slug, title and
+summary joined with newlines. Filters combine with AND; blank query and blank-only ids are
+ignored. `limit` is clamped to 1..100 and `budget_chars` to 4,000..40,000. Read-only — writes
+nothing, ever; safe to call repeatedly.
+
+**Returns:** one text block containing compact JSON: `{"matched": int, "returned": int,
+"omitted": int, "domains": [...], "hint": str | null}`. Counts are after filtering and
+before bounds; no matches means all three counts are zero. `domains` is the largest fitting
+initial prefix of complete rows, sorted by slug. Each row retains the existing fields:
+`{"id", "slug", "title", "summary", "status", "member_count", "path_prefixes",
+"seed_anchor_count", "parent_slug", "child_slugs"}`. `member_count` remains
+`len(domain.communities)`. Parent/child lineage comes from the full store even when filters
+exclude relatives. When the character budget omits rows, `hint` identifies the effective bound,
+suggests filters, and gives a bounded relative local-file fallback for the next omitted domain.
+When `limit` cuts the list, the hint suggests filters and raising `limit` only below 100. Empty
+stores say `No domains in the store.`; empty filtered matches name active filter keys without
+echoing their values. This is the provisional MCP return shape and sends no output schema or
+structured duplicate.
 
 ## `propose_decisions`
 

{sidegraph-0.15.0 → sidegraph-0.16.0}/docs/reference/store-format.md

@@ -595,17 +595,21 @@ collision — publishing retries under the next sequence number rather than over
 Identical content normally produces identical bytes and a matching hash suffix; the loader
 deduplicates overlapping ULIDs after branches merge.
 
-The loader reads hot files **and** every archive segment on every load, deduping by ULID (a
-record can legitimately appear in more than one segment — e.g. compaction run independently on
-two branches before they merged — but terminal records are immutable, so any duplicate is
-byte-identical and it doesn't matter which copy wins). If a hot file and an archived copy of
-the same id ever disagree, the hot file wins and a warning prints — that shape means
-corruption or a hand-edit, and the store never silently prefers the archive over live disk
-state. A key the hot file lacks, against `null` or an empty list or object in the archive, is
-not a disagreement (the file predates the field); a key only the hot file holds, at any depth
-and whatever its value, always is, and `sidegraph-compact` keeps such a file. The freshness digest (above) covers `archive/*.jsonl` too, so a segment absorbed from a
-teammate's branch via `git pull` is picked up on the next open exactly like any other new
-committed file.
+The loader reads hot files **and** every archive segment on every load, deduping by ULID (an
+archive record can legitimately appear in more than one segment — e.g. compaction run
+independently on two branches before they merged — and byte-identical archive copies are
+equivalent). If a hot file and an archived copy of the same id disagree, the hot file wins and
+a warning prints; the store never silently prefers the archive over live disk state. A key the
+hot file lacks, against `null` or an empty list or object in the archive, is not a disagreement
+(the file predates the field). A key only the hot file holds, at any depth and whatever its
+value, always is, and `sidegraph-compact` keeps that file. Warnings identify whether hot-only
+fields explain the mismatch or whether shared values/structures differ; neither cause alone
+proves which writer produced the copy. Both copies remain available, so `sidegraph-verify` may
+report `duplicate-ulid`. Back up the store, verify it, compare both copies against known-good
+history, and retain both until an information-preserving reconciliation is established. An
+upgrade alone does not promise to reconcile an existing immutable archive entry. The freshness
+digest (above) covers `archive/*.jsonl` too, so a segment absorbed from a teammate's branch via
+`git pull` is picked up on the next open exactly like any other new committed file.
 
 `sidegraph-compact --older-than N` additionally requires a record to have been terminal for at
 least `N` days; domains are always excluded from that filter (nothing on `Domain` records when

{sidegraph-0.15.0 → sidegraph-0.16.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "exports": "./index.js"
 }

{sidegraph-0.15.0 → sidegraph-0.16.0}/plugin/sidegraph/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sidegraph",
   "displayName": "Sidegraph",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Durable decision/lessons memory over your code graph — ADRs, gotchas, and constraints that survive refactors, retrieved mistakes-first.",
   "author": { "name": "SantyagoSeaman", "url": "https://github.com/SantyagoSeaman" },
   "homepage": "https://github.com/SantyagoSeaman/sidegraph",

{sidegraph-0.15.0 → sidegraph-0.16.0}/plugin/sidegraph/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Durable decision/lessons memory over your code graph — ADRs, gotchas, and constraints that survive refactors, retrieved mistakes-first.",
   "license": "Apache-2.0",
   "skills": "./skills/",