@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

package/dist/core/bash-classifier.js

@@ -1,26 +1,26 @@
 /**
- * Bash command classifier — Sprint α5.2 (ADR-0056 PR-PUGI-CLI-M1-GAP-B).
+ * Bash command classifier — Sprint .
  *
  * Splits a shell command into a 7-class taxonomy so the permission
  * engine can apply class-aware policy instead of the prior bool gate
  * (`destructiveBashPatterns ? deny : ask`).
  *
  * Design notes:
- *   - The classifier is a conservative pattern matcher, not a full
- *     bash AST parser. M2 will replace it with a real parser (see
- *     bash-security.md §4). For M1 the rules are explicit-substring +
- *     simple tokenization, which is good enough to gate every command
- *     the engine loop currently emits.
- *   - Compound commands (`a && b`, `a || b`, `a ; b`, `a | b`) are
- *     split on the four separators and every component is classified
- *     individually. The overall class is the most dangerous component.
- *   - The `destructive` patterns originally lived in
- *     `permission.ts::destructiveBashPatterns`. They are now the
- *     single source of truth here; `permission.ts` re-exports the
- *     hard-deny check through `classifyBash`.
- *   - The `unknown` class fires on parse failure (`eval`, deep
- *     `$(...)` nesting, `curl | sh` install pipes) so the permission
- *     engine can fail closed in interactive modes.
+ *  - The classifier is a conservative pattern matcher, not a full
+ *    bash AST parser. M2 will replace it with a real parser (see
+ *    bash-security.md §4). For M1 the rules are explicit-substring +
+ *    simple tokenization, which is good enough to gate every command
+ *    the engine loop currently emits.
+ *  - Compound commands (`a && b`, `a || b`, `a ; b`, `a | b`) are
+ *    split on the four separators and every component is classified
+ *    individually. The overall class is the most dangerous component.
+ *  - The `destructive` patterns originally lived in
+ *    `permission.ts::destructiveBashPatterns`. They are now the
+ *    single source of truth here; `permission.ts` re-exports the
+ *    hard-deny check through `classifyBash`.
+ *  - The `unknown` class fires on parse failure (`eval`, deep
+ *    `$(...)` nesting, `curl | sh` install pipes) so the permission
+ *    engine can fail closed in interactive modes.
  */
 /**
  * Class rank for worst-component reduction in compound commands.
@@ -34,7 +34,7 @@
  * still letting genuine `write_workspace`, `network`, `write_protected`
  * and `destructive` components win when they appear.
  *
- * Code Reviewer P0 retro 2026-05-24: previously `unknown: 0` meant
+ * Code Reviewer P0 retro: previously `unknown: 0` meant
  * `read` (rank 1) won over `unknown` (rank 0) in the worst-component
  * reduction. That bypassed the file-level promise of fail-closed on
  * parse failure.
@@ -119,6 +119,63 @@ const DESTRUCTIVE_PATTERNS = [
     // History destruction
     { pattern: 'history -c' },
     { pattern: ' >/dev/null 2>&1; rm' },
+    // ---------------------------------------------------------------
+    // Patterns ported from external utility (Apache-2.0)
+    // and `safety-guard.sh` BLOCKED_PATTERNS array. Upstream source:
+    //  external hooks/destructive-guard.sh (lines 7-13)
+    //  external hooks/safety-guard.sh      (lines 14-50)
+    // 
+    //
+    // The patterns below need word-boundary matching because their
+    // tokens (kill, halt, reboot, ...) appear as substrings of common
+    // unrelated words (skills, default, chrooted-rebooter, etc.).
+    // Substring `.includes` cannot express that — `regex` is required.
+    // ---------------------------------------------------------------
+    // Process termination — `kill`, `pkill`, `killall` at command head
+    // or after `sudo`. Matches `kill 1234`, `kill -9 $$`, `sudo killall
+    // node`, but NOT `skill issue` (no leading boundary) or
+    // `git commit -m "skill kill story"` (the kill is inside a quoted
+    // string — quote-aware split handled upstream; here we still need
+    // the boundary). Anchored to start-of-component or `sudo ` prefix.
+    {
+        pattern: 'kill',
+        regex: /^(?:sudo\s+)?(?:pkill|killall|kill)\b/,
+    },
+    // System power state — reboot / shutdown / halt / poweroff / init 0
+    // / init 6. External tooling matches these anywhere in the command; we
+    // tighten to start-of-component or `sudo ` prefix to avoid FPs on
+    // file paths or variable names containing the substring.
+    {
+        pattern: 'reboot',
+        regex: /^(?:sudo\s+)?reboot\b/,
+    },
+    {
+        pattern: 'shutdown',
+        regex: /^(?:sudo\s+)?shutdown\b/,
+    },
+    {
+        pattern: 'halt',
+        regex: /^(?:sudo\s+)?halt\b/,
+    },
+    {
+        pattern: 'poweroff',
+        regex: /^(?:sudo\s+)?poweroff\b/,
+    },
+    {
+        pattern: 'init 0',
+        regex: /^(?:sudo\s+)?init\s+0\b/,
+    },
+    {
+        pattern: 'init 6',
+        regex: /^(?:sudo\s+)?init\s+6\b/,
+    },
+    // `git clean -f` (without -dx) — External tooling lists this as destructive
+    // because it still deletes untracked files. Pugi previously only
+    // gated `git clean -fdx`; broaden to any `-f` variant.
+    {
+        pattern: 'git clean -f',
+        regex: /\bgit\s+clean\s+-[A-Za-z]*f/,
+    },
 ];
 /**
  * Compound separators. We split on `&&`, `||`, `;`, `|` to classify
@@ -133,7 +190,7 @@ const COMPOUND_SEPARATORS = /\s*(?:&&|\|\||;|\|)\s*/;
  * that script bodies passed to `awk`, `sed`, `perl`, `python -c` are
  * not mis-split when they contain bare `;` or `|` glyphs.
  *
