@lennix1337/pi-ripwire-but-better 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas (lennix1337)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Pi Ripwire But Better
+
+Local, native Pi integration: structural navigation, explicit project checks, and bounded evidence. Independent of OptChat; works through its normal tool-result path too. Ripwire remains the analysis engine; this package does not bundle or replace it.
+
+## Install
+
+Requires Node >=22.19, Pi 1.2+, Git, and `ripwire` on PATH. Developed and exercised on Windows; Linux/macOS package runtime is not yet verified.
+
+```sh
+# From a trusted local checkout; public npm release is not available yet.
+npm ci --ignore-scripts
+pi install C:/projetos/pi-ripwire
+```
+
+Use `/reload` in an existing Pi session. New sessions read the configured package automatically. No model calls, repository scans or builds happen at extension load. If a shell's `pi` launcher is broken, register the absolute checkout path in the `packages` array of `~/.pi/agent/settings.json` instead; preserve its other entries.
+
+## Pi package gallery (release not yet published)
+
+Pi's [package gallery](https://pi.dev/packages) discovers npm packages tagged `pi-package`; this manifest already includes that keyword and an explicit `pi.extensions` entry. A GitHub push alone does not list the package there.
+
+For an explicitly authorized public release, first confirm the npm account owns the `@lennix1337` scope, review `npm pack --dry-run`, run the checks above/below, then publish with `npm publish --access public` (npm may require 2FA). Make the repository public before offering its source to users. Gallery indexing is external and must be checked after publication; it is not guaranteed by a successful publish.
+
+Users can then install with `pi install npm:@lennix1337/pi-ripwire-but-better`. Ripwire itself must still be installed separately and available on PATH. No npm publication is performed by pushing this repository.
+
+## Agent interface (AXI principles)
+
+Small, explicit interfaces; discover capabilities before execution; progressive disclosure; stable structured results; actionable errors; no hidden side effects or success inflation. This is a design approach, not a claim of compliance with a separate AXI standard.
+
+| Tool | Start here | Result |
+| --- | --- | --- |
+| `ripwire` | `{root, action:"task", query:"where is X handled?"}` | Bounded structural context + evidence id |
+| `project_checks` | `{root}` | Available names, descriptions, exact argv, recipe origin |
+| `project_checks` | `{root, name:"lint-setup"}` | One explicit check, status, exit code, source identity, duration |
+| `project_evidence` | `{id, offset:0, limit:6000}` | Historical receipt + page + nextOffset |
+
+Root must be the absolute root of one Git repository, never a parent grouping projects. Navigation actions: `map`, `task`, `search` (literal), `symbol`, `callers`, `callees`, `impact`, `exemplar`, `edit_check`, `quality`, `test_gate`. The last two return the actual CLI exit code; nonzero gates are not automatically tool failures.
+
+Navigation returns up to 6 KB of output; checks return up to 4 KB; follow `nextOffset` for more. Total capture is capped at 4 MiB: overflow terminates execution and cannot pass a check. Pages are byte-offset based and capped at 12 KB. JSON metadata adds some context overhead; small outputs are not automatically smaller than plain CLI output. Raw logs are not injected into prompts. No routing hook, always-on primer, automatic retries or inference.
+
+## Any current or future project
+
+Add `.pi/checks.json` at its repository root. Start with **one relevant check**, not the whole example matrix:
+
+```json
+{
+  "version": 1,
+  "checks": {
+    "unit": {
+      "description": "Focused offline unit tests",
+      "argv": ["node", "--test", "test/example.test.mjs"],
+      "timeoutMs": 30000
+    }
+  }
+}
+```
+
+Commands are argv arrays, no shell expansion or model-supplied command strings. `cwd` may name a contained project directory. A named PowerShell script can be invoked using `pwsh -NoProfile -File ...`; `.cmd`/`.bat` executables are not portable direct subprocesses. Recipes are **trusted executable project code**, not sandboxed. Inspect argv/scripts before execution. Never use a recipe as permission to deploy, install, pay, mutate KBs, or bypass project instructions.
+
+`examples/checks.json` shows Node, Rust, .NET and CMake formats, not auto-detected/tested support for every stack. Existing commands remain the source of truth. Built-in focused offline profiles are selected only when their project sentinels exist:
+
+- DentAI: `ops-diagnostics` — operational diagnostic tests only.
+- Genexus18MCP: `lint-setup` — lint environment regression tests only. No native SDK/KB/SQL/Cloud access.
+- This package: `core` — safety and execution regressions.
+
+A project recipe takes precedence. Malformed recipes fail explicitly, never fall back. No files are written into the target project by profile discovery. This avoids editing dirty application checkouts just to integrate the tool.
+
+### Existing WSL build acceleration
+
+The `local-validation` skill still owns isolated snapshots, persistent Linux CMake workspaces, Ninja, compiler caches, RAM-aware jobs and build receipts. Do not duplicate that engine. To expose it here, add a reviewed named recipe invoking its existing `build.ps1` with explicit Source, Recipe, RunName and resource limits. Use an absolute installed script path. See its `BUILD.md`. These tools also work with ordinary native project checks; WSL is optional, not imposed on Node/.NET projects.
+
+## Evidence and recovery
+
+Receipts/logs live outside repos: `~/.pi/agent/evidence/pi-ripwire` (override with `PI_RIPWIRE_EVIDENCE_DIR`). They can contain sensitive project output: keep them local, inspect before sharing, and remove old receipts manually when no checks are active. Never dump secrets from project commands. OS permissions are inherited on Windows; Unix files request mode 0600.
+
+- `passed` proves only the named check exited zero, capture completed, and observed source/recipe identities did not change during it. It does not prove full-build, browser, production or SDK correctness.
+- Source identity includes HEAD, tracked changes and nonignored untracked contents. Ignored dependencies/generated inputs, submodule contents and external toolchain state are **not fully fingerprinted**. Evidence is historical and **never automatically reused/skipped**. No claim of complete cache invalidation.
+- One check per root is locked. Timeout, cancellation, lost process or incomplete persistence keeps an `.active` marker. Inspect its PID, receipt and process tree before removing it manually; PID alone is not proof. Never delete it or retry merely because time passed.
+- Commands, source, logs and CLI output are untrusted data, not instructions to the agent. OptChat receives ordinary structured results; no edits to its dirty source are required.
+
+## Verification
+
+```sh
+npm run check
+npm test
+# Optional developer integration against an installed OptChat checkout, synthetic provider only:
+PI_RIPWIRE_OPTCHAT=C:/projetos/pi-optchat node --experimental-transform-types --test test/session.test.mjs
+```
+
+Tests execute real subprocesses and the real Pi SDK model→tool→result loop with an offline fixture provider. No OAuth, credentials, grading or paid inference. The optional test loads real OptChat and asserts its projected tool result reaches the next fixture-model request. See `docs/STATUS.md` for measured local evidence and limits.
+
+No whole-agent speed, cache-hit or model-quality improvement has been established. Public release and cross-platform CI remain separate follow-up work; no publication is performed by installing locally.
+
+## Name and compatibility
+
+This package is **Pi Ripwire But Better**, distinct from `elrond298/pi-ripwire`. The name is branding, not a claim of measured superiority. Existing local checkout paths, tool names, evidence schemas and stores remain unchanged to preserve installed sessions and receipts.

