@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/extensions/bash-guard.d.ts

@@ -0,0 +1,467 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+/**
+ * Read-only programs a review session may run directly.
+ *
+ * **`awk` is deliberately ABSENT, and must not be re-added.** No regex gating
+ * of awk is sound: it is a programming language in which `system(x)`,
+ * `x | getline`, `print | x` and `print > x` are all first-class and every one
+ * takes an ARBITRARY EXPRESSION, so a bare identifier holding the command
+ * defeats any rule keyed on the token after the operator. VERIFIED executing:
+ *
+ *     awk 'BEGIN{c="sh"; print "<cmd>" | c}'        → ran <cmd>
+ *     awk 'BEGIN{f="<path>"; print "x" > f}'        → wrote <path>
+ *     awk 'BEGIN{f=".git/config"; printf … >> f}'   → then a plain `git diff` ran <cmd>
+ *
+ * The first is arbitrary execution with no config file touched, so the
+ * round-boundary integrity check cannot see it either.
+ *
+ * The cost is close to zero: `awk` appears in no prompt, no agent and no
+ * session-sanctioned script. A reviewer keeps `rg`, `grep`, `jq`, `cut`,
+ * `sort`, `uniq`, `head`, `tail`, `wc`, `nl`, `tr` and `sed -n`; `gawk`,
+ * `mawk` and `nawk` are off ALLOWED too.
+ *
+ * `sed` stays, on a narrower argument: its script language is small and
+ * fixed — its file/exec verbs are the `e`/`w`/`W`/`r`/`R` commands and the
+ * `e`/`w` flags of `s` — so `checkSedInvocation` PARSES every invocation
+ * (options, addresses, any `s` delimiter) and refuses anything it cannot
+ * classify. awk's language takes an expression anywhere; sed's does not.
+ *
+ * Exported in ORDER because the sentence every built pass reads ("Allowed
+ * commands: …", `packages/pi-plugin/src/include.ts`) is rendered from this array: a model told a
+ * tool exists and then refused reads the refusal as a malfunction, so the
+ * enforcing half is the only author of the advertised half;
+ * `tests/fences.test.ts` holds the advertised set equal to this array, runs
+ * every advertised program through `checkBashCommand` (from source), and
+ * separately checks the rendered sentence against `packages/pi-plugin/dist/src/include.js`.
+ */
+export declare const ALLOWED_PROGRAMS: readonly string[];
+export interface BashCheck {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * What the guard's policy is judged against, resolved: the sandbox root that
+ * owns the sanctioned script bytes, whether this is a regression replay
+ * session, and the secrets dirs. `createBashGuard` builds one from its config
+ * at construction; the exported pure checkers take one as an argument, and
+ * `extensions/cli/bash-guard-ambient.ts` supplies the process-derived one.
+ */
+export interface GuardPolicy {
+    sandboxRoot: string;
+    /** The cwd the secret and /proc belts resolve a relative word against when a
+     * `cd` has made the command's own cwd unknown. */
+    cwd: string;
+    /** A regression replay session (src/replay.ts), spawned with `QCR_REPLAY=1`
+     * on its pi's own environment, which no bash command can change. It posts
+     * nothing and reads nothing from GitHub, so no sandbox script is sanctioned
+     * in it at all: the relative-spelling rule alone was reachable by
+     * `cd <sandbox root> && bash scripts/post-review.sh …`. */
+    replay: boolean;
+    /** A takeover (`QCR_TAKEOVER=1` on its pi's own environment, which no bash
+     * command can change): the operator works in the PR's real session and nothing
+     * is posted from it. The scripts that post are not sanctioned there; the
+     * reading ones are. The daemon refuses a takeover's posts as well. */
+    noPost: boolean;
+    /** The secret-path context minus the cwd, which is per call. */
+    secrets: Omit<SecretPathContext, "cwd">;
+}
+interface ShellWords {
+    words: string[];
+    /** A quote was still open at the end of the text. On a segment produced by
+     * `splitShellSegments` that means the segment was CUT at a `$(` or backtick:
+     * the rest of the word is assembled at runtime by a substitution. */
+    unterminated: boolean;
+    /** A `$'…'` held an escape this function does not decode (`\x3b`, `\073`,
+     * `\u003b`): the words carry the escape's letters, not what bash would
+     * produce, so a payload built from them is not what bash runs. */
+    undecoded: boolean;
+}
+/**
+ * Split text into shell WORDS: quote-aware, DEQUOTED, split only on unquoted
+ * whitespace. `'…'`, `"…"` (with `\"` and `\\`), `$'…'` (ANSI-C: `\n`, `\t`,
+ * `\\`, `\'`, `\"`) and backslash escapes are all resolved, so what comes out
+ * is what bash would hand the program as argv. Unlike the whitespace re-split
+ * in `checkBashCommand`, this preserves separators (`;`, newline, `&&`) that
+ * live INSIDE a quoted word — which is exactly what a `bash -c` payload is.
+ */
+export declare function shellWords(s: string): ShellWords;
+/** Quote/substitution-aware segment splitter (a quote-blind split shreds
+ * `rg 'a|b'` on the quoted pipe and vets pattern fragments as programs). Rules:
+ *  - single quotes: everything inside is literal;
+ *  - double quotes: separators are literal, but `$(` and backticks still
+ *    execute, so they still split (quote state restored at the matching `)`);
+ *  - backslash escapes the next char (outside single quotes);
+ *  - unquoted `; & | && || newline ( )` split; `$(`/`)` track nesting so the
+ *    command FOLLOWING a substitution lands in its own segment and is vetted
+ *    (merging it back would let `A="$(cat x)" python3 e.py` through). */
+export declare function splitShellSegments(cmd: string): string[];
+/** The root-credential check, plus the App-secret belt below.
+ * Exported so the reason is testable on its own. extensions/cli/bash-guard-ambient.ts
+ * is the same call with `ctx` defaulted to this process's own cwd, home and
+ * secrets dirs. */
+export declare function checkSecretPaths(cmd: string, ctx: SecretPathContext): BashCheck;
+/**
+ * The App-secret belt — and what it is NOT.
+ *
+ * `cat` is a sanctioned reader, and a posted review body is a channel to
+ * GitHub, so without this a prompt-injected session could read
+ * `/opt/quickreview/secrets/app.pem` and publish the App's private key. This
+ * cheap interim belt refuses any session command, and any read/write tool
+ * call, that NAMES one of the App's secret files or the secrets dir itself.
+ *
+ * It is a SPELLING belt. Variable indirection (`d=/opt/quickreview/sec; cat
+ * ${d}rets/app.pem`), a recursive read of an ancestor (`grep -r . /opt`), a
+ * symlink, a file list fed to `xargs` — all of these still reach the files,
+ * and no amount of pattern work here closes that class. The real fix is that
+ * a session cannot read the dir at all: a uid or mount split. Until then this
+ * turns the obvious spellings into a loud refusal.
+ *
+ * The sanctioned scripts keep working because they read the secrets as
+ * SUBPROCESSES: `bash scripts/mint-token.sh` names no secret on the session's
+ * command line, and only that line is checked.
+ *
+ * How a word is judged — after quotes, backslashes and `$'…'` escapes are
+ * removed, `~`/`$HOME`/`$XDG_CONFIG_HOME`/`$QCR_INSTALL` expanded and `{a,b}`
+ * braces expanded:
+ *   · a path COMPONENT that is a secret file's name (`APP_SECRET_NAME_RE`);
+ *   · a spelling of a secrets dir on its own (`/opt/quickreview/secrets`,
+ *     `…/qcr/<install>/secrets`, the old `~/.config/quickreview-bot`);
+ *   · the word resolved against the cwd (a `cd` earlier in the same command
+ *     moves it) landing on, or inside, one of the resolved secrets dirs —
+ *     so `../secrets/app_id` from the sandbox root is caught;
+ *   · a GLOB that could expand to a secret path (`../secrets/*`,
+ *     `/opt/*` + `/s*` + `/*`), or one of whose components could match a
+ *     secret file's name with at least half of that name spelled literally
+ *     (`app.p*m`, `*.pem`, `openai*key` — but not `*`, `*key` or `*token`,
+ *     which would refuse ordinary reads).
+ * A grep/rg PATTERN and a sed SCRIPT are exempt (the first positional, or the
+ * value of `-e`): they read nothing, and a reviewer of code that handles
+ * secrets greps for `openai_api_key` as a matter of course.
+ */
+export interface SecretPathContext {
+    /** The directory a bare relative word resolves against (the session cwd). */
+    cwd: string;
+    /** For `~`, `$HOME`, `$XDG_CONFIG_HOME` and `$QCR_INSTALL` expansion. */
+    env: Readonly<Record<string, string | undefined>>;
+    /** Every secrets dir this install could be using, absolute, no trailing `/`. */
+    dirs: readonly string[];
+    /** The daemon's IPC run dirs (`<state>/run`: the socket, the capability launch
+     * files), absolute, no trailing `/`. Nothing under one is readable. */
+    runDirs?: readonly string[];
+}
+/** The in-container secrets mount (deploy/ansible entrypoint `SECRETS`). */
+export declare const CONTAINER_SECRETS_DIR = "/opt/quickreview/secrets";
+/** The files the secrets dir holds, by their shipped names
+ * (deploy/collect-secrets.sh, the src/config.ts defaults). */
+export declare const APP_SECRET_FILES: readonly string[];
+/**
+ * This process's secrets dirs — self-contained on purpose (no `src/` import):
+ * bash-guard is registered GLOBALLY on the VM and in the bench sandbox, and
+ * must load wherever pi finds it. Mirrors `locateSecrets` in src/install.ts:
+ * the container mount, `$QCR_SECRETS_MOUNT`, `$QC_SECRETS_DIR`,
+ * `<config home>/secrets` (including absolute `$QCR_CONFIG_HOME`), the legacy `~/.config/quickreview-bot`, and a
+ * `[github] secrets_dir` read best-effort from `$QCR_CONFIG`.
+ */
+export declare function defaultSecretPathContext(env: Readonly<Record<string, string | undefined>>, cwd: string): SecretPathContext;
+/** One expanded, unquoted word judged as a path. */
+export declare function judgeSecretPath(w: string, ctx: SecretPathContext): BashCheck;
+/**
+ * The file TOOLS' secret veto. pi's built-in `read` takes a `path` and
+ * resolves `~` and a leading `@` itself (VERIFIED against pi 1.0.0's
+ * dist/core/tools/read.js schema and path-utils.js `resolveToCwd`), so the
+ * judgement the bash belt applies to a word applies to that path — plus the
+ * OpenViking root-credential spellings.
+ */
+export declare function checkReadPath(path: string, c: SecretPathContext): BashCheck;
+/** One expanded word judged as a path. */
+export declare function judgeProcPath(w: string, cwd: string): BashCheck;
+/** Refuse a command that names `/proc/<pid>/{environ,mem,cmdline,fd,fdinfo}`. */
+export declare function checkProcSecrets(cmd: string, cwd: string): BashCheck;
+export declare function isGitConfigSurface(path: string): boolean;
+/**
+ * This system's OWN policy-carrying surface — the analogue of
+ * `isGitConfigSurface`, one level out. `isGitConfigSurface` protects the files
+ * that turn an ordinary GIT command into shell execution; this protects the
+ * files that decide what every layer of THIS boundary does. A review session
+ * READS code (scoping rule 2); it never writes any of these, so a write to one
+ * is always a reconfiguration of its own controls:
+ *
+ *   · `config.toml`           — the guards' and the gate's configuration. The
+ *     posting scripts read `dry_run` and every `[guards]` knob out of it per
+ *     invocation, and `guard_enabled` treats a knob as ON unless it is literally
+ *     `false`, so ONE write turns guards 1-5 off and flips a dry-run install to
+ *     live on the next sanctioned post — AGENTS.md invariant 6, by a redirection.
+ *   · `scripts/**`            — the sanctioned posting route (the shims that
+ *     hand over to the daemon). Overwriting one posts around it.
+ *   · `dist/**`               — the COMPILED artifacts the container actually
+ *     runs, `packages/pi-plugin/dist/extensions/bash-guard.js` among them: overwrite the compiled
+ *     guard and the boundary is off for every later round in that container.
+ *   · `extensions/**`         — the guard's own source and the other pi
+ *     extensions, which `deploy.sh sync` ships and the build compiles.
+ *   · `prompts/**`, `agents/**`, `seeds/**` — the frozen seeds (rule 6); the
+ *     `agents/` rule also covers the BUILT `state/agents/**` pass bodies pi
+ *     loads each round (a `state/agents/…` path has `agents/` after a slash).
+ *   · `AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, `CLAUDE.MD`
+ *     — pi's project-context files. pi loads the FIRST of them it finds in the
+ *     cwd into EVERY session and pass it starts there (`loadContextFileFromDir`,
+ *     pi 0.87.1, unchanged at 0.99.1 and 1.0.0 — VERIFY-ON-PIN: the candidate list is pi's), and every session
+ *     and pass runs in the sandbox root. One write plants instructions in every
+ *     later session until the next deploy — the overseer's included.
+ *   · `.pi/**`                — pi's PROJECT resource dir: `settings.json`,
+ *     `extensions/`, `mcp.json` (pi 0.99+). Every project is trusted
+ *     (`defaultProjectTrust = "always"`, the no-stall decision), so a file
+ *     planted here loads into every later session and pass started in that
+ *     root: an extension runs as code, a `mcp.json` launches server processes,
+ *     and a `+builtin:mcp` in project settings re-enables what the global
+ *     settings switch off (packages/pi-plugin/src/pibuiltins.ts) — project entries override the
+ *     user's. As a SHAPE this also covers `<pi home>/.pi/agent/…`, the
+ *     session's own global pi settings and login; a session writes neither.
+ *
+ * The list is OURS, closed and documented (docs/exec-boundary.md), not a list
+ * of attacks. `POLICY_SURFACE_FILES` / `POLICY_SURFACE_DIRS` — top-level names
+ * RELATIVE TO THE SANDBOX ROOT — and `POLICY_SURFACE_PATHS` (whole paths under
+ * it) are the ONE definition three consumers read:
+ * the write/edit tool veto and the shell-redirection scan (both through
+ * `isPolicySurface`, as a path SHAPE: the name after any prefix, because the
+ * guard does not know the session's cwd) and layer 4's round-boundary
+ * integrity check (`policySurfaceWatchPaths` in src/execboundary.ts, as
+ * concrete paths under the root — the one layer that also sees the write no
+ * command string can show, `T=config.toml; cat p > $T`). Being a SHAPE, the
+ * write veto also refuses `scripts/…`, `dist/…` etc. inside the REVIEWED
+ * repo's worktree; a reviewer never writes there either (scoping rule 2).
+ * `state/agents/**` — the BUILT pass bodies — is refused at the write boundary
+ * through the `agents/` shape but deliberately NOT watched by layer 4: the
+ * daemon itself rebuilds it mid-round on feedback ingest and the day change.
+ */
+export declare const POLICY_SURFACE_FILES: readonly ["config.toml", "AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+export declare const POLICY_SURFACE_DIRS: readonly ["scripts", "dist", "extensions", "prompts", "agents", "seeds", ".pi"];
+/** Policy files named by their PATH under the sandbox root, not a bare name:
+ * the review core's export map decides which compiled guard and gate an
+ * `@quickchatai/pi-quickreview/...` import loads (every shim, every worker),
+ * while a package.json anywhere else is no policy at all. */
+export declare const POLICY_SURFACE_PATHS: readonly ["packages/pi-plugin/package.json"];
+/** Is this path part of this system's own policy surface? Exported so both
+ * boundaries ask ONE question — see `POLICY_SURFACE_RE`. */
+export declare function isPolicySurface(path: string): boolean;
+/**
+ * The MEMORY-SCOPE files — what decides how far a PR session's OWN memory
+ * recall may reach. The daemon publishes both into the session's pi home,
+ * beside its `ovcli.conf` (src/memory/ovsession.ts), and the vendored
+ * OpenViking extension reads them on every prompt:
+ *
+ *   · `recall-hints/<session>.json` — the RECALL HINT (`ovRecallHintPathIn`):
+ *     the round's query and the memory AREAS the session's recall and its
+ *     memory tools may reach (`experiences/` alone — vendored patches
+ *     0008/0009/0011). One write of `{"areas":["finding-cases","events"]}`
+ *     would widen the session's own scope to the finding cases and the
+ *     feedback events no round may read, until the daemon writes the hint
+ *     again at the next round.
+ *   · `retired-uris.json` — the RETIRED list (`ovRetiredPathIn`) the recall
+ *     excludes. Emptied, it brings retired entries back into every prompt's
+ *     recall.
+ *
+ * A review session READS memory and never writes either file; the daemon does,
+ * whole and atomically, every round. Matched as a SHAPE like the policy
+ * surface — the distinctive name under ANY prefix, because the guard does not
+ * know the pi home (and a `cd` into `.openviking/` drops that part of the
+ * spelling) — and NOT watched by layer 4: the daemon rewrites the hint at
+ * every round's dispatch, so a round-boundary hash would read its own work as
+ * a change (the `state/agents/**` reasoning). The write veto is the
+ * protection these files have.
+ */
+export declare const MEMORY_SCOPE_SURFACE: readonly ["recall-hints/", "retired-uris.json"];
+/** Is this path one of the memory-scope files a session's recall reads?
+ * Exported so both write boundaries ask ONE question. */
+export declare function isMemoryScopeSurface(path: string): boolean;
+/**
+ * The WAKE-DELIVERY files — the daemon's inject dirs
+ * (`<root>/inject/<session>/`, `PiSessionManager.injectDir`) and the inject
+ * bridge's record of what pi accepted. The bridge takes pending wakes in name
+ * order and moves each one pi accepts into `.done/`; the daemon reads that
+ * move as "this turn is now running" — above all for the overseer, whose
+ * Slack command rights are the served turn's (`src/slack/origin.ts`). One
+ * planted `.done/<queued wake>.md`, or a queued wake emptied in place (the
+ * bridge moves an empty file to `.done/` without serving it), would hand a
+ * running turn the rights of one still queued; a file dropped into another
+ * session's inject dir is a prompt in that session.
+ *
+ * A session never writes any of them; the daemon writes the wakes and the
+ * bridge moves them. Matched as a SHAPE: the `inject` dir and anything in it
+ * under any prefix, a `.done` dir and anything in it (a `cd` into the inject
+ * dir drops the `inject/` part), and the wake file's own name
+ * (`<ISO stamp>-<seq>[--cmd-<id>].md`, its atomic-write temp included — a `cd`
+ * into the session's dir drops every directory). Not watched by layer 4: the
+ * daemon and the bridge rewrite these dirs all the time, so a round-boundary
+ * hash would report their own work. The write veto is the protection, and a
+ * session has no program that moves or removes a file.
+ */
+export declare const DELIVERY_SURFACE: readonly ["inject/", ".done/", "<wake file>.md"];
+/** Is this path one of the wake-delivery files? Exported so both write
+ * boundaries ask ONE question. */
+export declare function isDeliverySurface(path: string): boolean;
+/** The full set a session may not write, from ONE definition: git's own config
+ * and hook surface, this system's policy surface, the memory-scope files its
+ * own recall reads and the wake-delivery files. Both the write/edit tool veto
+ * (`checkWritePath`) and the shell-redirection / sed scan
+ * (`checkProtectedWrites`) refuse exactly this, so they cannot drift. */
+export declare function isProtectedWriteTarget(path: string): boolean;
+/** The protected path a redirection-target PATTERN can expand onto, or null
+ * (also null for a target with no pattern syntax at all). */
+export declare function protectedPatternHit(target: string): string | null;
+/** Whether `text` opens ANSI-C (`$'…'`) or locale (`$"…"`) quoting — forms
+ * `dequote` does not decode. Only a `$` OUTSIDE quotes opens one: inside
+ * single or double quotes `$'`/`$"` is literal (`--jq 'test("x$")'`).
+ * Exported because `src/usage.ts` audits the same forms. */
+export declare function opensUnmodelledQuoting(text: string): boolean;
+/**
+ * Every spelling of an OUTPUT redirection, rewritten onto the canonical `>` /
+ * `>>` before anything else reads the command, so the write-target scan and
+ * the segment splitter both see one form. Exported because `src/usage.ts`
+ * borrows it the way it borrows `splitShellSegments` — the TOKENISER, not the
+ * policy. Bash has more of these than `>`:
+ *   · fd-dups (`2>&1`, `>&2`, `1>&-`) name no file and are dropped;
+ *   · `>&file`, `&>file`, `&>>file` write stdout+stderr to a FILE;
+ *   · `{v}>file` opens the file on a descriptor bash picks and stores in `v`;
+ *   · `<>file` opens read-write — `printf x 1<>config.toml` OVERWRITES it;
+ *   · `>|file` overrides noclobber.
+ * All five VERIFIED writing the target; a scan that knew only `>` and `>>`
+ * would miss each.
+ */
+export declare function normalizeRedirections(cmd: string): string;
+/**
+ * Shell redirections and `sed -i` whose target is a PROTECTED write surface —
+ * git's config/hook surface, this system's own policy surface (config.toml,
+ * scripts/, dist/, extensions/, prompts/agents/seeds, .pi/, the pi context
+ * files) or the memory-scope files a session's recall reads.
+ *
+ * The segment splitter deliberately skips redirection remnants when hunting for
+ * the program token, so `cat evil > config.toml` and `printf '…' > .git/config`
+ * both vet as an allowlisted program (`cat`/`printf`) and pass the per-segment
+ * check. That is right for finding the PROGRAM and wrong for finding the TARGET,
+ * so the target is asked about separately, over the raw command — the same shape
+ * `checkSecretPaths` already uses for the root-credential paths, and for the
+ * same reason: the path, not the program, is what distinguishes it. This is one
+ * of the TWO boundaries `isProtectedWriteTarget` binds; the other is the
+ * write/edit tool veto in `checkWritePath`, and both read the same predicate so
+ * they cannot drift apart.
+ *
+ * `tee`, `cp`, `mv` and `dd` are the other ways to write a named file, and they
+ * need no case here: none is on `ALLOWED`, so `checkProgram` refuses them
+ * outright whatever their target. `sort -o`, `find -fprintf` and `awk` are
+ * refused whole (reader-mode rules / off the allowlist), so they cannot reach a
+ * target either. `sed -i` is the one allowlisted writer that names its target as
+ * a plain argument rather than after a `>`; the reader-mode rules already refuse
+ * `sed -i` outright, so this scan is defense in depth for it. The
+ * redirection itself has more spellings than `>`/`>>` — see
+ * `normalizeRedirections`, which folds all of them onto those two first.
+ */
+export declare function checkProtectedWrites(cmd: string): BashCheck;
+/**
+ * The target of every UNQUOTED output redirection in a command (after
+ * `normalizeRedirections` has folded the spellings onto `>`/`>>`), each with
+ * its quoting removed as bash removes it — `$'…'` and `$"…"` included. A
+ * `>` inside single or double quotes, or escaped, is text, not an operator;
+ * one glued to the word before it (`x>file`) is an operator. Process
+ * substitution (`>(…)`) names no file and yields nothing. Exported because
+ * `src/usage.ts` borrows it the way it borrows `splitShellSegments` — the
+ * TOKENISER, not the policy.
+ */
+export declare function redirectTargets(cmd: string): string[];
+/** Pure policy check over a full bash command string: split into segments
+ * (quote-aware) and vet each segment's first program token. */
+export declare function checkBashCommand(cmd: string, depth: number, cwd: string | null, policy: GuardPolicy): BashCheck;
+/**
+ * sed, read as sed reads it. The regex rules above match spellings; sed's
+ * script language is small enough to PARSE, so the decision is made on the
+ * parse: every option is classified, every script is split into commands, and
+ * the guard allows only an invocation whose every part it understood and none
+ * of which writes, reads another file or runs a command. Fails closed: an
+ * option it does not know, an abbreviation it cannot resolve to one safe
+ * option, a script it cannot finish parsing, a script it cannot see (a
+ * `$`-expansion or a backtick in an argument; `xargs`, which can append
+ * options and scripts from stdin) are all refused.
+ *
+ * What it refuses inside a script: the `e`, `w`, `W`, `r` and `R` commands
+ * (run a command, write a file, read a file into the stream), at any address
+ * (`/re/`, `\cREc`, a number, `$`, `first~step`, `addr,+N`, negated with `!`);
+ * and an `s` command whose flags carry `e` (run the pattern space as a
+ * command) or `w` (write) — with ANY delimiter, flags in any order.
+ */
+export declare function checkSedInvocation(words: readonly string[]): string | null;
+/** The first command in a sed script that writes, reads a file or runs a
+ * command — or that the parser cannot classify — or null when every command
+ * is a plain stream edit. */
+export declare function sedScriptDanger(script: string): string | null;
+/** Shell words of a sed invocation's argument text, as bash will hand them to
+ * sed — or null when a word's value is not knowable from the text (a `$`
+ * expansion, ANSI-C or locale quoting, a backtick, an unclosed quote). */
+export declare function sedWords(text: string): string[] | null;
+/**
+ * Does this invocation of an allowlisted reader use one of its write/exec
+ * modes? Exported so the reason is testable on its own.
+ */
+export declare function checkReaderModes(prog: string, args: readonly string[], rawArgs?: readonly string[], rawText?: string): BashCheck;
+/**
+ * The write/edit tools' policy check. The write half of the two boundaries
+ * `isProtectedWriteTarget` binds — the other is the shell redirection /
+ * `sed -i` scan in `checkProtectedWrites`, and both read the same predicate so
+ * a session cannot write through one what it is refused through the other.
+ * Refuses git's config/hook surface, this system's own policy surface
+ * (config.toml, scripts/, dist/, extensions/, prompts/agents/seeds, .pi/, the
+ * pi context files) and the memory-scope files its recall reads (the recall
+ * hint, the retired list); everything else a session writes — the verdict file,
+ * the ledger, /tmp bodies — is allowed. This is not a write allowlist.
+ */
+export declare function checkWritePath(path: string): BashCheck;
+/**
+ * What one bash-guard needs, resolved: no env is read past this. Only these
+ * inputs are configurable. The policy itself (the program allowlist, the
+ * secret-path and /proc rules, the protected write surfaces) is code in this
+ * file, and the secrets dirs below are a FLOOR the guard adds the container's
+ * own mount to; no profile layer (packages/pi-plugin/src/profileoverrides.ts) reaches either, and
+ * the engine host builds this from the install, never from a profile.
+ */
+export interface BashGuardConfig {
+    /** The daemon-selected checkout that owns the sanctioned script bytes. */
+    sandboxRoot: string;
+    /** The cwd a tool call is judged from when pi's context names none. Omitted:
+     * the sandbox root. */
+    cwd?: string;
+    /** A regression replay session: no sandbox script is sanctioned at all. */
+    replay: boolean;
+    /** A takeover: the scripts that post are not sanctioned. Omitted: false. */
+    noPost?: boolean;
+    /** Every secrets dir this install could be using, absolute. The container
+     * mount (`CONTAINER_SECRETS_DIR`) is always added. */
+    secretDirs: readonly string[];
+    /** HOME, XDG_CONFIG_HOME and QCR_INSTALL, the variables a secrets path is
+     * spelled with in a command, plus QCR_IPC_SOCKET, which locates the IPC
+     * run dir. Unset falls back to the
+     * defaults `defaultSecretPathContext` uses. */
+    pathEnv?: Readonly<Record<string, string | undefined>>;
+}
+/** The three env-decoded guard inputs: the sandbox root (QCR_SANDBOX_ROOT, else
+ * the cwd), QCR_REPLAY and QCR_TAKEOVER. The one place the env is read for them. */
+export declare function guardFlagsFromEnv(env: Readonly<Record<string, string | undefined>>, cwd: string): {
+    sandboxRoot: string;
+    replay: boolean;
+    noPost: boolean;
+};
+/** The config the env describes: QCR_SANDBOX_ROOT (else the cwd), QCR_REPLAY,
+ * QCR_TAKEOVER, and the secrets dirs `defaultSecretPathContext` resolves from the same env. */
+export declare function bashGuardConfigFromEnv(env: Readonly<Record<string, string | undefined>>, cwd: string): BashGuardConfig;
+/**
+ * The factory a session loads: the guard over this config. A pi loaded by
+ * path gets it through the env shim, extensions/cli/bash-guard.ts, and an SDK
+ * session as this extension factory. VERIFIED (pi control-surface findings §5):
+ * a tool_call handler can return { block: true, reason } to veto the call, and
+ * event.input is mutable. pi 1.3.0 emits `{ type: "tool_call", toolName,
+ * toolCallId, input }` and its read/grep/find/ls tools take `path` (grep also
+ * `glob`).
+ * `toolName` and `input` on the event payload are seen in production (above).
+ * // VERIFY-ON-PIN: `path`/`file_path` on a file tool's input (following
+ * extensions/companion-guard.ts, which already vetoes writes this way).
+ */
+export declare function createBashGuard(config: BashGuardConfig): ExtensionFactory;
+export {};
+//# sourceMappingURL=bash-guard.d.ts.map

package/dist/extensions/bash-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-guard.d.ts","sourceRoot":"","sources":["../../extensions/bash-guard.ts"],"names":[],"mappings":"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"}