[JetSquirrel]

Closes #69. Part of #64.

Why

A person or the next agent picking up an analysis had no way to see what a conclusion rested on, or whether it still held. History records queries, but not sources, versions or completeness, and not which queries a finding used.

What

export DUCKLOCAL_SESSION=analysis.session.jsonl    # query, check, propose, open now record themselves
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20                   # or --format md, for reading
ducklocal session get --seq 4                      # one step whole, such as a spec's text
ducklocal session snapshot                         # what the window shows: tabs, SQL, filter picks
ducklocal session clear analysis.session.jsonl

The main idea is doubts, worked out when you read the file. Each step and conclusion lists what failed, was cut off or went unchecked, or whose source, database or spec has changed since:

{"text": "EU leads", "latest": false, "steps_since": 3,
 "doubts": ["#1: orders.csv has changed since"]}

So a truncated result is never shown as complete, and an old conclusion says what has moved under it. An empty list means nothing is known against it, not that it's right, and the docs say so.

It's recorded per file, and only when asked. One JSON Lines file, named by whoever wants it, so there's no central store and no retention policy to invent: it stays until you clear it.

What's kept out

• Rows: never. Sources are recorded by reference, with size and date. snapshot strips previews.
• Credentials: SQL or a spec that may hold them is left out whole, including its hash, since a hash of a short secret can be guessed. Remote addresses lose their query string.

Limits to review

• The credential check is a word search, tuned to err towards leaving text out. A column named secret or token costs you that query's text. It can also miss a credential in an unusual form, such as a key pasted as a plain string. I'd treat a session file as sensitive either way, and the skill says to keep it out of shared folders unless the person agrees.
• Errors are kept, cut to 500 characters, and can quote values, since DuckDB's messages sometimes do. That's the one place data can reach the file. Dropping errors would lose why something failed; tell me if you'd prefer that.
• Sources are known only for a SELECT with plain paths. read_csv(['a.csv', 'b.csv']) or a COPY reports "its sources could not be read from the SQL" rather than a partial list.
• Change detection uses size and modification time, not contents, because hashing large data on every query is too slow. An edit that keeps both isn't noticed.
• origin is just what the environment says, and nothing checks it. The docs say so.
• The person's actions in the window aren't recorded, except through snapshot and how a proposal ended. There's no timeline in the GUI yet; --format md is the readable view. The issue allowed a summary, but a GUI view would be a natural next step.

Other changes

check --summary now also lists truncated queries, an addition. Passing says nothing about them, and the session needs to know.

Testing

• tests/cli.rs runs the real commands end to end: no recording without the variable, no rows or credentials in the file, failed and refused queries, truncation, a source changing and then disappearing, spec revisions, proposals, manual clearing, and refusing to overwrite or delete a file that isn't a session.
• session::tests cover credentials, parser references, source and glob fingerprints, and a cut-off line. The parser test also pins the JSON shape of DuckDB 2.0's json_serialize_sql, which I got wrong at first; a DuckDB upgrade that changes it fails there.
• cargo test --locked: 466 unit, 32 CLI and 8 LSP tests pass. Clippy and fmt are clean.

Not tested against a real window: record_open and session snapshot. On Windows that would write to my local history and saved tabs. Stripping rows from a state is unit-tested, and session snapshot with no window running should exit 1 with kind not_running.

Docs are in session --help, the skill and the CLI reference. If #76 merges first, the README line may need a small merge.

🤖 Generated with Claude Code