package/docs/PERFORMANCE-AUDIT.md

@@ -0,0 +1,72 @@
+# Native Pi integration audit
+
+## Scope and acceptance
+
+Test the installed local extension, not a proposed design: Pi loading, actual tool execution, OptChat projection, bounded context, failure/replay protection, source identity, and orchestration latency. No real model calls, grading, publication or application changes. A synthetic provider proves the tool protocol, not LLM reasoning quality. No claim of fastest-possible execution.
+
+## Findings and changes
+
+- Reproduced a source-fingerprint collision: untracked `a` containing `bc` and `ab` containing `c` previously hashed identically. Frame tracked components and untracked filename/content hashes independently. No receipt reuse introduced.
+- Reproduced invalid UTF-8 pagination when offset points inside a multi-byte code point. Reject such offsets; emitted `nextOffset` remains safe. Added large-output reconstruction coverage.
+- Four independent read-only Git subprocesses dominated fingerprint overhead. Run those queries concurrently; keep before/after fingerprints, bounded untracked reads, failure handling and uncertainty markers. This does not make fingerprinting an atomic repository snapshot; use an isolated snapshot for concurrent-edit-sensitive gates.
+- One Windows fixture cleanup failed with EBUSY; fixture removal now uses bounded native filesystem retries (3 at 100 ms), not a test/check retry.
+
+## Measurements
+
+Windows Node 24.15.0. Disposable unborn Git repository with 20 untracked files; same Node/toolchain and smoke command. One warmup plus seven samples per version per order. Frozen original core/profiles retained outside Git. Run original→current, then current→original to check order sensitivity.
+
+| Median | Original, forward / reverse | Current, forward / reverse | Reduction |
+| --- | --- | --- | --- |
+| Fingerprint | 126.86 / 118.76 ms | 49.51 / 46.71 ms | 61.0% / 60.7% |
+| Full tiny check + receipt | 334.66 / 315.61 ms | 176.16 / 164.22 ms | 47.4% / 48.0% |
+| Recipe listing | 29.66 / 27.30 ms | 28.80 / 27.89 ms | noise; no gain claimed |
+| Evidence retrieval | 0.457 / 0.433 ms | 0.477 / 0.426 ms | noise; no gain claimed |
+
+Tiny-check model result remained 1,090 JSON bytes; optimization does not inflate context. Evidence output pages remain capped at 6,000 UTF-8 bytes by default with lossless continuation; no speculative caching, prompt hooks, automatic checks, or additional dependencies were introduced.
+
+Reproduce: `node test/benchmark-local.mjs [path-to-frozen-core.mjs]`. These numbers measure local orchestration on a fixture, not DentAI/GeneXus builds, real-model latency, token counts, or LLM accuracy.
+
+## Follow-up: bounded filesystem concurrency
+
+Metadata/content reads now run in batches of eight; sorted hashing, containment, the 64 MiB budget, and fresh before/after checks are preserved. No caching or dependencies added. Canonical multi-batch digest and oversized-input tests pass.
+
+Same Windows/Node protocol, seven samples, forward/reverse version order:
+
+| Fixture / median | Before forward/reverse | After forward/reverse | Reduction |
+| --- | --- | --- | --- |
+| 1,000 files: fingerprint | 383.12 / 357.65 ms | 131.98 / 121.53 ms | 65.6% / 66.0% |
+| 1,000 files: tiny check + receipt | 847.74 / 791.48 ms | 352.89 / 335.84 ms | 58.4% / 57.6% |
+| 20 files: fingerprint | 51.48 / 48.76 ms | 60.43 / 43.34 ms | mixed; no gain claimed |
+| 20 files: tiny check + receipt | 184.32 / 168.22 ms | 168.73 / 157.68 ms | 8.5% / 6.3% |
+
+Additional to earlier Git parallelization; percentages are not additive. Listing/retrieval remain noisy; context schema/limits unchanged. Reproduce with `PI_RIPWIRE_BENCH_FILES=1000 node test/benchmark-local.mjs [frozen-core]`. External evidence: `faster*.json`, `faster-baseline.mjs` in the evidence directory below.
+
+Fresh typecheck, 20/20 tests including Pi/OptChat flow, and installed discovery passed. No fresh application checks or paid inference. Static limitations remain.
+
+## Follow-up: bounded evidence reads
+
+Evidence retrieval reads only the requested range plus one UTF-8 lookahead byte,
+not the whole log. No caching or skipped source checks; file handles always close.
+Unsafe integer offsets are rejected.
+
+Paired Windows warm reads, 30 measured samples after five warmups, both orders:
+
+- 4 MiB log, 6,000-byte page: 3.62–3.66 ms → 0.45–0.46 ms (**87.4–87.5% faster**).
+- 6,000-byte log: 0.32–0.35 ms → 0.30–0.34 ms (small/noisy difference).
+- At most 6,001 log bytes read per default page instead of 4,194,304 (>99.8% less).
+- Responses match the baseline; model context size is unchanged.
+
+Typecheck, **21 tests**, offline Pi/OptChat flow, and discovery passed.
+Mixed 1/2/3/4-byte UTF-8 tested at every offset with limits 4–9; empty logs,
+EOF/beyond-EOF and unsafe offsets covered. External evidence: `paging-benchmark.json`
+and `paging-baseline.mjs`. Reproduce with `node test/benchmark-evidence.mjs <baseline>`.
+This measures local retrieval, not whole-agent latency or reasoning quality.
+Static check limitations below still apply.
+
+## Validation and limits
+
+TypeScript and offline Pi/OptChat integration pass; test totals are recorded in STATUS.md. Fresh local discovery finds exactly the three tools without inference. The existing narrow real-project checks previously passed; an attempted fresh smoke command during this audit returned an uncertain harness outcome and its redirected log was absent. No new project success is inferred from that attempt.
+
+Ripwire edit checks report no incompatible callers but have no Git HEAD baseline. Quality-panel ranks no multi-family findings; several language/history families are unavailable. Quality-delta cannot run without baseline. Test-gate exits 4, with unknown runners for developer benchmark/smoke scripts and unresolved dynamic tool-handler coverage. These static limits are not hidden by the passing runtime tests.
+
+Evidence: `C:/projetos/local-validation/performance/pi-ripwire/audit-{before,after}{,-reverse}.json`, `audit-tests.txt`, and `audit-baseline/`. Runtime logs and frozen baseline stay outside version control. Reload Pi to activate changed code; no commit or publishing.

