scip-query 0.19.5 → 0.19.8

package/CHANGELOG.md

@@ -4,6 +4,90 @@ All notable changes to `scip-query` are documented here. This file starts at 0.1
 
 ## [Unreleased]
 
+## [0.19.8]
+
+### Complete agent evidence
+
+- Every descriptor-backed command now supports resumable output pages backed
+  by one immutable private snapshot. Pages report exact character totals,
+  bind cursors to the original invocation and content hash, and emit the exact
+  continuation command without rerunning a nondeterministic query.
+- Incomplete machine-readable and human pages identify themselves as
+  incomplete evidence. Generated project guidance requires agents to retrieve
+  every page before drawing a conclusion, changing evidence commands, or
+  reporting completion.
+
+### Diff-gate containment
+
+- CLI and Stop-hook gates now share a per-project single-flight lease, so
+  overlapping agents report the live owner instead of multiplying detector
+  work.
+- Gate evaluation runs in an owned child with a finite 60-second deadline, or
+  180 seconds with `--full`. Timeout terminates and reaps the child and fails
+  closed.
+- Historical finding reconciliation replays at most one comparison base per
+  foreground gate, runs only the detectors needed for that base, and leaves
+  deferred findings open with exact counts.
+
+### Security and operational hardening
+
+- Repository-controlled paths, tools, regular expressions, persisted records,
+  subprocesses, and output now cross explicit containment, size, time, and
+  trust boundaries. Terminal text is rendered inert, and destructive cache
+  operations require verified ownership.
+- Watchers and semantic mailboxes back off while idle, suppress redundant
+  refreshes, and preserve one canonical source identity across filesystem
+  aliases.
+- Production dependency audit and release preflight now reject high-severity
+  production advisories; the shipped production dependency tree is clean.
+
+## [0.19.6]
+
+### State and process resilience
+
+- Index publication now binds SQLite, SCIP, metadata, cursors, semantic
+  sessions, and retained generations to one immutable generation identity.
+  Shared-cache hydration and lease updates preserve current ownership across
+  concurrent writers and crash recovery.
+- Watch/reindex locks, refresh requests, TypeScript and Rust mailboxes,
+  evidence counters, suppressions, and outcome records now use explicit
+  operation identities, bounded queues, durable publication, conservative
+  owner reclamation, retry-safe transitions, and versioned compatibility
+  readers.
+- Child processes, workers, verified downloads, and Rust LSP framing have
+  finite time, byte, output, and shutdown budgets with typed timeout,
+  overflow, cancellation, and recovery outcomes.
+
+### Public and durable contracts
+
+- CLI JSON, project configuration, reindex metadata, committed suppression and
+  outcome files, and Rust durable-session messages have explicit current,
+  legacy, malformed, and future-version policies. Incomplete history and
+  partial metadata disclose their reduced capabilities instead of silently
+  acting current.
+- The published TypeScript declaration surface is checked across all 72
+  export paths and 871 declarations, including transitive declaration chunks
+  and a downstream consumer compile fixture.
+
+### Windows sidecar and npm release
+
+- The Windows sidecar carries a versioned provenance manifest binding its
+  immutable SCIP source commit, pinned Go toolchain, build contract, PE
+  machines, sizes, and SHA-256 hashes. Build, sidecar pack, and release all
+  reject stale, partial, swapped, or unverifiable binaries.
+- Existing npm versions are accepted only after local pack reports, registry
+  metadata, downloaded tarball hashes, package coordinates, and provenance
+  bytes agree. Only an explicit npm `E404` authorizes first publication;
+  ambiguity and concurrent different-content winners fail closed.
+- `npm run release:npm` owns the complete two-package workflow: test/build/API
+  preflight and both packs from one clean, unchanged Git revision precede
+  registry mutation, the sidecar publishes and verifies first, the main
+  package publishes and verifies last, and a durable schema-versioned local
+  state record binds the canonical HTTPS registry, source revision, and exact
+  artifacts so every partial state is observable and safely retryable. Direct
+  `npm publish` is guarded because it cannot provide that cross-package
+  recovery contract.
+
 ## [0.19.5]
 
 ### Agent evidence and workflows
@@ -201,7 +285,7 @@ All notable changes to `scip-query` are documented here. This file starts at 0.1
 
 ### Fixes (accuracy / false-positive)
 
-- **Three false-dead archetypes fixed.** Symbols consumed only via `import type` across a `tsconfig` path alias are no longer reported dead. pnpm-workspace cross-package consumers are now resolved via a new workspace-package resolver (this also fixed a real bug — `fanInBySymbolId.get(id) === 0` treated an *absent* symbol the same as a zero-reference one, suppressing semantic enrichment broadly, not just for the workspace case). Vue `<script setup>` composable consumers were verified already correct and gained a regression fixture. Where the remaining gap couldn't be closed this release (an ambiguous leaf name across an unresolved barrel re-export hop), the finding is now labeled `unconfirmed` instead of asserted `dead`.
+- **Three false-dead archetypes fixed.** Symbols consumed only via `import type` across a `tsconfig` path alias are no longer reported dead. pnpm-workspace cross-package consumers are now resolved via a new workspace-package resolver (this also fixed a real bug — `fanInBySymbolId.get(id) === 0` treated an _absent_ symbol the same as a zero-reference one, suppressing semantic enrichment broadly, not just for the workspace case). Vue `<script setup>` composable consumers were verified already correct and gained a regression fixture. Where the remaining gap couldn't be closed this release (an ambiguous leaf name across an unresolved barrel re-export hop), the finding is now labeled `unconfirmed` instead of asserted `dead`.
 - **`diff-gate` fails closed.** A git-diff-unavailable condition (diff too large for the exec buffer, a bad `--base`, or a git error) now exits nonzero having run zero checks, instead of silently passing.
 - **`doc-drift` epoch-0 timestamp bug fixed.** A doc whose only commit touched it as part of a >50-file bulk sweep now falls back to file mtime instead of being reported as "last changed at the Unix epoch."
 - **SANY XML export was silently dead code.** `-o <path>` on the SANY invocation meant "offline mode," not "output path" — the real-parser XML export path never actually ran. Fixed the invocation and rewrote the XML grammar parser against real `tla2tools` v1.8.0 output.

