claude-session-recall 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,253 @@
+# session-recall
+
+**Your AI coding session has been compacted. It did not tell you how many times, and it cannot tell
+which of the things it "knows" it actually measured.**
+
+![recall compactions, run against a real Claude Code session: 28 compactions, and 495,488 characters of summary standing in for the record](docs/demo.gif)
+
+Run it on your own session, before reading any further:
+
+```bash
+git clone https://github.com/CavsSatyamKhatri/claude-session-recall.git
+node claude-session-recall/recall.mjs compactions
+```
+
+Your numbers will be different. That is the point — they are *yours*, and nothing else was going to
+tell you.
+
+A Claude Code skill that reads the session's own transcript, so a fact that arrived through a
+compaction summary can be checked instead of repeated.
+
+---
+
+## The problem
+
+When a conversation is compacted, what survives into the next context window is a **summary**:
+chosen, compressed and written by the assistant. The full record is not deleted — it stays in the
+transcript on disk — but nothing points at it.
+
+So a fact that arrived through a summary is **indistinguishable** from a fact that was measured. It
+reads the same, it is stated with the same confidence, and it gets acted on the same way. Repeat
+that through several compactions and a claim nobody ever checked becomes something everybody
+believes.
+
+## Find your own inherited claims
+
+You do not have to guess what to look for. Ask what your last summary asserted:
+
+```bash
+node recall.mjs claims
+```
+
+```
+  Summary #28 of 28, line 103216, 17,109 chars.
+  16 sentence(s) in it assert something checkable.
+
+  This is a starting list, not a verdict: a sentence here is not wrong, and one that is
+  missing is not cleared. Trace the ones your next decision depends on.
+
+   1. [version] ... the release chore is still pending ...
+      recall trace "the release chore is still pending"
+   ...
+```
+
+Then trace the one your next decision rests on. It prints the command for you:
+
+```bash
+node recall.mjs trace "the release chore is still pending"
+```
+
+Two answers are possible, and they look nothing alike.
+
+**A claim with nothing behind it:**
+
+```
+  First stated in a compaction summary at line 103216.
+  Occurrences in the record BEFORE that: 0
+
+  THE SUMMARY IS THE ORIGIN. Nothing in the record measured this before a summary
+  asserted it, so there is no evidence behind it in this session. Measure it now
+  rather than repeating it.
+```
+
+**A claim that was actually established:**
+
+```
+  First stated in a compaction summary at line 95403.
+  Occurrences in the record BEFORE that: 9
+
+  It was in the record first, earliest at line 91905.
+  Read it with:  recall around 91905
+```
+
+That distinction is the whole tool.
+
+## Install
+
+**To give it to Claude Code as a skill** (so it reaches for it on its own):
+
+```bash
+git clone https://github.com/CavsSatyamKhatri/claude-session-recall.git \
+  ~/.claude/skills/session-recall
+```
+
+That is the whole install. No dependencies, no build, no config, nothing running in the background —
+just Node's standard library and a file you already have. Claude Code picks the skill up on the next
+session, and `SKILL.md`'s description tells it when to reach for it.
+
+## What runs where
+
+The tool itself is **cross-platform**: `compactions`, `trace`, `claims`, `turns`, `find` and
+`around` read a transcript, and that is the same on macOS, Linux and Windows.
+
+The optional guards are not all universal, and it is better to say so than to have you find out:
+
+| guard | where it applies |
+|---|---|
+| an `Edit` whose text is not in the file | **everywhere** — and it is the one that fires most |
+| a backslash before a quote in a Python heredoc | everywhere |
+| `/tmp` crossing between Git Bash and a Windows interpreter | Windows only |
+| `&&` / `\|\|` in Windows PowerShell 5.1 | Windows only |
+
+On macOS and Linux the two Windows guards simply never fire; they check `process.platform` and stay
+out of the way.
+
+## Commands
+
+| | |
+|---|---|
+| `compactions` | how many times this session was compacted, when, and how much each summary carried |
+| `claims [n] [max]` | what summary *n* asserts that can be checked, each with a ready-made `trace` |
+| `trace "<text>"` | **the important one** — did the record contain this before a summary claimed it? |
+| `turns [n]` | the last n things you asked for, with transcript line numbers |
+| `find "<text>"` | every byte-exact occurrence, with surrounding context |
+| `around <line>` | what was being worked on near that point |
+
+`--file <path>` reads an older transcript instead of the live one.
+
+It finds the live transcript by **modification time** — the `.jsonl` being appended to under
+`~/.claude/projects/`. Not by deriving the folder name from the working directory: that folder is a
+slug of the path whose casing is not consistent (`C--Users-Admin` sits beside `d--Projects-...`),
+and a wrong guess reads somebody else's session.
+
+## Three things to know before trusting the output
+
+**`claims` is a heuristic and says so.** It looks for the shapes that go wrong in practice — a
+version number, a count, and the words that quietly turn a past observation into a present-tense
+claim: *still*, *remains*, *pending*, *already*. A sentence it flags is not guilty, and a sentence
+it misses is not cleared. It exists to give you somewhere to start, not a verdict.
+
+**Trace a claim, not a token.** Tracing a bare version string can return hundreds of hits from code
+comments and build files, and tells you almost nothing. Trace the distinctive phrase that carries
+the assertion. `claims` builds that phrase for you.
+
+**Your own searching lands in the record.** Running `trace` writes that command into the transcript,
+so occurrences *after* the summary can include the query itself. The output separates before and
+after for exactly this reason — only the "before" count is evidence. This was found by testing, not
+by reasoning: a search for a sentence that had never been said still returned one hit.
+
+## The guards (optional, and a different thing)
+
+Tracing an inherited claim fixes one failure. There is a second kind, and it is not a memory failure
+at all. Count it on your own record:
+
+```bash
+node recall.mjs errors
+```
+
+```
+  Mechanical failures in this record - each one a round-trip that could not have worked:
+
+       148   a script that could not parse            SyntaxError
+       136   a command that is not on this machine    command not found
+        66   /tmp meaning two different places        No such file or directory: '/tmp/
+        62   unbalanced quoting in a shell command    unexpected EOF while looking for matching
+        61   an Edit whose text was not in the file   String to replace not found
+        61   a backslash inside a Python string       unterminated string literal
+        18   && in Windows PowerShell                 is not a valid statement separator
+       ...
+```
+
+Again, your numbers will differ — the shape is what matters. **Every one of these was already
+covered by a rule that was present and was broken anyway.** The PowerShell one is the clearest case:
+*"`&&` is not available in this version"* sits in the tool description on **every single request**.
+It was still broken, repeatedly.
+
+So the problem is not that a rule is missing, or hard to find, or badly worded. A rule has to be
+*applied*, and attention is not reliable.
+
+A hook does not need attention. It runs outside the assistant's judgement, before the tool call, and
+refuses. `hooks/guard.mjs` refuses four things:
+
+- **`/tmp` crossing interpreters** — Git Bash resolves `/tmp` inside its own install; a
+  Windows-native `python`/`node` resolves it to `C:\tmp`. A file written by one and read by the
+  other is simply not there.
+- **A backslash before a quote in a Python heredoc** — `'\'` and `.replace('\','/')` are an
+  unterminated literal or a silent escape.
+- **`&&` or `||` in Windows PowerShell 5.1** — a parser error before anything runs.
+- **An `Edit` whose text is not in the file** — and it names *why*: line endings, indentation, or
+  the block having changed since it was read.
+
+```bash
+node hooks/install-hooks.mjs     # you run this, not the assistant
+```
+
+**You install it, deliberately.** A thing whose purpose is to limit the assistant's behaviour should
+not be installed by the assistant — and it cannot be: writing your hook and permission settings is
+refused, which is the correct design. The installer merges rather than replaces, backs the file up,
+prints exactly what changed, and does nothing at all if your `settings.json` is not valid JSON.
+
+```bash
+node hooks/prove.mjs             # 11 cases: 5 that must be refused, 6 that must not
+```
+
+Run that before trusting it. **A guard that cannot be seen to refuse is not a guard — and one that
+refuses the wrong thing is worse than none**, because it gets switched off within a week and takes
+the working guards with it. The allow cases are there for that reason and matter as much as the deny
+cases: ordinary `/tmp` use in bash, a heredoc with no backslash, PowerShell using `;`, an `Edit`
+that really does match.
+
+Two of those eleven cases failed the first two times it was run, and **both times the guard was
+right and the test was wrong** — searching with *less* indentation than the file has still matches,
+because the shorter run of spaces sits inside the longer one. That is the sort of thing only running
+it tells you.
+
+## What it deliberately is not
+
+**It builds no index and caches nothing.** A transcript of several hundred million characters
+searches in about two seconds. A stored summary of it would buy nothing measurable and would go
+stale — which is the exact failure this exists to prevent. Reading the record directly cannot be
+out of date.
+
+**It never tells you whether a claim is true.** It tells you where the claim entered. The transcript
+proves what was *said*, never what is *true now* — a version that was correct when it was written
+may be wrong today. Where the running system can be asked, ask the running system; use this to find
+out whether anyone ever did.
+
+**It is not a memory system.** It does not persist anything between sessions, rank importance, or
+decide what matters. It reads a file you already have.
+
+## Why not just grep the transcript?
+
+You can, and for a known string you should — it is the same file. What `trace` adds is the one
+distinction grep cannot make: **whether an occurrence sits inside a compaction summary or in the
+record itself**, and therefore whether a claim had any evidence behind it before a summary asserted
+it. Compaction boundaries are marked in the transcript (`isCompactSummary`); this reads them.
+
+## Where this came from
+
+One long-running session, compacted 28 times. A summary carried a version number and the words
+*"still pending"*. Both were wrong — the thing had already shipped — and the claim survived several
+more compactions, was written into plans, and was repeated for hours before anyone thought to check
+it. Tracing it afterwards took one command and showed zero occurrences in the record before the
+summary that asserted it.
+
+The number had never been measured. It had been inherited.
+
+## Requirements
+
+Node 18+. Nothing else.
+
+## Licence
+
+MIT.

