@tduyng/pi-guard 0.0.2 → 0.0.4

package/README.md

@@ -1,85 +1,72 @@
 # @tduyng/pi-guard
 
-Four safety guards for pi: path reservations between parallel sessions, secret redaction on read results, git hook enforcement, and unhandled rejection handling.
+Four guards for the ways a session ends badly. Three are hooks and spawn no schema, so a session that never needs them pays nothing.
 
-## Reserve
+| Guard | Failure it prevents |
+| --- | --- |
+| `reserve` | A peer session edits a file this session is working on |
+| `cloak` | A key file lands in the transcript and goes to the provider |
+| `git-interceptor` | Git opens an editor and hangs the turn, or `--no-verify` skips a hook |
+| `reject-guard` | One unhandled promise takes down the session |
 
-Pi serializes writes inside one process, so two sessions in one folder still overwrite each other. This guard is the cross-session half. A session records what it holds in `.pi/reservations/<session>.json`, and a `tool_call` hook refuses `edit` and `write` against a path a live peer holds.
+Only sessions that load `reserve` pay for it, at 215 tokens.
 
-Reserving `extensions/pi-goal/src/` takes the whole subtree and an exact path takes one file, while `release` with no paths gives everything back and `list` prints every live session with what it holds.
+## Sessions in one folder
 
-Liveness is `process.kill(pid, 0)`, so a session that is killed takes its reservations with it. Nothing to keep alive, no heartbeat, no daemon.
+Pi serializes writes inside one process. Two sessions in one folder do not see each other, so the second overwrites a file the first is halfway through reshaping.
 
-Reservations cover files, and `bash` is checked too: a command that writes a reserved path is
-turned away, whether it says `sed -i`, `git checkout`, or redirects into it. A command that only
-reads a reserved path is left alone. What this cannot see is a mutation that names no path at
-all, so `git add -A` and a bare `git commit` still take whatever is staged. Two sessions
-committing in one repo also race on `.git/index.lock`, and no reservation covers that. Delegate
-the commit with `isolation: "worktree"` on `subagent`, which works in a
-checkout of its own. The branch is named in the result and its commits outlive the checkout.
+A session writes what it holds to `.pi/reservations/<session>.json`. A `tool_call` hook refuses `edit` and `write` against a path a live peer holds, and it checks `bash` too, so `sed -i`, `git checkout` and a redirect into a reserved path are turned away while a read-only command passes.
 
-## Cloak: secret redaction
-
-A `tool_result` hook intercepts `read` tool results and redacts secrets before they enter the model's context. Three independent checks, all configurable:
-
-### Vendor key detection
-
-Matches known API key shapes by fixed literal prefix. No entropy or shape scanning. Each prefix has a word boundary check so a substring inside a longer identifier does not false-positive. Patterns:
-
-- `AKIA` and `ASIA` (AWS access keys)
-- `sk-` (OpenAI/Anthropic)
-- `sk_live_` and `sk_test_` (Stripe)
-- `ghp_`, `gho_`, `ghs_`, `ghr_`, `github_pat_` (GitHub)
-- `eyJ` (JWTs, three-part base64 structure)
-- `xoxb-`, `xoxp-`, `xoxa-`, `xoxr-`, `xoxs-` (Slack)
-- `glpat-` (GitLab)
-- `AIza` (Google)
-- `npm_` (npm)
-- `SG.` (SendGrid)
-- `Bearer` followed by a token
-
-Each match is replaced with a marker: the first 4 characters plus stars (minimum 8, maximum 20) plus `[REDACTED:type]`.
-
-### PEM block detection
+```text
+reserve({action: "reserve", paths: ["extensions/pi-goal/src/"]})
+reserve({action: "list"})
+reserve({action: "release"})
+```
 
-Matches `-----BEGIN ...-----` certificate and key blocks. Replaced with `[REDACTED:PEM TYPE]`.
+A directory reserves its whole subtree, an exact path reserves one file, and `release` with no paths gives everything back. The refusal names the holder, so the other session is one that can be inspected.
 
