ytdb-slate 0.8.0 → 0.9.0

package/docs/context-budget.md

@@ -142,13 +142,16 @@ schema. A tool description and a parameter description are therefore both
 always loaded.
 
 The current `thread` tool description is 1,386 UTF-8 bytes. Its serialized
-parameter schema is 1,791 bytes, measured as `JSON.stringify(parameters)`, and
-includes the 289-byte `type` parameter description. The description and schema
-are 3,177 bytes together before provider framing. The thread-type wording in
-the description and schema adds 142 bytes to the previous combined figure. The
-increase is roughly 36 tokens at four characters per token. The figure excludes
-the prompt snippet, prompt guidelines, tool name,
-provider framing, and any serialization outside the parameter schema.
+parameter schema is 2,005 bytes, measured as `JSON.stringify(parameters)`.
+The schema includes the 289-byte `type` parameter description and the
+`freshContext` argument.
+
+The description and schema total 3,391 bytes before provider framing. The
+`freshContext` schema entry adds 214 bytes to the previous combined figure.
+The increase is roughly 54 tokens at four characters per token.
+
+The figure excludes the prompt snippet, prompt guidelines, tool name,
+provider framing, and serialization outside the parameter schema.
 
 The always-loaded doctrine has a separate measurement after the compaction
 policy.
@@ -174,14 +177,14 @@ you pay its input tokens every turn.
 
 **Its size depends on where the package is installed.** That is not
 obvious, and it catches anyone who measures: the doctrine cites the
-shipped docs by ABSOLUTE path, so three to six full filesystem paths
-are embedded in the block — three at minimum
-(`track-workflow.md`, `review-rules.md`, `design-principles.md`),
-plus `pr-publishing.md` when `workflow.draftPRs` is on, plus
-`model-routing.md` when the routing rule renders, plus
-`writing-guidance.md` when `writing.check` is on. Every additional
-character in the installed `docs/` directory therefore costs 3–6
-characters of doctrine.
+shipped docs by ABSOLUTE path, so four to seven full filesystem paths
+are embedded in the block — four at minimum
+(`thread-cache-cost.md`, `track-workflow.md`, `review-rules.md`,
+`design-principles.md`), plus `pr-publishing.md` when
+`workflow.draftPRs` is on, plus `model-routing.md` when the routing
+rule renders, plus `writing-guidance.md` when `writing.check` is on.
+Every additional character in the installed `docs/` directory therefore
+costs 4–7 characters of doctrine.
 
 The figures below are **portable characters**, defined exactly as
 Slate's own automated `doctrine-budget` check defines them: the
@@ -204,18 +207,18 @@ must be named instead of presented as the same measurement:
 
 | router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
-| off | — | off | off | 3 | 1,929 | 38 |
-| off | — | off | on | 4 | 2,999 | 60 |
-| off | — | on | off | 4 | 1,948 | 38 |
-| off | — | on | on | 5 | 3,018 | 60 |
-| on | `.pi/slate.json` six | off | off | 4 | 3,879 | 58 |
-| on | `.pi/slate.json` six | off | on | 5 | 4,949 | 80 |
-| on | `.pi/slate.json` six | on | off | 5 | 3,898 | 58 |
-| on | `.pi/slate.json` six | on | on | 6 | 4,968 | 80 |
-| on | all 9 shipped | off | off | 4 | 4,434 | 61 |
-| on | all 9 shipped | off | on | 5 | 5,504 | 83 |
-| on | all 9 shipped | on | off | 5 | 4,453 | 61 |
-| on | all 9 shipped | on | on | 6 | 5,523 | 83 |
+| off | — | off | off | 4 | 2,270 | 43 |
+| off | — | off | on | 5 | 3,340 | 65 |
+| off | — | on | off | 5 | 2,289 | 43 |
+| off | — | on | on | 6 | 3,359 | 65 |
+| on | `.pi/slate.json` six | off | off | 5 | 4,300 | 64 |
+| on | `.pi/slate.json` six | off | on | 6 | 5,370 | 86 |
+| on | `.pi/slate.json` six | on | off | 6 | 4,319 | 64 |
+| on | `.pi/slate.json` six | on | on | 7 | 5,389 | 86 |
+| on | all 9 shipped | off | off | 5 | 4,855 | 67 |
+| on | all 9 shipped | off | on | 6 | 5,925 | 89 |
+| on | all 9 shipped | on | off | 6 | 4,874 | 67 |
+| on | all 9 shipped | on | on | 7 | 5,944 | 89 |
 
 An untrusted project reads the first row whatever its `slate.json`
 says: no project config is loaded, so no optional rule renders. Line
@@ -231,9 +234,9 @@ path:
 
 - The routing rule is a live table with ONE ROW PER ROUTABLE MODEL,
   so what renders is the models you CONFIGURE — not the nine Slate
