@raibitsi/tiresias 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/CHANGELOG.md +199 -0
  2. package/README.md +50 -27
  3. package/dist/background.js +6 -3
  4. package/dist/browsecli.js +4 -3
  5. package/dist/cdp.js +22 -1
  6. package/dist/cli.js +82 -29
  7. package/dist/config.js +32 -26
  8. package/dist/confirm.js +16 -7
  9. package/dist/cooldown.js +65 -34
  10. package/dist/dailylog.js +11 -5
  11. package/dist/engine.js +5 -4
  12. package/dist/envelope.js +20 -2
  13. package/dist/fetcher.js +5 -0
  14. package/dist/filereply.js +7 -1
  15. package/dist/files.js +4 -4
  16. package/dist/formflow.js +21 -3
  17. package/dist/forms.js +257 -34
  18. package/dist/getactions.js +99 -0
  19. package/dist/history.js +8 -5
  20. package/dist/hook.js +2 -0
  21. package/dist/hosts.js +15 -13
  22. package/dist/inside.js +2 -2
  23. package/dist/inspect.js +4 -1
  24. package/dist/keys.js +420 -18
  25. package/dist/mcp.js +10 -10
  26. package/dist/needs.js +9 -5
  27. package/dist/parentwatch.js +6 -16
  28. package/dist/pdf.js +4 -1
  29. package/dist/pdfchild.js +0 -2
  30. package/dist/pdfproc.js +26 -11
  31. package/dist/pdfwatch.js +14 -0
  32. package/dist/pipeline.js +25 -8
  33. package/dist/profiles.js +3 -3
  34. package/dist/queue.js +15 -7
  35. package/dist/reader.js +43 -18
  36. package/dist/receipts.js +2 -2
  37. package/dist/render.js +103 -24
  38. package/dist/resume.js +17 -8
  39. package/dist/rules.js +29 -7
  40. package/dist/safebrowsing.js +3 -3
  41. package/dist/safety.js +9 -3
  42. package/dist/sandbox.js +1 -1
  43. package/dist/saved.js +108 -60
  44. package/dist/savedlock.js +208 -0
  45. package/dist/settings.js +7 -3
  46. package/dist/shelf.js +1 -1
  47. package/dist/sites.js +9 -4
  48. package/dist/slips.js +43 -1
  49. package/dist/store.js +119 -25
  50. package/dist/tabs.js +1 -1
  51. package/dist/textview.js +10 -0
  52. package/dist/translate.js +22 -2
  53. package/dist/types.js +2 -2
  54. package/dist/watchflow.js +1 -2
  55. package/dist/work.js +4 -2
  56. package/package.json +2 -1