package/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: session-recall
+description: Use when a fact arrived through a compaction summary rather than from something you measured this turn - versions, counts, "still pending", "already done", "last deployed on", anything inherited from earlier context. Reads the session's own transcript to show where the claim entered, so it can be checked instead of repeated. Also use when picking up a long-running session, when you cannot remember what was decided earlier, or when the user says "check this first".
+---
+
+# Session Recall
+
+## The failure this exists for
+
+When a conversation is compacted, what survives into the next context window is a **summary**:
+chosen, compressed and written by the assistant. The full record is not deleted — it stays in the
+session transcript on disk — but nothing points at it.
+
+So a fact that arrived through a summary is **indistinguishable** from one that was measured. It
+reads the same, it is stated with the same confidence, and it is acted on the same way. Repeat that
+through several compactions and a claim nobody ever checked becomes something everybody believes —
+written into plans, carried into the next summary, and repeated until somebody says "check this".
+
+## The rule
+
+**A fact you did not measure this session is a claim until you check it.** Especially:
+
+- version numbers, counts, sizes, dates
+- "still pending", "already done", "not built yet", "last deployed on…"
+- anything phrased as settled that you cannot point at a command for
+
+Check it one of two ways, and the first is usually better:
+
+1. **Measure it again.** If it can be read off the running system in one command, read it.
+2. **Trace it.** `trace "<the claim>"` says whether the record contained it before a summary
+   asserted it. Zero occurrences before the summary means the summary is the origin.
+
+## Using it
+
+```bash
+node ~/.claude/skills/session-recall/recall.mjs compactions
+node ~/.claude/skills/session-recall/recall.mjs claims
+node ~/.claude/skills/session-recall/recall.mjs trace "<a phrase from the summary>"
+node ~/.claude/skills/session-recall/recall.mjs around <line>
+```
+
+| | |
+|---|---|
+| `compactions` | how many times this session was compacted, when, and how much each summary carried |
+| `claims [n] [max]` | what summary *n* asserts that can be checked, each with a ready-made `trace` |
+| `trace "<text>"` | **the important one** — did the record contain this before a summary claimed it? |
+| `turns [n]` | the last n things the user asked for, with transcript line numbers |
+| `find "<text>"` | every byte-exact occurrence, with surrounding context |
+| `around <line>` | what was being worked on near that point |
+
+It finds the live transcript itself — the `.jsonl` being appended to under `~/.claude/projects/` —
+so no path has to be supplied. `--file <path>` reads an older session instead.
+
+**Start with `claims` when you do not know what to check.** It reads the latest summary and lists
+what it asserts, printing the `trace` command for each. That removes the need to guess which phrase
+to search for.
+
+## Three things to know before trusting the output
+
+**`claims` is a heuristic.** It looks for version numbers, counts, and the words that turn a past
+observation into a present-tense claim — *still*, *remains*, *pending*, *already*. A sentence it
+flags is not guilty; a sentence it misses is not cleared. It gives you somewhere to start.
+
+**Trace a claim, not a token.** A bare version string can return hundreds of hits from code comments
+and build files, and tells you almost nothing. Trace the distinctive phrase that carries the
+assertion — `claims` builds that phrase for you.
+
+**Your own searching lands in the record.** Running `trace` writes that command into the transcript,
+so occurrences *after* the summary can include the query itself. The output separates before and
+after for exactly this reason — only the "before" count is evidence.
+
+## The guards beside it
+
+`hooks/guard.mjs` is a PreToolUse hook, not part of this skill's instructions, and the distinction
+is the point. Everything it refuses was already covered by a rule that was present and broken
+anyway — `&&` in PowerShell sits in the tool description on every request. **A rule has to be
+applied; a hook does not.**
+
+It refuses `/tmp` paths that cross between Git Bash and a Windows-native interpreter, a backslash
+before a quote in a Python heredoc, `&&`/`||` in Windows PowerShell, and an `Edit` whose text is not
+in the file (naming whether it is line endings, indentation, or a block that has changed).
+
+The user installs it with `node hooks/install-hooks.mjs` — not you. Writing hook and permission
+settings is refused, and that is correct: a limit on your own behaviour is not yours to install.
+
+## What it deliberately is not
+
+**It builds no index and caches nothing.** A transcript of several hundred million characters
+searches in about two seconds, so a stored summary of it would buy nothing measurable and would go
+stale — which is the exact failure this skill exists to prevent. Reading the record directly cannot
+be out of date.
+
+**It never says whether a claim is true.** It says where the claim entered. A tool that confidently
+answers a question it cannot actually answer is the disease, not the cure — and the transcript
+proves what was *said*, never what is *true now*. Where the running system can be asked, ask the
+running system; use this to find out whether anyone ever did.

