@litfamily/litgrok 1.0.0

package/.grok/skills/debugging/references/reproduction-recipes.md

@@ -0,0 +1,182 @@
+# Reproduction recipes
+
+Load these recipes when a PostToolUseFailure observation must be converted into a stable, safe experiment. Each recipe keeps one causal dimension fixed and names the evidence needed to distinguish outcomes.
+
+## Recipe 1 — Wrong working directory
+
+### Trigger
+
+A package command, relative path, or generated output is missing even though the repository appears to contain it.
+
+### Reproducer
+
+    1. Record event.cwd and event.workspaceRoot from the failed tool observation.
+    2. Resolve the intended product root using a read-only path/status check.
+    3. List the named package or target relative to both roots.
+    4. Run the narrow documented command from the intended root without changing inputs.
+
+### Expected evidence
+
+The original invocation, both resolved paths, and the second exit status. If changing only cwd changes failure to success, classify working-directory mismatch. If it does not, reject that hypothesis. Do not modify scripts to accommodate an accidental root.
+
+### Cleanup
+
+None, unless the command created cache or evidence files; inventory and remove only disposable files created by the recipe.
+
+## Recipe 2 — Permission denial versus sandbox denial
+
+### Trigger
+
+A read, edit, or shell action reports that access is unavailable.
+
+### Reproducer
+
+    1. Determine whether the host attempted the tool call.
+    2. Record the matching permission decision without editing configuration.
+    3. Record the active sandbox profile.
+    4. Probe a read-only path known to be inside the active profile.
+    5. Compare with the exact denied target; do not broaden either boundary.
+
+### Expected evidence
+
+A permission denial means the tool did not receive approval. A sandbox denial follows an approved attempt and identifies an operating boundary in visible output. If both can apply, record both. Reproduction succeeds by classifying the layer, not by making the blocked operation run.
+
+### Cleanup
+
+No permission, sandbox, or trust configuration changed.
+
+## Recipe 3 — Malformed tool input
+
+### Trigger
+
+A tool rejects input before observable work begins, or a rich invocation fails with an ambiguous validation message.
+
+### Reproducer
+
+    Original input: preserve as inert evidence.
+    Control input: the smallest documented valid shape.
+    Reduction: add one original field at a time until failure returns.
+    Conflict check: remove mutually exclusive or duplicate fields.
+
+### Expected evidence
+
+The minimal valid input, the first failing increment, and the exact validation result. The PostToolUseFailure envelope can preserve toolName and toolInput; it does not provide a documented parsed-error object. Redact secrets without changing the structural cause.
+
+### Cleanup
+
+Remove any temporary input file created for reduction. Do not delete the user's original fixture.
+
+## Recipe 4 — Program exit versus assertion failure
+
+### Trigger
+
+A test command reports non-zero but the first meaningful failure layer is unclear.
+
+### Reproducer
+
+    1. Run the smallest named test file or case.
+    2. Capture command exit, stderr/stdout, and first failing assertion.
+    3. If setup exits before a test runs, classify program/environment failure.
+    4. If the assertion runs, preserve expected and actual values.
+    5. Change one input dimension and repeat.
+
+### Expected evidence
+
+An explicit count of tests that ran, the first expected/actual mismatch when applicable, and the process exit status. A setup error is not RED for a behavior test. A failing assertion unrelated to proposed behavior is not proof of target cause.
+
+### Cleanup
+
+Check for snapshots, coverage, or generated fixtures. Do not update them to turn the run GREEN unless that update is the authorized behavior.
+
+## Recipe 5 — Timeout, hang, or background continuation
+
+### Trigger
+
+A command exceeds its foreground interval or returns control while work may continue.
+
+### Reproducer
+
+    1. Record the configured foreground timeout.
+    2. Determine whether the host backgrounded the command.
+    3. Inspect documented task status instead of starting a duplicate.
+    4. Capture last emitted progress and whether output advances.
+    5. Cancel only when safe and authorized; inspect partial state.
+
+### Expected evidence
+
+One of: completed with status, still running with task identity, timed out with no continuation, cancelled, or hung with a stable no-progress observation. Do not label a running background task failed. Do not label a timeout a test failure without final state.
+
+### Cleanup
+
+Account for the task, child processes, locks, temporary files, and partial artifacts.
+
+## Recipe 6 — Dirty-tree regression comparison
+
+### Trigger
+
+A suite fails after a change and ownership of the failure is uncertain.
+
+### Reproducer
+
+    1. Preserve the dirty tree; record its status.
+    2. Run the focused failing command in the current tree.
+    3. Create an isolated baseline at HEAD in a bounded temporary worktree when authorized.
+    4. Reuse dependencies safely without copying dirty source.
+    5. Run the identical command with the identical runtime version.
+    6. Compare failing test names and counts.
+
+### Expected evidence
+
+Current-tree and baseline commands, cwd, exit, pass/fail counts, and exact overlapping or unique failures. A baseline failure supports “pre-existing” only for the same failure under comparable conditions. Clean up the temporary worktree without touching the user's dirty state.
+
+### Cleanup
+
+Remove the exact temporary worktree and verify no new branch, process, or archive remains.
+
+## Recipe 7 — Partial write after a failed mutating tool
+
+### Trigger
+
+A write, installer, formatter, or generator reports failure after it may have touched files.
+
+### Reproducer
+
+    1. Stop retries.
+    2. Inventory the named destination and adjacent temp/lock files.
+    3. Compare bytes or hashes with preflight state when available.
+    4. Determine whether operation was atomic, partial, or untouched.
+    5. Choose recovery only from verified ownership and conflict policy.
+
+### Expected evidence
+
+A path-by-path state table showing absent, unchanged, created, modified, or unknown. The tool failure event proves failure, not rollback. Do not overwrite foreign content or run broad cleanup to recover.
+
+### Cleanup
+
+Remove only verified disposable remnants created by the failed operation. Preserve unknown state and report it.
+
+## Recipe 8 — Passive hook record absent
+
+### Trigger
+
+A visible tool failure has no matching session-ledger record.
+
+### Reproducer
+
+    1. Confirm the project hook was loaded and trusted.
+    2. Drive the command script with documented event JSON on stdin.
+    3. Test GROK_HOOK_EVENT present, env absent with stdin hookEventName present,
+       and both absent.
+    4. Inspect exit, stderr, and exact ledger destination.
+
+### Expected evidence
+
+The driver distinguishes hook configuration, event-name fallback, validation, and ledger-write behavior. Passive stdout is ignored by the host, so success is exit 0 plus expected state. Missing live activation remains a separate uncertainty.
+
+### Cleanup
+
+Use a temporary workspace root and remove it after the receipt.
+
+## Reproduction stop rule
+
+Stop when the next probe needs credentials, destructive recovery, configuration weakening, project trust, external mutation, or scope expansion that was not authorized. Return the supported failure class, evidence already gathered, and exact next decision.