- * Code Reviewer P0 retro 2026-05-24: a naive regex split on
+ * Code Reviewer P0 retro: a naive regex split on
  * `awk 'BEGIN { for (i=0;i<5000;i++) ... }'` produces 3 components
  * (the awk script header + two for-loop fragments) that get
  * classified as `unknown` each and — with the unknown:3 rank above
@@ -289,6 +346,93 @@ const BUILD_TEST_PREFIXES = [
     'tsc -p',
     'eslint',
     'prettier --check',
+    // P0 fix (#37 CRITICAL): customer-blocking gap surfaced
+    // during dogfood. Engine emitted `chmod +x build.sh`, `node script.js`,
+    // `python3 -m pytest`, `git status`, `pnpm build`, `docker ps`, etc.
+    // and the classifier returned `unknown` → permission matrix denied
+    // в bypassPermissions mode (which the customer expected to auto-allow
+    // basic dev tools). Customers could not run ANY real build/test/git
+    // workflow through Pugi.
+    //
+    // The prefixes below cover three classes of developer tooling that
+    // are always allowed in `auto`/`dontAsk`/`bypassPermissions` modes,
+    // `ask` in interactive modes, and `deny` in `plan` (read-only) mode:
+    //  - Language runtimes: `node`, `python`, `python3`, `ruby`, etc.
+    //  - Native build chains: `gcc`, `clang`, `cmake`, `rustc`, etc.
+    //  - Container/k8s read-class: `docker ps/inspect/logs`, `kubectl get`.
+    //
+    // Destructive variants are already gated upstream by DESTRUCTIVE_PATTERNS
+    // (e.g. `docker system prune`, `kubectl delete --all`). The first-token
+    // gate in classifyComponent runs THIS list before the unknown fallback.
+    //
+    // Language runtime invocations (first-token match, with or without args).
+    'node',
+    'python',
+    'python3',
+    'ruby',
+    'perl',
+    'php',
+    'deno',
+    'bun',
+    'tsx',
+    'ts-node',
+    // Native build chains.
+    'gcc',
+    'g++',
+    'clang',
+    'clang++',
+    'cmake',
+    'rustc',
+    'javac',
+    'java',
+    // Container/k8s read-class (the destructive subcommands are pre-empted
+    // by DESTRUCTIVE_PATTERNS: `docker system prune`, `kubectl delete --all`,
+    // `kubectl delete namespace`).
+    'docker ps',
+    'docker images',
+    'docker inspect',
+    'docker logs',
+    'docker version',
+    'docker info',
+    'docker exec',
+    'docker run',
+    'docker stop',
+    'docker start',
+    'docker restart',
+    'docker rm',
+    'docker rmi',
+    'docker build',
+    'docker tag',
+    'docker compose',
+    'docker-compose',
+    'kubectl get',
+    'kubectl describe',
+    'kubectl logs',
+    'kubectl exec',
+    'kubectl apply',
+    'kubectl create',
+    'kubectl rollout',
+    'kubectl port-forward',
+    'kubectl config',
+    // Git read+write surface (network ops already handled by NETWORK_PREFIXES;
+    // destructive ops `reset --hard`/`clean -fdx`/`push --force` blocked above).
+    // Note: WRITE_WORKSPACE_PREFIXES already covers `git commit/add/checkout/...`.
+    // These entries handle plain `git rev-list`, `git cherry-pick`, `git worktree`,
+    // `git submodule`, etc that customer scripts commonly invoke.
+    'git rev-list',
+    'git cherry-pick',
+    'git worktree',
+    'git submodule',
+    'git blame',
+    'git describe',
+    'git tag --list',
+    'git tag -l',
+    'git for-each-ref',
+    'git ls-remote',
+    // gh CLI (GitHub). `gh repo delete` / `gh release delete` reach into
+    // network operations but are non-destructive for the local workspace.
+    // Permission matrix asks before allowing in auto.
+    'gh',
 ];
 /** Single-token read-only commands. Argument-free entries match exact. */
 const READ_TOKENS = new Set([
@@ -327,6 +471,16 @@ const READ_TOKENS = new Set([
     'cut',
     'sort',
     'uniq',
+    // P0 fix (#37 CRITICAL): structured-data inspection tools
+    // are pure stdin/stdout transformers (no FS write, no network) when
+    // не paired с `>` redirection (the redirection branch above promotes
+    // к write_workspace independently). Common в dev scripts for parsing
+    // package.json, tsconfig.json, Helm values.yaml, etc.
+    // `tee` is INTENTIONALLY excluded — it writes by definition, even
+    // в protected paths (`tee /etc/...` is already in DESTRUCTIVE_PATTERNS).
+    'jq',
+    'yq',
+    'column',
 ]);
 const READ_PREFIXES = [
     'git status',
@@ -361,13 +515,23 @@ const WRITE_WORKSPACE_PREFIXES = [
     'git tag',
     'git rebase',
     'git merge',
+    // P0 fix (#37 CRITICAL): file-permission ops are common
+    // в build scripts (`chmod +x build.sh`, `chown $USER file`). The
+    // destructive variants (`chmod 777 /`, `chmod -R 777 /`, `chmod -R
+    // 777 ~`, `chown -R root /`, `chown -R / ...`) are pre-empted by
+    // DESTRUCTIVE_PATTERNS which runs BEFORE this list — safe to add
+    // here for the non-destructive path. detectProtectedWrite's `\bchmod\b`
+    // / `\bchown\b` regex also catches writes into protected paths
+    // regardless of this list.
+    'chmod ',
+    'chown ',
 ];
 /**
  * Protected-write triggers. If a command writes to any of these paths
  * the class is `write_protected` regardless of the operation type.
  *
  * Wildcards are handled as substring matches (e.g. `/.ssh/` matches
- * `~/.ssh/foo` and `/Users/x/.ssh/bar`).
+ * `~/.ssh/foo` and `[HOME]/USER/.ssh/bar`).
  */
 const PROTECTED_PATH_SUBSTRINGS = [
     '/.ssh/',
@@ -388,6 +552,40 @@ const PROTECTED_PATH_SUBSTRINGS = [
     '/usr/',
     '/var/',
 ];
+/**
+ * Protected basename triggers — files whose CONTENT must never leak
+ * through the bash surface, even when the literal path is workspace-
+ * local. Mirrors `permission.ts::protectedBasenames` and `.env.*`
+ * pattern so the read-tool gate (which fires on `read .env`) and the
+ * bash gate (which fires on `cat .env`) stay symmetric.
+ *
+ * P0 fix (Codex audit): before this list existed, the
+ * engine model could circumvent the `read` tool's `protectedTargetReason`
+ * check by emitting `bash cat .env` — the classifier saw `cat` (read
+ * token) + `.env` (not in PROTECTED_PATH_SUBSTRINGS) and returned class
+ * `read`, which the permission matrix allows under every mode. The
+ * `local-first-invariants` spec proved the leak: `pugi explain .env`
+ * surfaced `SECRET=should_never_leak` in the engine summary.
+ *
+ * Match shape: the substring must touch a `.` boundary (`/.env`,
+ * ` .env`, `.env\b`) or appear as the full token so a path like
+ * `apps/codeforge/file.env-template` (no real secret) does not
+ * over-trigger.
+ */
+const PROTECTED_BASENAME_PATTERNS = [
+    // `.env`, `.env.production`, `.env.local` — anywhere in the command.
+    // Boundary on the left is start/whitespace/quote/`/`, on the right
+    // start/whitespace/end/quote/`>`/`|`/`;`.
+    /(^|[\s'"\/=])\.env(\.[A-Za-z0-9_-]+)?($|[\s'"<>|;&])/,
+    // SSH key basenames (covers both `id_rsa` and `id_ed25519` even
+    // outside `~/.ssh/`). The `/.ssh/` substring above gates the
+    // directory case; this catches a key file copied to the workspace.
+    /(^|[\s'"\/])id_(rsa|ed25519|ecdsa|dsa)(\.pub)?($|[\s'"<>|;&])/,
+    // Other credential basenames mirrored from permission.ts.
+    /(^|[\s'"\/])\.npmrc($|[\s'"<>|;&])/,
+    /(^|[\s'"\/])\.pypirc($|[\s'"<>|;&])/,
+    /(^|[\s'"\/])\.gitconfig($|[\s'"<>|;&])/,
+];
 /**
  * Obfuscation triggers — any of these forces the `unknown` class so
  * the permission engine can fail closed.
@@ -400,16 +598,16 @@ const OBFUSCATION_TRIGGERS = [
  * Classify a single (non-compound) command component.
  *
  * Order of checks (most-specific first):
- *   1. destructive substring (hard deny path)
- *   2. obfuscation (curl|sh, deep $() nesting, raw eval)
- *   3. cd-escape (covered by classifyBash for the overall command;
- *      single-component cd is handled here too)
- *   4. protected-write (redirection or write op into a protected path)
- *   5. write_workspace (mkdir/touch/cp/mv/git-write etc)
- *   6. network (curl/wget/ssh/installers)
- *   7. build_test (pnpm test, cargo build, ...)
- *   8. read (pwd, ls, cat, ...)
- *   9. unknown (default)
+ *  1. destructive substring (hard deny path)
+ *  2. obfuscation (curl|sh, deep $() nesting, raw eval)
+ *  3. cd-escape (covered by classifyBash for the overall command;
+ *     single-component cd is handled here too)
+ *  4. protected-write (redirection or write op into a protected path)
+ *  5. write_workspace (mkdir/touch/cp/mv/git-write etc)
+ *  6. network (curl/wget/ssh/installers)
+ *  7. build_test (pnpm test, cargo build, ...)
+ *  8. read (pwd, ls, cat, ...)
+ *  9. unknown (default)
  */
 function classifyComponent(cmd, ctx) {
     const trimmed = cmd.trim();
@@ -459,7 +657,7 @@ function classifyComponent(cmd, ctx) {
     // `cat ~/.ssh/id_ed25519` still win when matched (they run before
     // this check).
     //
-    // Code Reviewer P0 retro 2026-05-24: previously these reads fell
+    // Code Reviewer P0 retro: previously these reads fell
     // through to READ_TOKENS and were allowed in every mode.
     const protectedRead = detectProtectedRead(trimmed);
     if (protectedRead) {
@@ -469,6 +667,26 @@ function classifyComponent(cmd, ctx) {
             matched: protectedRead.matched,
         };
     }
+    // 4a-bis. Parent-traversal in read arguments. The file-tools layer
+    // refuses `..` segments via `resolveWorkspacePath`, but the bash
+    // surface had no equivalent gate — the engine could emit
+    // `cat ../README.md` or `ls ..` to enumerate / read outside the
+    // workspace, sidestepping the path-security check that the `read`
+    // and `glob` tools enforce.
+    //
+    // P0 fix (Codex audit): treat `..` as a path segment
+    // (`../`, ` ..`, `..\n`) in any read-class command as a workspace
+    // escape. We classify it as `write_protected` so the auto/dontAsk
+    // modes refuse, mirroring the `Path escapes workspace` semantics
+    // the file-tools layer already provides.
+    const traversal = detectParentTraversalRead(trimmed);
+    if (traversal) {
+        return {
+            class: 'write_protected',
+            reason: traversal.reason,
+            matched: traversal.matched,
+        };
+    }
     // 4b. .env writes are always protected, even inside the workspace
     // (CEO directive feedback_never_delete_untracked_env.md).
     const envWrite = detectEnvWrite(trimmed);
@@ -525,6 +743,25 @@ function classifyComponent(cmd, ctx) {
     if (trimmed === 'make' || trimmed.startsWith('make ')) {
         return { class: 'build_test', reason: 'make runner', matched: 'make' };
     }
+    // 7c. Operator-override safe tokens (P0 fix #37).
+    // `PUGI_CLASSIFIER_EXTRA_SAFE=tool1,tool2,...` extends the BUILD_TEST
+    // first-token list at runtime. This is a security-sensitive escape
+    // hatch — operators can add their custom build tools without a
+    // recompile. Destructive patterns ALREADY ran above (step 1) so this
+    // cannot whitelist `rm`, `mkfs`, `git push --force`, etc. The match
+    // is strict first-token equality — not substring — and the env var
+    // is read fresh on every classify call so tests can mutate it.
+    const extraSafe = readExtraSafeTokens();
+    if (extraSafe.size > 0) {
+        const firstTokenForExtraSafe = trimmed.split(/\s+/)[0] ?? '';
+        if (extraSafe.has(firstTokenForExtraSafe)) {
+            return {
+                class: 'build_test',
+                reason: `PUGI_CLASSIFIER_EXTRA_SAFE override: ${firstTokenForExtraSafe}`,
+                matched: firstTokenForExtraSafe,
+            };
+        }
+    }
     // 7c. Bare `cd <path>` (inside workspace — the cwd-escape detector
     // upgrades the class to write_protected when the target is
     // outside). Standalone `cd` (HOME) is escape, also handled by the
@@ -568,7 +805,15 @@ function classifyComponent(cmd, ctx) {
 }
 function findDestructiveMatch(cmd) {
     const upper = cmd.toUpperCase();
-    for (const { pattern, caseInsensitive } of DESTRUCTIVE_PATTERNS) {
+    for (const { pattern, caseInsensitive, regex } of DESTRUCTIVE_PATTERNS) {
+        if (regex) {
+            // Word-boundary regex form (external-derived patterns). Match
+            // against the trimmed component so `^` anchors to command head,
+            // not surrounding whitespace from the compound split.
+            if (regex.test(cmd.trim()))
+                return pattern;
+            continue;
+        }
         if (caseInsensitive) {
             if (upper.includes(pattern))
                 return pattern;
@@ -637,14 +882,57 @@ function nestingDepth(cmd, open, close) {
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/**
+ * Operator-override safe tokens. Read from `PUGI_CLASSIFIER_EXTRA_SAFE`
+ * (comma-separated). Allows operators to extend the BUILD_TEST first-
+ * token list at runtime for site-specific tooling без recompile.
+ *
+ * Security note: destructive substring patterns run BEFORE this gate
+ * (step 1 in classifyComponent), so this cannot whitelist `rm`, `mkfs`,
+ * `git push --force`, etc. The env var only adds tools to the benign
+ * build_test class. Invalid entries (empty strings, тokens containing
+ * shell metas) are silently dropped to avoid surprising classifications.
+ *
+ * Read fresh on every call so per-test mutations work и so operators
+ * can update without restarting the agent loop. The cost (one env var
+ * read + Set construction per call) is negligible for the classifier's
+ * call frequency.
+ */
+function readExtraSafeTokens() {
+    const raw = process.env.PUGI_CLASSIFIER_EXTRA_SAFE;
+    if (!raw || raw.trim() === '')
+        return new Set();
+    const tokens = new Set();
+    for (const candidate of raw.split(',')) {
+        const trimmed = candidate.trim();
+        if (trimmed === '')
+            continue;
+        // Reject anything containing shell metas or whitespace — only bare
+        // tool names allowed. Defends against accidental
+        // `PUGI_CLASSIFIER_EXTRA_SAFE='rm -rf /'` smuggling.
+        if (/[\s;|&<>$`(){}\[\]'"\\]/.test(trimmed))
+            continue;
+        tokens.add(trimmed);
+    }
+    return tokens;
+}
 function detectProtectedWrite(cmd, ctx) {
     // Surface every write target this command produces so we can both
     // protected-path-check and outside-workspace-check them uniformly.
     // Captures `sort -o`, `uniq <in> <out>`, `sed -i` files, `awk '... > "file"'`,
     // and `>` / `>>` redirections without surrounding whitespace.
     const writeTargets = extractWriteTargets(cmd);
+    // Strip heredoc bodies before substring scan. Heredoc payloads are
+    // DATA (file contents the script writes), not commands the shell
+    // executes — a `package.json` body containing `/usr/local/bin/...`
+    // would FP as "Write into protected path: /usr/" under the broad
+    // includes() scan below. The per-target check at the bottom of this
+    // function still catches real `cat > /usr/file << EOF` attempts
+    // because extractWriteTargets reads the redirection target, not the
+    // heredoc body. CEO dogfood (#28 follow-up).
+    const cmdForScan = stripHeredocBodies(cmd);
     for (const needle of PROTECTED_PATH_SUBSTRINGS) {
-        if (!cmd.includes(needle))
+        if (!cmdForScan.includes(needle))
             continue;
         // Reading from a protected path is allowed at the classifier
         // layer (the permission engine still gates `read`); writing is
@@ -695,17 +983,67 @@ function detectProtectedWrite(cmd, ctx) {
 }
 /**
  * Extract every write-target path the command produces. Covers:
- *   - shell redirection `> file`, `>> file` (with optional whitespace,
- *     skipping `>&1`, `>&2`, etc.)
- *   - `sort -o file`
- *   - `uniq <input> <output>` (the two-arg form)
- *   - `sed -i <file>...` (in-place edit treats every trailing file as a
- *     write target)
- *   - `awk '... > "file"'` (quoted redirection inside an awk script)
+ *  - shell redirection `> file`, `>> file` (with optional whitespace,
+ *    skipping `>&1`, `>&2`, etc.)
+ *  - `sort -o file`
+ *  - `uniq <input> <output>` (the two-arg form)
+ *  - `sed -i <file>...` (in-place edit treats every trailing file as a
+ *    write target)
+ *  - `awk '... > "file"'` (quoted redirection inside an awk script)
  *
  * Conservative — we do not try to resolve shell vars or globs; the
  * caller still gates absolute paths via `looksAbsoluteOutsideWorkspace`.
  */
+/**
+ * Strip heredoc bodies so substring scans (e.g. `cmd.includes('/usr/')`)
+ * do not false-positive on file content the script is *writing*. A
+ * heredoc starts с `<< 'WORD'` (or `<< WORD` / `<<-WORD`) and ends на a
+ * line containing only WORD. The body between is DATA, not commands.
+ *
+ * Best-effort: handles single-heredoc-per-command (the common case)
+ * AND multiple sequential heredocs. Nested heredocs (heredoc-inside-
+ * heredoc) are rare and out of scope — the substring scan still gates
+ * the outer command, just без stripping the nested body. Per-target
+ * detection at detectProtectedWrite's tail loop catches real
+ * `cat > /usr/file << EOF` attacks regardless of body content.
+ *
+ * CEO dogfood : `cat > package.json << 'EOF'\n{"bin":
+ * "/usr/local/bin/foo"}\nEOF` was rejected as "Write into protected
+ * path: /usr/" because the broad substring scan saw `/usr/` in the
+ * JSON body. With heredoc-body stripping, the scan now sees only
+ * `cat > package.json << 'EOF' EOF` which contains no protected path.
+ */
+function stripHeredocBodies(cmd) {
+    // Match `<< [-]'WORD'` or `<< [-]"WORD"` or `<< [-]WORD` (quoted form
+    // disables variable expansion in real bash; we treat all three the
+    // same for stripping). Capture the WORD so we can find the close
+    // marker.
+    const heredocStart = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+    let out = cmd;
+    let safetyLoops = 0;
+    let match;
+    while ((match = heredocStart.exec(out)) !== null) {
+        if (++safetyLoops > 16)
+            break;
+        const word = match[2];
+        if (!word)
+            continue;
+        const headEnd = match.index + match[0].length;
+        // Find the close-marker line: `\n<optional indent>WORD<\n|$>`.
+        const closeRegex = new RegExp(`\\n\\s*${word}(?:\\n|$)`);
+        closeRegex.lastIndex = headEnd;
+        const closeMatch = closeRegex.exec(out.slice(headEnd));
+        if (!closeMatch)
+            break;
+        const closeStart = headEnd + closeMatch.index;
+        const closeEnd = closeStart + closeMatch[0].length;
+        // Replace heredoc body + close marker с single space so the regex
+        // iterator's lastIndex stays meaningful.
+        out = out.slice(0, headEnd) + ' ' + out.slice(closeEnd);
+        heredocStart.lastIndex = headEnd + 1;
+    }
+    return out;
+}
 function extractWriteTargets(cmd) {
     const targets = [];
     // Shell redirection (`>`, `>>`) with optional whitespace. Skip
@@ -777,14 +1115,72 @@ function detectProtectedRead(cmd) {
         firstToken === 'find';
     if (!isReadTool)
         return null;
+    // Strip heredoc bodies so `cat > config << 'EOF'\n... /etc/... \nEOF`
+    // does not FP as "Read from protected path" when first-token=`cat` +
+    // redirection writes к workspace-local file. Heredoc payload is data.
+    // CEO dogfood .
+    const cmdForScan = stripHeredocBodies(cmd);
     for (const needle of PROTECTED_PATH_SUBSTRINGS) {
-        if (cmd.includes(needle)) {
+        if (cmdForScan.includes(needle)) {
             return {
                 reason: `Read from protected path: ${needle}`,
                 matched: needle,
             };
         }
     }
+    // P0 fix: extend protected-read detection to credential
+    // basenames (`cat .env`, `head id_rsa`, `grep TOKEN .env.production`).
+    // Without this branch, the engine model can bypass the `read` tool's
+    // `protectedTargetReason` gate by emitting a bash `cat` — the read
+    // tool refuses, the model falls back to bash, and the classifier
+    // (which only knew about full-path substrings) classified `cat .env`
+    // as benign `read`. The `local-first-invariants` spec proved the leak.
+    for (const pattern of PROTECTED_BASENAME_PATTERNS) {
+        const match = cmd.match(pattern);
+        if (match) {
+            return {
+                reason: `Read from protected basename: ${match[0].trim()}`,
+                matched: match[0].trim(),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Detect parent-traversal segments (`..`) inside read-class commands.
+ * The file-tools layer (`resolveWorkspacePath`) refuses these for the
+ * `read`/`glob`/`grep` tools, but bash had no equivalent gate. We
+ * trigger on the SAME shape `path-security.ts` rejects: a `..` segment
+ * separated by `/` or whitespace. Quoted/escaped variants get the same
+ * treatment.
+ *
+ * Returns null on the safe path (no `..` segment) so the caller falls
+ * through to the regular read classification.
+ */
+function detectParentTraversalRead(cmd) {
+    const firstToken = cmd.split(/\s+/)[0] ?? '';
+    const isReadTool = READ_TOKENS.has(firstToken) ||
+        READ_PREFIX_TOKENS.has(firstToken) ||
+        firstToken === 'sed' ||
+        firstToken === 'awk' ||
+        firstToken === 'find';
+    if (!isReadTool)
+        return null;
+    // Match `..` as a path segment: preceded by start/whitespace/quote/`/`
+    // and followed by `/`, end-of-string, whitespace, or shell metas.
+    // Avoids over-matching `v1..v2` (range syntax inside a single token)
+    // and `1..5` (numeric ranges) because those lack the path boundary.
+    const traversalPattern = /(^|[\s'"\/])\.\.(\/|$|[\s'"<>|;&])/;
+    const m = cmd.match(traversalPattern);
+    if (m) {
+        return {
+            reason: 'Read command escapes workspace via parent traversal',
+            matched: '..',
+        };
+    }
+    // Absolute path read of /etc, /usr, /var, etc is already covered by
+    // PROTECTED_PATH_SUBSTRINGS in detectProtectedRead — no extra branch
+    // needed here.
     return null;
 }
 function detectEnvWrite(cmd) {