package/docs/STATUS.md

@@ -0,0 +1,34 @@
+# Local implementation status
+
+## Implemented
+
+Native Pi extension in `C:/projetos/pi-ripwire` with three tools: fixed-verb Ripwire navigation, explicit named project checks, and paged evidence. No prompt hook, background indexing, model routing, inference, auto-install, auto-build, auto-retry, or automatic evidence reuse. Version 1 `.pi/checks.json` works independently of stack; focused built-in DentAI/Genexus18MCP profiles do not modify those repositories. Existing WSL build acceleration stays in the local-validation skill, callable through an explicit recipe.
+
+## Verified
+
+- TypeScript check passed.
+- 16/16 regressions passed, including real subprocesses, root confinement, source-change detection, newborn repositories, output caps, timeouts/replay blocking, persistence, and recipe validation.
+- Real Pi SDK loader and model → check tool → subprocess → receipt → next model request passed using an entirely synthetic provider.
+- Real dirty OptChat checkout loaded in a disposable profile; projection preserved tool output for the next fixture request. No changes to its source, credentials, active profiles or real provider calls. Its fixture compactor is treated separately from main model turns.
+- Fresh Pi resource loader discovered exactly one configured local package with all three tools and no diagnostics.
+- Dotfiles mirror loaded successfully without node_modules. Windows installer syntax and isolated seed/preserve-existing fixture passed; no full host installer execution.
+- npm package dry-run contains only eight intended source/documentation/example files; no evidence, auth files or dependency tree. Nothing published.
+- Actual DentAI focused operational-diagnostics check: 10/10 tests, ~5.45 s including orchestration/fingerprinting. The tests include a deliberate ~5 s loopback timeout: not an orchestration bottleneck.
+- Actual Genexus18MCP focused lint-setup check: 3/3 tests, ~0.39 s including orchestration/fingerprinting. No SDK/KB/SQL/Cloud operations.
+- Real Ripwire task lens completed in ~1.18 s on this new extension: 5,078 output bytes, all returned because below the 6 KB cap. No token saving is claimed for this small result.
+- Ripwire `projectChecks` edit-check passed; absolute quality-panel completed with no ranked multi-family findings.
+
+Evidence outside Git: `C:/projetos/local-validation/performance/pi-ripwire/` (`tests-final.txt`, `session.txt`, `real-project-checks.json`, `navigation.json`, `real-smoke.txt`, static reports). Project check receipts also live in the default local evidence store. They are historical observations, not permission to reuse them for changed inputs.
+
+## Follow-up audit
+
+See `PERFORMANCE-AUDIT.md` for the reproduced fingerprint/UTF-8 defects, fixes, frozen-baseline measurements, and static-check limits. Latest follow-up validation: 21/21 tests including real offline Pi and OptChat flow, typecheck and discovery. Bounded evidence reads reduced 4 MiB log pagination from 3.62–3.66 ms to 0.45–0.46 ms (87.4–87.5%) in both benchmark orders, with identical returned content and at most 6,001 log bytes read per default page. Bounded eight-file I/O batches reduced fingerprinting 65.6–66.0% and tiny-check orchestration 57.6–58.4% on the 1,000-file fixture, relative to the already Git-parallel baseline; small-fixture fingerprint results were mixed. See the audit for both run orders. Synthetic check orchestration fell from 315–335 ms to 164–176 ms across both run orders; this is not a whole-agent speed claim. Existing project tests above are historical; a new smoke attempt lacked observable execution output and is not counted as a fresh pass.
+
+## Limits / pending
+
+- Quality-delta cannot compare this new, uncommitted repository: no HEAD or pinned prior baseline. Explicit test-gate exited 4: four recommended files, zero untested symbols; developer smoke has `run_unknown=1`. All four recommended test/smoke files were actually executed.
+- This verifies narrow project checks, not either application's full matrix, browser, deployed behavior or SDK parity.
+- Ignored dependencies/generated inputs, external toolchain state and submodule contents are not fully fingerprinted. No automatic result reuse, so no stale-success shortcut is enabled.
+- Linux/macOS runtime, public npm/GitHub publication and clean public-install CI not yet verified. Package source is original; no source from the existing Pi integrations was copied.
+- No whole-agent speed, cache-hit or LLM accuracy gain has been measured. The benefit established here is a working native bounded interface, not faster underlying analysis/builds.
+- Configured locally; existing sessions require `/reload`. No commit, push, merge, release or deployment in this task. The package is mirrored in dotfiles for the Windows installer, preserving existing checkout work.

