sidegraph 0.11.1__tar.gz → 0.13.0__tar.gz

sidegraph-0.13.0/.github/workflows/ci.yml

@@ -0,0 +1,339 @@
+# Project lint+type+test gate. `lint` runs the SAME .pre-commit-config.yaml a developer
+# runs locally, so there is one definition of lint rather than a CI copy that drifts.
+# Mostly distinct from the sidegraph-recipe workflows in docs/guides/ci-cd-maintenance.md
+# (recipes for USER repos consuming Sidegraph) — except `store-lint`, which is Recipe 2
+# self-applied to this repo's own dogfood store (2026-08-09 maintenance retrospective,
+# cadence lever): the store rides every PR, so its transition rules should gate every PR.
+#
+# Actions are pinned to commit SHAs (the tag comment records the version): a mutable tag
+# is a supply-chain hole, and this workflow ships to the public repo by snapshot.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:   # reused as the pre-publish gate by publish.yml (tag builds)
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes, so the checkout's git credentials should not
+      # persist into the runner's git config where a later step (or an uploaded artifact) could
+      # leak them.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0   # committed-history secret scan needs every reachable commit
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Cache pre-commit hooks
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run pre-commit checks
+        run: uv run pre-commit run --all-files
+
+      - name: Scan committed history for secrets
+        run: |
+          test "$(git rev-parse --is-shallow-repository)" = false
+          uv run pre-commit run gitleaks-history --hook-stage manual --all-files
+
+      - name: Exercise secret scanner integration
+        env:
+          SIDEGRAPH_SECRET_SCAN_INTEGRATION: "1"
+        run: |
+          uv run pytest tests/test_secret_scan_gate.py -q --junitxml="$RUNNER_TEMP/secret-scan.xml"
+          python3 - <<'PY'
+          import os
+          from pathlib import Path
+          from xml.etree import ElementTree
+
+          report = Path(os.environ["RUNNER_TEMP"]) / "secret-scan.xml"
+          suites = list(ElementTree.parse(report).getroot().iter("testsuite"))
+          assert sum(int(s.attrib["tests"]) for s in suites) > 0, "no scanner tests ran"
+          assert sum(int(s.attrib["skipped"]) for s in suites) == 0, "scanner tests skipped"
+          PY
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run tests
+        run: uv run pytest -q
+
+  sdk-compatibility:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [minimum, latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Validate supported SDK bounds against installed wheel
+        env:
+          SDK_PAIR: ${{ matrix.sdk }}
+        run: |
+          uv build
+          wheels=(dist/sidegraph-*.whl)
+          test "${#wheels[@]}" -eq 1
+          wheel="$(realpath "${wheels[0]}")"
+          probe="$(realpath tests/wheel_smoke.py)"
+          environment="$RUNNER_TEMP/sidegraph-sdk-env"
+          uv venv --python 3.13 "$environment"
+          interpreter="$environment/bin/python"
+          constraints=()
+          if [ "$SDK_PAIR" = minimum ]; then
+            constraints=(fastmcp==3.4.2 mcp==1.24.0)
+          fi
+          uv pip install --python "$interpreter" "$wheel" pytest "${constraints[@]}"
+          mkdir -p "$RUNNER_TEMP/sdk-check"
+          cp -R tests "$RUNNER_TEMP/sdk-check/tests"
+          cd "$RUNNER_TEMP/sdk-check"
+          "$interpreter" -I "$probe" --wheel "$wheel" --python "$interpreter"
+          "$interpreter" -I -m pytest -q tests/test_server_result_contract.py \
+            tests/test_server_argument_names.py tests/test_security_write_boundary.py \
+            tests/test_security_mcp_write_diagnostics.py tests/test_server_invocation_policy.py
+          "$interpreter" -I -m pytest -q tests/test_session_attribution.py \
+            -k "not t9 and not t14_every and not t14_the_manual and not console_script_is_the_host_entry"
+
+  windows-core:
+    runs-on: windows-2022
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      # Native core selection; Unix host/editor integrations remain covered on Linux.
+      - name: Record native environment
+        shell: pwsh
+        run: |
+          uv run python -c "import json,platform,importlib.metadata as m; print(json.dumps({'os':platform.system(),'python':platform.python_version(),'fastmcp':m.version('fastmcp'),'mcp':m.version('mcp')}))" > "$env:RUNNER_TEMP/windows-environment.json"
+          exit $LASTEXITCODE
+
+      - name: Test portable core and MCP contracts
+        shell: pwsh
+        run: |
+          $privateTests = @()
+          if (Test-Path "tools/desktop_e2e_probe.py") {
+            $privateTests = @("tests/test_desktop_e2e_probe.py", "tests/test_desktop_e2e_session.py")
+            # Later modules' tests join only when present; the snapshot excludes all of them.
+            foreach ($name in "appserver", "lifecycle", "preflight", "aggregate", "codex", "receipt") {
+              if (Test-Path "tests/test_desktop_e2e_$name.py") {
+                $privateTests += "tests/test_desktop_e2e_$name.py"
+              }
+            }
+          }
+          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_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 `
+            tests/test_repo_relative_paths_portable.py `
+            tests/test_command_windows.py `
+            tests/test_hook_payload_encoding.py `
+            tests/test_git_output_utf8.py `
+            $privateTests `
+            tests/test_installed_wheel_smoke.py
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Validate installed wheel over native stdio
+        id: windows-wheel
+        shell: pwsh
+        env:
+          WHEEL_PYTHON_VERSION: ${{ matrix.python-version }}
+        run: |
+          uv build
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          $wheels = @(Get-ChildItem dist/sidegraph-*.whl)
+          if ($wheels.Count -ne 1) { throw "Expected one wheel artifact" }
+          $wheel = $wheels[0].FullName
+          $probe = (Resolve-Path tests/wheel_smoke.py).Path
+          $environment = Join-Path $env:RUNNER_TEMP "sidegraph-wheel-env"
+          uv venv --python "$env:WHEEL_PYTHON_VERSION" "$environment"
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          $interpreter = Join-Path $environment "Scripts/python.exe"
+          uv pip install --python "$interpreter" "$wheel"
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          Set-Location "$env:RUNNER_TEMP"
+          & "$interpreter" -I "$probe" --wheel "$wheel" --python "$interpreter" |
+            Tee-Object -FilePath "$env:RUNNER_TEMP/windows-wheel.json"
+          exit $LASTEXITCODE
+
+      # Preserve the primary failure. Instrumentation uses new no-graph/no-repo scratch.
+      - name: Diagnose first installed-wheel write
+        if: ${{ !cancelled() && steps.windows-wheel.outcome == 'failure' }}
+        timeout-minutes: 2
+        shell: pwsh
+        run: |
+          $wheels = @(Get-ChildItem dist/sidegraph-*.whl)
+          if ($wheels.Count -ne 1) { throw "Expected one wheel artifact" }
+          $wheel = $wheels[0].FullName
+          $probe = (Resolve-Path tests/wheel_smoke.py).Path
+          $interpreter = Join-Path $env:RUNNER_TEMP "sidegraph-wheel-env/Scripts/python.exe"
+          Set-Location "$env:RUNNER_TEMP"
+          & "$interpreter" -I "$probe" --wheel "$wheel" --python "$interpreter" `
+            --diagnose-first-write
+          exit $LASTEXITCODE
+
+      - name: Sanitize test report
+        if: ${{ !cancelled() }}
+        shell: pwsh
+        run: |
+          @'
+          import os
+          from pathlib import Path
+          from xml.etree import ElementTree as ET
+          report = Path(os.environ['RUNNER_TEMP']) / 'windows-core.xml'
+          if report.exists():
+              tree = ET.parse(report)
+              for element in tree.getroot().iter():
+                  if element.tag in {'failure', 'error', 'skipped', 'system-out', 'system-err'}:
+                      element.attrib.clear()
+                      element.text = 'Details omitted; see the CI step output.'
+                  element.attrib.pop('file', None)
+                  element.attrib.pop('hostname', None)
+              tree.write(report, encoding='utf-8', xml_declaration=True)
+          '@ | uv run python -
+          exit $LASTEXITCODE
+
+      - name: Upload bounded Windows evidence
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: windows-core-${{ matrix.python-version }}
+          path: |
+            ${{ runner.temp }}/windows-core.xml
+            ${{ runner.temp }}/windows-environment.json
+            ${{ runner.temp }}/windows-wheel.json
+          if-no-files-found: warn
+          retention-days: 7
+
+  # Recipe 2 (docs/guides/ci-cd-maintenance.md) on our own store: catch a hand-edited or
+  # history-rewritten record no MCP tool would produce. Diffs against the PR's merge base
+  # (never a moving branch name — see the recipe for why). Skips cleanly when the checkout
+  # carries no store: the public snapshot ships .sidegraph only on the demo branch, and
+  # this workflow ships to the public repo.
+  store-lint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0   # full history — merge-base needs it
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: sidegraph-verify --against merge-base
+        run: |
+          if [ ! -d .sidegraph ]; then
+            echo "no .sidegraph in this checkout — store lint not applicable"
+            exit 0
+          fi
+          uv sync --locked
+          base="$(git merge-base "origin/$GITHUB_BASE_REF" HEAD)"
+          uv run sidegraph-verify --against "$base" --json
+
+  # Recipe 1 self-applied: rebuild the graph from scratch and fail on attention findings
+  # (stale decisions, empty/overbroad domains, slug conflicts, refresh failures). A
+  # cache-less rebuild was verified label-identical to the local cached graph and the
+  # check green on it (2026-08-09 retrospective, cadence lever) — so a red here is a real
+  # finding, not CI-environment noise. Lone orphaned/ambiguous entities do NOT fail the
+  # check: multi-anchor tolerates them by design. The engine is version-pinned (engine-
+  # seam invariant); the sync writes only to the ephemeral checkout's .sidegraph/.
+  anchor-health:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # zizmor artipacked: this job never pushes; do not persist git credentials past checkout.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Rebuild graph and run sidegraph-sync --check
+        run: |
+          if [ ! -d .sidegraph ]; then
+            echo "no .sidegraph in this checkout — anchor health not applicable"
+            exit 0
+          fi
+          uvx --from graphifyy==0.9.6 graphify update .
+          uv sync --locked
+          uv run sidegraph-sync --json --check

{sidegraph-0.11.1 → sidegraph-0.13.0}/AGENTS.md

@@ -37,7 +37,8 @@ Python 3.13+; `uv`:
 - `uv run pre-commit run --all-files`: shared lint/format/type/secret-scanning gate (also
   runs `gitleaks`, `detect-private-key`, `zizmor`, `actionlint`, `check-toml`, and a
   `uv.lock`-in-sync check).
-- `uv run sidegraph-mcp`: stdio server; `uv build`: distributions.
+- `uv run sidegraph-mcp`: stdio server; `uv build`: distributions. `python -m sidegraph.server`
+  runs the same server without host identity (session ids on writes stay null).
 
 Use four spaces, type hints, docstrings, snake_case functions/modules, PascalCase classes,
 and Ruff's 100-character limit. End text files with a newline.

{sidegraph-0.11.1 → sidegraph-0.13.0}/CHANGELOG.md

@@ -7,6 +7,181 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-10-14
+
+### Fixed
+
+- On Windows, hooks misread the payload the host sends when a path in it has a non-ASCII
+  character (an accented or Cyrillic user name or project folder). The Stop capture reminder
+  never fired, PreToolUse delivered no records, and for some names SessionStart and
+  SubagentStart printed nothing.
+- On Windows, a non-ASCII git user name, branch name or repository path was read back garbled:
+  a ratified record could carry a garbled name in its provenance, and `sidegraph-verify
+  --against` failed or reported false changes for records containing non-ASCII text.
+- A change to a file whose name has non-ASCII characters, spaces or quotes was missed by the
+  drift check and the commit-trailer candidates, because git escaped the name.
+- On Windows, a Codex hook started from a subdirectory of a repository whose path has non-ASCII
+  characters now runs from the repository root.
+- A default Git for Windows install no longer breaks the MCP server. Its installer puts only
+  `Git\cmd` on PATH, which has no `sh`, so the server, which started with `sh`, did not start.
+  The Codex hooks have a Windows command for the same reason (see Changed).
+- The project's ratify policy now applies under Codex. `sidegraph-init` commits it to
+  `.claude/settings.json`, which Codex does not read, so under Codex every agent proposal
+  waited for review whatever the team chose. The plugin's MCP server now reads the committed
+  value when its environment sets none; an explicit `SIDEGRAPH_RATIFY_POLICY` still wins.
+
+### Changed
+
+- The plugins launch without `sh` on PATH. Both MCP launchers start `uvx` (`uv` in the
+  development manifest) directly, and `sidegraph-mcp --repo-root` anchors the server to the
+  project: `CLAUDE_PROJECT_DIR`, else the git top-level, else the working directory. The Codex
+  hooks gain a PowerShell `commandWindows` that Windows PowerShell 5.1 parses. On native Windows
+  you need no PATH change and no PowerShell 7; Git for Windows at its default options is
+  enough. The Codex hooks need a Codex release that supports `commandWindows` (verified with
+  0.162.1). The Windows hook definition changes, so approve the changed hooks once in `/hooks`
+  on Windows; other platforms are unaffected.
+- The optional terminal CLI now installs from the same place as the plugin, the public
+  repository's `main` branch: `uv tool install git+https://github.com/SantyagoSeaman/sidegraph.git@main`,
+  updated after each release with `uv tool upgrade sidegraph`. The docs no longer send you to
+  PyPI for it; PyPI still carries every release for pinning an exact version. The `path-skew`
+  SessionStart line now offers `uv tool install --reinstall git+https://github.com/SantyagoSeaman/sidegraph.git@main`,
+  which moves an older install from PyPI, pinned or not, to the latest release.
+- README: the Quickstart is one numbered sequence with the plugin commands inline, a teammate
+  path, and the rarer options below it; "How it works" is a numbered list instead of a diagram.
+
+## [0.12.0] — 2026-10-12
+
+### Fixed
+
+- The Codex plugin's `SessionStart` hook now starts on native Windows. Its command used POSIX
+  syntax (`VAR=value command`, `$(...)`) that the PowerShell Codex runs hooks in cannot parse, so
+  Windows sessions showed "the SessionStart hook could not start" although the entry point itself
+  worked when run directly. It is now wrapped in `sh -c`, like the `Stop` and `SubagentStart`
+  hooks, and keeps the same message if the launch fails. Codex records trust per hook definition,
+  so approve the changed `SessionStart` hook once in `/hooks`. On Windows the Codex hooks need
+  PowerShell 7: Codex runs hooks in PowerShell, and Windows PowerShell 5.1 cannot run them.
+- On native Windows, `sidegraph-import` now imports the documents a profile covers: their
+  repo-relative paths were built with backslashes, so every in-repo document was counted as
+  outside the profile and nothing was imported. Record keys, anchor lookups and `provenance.ref`
+  now use the POSIX path Graphify's `source_file` carries, so a later re-import on another
+  platform does not duplicate records going forward, and a symlink that resolves outside the
+  repository is refused there as on other platforms. A document on another drive than the
+  repository no longer crashes the import. A store that already holds backslash-keyed records
+  from an earlier Windows `--any-doc` import gets a second, POSIX-keyed record for the same
+  document on re-import; supersede the old ones.
+- On native Windows, records are now delivered before a Read, Edit, Write or Grep, and before a
+  Bash `cat`, `sed`, `grep` or `rg`, and a subagent brief's files find their records. These paths
+  were built with backslashes (`src\sample.py`) and never matched the POSIX paths anchors use.
+  Touch events and the usage statistics now record POSIX paths, and `query_decisions(files=…)`
+  without a graph finds the file's records. A root-level file whose name starts with `..` is no
+  longer mistaken for a path outside the repository. Hooks now key a Windows session by its
+  transcript file name, as on other platforms, instead of the whole `C:\…` path, so hook showings,
+  touch events and capture state join the session the MCP server attributes calls to.
+- The 40,000-character hard cap on `get_task_context` and `query_decisions` now keeps its advice
+  blocks (how the seeds were read, what is not in the graph, the supersede hint) when a record's
+  text contains a `## ` line or a seed path is absurdly long, and the closing note names what was
+  cut. Seed paths echoed in those blocks are clipped to their head and file name. The usage
+  statistics count only the records left in the text after the cap, nearest-anchored records
+  included, and a worktree seed written as an absolute or nested path is journaled as the
+  repo-relative path the answer shows. A record spanning several lines is cut whole, never
+  without its id line, and `degraded` and `chars_used` describe the delivered text too. The
+  bound-record count of the nearest-anchored block reads "at least N" for a path whose bound
+  records include some of the nearest records shown.
+- `drill_down` bounds the whole answer, not only the decisions: a domain summary, titles and member
+  lines too long for `budget_chars` (measured as serialized JSON, a slug included) are clipped with a
+  marker, and subdomains or members that do not fit are left out with `subdomains_omitted` /
+  `members_omitted` counts and a `hint`.
+- `sidegraph-doctor` no longer crashes on an `index.db` that has `anchor_bindings` but no `meta`
+  table: such an index counts as having its binding statuses computed, so the checks run. Only an
+  unreadable index is reported as skipped.
+- `sidegraph-doctor` no longer reports zero `degraded-binding`/`orphaned-binding` findings while
+  binding statuses are not computed for the current graph (after an index reload and before the
+  next `sidegraph-sync`). It lists `binding-status` among the skipped checks, and the text
+  line for it and `orphaned-records` no longer blames a missing `index.db`.
+- `get_task_context` no longer calls a real file of a sibling linked worktree "not a
+  repo-relative path", guesses it to be a same-named graph file, or reads a nested worktree path
+  as the main checkout's file. It names the worktree and branch; a well-formed path that is a file in no checkout is "not a
+  file in this checkout", and only malformed paths keep the old sentence. A path with records
+  bound to a file the graph lacks and not shown elsewhere in the answer says so in the
+  nearest-anchored block, and
+  `retrieve_decisions(files=[...])` reads such a path exactly.
+- Attribute each MCP call to its own session instead of the last `SessionStart` of any host
+  in the repository. A write that omits `session_id` and a retrieval-journal row now carry the
+  calling host's session: `CLAUDE_CODE_SESSION_ID` for Claude Code (2.1.154 or later for exact
+  attribution, 2.1.163 or later to keep one id across `--resume`) and the request `threadId`
+  for Codex. A client that names its host but no session falls back to the one fresh stamp of
+  the same host family, else to nothing; a retrieval that cannot be attributed is journaled as
+  `unattributed` and `sidegraph-stats` reports those calls instead of counting their sessions
+  as silent. The `sidegraph-mcp` console script moves to `sidegraph.host.mcp_entry:main`
+  (the command name is unchanged; `python -m sidegraph.server` still starts the server, without
+  host identity). Hook commands set the new `SIDEGRAPH_HOST` variable. Hand-written
+  SessionStart wiring should add `SIDEGRAPH_HOST=claude` or `SIDEGRAPH_HOST=codex`.
+- Serialize Store state checks and publication behind a SQLite writer reservation,
+  including pending verdicts and server-side domain/fact preconditions. Busy admission
+  reports conservative inspect-before-retry guidance; file and index commits remain
+  separate operations.
+- Read graph/label JSON and Claude settings as UTF-8 independently of the default locale;
+  retry incomplete graph encodings and close temporary descriptors on setup failures.
+- Isolate noninteractive Git subprocess stdin from the MCP protocol pipe, resolving
+  native Windows first-write stalls in the installed-wheel stdio checks.
+- Set MCP `isError` for complete anchor-operation failures while retaining structured
+  payloads and partial-batch outcomes. Unknown tool names receive bounded discovery advice.
+
+### Changed
+
+- The Quickstart no longer installs the CLI for plugin users: its commands run through `uvx`,
+  as the plugin does. `uv tool install sidegraph` is documented as optional beside a plugin
+  and the usual setup without one, and its install now includes a mandatory update after every
+  release, `uv tool install sidegraph@latest`. The plugin's skills run every
+  `sidegraph-*` command at the session's version through `uvx` and never the copy on `PATH`.
+- The PreToolUse hook records what it hands over as showings: each record printed in a
+  file-read block (`inject`) or appended to a subagent's brief (`inject_brief`) is journaled
+  and bumps `retrieval_shows`. `sidegraph-stats` gains a `record showings delivered by hooks`
+  line (`activation.hook_showings` in `--json`), and `no recorded showing` and the doctor's
+  `never-surfaced` check count a record the hook printed as shown. Upgrade `sidegraph-stats`
+  together with the plugin: an older CLI reads the new journal rows as memory lookups.
+  The Agent-brief path, read-only until now, writes one transaction (up to the one-second busy
+  timeout under a held lock; a failed write never costs the brief).
+- Bound the output of five listing tools. `list_facts`, `get_entity_history`, `drill_down`,
+  `list_domain_candidates` and `list_proposed` now take `budget_chars` (default 24000,
+  maximum 40000) and say what was left out and how to narrow; `list_facts` gains `status`,
+  `files`, `query`, `ids` and `limit`, and `get_entity_history` gains `status` and `limit`.
+  Before, a store with a few hundred facts or a long-lived entity produced answers (up to
+  170,000 characters) that Claude Code replaced with an "exceeds maximum allowed tokens"
+  notice. **Return shapes change:** `list_facts` and `get_entity_history` return a JSON
+  object instead of a list; `drill_down` and `list_domain_candidates` add
+  `hint`/`truncated`-style fields (`omitted_ids`, `omitted_by_budget`); the first four are sent
+  once, as text, with no `structuredContent` copy. `list_domain_candidates` shows fewer
+  candidates by default (the budget cuts first; narrow with `paths`; `limit=0` still lifts the
+  count limit). `retrieve_decisions`'s maximum `budget_chars` falls from 60000 to 40000, below
+  Claude Code's 50,000-character limit, and `get_task_context`, `query_structure`,
+  `query_decisions` and `list_proposed` never return more than 40,000 characters (a cut says
+  so in a closing note and keeps the advice blocks).
+- Text-only MCP tools `get_task_context`, `query_structure`, `query_decisions`, and
+  `list_proposed` no longer advertise an output schema or duplicate text in
+  `structuredContent`. Machine-oriented dictionary results retain their schemas.
+- Bound supported dependency majors to FastMCP 3 (`>=3.4.2`) and MCP Python SDK 1 (`>=1.24`).
+
+### Added
+
+- A SessionStart advisory, `path-skew`, on macOS and Linux, when a `sidegraph-*` command on
+  `PATH` (outside the session's own environment) is a different version than the session, such
+  as a forgotten `uv tool install sidegraph`. It reads the install's dist-info and runs nothing.
+- Per-process MCP tool admission: burst 200, refill 100 calls/second, immediate refusal
+  before tool work; initialization, ping, and discovery remain available.
+- Native Windows x64 CI for Python 3.13/3.14, covering selected core/MCP contracts and
+  an exact installed-wheel CLI/stdio probe outside the checkout.
+
+### Documentation
+
+- Reorganize the README around setup, usage, limits, and contribution paths; remove
+  unsupported comparisons and clarify the runtime versus host data boundary.
+- Document tested platform coverage, the locked MCP protocol range, result error
+  handling, and recovery after a cancelled write. Align guides and reference pages
+  with the current release and stability policies.
+- Explain Windows plugin shell/PATH requirements, WSL setup, native MCP-only limits,
+  and the distinction between core/wheel CI and full agent-plugin validation.
+
 ## [0.11.1] — 2026-10-10
 
 ### Fixed

{sidegraph-0.11.1 → sidegraph-0.13.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.11.1) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.13.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
@@ -60,6 +60,8 @@ src/sidegraph/
 │   └── reader.py    #   GraphifyReader: reads graph.json (read-only input; no MCP)
 └── host/            # ── HOST SEAM ── Claude Code integration (SessionStart/Stop/PreToolUse/SubagentStart)
     ├── hooks.py     #   host-specific; portable core never reaches in here
+    ├── mcp_entry.py #   `sidegraph-mcp` entry: server + session-binding middleware
+    ├── session_identity.py  #   Claude/Codex session id from clientInfo, env, _meta
     └── subagent.py  #   SubagentStart: the memory brief for a starting subagent
 ```
 
@@ -103,6 +105,7 @@ uv run pytest -m "not slow"         # broader pre-push check: skips subprocess-h
 uv run pytest                      # full suite: once before a commit or PR (CI runs it again)
 uv run pre-commit run --all-files  # lint + format + types, exactly what CI runs
 uv run sidegraph-mcp               # run the decision MCP server (stdio)
+                                   # (`python -m sidegraph.server`: same server, no host identity)
 ```
 
 ## Working agreements

{sidegraph-0.11.1 → sidegraph-0.13.0}/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 
-Thanks for considering a contribution. The project is young and small — short, focused
-issues and patches land fastest.
+Contributions are welcome: bug reports, documentation improvements, tests, and code
+changes. For substantial changes, open an issue first to discuss the problem and scope.
 
 ## How this repository works
 
@@ -10,15 +10,15 @@ replaces its tree wholesale from the upstream working repo. That has one practic
 consequence for you:
 
 - **Issues are the best channel** — bug reports, feature requests and questions are read here.
-- **Pull requests are ported upstream, not merged here.** A merge commit on this repo would be
-  erased by the next release. Open the PR anyway if you have a patch: it will be reviewed here,
+- **Pull requests are ported upstream, not merged here.** A change applied only to this snapshot would not be
+  included in the next release tree. Open the PR anyway if you have a patch: it will be reviewed here,
   applied upstream with attribution, and it will arrive back in this repo with the next release.
 
 ## Development setup
 
 ```bash
 git clone https://github.com/SantyagoSeaman/sidegraph.git && cd sidegraph
-uv sync                        # runtime + dev dependencies (Python 3.13+)
+uv sync --locked               # runtime + dev dependencies (Python 3.13+)
 uv run pre-commit install      # once per clone — the lint gate runs before each commit
 uv run pytest tests/test_store.py -q -x --lf   # while editing: the touched file
 uv run pytest -m "not slow"   # broader pre-push check: skips subprocess-heavy tests, still takes minutes
@@ -26,7 +26,6 @@ uv run pytest -q               # full suite: run before a commit or PR, must be
 uv run pre-commit run --all-files   # lint + format + types + staged secrets
 ```
 
-
 The Gitleaks commit hook scans staged content even when all changed paths are excluded from
 formatting, including `.sidegraph/`. `--all-files` does not turn it into a committed scan.
 CI additionally scans all history reachable from HEAD with the same pinned scanner:
@@ -56,6 +55,18 @@ That gate also runs secret detection (`gitleaks`, `detect-private-key`), GitHub
 security/correctness checks (`zizmor`, `actionlint`), and `check-toml`/a `uv.lock`-in-sync
 check, alongside the usual formatting and type checks.
 
+## Preparing a pull request
+
+Describe the problem, the resulting behavior, and the checks you ran. Link the related
+issue when there is one, keep the patch focused, and update affected documentation.
+Use an area-prefixed imperative commit subject, for example `store: preserve history`,
+and sign off each commit as described below.
+
+CI runs the full suite on Linux/Python 3.13 and 3.14 and a selected native Windows
+core/MCP suite on both versions; see [platform coverage](docs/getting-started/installation.md#platform-coverage).
+If your change touches paths, permissions,
+subprocesses, or shell commands, describe any additional platform checks you performed.
+
 ## Ground rules
 
 - **Tests first for behavior changes.** Schema invariants and store write-path rules are