package/CHANGELOG.md ADDED
@@ -0,0 +1,199 @@
1
+ # Changelog
2
+
3
+ Built from docs/SPEC.md, section 10, which has the full detail of every version.
4
+
5
+ ## v1.1.0 (2026-11-10)
6
+
7
+ The security deep dive. Every promise in SECURITY.md was attacked end to end, the way a hostile page or a fooled agent would, and each finding was fixed with a test or written down as a known limit in SECURITY.md.
8
+
9
+ For owners:
10
+
11
+ - Four new settings, shown in `tiresias settings`. `get_form_actions` is `read` by default; `slip` makes reading an address that matches a known GET form action need a `submit_form` slip. `private_spacing` is `shared` by default, so private calls and previews now wait their turn across processes and write only the site's origin and times; `none` turns that off after confirmation. `hook_secrets` is `hidden` by default, so your scanner and translator hooks no longer receive Tiresias's own secret variables; `inherit` restores the old behavior after confirmation. `text_views` is `marked` by default, so `--text` views and the default `log` and `needs` output mark where web text begins; `wrapped` wraps it the way JSON output does.
12
+ - `tiresias keys rotate` gives you a new signing key while the old one stays in the directory for 7 days (`--overlap` 0 to 30). `--finish` ends the overlap early. `--slips` makes a new slip key and revokes every slip.
13
+ - SECURITY.md states the form promise as the code keeps it: no form is sent without your permission slip, and recognizing sign-in, payment and purchase forms is best-effort in 13 languages.
14
+
15
+ Forms:
16
+
17
+ - Purchase forms without card fields ("Pay now", checkout) and sign-in forms without a password field are now recognized and refused. Recognition is by word lists in English, Spanish, French, German, Portuguese, Italian, Dutch, Russian, Chinese, Japanese, Korean, Arabic and Hindi.
18
+ - A slip is checked again right before the form is sent. One that expired or was revoked while the submit waited is not used.
19
+ - A rendered page's scripts may not request an address that matches a GET form action on that page.
20
+
21
+ The site's rules:
22
+
23
+ - A robots.txt redirect to another site is followed only to that site's own `/robots.txt`. Anything else counts as the site saying no.
24
+ - Retry-After on a redirect is obeyed before the redirect is followed, for pages, robots.txt and rendered requests.
25
+ - A Crawl-delay longer than 30 seconds is no longer shortened to 30: Tiresias declines the read instead of waiting less than the site asked. When robots groups merge, the longest delay applies.
26
+ - An active Retry-After wait is not forgotten however large the cooldown log grows. If the wait cannot be read, Tiresias does not send.
27
+
28
+ Web text stays data:
29
+
30
+ - Machine translations are scanned by the injection shield. Flags stay with the reply, with snippets inside `untrusted_content`, and survive a translation dropped for size.
31
+ - A bookmark name chosen by an agent appears inside `untrusted_content` in `watch` replies, not beside Tiresias's own fields.
32
+ - Text an agent supplies to `resume` over MCP is recorded as provided by the agent, not by a person.
33
+
34
+ Secrets, files and limits:
35
+
36
+ - The Google Web Risk request gets the same private-address and port checks as every other request.
37
+ - The PDF child process may no longer start worker threads.
38
+ - Calendar files are always read in a worker thread with a time budget, whatever their size.
39
+ - A secret the site echoes back is looked for in the full text of an Office answer or a PDF title before anything is shortened.
40
+ - A page whose outline would take too long to build ends as `page_too_complex` instead of stalling other calls.
41
+ - Requests waiting during a render keep only a bounded set of header fields in memory.
42
+ - History and receipt scans stop on cancellation or at a 60 second deadline.
43
+
44
+ Testing and releases:
45
+
46
+ - An attack lab of hostile pages runs in the test suite, so every attack tried in this review stays tested.
47
+ - The fuzzer (`scripts/fuzz.mjs`, opt-in) gained two targets that drive the real MCP server and the form flow with malformed input.
48
+ - Releases are built by GitHub Actions and staged on npm through trusted publishing, with provenance and a software bill of materials. A person approves each staged version before anyone can install it, and no npm token is stored anywhere.
49
+
50
+ ## v1.0.1 (2026-11-01)
51
+
52
+ - Cancelling a read while it waits its turn no longer adds extra delays to later requests.
53
+ - An unexpected robots.txt “not modified” response is retried once; browsing stops if it answers “not modified” again without providing rules.
54
+ - Malformed Retry-After headers keep the normal fallback cooldown.
55
+ - Relative HTML links follow the page's first base URL; receipts still name the page that was read.
56
+ - Rendered text with many lines stays readable when its final lines are visible. Incomplete geometry is reported as a partial inspection.
57
+ - Emoji and other Unicode characters remain intact when text is split into blocks.
58
+ - Large plain-format reads report how much text was omitted.
59
+ - Cached pages honor the current rendering setting and each read's rendering request.
60
+ - Markdown alternatives keep the original URL's query parameters.
61
+ - Office text is withheld with its receipts when the reply cannot fit both.
62
+ - Known archive signatures keep their archive warning even when the filename claims to be an Office document or application.
63
+ - Concurrent page saves cannot exceed the snapshot cap or push out earlier evidence.
64
+ - Replacing site restrictions no longer breaks unrelated browsing while confirmed restrictions are retained.
65
+ - Active calls keep their starting settings, including their scanner and translator hooks.
66
+ - Listing settings in private mode creates nothing and leaves folder permissions alone.
67
+ - Resuming a handoff works when an unrelated storage limit is invalid.
68
+ - History keeps questions up to 1,000 characters, marks longer cuts, and keeps questions that differ after character 500 separate in the needs report.
69
+
70
+ ## v1.0.0 (2026-11-01)
71
+
72
+ The first public release. Tiresias is a browser for AI agents with no screen: your agent calls it over MCP (or you run it from the command line), it reads a page into a short outline with numbered links, answers questions with exact quotes and receipts, and says honestly who is calling. It obeys robots.txt and every request to wait, stops at a CAPTCHA, a bot check or a login and hands the page to you, and runs on your machine under your keys, with no account and no telemetry. macOS and Linux; Windows is not supported yet.
73
+
74
+ What the versions before it built, in one place:
75
+
76
+ - **Reading (v0.1, v0.5.1).** Outline first, then one section or the best quoted passages, in pages that fit a context window; markdown asked for first, `llms.txt` and `llms-full.txt` used, MCP servers, API specs and feeds reported. Every quote has a receipt. Page content always sits inside `untrusted_content`; hidden text, invisible characters and instructions aimed at an AI are flagged.
77
+ - **Honest by default (v0.1, v0.2).** A plain user agent, robots.txt, Crawl-delay and Retry-After on every request, one second between requests to a site, and optional Web Bot Auth signing of every request with your own key. Raibit's own copy is verified by Cloudflare (2026-11-01).
78
+ - **Memory (v0.3).** What changed since the last visit, a cache shared by every agent on the machine, bookmarks and a watchlist, a needs report, a hand-off ticket to resume a read after a person clears a wall, and a phishing check before every fetch (optionally Google Web Risk with your own key).
79
+ - **Permission (v0.4).** Profiles, and forms sent only with a permission slip you grant at a terminal; login, password, CAPTCHA and payment forms are never sent.
80
+ - **Files (v0.5, v0.6).** A file is named by its first bytes and comes back as a warning with its fingerprint, never run; zip listings, Office text and calendar invites are read in memory; your own virus checker can be plugged in. Tabs, a downloads shelf, per-site settings and a settings page.
81
+ - **JavaScript pages and languages (v0.7).** Rendering in the Google Chrome you already have, off until you allow it, with every request the page makes fetched under Tiresias's rules; walls and hidden text judged by what the browser shows; the language of every read; your own translator.
82
+ - **Proof (v0.8).** Signed snapshots of exactly what a read received, and free Bitcoin timestamps (OpenTimestamps) that prove a receipt existed then and was not edited.
83
+ - **Hardening (v0.9, v0.9.1).** Risky settings take an all-caps confirmation phrase and are logged; a security audit, a fuzz script, a memory ceiling for the MCP server and an optional Docker box; then every deferred finding from the reviews closed, so v1.0 ships with no known bug.
84
+
85
+ In this release: the docs were rewritten for a first-time reader (README, QUICKSTART, SECURITY.md, and a new docs/DEMO.md with real output), the install is `npm install -g @raibitsi/tiresias`, two failures seen only on Linux were fixed (the anchor's receipt cursor after a file is written again under the same inode; a test whose waits ended during a slow run), and two refusal texts no longer say "v0.x". The key directory signing guidance now covers live signing, which Cloudflare asks for.
86
+
87
+ **Upgrading from v0.8:** if you had turned on saving, rendering or anchoring, each is held off after the upgrade until you confirm it once, with whichever of these apply:
88
+
89
+ ```
90
+ tiresias settings confirm saving --confirm "YES, TURN ON SAVING"
91
+ tiresias settings confirm rendering --confirm "YES, TURN ON RENDERING"
92
+ tiresias settings confirm anchoring --confirm "YES, TURN ON ANCHORING"
93
+ ```
94
+
95
+ (`rendering` at `auto` takes `"YES, TURN ON AUTOMATIC RENDERING"`.) The first reply after the upgrade lists what is waiting, `tiresias mcp` prints it on standard error at start, and `tiresias settings` shows it. Upgrading from v0.9.x needs nothing.
96
+
97
+ ## v0.9.1 (2026-10-31)
98
+
99
+ The pre-v1.0 sweep. Every MEDIUM and LOW finding deferred from v0.7.0, v0.8.0 and v0.9.0 (67 in all) was closed: 64 fixed, each with a test that fails without the fix, and 3 designed away (the behavior decided and written down). Two of them were decided by Travis: on a rendered page, text with `pointer-events: none` that cannot be measured for clipping now makes the inspection partial so the HTML checks also run; and any background image or gradient counts as covering the text under it (it can flag text under a see-through decorative layer, but never shows hidden text). Google Web Risk lookups stay exempt from site spacing (they are calls to Google, not site visits). Codex wrote the fixes and Claude reviewed each one; then Codex reviewed the whole sweep until a round came back clean. The full list is in SPEC.md, section 10, v0.9.1.
100
+
101
+ What you may notice:
102
+
103
+ - **`tiresias mcp` now tells you on standard error when a setting is held back.** If config.json turns on a risky setting that has not been confirmed (the usual case after upgrading from v0.8 with saving, rendering or anchoring on), the server prints one line at start with the exact `tiresias settings confirm ... --confirm '...'` command for each. Your AI app usually keeps that in its MCP server log.
104
+ - **Rendered pages:** walls and hidden text are judged more exactly (text in `display: contents` wrappers, dark-scheme pages, `color()` and `oklch()` colours, `xmp` and `textarea` text, page elements named like browser built-ins, CAPTCHA and password boxes past the first 2,000 candidates). A failed render keeps the last good rendered copy; an explicit `render` renders again unless a rendered copy is still fresh by the site's own caching rules (`fresh: true` always renders again); cached rendered replies keep their walls and hidden-text codes; a redirected script or style is handed to Chrome as a redirect; a large fixed layer above the text gets its own overlay note.
105
+ - **Save page and receipts:** a snapshot is never written that `saved verify` would refuse; quotes containing NUL and pages with odd characters verify; Office receipts name their snapshot; `clear` counts what it really removed. A failed `saved verify` or `receipts verify` now prints `status: "error"` with `reason: "verification_failed"` on standard error (exit codes unchanged).
106
+ - **Anchoring:** a bad answer from one calendar can no longer spoil a batch another calendar served well; calendars' Retry-After is honored; very large stores keep every batch searchable and resume long scans; `receipts prove --out` cleans up after itself on failure.
107
+ - **Confirmations:** every reply path carries the settings notice; a 24-hour notice is never cut short; always-allowed ports and the default spacing no longer ask for a phrase; `scanner off` and `translator off` work while `sites` is broken; suggested commands put `--confirm` in the right place.
108
+ - **Reading:** markdown code keeps its indentation; very deep pages and lists stay within the time budget; an unsolicited "not modified" answer is never served from an older parse; a JavaScript-only page read without rendering says so; `resume` keeps `render` and `translate`; a cancelled read writes nothing; `history --text` and `receipts --text` start with a count line. The parser version is 14, so a page cached by the older reader is parsed again once.
109
+ - **pdf.js's native canvas add-on** that an `npm install -g` puts on disk stays unbundled on purpose (it is never loaded; bundling would tie outside security fixes to Tiresias releases). README says so.
110
+
111
+ ## v0.9.0 (2026-10-31)
112
+
113
+ Risky settings need confirmation (W-32). Turning a risky setting on or looser (`saving`, `rendering`, `translator`, `scanner` with `--send-file`, `anchoring`, `anchor_calendars`, `safe_browsing` off, and per site more `ports`, lower `spacing_seconds`, `never_visit` or `hand_off` off) takes an exact all-caps phrase naming it, passed as `--confirm` (for example `--confirm "YES, TURN ON SAVING"`); a wrong or missing phrase changes nothing and prints the phrase. Turning things off or stricter never asks. Each change is recorded in history and the daily log with who made it (a terminal or not, best effort), and CLI and MCP replies carry `settings_notice` for 24 hours. A hand edit of `config.json` that loosens is not in force until confirmed (`tiresias settings confirm`); the last confirmed state lives in `confirmations.json`, and no record means the safe defaults (an owner upgrading from v0.8 with a risky setting on confirms it once). `TIRESIAS_RENDERING`, `TIRESIAS_SAFE_BROWSING=0` and `TIRESIAS_ALLOW_PORTS` loosen only with their phrase in `TIRESIAS_CONFIRM`. `tiresias settings confirmations off|on` (each with its own phrase) stops or resumes the asking; `tiresias settings` shows the state. MCP still cannot read or change any setting. It stops accidents and casual page-text tricks, not a fully fooled agent; the log makes that visible. Full record: `docs/v0.9/confirm.md`.
114
+
115
+ **Upgrading from v0.8:** if you had turned on saving, rendering or anchoring, each is held off after the upgrade until you confirm it once. Run whichever apply:
116
+
117
+ ```
118
+ tiresias settings confirm saving --confirm "YES, TURN ON SAVING"
119
+ tiresias settings confirm rendering --confirm "YES, TURN ON RENDERING"
120
+ tiresias settings confirm anchoring --confirm "YES, TURN ON ANCHORING"
121
+ ```
122
+
123
+ (If you had `rendering` at `auto`, its phrase is `"YES, TURN ON AUTOMATIC RENDERING"`.) Until then the first reply after the upgrade, CLI or MCP, lists each held-off setting with its exact command, and `tiresias settings` shows what is waiting. If you use Tiresias only through an AI app, run `tiresias settings` once at a terminal after upgrading, since the notice reaches you only if the agent passes it on.
124
+
125
+ Hardening audit of the whole codebase as it will be published. A `SECURITY.md` threat model; SPDX license headers; `npm audit` fixes under the MCP SDK; an opt-in fuzz script (`npm run fuzz`). Fixed, each with a test: a `Content-Encoding` Tiresias does not decode now fails the request (a compressed robots.txt used to read as "no rules"); a robots.txt that is not text, any 2xx answer, a 206, and rules that write `*` or `$` as `%2A` / `%24` are all honored (unreadable means the site says no); the daily log is bounded; CLI `receipts` and `history` put their records inside `untrusted_content`, as MCP does; one MCP server runs at most 8 tool calls, 4 parser workers and 2 renders at once, with fixed-text refusals past their queues; the MCP message boundary caps arguments (1,000 elements, 8 MB) and open requests (64), pauses reading while output backs up, and never repeats a caller's text outside the envelope; bad dates get fixed texts; the in-process cooldown list is bounded (at most 10,000 waits by name, the rest in a fixed 8 MiB keyed store that never forgets or shortens a wait). README and SECURITY.md wording that overclaimed was corrected. Full record: `docs/v0.9/hardening.md`.
126
+
127
+ The MCP client is trusted, the server has a memory ceiling, and Docker is optional (W-33). The AI app that starts `tiresias mcp` is now trusted not to flood its own server (SECURITY.md says so; every limit stays). `tiresias mcp` runs the server under its own memory ceiling, `TIRESIAS_MEMORY_MB` (default 1024 MB, `off` to skip): at the ceiling it stops with a clear line on standard error and a "Server stopped" line in the daily log, and the app can start it again. A `Dockerfile` (official Node 22 slim image pinned by digest, non-root, rendering off) and `docs/docker.md` give advanced owners a hard box with memory, CPU and process limits and a read-only file system; same commands, same store. v1.0 will support macOS and Linux; Windows is not yet supported. Full record: `docs/v0.9/client-trust.md`.
128
+
129
+ A site's echo of a secret is withheld, not masked. When the answer to a sent form repeats a hidden value or a cookie the site set for that call (6 characters or more), Tiresias now withholds the whole answer (`form.reason: "secret_withheld"`, the HTTP status and size only) instead of masking it as `[hidden value]`. The answer is checked once as received, with HTML, percent and JSON escapes decoded and case, quotes and spaces ignored, and again before anything from it is recorded. `counts.receipts_withheld` is gone. Best effort, stated in SECURITY.md: an echo in an encoding Tiresias does not decode is not caught.
130
+
131
+ Private launch rehearsal: a newcomer's first hour, end to end (an npm tarball installed into a temporary prefix, a fresh home, the README followed literally, MCP through Claude Code and a small client, rendering, saving, anchoring against a local calendar, slips and forms, the upgrade from a v0.8 store, and the unhappy paths). Fixed what tripped them up: a label Tiresias makes, `(top of page)` and `(structured data)`, is no longer quoted in a receipt as if the page said it; `receipts --url https://example.com` finds what was recorded as `https://example.com/`; an older Node, a mistyped option, an address with no `https://`, a store folder that cannot be written and being offline each get a plain message saying what to do (the store one used to say "internal error"); `--text` prints a page read's receipt count instead of every receipt as JSON, and says so when a listing is empty; hints that name a risky setting now carry its phrase; `--help` starts with the first command to try. The README's Claude Code line uses `--scope user`, and states that an npm install puts pdf.js's optional native add-on on disk, where the PDF child's permission model keeps it from loading. New `docs/QUICKSTART.md` (shipped in the package). The recurring render flake under full-suite load (the first render of a test file starting Chrome cold under a shortened limit) is fixed in the tests. The parser version is 13, so a page cached by the older reader is parsed again. Full record: `docs/v0.9/rehearsal.md`.
132
+
133
+ ## v0.8.0 (2026-10-31)
134
+
135
+ Save page (W-28) and tamper-proof receipts (W-08). With the owner's new `saving` setting at `ask` (default `off`; owner only, never through MCP or an environment variable), `read --save` and the MCP read's `save` keep a snapshot in the profile's `saved/` folder: the bytes the read received (after transfer framing and Content-Encoding, before charset decoding) and, for a rendered read, the rendered HTML, with a `manifest.json` signed by the profile's slip key. The snapshot's id is the SHA-256 of the manifest's facts; every receipt of that read carries it as `snapshot`. `tiresias saved` lists, shows, verifies (re-hash, signature, and each receipt's quote found in the saved bytes by the same reader steps) and deletes snapshots. A save always fetches; private mode, `no-store` pages, walls and errors save nothing; a file warning saves only its fingerprint. Caps: `max_saved_mb` (100) and 1,000 snapshots, a save over them is refused, never evicting; `keep_saved_days` (90) through `clear` and the daily trim. Full record: `docs/v0.8/save.md`. And with the owner's new `anchoring` setting `on` (default `off`; owner only, never through MCP or an environment variable), `tiresias anchor` timestamps the fingerprints of new receipt records and saved snapshots through OpenTimestamps (free, Bitcoin-backed, no wallet or account): one Merkle tree per batch over salted leaves in a random order, and only its root sent to the calendars (`anchor_calendars`, default the four public ones), through Tiresias's own fetcher. `anchor status`, `anchor upgrade`; `tiresias receipts` shows each record's `record_fingerprint` (a file warning keeps its own `fingerprint`, the file's SHA-256); `receipts prove <id> [--out]` exports the record, salt, Merkle path and a standard `.ots` file; `receipts verify <bundle>` checks it offline and names the step that needs a Bitcoin block header. The OpenTimestamps format is implemented in `src/ots.ts` (no new package). Private mode is never anchored; each profile anchors separately; anchoring is never on the read path. Full record: `docs/v0.8/anchor.md`. At integration the receipts listing's new field was named `record_fingerprint`, so a file-warning record keeps its own `fingerprint`. Integration review also closed five private-mode gaps, three of them older than v0.8: a private session (`--private` or `TIRESIAS_PRIVATE=1`) now refuses `receipts prove --out`, `clear` (except `--dry-run`), `log --to`, `keys init` and `keys sign-directory --out`, and `tiresias mcp --private` now serves a private session (the flag used to be ignored). 16 MEDIUM and LOW findings are deferred to the compute-day sweep (docs/SPEC.md section 10).
136
+
137
+ ## v0.7.0 (2026-10-31)
138
+
139
+ JavaScript-only pages (W-10), translate (W-26), and walls and hidden text revisited with rendering (N-02, N-05). Optional rendering in the Google Chrome already installed, driven over a pipe with no new package, off by default and turned on only by the owner (`rendering` off|ask|auto); every request the page makes goes through Tiresias's own rules, under caps on time, requests and bytes. On a rendered page the browser decides walls and hidden text. Every read reports its language (13 languages, no dependency), the shield matches phrases aimed at an AI in all 13, and an optional owner-set translation hook (`tiresias translator`) answers `read` with `translate`. Every request is now counted and capped by the bytes its connection receives, for plain reads too. Built as three tracks, reviewed by Codex, then together; deferred MEDIUM and LOW findings are listed in SPEC.md, section 10, v0.7.0.
140
+
141
+ ## v0.6.1 (2026-10-30)
142
+
143
+ The compute-day sweep: the 10 MEDIUM and LOW findings deferred from v0.6.0, each fixed with a test (written by Codex, reviewed by Claude). Office parts with repeated or out-of-order containers are refused; long Office lines page in bounded blocks and the whole reply stays in its limit; receipts from a file a person saved keep their source; resume honors section and question for a saved Office file; Office answers to a sent form withhold receipts touched by hidden values before anything is logged; tabs honor current site settings for cached copies; the downloads shelf keeps the macros flag; `tiresias settings` lists `TIRESIAS_MAX_INSPECT_BYTES`. See SPEC.md, "Deferred to compute-day sweep".
144
+
145
+ ## v0.6.0 (2026-10-26)
146
+
147
+ Inside files, plus browser basics. Zip listing without unpacking, Office text without macros (with receipts, section paging and question search), and calendar events from `.ics` files; tabs and back/forward (W-24), the downloads shelf (W-27), site settings per host (W-25), the `tiresias settings` command (W-29) and a fast first read with the door checks in the background (W-30). Closes W-24, W-25, W-27, W-29, W-30 and the "Not in v0.5" items of section 4.4.
148
+
149
+ ## v0.5.0 (2026-10-20)
150
+
151
+ Released: dangerous files (W-20) and the owner's own scanner (W-21), built to the coordinator's scope in section 4.4, after Codex round 68, the final, severity-rated round, found nothing HIGH (`reviews/2026-10-20-codex-round-68.md`: 0 high, 1 medium, 1 low). The entries below are the work log kept while v0.5 was built.
152
+
153
+ ## v0.4.0 (2026-10-18)
154
+
155
+ Released: profiles (W-18), permission slips (W-05) and permission-gated forms (W-04), after Codex round 57 found nothing blocking. The entries below are the work log kept while v0.4 was built.
156
+
157
+ ## v0.3.0 (2026-10-17)
158
+
159
+ Released: needs report (W-12), diffs (W-02), bookmarks and watchlist (W-16), handoff and resume (W-06), shared cache (W-03), Safe Browsing (W-19), after Codex round 45 found nothing blocking. The entries below are the work log kept while v0.3 was built.
160
+
161
+ ## v0.2.0 (2026-10-17)
162
+
163
+ Released: signing (N-07), the daily log (W-13), private mode (W-14), storage limits (W-15) and PDFs (W-17), merged to main after Codex round 35 found nothing. **W-09:** submitted to Cloudflare's Bots and Agents Directory (BotBase) on 2026-10-17 as Tiresias, operator Raibit, Direct, category Agent, content use immediate, Web Bot Auth with the raibit.ai key directory. Status: waiting for review. The entries below are the work log kept while v0.2 was built.
164
+
165
+ ## v0.1.8 (2026-10-16)
166
+
167
+ Software release. Closes the six non-blocking items from Codex review round 8 (`reviews/2026-10-16-codex-round-8.md`: no blocking findings, ready for a private push).
168
+
169
+ ## v0.1.7 (2026-10-16)
170
+
171
+ Software release. Fixes Codex review round 7 (`reviews/2026-10-16-codex-round-7.md`: three blocking, two non-blocking).
172
+
173
+ ## v0.1.6 (2026-10-16)
174
+
175
+ Software release. Fixes Codex review round 6 (`reviews/2026-10-16-codex-round-6.md`: round 5 verified fixed; four blocking items from a whole-repo pass, one small regression).
176
+
177
+ ## v0.1.5 (2026-10-16)
178
+
179
+ Software release. Fixes Codex review round 5 (`reviews/2026-10-16-codex-round-5.md`: three blocking items in rotation, two small).
180
+
181
+ ## v0.1.4 (2026-10-16)
182
+
183
+ Software release. Fixes Codex review round 4 (`reviews/2026-10-16-codex-round-4.md`: one blocking item, B1, plus small ones). Numbers: A = round-3 item status, B-1 and B-2 = new in round 4.
184
+
185
+ ## v0.1.3 (2026-10-16)
186
+
187
+ Software release. Fixes Codex review round 3 (`reviews/2026-10-16-codex-round-3.md`: no High; B1 to B5 new, plus residual partials).
188
+
189
+ ## v0.1.2 (2026-10-16)
190
+
191
+ Software release. Fixes Codex review round 2 (`reviews/2026-10-16-codex-round-2.md`: 13 fixed, 13 partial, 13 new). Numbers below: P = round-1 finding that was partial, N = new finding in round 2.
192
+
193
+ ## v0.1.1 (2026-10-16)
194
+
195
+ Software release. Spec stays at 0.5 apart from section 6.1. Fixes Codex review round 1 (`reviews/2026-10-16-codex-round-1.md`, 26 findings, verdict "not ready").
196
+
197
+ ## v0.1.0 (2026-10-16)
198
+
199
+ Software release. Spec stays at 0.5.
package/README.md CHANGED
@@ -83,7 +83,7 @@ tiresias read https://example.com/anvil-care --question "how do I test rebound"
83
83
 
84
84
  - **Reads pages the way an agent needs them.** An outline first, one section or the best quoted passages on request, in pages that fit a context window. Main content found and boilerplate (menus, cookie banners, related posts) dropped; tables as rows, HTML and Markdown code blocks kept as written, lists with their markers, page metadata. Markdown, JSON, PDFs, SVG and plain text too.
85
85
  - **Uses the front door when there is one.** Asks for markdown first, reads `llms.txt` and `llms-full.txt`, and reports the MCP servers, API specs and feeds a site offers.
86
- - **Is honest on every request.** Says what it is in its user agent (`Tiresias/<version> (+https://raibit.ai/tiresias/)`, a page that leads to this repo), can sign each request with Web Bot Auth so a site can verify it, obeys robots.txt, Crawl-delay and Retry-After on every site it reads, and spaces its requests to one site at least a second apart, shared by every Tiresias process on the machine (private reads and form previews keep their spacing in their own process, since they write nothing to disk).
86
+ - **Is honest on every request.** Says what it is in its user agent (`Tiresias/<version> (+https://raibit.ai/tiresias/)`, a page that leads to this repo), can sign each request with Web Bot Auth so a site can verify it, obeys robots.txt, Crawl-delay and Retry-After on every site it reads, and spaces its requests to one site at least a second apart, shared by every Tiresias process on the machine (private reads and form previews share only the minimal politeness state, origin and times; `private_spacing=none` disables that sharing after confirmation).
87
87
  - **Stops for a person.** At a CAPTCHA, a login or a bot check it stops, gives you the page to open, and keeps a ticket so the agent can resume once you are through, or read the page you saved.
88
88
  - **Treats the web as data.** Everything from a page sits inside `untrusted_content`; hidden text (inline styles, the page's own style rules, screen-reader-only classes, white or off-page PDF text, and on a rendered page whatever the browser does not show), invisible characters and instructions aimed at an AI in 13 languages are flagged.
89
89
  - **Renders JavaScript-only pages, if you allow it.** In the Google Chrome you already have, with every request the page makes fetched under Tiresias's own rules (v0.7).
@@ -93,7 +93,7 @@ tiresias read https://example.com/anvil-care --question "how do I test rebound"
93
93
  - **Checks for phishing first.** Every URL is checked against the Phishing.Database list (and Google Web Risk if you add a key) before it is fetched (a private session uses the list already on disk and never downloads one: run `tiresias safety update` first).
94
94
  - **Acts only with your permission.** It can send a form only with a permission slip that you grant, at a terminal; it never pays.
95
95
  - **Watches for changes.** `check` and `watch` say what changed since the last visit, block by block.
96
- - **Stays private when asked.** Private mode keeps nothing about the visit.
96
+ - **Stays private when asked.** Private mode keeps no page record; the site's waits and minimal spacing state still apply.
97
97
 
98
98
  ## How it compares
99
99
 
@@ -127,7 +127,7 @@ args = ["mcp"]
127
127
 
128
128
  Any other MCP app takes the same command, `tiresias mcp`, over stdio (`examples/claude-code.mcp.json` is a project-level `.mcp.json`). From a source checkout, use `node /path/to/tiresias/dist/cli.js mcp` instead.
129
129
 
130
- Tools (18): `read`, `doors`, `check`, `receipts`, `history`, `log`, `needs_report`, `bookmarks`, `bookmark`, `watch`, `resume`, `handoffs`, `slips` (read only), `form_preview`, `form_submit`, and since v0.6 `tabs`, `tab` and `files` (the downloads shelf). Each has a title and the standard annotations (read-only, destructive, open-world), and the rules they share are in the server's instructions. The agent's name from the MCP handshake is recorded in history. One server runs at most 8 calls at once (32 more wait their turn; past that a call gets an error at once), 4 page parsers and 2 renders; a call's arguments are capped (1,000 values, 8 MB), and a call the server cannot run (an unknown tool, arguments that do not fit) gets a fixed error, never the caller's own words back.
130
+ Tools (18): `read`, `doors`, `check`, `receipts`, `history`, `log`, `needs_report`, `bookmarks`, `bookmark`, `watch`, `resume`, `handoffs`, `slips` (read only), `form_preview`, `form_submit`, and since v0.6 `tabs`, `tab` and `files` (the downloads shelf). History, receipts, log and needs scans stop on cancellation or after 60 seconds, and read only up to each file's starting end offset. Each has a title and the standard annotations (read-only, destructive, open-world), and the rules they share are in the server's instructions. The agent's name from the MCP handshake is recorded in history. One server runs at most 8 calls at once (32 more wait their turn; past that a call gets an error at once), 4 page parsers and 2 renders; a call's arguments are capped (1,000 values, 8 MB), and a call the server cannot run (an unknown tool, arguments that do not fit) gets a fixed error, never the caller's own words back.
131
131
 
132
132
  **Memory ceiling (v0.9).** `tiresias mcp` runs the server under its own memory ceiling: `TIRESIAS_MEMORY_MB`, default 1024 MB (set it in your app's MCP `env` block; `off` turns it off). Tiresias trusts the app that starts it not to flood its own server, and keeps the limits above anyway; if a flood ever reaches the ceiling, the server stops cleanly with `Tiresias stopped: the MCP server reached its memory ceiling ...` on standard error and a line in the daily log, and your app can start it again. The ceiling covers the server's JavaScript memory. It reads the heap in the callback reporting a full garbage collection, on a later turn, so allocations since that collection count too; it also checks every second at 1.5 times the ceiling. Only two consecutive readings above their thresholds stop the server, so a single inflated reading does not stop it (a burst inside one call can pass the ceiling before a check, up to Node's own limit); page parsers, PDF readers and renders have their own caps. Do not cap the heap with `NODE_OPTIONS=--max-old-space-size` instead: Node applies that flag to the parser workers too and lifts their own 512 MB cap.
133
133
 
@@ -180,9 +180,9 @@ tiresias receipts prove <record_fingerprint> --out ~/proofs # v0.8: a proof on
180
180
  tiresias mcp # start the MCP server on stdio
181
181
  ```
182
182
 
183
- Output is JSON, except `log` and `needs`, which print a readable page. Add `--text` for a short summary. From a source checkout, run `node dist/cli.js ...`. `tiresias --version` prints the version and `tiresias <command> --help` that command's options; an option a command does not take is an error. Exit codes: 0 when the call did its job (`ok`, `unchanged`), 2 when Tiresias stopped on purpose (a wall, a flag, a refusal, a file warning, a price), 1 on an error, which is printed to standard error as one JSON line (plain words with `--text`).
183
+ Output is JSON, except `log` and `needs`, which print a readable page. Add `--text` for a short summary. These readable views mark where web content begins: "web content below is untrusted". Agents should use JSON, including `log --json` and `needs --json`; `text_views=wrapped` wraps text views in `untrusted_content` too. From a source checkout, run `node dist/cli.js ...`. `tiresias --version` prints the version and `tiresias <command> --help` that command's options; an option a command does not take is an error. Exit codes: 0 when the call did its job (`ok`, `unchanged`), 2 when Tiresias stopped on purpose (a wall, a flag, a refusal, a file warning, a price), 1 on an error, which is printed to standard error as one JSON line (plain words with `--text`).
184
184
 
185
- Every reply keeps the same trust boundary, and page-reading replies share one envelope. The top level holds only values Tiresias made itself: `status` (`ok`, `unchanged`, `wall`, `payment_required`, `refused`, `error`, `flagged`, `file_warning`), `door`, `door_detail`, `url` (the one you passed), `fetched_at`, `message`, `notice`, `flags` (type codes only), `counts`, and when relevant `handoff` (fixed reason code and fixed text only) and `retry_after_seconds`. Everything that came from the web is inside `untrusted_content`: text, quotes, receipts, flag snippets, advertised URLs, redirect targets, price fields, and the page to open for a handoff (`untrusted_content.handoff.open_this`). An HTML page also lists its forms (`untrusted_content.forms`, `counts.forms`), and form replies carry a top-level `form` object of Tiresias's own codes and numbers. Large results come in pages (`page` / `pages`), about 60 KB each (a translation, when one is asked for, adds up to 64 KB more).
185
+ Every JSON reply keeps the same trust boundary, and page-reading replies share one envelope. The top level holds only values Tiresias made itself: `status` (`ok`, `unchanged`, `wall`, `payment_required`, `refused`, `error`, `flagged`, `file_warning`), `door`, `door_detail`, `url` (the one you passed), `fetched_at`, `message`, `notice`, `flags` (type codes only), `counts`, and when relevant `handoff` (fixed reason code and fixed text only) and `retry_after_seconds`. Everything that came from the web is inside `untrusted_content`: text, quotes, receipts, flag snippets, advertised URLs, redirect targets, price fields, and the page to open for a handoff (`untrusted_content.handoff.open_this`). An HTML page also lists its forms (`untrusted_content.forms`, `counts.forms`), and form replies carry a top-level `form` object of Tiresias's own codes and numbers. Large results come in pages (`page` / `pages`), about 60 KB each (a translation, when one is asked for, adds up to 64 KB more).
186
186
 
187
187
  ## Where things are stored
188
188
 
@@ -195,12 +195,14 @@ Tiresias can sign every request it sends, so a site can check that it really cam
195
195
  1. Make a key: `tiresias keys init`. It writes a private Ed25519 key to `~/.tiresias/keys/ed25519.private.jwk` (owner-only) and never prints it. It refuses to run inside a synced folder (OneDrive, iCloud Drive, Dropbox, Google Drive; judged by the real folder, not by a word in the name), because syncing would copy the private key elsewhere. It will not replace an existing key unless you add `--force`.
196
196
  2. Run `tiresias keys show` (or `keys directory`) to get the public key and the directory JSON.
197
197
  3. Publish that directory at `https://<your site>/.well-known/http-message-signatures-directory`. Verifiers want the directory's response signed too, and there are two ways to do it:
198
- - **Signed live (what Cloudflare asks for).** A small server, such as a Cloudflare Worker, holds a copy of the private key as a secret and signs each directory response as it is served, with a short expiry. Cloudflare's bot registry asked Raibit for signatures that expire within an hour, so Raibit's own directory on raibit.ai has been signed this way since 2026-10-27 (5-minute signatures). The cost is a second copy of the key on that server: if that account is ever broken into, make a new key (`tiresias keys init --force`) and publish the new directory. Tiresias does not include the server; any code that signs per RFC 9421 with the tag `http-message-signatures-directory` will do.
198
+ - **Signed live (what Cloudflare asks for).** A small server, such as a Cloudflare Worker, holds a copy of the private key as a secret and signs each directory response as it is served, with a short expiry. Cloudflare's bot registry asked Raibit for signatures that expire within an hour, so Raibit's own directory on raibit.ai has been signed this way since 2026-10-27 (5-minute signatures). The cost is a second copy of the key on that server: if that account is ever broken into, make a new key (`tiresias keys rotate --overlap 0`) and publish the new directory. Tiresias does not include the server; any code that signs per RFC 9421 with the tag `http-message-signatures-directory` will do.
199
199
  - **Pre-signed, as static files.** `tiresias keys sign-directory --out <folder> --host example.com` (`--host` may be left out once step 4 has set `signature_agent`; `--days` is 1 to 90, default 30) writes the directory body and the exact headers to serve with it (Content-Type, Signature, Signature-Input). The response is signed on your machine, so the private key never leaves it. The signature stops working on the expiry date it prints: run it again and re-upload before then. This suits a verifier that accepts day-long signatures; it does not meet Cloudflare's one-hour limit.
200
200
  4. Put the origin of that site in `config.json` as `"signature_agent": "https://example.com"` (just the site: no path or query).
201
201
 
202
202
  From then on every https request to a site is signed: pages, robots.txt, discovery probes and each redirect hop (for its own site). Plain http requests are never signed, and neither are Google Web Risk lookups (if you set a key). An http-only call does not load or validate the signing key: a damaged key is noticed on the next https request that needs it, or by `tiresias keys show`. Signatures last 60 seconds. If signing an https request fails (a damaged key file, a bad address), the call stops with a clear message instead of sending unsigned. Private mode still signs. Each browsing reply (read, doors, check and the others that fetch a site) that sent a request carries `"signed": true` or `false`.
203
203
 
204
+ To change keys, run `tiresias keys rotate`. New requests are signed with the new key at once, and the old key stays in the directory for 7 days (`--overlap` 0 to 30 days) so sites that cached it catch up; then it drops out by itself, or at once with `tiresias keys rotate --finish`. During that window `keys sign-directory` signs with both keys and its signatures end with the window, so sign again after it. After a leak use `--overlap 0`. `tiresias keys rotate --slips --confirm "YES, ROTATE THE SLIP KEY"` does the same for the permission slip key: it revokes every slip, and saved pages stay checkable. SECURITY.md has the steps for each key ("If your key leaks").
205
+
204
206
  **Cloudflare.** Raibit's own copy of Tiresias is listed in Cloudflare's bot directory as an Intermediary agent (it fetches at a person's request and returns the page to that person), and Cloudflare verifies its signed requests (checked on 2026-11-01 against Cloudflare's test page, which answered "this is a verified web-bot-auth-request"). Signatures are per owner: your copy signs with your key and your `signature_agent`, so Cloudflare recognises it only once you register your own directory with Cloudflare.
205
207
 
206
208
  `signature_agent_style` is `"quoted"` by default (the header form Cloudflare accepts today); set `"dictionary"` for the newer IETF form.
@@ -211,9 +213,9 @@ A PDF is read as text, one section per page ("Page 1", "Page 2", ...). A receipt
211
213
 
212
214
  It uses Mozilla's pdf.js, locked down (these are pdf.js options Tiresias sets; the process limits are in the next paragraph): only the bytes Tiresias already fetched are used, nothing is downloaded, no script or action in the PDF runs, forms and attachments are ignored, links in a PDF are not listed or followed, and nothing is rendered. A PDF is recognised by the exact type `application/pdf` (parameters and case ignored), or by starting with `%PDF-` when the type is missing, `application/octet-stream` or `binary/octet-stream`. An explicit `text/html` or `text/plain` response is never treated as a PDF.
213
215
 
214
- HTML and SVG nesting is tracked up to 256 elements; further nesting is flattened and its text is kept. List indentation stops at eight levels. Forms on a page whose nesting was flattened are listed but refused as `too_large`, since flattening can change which fields belong to a form. Parser results whose JSON is over 16,777,216 characters (UTF-16 code units) are refused as `page_too_complex` before leaving the worker.
216
+ HTML and SVG nesting is tracked up to 256 elements; further nesting is flattened and its text is kept. List indentation stops at eight levels. Forms on a page whose nesting was flattened are listed but refused as `too_large`, since flattening can change which fields belong to a form. Parser results whose JSON is over 16,777,216 characters (UTF-16 code units) are refused as `page_too_complex` before leaving the worker. Receipt construction is also bounded before it starts; a page with too many sections or blocks for the length of its source URL is refused as `page_too_complex`.
215
217
 
216
- Each PDF is read in its own short-lived child process, not in the parser's worker thread, because pdf.js can allocate memory (decoder buffers) that a thread's heap limit does not count. The child gets an empty environment, no shell and no stdout, and runs under Node's permission model: it may read only Tiresias's own folder and the `node_modules` folder it was installed with (not your files, not `~/.tiresias` and its keys), and may start a worker thread (its parent watchdog). Node's permission model does not limit the network: the child is simply given no address and no code that fetches. Tiresias watches the child's real memory (resident set size: `VmRSS` from `/proc/<pid>/status` on Linux, `ps -o rss=` on macOS, checked every 50 ms) and kills it with SIGKILL above 1024 MB (`TIRESIAS_PDF_MEMORY_MB`), or when the time budget runs out (5 seconds, `TIRESIAS_PARSE_BUDGET_MS`), or when the call is cancelled. A PDF that crashes, runs out of memory or is killed ends as `page_too_complex` and nothing is saved. The child dies with its parent, even if it is stuck in a loop (a small watchdog thread inside it checks every 200 ms that its parent is still the same process). Starting a process costs a fraction of a second per PDF (a cold start).
218
+ Each PDF is read in its own short-lived child process, not in the parser's worker thread, because pdf.js can allocate memory (decoder buffers) that a thread's heap limit does not count. The child gets an empty environment, no shell and no stdout, and runs under Node's permission model: it may read only Tiresias's own folder and the `node_modules` folder it was installed with (not your files, not `~/.tiresias` and its keys), and may not start worker threads. Node's permission model does not limit the network: the child is simply given no address and no code that fetches. Tiresias watches the child's real memory (resident set size: `VmRSS` from `/proc/<pid>/status` on Linux, `ps -o rss=` on macOS, checked every 50 ms) and kills it with SIGKILL above 1024 MB (`TIRESIAS_PDF_MEMORY_MB`), or when the time budget runs out (5 seconds, `TIRESIAS_PARSE_BUDGET_MS`), or when the call is cancelled. A PDF that crashes, runs out of memory or is killed ends as `page_too_complex` and nothing is saved. The child dies with its parent, even if it is stuck in a loop (a separate watchdog process kills it when the parent's IPC channel closes). Starting a process costs a fraction of a second per PDF (a cold start).
217
219
 
218
220
  **If memory cannot be watched, PDFs are not read.** Before starting a child, Tiresias checks that it can read memory use on this system. If it cannot (Windows, or no `ps` or `/proc`), a PDF answers with a clear error and web pages are unaffected. Windows therefore cannot read PDFs.
219
221
 
@@ -225,9 +227,9 @@ Limits: a PDF over the 5 MB fetch cap is refused with a message that says so (it
225
227
 
226
228
  ## Private mode
227
229
 
228
- Add `--private` to `read`, `doors` or `check`, pass `private: true` to the MCP tools, or start a whole session with `TIRESIAS_PRIVATE=1` (for example `TIRESIAS_PRIVATE=1 tiresias mcp`). A private call saves nothing about the visit: no history line, no receipts, and it neither reads nor writes the page cache, probe reuse or shared robots state, and creates no folders in the store, so it never shows or records an earlier visit (a rendered private read still uses Chrome's throwaway profile in the system temp folder, deleted afterwards). The reply carries `"private": true`.
230
+ Add `--private` to `read`, `doors` or `check`, pass `private: true` to the MCP tools, or start a whole session with `TIRESIAS_PRIVATE=1` (for example `TIRESIAS_PRIVATE=1 tiresias mcp`). A private call keeps no page record: no history line, no receipts, and it neither reads nor writes the page cache, probe reuse or shared robots state, so it never shows or records an earlier page visit (a rendered private read still uses Chrome's throwaway profile in the system temp folder, deleted afterwards). The reply carries `"private": true`.
229
231
 
230
- Private is local only, like a browser's private window. The site still sees the same honest `Tiresias` user agent, and robots.txt and Retry-After are still obeyed. One thing is still written: if a site answers 429 or 503 with a wait, that wait is recorded (the site's address and the deadline, never the page path), because obeying the site comes before local privacy.
232
+ Private is local only, like a browser's private window. The site still sees the same honest `Tiresias` user agent, and robots.txt and Retry-After are still obeyed. Minimal politeness state is still written: origin and times for spacing across processes (private calls and form previews included), and if a site answers 429 or 503, or a redirect asks for a wait, that wait is recorded (the site's address and the deadline, never the page path), because obeying the site comes before local privacy. `private_spacing=none` disables shared spacing for private calls and previews after confirmation; Retry-After is always kept.
231
233
 
232
234
  ## Storage limits and cleanup
233
235
 
@@ -241,7 +243,7 @@ Defaults: keep history 90 days, receipts 90 days, cached pages 30 days, and brin
241
243
 
242
244
  Each value must be a whole number of 1 or more; a bad limit value is reported plainly by `tiresias clear` and never breaks a read. (A `config.json` that is not valid JSON at all does stop reads, with a message saying so, because the risky settings in it cannot be judged.) Tiresias trims past-limit data by itself at most once a day, on the first normal (non-private) call. `tiresias clear` does it on demand: `--older-than 30d` (whole days) overrides the age limits for that run, `--all` removes all history, receipts and cached pages, and `--dry-run` shows what would go without changing anything. It reports what it removed and the bytes freed.
243
245
 
244
- Cleanup only deletes whole files (a day of history, a day of receipts, a cached page) and never rewrites one, so it is safe beside running agents and `--dry-run` shows exactly what a real run would remove. Waits recorded in `cooldowns.jsonl` are never compacted or deleted by Tiresias, not even by `--all` (it grows by a few lines per 429/503). Deleting it by hand is safe only when no Tiresias process is running. `clear --dry-run`, `log` and the history and receipts commands never create the store folder or change its permissions.
246
+ Cleanup only deletes whole files (a day of history, a day of receipts, a cached page) and never rewrites one, so it is safe beside running agents and `--dry-run` shows exactly what a real run would remove. Waits recorded in `cooldowns.jsonl` are never compacted or deleted by Tiresias, not even by `--all` (it grows when a site asks for a wait). Deleting it by hand is safe only when no Tiresias process is running. `clear --dry-run`, `log` and the history and receipts commands never create the store folder or change its permissions.
245
247
 
246
248
  ## What changed, needs and bookmarks
247
249
 
@@ -249,7 +251,7 @@ Cleanup only deletes whole files (a day of history, a day of receipts, a cached
249
251
 
250
252
  **Needs report (W-12).** `tiresias needs` (MCP `needs_report`) reads the last 30 days of history (`--since` to change it) and lists the walls hit by site and reason, questions that came back empty, reads where the site offered a better door, pages read most often, and sites visited 3 or more times that offer no agent door. Each pattern comes with a suggested want or need for you to accept or reject. It is built when you ask and never stored.
251
253
 
252
- **Bookmarks and watchlist (W-16).** `tiresias bookmark add <name> <url> [--watch]`, `bookmark remove <name>`, `bookmark watch <name> on|off`, `bookmark list`. Names are 1 to 64 characters of `a-z`, `0-9` and `-`; at most 1,000 bookmarks, one small file each in `~/.tiresias/bookmarks/`. `tiresias watch` checks every watched bookmark like a normal `check` (robots.txt, waits and signing all apply), and reports the ones that changed, with what changed. It also names the bookmarks that were walled, failed or are waiting on a site's Retry-After (in `attention`: name, outcome, the wall reason or the seconds to wait; their URLs are inside `untrusted_content`), at most 100, since those are the ones a person may need to act on. Unchanged ones are only counted. A changed bookmark shows the start of its list of changes; for all of it, run `tiresias check <url>` from page 1. `watch --text` (the form the cron line below uses) prints the changed bookmarks with their counts and the ones needing attention with the reason, so the log says what to look at. Tiresias has no scheduler; run it yourself, for example with cron (`crontab -e` on macOS or Linux):
254
+ **Bookmarks and watchlist (W-16).** `tiresias bookmark add <name> <url> [--watch]`, `bookmark remove <name>`, `bookmark watch <name> on|off`, `bookmark list`. Names are 1 to 64 characters of `a-z`, `0-9` and `-`; at most 1,000 bookmarks, one small file each in `~/.tiresias/bookmarks/`. `tiresias watch` checks every watched bookmark like a normal `check` (robots.txt, waits and signing all apply), and reports the ones that changed, with what changed. It also names the bookmarks that were walled, failed or are waiting on a site's Retry-After (in `untrusted_content.attention`: name, outcome, the wall reason or the seconds to wait; their URLs are also inside `untrusted_content`), at most 100, since those are the ones a person may need to act on. Unchanged ones are only counted. A changed bookmark shows the start of its list of changes; for all of it, run `tiresias check <url>` from page 1. `watch --text` (the form the cron line below uses) prints the changed bookmarks with their counts and the ones needing attention with the reason, so the log says what to look at. Tiresias has no scheduler; run it yourself, for example with cron (`crontab -e` on macOS or Linux):
253
255
 
254
256
  ```
255
257
  0 7 * * * /full/path/to/tiresias watch --text >> ~/tiresias-watch.log 2>&1
@@ -262,7 +264,7 @@ Bookmarks are your saved list, not browsing data: `clear` (even `--all`) never r
262
264
  **Handoff and resume (W-06).** When a read stops at a wall (a bot check, a CAPTCHA, a login, a 403), the reply carries `handoff.ticket`, an id for picking up later, next to the page for a person to open (`untrusted_content.handoff.open_this`). The person opens it and gets through themselves. Then either:
263
265
 
264
266
  - `tiresias resume <ticket>` (MCP `resume` with `ticket`) runs the same read again, with the same question and section. robots.txt, waits, signing and wall detection all apply, and it always asks the site. If the wall is still there, you get it back with the same ticket.
265
- - `tiresias resume <ticket> --from-file <saved page>` (MCP `resume` with `text`) reads the page the person saved (HTML, markdown, text, or PDF from a file; at most 5 MB). Tiresias sends nothing to the site for it, so no cookies or logins are ever involved. The reply and every receipt say `source: "provided_by_person"`, and the page is not cached, because it may show the person's own logged-in view.
267
+ - `tiresias resume <ticket> --from-file <saved page>` reads the page the person saved (HTML, markdown, text, or PDF from a file; at most 5 MB). Tiresias sends nothing to the site for it, so no cookies or logins are ever involved. The reply and every receipt say `source: "provided_by_person"`, and the page is not cached, because it may show the person's own logged-in view. MCP `resume` with `text` is recorded as `provided_by_agent` in the reply, receipts and history: Tiresias cannot verify that a person supplied it.
266
268
 
267
269
  A ticket is removed once the read succeeds and expires after 7 days (`keep_handoff_days`). `tiresias handoffs` lists the open ones. At most 500 are kept. Private mode keeps no ticket and says so. Only `read` keeps tickets; `watch` names walled bookmarks instead.
268
270
 
@@ -329,7 +331,7 @@ tiresias slip revoke <id> # take one back; tiresias slip revoke --al
329
331
 
330
332
  - Only you grant, and only from the command line, as a person at a terminal: `slip grant` and `slip revoke` ask you to type the slip's site back (`revoke all` for `--all`) and refuse when their input is not a terminal, so an agent running the command from its shell cannot grant itself a slip. No MCP tool or parameter can make, extend or change a slip. Agents get a read-only `slips` tool that lists the active ones. An agent that can run commands on your machine is otherwise trusted like you (it could, for example, build its own terminal); the gate is against an agent granting itself permission in passing, not against a program determined to impersonate you.
331
333
  - Each use is a signed file, counted up to the highest use number, so deleting a use file gives nothing back. Every revoked slip goes on `slips/revoked.jsonl` until it would have expired, so a copy of a revoked slip put back is never used.
332
- - A slip allows one action (`submit_form` is the only one) on one exact site (`https://host` or `https://host:port`; plain `http` only for localhost, for tests), and optionally only under one path, matched on whole path segments (`/contact` covers `/contact` and `/contact/send`, never `/contactus`). `pay` is refused: this version of Tiresias never pays (paying, with guardrails, is planned for v1.1).
334
+ - A slip allows one action (`submit_form` is the only one) on one exact site (`https://host` or `https://host:port`; plain `http` only for localhost, for tests), and optionally only under one path, matched on whole path segments (`/contact` covers `/contact` and `/contact/send`, never `/contactus`). `pay` is refused: this version of Tiresias never pays (paying, with guardrails, is planned for v1.3).
333
335
  - It lasts 24 hours by default (`--for 12h`, `--for 7d`, or `--until 2026-10-24`, which means through the end of that day), at most 30 days, and allows 1 use by default (`--uses`, at most 100). At most 200 slips per profile.
334
336
  - Each slip is signed with a separate key (`keys/slips.private.jwk`, made on your first grant or first saved snapshot, never printed, never used to sign web requests; it signs slips and snapshot manifests only). A slip file that was edited by hand, damaged, renamed, or copied from another profile does not verify and is never used; `slip list` counts it as damaged. Signing does not protect against a program running as you, which could read the key, the same as everything else in the store.
335
337
  - Slips belong to one profile (`--profile`). `clear` and the daily trim remove expired and used-up slips; `clear --all` never removes an active one, and slips do not count toward the disk cap. Private mode refuses `slip grant` and `slip revoke`, and a private session never uses a slip.
@@ -344,15 +346,15 @@ A form is an action taken in your name, so Tiresias shows it, previews it, and s
344
346
  tiresias slip grant --action submit_form --site https://example.com --path /contact --uses 1 --note "the contact form"
345
347
  ```
346
348
 
347
- **2. Your agent reads the page and sees its forms.** `read` lists them inside `untrusted_content.forms`: each form's number, method, where it sends, and its fields with their labels, defaults and choices. Fields the site fills in itself (hidden fields, often a security token) are listed by name only, as `set by the site`; their values are never shown to the agent. Forms with a password, a file upload, card or bank fields (hidden ones too), or a CAPTCHA are marked `not_allowed` and are never sent: a person handles those. So are GET forms with hidden fields (their values would land in the address), forms that send to an address whose path is not plain (only letters, digits, `_`, `~`, `-` and single dots between them; some real sites' addresses fail this and cannot be submitted to), forms with a field name that is not plain or two fields whose names a server could treat as one (`role_flag` and `role.flag`), POST forms with no address of their own on a page whose address has a query, forms whose hidden values are not plain printable ASCII (a space, line break or accented letter), and any request that would carry a card number anywhere, whoever typed it.
349
+ **2. Your agent reads the page and sees its forms.** `read` lists them inside `untrusted_content.forms`: each form's number, method, where it sends, and its fields with their labels, defaults and choices. Fields the site fills in itself (hidden fields, often a security token) are listed by name only, as `set by the site`; their values are never shown to the agent. Forms with sign-in actions or username autocomplete, a password, a file upload, payment or purchase actions (including saved funds), card or bank fields (hidden ones too), or a CAPTCHA are marked `not_allowed` and are never sent: a person handles those. (Sign-in, payment and purchase actions are recognized from word lists in 13 languages, so a form worded another way can go unmarked; the slip, not the word list, is the guarantee. See SECURITY.md.) So are GET forms with hidden fields (their values would land in the address), forms that send to an address whose path is not plain (only letters, digits, `_`, `~`, `-` and single dots between them; some real sites' addresses fail this and cannot be submitted to), forms with a field name that is not plain or two fields whose names a server could treat as one (`role_flag` and `role.flag`), POST forms with no address of their own on a page whose address has a query, forms whose hidden values are not plain printable ASCII (a space, line break or accented letter), and any request that would carry a card number anywhere, whoever typed it.
348
350
 
349
- **3. The agent previews** (`form_preview`, or `tiresias form preview <url> --form 1 --set name=Ann --set email=ann@example.com`; `--set` repeated with one name gives a checkbox group or multiple select several values, and `--unset name` chooses none). Tiresias fetches the page fresh, checks the values against the form (known fields only, listed choices only, required fields filled, lengths respected) and shows the exact request it would send: method, full address, and the encoded body, with each hidden value shown as `[set by the site]`. It also says whether a slip covers that address and gives a `preview_hash`. Nothing is sent and nothing is saved (except, as for every fetch, a Retry-After wait the site asks for).
351
+ **3. The agent previews** (`form_preview`, or `tiresias form preview <url> --form 1 --set name=Ann --set email=ann@example.com`; `--set` repeated with one name gives a checkbox group or multiple select several values, and `--unset name` chooses none). Tiresias fetches the page fresh, checks the values against the form (known fields only, listed choices only, required fields filled, lengths respected) and shows the exact request it would send: method, full address, and the encoded body, with each hidden value shown as `[set by the site]`. It also says whether a slip covers that address and gives a `preview_hash`. The previewed form is not sent. Only Retry-After and minimal spacing state are saved by default. With `get_form_actions=slip`, fetching a page at a known GET form action also needs and spends a slip use.
350
352
 
351
353
  **4. The agent submits** (`form_submit` with the same values and the `preview_hash`, or `tiresias form submit ... --preview <hash>`). In that one call Tiresias fetches the page again and rebuilds the request. If the form or the values changed since the preview, it refuses (`form_changed`) and sends nothing. It checks the address the form sends to (Safe Browsing, with no way to override a flag; robots.txt; any wait the site asked for), and only then uses one use of your slip. No slip, no request. The form is sent once and never retried, with the site's own hidden values from this fetch and only the cookies the site set during this call (kept in memory, thrown away afterwards, never sent to another site). No redirect after a submit is followed, so the form can never be sent twice; the reply gives the address the site pointed to, which the agent can read with `read`. The reply has the HTTP status, which slip use was spent, and the answer page read like any page.
352
354
 
353
- If the site's answer repeats one of its hidden values, or a cookie it set while the form was fetched (of 6 characters or more), Tiresias withholds the whole answer (since v0.9): the reply says the form was sent and gives the HTTP status and size, with `form.reason: "secret_withheld"`, and nothing from the answer is shown or recorded. The answer is checked once, as received, with HTML, percent and JSON escapes decoded and case, quotes and spaces ignored, so the usual spellings of an echo are all caught; an echo in an encoding Tiresias does not decode (base64, a hash) is not. It is the site's own secret from this one call, so this is best effort: Tiresias tries not to see it. Shorter values are not checked: every `1` or `en` in a page would match, and a value that short is not a secret.
355
+ If the site's answer repeats one of its hidden values, or a cookie it set while the form was fetched (of 6 characters or more), Tiresias withholds the whole answer (since v0.9): the reply says the form was sent and gives the HTTP status and size, with `form.reason: "secret_withheld"`, and nothing from the answer is shown or recorded. The answer is checked as received, and its extracted text is checked again before anything is shown or recorded, with HTML, percent and JSON escapes decoded and case, quotes and spaces ignored, so the usual spellings of an echo are all caught; an echo in an encoding Tiresias does not decode (base64, a hash) is not. It is the site's own secret from this one call, so this is best effort: Tiresias tries not to see it. Shorter values are not checked: every `1` or `en` in a page would match, and a value that short is not a secret.
354
356
 
355
- The guard that refuses login, password, CAPTCHA and payment forms errs toward refusing: a form is refused (`not_allowed`) when a marker word appears anywhere in its fields, labels or surrounding text, even run together with other words, so an ordinary form is sometimes refused too. `not_allowed` means "an agent should not send this", not proof of what the form does. What Tiresias promises, and what stays the site's own job (how its server reads parameters), is written down in docs/SPEC.md section 9 ("What form submission guarantees").
357
+ The guard that refuses login, password, CAPTCHA and payment forms errs toward refusing: a form is refused (`not_allowed`) when a marker word appears anywhere in its fields, labels or surrounding text, so an ordinary form is sometimes refused too. Markers such as `password` and `captcha` count even when run together with other words; action words such as "buy", "pay" and "sign in" count only as whole words, so "Buyers" does not refuse a form. `not_allowed` means "an agent should not send this", not proof of what the form does. What Tiresias promises, and what stays the site's own job (how its server reads parameters), is written down in docs/SPEC.md section 9 ("What form submission guarantees").
356
358
 
357
359
  What is kept: a history line for each submit, and in the receipts log a record of what was sent (where, which slip, the field names and the values from visible fields, each value cut at 2,000 characters and the record marked `cut: true` when it had to be shortened; hidden fields by name only). Private mode refuses `form_submit` (using a slip writes), and preview works privately. GET forms (like a search box) need a slip too: every form is an action.
358
360
 
@@ -363,7 +365,7 @@ When a link leads to a file instead of a page, Tiresias decides what it is from
363
365
  - **What the warning says** (top-level `file_warning`): `kind` (`program`, `script`, `shortcut`, `addon`, `archive`, `office`, `image`, `media` or `unknown`), `risk` (`low` for images and media, `high` for everything else, unknown files included), `size`, a `fingerprint` (`sha256:...`), `flags` and a fixed `reason`. The URL, final URL and the declared type and name are inside `untrusted_content`. A file is hashed as it streams and never held whole (except a body sent with `Content-Encoding: deflate`, collected compressed up to the cap to inflate it safely, and a zip or Office file Tiresias looks inside, held in memory up to 20 MiB, `TIRESIAS_MAX_INSPECT_BYTES`); over `TIRESIAS_MAX_FILE_BYTES` (default 50 MB) the download stops and the warning has no fingerprint, and a file the site says is bigger than that is not downloaded at all.
364
366
  - **Flags:** `type_mismatch` when the declared type or name disagrees with the content (an "invoice.pdf" that is a program), `double_extension` for names like `invoice.pdf.exe`.
365
367
  - **Text kinds** are read, never run, and flagged: scripts (`.sh`, `.js`, `.ps1`, a `#!` first line and the like) as plain text with the `script` flag; SVG images as text only (scripts and styles dropped, the injection shield on) with `svg`; CSV with `csv_formulas` and a count when cells start like a spreadsheet formula; calendar (`.ics`) and contact (`.vcf`) files with `calendar` or `contact`, their links listed and never followed. Shortcut and system files served as text (`.url`, `.desktop`, `.reg`, `.mobileconfig`, `.inf`, `.library-ms`) are never read: they are file warnings. PDFs keep their text and add `pdf_javascript`, `pdf_attachments` or `pdf_launch` when they hold those (none of them is run or opened; `pdf_launch` is looked for in the file's plain bytes, so one inside a compressed object stream is not seen).
366
- - File warnings are recorded in history and receipts (never in private mode), counted by the daily log and the needs report, and named under `attention` by `watch`. They work the same from `check`, `watch`, `resume` (including a file a person saved) and a form's answer.
368
+ - File warnings are recorded in history and receipts (never in private mode), counted by the daily log and the needs report, and named under `untrusted_content.attention` by `watch`. They work the same from `check`, `watch`, `resume` (including a file a person saved) and a form's answer.
367
369
 
368
370
  **Your own scanner (optional).** Tiresias does no virus checking of its own and calls no outside service. If you already use one, you can connect it, and every high-risk file warning that was downloaded whole (so it has a fingerprint) is checked automatically; a file over the size cap, stopped by time, or not downloaded at all is not:
369
371
 
@@ -387,7 +389,7 @@ Every successful read (`ok` or `unchanged`, not private) opens a numbered tab. `
387
389
 
388
390
  `tiresias settings` is the settings page: every owner setting with its current value, its default, a line on what it does and where it is stored (`config.json` in the profile's folder, or an environment variable). `tiresias settings set <name> [<site>] <value>` changes one and `tiresias settings reset <name> [<site>]` puts back the default; every value is checked before the file is written, the file is written whole or not at all, and a bad `config.json` is reported by the name of the key that is wrong. Only the command line can do this: no MCP tool reads or changes a setting.
389
391
 
390
- **Risky settings need confirmation (v0.9, W-32).** An agent that can run commands on your computer can run `tiresias settings` too, so turning a risky setting on or looser takes an exact all-caps phrase naming it, given as `--confirm`: `tiresias settings set saving ask --confirm "YES, TURN ON SAVING"`. Without it, or with any other text, nothing changes and the reply prints the exact phrase. Turning a setting off or stricter never asks. Risky: `saving`, `rendering` (`ask`, and `auto` with its own phrase), `translator`, `scanner` with `--send-file`, `anchoring`, `anchor_calendars` (adding one), `safe_browsing` off, and per site more `ports`, lower `spacing_seconds`, and `never_visit` or `hand_off` turned off. An agent may type the phrase; the point is that nothing is loosened by accident or in passing, and every change made with a settings command is written to `tiresias history` and the daily log with who made it (whether the command ran at a terminal, so likely you, or not, so an agent, a script or cron: a best guess), and every reply, CLI and MCP, carries a short `settings_notice` for 24 hours. It does not stop an agent that is fully fooled into typing the phrase; the log and the notice make that visible.
392
+ **Risky settings need confirmation (v0.9, W-32).** An agent that can run commands on your computer can run `tiresias settings` too, so turning a risky setting on or looser takes an exact all-caps phrase naming it, given as `--confirm`: `tiresias settings set saving ask --confirm "YES, TURN ON SAVING"`. Without it, or with any other text, nothing changes and the reply prints the exact phrase. Turning a setting off or stricter never asks. Risky: `saving`, `rendering` (`ask`, and `auto` with its own phrase), `translator`, `scanner` with `--send-file`, `anchoring`, `anchor_calendars` (adding one), `safe_browsing` off, and per site more `ports`, lower `spacing_seconds`, and `never_visit` or `hand_off` turned off, plus `private_spacing none` and `hook_secrets inherit` (below). An agent may type the phrase; the point is that nothing is loosened by accident or in passing, and every change made with a settings command is written to `tiresias history` and the daily log with who made it (whether the command ran at a terminal, so likely you, or not, so an agent, a script or cron: a best guess), and every reply, CLI and MCP, carries a short `settings_notice` for 24 hours. It does not stop an agent that is fully fooled into typing the phrase; the log and the notice make that visible.
391
393
 
392
394
  - **Editing `config.json` by hand.** Tiresias keeps the last confirmed state in `confirmations.json` next to it. A hand edit that loosens a risky setting is not in force until you confirm it (`tiresias settings confirm saving --confirm "YES, TURN ON SAVING"`); until then the confirmed value applies, and replies and `tiresias settings` say so. A hand edit that tightens applies at once. No record (a new store, or an upgrade from v0.8) means the safe defaults are the confirmed ones: confirm once what you had turned on. **Upgrading from v0.8:** if you had turned on saving, rendering or anchoring, they are held off until you confirm each one; the first reply after the upgrade lists them with the exact command, for example `tiresias settings confirm saving --confirm "YES, TURN ON SAVING"` (and the same with `rendering` and `"YES, TURN ON RENDERING"`, or `anchoring` and `"YES, TURN ON ANCHORING"`). `tiresias settings` shows what is waiting. Since v0.9.1, `tiresias mcp` also prints one line on standard error when it starts while a setting is held back, naming the exact command for each (your AI app usually keeps that in its MCP server log), so an owner who uses Tiresias only through an agent can find it too. The record is a plain file, so anything that can write to your folder can edit both; it catches accidents and casual tricks, not a determined program.
393
395
  - **Environment variables** that loosen (`TIRESIAS_RENDERING`, `TIRESIAS_SAFE_BROWSING=0`, `TIRESIAS_ALLOW_PORTS`) apply only with their phrase in `TIRESIAS_CONFIRM` (several separated by `;`), for example `TIRESIAS_CONFIRM="YES, TURN OFF SAFE BROWSING"`; otherwise they are ignored and replies say so.
@@ -396,6 +398,27 @@ Every successful read (`ok` or `unchanged`, not private) opens a numbered tab. `
396
398
  - **Fast first read (`doors`).** A first read of a site returns the page right after robots.txt, in about a second instead of about seven. The checks for better doors (llms.txt, MCP, API specs) run afterwards in the background, one at a time and still spaced, and the reply says `doors_pending`; the next read uses their answers. The CLI waits for them before it exits (Ctrl-C cancels them cleanly). A private read checks them in the call, as before. `tiresias settings set doors wait` makes every first read wait for them.
397
399
  - **Site settings (`sites`).** Per host (`example.com`) or a host and everything under it (`*.example.com`): `spacing_seconds` (1 to 30, only ever raises the 1-second spacing), `ports` (extra ports for that site, like `8443,9000-9100`), `hand_off` (never read it: the agent gets the link to give you, status `wall`, reason `owner_hand_off`) and `never_visit` (send it nothing, status `refused`). They apply to every request to a site, redirects and robots.txt included (Google Web Risk lookups are not spaced), and a reply names the ones that applied in `site_settings`.
398
400
 
401
+ The v1.1 choices are settings too, changed only through the command line or `config.json`:
402
+
403
+ | Setting | Default | Other choice |
404
+ |---|---|---|
405
+ | `get_form_actions` | `read`: links are ordinary reads | `slip`: reading a known GET form action requires and spends a `submit_form` slip |
406
+ | `private_spacing` | `shared`: private calls and previews share minimal spacing state | `none`: write no spacing state for them; separate processes are not spaced against each other |
407
+ | `hook_secrets` | `hidden`: hooks do not receive Tiresias secret variables | `inherit`: hooks receive the full environment |
408
+ | `text_views` | `marked`: readable text with an untrusted-content marker | `wrapped`: text inside `untrusted_content`, like JSON |
409
+
410
+ Set them with `tiresias settings set <name> <value>`; `tiresias settings` shows their defaults and current values.
411
+ The two loosenings need `--confirm "YES, TURN OFF PRIVATE SPACING"` for `private_spacing none`, or
412
+ `--confirm "YES, SHARE TIRESIAS SECRETS WITH HOOKS"` for `hook_secrets inherit`. Like other risky settings,
413
+ they are held back when unconfirmed, logged with who changed them, and shown in replies.
414
+
415
+ Permission slips gate sending forms. Reading a link is a read; a site that changes something on a plain GET breaks
416
+ HTTP's rule that GET is safe. The `slip` setting tightens reads of GET form targets Tiresias has observed, matching
417
+ origin and path regardless of query. Cacheable non-private pages keep that policy in the cache; private calls and previews
418
+ keep observations only in memory. A gated read spends a slip use, even when reached during a form preview; private
419
+ calls cannot spend a slip. A claimed submission is checked again after its queue wait, right before dispatch;
420
+ a reserved use stays spent if it expires or is revoked while waiting.
421
+
399
422
  **Inside files (v0.6).** A zip or an Office file (`.docx`, `.xlsx`, `.pptx` and their macro types) of up to `TIRESIAS_MAX_INSPECT_BYTES` (default 20 MiB) is held in memory, never on disk, and looked inside without unpacking it: a zip gives its names and declared sizes, with programs, scripts, shortcuts, nested archives, names that climb out of their folder, password-protected entries and signs of a zip bomb flagged (`file_warning.inside`, names in `untrusted_content.inside`); an Office file gives its text only, with a `macros` flag (never run) and its outside links listed (never fetched). It is still a `file_warning`: the file was never opened. A calendar file (`.ics`) also gives its events (`untrusted_content.events`: summary, start, end, organizer, location, description, URL and links), with no link followed. Looking inside is bounded, and says so when it stops short: at most 10,000 zip entries listed, 500 Office parts and 200,000 characters of Office text read, 50 calendar events kept (the rest counted).
400
423
 
401
424
  ## Languages and your own translator (v0.7)
@@ -410,7 +433,7 @@ tiresias translator show
410
433
  tiresias translator off
411
434
  ```
412
435
 
413
- It is run only when a read asks for a translation (`read --translate en`, MCP `read` with `translate: "en"`), directly (no shell, a full path), as `your-translate [args...] <source> <target>`, with the text the reply shows on standard input (at most 32 KB) and at most 64 KB of its output kept. The output goes inside `untrusted_content.translation` with a note that it is a machine translation by your tool and not the page's own words; receipts always quote the original text, and the translation is never cached or logged. If it times out, fails, prints too much or nothing, the page comes back as usual and `translation: { status, reason }` says why. It is set only from the command line or by editing `config.json` (`"translator": {"command": [...], "timeout_seconds": 20}`), and since v0.9 setting a program takes `--confirm "YES, TURN ON THE TRANSLATOR"` (see Settings); over MCP an agent can only ask for a language, never choose or change the program. It runs on macOS and Linux only, like the scanner. Both are your own programs and are trusted like you: they run with your user's rights and Tiresias's environment, and Tiresias's privacy and file protections do not apply to what they do (a translator also runs on private reads, since it only sees the reply's text).
436
+ It is run only when a read asks for a translation (`read --translate en`, MCP `read` with `translate: "en"`), directly (no shell, a full path), as `your-translate [args...] <source> <target>`, with the text the reply shows on standard input (at most 32 KB) and at most 64 KB of its output kept. The output goes inside `untrusted_content.translation` with a note that it is a machine translation by your tool and not the page's own words; receipts always quote the original text, and the translation is never cached or logged. Successful translations are scanned for instructions aimed at an AI; the reply carries only fixed flag codes at the top level, with snippets labelled `machine translation` inside `untrusted_content.flag_details`. These findings stay specific to the reply. If the translation is dropped for size, its flag stays and its detail says the translation was omitted. If it times out, fails, prints too much or nothing, the page comes back as usual and `translation: { status, reason }` says why. It is set only from the command line or by editing `config.json` (`"translator": {"command": [...], "timeout_seconds": 20}`), and since v0.9 setting a program takes `--confirm "YES, TURN ON THE TRANSLATOR"` (see Settings); over MCP an agent can only ask for a language, never choose or change the program. It runs on macOS and Linux only, like the scanner. Both are your own programs and are trusted like you: they run with your user's rights and environment, with Tiresias secret variables removed by default (`hook_secrets=hidden`), and Tiresias's privacy and file protections do not apply to what they do (a translator also runs on private reads, since it only sees the reply's text).
414
437
 
415
438
  ## JavaScript-only pages (v0.7)
416
439
 
@@ -427,9 +450,9 @@ tiresias settings set rendering off # the default: never
427
450
  It uses the **Google Chrome already installed** on your machine, driven directly over a private pipe (no extra package, and Tiresias never downloads a browser). If Chrome is not found, the read comes back as usual with `render: { status: "unavailable" }` and how to enable it (install Google Chrome, or set `TIRESIAS_CHROME` to its program path).
428
451
 
429
452
  The page's JavaScript is treated as hostile:
430
- - **Every request the page makes goes through Tiresias's own rules**, exactly like a plain read: Safe Browsing, your site settings, the private-address block, ports, robots.txt, the site's waits and spacing, and signing. Chrome's own network never reaches a site; anything that tries another way (WebSocket, WebRTC) hits a dead end Tiresias sets up. Only scripts, style sheets and data requests are fetched, and only with GET; images, fonts, media, frames, files, popups, workers, form posts and the page moving itself elsewhere are refused and counted.
453
+ - **Every request the page makes goes through Tiresias's own rules**, exactly like a plain read: Safe Browsing, your site settings, the private-address block, ports, robots.txt, the site's waits and spacing, and signing. Chrome's own network never reaches a site; anything that tries another way (WebSocket, WebRTC) hits a dead end Tiresias sets up. Only scripts, style sheets and data requests are fetched, and only with GET; images, fonts, media, frames, files, popups, workers, form posts, requests matching GET form actions on the page, and the page moving itself elsewhere are refused and counted.
431
454
  - Chrome's own sandbox stays on. Each render gets a new, empty browser profile that is deleted afterwards, with no cookies, no downloads, no service workers, popups closed and dialogs dismissed. Tiresias never clicks, types or submits.
432
- - Hard limits: 20 seconds, 100 requests, 10 MB fetched, a rendered page of 50,000 elements and 5 MB. The browser is killed at the end of every render, whatever happened.
455
+ - Hard limits: 20 seconds, 100 requests, 10 MB fetched, a rendered page of 50,000 elements and 5 MB. Paused requests keep only bounded metadata; page headers and bodies are discarded, apart from the small fields needed to answer a CORS preflight. Outstanding paused requests are capped too. The browser is killed at the end of every render, whatever happened.
433
456
 
434
457
  The rendered page then goes through the same reader and shield as any page (receipts, flags, paging, walls, language).
435
458
 
@@ -478,9 +501,9 @@ tiresias receipts verify <bundle> # check a bundle offline
478
501
  ## How fetching is kept safe
479
502
 
480
503
  - Refuses non-http(s) URLs and private, loopback, link-local, CGNAT and internal addresses. IPv6 is allowed only for global unicast (and IPv4-mapped or well-known NAT64 addresses whose IPv4 address is itself allowed). The connection uses the same validated DNS answer that was checked (no second lookup), and redirects (301, 302, 303, 307 and 308 only) are followed by hand with every hop re-checked (max 5), and an https page that redirects to plain http is refused. Only ports 80, 443 and 8000 to 8999 are called (`TIRESIAS_ALLOW_PORTS` adds more). A 15 second timer covers what the site does (DNS, connection, answer, body); waits the site asked for run on the call's own 60 second deadline. 5 MB cap on decoded bytes. Since v0.7 every request is also cut off by the bytes its connection actually receives (headers, redirects, informational responses and compressed bodies included): the body cap plus 1 MB (for a read, the larger of the page and file caps, since whether a response is a page or a file is known only from its first bytes).
481
- - Parsing and scanning of page content runs in a worker thread under a time budget (5 seconds by default; set `TIRESIAS_PARSE_BUDGET_MS` to change it). A page that takes longer, or a caller that cancels, ends the worker and the call returns `page_too_complex`. Inputs of 8 KB or less run inline. The worker has a 512 MB heap limit (`TIRESIAS_WORKER_HEAP_MB`; Node's own `--max-old-space-size` flag overrides it); a page that exhausts it also returns `page_too_complex`. JSON that expands past 5 Mi characters of text is cut there and the cut is counted in `text_omitted` (the printer stops at the cap, so the full expansion is never built; `text_omitted` is exact, or a lower bound marked `text_omitted_at_least` for documents nested over 100,000 levels). Some smaller steps (robots parsing, discovery scanning, price parsing, cache handling) still run on the main thread; see the limits below.
482
- - Page and robots checks use bounded `indexOf` scanning (first 512 KB), never regexes with nested or lazy spans, so a hostile page cannot stall the process. Retry-After is recorded the moment 429/503 headers arrive, and a challenged redirect stops the call before it is followed.
483
- - Reads robots.txt (cached 1 hour) per RFC 9309: longest-match Allow/Disallow, `*` and `$`, percent-encoding normalized, CR/LF/CRLF, non-backtracking matcher. Missing robots means allowed. An unreachable or 5xx robots.txt, or a challenged one, means stop. Honors Crawl-delay up to 30 seconds. Retry-After on 429/503 starts a cooldown that blocks every later request to that site, across runs.
504
+ - Parsing and scanning of page content runs in a worker thread under a time budget (5 seconds by default; set `TIRESIAS_PARSE_BUDGET_MS` to change it). A page that takes longer, or a caller that cancels, ends the worker and the call returns `page_too_complex`. Inputs of 8 KB or less run inline, except PDFs, zip and Office files, and calendars, which always run outside the main thread. The worker has a 512 MB heap limit (`TIRESIAS_WORKER_HEAP_MB`; Node's own `--max-old-space-size` flag overrides it); a page that exhausts it also returns `page_too_complex`. JSON that expands past 5 Mi characters of text is cut there and the cut is counted in `text_omitted` (the printer stops at the cap, so the full expansion is never built; `text_omitted` is exact, or a lower bound marked `text_omitted_at_least` for documents nested over 100,000 levels). Some smaller steps (robots parsing, discovery scanning, price parsing, cache handling) still run on the main thread; see the limits below.
505
+ - Page and robots checks use bounded `indexOf` scanning (first 512 KB), never regexes with nested or lazy spans, so a hostile page cannot stall the process. Retry-After is recorded when 429/503 or redirect headers arrive; a redirect asking for a wait is not followed. A challenged redirect also stops the call before it is followed.
506
+ - Reads robots.txt (cached 1 hour) per RFC 9309: longest-match Allow/Disallow, `*` and `$`, percent-encoding normalized, CR/LF/CRLF, non-backtracking matcher. Missing robots means allowed. An unreachable or 5xx robots.txt, or a challenged one, means stop. Keeps the longest applicable Crawl-delay in full and declines waits over 30 seconds. Cross-origin robots redirects are followed only to that origin's own `/robots.txt`, with no query; any other path means stop. Retry-After on 429/503 and redirects starts a cooldown that blocks every later request to that site, across runs.
484
507
  - Looks for llms.txt, llms-full.txt, `/.well-known/mcp.json`, OpenAPI specs, feeds, sitemaps and JSON-LD. A challenge or 402 on any probe stops the whole call when the probes run before the reply (`doors wait`, private reads); with background door checks (the default) the page already read stands, and the challenge or price stops only the door checks. A bare 401/403 on a probe path only means that door is unavailable; the page itself still gets full wall detection.
485
508
  - Reads HTML, markdown, plain text, JSON and PDF.
486
509
  - Recognizes 401/403, Cloudflare challenges, CAPTCHA pages and login pages as walls, for any content type.
@@ -498,7 +521,7 @@ tiresias receipts verify <bundle> # check a bundle offline
498
521
  - The HTTPS path uses the same pinned lookup but has no local automated test.
499
522
  - Long URLs (over 2,048 characters) in links, feeds and sitemaps are left out and counted, never shortened.
500
523
  - Cooldowns left in a v0.1.3 JSON store or a v0.1.4 `cooldowns.old.jsonl` are still honored (read only).
501
- - Retry-After cooldowns are kept in one append-only file (`cooldowns.jsonl`), with no lock and no rotation. Many processes can record cooldowns at once without losing any. The file only grows (a few lines per 429/503) and only its last 8 MB is read. Nothing in Tiresias compacts or deletes it, not even `clear --all`; deleting it by hand is safe only when no Tiresias process is running.
524
+ - Retry-After cooldowns are kept in one append-only file (`cooldowns.jsonl`), with no lock and no rotation. Many processes can record cooldowns at once without losing any. The file only grows when a site asks for a wait. The whole file is replayed in bounded chunks when it changes, keeping every unexpired wait; if it cannot be read within its time budget, requests stop. Nothing in Tiresias compacts or deletes it, not even `clear --all`; deleting it by hand is safe only when no Tiresias process is running.
502
525
  - The store's parent folders are checked on every call up to your home folder; the home folder itself is trusted. If you reach the store through a symlinked alias in a writable folder, the alias's own folders are not checked (set `TIRESIAS_HOME` to a real path).
503
526
  - A Retry-After over 10 years is replaced by a 24 hour cooldown. A JSON-LD record over 5 MiB is skipped and reported.
504
527
  - Robots matching has a step budget. A path over 8,192 characters, or a robots.txt too costly to check, is refused rather than guessed.
@@ -15,6 +15,7 @@
15
15
  import { callContext } from "./context.js";
16
16
  import { probeOrigin } from "./doors.js";
17
17
  import * as safebrowsing from "./safebrowsing.js";
18
+ import { snapshotConfig } from "./config.js";
18
19
  import { withSignal } from "./safety.js";
19
20
  import { canonOrigin } from "./sitekey.js";
20
21
  import { MAX_SPACING_S, loadSites } from "./sites.js";
@@ -43,8 +44,10 @@ export function startDoorProbe(origin) {
43
44
  if (jobs.size >= MAX_JOBS)
44
45
  return false;
45
46
  let gate;
47
+ let config;
46
48
  try {
47
- gate = safebrowsing.makeGate({ allowFlagged: false, priv: false });
49
+ config = snapshotConfig();
50
+ gate = callContext.run({ config }, () => safebrowsing.makeGate({ allowFlagged: false, priv: false }));
48
51
  }
49
52
  catch {
50
53
  return false;
@@ -52,10 +55,10 @@ export function startDoorProbe(origin) {
52
55
  const ctl = new AbortController();
53
56
  const signal = AbortSignal.any([AbortSignal.timeout(JOB_MS), ctl.signal, shutdownSignal]);
54
57
  const sent = { requests: 0, signed: 0 };
55
- // Outside the asking call's context (callContext.exit): not its deadline, its cancellation, its
58
+ // Outside the asking call's context: not its deadline, its cancellation, its
56
59
  // per-call robots cache or its private flag; withSignal then gives the job a context of its own.
57
60
  const done = callContext
58
- .exit(() => withSignal(signal, () => {
61
+ .run({ config }, () => withSignal(signal, () => {
59
62
  // A job is its own call: it reads the site settings once, when it starts (sites.ts).
60
63
  const store = callContext.getStore();
61
64
  if (store)