package/README.md

@@ -34,16 +34,22 @@ Two layers, wired by `scip-query setup`:
 
 **Invoked** — the agent routes work through skills, each carrying its own short command list so it never navigates the full CLI:
 
-| Phase     | Skill                                                            | Commands underneath (also usable directly)           |
-| --------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
-| Orient    | `scip-explore`                                                   | `system`, `trace`, `plan-context`, `call-graph`      |
-| Plan      | `scip-concrete-plan` (one change) · `scip-conductor` (a program) | `plan-context`, `change-surface`, `co-change`        |
-| Reuse     | (taught in-loop by the planning skills)                          | `similar`, `duplicate-bodies`, `recent-duplicates`   |
-| Implement | your agent + the post-change check for the change type           | `incomplete-migration`, `unused-params`, `co-change` |
-| Verify    | `scip-verify` (closeout) + the ambient diff gate                 | `diff-impact`, `diff-gate`, `health --baseline`      |
-| Clean up  | `scip-cleanup-audit` → `scip-cleanup-improve`                    | `cleanup-plan --verify`, `dead`, `twin-drift`        |
-
-Interrogation lenses go deeper on demand: `scip-integrity-audit` ("is this implementation real?"), `scip-twin-drift`, `scip-claim-audit`, `scip-probe-reachability`, and `scip-maintainability`. The full map with essential differences is in [Bundled skills](#bundled-skills); every command remains directly invocable for humans and scripts.
+| Phase    | Skill                                            | Commands underneath (also usable directly)      |
+| -------- | ------------------------------------------------ | ----------------------------------------------- |
+| Orient   | `scip-explore`                                   | `system`, `trace`, `affected`, `call-graph`     |
+| Plan     | `scip-plan`                                      | `plan-context`, `change-surface`, `co-change`   |
+| Diagnose | `scip-diagnose`                                  | `files`, `trace`, `call-graph`, `outline`       |
+| Audit    | `scip-audit`                                     | `cleanup-plan --verify`, `dead`, `twin-drift`   |
+| Improve  | `scip-improve`                                   | `incomplete-migration`, `recent-duplicates`     |
+| Verify   | `scip-verify` (closeout) + the ambient diff gate | `diff-impact`, `diff-gate`, `health --baseline` |
+| Set up   | `scip-setup`                                     | `doctor`, `setup`, `setup-hooks`, `setup-agent` |
+
+The consolidated skills retain the former specialist lenses as routed
+scenarios: API impact and formal/performance planning live in `scip-plan`;
+root cause and reachability probes live in `scip-diagnose`; integrity,
+maintainability, claim, framework, directory, and twin-drift review live in
+`scip-audit`; and cleanup or documentation repair lives in `scip-improve`.
+Every command remains directly invocable for humans and scripts.
 
 React and Vue repositories get additional framework-aware checks for repeated component/template structure, hook/composable behavior, and large-component or large-view pressure. These extend the same reuse and completion workflow; the core graph, history, planning, cleanup, and diff-gate commands are not frontend-specific.
 
@@ -69,6 +75,15 @@ For automation, use `scip-query setup --yes` to accept recommended defaults or
 scope is intentionally managed elsewhere. Or run without a global install:
 `npx scip-query@latest setup`.
 
+Every public `--json` response identifies its envelope schema, command result
+schema, and producing package version. See the
+[CLI JSON output contract](docs/CLI_JSON_OUTPUT.md) for the compatibility
+policy, decoder API, and machine-readable schema.
+
+Contributors changing exported TypeScript declarations should also follow the
+[public API evolution workflow](docs/API_EVOLUTION.md). Its committed manifest
+makes every package-subpath signature change explicit before release.
+
 ### If npm warns about install scripts
 
 On npm setups with script approval enabled (`allow-scripts`), the install prints warnings like
@@ -104,8 +119,9 @@ scip-query similar <closest-symbol>
 # After an extraction or migration: find sites that still contain old logic
 scip-query incomplete-migration
 
-# Before declaring the work complete: refresh the index and gate the diff
-scip-query reindex && scip-query diff-gate --json
+# Before declaring the work complete: gate the diff. Reindex only when status
+# reports stale and no live watcher or hook refresh is already responsible.
+scip-query diff-gate --json
 ```
 
 For a repository-wide cleanup pass:
@@ -243,7 +259,34 @@ scip-query suppress SQABC123DEF456 --check echo --reason "intentional compatibil
 
 This writes one file per suppression under `.scipquery/suppressions/` — commit it with your change. One-file-per-suppression means two branches suppressing different findings merge without conflict; the legacy `suppressions[]` array in `.scipquery.json` is still honored (read-only). Every suppression requires a reason plus either a stable finding id or a `check` (optionally narrowed by `file`). Check+file suppressions are allowed but warn because they waive every matching finding in that file. `diff-gate --json` reports both active and suppressed findings.
 
-**12. Measure whether the gate is earning its keep.** Every completed `diff-gate` run, including JSON and installed Stop-hook runs, writes each finding transition to its own committed `.scipquery/events/*.json` file. Independent branches add independent paths instead of editing one shared ledger file, so ordinary event writes do not create merge conflicts. Each event stores the immutable Git commit used as its comparison base. A finding is a verified fix when it disappears under that same comparison—either directly or after scip-query cleanly replays the original base against a newer committed `HEAD`. Merely committing the finding cannot clear it: if replay still finds it, the outcome stays open; if the worktree is dirty or Git cannot reproduce the base, verification waits. A suppressed finding was noise or an accepted trade-off:
+The first suppression for an identity is created exclusively. Repeating the
+same decision is idempotent, but a different reason, expiry, check, or file is
+a policy change and never silently overwrites the existing file. The command
+reports the existing SHA-256 revision:
+
+```text
+error: A different suppression decision already exists at ...
+Current revision: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef.
+```
+
+After reviewing the committed decision, replace exactly that revision:
+
+```bash
+scip-query suppress SQABC123DEF456 --check echo \
+  --reason "superseded by a narrower compatibility exception" \
+  --replace 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+If another writer changes the record first, the stale replacement is rejected
+and the newer bytes remain intact. New records declare their schema version,
+record kind, stable suppression identity, and writer version. Older
+unversioned and pre-discriminator v1 records remain readable and are upgraded
+only by an explicit replacement. If a malformed or future record cannot be
+used, `diff-gate` reports exact incomplete-coverage counts and keeps findings
+conservatively unsuppressed. The wire schemas and merge rules are documented
+in [`docs/COMMITTED_RECORD_COMPATIBILITY.md`](docs/COMMITTED_RECORD_COMPATIBILITY.md).
+
+**12. Measure whether the gate is earning its keep.** Every completed `diff-gate` run, including JSON and installed Stop-hook runs, writes each finding transition to its own committed `.scipquery/events/*.json` file. Independent branches add independent paths instead of editing one shared ledger file, so ordinary event writes do not create merge conflicts. Each event stores the immutable Git commit used as its comparison base. A finding is a verified fix when it disappears under that same comparison—either directly or after scip-query cleanly replays the original base against a newer committed `HEAD`. Merely committing the finding cannot clear it: if replay still finds it, the outcome stays open; if the worktree is dirty or Git cannot reproduce the base, verification waits. Historical reconciliation is deliberately incremental: one run replays at most one stored comparison base, reports the exact deferred base and finding counts, and leaves every deferred finding open for a later gate. A suppressed finding was noise or an accepted trade-off:
 
 ```bash
 scip-query effectiveness --since 30d
@@ -255,7 +298,28 @@ echo        14      10     2           1     0      1           83%        0.8
 new-dead    6       5      0           1     0      0           100%       0.3
 ```
 
-`precision` is verified fixed ÷ (verified fixed + suppressed). `moved` separates rename churn, while `unverified` is reserved for legacy or otherwise non-comparable resolutions that lack replay proof. Run diff-gate once to record the finding and again after the repair; a pre-commit rerun uses the same base directly, while a clean post-commit run automatically replays the stored base. Filter with `--check <name>`, window with `--since 30d|12w|<ISO date>`, and get machine-readable output with `--json`. Because the event files are committed, the numbers survive re-clones and aggregate across every machine and agent working the repo. Legacy `.scipquery/ledger/events.jsonl` records remain readable and are migrated to individual files on the next gate write. Historical cross-`HEAD` events without stored comparison evidence remain unverified rather than being reclassified speculatively. Standalone health/cleanup commands are not yet outcome-tracked because they do not all expose a complete-scan contract.
+`precision` is verified fixed ÷ (verified fixed + suppressed). `moved` separates rename churn, while `unverified` is reserved for legacy or otherwise non-comparable resolutions that lack replay proof. Run diff-gate once to record the finding and again after the repair; a pre-commit rerun uses the same base directly, while clean post-commit runs advance through stored bases incrementally. Filter with `--check <name>`, window with `--since 30d|12w|<ISO date>`, and get machine-readable output with `--json`. Because the event files are committed, the numbers survive re-clones and aggregate across every machine and agent working the repo. Current event files carry an additive v1 discriminator, stable semantic identity, and writer version; existing unversioned files remain readable. `effectiveness` reports accepted and omitted record counts when history is partial, and cross-HEAD verification defers fixes rather than trusting an incomplete lifecycle. Legacy `.scipquery/ledger/events.jsonl` records remain readable and are migrated to individual files on the next gate write only when every non-empty line is compatible; otherwise the source ledger is preserved. Historical cross-`HEAD` events without stored comparison evidence remain unverified rather than being reclassified speculatively. Standalone health/cleanup commands are not yet outcome-tracked because they do not all expose a complete-scan contract.
+
+`diff-gate` is also single-flight per project: a second CLI or Stop-hook gate
+returns the live owner's PID and start time instead of duplicating the same
+CPU-heavy work. The gate runs in an owned child process with a 60-second
+deadline, or 180 seconds with `--full`; timeout terminates and reaps that child
+and fails the gate explicitly. Operators may set
+`SCIP_QUERY_DIFF_GATE_TIMEOUT_MS` to a positive millisecond value, capped at
+10 minutes.
+
+The health report also keeps a worktree-local repeat counter in `evidence.db`.
+A logical observation is one completed detector evaluation named by an
+observation ID; unlike a process attempt, a retry of that evaluation reuses the
+same ID. SQLite serializes these observations before deriving their
+transitions. Two different IDs that report the same finding therefore add two
+to `timesShown`, while an exact retry with the same ID and evidence adds
+nothing. Reusing an ID for different evidence is rejected and reported. A
+writer-lock timeout skips the local counter update rather than delaying or
+changing the gate decision, and the next distinct run may try again. The
+dedupe records live as long as that rebuildable `evidence.db`; deleting the
+database resets both the counters and their retry memory. These local counters
+feed detector-precision hints, not the committed `effectiveness` totals above.
 
 Before any edit, `plan-context <target>` bundles the structural picture — definitions, references, call graph, blast radius — plus a HISTORY section: churn, fix-commit density, and the files that usually change together with the target ("editing this usually means editing these").
 
@@ -312,40 +376,35 @@ Heuristic detectors carry guardrails learned from real codebases: published `pac
 
 One-line "essential difference" per skill — read this table before the Routes table in `skills/scip-query/SKILL.md` if two names sound alike.
 
-| Skill                         | Essential difference                                                                   |
-| ----------------------------- | -------------------------------------------------------------------------------------- |
-| `scip-query`                  | Router: dispatches codebase work to the specialist skill below.                        |
-| `scip-explore`                | Understand before touching.                                                            |
-| `scip-concrete-plan`          | Specify ONE change so an executor can't guess.                                         |
-| `scip-conductor`              | Run a multi-phase program (delegate, verify handoffs, pre-registered benchmarks).      |
-| `scip-debug`                  | Root-cause a failure.                                                                  |
-| `scip-root-cause`             | Diagnose the design flaw behind a family of recurring bugs.                            |
-| `scip-triage-issue`           | Package a report into an actionable issue+fix plan.                                    |
-| `scip-verify`                 | Post-change closeout gate.                                                             |
-| `scip-cleanup-audit`          | Rank findings, no edits.                                                               |
-| `scip-cleanup-improve`        | Autonomously fix confirmed findings.                                                   |
-| `scip-maintainability`        | Is this well-organized (scattered concepts, accidental variation)?                     |
-| `scip-integrity-audit`        | Is this real (decorative checkers, faked implementations, dead fallback-hidden paths)? |
-| `scip-calibrate`              | Measure detector precision on a repo before trusting scores or gating anyone.          |
-| `scip-twin-drift`             | Same-name implementations that drifted apart.                                          |
-| `scip-claim-audit`            | Status words derived vs asserted.                                                      |
-| `scip-probe-reachability`     | Prove parser/AST branches actually fire.                                               |
-| `scip-api-impact`             | Blast radius before changing public surfaces.                                          |
-| `scip-directory-architecture` | Folder/ownership layout.                                                               |
-| `scip-doc-reconcile`          | Docs vs code drift.                                                                    |
-| `scip-diagram`                | Visual artifacts.                                                                      |
-| `scip-react-maintainability`  | Framework-specific reuse lens (React).                                                 |
-| `scip-vue-maintainability`    | Framework-specific reuse lens (Vue).                                                   |
-| `scip-language-playbook`      | Which commands per language.                                                           |
-| `scip-hyper-optimization`     | Performance campaigns without output changes.                                          |
-| `scip-tla-model-system`       | Formal models tied to code evidence.                                                   |
-| `scip-setup`                  | Adopt or repair scip-query in a repo.                                                  |
-| `_shared`                     | Reference loaded by other skills, not user-invoked.                                    |
-
-The confusable clusters, disambiguated: `scip-debug` (one failure, one minimal fix) vs `scip-root-cause` (a family of recurring bugs traced to a design flaw); `scip-concrete-plan` (one change) vs `scip-conductor` (a program of changes with delegation); `scip-cleanup-audit` (report only) vs `scip-cleanup-improve` (autonomous fixing loop); `scip-verify` (did this specific change land safely) vs `scip-integrity-audit` (does this code actually work at all) vs `scip-maintainability` (is this well organized) vs `scip-twin-drift` (one drifted same-name pair specifically); `scip-directory-architecture` (folder ownership) vs `scip-maintainability` (deeper structural compression). `skills/scip-query/SKILL.md`'s Tie-Breaks section has the full routing logic.
+| Skill           | Essential difference                                                           |
+| --------------- | ------------------------------------------------------------------------------ |
+| `scip-query`    | Router: select the smallest workflow that answers the request.                 |
+| `scip-explore`  | Understand or diagram existing code without changing it.                       |
+| `scip-plan`     | Prove the blast radius and specify one change or a multi-phase program.        |
+| `scip-diagnose` | Trace a failure, recurring design flaw, issue, or unreachable branch to cause. |
+| `scip-audit`    | Classify integrity, maintainability, drift, framework, and cleanup evidence.   |
+| `scip-improve`  | Act on confirmed audit or documentation findings and ratchet the result.       |
+| `scip-verify`   | Test and challenge a finished change before declaring it complete.             |
+| `scip-setup`    | Adopt or repair scip-query in a repository.                                    |
+| `_shared`       | Manual-only command/evidence reference loaded by another workflow when needed. |
+
+The important boundary is read-only versus mutating work: `scip-audit`
+classifies current evidence, while `scip-improve` changes confirmed findings.
+`scip-plan` is prospective evidence before implementation; `scip-verify`
+challenges a concrete finished diff. `scip-explore` explains working behavior;
+`scip-diagnose` starts from a failure or contradiction.
 
 Project setup writes reviewable checkout-local lifecycle hooks for Codex and Claude Code (`.codex/hooks.json` and `.claude/settings.local.json`). A checkout-local hook is an agent-tool preference whose defining trait is that it applies to one clone rather than expressing team policy. Setup adds both paths to that clone's `.git/info/exclude`, so they do not appear in commits, and refuses to rewrite either path if it is already tracked. `setup-hooks --shared` remains accepted only as a deprecated compatibility flag; it no longer writes `.claude/settings.json`. These hooks add scip-query context at session start, route prompts toward the right skill, and run an advisory Stop-hook wrapper around the diff gate only for that repository. The Stop hook sends feedback to the agent by default instead of blocking; set `SCIP_QUERY_STOP_HOOK_MODE=warn` for a warning-only hook response, or `SCIP_QUERY_STOP_HOOK_MODE=block` to enforce the gate. Set `SCIP_QUERY_SKIP_HOOK_INSTALL=1` or run `scip-query setup --no-hooks` to skip hook installation during setup, and run `scip-query setup-hooks --json` later to repair the current checkout's hooks.
 
+Setup/configuration writers are conflict-aware. They reread the latest file
+under a short token-owned lock, preserve unknown JSON fields and prose outside
+owned Markdown markers, and publish complete bytes durably. An unrelated
+intervening JSON edit is merged; a stale decision about the same project-config
+field, malformed latest JSON, malformed managed markers, or an edit that wins
+the final revision check produces an explicit conflict and leaves the latest
+file untouched. Reload the file and rerun the command after resolving that
+conflict. See [Configuration and setup write safety](docs/CONFIGURATION_WRITE_SAFETY.md).
+
 For a project, run `scip-query setup`. It enables demand-started automatic
 indexing unless the project already has an explicit `watch.enabled: false`,
 starts or reuses the project service, verifies its clean-idle deadline, and
@@ -353,7 +412,8 @@ reports Rust's final durable/worker semantic selection and lifecycle state.
 The status read is passive; the setup health audit may make a semantic request
 that wakes rust-analyzer, after which the helper exits on clean idle.
 It also installs/refreshes skills, configures project-local hooks unless
-skipped, checks indexer readiness, attempts configured indexer remediation,
+skipped, checks indexer readiness, performs explicitly approved pinned indexer
+remediation,
 refreshes the index, smoke-tests representative command families, writes
 `docs/scip-query/health-dossier.md` and `.json` when the optional health pass is
 selected, reports the health score and items needing attention, and seeds
@@ -361,10 +421,12 @@ AGENTS.md/CLAUDE.md guidance. Use
 the default terminal checklist to accept or decline the recommended automatic
 indexing action and other project-local changes (`--guided` reopens it
 explicitly). After setup,
-`scip-cleanup-audit` confirms raw signals and `scip-cleanup-improve` keeps
+`scip-audit` confirms raw signals and `scip-improve` keeps
 fixing the worst confirmed items until no safe confirmed cleanup remains. Use
 `scip-query setup --git-hook` when you also want a local pre-commit diff gate.
-CI setup is intentionally separate.
+Non-interactive setup and ordinary reindex report missing global tools without
+installing them; pass `--install-missing` only when that operation may install
+the reviewed immutable package versions. CI setup is intentionally separate.
 
 Setup classifies every change by where its facts belong:
 
@@ -386,7 +448,24 @@ scip-query tla trace-check specs/queue/Queue.tla --trace traces/run1.json   # ch
 scip-query tla fetch-tools                           # download the pinned tla2tools.jar into the cache
 ```
 
-`tla verify` checks the mapping contract against the model text and the indexed code: variable and action referents must resolve to value-like symbols (not types), declared reads/writes are checked against a static scan, and every waiver requires a reason and is counted in the output. At scale, findings are grouped by `(category, modelElement)` with up to 3 exemplars per group by default — pass `--full` to print every finding ungrouped. The `scip-tla-model-system` skill (`scip-query install-skills`) walks the scaffold → verify → instrument → trace-check loop end to end.
+`tla verify` checks the mapping contract against the model text and the indexed code: variable and action referents must resolve to value-like symbols (not types), declared reads/writes are checked against a static scan, and every waiver requires a reason and is counted in the output. At scale, findings are grouped by `(category, modelElement)` with up to 3 exemplars per group by default — pass `--full` to print every finding ungrouped. The `scip-plan` formal-model scenario (`scip-query install-skills`) walks the scaffold → verify → instrument → trace-check loop end to end.
+
+`tla fetch-tools` allows five minutes and 256 MiB for the pinned download by
+default. It streams bytes through the SHA-256 verifier instead of buffering the
+response, rejects malformed or oversized `Content-Length`, and enforces the
+same ceiling when the header is absent. Callers for one cache path serialize on
+a token-owned lock and recheck the winner's checksum before fetching. Failed,
+aborted, or competing operations remove only their random-token staging file;
+the previously accepted cache remains available. Successful promotion flushes
+the verified file and its containing directory before acknowledging the new
+cache where the platform supports directory sync.
+
+File-backed state uses an explicit visibility-versus-crash-durability
+classification. See [Filesystem Publication and Durability](docs/DURABILITY.md)
+for the guarantees, failure outcomes, Windows limitation, and call-site matrix.
+Process coordination uses one versioned, token-owned format with conservative
+malformed-file recovery; see
+[Process Lock Ownership and Recovery](docs/LOCK_PROTOCOL.md).
 
 ## Quick Start
 
@@ -409,7 +488,18 @@ scip-query health --write-baseline   # start the ratchet
 - `scip` CLI, from [Sourcegraph SCIP releases](https://github.com/sourcegraph/scip/releases)
 - A language-specific SCIP indexer for your project
 
-On Windows, the `scip` binary is installed automatically from npm: `scip-query-scip-windows` is an os-gated optional dependency (universal package, x64 + arm64) that only Windows installs fetch. Resolution order: `scip` on PATH, then `SCIP_QUERY_SCIP_BIN`, then the sidecar package. Run `scip-query check-deps` for platform-specific install instructions.
+On Windows, the `scip` binary is installed automatically from npm:
+`scip-query-scip-windows` is an OS-gated optional dependency (universal
+package, x64 + ARM64) that only Windows installs fetch. Resolution order:
+`scip` on PATH, then `SCIP_QUERY_SCIP_BIN`, then the sidecar package. Run
+`scip-query check-deps` for platform-specific install instructions. The
+[Windows sidecar release guide](docs/WINDOWS_SIDECAR_RELEASE.md) defines its
+executable provenance, fail-closed build/pack checks, and registry identity
+gate. Release operators can run `npm run verify:scip-windows-registry` for a
+sidecar-only read, or `npm run release:npm:dry-run` for the complete
+main-plus-sidecar preflight and registry reconciliation without publication.
+The publishing command is `npm run release:npm`; direct `npm publish` refuses
+to run because it cannot own the recoverable two-package ordering.
 
 | Language                      | Indexer          | Install                                                                                                                       |
 | ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
@@ -429,6 +519,16 @@ For Python, the executable may be `scip-python`, `scip-python-plus`, or both. `s
 
 Vue single-file components are handled through the JavaScript/TypeScript indexer. `scip-query` also extracts the `<script>` or `<script setup>` block so symbol, reference, and import queries cover Vue components alongside regular `.ts` and `.js` files.
 
+`augment-vue` uses one in-process Volar context by default. Calibrated projects
+can opt into parallel computation with `SCIP_QUERY_AUGMENT_VUE_WORKERS=<count>`.
+The CLI then owns every worker until exit: a timeout or peer failure terminates
+and awaits all unfinished workers before removing their private result
+directory. `SCIP_QUERY_AUGMENT_VUE_WORKER_TIMEOUT_MS` defaults to five minutes,
+and `SCIP_QUERY_AUGMENT_VUE_WORKER_RESULT_MAX_BYTES` defaults to 64 MiB per
+worker. Every result carries its run, worker, and task identities and is
+size-checked before parsing, so a stale, partial, or mismatched result cannot
+enter the deterministic worker-order merge.
+
 `scip-query capabilities` prints project-level readiness plus a per-language matrix for SCIP indexing, source fallback evidence, semantic provider support, cleanup detector support, and cleanup verification coverage. Use it when you need to know whether a finding is graph-backed, semantic, heuristic, or compiler-verified for the language in front of you.
 
 ## How It Works
@@ -439,6 +539,21 @@ Vue single-file components are handled through the JavaScript/TypeScript indexer
 
 By default, indexes live in `~/.cache/scip-query/projects/<hash>/`, keeping project directories clean. Override paths with `.scipquery.json` or `SCIP_QUERY_*` environment variables. Reindexing writes per-language SCIP shards next to the SQLite index, so a mixed-language repo can reuse unchanged language outputs and rerun only the languages whose source/config inputs changed.
 
+Each accepted worktree-local index is also stored beneath an immutable
+`.scipquery-generations/<identity>/` directory. An atomic `state.json` pointer
+selects the database, SCIP companion, and metadata as one unit; every
+`ScipDatabase` retains that unit for its lifetime. The familiar top-level
+`index.db`, `index.scip`, and `meta.json` files remain compatibility mirrors,
+but internal queries do not reread them after opening a generation. This keeps
+cursor identities and semantic requests attached to the same rows even during
+a concurrent reindex. The publication, crash, legacy-overlap, and retention
+rules are documented in [Local Index Generations](docs/INDEX_GENERATIONS.md).
+
+All `meta.json` consumers share one version decoder and an explicit capability
+matrix. Version 2 remains readable, version 3 is current, and version 4 is a
+reserved unsupported migration boundary. See
+[Reindex Metadata Compatibility](docs/REINDEX_METADATA_COMPATIBILITY.md).
+
 Git worktrees in the same repository also share immutable generations under
 `~/.cache/scip-query/repositories/<repository-id>/`. A shared generation is a
 complete index for one exact committed tree, indexing configuration, artifact
@@ -450,6 +565,15 @@ copy-on-write cloning is used when available, with an ordinary copy fallback;
 hard links are never used. Dirty edits, watcher refreshes, locks, and local
 `evidence.db` state therefore remain private to the worktree.
 
+Each worktree lease names the exact shared generation protected from
+collection. Lease publication, liveness touches, and repository cleanup share
+one repository-cache lock. A touch rereads the current lease only after
+acquiring that lock, validates its ownership checksum and current local
+generation, and changes only `lastSeenAt`. If a newer generation was attached,
+the lease was deleted or recreated, or its ownership changed while the touch
+waited, the touch preserves that current state instead of replaying its stale
+observation.
+
 Automatic refresh follows the same boundary. When `watch.enabled` is true,
 the first watcher-eligible command in each worktree starts or reuses a daemon
 identified by that checkout's Git worktree ID. A Git worktree ID is a checkout
@@ -472,6 +596,16 @@ shared generation is only a warm starting snapshot; it never implies a shared
 watcher or shared later writes. A daemon that exits after its configured idle
 timeout starts warm again when that worktree is next used.
 
+Command-triggered refresh intent is stored separately from disposable activity
+timestamps. Each accepted demand is an immutable request with a deadline and
+optional idempotency key; the daemon claims pending requests exclusively,
+coalesces them deliberately, and acknowledges them only after the corresponding
+reindex completes. A failed attempt returns its requests to pending, and a
+successor daemon recovers claims left by a crashed owner. `watch --status`
+reports pending, claimed, completed, and expired counts. The complete
+at-least-once and retention contract is documented in
+[Watch Refresh Requests](docs/WATCH_REFRESH_REQUESTS.md).
+
 The primary checkout is only a possible source of a generation, never an
 authority for a linked worktree. If its local cache already contains
 uncommitted changes that are absent from a new worktree's `HEAD`, the full
@@ -506,6 +640,26 @@ Historical shadow rows are compact calibration summaries. They rotate at
 project; the complete latest record remains available for status diagnostics.
 After acquiring a project's exclusive reindex lock, each reindex also removes
 staging directories abandoned by interrupted earlier reindexes.
+Watch and watcher-triggered reindex ownership records include the operating
+system process start identity as well as the PID. `watch stop`, daemon
+replacement, and manual preemption verify both values before signaling. A
+legacy record or a platform lookup failure therefore fails closed with an
+explicit recovery error instead of treating a reused PID as the old
+tool-owned process.
+
+Finite subprocesses use explicit wall-time and output budgets. Quick binary
+probes default to 10 seconds, Git operations to 30 seconds, isolated analysis
+workers to 180 seconds, installers and index conversion to 300 seconds, and
+language indexers to 600 seconds. Set `SCIP_QUERY_INDEXER_TIMEOUT_MS` to a
+positive integer to override the indexer deadline. Command-specific checker,
+TLA+, benchmark, and Rust semantic budgets continue to use their documented
+options or environment settings. When an asynchronous finite child exceeds
+its deadline or output budget, scip-query drains both streams, sends `TERM`,
+escalates to `KILL` after a one-second grace period only while the recorded
+process identity still matches, and reports completion only after the child
+has closed. Detached watch and semantic services are deliberate exceptions:
+their persisted identity, lease, request deadlines, and stop protocol own
+their lifetime.
 
 TypeScript monorepos can opt into project sharding with `indexer.typescript.projectMode: "workspace"`. In that mode, `scip-query` discovers repo-local TypeScript project roots, runs one `scip-typescript` process per project with bounded concurrency, merges the shard protobufs, and still publishes one TypeScript language index. Set `indexer.typescript.projects` to an explicit list of project directories or tsconfig paths when automatic discovery is too broad. When `projects` is set to a non-empty list, it is authoritative: only the listed projects are indexed, automatic discovery does not run, and the repo root is not re-added alongside them (even if the root tsconfig covers subdirectories) — files that are only covered by an excluded root tsconfig (e.g. shared ambient `.d.ts` files) drop out of the index, so pick the list deliberately. An empty or absent `projects` falls back to full discovery, unchanged. Workspace mode also caches each project shard: reindexing after an edit reruns only the changed projects and their dependents (workspace `package.json` dependencies and tsconfig `paths`/`references` targets count as dependencies), serves untouched projects from `language-indexes/typescript-projects/`, and reports every reuse decision in `reindex --json` shard diagnostics. Set `indexerConcurrency` when a repo needs a persistent worker cap; CLI `--indexer-concurrency` and `SCIP_QUERY_INDEXER_CONCURRENCY` still override ad hoc runs.
 Use `indexer.typescript.pnpmWorkspaces` only with the default single-project mode; workspace mode passes explicit projects instead.
@@ -520,6 +674,8 @@ Clojure projects can pass a project-local `scip-clojure` config file through `.s
 
 ```json
 {
+  "$schema": "./node_modules/scip-query/docs/schemas/project-config.schema.json",
+  "schemaVersion": 2,
   "languages": ["clojure"],
   "indexer": {
     "clojure": {
@@ -547,6 +703,8 @@ It creates a minimal `.scipquery.json`:
 
 ```json
 {
+  "$schema": "./node_modules/scip-query/docs/schemas/project-config.schema.json",
+  "schemaVersion": 2,
   "languages": ["typescript"],
   "watch": {
     "enabled": true,
@@ -559,6 +717,17 @@ It creates a minimal `.scipquery.json`:
 }
 ```
 
+`schemaVersion` identifies the meaning of the persisted fields. Version 2 is
+the current format. The CLI reads both unversioned/explicit-v1 legacy files
+and version 2. A setup command migrates a legacy file on its next authorized
+config write, preserving fields it does not own. An unsupported future
+version or malformed discriminator fails before any option is used and is
+left byte-for-byte unchanged. `$schema` points editors at the JSON Schema
+bundled with the installed package.
+
+Creation is exclusive: if another process creates `.scipquery.json` first,
+`init` preserves that complete file rather than replacing it.
+
 Add optional fields such as `indexerConcurrency`, `indexer`, `entryRoots`,
 `declaredCouplings`, and `suppressions` only when the project needs them.
 
@@ -571,18 +740,47 @@ background service. Relevant file/Git activity keeps it alive; it exits after
 timeout to `0` to keep it running. `scip-query watch` still provides foreground
 mode, while `watch --daemon`, `watch --status`, and `watch --stop` expose the
 background lifecycle. Both modes share one project lock, so only one can own an
-index cache.
+index cache. Stopping is an asynchronous drain: the watcher first rejects new
+refreshes, continuously consumes a bounded tail of the active worker's output,
+closes every source subscription, and waits for the worker to exit after
+`TERM`/`KILL` escalation before it removes service state or releases the lock.
+`watch --status` reports `Stopping safely` while that work is in progress. If a
+subscription cannot close or worker exit cannot be established, the service
+keeps an explicit degraded draining record and its ownership files instead of
+advertising a clean stop; the reported reason is the recovery evidence.
+Elapsed waits and idle control use a process-local monotonic clock; shared
+heartbeats remain civil-time diagnostics and never authorize replacement or a
+process signal by age alone. See [Time Semantics](docs/TIME_SEMANTICS.md).
 
 The same demand-started service lazily owns TypeScript compiler Projects after
 the first command that needs ts-morph semantics. Separate CLI processes reuse
-that session through a repository-local atomic mailbox; source-only index
+that session through a repository-local bounded mailbox; source-only index
 generations refresh the existing Projects, while configuration or uncertain
 changes replace them. `watch --status` reports Project/session/request counts.
+Current TypeScript and durable Rust mailbox operations use stable
+content-derived identities, pending/inflight/response states, atomic
+owner-expiring claims, retained idempotent completions, FIFO enqueue ordering,
+typed item/byte backpressure, bounded cleanup, and pressure telemetry. Client
+timeout or exit no longer deletes shared work; a service crash before response
+is reclaimable, while a response published before a crash prevents
+re-execution. The precise state machine, default limits, legacy overlap, and
+failure matrix are documented in
+[`docs/MAILBOX_LIFECYCLE.md`](docs/MAILBOX_LIFECYCLE.md).
+Rust v3 additionally binds every accepted response to its request ID,
+operation ID, mailbox-session identity, and authoritative absolute deadline;
+its old/current/future compatibility matrix is in
+[`docs/RUST_DURABLE_SESSION_PROTOCOL.md`](docs/RUST_DURABLE_SESSION_PROTOCOL.md).
 It also reports a rolling 24-hour reindex activity summary: rebuilt, reused,
 failed, and freshness-proven suppressed refreshes plus estimated logical output
 bytes. The estimate counts scip-query artifacts emitted by rebuilt refreshes;
 it is not a measurement of physical SSD writes. The underlying
-`reindex-activity.jsonl` history uses two bounded 1 MiB segments.
+`reindex-activity.jsonl` history uses two bounded 1 MiB segments. Append,
+rotation, and retained-set reads share a process-instance lock; incomplete
+crash tails are trimmed or ignored without deleting earlier complete lines.
+These observations are process-visible rather than crash-durable. See
+[`docs/TELEMETRY_RETENTION.md`](docs/TELEMETRY_RETENTION.md).
+The refresh-request counters reported beside it describe durable demand
+admission and processing state, not reindex frequency.
 If the service is stopped, incompatible, busy beyond its bound, or returns an
 invalid response, the command falls back to the existing in-process ts-morph
 provider.
@@ -592,6 +790,12 @@ session by default. It remains stopped until a Rust semantic request needs it,
 exits after its clean idle period, and automatically falls back to the
 per-command worker on helper/readiness/timeout/request failure. Set
 `SCIP_RUST_SEMANTIC_DURABLE_SESSION=0` for an explicit worker-only opt-out.
+The LSP transport accepts at most a 16 KiB response header and a 64 MiB JSON
+message by default, with a 64 KiB header ceiling and a 256 MiB combined
+wire-buffer ceiling even for programmatic overrides. Missing, invalid,
+duplicate, unsafe, or oversized `Content-Length` framing kills that transport
+once, clears its retained bytes, and fails all outstanding semantic/readiness
+work so the normal worker or graph/source fallback can take over.
 
 Use `declaredCouplings` for files that intentionally form one maintenance unit.
 These pairs are treated as structurally linked by `co-change` and health, while
@@ -639,6 +843,8 @@ Query results are filtered through the project's `.gitignore`. If none exists, c
 - [Detector Guide](docs/DETECTOR_GUIDE.md): what each detector measures, the differences between the confusable ones, and which check to run after which kind of change.
 - [Agent Guide](docs/AGENT_GUIDE.md): goal-oriented workflows for tracing, planning, cleanup, quality checks, and change verification.
 - [Command Reference](docs/COMMAND_REFERENCE.md): generated command syntax, descriptions, and options.
+- [CLI JSON output contract](docs/CLI_JSON_OUTPUT.md): versioned envelopes, compatibility rules, and schema.
+- [Security model](docs/SECURITY_MODEL.md): untrusted-checkout boundaries, authority flags, input budgets, and complete-output pagination.
 - [Programmatic API](docs/API.md): using the query functions from TypeScript.
 - [Historical plans](https://github.com/PlunderStruck/scip-query/tree/main/docs/plans): implementation notes and completed cleanup plans.
 

package/dist/augment-vue-worker.js

@@ -1,2 +1,2 @@
-import{c as t}from"./chunk-64RFXJT5.js";import"./chunk-C7NIYIQ4.js";import{writeFileSync as o}from"fs";import{workerData as s}from"worker_threads";var e=s;try{let r=t({projectRoot:e.projectRoot,dbPath:e.dbPath,tsconfig:e.tsconfig,vueFiles:e.vueFiles,tasks:e.tasks});o(e.resultPath,JSON.stringify({ok:!0,result:r}))}catch(r){o(e.resultPath,JSON.stringify({ok:!1,error:r instanceof Error?r.message:String(r)}))}finally{let r=new Int32Array(e.sharedBuffer);Atomics.add(r,0,1),Atomics.notify(r,0)}
+import{c as t}from"./chunk-3ZSJ3PWF.js";import"./chunk-IF6FP6B2.js";import"./chunk-C5Q44Q5D.js";import"./chunk-46XGSFNI.js";import{writeFileSync as s}from"fs";import{workerData as o}from"worker_threads";var r=o;try{let e=t({projectRoot:r.projectRoot,dbPath:r.dbPath,tsconfig:r.tsconfig,vueFiles:r.vueFiles,tasks:r.tasks});s(r.resultPath,JSON.stringify({version:1,runId:r.runId,workerId:r.workerId,taskIds:r.taskIds,ok:!0,result:e}))}catch(e){s(r.resultPath,JSON.stringify({version:1,runId:r.runId,workerId:r.workerId,taskIds:r.taskIds,ok:!1,error:e instanceof Error?e.message:String(e)}))}
 //# sourceMappingURL=augment-vue-worker.js.map