sidegraph 0.11.0__tar.gz → 0.12.0__tar.gz

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

@@ -0,0 +1,336 @@
+# 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 `
+            $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.0 → sidegraph-0.12.0}/.pre-commit-config.yaml

@@ -71,6 +71,16 @@ repos:
     rev: v8.30.1
     hooks:
       - id: gitleaks
+        # Filename exclusions protect immutable files from formatters, not this scanner:
+        # its upstream entry reads the staged Git index without filtered filenames.
+        always_run: true
+        stages: [pre-commit]
+      - id: gitleaks
+        alias: gitleaks-history
+        name: Detect hardcoded secrets in committed history
+        entry: gitleaks git --redact "--log-opts=--diff-merges=first-parent HEAD" --verbose
+        always_run: true
+        stages: [manual]
 
   # Finds GitHub Actions supply-chain/security issues (unpinned actions, script injection via
   # untrusted `${{ }}` template interpolation, excessive `permissions:`) in the workflows that

{sidegraph-0.11.0 → sidegraph-0.12.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.0 → sidegraph-0.12.0}/CHANGELOG.md

@@ -7,6 +7,225 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [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
+
+- **Bootstrap excludes special files and validates one bounded regular descriptor.** FIFO,
+  sockets and devices cannot become selected text sources, including through `--include`.
+  Available nonblocking/no-follow flags guard final-component replacement; the opened
+  descriptor is rechecked before strict incremental UTF-8 validation. Directory aliases
+  are rechecked against exclusions. Include retains its size override but observed growth
+  past opened size is excluded. Later planner/apply reads and ancestor races retain their
+  existing scope.
+
+- **Git verification preserves unusual filenames through binary NUL framing.** Verify and
+  doctor detect immutable edits and archive deletions at paths containing Unicode, TAB,
+  LF, CR, quotes, backslashes or surrounding whitespace. Malformed or unsupported diff
+  output is an operational error (exit `1`), never a partial clean report. Shared Git
+  callers keep their decoded-text behavior; only diff reads raw pathname bytes.
+
+- **Git verification resolves `--against` to one protected, frozen commit ID.** Verify and
+  doctor reject option-shaped, empty, NUL-containing, unavailable and non-commit baselines
+  operationally (exit `1`). Diff and every baseline record read use the same full SHA-1 or
+  SHA-256 ID, so a branch moving between those operations cannot hide an immutable edit.
+  There is no raw-ref fallback. Current working-tree reads retain
+  their existing concurrency limits.
+
+- **Malformed write diagnostics omit raw input and arbitrary failure causes.** Capture
+  errors use bounded schema fields/codes; logical MCP writes apply raw admission before
+  signature coercion and intercept exceptions before framework warning/error logging.
+  Unknown write arguments keep valid parameter help without echoing their names.
+  Unsupported registrations fail closed. Partial-write warnings and recovery guidance
+  remain truthful; domain/ratify causes are controlled. Read diagnostics and upstream
+  FastMCP DEBUG argument tracing retain their existing scope.
+
+- **Capture and direct writes reject oversized input before redaction or canonical writes.**
+  Limits are 256 KiB UTF-8 per string, 4 MiB admitted strings and 65,536 admitted nodes per
+  request, depth 32 and 4,096 nodes per draft, and 100 agent drafts including attached facts.
+  Combined decisions/facts share one budget; item violations reject the containing draft,
+  while request-wide violations fail before any write. Documents have an independent 8 MiB
+  per-file limit with whole-file skips, matching real/dry reports and no total-import cap.
+  Import tags and free-text options are bounded separately; input is never silently truncated.
+  Raw Python batches use lists/tuples; supported scalar, mapping and model fields are
+  inspected. Other opaque Python values (including sets, deques, generators and non-string
+  Enum objects) are rejected before Pydantic coercion, without consuming iterators. Numeric
+  enums can become strings rather than behave as numbers in Pydantic string fields; only
+  string-derived enums keep their measured base-string behavior.
+- **Redaction avoids repeated suffix searches in four known attack families.** Linear
+  assignment-key, URL-credential, JWT and private-key-block recognizers preserve matching
+  order/counts and the existing conservative quoted-value behavior. This does not claim
+  universal regex linearity or complete secret detection. See [security policy](SECURITY.md).
+
+- **Secret-bearing tags are redacted before document import stores their slugs.** Capture,
+  direct MCP writes and document import share tag normalization. Import reports tag
+  substitutions once per batch in real and dry runs, including duplicate raw tags.
+  Comma-separated MCP strings are cleaned before splitting; a secret-bearing string with
+  commas drops all its tags conservatively. List input keeps explicit boundaries.
+
+- **Quoted assignment redaction consumes multiline, triple-quoted and unterminated values.**
+  Escaped closers and glued tails stay covered. An unterminated value removes the
+  remaining input conservatively if no legal closer is found. An assignment span,
+  including URL/card expansion, that would swallow another assignment's key also consumes
+  the remaining input and following prose. A multiline quoted span splitting a URL
+  credential or checksum-valid grouped card number does so too. Bare values and
+  single-line glued tails extend through crossing URL/card matches while otherwise
+  preserving later prose. Prior tag entities and Git history remain: review old tags and
+  rotate exposed credentials. Unicode letters/digits after a single quote keep it inside
+  the value as an apostrophe; an unclosed value removes the remainder.
+
+- **Secret scanning covers store-only commits and committed CI history.** The pinned
+  Gitleaks hook runs even when changed files are excluded from formatting. A separate manual
+  `gitleaks-history` hook scans committed HEAD history, also run by CI with a full checkout.
+  Scanner integration tests exercise staged, committed, and removed synthetic secrets.
+
+- **Store verification checks the content of newly archived history.** A matching archive ID
+  alone no longer permits deletion of a committed hot decision or domain: every archive copy
+  must be compactable and a legal transition from the baseline, preserving raw immutable keys.
+  The snapshot check also reports nonterminal archive records. Legal supersede/drop followed
+  by compaction, older absent `null`/empty defaults, identical merge copies, and crash cleanup
+  still pass.
+
+### Changed
+
+- **Security documentation states the limits explicitly.** The privacy overview describes
+  best-effort redaction and writes outside the store. CLI documentation distinguishes
+  argument syntax errors from rejected Git baselines and recommends JSON output when
+  a terminal cannot encode a reported pathname.
+
 ## [0.11.0] — 2026-10-09
 
 ### Changed

{sidegraph-0.11.0 → sidegraph-0.12.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.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.12.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