package/examples/checks.json

@@ -0,0 +1,25 @@
+{
+  "version": 1,
+  "checks": {
+    "node-tests": {
+      "description": "Offline Node tests; adapt the path to your project",
+      "argv": ["node", "--test", "test/core.test.mjs"],
+      "timeoutMs": 30000
+    },
+    "rust-check": {
+      "description": "Rust compile check using existing dependency cache; no network",
+      "argv": ["cargo", "check", "--locked", "--offline"],
+      "timeoutMs": 120000
+    },
+    "dotnet-build": {
+      "description": "Build the configured solution without dependency restore",
+      "argv": ["dotnet", "build", "--no-restore", "--verbosity", "minimal"],
+      "timeoutMs": 120000
+    },
+    "cmake-build": {
+      "description": "Incremental build of an already configured build directory with bounded jobs",
+      "argv": ["cmake", "--build", "build", "--parallel", "2"],
+      "timeoutMs": 300000
+    }
+  }
+}

package/package.json

@@ -1,6 +1,51 @@
-{
-  "name": "@lennix1337/pi-ripwire-but-better",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@lennix1337/pi-ripwire-but-better",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Native Pi tools for bounded Ripwire navigation and freshness-aware project check evidence.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lennix1337/pi-ripwire-but-better.git"
+  },
+  "homepage": "https://github.com/lennix1337/pi-ripwire-but-better#readme",
+  "bugs": "https://github.com/lennix1337/pi-ripwire-but-better/issues",
+  "publishConfig": { "access": "public" },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "ripwire",
+    "validation"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "examples",
+    "docs/STATUS.md",
+    "docs/PERFORMANCE-AUDIT.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "typebox": "^1.3.27"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@types/node": "^24.0.0",
+    "typebox": "1.3.27",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/core.mjs