package/demo.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Run the commands that tell the story, with the pauses a viewer needs.
+ *
+ * This exists so a recording does not depend on somebody typing accurately while being filmed. It
+ * prints each command as if it had been typed, waits long enough to read the output, and stops.
+ *
+ *     node demo.mjs                      # all three steps, about 32 seconds
+ *     node demo.mjs --fast               # half the pauses
+ *     node demo.mjs --only compactions   # the first step only - shows no work of yours
+ *     node demo.mjs --trace "<phrase>"   # trace a phrase you choose rather than one it picks
+ *     node demo.mjs --no-redact          # leave your paths in
+ *
+ * Nothing here is special to the recording: it runs the real commands against your real transcript,
+ * so what is filmed is what a viewer will get.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const RECALL = join(HERE, 'recall.mjs')
+const ARGV = process.argv.slice(2)
+const FAST = ARGV.includes('--fast')
+const REDACT = !ARGV.includes('--no-redact')
+const ONLY = ARGV.includes('--only') ? ARGV[ARGV.indexOf('--only') + 1] : null
+const PHRASE = ARGV.includes('--trace') ? ARGV[ARGV.indexOf('--trace') + 1] : null
+const wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, FAST ? ms / 2 : ms)
+
+function type(text) {
+  process.stdout.write('\n$ ')
+  for (const ch of text) {
+    process.stdout.write(ch)
+    wait(18)
+  }
+  process.stdout.write('\n')
+  wait(300)
+}
+
+/** Show the command the way a viewer would have to type it - quoted where it needs quoting. */
+function shown(args) {
+  return 'recall ' + args
+    .filter((a) => a !== '')
+    .map((a) => (/[ "]/.test(a) ? '"' + a.replace(/"/g, '\\"') + '"' : a))
+    .join(' ')
+}
+
+/**
+ * Take your own name out of the picture.
+ *
+ * A recording of this runs against YOUR transcript, so the header carries your home directory and
+ * the slug of the project you were working in - which is an employer's name as often as not. The
+ * replacement is written to look like a placeholder, so nobody mistakes it for real output.
+ *
+ * The home directory is a PATH and not a pattern: `C:\Users\Admin` handed to RegExp raw turns \U
+ * and \A into escapes and matches nothing, which is exactly what happened the first time - the path
+ * printed in full while this function claimed to be redacting it. Escape it.
+ *
+ * It only touches paths. What a summary claimed is your own text and cannot be masked without
+ * lying about what the tool does; choose the claim with --trace, or record only `compactions`.
+ */
+const escapeForRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const home = process.env.USERPROFILE || process.env.HOME || ''
+const HOME_RE = home ? new RegExp(escapeForRegex(home), 'gi') : null
+
+function redact(s) {
+  if (!REDACT) return s
+  const withHome = HOME_RE ? s.replace(HOME_RE, '~') : s
+  return withHome.replace(/(\.claude[\\/]projects[\\/])[^\\/\s]+/gi, '$1<your-project>')
+}
+
+function run(args, hold) {
+  type(shown(args))
+  const r = spawnSync(process.execPath, [RECALL, ...args], { encoding: 'utf8' })
+  process.stdout.write(redact(r.stdout || r.stderr || ''))
+  wait(hold)
+}
+
+// 1. The thing nobody knows is happening. Counts and dates only - no work of yours appears here.
+run(['compactions'], 4500)
+
+if (ONLY === 'compactions') process.exit(0)
+
+// 2. What the latest summary is asserting.
+//
+// This prints YOUR summary's own sentences, and no redaction can fix that without lying about what
+// the tool does. If the recording is going somewhere public, either stop at step 1 with
+// `--only compactions` or pick a harmless claim with `--trace`.
+run(['claims', '', '3'], 5000)
+
+// 3. The question that matters - shown on a claim where the answer is interesting.
+//
+// The first suggestion is often a claim that WAS measured, and tracing that proves the tool works
+// while showing nothing worth watching. So try them in order and stop at the first one the record
+// does not support. If every one is well-founded, that is a good session and the last result is
+// shown as it is: a demo that manufactured a failure would be worse than a dull one.
+let chosen = PHRASE
+if (!chosen) {
+  const claims = spawnSync(process.execPath, [RECALL, 'claims'], { encoding: 'utf8' }).stdout || ''
+  const suggestions = [...claims.matchAll(/recall trace "([^"]+)"/g)].map((m) => m[1])
+  chosen = suggestions[0]
+  for (const s of suggestions.slice(0, 8)) {
+    const out = spawnSync(process.execPath, [RECALL, 'trace', s], { encoding: 'utf8' }).stdout || ''
+    if (out.includes('THE SUMMARY IS THE ORIGIN')) { chosen = s; break }
+  }
+}
+run(['trace', chosen || 'still pending'], 6000)
+
+process.stdout.write('\n')

package/hooks/guard.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * Stop the mistakes that were already written down and made anyway.
+ *
+ * WHY A HOOK AND NOT INSTRUCTIONS
+ * -------------------------------
+ * Every failure below was already covered by a rule the assistant had in front of it. The
+ * PowerShell one is the clearest: "`&&` is not available" sits in the tool description on every
+ * single request, and it was broken anyway. So the problem is not that the rule is missing or hard
+ * to find - it is that a rule depends on being applied, and attention is not reliable.
+ *
+ * A hook does not depend on attention. It runs outside the assistant's judgement, before the tool
+ * call, and refuses. That is the whole reason this is a hook rather than more words in a skill.
+ *
+ * MEASURED, NOT GUESSED
+ * ---------------------
+ * Counts from one long Claude Code session's own transcript (467 million characters):
+ *
+ *     SyntaxError                                135
+ *     command not found                          124
+ *     No such file or directory: '/tmp/           56
+ *     unexpected EOF while looking for matching   52
+ *     String to replace not found                 49
+ *     unterminated string literal                 48
+ *     is not a valid statement separator           6
+ *
+ * Roughly 470 round-trips spent on mistakes a few lines of pattern matching can refuse. Each guard
+ * below names the count it is there for; if a guard cannot point at a number, it should not exist.
+ *
+ * SAFETY
+ * ------
+ * A hook that throws could block every tool call, so everything here is wrapped and the default is
+ * always to allow. A guard that is unsure says nothing.
+ */
+
+import { readFileSync } from 'node:fs'
+
+const IS_WINDOWS = process.platform === 'win32'
+
+/** Deny with a reason the assistant can act on. Anything else allows. */
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }))
+  process.exit(0)
+}
+
+function allow() {
+  process.stdout.write(JSON.stringify({}))
+  process.exit(0)
+}
+
+/**
+ * `/tmp` is not one place. (56 failures)
+ *
+ * Git Bash resolves `/tmp` inside its own installation; a Windows-native `python`/`node` resolves
+ * the same string to `C:\tmp`. So a file written by one and read by the other is simply not there,
+ * and the error arrives as `FileNotFoundError`, several seconds later, pointing at a path that
+ * looks perfectly correct.
+ */
+function tmpCrossesInterpreters(cmd) {
+  if (!IS_WINDOWS) return null
+  if (!/\/tmp\//.test(cmd)) return null
+  if (!/\b(python3?|node)\b/.test(cmd)) return null
+  return 'This command writes or reads /tmp AND runs python or node. Those are two different ' +
+    'places on Windows: Git Bash resolves /tmp inside its own install, a Windows-native ' +
+    'interpreter resolves it to C:\\tmp. The file will not be found. Use a path both agree on - ' +
+    'the session scratchpad directory, or $env:TEMP / %TEMP% - and pass it explicitly.'
+}
+
+/**
+ * A lone backslash inside a Python string. (48 failures, part of 135 SyntaxErrors)
+ *
+ * Writing `'\'` or `.replace('\','/')` in a heredoc body is an unterminated string literal, and
+ * `'\r'`-style sequences inside a non-raw string silently become the control character rather than
+ * the two characters that were meant. Both were hit repeatedly while editing Windows paths.
+ */
+function pythonBackslashInString(cmd) {
+  if (!/\bpython3?\b[^|]*<<'?\w+'?/.test(cmd)) return null
+  // A backslash immediately before a closing quote is the shape that breaks.
+  if (!/\\['"]/.test(cmd)) return null
+  return 'This Python heredoc contains a backslash directly before a quote. In a non-raw string ' +
+    "that is an unterminated literal or a silent escape - `'\\'` and `.replace('\\','/')` both " +
+    'fail this way. Use chr(92) for a literal backslash, or a raw string (r\'...\'), or avoid the ' +
+    'question: paths in this transcript format already use forward slashes.'
+}
+
+/**
+ * `&&` in Windows PowerShell 5.1. (6 failures)
+ *
+ * Pipeline chain operators arrived in PowerShell 7. In 5.1 this is a parser error before anything
+ * runs, and the message ("The token '&&' is not a valid statement separator in this version") does
+ * not say what to use instead.
+ */
+function powershellChain(cmd) {
+  if (!/&&|\|\|/.test(cmd)) return null
+  return 'Windows PowerShell 5.1 has no && or || - they are a parser error before anything runs. ' +
+    'Use `;` to run unconditionally, or `if ($?) { ... }` to run only when the previous command ' +
+    'succeeded. If you are handing this to a person to paste, run it yourself first.'
+}
+
+/**
+ * The text being replaced is not in the file. (49 failures)
+ *
+ * An Edit that does not match is a whole round-trip spent learning that something invisible
+ * differed - almost always line endings or leading whitespace. That is checkable before the call,
+ * and the reason can be named instead of guessed at.
+ */
+function editWillNotMatch(input) {
+  const { file_path: file, old_string: oldStr } = input || {}
+  if (!file || typeof oldStr !== 'string' || oldStr === '') return null
+  let text
+  try { text = readFileSync(file, 'utf8') } catch { return null }   // a new file is not our business
+  if (text.includes(oldStr)) return null
+
+  // It does not match. Say WHY, because "not found" alone is what wasted the round-trip.
+  const why = []
+  if (text.replace(/\r\n/g, '\n').includes(oldStr.replace(/\r\n/g, '\n'))) {
+    why.push('line endings differ (the file has CRLF, or the search text does)')
+  }
+  const squash = (s) => s.replace(/[ \t]+/g, ' ').trim()
+  if (!why.length && squash(text).includes(squash(oldStr))) {
+    why.push('the text is there but the indentation or spacing differs')
+  }
+  const firstLine = oldStr.split('\n')[0].trim()
+  if (!why.length && firstLine.length > 8 && text.includes(firstLine)) {
+    why.push('the first line matches but the rest does not - the block has changed since it was read')
+  }
+  if (!why.length) why.push('no part of it is in the file - wrong file, or it was already changed')
+
+  return 'This Edit will not match: ' + why[0] + '. Read the exact bytes first ' +
+    '(Read, or grep with -n) and copy the target from what the file actually contains. ' +
+    'File: ' + file
+}
+
+let raw = ''
+process.stdin.on('data', (c) => { raw += c })
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(raw || '{}')
+    const tool = payload.tool_name || ''
+    const input = payload.tool_input || {}
+    const cmd = typeof input.command === 'string' ? input.command : ''
+
+    let reason = null
+    if (tool === 'Bash') {
+      reason = tmpCrossesInterpreters(cmd) || pythonBackslashInString(cmd)
+    } else if (tool === 'PowerShell') {
+      reason = (IS_WINDOWS ? powershellChain(cmd) : null) || tmpCrossesInterpreters(cmd)
+    } else if (tool === 'Edit' || tool === 'MultiEdit') {
+      reason = editWillNotMatch(input)
+    }
+
+    if (reason) deny(reason)
+    allow()
+  } catch {
+    // A guard that is unsure says nothing. Blocking every tool call because this script has a bug
+    // would be far worse than the mistakes it is here to prevent.
+    allow()
+  }
+})

