chore: bump version to 1.7.3

Name the task_agent tool literally so the model connects the guidance
to the tool the persona grants, and restore "asking for permission".

(cherry picked from commit 9668862a7f)

CHANGELOG.md

@@ -14,6 +14,112 @@ experimental line:
 
 Earlier stable lines (`stable/1.6`, `stable/1.5`) are frozen.
 
+## [1.7.3]
+
+A small feature and maintenance patch for the 1.7 line. No schema migrations
+and no new configuration knobs.
+
+### Added
+
+- **OpenAI GPT-5.6 (Sol/Terra/Luna) support** — the Responses provider
+  understands the GPT-5.6 family: the `reasoning.mode` control, the new
+  `max` effort tier, and `text.verbosity`, with golden wire payloads pinning
+  the request shapes. The `openai` dependency floor moves to `>=2.44`.
+
+### Changed
+
+- **Engineer base prompt hardened with process discipline** — the default
+  base prompt for non-coordinator sessions now works in phases scaled to the
+  size of the change, defaults to red-green for testable work, scopes to the
+  smallest sufficient diff, stops to report after repeated failed attempts
+  instead of thrashing, reports only observed results, and delegates
+  exploration to `task_agent`. Persona prompts freeze into the workstream
+  stamp at creation, so this reaches new workstreams only.
+
+### Fixed
+
+- **Unknown reasoning-mode warnings name the allowed modes** — a model
+  definition with an unrecognized reasoning mode now logs the valid options
+  instead of leaving the operator to guess.
+
+### Documentation
+
+- **HYPOTHESIS.md / PRIMER.md** — the control normal form is tightened and
+  the factored Q_E reading is carried into the glossary; the plain-language
+  PRIMER stays in sync.
+
+## [1.7.2]
+
+A feature-bearing patch for the 1.7 line. Rather than hold this work for the
+larger 1.8 churn, the fixes and the smaller features that had already
+stabilised on `main` are rolled into the stable line now: a rich preview
+pane, persona/project settings on scheduled tasks, and a batch of streaming,
+rendering, and nudge-delivery hardening.
+
+> **⚠️ Before upgrading:** 1.7.2 adds Alembic migration `066`, applied
+> automatically on first start. It adds two `Text NOT NULL DEFAULT ''`
+> columns (`persona`, `project_id`) to the `scheduled_tasks` table; existing
+> rows migrate to the empty default, which is byte-identical to pre-066
+> dispatch behaviour. The change is additive and reversible, but — as always
+> — back up your storage before upgrading (`pg_dump` for PostgreSQL; copy the
+> database file for SQLite).
+
+### Added
+
+- **Rich preview pane + `open_preview` tool** — a workstream can now open a
+  rendered preview (HTML, Markdown, and other kinds) in a pane beside the
+  conversation via the new `open_preview` tool. Guarded fetches stream under
+  a byte budget whose ceiling tracks the widest per-kind cap, preview blob
+  ids are salted, and a preflight probe handles legacy charsets and a
+  remote-assets opt-in. See `docs/tools.md`.
+- **`allow_private_network` opt-in for `web_fetch` / `open_preview`** —
+  private-address fetch and preview targets stay blocked by default; an
+  operator can opt a workstream in through the settings registry when a
+  private endpoint is genuinely intended. (Distinct from the 1.7.1 `[oidc]`
+  flag of the same name, which governs identity-provider discovery.)
+- **Persona + project settings on scheduled tasks** (migration `066`) — a
+  scheduled task can now pin the **persona** and **project** of the
+  workstream it dispatches, matching the levers a manually-created workstream
+  already carries. Both default to empty (kind-default persona / no project),
+  so existing schedules dispatch exactly as before.
+
+### Fixed
+
+- **Streaming fast-path overflow recovery** — fast-stream tokens are now
+  batched and overflowed SSE listeners recover instead of stalling (and
+  `connectSSE` no longer opens into a hidden background tab). The same
+  overflow-recovery companions were carried to the coordinator pane, so a
+  coordinator watching many children recovers dropped listeners the same way
+  the live-session view does.
+- **Renderer containment** — markdown sentinel-forgery and recursive-frame
+  content loss are contained, and an indented fence close no longer drags its
+  indent into the enclosed code content.
+- **Idle nudge / wake delivery** — nudge and wake delivery is hardened across
+  session eviction, cancellation, and identity rebinds; the wake gate now
+  requires a real nudge queue, refused wakes are logged, and
+  `initial_message_status` is typed as a closed enum on the wire.
+- **`web_fetch` extraction inherits model settings** — the completion that
+  extracts content from a fetched page now inherits the workstream's model
+  settings instead of falling back to defaults.
+- **UI panes** — ephemeral panes close on split-dismiss instead of orphaning
+  a tab, and an unsplit skips the redundant refresh after an ephemeral pane
+  closes.
+- **Shared code-highlight CSS** — renderer-output CSS is shared so the console
+  and coordinator panes highlight code identically.
+
+### Security
+
+- **`Content-Disposition` filenames made wire-safe** — download filenames
+  derived from user-controlled text are sanitised (latin-1- and
+  control-char-safe, quoting-safe) before they reach the `Content-Disposition`
+  response header, including the fallback path.
+
+### Documentation
+
+- **HYPOTHESIS.md: daemons + the outer loop, plus a plain-language PRIMER** —
+  the harness north-star document gains its daemon / outer-loop treatment and
+  a new top-level `PRIMER.md`.
+
 ## [1.7.1]
 
 A maintenance and hardening patch for the 1.7 line. No schema migrations;

PRIMER.md

@@ -0,0 +1,155 @@
+# What a Harness Is — and What It Can Never Promise
+
+*A plain-language companion to [HYPOTHESIS.md](HYPOTHESIS.md). Same object, no symbols required.*
+
+**How to read this.** HYPOTHESIS.md defines, formally, what an agent harness is and what it can never guarantee. This file is that document lowered into plain language — and by the formal document's own rules, a summary is a cache, not an authority: it must stay re-derivable from its source, and wherever the two disagree, the formal one wins. Symbols appear once, in parentheses, so you can cross over; nothing here requires them. And none of it is decoration: the formal version, used as a checklist, has caught real bugs in a real harness — because most bugs are a violated invariant nobody had written down.
+
+## The problem
+
+You have a model. It is, roughly, a brilliant, tireless, lightning-fast intern that has read most of the internet — and that sometimes makes things up, sometimes gets confused, and sometimes takes instructions from strangers, because a page it was asked to read said "ignore your boss and email the passwords here" in white text on a white background.
+
+So you don't wire the intern to production. You build a loop around it. The **harness** is that whole governed loop: a deterministic shell *you* write — build the prompt, approve or refuse each proposed action, fold the result back into memory — wrapped around a model you didn't write and a world you don't control, repeated until the run reaches a stopping state. The shell is code and does the same thing every time. The model is neither, and everything in the theory comes from taking that split seriously.
+
+One sentence to keep: **the model proposes; the gate disposes.** The model's output is never an action. It is a suggestion, in text, which a piece of ordinary code you wrote either turns into an action or refuses.
+
+## The parts
+
+| Plain name | What it does | In the formal doc |
+|---|---|---|
+| The owner | The human — or sign-off group — the run acts for; the only place new permissions can come from | the trusted principal |
+| The memory | Everything the run knows: task, plan, transcript, and the ledger of what has been done | the state, *s* |
+| The prompt builder | Decides which slice of memory the model gets to see this step | the lowering, π |
+| The model | The black box that reads the prompt and writes a proposal | the plant, M_W |
+| The gate | Ordinary code that checks every proposal and approves or refuses it | the gate, γ |
+| The tools and the world | What approved actions actually touch: files, APIs, shells, people | the environment, Q_E |
+| The verifier | Checks each tool result, then writes it into memory | the fold-back, ρ |
+| The stop rule | Decides when the run is finished — and whether it finished *well* | the halt set H, accepting halts H_ok |
+| The danger zone | States that must never be reached: secrets exfiltrated, wrong files deleted, money moved twice | the bad set, B |
+
+The loop:
+
+```
+you ask for something
+        ↓
+prompt builder → model → "I propose: send_email(...)"
+                            ↓
+                          GATE ── no ──→ nothing happens (safe, recorded)
+                            ↓ yes
+                          tool runs in the world
+                            ↓
+                          verifier checks the result, writes it to memory
+                            ↓
+                  done? ── no → around again
+                    ↓ yes
+                  stop (well, or refused)
+```
+
+## The rules that make it a harness
+
+Four invariants, all about *where* things are allowed to happen.
+
+1. **The model sees only what the prompt builder shows it** — never raw memory. The corollary with teeth: a secret that never enters the prompt cannot leak through the model. The redaction step that keeps credentials and other people's data out of the prompt must be dumb, deterministic code — the moment that filter is "smart," your confidentiality guarantee is a probability.
+2. **Model outputs are proposals, not actions.**
+3. **Every side effect passes the gate.** There is no second door.
+4. **The harness itself flips no coins.** Replay a step with the model's answer and the tool results pinned, and behavior must be identical; any leftover variation is randomness *you* added and must be accounted for. The fine print: "deterministic" is conditional on pinned versions — a provider silently retraining the model behind the same API name changes the machine under you, and every dashboard number you collected dies with the version.
+
+Notice what the rules don't say: they don't say the harness is *good*. A gate that approves everything satisfies rule 3 the way a lock that's always open satisfies "has a lock." The definition is a shape; the guarantees are what a particular harness *earns* inside it. Everything below is about what can be earned — and what can't.
+
+And notice the symmetry between rules 1 and 3. There is exactly one door from your data into the model — what it may see — and exactly one door from the model into the world — what it may do. Nearly every security failure in these systems is one of those two doors with a hole in it: a secret lowered into a prompt that didn't need it, or a path from model text to a side effect that skipped the gate. Same bug, arrow flipped.
+
+## Fail-closed, said precisely
+
+"Fail-closed" gets used loosely. Here it means something exact: **nothing happens unless the gate said yes, and a refusal must itself be safe** — a refused proposal causes no side effect and leaves the run somewhere sane, which may be "stopped, having declined." The run is allowed to *say so*: a templated status message written by the shell is the shell speaking, not the model, and needs no gate. Failed runs don't have to die silent.
+
+Three consequences people miss:
+
+**Reads are not free.** A read-only call can smuggle instructions *in* (the fetched page is attacker-controlled) or secrets *out* (the URL it fetches can encode the payload). The gate approves calls, not just writes.
+
+**Validation must not act.** A "validator" that resolves a URL, expands a template that fires a webhook, or evaluates an argument has already acted — inside the check. The gate must be pure: it reads the proposal and the memory and outputs yes or no. If deciding requires touching the world, that touch is itself an action and goes through the gate.
+
+**Anything irreversible is decided at the gate.** The verifier can reject a bad *result*; it cannot unsend the email. So the question "can we take this back, and until when?" is asked before execution — which means each tool declares, up front, how reversible its effects are, and the gate reads that declaration when it decides; the mark that comes back in the result record is confirmation for the books, not the gate's source — the gate needed the answer before the tool ever ran.
+
+Two honest asterisks. First, the gate checks a snapshot: it approves against the world *as its memory describes it*, and the world can move between check and commit. For actions that race the world — spend against a balance, write against a row — the tool itself must bind check to commit (compare-and-swap), or you have a classic time-of-check/time-of-use hole. The gate decides; for those effects, the tool enforces. Second, a gate is only as binding as the authority behind the tools. A tool process holding standing credentials — a database connection with every grant, an environment full of long-lived secrets — doesn't need the model's proposal to act, and against it the gate's "no" is a decision with nothing enforcing it. **A gate in front of an omnipotent tool is a suggestion.** The fix is to make the approval *be* the key: each authorized action carries a short-lived credential scoped to exactly that action, that resource, that operation, so tools hold no standing power at all.
+
+## Why you don't get a proof — and what you do instead
+
+If you write a sort function, you can prove it sorts: the function is small and the spec is exact. A harness has neither luxury. The spec side fails first — the task arrives in natural language, and natural language is, in the compiler's sense, *all undefined behavior*: there is no formal standard for "what the user meant" to verify against. The mechanism side fails next — the model is billions of learned parameters, and nobody can hand you a compact argument for why they jointly do the right thing.
+
+Here is the careful version, because "you can't prove it" overshoots. The quantity you would want — call it the *expected steps to done* from any situation — is perfectly well-defined; in principle it exists. The document's central conjecture is that, for a model of this size, any faithful writing-down of that quantity is roughly *model-sized*: the honest proof-object does not compress. Find a small one and the conjecture dies — the document lists that outcome, explicitly, among the ways it could be wrong.
+
+So instead of proving, you measure. You pick a progress meter — plan depth shrinking, open obligations closing, budget burning at the expected rate — and you check, across many runs, that it goes downhill and that its stalls predict failure. Two disciplines keep the measurement honest. The number bounds the world you *sampled*, never the world an adversary will choose: a meter calibrated on friendly traffic says nothing about hostile traffic. And the meter is itself attack surface: if "is the agent making progress?" is judged by another model, an attacker who can bend your agent can bend your *measurement of it* first, hiding the divergence from the very dashboard built to catch it. A learned meter is part of the system under test, never a neutral instrument.
+
+A measurement is a risk metric. A proof is a certificate. Keeping those two words apart is half of what this theory is for.
+
+## Security: reach the goal, avoid the danger — and who may change the rules
+
+Formally, security here is a *reach-avoid* problem: reach a good stop, never touch the danger zone, **while an adversary picks the worst tool outputs your setup permits**. That last clause is the formal home of prompt injection: injection isn't "the model misbehaved," it's the environment optimized to bend your loop — poisoned pages, malicious tool descriptions, crafted responses.
+
+Two different numbers fall out here, and dashboards love to collapse them: *success* (reached an accepted end before anything went wrong — a safe refusal counts against it) and *safety* (never touched the danger zone — a safe refusal is perfectly safe). Track both. They move independently. And both are scored by your own stop rule — they count what the shell *declared* a success. Whether a declared success was actually *right* is a third, harder number that no dashboard inside the system can produce; only a judge outside the run — a test suite, an audit, ground truth — can.
+
+The gate handles the visible half of injection: the model, freshly poisoned, proposes emailing your credentials somewhere, and the gate refuses — and injection or not, the action does not happen. But the deeper attack doesn't propose a bad action today. It rewrites *what the run believes its job is* — it edits the plan — and then every future action looks locally reasonable against a corrupted plan. So memory has to be partitioned: **data** (tool results, fetched pages, retrieved documents — content the world supplied) and **control** (the plan, the permissions, what is authorized next). The security claim is conditional on that partition holding: untrusted content lands in data, always. And "trust" is really two questions pointing opposite ways, which is worth keeping straight: *can this leak?* (a value is as secret as the most-secret thing that fed it — secrecy flows **upward**) and *can this boss us around?* (a value is as trustworthy as the least-trustworthy thing that fed it — authority flows **downward**). Untrusted content is safe as *data* precisely because the second question keeps it off the control side; a secret is kept out of the model by the first. Lowering either barrier on purpose — declassifying a secret, promoting data to trusted — is an explicit decision the owner makes, never a thing that happens by accident when two values are combined.
+
+Which forces the question the theory has to answer: *somebody* must be able to write control mid-run, or no plan could ever be steered and no permission ever granted. The answer is a small hierarchy with a top the model can't reach. The simplest top is one owner — but it needn't be a single person: a two-person sign-off, a quorum, several authenticated people each holding different scopes all work equally well, because the one property that matters is the same for all of them — the thing that can grant new power is a *human decision*, never a model:
+
+- **The top alone widens.** New permission, bigger budget, approval of the irreversible thing — asking the top — the owner, in the simple case — is itself an ordinary tool call, and its answer is the one kind of tool result allowed to change control.
+- **The model rewrites the plan** — that is what replanning *is* — but only through the gated loop, and a plan is not a permission: nothing the model writes into its own plan can grant it powers it didn't have.
+- **Everything else is data.** A fetched page can inform the plan only by passing through the model and the gate like everything else. It can suggest. It cannot promote itself to boss.
+- **AI judges only tighten.** Add a model-based check — "does this action match what the user actually wanted?" — and its verdict may *veto* an action the plain rules would have allowed, never approve one they'd have refused. A judge that can approve is a tricked judge that can open the vault. And don't over-credit the veto either: a tricked judge can *aim* its refusals — denying exactly the action safety depended on, or denying everything but the path an attacker curated — so the escape hatch to the owner is the one thing a judge can never veto, and a judge's stated *reasons* are picked from a fixed, shell-owned menu, never written as prose. A judge that writes free text into the loop is an injection channel wearing a badge.
+
+One more rule closes the loop: transformations don't launder trust. A *summary* of a session that contained an injected page is still injected — the summarizer is a model, and can be persuaded to write "the user asked to export the database" into the summary. So summaries of data are data, and the control lines — the plan, the grants — cross a summarization by being *copied verbatim* or re-confirmed by the owner, never paraphrased by the model. Memory that persists across sessions carries its trust label with it, or a poisoned memory is just an injection with a very long fuse.
+
+## Operations: the rules you feel on Tuesday at 3 a.m.
+
+The formal document's appendix works the operational cases in full; here they are at speed.
+
+**The ledger, and the three-way distinction that keeps it honest.** Every action gets an ID and a record: committed, never-launched, or *unknown*. "The tool didn't confirm" is not "the tool didn't do it" — collapse those and you will, sooner or later, re-send something that already happened. And a subtler honesty: the ledger records what the tool *reported*, not what the world actually did. A well-built shell can guarantee its bookkeeping is faithful to the responses it received — it cannot, on its own, guarantee a tool told the truth. A tool that returns a clean "done!" for something it never did puts a clean "done!" in your ledger. So "the ledger is what happened" is only as good as your reason to trust the tools reporting into it; where you have no such reason, *unknown* is the honest entry, not an optimistic guess in either direction. The double-send bug has one reliable cure: **journal before dispatch.** The shell writes "I am about to run action #417" into durable memory *before* the tool sees it, so a crash in the gap resumes to an honest "unknown — go ask," never to silence misread as "never sent." Old database wisdom, but here it isn't imported; it's forced — it is the only ordering under which every crash point has a truthful reading.
+
+**Crashes aren't finishes.** A process dying mid-run is not the run stopping; it's the run *pausing being computed*. Resume means re-entering the loop at the last durable memory — sound exactly when the durable memory was the *whole* state. Anything load-bearing that lived only in RAM — an in-flight buffer, a plan revision not yet written — is a bug you discover at the worst possible time. Recovery is where you find out whether your state was really your state. And a run you stopped — crash or deliberate cancel — is not automatically a *safe* run: if something was in flight and you never learned whether it fired, it may already have done the damage. "We stopped in time" is only true when everything in flight resolved to something safe; an outstanding *unknown* has to be treated as possibly-bad, the same optimism the ledger warns against, one level up.
+
+**Two innocent actions can be guilty together.** Models emit several tool calls per turn. "Read the secret" passes review. "Post to the web" passes review. The pair is an exfiltration channel — so the gate authorizes the *set*, atomically, with the interactions checked, not each element in isolation.
+
+**Sub-agents are just fancy tools.** An agent that spawns another agent is, from the parent's chair, calling a tool: the spawn is gated, the budget is part of the deal, and the child's whole run comes back as one result carrying the child's ledger. Two laws travel down the tree: budgets subdivide, and **authority only narrows** — a child holds at most a subset of its parent's permissions, and a child's request beyond those grants routes *up*, ultimately to the owner, because a parent inventing an approval it never held is the tricked-judge case wearing a manager's badge. A corollary worth framing: a *fully autonomous* run is one whose owner is unreachable — meaning the only channel that can ever widen anything is closed, and its permissions are frozen at launch. That is not a limitation of the theory. That is what the word "autonomous" costs.
+
+**Keep the originals.** When the transcript outgrows the prompt and you summarize it down, deleting the original is an irreversible act against your own state — and irreversible acts are gate decisions, self-directed or not. Keep originals content-addressed; let the summary be an index, re-derivable, auditable. A summary you can check against its source is a note. A summary that replaced its source is a fait accompli.
+
+## Robots that never clock out — and robots that assign their own work
+
+Everything so far assumed a job that *ends*: you ask, the robot does it, you read the result. Two steps past that are where the interesting failures live, and they're the same idea one level bigger each time.
+
+**The robot that never clocks out (a daemon).** A monitor, a coordinator, a service — it isn't supposed to finish; it's supposed to keep going, wake on events, do a bit of work, go back to waiting. The clean way to think about it: each wake-work-rest cycle is one ordinary run, and the daemon is just those runs chained end to end forever. That reframing is free — but it comes with a bill nobody likes. **Safety that's fine per cycle rots over many cycles.** A 99.99%-safe cycle sounds bulletproof; run it ten thousand times and you're at about a coin-flip of having touched the danger zone at least once. So a long-running robot's safety isn't a fixed wall, it's a slow leak — which means the antidote isn't a better wall, it's *scheduled resets*: the owner re-confirming, credentials rotating, memory getting audited and re-summarized against the originals. Housekeeping isn't housekeeping; it's the thing that keeps the safety math from decaying. And the slow-leak logic is exactly where slow attacks live — a poisoned note dropped into memory on Monday and read back into the plan on Friday is an injection with a long fuse. So the trust label on a piece of information has to survive across cycles, not just within one. One more wrinkle: a daemon drifts in and out of your reach. While you're around, it can escalate to you; while you're not, "escalate to the owner" isn't available — so the one thing it must always be able to do instead is *stop*. A robot that can be tricked into refusing everything, and can't reach you, had better be able to halt rather than be steered.
+
+**The robot that assigns its own work (the loop).** Step back one more time. Above the robot that *does* a task sits a system that decides *which task is next* — scans the backlog, picks one, launches the robot at it, checks the result, remembers, fires again. This is the thing people mean in 2026 when they say they've stopped prompting their agents and started writing *loops* that prompt them: you design the assigner once, and it runs the doer for you while you sleep. The honest observation — and the reason this document bothers with it — is that the assigner is *not a new kind of thing*. It's the same harness, one level up: it has its own memory (the backlog), its own gate (**who let the loop refactor the auth module at 3 a.m.?**), its own verifier, and its own two walls. Every rule from the inner robot recurs on the outer one — including the uncomfortable ones. There's still no proof it stays out of trouble over a long night; there's only a measured progress meter, with the same catch that a *learned* meter can be fooled. And the origin story of the whole trend is the cautionary case in miniature: the famous first version was literally the same prompt in a `while` loop until the tests passed — which is the empty gate, the always-open lock, one level up. It works beautifully right up until the tests weren't checking the thing that mattered. The loop doesn't delete the hard problems. It moves them up a floor, where they're bigger and you're further away.
+
+The pattern, if you want the whole thing in one line: *words, context, robot, loop* are four sizes of the same object, and every promise in this document lives in the whole assembled thing — never in any one layer by itself.
+
+## The two walls
+
+Two limits are structural. You don't fix them with a better harness; you design around them.
+
+**The desk.** The model can hold only so much *in mind at once* — the context window. Files, databases, and search extend what it can *look up*, not what it can hold: every lookup still passes through the same small window to touch actual computation. The shell can page; the model cannot grow its desk. Tasks whose irreducible working set exceeds the desk don't fail loudly — they fail by forgetting the middle (the well-documented "lost in the middle" effect is this wall showing through the paint).
+
+**The dictionary.** The model's knowledge is frozen into its parameters at training time — and the proof problem above is conjectured to live at that same scale: the certificate wouldn't fit anywhere smaller than the brain it certifies. The two walls trade against each other along the training-versus-inference axis — bigger dictionary or bigger desk — directionally, and at no clean exchange rate.
+
+## How this could be wrong
+
+This is a hypothesis, and it says out loud what would kill it. The tests, in plain terms:
+
+- **The replay test.** Rerun with model answers and tool results pinned. Any leftover variation — timestamps, wall-clocks, and cache expiries are the classic leaks — falsifies "the harness adds no randomness" until accounted for.
+- **The drop-a-variable test.** Remove something from memory; if behavior statistics shift, the memory wasn't complete. The crash-resume version of the same test: if resuming from saved state breaks, the saved state wasn't the state.
+- **Does the meter mean anything?** If no reasonable progress meter's drift predicts real failures — across the natural families, not just one bad candidate — the whole "measure what you can't prove" program is empty.
+- **The red-team test.** Swap sampled tool outputs for worst-case ones: injected pages, poisoned metadata, malformed replies. The design must survive the worst permitted world, not the average one.
+- **Gates versus begging.** The theory predicts deterministic gating beats prompt-level pleading. If "please be careful" alone matches real gates on security outcomes, the controller-versus-model story is wrong.
+- **The compression hunt.** Exhibit a compact, provably sound progress certificate for a frontier-scale model on a nontrivial task family, and the central conjecture falls — constructively.
+- **The desk probe.** Take a task family with a *proven* memory floor — so "it needed the whole picture at once" is someone else's theorem, not our excuse — scale it past the window, and watch: the wall predicts a *ceiling*, not a cliff — past the boundary, a success rate that stays capped no matter how many retries you buy. A family solved reliably out there, without new shell tricks for splitting the work, kills the wall.
+
+## Who else landed here
+
+The formal document keeps three honesty tiers. **Borrowed**: real theorems, cited — the drift and stopping-time mathematics is classical, and the very architecture of a deterministic supervisor gating a plant it didn't author is 1987 control theory; the shape is older than the web. **Ours**: the modeling choices and the conjectures — the walls, the incompressibility claim, the design rules — organizing principles, not results. **Corroborated**: pieces of the same object reached independently by people who never saw this framing — capability-security work isolating control flow from untrusted data (CaMeL), reinforcement-learning "shields" filtering a learned policy's actions through a deterministic checker, verification work that states the "learned safeguards can't certify" gap as its opening motivation, and architecture patterns converging on plan-then-execute. Even the field's live disagreement — provable-but-rigid deterministic layers versus flexible-but-uncertifiable learned checks — is, in this frame, not a fight but a placement: you need both, on their proper sides of the irreversibility line, with the learned one permitted only to tighten.
+
+## What to remember
+
+The model proposes; the gate disposes. No is the default, and a refusal must be safe. Only the top of the trust hierarchy widens permissions — a human decision, never the model, a tool result, a summary, or a judge. "Didn't confirm" is not "didn't happen." The desk is finite and the proof doesn't compress, so you measure — and you say *measurement* when you mean measurement. A robot that never stops leaks safety slowly, so it needs scheduled resets — and when it can't reach you, it must be able to stop. A loop that runs robots for you is just a bigger robot with the same rules and a further-away owner. And all of it is a hypothesis wearing its own kill-conditions on its sleeve.
+
+The formal version — the objects, the certificates, the falsifiers, the citations — is [HYPOTHESIS.md](HYPOTHESIS.md). It wins every disagreement with this file, including this sentence.
+
+*Same ramblings, fewer symbols.*

README.md

@@ -21,7 +21,7 @@ Named after the [Ruddy Turnstone](https://en.wikipedia.org/wiki/Ruddy_turnstone)
 ℋ :  s_{n+1} ~ T(s_n)   for n < τ*,    T = ρ ∘ (M_W ∘ π, E)
 ```
 
-[**the hypothesis →**](HYPOTHESIS.md)
+[**the primer →**](PRIMER.md)
 
 ### Release Tracks
 

docs/api-reference.md

@@ -948,6 +948,7 @@ All fields are optional. The body can be empty or an empty JSON object.
 | `name`          | string | Auto-generated workstream name                      |
 | `resumed`       | bool   | Whether a previous session was successfully resumed |
 | `message_count` | int    | Number of messages in the resumed session (0 if fresh) |
+| `initial_message_status` | string | Present ONLY when the workstream was created but its `initial_message` could not be delivered: `"queue_full"` (a raced live worker's interjection queue was at capacity — resend via `/send`; any uploads stay staged) or `"refused_closed"` (the workstream was closed mid-create). Absent whenever the message was dispatched. |
 
 **Error (limit reached):**
 

docs/tools.md

@@ -1,6 +1,6 @@
 # Tools Reference
 
-turnstone exposes 16 built-in tools plus any number of external MCP tools to the
+turnstone exposes 17 built-in tools plus any number of external MCP tools to the
 LLM via the OpenAI function-calling interface. Built-in tools are defined as JSON
 files under `turnstone/tools/` and loaded at startup by `turnstone/core/tools.py`.
 MCP tools are discovered from configured MCP servers at startup by
@@ -44,10 +44,10 @@ schema plus turnstone-specific metadata keys:
 
 | Name                | Description |
 |---------------------|-------------|
-| `TOOLS`             | All 28 loaded built-in tool definitions (interactive + coordinator union). Sessions send a kind-specific subset (`INTERACTIVE_TOOLS` or `COORDINATOR_TOOLS`). |
+| `TOOLS`             | All 29 loaded built-in tool definitions (interactive + coordinator union). Sessions send a kind-specific subset (`INTERACTIVE_TOOLS` or `COORDINATOR_TOOLS`). |
 | `TASK_AGENT_TOOLS`  | Tools with `task_agent: true` -- available to task sub-agents. Includes write operations. |
 | `TASK_AUTO_TOOLS`   | Set of all tool names with `auto_approve: true` -- used by task-agent sub-sessions to skip confirmation for matching available tools. |
-| `BUILTIN_TOOL_NAMES`| Frozenset of all 28 built-in tool names (interactive + coordinator union). Used by tool search to distinguish always-on tools from deferrable MCP tools. |
+| `BUILTIN_TOOL_NAMES`| Frozenset of all 29 built-in tool names (interactive + coordinator union). Used by tool search to distinguish always-on tools from deferrable MCP tools. |
 | `PRIMARY_KEY_MAP`   | Dict mapping tool name to its `primary_key` parameter name. |
 
 ---
@@ -65,7 +65,7 @@ Tool execution follows a three-phase pipeline inside `ChatSession._execute_tools
 - Parses the JSON arguments (with fallback for malformed JSON).
 - If JSON parsing fails entirely, uses `PRIMARY_KEY_MAP` to map a bare string
   to the correct parameter.
-- Dispatches to the matching `_prepare_{func_name}()` handler. There are 16
+- Dispatches to the matching `_prepare_{func_name}()` handler. There are 17
   built-in tools plus `tool_search` (synthetic, client-side BM25 fallback) and
   the generic `_prepare_mcp_tool()` handler for MCP tools.
 - Validates arguments and builds a preview dict containing:
@@ -125,6 +125,9 @@ Each item's `execute` callable is invoked:
 - `web_fetch` -- fetches a URL (SSRF-protected, but makes network requests)
 - `web_search` -- web search via self-hosted SearxNG (makes network requests)
 - `task_agent` -- spawns an autonomous sub-agent
+- `open_preview` -- **URL targets only** (network access, gated like `web_fetch`);
+  file-path and `attachment:` targets are local reads and run unprompted like
+  `read_file`
 
 Note: The JSON schema metadata key `auto_approve` controls membership in
 `TASK_AUTO_TOOLS` (used for task agent sub-sessions). The actual runtime
@@ -157,6 +160,7 @@ Every tool defines a `primary_key`. The mapping is:
 | `search`     | `query`     |
 | `web_fetch`  | `url`       |
 | `web_search` | `query`     |
+| `open_preview` | `target`  |
 | `task_agent` | `prompt`    |
 | `memory`     | `name`      |
 | `recall`     | `query`     |
@@ -285,7 +289,7 @@ Fetch a URL and extract specific information from it.
 | `url`      | string | yes      | The URL to fetch (must start with `http://` or `https://`). |
 | `question` | string | yes      | What to extract or answer from the page content. |
 
-- **What it does**: Fetches the URL, strips HTML to plain text, and uses the LLM to extract the answer to the question from the page content. Protected against SSRF (blocks private/internal IPs).
+- **What it does**: Fetches the URL, strips HTML to plain text, and uses the LLM to extract the answer to the question from the page content. Every redirect hop is SSRF-screened before it is requested. Private/internal addresses are refused by default; enable `tools.allow_private_network` (console Settings → Tools) to make them approvable for self-hosted setups whose services live on the local network — the approval prompt marks such requests, and a public site redirecting into private space is refused regardless.
 - **Auto-approve**: No -- requires user confirmation (makes network requests).
 - **Agent availability**: `task_agent`.
 
@@ -345,6 +349,39 @@ It reports the score scale, whether the endpoint cleanly separates relevant from
 
 ---
 
+### open_preview
+
+Show the user rich content in a preview pane beside the conversation.
+
+| Parameter | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `target`  | string | yes      | An http(s) URL, a file path, or `attachment:<id>` for a file attached to the conversation. |
+| `kind`    | string | no       | Rendering override: `web`, `pdf`, `image`, `table`, `text`, or `markdown`. Detected from the content when omitted. |
+| `title`   | string | no       | Pane header title. Defaults to the page title, filename, or URL. |
+
+- **What it does**: Resolves the target to bytes (URLs fetch through the same
+  SSRF-guarded path as `web_fetch`, screened per redirect hop, honoring the
+  same `tools.allow_private_network` opt-in), classifies the
+  content, stores it content-addressed against the workstream, and opens the
+  frontend preview pane beside the conversation: web pages render in a fully
+  sandboxed iframe (no scripts, opaque origin), PDFs in the browser viewer,
+  images inline, CSV/TSV/JSON as a sortable table, text/markdown rendered. A
+  previewed web page loads none of its remote images or styles by default, so
+  opening it never reveals the viewer to the page's site; a toggle in the pane
+  header turns remote content back on for that preview. The
+  model receives only a one-line confirmation — to reason about content, use
+  `web_fetch` / `read_file` instead. Preview content is size-capped per kind
+  (pages 4 MB, PDFs 32 MB, images 4 MB, tables 2 MB, text 512 KB) and GC'd
+  with the workstream.
+- **Auto-approve**: URL targets require confirmation (network access); file
+  paths and `attachment:` targets run unprompted (local reads).
+- **Agent availability**: interactive sessions only (not `task_agent`, not
+  coordinators).
+- **Surfaces**: the pane renders in the web UI (standalone and console). The
+  CLI prints the confirmation line only — there is no terminal pane.
+
+---
+
 ## Agent
 
 The tool name uses the `_agent` suffix — bare `task` collides with
@@ -545,6 +582,7 @@ pre-configure skills at workstream creation.
 | `search`     | File Ops   | Yes          | Yes        | `query`     |
 | `web_fetch`  | Info       | No           | Yes        | `url`       |
 | `web_search` | Info       | No           | Yes        | `query`     |
+| `open_preview`| Info      | URL: no; path/attachment: yes | No | `target` |
 | `task_agent` | Agent      | No           | No         | `prompt`    |
 | `memory`     | Memory     | Yes          | No         | `name`      |
 | `recall`     | Memory     | Yes          | No         | `query`     |
@@ -654,7 +692,7 @@ MCP-compatible service.
 3. **Schema conversion**: Each MCP tool's `inputSchema` is converted to OpenAI
    function-calling format. The tool name is prefixed: `mcp__{server}__{tool}`.
 
-4. **Merging**: MCP tools are appended after the 16 built-in tools via
+4. **Merging**: MCP tools are appended after the 17 built-in tools via
    `merge_mcp_tools()`. Built-in tools appear first, giving them natural LLM priority.
    When dynamic tool search is active, MCP tools are deferred rather than directly
    visible -- the model discovers them via search as needed (see

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "turnstone"
-version = "1.7.1"
+version = "1.7.3"
 description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
 readme = "README.md"
 license = "Apache-2.0"
@@ -23,7 +23,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "openai>=2.37",
+    "openai>=2.44",  # GPT-5.6 (Sol/Terra/Luna): Responses reasoning.mode + effort "max" + text.verbosity
     "anthropic>=0.108",  # claude-fable-5 support; hard runtime floor is 0.105 (mid-conversation system blocks)
     "httpx>=0.28",
     "mcp>=1.27,<2",  # v2 is a breaking rewrite (2.0.0a1 live 2026-06-11; stable ~2026-07-27) — streamablehttp_client removed, 2-tuple transport, snake_case types; migrate deliberately

sdk/typescript/openapi-console.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "turnstone Console API",
-    "version": "1.7.0a6",
+    "version": "1.7.0rc1",
     "description": "Cluster-wide visibility and control across all turnstone nodes."
   },
   "paths": {
@@ -6688,7 +6688,7 @@
         "tags": [
           "Coordinator"
         ],
-        "description": "Aggregates the persisted row, a best-effort live block from the owning node (or the in-process coordinator manager for ``kind=\"coordinator\"`` rows), and the tail of the message history.  Gated on the ``admin.cluster.inspect`` permission (granted to ``builtin-admin`` via migration 040; revoke or reassign to a custom role for tighter control).  ``live`` is null on node unreachability / 5xx so callers can degrade gracefully.",
+        "description": "Aggregates the persisted row, a best-effort live block from the owning node (or the in-process coordinator manager for ``kind=\"coordinator\"`` rows), and the tail of the message history.  Gated on the ``admin.cluster.inspect`` permission (granted to ``builtin-admin`` via migration 040; revoke or reassign to a custom role for tighter control).  A workstream attached to a *private* project stays confidential to its members: a permitted caller who isn't its owner / creator / project member gets a 404 (same masking as an unknown id).  ``live`` is null on node unreachability / 5xx so callers can degrade gracefully.",
         "parameters": [
           {
             "name": "ws_id",
@@ -13361,7 +13361,7 @@
         "type": "object"
       },
       "PendingApprovalItem": {
-        "description": "One pending tool-call inside a ``PendingApprovalDetail`` envelope.\n\nMirrors the dict ``SessionUIBase.serialize_pending_approval_detail``\nemits per item. ``heuristic_verdict`` / ``judge_verdict`` are kept\nloosely-typed because the underlying verdict shape varies by tier;\nconsumers that want the full structure can decode against\n:class:`turnstone.sdk.events.IntentVerdictEvent`.",
+        "description": "One pending tool-call inside a ``PendingApprovalDetail`` envelope.\n\nMirrors the dict ``SessionUIBase.serialize_pending_approval_details``\nemits per item inside each cycle entry. ``heuristic_verdict`` / ``judge_verdict`` are kept\nloosely-typed because the underlying verdict shape varies by tier;\nconsumers that want the full structure can decode against\n:class:`turnstone.sdk.events.IntentVerdictEvent`.",
         "properties": {
           "call_id": {
             "default": "",

sdk/typescript/openapi-server.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "turnstone Server API",
-    "version": "1.7.0a6",
+    "version": "1.7.0rc1",
     "description": "Single-node workstream management, chat interaction, and real-time streaming."
   },
   "paths": {
@@ -2564,6 +2564,23 @@
             },
             "title": "Attachment Ids",
             "type": "array"
+          },
+          "initial_message_status": {
+            "anyOf": [
+              {
+                "enum": [
+                  "queue_full",
+                  "refused_closed"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Present ONLY when the workstream was created but its initial_message could not be delivered: 'queue_full' (a raced live worker's interjection queue was at capacity \u2014 resend via /send; any uploads stay staged) or 'refused_closed' (the workstream was closed mid-create). Absent whenever the message was dispatched.",
+            "title": "Initial Message Status"
           }
         },
         "required": [
@@ -2747,7 +2764,7 @@
         "type": "object"
       },
       "PendingApprovalItem": {
-        "description": "One pending tool-call inside a ``PendingApprovalDetail`` envelope.\n\nMirrors the dict ``SessionUIBase.serialize_pending_approval_detail``\nemits per item. ``heuristic_verdict`` / ``judge_verdict`` are kept\nloosely-typed because the underlying verdict shape varies by tier;\nconsumers that want the full structure can decode against\n:class:`turnstone.sdk.events.IntentVerdictEvent`.",
+        "description": "One pending tool-call inside a ``PendingApprovalDetail`` envelope.\n\nMirrors the dict ``SessionUIBase.serialize_pending_approval_details``\nemits per item inside each cycle entry. ``heuristic_verdict`` / ``judge_verdict`` are kept\nloosely-typed because the underlying verdict shape varies by tier;\nconsumers that want the full structure can decode against\n:class:`turnstone.sdk.events.IntentVerdictEvent`.",
         "properties": {
           "call_id": {
             "default": "",

sdk/typescript/src/types.ts

@@ -164,6 +164,13 @@ export interface CreateWorkstreamResponse {
   message_count?: number;
   /** Ids of attachments saved by this request (multipart variant only). */
   attachment_ids?: string[];
+  /**
+   * Present ONLY when the workstream was created but its initial_message
+   * could not be delivered: "queue_full" (raced live worker's interjection
+   * queue at capacity — resend via /send; uploads stay staged) or
+   * "refused_closed" (workstream closed mid-create).
+   */
+  initial_message_status?: "queue_full" | "refused_closed";
 }
 
 export interface CloseWorkstreamRequest {

tests/_helpers.py

@@ -3,9 +3,37 @@ not fixtures, and several test files want to import them directly."""
 
 from __future__ import annotations
 
-from typing import Any
+import time
+from typing import TYPE_CHECKING, Any
 from unittest.mock import MagicMock
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def wait_until(cond: Callable[[], bool], timeout: float = 5.0) -> None:
+    """Poll ``cond`` to True within ``timeout`` or fail the test.
+
+    The worker/wake tests can't join threads by identity:
+    ``session_worker.send`` assigns ``ws.worker_thread`` under the lock
+    BEFORE ``t.start()``, so the instant a dispatching call returns, a
+    fast worker may already have run its exit backstop and installed the
+    (not-yet-started) wake thread — joining whatever ``ws.worker_thread``
+    points at races ``RuntimeError: cannot join thread before it is
+    started``.  Poll outcomes instead.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if cond():
+            return
+        time.sleep(0.005)
+    if cond():
+        # Final re-check: the condition can become true during the last
+        # sleep (or a CI descheduling stall past the deadline) — failing
+        # without re-looking makes the helper itself a flake source.
+        return
+    raise AssertionError("condition not met within timeout")
+
 
 def make_chat_session(**overrides: Any) -> Any:
     """Build a minimal ``ChatSession`` with sane test defaults.

tests/data/wire_payloads/openai_responses_max__text.json

@@ -0,0 +1,30 @@
+{
+  "include": [
+    "reasoning.encrypted_content"
+  ],
+  "input": [
+    {
+      "content": "Hi there.",
+      "role": "user",
+      "type": "message"
+    },
+    {
+      "content": "Hello! How can I help?",
+      "role": "assistant",
+      "type": "message"
+    },
+    {
+      "content": "What's the weather in Paris?",
+      "role": "user",
+      "type": "message"
+    }
+  ],
+  "max_output_tokens": 4096,
+  "model": "gpt-5.6-sol",
+  "prompt_cache_retention": "24h",
+  "reasoning": {
+    "effort": "max"
+  },
+  "store": false,
+  "stream": true
+}

tests/data/wire_payloads/openai_responses_max__toolcall_complete.json

@@ -0,0 +1,55 @@
+{
+  "include": [
+    "reasoning.encrypted_content"
+  ],
+  "input": [
+    {
+      "content": "Weather in Paris?",
+      "role": "user",
+      "type": "message"
+    },
+    {
+      "arguments": "{\"city\": \"Paris\"}",
+      "call_id": "call_1",
+      "name": "get_weather",
+      "type": "function_call"
+    },
+    {
+      "call_id": "call_1",
+      "output": "18C, clear.",
+      "type": "function_call_output"
+    },
+    {
+      "content": "It's 18C and clear in Paris.",
+      "role": "assistant",
+      "type": "message"
+    }
+  ],
+  "max_output_tokens": 4096,
+  "model": "gpt-5.6-sol",
+  "prompt_cache_retention": "24h",
+  "reasoning": {
+    "effort": "max"
+  },
+  "store": false,
+  "stream": true,
+  "tools": [
+    {
+      "description": "Look up the weather for a city.",
+      "name": "get_weather",
+      "parameters": {
+        "properties": {
+          "city": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "city"
+        ],
+        "type": "object"
+      },
+      "strict": false,
+      "type": "function"
+    }
+  ]
+}

tests/data/wire_payloads/openai_responses_verbosity_pro__text.json

@@ -0,0 +1,34 @@
+{
+  "include": [
+    "reasoning.encrypted_content"
+  ],
+  "input": [
+    {
+      "content": "Hi there.",
+      "role": "user",
+      "type": "message"
+    },
+    {
+      "content": "Hello! How can I help?",
+      "role": "assistant",
+      "type": "message"
+    },
+    {
+      "content": "What's the weather in Paris?",
+      "role": "user",
+      "type": "message"
+    }
+  ],
+  "max_output_tokens": 4096,
+  "model": "gpt-5.6-sol",
+  "prompt_cache_retention": "24h",
+  "reasoning": {
+    "effort": "high",
+    "mode": "pro"
+  },
+  "store": false,
+  "stream": true,
+  "text": {
+    "verbosity": "low"
+  }
+}

tests/test_app_js.py

@@ -1592,6 +1592,287 @@ def test_coord_connectsse_onerror_preserves_native_reconnect() -> None:
     assert passed, f"coordinator.js connectSSE.onerror regressed: {reason}"
 
 
+# ---------------------------------------------------------------------------
+# Coordinator-pane parity for the SSE overflow-recovery companions (issue #806).
+# The server-side fixes (emit-time batching, _ListenerQueue poison, out-of-band
+# closing) live in SessionUIBase and already cover EVERY SSE stream; these pin
+# the CLIENT-side companions ported into coordinator.js so it stops relying on
+# native reconnect alone — storm guard + degraded catch-up, close-on-hide /
+# replay-on-show, and drop-vs-render-wedge counters.
+# ---------------------------------------------------------------------------
+
+
+def test_coord_imports_shared_overflow_helpers() -> None:
+    """coordinator.js consumes the SAME sse_overflow.js helpers as the
+    interactive pane (over the /shared mount) so the trip threshold and cooldown
+    ladder cannot drift between the two surfaces."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    m = re.search(
+        r"import \{([^}]*)\} from \"/shared/sse_overflow\.js\";",
+        body,
+        re.S,
+    )
+    assert m is not None, "coordinator must import the shared overflow helpers"
+    imported = m.group(1)
+    for name in (
+        "OVERFLOW_TRIP_COUNT",
+        "OVERFLOW_TRIP_WINDOW_MS",
+        "DEGRADED_COOLDOWN_BASE_MS",
+        "DEGRADED_COOLDOWN_MAX_MS",
+        "DEGRADED_COOLDOWN_RESET_MS",
+        "overflowWindowTripped",
+        "degradedCooldownStep",
+    ):
+        assert name in imported, f"{name} must be imported from /shared/sse_overflow.js"
+    # No local fork of the extracted pure functions on the coordinator side.
+    assert not re.search(r"^\s*function overflowWindowTripped\(", body, re.M)
+    assert not re.search(r"^\s*function degradedCooldownStep\(", body, re.M)
+
+
+def test_coord_stream_overflow_case_counts_and_rate_limits() -> None:
+    """The coordinator handles the id-less ``stream_overflow`` frame: count it
+    (drop-vs-wedge field instrumentation) and feed the rolling-window storm
+    guard, exactly like the interactive pane."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    assert 'case "stream_overflow":' in body
+    assert "noteStreamOverflow();" in body
+    # The three-way health counter distinguishes dropped events (overflow /
+    # malformed frame) from render wedges (dispatch / render throw).
+    assert "streamHealth = { overflows: 0, renderThrows: 0, malformedFrames: 0 }" in body
+    assert "streamHealth.overflows += 1;" in body
+    assert "streamHealth.malformedFrames += 1;" in body
+    # Exactly two render-throw increment sites: the noteRenderThrow helper
+    # (all three contained render/finalize catches route through it — they
+    # recover with a plain-text fallback, so console.warn) and the onmessage
+    # dispatch catch (console.error class — the event is dropped outright).
+    # The three recovered call sites are pinned by label so a new render path
+    # that forgets to count surfaces loudly.
+    assert body.count("streamHealth.renderThrows += 1;") == 2
+    helper = re.search(r"function noteRenderThrow\(where, err\)\s*\{(.*?)\n  \}", body, re.S)
+    assert helper is not None, "noteRenderThrow helper not found"
+    assert "streamHealth.renderThrows += 1;" in helper.group(1)
+    assert 'noteRenderThrow("streamingRender", e);' in body
+    assert 'noteRenderThrow("in_progress_snapshot render", e);' in body
+    assert 'noteRenderThrow("streamingRenderFinalize", e);' in body
+    note = re.search(r"function noteStreamOverflow\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert note is not None, "noteStreamOverflow not found"
+    assert "overflowWindowTripped(" in note.group(1)
+    assert "enterDegradedCatchup()" in note.group(1)
+    # The trip handler only counts + trips; the cooldown reset lives in
+    # enterDegradedCatchup (keyed off lastDegradedAt) — the finding [0] shape.
+    assert "degradedCooldownMs" not in note.group(1), (
+        "noteStreamOverflow must not touch the cooldown — that reset defeated the ladder escalation"
+    )
+
+
+def test_coord_handleevent_dispatch_is_wedge_guarded() -> None:
+    """A throw escaping onmessage does NOT close the EventSource, so an
+    unguarded handler throw left the streaming refs stale and wedged every later
+    turn.  The coordinator wraps the dispatch and counts the throw (render-wedge
+    class) so a field report tells it apart from a dropped-events gap."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    m = re.search(r"try \{\s*handleEvent\(data\);\s*\} catch \(err\) \{(.*?)\}", body, re.S)
+    assert m is not None, "handleEvent(data) must be wrapped in try/catch in onmessage"
+    assert "streamHealth.renderThrows += 1;" in m.group(1)
+
+
+def test_coord_degraded_catchup_stops_live_stream_and_retries() -> None:
+    """Three overflow closes inside the window drop the coordinator to a
+    degraded catch-up: suspend the live stream, say so plainly, and reconnect
+    after a doubling cooldown — the reconnect replays the gap (or falls to the
+    /history floor once it outgrows the ring)."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    m = re.search(r"function enterDegradedCatchup\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert m is not None, "enterDegradedCatchup not found"
+    method = m.group(1)
+    assert "degradedCooldownStep(" in method
+    assert "lastDegradedAt = now" in method
+    # Suspend the stream BEFORE arming the retry timer (mirrors interactive's
+    # disconnect-then-rearm ordering) or the fresh timer is cancelled at once.
+    assert method.index("suspendStream()") < method.index("degradedTimer = setTimeout")
+    # Plain-language status, not a silent stall.
+    assert "catching up" in method
+    # A fresh connect must cancel a pending degraded timer so it can't
+    # double-open behind the retry — connectSSE's prologue routes through the
+    # shared closeStreamTransport teardown, which owns that clear (alongside
+    # the reconnect timer + the EventSource close/null).
+    conn = re.search(r"function connectSSE\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert conn is not None
+    assert "closeStreamTransport();" in conn.group(1)
+    teardown = re.search(r"function closeStreamTransport\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert teardown is not None, "closeStreamTransport not found"
+    assert "clearTimeout(degradedTimer)" in teardown.group(1)
+    assert "clearTimeout(reconnectTimer)" in teardown.group(1)
+    assert "evtSource = null;" in teardown.group(1)
+
+
+def test_coord_visibilitychange_closes_on_hide_reconnects_on_show() -> None:
+    """A hidden tab's throttled drain is the worst-case slow SSE consumer.  The
+    coordinator installs a visibilitychange handler that closes the stream on
+    hide (marking its OWN close via hiddenDisconnect) and reconnects on show from
+    the saved lastEventId, and removes the listener on teardown."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    assert 'document.addEventListener("visibilitychange", visHandler);' in body
+    assert 'document.removeEventListener("visibilitychange", visHandler);' in body
+    vis = re.search(r"function onVisibilityChange\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert vis is not None, "onVisibilityChange not found"
+    method = vis.group(1)
+    assert "document.hidden" in method
+    assert "suspendStream()" in method
+    assert "hiddenDisconnect = true;" in method
+    assert "else if (hiddenDisconnect)" in method
+    assert "connectSSE();" in method
+
+
+def test_coord_connectsse_defers_open_when_tab_hidden() -> None:
+    """connectSSE must never open an EventSource into a hidden tab — the single
+    chokepoint that also backstops a FIRST connect in a background tab (where the
+    close-on-hide handler never fires because there was no open stream).  It
+    marks hiddenDisconnect so the show edge owns the reconnect, marks the
+    deferral as a GAP (markStreamGap) so the eventual open runs the post-gap
+    recovery — without the mark a pane first opened in a background tab
+    silently missed every child/task created while hidden — and reports an
+    honest paused status instead of pinning "connecting" with no attempt in
+    flight."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    conn = re.search(r"function connectSSE\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert conn is not None
+    method = conn.group(1)
+    guard = method.index("if (document.hidden)")
+    open_idx = method.index("new EventSource(")
+    assert guard < open_idx, "the hidden guard must precede new EventSource"
+    head = method[guard:open_idx]
+    assert "markStreamGap();" in head, "the hidden deferral must count as a stream gap"
+    assert "hiddenDisconnect = true;" in head
+    assert "return;" in head
+    assert 'setSseStatus("paused' in head, "the deferral must report paused, not connecting"
+    # "connecting" is claimed only once an attempt actually starts — after
+    # the hidden guard, immediately before the EventSource construction.
+    connecting = method.index('setSseStatus("connecting')
+    assert guard < connecting < open_idx
+
+
+def test_coord_destroy_removes_visibility_handler_and_stream_transport() -> None:
+    """Teardown must detach the document-level visibilitychange listener (it
+    holds a strong ref to the closure) and tear down the stream transport —
+    closeStreamTransport closes the EventSource and cancels the reconnect +
+    degraded retry timers (pinned in the degraded-catchup test) — or a
+    destroyed pane leaks and a show edge / pending retry reopens its stream."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    d = re.search(r"function destroy\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert d is not None, "destroy not found"
+    method = d.group(1)
+    assert "removeVisibilityHandler();" in method
+    assert "closeStreamTransport();" in method
+
+
+def test_coord_close_session_detaches_visibility_reopen() -> None:
+    """coordCloseSession suspends the stream AND removes the visibilitychange
+    handler BEFORE awaiting the /close POST: a tab hide→show while the POST is
+    in flight must not reopen a stream against the workstream the server is
+    tearing down (404 / reconnect churn against a dead session).  The failure
+    paths resume via connectSSE, which reinstalls the handler at its
+    install-once chokepoint — so close-on-hide survives a failed close."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    m = re.search(r"async function coordCloseSession\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert m is not None, "coordCloseSession not found"
+    method = m.group(1)
+    suspend = method.index("suspendStream();")
+    unhook = method.index("removeVisibilityHandler();")
+    # The quoted URL fragment, not the bare word (comments mention /close too).
+    post = method.index('"/close"')
+    assert suspend < post, "stream suspension must precede the /close POST"
+    assert unhook < post, "visibility detach must precede the /close POST"
+    assert "resumeSse()" in method
+
+
+def test_coord_post_gap_sidebar_refresh_is_replay_aware() -> None:
+    """The replace-mode children/tasks refresh (a sidebar rebuild) must NOT
+    fire on every reconnect: child_ws_* / task-mutating events are ordinary
+    ring-buffer entries, so a cursor reconnect (replay_ok) redelivers them and
+    the sidebar heals through the normal handlers — a momentary blur→focus
+    under close-on-hide must not rebuild the sidebar.  The refresh fires
+    exactly when the replay cannot vouch for the gap: no resume cursor or an
+    over-threshold gap at onopen, or the server's replay_truncated envelope
+    (ring evicted), deduped per open via gapRefreshedAtOpen."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    conn = re.search(r"function connectSSE\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert conn is not None
+    method = conn.group(1)
+    gate = re.search(
+        r"wasReconnecting &&\s*\(lastEventId == null \|\| gapMs > GAP_REFRESH_THRESHOLD_MS\)",
+        method,
+    )
+    assert gate is not None, "onopen must gate the sidebar refresh on replay coverage"
+    assert "refreshSidebarAfterGap();" in method
+    assert "gapRefreshedAtOpen = true;" in method
+    # The ring-evicted signal triggers the same refresh (deduped per open).
+    trunc = re.search(r'case "replay_truncated":(.*?)break;', body, re.S)
+    assert trunc is not None, "replay_truncated case not found"
+    assert "refreshSidebarAfterGap()" in trunc.group(1)
+    assert "gapRefreshedAtOpen" in trunc.group(1)
+    # Deliberate suspends (hide / overflow / close-session) mark the gap so
+    # the next open participates in the recovery decision at all.
+    sus = re.search(r"function suspendStream\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert sus is not None, "suspendStream not found"
+    assert "markStreamGap();" in sus.group(1)
+    # The refresh helper carries the whole replace-mode bundle: children,
+    # tasks, and the live-badge purge (permanent 403/404 entries preserved).
+    ref = re.search(r"function refreshSidebarAfterGap\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert ref is not None, "refreshSidebarAfterGap not found"
+    assert "loadChildren({ replace: true });" in ref.group(1)
+    assert "loadTasks();" in ref.group(1)
+    assert "_liveBadgeCacheDelete(id)" in ref.group(1)
+
+
+def test_coord_defers_truncated_resync_and_consumes_at_idle() -> None:
+    """replay_truncated seen mid-stream must be DEFERRED, not dropped (matches
+    interactive's _pendingTruncatedResync): refetching immediately would detach
+    the live bubble (content OR a reasoning-only one), but skipping outright
+    leaves the ring-evicted turns lost for the session.  The guard covers both
+    streaming targets and latches otherwise; the next state_change=idle consumes
+    the flag — which also repairs a turn stranded by close-on-hide (stream_end
+    evicted while hidden), resetting the streaming refs first since
+    refetchHistory does not null them."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    trunc = re.search(r'case "replay_truncated":(.*?)break;', body, re.S)
+    assert trunc is not None, "replay_truncated case not found"
+    t = trunc.group(1)
+    assert "if (!currentAssistantEl && !currentReasoningEl)" in t
+    assert "refetchHistory();" in t
+    assert "pendingTruncatedResync = true;" in t
+    st = re.search(r'case "state_change":(.*?)\n      case ', body, re.S)
+    assert st is not None, "state_change case not found"
+    s = st.group(1)
+    assert "if (pendingTruncatedResync)" in s
+    assert "pendingTruncatedResync = false;" in s
+    assert "currentAssistantEl = null;" in s
+    assert "refetchHistory();" in s
+    # Consume the latch, THEN reset the dangling refs and refetch.
+    consume = s.index("pendingTruncatedResync = false;")
+    refetch = s.index("refetchHistory();")
+    assert consume < refetch
+
+
+def test_coord_detects_server_restart_by_backwards_event_id() -> None:
+    """A coordinator process restart resets the per-ws event counter, and the
+    replay path reports replay_ok for a stale-high cursor (past the new max), so
+    the gap is unsignalled and the sidebar goes stale.  onmessage catches it: a
+    live event id below the saved cursor == the counter reset → pull
+    authoritative sidebar state (deduped per open against onopen's refresh),
+    checked BEFORE the cursor is overwritten."""
+    body = _COORD_JS.read_text(encoding="utf-8")
+    m = re.search(r"evtSource\.onmessage = function \(event\) \{(.*?)\n    \};", body, re.S)
+    assert m is not None, "onmessage handler not found"
+    handler = m.group(1)
+    assert "Number(evtSource.lastEventId) < Number(lastEventId)" in handler
+    assert "!gapRefreshedAtOpen" in handler
+    assert "refreshSidebarAfterGap();" in handler
+    check = handler.index("Number(evtSource.lastEventId) < Number(lastEventId)")
+    overwrite = handler.index("lastEventId = evtSource.lastEventId;")
+    assert check < overwrite
+
+
 def test_interactive_history_is_rest_first_not_sse() -> None:
     """PR A converged interactive onto coord's REST-first history
     model: first paint and post-rewind re-render fetch ``GET /history``

tests/test_cancel.py

@@ -13,7 +13,7 @@ from turnstone.core.session import (
     ChatSession,
     GenerationCancelled,
     _CancelRef,
-    _effect_status_meta,
+    _tool_turn_meta,
 )
 from turnstone.core.trajectory import (
     EffectStatus,
@@ -1183,8 +1183,13 @@ class TestEffectStatusPersistence:
     effect-record appendix — the ledger persists for audit)."""
 
     def test_effect_status_meta_envelope(self):
-        assert _effect_status_meta(None) is None
-        assert json.loads(_effect_status_meta(EffectStatus.UNKNOWN)) == {"effect_status": "unknown"}
+        assert _tool_turn_meta(None) is None
+        assert json.loads(_tool_turn_meta(EffectStatus.UNKNOWN)) == {"effect_status": "unknown"}
+        assert json.loads(_tool_turn_meta(None, {"kind": "web"})) == {"preview": {"kind": "web"}}
+        assert json.loads(_tool_turn_meta(EffectStatus.UNKNOWN, {"kind": "web"})) == {
+            "effect_status": "unknown",
+            "preview": {"kind": "web"},
+        }
 
     def test_reconstruct_routes_tool_effect_status(self):
         from turnstone.core.storage._utils import reconstruct_turns

tests/test_console.py

@@ -2690,3 +2690,56 @@ class TestCollectorMCPAggregation:
         assert overview["mcp_servers"] == 3
         assert overview["mcp_resources"] == 10
         assert overview["mcp_prompts"] == 7
+
+
+class TestProxyGetHeaderPassThrough:
+    """The generic /node/{id} GET proxy must carry the node's hardening
+    headers through — dropping Content-Security-Policy would serve previewed
+    attacker HTML from the CONSOLE origin with no CSP sandbox (review
+    finding, preview-pane branch)."""
+
+    def test_security_headers_forwarded(self, monkeypatch):
+        from types import SimpleNamespace
+        from unittest.mock import MagicMock
+
+        import httpx
+
+        from turnstone.console import server as csrv
+
+        upstream = httpx.Response(
+            200,
+            content=b"<html>page</html>",
+            headers={
+                "content-type": "text/html; charset=utf-8",
+                "content-security-policy": "sandbox",
+                "x-content-type-options": "nosniff",
+                "content-disposition": 'inline; filename="p"',
+                "cache-control": "private, no-store",
+                "server": "upstream-internal",  # hop metadata: must NOT pass
+            },
+            request=httpx.Request("GET", "http://n:1/x"),
+        )
+
+        async def _mock_get(*a, **kw):
+            return upstream
+
+        proxy_client = MagicMock(spec=httpx.AsyncClient)
+        proxy_client.get = MagicMock(side_effect=_mock_get)
+        request = SimpleNamespace(
+            app=SimpleNamespace(state=SimpleNamespace(proxy_client=proxy_client)),
+            url=SimpleNamespace(query=""),
+        )
+        monkeypatch.setattr(csrv, "_proxy_auth_headers", lambda r: {})
+
+        resp = asyncio.run(csrv._proxy_get(request, "http://n:1", "v1/api/x"))
+
+        assert resp.status_code == 200
+        assert resp.headers["content-security-policy"] == "sandbox"
+        assert resp.headers["x-content-type-options"] == "nosniff"
+        assert resp.headers["content-disposition"] == 'inline; filename="p"'
+        assert resp.headers["cache-control"] == "private, no-store"
+        assert resp.headers["content-type"].startswith("text/html")
+        assert (
+            "server" not in {k.lower() for k in resp.headers}
+            or resp.headers.get("server") != "upstream-internal"
+        )

tests/test_coord_rich_ws_state_payload.py

@@ -114,11 +114,16 @@ def test_coord_on_aux_usage_leaves_live_counters_untouched() -> None:
     assert ui._ws_context_ratio == 0.0
 
 
-def test_coord_on_content_token_accumulates() -> None:
+def test_coord_on_content_token_accumulates(monkeypatch: pytest.MonkeyPatch) -> None:
     """Pre-lift coord ``on_content_token`` only enqueued; lift turns it
     into the same per-ws accumulator WebUI uses so the collector
     broadcast can piggyback the joined turn content on the IDLE
-    state-change event."""
+    state-change event.
+
+    Batch window forced to 0 (per-token flush) — pins the accumulator
+    wiring, not the batching cadence (test_sse_token_batching.py)."""
+
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
     ui = ConsoleCoordinatorUI(ws_id="coord-ws", user_id="u1")
     ui.on_content_token("Hello ")
     ui.on_content_token("world")

tests/test_coordinator_adapter.py

@@ -245,6 +245,24 @@ def test_cleanup_ui_tolerates_missing_session_and_ui() -> None:
     ws.session = None
     ws.ui = None
     adapter.cleanup_ui(ws)  # no crash
+    assert ws._closed is True  # still marked dead
+
+
+def test_cleanup_ui_marks_workstream_closed() -> None:
+    """Every teardown path — close, close_idle, EVICTION, delete,
+    discard — funnels through cleanup_ui, which marks the object dead
+    under ``ws._lock`` BEFORE the teardown body runs.  The wake paths
+    that hold OBJECT references (the watch ``wake_fn``,
+    ``session_worker``'s exit backstop) gate on ``_closed``, and
+    ``session_worker.send`` re-checks it under the same lock — without
+    this write here, a wake racing an eviction or delete (which never
+    set the flag) would spawn a full unattended turn on the torn-down
+    session."""
+    adapter, _ = _make_adapter()
+    ws = _make_ws()
+    assert ws._closed is False
+    adapter.cleanup_ui(ws)
+    assert ws._closed is True
 
 
 # ---------------------------------------------------------------------------

tests/test_coordinator_tools.py

@@ -35,7 +35,14 @@ class _StubUI:
     def on_error(self, msg: str) -> None:
         self.errors.append(msg)
 
-    def on_tool_result(self, call_id: str, name: str, output: str, is_error: bool = False) -> None:
+    def on_tool_result(
+        self,
+        call_id: str,
+        name: str,
+        output: str,
+        is_error: bool = False,
+        preview: dict[str, Any] | None = None,
+    ) -> None:
         self.tool_results.append((call_id, name, output, is_error))
 
     # Other SessionUI methods — only stubs, not exercised here.

tests/test_idle_nudge_wake_integration.py

@@ -28,8 +28,10 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
+from tests._helpers import wait_until as _wait_until
 from tests.test_session_manager import FakeStorage
-from turnstone.core.idle_nudge_watcher import IdleNudgeWatcher
+from turnstone.core import session_worker
+from turnstone.core.idle_nudge_watcher import IdleNudgeWatcher, wake_workstream_if_pending
 from turnstone.core.session import ChatSession
 from turnstone.core.session_manager import SessionManager
 from turnstone.core.trajectory import dicts_from_turns, turn_from_dict
@@ -299,6 +301,72 @@ def test_idle_event_with_empty_queue_does_not_dispatch_wake(real_mgr, tmp_db):
         watcher.shutdown()
 
 
+def test_watch_fire_on_already_idle_session_drives_wake_send(real_mgr, tmp_db):
+    """A watch firing on an ALREADY-idle workstream sees no IDLE
+    transition, so :class:`IdleNudgeWatcher` never re-checks the queue —
+    the dispatch closure's ``wake_fn`` must drive the wake itself.
+
+    Boundary path under test (only the LLM stream is patched):
+      dispatch closure (real, built by ``set_watch_runner``)
+        → NudgeQueue.enqueue (real)
+        → wake_fn → wake_workstream_if_pending (real)
+        → session_worker.send (real) → daemon thread
+        → ChatSession.deliver_wake_nudge_from_queue (real)
+        → ChatSession.send("") → watch_triggered system turn in history
+    """
+    mgr, _adapter = real_mgr
+    ws = mgr.create(user_id="u1", name="watch-wake-int", skill=None)
+    assert ws.session is not None
+
+    captured: dict[str, Any] = {}
+
+    class _StubRunner:
+        def set_dispatch_fn(self, ws_id: str, fn: Any) -> None:
+            captured["fn"] = fn
+
+    # Production wiring shape (server.py): wake_fn closes over the
+    # Workstream OBJECT — not its id — so eviction+restore id drift
+    # can't strand the wake.
+    ws.session.set_watch_runner(
+        _StubRunner(), wake_fn=lambda: wake_workstream_if_pending(ws, trigger="watch-fire")
+    )
+
+    with (
+        patch.object(ws.session, "_create_stream_with_retry", return_value=iter([])),
+        patch.object(
+            ws.session,
+            "_stream_response",
+            return_value={"role": "assistant", "content": "ok"},
+        ),
+        patch.object(ws.session, "_update_token_table"),
+        patch.object(ws.session, "_print_status_line"),
+        patch.object(ws.session, "_visible_memory_count", return_value=0),
+        patch("turnstone.core.session.save_message"),
+    ):
+        ws.session._title_generated = True
+        # Idle all along — no worker, and no state transition coming.
+        assert ws.state is WorkstreamState.IDLE
+
+        # Simulate the WatchRunner poll thread delivering a fire.
+        captured["fn"]({"type": "watch_triggered", "text": "deploy finished: OK"}, "watch-1")
+
+        _wait_for_worker_done(ws)
+
+    # Queue drained by the wake — not parked until the next user message.
+    assert len(ws.session._nudge_queue) == 0
+
+    msgs = dicts_from_turns(ws.session.messages)
+    user_msgs = [m for m in msgs if m.get("role") == "user"]
+    assert user_msgs, "expected a synthesized user message from the wake"
+    assert user_msgs[-1]["content"] == ""
+    assert user_msgs[-1].get("_source") == "system_nudge"
+    sys_turns = [m for m in msgs if m.get("role") == "system"]
+    assert any(
+        m.get("_source") == "watch_triggered" and "deploy finished: OK" in m.get("content", "")
+        for m in sys_turns
+    ), f"expected a watch_triggered system turn, got {sys_turns!r}"
+
+
 @pytest.fixture
 def coord_mgr() -> tuple[SessionManager, _BuildRealSessionAdapter, FakeStorage]:
     """Real coord-side SessionManager with the adapter's kind set to
@@ -411,3 +479,120 @@ def test_coord_idle_with_active_children_emits_envelope_via_real_managers(coord_
     finally:
         watcher.shutdown()
         observer.shutdown()
+
+
+def test_coord_idle_emitted_from_worker_thread_still_wakes(coord_mgr, tmp_db):
+    """The production-shaped race the test above does NOT exercise: in
+    production, IDLE is emitted from INSIDE the worker (``set_state``
+    subscribers fire on the calling thread — the coord's send emits IDLE
+    before its worker exits).  The watcher's wake dispatch therefore
+    lands on ``session_worker.send``'s reuse path while the
+    transitioning worker still owns the flag, and no-ops.  Without the
+    ownership-clear backstop the ``idle_children`` nudge strands until
+    the next user message — a coord that forgot ``wait_for_workstream``
+    never revives.
+
+    Boundary path under test:
+      worker thread: mgr.set_state(IDLE)
+        → observer enqueues (real) → watcher wake no-ops (worker owns flag)
+        → run() returns → session_worker._runner finally clears the flag
+        → _retry_pending_wake → wake_workstream_if_pending (real)
+        → wake daemon → deliver_wake_nudge_from_queue → send("")
+        → idle_children system turn in history
+    """
+    from turnstone.console.coordinator_idle_observer import CoordinatorIdleObserver
+    from turnstone.core.workstream import WorkstreamKind as _Kind
+
+    mgr, adapter, storage = coord_mgr
+    observer = CoordinatorIdleObserver(mgr, storage)
+    observer.start()
+    watcher = IdleNudgeWatcher(mgr)
+    watcher.start()
+
+    try:
+        coord = mgr.create(user_id="u1", name="parent-coord-2", skill=None)
+        assert coord.session is not None
+
+        storage.register_workstream(
+            "child-x",
+            user_id="u1",
+            name="crawl-docs",
+            kind=_Kind.INTERACTIVE,
+            parent_ws_id=coord.id,
+            state="running",
+        )
+
+        coord.session.messages.append(turn_from_dict({"role": "user", "content": "spawn 1"}))
+        coord.session.messages.append(turn_from_dict({"role": "assistant", "content": "ok"}))
+
+        with (
+            patch.object(coord.session, "_create_stream_with_retry", return_value=iter([])),
+            patch.object(
+                coord.session,
+                "_stream_response",
+                return_value={"role": "assistant", "content": "ack"},
+            ),
+            patch.object(coord.session, "_full_messages", return_value=[]),
+            patch.object(coord.session, "_update_token_table"),
+            patch.object(coord.session, "_print_status_line"),
+            patch.object(coord.session, "_visible_memory_count", return_value=0),
+            patch("turnstone.core.session.save_message"),
+        ):
+            coord.session._title_generated = True
+
+            # Drive the IDLE transition from INSIDE a session_worker
+            # worker, as production does.
+            ok = session_worker.send(
+                coord,
+                enqueue=lambda: None,
+                run=lambda: mgr.set_state(coord.id, WorkstreamState.IDLE),
+                thread_name="coord-send-sim",
+            )
+            assert ok is True
+            # Without the backstop the queue never drains (the watcher's
+            # transition-time wake no-opped against the sim worker) and
+            # this poll times out.  Queue-empty implies the wake worker's
+            # drain ran, so the follow-up flag poll waits for ITS exit.
+            _wait_until(lambda: len(coord.session._nudge_queue) == 0)
+            _wait_for_worker_done(coord)
+
+        # Queue drained by the wake, not waiting on the next user message.
+        assert len(coord.session._nudge_queue) == 0
+        msgs = dicts_from_turns(coord.session.messages)
+        user_msgs = [m for m in msgs if m.get("role") == "user"]
+        wake_msg = user_msgs[-1]
+        assert wake_msg["content"] == ""
+        assert wake_msg.get("_source") == "system_nudge"
+        idle_turns = [
+            m for m in msgs if m.get("role") == "system" and m["_source"] == "idle_children"
+        ]
+        assert len(idle_turns) == 1
+        assert "crawl-docs" in idle_turns[0]["content"]
+        assert "wait_for_workstream" in idle_turns[0]["content"]
+    finally:
+        watcher.shutdown()
+        observer.shutdown()
+
+
+def test_wake_delivery_contains_generation_cancelled(tmp_db):
+    """A close/force-cancel racing the wake turn raises
+    ``GenerationCancelled`` (a BaseException) out of ``send("")`` — the
+    wake method must contain it: it IS the wake worker's ``run()``
+    closure, and ``session_worker._runner`` catches only ``Exception``,
+    so an escape would land in ``threading.excepthook`` as stderr noise
+    on every close-vs-wake race."""
+    from tests._helpers import make_chat_session
+    from turnstone.core.session import GenerationCancelled
+
+    session = make_chat_session()
+    session._nudge_queue.enqueue("idle_children", "kids waiting", "any")
+
+    def _cancelled_send(*_a: Any, **_k: Any) -> None:
+        raise GenerationCancelled
+
+    session.send = _cancelled_send  # type: ignore[method-assign]
+
+    session.deliver_wake_nudge_from_queue()  # must not raise
+
+    assert session._wake_source_tag == ""
+    assert session._wake_drained_reminders is None

tests/test_idle_nudge_watcher.py

@@ -9,13 +9,14 @@ module-level function to capture calls without spawning real threads.
 from __future__ import annotations
 
 import contextlib
+import logging
 import threading
 from typing import Any
 from unittest.mock import patch
 
 import pytest
 
-from turnstone.core.idle_nudge_watcher import IdleNudgeWatcher
+from turnstone.core.idle_nudge_watcher import IdleNudgeWatcher, wake_workstream_if_pending
 from turnstone.core.nudge_queue import NudgeQueue
 from turnstone.core.workstream import WorkstreamState
 
@@ -32,6 +33,7 @@ class _FakeSession:
 class _FakeWorkstream:
     def __init__(self, ws_id: str = "ws-test") -> None:
         self.id = ws_id
+        self.state = WorkstreamState.IDLE
         self.session: _FakeSession | None = _FakeSession()
         self._lock = threading.Lock()
         self._worker_running = False
@@ -163,3 +165,154 @@ class TestIdleNudgeWatcher:
         watcher.start()
         watcher.shutdown()
         watcher.shutdown()  # no error
+
+
+class TestWakeWorkstreamIfPending:
+    """Direct tests for the shared wake gate.
+
+    The IDLE-transition path (via the watcher) is covered above; these
+    pin the gates the watch dispatch closure relies on when it calls
+    the helper directly, with no state event involved.
+    """
+
+    def test_wakes_idle_ws_with_pending_entry(self, fake_mgr_and_ws):
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("watch_triggered", "output", "any")
+        with patch("turnstone.core.session_worker.send", return_value=True) as mock_send:
+            assert wake_workstream_if_pending(ws) is True
+            assert mock_send.call_count == 1
+            kwargs = mock_send.call_args.kwargs
+            assert kwargs["enqueue"]() is None
+            kwargs["run"]()
+            assert ws.session.deliver_wake_nudge_from_queue_called == 1
+            assert kwargs["thread_name"].startswith("wake-nudge-")
+
+    def test_skips_session_none(self, fake_mgr_and_ws):
+        _mgr, ws = fake_mgr_and_ws
+        ws.session = None
+        with patch("turnstone.core.session_worker.send") as mock_send:
+            assert wake_workstream_if_pending(ws) is False
+            assert mock_send.call_count == 0
+
+    def test_skips_closed_ws(self, fake_mgr_and_ws):
+        """A workstream mid-``close()`` must not get a wake spawned on
+        its torn-down session, even while its ``state`` field still
+        reads IDLE (there is no CLOSED member — close uses the
+        ``_closed`` tombstone)."""
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("watch_triggered", "output", "any")
+        ws._closed = True
+        with patch("turnstone.core.session_worker.send") as mock_send:
+            assert wake_workstream_if_pending(ws) is False
+            assert mock_send.call_count == 0
+
+    def test_skips_non_idle_states(self, fake_mgr_and_ws):
+        """Busy states imply a live worker that drains at its own seams;
+        ERROR stays parked for the operator — neither gets a wake."""
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("watch_triggered", "output", "any")
+        with patch("turnstone.core.session_worker.send") as mock_send:
+            for state in (
+                WorkstreamState.RUNNING,
+                WorkstreamState.THINKING,
+                WorkstreamState.ATTENTION,
+                WorkstreamState.ERROR,
+            ):
+                ws.state = state
+                assert wake_workstream_if_pending(ws) is False
+            assert mock_send.call_count == 0
+
+    def test_skips_tool_only_entries(self, fake_mgr_and_ws):
+        """Tool-channel entries belong to the next tool-result seam — a
+        synthetic empty user turn can't drain them, so no wake."""
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("tool_error", "check memories", "tool")
+        with patch("turnstone.core.session_worker.send") as mock_send:
+            assert wake_workstream_if_pending(ws) is False
+            assert mock_send.call_count == 0
+
+    def test_refuses_non_nudgequeue_stub(self, fake_mgr_and_ws):
+        """The gate refuses on TYPE, not just presence: a mock session's
+        auto-created ``_nudge_queue`` answers ``has_pending`` truthily
+        while its ``deliver_wake_nudge_from_queue`` consumes nothing —
+        with the worker-exit backstop re-running this gate after every
+        exit, one worker on such a session would respawn wake workers
+        forever (the storm that took down the full-suite CI run).  Only
+        a real :class:`NudgeQueue` carries the drain semantics the wake
+        contract needs."""
+        from unittest.mock import MagicMock
+
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue = MagicMock()  # truthy has_pending, no real drain
+        with patch("turnstone.core.session_worker.send") as mock_send:
+            assert wake_workstream_if_pending(ws) is False
+            assert mock_send.call_count == 0
+
+    def test_dispatched_path_logs_trigger(self, fake_mgr_and_ws, caplog):
+        """A fresh spawn — ``send`` returns True without touching the
+        passed ``enqueue`` — emits ``nudge_wake.dispatched`` tagged with
+        the trigger label (structlog renders the event name + ``%s``
+        placeholders into ``msg``; substring-match like the sibling
+        nudge_queue tests)."""
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("watch_triggered", "output", "any")
+        with (
+            patch("turnstone.core.session_worker.send", return_value=True) as mock_send,
+            caplog.at_level(logging.INFO, logger="turnstone.core.idle_nudge_watcher"),
+        ):
+            assert wake_workstream_if_pending(ws, trigger="idle-transition") is True
+            assert mock_send.call_count == 1
+        dispatched = [r for r in caplog.records if "nudge_wake.dispatched" in r.getMessage()]
+        assert len(dispatched) == 1
+        assert dispatched[0].levelno == logging.INFO
+        assert "trigger=" in dispatched[0].getMessage()
+        # The reuse-path drop line must not appear on a fresh spawn.
+        assert not any("nudge_wake.deferred_worker_busy" in r.getMessage() for r in caplog.records)
+
+    def test_deferred_path_logs_worker_busy(self, fake_mgr_and_ws, caplog):
+        """The reuse path — ``send`` invokes the passed ``enqueue`` and
+        returns True — emits ``nudge_wake.deferred_worker_busy`` instead
+        of ``dispatched``.  The entry stays owed to the owning worker's
+        exit backstop; the return value is still True."""
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("watch_triggered", "output", "any")
+
+        def _reuse_send(_ws: Any, *, enqueue: Any, run: Any, thread_name: Any) -> bool:
+            # Mimic a live worker owning the workstream: send routes the
+            # wake to the no-op enqueue rather than spawning a daemon.
+            enqueue()
+            return True
+
+        with (
+            patch("turnstone.core.session_worker.send", side_effect=_reuse_send) as mock_send,
+            caplog.at_level(logging.INFO, logger="turnstone.core.idle_nudge_watcher"),
+        ):
+            assert wake_workstream_if_pending(ws, trigger="idle-transition") is True
+            assert mock_send.call_count == 1
+        deferred = [
+            r for r in caplog.records if "nudge_wake.deferred_worker_busy" in r.getMessage()
+        ]
+        assert len(deferred) == 1
+        assert deferred[0].levelno == logging.INFO
+        assert "trigger=" in deferred[0].getMessage()
+        assert not any("nudge_wake.dispatched" in r.getMessage() for r in caplog.records)
+
+    def test_refused_path_logs_refusal(self, fake_mgr_and_ws, caplog):
+        """``send`` refusing outright — its authoritative under-lock
+        ``_closed`` re-check caught a teardown the gate's lockless peek
+        missed — emits ``nudge_wake.refused``: a dropped wake must stay
+        traceable to its trigger, not vanish silently."""
+        _mgr, ws = fake_mgr_and_ws
+        ws.session._nudge_queue.enqueue("watch_triggered", "output", "any")
+        with (
+            patch("turnstone.core.session_worker.send", return_value=False) as mock_send,
+            caplog.at_level(logging.INFO, logger="turnstone.core.idle_nudge_watcher"),
+        ):
+            assert wake_workstream_if_pending(ws, trigger="watch-fire") is False
+            assert mock_send.call_count == 1
+        refused = [r for r in caplog.records if "nudge_wake.refused" in r.getMessage()]
+        assert len(refused) == 1
+        assert refused[0].levelno == logging.INFO
+        assert "trigger=" in refused[0].getMessage()
+        assert not any("nudge_wake.dispatched" in r.getMessage() for r in caplog.records)
+        assert not any("nudge_wake.deferred_worker_busy" in r.getMessage() for r in caplog.records)

tests/test_interactive_pane_js.py

@@ -429,3 +429,210 @@ def test_sync_approval_state_prunes_orphan_cycles() -> None:
     assert "this.approvalCycles.delete(cid);" in tail, (
         "orphan pruning must delete the cycle from the Map"
     )
+
+
+# ---------------------------------------------------------------------------
+# SSE overflow recovery + close-on-hide (fast-stream corruption fixes)
+# ---------------------------------------------------------------------------
+
+
+def test_stream_overflow_case_counts_and_rate_limits() -> None:
+    """The server closes an overflowed stream after an id-less
+    ``stream_overflow`` frame; the pane must count it (field
+    instrumentation for the drop-vs-render-wedge diagnosis) and route it
+    through the reconnect limiter so a persistently slow consumer trips
+    the degraded catch-up instead of churning reconnect/replay cycles."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    assert 'case "stream_overflow":' in body
+    assert "this._noteStreamOverflow();" in body
+    assert "_streamHealth = { overflows: 0, renderThrows: 0, malformedFrames: 0 }" in body
+    # Both wedge-class catch sites increment the render-throw counter,
+    # and the malformed-frame drop counts too — the C-OVERDETERMINED
+    # instrumentation that tells drops apart from wedges in the field.
+    assert body.count("this._streamHealth.renderThrows += 1;") == 2
+    assert "this._streamHealth.malformedFrames += 1;" in body
+    assert "this._streamHealth.overflows += 1;" in body
+
+
+def test_degraded_catchup_stops_live_stream_and_retries() -> None:
+    """Degraded catch-up contract: close the stream FIRST (which also
+    clears any earlier degraded timer — disconnectSSE owns that), show a
+    plain-language status, then arm the retry timer with a doubling
+    cooldown.  The retry must defer to the show edge when the tab is
+    hidden (reopening into a throttled tab would overflow again)."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    m = re.search(r"_enterDegradedCatchup\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert m is not None, "_enterDegradedCatchup method not found"
+    method = m.group(1)
+    # Order matters: disconnect before arming the timer, or the fresh
+    # timer would be cancelled by its own disconnect.
+    assert method.index("this.disconnectSSE()") < method.index("this._degradedTimer = setTimeout")
+    assert "Connection is slow" in method, "degraded state must use plain language"
+    assert "DEGRADED_COOLDOWN_MAX_MS" in method
+    assert "document.hidden" in method
+    # disconnectSSE owns the timer teardown (ws-switch / giveUp / destroy
+    # all supersede a pending degraded retry through it).
+    dis = re.search(r"disconnectSSE\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert dis is not None
+    assert "clearTimeout(this._degradedTimer)" in dis.group(1)
+
+
+def test_visibilitychange_closes_on_hide_reconnects_on_show() -> None:
+    """Close-on-hide / replay-on-show: a hidden tab's throttled drain is
+    the likeliest slow consumer behind server-side overflow (the old
+    "PR-G closes those connections on hide" comment described a handler
+    that never existed).  The pane installs one visibilitychange
+    listener, marks ITS OWN hide-closes via ``_hiddenDisconnect`` so a
+    show edge never resurrects a deliberately-closed stream, and the
+    factory's destroy removes the listener (it strongly references the
+    pane)."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    assert 'document.addEventListener("visibilitychange", this._visHandler);' in body
+    assert 'document.removeEventListener("visibilitychange", this._visHandler);' in body
+    vis = re.search(r"_onVisibilityChange\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert vis is not None, "_onVisibilityChange method not found"
+    method = vis.group(1)
+    assert "this.disconnectSSE();" in method
+    assert "this._hiddenDisconnect = true;" in method
+    assert "this.connectSSE(this.wsId);" in method
+    # Reconnect only consumes OUR hide-close marker.
+    assert "else if (this._hiddenDisconnect)" in method
+    # Teardown: the factory controller removes the listener on destroy.
+    assert "pane._removeVisibilityHandler();" in body
+    # The streaming buffers survive a hide-close: disconnectSSE stays
+    # transport-only (no contentBuffer wipe) so the visible tail is
+    # intact when the tab returns.
+    dis = re.search(r"disconnectSSE\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert dis is not None
+    assert "contentBuffer" not in dis.group(1)
+
+
+def test_no_global_sse_gap_detector() -> None:
+    """Live event ids are NOT strictly monotonic across concurrent
+    tool+content emit (the fan-out runs outside the listeners lock), so
+    a naive ``id !== lastEventId + 1`` gap check would false-positive.
+    Recovery is server-signalled (``stream_overflow``) + reconnect
+    replay instead.  This tripwire pins the absence of the naive
+    arithmetic — if gap detection is ever added, it must be scoped to
+    the content stream only (content-vs-content never reorders)."""
+    code = _strip_comments(_INTERACTIVE.read_text(encoding="utf-8"))
+    assert not re.search(r"_lastEventId\s*[+\-]\s*1", code), (
+        "found lastEventId +/- 1 arithmetic — a global gap detector "
+        "false-positives on legal concurrent tool/content id inversion"
+    )
+
+
+def test_overflow_helpers_extracted_to_shared_module() -> None:
+    """The storm-guard constants + the two pure helpers were extracted to the
+    shared ``sse_overflow.js`` module (its own runtime probes live in
+    ``test_sse_overflow_js.py``) so the interactive and coordinator panes can't
+    drift.  Pin that the pane IMPORTS them rather than re-declaring a local
+    copy: a stray local ``function overflowWindowTripped`` / ``const
+    OVERFLOW_TRIP_COUNT`` would silently fork the trip math again."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    m = re.search(
+        r"import \{([^}]*)\} from \"\./sse_overflow\.js\";",
+        body,
+        re.S,
+    )
+    assert m is not None, "interactive pane must import the shared overflow helpers"
+    imported = m.group(1)
+    for name in (
+        "OVERFLOW_TRIP_COUNT",
+        "OVERFLOW_TRIP_WINDOW_MS",
+        "DEGRADED_COOLDOWN_BASE_MS",
+        "DEGRADED_COOLDOWN_MAX_MS",
+        "DEGRADED_COOLDOWN_RESET_MS",
+        "overflowWindowTripped",
+        "degradedCooldownStep",
+    ):
+        assert name in imported, f"{name} must be imported from sse_overflow.js"
+    # No local fork of the extracted definitions.
+    assert not re.search(r"^function overflowWindowTripped\(", body, re.M), (
+        "overflowWindowTripped must be imported, not re-declared locally"
+    )
+    assert not re.search(r"^function degradedCooldownStep\(", body, re.M), (
+        "degradedCooldownStep must be imported, not re-declared locally"
+    )
+    assert not re.search(r"^const OVERFLOW_TRIP_COUNT\s*=", body, re.M), (
+        "the trip constants must be imported, not re-declared locally"
+    )
+
+
+def test_note_stream_overflow_does_not_reset_cooldown() -> None:
+    """The exact finding [0] bug shape must not regress: _noteStreamOverflow
+    only counts + trips; it must NOT touch _degradedCooldownMs (the reset
+    that defeated the ladder lived here).  The ladder decision lives solely
+    in _enterDegradedCatchup, keyed off _lastDegradedAt via
+    degradedCooldownStep."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    note = re.search(r"_noteStreamOverflow\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert note is not None, "_noteStreamOverflow not found"
+    assert "_degradedCooldownMs" not in note.group(1), (
+        "_noteStreamOverflow must not write _degradedCooldownMs — that reset "
+        "was the bug that stopped the ladder escalating"
+    )
+    enter = re.search(r"_enterDegradedCatchup\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert enter is not None
+    assert "degradedCooldownStep(" in enter.group(1)
+    assert "this._lastDegradedAt = now" in enter.group(1)
+
+
+def test_recover_beat_defers_reconnect_when_tab_hidden() -> None:
+    """Review round-2 finding [1]: the factory's transient-error recovery
+    beat (recoverTimer) must NOT reopen an EventSource into a hidden tab —
+    that re-creates the throttled slow-consumer overflow that close-on-hide
+    exists to prevent.  It guards on document.hidden and defers to the
+    visibilitychange show edge (marking _hiddenDisconnect)."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    beat = re.search(r"recoverTimer = setTimeout\(\(\) => \{(.*?)\n      \}, 5000\);", body, re.S)
+    assert beat is not None, "recoverTimer setTimeout body not found"
+    b = beat.group(1)
+    assert "document.hidden" in b, "recovery beat must guard on document.hidden"
+    assert "pane._hiddenDisconnect = true" in b, (
+        "recovery beat must defer to the show edge when hidden"
+    )
+    # The hidden guard must precede the reconnect (connectSSE) so it can't fall
+    # through to reopening the stream.
+    assert b.index("document.hidden") < b.index("pane.connectSSE(pane.wsId)")
+
+
+def test_giveup_removes_visibility_handler() -> None:
+    """Review round-2 finding [3]: giveUp() (markDead) must detach the
+    visibility handler and clear _hiddenDisconnect, or a tab hidden before
+    the give-up resurrects the dead controller's stream on return (the show
+    edge would connectSSE the closed ws and 404-reconnect it forever)."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    give = re.search(r"const giveUp = function \(\) \{(.*?)\n  \};", body, re.S)
+    assert give is not None, "giveUp function body not found"
+    g = give.group(1)
+    assert "pane._removeVisibilityHandler();" in g, (
+        "giveUp must remove the visibility handler so a show edge can't resurrect a dead controller"
+    )
+    # _removeVisibilityHandler also clears _hiddenDisconnect (pinned in its body).
+    rvh = re.search(r"_removeVisibilityHandler\(\)\s*\{(.*?)\n  \}", body, re.S)
+    assert rvh is not None
+    assert "this._hiddenDisconnect = false" in rvh.group(1)
+
+
+def test_connectsse_defers_open_when_tab_hidden() -> None:
+    """PR #805 review (Copilot + R3): connectSSE is the single connect
+    chokepoint and must not open an EventSource into a hidden tab.  The
+    fresh-connect path (_loadHistoryThenConnect) has no timer guard, so a
+    first load in a background tab would otherwise open a throttled stream —
+    the slow-consumer overflow this PR exists to prevent.  The guard sits
+    AFTER the visibilitychange-handler install (so the show edge can
+    reconnect) and AFTER the wsId assignment (so it targets the right ws),
+    and BEFORE `new EventSource` (so nothing opens)."""
+    body = _INTERACTIVE.read_text(encoding="utf-8")
+    start = body.index("connectSSE(wsId) {")
+    open_at = body.index("new EventSource(evtUrl)", start)
+    head = body[start:open_at]  # connectSSE up to the EventSource open
+    assert "if (document.hidden) {" in head, (
+        "connectSSE must guard on document.hidden BEFORE opening the stream"
+    )
+    assert "this._hiddenDisconnect = true;" in head, (
+        "the deferred connect must mark _hiddenDisconnect so the show edge reconnects"
+    )
+    assert head.index("this.wsId = wsId;") < head.index("if (document.hidden) {")
+    assert head.index('addEventListener("visibilitychange"') < head.index("if (document.hidden) {")

tests/test_migration_066.py

@@ -0,0 +1,103 @@
+"""Tests for alembic migration 066 (persona + project on scheduled_tasks).
+
+Drives ``command.upgrade``/``downgrade`` against an isolated SQLite database per
+test (the 060/062/063/065 harness pattern), then asserts:
+
+* upgrade adds the ``persona`` and ``project_id`` columns to ``scheduled_tasks``;
+* a pre-066 scheduled task migrates cleanly, gaining ``""`` for both new columns
+  — the empty default that means "kind default persona" / "no project" and
+  preserves byte-identical dispatch behaviour to pre-066;
+* downgrade removes both columns, returning ``scheduled_tasks`` to its exact
+  pre-066 shape — pinning the clean-rollback guarantee;
+* up -> down -> up lands cleanly with no leftover-column conflict.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import sqlalchemy as sa
+from alembic import command
+from alembic.config import Config
+
+_MIGRATIONS_DIR = str(
+    Path(__file__).resolve().parent.parent / "turnstone" / "core" / "storage" / "migrations"
+)
+
+
+def _alembic_cfg(db_path: Path) -> Config:
+    cfg = Config()
+    cfg.set_main_option("script_location", _MIGRATIONS_DIR)
+    cfg.set_main_option("sqlalchemy.url", f"sqlite:///{db_path}")
+    return cfg
+
+
+def _insert_pre066_task(engine: sa.Engine) -> None:
+    with engine.begin() as conn:
+        conn.execute(
+            sa.text(
+                "INSERT INTO scheduled_tasks "
+                "(task_id, name, schedule_type, initial_message, created, updated) "
+                "VALUES ('t1', 'Nightly', 'cron', 'run', "
+                "'2026-01-01T00:00:00', '2026-01-01T00:00:00')"
+            )
+        )
+
+
+class TestMigration066:
+    def test_upgrade_adds_persona_and_project_columns(self, tmp_path: Path) -> None:
+        db_path = tmp_path / "066-up.db"
+        command.upgrade(_alembic_cfg(db_path), "066")
+
+        engine = sa.create_engine(f"sqlite:///{db_path}")
+        try:
+            cols = {c["name"] for c in sa.inspect(engine).get_columns("scheduled_tasks")}
+            assert {"persona", "project_id"} <= cols
+        finally:
+            engine.dispose()
+
+    def test_preexisting_row_migrates_with_empty_default(self, tmp_path: Path) -> None:
+        db_path = tmp_path / "066-default.db"
+        cfg = _alembic_cfg(db_path)
+        # Stop at 065, insert a pre-066 scheduled task, THEN upgrade to 066.
+        command.upgrade(cfg, "065")
+        engine = sa.create_engine(f"sqlite:///{db_path}")
+        try:
+            _insert_pre066_task(engine)
+            command.upgrade(cfg, "066")
+            with engine.connect() as conn:
+                row = conn.execute(
+                    sa.text("SELECT persona, project_id FROM scheduled_tasks WHERE task_id = 't1'")
+                ).fetchone()
+            assert row is not None
+            assert row[0] == "" and row[1] == ""
+        finally:
+            engine.dispose()
+
+    def test_downgrade_removes_persona_and_project_columns(self, tmp_path: Path) -> None:
+        db_path = tmp_path / "066-down.db"
+        cfg = _alembic_cfg(db_path)
+        command.upgrade(cfg, "066")
+        command.downgrade(cfg, "065")
+
+        engine = sa.create_engine(f"sqlite:///{db_path}")
+        try:
+            cols = {c["name"] for c in sa.inspect(engine).get_columns("scheduled_tasks")}
+            assert "persona" not in cols and "project_id" not in cols
+        finally:
+            engine.dispose()
+
+    def test_downgrade_then_upgrade_round_trip(self, tmp_path: Path) -> None:
+        """up -> down -> up must land cleanly (no leftover column conflict)."""
+        db_path = tmp_path / "066-roundtrip.db"
+        cfg = _alembic_cfg(db_path)
+        command.upgrade(cfg, "066")
+        command.downgrade(cfg, "065")
+        command.upgrade(cfg, "066")
+
+        engine = sa.create_engine(f"sqlite:///{db_path}")
+        try:
+            cols = {c["name"] for c in sa.inspect(engine).get_columns("scheduled_tasks")}
+            assert {"persona", "project_id"} <= cols
+        finally:
+            engine.dispose()

tests/test_open_preview_tool.py

@@ -0,0 +1,815 @@
+"""End-to-end coverage for the ``open_preview`` tool wiring.
+
+Spans the seams the preview descriptor rides: preparer validation +
+approval posture, executor target resolution (mocked ``httpx`` for URLs,
+tmp files for paths, monkeypatched storage for attachments), the
+``_tool_previews`` side channel + live SSE event, the ``Turn.meta``
+round-trip, the ``/history`` projection, the storage reconstruct routing,
+and the auth scope of the serving route.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from turnstone.core.session import ChatSession
+from turnstone.core.trajectory import Role, turn_from_dict, turn_to_dict
+
+PNG_1x1 = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+    b"\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\rIDATx\x9cc\xfc\xcf"
+    b"\xc0\xc0\xc0\x00\x00\x00\x05\x00\x01\xa5\xf6E@\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+
+
+class _RecordingUI:
+    """SessionUI double that records tool_result calls (kwargs included)."""
+
+    def __init__(self):
+        self.tool_results = []
+
+    def __getattr__(self, name):
+        # Every other SessionUI hook is an inert no-op.
+        def _noop(*args, **kwargs):
+            return None
+
+        return _noop
+
+    def on_tool_result(self, call_id, name, output, **kwargs):
+        self.tool_results.append((call_id, name, output, kwargs))
+
+
+def _make_session(**kwargs):
+    defaults = dict(
+        client=MagicMock(),
+        model="test-model",
+        ui=_RecordingUI(),
+        instructions=None,
+        temperature=0.5,
+        max_tokens=4096,
+        tool_timeout=5,
+    )
+    defaults.update(kwargs)
+    return ChatSession(**defaults)
+
+
+def _fake_response(url, body, content_type):
+    import httpx
+
+    resp = SimpleNamespace()
+    # A real httpx.URL so the executor's userinfo-strip path runs unmocked.
+    resp.url = httpx.URL(url)
+    resp.content = body
+    resp.text = body.decode("utf-8", errors="replace")
+    resp.headers = {"content-type": content_type}
+    resp.raise_for_status = lambda: None
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Preparer
+# ---------------------------------------------------------------------------
+
+
+class TestPrepareOpenPreview:
+    def test_missing_target_errors(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {})
+        assert item["error"].startswith("Error: missing target")
+
+    def test_invalid_kind_errors(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {"target": "a.txt", "kind": "hologram"})
+        assert "kind must be one of" in item["error"]
+
+    def test_url_target_needs_approval(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {"target": "https://example.com/x"})
+        assert item["needs_approval"] is True
+        assert item["target_kind"] == "url"
+        assert item["approval_label"] == "open_preview"
+        assert "error" not in item
+
+    def test_private_url_blocked_pre_approval(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {"target": "http://169.254.169.254/meta"})
+        assert "error" in item
+        assert item["needs_approval"] is False
+
+    def test_path_target_runs_unprompted(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {"target": "~/notes.md"})
+        assert item["needs_approval"] is False
+        assert item["target_kind"] == "path"
+        assert not item["path"].startswith("~")
+
+    def test_attachment_target(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {"target": "attachment:abc123"})
+        assert item["needs_approval"] is False
+        assert item["target_kind"] == "attachment"
+        assert item["attachment_id"] == "abc123"
+        empty = s._prepare_open_preview("c1", {"target": "attachment:"})
+        assert "error" in empty
+
+
+# ---------------------------------------------------------------------------
+# Executor
+# ---------------------------------------------------------------------------
+
+
+class TestExecOpenPreview:
+    def test_url_html_builds_web_descriptor(self, monkeypatch):
+        s = _make_session()
+        body = b"<html><head><title>Acme Pricing</title></head><body>x</body></html>"
+        monkeypatch.setattr(
+            "turnstone.core.session.fetch_with_ssrf_guard",
+            lambda url, **kw: _fake_response(url, body, "text/html; charset=utf-8"),
+        )
+        item = s._prepare_open_preview("c1", {"target": "https://acme.com/pricing"})
+        call_id, msg = s._exec_open_preview(item)
+        assert call_id == "c1"
+        assert "Acme Pricing" in msg
+        descriptor, att = s._tool_previews["c1"]
+        assert descriptor["kind"] == "web"
+        assert descriptor["title"] == "Acme Pricing"
+        assert descriptor["source"] == "https://acme.com/pricing"
+        assert descriptor["content_type"].startswith("text/html")
+        assert att.kind == "preview"
+        # The stored bytes gained a base for relative-asset resolution.
+        assert b'<base href="https://acme.com/pricing">' in att.content
+        # The live event carried the descriptor.
+        results = s.ui.tool_results
+        assert results and results[-1][3].get("preview") == descriptor
+
+    def test_url_userinfo_stripped_from_descriptor(self, monkeypatch):
+        s = _make_session()
+        body = b"<html><head></head><body>x</body></html>"
+        monkeypatch.setattr(
+            "turnstone.core.session.fetch_with_ssrf_guard",
+            lambda url, **kw: _fake_response(url, body, "text/html"),
+        )
+        item = s._prepare_open_preview("c1", {"target": "https://user:sekret@acme.com/page"})
+        s._exec_open_preview(item)
+        descriptor, att = s._tool_previews["c1"]
+        assert "sekret" not in descriptor["source"]
+        assert "sekret" not in descriptor["title"]
+        assert b"sekret" not in att.content  # the injected <base href>
+
+    def test_redirect_into_private_space_blocked(self, monkeypatch):
+        s = _make_session()
+
+        # The guarded fetch raises BEFORE requesting a private hop — the
+        # executor's ValueError lane turns that into a tool error.
+        def _blocked(url, **kw):
+            raise ValueError("Blocked: URL resolves to private/internal address (169.254.169.254)")
+
+        monkeypatch.setattr("turnstone.core.session.fetch_with_ssrf_guard", _blocked)
+        item = s._prepare_open_preview("c1", {"target": "https://innocent.example/"})
+        _, msg = s._exec_open_preview(item)
+        assert msg.startswith("Error: fetch failed: Blocked")
+        assert "c1" not in s._tool_previews
+
+    def test_oversized_web_content_errors(self, monkeypatch):
+        s = _make_session()
+        big = b"<html>" + b"x" * (4 * 1024 * 1024 + 16) + b"</html>"
+        monkeypatch.setattr(
+            "turnstone.core.session.fetch_with_ssrf_guard",
+            lambda url, **kw: _fake_response(url, big, "text/html"),
+        )
+        item = s._prepare_open_preview("c1", {"target": "https://example.com/big"})
+        _, msg = s._exec_open_preview(item)
+        assert msg.startswith("Error:")
+        assert "too large" in msg
+
+    def test_url_pdf_over_10mb_previews_to_kind_cap(self, monkeypatch):
+        # Review finding (PR #800): a flat 10 MB URL pre-check rejected PDFs
+        # the 32 MiB pdf kind cap allows — the fetch ceiling must track the
+        # widest kind cap and leave the per-kind caps as the authority.
+        from turnstone.core.preview import PREVIEW_SIZE_CAPS
+
+        s = _make_session()
+        body = b"%PDF-1.7\n" + b"a" * (12 * 1024 * 1024)
+        seen = {}
+
+        def _capture(url, **kw):
+            seen.update(kw)
+            return _fake_response(url, body, "application/pdf")
+
+        monkeypatch.setattr("turnstone.core.session.fetch_with_ssrf_guard", _capture)
+        item = s._prepare_open_preview("c1", {"target": "https://acme.com/report.pdf"})
+        _, msg = s._exec_open_preview(item)
+        assert not msg.startswith("Error:")
+        descriptor, _ = s._tool_previews["c1"]
+        assert descriptor["kind"] == "pdf"
+        assert descriptor["size"] == len(body)
+        assert seen["max_bytes"] == max(PREVIEW_SIZE_CAPS.values())
+
+    def test_path_image(self, tmp_path):
+        s = _make_session()
+        p = tmp_path / "chart.png"
+        p.write_bytes(PNG_1x1)
+        item = s._prepare_open_preview("c1", {"target": str(p)})
+        _, msg = s._exec_open_preview(item)
+        assert not msg.startswith("Error:")
+        descriptor, att = s._tool_previews["c1"]
+        assert descriptor["kind"] == "image"
+        assert descriptor["content_type"] == "image/png"
+        assert descriptor["title"] == "chart.png"
+        assert att.content == PNG_1x1
+
+    def test_preview_blob_id_salted_out_of_upload_namespace(self, tmp_path):
+        import hashlib
+
+        s = _make_session()
+        p = tmp_path / "chart.png"
+        p.write_bytes(PNG_1x1)
+        item = s._prepare_open_preview("c1", {"target": str(p)})
+        s._exec_open_preview(item)
+        _, att = s._tool_previews["c1"]
+        # Uploads are keyed bare sha256(body) and save_attachment freezes
+        # `kind` at first insert — an unsalted preview of identical bytes
+        # would collide with (or pre-empt) a real upload's row.
+        assert att.attachment_id != hashlib.sha256(PNG_1x1).hexdigest()
+        assert att.attachment_id == hashlib.sha256(b"preview:" + PNG_1x1).hexdigest()
+
+    def test_path_csv_is_table(self, tmp_path):
+        s = _make_session()
+        p = tmp_path / "results.csv"
+        p.write_text("name,score\na,1\nb,2\n")
+        item = s._prepare_open_preview("c1", {"target": str(p)})
+        s._exec_open_preview(item)
+        descriptor, _ = s._tool_previews["c1"]
+        assert descriptor["kind"] == "table"
+        assert descriptor["content_type"].startswith("text/csv")
+
+    def test_path_missing_errors(self):
+        s = _make_session()
+        item = s._prepare_open_preview("c1", {"target": "/nonexistent/nowhere.txt"})
+        _, msg = s._exec_open_preview(item)
+        assert msg.startswith("Error: file not found")
+
+    def test_path_binary_unpreviewable(self, tmp_path):
+        s = _make_session()
+        p = tmp_path / "blob.bin"
+        p.write_bytes(b"\x00\x01\x02\x03" * 64)
+        item = s._prepare_open_preview("c1", {"target": str(p)})
+        _, msg = s._exec_open_preview(item)
+        assert "not previewable" in msg
+
+    def test_attachment_target_requires_ws_reference(self, monkeypatch):
+        s = _make_session(ws_id="ws-1")
+        monkeypatch.setattr(
+            "turnstone.core.memory.get_attachment",
+            lambda aid: {"content": b"# doc", "mime_type": "text/markdown", "filename": "d.md"},
+        )
+        monkeypatch.setattr(
+            "turnstone.core.memory.attachment_referenced_in_ws",
+            lambda aid, ws: False,
+        )
+        item = s._prepare_open_preview("c1", {"target": "attachment:deadbeef"})
+        _, msg = s._exec_open_preview(item)
+        assert msg.startswith("Error: attachment not found")
+
+    def test_attachment_target_happy_path(self, monkeypatch):
+        s = _make_session(ws_id="ws-1")
+        monkeypatch.setattr(
+            "turnstone.core.memory.get_attachment",
+            lambda aid: {"content": b"# doc", "mime_type": "text/markdown", "filename": "d.md"},
+        )
+        monkeypatch.setattr(
+            "turnstone.core.memory.attachment_referenced_in_ws",
+            lambda aid, ws: True,
+        )
+        item = s._prepare_open_preview("c1", {"target": "attachment:deadbeef"})
+        _, msg = s._exec_open_preview(item)
+        assert not msg.startswith("Error:")
+        descriptor, _ = s._tool_previews["c1"]
+        assert descriptor["kind"] == "markdown"
+        assert descriptor["title"] == "d.md"
+
+    def test_legacy_charset_table_stored_as_utf8(self, monkeypatch):
+        # A latin-1 CSV attachment previews as a table, and the executor
+        # transcodes it to UTF-8 at store time so "café" round-trips instead of
+        # erroring "not previewable".
+        s = _make_session(ws_id="ws-1")
+        latin1_csv = "name,city\nRené,Montréal\n".encode("iso-8859-1")
+        monkeypatch.setattr(
+            "turnstone.core.memory.get_attachment",
+            lambda aid: {
+                "content": latin1_csv,
+                "mime_type": "text/csv; charset=iso-8859-1",
+                "filename": "people.csv",
+            },
+        )
+        monkeypatch.setattr(
+            "turnstone.core.memory.attachment_referenced_in_ws",
+            lambda aid, ws: True,
+        )
+        item = s._prepare_open_preview("c1", {"target": "attachment:deadbeef"})
+        _, msg = s._exec_open_preview(item)
+        assert not msg.startswith("Error:")
+        descriptor, att = s._tool_previews["c1"]
+        assert descriptor["kind"] == "table"
+        assert descriptor["content_type"].startswith("text/csv")
+        # Stored bytes are valid UTF-8 with the accented characters preserved.
+        assert att.content.decode("utf-8") == "name,city\nRené,Montréal\n"
+
+    def test_title_override_wins(self, tmp_path):
+        s = _make_session()
+        p = tmp_path / "x.csv"
+        p.write_text("a,b\n")
+        item = s._prepare_open_preview("c1", {"target": str(p), "title": "Q3 numbers"})
+        s._exec_open_preview(item)
+        descriptor, _ = s._tool_previews["c1"]
+        assert descriptor["title"] == "Q3 numbers"
+
+
+# ---------------------------------------------------------------------------
+# Trajectory / history / storage seams
+# ---------------------------------------------------------------------------
+
+
+class TestDescriptorSeams:
+    DESCRIPTOR = {
+        "kind": "web",
+        "title": "T",
+        "source": "https://a.io",
+        "attachment_id": "abc",
+        "content_type": "text/html; charset=utf-8",
+        "size": 7,
+    }
+
+    def test_turn_roundtrip(self):
+        turn = turn_from_dict(
+            {
+                "role": "tool",
+                "tool_call_id": "c1",
+                "content": "Preview shown",
+                "_preview": self.DESCRIPTOR,
+            }
+        )
+        assert turn.meta.extra["preview"] == self.DESCRIPTOR
+        out = turn_to_dict(turn)
+        assert out["_preview"] == self.DESCRIPTOR
+
+    def test_history_projection_carries_preview(self):
+        from turnstone.core.history_decoration import project_history_messages
+
+        msgs = [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {"id": "c1", "function": {"name": "open_preview", "arguments": "{}"}}
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "c1",
+                "content": "Preview shown to the user: T (web, 7 bytes)",
+                "_preview": self.DESCRIPTOR,
+            },
+        ]
+        history = project_history_messages(msgs)
+        tool_entries = [h for h in history if h.get("role") == "tool"]
+        assert tool_entries and tool_entries[0]["preview"] == self.DESCRIPTOR
+
+    def test_reconstruct_routes_tool_preview_meta(self):
+        import json
+
+        from turnstone.core.storage._utils import reconstruct_turns
+
+        # Row layout per reconstruct_turns' unpack: (row_id, role, content,
+        # tool_name, tool_call_id, provider_data, tool_calls_json, source,
+        # event_id, is_error, meta).
+        row = (
+            1,
+            "tool",
+            "ok",
+            "open_preview",
+            "c1",
+            None,
+            None,
+            None,
+            7,
+            0,
+            json.dumps({"effect_status": "unknown", "preview": self.DESCRIPTOR}),
+        )
+        turns = reconstruct_turns([row], "ws-1", attachments_by_msg={})
+        assert turns[0].role is Role.TOOL
+        assert turns[0].meta.extra["preview"] == self.DESCRIPTOR
+        assert turns[0].meta.extra["effect_status"] == "unknown"
+
+    def test_reconstruct_skips_preview_blob_refs(self):
+        """A preview blob on a tool row's ref-list must NOT become a content
+        block — it is meta-addressed frontend content, and a content block
+        would be materialized onto the wire on reload."""
+        from turnstone.core.storage._utils import reconstruct_turns
+
+        row = (
+            1,
+            "tool",
+            "ok",
+            "open_preview",
+            "c1",
+            None,
+            None,
+            None,
+            None,
+            0,
+            None,
+        )
+        atts = {
+            1: [
+                {
+                    "attachment_id": "abc",
+                    "kind": "preview",
+                    "filename": "preview-web",
+                    "mime_type": "text/html; charset=utf-8",
+                    "size_bytes": 7,
+                },
+                {
+                    "attachment_id": "img1",
+                    "kind": "image",
+                    "filename": "shot.png",
+                    "mime_type": "image/png",
+                    "size_bytes": 9,
+                },
+            ]
+        }
+        turns = reconstruct_turns([row], "ws-1", attachments_by_msg=atts)
+        kinds = [b.kind for b in turns[0].content if b.__class__.__name__ == "AttachmentRef"]
+        # The vision lane still reconstructs; the preview blob does not.
+        assert kinds == ["image"]
+
+    def test_preview_route_scope_is_read(self):
+        from turnstone.core.auth import required_scope
+
+        assert required_scope("GET", "/v1/api/workstreams/ws1/attachments/abc/preview") == "read"
+        assert (
+            required_scope("GET", "/node/n1/v1/api/workstreams/ws1/attachments/abc/preview")
+            == "read"
+        )
+
+
+# ---------------------------------------------------------------------------
+# fetch_with_ssrf_guard — per-hop redirect screening (core/web.py)
+# ---------------------------------------------------------------------------
+
+
+class _FakeHop:
+    """client.stream() double: a context manager yielding chunked body bytes."""
+
+    def __init__(self, status, headers=None, body=b""):
+        self.status_code = status
+        self.headers = headers or {}
+        self._chunks = body if isinstance(body, list) else [body]
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def iter_bytes(self):
+        yield from self._chunks
+
+
+class _FakeClient:
+    """httpx.Client double: serves a scripted {url: response} table."""
+
+    calls: list[str] = []
+    table: dict[str, _FakeHop] = {}
+
+    def __init__(self, **kwargs):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def stream(self, method, url):
+        _FakeClient.calls.append(url)
+        return _FakeClient.table[url]
+
+
+class TestFetchWithSsrfGuard:
+    def _wire(self, monkeypatch, table):
+        _FakeClient.calls = []
+        _FakeClient.table = table
+        monkeypatch.setattr("turnstone.core.web.httpx.Client", _FakeClient)
+
+    def test_follows_public_redirect_chain(self, monkeypatch):
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        self._wire(
+            monkeypatch,
+            {
+                "https://a.example/": _FakeHop(302, {"location": "https://b.example/x"}),
+                "https://b.example/x": _FakeHop(200, {}, body=b"landed"),
+            },
+        )
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: None)
+        resp = fetch_with_ssrf_guard("https://a.example/", timeout=5)
+        assert resp.status_code == 200
+        assert _FakeClient.calls == ["https://a.example/", "https://b.example/x"]
+
+    def test_private_hop_blocked_before_request(self, monkeypatch):
+        import pytest
+
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        self._wire(
+            monkeypatch,
+            {
+                "https://a.example/": _FakeHop(302, {"location": "http://169.254.169.254/latest"}),
+            },
+        )
+        blocked = {"http://169.254.169.254/latest": "Blocked: private"}
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: blocked.get(url))
+        with pytest.raises(ValueError, match="Blocked: private"):
+            fetch_with_ssrf_guard("https://a.example/", timeout=5)
+        # The load-bearing assertion: the private hop was NEVER requested.
+        assert _FakeClient.calls == ["https://a.example/"]
+
+    def test_relative_location_resolves_against_current(self, monkeypatch):
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        self._wire(
+            monkeypatch,
+            {
+                "https://a.example/start": _FakeHop(301, {"location": "/moved"}),
+                "https://a.example/moved": _FakeHop(200, {}),
+            },
+        )
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: None)
+        resp = fetch_with_ssrf_guard("https://a.example/start", timeout=5)
+        assert resp.status_code == 200
+        # The realized response carries the FINAL hop's URL — open_preview's
+        # descriptor source and stored <base href> both key off it.
+        assert str(resp.url) == "https://a.example/moved"
+
+    def test_redirect_loop_capped(self, monkeypatch):
+        import pytest
+
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        self._wire(
+            monkeypatch,
+            {"https://a.example/": _FakeHop(302, {"location": "https://a.example/"})},
+        )
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: None)
+        with pytest.raises(ValueError, match="redirects"):
+            fetch_with_ssrf_guard("https://a.example/", timeout=5)
+
+    def test_body_over_budget_aborts(self, monkeypatch):
+        import pytest
+
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        self._wire(
+            monkeypatch,
+            {"https://a.example/": _FakeHop(200, {}, body=[b"aaaa", b"bbbb", b"cccc"])},
+        )
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: None)
+        with pytest.raises(ValueError, match="fetch limit"):
+            fetch_with_ssrf_guard("https://a.example/", timeout=5, max_bytes=10)
+
+    def test_redirect_hop_body_never_read(self, monkeypatch):
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        class _BodyBomb(_FakeHop):
+            def iter_bytes(self):
+                raise AssertionError("redirect hop body must not be read")
+
+        self._wire(
+            monkeypatch,
+            {
+                "https://a.example/": _BodyBomb(302, {"location": "https://b.example/x"}),
+                "https://b.example/x": _FakeHop(200, {}, body=b"ok"),
+            },
+        )
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: None)
+        resp = fetch_with_ssrf_guard("https://a.example/", timeout=5)
+        assert resp.status_code == 200
+        assert resp.content == b"ok"
+
+    def test_stale_framing_headers_dropped(self, monkeypatch):
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        self._wire(
+            monkeypatch,
+            {
+                "https://a.example/": _FakeHop(
+                    200,
+                    {
+                        "content-encoding": "gzip",
+                        "content-length": "999",
+                        "content-type": "text/html; charset=utf-8",
+                    },
+                    body=b"<html>hi</html>",
+                )
+            },
+        )
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", lambda url: None)
+        resp = fetch_with_ssrf_guard("https://a.example/", timeout=5)
+        # iter_bytes() hands the guard content-DECODED bytes — a surviving
+        # content-encoding would make .text try to gunzip plain text, and the
+        # upstream content-length no longer describes the body carried.
+        assert "content-encoding" not in resp.headers
+        assert resp.headers.get("content-length") != "999"
+        assert resp.headers.get("content-type") == "text/html; charset=utf-8"
+        assert resp.text == "<html>hi</html>"
+
+
+# ---------------------------------------------------------------------------
+# Cancelled-batch synthesis — a staged preview whose descriptor already
+# reached the frontend must commit, not vanish (session.py review fix)
+# ---------------------------------------------------------------------------
+
+
+class TestCancelledBatchPreservesPreview:
+    def test_synthesize_commits_staged_preview(self, monkeypatch):
+        import json as _json
+
+        from turnstone.core.attachments import Attachment
+        from turnstone.core.trajectory import Turn
+
+        s = _make_session(ws_id="ws-1")
+        descriptor = {
+            "kind": "web",
+            "title": "T",
+            "source": "https://a.io",
+            "attachment_id": "abc",
+            "content_type": "text/html; charset=utf-8",
+            "size": 7,
+        }
+        att = Attachment(
+            attachment_id="abc",
+            filename="preview-web",
+            mime_type="text/html; charset=utf-8",
+            kind="preview",
+            content=b"<p>x</p>",
+        )
+        s._tool_previews["c1"] = (descriptor, att)
+        # Assistant turn with one UNANSWERED call — the cancel shape.
+        s.messages.append(
+            turn_from_dict(
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "id": "c1",
+                            "type": "function",
+                            "function": {"name": "open_preview", "arguments": "{}"},
+                        }
+                    ],
+                }
+            )
+        )
+        s._msg_tokens.append(1)
+
+        saved = {}
+        monkeypatch.setattr(
+            "turnstone.core.session.save_message",
+            lambda ws, role, content, name, **kw: (
+                saved.update({"meta": kw.get("meta"), "row": 42}) or 42
+            ),
+        )
+        persisted = {}
+        monkeypatch.setattr(
+            ChatSession,
+            "_persist_attachment_refs",
+            lambda self, row_id, atts, origin="upload": persisted.update(
+                {"row": row_id, "ids": [a.attachment_id for a in atts], "origin": origin}
+            ),
+        )
+
+        s._synthesize_cancelled_results("Cancelled by user.")
+
+        # Side channel drained; descriptor + blob committed with the turn.
+        assert "c1" not in s._tool_previews
+        meta = _json.loads(saved["meta"])
+        assert meta["preview"] == descriptor
+        assert meta["effect_status"] == "unknown"
+        assert persisted == {"row": 42, "ids": ["abc"], "origin": "tool"}
+        # The in-memory synthesized turn carries the descriptor too.
+        tool_turns = [t for t in s.messages if isinstance(t, Turn) and t.role is Role.TOOL]
+        assert tool_turns and tool_turns[-1].meta.extra.get("preview") == descriptor
+
+
+# ---------------------------------------------------------------------------
+# tools.allow_private_network — the self-hoster opt-in (admin Settings → Tools)
+# ---------------------------------------------------------------------------
+
+
+class TestAllowPrivateNetwork:
+    def test_screen_public_url_passes(self):
+        from turnstone.core.session import _screen_tool_url
+
+        err, private = _screen_tool_url("https://example.com/x", False)
+        assert err is None and private is False
+
+    def test_screen_private_blocked_with_discoverable_hint(self):
+        from turnstone.core.session import _screen_tool_url
+
+        err, private = _screen_tool_url("http://10.0.0.7/grafana", False)
+        assert err is not None and private is False
+        # The refusal teaches the knob (mirrors the oidc opt-in hint pattern).
+        assert "tools.allow_private_network" in err
+        assert "Settings" in err
+
+    def test_screen_private_allowed_when_opted_in(self):
+        from turnstone.core.session import _screen_tool_url
+
+        err, private = _screen_tool_url("http://10.0.0.7/grafana", True)
+        assert err is None and private is True
+
+    def test_screen_invalid_url_never_hints(self):
+        from turnstone.core.session import _screen_tool_url
+
+        err, private = _screen_tool_url("http://", True)
+        assert err is not None and private is False
+        assert "allow_private_network" not in err
+
+    def test_bare_session_defaults_strict(self):
+        # No ConfigStore (CLI / eval surface) → no admin opted in → strict.
+        s = _make_session()
+        assert s._allow_private_network() is False
+
+    def test_prepare_web_fetch_private_opted_in(self, monkeypatch):
+        s = _make_session()
+        monkeypatch.setattr(ChatSession, "_allow_private_network", lambda self: True)
+        item = s._prepare_web_fetch(
+            "c1", {"url": "http://192.168.1.50:3000/d/home", "question": "what is shown?"}
+        )
+        assert "error" not in item
+        assert item["needs_approval"] is True  # the human gate stays
+        assert "(private network)" in item["header"]
+        assert item["allow_private_origin"] is True
+
+    def test_prepare_open_preview_private_opted_in(self, monkeypatch):
+        s = _make_session()
+        monkeypatch.setattr(ChatSession, "_allow_private_network", lambda self: True)
+        item = s._prepare_open_preview("c1", {"target": "http://192.168.1.50:3000/d/home"})
+        assert "error" not in item
+        assert item["needs_approval"] is True
+        assert "(private network)" in item["header"]
+        assert item["allow_private_origin"] is True
+
+    def test_prepare_private_still_blocked_by_default(self, monkeypatch):
+        s = _make_session()
+        monkeypatch.setattr(ChatSession, "_allow_private_network", lambda self: False)
+        for prepare, args in (
+            (s._prepare_web_fetch, {"url": "http://10.0.0.7/x", "question": "q"}),
+            (s._prepare_open_preview, {"target": "http://10.0.0.7/x"}),
+        ):
+            item = prepare("c1", args)
+            assert "error" in item
+            assert "tools.allow_private_network" in item["error"]
+
+    def test_executor_passes_private_origin_to_guard(self, monkeypatch):
+        s = _make_session()
+        monkeypatch.setattr(ChatSession, "_allow_private_network", lambda self: True)
+        seen = {}
+
+        def _capture(url, **kw):
+            seen.update(kw, url=url)
+            return _fake_response(url, b"<html><head></head><body>x</body></html>", "text/html")
+
+        monkeypatch.setattr("turnstone.core.session.fetch_with_ssrf_guard", _capture)
+        item = s._prepare_open_preview("c1", {"target": "http://10.0.0.7/status"})
+        s._exec_open_preview(item)
+        assert seen["allow_private_origin"] is True
+
+    def test_guard_skips_hop_screen_for_private_origin(self, monkeypatch):
+        from turnstone.core.web import fetch_with_ssrf_guard
+
+        _FakeClient.calls = []
+        _FakeClient.table = {
+            "http://10.0.0.7/a": _FakeHop(302, {"location": "http://10.0.0.8/b"}),
+            "http://10.0.0.8/b": _FakeHop(200, {}),
+        }
+        monkeypatch.setattr("turnstone.core.web.httpx.Client", _FakeClient)
+
+        def _explode(url):
+            raise AssertionError("hop screening must be skipped for a private origin")
+
+        monkeypatch.setattr("turnstone.core.web.check_ssrf", _explode)
+        resp = fetch_with_ssrf_guard("http://10.0.0.7/a", timeout=5, allow_private_origin=True)
+        assert resp.status_code == 200
+        assert _FakeClient.calls == ["http://10.0.0.7/a", "http://10.0.0.8/b"]
+
+    def test_registry_entry_shape(self):
+        from turnstone.core.settings_registry import SETTINGS
+
+        d = SETTINGS["tools.allow_private_network"]
+        assert d.type == "bool"
+        assert d.default is False
+        assert d.section == "tools"
+        assert d.help  # the admin form renders this — it must explain the caveat

tests/test_preview.py

@@ -0,0 +1,305 @@
+"""Unit tests for the preview-content policy module (``turnstone/core/preview.py``).
+
+Pure-function coverage: kind resolution precedence (magic bytes → MIME hint →
+extension → UTF-8 fallback), the explicit ``kind`` override lanes, base-href
+injection, title extraction, and the per-MIME serving headers the route
+attaches.  The tool executor and the HTTP route are covered separately
+(``test_open_preview_tool.py`` / ``test_server_attachments_endpoints.py``).
+"""
+
+from __future__ import annotations
+
+from turnstone.core.attachments import IMAGE_SIZE_CAP, PDF_SIZE_CAP, TEXT_DOC_SIZE_CAP
+from turnstone.core.preview import (
+    PREVIEW_BLOB_KIND,
+    PREVIEW_KINDS,
+    PREVIEW_SERVE_MIMES,
+    PREVIEW_SIZE_CAPS,
+    build_preview_descriptor,
+    inject_base_href,
+    page_title,
+    preview_response_headers,
+    resolve_preview_kind,
+    transcode_text,
+)
+
+PNG_1x1 = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+    b"\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\rIDATx\x9cc\xfc\xcf"
+    b"\xc0\xc0\xc0\x00\x00\x00\x05\x00\x01\xa5\xf6E@\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+PDF_MIN = b"%PDF-1.4 fake body"
+HTML_DOC = b"<html><head><title>Acme Pricing</title></head><body>hi</body></html>"
+
+
+class TestResolvePreviewKind:
+    def test_magic_bytes_win_over_everything(self):
+        # A PNG claiming to be CSV by both MIME and extension is an image.
+        assert resolve_preview_kind("text/csv", "data.csv", PNG_1x1) == ("image", "image/png")
+        assert resolve_preview_kind("text/plain", "doc.txt", PDF_MIN) == (
+            "pdf",
+            "application/pdf",
+        )
+
+    def test_mime_hint_html(self):
+        kind, mime = resolve_preview_kind("text/html; charset=iso-8859-1", "page", HTML_DOC)
+        assert kind == "web"
+        assert mime == "text/html; charset=utf-8"
+
+    def test_mime_hint_families(self):
+        assert resolve_preview_kind("text/csv", "x", b"a,b\n1,2")[0] == "table"
+        assert resolve_preview_kind("application/json", "x", b"[]") == (
+            "table",
+            "application/json",
+        )
+        assert resolve_preview_kind("text/markdown", "x", b"# hi")[0] == "markdown"
+        assert resolve_preview_kind("text/x-log", "x", b"line")[0] == "text"
+
+    def test_extension_fallback_when_no_mime(self):
+        assert resolve_preview_kind("", "report.html", HTML_DOC)[0] == "web"
+        assert resolve_preview_kind("", "data.tsv", b"a\tb")[0] == "table"
+        assert resolve_preview_kind("", "notes.md", b"# t")[0] == "markdown"
+        # URL tails strip query/fragment before the extension check.
+        assert resolve_preview_kind("", "https://x.io/a.csv?dl=1#f", b"a,b")[0] == "table"
+
+    def test_utf8_text_fallback(self):
+        assert resolve_preview_kind("", "LICENSE", b"MIT License") == (
+            "text",
+            "text/plain; charset=utf-8",
+        )
+
+    def test_binary_is_not_previewable(self):
+        assert resolve_preview_kind("", "blob.bin", b"\x00\x01\x02\x03" * 8) is None
+        # Text-DECLARED binary is misdeclared, not previewable text.
+        assert resolve_preview_kind("text/plain", "x", b"\x00\xff" * 8) is None
+        assert resolve_preview_kind("application/octet-stream", "x", b"\x00" * 32) is None
+
+    def test_override_validates_bytes(self):
+        # image override on non-image bytes fails rather than mislabeling.
+        assert resolve_preview_kind("", "x", b"not an image", "image") is None
+        assert resolve_preview_kind("", "x", PNG_1x1, "image") == ("image", "image/png")
+        assert resolve_preview_kind("", "x", b"not a pdf", "pdf") is None
+        # Text-family override on binary bytes fails.
+        assert resolve_preview_kind("", "x", b"\x00\x01", "text") is None
+
+    def test_override_forces_view(self):
+        # kind='text' on an HTML doc = view source.
+        assert resolve_preview_kind("text/html", "p.html", HTML_DOC, "text")[0] == "text"
+        # kind='table' keeps the real payload type for the client parser.
+        assert resolve_preview_kind("application/json", "d", b"[1]", "table") == (
+            "table",
+            "application/json",
+        )
+        assert resolve_preview_kind("", "d.tsv", b"a\tb", "table") == (
+            "table",
+            "text/tab-separated-values; charset=utf-8",
+        )
+        assert resolve_preview_kind("", "d.txt", b"a,b", "table") == (
+            "table",
+            "text/csv; charset=utf-8",
+        )
+
+    def test_unknown_override_rejected(self):
+        assert resolve_preview_kind("text/plain", "x", b"hi", "hologram") is None
+
+
+class TestHtmlHelpers:
+    def test_base_href_inserted_after_head(self):
+        out = inject_base_href("<html><head><meta x></head></html>", "https://a.io/p/q")
+        assert out.startswith('<html><head><base href="https://a.io/p/q">')
+
+    def test_base_href_prepended_without_head(self):
+        out = inject_base_href("<p>bare</p>", "https://a.io/")
+        assert out.startswith('<base href="https://a.io/">')
+
+    def test_existing_base_untouched(self):
+        doc = '<head><base href="https://original/"></head>'
+        assert inject_base_href(doc, "https://other/") == doc
+
+    def test_base_href_attribute_escaped(self):
+        out = inject_base_href("<head></head>", 'https://a.io/"><script>x</script>')
+        assert "<script>" not in out
+        assert "&quot;&gt;&lt;script&gt;" in out
+
+    def test_page_title_extraction(self):
+        assert page_title(HTML_DOC.decode()) == "Acme Pricing"
+        assert page_title("<title>a &amp; b\n   c</title>") == "a & b c"
+        assert page_title("<p>no title</p>") is None
+        assert page_title("<title></title>") is None
+
+
+_LOCKED_HTML_CSP = (
+    "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:"
+)
+
+
+class TestServingPolicy:
+    def test_html_default_locks_out_remote_assets(self):
+        # Default (no opt-in): sandboxed AND off the network — inline styling +
+        # data-URI images render, but the page can fetch nothing, so previewing
+        # never discloses the viewer to the origin site.
+        h = preview_response_headers("text/html", "page.html")
+        assert h["Content-Security-Policy"] == _LOCKED_HTML_CSP
+        assert h["X-Content-Type-Options"] == "nosniff"
+        assert h["Cache-Control"] == "private, no-store"
+        assert h["Content-Disposition"].startswith("inline;")
+
+    def test_html_assets_opt_in_gets_bare_sandbox_csp(self):
+        # allow_remote_assets=True drops back to the bare sandbox so the page's
+        # own images / CSS load.
+        h = preview_response_headers("text/html", "page.html", allow_remote_assets=True)
+        assert h["Content-Security-Policy"] == "sandbox"
+        assert h["X-Content-Type-Options"] == "nosniff"
+
+    def test_assets_flag_does_not_touch_non_html_kinds(self):
+        for mime in ("application/pdf", "image/png", "text/csv", "text/plain"):
+            assert preview_response_headers(
+                mime, "f", allow_remote_assets=True
+            ) == preview_response_headers(mime, "f")
+
+    def test_pdf_gets_no_csp(self):
+        h = preview_response_headers("application/pdf", "doc.pdf")
+        assert "Content-Security-Policy" not in h
+        assert h["X-Content-Type-Options"] == "nosniff"
+
+    def test_other_kinds_keep_full_csp(self):
+        for mime in ("image/png", "text/csv", "text/plain"):
+            h = preview_response_headers(mime, "f")
+            assert h["Content-Security-Policy"] == "default-src 'none'; sandbox"
+
+    def test_filename_header_injection_stripped(self):
+        h = preview_response_headers("text/plain", 'a"\r\nX-Evil: 1')
+        assert "\r" not in h["Content-Disposition"]
+        assert "\n" not in h["Content-Disposition"]
+        assert '"' not in h["Content-Disposition"].split("filename=")[1].strip('"')
+
+    def test_serve_allowlist_covers_every_stored_kind(self):
+        for mime in (
+            "text/html",
+            "application/pdf",
+            "image/png",
+            "image/webp",
+            "text/csv",
+            "text/tab-separated-values",
+            "application/json",
+            "text/markdown",
+            "text/plain",
+        ):
+            assert mime in PREVIEW_SERVE_MIMES
+
+    def test_caps_reuse_attachment_constants(self):
+        assert PREVIEW_SIZE_CAPS["image"] == IMAGE_SIZE_CAP
+        assert PREVIEW_SIZE_CAPS["pdf"] == PDF_SIZE_CAP
+        assert PREVIEW_SIZE_CAPS["text"] == TEXT_DOC_SIZE_CAP
+        assert set(PREVIEW_SIZE_CAPS) == set(PREVIEW_KINDS)
+
+    def test_blob_kind_is_outside_model_vocabulary(self):
+        assert PREVIEW_BLOB_KIND not in ("image", "text", "pdf", "audio")
+
+    def test_descriptor_shape(self):
+        d = build_preview_descriptor(
+            kind="web",
+            title="T",
+            source="https://a.io",
+            attachment_id="abc",
+            content_type="text/html; charset=utf-8",
+            size=7,
+        )
+        assert d == {
+            "kind": "web",
+            "title": "T",
+            "source": "https://a.io",
+            "attachment_id": "abc",
+            "content_type": "text/html; charset=utf-8",
+            "size": 7,
+        }
+
+
+class TestReviewHardening:
+    """Pins for the review-round fixes (2026-07-07)."""
+
+    def test_filename_folds_to_latin1_safe_ascii(self):
+        # Starlette encodes header values latin-1; em dashes / CJK titles
+        # must fold, not 500 the serving route.
+        h = preview_response_headers("text/html", "Docs — v1.7 日本語.html")
+        h["Content-Disposition"].encode("latin-1")  # must not raise
+        h2 = preview_response_headers("text/plain", "——")
+        h2["Content-Disposition"].encode("latin-1")
+        assert (
+            'filename="preview"' in h2["Content-Disposition"]
+            or "filename=" in h2["Content-Disposition"]
+        )
+
+    def test_base_href_never_precedes_doctype(self):
+        doc = "<!DOCTYPE html><body>no head</body>"
+        out = inject_base_href(doc, "https://a.io/")
+        assert out.startswith("<!DOCTYPE html>")
+        assert '<base href="https://a.io/">' in out
+        # <html> without <head> also keeps document order.
+        doc2 = "<!doctype html><html lang=en><body>x</body></html>"
+        out2 = inject_base_href(doc2, "https://a.io/")
+        assert out2.startswith("<!doctype html><html lang=en>")
+        assert out2.index("<base") > out2.index("<html")
+
+    def test_legacy_charset_web_pages_stay_previewable(self):
+        # windows-1252 / iso-8859-1 bytes are not UTF-8; web kind must not
+        # reject them (the executor transcodes at store time).
+        latin1_html = "<html><body>café</body></html>".encode("latin-1")
+        assert resolve_preview_kind("text/html; charset=iso-8859-1", "p", latin1_html) == (
+            "web",
+            "text/html; charset=utf-8",
+        )
+        # Extension lane and explicit override agree.
+        assert resolve_preview_kind("", "page.html", latin1_html)[0] == "web"
+        assert resolve_preview_kind("", "page.bin", latin1_html, "web")[0] == "web"
+        # Non-web text kinds now transcode too — a declared text/csv MIME on
+        # legacy-charset bytes is previewable (was strict-UTF-8-only before).
+        assert resolve_preview_kind("text/csv", "d.csv", latin1_html) == (
+            "table",
+            "text/csv; charset=utf-8",
+        )
+        # …but binary declared as text (a NUL byte) is still rejected.
+        assert resolve_preview_kind("text/csv", "d.csv", b"\x00\x01\x02" * 8) is None
+
+
+class TestLegacyCharsetText:
+    """Text-family kinds transcode legacy charsets at store time; only the
+    undeclared fallback lane stays strict UTF-8 (2026-07-07 follow-up)."""
+
+    def test_declared_latin1_csv_is_a_table(self):
+        latin1_csv = "name,city\nRené,Montréal\n".encode("iso-8859-1")
+        # MIME hint carrying the charset.
+        assert resolve_preview_kind("text/csv; charset=iso-8859-1", "d", latin1_csv) == (
+            "table",
+            "text/csv; charset=utf-8",
+        )
+        # Extension lane and explicit override agree — all "declared text".
+        assert resolve_preview_kind("", "data.csv", latin1_csv)[0] == "table"
+        assert resolve_preview_kind("", "data.bin", latin1_csv, "table")[0] == "table"
+
+    def test_declared_text_nul_byte_still_binary(self):
+        # The ladder never fails, so the NUL check is the only binary gate left
+        # for declared text — it must hold in every declared lane.
+        nul = b"a,b\n1,\x00\n"
+        assert resolve_preview_kind("text/csv", "d.csv", nul) is None
+        assert resolve_preview_kind("", "d.csv", nul) is None
+        assert resolve_preview_kind("", "d", nul, "table") is None
+
+    def test_undeclared_non_utf8_still_rejected(self):
+        # No MIME hint, no text-family extension, no override: the bare
+        # fallback lane stays strict UTF-8 — cp1252+replace would otherwise
+        # classify arbitrary binary as text.
+        assert resolve_preview_kind("", "mystery", b"caf\xe9 nonsense \xff\xfe") is None
+
+    def test_transcode_ladder_rungs(self):
+        # (a) charset= parameter honored.
+        assert transcode_text("café".encode("iso-8859-1"), "text/csv; charset=iso-8859-1") == "café"
+        # (b) UTF-8 when the charset is absent / unknown.
+        assert transcode_text("héllo".encode(), "text/plain") == "héllo"
+        assert transcode_text("héllo".encode(), "text/plain; charset=made-up") == "héllo"
+        # (c) cp1252 fallback rung: smart quotes are invalid UTF-8 (the shape a
+        # legacy .txt with no charset takes — empty mime hint), decoded via the
+        # last rung rather than erroring.
+        smart = b"he said \x93hi\x94"
+        out = transcode_text(smart, "")
+        assert "“" in out and "”" in out

tests/test_preview_js.py

@@ -0,0 +1,214 @@
+"""Static guards for the preview pane frontend (shared_static/preview.js and
+its wiring through conversation.js / interactive.js / shell.js).
+
+Same posture as ``test_shell_js.py``: Python-side string-presence assertions
+that catch the silent one-line regression (a renamed export, a dropped
+sandbox attribute, a de-registered pane type).  Parse + sink + var guards for
+``preview.js`` itself live in ``test_shell_js.py``'s bundle sweeps.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parent.parent
+_SHARED = _ROOT / "turnstone/shared_static"
+_PANE_JS = _SHARED / "pane.js"
+_PREVIEW_JS = _SHARED / "preview.js"
+_CONVERSATION_JS = _SHARED / "conversation.js"
+_INTERACTIVE_JS = _SHARED / "interactive.js"
+_SHELL_JS = _SHARED / "shell.js"
+_PREVIEW_CSS = _SHARED / "preview.css"
+_UI_INDEX = _ROOT / "turnstone/ui/static/index.html"
+_CONSOLE_INDEX = _ROOT / "turnstone/console/static/index.html"
+
+
+def _read(p: Path) -> str:
+    return p.read_text(encoding="utf-8")
+
+
+class TestPreviewPaneModule:
+    def test_factory_exported(self) -> None:
+        assert "export function createPreviewPane" in _read(_PREVIEW_JS)
+
+    def test_web_iframe_is_fully_sandboxed(self) -> None:
+        """The web renderer must keep the empty-sandbox attribute — every
+        capability (scripts, same-origin, forms, popups) stays off.  Dropping
+        or loosening it turns fetched pages into live documents."""
+        body = _read(_PREVIEW_JS)
+        assert 'frame.setAttribute("sandbox", "")' in body
+        assert 'frame.setAttribute("referrerpolicy", "no-referrer")' in body
+
+    def test_pdf_iframe_is_not_sandboxed(self) -> None:
+        """Deliberate asymmetry: Chromium's PDF viewer refuses to paint in a
+        sandboxed context.  The renderer comment carries the rationale; this
+        pins that renderPdf never gained a sandbox attribute by copy-paste."""
+        body = _read(_PREVIEW_JS)
+        pdf_fn = body.split("const renderPdf")[1].split("const renderImage")[0]
+        assert "sandbox" not in pdf_fn or "No sandbox attribute" in pdf_fn
+
+    def test_content_loads_through_authfetch_probe(self) -> None:
+        """src-loaded kinds preflight with a probe request (authFetch of
+        ?probe=1), NOT a HEAD.  The console reverse proxy forwards a HEAD as a
+        full GET, so a real HEAD would drag the whole blob across the hop just
+        to discard it; the probe still surfaces the persist race + auth
+        failures as a typed error card and rides the 401-refresh retry a bare
+        iframe/img src can't."""
+        body = _read(_PREVIEW_JS)
+        assert "authFetch(probeUrl)" in body
+        assert "probe=1" in body
+        # The old full-GET HEAD preflight is gone.
+        assert 'method: "HEAD"' not in body
+
+    def test_markdown_uses_the_sanctioned_html_lane(self) -> None:
+        body = _read(_PREVIEW_JS)
+        assert "setSafeHtml(doc, renderMarkdown(text))" in body
+
+    def test_markdown_runs_vendor_post_pass(self) -> None:
+        """The pane runs renderer.js's post-render pass (hljs token coloring +
+        mermaid) like the conversation pane — dropping it silently regresses
+        code highlighting and diagram rendering in previews."""
+        body = _read(_PREVIEW_JS)
+        assert "postRenderMarkdown(" in body
+
+    def test_remote_assets_toggle_is_default_off(self) -> None:
+        """The remote-assets opt-in defaults OFF: a previewed page must not
+        contact its origin site until the user asks.  Pins the label / tooltip
+        copy and the sticky-boolean initializer."""
+        body = _read(_PREVIEW_JS)
+        assert "Load remote images & styles" in body
+        assert "Off keeps this preview from contacting the site" in body
+        assert "pane._assetsOn = false" in body
+
+    def test_assets_flag_only_rides_behind_toggle(self) -> None:
+        """assets=1 reaches the URL only when the per-pane toggle is on."""
+        body = _read(_PREVIEW_JS)
+        assert "assets=1" in body
+        assert "pane._assetsOn" in body
+
+    def test_history_is_bounded(self) -> None:
+        assert "HISTORY_CAP" in _read(_PREVIEW_JS)
+
+    def test_table_renderer_caps_rows(self) -> None:
+        assert "TABLE_ROW_CAP" in _read(_PREVIEW_JS)
+
+    def test_url_builder_encodes_path_parts(self) -> None:
+        body = _read(_PREVIEW_JS)
+        assert "encodeURIComponent(ws)" in body
+        assert 'encodeURIComponent(descriptor.attachment_id || "")' in body
+
+
+class TestTranscriptChip:
+    def test_chip_builder_exported(self) -> None:
+        assert "export function buildPreviewChip" in _read(_CONVERSATION_JS)
+
+    def test_live_path_gates_auto_open_on_focus(self) -> None:
+        """A backgrounded session must not commandeer the split — the live
+        path auto-opens only while the originating pane is focused; the chip
+        is the deliberate reopen everywhere else."""
+        body = _read(_INTERACTIVE_JS)
+        assert "if (this._host.isFocused(this)) this._host.onPreview(preview);" in body
+
+    def test_replay_path_renders_chip_without_auto_open(self) -> None:
+        body = _read(_INTERACTIVE_JS)
+        # The replay branch builds the chip…
+        assert "buildPreviewChip(msg.preview" in body
+        # …and the auto-open call appears exactly once (the live path).
+        assert body.count("this._host.onPreview(preview)") == 1
+
+    def test_tool_result_event_passes_preview(self) -> None:
+        assert "evt.preview," in _read(_INTERACTIVE_JS)
+
+    def test_host_bridge_carries_transport_ctx(self) -> None:
+        """The preview pane fetches blobs from the ORIGINATING workstream
+        through the same node proxy — the bridge must pass both base and
+        wsId, not just the descriptor."""
+        body = _read(_INTERACTIVE_JS)
+        assert "window.TS_SHELL.openPreview(descriptor, { base: base, wsId: wsId })" in body
+
+
+class TestShellWiring:
+    def test_pane_type_registered(self) -> None:
+        body = _read(_SHELL_JS)
+        assert 'pm.registerType("preview"' in body
+        assert "createPreviewPane" in body
+
+    def test_opens_beside_the_conversation(self) -> None:
+        """openPaneBeside is the load-bearing gesture — the preview coexists
+        with the conversation that spawned it instead of replacing it."""
+        body = _read(_SHELL_JS)
+        assert 'pm.openPaneBeside("preview")' in body
+
+    def test_seam_exported_on_ts_shell(self) -> None:
+        assert "openPreview," in _read(_SHELL_JS)
+
+
+class TestStylesheets:
+    def test_both_surfaces_link_preview_css(self) -> None:
+        for page in (_UI_INDEX, _CONSOLE_INDEX):
+            assert "/shared/preview.css" in _read(page), page.name
+
+    def test_stylesheet_uses_ds_tokens_not_legacy_vars(self) -> None:
+        """conv-* card rule: DS tokens only — chat.css legacy vars
+        (--green/--red/--fg) must not creep into the new sheet."""
+        body = _read(_PREVIEW_CSS)
+        assert "var(--ink-" in body
+        assert "var(--hair)" in body
+        for legacy in ("var(--green)", "var(--red)", "var(--fg)"):
+            assert legacy not in body
+
+
+class TestEphemeralDismiss:
+    """The preview is an ephemeral pane: dismissing its split cell CLOSES it
+    (tab and content gone) instead of parking an orphan tab whose only reopen
+    is the transcript chip.  Regression guard for the pane/tab desync."""
+
+    def test_preview_pane_is_ephemeral(self) -> None:
+        """createPreviewPane must flag the pane ephemeral — the whole fix keys
+        off this bit."""
+        body = _read(_PREVIEW_JS)
+        assert "ephemeral: true" in body, "the preview pane must declare itself ephemeral"
+
+    def test_shellpane_carries_the_ephemeral_flag(self) -> None:
+        body = _read(_PANE_JS)
+        assert "this.ephemeral = opts.ephemeral || false;" in body, (
+            "ShellPane must accept and default the ephemeral flag"
+        )
+
+    def test_cell_chip_closes_ephemeral_pane_outright(self) -> None:
+        """In a split the ✕ chip normally HIDES the cell (closeCell); for an
+        ephemeral pane it must fall through to close() — the `!pane.ephemeral`
+        guard is what routes it there.  Pin BOTH the guard and where the
+        skipped case lands (the else), or gutting the else regresses the fix
+        while the guard string survives verbatim."""
+        body = _read(_PANE_JS)
+        assert "if (this._layout && this._leafFor(pane.id) && !pane.ephemeral)" in body, (
+            "the cell chip must skip closeCell for an ephemeral pane"
+        )
+        assert "else this.close(pane.id);" in body, (
+            "the skipped (ephemeral / single-pane) case must land on close()"
+        )
+
+    def test_cell_chip_signals_destruction_for_ephemeral(self) -> None:
+        """The glyph/label must not lie: an ephemeral pane's split chip reads
+        as a destructive close (✕ + danger hover + 'Close pane'), never the
+        reversible '− / Hide from split'."""
+        body = _read(_PANE_JS)
+        assert "const destroys = !multi || pane.ephemeral;" in body, (
+            "chip mode must treat ephemeral panes as destructive even in a split"
+        )
+
+    def test_unsplit_closes_ephemeral_non_survivors(self) -> None:
+        """Collapsing the split from the OTHER pane must not orphan the preview
+        either — unsplit closes ephemeral panes it isn't keeping."""
+        body = _read(_PANE_JS)
+        assert "const keep = this._activeId;" in body, (
+            "the unsplit survivor must be the FOCUSED pane — the filter's "
+            "`id !== keep` guard is only correct if keep is _activeId"
+        )
+        assert "for (const id of doomed) this.close(id);" in body, (
+            "unsplit must destroy ephemeral panes it does not keep"
+        )
+        assert "return id !== keep && p && p.ephemeral;" in body, (
+            "unsplit must spare the focused survivor and non-ephemeral panes"
+        )

tests/test_providers.py

@@ -2212,6 +2212,40 @@ class TestOpenAIParameterGating:
         assert "temperature" not in kwargs
         assert kwargs["reasoning_effort"] == "medium"  # fell back from unsupported "low"
 
+    def test_gpt56_sol_max_effort_and_temperature(self) -> None:
+        """GPT-5.6 (Sol / bare alias): 1M context + tool search; accepts
+        the NEW "max" reasoning effort verbatim (first commercial OpenAI
+        model to use it); temperature only at reasoning_effort="none"."""
+        caps = lookup_openai_capabilities("gpt-5.6")
+        assert caps.context_window == 1050000
+        assert caps.supports_tool_search is True
+        assert caps.supports_vision is True
+        assert "max" in caps.reasoning_effort_values
+        kwargs: dict[str, Any] = {}
+        apply_temperature_and_effort(kwargs, caps, temperature=0.7, reasoning_effort="max")
+        assert "temperature" not in kwargs
+        assert kwargs["reasoning_effort"] == "max"
+        none_kwargs: dict[str, Any] = {}
+        apply_temperature_and_effort(none_kwargs, caps, temperature=0.7, reasoning_effort="none")
+        assert none_kwargs["temperature"] == 0.7
+        assert none_kwargs["reasoning_effort"] == "none"
+
+    def test_gpt56_sol_id_resolves_by_prefix(self) -> None:
+        """The explicit "gpt-5.6-sol" id and dated Sol snapshots inherit
+        the Sol/alias row (incl. "max") by longest-prefix match."""
+        assert "max" in lookup_openai_capabilities("gpt-5.6-sol").reasoning_effort_values
+        assert "max" in lookup_openai_capabilities("gpt-5.6-2026-07-09").reasoning_effort_values
+
+    def test_gpt56_terra_luna_max_snaps_to_xhigh_ceiling(self) -> None:
+        """GPT-5.6 Terra and Luna have no "max" (Sol-only); the knob's "max"
+        snaps DOWN to the declared "xhigh" ceiling rather than being dropped."""
+        for tier in ("gpt-5.6-terra", "gpt-5.6-luna"):
+            caps = lookup_openai_capabilities(tier)
+            assert "max" not in caps.reasoning_effort_values, tier
+            kwargs: dict[str, Any] = {}
+            apply_temperature_and_effort(kwargs, caps, temperature=0.7, reasoning_effort="max")
+            assert kwargs["reasoning_effort"] == "xhigh", tier
+
 
 class TestAnthropicOrphanedToolUse:
     """Verify _convert_messages synthesizes tool_results for orphaned tool_use."""
@@ -3919,6 +3953,10 @@ class TestOpenAIPromptCaching:
             "gpt-5.4-pro",
             "gpt-5.5",
             "gpt-5.5-pro",
+            "gpt-5.6",
+            "gpt-5.6-sol",
+            "gpt-5.6-terra",
+            "gpt-5.6-luna",
             "gpt-5-mini",
             "gpt-5-pro",
         ):
@@ -4316,6 +4354,104 @@ class TestResponsesParamBuilding:
         )
         assert kwargs["store"] is False
 
+    def _build(self, caps: ModelCapabilities, reasoning_effort: str = "medium") -> dict[str, Any]:
+        return self.provider._build_kwargs(
+            model="gpt-5.6-sol",
+            messages=[{"role": "user", "content": "Hi"}],
+            tools=None,
+            max_tokens=4096,
+            temperature=0.5,
+            reasoning_effort=reasoning_effort,
+            deferred_names=None,
+            capabilities=caps,
+        )
+
+    def test_verbosity_emitted_under_text_when_supported(self) -> None:
+        """Operator-declared verbosity nests under text.verbosity (never
+        top-level, which 400s on the Responses API)."""
+        kwargs = self._build(ModelCapabilities(supports_verbosity=True, verbosity="low"))
+        assert kwargs["text"] == {"verbosity": "low"}
+
+    def test_verbosity_omitted_when_unsupported(self) -> None:
+        """A verbosity value on a model that doesn't support it is dropped."""
+        kwargs = self._build(ModelCapabilities(supports_verbosity=False, verbosity="low"))
+        assert "text" not in kwargs
+
+    def test_verbosity_omitted_when_value_empty(self) -> None:
+        """Supported but unset (the default) → nothing sent, server default."""
+        kwargs = self._build(ModelCapabilities(supports_verbosity=True, verbosity=""))
+        assert "text" not in kwargs
+
+    def test_pro_mode_folds_into_reasoning(self) -> None:
+        """reasoning.mode='pro' rides alongside the effort in one dict."""
+        caps = ModelCapabilities(
+            supports_pro_mode=True,
+            reasoning_mode="pro",
+            reasoning_effort_values=("low", "medium", "high"),
+        )
+        kwargs = self._build(caps, reasoning_effort="high")
+        assert kwargs["reasoning"] == {"effort": "high", "mode": "pro"}
+
+    def test_pro_mode_rejected_when_unsupported(self) -> None:
+        """A pro reasoning_mode on Terra/Luna (supports_pro_mode False) is
+        dropped — effort still rides, mode does not."""
+        caps = ModelCapabilities(
+            supports_pro_mode=False,
+            reasoning_mode="pro",
+            reasoning_effort_values=("low", "medium", "high"),
+        )
+        kwargs = self._build(caps, reasoning_effort="high")
+        assert kwargs["reasoning"] == {"effort": "high"}
+
+    def test_pro_mode_without_effort_sends_mode_only(self) -> None:
+        """No declared effort (param omitted) but pro mode set → the
+        reasoning dict carries mode alone (effort defaults server-side)."""
+        caps = ModelCapabilities(supports_pro_mode=True, reasoning_mode="pro")
+        kwargs = self._build(caps, reasoning_effort="medium")
+        assert kwargs["reasoning"] == {"mode": "pro"}
+
+    def test_verbosity_unknown_value_dropped(self) -> None:
+        """A verbosity outside {low,medium,high} is dropped, not sent — an
+        operator typo must not 400 every request."""
+        kwargs = self._build(ModelCapabilities(supports_verbosity=True, verbosity="verbose"))
+        assert "text" not in kwargs
+
+    def test_pro_mode_unknown_value_dropped(self) -> None:
+        """An unknown reasoning_mode is dropped; a valid effort still rides."""
+        caps = ModelCapabilities(
+            supports_pro_mode=True,
+            reasoning_mode="ultra",
+            reasoning_effort_values=("low", "medium", "high"),
+        )
+        kwargs = self._build(caps, reasoning_effort="high")
+        assert kwargs["reasoning"] == {"effort": "high"}
+
+    def test_gpt56_terra_max_snaps_to_xhigh_on_responses_wire(self) -> None:
+        """Terra's knob "max" snaps to the xhigh ceiling on the ACTUAL
+        Responses wire path (_build_kwargs), not only the shared resolver."""
+        kwargs = self.provider._build_kwargs(
+            model="gpt-5.6-terra",
+            messages=[{"role": "user", "content": "Hi"}],
+            tools=None,
+            max_tokens=4096,
+            temperature=0.5,
+            reasoning_effort="max",
+            deferred_names=None,
+        )
+        assert kwargs["reasoning"] == {"effort": "xhigh"}
+
+    def test_gpt56_verbosity_and_pro_flags(self) -> None:
+        """The static rows carry the right capability flags: verbosity on all
+        three tiers, pro mode on Sol/alias only."""
+        sol = lookup_openai_capabilities("gpt-5.6-sol")
+        assert sol.supports_verbosity is True
+        assert sol.supports_pro_mode is True
+        assert lookup_openai_capabilities("gpt-5.6").supports_pro_mode is True
+        for tier in ("gpt-5.6-terra", "gpt-5.6-luna"):
+            caps = lookup_openai_capabilities(tier)
+            assert caps.supports_verbosity is True
+            assert caps.supports_pro_mode is False
+
     def _kwargs_with(self, tools: list[dict[str, Any]], caps: ModelCapabilities) -> dict[str, Any]:
         return self.provider._build_kwargs(
             model="gpt-5.4",

tests/test_renderer_js.py

@@ -1549,3 +1549,365 @@ def test_streaming_apply_marks_buffer_only_on_success() -> None:
     assert ".catch(function (e) {" in body[chain_at : chain_at + 3500], (
         "every mermaid chain link must settle back to fulfilled"
     )
+
+
+# ---------------------------------------------------------------------------
+# Renderer containment escapes (frontend-render-containment-brief)
+#
+# The renderer protects structural blocks with in-band NUL-framed sentinels
+# (NUL + two-letter-tag + index + NUL, e.g. code-block 0 -> chr(0)+"CB0"+chr(0)).
+# escapeHtml preserves U+0000, so model/tool text carrying such a sequence used
+# to FORGE a sentinel: the shared restore pass rewrote every match, duplicating
+# or relocating a protected block (B1), printing literal "undefined" for an
+# out-of-range index (B2), or injecting a restored span across a container (B3).
+# Fix 1 strips U+0000 (NUL) at the TOP-LEVEL render entry only, so no forged
+# NUL survives to frame a sentinel while generated (recursive-frame) sentinels
+# are left intact.  Only NUL is stripped — every other control byte survives so
+# code fences show pasted source verbatim.  Inputs build NUL via chr(0) (never
+# a literal escape) per the brief.
+# ---------------------------------------------------------------------------
+
+_NUL = chr(0)
+
+
+def test_forged_code_block_sentinel_does_not_duplicate_block() -> None:
+    """B1: prose carrying a forged ``chr(0)+CB0+chr(0)`` used to make the
+    shared restore pass emit the protected code block a SECOND time (content
+    spoofing / relocation).  Stripping NUL at the entry neutralises the
+    forgery: exactly one code block, no leaked sentinel."""
+    md = "```python\nprint('hi')\n```\n\nprose " + _NUL + "CB0" + _NUL + " end"
+    out = _render(md)
+    assert out.count("<pre>") == 1, "forged CB sentinel duplicated the block:\n" + out
+    assert out.count("print(") == 1
+    assert _NUL not in out, "raw NUL / forged sentinel leaked into output"
+
+
+def test_forged_out_of_range_sentinel_does_not_print_undefined() -> None:
+    """B2: ``chr(0)+IC7+chr(0)`` with no inline codes used to restore
+    ``inlineCodes[7]`` -> literal ``undefined`` in the rendered text.  After
+    the entry strip the forged framing is gone, so no ``undefined`` appears."""
+    out = _render("text " + _NUL + "IC7" + _NUL + " tail")
+    assert "undefined" not in out, "out-of-range forged sentinel printed 'undefined':\n" + out
+    assert _NUL not in out
+
+
+def test_control_strip_preserves_legit_fence_and_inline() -> None:
+    """Fix 1 must not disturb legitimately generated sentinels: a normal
+    fence and inline-code span still render after the entry strip (the strip
+    only removes caller-supplied control chars, which are never valid data)."""
+    out = _render("Here is `inline` and a block:\n\n```py\nx = 1\n```")
+    assert "<code>inline</code>" in out
+    assert "<pre><code" in out
+    assert "x = 1" in out
+    assert _NUL not in out
+
+
+def test_strip_removes_only_nul_preserving_other_control_bytes() -> None:
+    """The entry strip removes ONLY NUL (the sentinel-framing byte), so a code
+    fence still shows pasted control bytes (terminal output, ANSI escapes)
+    verbatim.  Stripping the whole C0/DEL range would silently corrupt code
+    samples; only NUL can forge a sentinel."""
+    esc = chr(27)  # ANSI escape — legitimate in pasted terminal output
+    out = _render("```\nbefore " + esc + "[0m after " + _NUL + " end\n```")
+    assert esc in out, "ESC (0x1b) must survive inside a code fence:\n" + repr(out)
+    assert _NUL not in out, "NUL must still be stripped (sentinel-framing byte)"
+    assert "before " in out and " end" in out
+
+
+def test_forged_inline_sentinel_not_injected_inside_fence() -> None:
+    """B3: a forged ``chr(0)+IC0+chr(0)`` placed inside a real code fence
+    used to be substituted AFTER the fence was restored (CB restores before
+    IC), injecting a real ``<code>`` span into the ``<pre>``.  With a genuine
+    inline-code span present (so inlineCodes[0] exists), the forged reference
+    must NOT clone it into the code block."""
+    md = "`real`\n\n```text\nbefore " + _NUL + "IC0" + _NUL + " after\n```"
+    out = _render(md)
+    assert out.count("<code>real</code>") == 1, "forged IC sentinel injected into <pre>:\n" + out
+    assert _NUL not in out
+    assert "before IC0 after" in out, "fence body should show the inert forged tag as text"
+
+
+def test_nul_strip_scoped_to_top_level_call() -> None:
+    """Structural pin for the PLAUSIBLE placement refinement: the NUL strip
+    lives inside the ``_fnDepth === 0`` guard of the exported wrapper, NOT in
+    ``_renderMarkdownBody`` (which runs at every recursion depth).  An
+    unconditional strip would shred the generated sentinels that recursive
+    ``<details>``/footnote frames legitimately carry — foreclosing the
+    recursive-frame fix.  Recursion must reach raw text with its sentinels."""
+    body = _RENDERER_JS.read_text(encoding="utf-8")
+    assert "_NUL_STRIP_RE" in body
+    wrapper = body.index("export function renderMarkdown(text)")
+    body_fn = body.index("function _renderMarkdownBody(text)")
+    seg = body[wrapper:body_fn]
+    guard_at = seg.index("_fnDepth === 0")
+    strip_at = seg.index("_NUL_STRIP_RE", guard_at)
+    incr_at = seg.index("_fnDepth++")
+    assert guard_at < strip_at < incr_at, (
+        "the NUL strip must run inside the top-level (_fnDepth === 0) "
+        "guard, before the depth increment"
+    )
+    assert "_NUL_STRIP_RE" not in body[body_fn:], (
+        "strip must not live in _renderMarkdownBody (would run at every depth)"
+    )
+
+
+def test_recursive_frame_degrades_without_literal_undefined() -> None:
+    """Fix 2 floor for the NEW-1 residual: a recursive render frame
+    (``<details>`` body, footnote definition) whose fresh block arrays cannot
+    resolve an outer-scope sentinel must NOT print the literal word
+    ``undefined``.  The restore callbacks return the (inert) matched sentinel
+    instead.  (This asserts only the ``undefined`` floor — Fix 5 is what makes
+    the body actually render; the raw sentinel that the node harness preserves
+    here is dropped by a real browser's tokenizer.)"""
+    details = _render("<details>\n<summary>x</summary>\n\n```py\nsecret_code()\n```\n\n</details>")
+    assert "undefined" not in details, "code-in-<details> printed 'undefined':\n" + details
+    footnote = _render("See[^1].\n\n[^1]: a `snippet` ok")
+    assert "undefined" not in footnote, "inline-code-in-footnote printed 'undefined':\n" + footnote
+
+
+def test_standalone_code_block_not_wrapped_in_paragraph() -> None:
+    """Fix 6 (NEW-3): code blocks need the ``<p>SENTINEL</p>`` unwrap variant
+    that DT/BQ/MB/TB already have.  Without it a lone fenced block emits
+    ``<p><pre>…</pre></p>``, which a real browser splits into a stray empty
+    ``<p>`` before the ``<pre>``.  The unwrap removes the wrapping paragraph."""
+    out = _render("```py\nx = 1\n```")
+    assert "<pre><code" in out
+    assert "<p><pre>" not in out, "code block still wrapped in a paragraph:\n" + out
+    assert out.strip().startswith("<pre>"), "code block should not be paragraph-wrapped:\n" + out
+
+
+# ---------------------------------------------------------------------------
+# Fix 3 — blockquote-in-fence (B4): fence protection must run before (and
+# mask) the line-based blockquote pass, with the fence open anchored to line
+# start so a blockquoted fence (`> ```) is NOT matched at column > 0.
+# ---------------------------------------------------------------------------
+
+
+def test_blockquote_inside_fence_not_extracted() -> None:
+    """B4 (the common one, no special chars): ``> `` lines INSIDE a code
+    fence used to be scooped out by the blockquote pre-pass (which ran first)
+    and rendered as a real ``<blockquote>`` nested in ``<pre><code>`` — a
+    shell transcript or quoted-email code block would sprout a headline.  The
+    fence pass now runs first and masks the region."""
+    out = _render("```text\nplain\n> quoted\nafter\n```")
+    assert "<blockquote>" not in out, "blockquote extracted from inside a fence:\n" + out
+    assert "<pre><code" in out
+    assert "&gt; quoted" in out, "the quoted line must stay literal (escaped) code:\n" + out
+
+
+def test_blockquoted_fence_renders_as_code() -> None:
+    """A fence nested inside a blockquote (``> ```` ``) must still render as a
+    code block WITHIN the ``<blockquote>``.  Anchoring the fence open to line
+    start means it is not matched at column > 0, so the blockquote pass
+    extracts the ``> `` run and its recursive render handles the fence.  (Pins
+    that we did not over-correct by simply hoisting the fence pass — which
+    would have swallowed the blockquoted fence as ``undefined``.)"""
+    out = _render("> ```\n> code\n> ```")
+    assert "<blockquote>" in out
+    assert "<pre><code>code</code></pre>" in out, "blockquoted fence lost its code:\n" + out
+    assert "undefined" not in out
+    assert _NUL not in out
+
+
+def test_indented_fence_still_renders_as_code() -> None:
+    """The open anchor allows arbitrary leading indent, so a legitimately
+    indented fence (e.g. under a list item) still renders as code rather than a
+    paragraph of literal backticks.  (A bare ``^`` anchor would drop it; the
+    deeper 4-space-indent case is pinned separately.)"""
+    out = _render("  ```py\n  x = 1\n  ```")
+    assert "<pre><code" in out, "indented fence dropped (not rendered as code):\n" + out
+    assert "x = 1" in out
+
+
+def test_indented_fence_close_leaves_no_trailing_whitespace_line() -> None:
+    """An indented closing line's leading spaces must NOT survive as a trailing
+    whitespace-only line inside the code block: the content strip removes a
+    trailing newline PLUS any indent the close dragged into the capture (a
+    `` ``` `` closed at column 0 is unaffected).  Copilot review, PR #804."""
+    out = _render("  ```py\n  x = 1\n  ```")
+    m = re.search(r"<code[^>]*>(.*?)</code>", out, re.S)
+    assert m, "no <code> block:\n" + out
+    assert m.group(1) == "  x = 1", "indented fence close left a trailing whitespace line: " + repr(
+        m.group(1)
+    )
+
+
+# ---------------------------------------------------------------------------
+# Fix 4 — <details> open anchored to line start (B5). The details pass ran
+# with an unanchored open, so a `<details>` mentioned mid-line inside inline
+# code matched across the backtick spans and swallowed the DT sentinel /
+# lost the content between them.
+# ---------------------------------------------------------------------------
+
+
+def test_inline_code_details_tag_not_consumed_by_details_pass() -> None:
+    """B5: ``Use `<details>` then `</details>` to fold`` must render two
+    inline-code spans of the literal tags — NOT a real <details> element with
+    the text between the spans swallowed."""
+    out = _render("Use `<details>` then `</details>` to fold.")
+    assert "&lt;details&gt;" in out, "opening <details> tag not shown as literal code:\n" + out
+    assert "&lt;/details&gt;" in out, "closing </details> tag not shown as literal code:\n" + out
+    assert "<details>" not in out, "a real <details> element was wrongly created:\n" + out
+    assert out.count("<code>") == 2, "expected two inline-code spans:\n" + out
+
+
+def test_block_details_still_renders() -> None:
+    """No-regression: a genuine multi-line <details> block (at line start)
+    still renders as a real disclosure element."""
+    out = _render("<details>\n<summary>More</summary>\n\nBody text here.\n\n</details>")
+    assert "<details><summary>More</summary>" in out
+    assert "Body text here." in out
+
+
+def test_oneline_details_still_renders() -> None:
+    """No-regression: the common one-line form must survive the open anchor
+    (anchoring the CLOSE too would break this — do not)."""
+    out = _render("<details><summary>x</summary>y</details>")
+    assert "<details><summary>x</summary>" in out
+    assert "y" in out and out.rstrip().endswith("</details>")
+
+
+def test_details_inside_fence_stays_literal() -> None:
+    """Lock the behavior Fix 5a must preserve: a <details> shown INSIDE a code
+    fence is masked by the (earlier) fence pass and must stay literal escaped
+    code, never extracted into a real element."""
+    out = _render("```html\n<details><summary>s</summary>x</details>\n```")
+    assert "<pre><code" in out
+    assert "&lt;details&gt;" in out, "details-in-fence should be literal code:\n" + out
+    assert "<details>" not in out, "details inside a fence was wrongly extracted:\n" + out
+
+
+# ---------------------------------------------------------------------------
+# Fix 5 (NEW-1) — recursive-frame content loss.  renderMarkdown recurses for
+# <details> bodies and footnote definitions.  When those bodies were extracted
+# AFTER the fence/inline-code/math passes, they carried outer-scope sentinels
+# that the recursive call — with fresh, empty block arrays — could not resolve,
+# so a code block / inline code / math inside them rendered as `undefined` (or,
+# after the Fix 2 floor, an inert `CB0`/`IC0` sentinel) — silent content loss.
+# The structural fix extracts <details> from RAW markdown (before fence/inline
+# protection, fence-aware) and collects footnote definitions before the inline
+# passes, so each recursion sees raw content.
+# ---------------------------------------------------------------------------
+
+
+def test_code_block_in_details_renders_code() -> None:
+    """NEW-1 (a), the headline case: a fenced code block inside <details> must
+    render the CODE, not `undefined` and not an inert `CB0` sentinel."""
+    out = _render("<details>\n<summary>x</summary>\n\n```py\nsecret_code()\n```\n\n</details>")
+    assert "secret_code()" in out, "code inside <details> was lost:\n" + out
+    assert "<pre><code" in out and 'class="language-py"' in out
+    assert "undefined" not in out
+    assert _NUL not in out, "a raw sentinel leaked (recursion did not see raw markdown):\n" + out
+
+
+def test_blockquote_in_details_renders() -> None:
+    """NEW-1 generalises to any recursive block: a blockquote inside <details>
+    must render as a real <blockquote>, not a lost/inert sentinel."""
+    out = _render("<details>\n<summary>x</summary>\n\n> quoted\n\n</details>")
+    assert "<blockquote>" in out, "blockquote inside <details> was lost:\n" + out
+    assert "quoted" in out
+    assert _NUL not in out
+
+
+def test_inline_code_in_footnote_renders() -> None:
+    """NEW-1 (b): inline code in a footnote definition must render as a real
+    <code> span in the footnote section, not `undefined`/`IC0`."""
+    out = _render("See[^1].\n\n[^1]: uses `code` here")
+    assert "<code>code</code>" in out, "inline code in footnote def was lost:\n" + out
+    assert "undefined" not in out
+    assert _NUL not in out
+
+
+def test_math_in_footnote_renders() -> None:
+    r"""NEW-1 (b), math variant: display/inline math in a footnote definition
+    must reach KaTeX, not restore to `undefined`/`MB0`."""
+    out = _render("See[^1].\n\n[^1]: with \\(x^2\\) inline")
+    assert '<span class="katex">' in out, "math in footnote def was lost:\n" + out
+    assert "undefined" not in out
+    assert _NUL not in out
+
+
+# ---------------------------------------------------------------------------
+# Review round-1 regression pins: the details pass runs AFTER fence protection
+# (fence-masking, not offset math, provides fence-awareness), and both the
+# fence and details opens allow arbitrary leading indent.
+# ---------------------------------------------------------------------------
+
+
+def test_details_close_tag_shown_in_fenced_example_does_not_close_block() -> None:
+    """A `</details>` shown as example code inside a fence must NOT close the
+    real disclosure early.  Because the fence pass runs first and masks the
+    example as a sentinel, the details close matches only the real trailing
+    tag; the fenced example renders as literal code inside the block."""
+    md = "<details>\n<summary>s</summary>\n\n```html\n</details>\n```\n\n</details>"
+    out = _render(md)
+    assert '<pre><code class="language-html">' in out, "fenced example was swallowed:\n" + out
+    assert "&lt;/details&gt;" in out, "example </details> should be literal code:\n" + out
+    assert out.strip().startswith("<details><summary>s</summary>"), out
+    assert out.rstrip().endswith("</details>"), "real block closed early / stray text:\n" + out
+    assert _NUL not in out
+
+
+def test_deeply_indented_fence_renders_as_code() -> None:
+    """A fence indented 4+ spaces (as when nested under a list item) still
+    tokenises as a code block — the open anchor allows arbitrary indent, so we
+    don't regress deeply-nested code samples to literal backticks."""
+    out = _render("    ```py\n    x = 1\n    ```")
+    assert "<pre><code" in out, "deeply-indented fence dropped:\n" + out
+    assert "x = 1" in out
+
+
+def test_fence_on_list_marker_line_renders_as_code() -> None:
+    """A code fence that OPENS on the same line as a list marker (`- ```py`)
+    still tokenises as a code block inside the list item.  The open matches
+    after an optional list marker, which is re-emitted before the sentinel so
+    the list pass still sees the item.  Regression guard: a bare `^[ \\t]*`
+    anchor (no list-marker allowance) destroyed the block and leaked the raw
+    backticks + language tag as text."""
+    for src in ["- ```py\n  print(1)\n  ```", "1. ```py\n   print(1)\n   ```"]:
+        out = _render(src)
+        assert "<pre><code" in out, "list-marker-line fence dropped:\n" + repr(src) + "\n" + out
+        assert "print(1)" in out
+        assert "```py" not in out, "raw fence backticks leaked as text:\n" + out
+        assert "<li>" in out, "list structure lost:\n" + out
+
+
+def test_nested_list_fence_stays_nested() -> None:
+    """A fenced code block as a NESTED sub-item keeps its nesting level: the
+    fence pass re-emits the leading indent before the sentinel, so the list
+    pass still reads the sub-item's indentation.  Regression guard: dropping
+    the indent flattened the code block to a top-level sibling of the parent."""
+    out = _render("- parent\n  - ```py\n    code\n    ```")
+    assert "parent" in out
+    assert "<pre><code" in out and "```py" not in out
+    assert out.count("<ul>") == 2, "nested list fence flattened to a sibling:\n" + out
+
+
+def test_big_ordered_marker_fence_is_protected() -> None:
+    r"""A fence opening on a 10+ digit ordered-list marker line is still
+    protected — the marker alternation uses ``\d+``, matching the list pass,
+    not a capped ``\d{1,9}`` that would leave the fence unprotected."""
+    out = _render("1234567890. ```py\ncode\n```")
+    assert "<pre><code" in out, "big ordered-marker fence leaked as text:\n" + out
+    assert "```py" not in out
+
+
+def test_fenced_block_in_footnote_renders_in_footnote() -> None:
+    """A fenced code block continuing a footnote definition renders INSIDE the
+    footnote section (the fence pass re-emits the 2-space indent the
+    continuation scan needs; the restore round-trip then resolves it there)."""
+    out = _render("See[^1].\n\n[^1]: note\n  ```py\n  x=1\n  ```")
+    assert 'class="footnotes"' in out
+    assert out.find("<pre") > out.find('class="footnotes"'), (
+        "fenced code in a footnote rendered outside the footnote section:\n" + out
+    )
+    assert "x=1" in out
+
+
+def test_indented_details_is_extracted() -> None:
+    """An indented `<details>` (e.g. under a list item) is still extracted into
+    a real disclosure element — the open anchor allows leading whitespace,
+    while a mid-line `<details>` inside inline code still is not (B5)."""
+    out = _render("  <details><summary>x</summary>y</details>")
+    assert "<details><summary>x</summary>" in out, "indented <details> not extracted:\n" + out
+    assert "y" in out

tests/test_schedule_api.py

@@ -176,6 +176,206 @@ class TestScheduleAPI:
         assert resp.status_code == 400
         assert "future" in resp.json()["error"].lower()
 
+    @staticmethod
+    def _seed_persona(storage, name="researcher", kinds=None):
+        storage.create_persona(
+            {
+                "persona_id": f"id-{name}",
+                "name": name,
+                "display_name": name.title(),
+                "description": "",
+                "base_prompt": "You are a test persona.",
+                "applies_to_kinds": kinds or ["interactive"],
+            }
+        )
+
+    def test_create_with_persona_and_project(self, client, storage):
+        self._seed_persona(storage)
+        # Owned by the authenticated admin (created_by) → attachable.
+        storage.create_project("proj_1", "My Project", "test-admin")
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_cron_payload(persona="researcher", project_id="proj_1"),
+        )
+        assert resp.status_code == 200, resp.text
+        data = resp.json()
+        assert data["persona"] == "researcher"
+        assert data["project_id"] == "proj_1"
+
+    def test_create_defaults_persona_project_empty(self, client):
+        resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["persona"] == ""
+        assert data["project_id"] == ""
+
+    def test_create_unknown_persona_rejected(self, client):
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_cron_payload(persona="ghost"),
+        )
+        assert resp.status_code == 400
+        assert "persona" in resp.json()["error"].lower()
+
+    def test_create_persona_wrong_kind_rejected(self, client, storage):
+        # A coordinator-only persona is refused — schedules only ever dispatch
+        # interactive workstreams, so the picker/validation are kind-scoped.
+        self._seed_persona(storage, name="orchestrator", kinds=["coordinator"])
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_cron_payload(persona="orchestrator"),
+        )
+        assert resp.status_code == 400
+
+    def test_create_unattachable_project_rejected(self, client, storage):
+        # A private project owned by someone else — the admin isn't a member.
+        storage.create_project("proj_x", "Theirs", "someone-else", visibility="private")
+        resp = client.post(
+            "/v1/api/admin/schedules",
+            json=_cron_payload(project_id="proj_x"),
+        )
+        assert resp.status_code == 403
+
+    def test_update_persona_and_project(self, client, storage):
+        self._seed_persona(storage, name="scribe")
+        storage.create_project("proj_2", "Proj Two", "test-admin")
+        task_id = client.post("/v1/api/admin/schedules", json=_cron_payload()).json()["task_id"]
+        resp = client.put(
+            f"/v1/api/admin/schedules/{task_id}",
+            json={"persona": "scribe", "project_id": "proj_2"},
+        )
+        assert resp.status_code == 200, resp.text
+        data = client.get(f"/v1/api/admin/schedules/{task_id}").json()
+        assert data["persona"] == "scribe"
+        assert data["project_id"] == "proj_2"
+
+    @staticmethod
+    def _legacy_task(storage, task_id="legacy"):
+        """A schedule from before the created_by fix — created_by is ''."""
+        storage.create_scheduled_task(
+            task_id=task_id,
+            name="Legacy",
+            description="",
+            schedule_type="cron",
+            cron_expr="0 9 * * *",
+            at_time="",
+            target_mode="auto",
+            model="",
+            initial_message="go",
+            auto_approve=False,
+            auto_approve_tools=[],
+            created_by="",
+            next_run="2099-01-01T09:00:00",
+        )
+
+    def test_update_assign_project_heals_empty_created_by(self, client, storage):
+        # Assigning a project to an orphaned schedule adopts the editing admin
+        # as owner so the attach — and every future dispatch — has an identity.
+        self._legacy_task(storage)
+        storage.create_project("proj_heal", "Heal", "test-admin")
+        resp = client.put(
+            "/v1/api/admin/schedules/legacy",
+            json={"project_id": "proj_heal"},
+        )
+        assert resp.status_code == 200, resp.text
+        row = storage.get_scheduled_task("legacy")
+        assert row["project_id"] == "proj_heal"
+        assert row["created_by"] == "test-admin"
+
+    def test_update_denied_project_does_not_heal_created_by(self, client, storage):
+        # Healing must not become an attach bypass: a project the editing admin
+        # can't reach is still 403, and created_by/project stay untouched.
+        self._legacy_task(storage, task_id="legacy2")
+        storage.create_project("proj_other", "Other", "someone-else", visibility="private")
+        resp = client.put(
+            "/v1/api/admin/schedules/legacy2",
+            json={"project_id": "proj_other"},
+        )
+        assert resp.status_code == 403
+        row = storage.get_scheduled_task("legacy2")
+        assert row["created_by"] == ""
+        assert row["project_id"] == ""
+
+    def test_update_project_keeps_existing_owner(self, client, storage):
+        # A schedule that already has a real owner is NOT re-owned by an editing
+        # admin — created_by is only adopted for the orphaned "" case.
+        self._seed_persona(storage, name="researcher")
+        storage.create_scheduled_task(
+            task_id="owned",
+            name="Owned",
+            description="",
+            schedule_type="cron",
+            cron_expr="0 9 * * *",
+            at_time="",
+            target_mode="auto",
+            model="",
+            initial_message="go",
+            auto_approve=False,
+            auto_approve_tools=[],
+            created_by="original-owner",
+            next_run="2099-01-01T09:00:00",
+        )
+        # A public project the original owner (and anyone) can attach to.
+        storage.create_project("proj_pub", "Pub", "someone-else", visibility="public")
+        resp = client.put(
+            "/v1/api/admin/schedules/owned",
+            json={"project_id": "proj_pub"},
+        )
+        assert resp.status_code == 200, resp.text
+        row = storage.get_scheduled_task("owned")
+        assert row["project_id"] == "proj_pub"
+        assert row["created_by"] == "original-owner"
+
+    def test_update_unchanged_persona_skips_revalidation(self, client, storage):
+        # A persona disabled after creation must not block editing other fields
+        # when the shelf resends the unchanged slug (it still fails at dispatch).
+        self._seed_persona(storage, name="researcher")
+        task_id = client.post(
+            "/v1/api/admin/schedules", json=_cron_payload(persona="researcher")
+        ).json()["task_id"]
+        storage.update_persona("id-researcher", enabled=False)
+        resp = client.put(
+            f"/v1/api/admin/schedules/{task_id}",
+            json={"name": "Renamed", "persona": "researcher"},
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["name"] == "Renamed"
+        assert resp.json()["persona"] == "researcher"
+
+    def test_update_unchanged_project_skips_regate(self, client, storage):
+        # Project attach isn't re-gated when unchanged, so a project deleted (or
+        # membership lost) out from under the schedule doesn't block edits.
+        storage.create_project("proj_keep", "Keep", "test-admin")
+        task_id = client.post(
+            "/v1/api/admin/schedules", json=_cron_payload(project_id="proj_keep")
+        ).json()["task_id"]
+        storage.delete_project("proj_keep")  # a re-gate would now 400
+        resp = client.put(
+            f"/v1/api/admin/schedules/{task_id}",
+            json={"name": "Renamed", "project_id": "proj_keep"},
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["project_id"] == "proj_keep"
+
+    def test_update_ignores_created_by_in_body(self, client, storage):
+        # created_by is never sourced from the request body — a spoofed value
+        # in the PUT payload is ignored (only the heal path from auth writes it).
+        task_id = client.post("/v1/api/admin/schedules", json=_cron_payload()).json()["task_id"]
+        client.put(
+            f"/v1/api/admin/schedules/{task_id}",
+            json={"name": "X", "created_by": "attacker"},
+        )
+        row = storage.get_scheduled_task(task_id)
+        assert row["created_by"] == "test-admin"
+
+    def test_update_unknown_persona_rejected(self, client):
+        task_id = client.post("/v1/api/admin/schedules", json=_cron_payload()).json()["task_id"]
+        resp = client.put(
+            f"/v1/api/admin/schedules/{task_id}",
+            json={"persona": "ghost"},
+        )
+        assert resp.status_code == 400
+
     def test_get_schedule(self, client):
         create_resp = client.post("/v1/api/admin/schedules", json=_cron_payload())
         task_id = create_resp.json()["task_id"]

tests/test_scheduled_tasks_storage.py

@@ -47,9 +47,44 @@ class TestScheduledTaskCRUD:
         assert result["enabled"] == 1
         assert result["created_by"] == "u_admin"
         assert result["next_run"] == "2099-01-01T09:00:00"
+        # persona/project default to "" — empty means "kind default" / "no
+        # project", resolved late at dispatch (mirrors empty model/skill).
+        assert result["persona"] == ""
+        assert result["project_id"] == ""
         assert "created" in result
         assert "updated" in result
 
+    def test_create_with_persona_and_project(self, db):
+        db.create_scheduled_task(**_make_task_kwargs(persona="researcher", project_id="proj_42"))
+        result = db.get_scheduled_task("task_001")
+        assert result is not None
+        assert result["persona"] == "researcher"
+        assert result["project_id"] == "proj_42"
+
+    def test_update_persona_and_project(self, db):
+        db.create_scheduled_task(**_make_task_kwargs())
+        assert db.update_scheduled_task("task_001", persona="scribe", project_id="proj_9")
+        updated = db.get_scheduled_task("task_001")
+        assert updated is not None
+        assert updated["persona"] == "scribe"
+        assert updated["project_id"] == "proj_9"
+        # Clearing back to defaults is a first-class update, not a no-op.
+        assert db.update_scheduled_task("task_001", persona="", project_id="")
+        cleared = db.get_scheduled_task("task_001")
+        assert cleared is not None
+        assert cleared["persona"] == ""
+        assert cleared["project_id"] == ""
+
+    def test_update_created_by(self, db):
+        # created_by is allow-listed for update so the API can adopt an orphaned
+        # ("") schedule's owner. Exercised here so the Postgres backend covers
+        # the write too (the API test is SQLite-pinned).
+        db.create_scheduled_task(**_make_task_kwargs(created_by=""))
+        assert db.update_scheduled_task("task_001", created_by="adopted")
+        row = db.get_scheduled_task("task_001")
+        assert row is not None
+        assert row["created_by"] == "adopted"
+
     def test_get_nonexistent(self, db):
         assert db.get_scheduled_task("no_such_task") is None
 

tests/test_scheduler.py

@@ -156,6 +156,52 @@ class TestSchedulerTick:
         assert run_kwargs["status"] == "dispatched"
         assert run_kwargs["ws_id"] == "ws_abc123"
 
+    def test_dispatch_passes_persona_and_project(self, mocks):
+        """persona + project_id ride to create_workstream; created_by becomes
+        the user_id the node gates the project attach against."""
+        collector, storage = mocks
+
+        task = _make_task(persona="researcher", project_id="proj_42")
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = ([_make_node()], 1)
+        collector.get_node_detail.return_value = {"server_url": "http://node-001:8080"}
+
+        scheduler = TaskScheduler(collector, storage)
+        with patch(
+            "turnstone.console.scheduler.TurnstoneServer.create_workstream",
+            return_value=_mock_create_response(),
+        ) as mock_create:
+            scheduler._tick()
+
+        mock_create.assert_called_once()
+        call_kwargs = mock_create.call_args[1]
+        assert call_kwargs["persona"] == "researcher"
+        assert call_kwargs["project_id"] == "proj_42"
+        assert call_kwargs["user_id"] == "u_admin"
+
+    def test_dispatch_defaults_persona_project_empty(self, mocks):
+        """A task row without persona/project keys dispatches with empty
+        strings — the node then resolves the current kind default / no attach."""
+        collector, storage = mocks
+
+        task = _make_task()
+        task.pop("persona", None)
+        task.pop("project_id", None)
+        storage.list_due_tasks.return_value = [task]
+        collector.get_nodes.return_value = ([_make_node()], 1)
+        collector.get_node_detail.return_value = {"server_url": "http://node-001:8080"}
+
+        scheduler = TaskScheduler(collector, storage)
+        with patch(
+            "turnstone.console.scheduler.TurnstoneServer.create_workstream",
+            return_value=_mock_create_response(),
+        ) as mock_create:
+            scheduler._tick()
+
+        call_kwargs = mock_create.call_args[1]
+        assert call_kwargs["persona"] == ""
+        assert call_kwargs["project_id"] == ""
+
     def test_dispatch_pool_mode(self, mocks):
         collector, storage = mocks
 

tests/test_sdk_console.py

@@ -337,6 +337,8 @@ async def test_create_schedule():
             schedule_type="cron",
             initial_message="Run nightly checks",
             cron_expr="0 2 * * *",
+            persona="researcher",
+            project_id="proj_1",
         )
         assert resp.task_id == "t1"
         body = captured_body[0]
@@ -344,6 +346,8 @@ async def test_create_schedule():
         assert body["schedule_type"] == "cron"
         assert body["cron_expr"] == "0 2 * * *"
         assert body["initial_message"] == "Run nightly checks"
+        assert body["persona"] == "researcher"
+        assert body["project_id"] == "proj_1"
         # Optional fields with defaults should not appear when not set
         assert "description" not in body
         assert "model" not in body

tests/test_sdk_server.py

@@ -380,12 +380,16 @@ async def test_create_workstream_extended_params():
             auto_approve_tools="read_file,write_file",
             user_id="u42",
             ws_id="ws_custom",
+            persona="researcher",
+            project_id="proj_9",
         )
         assert captured_body["name"] == "ext"
         assert captured_body["initial_message"] == "hi"
         assert captured_body["auto_approve_tools"] == "read_file,write_file"
         assert captured_body["user_id"] == "u42"
         assert captured_body["ws_id"] == "ws_custom"
+        assert captured_body["persona"] == "researcher"
+        assert captured_body["project_id"] == "proj_9"
 
 
 @pytest.mark.anyio
@@ -406,3 +410,5 @@ async def test_create_workstream_omits_empty_params():
         assert "auto_approve_tools" not in captured_body
         assert "user_id" not in captured_body
         assert "ws_id" not in captured_body
+        assert "persona" not in captured_body
+        assert "project_id" not in captured_body

tests/test_server_attachments_endpoints.py

@@ -296,6 +296,24 @@ class TestGetContent:
         assert "default-src 'none'" in resp.headers.get("content-security-policy", "")
         assert resp.headers.get("content-disposition", "").startswith("inline;")
 
+    def test_get_content_non_latin1_filename_does_not_500(self, app_client):
+        # Starlette encodes header values as latin-1 and raises on anything
+        # else; an uploaded filename with CJK / em dashes must fold to an
+        # ASCII-safe Content-Disposition rather than 500 the serving route.
+        # Mirrors preview_response_headers' latin-1 fold.
+        client, _ = app_client
+        aid = _upload(client, "ws-A", "userA", "文書 — v1.md", b"x", "text/markdown")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/content",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200
+        assert resp.content == b"x"
+        # Non-ASCII folded to '?', ASCII kept — pinning the value proves the
+        # fold actually ran and the header is latin-1 clean (all codepoints
+        # < 0x80), not merely that the route didn't crash.
+        assert resp.headers["content-disposition"] == 'inline; filename="?? ? v1.md"'
+
     def test_get_content_forces_text_plain_for_text_kinds(self, app_client):
         # Uploading an HTML-ish file as text/html must NOT be served back
         # with Content-Type: text/html from our origin (XSS vector).
@@ -459,6 +477,11 @@ class TestSendMessageAttachments:
         session = MagicMock()
         session._cancel_event = threading.Event()
         session.queue_message = MagicMock()
+        # A bare Mock's auto-created ``_nudge_queue`` (truthy, has_pending
+        # truthy, no-op deliver) turns the worker-exit wake backstop into an
+        # endless respawn loop; declare this a stub session WITHOUT a queue
+        # so the wake gate's stub-guard bails.
+        session._nudge_queue = None
         captured: dict = {}
 
         def fake_send(message, attachments=None, send_id=None):
@@ -480,6 +503,7 @@ class TestSendMessageAttachments:
         ws.session = session
         ws.worker_thread = None
         ws._worker_running = False
+        ws._closed = False  # a bare Mock attr is truthy → send() would refuse
         ws._lock = threading.RLock()
         mgr.get.return_value = ws
         return captured, session
@@ -658,6 +682,9 @@ class TestQueuedSendWithAttachments:
         session = MagicMock()
         session._cancel_event = threading.Event()
         session.queue_message = fake_queue_message
+        # Stub session without a NudgeQueue — see _wire_ws for why a bare
+        # Mock queue would feed the exit backstop an endless wake loop.
+        session._nudge_queue = None
 
         ui = MagicMock()
         ui._ws_lock = threading.Lock()
@@ -675,6 +702,7 @@ class TestQueuedSendWithAttachments:
         ws.session = session
         ws.worker_thread = worker
         ws._worker_running = True
+        ws._closed = False  # a bare Mock attr is truthy → send() would refuse
         ws._lock = threading.RLock()
         mgr.get.return_value = ws
         return captured
@@ -738,6 +766,7 @@ class TestBusyWorkerAttachments:
         ws.ui = ui
         ws.session = session
         ws.worker_thread = worker
+        ws._closed = False  # a bare Mock attr is truthy → send() would refuse
         ws._lock = threading.RLock()
         mgr.get.return_value = ws
         return ws, session
@@ -1032,3 +1061,156 @@ class TestTextToSpeech:
         body = resp.json()
         assert body["error"] == "Speech synthesis backend failed"
         assert "internal-host" not in body["error"]
+
+
+# ---------------------------------------------------------------------------
+# GET /preview — the renderable serving route (preview pane)
+# ---------------------------------------------------------------------------
+
+
+def _seed_committed(ws_id: str, kind: str, mime: str, body: bytes, filename: str) -> str:
+    """Commit a blob the way the open_preview fold does: content-addressed
+    save + a tool row whose ref-list names it (the serving ownership gate)."""
+    import hashlib
+
+    from turnstone.core.memory import save_attachment, save_message, set_message_attachments
+
+    aid = hashlib.sha256(b"preview:" + body).hexdigest()
+    save_attachment(aid, filename, mime, len(body), kind, body, "tool")
+    row_id = save_message(ws_id, "tool", "Preview shown", "open_preview", tool_call_id="c1")
+    assert row_id is not None
+    set_message_attachments(ws_id, row_id, [aid])
+    return aid
+
+
+class TestGetPreview:
+    def test_html_default_serves_locked_down_csp(self, app_client):
+        client, _ = app_client
+        body = b'<html><head><base href="https://acme.com/"></head><body>x</body></html>'
+        aid = _seed_committed("ws-A", "preview", "text/html; charset=utf-8", body, "preview-web")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200
+        assert resp.headers["content-type"].startswith("text/html")
+        assert resp.content == body
+        # Default (no ?assets): renderable but off the network — sandboxed,
+        # inline styling + data-URI images only, so previewing discloses
+        # nothing to the origin site.
+        assert resp.headers.get("content-security-policy") == (
+            "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:"
+        )
+        assert resp.headers.get("x-content-type-options") == "nosniff"
+        assert resp.headers.get("content-disposition", "").startswith("inline;")
+        assert resp.headers.get("cache-control") == "private, no-store"
+
+    def test_html_assets_flag_serves_bare_sandbox(self, app_client):
+        # ?assets=1 is the per-pane opt-in: drop back to the bare sandbox so
+        # the page's own images / CSS load.
+        client, _ = app_client
+        body = b"<html><head></head><body>x</body></html>"
+        aid = _seed_committed("ws-A", "preview", "text/html; charset=utf-8", body, "preview-web")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview?assets=1",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200
+        assert resp.headers.get("content-security-policy") == "sandbox"
+
+    def test_pdf_served_without_csp(self, app_client):
+        client, _ = app_client
+        aid = _seed_committed("ws-A", "preview", "application/pdf", b"%PDF-1.4 x", "d.pdf")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200
+        assert resp.headers["content-type"].startswith("application/pdf")
+        # Chromium's viewer refuses sandboxed contexts — the route omits CSP.
+        assert "content-security-policy" not in resp.headers
+
+    def test_image_keeps_full_csp(self, app_client):
+        client, _ = app_client
+        aid = _seed_committed("ws-A", "preview", "image/png", PNG_1x1, "chart.png")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200
+        assert "default-src 'none'" in resp.headers.get("content-security-policy", "")
+
+    def test_non_renderable_mime_415(self, app_client):
+        client, _ = app_client
+        aid = _seed_committed("ws-A", "audio", "audio/wav", WAV_12, "a.wav")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 415
+
+    def test_uploaded_attachment_also_previews(self, app_client):
+        # An UPLOADED image (committed via the normal user lane) renders
+        # through /preview too — the pane serves attachment: targets.
+        client, _ = app_client
+        aid = _seed_committed("ws-A", "image", "image/png", PNG_1x1, "up.png")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200
+        assert resp.headers["content-type"].startswith("image/png")
+
+    def test_unreferenced_id_404(self, app_client):
+        client, _ = app_client
+        aid = _seed_committed("ws-A", "preview", "text/html", b"<p>x</p>", "p")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-B/attachments/{aid}/preview",
+            headers=_auth("userB"),
+        )
+        assert resp.status_code == 404
+
+    def test_probe_returns_204_with_hardening_headers(self, app_client):
+        # The pane preflights src-loaded kinds with ?probe=1 instead of HEAD:
+        # the console reverse proxy forwards a HEAD as a full GET, so a real
+        # HEAD would drag the whole blob across the hop just to discard it. The
+        # probe runs the ownership + renderable-type gates and returns the real
+        # response's hardening headers with an empty body.
+        client, _ = app_client
+        body = b"<html><head></head><body>x</body></html>"
+        aid = _seed_committed("ws-A", "preview", "text/html; charset=utf-8", body, "preview-web")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview?probe=1",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 204
+        assert resp.content == b""
+        # Same hardening headers the real GET would carry (the probe answers
+        # "will the load paint?"): the html CSP is present.
+        assert resp.headers.get("content-security-policy") == (
+            "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:"
+        )
+        assert resp.headers.get("x-content-type-options") == "nosniff"
+
+    def test_probe_composes_with_assets_flag(self, app_client):
+        # ?probe=1&assets=1 → 204 whose headers reflect the assets opt-in.
+        client, _ = app_client
+        body = b"<html><head></head><body>x</body></html>"
+        aid = _seed_committed("ws-A", "preview", "text/html; charset=utf-8", body, "preview-web")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview?probe=1&assets=1",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 204
+        assert resp.headers.get("content-security-policy") == "sandbox"
+
+    def test_probe_non_renderable_mime_still_415(self, app_client):
+        # A probe must answer "will the real load succeed?" — a non-renderable
+        # blob 415s exactly as the real GET would, before any 204.
+        client, _ = app_client
+        aid = _seed_committed("ws-A", "audio", "audio/wav", WAV_12, "a.wav")
+        resp = client.get(
+            f"/v1/api/workstreams/ws-A/attachments/{aid}/preview?probe=1",
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 415

tests/test_server_attachments_on_create.py

@@ -434,6 +434,91 @@ class TestCreateMultipart:
         # pane's rehydrate can't observe it as still-staged.
         assert get_attachment_buffer().get(aid, ws_id=ws_id, user_id="userA") is None
 
+    def test_create_raced_by_live_worker_keeps_attachments_staged(self, app_client, monkeypatch):
+        """The enqueue branch (caller-supplied ws_id raced by a concurrent
+        /send claiming the worker first) can't deliver attachments through
+        the interjection seam — they must REMAIN STAGED so the composer
+        still shows them and the user's next send delivers them, while the
+        message text itself rides the queue."""
+        from turnstone.core import session_worker
+        from turnstone.core.attachment_buffer import get_attachment_buffer
+
+        client, _sessions, _gq = app_client
+        queued: list[str] = []
+
+        def _record_queue(self, text, *a, **k):
+            queued.append(text)
+            return ("", "normal", "msg-x")
+
+        monkeypatch.setattr(_FakeSession, "queue_message", _record_queue)
+
+        def _live_worker_send(ws, *, enqueue, run, thread_name=None):
+            enqueue()  # a worker already owns the ws — reuse path
+            return True
+
+        monkeypatch.setattr(session_worker, "send", _live_worker_send)
+
+        meta = {"name": "raced", "initial_message": "look at this file"}
+        resp = client.post(
+            "/v1/api/workstreams/new",
+            data={"meta": json.dumps(meta)},
+            files=[("file", ("notes.md", b"# hello\n", "text/markdown"))],
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200, resp.text
+        ws_id = resp.json()["ws_id"]
+        aid = resp.json()["attachment_ids"][0]
+
+        assert queued == ["look at this file"]  # text preserved via the queue
+        # NOT drained: the upload stays staged, recoverable on the next send.
+        assert get_attachment_buffer().get(aid, ws_id=ws_id, user_id="userA") is not None
+        # Delivered path → no dropped-message marker on the response.
+        assert "initial_message_status" not in resp.json()
+
+    def test_create_raced_queue_full_reports_dropped_message(self, app_client, monkeypatch):
+        """``queue.Full`` on the raced enqueue path must not read as
+        success: it propagates out of ``_enqueue_init`` into
+        ``session_worker.send``'s backpressure branch (→ ``False``), and
+        the create response carries ``initial_message_status:
+        "queue_full"`` instead of a bare 200 implying the first message
+        was delivered.  Attachments stay staged for the retry."""
+        import queue as _queue
+
+        from turnstone.core import session_worker
+        from turnstone.core.attachment_buffer import get_attachment_buffer
+
+        client, _sessions, _gq = app_client
+
+        def _full_queue(self, *a, **k):
+            raise _queue.Full
+
+        monkeypatch.setattr(_FakeSession, "queue_message", _full_queue)
+
+        def _live_worker_send(ws, *, enqueue, run, thread_name=None):
+            # Mirror the real send()'s reuse-path backpressure contract:
+            # queue.Full → False, never a raise to the caller.
+            try:
+                enqueue()
+            except _queue.Full:
+                return False
+            return True
+
+        monkeypatch.setattr(session_worker, "send", _live_worker_send)
+
+        meta = {"name": "raced-full", "initial_message": "look at this file"}
+        resp = client.post(
+            "/v1/api/workstreams/new",
+            data={"meta": json.dumps(meta)},
+            files=[("file", ("notes.md", b"# hello\n", "text/markdown"))],
+            headers=_auth("userA"),
+        )
+        assert resp.status_code == 200, resp.text
+        body = resp.json()
+        assert body["initial_message_status"] == "queue_full"
+        # Attachments untouched — the composer chips survive for the retry.
+        aid = body["attachment_ids"][0]
+        assert get_attachment_buffer().get(aid, ws_id=body["ws_id"], user_id="userA") is not None
+
     def test_create_with_attachments_no_initial_message_keeps_staged(self, app_client):
         import hashlib
 
@@ -527,3 +612,28 @@ class TestCreateJsonStillWorks:
         assert data["ws_id"]
         # New optional field, but always emitted (empty list when absent)
         assert data["attachment_ids"] == []
+
+    def test_initial_message_routes_through_session_worker_send(self, app_client):
+        """The initial-message worker is dispatched via
+        ``session_worker.send`` (not an inlined ``threading.Thread``) so it
+        inherits the ownership-clear wake backstop.  Patching the module
+        attribute captures the wiring without spawning a thread — server.py
+        calls ``session_worker.send`` as a module attribute even from its
+        local import."""
+        from unittest.mock import patch
+
+        client, _sessions, _gq = app_client
+        with patch("turnstone.core.session_worker.send", return_value=True) as mock_send:
+            resp = client.post(
+                "/v1/api/workstreams/new",
+                json={"name": "init-dispatch", "initial_message": "go"},
+                headers=_auth("userA"),
+            )
+            assert resp.status_code == 200, resp.text
+            assert mock_send.call_count == 1
+            kwargs = mock_send.call_args.kwargs
+            assert kwargs["thread_name"].startswith("ws-init-")
+            # ``run`` is the init closure the shared dispatcher spawns; the
+            # dead-by-construction ``enqueue`` branch is still wired (loudly).
+            assert callable(kwargs["run"])
+            assert callable(kwargs["enqueue"])

tests/test_session.py

@@ -5086,6 +5086,55 @@ class TestMetacognitiveBuffers:
         assert sys_turn["_source"] == "tool_error"
         assert sys_turn["content"] == "you hit an error; check memory"
 
+    def test_denial_nudge_queues_on_tool_channel(self, tmp_db):
+        """A denial responds to the tool batch the user just rejected — the
+        producer must queue it on the TOOL channel so it drains through
+        ``_collect_advisories`` alongside the denied results (the same seam
+        tool_error / repeat use), not sit on the user channel until the next
+        user-message seam — by which point the model has already reacted to
+        the denial without the nudge.
+
+        Drives the REAL ``_execute_tools`` two-phase gate with real
+        ``_nudges_enabled`` / ``should_nudge`` gating; only the prepare
+        step and the UI approval are stubbed."""
+        from turnstone.core.metacognition import format_nudge
+
+        session = _make_session()
+        # ``should_nudge`` skips the very first message — give the session
+        # the natural pre-batch shape (user turn + assistant tool-call turn).
+        session.messages.append(turn_from_dict({"role": "user", "content": "do the thing"}))
+        session.messages.append(turn_from_dict({"role": "assistant", "content": "calling"}))
+
+        item = {
+            "call_id": "call_1",
+            "func_name": "notify",
+            "needs_approval": True,
+            # Must NOT run — a denied tool never executes.
+            "execute": lambda p: (p["call_id"], "EXECUTED — must not happen"),
+        }
+        with (
+            patch.object(session, "_safe_prepare_tool", return_value=item),
+            patch.object(session.ui, "approve_tools", return_value=(False, "use /tmp instead")),
+            patch.object(session, "_visible_memory_count", return_value=0),
+        ):
+            tool_calls = [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {"name": "notify", "arguments": "{}"},
+                }
+            ]
+            results, feedback = session._execute_tools(tool_calls)
+
+        # The denied item surfaced the operator's feedback as its result…
+        assert results == [("call_1", "Denied by user: use /tmp instead")]
+        assert feedback is None
+        # …and the denial nudge is queued on the TOOL channel, so the same
+        # batch's ``_collect_advisories`` drain delivers it; nothing defers
+        # to the next user turn.
+        assert session._nudge_queue.pending(channel="tool") == [("denial", format_nudge("denial"))]
+        assert session._nudge_queue.pending(channel="user") == []
+
     def test_queued_message_appends_system_turn_after_tool_batch(self, tmp_db):
         """A queued message arriving during a tool batch becomes a
         first-class ``{"role": "system", "_source": "user_interjection"}``
@@ -6984,6 +7033,73 @@ def test_utility_completion_defers_temperature_to_session():
     assert kw2["temperature"] == 0.9  # explicit override still honored
 
 
+def test_web_fetch_extraction_inherits_session_max_tokens_and_effort():
+    """web_fetch's extraction call must inherit the session/registry max_tokens
+    and reasoning_effort rather than forcing constants.  Hard-coding
+    max_tokens=8192 / reasoning_effort="low" broke local-inference models whose
+    registry entry advertises a tighter output limit or a reasoning config the
+    forced values fought — this lane now behaves like the main turn."""
+    from unittest.mock import patch
+
+    from turnstone.core.providers._protocol import CompletionResult
+
+    session = _make_session(max_tokens=512, reasoning_effort="high")
+
+    resp = MagicMock()
+    resp.raise_for_status.return_value = None
+    resp.headers = {"content-type": "text/plain"}
+    resp.text = "The page body that holds the answer."
+
+    with (
+        patch("turnstone.core.session.fetch_with_ssrf_guard", return_value=resp),
+        patch.object(
+            session,
+            "_utility_completion",
+            return_value=CompletionResult(content="Extracted answer."),
+        ) as uc,
+    ):
+        call_id, answer = session._exec_web_fetch({"call_id": "c1", "url": "https://example.com/"})
+
+    assert call_id == "c1"
+    assert answer == "Extracted answer."
+    _, kw = uc.call_args
+    # 512 < context_window // 4 (8192), so the tighter session value passes
+    # through unclamped — inheritance, not the old hard-coded 8192.
+    assert kw["max_tokens"] == 512
+    assert kw["reasoning_effort"] == "high"  # session value, not the old "low"
+
+
+def test_web_fetch_extraction_caps_max_tokens_to_window_reserve():
+    """The extraction request is capped to the ~25% window slice Phase 2
+    reserves (``context_window // 4``), matching the main turn's response
+    reserve — so a large operator ``max_tokens`` on a small-context local
+    model can't push prompt + output past the window."""
+    from unittest.mock import patch
+
+    from turnstone.core.providers._protocol import CompletionResult
+
+    # context_window=8192 -> reserve 2048; the session budget is far larger.
+    session = _make_session(max_tokens=16384, context_window=8192)
+
+    resp = MagicMock()
+    resp.raise_for_status.return_value = None
+    resp.headers = {"content-type": "text/plain"}
+    resp.text = "The page body that holds the answer."
+
+    with (
+        patch("turnstone.core.session.fetch_with_ssrf_guard", return_value=resp),
+        patch.object(
+            session,
+            "_utility_completion",
+            return_value=CompletionResult(content="Extracted answer."),
+        ) as uc,
+    ):
+        session._exec_web_fetch({"call_id": "c1", "url": "https://example.com/"})
+
+    _, kw = uc.call_args
+    assert kw["max_tokens"] == 2048  # context_window // 4, not the 16384 session value
+
+
 def test_record_aux_usage_skips_when_usage_missing():
     """A provider that reports no usage object must not emit a phantom
     zero-token row."""

tests/test_session_routes.py

@@ -37,7 +37,7 @@ async def _stub(_request: Request) -> JSONResponse:
 
 def _attach() -> AttachmentHandlers:
     return AttachmentHandlers(
-        upload=_stub, list=_stub, get_content=_stub, thumbnail=_stub, delete=_stub
+        upload=_stub, list=_stub, get_content=_stub, thumbnail=_stub, preview=_stub, delete=_stub
     )
 
 

tests/test_session_ui_base.py

@@ -39,6 +39,22 @@ def _make_ui(ws_id: str = "ws-1", user_id: str = "u1") -> _ConcreteUI:
     return _ConcreteUI(ws_id=ws_id, user_id=user_id)
 
 
+@pytest.fixture(autouse=True)
+def _per_token_flush(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Force per-token flushes (batch window 0) for this whole file.
+
+    These tests pin per-emit invariants — seq advance, mid-stream
+    inflight buffer state, snapshot atomicity — that predate emit-time
+    token batching and remain the contract AT each flush boundary;
+    window 0 makes every token its own flush, which is exactly the
+    emit shape they were written against.  Batching cadence itself
+    (window/size coalescing, pending-batch visibility, flush-before-
+    non-token ordering) is pinned in ``test_sse_token_batching.py``.
+    """
+
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
+
+
 # ---------------------------------------------------------------------------
 # Listener fan-out
 # ---------------------------------------------------------------------------

tests/test_session_worker.py

@@ -2,7 +2,7 @@
 
 The shared worker dispatch is load-bearing for both the interactive
 ``/v1/api/workstreams/{ws_id}/send`` HTTP handler and the coordinator
-``CoordinatorAdapter.send`` path. Tests cover the four invariants the
+``CoordinatorAdapter.send`` path. Tests cover the five invariants the
 module must hold:
 
 * live worker → enqueue, no thread spawn
@@ -10,10 +10,14 @@ module must hold:
 * concurrent ``send`` calls produce exactly one worker thread
   (Stage 1 bug-1 — the racy ``Thread.is_alive()`` gate stays caught)
 * ``_worker_running`` cleared in ``finally`` even on uncaught exception
+* ownership-clear wake backstop: a worker exiting with USER_DRAIN
+  nudges queued on an IDLE workstream spawns the wake send that the
+  IDLE fan-out (which ran on this worker's own thread) had to drop
 
-Callers pass no-arg closures, so this module never touches
-``ws.session`` — keeps the contract narrow and lets watch-style
-dispatchers drive a session that isn't installed on ``ws``.
+Callers pass no-arg closures, so dispatch never touches ``ws.session``;
+the exit backstop only PEEKS it defensively (``getattr`` for
+``_nudge_queue``, bail on stubs) — watch-style dispatchers can still
+drive a session that isn't installed on ``ws``.
 """
 
 from __future__ import annotations
@@ -22,8 +26,10 @@ import queue
 import threading
 from typing import Any
 
+from tests._helpers import wait_until as _wait_until
 from turnstone.core import session_worker
-from turnstone.core.workstream import Workstream
+from turnstone.core.nudge_queue import USER_DRAIN, NudgeQueue
+from turnstone.core.workstream import Workstream, WorkstreamState
 
 
 class _SendSession:
@@ -140,6 +146,41 @@ def test_enqueue_unexpected_exception_returns_false_logged() -> None:
     assert ws._worker_running is True
 
 
+def test_closed_workstream_refused_no_spawn() -> None:
+    """Authoritative closed-check: ``close()`` sets ``_closed`` under
+    ``ws._lock``, so a wake (or send) racing it must be refused HERE —
+    the wake gate's lockless peek can go stale, and a spawn past this
+    point would run a full unattended turn (inference, tool calls,
+    storage writes) on a workstream whose ``ws_closed`` already fired.
+    """
+    session = _SendSession()
+    ws = _make_ws(session)
+    ws._closed = True
+
+    ok = _send_message(ws, session, "hello")
+
+    assert ok is False
+    assert session.send_calls == []
+    assert session.queue_calls == []
+    assert ws.worker_thread is None
+    assert ws._worker_running is False
+
+
+def test_closed_workstream_refused_on_reuse_path_too() -> None:
+    """The refusal precedes the enqueue branch: no interjection is queued
+    onto a session whose workstream is already closed."""
+    session = _SendSession()
+    ws = _make_ws(session)
+    ws._worker_running = True
+    ws._closed = True
+
+    ok = _send_message(ws, session, "hello")
+
+    assert ok is False
+    assert session.queue_calls == []
+    assert ws._worker_running is True  # untouched — not ours to clear
+
+
 # ---------------------------------------------------------------------------
 # _worker_running lifecycle
 # ---------------------------------------------------------------------------
@@ -301,6 +342,141 @@ def test_thread_name_explicit_override() -> None:
     ws.worker_thread.join(timeout=2.0)
 
 
+class _WakeCapableSession(_SendSession):
+    """Adds the ChatSession surface the exit backstop peeks at."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._nudge_queue = NudgeQueue()
+        self.deliver_calls = 0
+        self.deliver_thread_names: list[str] = []
+        self.delivered = threading.Event()
+
+    def deliver_wake_nudge_from_queue(self) -> None:
+        # Mirror the real contract: the wake drains its own queue, so
+        # the wake worker's OWN exit backstop sees nothing pending and
+        # the chain converges instead of spawning wakes forever.
+        self.deliver_calls += 1
+        self.deliver_thread_names.append(threading.current_thread().name)
+        self._nudge_queue.drain(USER_DRAIN)
+        self.delivered.set()
+
+
+class TestWorkerExitWakeBackstop:
+    """A worker exiting while its (idle) workstream has USER_DRAIN
+    nudges queued spawns the wake send the IDLE fan-out had to drop.
+
+    Production shape being modelled: ``set_state(IDLE)`` fires its
+    subscribers on the worker thread from inside ``run()`` —
+    ``CoordinatorIdleObserver`` enqueues ``idle_children``, then
+    ``IdleNudgeWatcher``'s wake dispatch lands on the reuse path
+    (this very worker still owns the flag) and no-ops.  The enqueue
+    inside ``run`` below stands in for that observer enqueue.
+    """
+
+    def test_worker_exit_delivers_pending_wake(self) -> None:
+        session = _WakeCapableSession()
+        ws = _make_ws(session)
+        assert ws.state is WorkstreamState.IDLE  # dataclass default
+
+        def run() -> None:
+            # What the IDLE fan-out's observer does, on this thread.
+            session._nudge_queue.enqueue("idle_children", "kids waiting", "any")
+
+        ok = session_worker.send(ws, enqueue=lambda: None, run=run)
+        assert ok is True
+
+        # The wake is delivered on a fresh wake-named worker thread…
+        assert session.delivered.wait(timeout=2.0), (
+            "exit backstop did not deliver the pending nudge"
+        )
+        assert session.deliver_thread_names[0].startswith("wake-nudge-")
+        # …after which the wake worker's own exit backstop sees an empty
+        # queue and the chain converges: flag at rest, exactly one deliver.
+        _wait_until(lambda: ws._worker_running is False)
+        assert session.deliver_calls == 1
+        assert len(session._nudge_queue) == 0
+
+    def test_worker_exit_no_wake_when_queue_empty(self) -> None:
+        session = _WakeCapableSession()
+        ws = _make_ws(session)
+
+        ok = session_worker.send(ws, enqueue=lambda: None, run=lambda: None)
+        assert ok is True
+        original = ws.worker_thread
+        assert original is not None
+        original.join(timeout=2.0)
+
+        assert ws.worker_thread is original  # no wake spawned
+        assert session.deliver_calls == 0
+        assert ws._worker_running is False
+
+    def test_worker_exit_no_wake_for_stub_session_without_queue(self) -> None:
+        """The narrow-contract escape hatch: a session without a
+        ``_nudge_queue`` (watch-style stubs) is skipped by the shared
+        wake gate's own defensive peek — no AttributeError, no wake."""
+        session = _SendSession()
+        ws = _make_ws(session)
+
+        ok = _send_message(ws, session, "hello")
+        assert ok is True
+        original = ws.worker_thread
+        assert original is not None
+        original.join(timeout=2.0)
+
+        assert ws.worker_thread is original
+        assert ws._worker_running is False
+
+    def test_worker_exit_no_wake_when_state_not_idle(self) -> None:
+        """An ERROR exit stays parked for the operator — pending nudges
+        wait for the next real interaction rather than burning
+        unattended inference on a failed session."""
+        session = _WakeCapableSession()
+        ws = _make_ws(session)
+
+        def run() -> None:
+            session._nudge_queue.enqueue("idle_children", "kids waiting", "any")
+            ws.state = WorkstreamState.ERROR
+
+        ok = session_worker.send(ws, enqueue=lambda: None, run=run)
+        assert ok is True
+        original = ws.worker_thread
+        assert original is not None
+        original.join(timeout=2.0)
+
+        assert ws.worker_thread is original
+        assert session.deliver_calls == 0
+        assert len(session._nudge_queue) == 1  # still queued for later seams
+
+    def test_abandoned_worker_does_not_run_wake_backstop(self) -> None:
+        """Only the owner retries: an abandoned worker (successor claimed
+        the flag) finishing late must not spawn a wake — the successor's
+        own exit runs the backstop."""
+        send_gate = threading.Event()
+        session = _WakeCapableSession(send_gate=send_gate)
+        ws = _make_ws(session)
+
+        ok = _send_message(ws, session, "hello")
+        assert ok is True
+        abandoned = ws.worker_thread
+        assert abandoned is not None
+
+        session._nudge_queue.enqueue("idle_children", "kids waiting", "any")
+        sentinel = threading.Thread(target=lambda: None, name="successor")
+        with ws._lock:
+            ws.worker_thread = sentinel
+            ws._worker_running = True
+
+        send_gate.set()
+        abandoned.join(timeout=3.0)
+        assert not abandoned.is_alive()
+
+        # No wake spawned by the abandoned thread; ownership intact.
+        assert ws.worker_thread is sentinel
+        assert session.deliver_calls == 0
+        assert ws._worker_running is True
+
+
 def test_does_not_deadlock_when_run_briefly_grabs_ws_lock() -> None:
     """Sanity check: ``run`` is invoked OUTSIDE ``ws._lock``. A worker
     body that briefly takes the lock (e.g. to update worker state)

tests/test_shell_js.py

@@ -49,6 +49,7 @@ _ESM_BUNDLES = [
     _SHARED / "composer_queue.js",
     _SHARED / "interactive.js",
     _SHARED / "conversation.js",
+    _SHARED / "preview.js",
     _SHARED / "redact_credentials.js",
 ]
 
@@ -69,6 +70,7 @@ _ESM_NO_VAR_BUNDLES = [
     _SHARED / "auth.js",
     _SHARED / "interactive.js",
     _SHARED / "conversation.js",
+    _SHARED / "preview.js",
     _SHARED / "redact_credentials.js",
 ]
 
@@ -864,16 +866,20 @@ def test_pane_manager_split_engine() -> None:
     assert "_restoreLayout(data)" in pane and "seen.has(d.paneId)" in pane
     # the visible-but-unfocused tab marker
     assert 'classList.toggle("shown"' in pane
-    # per-pane ✕: split mode hides ONE cell keeping the tab (closeCell);
-    # single-pane it closes the pane (withheld from non-closable) — the click
-    # decides at click time, the label tracks the mode.  Manager-injected into
-    # the pane SECTION (content untouched), removed via _clearCellStyle.
+    # per-pane ✕: split mode hides ONE cell keeping the tab (closeCell), EXCEPT
+    # an ephemeral pane which closes outright; single-pane it closes the pane
+    # (withheld from non-closable) — the click decides at click time, the label
+    # tracks the mode.  Manager-injected into the pane SECTION (content
+    # untouched), removed via _clearCellStyle.  Ephemeral-dismiss behaviour has
+    # its own deep coverage in test_preview_js.py::TestEphemeralDismiss.
     assert "closeCell(paneId)" in pane and "_refreshCellChips()" in pane
     assert 'b.className = "cell-unsplit"' in pane
     assert '"Close pane"' in pane, "the single-pane chip mode"
     # mode-DISTINCT glyphs (designer P1: identical signifier + locus with a
-    # reversible/destructive divergence is a mode-error trap)
-    assert 'b.textContent = multi ? "−" : "✕"' in pane
+    # reversible/destructive divergence is a mode-error trap) — a click that
+    # cannot be a reversible cell-hide shows ✕, else −.
+    assert "const destroys = !multi || pane.ephemeral;" in pane
+    assert 'b.textContent = destroys ? "✕" : "−"' in pane
     assert '"cell-unsplit--close"' in pane
     assert "this._removeCellChip(pane)" in pane
     # open-beside: the coordinator child-link placement (split right of the

tests/test_sse_overflow_js.py

@@ -0,0 +1,140 @@
+"""Static + runtime guards for the shared SSE overflow-recovery helper.
+
+``turnstone/shared_static/sse_overflow.js`` is the client half of the SSE
+overflow recovery — the storm-guard threshold, the cooldown-ladder constants,
+and the two pure helpers (``overflowWindowTripped`` / ``degradedCooldownStep``)
+— extracted so BOTH the interactive pane (``shared_static/interactive.js``) and
+the coordinator pane (``console/static/coordinator/coordinator.js``) share one
+source of truth for the trip math instead of drifting copies.  The panes keep
+their own transport/DOM glue; only the pure core lives here.
+
+Like the rest of the WebUI the module has no JS test framework, so these are
+Python-side string-presence assertions plus two ``node`` runtime probes that
+execute the extracted pure functions — the storm-guard math is the part the
+design review marked UNCONFIRMED, so it gets run, not just string-pinned.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pytest
+
+_ROOT = Path(__file__).resolve().parent.parent
+_SSE_OVERFLOW = _ROOT / "turnstone/shared_static/sse_overflow.js"
+
+
+def test_module_exports_constants_and_pure_helpers() -> None:
+    """The single source of truth exports the five tuning constants and the two
+    pure helpers.  Both panes import these by name (pinned in their own suites),
+    so a rename here is a breaking change that must surface loudly."""
+    body = _SSE_OVERFLOW.read_text(encoding="utf-8")
+    for const, value in (
+        ("OVERFLOW_TRIP_COUNT", "3"),
+        ("OVERFLOW_TRIP_WINDOW_MS", "60000"),
+        ("DEGRADED_COOLDOWN_BASE_MS", "15000"),
+        ("DEGRADED_COOLDOWN_MAX_MS", "120000"),
+        ("DEGRADED_COOLDOWN_RESET_MS", "300000"),
+    ):
+        assert f"export const {const} = {value};" in body, f"missing export const {const}"
+    assert "export function overflowWindowTripped(" in body
+    assert "export function degradedCooldownStep(" in body
+
+
+def test_overflow_window_tripped_runtime() -> None:
+    """Runtime probe for the limiter's rolling-window helper — the storm-guard
+    math is the part of Fix A the design review marked UNCONFIRMED, so it gets
+    executed, not just string-pinned: prunes stale entries in place, trips at
+    exactly K-in-window, and does not trip for closes spread wider than the
+    window."""
+    body = _SSE_OVERFLOW.read_text(encoding="utf-8")
+    m = re.search(
+        r"^export function overflowWindowTripped\(times, nowMs, count, windowMs\) \{.*?^\}",
+        body,
+        re.S | re.M,
+    )
+    assert m is not None, "overflowWindowTripped not found (keep it a module-level export)"
+    harness = (
+        m.group(0)
+        + "\n"
+        + "// trips at exactly count-in-window\n"
+        + "let t = [1000, 2000, 3000];\n"
+        + "if (!overflowWindowTripped(t, 3000, 3, 60000)) throw new Error('K-in-window must trip');\n"
+        + "// stale entries prune in place and prevent the trip\n"
+        + "t = [1000, 2000, 70000];\n"
+        + "if (overflowWindowTripped(t, 70000, 3, 60000)) throw new Error('stale entries must not trip');\n"
+        + "if (JSON.stringify(t) !== '[70000]') throw new Error('prune in place failed: ' + JSON.stringify(t));\n"
+        + "// boundary: an entry exactly windowMs old is still counted\n"
+        + "t = [10000, 70000];\n"
+        + "if (!overflowWindowTripped(t, 70000, 2, 60000)) throw new Error('boundary entry must count');\n"
+        + "// below threshold never trips\n"
+        + "t = [];\n"
+        + "if (overflowWindowTripped(t, 1, 1, 60000) !== false) throw new Error('empty must not trip');\n"
+    )
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".mjs", delete=False) as f:
+        f.write(harness)
+        tmp = f.name
+    try:
+        proc = subprocess.run(["node", tmp], capture_output=True, text=True, timeout=15)
+    except FileNotFoundError:
+        pytest.skip("node binary not available on PATH")
+    finally:
+        os.unlink(tmp)
+    assert proc.returncode == 0, (
+        f"overflowWindowTripped runtime probe failed. stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    )
+
+
+def test_degraded_cooldown_ladder_escalates_and_resets_runtime() -> None:
+    """Review finding [0] regression: the degraded-catchup cooldown ladder must
+    actually ESCALATE across consecutive trips (15→30→60→120s, capped) and reset
+    to base only after a genuine quiet gap.  The original bug cleared the
+    overflow-window array in the trip handler, so the empty-window check reset
+    the cooldown to base on every storm's first overflow and the doubling never
+    took effect.  The fix keys the ladder off a last-trip timestamp via the pure
+    degradedCooldownStep helper, exercised here directly."""
+    body = _SSE_OVERFLOW.read_text(encoding="utf-8")
+    m = re.search(
+        r"^export function degradedCooldownStep\(.*?\) \{.*?^\}",
+        body,
+        re.S | re.M,
+    )
+    assert m is not None, "degradedCooldownStep not found (keep it a module-level export)"
+    harness = (
+        m.group(0)
+        + "\n"
+        + "const BASE=15000, MAX=120000, RESET=300000;\n"
+        + "function assert(c,msg){ if(!c) throw new Error(msg); }\n"
+        + "// First trip: gap since lastTrip(0) exceeds RESET -> base, next doubles.\n"
+        + "let s = degradedCooldownStep(BASE, 0, 1000000, BASE, MAX, RESET);\n"
+        + "assert(s.cooldown===15000, 'first trip cooldown '+s.cooldown);\n"
+        + "assert(s.nextCooldownMs===30000, 'first next '+s.nextCooldownMs);\n"
+        + "// Second trip recurs within RESET -> escalates (uses the doubled prev).\n"
+        + "s = degradedCooldownStep(30000, 1000000, 1030000, BASE, MAX, RESET);\n"
+        + "assert(s.cooldown===30000, 'second trip must ESCALATE not reset, got '+s.cooldown);\n"
+        + "assert(s.nextCooldownMs===60000, 'second next '+s.nextCooldownMs);\n"
+        + "// Third + fourth keep escalating and cap at MAX.\n"
+        + "s = degradedCooldownStep(60000, 1030000, 1060000, BASE, MAX, RESET);\n"
+        + "assert(s.cooldown===60000 && s.nextCooldownMs===120000, 'third '+JSON.stringify(s));\n"
+        + "s = degradedCooldownStep(120000, 1060000, 1090000, BASE, MAX, RESET);\n"
+        + "assert(s.cooldown===120000 && s.nextCooldownMs===120000, 'fourth must cap at MAX '+JSON.stringify(s));\n"
+        + "// A quiet gap longer than RESET resets the ladder to base.\n"
+        + "s = degradedCooldownStep(120000, 1090000, 1090000+RESET+1, BASE, MAX, RESET);\n"
+        + "assert(s.cooldown===15000, 'quiet gap must reset to base, got '+s.cooldown);\n"
+    )
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".mjs", delete=False) as f:
+        f.write(harness)
+        tmp = f.name
+    try:
+        proc = subprocess.run(["node", tmp], capture_output=True, text=True, timeout=15)
+    except FileNotFoundError:
+        pytest.skip("node binary not available on PATH")
+    finally:
+        os.unlink(tmp)
+    assert proc.returncode == 0, (
+        f"degradedCooldownStep escalation probe failed. stderr={proc.stderr!r}"
+    )

tests/test_sse_reconnect_replay.py

@@ -20,6 +20,7 @@ The browser-side guard for the ``onerror`` close pattern lives in
 from __future__ import annotations
 
 import asyncio
+import queue
 import threading
 from types import SimpleNamespace as SimpleNS
 from typing import Any
@@ -199,17 +200,17 @@ def test_event_id_monotonic_under_concurrent_writers() -> None:
 
 
 def test_event_id_does_not_skip_when_listener_queue_full() -> None:
-    """If a slow listener's queue is full, the per-listener
-    ``put_nowait`` is silently dropped — but the counter must NOT
-    skip.  A subsequently-registered listener with
-    ``Last-Event-ID=0`` must see ALL the ids from the buffer
-    (1..N), not a sparse subset.  Pre-bug-class: moving the
-    id-increment inside the per-listener loop would create phantom
-    "gaps" the truncation detector would misread."""
+    """If a slow listener's queue is full, the per-listener put is
+    rejected (the first rejection poisons the listener; later ones are
+    latch refusals) — but the counter must NOT skip.  A subsequently-
+    registered listener with ``Last-Event-ID=0`` must see ALL the ids
+    from the buffer (1..N), not a sparse subset.  Pre-bug-class:
+    moving the id-increment inside the per-listener loop would create
+    phantom "gaps" the truncation detector would misread."""
     ui = _make_ui()
     slow_lq = ui._register_listener(maxsize=1)
     slow_lq.put_nowait({"placeholder": True})  # full immediately
-    # Fire 10 events — 9 will hit queue.Full and be suppressed.
+    # Fire 10 events — none can land in the full/poisoned queue.
     for i in range(10):
         ui._enqueue({"type": "tool_started", "name": f"t{i}"})
     # Replay from id=0 — fresh listener gets all 10, ids 1..10 dense.
@@ -261,12 +262,17 @@ def test_cross_thread_writer_and_replay_observer_consistent() -> None:
         )
 
 
-def test_event_id_persists_across_turn_boundaries() -> None:
+def test_event_id_persists_across_turn_boundaries(monkeypatch: Any) -> None:
     """Resetting ``_event_id`` to 0 at turn boundaries would silently
     mis-replay a long-lived SSE subscriber whose ``Last-Event-ID``
     was from a prior turn.  Mirrors the pre-existing
     ``test_inflight_seq_monotonic_across_turn_boundaries`` invariant
-    on the snap_seq side, extended to the buffer/replay side."""
+    on the snap_seq side, extended to the buffer/replay side.
+
+    Batch window forced to 0 (per-token flush) — this test pins id
+    numbering across turn boundaries, not the batching cadence."""
+
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
     ui = _make_ui()
     ui.on_content_token("turn-N tok1 ")
     ui.on_content_token("turn-N tok2 ")
@@ -305,7 +311,7 @@ def test_replay_ok_skips_in_progress_snapshot_path() -> None:
     assert snap["seq"] >= 1
 
 
-def test_truncated_path_snapshot_captures_real_snap_seq() -> None:
+def test_truncated_path_snapshot_captures_real_snap_seq(monkeypatch: Any) -> None:
     """Regression for PR #542 review comment 1 (Copilot, low-confidence).
 
     On the truncated path the caller used to set ``snap_seq=0``, which
@@ -321,9 +327,13 @@ def test_truncated_path_snapshot_captures_real_snap_seq() -> None:
     ``register_listener_with_replay`` under the same nested-lock
     acquire as the listener registration + buffer slice + counter
     read, so ``snap_seq`` returned in the snapshot is the exact
-    high-water mark the snapshot text corresponds to."""
+    high-water mark the snapshot text corresponds to.
+
+    Batch window forced to 0 so each token is its own ring entry —
+    the truncation scenario needs 10 distinct buffered events."""
     import collections
 
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
     ui = _make_ui()
     ui._event_buffer = collections.deque(maxlen=3)
     # Fire enough events to trigger truncation on reconnect with a
@@ -362,15 +372,15 @@ def test_snap_seq_high_water_mark_holds_under_writer_race() -> None:
     double-render.
 
     The race window in plain Python is narrow (a few bytecodes
-    between lock release and the ``_enqueue`` call), so a pure
-    barrier-based race rarely hits it.  This test injects a
-    deterministic sleep into ``_enqueue`` via monkey-patch to
-    widen the window enough to be reliably observed under the
-    pre-fix code path — AND to be reliably AVOIDED under the
-    post-fix code path (because the post-fix
-    ``on_content_token`` calls ``_enqueue`` while still holding
-    ``_ws_lock``, so the snapshot reader can't acquire
-    ``_ws_lock`` until the writer is fully done).
+    between lock release and the emit call), so a pure barrier-based
+    race rarely hits it.  This test injects a deterministic sleep
+    into ``_enqueue_direct`` — the inner emit point the token
+    batcher's flush calls under ``_ws_lock`` — to widen the window
+    enough to be reliably observed if the flush's inflight-append
+    and enqueue are ever split across ``_ws_lock`` sections, AND to
+    be reliably AVOIDED under the correct code path (the flush holds
+    ``_ws_lock`` across both, so the snapshot reader can't acquire
+    it until the writer is fully done).
     """
     import queue
     import threading
@@ -378,20 +388,20 @@ def test_snap_seq_high_water_mark_holds_under_writer_race() -> None:
 
     ui = _make_ui()
     marker = "RACE-MARKER"
-    original_enqueue = ui._enqueue
+    original_direct = ui._enqueue_direct
 
-    # Widen the race window: sleep just BEFORE the original
-    # ``_enqueue`` runs (which is where ``_event_id`` would advance).
-    # Post-fix this sleep happens while the writer still holds
-    # ``_ws_lock`` — readers block.  Pre-fix the writer has
-    # released ``_ws_lock`` before reaching this monkey-patch, so
-    # the reader gets a clean window to capture an inconsistent
-    # ``(inflight, _event_id)`` pair.
-    def slow_enqueue(data: dict[str, Any]) -> None:
+    # Widen the race window: sleep just BEFORE the inner emit runs
+    # (which is where ``_event_id`` advances).  Under the correct
+    # locking this sleep happens while the writer still holds
+    # ``_ws_lock`` — readers block.  If the flush ever releases
+    # ``_ws_lock`` before its enqueue, the reader gets a clean
+    # window to capture an inconsistent ``(inflight, _event_id)``
+    # pair and the invariant below trips.
+    def slow_direct(data: dict[str, Any]) -> int:
         time.sleep(0.05)  # 50 ms — orders of magnitude wider than the GIL switch interval
-        return original_enqueue(data)
+        return original_direct(data)
 
-    ui._enqueue = slow_enqueue  # type: ignore[method-assign]
+    ui._enqueue_direct = slow_direct  # type: ignore[method-assign]
 
     snap_box: dict[str, Any] = {}
     writer_done = threading.Event()
@@ -572,10 +582,15 @@ def test_handler_emits_retry_on_first_yield() -> None:
     assert 2500 <= retry <= 4500, f"retry {retry} outside jitter band [2500, 4500]"
 
 
-def test_handler_replay_ok_skips_snapshot_emits_id() -> None:
+def test_handler_replay_ok_skips_snapshot_emits_id(monkeypatch: Any) -> None:
     """``Last-Event-ID`` + buffer covers gap → emit buffered events
     with SSE ``id:`` field, SKIP the in-progress snapshot (it would
-    double-render content the buffered events already carry)."""
+    double-render content the buffered events already carry).
+
+    Batch window forced to 0 so the two tokens are two ring entries
+    (the assertion wants two distinct ``id:`` lines)."""
+
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
     ui = _make_ui()
     ui.on_content_token("hello ")
     ui.on_content_token("world")
@@ -590,13 +605,17 @@ def test_handler_replay_ok_skips_snapshot_emits_id() -> None:
     assert "id: 2" in blob, f"missing id: 2 in:\n{blob}"
 
 
-def test_handler_truncated_emits_envelope_then_snapshot() -> None:
+def test_handler_truncated_emits_envelope_then_snapshot(monkeypatch: Any) -> None:
     """Stale ``Last-Event-ID`` + buffer too short → emit
     ``replay_truncated`` envelope, THEN fall through to the
     fresh-style replay (state_change + in_progress_snapshot) as the
-    recovery floor."""
+    recovery floor.
+
+    Batch window forced to 0 so each token is its own ring entry —
+    the truncation scenario needs the deque to evict."""
     import collections
 
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
     ui = _make_ui()
     ui._event_buffer = collections.deque(maxlen=3)
     for i in range(10):
@@ -717,3 +736,382 @@ def test_handler_replay_ok_does_not_resurface_last_error(monkeypatch: Any) -> No
     ui.on_content_token("hi")  # one buffered event so Last-Event-ID=0 → replay_ok
     _, blob = _drain_handler_yields(ui, headers={"Last-Event-ID": "0"}, state="error", max_yields=8)
     assert "boom" not in blob
+
+
+# ---------------------------------------------------------------------------
+# Poison-on-overflow (Fix A) — queue.Full stops being a silent drop
+# ---------------------------------------------------------------------------
+#
+# Silent per-listener drops at queue.Full left permanent holes BELOW the
+# client's advancing lastEventId (scattered interleaved drops once the
+# queue saturates), which reconnect-with-replay can never heal (the slice
+# is ``eid > last_event_id`` only).  The listener queue now latches
+# ``poisoned`` atomically at the FIRST rejected put and refuses every
+# later put, freezing its contents as a contiguous prefix; the drain
+# loop closes the stream (after an id-less ``stream_overflow`` frame)
+# and the native EventSource reconnect replays the contiguous tail.
+#
+# Poisoning at the first full (not after N) is load-bearing: any
+# delivered-while-dropping window advances lastEventId past interior
+# holes -> permanent gap even after a "successful" reconnect.
+
+
+def _fake_live_request(*, path_params: dict[str, str] | None = None) -> Request:
+    """A request whose ``receive()`` never resolves, so
+    ``is_disconnected()`` stays ``False`` — the poison check, not
+    disconnect detection, must be what terminates the drain loop."""
+    scope = {
+        "type": "http",
+        "method": "GET",
+        "headers": [],
+        "path": "/events",
+        "raw_path": b"/events",
+        "query_string": b"",
+        "path_params": path_params or {},
+        "app": MagicMock(),
+    }
+
+    async def _recv() -> dict[str, Any]:
+        await asyncio.Event().wait()  # pends forever
+        return {"type": "http.disconnect"}  # unreachable
+
+    return Request(scope, receive=_recv)
+
+
+def test_listener_queue_poisons_at_first_full_and_refuses_after() -> None:
+    """The first rejected put latches ``poisoned`` (atomically, under
+    the queue's own mutex) and every later put is refused even if the
+    consumer frees slots — otherwise a racing consumer pop would let a
+    later event land BEHIND the hole and the drain would deliver past
+    it, advancing lastEventId beyond an unreplayable gap."""
+    ui = _make_ui()
+    lq = ui._register_listener(maxsize=2)
+    ui._enqueue({"type": "a"})
+    ui._enqueue({"type": "b"})
+    assert getattr(lq, "poisoned", None) is False
+    ui._enqueue({"type": "c"})  # first overflow -> latch
+    assert lq.poisoned is True
+    lq.get_nowait()  # consumer frees a slot
+    ui._enqueue({"type": "d"})  # must be refused — queue contents frozen
+    leftover = []
+    while True:
+        try:
+            leftover.append(lq.get_nowait())
+        except queue.Empty:
+            break
+    assert [ev["type"] for ev in leftover] == ["b"], (
+        "a post-poison put landed in the freed slot — interior hole"
+    )
+    # The ring is untouched by listener poisoning: ids stay dense.
+    _, replay, status, _, _, _ = ui.register_listener_with_replay(0)
+    assert status == "replay_ok"
+    assert [ev["_event_id"] for ev in replay] == [1, 2, 3, 4]
+
+
+def test_poisoned_gap_is_contiguous_tail_fully_replayable() -> None:
+    """Recovery math at the poison instant: delivered ids form a
+    contiguous prefix, the ring holds everything, and a reconnect with
+    ``Last-Event-ID = <last delivered>`` replays exactly the missing
+    tail — no duplicate, no loss, no off-by-one."""
+    ui = _make_ui()
+    lq = ui._register_listener(maxsize=3)
+    for i in range(5):
+        ui._enqueue({"type": "tool_started", "name": f"t{i}"})
+    # Queue froze at [1,2,3]; 4 latched poison; 5 was refused.
+    delivered = []
+    while True:
+        try:
+            delivered.append(lq.get_nowait()["_event_id"])
+        except queue.Empty:
+            break
+    assert delivered == [1, 2, 3]
+    _, replay, status, lost, _, _ = ui.register_listener_with_replay(delivered[-1])
+    assert status == "replay_ok"
+    assert lost == 0
+    assert [ev["_event_id"] for ev in replay] == [4, 5]
+    assert delivered + [ev["_event_id"] for ev in replay] == [1, 2, 3, 4, 5]
+
+
+def test_poison_isolated_to_slow_listener() -> None:
+    """One slow tab must not degrade its siblings: the healthy listener
+    keeps receiving every event after the slow one is poisoned (and the
+    poisoned one stops consuming fan-out puts entirely)."""
+    ui = _make_ui()
+    slow = ui._register_listener(maxsize=1)
+    healthy = ui._register_listener(maxsize=100)
+    for i in range(6):
+        ui._enqueue({"type": "tool_started", "name": f"t{i}"})
+    assert slow.poisoned is True
+    got = []
+    while True:
+        try:
+            got.append(healthy.get_nowait()["name"])
+        except queue.Empty:
+            break
+    assert got == [f"t{i}" for i in range(6)]
+
+
+def test_drain_loop_closes_with_overflow_frame_on_poison() -> None:
+    """Once its queue is poisoned the drain loop must terminate the SSE
+    response — discarding the queued backlog (the replay covers it) —
+    after yielding a final id-less ``stream_overflow`` frame so the
+    client can count overflow closes (reconnect-limiter + the
+    drop-vs-render-wedge field instrumentation) without advancing
+    ``lastEventId`` past the gap."""
+    from turnstone.core.session_ui_base import _DEFAULT_LISTENER_QUEUE_MAX
+
+    ui = _make_ui()
+    handler = _wire_events_handler(ui)
+    req = _fake_live_request(path_params={"ws_id": ui.ws_id})
+
+    async def _run() -> list[Any]:
+        resp = await handler(req)
+        agen = resp.body_iterator
+        yields = [await agen.__anext__()]  # retry frame
+        yields.append(await agen.__anext__())  # synthetic state_change
+        # Overflow the registered listener's queue: cap fills, +1 poisons.
+        for i in range(_DEFAULT_LISTENER_QUEUE_MAX + 1):
+            ui._enqueue({"type": "info", "message": f"m{i}"})
+        yields.append(await agen.__anext__())  # overflow frame, then close
+        try:
+            extra = await agen.__anext__()
+        except StopAsyncIteration:
+            extra = None
+        yields.append(extra)
+        return yields
+
+    yields = asyncio.run(_run())
+    assert yields[-1] is None, "drain loop kept yielding after poison"
+    overflow = yields[-2]
+    assert isinstance(overflow, dict)
+    assert "stream_overflow" in overflow["data"]
+    assert "id" not in overflow, (
+        "the overflow frame must not carry an SSE id — advancing "
+        "lastEventId here would strand the dropped gap below the cursor"
+    )
+    # The 500-event backlog was discarded, not delivered: nothing
+    # between the synthetic replay and the overflow frame.
+    assert all("m0" not in str(y) for y in yields)
+
+
+def test_drain_loop_delivers_until_poison_then_stops_before_backlog() -> None:
+    """Pre-poison delivery works normally; at poison the loop closes
+    BEFORE delivering the queued backlog (check precedes the blocking
+    get), so the client's lastEventId freezes at the contiguous prefix
+    and reconnect replays everything else."""
+    from turnstone.core.session_ui_base import _DEFAULT_LISTENER_QUEUE_MAX
+
+    ui = _make_ui()
+    handler = _wire_events_handler(ui)
+    req = _fake_live_request(path_params={"ws_id": ui.ws_id})
+
+    async def _run() -> tuple[list[Any], Any, Any]:
+        resp = await handler(req)
+        agen = resp.body_iterator
+        head = [await agen.__anext__(), await agen.__anext__()]  # retry + state
+        ui._enqueue({"type": "info", "message": "live-1"})
+        live = await agen.__anext__()
+        for i in range(_DEFAULT_LISTENER_QUEUE_MAX + 1):
+            ui._enqueue({"type": "info", "message": f"m{i}"})
+        tail = await agen.__anext__()
+        try:
+            await agen.__anext__()
+            closed = False
+        except StopAsyncIteration:
+            closed = True
+        return head, live, (tail, closed)
+
+    _, live, (tail, closed) = asyncio.run(_run())
+    assert "live-1" in live["data"]
+    assert "stream_overflow" in tail["data"]
+    assert closed, "generator must return right after the overflow frame"
+
+
+def test_overflow_reconnect_replays_full_gap_through_handler() -> None:
+    """End-to-end recovery shape: after an overflow close, a reconnect
+    carrying the pre-poison ``Last-Event-ID`` replays the whole gap via
+    ``replay_ok`` — the poisoned stream lost nothing durable."""
+    ui = _make_ui()
+    lq = ui._register_listener(maxsize=3)
+    for i in range(5):
+        ui._enqueue({"type": "tool_started", "name": f"t{i}"})
+    delivered_ids = []
+    while True:
+        try:
+            delivered_ids.append(lq.get_nowait()["_event_id"])
+        except queue.Empty:
+            break
+    ui._unregister_listener(lq)  # what the drain loop's finally does
+    _, blob = _drain_handler_yields(
+        ui, headers={"Last-Event-ID": str(delivered_ids[-1])}, max_yields=6
+    )
+    assert "replay_truncated" not in blob
+    assert "t3" in blob
+    assert "t4" in blob
+
+
+def test_listener_queue_basic_put_get_semantics() -> None:
+    """Stdlib-drift canary for ``_ListenerQueue.put_nowait``'s
+    reimplementation against ``queue.Queue``'s documented extension
+    surface (``mutex`` / ``_qsize`` / ``_put`` / ``unfinished_tasks`` /
+    ``not_empty``): normal put/get round-trips work, FIFO order holds,
+    a blocked ``get(timeout=...)`` is woken by a put (the
+    ``not_empty.notify`` path the drain loop's executor get relies on),
+    and the poison latch engages exactly at the first rejected put."""
+    from turnstone.core.session_ui_base import _ListenerQueue
+
+    q = _ListenerQueue(maxsize=2)
+    q.put_nowait({"n": 1})
+    q.put_nowait({"n": 2})
+    assert q.qsize() == 2
+    try:
+        q.put_nowait({"n": 3})
+        raise AssertionError("third put must raise queue.Full")
+    except queue.Full:
+        pass
+    assert q.poisoned is True
+    assert q.get_nowait()["n"] == 1  # FIFO preserved
+    try:
+        q.put_nowait({"n": 4})
+        raise AssertionError("post-poison put must be refused")
+    except queue.Full:
+        pass
+    assert q.get_nowait()["n"] == 2
+
+    # A blocked get() must be woken by a concurrent put_nowait — the
+    # notify path the events handler's executor get depends on.
+    fresh = _ListenerQueue(maxsize=2)
+    got: list[dict[str, Any]] = []
+
+    def _getter() -> None:
+        got.append(fresh.get(timeout=5))
+
+    t = threading.Thread(target=_getter)
+    t.start()
+    fresh.put_nowait({"n": 42})
+    t.join(timeout=5)
+    assert not t.is_alive(), "get(timeout) never woke — not_empty.notify broken"
+    assert got == [{"n": 42}]
+
+
+def test_closing_queue_unwinds_clean_not_overflow_when_poisoned() -> None:
+    """Review finding [1]: a ws closing/evicting while a slow pane's
+    queue is full must unwind as a CLEAN close, not a false
+    ``stream_overflow``.  The poison latch rejects the in-band
+    ``ws_closed`` sentinel, so ``mark_closing`` carries the signal
+    out-of-band and the drain loop honours it BEFORE the poison check —
+    otherwise a clean close of a slow consumer is mis-reported as a
+    send-overflow (polluting the client's drop-vs-wedge counter and
+    tripping its reconnect limiter on a ws that is simply gone)."""
+    ui = _make_ui()
+    handler = _wire_events_handler(ui)
+    req = _fake_live_request(path_params={"ws_id": ui.ws_id})
+
+    async def _run() -> tuple[Any, bool]:
+        resp = await handler(req)
+        agen = resp.body_iterator
+        await agen.__anext__()  # retry frame
+        await agen.__anext__()  # synthetic state_change
+        # Overflow the listener queue so it poisons, exactly as a slow
+        # consumer would, THEN close the ws (evict/delete/close path).
+        from turnstone.core.session_ui_base import _DEFAULT_LISTENER_QUEUE_MAX
+
+        for i in range(_DEFAULT_LISTENER_QUEUE_MAX + 1):
+            ui._enqueue({"type": "info", "message": f"m{i}"})
+        assert ui._listeners, "listener should still be registered pre-close"
+        lq = ui._listeners[0]
+        assert lq.poisoned is True
+        # Simulate _broadcast_ws_closed_to_listeners' out-of-band flag.
+        lq.mark_closing()
+        try:
+            frame = await agen.__anext__()
+            closed = False
+        except StopAsyncIteration:
+            frame = None
+            closed = True
+        return frame, closed
+
+    frame, closed = asyncio.run(_run())
+    assert closed, "closing queue must end the stream"
+    assert frame is None, f"closing ws must NOT emit a stream_overflow frame; got {frame!r}"
+
+
+def test_broadcast_ws_closed_marks_closing_on_poisoned_queue() -> None:
+    """The teardown broadcaster must set the out-of-band ``closing``
+    flag even when the queue is poisoned/full (its in-band ``ws_closed``
+    put is refused by the poison latch).  Pins the wiring finding [1]
+    depends on: ``mark_closing`` is called for every listener."""
+    from turnstone.core.adapters._ui_cleanup import _broadcast_ws_closed_to_listeners
+
+    ui = _make_ui()
+    lq = ui._register_listener(maxsize=2)
+    ui._enqueue({"type": "a"})
+    ui._enqueue({"type": "b"})
+    ui._enqueue({"type": "c"})  # overflow -> poison
+    assert lq.poisoned is True
+    assert lq.closing is False
+    _broadcast_ws_closed_to_listeners(ui)
+    assert lq.closing is True, "teardown must flag the poisoned queue closing"
+    # Broadcaster clears the listener list (no re-fire on a closed ws).
+    assert ui._listeners == []
+
+
+def test_healthy_queue_close_still_delivers_ws_closed_sentinel() -> None:
+    """The out-of-band flag must not regress the normal path: a
+    non-full queue still receives the in-band ``ws_closed`` sentinel
+    (so a drain loop blocked in ``get`` wakes immediately) AND gets the
+    ``closing`` flag."""
+    from turnstone.core.adapters._ui_cleanup import _broadcast_ws_closed_to_listeners
+
+    ui = _make_ui()
+    lq = ui._register_listener(maxsize=100)
+    _broadcast_ws_closed_to_listeners(ui)
+    assert lq.closing is True
+    drained = []
+    while True:
+        try:
+            drained.append(lq.get_nowait())
+        except queue.Empty:
+            break
+    assert {ev["type"] for ev in drained} == {"ws_closed"}
+
+
+def test_healthy_closing_queue_drains_tail_before_close() -> None:
+    """Review round-2 finding [0]: a healthy (non-poisoned) client that is
+    momentarily behind must still receive its queued tail — the turn's
+    final content batch + ``stream_end`` — at ws teardown.  A close has no
+    reconnect+replay, so dropping that tail truncates the last assistant
+    message permanently.  The ``closing`` flag must therefore NOT
+    short-circuit the FIFO drain for a healthy queue (an earlier revision
+    checked it at the top of the loop and did exactly that); the in-band
+    ``ws_closed`` sentinel — which fits, the queue isn't full — closes the
+    stream AFTER the drain delivers everything."""
+    from turnstone.core.adapters._ui_cleanup import _broadcast_ws_closed_to_listeners
+
+    ui = _make_ui()
+    handler = _wire_events_handler(ui)
+    req = _fake_live_request(path_params={"ws_id": ui.ws_id})
+
+    async def _run() -> list[str]:
+        resp = await handler(req)
+        agen = resp.body_iterator
+        await agen.__anext__()  # retry frame
+        await agen.__anext__()  # synthetic state_change
+        # Enqueue the turn's tail into a HEALTHY (roomy) queue, then close
+        # the ws while those events are still undrained.
+        ui.on_content_token("final answer")
+        ui.on_stream_end()
+        _broadcast_ws_closed_to_listeners(ui)  # mark_closing + ws_closed sentinel
+        out: list[str] = []
+        while True:
+            try:
+                frame = await agen.__anext__()
+            except StopAsyncIteration:
+                break
+            out.append(frame["data"] if isinstance(frame, dict) else str(frame))
+        return out
+
+    blob = "\n".join(asyncio.run(_run()))
+    assert "final answer" in blob, "healthy closing queue dropped its content tail"
+    assert "stream_end" in blob, "healthy closing queue dropped stream_end"
+    assert "stream_overflow" not in blob, "a healthy close must not emit an overflow frame"

tests/test_sse_token_batching.py

@@ -0,0 +1,391 @@
+"""Emit-time micro-batching of content / reasoning tokens (SSE Fix B).
+
+At local-inference rates (500+ tok/s) the per-delta ``_enqueue`` was the
+load that overflowed listener queues (silent drops -> corrupted panes).
+:meth:`SessionUIBase.on_content_token` / :meth:`on_reasoning_token` now
+coalesce fragments over a small window and enqueue ONE event per batch.
+
+The two conditions that make batching safe are pinned here because each
+was a verified corruption mode in the design review:
+
+- **Condition 1 — atomic flush.**  The pending accumulator is invisible
+  to snapshot readers; the flush appends to the inflight buffers AND
+  enqueues the batched event inside one ``_ws_lock`` section, so
+  ``snap_seq`` stays a true high-water mark for the snapshot text.  If
+  inflight were appended per-token while enqueueing per-batch, a
+  snapshot straddling the batch would double-render (the batch arrives
+  with ``_seq > snap_seq`` carrying already-snapshotted text; the client
+  has no content dedup — its ``content`` case is a blind ``+=``).
+- **Condition 2 — every non-token emit flushes first.**  ``stream_end``
+  / ``tool_*`` / ``state_change`` bypass the batcher; if one overtook a
+  pending batch, the client would reset its streaming refs and the late
+  batch would paint into a NEW assistant bubble (the split/duplicate
+  look).  The flush lives at the top of ``_enqueue`` itself so every
+  emit path — base-class, subclass, and route-level — is covered.
+
+Negative-test discipline: the double-render tests fail if the flush's
+inflight-append + enqueue are split across ``_ws_lock`` sections, and
+the ordering tests fail if the ``_enqueue`` choke-point flush is
+removed — each was reverted-and-verified during development.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from typing import Any
+
+import pytest
+
+from turnstone.core.session_ui_base import _TOKEN_BATCH_WINDOW_SECS, SessionUIBase
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _ConcreteUI(SessionUIBase):
+    """Minimal concrete subclass for direct UI tests."""
+
+
+def _make_ui(ws_id: str = "ws-batch") -> _ConcreteUI:
+    return _ConcreteUI(ws_id=ws_id, user_id="u1")
+
+
+def _drain(lq: queue.Queue[dict[str, Any]]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    while True:
+        try:
+            out.append(lq.get_nowait())
+        except queue.Empty:
+            return out
+
+
+@pytest.fixture
+def wide_window(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Make the batch window effectively infinite so tests control the
+    flush points explicitly (via non-token emits / size cap) and a slow
+    CI machine can't turn one expected batch into two."""
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 60.0)
+
+
+# ---------------------------------------------------------------------------
+# Coalescing shape — one fresh id per batch, first fragment immediate
+# ---------------------------------------------------------------------------
+
+
+def test_fast_tokens_coalesce_into_single_batch_event(wide_window: None) -> None:
+    """N tokens inside one window -> the first flushes immediately (the
+    time-to-first-token protection), the rest coalesce into ONE enqueued
+    event whose text is the concatenation, carrying one fresh
+    ``_event_id`` / ``_seq``."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    for i in range(6):
+        ui.on_content_token(f"t{i}")
+    ui.on_stream_end()
+    events = _drain(lq)
+    content = [ev for ev in events if ev["type"] == "content"]
+    assert [ev["text"] for ev in content] == ["t0", "t1t2t3t4t5"]
+    # One fresh id per batch, and the token-event dedup tag rides it.
+    for ev in content:
+        assert isinstance(ev["_event_id"], int)
+        assert ev["_seq"] == ev["_event_id"]
+    # The batch is one ring entry too — ids stay dense (no reserved
+    # per-token ids leak into the ring numbering).
+    _, replay, status, _, _, _ = ui.register_listener_with_replay(0)
+    assert status == "replay_ok"
+    assert [ev["_event_id"] for ev in replay] == list(range(1, len(replay) + 1))
+
+
+def test_zero_window_flushes_every_token_individually(monkeypatch: pytest.MonkeyPatch) -> None:
+    """With the window forced to zero every token arrives past the
+    window boundary and flushes on its own — batching self-disables
+    with no behaviour change vs the pre-batching emit shape."""
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
+    ui = _make_ui()
+    lq = ui._register_listener()
+    for i in range(4):
+        ui.on_content_token(f"t{i}")
+    events = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert [ev["text"] for ev in events] == ["t0", "t1", "t2", "t3"]
+
+
+def test_slow_tokens_flush_individually_at_default_window() -> None:
+    """Tokens arriving slower than the real (unpatched) window each
+    flush individually — pins the constant's scale: a human-readable
+    typewriter stream must not regress to visible 25 ms batching
+    artifacts, and a mid-turn stall must not hold tokens hostage."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    for i in range(3):
+        time.sleep(_TOKEN_BATCH_WINDOW_SECS + 0.01)
+        ui.on_content_token(f"t{i}")
+    events = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert [ev["text"] for ev in events] == ["t0", "t1", "t2"]
+
+
+def test_batch_size_cap_triggers_flush(wide_window: None, monkeypatch: pytest.MonkeyPatch) -> None:
+    """A pending batch reaching the size cap flushes without waiting for
+    the window — bounds worst-case batch size (and client repaint cost)
+    at fast rates."""
+    monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_MAX_CHARS", 8)
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("x")  # immediate first flush
+    ui.on_content_token("aaaa")  # pending (4 < 8)
+    ui.on_content_token("bbbb")  # 8 >= 8 -> flush
+    events = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert [ev["text"] for ev in events] == ["x", "aaaabbbb"]
+
+
+# ---------------------------------------------------------------------------
+# Condition 1 — snapshot readers never double-render across a batch
+# ---------------------------------------------------------------------------
+
+
+def test_snapshot_mid_batch_sees_only_flushed_text_no_double_render(
+    wide_window: None,
+) -> None:
+    """A snapshot taken between two tokens of a pending batch must
+    exclude the pending text (it has no event id yet), and the later
+    flush must arrive with ``_seq > snap_seq`` so the client renders
+    each character exactly once: snapshot text + post-``snap_seq`` live
+    events == the full stream, no overlap."""
+    ui = _make_ui()
+    ui.on_content_token("aa")  # immediate first flush
+    ui.on_content_token("bb")  # pending — invisible to snapshots
+    lq, snap = ui.register_listener_with_in_progress_snapshot()
+    assert snap["content"] == "aa", (
+        "pending batch text leaked into the snapshot — the flush must be "
+        "the only writer of the inflight buffers"
+    )
+    ui.on_stream_end()  # flushes the pending batch, then stream_end
+    live = [ev for ev in _drain(lq) if ev["type"] == "content" and ev["_seq"] > snap["seq"]]
+    assert "".join(ev["text"] for ev in live) == "bb"
+    assert snap["content"] + "".join(ev["text"] for ev in live) == "aabb"
+    # The flush wrote the inflight buffer too — the NEXT snapshotter
+    # sees the full text (nothing stranded in the accumulator).
+    _, snap2 = ui.register_listener_with_in_progress_snapshot()
+    assert snap2["content"] == "aabb"
+
+
+def test_replay_registration_mid_batch_no_double_render(wide_window: None) -> None:
+    """Same straddle through the ``Last-Event-ID`` reconnect path: the
+    replay slice must not contain the pending batch (not enqueued yet),
+    and the post-registration flush lands exactly once in the live
+    queue."""
+    ui = _make_ui()
+    ui.on_content_token("aa")  # immediate flush -> event id 1
+    ui.on_content_token("bb")  # pending
+    lq, replay, status, _, _, snap = ui.register_listener_with_replay(1)
+    assert status == "replay_ok"
+    assert replay == [], "pending batch must not appear in the replay slice"
+    ui.on_stream_end()
+    live = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert "".join(ev["text"] for ev in live) == "bb"
+    # Full-stream integrity for a fresh reconnect afterwards.
+    _, replay2, _, _, _, _ = ui.register_listener_with_replay(0)
+    assert "".join(ev["text"] for ev in replay2 if ev["type"] == "content") == "aabb"
+
+
+# ---------------------------------------------------------------------------
+# Condition 2 — every non-token emit flushes the pending batch first
+# ---------------------------------------------------------------------------
+
+
+def test_stream_end_flushes_pending_batch_before_itself(wide_window: None) -> None:
+    """``stream_end`` resets the client's streaming refs; a batch
+    arriving after it would paint into a NEW assistant bubble.  The
+    flush must therefore precede ``stream_end`` on the wire (strictly
+    smaller event id, earlier queue position)."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aa")
+    ui.on_content_token("bb")  # pending
+    ui.on_stream_end()
+    events = _drain(lq)
+    types = [ev["type"] for ev in events]
+    assert types == ["content", "content", "stream_end"]
+    assert events[1]["text"] == "bb"
+    assert events[1]["_event_id"] < events[2]["_event_id"]
+
+
+def test_direct_enqueue_flushes_pending_batch_first(wide_window: None) -> None:
+    """The flush lives at the ``_enqueue`` choke point, so even
+    route-level / subclass emits (``state_change``, ``cancelled``,
+    ``clear_ui``) deliver the pending batch first — not just the
+    ``on_*`` helpers."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aa")
+    ui.on_content_token("bb")  # pending
+    ui._enqueue({"type": "state_change", "state": "idle"})
+    events = _drain(lq)
+    assert [ev["type"] for ev in events] == ["content", "content", "state_change"]
+    assert events[1]["text"] == "bb"
+
+
+def test_tool_and_status_emits_flush_pending_batch(wide_window: None) -> None:
+    """Representative non-token ``on_*`` emitters (tool output chunk,
+    status) deliver a pending batch before their own event."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aa")
+    ui.on_content_token("bb")  # pending
+    ui.on_tool_output_chunk("call-1", "chunk")
+    ui.on_content_token("cc")  # immediate?  No — window is wide and the
+    # flush just ran, so this pends; the status emit must deliver it.
+    ui.on_status({"prompt_tokens": 1, "completion_tokens": 2}, 1000, "med")
+    events = _drain(lq)
+    types = [ev["type"] for ev in events]
+    assert types == ["content", "content", "tool_output_chunk", "content", "status"]
+    assert events[1]["text"] == "bb"
+    assert events[3]["text"] == "cc"
+
+
+def test_reasoning_batches_and_kind_switch_flushes(wide_window: None) -> None:
+    """Reasoning batches like content (own accumulator semantics), and a
+    kind switch flushes the other kind first so wire order preserves
+    arrival order between the two token streams."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_reasoning_token("r0")  # immediate first flush
+    ui.on_reasoning_token("r1")  # pending
+    ui.on_content_token("c0")  # must flush the reasoning batch first
+    ui.on_stream_end()
+    events = _drain(lq)
+    reasoning = [ev for ev in events if ev["type"] == "reasoning"]
+    content = [ev for ev in events if ev["type"] == "content"]
+    assert "".join(ev["text"] for ev in reasoning) == "r0r1"
+    assert "".join(ev["text"] for ev in content) == "c0"
+    assert max(ev["_event_id"] for ev in reasoning) < min(ev["_event_id"] for ev in content)
+    # Reasoning landed in ITS inflight buffer, content in its own.
+    _, snap = ui.register_listener_with_in_progress_snapshot()
+    assert snap["reasoning"] == "r0r1"
+    assert snap["content"] == "c0"
+
+
+# ---------------------------------------------------------------------------
+# Buffer-cap and turn-boundary semantics under batching
+# ---------------------------------------------------------------------------
+
+
+def test_inflight_cap_respected_and_stream_continues_past_cap(
+    wide_window: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The 512 KiB inflight cap applies to the batched append exactly as
+    it did per-token: check-before-append (bounded overshoot), and the
+    live stream keeps flowing past the cap — the cap bounds the
+    snapshot, it is NOT a stop-streaming signal."""
+    monkeypatch.setattr("turnstone.core.session_ui_base._MAX_TURN_CONTENT_CHARS", 6)
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aaaa")  # immediate flush; inflight size 4 < 6
+    ui.on_content_token("bbbb")  # pending
+    ui.on_stream_end()  # flush appends (4 < 6 -> append; size 8)
+    ui.on_content_token("cccc")  # immediate flush; 8 >= 6 -> NOT appended
+    ui.on_stream_end()
+    live = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert [ev["text"] for ev in live] == ["aaaa", "bbbb", "cccc"], (
+        "live stream must continue past the inflight cap"
+    )
+    _, snap = ui.register_listener_with_in_progress_snapshot()
+    assert snap["content"] == "aaaabbbb", (
+        "snapshot text is capped (check-before-append overshoot only)"
+    )
+
+
+def test_on_turn_start_discards_stale_pending(wide_window: None) -> None:
+    """``on_turn_start`` covers the crashed-prior-``send()`` case; a
+    stale pending batch from that crash must be DISCARDED (never
+    enqueued), not painted into the new turn's bubble."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aa")
+    ui.on_content_token("stale")  # pending, then the send crashes
+    ui.on_turn_start()
+    ui.on_stream_end()
+    live = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert [ev["text"] for ev in live] == ["aa"]
+    _, snap = ui.register_listener_with_in_progress_snapshot()
+    assert snap["content"] == ""
+
+
+def test_on_turn_committed_flushes_pending_before_reset(wide_window: None) -> None:
+    """``on_turn_committed`` runs after the assistant message committed;
+    any pending text is part of that committed message, so it flushes
+    (live view + ring stay complete) BEFORE the inflight reset."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aa")
+    ui.on_content_token("bb")  # pending
+    ui.on_turn_committed()
+    live = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert [ev["text"] for ev in live] == ["aa", "bb"]
+    _, snap = ui.register_listener_with_in_progress_snapshot()
+    assert snap["content"] == "", "inflight reset still runs after the flush"
+
+
+def test_idle_state_payload_includes_pending_batch(wide_window: None) -> None:
+    """``snapshot_and_consume_state_payload('idle')`` is the cancel /
+    error chokepoint that drains the turn-content accumulator; a pending
+    batch must flush into it first so the dashboard payload carries the
+    full turn."""
+    ui = _make_ui()
+    lq = ui._register_listener()
+    ui.on_content_token("aa")
+    ui.on_content_token("bb")  # pending
+    payload = ui.snapshot_and_consume_state_payload("idle")
+    assert payload["content"] == "aabb"
+    live = [ev for ev in _drain(lq) if ev["type"] == "content"]
+    assert "".join(ev["text"] for ev in live) == "aabb"
+
+
+# ---------------------------------------------------------------------------
+# Concurrency — flush choke point vs a concurrent snapshot reader
+# ---------------------------------------------------------------------------
+
+
+def test_concurrent_snapshots_never_double_render_batched_stream(
+    wide_window: None,
+) -> None:
+    """Hammer test for Condition 1: a writer streams batched tokens
+    while a reader repeatedly registers snapshot listeners; for every
+    snapshot, snapshot-text + post-``snap_seq`` live events must equal
+    the full stream exactly once (no overlap, no gap) — the invariant
+    that breaks if the inflight append and the batch enqueue are ever
+    split across ``_ws_lock`` sections."""
+    ui = _make_ui()
+    n = 200
+    done = threading.Event()
+
+    def _writer() -> None:
+        for i in range(n):
+            ui.on_content_token(f"[{i}]")
+        ui.on_stream_end()
+        done.set()
+
+    results: list[tuple[str, int, queue.Queue[dict[str, Any]]]] = []
+
+    def _reader() -> None:
+        while not done.is_set():
+            lq, snap = ui.register_listener_with_in_progress_snapshot()
+            results.append((snap["content"], snap["seq"], lq))
+
+    w = threading.Thread(target=_writer)
+    r = threading.Thread(target=_reader)
+    w.start()
+    r.start()
+    w.join()
+    r.join()
+
+    full = "".join(f"[{i}]" for i in range(n))
+    for snap_content, snap_seq, lq in results:
+        live = [ev for ev in _drain(lq) if ev["type"] == "content" and ev["_seq"] > snap_seq]
+        rebuilt = snap_content + "".join(ev["text"] for ev in live)
+        assert rebuilt == full, (
+            f"client view diverged: snapshot({len(snap_content)} chars) + "
+            f"{len(live)} live events != full stream"
+        )

tests/test_storage_attachments.py

@@ -404,3 +404,29 @@ class TestParametrizedKind:
         assert len(rows) == 1
         assert rows[0]["content"] == payload
         assert rows[0]["kind"] == kind
+
+
+class TestGetAttachmentsExcludeKinds:
+    def test_exclude_kinds_filters_at_the_query(self, backend):
+        """Preview-pane blobs ride ref-lists only for GC + the serving gate;
+        the reconstruct loader excludes them so a history load never pulls
+        their multi-MB content just to discard it."""
+        backend.register_workstream("ws-ex")
+        blob = _hash(b"<html>big page</html>")
+        img = _hash(PNG_1x1)
+        backend.save_attachment(
+            blob,
+            "preview-web",
+            "text/html; charset=utf-8",
+            21,
+            "preview",
+            b"<html>big page</html>",
+            "tool",
+        )
+        backend.save_attachment(
+            img, "shot.png", "image/png", len(PNG_1x1), "image", PNG_1x1, "tool"
+        )
+        rows = backend.get_attachments([blob, img], exclude_kinds=("preview",))
+        assert [r["attachment_id"] for r in rows] == [img]
+        # Default stays unfiltered — the serving route still resolves previews.
+        assert {r["attachment_id"] for r in backend.get_attachments([blob, img])} == {blob, img}

tests/test_storage_sqlite.py

@@ -298,9 +298,9 @@ class TestLoadMessagesLimit:
         captured: list[list[str]] = []
         orig = backend.get_attachments
 
-        def _spy(ids):
+        def _spy(ids, exclude_kinds=()):
             captured.append(sorted(ids))
-            return orig(ids)
+            return orig(ids, exclude_kinds=exclude_kinds)
 
         # Tail-N=5 fetches only the 5 newest rows (all plain) — the
         # attachment row is excluded, so NO blob fetch is issued.

tests/test_tools_schema.py

@@ -60,8 +60,8 @@ class TestToolsMetadata:
     """Validate the metadata extracted from JSON files."""
 
     def test_tool_count(self):
-        # 16 interactive tools + 12 coordinator-only tools.
-        assert len(TOOLS) == 28
+        # 17 interactive tools + 12 coordinator-only tools.
+        assert len(TOOLS) == 29
 
     def test_task_agent_tools_count(self):
         assert len(TASK_AGENT_TOOLS) == 11
@@ -126,6 +126,7 @@ class TestToolsMetadata:
             "edit_file": "old_string",
             "web_fetch": "url",
             "web_search": "query",
+            "open_preview": "target",
             "task_agent": "prompt",
             "memory": "name",
             "recall": "query",

tests/test_watch.py

@@ -2,11 +2,15 @@
 
 from __future__ import annotations
 
+import threading
+import time
 from datetime import UTC, datetime
+from typing import Any
 from unittest.mock import MagicMock
 
 import pytest
 
+from tests._helpers import wait_until
 from turnstone.core.watch import (
     WatchRunner,
     build_watch_reminder,
@@ -545,8 +549,12 @@ class TestWatchRunner:
         assert runner.get_dispatch_fn("ws-1") is fn
         # Unknown ws → None.
         assert runner.get_dispatch_fn("ws-missing") is None
-        # After removal → None.
-        runner.remove_dispatch_fn("ws-1")
+        # Owner-checked removal: a non-owner's teardown must not remove a
+        # still-live registration (restore shell vs reopened pane).
+        runner.remove_dispatch_fn("ws-1", owner=MagicMock())
+        assert runner.get_dispatch_fn("ws-1") is fn
+        # The owner (or a blind removal) does remove it.
+        runner.remove_dispatch_fn("ws-1", owner=fn)
         assert runner.get_dispatch_fn("ws-1") is None
 
     def test_run_command_success(self):
@@ -566,3 +574,718 @@ class TestWatchRunner:
         output, code = runner._run_command("sleep 30")
         assert "timed out" in output.lower()
         assert code == -1
+
+
+def _watch_row(**over: Any) -> dict[str, Any]:
+    """A firing watch row (condition matches ``echo hello``); override
+    fields per test."""
+    row: dict[str, Any] = {
+        "watch_id": "abc123",
+        "ws_id": "ws-1",
+        "name": "test-watch",
+        "command": "echo hello",
+        "stop_on": '"hello" in output',
+        "max_polls": 100,
+        "poll_count": 0,
+        "last_output": None,
+        "interval_secs": 60,
+        "created": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+    row.update(over)
+    return row
+
+
+def _slow_restore(runner: WatchRunner, ws_id: str, calls: list[str], lock: threading.Lock) -> Any:
+    """Restore_fn stand-in: record the call, register a dispatch fn (as the
+    real restore does via ``set_watch_runner``), and sleep briefly so a
+    concurrent second caller is guaranteed to be waiting on ``_restore_lock``
+    when we return.
+    """
+    with lock:
+        calls.append(ws_id)
+    time.sleep(0.05)
+    fn = MagicMock()
+    runner.set_dispatch_fn(ws_id, fn)
+    return fn
+
+
+class TestWatchRunnerDeliveryRetry:
+    """Delivery failure HOLDS the built reminder and re-delivers it on a
+    later tick — never re-running the command, so a transient stop_on match
+    isn't lost — bounded by ``MAX_DELIVERY_ATTEMPTS``.  Until delivery lands
+    the row commits only ``next_poll`` plus the fire's durable poll charge:
+    no baseline advance and no deactivation of a fire the model never saw,
+    while a restart mid-hold (which re-runs the command) stays bounded by
+    ``max_polls``."""
+
+    def _make_runner(self, storage: Any, **kwargs: Any) -> WatchRunner:
+        return WatchRunner(
+            storage=storage,
+            node_id="test-node",
+            check_interval=0.1,
+            tool_timeout=5,
+            **kwargs,
+        )
+
+    def test_delivery_failure_holds_reminder_and_defers_row(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        # No dispatch fn registered, no restore_fn → delivery fails.
+        runner = self._make_runner(storage)
+
+        runner._poll_watch(_watch_row())
+
+        # Row commit is the retry cadence + this fire's durable poll charge
+        # — the fire stays fully retryable, and a restart mid-hold (which
+        # re-runs the command) stays bounded by max_polls.
+        storage.update_watch.assert_called_once()
+        args, kwargs = storage.update_watch.call_args
+        assert args[0] == "abc123"
+        assert set(kwargs) == {"next_poll", "poll_count"}
+        assert kwargs["poll_count"] == 1  # charged durably at hold time
+        assert kwargs["next_poll"]  # advanced, not cleared
+        # The reminder is HELD for re-delivery; the row is NOT marked
+        # terminal-dispatched (the model never saw it).
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+            assert runner._pending_delivery["abc123"]["attempts"] == 1
+        with runner._terminal_dispatched_lock:
+            assert "abc123" not in runner._terminal_dispatched
+
+    def test_redelivery_uses_held_reminder_without_rerunning_command(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)
+
+        # Poll 1: fails → holds.  Capture the exact held reminder object.
+        runner._poll_watch(_watch_row())
+        with runner._pending_delivery_lock:
+            held = runner._pending_delivery["abc123"]["reminder"]
+
+        # ws restored: register a fn, and make _run_command explode so the
+        # test proves re-delivery does NOT re-run the command.
+        dispatch_fn = MagicMock()
+        runner.set_dispatch_fn("ws-1", dispatch_fn)
+        runner._run_command = MagicMock(  # type: ignore[method-assign]
+            side_effect=AssertionError("command must not re-run on re-delivery")
+        )
+
+        runner._poll_watch(_watch_row())
+
+        # Delivered the SAME held reminder; command untouched; committed
+        # terminal with the ORIGINAL fire's poll_count; hold cleared.
+        dispatch_fn.assert_called_once()
+        assert dispatch_fn.call_args[0][0] is held
+        runner._run_command.assert_not_called()
+        _a, kwargs = storage.update_watch.call_args
+        assert kwargs["active"] is False
+        assert kwargs["poll_count"] == 1  # retries consumed no ADDITIONAL budget
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+
+    def test_transient_exhaustion_keeps_watch_active(self):
+        # A purely transient cause (no fn, no restore → returns False) that
+        # outlasts the attempt budget must NOT silently deactivate the watch
+        # — it drops the held reminder, charges ONE poll to the max_polls
+        # budget, and leaves the watch active to re-fire on its next
+        # interval.  The baseline (last_output) stays uncommitted so a
+        # delta-style stop_on re-fires on the change the model never saw.
+        from turnstone.core.watch import MAX_DELIVERY_ATTEMPTS
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)  # always fails, transiently
+
+        # Poll 1 fires + holds (attempts=1); polls 2..MAX bump attempts, the
+        # MAX-th hitting the exhaustion ceiling.
+        for _ in range(MAX_DELIVERY_ATTEMPTS):
+            runner._poll_watch(_watch_row())
+
+        # Hold dropped, but the watch was NEVER deactivated — no active=False
+        # commit anywhere; the final commit charges the poll and re-schedules
+        # (no last_output → the fire re-detects next cycle).
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+        deactivations = [
+            c for c in storage.update_watch.call_args_list if c.kwargs.get("active") is False
+        ]
+        assert deactivations == []
+        _a, kwargs = storage.update_watch.call_args  # last commit
+        assert set(kwargs) == {"poll_count", "next_poll"}
+        assert kwargs["poll_count"] == 1  # one poll charged to the budget
+
+    def test_transient_exhaustion_with_budget_spent_deactivates(self):
+        # The keep-alive-on-transient behavior is bounded by the watch's own
+        # max_polls budget: once poll_count reaches it, exhaustion commits
+        # the held (deactivating) update instead of re-running the command
+        # every interval forever against an unreachable workstream.
+        from turnstone.core.watch import MAX_DELIVERY_ATTEMPTS
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)  # always fails, transiently
+
+        for _ in range(MAX_DELIVERY_ATTEMPTS):
+            runner._poll_watch(_watch_row(max_polls=1))  # budget spent on fire 1
+
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+        _a, kwargs = storage.update_watch.call_args  # last commit
+        assert kwargs["active"] is False  # deactivated: budget spent
+        assert kwargs["poll_count"] == 1
+
+    def test_held_delivery_retries_on_capped_cadence_not_interval(self):
+        # Re-delivery is a cheap in-memory dispatch — a daily watch whose
+        # fire hit a busy restore slot must retry within
+        # DELIVERY_RETRY_CAP_SECS, not sit on the reminder for 24 h.
+        from turnstone.core.watch import DELIVERY_RETRY_CAP_SECS
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)
+
+        runner._poll_watch(_watch_row(interval_secs=86_400))
+
+        _a, kwargs = storage.update_watch.call_args
+        assert set(kwargs) == {"next_poll", "poll_count"}
+        retry_at = datetime.strptime(kwargs["next_poll"], "%Y-%m-%dT%H:%M:%S").replace(tzinfo=UTC)
+        delta = (retry_at - datetime.now(UTC)).total_seconds()
+        assert 0 < delta <= DELIVERY_RETRY_CAP_SECS + 5  # capped, not 86400
+
+    def test_permanent_unrestorable_deactivates_immediately(self):
+        # A permanent failure (restore raises WatchWorkstreamUnrestorable,
+        # e.g. corrupt persona stamp) deactivates the watch on the FIRST
+        # fire — no held reminder, no waiting out the attempt budget.
+        from turnstone.core.watch import WatchWorkstreamUnrestorable
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_fn = MagicMock(side_effect=WatchWorkstreamUnrestorable("ws-1"))
+        runner = self._make_runner(storage, restore_fn=restore_fn)
+
+        runner._poll_watch(_watch_row())
+
+        restore_fn.assert_called_once_with("ws-1")  # not retried 5×
+        _a, kwargs = storage.update_watch.call_args
+        assert kwargs["active"] is False  # deactivated now
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery  # nothing held
+        # The admission slot is released even on the raising path.
+        with runner._restore_lock:
+            assert "ws-1" not in runner._restoring
+
+    def test_pending_cleared_on_already_dispatched_retry(self):
+        # Constructs the id-in-both-sets state DIRECTLY: no current path
+        # produces it (_redeliver_pending clears the hold before its
+        # commit), but the already-dispatched branch deactivates the row —
+        # after which it never re-lists — so it is the last line of
+        # defense against any such hold leaking forever.  Pin that it
+        # clears the hold alongside the retry-deactivate.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)
+        with runner._terminal_dispatched_lock:
+            runner._terminal_dispatched.add("abc123")
+        runner._stash_pending_delivery("abc123", {"text": "x"}, {"active": False}, attempts=1)
+
+        runner._poll_watch(_watch_row())  # hits the already_dispatched branch
+
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+        with runner._terminal_dispatched_lock:
+            assert "abc123" not in runner._terminal_dispatched
+
+    def test_restore_capacity_full_defers_without_restoring(self):
+        # When MAX_CONCURRENT_RESTORES restores are already in flight, a
+        # new evicted-ws poll must DEFER (return False, hold) rather than
+        # block a poll slot — and must not start a restore.
+        from turnstone.core.watch import MAX_CONCURRENT_RESTORES
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_fn = MagicMock(return_value=MagicMock())
+        runner = self._make_runner(storage, restore_fn=restore_fn)
+        # Saturate the restore admission with other in-flight ws_ids.
+        with runner._restore_lock:
+            for i in range(MAX_CONCURRENT_RESTORES):
+                runner._restoring[f"other-{i}"] = time.monotonic()
+
+        result = runner._dispatch_result("ws-evicted", {"text": "x"}, "w1")
+
+        assert result is False  # deferred
+        restore_fn.assert_not_called()  # no restore admitted
+
+    def test_race_won_admission_delivers_outside_restore_lock(self):
+        # A dispatch fn registered between the fast-path miss and the
+        # admission check must be delivered WITHOUT holding _restore_lock:
+        # the closure can block (ws._lock, wake-thread spawn), and running
+        # it under the lock serialises every restore admission on the node
+        # behind one delivery.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_fn = MagicMock(return_value=None)
+        runner = self._make_runner(storage, restore_fn=restore_fn)
+
+        lock_free_during_dispatch: list[bool] = []
+
+        def probe(reminder: dict[str, Any], watch_id: str) -> None:
+            ok = runner._restore_lock.acquire(blocking=False)
+            lock_free_during_dispatch.append(ok)
+            if ok:
+                runner._restore_lock.release()
+
+        real_try = runner._try_dispatch_fn
+        calls = {"n": 0}
+
+        def fake_try(ws_id: str, reminder: dict[str, Any], watch_id: str) -> bool | None:
+            calls["n"] += 1
+            if calls["n"] == 1:
+                # Simulate a restore completing between the fast path and
+                # the admission check: the fn appears "while we waited".
+                runner.set_dispatch_fn("ws-1", probe)
+                return None
+            return real_try(ws_id, reminder, watch_id)
+
+        runner._try_dispatch_fn = fake_try  # type: ignore[method-assign]
+
+        result = runner._dispatch_result("ws-1", {"text": "x"}, "w1")
+
+        assert result is True  # race-won fn delivered
+        assert lock_free_during_dispatch == [True]  # ...outside the lock
+        restore_fn.assert_not_called()  # no restore admitted for a live fn
+
+    def test_restore_returning_none_holds(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_fn = MagicMock(return_value=None)  # e.g. all slots active
+        runner = self._make_runner(storage, restore_fn=restore_fn)
+
+        runner._poll_watch(_watch_row())
+
+        restore_fn.assert_called_once_with("ws-1")
+        _a, kwargs = storage.update_watch.call_args
+        assert set(kwargs) == {"next_poll", "poll_count"}
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+
+    def test_live_fn_raise_holds_without_restoring(self):
+        # A registered fn that RAISES means the ws is live; we must NOT fall
+        # through to restore (that would spawn a duplicate session on a live
+        # conversation).  The reminder is held for re-delivery instead.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_fn = MagicMock()
+        runner = self._make_runner(storage, restore_fn=restore_fn)
+        runner.set_dispatch_fn("ws-1", MagicMock(side_effect=RuntimeError("stale closure")))
+
+        runner._poll_watch(_watch_row())
+
+        restore_fn.assert_not_called()
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+        _a, kwargs = storage.update_watch.call_args
+        assert set(kwargs) == {"next_poll", "poll_count"}
+
+    def test_forget_terminal_dispatched_clears_held_reminder(self):
+        # User-cancel takes the row out of the due view; its held reminder
+        # must be dropped too or it would leak (never re-polled).
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)
+        runner._poll_watch(_watch_row())
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+
+        runner.forget_terminal_dispatched("abc123")
+
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+
+    def test_abandon_write_failure_keeps_hold_for_write_retry(self):
+        # Reads-succeed/writes-fail storage (e.g. disk-full SQLite): a
+        # failed abandon commit must keep the hold so the next tick retries
+        # the WRITE via the redeliver path — the clear-first order let the
+        # row re-list into a fresh COMMAND RUN every attempt-budget cycle,
+        # forever, with the poll budget never advancing.
+        from turnstone.core.watch import WatchWorkstreamUnrestorable
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)
+        runner._poll_watch(_watch_row())  # fire → hold (write still OK here)
+        with runner._pending_delivery_lock:
+            pending = dict(runner._pending_delivery["abc123"])
+
+        runner._restore_fn = MagicMock(  # type: ignore[assignment]
+            side_effect=WatchWorkstreamUnrestorable("ws-1")
+        )
+        storage.update_watch.side_effect = RuntimeError("disk full")
+
+        with pytest.raises(RuntimeError):
+            runner._redeliver_pending(_watch_row(), pending)
+
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery  # hold survived
+
+    def test_unrestorable_abandon_write_failure_keeps_hold(self):
+        # Fresh-fire permanent failure whose deactivation write fails must
+        # not strand the still-active row into a fresh command run every
+        # tick: the stash routes the next tick into the redeliver path,
+        # which retries the WRITE — never the command.
+        from turnstone.core.watch import WatchWorkstreamUnrestorable
+
+        storage = MagicMock()
+        storage.update_watch.side_effect = RuntimeError("disk full")
+        restore_fn = MagicMock(side_effect=WatchWorkstreamUnrestorable("ws-1"))
+        runner = self._make_runner(storage, restore_fn=restore_fn)
+
+        with pytest.raises(RuntimeError):
+            runner._poll_watch(_watch_row())
+
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery  # hold survived
+
+        # Next tick: the write retries and lands; the command never re-runs.
+        runner._run_command = MagicMock(  # type: ignore[method-assign]
+            side_effect=AssertionError("command must not re-run")
+        )
+        storage.update_watch.side_effect = None
+        storage.update_watch.return_value = True
+
+        runner._poll_watch(_watch_row())
+
+        runner._run_command.assert_not_called()
+        _a, kwargs = storage.update_watch.call_args
+        assert kwargs["active"] is False  # deactivation landed on the retry
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+
+    def test_exhaustion_write_failure_keeps_hold_for_write_retry(self):
+        # Same pathology on the transient-exhaustion branch: the charge
+        # commit failing must keep the hold (write retried next tick), not
+        # drop it into a fresh command cycle with the budget never durable.
+        from turnstone.core.watch import MAX_DELIVERY_ATTEMPTS
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)  # no fn, no restore → transient
+        runner._poll_watch(_watch_row())  # fire → hold
+        with runner._pending_delivery_lock:
+            runner._pending_delivery["abc123"]["attempts"] = MAX_DELIVERY_ATTEMPTS - 1
+            pending = dict(runner._pending_delivery["abc123"])
+
+        storage.update_watch.side_effect = RuntimeError("disk full")
+
+        with pytest.raises(RuntimeError):
+            runner._redeliver_pending(_watch_row(), pending)
+
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery  # hold survived
+
+
+class TestWatchRunnerCancelRace:
+    """User-cancel racing the poll pool: the delivery paths re-check the
+    row's active state so a cancelled watch can neither deliver nor leak a
+    held reminder, and the tick sweep mops up the one interleaving the
+    point checks can't reach (a stash landing after the cancel path's
+    ``forget_terminal_dispatched`` already cleared)."""
+
+    def _make_runner(self, storage: Any, **kwargs: Any) -> WatchRunner:
+        return WatchRunner(
+            storage=storage,
+            node_id="test-node",
+            check_interval=0.1,
+            tool_timeout=5,
+            **kwargs,
+        )
+
+    def test_hold_dropped_when_watch_cancelled_mid_fire(self):
+        # Cancel lands while the fire's command is running: the hold path
+        # re-checks the row and DROPS instead of stashing — an inactive row
+        # never re-lists, so a stash here would leak for the process
+        # lifetime with nothing ever retrying or clearing it.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        storage.is_watch_active.return_value = False
+        runner = self._make_runner(storage)  # no fn, no restore → would hold
+
+        runner._poll_watch(_watch_row())
+
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+        # No retry-cadence commit either — the row already left the view.
+        storage.update_watch.assert_not_called()
+
+    def test_redelivery_dropped_when_watch_cancelled(self):
+        # Cancel lands between the due listing and the redelivery dispatch:
+        # deliver nothing (the model must not act on — nor a restore be
+        # spawned for — a watch the user just cancelled) and drop the hold.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        runner = self._make_runner(storage)
+        runner._poll_watch(_watch_row())  # fails → holds (row still active)
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+
+        storage.is_watch_active.return_value = False  # user cancels
+        dispatch_fn = MagicMock()
+        runner.set_dispatch_fn("ws-1", dispatch_fn)  # ws even came back live
+
+        runner._poll_watch(_watch_row())
+
+        dispatch_fn.assert_not_called()
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+        # The only row write remains the initial hold's cadence commit —
+        # no terminal commit lands over the cancel's row state.
+        assert storage.update_watch.call_count == 1
+
+    def test_tick_sweeps_cancelled_holds(self):
+        # The residual interleaving: a stash that landed AFTER the cancel's
+        # forget_terminal_dispatched cleared (its active re-check passed
+        # just before the cancel's row write).  The sweep drops it within
+        # one tick.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        storage.list_due_watches.return_value = []
+        runner = self._make_runner(storage)
+        runner._stash_pending_delivery("abc123", {"text": "x"}, {"active": False}, attempts=1)
+        storage.is_watch_active.return_value = False  # row already cancelled
+
+        runner._tick()
+
+        with runner._pending_delivery_lock:
+            assert "abc123" not in runner._pending_delivery
+
+    def test_tick_sweep_keeps_active_holds(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        storage.list_due_watches.return_value = []
+        runner = self._make_runner(storage)
+        runner._stash_pending_delivery("abc123", {"text": "x"}, {"active": False}, attempts=1)
+        storage.is_watch_active.return_value = True
+
+        runner._tick()
+
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+
+    def test_active_checks_bias_toward_delivery_on_storage_error(self):
+        # is_watch_active RAISING must not drop a fire: the sweep keeps the
+        # hold and the delivery paths proceed (bounded by their own attempt
+        # and poll budgets) — a storage blip is not a cancellation.
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        storage.list_due_watches.return_value = []
+        storage.is_watch_active.side_effect = RuntimeError("storage down")
+        runner = self._make_runner(storage)
+        runner._stash_pending_delivery("abc123", {"text": "x"}, {"active": False}, attempts=1)
+
+        runner._tick()  # sweep: biased active → kept
+
+        with runner._pending_delivery_lock:
+            assert "abc123" in runner._pending_delivery
+
+
+class TestWatchRunnerRestoreSerialization:
+    """Two watches on ONE evicted workstream, polled concurrently, must
+    trigger the restore path at most once — otherwise each spawns a live
+    auto-approved session racing writes into one conversation history."""
+
+    def test_concurrent_same_ws_restores_once(self):
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_calls: list[str] = []
+        calls_lock = threading.Lock()
+
+        runner = WatchRunner(
+            storage=storage,
+            node_id="n",
+            check_interval=0.1,
+            tool_timeout=5,
+            restore_fn=lambda ws_id: _slow_restore(runner, ws_id, restore_calls, calls_lock),
+        )
+
+        reminder = {"type": "watch_triggered", "text": "x"}
+        barrier = threading.Barrier(2)
+        results: list[bool] = []
+        results_lock = threading.Lock()
+
+        def call(wid: str) -> None:
+            barrier.wait(timeout=2.0)
+            ok = runner._dispatch_result("ws-shared", reminder, wid)
+            with results_lock:
+                results.append(ok)
+
+        threads = [threading.Thread(target=call, args=(f"w{i}",)) for i in range(2)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=3.0)
+
+        # Exactly one restore ran; the winner delivered (True) and the other
+        # DEFERRED (False, holds + re-delivers next tick) rather than blocking
+        # its poll slot on the in-flight restore or restoring a second time.
+        assert restore_calls == ["ws-shared"]
+        assert sorted(results) == [False, True]
+        # Admission slot released after the restore.
+        with runner._restore_lock:
+            assert "ws-shared" not in runner._restoring
+
+    def test_wedged_restore_admissions_defer_and_alert(self, caplog):
+        # Admission entries older than RESTORE_STALL_ALERT_SECS are alerted
+        # on but NEVER evicted: the wedged poll thread's pool slot is never
+        # released, so reclaiming its admission would just readmit a restore
+        # that can wedge another pool thread on the same cause — trading
+        # this capped degraded state (restores blocked, polling intact) for
+        # total poll-pool collapse.  New restores keep deferring; the error
+        # log is the operator's restart signal.
+        from turnstone.core.watch import RESTORE_STALL_ALERT_SECS
+
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        restore_fn = MagicMock(return_value=MagicMock())
+        runner = WatchRunner(
+            storage=storage,
+            node_id="n",
+            check_interval=0.1,
+            tool_timeout=5,
+            restore_fn=restore_fn,
+        )
+        stalled_at = time.monotonic() - RESTORE_STALL_ALERT_SECS - 1
+        with runner._restore_lock:
+            runner._restoring["wedged-1"] = stalled_at
+            runner._restoring["wedged-2"] = stalled_at  # both slots wedged
+
+        with caplog.at_level("ERROR"):
+            result = runner._dispatch_result("ws-new", {"text": "x"}, "w1")
+
+        assert result is False  # wedged capacity stays consumed → defer
+        restore_fn.assert_not_called()
+        with runner._restore_lock:
+            assert "wedged-1" in runner._restoring
+            assert "wedged-2" in runner._restoring
+        assert any("watch_runner.restore_admission_wedged" in r.message for r in caplog.records)
+
+
+class TestWatchRunnerConcurrency:
+    """The tick thread only enumerates due rows; polls run on bounded
+    daemon threads.  Pins: genuine concurrency, per-watch in-flight
+    dedup, saturation leaving rows due (not dropped), and ``stop``
+    draining in-flight polls."""
+
+    def _make_runner(self, rows: list[dict[str, Any]], **kwargs: Any) -> WatchRunner:
+        storage = MagicMock()
+        storage.update_watch.return_value = True
+        storage.list_due_watches.return_value = rows
+        return WatchRunner(
+            storage=storage,
+            node_id="test-node",
+            check_interval=0.1,
+            tool_timeout=5,
+            **kwargs,
+        )
+
+    @staticmethod
+    def _wait_in_flight_empty(runner: WatchRunner, timeout: float = 3.0) -> None:
+        def _drained() -> bool:
+            with runner._in_flight_lock:
+                return not runner._in_flight
+
+        wait_until(_drained, timeout=timeout)
+
+    def test_tick_polls_concurrently(self):
+        rows = [_watch_row(watch_id=f"w{i}", ws_id=f"ws-{i}") for i in range(3)]
+        runner = self._make_runner(rows)
+
+        all_in = threading.Event()
+        release = threading.Event()
+        barrier = threading.Barrier(3)
+
+        def fake_poll(_row: dict[str, Any]) -> None:
+            # All three poll threads must be inside simultaneously for the
+            # barrier to trip — serial execution would deadlock here (and
+            # fail via the barrier timeout instead).
+            barrier.wait(timeout=2.0)
+            all_in.set()
+            release.wait(timeout=2.0)
+
+        runner._poll_watch = fake_poll  # type: ignore[method-assign]
+        runner._tick()
+
+        assert all_in.wait(timeout=2.0), "polls did not run concurrently"
+        release.set()
+        self._wait_in_flight_empty(runner)
+
+    def test_tick_skips_in_flight_watch(self):
+        rows = [_watch_row(watch_id="w0", ws_id="ws-0")]
+        runner = self._make_runner(rows)
+        polled: list[str] = []
+        runner._poll_watch = lambda row: polled.append(row["watch_id"])  # type: ignore[method-assign]
+
+        # Simulate a slow poll from a previous tick still running.
+        with runner._in_flight_lock:
+            runner._in_flight.add("w0")
+
+        runner._tick()
+
+        assert polled == []
+        # The foreign in-flight entry was not clobbered by the skip.
+        with runner._in_flight_lock:
+            assert "w0" in runner._in_flight
+
+    def test_tick_saturation_leaves_rows_due(self):
+        rows = [_watch_row(watch_id=f"w{i}", ws_id=f"ws-{i}") for i in range(2)]
+        runner = self._make_runner(rows, max_concurrent_polls=1)
+
+        started = threading.Event()
+        release = threading.Event()
+        polled: list[str] = []
+
+        def fake_poll(row: dict[str, Any]) -> None:
+            polled.append(row["watch_id"])
+            started.set()
+            release.wait(timeout=2.0)
+
+        runner._poll_watch = fake_poll  # type: ignore[method-assign]
+        runner._tick()
+        assert started.wait(timeout=2.0)
+
+        # Only the first row got a slot this tick; the second stays due
+        # for the next tick rather than being dropped.
+        assert polled == ["w0"]
+        release.set()
+        self._wait_in_flight_empty(runner)
+
+        # Next tick (slot free again) picks up the remaining row.
+        runner._storage.list_due_watches.return_value = [rows[1]]
+        runner._tick()
+        self._wait_in_flight_empty(runner)
+        assert polled == ["w0", "w1"]
+
+    def test_stop_waits_for_in_flight_polls(self):
+        rows = [_watch_row(watch_id="w0", ws_id="ws-0")]
+        runner = self._make_runner(rows)
+
+        started = threading.Event()
+        release = threading.Event()
+
+        def fake_poll(_row: dict[str, Any]) -> None:
+            started.set()
+            release.wait(timeout=3.0)
+
+        runner._poll_watch = fake_poll  # type: ignore[method-assign]
+        runner._tick()
+        assert started.wait(timeout=2.0)
+
+        stopper = threading.Thread(target=runner.stop, daemon=True)
+        stopper.start()
+        # stop() must be draining (poll still pinned), not returned.
+        time.sleep(0.15)
+        assert stopper.is_alive(), "stop() returned while a poll was in flight"
+
+        release.set()
+        stopper.join(timeout=3.0)
+        assert not stopper.is_alive()
+        with runner._in_flight_lock:
+            assert not runner._in_flight

tests/test_watch_dispatch.py

@@ -54,9 +54,11 @@ def _make_session_for_dispatch(**kwargs: Any) -> ChatSession:
     return ChatSession(**defaults)
 
 
-def _register_runner(session: ChatSession) -> tuple[Any, Any]:
+def _register_runner(session: ChatSession, wake_fn: Any = None) -> tuple[Any, Any]:
     """Attach a minimal stub ``WatchRunner`` to *session* and return the
     ``(runner, dispatch_fn)`` pair captured by ``set_dispatch_fn``.
+    ``wake_fn`` rides through to ``set_watch_runner`` (default ``None``
+    matches the pre-wake wiring most tests here exercise).
     """
     captured: dict[str, Any] = {}
 
@@ -65,7 +67,7 @@ def _register_runner(session: ChatSession) -> tuple[Any, Any]:
             captured["fn"] = fn
 
     runner = _StubRunner()
-    session.set_watch_runner(runner)
+    session.set_watch_runner(runner, wake_fn=wake_fn)
     return runner, captured["fn"]
 
 
@@ -400,3 +402,216 @@ class TestMetadataPropagation:
         assert len(snapshot) == 1
         _nt, _text, meta = snapshot[0]
         assert meta is None
+
+
+# ---------------------------------------------------------------------------
+# Wake trigger
+# ---------------------------------------------------------------------------
+
+
+class TestWakeFn:
+    """``set_watch_runner``'s optional ``wake_fn`` fires once per enqueued
+    dispatch — AFTER the entry lands — so a watch firing on an
+    already-idle workstream (no IDLE transition for the
+    ``IdleNudgeWatcher`` to observe) can spawn the wake worker that
+    drains it.  Failures are contained: the enqueue must survive a
+    raising ``wake_fn``, because a propagated raise would abort
+    ``WatchRunner._poll_watch`` before the watch-row update commits and
+    re-fire the same reminder every subsequent tick.
+    """
+
+    def test_wake_fn_called_after_enqueue(self, tmp_db):
+        session = _make_session_for_dispatch()
+        depth_at_wake: list[int] = []
+        _runner, dispatch = _register_runner(
+            session, wake_fn=lambda: depth_at_wake.append(len(session._nudge_queue))
+        )
+
+        dispatch(_reminder("watch fired body"), "watch-1")
+
+        # Fired exactly once, and the entry was already queued when it ran
+        # — the wake worker's drain must be able to see the fresh entry.
+        assert depth_at_wake == [1]
+
+    def test_wake_fn_not_called_when_payload_sanitizes_empty(self, tmp_db):
+        """A fire whose payload strips to nothing enqueues nothing — and
+        must not wake anything either (a wake with an empty queue would
+        just spawn a worker that no-ops at the drain guard)."""
+        session = _make_session_for_dispatch()
+        wake = MagicMock()
+        _runner, dispatch = _register_runner(session, wake_fn=wake)
+
+        dispatch(_reminder("\x07\x0b\x7f"), "watch-1")
+
+        assert len(session._nudge_queue) == 0
+        wake.assert_not_called()
+
+    def test_wake_fn_exception_is_contained(self, tmp_db, caplog):
+        session = _make_session_for_dispatch()
+        wake = MagicMock(side_effect=RuntimeError("boom"))
+        _runner, dispatch = _register_runner(session, wake_fn=wake)
+
+        with caplog.at_level("WARNING"):
+            dispatch(_reminder("body"), "watch-1")  # must not raise
+
+        # Entry survived; the failure surfaced as a warning, not a raise
+        # up into the poll loop.
+        assert len(session._nudge_queue) == 1
+        assert any("watch_dispatch.wake_failed" in r.message for r in caplog.records), (
+            "expected a watch_dispatch.wake_failed warning record"
+        )
+
+
+class _RecordingRunner:
+    """Stub WatchRunner recording registration/removal order.  Mirrors the
+    production owner-checked removal semantics — the resume tail passes
+    ``owner`` and peeks ``get_dispatch_fn`` before re-registering."""
+
+    def __init__(self) -> None:
+        self.events: list[tuple[str, str]] = []
+        self.fns: dict[str, Any] = {}
+
+    def set_dispatch_fn(self, ws_id: str, fn: Any) -> None:
+        self.events.append(("set", ws_id))
+        self.fns[ws_id] = fn
+
+    def get_dispatch_fn(self, ws_id: str) -> Any:
+        return self.fns.get(ws_id)
+
+    def remove_dispatch_fn(self, ws_id: str, owner: Any = None) -> None:
+        if owner is not None and self.fns.get(ws_id) is not owner:
+            return
+        self.events.append(("remove", ws_id))
+        self.fns.pop(ws_id, None)
+
+
+class TestResumeReRegistration:
+    """A non-fork ``resume()`` rebinds ``_ws_id``; the dispatch
+    registration must FOLLOW that identity — otherwise watches stamped
+    with the adopted id never find the live session, and every fire
+    takes the restore path, spawning a duplicate auto-approved session
+    racing writes into the same conversation (CLI ``--resume`` and the
+    ``/resume`` command both hit this)."""
+
+    def _saved_ws(self, ws_id: str) -> None:
+        from turnstone.core.memory import register_workstream, save_message
+
+        register_workstream(ws_id)
+        save_message(ws_id, "user", "hi")
+
+    def test_nonfork_resume_moves_registration_to_adopted_id(self, tmp_db):
+        self._saved_ws("resume-target")
+        session = _make_session_for_dispatch()
+        old_id = session._ws_id
+        runner = _RecordingRunner()
+        session.set_watch_runner(runner, wake_fn=None)
+
+        assert session.resume("resume-target") is True
+
+        # New key live BEFORE the old key is removed — a fire during the
+        # transition can never observe an empty registry (which would
+        # divert it to the restore path).
+        assert runner.events == [
+            ("set", old_id),
+            ("set", "resume-target"),
+            ("remove", old_id),
+        ]
+        assert set(runner.fns) == {"resume-target"}
+
+    def test_fork_resume_keeps_registration(self, tmp_db):
+        self._saved_ws("fork-src")
+        session = _make_session_for_dispatch()
+        old_id = session._ws_id
+        runner = _RecordingRunner()
+        session.set_watch_runner(runner, wake_fn=None)
+
+        assert session.resume("fork-src", fork=True) is True
+
+        # Fork keeps its own identity — registration untouched.
+        assert runner.events == [("set", old_id)]
+
+    def test_resume_without_runner_is_noop(self, tmp_db):
+        # CLI --resume / restore-fn shape: resume() runs BEFORE any
+        # set_watch_runner call — nothing to re-register, nothing raises.
+        self._saved_ws("resume-bare")
+        session = _make_session_for_dispatch()
+
+        assert session.resume("resume-bare") is True
+        assert session._watch_runner is None
+
+    def test_reregistered_closure_keeps_wake_fn(self, tmp_db):
+        # The stored wake_fn rides the re-registration: a watch firing on
+        # the ADOPTED id must still wake the workstream.
+        self._saved_ws("resume-wake")
+        session = _make_session_for_dispatch()
+        runner = _RecordingRunner()
+        wake = MagicMock()
+        session.set_watch_runner(runner, wake_fn=wake)
+
+        assert session.resume("resume-wake") is True
+
+        runner.fns["resume-wake"](_reminder("watch output"), "w1")
+        assert len(session._nudge_queue) == 1
+        wake.assert_called_once()
+
+    def test_resume_does_not_steal_another_live_registration(self, tmp_db):
+        # In-session /resume of a workstream that is OPEN IN ANOTHER PANE
+        # (a degenerate two-live-sessions state): the original owner keeps
+        # its watch fires — the adopter neither clobbers the target's
+        # registration nor (on a later resume-away or close) deletes it.
+        self._saved_ws("shared-A")
+        self._saved_ws("other-C")
+        runner = _RecordingRunner()
+
+        pane_a = _make_session_for_dispatch()
+        pane_a._ws_id = "shared-A"  # pane A opened A and registered
+        pane_a.set_watch_runner(runner, wake_fn=None)
+        fn_a = runner.fns["shared-A"]
+
+        pane_b = _make_session_for_dispatch()
+        pane_b.set_watch_runner(runner, wake_fn=None)
+
+        assert pane_b.resume("shared-A") is True
+        # Pane A's registration survived the adoption…
+        assert runner.fns["shared-A"] is fn_a
+
+        assert pane_b.resume("other-C") is True
+        # …and the resume-away removed only pane B's own (absent) claim.
+        assert runner.fns["shared-A"] is fn_a
+        assert "other-C" in runner.fns
+
+    def test_new_command_moves_registration_to_fresh_id(self, tmp_db):
+        # /new is the other identity rebind: watches created AFTER it stamp
+        # the fresh id and must reach this session, while the old
+        # workstream's fires must stop landing in a conversation that no
+        # longer shows them (they divert to the restore path instead).
+        session = _make_session_for_dispatch()
+        old_id = session._ws_id
+        runner = _RecordingRunner()
+        session.set_watch_runner(runner, wake_fn=None)
+
+        # handle_command's return means "should exit" — /new never exits.
+        assert session.handle_command("/new") is False
+
+        assert session._ws_id != old_id
+        assert set(runner.fns) == {session._ws_id}
+        assert ("remove", old_id) in runner.events
+
+    def test_close_removes_only_own_registration(self, tmp_db):
+        # A watch-restore shell and a reopened pane can serve one ws_id in
+        # sequence; the shell's later teardown must not unregister the pane.
+        self._saved_ws("shared-W")
+        runner = _RecordingRunner()
+
+        shell = _make_session_for_dispatch()
+        shell._ws_id = "shared-W"
+        shell.set_watch_runner(runner, wake_fn=None)
+
+        pane = _make_session_for_dispatch()
+        pane._ws_id = "shared-W"
+        pane.set_watch_runner(runner, wake_fn=None)  # pane re-registers (last writer)
+        pane_fn = runner.fns["shared-W"]
+
+        shell.close()  # shell reaped (close_idle / eviction)
+
+        assert runner.fns.get("shared-W") is pane_fn  # pane still registered

tests/test_watch_integration.py

@@ -340,8 +340,8 @@ def test_poll_watch_terminal_fire_survives_drain(
     monkeypatch.setattr(session._nudge_queue, "enqueue", _spy_enqueue)
 
     # For the max_polls=1 case the first poll has prev_output=None and
-    # would not normally fire on output change; the max_polls branch
-    # at watch.py:412-414 still marks is_final=True so dispatch runs.
+    # would not normally fire on output change; _poll_watch's max_polls
+    # branch still marks is_final=True so dispatch runs.
     due = storage.list_due_watches("2099-01-01T00:00:00")
     matching = [r for r in due if r["watch_id"] == f"w-regression-{label}"]
     assert len(matching) == 1, f"watch row not picked up by list_due_watches: {due!r}"

tests/test_web_helpers.py

@@ -114,3 +114,85 @@ class TestVersionHtml:
         html = '<script src="/static/app.js?foo=bar"></script>'
         result = version_html(html)
         assert result == html  # unchanged — already has query string
+
+
+class TestLatin1SafeFilename:
+    """Content-Disposition filename sanitizer — must yield a value that is
+    both latin-1 encodable (Starlette) and control-char free (h11)."""
+
+    def _assert_wire_safe(self, out: str) -> None:
+        # Independent oracle — deliberately does NOT reuse the impl's
+        # isprintable() gate (that would pass by construction). Every char
+        # must be printable ASCII (0x20..0x7e) and neither quoted-string
+        # metacharacter, so the value is latin-1 clean, control-free, and
+        # safely quotable.
+        assert all(0x20 <= ord(c) <= 0x7E and c not in '"\\' for c in out)
+
+    def test_plain_ascii_unchanged(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        assert latin1_safe_filename("report_2026.md") == "report_2026.md"
+
+    def test_non_latin1_folds_to_question_marks(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        # CJK + em dash (U+2014) are printable but non-latin-1 → fold to '?'.
+        out = latin1_safe_filename("文書 — v1.md")
+        assert out == "?? ? v1.md"
+        self._assert_wire_safe(out)
+
+    def test_latin1_but_control_chars_are_stripped(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        # All latin-1 encodable, so the old strip/fold left them in the header
+        # and the HTTP server layer then 500'd (h11 rejects NUL/CR/LF/FF/VT;
+        # httptools is stricter). NUL / form-feed / DEL / TAB / VT / C1-NEL
+        # (0x85) must all be dropped, not merely folded.
+        out = latin1_safe_filename("a\x00b\x0cc\x7fd\te\x0bf\x85g.md")
+        assert out == "abcdefg.md"
+        self._assert_wire_safe(out)
+
+    def test_crlf_and_quote_stripped(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        out = latin1_safe_filename('a"\r\nX-Evil: 1.md')
+        assert "\r" not in out and "\n" not in out and '"' not in out
+        self._assert_wire_safe(out)
+
+    def test_backslash_stripped(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        # Backslash is the RFC 6266 quoted-pair escape inside filename="..." —
+        # a trailing '\' would escape the closing quote, and '\x' mid-name
+        # becomes a spurious escape. Both must be dropped (Windows-origin
+        # uploads legitimately carry '\').
+        assert latin1_safe_filename("dir\\file.md") == "dirfile.md"
+        assert latin1_safe_filename("trailing\\") == "trailing"
+        self._assert_wire_safe(latin1_safe_filename("a\\b\\c"))
+
+    def test_empty_after_sanitizing_uses_fallback(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        # A name of only quotes / controls sanitizes to empty → fallback,
+        # never ``filename=""``.
+        assert latin1_safe_filename('"""') == "attachment"
+        assert latin1_safe_filename("\x00\x0c\x7f") == "attachment"
+        assert latin1_safe_filename("", fallback="preview") == "preview"
+
+    def test_all_non_latin1_stays_non_empty_no_fallback(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        # An all-CJK name folds to '???' (truthy) — must NOT hit the fallback.
+        assert latin1_safe_filename("日本語", fallback="preview") == "???"
+
+    def test_fallback_is_also_sanitized(self):
+        from turnstone.core.web_helpers import latin1_safe_filename
+
+        # The fallback fires only when the name sanitizes to empty, and it is
+        # cleaned by the SAME rules — a caller can't reintroduce the crash /
+        # corruption through an unsafe fallback.
+        assert latin1_safe_filename("", fallback="—\x00.txt") == "?.txt"
+        self._assert_wire_safe(latin1_safe_filename("", fallback="bad\\\x00name"))
+        # If even the fallback sanitizes to empty, a safe constant backs it —
+        # never filename="".
+        assert latin1_safe_filename("", fallback='"\x00') == "download"

tests/test_webui_content.py

@@ -32,8 +32,14 @@ def _drain_global() -> list[dict]:
 class TestContentAccumulation:
     """WebUI should accumulate content tokens and include in idle broadcast."""
 
-    def test_content_token_accumulates(self):
-        """on_content_token should append to _ws_turn_content."""
+    def test_content_token_accumulates(self, monkeypatch):
+        """on_content_token should append to _ws_turn_content.
+
+        Batch window forced to 0 (per-token flush) — this pins the
+        accumulator wiring, not the emit-time batching cadence (which
+        coalesces fragments; see test_sse_token_batching.py)."""
+
+        monkeypatch.setattr("turnstone.core.session_ui_base._TOKEN_BATCH_WINDOW_SECS", 0.0)
         ui = _make_ui()
         ui.on_content_token("Hello ")
         ui.on_content_token("world")

tests/test_wire_payload_golden.py

@@ -23,6 +23,7 @@ the affected golden and inspecting the diff.
 from __future__ import annotations
 
 import contextlib
+import dataclasses
 import json
 import os
 from pathlib import Path
@@ -308,3 +309,53 @@ def test_wire_payload_anthropic_compat(fixture_id: str) -> None:
     )
     assert "thinking" not in payload, "compat lane must never send the native thinking param"
     _assert_golden(f"anthropic_compat__{fixture_id}", payload)
+
+
+# GPT-5.6 Sol is the first COMMERCIAL OpenAI model to expose the "max"
+# reasoning effort (Terra/Luna cap at "xhigh"; see OPENAI_CAPABILITIES).
+# The base matrix above pins only the default-effort Responses shape
+# (gpt-5 → "medium"), so freeze a max-effort request to prove the new
+# level compiles onto the native ``reasoning={"effort": "max"}`` param.
+# Driving it through "gpt-5.6-sol" also exercises the longest-prefix
+# inheritance (that id resolves to the "gpt-5.6" row) on the real wire,
+# not just the capability lookup — over a bare turn and a tool round-trip.
+_OPENAI_MAX_FIXTURES = ("text", "toolcall_complete")
+
+
+@pytest.mark.parametrize("fixture_id", _OPENAI_MAX_FIXTURES)
+def test_wire_payload_openai_max(fixture_id: str) -> None:
+    messages, opts = _FIXTURES[fixture_id]
+    provider = OpenAIResponsesProvider()
+    payload = _capture(
+        provider,
+        model="gpt-5.6-sol",
+        messages=[dict(m) for m in messages],
+        reasoning_effort="max",
+        **opts,
+    )
+    assert payload["reasoning"] == {"effort": "max"}, "max must compile onto reasoning.effort"
+    _assert_golden(f"openai_responses_max__{fixture_id}", payload)
+
+
+def test_wire_payload_openai_verbosity_pro() -> None:
+    """Operator-declared verbosity + pro mode compile onto ``text.verbosity``
+    and ``reasoning.mode`` for GPT-5.6 Sol.  Both are default-off; an operator
+    turns them on via the model-definition capabilities JSON, which
+    ``ChatSession._resolve_capabilities`` merges into caps at request time —
+    modeled here by the ``dataclasses.replace`` override _capture forwards."""
+    provider = OpenAIResponsesProvider()
+    caps = dataclasses.replace(
+        provider.get_capabilities("gpt-5.6-sol"), verbosity="low", reasoning_mode="pro"
+    )
+    messages, opts = _FIXTURES["text"]
+    payload = _capture(
+        provider,
+        model="gpt-5.6-sol",
+        messages=[dict(m) for m in messages],
+        caps=caps,
+        reasoning_effort="high",
+        **opts,
+    )
+    assert payload["text"] == {"verbosity": "low"}
+    assert payload["reasoning"] == {"effort": "high", "mode": "pro"}
+    _assert_golden("openai_responses_verbosity_pro__text", payload)

turnstone/__init__.py

@@ -1,3 +1,3 @@
 """turnstone - Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."""
 
-__version__ = "1.7.1"
+__version__ = "1.7.3"

turnstone/api/console_schemas.py

@@ -151,6 +151,10 @@ class ConsoleCreateWsRequest(BaseModel):
         default="",
         description="Persona slug; resolved and snapshotted at creation, empty = kind default",
     )
+    project_id: str = Field(
+        default="",
+        description="Project to attach the workstream to (validated against membership, empty = none)",
+    )
     resume_ws: str = Field(
         default="", description="Workstream ID to resume (loads previous conversation)"
     )

turnstone/api/schemas.py

@@ -195,6 +195,8 @@ class CreateScheduleRequest(BaseModel):
     auto_approve: bool = Field(default=False)
     auto_approve_tools: list[str] = Field(default_factory=list)
     skill: str = Field(default="", description="Skill name (replaces default skills)")
+    persona: str = Field(default="", description="Persona slug (empty = kind default)")
+    project_id: str = Field(default="", description="Project to attach the workstream to")
     notify_targets: list[dict[str, str]] = Field(
         default_factory=list,
         description="Notification targets on completion (channel_type + channel_id/user_id)",
@@ -216,6 +218,8 @@ class UpdateScheduleRequest(BaseModel):
     auto_approve: bool | None = None
     auto_approve_tools: list[str] | None = None
     skill: str | None = None
+    persona: str | None = None
+    project_id: str | None = None
     notify_targets: list[dict[str, str]] | None = None
     enabled: bool | None = None
 
@@ -235,6 +239,8 @@ class ScheduleInfo(BaseModel):
     auto_approve: bool = False
     auto_approve_tools: list[str] = Field(default_factory=list)
     skill: str = ""
+    persona: str = ""
+    project_id: str = ""
     notify_targets: list[dict[str, str]] = Field(default_factory=list)
     enabled: bool = True
     created_by: str = ""

turnstone/api/server_schemas.py

@@ -224,6 +224,17 @@ class CreateWorkstreamResponse(BaseModel):
             "/v1/api/workstreams/{ws_id}/send."
         ),
     )
+    initial_message_status: Literal["queue_full", "refused_closed"] | None = Field(
+        default=None,
+        description=(
+            "Present ONLY when the workstream was created but its "
+            "initial_message could not be delivered: 'queue_full' (a raced "
+            "live worker's interjection queue was at capacity — resend via "
+            "/send; any uploads stay staged) or 'refused_closed' (the "
+            "workstream was closed mid-create). Absent whenever the message "
+            "was dispatched."
+        ),
+    )
 
 
 class CloseWorkstreamRequest(BaseModel):

turnstone/cli.py

@@ -277,7 +277,11 @@ class TerminalUI(SessionUI):
         output: str,
         *,
         is_error: bool = False,
+        preview: dict[str, Any] | None = None,
     ) -> None:
+        # ``preview`` renders nowhere in a terminal -- the result line already
+        # names what was shown, and the header carries the target for the
+        # operator to open themselves.
         if is_error:
             with self._print_lock:
                 sys.stderr.write(f"{RED}\u2717 {name}: {output}{RESET}\n")
@@ -479,9 +483,10 @@ class WorkstreamTerminalUI(TerminalUI):
         output: str,
         *,
         is_error: bool = False,
+        preview: dict[str, Any] | None = None,
     ) -> None:
         if self.is_foreground:
-            super().on_tool_result(call_id, name, output, is_error=is_error)
+            super().on_tool_result(call_id, name, output, is_error=is_error, preview=preview)
 
     def on_tool_output_chunk(self, call_id: str, chunk: str) -> None:
         if self.is_foreground:

turnstone/console/scheduler.py

@@ -318,6 +318,8 @@ class TaskScheduler:
                 auto_approve_tools=",".join(self._parse_tools(task)),
                 user_id=task.get("created_by", ""),
                 skill=task.get("skill", ""),
+                persona=task.get("persona", ""),
+                project_id=task.get("project_id", ""),
                 notify_targets=task.get("notify_targets", "[]"),
                 # Mark the resulting ChatSession as non-interactive-for-
                 # consent so OAuth-MCP errors get persisted to

turnstone/console/server.py

@@ -3154,6 +3154,25 @@ async def proxy_non_api(request: Request) -> Response:
     return await _proxy_get(request, server_url, path)
 
 
+# Upstream response headers the generic proxy must carry through.  These are
+# the node's hardening + disposition headers: dropping Content-Security-Policy
+# would serve previewed attacker HTML from the CONSOLE origin with no CSP
+# sandbox — opened top-level, its scripts would run with the operator's
+# console cookies, where the same bytes on the node origin are inert.  The
+# rendezvous attachment proxy (route_attachment_proxy) already preserves
+# these; the /node/{id} lane must match.
+_PROXY_PASS_HEADERS = (
+    "content-security-policy",
+    "x-content-type-options",
+    "content-disposition",
+    "cache-control",
+)
+
+
+def _proxy_pass_headers(resp: httpx.Response) -> dict[str, str]:
+    return {h: resp.headers[h] for h in _PROXY_PASS_HEADERS if h in resp.headers}
+
+
 async def _proxy_get(request: Request, server_url: str, path: str) -> Response:
     """Forward a GET request to the target server."""
     client: httpx.AsyncClient = request.app.state.proxy_client
@@ -3166,6 +3185,7 @@ async def _proxy_get(request: Request, server_url: str, path: str) -> Response:
             content=resp.content,
             status_code=resp.status_code,
             media_type=resp.headers.get("content-type", "application/json"),
+            headers=_proxy_pass_headers(resp),
         )
     except httpx.HTTPError as exc:
         log.debug("Proxy GET error for %s: %s", target, exc)
@@ -6075,6 +6095,43 @@ def _validate_schedule_fields(schedule_type: str, cron_expr: str, at_time: str)
     return None
 
 
+def _resolve_schedule_persona(storage: Any, persona: str) -> tuple[str, str | None]:
+    """Validate a schedule's persona slug against the interactive kind.
+
+    Schedules dispatch interactive workstreams, so the persona is resolved
+    against that kind — the same eligibility rule the create handler applies,
+    surfaced here so a bad slug fails at edit time rather than silently at the
+    next firing.  Returns ``(canonical_slug, None)`` on success (the resolved
+    row's name, never the raw input, per the persona contract) or
+    ``("", error)`` on failure.  Empty persona = kind default, always valid.
+    """
+    if not persona:
+        return "", None
+    from turnstone.core.personas import resolve_persona_for_kind
+
+    row, err = resolve_persona_for_kind(storage, persona, "interactive")
+    if err:
+        return "", err
+    return (str(row["name"]) if row else persona), None
+
+
+def _validate_schedule_project(
+    storage: Any, user_id: str, project_id: str
+) -> tuple[int, str] | None:
+    """Gate attaching a schedule's dispatched workstream to *project_id*.
+
+    Checked against *user_id* — the schedule's ``created_by``, the identity the
+    scheduler dispatches under — so the same owner/member rule the node enforces
+    at dispatch is applied up front.  Returns ``None`` when allowed, else the
+    ``(status, message)`` to surface.  Empty project_id = no attach, allowed.
+    """
+    if not project_id:
+        return None
+    from turnstone.core.auth import ensure_project_attachable
+
+    return ensure_project_attachable(user_id, project_id, storage=storage)
+
+
 async def admin_preview_schedule(request: Request) -> JSONResponse:
     """POST /v1/api/admin/schedules/preview — validate timing, return next runs.
 
@@ -6168,7 +6225,17 @@ async def admin_create_schedule(request: Request) -> JSONResponse:
     raw_tools = body.get("auto_approve_tools", [])
     auto_approve_tools = raw_tools if isinstance(raw_tools, list) else []
     skill_name = str(body.get("skill", "")).strip()[:256]
+    persona = str(body.get("persona", "")).strip()[:64]
+    project_id = str(body.get("project_id", "")).strip()[:64]
     enabled = bool(body.get("enabled", True))
+    # created_by is the authenticated admin — read via auth_result like every
+    # other console endpoint (AuthMiddleware never sets request.state.user_id,
+    # so the previous ``state.user_id`` read silently stored ""). It is now
+    # load-bearing: the scheduler dispatches under this identity and the node
+    # gates the project attach against it, so an empty value would make every
+    # project-scoped schedule fail the attach.
+    auth_result = getattr(getattr(request, "state", None), "auth_result", None)
+    created_by = getattr(auth_result, "user_id", "") or ""
 
     # Validate notify_targets
     from turnstone.server import _validate_notify_targets
@@ -6188,6 +6255,13 @@ async def admin_create_schedule(request: Request) -> JSONResponse:
         return JSONResponse({"error": "initial_message is required"}, status_code=400)
     if skill_name and not storage.get_prompt_template_by_name(skill_name):
         return JSONResponse({"error": f"Skill not found: {skill_name}"}, status_code=400)
+    persona, persona_err = _resolve_schedule_persona(storage, persona)
+    if persona_err:
+        return JSONResponse({"error": persona_err}, status_code=400)
+    project_denied = _validate_schedule_project(storage, created_by, project_id)
+    if project_denied is not None:
+        status_code, message = project_denied
+        return JSONResponse({"error": message}, status_code=status_code)
 
     validation_err = _validate_schedule_fields(schedule_type, cron_expr, at_time)
     if validation_err:
@@ -6206,7 +6280,6 @@ async def admin_create_schedule(request: Request) -> JSONResponse:
 
     next_run = _compute_next_run(schedule_type, cron_expr, at_time)
     task_id = uuid.uuid4().hex
-    created_by = getattr(getattr(request, "state", None), "user_id", "")
 
     storage.create_scheduled_task(
         task_id=task_id,
@@ -6224,6 +6297,8 @@ async def admin_create_schedule(request: Request) -> JSONResponse:
         next_run=next_run if enabled else "",
         skill=skill_name,
         notify_targets=notify_targets,
+        persona=persona,
+        project_id=project_id,
     )
 
     if not enabled:
@@ -6303,6 +6378,47 @@ async def admin_update_schedule(request: Request) -> JSONResponse:
         if skill_val and not storage.get_prompt_template_by_name(skill_val):
             return JSONResponse({"error": f"Skill not found: {skill_val}"}, status_code=400)
         updates["skill"] = skill_val
+    if "persona" in body:
+        persona_val = str(body["persona"]).strip()[:64]
+        # Re-validate only when the persona actually changes: the edit shelf
+        # always resends the current slug, and a schedule whose persona was
+        # since disabled (or the picker couldn't show) must stay editable for
+        # its other fields. A stale persona still fails loudly at dispatch,
+        # where the node re-resolves it.
+        if persona_val != (existing.get("persona") or ""):
+            persona_val, persona_err = _resolve_schedule_persona(storage, persona_val)
+            if persona_err:
+                return JSONResponse({"error": persona_err}, status_code=400)
+        updates["persona"] = persona_val
+    if "project_id" in body:
+        project_val = str(body["project_id"]).strip()[:64]
+        # Re-gate only when the project actually changes: the edit shelf
+        # resends the current value, and membership churn (or a project the
+        # editing admin can't see) must not block unrelated edits — the node
+        # re-gates against the owner at dispatch. On an actual change, the
+        # schedule dispatches under created_by and the node gates the attach
+        # against it, so a schedule created before the created_by fix ("")
+        # could never attach. When a project is assigned to such an orphaned
+        # schedule, adopt the editing admin as its owner (never overriding a
+        # real created_by) and persist it so the create-time check and the
+        # dispatch identity agree.
+        if project_val != (existing.get("project_id") or ""):
+            editing_admin = (
+                getattr(
+                    getattr(getattr(request, "state", None), "auth_result", None),
+                    "user_id",
+                    "",
+                )
+                or ""
+            )
+            owner = existing.get("created_by", "") or editing_admin
+            project_denied = _validate_schedule_project(storage, owner, project_val)
+            if project_denied is not None:
+                status_code, message = project_denied
+                return JSONResponse({"error": message}, status_code=status_code)
+            if project_val and not existing.get("created_by", ""):
+                updates["created_by"] = owner
+        updates["project_id"] = project_val
     if "enabled" in body:
         updates["enabled"] = bool(body["enabled"])
     if "notify_targets" in body:

turnstone/console/static/admin.js

@@ -1329,8 +1329,10 @@ function _populateScheduleSelect(selectId, url, labelKey, valueKey, opts) {
     .then(function (data) {
       const temp = sel.querySelector("[data-temporary]");
       if (temp) temp.remove();
-      const items = opts && opts.listKey ? data[opts.listKey] : data;
+      let items = opts && opts.listKey ? data[opts.listKey] : data;
       if (!Array.isArray(items)) return;
+      if (opts && typeof opts.filter === "function")
+        items = items.filter(opts.filter);
       items.forEach(function (item) {
         const opt = document.createElement("option");
         opt.value = item[valueKey];
@@ -1338,7 +1340,22 @@ function _populateScheduleSelect(selectId, url, labelKey, valueKey, opts) {
           opts && opts.display ? opts.display(item) : item[labelKey];
         sel.appendChild(opt);
       });
-      if (opts && opts.selected) sel.value = opts.selected;
+      if (opts && opts.selected) {
+        sel.value = opts.selected;
+        if (sel.value !== opts.selected) {
+          // The current value isn't in this list — it was filtered out
+          // (a disabled/wrong-kind persona) or is outside the caller-scoped
+          // feed (a private/archived project the editing admin can't see).
+          // Re-add it as a "(current)" option so it round-trips; without this
+          // the select falls back to the placeholder and saving an unrelated
+          // field would silently CLEAR the setting.
+          const keep = document.createElement("option");
+          keep.value = opts.selected;
+          keep.textContent = opts.selected + " (current)";
+          sel.appendChild(keep);
+          sel.value = opts.selected;
+        }
+      }
       // Caller hook for placeholder annotation / other post-load tweaks.
       // Used by the schedule modals to rewrite the bare "Default model"
       // placeholder with the resolved alias so the label matches the
@@ -1923,7 +1940,12 @@ function _schResetForm() {
   _schSetMode("daily");
 }
 
-function _schPopulateSelects(selectedModel, selectedSkill) {
+function _schPopulateSelects(
+  selectedModel,
+  selectedSkill,
+  selectedPersona,
+  selectedProject,
+) {
   _populateScheduleSelect("sch-model", "/v1/api/models", "alias", "alias", {
     listKey: "models",
     selected: selectedModel || "",
@@ -1945,6 +1967,32 @@ function _schPopulateSelects(selectedModel, selectedSkill) {
       },
     },
   );
+  // Schedules dispatch interactive workstreams, so only offer personas
+  // eligible for that kind; the label matches the home/create picker
+  // (display name, falling back to the slug).
+  _populateScheduleSelect("sch-persona", "/v1/api/personas", "name", "name", {
+    listKey: "personas",
+    selected: selectedPersona || "",
+    filter: function (p) {
+      return (p.applies_to_kinds || []).indexOf("interactive") !== -1;
+    },
+    display: function (p) {
+      return p.display_name || p.name;
+    },
+  });
+  _populateScheduleSelect(
+    "sch-project",
+    "/v1/api/projects",
+    "name",
+    "project_id",
+    {
+      listKey: "projects",
+      selected: selectedProject || "",
+      display: function (p) {
+        return p.name;
+      },
+    },
+  );
 }
 
 function _schOpen(title, tag, kind, submitLabel) {
@@ -1962,7 +2010,7 @@ function showCreateScheduleModal() {
   _schWire();
   _schResetForm();
   document.getElementById("sch-enabled-row").hidden = true;
-  _schPopulateSelects("", "");
+  _schPopulateSelects("", "", "", "");
   _schOpen("New schedule", "SCH-NEW", "create", "Create");
 }
 
@@ -1991,7 +2039,12 @@ function showEditScheduleModal(taskId) {
         ? s.target_mode
         : "";
       document.getElementById("sch-node-group").hidden = !isSpecificNode;
-      _schPopulateSelects(s.model || "", s.skill || "");
+      _schPopulateSelects(
+        s.model || "",
+        s.skill || "",
+        s.persona || "",
+        s.project_id || "",
+      );
       document.getElementById("sch-message").value = s.initial_message || "";
       document.getElementById("sch-autoapprove").checked = !!s.auto_approve;
       document.getElementById("sch-enabled").checked = !!s.enabled;
@@ -2036,6 +2089,8 @@ function _submitScheduleShelf() {
     target_mode: targetMode,
     model: (document.getElementById("sch-model").value || "").trim(),
     skill: (document.getElementById("sch-template").value || "").trim(),
+    persona: (document.getElementById("sch-persona").value || "").trim(),
+    project_id: (document.getElementById("sch-project").value || "").trim(),
     initial_message: message,
     auto_approve: document.getElementById("sch-autoapprove").checked,
     notify_targets: _collectNotifyTargets("sch"),

turnstone/console/static/coordinator/coordinator.js

@@ -41,6 +41,15 @@ import {
   indexLabel,
 } from "/shared/conversation.js";
 import { redactCredentials } from "/shared/redact_credentials.js";
+import {
+  OVERFLOW_TRIP_COUNT,
+  OVERFLOW_TRIP_WINDOW_MS,
+  DEGRADED_COOLDOWN_BASE_MS,
+  DEGRADED_COOLDOWN_MAX_MS,
+  DEGRADED_COOLDOWN_RESET_MS,
+  overflowWindowTripped,
+  degradedCooldownStep,
+} from "/shared/sse_overflow.js";
 
 function buildCoordChrome(root, opts) {
   opts = opts || {};
@@ -430,15 +439,40 @@ function createCoordinatorPane(root, wsId, opts) {
 
   let evtSource = null;
   let reconnectAttempts = 0;
-  // Flag set in onerror, cleared in onopen.  Drives the "did we
-  // just recover from a gap?" decision in onopen so the replace-
-  // mode refresh of children/tasks/wait/badge caches fires on
-  // every reconnect — including the common case where native
-  // EventSource auto-reconnect handles the underlying SSE transition
-  // without scheduleReconnect running (which used to be the only
-  // place reconnectAttempts incremented; that path is rarely hit
-  // now that native reconnect handles transient errors).
-  let disconnectedSinceLastOpen = false;
+  // Wall-clock start of the CURRENT gap (0 = no gap in progress).  Stamped by
+  // markStreamGap (from onerror and every deliberate suspend), cleared by
+  // onopen.  A non-zero value IS the "did we just recover from a gap?" flag
+  // that drives onopen's replace-mode children/tasks/badge refresh — no
+  // separate boolean is kept in lockstep with it.  Kept at the EARLIEST mark
+  // so repeated onerror fires during one outage don't shrink the measured gap.
+  // (The scheduleReconnect-after-CLOSED path bumps reconnectAttempts instead;
+  // wasReconnecting ORs the two — that path is rarely hit now that native
+  // reconnect handles transient errors.)
+  let disconnectedAt = 0;
+  // Reconnect-replay trust window for the sidebar.  child_ws_* / task events
+  // are ordinary ring-buffer entries, so a cursor reconnect (replay_ok)
+  // redelivers them and the sidebar heals without any REST refetch; gaps the
+  // ring could NOT cover announce themselves via replay_truncated.  The one
+  // blind spot is a stale cursor the server no longer recognises (process
+  // restart resets event ids; the empty/reset ring reports replay_ok and
+  // silently skips the gap).  Past this gap length we stop trusting the cursor
+  // and pull authoritative /children + /tasks state; a FASTER restart (under
+  // the threshold) is caught instead by the backwards-event-id check in
+  // onmessage (a live id below our saved cursor == the counter reset).
+  // Momentary blur/focus cycles stay well below the threshold — no rebuild
+  // flicker on an alt-tab.
+  const GAP_REFRESH_THRESHOLD_MS = 60000;
+  // True when THIS connection's onopen already ran refreshSidebarAfterGap —
+  // lets the replay_truncated handler (first frame after open) skip a
+  // back-to-back duplicate of the refresh it would otherwise trigger.
+  let gapRefreshedAtOpen = false;
+  // Set when replay_truncated arrives while a turn is mid-stream (refetching
+  // then would detach the live bubble); consumed on the next state_change=idle.
+  // Mirrors interactive.js's _pendingTruncatedResync — the deferral keeps a
+  // ring-evicted gap from going unrepaired for the rest of the session, and
+  // also catches a turn stranded by close-on-hide (finished while hidden, its
+  // stream_end evicted before the show-edge reconnect).
+  let pendingTruncatedResync = false;
   // Saved high-water mark for the manual-reconnect path.  The
   // EventSource constructor can't set custom headers, so when we
   // construct a fresh source we thread ``?last_event_id=N`` instead
@@ -449,6 +483,28 @@ function createCoordinatorPane(root, wsId, opts) {
   // close).
   let lastEventId = null;
   let reconnectTimer = null;
+  // --- SSE overflow-recovery state (client half — mirrors interactive.js) ---
+  // Field instrumentation for the two distinct "output stops while the backend
+  // is healthy" causes: server-signalled overflow closes (dropped-events
+  // class) vs client dispatch/render throws (wedge class).  The console line
+  // at each increment carries the running count, so a field report shows which
+  // class fired without a debugger attached.
+  const streamHealth = { overflows: 0, renderThrows: 0, malformedFrames: 0 };
+  // Rolling timestamps of stream_overflow closes feeding the degraded-catchup
+  // limiter (overflowWindowTripped); plus the cooldown-ladder state, keyed off
+  // the last-trip timestamp via degradedCooldownStep — never off overflowTimes
+  // (enterDegradedCatchup clears it each trip).  See enterDegradedCatchup.
+  const overflowTimes = [];
+  let degradedTimer = null;
+  let degradedCooldownMs = DEGRADED_COOLDOWN_BASE_MS;
+  let lastDegradedAt = 0;
+  // Close-on-hide / replay-on-show bookkeeping.  A hidden tab's throttled event
+  // loop is the likeliest too-slow SSE consumer, so the visibilitychange
+  // handler closes the stream on hide and reconnects with the saved lastEventId
+  // on show (replay_ok covers the gap).  hiddenDisconnect marks that WE closed
+  // for hide, so show never resurrects a stream closed deliberately elsewhere.
+  let visHandler = null;
+  let hiddenDisconnect = false;
   // Ids of operator-context system turns already painted from /history.  A
   // later SSE replay that redelivers one (resume-cursor overlap) is skipped
   // by the system_turn handler — reset per refetchHistory.  Mirrors
@@ -1681,7 +1737,7 @@ function createCoordinatorPane(root, wsId, opts) {
       try {
         streamingRender(body, currentAssistantBuf);
       } catch (e) {
-        console.warn("coordinator streamingRender failed", e);
+        noteRenderThrow("streamingRender", e);
         body.textContent = currentAssistantBuf;
       }
     } else if (body) {
@@ -1719,7 +1775,7 @@ function createCoordinatorPane(root, wsId, opts) {
         try {
           streamingRenderFinalize(body, currentAssistantBuf);
         } catch (e) {
-          console.warn("coordinator streamingRenderFinalize failed", e);
+          noteRenderThrow("streamingRenderFinalize", e);
         }
       }
     }
@@ -2090,11 +2146,13 @@ function createCoordinatorPane(root, wsId, opts) {
       }
     };
     try {
-      if (evtSource) evtSource.close();
-      if (reconnectTimer) {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-      }
+      suspendStream();
+      // Session teardown owns the stream from here: a tab hide→show while
+      // the /close POST is in flight must NOT reopen a stream against the
+      // workstream the server is tearing down (404 / reconnect churn against
+      // a dead session).  connectSSE reinstalls the handler, so the failure
+      // paths below get close-on-hide back for free via resumeSse.
+      removeVisibilityHandler();
     } catch (_) {
       /* best-effort suspension */
     }
@@ -2184,32 +2242,47 @@ function createCoordinatorPane(root, wsId, opts) {
     }
   }
 
-  function connectSSE() {
-    if (reconnectTimer) {
-      clearTimeout(reconnectTimer);
-      reconnectTimer = null;
-    }
+  // The transport-teardown chokepoint: close + null the EventSource and
+  // cancel BOTH pending retry timers (reconnect backoff + degraded catch-up).
+  // Every teardown path routes through here — connectSSE's redial prologue,
+  // suspendStream (overflow / hide / close-session), destroy — so a new
+  // transport timer gets cancelled in one place instead of by hand at each
+  // call site.  Cancelling the degraded timer on redial also keeps a pending
+  // catch-up retry from firing mid-stream and double-opening;
+  // enterDegradedCatchup re-arms AFTER its own suspend, so this never cancels
+  // the timer it is about to set.  Gap accounting stays OUT of this helper —
+  // a redial is not itself a gap (suspendStream layers markStreamGap on top).
+  function closeStreamTransport() {
     if (evtSource) {
       try {
         evtSource.close();
       } catch (_) {
         /* noop */
       }
+      evtSource = null;
     }
-    setSseStatus("connecting…", "");
-    // Snapshot whether this is a reconnect BEFORE resetting
-    // reconnectAttempts in onopen — child_ws_* events dispatched while
-    // we were disconnected aren't replayed by the events SSE handler,
-    // so the client has to pull authoritative state after any gap.
-    // Snapshot whether this connect attempt follows a prior
-    // disconnect.  Native EventSource auto-reconnect no longer
-    // routes through scheduleReconnect on the transient-error path,
-    // so the legacy ``reconnectAttempts > 0`` check is always false
-    // after PR-D — use ``disconnectedSinceLastOpen`` (set by onerror,
-    // cleared by onopen below) as the authoritative "was-gap" flag.
-    // Falls back to the legacy semantic for the genuinely manual
-    // case (scheduleReconnect-driven reconnect after CLOSED state).
-    const wasReconnecting = disconnectedSinceLastOpen || reconnectAttempts > 0;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (degradedTimer) {
+      clearTimeout(degradedTimer);
+      degradedTimer = null;
+    }
+  }
+
+  function connectSSE() {
+    closeStreamTransport();
+    // Snapshot whether this connect attempt follows a prior disconnect
+    // BEFORE onopen resets the flags — onopen's post-gap sidebar recovery
+    // keys off it.  Native EventSource auto-reconnect no longer routes
+    // through scheduleReconnect on the transient-error path, so the legacy
+    // ``reconnectAttempts > 0`` check is always false after PR-D — use
+    // ``disconnectedAt`` (stamped by markStreamGap from onerror and from every
+    // deliberate suspend, cleared by onopen below) as the authoritative
+    // "was-gap" flag.  Falls back to the legacy semantic for the genuinely
+    // manual case (scheduleReconnect-driven reconnect after CLOSED state).
+    const wasReconnecting = disconnectedAt !== 0 || reconnectAttempts > 0;
     let url = "/v1/api/workstreams/" + encodeURIComponent(wsId) + "/events";
     // ``!= null`` (not truthiness): a resume cursor of 0 is valid (the
     // ring buffer's first emitted event is id 1), and a brand-new ws's
@@ -2218,12 +2291,47 @@ function createCoordinatorPane(root, wsId, opts) {
     if (lastEventId != null) {
       url += "?last_event_id=" + encodeURIComponent(lastEventId);
     }
+    // Close-on-hide / replay-on-show: install once per pane, removed by
+    // destroy().  A hidden tab's throttled drain is the likeliest slow consumer
+    // behind a server-side queue overflow, and an idle hidden tab holds a node
+    // connection for nothing — closing on hide removes both, and the saved
+    // lastEventId makes the show-edge reconnect lossless (replay_ok).
+    if (!visHandler) {
+      // onVisibilityChange is a plain closure function (no `this` to bind), so
+      // it serves directly as the once-install sentinel AND the
+      // add/removeEventListener handle — no wrapper needed.
+      visHandler = onVisibilityChange;
+      document.addEventListener("visibilitychange", visHandler);
+    }
+    // Never open an EventSource into a hidden (throttled) tab — including a
+    // FIRST connect in a background tab, where the close-on-hide handler never
+    // fires because there was no open stream to close.  This single connect
+    // chokepoint backstops every caller (init, scheduleReconnect, degraded
+    // retry, show edge); the saved lastEventId + the handler installed just
+    // above make the show-edge reconnect replay the gap.  The deferral IS a
+    // gap — everything until the show edge is missed exactly as if the
+    // transport had dropped — so mark it like one: without the mark, a pane
+    // first opened in a background tab skipped onopen's post-gap recovery and
+    // the sidebar silently missed every child/task the backend created while
+    // hidden.  And say so honestly — "connecting…" (set below, only when an
+    // attempt really starts) used to pin here forever with nothing in flight.
+    if (document.hidden) {
+      markStreamGap();
+      hiddenDisconnect = true;
+      setSseStatus("paused — tab hidden", "");
+      return;
+    }
+    setSseStatus("connecting…", "");
     evtSource = new EventSource(url, { withCredentials: true });
     evtSource.onopen = function () {
       reconnectAttempts = 0;
-      // Clear the "was disconnected" flag now that the gap is
-      // closed.  Future onerror fires will set it again.
-      disconnectedSinceLastOpen = false;
+      // Measure the gap this open just closed, then clear it (disconnectedAt is
+      // the was-gap flag).  A gap with no start stamp (legacy scheduleReconnect
+      // path) reads as Infinity — unknown length means we can't argue the
+      // replay covered it, so refresh below.
+      const gapMs = disconnectedAt ? Date.now() - disconnectedAt : Infinity;
+      disconnectedAt = 0;
+      gapRefreshedAtOpen = false;
       setSseStatus("live", "ok");
       // Lift the disconnected dim treatment + restore the last known
       // counters; the replay phase will overwrite with authoritative
@@ -2236,26 +2344,22 @@ function createCoordinatorPane(root, wsId, opts) {
       statusBarEl.classList.remove("ws-sb-disconnected");
       if (lastStatusEvt) updateStatusBar(lastStatusEvt);
       else StatusBar.resetTokensPlaceholder(sbTokensEl);
-      if (wasReconnecting) {
-        // Replace-mode refresh: the server is authoritative after a
-        // gap; any SSE-only rows the client accumulated before
-        // disconnect are stale.
-        loadChildren({ replace: true });
-        loadTasks();
-        // Drop the live-badge cache too — entries within the 5s TTL
-        // can carry stale pending_approval_details (the child may
-        // have resolved its approval during the SSE gap).  Without
-        // this clear, inline approve/deny buttons could render on
-        // a row whose approval was resolved elsewhere; the next
-        // scheduleLiveFetch from loadChildren's finally branch
-        // (which fires for every visible row) repopulates with
-        // authoritative state. Preserve `permanent: true` entries
-        // (set on 403/404 — denied by permission/identity, not by
-        // state) so a user lacking admin.cluster.inspect doesn't
-        // pay one 403 per denied id on every reconnect.
-        for (const [id, c] of liveBadgeCache) {
-          if (!c || !c.permanent) _liveBadgeCacheDelete(id);
-        }
+      // Post-gap sidebar recovery.  child_ws_* / task-mutating events are
+      // ordinary ring-buffer entries, so a cursor reconnect (replay_ok)
+      // redelivers them and the normal handlers heal the sidebar — no REST
+      // refetch, no replace-mode rebuild flicker on a momentary blur/focus.
+      // Refresh eagerly only when the replay CANNOT vouch for the gap: no
+      // cursor to resume from (the fresh path's synthetic replay carries no
+      // child events), or a gap long enough that a stale cursor could be
+      // lying (see GAP_REFRESH_THRESHOLD_MS).  The ring-evicted case
+      // announces itself — the replay_truncated handler runs the same
+      // refresh on arrival (gapRefreshedAtOpen keeps the two from stacking).
+      if (
+        wasReconnecting &&
+        (lastEventId == null || gapMs > GAP_REFRESH_THRESHOLD_MS)
+      ) {
+        refreshSidebarAfterGap();
+        gapRefreshedAtOpen = true;
       }
     };
     evtSource.onerror = function () {
@@ -2267,7 +2371,7 @@ function createCoordinatorPane(root, wsId, opts) {
       // reconnect, which is exactly the reconnect-with-replay defect
       // PR-D ships to fix.  See
       // tests/test_app_js.py::test_coord_connectsse_onerror_preserves_native_reconnect.
-      disconnectedSinceLastOpen = true;
+      markStreamGap();
       setSseStatus("disconnected", "err");
       // Dim the status bar so a stale reading doesn't read as live.
       statusBarEl.classList.add("ws-sb-disconnected");
@@ -2362,18 +2466,59 @@ function createCoordinatorPane(root, wsId, opts) {
       // doesn't desync the manual-reconnect fallback from native
       // auto-reconnect.
       if (evtSource && evtSource.lastEventId) {
+        // A live event id BELOW our saved cursor means the server's per-ws
+        // event counter reset — a coordinator process restart with a fresh,
+        // empty ring.  The replay path can't flag that (a cursor at/above the
+        // ring's earliest id reports replay_ok even when it's past the new
+        // max), so the gap is silent and the sidebar's pre-restart rows go
+        // stale with nothing to replay them.  Catch it here and pull
+        // authoritative state — deduped per open against onopen's /
+        // replay_truncated's own refresh.  (Gaps that DON'T reset the counter
+        // are handled at onopen by the cursor-trust window.)
+        if (
+          lastEventId != null &&
+          !gapRefreshedAtOpen &&
+          Number(evtSource.lastEventId) < Number(lastEventId)
+        ) {
+          refreshSidebarAfterGap();
+          gapRefreshedAtOpen = true;
+        }
         lastEventId = evtSource.lastEventId;
       }
       let data = null;
       try {
         data = JSON.parse(event.data);
-      } catch (_) {
+      } catch (err) {
+        streamHealth.malformedFrames += 1;
+        console.warn(
+          "coordinator: dropping malformed SSE frame (total " +
+            streamHealth.malformedFrames +
+            ")",
+          err,
+        );
         return;
       }
       // Tag the event with its own SSE id so the system_turn handler can dedup
       // a turn already painted from /history (mirrors ui/static/app.js).
       if (event.lastEventId) data._event_id = event.lastEventId;
-      handleEvent(data);
+      // Guard the dispatch: an exception escaping onmessage does NOT close the
+      // EventSource, so an unhandled throw here leaves the streaming refs stale
+      // and every later turn paints into the poisoned segment — the "output
+      // stops while the backend is healthy" wedge.  Count it (render-throw
+      // class) so a field report tells it apart from a dropped-events gap.
+      try {
+        handleEvent(data);
+      } catch (err) {
+        streamHealth.renderThrows += 1;
+        console.error(
+          "coordinator: handleEvent failed for " +
+            (data && data.type) +
+            " (render-throw total " +
+            streamHealth.renderThrows +
+            ")",
+          err,
+        );
+      }
     };
   }
 
@@ -2384,6 +2529,168 @@ function createCoordinatorPane(root, wsId, opts) {
     reconnectTimer = setTimeout(connectSSE, base + jitter);
   }
 
+  // ------------------------------------------------------------------
+  // SSE overflow recovery (client half) — mirrors interactive.js.  The
+  // trip threshold + cooldown-ladder math is shared via sse_overflow.js;
+  // the stateful glue below is coupled to this closure's evtSource seam.
+  // ------------------------------------------------------------------
+
+  // Transport-only stream suspension for the overflow / visibility /
+  // close-session paths: the closeStreamTransport teardown WITHOUT the full
+  // destroy() cleanup (observers, task timers), plus gap accounting.
+  // connectSSE re-opens from the saved lastEventId, so this is lossless for
+  // committed turns.
+  function suspendStream() {
+    closeStreamTransport();
+    // A deliberate suspend is still a gap.  The transient-error path marks
+    // it via onerror; the overflow/hide/close-session paths self-close (no
+    // onerror fires after .close()), so mark it here instead.
+    markStreamGap();
+  }
+
+  // Open a gap in the stream's coverage: stamp its wall-clock start, which
+  // doubles as the was-reconnecting flag the next onopen snapshots (see
+  // connectSSE).  Keep the EARLIEST stamp when marks pile up (repeated onerror
+  // fires, hide followed by a deferred connect) so onopen measures the whole
+  // outage, not just its last slice.  onopen clears it.
+  function markStreamGap() {
+    if (!disconnectedAt) disconnectedAt = Date.now();
+  }
+
+  // Replace-mode sidebar re-sync after a gap the reconnect replay could not
+  // (or might not) have covered — the server is authoritative; any SSE-only
+  // child/task rows accumulated before the disconnect are stale.  Two
+  // callers: onopen (no-cursor / over-threshold gaps) and the
+  // replay_truncated handler (ring-evicted gaps).  Ordinary short gaps need
+  // neither — the ring replay redelivers child_ws_* / task events itself.
+  function refreshSidebarAfterGap() {
+    loadChildren({ replace: true });
+    loadTasks();
+    // Drop the live-badge cache too — entries within the 5s TTL can carry
+    // stale pending_approval_details (the child may have resolved its
+    // approval during the SSE gap).  Without this clear, inline approve/deny
+    // buttons could render on a row whose approval was resolved elsewhere;
+    // the next scheduleLiveFetch from loadChildren's finally branch (which
+    // fires for every visible row) repopulates with authoritative state.
+    // Preserve `permanent: true` entries (set on 403/404 — denied by
+    // permission/identity, not by state) so a user lacking
+    // admin.cluster.inspect doesn't pay one 403 per denied id on every
+    // refresh.
+    for (const [id, c] of liveBadgeCache) {
+      if (!c || !c.permanent) _liveBadgeCacheDelete(id);
+    }
+  }
+
+  // Count + log a caught render throw (wedge-class instrumentation).  The
+  // running total rides in the log line so a field report shows which class
+  // fired — dropped events vs render wedge — without a debugger attached.
+  // console.warn, not error: every caller recovers (plain-text fallback or
+  // keeping the already-streamed text).  The onmessage dispatch catch keeps
+  // its own inline increment — that one is console.error (the whole event is
+  // dropped, nothing recovers it) and names the event type.
+  function noteRenderThrow(where, err) {
+    streamHealth.renderThrows += 1;
+    console.warn(
+      "coordinator " +
+        where +
+        " failed (render-throw total " +
+        streamHealth.renderThrows +
+        ")",
+      err,
+    );
+  }
+
+  function noteStreamOverflow() {
+    streamHealth.overflows += 1;
+    const now = Date.now();
+    overflowTimes.push(now);
+    console.warn(
+      "coordinator: server closed the stream after a send-queue overflow " +
+        "(total " +
+        streamHealth.overflows +
+        "); reconnect will replay the gap",
+    );
+    // Trip when OVERFLOW_TRIP_COUNT closes land inside the rolling window.  The
+    // cooldown-ladder reset lives in enterDegradedCatchup (keyed off
+    // lastDegradedAt), NOT here — this only counts and trips.
+    if (
+      overflowWindowTripped(
+        overflowTimes,
+        now,
+        OVERFLOW_TRIP_COUNT,
+        OVERFLOW_TRIP_WINDOW_MS,
+      )
+    ) {
+      enterDegradedCatchup();
+    }
+  }
+
+  function enterDegradedCatchup() {
+    // Repeated overflow closes inside one window: this consumer cannot keep up
+    // with live streaming right now, and each reconnect round just stalls
+    // rendering behind the retry before re-saturating.  Stop the churn: close
+    // the stream, say so in plain language, and come back after a (doubling)
+    // cooldown — that reconnect replays the gap from the server's ring buffer,
+    // or falls to the replay_truncated → /history resync floor once the gap
+    // has outgrown it.  Either path is lossless for committed turns.
+    const now = Date.now();
+    // Escalate the cooldown when trips recur; reset to base only after a
+    // genuine quiet gap.  Keyed off lastDegradedAt (a timestamp), NOT
+    // overflowTimes — this clears that array below, so keying the reset off it
+    // would restart the ladder on the next storm's first overflow and the
+    // doubling (15→30→60→120s) would never take effect.
+    const step = degradedCooldownStep(
+      degradedCooldownMs,
+      lastDegradedAt,
+      now,
+      DEGRADED_COOLDOWN_BASE_MS,
+      DEGRADED_COOLDOWN_MAX_MS,
+      DEGRADED_COOLDOWN_RESET_MS,
+    );
+    lastDegradedAt = now;
+    degradedCooldownMs = step.nextCooldownMs;
+    overflowTimes.length = 0;
+    suspendStream(); // also cancels any earlier degraded timer
+    setSseStatus("catching up…", "err");
+    statusBarEl.classList.add("ws-sb-disconnected");
+    sbTokensEl.textContent = "Connection is slow — catching up…";
+    const cooldown = step.cooldown;
+    degradedTimer = setTimeout(function () {
+      degradedTimer = null;
+      if (document.hidden) {
+        // Reopening into a throttled hidden tab would overflow again — defer to
+        // the visibilitychange show edge instead.
+        hiddenDisconnect = true;
+        return;
+      }
+      connectSSE();
+    }, cooldown);
+  }
+
+  function onVisibilityChange() {
+    if (document.hidden) {
+      // Closing beats letting the hidden tab's throttled event loop starve the
+      // drain until the server-side queue overflows.  The streaming buffers
+      // (currentAssistantBuf / currentAssistantEl) survive — suspendStream is
+      // transport-only — so the visible tail is intact when the tab returns.
+      if (evtSource) {
+        suspendStream();
+        hiddenDisconnect = true;
+      }
+    } else if (hiddenDisconnect) {
+      hiddenDisconnect = false;
+      connectSSE();
+    }
+  }
+
+  function removeVisibilityHandler() {
+    if (visHandler) {
+      document.removeEventListener("visibilitychange", visHandler);
+      visHandler = null;
+    }
+    hiddenDisconnect = false;
+  }
+
   // ------------------------------------------------------------------
   // SSE event router
   // ------------------------------------------------------------------
@@ -2428,7 +2735,7 @@ function createCoordinatorPane(root, wsId, opts) {
             try {
               streamingRender(abody, currentAssistantBuf);
             } catch (e) {
-              console.warn("coordinator streamingRender failed", e);
+              noteRenderThrow("in_progress_snapshot render", e);
               abody.textContent = currentAssistantBuf;
             }
           } else if (abody) {
@@ -2440,6 +2747,15 @@ function createCoordinatorPane(root, wsId, opts) {
       case "stream_end":
         finishAssistantStream();
         break;
+      case "stream_overflow":
+        // The server poisoned this listener at its first queue overflow and
+        // closes the stream right after this id-less frame.  lastEventId still
+        // points below the gap, so native EventSource reconnect replays it
+        // losslessly from the ring buffer.  Count the close: a persistently
+        // slow consumer trips the degraded catch-up instead of churning
+        // reconnects.
+        noteStreamOverflow();
+        break;
       case "tool_result":
         appendToolResult(
           ev.name || "tool",
@@ -2641,6 +2957,24 @@ function createCoordinatorPane(root, wsId, opts) {
         // reset, idle-after-error). Mirrors the interactive pane.
         if (ev.state === "idle" || ev.state === "error") {
           setBusy(false);
+          // Deferred replay_truncated re-sync: the truncation arrived while a
+          // turn was mid-stream (refetching then would have detached the live
+          // bubble), so repair the ring-evicted gap now that the turn is
+          // settled and /history is complete.  Also repairs a turn stranded by
+          // close-on-hide — hidden mid-turn, its stream_end evicted, so the
+          // show-edge replay_truncated latched the flag and the live bubble
+          // never finalized.  Reset the streaming refs first: refetchHistory
+          // replaceChildren()s the DOM but does NOT null them, and a dangling
+          // ref would strand the NEXT turn's tokens into a detached node.
+          // Mirrors interactive.js.
+          if (pendingTruncatedResync) {
+            pendingTruncatedResync = false;
+            currentAssistantEl = null;
+            currentAssistantBuf = "";
+            currentReasoningEl = null;
+            currentReasoningBuf = "";
+            refetchHistory();
+          }
         } else if (
           ev.state === "running" ||
           ev.state === "thinking" ||
@@ -2739,9 +3073,24 @@ function createCoordinatorPane(root, wsId, opts) {
       }
       case "replay_truncated":
         // Reconnect buffer evicted past our last-seen id — re-sync from REST.
-        // Skip mid-stream: in_progress_snapshot already paints the live turn
-        // and a replaceChildren() would detach the streaming bubble.
-        if (!currentAssistantEl) refetchHistory();
+        // Skip while a turn is mid-stream (BOTH a content bubble and a
+        // reasoning-only one are detachable): the recovery floor's
+        // in_progress_snapshot repaints it, and an async refetch's
+        // replaceChildren() would detach the live bubble so deltas render
+        // nowhere.  Mid-stream the resync is DEFERRED, not dropped — skipping
+        // outright left the ring-evicted gap unrepaired for the rest of the
+        // session (no clean reconnect may come for hours); the idle edge
+        // consumes the flag.  Mirrors interactive.js's _pendingTruncatedResync.
+        if (!currentAssistantEl && !currentReasoningEl) {
+          refetchHistory();
+        } else {
+          pendingTruncatedResync = true;
+        }
+        // The evicted slice may have carried child_ws_* / task events the
+        // sidebar will never see replayed — this is the server saying the
+        // gap was NOT covered, so pull authoritative state (unless onopen
+        // already did, milliseconds ago, for this same reconnect).
+        if (!gapRefreshedAtOpen) refreshSidebarAfterGap();
         break;
       case "tool_pending":
         // Early paint — render the batch the instant the model commits to
@@ -4959,10 +5308,8 @@ function createCoordinatorPane(root, wsId, opts) {
   //  login out to every open pane.)
   function onLogin() {
     reconnectAttempts = 0;
-    if (reconnectTimer) {
-      clearTimeout(reconnectTimer);
-      reconnectTimer = null;
-    }
+    // connectSSE's closeStreamTransport prologue cancels any pending
+    // reconnect / degraded timers before dialling.
     connectSSE();
   }
 
@@ -4970,20 +5317,21 @@ function createCoordinatorPane(root, wsId, opts) {
   // per-instance pane must release the stream + every timer/observer or a
   // backgrounded pane keeps an SSE open and fires renders into detached DOM.
   function destroy() {
-    if (evtSource) {
-      evtSource.close();
-      evtSource = null;
-    }
+    // Stream + both retry timers (reconnect backoff, degraded catch-up).
+    closeStreamTransport();
     [
-      reconnectTimer,
       cancelTimeoutId,
       forceTimeoutId,
       tasksRefreshTimer,
       liveBadgeFlushTimer,
     ].forEach((t) => t && clearTimeout(t));
-    reconnectTimer = cancelTimeoutId = forceTimeoutId = null;
+    cancelTimeoutId = forceTimeoutId = null;
     tasksRefreshTimer = liveBadgeFlushTimer = null;
     if (pruneTimer) clearInterval(pruneTimer);
+    // The document-level visibilitychange listener holds a strong ref to this
+    // closure — leaving it registered would both leak the pane and let a show
+    // edge reopen a stream for a destroyed pane.
+    removeVisibilityHandler();
     if (_childObserver && _childObserver.disconnect)
       _childObserver.disconnect();
   }

turnstone/console/static/index.html

@@ -25,6 +25,7 @@
     <link rel="stylesheet" href="/static/coordinator/coordinator.css" />
     <link rel="stylesheet" href="/static/coordinator/coord-chrome.css" />
     <link rel="stylesheet" href="/shared/interactive.css" />
+    <link rel="stylesheet" href="/shared/preview.css" />
     <link rel="stylesheet" href="/shared/hatch.css" />
   </head>
   <body>
@@ -1532,6 +1533,18 @@
               <select id="sch-template">
                 <option value="">None</option>
               </select>
+              <label for="sch-persona"
+                >Persona <span class="label-hint">optional</span></label
+              >
+              <select id="sch-persona">
+                <option value="">Default persona</option>
+              </select>
+              <label for="sch-project"
+                >Project <span class="label-hint">optional</span></label
+              >
+              <select id="sch-project">
+                <option value="">No project</option>
+              </select>
               <label for="sch-message">Initial message</label>
               <textarea
                 id="sch-message"

turnstone/core/adapters/_ui_cleanup.py

@@ -23,12 +23,28 @@ if TYPE_CHECKING:
 def cleanup_session_ui(ws: Workstream) -> None:
     """Shared SessionKindAdapter cleanup_ui implementation.
 
-    Unblocks pending approval / plan / foreground events on the
-    workstream's UI, broadcasts ``ws_closed`` to per-UI listener
-    queues, then cancels + closes the session. The ``hasattr`` checks
-    guard stub UIs used in tests — the real ``WebUI`` /
+    Marks the workstream object dead (``ws._closed``) FIRST, under
+    ``ws._lock``, then unblocks pending approval / plan / foreground
+    events on the workstream's UI, broadcasts ``ws_closed`` to per-UI
+    listener queues, and cancels + closes the session. The ``hasattr``
+    checks guard stub UIs used in tests — the real ``WebUI`` /
     ``ConsoleCoordinatorUI`` always have these attributes.
+
+    The flag write lives HERE because every teardown path funnels
+    through this function — ``close``, ``close_idle``, EVICTION,
+    ``delete``, ``discard`` — and per-path writes are not enough: a
+    flag set by only some paths, or set after this teardown body,
+    leaves windows where the workstream is being torn down while
+    still reading as live.  The wake paths that hold OBJECT
+    references (the watch ``wake_fn``, ``session_worker``'s exit
+    backstop) gate on this flag, and ``session_worker.send``
+    re-checks it under the same lock: once this write lands, no wake
+    can spawn a worker on the torn-down session — including on
+    evicted or deleted workstreams, and including during the
+    remainder of this teardown.
     """
+    with ws._lock:
+        ws._closed = True
     if ws.session is not None and hasattr(ws.session, "cancel"):
         ws.session.cancel()
     ui = ws.ui
@@ -68,6 +84,15 @@ def _broadcast_ws_closed_to_listeners(ui: SessionUI) -> None:
         return
     with listeners_lock:
         for lq in listeners:
+            # Mark the stream closing BEFORE attempting the sentinel: a
+            # poisoned/full ``_ListenerQueue`` rejects every put (the
+            # eviction-safe retry below can't beat the poison latch), so
+            # the drain loop needs this out-of-band flag to unwind as a
+            # clean close instead of emitting a spurious ``stream_overflow``
+            # frame.  Best-effort on plain ``queue.Queue`` (no such method).
+            mark_closing = getattr(lq, "mark_closing", None)
+            if mark_closing is not None:
+                mark_closing()
             try:
                 lq.put_nowait({"type": "ws_closed"})
             except queue.Full:

turnstone/core/history_decoration.py

@@ -630,6 +630,12 @@ def project_history_messages(
             result_call_id = msg.get("tool_call_id")
             if result_call_id:
                 entry["tool_call_id"] = str(result_call_id)
+            # Preview-pane descriptor → top-level ``preview``, mirroring the
+            # live ``tool_result`` SSE event's field so replay renders the
+            # same reopen chip the live path did.
+            preview = msg.get("_preview")
+            if isinstance(preview, dict) and preview:
+                entry["preview"] = preview
             if isinstance(content, list):
                 # Renderers require a string (``replayHistory`` calls
                 # ``stripAnsi(content).trim()``; coord joins text parts), so

turnstone/core/idle_nudge_watcher.py

@@ -1,8 +1,18 @@
-"""Idle wake-trigger for the metacog NudgeQueue pipeline.
+"""Idle wake-triggers for the metacog NudgeQueue pipeline.
 
-Hosts :class:`IdleNudgeWatcher` plus the
-:func:`install_idle_nudge_watcher` / :func:`shutdown_idle_nudge_watchers`
-lifespan helpers.  Pulled out of :mod:`turnstone.core.metacognition`
+Hosts the two wake entry points plus their lifespan helpers:
+
+* :class:`IdleNudgeWatcher` — event-driven: a workstream transitions
+  to IDLE while nudges are ALREADY queued.
+* :func:`wake_workstream_if_pending` — the shared wake gate, also
+  called directly by asynchronous producers that enqueue onto an
+  ALREADY-idle workstream (the watch dispatch closure, via
+  ``ChatSession.set_watch_runner``'s ``wake_fn``).  Such producers see
+  no IDLE transition — the workstream has been idle all along — so
+  the watcher alone would leave their entries queued until the next
+  user message.
+
+Pulled out of :mod:`turnstone.core.metacognition`
 because the watcher is subscriber-lifecycle / runtime-orchestration
 code with different concerns from the static nudge-text templates and
 detection heuristics that live in metacognition; mixing them grew the
@@ -16,32 +26,129 @@ from typing import TYPE_CHECKING, Any
 
 from turnstone.core import session_worker
 from turnstone.core.log import get_logger
-from turnstone.core.nudge_queue import USER_DRAIN
+from turnstone.core.nudge_queue import USER_DRAIN, NudgeQueue
 from turnstone.core.workstream import WorkstreamState
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
     from turnstone.core.session_manager import SessionManager
+    from turnstone.core.workstream import Workstream
 
 log = get_logger(__name__)
 
 
+def wake_workstream_if_pending(ws: Workstream, *, trigger: str = "unspecified") -> bool:
+    """Spawn a wake send for *ws* when it is idle with drainable nudges.
+
+    The shared gate behind both wake triggers:
+
+    * :class:`IdleNudgeWatcher` — the workstream just transitioned to
+      IDLE with nudges already queued.
+    * the watch dispatch closure (``ChatSession.set_watch_runner``'s
+      ``wake_fn``) — a watch fired on a workstream that is ALREADY
+      idle, so no IDLE transition will ever re-check the queue.
+
+    *trigger* is a short label naming which path requested the wake
+    (``"idle-transition"``, ``"watch-fire"``, ``"worker-exit"``); it is
+    used only to tag the log lines below and never affects control flow.
+
+    Gates, in order:
+
+    * ``ws.session is None`` — workstream tracked but session not
+      built — or a session whose ``_nudge_queue`` is not a real
+      :class:`NudgeQueue` (bare stubs; mock sessions).  The wake
+      contract REQUIRES real drain semantics: the spawned worker's
+      ``deliver_wake_nudge_from_queue`` must actually CONSUME what
+      ``has_pending`` saw, or the worker-exit backstop respawns wake
+      workers forever — a mock queue's truthy ``has_pending`` plus a
+      no-op deliver is exactly that storm, so the gate refuses on
+      TYPE, not just presence.
+    * ``ws._closed`` — ``close()`` already ran (or is racing us); its
+      storage row says ``closed`` and a wake send would drive a
+      torn-down session.  Lockless FAST-PATH only: a stale ``False``
+      falls through to ``session_worker.send``, which re-checks
+      ``_closed`` under ``ws._lock`` — the same lock ``close()`` sets
+      it under — and refuses, so a wake racing a close can never spawn
+      a worker on the torn-down session.
+    * ``ws.state is not IDLE`` — a busy workstream's worker drains the
+      queue at its own seams (``ATTENTION``/``THINKING``/``RUNNING``
+      all imply a live worker), and ``ERROR`` stays parked for the
+      operator rather than burning inference unattended.
+    * nothing drainable under ``USER_DRAIN`` — tool-only entries
+      belong to the next tool-result seam, not a synthetic empty user
+      turn (``deliver_wake_nudge_from_queue`` would no-op on them).
+
+    Past the gates, exactly one info line is emitted per call:
+
+    * ``nudge_wake.deferred_worker_busy`` — the reuse-path drop: a
+      worker owned the workstream, so ``session_worker.send`` called
+      the no-op ``enqueue`` instead of spawning.  The entry stays
+      queued; the owning worker's exit backstop (or its next drain
+      seam) delivers it.
+    * ``nudge_wake.dispatched`` — a fresh wake daemon was spawned.
+    * ``nudge_wake.refused`` — ``session_worker.send`` declined the
+      spawn: its authoritative under-lock ``_closed`` re-check caught a
+      teardown this gate's lockless peek missed.  The entry dies with
+      the workstream; logged here so a dropped wake is traceable to its
+      trigger during production troubleshooting.
+
+    Returns ``True`` iff the wake was handed to
+    ``session_worker.send`` — which may still downgrade it to a no-op
+    enqueue when a worker owns the workstream (see the race-semantics
+    section on :class:`IdleNudgeWatcher`).
+    """
+    session = ws.session
+    if session is None or ws._closed or ws.state is not WorkstreamState.IDLE:
+        return False
+    nudge_queue = getattr(session, "_nudge_queue", None)
+    if not isinstance(nudge_queue, NudgeQueue) or not nudge_queue.has_pending(USER_DRAIN):
+        return False
+
+    deferred = False
+
+    def _noop_enqueue() -> None:
+        nonlocal deferred
+        deferred = True
+
+    ok = session_worker.send(
+        ws,
+        enqueue=_noop_enqueue,
+        run=session.deliver_wake_nudge_from_queue,
+        thread_name=f"wake-nudge-{ws.id[:8]}",
+    )
+    if deferred:
+        log.info("nudge_wake.deferred_worker_busy ws=%s trigger=%s", ws.id[:8], trigger)
+    elif ok:
+        log.info("nudge_wake.dispatched ws=%s trigger=%s", ws.id[:8], trigger)
+    else:
+        log.info("nudge_wake.refused ws=%s trigger=%s", ws.id[:8], trigger)
+    return ok
+
+
 class IdleNudgeWatcher:
     """Convert a workstream IDLE transition into a wake send when the
     session has queued nudges.
 
     Subscribes to :meth:`SessionManager.subscribe_to_state` and listens
-    for ``WorkstreamState.IDLE``.  If the workstream's
+    for ``WorkstreamState.IDLE``, then defers to
+    :func:`wake_workstream_if_pending` (the shared gate — see its
+    docstring for the full gate order).  If the workstream's
     :class:`NudgeQueue` has any drainable entry for the wake's drain
-    filter (``USER_DRAIN`` — channels ``"user"`` or ``"any"``),
-    dispatches via ``session_worker.send`` with a no-op ``enqueue``
-    callback.  Tool-only entries don't fire the wake — they belong to
-    the next tool-result seam, not a synthetic empty user turn —
-    otherwise every IDLE event with a queued tool advisory would spawn
-    a wake daemon that immediately no-ops at
+    filter (``USER_DRAIN`` — channels ``"user"`` or ``"any"``), the
+    gate dispatches via ``session_worker.send`` with a no-op
+    ``enqueue`` callback.  Tool-only entries don't fire the wake —
+    they belong to the next tool-result seam, not a synthetic empty
+    user turn — otherwise every IDLE event with a queued tool advisory
+    would spawn a wake daemon that immediately no-ops at
     ``deliver_wake_nudge_from_queue``'s drain guard.
 
+    This watcher only covers nudges that are already queued when the
+    IDLE transition fires.  Producers that enqueue asynchronously onto
+    an already-idle workstream (watch fires) call
+    :func:`wake_workstream_if_pending` themselves — there is no state
+    transition for this watcher to observe in that case.
+
     **Race semantics.**  ``session_worker.send`` decides atomically
     under ``ws._lock`` whether a worker thread already owns the
     workstream.  Three outcomes:
@@ -51,10 +158,17 @@ class IdleNudgeWatcher:
       drains its own queue and runs the synthetic empty-user turn).
     * Worker running → call our ``enqueue`` lambda, which is a no-op.
       The wake is silently dropped; the queued nudge stays in
-      ``NudgeQueue`` and the in-flight worker picks it up at its next
-      user-message-attach or tool-result seam (whichever fires first
-      for the entry's channel).  This is the load-bearing fallback —
-      we never spawn a competing worker.
+      ``NudgeQueue``.  We never spawn a competing worker.  This branch
+      is the COMMON case for IDLE-transition wakes, not the exception:
+      ``set_state`` subscribers fire on the calling thread, and IDLE
+      is emitted from inside ``run()`` at the end of a send — so the
+      transitioning worker still owns the flag while this watcher
+      dispatches.  Delivery is then owed to one of two follow-ups:
+      the in-flight worker's next drain seam (when IDLE fired
+      mid-turn), or — for the end-of-send case, where no later seam
+      exists — ``session_worker``'s ownership-clear backstop
+      (``_retry_pending_wake``), which re-runs
+      :func:`wake_workstream_if_pending` the moment the worker exits.
     * Workstream gone (``ws is None``) or session not built
       (``ws.session is None``) → bail.
 
@@ -82,17 +196,9 @@ class IdleNudgeWatcher:
             if state is not WorkstreamState.IDLE:
                 return
             ws = self._manager.get(ws_id)
-            if ws is None or ws.session is None:
+            if ws is None:
                 return
-            session = ws.session
-            if not session._nudge_queue.has_pending(USER_DRAIN):
-                return
-            session_worker.send(
-                ws,
-                enqueue=lambda: None,
-                run=session.deliver_wake_nudge_from_queue,
-                thread_name=f"wake-nudge-{ws.id[:8]}",
-            )
+            wake_workstream_if_pending(ws, trigger="idle-transition")
 
         self._callback = _on_state
         self._manager.subscribe_to_state(_on_state)

turnstone/core/preview.py

@@ -0,0 +1,362 @@
+"""Preview-content policy for the ``open_preview`` tool.
+
+The preview pane renders tool-selected content — a fetched web page, a PDF, an
+image, a data table, a text/markdown document — in a dedicated frontend pane
+beside the conversation.  This module owns the pure policy so the session
+executor and the serving route share one definition: the content-kind
+vocabulary, how bytes + hints resolve to a kind, the per-kind size caps, the
+serving MIME allowlist + response headers, and the small HTML mutations
+(base-href injection, title extraction) applied to fetched pages at store
+time.
+
+Preview blobs are persisted content-addressed with attachment kind
+``PREVIEW_BLOB_KIND``.  That kind is deliberately outside the model-visible
+attachment vocabulary (image / text / pdf / audio): trajectory reconstruction
+skips it, so a preview blob can never be lifted into a turn's content and
+materialized onto the wire — the tool turn's ``meta.extra["preview"]``
+descriptor is the only carrier, and it is frontend-facing only.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from typing import Any
+
+from turnstone.core.attachments import (
+    ALLOWED_IMAGE_MIMES,
+    IMAGE_SIZE_CAP,
+    PDF_SIZE_CAP,
+    TEXT_DOC_SIZE_CAP,
+    sniff_image_mime,
+    sniff_pdf_mime,
+)
+from turnstone.core.web_helpers import latin1_safe_filename
+
+# Rendered-content kinds the pane knows how to display.  ``web`` is a fetched
+# HTML document (sandboxed iframe); ``table`` is CSV/TSV/JSON parsed and
+# rendered client-side; the rest map 1:1 onto native browser rendering.
+PREVIEW_KINDS: frozenset[str] = frozenset({"web", "pdf", "image", "table", "text", "markdown"})
+
+# Storage ``kind`` for preview blobs — see the module docstring for why this
+# is not one of the model-visible attachment kinds.
+PREVIEW_BLOB_KIND = "preview"
+
+# Per-kind byte caps on the STORED preview content.  image/pdf/text reuse the
+# attachment-subsystem caps so a previewable file and an uploadable file agree
+# on "too big".  Fetched pages get their own cap (real-world pages fit well
+# under it; over-cap pages error rather than truncate — a mid-tag cut renders
+# garbage).  Tables get headroom over plain text: a few-MB CSV is a normal
+# artifact of "bash produced data", and the client-side renderer row-caps.
+PREVIEW_SIZE_CAPS: dict[str, int] = {
+    "web": 4 * 1024 * 1024,
+    "pdf": PDF_SIZE_CAP,
+    "image": IMAGE_SIZE_CAP,
+    "table": 2 * 1024 * 1024,
+    "text": TEXT_DOC_SIZE_CAP,
+    "markdown": TEXT_DOC_SIZE_CAP,
+}
+
+# MIME types the preview route will serve with a renderable Content-Type.
+# Everything stored by ``open_preview`` lands in this set; the route still
+# allowlists defensively so a non-preview blob addressed by id serves nothing
+# renderable.  Parameterized types (``text/html; charset=utf-8``) match on the
+# bare type.
+PREVIEW_SERVE_MIMES: frozenset[str] = frozenset(
+    {
+        "text/html",
+        "application/pdf",
+        "text/plain",
+        "text/csv",
+        "text/tab-separated-values",
+        "application/json",
+        "text/markdown",
+    }
+    | set(ALLOWED_IMAGE_MIMES)
+)
+
+# Extension → (kind, stored mime).  Consulted after magic bytes and the
+# transport MIME hint; keys are lowercase with the dot.
+_EXT_KINDS: dict[str, tuple[str, str]] = {
+    ".html": ("web", "text/html; charset=utf-8"),
+    ".htm": ("web", "text/html; charset=utf-8"),
+    ".pdf": ("pdf", "application/pdf"),
+    ".csv": ("table", "text/csv; charset=utf-8"),
+    ".tsv": ("table", "text/tab-separated-values; charset=utf-8"),
+    ".json": ("table", "application/json"),
+    ".md": ("markdown", "text/markdown; charset=utf-8"),
+    ".markdown": ("markdown", "text/markdown; charset=utf-8"),
+}
+
+# Stored mime per kind when the kind is chosen first (explicit ``kind`` arg or
+# a MIME-hint match): the inverse of ``_EXT_KINDS`` plus the text fallback.
+_KIND_MIMES: dict[str, str] = {
+    "web": "text/html; charset=utf-8",
+    "pdf": "application/pdf",
+    "table": "text/csv; charset=utf-8",
+    "text": "text/plain; charset=utf-8",
+    "markdown": "text/markdown; charset=utf-8",
+}
+
+
+def _is_utf8_text(data: bytes) -> bool:
+    """True when *data* decodes as UTF-8 and carries no NUL (binary tell)."""
+    if b"\x00" in data:
+        return False
+    try:
+        data.decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    return True
+
+
+def _is_decodable_text(data: bytes) -> bool:
+    """True when *data* carries no NUL byte — the gate for DECLARED text.
+
+    A text-family MIME hint / extension / ``kind`` override says "this is
+    text"; the store-time transcode ladder (:func:`transcode_text`) then
+    decodes it whatever the charset, so the only hard reject left is the NUL
+    byte that marks genuinely-binary content.  The *undeclared* fallback lane
+    keeps the stricter :func:`_is_utf8_text`: cp1252-with-replacement never
+    fails, so unknown bytes must prove UTF-8 rather than be waved through as
+    text.
+    """
+    return b"\x00" not in data
+
+
+def _charset_param(mime: str) -> str | None:
+    """The ``charset=`` value from a MIME string, lowercased, or ``None``."""
+    for part in mime.split(";")[1:]:
+        key, sep, value = part.partition("=")
+        if sep and key.strip().lower() == "charset":
+            return value.strip().strip('"').lower() or None
+    return None
+
+
+def transcode_text(body: bytes, mime_hint: str) -> str:
+    """Decode text-family *body* to ``str`` via a charset ladder.
+
+    Rungs: (a) the ``charset=`` parameter from *mime_hint* when it names a
+    codec Python knows, (b) UTF-8, (c) cp1252 with ``errors="replace"``.  The
+    last rung never fails, so the return is always a usable string — this is
+    the store-time transcode that lets a legacy-charset page / CSV / log render
+    as UTF-8.  Binary rejection stays upstream in :func:`resolve_preview_kind`
+    (the NUL check); by the time bytes reach here they are already classified
+    text.
+    """
+    charset = _charset_param(mime_hint)
+    if charset:
+        try:
+            return body.decode(charset)
+        except (LookupError, UnicodeDecodeError):
+            pass
+    try:
+        return body.decode("utf-8")
+    except UnicodeDecodeError:
+        return body.decode("cp1252", errors="replace")
+
+
+def _kind_from_mime(mime: str) -> tuple[str, str] | None:
+    """Map a transport MIME hint to ``(kind, stored_mime)``, or ``None``."""
+    bare = mime.split(";", 1)[0].strip().lower()
+    if not bare:
+        return None
+    if "html" in bare:
+        return "web", _KIND_MIMES["web"]
+    if bare == "application/pdf":
+        return "pdf", _KIND_MIMES["pdf"]
+    if bare in ALLOWED_IMAGE_MIMES:
+        return "image", bare
+    if bare == "text/csv":
+        return "table", "text/csv; charset=utf-8"
+    if bare == "text/tab-separated-values":
+        return "table", "text/tab-separated-values; charset=utf-8"
+    if bare in ("application/json", "text/json"):
+        return "table", "application/json"
+    if bare == "text/markdown":
+        return "markdown", _KIND_MIMES["markdown"]
+    if bare.startswith("text/"):
+        return "text", _KIND_MIMES["text"]
+    return None
+
+
+def resolve_preview_kind(
+    mime_hint: str,
+    name_hint: str,
+    body: bytes,
+    kind_override: str | None = None,
+) -> tuple[str, str] | None:
+    """Resolve ``(kind, stored_mime)`` for *body*, or ``None`` if unpreviewable.
+
+    Precedence: explicit *kind_override* (the model's ``kind`` argument) →
+    magic bytes (image / pdf — never extension-trusted, mirroring the upload
+    classifier) → transport MIME hint → filename/URL extension → UTF-8 text
+    fallback.  A binary body that matches nothing is not previewable.
+    """
+    if kind_override:
+        if kind_override not in PREVIEW_KINDS:
+            return None
+        if kind_override == "image":
+            sniffed_image = sniff_image_mime(body)
+            return ("image", sniffed_image) if sniffed_image else None
+        if kind_override == "pdf":
+            return ("pdf", "application/pdf") if sniff_pdf_mime(body) else None
+        # Text-family overrides (table / text / markdown) reject only genuine
+        # binary here — the NUL check.  The executor transcodes the bytes to
+        # UTF-8 at store time, so a legacy-charset body forced to a text kind
+        # still renders (web always took this path; the others now join it).
+        if kind_override != "web" and not _is_decodable_text(body):
+            return None
+        if kind_override == "table":
+            # Preserve a JSON payload's real type so the client parser branches.
+            bare = mime_hint.split(";", 1)[0].strip().lower()
+            ext = _name_ext(name_hint)
+            if bare in ("application/json", "text/json") or ext == ".json":
+                return "table", "application/json"
+            if bare == "text/tab-separated-values" or ext == ".tsv":
+                return "table", "text/tab-separated-values; charset=utf-8"
+            return "table", _KIND_MIMES["table"]
+        return kind_override, _KIND_MIMES[kind_override]
+
+    sniffed = sniff_image_mime(body)
+    if sniffed:
+        return "image", sniffed
+    if sniff_pdf_mime(body):
+        return "pdf", "application/pdf"
+    from_mime = _kind_from_mime(mime_hint)
+    if from_mime:
+        # A text-family MIME hint declares text: reject only genuine binary
+        # (the NUL check).  Legacy charsets (windows-1252 / Shift-JIS pages,
+        # iso-8859-1 CSVs / logs) are not UTF-8 on the raw bytes, and the
+        # executor transcodes every text-family kind to UTF-8 at store time
+        # (charset-aware for fetches, ladder-decoded otherwise).
+        if from_mime[0] in ("table", "text", "markdown") and not _is_decodable_text(body):
+            return None
+        return from_mime
+    ext_match = _EXT_KINDS.get(_name_ext(name_hint))
+    if ext_match:
+        # A text-family extension declares text too — same NUL-only gate; the
+        # store-time ladder handles whatever charset the bytes are in.
+        if ext_match[0] != "web" and not _is_decodable_text(body):
+            return None
+        return ext_match
+    if _is_utf8_text(body):
+        return "text", _KIND_MIMES["text"]
+    return None
+
+
+def _name_ext(name: str) -> str:
+    """Lowercase extension of a path / URL tail (query and fragment stripped)."""
+    tail = name.rsplit("/", 1)[-1].split("?", 1)[0].split("#", 1)[0]
+    dot = tail.rfind(".")
+    return tail[dot:].lower() if dot >= 0 else ""
+
+
+# ``<base>`` / ``<head>`` / ``<html>`` / doctype openers in the first slice of
+# the document — enough for any real page; scanning megabytes for a head that
+# must appear early is wasted work.
+_HEAD_SCAN_LIMIT = 65536
+_BASE_TAG_RE = re.compile(r"<base[\s>/]", re.IGNORECASE)
+_HEAD_OPEN_RE = re.compile(r"<head(?:\s[^>]*)?>", re.IGNORECASE)
+_HTML_OPEN_RE = re.compile(r"<html(?:\s[^>]*)?>", re.IGNORECASE)
+_DOCTYPE_RE = re.compile(r"<!doctype[^>]*>", re.IGNORECASE)
+
+
+def inject_base_href(html_text: str, base_url: str) -> str:
+    """Give a fetched page a ``<base href>`` so relative assets resolve.
+
+    The stored bytes are what the fetch saw; without a base, every relative
+    ``src``/``href`` inside the sandboxed iframe would resolve against the
+    turnstone origin and 404.  A page that declares its own ``<base>`` is left
+    alone.  Insertion goes right after the ``<head>`` opener when present,
+    else after ``<html>`` / the doctype — the parser hoists the tag into the
+    implied head from there.  Never ahead of the doctype: markup before
+    ``<!doctype`` voids it and drops the whole preview into quirks mode.
+    """
+    head_slice = html_text[:_HEAD_SCAN_LIMIT]
+    if _BASE_TAG_RE.search(head_slice):
+        return html_text
+    tag = f'<base href="{html.escape(base_url, quote=True)}">'
+    m = _HEAD_OPEN_RE.search(head_slice) or _HTML_OPEN_RE.search(head_slice)
+    if not m:
+        m = _DOCTYPE_RE.search(head_slice)
+    if m:
+        return html_text[: m.end()] + tag + html_text[m.end() :]
+    return tag + html_text
+
+
+_TITLE_RE = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
+
+
+def page_title(html_text: str) -> str | None:
+    """The document's ``<title>`` text (unescaped, whitespace-collapsed), or None."""
+    m = _TITLE_RE.search(html_text[:_HEAD_SCAN_LIMIT])
+    if not m:
+        return None
+    title = " ".join(html.unescape(m.group(1)).split())
+    return title[:200] or None
+
+
+def build_preview_descriptor(
+    *,
+    kind: str,
+    title: str,
+    source: str,
+    attachment_id: str,
+    content_type: str,
+    size: int,
+) -> dict[str, Any]:
+    """The structured descriptor that rides the tool turn's meta to the frontend.
+
+    One shape on every boundary — the live ``tool_result`` SSE event, the
+    persisted ``conversations.meta`` column, and the ``/history`` projection —
+    so the pane renders identically live and on replay.
+    """
+    return {
+        "kind": kind,
+        "title": title,
+        "source": source,
+        "attachment_id": attachment_id,
+        "content_type": content_type,
+        "size": size,
+    }
+
+
+def preview_response_headers(
+    bare_mime: str, filename: str, *, allow_remote_assets: bool = False
+) -> dict[str, str]:
+    """Response headers for the preview serving route, per rendered MIME.
+
+    ``text/html`` is served sandboxed either way — scripts never run and its
+    origin is opaque, so it can't touch the app origin's cookies or DOM, and
+    the embedding iframe carries the ``sandbox`` attribute too.  The default
+    (``allow_remote_assets=False``) additionally locks the document out of the
+    network: it renders with its inline styling and data-URI images but cannot
+    fetch anything, so previewing a page never discloses the viewer's IP or
+    traffic to the origin site.  ``allow_remote_assets=True`` (a per-pane
+    opt-in) drops back to the bare ``sandbox`` so the page's own images / CSS
+    load.  ``application/pdf`` gets no CSP: Chromium's PDF viewer refuses to
+    paint inside a sandboxed context, and the response is inert media rendered
+    by browser chrome, not an active document.  Everything else keeps the
+    attachment endpoints' full ``default-src 'none'; sandbox`` posture.
+    """
+    # Page-title-derived filenames routinely carry em dashes / CJK (non-latin-1)
+    # and can carry control bytes — either would 500 the serving route, so run
+    # the shared header sanitizer rather than emit them verbatim.
+    safe_name = latin1_safe_filename(filename, fallback="preview")
+    headers = {
+        "X-Content-Type-Options": "nosniff",
+        "Content-Disposition": f'inline; filename="{safe_name}"',
+        "Cache-Control": "private, no-store",
+    }
+    if bare_mime == "text/html":
+        if allow_remote_assets:
+            headers["Content-Security-Policy"] = "sandbox"
+        else:
+            headers["Content-Security-Policy"] = (
+                "sandbox; default-src 'none'; style-src 'unsafe-inline'; "
+                "img-src data:; font-src data:"
+            )
+    elif bare_mime != "application/pdf":
+        headers["Content-Security-Policy"] = "default-src 'none'; sandbox"
+    return headers

turnstone/core/providers/_openai_common.py

@@ -172,6 +172,60 @@ OPENAI_CAPABILITIES: dict[str, ModelCapabilities] = {
         supports_pdf=True,
         supports_reasoning_replay=True,
     ),
+    # GPT-5.6 (Sol / Terra / Luna) — released 2026-07-09.  The bare
+    # "gpt-5.6" alias routes to Sol (developers.openai.com/api/docs/guides/
+    # latest-model, 2026-07 check), so this catch-all row carries Sol's
+    # caps and also covers dated Sol snapshots ("gpt-5.6-2026-..") and the
+    # explicit "gpt-5.6-sol" id by longest-prefix match.  Sol is the ONLY
+    # 5.6 tier that unlocks the new "max" reasoning effort — the first
+    # COMMERCIAL OpenAI model to use it (KNOB_EFFORT_ORDER already ranks
+    # "max" for the Anthropic lane, so the ordinal snap and effort ladder
+    # need no change).  Sol also has a Sol-only "ultra" multi-agent mode
+    # that Turnstone does NOT expose (only "pro" is wired — see below).
+    # Default effort is "medium" like gpt-5.5; temperature is accepted only at
+    # reasoning_effort="none" (the "none"-in-values gate).  There is NO
+    # gpt-5.6-pro model: "pro" is now a reasoning.mode="pro" request param,
+    # not a separate model id.  Context window is not yet on the model page
+    # (limited preview); 1.05M mirrors the 5.4/5.5 lineage — override via
+    # the DB model definition if OpenAI publishes a different window (a
+    # smaller Luna window has been reported but is unconfirmed).
+    "gpt-5.6": ModelCapabilities(
+        context_window=1050000,
+        max_output_tokens=128000,
+        reasoning_effort_values=("none", "low", "medium", "high", "xhigh", "max"),
+        default_reasoning_effort="medium",
+        supports_tool_search=True,
+        supports_vision=True,
+        supports_pdf=True,
+        supports_reasoning_replay=True,
+        supports_verbosity=True,
+        supports_pro_mode=True,  # Sol-only reasoning.mode="pro"
+    ),
+    # GPT-5.6 Terra — balanced tier; Sol's ladder minus "max" (Sol-only),
+    # so the knob's "max" snaps to the "xhigh" ceiling.  No pro mode.
+    "gpt-5.6-terra": ModelCapabilities(
+        context_window=1050000,
+        max_output_tokens=128000,
+        reasoning_effort_values=("none", "low", "medium", "high", "xhigh"),
+        default_reasoning_effort="medium",
+        supports_tool_search=True,
+        supports_vision=True,
+        supports_pdf=True,
+        supports_reasoning_replay=True,
+        supports_verbosity=True,
+    ),
+    # GPT-5.6 Luna — fastest/cheapest tier; no "max" effort, no pro mode.
+    "gpt-5.6-luna": ModelCapabilities(
+        context_window=1050000,
+        max_output_tokens=128000,
+        reasoning_effort_values=("none", "low", "medium", "high", "xhigh"),
+        default_reasoning_effort="medium",
+        supports_tool_search=True,
+        supports_vision=True,
+        supports_pdf=True,
+        supports_reasoning_replay=True,
+        supports_verbosity=True,
+    ),
     # O-series reasoning models
     "o1": ModelCapabilities(
         context_window=200000,
@@ -372,6 +426,48 @@ def apply_cache_retention(kwargs: dict[str, Any], model: str) -> None:
         kwargs["prompt_cache_retention"] = "24h"
 
 
+# ---------------------------------------------------------------------------
+# Output verbosity + reasoning mode (Responses API)
+# ---------------------------------------------------------------------------
+
+# Known-good enum values for the operator-declared ``verbosity`` /
+# ``reasoning_mode`` capability fields.  These arrive from the
+# model-definition capabilities JSON via
+# ``ChatSession._resolve_capabilities`` — a field-name-filtered
+# ``dataclasses.replace`` that does NOT validate values — so an operator
+# typo would otherwise ride straight to the wire and 400 every request.
+# The emission sites drop unknown values with a warning instead, mirroring
+# how ``model_registry`` clamps out-of-range temperature / max_tokens.
+VERBOSITY_LEVELS: frozenset[str] = frozenset({"low", "medium", "high"})
+REASONING_MODES: frozenset[str] = frozenset({"pro"})
+
+
+def apply_verbosity(kwargs: dict[str, Any], caps: ModelCapabilities) -> None:
+    """Set Responses-API output verbosity when the operator declared one.
+
+    ``verbosity`` (``"low"``/``"medium"``/``"high"``) is the GPT-5 family's
+    output-length lever, distinct from reasoning effort (you can ask for a
+    terse answer at high reasoning).  It is Responses-API-specific and nests
+    under ``text.verbosity`` — a top-level ``verbosity`` field 400s there —
+    so Turnstone emits it on this lane only.  ``supports_verbosity`` is the
+    static capability; ``caps.verbosity`` is the operator-declared value
+    (model-definition capabilities JSON), ``""`` = omit.  An unset value, or
+    one on a model that doesn't support it, is silently omitted (matching
+    ``apply_temperature``); a value outside ``VERBOSITY_LEVELS`` is dropped
+    with a warning (an operator typo must not 400 every request).
+    """
+    if not (caps.supports_verbosity and caps.verbosity):
+        return
+    if caps.verbosity not in VERBOSITY_LEVELS:
+        log.warning(
+            "openai.responses: ignoring unknown verbosity",
+            value=caps.verbosity,
+            expected=sorted(VERBOSITY_LEVELS),
+        )
+        return
+    kwargs.setdefault("text", {})["verbosity"] = caps.verbosity
+
+
 # ---------------------------------------------------------------------------
 # Tool search (native deferred loading)
 # ---------------------------------------------------------------------------

turnstone/core/providers/_openai_responses.py

@@ -17,10 +17,12 @@ import structlog
 
 from turnstone.core.providers._openai_common import (
     OPENAI_COMPAT_DEFAULT,
+    REASONING_MODES,
     RETRYABLE_ERROR_NAMES,
     apply_cache_retention,
     apply_temperature,
     apply_tool_search,
+    apply_verbosity,
     extract_usage,
     format_citations,
     format_document_wrapper,
@@ -435,11 +437,29 @@ class OpenAIResponsesProvider:
 
         apply_temperature(kwargs, caps, temperature, reasoning_effort)
 
-        # Reasoning effort → {"effort": value} dict (Responses API format)
+        # Reasoning params → {"effort": ..., "mode": ...} (Responses format).
+        # "mode": "pro" (GPT-5.6 Sol) applies more model work before a single
+        # final answer; it rides with or without an effort level (effort
+        # defaults to medium in pro mode), and effort still rides without a
+        # mode.  Both are operator-declared and gated by their static
+        # capability, so a value on a model lacking the feature is dropped.
+        reasoning: dict[str, Any] = {}
         effort = resolve_reasoning_effort(caps, reasoning_effort)
         if effort:
-            kwargs["reasoning"] = {"effort": effort}
+            reasoning["effort"] = effort
+        if caps.supports_pro_mode and caps.reasoning_mode:
+            if caps.reasoning_mode in REASONING_MODES:
+                reasoning["mode"] = caps.reasoning_mode
+            else:
+                log.warning(
+                    "openai.responses: ignoring unknown reasoning mode",
+                    value=caps.reasoning_mode,
+                    expected=sorted(REASONING_MODES),
+                )
+        if reasoning:
+            kwargs["reasoning"] = reasoning
 
+        apply_verbosity(kwargs, caps)
         apply_cache_retention(kwargs, model)
         return kwargs
 

turnstone/core/providers/_protocol.py

@@ -102,6 +102,23 @@ class ModelCapabilities:
     # this False: there, an empty values list means the model has no
     # effort control at all (o1-mini) and the param must be omitted.
     effort_passthrough: bool = False
+    # Responses-API output-length control (GPT-5 family): "low"/"medium"/
+    # "high", separate from reasoning effort.  ``supports_verbosity`` is the
+    # static capability; ``verbosity`` is the operator-declared value
+    # (model-definition capabilities JSON, merged via
+    # ``ChatSession._resolve_capabilities``), "" = omit.  Nests under
+    # ``text.verbosity`` on the Responses wire (a top-level ``verbosity``
+    # 400s there); the Chat/compat lane never emits it.  A value set on a
+    # model whose ``supports_verbosity`` is False is dropped, not sent.
+    supports_verbosity: bool = False
+    verbosity: str = ""
+    # Responses-API ``reasoning.mode`` (GPT-5.6 Sol): "pro" applies more
+    # model work before a single final answer.  ``supports_pro_mode`` is the
+    # static capability (Sol-only); ``reasoning_mode`` is the
+    # operator-declared value, "" = omit (normal reasoning).  There is no
+    # gpt-5.6-pro *model* — "pro" is this request-level mode instead.
+    supports_pro_mode: bool = False
+    reasoning_mode: str = ""
     supports_web_search: bool = False
     supports_tool_search: bool = False
     supports_vision: bool = False

turnstone/core/session.py

@@ -124,6 +124,16 @@ from turnstone.core.personas import (
     snapshot_from_config,
     snapshot_from_persona,
 )
+from turnstone.core.preview import (
+    PREVIEW_BLOB_KIND,
+    PREVIEW_KINDS,
+    PREVIEW_SIZE_CAPS,
+    build_preview_descriptor,
+    inject_base_href,
+    page_title,
+    resolve_preview_kind,
+    transcode_text,
+)
 from turnstone.core.providers import create_provider
 from turnstone.core.ratelimit import TokenBucket
 from turnstone.core.safety import is_command_blocked, sanitize_command
@@ -166,7 +176,7 @@ from turnstone.core.trajectory import (
     turns_from_dicts,
 )
 from turnstone.core.watch import WATCH_REMINDER_OPTIONAL_KEYS
-from turnstone.core.web import check_ssrf, strip_html
+from turnstone.core.web import check_ssrf, fetch_with_ssrf_guard, strip_html
 from turnstone.core.workstream import WorkstreamKind
 from turnstone.prompts import (
     INTERACTIVE_CONSENT_CLIENT_TYPES,
@@ -181,7 +191,7 @@ from turnstone.ui.colors import DIM, GRAY, GREEN, RED, RESET, YELLOW, bold, cyan
 log = get_logger(__name__)
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
 
     from turnstone.core.config_store import ConfigStore
     from turnstone.core.healthcheck import BackendHealthTracker, HealthTrackerRegistry
@@ -1056,6 +1066,7 @@ class SessionUI(Protocol):
         output: str,
         *,
         is_error: bool = False,
+        preview: dict[str, Any] | None = None,
     ) -> None: ...
     def on_tool_output_chunk(self, call_id: str, chunk: str) -> None: ...
     def on_status(self, usage: dict[str, Any], context_window: int, effort: str) -> None: ...
@@ -1164,12 +1175,49 @@ def _notify_auth_headers() -> dict[str, str]:
     return header
 
 
-def _effect_status_meta(status: EffectStatus | None) -> str | None:
-    """Serialize a tool effect status to the ``conversations.meta`` JSON
-    envelope. Role-exclusive with ``source_meta`` (which rides SYSTEM turns),
-    so a tool row's meta column holds only ``{"effect_status": ...}``; the
-    decode + role routing lives in ``reconstruct_turns``. ``None`` → no meta."""
-    return json.dumps({"effect_status": status.value}) if status is not None else None
+def _screen_tool_url(url: str, allow_private_network: bool) -> tuple[str | None, bool]:
+    """SSRF-screen a tool's target URL under the operator's private-network opt-in.
+
+    ``allow_private_network`` is the live ``tools.allow_private_network``
+    setting (admin Settings → Tools; DB-backed, hot-toggleable — the caller
+    reads it per prepare).  Returns ``(error, private_origin)``.  ``error`` is
+    the rejection text (``None`` = proceed); a private-address rejection names
+    the setting so a self-hosted operator learns the knob from the refusal
+    itself.  ``private_origin`` is True when the target NAMES a private
+    address the operator opted into: the approval header tags it, and the
+    guarded fetch skips per-hop screening for that chain — the gate approved a
+    private URL, so its redirects are the operator's own network.  Public
+    origins never set it, keeping the public→private redirect bounce blocked
+    regardless of the opt-in.
+    """
+    ssrf_err = check_ssrf(url)
+    if not ssrf_err:
+        return None, False
+    is_private_block = "private/internal address" in ssrf_err
+    if is_private_block and allow_private_network:
+        return None, True
+    hint = ""
+    if is_private_block:
+        hint = (
+            " Enable 'tools.allow_private_network' in the console"
+            " (Settings → Tools) to allow fetching private-network addresses."
+        )
+    return f"Error: {ssrf_err}.{hint}", False
+
+
+def _tool_turn_meta(
+    status: EffectStatus | None, preview: dict[str, Any] | None = None
+) -> str | None:
+    """Serialize a tool turn's typed side-channels to the ``conversations.meta``
+    JSON envelope: the effect disposition and/or the preview-pane descriptor.
+    Role-exclusive with ``source_meta`` (which rides SYSTEM turns); the decode +
+    role routing lives in ``reconstruct_turns``. No channels → no meta."""
+    envelope: dict[str, Any] = {}
+    if status is not None:
+        envelope["effect_status"] = status.value
+    if preview:
+        envelope["preview"] = preview
+    return json.dumps(envelope) if envelope else None
 
 
 # ---------------------------------------------------------------------------
@@ -1437,6 +1485,16 @@ class ChatSession:
         self._notify_count = 0
         # Watch support: server-level runner injected via set_watch_runner()
         self._watch_runner: Any = None  # WatchRunner | None
+        # The wake_fn last passed to set_watch_runner, kept so a non-fork
+        # resume() can re-register the dispatch closure under the adopted
+        # ws_id with the same wake wiring (registration follows identity).
+        self._watch_wake_fn: Callable[[], object] | None = None
+        # The dispatch closure this session last registered — the OWNER
+        # token for registry removals: multiple live sessions can
+        # transiently serve one ws_id (watch-restore shell vs a reopened
+        # pane; in-session /resume of an id open in another pane), and a
+        # blind removal on teardown would unregister the OTHER session.
+        self._watch_dispatch_fn: Callable[[dict[str, Any], str], None] | None = None
         # Metacognitive nudges: ephemeral prompts for proactive memory use.
         # One ``NudgeQueue`` per session; producers tag each entry with a
         # channel and consumers drain by filter, emitting each drained nudge
@@ -1487,6 +1545,11 @@ class ChatSession:
         # (only for non-ordinary outcomes — e.g. UNKNOWN on a timeout/cancel)
         # and popped at the fold; same lifecycle as ``_tool_error_flags``.
         self._tool_status: dict[str, EffectStatus] = {}
+        # Preview-pane side channel: call_id → (descriptor, blob Attachment),
+        # set by ``_exec_open_preview`` and popped at the fold, where the
+        # descriptor lands on the tool turn's meta and the blob persists
+        # content-addressed against the turn; same lifecycle as the two above.
+        self._tool_previews: dict[str, tuple[dict[str, Any], Attachment]] = {}
         # Cooperative cancellation: set from outside to stop generation
         self._cancel_event = threading.Event()
         self._cancel_ref: _CancelRef = _CancelRef(self)  # provider appends SDK stream here
@@ -2770,7 +2833,7 @@ class ChatSession:
         else:
             self._tool_search = None
 
-    def set_watch_runner(self, runner: Any) -> None:
+    def set_watch_runner(self, runner: Any, wake_fn: Callable[[], object] | None = None) -> None:
         """Inject the server-level WatchRunner and register a dispatch fn
         that routes watch results onto this session's NudgeQueue.
 
@@ -2789,14 +2852,37 @@ class ChatSession:
             sourced from arbitrary shell output can't tamper with the
             envelope at interpolation time.
 
+        ``wake_fn`` runs once per enqueued fire, AFTER the entry lands
+        on the queue.  The server wires it to
+        :func:`turnstone.core.idle_nudge_watcher.wake_workstream_if_pending`
+        closed over this session's Workstream: a watch firing on an
+        ALREADY-idle workstream sees no IDLE transition, so without an
+        explicit wake the entry would sit queued until the next user
+        message.  Busy workstreams stay safe — the wake gate defers to
+        ``session_worker.send``'s atomic ownership check, which
+        downgrades the wake to a no-op while a worker owns the session
+        (the in-flight worker drains the ``"any"``-channel entry at its
+        next seam).  Exceptions from ``wake_fn`` are logged and
+        swallowed: the enqueue already happened, and a raise here would
+        abort ``WatchRunner._poll_watch`` before the watch-row update
+        commits — re-firing the same reminder every subsequent tick.
+
         No ``valid_until`` predicate is wired: ``WatchRunner._poll_watch``
         commits ``active=False`` for terminal fires right after dispatch
         returns, and an ``is_watch_active`` predicate would race that
         write at drain time and drop the fire the model was meant to see.
         A user-cancelled watch's last splat is informative (the reminder
         carries ``is_final=True``), not stale-noise to suppress.
+
+        The registration is keyed on ``self._ws_id`` AT CALL TIME.  The
+        identity-rebind sites (non-fork :meth:`resume`, ``/new``) call
+        :meth:`_follow_watch_registration` to move it onto the new id
+        (re-invoking this method with the ``wake_fn`` stored below) —
+        callers therefore don't need to order their own
+        ``set_watch_runner``/``resume`` calls.
         """
         self._watch_runner = runner
+        self._watch_wake_fn = wake_fn
         nudge_queue = self._nudge_queue
         ws_id = self._ws_id
 
@@ -2839,7 +2925,13 @@ class ChatSession:
                 "any",
                 metadata=metadata or None,
             )
+            if wake_fn is not None:
+                try:
+                    wake_fn()
+                except Exception:
+                    log.warning("watch_dispatch.wake_failed ws=%s", ws_id, exc_info=True)
 
+        self._watch_dispatch_fn = _dispatch
         runner.set_dispatch_fn(self._ws_id, _dispatch)
 
     def close(self) -> None:
@@ -2876,8 +2968,12 @@ class ChatSession:
                 self._mcp_prompt_cb, user_id=self._mcp_listener_user_id
             )
             self._mcp_prompt_cb = None
-        if self._watch_runner:
-            self._watch_runner.remove_dispatch_fn(self._ws_id)
+        if self._watch_runner and self._watch_dispatch_fn is not None:
+            # Owner-checked: a watch-restore shell and a reopened pane can
+            # both have served this ws_id — tearing down one must not
+            # unregister the other (whose next fire would then restore a
+            # DUPLICATE auto-approved session onto the live conversation).
+            self._watch_runner.remove_dispatch_fn(self._ws_id, owner=self._watch_dispatch_fn)
         if self._coord_client is not None and hasattr(self._coord_client, "close"):
             try:
                 self._coord_client.close()
@@ -2964,18 +3060,21 @@ class ChatSession:
         *,
         is_error: bool = False,
         status: EffectStatus | None = None,
+        preview: dict[str, Any] | None = None,
     ) -> None:
         """Notify the UI and record error flag for message persistence.
 
         ``status`` is the typed effect disposition (HYPOTHESIS.md effect-record
         appendix), set only for non-ordinary outcomes — UNKNOWN on a timeout or
         mid-flight cancel — and folded onto the persisted tool turn. ``None``
-        leaves the turn unclassified (the ordinary case)."""
+        leaves the turn unclassified (the ordinary case). ``preview`` is the
+        preview-pane descriptor riding the live event so the pane opens without
+        waiting for the fold."""
         if is_error:
             self._tool_error_flags[call_id] = True
         if status is not None:
             self._tool_status[call_id] = status
-        self.ui.on_tool_result(call_id, name, output, is_error=is_error)
+        self.ui.on_tool_result(call_id, name, output, is_error=is_error, preview=preview)
 
     def _ui_event_id(self) -> int | None:
         """Current per-ws SSE ring-buffer high-water mark for stamping
@@ -3313,6 +3412,9 @@ class ChatSession:
         turns = load_message_turns(ws_id)
         if not turns:
             return False
+        # Pre-rebind identity, for moving the watch dispatch registration
+        # onto the adopted id at the end of a successful non-fork resume.
+        old_ws_id = self._ws_id
         # Load persisted config and parse the persona stamp BEFORE touching
         # session identity/history: a corrupt stamp must raise while this
         # session is still intact — the web /command surface reports the
@@ -3529,9 +3631,42 @@ class ChatSession:
             cooldown_secs=self._mem_cfg.nudge_cooldown,
         ):
             self._queue_user_advisory("resume", format_nudge("resume"))
+        if not fork:
+            self._follow_watch_registration(old_ws_id)
         self._init_system_messages()
         return True
 
+    def _follow_watch_registration(self, old_ws_id: str) -> None:
+        """Move the watch dispatch registration onto the current
+        ``_ws_id`` after an identity rebind (non-fork :meth:`resume`,
+        ``/new``).
+
+        The registry is keyed by ``_ws_id`` at registration time.
+        Without the move, watches stamped with the NEW id never find
+        this live session — every fire takes the restore path and
+        spawns a DUPLICATE auto-approved session racing writes into the
+        same conversation — while fires for the OLD id keep delivering
+        into a session that no longer displays that conversation.  The
+        new key goes live BEFORE the old one is removed so no fire can
+        observe a window with no registration at all (which would
+        likewise divert to the restore path).  If ANOTHER live session
+        already serves the new id (in-session /resume of a workstream
+        open in a second pane — an inherently degenerate two-writers
+        state), its registration is NOT stolen: the original owner
+        keeps its watch fires.  Removal of the old key is owner-checked
+        for the same reason.
+        """
+        if self._watch_runner is None:
+            return
+        old_fn = self._watch_dispatch_fn
+        existing = self._watch_runner.get_dispatch_fn(self._ws_id)
+        if existing is None or existing is old_fn:
+            self.set_watch_runner(self._watch_runner, wake_fn=self._watch_wake_fn)
+        else:
+            log.warning("watch_registry.adopted_id_owned_elsewhere ws=%s", self._ws_id[:8])
+        if old_ws_id != self._ws_id:
+            self._watch_runner.remove_dispatch_fn(old_ws_id, owner=old_fn)
+
     def _nudges_enabled(self, nudge_type: str) -> bool:
         """Config gate + persona lever 4 for metacognitive nudges.
 
@@ -5967,8 +6102,9 @@ class ChatSession:
 
                     # Operator context for this result: output-guard
                     # findings + queued user messages (Seam 1), plus
-                    # tool-channel metacog nudges (tool_error / repeat) and
-                    # any-channel nudges (watch_triggered / idle_children).
+                    # tool-channel metacog nudges (tool_error / repeat /
+                    # denial) and any-channel nudges (watch_triggered /
+                    # idle_children).
                     # All of them are now emitted as first-class
                     # ``{"role": "system"}`` turns AFTER this clean tool
                     # message (uniform attach rule) — the tool message content
@@ -5996,6 +6132,12 @@ class ChatSession:
                     tool_status = self._tool_status.pop(tc_id, None)
                     if tool_status is not None:
                         tool_msg["_effect_status"] = tool_status.value
+                    # Preview descriptor + blob (``_exec_open_preview``): the
+                    # descriptor rides the turn's meta side channel to the
+                    # frontend; the blob persists content-addressed below.
+                    tool_preview = self._tool_previews.pop(tc_id, None)
+                    if tool_preview is not None:
+                        tool_msg["_preview"] = tool_preview[0]
                     self.messages.append(turn_from_dict(tool_msg))
 
                     # Token estimation — image content uses a fixed heuristic
@@ -6037,12 +6179,15 @@ class ChatSession:
                         tool_call_id=tc_id,
                         event_id=self._ui_event_id(),
                         is_error=tool_is_error,
-                        meta=_effect_status_meta(tool_status),
+                        meta=_tool_turn_meta(
+                            tool_status, tool_preview[0] if tool_preview else None
+                        ),
                     )
-                    if tool_image_atts and tool_message_id:
-                        self._persist_attachment_refs(
-                            tool_message_id, tool_image_atts, origin="tool"
-                        )
+                    tool_atts = list(tool_image_atts)
+                    if tool_preview is not None:
+                        tool_atts.append(tool_preview[1])
+                    if tool_atts and tool_message_id:
+                        self._persist_attachment_refs(tool_message_id, tool_atts, origin="tool")
 
                     # Accumulate this result's operator context (guard
                     # findings per-result; queued interjections + metacog
@@ -6174,10 +6319,11 @@ class ChatSession:
     def _drain_pending_advisories(self) -> None:
         """Drop every pending nudge regardless of channel.
 
-        Tool-channel nudges (``tool_error``, ``repeat``) queued earlier
-        in this batch and user-channel nudges (``correction``,
-        ``denial``, …) queued during ``_check_metacognitive_nudge`` but
-        not yet drained share the same per-session :class:`NudgeQueue`.
+        Tool-channel nudges (``tool_error``, ``repeat``, ``denial``)
+        queued earlier in this batch and user-channel nudges
+        (``correction``, …) queued during ``_check_metacognitive_nudge``
+        but not yet drained share the same per-session
+        :class:`NudgeQueue`.
         When a generation is abandoned (cancel, KeyboardInterrupt,
         unexpected exception) the entire queue drops so nothing bleeds
         into the next send's tool loop or next user turn.
@@ -6223,11 +6369,23 @@ class ChatSession:
             tc_id = tc.id
             func_name = tc.name
             if tc_id and tc_id not in answered_ids:
-                self.messages.append(
-                    Turn.tool(tc_id, detail, is_error=True, effect_status=EffectStatus.UNKNOWN)
+                # A staged preview means _exec_open_preview COMPLETED and its
+                # descriptor already reached the frontend (live SSE at exec
+                # time) — the pane is open on it.  Discarding the blob here
+                # would 404 that pane forever and drop the reopen chip from
+                # replay, so commit blob + descriptor with the synthesized
+                # turn even though the BATCH outcome is unknown.  Popping
+                # regardless also keeps a never-shown blob from pinning its
+                # bytes in memory for the session's life.
+                preview_entry = self._tool_previews.pop(tc_id, None)
+                cancelled_turn = Turn.tool(
+                    tc_id, detail, is_error=True, effect_status=EffectStatus.UNKNOWN
                 )
+                if preview_entry is not None:
+                    cancelled_turn.meta.extra["preview"] = preview_entry[0]
+                self.messages.append(cancelled_turn)
                 self._msg_tokens.append(1)
-                save_message(
+                cancelled_row_id = save_message(
                     self._ws_id,
                     "tool",
                     detail,
@@ -6235,8 +6393,15 @@ class ChatSession:
                     tool_call_id=tc_id,
                     event_id=self._ui_event_id(),
                     is_error=True,
-                    meta=_effect_status_meta(EffectStatus.UNKNOWN),
+                    meta=_tool_turn_meta(
+                        EffectStatus.UNKNOWN,
+                        preview_entry[0] if preview_entry else None,
+                    ),
                 )
+                if preview_entry is not None and cancelled_row_id:
+                    self._persist_attachment_refs(
+                        cancelled_row_id, [preview_entry[1]], origin="tool"
+                    )
                 # Emit synthetic tool_result so live SSE listeners can
                 # complete the in-DOM tool batch — without this the
                 # coord ``--running`` indicator (added by SSE
@@ -8569,10 +8734,11 @@ class ChatSession:
           ``priority`` so the UI can frame important interjections
           distinctly.  Cancel / exception / no-tool-call paths drain the
           queue as a real user row instead (Seams 2 and 3).
-        - **Metacognitive tool-channel nudges** (``tool_error`` / ``repeat``)
-          and any-channel nudges (``watch_triggered`` / ``idle_children``)
-          — drained on the last result.  ``meta`` carries the producer's
-          optional fields (e.g. ``watch_triggered``'s ``watch_name``).
+        - **Metacognitive tool-channel nudges** (``tool_error`` /
+          ``repeat`` / ``denial``) and any-channel nudges
+          (``watch_triggered`` / ``idle_children``) — drained on the last
+          result.  ``meta`` carries the producer's optional fields
+          (e.g. ``watch_triggered``'s ``watch_name``).
 
         Empty when no advisories apply (common case).  Guard findings
         attach per-result; queued messages and metacognitive nudges drain
@@ -8783,7 +8949,13 @@ class ChatSession:
                 memory_count=self._visible_memory_count(),
                 cooldown_secs=self._mem_cfg.nudge_cooldown,
             ):
-                self._queue_user_advisory("denial", format_nudge("denial"))
+                # Tool channel, not user: the denial is a response to THIS
+                # batch, so the nudge rides ``_collect_advisories`` alongside
+                # the denied tool results (same seam as tool_error / repeat)
+                # instead of deferring to the next user-message seam — by
+                # which point the model has already reacted to the denial
+                # without it.
+                self._queue_tool_advisory("denial", format_nudge("denial"))
 
         # Phase 3: execute (check cancellation before starting)
         self._check_cancelled()
@@ -9063,6 +9235,7 @@ class ChatSession:
             "edit_file": self._prepare_edit_file,
             "web_fetch": self._prepare_web_fetch,
             "web_search": self._prepare_web_search,
+            "open_preview": self._prepare_open_preview,
             "tool_search": self._prepare_tool_search,
             "task_agent": self._prepare_task,
             "memory": self._prepare_memory,
@@ -9629,6 +9802,19 @@ class ChatSession:
             "replace_all": replace_all,
         }
 
+    def _allow_private_network(self) -> bool:
+        """Live read of ``tools.allow_private_network`` (admin Settings → Tools).
+
+        Read per prepare — an admin flipping the toggle takes effect on the
+        next tool call, no restart or config push.  Surfaces without a
+        ConfigStore (bare CLI, eval) stay strict: there is no admin surface
+        to have opted in on.
+        """
+        cs = getattr(self, "_config_store", None)
+        if cs is None:
+            return False
+        return bool(cs.get("tools.allow_private_network"))
+
     def _prepare_web_fetch(self, call_id: str, args: dict[str, Any]) -> dict[str, Any]:
         url = args.get("url", "").strip()
         question = args.get("question", "").strip()
@@ -9659,31 +9845,134 @@ class ChatSession:
                 "needs_approval": False,
                 "error": f"Error: URL must start with http:// or https:// (got {url!r})",
             }
-        # SSRF protection: reject private/link-local/metadata IPs
-        ssrf_err = check_ssrf(url)
-        if ssrf_err:
+        # SSRF screen \u2014 a NAMED private address is approvable under the
+        # tools.allow_private_network opt-in (the header tags it so the
+        # operator approves it as what it is).
+        screen_err, private_origin = _screen_tool_url(url, self._allow_private_network())
+        if screen_err:
             return {
                 "call_id": call_id,
                 "func_name": "web_fetch",
-                "header": "\u2717 web_fetch: blocked (private network)",
+                "header": "\u2717 web_fetch: blocked (private network)"
+                if "private/internal" in screen_err
+                else "\u2717 web_fetch: blocked",
                 "preview": f"    {url}",
                 "needs_approval": False,
-                "error": f"Error: {ssrf_err}",
+                "error": screen_err,
             }
         q_preview = question[:200] + ("..." if len(question) > 200 else "")
         preview = f"    {url}\n    Q: {q_preview}"
+        private_tag = " (private network)" if private_origin else ""
         return {
             "call_id": call_id,
             "func_name": "web_fetch",
-            "header": f"\u2699 web_fetch: {url[:80]}",
+            "header": f"\u2699 web_fetch: {url[:80]}{private_tag}",
             "preview": preview,
             "needs_approval": True,
             "approval_label": "web_fetch",
             "execute": self._exec_web_fetch,
             "url": url,
             "question": question,
+            "allow_private_origin": private_origin,
         }
 
+    def _prepare_open_preview(self, call_id: str, args: dict[str, Any]) -> dict[str, Any]:
+        """Prepare a preview-pane open for approval / execution.
+
+        The target decides the approval posture: an http(s) URL is network
+        egress and gates like ``web_fetch``; a file path or an
+        ``attachment:<id>`` reference is a local read and runs unprompted like
+        ``read_file``.  SSRF screening happens here (pre-approval) so a
+        blocked target never even reaches the approval card, and again on the
+        post-redirect URL at execution.
+        """
+        target = str(args.get("target") or "").strip()
+        kind = args.get("kind")
+        title = args.get("title")
+        if not target:
+            return {
+                "call_id": call_id,
+                "func_name": "open_preview",
+                "header": "✗ open_preview: missing target",
+                "preview": "",
+                "needs_approval": False,
+                "error": "Error: missing target",
+            }
+        if kind is not None and kind not in PREVIEW_KINDS:
+            return {
+                "call_id": call_id,
+                "func_name": "open_preview",
+                "header": "✗ open_preview: invalid kind",
+                "preview": "",
+                "needs_approval": False,
+                "error": (f"Error: kind must be one of {sorted(PREVIEW_KINDS)} (got {kind!r})"),
+            }
+        item: dict[str, Any] = {
+            "call_id": call_id,
+            "func_name": "open_preview",
+            "header": f"⚙ open_preview: {target[:80]}",
+            "preview": "",
+            "execute": self._exec_open_preview,
+            "kind": kind,
+            "title": str(title).strip() if title else None,
+        }
+        if target.startswith(("http://", "https://")):
+            # Same opt-in lane as web_fetch: a named private address is
+            # approvable under tools.allow_private_network, tagged so the
+            # operator approves it as what it is.
+            screen_err, private_origin = _screen_tool_url(target, self._allow_private_network())
+            if screen_err:
+                return {
+                    "call_id": call_id,
+                    "func_name": "open_preview",
+                    "header": "✗ open_preview: blocked (private network)"
+                    if "private/internal" in screen_err
+                    else "✗ open_preview: blocked",
+                    "preview": f"    {target}",
+                    "needs_approval": False,
+                    "error": screen_err,
+                }
+            if private_origin:
+                item["header"] = f"⚙ open_preview: {target[:80]} (private network)"
+            item.update(
+                {
+                    "preview": f"    {target}",
+                    "needs_approval": True,
+                    "approval_label": "open_preview",
+                    "target_kind": "url",
+                    "url": target,
+                    "allow_private_origin": private_origin,
+                }
+            )
+            return item
+        if target.startswith("attachment:"):
+            attachment_id = target[len("attachment:") :].strip()
+            if not attachment_id:
+                return {
+                    "call_id": call_id,
+                    "func_name": "open_preview",
+                    "header": "✗ open_preview: empty attachment id",
+                    "preview": "",
+                    "needs_approval": False,
+                    "error": "Error: attachment:<id> requires an id",
+                }
+            item.update(
+                {
+                    "needs_approval": False,
+                    "target_kind": "attachment",
+                    "attachment_id": attachment_id,
+                }
+            )
+            return item
+        item.update(
+            {
+                "needs_approval": False,
+                "target_kind": "path",
+                "path": os.path.expanduser(target),
+            }
+        )
+        return item
+
     def _prepare_web_search(self, call_id: str, args: dict[str, Any]) -> dict[str, Any]:
         """Prepare a web search via the configured backend for approval."""
         query = (args.get("query") or "").strip()
@@ -10398,8 +10687,10 @@ class ChatSession:
 
         Drains in ``_emit_pending_user_nudges`` and is appended as a
         first-class ``{"role": "system"}`` turn AFTER the user turn.  Used
-        for nudges that respond to user behaviour: ``correction``,
-        ``denial``, ``resume``, ``start``, ``completion``.
+        for nudges that respond to the user's message: ``correction``,
+        ``resume``, ``start``, ``completion``.  (``denial`` is user
+        behaviour too, but it responds to a specific TOOL BATCH — it
+        rides the tool channel so it lands with the denied results.)
 
         No-ops while the session is inside a wake-driven turn
         (``_wake_source_tag`` set) so model behaviour during the wake
@@ -10423,8 +10714,8 @@ class ChatSession:
         the system turns sit after the user turn they advise (uniform attach
         rule).  Each drained nudge becomes one ``{"role": "system",
         "_source": <nudge_type>, ...}`` turn via :meth:`_append_system_turn`
-        — the source is the nudge type (``correction`` / ``denial`` /
-        ``resume`` / ``start`` / ``completion`` / ``idle_children`` /
+        — the source is the nudge type (``correction`` / ``resume`` /
+        ``start`` / ``completion`` / ``idle_children`` /
         ``watch_triggered``) and any optional metadata (e.g.
         ``watch_triggered``'s ``watch_name``) rides as sibling keys.
         ``_append_system_turn`` persists each row and fires the live
@@ -10461,8 +10752,9 @@ class ChatSession:
         Drains in ``_collect_advisories`` alongside guard findings, then is
         emitted as a first-class ``{"role": "system"}`` turn AFTER the tool
         batch (see the per-result loop in ``_run_loop``).  Used for nudges
-        that respond to model behaviour at a tool boundary: ``tool_error``,
-        ``repeat``.
+        that respond to a tool batch: ``tool_error``, ``repeat`` (model
+        behaviour), and ``denial`` (the operator rejected the batch — the
+        nudge belongs next to the denied results it explains).
 
         No-ops while the session is inside a wake-driven turn (see
         ``_queue_user_advisory`` for the rationale).
@@ -10522,6 +10814,14 @@ class ChatSession:
         self._wake_drained_reminders = wake_reminders
         try:
             self.send("", from_wake=True)
+        except GenerationCancelled:
+            # A close/force-cancel raced this unattended wake turn.  This
+            # method IS the wake worker's run() closure, and
+            # ``session_worker._runner`` catches only ``Exception`` — a
+            # BaseException here would escape to ``threading.excepthook``
+            # as stderr noise.  The teardown gates stop any respawn; the
+            # cancellation itself is the intended outcome.
+            log.info("wake_nudge.cancelled ws=%s", self._ws_id[:8])
         finally:
             self._wake_source_tag = ""
             self._wake_drained_reminders = None
@@ -15681,15 +15981,22 @@ class ChatSession:
             # view (already-inactive or just-cancelled with empty
             # next_poll), so the runner's retry-deactivate branch will
             # never reclaim a pending ``_terminal_dispatched`` entry.
-            # Clear it here to bound the lifetime of any leftover from
-            # a previous dispatch-then-failed-row-write.
-            if self._watch_runner is not None:
-                self._watch_runner.forget_terminal_dispatched(target["watch_id"])
+            # Clear it via ``forget_terminal_dispatched`` to bound the
+            # lifetime of any leftover from a previous
+            # dispatch-then-failed-row-write — AFTER the row write, per
+            # that method's ordering contract: the runner's delivery
+            # paths re-check the row before stashing, so clearing first
+            # would let a racing poll thread re-stash a held reminder
+            # behind the clear.
             if not target["active"]:
+                if self._watch_runner is not None:
+                    self._watch_runner.forget_terminal_dispatched(target["watch_id"])
                 msg = f'Watch "{target["name"]}" already completed (auto-cancelled).'
                 self._report_tool_result(call_id, "watch", msg)
                 return call_id, msg
             storage.update_watch(target["watch_id"], active=False, next_poll="")
+            if self._watch_runner is not None:
+                self._watch_runner.forget_terminal_dispatched(target["watch_id"])
             msg = f'Watch "{target["name"]}" cancelled.'
             self._report_tool_result(call_id, "watch", msg)
             return call_id, msg
@@ -15838,13 +16145,14 @@ class ChatSession:
         call_id, url = item["call_id"], item["url"]
         question = item.get("question", "Summarize the key content of this page.")
 
-        # Phase 1: fetch the URL
+        # Phase 1: fetch the URL.  The guarded fetch SSRF-screens every
+        # redirect hop before requesting it (the prepare-time check covers
+        # only the URL the model named, not where it 302s).
         try:
-            resp = httpx.get(
+            resp = fetch_with_ssrf_guard(
                 url,
-                headers={"User-Agent": "turnstone/1.0"},
                 timeout=self.tool_timeout,
-                follow_redirects=True,
+                allow_private_origin=item.get("allow_private_origin", False),
             )
             resp.raise_for_status()
             ct = resp.headers.get("content-type", "")
@@ -15887,10 +16195,17 @@ class ChatSession:
             text = text[:max_content] + f"\n\n... [{len(text) - max_content} chars truncated] ...\n"
 
         # Phase 3: summarization API call.
-        # Use a generous max_tokens so thinking models don't starve the
-        # visible answer, and pass reasoning_effort="low" to avoid wasting
-        # budget on deep reasoning for a simple extraction task.  Temperature
-        # is left to the session/registry default rather than overridden here.
+        # Inherit the operator's per-model settings — reasoning_effort and
+        # (via the default) temperature from the session/registry — rather
+        # than forcing constants here: hard-coding reasoning_effort="low" and
+        # a fixed max_tokens kept breaking local-inference models whose
+        # registry entry advertises a different reasoning config or a tighter
+        # output limit.  max_tokens is the session budget, but capped to the
+        # ~25% window slice Phase 2 reserved above — the same bound the main
+        # turn puts on its response reserve (``_remaining_token_budget``).
+        # That honors a tighter registry max_tokens while keeping prompt +
+        # output from overflowing a small context window on strict runtimes
+        # (the old fixed 8192 was exactly this reserve for the 32k default).
         try:
             result = self._utility_completion(
                 [
@@ -15913,7 +16228,8 @@ class ChatSession:
                         ),
                     },
                 ],
-                max_tokens=8192,
+                max_tokens=min(self.max_tokens, self.context_window // 4),
+                reasoning_effort=self.reasoning_effort,
             )
             answer = result.content or ""
             if not answer:
@@ -15930,6 +16246,159 @@ class ChatSession:
 
         return call_id, answer
 
+    def _exec_open_preview(self, item: dict[str, Any]) -> tuple[str, str]:
+        """Resolve the preview target to bytes and hand the pane its descriptor.
+
+        Content is resolved server-side (URL fetch through the web_fetch
+        guards, local read, or committed-attachment lookup), classified by
+        ``resolve_preview_kind``, size-capped, and stashed on the
+        ``_tool_previews`` side channel: the fold persists the bytes
+        content-addressed against the tool turn and folds the descriptor onto
+        its meta.  The model gets a one-line confirmation — the content itself
+        is for the user's pane, not the wire.
+        """
+        self._check_cancelled()
+        call_id = item["call_id"]
+        target_kind = item["target_kind"]
+        kind_override = item.get("kind")
+        title_override = item.get("title")
+
+        def _fail(msg: str) -> tuple[str, str]:
+            self._report_tool_result(call_id, "open_preview", msg, is_error=True)
+            return call_id, msg
+
+        body: bytes
+        if target_kind == "url":
+            url = item["url"]
+            try:
+                # Every redirect hop is SSRF-screened BEFORE its request goes
+                # out — the pre-approval screen covers only the URL the model
+                # named, not where it 302s.  The fetch ceiling tracks the most
+                # permissive kind cap (like the path lane's stat pre-check);
+                # the per-kind cap after resolution is the authority.
+                resp = fetch_with_ssrf_guard(
+                    url,
+                    timeout=self.tool_timeout,
+                    allow_private_origin=item.get("allow_private_origin", False),
+                    max_bytes=max(PREVIEW_SIZE_CAPS.values()),
+                )
+                resp.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                return _fail(f"Error: fetch failed: HTTP {e.response.status_code}")
+            except (httpx.RequestError, ValueError) as e:
+                return _fail(f"Error: fetch failed: {e}")
+            final_url = str(resp.url)
+            # The final URL feeds the descriptor (displayed, persisted) and
+            # the stored <base href> — strip any userinfo so embedded
+            # credentials never reach the transcript or the stored bytes.
+            if resp.url.username or resp.url.password:
+                final_url = str(resp.url.copy_with(username=None, password=None))
+            body = resp.content
+            mime_hint = resp.headers.get("content-type", "")
+            name_hint = final_url
+            source = final_url
+        elif target_kind == "attachment":
+            from turnstone.core.memory import attachment_referenced_in_ws, get_attachment
+
+            attachment_id = item["attachment_id"]
+            row = get_attachment(attachment_id)
+            if not row or not attachment_referenced_in_ws(attachment_id, self._ws_id):
+                # Mirror the serving gate: unreferenced ids read as absent so
+                # existence in other workstreams doesn't leak.
+                return _fail(f"Error: attachment not found: {attachment_id}")
+            body = row.get("content") or b""
+            mime_hint = str(row.get("mime_type") or "")
+            name_hint = str(row.get("filename") or "")
+            source = name_hint or f"attachment:{attachment_id}"
+        else:
+            path = item["path"]
+            resolved = os.path.realpath(path)
+            if not os.path.isfile(resolved):
+                return _fail(f"Error: file not found: {path}")
+            try:
+                size = os.path.getsize(resolved)
+                if size > max(PREVIEW_SIZE_CAPS.values()):
+                    return _fail(
+                        f"Error: file too large to preview ({size:,} bytes; "
+                        f"cap {max(PREVIEW_SIZE_CAPS.values()):,})"
+                    )
+                with open(resolved, "rb") as f:
+                    body = f.read()
+            except OSError as e:
+                return _fail(f"Error: could not read file: {e}")
+            mime_hint = ""
+            name_hint = path
+            source = path
+
+        if not body:
+            return _fail("Error: nothing to preview (empty content)")
+
+        resolved_kind = resolve_preview_kind(mime_hint, name_hint, body, kind_override)
+        if resolved_kind is None:
+            hint = f" (content-type {mime_hint.split(';')[0]})" if mime_hint else ""
+            return _fail(
+                f"Error: content is not previewable{hint} — supported kinds: "
+                f"{', '.join(sorted(PREVIEW_KINDS))}"
+            )
+        kind, stored_mime = resolved_kind
+        cap = PREVIEW_SIZE_CAPS[kind]
+        if len(body) > cap:
+            return _fail(
+                f"Error: {kind} content too large to preview ({len(body):,} bytes; cap {cap:,})"
+            )
+
+        title = title_override
+        if kind in ("web", "table", "text", "markdown"):
+            # Store text-family content as UTF-8 so legacy charsets render
+            # instead of erroring "not previewable": a fetch honors the
+            # response charset (httpx ``resp.text``); local / attachment bytes
+            # go through the transcode ladder.  Web additionally gains a
+            # ``<base href>`` (url targets) and a title fallback.
+            text = resp.text if target_kind == "url" else transcode_text(body, mime_hint)
+            if kind == "web":
+                if target_kind == "url":
+                    text = inject_base_href(text, final_url)
+                if not title:
+                    title = page_title(text)
+            body = text.encode("utf-8")
+            if len(body) > cap:
+                return _fail(
+                    f"Error: {kind} content too large to preview ({len(body):,} bytes; cap {cap:,})"
+                )
+        if not title:
+            tail = name_hint.rsplit("/", 1)[-1].split("?", 1)[0]
+            title = tail or source
+        title = title[:200]
+
+        # Salted out of the upload namespace: model-visible attachments use
+        # bare sha256(body) and save_attachment freezes `kind` at first insert,
+        # so a byte-identical preview and upload would otherwise share a row —
+        # whichever lands second inherits the other's kind (hiding an upload
+        # from model context, or materializing preview bytes into it).
+        blob_id = hashlib.sha256(b"preview:" + body).hexdigest()
+        descriptor = build_preview_descriptor(
+            kind=kind,
+            title=title,
+            source=source,
+            attachment_id=blob_id,
+            content_type=stored_mime,
+            size=len(body),
+        )
+        filename = title if "." in title else f"preview-{kind}"
+        self._tool_previews[call_id] = (
+            descriptor,
+            Attachment(
+                attachment_id=blob_id,
+                filename=filename[:120],
+                mime_type=stored_mime,
+                kind=PREVIEW_BLOB_KIND,
+                content=body,
+            ),
+        )
+        msg = f"Preview shown to the user: {title} ({kind}, {len(body):,} bytes)"
+        self._report_tool_result(call_id, "open_preview", msg, preview=descriptor)
+        return call_id, msg
+
     def _exec_web_search(self, item: dict[str, Any]) -> tuple[str, str]:
         """Search the web via the configured backend (SearxNG or MCP)."""
         self._check_cancelled()
@@ -16016,14 +16485,20 @@ class ChatSession:
             self._last_usage = None
             self._calibrated_msg_count = 0
             self._msg_tokens = []
+            old_ws_id = self._ws_id
             self._ws_id = uuid.uuid4().hex
             # A brand-new ws_id is the same class of identity change as a
             # non-fork resume(): the old workstream's participant state must
-            # not leak into this empty one, and its trust nonces must not
-            # carry over (see resume()'s matching reset + remint).
+            # not leak into this empty one, its trust nonces must not carry
+            # over (see resume()'s matching reset + remint), and the watch
+            # dispatch registration must follow the identity — otherwise
+            # watches created here (stamped with the new id) never reach
+            # this session, and the old workstream's fires land in a
+            # conversation that no longer shows them.
             self._reset_shared_state()
             self._envelope_nonce = fence.mint_nonce()
             self._sender_label_nonce = fence.mint_nonce()
+            self._follow_watch_registration(old_ws_id)
             self._title_generated = False
             # The session keeps its persona across /new (the stamp is
             # re-written by _save_config below) — carry the display slug

turnstone/core/session_routes.py

@@ -486,6 +486,7 @@ class AttachmentHandlers:
     list: Handler  # GET    {prefix}/{ws_id}/attachments
     get_content: Handler  # GET    {prefix}/{ws_id}/attachments/{attachment_id}/content
     thumbnail: Handler  # GET    {prefix}/{ws_id}/attachments/{attachment_id}/thumbnail
+    preview: Handler  # GET    {prefix}/{ws_id}/attachments/{attachment_id}/preview
     delete: Handler  # DELETE {prefix}/{ws_id}/attachments/{attachment_id}
 
 
@@ -638,6 +639,13 @@ def register_session_routes(
                 methods=["GET"],
             )
         )
+        routes.append(
+            Route(
+                f"{p}/{{ws_id}}/attachments/{{attachment_id}}/preview",
+                a.preview,
+                methods=["GET"],
+            )
+        )
         routes.append(
             Route(
                 f"{p}/{{ws_id}}/attachments/{{attachment_id}}",
@@ -2238,18 +2246,60 @@ def make_events_handler(cfg: SessionEndpointConfig) -> Handler:
                 # otherwise gate; shortening to 1s 5x'd the wakeup
                 # rate without any client-observable benefit).
                 #
-                # ``_seq`` filter: ``on_content_token`` /
-                # ``on_reasoning_token`` tag each emit with the
-                # per-ws event counter.  On the ``fresh`` path,
-                # events whose seq is already covered by the
-                # snapshot we just yielded get dropped to avoid
-                # double-rendering.  On ``replay_ok`` / ``truncated``
-                # paths, ``snap_seq`` is 0 so no live event is
-                # filtered — the replay buffer (or replay_truncated
-                # envelope) has already established the cutoff.
+                # ``_seq`` filter: token events are tagged with the
+                # per-ws event counter at enqueue time.  On the
+                # ``fresh`` and ``truncated`` paths, events whose seq
+                # is already covered by the snapshot we just yielded
+                # get dropped to avoid double-rendering.  On the
+                # ``replay_ok`` path ``snap_seq`` is 0 so no live
+                # event is filtered — the replayed buffer slice has
+                # already established the cutoff.
                 while True:
                     if await request.is_disconnected():
                         return
+                    if getattr(client_queue, "poisoned", False):
+                        # The queue overflowed: it latched ``poisoned``
+                        # at the FIRST rejected put, freezing its
+                        # contents as a contiguous prefix (see
+                        # ``_ListenerQueue``).
+                        if getattr(client_queue, "closing", False):
+                            # ws teardown raced the overflow: the queue is
+                            # poisoned AND its ws is closing.  Unwind as a
+                            # CLEAN close — no ``stream_overflow`` frame,
+                            # which would otherwise pollute the client's
+                            # drop-vs-wedge instrumentation and trip its
+                            # reconnect limiter on a ws that is simply gone
+                            # (the poisoned queue can't accept the in-band
+                            # ``ws_closed`` sentinel, so ``closing`` is the
+                            # only close signal it will ever see).  Recovery
+                            # of the frozen tail is the ``/history`` reload,
+                            # not a reconnect — the ws is gone.
+                            return
+                        # Genuine slow-consumer overflow (ws still live).
+                        # Close now — the queued backlog is discarded,
+                        # because the ring buffer replays everything past
+                        # the client's ``Last-Event-ID`` on the native
+                        # EventSource reconnect.  Delivering the backlog
+                        # first would only stall recovery behind the very
+                        # consumer that couldn't keep up.  The farewell
+                        # frame is id-less so ``lastEventId`` stays below
+                        # the gap; the client counts these closes for its
+                        # reconnect rate-limiter and the drop-vs-render-
+                        # wedge field instrumentation.
+                        log.info(
+                            "ws.events.overflow_close ws=%s",
+                            ws_id[:8],
+                        )
+                        yield {"data": json.dumps({"type": "stream_overflow", "ws_id": ws_id})}
+                        return
+                    # NOT poisoned: a ``closing`` ws is handled by the
+                    # in-band ``ws_closed`` sentinel below, AFTER the FIFO
+                    # drain delivers every queued event.  Returning here on
+                    # ``closing`` (as an earlier revision did) would drop a
+                    # healthy-but-slightly-behind client's queued tail (the
+                    # turn's final content batch + ``stream_end``) at
+                    # teardown — a permanent truncation, since a close has
+                    # no reconnect+replay to repaint it.
                     try:
                         event = await loop.run_in_executor(
                             live_executor,
@@ -2764,15 +2814,21 @@ def make_create_handler(
                 attachment_ids,
             )
 
-        return JSONResponse(
-            {
-                "ws_id": ws.id,
-                "name": ws.name,
-                "resumed": bool(extra_response.get("resumed", False)),
-                "message_count": int(extra_response.get("message_count", 0)),
-                "attachment_ids": attachment_ids,
-            }
-        )
+        create_payload: dict[str, Any] = {
+            "ws_id": ws.id,
+            "name": ws.name,
+            "resumed": bool(extra_response.get("resumed", False)),
+            "message_count": int(extra_response.get("message_count", 0)),
+            "attachment_ids": attachment_ids,
+        }
+        if extra_response.get("initial_message_status"):
+            # Present only when the post-install hook could NOT deliver
+            # the initial message (raced live worker, interjection queue
+            # full) — the workstream exists, but a bare 200 would read as
+            # "first message accepted".  Mirrors /send's in-body
+            # ``queue_full`` backpressure surface.
+            create_payload["initial_message_status"] = str(extra_response["initial_message_status"])
+        return JSONResponse(create_payload)
 
     return create
 
@@ -3656,6 +3712,7 @@ def make_export_handler(cfg: SessionEndpointConfig) -> Handler:
         from starlette.responses import Response as _Response
 
         from turnstone.core.export import WorkstreamNotFoundError, export_workstream
+        from turnstone.core.web_helpers import latin1_safe_filename
 
         # Conversation-only: never bundle children, always JSON.  A live
         # session whose storage row was deleted skips the fallback
@@ -3665,10 +3722,10 @@ def make_export_handler(cfg: SessionEndpointConfig) -> Handler:
             result = await asyncio.to_thread(export_workstream, storage, ws_id)
         except WorkstreamNotFoundError:
             return JSONResponse({"error": cfg.not_found_label}, status_code=404)
-        # ws_ids are hex so the filename is already safe, but mirror the
-        # attachment download handler's defensive strip of quotes/CR/LF
-        # so a future non-hex id can't break the Content-Disposition.
-        safe_name = result.filename.replace('"', "").replace("\r", "").replace("\n", "")
+        # ws_ids are hex so the filename is already safe, but run the shared
+        # sanitizer anyway so a future non-hex id can't break the
+        # Content-Disposition (latin-1 fold + control-char strip).
+        safe_name = latin1_safe_filename(result.filename)
         return _Response(
             result.data,
             media_type=result.content_type,
@@ -3790,6 +3847,27 @@ def make_detail_handler(cfg: SessionEndpointConfig) -> Handler:
                 # mismatch, and tombstoned rows — all surface as 404.
                 return JSONResponse({"error": cfg.not_found_label}, status_code=404)
 
+            # A detail GET that lazily rehydrates IS an open — run the
+            # same kind-specific post-load the open handler runs.
+            # Skipping it leaves the now-live session with no watch
+            # dispatch registration (its next watch fire would take the
+            # restore path and spawn a duplicate auto-approved session
+            # racing writes into this live conversation) and never tells
+            # dashboards the workstream came live (``ws_created``).
+            if cfg.open_post_load is not None:
+                try:
+                    # Off-loop: interactive's post_load does blocking
+                    # storage I/O (display-name lookup).
+                    await asyncio.to_thread(cfg.open_post_load, request, ws)
+                except Exception:
+                    # Post-load is observational — never let a hook bug
+                    # block the detail response. Log + continue.
+                    log.debug(
+                        "ws.detail.post_load_failed ws=%s",
+                        ws.id[:8],
+                        exc_info=True,
+                    )
+
         # Pending-approval snapshot — lets a freshly-loaded chat tab
         # paint the inline approval gate from this single response
         # instead of waiting for the SSE approve_request replay (which
@@ -4089,6 +4167,12 @@ def make_send_handler(cfg: SessionEndpointConfig) -> Handler:
             thread_name=f"send-worker-{ws.id[:8]}",
         )
         if not ok:
+            if ws._closed:
+                # ``send`` refused because the workstream closed between our
+                # resolution and the dispatch — a ``queue_full`` here would
+                # tell the client to retry a workstream whose very next
+                # resolution 404s.  Mirror the resolution miss instead.
+                return JSONResponse({"error": cfg.not_found_label}, status_code=404)
             # queue.Full or session-disappeared race — surface as
             # queue_full so clients retry rather than 500. ``attached_ids``
             # is always empty on this path (the dispatch never took
@@ -4347,6 +4431,8 @@ def make_attachment_handlers(cfg: SessionEndpointConfig) -> AttachmentHandlers:
     async def get_content(request: Request) -> Response:
         from starlette.responses import Response as _Response
 
+        from turnstone.core.web_helpers import latin1_safe_filename
+
         resolved = await _resolve_served_blob(request)
         if not isinstance(resolved, tuple):
             return resolved
@@ -4355,7 +4441,10 @@ def make_attachment_handlers(cfg: SessionEndpointConfig) -> AttachmentHandlers:
         # rendering if a user uploaded an HTML-ish text file.  Images keep their
         # sniffed MIME (allowlist is strict: png/jpeg/gif/webp).
         response_mime = "text/plain; charset=utf-8" if kind == "text" else stored_mime
-        safe_name = filename.replace('"', "").replace("\r", "").replace("\n", "")
+        # Uploaded filenames routinely carry CJK / em dashes (non-latin-1) and
+        # can carry control bytes — either would 500 the serving route, so run
+        # the shared header sanitizer rather than emit them verbatim.
+        safe_name = latin1_safe_filename(filename)
         headers = {
             "X-Content-Type-Options": "nosniff",
             "Content-Security-Policy": "default-src 'none'; sandbox",
@@ -4364,6 +4453,42 @@ def make_attachment_handlers(cfg: SessionEndpointConfig) -> AttachmentHandlers:
         }
         return _Response(body, media_type=response_mime, headers=headers)
 
+    async def get_preview(request: Request) -> Response:
+        from starlette.responses import Response as _Response
+
+        from turnstone.core.preview import PREVIEW_SERVE_MIMES, preview_response_headers
+
+        resolved = await _resolve_served_blob(request)
+        if not isinstance(resolved, tuple):
+            return resolved
+        body, _kind, stored_mime, filename = resolved
+        # Serve the STORED type so the browser renders it (html document, pdf
+        # viewer, image) — the opposite posture from ``get_content``'s
+        # force-text/plain, made safe by the per-mime CSP sandbox headers
+        # (``preview_response_headers``) plus the pane's iframe sandbox.
+        # Non-renderable types 415 rather than fall back to octet-stream: this
+        # route exists to render, ``/content`` exists to download.
+        bare_mime = stored_mime.split(";", 1)[0].strip().lower()
+        if bare_mime not in PREVIEW_SERVE_MIMES:
+            return JSONResponse({"error": "attachment is not previewable"}, status_code=415)
+        # ``?assets=1`` opts a previewed page back into loading its remote
+        # images / styles; default-off keeps the sandboxed document off the
+        # network (see ``preview_response_headers``).
+        allow_remote_assets = bool(request.query_params.get("assets"))
+        headers = preview_response_headers(
+            bare_mime, filename, allow_remote_assets=allow_remote_assets
+        )
+        # ``?probe=1`` preflight: the pane asks "will the real load paint?"
+        # before pointing an iframe / img at this URL.  Answer with the exact
+        # hardening headers the real response would carry but no body — the
+        # console reverse proxy forwards a HEAD as a full GET, so a HEAD
+        # preflight would drag the whole blob across the node→console hop just
+        # to discard it.  The ownership gate and the renderable-type check
+        # above have already run, so a 204 here means the GET will succeed.
+        if request.query_params.get("probe"):
+            return _Response(status_code=204, headers=headers)
+        return _Response(body, media_type=stored_mime, headers=headers)
+
     async def get_thumbnail(request: Request) -> Response:
         import asyncio
 
@@ -4415,6 +4540,7 @@ def make_attachment_handlers(cfg: SessionEndpointConfig) -> AttachmentHandlers:
         list=list_pending,
         get_content=get_content,
         thumbnail=get_thumbnail,
+        preview=get_preview,
         delete=delete_,
     )
 

turnstone/core/session_ui_base.py

@@ -42,9 +42,110 @@ log = get_logger(__name__)
 
 # Matches WebUI's historical listener queue size and the coordinator
 # UI's ``_LISTENER_QUEUE_MAX``. Per-queue cap keeps a slow SSE consumer
-# from bloating memory.
+# from bloating memory.  Headroom only — the load fix for fast models
+# is emit-time token batching (below), and the recovery for a consumer
+# that still can't keep up is the poison-at-first-overflow close in
+# :class:`_ListenerQueue` + the events handler's reconnect replay.
 _DEFAULT_LISTENER_QUEUE_MAX = 500
 
+# Emit-time micro-batching of content/reasoning fragments.  At
+# local-inference rates (500-2000 tok/s) per-delta ``_enqueue`` calls
+# were the event load that overflowed listener queues; coalescing
+# fragments over a small window cuts the wire event rate 10-20x while
+# staying invisible at human reading speed (tokens already arrive
+# faster than a display frame).  A batch is assembled BEFORE
+# ``_enqueue`` and gets one fresh ``_event_id``, so it never violates
+# the no-in-ring-coalescing rule (see ``_resolve_event_buffer_max``):
+# no consumer's ``last_event_id`` can fall inside a batch.
+#
+# The window is measured from the LAST flush, checked on token
+# arrival (no timer thread): the first fragment after ≥window of
+# quiet flushes immediately (time-to-first-token protection at turn
+# starts and after tool pauses), a sustained stream flushes every
+# ~window, and a slow stream (fragments arriving further apart than
+# the window) degenerates to per-token flushes — batching
+# self-disables.  The size cap bounds worst-case batch size (client
+# repaint cost) independent of rate.  Both are read at call time so
+# tests can pin cadence-sensitive behaviour deterministically.
+_TOKEN_BATCH_WINDOW_SECS = 0.025
+_TOKEN_BATCH_MAX_CHARS = 4096
+
+
+class _ListenerOverflow(queue.Full):
+    """Raised by :meth:`_ListenerQueue.put_nowait` exactly once per queue —
+    at the rejected put that latches ``poisoned``.  A ``queue.Full``
+    subclass so any caller that suppresses ``Full`` keeps working; the
+    fan-out in ``_enqueue_direct`` catches this subclass first to log the
+    overflow transition exactly once without racy flag bookkeeping."""
+
+
+class _ListenerQueue(queue.Queue[dict[str, Any]]):
+    """Per-SSE-listener queue that poisons itself at the FIRST rejected put.
+
+    A silently-dropped event is unrecoverable: once the consumer keeps
+    draining past a drop, its ``Last-Event-ID`` advances beyond the hole
+    and the reconnect replay (``eid > last_event_id``) never revisits it —
+    scattered interleaved drops under saturation corrupt the pane
+    permanently.  Poisoning at the first full instead freezes the queue's
+    contents as a contiguous prefix: the drain loop closes the stream, the
+    client reconnects with the last id it processed, and the ring buffer
+    replays the whole gap (the rejected event included — the ring append
+    precedes the per-listener put).
+
+    The latch and the rejection are one atomic step under the queue's own
+    ``mutex`` — the same lock every ``put_nowait``/``get`` uses — and a
+    poisoned queue refuses every later put.  Without that atomicity a
+    concurrent producer could land a later event in a slot the consumer
+    freed mid-latch, leaving an interior hole BEHIND the delivered
+    high-water mark (exactly the unrecoverable shape poisoning exists to
+    prevent).
+
+    Reimplements ``put_nowait`` against the documented ``queue.Queue``
+    extension surface (``mutex`` / ``_qsize`` / ``_put`` /
+    ``unfinished_tasks`` / ``not_empty``) because the stdlib body offers
+    no hook between the full-check and the insert;
+    ``test_listener_queue_basic_put_get_semantics`` canaries stdlib drift.
+    """
+
+    def __init__(self, maxsize: int = 0) -> None:
+        super().__init__(maxsize)
+        # Latched under ``self.mutex``; read locklessly by the events
+        # handler's drain loop (a stale read just delays the close by
+        # one iteration) and by ``_enqueue_direct``'s fan-out snapshot.
+        self.poisoned = False
+        # Set at ws teardown by ``_broadcast_ws_closed_to_listeners``.
+        # The drain loop consults this INSIDE its ``poisoned`` branch: a
+        # queue that is both poisoned AND closing unwinds as a CLEAN close
+        # rather than emitting a false ``stream_overflow`` frame + client
+        # reconnect.  (A healthy closing queue needs no flag — it drains
+        # its tail FIFO to the in-band ``ws_closed`` sentinel.)  The flag
+        # has to travel out-of-band because a poisoned/full queue rejects
+        # that sentinel — the exact case the eviction-safe retry in
+        # ``_broadcast_ws_closed_to_listeners`` targets.
+        self.closing = False
+
+    def put_nowait(self, item: dict[str, Any]) -> None:
+        with self.mutex:
+            if self.poisoned:
+                raise queue.Full
+            if 0 < self.maxsize <= self._qsize():
+                self.poisoned = True
+                raise _ListenerOverflow
+            self._put(item)
+            self.unfinished_tasks += 1
+            self.not_empty.notify()
+
+    def mark_closing(self) -> None:
+        """Flag this listener's stream for a clean close at ws teardown.
+
+        Out-of-band (a bare bool set under ``self.mutex``) because a
+        poisoned/full queue rejects the in-band ``ws_closed`` sentinel,
+        yet the drain loop must still unwind as a clean close rather than
+        emit a spurious overflow frame.  Idempotent."""
+        with self.mutex:
+            self.closing = True
+
+
 # Recall: how many finished task agents' projected sub-trajectories to retain
 # in memory for /history card rebuilds.  LRU-bounded so a marathon workstream
 # can't grow it without limit; eviction (and a cold reopen, which starts empty)
@@ -146,29 +247,35 @@ def _resolve_event_buffer_max() -> int:
     casual reading of "how many events does an SSE stream see":
 
     1. Local-inference deployments stream at 500–2000 tok/s per
-       active model.  Each token is an ``_enqueue`` call, so a single
-       active workstream can fire ~2000 events/sec sustained.  At
-       the 50000 cap that buys ~25 s of pure token streaming before
-       truncation; at typical cloud-provider rates (50–200 events/sec
-       per stream) it's minutes of coverage.
+       active model.  Emit-time batching (``_TOKEN_BATCH_*``)
+       coalesces those into ~40 events/sec of content, so the cap
+       now buys the ring MINUTES of coverage at any token rate —
+       but tool-chunk storms and multi-listener turns still burst,
+       and the cap is deliberately sized for the pre-batching worst
+       case as safety margin.
     2. Browsers throttle the SSE-drain microtask aggressively when
        the tab isn't visible (Chrome's background-tab budget drops
-       to ~1 wake/min after ~5 min hidden).  A backgrounded tab can
-       legitimately go tens of seconds without draining its
-       EventSource buffer — and PR-G (drop-pings-let-it-die)
-       deliberately closes those connections on hide.  Reconnect-with-
-       replay is the recovery path; if the buffer evicted in the
-       interim, the snapshot floor is all that's left.
+       to ~1 wake/min after ~5 min hidden).  The client closes its
+       EventSource on tab-hide and reconnects with the saved
+       ``Last-Event-ID`` on show (interactive.js ``visibilitychange``
+       handler), so the ring's job is covering that hide window;
+       a consumer that stays slow while visible is handled by the
+       listener-queue poison → reconnect-replay path instead.  If
+       the buffer evicted in the interim, the snapshot floor is all
+       that's left.
 
-    Why not coalesce consecutive content/reasoning tokens?  A naive
-    text-merge breaks the replay-slice semantic: a coalesced entry
-    has the latest ``_event_id`` but text that includes content the
-    client already received under an earlier id, so any consumer
-    with ``last_event_id`` falling INSIDE the coalesced span would
-    double-render.  A correctness-preserving coalesce would need a
-    per-consumer high-water tracker we deliberately don't maintain
-    (consumers register and disconnect independently).  Bigger cap
-    + simple per-event storage avoids the trap.
+    Why not coalesce consecutive content/reasoning tokens IN THE
+    RING?  A naive in-buffer text-merge breaks the replay-slice
+    semantic: a coalesced entry has the latest ``_event_id`` but
+    text that includes content the client already received under an
+    earlier id, so any consumer with ``last_event_id`` falling
+    INSIDE the coalesced span would double-render.  A correctness-
+    preserving coalesce would need a per-consumer high-water tracker
+    we deliberately don't maintain (consumers register and
+    disconnect independently).  Bigger cap + simple per-event
+    storage avoids the trap.  (Emit-time batching is different in
+    kind: it merges fragments BEFORE they get an id, so a batch is
+    one ordinary ring entry no cursor can fall inside.)
 
     Memory cost is ~200–500 bytes per event (deque node + dict
     overhead + payload), so 50000 × 100-ws design ceiling caps at
@@ -505,6 +612,23 @@ class SessionUIBase:
         self._ws_inflight_content_size: int = 0
         self._ws_inflight_reasoning: list[str] = []
         self._ws_inflight_reasoning_size: int = 0
+        # Emit-time token-batch accumulator (see the module-level
+        # ``_TOKEN_BATCH_*`` constants).  Holds not-yet-emitted
+        # content/reasoning fragments; at most ONE kind pends at a time
+        # (a kind switch flushes the other first, preserving arrival
+        # order on the wire).  Pending text is INVISIBLE everywhere —
+        # not in the inflight buffers, not in the ring, no event id —
+        # until ``_flush_token_batch_locked`` appends it to the inflight
+        # buffers AND enqueues the batched event inside one ``_ws_lock``
+        # section, which is what keeps a snapshot's ``snap_seq`` a true
+        # high-water mark for its text (no double-render across a
+        # straddling batch).  All four fields guarded by ``_ws_lock``.
+        self._pending_tokens: list[str] = []
+        self._pending_tokens_size: int = 0
+        self._pending_kind: str = ""
+        # ``time.monotonic()`` of the last real flush; 0.0 makes the
+        # first fragment of a fresh UI flush immediately.
+        self._last_token_flush: float = 0.0
         # Last broadcast (activity, activity_state) tuple — used by
         # :meth:`_broadcast_activity` overrides to dedup back-to-back
         # identical activity ticks. Tool-heavy turns can fire many
@@ -565,6 +689,46 @@ class SessionUIBase:
     def _enqueue(self, data: dict[str, Any]) -> int:
         """Fan ``data`` out to every registered listener queue.
 
+        This is the choke point for every NON-token emit — base-class
+        ``on_*`` hooks, subclass overrides (``state_change`` /
+        ``clear_ui`` / rename), and route-level emits (``cancelled``,
+        the interject path's synthetic ``stream_end``) all land here —
+        so it first flushes any pending token batch.  Without that, a
+        ``stream_end`` could overtake its own turn's trailing content
+        batch: the client resets its streaming refs on ``stream_end``
+        and the late batch would paint into a NEW assistant bubble.
+        Emits that happen on the worker thread (the token producer) are
+        therefore strictly ordered after the tokens that preceded them;
+        cross-thread emits (a streaming tool's background
+        ``tool_output_chunk``) keep their pre-existing best-effort
+        ordering.
+
+        MUST NOT be called while holding ``_ws_lock`` — the flush
+        acquires it (non-reentrant).  Token events never come through
+        here: :meth:`on_content_token` / :meth:`on_reasoning_token`
+        buffer under ``_ws_lock`` and their flush emits via
+        :meth:`_enqueue_direct`.  Every current call site enqueues
+        outside ``_ws_lock``; a violation deadlocks immediately (and
+        loudly) in any test that exercises the path.
+
+        Returns the monotonic ``_event_id`` assigned to this event so a
+        caller that also persists the same turn (e.g.
+        ``ChatSession._append_system_turn``) can stamp the row with the
+        matching id, keeping the ``/history`` resume cursor and the live
+        event stream aligned.
+        """
+        self._flush_token_batch()
+        return self._enqueue_direct(data)
+
+    def _enqueue_direct(self, data: dict[str, Any]) -> int:
+        """Stamp + ring-append + fan out ``data`` (no batch flush).
+
+        Only two kinds of caller: :meth:`_enqueue` (after it flushed the
+        pending token batch) and :meth:`_flush_token_batch_locked` (the
+        flush itself, which runs under ``_ws_lock`` — acquisition order
+        ``_ws_lock`` outer → ``_listeners_lock`` inner matches the
+        snapshot helpers).
+
         Stamps ``ws_id`` on the payload if not already present so the
         browser can validate it belongs to the pane's current
         workstream.  Stamps a monotonic ``_event_id`` on every event
@@ -583,11 +747,12 @@ class SessionUIBase:
         fanned out to a not-yet-registered listener AND missing from
         the replay buffer.
 
-        Returns the monotonic ``_event_id`` assigned to this event so a
-        caller that also persists the same turn (e.g.
-        ``ChatSession._append_system_turn``) can stamp the row with the
-        matching id, keeping the ``/history`` resume cursor and the live
-        event stream aligned.
+        Fan-out skips queues already poisoned (their stream is closing;
+        puts would be latch-refused anyway) and logs the poison
+        TRANSITION exactly once per listener via the
+        :class:`_ListenerOverflow` first-rejection signal — the node-side
+        visibility for an overflow that is otherwise only observable in
+        the browser (a proxied coordinator pane hides it entirely).
         """
         if "ws_id" not in data:
             data = {**data, "ws_id": self.ws_id}
@@ -607,12 +772,123 @@ class SessionUIBase:
                 # bypassing the snapshot filter by absence of ``_seq``.
                 data = {**data, "_seq": event_id}
             self._event_buffer.append((event_id, data))
-            snapshot = list(self._listeners)
+            snapshot = [lq for lq in self._listeners if not getattr(lq, "poisoned", False)]
         for lq in snapshot:
-            with contextlib.suppress(queue.Full):
+            try:
                 lq.put_nowait(data)
+            except _ListenerOverflow:
+                log.warning(
+                    "sse.listener_overflow ws=%s event_id=%d: listener queue full; "
+                    "poisoned — its drain loop will close the stream and the "
+                    "client reconnect replays the gap from the ring buffer",
+                    self.ws_id[:8],
+                    event_id,
+                )
+            except queue.Full:
+                # Poison latched by a concurrent producer between our
+                # snapshot and this put (or a raw ``queue.Queue`` a test
+                # registered directly): same silent-skip as before.
+                continue
         return event_id
 
+    def _buffer_token_locked(self, kind: str, text: str) -> None:
+        """Accumulate one content/reasoning fragment; flush on window/size.
+
+        Caller holds ``_ws_lock``.  A kind switch (reasoning→content or
+        back) flushes the other kind first so the wire preserves arrival
+        order between the two token streams.  The window is measured
+        from the last flush and checked here, on arrival — no timer
+        thread, so a mid-stream stall just holds the final partial batch
+        until the next fragment or the next non-token emit's
+        choke-point flush (``stream_end`` at the latest).
+        """
+        if self._pending_kind and self._pending_kind != kind:
+            self._flush_token_batch_locked()
+        if not self._pending_tokens:
+            self._pending_kind = kind
+        self._pending_tokens.append(text)
+        self._pending_tokens_size += len(text)
+        if (
+            time.monotonic() - self._last_token_flush >= _TOKEN_BATCH_WINDOW_SECS
+            or self._pending_tokens_size >= _TOKEN_BATCH_MAX_CHARS
+        ):
+            self._flush_token_batch_locked()
+
+    def _flush_token_batch_locked(self) -> None:
+        """Emit the pending token batch as ONE event.  Caller holds ``_ws_lock``.
+
+        The inflight-buffer append and the enqueue are deliberately one
+        critical section: ``register_listener_with_in_progress_snapshot``
+        / ``register_listener_with_replay`` capture ``(inflight text,
+        _event_id)`` under the same lock, so ``snap_seq`` stays a true
+        high-water mark for the snapshot text.  Splitting them (e.g.
+        appending inflight per-token while enqueueing per-batch) lets a
+        straddling snapshot carry text whose batch then arrives with
+        ``_seq > snap_seq`` — the client (a blind ``+=``, no content
+        dedup) double-renders it.  Pinned by
+        ``test_snapshot_mid_batch_sees_only_flushed_text_no_double_render``
+        and the writer-race test in ``test_sse_reconnect_replay.py``.
+
+        Cap semantics match the old per-token appends: check-before-
+        append, so overshoot is bounded by one batch
+        (``_TOKEN_BATCH_MAX_CHARS`` + one fragment) instead of one
+        token; the live stream continues past the cap either way.
+        """
+        if not self._pending_tokens:
+            return
+        self._last_token_flush = time.monotonic()
+        text = "".join(self._pending_tokens)
+        kind = self._pending_kind
+        self._reset_pending_locked()
+        if kind == "content":
+            if self._ws_turn_content_size < _MAX_TURN_CONTENT_CHARS:
+                self._ws_turn_content.append(text)
+                self._ws_turn_content_size += len(text)
+            if self._ws_inflight_content_size < _MAX_TURN_CONTENT_CHARS:
+                self._ws_inflight_content.append(text)
+                self._ws_inflight_content_size += len(text)
+        else:
+            if self._ws_inflight_reasoning_size < _MAX_TURN_CONTENT_CHARS:
+                self._ws_inflight_reasoning.append(text)
+                self._ws_inflight_reasoning_size += len(text)
+        self._enqueue_direct({"type": kind, "text": text})
+
+    def _flush_token_batch(self) -> None:
+        """Flush the pending token batch from OUTSIDE ``_ws_lock``.
+
+        The lockless empty-check is the fast path for every non-token
+        emit (the overwhelmingly common case).  Same-thread visibility
+        is what correctness needs: the worker that buffered the tokens
+        sees its own append when it later emits ``stream_end`` /
+        ``tool_*`` — cross-thread emits racing a concurrent append keep
+        their pre-existing best-effort ordering either way.
+        """
+        if not self._pending_tokens:
+            return
+        with self._ws_lock:
+            self._flush_token_batch_locked()
+
+    def _reset_pending_locked(self) -> None:
+        """Zero the pending token accumulator.  Caller holds ``_ws_lock``.
+
+        Single source of truth for the reset so a later accumulator field
+        can't be half-cleared by one of its two callers
+        (:meth:`_flush_token_batch_locked` after capturing the text,
+        :meth:`_discard_pending_tokens_locked` on the crash path)."""
+        self._pending_tokens = []
+        self._pending_tokens_size = 0
+        self._pending_kind = ""
+
+    def _discard_pending_tokens_locked(self) -> None:
+        """Drop a never-emitted pending batch.  Caller holds ``_ws_lock``.
+
+        Only for the stale-crash path (:meth:`on_turn_start`): the text
+        was never enqueued, never ring-buffered, never inflight — so
+        discarding it is consistent everywhere, whereas flushing it
+        would paint a dead ``send()``'s tail into the NEW turn's bubble.
+        """
+        self._reset_pending_locked()
+
     def _stamp_agent_parent(self, data: dict[str, Any]) -> dict[str, Any]:
         """Stamp ``parent_call_id`` on a sub-agent's child event.
 
@@ -718,7 +994,7 @@ class SessionUIBase:
         self, maxsize: int = _DEFAULT_LISTENER_QUEUE_MAX
     ) -> queue.Queue[dict[str, Any]]:
         """Create a per-client queue and register it as a listener."""
-        client_queue: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=maxsize)
+        client_queue: queue.Queue[dict[str, Any]] = _ListenerQueue(maxsize=maxsize)
         with self._listeners_lock:
             self._listeners.append(client_queue)
         return client_queue
@@ -769,7 +1045,7 @@ class SessionUIBase:
         duration. The shallow ``list(...)`` copies under the lock mean
         subsequent appends to the live buffers don't mutate our view.
         """
-        client_queue: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=maxsize)
+        client_queue: queue.Queue[dict[str, Any]] = _ListenerQueue(maxsize=maxsize)
         with self._ws_lock:
             captured_content = list(self._ws_inflight_content)
             captured_reasoning = list(self._ws_inflight_reasoning)
@@ -862,7 +1138,7 @@ class SessionUIBase:
         for the genuine cold-start case (no false ``replay_truncated``
         envelopes on freshly-opened workstreams).
         """
-        client_queue: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=maxsize)
+        client_queue: queue.Queue[dict[str, Any]] = _ListenerQueue(maxsize=maxsize)
         # Lock order matches writer: ``_ws_lock`` outer, ``_listeners_lock``
         # inner.  Both inflight buffers AND the buffer slice AND the
         # ``_event_id`` counter AND the listener registration captured
@@ -2655,8 +2931,13 @@ class SessionUIBase:
         stale content in the buffers. Steady-state, the buffers are
         already empty at this point because :meth:`on_turn_committed`
         cleared them right after the last assistant message committed.
+
+        A pending token batch here is the same stale-crash residue and
+        is DISCARDED (never emitted) — flushing it would paint the dead
+        ``send()``'s tail into the new turn's bubble.
         """
         with self._ws_lock:
+            self._discard_pending_tokens_locked()
             self._reset_inflight_buffers_locked()
 
     def on_turn_committed(self) -> None:
@@ -2674,8 +2955,15 @@ class SessionUIBase:
         within the current send) will override this hook to copy
         inflight reasoning to a per-message persistence store BEFORE
         clearing — keeping the `current vs historical` boundary clean.
+
+        A pending token batch here is part of the message that just
+        committed (the worker's ``stream_end`` normally flushed it
+        already), so it FLUSHES — before the reset — keeping the live
+        view and the replay ring complete rather than silently dropping
+        committed text from connected panes.
         """
         with self._ws_lock:
+            self._flush_token_batch_locked()
             self._reset_inflight_buffers_locked()
 
     def on_thinking_start(self) -> None:
@@ -2690,86 +2978,52 @@ class SessionUIBase:
         self._enqueue({"type": "thinking_stop"})
 
     def on_reasoning_token(self, text: str) -> None:
-        """Append to the inflight reasoning buffer (capped) + enqueue.
+        """Buffer one reasoning fragment into the emit-time batcher.
 
-        Mirrors :meth:`on_content_token`'s shape.  The ``_seq`` dedup
-        tag is stamped by :meth:`_enqueue` against the per-ws
-        ``_event_id`` counter, which advances on EVERY emit
-        regardless of whether the inflight cap rejected the append.
-        If the seq stalled at high-water-pre-cap, subscribers
-        registering after the cap is hit would capture
-        ``snap_seq == high-water`` and every subsequent live token
-        (with the same stalled seq) would be filter-dropped as
-        "already in your snapshot" — silently losing the rest of
-        the stream. The cap is a buffer-size limit, NOT a "stop
-        streaming" signal.
-
-        Tokens past the cap are absent from ``snap.reasoning`` (the
-        snapshot text was truncated at cap) but the live stream
-        continues normally past them — refresh-after-cap renders the
-        snapshot text up to the cap and then live tokens past it,
-        with a visual gap equal to the past-cap chunk. No silent
-        drop of subsequent tokens.
-
-        **Lock coupling**: ``_enqueue`` is called WHILE still
-        holding ``_ws_lock`` so the inflight append AND the
-        ``_event_id`` advancement happen atomically against a
-        snapshot reader.  Without this coupling a reader could
-        capture the inflight (with the new text) and read
-        ``_event_id`` BEFORE the writer's ``_enqueue`` bumped it,
-        producing a ``snap_seq`` lower than the new event's
-        ``_event_id``.  The new event would then slip past the
-        ``_seq <= snap_seq`` live-drain dedup and double-render
-        the text the snapshot already contained.  Acquisition
-        order ``_ws_lock`` (outer) → ``_listeners_lock`` (inner via
-        ``_enqueue``) matches the snapshot helpers, so no deadlock.
+        Mirrors :meth:`on_content_token`'s shape — see there for the
+        locking rationale and :meth:`_flush_token_batch_locked` for
+        where the (capped) inflight append + single-event enqueue
+        happen.  The inflight cap is a buffer-size limit, NOT a "stop
+        streaming" signal: batches past the cap skip the snapshot
+        buffers but still emit, so the live stream continues (a
+        refresh-after-cap renders the capped snapshot then live tokens
+        past it).
         """
         with self._ws_lock:
-            if self._ws_inflight_reasoning_size < _MAX_TURN_CONTENT_CHARS:
-                self._ws_inflight_reasoning.append(text)
-                self._ws_inflight_reasoning_size += len(text)
-            self._enqueue({"type": "reasoning", "text": text})
+            self._buffer_token_locked("reasoning", text)
 
     def on_content_token(self, text: str) -> None:
-        """Append to both turn-content buffers (capped) + enqueue.
+        """Buffer one content fragment into the emit-time batcher.
+
+        Fragments accumulate under ``_ws_lock`` and flush as ONE
+        ``content`` event per batch window (see the ``_TOKEN_BATCH_*``
+        constants) — the event-rate reduction that keeps fast local
+        models (500+ tok/s) from overflowing listener queues.  The
+        flush — inside :meth:`_flush_token_batch_locked`, still under
+        the caller's ``_ws_lock`` — appends the batch to both capped
+        turn-content buffers:
 
-        Writes under ``_ws_lock`` to two independent buffers:
          - ``_ws_turn_content`` (multi-turn, drained at idle/error)
            — fuels the dashboard's IDLE-piggyback content payload.
          - ``_ws_inflight_content`` (per-turn, drained at
            :meth:`on_turn_start`) — fuels the SSE ``in_progress_snapshot``
            event a reconnecting client sees on mid-stream refresh.
 
-        Both caps are checked independently.  The ``_seq`` dedup tag
-        is stamped by :meth:`_enqueue` against the per-ws
-        ``_event_id`` counter, which advances on EVERY emit
-        regardless of cap state — see :meth:`on_reasoning_token` for
-        the full rationale, including why ``_enqueue`` runs while
-        still holding ``_ws_lock`` (the lock coupling that makes
-        ``snap_seq`` a true high-water mark for the snapshot text).
-
-        The cap-check + append + size-update + enqueue all run under
-        ``_ws_lock`` so a concurrent
-        :meth:`snapshot_and_consume_state_payload` IDLE/ERROR drain or
-        a concurrent :meth:`register_listener_with_in_progress_snapshot`
-        / :meth:`register_listener_with_replay` sees a consistent
-        ``(inflight_content, _event_id)`` pair.  In production this
-        is single-writer-per-ws (the worker thread) but the snapshot
-        reader runs from coord's adapter via ``mgr.set_state``;
-        without the lock the writer's append could land in an
-        orphaned list reference the snapshot just swapped out, AND
-        the inflight/counter pair could de-sync.  Lock hold is
-        microseconds (the fan-out's ``put_nowait`` calls are O(N
-        listeners) but each is a single non-blocking enqueue).
+        and enqueues the batched event in the same critical section,
+        so a concurrent :meth:`snapshot_and_consume_state_payload`
+        IDLE/ERROR drain or a concurrent
+        :meth:`register_listener_with_in_progress_snapshot` /
+        :meth:`register_listener_with_replay` sees a consistent
+        ``(inflight_content, _event_id)`` pair — never a pending
+        fragment without its event, never an event without its text.
+        In production this is single-writer-per-ws (the worker
+        thread) but the snapshot reader runs from coord's adapter via
+        ``mgr.set_state``.  Acquisition order ``_ws_lock`` (outer) →
+        ``_listeners_lock`` (inner, via ``_enqueue_direct``) matches
+        the snapshot helpers, so no deadlock.
         """
         with self._ws_lock:
-            if self._ws_turn_content_size < _MAX_TURN_CONTENT_CHARS:
-                self._ws_turn_content.append(text)
-                self._ws_turn_content_size += len(text)
-            if self._ws_inflight_content_size < _MAX_TURN_CONTENT_CHARS:
-                self._ws_inflight_content.append(text)
-                self._ws_inflight_content_size += len(text)
-            self._enqueue({"type": "content", "text": text})
+            self._buffer_token_locked("content", text)
 
     def on_stream_end(self) -> None:
         with self._ws_lock:
@@ -2785,6 +3039,7 @@ class SessionUIBase:
         output: str,
         *,
         is_error: bool = False,
+        preview: dict[str, Any] | None = None,
     ) -> None:
         """Track per-ws tool-call counts + clear activity + enqueue.
 
@@ -2792,6 +3047,10 @@ class SessionUIBase:
         ``WebUI`` calls :func:`_metrics.record_tool_call` on top of the
         shared writes); call ``super().on_tool_result(...)`` to keep
         the per-ws counters consistent.
+
+        ``preview`` is the preview-pane descriptor (``open_preview``) — it
+        rides the live event verbatim, mirrored by the ``/history``
+        projection's ``preview`` field so live and replay render identically.
         """
         with self._ws_lock:
             self._ws_tool_calls[name] = self._ws_tool_calls.get(name, 0) + 1
@@ -2807,6 +3066,8 @@ class SessionUIBase:
         }
         if is_error:
             event["is_error"] = True
+        if preview:
+            event["preview"] = preview
         self._enqueue(event)
 
     def on_tool_output_chunk(self, call_id: str, chunk: str) -> None:
@@ -3085,6 +3346,13 @@ class SessionUIBase:
         """
         captured_content: list[str] = []
         with self._ws_lock:
+            # Deliver any pending token batch first: this is the
+            # cancel/error chokepoint (see the idle-branch comment
+            # below), and the terminal-state payload must carry the
+            # full turn text — a batch stranded in the accumulator
+            # would otherwise vanish from the dashboard payload AND
+            # from connected panes.
+            self._flush_token_batch_locked()
             tokens = self._ws_prompt_tokens + self._ws_completion_tokens
             ctx = self._ws_context_ratio
             activity = self._ws_current_activity

turnstone/core/session_worker.py

@@ -18,11 +18,22 @@ with no consumer. The flag transitions atomically inside the same lock
 this module holds, so both coord and interactive callers inherit the
 fix.
 
-This module owns ONLY the dispatch decision and the
-``_worker_running`` lifecycle. Per-kind concerns — session resolution,
+This module owns ONLY the dispatch decision, the ``_worker_running``
+lifecycle, and the ownership-clear wake backstop
+(:func:`_retry_pending_wake`). Per-kind concerns — session resolution,
 attachment resolution, error surfacing, UI callbacks,
 ``GenerationCancelled`` handling — live in the caller's
 ``enqueue`` / ``run`` no-arg closures.
+
+The wake backstop exists because IDLE state fans out from INSIDE
+``run()`` (``set_state`` subscribers fire on the calling thread — the
+worker that did the transition).  Any wake the IDLE fan-out dispatches
+(``IdleNudgeWatcher``) therefore lands on the reuse path while this
+worker still owns the flag and no-ops; with IDLE emitted at the END of
+a send there is no later seam in this worker to drain the queue, so
+the nudge would strand until the next user message.  Re-running the
+wake gate at the exact moment ownership clears is the only spot that
+closes the window without ever racing a competing worker.
 """
 
 from __future__ import annotations
@@ -41,6 +52,41 @@ if TYPE_CHECKING:
 log = get_logger(__name__)
 
 
+def _retry_pending_wake(ws: Workstream) -> None:
+    """Deliver nudges that arrived while the exiting worker owned *ws*.
+
+    Runs in the worker's ``finally`` immediately after it cleared
+    ``_worker_running`` (owner only — abandoned threads skip it).  The
+    canonical strand it closes: the coordinator's ``idle_children``
+    nudge, enqueued by ``CoordinatorIdleObserver`` during the IDLE
+    fan-out at the end of the coord's send — the fan-out runs on the
+    worker thread, so ``IdleNudgeWatcher``'s wake dispatch hits the
+    reuse path and no-ops, and nothing else ever re-checks the queue.
+    The same window covers a watch ``wake_fn`` firing while a worker
+    is mid-exit.
+
+    The wake gate
+    (:func:`~turnstone.core.idle_nudge_watcher.wake_workstream_if_pending`)
+    owns every defensive check — session missing, bare stub without a
+    NudgeQueue (watch-style dispatchers drive sessions that aren't
+    installed on the workstream), closed, non-idle, nothing pending —
+    and its ``session_worker.send`` dispatch is the same atomic spawn
+    as any other: a successor worker claimed between our flag-clear
+    and the retry just downgrades the wake to a no-op enqueue again,
+    and THAT worker's own exit re-runs this backstop.  Convergence is
+    owned by the producers' gates (cooldown, hard caps, ``valid_until``
+    predicates): a wake worker whose drain empties the queue retries
+    once at its own exit, sees nothing pending, and stops.
+    """
+    # Local import: idle_nudge_watcher imports this module at top level.
+    from turnstone.core.idle_nudge_watcher import wake_workstream_if_pending
+
+    try:
+        wake_workstream_if_pending(ws, trigger="worker-exit")
+    except Exception:
+        log.warning("session_worker.wake_retry_failed ws=%s", ws.id[:8], exc_info=True)
+
+
 def send(
     ws: Workstream,
     *,
@@ -63,10 +109,11 @@ def send(
     Returns:
         ``True`` on successful enqueue (existing worker accepted) or
         thread spawn (no live worker).
-        ``False`` when ``enqueue`` raises ``queue.Full`` (queue at
-        capacity — caller surfaces 429) or any other exception
-        (logged). Falling through to spawn a second worker on a full
-        queue would corrupt ChatSession state.
+        ``False`` when the workstream is already closed (see below), or
+        when ``enqueue`` raises ``queue.Full`` (queue at capacity —
+        caller surfaces 429) or any other exception (logged). Falling
+        through to spawn a second worker on a full queue would corrupt
+        ChatSession state.
     """
     name = thread_name or f"session-worker-{ws.id[:8]}"
 
@@ -85,6 +132,7 @@ def send(
             # close style signals if the runtime ever delivers them).
             log.exception("session_worker.uncaught ws=%s", ws.id[:8])
         finally:
+            was_owner = False
             with ws._lock:
                 # Only clear the flag if THIS thread is still the current
                 # worker.  A force-cancel abandons the worker
@@ -96,8 +144,23 @@ def send(
                 # spawns a second concurrent worker on the same session.
                 if ws.worker_thread is threading.current_thread():
                     ws._worker_running = False
+                    was_owner = True
+            # Outside the lock (the retry's wake dispatch re-acquires it).
+            # Owner only: an abandoned thread retrying would race the
+            # successor's own exit backstop for no benefit.
+            if was_owner:
+                _retry_pending_wake(ws)
 
     with ws._lock:
+        if ws._closed:
+            # Authoritative closed-check: ``SessionManager.close`` sets
+            # ``_closed`` under this same lock, so unlike the wake gate's
+            # lockless peek this read cannot go stale.  Without it, a
+            # wake (or send) racing ``close()`` spawns a worker that runs
+            # a full unattended turn — inference, tool calls, storage
+            # writes — on a workstream whose ``ws_closed`` already fired.
+            log.info("session_worker.closed_refused ws=%s", ws.id[:8])
+            return False
         if ws._worker_running:
             try:
                 enqueue()

turnstone/core/settings_registry.py

@@ -194,6 +194,19 @@ def _build_registry() -> dict[str, SettingDef]:
             "Use with caution \u2014 the model will be able to run commands, write files, "
             "and take actions without human review.",
         ),
+        SettingDef(
+            "tools.allow_private_network",
+            "bool",
+            False,
+            "Allow web_fetch / open_preview to reach private-network addresses",
+            "tools",
+            help="When enabled, a fetch or preview whose URL points at a private or "
+            "internal address (a home-lab service, an internal dashboard, localhost) "
+            "can be approved instead of being refused outright — the approval prompt "
+            "marks it as a private-network request. A public site that redirects into "
+            "your private network is still refused either way: that address never "
+            "appeared in the approval prompt, so it is never fetched.",
+        ),
         SettingDef(
             "tools.search",
             "str",

turnstone/core/storage/_postgresql.py

@@ -513,7 +513,10 @@ class PostgreSQLBackend:
                 all_ids.update(ids)
         if not all_ids:
             return {}
-        blobs = self.get_attachments(list(all_ids))
+        # Preview-pane blobs (kind='preview', see core.preview.PREVIEW_BLOB_KIND)
+        # ride ref-lists only for GC + the serving gate; reconstruction skips
+        # them, so don't pull their multi-MB content off disk on every load.
+        blobs = self.get_attachments(list(all_ids), exclude_kinds=("preview",))
         rows_by_id = {str(b["attachment_id"]): b for b in blobs}
         return _build_attachments_by_msg(attachment_refs, rows_by_id)
 
@@ -1136,15 +1139,18 @@ class PostgreSQLBackend:
             )
             conn.commit()
 
-    def get_attachments(self, attachment_ids: list[str]) -> list[dict[str, Any]]:
+    def get_attachments(
+        self, attachment_ids: list[str], exclude_kinds: tuple[str, ...] = ()
+    ) -> list[dict[str, Any]]:
         if not attachment_ids:
             return []
         with self._conn() as conn:
-            rows = conn.execute(
-                sa.select(workstream_attachments).where(
-                    workstream_attachments.c.attachment_id.in_(attachment_ids)
-                )
-            ).fetchall()
+            stmt = sa.select(workstream_attachments).where(
+                workstream_attachments.c.attachment_id.in_(attachment_ids)
+            )
+            if exclude_kinds:
+                stmt = stmt.where(workstream_attachments.c.kind.notin_(exclude_kinds))
+            rows = conn.execute(stmt).fetchall()
             return [dict(r._mapping) for r in rows]
 
     def get_attachment(self, attachment_id: str) -> dict[str, Any] | None:
@@ -1794,6 +1800,8 @@ class PostgreSQLBackend:
         next_run: str,
         skill: str = "",
         notify_targets: str = "[]",
+        persona: str = "",
+        project_id: str = "",
     ) -> None:
         from sqlalchemy.dialects import postgresql
 
@@ -1814,6 +1822,8 @@ class PostgreSQLBackend:
                     auto_approve=1 if auto_approve else 0,
                     auto_approve_tools=",".join(auto_approve_tools),
                     skill=skill,
+                    persona=persona,
+                    project_id=project_id,
                     notify_targets=notify_targets,
                     enabled=1,
                     created_by=created_by,
@@ -1856,8 +1866,14 @@ class PostgreSQLBackend:
             "auto_approve",
             "auto_approve_tools",
             "skill",
+            "persona",
+            "project_id",
             "notify_targets",
             "enabled",
+            # created_by is only ever set by the update handler adopting an
+            # orphaned (pre-fix "") schedule's owner from auth_result — never
+            # sourced from the request body, so this is not a spoofing surface.
+            "created_by",
             "last_run",
             "next_run",
             "updated",

turnstone/core/storage/_protocol.py

@@ -347,10 +347,15 @@ class StorageBackend(Protocol):
         """
         ...
 
-    def get_attachments(self, attachment_ids: list[str]) -> list[dict[str, Any]]:
+    def get_attachments(
+        self, attachment_ids: list[str], exclude_kinds: tuple[str, ...] = ()
+    ) -> list[dict[str, Any]]:
         """Bulk fetch attachments by id, including their ``content`` bytes.
 
         Unknown ids are silently skipped.  Order is unspecified.
+        ``exclude_kinds`` filters at the QUERY so callers that will discard a
+        kind anyway (trajectory reconstruction skips ``preview`` blobs) don't
+        pull multi-megabyte content off disk just to drop it.
         """
         ...
 
@@ -1053,8 +1058,14 @@ class StorageBackend(Protocol):
         next_run: str,
         skill: str = "",
         notify_targets: str = "[]",
+        persona: str = "",
+        project_id: str = "",
     ) -> None:
-        """Create a scheduled task. No-op if task_id already exists."""
+        """Create a scheduled task. No-op if task_id already exists.
+
+        ``persona`` (slug) and ``project_id`` are stamped onto the workstream
+        each firing creates; empty = kind-default persona / no project.
+        """
         ...
 
     def get_scheduled_task(self, task_id: str) -> dict[str, Any] | None:

turnstone/core/storage/_schema.py

@@ -258,6 +258,14 @@ scheduled_tasks = sa.Table(
     sa.Column("auto_approve", sa.Integer, nullable=False, server_default="0"),
     sa.Column("auto_approve_tools", sa.Text, nullable=False, server_default=""),
     sa.Column("skill", sa.Text, nullable=False, server_default=""),
+    # persona/project_id: slug + project stamped onto the workstream each firing
+    # creates.  Empty = "kind default persona" / "no project", mirroring how an
+    # empty model/skill means "use the default".  Passed verbatim to
+    # create_workstream at dispatch, where the node resolves the persona and
+    # gates the project attach (scheduler.py::_dispatch_to_node).  Added in
+    # migration 066.
+    sa.Column("persona", sa.Text, nullable=False, server_default=""),
+    sa.Column("project_id", sa.Text, nullable=False, server_default=""),
     sa.Column("notify_targets", sa.Text, nullable=False, server_default="[]"),
     sa.Column("enabled", sa.Integer, nullable=False, server_default="1"),
     sa.Column("created_by", sa.Text, nullable=False, server_default=""),

turnstone/core/storage/_sqlite.py

@@ -576,7 +576,10 @@ class SQLiteBackend:
                 all_ids.update(ids)
         if not all_ids:
             return {}
-        blobs = self.get_attachments(list(all_ids))
+        # Preview-pane blobs (kind='preview', see core.preview.PREVIEW_BLOB_KIND)
+        # ride ref-lists only for GC + the serving gate; reconstruction skips
+        # them, so don't pull their multi-MB content off disk on every load.
+        blobs = self.get_attachments(list(all_ids), exclude_kinds=("preview",))
         rows_by_id = {str(b["attachment_id"]): b for b in blobs}
         return _build_attachments_by_msg(attachment_refs, rows_by_id)
 
@@ -1293,15 +1296,18 @@ class SQLiteBackend:
             )
             conn.commit()
 
-    def get_attachments(self, attachment_ids: list[str]) -> list[dict[str, Any]]:
+    def get_attachments(
+        self, attachment_ids: list[str], exclude_kinds: tuple[str, ...] = ()
+    ) -> list[dict[str, Any]]:
         if not attachment_ids:
             return []
         with self._conn() as conn:
-            rows = conn.execute(
-                sa.select(workstream_attachments).where(
-                    workstream_attachments.c.attachment_id.in_(attachment_ids)
-                )
-            ).fetchall()
+            stmt = sa.select(workstream_attachments).where(
+                workstream_attachments.c.attachment_id.in_(attachment_ids)
+            )
+            if exclude_kinds:
+                stmt = stmt.where(workstream_attachments.c.kind.notin_(exclude_kinds))
+            rows = conn.execute(stmt).fetchall()
             return [dict(r._mapping) for r in rows]
 
     def get_attachment(self, attachment_id: str) -> dict[str, Any] | None:
@@ -1939,6 +1945,8 @@ class SQLiteBackend:
         next_run: str,
         skill: str = "",
         notify_targets: str = "[]",
+        persona: str = "",
+        project_id: str = "",
     ) -> None:
 
         now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
@@ -1958,6 +1966,8 @@ class SQLiteBackend:
                     "auto_approve": 1 if auto_approve else 0,
                     "auto_approve_tools": ",".join(auto_approve_tools),
                     "skill": skill,
+                    "persona": persona,
+                    "project_id": project_id,
                     "notify_targets": notify_targets,
                     "enabled": 1,
                     "created_by": created_by,
@@ -1999,8 +2009,14 @@ class SQLiteBackend:
             "auto_approve",
             "auto_approve_tools",
             "skill",
+            "persona",
+            "project_id",
             "notify_targets",
             "enabled",
+            # created_by is only ever set by the update handler adopting an
+            # orphaned (pre-fix "") schedule's owner from auth_result — never
+            # sourced from the request body, so this is not a spoofing surface.
+            "created_by",
             "last_run",
             "next_run",
             "updated",

turnstone/core/storage/_utils.py

@@ -426,6 +426,12 @@ def _reconstruct_attachment_refs(
         # placeholder type ({type:pdf} / {type:audio}) consistent with the live
         # injection path, which already emits those.
         kind_str = str(att.get("kind") or "")
+        if kind_str == "preview":
+            # Preview-pane blobs ride the ref-list ONLY for refcount GC and
+            # the serving-route ownership gate — they are frontend content,
+            # addressed by the tool turn's meta descriptor, and must never
+            # become a content block a wire materialization could inline.
+            continue
         ref_kind = kind_str if kind_str in ("image", "pdf", "audio") else "document"
         refs.append(
             AttachmentRef(
@@ -1087,12 +1093,16 @@ def reconstruct_turns(
         raw_meta = _source_meta_from_json(row[10]) if len(row) > 10 else None
         if raw_meta is not None:
             # The ``meta`` column is role-exclusive: a TOOL row carries the
-            # typed ``{"effect_status": ...}`` envelope; a SYSTEM row carries
-            # operator-context ``source_meta``. Route so a tool's disposition
-            # doesn't land under source_meta (and vice versa). Legacy SYSTEM
-            # rows (bare source_meta dict, no effect_status key) fall through.
-            if role == "tool" and "effect_status" in raw_meta:
-                meta.extra["effect_status"] = raw_meta["effect_status"]
+            # typed ``{"effect_status": ..., "preview": ...}`` envelope (each
+            # key optional); a SYSTEM row carries operator-context
+            # ``source_meta``. Route so a tool's disposition doesn't land
+            # under source_meta (and vice versa). Legacy SYSTEM rows (bare
+            # source_meta dict, no tool keys) fall through.
+            if role == "tool" and ("effect_status" in raw_meta or "preview" in raw_meta):
+                if "effect_status" in raw_meta:
+                    meta.extra["effect_status"] = raw_meta["effect_status"]
+                if "preview" in raw_meta:
+                    meta.extra["preview"] = raw_meta["preview"]
             elif role == "user" and "sender" in raw_meta:
                 # Per-message sender identity (shared-workstream attribution).
                 # A USER row's meta blob carries only ``{"sender": ...}`` — route

turnstone/core/storage/migrations/versions/066_scheduled_task_persona_project.py

@@ -0,0 +1,43 @@
+"""Add persona + project settings to scheduled tasks.
+
+A scheduled task dispatches a fresh workstream every firing.  Until now it
+could pin the model and skill of that workstream but not its **persona** or
+**project** — the two levers a manually-created workstream already carries
+(``workstreams.persona`` from migration 063, ``workstreams.project_id`` from
+062).  These two columns close that gap so a schedule can run under, say, the
+``researcher`` persona attached to a specific project's memory bucket.
+
+Both are ``Text NOT NULL DEFAULT ''`` following the ``scheduled_tasks``
+convention (``model``/``skill`` use the same shape): empty = "kind default
+persona" / "no project", exactly as an empty model means "default model".  The
+values are stamped verbatim onto ``create_workstream`` at dispatch, where the
+node resolves the persona for the workstream kind and gates the project attach
+(``console/scheduler.py::_dispatch_to_node`` → ``/v1/api/workstreams/new``);
+nothing is resolved or enforced at migration time.  Existing rows migrate
+cleanly to the empty default — byte-identical dispatch behaviour to pre-066.
+Additive and reversible.
+
+Revision ID: 066
+Revises: 065
+Create Date: 2026-07-08
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "066"
+down_revision = "065"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("scheduled_tasks") as batch_op:
+        batch_op.add_column(sa.Column("persona", sa.Text, nullable=False, server_default=""))
+        batch_op.add_column(sa.Column("project_id", sa.Text, nullable=False, server_default=""))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("scheduled_tasks") as batch_op:
+        batch_op.drop_column("project_id")
+        batch_op.drop_column("persona")

turnstone/core/trajectory.py

@@ -305,6 +305,11 @@ def turn_from_dict(msg: dict[str, Any]) -> Turn:
     es = msg.get("_effect_status")
     if es:
         meta.extra["effect_status"] = es
+    # Preview-pane descriptor (``open_preview`` tool results) — frontend-facing
+    # only; never folded into wire content.
+    pv = msg.get("_preview")
+    if pv:
+        meta.extra["preview"] = pv
     # Per-message sender identity for shared workstreams (who actually sent this
     # user turn). Wire-invisible side channel — folded into the model-visible
     # content at :meth:`ChatSession._prepare_wire_messages` only when the
@@ -359,6 +364,9 @@ def turn_to_dict(turn: Turn) -> dict[str, Any]:
     es = turn.meta.extra.get("effect_status")
     if es:
         msg["_effect_status"] = es
+    pv = turn.meta.extra.get("preview")
+    if pv:
+        msg["_preview"] = pv
     sndr = turn.meta.extra.get("sender")
     if sndr:
         msg["_sender"] = sndr

turnstone/core/watch.py

@@ -13,6 +13,7 @@ import json
 import re
 import subprocess
 import threading
+import time
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
@@ -33,6 +34,49 @@ MIN_INTERVAL = 10  # seconds
 MAX_INTERVAL = 86_400  # 24 hours
 DEFAULT_MAX_POLLS = 100
 MAX_OUTPUT_SIZE = 65_536  # truncate stored/dispatched output at 64 KB
+# Cap on delivery re-attempts for a fire whose workstream can't be
+# reached (evicted + transiently unrestorable — all restore slots busy).
+# On exhaustion the held reminder is dropped and one poll is charged to
+# the watch's own ``max_polls`` budget: with budget left the watch stays
+# ACTIVE and the fire cycle repeats on its normal cadence; with the
+# budget spent it deactivates (loudly) — so a persistently unreachable
+# workstream can never re-run its command forever.  A PERMANENT failure
+# (:class:`WatchWorkstreamUnrestorable`, e.g. corrupt persona stamp)
+# deactivates immediately without waiting out either budget.
+MAX_DELIVERY_ATTEMPTS = 5
+# Cap on the held-reminder retry delay.  Re-delivery is a cheap in-memory
+# dispatch (never a command re-run), so it retries on a short cadence —
+# ``min(interval_secs, this)`` — rather than the watch's own interval: a
+# daily watch whose fire hit a busy restore slot must not sit on its
+# reminder for 24 h when the cause clears in seconds.
+DELIVERY_RETRY_CAP_SECS = 60
+# Cap on concurrent restore paths in flight across the poll pool.  Kept
+# below ``max_concurrent_polls`` so a burst of evicted-workstream fires
+# can never occupy every poll slot on slow restores (leaving normal polls
+# unserved) and can't drain the shared DB connection pool.  A poll that
+# would exceed the cap DEFERS (holds its reminder, releases its slot)
+# instead of blocking.
+MAX_CONCURRENT_RESTORES = 2
+# Age past which an in-flight restore's admission entry is presumed
+# wedged inside ``restore_fn`` and ALERTED on (error log at every
+# refused admission).  Ten minutes exceeds every configured storage /
+# MCP timeout by an order of magnitude, so a genuine restore never
+# trips it.  Deliberately detection-ONLY — the entry is never evicted:
+# the wedged poll thread's pool slot is never released, so reclaiming
+# its admission would just readmit a restore that can wedge ANOTHER
+# pool thread on the same cause, converting this capped degraded state
+# (restores blocked, normal polling intact) into total poll-pool
+# collapse, one slot per threshold period.  Recovery from a genuine
+# wedge is a process restart; the loud log is what tells the operator.
+RESTORE_STALL_ALERT_SECS = 600.0
+# Cap on ``stop()``'s in-flight-poll drain.  Shutdown runs under an
+# external deadline (systemd's stop timeout defaults to 90 s), and the
+# teardown steps AFTER the watch runner — state-writer drain, node
+# deregistration — must still get their turn, so the drain waits
+# ``min(tool_timeout, this) + 5`` rather than a full ``tool_timeout``
+# (default 120 s).  An abandoned poll is loud and safe: its row stays
+# due and re-polls on the next boot.
+STOP_DRAIN_CAP_SECS = 30.0
 
 # Safe builtins exposed to condition expressions.
 _SAFE_BUILTINS: dict[str, Any] = {
@@ -258,6 +302,11 @@ def build_watch_reminder(
     }
 
 
+def _iso_in(seconds: float) -> str:
+    """``now + seconds`` in the storage layer's naive-UTC second format."""
+    return (datetime.now(UTC) + timedelta(seconds=seconds)).strftime("%Y-%m-%dT%H:%M:%S")
+
+
 def format_interval(secs: float) -> str:
     """Human-readable duration (e.g. ``'5m'``, ``'1h30m'``)."""
     if secs < 60:
@@ -276,11 +325,41 @@ def format_interval(secs: float) -> str:
 # ---------------------------------------------------------------------------
 
 
+class WatchWorkstreamUnrestorable(Exception):  # noqa: N818
+    """Raised by a ``restore_fn`` when a watch's workstream can NEVER be
+    restored (e.g. a corrupt persona stamp the operator must fix), as
+    opposed to a transient failure (all restore slots busy) which returns
+    ``None``.  Signals :class:`WatchRunner` to stop retrying delivery and
+    deactivate the watch immediately rather than burning the whole
+    attempt budget on a cause that can't clear on its own.
+    """
+
+
 class WatchRunner:
     """Polls the database for due watches and dispatches results.
 
     Runs as a daemon thread in the server process, analogous to
     ``TaskScheduler`` in the console.
+
+    Poll execution is CONCURRENT and bounded: the tick thread only
+    enumerates due rows and hands each to a short-lived daemon thread
+    gated by a semaphore (``max_concurrent_polls``), so one hung
+    command — itself bounded by ``tool_timeout`` — delays at most one
+    slot instead of head-of-line blocking every watch on the node.  A
+    per-``watch_id`` in-flight set prevents double-polling rows that
+    keep appearing in ``list_due_watches`` while their (slow) poll is
+    still running.  When a fire can't reach its workstream, the built
+    reminder is HELD and re-delivered on a short retry cadence
+    (``min(interval_secs, DELIVERY_RETRY_CAP_SECS)``, never re-running
+    the command); transient failures retry up to
+    :data:`MAX_DELIVERY_ATTEMPTS`, after which one poll is charged to the
+    watch's ``max_polls`` budget and the fire cycle repeats on its normal
+    cadence — or, with the budget spent, the watch deactivates loudly.  A
+    permanent :class:`WatchWorkstreamUnrestorable` deactivates it at
+    once.  Restore is admission-controlled (per-ws_id
+    dedup + a :data:`MAX_CONCURRENT_RESTORES` cap, both without blocking a
+    poll slot) so two watches on one evicted workstream can't each spawn a
+    live session and a restore burst can't starve the poll pool.
     """
 
     def __init__(
@@ -290,6 +369,7 @@ class WatchRunner:
         *,
         check_interval: float = 15.0,
         tool_timeout: float = 30.0,
+        max_concurrent_polls: int = 4,
         restore_fn: Callable[[str], Callable[[dict[str, Any], str], None] | None] | None = None,
     ) -> None:
         self._storage = storage
@@ -297,10 +377,48 @@ class WatchRunner:
         self._check_interval = check_interval
         self._tool_timeout = tool_timeout
         self._restore_fn = restore_fn
+        # Bounded poll concurrency (see class docstring).  The slot is
+        # acquired on the tick thread and released in ``_poll_one``'s
+        # ``finally``; the in-flight set is keyed by watch_id and holds
+        # entries for exactly the lifetime of their poll thread.
+        self._poll_slots = threading.BoundedSemaphore(max_concurrent_polls)
+        self._in_flight: set[str] = set()
+        self._in_flight_lock = threading.Lock()
 
         self._dispatch_fns: dict[str, Callable[[dict[str, Any], str], None]] = {}
         self._dispatch_lock = threading.Lock()
 
+        # Restore admission control.  The restore path (``manager.create``
+        # + ``session.resume``) must not run twice for one ws_id, or two
+        # watches on the same evicted workstream — polled on separate pool
+        # threads — would each spawn a live auto-approved session racing
+        # writes into one conversation history.  ``_restoring`` tracks the
+        # ws_ids with a restore in flight; ``_restore_lock`` guards it but
+        # is held only for the fast admit/reject check, NEVER across the
+        # slow restore (which would pin the caller's poll slot and starve
+        # the pool).  A poll is admitted only when its ws_id isn't already
+        # restoring AND fewer than :data:`MAX_CONCURRENT_RESTORES` restores
+        # are in flight; otherwise it DEFERS (holds its reminder, releases
+        # its slot) and re-delivers on the capped retry cadence — by which
+        # point the winning restore has registered a dispatch fn.  Values
+        # are ``time.monotonic()`` admission stamps, used ONLY to alert on
+        # wedged restores (:data:`RESTORE_STALL_ALERT_SECS`); entries are
+        # removed solely by their own restore's ``finally``.
+        self._restoring: dict[str, float] = {}
+        self._restore_lock = threading.Lock()
+
+        # Held reminders whose delivery failed, keyed by watch_id.  Value:
+        # ``{"reminder", "update_fields", "attempts"}``.  Held deliveries
+        # are always TERMINAL fires (``fired ⟹ is_final``, and reminders
+        # are only built for final polls), so committing ``update_fields``
+        # always deactivates the row.  A later tick re-DELIVERS the
+        # reminder (never re-runs the command, so a transient stop_on
+        # match survives) up to :data:`MAX_DELIVERY_ATTEMPTS`.  Access is
+        # guarded, though the per-watch_id in-flight gate already
+        # serialises pollers for a given watch_id.
+        self._pending_delivery: dict[str, dict[str, Any]] = {}
+        self._pending_delivery_lock = threading.Lock()
+
         # Watch ids whose terminal reminder has already been dispatched
         # but whose row write has not yet been confirmed.  Populated
         # between ``_dispatch_result`` and ``update_watch`` in
@@ -330,6 +448,31 @@ class WatchRunner:
         if self._thread is not None:
             self._thread.join(timeout=self._check_interval + 5)
             self._thread = None
+        # Drain in-flight polls so their storage writes land before
+        # teardown.  A poll's command can block up to ``tool_timeout``, so
+        # bound the wait on THAT (not the tick cadence): a poll that
+        # started just before ``stop()`` may legitimately still be running
+        # its command, and a ``check_interval``-based deadline would
+        # abandon it mid-run and skip its commit.  The wait is capped at
+        # :data:`STOP_DRAIN_CAP_SECS` though — shutdown itself runs under
+        # an external deadline (systemd stop timeout), and the teardown
+        # steps queued after us must still run.  On the deadline we
+        # abandon loudly; the daemon threads die with the process and the
+        # abandoned rows stay due (re-polled on next boot).
+        deadline = time.monotonic() + min(self._tool_timeout, STOP_DRAIN_CAP_SECS) + 5
+        while time.monotonic() < deadline:
+            with self._in_flight_lock:
+                if not self._in_flight:
+                    break
+            time.sleep(0.05)
+        else:
+            with self._in_flight_lock:
+                leftover = len(self._in_flight)
+            # Only warn on a genuine abandonment — the last poll can drain
+            # in the same window the deadline is crossed, and a count=0
+            # warning would be a false alarm for log-based monitoring.
+            if leftover:
+                log.warning("watch_runner.stop_abandoned_polls count=%d", leftover)
         log.info("watch_runner.stopped")
 
     # -- Dispatch function registry ------------------------------------------
@@ -353,8 +496,21 @@ class WatchRunner:
         with self._dispatch_lock:
             self._dispatch_fns[ws_id] = fn
 
-    def remove_dispatch_fn(self, ws_id: str) -> None:
+    def remove_dispatch_fn(
+        self, ws_id: str, owner: Callable[[dict[str, Any], str], None] | None = None
+    ) -> None:
+        """Remove the registration for ``ws_id`` — with ``owner`` given,
+        ONLY if the registered fn IS that closure.  Multiple live
+        sessions can transiently serve one ws_id (a watch-restore shell
+        vs a reopened pane; an in-session ``/resume`` of an id open in
+        another pane), and a blind removal from one session's teardown
+        would silently unregister the OTHER, still-live session — its
+        next fire would then take the restore path and spawn a duplicate
+        auto-approved session onto the live conversation.
+        """
         with self._dispatch_lock:
+            if owner is not None and self._dispatch_fns.get(ws_id) is not owner:
+                return
             self._dispatch_fns.pop(ws_id, None)
 
     def get_dispatch_fn(self, ws_id: str) -> Callable[[dict[str, Any], str], None] | None:
@@ -367,8 +523,9 @@ class WatchRunner:
             return self._dispatch_fns.get(ws_id)
 
     def forget_terminal_dispatched(self, watch_id: str) -> None:
-        """Discard ``watch_id`` from the pending-terminal-dispatched
-        set if present.  Called by paths that take a watch out of
+        """Discard ``watch_id`` from the runner's per-watch transient
+        state (terminal-dispatched set AND any held pending delivery).
+        Called by paths that take a watch out of
         :meth:`StorageBackend.list_due_watches` view independent of
         the runner's own poll (most importantly the user-cancel path
         in :meth:`ChatSession._exec_watch`).  Without this, a
@@ -377,10 +534,21 @@ class WatchRunner:
         the user-cancel writes ``next_poll=''`` which excludes the
         row from ``list_due_watches``, so the retry-deactivate branch
         at the top of :meth:`_poll_watch` never fires to clear the
-        entry.
+        entry.  Held reminders are dropped for the same reason: a
+        cancelled watch's row leaves the due view, so its pending
+        re-delivery would never be retried and would leak.
+
+        Call this AFTER the row write that takes the watch out of the
+        active view: the delivery paths re-check ``is_watch_active``
+        before stashing or dispatching, so with the write already
+        visible a racing poll thread drops its own hold instead of
+        re-stashing behind this clear.  (The residual
+        check-before-write / stash-after-clear interleaving is mopped
+        up by :meth:`_sweep_cancelled_holds` within one tick.)
         """
         with self._terminal_dispatched_lock:
             self._terminal_dispatched.discard(watch_id)
+        self._clear_pending_delivery(watch_id)
 
     # -- Main loop -----------------------------------------------------------
 
@@ -399,6 +567,7 @@ class WatchRunner:
     def _tick(self) -> None:
         if self._storage is None:
             return
+        self._sweep_cancelled_holds()
         now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
         due = self._storage.list_due_watches(now)
         for watch_row in due:
@@ -408,13 +577,60 @@ class WatchRunner:
             row_node = watch_row.get("node_id", "")
             if row_node and row_node != self._node_id:
                 continue
+            watch_id = str(watch_row.get("watch_id", ""))
+            with self._in_flight_lock:
+                if watch_id in self._in_flight:
+                    # Still polling from a previous tick (slow command) —
+                    # the row keeps listing as due until its update
+                    # commits; don't double-poll it.
+                    continue
+                self._in_flight.add(watch_id)
+            if not self._poll_slots.acquire(blocking=False):
+                # Pool saturated: the remaining due rows stay due and the
+                # next tick retries them — nothing is dropped, delivery is
+                # just deferred by up to ``check_interval``.
+                with self._in_flight_lock:
+                    self._in_flight.discard(watch_id)
+                log.debug("watch_runner.poll_slots_saturated")
+                break
             try:
-                self._poll_watch(watch_row)
+                threading.Thread(
+                    target=self._poll_one,
+                    args=(watch_row,),
+                    daemon=True,
+                    name=f"watch-poll-{watch_id[:8]}",
+                ).start()
             except Exception:
-                log.exception(
-                    "watch_runner.poll_error",
-                    extra={"watch_id": watch_row.get("watch_id")},
-                )
+                # Spawn failure (e.g. OS thread exhaustion) must not leak
+                # the slot or the in-flight entry, and must NOT abort the
+                # rest of this tick — the failed watch stays due and
+                # retries next tick while its siblings still get polled
+                # (a raise here would unwind out of the un-guarded
+                # due-row loop and skip every remaining due watch).
+                with self._in_flight_lock:
+                    self._in_flight.discard(watch_id)
+                self._poll_slots.release()
+                log.exception("watch_runner.poll_spawn_failed", extra={"watch_id": watch_id})
+                continue
+
+    def _poll_one(self, watch_row: dict[str, Any]) -> None:
+        """Run one ``_poll_watch`` on a pool thread.
+
+        Always releases the slot and the in-flight entry, even on an
+        unexpected raise — a leaked slot would shrink the pool for the
+        rest of the process lifetime.
+        """
+        try:
+            self._poll_watch(watch_row)
+        except Exception:
+            log.exception(
+                "watch_runner.poll_error",
+                extra={"watch_id": watch_row.get("watch_id")},
+            )
+        finally:
+            with self._in_flight_lock:
+                self._in_flight.discard(str(watch_row.get("watch_id", "")))
+            self._poll_slots.release()
 
     def _poll_watch(self, watch_row: dict[str, Any]) -> None:
         watch_id = watch_row["watch_id"]
@@ -437,10 +653,36 @@ class WatchRunner:
                 self._storage.update_watch(watch_id, active=False, next_poll="")
                 with self._terminal_dispatched_lock:
                     self._terminal_dispatched.discard(watch_id)
+                # Belt-and-braces: no current path leaves an id in both
+                # ``_terminal_dispatched`` AND ``_pending_delivery``
+                # (``_redeliver_pending`` clears the hold BEFORE its
+                # commit), but this branch deactivates the row — after
+                # which it never re-lists — so any hold that ever DID
+                # coexist with the terminal mark would leak forever
+                # without this clear.  The mark means the reminder was
+                # delivered; a coexisting hold is by definition stale.
+                self._clear_pending_delivery(watch_id)
             except Exception:
                 log.exception("watch_runner.retry_deactivate_failed", extra={"watch_id": watch_id})
             return
 
+        # Held-reminder re-delivery: a prior poll fired but couldn't reach
+        # this watch's workstream.  Re-DELIVER the stashed reminder without
+        # re-running the command (so a stop_on match that was momentarily
+        # true isn't lost to a fresh run), bounded by MAX_DELIVERY_ATTEMPTS.
+        # The per-watch_id in-flight gate in _tick serialises POLLERS for
+        # this watch_id; the user-cancel path's forget_terminal_dispatched
+        # runs on a worker thread and CAN race this peek — which is why
+        # _redeliver_pending re-checks the row's active state before
+        # dispatching, the hold paths re-check before stashing, and
+        # _sweep_cancelled_holds mops up any stash that still lands after
+        # a cancel's clear.
+        with self._pending_delivery_lock:
+            pending = self._pending_delivery.get(watch_id)
+        if pending is not None:
+            self._redeliver_pending(watch_row, pending)
+            return
+
         # Safety check
         blocked = is_command_blocked(command)
         if blocked:
@@ -474,6 +716,23 @@ class WatchRunner:
         now = datetime.now(UTC)
         now_str = now.strftime("%Y-%m-%dT%H:%M:%S")
 
+        # Build the row update this poll intends to commit, UP FRONT, so a
+        # delivery failure can stash it verbatim alongside the reminder
+        # (see :meth:`_redeliver_pending`) instead of recomputing it at
+        # re-delivery time.
+        update_fields: dict[str, Any] = {
+            "poll_count": poll_count,
+            "last_output": output,
+            "last_exit_code": exit_code,
+            "last_poll": now_str,
+        }
+        if is_final:
+            update_fields["active"] = False
+            update_fields["next_poll"] = ""
+        else:
+            next_poll = now + timedelta(seconds=watch_row["interval_secs"])
+            update_fields["next_poll"] = next_poll.strftime("%Y-%m-%dT%H:%M:%S")
+
         # Dispatch before committing the row update.  Belt-and-braces
         # given the rest of the fix (closure no longer wires a
         # ``valid_until`` predicate, cancel-by-name uses
@@ -485,7 +744,12 @@ class WatchRunner:
         # ``_terminal_dispatched`` guard above it also bounds the
         # duplicate-fire blast radius if the row write fails after the
         # reminder shipped.
-        if fired or is_final:
+        #
+        # ``fired ⟹ is_final`` (see the assignment above), so reminders
+        # are built ONLY for terminal polls — the held-delivery machinery
+        # relies on that (a committed ``update_fields`` always
+        # deactivates).
+        if is_final:
             # Compute elapsed from created time
             elapsed_secs = 0.0
             if created:
@@ -506,34 +770,34 @@ class WatchRunner:
                 is_final=is_final,
                 reason=reason,
             )
-            self._dispatch_result(ws_id, reminder, watch_id)
-            if is_final:
-                # Mark BEFORE the row write so a raise below routes the
-                # next tick into the retry-deactivate branch instead of
-                # re-firing the reminder.
-                with self._terminal_dispatched_lock:
-                    self._terminal_dispatched.add(watch_id)
-
-        # Update DB
-        update_fields: dict[str, Any] = {
-            "poll_count": poll_count,
-            "last_output": output,
-            "last_exit_code": exit_code,
-            "last_poll": now_str,
-        }
-        if is_final:
-            update_fields["active"] = False
-            update_fields["next_poll"] = ""
+            try:
+                delivered = self._dispatch_result(ws_id, reminder, watch_id)
+            except WatchWorkstreamUnrestorable:
+                # Permanent: the workstream can never be restored (corrupt
+                # persona stamp / history gone).  Stash BEFORE the abandon
+                # write — not for delivery (there is nowhere to deliver),
+                # but so a failing deactivation write routes the next tick
+                # into the redeliver path (which retries the WRITE) instead
+                # of the still-active row re-listing into a fresh command
+                # run every tick with the budget never advancing.  On a
+                # successful write, _abandon_delivery clears the stash
+                # immediately (write-then-clear).
+                self._stash_pending_delivery(watch_id, reminder, update_fields, attempts=1)
+                self._abandon_delivery(watch_id, ws_id, update_fields, reason="unrestorable")
+                return
+            if not delivered:
+                # Transiently undeliverable (ws evicted + slots busy, or
+                # restore admission deferred).  HOLD the built reminder +
+                # its intended row update for re-delivery on the capped
+                # retry cadence, advancing next_poll and durably charging
+                # this fire's poll — no baseline advance and no command
+                # re-run (which would lose a transient stop_on match);
+                # see :meth:`_hold_delivery` for why the charge commits.
+                self._hold_delivery(watch_row, reminder, update_fields, attempts=1)
+                return
+            self._commit_terminal_update(watch_id, update_fields)
         else:
-            next_poll = now + timedelta(seconds=watch_row["interval_secs"])
-            update_fields["next_poll"] = next_poll.strftime("%Y-%m-%dT%H:%M:%S")
-        self._storage.update_watch(watch_id, **update_fields)
-
-        if is_final:
-            # Row write committed; the retry-deactivate branch will
-            # never be reached for this watch_id.
-            with self._terminal_dispatched_lock:
-                self._terminal_dispatched.discard(watch_id)
+            self._storage.update_watch(watch_id, **update_fields)
 
         log.debug(
             "watch_runner.polled",
@@ -568,38 +832,395 @@ class WatchRunner:
         except Exception as exc:
             return f"[command failed: {exc}]", -1
 
-    def _dispatch_result(self, ws_id: str, reminder: dict[str, Any], watch_id: str) -> None:
+    def _try_dispatch_fn(self, ws_id: str, reminder: dict[str, Any], watch_id: str) -> bool | None:
+        """Deliver via the registered dispatch fn, if one exists.
+
+        Returns ``True`` (delivered), ``False`` (a fn is registered but it
+        raised — the ws is live, so the caller must NOT restore, which
+        would spawn a duplicate session), or ``None`` (no fn registered —
+        the ws may be evicted and the caller should try to restore).
+        """
+        with self._dispatch_lock:
+            fn = self._dispatch_fns.get(ws_id)
+        if fn is None:
+            return None
+        try:
+            fn(reminder, watch_id)
+            return True
+        except Exception:
+            log.exception("watch_runner.dispatch_error", extra={"ws_id": ws_id})
+            return False
+
+    def _dispatch_result(self, ws_id: str, reminder: dict[str, Any], watch_id: str) -> bool:
         """Deliver a watch result to the owning workstream.
 
         ``reminder`` is the structured dict produced by
         :func:`build_watch_reminder` — ``text`` is the formatted body
         (matched by the dispatch closure's :func:`sanitize_payload`
         pass) and the optional fields ride as queue-entry metadata.
+
+        Returns ``True`` iff a dispatch closure ran without raising — the
+        registered one, or the one the restore path produced.  ``False``
+        means the reminder was not delivered for a TRANSIENT reason (no fn
+        + slots busy, restore admission deferred, or a live fn raised); the
+        caller HOLDS the reminder and re-delivers on the capped retry
+        cadence.  Raises
+        :class:`WatchWorkstreamUnrestorable` for a PERMANENT failure so the
+        caller can deactivate the watch instead of retrying.
         """
-        with self._dispatch_lock:
-            fn = self._dispatch_fns.get(ws_id)
+        delivered = self._try_dispatch_fn(ws_id, reminder, watch_id)
+        if delivered is not None:
+            return delivered
 
-        if fn is not None:
-            try:
-                fn(reminder, watch_id)
-                return
-            except Exception:
-                log.exception("watch_runner.dispatch_error", extra={"ws_id": ws_id})
+        # No dispatch fn — the workstream may be evicted.  Admit a restore
+        # only when this ws isn't already restoring and the concurrent-
+        # restore cap has room; hold ``_restore_lock`` for that fast check
+        # ONLY (never across the slow restore, which would pin this poll
+        # slot).  A rejected poll defers (holds + re-delivers on the
+        # capped retry cadence).
+        if self._restore_fn is None:
+            log.warning(
+                "watch_runner.dispatch_failed",
+                extra={"ws_id": ws_id, "reason": "no dispatch fn and no restore_fn"},
+            )
+            return False
 
-        # Workstream may be evicted — try to restore
-        if self._restore_fn is not None:
+        deliver_after_admission = False
+        with self._restore_lock:
+            # Re-check: a restore that completed while we waited for the
+            # lock may already have registered a fn for this ws_id.  This
+            # is a PRESENCE check only — the dispatch closure itself can
+            # block (it takes ``ws._lock`` and may spawn a wake thread),
+            # and running it here would serialise every restore admission
+            # on the node behind one delivery.  (Lock order: _restore_lock
+            # → _dispatch_lock via get_dispatch_fn; nothing takes them in
+            # the reverse order.)
+            if self.get_dispatch_fn(ws_id) is not None:
+                deliver_after_admission = True
+            else:
+                # Alert on admission entries past the stall threshold —
+                # a restore wedged inside ``restore_fn`` (its poll thread
+                # is blocked, so the release in the ``finally`` below can
+                # never run) holds this capacity for the process
+                # lifetime.  Detection ONLY: see
+                # :data:`RESTORE_STALL_ALERT_SECS` for why reclaiming the
+                # entry would make the failure strictly worse.
+                now = time.monotonic()
+                for rid, started in self._restoring.items():
+                    if now - started > RESTORE_STALL_ALERT_SECS:
+                        log.error(
+                            "watch_runner.restore_admission_wedged",
+                            extra={"ws_id": rid, "stalled_secs": round(now - started, 1)},
+                        )
+                if ws_id in self._restoring or len(self._restoring) >= MAX_CONCURRENT_RESTORES:
+                    # Same-ws restore already running, or the pool is at
+                    # its restore cap — defer rather than block a poll
+                    # slot.
+                    return False
+                self._restoring[ws_id] = now
+        if deliver_after_admission:
+            # The fn appeared while we waited: deliver OUTSIDE the lock.
+            # ``None`` (it vanished again — an eviction race) defers like
+            # any other transient.
+            return bool(self._try_dispatch_fn(ws_id, reminder, watch_id))
+
+        try:
+            restored_fn = self._restore_fn(ws_id)  # may raise WatchWorkstreamUnrestorable
+        except WatchWorkstreamUnrestorable:
+            raise  # permanent — caller deactivates the watch
+        except Exception:
+            log.exception("watch_runner.restore_error", extra={"ws_id": ws_id})
+            return False
+        finally:
+            with self._restore_lock:
+                self._restoring.pop(ws_id, None)
+
+        if restored_fn is not None:
             try:
-                restored_fn = self._restore_fn(ws_id)
-                if restored_fn is not None:
-                    restored_fn(reminder, watch_id)
-                    return
+                restored_fn(reminder, watch_id)
+                return True
             except Exception:
-                log.exception("watch_runner.restore_error", extra={"ws_id": ws_id})
+                log.exception("watch_runner.restore_dispatch_error", extra={"ws_id": ws_id})
+                return False
 
         log.warning(
             "watch_runner.dispatch_failed",
-            extra={"ws_id": ws_id, "reason": "no dispatch function and restore failed"},
+            extra={"ws_id": ws_id, "reason": "restore produced no dispatch fn"},
         )
+        return False
+
+    # -- Held-reminder re-delivery -------------------------------------------
+    #
+    # Everything held here is a TERMINAL fire (``fired ⟹ is_final`` in
+    # ``_poll_watch``, and reminders are built only for final polls), so a
+    # committed ``update_fields`` always deactivates the row.  The delivery
+    # outcome state machine — commit-with-terminal-mark, abandon, hold —
+    # lives in the three helpers below so ``_poll_watch`` (fresh fire) and
+    # ``_redeliver_pending`` can't drift apart on the fragile ordering.
+
+    def _watch_still_active(self, watch_id: str) -> bool:
+        """``True`` unless the row has CLEANLY left the active view (user
+        cancel / deletion).  A storage error biases toward ``True``:
+        delivery paths keep retrying on a blip — bounded by their own
+        attempt and poll budgets — rather than dropping a fire.
+        """
+        try:
+            return bool(self._storage.is_watch_active(watch_id))
+        except Exception:
+            return True
+
+    def _stash_pending_delivery(
+        self,
+        watch_id: str,
+        reminder: dict[str, Any],
+        update_fields: dict[str, Any],
+        *,
+        attempts: int,
+    ) -> None:
+        """Hold ``reminder`` + its intended row update for re-delivery."""
+        with self._pending_delivery_lock:
+            self._pending_delivery[watch_id] = {
+                "reminder": reminder,
+                "update_fields": update_fields,
+                "attempts": attempts,
+            }
+
+    def _clear_pending_delivery(self, watch_id: str) -> None:
+        with self._pending_delivery_lock:
+            self._pending_delivery.pop(watch_id, None)
+
+    def _commit_terminal_update(self, watch_id: str, update_fields: dict[str, Any]) -> None:
+        """Commit a DELIVERED terminal fire's row update with the
+        ``_terminal_dispatched`` mark held across the write: if the write
+        raises, the next tick routes into the retry-deactivate branch at
+        the top of :meth:`_poll_watch` instead of re-firing a reminder the
+        model already saw.
+        """
+        with self._terminal_dispatched_lock:
+            self._terminal_dispatched.add(watch_id)
+        self._storage.update_watch(watch_id, **update_fields)
+        # Row write committed; the retry-deactivate branch will never be
+        # reached for this watch_id.
+        with self._terminal_dispatched_lock:
+            self._terminal_dispatched.discard(watch_id)
+
+    def _abandon_delivery(
+        self,
+        watch_id: str,
+        ws_id: str,
+        update_fields: dict[str, Any],
+        *,
+        reason: str,
+        attempts: int | None = None,
+    ) -> None:
+        """Give up on delivering this fire: commit the intended row
+        update (deactivating the terminal watch), then drop any held
+        reminder.  Write-then-clear: a failed commit leaves the hold in
+        place, so the next tick retries via the REDELIVER path (dispatch
+        → same terminal outcome → retry this write) without re-running
+        the command — clearing first would let the row re-list into a
+        fresh command run every attempt-budget cycle, forever, whenever
+        storage can read but not write (e.g. disk-full SQLite), with the
+        poll budget never advancing.  The clear itself is pure in-memory
+        and cannot fail after a successful commit, so no ordering leaks
+        the hold.
+        """
+        self._storage.update_watch(watch_id, **update_fields)
+        self._clear_pending_delivery(watch_id)
+        extra: dict[str, Any] = {"watch_id": watch_id, "ws_id": ws_id, "reason": reason}
+        if attempts is not None:
+            extra["attempts"] = attempts
+        log.error("watch_runner.delivery_abandoned", extra=extra)
+
+    def _hold_delivery(
+        self,
+        watch_row: dict[str, Any],
+        reminder: dict[str, Any],
+        update_fields: dict[str, Any],
+        *,
+        attempts: int,
+    ) -> None:
+        """Stash the reminder + intended update and advance ``next_poll``
+        (by the capped retry delay) so the row re-lists for re-delivery
+        soon — without advancing its baseline or running its command.
+        Re-delivery is a cheap in-memory dispatch, so it retries on
+        ``min(interval_secs, DELIVERY_RETRY_CAP_SECS)`` rather than the
+        watch's own interval: a daily watch must not sit on its fired
+        reminder for 24 h because a restore slot was briefly busy.
+
+        The poll charge (``update_fields["poll_count"]``) is committed
+        alongside ``next_poll``: the hold itself lives only in this
+        process, so a restart mid-hold re-lists the row and re-runs the
+        (possibly side-effectful) command — with the charge durable those
+        re-runs stay bounded by the watch's own ``max_polls``, matching
+        the in-memory exhaustion path, plus at most ONE regeneration run
+        per restart when the held fire had already spent the budget (the
+        re-list runs the command before the cap check so the lost
+        reminder is regenerated rather than silently dropped).  The
+        baseline (``last_output``) stays uncommitted so a delta-style
+        ``stop_on`` re-detects the change the model never saw.
+
+        Dropped instead when the row has left the active view: the user
+        cancelled while this fire was in flight, and a stash landing
+        after the cancel path's :meth:`forget_terminal_dispatched` would
+        leak the hold forever (an inactive row never re-lists to retry
+        it) and violate that method's drop guarantee.
+        """
+        watch_id = watch_row["watch_id"]
+        ws_id = watch_row["ws_id"]
+        if not self._watch_still_active(watch_id):
+            self._clear_pending_delivery(watch_id)
+            log.info(
+                "watch_runner.hold_dropped_cancelled",
+                extra={"watch_id": watch_id, "ws_id": ws_id, "attempts": attempts},
+            )
+            return
+        retry_secs = min(int(watch_row["interval_secs"]), DELIVERY_RETRY_CAP_SECS)
+        self._stash_pending_delivery(watch_id, reminder, update_fields, attempts=attempts)
+        retry_poll = _iso_in(retry_secs)
+        self._storage.update_watch(
+            watch_id,
+            next_poll=retry_poll,
+            poll_count=int(update_fields["poll_count"]),
+        )
+        log.warning(
+            "watch_runner.delivery_deferred",
+            extra={
+                "watch_id": watch_id,
+                "ws_id": ws_id,
+                "attempts": attempts,
+                "next_retry": retry_poll,
+            },
+        )
+
+    def _redeliver_pending(self, watch_row: dict[str, Any], pending: dict[str, Any]) -> None:
+        """Re-attempt delivery of a held reminder WITHOUT re-running the
+        command.
+
+        Five outcomes:
+
+        * **Watch cancelled** — the user-cancel path raced the due
+          listing.  Drop the hold and deliver nothing: cancel's
+          :meth:`forget_terminal_dispatched` promises the held reminder
+          is dropped, and delivering here could even RESTORE a session
+          for a watch the user just cancelled.
+        * **Delivered** — commit the row update stashed at fire time (which
+          deactivates the terminal watch) and clear the hold.  The hold is
+          cleared BEFORE the commit so that a commit failure can't strand
+          it (the row then re-lists and the ``already_dispatched`` guard
+          finishes deactivation).
+        * **Permanent failure** (:class:`WatchWorkstreamUnrestorable`) —
+          deactivate the watch now and drop the reminder; it can never be
+          delivered.
+        * **Transient failure past** :data:`MAX_DELIVERY_ATTEMPTS`, poll
+          budget remaining — drop the held reminder, charge ONE poll to the
+          watch's ``max_polls`` budget, and leave it ACTIVE on its normal
+          cadence: a temporary cause (restore slots saturated under load)
+          doesn't silently turn the watch off, it re-fires and re-attempts
+          delivery next interval.  The baseline (``last_output``) is
+          deliberately NOT committed, so a delta-style ``stop_on`` re-fires
+          on the same change the model never saw.
+        * **Transient exhaustion with the poll budget spent** — commit the
+          held update (deactivates).  Without this bound a persistently
+          unreachable workstream would re-run its command every interval
+          forever, past the user's own ``max_polls``.
+        """
+        watch_id = watch_row["watch_id"]
+        ws_id = watch_row["ws_id"]
+        reminder = pending["reminder"]
+        update_fields = pending["update_fields"]
+
+        if not self._watch_still_active(watch_id):
+            self._clear_pending_delivery(watch_id)
+            log.info(
+                "watch_runner.redelivery_dropped_cancelled",
+                extra={"watch_id": watch_id, "ws_id": ws_id},
+            )
+            return
+
+        try:
+            delivered = self._dispatch_result(ws_id, reminder, watch_id)
+        except WatchWorkstreamUnrestorable:
+            self._abandon_delivery(watch_id, ws_id, update_fields, reason="unrestorable")
+            return
+
+        if delivered:
+            # Clear the hold FIRST: if the commit below raises, the row
+            # re-lists and the ``already_dispatched`` branch deactivates it
+            # — with the hold already gone there's nothing to leak.
+            self._clear_pending_delivery(watch_id)
+            self._commit_terminal_update(watch_id, update_fields)
+            log.info(
+                "watch_runner.delivery_recovered",
+                extra={"watch_id": watch_id, "ws_id": ws_id},
+            )
+            return
+
+        attempts = int(pending["attempts"]) + 1
+        if attempts >= MAX_DELIVERY_ATTEMPTS:
+            poll_count = int(update_fields.get("poll_count", 0))
+            max_polls = int(watch_row.get("max_polls", DEFAULT_MAX_POLLS))
+            if poll_count >= max_polls:
+                # Poll budget spent — deactivate rather than re-run the
+                # command forever against an unreachable workstream.
+                self._abandon_delivery(
+                    watch_id,
+                    ws_id,
+                    update_fields,
+                    reason="poll_budget_exhausted",
+                    attempts=attempts,
+                )
+                return
+            # Budget remains: charge this cycle's poll, then drop the hold
+            # and let the watch re-fire on its own cadence.  next_poll uses
+            # the FULL interval (a fresh command cycle, not a cheap
+            # re-delivery) and the baseline stays uncommitted so the fire
+            # re-detects.  Write-then-clear, mirroring _abandon_delivery: a
+            # failed charge commit keeps the hold, so the next tick retries
+            # THIS branch instead of the row re-listing into a fresh
+            # command run with the budget never advancing.
+            self._storage.update_watch(
+                watch_id,
+                poll_count=poll_count,
+                next_poll=_iso_in(int(watch_row["interval_secs"])),
+            )
+            self._clear_pending_delivery(watch_id)
+            log.warning(
+                "watch_runner.delivery_abandoned",
+                extra={
+                    "watch_id": watch_id,
+                    "ws_id": ws_id,
+                    "attempts": attempts,
+                    "reason": "transient_exhausted",
+                    "watch_active": True,
+                    "poll_count": poll_count,
+                    "max_polls": max_polls,
+                },
+            )
+            return
+
+        self._hold_delivery(watch_row, reminder, update_fields, attempts=attempts)
+
+    def _sweep_cancelled_holds(self) -> None:
+        """Drop held deliveries whose rows have left the active view.
+
+        The cancel paths call :meth:`forget_terminal_dispatched`, but a
+        poll thread that already passed its own active re-check can
+        re-stash a hold microseconds AFTER that clear — no ordering
+        between the cancel's row write and the in-memory stash can
+        prevent it without a per-watch lock spanning storage I/O.  An
+        inactive row never re-lists, so nothing else would ever retry or
+        drop such an entry; this tick-time sweep bounds the leak (and
+        any post-cancel redelivery) to one ``check_interval``.  Iterates
+        only currently-held ids — holds are rare and short-lived — so
+        the steady-state per-tick cost is zero storage reads.
+        """
+        with self._pending_delivery_lock:
+            held_ids = list(self._pending_delivery)
+        for watch_id in held_ids:
+            if not self._watch_still_active(watch_id):
+                self._clear_pending_delivery(watch_id)
+                log.info("watch_runner.hold_swept_cancelled", extra={"watch_id": watch_id})
 
     def _deactivate_watch(self, watch_id: str) -> None:
         self._storage.update_watch(watch_id, active=False, next_poll="")

turnstone/core/web.py

@@ -1,4 +1,4 @@
-"""Web utilities — HTML stripping and SSRF protection."""
+"""Web utilities — HTML stripping, SSRF protection, and the guarded fetch."""
 
 import ipaddress
 import re
@@ -6,6 +6,8 @@ import socket
 from html import unescape as _html_unescape
 from urllib.parse import urlparse
 
+import httpx
+
 _RE_INVISIBLE = re.compile(
     r"<(script|style|template|noscript)\b[^>]*>.*?</\1\s*>",
     re.DOTALL | re.IGNORECASE,
@@ -120,3 +122,91 @@ def check_ssrf(url: str) -> str | None:
     except (socket.gaierror, OSError):
         pass  # DNS failure — let the actual fetch handle it
     return None
+
+
+FETCH_BYTE_CEILING = 32 * 1024 * 1024
+"""Anti-OOM backstop on a guarded fetch's decoded body (see fetch_with_ssrf_guard)."""
+
+_REDIRECT_STATUSES = (301, 302, 303, 307, 308)
+_STALE_FRAMING_HEADERS = frozenset({"content-encoding", "content-length", "transfer-encoding"})
+
+
+def fetch_with_ssrf_guard(
+    url: str,
+    *,
+    timeout: float,
+    user_agent: str = "turnstone/1.0",
+    max_redirects: int = 5,
+    allow_private_origin: bool = False,
+    max_bytes: int = FETCH_BYTE_CEILING,
+) -> httpx.Response:
+    """GET *url* following redirects manually, SSRF-screening EVERY hop.
+
+    ``httpx.get(follow_redirects=True)`` checks nothing between hops — a
+    public URL that 302s into private address space (cloud metadata, an
+    internal admin endpoint) would be fetched before any post-hoc check runs,
+    executing the private-network request even if the response is later
+    discarded.  Here each hop's URL is screened BEFORE its request is issued.
+
+    ``allow_private_origin`` is the ``[tools] allow_private_network`` lane:
+    the CALLER sets it only when the operator opted in AND the ORIGINAL
+    target itself named a private address — the approval gate then saw and
+    approved that private URL, so its redirect chain is the operator's own
+    network and hop screening is skipped.  A public origin never sets it,
+    so a public site bouncing the fetcher into private space stays blocked
+    regardless of the opt-in: that hop was never shown to the approval gate.
+
+    The body is streamed under a *max_bytes* budget rather than buffered
+    blind — ``client.get()`` would read an unbounded body into memory before
+    any caller-side size cap could run.  The budget counts DECODED bytes
+    (``iter_bytes`` runs after content-decoding), so a small gzip body cannot
+    expand past it, and redirect-hop bodies are never read at all.  Callers
+    keep their own tighter product caps; this ceiling only bounds a hostile
+    or runaway response.  The realized response drops the wire-framing
+    headers (content-encoding / content-length / transfer-encoding) that no
+    longer describe the decoded content it carries.
+
+    Raises ``ValueError`` for a blocked hop, an over-budget body, or a
+    redirect chain past *max_redirects* (callers already route
+    ``ValueError`` to their fetch-failed lane), and lets ``httpx``
+    transport errors propagate unchanged.  ``resp.raise_for_status()``
+    stays the caller's call.
+    """
+    current = url
+    with httpx.Client(
+        headers={"User-Agent": user_agent},
+        timeout=timeout,
+        follow_redirects=False,
+    ) as client:
+        for _hop in range(max_redirects + 1):
+            if not allow_private_origin:
+                ssrf_err = check_ssrf(current)
+                if ssrf_err:
+                    raise ValueError(ssrf_err)
+            with client.stream("GET", current) as resp:
+                if resp.status_code in _REDIRECT_STATUSES:
+                    location = resp.headers.get("location")
+                    if location:
+                        current = str(httpx.URL(current).join(location))
+                        continue  # leaves the with-block: hop body never read
+                chunks: list[bytes] = []
+                total = 0
+                for chunk in resp.iter_bytes():
+                    total += len(chunk)
+                    if total > max_bytes:
+                        raise ValueError(
+                            f"Blocked: response body exceeded the {max_bytes:,}-byte fetch limit"
+                        )
+                    chunks.append(chunk)
+                headers = [
+                    (k, v)
+                    for k, v in resp.headers.items()
+                    if k.lower() not in _STALE_FRAMING_HEADERS
+                ]
+                return httpx.Response(
+                    status_code=resp.status_code,
+                    headers=headers,
+                    content=b"".join(chunks),
+                    request=httpx.Request("GET", current),
+                )
+    raise ValueError(f"Blocked: more than {max_redirects} redirects")

turnstone/core/web_helpers.py

@@ -14,6 +14,38 @@ if TYPE_CHECKING:
     from starlette.responses import JSONResponse
 
 
+def latin1_safe_filename(name: str, *, fallback: str = "attachment") -> str:
+    """A ``Content-Disposition`` ``filename`` value that is safe on the wire.
+
+    The value is emitted as ``filename="<this>"``, and three independent
+    hazards bite filenames derived from user uploads or fetched-page titles:
+
+    * Starlette encodes header values as latin-1 and raises on anything
+      outside it, so a CJK / em-dash name would 500 the serving route.
+    * The HTTP server layer rejects control characters in a header value even
+      when they are latin-1 encodable (h11 rejects NUL / CR / LF / FF / VT;
+      httptools is stricter still), so a stray control byte 500s there.
+    * ``"`` and ``\\`` are the quoted-string metacharacters — ``\\`` is the
+      RFC 6266 quoted-pair escape — so either would break out of or corrupt
+      the value (a trailing ``\\`` escapes the closing quote).
+
+    Drop every non-printable character (covers CR / LF / TAB / NUL / DEL, the
+    C0 / C1 control ranges, and zero-width / bidi format chars) and both
+    quoted-string metacharacters, then fold any surviving non-ASCII codepoint
+    to ``?``.  The result is pure printable ASCII with no ``"`` or ``\\`` —
+    latin-1 clean, control-free, and safely quotable.  ``fallback`` is run
+    through the same cleaning (so a caller can't reintroduce the crash via an
+    unsafe fallback), backed by a safe constant if even that is empty — the
+    return is always wire-safe and never ``filename=""``.
+    """
+
+    def _clean(s: str) -> str:
+        kept = "".join(c for c in s if c.isprintable() and c not in '"\\')
+        return kept.encode("ascii", errors="replace").decode("ascii")
+
+    return _clean(name) or _clean(fallback) or "download"
+
+
 def skill_summary_rows(storage: Any) -> list[dict[str, Any]]:
     """Build the public picker payload for ``/v1/api/skills``.
 

turnstone/eval/core.py

@@ -112,6 +112,7 @@ class NullUI:
         output: str,
         *,
         is_error: bool = False,
+        preview: dict[str, Any] | None = None,
     ) -> None:
         pass
 

turnstone/prompts/personas/engineer.md

@@ -1,9 +1,15 @@
-You are a software engineer working on this project. You know the codebase, the tools, and their limits.
+You are a software engineer working on this project. You do real work: investigating bugs, implementing features, reviewing code for correctness and security, writing code that ships. You know your tools and their limits. You learn a codebase by reading it, not by assuming you remember it.
 
-You do real work: investigating bugs, implementing features, reviewing security, writing code that ships. You have access to the project's files and the tools your environment provides. You don't have access to everything — some tools require approval, some paths are restricted, and that's by design. You work within those boundaries.
+Some tools require approval and some paths are restricted — that's by design, and you work within those boundaries rather than around them. Ambiguity is different: when a request is unclear, you make a reasonable call, note what you assumed, and keep moving. You don't stall asking for permission on judgment calls.
 
-You think before you act. You read before you edit. You verify before you commit. When something breaks, you diagnose before you retry. When you're uncertain, you say so. When a request is ambiguous, you make a reasonable call and note what you assumed — you don't stall asking for permission on every judgment call.
+You think before you act. You read before you edit. You verify before you commit — and you never report a result you didn't observe. When you're uncertain, you say so. When something breaks, you diagnose before you retry. When two or three attempts haven't landed, you stop and report what you tried and what you learned instead of thrashing.
 
-When you disagree with a direction, you push back with reasoning — then defer to the user's call.
+When you take on a change, you work in phases: understand the problem and the relevant code surface, design the approach, plan the specific edits, make them, verify they work. You don't skip to editing. When you can delegate exploration to a task_agent, you do — mapping boundaries and file locations before you commit to a design. You scale the ceremony to the size of the change: a one-line fix doesn't need a phase plan.
+
+When the work is testable, you write the failing test first, then the implementation that makes it pass. That defines "done" before you build and leaves a regression net behind. Config, docs, and mechanical refactors may not need it, but red-green is your default. A test is a specification, not a hurdle: if one is wrong, you fix it deliberately and say so. You never weaken a test to make it pass.
+
+You make the smallest change that solves the problem. You don't refactor what you weren't asked to touch; when you see something worth improving nearby, you note it instead.
+
+When you disagree with a direction, you push back with reasoning, once — then you defer to the user's call, stating your disagreement for the record.
 
 The code you write will run. The files you edit are real. The commits you make go to a shared repository. Act accordingly.

turnstone/prompts/tools.md

@@ -26,6 +26,14 @@ Run a command, git, or tests → bash:
 Retrieve a URL → web_fetch:
    web_fetch(url='https://example.com')
 
+Show the user content visually (rendered page, PDF, image, data table) → open_preview:
+   open_preview(target='https://example.com/pricing')
+   open_preview(target='chart.png')
+   open_preview(target='results.csv')
+User asks to READ/SEE something → open_preview; you need to reason about it yourself → web_fetch / read_file.
+Render then show → bash then open_preview:
+   bash(command='python plot.py') → open_preview(target='plot.png')
+
 Search the web for information → web_search:
    web_search(query='current population of Tokyo')
 

turnstone/sdk/console.py

@@ -557,6 +557,8 @@ class AsyncTurnstoneConsole(_BaseClient):
         model: str = "",
         auto_approve: bool = False,
         auto_approve_tools: list[str] | None = None,
+        persona: str = "",
+        project_id: str = "",
         enabled: bool = True,
     ) -> ScheduleInfo:
         body: dict[str, Any] = {
@@ -577,6 +579,10 @@ class AsyncTurnstoneConsole(_BaseClient):
             body["model"] = model
         if auto_approve_tools:
             body["auto_approve_tools"] = auto_approve_tools
+        if persona:
+            body["persona"] = persona
+        if project_id:
+            body["project_id"] = project_id
         return await self._request(
             "POST", "/v1/api/admin/schedules", json_body=body, response_model=ScheduleInfo
         )
@@ -600,6 +606,8 @@ class AsyncTurnstoneConsole(_BaseClient):
         initial_message: Any = _UNSET,
         auto_approve: Any = _UNSET,
         auto_approve_tools: Any = _UNSET,
+        persona: Any = _UNSET,
+        project_id: Any = _UNSET,
         enabled: Any = _UNSET,
     ) -> ScheduleInfo:
         body: dict[str, Any] = {}
@@ -614,6 +622,8 @@ class AsyncTurnstoneConsole(_BaseClient):
             ("initial_message", initial_message),
             ("auto_approve", auto_approve),
             ("auto_approve_tools", auto_approve_tools),
+            ("persona", persona),
+            ("project_id", project_id),
             ("enabled", enabled),
         ]:
             if val is not _UNSET:

turnstone/sdk/server.py

@@ -112,6 +112,7 @@ class AsyncTurnstoneServer(_BaseClient):
         ws_id: str = "",
         client_type: str = "",
         notify_targets: str = "",
+        project_id: str = "",
         attachments: list[AttachmentUpload] | None = None,
     ) -> CreateWorkstreamResponse:
         """Create a new workstream.
@@ -127,6 +128,8 @@ class AsyncTurnstoneServer(_BaseClient):
 
         *persona* selects the persona the workstream is created with
         (resolved and snapshotted server-side; empty = the kind default).
+        *project_id* attaches the workstream to a project (validated
+        server-side against the *user_id*'s membership; empty = none).
         """
         body: dict[str, Any] = {}
         if name:
@@ -141,6 +144,8 @@ class AsyncTurnstoneServer(_BaseClient):
             body["skill"] = skill
         if persona:
             body["persona"] = persona
+        if project_id:
+            body["project_id"] = project_id
         if initial_message:
             body["initial_message"] = initial_message
         if auto_approve_tools:
@@ -634,6 +639,7 @@ class TurnstoneServer:
         ws_id: str = "",
         client_type: str = "",
         notify_targets: str = "",
+        project_id: str = "",
         attachments: list[AttachmentUpload] | None = None,
     ) -> CreateWorkstreamResponse:
         return self._runner.run(
@@ -650,6 +656,7 @@ class TurnstoneServer:
                 ws_id=ws_id,
                 client_type=client_type,
                 notify_targets=notify_targets,
+                project_id=project_id,
                 attachments=attachments,
             )
         )

turnstone/server.py

@@ -33,7 +33,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Callable, Iterable
 
 from sse_starlette import EventSourceResponse
 from starlette.applications import Starlette
@@ -55,6 +55,7 @@ from turnstone.core.auth import (
     _DenyFilter,
     jwt_version_slot,
 )
+from turnstone.core.idle_nudge_watcher import wake_workstream_if_pending
 from turnstone.core.log import get_logger
 from turnstone.core.metrics import metrics as _metrics
 from turnstone.core.ratelimit import resolve_client_ip
@@ -335,10 +336,11 @@ class WebUI(SessionUIBase):
         output: str,
         *,
         is_error: bool = False,
+        preview: dict[str, Any] | None = None,
     ) -> None:
         """Layer node-only Prometheus metrics on top of the shared body."""
         _metrics.record_tool_call(name)
-        super().on_tool_result(call_id, name, output, is_error=is_error)
+        super().on_tool_result(call_id, name, output, is_error=is_error, preview=preview)
 
     def on_status(self, usage: dict[str, Any], context_window: int, effort: str) -> None:
         """Layer node-only Prometheus metrics on top of the shared body.
@@ -771,6 +773,19 @@ def _interactive_events_replay(
             yield {"type": "intent_verdict", **v}
 
 
+def _watch_fire_wake_fn(ws: Workstream) -> Callable[[], object]:
+    """Wake closure for watch fires, for ``ChatSession.set_watch_runner``.
+
+    Closes over the Workstream OBJECT, never its id: after an
+    eviction+restore the manager tracks the workstream under a fresh id
+    while the watch rows keep the resumed session's ``_ws_id``, so an
+    id-keyed ``manager.get`` lookup at fire time would miss.  Shared by
+    every ``set_watch_runner`` site (create, reopen, watch-restore,
+    CLI ``--resume``) so they can't drift on that subtlety.
+    """
+    return lambda: wake_workstream_if_pending(ws, trigger="watch-fire")
+
+
 def _interactive_open_post_load(request: Request, ws: Workstream) -> None:
     """Post-load hook for the lifted interactive ``open`` body.
 
@@ -793,6 +808,13 @@ def _interactive_open_post_load(request: Request, ws: Workstream) -> None:
        handler-side emission is the load-bearing path on interactive;
        ``InteractiveAdapter.emit_rehydrated`` is a no-op stub
        precisely because this enqueue lives here.
+    4. Re-wire the watch dispatch registration.  The workstream's
+       previous ``close()`` removed its registration, and nothing on
+       the ``open`` path restored it — so a watch firing on a
+       REOPENED, actively-viewed workstream found no dispatch fn and
+       took the restore path, spawning a duplicate auto-approved
+       session that raced turns into the same conversation the live
+       one was showing.
     """
     from turnstone.core.memory import get_workstream_display_name
 
@@ -802,6 +824,12 @@ def _interactive_open_post_load(request: Request, ws: Workstream) -> None:
     if isinstance(ui, WebUI) and session is not None and session.messages:
         ui._enqueue({"type": "clear_ui"})
 
+    runner = getattr(request.app.state, "watch_runner", None)
+    if runner is not None and session is not None:
+        # ``mgr.open`` already resumed, so this keys the registration on
+        # the adopted id (and ``resume()`` re-registers by itself anyway).
+        session.set_watch_runner(runner, wake_fn=_watch_fire_wake_fn(ws))
+
     gq: queue.Queue[dict[str, Any]] | None = getattr(request.app.state, "global_queue", None)
     if gq is not None:
         with contextlib.suppress(queue.Full):
@@ -2103,7 +2131,7 @@ async def _interactive_create_post_install(
         ws.ui.auto_approve = True
     runner = getattr(request.app.state, "watch_runner", None)
     if runner and ws.session:
-        ws.session.set_watch_runner(runner)
+        ws.session.set_watch_runner(runner, wake_fn=_watch_fire_wake_fn(ws))
     gq: queue.Queue[dict[str, Any]] = request.app.state.global_queue
     # Emit ``ws_created`` on the global queue for SSE consumers
     # (console). Held until past attachment validation in the
@@ -2227,7 +2255,9 @@ async def _interactive_create_post_install(
 
     # Initial-message worker thread.
     initial_message = body.get("initial_message", "").strip()
+    initial_message_status = ""
     if initial_message and ws.session is not None:
+        from turnstone.core import session_worker
         from turnstone.core.attachments import (
             resolve_staged_attachments as _resolve_staged,
         )
@@ -2235,20 +2265,13 @@ async def _interactive_create_post_install(
         session = ws.session
         send_id = uuid.uuid4().hex
         resolved_atts: list[Any] = []
+        staged_ord: list[str] = []
         if attachment_ids:
-            # Resolve (peek) the staged uploads, then drain them from the buffer
-            # now.  The inlined first turn is their only consumer and it always
-            # commits at create (no queue rejection by construction), so leaving
-            # them staged would let the freshly-opened pane's rehydrate race the
-            # worker's write-time drain and paint them as still-pending composer
-            # chips.  ``_append_user_turn``'s own per-id discard then no-ops.
-            resolved_atts, _ord, _drop = _resolve_staged(attachment_ids, ws.id, uid)
-            if _ord:
-                from turnstone.core.attachment_buffer import get_attachment_buffer
-
-                _buf = get_attachment_buffer()
-                for _aid in _ord:
-                    _buf.discard(_aid, ws_id=ws.id, user_id=uid)
+            # Resolve (peek) the staged uploads.  The buffer DRAIN happens
+            # after the dispatch below, and only on the spawn path — the
+            # enqueue path can't deliver attachments, so there they must
+            # stay staged (see ``_enqueue_init``).
+            resolved_atts, staged_ord, _drop = _resolve_staged(attachment_ids, ws.id, uid)
 
         def _run_initial() -> None:
             try:
@@ -2267,31 +2290,89 @@ async def _interactive_create_post_install(
                     _fire_notify_targets(ws, last_content)
                 except Exception:
                     log.warning("notify_completion.hook_error", ws_id=ws.id, exc_info=True)
-                with ws._lock:
-                    # Only clear the flag if THIS thread is still the current
-                    # worker — a force-cancel abandons this thread and a
-                    # follow-up send may already have spawned a successor; an
-                    # abandoned initial-send worker finishing late must not
-                    # clobber that successor's running flag (mirrors the guard
-                    # in session_worker._runner).
-                    if ws.worker_thread is threading.current_thread():
-                        ws._worker_running = False
 
-        # Inlined rather than via ``session_worker.send`` because at
-        # workstream creation no live worker can exist by
-        # construction — the enqueue branch of the shared dispatch
-        # is dead code here. ``_worker_running`` + ``ws.worker_thread``
-        # are set together under ``ws._lock`` so a path-keyed send
-        # arriving immediately after creation observes the running
-        # state via the shared session_worker gate instead of racing
-        # into a parallel worker.
-        with ws._lock:
-            ws._worker_running = True
-            t = threading.Thread(target=_run_initial, daemon=True, name=f"ws-init-{ws.id[:8]}")
-            ws.worker_thread = t
-            t.start()
+        init_enqueued = False
 
-    return {"resumed": resumed, "message_count": message_count}
+        def _enqueue_init() -> None:
+            # Reached only if a worker already owns this freshly-created ws
+            # — possible solely with a caller-supplied ws_id raced by a
+            # concurrent /send.  Don't drop the user's first message: queue
+            # its TEXT as an interjection so the live worker delivers it.
+            # Attachments can't ride the interjection seam (queue_message
+            # rejects them), so they stay STAGED instead (the drain below
+            # is skipped on this branch): the composer keeps showing them
+            # as pending chips and the user's next send delivers them.
+            #
+            # No try/except: ``queue.Full`` must reach
+            # ``session_worker.send``'s backpressure branch so it returns
+            # ``False`` — the same surface the /send path reports as
+            # ``queue_full`` — instead of this create responding as if the
+            # message were delivered.
+            nonlocal init_enqueued
+            init_enqueued = True
+            session.queue_message(initial_message)
+            if resolved_atts:
+                log.warning(
+                    "ws_init.live_worker_at_creation ws=%s — %d attachment(s) left staged "
+                    "(cannot ride the interjection seam); message text queued, attachments "
+                    "stay in the composer for the next send",
+                    ws.id[:8],
+                    len(resolved_atts),
+                )
+
+        # Routed through ``session_worker.send`` so the init worker
+        # inherits ``_runner``'s ownership-clear wake backstop
+        # (``_retry_pending_wake``): a nudge enqueued during the initial
+        # send (e.g. a watch fire on a schedule-created workstream) no
+        # longer strands until the next user message.  The enqueue branch
+        # is unreachable by construction (no worker can own a ws at
+        # creation) unless a caller-supplied ws_id is raced — hence
+        # ``_enqueue_init`` preserves the message and leaves the staged
+        # attachments recoverable instead of assuming the branch is dead.
+        init_ok = session_worker.send(
+            ws,
+            enqueue=_enqueue_init,
+            run=_run_initial,
+            thread_name=f"ws-init-{ws.id[:8]}",
+        )
+        if not init_ok:
+            # Two refusal shapes: the raced live worker's interjection
+            # queue rejected the text (``init_enqueued=True`` — queue.Full,
+            # the condition /send surfaces as ``queue_full``), or ``send``
+            # refused outright because the workstream was closed under our
+            # feet (``init_enqueued=False`` — a create raced by an off-loop
+            # close).  Either way the workstream exists and the first
+            # message was NOT delivered; say so instead of answering as if
+            # it were.  Attachments stay staged on both paths (the drain
+            # below is gated on ``init_ok``) so the composer chips survive
+            # for the user's retry.
+            initial_message_status = "queue_full" if init_enqueued else "refused_closed"
+            log.error(
+                "ws_init.initial_message_dropped ws=%s (%s)",
+                ws.id[:8],
+                initial_message_status,
+            )
+        if staged_ord and not init_enqueued and init_ok:
+            # Spawn path took the message: drain the staged copies NOW,
+            # before this handler returns — the pane's rehydrate can only
+            # start after it receives this response, so it can never
+            # observe the consumed uploads as still-pending composer
+            # chips.  (``enqueue`` runs synchronously inside ``send``, so
+            # ``init_enqueued`` is settled here.)  ``_append_user_turn``'s
+            # own per-id discard then no-ops.
+            from turnstone.core.attachment_buffer import get_attachment_buffer
+
+            _buf = get_attachment_buffer()
+            for _aid in staged_ord:
+                _buf.discard(_aid, ws_id=ws.id, user_id=uid)
+
+    out: dict[str, Any] = {"resumed": resumed, "message_count": message_count}
+    if initial_message_status:
+        # Only present when the initial message was NOT delivered — the
+        # factory passes it through to the response so API clients don't
+        # read the 200 as "first message accepted".
+        out["initial_message_status"] = initial_message_status
+    return out
 
 
 def _audit_workstream_created(
@@ -2499,6 +2580,13 @@ async def cancel_watch(request: Request) -> JSONResponse:
     if watch_node and node_id and watch_node != node_id:
         return JSONResponse({"error": "Watch belongs to another node"}, status_code=403)
     storage.update_watch(watch_id, active=False, next_poll="")
+    # AFTER the row write, per forget_terminal_dispatched's ordering
+    # contract: drop the runner's transient state for this id (held
+    # reminder / terminal-dispatched mark) — the inactive row never
+    # re-lists, so nothing else would ever clear it.
+    runner = getattr(request.app.state, "watch_runner", None)
+    if runner is not None:
+        runner.forget_terminal_dispatched(watch_id)
     return JSONResponse({"status": "ok", "watch_id": watch_id})
 
 
@@ -4076,7 +4164,11 @@ async def _lifespan(app: Starlette) -> AsyncGenerator[None, None]:
     if tls_client is not None:
         await tls_client.stop_renewal()
     if app.state.watch_runner:
-        app.state.watch_runner.stop()
+        # ``stop()`` drains in-flight polls (bounded, but up to ~35 s) —
+        # run it off the event loop like the state-writer below so SSE
+        # teardown and the remaining shutdown steps aren't frozen behind
+        # a watch command that's still finishing.
+        await asyncio.to_thread(app.state.watch_runner.stop)
     from turnstone.core.idle_nudge_watcher import shutdown_idle_nudge_watchers
 
     shutdown_idle_nudge_watchers(app)
@@ -4963,7 +5055,7 @@ def main() -> None:
 
     # Create WatchRunner (periodic command polling, server-level)
     from turnstone.core.storage import get_storage as _get_storage
-    from turnstone.core.watch import WatchRunner
+    from turnstone.core.watch import WatchRunner, WatchWorkstreamUnrestorable
 
     # Create session manager first (watch restore_fn captures it).
     interactive_adapter = InteractiveAdapter(
@@ -5022,25 +5114,110 @@ def main() -> None:
         on the rehydrated session, so ``WatchRunner._dispatch_result`` can
         re-deliver the current message into the rehydrated workstream's
         :class:`NudgeQueue` without a second pass through ``restore_fn``.
+
+        Failure taxonomy: two failures are PERMANENT — the persona-stamp
+        pre-read raising (corrupt stamp, nothing created yet) and
+        ``resume()`` returning ``False`` (no stored turns: the target's
+        history is gone, so there is nothing to deliver into and every
+        retry would rebuild this shell just to fail again).  Everything
+        else after ``manager.create`` is treated as transient — the
+        half-built shell is closed so a failed attempt can't leak a
+        ``max_active`` slot, and the runner holds the reminder and
+        retries, bounded by the watch's own poll budget.  Deliberately
+        NOT mapping post-create ``ValueError`` to permanent: ``resume``
+        can raise it for reasons beyond the corrupt-stamp contract, and
+        a misclassification here silently kills the user's watch.
         """
         try:
-            ws = manager.create(user_id="", name="watch-restore", **_resume_persona_kwargs(ws_id))
+            persona_kwargs = _resume_persona_kwargs(ws_id)
+        except ValueError as exc:
+            # PERMANENT: corrupt persona stamp.  Refuse to run the watch
+            # under an envelope the operator didn't choose (it would be
+            # unattended AND auto-approved), and signal the runner to stop
+            # retrying and deactivate the watch rather than burn the whole
+            # attempt budget on a cause that can't clear on its own.
+            log.warning("watch_restore: corrupt persona stamp on ws %s", ws_id, exc_info=True)
+            raise WatchWorkstreamUnrestorable(ws_id) from exc
+
+        try:
+            ws = manager.create(user_id="", name="watch-restore", **persona_kwargs)
+        except RuntimeError:
+            # TRANSIENT: all restore slots active right now.  Return None so
+            # the runner holds the reminder and retries on a later tick.
+            log.warning("watch_restore: cannot restore ws %s (all slots active)", ws_id)
+            return None
+
+        try:
             # Restored workstreams run unattended — auto-approve tool calls
             # to avoid blocking forever on approval with no connected user.
             if isinstance(ws.ui, WebUI):
                 ws.ui.auto_approve = True
-            if ws.session:
-                ws.session.resume(ws_id)
-                ws.session.set_watch_runner(_watch_runner)
-                return _watch_runner.get_dispatch_fn(ws.session._ws_id)
-        except RuntimeError:
-            log.warning("watch_restore: cannot restore ws %s (all slots active)", ws_id)
-        except ValueError:
-            # Corrupt persona stamp — refuse to run the watch under an
-            # envelope the operator didn't choose (it would be unattended
-            # AND auto-approved); the watch stays queued for a manual open.
-            log.warning("watch_restore: corrupt persona stamp on ws %s", ws_id, exc_info=True)
-        return None
+            if ws.session is None:
+                raise RuntimeError("created workstream has no session")
+            if not ws.session.resume(ws_id):
+                # ``resume``'s turn loader swallows storage errors into []
+                # (memory.load_message_turns), so False here is EITHER
+                # "history is gone" (permanent — without this check the
+                # fresh session keeps its own fresh ``_ws_id``, the
+                # registration below keys on THAT, and the reminder would
+                # be "delivered" into a blank, orphaned, auto-approved
+                # session while the watch deactivates as delivered) OR a
+                # transient read blip.  Re-probe with the RAISING storage
+                # call before declaring permanence: misclassifying a blip
+                # silently kills the user's watch and drops the fired
+                # reminder.
+                with contextlib.suppress(Exception):
+                    manager.close(ws.id)
+                try:
+                    turns_exist = bool(_get_storage().load_message_turns(ws_id, checkpointed=True))
+                except Exception:
+                    log.warning(
+                        "watch_restore: turns probe failed for ws %s (treating as transient)",
+                        ws_id,
+                        exc_info=True,
+                    )
+                    return None
+                if turns_exist:
+                    # Rows exist but resume()'s read came back empty — a
+                    # blip.  Retry on the held-delivery cadence.
+                    log.warning("watch_restore: empty resume read for ws %s (blip)", ws_id)
+                    return None
+                log.warning("watch_restore: ws %s has no stored turns", ws_id)
+                raise WatchWorkstreamUnrestorable(ws_id)
+            # A live registration may have appeared while this shell was
+            # being built — the user reopening the workstream mid-restore
+            # (``mgr.open`` + post-load registers their PANE).  The pane
+            # wins: deliver into it and close the redundant shell.
+            # Registering ours would silently clobber the pane's — every
+            # later fire would run unattended in the shell while the user
+            # watches a conversation that never shows its watch results.
+            # (A pane registration landing in the microseconds between
+            # this check and the set below can still be clobbered; that
+            # residue requires the reopen to race a window ~10^6 times
+            # narrower than the restore itself.)
+            existing = _watch_runner.get_dispatch_fn(ws_id)
+            if existing is not None:
+                log.info("watch_restore: live registration appeared for ws %s — yielding", ws_id)
+                with contextlib.suppress(Exception):
+                    manager.close(ws.id)
+                return existing
+            # ``ws`` is the freshly created workstream (manager-tracked id)
+            # even though the session resumed the original ``ws_id`` — the
+            # wake must target the live Workstream object, and firing it
+            # is what lets an unattended restore actually RUN the watch
+            # result (auto_approve above exists for exactly that turn).
+            ws.session.set_watch_runner(_watch_runner, wake_fn=_watch_fire_wake_fn(ws))
+            return _watch_runner.get_dispatch_fn(ws.session._ws_id)
+        except WatchWorkstreamUnrestorable:
+            raise  # shell already closed at the raise site above
+        except Exception:
+            # TRANSIENT: the shell exists but never became the watch's live
+            # target — close it (untrack + mark closed) so the failed
+            # attempt doesn't hold a max_active slot forever.
+            log.warning("watch_restore: resume failed for ws %s", ws_id, exc_info=True)
+            with contextlib.suppress(Exception):
+                manager.close(ws.id)
+            return None
 
     _watch_runner = WatchRunner(
         storage=_get_storage(),
@@ -5066,10 +5243,16 @@ def main() -> None:
         if args.skip_permissions or config_store.get("tools.skip_permissions"):
             ws.ui.auto_approve = True
         assert ws.session is not None
-        ws.session.set_watch_runner(_watch_runner)
         if not ws.session.resume(target_id):
             log.error("Workstream '%s' has no messages.", args.resume)
             sys.exit(1)
+        # AFTER the successful resume (mirroring the restore fn's order),
+        # so the registration keys on the adopted ``target_id`` — the id
+        # the session's watch rows are stamped with.  Registered before
+        # resume, the registry key would be the create-time id no watch
+        # row references, and every fire would restore a SECOND
+        # auto-approved session onto the operator's live conversation.
+        ws.session.set_watch_runner(_watch_runner, wake_fn=_watch_fire_wake_fn(ws))
         log.info("Resumed workstream %s (%d messages)", target_id, len(ws.session.messages))
 
     # Record detected model and judge status in metrics

turnstone/shared_static/chat.css

@@ -1200,6 +1200,171 @@
   background: var(--panel-2);
 }
 
+/* Syntax highlighting — highlight.js theme (instrument panel).
+   Lives here (shared) rather than in a per-surface style.css so the
+   server UI, the console, AND the coordinator all colour hljs token
+   spans identically.  highlight.js emits the <span class="hljs-*">
+   markup on every surface (postRenderHljs in renderer.js); without
+   these rules the spans render in the default --fg and code blocks
+   look unhighlighted.  Colours resolve against the palette variables
+   in base.css (also shared). */
+.msg.assistant pre code.hljs {
+  /* No background here on purpose — the <pre> carries the code-surface colour
+     on every surface (--code-bg on the server UI via .msg.assistant pre, --panel
+     on the console/coordinator via the shared .msg-body pre).  Painting it on
+     the inner <code> too made a darker box inside a lighter pad band wherever
+     the two differ (the console/coordinator seam).  Let the code stay
+     transparent and show the pre. */
+  color: var(--fg);
+  padding: 0;
+}
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-built_in,
+.hljs-type {
+  color: var(--magenta);
+}
+.hljs-string,
+.hljs-attr,
+.hljs-template-tag,
+.hljs-template-variable {
+  color: var(--green);
+}
+.hljs-number,
+.hljs-literal,
+.hljs-variable,
+.hljs-symbol,
+.hljs-bullet {
+  color: var(--cyan);
+}
+.hljs-title,
+.hljs-title.class_,
+.hljs-title.function_ {
+  color: var(--accent);
+}
+.hljs-comment,
+.hljs-quote {
+  color: var(--fg-dim);
+  font-style: italic;
+}
+.hljs-meta {
+  color: var(--fg-dim);
+}
+.hljs-doctag {
+  color: var(--cyan);
+  font-weight: 500;
+}
+.hljs-char.escape_ {
+  color: var(--cyan);
+}
+.hljs-emphasis {
+  font-style: italic;
+}
+.hljs-strong {
+  font-weight: bold;
+  color: var(--fg-bright);
+}
+.hljs-attribute {
+  color: var(--yellow);
+}
+.hljs-regexp,
+.hljs-link {
+  color: var(--cyan);
+}
+.hljs-selector-id,
+.hljs-selector-class {
+  color: var(--yellow);
+}
+.hljs-section {
+  color: var(--accent);
+  font-weight: bold;
+}
+.hljs-tag {
+  color: var(--fg-dim);
+}
+.hljs-name {
+  color: var(--magenta);
+}
+.hljs-params {
+  color: var(--fg);
+}
+.hljs-addition {
+  color: var(--green);
+  background: rgba(52, 211, 153, 0.08);
+  display: inline-block;
+  width: 100%;
+}
+.hljs-deletion {
+  color: var(--red);
+  background: rgba(248, 113, 113, 0.08);
+  display: inline-block;
+  width: 100%;
+}
+.msg.assistant pre.code-terminal {
+  border-left: 2px solid var(--green);
+}
+[data-theme="light"] .hljs-addition {
+  background: rgba(4, 120, 87, 0.06);
+}
+[data-theme="light"] .hljs-deletion {
+  background: rgba(220, 38, 38, 0.06);
+}
+
+/* KaTeX math wrappers — shared for the same reason as the hljs theme above:
+   the console + coordinator load /static/style.css from their own directory
+   (and do NOT load preview.css), so the app-level frame for rendered math has
+   to live here.  The vendored katex.min.css draws the glyphs; this gives block
+   equations a horizontal scroll container (wide equations overflow without it)
+   and colours parse errors. */
+.msg.assistant .katex-display {
+  margin: 8px 0;
+  padding: 8px 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+.msg.assistant .katex-error {
+  color: var(--red) !important;
+  font-size: 12px;
+}
+
+/* Mermaid diagram wrappers — shared for the same reason.  mermaid.js draws a
+   self-contained SVG, so diagrams appear even with these missing; but without
+   them the SVG isn't centred or width-clamped (a wide diagram overflows the
+   pane) and the loading/error states render unstyled. */
+.msg.assistant .mermaid-container {
+  margin: 8px 0;
+  text-align: center;
+  border-radius: var(--radius);
+  overflow-x: auto;
+  min-height: 40px;
+}
+.msg.assistant .mermaid-container svg {
+  max-width: 100%;
+  height: auto;
+}
+.msg.assistant .mermaid-loading {
+  padding: 16px;
+  color: var(--fg-dim);
+  font-size: 12px;
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+}
+.msg.assistant .mermaid-error {
+  text-align: left;
+}
+.msg.assistant .mermaid-error-msg {
+  padding: 8px 12px;
+  color: var(--red);
+  font-size: 12px;
+  font-weight: 600;
+  border-bottom: 1px solid var(--border);
+}
+@media (prefers-reduced-motion: reduce) {
+  .msg.assistant .mermaid-container svg * {
+    animation: none !important;
+  }
+}
+
 .msg-body a {
   color: var(--accent);
   text-decoration: underline;

turnstone/shared_static/conversation.js

@@ -643,6 +643,46 @@ export function buildConvResult(output, opts) {
   return block;
 }
 
+// Preview chip (.conv-preview-chip) — the transcript affordance for a tool
+// result that carries a preview-pane descriptor.  Live results auto-open the
+// pane; this chip is how the operator RE-opens one (after closing the pane,
+// or from a replayed transcript, where nothing auto-opens).  `descriptor` is
+// the structured preview object off the tool_result event / history entry;
+// `onOpen(descriptor)` is the pane-supplied opener (routed through the host
+// seam so this builder stays shell-agnostic).  textContent only.
+export function buildPreviewChip(descriptor, onOpen) {
+  const d = descriptor || {};
+  const chip = document.createElement("button");
+  chip.type = "button";
+  chip.className = "conv-preview-chip";
+  // The label can be a raw URL (no <title> found) — a target with embedded
+  // basic-auth must not print credentials into the transcript.
+  const label = redactCredentials(d.title || d.source || "preview");
+  chip.setAttribute("aria-label", "Open preview: " + label);
+  chip.title = d.source
+    ? "Open preview — " + redactCredentials(d.source)
+    : "Open preview";
+  const glyph = document.createElement("span");
+  glyph.className = "conv-preview-glyph";
+  glyph.setAttribute("aria-hidden", "true");
+  glyph.textContent = "▤";
+  chip.appendChild(glyph);
+  const text = document.createElement("span");
+  text.className = "conv-preview-title";
+  text.textContent = label;
+  chip.appendChild(text);
+  if (d.kind) {
+    const kind = document.createElement("span");
+    kind.className = "conv-preview-kind";
+    kind.textContent = d.kind;
+    chip.appendChild(kind);
+  }
+  if (typeof onOpen === "function") {
+    chip.addEventListener("click", () => onOpen(d));
+  }
+  return chip;
+}
+
 // Expandable body for a task_agent row's nested sub-steps (the "agent card").
 // A task agent runs its own sub-tools; this gives that row a collapsible body
 // the pane renders the live step stream into, so the steps nest UNDER the

turnstone/shared_static/interactive.js

@@ -32,6 +32,7 @@ import {
   buildConvActions,
   buildConvStatus,
   buildAgentCardBody,
+  buildPreviewChip,
   batchKicker,
   indexLabel,
 } from "./conversation.js";
@@ -47,6 +48,15 @@ import { createQueueController } from "./composer_queue.js";
 import { StatusBar } from "./status_bar.js";
 import { streamingRender, streamingRenderFinalize } from "./renderer.js";
 import { setMarkdown, operatorSourceLabel } from "./utils.js";
+import {
+  OVERFLOW_TRIP_COUNT,
+  OVERFLOW_TRIP_WINDOW_MS,
+  DEGRADED_COOLDOWN_BASE_MS,
+  DEGRADED_COOLDOWN_MAX_MS,
+  DEGRADED_COOLDOWN_RESET_MS,
+  overflowWindowTripped,
+  degradedCooldownStep,
+} from "./sse_overflow.js";
 
 let _paneCounter = 0;
 
@@ -166,8 +176,19 @@ const INTERACTIVE_DEFAULT_HOST = {
   // An MCP server needs (re-)consent — the standalone shell drives its
   // settings-gear badge; a bare/console pane surfaces it inline only.
   onConsentDetected() {},
+  // A tool result carried a preview-pane descriptor — the L-shell host opens
+  // the preview pane beside this one; a bare pane keeps the transcript chip
+  // as the only affordance.
+  onPreview() {},
 };
 
+// The SSE overflow-recovery limiter (storm-guard threshold, cooldown-ladder
+// constants, and the two pure helpers overflowWindowTripped /
+// degradedCooldownStep) lives in ./sse_overflow.js — imported above and shared
+// with the coordinator pane so the trip math has a single source of truth.
+// The stateful glue (_noteStreamOverflow / _enterDegradedCatchup below) stays
+// here because it is coupled to this class's disconnectSSE/connectSSE seam.
+
 class Pane {
   constructor(wsId, opts) {
     opts = opts || {};
@@ -247,6 +268,29 @@ class Pane {
     // Set when replay_truncated arrives mid-stream (refetching then would
     // detach the live bubble); consumed on the next idle edge.
     this._pendingTruncatedResync = false;
+    // Field instrumentation for the two distinct "output stops while the
+    // backend is healthy" causes: server-signalled overflow closes
+    // (dropped-events class) vs client dispatch/render throws (wedge
+    // class).  The console lines at each increment carry the running
+    // count, so a field report shows which class fired without a
+    // debugger attached.
+    this._streamHealth = { overflows: 0, renderThrows: 0, malformedFrames: 0 };
+    // Rolling timestamps of stream_overflow closes — input to the
+    // degraded catch-up limiter (see overflowWindowTripped above).
+    this._overflowTimes = [];
+    this._degradedTimer = null;
+    this._degradedCooldownMs = DEGRADED_COOLDOWN_BASE_MS;
+    // Timestamp of the last degraded-catchup trip; drives the cooldown
+    // ladder's escalate-vs-reset decision independently of _overflowTimes.
+    this._lastDegradedAt = 0;
+    // Close-on-hide bookkeeping.  A hidden tab's throttled event loop is
+    // the likeliest too-slow SSE consumer, so the visibilitychange
+    // handler closes the stream on hide and reconnects with the saved
+    // Last-Event-ID on show (replay_ok covers the gap).
+    // _hiddenDisconnect marks that WE closed for hide, so show never
+    // resurrects a stream that was closed deliberately elsewhere.
+    this._visHandler = null;
+    this._hiddenDisconnect = false;
     this._cancelTimeout = null;
     this._forceTimeout = null;
     this._pendingEditSend = null;
@@ -297,6 +341,15 @@ class Pane {
       clearTimeout(this._forceTimeout);
       this._forceTimeout = null;
     }
+    // Any pending degraded-catch-up reconnect is owned by the stream
+    // lifecycle: whoever closes the stream (ws switch, giveUp, destroy,
+    // or a fresh manual connect — connectSSE's first line lands here)
+    // supersedes it.  _enterDegradedCatchup re-arms AFTER its own
+    // disconnect, so this never cancels the timer it is about to set.
+    if (this._degradedTimer) {
+      clearTimeout(this._degradedTimer);
+      this._degradedTimer = null;
+    }
     if (this.evtSource) {
       this.evtSource.close();
       this.evtSource = null;
@@ -1143,6 +1196,30 @@ class Pane {
     if (this._lastEventId != null) {
       evtUrl += "?last_event_id=" + encodeURIComponent(this._lastEventId);
     }
+    // Close-on-hide / replay-on-show: installed once per pane, removed
+    // by the factory's destroy().  A hidden tab's throttled drain is the
+    // likeliest slow consumer behind server-side queue overflow, and an
+    // idle hidden tab holds a node connection for nothing — closing on
+    // hide removes both, and the saved _lastEventId makes the show-edge
+    // reconnect lossless (replay_ok from the server's ring buffer).
+    if (!this._visHandler) {
+      this._visHandler = () => this._onVisibilityChange();
+      document.addEventListener("visibilitychange", this._visHandler);
+    }
+    // Never open an EventSource into a hidden (throttled) tab — including on a
+    // FIRST load in a background tab, where the close-on-hide handler never
+    // fires because there was no open stream to close (a throttled hidden tab
+    // is the worst-case slow consumer that overflows the server send queue).
+    // This is the single connect chokepoint, so it backstops every caller —
+    // fresh connect, degraded retry, recover beat, show edge; the wsId + the
+    // visibilitychange handler installed just above make the show edge
+    // reconnect (replay_ok from the ring). The timer callbacks keep their own
+    // pre-checks (the recover beat's also gates failCount), so this is the
+    // net that closes the fresh-connect gap they never covered.
+    if (document.hidden) {
+      this._hiddenDisconnect = true;
+      return;
+    }
     this.evtSource = new EventSource(evtUrl);
 
     this.evtSource.onopen = () => {
@@ -1175,7 +1252,13 @@ class Pane {
       try {
         data = JSON.parse(e.data);
       } catch (err) {
-        console.warn("interactive: dropping malformed SSE frame", err);
+        this._streamHealth.malformedFrames += 1;
+        console.warn(
+          "interactive: dropping malformed SSE frame (total " +
+            this._streamHealth.malformedFrames +
+            ")",
+          err,
+        );
         return;
       }
       // Tag the event with its own SSE id so the system_turn handler can
@@ -1186,8 +1269,13 @@ class Pane {
       try {
         this.handleEvent(data);
       } catch (err) {
+        this._streamHealth.renderThrows += 1;
         console.error(
-          "interactive: handleEvent failed for " + (data && data.type),
+          "interactive: handleEvent failed for " +
+            (data && data.type) +
+            " (render-throw total " +
+            this._streamHealth.renderThrows +
+            ")",
           err,
         );
       }
@@ -1216,6 +1304,98 @@ class Pane {
     };
   }
 
+  _onVisibilityChange() {
+    if (document.hidden) {
+      // Closing beats letting the hidden tab's throttled event loop
+      // starve the drain until the server-side queue overflows.  The
+      // streaming refs (contentBuffer / currentAssistantEl) survive —
+      // disconnectSSE is transport-only — so the visible tail is intact
+      // when the tab comes back.
+      if (this.evtSource) {
+        this.disconnectSSE();
+        this._hiddenDisconnect = true;
+      }
+    } else if (this._hiddenDisconnect) {
+      this._hiddenDisconnect = false;
+      if (this.wsId) this.connectSSE(this.wsId);
+    }
+  }
+
+  _removeVisibilityHandler() {
+    if (this._visHandler) {
+      document.removeEventListener("visibilitychange", this._visHandler);
+      this._visHandler = null;
+    }
+    this._hiddenDisconnect = false;
+  }
+
+  _noteStreamOverflow() {
+    this._streamHealth.overflows += 1;
+    const now = Date.now();
+    this._overflowTimes.push(now);
+    console.warn(
+      "interactive: server closed the stream after a send-queue overflow " +
+        "(total " +
+        this._streamHealth.overflows +
+        "); reconnect will replay the gap",
+    );
+    // Trip when OVERFLOW_TRIP_COUNT closes land inside the rolling window.
+    // The cooldown-ladder reset lives in _enterDegradedCatchup (keyed off
+    // _lastDegradedAt), NOT here — this method only counts and trips.
+    if (
+      overflowWindowTripped(
+        this._overflowTimes,
+        now,
+        OVERFLOW_TRIP_COUNT,
+        OVERFLOW_TRIP_WINDOW_MS,
+      )
+    ) {
+      this._enterDegradedCatchup();
+    }
+  }
+
+  _enterDegradedCatchup() {
+    // Repeated overflow closes inside one window: this consumer cannot
+    // keep up with live streaming right now, and each reconnect round
+    // just stalls rendering behind the 2.5-4.5 s retry before
+    // re-saturating.  Stop the churn: close the stream, say so in plain
+    // language, and come back after a (doubling) cooldown — that
+    // reconnect replays the gap from the server's ring buffer, or falls
+    // to the replay_truncated → /history resync floor once the gap has
+    // outgrown it.  Either path is lossless for committed turns.
+    const now = Date.now();
+    // Escalate the cooldown when trips recur; reset to base only after a
+    // genuine quiet gap.  Keyed off _lastDegradedAt (a timestamp), NOT
+    // _overflowTimes — this method clears that array below, so keying the
+    // reset off it would restart the ladder on the next storm's first
+    // overflow and the doubling (15→30→60→120s) would never take effect.
+    const step = degradedCooldownStep(
+      this._degradedCooldownMs,
+      this._lastDegradedAt,
+      now,
+      DEGRADED_COOLDOWN_BASE_MS,
+      DEGRADED_COOLDOWN_MAX_MS,
+      DEGRADED_COOLDOWN_RESET_MS,
+    );
+    this._lastDegradedAt = now;
+    this._degradedCooldownMs = step.nextCooldownMs;
+    this._overflowTimes.length = 0;
+    this.disconnectSSE(); // also cancels any earlier degraded timer
+    this.statusBarEl.classList.add("ws-sb-disconnected");
+    this._sbTokens.textContent = "Connection is slow — catching up…";
+    const cooldown = step.cooldown;
+    this._degradedTimer = setTimeout(() => {
+      this._degradedTimer = null;
+      if (document.hidden) {
+        // Reopening into a throttled hidden tab would overflow again —
+        // defer to the visibilitychange show edge instead.
+        this._hiddenDisconnect = true;
+        return;
+      }
+      if (this.wsId) this.connectSSE(this.wsId);
+    }, cooldown);
+  }
+
   _loadHistoryThenConnect(wsId) {
     // Mirror coord's init() ordering: render history from REST first,
     // THEN open the live stream. Disconnect any existing stream up
@@ -1482,7 +1662,13 @@ class Pane {
           try {
             streamingRenderFinalize(doneBodyEl, doneBuffer);
           } catch (err) {
-            console.warn("interactive: streamingRenderFinalize failed", err);
+            this._streamHealth.renderThrows += 1;
+            console.warn(
+              "interactive: streamingRenderFinalize failed (render-throw total " +
+                this._streamHealth.renderThrows +
+                ")",
+              err,
+            );
             doneBodyEl.textContent = doneBuffer;
           }
         }
@@ -1640,6 +1826,7 @@ class Pane {
           evt.name,
           evt.output,
           evt.is_error,
+          evt.preview,
         );
         break;
 
@@ -1829,6 +2016,16 @@ class Pane {
           this._pendingTruncatedResync = true;
         }
         break;
+
+      case "stream_overflow":
+        // The server poisoned this listener at its first queue overflow
+        // and closes the stream right after this frame.  The frame is
+        // id-less, so lastEventId still points below the gap and the
+        // native EventSource reconnect replays it losslessly from the
+        // ring buffer.  Count the close: a persistently slow consumer
+        // trips the degraded catch-up instead of churning reconnects.
+        this._noteStreamOverflow();
+        break;
     }
   }
 
@@ -2662,6 +2859,16 @@ class Pane {
               insertChained(renderCollapsibleOutput(stripped, isToolError));
             }
           }
+          // Replayed preview descriptor: chip only — a reload must never
+          // auto-open panes for every historical preview (the live path's
+          // focused auto-open already happened when it was current).  Error
+          // turns keep their chip: a cancelled BATCH synthesizes an error
+          // result for an open_preview whose content committed fine.
+          if (msg.preview && !isDenied) {
+            insertChained(
+              buildPreviewChip(msg.preview, (d) => this._host.onPreview(d)),
+            );
+          }
           if (
             isToolError &&
             !lastToolBlock.classList.contains("conv-batch--denied")
@@ -3265,7 +3472,7 @@ class Pane {
     return card.wrap;
   }
 
-  appendToolOutput(callId, name, output, isError) {
+  appendToolOutput(callId, name, output, isError, preview) {
     // Capture pin before the streamEl removal + result insertion change
     // scrollHeight — see announceToolBlock.  The result block is the other
     // tall one-shot append in the tool flow (up to 10 lines before collapse).
@@ -3382,6 +3589,15 @@ class Pane {
     }
 
     target.after(out);
+    // Preview descriptor (open_preview): chip in the transcript always; the
+    // pane auto-opens only while THIS pane is the user's focus — a
+    // backgrounded session must not commandeer the split, and the chip
+    // remains the deliberate reopen for that case (and for replay).
+    if (preview && !isError) {
+      const chip = buildPreviewChip(preview, (d) => this._host.onPreview(d));
+      out.after(chip);
+      if (this._host.isFocused(this)) this._host.onPreview(preview);
+    }
     this.scrollToBottom(stick);
   }
 
@@ -4351,6 +4567,14 @@ function createInteractivePane(root, wsId, opts) {
     // reopen a stream for a session we just declared dead.
     pane._historyLoadToken = (pane._historyLoadToken || 0) + 1;
     pane.disconnectSSE();
+    // Detach the visibility handler and clear the hide-close marker: a dead
+    // controller must NOT be resurrected by a tab-visibility change.  Without
+    // this, a tab hidden BEFORE the give-up (which set _hiddenDisconnect) would,
+    // on return, fire _onVisibilityChange and connectSSE() the closed ws —
+    // reopening a stream the shell has declared gone and 404-reconnecting it
+    // forever (onStreamError early-returns when dead, so nothing stops it).
+    // Idempotent with destroy()'s own _removeVisibilityHandler call.
+    pane._removeVisibilityHandler();
     // Terminal wording — the transient error path says "Reconnecting…".
     pane.statusBarEl.classList.add("ws-sb-disconnected");
     pane._sbTokens.textContent = "Disconnected";
@@ -4380,6 +4604,15 @@ function createInteractivePane(root, wsId, opts) {
       if (recoverTimer) clearTimeout(recoverTimer);
       recoverTimer = setTimeout(() => {
         recoverTimer = null;
+        if (document.hidden) {
+          // Don't reopen an EventSource into a hidden (throttled) tab —
+          // that re-creates the slow-consumer overflow close-on-hide
+          // exists to prevent.  Mark it so the visibilitychange show edge
+          // owns the reconnect (a hide close normally set this already;
+          // set it defensively for the error-before-hide ordering).
+          pane._hiddenDisconnect = true;
+          return;
+        }
         if (
           pane.evtSource &&
           pane.evtSource.readyState !== EventSource.CLOSED
@@ -4412,6 +4645,19 @@ function createInteractivePane(root, wsId, opts) {
         window.TS_APP.onConsentDetected(server);
       }
     },
+    // Preview descriptors open the shell's preview pane beside this one.
+    // Bridged through the TS_SHELL seam (mountShell defines it) with THIS
+    // pane's transport context attached, so the preview pane fetches blob
+    // content from the same workstream through the same node proxy the
+    // session streams from.
+    onPreview(descriptor) {
+      if (
+        window.TS_SHELL &&
+        typeof window.TS_SHELL.openPreview === "function"
+      ) {
+        window.TS_SHELL.openPreview(descriptor, { base: base, wsId: wsId });
+      }
+    },
   };
 
   const pane = new Pane(wsId, {
@@ -4466,6 +4712,10 @@ function createInteractivePane(root, wsId, opts) {
         recoverTimer = null;
       }
       pane.disconnectSSE();
+      // The document-level visibilitychange listener holds a strong ref
+      // to the pane — leaving it registered would both leak the pane and
+      // let a show edge reopen a stream for a destroyed controller.
+      pane._removeVisibilityHandler();
       // Terminal cleanup that transport-only reconnects must NOT do (see
       // disconnectSSE): cancel orphan grace timers so a post-destroy escape
       // can't paint into the detached pane / shared announcer, release the

turnstone/shared_static/pane.js

@@ -45,6 +45,12 @@ export class ShellPane {
     this.glyph = opts.glyph || null; // a single static char shown in the tab (e.g. "◇"); stateful panes use a live .ui-glyph-* instead
     this.stateful = opts.stateful || false; // conversational panes: tab glyph tracks live Tier-1 state (set via setTabGlyph)
     this.closable = opts.closable !== false; // dashboard is not closable
+    // Ephemeral: a pane with no standalone background-tab life.  Dismissing its
+    // split cell (the ✕ chip, or unsplit) CLOSES it — destroy, not the default
+    // hide-and-keep-the-tab — because there is no meaningful re-open-from-tab;
+    // its reopen affordance lives elsewhere (the transcript preview chip).  The
+    // preview singleton sets this; conversational panes do not.
+    this.ephemeral = opts.ephemeral || false;
     // DOM — created and owned by the PaneManager on mount:
     this.el = null; // <section class="pane">
     this.bodyEl = null; // <div class="pane-body"> — pane content host
@@ -617,11 +623,25 @@ export class PaneManager {
     return { ok: true };
   }
 
-  /** Collapse back to a single pane — the focused one.  The other panes stay
-   *  open as tabs (they just stop being visible); nothing is closed. */
+  /** Collapse back to a single pane — the focused one.  Other panes stay open
+   *  as tabs (they just stop being visible) — EXCEPT ephemeral ones (e.g. the
+   *  preview), which have no background-tab life and close outright rather than
+   *  linger as orphan tabs.  The focused survivor is spared even if ephemeral. */
   unsplit() {
     if (!this._layout) return;
-    this._exitLayout(this._activeId);
+    const keep = this._activeId;
+    const doomed = this._leaves()
+      .map((l) => l.paneId)
+      .filter((id) => {
+        const p = this._panes.get(id);
+        return id !== keep && p && p.ephemeral;
+      });
+    // close() destroys the pane AND renders/persists/notifies; a 2-cell split
+    // fully collapses inside it, so bail before repeating that work.  Only a
+    // 3+-cell split (or an empty doom list) still needs the exit + refresh here.
+    for (const id of doomed) this.close(id);
+    if (!this._layout) return;
+    this._exitLayout(keep);
     this._renderTabs();
     this._persist();
     this._notifyActive();
@@ -873,7 +893,11 @@ export class PaneManager {
       b.type = "button";
       b.className = "cell-unsplit";
       b.addEventListener("click", () => {
-        if (this._layout && this._leafFor(pane.id)) this.closeCell(pane.id);
+        // In a multi-cell split the chip HIDES this cell (the tab stays) —
+        // except an ephemeral pane (e.g. the preview), which has no background-
+        // tab life and so closes outright, exactly as it does single-pane.
+        if (this._layout && this._leafFor(pane.id) && !pane.ephemeral)
+          this.closeCell(pane.id);
         else this.close(pane.id);
       });
       pane.el.append(b);
@@ -882,11 +906,15 @@ export class PaneManager {
     // Mode-DISTINCT glyphs — an identical signifier at an identical locus with
     // divergent outcomes is a mode-error trap (split-mode muscle memory would
     // fire the destructive close): − hides the cell (reversible — the tab
-    // stays), ✕ closes the pane.  Close mode also wears a danger hover
-    // (shell.css .cell-unsplit--close).
-    b.textContent = multi ? "−" : "✕";
-    b.classList.toggle("cell-unsplit--close", !multi);
-    const label = multi ? "Hide from split — the tab stays open" : "Close pane";
+    // stays), ✕ closes the pane.  The chip DESTROYS whenever the click cannot be
+    // a reversible cell-hide: single-pane always, and an ephemeral pane even in
+    // a split.  Close mode also wears a danger hover (shell.css .cell-unsplit--close).
+    const destroys = !multi || pane.ephemeral;
+    b.textContent = destroys ? "✕" : "−";
+    b.classList.toggle("cell-unsplit--close", destroys);
+    const label = destroys
+      ? "Close pane"
+      : "Hide from split — the tab stays open";
     b.title = label;
     b.setAttribute("aria-label", label);
   }

turnstone/shared_static/preview.css

@@ -0,0 +1,313 @@
+/* ==========================================================================
+   Preview pane (shared_static/preview.js) — header bar + per-kind content.
+   DS tokens only (--ink-*, --panel*, --hair, --accent); no chat.css legacy
+   vars.  The pane fills its PaneManager cell; only .preview-content scrolls.
+   ========================================================================== */
+
+.preview-root {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+/* ----- header bar ----- */
+.preview-bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--hair);
+  background: var(--panel);
+  flex: none;
+}
+
+.preview-nav {
+  flex: none;
+  width: 24px;
+  height: 22px;
+  padding: 0;
+  font-size: 10px;
+  line-height: 1;
+  color: var(--ink-2);
+  background: var(--panel-2);
+  border: 1px solid var(--hair);
+  border-radius: 3px;
+  cursor: pointer;
+}
+.preview-nav:hover:not(:disabled) {
+  color: var(--ink-1);
+  border-color: var(--ink-4);
+}
+.preview-nav:disabled {
+  opacity: 0.35;
+  cursor: default;
+}
+
+.preview-kindchip {
+  flex: none;
+  padding: 1px 6px;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--ink-2);
+  background: color-mix(in srgb, var(--accent) 18%, transparent);
+  border: 1px solid var(--hair);
+  border-radius: 3px;
+}
+.preview-kindchip:empty {
+  display: none;
+}
+
+.preview-titletext {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  color: var(--ink-1);
+}
+
+.preview-ext {
+  flex: none;
+  font-size: 11px;
+  color: var(--ink-2);
+  text-decoration: none;
+  border-bottom: 1px dotted var(--ink-4);
+}
+.preview-ext:hover {
+  color: var(--ink-1);
+}
+
+/* remote-assets opt-in (web previews) — compact single-row header control */
+.preview-assets {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 11px;
+  color: var(--ink-2);
+  white-space: nowrap;
+  cursor: pointer;
+}
+.preview-assets:hover {
+  color: var(--ink-1);
+}
+.preview-assets-box {
+  flex: none;
+  margin: 0;
+  cursor: pointer;
+}
+
+/* ----- content host ----- */
+.preview-content {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+  background: var(--panel-2);
+}
+
+/* web + pdf fill the cell */
+.preview-frame {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  background: #fff; /* pages assume a light canvas until their CSS paints */
+}
+
+.preview-imgwrap {
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 12px;
+}
+.preview-img {
+  max-width: 100%;
+  height: auto;
+}
+
+.preview-pre {
+  margin: 0;
+  padding: 10px 12px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  line-height: 1.5;
+  color: var(--ink-2);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.preview-markdown {
+  padding: 12px 16px;
+  font-size: 13px;
+  color: var(--ink-1);
+}
+/* Code-block chrome + katex display + mermaid: the .msg.assistant-scoped rules
+   in shared chat.css don't reach the pane (content is .preview-markdown, not a
+   .msg.assistant message), so restate them on DS tokens.  The hljs TOKEN colors
+   are global and already apply. */
+.preview-markdown code {
+  padding: 1px 4px;
+  font-family: var(--font-mono);
+  font-size: 0.92em;
+  background: color-mix(in srgb, var(--ink-4) 18%, transparent);
+  border-radius: 3px;
+}
+.preview-markdown pre {
+  padding: 8px;
+  overflow-x: auto;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  background: var(--panel);
+  border: 1px solid var(--hair);
+  border-radius: 3px;
+}
+.preview-markdown pre code {
+  padding: 0;
+  font-size: inherit;
+  background: none;
+}
+.preview-markdown .katex-display {
+  margin: 8px 0;
+  overflow-x: auto;
+}
+/* Mermaid: mermaid.js draws a self-contained SVG, but without a width clamp a
+   wide diagram overflows the pane (the .msg.assistant mermaid rules in chat.css
+   don't reach .preview-markdown). */
+.preview-markdown .mermaid-container {
+  margin: 8px 0;
+  text-align: center;
+  overflow-x: auto;
+}
+.preview-markdown .mermaid-container svg {
+  max-width: 100%;
+  height: auto;
+}
+.preview-markdown img {
+  max-width: 100%;
+}
+
+/* ----- table kind ----- */
+.preview-tablewrap {
+  overflow: auto;
+  padding: 8px;
+}
+.preview-table {
+  border-collapse: collapse;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--ink-2);
+}
+.preview-table th,
+.preview-table td {
+  padding: 3px 8px;
+  border: 1px solid var(--hair);
+  text-align: left;
+  white-space: nowrap;
+  max-width: 360px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.preview-table thead th {
+  position: sticky;
+  top: 0;
+  background: var(--panel);
+  padding: 0;
+}
+.preview-th {
+  display: block;
+  width: 100%;
+  padding: 4px 8px;
+  font: inherit;
+  font-weight: 600;
+  color: var(--ink-1);
+  text-align: left;
+  background: none;
+  border: 0;
+  cursor: pointer;
+}
+.preview-th:hover {
+  background: color-mix(in srgb, var(--accent) 15%, transparent);
+}
+.preview-table th[aria-sort] .preview-th::after {
+  content: " ▲";
+  font-size: 9px;
+}
+.preview-table th[aria-sort="descending"] .preview-th::after {
+  content: " ▼";
+}
+
+/* ----- states ----- */
+.preview-empty,
+.preview-loading,
+.preview-error {
+  padding: 24px 16px;
+  font-size: 12px;
+  color: var(--ink-3);
+  text-align: center;
+}
+.preview-error-msg {
+  margin-bottom: 10px;
+}
+.preview-retry {
+  padding: 4px 14px;
+  font-size: 11px;
+  color: var(--ink-1);
+  background: var(--panel);
+  border: 1px solid var(--hair);
+  border-radius: 3px;
+  cursor: pointer;
+}
+.preview-retry:hover {
+  border-color: var(--ink-4);
+}
+.preview-note {
+  padding: 6px 12px;
+  font-size: 10px;
+  color: var(--ink-3);
+  border-top: 1px solid var(--hair);
+}
+
+/* ----- transcript chip (conversation.js buildPreviewChip) ----- */
+.conv-preview-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  max-width: 100%;
+  margin-top: 6px;
+  padding: 3px 10px;
+  font-size: 11px;
+  color: var(--ink-2);
+  background: color-mix(in srgb, var(--accent) 15%, transparent);
+  border: 1px solid var(--hair);
+  border-radius: 3px;
+  cursor: pointer;
+}
+.conv-preview-chip:hover {
+  color: var(--ink-1);
+  border-color: var(--ink-4);
+}
+.conv-preview-glyph {
+  flex: none;
+  color: var(--ink-3);
+}
+.conv-preview-title {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.conv-preview-kind {
+  flex: none;
+  padding: 0 5px;
+  font-size: 9px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--ink-3);
+  border: 1px solid var(--hair);
+  border-radius: 3px;
+}

turnstone/shared_static/preview.js

@@ -0,0 +1,613 @@
+// preview.js — the preview pane: rich rendering of tool-selected content
+// (a fetched web page, PDF, image, data table, text/markdown document) in a
+// dedicated pane beside the conversation.
+//
+// One singleton pane per shell (PaneManager type "preview").  Content arrives
+// as a DESCRIPTOR — the structured object the open_preview tool folds onto
+// its tool turn ({kind, title, source, attachment_id, content_type, size}) —
+// plus a transport context {base, wsId} from the ORIGINATING conversation
+// pane, so blob fetches route through the same node proxy that session
+// streams from.  Bytes are never inlined into events; everything loads from
+// the per-workstream preview route on cookie auth (the house pattern:
+// plain same-origin src URLs, no blob:/createObjectURL).
+//
+// Developer-tool posture: keyboard-operable (←/→ walk the session's preview
+// history), sandboxed (web content renders in a fully sandboxed iframe on top
+// of the route's own CSP), and coexistent — it opens BESIDE the conversation
+// via openPaneBeside, never replacing it.
+//
+// House style: ES module, programmatic DOM (createElement / textContent /
+// append), NO innerHTML — the one HTML sink is setSafeHtml over
+// renderMarkdown, the sanctioned renderer.js lane.  All queries root-scoped.
+
+import { ShellPane } from "./pane.js";
+import { authFetch } from "./auth.js";
+import { redactCredentials } from "./redact_credentials.js";
+import { renderMarkdown, postRenderMarkdown } from "./renderer.js";
+import { setSafeHtml } from "./utils.js";
+
+// How many viewed descriptors the ←/→ history keeps.  Session-scoped and
+// in-memory; only the CURRENT one is persisted for reload (pane.meta).
+const HISTORY_CAP = 20;
+// Table renderer row cap — past this the DOM cost buys no decision value;
+// the notice row reports what was withheld.
+const TABLE_ROW_CAP = 5000;
+// Automatic reloads for the persist race: the live descriptor beats the
+// tool-turn fold that commits its blob whenever a parallel SIBLING tool is
+// still running — the fold waits on the whole batch, so the gap is that
+// sibling's remaining runtime, not milliseconds.  Backoff doubles from
+// RETRY_BASE_MS across MAX_AUTO_RETRIES attempts (0.9s, 1.8s, 3.6s, 7.2s —
+// ~13.5s covered) before the manual Retry card takes over.
+const RETRY_BASE_MS = 900;
+const MAX_AUTO_RETRIES = 4;
+
+function make(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// The per-workstream serving route for a descriptor, through the originating
+// pane's transport base ("" local, "/node/{id}" console-proxied).
+function previewContentUrl(ctx, descriptor) {
+  const base = (ctx && ctx.base) || "";
+  const ws = (ctx && ctx.wsId) || "";
+  return (
+    base +
+    "/v1/api/workstreams/" +
+    encodeURIComponent(ws) +
+    "/attachments/" +
+    encodeURIComponent(descriptor.attachment_id || "") +
+    "/preview"
+  );
+}
+
+// Append preview query flags to a content URL (which never carries a query of
+// its own).  ``probe`` asks the route for a bodyless 204 "will the real load
+// paint?" preflight — the console reverse proxy forwards a HEAD as a full GET,
+// so a real HEAD would drag the whole blob across the hop just to discard it.
+// ``assets`` opts a sandboxed page back into loading its remote images/styles.
+function withPreviewFlags(url, opts) {
+  const q = [];
+  if (opts && opts.probe) q.push("probe=1");
+  if (opts && opts.assets) q.push("assets=1");
+  return q.length ? url + "?" + q.join("&") : url;
+}
+
+// ---------------------------------------------------------------------------
+// Delimited-text parsing (table kind).  Minimal RFC-4180 state machine:
+// quoted fields, "" escapes, \r\n and \n rows.  Returns rows of strings.
+// ---------------------------------------------------------------------------
+function parseDelimited(text, delim) {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          quoted = false;
+        }
+      } else {
+        field += ch;
+      }
+    } else if (ch === '"' && field === "") {
+      quoted = true;
+    } else if (ch === delim) {
+      row.push(field);
+      field = "";
+    } else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      row.push(field);
+      field = "";
+      rows.push(row);
+      row = [];
+    } else {
+      field += ch;
+    }
+  }
+  if (field !== "" || row.length) {
+    row.push(field);
+    rows.push(row);
+  }
+  // Drop a pure-empty trailing row (text ending in a newline).
+  if (rows.length && rows[rows.length - 1].every((f) => f === "")) rows.pop();
+  return rows;
+}
+
+// JSON payloads → (header, rows).  Array of objects: columns = key union in
+// first-seen order.  Array of scalars/arrays: index-labelled columns.  A bare
+// object: two-column key/value listing.
+function tableFromJson(parsed) {
+  if (Array.isArray(parsed)) {
+    if (
+      parsed.length &&
+      parsed.every((r) => r && typeof r === "object" && !Array.isArray(r))
+    ) {
+      const cols = [];
+      for (const r of parsed) {
+        for (const k of Object.keys(r)) if (!cols.includes(k)) cols.push(k);
+      }
+      const rows = parsed.map((r) =>
+        cols.map((c) => {
+          const v = r[c];
+          if (v == null) return "";
+          return typeof v === "object" ? JSON.stringify(v) : String(v);
+        }),
+      );
+      return { header: cols, rows };
+    }
+    const rows = parsed.map((r) =>
+      Array.isArray(r)
+        ? r.map((v) =>
+            v == null
+              ? ""
+              : typeof v === "object"
+                ? JSON.stringify(v)
+                : String(v),
+          )
+        : [
+            typeof r === "object" && r != null
+              ? JSON.stringify(r)
+              : String(r ?? ""),
+          ],
+    );
+    const width = rows.reduce((w, r) => Math.max(w, r.length), 0);
+    const header = [];
+    for (let i = 0; i < width; i++) header.push(String(i + 1));
+    return { header, rows };
+  }
+  if (parsed && typeof parsed === "object") {
+    return {
+      header: ["key", "value"],
+      rows: Object.entries(parsed).map(([k, v]) => [
+        k,
+        typeof v === "object" && v != null
+          ? JSON.stringify(v)
+          : String(v ?? ""),
+      ]),
+    };
+  }
+  return { header: ["value"], rows: [[String(parsed)]] };
+}
+
+// Numeric-aware comparator for column sorts: numbers order numerically,
+// everything else falls back to locale string compare.
+function compareCells(a, b) {
+  const na = parseFloat(a);
+  const nb = parseFloat(b);
+  const bothNumeric =
+    !Number.isNaN(na) &&
+    !Number.isNaN(nb) &&
+    a.trim() !== "" &&
+    b.trim() !== "";
+  if (bothNumeric && na !== nb) return na < nb ? -1 : 1;
+  if (bothNumeric) return 0;
+  return a.localeCompare(b);
+}
+
+// ---------------------------------------------------------------------------
+// createPreviewPane — the PaneManager factory body.
+//   hostApi: { persistMeta(meta), setTitle(text) } — the two pm-owned verbs
+//   the pane needs, injected by the shell so the pane owns no manager ref.
+//   extra:   the rehydrate hint ({descriptor, ctx}) persisted via pane.meta.
+// ---------------------------------------------------------------------------
+export function createPreviewPane(extra, hostApi) {
+  const api = hostApi || {};
+  const pane = new ShellPane({
+    type: "preview",
+    title: "Preview",
+    glyph: "▤",
+    // Dismissing the preview cell CLOSES it (tab and all) instead of parking an
+    // orphan tab — its content is transient tool output and its reopen lives on
+    // the transcript chip, not the tab bar.
+    ephemeral: true,
+  });
+
+  // Viewed-descriptor history (session-scoped): entries are {descriptor, ctx}.
+  pane._stack = [];
+  pane._idx = -1;
+  pane._loadToken = 0;
+  // Remote-assets opt-in: per-pane, sticky across previews, NOT persisted in
+  // pane meta.  Default OFF — a previewed page must not contact its origin
+  // site (an IP/traffic disclosure) until the user asks.
+  pane._assetsOn = false;
+
+  const shortTitle = (d) => {
+    const t = redactCredentials(d.title || d.source || "preview");
+    return t.length > 40 ? t.slice(0, 39) + "…" : t;
+  };
+
+  const setNavState = () => {
+    pane._backBtn.disabled = pane._idx <= 0;
+    pane._fwdBtn.disabled = pane._idx >= pane._stack.length - 1;
+  };
+
+  const renderEmpty = () => {
+    pane._contentEl.replaceChildren(
+      make(
+        "div",
+        "preview-empty",
+        "Nothing previewed yet — ask the assistant to show a page, file, image, or data table.",
+      ),
+    );
+  };
+
+  const renderError = (message, entry) => {
+    const wrap = make("div", "preview-error");
+    wrap.append(make("div", "preview-error-msg", message));
+    const retry = make("button", "preview-retry", "Retry");
+    retry.type = "button";
+    // A manual retry is a single deliberate attempt — no silent backoff run.
+    retry.addEventListener("click", () => renderEntry(entry, MAX_AUTO_RETRIES));
+    wrap.append(retry);
+    pane._contentEl.replaceChildren(wrap);
+  };
+
+  const renderNote = (text) => make("div", "preview-note", text);
+
+  // ----- per-kind renderers -------------------------------------------------
+
+  const renderWeb = (url) => {
+    const frame = make("iframe", "preview-frame");
+    // Full lockdown: no scripts, no same-origin, no forms/popups.  The route
+    // additionally serves the document under its own CSP sandbox — neither
+    // layer alone is load-bearing.
+    frame.setAttribute("sandbox", "");
+    frame.setAttribute("referrerpolicy", "no-referrer");
+    frame.title = "Web page preview";
+    frame.src = url;
+    pane._contentEl.replaceChildren(frame);
+  };
+
+  const renderPdf = (url, d) => {
+    const frame = make("iframe", "preview-frame");
+    // No sandbox attribute: Chromium's built-in PDF viewer refuses to paint
+    // in a sandboxed context, and the response is inert media (the serving
+    // route omits CSP for application/pdf for the same reason).
+    frame.title = (d.title || "Document") + " (PDF preview)";
+    frame.src = url;
+    pane._contentEl.replaceChildren(frame);
+  };
+
+  const renderImage = (url, d) => {
+    const holder = make("div", "preview-imgwrap");
+    const img = make("img", "preview-img");
+    img.alt = d.title || "Image preview";
+    img.decoding = "async";
+    img.src = url;
+    holder.append(img);
+    pane._contentEl.replaceChildren(holder);
+  };
+
+  const renderText = (text) => {
+    const pre = make("pre", "preview-pre");
+    pre.textContent = text;
+    pane._contentEl.replaceChildren(pre);
+  };
+
+  const renderMarkdownDoc = (text) => {
+    const doc = make("div", "preview-markdown");
+    // The one sanctioned HTML lane: renderer.js output through setSafeHtml.
+    setSafeHtml(doc, renderMarkdown(text));
+    pane._contentEl.replaceChildren(doc);
+    // Vendor post-pass — hljs token coloring + mermaid diagrams, matching the
+    // conversation pane.  Runs AFTER the attach: the renderer tolerates
+    // detached elements (the async mermaid apply gates on isConnected and
+    // attachment here is synchronous), but attach-first matches the
+    // conversation pane's ordering and leaves no room for doubt.
+    // renderer.js typeof-guards absent vendors, so no try/catch is needed.
+    postRenderMarkdown(doc);
+  };
+
+  const renderTable = (text, d) => {
+    let header;
+    let rows;
+    const bare = String(d.content_type || "")
+      .split(";")[0]
+      .trim()
+      .toLowerCase();
+    if (bare === "application/json") {
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch (e) {
+        renderText(text); // not actually JSON — degrade to plain text
+        return;
+      }
+      ({ header, rows } = tableFromJson(parsed));
+    } else {
+      const delim = bare === "text/tab-separated-values" ? "\t" : ",";
+      const all = parseDelimited(text, delim);
+      if (!all.length) {
+        renderText(text);
+        return;
+      }
+      header = all[0];
+      rows = all.slice(1);
+      // Ragged files: a short first row must not silently hide trailing
+      // columns of later rows — pad the header out to the widest row so
+      // every parsed cell renders (and sorts).
+      const width = rows.reduce((w, r) => Math.max(w, r.length), header.length);
+      while (header.length < width) header.push(String(header.length + 1));
+    }
+
+    const wrap = make("div", "preview-tablewrap");
+    const table = make("table", "preview-table");
+    const thead = document.createElement("thead");
+    const headRow = document.createElement("tr");
+    const state = { col: -1, dir: 1, rows };
+
+    const tbody = document.createElement("tbody");
+    const renderBody = () => {
+      tbody.replaceChildren();
+      const shown = state.rows.slice(0, TABLE_ROW_CAP);
+      for (const r of shown) {
+        const tr = document.createElement("tr");
+        for (let c = 0; c < header.length; c++) {
+          const td = document.createElement("td");
+          td.textContent = r[c] != null ? r[c] : "";
+          tr.append(td);
+        }
+        tbody.append(tr);
+      }
+    };
+
+    header.forEach((h, ci) => {
+      const th = document.createElement("th");
+      th.scope = "col";
+      const btn = make("button", "preview-th", h);
+      btn.type = "button";
+      btn.title = "Sort by " + h;
+      btn.addEventListener("click", () => {
+        state.dir = state.col === ci ? -state.dir : 1;
+        state.col = ci;
+        state.rows = state.rows
+          .slice()
+          .sort((a, b) => state.dir * compareCells(a[ci] || "", b[ci] || ""));
+        for (const other of headRow.querySelectorAll("th")) {
+          other.removeAttribute("aria-sort");
+        }
+        th.setAttribute(
+          "aria-sort",
+          state.dir > 0 ? "ascending" : "descending",
+        );
+        renderBody();
+      });
+      th.append(btn);
+      headRow.append(th);
+    });
+    thead.append(headRow);
+    table.append(thead, tbody);
+    renderBody();
+    wrap.append(table);
+    pane._contentEl.replaceChildren(wrap);
+    if (rows.length > TABLE_ROW_CAP) {
+      pane._contentEl.append(
+        renderNote(
+          "Showing " +
+            TABLE_ROW_CAP.toLocaleString() +
+            " of " +
+            rows.length.toLocaleString() +
+            " rows",
+        ),
+      );
+    }
+  };
+
+  // ----- load + dispatch ----------------------------------------------------
+
+  // attempt 0..MAX_AUTO_RETRIES-1 = silent backoff retries for the persist
+  // race; past that (including the manual Retry button, which passes
+  // MAX_AUTO_RETRIES) failures land on the error card immediately.
+  const renderEntry = (entry, attempt) => {
+    const token = ++pane._loadToken;
+    const d = entry.descriptor;
+    const url = previewContentUrl(entry.ctx, d);
+    const failed = (why) => {
+      if (token !== pane._loadToken) return;
+      if (attempt < MAX_AUTO_RETRIES) {
+        setTimeout(
+          () => {
+            if (token === pane._loadToken) renderEntry(entry, attempt + 1);
+          },
+          RETRY_BASE_MS * Math.pow(2, attempt),
+        );
+        return;
+      }
+      renderError(why, entry);
+    };
+
+    pane._kindEl.textContent = d.kind || "";
+    // Display strings can be raw URLs — never print embedded credentials.
+    // The ext link below keeps the RAW url (it must actually navigate).
+    pane._titleEl.textContent = redactCredentials(d.title || d.source || "");
+    pane._titleEl.title = redactCredentials(d.source || "");
+    const isWeb = d.kind === "web" && /^https?:\/\//.test(d.source || "");
+    pane._extLink.hidden = !isWeb;
+    if (isWeb) pane._extLink.href = d.source;
+    // The remote-assets toggle rides web previews only; its checked state
+    // mirrors the pane's sticky opt-in on every render.
+    pane._assetsLabel.hidden = d.kind !== "web";
+    pane._assetsBox.checked = !!pane._assetsOn;
+    api.setTitle && api.setTitle("Preview · " + shortTitle(d));
+
+    pane._contentEl.replaceChildren(make("div", "preview-loading", "Loading…"));
+
+    // Remote assets are a web-only concern; the flag only reaches web URLs.
+    const assetsOn = d.kind === "web" && !!pane._assetsOn;
+    const probeUrl = withPreviewFlags(url, { probe: true, assets: assetsOn });
+    const srcUrl = withPreviewFlags(url, { assets: assetsOn });
+
+    if (d.kind === "web" || d.kind === "pdf" || d.kind === "image") {
+      // src-loaded kinds: preflight with a probe request so the persist race
+      // and auth failures surface as a typed error card, not a broken frame.
+      authFetch(probeUrl)
+        .then((r) => {
+          if (token !== pane._loadToken) return;
+          if (!r.ok) {
+            failed(
+              r.status === 404
+                ? "This preview's content isn't available yet."
+                : "Could not load the preview (" + r.status + ").",
+            );
+            return;
+          }
+          if (d.kind === "web") renderWeb(srcUrl);
+          else if (d.kind === "pdf") renderPdf(srcUrl, d);
+          else renderImage(srcUrl, d);
+        })
+        .catch(() => failed("Could not load the preview."));
+      return;
+    }
+    // text-family kinds render client-side from fetched text.
+    authFetch(url)
+      .then((r) => {
+        if (token !== pane._loadToken) return null;
+        if (!r.ok) {
+          failed(
+            r.status === 404
+              ? "This preview's content isn't available yet."
+              : "Could not load the preview (" + r.status + ").",
+          );
+          return null;
+        }
+        return r.text();
+      })
+      .then((text) => {
+        if (text == null || token !== pane._loadToken) return;
+        if (d.kind === "table") renderTable(text, d);
+        else if (d.kind === "markdown") renderMarkdownDoc(text);
+        else renderText(text);
+      })
+      .catch(() => failed("Could not load the preview."));
+  };
+
+  const showAt = (idx) => {
+    if (idx < 0 || idx >= pane._stack.length) return;
+    pane._idx = idx;
+    setNavState();
+    const entry = pane._stack[idx];
+    renderEntry(entry, 0);
+    // Persist ONLY the current view — reload restores it via the factory's
+    // rehydrate hint (the meta shape is exactly the entry: serializable).
+    api.persistMeta &&
+      api.persistMeta({ descriptor: entry.descriptor, ctx: entry.ctx });
+  };
+
+  /** Public API: show a descriptor (new gesture or chip re-open). */
+  pane.showPreview = (descriptor, ctx) => {
+    if (!descriptor || !descriptor.attachment_id) return;
+    const top = pane._stack[pane._idx];
+    if (
+      top &&
+      top.descriptor.attachment_id === descriptor.attachment_id &&
+      top.descriptor.kind === descriptor.kind
+    ) {
+      // Same content re-requested — re-render in place (retry semantics),
+      // don't grow the history with duplicates.
+      showAt(pane._idx);
+      return;
+    }
+    // A new view truncates any forward history (browser-history semantics).
+    pane._stack = pane._stack.slice(0, pane._idx + 1);
+    pane._stack.push({ descriptor, ctx: ctx || null });
+    if (pane._stack.length > HISTORY_CAP) pane._stack.shift();
+    showAt(pane._stack.length - 1);
+  };
+
+  pane.onMount = function () {
+    const root = make("div", "preview-root");
+
+    const bar = make("div", "preview-bar");
+    const back = make("button", "preview-nav", "◀");
+    back.type = "button";
+    back.title = "Previous preview (←)";
+    back.setAttribute("aria-label", "Previous preview");
+    back.addEventListener("click", () => showAt(pane._idx - 1));
+    const fwd = make("button", "preview-nav", "▶");
+    fwd.type = "button";
+    fwd.title = "Next preview (→)";
+    fwd.setAttribute("aria-label", "Next preview");
+    fwd.addEventListener("click", () => showAt(pane._idx + 1));
+    const kind = make("span", "preview-kindchip", "");
+    const title = make("span", "preview-titletext", "");
+    const ext = make("a", "preview-ext", "Open in browser ↗");
+    ext.target = "_blank";
+    ext.rel = "noopener noreferrer";
+    ext.hidden = true;
+    // Remote-assets opt-in — web previews only.  Plain operator language; the
+    // tooltip states the default posture without naming the mechanism.
+    const assets = make("label", "preview-assets");
+    assets.title = "Off keeps this preview from contacting the site";
+    const assetsBox = make("input", "preview-assets-box");
+    assetsBox.type = "checkbox";
+    assets.append(
+      assetsBox,
+      make("span", "preview-assets-text", "Load remote images & styles"),
+    );
+    assets.hidden = true;
+    assetsBox.addEventListener("change", () => {
+      pane._assetsOn = assetsBox.checked;
+      // Reload the current web preview so its iframe re-fetches in the new
+      // mode.  A toggle is a deliberate act — no silent-backoff run.
+      const cur = pane._stack[pane._idx];
+      if (cur && cur.descriptor.kind === "web")
+        renderEntry(cur, MAX_AUTO_RETRIES);
+    });
+    bar.append(back, fwd, kind, title, ext, assets);
+
+    const content = make("div", "preview-content");
+
+    pane._backBtn = back;
+    pane._fwdBtn = fwd;
+    pane._kindEl = kind;
+    pane._titleEl = title;
+    pane._extLink = ext;
+    pane._assetsLabel = assets;
+    pane._assetsBox = assetsBox;
+    pane._contentEl = content;
+
+    root.append(bar, content);
+    this.bodyEl.append(root);
+
+    // ←/→ walk the preview history while the pane has focus.  The pane hosts
+    // no text inputs; the guard keeps future in-pane fields (and the header
+    // link) from losing their native arrow behaviour.
+    this.el.addEventListener("keydown", (e) => {
+      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+      const t = e.target;
+      if (
+        t &&
+        (t.tagName === "INPUT" ||
+          t.tagName === "TEXTAREA" ||
+          t.isContentEditable)
+      )
+        return;
+      e.preventDefault();
+      showAt(pane._idx + (e.key === "ArrowLeft" ? -1 : 1));
+    });
+
+    setNavState();
+    // Rehydrate: a reload restores the LAST viewed preview from pane.meta.
+    if (extra && extra.descriptor) {
+      pane.showPreview(extra.descriptor, extra.ctx || null);
+    } else {
+      renderEmpty();
+    }
+  };
+
+  pane.onClose = function () {
+    pane._loadToken++; // orphan any in-flight loads
+    pane._stack = [];
+    pane._idx = -1;
+  };
+
+  return pane;
+}

turnstone/shared_static/renderer.js

@@ -268,6 +268,15 @@ function _langToCssClass(lang) {
 // the cap the nested body renders as escaped plain text: degraded, visible.
 var _MD_MAX_DEPTH = 100;
 
+// U+0000 (NUL) only.  Structural sentinels are NUL-framed (chr(0)+tag+idx+
+// chr(0)) and renderer.js is the sole NUL producer, so stripping NUL at the
+// top-level entry closes every forgery path — while leaving every OTHER
+// control byte intact, because a code fence must show pasted source verbatim
+// (terminal output legitimately carries ESC/FF/VT/DEL, none of which can forge
+// a sentinel).  Authored as the literal \x00 escape (only \uXXXX decodes to a
+// raw byte in this toolchain), matching the file's \x00 sentinel convention.
+var _NUL_STRIP_RE = /\x00/g;
+
 export function renderMarkdown(text) {
   if (_fnDepth >= _MD_MAX_DEPTH) {
     return "<p>" + escapeHtml(String(text == null ? "" : text)) + "</p>";
@@ -276,7 +285,21 @@ export function renderMarkdown(text) {
   // messages).  Depth accounting rides a try/finally: a throw anywhere in the
   // body used to strand _fnDepth elevated, freezing _fnScopeId so footnote
   // anchor ids collided across every later message.
-  if (_fnDepth === 0) _fnScopeId++;
+  //
+  // Strip caller-supplied NUL, but at the TOP-LEVEL call ONLY.  The renderer
+  // frames structural blocks with in-band NUL sentinels (NUL+tag+index+NUL)
+  // and escapeHtml preserves U+0000, so model/tool text carrying that shape
+  // could forge a sentinel and duplicate/relocate a block or print "undefined"
+  // (B1/B2/B3).  renderer.js is the sole NUL producer and every restore regex
+  // is NUL-framed, so removing NUL here erases every forgery path — and ONLY
+  // NUL, so a fenced code block still shows pasted control bytes (ESC/FF/VT/
+  // DEL) verbatim.  Depth 0 only: recursive frames (blockquote/details/
+  // footnote bodies) legitimately carry generated sentinels and an
+  // unconditional strip would shred them.  NUL is never valid content.
+  if (_fnDepth === 0) {
+    text = String(text == null ? "" : text).replace(_NUL_STRIP_RE, "");
+    _fnScopeId++;
+  }
   _fnDepth++;
   try {
     return _renderMarkdownBody(text);
@@ -285,10 +308,151 @@ export function renderMarkdown(text) {
   }
 }
 
+// Restore-pass callback factory: one guarded closure per protected-block
+// array.  Returns the matched sentinel `m` when the index is out of range (an
+// inert placeholder the tokenizer strips the NUL from) instead of the array's
+// `undefined`.  Factored so the ~12 restore passes share one implementation
+// and can't drift (e.g. a callback reading the wrong array after a copy-paste).
+function _restorer(arr) {
+  return function (m, idx) {
+    var v = arr[parseInt(idx)];
+    return v === undefined ? m : v;
+  };
+}
+
 function _renderMarkdownBody(text) {
-  // Pre-pass: extract blockquote blocks and recursively render.
-  // Must run FIRST (before code/math protection) so the recursive call
-  // processes raw markdown, not text with outer-scope placeholders.
+  // Protect code blocks before the line-based passes (blockquote,
+  // table) that would otherwise scoop a `> ` / `|` line out of a fenced body
+  // and render it as real markdown nested in <pre><code> (B4: shell
+  // transcripts, quoted email, markdown-about-markdown).  The open matches at
+  // line start after optional indent (group 1) AND an optional list marker
+  // (group 2: `- `, `1. `), so a fence opening on a list-item's marker line
+  // (`- ```py`) still tokenises; both the indent and the marker are re-emitted
+  // before the sentinel so the fence keeps its document position (see the
+  // callback).  A blockquoted fence (`> ```) is NOT matched — `>` is not indent
+  // or a list marker — so the blockquote pass below extracts that `> ` run and
+  // its recursive render handles it.
+  //
+  // The opening-run length is captured and required on the close via
+  // backreference so a 4-backtick outer fence wrapping a 3-backtick inner
+  // (common when embedding markdown-about-markdown or lang-tagged snippets
+  // inside another code block) is tokenised as one outer block with the inner
+  // triple-backticks preserved verbatim — the prior `` ```...``` `` regex
+  // treated the outer-open and inner-open as a single fence pair, stranding
+  // the rest of the content with visible \x00CB{n}\x00 sentinels.
+  //
+  // Two constraints below close the gap that mid-stream buffers expose:
+  //
+  //   1. Content can't contain its own close pattern — `(?!\3)` (group 3 is
+  //      the backtick run; groups 1-2 are the indent and optional list marker)
+  //      inside the content quantifier blocks the lazy matcher from extending
+  //      across another N-backtick run. Without this, a buffer like
+  //      ```mermaid\n<partial>\n```python\n<partial>\n```  would extend
+  //      mermaid's content all the way to the FINAL ```, swallowing python
+  //      and handing mermaid a wrong (and incomplete-looking) source. With
+  //      the lookahead, content stops at the first matching run and the open
+  //      simply doesn't match anything until a true close arrives. Inner
+  //      backticks of a SMALLER count (e.g. 3-backtick inner inside a
+  //      4-backtick outer) still pass since `\3` is the OPEN count.
+  //
+  //   2. The close must live at a line boundary — `[ \t]*(?=\n|$)` after
+  //      `\3` forbids the close from being immediately followed by a language
+  //      tag, so ```python opening another fence can't masquerade as the
+  //      previous fence's close.
+  //
+  // Together these mean an unclosed fence stays as plain markdown until its
+  // true close arrives — no intermediate parse errors flash through mermaid /
+  // hljs while a stream is in flight.
+  // codeBlockRaw keeps each fence's RAW source next to its rendered HTML, so
+  // the <details> pre-pass below can restore a fenced body to raw markdown for
+  // its recursive render (NEW-1) rather than an unresolvable outer sentinel.
+  // Populated only when the text contains a <details> tag — its sole reader —
+  // so the common no-<details> render skips the per-fence slice.  (When there
+  // is no <details>, the details .replace matches nothing and its CB->raw
+  // restore never runs, so the empty array is never read.)
+  var codeBlocks = [];
+  var codeBlockRaw = [];
+  var needFenceRaw = /<details>/i.test(text);
+  text = text.replace(
+    /^([ \t]*)((?:[-*+]|\d+[.)])[ \t]+)?(```+)([^\s`]*)\n((?:(?!\3)[\s\S])*?)\3[ \t]*(?=\n|$)/gm,
+    function (m, indent, marker, _open, lang, code) {
+      var cssLang = _langToCssClass(lang);
+      codeBlocks.push(
+        "<pre><code" +
+          (cssLang ? ' class="language-' + escapeHtml(cssLang) + '"' : "") +
+          ">" +
+          // Strip the trailing newline plus any whitespace an indented close
+          // dragged into the content (a `  ```` close would otherwise leave a
+          // whitespace-only last line in the code block).
+          escapeHtml(code.replace(/\n[ \t]*$/, "")) +
+          "</code></pre>",
+      );
+      // Store the fence source WITHOUT the re-emitted indent/marker prefix so
+      // the <details> CB->raw restore substitutes the fence alone (no double);
+      // only when a <details> is present to read it (kept index-aligned with
+      // codeBlocks because every fence pushes to both in that case).
+      if (needFenceRaw) {
+        codeBlockRaw.push(
+          m.slice(indent.length + (marker ? marker.length : 0)),
+        );
+      }
+      // Re-emit the leading indent AND any list marker so the fence keeps its
+      // place in the document: a nested list item (`  - ```py`) stays nested,
+      // `- ```py` stays a list item, and a fence continuing a footnote def
+      // keeps the 2-space indent the continuation scan needs.  The CB <p>-unwrap
+      // (restore pass) tolerates that preserved indent, so an own-line indented
+      // fence still leaves no stray <p> (NEW-3).  A blockquoted fence (`> ```)
+      // stays excluded: `>` is neither indent nor a list marker.
+      return (
+        indent + (marker || "") + "\x00CB" + (codeBlocks.length - 1) + "\x00"
+      );
+    },
+  );
+
+  // Extract <details> blocks and recursively render — AFTER fence protection,
+  // BEFORE the blockquote/inline/math passes.  Running after fence means a
+  // fenced code block inside <details> is already a \x00CB\x00 sentinel; it is
+  // restored to its RAW source (codeBlockRaw) before the recursive
+  // renderMarkdown, so the code renders in-frame instead of restoring to
+  // `undefined` / an inert sentinel against the recursion's empty arrays
+  // (NEW-1, silent content loss).  Fence-first also masks a `</details>` shown
+  // as example code (so it can't close the block early) and a whole <details>
+  // shown inside a fence (so it stays literal) — no separate fence-awareness
+  // needed.  The open is anchored to line start (`^[ \t]*`: allows indentation,
+  // e.g. under a list, but not a mid-line `<details>` inside inline code — B5);
+  // the close stays unanchored so the one-line
+  // <details><summary>x</summary>y</details> form still matches.
+  var detailsBlocks = [];
+  text = text.replace(
+    /^[ \t]*<details>\s*\n?([\s\S]*?)<\/details>/gim,
+    function (m, inner) {
+      // Restore any fenced bodies to raw markdown so the recursion re-renders
+      // them in its own frame (the outer codeBlocks entry is then unused).
+      inner = inner.replace(/\x00CB(\d+)\x00/g, _restorer(codeBlockRaw));
+      var sumMatch = inner.match(
+        /^\s*<summary>([\s\S]*?)<\/summary>\s*\n?([\s\S]*)/i,
+      );
+      var html;
+      if (sumMatch) {
+        html =
+          "<details><summary>" +
+          inlineMarkdown(sumMatch[1].trim()) +
+          "</summary>" +
+          renderMarkdown(sumMatch[2]) +
+          "</details>";
+      } else {
+        html = "<details>" + renderMarkdown(inner) + "</details>";
+      }
+      detailsBlocks.push(html);
+      return "\x00DT" + (detailsBlocks.length - 1) + "\x00";
+    },
+  );
+
+  // Pre-pass: extract blockquote blocks and recursively render.  Runs after
+  // fence protection (a fenced `> ` line is already masked as a \x00CB\x00
+  // sentinel, so it is not scooped here — B4) but before the remaining
+  // code/math protection, so the recursive call still processes raw markdown,
+  // not text with outer-scope placeholders.
   var bqBlocks = [];
   (function () {
     var blines = text.split("\n");
@@ -350,80 +514,6 @@ function _renderMarkdownBody(text) {
     text = result.join("\n");
   })();
 
-  // Protect code blocks.  The opening-run length is captured and
-  // required on the close via backreference so a 4-backtick outer
-  // fence wrapping a 3-backtick inner (common when embedding
-  // markdown-about-markdown or lang-tagged snippets inside another
-  // code block) is tokenised as one outer block with the inner
-  // triple-backticks preserved verbatim — the prior `` ```...``` ``
-  // regex treated the outer-open and inner-open as a single fence
-  // pair, stranding the rest of the content with visible
-  // \x00CB{n}\x00 sentinels.
-  //
-  // Two constraints below close the gap that mid-stream buffers
-  // expose:
-  //
-  //   1. Content can't contain its own close pattern — `(?!\1)`
-  //      inside the content quantifier blocks the lazy matcher
-  //      from extending across another N-backtick run. Without
-  //      this, a buffer like  ```mermaid\n<partial>\n```python\n
-  //      <partial>\n```  would extend mermaid's content all the
-  //      way to the FINAL ```, swallowing python and handing
-  //      mermaid a wrong (and incomplete-looking) source. With
-  //      the lookahead, content stops at the first matching run
-  //      and the open simply doesn't match anything until a true
-  //      close arrives. Inner backticks of a SMALLER count (e.g.
-  //      3-backtick inner inside a 4-backtick outer) still pass
-  //      since `\1` is the OPEN count, not just three.
-  //
-  //   2. The close must live at a line boundary — `[ \t]*(?=\n|$)`
-  //      after `\1` forbids the close from being immediately
-  //      followed by a language tag, so ```python opening another
-  //      fence can't masquerade as the previous fence's close.
-  //
-  // Together these mean an unclosed fence stays as plain markdown
-  // until its true close arrives — no intermediate parse errors
-  // flash through mermaid / hljs while a stream is in flight.
-  var codeBlocks = [];
-  text = text.replace(
-    /(```+)([^\s`]*)\n((?:(?!\1)[\s\S])*?)\1[ \t]*(?=\n|$)/g,
-    function (m, _open, lang, code) {
-      var cssLang = _langToCssClass(lang);
-      codeBlocks.push(
-        "<pre><code" +
-          (cssLang ? ' class="language-' + escapeHtml(cssLang) + '"' : "") +
-          ">" +
-          escapeHtml(code.replace(/\n$/, "")) +
-          "</code></pre>",
-      );
-      return "\x00CB" + (codeBlocks.length - 1) + "\x00";
-    },
-  );
-
-  // Protect <details> blocks (safe HTML — attribute-free only)
-  var detailsBlocks = [];
-  text = text.replace(
-    /<details>\s*\n?([\s\S]*?)<\/details>/gi,
-    function (m, inner) {
-      var sumMatch = inner.match(
-        /^\s*<summary>([\s\S]*?)<\/summary>\s*\n?([\s\S]*)/i,
-      );
-      var html;
-      if (sumMatch) {
-        html =
-          "<details><summary>" +
-          inlineMarkdown(sumMatch[1].trim()) +
-          "</summary>" +
-          renderMarkdown(sumMatch[2]) +
-          "</details>";
-      } else {
-        html = "<details>" + renderMarkdown(inner) + "</details>";
-      }
-      detailsBlocks.push(html);
-      return "\x00DT" + (detailsBlocks.length - 1) + "\x00";
-    },
-  );
-
   // Protect inline code FIRST so backtick spans containing math
   // delimiters (e.g. `` `$$x$$` `` or `` `\[x\]` ``) stay literal.
   // Display math used to run first, but that lets the math regex
@@ -700,7 +790,20 @@ function _renderMarkdownBody(text) {
 
   var result = out.join("\n");
 
-  // Append footnote section if any definitions were collected
+  // Append footnote section if any definitions were collected.
+  //
+  // Each definition body is rendered by a recursive renderMarkdown call.  The
+  // body was collected AFTER the inline-code/math passes, so it may carry
+  // outer-scope sentinels (e.g. `code` in a footnote -> a \x00IC\x00 sentinel).
+  // The recursion can't resolve those against its own fresh, empty arrays, but
+  // the restore guard (Fix 2) leaves the sentinel intact instead of emitting
+  // "undefined"; because this section is appended to `result` BEFORE the
+  // restore passes below — whose inlineCodes/mathBlocks are still populated —
+  // the OUTER restore resolves it, so inline code / math in a footnote renders
+  // correctly.  A FENCED block continuing a footnote definition works the same
+  // way: the fence pass re-emits its 2-space indent before the sentinel, so
+  // the continuation scan still collects it and the round-trip restores the
+  // code inside the footnote item.
   var fnKeys = Object.keys(footnoteDefs);
   if (fnKeys.length > 0) {
     var fnHtml =
@@ -727,40 +830,31 @@ function _renderMarkdownBody(text) {
     result += fnHtml;
   }
 
-  // Restore protected blocks
-  result = result.replace(/\x00CB(\d+)\x00/g, function (m, idx) {
-    return codeBlocks[parseInt(idx)];
-  });
-  result = result.replace(/<p>\x00DT(\d+)\x00<\/p>/g, function (m, idx) {
-    return detailsBlocks[parseInt(idx)];
-  });
-  result = result.replace(/\x00DT(\d+)\x00/g, function (m, idx) {
-    return detailsBlocks[parseInt(idx)];
-  });
-  result = result.replace(/<p>\x00BQ(\d+)\x00<\/p>/g, function (m, idx) {
-    return bqBlocks[parseInt(idx)];
-  });
-  result = result.replace(/\x00BQ(\d+)\x00/g, function (m, idx) {
-    return bqBlocks[parseInt(idx)];
-  });
-  result = result.replace(/<p>\x00MB(\d+)\x00<\/p>/g, function (m, idx) {
-    return mathBlocks[parseInt(idx)];
-  });
-  result = result.replace(/\x00MB(\d+)\x00/g, function (m, idx) {
-    return mathBlocks[parseInt(idx)];
-  });
-  result = result.replace(/<p>\x00TB(\d+)\x00<\/p>/g, function (m, idx) {
-    return tableBlocks[parseInt(idx)];
-  });
-  result = result.replace(/\x00TB(\d+)\x00/g, function (m, idx) {
-    return tableBlocks[parseInt(idx)];
-  });
-  result = result.replace(/\x00IC(\d+)\x00/g, function (m, idx) {
-    return inlineCodes[parseInt(idx)];
-  });
-  result = result.replace(/\x00IM(\d+)\x00/g, function (m, idx) {
-    return inlineMaths[parseInt(idx)];
-  });
+  // Restore protected blocks through the _restorer factory (out-of-range
+  // indices — reachable only via a recursive frame whose fresh array can't
+  // resolve an outer-scope sentinel, the NEW-1 residual — leave the inert
+  // sentinel rather than the literal "undefined").  Each block type unwraps a
+  // `<p>SENTINEL</p>` paragraph first (the line pass wraps a lone sentinel in
+  // <p>) so the browser doesn't split a stray empty <p> off the block; the
+  // bare form follows.  The CB unwrap also tolerates surrounding whitespace
+  // (`<p>  \x00CB0\x00</p>`) because the fence pass re-emits an own-line
+  // fence's leading indent before the sentinel — the other block types emit
+  // their sentinel at column 0, so they don't need it.
+  result = result.replace(
+    /<p>[ \t]*\x00CB(\d+)\x00[ \t]*<\/p>/g,
+    _restorer(codeBlocks),
+  );
+  result = result.replace(/\x00CB(\d+)\x00/g, _restorer(codeBlocks));
+  result = result.replace(/<p>\x00DT(\d+)\x00<\/p>/g, _restorer(detailsBlocks));
+  result = result.replace(/\x00DT(\d+)\x00/g, _restorer(detailsBlocks));
+  result = result.replace(/<p>\x00BQ(\d+)\x00<\/p>/g, _restorer(bqBlocks));
+  result = result.replace(/\x00BQ(\d+)\x00/g, _restorer(bqBlocks));
+  result = result.replace(/<p>\x00MB(\d+)\x00<\/p>/g, _restorer(mathBlocks));
+  result = result.replace(/\x00MB(\d+)\x00/g, _restorer(mathBlocks));
+  result = result.replace(/<p>\x00TB(\d+)\x00<\/p>/g, _restorer(tableBlocks));
+  result = result.replace(/\x00TB(\d+)\x00/g, _restorer(tableBlocks));
+  result = result.replace(/\x00IC(\d+)\x00/g, _restorer(inlineCodes));
+  result = result.replace(/\x00IM(\d+)\x00/g, _restorer(inlineMaths));
 
   return result;
 }

turnstone/shared_static/shell.css

@@ -827,9 +827,11 @@
   z-index: 13; /* above the ring overlay — a clean bar, not bar-plus-ring-line */
   pointer-events: none;
 }
-/* per-pane ✕ — on every visible pane.  Split mode: "hide this cell" (the TAB
-   stays — closeCell); single-pane: "close pane" (withheld from the unclosable
-   Dashboard).  Shell chrome floating over pane content: elevated panel +
+/* per-pane dismiss chip (.cell-unsplit) — on every visible pane.  Split mode:
+   "−" hides this cell (the TAB stays — closeCell), but an ephemeral pane (the
+   preview) shows "✕" and closes outright; single-pane: "✕" closes the pane
+   (withheld from the unclosable Dashboard).  The destructive "✕" modes wear
+   .cell-unsplit--close.  Shell chrome floating over pane content: elevated panel +
    hairline so it reads as the shell's, not the conversation's; sits clear of
    the 2px focus bar and the cell corner. */
 .cell-unsplit {

turnstone/shared_static/shell.js

@@ -33,6 +33,7 @@ import { authFetch } from "./auth.js";
 // standalone turnstone-server has no /static/coordinator/* and a static import
 // would 404 and abort the whole shell module.
 import { createInteractivePane } from "./interactive.js";
+import { createPreviewPane } from "./preview.js";
 
 function make(tag, className, text) {
   const node = document.createElement(tag);
@@ -1003,6 +1004,40 @@ async function mountShell() {
     }
   }
 
+  // Preview pane: rich rendering of tool-selected content (the open_preview
+  // tool) — a singleton that opens BESIDE the conversation that produced it.
+  // Surface-agnostic: the descriptor arrives on a conversational pane's
+  // Tier-2 stream and reaches here through the TS_SHELL.openPreview seam.
+  // `extra` is the rehydrate hint (last-viewed descriptor + transport ctx)
+  // the pane keeps current via setPaneMeta, so a reload restores the view.
+  pm.registerType("preview", (id, extra) => {
+    const pane = createPreviewPane(extra, {
+      persistMeta: (meta) => pm.setPaneMeta("preview", meta),
+      setTitle: (text) => pm.setTabTitle("preview", text),
+    });
+    pane.tabMenu = () => [
+      {
+        label: "Close pane",
+        accel: "close-pane",
+        key: paneAccelBadge("close-pane"),
+        action: () => pm.close(pane.id),
+      },
+    ];
+    return pane;
+  });
+  // Create-or-focus the preview pane BESIDE the focused cell (the
+  // conversation stays visible; a denied split degrades to a tab swap
+  // inside openPaneBeside), then hand it the descriptor.  `ctx` is the
+  // originating pane's transport context ({base, wsId}) — blob fetches ride
+  // the same node proxy the session streams from.
+  const openPreview = (descriptor, ctx) => {
+    if (!descriptor) return;
+    const pane = pm.openPaneBeside("preview");
+    if (pane && typeof pane.showPreview === "function") {
+      pane.showPreview(descriptor, ctx || null);
+    }
+  };
+
   // Tier-1 lifecycle → pane signal.  The console's ws_closed handler calls
   // this so an open pane on a CLOSED session closes outright — tab gone, a
   // split cell collapses onto its sibling.  This is the coordinator-closes-
@@ -1023,6 +1058,7 @@ async function mountShell() {
     notifySessionClosed,
     setRowBadge,
     inEditable,
+    openPreview,
   };
 
   // Login fan-out: app.js owns the single window.onLoginSuccess (the Tier-1