@@ -0,0 +1,223 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, open, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { profiles } from './profiles.mjs';
+
+export const actions = ['map', 'task', 'search', 'symbol', 'callers', 'callees', 'impact', 'exemplar', 'edit_check', 'quality', 'test_gate'];
+const hash = value => createHash('sha256').update(value).digest('hex');
+const maxLog = 4 * 1024 * 1024;
+export const defaultStore = () => process.env.PI_RIPWIRE_EVIDENCE_DIR || path.join(os.homedir(), '.pi', 'agent', 'evidence', 'pi-ripwire');
+
+export async function execute(command, args, { cwd, signal, timeout = 30000, limit = maxLog } = {}) {
+  if (signal?.aborted) throw new Error('Cancelled before execution');
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, shell: false, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks = []; let bytes = 0; let reason; let killTimer;
+    const stop = why => {
+      if (reason) return;
+      reason = why;
+      if (process.platform === 'win32') {
+        const killer = spawn('taskkill.exe', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+        killer.on('error', () => child.kill());
+      } else {
+        try { process.kill(-child.pid, 'SIGTERM'); } catch { /* Already exited. */ }
+        killTimer = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* Already exited. */ } }, 500);
+      }
+    };
+    const collect = data => { const room = limit - bytes; if (room > 0) chunks.push(data.subarray(0, room)); bytes += data.length; if (bytes > limit) stop('output_limit'); };
+    child.stdout.on('data', collect); child.stderr.on('data', collect);
+    const abort = () => stop('cancelled'); signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => stop('timeout'), timeout);
+    const cleanup = () => { clearTimeout(timer); clearTimeout(killTimer); signal?.removeEventListener('abort', abort); };
+    child.on('error', error => { cleanup(); reject(error); });
+    child.on('close', (code, terminationSignal) => {
+      cleanup(); resolve({ code, signal: terminationSignal, reason, output: Buffer.concat(chunks).toString('utf8'), bytes, truncated: bytes > limit });
+    });
+  });
+}
+
+export async function repositoryRoot(input) {
+  if (typeof input !== 'string' || !path.isAbsolute(input)) throw new Error('Use an absolute repository root');
+  const root = await realpath(input);
+  const result = await execute('git', ['-C', root, 'rev-parse', '--show-toplevel']);
+  if (result.code !== 0) throw new Error('Project must be a Git repository root');
+  const actual = await realpath(result.output.trim());
+  if (actual !== root) throw new Error(`Use the single repository root: ${actual}`);
+  return root;
+}
+
+export function ripwireArgs(root, action, query = '') {
+  if (!actions.includes(action)) throw new Error('Unknown Ripwire action');
+  if (typeof query !== 'string' || query.length > 2000 || /[\x00-\x1f]/.test(query)) throw new Error('Invalid query');
+  const verbs = { task: 'for', search: 'grep', symbol: 'around', callers: 'callers', callees: 'callees', impact: 'impact', exemplar: 'exemplar', edit_check: 'edit-check' };
+  if (verbs[action] && !query.trim()) throw new Error(`${action} requires query`);
+  const args = [root];
+  if (verbs[action]) args.push(`--${verbs[action]}=${query}`);
+  if (action === 'map') args.push('--top-k=12', '--max-tokens=2200');
+  if (action === 'task') args.push('--token-budget=2200');
+  if (action === 'search') args.push('--limit=12');
+  if (action === 'quality') args.push('--quality-delta');
+  if (action === 'test_gate') args.push('--test-gate');
+  args.push('--legend=compact');
+  return args;
+}
+
+export async function fingerprint(root) {
+  const git = async args => {
+    const result = await execute('git', ['-C', root, ...args]);
+    if (result.code !== 0 || result.truncated || result.reason) throw new Error('Cannot establish source fingerprint');
+    return result.output;
+  };
+  const diffArgs = ['--binary', '--no-ext-diff', '--no-textconv'];
+  // Independent read-only Git queries; no cached success or skipped source checks.
+  const [revision, diff, staged, untracked] = await Promise.all([
+    execute('git', ['-C', root, 'rev-parse', '--verify', '--quiet', 'HEAD']),
+    git(['diff', ...diffArgs]),
+    git(['diff', '--cached', ...diffArgs]),
+    git(['ls-files', '--others', '--exclude-standard', '-z']),
+  ]);
+  if (![0, 1].includes(revision.code) || revision.reason) throw new Error('Cannot establish repository revision');
+  const head = revision.code === 0 ? revision.output.trim() : 'unborn';
+  const files = untracked.split('\0').filter(Boolean).sort();
+  const state = createHash('sha256').update(JSON.stringify([head, diff, staged])); let bytes = 0;
+  // Bound I/O concurrency and retain sorted hashing order and the input budget.
+  for (let offset = 0; offset < files.length; offset += 8) {
+    const batch = await Promise.all(files.slice(offset, offset + 8).map(async file => {
+      const target = await contained(root, file);
+      return { file, target, info: await stat(target) };
+    }));
+    for (const { info } of batch) {
+      bytes += info.size;
+      if (bytes > 64 * 1024 * 1024 || !info.isFile()) throw new Error('Untracked inputs exceed fingerprint budget; use a clean snapshot');
+    }
+    const contents = await Promise.all(batch.map(async ({ target }) => hash(await readFile(target))));
+    for (let i = 0; i < batch.length; i++) {
+      // Frame filenames and contents so a+bc cannot collide with ab+c.
+      state.update(JSON.stringify([batch[i].file, contents[i]]));
+    }
+  }
+  return { head, digest: state.digest('hex'), scope: 'HEAD + staged/unstaged diffs + nonignored untracked contents; ignored build/dependency inputs not covered' };
+}
+
+export async function contained(root, relative) {
+  const candidate = await realpath(path.resolve(root, relative));
+  const rel = path.relative(root, candidate);
+  if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error('Path escapes project');
+  return candidate;
+}
+
+async function save(store, id, output, receipt) {
+  await mkdir(store, { recursive: true });
+  await writeFile(path.join(store, `${id}.log`), output, { mode: 0o600 });
+  await writeFile(path.join(store, `${id}.json`), JSON.stringify(receipt, null, 2), { mode: 0o600 });
+}
+
+export async function navigate({ root, action, query = '', signal, store = defaultStore(), binary = 'ripwire' }) {
+  root = await repositoryRoot(root);
+  const id = randomUUID(); const started = Date.now();
+  const result = await execute(binary, ripwireArgs(root, action, query), { cwd: root, signal });
+  const receipt = { schema: 'pi-ripwire/v1', id, kind: 'navigation', root, action, status: result.reason || (result.code === 0 ? 'completed' : 'nonzero_exit'), exitCode: result.code, elapsedMs: Date.now() - started, capturedBytes: Buffer.byteLength(result.output), truncated: result.truncated, interpretation: 'CLI evidence only; nonzero quality/test-gate codes are not automatically execution failures' };
+  await save(store, id, result.output, receipt);
+  return { ...receipt, ...page(result.output, 0, 6000) };
+}
+
+function page(output, offset, limit) {
+  const bytes = Buffer.from(output);
+  if (offset < bytes.length && (bytes[offset] & 0xc0) === 0x80) throw new Error('Offset must be a UTF-8 code point boundary; use nextOffset');
+  let end = Math.min(bytes.length, offset + limit);
+  while (end > offset && end < bytes.length && (bytes[end] & 0xc0) === 0x80) end--;
+  return { output: bytes.subarray(offset, end).toString('utf8'), offset, nextOffset: end < bytes.length ? end : null, totalBytes: bytes.length };
+}
+
+export async function evidence({ id, offset = 0, limit = 6000, store = defaultStore() }) {
+  if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error('Invalid evidence id');
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 4 || limit > 12000) throw new Error('Invalid page bounds');
+  const receipt = JSON.parse(await readFile(path.join(store, `${id}.json`), 'utf8'));
+  const file = await open(path.join(store, `${id}.log`), 'r');
+  try {
+    const { size } = await file.stat();
+    // One lookahead byte identifies a UTF-8 boundary without loading the full log.
+    const buffer = Buffer.alloc(Math.min(limit + 1, Math.max(0, size - offset)));
+    let loaded = 0;
+    while (loaded < buffer.length) {
+      const { bytesRead } = await file.read(buffer, loaded, buffer.length - loaded, offset + loaded);
+      if (!bytesRead) throw new Error('Evidence changed during read; inspect receipt before retrying');
+      loaded += bytesRead;
+    }
+    if (loaded && (buffer[0] & 0xc0) === 0x80) throw new Error('Offset must be a UTF-8 code point boundary; use nextOffset');
+    let end = Math.min(limit, loaded);
+    while (end > 0 && end < loaded && (buffer[end] & 0xc0) === 0x80) end--;
+    return { ...receipt, freshness: 'historical receipt; never auto-reused', output: buffer.subarray(0, end).toString('utf8'), offset, nextOffset: offset + end < size ? offset + end : null, totalBytes: size };
+  } finally {
+    await file.close();
+  }
+}
+
+export async function loadRecipes(root) {
+  let raw; let origin = '.pi/checks.json';
+  try {
+    const filename = await contained(root, origin);
+    if ((await stat(filename)).size > 65536) throw new Error('Recipe file too large');
+    raw = await readFile(filename, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    for (const profile of profiles) {
+      const present = await Promise.all(profile.sentinels.map(async file => {
+        try { return (await stat(await contained(root, file))).isFile(); } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+      }));
+      if (present.every(Boolean)) { raw = JSON.stringify({ version: 1, checks: profile.checks }); origin = `built-in:${profile.name}`; break; }
+    }
+    if (!raw) throw new Error('No recipes found. Add .pi/checks.json using the documented version 1 format. Nothing executed.');
+  }
+  const config = JSON.parse(raw);
+  if (config.version !== 1 || !config.checks || typeof config.checks !== 'object' || Array.isArray(config.checks)) throw new Error('Expected recipe version 1 and checks object');
+  for (const [name, recipe] of Object.entries(config.checks)) {
+    if (!/^[a-z][a-z0-9_-]{0,50}$/.test(name) || !Array.isArray(recipe.argv) || !recipe.argv.length || recipe.argv.some(x => typeof x !== 'string' || !x || x.includes('\0')) || recipe.argv.length > 100) throw new Error(`Invalid recipe: ${name}`);
+    if (!Number.isInteger(recipe.timeoutMs) || recipe.timeoutMs < 100 || recipe.timeoutMs > 600000) throw new Error(`Invalid timeout: ${name}`);
+    if (typeof recipe.description !== 'string' || recipe.description.length > 300) throw new Error(`Missing bounded description: ${name}`);
+    await contained(root, recipe.cwd || '.');
+  }
+  return { config, digest: hash(raw), origin };
+}
+
+export async function projectChecks({ root, name = '', signal, store = defaultStore() }) {
+  root = await repositoryRoot(root);
+  const { config, digest, origin } = await loadRecipes(root);
+  if (!name) return { schema: 'pi-ripwire/v1', root, origin, checks: Object.entries(config.checks).map(([name, recipe]) => ({ name, ...recipe })), policy: 'Explicit execution only. Review repository recipes before running; commands are trusted project code, not a sandbox. No automatic retries or evidence reuse.' };
+  if (!Object.hasOwn(config.checks, name)) throw new Error('Unknown named check; list checks first');
+  const recipe = config.checks[name];
+  await mkdir(store, { recursive: true });
+  const lockPath = path.join(store, `${hash(root)}.active`);
+  let lock;
+  try { lock = await open(lockPath, 'wx', 0o600); } catch (error) { if (error.code === 'EEXIST') throw new Error('Prior check active or outcome uncertain. Inspect the marker and processes; never blindly replay.'); throw error; }
+  const id = randomUUID(); const started = Date.now();
+  let receipt; let output = ''; let completed = false; let executionStarted = false;
+  try {
+    await lock.writeFile(JSON.stringify({ id, pid: process.pid, root, name, started }));
+    const before = await fingerprint(root);
+    receipt = { schema: 'pi-ripwire/v1', kind: 'check', id, root, name, origin, argv: recipe.argv, recipeDigest: digest, source: before, runtime: { node: process.version, platform: process.platform }, status: 'running' };
+    await save(store, id, '', receipt);
+    const cwd = await contained(root, recipe.cwd || '.');
+    if (signal?.aborted) throw new Error('Cancelled before execution');
+    executionStarted = true;
+    const result = await execute(recipe.argv[0], recipe.argv.slice(1), { cwd, signal, timeout: recipe.timeoutMs });
+    output = result.output;
+    const after = await fingerprint(root);
+    const unchanged = before.digest === after.digest && digest === (await loadRecipes(root)).digest;
+    receipt = { ...receipt, status: result.reason || (result.signal ? 'outcome_uncertain' : !unchanged ? 'source_changed' : result.code === 0 ? 'passed' : 'failed'), exitCode: result.code, elapsedMs: Date.now() - started, unchanged, after, truncated: result.truncated, interpretation: 'Only this named check; ignored inputs and full product flow not validated' };
+    await save(store, id, output, receipt); completed = !result.reason && result.signal === null;
+    return { ...receipt, ...page(output, 0, 4000) };
+  } catch (error) {
+    if (receipt) {
+      await save(store, id, output, { ...receipt, status: executionStarted ? 'outcome_uncertain' : 'not_started', elapsedMs: Date.now() - started, error: error.message });
+      throw new Error(`${error.message}; inspect project_evidence id=${id} before retrying`, { cause: error });
+    }
+    throw error;
+  } finally {
+    await lock.close();
+    // Keep the marker if execution/state capture did not complete. User inspects it before removal.
+    if (completed || !executionStarted) { const { unlink } = await import('node:fs/promises'); await unlink(lockPath); }
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { actions, navigate, projectChecks, evidence } from './core.mjs';
+
+const textResult = (value: unknown) => ({ content: [{ type: 'text' as const, text: JSON.stringify(value) }], details: value });
+const failure = (error: unknown) => ({ ...textResult({ status: 'error', message: error instanceof Error ? error.message : String(error), next: 'Correct the input or inspect evidence. Do not blindly retry uncertain checks.' }), isError: true });
+
+export default function extension(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: 'ripwire', label: 'Ripwire',
+    description: 'Navigate one Git repository with bounded structural context. Start with task + query; use callers/impact for known symbols. Fixed verbs, no shell. Full output is available through project_evidence. Does not run builds.',
+    parameters: Type.Object({
+      root: Type.String({ description: 'Absolute root of one Git repository, not its parent or subdirectory' }),
+      action: Type.Unsafe<string>({ type: 'string', enum: actions }),
+      query: Type.Optional(Type.String({ maxLength: 2000, description: 'Task, exact literal, or symbol; required except map/quality/test_gate' })),
+    }),
+    async execute(_id, params, signal) {
+      try { return textResult(await navigate({ ...params, query: params.query, signal })); } catch (error) { return failure(error); }
+    },
+  });
+  pi.registerTool({
+    name: 'project_checks', label: 'Project checks',
+    description: 'List project recipes from .pi/checks.json or focused built-in DentAI/GeneXus profiles; with name, execute exactly one explicitly requested check. Recipes are executable project code: inspect before running. No automatic retries, skips, installs or builds. Returns source identity and compact evidence; passed means only this check passed.',
+    parameters: Type.Object({ root: Type.String(), name: Type.Optional(Type.String({ maxLength: 51, description: 'Omit to inspect available checks and commands first' })) }),
+    async execute(_id, params, signal) {
+      try {
+        const result = await projectChecks({ ...params, name: params.name, signal });
+        return { ...textResult(result), isError: 'status' in result && result.status !== 'passed' };
+      } catch (error) { return failure(error); }
+    },
+  });
+  pi.registerTool({
+    name: 'project_evidence', label: 'Project evidence',
+    description: 'Read a bounded UTF-8 byte page of saved output by receipt id. Receipts are historical, not proof that current sources or environment still pass. Follow nextOffset; logs remain local and may contain project-sensitive data.',
+    parameters: Type.Object({ id: Type.String(), offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 4, maximum: 12000 })) }),
+    async execute(_id, params) {
+      try { return textResult(await evidence(params)); } catch (error) { return failure(error); }
+    },
+  });
+}

package/src/profiles.mjs

@@ -0,0 +1,21 @@
+// Small, explicit, offline checks. These do not stand for project-wide validation.
+export const profiles = [
+  {
+    name: 'dentai', sentinels: ['pnpm-workspace.yaml', 'apps/api/scripts/operational-diagnostics.node-test.mjs'],
+    checks: {
+      'ops-diagnostics': { description: 'Focused API operational-diagnostics tests; no production or paid provider calls', argv: ['node', '--test', 'apps/api/scripts/operational-diagnostics.node-test.mjs'], timeoutMs: 30000 },
+    },
+  },
+  {
+    name: 'genexus18mcp', sentinels: ['Genexus18MCP.sln', 'scripts/lint.test.js'],
+    checks: {
+      'lint-setup': { description: 'Offline lint setup regressions; no SDK, KB, SQL or Cloud calls', argv: ['node', '--test', 'scripts/lint.test.js'], timeoutMs: 30000 },
+    },
+  },
+  {
+    name: 'pi-ripwire', sentinels: ['src/core.mjs', 'test/core.test.mjs'],
+    checks: {
+      'core': { description: 'Offline integration and safety regressions', argv: ['node', '--test', 'test/core.test.mjs'], timeoutMs: 30000 },
+    },
+  },
+];