package/.grok/skills/debugging/references/runtimes/bundled-js-binary.md

@@ -0,0 +1,415 @@
+# Bundled-JS / Embedded-Source Binaries (Bun SEA, Node SEA, Deno compile, pkg, Electron, PyInstaller)
+
+A growing class of "binaries" are not stripped C/C++ at all — they are a runtime VM glued onto a high-level-language bundle. The bundle is **plaintext or trivially-decodable** inside the binary.
+
+If you reach for `native-binary.md` workflow on these (Ghidra → pwndbg → hex), you will waste hours decompiling a runtime you don't care about while the actual logic sits exposed three megabytes away.
+
+**This reference exists because the workflow is fundamentally different from stripped C.**
+
+---
+
+## When to use this reference instead of `native-binary.md`
+
+Open this if `file ./target` shows a generic Mach-O / ELF / PE BUT any of:
+
+- Size is suspiciously large (50 MB+ for a "simple CLI")
+- `strings -n 8 ./target | rg -i "node_modules|webpack|esbuild|bun|pkg/lib|electron|pyinstaller"` returns hits
+- The binary's CLI flags include things like `--inspect`, `--unhandled-rejections`, npm-style help text
+- Vendor docs say it's built with Bun / pkg / nexe / Deno compile / PyInstaller / Electron / Tauri (UI shell)
+- `head -c 4 ./target | xxd` shows a known runtime magic for an embedded archive section
+
+If yes → **stop following `native-binary.md` and follow this**. Triage and dynamic tracing are the same. Static analysis is completely different.
+
+---
+
+## The workflow
+
+```
+  [1] Triage           →  identify the bundler (Bun? pkg? Deno? Electron? PyInstaller?)
+  [2] Locate the bundle → find where the embedded source archive starts
+  [3] Extract           → dump source to disk so you can grep / read it
+  [4] Source-level static analysis (rg + Read, NOT Ghidra)
+  [5] Runtime verification → debug logs, --inspect, partial-evidence patterns
+  [6] Fix / report
+```
+
+Step 3 is the unlock — once you have plaintext source on disk, the rest is normal codebase exploration.
+
+---
+
+## [1] Identify the bundler — 30-second fingerprint
+
+```bash
+# Look for runtime-specific markers in plaintext strings
+strings -n 12 ./target 2>/dev/null | rg -iE 'bun|node_modules|webpack|esbuild|deno|pkg/lib|electron|pyinstaller|nexe|NODE_SEA_FUSE|NODE_SEA_BLOB|tauri|ESZIP_V2|denort' | head -20
+```
+
+| Marker pattern | Bundler | Source format |
+|---|---|---|
+| `@oven/bun-darwin`, `bun-lockfile-format-v`, `// @bun` | **Bun SEA** (compiled via `bun build --compile`) | Plaintext JS, single big bundle |
+| `NODE_SEA_BLOB` + `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2:1` | **Node SEA** (`node --build-sea` or `--experimental-sea-config`) | Plaintext JS, or V8 code cache (when `useCodeCache: true`), or startup snapshot (when `useSnapshot: true`) — the latter two are NOT plaintext |
+| `pkg/lib/bootstrap.js`, `pkg/prelude`, `PAYLOAD_POSITION` | **pkg** (vercel/pkg) | Plaintext or v8 cached data |
+| `ESZIP_V2`, `denort`, `deno_runtime` | **Deno compile** (`deno compile`) | TS/JS in eszip archive — readable but needs `eszip` crate to walk; not pure plaintext |
+| `Electron`, `app.asar`, `chrome.dll`, `Squirrel.Mac` | **Electron** | `app.asar` archive (TAR-like with JSON header). Source is plaintext JS once extracted |
+| `PyInstaller`, `pyz`, `_MEIPASS`, `pyi-os-utils` | **PyInstaller** | Compressed `.pyc` bytecode — needs `pyinstxtractor` + `decompyle3` to recover Python source |
+| `nexe-`, `nexe_compile`, `:::nexe::` | **nexe** | Plaintext JS appended to node binary |
+| `Tauri`, `tao`, `wry`, `tauri::generate_context` | **Tauri** (Rust shell + JS UI) | **Two worlds**: JS frontend in resource section is extractable here; Rust commands / core logic are native and require [native-binary.md](native-binary.md) |
+
+If multiple match (e.g. Tauri + Bun): the outer shell is the first one (Tauri/Electron). The inner JS is the second one's format. **For Tauri specifically, expect to use both this reference (for the UI bundle) and `native-binary.md` (for the Rust binary side).**
+
+> **Source-format reality check**: only Bun SEA, pkg (when not using `--public-packages`), nexe, and Electron `.asar` are reliably plaintext. Node SEA with code-cache or snapshot, PyInstaller `.pyc`, and Deno eszip require additional tooling. Don't assume `strings` will find readable code — verify the bundler first.
+
+---
+
+## [2] Locate the bundle
+
+### Bun SEA — JS is just embedded plaintext
+
+The JS source is concatenated into the binary as a giant template literal / string. No decoding needed.
+
+```bash
+# Verify by searching for typical JS bundle markers
+strings -n 8 ./target | rg "function|var |let |const |async function" | head -5
+
+# Find where the bundle starts (look for "use strict" or banner comment)
+LC_ALL=C grep -aob '"use strict"' ./target | head -5
+LC_ALL=C grep -aob '#!/usr/bin/env bun' ./target | head -5
+```
+
+### Node SEA — `NODE_SEA_BLOB` resource/segment + activated fuse
+
+Per the [Node.js SEA docs](https://nodejs.org/api/single-executable-applications.html), a Node-built SEA contains:
+- A resource (PE), section in `NODE_SEA` segment (Mach-O), or note (ELF) named `NODE_SEA_BLOB`
+- The fuse string `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2:1` (with trailing `:1` indicating injected; `:0` means a copy of the node binary that has not yet had a blob injected)
+
+```bash
+# Confirm it is a SEA at all
+LC_ALL=C grep -aob 'NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2:1' ./target | head -1
+
+# Find the blob resource/section
+LC_ALL=C grep -aob 'NODE_SEA_BLOB' ./target | head
+
+# On Mach-O, inspect the segment directly
+otool -l ./target | grep -A4 'NODE_SEA'
+```
+
+The blob format is documented but non-trivial to walk by hand. For extraction, **use postject in reverse** (carve the section bytes) or read the blob via `node:sea` API from inside a debug build of the same binary. Plain `strings` will get you the embedded JS only when the SEA was built without `useCodeCache` and without `useSnapshot` — both of those replace plaintext with V8 cache data or startup snapshot bytes.
+
+`node --build-sea sea-config.json` and `node --experimental-sea-config sea-config.json` *generate* SEA blobs; neither inspects an existing executable.
+
+### Deno compile — eszip archive section
+
+```bash
+# Deno-compile binaries embed an eszip v2 archive
+LC_ALL=C grep -aob 'ESZIP_V2' ./target | head -3
+# Also confirm the runtime
+LC_ALL=C grep -aob 'denort' ./target | head -1
+```
+
+To extract, use the `eszip` Rust crate (or the `@deno/eszip` JS port) to parse the archive after carving it out at the offset above. There is no stable Deno CLI flag that inspects compiled-executable eszip contents as of 2026-04 — `deno info` only works on source files.
+
+### pkg — `PAYLOAD_POSITION` marker
+
+```bash
+LC_ALL=C grep -aob 'PAYLOAD_POSITION' ./target | head
+LC_ALL=C grep -aob 'pkg/prelude' ./target | head
+```
+
+For source extraction, use the `pkg-extract` tooling community projects or carve based on the offset reported by the `PAYLOAD_POSITION:<n>` value.
+
+### Electron — `app.asar` is usually a separate file
+
+Most Electron apps ship `app.asar` next to the binary, not embedded inside. Extract it with the official tool:
+
+```bash
+# macOS layout
+ls -la /Applications/MyApp.app/Contents/Resources/app.asar
+npx @electron/asar extract app.asar ./extracted/
+# or older:
+npx asar extract app.asar ./extracted/
+```
+
+For single-file builds where the asar is embedded inside the executable, **do not pattern-match arbitrary 4-byte sequences** (the asar format starts with a Pickle-encoded uint32 header size + JSON metadata, and the same bytes appear elsewhere in any binary). Instead, use a Pickle-aware extractor that validates the JSON header before claiming a match — the `asar` npm package's programmatic `extractAll()` API does this. Carve the asar bytes by scanning for a candidate Pickle header (4-byte size + 4-byte payload size + `{"files":` prefix), validate the JSON parses, then feed the carved buffer to `extractAll()`.
+
+### PyInstaller — use `pyinstxtractor`, NOT runtime self-extraction
+
+```bash
+# Recover the embedded archive without running the binary
+python3 pyinstxtractor.py ./target
+# Output: ./target_extracted/ with .pyc files
+
+# Decompile the .pyc files back to Python source
+decompyle3 ./target_extracted/main.pyc          # Python 3.7+
+uncompyle6 ./target_extracted/main.pyc          # older Python
+```
+
+If `pyinstxtractor` cannot read the archive (e.g. non-standard PyInstaller version), use the official `pyi-archive_viewer` tool that ships with PyInstaller. Avoid the "run-the-binary-and-snoop-`/tmp/_MEI*`" approach: it only catches what runs in the time window between `_MEIPASS` extraction and cleanup, and it executes potentially untrusted code.
+
+---
+
+## [3] Extract source to disk — DO NOT skip this
+
+**The single biggest mistake** with bundled-JS reverse engineering is trying to read the source out of `strings` output or `xxd` dumps. You will lose data. See "Gotchas" below.
+
+### For Bun SEA / nexe / single-string-blob bundlers
+
+Read the binary as bytes, find the JS section, save to a `.js` file:
+
+```python
+# extract_bundled_js.py
+import sys
+
+if len(sys.argv) < 2:
+    raise SystemExit("usage: extract_bundled_js.py <target>")
+
+with open(sys.argv[1], 'rb') as f:
+    data = f.read()
+
+markers = [b'// @bun', b'"use strict"', b"'use strict'", b'#!/usr/bin/env']
+start = -1
+for m in markers:
+    p = data.find(m)
+    if p != -1 and (start == -1 or p < start):
+        start = p
+
+if start == -1:
+    raise SystemExit(
+        "no bundle marker found — binary may not be Bun/nexe, "
+        "or markers were stripped. Try strings(1) for hints."
+    )
+
+# Heuristic end: look for a long null run AFTER start.
+# This is a heuristic, NOT a guarantee. Verify the tail of the output
+# looks like JS (closing braces, EOF) before trusting it.
+end = data.find(b'\x00' * 1024, start)
+if end == -1:
+    end = len(data)
+
+bundle = data[start:end]
+print(f'Extracted {len(bundle)} bytes from offset {start} to {end}', file=sys.stderr)
+sys.stdout.buffer.write(bundle)
+```
+
+```bash
+python3 extract_bundled_js.py ./target > extracted-bundle.js
+wc -c extracted-bundle.js
+# Sanity check the tail is JS, not random binary
+tail -c 200 extracted-bundle.js
+```
+
+### For PyInstaller
+
+Use `pyinstxtractor` then `uncompyle6` / `decompyle3` on the `.pyc` files.
+
+### For Electron .asar
+
+```bash
+npx asar extract app.asar ./extracted/
+# Now ./extracted/ has a normal node_modules + your source layout
+```
+
+### For Deno compile
+
+Use the `eszip` Rust crate or the `@deno/eszip` JS port to walk the archive after carving the eszip section out at the offset reported by the `ESZIP_V2` magic search. There is no stable Deno CLI as of 2026-04 that inspects compiled-binary eszip contents directly.
+
+---
+
+## [4] Source-level static analysis — `rg` + `Read`, not Ghidra
+
+Once you have the source on disk, treat it as a normal codebase:
+
+```bash
+# Find function definitions
+rg -n "^function |^const \w+ = (function|\(.*\) =>)" extracted-bundle.js | head
+
+# Find specific behavior
+rg -n "claude-opus-4-7|reasoning_effort|api_key" extracted-bundle.js
+
+# Resolve minified identifiers — they show up as `var XYZ="value"`
+rg -aoP 'var \w+="[^"]+"' extracted-bundle.js | head -50
+```
+
+For minified bundles, use a template-literal-aware parser to extract specific functions or template strings. Example skeleton:
+
+```python
+def find_template_end(data, start):
+    """Walk a JS template literal preserving ${...} interpolation depth.
+    Returns position of closing backtick."""
+    i = start
+    while i < len(data):
+        c = data[i:i+1]
+        if c == b'\\':
+            i += 2; continue
+        if c == b'$' and data[i+1:i+2] == b'{':
+            depth = 1; i += 2
+            while i < len(data) and depth > 0:
+                cc = data[i:i+1]
+                if cc == b'\\': i += 2; continue
+                if cc == b'`':
+                    j = find_template_end(data, i+1)
+                    i = j + 1; continue
+                if cc == b'{': depth += 1
+                elif cc == b'}': depth -= 1
+                elif cc in (b'"', b"'"):
+                    q = cc; i += 1
+                    while i < len(data) and data[i:i+1] != q:
+                        if data[i:i+1] == b'\\': i += 2
+                        else: i += 1
+                    i += 1; continue
+                i += 1
+            continue
+        if c == b'`': return i
+        i += 1
+    return -1
+```
+
+For function-body extraction, **track the parameter list separately** before tracking body braces. The naive approach mis-counts destructuring `function f({a, b, ...c})` as the body `{` and exits early.
+
+---
+
+## [5] Runtime verification
+
+You usually cannot single-step JS inside a Bun-compiled binary the way you would with `node --inspect`. Workarounds:
+
+### Bun-compiled
+
+Bun's inspector takes `--inspect[=<host>:<port>[/<prefix>]]` on the command line. For env-var control of compiled binaries, the form is the same minus the leading `--`:
+
+```bash
+# Default port (6499) auto-prefix
+./target --inspect
+# → ws://localhost:6499/<auto-prefix>  (paste into https://debug.bun.sh)
+
+# Explicit host:port[/prefix]
+./target --inspect=localhost:9229/dbg
+# Or via env var (if --inspect cannot be passed)
+BUN_INSPECT=localhost:9229/dbg ./target
+```
+
+**For HTTP request tracing without an interactive debugger** (highest-value Bun-specific runtime evidence):
+
+```bash
+# Print every fetch() / node:http request as a curl command + full headers/body
+BUN_CONFIG_VERBOSE_FETCH=curl ./target ...
+
+# Or just print the request/response without curl-format
+BUN_CONFIG_VERBOSE_FETCH=true ./target ...
+```
+
+Plus generic env-var-based debug logging if the app supports it:
+
+```bash
+APP_DEBUG=1 APP_LOG_LEVEL=debug APP_LOG_FILE=/tmp/trace.log ./target
+```
+
+### Node SEA / pkg / nexe
+```bash
+# These usually accept --inspect since they are real Node
+./target --inspect
+# Then chrome://inspect or node --inspect-brk
+```
+
+### Electron
+```bash
+./target.app/Contents/MacOS/target --inspect=9229 --remote-debugging-port=9223
+# Renderer process is at chrome://inspect, main process via the inspector port
+```
+
+### When you cannot make a real call
+The target's API may require credentials, network access, or paid quota you don't have. **You are not stuck** — see [methodology/partial-runtime-evidence.md](../methodology/partial-runtime-evidence.md) for the fallback patterns.
+
+---
+
+## ⚠️ Gotchas — read these before extracting
+
+### G1. `strings -n N` silently drops short identifier interpolations
+
+`strings` outputs runs of printable characters of length **≥ N**. Default is 4 on most systems; many references (including older versions of `native-binary.md`) recommend `-n 8` for less noise.
+
+**With `-n 8`, short template-literal interpolations like `${x}`, `${i}`, `${R}` are silently dropped** because they are 4 chars surrounded by non-printable bytes (newlines or section padding). The result looks like:
+
+```text
+expected:  <INSTRUCTIONS>\n${x}\n</INSTRUCTIONS>
+strings:   <INSTRUCTIONS>\n</INSTRUCTIONS>      ← ${x} is gone, no warning
+```
+
+A consumer reading the strings output would conclude the template is empty.
+
+**Mitigation**:
+1. Use `strings` only for **fingerprinting** (Phase 1 triage), never as the source of extracted text.
+2. For actual extraction, **read the binary as bytes** with `python3 -c "open('./target','rb').read()"` and grep / parse from there.
+3. If you must use `strings`, try `strings -n 1 -t x ./target` and post-filter — but byte-level reads are still more reliable.
+
+### G2. Stale cached binary ≠ latest features
+
+Bundled-app installers often check a remote version and skip download if a cached binary exists. If you reverse-engineered an old version and the user reports behavior you don't see in the source, **re-run the installer** (or fetch the version manifest manually) before assuming the source is current.
+
+```bash
+# Example pattern - varies by tool
+curl -fsSL https://example.com/install.sh | head -50  # find version-fetch URL
+curl -fsSL https://static.example.com/cli/cli-version.txt
+./your-tool --version
+# Compare. If different, re-install.
+```
+
+### G3. APFS / NTFS case-insensitivity silently overwrites files
+
+When extracting many minified function bodies (`cVR`, `CVR`, `dpr`, `DPR`, …) and saving each to its own file, **macOS APFS and Windows NTFS treat `cVR.txt` and `CVR.txt` as the same file**. The second write silently overwrites the first.
+
+**Mitigation**: prefix filenames with something case-distinguishing, e.g. `mode-cVR.txt`, `mode-CVR.txt`, or use a hash suffix.
+
+### G4. Bun's runtime adds 30-50 MB of unrelated symbols
+
+A 70 MB Bun-compiled binary is **mostly Bun runtime** (~50 MB) plus your app (~20 MB). When fingerprinting, you will see thousands of strings like `tree-sitter-typescript`, `react-native-stylex` etc. that the user's actual app doesn't use — these are package names baked into Bun's package-resolution data.
+
+**Mitigation**: when grepping for "what does this app do?", filter out runtime noise:
+```bash
+strings -n 8 ./target | rg -v 'node_modules|@oven/bun|package-lock|tree-sitter|ffmpeg-installer' | head
+```
+
+### G5. Source maps usually NOT shipped
+
+Bundled apps strip source maps for production. Variable names are minified to `T`, `R`, `a`, `r`, etc. Treat the bundle like an obfuscated codebase: identify constants by tracing assignments (`var T="actual-name"`) and resolve interpolations manually.
+
+### G6. The "extract" file is not legally redistributable
+
+If reverse-engineering proprietary software, the extracted source is the vendor's IP. Use it for understanding behavior, **never commit it to git**, never post snippets in public issues. Cleanup your `extracted-bundle.js` files in Phase 9.
+
+---
+
+## Silent-failure patterns specific to bundled JS
+
+| Pattern | Why it's silent |
+|---|---|
+| Bundle includes unreachable dead code from tree-shaking failures | You read code that never runs — verify with runtime trace |
+| `process.env.X` resolved at BUILD time, not RUNTIME | Setting the env var at runtime has no effect; the value is baked in |
+| `import.meta.url` in compiled binary returns `bun://...` not a real path | File-relative resolution silently breaks |
+| Worker threads spawn from embedded code, look for sub-bundle inside main bundle | Workers may have their own copy of dependencies |
+| Minified identifiers with case variants used in same module | Easy to confuse `cVR` with `CVR` when reading fast |
+
+---
+
+## Phase 9 cleanup specifics for bundled-JS work
+
+```bash
+# Remove extracted bundles — they may contain proprietary source
+rm -f /tmp/extracted-bundle.js /tmp/extracted-*.js
+rm -rf /tmp/asar-extracted/
+rm -rf /tmp/_MEI*
+
+# Remove strings dumps
+rm -f /tmp/*-strings.txt /tmp/*-strings-v*.txt
+
+# Remove Python helper scripts created for parsing
+rm -f /tmp/extract_bundled_js.py /tmp/parse_template.py
+
+# Verify the extraction directory is gone (if you used a workspace dir)
+ls /Users/$USER/local-workspaces/*-extracted/ 2>/dev/null
+# rm -rf only after journal review confirms nothing important is there
+```
+
+---
+
+## When to escalate back to `native-binary.md`
+
+If extraction reveals the "bundle" is actually compiled to v8 cached data (pkg with `--public-packages` or PyInstaller with bytecode-only mode), and decompilation is non-trivial, **switch back to `native-binary.md` workflow** (Ghidra against the runtime + careful tracing). Bundled-JS workflow only helps when the high-level source is recoverable as readable text.