package/hooks/install-hooks.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Register the guards as PreToolUse hooks.
+ *
+ * You run this, not the assistant. That is deliberate: a thing whose whole purpose is to put a
+ * limit on the assistant's behaviour should not be installed by the assistant. (It also cannot be -
+ * writing your permission and hook settings is refused, which is the correct design.)
+ *
+ * It merges rather than replaces, backs the file up first, and prints exactly what changed. Run it
+ * again to update the path; it will not add a second copy.
+ */
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const GUARD = resolve(join(dirname(fileURLToPath(import.meta.url)), 'guard.mjs'))
+const SETTINGS = join(homedir(), '.claude', 'settings.json')
+const MATCHER = 'Bash|PowerShell|Edit|MultiEdit'
+const command = 'node "' + GUARD + '"'
+
+if (!existsSync(GUARD)) {
+  console.error('guard.mjs is not beside this script: ' + GUARD)
+  process.exit(1)
+}
+if (!existsSync(SETTINGS)) {
+  console.error('No settings file at ' + SETTINGS + '. Start Claude Code once, then run this again.')
+  process.exit(1)
+}
+
+const before = readFileSync(SETTINGS, 'utf8')
+let settings
+try {
+  settings = JSON.parse(before)
+} catch (e) {
+  console.error('settings.json is not valid JSON, so this will not touch it: ' + e.message)
+  process.exit(1)
+}
+
+const backup = SETTINGS + '.bak-before-guards'
+copyFileSync(SETTINGS, backup)
+
+const hooks = settings.hooks || (settings.hooks = {})
+const pre = hooks.PreToolUse || (hooks.PreToolUse = [])
+
+// Merge: never replace what is already there, and never register twice.
+let entry = pre.find((h) => h && h.matcher === MATCHER)
+if (!entry) {
+  entry = { matcher: MATCHER, hooks: [] }
+  pre.push(entry)
+}
+entry.hooks = entry.hooks || []
+const already = entry.hooks.find((h) => h && typeof h.command === 'string' && h.command.includes('guard.mjs'))
+if (already) {
+  already.command = command
+  console.log('  updated the existing guard entry to point at:')
+} else {
+  entry.hooks.push({ type: 'command', command })
+  console.log('  added a PreToolUse guard on ' + MATCHER + ':')
+}
+console.log('    ' + command)
+
+writeFileSync(SETTINGS, JSON.stringify(settings, null, 2))
+
+// Say what changed, at the level that matters: nothing else should have moved.
+const after = JSON.parse(readFileSync(SETTINGS, 'utf8'))
+const beforeParsed = JSON.parse(before)
+const keys = (o) => Object.keys(o).sort().join(',')
+console.log()
+console.log('  top-level keys before : ' + keys(beforeParsed))
+console.log('  top-level keys after  : ' + keys(after))
+console.log('  permissions untouched : ' +
+  (JSON.stringify(beforeParsed.permissions) === JSON.stringify(after.permissions)))
+console.log('  backup                : ' + backup)
+console.log()
+console.log('  Open /hooks in Claude Code once (or restart) so the new configuration is read.')
+console.log('  To remove it later: delete the entry from ' + SETTINGS + ', or restore the backup.')