-### Sensitive file types
+Liveness is `process.kill(pid, 0)`, so a killed session takes its reservations with it. No heartbeat and no daemon. Writes go through a temp file and a rename, so two sessions reserving at once cannot leave a half-written file.
 
-If the file path matches a sensitive pattern, the entire read is replaced with a single marker like `[REDACTED:Protected File (SSH Key)]`. Each pattern carries a type label used in the marker. Patterns include `.pem` (PEM File), `.crt` and `.cer` (Certificate File), `.p12` and `.pfx` (PKCS12 File), `.ssh/id_rsa`, `.ssh/id_ed25519`, `.ssh/id_ecdsa`, and `.ssh/id_dsa` (SSH Key), `.ssh/known_hosts` (SSH Known Hosts), `.ssh/authorized_keys` (SSH Authorized Keys), `.aws/credentials` (AWS Credentials), `.npmrc` (npm Config), `.pypirc` (PyPI Config), `.netrc` (Netrc File), `.docker/config.json` (Docker Config), `.kube/config` (Kube Config).
+A mutation that names no path is invisible to this, so `git add -A` and a bare `git commit` still take whatever is staged. Two sessions committing in one repository also race on `.git/index.lock`, and no reservation covers that. Commit from a `subagent` with `isolation: "worktree"` instead, whose checkout is its own.
 
-### Custom patterns
+## Secrets in the transcript
 
-Place a `cloak.json` in the agent directory (`getAgentDir()`) or in a project's `.pi/cloak.json` to add your own rules. A project file overrides the scalar keys and appends its `patterns` to the agent dir ones. Keys:
+A `tool_result` hook cleans `read` results on their way into the model. Three checks, each switchable:
 
-- `enabled` (boolean, default `true`): master switch.
-- `cloakCharacter` (string, default `*`): masking character.
-- `cloakLength` (number or null): fixed replacement length. Null preserves original length.
-- `tryAllPatterns` (boolean, default `true`): apply all matching rules, not just the first.
-- `patterns` (array): custom rules with `filePattern` (glob), `cloakPattern` (regex), and optional `replace`.
-- `vendorKeys` (boolean, default `true`): built-in vendor prefix detection.
-- `pemBlocks` (boolean, default `true`): PEM block detection.
-- `sensitiveFileTypes` (boolean, default `true`): whole-file redaction for sensitive paths.
+| Check | Catches | Replacement |
+| --- | --- | --- |
+| Vendor keys | AWS, OpenAI, Anthropic, Stripe, GitHub, Slack, GitLab, Google, npm, SendGrid, JWTs, `Bearer` | First 4 characters, stars, `[REDACTED:type]` |
+| PEM blocks | `-----BEGIN ...-----` certificates and keys | `[REDACTED:PEM TYPE]` |
+| Sensitive paths | `.pem`, `.crt`, `.p12`, SSH keys, `.aws/credentials`, `.npmrc`, `.netrc`, `.docker/config.json`, `.kube/config` | The whole read becomes `[REDACTED:Protected File (...)]` |
 
-When multiple patterns overlap the same span, the first applied match wins and later matches overlapping that span are skipped.
+Secrets have known prefixes, so `AKIA`, `sk-`, `ghp_`, `glpat-`, `xoxb-`, `AIza` and a dozen more are matched as literals with a word boundary. An earlier version scanned by entropy and flagged nix store hashes and `sha256` digests in derivations, so that check is gone.
 
-Use `/cloak-status` to see whether cloak is enabled, how many custom patterns are loaded, and which built-in checks are on.
+Custom rules go in `<agent-dir>/cloak.json` or `.pi/cloak.json`. A project file overrides the scalar keys and appends its `patterns`.
 