-  ships profiles for. In this snapshot it is 1,950 portable
-  characters and adds 20 doctrine lines for six configured models;
-  for all nine it is 2,505 characters and adds 23 lines. The six
+  ships profiles for. In this snapshot it is 2,030 portable
+  characters and adds 21 doctrine lines for six configured models;
+  for all nine it is 2,585 characters and adds 24 lines. The six
   model rows are 146–181 characters; all nine are 146–183. The
   legend adds a one-off clause per marker it has to explain, so
   growth is not only the sum of new rows.
@@ -247,14 +250,14 @@ worker extensions and support verification decisions:
 
 | basis | models | worker extensions | paths | portable | lines | rough tokens |
 | --- | ---: | --- | ---: | ---: | ---: | ---: |
-| current `.pi/slate.json` dogfood config | 6 | real 2 units / 4 tools | 6 | 5,884 | 90 | ≈1,471 |
-| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 6 | 6,870 | 93 | ≈1,718 |
+| current `.pi/slate.json` dogfood config | 6 | pinned-package 2 units / 4 tools | 7 | 6,305 | 96 | ≈1,576 |
+| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 7 | 7,291 | 99 | ≈1,823 |
 
 The dogfood row uses `workflow.draftPRs: true`, `writing.check: true`, and the
 six models in `.pi/slate.json`. Its extension basis is
 `pi-smart-fetch@0.3.12` plus `pi-web-search@1.3.1`. Those packages resolve to two
 units and four tools. Their worker-extension rule is 916 portable characters /