package/hooks/prove.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Prove each guard fires, and that ordinary work does not.
+ *
+ * A guard that cannot be seen to refuse is not a guard, and one that refuses the wrong thing is
+ * worse than none - it gets switched off within a week and takes the working guards with it. So
+ * every case below is run for real against `guard.mjs`, and the allow cases matter as much as the
+ * deny cases.
+ */
+
+import { spawn } from 'node:child_process'
+import { writeFileSync, mkdtempSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const GUARD = join(dirname(fileURLToPath(import.meta.url)), 'guard.mjs')
+
+function ask(payload) {
+  return new Promise((resolve) => {
+    const p = spawn(process.execPath, [GUARD], { stdio: ['pipe', 'pipe', 'ignore'] })
+    let out = ''
+    p.stdout.on('data', (c) => { out += c })
+    p.on('close', () => {
+      let d = {}
+      try { d = JSON.parse(out || '{}') } catch { /* treated as allow */ }
+      const h = d.hookSpecificOutput || {}
+      resolve({ denied: h.permissionDecision === 'deny', reason: h.permissionDecisionReason || '' })
+    })
+    p.stdin.write(JSON.stringify(payload))
+    p.stdin.end()
+  })
+}
+
+// A real file, so the Edit guard has something true to check against.
+const dir = mkdtempSync(join(tmpdir(), 'guard-proof-'))
+const file = join(dir, 'sample.txt')
+writeFileSync(file, 'first line\n    indented line\nlast line\n')
+
+const CASES = [
+  // --- must be REFUSED -------------------------------------------------------------------------
+  { deny: true, name: '/tmp written in bash, read by python',
+    p: { tool_name: 'Bash', tool_input: { command: "echo hi > /tmp/x.txt && python3 /tmp/x.txt" } } },
+  { deny: true, name: 'python heredoc with a backslash before a quote',
+    p: { tool_name: 'Bash', tool_input: { command: "python3 - <<'PY'\nprint('a'.replace('\\','/'))\nPY" } } },
+  { deny: true, name: 'PowerShell &&',
+    p: { tool_name: 'PowerShell', tool_input: { command: 'git add -A && git commit -m x' } } },
+  { deny: true, name: 'Edit whose text is not in the file',
+    p: { tool_name: 'Edit', tool_input: { file_path: file, old_string: 'this text was never there' } } },
+  // Six spaces where the file has four - deeper, so it cannot accidentally be a substring. Written
+  // this way after two wrong attempts: searching with LESS indentation than the file has still
+  // matches, because the shorter run of spaces sits inside the longer one. The guard was right both
+  // times and the test was wrong, which is the sort of thing only running it tells you.
+  { deny: true, name: 'Edit whose indentation differs (6 spaces vs 4)',
+    p: { tool_name: 'Edit', tool_input: { file_path: file, old_string: '      indented line\nlast line' } } },
+
+  // --- must be ALLOWED: ordinary work, and near-misses ------------------------------------------
+  { deny: false, name: 'bash using /tmp on its own (no python, no node)',
+    p: { tool_name: 'Bash', tool_input: { command: 'echo hi > /tmp/x.txt; cat /tmp/x.txt' } } },
+  { deny: false, name: 'python heredoc with no backslash at all',
+    p: { tool_name: 'Bash', tool_input: { command: "python3 - <<'PY'\nprint('hello')\nPY" } } },
+  { deny: false, name: 'PowerShell using ; instead of &&',
+    p: { tool_name: 'PowerShell', tool_input: { command: 'git add -A; if ($?) { git commit -m x }' } } },
+  { deny: false, name: 'Edit that really does match',
+    p: { tool_name: 'Edit', tool_input: { file_path: file, old_string: 'first line' } } },
+  { deny: false, name: 'Edit on a file that does not exist yet',
+    p: { tool_name: 'Edit', tool_input: { file_path: join(dir, 'nope.txt'), old_string: 'x' } } },
+  { deny: false, name: 'an ordinary command',
+    p: { tool_name: 'Bash', tool_input: { command: 'git status --short' } } },
+]
+
+let bad = 0
+console.log('  ' + 'expected'.padEnd(10) + 'got'.padEnd(10) + 'case')
+for (const c of CASES) {
+  const r = await ask(c.p)
+  const ok = r.denied === c.deny
+  if (!ok) bad++
+  console.log('  ' + (c.deny ? 'deny' : 'allow').padEnd(10) +
+              (r.denied ? 'deny' : 'allow').padEnd(10) +
+              (ok ? '   ' : '!! ') + c.name)
+  if (r.denied && c.deny) console.log('             -> ' + r.reason.split('. ')[0] + '.')
+}
+console.log()
+console.log(bad === 0
+  ? '  All ' + CASES.length + ' cases behaved as specified.'
+  : '  ' + bad + ' of ' + CASES.length + ' did NOT. The guard is not trustworthy until they do.')
+process.exit(bad === 0 ? 0 : 1)

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-session-recall",
+  "version": "1.0.0",
+  "description": "Read your Claude Code session's own transcript. See how many times it was compacted, and whether a fact you are relying on was ever measured or only inherited from a summary.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-code-skill",
+    "compaction",
+    "context-window",
+    "transcript",
+    "ai-coding-assistant",
+    "anthropic",
+    "agent-memory"
+  ],
+  "homepage": "https://github.com/CavsSatyamKhatri/claude-session-recall#readme",
+  "bugs": "https://github.com/CavsSatyamKhatri/claude-session-recall/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CavsSatyamKhatri/claude-session-recall.git"
+  },
+  "license": "MIT",
+  "author": "Satyam Khatri",
+  "type": "module",
+  "bin": {
+    "claude-session-recall": "recall.mjs",
+    "recall-session": "recall.mjs"
+  },
+  "files": [
+    "recall.mjs",
+    "demo.mjs",
+    "SKILL.md",
+    "hooks/",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node hooks/prove.mjs"
+  }
+}