-### What cloak does not do
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch |
+| `cloakCharacter` | `*` | Masking character |
+| `cloakLength` | `null` | Fixed replacement length, null keeps the original |
+| `tryAllPatterns` | `true` | Apply every matching rule, not just the first |
+| `patterns` | `[]` | Rules with `filePattern` (glob), `cloakPattern` (regex), optional `replace` |
+| `vendorKeys` | `true` | Built-in prefix detection |
+| `pemBlocks` | `true` | PEM detection |
+| `sensitiveFileTypes` | `true` | Whole-file redaction |
 
-The extension does not scan by entropy or shape. A nix store hash, a `narHash` field, or a sha256 digest in a Nix derivation will not false-positive. The hook does not touch the outbound provider payload, the assistant's reply, or tools other than `read`. For files matching custom `patterns`, only the matched spans are replaced. Sensitive file types replace the entire read.
+When two matches overlap, the first rule applied wins. A custom pattern replaces only its matched spans, while a sensitive file type replaces the whole read. `/cloak-status` shows whether cloak is on, how many custom patterns loaded, and which built-in checks are active.
 
-## Git interceptor
+## Git in a non-interactive turn
 
-Two guards for agent-driven git commands:
+`GIT_EDITOR=true`, `GIT_SEQUENCE_EDITOR=true` and `GIT_MERGE_AUTOEDIT=no` go on `process.env`. Pi builds a child's environment by spreading `process.env`, so one assignment covers the bash tool, `bg`, and every other spawn.
 
-**Editor hang prevention**: sets `GIT_EDITOR=true`, `GIT_SEQUENCE_EDITOR=true`, and `GIT_MERGE_AUTOEDIT=no` on `process.env`. Pi builds a child's env by spreading `process.env`, so this one assignment covers the bash tool, `bg`, and any other spawn. Git never spawns an interactive editor.
+The extension blocks a bash command containing `--no-verify`, because the agent should fix what the hook complains about or ask. The check is string matching, best effort, and not a security boundary.
 
-**Hook bypass prevention**: blocks any bash command containing `--no-verify`. The agent should fix the underlying issue causing the hook to fail, or ask the human for help. This is string matching, best-effort, not a security boundary.
+## The rejection that kills a session
 
-## Reject guard
+Pi installs an `uncaughtException` handler and no `unhandledRejection` handler, so one unhandled rejected promise tears down the session. The guard adds the missing listener, logs the reason with a stack trace to stderr prefixed `[reject-guard] unhandled rejection (session kept alive):`, and the turn continues.
 
-Pi registers an `uncaughtException` handler but no `unhandledRejection` handler. An unhandled rejected promise tears down the whole session. This guard adds an `unhandledRejection` listener that logs the rejection reason (with stack trace when available) to stderr and keeps the session alive. The log line starts with `[reject-guard] unhandled rejection (session kept alive):`. The listener installs once. A `/reload` re-evaluates the module, and an install flag on `globalThis` keeps a second registration from logging every rejection twice.
+It installs once. `/reload` re-evaluates the module, and a flag on `globalThis` stops a second registration from logging every rejection twice.
 
 ## Install
 
@@ -89,6 +76,10 @@ pi install npm:@tduyng/pi-guard
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-guard`
 
-## Configure
+All four guards activate on install. Add `cloak.json` when a rule fires too widely or misses a secret shape.
+
+## Limits
 
-No configuration required. All four guards activate on install. Customize redaction via `cloak.json` as described above.
+- Cloak reads the `read` result on its way into the model. It does not touch the outbound provider payload, the assistant's reply, or any tool other than `read`, and it does not redact a file pasted into a prompt.
+- A reservation is advisory between pi sessions. A shell opened by hand is outside it.
+- `--no-verify` blocking can be worked around by anyone who wants to.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-guard",
-  "version": "0.0.2",
-  "description": "Four guards: keep parallel pi sessions off each other's files, redact secrets out of read results, keep a stray rejected promise from killing the session, and stop git from hanging on an editor or skipping hooks.",
+  "version": "0.0.4",
+  "description": "Secret redaction, cross-session path reservations, git safety, and a rejection guard. Three of the four add no schema at all.",
   "keywords": [
     "pi",
     "pi-package",