-11 lines. Raw size remains symbolic: `portable + 6 × length(installed docs
+11 lines. Raw size remains symbolic: `portable + 7 × length(installed docs
 directory)`. No maintainer checkout path belongs in this shipped document.
 
 The stable maximal row uses all nine shipped profiles, draft PRs, and writing.
@@ -267,23 +270,54 @@ independent of installed extension labels, descriptions, versions and other
 prose. The worker rule measures 1,347 characters against its 1,600-character
 verification budget.
 
-`doctrine-budget` caps that representative maximal doctrine at 7,200 portable
-characters. The measured 6,870 leaves 330 characters, or 4.6 percent of the
-7,200-character bound. A positive control adds one capped tool
-and three copies of the largest measured model row. It measures 7,634 portable
-characters and exceeds the bound by 434. These figures are verification budgets,
-never runtime limits. Arbitrary user extension rosters can exceed them.
-
-The exact values are maintenance tripwires. A deliberate doctrine wording,
-requirement roster, renderer cap, or fixture change requires a fresh render
-through `doctrine-budget`. Update its exact expectations and every published
-figure in the same commit. Keep the positive control steps unchanged unless the
-fixture design itself changes.
+The reserve policy is: every doctrine upper bound must exceed its current
+measurement by at least five percent, with a required character-bound raise
+rounded up to the next hundred characters. Existing bounds stay in place when
+they already satisfy the policy. Line bounds use the same five-percent rule and
+the next whole line.
+
+Two guards have different jobs. An exact pinned literal is the sensitive guard.
+It fails for every size change in its rendered fixture, including one character.
+The paired maximal fixtures cover rule 8 with draft pull requests enabled and
+disabled. The bound is a coarse ceiling that stops unbounded growth over time.
+A bound close to a fixture adds friction but no detection, because its exact
+literal already detects the change. Real reserve therefore weakens nothing.
+
+A doctrine change updates the exact literal and every published measurement. A
+maintainer revisits a bound only when the reserve policy requires it. The check
+applies the five-percent rule to every upper bound, so this decision is auditable.
+
+| budget term | measured | old bound | current bound | current reserve |
+| --- | ---: | ---: | ---: | ---: |
+| routing rule characters | 2,585 | 4,000 | 4,000 | 1,415 |
+| routing rule lines | 25 | 34 | 34 | 9 |
+| routing fixed prose | 1,110 | 1,500 | 1,500 | 390 |
+| largest model row | 183 | 300 | 300 | 117 |
+| router-on doctrine | 4,855 | 6,500 | 6,500 | 1,645 |
+| writing-only doctrine | 3,340 | 5,600 | 5,600 | 2,260 |
+| writing plus router | 5,925 | 6,300 | 6,500 | 575 |
+| writing plus extensions | 3,595 | 6,000 | 6,000 | 2,405 |
+| writing plus router and extensions | 6,180 | 6,600 | 6,800 | 620 |
+| maximal doctrine, draft PRs enabled | 7,291 | 7,800 | 7,900 | 609 |
+| maximal doctrine, draft PRs disabled | 7,272 | 7,800 | 7,900 | 628 |
+| capped worker rule | 1,347 | 1,600 | 1,600 | 253 |
+| writing rule characters | 1,070 | 1,150 | 1,150 | 80 |
+| writing rule lines | 23 | 24 | 25 | 2 |
+
+The positive control adds one capped tool and four copies of the largest
+measured model row. It measures 8,239 portable characters and exceeds the new
+7,900-character maximal bound by 339. That margin remains larger than the
+184-character maximum model-row growth and the 212-character capped tool growth.
+The raised bound does not blunt the positive control.
+
+These figures are verification budgets, never runtime limits. Arbitrary user
+extension rosters can exceed them. Keep the positive-control steps unchanged
+unless the fixture design itself changes.
 
 Against a 256,000-token context budget, these blocks remain small. At four
 characters per token as a rough estimate, the shipped-rule table ranges from
-about 482 tokens to about 1,381 tokens. The current dogfood basis is about 1,471
-tokens. The representative maximum is about 1,718 tokens, or 0.67 percent of the
+about 568 tokens to about 1,486 tokens. The current dogfood basis is about 1,576
+tokens. The representative maximum is about 1,823 tokens, or 0.72 percent of the
 default budget.
 
 No tokenizer was run, and tables are denser than prose. The block is re-sent on every request rather than paid once. These figures show how
@@ -381,7 +415,9 @@ long-context rates listed above.
 
 With action-level routing on, this override also settles a warning
 you will otherwise see once per session for each configured
-`gpt-5.6-*` model: Slate's own profile for those models records a
+`gpt-5.6-*` model during resolution. Dispatch-time price divergence warnings
+are conditional and can repeat on later dispatches. Slate's own profile for those
+models records a
 1,050,000-token window, pi's stock registry reports 272,000, and the
 router reports that divergence without adjudicating it (routing uses
 the registry figure). Raising the registry window removes the

package/docs/design-principles.md

@@ -316,10 +316,10 @@ the load-on-demand discipline the extension itself prescribes:
   that ships with this package (`track-workflow.md` in this directory),
   appended to the system prompt every turn while orchestrator mode is
   on. Sizing it matters to the tiering argument, so it is measured
-  rather than asserted: with both conditional tail rules and
-  `workflow.draftPRs` off, the block is **1,929 portable characters /
-  38 lines**, and configuring the router for six models roughly
-  DOUBLES it, to **3,870** on that same basis — the routing rule
+  rather than asserted: with every conditional tail rule off and
+  `workflow.draftPRs` off, the block is **2,270 portable characters /
+  43 lines**, and configuring the router for six models nearly
+  doubles it, to **4,300** on that same basis — the routing rule
   renders one table row per routable model. (Portable characters, and
   the rest of the configurations, are defined and tabulated in
   `context-budget.md`; the raw count also depends on where the package

package/docs/model-routing.md

@@ -279,6 +279,7 @@ warning, but removal is not the ADD remedy in condition 2. Condition
 | pi has no usable credentials configured for it | dropped | "has no usable credentials configured in pi. Slate drops it from routing." | configuration fault |
 | every entry is dropped | router turns OFF | "survived validation. The warnings above name each dropped entry" | configuration fault |
 | no usable input price exists for today's date | kept, ordered last | "Slate cannot compare its cost with the other models." | model data note |
+| a profile price is negative or non-finite | kept, ordered last or unavailable | "has invalid input price data" or "has invalid output price data" | model data note |
 | no usable effort ladder exists in the profile | kept | "Such a level passes through to pi, which clamps it" | model data note |
 | profile context window differs from the registry window | kept, registry value used | "differs between two sources" | model data note |
 | the first profile names unknown routing-critical fields | kept | "picks models from a research table shipped inside slate" | model data note |
@@ -288,20 +289,30 @@ warning, but removal is not the ADD remedy in condition 2. Condition
 | every configured candidate is marked non-preferred | cheapest candidate becomes the base | "profiles mark every configured model as one it must never pick by itself" | configuration fault |
 | resolution throws | router turns OFF | "routing is disabled. The router could not resolve its model list" | configuration fault |
 
-Every warning is emitted at most once per session. The complete
-resolution retains every warning regardless of display filtering.
-With `router.showWarnings: true`, every warning reaches the same
-channel as the other config warnings: a UI notification when a UI is
-attached, the console otherwise. With the default `false`, every
-configuration fault still reaches that channel and model data notes
-do not.
-
-When at least one note is hidden, Slate emits one discoverability
-line after resolution. It gives the hidden warning count, names
-`router.showWarnings`, and says that a hidden warning can affect
-which model runs an action. The count is warnings, not physical
-display lines: one warning can wrap across several lines. No
-discoverability line appears when nothing was hidden.
+Each resolution warning is deduplicated by a condition key and retained in the
+frozen resolution regardless of display filtering. With `router.showWarnings:
+true`, every resolution warning reaches the normal UI notification or console
+channel. With the default `false`, every configuration fault remains visible
+and model data notes are hidden.
+
+When resolution hides at least one note, Slate emits one discoverability line.
+It gives the hidden warning count, names `router.showWarnings`, and says that a
+hidden warning can affect model selection. The count is warnings, not physical
+display lines. The line appears at most once per session.
+
+Dispatch-time warnings are separate. Context substitution, effort evidence
+gaps, long-context billing, failover window notices, and the model-visible
+registry-price divergence warning are evaluated for each planned action. They
+can repeat on later dispatches. The divergence warning is hardened and capped
+through the router sanitizer. It omits exact rates and is not deduplicated.
+
+The exact-rate companion uses the class-aware router sink as a model data note.
+It is hidden by default and shown when `router.showWarnings` is true. Its
+condition key includes the model, date, and differing rates, so identical live
+evidence reports once while changed evidence reports again. It passes through
+the same control stripping, citation cleanup, field caps, and whole-message cap
+as resolution warnings. A hidden dispatch-time note can trigger the one-time
+discoverability line only when resolution did not already trigger it.
 
 Half a list is still a routing policy, so partial drops leave the
 router ON. Nothing surviving is not a policy: the router turns OFF
@@ -485,17 +496,18 @@ model's ladder is unreadable.
   `(unmeasured)` where that applies. `live=<model> (failover)` means
   a held fallback currently overrides the nominal base for the live
   session.
-- **At the session level:** the resolution's own warnings, as UI
-  notifications (console when no UI is attached).
+- **At the session level:** configuration faults and model data notes enabled by
+  `router.showWarnings`, as UI notifications or console output. The default
+  instead shows one discoverability line when it hides notes.
 - **In the orchestrator's own system prompt, every turn:** the
   doctrine gains a routing rule — a table with one row per routable
   model, plus the rules for reading it. This is the surface you do
-  not see, and it is the router's standing cost: 1,950 characters /
-  20 added doctrine lines for six configured models, 2,505 / 23 for
+  not see, and it is the router's standing cost: 2,030 characters /
+  21 added doctrine lines for six configured models, 2,585 / 24 for
   all nine. In the current snapshot a model row costs 146–183
   characters, plus a one-off legend clause for each marker it
   introduces. Configuring the router roughly doubles Slate's
-  always-loaded block (1,929 characters with routing and writing
+  always-loaded block (2,270 characters with routing and writing
   off). Those are PORTABLE characters — the
   doctrine with each occurrence of the installed `docs/` directory
   removed, filenames kept — because the doctrine embeds absolute doc
@@ -506,10 +518,12 @@ model's ladder is unreadable.
 
 ## Expected first-session warnings
 
-The stock count below is a render over this repository's
-`.pi/slate.json`, the shipped profile table, and the provider data
-inside the pinned pi 0.83.0 package. It does not read the live model
-registry. The packaged OpenAI data at
+The stock count below comes from executing `resolveModelRouter` with this
+repository's sanitized `.pi/slate.json`, the shipped profile table, and a real
+`ModelRuntime` from the pinned pi 0.83.0 package. The runtime used
+`modelsPath: null` and `allowModelNetwork: false`, so no local registry override
+or network refresh could affect it. Dummy OpenAI and Anthropic credentials made
+the configured-auth premise explicit. The packaged OpenAI data at
 `@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai/dist/providers/data/openai.json`
 reports a **272,000-token** context window for
 `openai/gpt-5.6-luna`, `openai/gpt-5.6-terra` and
@@ -528,8 +542,8 @@ data notes**. The default `router.showWarnings: false` therefore
 shows **0 of those warnings** and one discoverability line. That line
 begins `slate: there are 11 hidden warnings in the model router.`
 Enabling the option shows all 11 warnings and no discoverability
-line. Each warning fires at most once per session, and the resolution
-is frozen after the first consultation.
+line. Each resolution warning fires at most once per session, and the
+resolution is frozen after the first consultation.
 
 | warnings | class | condition keys | why | shown by default |
 | --- | --- | --- | --- | --- |
@@ -576,9 +590,31 @@ A hidden warning can still alter which model runs an action. Context-
 window divergence is the concrete case, and the stock registry emits
 three such hidden notes for this list. Routing uses the registry
 window, and that value drives the context-window substitution guard.
-`router.showWarnings` changes display only; it does not change the
+`router.showWarnings` changes display only. It does not change the
 resolution or the guard input.
 
+## Thread choice after routing
+
+Routing resolves the model and effort for one action. Thread choice then uses that applied pair when it evaluates a continuation.
+
+A model or effort change makes the existing prefix cold. Current cache-write prices are 12.5 times the matching cache-read prices.
+
+The `thread` tool owns the economic comparison. The orchestrator still decides whether named episodes can replace the live transcript.
+
+On a continuation with `threadChoice.act: true`, `freshContext` is required. With acting off, it is optional. Every supplied valid value reaches the planner on either continuation path. An empty array refuses a restart. A non-empty list of existing episode ids permits one and seeds the new thread.
+
+Whenever `freshContext` is supplied, malformed input or an unknown episode is a tool error before creation or mutation. A valid value on a creation call is accepted and unused because creation has no planner.
+
+The planner can return `continue`, `fresh`, `abstain`, or `refused`. Only `fresh` can trigger a restart when `threadChoice.act` is enabled.
+
+Acting defaults off. The default `threadChoice.report` setting returns the verdict without moving the action.
+
+The planner uses current price rows, recorded prefix size, episode size, and dated retention evidence. It abstains when required price or size evidence is missing.
+
+A stale retention row grants no retention window. Missing retention or elapsed time does not prove expiry, so an unchanged route remains warm.
+
+The complete mechanism and evidence limits are in [Thread cache cost](thread-cache-cost.md).
+
 ## What the router does NOT enforce
 
 Two obligations carried by the shipped profile data and stated in
@@ -724,11 +760,9 @@ concern; a green suite says nothing about it.
   the shipped profile for the plan target when pi's registry can serve
   that model. The `model` argument itself is passed through
   byte-for-byte, so a malformed spec still produces pi's own error.
-- **A mid-thread model switch costs the prompt cache.** A long
-  thread runs overwhelmingly on cache reads; routing a small action
-  to a cheaper model on a cold cache can cost more than staying on
-  the warm one. The router compares base rates, not the cache state
-  of your thread.
+- **A mid-thread route can cost the prompt cache.** A model or effort
+  change makes the prefix cold. The thread-choice planner prices that
+  cache state after routing. See [Thread choice after routing](#thread-choice-after-routing).
 - **The window guard can move an action to a model you did not
   choose** (it warns, and names what it replaced), and it never
   blocks: if nothing listed is wider, the action runs and pi

package/docs/thread-cache-cost.md

@@ -0,0 +1,223 @@
+# Thread cache cost
+
+This document explains Slate's implemented choice between continuing a worker thread and starting a fresh one. It carries mechanism and evidence that would be too costly in Slate's doctrine.
+
+## Evidence record
+
+This document is the durable measurement summary. The deleted research log was folded into the description of [pull request 130](https://github.com/JetBrains/ytdb-slate/pull/130), so that description preserves the approved decisions and their reasoning. It does not contain raw measurements, per-arm tables, or transcripts, and no repository copy of those raw records survives. For more decision rationale and implementation review history, read the pull request. The numerical evidence needed to assess the rules is carried below. Dates are measurement dates, not guarantees about later provider behavior.
+
+Every numerical figure carries one of these evidence labels:
+
+- **Measured probe** reports an observed provider response or local run. Its date and sample size bound the claim. Re-run it under the matching refresh condition below. Slate accepts cache-retention probes for 90 days, then treats them as stale.
+- **Documented provider price** reports a dated provider price row. The profile table records when a row was observed or took effect. No age check rejects an old price row, so maintainers must review prices under the refresh conditions below.
+- **Modelled projection** computes a result from stated inputs. It stays current only while every input and assumption stays current. Regenerate it when any listed input changes.
+- **Implemented constant** reports a code or configuration value. Re-check it whenever the named implementation changes.
+
+## Terms
+
+A **warm thread** can reuse the cached request prefix from its previous turn. That prefix includes the worker instructions, tools, conversation, and prior tool results accepted by the provider's cache.
+
+A **cold thread** cannot reuse that prefix on its next request. The provider must process the prefix again. A cache hit remains a provider decision, so a warm classification predicts eligibility rather than guaranteeing billed cached tokens.
+
+A **turn** is one worker model response and its associated tool activity. The planner prices a caller-supplied turn estimate.
+
+## Total cold transitions
+
+Changing an existing thread's model makes its next request cold. Changing its effort level also makes the request cold, even when the model stays the same. Treat either change as a rewrite of the whole prefix.
+
+The two transition claims have different evidence.
+
+**Measured probe, model-change method, 2026-08-06.** A transcript audit covered three real OpenAI worker threads and 71 assistant turns. It found one in-thread model transition, from `gpt-5.6-luna` to `gpt-5.6-sol`. The switch request read **0** cached tokens and wrote **53,763**; its next request recovered to a 0.528 cache-hit fraction. Thus the model-change sample size is **n=1**, on one provider family. It was observational rather than a controlled arm, and no Anthropic model-change sample was run.
+
+**Measured probe, effort-change method, 2026-08-06.** A corrected controlled run gave each arm a distinct approximately 18,000-token system prefix and a unique tool. It changed only the live effort through the same `setThinkingLevel` route Slate uses. Each provider family had one unchanged control and three changed arms: step up, step down, and `off`.
+
+| family and model | unchanged control | changed arms | changed-arm result |
+| --- | ---: | ---: | --- |
+| OpenAI `gpt-5.6-luna` | 18,113 written, then 18,113 read | 3 | each read 0 after an approximately 18,115-token write |
+| Anthropic `claude-sonnet-5` | 18,555 written, then 18,555 read | 3 | each read 0 after an approximately 18,556-token write |
+
+The effort-change sample is **n=6 transitions** across two model families, with **n=2 controls**. No changed arm showed partial survival. An earlier calibration run had cross-arm tool-definition reuse and was excluded; unique tools removed that independent cache breakpoint.
+
+**Measured probe, effort-change replication, 2026-08-06.** A second controlled harness used a dedicated cache key for every probe, an approximately 6,000-token prefix, and a 60-second gap. The harness also asserted the effort value sent on every request. A low-to-high change produced zero cache reads in **3 of 3 probes** on OpenAI `gpt-5.6-luna` and **3 of 3 probes** on Anthropic `claude-sonnet-5`. Same-effort controls remained warm in **3 of 3 probes** on each model. The sample is three probes per changed or control cell. It tested only a low-to-high transition and only one model from each provider family.
+
+Anthropic documents that a thinking or effort change invalidates the message portion of its cache, so the Anthropic result confirms documented behavior. OpenAI documents no cache effect for an effort change in either direction, so the OpenAI result is new evidence rather than a confirmation of a published guarantee.
+
+The decision rule therefore treats the transitions as binary:
+
+- the model and effort both stay unchanged, so the existing thread remains eligible for prefix reuse;
+- either value changes, so none of the existing prefix receives warm-thread credit.
+
+This rule is conservative rather than a provider guarantee. Provider caching is best effort. The same 2026-08-06 transcript audit found one unexplained OpenAI miss 571 seconds after the prior dispatch, inside the observed retention window and without a model change or known expiry. A zero read can therefore occur without a transition, and these samples cannot prove that every future model, API path, or provider release behaves the same way.
+
+**Measured probe, unexplained-miss follow-up, 2026-08-06.** The 571-second miss did not reproduce. On the same OpenAI `gpt-5.6-sol` model, one dedicated key remained warm in **5 of 5 probes at 571 seconds** and **3 of 3 probes at 1,500 seconds**. A shared key under contention remained warm in **4 of 4 probes at 571 seconds**. An earlier OpenAI `gpt-5.6-luna` arm remained warm in **12 of 12 probes at 571 and 1,500 seconds** while four prefixes competed and a writer ran every 30 seconds.
+
+The follow-up means the original miss is rare or environment-specific. It also means cache-key contention is not the explanation at this tested scale. It does not explain the original miss, which remains unresolved. The original observation stays in this record because failure to reproduce it does not erase the observation.
+
+## Fresh-thread rediscovery
+
+A fresh thread lacks the working context that an existing thread accumulated. Episodes can transfer durable results, but the new worker still has to orient itself to the task and repository.
+
+**Measured probe, method and result, 2026-08-06.** One repository follow-up was given to a continuation and to a fresh thread with durable episode context. The fresh arm made **one more tool call** than the continuation and produced the better answer, with line numbers and a flagged error. The usable sample is **n=1 task pair**. It was not designed as a model-family comparison, and the surviving decision record does not identify the worker models, so no provider-family conclusion follows. A second question supplies no independent sample because its continuation arm was contaminated by prior self-correction.
+
+Slate expresses the observed **+1 tool call** as an approximate one-turn rediscovery penalty. Charge the fresh-thread option one extra turn when comparing it with continuation. The raw transcript and absolute per-arm call counts were not retained; only the measured difference, answer comparison, and contamination finding survive. The sample cannot establish a distribution or a universal constant. A simple action may need no rediscovery, while a poorly compressed or unusual work stream may need more.
+
+## Basis of the two-turn guard
+
+**Modelled projection, method, 2026-08-06.** Six cost-model grids covered OpenAI and Anthropic paths. Each grid crossed context sizes **20k, 40k, 60k, 80k, 120k, and 160k** with **1, 3, 5, 10, and 20** future turns: 30 cells per grid and **180 modeled cells** in total, not 180 live dispatches. The cases were OpenAI warm and cold before shared seed reads, OpenAI warm and cold after shared seed reads, and Anthropic warm and cold.
+
+The projection used **measured probe** seeds of **16,116 OpenAI tokens** and **26,481 Anthropic tokens**, each observed twice. Its model inputs were three injected episodes totaling **5,400 OpenAI tokens** or **7,200 Anthropic tokens**, plus **500 task tokens**, **3,500 growth tokens per turn**, and **600 output tokens per turn**. **Documented provider price:** the dated current rows produced a cache-write/cache-read ratio of **12.5**. Those inputs gave this modelled boundary:
+
+`existing context > seed + episodes + 11.5 × written share / expected turns`
+
+**Modelled projection:** the exact boundaries show why turn count matters.
+
+| modelled case | 1 turn | 3 turns | 5 turns | 20 turns |
+| --- | ---: | ---: | ---: | ---: |
+| OpenAI warm, seed written | 269k | 104k | 71k | 34k |
+| OpenAI warm, seed read | 84k | 43k | 34k | 25k |
+| OpenAI cold | 22k | 22k | 22k | 22k |
+| Anthropic warm, seed read | 118k | 62k | 51k | 38k |
+| Anthropic cold | 34k | 34k | 34k | 34k |
+
+A 50k OpenAI threshold classified **22 of 30** warm, seed-written cells correctly and missed eight. Five misses were material: four at one turn and one at three turns. The guard therefore places one- and two-turn work on the continuation side. Two turns was inferred as the boundary between modeled one- and three-turn cases; no live two-turn break-even experiment was run.
+
+The grids cannot establish a universal break-even point. Their result depends on the project's prompt seed, episode size, cache state, input and cache-write prices, expected output, and the accuracy of the orchestrator's turn estimate. They also optimize one dispatch rather than the permanent context growth of a whole work stream.
+
+## Implemented choice mechanism
+
+Unless a paragraph carries another label, every figure in this section is an **implemented constant**.
+
+Slate divides thread choice between the orchestrator and the `thread` tool. The orchestrator retains every semantic decision.
+
+The orchestrator chooses the work stream, thread, model, effort, task, and required context. It also decides whether episodes can replace the live transcript.
+
+The tool makes one narrow economic judgement. It decides whether continuing the named thread costs more than a fresh thread seeded with named episodes.
+
+### Permission through `freshContext`
+
+The `freshContext` contract asks three separate questions:
+
+1. **Presence:** a continuation requires the argument only when `threadChoice.act` is `true`.
+2. **Validity:** every supplied value is validated on every call.
+3. **Delivery:** every continuation delivers a supplied valid value to the planner. Creation has no planner, so it delivers nothing.
+
+The twelve distinct combinations follow. Creation has one behavior for both acting settings, so its four input rows cover acting off and on.
+
+| call | acting | input | result |
+| --- | --- | --- | --- |
+| create | off or on | omitted | accepted, with nothing delivered |
+| create | off or on | malformed | tool error before creation or mutation |
+| create | off or on | `[]` | accepted and unused |
+| create | off or on | non-empty list | accepted and unused if every id names an existing episode, otherwise a tool error |
+| continue | off | omitted | accepted, with no permission delivered to the planner |
+| continue | off | malformed | tool error before mutation |
+| continue | off | `[]` | accepted, with an explicit refusal delivered to the planner |
+| continue | off | non-empty list | permission and seed episodes reach the planner if every id exists, otherwise a tool error |
+| continue | on | omitted | tool error before mutation |
+| continue | on | malformed | tool error before mutation |
+| continue | on | `[]` | accepted, with an explicit refusal delivered to the planner |
+| continue | on | non-empty list | permission and seed episodes reach the planner if every id exists, otherwise a tool error |
+
+A valid array stays within the size limit and contains only strings. Slate never treats missing permission as consent. Slate also does not judge whether the named episodes preserve enough meaning. The orchestrator must make that judgement.
+
+### Planner verdicts and order
+
+The planner returns one of four verdicts:
+
+- `continue` keeps the named thread.
+- `fresh` says the fresh option costs less.
+- `abstain` says the available inputs cannot support a choice.
+- `refused` says a rule forbids a fresh thread.
+
+Every verdict carries a machine code and a human-readable reason. Priced verdicts include both arm estimates and their warmth evidence.
+
+The planner evaluates refusals before cache evidence or prices. Missing permission, unusable tools, and a failed last dispatch can forbid a fresh thread. The dispatch boundary rejects malformed or unknown episodes before the planner runs.
+
+A dispatch without a source thread starts a new work stream. No comparison is needed because no existing prefix can be reused.
+
+The pure planner keeps work of one or two turns on the named thread. The current dispatch caller estimates at least three turns from work-stream depth.
+
+The doctrine therefore uses an empty `freshContext` for one-turn or two-turn work. It also uses an empty value when the live transcript is required.
+
+For longer work, the planner prices both arms over every expected turn. It charges the fresh arm one extra rediscovery turn.
+
+Input, cache-read, and cache-write buckets remain disjoint. Long-context billing applies independently to each arm at the exact threshold.
+
+**Documented provider price:** the dated current rows produce a cache-write to cache-read ratio of **12.5**. A false cold estimate can therefore destroy a valuable warm prefix.
+
+A tie continues the named thread. Uncertainty never becomes permission to destroy a warm prefix.
+
+### Reporting, acting, and lineage
+
+Configure the feature under `threadChoice` in the project's `.pi/slate.json` file. This example reports choices and enables automatic restarts:
+
+```json
+{
+  "threadChoice": {
+    "report": true,
+    "act": true
+  }
+}
+```
+
+**Implemented constants:** `threadChoice.report` defaults to `true`, while `threadChoice.act` defaults to `false`. The default therefore reports the verdict without moving work. Only a `fresh` verdict can move work when acting is enabled.
+
+Acting adds semantic refusals after the economic verdict. Reviewer and adversarial threads keep their live review transcripts.
+
+A successor with no episode of its own cannot restart again. It must publish new evidence before another restart.
+
+Slate writes the successor and restart lineage before the successor publishes an episode. The source record names the successor through `supersededBy`.
+
+A later dispatch to the superseded source is a tool error. The error names the successor that must continue the work stream.
+
+A restart carries the source thread's type, tools, and base route. The named `freshContext` episodes become the successor's injected context.
+
+A restart has an explicit commit point. The commit point occurs when the successor's worker session starts executing its prompt.
+
+Before the commit point, an abort or failure removes the successor and restores the source. A failure then runs the action on the source. An abort ends the action without running it again.
+
+At or after the commit point, an abort or failure never rolls the restart back. The successor keeps its lineage, and Slate reports the action outcome on that successor. Slate never repeats the committed action on the source.
+
+### Missing and stale evidence
+
+The planner abstains rather than guessing when missing or stale evidence prevents honest pricing.
+
+**Implemented constant:** the dispatch path accepts documented and measured retention evidence for 90 days. Older retention rows grant no retention window.
+
+Documented retention comes from provider sources with retrieval dates. Measured retention comes from dated local probes listed in the model profiles.
+
+Missing retention data does not prove expiry. The planner treats an unchanged route as warm when retention or elapsed time is unknown.
+
+An unknown shared-seed cache state is priced as a write. This conservative assumption makes a fresh thread look no cheaper than the evidence supports.
+
+The planner abstains when required prices or sizes are unavailable. Required sizes include the existing prefix, fresh seed, and named episodes.
+
+A failed episode write makes the live session newer than its durable measurements. The next choice drops those stale measurements and abstains.
+
+Do not preserve warmth by choosing a model or effort that cannot clear the action. Cache savings never justify lower required capability.
+
+## Cache-key sharding experiment
+
+**Measured probe, 2026-08-06.** A controlled experiment tested the implementation as shipped in this branch on the OpenAI `gpt-5.6-luna` path. Two arms used distinct long prefixes. Each arm created four worker threads sequentially in one persistent process. Treatment used the default two shards. Control set `cacheKeyEnabled: false`, so Slate installed no shared key.
+
+| measured arm | threads | input tokens | cached tokens | cached/input | worker cost |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| two-shard treatment | 4 | 119,124 | 59,496 | 0.499 | $0.01612032 |
+| disabled control | 4 | 119,116 | 0 | 0.000 | $0.02980240 |
+
+**Measured probe:** worker cost fell 45.91%. All-in cost was $0.04249825 for treatment and $0.05489782 for control, or $0.09739607 across both arms.
+
+The per-thread pattern is evidence that the provider path honors the key. The first thread on each treatment shard wrote its full prefix. The later thread on the same shard read 29,748 cached tokens. Threads with identical prefixes but different shard keys did not share cache. That pattern is inconsistent with a provider ignoring the key.
+
+The experiment is thin: four threads per arm. Treatment ran before control. Traffic passed through a local proxy, so attribution to the upstream provider is indirect. The run covers only the first dispatch. It does not cover long conversations, retention expiry, compaction, other models, other providers, or high request rates. This result supersedes every earlier cache-key measurement in the pull request record.
+
+## Limits and refresh conditions
+
+Re-measure each claim when its inputs can have changed:
+
+- **Cold transitions:** repeat controlled model and effort arms after a provider changes cache semantics, pi changes request construction, Slate changes route application, or a new model family becomes supported. A future model-change run should include controlled samples from both provider families because the current model evidence is one OpenAI event.
+- **Rediscovery:** repeat controlled pairs across several task shapes, model families, and repository sizes. Replace the one-turn charge only after the distribution is stable enough to support another policy.
+- **Two-turn guard and prices:** regenerate the grids after material changes to prompt-seed size, episode construction, provider prices, cache-write behavior, cache-key behavior, compaction, or supported model families. Validate the inferred two-turn boundary with live two-turn actions when possible. Price rows have no automatic age check, so review their provider sources whenever this projection is refreshed.
+- **Cache-key sharding:** repeat with more threads and randomized arm order after changes to key derivation, shard assignment, the disable switch, the local proxy, the OpenAI API path, or provider cache policy. Add continuation, expiry, and compaction arms before applying the first-dispatch result to those cases.
+
+This document describes decision inputs. The provider's reported usage remains the authority for the cost that actually occurred.