package/recall.mjs

@@ -0,0 +1,453 @@
+#!/usr/bin/env node
+/**
+ * Read the session's own record, and find out where a "fact" came from.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * When a conversation is compacted, what survives is a SUMMARY - chosen, compressed and written by
+ * the assistant. The full record is not deleted; it stays in the session transcript. But nothing
+ * points at it, so a fact that arrived through a summary looks exactly like a fact that was
+ * measured, and gets acted on as though it were one.
+ *
+ * The session this came out of had been compacted 28 times, and nothing anywhere said so. One of
+ * its summaries carried a version number and the words "still pending". Both were wrong - the
+ * thing had already shipped - and the claim survived several more compactions, was written into
+ * plans, and was repeated for hours before anyone thought to check it.
+ *
+ * Tracing it afterwards took one command, and showed zero occurrences in the record before the
+ * summary that asserted it. The number had never been measured. It had been inherited.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ * --------------------------------
+ * It builds no index and caches nothing. A 467-million-character transcript searches in about a
+ * second, so a stored summary of it would buy nothing measurable and would go stale - which is the
+ * exact failure this exists to prevent. It also never judges whether a claim is TRUE; it shows
+ * where the claim entered and leaves the judgement to a person, because a tool that confidently
+ * answers a question it cannot actually answer is the disease, not the cure.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const NL = String.fromCharCode(10)
+
+/**
+ * The transcript being written right now.
+ *
+ * By modification time rather than by deriving the project folder from the working directory: that
+ * folder is a slug of the path whose casing is not consistent (`C--Users-Admin` sits beside
+ * `d--Projects-...`), and a wrong guess reads somebody else's session. The live transcript is the
+ * one being appended to, which is a fact rather than a convention.
+ */
+function liveTranscript(explicit) {
+  if (explicit) return explicit
+  const root = join(homedir(), '.claude', 'projects')
+  if (!existsSync(root)) throw new Error('No transcripts at ' + root)
+  let best = null
+  for (const dir of readdirSync(root)) {
+    const d = join(root, dir)
+    let st
+    try { st = statSync(d) } catch { continue }
+    if (!st.isDirectory()) continue
+    for (const f of readdirSync(d)) {
+      if (!f.endsWith('.jsonl')) continue
+      const p = join(d, f)
+      const s = statSync(p)
+      if (!best || s.mtimeMs > best.mtimeMs) best = { path: p, mtimeMs: s.mtimeMs }
+    }
+  }
+  if (!best) throw new Error('No .jsonl transcript under ' + root)
+  return best.path
+}
+
+/** The whole file, once. Everything below works off this. */
+function load(path) {
+  const text = readFileSync(path, 'utf8')
+  return { text, lines: text.split(NL) }
+}
+
+function textOf(entry) {
+  const c = entry && entry.message && entry.message.content
+  if (typeof c === 'string') return c
+  if (Array.isArray(c)) return c.filter((b) => b && b.type === 'text').map((b) => b.text).join(' ')
+  return ''
+}
+
+/** The compaction boundaries, and what each summary carried. */
+function compactions(lines, withText) {
+  const out = []
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (!l || l.indexOf('"isCompactSummary"') < 0) continue
+    let d
+    try { d = JSON.parse(l) } catch { continue }
+    if (!d.isCompactSummary) continue
+    const t = textOf(d)
+    out.push({ line: i + 1, when: d.timestamp || '', chars: t.length, text: withText ? t : '' })
+  }
+  return out
+}
+
+/**
+ * Sentences in a summary that assert a checkable fact.
+ *
+ * This is a HEURISTIC and it is meant to be one: it produces a starting list, never a verdict. The
+ * shapes it looks for are the ones that went wrong in practice - a version number, a count, and the
+ * words that quietly turn a past observation into a present-tense claim ("still", "remains",
+ * "pending", "already"). A sentence it misses is not cleared; a sentence it flags is not guilty.
+ */
+function claimSentences(text) {
+  const SHAPES = [
+    { name: 'version', re: /\bv?\d+\.\d+(\.\d+)?\b/ },
+    { name: 'state', re: /\b(still|remains?|pending|not yet|already|never|unchanged|outstanding)\b/i },
+    { name: 'count', re: /\b\d{1,6}\s+(of|out of)\s+\d{1,6}\b|\b\d{2,6}\s+(tests?|files?|screens?|rows?|commits?|devices?)\b/i },
+    { name: 'done', re: /\b(is|are|was|were)\s+(done|built|deployed|published|fixed|complete|live)\b/i },
+  ]
+  const out = []
+  // Split on sentence ends and on list-item boundaries: summaries are mostly bullets.
+  for (const raw of text.split(/(?:\r?\n)+|(?<=[.!?])\s+/)) {
+    const s = raw.replace(/\s+/g, ' ').trim().replace(/^[-*\d.)\s]+/, '')
+    if (s.length < 25 || s.length > 240) continue
+    const tags = SHAPES.filter((sh) => sh.re.test(s)).map((sh) => sh.name)
+    if (tags.length === 0) continue
+    out.push({ text: s, tags })
+  }
+  return out
+}
+
+/**
+ * The most distinctive run of words in a sentence - what to hand to `trace`.
+ *
+ * Markdown and quotes are stripped first. A summary is written in markdown, so a phrase lifted from
+ * it carries `**` and backticks that are not in the underlying record - and an embedded double
+ * quote would break the shell command this is printed as. Both were found by running it.
+ */
+function tracePhrase(sentence) {
+  const clean = sentence.replace(/[*`"]/g, '').replace(/\s+/g, ' ').trim()
+  const words = clean.split(' ').filter(Boolean)
+  // Long enough to be unique, short enough to survive re-wording between summaries.
+  const n = Math.min(8, words.length)
+  let best = words.slice(0, n).join(' ')
+  for (let i = 0; i + n <= words.length; i++) {
+    const w = words.slice(i, i + n)
+    // Prefer a window that carries a number: that is the part that is checkable.
+    if (/\d/.test(w.join(' '))) { best = w.join(' '); break }
+  }
+  return best.replace(/^[^\w]+|[^\w.)%]+$/g, '')
+}
+
+/** The human's own messages - the natural boundaries of what was asked for. */
+function humanTurns(lines) {
+  const out = []
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (!l || l.indexOf('"type":"user"') < 0) continue
+    let d
+    try { d = JSON.parse(l) } catch { continue }
+    if (d.type !== 'user' || d.isCompactSummary) continue
+    const c = d.message && d.message.content
+    let text = null
+    if (typeof c === 'string') text = c
+    else if (Array.isArray(c)) {
+      // A tool result is recorded as a user message too. It is not something a person said.
+      if (c.some((b) => b && b.type === 'tool_result')) continue
+      text = c.filter((b) => b && b.type === 'text').map((b) => b.text).join(' ')
+    }
+    if (!text || !text.trim()) continue
+    if (text.trimStart().startsWith('<system-reminder>')) continue
+    out.push({ line: i + 1, when: d.timestamp || '', text: text.trim().replace(/\s+/g, ' ') })
+  }
+  return out
+}
+
+/** Offset -> line number, built once so many hits cost no more than one. */
+function lineIndex(text) {
+  const starts = [0]
+  let i = text.indexOf(NL)
+  while (i >= 0) { starts.push(i + 1); i = text.indexOf(NL, i + 1) }
+  return (off) => {
+    let lo = 0, hi = starts.length - 1, ans = 0
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1
+      if (starts[mid] <= off) { ans = mid; lo = mid + 1 } else hi = mid - 1
+    }
+    return ans + 1
+  }
+}
+
+/** Every byte-exact occurrence of a term. */
+function occurrences(text, term, cap) {
+  const lineOf = lineIndex(text)
+  const hits = []
+  let from = 0
+  while (hits.length < (cap || 400)) {
+    const i = text.indexOf(term, from)
+    if (i < 0) break
+    from = i + term.length
+    hits.push({ off: i, line: lineOf(i) })
+  }
+  return hits
+}
+
+const args = process.argv.slice(2)
+const cmd = args[0]
+const fileArg = args.indexOf('--file') >= 0 ? args[args.indexOf('--file') + 1] : null
+const path = liveTranscript(fileArg)
+const say = (s) => console.log(s === undefined ? '' : s)
+
+const COMMANDS = {}
+
+COMMANDS.compactions = {
+  use: "compactions",
+  blurb: "how many times this session was compacted, and when",
+  run() {
+  const { lines } = load(path)
+  const cs = compactions(lines)
+  say(path)
+  say()
+  if (cs.length === 0) {
+    say('  Never compacted. Everything in context arrived first-hand.')
+  } else {
+    say('  Compacted ' + cs.length + ' time(s). Everything you "remember" from before the last one')
+    say('  reached you through a summary somebody wrote, not through the record.')
+    say()
+
+    // The most recent few, not all of them. A long session produces dozens, and printing every
+    // one scrolls the count - the only number that matters here - off the top of the terminal.
+    // `recall compactions all` prints the lot.
+    const all = args[1] === 'all'
+    const shown = all ? cs : cs.slice(-6)
+    if (shown.length < cs.length) {
+      say('    ... ' + (cs.length - shown.length) + ' earlier, back to ' +
+          cs[0].when.slice(0, 10) + '    (recall compactions all)')
+    }
+    for (const c of shown) {
+      say('    #' + String(cs.indexOf(c) + 1).padStart(2) + '  line ' + String(c.line).padStart(7) +
+          '  ' + c.when.slice(0, 16).replace('T', ' ') +
+          '  summary of ' + c.chars.toLocaleString('en-US') + ' chars')
+    }
+    say()
+    say('  ' + cs.reduce((n, c) => n + c.chars, 0).toLocaleString('en-US') +
+        ' characters of summary have stood in for the record so far.')
+  }
+  },
+}
+
+COMMANDS.errors = {
+  use: "errors",
+  blurb: "mechanical failures in this record - the ones a hook could refuse",
+  run() {
+  /**
+   * Count the mechanical failures in your own record.
+   *
+   * Not "mistakes" in general - only the ones a machine can recognise from the error it produced,
+   * and therefore the only ones a hook could have refused before they happened. Each is a wasted
+   * round-trip: a command that could not have worked, sent anyway.
+   */
+  const PATTERNS = [
+    ['SyntaxError', 'a script that could not parse'],
+    ['command not found', 'a command that is not on this machine'],
+    ["No such file or directory: '/tmp/", '/tmp meaning two different places'],
+    ['unexpected EOF while looking for matching', 'unbalanced quoting in a shell command'],
+    ['String to replace not found', 'an Edit whose text was not in the file'],
+    ['unterminated string literal', 'a backslash inside a Python string'],
+    ['is not a valid statement separator', '&& in Windows PowerShell'],
+    ['ModuleNotFoundError', 'a Python import that is not installed'],
+    ['is not recognized as the name of a cmdlet', 'a unix command typed into PowerShell'],
+  ]
+  const { text } = load(path)
+  say(path)
+  say()
+  say('  Mechanical failures in this record - each one a round-trip that could not have worked:')
+  say()
+  let total = 0
+  const rows = PATTERNS.map(([p, what]) => {
+    let n = 0, from = 0
+    for (;;) { const i = text.indexOf(p, from); if (i < 0) break; n++; from = i + p.length }
+    total += n
+    return { p, what, n }
+  }).sort((a, b) => b.n - a.n)
+  for (const r of rows) {
+    if (r.n === 0) continue
+    say('    ' + String(r.n).padStart(6) + '   ' + r.what)
+    say('             ' + r.p)
+  }
+  say()
+  say('    ' + String(total).padStart(6) + '   in total')
+  say()
+  say('  Every one of these is recognisable before the command runs, which is what hooks/guard.mjs')
+  say('  refuses. Counting them here rather than quoting somebody else\'s number: yours are the')
+  say('  ones that matter, and they are the argument for installing the guards or not.')
+  say()
+  say('  (Some hits are the error being discussed rather than thrown - this counts text, not events.)')
+  },
+}
+
+COMMANDS.claims = {
+  use: "claims [n] [max]",
+  blurb: "what a summary asserts, each with a ready-made trace",
+  run() {
+  const { lines } = load(path)
+  const cs = compactions(lines, true)
+  say(path)
+  say()
+  if (cs.length === 0) {
+    say('  Never compacted, so nothing in your context was inherited. Nothing to check.')
+  } else {
+    const which = Number(args[1]) || cs.length
+    const c = cs[Math.max(0, Math.min(cs.length, which) - 1)]
+    const found = claimSentences(c.text)
+    say('  Summary #' + which + ' of ' + cs.length + ', line ' + c.line + ', ' +
+        c.when.slice(0, 16).replace('T', ' ') + ', ' + c.chars.toLocaleString('en-US') + ' chars.')
+    say('  ' + found.length + ' sentence(s) in it assert something checkable.')
+    say()
+    say('  This is a starting list, not a verdict: a sentence here is not wrong, and one that is')
+    say('  missing is not cleared. Trace the ones your next decision depends on.')
+    say()
+    found.slice(0, Number(args[2]) || 15).forEach((f, i) => {
+      say('  ' + String(i + 1).padStart(2) + '. [' + f.tags.join(',') + '] ' + f.text.slice(0, 150))
+      say('      recall trace "' + tracePhrase(f.text) + '"')
+      say()
+    })
+    if (found.length > (Number(args[2]) || 15)) {
+      say('  ... ' + (found.length - (Number(args[2]) || 15)) + ' more; pass a count: recall claims ' + which + ' 40')
+    }
+  }
+  },
+}
+
+COMMANDS.trace = {
+  use: "trace \"<text>\"",
+  blurb: "where did this fact enter? the record, or only a summary?",
+  run() {
+  const term = args[1]
+  if (!term) { console.error('usage: recall trace "<exact text>"'); process.exit(2) }
+  const { text, lines } = load(path)
+  const summaryLines = new Set(compactions(lines).map((c) => c.line))
+  const hits = occurrences(text, term)
+
+  say(path)
+  say()
+  if (hits.length === 0) {
+    say('  "' + term + '" does not appear in the record at all.')
+    say('  If something in your context asserts it, that assertion is its only source.')
+  } else {
+    const inSummary = hits.filter((h) => summaryLines.has(h.line))
+    const inRecord = hits.filter((h) => !summaryLines.has(h.line))
+    say('  "' + term + '" - ' + hits.length + ' occurrence(s): ' +
+        inRecord.length + ' in the record, ' + inSummary.length + ' inside compaction summaries.')
+    say()
+
+    if (inSummary.length === 0) {
+      say('  Never carried by a summary. It is in the record itself, first at line ' +
+          inRecord[0].line + '.')
+      say('  Read it with:  recall around ' + inRecord[0].line)
+      say('  and ask whether it was MEASURED there, or merely written down.')
+    } else {
+      // The question worth asking is not "does it appear" but "was it in the record BEFORE a
+      // summary asserted it". A summary that is the earliest source is a summary that invented,
+      // or inherited, the claim - and everything after it is repetition, not evidence.
+      const firstSummary = inSummary[0].line
+      const earlier = inRecord.filter((h) => h.line < firstSummary)
+      say('  First stated in a compaction summary at line ' + firstSummary + '.')
+      say('  Occurrences in the record BEFORE that: ' + earlier.length)
+      say()
+      if (earlier.length === 0) {
+        say('  THE SUMMARY IS THE ORIGIN. Nothing in the record measured this before a summary')
+        say('  asserted it, so there is no evidence behind it in this session. Measure it now')
+        say('  rather than repeating it.')
+      } else {
+        say('  It was in the record first, earliest at line ' + earlier[0].line + '.')
+        say('  Read it with:  recall around ' + earlier[0].line)
+        say('  and ask whether it was MEASURED there, or merely written down.')
+      }
+      const later = inRecord.filter((h) => h.line > firstSummary)
+      if (later.length) {
+        say()
+        say('  (' + later.length + ' occurrence(s) after the summary - repetition, and possibly this')
+        say('  very command: your own search lands in the record too.)')
+      }
+    }
+  }
+  },
+}
+
+COMMANDS.turns = {
+  use: "turns [n]",
+  blurb: "the last n things the operator asked for, with line numbers",
+  run() {
+  const limit = Number(args[1]) || 40
+  const { lines } = load(path)
+  const turns = humanTurns(lines)
+  say(path)
+  say(turns.length + ' things the operator asked for; newest ' + Math.min(limit, turns.length) + ':')
+  say()
+  for (const t of turns.slice(-limit)) {
+    say('  line ' + String(t.line).padStart(7) + '  ' + t.when.slice(0, 16).replace('T', ' ') +
+        '  ' + t.text.slice(0, 110))
+  }
+  },
+}
+
+COMMANDS.find = {
+  use: "find \"<text>\"",
+  blurb: "every byte-exact occurrence, with surrounding context",
+  run() {
+  const term = args[1]
+  if (!term) { console.error('usage: recall find "<exact text>"'); process.exit(2) }
+  const pad = Number(args[2]) || 90
+  const { text } = load(path)
+  const hits = occurrences(text, term, 30)
+  say(path)
+  say('"' + term + '" - ' + hits.length + (hits.length >= 30 ? '+' : '') + ' occurrence(s)')
+  say()
+  for (const h of hits) {
+    const s = text.slice(Math.max(0, h.off - pad), h.off + term.length + pad).replace(/\s+/g, ' ')
+    say('  line ' + String(h.line).padStart(7) + '  ...' + s + '...')
+  }
+  if (hits.length === 0) say('  Not in the record.')
+  },
+}
+
+COMMANDS.around = {
+  use: "around <line>",
+  blurb: "what was being worked on near that point",
+  run() {
+  const target = Number(args[1])
+  if (!target) { console.error('usage: recall around <line>'); process.exit(2) }
+  const { lines } = load(path)
+  const turns = humanTurns(lines)
+  const before = turns.filter((t) => t.line <= target).slice(-3)
+  const after = turns.filter((t) => t.line > target).slice(0, 2)
+  say(path)
+  say('what was being asked for around line ' + target + ':')
+  say()
+  for (const t of before.concat(after)) {
+    say('  ' + (t.line <= target ? ' ' : '>') + ' line ' + String(t.line).padStart(7) +
+        '  ' + t.when.slice(0, 16).replace('T', ' ') + '  ' + t.text.slice(0, 110))
+  }
+  },
+}
+
+/**
+ * One table, so a command that exists is listed and a listed command exists.
+ *
+ * The help used to be written out separately, and drifted the first time commands were added: two
+ * of them worked and appeared nowhere. Generating it from the same object the dispatch reads makes
+ * that impossible rather than unlikely.
+ */
+function help() {
+  const width = Math.max(...Object.values(COMMANDS).map((c) => c.use.length)) + 2
+  say('recall - read this session\'s own record, so an inherited "fact" can be checked.')
+  say()
+  for (const c of Object.values(COMMANDS)) say('  recall ' + c.use.padEnd(width) + c.blurb)
+  say()
+  say('  --file ' + '<path>'.padEnd(width) + 'an older transcript instead of the live one')
+  say()
+  say('Nothing is written and nothing is cached; the record is searched directly.')
+}
+
+const chosen = COMMANDS[cmd]
+if (chosen) chosen.run()
+else help()