From c1a365ad31849aa6bd86fb7083d555398126942a Mon Sep 17 00:00:00 2001
From: Max Abouchar <maxabouchar@gmail.com>
Date: Thu, 9 Jul 2026 16:04:09 -0700
Subject: [PATCH 01/33] feat(prompts): move backend + HTML-dashboard contracts
 into built-in skills

The 15.3k-char BACKEND_GENERATION_PROMPT and 10.7k-char
VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT were re-sent in the system prompt on
every LLM call. They now ship as read-only built-in skills
(build-fullstack-backend, build-html-dashboard) served by SkillStore and are
recalled on demand; the always-sent prompt carries short mandatory recall
hints instead. create_artifact/launch_backend descriptions reinforce the
recall. System prompt drops from ~43.5k to ~22.6k chars.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 anton/core/llm/prompt_builder.py              |   4 +-
 anton/core/llm/prompts.py                     | 464 +-----------------
 .../build-fullstack-backend/SKILL.md          | 178 +++++++
 .../build-html-dashboard/SKILL.md             |  92 ++++
 anton/core/memory/skills.py                   | 115 +++--
 anton/core/tools/tool_defs.py                 |  11 +
 tests/conftest.py                             |  14 +
 tests/test_builtin_skills.py                  | 122 +++++
 uv.lock                                       |   2 +-
 9 files changed, 526 insertions(+), 476 deletions(-)
 create mode 100644 anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md
 create mode 100644 anton/core/memory/builtin_skills/build-html-dashboard/SKILL.md
 create mode 100644 tests/test_builtin_skills.py

diff --git a/anton/core/llm/prompt_builder.py b/anton/core/llm/prompt_builder.py
index 3c3d429d..fca3a57c 100644
--- a/anton/core/llm/prompt_builder.py
+++ b/anton/core/llm/prompt_builder.py
@@ -163,7 +163,9 @@ def build(
             conversation_started=conversation_started,
         )
 
-        prompt += "\n\n" + BACKEND_GENERATION_PROMPT.format(output_dir=output_dir)
+        # Short pointer only — the full backend/fullstack contract lives in the
+        # built-in `build-fullstack-backend` skill (recalled on demand).
+        prompt += "\n\n" + BACKEND_GENERATION_PROMPT
 
         tool_prompts = self._build_tool_prompts_section(tool_defs)
         if tool_prompts:
diff --git a/anton/core/llm/prompts.py b/anton/core/llm/prompts.py
index 3271504a..2b924cb6 100644
--- a/anton/core/llm/prompts.py
+++ b/anton/core/llm/prompts.py
@@ -336,164 +336,16 @@
 
 
 VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT = """\
-LIST THE INSIGHTS (terse — one line each, not an essay):
-Before coding, list the insights you want to present/convey/highlight as `1 - <chart/infographic/etc>: <insight it conveys and why it matters>..`
-Example: `1 - Line chart of weekly signups: shows growth inflection after the March launch, flags whether momentum is sustained.`
-This is a checklist, not a brief — no narrative prose, no design discussion.
-
-BUILD THE DASHBOARD — use multiple scratchpad cells, but produce ONE single self-contained HTML file:
-
-Before the first write, call `create_artifact(type="html-app", \
-name=..., description=..., primary="dashboard.html")` and use the returned \
-`<artifact_path>` for every file you write (the HTML, any sibling data files, \
-images, etc.). All paths below referring to "the output directory" mean \
-`<artifact_path>`. The final dashboard MUST be a single .html file with ALL \
-data, CSS, and JS inlined. Do NOT reference external local files (like \
-data.js) — browsers block local file:// cross-references for security \
-reasons and the dashboard will silently fail to load data.
-
-  REROUND DISCIPLINE (critical — most "round-cap exhaustion" failures we've \
-seen on real dashboards come from drifting off one or more of these):
-  1. ONE scratchpad, ONE name. Pick a name on the first cell (e.g. `dash`) \
-and reuse it for the entire build. Switching names (`build_pres` → `write_html` \
-→ `pres1` …) creates *separate isolated environments* — variables in one don't \
-exist in another — and burns rounds on recovery.
-  2. WRITE TO DISK INCREMENTALLY. Open the output `.html` once in 'w' mode, \
-then `open(path, 'a')` to append head → body skeleton → each chart section → \
-nav/JS → closing tags. Each cell appends a small chunk you can sanity-check. \
-Do NOT build a single 20KB+ HTML string in memory and write it at the end.
-  3. CAP STRING SIZE PER CELL at ~5KB. Large-string scratchpad calls are the \
-single biggest cause of silent failures (the tool occasionally drops the \
-`code` payload on oversized inputs and the cell comes back with an empty-code \
-error, which still counts against the round cap). If a section is too big, split it.
-  4. NEVER re-emit the full HTML mid-build. Append deltas, don't re-print \
-the world. Assembly is a one-line concat at the end, not a re-render of \
-everything you've written so far.
-  5. KEEP READS SMALL. To verify what landed, `os.path.getsize(path)` or \
-`open(path).read(2000)` — never `open(path).read()` on a multi-KB HTML.
-
-  SECURITY (critical): Dashboards may be published to the web. NEVER embed API keys, tokens, \
-passwords, connection strings, or any credentials in the HTML, JS, or inline data. Fetch data \
-in scratchpad cells using credentials from environment variables, then serialize only the \
-resulting data into the dashboard. If the user explicitly asks to embed a credential \
-(e.g. for a live-updating dashboard), warn them that publishing will expose it and get \
-confirmation before proceeding.
-
-  Build the parts in separate cells, then assemble at the end:
-
-  CELL 1 — Serialize data to a JS string variable (programmatic, no HTML):
-  Serialize all computed data (dataframes, metrics, KPIs) into a Python string. Build a \
-Python dict with keys like "kpis", "tables", "charts" — each containing the relevant data. \
-Convert DataFrames with df.to_dict(orient='records'). Use json.dumps(data, default=str) to \
-handle dates, Decimal, numpy types. Store as a Python variable: \
-`data_js = 'const D = ' + json_string + ';'` — do NOT write to a separate file.
-
-  CELL 2 — Build CSS + HTML structure as a Python string variable:
-  Write the HTML head (styles, CDN script tags) and body structure (header, KPIs, chart divs, \
-tabs, tables) as a Python string variable `html_body`. This cell builds the template.
-
-  CELL 3+ — Build JS chart rendering logic as Python string variables:
-  Write the JavaScript that initializes charts, populates tables, handles tabs, etc. \
-Split across multiple cells if needed to avoid token limits. Store as `js_charts` etc.
-
-  FINAL CELL — Assemble and write the HTML file:
-  Combine: `html = html_body.replace('</body>', f'<script>{{data_js}}{{js_charts}}</script></body>')` \
-or similar.
-
-  SELF-CONTAINED OUTPUT (critical):
-  Prefer inlining everything — CSS in `<style>`, JS in `<script>`, data as JS variables. \
-A single .html file is the most portable and publishable format. \
-If the dataset is very large (>100KB of JSON), you may write it to a separate .js file \
-in the SAME directory and reference it with a \
-relative `<script src="dashboard_data.js">` tag. The publisher will auto-bundle sibling \
-files referenced in the HTML. Never reference files outside the output directory.
-
-  WHY: (1) Browsers block local file:// cross-references across directories. \
-(2) Splitting the build across cells catches JS/CSS errors early — if a cell has a syntax issue \
-in a string, you'll see it before the final assembly. (3) Large datasets in single cells timeout. \
-(4) Self-contained files can be published to the web via /publish without missing assets.
-
-  PYTHON → JS STRING SAFETY (critical):
-  When building JS code inside Python strings, escape sequences get resolved by Python BEFORE \
-writing to the file. This means '\\n' in Python becomes a literal newline in the output, which \
-breaks JavaScript string literals. Rules:
-  - Use '\\\\n' in Python if you need a literal \\n in the JS output
-  - Use raw strings (r"...") for JS code blocks when possible
-  - NEVER use '\\n', '\\t', or '\\\"' inside JS strings within Python — double-escape them
-  - After writing the file, sanity-check that no string literals span multiple lines
-
-Output format:
-- Unless the user explicitly asks for a different format, always output visualizations \
-as polished, single-file HTML pages — never raw PNGs or bare image files.
-
-Visual design:
-- Make it look good by default. Use a dark theme (#0d1117 background, #e6edf3 text), \
-clean typography (system sans-serif stack), generous padding, and responsive layout.
-- ALWAYS use Apache ECharts for interactive charts. Load it via CDN: \
-`<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>`. \
-No Python dependencies needed — just write the HTML with inline JS. Use ECharts' built-in \
-dark theme: `echarts.init(dom, 'dark')`, then customize colors to match #0d1117 background.
-- NEVER use Plotly, matplotlib, or other charting libraries unless the user explicitly asks.
-
-Line smoothing (critical — smooth: true misrepresents volatile data):
-- DEFAULT: `smooth: false` on ALL line series. Straight segments between data points are \
-the honest representation — they show actual volatility, drawdowns, and inflection points.
-- EXCEPTION: Use `smooth: true` ONLY for cumulative/monotonic series (cumulative returns, \
-running totals, growth curves) where the trend matters more than point-to-point moves.
-- Decision heuristic: Does the line ever reverse direction meaningfully? If yes → smooth: false. \
-Is it a running sum, cumulative metric, or long-horizon trend? → smooth: true is acceptable.
-- Line widths: 2.5 for hero/primary lines, 1.5 for multi-line comparisons, 1 for secondary/reference lines.
-
-Chart readability (critical — labels must NEVER overlap):
-- Use `axisLabel: {{ rotate: -45 }}` or `{{ rotate: 45 }}` on crowded axes. \
-Set `grid: {{ containLabel: true }}` so labels never clip. Use `legend: {{ type: 'scroll', \
-bottom: 0 }}` to place scrollable legends below the chart. For pie/donut charts use \
-`label: {{ show: true, position: 'outside' }}` with `labelLayout: {{ hideOverlap: true }}`. \
-For bar charts with many categories, use horizontal bars (`yAxis` as category) or \
-abbreviate labels with `axisLabel: {{ formatter }}`. Always configure rich `tooltip` with \
-`formatter` functions for precise value display on hover. Use `dataZoom` for time series \
-so users can zoom into ranges.
-
-Multi-tab / multi-view dashboards (critical — charts fail silently on hidden containers):
-- ECharts, Chart.js, and Plotly all render nothing when called on a container with \
-`display: none` or 0×0 dimensions — no error, no warning, just a blank chart. \
-NEVER call `echarts.init()` inside `DOMContentLoaded` for tabs/pages that start hidden.
-- Initialize charts lazily, gated on first visibility: in the tab-click handler, \
-check a `Set` of already-rendered tabs and call the page's init function only on \
-first visit. Example pattern: \
-`const _rendered = new Set(['overview']); function showPage(name) {{ /* toggle classes */ \
-if (!_rendered.has(name)) {{ _rendered.add(name); initChartsFor(name); }} }}` \
-— only the default-visible page initializes on load.
-
-Layout and composition:
-- For non-chart visualizations (tables, reports, dashboards), write clean HTML/CSS directly. \
-Use CSS grid or flexbox. Add subtle styling: rounded corners, soft shadows, hover effects.
-- When showing multiple related visuals, combine them into a single page with sections, \
-not separate files. Ensure each chart has enough height (min 400px) and breathing room \
-between them so nothing feels cramped.
-- Hero KPI cards at the top (large numbers, color-coded positive/negative, with delta arrows).
-- Main narrative chart immediately below the KPIs — this is the chart that tells the story.
-- Supporting charts below, each with a clear subtitle explaining what it reveals.
-- Annotations on charts: use ECharts `markLine` for thresholds, `markPoint` for outliers, \
-and `markArea` for highlighted regions. A chart without annotations is a missed opportunity.
-- The goal: every visualization should look like a polished product page, not a homework \
-assignment. Think dark-mode dashboard, not Jupyter default.
-
-Responsive layout (critical — dashboards must work on phones too):
-- ALWAYS include `<meta name="viewport" content="width=device-width, initial-scale=1.0">` \
-in `<head>`. Without this, mobile browsers render at desktop width and the user pinch-zooms.
-- Multi-card sections use `grid-template-columns: repeat(auto-fit, minmax(360px, 1fr))` \
-(or 300px on dense layouts). This lets the browser reflow to single-column on narrow \
-viewports without a media query — cards stack vertically instead of getting squashed into \
-unreadable columns.
-- Chart containers use `width: 100%` and `height: min(420px, 60vh)` (NOT fixed pixel widths). \
-For each ECharts instance, register a window resize hook so it refits: \
-`window.addEventListener('resize', () => myChart.resize());` — without this, rotating a \
-phone or resizing the window leaves charts the wrong size.
-- Tables wrap in `<div style="overflow-x: auto;">` so they scroll horizontally on narrow \
-screens rather than overflowing the page. Do NOT set fixed table widths.
-- Default to one column on narrow viewports unless the user explicitly asks for a fixed \
-multi-column layout (e.g. for a printable PDF).\
+Present analysis results as HTML dashboards/reports — the user has proactive \
+dashboards enabled. Narrate the key insights in chat first (per the workflow \
+above), then build the visualization as a self-contained HTML artifact.
+
+MANDATORY: BEFORE writing any dashboard, chart, or report HTML, call \
+`recall_skill("build-html-dashboard")` and follow the loaded output contract \
+(artifact registration, file layout, charting library, theme, data embedding). \
+Do NOT build dashboard HTML from memory of those rules — recall the skill in \
+every conversation that produces one. Recalling it too often is fine; \
+skipping it is not.\
 """
 
 
@@ -514,294 +366,26 @@
 see the ARTIFACTS section above for the full contract. \
 Fallback only if `create_artifact` is unavailable: save to `{output_dir}` \
 (create it if needed). \
-Use Apache ECharts (CDN), dark theme (#0d1117), and follow standard dashboard best practices. \
-If the dataset is very large (>100KB), write it to a separate .js file in the same directory. \
-Never split CSS or chart logic into separate files — only large data payloads.\
+MANDATORY: call `recall_skill("build-html-dashboard")` BEFORE writing the HTML \
+and follow the loaded output contract (charting library, theme, file layout, \
+large-dataset handling). Recalling it too often is fine; skipping it is not.\
 """
 
 
 BACKEND_GENERATION_PROMPT = """\
 BACKEND & FULLSTACK APPLICATION GENERATION:
 
-When the user asks to build a backend service, web application with a backend, or \
-API-driven system, follow this workflow. It covers BOTH fullstack artifact types — \
-the steps are identical; only the LOCAL STATE rule (see RULES) differs.
-
-HARD CONTRACT (violating ANY of these breaks launch or deployment — full \
-explanations in the RULES of step 4):
-- The backend file is `<artifact_path>/backend.py`; the `handler` attribute \
-and the `SECRETS` dict keep exactly those names.
-- `handler = Mangum(app, lifespan="off")`.
-- ALL API routes live under `/api/*` and are registered BEFORE \
-`app.mount("/", StaticFiles(...))`.
-- The script accepts `--port` via argparse and binds to it — never hardcode a port.
-- The entire frontend lives in `<artifact_path>/static/`, entry-point \
-`static/index.html`.
-- `<artifact_path>/requirements.txt` exists and lists at least `fastapi`, \
-`mangum`, `uvicorn`.
-- Secrets are read from `SECRETS[...]` at their point of use inside routes — \
-never copied into module-level variables at import time.
-
-1. REGISTER THE ARTIFACT: Follow the universal artifact contract from the \
-ARTIFACTS section. For backend apps specifically:
-  - `type`: pick between the two fullstack types:
-    * `"fullstack-stateless-app"` — the DEFAULT. Always start here. The app \
-keeps NO local state between requests (the deployment target is stateless: \
-AWS Lambda with a read-only filesystem, see RULES and DEPLOYMENT NOTES below); \
-all persistence goes through external data sources.
-    * `"fullstack-stateful-app"` — ONLY when the app genuinely requires local \
-on-disk state between requests (e.g. a SQLite DB) AND that state cannot live \
-in an external connected data source. When in doubt, choose stateless.
-  - `primary`: set to `"static/index.html"` — the frontend ALWAYS lives in a \
-`static/` subfolder of the artifact (see steps 4 and 5 below).
-  Use the returned `<artifact_path>` for ALL subsequent writes — `backend.py` \
-and `requirements.txt` go directly in `<artifact_path>/`; ALL frontend files \
-(HTML, CSS, JS, images, fonts) go into `<artifact_path>/static/`.
-
-2. TECHNICAL SPECIFICATION (as a system analyst): Create a brief technical specification for \
-the application. The specification MUST include:
-  - Brief description of what the application does (keep it concise)
-  - Core features and requirements
-  - REST API specification in markdown format with:
-    * Endpoints and HTTP methods
-    * Request/response schemas (JSON examples)
-    * Error handling
-  - Framework: ALWAYS use FastAPI. No other framework is supported here — \
-    every backend MUST be FastAPI so it can be invoked both locally and as \
-    an AWS Lambda function via the canonical template in step 4.
-  - Key dependencies and libraries needed (in addition to the mandatory \
-    `fastapi`, `mangum`, `uvicorn` — see step 4)
-
-3. FETCH & VALIDATE SAMPLE DATA: Using the scratchpad tool:
-  - Fetch representative sample data from the user's data source (API, database, file)
-  - Get enough data to understand: structure, data types, volume, and shape
-  - Answer these questions:
-    * Is the fetched data sufficient for building the application per the spec?
-    * Can this data type be used to implement the API as designed?
-    * Do we need different/more data, or should the spec be revised?
-  - If the answer to any question is "no" — go back to step 2 and revise the technical \
-    specification based on what you learned about the actual data
-
-4. IMPLEMENT BACKEND: In a scratchpad **named exactly the artifact slug** \
-(use the `slug` returned by `create_artifact` / `open_artifact` as the scratchpad \
-name), implement the backend code. `launch_backend` runs the backend in this same \
-scratchpad's venv, so any packages you install or imports you test here will be \
-present at launch.
-
-  CANONICAL TEMPLATE (use this skeleton verbatim, add your routes inside the \
-`# === API routes ===` block). It runs unchanged both locally \
-(`python backend.py --port=NNN`) and on AWS Lambda (handler = `backend.handler`):
-
-  ```python
-  import argparse
-  import os
-  from pathlib import Path
-  from fastapi import FastAPI
-  from fastapi.middleware.cors import CORSMiddleware
-  from fastapi.staticfiles import StaticFiles
-  from mangum import Mangum
-
-  app = FastAPI()
-
-  # CORS — frontend may be served from a different origin (e.g. CloudFront/S3
-  # in front of the Lambda). Tighten `allow_origins` in production.
-  app.add_middleware(
-      CORSMiddleware,
-      allow_origins=["*"],
-      allow_methods=["*"],
-      allow_headers=["*"],
-  )
-
-  # === Secrets ===
-  # Keys are the canonical DS_<ENGINE>_<NAME>__<FIELD> env-var names. Locally
-  # each value comes from os.environ (the data vault injected it into Anton's
-  # env, which `launch_backend` inherits). In the cloud, the shared runner
-  # overlays the decrypted values onto this dict before each request. Leave
-  # SECRETS empty if the backend uses none. READ a secret by key AT ITS POINT
-  # OF USE (inside the route) — never copy a SECRETS value into a module-level
-  # variable at import time.
-  SECRETS = {{
-      # "DS_POSTGRES_PROD_DB__PASSWORD": os.environ.get("DS_POSTGRES_PROD_DB__PASSWORD"),
-  }}
-
-  # === API routes ===
-  @app.get("/api/hello")
-  async def hello():
-      # Example secret use (read at point of use, not at import):
-      #   pw = SECRETS["DS_POSTGRES_PROD_DB__PASSWORD"]
-      return {{"hello": "world"}}
-
-  # Static mount MUST come AFTER all API routes (mount at "/" catches every
-  # remaining path). Used for local preview; in Lambda, statics are served
-  # by an external service (CloudFront/S3), so this mount is harmless there.
-  STATIC_DIR = Path(__file__).parent / "static"
-  if STATIC_DIR.exists():
-      app.mount("/", StaticFiles(directory=str(STATIC_DIR), html=True), name="static")
-
-  # CLOUD entry-point. lifespan="off" is REQUIRED — there is no 
-  # long-lived process for FastAPI startup/shutdown.
-  # (Locally, `uvicorn.run(app, ...)` below serves the app directly.)
-  handler = Mangum(app, lifespan="off")
-
-  if __name__ == "__main__":
-      import uvicorn
-      parser = argparse.ArgumentParser()
-      parser.add_argument("--port", type=int, required=True)
-      args = parser.parse_args()
-      uvicorn.run(app, host="127.0.0.1", port=args.port)
-  ```
-
-  RULES (critical):
-  - Save the file as `<artifact_path>/backend.py` — the filename, the \
-`handler` attribute, and the `SECRETS` dict are load-bearing (the cloud \
-runner overlays secrets onto `backend.SECRETS` and invokes `backend.handler`). \
-Do NOT rename any of them.
-  - Keep `Mangum(app, lifespan="off")`. Without `lifespan="off"` Mangum \
-warns and may fail cold start.
-  - SECRETS: expose `SECRETS` as a module-level dict, keyed by the canonical \
-`DS_<ENGINE>_<NAME>__<FIELD>` name, with each entry initialized from \
-`os.environ.get(...)` (the local default). The cloud runner overlays the \
-decrypted values onto this same dict before each request. Read a secret AT \
-ITS POINT OF USE — `SECRETS["DS_..."]` inside the route — and NEVER hoist it \
-into a module-level variable at import time: the import runs before the \
-overlay, so the cloud value would be missed. If a credential-backed resource \
-(DB pool, API client) is needed, build it LAZILY on first request, never at \
-module level.
-  - ALL API endpoints MUST live under the `/api/*` path prefix (e.g. \
-`/api/items`, `/api/users/{{user_id}}`, `/api/search`). This is a hard \
-contract between backend and frontend: it separates API traffic from the \
-static mount at `/`, and lets edge routing (CloudFront behaviors, API \
-Gateway path-based routing) split frontend vs backend traffic by prefix \
-in production. NEVER expose routes at the root (e.g. `/items`, `/login`) — \
-they will collide with the static mount and break in deployment.
-  - API routes MUST be registered BEFORE `app.mount("/", StaticFiles(...))`. \
-FastAPI matches in registration order — a mount at `/` swallows everything \
-after it.
-  - The backend MUST accept `--port` via argparse and bind to that port. \
-NEVER hardcode the port — `launch_backend` picks a free one and passes it in.
-  - Prefer `async def` for I/O-bound routes (DB queries, external HTTP \
-calls via `httpx.AsyncClient`). Sync `def` is fine for trivial CPU work, but \
-sync blocking I/O inside an async app stalls the event loop.
-  - LOCAL STATE (the ONE rule that differs between the two fullstack types):
-    * `fullstack-stateless-app`: no local state of any kind survives a \
-request. No module-level mutable caches that matter across requests \
-(`USERS = {{}}`, `SESSIONS = []`) — in Lambda these globals may or may not \
-survive between invocations, never rely on them. Treat the filesystem as \
-read-only and non-persistent: anything written is lost between requests and \
-may fail outright depending on the host (Linux, Windows, or a read-only cloud \
-sandbox). NEVER write to `<artifact_path>` at runtime, and never rely on a \
-file surviving to a later request. If a request genuinely needs scratch \
-space, use the OS temp dir via `tempfile` and treat it as ephemeral (gone \
-the moment the request ends). ALL persistence goes through external data \
-sources.
-    * `fullstack-stateful-app`: local on-disk state (e.g. a SQLite file) IS \
-allowed — keep it in the artifact root (`<artifact_path>/`, next to \
-`backend.py`). Every other rule in this list still applies.
-  - LOGGING: `print()` and `logging.getLogger(__name__).info(...)` both go \
-to CloudWatch in Lambda and to `backend.log` locally — no extra setup needed.
-  - REQUIREMENTS: always save a `<artifact_path>/requirements.txt` with at \
-minimum:
-    ```
-    fastapi
-    mangum
-    uvicorn
-    ```
-    Add any other libraries the backend imports (one per line: `pkg` or \
-`pkg==1.2`). `launch_backend` reads this file and installs everything into \
-the slug-named scratchpad's venv before spawning the process. Only simple \
-lines are supported — `-r`, `-e`, `--index-url`, blank lines and `#` \
-comments are ignored.
-  - Do NOT start the server inside the scratchpad — use `launch_backend` in step 6.
-  - DECLARE DATASOURCES: if `backend.py` reads any `DS_<ENGINE>_<NAME>__<FIELD>` \
-env var, call `update_artifact(slug=<slug>, datasources=[...])` immediately \
-after writing the file. Pass a flat list of connection slugs (e.g. \
-`["postgres-prod_db", "hubspot-main"]`); each slug MUST match a connection \
-from the `Connected Data Sources` section of this prompt. This records the \
-deployable's credential dependencies in `metadata.json` so the artifact can \
-be redeployed with the right env vars later. Skip this call only when the \
-backend uses no `DS_*` vars at all.
-
-5. BUILD FRONTEND (if needed): In a separate scratchpad:
-  - Build a single-file HTML dashboard or web interface
-  - Include all CSS and JS inlined (no external file references)
-  - Apply the HTML build guidance from the `VISUALIZATIONS` section above \
-(single self-contained HTML file; Apache ECharts via CDN for charts; dark \
-theme #0d1117; responsive layout with a viewport meta tag). If that section \
-is not present in this prompt, follow these same defaults regardless.
-  - Save the entry-point to `<artifact_path>/static/index.html` (create the \
-`static/` subfolder if needed). ANY additional frontend assets (separate CSS, \
-JS, images, fonts, large data .js payloads) MUST also live under \
-`<artifact_path>/static/` — never at the artifact root, since the backend only \
-serves files from `static/`.
-  - All backend endpoints MUST be called under the `/api/*` prefix (matches \
-the backend route convention from step 4). The frontend never calls bare \
-paths like `/items` — always `/api/items`.
-  - API base URL is supplied via a `<meta>` tag so the same HTML works \
-locally AND when deployed with frontend and backend on different origins \
-(e.g. CloudFront/S3 + API Gateway/Lambda). Include this line in `<head>`:
-    ```html
-    <meta name="api-base" content="">
-    ```
-    Empty `content` is the local default — fetch falls back to a relative \
-path and hits the same FastAPI process that serves the page. At deploy \
-time the publisher rewrites `content=""` to the real API root \
-(e.g. `content="https://abc123.execute-api.us-east-1.amazonaws.com"`).
-  - Read the meta tag once at startup and prepend it to every API call. \
-Use this exact pattern (or an equivalent helper) — do NOT scatter \
-`document.querySelector` calls across the codebase:
-    ```js
-    const API_BASE = document.querySelector('meta[name="api-base"]')?.content || "";
-    const api = (path) => `${{API_BASE}}${{path}}`;
-    // usage: fetch(api('/api/items'))
-    ```
-  - NEVER hardcode an absolute URL in the source — no \
-`fetch('http://localhost:PORT/...')`, no `fetch('https://api.example.com/...')`, \
-no `const API_BASE = 'http://...'`. The meta tag is the ONLY place the \
-base URL is configured.
-
-6. LAUNCH THE BACKEND: Call the `launch_backend` tool with the artifact's slug:
-  - `launch_backend(slug=<slug>)` — the tool picks a free port, spawns \
-`python backend.py --port <port>` as a standalone process with `<artifact_path>` as cwd, \
-waits for readiness, writes the port into `metadata.json`, and returns \
-`{{slug, port, pid, url, log_path}}` as JSON.
-  - Uses the scratchpad named `<slug>` — created automatically on first call. If \
-`<artifact_path>/requirements.txt` exists, its packages are installed into that \
-scratchpad's venv before spawn (install output is appended to `backend.log` with a \
-banner). An install failure aborts the launch and is returned as an error string — \
-fix `requirements.txt` and retry.
-  - Backend stdout/stderr stream to `<artifact_path>/backend.log` — read it if \
-the launch fails or the API misbehaves.
-  - Do NOT call `update_artifact(port=...)` manually — `launch_backend` does it.
-  - The launched process outlives the scratchpad cell and is reaped automatically \
-when the Anton session ends.
-  - Calling `launch_backend` again for the same slug terminates the previous \
-process and starts a fresh one — use this for hot reloads after code changes.
-
-7. PREVIEW THE APPLICATION: Direct the user to the `url` returned by `launch_backend` \
-(e.g. http://127.0.0.1:54321):
-  - CRITICAL: Open that URL, NOT the HTML file from disk (file://...). \
-The backend serves the frontend at `/`, so opening the URL loads the page and \
-its `fetch()` calls land on the same origin.
-  - If the user opens the HTML file directly from disk, `fetch()` calls fail due \
-to browser CORS/file:// restrictions.
-
-DEPLOYMENT NOTES:
-- Same `backend.py` runs in two modes:
-  - LOCAL: `python backend.py --port=NNN` (used by `launch_backend`). \
-uvicorn serves the FastAPI app and the `static/` mount, frontend reachable at `/`. \
-Secrets come from the `DS_*` env vars in `SECRETS`' defaults.
-  - CLOUD: a shared runner overlays the decrypted secrets onto `backend.SECRETS` \
-and invokes `backend.handler` (the Mangum ASGI app) per request. Statics are \
-served separately (the gateway reads `static/` from object storage), so the \
-`StaticFiles` mount sits unused there — the runner only sees `/api/*` traffic.
-- Secrets ride in the backend module's `SECRETS` dict, not `os.environ` — the \
-shared cloud runner injects them per request without polluting the process env.
-- The local backend process shuts down when the Anton CLI session ends (per MVP constraints).
-
-PUBLISH OR SHARE:
-- After building, offer to preview the frontend by directing the user to the \
-URL returned by `launch_backend`
-- The backend must be running for the frontend to work
+Building a backend service, API, or fullstack web app (artifact types \
+`fullstack-stateless-app` / `fullstack-stateful-app`, launched via \
+`launch_backend`) follows a STRICT contract: a canonical FastAPI+Mangum \
+backend.py template, SECRETS handling, the `/api/*` route prefix, the \
+`static/` frontend layout, requirements.txt, and a launch/preview workflow. \
+The full procedure is NOT in this prompt — it lives in the \
+`build-fullstack-backend` skill. MANDATORY: call \
+`recall_skill("build-fullstack-backend")` BEFORE registering a fullstack \
+artifact or writing any backend code. Code written without it WILL fail \
+launch and deployment. If there is any chance the task involves a backend, \
+recall the skill first — recalling it too often is fine; skipping it is not.\
 """
 
 CONSOLIDATION_PROMPT = """\
diff --git a/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md b/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md
new file mode 100644
index 00000000..834dc592
--- /dev/null
+++ b/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md
@@ -0,0 +1,178 @@
+---
+name: build-fullstack-backend
+description: 'MANDATORY reading before writing ANY backend, API, server, or fullstack
+  application code (create_artifact types fullstack-stateless-app / fullstack-stateful-app,
+  or anything that will be launched with launch_backend). Contains the complete hard
+  contract: the canonical FastAPI+Mangum backend.py template, SECRETS handling, /api/*
+  route prefix rules, static/ frontend layout, requirements.txt, and the launch/preview
+  workflow. Building a backend without recalling this skill first WILL break launch
+  and deployment. When in doubt, recall it.'
+metadata:
+  display_name: Backend & fullstack app generation
+  provenance: builtin
+---
+BACKEND & FULLSTACK APPLICATION GENERATION:
+
+When the user asks to build a backend service, web application with a backend, or API-driven system, follow this workflow. It covers BOTH fullstack artifact types — the steps are identical; only the LOCAL STATE rule (see RULES) differs.
+
+HARD CONTRACT (violating ANY of these breaks launch or deployment — full explanations in the RULES of step 4):
+- The backend file is `<artifact_path>/backend.py`; the `handler` attribute and the `SECRETS` dict keep exactly those names.
+- `handler = Mangum(app, lifespan="off")`.
+- ALL API routes live under `/api/*` and are registered BEFORE `app.mount("/", StaticFiles(...))`.
+- The script accepts `--port` via argparse and binds to it — never hardcode a port.
+- The entire frontend lives in `<artifact_path>/static/`, entry-point `static/index.html`.
+- `<artifact_path>/requirements.txt` exists and lists at least `fastapi`, `mangum`, `uvicorn`.
+- Secrets are read from `SECRETS[...]` at their point of use inside routes — never copied into module-level variables at import time.
+
+1. REGISTER THE ARTIFACT: Follow the universal artifact contract from the ARTIFACTS section. For backend apps specifically:
+  - `type`: pick between the two fullstack types:
+    * `"fullstack-stateless-app"` — the DEFAULT. Always start here. The app keeps NO local state between requests (the deployment target is stateless: AWS Lambda with a read-only filesystem, see RULES and DEPLOYMENT NOTES below); all persistence goes through external data sources.
+    * `"fullstack-stateful-app"` — ONLY when the app genuinely requires local on-disk state between requests (e.g. a SQLite DB) AND that state cannot live in an external connected data source. When in doubt, choose stateless.
+  - `primary`: set to `"static/index.html"` — the frontend ALWAYS lives in a `static/` subfolder of the artifact (see steps 4 and 5 below).
+  Use the returned `<artifact_path>` for ALL subsequent writes — `backend.py` and `requirements.txt` go directly in `<artifact_path>/`; ALL frontend files (HTML, CSS, JS, images, fonts) go into `<artifact_path>/static/`.
+
+2. TECHNICAL SPECIFICATION (as a system analyst): Create a brief technical specification for the application. The specification MUST include:
+  - Brief description of what the application does (keep it concise)
+  - Core features and requirements
+  - REST API specification in markdown format with:
+    * Endpoints and HTTP methods
+    * Request/response schemas (JSON examples)
+    * Error handling
+  - Framework: ALWAYS use FastAPI. No other framework is supported here —     every backend MUST be FastAPI so it can be invoked both locally and as     an AWS Lambda function via the canonical template in step 4.
+  - Key dependencies and libraries needed (in addition to the mandatory     `fastapi`, `mangum`, `uvicorn` — see step 4)
+
+3. FETCH & VALIDATE SAMPLE DATA: Using the scratchpad tool:
+  - Fetch representative sample data from the user's data source (API, database, file)
+  - Get enough data to understand: structure, data types, volume, and shape
+  - Answer these questions:
+    * Is the fetched data sufficient for building the application per the spec?
+    * Can this data type be used to implement the API as designed?
+    * Do we need different/more data, or should the spec be revised?
+  - If the answer to any question is "no" — go back to step 2 and revise the technical     specification based on what you learned about the actual data
+
+4. IMPLEMENT BACKEND: In a scratchpad **named exactly the artifact slug** (use the `slug` returned by `create_artifact` / `open_artifact` as the scratchpad name), implement the backend code. `launch_backend` runs the backend in this same scratchpad's venv, so any packages you install or imports you test here will be present at launch.
+
+  CANONICAL TEMPLATE (use this skeleton verbatim, add your routes inside the `# === API routes ===` block). It runs unchanged both locally (`python backend.py --port=NNN`) and on AWS Lambda (handler = `backend.handler`):
+
+  ```python
+  import argparse
+  import os
+  from pathlib import Path
+  from fastapi import FastAPI
+  from fastapi.middleware.cors import CORSMiddleware
+  from fastapi.staticfiles import StaticFiles
+  from mangum import Mangum
+
+  app = FastAPI()
+
+  # CORS — frontend may be served from a different origin (e.g. CloudFront/S3
+  # in front of the Lambda). Tighten `allow_origins` in production.
+  app.add_middleware(
+      CORSMiddleware,
+      allow_origins=["*"],
+      allow_methods=["*"],
+      allow_headers=["*"],
+  )
+
+  # === Secrets ===
+  # Keys are the canonical DS_<ENGINE>_<NAME>__<FIELD> env-var names. Locally
+  # each value comes from os.environ (the data vault injected it into Anton's
+  # env, which `launch_backend` inherits). In the cloud, the shared runner
+  # overlays the decrypted values onto this dict before each request. Leave
+  # SECRETS empty if the backend uses none. READ a secret by key AT ITS POINT
+  # OF USE (inside the route) — never copy a SECRETS value into a module-level
+  # variable at import time.
+  SECRETS = {
+      # "DS_POSTGRES_PROD_DB__PASSWORD": os.environ.get("DS_POSTGRES_PROD_DB__PASSWORD"),
+  }
+
+  # === API routes ===
+  @app.get("/api/hello")
+  async def hello():
+      # Example secret use (read at point of use, not at import):
+      #   pw = SECRETS["DS_POSTGRES_PROD_DB__PASSWORD"]
+      return {"hello": "world"}
+
+  # Static mount MUST come AFTER all API routes (mount at "/" catches every
+  # remaining path). Used for local preview; in Lambda, statics are served
+  # by an external service (CloudFront/S3), so this mount is harmless there.
+  STATIC_DIR = Path(__file__).parent / "static"
+  if STATIC_DIR.exists():
+      app.mount("/", StaticFiles(directory=str(STATIC_DIR), html=True), name="static")
+
+  # CLOUD entry-point. lifespan="off" is REQUIRED — there is no 
+  # long-lived process for FastAPI startup/shutdown.
+  # (Locally, `uvicorn.run(app, ...)` below serves the app directly.)
+  handler = Mangum(app, lifespan="off")
+
+  if __name__ == "__main__":
+      import uvicorn
+      parser = argparse.ArgumentParser()
+      parser.add_argument("--port", type=int, required=True)
+      args = parser.parse_args()
+      uvicorn.run(app, host="127.0.0.1", port=args.port)
+  ```
+
+  RULES (critical):
+  - Save the file as `<artifact_path>/backend.py` — the filename, the `handler` attribute, and the `SECRETS` dict are load-bearing (the cloud runner overlays secrets onto `backend.SECRETS` and invokes `backend.handler`). Do NOT rename any of them.
+  - Keep `Mangum(app, lifespan="off")`. Without `lifespan="off"` Mangum warns and may fail cold start.
+  - SECRETS: expose `SECRETS` as a module-level dict, keyed by the canonical `DS_<ENGINE>_<NAME>__<FIELD>` name, with each entry initialized from `os.environ.get(...)` (the local default). The cloud runner overlays the decrypted values onto this same dict before each request. Read a secret AT ITS POINT OF USE — `SECRETS["DS_..."]` inside the route — and NEVER hoist it into a module-level variable at import time: the import runs before the overlay, so the cloud value would be missed. If a credential-backed resource (DB pool, API client) is needed, build it LAZILY on first request, never at module level.
+  - ALL API endpoints MUST live under the `/api/*` path prefix (e.g. `/api/items`, `/api/users/{user_id}`, `/api/search`). This is a hard contract between backend and frontend: it separates API traffic from the static mount at `/`, and lets edge routing (CloudFront behaviors, API Gateway path-based routing) split frontend vs backend traffic by prefix in production. NEVER expose routes at the root (e.g. `/items`, `/login`) — they will collide with the static mount and break in deployment.
+  - API routes MUST be registered BEFORE `app.mount("/", StaticFiles(...))`. FastAPI matches in registration order — a mount at `/` swallows everything after it.
+  - The backend MUST accept `--port` via argparse and bind to that port. NEVER hardcode the port — `launch_backend` picks a free one and passes it in.
+  - Prefer `async def` for I/O-bound routes (DB queries, external HTTP calls via `httpx.AsyncClient`). Sync `def` is fine for trivial CPU work, but sync blocking I/O inside an async app stalls the event loop.
+  - LOCAL STATE (the ONE rule that differs between the two fullstack types):
+    * `fullstack-stateless-app`: no local state of any kind survives a request. No module-level mutable caches that matter across requests (`USERS = {}`, `SESSIONS = []`) — in Lambda these globals may or may not survive between invocations, never rely on them. Treat the filesystem as read-only and non-persistent: anything written is lost between requests and may fail outright depending on the host (Linux, Windows, or a read-only cloud sandbox). NEVER write to `<artifact_path>` at runtime, and never rely on a file surviving to a later request. If a request genuinely needs scratch space, use the OS temp dir via `tempfile` and treat it as ephemeral (gone the moment the request ends). ALL persistence goes through external data sources.
+    * `fullstack-stateful-app`: local on-disk state (e.g. a SQLite file) IS allowed — keep it in the artifact root (`<artifact_path>/`, next to `backend.py`). Every other rule in this list still applies.
+  - LOGGING: `print()` and `logging.getLogger(__name__).info(...)` both go to CloudWatch in Lambda and to `backend.log` locally — no extra setup needed.
+  - REQUIREMENTS: always save a `<artifact_path>/requirements.txt` with at minimum:
+    ```
+    fastapi
+    mangum
+    uvicorn
+    ```
+    Add any other libraries the backend imports (one per line: `pkg` or `pkg==1.2`). `launch_backend` reads this file and installs everything into the slug-named scratchpad's venv before spawning the process. Only simple lines are supported — `-r`, `-e`, `--index-url`, blank lines and `#` comments are ignored.
+  - Do NOT start the server inside the scratchpad — use `launch_backend` in step 6.
+  - DECLARE DATASOURCES: if `backend.py` reads any `DS_<ENGINE>_<NAME>__<FIELD>` env var, call `update_artifact(slug=<slug>, datasources=[...])` immediately after writing the file. Pass a flat list of connection slugs (e.g. `["postgres-prod_db", "hubspot-main"]`); each slug MUST match a connection from the `Connected Data Sources` section of this prompt. This records the deployable's credential dependencies in `metadata.json` so the artifact can be redeployed with the right env vars later. Skip this call only when the backend uses no `DS_*` vars at all.
+
+5. BUILD FRONTEND (if needed): In a separate scratchpad:
+  - Build a single-file HTML dashboard or web interface
+  - Include all CSS and JS inlined (no external file references)
+  - Apply the HTML build guidance from the `VISUALIZATIONS` section above (single self-contained HTML file; Apache ECharts via CDN for charts; dark theme #0d1117; responsive layout with a viewport meta tag). If that section is not present in this prompt, follow these same defaults regardless.
+  - Save the entry-point to `<artifact_path>/static/index.html` (create the `static/` subfolder if needed). ANY additional frontend assets (separate CSS, JS, images, fonts, large data .js payloads) MUST also live under `<artifact_path>/static/` — never at the artifact root, since the backend only serves files from `static/`.
+  - All backend endpoints MUST be called under the `/api/*` prefix (matches the backend route convention from step 4). The frontend never calls bare paths like `/items` — always `/api/items`.
+  - API base URL is supplied via a `<meta>` tag so the same HTML works locally AND when deployed with frontend and backend on different origins (e.g. CloudFront/S3 + API Gateway/Lambda). Include this line in `<head>`:
+    ```html
+    <meta name="api-base" content="">
+    ```
+    Empty `content` is the local default — fetch falls back to a relative path and hits the same FastAPI process that serves the page. At deploy time the publisher rewrites `content=""` to the real API root (e.g. `content="https://abc123.execute-api.us-east-1.amazonaws.com"`).
+  - Read the meta tag once at startup and prepend it to every API call. Use this exact pattern (or an equivalent helper) — do NOT scatter `document.querySelector` calls across the codebase:
+    ```js
+    const API_BASE = document.querySelector('meta[name="api-base"]')?.content || "";
+    const api = (path) => `${API_BASE}${path}`;
+    // usage: fetch(api('/api/items'))
+    ```
+  - NEVER hardcode an absolute URL in the source — no `fetch('http://localhost:PORT/...')`, no `fetch('https://api.example.com/...')`, no `const API_BASE = 'http://...'`. The meta tag is the ONLY place the base URL is configured.
+
+6. LAUNCH THE BACKEND: Call the `launch_backend` tool with the artifact's slug:
+  - `launch_backend(slug=<slug>)` — the tool picks a free port, spawns `python backend.py --port <port>` as a standalone process with `<artifact_path>` as cwd, waits for readiness, writes the port into `metadata.json`, and returns `{slug, port, pid, url, log_path}` as JSON.
+  - Uses the scratchpad named `<slug>` — created automatically on first call. If `<artifact_path>/requirements.txt` exists, its packages are installed into that scratchpad's venv before spawn (install output is appended to `backend.log` with a banner). An install failure aborts the launch and is returned as an error string — fix `requirements.txt` and retry.
+  - Backend stdout/stderr stream to `<artifact_path>/backend.log` — read it if the launch fails or the API misbehaves.
+  - Do NOT call `update_artifact(port=...)` manually — `launch_backend` does it.
+  - The launched process outlives the scratchpad cell and is reaped automatically when the Anton session ends.
+  - Calling `launch_backend` again for the same slug terminates the previous process and starts a fresh one — use this for hot reloads after code changes.
+
+7. PREVIEW THE APPLICATION: Direct the user to the `url` returned by `launch_backend` (e.g. http://127.0.0.1:54321):
+  - CRITICAL: Open that URL, NOT the HTML file from disk (file://...). The backend serves the frontend at `/`, so opening the URL loads the page and its `fetch()` calls land on the same origin.
+  - If the user opens the HTML file directly from disk, `fetch()` calls fail due to browser CORS/file:// restrictions.
+
+DEPLOYMENT NOTES:
+- Same `backend.py` runs in two modes:
+  - LOCAL: `python backend.py --port=NNN` (used by `launch_backend`). uvicorn serves the FastAPI app and the `static/` mount, frontend reachable at `/`. Secrets come from the `DS_*` env vars in `SECRETS`' defaults.
+  - CLOUD: a shared runner overlays the decrypted secrets onto `backend.SECRETS` and invokes `backend.handler` (the Mangum ASGI app) per request. Statics are served separately (the gateway reads `static/` from object storage), so the `StaticFiles` mount sits unused there — the runner only sees `/api/*` traffic.
+- Secrets ride in the backend module's `SECRETS` dict, not `os.environ` — the shared cloud runner injects them per request without polluting the process env.
+- The local backend process shuts down when the Anton CLI session ends (per MVP constraints).
+
+PUBLISH OR SHARE:
+- After building, offer to preview the frontend by directing the user to the URL returned by `launch_backend`
+- The backend must be running for the frontend to work
\ No newline at end of file
diff --git a/anton/core/memory/builtin_skills/build-html-dashboard/SKILL.md b/anton/core/memory/builtin_skills/build-html-dashboard/SKILL.md
new file mode 100644
index 00000000..bbef3ef3
--- /dev/null
+++ b/anton/core/memory/builtin_skills/build-html-dashboard/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: build-html-dashboard
+description: 'MANDATORY reading before building ANY HTML dashboard, chart, plot, interactive
+  report, or browser-based visualization (create_artifact type="html-app", or the
+  frontend of a fullstack app). Contains the full HTML output contract: self-contained
+  file rules, Apache ECharts setup, dark theme, layout/design standards, and large-dataset
+  handling. Recall it BEFORE writing the first line of dashboard HTML. When in doubt,
+  recall it.'
+metadata:
+  display_name: HTML dashboard & visualization output format
+  provenance: builtin
+---
+LIST THE INSIGHTS (terse — one line each, not an essay):
+Before coding, list the insights you want to present/convey/highlight as `1 - <chart/infographic/etc>: <insight it conveys and why it matters>..`
+Example: `1 - Line chart of weekly signups: shows growth inflection after the March launch, flags whether momentum is sustained.`
+This is a checklist, not a brief — no narrative prose, no design discussion.
+
+BUILD THE DASHBOARD — use multiple scratchpad cells, but produce ONE single self-contained HTML file:
+
+Before the first write, call `create_artifact(type="html-app", name=..., description=..., primary="dashboard.html")` and use the returned `<artifact_path>` for every file you write (the HTML, any sibling data files, images, etc.). All paths below referring to "the output directory" mean `<artifact_path>`. The final dashboard MUST be a single .html file with ALL data, CSS, and JS inlined. Do NOT reference external local files (like data.js) — browsers block local file:// cross-references for security reasons and the dashboard will silently fail to load data.
+
+  REROUND DISCIPLINE (critical — most "round-cap exhaustion" failures we've seen on real dashboards come from drifting off one or more of these):
+  1. ONE scratchpad, ONE name. Pick a name on the first cell (e.g. `dash`) and reuse it for the entire build. Switching names (`build_pres` → `write_html` → `pres1` …) creates *separate isolated environments* — variables in one don't exist in another — and burns rounds on recovery.
+  2. WRITE TO DISK INCREMENTALLY. Open the output `.html` once in 'w' mode, then `open(path, 'a')` to append head → body skeleton → each chart section → nav/JS → closing tags. Each cell appends a small chunk you can sanity-check. Do NOT build a single 20KB+ HTML string in memory and write it at the end.
+  3. CAP STRING SIZE PER CELL at ~5KB. Large-string scratchpad calls are the single biggest cause of silent failures (the tool occasionally drops the `code` payload on oversized inputs and the cell comes back with an empty-code error, which still counts against the round cap). If a section is too big, split it.
+  4. NEVER re-emit the full HTML mid-build. Append deltas, don't re-print the world. Assembly is a one-line concat at the end, not a re-render of everything you've written so far.
+  5. KEEP READS SMALL. To verify what landed, `os.path.getsize(path)` or `open(path).read(2000)` — never `open(path).read()` on a multi-KB HTML.
+
+  SECURITY (critical): Dashboards may be published to the web. NEVER embed API keys, tokens, passwords, connection strings, or any credentials in the HTML, JS, or inline data. Fetch data in scratchpad cells using credentials from environment variables, then serialize only the resulting data into the dashboard. If the user explicitly asks to embed a credential (e.g. for a live-updating dashboard), warn them that publishing will expose it and get confirmation before proceeding.
+
+  Build the parts in separate cells, then assemble at the end:
+
+  CELL 1 — Serialize data to a JS string variable (programmatic, no HTML):
+  Serialize all computed data (dataframes, metrics, KPIs) into a Python string. Build a Python dict with keys like "kpis", "tables", "charts" — each containing the relevant data. Convert DataFrames with df.to_dict(orient='records'). Use json.dumps(data, default=str) to handle dates, Decimal, numpy types. Store as a Python variable: `data_js = 'const D = ' + json_string + ';'` — do NOT write to a separate file.
+
+  CELL 2 — Build CSS + HTML structure as a Python string variable:
+  Write the HTML head (styles, CDN script tags) and body structure (header, KPIs, chart divs, tabs, tables) as a Python string variable `html_body`. This cell builds the template.
+
+  CELL 3+ — Build JS chart rendering logic as Python string variables:
+  Write the JavaScript that initializes charts, populates tables, handles tabs, etc. Split across multiple cells if needed to avoid token limits. Store as `js_charts` etc.
+
+  FINAL CELL — Assemble and write the HTML file:
+  Combine: `html = html_body.replace('</body>', f'<script>{data_js}{js_charts}</script></body>')` or similar.
+
+  SELF-CONTAINED OUTPUT (critical):
+  Prefer inlining everything — CSS in `<style>`, JS in `<script>`, data as JS variables. A single .html file is the most portable and publishable format. If the dataset is very large (>100KB of JSON), you may write it to a separate .js file in the SAME directory and reference it with a relative `<script src="dashboard_data.js">` tag. The publisher will auto-bundle sibling files referenced in the HTML. Never reference files outside the output directory.
+
+  WHY: (1) Browsers block local file:// cross-references across directories. (2) Splitting the build across cells catches JS/CSS errors early — if a cell has a syntax issue in a string, you'll see it before the final assembly. (3) Large datasets in single cells timeout. (4) Self-contained files can be published to the web via /publish without missing assets.
+
+  PYTHON → JS STRING SAFETY (critical):
+  When building JS code inside Python strings, escape sequences get resolved by Python BEFORE writing to the file. This means '\n' in Python becomes a literal newline in the output, which breaks JavaScript string literals. Rules:
+  - Use '\\n' in Python if you need a literal \n in the JS output
+  - Use raw strings (r"...") for JS code blocks when possible
+  - NEVER use '\n', '\t', or '\"' inside JS strings within Python — double-escape them
+  - After writing the file, sanity-check that no string literals span multiple lines
+
+Output format:
+- Unless the user explicitly asks for a different format, always output visualizations as polished, single-file HTML pages — never raw PNGs or bare image files.
+
+Visual design:
+- Make it look good by default. Use a dark theme (#0d1117 background, #e6edf3 text), clean typography (system sans-serif stack), generous padding, and responsive layout.
+- ALWAYS use Apache ECharts for interactive charts. Load it via CDN: `<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>`. No Python dependencies needed — just write the HTML with inline JS. Use ECharts' built-in dark theme: `echarts.init(dom, 'dark')`, then customize colors to match #0d1117 background.
+- NEVER use Plotly, matplotlib, or other charting libraries unless the user explicitly asks.
+
+Line smoothing (critical — smooth: true misrepresents volatile data):
+- DEFAULT: `smooth: false` on ALL line series. Straight segments between data points are the honest representation — they show actual volatility, drawdowns, and inflection points.
+- EXCEPTION: Use `smooth: true` ONLY for cumulative/monotonic series (cumulative returns, running totals, growth curves) where the trend matters more than point-to-point moves.
+- Decision heuristic: Does the line ever reverse direction meaningfully? If yes → smooth: false. Is it a running sum, cumulative metric, or long-horizon trend? → smooth: true is acceptable.
+- Line widths: 2.5 for hero/primary lines, 1.5 for multi-line comparisons, 1 for secondary/reference lines.
+
+Chart readability (critical — labels must NEVER overlap):
+- Use `axisLabel: { rotate: -45 }` or `{ rotate: 45 }` on crowded axes. Set `grid: { containLabel: true }` so labels never clip. Use `legend: { type: 'scroll', bottom: 0 }` to place scrollable legends below the chart. For pie/donut charts use `label: { show: true, position: 'outside' }` with `labelLayout: { hideOverlap: true }`. For bar charts with many categories, use horizontal bars (`yAxis` as category) or abbreviate labels with `axisLabel: { formatter }`. Always configure rich `tooltip` with `formatter` functions for precise value display on hover. Use `dataZoom` for time series so users can zoom into ranges.
+
+Multi-tab / multi-view dashboards (critical — charts fail silently on hidden containers):
+- ECharts, Chart.js, and Plotly all render nothing when called on a container with `display: none` or 0×0 dimensions — no error, no warning, just a blank chart. NEVER call `echarts.init()` inside `DOMContentLoaded` for tabs/pages that start hidden.
+- Initialize charts lazily, gated on first visibility: in the tab-click handler, check a `Set` of already-rendered tabs and call the page's init function only on first visit. Example pattern: `const _rendered = new Set(['overview']); function showPage(name) { /* toggle classes */ if (!_rendered.has(name)) { _rendered.add(name); initChartsFor(name); } }` — only the default-visible page initializes on load.
+
+Layout and composition:
+- For non-chart visualizations (tables, reports, dashboards), write clean HTML/CSS directly. Use CSS grid or flexbox. Add subtle styling: rounded corners, soft shadows, hover effects.
+- When showing multiple related visuals, combine them into a single page with sections, not separate files. Ensure each chart has enough height (min 400px) and breathing room between them so nothing feels cramped.
+- Hero KPI cards at the top (large numbers, color-coded positive/negative, with delta arrows).
+- Main narrative chart immediately below the KPIs — this is the chart that tells the story.
+- Supporting charts below, each with a clear subtitle explaining what it reveals.
+- Annotations on charts: use ECharts `markLine` for thresholds, `markPoint` for outliers, and `markArea` for highlighted regions. A chart without annotations is a missed opportunity.
+- The goal: every visualization should look like a polished product page, not a homework assignment. Think dark-mode dashboard, not Jupyter default.
+
+Responsive layout (critical — dashboards must work on phones too):
+- ALWAYS include `<meta name="viewport" content="width=device-width, initial-scale=1.0">` in `<head>`. Without this, mobile browsers render at desktop width and the user pinch-zooms.
+- Multi-card sections use `grid-template-columns: repeat(auto-fit, minmax(360px, 1fr))` (or 300px on dense layouts). This lets the browser reflow to single-column on narrow viewports without a media query — cards stack vertically instead of getting squashed into unreadable columns.
+- Chart containers use `width: 100%` and `height: min(420px, 60vh)` (NOT fixed pixel widths). For each ECharts instance, register a window resize hook so it refits: `window.addEventListener('resize', () => myChart.resize());` — without this, rotating a phone or resizing the window leaves charts the wrong size.
+- Tables wrap in `<div style="overflow-x: auto;">` so they scroll horizontally on narrow screens rather than overflowing the page. Do NOT set fixed table widths.
+- Default to one column on narrow viewports unless the user explicitly asks for a fixed multi-column layout (e.g. for a printable PDF).
\ No newline at end of file
diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 92121672..7d94afe6 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -51,6 +51,12 @@
 
 _DEFAULT_SKILLS_ROOT = Path("~/.anton/skills").expanduser()
 
+# Read-only skills shipped inside the package. They appear in listings and
+# recall_skill lookups like user skills, but live in the codebase so every
+# install has them from the first session. A user/consolidator skill with the
+# same label shadows the built-in.
+_BUILTIN_SKILLS_ROOT = Path(__file__).parent / "builtin_skills"
+
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Data classes
@@ -266,8 +272,16 @@ class SkillStore:
     on first access via check_migrate().
     """
 
-    def __init__(self, root: Path | None = None) -> None:
+    def __init__(
+        self,
+        root: Path | None = None,
+        builtin_root: Path | None = None,
+    ) -> None:
         self.root = Path(root) if root is not None else _DEFAULT_SKILLS_ROOT
+        # Resolved at construction so tests can monkeypatch the module default.
+        self.builtin_root = (
+            Path(builtin_root) if builtin_root is not None else _BUILTIN_SKILLS_ROOT
+        )
 
     # ── internal helpers ─────────────────────────────────────────────
 
@@ -311,18 +325,26 @@ def _skill_from_dir(self, d: Path) -> Skill | None:
     # ── reading ─────────────────────────────────────────────────────
 
     def load(self, label: str) -> Skill | None:
-        """Read a single skill by label. Returns None if absent or unreadable."""
-        if not self.root.is_dir():
-            return None
-        d = self._find_dir(label)
-        if d is None:
-            return None
+        """Read a single skill by label. Returns None if absent or unreadable.
 
-        d = check_migrate(d, self.root)
-        if d is None:
+        User skills (under `root`) shadow built-in skills with the same label.
+        """
+        if self.root.is_dir():
+            d = self._find_dir(label)
+            if d is not None:
+                d = check_migrate(d, self.root)
+                if d is not None:
+                    return self._skill_from_dir(d)
+        return self._load_builtin(label)
+
+    def _load_builtin(self, label: str) -> Skill | None:
+        d = self.builtin_root / label.replace("_", "-")
+        if not d.is_dir():
             return None
-
-        return self._skill_from_dir(d)
+        skill = self._skill_from_dir(d)
+        if skill is not None:
+            skill.provenance = "builtin"
+        return skill
 
     def _load_stats(self, label: str) -> SkillStats:
         path = self._skill_dir(label) / "stats.json"
@@ -340,51 +362,76 @@ def _load_stats(self, label: str) -> SkillStats:
         )
 
     def list_all(self) -> list[Skill]:
-        """Return every loadable skill, sorted by label."""
-        if not self.root.is_dir():
-            return []
+        """Return every loadable skill (built-ins included), sorted by label."""
         out: list[Skill] = []
-        for child in sorted(self.root.iterdir()):
-            if not child.is_dir():
-                continue
-            try:
-                child = check_migrate(child, self.root)
-                if child is None:
+        if self.root.is_dir():
+            for child in sorted(self.root.iterdir()):
+                if not child.is_dir():
                     continue
-            except OSError:
+                try:
+                    child = check_migrate(child, self.root)
+                    if child is None:
+                        continue
+                except OSError:
+                    continue
+                skill = self._skill_from_dir(child)
+                if skill is not None:
+                    out.append(skill)
+        seen = {s.label for s in out}
+        for child in self._builtin_dirs():
+            if child.name in seen:
                 continue
-            skill = self._skill_from_dir(child)
+            skill = self._load_builtin(child.name)
             if skill is not None:
                 out.append(skill)
+        out.sort(key=lambda s: s.label)
         return out
 
+    def _builtin_dirs(self) -> list[Path]:
+        if not self.builtin_root.is_dir():
+            return []
+        return sorted(
+            d for d in self.builtin_root.iterdir()
+            if d.is_dir() and (d / "SKILL.md").is_file()
+        )
+
     def list_summaries(self) -> list[dict]:
         """Lightweight listing for prompt-building.
 
         Returns dicts with keys: label, name, description.
         Reads only SKILL.md frontmatter, skips the body.
         """
-        if not self.root.is_dir():
-            return []
         out: list[dict] = []
-        for child in sorted(self.root.iterdir()):
-            if not child.is_dir():
-                continue
-            try:
-                child = check_migrate(child, self.root)
-                if child is None:
+        if self.root.is_dir():
+            for child in sorted(self.root.iterdir()):
+                if not child.is_dir():
                     continue
-            except OSError:
-                continue
+                try:
+                    child = check_migrate(child, self.root)
+                    if child is None:
+                        continue
+                except OSError:
+                    continue
+                fm = parse_skill_dir(child)
+                if fm is None:
+                    continue
+
+                out.append({
+                    "label": fm.name,
+                    "name": fm.metadata.get("display_name", fm.name),
+                    "description": fm.description,
+                })
+        seen = {s["label"] for s in out}
+        for child in self._builtin_dirs():
             fm = parse_skill_dir(child)
-            if fm is None:
+            if fm is None or fm.name in seen:
                 continue
-
             out.append({
                 "label": fm.name,
                 "name": fm.metadata.get("display_name", fm.name),
                 "description": fm.description,
             })
+        out.sort(key=lambda s: s["label"])
         return out
 
     # ── writing ─────────────────────────────────────────────────────
diff --git a/anton/core/tools/tool_defs.py b/anton/core/tools/tool_defs.py
index debe6c1e..0dbdfed0 100644
--- a/anton/core/tools/tool_defs.py
+++ b/anton/core/tools/tool_defs.py
@@ -161,6 +161,12 @@ class ToolDef:
         "files — the tool returns the absolute folder path you should write "
         "into. Each artifact gets its own subfolder under `<workspace>/artifacts/`, "
         "with a `metadata.json` + `README.md` written automatically.\n\n"
+        "SKILL PREREQUISITE: `html-app` and the two fullstack types have "
+        "detailed output contracts stored as skills. If you haven't already "
+        "done so this conversation, call `recall_skill(\"build-html-dashboard\")` "
+        "before an html-app, and `recall_skill(\"build-fullstack-backend\")` "
+        "before a fullstack app — BEFORE writing any files. When unsure, "
+        "recall; skipping breaks rendering/launch.\n\n"
         "Pick `type` from the closed enum:\n"
         "- html-app: a single self-contained HTML page (charts, dashboards, demos)\n"
         "- document: a doc, report, or markdown file the user reads\n"
@@ -319,6 +325,11 @@ class ToolDef:
         "(plus any `extra_args`), waits until the server is reachable, "
         "records the port in the artifact's `metadata.json`, and returns "
         "`{slug, port, pid, url, log_path}` as JSON.\n\n"
+        "The backend MUST follow the contract in the `build-fullstack-backend` "
+        "skill (template, `--port`, `/api/*` prefix, SECRETS). If you haven't "
+        "recalled it this conversation, call "
+        "`recall_skill(\"build-fullstack-backend\")` before writing or fixing "
+        "backend code.\n\n"
         "The spawned process inherits Anton's environment, including the "
         "`DS_<ENGINE>_<NAME>__<FIELD>` variables of connected data sources.\n\n"
         "Runs in a scratchpad named exactly `<slug>` (created on first call). "
diff --git a/tests/conftest.py b/tests/conftest.py
index 0557730c..8b57c442 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -47,3 +47,17 @@ def _factory(
         )
 
     return _factory
+
+
+@pytest.fixture(autouse=True)
+def _no_builtin_skills(tmp_path_factory, monkeypatch):
+    """Point the built-in skills root at an empty dir for all tests.
+
+    Built-in skills (anton/core/memory/builtin_skills/) would otherwise appear
+    in every SkillStore listing and break empty-store assumptions. Tests that
+    exercise built-ins pass an explicit `builtin_root=` to SkillStore.
+    """
+    from anton.core.memory import skills as skills_mod
+
+    empty = tmp_path_factory.mktemp("no-builtin-skills")
+    monkeypatch.setattr(skills_mod, "_BUILTIN_SKILLS_ROOT", empty)
diff --git a/tests/test_builtin_skills.py b/tests/test_builtin_skills.py
new file mode 100644
index 00000000..3615992b
--- /dev/null
+++ b/tests/test_builtin_skills.py
@@ -0,0 +1,122 @@
+"""Built-in packaged skills: shipped content, store integration, hint-label drift."""
+
+from pathlib import Path
+
+import pytest
+
+from anton.core.memory import skills as skills_mod
+from anton.core.memory.skills import Skill, SkillStore
+
+REAL_BUILTIN_ROOT = (
+    Path(skills_mod.__file__).parent / "builtin_skills"
+)
+SHIPPED_LABELS = {"build-fullstack-backend", "build-html-dashboard"}
+
+
+@pytest.fixture()
+def store(tmp_path) -> SkillStore:
+    """Store with an empty user root and the REAL packaged builtin root."""
+    return SkillStore(root=tmp_path / "user-skills", builtin_root=REAL_BUILTIN_ROOT)
+
+
+class TestShippedSkills:
+    def test_shipped_skills_present(self, store):
+        labels = {s["label"] for s in store.list_summaries()}
+        assert SHIPPED_LABELS <= labels
+
+    def test_load_returns_full_body(self, store):
+        backend = store.load("build-fullstack-backend")
+        assert backend is not None
+        assert backend.provenance == "builtin"
+        # spot-check load-bearing contract pieces survived extraction
+        assert "Mangum(app, lifespan=\"off\")" in backend.declarative_md
+        assert "/api/" in backend.declarative_md
+        assert "requirements.txt" in backend.declarative_md
+
+        dashboard = store.load("build-html-dashboard")
+        assert dashboard is not None
+        assert dashboard.provenance == "builtin"
+        assert len(dashboard.declarative_md) > 5_000
+
+    def test_descriptions_fit_prompt_budget(self, store):
+        for summary in store.list_summaries():
+            assert len(summary["description"]) <= 1024
+
+
+class TestStoreIntegration:
+    def test_user_skill_shadows_builtin(self, store):
+        store.save(
+            Skill(
+                label="build-fullstack-backend",
+                name="My Override",
+                description="user override",
+                declarative_md="user body",
+                created_at="",
+                provenance="manual",
+            )
+        )
+        loaded = store.load("build-fullstack-backend")
+        assert loaded.provenance == "manual"
+        assert loaded.declarative_md == "user body"
+        # no duplicate rows in listings
+        labels = [s["label"] for s in store.list_summaries()]
+        assert labels.count("build-fullstack-backend") == 1
+
+    def test_delete_builtin_is_noop(self, store):
+        assert store.delete("build-fullstack-backend") is False
+        assert store.load("build-fullstack-backend") is not None
+
+    def test_increment_recommended_is_safe(self, store):
+        # stats live in the (read-only) builtin dir only for user skills;
+        # builtins must no-op without raising or writing.
+        store.increment_recommended("build-fullstack-backend")
+        assert not (REAL_BUILTIN_ROOT / "build-fullstack-backend" / "stats.json").exists()
+
+    def test_list_all_includes_builtins_sorted(self, store):
+        labels = [s.label for s in store.list_all()]
+        assert labels == sorted(labels)
+        assert SHIPPED_LABELS <= set(labels)
+
+    def test_missing_builtin_root_is_harmless(self, tmp_path):
+        s = SkillStore(root=tmp_path / "u", builtin_root=tmp_path / "nope")
+        assert s.list_summaries() == []
+        assert s.load("build-fullstack-backend") is None
+
+
+class TestHintLabelDrift:
+    """The prompts/tool descriptions reference skills by label; those labels
+    must exist as shipped built-ins or the recall hint dead-ends."""
+
+    def _referenced_labels(self, *texts: str) -> set[str]:
+        import re
+
+        out: set[str] = set()
+        for t in texts:
+            out.update(re.findall(r'recall_skill\(\\?"([a-z0-9-]+)\\?"\)', t))
+        return out
+
+    def test_prompt_hints_reference_shipped_skills(self, store):
+        from anton.core.llm.prompts import (
+            BACKEND_GENERATION_PROMPT,
+            VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT,
+            VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT,
+        )
+
+        referenced = self._referenced_labels(
+            BACKEND_GENERATION_PROMPT,
+            VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT,
+            VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT,
+        )
+        assert referenced  # hints actually exist
+        for label in referenced:
+            assert store.load(label) is not None, f"hinted skill missing: {label}"
+
+    def test_tool_descriptions_reference_shipped_skills(self, store):
+        from anton.core.tools.tool_defs import CREATE_ARTIFACT_TOOL, LAUNCH_BACKEND_TOOL
+
+        referenced = self._referenced_labels(
+            CREATE_ARTIFACT_TOOL.description, LAUNCH_BACKEND_TOOL.description
+        )
+        assert referenced
+        for label in referenced:
+            assert store.load(label) is not None, f"hinted skill missing: {label}"
diff --git a/uv.lock b/uv.lock
index 08c2abc4..e23502f3 100644
--- a/uv.lock
+++ b/uv.lock
@@ -203,7 +203,7 @@ requires-dist = [
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24" },
     { name = "pyyaml", specifier = ">=6.0" },
-    { name = "rich", specifier = ">=13.0" },
+    { name = "rich", specifier = ">=13.0,<15" },
     { name = "typer", specifier = ">=0.12.4" },
 ]
 provides-extras = ["clipboard", "dev"]

From 0af668793b8da343f901f04554b5e9bfd6a5eb2d Mon Sep 17 00:00:00 2001
From: Max Abouchar <maxabouchar@gmail.com>
Date: Fri, 10 Jul 2026 18:04:13 -0700
Subject: [PATCH 02/33] =?UTF-8?q?fix(skills):=20address=20review=20?=
 =?UTF-8?q?=E2=80=94=20shadow=20fallback,=20recall=20idempotence,=20one=20?=
 =?UTF-8?q?source=20of=20truth=20for=20HTML=20contract?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- load() falls back to the built-in when a same-label user dir exists but
  is unreadable (broken shadow no longer dead-ends a mandatory contract),
  and logs when a user skill shadows a built-in label.
- recall_skill embeds a stable marker in its payload; repeat recalls
  return a short stub while the body is still visible in history, and
  re-send the full procedure if compaction evicted it.
- build-fullstack-backend step 5 no longer references the deleted
  VISUALIZATIONS prompt section — it recalls build-html-dashboard, the
  single source of truth for dashboard HTML (inline defaults only as
  fallback).
- Hygiene: revert unrelated uv.lock resync; provenance comment/docstring/
  developer docs mention built-ins; list_all/list_summaries share one
  _iter_skill_dirs walk.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../build-fullstack-backend/SKILL.md          |   2 +-
 anton/core/memory/skills.py                   | 116 ++++++++++--------
 anton/core/tools/recall_skill.py              |  38 ++++++
 docs/docs/developer/skills-internals.md       |  14 +++
 tests/test_builtin_skills.py                  |  49 ++++++++
 uv.lock                                       |   2 +-
 6 files changed, 169 insertions(+), 52 deletions(-)

diff --git a/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md b/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md
index 834dc592..d7ba130f 100644
--- a/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md
+++ b/anton/core/memory/builtin_skills/build-fullstack-backend/SKILL.md
@@ -138,7 +138,7 @@ HARD CONTRACT (violating ANY of these breaks launch or deployment — full expla
 5. BUILD FRONTEND (if needed): In a separate scratchpad:
   - Build a single-file HTML dashboard or web interface
   - Include all CSS and JS inlined (no external file references)
-  - Apply the HTML build guidance from the `VISUALIZATIONS` section above (single self-contained HTML file; Apache ECharts via CDN for charts; dark theme #0d1117; responsive layout with a viewport meta tag). If that section is not present in this prompt, follow these same defaults regardless.
+  - MANDATORY: call `recall_skill("build-html-dashboard")` and apply its full HTML output contract to the frontend — it is the single source of truth for dashboard/chart HTML. Only if that skill cannot be recalled, fall back to these defaults: single self-contained HTML file; Apache ECharts via CDN for charts; dark theme #0d1117; responsive layout with a viewport meta tag.
   - Save the entry-point to `<artifact_path>/static/index.html` (create the `static/` subfolder if needed). ANY additional frontend assets (separate CSS, JS, images, fonts, large data .js payloads) MUST also live under `<artifact_path>/static/` — never at the artifact root, since the backend only serves files from `static/`.
   - All backend endpoints MUST be called under the `/api/*` prefix (matches the backend route convention from step 4). The frontend never calls bare paths like `/items` — always `/api/items`.
   - API base URL is supplied via a `<meta>` tag so the same HTML works locally AND when deployed with frontend and backend on different origins (e.g. CloudFront/S3 + API Gateway/Lambda). Include this line in `<head>`:
diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
index 7d94afe6..32de7011 100644
--- a/anton/core/memory/skills.py
+++ b/anton/core/memory/skills.py
@@ -14,6 +14,13 @@
     ├── scripts/           # Stage 3 — optional
     └── stats.json         # per-stage usage counters (internal sidecar)
 
+A second, read-only root ships inside the package (`builtin_skills/` next to
+this module) for skills every install must carry from the first session (e.g.
+the backend/fullstack and HTML-dashboard contracts). Built-ins appear in
+listings and `recall_skill` lookups like user skills; a user skill with the
+same label shadows the built-in (logged), and an unreadable user dir falls
+back to the built-in.
+
 Legacy format (meta.json + declarative.md) is migrated transparently on first
 read via check_migrate().
 
@@ -95,7 +102,7 @@ class Skill:
     description: str
     declarative_md: str
     created_at: str
-    provenance: str  # "manual" | "consolidator"
+    provenance: str  # "manual" | "consolidator" | "builtin"
     when_to_use: str = ""
     stage_1_present: bool = True
     stage_2_present: bool = False
@@ -327,14 +334,34 @@ def _skill_from_dir(self, d: Path) -> Skill | None:
     def load(self, label: str) -> Skill | None:
         """Read a single skill by label. Returns None if absent or unreadable.
 
-        User skills (under `root`) shadow built-in skills with the same label.
+        User skills (under `root`) shadow built-in skills with the same label;
+        the shadow is logged so a silent swap of a built-in contract is at
+        least visible. A user dir that exists but cannot be parsed falls back
+        to the built-in rather than dead-ending the label.
         """
         if self.root.is_dir():
             d = self._find_dir(label)
             if d is not None:
-                d = check_migrate(d, self.root)
-                if d is not None:
-                    return self._skill_from_dir(d)
+                try:
+                    migrated = check_migrate(d, self.root)
+                except OSError:
+                    migrated = None
+                skill = self._skill_from_dir(migrated) if migrated is not None else None
+                if skill is not None:
+                    if (self.builtin_root / skill.label).is_dir():
+                        logger.info(
+                            "skill %r: user skill shadows the built-in skill "
+                            "of the same label", skill.label,
+                        )
+                    return skill
+                fallback = self._load_builtin(label)
+                if fallback is not None:
+                    logger.warning(
+                        "skill dir %r exists but is unreadable; falling back "
+                        "to the built-in skill", label,
+                    )
+                    return fallback
+                return None
         return self._load_builtin(label)
 
     def _load_builtin(self, label: str) -> Skill | None:
@@ -364,29 +391,34 @@ def _load_stats(self, label: str) -> SkillStats:
     def list_all(self) -> list[Skill]:
         """Return every loadable skill (built-ins included), sorted by label."""
         out: list[Skill] = []
-        if self.root.is_dir():
-            for child in sorted(self.root.iterdir()):
-                if not child.is_dir():
-                    continue
-                try:
-                    child = check_migrate(child, self.root)
-                    if child is None:
-                        continue
-                except OSError:
-                    continue
-                skill = self._skill_from_dir(child)
-                if skill is not None:
-                    out.append(skill)
-        seen = {s.label for s in out}
-        for child in self._builtin_dirs():
-            if child.name in seen:
-                continue
-            skill = self._load_builtin(child.name)
+        for child in self._iter_skill_dirs():
+            skill = self._skill_from_dir(child)
             if skill is not None:
+                if child.parent == self.builtin_root:
+                    skill.provenance = "builtin"
                 out.append(skill)
         out.sort(key=lambda s: s.label)
         return out
 
+    def list_summaries(self) -> list[dict]:
+        """Lightweight listing for prompt-building.
+
+        Returns dicts with keys: label, name, description.
+        Reads only SKILL.md frontmatter, skips the body.
+        """
+        out: list[dict] = []
+        for child in self._iter_skill_dirs():
+            fm = parse_skill_dir(child)
+            if fm is None:
+                continue
+            out.append({
+                "label": fm.name,
+                "name": fm.metadata.get("display_name", fm.name),
+                "description": fm.description,
+            })
+        out.sort(key=lambda s: s["label"])
+        return out
+
     def _builtin_dirs(self) -> list[Path]:
         if not self.builtin_root.is_dir():
             return []
@@ -395,44 +427,28 @@ def _builtin_dirs(self) -> list[Path]:
             if d.is_dir() and (d / "SKILL.md").is_file()
         )
 
-    def list_summaries(self) -> list[dict]:
-        """Lightweight listing for prompt-building.
+    def _iter_skill_dirs(self) -> list[Path]:
+        """User skill dirs (migrated) plus built-in dirs not shadowed by one.
 
-        Returns dicts with keys: label, name, description.
-        Reads only SKILL.md frontmatter, skips the body.
+        Shared walk for list_all()/list_summaries(); load() resolves single
+        labels itself so it can fall back when a user dir is unreadable.
         """
-        out: list[dict] = []
+        dirs: list[Path] = []
+        seen: set[str] = set()
         if self.root.is_dir():
             for child in sorted(self.root.iterdir()):
                 if not child.is_dir():
                     continue
                 try:
                     child = check_migrate(child, self.root)
-                    if child is None:
-                        continue
                 except OSError:
                     continue
-                fm = parse_skill_dir(child)
-                if fm is None:
+                if child is None:
                     continue
-
-                out.append({
-                    "label": fm.name,
-                    "name": fm.metadata.get("display_name", fm.name),
-                    "description": fm.description,
-                })
-        seen = {s["label"] for s in out}
-        for child in self._builtin_dirs():
-            fm = parse_skill_dir(child)
-            if fm is None or fm.name in seen:
-                continue
-            out.append({
-                "label": fm.name,
-                "name": fm.metadata.get("display_name", fm.name),
-                "description": fm.description,
-            })
-        out.sort(key=lambda s: s["label"])
-        return out
+                dirs.append(child)
+                seen.add(child.name)
+        dirs.extend(d for d in self._builtin_dirs() if d.name not in seen)
+        return dirs
 
     # ── writing ─────────────────────────────────────────────────────
 
diff --git a/anton/core/tools/recall_skill.py b/anton/core/tools/recall_skill.py
index 6e1438c2..e6b7d5e0 100644
--- a/anton/core/tools/recall_skill.py
+++ b/anton/core/tools/recall_skill.py
@@ -51,12 +51,25 @@
 }
 
 
+def _recall_marker(label: str) -> str:
+    """Stable marker embedded in every recall payload.
+
+    Used to detect whether a skill's body is still present in the current
+    history: repeat recalls return a short stub instead of re-appending the
+    full body (which would be re-sent on every subsequent call), but if
+    compaction summarized the payload away the marker disappears with it and
+    the next recall re-sends the full procedure.
+    """
+    return f"# Skill recalled: `{label}`"
+
+
 def _format_skill_response(skill, *, warning: str = "") -> str:
     """Render the recall payload sent back to the LLM as a tool result."""
     parts: list[str] = []
     if warning:
         parts.append(warning.strip())
         parts.append("")  # blank line before the procedure
+    parts.append(_recall_marker(skill.label))
     parts.append(f"# Skill: {skill.name}")
     parts.append("")
     if skill.description:
@@ -68,6 +81,23 @@ def _format_skill_response(skill, *, warning: str = "") -> str:
     return "\n".join(parts)
 
 
+def _already_in_history(session, label: str) -> bool:
+    """True if a prior recall of `label` is still visible in the history."""
+    history = getattr(session, "history", None)
+    if not isinstance(history, list):
+        return False
+    marker = _recall_marker(label)
+    try:
+        import json as _json
+
+        return any(
+            marker in (m if isinstance(m, str) else _json.dumps(m, default=str))
+            for m in history
+        )
+    except Exception:  # noqa: BLE001 - never let the guard break a recall
+        return False
+
+
 async def handle_recall_skill(session: "ChatSession", tc_input: dict) -> str:
     """Look up a skill by label and return its declarative procedure."""
     label_in = (tc_input.get("label") or "").strip()
@@ -112,6 +142,14 @@ async def handle_recall_skill(session: "ChatSession", tc_input: dict) -> str:
             f"procedure below and proceed without a recalled skill."
         )
 
+    if _already_in_history(session, skill.label):
+        return (
+            f"Skill '{skill.label}' was already recalled in this conversation "
+            "— its full procedure is in your context above (look for "
+            f"'{_recall_marker(skill.label)}') and still applies. Not "
+            "re-sending the body."
+        )
+
     # Increment the recommended counter for the *resolved* label, not the
     # input. If the LLM typo'd 'csv-sumary', we credit 'csv-summary'.
     store.increment_recommended(skill.label, stage=1)
diff --git a/docs/docs/developer/skills-internals.md b/docs/docs/developer/skills-internals.md
index 157251d4..ec70b966 100644
--- a/docs/docs/developer/skills-internals.md
+++ b/docs/docs/developer/skills-internals.md
@@ -38,6 +38,20 @@ representations that **coexist** (rather than graduating between stages):
 └── stats.json         ← per-stage usage counters
 ```
 
+### Built-in skills
+
+A second, **read-only** root ships inside the package
+(`anton/core/memory/builtin_skills/<label>/SKILL.md`) for contracts every
+install must carry from the first session — currently
+`build-fullstack-backend` (the backend/fullstack generation contract) and
+`build-html-dashboard` (the HTML dashboard output contract). Built-ins appear
+in listings and `recall_skill` lookups exactly like user skills, with
+`provenance: "builtin"`. A user/consolidator skill with the same label shadows
+the built-in (the shadow is logged); if a same-label user dir exists but is
+unreadable, `load()` falls back to the built-in instead of dead-ending the
+label. Built-ins are never written to: `delete()` no-ops and stats writes are
+skipped.
+
 The three stages mirror the cortico-striatal-cerebellar gradient:
 
 - **Stage 1 (declarative)** — what the prefrontal cortex reads when first
diff --git a/tests/test_builtin_skills.py b/tests/test_builtin_skills.py
index 3615992b..6c11e9d5 100644
--- a/tests/test_builtin_skills.py
+++ b/tests/test_builtin_skills.py
@@ -120,3 +120,52 @@ def test_tool_descriptions_reference_shipped_skills(self, store):
         assert referenced
         for label in referenced:
             assert store.load(label) is not None, f"hinted skill missing: {label}"
+
+
+class TestBrokenShadowFallback:
+    def test_unreadable_user_dir_falls_back_to_builtin(self, store):
+        bad = store.root / "build-fullstack-backend"
+        bad.mkdir(parents=True)
+        (bad / "SKILL.md").write_text("not: [valid: yaml\nno frontmatter fence")
+        loaded = store.load("build-fullstack-backend")
+        assert loaded is not None
+        assert loaded.provenance == "builtin"
+        assert "Mangum" in loaded.declarative_md
+
+    def test_unreadable_dir_without_builtin_still_none(self, tmp_path):
+        s = SkillStore(root=tmp_path / "u", builtin_root=tmp_path / "nope")
+        bad = s.root / "some-skill"
+        bad.mkdir(parents=True)
+        (bad / "SKILL.md").write_text("garbage")
+        assert s.load("some-skill") is None
+
+
+class TestRecallIdempotence:
+    def _session(self, store, history):
+        from types import SimpleNamespace
+
+        return SimpleNamespace(_skill_store=store, history=history)
+
+    @pytest.mark.asyncio
+    async def test_second_recall_returns_stub(self, store):
+        from anton.core.tools.recall_skill import handle_recall_skill
+
+        history: list = []
+        session = self._session(store, history)
+        first = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        assert "## Procedure" in first
+        # simulate the tool result landing in history
+        history.append({"role": "user", "content": [{"type": "tool_result", "content": first}]})
+        second = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        assert "already recalled" in second
+        assert "## Procedure" not in second
+
+    @pytest.mark.asyncio
+    async def test_compacted_history_resends_full_body(self, store):
+        from anton.core.tools.recall_skill import handle_recall_skill
+
+        # a summary that mentions the skill but lacks the recall marker
+        history = [{"role": "user", "content": "[compacted] recalled build-html-dashboard earlier"}]
+        session = self._session(store, history)
+        result = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        assert "## Procedure" in result
diff --git a/uv.lock b/uv.lock
index e23502f3..08c2abc4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -203,7 +203,7 @@ requires-dist = [
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24" },
     { name = "pyyaml", specifier = ">=6.0" },
-    { name = "rich", specifier = ">=13.0,<15" },
+    { name = "rich", specifier = ">=13.0" },
     { name = "typer", specifier = ">=0.12.4" },
 ]
 provides-extras = ["clipboard", "dev"]

From c5db0786daa1f898b8209e44c15b86e3d316894b Mon Sep 17 00:00:00 2001
From: Max Abouchar <maxabouchar@gmail.com>
Date: Mon, 13 Jul 2026 17:49:43 -0700
Subject: [PATCH 03/33] fix(skills): stub must not satisfy the already-recalled
 check

The idempotence stub embedded the same marker _already_in_history
matches on, so a stub surviving compaction (while the full body was
evicted) suppressed re-sends forever. Detection now requires the marker
AND the procedure header in the same message (only the full payload has
both, ensure_ascii=False so the em-dash header actually matches), and
the stub carries neither. Regression tests: surviving stub and
marker-quoting summary both trigger a full re-send.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 anton/core/tools/recall_skill.py | 35 +++++++++++++++++++++++++-------
 tests/test_builtin_skills.py     | 30 +++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/anton/core/tools/recall_skill.py b/anton/core/tools/recall_skill.py
index e6b7d5e0..4231da1a 100644
--- a/anton/core/tools/recall_skill.py
+++ b/anton/core/tools/recall_skill.py
@@ -81,8 +81,18 @@ def _format_skill_response(skill, *, warning: str = "") -> str:
     return "\n".join(parts)
 
 
+_PROCEDURE_HEADER = "## Procedure (Stage 1 — declarative)"
+
+
 def _already_in_history(session, label: str) -> bool:
-    """True if a prior recall of `label` is still visible in the history."""
+    """True if a prior FULL recall of `label` is still visible in the history.
+
+    Requires the marker AND the procedure header in the same message: only
+    the full payload carries both. The stub deliberately contains neither
+    (see below) — a stub that survives compaction while the body is evicted
+    must not keep suppressing re-sends, and a summary that merely quotes the
+    marker doesn't count as the contract being present.
+    """
     history = getattr(session, "history", None)
     if not isinstance(history, list):
         return False
@@ -90,10 +100,17 @@ def _already_in_history(session, label: str) -> bool:
     try:
         import json as _json
 
-        return any(
-            marker in (m if isinstance(m, str) else _json.dumps(m, default=str))
-            for m in history
-        )
+        for m in history:
+            # ensure_ascii=False: the header contains an em-dash, which
+            # default json.dumps would escape to — and never match.
+            text = (
+                m
+                if isinstance(m, str)
+                else _json.dumps(m, default=str, ensure_ascii=False)
+            )
+            if marker in text and _PROCEDURE_HEADER in text:
+                return True
+        return False
     except Exception:  # noqa: BLE001 - never let the guard break a recall
         return False
 
@@ -143,10 +160,14 @@ async def handle_recall_skill(session: "ChatSession", tc_input: dict) -> str:
         )
 
     if _already_in_history(session, skill.label):
+        # NOTE: this stub must never contain _recall_marker() or the
+        # procedure header — otherwise a stub surviving compaction would
+        # satisfy _already_in_history forever and the full contract would
+        # never be re-sent.
         return (
             f"Skill '{skill.label}' was already recalled in this conversation "
-            "— its full procedure is in your context above (look for "
-            f"'{_recall_marker(skill.label)}') and still applies. Not "
+            "— its full procedure is in your context above, under the "
+            f"'# Skill: {skill.name}' heading, and still applies. Not "
             "re-sending the body."
         )
 
diff --git a/tests/test_builtin_skills.py b/tests/test_builtin_skills.py
index 6c11e9d5..cd84f9f8 100644
--- a/tests/test_builtin_skills.py
+++ b/tests/test_builtin_skills.py
@@ -169,3 +169,33 @@ async def test_compacted_history_resends_full_body(self, store):
         session = self._session(store, history)
         result = await handle_recall_skill(session, {"label": "build-html-dashboard"})
         assert "## Procedure" in result
+
+    @pytest.mark.asyncio
+    async def test_surviving_stub_does_not_suppress_resend(self, store):
+        """Compaction can evict the full body while keeping a newer stub.
+        The stub must not satisfy the already-recalled check, or recall
+        returns stubs forever and the contract is never re-sent."""
+        from anton.core.tools.recall_skill import handle_recall_skill
+
+        history: list = []
+        session = self._session(store, history)
+        full = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        history.append({"role": "user", "content": [{"type": "tool_result", "content": full}]})
+        stub = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        assert "already recalled" in stub
+        # simulate compaction: full body evicted, stub survives
+        history.clear()
+        history.append({"role": "user", "content": [{"type": "tool_result", "content": stub}]})
+        result = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        assert "## Procedure" in result
+
+    @pytest.mark.asyncio
+    async def test_summary_quoting_marker_does_not_suppress_resend(self, store):
+        """A compaction summary that quotes the marker text (but not the
+        procedure) must not count as the contract being present."""
+        from anton.core.tools.recall_skill import _recall_marker, handle_recall_skill
+
+        history = [{"role": "user", "content": f"[compacted] earlier: {_recall_marker('build-html-dashboard')}"}]
+        session = self._session(store, history)
+        result = await handle_recall_skill(session, {"label": "build-html-dashboard"})
+        assert "## Procedure" in result

From fd372edcd78c623bcb2c173c90555779948973b3 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Wed, 15 Jul 2026 18:17:01 +0300
Subject: [PATCH 04/33] feat(publish): add access modes (password/restricted)
 to /publish and publish_or_preview

---
 anton/chat.py                        |  61 +++++-
 anton/publish_access.py              | 308 +++++++++++++++++++++++++++
 anton/tools.py                       |  94 +++++++-
 tests/test_publish_access_resolve.py | 197 +++++++++++++++++
 tests/test_publish_api_key.py        |   7 +-
 tests/test_publish_chat_access.py    |  67 ++++++
 tests/test_publish_tool_access.py    |  90 ++++++++
 7 files changed, 804 insertions(+), 20 deletions(-)
 create mode 100644 anton/publish_access.py
 create mode 100644 tests/test_publish_access_resolve.py
 create mode 100644 tests/test_publish_chat_access.py
 create mode 100644 tests/test_publish_tool_access.py

diff --git a/anton/chat.py b/anton/chat.py
index d9f34ecd..e238c9bc 100644
--- a/anton/chat.py
+++ b/anton/chat.py
@@ -426,6 +426,11 @@ async def _handle_publish(
     import webbrowser
     from pathlib import Path
 
+    from anton.publish_access import (
+        prompt_access,
+        resolve_access,
+        resolve_publish_target,
+    )
     from anton.publisher import publish
 
     console.print()
@@ -475,7 +480,6 @@ async def _handle_publish(
     # directory is no longer scanned; users move old files into a
     # proper artifact subfolder if they still want them publishable.
     artifacts_root = Path(settings.artifacts_dir)
-    publish_index_dir = artifacts_root  # `.published.json` lives at the root
     store = ArtifactStore(artifacts_root)
 
     def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
@@ -630,20 +634,34 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
         console.print()
         return
 
-    # 3. Check if this artifact was previously published
-    published_json = publish_index_dir / ".published.json"
+    # 3. Resolve where .published.json lives (unified convention) + read prev.
+    _t, published_dir, published_key, _fs = resolve_publish_target(target, [artifacts_root])
+    published_json = published_dir / ".published.json"
     published_map = {}
     try:
         if published_json.is_file():
             published_map = json.loads(published_json.read_text())
     except Exception:
         pass
+    prev = published_map.get(published_key)
 
-    report_id = None
-    prev = published_map.get(file_key)
+    # Back-compat: legacy /publish wrote a single root map keyed by relative path.
+    if not prev:
+        legacy_json = artifacts_root / ".published.json"
+        try:
+            if legacy_json.is_file():
+                legacy_map = json.loads(legacy_json.read_text())
+                legacy_entry = legacy_map.get(file_key)
+                if isinstance(legacy_entry, dict) and legacy_entry.get("report_id"):
+                    prev = legacy_entry  # carry over report_id/url/last_md5/access
+        except Exception:
+            pass
 
+    report_id = None
     if prev and prev.get("report_id"):
-        console.print(f"  [anton.muted]Previously published: {prev.get('url', '')}[/]")
+        _mode = prev.get("mode", "public")
+        _badge = {"password": " 🔒 password", "restricted": " 👥 restricted"}.get(_mode, "")
+        console.print(f"  [anton.muted]Previously published: {prev.get('url', '')}{_badge}[/]")
         update_choice = await prompt_or_cancel(
             "  Update existing report, or publish as new?",
             choices=["update", "new", "u", "n"],
@@ -655,6 +673,18 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
             return
         if update_choice in ("update", "u"):
             report_id = prev["report_id"]
+        else:
+            prev = None  # publish as new → do not inherit versions/access
+
+    # 3b. Collect access mode from the user.
+    access = await prompt_access(
+        prompt_or_cancel, previous=prev, allow_keep=bool(report_id and prev),
+    )
+    if access is None:
+        console.print()
+        return
+
+    eff_access, pwd_version, access_version, owner_side = resolve_access(None, access, prev)
 
     # 4. Publish
     from rich.live import Live
@@ -669,6 +699,9 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
                 report_id=report_id,
                 publish_url=settings.publish_url,
                 ssl_verify=settings.minds_ssl_verify,
+                access=eff_access,
+                pwd_version=pwd_version,
+                access_version=access_version,
             )
         except Exception as e:
             import urllib.error
@@ -698,15 +731,25 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
     else:
         console.print(f"  [anton.success]Published![/]")
     console.print(f"  [link={view_url}]{view_url}[/link]")
+
+    _mode = owner_side.get("mode", "public")
+    if _mode == "password":
+        console.print("  [anton.muted]🔒 Password-protected[/]")
+    elif _mode == "restricted":
+        _n = len(owner_side.get("emails", []))
+        _org = " · org allowed" if owner_side.get("org_allowed") else ""
+        console.print(f"  [anton.muted]👥 Restricted · {_n} emails{_org}[/]")
     console.print()
 
-    # 5. Save mapping
+    # 5. Save mapping (owner-side; new unified location + key).
     if returned_report_id:
-        published_map[file_key] = {
+        entry = dict(owner_side)
+        entry.update({
             "report_id": returned_report_id,
             "url": view_url,
             "last_md5": result.get("md5", ""),
-        }
+        })
+        published_map[published_key] = entry
         try:
             published_json.write_text(json.dumps(published_map, indent=2))
         except Exception:
diff --git a/anton/publish_access.py b/anton/publish_access.py
new file mode 100644
index 00000000..5e5724c7
--- /dev/null
+++ b/anton/publish_access.py
@@ -0,0 +1,308 @@
+"""Single source of truth for publish access resolution + target resolution.
+
+Ported verbatim (behaviour-preserving) from cowork-server so that anton's
+`/publish`, anton's `publish_or_preview` tool, and cowork-server all resolve
+access, versioning, and `.published.json` location the same way.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
+_EMAIL_SPLIT_RE = re.compile(r"[\s,;]+")
+
+# Keep in sync with anton.publisher._FULLSTACK_EXCLUDED (publisher.py:42):
+# backend.log is the running backend's runtime log — excluded from the
+# published bundle there, so it must not count as user content here either.
+_HOUSEKEEPING_FILES = {"metadata.json", "README.md", "backend.log", ".published.json"}
+
+
+def normalize_emails(values) -> list[str]:
+    """Strip + lowercase + de-dupe, preserving first-seen order."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for raw in values or []:
+        email = str(raw).strip().lower()
+        if email and email not in seen:
+            seen.add(email)
+            out.append(email)
+    return out
+
+
+def resolve_access(
+    password: str | None, access: dict | None, previous: Any
+) -> tuple[dict, int, int, dict]:
+    """Resolve effective publish access from request + prior state.
+
+    Returns ``(effective_access, pwd_version, access_version, owner_side)``.
+    A request with no usable selection (empty password, or restricted with no
+    emails and no org) degrades to ``public`` — a server-side safety net for
+    programmatic callers; interactive callers must gate empty input earlier.
+    NOTE: with ``access=None`` and ``password=None`` the mode defaults to
+    ``public`` — the prior mode is NOT inherited (``previous`` only feeds the
+    version counters). Callers that want to preserve a prior non-public mode
+    must reconstruct it via ``access_from_owner_side`` first.
+    """
+    prev = previous if isinstance(previous, dict) else {}
+    password = (password or "").strip() or None
+
+    mode = (access or {}).get("mode") if access else None
+    if not mode:
+        mode = "password" if password else "public"
+
+    prev_pwd_version = prev.get("pwd_version", 0) or 0
+    prev_access_version = prev.get("access_version", 0) or 0
+    pwd_version = prev_pwd_version or 1
+    access_version = prev_access_version or 1
+
+    if mode == "password":
+        pw = ((access or {}).get("password") or password or "").strip() or None
+        if pw:
+            prev_password = prev.get("access_password")
+            pwd_version = (prev_pwd_version + 1) if pw != prev_password else (prev_pwd_version or 1)
+            owner_side = {
+                "mode": "password",
+                "requires_password": True,
+                "access_password": pw,
+                "pwd_version": pwd_version,
+            }
+            return {"mode": "password", "password": pw}, pwd_version, access_version, owner_side
+        mode = "public"  # empty password → public
+
+    if mode == "restricted":
+        emails = normalize_emails((access or {}).get("emails"))
+        org_allowed = bool((access or {}).get("org_allowed"))
+        if emails or org_allowed:
+            prev_restricted = prev.get("mode") == "restricted"
+            prev_emails = prev.get("emails") if prev_restricted else None
+            prev_org = prev.get("org_allowed") if prev_restricted else None
+            changed = (emails != prev_emails) or (org_allowed != prev_org)
+            access_version = (prev_access_version + 1) if changed else (prev_access_version or 1)
+            owner_side = {
+                "mode": "restricted",
+                "requires_password": False,
+                "emails": emails,
+                "org_allowed": org_allowed,
+                "access_version": access_version,
+            }
+            return (
+                {"mode": "restricted", "emails": emails, "org_allowed": org_allowed},
+                pwd_version,
+                access_version,
+                owner_side,
+            )
+        mode = "public"  # nothing selected → public
+
+    return {"mode": "public"}, pwd_version, access_version, {"mode": "public", "requires_password": False}
+
+
+def parse_emails(text_or_list) -> tuple[list[str], list[str]]:
+    """Split + validate emails (mirrors AccessChooser.jsx parseEmailList).
+
+    Accepts a raw string ("a@x.com, b@x.com") or a list. Returns
+    ``(valid, invalid)`` — valid are stripped/lowercased/de-duped, invalid
+    keep their original text (for a "Skipped invalid: ..." warning).
+    """
+    if isinstance(text_or_list, str):
+        tokens = _EMAIL_SPLIT_RE.split(text_or_list)
+    else:
+        tokens = [str(t) for t in (text_or_list or [])]
+    valid: list[str] = []
+    invalid: list[str] = []
+    seen: set[str] = set()
+    for tok in tokens:
+        tok = tok.strip()
+        if not tok:
+            continue
+        low = tok.lower()
+        if _EMAIL_RE.match(low):
+            if low not in seen:
+                seen.add(low)
+                valid.append(low)
+        else:
+            invalid.append(tok)
+    return valid, invalid
+
+
+def access_from_owner_side(entry: Any) -> dict:
+    """Rebuild the input access shape from a stored `.published.json` entry.
+
+    Canonicalises the inline reconstruction that used to live in
+    cowork-server's ``update_artifact``. Used by: /publish "keep", the tool's
+    "preserve previous" default, and cowork-server's update_artifact.
+    """
+    entry = entry if isinstance(entry, dict) else {}
+    mode = entry.get("mode") or ("password" if entry.get("requires_password") else "public")
+    if mode == "password":
+        return {"mode": "password", "password": entry.get("access_password", "") or ""}
+    if mode == "restricted":
+        return {
+            "mode": "restricted",
+            "emails": entry.get("emails", []) or [],
+            "org_allowed": bool(entry.get("org_allowed")),
+        }
+    return {"mode": "public"}
+
+
+def _fullstack_types() -> frozenset[str]:
+    """Artifact types anton's publisher bundles as fullstack apps.
+
+    Imported lazily to avoid a publish_access ↔ publisher import cycle."""
+    from anton.publisher import FULLSTACK_ARTIFACT_TYPES
+    return FULLSTACK_ARTIFACT_TYPES
+
+
+def _load_metadata(folder: Path) -> dict | None:
+    path = folder / "metadata.json"
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        logger.warning("Skipping artifact with unreadable metadata: %s", path, exc_info=True)
+        return None
+
+
+def _user_files(folder: Path) -> list[Path]:
+    """All non-housekeeping files inside an artifact folder, mtime desc."""
+    out: list[Path] = []
+    try:
+        for p in folder.rglob("*"):
+            if not p.is_file() or p.is_symlink():
+                continue
+            rel = p.relative_to(folder)
+            top = rel.parts[0] if rel.parts else ""
+            if top in _HOUSEKEEPING_FILES:
+                continue
+            out.append(p)
+    except OSError:
+        return []
+    try:
+        out.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    except OSError:
+        pass
+    return out
+
+
+def _pick_primary(folder: Path, files: list[Path], primary_hint: str | None = None) -> Path | None:
+    """The "open this" file for an artifact."""
+    if primary_hint:
+        try:
+            target = (folder / primary_hint).resolve()
+            target.relative_to(folder.resolve())
+            if target.is_file():
+                return target
+        except (ValueError, OSError):
+            pass
+    if not files:
+        return None
+    index = next((f for f in files if f.name == "index.html"), None)
+    if index is not None:
+        return index
+    html = next((f for f in files if f.suffix.lower() == ".html"), None)
+    if html is not None:
+        return html
+    return files[0]
+
+
+def _artifact_root_for(path: Path, container_dirs: list[Path]) -> Path:
+    """Climb from an artifact file to the folder holding its metadata.json,
+    bounded by the given container dirs (anton: [artifacts_dir]; cowork:
+    _scan_artifact_dirs()). Falls back to path.parent."""
+    containers = {str(Path(d).resolve()) for d in container_dirs}
+    current = path.parent.resolve()
+    while True:
+        if (current / "metadata.json").is_file():
+            return current
+        if str(current) in containers or current.parent == current:
+            return path.parent.resolve()
+        current = current.parent
+
+
+def resolve_publish_target(
+    artifact: Path, container_dirs: list[Path]
+) -> tuple[Path, Path, str, bool]:
+    """Decide what to publish + where `.published.json` lives + its key.
+
+    Returns (publish_target, published_dir, published_key, is_fullstack).
+    - fullstack → publish the artifact *directory*; `.published.json` at root;
+    - static → publish the single primary *file*; `.published.json` in its parent.
+    Always keyed by the primary file name.
+    """
+    if artifact.is_dir():
+        artifact_root = artifact
+        meta = _load_metadata(artifact_root) or {}
+        primary = _pick_primary(artifact_root, _user_files(artifact_root), primary_hint=meta.get("primary"))
+    else:
+        artifact_root = _artifact_root_for(artifact, container_dirs)
+        meta = _load_metadata(artifact_root) if (artifact_root / "metadata.json").is_file() else None
+        primary = artifact
+
+    if (meta or {}).get("type") in _fullstack_types():
+        key = primary.name if primary else "index.html"
+        return artifact_root, artifact_root, key, True
+    if primary:
+        return primary, primary.parent, primary.name, False
+    return artifact_root, artifact_root, "index.html", False
+
+
+async def prompt_access(prompt_fn, *, previous=None, allow_keep=False) -> dict | None:
+    """Interactively collect an access spec via a prompt_or_cancel-like coro.
+
+    Returns an input access dict ({"mode": ...}) or None if the user cancels
+    (Esc at any step). Empty password / empty restricted selection re-prompt
+    rather than silently degrading to public — parity with cowork's
+    isAccessDraftValid(). ``prompt_fn`` is injected so this is unit-testable
+    without a TTY.
+    """
+    choices = ["public", "password", "restricted"]
+    if allow_keep:
+        choices = ["keep"] + choices
+    mode = await prompt_fn(
+        "  Access",
+        choices=choices,
+        choices_display="/".join(choices),
+        default=("keep" if allow_keep else "public"),
+    )
+    if mode is None:
+        return None
+    mode = (mode or "").strip().lower() or ("keep" if allow_keep else "public")
+
+    if mode == "keep":
+        return access_from_owner_side(previous) if previous else {"mode": "public"}
+    if mode == "public":
+        return {"mode": "public"}
+
+    if mode == "password":
+        while True:
+            pw = await prompt_fn("  Password", password=True)
+            if pw is None:
+                return None
+            pw = pw.strip()
+            if pw:
+                return {"mode": "password", "password": pw}
+            # empty → re-prompt (do NOT degrade to public silently)
+
+    if mode == "restricted":
+        while True:
+            raw = await prompt_fn("  Allowed emails (comma or space separated)")
+            if raw is None:
+                return None
+            valid, _invalid = parse_emails(raw)
+            org_ans = await prompt_fn(
+                "  Allow everyone in your organization?",
+                choices=["y", "n"], choices_display="y/n", default="n",
+            )
+            if org_ans is None:
+                return None
+            org_allowed = org_ans.strip().lower() in ("y", "yes")
+            if valid or org_allowed:
+                return {"mode": "restricted", "emails": valid, "org_allowed": org_allowed}
+            # nothing selected → re-prompt
+
+    return {"mode": "public"}
diff --git a/anton/tools.py b/anton/tools.py
index 1a6ae53e..d6157c5e 100644
--- a/anton/tools.py
+++ b/anton/tools.py
@@ -423,10 +423,20 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
     from rich.live import Live
     from rich.spinner import Spinner
 
+    from anton.publish_access import (
+        access_from_owner_side,
+        resolve_access,
+        resolve_publish_target,
+    )
+    from anton.utils.prompt import prompt_or_cancel
+
     # Check if this file was previously published — reuse report_id to
-    # update instead of creating a new report every time.
-    output_dir = file_path.parent
-    published_json = output_dir / ".published.json"
+    # update instead of creating a new report every time. Resolve the
+    # .published.json location with the unified convention (shared with
+    # /publish and cowork-server) so the two entry points never disagree.
+    artifacts_root = Path(settings.artifacts_dir)
+    _t, published_dir, published_key, _fs = resolve_publish_target(file_path, [artifacts_root])
+    published_json = published_dir / ".published.json"
     published_map: dict = {}
     try:
         if published_json.is_file():
@@ -434,10 +444,43 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
     except Exception:
         pass
 
-    file_key = file_path.name
-    prev = published_map.get(file_key)
+    prev = published_map.get(published_key)
     report_id = prev.get("report_id") if isinstance(prev, dict) else None
 
+    # Resolve the access spec: explicit tool fields > preserve previous >
+    # public. NB: password input (when the user asked for a password but gave
+    # no value) is collected BEFORE the Live spinner below — prompt_toolkit
+    # and rich.Live must not run at the same time.
+    access_mode = tc_input.get("access_mode")
+    if access_mode:
+        req_access = {"mode": access_mode}
+        if access_mode == "password":
+            pw = (tc_input.get("password") or "").strip()
+            if not pw:
+                import sys
+                if sys.stdin.isatty():
+                    entered = await prompt_or_cancel("  Set a password for this report", password=True)
+                    if entered is None or not entered.strip():
+                        return "CANCELLED: publish aborted by user (no password entered)."
+                    pw = entered.strip()
+                else:
+                    return (
+                        "CANCELLED: password required but no TTY. Ask the user to run "
+                        "/publish to set a password interactively."
+                    )
+            req_access["password"] = pw
+        elif access_mode == "restricted":
+            from anton.publish_access import parse_emails
+            valid, _invalid = parse_emails(tc_input.get("emails") or [])
+            req_access["emails"] = valid
+            req_access["org_allowed"] = bool(tc_input.get("org_allowed"))
+    elif isinstance(prev, dict) and prev.get("report_id"):
+        req_access = access_from_owner_side(prev)  # preserve previous, do NOT reset to public
+    else:
+        req_access = {"mode": "public"}
+
+    eff_access, pwd_version, access_version, owner_side = resolve_access(None, req_access, prev)
+
     action_text = "  Updating..." if report_id else "  Publishing..."
     with Live(Spinner("dots", text=action_text, style="anton.cyan"), console=console, transient=True):
         try:
@@ -447,6 +490,9 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
                 report_id=report_id,
                 publish_url=settings.publish_url,
                 ssl_verify=settings.minds_ssl_verify,
+                access=eff_access,
+                pwd_version=pwd_version,
+                access_version=access_version,
             )
         except Exception as e:
             if report_id:
@@ -458,6 +504,9 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
                         api_key=settings.minds_api_key,
                         publish_url=settings.publish_url,
                         ssl_verify=settings.minds_ssl_verify,
+                        access=eff_access,
+                        pwd_version=pwd_version,
+                        access_version=access_version,
                     )
                 except Exception as e2:
                     console.print(f"  [anton.error]Publish failed: {e2}[/]")
@@ -483,13 +532,15 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
     console.print()
 
     # Persist the mapping so future publishes of the same file update
-    # instead of creating a new report.
+    # instead of creating a new report (owner-side; unified location + key).
     if returned_report_id:
-        published_map[file_key] = {
+        entry = dict(owner_side)
+        entry.update({
             "report_id": returned_report_id,
             "url": view_url,
             "last_md5": result.get("md5", ""),
-        }
+        })
+        published_map[published_key] = entry
         try:
             published_json.write_text(_json.dumps(published_map, indent=2))
         except Exception:
@@ -528,6 +579,24 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
                 "enum": ["ask", "preview", "publish"],
                 "description": "What to do: 'ask' prompts user, 'preview' opens locally, 'publish' publishes to web",
             },
+            "access_mode": {
+                "type": "string",
+                "enum": ["public", "password", "restricted"],
+                "description": "Access level. ONLY set when the user explicitly asked for it.",
+            },
+            "password": {
+                "type": "string",
+                "description": "Password for access_mode='password'. ONLY if the user stated it verbatim; otherwise leave empty and it will be asked interactively. NEVER invent one.",
+            },
+            "emails": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Allowed viewer emails for access_mode='restricted'.",
+            },
+            "org_allowed": {
+                "type": "boolean",
+                "description": "Whether the whole organization may view (access_mode='restricted').",
+            },
         },
         "required": ["file_path"],
     },
@@ -539,6 +608,13 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
         "- services (paste sites, gists, CDNs, file hosts) via scratchpad code — unless the user \n"
         "- explicitly names the service and confirms. Reading from public APIs and writing to the \n"
         "- user's connected datasources (databases, CRMs, etc.) is fine — this rule only applies to \n"
-        "- sharing generated output with the public internet."
+        "- sharing generated output with the public internet.\n"
+        "ACCESS MODE:\n"
+        "- Pass access_mode/password/emails/org_allowed ONLY if the user explicitly asked "
+        "(e.g. 'publish with password', 'share only with a@x.com').\n"
+        "- NEVER invent a password. If the user wants a password but didn't state it, set "
+        "access_mode='password' and leave password empty — the app will prompt them.\n"
+        "- If the user says nothing about access, omit these fields (public, or the artifact's "
+        "previous access is preserved on re-publish)."
     ),
 )
diff --git a/tests/test_publish_access_resolve.py b/tests/test_publish_access_resolve.py
new file mode 100644
index 00000000..2b0c795b
--- /dev/null
+++ b/tests/test_publish_access_resolve.py
@@ -0,0 +1,197 @@
+"""Tests for anton.publish_access — access resolution ported from cowork-server."""
+
+from pathlib import Path
+
+import pytest
+
+from anton.publish_access import (
+    access_from_owner_side,
+    normalize_emails,
+    parse_emails,
+    prompt_access,
+    resolve_access,
+    resolve_publish_target,
+)
+
+
+def _write(p: Path, text: str = "x") -> Path:
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(text, encoding="utf-8")
+    return p
+
+
+def test_normalize_emails_strips_lowers_dedupes():
+    assert normalize_emails([" A@x.com ", "a@x.com", "B@x.com"]) == ["a@x.com", "b@x.com"]
+    assert normalize_emails(None) == []
+
+
+def test_resolve_public_default():
+    eff, pwd_v, acc_v, owner = resolve_access(None, None, None)
+    assert eff == {"mode": "public"}
+    assert owner == {"mode": "public", "requires_password": False}
+
+
+def test_resolve_legacy_password():
+    eff, pwd_v, acc_v, owner = resolve_access("hunter2", None, None)
+    assert eff == {"mode": "password", "password": "hunter2"}
+    assert pwd_v == 1
+    assert owner["mode"] == "password"
+    assert owner["requires_password"] is True
+    assert owner["access_password"] == "hunter2"
+    assert owner["pwd_version"] == 1
+
+
+def test_resolve_empty_password_degrades_to_public():
+    eff, *_ = resolve_access("   ", None, None)
+    assert eff == {"mode": "public"}
+
+
+def test_resolve_password_change_bumps_pwd_version():
+    prev = {"mode": "password", "access_password": "old", "pwd_version": 2}
+    _, pwd_v, _, owner = resolve_access("new", None, prev)
+    assert pwd_v == 3
+    assert owner["pwd_version"] == 3
+
+
+def test_resolve_password_unchanged_keeps_pwd_version():
+    prev = {"mode": "password", "access_password": "same", "pwd_version": 2}
+    _, pwd_v, _, _ = resolve_access("same", None, prev)
+    assert pwd_v == 2
+
+
+def test_resolve_restricted_normalizes():
+    eff, _, acc_v, owner = resolve_access(
+        None, {"mode": "restricted", "emails": [" A@x.com ", "a@x.com"], "org_allowed": True}, None
+    )
+    assert eff == {"mode": "restricted", "emails": ["a@x.com"], "org_allowed": True}
+    assert acc_v == 1
+    assert owner["mode"] == "restricted"
+    assert owner["emails"] == ["a@x.com"]
+    assert owner["org_allowed"] is True
+    assert owner["access_version"] == 1
+
+
+def test_resolve_restricted_change_bumps_access_version():
+    prev = {"mode": "restricted", "emails": ["a@x.com"], "org_allowed": False, "access_version": 2}
+    _, _, acc_v, _ = resolve_access(
+        None, {"mode": "restricted", "emails": ["a@x.com", "b@x.com"], "org_allowed": False}, prev
+    )
+    assert acc_v == 3
+
+
+def test_resolve_restricted_empty_degrades_to_public():
+    eff, *_ = resolve_access(None, {"mode": "restricted", "emails": [], "org_allowed": False}, None)
+    assert eff == {"mode": "public"}
+
+
+def test_parse_emails_splits_and_validates():
+    valid, invalid = parse_emails("a@x.com, b@x.com foo@ ; c@y.io")
+    assert valid == ["a@x.com", "b@x.com", "c@y.io"]
+    assert invalid == ["foo@"]
+
+
+def test_parse_emails_accepts_list():
+    valid, invalid = parse_emails(["A@x.com", "bad"])
+    assert valid == ["a@x.com"]
+    assert invalid == ["bad"]
+
+
+def test_access_from_owner_side_password():
+    entry = {"mode": "password", "requires_password": True, "access_password": "s3cret"}
+    assert access_from_owner_side(entry) == {"mode": "password", "password": "s3cret"}
+
+
+def test_access_from_owner_side_restricted():
+    entry = {"mode": "restricted", "emails": ["a@x.com"], "org_allowed": True}
+    assert access_from_owner_side(entry) == {
+        "mode": "restricted", "emails": ["a@x.com"], "org_allowed": True,
+    }
+
+
+def test_access_from_owner_side_public_and_legacy():
+    assert access_from_owner_side({"mode": "public"}) == {"mode": "public"}
+    assert access_from_owner_side({"requires_password": True, "access_password": "p"}) == {
+        "mode": "password", "password": "p",
+    }
+    assert access_from_owner_side({}) == {"mode": "public"}
+
+
+def test_resolve_target_static_html(tmp_path):
+    root = tmp_path / "artifacts"
+    art = root / "sales"
+    _write(art / "metadata.json", '{"type": "html-report", "primary": "report.html"}')
+    _write(art / "report.html", "<html></html>")
+    target, pub_dir, key, is_fs = resolve_publish_target(art, [root])
+    assert is_fs is False
+    assert target == (art / "report.html")
+    assert pub_dir == art
+    assert key == "report.html"
+
+
+def test_resolve_target_static_addressed_by_file(tmp_path):
+    root = tmp_path / "artifacts"
+    art = root / "sales"
+    _write(art / "metadata.json", '{"type": "html-report", "primary": "report.html"}')
+    f = _write(art / "report.html", "<html></html>")
+    target, pub_dir, key, is_fs = resolve_publish_target(f, [root])
+    assert is_fs is False
+    assert key == "report.html"
+    assert pub_dir == art
+
+
+def test_resolve_target_fullstack(tmp_path):
+    root = tmp_path / "artifacts"
+    art = root / "app"
+    _write(art / "metadata.json", '{"type": "fullstack-stateless-app", "primary": "static/index.html"}')
+    _write(art / "backend.py", "print(1)")
+    _write(art / "static" / "index.html", "<html></html>")
+    target, pub_dir, key, is_fs = resolve_publish_target(art, [root])
+    assert is_fs is True
+    assert target == art
+    assert pub_dir == art
+    assert key == "index.html"
+
+
+class _FakePrompt:
+    """Feeds scripted answers to a prompt_or_cancel-compatible callable."""
+
+    def __init__(self, answers):
+        self._answers = list(answers)
+        self.asked = []
+
+    async def __call__(self, label, *, default="", password=False,
+                       choices=None, choices_display="", allow_cancel=True, default_text=""):
+        self.asked.append(label)
+        return self._answers.pop(0)
+
+
+@pytest.mark.asyncio
+async def test_prompt_access_public():
+    fp = _FakePrompt(["public"])
+    assert await prompt_access(fp) == {"mode": "public"}
+
+
+@pytest.mark.asyncio
+async def test_prompt_access_password():
+    fp = _FakePrompt(["password", "hunter2"])
+    assert await prompt_access(fp) == {"mode": "password", "password": "hunter2"}
+
+
+@pytest.mark.asyncio
+async def test_prompt_access_password_empty_reprompts_then_cancel():
+    fp = _FakePrompt(["password", "", None])
+    assert await prompt_access(fp) is None
+
+
+@pytest.mark.asyncio
+async def test_prompt_access_restricted():
+    fp = _FakePrompt(["restricted", "a@x.com, b@x.com", "y"])
+    assert await prompt_access(fp) == {
+        "mode": "restricted", "emails": ["a@x.com", "b@x.com"], "org_allowed": True,
+    }
+
+
+@pytest.mark.asyncio
+async def test_prompt_access_cancel_at_mode():
+    fp = _FakePrompt([None])
+    assert await prompt_access(fp) is None
diff --git a/tests/test_publish_api_key.py b/tests/test_publish_api_key.py
index 5e07a815..494cbdfe 100644
--- a/tests/test_publish_api_key.py
+++ b/tests/test_publish_api_key.py
@@ -58,7 +58,7 @@ async def test_401_clears_api_key(tmp_path):
     )
 
     with (
-        patch("anton.chat.prompt_or_cancel", new=AsyncMock(side_effect=["y", "wrongkey", "1"])),
+        patch("anton.chat.prompt_or_cancel", new=AsyncMock(side_effect=["y", "wrongkey", "public"])),
         patch("anton.publisher.publish", side_effect=http_401),
     ):
         await _handle_publish(console, settings, workspace, file_arg=str(html))
@@ -91,7 +91,7 @@ async def test_successful_publish_persists_key(tmp_path):
     }
 
     with (
-        patch("anton.chat.prompt_or_cancel", new=AsyncMock(side_effect=["y", "goodkey", "1"])),
+        patch("anton.chat.prompt_or_cancel", new=AsyncMock(side_effect=["y", "goodkey", "public"])),
         patch("anton.publisher.publish", return_value=publish_result),
         patch("webbrowser.open"),
     ):
@@ -117,6 +117,9 @@ async def test_401_with_existing_key_clears_it(tmp_path):
     )
 
     with (
+        # /publish now asks for an access mode before publishing; the key is
+        # already set so no key prompts fire — just answer the Access prompt.
+        patch("anton.chat.prompt_or_cancel", new=AsyncMock(side_effect=["public"])),
         patch("anton.publisher.publish", side_effect=http_401),
     ):
         await _handle_publish(console, settings, workspace, file_arg=str(html))
diff --git a/tests/test_publish_chat_access.py b/tests/test_publish_chat_access.py
new file mode 100644
index 00000000..bd4cf435
--- /dev/null
+++ b/tests/test_publish_chat_access.py
@@ -0,0 +1,67 @@
+"""_handle_publish passes the selected access through to publisher.publish."""
+
+import json
+from pathlib import Path
+from unittest import mock
+
+import pytest
+from rich.console import Console
+
+import anton.chat as chat
+
+
+def _make_artifact(tmp_path: Path) -> Path:
+    root = tmp_path / "artifacts"
+    art = root / "sales"
+    art.mkdir(parents=True)
+    (art / "metadata.json").write_text(json.dumps({
+        "schemaVersion": 1,
+        "id": "abcd1234",
+        "slug": "sales",
+        "createdAt": "2026-01-01T00:00:00Z",
+        "updatedAt": "2026-01-01T00:00:00Z",
+        "name": "Sales",
+        "description": "Sales report",
+        "type": "html-app",
+        "primary": "report.html",
+    }))
+    (art / "report.html").write_text("<html><title>Sales</title></html>")
+    return root
+
+
+@pytest.mark.asyncio
+async def test_publish_passes_password_access(tmp_path):
+    root = _make_artifact(tmp_path)
+
+    settings = mock.Mock()
+    settings.minds_api_key = "key"
+    settings.artifacts_dir = str(root)
+    settings.workspace_path = str(tmp_path)
+    settings.publish_url = "https://view.test"
+    settings.minds_ssl_verify = True
+
+    fake_publish = mock.Mock(return_value={
+        "view_url": "https://view.test/r/abc", "report_id": "abc",
+        "md5": "m", "version": 1,
+    })
+
+    async def fake_prompt_access(*a, **k):
+        return {"mode": "password", "password": "hunter2"}
+
+    # publish и prompt_access импортируются в _handle_publish на уровне функции,
+    # поэтому патчим ИСХОДНЫЕ модули — function-level импорт резолвит имя в
+    # момент вызова и подхватит патч.
+    with mock.patch("anton.publisher.publish", fake_publish), \
+         mock.patch("anton.publish_access.prompt_access", side_effect=fake_prompt_access), \
+         mock.patch("webbrowser.open"):
+        # Директорию _make_candidate публикует только для fullstack; для
+        # html-report адресуем файл (файловая ветка _make_candidate).
+        await chat._handle_publish(Console(), settings, mock.Mock(), file_arg="sales/report.html")
+
+    _, kwargs = fake_publish.call_args
+    assert kwargs["access"] == {"mode": "password", "password": "hunter2"}
+
+    # owner-side persisted next to the primary, keyed by file name
+    published = json.loads((root / "sales" / ".published.json").read_text())
+    assert published["report.html"]["mode"] == "password"
+    assert published["report.html"]["access_password"] == "hunter2"
diff --git a/tests/test_publish_tool_access.py b/tests/test_publish_tool_access.py
new file mode 100644
index 00000000..d8fcd490
--- /dev/null
+++ b/tests/test_publish_tool_access.py
@@ -0,0 +1,90 @@
+"""publish_or_preview tool: access fields + preserve-previous default."""
+
+import json
+from pathlib import Path
+from unittest import mock
+
+import pytest
+from rich.console import Console
+
+import anton.tools as tools
+
+
+def _artifact(tmp_path: Path) -> Path:
+    root = tmp_path / "artifacts"
+    art = root / "sales"
+    art.mkdir(parents=True)
+    (art / "metadata.json").write_text('{"type": "html-report", "primary": "report.html"}')
+    f = art / "report.html"
+    f.write_text("<html></html>")
+    return f
+
+
+def _session(tmp_path):
+    s = mock.Mock()
+    s._console = Console()
+    ws = mock.Mock()
+    ws.base = str(tmp_path)
+    s._workspace = ws
+    return s
+
+
+def _settings(root):
+    s = mock.Mock()
+    s.minds_api_key = "key"
+    s.publish_url = "https://view.test"
+    s.minds_ssl_verify = True
+    s.artifacts_dir = str(root)
+    return s
+
+
+@pytest.mark.asyncio
+async def test_tool_explicit_password(tmp_path):
+    f = _artifact(tmp_path)
+    fake_publish = mock.Mock(return_value={"view_url": "u", "report_id": "r", "md5": "m", "version": 1})
+    with mock.patch("anton.publisher.publish", fake_publish), \
+         mock.patch("anton.config.settings.AntonSettings", return_value=_settings(f.parent.parent)), \
+         mock.patch("webbrowser.open"):
+        out = await tools.handle_publish_or_preview(
+            _session(tmp_path),
+            {"file_path": str(f), "action": "publish",
+             "access_mode": "password", "password": "hunter2"},
+        )
+    _, kwargs = fake_publish.call_args
+    assert kwargs["access"] == {"mode": "password", "password": "hunter2"}
+    assert "Published" in out
+
+
+@pytest.mark.asyncio
+async def test_tool_preserves_previous_when_no_fields(tmp_path):
+    f = _artifact(tmp_path)
+    (f.parent / ".published.json").write_text(json.dumps({
+        "report.html": {"report_id": "r", "url": "u", "last_md5": "m",
+                          "mode": "password", "requires_password": True,
+                          "access_password": "old", "pwd_version": 1},
+    }))
+    fake_publish = mock.Mock(return_value={"view_url": "u", "report_id": "r", "md5": "m2", "version": 2})
+    with mock.patch("anton.publisher.publish", fake_publish), \
+         mock.patch("anton.config.settings.AntonSettings", return_value=_settings(f.parent.parent)), \
+         mock.patch("webbrowser.open"):
+        await tools.handle_publish_or_preview(
+            _session(tmp_path), {"file_path": str(f), "action": "publish"},
+        )
+    _, kwargs = fake_publish.call_args
+    assert kwargs["access"] == {"mode": "password", "password": "old"}  # NOT public
+
+
+@pytest.mark.asyncio
+async def test_tool_password_no_value_non_tty_cancels(tmp_path):
+    f = _artifact(tmp_path)
+    fake_publish = mock.Mock()
+    with mock.patch("anton.publisher.publish", fake_publish), \
+         mock.patch("anton.config.settings.AntonSettings", return_value=_settings(f.parent.parent)), \
+         mock.patch("sys.stdin") as stdin:
+        stdin.isatty.return_value = False
+        out = await tools.handle_publish_or_preview(
+            _session(tmp_path),
+            {"file_path": str(f), "action": "publish", "access_mode": "password"},
+        )
+    assert "CANCELLED" in out
+    fake_publish.assert_not_called()

From 18cf596cdd51e527d16e0fd98ff10f94e3909af8 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Thu, 16 Jul 2026 09:03:16 -0700
Subject: [PATCH 05/33] fix(scratchpad): force UTF-8 so non-UTF-8 host locales
 don't crash the scratchpad (ENG-824)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On a host whose default code page isn't UTF-8 (GBK/cp936 on Chinese Windows,
and likely other CJK locales) LocalScratchpadRuntime crashed before any cell
ran: `_BOOT_SCRIPT_PATH.read_text()` decoded the boot script (which contains
`…`/`—`) with the locale default → `'gbk' codec can't decode byte 0xa6`.

Fix, at every parent↔child byte boundary + interpreter-level:
- Read/write the boot script as UTF-8 (read_text/encode).
- Force UTF-8 mode in the subprocess env (PYTHONUTF8=1 / PYTHONIOENCODING=utf-8,
  via _utf8_env, setdefault so an explicit override wins) — so the child's
  file I/O and stdio are UTF-8 regardless of host locale.
- Decode/encode the cell payload + stdout/install output as UTF-8
  (errors="replace" on display output so odd bytes never crash the reader).

Non-breaking: this content is already UTF-8 on the wire, so UTF-8-default hosts
(macOS/Linux/English Windows) are unchanged; it only turns the hard crash into
working on non-UTF-8-locale hosts.

Tests: _utf8_env forces UTF-8 / respects overrides; the boot script must be
read as UTF-8 (its bytes are not GBK-decodable). 96 existing scratchpad tests
still pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/backends/local.py  | 37 ++++++++++++++++++++++++++++-------
 tests/test_scratchpad_utf8.py | 34 ++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 7 deletions(-)
 create mode 100644 tests/test_scratchpad_utf8.py

diff --git a/anton/core/backends/local.py b/anton/core/backends/local.py
index 91beff5c..e159bac6 100644
--- a/anton/core/backends/local.py
+++ b/anton/core/backends/local.py
@@ -22,6 +22,24 @@
 from anton.core.backends.utils import compute_timeouts
 
 _BOOT_SCRIPT_PATH = Path(__file__).parent / "scratchpad_boot.py"
+
+
+def _utf8_env(base: "os._Environ[str] | dict[str, str]") -> dict[str, str]:
+    """A copy of ``base`` with Python UTF-8 mode forced for the scratchpad
+    subprocess.
+
+    The parent may run under a non-UTF-8 host locale (e.g. GBK/cp936 on
+    Chinese Windows). Without this, the child interpreter inherits that code
+    page and every ``open()``/``print()``/stdio defaults to it — so reading the
+    boot script or emitting non-ASCII output crashes (ENG-824). ``setdefault``
+    so an explicit operator override still wins.
+    """
+    env = dict(base)
+    env.setdefault("PYTHONUTF8", "1")
+    env.setdefault("PYTHONIOENCODING", "utf-8")
+    return env
+
+
 _MAX_OUTPUT = 10_000
 
 
@@ -199,7 +217,7 @@ def _verify_venv_python(self) -> bool:
                 capture_output=True,
                 timeout=5,
             )
-            return result.returncode == 0 and "ok" in result.stdout.decode()
+            return result.returncode == 0 and "ok" in result.stdout.decode("utf-8", errors="replace")
         except Exception:
             return False
 
@@ -324,13 +342,18 @@ async def start(self) -> None:
         """Write the boot script to a temp file and launch the subprocess."""
         self._ensure_venv()
 
-        boot_code = _BOOT_SCRIPT_PATH.read_text()
+        # Read/write the boot script as UTF-8 explicitly: it contains non-ASCII
+        # (…, —), so a host-locale-default read (e.g. GBK on Chinese Windows)
+        # crashes with a codec error before the scratchpad can start (ENG-824).
+        boot_code = _BOOT_SCRIPT_PATH.read_text(encoding="utf-8")
         fd, path = tempfile.mkstemp(suffix=".py", prefix="anton_scratchpad_")
-        os.write(fd, boot_code.encode())
+        os.write(fd, boot_code.encode("utf-8"))
         os.close(fd)
         self._boot_path = path
 
-        env = os.environ.copy()
+        # Force UTF-8 mode in the child so its I/O never depends on the host
+        # code page (ENG-824).
+        env = _utf8_env(os.environ)
         if self._coding_model:
             env["ANTON_SCRATCHPAD_MODEL"] = self._coding_model
         if self._coding_provider:
@@ -490,7 +513,7 @@ async def execute_streaming(
             return
 
         payload = code + "\n" + CELL_DELIM + "\n"
-        self._proc.stdin.write(payload.encode())  # type: ignore[union-attr]
+        self._proc.stdin.write(payload.encode("utf-8"))  # type: ignore[union-attr]
         await self._proc.stdin.drain()  # type: ignore[union-attr]
 
         total_timeout, inactivity_timeout = compute_timeouts(estimated_seconds)
@@ -622,7 +645,7 @@ async def _read_result(
                 }
                 return
 
-            line = raw.decode().rstrip("\r\n")
+            line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
 
             if line.startswith(PROGRESS_MARKER):
                 current_inactivity = max(
@@ -685,7 +708,7 @@ async def install_packages(self, packages: list[str]) -> str:
             proc.kill()
             await proc.wait()
             return f"Install timed out after {_install_timeout}s."
-        output = stdout.decode()
+        output = stdout.decode("utf-8", errors="replace")
         if proc.returncode != 0:
             return f"Install failed (exit {proc.returncode}):\n{output}"
         for p in needed:
diff --git a/tests/test_scratchpad_utf8.py b/tests/test_scratchpad_utf8.py
new file mode 100644
index 00000000..18dc63b4
--- /dev/null
+++ b/tests/test_scratchpad_utf8.py
@@ -0,0 +1,34 @@
+"""ENG-824 regression: the scratchpad must be UTF-8-safe regardless of the
+host locale code page (e.g. GBK/cp936 on Chinese Windows)."""
+
+from __future__ import annotations
+
+import pytest
+
+import anton.core.backends.local as local
+
+
+def test_utf8_env_forces_utf8_mode():
+    env = local._utf8_env({"FOO": "bar"})
+    assert env["PYTHONUTF8"] == "1"
+    assert env["PYTHONIOENCODING"] == "utf-8"
+    assert env["FOO"] == "bar"  # base is preserved
+
+
+def test_utf8_env_respects_explicit_override():
+    # setdefault: an operator who deliberately set these keeps them.
+    env = local._utf8_env({"PYTHONUTF8": "0", "PYTHONIOENCODING": "latin-1"})
+    assert env["PYTHONUTF8"] == "0"
+    assert env["PYTHONIOENCODING"] == "latin-1"
+
+
+def test_boot_script_must_be_read_as_utf8():
+    # The boot script contains non-ASCII (…, —). Reading it with a non-UTF-8
+    # host-locale default (GBK on Chinese Windows) throws a UnicodeDecodeError
+    # before the scratchpad can start — the exact ENG-824 crash. Guard that (a)
+    # UTF-8 decodes cleanly and (b) the content genuinely needs UTF-8, so a
+    # locale-default read is unsafe and must not regress.
+    raw = local._BOOT_SCRIPT_PATH.read_bytes()
+    raw.decode("utf-8")  # the fix: explicit UTF-8 succeeds
+    with pytest.raises(UnicodeDecodeError):
+        raw.decode("gbk")  # a GBK-locale default read would crash

From 0dc7261365f6b046f8e8cd418578e5f3d7da4519 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Thu, 16 Jul 2026 09:09:21 -0700
Subject: [PATCH 06/33] fix(scratchpad): drop PYTHONIOENCODING, keep only
 PYTHONUTF8 (self-review, ENG-824)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-review: a bare PYTHONIOENCODING=utf-8 downgrades the child's stdio error
handler from surrogateescape → strict (verified), which adds nothing over
PYTHONUTF8=1 (already utf-8 for open()/filesystem/stdio) and re-introduces a
strict-encode crash on exotic output. Keep only PYTHONUTF8=1.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/backends/local.py  | 7 ++++++-
 tests/test_scratchpad_utf8.py | 9 +++++----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/anton/core/backends/local.py b/anton/core/backends/local.py
index e159bac6..0d5f5baa 100644
--- a/anton/core/backends/local.py
+++ b/anton/core/backends/local.py
@@ -33,10 +33,15 @@ def _utf8_env(base: "os._Environ[str] | dict[str, str]") -> dict[str, str]:
     page and every ``open()``/``print()``/stdio defaults to it — so reading the
     boot script or emitting non-ASCII output crashes (ENG-824). ``setdefault``
     so an explicit operator override still wins.
+
+    Only ``PYTHONUTF8`` is set: UTF-8 mode already makes open()/filesystem/stdio
+    UTF-8 with the lenient ``surrogateescape`` stdio handler. We deliberately do
+    NOT also set ``PYTHONIOENCODING`` — a bare value downgrades the stdio error
+    handler back to ``strict`` (verified), which would re-introduce a crash on
+    exotic output rather than round-tripping it.
     """
     env = dict(base)
     env.setdefault("PYTHONUTF8", "1")
-    env.setdefault("PYTHONIOENCODING", "utf-8")
     return env
 
 
diff --git a/tests/test_scratchpad_utf8.py b/tests/test_scratchpad_utf8.py
index 18dc63b4..bc2040c4 100644
--- a/tests/test_scratchpad_utf8.py
+++ b/tests/test_scratchpad_utf8.py
@@ -11,15 +11,16 @@
 def test_utf8_env_forces_utf8_mode():
     env = local._utf8_env({"FOO": "bar"})
     assert env["PYTHONUTF8"] == "1"
-    assert env["PYTHONIOENCODING"] == "utf-8"
     assert env["FOO"] == "bar"  # base is preserved
+    # Deliberately NOT set — a bare PYTHONIOENCODING makes stdio strict, which
+    # would re-introduce a crash on exotic output (UTF-8 mode already covers it).
+    assert "PYTHONIOENCODING" not in env
 
 
 def test_utf8_env_respects_explicit_override():
-    # setdefault: an operator who deliberately set these keeps them.
-    env = local._utf8_env({"PYTHONUTF8": "0", "PYTHONIOENCODING": "latin-1"})
+    # setdefault: an operator who deliberately set UTF-8 mode off keeps it.
+    env = local._utf8_env({"PYTHONUTF8": "0"})
     assert env["PYTHONUTF8"] == "0"
-    assert env["PYTHONIOENCODING"] == "latin-1"
 
 
 def test_boot_script_must_be_read_as_utf8():

From a4ba80a683b0f7cadb8e0305490e1d9cf42fc149 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Thu, 16 Jul 2026 09:17:54 -0700
Subject: [PATCH 07/33] fix(scratchpad): give the pip/uv install subprocess
 UTF-8 mode too (self-review, ENG-824)

Skill review: the main scratchpad subprocess got _utf8_env but the dependency
install subprocess didn't, so on a non-UTF-8 host locale pip/uv output could
come back as mojibake. Pass env=_utf8_env(os.environ) here too for consistency.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/backends/local.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/anton/core/backends/local.py b/anton/core/backends/local.py
index 0d5f5baa..ea92c8da 100644
--- a/anton/core/backends/local.py
+++ b/anton/core/backends/local.py
@@ -704,6 +704,9 @@ async def install_packages(self, packages: list[str]) -> str:
             *cmd,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.STDOUT,
+            # Same UTF-8 mode as the scratchpad process, so pip/uv output on a
+            # non-UTF-8 host locale doesn't come back as mojibake (ENG-824).
+            env=_utf8_env(os.environ),
         )
         try:
             stdout, _ = await asyncio.wait_for(

From 0a0bb9186f0a245587d1cc9ffcc8eea46be11454 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Fri, 17 Jul 2026 12:03:26 +0300
Subject: [PATCH 08/33] fix(publish): clear local .published.json on /unpublish
 so re-publish starts fresh

---
 anton/chat.py                        | 35 +++++++++++++++++++
 tests/test_unpublish_clears_local.py | 51 ++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 tests/test_unpublish_clears_local.py

diff --git a/anton/chat.py b/anton/chat.py
index e238c9bc..ed5f2f5c 100644
--- a/anton/chat.py
+++ b/anton/chat.py
@@ -869,6 +869,41 @@ async def _handle_unpublish(
     console.print(f"  [anton.success]Removed:[/] {title}")
     console.print()
 
+    # 6. Drop the local owner-side record for this report so a later /publish
+    # treats it as a fresh publish instead of offering to "update" (and reusing
+    # the report_id of) a report that no longer exists.
+    import json as _json
+    from pathlib import Path as _Path
+
+    removed_report_id = selected.get("report_id") or ""
+    removed_md5 = selected.get("md5") or ""
+    artifacts_root = _Path(settings.artifacts_dir)
+    for pub_file in artifacts_root.rglob(".published.json"):
+        try:
+            data = _json.loads(pub_file.read_text())
+        except Exception:
+            continue
+        if not isinstance(data, dict):
+            continue
+        changed = False
+        for key in list(data.keys()):
+            entry = data.get(key)
+            if not isinstance(entry, dict):
+                continue
+            entry_report_id = entry.get("report_id") or ""
+            matches = (
+                (removed_report_id and entry_report_id == removed_report_id)
+                or (not entry_report_id and removed_md5 and entry.get("last_md5") == removed_md5)
+            )
+            if matches:
+                del data[key]
+                changed = True
+        if changed:
+            try:
+                pub_file.write_text(_json.dumps(data, indent=2))
+            except Exception:
+                pass
+
 
 async def _agent_zero(console: Console, session: "ChatSession", settings) -> str | None:
     """First-run staged demo. Runs the backup script in a real scratchpad cell.
diff --git a/tests/test_unpublish_clears_local.py b/tests/test_unpublish_clears_local.py
new file mode 100644
index 00000000..51d47508
--- /dev/null
+++ b/tests/test_unpublish_clears_local.py
@@ -0,0 +1,51 @@
+"""/unpublish must drop the local .published.json entry so a later /publish
+does not offer to 'update' a report that no longer exists."""
+
+import json
+from pathlib import Path
+from unittest import mock
+
+import pytest
+from rich.console import Console
+
+import anton.chat as chat
+
+
+def _make_published_artifact(tmp_path: Path) -> tuple[Path, Path]:
+    root = tmp_path / "artifacts"
+    art = root / "server-time-display-2"
+    art.mkdir(parents=True)
+    (art / "report.html").write_text("<html></html>")
+    pub = art / ".published.json"
+    pub.write_text(json.dumps({
+        "report.html": {
+            "report_id": "247c4983", "url": "https://view/a/247c4983",
+            "last_md5": "m", "mode": "password", "requires_password": True,
+            "access_password": "s3cret", "pwd_version": 1,
+        },
+    }))
+    return root, pub
+
+
+@pytest.mark.asyncio
+async def test_unpublish_removes_local_entry(tmp_path):
+    root, pub = _make_published_artifact(tmp_path)
+
+    settings = mock.Mock()
+    settings.minds_api_key = "key"
+    settings.artifacts_dir = str(root)
+    settings.publish_url = "https://view.test"
+    settings.minds_ssl_verify = True
+
+    reports = [{"title": "server-time-display-2", "report_id": "247c4983",
+                "md5": "m", "view_url": "https://view/a/247c4983"}]
+
+    with mock.patch("anton.publisher.list_published", return_value=reports), \
+         mock.patch("anton.publisher.unpublish", return_value={}), \
+         mock.patch("anton.chat.prompt_or_cancel",
+                    new=mock.AsyncMock(side_effect=["1", "y"])):
+        await chat._handle_unpublish(Console(), settings, mock.Mock())
+
+    # The stale entry must be gone so /publish treats it as fresh.
+    data = json.loads(pub.read_text())
+    assert "report.html" not in data

From 8b0014477011b89aa5ccd808fbb6537447480d88 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Fri, 17 Jul 2026 12:29:49 +0300
Subject: [PATCH 09/33] fix(publish): publish_or_preview resolves artifact
 target from metadata (folder-aware) [ENG-844]

---
 anton/tools.py                    | 106 ++++++++++++++++++++++--------
 tests/test_publish_tool_access.py |  43 ++++++++++++
 2 files changed, 121 insertions(+), 28 deletions(-)

diff --git a/anton/tools.py b/anton/tools.py
index d6157c5e..a48768d6 100644
--- a/anton/tools.py
+++ b/anton/tools.py
@@ -376,36 +376,85 @@ async def handle_connect_datasource(session: ChatSession, tc_input: dict) -> str
 )
 
 
+def _previewable_html(path: "Path"):
+    """Best-effort HTML file to open for local preview.
+
+    For a file, returns it as-is; for a folder (e.g. a fullstack artifact),
+    prefers index.html / static/index.html, else the first ``*.html`` found."""
+    from pathlib import Path
+
+    path = Path(path)
+    if path.is_file():
+        return path
+    for cand in (path / "index.html", path / "static" / "index.html"):
+        if cand.is_file():
+            return cand
+    try:
+        htmls = sorted(path.rglob("*.html"))
+    except OSError:
+        htmls = []
+    return htmls[0] if htmls else None
+
+
 async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str:
-    """Interactive preview/publish flow after dashboard creation."""
+    """Interactive preview/publish flow after dashboard creation.
+
+    Accepts the **artifact folder** (preferred) or any file inside it. The
+    artifact type is read from its ``metadata.json`` via
+    ``resolve_publish_target`` — fullstack apps publish the whole folder, static
+    reports publish the primary file — so callers never need to know the type."""
     import os
     import webbrowser
     from pathlib import Path
 
+    from anton.config.settings import AntonSettings
+    from anton.publish_access import (
+        access_from_owner_side,
+        resolve_access,
+        resolve_publish_target,
+    )
+
     console = session._console
 
     raw_path = tc_input.get("file_path", "")
     title = tc_input.get("title", "Dashboard")
     action = tc_input.get("action", "ask")
+
+    settings = AntonSettings()
+    artifacts_root = Path(settings.artifacts_dir)
+
+    # Accept the artifact folder (preferred) or any file inside it. Resolve a
+    # relative path against the artifacts dir first (so "my-app" works), then
+    # the workspace base.
     file_path = Path(raw_path)
-    if not file_path.is_absolute() and session._workspace:
-        file_path = Path(session._workspace.base) / raw_path
+    if not file_path.is_absolute():
+        base = Path(session._workspace.base) if session._workspace else artifacts_root
+        file_path = next(
+            (c for c in (artifacts_root / raw_path, base / raw_path) if c.exists()),
+            base / raw_path,
+        )
 
     if not file_path.exists():
-        return f"File not found: {file_path}"
+        return f"Path not found: {file_path}"
+
+    # Decide WHAT to publish from the artifact's metadata.json: fullstack → the
+    # whole folder, static → the primary file. Also yields the canonical
+    # .published.json location + key (shared with /publish and cowork-server).
+    publish_target, published_dir, published_key, _is_fullstack = resolve_publish_target(
+        file_path, [artifacts_root]
+    )
 
-    # Direct preview — just open and return, no prompts
+    # Direct preview — open a previewable HTML and return, no prompts.
     if action in ("preview", "ask"):
-        abs_path = os.path.abspath(str(file_path))
-        webbrowser.open(f"file://{abs_path}")
-        return f"Opened {title} in browser. The user can ask for changes or say /publish to publish it to the web."
+        preview_file = _previewable_html(publish_target)
+        if preview_file is not None:
+            webbrowser.open(f"file://{os.path.abspath(str(preview_file))}")
+            return f"Opened {title} in browser. The user can ask for changes or say /publish to publish it to the web."
+        return f"{title} is at {file_path} but no previewable HTML was found."
 
     # Publish flow
-    from anton.config.settings import AntonSettings
     from anton.publisher import publish
 
-    settings = AntonSettings()
-
     if not settings.minds_api_key:
         console.print()
         console.print("  [anton.muted]To publish you need a free Minds account.[/]")
@@ -423,19 +472,12 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
     from rich.live import Live
     from rich.spinner import Spinner
 
-    from anton.publish_access import (
-        access_from_owner_side,
-        resolve_access,
-        resolve_publish_target,
-    )
     from anton.utils.prompt import prompt_or_cancel
 
-    # Check if this file was previously published — reuse report_id to
-    # update instead of creating a new report every time. Resolve the
-    # .published.json location with the unified convention (shared with
-    # /publish and cowork-server) so the two entry points never disagree.
-    artifacts_root = Path(settings.artifacts_dir)
-    _t, published_dir, published_key, _fs = resolve_publish_target(file_path, [artifacts_root])
+    # Check if this artifact was previously published — reuse report_id to
+    # update instead of creating a new report every time. published_dir /
+    # published_key were resolved above via the unified convention (shared with
+    # /publish and cowork-server) so the entry points never disagree.
     published_json = published_dir / ".published.json"
     published_map: dict = {}
     try:
@@ -485,7 +527,7 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
     with Live(Spinner("dots", text=action_text, style="anton.cyan"), console=console, transient=True):
         try:
             result = publish(
-                file_path,
+                publish_target,
                 api_key=settings.minds_api_key,
                 report_id=report_id,
                 publish_url=settings.publish_url,
@@ -500,7 +542,7 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
                 # without report_id to create a fresh one.
                 try:
                     result = publish(
-                        file_path,
+                        publish_target,
                         api_key=settings.minds_api_key,
                         publish_url=settings.publish_url,
                         ssl_verify=settings.minds_ssl_verify,
@@ -556,19 +598,27 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
 PUBLISH_TOOL = ToolDef(
     name = "publish_or_preview",
     description = (
-        "Call this after generating an HTML dashboard or report in .anton/output/. "
+        "Call this after generating a dashboard/report/app to preview or publish it. "
+        "Pass the artifact FOLDER as file_path — the tool reads metadata.json and picks "
+        "the right thing to publish (whole folder for fullstack apps, primary file for "
+        "static reports). "
         "Actions: 'ask' (default) prompts the user to preview/publish/skip interactively. "
-        "'preview' opens the file in the browser immediately. "
+        "'preview' opens it in the browser immediately. "
         "'publish' publishes to the web immediately. "
         "Use 'preview' or 'publish' when the user has already stated their intent. "
-        "Use 'ask' after generating a new dashboard to let the user choose."
+        "Use 'ask' after generating a new artifact to let the user choose."
     ),
     input_schema = {
         "type": "object",
         "properties": {
             "file_path": {
                 "type": "string",
-                "description": "Path to the HTML file (e.g. .anton/output/dashboard.html)",
+                "description": (
+                    "Path to the artifact FOLDER (e.g. artifacts/<slug>). The tool reads "
+                    "the folder's metadata.json to decide how to publish: fullstack apps "
+                    "publish the whole folder, static reports publish their primary file. "
+                    "A path to a file inside the artifact also works."
+                ),
             },
             "title": {
                 "type": "string",
diff --git a/tests/test_publish_tool_access.py b/tests/test_publish_tool_access.py
index d8fcd490..feea1856 100644
--- a/tests/test_publish_tool_access.py
+++ b/tests/test_publish_tool_access.py
@@ -20,6 +20,18 @@ def _artifact(tmp_path: Path) -> Path:
     return f
 
 
+def _fullstack_artifact(tmp_path: Path) -> tuple[Path, Path]:
+    root = tmp_path / "artifacts"
+    art = root / "server-time-display-2"
+    (art / "static").mkdir(parents=True)
+    (art / "metadata.json").write_text(
+        '{"type": "fullstack-stateless-app", "primary": "static/index.html"}'
+    )
+    (art / "backend.py").write_text("print(1)")
+    (art / "static" / "index.html").write_text("<html></html>")
+    return root, art
+
+
 def _session(tmp_path):
     s = mock.Mock()
     s._console = Console()
@@ -88,3 +100,34 @@ async def test_tool_password_no_value_non_tty_cancels(tmp_path):
         )
     assert "CANCELLED" in out
     fake_publish.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_tool_fullstack_publishes_folder(tmp_path):
+    """Given the artifact folder, publish() receives the folder (fullstack bundle)."""
+    root, art = _fullstack_artifact(tmp_path)
+    fake_publish = mock.Mock(return_value={"view_url": "u", "report_id": "r", "md5": "m", "version": 1})
+    with mock.patch("anton.publisher.publish", fake_publish), \
+         mock.patch("anton.config.settings.AntonSettings", return_value=_settings(root)), \
+         mock.patch("webbrowser.open"):
+        await tools.handle_publish_or_preview(
+            _session(tmp_path), {"file_path": str(art), "action": "publish"},
+        )
+    args, _ = fake_publish.call_args
+    assert Path(args[0]) == art  # the folder, not an inner file
+
+
+@pytest.mark.asyncio
+async def test_tool_fullstack_from_inner_file_publishes_folder(tmp_path):
+    """Even if the model points at an inner HTML file, publish() gets the folder."""
+    root, art = _fullstack_artifact(tmp_path)
+    fake_publish = mock.Mock(return_value={"view_url": "u", "report_id": "r", "md5": "m", "version": 1})
+    with mock.patch("anton.publisher.publish", fake_publish), \
+         mock.patch("anton.config.settings.AntonSettings", return_value=_settings(root)), \
+         mock.patch("webbrowser.open"):
+        await tools.handle_publish_or_preview(
+            _session(tmp_path),
+            {"file_path": str(art / "static" / "index.html"), "action": "publish"},
+        )
+    args, _ = fake_publish.call_args
+    assert Path(args[0]) == art  # normalized up to the fullstack folder

From 2ef9614e2407af7e95ba63170312057837f41185 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Fri, 17 Jul 2026 14:48:08 +0300
Subject: [PATCH 10/33] feat(publish): ask for access mode in chat when the
 user didn't specify it

---
 anton/tools.py | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/anton/tools.py b/anton/tools.py
index a48768d6..41064d98 100644
--- a/anton/tools.py
+++ b/anton/tools.py
@@ -632,7 +632,7 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
             "access_mode": {
                 "type": "string",
                 "enum": ["public", "password", "restricted"],
-                "description": "Access level. ONLY set when the user explicitly asked for it.",
+                "description": "Access level the user chose. If the user hasn't said which access they want, ASK them first (see the tool guidance) rather than guessing; only set this once you know.",
             },
             "password": {
                 "type": "string",
@@ -660,11 +660,17 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
         "- user's connected datasources (databases, CRMs, etc.) is fine — this rule only applies to \n"
         "- sharing generated output with the public internet.\n"
         "ACCESS MODE:\n"
-        "- Pass access_mode/password/emails/org_allowed ONLY if the user explicitly asked "
-        "(e.g. 'publish with password', 'share only with a@x.com').\n"
-        "- NEVER invent a password. If the user wants a password but didn't state it, set "
+        "- Before publishing you MUST know the access mode. If the user stated it "
+        "(e.g. 'publish with password', 'share only with a@x.com', 'make it public'), use it: "
+        "set access_mode (+ password/emails/org_allowed) accordingly.\n"
+        "- If the user did NOT specify an access mode, ASK them in chat which one they want — "
+        "public (anyone with the link), password-protected, or restricted to specific emails / "
+        "the whole organization — and wait for their answer before calling this tool with "
+        "action='publish'. Do NOT silently default to public.\n"
+        "- NEVER invent a password. If the user chooses password but gives no value, set "
         "access_mode='password' and leave password empty — the app will prompt them.\n"
-        "- If the user says nothing about access, omit these fields (public, or the artifact's "
-        "previous access is preserved on re-publish)."
+        "- Exception: when re-publishing an artifact that already has access on record and the "
+        "user says nothing new about access, omit these fields to keep its previous access "
+        "(no need to ask again)."
     ),
 )

From a0814f23cb15d3914583edb14f0b2785c87d4512 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Fri, 17 Jul 2026 16:11:17 +0300
Subject: [PATCH 11/33] fiix

---
 tests/test_publish_chat_access.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tests/test_publish_chat_access.py b/tests/test_publish_chat_access.py
index bd4cf435..c2c85882 100644
--- a/tests/test_publish_chat_access.py
+++ b/tests/test_publish_chat_access.py
@@ -48,14 +48,14 @@ async def test_publish_passes_password_access(tmp_path):
     async def fake_prompt_access(*a, **k):
         return {"mode": "password", "password": "hunter2"}
 
-    # publish и prompt_access импортируются в _handle_publish на уровне функции,
-    # поэтому патчим ИСХОДНЫЕ модули — function-level импорт резолвит имя в
-    # момент вызова и подхватит патч.
+    # publish and prompt_access are imported inside _handle_publish at the
+    # function level, so we patch the SOURCE modules — a function-level import
+    # resolves the name at call time and picks up the patch.
     with mock.patch("anton.publisher.publish", fake_publish), \
          mock.patch("anton.publish_access.prompt_access", side_effect=fake_prompt_access), \
          mock.patch("webbrowser.open"):
-        # Директорию _make_candidate публикует только для fullstack; для
-        # html-report адресуем файл (файловая ветка _make_candidate).
+        # _make_candidate only publishes a directory for fullstack artifacts;
+        # for an html-report we address the file (the file branch of _make_candidate).
         await chat._handle_publish(Console(), settings, mock.Mock(), file_arg="sales/report.html")
 
     _, kwargs = fake_publish.call_args

From b898bfc79a52c0d0727c3b5425c4fd1962340d76 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Fri, 17 Jul 2026 17:06:44 +0300
Subject: [PATCH 12/33] fix web_search

---
 anton/core/backends/scratchpad_boot.py | 27 +++----------
 anton/core/llm/openai.py               | 16 ++++++++
 tests/test_scratchpad_flavor.py        | 52 ++++++++++++++++++++++++++
 3 files changed, 73 insertions(+), 22 deletions(-)
 create mode 100644 tests/test_scratchpad_flavor.py

diff --git a/anton/core/backends/scratchpad_boot.py b/anton/core/backends/scratchpad_boot.py
index 76aa5097..4c634dac 100644
--- a/anton/core/backends/scratchpad_boot.py
+++ b/anton/core/backends/scratchpad_boot.py
@@ -104,28 +104,11 @@ def _dump_namespace(ns: dict) -> str | None:
                 _llm_provider_kwargs["vision_format"] = "anthropic"
             # Resolve the OpenAI "flavor" so the injected web_search() helper can
             # route through whatever native web tooling the endpoint exposes.
-            # Mirrors LLMClient._resolve_openai_compatible_flavor: direct OpenAI
-            # BYOK uses the Responses API (web_search); an openai-compatible base
-            # URL pointing at Minds/mdb.ai uses the chat.completions passthrough;
-            # any other openai-compatible endpoint is generic (no native search).
-            if _scratchpad_provider_name == "openai":
-                _llm_provider_kwargs["flavor"] = _ProviderClass.FLAVOR_OPENAI
-            else:
-                _minds_url_norm = (
-                    os.environ.get("ANTON_MINDS_URL", "").rstrip("/").lower()
-                )
-                _base_norm = (_llm_base_url or "").rstrip("/").lower()
-                if _minds_url_norm and _base_norm in (
-                    _minds_url_norm,
-                    f"{_minds_url_norm}/api/v1",
-                ):
-                    _llm_provider_kwargs["flavor"] = (
-                        _ProviderClass.FLAVOR_MINDS_PASSTHROUGH
-                    )
-                else:
-                    _llm_provider_kwargs["flavor"] = (
-                        _ProviderClass.FLAVOR_OPENAI_COMPATIBLE_GENERIC
-                    )
+            # Detect Minds/mdb.ai by HOST, not provider name (always "openai" for
+            # an OpenAIProvider even on the minds gateway) — see resolve_web_flavor.
+            _llm_provider_kwargs["flavor"] = _ProviderClass.resolve_web_flavor(
+                _scratchpad_provider_name, _llm_base_url
+            )
             _llm_provider = _ProviderClass(**_llm_provider_kwargs)
         else:
             _llm_provider = _ProviderClass()  # Anthropic doesn't need ssl_verify
diff --git a/anton/core/llm/openai.py b/anton/core/llm/openai.py
index 88923c44..9d00cf48 100644
--- a/anton/core/llm/openai.py
+++ b/anton/core/llm/openai.py
@@ -686,6 +686,22 @@ def native_web_tools(self) -> set[str]:
             return {"web_search", "web_fetch"}
         return set()
 
+    @staticmethod
+    def resolve_web_flavor(provider_name: str, base_url: str) -> str:
+        """Flavor for the scratchpad's web_search(), from provider name + base URL.
+
+        ``name`` is always "openai" for an OpenAIProvider even when the base URL is
+        the minds gateway, so a minds/mdb.ai HOST must win over the name: minds
+        serves web_search over the chat.completions passthrough, not the Responses
+        API. Direct OpenAI uses Responses; anything else is generic (no native web).
+        """
+        host = (base_url or "").lower()
+        if any(h in host for h in ("mdb.ai", "mindshub.ai")):
+            return OpenAIProvider.FLAVOR_MINDS_PASSTHROUGH
+        if provider_name == "openai":
+            return OpenAIProvider.FLAVOR_OPENAI
+        return OpenAIProvider.FLAVOR_OPENAI_COMPATIBLE_GENERIC
+
     @staticmethod
     def _sanitize_langfuse_tag(tag: str) -> str:
         """Clean a caller-supplied langfuse tag so it survives the wire intact.
diff --git a/tests/test_scratchpad_flavor.py b/tests/test_scratchpad_flavor.py
new file mode 100644
index 00000000..263d690c
--- /dev/null
+++ b/tests/test_scratchpad_flavor.py
@@ -0,0 +1,52 @@
+"""Flavor resolution for the scratchpad's injected web_search() helper.
+
+Regression guard for the minds gateway case: OpenAIProvider.name is always
+"openai" even when the base URL is the minds gateway, so keying the flavor off
+the provider name alone picked the Responses-API flavor and dispatched
+web_search to a Responses endpoint the minds gateway does not implement — it
+silently returned empty. The host must win over the name.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from anton.core.llm.openai import OpenAIProvider
+
+resolve = OpenAIProvider.resolve_web_flavor
+
+
+@pytest.mark.parametrize(
+    "base_url",
+    [
+        "https://api.mindshub.ai/v1",
+        "https://api.staging.mindshub.ai/v1",
+        "https://mdb.ai/api/v1",
+        "HTTPS://API.MINDSHUB.AI/v1",  # case-insensitive
+    ],
+)
+def test_minds_host_uses_passthrough_even_with_openai_name(base_url):
+    # provider name is "openai" (the class default) yet the host is minds ->
+    # must be the chat.completions passthrough, NOT the Responses API.
+    assert resolve("openai", base_url) == OpenAIProvider.FLAVOR_MINDS_PASSTHROUGH
+
+
+def test_direct_openai_uses_responses_api():
+    assert resolve("openai", "https://api.openai.com/v1") == OpenAIProvider.FLAVOR_OPENAI
+    assert resolve("openai", "") == OpenAIProvider.FLAVOR_OPENAI
+    assert resolve("openai", None) == OpenAIProvider.FLAVOR_OPENAI
+
+
+def test_other_compatible_endpoint_is_generic():
+    assert (
+        resolve("openai-compatible", "https://my-proxy.internal/v1")
+        == OpenAIProvider.FLAVOR_OPENAI_COMPATIBLE_GENERIC
+    )
+
+
+def test_openai_compatible_minds_base_still_passthrough():
+    # An "openai-compatible" provider pointed at minds keeps passthrough too.
+    assert (
+        resolve("openai-compatible", "https://api.mindshub.ai/v1")
+        == OpenAIProvider.FLAVOR_MINDS_PASSTHROUGH
+    )

From e0584cd73915107bb56406d79c16a761f1d9abf8 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Mon, 20 Jul 2026 17:24:35 +0300
Subject: [PATCH 13/33] fix(prompts): reference created artifact in final
 message

---
 anton/core/llm/prompts.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/anton/core/llm/prompts.py b/anton/core/llm/prompts.py
index 3271504a..f4797935 100644
--- a/anton/core/llm/prompts.py
+++ b/anton/core/llm/prompts.py
@@ -301,6 +301,13 @@
 again — that creates a duplicate.
 3. If you discover the entry-point filename only later (or change it), call \
 `update_artifact(slug, primary=...)` so the renderer opens the right file.
+4. AFTER FINISHING — reference the artifact in your final message. Once the \
+artifact's files are written, tell the user what was created and point to it by \
+`name` and `slug`, and include the primary file's path \
+(`<artifact_path>/<primary>`) so it is clickable/openable in a plain CLI. NEVER \
+end with only a description of the content and no pointer to the result. (For \
+fullstack apps, prefer the `url` returned by `launch_backend` as the primary \
+pointer — see the BACKEND & FULLSTACK section.)
 """
 
 

From 94a34ec9afef8fbd43baa9224928422013617de1 Mon Sep 17 00:00:00 2001
From: Max Stepanov <stpmax@yandex.ru>
Date: Mon, 20 Jul 2026 17:58:31 +0300
Subject: [PATCH 14/33] fix(cli): flush per-round preambles separately instead
 of concatenating

---
 anton/chat_ui.py      |  66 ++++++----------
 tests/test_chat_ui.py | 180 ++++++++++++++++++++++++++++++++++++------
 2 files changed, 183 insertions(+), 63 deletions(-)

diff --git a/anton/chat_ui.py b/anton/chat_ui.py
index 4c5af725..dacb895f 100644
--- a/anton/chat_ui.py
+++ b/anton/chat_ui.py
@@ -202,11 +202,7 @@ def __init__(self, console: Console, toolbar: dict | None = None) -> None:
         self._live: Live | None = None
         self._toolbar = toolbar
         self._activities: list[_ToolActivity] = []
-        self._buffer = ""  # answer text accumulated during streaming
-        self._in_tool_phase = False
-        self._last_was_tool = False
-        self._initial_text = ""
-        self._initial_printed = False
+        self._pending = ""  # assistant text accumulated during streaming
         self._active = False
         # 3-line footer state
         self._line1_fun: str = ""  # Line 1: Esc to cancel — fun message
@@ -280,11 +276,7 @@ def start(self) -> None:
         self._line3_peek = ""
         self._set_status(self._line1_fun)
         self._activities = []
-        self._buffer = ""
-        self._initial_text = ""
-        self._initial_printed = False
-        self._in_tool_phase = False
-        self._last_was_tool = False
+        self._pending = ""
         self._cancel_msg = ""
         self._active = True
         self._start_spinner()
@@ -292,15 +284,9 @@ def start(self) -> None:
     def append_text(self, delta: str) -> None:
         if not self._active:
             return
-        if self._in_tool_phase:
-            self._buffer += delta
-            self._last_was_tool = False
-            self._line3_peek = self._extract_peek(self._buffer)
-            self._update_spinner()
-        else:
-            self._initial_text += delta
-            self._line3_peek = self._extract_peek(self._initial_text)
-            self._update_spinner()
+        self._pending += delta
+        self._line3_peek = self._extract_peek(self._pending)
+        self._update_spinner()
 
     def show_tool_result(self, content: str) -> None:
         """Print a tool result permanently (immediately scrollable)."""
@@ -308,7 +294,6 @@ def show_tool_result(self, content: str) -> None:
             return
         self._stop_spinner()
         self._console.print(Markdown(content))
-        self._last_was_tool = True
         self._start_spinner()
 
     def show_tool_execution(self, task: str) -> None:
@@ -316,13 +301,25 @@ def show_tool_execution(self, task: str) -> None:
         self.on_tool_use_start(f"_compat_{id(task)}", task)
 
     def on_tool_use_start(self, tool_id: str, name: str) -> None:
-        """Track a new tool use."""
+        """Track a new tool use.
+
+        Any text accumulated since the last flush is the current round's
+        preamble (inner-speech). Print it dimmed now and clear the
+        accumulator, so it is visually separated from other rounds'
+        preambles and from the final answer.
+        """
         import time as _time
 
         if not self._active:
             return
-        self._in_tool_phase = True
-        self._last_was_tool = True
+        preamble = self._pending.rstrip()
+        if preamble:
+            self._stop_spinner()
+            self._console.print(Text(preamble, style="anton.muted"))
+            self._start_spinner()
+        self._pending = ""
+        self._line3_peek = ""
+        self._update_spinner()  # refresh footer even when preamble was empty
         activity = _ToolActivity(
             tool_id=tool_id, name=name, start_time=_time.monotonic()
         )
@@ -467,23 +464,12 @@ def finish(self) -> None:
                 act.done_line_printed = True
                 self._print_done_line(act, act.work_elapsed)
 
-        # Print initial text as muted "inner speech" (if not already printed)
-        if self._initial_text and not self._initial_printed:
-            if self._activities:
-                self._console.print(
-                    Text(self._initial_text.rstrip(), style="anton.muted")
-                )
-
-        # Print answer
-        if self._activities:
-            if self._buffer:
-                self._console.print(Text("anton> ", style="anton.prompt"), end="")
-                self._console.print(Markdown(self._buffer))
-        else:
-            all_text = self._initial_text + self._buffer
-            if all_text:
-                self._console.print(Text("anton> ", style="anton.prompt"), end="")
-                self._console.print(Markdown(all_text))
+        # Whatever remains in _pending is the text after the last tool — the
+        # true final answer. All preambles were already flushed dimmed at
+        # each tool start, so there is nothing to disambiguate here.
+        if self._pending:
+            self._console.print(Text("anton> ", style="anton.prompt"), end="")
+            self._console.print(Markdown(self._pending))
 
         self._active = False
         self._console.print()
diff --git a/tests/test_chat_ui.py b/tests/test_chat_ui.py
index 4ed6d141..415e2bd2 100644
--- a/tests/test_chat_ui.py
+++ b/tests/test_chat_ui.py
@@ -20,7 +20,7 @@ def test_start_creates_live(self, MockLive):
         MockLive.return_value.start.assert_called_once()
 
     @patch("anton.chat_ui.Live")
-    def test_append_text_updates_buffer(self, MockLive):
+    def test_append_text_accumulates_in_pending(self, MockLive):
         display, console = self._make_display()
         display.start()
         live = MockLive.return_value
@@ -28,8 +28,8 @@ def test_append_text_updates_buffer(self, MockLive):
         display.append_text("Hello ")
         display.append_text("world!")
 
-        # Before any tool use, text goes to _initial_text
-        assert display._initial_text == "Hello world!"
+        # All streamed text accumulates in the single _pending buffer
+        assert display._pending == "Hello world!"
         assert live.update.call_count == 2
 
     @patch("anton.chat_ui.Live")
@@ -115,22 +115,50 @@ def test_json_delta_accumulation(self, MockLive):
 
     @patch("anton.chat_ui.Live")
     def test_finish_prints_activity_summary(self, MockLive):
+        from rich.markdown import Markdown as RichMarkdown
+        from rich.text import Text as RichText
+
         display, console = self._make_display()
         display.start()
 
-        # Initial text before tools
+        # Preamble before the tool — must flush dimmed AT on_tool_use_start
         display.append_text("Let me check...")
-
         display.on_tool_use_start("tool_1", "scratchpad")
+
+        muted_before_finish = [
+            c.args[0].plain
+            for c in console.print.call_args_list
+            if c.args
+            and isinstance(c.args[0], RichText)
+            and c.args[0].style == "anton.muted"
+        ]
+        assert muted_before_finish == ["Let me check..."]
+
         display.on_tool_use_delta("tool_1", '{"action": "exec", "name": "pad"}')
         display.on_tool_use_end("tool_1")
 
-        # Answer text after tools
+        # Answer text after the tool
         display.append_text("Here's what I found...")
-        display.finish()
 
-        # finish should print: muted initial, activity tree, anton> + answer markdown, trailing newline
-        assert console.print.call_count >= 4
+        calls_before_finish = len(console.print.call_args_list)
+        display.finish()
+        finish_calls = console.print.call_args_list[calls_before_finish:]
+
+        # finish() prints NO muted inner-speech (it was flushed earlier) …
+        assert not [
+            c
+            for c in finish_calls
+            if c.args
+            and isinstance(c.args[0], RichText)
+            and c.args[0].style == "anton.muted"
+        ]
+        # … and prints the final answer as a single Markdown block.
+        markdowns = [
+            c.args[0].markup
+            for c in finish_calls
+            if c.args and isinstance(c.args[0], RichMarkdown)
+        ]
+        assert markdowns == ["Here's what I found..."]
 
     @patch("anton.chat_ui.Live")
     def test_no_activities_no_tree(self, MockLive):
@@ -203,24 +231,130 @@ def test_scratchpad_display_falls_back_to_action(self):
         assert result == "exec"
 
     @patch("anton.chat_ui.Live")
-    def test_text_routes_to_initial_before_tools(self, MockLive):
-        display, _ = self._make_display()
-        display.start()
-
-        display.append_text("Let me check...")
-        assert display._initial_text == "Let me check..."
-        assert display._buffer == ""
-        assert not display._in_tool_phase
+    def test_preamble_flushed_dimmed_at_tool_start(self, MockLive):
+        from rich.text import Text as RichText
 
-    @patch("anton.chat_ui.Live")
-    def test_text_routes_to_buffer_after_tools(self, MockLive):
-        display, _ = self._make_display()
+        display, console = self._make_display()
         display.start()
 
         display.append_text("Initial text")
         display.on_tool_use_start("tool_1", "scratchpad")
+
+        # Preamble printed dimmed at the tool boundary, accumulator cleared
+        muted = [
+            c.args[0].plain
+            for c in console.print.call_args_list
+            if c.args
+            and isinstance(c.args[0], RichText)
+            and c.args[0].style == "anton.muted"
+        ]
+        assert muted == ["Initial text"]
+        assert display._pending == ""
+
+        # Subsequent text accumulates fresh
         display.append_text("Answer text")
+        assert display._pending == "Answer text"
+
+    @patch("anton.chat_ui.Live")
+    def test_multiround_preambles_flushed_separately(self, MockLive):
+        from rich.markdown import Markdown as RichMarkdown
+        from rich.text import Text as RichText
+
+        display, console = self._make_display()
+        display.start()
+
+        # Round 1: preamble → tool
+        display.append_text("Now launching the backend:")
+        display.on_tool_use_start("t1", "scratchpad")
+        display.on_tool_use_delta("t1", '{"action": "exec", "name": "p"}')
+        display.on_tool_use_end("t1")
+
+        # Round 2: preamble → tool
+        display.append_text("Launched! Checking the API:")
+        display.on_tool_use_start("t2", "scratchpad")
+        display.on_tool_use_delta("t2", '{"action": "exec", "name": "p"}')
+        display.on_tool_use_end("t2")
+
+        # Trailing text after the last tool = the real final answer
+        display.append_text("Everything works.")
+        display.finish()
+
+        muted = [
+            c.args[0].plain
+            for c in console.print.call_args_list
+            if c.args
+            and isinstance(c.args[0], RichText)
+            and c.args[0].style == "anton.muted"
+        ]
+        # Both preambles printed live, in order, each on its own line
+        assert muted == [
+            "Now launching the backend:",
+            "Launched! Checking the API:",
+        ]
+
+        markdowns = [
+            c.args[0].markup
+            for c in console.print.call_args_list
+            if c.args and isinstance(c.args[0], RichMarkdown)
+        ]
+        # Final answer is a single block — NOT concatenated with the preambles
+        assert markdowns == ["Everything works."]
+
+    @patch("anton.chat_ui.Live")
+    def test_consecutive_tools_no_text_no_flush(self, MockLive):
+        from rich.text import Text as RichText
+
+        display, console = self._make_display()
+        display.start()
+
+        display.on_tool_use_start("t1", "scratchpad")
+        display.on_tool_use_end("t1")
+        display.on_tool_use_start("t2", "scratchpad")
+        display.on_tool_use_end("t2")
+
+        muted = [
+            c
+            for c in console.print.call_args_list
+            if c.args
+            and isinstance(c.args[0], RichText)
+            and getattr(c.args[0], "style", None) == "anton.muted"
+        ]
+        assert muted == []
+
+    @patch("anton.chat_ui.Live")
+    def test_turn_ending_with_tool_prints_no_answer(self, MockLive):
+        from rich.markdown import Markdown as RichMarkdown
+
+        display, console = self._make_display()
+        display.start()
+
+        display.append_text("Preamble")
+        display.on_tool_use_start("t1", "scratchpad")
+        display.on_tool_use_end("t1")
+        display.finish()
+
+        markdowns = [
+            c
+            for c in console.print.call_args_list
+            if c.args and isinstance(c.args[0], RichMarkdown)
+        ]
+        # No trailing text → no anton> answer block
+        assert markdowns == []
+
+    @patch("anton.chat_ui.Live")
+    def test_no_tools_single_markdown_answer(self, MockLive):
+        from rich.markdown import Markdown as RichMarkdown
+
+        display, console = self._make_display()
+        display.start()
+
+        display.append_text("Hello ")
+        display.append_text("world!")
+        display.finish()
 
-        assert display._initial_text == "Initial text"
-        assert display._buffer == "Answer text"
-        assert display._in_tool_phase
+        markdowns = [
+            c.args[0].markup
+            for c in console.print.call_args_list
+            if c.args and isinstance(c.args[0], RichMarkdown)
+        ]
+        assert markdowns == ["Hello world!"]

From d9406ceb11bcb595c694008289103c531edd2713 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Mon, 20 Jul 2026 11:22:40 -0700
Subject: [PATCH 15/33] fix(scratchpad): UTF-8 the _parent_venv.pth write + pin
 the boot-script read (PR #253 review, ENG-824)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address Zoran's review on #253:
- _setup_parent_site_packages wrote _parent_venv.pth with a plain open() (host-
  locale encoded) while the child reads .pth as UTF-8 under UTF-8 mode — same
  class of bug as the boot script. Write it as encoding="utf-8".
- Extract _read_boot_script() and add a test that spies on Path.read_text to
  assert the boot-script read passes encoding="utf-8" — the previous bytes-only
  test would still pass on UTF-8 CI if the explicit encoding were dropped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/backends/local.py  | 22 +++++++++++++++++-----
 tests/test_scratchpad_utf8.py | 20 +++++++++++++++++++-
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/anton/core/backends/local.py b/anton/core/backends/local.py
index ea92c8da..1c8973a6 100644
--- a/anton/core/backends/local.py
+++ b/anton/core/backends/local.py
@@ -24,6 +24,16 @@
 _BOOT_SCRIPT_PATH = Path(__file__).parent / "scratchpad_boot.py"
 
 
+def _read_boot_script() -> str:
+    """Read the boot script as UTF-8 explicitly.
+
+    It contains non-ASCII (…, —), so a host-locale-default read (e.g. GBK on
+    Chinese Windows) crashes with a codec error before the scratchpad can start
+    (ENG-824). Kept as a helper so the explicit encoding is pinned by a test.
+    """
+    return _BOOT_SCRIPT_PATH.read_text(encoding="utf-8")
+
+
 def _utf8_env(base: "os._Environ[str] | dict[str, str]") -> dict[str, str]:
     """A copy of ``base`` with Python UTF-8 mode forced for the scratchpad
     subprocess.
@@ -273,7 +283,12 @@ def _setup_parent_site_packages(self) -> None:
                     break
             if child_site and parent_site:
                 pth_path = os.path.join(child_site, "_parent_venv.pth")
-                with open(pth_path, "w") as f:
+                # UTF-8 explicitly: a plain open() encodes with the host locale
+                # (e.g. GBK on Chinese Windows), but the child reads .pth files
+                # as UTF-8 under UTF-8 mode — a mismatch corrupts non-ASCII
+                # site-packages paths (same class of bug as the boot script,
+                # ENG-824).
+                with open(pth_path, "w", encoding="utf-8") as f:
                     for sp in parent_site:
                         f.write(sp + "\n")
 
@@ -347,10 +362,7 @@ async def start(self) -> None:
         """Write the boot script to a temp file and launch the subprocess."""
         self._ensure_venv()
 
-        # Read/write the boot script as UTF-8 explicitly: it contains non-ASCII
-        # (…, —), so a host-locale-default read (e.g. GBK on Chinese Windows)
-        # crashes with a codec error before the scratchpad can start (ENG-824).
-        boot_code = _BOOT_SCRIPT_PATH.read_text(encoding="utf-8")
+        boot_code = _read_boot_script()
         fd, path = tempfile.mkstemp(suffix=".py", prefix="anton_scratchpad_")
         os.write(fd, boot_code.encode("utf-8"))
         os.close(fd)
diff --git a/tests/test_scratchpad_utf8.py b/tests/test_scratchpad_utf8.py
index bc2040c4..68447e3f 100644
--- a/tests/test_scratchpad_utf8.py
+++ b/tests/test_scratchpad_utf8.py
@@ -23,7 +23,7 @@ def test_utf8_env_respects_explicit_override():
     assert env["PYTHONUTF8"] == "0"
 
 
-def test_boot_script_must_be_read_as_utf8():
+def test_boot_script_content_requires_utf8():
     # The boot script contains non-ASCII (…, —). Reading it with a non-UTF-8
     # host-locale default (GBK on Chinese Windows) throws a UnicodeDecodeError
     # before the scratchpad can start — the exact ENG-824 crash. Guard that (a)
@@ -33,3 +33,21 @@ def test_boot_script_must_be_read_as_utf8():
     raw.decode("utf-8")  # the fix: explicit UTF-8 succeeds
     with pytest.raises(UnicodeDecodeError):
         raw.decode("gbk")  # a GBK-locale default read would crash
+
+
+def test_boot_script_is_read_as_utf8(monkeypatch):
+    # Pin the *read*, not just the file's bytes: if someone drops the explicit
+    # encoding="utf-8" (reverting to a host-locale default), this fails even on a
+    # UTF-8 CI box — where a bytes-only check would still pass. Spy on
+    # Path.read_text and assert the boot-script read passes encoding="utf-8".
+    seen = {}
+    real_read_text = local.Path.read_text
+
+    def spy(self, *args, **kwargs):
+        if self == local._BOOT_SCRIPT_PATH:
+            seen["encoding"] = kwargs.get("encoding")
+        return real_read_text(self, *args, **kwargs)
+
+    monkeypatch.setattr(local.Path, "read_text", spy)
+    assert local._read_boot_script()  # exercises the real read path
+    assert seen.get("encoding") == "utf-8"

From 1fc202fecbb69edf033abfaa4406c2daaf02b977 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Mon, 20 Jul 2026 11:27:04 -0700
Subject: [PATCH 16/33] test(scratchpad): pin the _parent_venv.pth write
 encoding (self-review, ENG-824)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-review of the review-response commit: I pinned the boot-script *read* as
UTF-8 but left the sibling .pth *write* fix untested — asymmetric with the exact
concern Zoran raised. Add a regression test that spies on open() and asserts the
_parent_venv.pth write passes encoding="utf-8" (bypasses the heavy __init__;
verified it fails if the encoding is dropped).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 tests/test_scratchpad_utf8.py | 37 +++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/tests/test_scratchpad_utf8.py b/tests/test_scratchpad_utf8.py
index 68447e3f..ab54ec5f 100644
--- a/tests/test_scratchpad_utf8.py
+++ b/tests/test_scratchpad_utf8.py
@@ -51,3 +51,40 @@ def spy(self, *args, **kwargs):
     monkeypatch.setattr(local.Path, "read_text", spy)
     assert local._read_boot_script()  # exercises the real read path
     assert seen.get("encoding") == "utf-8"
+
+
+def test_parent_venv_pth_is_written_as_utf8(tmp_path, monkeypatch):
+    # Sibling of the boot-script read: the child reads .pth files as UTF-8 under
+    # UTF-8 mode, so the parent must *write* _parent_venv.pth as UTF-8 or a
+    # non-ASCII site-packages path (e.g. a CJK Windows user dir) corrupts.
+    # Pin the write encoding without spinning up a real venv.
+    import builtins
+    import site
+
+    # Force the "running inside a venv" branch deterministically.
+    monkeypatch.setattr(local.sys, "prefix", "/venv")
+    monkeypatch.setattr(local.sys, "base_prefix", "/usr")
+    monkeypatch.setattr(site, "getsitepackages", lambda: ["/parent/site-packages"])
+
+    child_site = tmp_path / "lib" / "python3.11" / "site-packages"
+    child_site.mkdir(parents=True)
+
+    # Bypass the heavy __init__ (no network/subprocess) — the method only reads
+    # self._venv_dir.
+    runtime = object.__new__(local.LocalScratchpadRuntime)
+    runtime._venv_dir = str(tmp_path)
+
+    seen = {}
+    real_open = builtins.open
+
+    def spy_open(file, *args, **kwargs):
+        if str(file).endswith("_parent_venv.pth"):
+            seen["encoding"] = kwargs.get("encoding")
+        return real_open(file, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "open", spy_open)
+    runtime._setup_parent_site_packages()
+
+    assert seen.get("encoding") == "utf-8"  # assert before any later read
+    written = (child_site / "_parent_venv.pth").read_text(encoding="utf-8")
+    assert "/parent/site-packages" in written

From e0720ff4557a9cb29db85c757094c876697f1baa Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Tue, 21 Jul 2026 18:19:45 +0300
Subject: [PATCH 17/33] count turns without tools

---
 anton/commands/session.py     |  3 ++-
 anton/core/session.py         |  3 ++-
 anton/memory/history_store.py | 22 ++++++++++++++++++++--
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/anton/commands/session.py b/anton/commands/session.py
index cdd9d8df..a2526b8b 100644
--- a/anton/commands/session.py
+++ b/anton/commands/session.py
@@ -9,6 +9,7 @@
 from anton.config.settings import AntonSettings
 from anton.utils.prompt import prompt_or_cancel
 from anton.chat_session import rebuild_session
+from anton.memory.history_store import is_user_turn
 
 if TYPE_CHECKING:
     from anton.chat import ChatSession
@@ -121,7 +122,7 @@ async def restore_session(
         session_id=sid,
     )
     new_session._history = list(history)
-    new_session._turn_count = sum(1 for m in history if m.get("role") == "user")
+    new_session._turn_count = sum(1 for m in history if is_user_turn(m))
 
     console.print()
     console.print(
diff --git a/anton/core/session.py b/anton/core/session.py
index adbe78c8..8ea6f82e 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -20,6 +20,7 @@
 from anton.core.memory.cerebellum import Cerebellum
 from anton.core.memory.skills import SkillStore
 from anton.core.tools.recall_skill import RECALL_SKILL_TOOL
+from anton.memory.history_store import is_user_turn
 from anton.core.llm.prompts import (
     RESILIENCE_NUDGE,
     SCRATCHPAD_SIZE_NUDGE,
@@ -319,7 +320,7 @@ def __init__(self, config: ChatSessionConfig) -> None:
         )
         self._pending_memory_confirmations: list = []
         self._turn_count = (
-            sum(1 for m in self._history if m.get("role") == "user")
+            sum(1 for m in self._history if is_user_turn(m))
             if config.initial_history
             else 0
         )
diff --git a/anton/memory/history_store.py b/anton/memory/history_store.py
index 13c58efc..36045216 100644
--- a/anton/memory/history_store.py
+++ b/anton/memory/history_store.py
@@ -20,6 +20,24 @@
     from anton.core.memory.episodes import EpisodicMemory
 
 
+def is_user_turn(message: dict) -> bool:
+    """True for a genuine user turn.
+
+    A user-role message whose content is only ``tool_result`` blocks is the
+    reply to a tool call, not a new turn. Counting it would inflate turn
+    totals once tool activity is replayed back into history.
+    """
+    if message.get("role") != "user":
+        return False
+    content = message.get("content")
+    if not isinstance(content, list):
+        return True  # string / multimodal input is always a real turn
+    return not any(
+        isinstance(block, dict) and block.get("type") == "tool_result"
+        for block in content
+    )
+
+
 class HistoryStore:
     """Persist and retrieve full chat history for session resume."""
 
@@ -159,8 +177,8 @@ def list_sessions(self, limit: int = 20) -> list[dict]:
 
             session_id = path.stem.removesuffix("_history")
 
-            # Count user turns
-            turns = sum(1 for m in data if m.get("role") == "user")
+            # Count user turns (tool_result replies are not turns)
+            turns = sum(1 for m in data if is_user_turn(m))
             if turns == 0:
                 continue
 

From dff7076bf1f6e4d6a65e50ffee5b17af14408216 Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Tue, 21 Jul 2026 12:18:12 -0700
Subject: [PATCH 18/33] fix(llm): back off + retry mid-stream provider
 failures; typed transient errors (ENG-673) (#246)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(llm): back off + retry mid-stream provider failures; typed transient errors (ENG-673)

A mid-stream overload arrives inside an HTTP-200 stream (the SDK raises
APIStatusError with status_code=200, real reason in .body), so anton's
status-only classifier surfaced the nonsensical "Server returned 200 — the LLM
endpoint may be temporarily unavailable" and the session loop retried it
instantly with zero backoff — burning all attempts within seconds of a
minutes-long incident (BUG-CM-001, Anthropic incident 2026-07-08).

- New `TransientProviderError` / `ProviderOverloadedError` + a shared
  `classify_transient` in provider.py. Classify by BODY, not status:
  overloaded/api_error, 5xx, plain-429, connection drops, truncated streams.
- anthropic.py: refactor the two byte-identical status-only blocks into a shared
  `_raise_for_status_error` mirroring the ENG-598 openai mapper; openai.py:
  extend that mapper with the transient branch (covers all four paths).
- session.py: budget-bounded backoff-and-retry (30s/turn, cancellation-aware,
  jittered ~2/10/18s) for the mid-stream case that had NO prior retry; on
  exhaustion raise ProviderOverloadedError (carries model+provider) for the
  cowork-server/cowork `provider_overloaded` card. Completed tool_results are
  never re-executed on retry (idempotency) — only dangling tool_use is sealed.
- Split by prior-retry: request-time 5xx/429/connection errors (already
  SDK-retried) and truncated streams carry session_backoff=False — honest typed
  message, but fail fast instead of stacking another 30s.
- Log the (scrubbed, via ENG-583 scrub_credentials) error body on every
  transient occurrence.

Tests: tests/test_transient_retry.py (classifier, both mappers, backoff helpers,
turn-level recovery / budget-exhaustion / cancel / no-replay). Updated the two
ENG-598 mapper tests (429/500 now typed-transient) and the two e2e error-handling
tests (honest message, fast fail). Full suite green except the 2 pre-existing
environmental scratchpad-subprocess failures.

Part 1 of 3 for ENG-673 (cowork-server + cowork companions to follow).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(llm): address adversarial-review findings on the transient-retry path (ENG-673)

Self-review of the 3-PR stack surfaced four issues; fixing them here (anton
side):

- #1 (was a real regression): truncation detection raised whenever a stream
  ended with no finish_reason/stop_reason — but many OpenAI-compatible endpoints
  simply don't report one, so a COMPLETE, good answer was being discarded and
  turned into an error (and would fail every turn for such a provider). Now only
  the truly-empty case (no content AND no tool_calls) is treated as truncated;
  a content-bearing stream without a terminal marker is logged and passed
  through.
- #3: user-stop DURING backoff re-raised the TransientProviderError, surfacing a
  provider-error card instead of a clean cancellation. Now it breaks cleanly
  (like a normal stop).
- #4: ProviderOverloadedError always named the planning model even when the
  CODING model was the one that failed. TransientProviderError now carries the
  in-flight `model` (threaded through classify_transient + both providers' raise
  sites); the card names the actual failing model, falling back to planning.

Tests updated for the new clean-cancel semantics + 2 new (model propagation,
failing-model-not-planning). Full suite green (bar the 2 pre-existing
environmental scratchpad failures).

(#2 — an overstated "graceful degradation" claim — corrected in the PR #246
description, no code change.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(llm): regression guards for the truncation fix — content-without-finish_reason passes through, empty stream truncates (ENG-673)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(session): don't tell the model to "adjust your approach" on a provider blip (ENG-673 #6)

A request-time TransientProviderError (5xx / rate-limit / dropped connection)
reaching the count-based retry path was injected as "An error interrupted
execution… adjust your approach to avoid the same error" — but that's a service
hiccup, not the model's fault, so the note misattributes the failure and can
degrade the next attempt mid-incident. Transient errors now get a neutral note
("a transient service issue, not a problem with your approach — continue as
planned"); genuine errors keep the original recovery guidance.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(llm): recover mid-stream connection/APIError failures; keep empty-truncated fail-fast (ENG-673)

Review-round fixes (Sam/SailingSF, anton#246):
- session_backoff now means "did the SDK already retry?" — mid-stream failures
  (connection drop after the 200, read timeout) back off within the budget;
  request-establishment failures still fail fast. Adds a stream_started flag on
  all three streaming paths (anthropic, openai chat.completions, Responses API).
- Catch the bare openai.APIError a mid-stream SSE error raises (it is NOT an
  APIStatusError) so the OpenAI/MindsHub path classifies + backs off instead of
  leaking a generic error; classify_transient now reads both the Anthropic
  (nested) and OpenAI (unwrapped, top-level) body dialects.
- Empty-from-start truncated stream stays fail-fast: a broken/misconfigured
  endpoint must not loop the 30s budget (product decision; carved out of the
  ticket's "truncated -> recover").
- Real-SDK mock harness (tests/test_transient_retry_e2e.py) over
  httpx.MockTransport; resolves the dangling test_transient_retry_e2e reference.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/llm/anthropic.py                | 138 +++++--
 anton/core/llm/openai.py                   | 139 ++++++-
 anton/core/llm/provider.py                 | 109 +++++
 anton/core/session.py                      | 122 +++++-
 tests/e2e/scenarios/test_error_handling.py |   6 +-
 tests/test_status_error_mapper.py          |  31 +-
 tests/test_transient_retry.py              | 456 +++++++++++++++++++++
 tests/test_transient_retry_e2e.py          | 189 +++++++++
 8 files changed, 1122 insertions(+), 68 deletions(-)
 create mode 100644 tests/test_transient_retry.py
 create mode 100644 tests/test_transient_retry_e2e.py

diff --git a/anton/core/llm/anthropic.py b/anton/core/llm/anthropic.py
index 7ca41555..bf817bc1 100644
--- a/anton/core/llm/anthropic.py
+++ b/anton/core/llm/anthropic.py
@@ -1,10 +1,13 @@
 from __future__ import annotations
 
-import json
+import logging
 from collections.abc import AsyncIterator
+from typing import NoReturn
 
 import anthropic
 
+from anton.utils.datasources import scrub_credentials
+
 from .provider import safe_parse_tool_input
 from .provider import (
     ContextOverflowError,
@@ -17,11 +20,57 @@
     StreamToolUseDelta,
     StreamToolUseEnd,
     StreamToolUseStart,
+    TokenLimitExceeded,
     ToolCall,
+    TransientProviderError,
     Usage,
+    classify_transient,
     compute_context_pressure,
 )
 
+logger = logging.getLogger(__name__)
+
+
+def _raise_for_status_error(
+    exc: anthropic.APIStatusError, *, provider: str = "Anthropic", model: str = "",
+) -> NoReturn:
+    """Map an Anthropic HTTP error onto anton's typed/curated exceptions.
+
+    Shared by ``complete`` and ``stream`` so the mapping can't drift (the two
+    were byte-identical copy-paste before ENG-673). Order matters — permanent
+    failures are classified first; only what's left is offered to the transient
+    classifier, and the generic "unavailable" copy is the last resort.
+
+    - 401 → ConnectionError (invalid-key copy; cowork-server keys on this phrase).
+    - 429 WITH a quota ``detail`` → TokenLimitExceeded (keeps its own card).
+    - overloaded/api_error (incl. the mid-stream HTTP-200 case), 5xx, plain 429
+      → TransientProviderError (retryable — see ENG-673).
+    - anything else → the generic "temporarily unavailable" ConnectionError.
+    """
+    if exc.status_code == 401:
+        raise ConnectionError(
+            "Invalid API key — check your ANTHROPIC_API_KEY environment variable."
+        ) from exc
+
+    body = exc.body if isinstance(exc.body, dict) else {}
+    if exc.status_code == 429 and body.get("detail"):
+        msg = f"Server returned 429 — {body['detail']}"
+        msg += " Visit https://console.mindshub.ai to upgrade or to top up your tokens."
+        raise TokenLimitExceeded(msg) from exc
+
+    transient = classify_transient(exc.status_code, body, provider=provider, model=model)
+    if transient is not None:
+        logger.warning(
+            "transient provider error (%s): status=%s body=%s",
+            transient.code, exc.status_code, scrub_credentials(str(exc.body))[:500],
+        )
+        raise transient from exc
+
+    raise ConnectionError(
+        f"Server returned {exc.status_code} — the LLM endpoint may be "
+        "temporarily unavailable. Try again in a moment."
+    ) from exc
+
 # Native server-side web tool type strings exposed by the Anthropic Messages API.
 # The model invokes these inside the provider — Anton's tool-dispatch loop never
 # sees a tool_use for them; the model's final text content already incorporates
@@ -118,25 +167,15 @@ async def complete(
                 raise ContextOverflowError(str(exc)) from exc
             raise
         except anthropic.APIStatusError as exc:
-            if exc.status_code == 401:
-                msg = "Invalid API key — check your ANTHROPIC_API_KEY environment variable."
-                raise ConnectionError(msg) from exc
-            elif (
-                exc.status_code == 429
-                and isinstance(exc.body, dict)
-                and exc.body.get("detail")
-            ):
-                msg = f"Server returned 429 — {exc.body['detail']}"
-                msg += " Visit https://console.mindshub.ai to upgrade or to top up your tokens."
-                from .provider import TokenLimitExceeded
-
-                raise TokenLimitExceeded(msg) from exc
-            else:
-                msg = f"Server returned {exc.status_code} — the LLM endpoint may be temporarily unavailable. Try again in a moment."
-            raise ConnectionError(msg) from exc
+            _raise_for_status_error(exc, model=model)
         except anthropic.APIConnectionError as exc:
-            raise ConnectionError(
-                "Could not reach the LLM server — check your connection or try again in a moment."
+            # Transient, but the SDK already retries connection errors at the
+            # transport layer — so classify honestly and fail fast rather than
+            # stacking the session budget on top (ENG-673).
+            raise TransientProviderError(
+                "Could not reach Anthropic — check your connection or try again in a moment.",
+                provider="Anthropic", code="connection_error", session_backoff=False,
+                model=model,
             ) from exc
 
         content_text = ""
@@ -197,8 +236,15 @@ async def stream(
         # Track content blocks by index for tool correlation
         blocks: dict[int, dict] = {}
 
+        # True once the 200 stream has been established. Anything that fails
+        # AFTER this point is mid-stream: the SDK's retry wrapper already
+        # returned, so it never retried — the session must (ENG-673). A failure
+        # BEFORE this (request establishment) was already SDK-retried → fail fast.
+        stream_started = False
+
         try:
             async with self._client.messages.stream(**kwargs) as stream:
+                stream_started = True
                 async for event in stream:
                     if event.type == "message_start":
                         usage = event.message.usage
@@ -265,27 +311,45 @@ async def stream(
                 raise ContextOverflowError(str(exc)) from exc
             raise
         except anthropic.APIStatusError as exc:
-            if exc.status_code == 401:
-                msg = "Invalid API key — check your ANTHROPIC_API_KEY environment variable."
-                raise ConnectionError(msg) from exc
-            elif (
-                exc.status_code == 429
-                and isinstance(exc.body, dict)
-                and exc.body.get("detail")
-            ):
-                msg = f"Server returned 429 — {exc.body['detail']}"
-                msg += " Visit https://console.mindshub.ai to upgrade or to top up your tokens."
-                from .provider import TokenLimitExceeded
-
-                raise TokenLimitExceeded(msg) from exc
-            else:
-                msg = f"Server returned {exc.status_code} — the LLM endpoint may be temporarily unavailable. Try again in a moment."
-            raise ConnectionError(msg) from exc
+            _raise_for_status_error(exc, model=model)
         except anthropic.APIConnectionError as exc:
-            raise ConnectionError(
-                "Could not reach the LLM server — check your connection or try again in a moment."
+            # A connection error here is retryable. If it dropped mid-stream
+            # (after the 200), the SDK never retried it → the session must back
+            # off and retry. If it failed during request establishment, the SDK
+            # already retried → fail fast (no second budget on top). (ENG-673)
+            raise TransientProviderError(
+                "Lost the connection to Anthropic mid-response — try again in a moment."
+                if stream_started
+                else "Could not reach Anthropic — check your connection or try again in a moment.",
+                provider="Anthropic", code="connection_error",
+                session_backoff=stream_started, model=model,
             ) from exc
 
+        # Missing stop_reason is a genuine truncation only when the stream
+        # produced NOTHING. A content/tool-bearing stream that lacks it is almost
+        # always a provider that doesn't report one — treating THAT as truncated
+        # would discard a complete, good answer, so we log and pass it through.
+        # Only the truly-empty case is transient (fail-fast). (ENG-673)
+        if stop_reason is None:
+            if content_text or tool_calls:
+                logger.warning("Anthropic stream ended with no stop_reason but produced output — "
+                               "passing through")
+            else:
+                logger.warning("Anthropic stream ended empty with no stop_reason — treating as truncated")
+                # Deliberate carve-out (ENG-673): this branch fires ONLY when the
+                # stream produced NOTHING (a content-bearing stream with no
+                # stop_reason passes through above). An empty-from-start 200 is a
+                # weak incident signal and a strong broken/misconfigured-endpoint
+                # signal, so it fails fast rather than looping the 30s budget on an
+                # endpoint that never emits. Genuine mid-incident silence surfaces
+                # instead as a connection drop / read timeout / SSE error event —
+                # all of which DO back off (session_backoff=True) above.
+                raise TransientProviderError(
+                    "Anthropic ended the response early — try again in a moment.",
+                    provider="Anthropic", code="truncated_stream",
+                    session_backoff=False, model=model,
+                )
+
         yield StreamComplete(
             response=LLMResponse(
                 content=content_text,
diff --git a/anton/core/llm/openai.py b/anton/core/llm/openai.py
index 9d00cf48..19e5c539 100644
--- a/anton/core/llm/openai.py
+++ b/anton/core/llm/openai.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import os
 from collections.abc import AsyncIterator
 from typing import NoReturn
@@ -8,6 +9,8 @@
 import openai
 from openai import AsyncAzureOpenAI
 
+from anton.utils.datasources import scrub_credentials
+
 from .provider import safe_parse_tool_input
 from .provider import (
     ContextOverflowError,
@@ -23,10 +26,14 @@
     StreamToolUseStart,
     TokenLimitExceeded,
     ToolCall,
+    TransientProviderError,
     Usage,
+    classify_transient,
     compute_context_pressure,
 )
 
+logger = logging.getLogger(__name__)
+
 
 def _raise_for_status_error(exc: "openai.APIStatusError", model: str) -> NoReturn:
     """Map a provider HTTP error onto anton's typed/curated exceptions.
@@ -103,6 +110,17 @@ def _raise_for_status_error(exc: "openai.APIStatusError", model: str) -> NoRetur
             )
         raise ModelUnavailableError(msg, code=code, model=model) from exc
 
+    # Retryable provider/infra failures — overload/api_error (incl. the mid-stream
+    # HTTP-200 case), 5xx, or a plain 429 — get backed off and retried by the
+    # session loop rather than surfacing an instant, misleading failure (ENG-673).
+    transient = classify_transient(exc.status_code, body, provider="The model provider", model=model)
+    if transient is not None:
+        logger.warning(
+            "transient provider error (%s): status=%s body=%s",
+            transient.code, exc.status_code, scrub_credentials(str(exc.body))[:500],
+        )
+        raise transient from exc
+
     raise ConnectionError(
         f"Server returned {exc.status_code} — the LLM endpoint may be "
         "temporarily unavailable. Try again in a moment."
@@ -811,8 +829,13 @@ async def complete(
         except openai.APIStatusError as exc:
             _raise_for_status_error(exc, model)
         except openai.APIConnectionError as exc:
-            raise ConnectionError(
-                "Could not reach the LLM server — check your connection or try again in a moment."
+            # Transient, but the SDK already retries connection errors at the
+            # transport layer — classify honestly and fail fast rather than
+            # stacking the session budget on top (ENG-673).
+            raise TransientProviderError(
+                "Could not reach the model provider — check your connection or try again in a moment.",
+                provider="The model provider", code="connection_error", session_backoff=False,
+                model=model,
             ) from exc
 
         choice = response.choices[0]
@@ -902,8 +925,15 @@ async def stream(
         # Track tool call deltas by index
         tc_state: dict[int, dict] = {}
 
+        # True once the 200 stream has been established. Anything that fails
+        # AFTER this point is mid-stream: the SDK's retry wrapper already
+        # returned, so it never retried — the session must (ENG-673). A failure
+        # BEFORE this (request establishment) was already SDK-retried → fail fast.
+        stream_started = False
+
         try:
             stream = await self._client.chat.completions.create(**kwargs)
+            stream_started = True
             async for chunk in stream:
                 if chunk.usage:
                     input_tokens = chunk.usage.prompt_tokens
@@ -965,8 +995,39 @@ async def stream(
         except openai.APIStatusError as exc:
             _raise_for_status_error(exc, model)
         except openai.APIConnectionError as exc:
-            raise ConnectionError(
-                "Could not reach the LLM server — check your connection or try again in a moment."
+            # A connection error here is retryable. If it dropped mid-stream
+            # (after the 200), the SDK never retried it → the session must back
+            # off and retry. If it failed during request establishment, the SDK
+            # already retried → fail fast (no second budget on top). (ENG-673)
+            raise TransientProviderError(
+                "Lost the connection to the model provider mid-response — try again in a moment."
+                if stream_started
+                else "Could not reach the model provider — check your connection or try again in a moment.",
+                provider="The model provider", code="connection_error",
+                session_backoff=stream_started, model=model,
+            ) from exc
+        except openai.APIError as exc:
+            # A mid-stream SSE `error` event (server_error / overloaded) arrives
+            # as a BARE APIError with no status_code — NOT an APIStatusError — so
+            # it slips past the handlers above. The SDK already consumed the 200,
+            # so it never retried it → the session must back off and retry, and we
+            # must classify it here or it surfaces as an opaque generic error on
+            # the OpenAI/MindsHub path (ENG-673, Sam's review). Body type sits at
+            # the top level (SDK-unwrapped); classify_transient handles that shape.
+            transient = classify_transient(
+                getattr(exc, "status_code", None), getattr(exc, "body", None),
+                provider="The model provider", model=model,
+            )
+            if transient is not None:
+                logger.warning(
+                    "transient mid-stream provider error (%s): %s",
+                    transient.code, scrub_credentials(str(getattr(exc, "body", "")))[:500],
+                )
+                raise transient from exc
+            raise TransientProviderError(
+                "The model provider failed mid-response — try again in a moment.",
+                provider="The model provider", code="stream_error",
+                session_backoff=True, model=model,
             ) from exc
 
         # Finalize tool calls. Same safe-parse protection as the
@@ -985,6 +1046,32 @@ async def stream(
             ))
             yield StreamToolUseEnd(id=info["id"])
 
+        # Missing finish_reason is ambiguous: it's a genuine truncation only when
+        # the stream produced NOTHING (empty + no terminal marker). A stream that
+        # produced content/tool_calls but no finish_reason is almost always a
+        # provider that just doesn't report one (many OpenAI-compatible endpoints)
+        # — treating THAT as truncated would discard a complete, good answer, so
+        # we log and pass it through. Only the truly-empty case is transient
+        # (fail-fast: a persistently-malformed endpoint must not loop). (ENG-673)
+        if stop_reason is None:
+            if content_text or tool_calls:
+                logger.warning("stream ended with no finish_reason but produced output — "
+                               "passing through (provider likely omits finish_reason)")
+            else:
+                logger.warning("stream ended empty with no finish_reason — treating as truncated")
+                # Deliberate carve-out (ENG-673): fires ONLY on a stream that
+                # produced NOTHING. An empty-from-start 200 is a weak incident
+                # signal and a strong broken/misconfigured-endpoint signal, so it
+                # fails fast rather than looping the 30s budget on an endpoint that
+                # never emits. Genuine mid-incident silence surfaces instead as a
+                # connection drop / read timeout / SSE error — all of which DO back
+                # off above. Keeps a persistently-malformed endpoint from looping.
+                raise TransientProviderError(
+                    "The model provider ended the response early — try again in a moment.",
+                    provider="The model provider", code="truncated_stream",
+                    session_backoff=False, model=model,
+                )
+
         yield StreamComplete(
             response=LLMResponse(
                 content=content_text,
@@ -1068,8 +1155,13 @@ async def _complete_via_responses(
         except openai.APIStatusError as exc:
             _raise_for_status_error(exc, model)
         except openai.APIConnectionError as exc:
-            raise ConnectionError(
-                "Could not reach the LLM server — check your connection or try again in a moment."
+            # Transient, but the SDK already retries connection errors at the
+            # transport layer — classify honestly and fail fast rather than
+            # stacking the session budget on top (ENG-673).
+            raise TransientProviderError(
+                "Could not reach the model provider — check your connection or try again in a moment.",
+                provider="The model provider", code="connection_error", session_backoff=False,
+                model=model,
             ) from exc
 
         return _parse_response_object(response, model)
@@ -1105,8 +1197,13 @@ async def _stream_via_responses(
         # a per-output_index stable handle for streaming arguments.
         fc_state: dict[int, dict] = {}
 
+        # See the chat-completions path: True once the 200 stream is established;
+        # a failure after this is mid-stream and was never SDK-retried (ENG-673).
+        stream_started = False
+
         try:
             stream = await self._client.responses.create(**kwargs)
+            stream_started = True
             async for event in stream:
                 etype = getattr(event, "type", "")
 
@@ -1182,8 +1279,34 @@ async def _stream_via_responses(
         except openai.APIStatusError as exc:
             _raise_for_status_error(exc, model)
         except openai.APIConnectionError as exc:
-            raise ConnectionError(
-                "Could not reach the LLM server — check your connection or try again in a moment."
+            # A connection error here is retryable. Mid-stream (after the 200) was
+            # never SDK-retried → session backs off; request-establishment was
+            # already SDK-retried → fail fast (ENG-673).
+            raise TransientProviderError(
+                "Lost the connection to the model provider mid-response — try again in a moment."
+                if stream_started
+                else "Could not reach the model provider — check your connection or try again in a moment.",
+                provider="The model provider", code="connection_error",
+                session_backoff=stream_started, model=model,
+            ) from exc
+        except openai.APIError as exc:
+            # Bare mid-stream SSE error (no status_code) — not an APIStatusError,
+            # so it slips past the handlers above; the SDK already consumed the
+            # 200 and never retried it → the session must back off (ENG-673).
+            transient = classify_transient(
+                getattr(exc, "status_code", None), getattr(exc, "body", None),
+                provider="The model provider", model=model,
+            )
+            if transient is not None:
+                logger.warning(
+                    "transient mid-stream provider error (%s): %s",
+                    transient.code, scrub_credentials(str(getattr(exc, "body", "")))[:500],
+                )
+                raise transient from exc
+            raise TransientProviderError(
+                "The model provider failed mid-response — try again in a moment.",
+                provider="The model provider", code="stream_error",
+                session_backoff=True, model=model,
             ) from exc
 
         yield StreamComplete(
diff --git a/anton/core/llm/provider.py b/anton/core/llm/provider.py
index 19732fd3..7831cd2e 100644
--- a/anton/core/llm/provider.py
+++ b/anton/core/llm/provider.py
@@ -312,6 +312,115 @@ class TokenLimitExceeded(Exception):
     """Raised when the LLM returns 429 due to billing/token limits."""
 
 
+class TransientProviderError(ConnectionError):
+    """Raised when the provider fails in a way that a retry might fix.
+
+    Covers provider/infra-side hiccups — an ``overloaded_error``/``api_error``
+    event (including the mid-stream case that arrives inside an HTTP-200 stream,
+    see ENG-673), a 5xx, a plain 429 (no quota detail), a dropped connection, or
+    a truncated stream. The session loop backs off and retries these within a
+    bounded budget; distinct from auth/quota/model-gate failures, which are
+    permanent for the identical request and must fail fast.
+
+    Subclasses ConnectionError so legacy call sites that only know the
+    ConnectionError mapping keep working unchanged.
+    """
+
+    def __init__(
+        self, message: str, *, provider: str = "", code: str | None = None,
+        retry_after: float | None = None, session_backoff: bool = True,
+        model: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.provider = provider
+        self.code = code
+        self.retry_after = retry_after
+        # The model that was in flight when this failed — so a downstream
+        # ProviderOverloadedError names the ACTUAL model (planning OR coding),
+        # not whatever the session defaults to (ENG-673).
+        self.model = model
+        # Whether the SESSION should spend its backoff budget on this (ENG-673).
+        # True for failures that had NO prior retry — a mid-stream error (arrives
+        # inside an HTTP-200 stream), a dropped connection, or a truncated stream.
+        # False for request-time HTTP errors (real 4xx/5xx): the SDK already
+        # retried those with backoff, so the session fails fast (still with the
+        # honest typed message) instead of stacking another 30s on top.
+        self.session_backoff = session_backoff
+
+
+class ProviderOverloadedError(ConnectionError):
+    """Terminal form of a transient failure: the retry budget was exhausted.
+
+    Carries the failing ``model`` + ``provider`` so cowork-server can render the
+    ``provider_overloaded`` card (the MindsHub cross-provider-failover nudge).
+    Typed consumers read ``code``/``model``/``provider``; it subclasses
+    ConnectionError for legacy call sites.
+    """
+
+    def __init__(
+        self, message: str, *, provider: str = "", model: str = "",
+        code: str = "provider_overloaded",
+    ) -> None:
+        super().__init__(message)
+        self.provider = provider
+        self.model = model
+        self.code = code
+
+
+# Body ``error.type``/``error.code`` values that mean "provider is momentarily
+# failing" — retryable. The mid-stream overload arrives with one of these inside
+# an HTTP-200 stream (ENG-673), so classification must read the body, not status.
+_TRANSIENT_ERROR_TYPES = frozenset(
+    {"overloaded_error", "overloaded", "api_error", "server_error", "service_unavailable"}
+)
+
+
+def classify_transient(
+    status_code: int | None, body: Any, *, provider: str = "", model: str = ""
+) -> "TransientProviderError | None":
+    """Arm A of the transient classifier (see ENG-673): inspect an
+    ``APIStatusError``'s status + body and return a ``TransientProviderError`` if
+    it's a retryable provider/infra failure, else ``None``.
+
+    Shared by both providers so the mapping can't drift. Call this only AFTER the
+    permanent classifications (401 / 429-quota / 403 model-gate) have been ruled
+    out — this decides between "retryable transient" and "generic unavailable".
+    """
+    b = body if isinstance(body, dict) else {}
+    # Two body dialects: Anthropic nests the error under `error` ({"error":
+    # {"type": ...}}); the OpenAI SDK unwraps its envelope (`body.get("error",
+    # body)`) so the type sits at the TOP level. Read the nested object when
+    # present, otherwise treat the body itself as the error object — so the
+    # mid-stream case classifies on BOTH providers (ENG-673, Sam's review).
+    err = b.get("error") if isinstance(b.get("error"), dict) else b
+    etype = err.get("type") or err.get("code")
+    # A mid-stream failure has no real HTTP error status (it's smuggled into an
+    # already-sent 200, or there's no status at all), so the SDK never retried it
+    # → the session must. A request-time error carries a real 4xx/5xx → the SDK
+    # already retried → fail fast.
+    session_backoff = status_code is None or status_code == 200
+    if isinstance(etype, str) and etype in _TRANSIENT_ERROR_TYPES:
+        # Explicit overload/api_error — the body is authoritative (status may be
+        # a misleading 200 mid-stream, or a real 529 at request time).
+        return TransientProviderError(
+            f"{provider or 'The model provider'} is momentarily overloaded.",
+            provider=provider, code=etype, session_backoff=session_backoff, model=model,
+        )
+    if isinstance(status_code, int) and 500 <= status_code < 600:
+        return TransientProviderError(
+            f"{provider or 'The model provider'} returned {status_code}.",
+            provider=provider, code=f"http_{status_code}", session_backoff=False, model=model,
+        )
+    if status_code == 429 and not b.get("detail"):
+        # Plain rate-limit ("slow down"), NOT an out-of-quota 429 (that carries a
+        # `detail` and is mapped to TokenLimitExceeded upstream of this call).
+        return TransientProviderError(
+            f"{provider or 'The model provider'} is rate-limiting requests.",
+            provider=provider, code="rate_limited", session_backoff=False, model=model,
+        )
+    return None
+
+
 class ModelUnavailableError(ConnectionError):
     """Raised when the gateway rejects the requested model with a structured 403.
 
diff --git a/anton/core/session.py b/anton/core/session.py
index adbe78c8..18bee9ab 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import random
 from collections.abc import AsyncIterator, Callable
 from dataclasses import asdict, dataclass, field, replace
 from datetime import datetime
@@ -28,6 +29,7 @@
 from anton.core.llm.provider import (
     ContextOverflowError,
     ModelUnavailableError,
+    ProviderOverloadedError,
     StreamComplete,
     StreamContextCompacted,
     StreamEvent,
@@ -36,6 +38,7 @@
     StreamToolResult,
     TokenLimitExceeded,
     ToolCall,
+    TransientProviderError,
 )
 from anton.core.llm.tracing import (
     TraceContext,
@@ -287,6 +290,11 @@ class ChatSessionConfig:
 class ChatSession:
     """Manages a multi-turn conversation with tool-call delegation."""
 
+    # ENG-673: wall-clock budget for backing off + retrying transient provider
+    # failures within a single turn. Class attribute so it's tunable (a future
+    # per-surface / config knob) and injectable in tests.
+    _transient_budget_s: float = 30.0
+
     def __init__(self, config: ChatSessionConfig) -> None:
         s = config.settings or CoreSettings()
         # Stash the full settings object (may be AntonSettings, CoreSettings,
@@ -1089,6 +1097,34 @@ def _compact_scratchpads(self) -> bool:
                 compacted = True
         return compacted
 
+    @staticmethod
+    def _transient_backoff_delay(attempt: int, retry_after: float | None = None) -> float:
+        """Backoff for a transient-provider retry (ENG-673).
+
+        Honors a provider `retry_after` when present (usually only on
+        request-time 429/529 — the mid-stream 200 case carries none). Otherwise
+        ~2s → ~10s → ~18s with ±20% jitter, so a fleet recovering from the same
+        incident doesn't retry in lockstep against an already-struggling provider.
+        """
+        if retry_after is not None and retry_after > 0:
+            return min(float(retry_after), 30.0)
+        base = (2.0, 10.0, 18.0)
+        d = base[attempt] if attempt < len(base) else base[-1]
+        return d * (0.8 + 0.4 * random.random())
+
+    async def _backoff_sleep(self, delay: float) -> bool:
+        """Sleep `delay` seconds, waking early if the turn is cancelled.
+
+        Returns True if cancelled during the wait, False if the full delay
+        elapsed — so a user hitting stop during backoff aborts immediately
+        instead of waiting out the incident (ENG-673).
+        """
+        try:
+            await asyncio.wait_for(self._cancel_event.wait(), timeout=delay)
+            return True  # _cancel_event fired
+        except asyncio.TimeoutError:
+            return False  # slept the full delay
+
     def _seal_dangling_tool_uses(self, reason: str = "interrupted") -> int:
         """Append synthetic `tool_result` blocks for any unmatched
         `tool_use` blocks in the last assistant message.
@@ -1698,6 +1734,14 @@ async def turn_stream(
         assistant_text_parts: list[str] = []
         _max_auto_retries = 2
         _retry_count = 0
+        # ENG-673: a mid-stream provider failure that had NO prior retry (an
+        # overload smuggled into an HTTP-200 stream) gets budget-bounded
+        # backoff-and-retry — separate from the instant, count-bounded recovery
+        # used for genuine errors. The clock starts on the first such error and
+        # is measured across the turn. Request-time transients (real 5xx/429,
+        # connection errors) carry session_backoff=False and skip this path.
+        _transient_deadline: float | None = None
+        _transient_attempt = 0
         self._active_explainability = ExplainabilityCollector(
             self._explainability_store,
             turn=self._turn_count + 1,
@@ -1737,6 +1781,51 @@ async def turn_stream(
                     # map them to their cards.
                     if isinstance(_agent_exc, (TokenLimitExceeded, ModelUnavailableError)):
                         raise
+
+                    # ENG-673: a mid-stream transient failure that had NO prior
+                    # retry (overload smuggled into a 200, or a truncated stream).
+                    # Back off and retry the SAME step within a per-turn budget —
+                    # do NOT inject a "you errored, change approach" note (it was
+                    # a provider blip, not the model's fault) and do NOT spend the
+                    # count-based retry budget reserved for genuine errors.
+                    # Completed tool_results already sit in history and are never
+                    # re-executed on retry (idempotency); we only seal any
+                    # tool_use the interrupted stream left dangling so the retried
+                    # request is valid. Request-time transients (real 5xx/429,
+                    # connection errors) set session_backoff=False — the SDK
+                    # already retried them, so they fall through to the fast
+                    # count-based path below with their honest typed message.
+                    if isinstance(_agent_exc, TransientProviderError) and _agent_exc.session_backoff:
+                        now = asyncio.get_running_loop().time()
+                        if _transient_deadline is None:
+                            _transient_deadline = now + self._transient_budget_s
+                        self._seal_dangling_tool_uses("interrupted by a transient provider error")
+                        remaining = _transient_deadline - now
+                        if remaining > 0.5:
+                            delay = min(
+                                self._transient_backoff_delay(
+                                    _transient_attempt, _agent_exc.retry_after
+                                ),
+                                remaining,
+                            )
+                            _transient_attempt += 1
+                            if await self._backoff_sleep(delay):
+                                # User cancelled during backoff — stop cleanly
+                                # (like a normal stop), not with an error card.
+                                break
+                            continue
+                        # Budget exhausted — fail with an actionable, honest error
+                        # the server renders as the provider_overloaded card.
+                        # Name the model that actually failed (planning OR coding),
+                        # falling back to the session's planning model.
+                        raise ProviderOverloadedError(
+                            f"{_agent_exc.provider or 'The model provider'} is experiencing an "
+                            "incident and didn't recover in time.",
+                            provider=getattr(_agent_exc, "provider", "") or "",
+                            model=(getattr(_agent_exc, "model", "") or "")
+                            or getattr(self._llm, "planning_model", "") or "",
+                        ) from _agent_exc
+
                     _retry_count += 1
                     # Anthropic's API rejects any history where the
                     # message after a `tool_use` lacks matching
@@ -1750,18 +1839,27 @@ async def turn_stream(
                     # and we get the same 400 forever.
                     self._seal_dangling_tool_uses("interrupted by error")
                     if _retry_count <= _max_auto_retries:
-                        # Inject the error into history and let the LLM try to recover
-                        self._append_history(
-                            {
-                                "role": "user",
-                                "content": (
-                                    f"SYSTEM: An error interrupted execution: {_agent_exc}\n\n"
-                                    "If you can diagnose and fix the issue, continue working on the task. "
-                                    "Adjust your approach to avoid the same error. "
-                                    "If this is unrecoverable, summarize what you accomplished and suggest next steps."
-                                ),
-                            }
-                        )
+                        # Inject the error into history and let the LLM try to
+                        # recover. A TransientProviderError reaching here is a
+                        # request-time provider blip (5xx / rate-limit / dropped
+                        # connection) — NOT the model's fault, so don't tell it to
+                        # "adjust your approach" (that misattributes the failure
+                        # and can degrade the next attempt during an incident);
+                        # just note it was transient and continue as planned (ENG-673).
+                        if isinstance(_agent_exc, TransientProviderError):
+                            recovery_note = (
+                                f"SYSTEM: A temporary provider error interrupted execution: {_agent_exc}\n\n"
+                                "This was a transient service issue, not a problem with your approach — "
+                                "continue the task as planned."
+                            )
+                        else:
+                            recovery_note = (
+                                f"SYSTEM: An error interrupted execution: {_agent_exc}\n\n"
+                                "If you can diagnose and fix the issue, continue working on the task. "
+                                "Adjust your approach to avoid the same error. "
+                                "If this is unrecoverable, summarize what you accomplished and suggest next steps."
+                            )
+                        self._append_history({"role": "user", "content": recovery_note})
                         # Continue the while loop — _stream_and_handle_tools will be called
                         # again with the error context now in history
                         continue
diff --git a/tests/e2e/scenarios/test_error_handling.py b/tests/e2e/scenarios/test_error_handling.py
index 731d19f5..a183d4f9 100644
--- a/tests/e2e/scenarios/test_error_handling.py
+++ b/tests/e2e/scenarios/test_error_handling.py
@@ -47,8 +47,10 @@ def log_message(self, *_): pass
 
     assert_exit_ok(result)
     assert_not_output(result, "Traceback (most recent call last)")
-    # After 3 retries the fallback text surfaces the ConnectionError message (openai.py:364)
-    assert_output(result, "Server returned 500")
+    # ENG-673: a request-time 5xx is now classified as a transient provider error
+    # and (since the SDK already retried it) fails fast with the honest typed
+    # message rather than the old "Server returned 500" phrasing.
+    assert_output(result, "returned 500")
 
 
 @pytest.mark.stub_only
diff --git a/tests/test_status_error_mapper.py b/tests/test_status_error_mapper.py
index beb8212d..a528b12c 100644
--- a/tests/test_status_error_mapper.py
+++ b/tests/test_status_error_mapper.py
@@ -26,7 +26,11 @@
 import pytest
 
 from anton.core.llm.openai import _raise_for_status_error
-from anton.core.llm.provider import ModelUnavailableError, TokenLimitExceeded
+from anton.core.llm.provider import (
+    ModelUnavailableError,
+    TokenLimitExceeded,
+    TransientProviderError,
+)
 
 
 def _sdk_error(status_code, json_body=None, text_body=None):
@@ -114,17 +118,23 @@ def test_429_enveloped_detail_also_maps_to_token_limit():
     # the `detail` field, the SDK unwraps it to top level — still classified.
     # (An envelope carrying only `message` — OpenAI's own quota dialect —
     # deliberately stays generic; see the mapper docstring's known limits.)
+    # Classified before the transient path (429+detail → quota), so ENG-673's
+    # bare-429-is-transient change leaves this untouched.
     exc = _sdk_error(429, json_body={"error": {"detail": "Monthly limit exceeded for tokens: 5/5"}})
     with pytest.raises(TokenLimitExceeded) as err:
         _raise_for_status_error(exc, "sonnet")
     assert "Monthly limit exceeded" in str(err.value)
 
 
-def test_bare_429_stays_generic():
+def test_bare_429_is_transient_fail_fast():
+    # ENG-673: a plain 429 (no quota detail) is a retryable rate-limit, but the
+    # SDK already retried it at request time → fail fast (no session backoff).
+    # Replaces the old test_bare_429_stays_generic — this path is now typed.
     exc = _sdk_error(429, json_body={})
-    with pytest.raises(ConnectionError) as err:
+    with pytest.raises(TransientProviderError) as err:
         _raise_for_status_error(exc, "sonnet")
-    assert "temporarily unavailable" in str(err.value)
+    assert err.value.session_backoff is False
+    assert "rate-limiting" in str(err.value).lower()
 
 
 def test_429_list_detail_stays_generic():
@@ -239,10 +249,13 @@ def test_429_with_detail_wins_even_if_error_code_present():
         _raise_for_status_error(exc, "sonnet")
 
 
-# ── other statuses stay generic ───────────────────────────────────────
+# ── 5xx / infra failures are transient (ENG-673) ──────────────────────
 
-def test_500_stays_generic():
-    exc = _sdk_error(500, json_body={"error": {"message": "boom"}})
-    with pytest.raises(ConnectionError) as err:
+def test_500_is_transient_fail_fast():
+    # ENG-673: a request-time 5xx is transient (retryable), but SDK-retried
+    # already → fail fast with the honest typed message, no session backoff.
+    exc = _sdk_error(500, json_body={})
+    with pytest.raises(TransientProviderError) as err:
         _raise_for_status_error(exc, "sonnet")
-    assert "Server returned 500" in str(err.value)
+    assert err.value.session_backoff is False
+    assert "returned 500" in str(err.value)
diff --git a/tests/test_transient_retry.py b/tests/test_transient_retry.py
new file mode 100644
index 00000000..707b3e10
--- /dev/null
+++ b/tests/test_transient_retry.py
@@ -0,0 +1,456 @@
+"""ENG-673 — transient mid-stream provider errors: classification + backoff.
+
+Covers the anton-side of the fix without a live provider:
+  * `classify_transient` (Arm A) — the shared body/status classifier.
+  * both provider mappers (`anthropic`/`openai` `_raise_for_status_error`) — the
+    right typed exception for each failure, incl. the mid-stream HTTP-200 case.
+  * the session backoff helpers — cadence, `retry_after`, and cancel-awareness.
+
+The real-SDK wire path (a genuine SSE `error` inside a 200 is parsed and
+classified on BOTH providers) is exercised by the mock-provider harness in
+`test_transient_retry_e2e.py`, which drives the real anthropic/openai SDKs
+against an `httpx.MockTransport`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import types
+
+import pytest
+
+from anton.core.llm.provider import (
+    ModelUnavailableError,
+    ProviderOverloadedError,
+    TokenLimitExceeded,
+    TransientProviderError,
+    classify_transient,
+)
+
+
+class _FakeStatusError(Exception):
+    """Minimal stand-in for anthropic/openai APIStatusError — the mappers only
+    read `.status_code` and `.body`, and `raise X from exc` needs a real exc."""
+
+    def __init__(self, status_code, body):
+        super().__init__(f"HTTP {status_code}")
+        self.status_code = status_code
+        self.body = body
+
+
+# --------------------------------------------------------------------------- #
+# classify_transient (Arm A)
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize(
+    "status,body",
+    [
+        (200, {"type": "error", "error": {"type": "overloaded_error"}}),  # mid-stream
+        (200, {"error": {"code": "api_error"}}),
+        (503, {}),
+        (500, {}),
+        (429, {}),                       # plain rate-limit (no quota detail)
+    ],
+)
+def test_classify_transient_retryable(status, body):
+    result = classify_transient(status, body, provider="Anthropic")
+    assert isinstance(result, TransientProviderError)
+    assert result.provider == "Anthropic"
+
+
+def test_session_backoff_flag_splits_midstream_from_requesttime():
+    # Mid-stream (overload smuggled into a 200) had NO prior retry → session
+    # backs off. Request-time errors (real 5xx/429/529) were SDK-retried already
+    # → fail fast, no extra session budget.
+    assert classify_transient(
+        200, {"error": {"type": "overloaded_error"}}, provider="X"
+    ).session_backoff is True
+    assert classify_transient(503, {}, provider="X").session_backoff is False
+    assert classify_transient(429, {}, provider="X").session_backoff is False
+    assert classify_transient(
+        529, {"error": {"type": "overloaded_error"}}, provider="X"
+    ).session_backoff is False
+
+
+@pytest.mark.parametrize(
+    "status,body",
+    [
+        (200, {}),                                   # clean stream, no error
+        (401, {}),                                   # auth
+        (403, {"error": {"code": "model_disabled"}}),      # model gate
+        (403, {"error": {"code": "model_access_denied"}}),
+        (429, {"detail": "out of tokens"}),          # quota → TokenLimitExceeded upstream
+        (400, {"error": {"type": "invalid_request_error"}}),
+    ],
+)
+def test_classify_transient_not_retryable(status, body):
+    assert classify_transient(status, body, provider="X") is None
+
+
+# --------------------------------------------------------------------------- #
+# provider mappers — the same input must map identically on both providers
+# --------------------------------------------------------------------------- #
+
+def _anthropic_map(status, body):
+    from anton.core.llm.anthropic import _raise_for_status_error
+    _raise_for_status_error(_FakeStatusError(status, body))
+
+
+def _openai_map(status, body):
+    from anton.core.llm.openai import _raise_for_status_error
+    _raise_for_status_error(_FakeStatusError(status, body), "latest:sonnet")
+
+
+@pytest.mark.parametrize("mapper", [_anthropic_map, _openai_map])
+def test_mapper_midstream_200_is_transient_not_confusing_200(mapper):
+    """The core ENG-673 fix: a mid-stream overload arriving inside an HTTP-200
+    stream must become TransientProviderError, never 'Server returned 200'."""
+    with pytest.raises(TransientProviderError) as ei:
+        mapper(200, {"type": "error", "error": {"type": "overloaded_error"}})
+    assert "200" not in str(ei.value)          # no misleading status echo
+    assert "overloaded" in str(ei.value).lower()
+
+
+@pytest.mark.parametrize("mapper", [_anthropic_map, _openai_map])
+def test_mapper_5xx_is_transient(mapper):
+    with pytest.raises(TransientProviderError):
+        mapper(503, {})
+
+
+@pytest.mark.parametrize("mapper", [_anthropic_map, _openai_map])
+def test_mapper_quota_429_is_token_limit_not_transient(mapper):
+    with pytest.raises(TokenLimitExceeded):
+        mapper(429, {"detail": "You have run out of tokens."})
+
+
+@pytest.mark.parametrize("mapper", [_anthropic_map, _openai_map])
+def test_mapper_401_stays_connectionerror_fail_fast(mapper):
+    # 401 must NOT be transient — retrying resends the same bad key forever.
+    with pytest.raises(ConnectionError) as ei:
+        mapper(401, {})
+    assert not isinstance(ei.value, TransientProviderError)
+
+
+def test_openai_mapper_model_gate_still_model_unavailable():
+    # ENG-598 behavior must be preserved: structured 403 → ModelUnavailableError.
+    with pytest.raises(ModelUnavailableError):
+        _openai_map(403, {"error": {"code": "model_access_denied"}})
+
+
+# --------------------------------------------------------------------------- #
+# session backoff helpers
+# --------------------------------------------------------------------------- #
+
+def _delay(attempt, retry_after=None):
+    from anton.core.session import ChatSession
+    return ChatSession._transient_backoff_delay(attempt, retry_after)
+
+
+def test_backoff_cadence_grows_and_jitters():
+    # Monotone-ish base cadence ~2 → ~10 → ~18, each within its ±20% jitter band.
+    assert 1.6 <= _delay(0) <= 2.4
+    assert 8.0 <= _delay(1) <= 12.0
+    assert 14.4 <= _delay(2) <= 21.6
+    # Beyond the table, clamps to the last step (still jittered).
+    assert 14.4 <= _delay(9) <= 21.6
+
+
+def test_backoff_honors_retry_after():
+    assert _delay(0, retry_after=5) == 5.0
+    assert _delay(0, retry_after=999) == 30.0   # capped at the budget
+
+
+async def test_backoff_sleep_returns_false_on_full_delay():
+    from anton.core.session import ChatSession
+    ns = types.SimpleNamespace(_cancel_event=asyncio.Event())
+    assert await ChatSession._backoff_sleep(ns, 0.01) is False
+
+
+async def test_backoff_sleep_wakes_on_cancel():
+    from anton.core.session import ChatSession
+    ev = asyncio.Event()
+    ns = types.SimpleNamespace(_cancel_event=ev)
+    ev.set()  # already cancelled → must return immediately, not wait out the delay
+    assert await asyncio.wait_for(ChatSession._backoff_sleep(ns, 30.0), timeout=1.0) is True
+
+
+def test_provider_overloaded_error_carries_model_and_provider():
+    exc = ProviderOverloadedError("boom", provider="Anthropic", model="latest:sonnet")
+    assert exc.code == "provider_overloaded"
+    assert exc.provider == "Anthropic"
+    assert exc.model == "latest:sonnet"
+    assert isinstance(exc, ConnectionError)  # legacy call sites still catch it
+
+
+# --------------------------------------------------------------------------- #
+# session turn loop — recovery, budget exhaustion, no-replay (idempotency)
+# --------------------------------------------------------------------------- #
+
+from unittest.mock import AsyncMock, MagicMock, patch  # noqa: E402
+
+import httpx  # noqa: E402
+import openai  # noqa: E402
+
+from anton.chat import ChatSession  # noqa: E402
+from anton.core.llm.openai import OpenAIProvider  # noqa: E402
+from anton.core.llm.provider import StreamComplete, StreamTextDelta  # noqa: E402
+from anton.core.session import ChatSessionConfig  # noqa: E402
+from tests.conftest import make_mock_llm  # noqa: E402
+
+
+# --------------------------------------------------------------------------- #
+# provider-level truncation — #1 fix regression guard
+# --------------------------------------------------------------------------- #
+
+def _chunk(content=None, finish_reason=None):
+    delta = MagicMock()
+    delta.content = content
+    delta.tool_calls = None
+    choice = MagicMock()
+    choice.delta = delta
+    choice.finish_reason = finish_reason
+    ch = MagicMock()
+    ch.choices = [choice]
+    ch.usage = None
+    return ch
+
+
+async def _run_openai_stream(chunks):
+    async def _aiter():
+        for c in chunks:
+            yield c
+    with patch("anton.core.llm.openai.openai") as mock_openai:
+        client = AsyncMock()
+        mock_openai.AsyncOpenAI.return_value = client
+        client.chat.completions.create = AsyncMock(return_value=_aiter())
+        prov = OpenAIProvider(api_key="k")
+        return [
+            ev async for ev in prov.stream(
+                model="latest:sonnet", system="s",
+                messages=[{"role": "user", "content": "hi"}],
+            )
+        ]
+
+
+async def test_stream_content_without_finish_reason_passes_through():
+    # #1 regression: a COMPLETE answer with no finish_reason (common on
+    # OpenAI-compatible endpoints) must complete, NOT be discarded as truncated.
+    events = await _run_openai_stream([_chunk(content="Hello "), _chunk(content="world")])
+    completes = [e for e in events if isinstance(e, StreamComplete)]
+    assert len(completes) == 1
+    assert completes[0].response.content == "Hello world"
+
+
+async def test_stream_empty_without_finish_reason_is_truncated():
+    # Only the truly-empty no-terminal-marker stream is a genuine truncation.
+    with pytest.raises(TransientProviderError) as ei:
+        await _run_openai_stream([])
+    assert ei.value.code == "truncated_stream"
+    # Deliberate carve-out (ENG-673): an empty-from-start 200 is a broken-endpoint
+    # signal, not a mid-incident blip — it fails fast rather than looping the
+    # backoff budget. Genuine mid-incident silence arrives as a connection drop /
+    # read timeout / SSE error, which DO back off (tested above/below).
+    assert ei.value.session_backoff is False
+
+
+# --------------------------------------------------------------------------- #
+# mid-stream vs request-time boundary — the ENG-673 session_backoff flag
+# (Sam's review): a failure AFTER the 200 was never SDK-retried → session backs
+# off; a failure DURING establishment was already SDK-retried → fail fast.
+# Drive a REAL OpenAIProvider whose client we replace, so the genuine openai.*
+# exception classes match the provider's except clauses (no module patching).
+# --------------------------------------------------------------------------- #
+
+def _req() -> httpx.Request:
+    return httpx.Request("POST", "http://mock/v1/chat/completions")
+
+
+async def _drain_openai_with_create(create_mock) -> TransientProviderError:
+    prov = OpenAIProvider(api_key="k")
+    prov._client = AsyncMock()
+    prov._client.chat.completions.create = create_mock
+    with pytest.raises(TransientProviderError) as ei:
+        _ = [
+            ev async for ev in prov.stream(
+                model="latest:sonnet", system="s",
+                messages=[{"role": "user", "content": "hi"}],
+            )
+        ]
+    return ei.value
+
+
+async def test_stream_connection_drop_during_establishment_is_fail_fast():
+    # create() itself raises → the SDK already retried at the transport layer.
+    exc = await _drain_openai_with_create(
+        AsyncMock(side_effect=openai.APIConnectionError(request=_req()))
+    )
+    assert exc.code == "connection_error"
+    assert exc.session_backoff is False
+
+
+async def test_stream_connection_drop_midstream_backs_off():
+    # A 200 was established (first chunk arrived) then the connection dropped —
+    # the SDK never retried this, so the session must.
+    async def _aiter():
+        yield _chunk(content="partial")
+        raise openai.APIConnectionError(request=_req())
+
+    exc = await _drain_openai_with_create(AsyncMock(return_value=_aiter()))
+    assert exc.code == "connection_error"
+    assert exc.session_backoff is True
+
+
+async def test_stream_midstream_bare_apierror_is_classified_and_backs_off():
+    # The OpenAI-shaped gap: a mid-stream SSE `error` surfaces as a bare
+    # openai.APIError (no status_code, body type at top level), which is NOT an
+    # APIStatusError. It must still be caught, classified from the body, and
+    # backed off — otherwise it escapes as an opaque generic error (ENG-673).
+    async def _aiter():
+        yield _chunk(content="Hel")
+        raise openai.APIError(
+            "overloaded", request=_req(),
+            body={"type": "server_error", "message": "overloaded"},
+        )
+
+    exc = await _drain_openai_with_create(AsyncMock(return_value=_aiter()))
+    assert exc.session_backoff is True
+    assert exc.code in ("server_error", "stream_error")
+
+
+def _session() -> ChatSession:
+    s = ChatSession(ChatSessionConfig(llm_client=make_mock_llm()))
+    s._llm.planning_model = "latest:sonnet"
+    return s
+
+
+def _stream_that_fails_then_succeeds(fail_n: int, calls: dict):
+    """Async-generator factory: raise a transient error `fail_n` times, then
+    yield a successful text delta."""
+    async def _gen(user_msg):
+        calls["n"] += 1
+        if calls["n"] <= fail_n:
+            raise TransientProviderError(
+                "Anthropic is momentarily overloaded.",
+                provider="Anthropic", code="overloaded_error",
+            )
+        yield StreamTextDelta(text="recovered-and-done")
+    return _gen
+
+
+async def test_turn_recovers_after_transient_retries():
+    s = _session()
+    calls = {"n": 0}
+    s._stream_and_handle_tools = _stream_that_fails_then_succeeds(2, calls)
+    s._backoff_sleep = AsyncMock(return_value=False)  # don't really sleep
+
+    events = [e async for e in s.turn_stream("build me a dashboard")]
+
+    text = "".join(e.text for e in events if isinstance(e, StreamTextDelta))
+    assert "recovered-and-done" in text          # turn completed
+    assert calls["n"] == 3                        # 2 failures + 1 success
+    assert s._backoff_sleep.await_count == 2      # backed off before each retry
+
+
+async def test_turn_transient_retry_does_not_inject_recovery_note():
+    """Idempotency/no-replay: a transient blip must NOT inject a 'you errored,
+    change approach' SYSTEM note (which would alter behavior / prompt a replay);
+    it simply retries the same step from unchanged history."""
+    s = _session()
+    calls = {"n": 0}
+    s._stream_and_handle_tools = _stream_that_fails_then_succeeds(2, calls)
+    s._backoff_sleep = AsyncMock(return_value=False)
+
+    _ = [e async for e in s.turn_stream("do it")]
+
+    joined = json.dumps(s._history)
+    assert "An error interrupted execution" not in joined
+    assert "transient provider error" not in joined  # seal reason not injected either
+
+
+async def test_turn_exhausts_budget_to_provider_overloaded():
+    s = _session()
+    s._transient_budget_s = 0.05   # exhaust almost immediately
+    calls = {"n": 0}
+
+    async def _always_fail(user_msg):
+        calls["n"] += 1
+        raise TransientProviderError(
+            "Anthropic is momentarily overloaded.",
+            provider="Anthropic", code="overloaded_error",
+        )
+        yield  # pragma: no cover  (makes this an async generator)
+
+    s._stream_and_handle_tools = _always_fail
+
+    with pytest.raises(ProviderOverloadedError) as ei:
+        _ = [e async for e in s.turn_stream("do it")]
+
+    assert ei.value.code == "provider_overloaded"
+    assert ei.value.provider == "Anthropic"
+    assert ei.value.model == "latest:sonnet"
+
+
+async def test_provider_overloaded_names_the_failing_model_not_planning():
+    # ENG-673 #4: the card must name the model that actually failed (which may be
+    # the coding model), not always the session's planning model.
+    s = _session()  # planning_model = latest:sonnet
+    s._transient_budget_s = 0.05
+
+    async def _always_fail(user_msg):
+        raise TransientProviderError(
+            "overloaded", provider="Anthropic", code="overloaded_error", model="latest:haiku",
+        )
+        yield  # pragma: no cover
+
+    s._stream_and_handle_tools = _always_fail
+    with pytest.raises(ProviderOverloadedError) as ei:
+        _ = [e async for e in s.turn_stream("do it")]
+    assert ei.value.model == "latest:haiku"   # the failing model, not planning
+
+
+async def test_request_time_transient_does_not_tell_model_to_adjust_approach():
+    # ENG-673 #6: a request-time provider blip (session_backoff=False) recovers
+    # via the count-based path, but must NOT inject "adjust your approach" — that
+    # misattributes a service hiccup to the model.
+    s = _session()
+    calls = {"n": 0}
+
+    async def _gen(user_msg):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise TransientProviderError(
+                "Server returned 500.", provider="X", code="http_500", session_backoff=False,
+            )
+        yield StreamTextDelta(text="ok done")
+
+    s._stream_and_handle_tools = _gen
+    events = [e async for e in s.turn_stream("do it")]
+
+    assert "ok done" in "".join(e.text for e in events if isinstance(e, StreamTextDelta))
+    history = json.dumps(s._history).lower()
+    assert "transient service issue" in history
+    assert "adjust your approach" not in history
+
+
+def test_classify_transient_propagates_model():
+    err = classify_transient(200, {"error": {"type": "overloaded_error"}}, provider="X", model="latest:opus")
+    assert err.model == "latest:opus"
+
+
+async def test_turn_transient_backoff_cancels_on_stop():
+    """User-stop during backoff aborts immediately rather than waiting out the
+    incident — and stops CLEANLY (like a normal stop), not with a provider-error
+    card surfaced to the user."""
+    s = _session()
+    calls = {"n": 0}
+    s._stream_and_handle_tools = _stream_that_fails_then_succeeds(5, calls)
+    s._backoff_sleep = AsyncMock(return_value=True)  # cancelled during backoff
+
+    events = [e async for e in s.turn_stream("do it")]  # no exception raised
+
+    assert calls["n"] == 1                    # failed once, then cancelled — no further retries
+    assert s._backoff_sleep.await_count == 1
+    # Clean cancel: no transient-error prose leaks into the transcript.
+    text = "".join(e.text for e in events if isinstance(e, StreamTextDelta))
+    assert "overloaded" not in text.lower()
diff --git a/tests/test_transient_retry_e2e.py b/tests/test_transient_retry_e2e.py
new file mode 100644
index 00000000..93e61794
--- /dev/null
+++ b/tests/test_transient_retry_e2e.py
@@ -0,0 +1,189 @@
+"""ENG-673 e2e — deterministic mock-provider harness.
+
+Drives the **real** anthropic / openai SDK stream parsers against an
+``httpx.MockTransport`` so we exercise the genuine wire path, not a hand-built
+exception. Proves the core fix on BOTH providers: a provider failure arriving
+*mid-stream inside an HTTP-200 stream* is classified as a retryable
+``TransientProviderError`` (``session_backoff=True``), never the misleading
+"Server returned 200".
+
+Complements ``test_transient_retry.py`` (unit-level classifier + session
+backoff/budget). The turn-level cadence/budget/idempotency behavior lives there
+against a faked stream; here we prove the classification the real SDK produces
+is the input those session tests assume.
+
+No network, no sleeping, no waiting for a real incident — the transport returns
+canned SSE bytes.
+"""
+
+from __future__ import annotations
+
+import anthropic
+import httpx
+import openai
+import pytest
+
+from anton.core.llm.anthropic import AnthropicProvider
+from anton.core.llm.openai import OpenAIProvider
+from anton.core.llm.provider import (
+    StreamComplete,
+    StreamTextDelta,
+    TransientProviderError,
+)
+
+
+# --------------------------------------------------------------------------- #
+# wire payloads
+# --------------------------------------------------------------------------- #
+
+def _sse(*lines: str) -> bytes:
+    return ("".join(lines)).encode()
+
+
+# Anthropic Messages API: a 200 stream that emits message_start then an SSE
+# `error` event carrying overloaded_error — the exact BUG-CM-001 shape.
+_ANTH_MIDSTREAM_OVERLOAD = _sse(
+    'event: message_start\n',
+    'data: {"type":"message_start","message":{"id":"msg_1","type":"message",'
+    '"role":"assistant","model":"claude","content":[],"stop_reason":null,'
+    '"stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":0}}}\n\n',
+    'event: error\n',
+    'data: {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}\n\n',
+)
+
+# Anthropic: a clean, complete stream (sanity — the harness itself is honest).
+_ANTH_GOOD = _sse(
+    'event: message_start\n',
+    'data: {"type":"message_start","message":{"id":"msg_2","type":"message",'
+    '"role":"assistant","model":"claude","content":[],"stop_reason":null,'
+    '"stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":0}}}\n\n',
+    'event: content_block_start\n',
+    'data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}\n\n',
+    'event: content_block_delta\n',
+    'data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello world"}}\n\n',
+    'event: content_block_stop\n',
+    'data: {"type":"content_block_stop","index":0}\n\n',
+    'event: message_delta\n',
+    'data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},'
+    '"usage":{"output_tokens":3}}\n\n',
+    'event: message_stop\n',
+    'data: {"type":"message_stop"}\n\n',
+)
+
+# OpenAI chat.completions: a 200 stream that emits one good chunk then an SSE
+# `error` — the SDK surfaces this as a BARE openai.APIError (status_code=None).
+_OAI_MIDSTREAM_ERROR = _sse(
+    'data: {"id":"1","object":"chat.completion.chunk","choices":'
+    '[{"index":0,"delta":{"content":"Hel"},"finish_reason":null}]}\n\n',
+    'data: {"error":{"message":"The server is overloaded","type":"server_error","code":null}}\n\n',
+)
+
+
+# --------------------------------------------------------------------------- #
+# provider factories wired to a MockTransport
+# --------------------------------------------------------------------------- #
+
+def _anthropic_provider(handler) -> AnthropicProvider:
+    prov = AnthropicProvider(api_key="test")
+    prov._client = anthropic.AsyncAnthropic(
+        api_key="test",
+        http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+    )
+    return prov
+
+
+def _openai_provider(handler) -> OpenAIProvider:
+    # Default flavor is openai-compatible-generic → the chat.completions path
+    # (the MindsHub-passthrough dialect), which is what MindsHub routing uses.
+    prov = OpenAIProvider(api_key="test", base_url="http://mock/v1")
+    prov._client = openai.AsyncOpenAI(
+        api_key="test", base_url="http://mock/v1",
+        http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+    )
+    return prov
+
+
+def _static(body: bytes):
+    def handler(_req):
+        return httpx.Response(
+            200, headers={"content-type": "text/event-stream"}, content=body
+        )
+    return handler
+
+
+async def _drain(prov):
+    return [
+        ev
+        async for ev in prov.stream(
+            model="latest:sonnet", system="s",
+            messages=[{"role": "user", "content": "hi"}],
+        )
+    ]
+
+
+# --------------------------------------------------------------------------- #
+# Anthropic
+# --------------------------------------------------------------------------- #
+
+async def test_e2e_anthropic_midstream_overload_is_transient_not_confusing_200():
+    prov = _anthropic_provider(_static(_ANTH_MIDSTREAM_OVERLOAD))
+    with pytest.raises(TransientProviderError) as ei:
+        await _drain(prov)
+    exc = ei.value
+    assert exc.code == "overloaded_error"
+    # The whole point of ENG-673: the 200 must NOT leak into the message, and
+    # the session must be allowed to back off (mid-stream had no SDK retry).
+    assert "200" not in str(exc)
+    assert exc.session_backoff is True
+
+
+async def test_e2e_anthropic_clean_stream_completes():
+    prov = _anthropic_provider(_static(_ANTH_GOOD))
+    events = await _drain(prov)
+    text = "".join(e.text for e in events if isinstance(e, StreamTextDelta))
+    completes = [e for e in events if isinstance(e, StreamComplete)]
+    assert text == "Hello world"
+    assert len(completes) == 1
+    assert completes[0].response.stop_reason == "end_turn"
+
+
+async def test_e2e_anthropic_recovers_after_n_failures():
+    """Attempt log verifies the fail-N-then-succeed shape at the SDK layer:
+    the same request resent after transient failures eventually completes."""
+    state = {"n": 0}
+
+    def handler(_req):
+        state["n"] += 1
+        body = _ANTH_MIDSTREAM_OVERLOAD if state["n"] <= 2 else _ANTH_GOOD
+        return httpx.Response(
+            200, headers={"content-type": "text/event-stream"}, content=body
+        )
+
+    prov = _anthropic_provider(handler)
+    # First two calls fail transiently...
+    for _ in range(2):
+        with pytest.raises(TransientProviderError):
+            await _drain(prov)
+    # ...the third (identical) request succeeds — exactly what the session's
+    # backoff loop replays.
+    events = await _drain(prov)
+    assert "".join(e.text for e in events if isinstance(e, StreamTextDelta)) == "Hello world"
+    assert state["n"] == 3
+
+
+# --------------------------------------------------------------------------- #
+# OpenAI / MindsHub (chat.completions dialect)
+# --------------------------------------------------------------------------- #
+
+async def test_e2e_openai_midstream_error_is_transient():
+    """The OpenAI-shaped gap: a mid-stream SSE error is a bare openai.APIError
+    (no status_code), which must still classify as transient + backoff-able —
+    'the fix is not tested if only Anthropic is mocked' (Sam's review)."""
+    prov = _openai_provider(_static(_OAI_MIDSTREAM_ERROR))
+    with pytest.raises(TransientProviderError) as ei:
+        await _drain(prov)
+    exc = ei.value
+    assert "200" not in str(exc)
+    assert exc.session_backoff is True
+    # server_error is in the transient set → classified by type, not a fallback.
+    assert exc.code in ("server_error", "stream_error")

From 83da2f8ac762d2ee2e4c1ed885c39272308edecc Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 22 Jul 2026 11:42:36 +0300
Subject: [PATCH 19/33] public-data-sources skill

---
 anton/core/llm/prompts.py                     | 49 +++----------------
 .../public-data-sources/SKILL.md              | 40 +++++++++++++++
 tests/test_builtin_skills.py                  | 33 ++++++++++++-
 3 files changed, 79 insertions(+), 43 deletions(-)
 create mode 100644 anton/core/memory/builtin_skills/public-data-sources/SKILL.md

diff --git a/anton/core/llm/prompts.py b/anton/core/llm/prompts.py
index 2b924cb6..5761518a 100644
--- a/anton/core/llm/prompts.py
+++ b/anton/core/llm/prompts.py
@@ -52,48 +52,13 @@
 - If the first source doesn't work, try alternatives. Don't give up after one \
 attempt — try 2-3 different approaches before telling the user it's unavailable.
 
-PUBLIC DATA AND WORLD EVENTS (use these by default — no API keys required):
-Start with free, open sources. Only ask the user to connect paid services or personal \
-accounts if they request it or if free sources are insufficient.
-
-News & current events (via RSS — use feedparser):
-- Google News RSS: `https://news.google.com/rss/search?q={{query}}&hl={{lang}}&gl={{country}}` \
-— any topic, any country. Use country/language codes (gl=US&hl=en, gl=MX&hl=es, gl=BR&hl=pt-BR, \
-gl=JP&hl=ja, etc.). This is your primary news source.
-- Reuters: `https://www.rss.reuters.com/news/` (world, business, tech sections)
-- AP News: `https://rsshub.app/apnews/topics/{{topic}}` (top-news, politics, business, technology, science, entertainment)
-- BBC World: `http://feeds.bbci.co.uk/news/rss.xml` (also /world, /business, /technology)
-- NPR: `https://feeds.npr.org/1001/rss.xml` (news), `1006/rss.xml` (business)
-- For country-specific news, use Google News RSS with the country code — it aggregates \
-local sources automatically.
-- Parse feeds with `feedparser`: title, link, published date, summary. \
-Store as a list of dicts for dashboard integration.
-
-Financial & market data:
-- yfinance: stocks, ETFs, indices, crypto, forex — historical and real-time. \
-Use tickers like ^GSPC (S&P 500), ^DJI (Dow), ^IXIC (Nasdaq), BTC-USD, etc.
-- FRED (Federal Reserve): `https://fred.stlouisfed.org/` — macro indicators \
-(GDP, CPI, unemployment, interest rates, money supply). Use fredapi package \
-with free API key, or fetch CSV directly: \
-`https://fred.stlouisfed.org/graph/fredgraph.csv?id={{series_id}}` (no key needed for CSV).
-- CoinGecko: `https://api.coingecko.com/api/v3/` — crypto prices, market cap, \
-volume, trending coins. Free, no key.
-
-Economic & global data:
-- World Bank: `https://api.worldbank.org/v2/country/{{code}}/indicator/{{indicator}}?format=json` \
-— GDP, population, poverty, education, health by country. Free, no key.
-- OECD: `https://sdmx.oecd.org/public/rest/data/` — economic indicators for OECD countries.
-- Open Exchange Rates: `https://open.er-api.com/v6/latest/{{base}}` — free forex rates.
-
-Social & sentiment:
-- Reddit JSON: `https://www.reddit.com/r/{{subreddit}}/.json` — add .json to any \
-Reddit URL for structured data. Good for sentiment on specific topics.
-- HackerNews: `https://hacker-news.firebaseio.com/v0/` — tech news, top/new/best stories.
-
-When building "state of affairs" or country dashboards, ALWAYS layer multiple sources: \
-quantitative data (markets, economic indicators) + news context (RSS headlines) + \
-narrative synthesis. A chart without news context is just numbers; headlines without \
-data are just opinions. Combine them.
+PUBLIC DATA AND WORLD EVENTS:
+Prefer free, open sources by default (Google News RSS, yfinance, FRED, CoinGecko, \
+World Bank, Reddit JSON, HackerNews) — only ask the user to connect paid services or \
+personal accounts if they request it or if free sources are insufficient. A curated \
+catalog of ready-to-use endpoints and URL patterns is available: call \
+`recall_skill("public-data-sources")` BEFORE fetching public news, market, or \
+world data.
 
 PROACTIVE FOLLOW-UP SUGGESTIONS:
 After completing analysis on public datasets, think about whether the user's own data \
diff --git a/anton/core/memory/builtin_skills/public-data-sources/SKILL.md b/anton/core/memory/builtin_skills/public-data-sources/SKILL.md
new file mode 100644
index 00000000..2c165184
--- /dev/null
+++ b/anton/core/memory/builtin_skills/public-data-sources/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: public-data-sources
+description: 'Recall BEFORE fetching public news, market, economic, or world data
+  from the scratchpad. Catalog of free, open, no-API-key data endpoints and URL
+  patterns — news RSS (Google News, Reuters, AP, BBC, NPR), financial/market
+  (yfinance, FRED, CoinGecko), economic/global (World Bank, OECD, exchange rates),
+  and social/sentiment (Reddit, HackerNews) — plus how to layer them for "state of
+  affairs" and country dashboards. When in doubt about where to get free live data,
+  recall it.'
+metadata:
+  display_name: Public data & world-event sources
+  provenance: builtin
+---
+PUBLIC DATA AND WORLD EVENTS (use these by default — no API keys required):
+Start with free, open sources. Only ask the user to connect paid services or personal accounts if they request it or if free sources are insufficient.
+
+News & current events (via RSS — use feedparser):
+- Google News RSS: `https://news.google.com/rss/search?q={query}&hl={lang}&gl={country}` — any topic, any country. Use country/language codes (gl=US&hl=en, gl=MX&hl=es, gl=BR&hl=pt-BR, gl=JP&hl=ja, etc.). This is your primary news source.
+- Reuters: `https://www.rss.reuters.com/news/` (world, business, tech sections)
+- AP News: `https://rsshub.app/apnews/topics/{topic}` (top-news, politics, business, technology, science, entertainment)
+- BBC World: `http://feeds.bbci.co.uk/news/rss.xml` (also /world, /business, /technology)
+- NPR: `https://feeds.npr.org/1001/rss.xml` (news), `1006/rss.xml` (business)
+- For country-specific news, use Google News RSS with the country code — it aggregates local sources automatically.
+- Parse feeds with `feedparser`: title, link, published date, summary. Store as a list of dicts for dashboard integration.
+
+Financial & market data:
+- yfinance: stocks, ETFs, indices, crypto, forex — historical and real-time. Use tickers like ^GSPC (S&P 500), ^DJI (Dow), ^IXIC (Nasdaq), BTC-USD, etc.
+- FRED (Federal Reserve): `https://fred.stlouisfed.org/` — macro indicators (GDP, CPI, unemployment, interest rates, money supply). Use fredapi package with free API key, or fetch CSV directly: `https://fred.stlouisfed.org/graph/fredgraph.csv?id={series_id}` (no key needed for CSV).
+- CoinGecko: `https://api.coingecko.com/api/v3/` — crypto prices, market cap, volume, trending coins. Free, no key.
+
+Economic & global data:
+- World Bank: `https://api.worldbank.org/v2/country/{code}/indicator/{indicator}?format=json` — GDP, population, poverty, education, health by country. Free, no key.
+- OECD: `https://sdmx.oecd.org/public/rest/data/` — economic indicators for OECD countries.
+- Open Exchange Rates: `https://open.er-api.com/v6/latest/{base}` — free forex rates.
+
+Social & sentiment:
+- Reddit JSON: `https://www.reddit.com/r/{subreddit}/.json` — add .json to any Reddit URL for structured data. Good for sentiment on specific topics.
+- HackerNews: `https://hacker-news.firebaseio.com/v0/` — tech news, top/new/best stories.
+
+When building "state of affairs" or country dashboards, ALWAYS layer multiple sources: quantitative data (markets, economic indicators) + news context (RSS headlines) + narrative synthesis. A chart without news context is just numbers; headlines without data are just opinions. Combine them.
diff --git a/tests/test_builtin_skills.py b/tests/test_builtin_skills.py
index cd84f9f8..d7250a07 100644
--- a/tests/test_builtin_skills.py
+++ b/tests/test_builtin_skills.py
@@ -10,7 +10,7 @@
 REAL_BUILTIN_ROOT = (
     Path(skills_mod.__file__).parent / "builtin_skills"
 )
-SHIPPED_LABELS = {"build-fullstack-backend", "build-html-dashboard"}
+SHIPPED_LABELS = {"build-fullstack-backend", "build-html-dashboard", "public-data-sources"}
 
 
 @pytest.fixture()
@@ -38,6 +38,14 @@ def test_load_returns_full_body(self, store):
         assert dashboard.provenance == "builtin"
         assert len(dashboard.declarative_md) > 5_000
 
+        data_sources = store.load("public-data-sources")
+        assert data_sources is not None
+        assert data_sources.provenance == "builtin"
+        # spot-check endpoints + single-brace URL params (SKILL.md bodies are
+        # not str.format()'d, unlike the CHAT_SYSTEM_PROMPT they moved out of)
+        assert "feedparser" in data_sources.declarative_md
+        assert "api.worldbank.org/v2/country/{code}/indicator/{indicator}" in data_sources.declarative_md
+
     def test_descriptions_fit_prompt_budget(self, store):
         for summary in store.list_summaries():
             assert len(summary["description"]) <= 1024
@@ -98,12 +106,14 @@ def _referenced_labels(self, *texts: str) -> set[str]:
     def test_prompt_hints_reference_shipped_skills(self, store):
         from anton.core.llm.prompts import (
             BACKEND_GENERATION_PROMPT,
+            CHAT_SYSTEM_PROMPT,
             VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT,
             VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT,
         )
 
         referenced = self._referenced_labels(
             BACKEND_GENERATION_PROMPT,
+            CHAT_SYSTEM_PROMPT,
             VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT,
             VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT,
         )
@@ -122,6 +132,27 @@ def test_tool_descriptions_reference_shipped_skills(self, store):
             assert store.load(label) is not None, f"hinted skill missing: {label}"
 
 
+class TestDataCatalogMovedToSkill:
+    """The public-data endpoint catalog must live in the recalled skill only,
+    not inline in the always-on CHAT_SYSTEM_PROMPT (that duplication is the
+    token cost this move removes)."""
+
+    CATALOG_MARKERS = ("api.worldbank.org", "hacker-news.firebaseio.com", "feedparser")
+
+    def test_catalog_not_inline_in_base_prompt(self):
+        from anton.core.llm.prompts import CHAT_SYSTEM_PROMPT
+
+        for marker in self.CATALOG_MARKERS:
+            assert marker not in CHAT_SYSTEM_PROMPT, f"catalog leaked into base prompt: {marker}"
+        assert 'recall_skill("public-data-sources")' in CHAT_SYSTEM_PROMPT
+
+    def test_catalog_lives_in_skill(self, store):
+        skill = store.load("public-data-sources")
+        assert skill is not None and skill.provenance == "builtin"
+        for marker in self.CATALOG_MARKERS:
+            assert marker in skill.declarative_md, f"catalog marker missing from skill: {marker}"
+
+
 class TestBrokenShadowFallback:
     def test_unreadable_user_dir_falls_back_to_builtin(self, store):
         bad = store.root / "build-fullstack-backend"

From 58c75c90e30189e264145e52d4fae34b55c0d6a9 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 22 Jul 2026 13:33:54 +0300
Subject: [PATCH 20/33] use router model for summarization

---
 anton/config/settings.py | 15 ++++++-
 anton/core/llm/client.py | 53 +++++++++++++++++++++++
 anton/core/session.py    |  2 +-
 tests/test_client.py     | 91 ++++++++++++++++++++++++++++++++++++++++
 tests/test_settings.py   | 15 +++++++
 5 files changed, 174 insertions(+), 2 deletions(-)

diff --git a/anton/config/settings.py b/anton/config/settings.py
index 31d72ee2..bf5f337c 100644
--- a/anton/config/settings.py
+++ b/anton/config/settings.py
@@ -36,7 +36,9 @@ class AntonSettings(CoreSettings):
     coding_provider: str = "anthropic"
     coding_model: str = "claude-haiku-4-5-20251001"
 
-    @field_validator("planning_provider", "coding_provider", mode="before")
+    @field_validator(
+        "planning_provider", "coding_provider", "router_provider", mode="before"
+    )
     @classmethod
     def _map_minds_cloud_to_openai_compatible(cls, v: object) -> object:
         """MindsHub is an OpenAI-compatible endpoint, so the CLI serves it via
@@ -48,6 +50,11 @@ def _map_minds_cloud_to_openai_compatible(cls, v: object) -> object:
         Normalise it here so both names resolve to the same working provider
         (ENG-655). Tolerant of case, surrounding whitespace, and the underscore
         spelling.
+
+        Covers ``router_provider`` too: ``LLMClient.from_settings`` validates the
+        router role identically, so without this a shared ``minds-cloud`` config
+        would re-crash with ``Unknown router provider: minds-cloud``. Keep every
+        provider field in this decorator's list.
         """
         if isinstance(v, str) and v.strip().lower().replace("_", "-") == "minds-cloud":
             return "openai-compatible"
@@ -66,6 +73,12 @@ def _map_minds_cloud_to_openai_compatible(cls, v: object) -> object:
     planning_reasoning_effort: str | None = None
     coding_reasoning_effort: str | None = None
 
+    # Router role (ENG-648) — the cheap model that runs history summarization
+    # (and, later, per-turn respond-vs-delegate gating). Unset falls back to
+    # the coding provider/model.
+    router_provider: str | None = None
+    router_model: str | None = None
+
     max_tokens: int = 8192  # max output tokens per LLM call
 
     anthropic_api_key: str | None = None
diff --git a/anton/core/llm/client.py b/anton/core/llm/client.py
index 107cf670..72bb9c21 100644
--- a/anton/core/llm/client.py
+++ b/anton/core/llm/client.py
@@ -40,12 +40,21 @@ def __init__(
         planning_model: str,
         coding_provider: LLMProvider,
         coding_model: str,
+        router_provider: LLMProvider | None = None,
+        router_model: str | None = None,
         max_tokens: int = 8192,
     ) -> None:
         self._planning_provider = planning_provider
         self._planning_model = planning_model
         self._coding_provider = coding_provider
         self._coding_model = coding_model
+        # Router role: the cheap model that owns history
+        # summarization (and, later, per-turn respond-vs-delegate gating).
+        # Defaults to the coding role so hosts that construct LLMClient
+        # directly (cowork-server) get behavior-preserving summarization
+        # with no changes.
+        self._router_provider = router_provider or coding_provider
+        self._router_model = router_model or coding_model
         self._max_tokens = max_tokens
 
     async def plan(
@@ -100,6 +109,16 @@ def coding_model(self) -> str:
         """The model name used for coding/skill execution."""
         return self._coding_model
 
+    @property
+    def router_provider(self) -> LLMProvider:
+        """The LLM provider used for the cheap router (summarization) role."""
+        return self._router_provider
+
+    @property
+    def router_model(self) -> str:
+        """The model name used for the cheap router (summarization) role."""
+        return self._router_model
+
     async def code(
         self,
         *,
@@ -118,6 +137,26 @@ async def code(
             native_web_tools=native_web_tools,
         )
 
+    async def summarize(
+        self,
+        *,
+        system: str,
+        messages: list[dict],
+        max_tokens: int | None = None,
+    ) -> LLMResponse:
+        """History-compaction call — runs on the cheap router role.
+
+        Falls back to the coding role when no router model is configured
+        (the router_* kwargs default to the coding role in __init__), so
+        this is behavior-preserving unless a distinct model is selected.
+        """
+        return await self._router_provider.complete(
+            model=self._router_model,
+            system=system,
+            messages=messages,
+            max_tokens=max_tokens or self._max_tokens,
+        )
+
     async def _generate_object_with(
         self,
         schema_class,
@@ -301,6 +340,18 @@ def from_settings(cls, settings: AntonSettings) -> LLMClient:
         if coding_factory is None:
             raise ValueError(f"Unknown coding provider: {settings.coding_provider}")
 
+        # Router role: the cheap model for summarization (and later gating).
+        # Optional override; unset falls back to the coding provider/model
+        # inside __init__. No reasoning effort: summarization is a single
+        # cheap call.
+        router_provider = None
+        router_provider_name = getattr(settings, "router_provider", None)
+        if router_provider_name:
+            router_factory = providers.get(router_provider_name)
+            if router_factory is None:
+                raise ValueError(f"Unknown router provider: {router_provider_name}")
+            router_provider = router_factory(None)
+
         return cls(
             planning_provider=planning_factory(
                 getattr(settings, "planning_reasoning_effort", None)
@@ -310,5 +361,7 @@ def from_settings(cls, settings: AntonSettings) -> LLMClient:
                 getattr(settings, "coding_reasoning_effort", None)
             ),
             coding_model=settings.coding_model,
+            router_provider=router_provider,
+            router_model=getattr(settings, "router_model", None),
             max_tokens=getattr(settings, "max_tokens", 8192),
         )
diff --git a/anton/core/session.py b/anton/core/session.py
index adbe78c8..85e7d507 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -1027,7 +1027,7 @@ async def _summarize_history(self) -> None:
             # 3b-full: a structured, in-place-updated STATE RECORD rather than a
             # freeform blob — so "Remaining" work survives compaction instead of
             # being flattened into prose.
-            summary_response = await self._llm.code(
+            summary_response = await self._llm.summarize(
                 system=(
                     "You compact an agent's earlier conversation into a terse, factual "
                     "STATE RECORD (not prose). Output only these sections, omitting any "
diff --git a/tests/test_client.py b/tests/test_client.py
index 6a73796f..1e91dda1 100644
--- a/tests/test_client.py
+++ b/tests/test_client.py
@@ -73,6 +73,61 @@ async def test_plan_passes_tools(self, mock_providers):
         assert call_kwargs["tools"] == tools
 
 
+class TestRouterRole:
+    """Summarization runs on the router role, which defaults to the coding
+    role when no distinct router model is configured (behavior-preserving)."""
+
+    async def test_summarize_defaults_to_coding_role(self, mock_providers):
+        planning, coding = mock_providers
+        client = LLMClient(
+            planning_provider=planning,
+            planning_model="model-a",
+            coding_provider=coding,
+            coding_model="model-b",
+        )
+        result = await client.summarize(
+            system="sys", messages=[{"role": "user", "content": "old turns"}]
+        )
+        coding.complete.assert_awaited_once()
+        assert coding.complete.call_args.kwargs["model"] == "model-b"
+        assert result.content == "code"
+
+    async def test_summarize_uses_distinct_router_model(self, mock_providers):
+        planning, coding = mock_providers
+        router = AsyncMock(spec=LLMProvider)
+        router.complete = AsyncMock(
+            return_value=LLMResponse(content="summary", usage=Usage())
+        )
+        client = LLMClient(
+            planning_provider=planning,
+            planning_model="model-a",
+            coding_provider=coding,
+            coding_model="model-b",
+            router_provider=router,
+            router_model="model-c",
+        )
+        result = await client.summarize(
+            system="sys", messages=[{"role": "user", "content": "old turns"}]
+        )
+        router.complete.assert_awaited_once()
+        assert router.complete.call_args.kwargs["model"] == "model-c"
+        coding.complete.assert_not_awaited()
+        assert result.content == "summary"
+        assert client.router_provider is router
+        assert client.router_model == "model-c"
+
+    def test_router_accessors_fall_back_to_coding(self, mock_providers):
+        planning, coding = mock_providers
+        client = LLMClient(
+            planning_provider=planning,
+            planning_model="model-a",
+            coding_provider=coding,
+            coding_model="model-b",
+        )
+        assert client.router_provider is coding
+        assert client.router_model == "model-b"
+
+
 class TestLLMClientFromSettings:
     def test_from_settings_creates_client(self):
         from anton.core.llm.anthropic import AnthropicProvider
@@ -129,3 +184,39 @@ def test_unknown_coding_provider_raises(self):
         )
         with pytest.raises(ValueError, match="Unknown coding provider"):
             LLMClient.from_settings(settings)
+
+    def test_router_model_wired_to_router_role(self):
+        with patch("anthropic.AsyncAnthropic"):
+            settings = AntonSettings(
+                planning_provider="anthropic",
+                coding_provider="anthropic",
+                coding_model="coding-m",
+                router_provider="anthropic",
+                router_model="router-m",
+                anthropic_api_key="test-key",
+                _env_file=None,
+            )
+            client = LLMClient.from_settings(settings)
+            assert client.router_model == "router-m"
+
+    def test_router_unset_falls_back_to_coding_role(self):
+        with patch("anthropic.AsyncAnthropic"):
+            settings = AntonSettings(
+                planning_provider="anthropic",
+                coding_provider="anthropic",
+                coding_model="coding-m",
+                anthropic_api_key="test-key",
+                _env_file=None,
+            )
+            client = LLMClient.from_settings(settings)
+            assert client.router_provider is client._coding_provider
+            assert client.router_model == "coding-m"
+
+    def test_unknown_router_provider_raises(self):
+        settings = AntonSettings(
+            router_provider="unknown",
+            anthropic_api_key="test",
+            _env_file=None,
+        )
+        with pytest.raises(ValueError, match="Unknown router provider"):
+            LLMClient.from_settings(settings)
diff --git a/tests/test_settings.py b/tests/test_settings.py
index a45232a4..14bb1328 100644
--- a/tests/test_settings.py
+++ b/tests/test_settings.py
@@ -199,6 +199,21 @@ def test_other_providers_pass_through(self, monkeypatch):
             s = AntonSettings(planning_provider=p, _env_file=None)
             assert s.planning_provider == p
 
+    def test_minds_cloud_router_maps_to_openai_compatible(self, monkeypatch):
+        # from_settings validates the router role identically, so the same
+        # normalization must cover router_provider or it re-crashes there.
+        for k in _ANTON_MODEL_KEYS:
+            monkeypatch.delenv(k, raising=False)
+        s = AntonSettings(router_provider="minds-cloud", _env_file=None)
+        assert s.router_provider == "openai-compatible"
+
+    def test_router_provider_and_model_default_none(self, monkeypatch):
+        for k in _ANTON_MODEL_KEYS:
+            monkeypatch.delenv(k, raising=False)
+        s = AntonSettings(_env_file=None)
+        assert s.router_provider is None
+        assert s.router_model is None
+
     def test_from_settings_does_not_crash_on_minds_cloud(self, monkeypatch):
         # The exact regression: building the LLM client from a minds-cloud
         # config must not raise "Unknown planning provider".

From 8675e4b86cd42169796255af2dc5ea9c7c2e61c5 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 22 Jul 2026 14:20:49 +0300
Subject: [PATCH 21/33] thalamus gate

---
 anton/core/llm/client.py   |  23 +++
 anton/core/llm/thalamus.py | 332 ++++++++++++++++++++++++++++++++++++
 anton/core/session.py      | 174 ++++++++++++++++++-
 anton/core/settings.py     |  12 ++
 tests/test_thalamus.py     | 341 +++++++++++++++++++++++++++++++++++++
 5 files changed, 878 insertions(+), 4 deletions(-)
 create mode 100644 anton/core/llm/thalamus.py
 create mode 100644 tests/test_thalamus.py

diff --git a/anton/core/llm/client.py b/anton/core/llm/client.py
index 72bb9c21..88c96629 100644
--- a/anton/core/llm/client.py
+++ b/anton/core/llm/client.py
@@ -157,6 +157,29 @@ async def summarize(
             max_tokens=max_tokens or self._max_tokens,
         )
 
+    async def gate(
+        self,
+        *,
+        system: str,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        tool_choice: dict | None = None,
+        max_tokens: int | None = None,
+    ) -> LLMResponse:
+        """One cheap gating call on the router role — see `anton.core.llm.thalamus`.
+
+        No ``native_web_tools``: the thalamus must never do work itself,
+        only answer from context or delegate.
+        """
+        return await self._router_provider.complete(
+            model=self._router_model,
+            system=system,
+            messages=messages,
+            tools=tools,
+            tool_choice=tool_choice,
+            max_tokens=max_tokens or self._max_tokens,
+        )
+
     async def _generate_object_with(
         self,
         schema_class,
diff --git a/anton/core/llm/thalamus.py b/anton/core/llm/thalamus.py
new file mode 100644
index 00000000..c1c90e7c
--- /dev/null
+++ b/anton/core/llm/thalamus.py
@@ -0,0 +1,332 @@
+"""Thalamus — the gate between an incoming turn and the cortex.
+
+Brain analogue
+==============
+
+The thalamus is the brain's central relay. Almost every sensory and
+motor signal passes through it on the way to the cortex — it is the
+first thing a signal hits, and it decides what happens next. Four of
+its properties are worth stealing:
+
+1. **It gates; it does not compute.** The thalamus relays signals and
+   modulates their gain. The heavy interpretation happens in the cortex.
+   A thalamus that started "thinking" would be both slow and a liability.
+
+2. **Its default posture is inhibitory.** The thalamic reticular
+   nucleus (TRN) is a shell of inhibitory neurons that suppresses relay
+   by default and selectively *dis*inhibits the one channel that earns
+   passage — Crick's "searchlight." Nothing gets through on a maybe.
+
+3. **It has two firing modes.** *Tonic* mode faithfully relays a simple,
+   attended signal. *Burst* mode is an alerting spike that says "cortex,
+   wake up, this one needs you." Every signal resolves to one or the
+   other.
+
+4. **The cortex talks back — a lot.** Corticothalamic fibers outnumber
+   the feed-forward ones roughly ten to one: the cortex constantly
+   biases what the thalamus lets through, based on context and
+   expectation. The gate is not context-free.
+
+Anton's analogue
+================
+
+Anton's thalamus is the cheap front-model that every text turn hits
+first (ENG-648). Mapping the four properties:
+
+1. *Gate, don't compute* — the gating call runs on a cost-effective
+   model with a minimal system prompt and **no tool schemas**. It may
+   answer, or it may hand off, but it never does real work (no
+   scratchpad, no data, no files). Keeping it thin is the whole point.
+
+2. *Default-inhibit* — the direct-answer path (the TRN "searchlight")
+   opens only for signals that are unambiguously trivial: derivable
+   from the conversation plus stable general knowledge, needing nothing
+   created, fetched, or computed. Every ambiguity — an empty response,
+   an answer that overran the output budget, an outright error — falls
+   through to the cortex. A wrong direct answer is far costlier than the
+   gating overhead, so "when in doubt, relay up" is the resting state.
+
+3. *Two modes* — the two decisions ARE tonic vs burst. ``ACTION_RESPOND``
+   is tonic relay: the thalamus itself passes a faithful, complete
+   answer for a simple signal. ``ACTION_DELEGATE`` is the burst: a
+   forced ``delegate`` tool call that alerts the planning model (the
+   cortex) and hands the turn up, optionally naming procedural skills to
+   preload so the cortex doesn't spend a round fetching them.
+
+4. *Corticothalamic feedback* — partial today, and the clearest place to
+   grow. The gate already receives one top-down signal: the list of
+   learned skills (a cortical/hippocampal product) shapes what it can
+   preload. The principled next step is to let recent cortical outcomes
+   bias the gate — e.g. if this project's turns almost always need
+   tools, lower the bar to delegate. That hook is called out at
+   ``gate_turn`` rather than built here.
+
+Because the thalamus is the first relay, a misfire starves everything
+downstream — so, like a lesioned thalamus that must not silently drop
+signals, ours fails *open*: any doubt or error relays the turn up to the
+cortex untouched.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from anton.core.llm.provider import LLMResponse
+
+if TYPE_CHECKING:
+    from anton.core.llm.client import LLMClient
+
+
+# The two gate outcomes — tonic relay (answer here) vs burst (alert the
+# cortex / planning model). See the module docstring.
+ACTION_RESPOND = "respond"
+ACTION_DELEGATE = "delegate"
+
+# The thalamus sees a condensed, text-only view of history: full
+# transcripts (and the tool_use/tool_result blocks inside them) are what
+# the cortex needs, not what a gating call needs.
+_MAX_GATE_MESSAGES = 16
+_MAX_CHARS_PER_MESSAGE = 1_500
+
+
+DELEGATE_TOOL: dict = {
+    "name": "delegate",
+    "description": (
+        "Hand the current request to the full agent, which can execute "
+        "code, query data sources, search the web, read files, and build "
+        "artifacts. Call this immediately — with no preamble text — "
+        "whenever the request needs anything beyond a direct "
+        "conversational answer."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "reason": {
+                "type": "string",
+                "description": "One short sentence: why the full agent is needed.",
+            },
+            "skills": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": (
+                    "Labels of known procedures (from the list in your "
+                    "system prompt) that clearly apply to this request, so "
+                    "they are preloaded for the full agent. Omit if none "
+                    "apply."
+                ),
+            },
+        },
+        "required": ["reason"],
+    },
+}
+
+
+_THALAMUS_SYSTEM_PROMPT = """\
+You are the fast front-line responder for Anton, an agent that analyzes data, \
+executes code, and builds things for the user. Decide, for the latest user \
+message, between exactly two actions:
+
+1. ANSWER DIRECTLY — reply yourself, only when ALL of these hold:
+   - No tools are needed: no code execution, no file or attachment access, no \
+data queries, no web search or fetching, no artifacts or dashboards.
+   - Nothing must be created, modified, computed, fetched, scheduled, or verified.
+   - You are not guessing: the answer is already in the conversation, or is \
+stable general knowledge.
+   Typical direct cases: greetings and small talk, answering questions about \
+results already shown in the conversation, explaining or rephrasing something \
+already said, asking the user a clarifying question when their request is too \
+vague to act on.
+
+2. DELEGATE — call the `delegate` tool immediately, with NO text before it, \
+when the request involves data analysis, files or attachments, running or \
+writing code, building or updating anything, web lookups or information that \
+could be stale, connecting to services, or memory/skill management — or \
+whenever you are unsure. When in doubt, delegate: a wrong or stale direct \
+answer is far worse than the small cost of delegating.
+{skills_section}
+Direct answers must be short, helpful, and in the user's language. Never \
+mention this routing step, the `delegate` tool, or "the full agent" — from \
+the user's point of view there is only one assistant."""
+
+
+_SKILLS_SECTION_HEADER = """
+When you delegate, include in `skills` any of these known procedures that \
+clearly apply (their labels exactly as written), so they are preloaded:
+"""
+
+
+def build_thalamus_system_prompt(
+    skill_summaries: list[dict] | None = None,
+) -> str:
+    """Render the thalamus's minimal system prompt.
+
+    ``skill_summaries`` is the ``SkillStore.list_summaries()`` shape:
+    dicts with ``label`` and ``description`` keys. Listed one per line so
+    the thalamus can name preloads at delegation time. This list is the
+    one corticothalamic signal the gate currently receives — top-down
+    context (learned procedures) biasing what it can relay upward.
+    """
+    skills_section = ""
+    lines: list[str] = []
+    for s in skill_summaries or []:
+        label = (s.get("label") or "").strip()
+        if not label:
+            continue
+        when = (s.get("description") or "").strip()
+        lines.append(f"- `{label}` — {when}" if when else f"- `{label}`")
+    if lines:
+        skills_section = _SKILLS_SECTION_HEADER + "\n".join(lines) + "\n"
+    return _THALAMUS_SYSTEM_PROMPT.format(skills_section=skills_section)
+
+
+def condense_history(
+    history: list[dict],
+    *,
+    max_messages: int = _MAX_GATE_MESSAGES,
+    max_chars: int = _MAX_CHARS_PER_MESSAGE,
+) -> list[dict]:
+    """Build the thalamus's text-only view of the conversation.
+
+    Tool blocks collapse to one-line markers (the gate only needs to
+    know work happened, not its payload), long messages are middle-
+    truncated, and consecutive same-role messages merge so the result
+    keeps the role alternation providers require. Only the most recent
+    ``max_messages`` survive, and a leading assistant message left over
+    from the cut is dropped so the list starts with a user message.
+    """
+    condensed: list[dict] = []
+    for msg in history:
+        role = msg.get("role")
+        if role not in ("user", "assistant"):
+            continue
+        content = msg.get("content")
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            parts: list[str] = []
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "text":
+                    parts.append(str(block.get("text", "")))
+                elif btype == "tool_use":
+                    parts.append(f"[ran tool: {block.get('name', '?')}]")
+                elif btype == "tool_result":
+                    parts.append("[tool output omitted]")
+                elif btype == "image":
+                    parts.append("[image]")
+            text = "\n".join(p for p in parts if p)
+        else:
+            continue
+        text = text.strip()
+        if not text:
+            continue
+        if len(text) > max_chars:
+            half = max_chars // 2
+            text = f"{text[:half]}\n[… truncated …]\n{text[-half:]}"
+        if condensed and condensed[-1]["role"] == role:
+            condensed[-1]["content"] += "\n" + text
+        else:
+            condensed.append({"role": role, "content": text})
+
+    condensed = condensed[-max_messages:]
+    while condensed and condensed[0]["role"] != "user":
+        condensed.pop(0)
+    return condensed
+
+
+@dataclass
+class ThalamicDecision:
+    """Outcome of the gating call.
+
+    ``action`` is ACTION_RESPOND (tonic relay — ``text`` carries the
+    direct answer) or ACTION_DELEGATE (burst — ``skills`` carries
+    preload labels validated later). ``response`` is the raw gating
+    LLMResponse, kept so callers can surface its usage in stream events.
+    """
+
+    action: str
+    text: str = ""
+    skills: list[str] = field(default_factory=list)
+    reason: str = ""
+    response: LLMResponse | None = None
+
+
+async def gate_turn(
+    llm: "LLMClient",
+    *,
+    history: list[dict],
+    skill_summaries: list[dict] | None = None,
+    max_tokens: int = 1024,
+) -> ThalamicDecision:
+    """Run the gating call and interpret its outcome.
+
+    Every non-answer shape resolves to DELEGATE (default-inhibit): a
+    `delegate` tool call (the explicit burst), an empty response, or a
+    direct answer cut off by ``max_tokens`` — an answer that long is
+    evidence the turn wasn't trivial, and a truncated reply must never
+    reach the user.
+
+    Corticothalamic-feedback hook: today the only top-down signal is
+    ``skill_summaries``. A future version can accept recent cortical
+    outcomes (delegation rate per project, last-turn tool usage) here and
+    bias the gate — lowering the bar to delegate where the cortex keeps
+    getting woken anyway. Deliberately not built yet; see the module
+    docstring.
+    """
+    messages = condense_history(history)
+    if not messages:
+        return ThalamicDecision(action=ACTION_DELEGATE, reason="no routable history")
+
+    response = await llm.gate(
+        system=build_thalamus_system_prompt(skill_summaries),
+        messages=messages,
+        tools=[DELEGATE_TOOL],
+        max_tokens=max_tokens,
+    )
+
+    for tc in response.tool_calls:
+        if tc.name != "delegate":
+            continue
+        tc_input = tc.input if isinstance(tc.input, dict) else {}
+        skills = [
+            s.strip()
+            for s in (tc_input.get("skills") or [])
+            if isinstance(s, str) and s.strip()
+        ]
+        return ThalamicDecision(
+            action=ACTION_DELEGATE,
+            skills=skills,
+            reason=str(tc_input.get("reason", "")),
+            response=response,
+        )
+
+    if response.stop_reason in ("max_tokens", "length"):
+        return ThalamicDecision(
+            action=ACTION_DELEGATE,
+            reason="direct answer exceeded the gating output budget",
+            response=response,
+        )
+
+    text = (response.content or "").strip()
+    if not text:
+        return ThalamicDecision(
+            action=ACTION_DELEGATE,
+            reason="thalamus produced no answer",
+            response=response,
+        )
+
+    return ThalamicDecision(action=ACTION_RESPOND, text=text, response=response)
+
+
+__all__ = [
+    "ACTION_DELEGATE",
+    "ACTION_RESPOND",
+    "DELEGATE_TOOL",
+    "ThalamicDecision",
+    "build_thalamus_system_prompt",
+    "condense_history",
+    "gate_turn",
+]
diff --git a/anton/core/session.py b/anton/core/session.py
index 85e7d507..dae5d7d1 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -5,6 +5,7 @@
 from dataclasses import asdict, dataclass, field, replace
 from datetime import datetime
 import json
+import logging
 import re
 from typing import TYPE_CHECKING, List, Literal
 import os
@@ -27,6 +28,7 @@
 )
 from anton.core.llm.provider import (
     ContextOverflowError,
+    LLMResponse,
     ModelUnavailableError,
     StreamComplete,
     StreamContextCompacted,
@@ -37,6 +39,11 @@
     TokenLimitExceeded,
     ToolCall,
 )
+from anton.core.llm.thalamus import (
+    ACTION_RESPOND,
+    ThalamicDecision,
+    gate_turn,
+)
 from anton.core.llm.tracing import (
     TraceContext,
     reset_trace_context,
@@ -77,6 +84,8 @@
 # recognize and update it in place rather than summarize a summary.
 _COMPACTED_MARKER = "[COMPACTED CONTEXT — REFERENCE ONLY]"
 
+logger = logging.getLogger(__name__)
+
 
 if TYPE_CHECKING:
     from rich.console import Console
@@ -282,6 +291,10 @@ class ChatSessionConfig:
     # None → fall back to today.
     started_at: datetime | None = None
     selection_elicitor: SelectionElicitor | None = None
+    # Cheap front-model routing (ENG-648). None (default) defers to the
+    # settings' `router_enabled` (ANTON_ROUTER_ENABLED); hosts pass an
+    # explicit bool to override per session.
+    router_enabled: bool | None = None
 
 
 class ChatSession:
@@ -302,6 +315,20 @@ def __init__(self, config: ChatSessionConfig) -> None:
         self._resilience_nudge_at = s.resilience_nudge_at
         self._token_status_cache_ttl = s.token_status_cache_ttl
         self._llm = config.llm_client
+        # Router (ENG-648): explicit host override wins; otherwise the
+        # settings flag (ANTON_ROUTER_ENABLED). getattr-guarded because
+        # tests pass bare CoreSettings-shaped objects.
+        self._router_enabled = (
+            config.router_enabled
+            if config.router_enabled is not None
+            else bool(getattr(s, "router_enabled", False))
+        )
+        self._router_max_tokens = int(getattr(s, "router_max_tokens", 1024))
+        # Monotonic counter for thalamus-preloaded tool_use ids. Deliberately
+        # separate from `_turn_count`, which only increments in turn_stream()
+        # — using it here would emit the same id on every call made through
+        # the non-streaming turn() API.
+        self._thalamus_recall_counter = 0
         self._self_awareness = config.self_awareness
         self._cortex = config.cortex
         self._episodic = config.episodic
@@ -935,11 +962,13 @@ async def _reap_tracked_backends(self) -> None:
         self._tracked_backends.clear()
 
     async def _summarize_history(self) -> None:
-        """Compress old conversation turns into a summary using the coding model.
+        """Compress old conversation turns into a summary.
 
         Splits history into old (first 60%) and recent (last 40%), keeping at
-        least 4 recent turns.  The old portion is summarized by the fast coding
-        model and replaced with a single user message.
+        least 4 recent turns. The old portion is summarized by the routing/
+        summarization model (the router role, which falls back to the coding
+        model when no distinct one is configured) and replaced with a single
+        user message.
         """
         if len(self._history) < 6:
             return  # Too short to summarize
@@ -1516,6 +1545,96 @@ def _schedule_cerebellum_flush(self) -> None:
             # Cerebellum learning is best-effort, so just drop the buffer.
             cb.reset()
 
+    async def _gate_turn(self) -> ThalamicDecision | None:
+        """Run the cheap routing call for the turn just appended to history.
+
+        Returns None — meaning "proceed to the planning model as if no
+        thalamus existed" — on any thalamus failure. Routing must never be
+        able to break a turn; it can only save one.
+        """
+        try:
+            summaries = (
+                self._skill_store.list_summaries()
+                if self._skill_store is not None
+                else []
+            )
+        except Exception:
+            summaries = []
+        try:
+            return await gate_turn(
+                self._llm,
+                history=self._history,
+                skill_summaries=summaries,
+                max_tokens=self._router_max_tokens,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Router call failed (%s) — falling through to the planning model.",
+                exc,
+            )
+            return None
+
+    def _inject_recalled_skills(self, labels: list[str]) -> None:
+        """Preload thalamus-named skills as a synthetic recall_skill exchange.
+
+        Appends an assistant `tool_use` + user `tool_result` pair to
+        history, byte-identical in payload to what the planning model
+        would have gotten by calling `recall_skill` itself — but without
+        spending a full-context planning round on the fetch. Labels must
+        match exactly (no fuzzy fallback: a wrong preload is worse than
+        none), unknown labels are dropped silently, and at most 3 skills
+        load per turn. Built-ins and user skills resolve through the same
+        SkillStore that `recall_skill` uses.
+        """
+        if not labels:
+            return
+        store = self._skill_store
+        if store is None:
+            return
+        from anton.core.tools.recall_skill import _format_skill_response
+
+        self._thalamus_recall_counter += 1
+        tool_uses: list[dict] = []
+        results: list[dict] = []
+        seen: set[str] = set()
+        for label in labels:
+            label = (label or "").strip()
+            if not label or label in seen:
+                continue
+            seen.add(label)
+            if len(tool_uses) >= 3:
+                break
+            try:
+                skill = store.load(label)
+            except Exception:
+                skill = None
+            if skill is None:
+                continue
+            content = _format_skill_response(skill)
+            try:
+                store.increment_recommended(skill.label, stage=1)
+            except Exception:
+                pass
+            tu_id = f"thalamus_recall_{self._thalamus_recall_counter}_{len(tool_uses)}"
+            tool_uses.append(
+                {
+                    "type": "tool_use",
+                    "id": tu_id,
+                    "name": "recall_skill",
+                    "input": {"label": skill.label},
+                }
+            )
+            results.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": tu_id,
+                    "content": content,
+                }
+            )
+        if tool_uses:
+            self._append_history({"role": "assistant", "content": tool_uses})
+            self._append_history({"role": "user", "content": results})
+
     async def turn(self, user_input: str | list[dict]) -> str:
         user_input = _scrub_user_input(user_input)
         self._append_history({"role": "user", "content": user_input})
@@ -1525,6 +1644,26 @@ async def turn(self, user_input: str | list[dict]) -> str:
             if isinstance(user_input, str)
             else next((b["text"] for b in user_input if b.get("type") == "text"), "")
         )
+
+        # Cheap front-model routing (ENG-648). Text-only turns first hit
+        # the thalamus model, which either answers trivial/from-context
+        # requests directly (skipping the full prompt + tools + planning
+        # model entirely) or delegates, optionally preloading skills.
+        # Image turns skip the thalamus — attachments imply real work.
+        if self._router_enabled and isinstance(user_input, str):
+            decision = await self._gate_turn()
+            if decision is not None and decision.action == ACTION_RESPOND:
+                self._append_history(
+                    {"role": "assistant", "content": decision.text}
+                )
+                if self._cortex is not None and self._cortex.mode != "off":
+                    self._cortex.maybe_vacuum()
+                self._schedule_cerebellum_flush()
+                self._schedule_acc_flush()
+                return decision.text
+            if decision is not None and decision.skills:
+                self._inject_recalled_skills(decision.skills)
+
         tools = self._build_tools()
         system = await self._build_system_prompt(user_msg_str)
         self._compacted_this_turn = False
@@ -1722,7 +1861,34 @@ async def turn_stream(
         )
 
         try:
-            while True:
+            # Cheap front-model routing (ENG-648). Text-only turns first
+            # hit the thalamus model, which either answers trivial/from-
+            # context requests directly (skipping the full prompt + tool
+            # schemas + planning model entirely) or delegates, optionally
+            # preloading skills into history so the planning model doesn't
+            # spend a round on recall_skill. Image turns skip the thalamus —
+            # attachments imply real work. The thalamus buffers rather than
+            # streams: direct answers are short by construction
+            # (router_max_tokens), and a delegate decision must never leak
+            # preamble text to the user.
+            routed_direct = False
+            if self._router_enabled and isinstance(user_input, str):
+                decision = await self._gate_turn()
+                if decision is not None and decision.action == ACTION_RESPOND:
+                    self._append_history(
+                        {"role": "assistant", "content": decision.text}
+                    )
+                    assistant_text_parts.append(decision.text)
+                    yield StreamTextDelta(text=decision.text)
+                    yield StreamComplete(
+                        response=decision.response
+                        or LLMResponse(content=decision.text)
+                    )
+                    routed_direct = True
+                elif decision is not None and decision.skills:
+                    self._inject_recalled_skills(decision.skills)
+
+            while not routed_direct:
                 try:
                     async for event in self._stream_and_handle_tools(user_msg_str):
                         if isinstance(event, StreamTextDelta):
diff --git a/anton/core/settings.py b/anton/core/settings.py
index 9bcf07bb..5057f8b9 100644
--- a/anton/core/settings.py
+++ b/anton/core/settings.py
@@ -5,6 +5,18 @@
 class CoreSettings(BaseSettings):
     model_config = {"env_prefix": "ANTON_", "extra": "ignore"}
 
+    # Router — cheap front-model gating (ENG-648). When enabled, every text
+    # turn first hits the router model, which either answers trivial/from-
+    # context requests directly or delegates to the planning model (optionally
+    # preloading skills). The mechanism is the "thalamus" (see
+    # anton/core/llm/thalamus.py); the user-facing knobs stay "router". Off by
+    # default until evaluated; flip with ANTON_ROUTER_ENABLED=true.
+    router_enabled: bool = False
+    # Output budget for the gating call. Deliberately small: a direct
+    # answer that doesn't fit here is evidence the turn wasn't trivial,
+    # and the router treats truncation as "delegate".
+    router_max_tokens: int = 1024
+
     # Session orchestration tuning
     max_tool_rounds: int = 25
     max_continuations: int = 3
diff --git a/tests/test_thalamus.py b/tests/test_thalamus.py
new file mode 100644
index 00000000..bf92fb58
--- /dev/null
+++ b/tests/test_thalamus.py
@@ -0,0 +1,341 @@
+"""Tests for the cheap front-model thalamus (ENG-648).
+
+Covers the three layers: history condensation, decision parsing in
+`gate_turn`, and the ChatSession integration (direct answer, delegation
+with skill preload, fail-open fallback, and the off-by-default flag).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+from anton.core.session import ChatSession, ChatSessionConfig
+from anton.core.llm.provider import (
+    LLMResponse,
+    StreamComplete,
+    StreamTextDelta,
+    ToolCall,
+    Usage,
+)
+from anton.core.llm.thalamus import (
+    ACTION_DELEGATE,
+    ACTION_RESPOND,
+    condense_history,
+    gate_turn,
+)
+from tests.conftest import make_mock_llm
+
+
+def _response(
+    content: str = "",
+    tool_calls: list[ToolCall] | None = None,
+    stop_reason: str | None = "end_turn",
+) -> LLMResponse:
+    return LLMResponse(
+        content=content,
+        tool_calls=tool_calls or [],
+        usage=Usage(input_tokens=10, output_tokens=20),
+        stop_reason=stop_reason,
+    )
+
+
+def _delegate_call(reason: str = "needs tools", skills: list[str] | None = None) -> ToolCall:
+    tc_input: dict = {"reason": reason}
+    if skills is not None:
+        tc_input["skills"] = skills
+    return ToolCall(id="tc_1", name="delegate", input=tc_input)
+
+
+class TestCondenseHistory:
+    def test_tool_blocks_collapse_to_markers(self):
+        history = [
+            {"role": "user", "content": "crunch the numbers"},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "On it."},
+                    {"type": "tool_use", "id": "t1", "name": "scratchpad", "input": {}},
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {"type": "tool_result", "tool_use_id": "t1", "content": "x" * 9000}
+                ],
+            },
+            {"role": "assistant", "content": "Done — the mean is 4.2."},
+            {"role": "user", "content": "what was the mean again?"},
+        ]
+        condensed = condense_history(history)
+        assert condensed[0] == {"role": "user", "content": "crunch the numbers"}
+        assert "[ran tool: scratchpad]" in condensed[1]["content"]
+        assert "[tool output omitted]" in condensed[2]["content"]
+        assert "x" * 100 not in condensed[2]["content"]  # payload not leaked
+        assert condensed[-1]["content"] == "what was the mean again?"
+
+    def test_merges_consecutive_same_role_and_truncates(self):
+        history = [
+            {"role": "user", "content": "a"},
+            {"role": "user", "content": "b" * 5000},
+            {"role": "assistant", "content": "ok"},
+        ]
+        condensed = condense_history(history, max_chars=200)
+        assert len(condensed) == 2
+        assert condensed[0]["role"] == "user"
+        assert condensed[0]["content"].startswith("a\n")
+        assert "[… truncated …]" in condensed[0]["content"]
+
+    def test_window_keeps_recent_and_starts_with_user(self):
+        history = []
+        for i in range(20):
+            history.append({"role": "user", "content": f"u{i}"})
+            history.append({"role": "assistant", "content": f"a{i}"})
+        condensed = condense_history(history, max_messages=5)
+        # 5 kept, but the leading assistant left by the cut is dropped
+        assert len(condensed) == 4
+        assert condensed[0]["role"] == "user"
+        assert condensed[-1]["content"] == "a19"
+
+    def test_empty_and_nontext_history(self):
+        assert condense_history([]) == []
+        assert condense_history([{"role": "system", "content": "x"}]) == []
+
+
+class TestGateTurn:
+    async def test_direct_answer(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(return_value=_response("Four."))
+        decision = await gate_turn(llm, history=[{"role": "user", "content": "2+2?"}])
+        assert decision.action == ACTION_RESPOND
+        assert decision.text == "Four."
+
+    async def test_delegate_tool_call_with_skills(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(
+            return_value=_response(
+                tool_calls=[_delegate_call(skills=["csv-summary", "  ", 42, "other"])]
+            )
+        )
+        decision = await gate_turn(llm, history=[{"role": "user", "content": "analyze data.csv"}])
+        assert decision.action == ACTION_DELEGATE
+        assert decision.skills == ["csv-summary", "other"]
+        assert decision.reason == "needs tools"
+
+    async def test_truncated_answer_delegates(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(
+            return_value=_response("a very long answer that got cut", stop_reason="max_tokens")
+        )
+        decision = await gate_turn(llm, history=[{"role": "user", "content": "explain X"}])
+        assert decision.action == ACTION_DELEGATE
+
+    async def test_empty_answer_delegates(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(return_value=_response(""))
+        decision = await gate_turn(llm, history=[{"role": "user", "content": "hm"}])
+        assert decision.action == ACTION_DELEGATE
+
+    async def test_unroutable_history_delegates_without_llm_call(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock()
+        decision = await gate_turn(llm, history=[{"role": "system", "content": "x"}])
+        assert decision.action == ACTION_DELEGATE
+        llm.gate.assert_not_called()
+
+    async def test_skill_summaries_listed_in_prompt(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(return_value=_response("hi"))
+        await gate_turn(
+            llm,
+            history=[{"role": "user", "content": "hi"}],
+            skill_summaries=[{"label": "csv-summary", "description": "Summarize CSVs"}],
+        )
+        system = llm.gate.call_args.kwargs["system"]
+        assert "`csv-summary` — Summarize CSVs" in system
+
+
+def _mock_skill_store():
+    skill = SimpleNamespace(
+        label="csv-summary",
+        name="CSV Summary",
+        description="Summarize CSVs",
+        declarative_md="1. load the CSV\n2. describe it",
+    )
+    store = MagicMock()
+    store.list_summaries.return_value = [
+        {"label": "csv-summary", "description": "Summarize CSVs"}
+    ]
+    store.load.side_effect = lambda label: skill if label == "csv-summary" else None
+    return store
+
+
+class TestSessionThalamus:
+    async def test_thalamus_off_by_default(self):
+        llm = make_mock_llm()
+        llm.plan = AsyncMock(return_value=_response("Hey!"))
+        llm.gate = AsyncMock()
+        session = ChatSession(ChatSessionConfig(llm_client=llm))
+        reply = await session.turn("hi")
+        assert reply == "Hey!"
+        llm.gate.assert_not_called()
+
+    async def test_direct_answer_skips_planning(self):
+        llm = make_mock_llm()
+        llm.plan = AsyncMock()
+        llm.gate = AsyncMock(return_value=_response("Four."))
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        reply = await session.turn("what is 2+2?")
+        assert reply == "Four."
+        llm.plan.assert_not_called()
+        assert session.history == [
+            {"role": "user", "content": "what is 2+2?"},
+            {"role": "assistant", "content": "Four."},
+        ]
+
+    async def test_direct_answer_streaming(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(return_value=_response("Four."))
+
+        async def _plan_stream(**kwargs):
+            raise AssertionError("planning model must not be called")
+            yield  # pragma: no cover
+
+        llm.plan_stream = _plan_stream
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        events = [e async for e in session.turn_stream("what is 2+2?")]
+        deltas = [e for e in events if isinstance(e, StreamTextDelta)]
+        completes = [e for e in events if isinstance(e, StreamComplete)]
+        assert [d.text for d in deltas] == ["Four."]
+        assert len(completes) == 1
+        assert session.history[-1] == {"role": "assistant", "content": "Four."}
+
+    async def test_delegate_preloads_skills_then_plans(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(
+            return_value=_response(
+                tool_calls=[_delegate_call(skills=["csv-summary", "nonexistent"])]
+            )
+        )
+        llm.plan = AsyncMock(return_value=_response("Here's the summary."))
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        session._skill_store = _mock_skill_store()
+
+        reply = await session.turn("summarize data.csv")
+
+        assert reply == "Here's the summary."
+        llm.plan.assert_called_once()
+        # history: user → assistant(recall tool_use) → user(tool_result) → assistant
+        assert len(session.history) == 4
+        tool_use = session.history[1]["content"][0]
+        assert tool_use["name"] == "recall_skill"
+        assert tool_use["input"] == {"label": "csv-summary"}
+        tool_result = session.history[2]["content"][0]
+        assert tool_result["tool_use_id"] == tool_use["id"]
+        assert "1. load the CSV" in tool_result["content"]
+        # only the existing skill was preloaded, and its counter bumped
+        assert len(session.history[1]["content"]) == 1
+        session._skill_store.increment_recommended.assert_called_once_with(
+            "csv-summary", stage=1
+        )
+        # planning saw the preloaded exchange
+        planned_messages = llm.plan.call_args.kwargs["messages"]
+        assert planned_messages[1]["content"][0]["name"] == "recall_skill"
+
+    async def test_preload_ids_unique_across_non_streaming_turns(self):
+        # turn() (unlike turn_stream()) never increments _turn_count, so an
+        # id derived from it would repeat on every call — regression guard
+        # for that.
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(
+            return_value=_response(
+                tool_calls=[_delegate_call(skills=["csv-summary"])]
+            )
+        )
+        llm.plan = AsyncMock(return_value=_response("ok"))
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        session._skill_store = _mock_skill_store()
+
+        await session.turn("summarize data.csv")
+        first_id = session.history[1]["content"][0]["id"]
+
+        await session.turn("summarize data.csv again")
+        second_id = session.history[5]["content"][0]["id"]
+
+        assert first_id != second_id
+
+    async def test_delegate_streaming_reaches_planning(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(return_value=_response(tool_calls=[_delegate_call()]))
+
+        async def _plan_stream(**kwargs):
+            yield StreamTextDelta(text="Working on it.")
+            yield StreamComplete(response=_response("Working on it."))
+
+        llm.plan_stream = _plan_stream
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        events = [e async for e in session.turn_stream("analyze data.csv")]
+        assert any(
+            isinstance(e, StreamTextDelta) and e.text == "Working on it." for e in events
+        )
+
+    async def test_thalamus_failure_falls_back_to_planning(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(side_effect=RuntimeError("thalamus down"))
+        llm.plan = AsyncMock(return_value=_response("Handled anyway."))
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        reply = await session.turn("hi")
+        assert reply == "Handled anyway."
+        llm.plan.assert_called_once()
+
+    async def test_image_turns_skip_thalamus(self):
+        llm = make_mock_llm()
+        llm.gate = AsyncMock()
+        llm.plan = AsyncMock(return_value=_response("Nice chart."))
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        reply = await session.turn(
+            [
+                {"type": "text", "text": "what's in this image?"},
+                {"type": "image", "source": {"type": "base64", "data": "…"}},
+            ]
+        )
+        assert reply == "Nice chart."
+        llm.gate.assert_not_called()
+
+
+class TestLLMClientGate:
+    async def test_gate_defaults_to_coding_role(self):
+        from anton.core.llm.client import LLMClient
+
+        planning = AsyncMock()
+        coding = AsyncMock()
+        coding.complete = AsyncMock(return_value=_response("ok"))
+        client = LLMClient(
+            planning_provider=planning,
+            planning_model="big-model",
+            coding_provider=coding,
+            coding_model="small-model",
+        )
+        assert client.router_model == "small-model"
+        await client.gate(system="s", messages=[{"role": "user", "content": "x"}])
+        assert coding.complete.call_args.kwargs["model"] == "small-model"
+        planning.complete.assert_not_called()
+
+    async def test_gate_uses_explicit_router_role(self):
+        from anton.core.llm.client import LLMClient
+
+        planning = AsyncMock()
+        coding = AsyncMock()
+        router = AsyncMock()
+        router.complete = AsyncMock(return_value=_response("ok"))
+        client = LLMClient(
+            planning_provider=planning,
+            planning_model="big-model",
+            coding_provider=coding,
+            coding_model="small-model",
+            router_provider=router,
+            router_model="tiny-model",
+        )
+        await client.gate(system="s", messages=[{"role": "user", "content": "x"}])
+        assert router.complete.call_args.kwargs["model"] == "tiny-model"
+        coding.complete.assert_not_called()

From 0775df66aead73b7dcfd394c82fdf513ba6e876a Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Wed, 22 Jul 2026 09:19:04 -0700
Subject: [PATCH 22/33] ENG-940: explicit encoding="utf-8" on scratchpad/chat
 reads (launcher-independent UTF-8) (#263)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(scratchpad): read/write scratchpad + chat files as explicit UTF-8 (ENG-940)

Completes ENG-824's Fix #2 ("suspenders") that the belt-only fix left undone.
The scratchpad/chat-path reads relied entirely on PYTHONUTF8 being set by the
launcher, so any path that misses it (bare CLI, provisioned/Docker cowork,
OpenClaw) re-crashed on a GBK/CJK Windows host at `code = script_path.read_text()`.

Add explicit encoding="utf-8" to every text read/write in that path so they're
launcher-independent (belt AND suspenders, as ENG-824 specced):
- chat.py: script read (the root-caused crash site), .env read + append,
  published/legacy/pub_file JSON read + write.
- core/backends/local.py: .python_version + requirements.txt read + write.

Tests (tests/test_scratchpad_utf8.py): a real non-ASCII fixture proves the
explicit UTF-8 read round-trips while a host-locale (GBK) read crashes-or-
corrupts (payload-independent); a regression guard fails if any `.read_text()`
in anton/chat.py drops encoding=. Both independent of PYTHONUTF8.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(scratchpad): surrogatepass the cell-payload encode — encode-side sibling of ENG-824 (ENG-940)

Follow-up from ENG-940's new evidence (users sabrina/eddie/janis): a non-ASCII
Windows path (pt-BR "Área de Trabalho", emoji filename) is surrogate-escaped
into lone surrogates (\udcXX) when decoded on a non-UTF-8 host. When that string
reaches the strict UTF-8 encode of the cell payload sent to the subprocess, it
raises "UnicodeEncodeError: surrogates not allowed" and kills the whole session
— the encode-side sibling of ENG-824's decode crash.

- local.py: extract _encode_cell_payload() using errors="surrogatepass" so the
  host-side encode can't crash when the host isn't in UTF-8 mode; the subprocess
  (always UTF-8 mode) decodes the payload fine.
- The two chat.py JSON writes need NO change: json.dumps defaults to
  ensure_ascii=True, so surrogates become ASCII \uXXXX escapes and never reach
  the encoder (verified).
- tests: pin the surrogate-safe encode (strict raises, surrogatepass round-trips)
  and a broadened accented-Latin + emoji case that must pass through unmangled.
  Verified the surrogate test fails if the helper reverts to strict.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(scratchpad): use surrogateescape (not surrogatepass) for the cell-payload encode (ENG-940 self-review)

Adversarial review of de6d6fb caught a real bug in my own fix. surrogatepass
does NOT round-trip through the subprocess: the subprocess always runs in UTF-8
mode, so its stdin decodes with surrogateescape — and surrogatepass emits the
3-byte CESU form that surrogateescape then re-mangles (\udc81 -> three
surrogates), so the path would not survive intact.

surrogateescape is correct on both counts: it's the inverse of the os.fsdecode
that created these lone surrogates (U+DC80..U+DCFF), so it restores the original
path bytes, and it matches the subprocess's surrogateescape stdin decode — the
path arrives verbatim. Verified end-to-end.

Also fixes the test, which previously asserted a false surrogatepass/surrogatepass
symmetry; it now decodes with surrogateescape (what the subprocess actually
does) and genuinely discriminates — it fails if the helper reverts to
surrogatepass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/chat.py                 | 21 +++++---
 anton/core/backends/local.py  | 32 ++++++++++--
 tests/test_scratchpad_utf8.py | 94 +++++++++++++++++++++++++++++++++++
 3 files changed, 134 insertions(+), 13 deletions(-)

diff --git a/anton/chat.py b/anton/chat.py
index ed5f2f5c..c5b7c431 100644
--- a/anton/chat.py
+++ b/anton/chat.py
@@ -640,7 +640,7 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
     published_map = {}
     try:
         if published_json.is_file():
-            published_map = json.loads(published_json.read_text())
+            published_map = json.loads(published_json.read_text(encoding="utf-8"))
     except Exception:
         pass
     prev = published_map.get(published_key)
@@ -650,7 +650,7 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
         legacy_json = artifacts_root / ".published.json"
         try:
             if legacy_json.is_file():
-                legacy_map = json.loads(legacy_json.read_text())
+                legacy_map = json.loads(legacy_json.read_text(encoding="utf-8"))
                 legacy_entry = legacy_map.get(file_key)
                 if isinstance(legacy_entry, dict) and legacy_entry.get("report_id"):
                     prev = legacy_entry  # carry over report_id/url/last_md5/access
@@ -751,7 +751,7 @@ def _make_candidate(path: Path) -> tuple[str, Path, str, str] | None:
         })
         published_map[published_key] = entry
         try:
-            published_json.write_text(json.dumps(published_map, indent=2))
+            published_json.write_text(json.dumps(published_map, indent=2), encoding="utf-8")
         except Exception:
             pass
 
@@ -880,7 +880,7 @@ async def _handle_unpublish(
     artifacts_root = _Path(settings.artifacts_dir)
     for pub_file in artifacts_root.rglob(".published.json"):
         try:
-            data = _json.loads(pub_file.read_text())
+            data = _json.loads(pub_file.read_text(encoding="utf-8"))
         except Exception:
             continue
         if not isinstance(data, dict):
@@ -900,7 +900,7 @@ async def _handle_unpublish(
                 changed = True
         if changed:
             try:
-                pub_file.write_text(_json.dumps(data, indent=2))
+                pub_file.write_text(_json.dumps(data, indent=2), encoding="utf-8")
             except Exception:
                 pass
 
@@ -1021,7 +1021,12 @@ async def _agent_zero(console: Console, session: "ChatSession", settings) -> str
         description="Demo dashboard comparing NVDA stock and BTC prices over time.",
         type="html-app",
     )
-    code = script_path.read_text()
+    # Read as UTF-8 explicitly, never the host-locale default: on a non-UTF-8
+    # Windows code page (GBK/cp936) a bare read_text() crashes decoding UTF-8
+    # script content (ENG-824's root-caused crash site — 'gbk' codec can't
+    # decode …). Explicit encoding is launcher-independent, unlike the
+    # PYTHONUTF8 belt (ENG-940).
+    code = script_path.read_text(encoding="utf-8")
     output_dir = str(_store.folder_for(_demo_artifact.slug))
     output_html = str(Path(output_dir) / "dashboard.html")
     code = (
@@ -1146,9 +1151,9 @@ def _persist_first_run_done(settings) -> None:
 
     env_path = Path.home() / ".anton" / ".env"
     env_path.parent.mkdir(parents=True, exist_ok=True)
-    existing = env_path.read_text() if env_path.is_file() else ""
+    existing = env_path.read_text(encoding="utf-8") if env_path.is_file() else ""
     if "ANTON_FIRST_RUN_DONE" not in existing:
-        with env_path.open("a") as f:
+        with env_path.open("a", encoding="utf-8") as f:
             if existing and not existing.endswith("\n"):
                 f.write("\n")
             f.write("ANTON_FIRST_RUN_DONE=true\n")
diff --git a/anton/core/backends/local.py b/anton/core/backends/local.py
index 1c8973a6..d73ee85c 100644
--- a/anton/core/backends/local.py
+++ b/anton/core/backends/local.py
@@ -34,6 +34,28 @@ def _read_boot_script() -> str:
     return _BOOT_SCRIPT_PATH.read_text(encoding="utf-8")
 
 
+def _encode_cell_payload(payload: str) -> bytes:
+    """Encode the cell payload sent to the scratchpad subprocess.
+
+    ``errors="surrogateescape"`` rather than a strict UTF-8 encode: model-written
+    cell code can embed a filesystem path that ``os.fsdecode`` surrogate-escaped
+    when it couldn't decode the path bytes on a non-UTF-8 host (e.g. a pt-BR
+    ``Área de Trabalho`` or an emoji path on Windows → lone surrogates in
+    U+DC80..U+DCFF). A strict encode raises ``UnicodeEncodeError: surrogates not
+    allowed`` here and takes down the whole session before the code reaches the
+    subprocess — the encode-side sibling of ENG-824's decode crash (ENG-940).
+
+    ``surrogateescape`` (not ``surrogatepass``) is deliberate: it's the inverse
+    of the ``os.fsdecode`` that created these surrogates, so it restores the
+    original path bytes, and it matches how the subprocess — which always runs
+    in UTF-8 mode (``_utf8_env``) and so decodes stdin with ``surrogateescape``
+    — reads them back. ``surrogatepass`` would emit the 3-byte CESU form that the
+    subprocess's ``surrogateescape`` decode then re-mangles, so the path would
+    not survive intact.
+    """
+    return payload.encode("utf-8", errors="surrogateescape")
+
+
 def _utf8_env(base: "os._Environ[str] | dict[str, str]") -> dict[str, str]:
     """A copy of ``base`` with Python UTF-8 mode forced for the scratchpad
     subprocess.
@@ -317,7 +339,7 @@ def _save_requirements(self) -> None:
             return
         try:
             req_path = os.path.join(self._venv_dir, "requirements.txt")
-            with open(req_path, "w") as f:
+            with open(req_path, "w", encoding="utf-8") as f:
                 for pkg in sorted(self._installed_packages):
                     f.write(pkg + "\n")
         except OSError:
@@ -328,7 +350,7 @@ def _load_requirements(self) -> None:
             return
         req_path = os.path.join(self._venv_dir, "requirements.txt")
         try:
-            with open(req_path) as f:
+            with open(req_path, encoding="utf-8") as f:
                 for line in f:
                     pkg = line.strip()
                     if pkg:
@@ -341,7 +363,7 @@ def _save_python_version(self) -> None:
             return
         try:
             ver_path = os.path.join(self._venv_dir, ".python_version")
-            with open(ver_path, "w") as f:
+            with open(ver_path, "w", encoding="utf-8") as f:
                 f.write(f"{sys.version_info.major}.{sys.version_info.minor}\n")
         except OSError:
             pass
@@ -351,7 +373,7 @@ def _check_python_version(self) -> bool:
             return False
         ver_path = os.path.join(self._venv_dir, ".python_version")
         try:
-            with open(ver_path) as f:
+            with open(ver_path, encoding="utf-8") as f:
                 saved = f.read().strip()
             expected = f"{sys.version_info.major}.{sys.version_info.minor}"
             return saved == expected
@@ -530,7 +552,7 @@ async def execute_streaming(
             return
 
         payload = code + "\n" + CELL_DELIM + "\n"
-        self._proc.stdin.write(payload.encode("utf-8"))  # type: ignore[union-attr]
+        self._proc.stdin.write(_encode_cell_payload(payload))  # type: ignore[union-attr]
         await self._proc.stdin.drain()  # type: ignore[union-attr]
 
         total_timeout, inactivity_timeout = compute_timeouts(estimated_seconds)
diff --git a/tests/test_scratchpad_utf8.py b/tests/test_scratchpad_utf8.py
index ab54ec5f..a3a3e90a 100644
--- a/tests/test_scratchpad_utf8.py
+++ b/tests/test_scratchpad_utf8.py
@@ -3,6 +3,9 @@
 
 from __future__ import annotations
 
+import inspect
+import re
+
 import pytest
 
 import anton.core.backends.local as local
@@ -88,3 +91,94 @@ def spy_open(file, *args, **kwargs):
     assert seen.get("encoding") == "utf-8"  # assert before any later read
     written = (child_site / "_parent_venv.pth").read_text(encoding="utf-8")
     assert "/parent/site-packages" in written
+
+
+# ── ENG-940: the chat/scratchpad-path reads are launcher-independent ──────────
+#
+# ENG-824 shipped the PYTHONUTF8 "belt"; these pin the "suspenders" — explicit
+# encoding="utf-8" on the reads themselves — so they can't regress to the host
+# locale default on a launcher that doesn't set the env (bare CLI, Docker,
+# OpenClaw), which would re-crash on a GBK/CJK Windows host.
+
+def test_scratchpad_script_read_is_locale_independent(tmp_path):
+    # Models ENG-824's root-caused crash site (`code = script_path.read_text()`):
+    # the scratchpad script holds arbitrary model-written non-ASCII (string
+    # literals, comments). A host-locale (GBK) default read crashes on UTF-8
+    # bytes — the reported failure. Explicit encoding="utf-8" is locale-
+    # independent. Proven on a real fixture, no dependence on the interpreter's
+    # UTF-8 mode / PYTHONUTF8.
+    script = tmp_path / "cell.py"
+    body = 'label = "café — 数据 リポート"\nprint(label)\n'
+    script.write_text(body, encoding="utf-8")
+
+    raw = script.read_bytes()
+    assert any(b > 0x7F for b in raw)  # genuinely non-ASCII → a locale read is at risk
+
+    # The fix: an explicit UTF-8 read returns the script verbatim, independent
+    # of the host locale / PYTHONUTF8.
+    assert script.read_text(encoding="utf-8") == body
+
+    # A host-locale (GBK) default read is unsafe — it either raises (the
+    # reported ENG-824 crash) or silently corrupts the source. Payload-
+    # independent: we don't rely on which failure mode these bytes trigger.
+    try:
+        assert raw.decode("gbk") != raw.decode("utf-8")  # mojibake
+    except UnicodeDecodeError:
+        pass  # crash — the exact ENG-824 failure mode
+
+
+def test_chat_module_has_no_bare_read_text():
+    # Regression guard (ENG-940): every text read in anton/chat.py must pass an
+    # explicit encoding, so it can't silently revert to the host-locale default
+    # (the ENG-824 crash at `code = script_path.read_text()`). Fails the instant
+    # a `.read_text(...)` call omits encoding=.
+    import anton.chat as chat
+
+    src = inspect.getsource(chat)
+    bare = [
+        m.group(0)
+        for m in re.finditer(r"\.read_text\(([^)]*)\)", src)
+        if "encoding=" not in m.group(1)
+    ]
+    assert not bare, f"bare read_text() in anton/chat.py (add encoding='utf-8'): {bare}"
+
+
+# ── ENG-940: the *encode*-side sibling (write path, lone surrogates) ──────────
+#
+# Distinct from the decode crash above: on a non-UTF-8 host, a non-ASCII
+# Windows path (pt-BR "Área de Trabalho", an emoji filename) is surrogate-
+# escaped into lone surrogates (\udcXX) when decoded. When such a string reaches
+# the strict UTF-8 encode of the cell payload it raises "surrogates not allowed"
+# and kills the whole session (users sabrina/eddie/janis). surrogatepass keeps
+# the host-side encode from crashing; the subprocess (UTF-8 mode) decodes it.
+
+def test_cell_payload_encode_survives_lone_surrogate():
+    # A Windows path that os.fsdecode surrogate-escaped on a non-UTF-8 host lands
+    # in the model-written code as lone surrogates (U+DC80..U+DCFF). Model this
+    # exactly and assert the fix.
+    code = 'open(r"C:\\Users\\\udc81\udc9d\\index.html", "w")  # 🎉\n'
+    payload = code + "\n" + local.CELL_DELIM + "\n"
+
+    # A strict UTF-8 encode is the crash the three users hit.
+    with pytest.raises(UnicodeEncodeError):
+        payload.encode("utf-8")
+
+    # The fix: the encode no longer raises, independent of PYTHONUTF8.
+    encoded = local._encode_cell_payload(payload)
+    assert isinstance(encoded, bytes)
+
+    # The path survives intact end-to-end: the subprocess always runs in UTF-8
+    # mode, so its stdin decodes with surrogateescape. Decoding *that* way (not
+    # surrogatepass) must reproduce the original — this is why the helper uses
+    # surrogateescape. surrogatepass would fail this assertion (re-mangled).
+    assert encoded.decode("utf-8", errors="surrogateescape") == payload
+
+
+def test_cell_payload_encode_preserves_accented_and_emoji():
+    # Ordinary (well-formed) accented-Latin + emoji content must pass through
+    # byte-for-byte — the fix must not mangle the common case.
+    code = 'label = "Área de Trabalho 🎉 café"\nprint(label)\n'
+    payload = code + "\n" + local.CELL_DELIM + "\n"
+
+    encoded = local._encode_cell_payload(payload)
+    assert encoded.decode("utf-8") == payload  # strict decode: no corruption

From 043a017ca6adcfd92f7a679ad5ff824db481f57c Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Wed, 22 Jul 2026 19:29:17 +0300
Subject: [PATCH 23/33] fix: preload skill alreadyin history

---
 anton/core/session.py  | 24 ++++++++++++++++++++++--
 tests/test_thalamus.py | 41 +++++++++++++++++++++++++++++++++++------
 2 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/anton/core/session.py b/anton/core/session.py
index dae5d7d1..80a7a3b8 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -1561,7 +1561,7 @@ async def _gate_turn(self) -> ThalamicDecision | None:
         except Exception:
             summaries = []
         try:
-            return await gate_turn(
+            decision = await gate_turn(
                 self._llm,
                 history=self._history,
                 skill_summaries=summaries,
@@ -1573,6 +1573,18 @@ async def _gate_turn(self) -> ThalamicDecision | None:
                 exc,
             )
             return None
+        # The gate hits every text turn, so its usage must be visible in
+        # telemetry regardless of outcome — StreamComplete only surfaces it
+        # on the direct-answer path, leaving all delegated turns unaccounted.
+        usage = getattr(decision.response, "usage", None)
+        if usage is not None:
+            logger.info(
+                "Router gate: action=%s in_tokens=%s out_tokens=%s",
+                decision.action,
+                getattr(usage, "input_tokens", "?"),
+                getattr(usage, "output_tokens", "?"),
+            )
+        return decision
 
     def _inject_recalled_skills(self, labels: list[str]) -> None:
         """Preload thalamus-named skills as a synthetic recall_skill exchange.
@@ -1591,7 +1603,10 @@ def _inject_recalled_skills(self, labels: list[str]) -> None:
         store = self._skill_store
         if store is None:
             return
-        from anton.core.tools.recall_skill import _format_skill_response
+        from anton.core.tools.recall_skill import (
+            _already_in_history,
+            _format_skill_response,
+        )
 
         self._thalamus_recall_counter += 1
         tool_uses: list[dict] = []
@@ -1610,6 +1625,11 @@ def _inject_recalled_skills(self, labels: list[str]) -> None:
                 skill = None
             if skill is None:
                 continue
+            # Skip skills whose full body is already in context — mirrors
+            # handle_recall_skill's stub path so a preload can't duplicate a
+            # procedure the planning model already has (wasted tokens).
+            if _already_in_history(self, skill.label):
+                continue
             content = _format_skill_response(skill)
             try:
                 store.increment_recommended(skill.label, stage=1)
diff --git a/tests/test_thalamus.py b/tests/test_thalamus.py
index bf92fb58..3755c400 100644
--- a/tests/test_thalamus.py
+++ b/tests/test_thalamus.py
@@ -245,21 +245,36 @@ async def test_delegate_preloads_skills_then_plans(self):
     async def test_preload_ids_unique_across_non_streaming_turns(self):
         # turn() (unlike turn_stream()) never increments _turn_count, so an
         # id derived from it would repeat on every call — regression guard
-        # for that.
+        # for that. Two *different* skills across the two turns, since the
+        # same skill would be deduped on the second preload.
+        skills = {
+            "csv-summary": SimpleNamespace(
+                label="csv-summary", name="CSV Summary",
+                description="", declarative_md="1. load the CSV",
+            ),
+            "json-summary": SimpleNamespace(
+                label="json-summary", name="JSON Summary",
+                description="", declarative_md="1. load the JSON",
+            ),
+        }
+        store = MagicMock()
+        store.load.side_effect = lambda label: skills.get(label)
+
         llm = make_mock_llm()
         llm.gate = AsyncMock(
-            return_value=_response(
-                tool_calls=[_delegate_call(skills=["csv-summary"])]
-            )
+            side_effect=[
+                _response(tool_calls=[_delegate_call(skills=["csv-summary"])]),
+                _response(tool_calls=[_delegate_call(skills=["json-summary"])]),
+            ]
         )
         llm.plan = AsyncMock(return_value=_response("ok"))
         session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
-        session._skill_store = _mock_skill_store()
+        session._skill_store = store
 
         await session.turn("summarize data.csv")
         first_id = session.history[1]["content"][0]["id"]
 
-        await session.turn("summarize data.csv again")
+        await session.turn("now summarize data.json")
         second_id = session.history[5]["content"][0]["id"]
 
         assert first_id != second_id
@@ -279,6 +294,20 @@ async def _plan_stream(**kwargs):
             isinstance(e, StreamTextDelta) and e.text == "Working on it." for e in events
         )
 
+    async def test_preload_skips_skill_already_in_history(self):
+        # A skill whose full body is already in context must not be
+        # re-injected — mirrors handle_recall_skill's stub path, so a
+        # later delegate naming the same skill can't duplicate the
+        # procedure (wasted tokens).
+        llm = make_mock_llm()
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        session._skill_store = _mock_skill_store()
+
+        session._inject_recalled_skills(["csv-summary"])
+        assert len(session.history) == 2  # tool_use + tool_result appended
+        session._inject_recalled_skills(["csv-summary"])
+        assert len(session.history) == 2  # second preload is a no-op
+
     async def test_thalamus_failure_falls_back_to_planning(self):
         llm = make_mock_llm()
         llm.gate = AsyncMock(side_effect=RuntimeError("thalamus down"))

From 84e31606b626aa242c2906f8f70d5b28464a004c Mon Sep 17 00:00:00 2001
From: Alejandro Cantu <alecantu7@gmail.com>
Date: Wed, 22 Jul 2026 14:30:52 -0700
Subject: [PATCH 24/33] ENG-981: heal lone surrogates before compile() in the
 scratchpad (#268)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(scratchpad): heal lone surrogates before compile() (ENG-981)

The scratchpad child crashes at `compile(code, "<scratchpad>", "exec")` when the
cell source carries a lone surrogate (\udcXX) — a non-ASCII Windows path byte
(e.g. "Área de Trabalho", an emoji filename) surrogate-escaped upstream and
passed through the belt's lenient surrogateescape stdin. compile() strict-encodes
the source and rejects the surrogate ("surrogates not allowed"), killing the cell
before any user code runs. Verified on 3 real desktop users (sabrina/eddie/tim).

This is a distinct site from ENG-824 (GBK decode) and ENG-940 (chat.py read
encoding); neither fixes it, and the ENG-824 belt (PYTHONUTF8) actually *enables*
it (the lenient stdin creates the surrogate; strict compile() then rejects it).

Fix: heal_surrogate_source() in wire.py, called in scratchpad_boot.py right
before compile(). It re-encodes via surrogateescape and decodes as UTF-8, which
*reassembles* the correct character when the surrogates are the byte-escaped
halves of a real multibyte char (the common path case — so the cell compiles AND
opens the right file), and falls back to a replacement-char scrub for a
genuinely-lone surrogate (compile succeeds instead of crashing). No-op on clean
source. Lives in wire.py so both the child and parent can share it.

Also corrects two ENG-940 (#263) tests that overclaimed: _encode_cell_payload's
surrogateescape transport only makes the pipe lossless — it does NOT fix the
compile() crash (that was input-dependent relocation). Relabeled to state they
pin transport fidelity only; the real fix is the heal tested here.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(scratchpad): heal recoverable chars in mixed cells (surrogateescape + replace) — hard-review finding (ENG-981)

Hard review caught a correctness gap in the heal: the recover path used a strict
decode with a full surrogatepass-scrub fallback, so a MIXED cell (a recoverable
byte-escaped path + an unrelated lone byte) raised on the lone byte and fell to
the full scrub — mojibako-ing the recoverable "Área" too.

Use errors="replace" on the surrogateescape decode instead: recoverable
multibyte chars are reassembled and stray bytes scrubbed to U+FFFD in the SAME
pass, so a recoverable path survives next to an unrecoverable byte. The
surrogatepass fallback now only guards the encode-raise (high/unpaired
surrogates outside DC80..DCFF). Still total (never raises), still no residual
surrogate. Adds a mixed-cell regression test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(scratchpad): pre-scrub unmappable surrogates before recover (pnewsam review, ENG-981)

Review caught a real mixed-cell data-loss path I missed: a high/unpaired
surrogate (outside DC80..DCFF, e.g. \ud800) makes the surrogateescape *encode*
raise, so the whole cell fell to the surrogatepass full-scrub — destroying the
recoverable byte-escaped "Á" elsewhere in the same cell (C:/Área -> C:/������rea).
This is the same data-loss class the previous commit fixed for the decode side.

Fix: two steps. (1) Replace surrogates outside the escapable DC80..DCFF range
with U+FFFD up front, so one unmappable surrogate can't drag recoverable ones
into a lossy path. (2) surrogateescape-encode + replace-decode the rest — now it
can never raise, so the try/except is gone entirely. Recoverable DC80..DCFF
byte-escapes survive next to any unmappable surrogate.

Adds test_heal_preserves_recoverable_char_beside_unmappable_surrogate. Also fixes
the stale surrogatepass/framing in the ENG-940 transport-test header comment
(minor, same review).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 anton/core/backends/scratchpad_boot.py |   5 ++
 anton/core/backends/wire.py            |  36 ++++++++
 tests/test_scratchpad_utf8.py          | 110 +++++++++++++++++++------
 3 files changed, 127 insertions(+), 24 deletions(-)

diff --git a/anton/core/backends/scratchpad_boot.py b/anton/core/backends/scratchpad_boot.py
index 4c634dac..a949752b 100644
--- a/anton/core/backends/scratchpad_boot.py
+++ b/anton/core/backends/scratchpad_boot.py
@@ -10,6 +10,7 @@
     CELL_DELIM,
     RESULT_START,
     RESULT_END,
+    heal_surrogate_source,
 )
 
 
@@ -718,6 +719,10 @@ def emit(self, record):
         break
 
     code = "".join(lines)
+    # Heal lone surrogates before compile() — a non-ASCII Windows path byte can
+    # arrive surrogate-escaped over stdin and would crash compile() with
+    # "surrogates not allowed" (ENG-981).
+    code = heal_surrogate_source(code)
     if not code.strip():
         result = {"stdout": "", "stderr": "", "logs": "", "error": None}
         _real_stdout.write(RESULT_START + "\n")
diff --git a/anton/core/backends/wire.py b/anton/core/backends/wire.py
index 46e16e6d..76cfd99b 100644
--- a/anton/core/backends/wire.py
+++ b/anton/core/backends/wire.py
@@ -8,3 +8,39 @@
 RESULT_START = "__ANTON_RESULT__"
 RESULT_END = "__ANTON_RESULT_END__"
 PROGRESS_MARKER = "__ANTON_PROGRESS__"
+
+
+def heal_surrogate_source(code: str) -> str:
+    """Return ``code`` with any lone surrogates resolved to valid UTF-8.
+
+    Cell source can arrive carrying lone surrogates (``\\udcXX``): a non-ASCII
+    Windows path byte (e.g. from ``Área de Trabalho`` or an emoji filename) is
+    surrogate-escaped upstream on a non-UTF-8 host and passed through the
+    scratchpad's lenient ``surrogateescape`` stdin. ``compile()`` strict-encodes
+    the source to UTF-8 and rejects a lone surrogate ("surrogates not allowed"),
+    crashing the cell before any user code runs (ENG-981). UTF-8 mode never
+    makes ``compile()`` lenient, so we must clean the source ourselves.
+
+    Strategy, in two steps so a single unrecoverable surrogate can't take down
+    the recoverable ones elsewhere in the same cell (mixed-cell data loss):
+
+    1. ``surrogateescape`` only maps the ``DC80..DCFF`` byte-escape range. Any
+       *other* surrogate (a high/unpaired one) would make the ``surrogateescape``
+       encode raise and force the whole cell down a lossy path — so replace those
+       up front with U+FFFD.
+    2. Re-encode the rest via ``surrogateescape`` to recover the original bytes,
+       then decode UTF-8 with ``errors="replace"``. Byte-escaped halves of a real
+       multibyte character (the common path case) reassemble exactly — the cell
+       compiles *and* references the correct path — while any leftover stray byte
+       becomes U+FFFD in the same pass. Never raises. A no-op for clean source.
+    """
+    if not any("\ud800" <= ch <= "\udfff" for ch in code):
+        return code
+    # Step 1: scrub surrogates outside the escapable DC80..DCFF range.
+    code = "".join(
+        ch if not ("\ud800" <= ch <= "\udfff") or ("\udc80" <= ch <= "\udcff")
+        else "�"
+        for ch in code
+    )
+    # Step 2: recover DC80..DCFF byte-escapes; replace anything still invalid.
+    return code.encode("utf-8", "surrogateescape").decode("utf-8", "replace")
diff --git a/tests/test_scratchpad_utf8.py b/tests/test_scratchpad_utf8.py
index a3a3e90a..4fba7ba8 100644
--- a/tests/test_scratchpad_utf8.py
+++ b/tests/test_scratchpad_utf8.py
@@ -9,6 +9,7 @@
 import pytest
 
 import anton.core.backends.local as local
+import anton.core.backends.wire as wire
 
 
 def test_utf8_env_forces_utf8_mode():
@@ -143,42 +144,103 @@ def test_chat_module_has_no_bare_read_text():
     assert not bare, f"bare read_text() in anton/chat.py (add encoding='utf-8'): {bare}"
 
 
-# ── ENG-940: the *encode*-side sibling (write path, lone surrogates) ──────────
+# ── ENG-940 transport (NOT the fix): parent→child cell-payload encode ─────────
 #
-# Distinct from the decode crash above: on a non-UTF-8 host, a non-ASCII
-# Windows path (pt-BR "Área de Trabalho", an emoji filename) is surrogate-
-# escaped into lone surrogates (\udcXX) when decoded. When such a string reaches
-# the strict UTF-8 encode of the cell payload it raises "surrogates not allowed"
-# and kills the whole session (users sabrina/eddie/janis). surrogatepass keeps
-# the host-side encode from crashing; the subprocess (UTF-8 mode) decodes it.
-
-def test_cell_payload_encode_survives_lone_surrogate():
-    # A Windows path that os.fsdecode surrogate-escaped on a non-UTF-8 host lands
-    # in the model-written code as lone surrogates (U+DC80..U+DCFF). Model this
-    # exactly and assert the fix.
+# On a non-UTF-8 host a non-ASCII Windows path (pt-BR "Área de Trabalho", an
+# emoji filename) becomes a lone surrogate (\udcXX) in the cell source. This
+# section only pins that _encode_cell_payload uses surrogateescape so the pipe
+# transport is lossless (a surrogatepass encode would re-mangle it). It does NOT
+# fix the crash — the raiser is compile() in the child, healed by
+# heal_surrogate_source (ENG-981), covered in the section below.
+
+def test_cell_payload_encode_is_lossless_over_the_pipe():
+    # NOTE: this pins the *transport* only — that _encode_cell_payload's
+    # surrogateescape encode (parent) round-trips through the subprocess's
+    # surrogateescape stdin decode. It does NOT by itself fix the crash: the real
+    # raiser is compile() in the child on a lone surrogate, healed by
+    # heal_surrogate_source (ENG-981), tested below. (A surrogatepass encode would
+    # fail this round-trip, re-mangling the bytes — that's the only claim here.)
     code = 'open(r"C:\\Users\\\udc81\udc9d\\index.html", "w")  # 🎉\n'
     payload = code + "\n" + local.CELL_DELIM + "\n"
-
-    # A strict UTF-8 encode is the crash the three users hit.
-    with pytest.raises(UnicodeEncodeError):
-        payload.encode("utf-8")
-
-    # The fix: the encode no longer raises, independent of PYTHONUTF8.
     encoded = local._encode_cell_payload(payload)
     assert isinstance(encoded, bytes)
-
-    # The path survives intact end-to-end: the subprocess always runs in UTF-8
-    # mode, so its stdin decodes with surrogateescape. Decoding *that* way (not
-    # surrogatepass) must reproduce the original — this is why the helper uses
-    # surrogateescape. surrogatepass would fail this assertion (re-mangled).
     assert encoded.decode("utf-8", errors="surrogateescape") == payload
 
 
 def test_cell_payload_encode_preserves_accented_and_emoji():
     # Ordinary (well-formed) accented-Latin + emoji content must pass through
-    # byte-for-byte — the fix must not mangle the common case.
+    # byte-for-byte — the transport must not mangle the common case.
     code = 'label = "Área de Trabalho 🎉 café"\nprint(label)\n'
     payload = code + "\n" + local.CELL_DELIM + "\n"
 
     encoded = local._encode_cell_payload(payload)
     assert encoded.decode("utf-8") == payload  # strict decode: no corruption
+
+
+# ── ENG-981: heal lone surrogates before compile() (the real encode-side fix) ──
+#
+# The raiser is compile() in the child on a lone surrogate in the cell source
+# (a non-ASCII Windows path byte, surrogate-escaped upstream and passed through
+# the belt's lenient surrogateescape stdin). compile() is always strict, so the
+# source must be cleaned first. These pin heal_surrogate_source, which the child
+# calls right before compile().
+
+def test_heal_recovers_byte_escaped_multibyte_path():
+    # The common case: a real char whose UTF-8 bytes were escaped byte-wise
+    # upstream (Á = C3 81 -> \udcc3\udc81). Heal must reassemble the *correct*
+    # character so the cell compiles AND references the right path.
+    mangled = 'open(r"C:\\Users\\\udcc3\udc81rea\\f.html")\n'   # "Área" split into surrogates
+    healed = wire.heal_surrogate_source(mangled)
+    assert healed == 'open(r"C:\\Users\\Área\\f.html")\n'
+    compile(healed, "<scratchpad>", "exec")  # no UnicodeEncodeError
+
+
+def test_heal_recovers_escaped_emoji():
+    mangled = 'x = "\udcf0\udc9f\udc8e\udc89"\n'                 # 🎉 = f0 9f 8e 89, escaped
+    healed = wire.heal_surrogate_source(mangled)
+    assert healed == 'x = "🎉"\n'
+    compile(healed, "<scratchpad>", "exec")
+
+
+def test_heal_preserves_recoverable_char_in_mixed_cell():
+    # A recoverable byte-escaped path AND an unrelated lone byte in the same
+    # cell: the recoverable "Área" must survive (only the stray byte is scrubbed)
+    # — a strict-decode-then-full-scrub would mojibake the whole thing.
+    mixed = 'p = r"C:\\\udcc3\udc81rea"  # noqa\nq = "\udc81"\n'
+    healed = wire.heal_surrogate_source(mixed)
+    assert "Área" in healed
+    assert not any("\ud800" <= ch <= "\udfff" for ch in healed)  # no residual
+    compile(healed, "<scratchpad>", "exec")
+
+
+def test_heal_preserves_recoverable_char_beside_unmappable_surrogate():
+    # Mixed-range (pnewsam review): a recoverable byte-escaped "Á" and a
+    # high/unpaired surrogate (\ud800, outside DC80..DCFF) in the same cell. The
+    # unmappable one must be scrubbed WITHOUT dragging the recoverable "Á" into a
+    # full-cell scrub — the surrogateescape encode would otherwise raise on
+    # \ud800 and lose everything.
+    mixed = 'p = r"C:\\\udcc3\udc81rea"\nq = "\ud800"\n'
+    healed = wire.heal_surrogate_source(mixed)
+    assert "Área" in healed
+    assert not any("\ud800" <= ch <= "\udfff" for ch in healed)  # no residual
+    compile(healed, "<scratchpad>", "exec")
+
+
+def test_heal_scrubs_truly_lone_surrogate_so_compile_succeeds():
+    # A genuinely lone surrogate (not a valid byte sequence): can't be recovered,
+    # but must not crash compile() — replaced rather than raised.
+    mangled = 'x = "a\udc81b"\n'
+    healed = wire.heal_surrogate_source(mangled)
+    assert "\udc81" not in healed
+    compile(healed, "<scratchpad>", "exec")  # previously: UnicodeEncodeError
+
+
+def test_heal_is_noop_on_clean_source():
+    clean = 'print("Área de Trabalho 🎉")\n'   # real chars, no surrogates
+    assert wire.heal_surrogate_source(clean) == clean
+
+
+def test_bare_compile_on_lone_surrogate_still_raises():
+    # Guard the premise: without the heal, this is the exact ENG-981 crash.
+    with pytest.raises(UnicodeEncodeError):
+        compile('x = "a\udc81b"\n', "<scratchpad>", "exec")

From 167db922f9816567031f09157a47d9e90fbf1337 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 23 Jul 2026 11:41:55 +0300
Subject: [PATCH 25/33] count gate tokens

---
 anton/core/session.py  | 25 ++++++++++---------------
 tests/test_thalamus.py | 20 ++++++++++++++++++++
 2 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/anton/core/session.py b/anton/core/session.py
index 80a7a3b8..776f9116 100644
--- a/anton/core/session.py
+++ b/anton/core/session.py
@@ -1561,7 +1561,7 @@ async def _gate_turn(self) -> ThalamicDecision | None:
         except Exception:
             summaries = []
         try:
-            decision = await gate_turn(
+            return await gate_turn(
                 self._llm,
                 history=self._history,
                 skill_summaries=summaries,
@@ -1573,18 +1573,6 @@ async def _gate_turn(self) -> ThalamicDecision | None:
                 exc,
             )
             return None
-        # The gate hits every text turn, so its usage must be visible in
-        # telemetry regardless of outcome — StreamComplete only surfaces it
-        # on the direct-answer path, leaving all delegated turns unaccounted.
-        usage = getattr(decision.response, "usage", None)
-        if usage is not None:
-            logger.info(
-                "Router gate: action=%s in_tokens=%s out_tokens=%s",
-                decision.action,
-                getattr(usage, "input_tokens", "?"),
-                getattr(usage, "output_tokens", "?"),
-            )
-        return decision
 
     def _inject_recalled_skills(self, labels: list[str]) -> None:
         """Preload thalamus-named skills as a synthetic recall_skill exchange.
@@ -1905,8 +1893,15 @@ async def turn_stream(
                         or LLMResponse(content=decision.text)
                     )
                     routed_direct = True
-                elif decision is not None and decision.skills:
-                    self._inject_recalled_skills(decision.skills)
+                elif decision is not None:
+                    # Delegating: surface the gate call's usage as its own
+                    # StreamComplete so token accounting counts it, exactly
+                    # like a planning round (the loop below emits more). The
+                    # gate hits every turn, so dropping it would under-report.
+                    if decision.response is not None:
+                        yield StreamComplete(response=decision.response)
+                    if decision.skills:
+                        self._inject_recalled_skills(decision.skills)
 
             while not routed_direct:
                 try:
diff --git a/tests/test_thalamus.py b/tests/test_thalamus.py
index 3755c400..6d7c7359 100644
--- a/tests/test_thalamus.py
+++ b/tests/test_thalamus.py
@@ -308,6 +308,26 @@ async def test_preload_skips_skill_already_in_history(self):
         session._inject_recalled_skills(["csv-summary"])
         assert len(session.history) == 2  # second preload is a no-op
 
+    async def test_gate_usage_counted_on_delegate_streaming(self):
+        # The gate hits every text turn; on delegate its usage must reach the
+        # consumer as its own StreamComplete (like a planning round), or token
+        # counters that sum StreamComplete usage under-report every gate call.
+        llm = make_mock_llm()
+        llm.gate = AsyncMock(return_value=_response(tool_calls=[_delegate_call()]))
+
+        async def _plan_stream(**kwargs):
+            yield StreamTextDelta(text="Working on it.")
+            yield StreamComplete(response=_response("Working on it."))
+
+        llm.plan_stream = _plan_stream
+        session = ChatSession(ChatSessionConfig(llm_client=llm, router_enabled=True))
+        events = [e async for e in session.turn_stream("analyze data.csv")]
+        completes = [e for e in events if isinstance(e, StreamComplete)]
+        # two calls billed: the gate, then the planning round
+        assert len(completes) == 2
+        total_in = sum(e.response.usage.input_tokens for e in completes)
+        assert total_in == 20  # 10 (gate) + 10 (planning)
+
     async def test_thalamus_failure_falls_back_to_planning(self):
         llm = make_mock_llm()
         llm.gate = AsyncMock(side_effect=RuntimeError("thalamus down"))

From 25d73558d88d7a062d348f6a0a535bbc46086fc9 Mon Sep 17 00:00:00 2001
From: andrew <elkin.andr@gmail.com>
Date: Thu, 23 Jul 2026 11:59:18 +0300
Subject: [PATCH 26/33] max_chars works also for messages of the same role
 which go subsequently

---
 anton/core/llm/thalamus.py | 38 +++++++++++++++++++++++++++++---------
 tests/test_thalamus.py     | 12 ++++++++++++
 2 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/anton/core/llm/thalamus.py b/anton/core/llm/thalamus.py
index c1c90e7c..b4cb9b61 100644
--- a/anton/core/llm/thalamus.py
+++ b/anton/core/llm/thalamus.py
@@ -180,6 +180,22 @@ def build_thalamus_system_prompt(
     return _THALAMUS_SYSTEM_PROMPT.format(skills_section=skills_section)
 
 
+_TRUNCATION_MARKER = "\n[… truncated …]\n"
+
+
+def _truncate_middle(text: str, max_chars: int) -> str:
+    """Middle-truncate ``text`` to at most ``max_chars``, keeping head and tail.
+
+    The result (including the marker) never exceeds ``max_chars`` — the
+    marker length is subtracted from the head/tail budget — so callers can
+    rely on a hard per-entry cap.
+    """
+    if len(text) <= max_chars:
+        return text
+    half = max(0, (max_chars - len(_TRUNCATION_MARKER)) // 2)
+    return f"{text[:half]}{_TRUNCATION_MARKER}{text[-half:]}"
+
+
 def condense_history(
     history: list[dict],
     *,
@@ -188,12 +204,15 @@ def condense_history(
 ) -> list[dict]:
     """Build the thalamus's text-only view of the conversation.
 
-    Tool blocks collapse to one-line markers (the gate only needs to
-    know work happened, not its payload), long messages are middle-
-    truncated, and consecutive same-role messages merge so the result
-    keeps the role alternation providers require. Only the most recent
-    ``max_messages`` survive, and a leading assistant message left over
-    from the cut is dropped so the list starts with a user message.
+    Tool blocks collapse to one-line markers (the gate only needs to know
+    work happened, not its payload), and consecutive same-role messages
+    merge so the result keeps the role alternation providers require. Only
+    the most recent ``max_messages`` survive, and a leading assistant
+    message left over from the cut is dropped so the list starts with a
+    user message. Each surviving entry is then middle-truncated to
+    ``max_chars`` — applied AFTER the merge so a merged block can't exceed
+    the cap. The whole view is therefore bounded by
+    ``max_messages * max_chars``.
     """
     condensed: list[dict] = []
     for msg in history:
@@ -223,9 +242,6 @@ def condense_history(
         text = text.strip()
         if not text:
             continue
-        if len(text) > max_chars:
-            half = max_chars // 2
-            text = f"{text[:half]}\n[… truncated …]\n{text[-half:]}"
         if condensed and condensed[-1]["role"] == role:
             condensed[-1]["content"] += "\n" + text
         else:
@@ -234,6 +250,10 @@ def condense_history(
     condensed = condensed[-max_messages:]
     while condensed and condensed[0]["role"] != "user":
         condensed.pop(0)
+    # Truncate AFTER merge: each surviving (possibly merged) entry is capped
+    # here, so the per-entry cap holds no matter how many messages merged.
+    for msg in condensed:
+        msg["content"] = _truncate_middle(msg["content"], max_chars)
     return condensed
 
 
diff --git a/tests/test_thalamus.py b/tests/test_thalamus.py
index 6d7c7359..0c03025d 100644
--- a/tests/test_thalamus.py
+++ b/tests/test_thalamus.py
@@ -101,6 +101,18 @@ def test_empty_and_nontext_history(self):
         assert condense_history([]) == []
         assert condense_history([{"role": "system", "content": "x"}]) == []
 
+    def test_merged_block_respects_max_chars_cap(self):
+        # Point 3: truncation runs AFTER merge, so a block merged from several
+        # near-cap same-role messages still honours the per-entry cap (before
+        # the fix each piece was capped but the merged sum blew past it).
+        history = [{"role": "user", "content": "x" * 1000} for _ in range(5)]
+        max_chars = 200
+        condensed = condense_history(history, max_chars=max_chars)
+        assert len(condensed) == 1  # all merged into one user block
+        assert len(condensed[0]["content"]) <= max_chars
+        # and the whole view is bounded by max_messages * max_chars
+        assert all(len(m["content"]) <= max_chars for m in condensed)
+
 
 class TestGateTurn:
     async def test_direct_answer(self):

From bd87572b310a8e8243e5edc16beba2b207eccdc6 Mon Sep 17 00:00:00 2001
From: martyna-mindsdb <martyna@mindsdb.com>
Date: Thu, 23 Jul 2026 12:28:16 +0200
Subject: [PATCH 27/33] fix for eng-845

---
 anton/core/datasources/data_vault.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/anton/core/datasources/data_vault.py b/anton/core/datasources/data_vault.py
index c2358b21..11acc718 100644
--- a/anton/core/datasources/data_vault.py
+++ b/anton/core/datasources/data_vault.py
@@ -235,7 +235,7 @@ def save(
         tmp = path.with_suffix(".tmp")
         tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
         tmp.chmod(0o600)
-        tmp.rename(path)
+        tmp.replace(path)
         return path
 
     def load(self, engine: str, name: str) -> dict[str, str] | None:

From d61470fca300e555ff47904f533b3d9b6324b683 Mon Sep 17 00:00:00 2001
From: martyna-mindsdb <martyna@mindsdb.com>
Date: Thu, 23 Jul 2026 14:28:31 +0200
Subject: [PATCH 28/33] fix: pillow vulnerability

---
 pyproject.toml |   2 +-
 uv.lock        | 162 ++++++++++++++++++++++++-------------------------
 2 files changed, 81 insertions(+), 83 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 49dcb0cb..4901fe87 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,7 +38,7 @@ dev = [
     "pytest-asyncio>=0.24",
 ]
 clipboard = [
-    "Pillow>=12.2.0",
+    "Pillow>=12.3.0",
 ]
 
 [project.urls]
diff --git a/uv.lock b/uv.lock
index e23502f3..c36083b7 100644
--- a/uv.lock
+++ b/uv.lock
@@ -196,7 +196,7 @@ requires-dist = [
     { name = "dill", specifier = "==0.3.8" },
     { name = "openai", specifier = ">=1.0" },
     { name = "packaging", specifier = ">=21.0" },
-    { name = "pillow", marker = "extra == 'clipboard'", specifier = ">=12.2.0" },
+    { name = "pillow", marker = "extra == 'clipboard'", specifier = ">=12.3.0" },
     { name = "prompt-toolkit", specifier = ">=3.0" },
     { name = "pydantic", specifier = ">=2.0" },
     { name = "pydantic-settings", specifier = ">=2.0" },
@@ -700,89 +700,87 @@ wheels = [
 
 [[package]]
 name = "pillow"
-version = "12.2.0"
+version = "12.3.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/8c/21/c2bcdd5906101a30244eaffc1b6e6ce71a31bd0742a01eb89e660ebfac2d/pillow-12.2.0.tar.gz", hash = "sha256:a830b1a40919539d07806aa58e1b114df53ddd43213d9c8b75847eee6c0182b5", size = 46987819, upload-time = "2026-04-01T14:46:17.687Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1c/3d/bb7fca845737cf9d7dbde16ed1843984665ff2e0a518f5db43e77ec540b9/pillow-12.3.0.tar.gz", hash = "sha256:3b8182a766685eaa002637e28b4ec8d6b18819a0c71f579bf0dbaa5830297cce", size = 47025035, upload-time = "2026-07-01T11:56:38.965Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/68/e1/748f5663efe6edcfc4e74b2b93edfb9b8b99b67f21a854c3ae416500a2d9/pillow-12.2.0-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:8be29e59487a79f173507c30ddf57e733a357f67881430449bb32614075a40ab", size = 5354347, upload-time = "2026-04-01T14:42:44.255Z" },
-    { url = "https://files.pythonhosted.org/packages/47/a1/d5ff69e747374c33a3b53b9f98cca7889fce1fd03d79cdc4e1bccc6c5a87/pillow-12.2.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:71cde9a1e1551df7d34a25462fc60325e8a11a82cc2e2f54578e5e9a1e153d65", size = 4695873, upload-time = "2026-04-01T14:42:46.452Z" },
-    { url = "https://files.pythonhosted.org/packages/df/21/e3fbdf54408a973c7f7f89a23b2cb97a7ef30c61ab4142af31eee6aebc88/pillow-12.2.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f490f9368b6fc026f021db16d7ec2fbf7d89e2edb42e8ec09d2c60505f5729c7", size = 6280168, upload-time = "2026-04-01T14:42:49.228Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/f1/00b7278c7dd52b17ad4329153748f87b6756ec195ff786c2bdf12518337d/pillow-12.2.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8bd7903a5f2a4545f6fd5935c90058b89d30045568985a71c79f5fd6edf9b91e", size = 8088188, upload-time = "2026-04-01T14:42:51.735Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/cf/220a5994ef1b10e70e85748b75649d77d506499352be135a4989c957b701/pillow-12.2.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3997232e10d2920a68d25191392e3a4487d8183039e1c74c2297f00ed1c50705", size = 6394401, upload-time = "2026-04-01T14:42:54.343Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/bd/e51a61b1054f09437acfbc2ff9106c30d1eb76bc1453d428399946781253/pillow-12.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e74473c875d78b8e9d5da2a70f7099549f9eb37ded4e2f6a463e60125bccd176", size = 7079655, upload-time = "2026-04-01T14:42:56.954Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/3d/45132c57d5fb4b5744567c3817026480ac7fc3ce5d4c47902bc0e7f6f853/pillow-12.2.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:56a3f9c60a13133a98ecff6197af34d7824de9b7b38c3654861a725c970c197b", size = 6503105, upload-time = "2026-04-01T14:42:59.847Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/2e/9df2fc1e82097b1df3dce58dc43286aa01068e918c07574711fcc53e6fb4/pillow-12.2.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:90e6f81de50ad6b534cab6e5aef77ff6e37722b2f5d908686f4a5c9eba17a909", size = 7203402, upload-time = "2026-04-01T14:43:02.664Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/2e/2941e42858ebb67e50ae741473de81c2984e6eff7b397017623c676e2e8d/pillow-12.2.0-cp311-cp311-win32.whl", hash = "sha256:8c984051042858021a54926eb597d6ee3012393ce9c181814115df4c60b9a808", size = 6378149, upload-time = "2026-04-01T14:43:05.274Z" },
-    { url = "https://files.pythonhosted.org/packages/69/42/836b6f3cd7f3e5fa10a1f1a5420447c17966044c8fbf589cc0452d5502db/pillow-12.2.0-cp311-cp311-win_amd64.whl", hash = "sha256:6e6b2a0c538fc200b38ff9eb6628228b77908c319a005815f2dde585a0664b60", size = 7082626, upload-time = "2026-04-01T14:43:08.557Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/88/549194b5d6f1f494b485e493edc6693c0a16f4ada488e5bd974ed1f42fad/pillow-12.2.0-cp311-cp311-win_arm64.whl", hash = "sha256:9a8a34cc89c67a65ea7437ce257cea81a9dad65b29805f3ecee8c8fe8ff25ffe", size = 2463531, upload-time = "2026-04-01T14:43:10.743Z" },
-    { url = "https://files.pythonhosted.org/packages/58/be/7482c8a5ebebbc6470b3eb791812fff7d5e0216c2be3827b30b8bb6603ed/pillow-12.2.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2d192a155bbcec180f8564f693e6fd9bccff5a7af9b32e2e4bf8c9c69dbad6b5", size = 5308279, upload-time = "2026-04-01T14:43:13.246Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/95/0a351b9289c2b5cbde0bacd4a83ebc44023e835490a727b2a3bd60ddc0f4/pillow-12.2.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f3f40b3c5a968281fd507d519e444c35f0ff171237f4fdde090dd60699458421", size = 4695490, upload-time = "2026-04-01T14:43:15.584Z" },
-    { url = "https://files.pythonhosted.org/packages/de/af/4e8e6869cbed569d43c416fad3dc4ecb944cb5d9492defaed89ddd6fe871/pillow-12.2.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:03e7e372d5240cc23e9f07deca4d775c0817bffc641b01e9c3af208dbd300987", size = 6284462, upload-time = "2026-04-01T14:43:18.268Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/9e/c05e19657fd57841e476be1ab46c4d501bffbadbafdc31a6d665f8b737b6/pillow-12.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:b86024e52a1b269467a802258c25521e6d742349d760728092e1bc2d135b4d76", size = 8094744, upload-time = "2026-04-01T14:43:20.716Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/54/1789c455ed10176066b6e7e6da1b01e50e36f94ba584dc68d9eebfe9156d/pillow-12.2.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7371b48c4fa448d20d2714c9a1f775a81155050d383333e0a6c15b1123dda005", size = 6398371, upload-time = "2026-04-01T14:43:23.443Z" },
-    { url = "https://files.pythonhosted.org/packages/43/e3/fdc657359e919462369869f1c9f0e973f353f9a9ee295a39b1fea8ee1a77/pillow-12.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:62f5409336adb0663b7caa0da5c7d9e7bdbaae9ce761d34669420c2a801b2780", size = 7087215, upload-time = "2026-04-01T14:43:26.758Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/f8/2f6825e441d5b1959d2ca5adec984210f1ec086435b0ed5f52c19b3b8a6e/pillow-12.2.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:01afa7cf67f74f09523699b4e88c73fb55c13346d212a59a2db1f86b0a63e8c5", size = 6509783, upload-time = "2026-04-01T14:43:29.56Z" },
-    { url = "https://files.pythonhosted.org/packages/67/f9/029a27095ad20f854f9dba026b3ea6428548316e057e6fc3545409e86651/pillow-12.2.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fc3d34d4a8fbec3e88a79b92e5465e0f9b842b628675850d860b8bd300b159f5", size = 7212112, upload-time = "2026-04-01T14:43:32.091Z" },
-    { url = "https://files.pythonhosted.org/packages/be/42/025cfe05d1be22dbfdb4f264fe9de1ccda83f66e4fc3aac94748e784af04/pillow-12.2.0-cp312-cp312-win32.whl", hash = "sha256:58f62cc0f00fd29e64b29f4fd923ffdb3859c9f9e6105bfc37ba1d08994e8940", size = 6378489, upload-time = "2026-04-01T14:43:34.601Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/7b/25a221d2c761c6a8ae21bfa3874988ff2583e19cf8a27bf2fee358df7942/pillow-12.2.0-cp312-cp312-win_amd64.whl", hash = "sha256:7f84204dee22a783350679a0333981df803dac21a0190d706a50475e361c93f5", size = 7084129, upload-time = "2026-04-01T14:43:37.213Z" },
-    { url = "https://files.pythonhosted.org/packages/10/e1/542a474affab20fd4a0f1836cb234e8493519da6b76899e30bcc5d990b8b/pillow-12.2.0-cp312-cp312-win_arm64.whl", hash = "sha256:af73337013e0b3b46f175e79492d96845b16126ddf79c438d7ea7ff27783a414", size = 2463612, upload-time = "2026-04-01T14:43:39.421Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/01/53d10cf0dbad820a8db274d259a37ba50b88b24768ddccec07355382d5ad/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:8297651f5b5679c19968abefd6bb84d95fe30ef712eb1b2d9b2d31ca61267f4c", size = 4100837, upload-time = "2026-04-01T14:43:41.506Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/98/f3a6657ecb698c937f6c76ee564882945f29b79bad496abcba0e84659ec5/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:50d8520da2a6ce0af445fa6d648c4273c3eeefbc32d7ce049f22e8b5c3daecc2", size = 4176528, upload-time = "2026-04-01T14:43:43.773Z" },
-    { url = "https://files.pythonhosted.org/packages/69/bc/8986948f05e3ea490b8442ea1c1d4d990b24a7e43d8a51b2c7d8b1dced36/pillow-12.2.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:766cef22385fa1091258ad7e6216792b156dc16d8d3fa607e7545b2b72061f1c", size = 3640401, upload-time = "2026-04-01T14:43:45.87Z" },
-    { url = "https://files.pythonhosted.org/packages/34/46/6c717baadcd62bc8ed51d238d521ab651eaa74838291bda1f86fe1f864c9/pillow-12.2.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5d2fd0fa6b5d9d1de415060363433f28da8b1526c1c129020435e186794b3795", size = 5308094, upload-time = "2026-04-01T14:43:48.438Z" },
-    { url = "https://files.pythonhosted.org/packages/71/43/905a14a8b17fdb1ccb58d282454490662d2cb89a6bfec26af6d3520da5ec/pillow-12.2.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:56b25336f502b6ed02e889f4ece894a72612fe885889a6e8c4c80239ff6e5f5f", size = 4695402, upload-time = "2026-04-01T14:43:51.292Z" },
-    { url = "https://files.pythonhosted.org/packages/73/dd/42107efcb777b16fa0393317eac58f5b5cf30e8392e266e76e51cff28c3d/pillow-12.2.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f1c943e96e85df3d3478f7b691f229887e143f81fedab9b20205349ab04d73ed", size = 6280005, upload-time = "2026-04-01T14:43:54.242Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/68/b93e09e5e8549019e61acf49f65b1a8530765a7f812c77a7461bca7e4494/pillow-12.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:03f6fab9219220f041c74aeaa2939ff0062bd5c364ba9ce037197f4c6d498cd9", size = 8090669, upload-time = "2026-04-01T14:43:57.335Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/6e/3ccb54ce8ec4ddd1accd2d89004308b7b0b21c4ac3d20fa70af4760a4330/pillow-12.2.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5cdfebd752ec52bf5bb4e35d9c64b40826bc5b40a13df7c3cda20a2c03a0f5ed", size = 6395194, upload-time = "2026-04-01T14:43:59.864Z" },
-    { url = "https://files.pythonhosted.org/packages/67/ee/21d4e8536afd1a328f01b359b4d3997b291ffd35a237c877b331c1c3b71c/pillow-12.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eedf4b74eda2b5a4b2b2fb4c006d6295df3bf29e459e198c90ea48e130dc75c3", size = 7082423, upload-time = "2026-04-01T14:44:02.74Z" },
-    { url = "https://files.pythonhosted.org/packages/78/5f/e9f86ab0146464e8c133fe85df987ed9e77e08b29d8d35f9f9f4d6f917ba/pillow-12.2.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:00a2865911330191c0b818c59103b58a5e697cae67042366970a6b6f1b20b7f9", size = 6505667, upload-time = "2026-04-01T14:44:05.381Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/1e/409007f56a2fdce61584fd3acbc2bbc259857d555196cedcadc68c015c82/pillow-12.2.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1e1757442ed87f4912397c6d35a0db6a7b52592156014706f17658ff58bbf795", size = 7208580, upload-time = "2026-04-01T14:44:08.39Z" },
-    { url = "https://files.pythonhosted.org/packages/23/c4/7349421080b12fb35414607b8871e9534546c128a11965fd4a7002ccfbee/pillow-12.2.0-cp313-cp313-win32.whl", hash = "sha256:144748b3af2d1b358d41286056d0003f47cb339b8c43a9ea42f5fea4d8c66b6e", size = 6375896, upload-time = "2026-04-01T14:44:11.197Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/82/8a3739a5e470b3c6cbb1d21d315800d8e16bff503d1f16b03a4ec3212786/pillow-12.2.0-cp313-cp313-win_amd64.whl", hash = "sha256:390ede346628ccc626e5730107cde16c42d3836b89662a115a921f28440e6a3b", size = 7081266, upload-time = "2026-04-01T14:44:13.947Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/25/f968f618a062574294592f668218f8af564830ccebdd1fa6200f598e65c5/pillow-12.2.0-cp313-cp313-win_arm64.whl", hash = "sha256:8023abc91fba39036dbce14a7d6535632f99c0b857807cbbbf21ecc9f4717f06", size = 2463508, upload-time = "2026-04-01T14:44:16.312Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/a4/b342930964e3cb4dce5038ae34b0eab4653334995336cd486c5a8c25a00c/pillow-12.2.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:042db20a421b9bafecc4b84a8b6e444686bd9d836c7fd24542db3e7df7baad9b", size = 5309927, upload-time = "2026-04-01T14:44:18.89Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/de/23198e0a65a9cf06123f5435a5d95cea62a635697f8f03d134d3f3a96151/pillow-12.2.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:dd025009355c926a84a612fecf58bb315a3f6814b17ead51a8e48d3823d9087f", size = 4698624, upload-time = "2026-04-01T14:44:21.115Z" },
-    { url = "https://files.pythonhosted.org/packages/01/a6/1265e977f17d93ea37aa28aa81bad4fa597933879fac2520d24e021c8da3/pillow-12.2.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:88ddbc66737e277852913bd1e07c150cc7bb124539f94c4e2df5344494e0a612", size = 6321252, upload-time = "2026-04-01T14:44:23.663Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/83/5982eb4a285967baa70340320be9f88e57665a387e3a53a7f0db8231a0cd/pillow-12.2.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d362d1878f00c142b7e1a16e6e5e780f02be8195123f164edf7eddd911eefe7c", size = 8126550, upload-time = "2026-04-01T14:44:26.772Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/48/6ffc514adce69f6050d0753b1a18fd920fce8cac87620d5a31231b04bfc5/pillow-12.2.0-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c727a6d53cb0018aadd8018c2b938376af27914a68a492f59dfcaca650d5eea", size = 6433114, upload-time = "2026-04-01T14:44:29.615Z" },
-    { url = "https://files.pythonhosted.org/packages/36/a3/f9a77144231fb8d40ee27107b4463e205fa4677e2ca2548e14da5cf18dce/pillow-12.2.0-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:efd8c21c98c5cc60653bcb311bef2ce0401642b7ce9d09e03a7da87c878289d4", size = 7115667, upload-time = "2026-04-01T14:44:32.773Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/fc/ac4ee3041e7d5a565e1c4fd72a113f03b6394cc72ab7089d27608f8aaccb/pillow-12.2.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9f08483a632889536b8139663db60f6724bfcb443c96f1b18855860d7d5c0fd4", size = 6538966, upload-time = "2026-04-01T14:44:35.252Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/a8/27fb307055087f3668f6d0a8ccb636e7431d56ed0750e07a60547b1e083e/pillow-12.2.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:dac8d77255a37e81a2efcbd1fc05f1c15ee82200e6c240d7e127e25e365c39ea", size = 7238241, upload-time = "2026-04-01T14:44:37.875Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/4b/926ab182c07fccae9fcb120043464e1ff1564775ec8864f21a0ebce6ac25/pillow-12.2.0-cp313-cp313t-win32.whl", hash = "sha256:ee3120ae9dff32f121610bb08e4313be87e03efeadfc6c0d18f89127e24d0c24", size = 6379592, upload-time = "2026-04-01T14:44:40.336Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/c4/f9e476451a098181b30050cc4c9a3556b64c02cf6497ea421ac047e89e4b/pillow-12.2.0-cp313-cp313t-win_amd64.whl", hash = "sha256:325ca0528c6788d2a6c3d40e3568639398137346c3d6e66bb61db96b96511c98", size = 7085542, upload-time = "2026-04-01T14:44:43.251Z" },
-    { url = "https://files.pythonhosted.org/packages/00/a4/285f12aeacbe2d6dc36c407dfbbe9e96d4a80b0fb710a337f6d2ad978c75/pillow-12.2.0-cp313-cp313t-win_arm64.whl", hash = "sha256:2e5a76d03a6c6dcef67edabda7a52494afa4035021a79c8558e14af25313d453", size = 2465765, upload-time = "2026-04-01T14:44:45.996Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/98/4595daa2365416a86cb0d495248a393dfc84e96d62ad080c8546256cb9c0/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:3adc9215e8be0448ed6e814966ecf3d9952f0ea40eb14e89a102b87f450660d8", size = 4100848, upload-time = "2026-04-01T14:44:48.48Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/79/40184d464cf89f6663e18dfcf7ca21aae2491fff1a16127681bf1fa9b8cf/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:6a9adfc6d24b10f89588096364cc726174118c62130c817c2837c60cf08a392b", size = 4176515, upload-time = "2026-04-01T14:44:51.353Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/63/703f86fd4c422a9cf722833670f4f71418fb116b2853ff7da722ea43f184/pillow-12.2.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:6a6e67ea2e6feda684ed370f9a1c52e7a243631c025ba42149a2cc5934dec295", size = 3640159, upload-time = "2026-04-01T14:44:53.588Z" },
-    { url = "https://files.pythonhosted.org/packages/71/e0/fb22f797187d0be2270f83500aab851536101b254bfa1eae10795709d283/pillow-12.2.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2bb4a8d594eacdfc59d9e5ad972aa8afdd48d584ffd5f13a937a664c3e7db0ed", size = 5312185, upload-time = "2026-04-01T14:44:56.039Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/8c/1a9e46228571de18f8e28f16fabdfc20212a5d019f3e3303452b3f0a580d/pillow-12.2.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:80b2da48193b2f33ed0c32c38140f9d3186583ce7d516526d462645fd98660ae", size = 4695386, upload-time = "2026-04-01T14:44:58.663Z" },
-    { url = "https://files.pythonhosted.org/packages/70/62/98f6b7f0c88b9addd0e87c217ded307b36be024d4ff8869a812b241d1345/pillow-12.2.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:22db17c68434de69d8ecfc2fe821569195c0c373b25cccb9cbdacf2c6e53c601", size = 6280384, upload-time = "2026-04-01T14:45:01.5Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/03/688747d2e91cfbe0e64f316cd2e8005698f76ada3130d0194664174fa5de/pillow-12.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7b14cc0106cd9aecda615dd6903840a058b4700fcb817687d0ee4fc8b6e389be", size = 8091599, upload-time = "2026-04-01T14:45:04.5Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/35/577e22b936fcdd66537329b33af0b4ccfefaeabd8aec04b266528cddb33c/pillow-12.2.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8cbeb542b2ebc6fcdacabf8aca8c1a97c9b3ad3927d46b8723f9d4f033288a0f", size = 6396021, upload-time = "2026-04-01T14:45:07.117Z" },
-    { url = "https://files.pythonhosted.org/packages/11/8d/d2532ad2a603ca2b93ad9f5135732124e57811d0168155852f37fbce2458/pillow-12.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4bfd07bc812fbd20395212969e41931001fd59eb55a60658b0e5710872e95286", size = 7083360, upload-time = "2026-04-01T14:45:09.763Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/26/d325f9f56c7e039034897e7380e9cc202b1e368bfd04d4cbe6a441f02885/pillow-12.2.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9aba9a17b623ef750a4d11b742cbafffeb48a869821252b30ee21b5e91392c50", size = 6507628, upload-time = "2026-04-01T14:45:12.378Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/f7/769d5632ffb0988f1c5e7660b3e731e30f7f8ec4318e94d0a5d674eb65a4/pillow-12.2.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:deede7c263feb25dba4e82ea23058a235dcc2fe1f6021025dc71f2b618e26104", size = 7209321, upload-time = "2026-04-01T14:45:15.122Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/7a/c253e3c645cd47f1aceea6a8bacdba9991bf45bb7dfe927f7c893e89c93c/pillow-12.2.0-cp314-cp314-win32.whl", hash = "sha256:632ff19b2778e43162304d50da0181ce24ac5bb8180122cbe1bf4673428328c7", size = 6479723, upload-time = "2026-04-01T14:45:17.797Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/8b/601e6566b957ca50e28725cb6c355c59c2c8609751efbecd980db44e0349/pillow-12.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:4e6c62e9d237e9b65fac06857d511e90d8461a32adcc1b9065ea0c0fa3a28150", size = 7217400, upload-time = "2026-04-01T14:45:20.529Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/94/220e46c73065c3e2951bb91c11a1fb636c8c9ad427ac3ce7d7f3359b9b2f/pillow-12.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:b1c1fbd8a5a1af3412a0810d060a78b5136ec0836c8a4ef9aa11807f2a22f4e1", size = 2554835, upload-time = "2026-04-01T14:45:23.162Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/ab/1b426a3974cb0e7da5c29ccff4807871d48110933a57207b5a676cccc155/pillow-12.2.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:57850958fe9c751670e49b2cecf6294acc99e562531f4bd317fa5ddee2068463", size = 5314225, upload-time = "2026-04-01T14:45:25.637Z" },
-    { url = "https://files.pythonhosted.org/packages/19/1e/dce46f371be2438eecfee2a1960ee2a243bbe5e961890146d2dee1ff0f12/pillow-12.2.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d5d38f1411c0ed9f97bcb49b7bd59b6b7c314e0e27420e34d99d844b9ce3b6f3", size = 4698541, upload-time = "2026-04-01T14:45:28.355Z" },
-    { url = "https://files.pythonhosted.org/packages/55/c3/7fbecf70adb3a0c33b77a300dc52e424dc22ad8cdc06557a2e49523b703d/pillow-12.2.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5c0a9f29ca8e79f09de89293f82fc9b0270bb4af1d58bc98f540cc4aedf03166", size = 6322251, upload-time = "2026-04-01T14:45:30.924Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/3c/7fbc17cfb7e4fe0ef1642e0abc17fc6c94c9f7a16be41498e12e2ba60408/pillow-12.2.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1610dd6c61621ae1cf811bef44d77e149ce3f7b95afe66a4512f8c59f25d9ebe", size = 8127807, upload-time = "2026-04-01T14:45:33.908Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/c3/a8ae14d6defd2e448493ff512fae903b1e9bd40b72efb6ec55ce0048c8ce/pillow-12.2.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0a34329707af4f73cf1782a36cd2289c0368880654a2c11f027bcee9052d35dd", size = 6433935, upload-time = "2026-04-01T14:45:36.623Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/32/2880fb3a074847ac159d8f902cb43278a61e85f681661e7419e6596803ed/pillow-12.2.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8e9c4f5b3c546fa3458a29ab22646c1c6c787ea8f5ef51300e5a60300736905e", size = 7116720, upload-time = "2026-04-01T14:45:39.258Z" },
-    { url = "https://files.pythonhosted.org/packages/46/87/495cc9c30e0129501643f24d320076f4cc54f718341df18cc70ec94c44e1/pillow-12.2.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fb043ee2f06b41473269765c2feae53fc2e2fbf96e5e22ca94fb5ad677856f06", size = 6540498, upload-time = "2026-04-01T14:45:41.879Z" },
-    { url = "https://files.pythonhosted.org/packages/18/53/773f5edca692009d883a72211b60fdaf8871cbef075eaa9d577f0a2f989e/pillow-12.2.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f278f034eb75b4e8a13a54a876cc4a5ab39173d2cdd93a638e1b467fc545ac43", size = 7239413, upload-time = "2026-04-01T14:45:44.705Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/e4/4b64a97d71b2a83158134abbb2f5bd3f8a2ea691361282f010998f339ec7/pillow-12.2.0-cp314-cp314t-win32.whl", hash = "sha256:6bb77b2dcb06b20f9f4b4a8454caa581cd4dd0643a08bacf821216a16d9c8354", size = 6482084, upload-time = "2026-04-01T14:45:47.568Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/13/306d275efd3a3453f72114b7431c877d10b1154014c1ebbedd067770d629/pillow-12.2.0-cp314-cp314t-win_amd64.whl", hash = "sha256:6562ace0d3fb5f20ed7290f1f929cae41b25ae29528f2af1722966a0a02e2aa1", size = 7225152, upload-time = "2026-04-01T14:45:50.032Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/6e/cf826fae916b8658848d7b9f38d88da6396895c676e8086fc0988073aaf8/pillow-12.2.0-cp314-cp314t-win_arm64.whl", hash = "sha256:aa88ccfe4e32d362816319ed727a004423aab09c5cea43c01a4b435643fa34eb", size = 2556579, upload-time = "2026-04-01T14:45:52.529Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/b7/2437044fb910f499610356d1352e3423753c98e34f915252aafecc64889f/pillow-12.2.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:0538bd5e05efec03ae613fd89c4ce0368ecd2ba239cc25b9f9be7ed426b0af1f", size = 5273969, upload-time = "2026-04-01T14:45:55.538Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/f4/8316e31de11b780f4ac08ef3654a75555e624a98db1056ecb2122d008d5a/pillow-12.2.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:394167b21da716608eac917c60aa9b969421b5dcbbe02ae7f013e7b85811c69d", size = 4659674, upload-time = "2026-04-01T14:45:58.093Z" },
-    { url = "https://files.pythonhosted.org/packages/d4/37/664fca7201f8bb2aa1d20e2c3d5564a62e6ae5111741966c8319ca802361/pillow-12.2.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5d04bfa02cc2d23b497d1e90a0f927070043f6cbf303e738300532379a4b4e0f", size = 5288479, upload-time = "2026-04-01T14:46:01.141Z" },
-    { url = "https://files.pythonhosted.org/packages/49/62/5b0ed78fce87346be7a5cfcfaaad91f6a1f98c26f86bdbafa2066c647ef6/pillow-12.2.0-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0c838a5125cee37e68edec915651521191cef1e6aa336b855f495766e77a366e", size = 7032230, upload-time = "2026-04-01T14:46:03.874Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/28/ec0fc38107fc32536908034e990c47914c57cd7c5a3ece4d8d8f7ffd7e27/pillow-12.2.0-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4a6c9fa44005fa37a91ebfc95d081e8079757d2e904b27103f4f5fa6f0bf78c0", size = 5355404, upload-time = "2026-04-01T14:46:06.33Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/8b/51b0eddcfa2180d60e41f06bd6d0a62202b20b59c68f5a132e615b75aecf/pillow-12.2.0-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:25373b66e0dd5905ed63fa3cae13c82fbddf3079f2c8bf15c6fb6a35586324c1", size = 6002215, upload-time = "2026-04-01T14:46:08.83Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/60/5382c03e1970de634027cee8e1b7d39776b778b81812aaf45b694dfe9e28/pillow-12.2.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:bfa9c230d2fe991bed5318a5f119bd6780cda2915cca595393649fc118ab895e", size = 7080946, upload-time = "2026-04-01T14:46:11.734Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/c8/0a78b0e02d7ac54bc03e5321c9220da52f0c2ea83b21f7c40e7f3169c502/pillow-12.3.0-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:00808c5e14ef63ac5161091d242999076604ff74b883423a11e5d7bbb38bf756", size = 5392415, upload-time = "2026-07-01T11:53:47.162Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/5b/a02d30018abd97ced9f5a6c63d28597694a00d066516b9c1c6de45859fc9/pillow-12.3.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:37d6d0a00072fd2948eb22bce7e1475f34569d90c87c59f7a2ec59541b77f7a6", size = 4785266, upload-time = "2026-07-01T11:53:49.079Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/98/766667a4be768150a202836acd9fad19c06824ca86c4286d3cf6b274964e/pillow-12.3.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:bcb46e2f9feff8d06323983bd83ed00c201fdcab3d74973e7072a889b3979fcd", size = 6263814, upload-time = "2026-07-01T11:53:51.32Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/2d/ede717bc1144f63886c21fd349bb95860b0d1a21149ff16f2bb362b612b6/pillow-12.3.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:23d27a3e0307ec2244cc51e7287b919aa68d097504ebe19df4e76a98a3eea5bd", size = 6934408, upload-time = "2026-07-01T11:53:53.487Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/48/9c58b685e69d49c31af6c8eb9012055fab7e665785165c84796e2c73ce72/pillow-12.3.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:4f883547d4b7f0495ebe7056b0cc2aea76094e7a4abc8e933540f3271df27d9c", size = 6337160, upload-time = "2026-07-01T11:53:55.457Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/fa/dc2a5c0ba6df93f67c31d34b808b7ce440b40cdbf96f0b81cde1d1e6fa93/pillow-12.3.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:236ff70b9312fb68943c703aa842ca6a758abfa45ac187a5e7c1452e96ef72b5", size = 7045172, upload-time = "2026-07-01T11:53:57.736Z" },
+    { url = "https://files.pythonhosted.org/packages/86/a5/444817a4d4c4c2417df00513086ca196f388d8f9ef40c2e4ccd1ad1af54b/pillow-12.3.0-cp311-cp311-win32.whl", hash = "sha256:10e41f0fbf1eec8cfd234b8fe17a4caac7c9d0db4c204d3c173a8f9f6ef3232b", size = 6472232, upload-time = "2026-07-01T11:53:59.767Z" },
+    { url = "https://files.pythonhosted.org/packages/63/c6/4bad1b18d132a50b27e1365e1ab163616f7a5bb56d330f66f9d1d9d4f9d4/pillow-12.3.0-cp311-cp311-win_amd64.whl", hash = "sha256:8e95e1385e4998ae9694eeaa4730ba5457ff61185b3a55e2e7bea0880aef452a", size = 7233653, upload-time = "2026-07-01T11:54:02.066Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/16/00f91ab7760dc842f5aad55217e80fc4a7067a0604535249bc8a2d6d9870/pillow-12.3.0-cp311-cp311-win_arm64.whl", hash = "sha256:ebaea975e03d3141d9d3a507df75c9b3ec90fa9d2ffd07567b3a978d9d790b26", size = 2568195, upload-time = "2026-07-01T11:54:04.622Z" },
+    { url = "https://files.pythonhosted.org/packages/37/bf/fb3ebff8ddcb76aac5a01389251bbbb9519922a9b520d8247c1ca864a25d/pillow-12.3.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ba09209fbe443b4acccebe845d8a138b89a8f4fbaeedd44953490b5315d5e965", size = 5345969, upload-time = "2026-07-01T11:54:06.397Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/66/9a386a92561f402389a4fc70c18838bf6d35eb5eb5c6850b4b2dc64f5048/pillow-12.3.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ffd0c5368496f41b0944be820fcb7a838aa6e623d250b01acf2643939c3f99d7", size = 4780323, upload-time = "2026-07-01T11:54:09.351Z" },
+    { url = "https://files.pythonhosted.org/packages/25/27/ac8f99618ffd3dde21db0f4d4b1d2ab00c0880595bfd17df103f7f39fd0c/pillow-12.3.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d9c7f76c0673154f044e9d78c8655fb4213f6ca31a836df48b40fe5d187717b9", size = 6266838, upload-time = "2026-07-01T11:54:11.71Z" },
+    { url = "https://files.pythonhosted.org/packages/84/21/a35af28dcc61f37ed850a2d64c65c701321dfbf25085e469d5559360cbbf/pillow-12.3.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:78cb2c6865a35ab8ff8b75fd122f6033b92a62c82801110e48ddd6c936a45d91", size = 6940830, upload-time = "2026-07-01T11:54:13.732Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/51/8b08617af3ad95e33ce6d7dd2c99ed6c8298f7fb131636303956be022e25/pillow-12.3.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e491916b378fba47242221bb9ead245211b70d504f495d105d17b14a24b4907c", size = 6344383, upload-time = "2026-07-01T11:54:15.756Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/72/cf78ac9780bb93c28328f408973845a309d4d145041665f734572ced1b52/pillow-12.3.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:0dd2064cbc55aaec028ef5fbb60fa47bb6c3e7918e07ff17935284b227a9d2df", size = 7052934, upload-time = "2026-07-01T11:54:17.721Z" },
+    { url = "https://files.pythonhosted.org/packages/20/20/25e0f4dc178a6bc0696793720055519a0de89e7661dae886992decbd2f81/pillow-12.3.0-cp312-cp312-win32.whl", hash = "sha256:dbce0b29841537a2fa4a214c2bbf14de3587c9680caa9b4e217568472490b28f", size = 6472684, upload-time = "2026-07-01T11:54:19.839Z" },
+    { url = "https://files.pythonhosted.org/packages/45/89/da2f7971a317f83d807fdd4065c0af40208e59e692cc43d315a71a0e96d1/pillow-12.3.0-cp312-cp312-win_amd64.whl", hash = "sha256:a2b55dd6b2a4c4b7d87ffa56bdb33fdc5fdb9a462173861a7bc097f17d91cb09", size = 7227137, upload-time = "2026-07-01T11:54:22.025Z" },
+    { url = "https://files.pythonhosted.org/packages/de/47/4845a0a6c0dbf1db8456bd9fc791f13c5ced7ced20606d08a0aacfd25b49/pillow-12.3.0-cp312-cp312-win_arm64.whl", hash = "sha256:331b624368d4f1d069149002f25f44bc61c8919ce8ddb3c45bdad8f6e2d89510", size = 2568267, upload-time = "2026-07-01T11:54:24.051Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/ac/31fb64e1e7efb5a4b50cd3d92049ba89ac6e4d8d3bb6a74e15048ca3353e/pillow-12.3.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:21900ce7ba264168cd50defae43cd75d25c833ad4ad6e73ffc5596d12e25ac89", size = 4161684, upload-time = "2026-07-01T11:54:25.934Z" },
+    { url = "https://files.pythonhosted.org/packages/87/b4/9805e23d2b4d77842b468513841fda254ee42f0289d25088340e4ff46e2d/pillow-12.3.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:4e8c2a84d977f50b9daed6eeaf3baef67d00d5d74d932288f02cb94518ee3ace", size = 4255487, upload-time = "2026-07-01T11:54:27.935Z" },
+    { url = "https://files.pythonhosted.org/packages/df/39/ecf519435a200c693fe053a6ee4d835b41cf963a4dfc2551c4e637cb2a71/pillow-12.3.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:ae26d61dfa7a47befdc7572b521024e8745f3d809bd95ca9505a7bba9ef849ec", size = 3696433, upload-time = "2026-07-01T11:54:29.813Z" },
+    { url = "https://files.pythonhosted.org/packages/42/92/2fc3ffad878ae8dd5469ec1bc8eb83b71f48e13efdf68f02709003982a32/pillow-12.3.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:7a743ff716f746fc19a9557f60dab1600d4613255f8a7aeb3cdde4db7eb15a66", size = 5345889, upload-time = "2026-07-01T11:54:31.97Z" },
+    { url = "https://files.pythonhosted.org/packages/10/76/8803c13605b763d33d156c4678fc77f8443389c0c51c8aef707bb02015f4/pillow-12.3.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:d69141514cc30b774ceea5e3ed3a6635c8d8a96edf664689b890f4089111fb35", size = 4780109, upload-time = "2026-07-01T11:54:34.026Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/01/e18aff37cb0b4aac47ac90f016d347a49aca667ef97f190b06ac2aabc928/pillow-12.3.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f7401aebd7f581d7f83a439d87d474999317ee099218e5ad25d125290990ba65", size = 6263736, upload-time = "2026-07-01T11:54:36.131Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/62/de5bdd77d935331f4f802edc11e4d82950f642caad6cb2f949837b8560e2/pillow-12.3.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0847a763afefb695bc912d7c131e7e0632d4edc1d8698f58ddabec8e46b8b6d3", size = 6937129, upload-time = "2026-07-01T11:54:38.216Z" },
+    { url = "https://files.pythonhosted.org/packages/70/4d/105627a13300c5e0df1d174230b32fd1273062c96f7745fd552b945d1e1d/pillow-12.3.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:571b9fcb07b97ef3a492028fb3d2dc0993ca23a06138b0315286566d29ef718a", size = 6339562, upload-time = "2026-07-01T11:54:40.354Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/1d/f13de01a553988ab895ba1c722e06cf3144d4f57656fd5b81b6d881f1179/pillow-12.3.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:756c768d0c9c2955feb7a56c37ea24aea2e369f8d36a88da270b6a9f19e62b5e", size = 7049439, upload-time = "2026-07-01T11:54:42.489Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/f9/066794cca041b969964f779ee5fa66a9498bbf34248ac39c5d7954e4198f/pillow-12.3.0-cp313-cp313-win32.whl", hash = "sha256:a876864214e136f0eb367788dbd7df045f4806801518e2cfe9e13229cfe06d8f", size = 6473287, upload-time = "2026-07-01T11:54:44.9Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/9b/7a58e61d62be561da3a356fe2384d4059a6345fc130e23ef1c36a5b81d24/pillow-12.3.0-cp313-cp313-win_amd64.whl", hash = "sha256:1cca606cd25738df4ed873d5ad46bbdb3d83b5cbca291f6b4ff13a4df6b0bbe8", size = 7239691, upload-time = "2026-07-01T11:54:47.141Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/b0/c4ed4f0ef8f8fa5ee8351537db6650bb8189f7e118842978dd6589065692/pillow-12.3.0-cp313-cp313-win_arm64.whl", hash = "sha256:b629de27fda84b42cde7edef0d85f13b958b47f6e9bbcbba9b673c562a89bd8b", size = 2568185, upload-time = "2026-07-01T11:54:49.137Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/01/001f65b68192f0228cc1dbbc8d2530ab5d58b61037ba0587f946fea607cd/pillow-12.3.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:9cf95fe4d0f84c82d282745d9bb08ad9f926efa00be4697e767b814ce40d4330", size = 4161736, upload-time = "2026-07-01T11:54:51.156Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/d2/0219746d0fd16fc8a84498e79452375be3797d3ce4044596ce565164b84f/pillow-12.3.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:8728f216dcdb6e6d555cf971cb34076139ad74b31fc2c14da4fafc741c5f6217", size = 4255435, upload-time = "2026-07-01T11:54:53.414Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/02/8d0bc62ef0302318c46ff2a512822d2610e81c7aa46c9b3abe6cbaca5ad0/pillow-12.3.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:a45650e8ce7fafffd731db8550230db6b0d306d181a90b67d3e6bca2f1990930", size = 3696262, upload-time = "2026-07-01T11:54:55.739Z" },
+    { url = "https://files.pythonhosted.org/packages/85/e2/73c77d218410b14f5f2d565e8a998d5317b7b9c75368d29985139f7a46f0/pillow-12.3.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:ba54cfebe86920a559a7c4d6b9050791c20513650a1952ebe3368c7dc70306f8", size = 5350344, upload-time = "2026-07-01T11:54:57.657Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/da/32c752228ae345f489e3a42499d817b6c3996da7e8a3bc7a04fc806b243b/pillow-12.3.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e158cb00350dc278f3b91551101aa7d12415a66ebf2c91d8d5ac14e56ddd3ad0", size = 4780131, upload-time = "2026-07-01T11:54:59.713Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/9d/8b2c807dbef61a5197c047afe99823787eb66f63daf9fb2432f91d6f0462/pillow-12.3.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e9aeb04d6aef139de265b29683e119b638208f88cf73cdd1658aa07221165321", size = 6263757, upload-time = "2026-07-01T11:55:01.778Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/44/c85361f65dbe00eea8576ee467c768d25129989efb76e94f205e9ca9bb46/pillow-12.3.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:251bf95b67017e27b13d82f5b326234ca62d70f9cf4c2b9032de2358a3b12c7b", size = 6936962, upload-time = "2026-07-01T11:55:03.93Z" },
+    { url = "https://files.pythonhosted.org/packages/18/7e/e483414b35800b86b6f08dbbc7803fb5cd52c4d6f897f47d53ea2c7e6f65/pillow-12.3.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:fe3cca2e4e8a592be0f269a1ca4835c25199d9f3ce815c8491048f785b0a0198", size = 6339171, upload-time = "2026-07-01T11:55:05.989Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/f4/68c491844841ede6bed70189546b3ee9731cf9f2cbad396faff5e1ccba45/pillow-12.3.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:23aceaa007d6172b02c277f0cd359c79492bbb14f7072b4ede9fbcaf20648130", size = 7048116, upload-time = "2026-07-01T11:55:08.131Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/34/77f3f793fed8efc7d243f21b33c5a3f0d1c97ee70346d3db855587e155ff/pillow-12.3.0-cp314-cp314-win32.whl", hash = "sha256:af8d94b0db561cf68b88a267c5c44b49e134f525d0dc2cb7ed413a66bc23559a", size = 6467209, upload-time = "2026-07-01T11:55:10.408Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/e0/492879f69d94f91f60fc8cd05ba03650e9520afebb2fb7aa12777d7c7f38/pillow-12.3.0-cp314-cp314-win_amd64.whl", hash = "sha256:fdafc9cce40277e0f7a0feabce0ee50dd2fa1800f3b38015e51296b5e814048d", size = 7237707, upload-time = "2026-07-01T11:55:12.745Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/ac/6b11f2875f1c2ac040d84e1bbf9cf22a88038f901ca1037898b280b38365/pillow-12.3.0-cp314-cp314-win_arm64.whl", hash = "sha256:e91206ee562682b51b98ef4b26a6ef48fd84e15fd4c4bc5ec768eb641d206838", size = 2565995, upload-time = "2026-07-01T11:55:14.736Z" },
+    { url = "https://files.pythonhosted.org/packages/52/69/c2208e56af9bfc1913afb24020297a691eb1d4ef688474c8a04913f65e04/pillow-12.3.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:164b31cd1a0490ab6efae01aa5df49da7061be0af1b30e035b6e9a1bfe34ee6e", size = 5352503, upload-time = "2026-07-01T11:55:17.076Z" },
+    { url = "https://files.pythonhosted.org/packages/07/70/e5686d753e898a45d778ff1718dba8516ead6ab6b95d85fc8c4b70650cf2/pillow-12.3.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5afb51d599ea772b8365ae807ae557f18bccfe46ab261fd1c2a9ed700fc6eb17", size = 4782956, upload-time = "2026-07-01T11:55:19.448Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/37/25c6692f06927ee973ff18c8d9ee98ad0b4d84ee67a09610c2dd1447958e/pillow-12.3.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3edce1d53195db527e0191f84b71d02022de0540bf43a16ed734ed7537b07385", size = 6322855, upload-time = "2026-07-01T11:55:21.613Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/91/420637fcb8f1bc11029e403b4538e6694744428d8246118e45719f944556/pillow-12.3.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bf16ba1b4d0b6b7c8e534936632270cf70eb00dbe09005bc345b2677b726855c", size = 6989642, upload-time = "2026-07-01T11:55:24.006Z" },
+    { url = "https://files.pythonhosted.org/packages/10/08/b94d7811281ccf0d143a1cf768d1c49e1e54af63e7b708ab2ee3eb87face/pillow-12.3.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:24870b09b224f7ae3c39ed07d10e819d06f8720bc551847b1d623832b5b0e28d", size = 6391281, upload-time = "2026-07-01T11:55:26.252Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/87/24233f785f55474dc02ce3e739c5528a77e3a862e9333d1dd7a25cc31f70/pillow-12.3.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:30f2aa603c41533cc25c05acd0da21636e84a315768feb631c937177db558931", size = 7096716, upload-time = "2026-07-01T11:55:28.318Z" },
+    { url = "https://files.pythonhosted.org/packages/23/26/fcb2f6e37175b04f53570b59937867e2b80ee1685e744023153028fc14f9/pillow-12.3.0-cp314-cp314t-win32.whl", hash = "sha256:4b0a7fe987b14c31ebda6083f74f22b561fd3739bc0ac51e019622e3d72668c7", size = 6474125, upload-time = "2026-07-01T11:55:30.956Z" },
+    { url = "https://files.pythonhosted.org/packages/90/de/3634abee5f1c9e13c56787b7d5517b0ba8d6de51700b95578cf338349c9f/pillow-12.3.0-cp314-cp314t-win_amd64.whl", hash = "sha256:962864dc93511324d51ddbb5b9f8731bf71675b93ca612a07441896f4688fb8c", size = 7242939, upload-time = "2026-07-01T11:55:34.044Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/2a/fd13f8eb24de5714a6eb444a3d67e2842c6c576e159a43793adf23051351/pillow-12.3.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0740a512dc522224c77d9aa5a8d70d8b7d73fb91f2c21125d8d025d3b8990e45", size = 2567506, upload-time = "2026-07-01T11:55:35.988Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/dc/8fdce34ec725a33c81c6ba122b904d6b9024e50ea9ac7bede62fab54506c/pillow-12.3.0-cp315-cp315-ios_13_0_arm64_iphoneos.whl", hash = "sha256:0feb2e9d6ad6c9e3c06effe9d00f3f1e618a6643273576b016f591e9315a7139", size = 4162063, upload-time = "2026-07-01T11:55:37.941Z" },
+    { url = "https://files.pythonhosted.org/packages/76/66/2044b9a63d3b84ff048228dfcb7cd9bf0df983e8470971bf7d4c57b693de/pillow-12.3.0-cp315-cp315-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:9e881fca225083806662a5c43d627d215f258ff43c890f831966c7d7ba9c7402", size = 4255549, upload-time = "2026-07-01T11:55:40.022Z" },
+    { url = "https://files.pythonhosted.org/packages/52/7e/1f67e6f4ece6b582ee4b539decbcc9f848dc245a93ed8cd7338bafef72f1/pillow-12.3.0-cp315-cp315-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:4998562bf62a445225f22e07c896bb04b35b1b1f2eb6d760584c9c51d7a5f78c", size = 3696331, upload-time = "2026-07-01T11:55:41.98Z" },
+    { url = "https://files.pythonhosted.org/packages/12/40/d306fc2c8e4d45d7f175c77edca7063be7b86fe7fe6e68f4353bf71d808c/pillow-12.3.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:dc624f6bc473dacdf7ef7eb8678d0d08edf15cd94fad6ae5c7d6cc67a4e4902f", size = 5350370, upload-time = "2026-07-01T11:55:44.028Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/44/668fb1437e8ce420f62d6106eb66e44a5971602a4d794615bdf79315d82d/pillow-12.3.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:71d6097b330eea8fd15097780c8e89cb1a8ce7838669f48c5bacd6f663dd4701", size = 4780147, upload-time = "2026-07-01T11:55:46.073Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/08/93fa2e70e30a2d81547e481b6ee2bb9522117221fb1e0ce4b5df70967677/pillow-12.3.0-cp315-cp315-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:28ce87c5ab450a9dd970b52e5aca5fe63ed432d18a2eaddd1979a00a1ba24ace", size = 6273659, upload-time = "2026-07-01T11:55:48.264Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/6d/043e96ff814fc31a33077e4cba86082167db520c93632afdf2042febbb0c/pillow-12.3.0-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6b02afb9b97f65fbca5f31db6a2a3ba21aa93030225f150fa3f249717e938fb4", size = 6947439, upload-time = "2026-07-01T11:55:50.503Z" },
+    { url = "https://files.pythonhosted.org/packages/af/92/ba71d2ee2ac0edf3fa33bd9d5ee9ee080da70b1766f3ca3934f9938ddac9/pillow-12.3.0-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:1182d52bc2d5e5d7d0949503aa7e36d12f42205dc287e4883f407b1988820d39", size = 6353577, upload-time = "2026-07-01T11:55:52.697Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/ce/e63064e2122923ff687c8ad792d0d736a7b3920a56a46982e81a7fdd25d6/pillow-12.3.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:e795b7eb908249c4e43c7c99fac7c2c75dab0c43566e37db472a355f63693d71", size = 7060394, upload-time = "2026-07-01T11:55:55.149Z" },
+    { url = "https://files.pythonhosted.org/packages/54/76/a09cc3ccc8d773a7283d34c38bec1708f9e3cc932093cbc4c5e71ac4060b/pillow-12.3.0-cp315-cp315-win32.whl", hash = "sha256:57b3d78c95ba9059768b10e28b813002261d3f3dfc55cc48b0c988f625175827", size = 6467375, upload-time = "2026-07-01T11:55:57.769Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/03/1846c49ba3b1d5550392a4bbd06d6fb4578e1cd91a803198b5c90f5f7d53/pillow-12.3.0-cp315-cp315-win_amd64.whl", hash = "sha256:fa4ecea169a355be7a3ade2c783e2ed12f0e40d2c5621cda8b3297faf7fbb9f5", size = 7237048, upload-time = "2026-07-01T11:55:59.975Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/bb/89f35dcc79610423f9f195504d7def7f0d1416a711541b42867e25fe3412/pillow-12.3.0-cp315-cp315-win_arm64.whl", hash = "sha256:877c3f311ff35410f690861c4409e7ccbf0cd2f878e50628a28e5a0bb689e658", size = 2566006, upload-time = "2026-07-01T11:56:02.143Z" },
+    { url = "https://files.pythonhosted.org/packages/30/88/707027ba09942dfa2c28759b5c222d769290a41c6d20ea60ec250801941f/pillow-12.3.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:e9871b1ffbfa9656b60aeee92ed5136a5742696006fa322b29ea3d8da0ecc9cf", size = 5352509, upload-time = "2026-07-01T11:56:04.2Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/6d/00352fa25332c2569cd387851f568cc5a4b75a9adbfb37ac4fbce4c02eec/pillow-12.3.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:53aa02d20d10c3d814d536aa4e5ac9b84ca0ff5a88377963b085ad6822f93e64", size = 4783167, upload-time = "2026-07-01T11:56:06.631Z" },
+    { url = "https://files.pythonhosted.org/packages/13/4f/9e049dfa21af7c22427275720e2490267ba8138120add5c4c574deb69782/pillow-12.3.0-cp315-cp315t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:446c34dcc4324b084a53b705127dc15717b22c5e140ae0a3c38349d4efec071e", size = 6329237, upload-time = "2026-07-01T11:56:08.868Z" },
+    { url = "https://files.pythonhosted.org/packages/36/16/cf6eeaae8d0fce8dd390a33437cf68c5d5bd73834a2bc6e2f14efda0ab45/pillow-12.3.0-cp315-cp315t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cf1845d02ad822a369a49f2bb9345b1614744267682e7a03527dc3bf6eea1777", size = 6997047, upload-time = "2026-07-01T11:56:11.379Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/69/dbf769bdd55f48bf5733cac28edc6364ffaa072ec9ba336266e4fe66be55/pillow-12.3.0-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:186941b6aef820ad110fb01fb06eb925374dc3a21b17e37ec9a53b250c6fe2d1", size = 6400440, upload-time = "2026-07-01T11:56:13.908Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/e1/ffc9cfc2eea0d178da8018e18e959301ad9d6bc9f3edb7181e748a474b97/pillow-12.3.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:f13c32a3abd6079a66d9526e18dad9b6d280384d49d7c54040cd57b6424041d9", size = 7105895, upload-time = "2026-07-01T11:56:16.575Z" },
+    { url = "https://files.pythonhosted.org/packages/18/f0/a5595c1e8c3ae44b9828cb2f0fa8155e5095ef04d6327b8f61cf44a3df85/pillow-12.3.0-cp315-cp315t-win32.whl", hash = "sha256:1657923d2d45afb66526e5b933e5b3052e6bdea196c90d3abb2424e18c77dae8", size = 6474384, upload-time = "2026-07-01T11:56:18.855Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/04/62bcd9f844984c5938d3b05264a61d797a29d3e0812341a8204af70bbdee/pillow-12.3.0-cp315-cp315t-win_amd64.whl", hash = "sha256:8cd2f7bdda092d99c9fc2fb7391354f306d01443d22785d0cbfafa2e2c8bb418", size = 7243537, upload-time = "2026-07-01T11:56:21.214Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/68/1f3066acedf37673694a7141381d8f811ae97f30d34413d236abe7d489f1/pillow-12.3.0-cp315-cp315t-win_arm64.whl", hash = "sha256:06ff022112bc9cbf83b60f8e028d94ad87b60621706487e65f673de61610ab59", size = 2567491, upload-time = "2026-07-01T11:56:23.506Z" },
+    { url = "https://files.pythonhosted.org/packages/75/18/2e8b40223153ccbc60df07f9e8928dc0c76202aa4e55ae9f53962b6510d6/pillow-12.3.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:b3c777e849237620b022f7f297dd67705f9f5cf1685f09f02e46f93e92725468", size = 5302510, upload-time = "2026-07-01T11:56:25.736Z" },
+    { url = "https://files.pythonhosted.org/packages/46/3e/51fabf59d5ab801ceab709453d3ab6b180083496579549de4c45ced6528a/pillow-12.3.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:b343699e8308bdc51978310e1c959c584e7869cc8c40780058c87da7781a1e94", size = 4736058, upload-time = "2026-07-01T11:56:28.041Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/20/22fe9384b7949e25fb1293bcfc84fb82590ff4ea6b37c95b24d26d793d86/pillow-12.3.0-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fbd139c8447d25dd750ab79ee274cc5e1fe80fc56340ab10b18a195e1b6eca3e", size = 5237776, upload-time = "2026-07-01T11:56:30.263Z" },
+    { url = "https://files.pythonhosted.org/packages/08/14/f6ba68107680ffa74b39985f3f30884e41318fbc4250caa423c79b4788bb/pillow-12.3.0-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e7e480451b9fa137494bccd3a7d69adbe8ac65a87d97be61e11f1b1050a5bac3", size = 5860358, upload-time = "2026-07-01T11:56:32.68Z" },
+    { url = "https://files.pythonhosted.org/packages/36/54/0169bc772ec491108b62f644f8ecf1fe5d8ae5ebafde2ee2142210166903/pillow-12.3.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:04f01d28a6aaff387bf842a13be313df23ba0597a44f1a976c9feb3c6ff4711a", size = 7231786, upload-time = "2026-07-01T11:56:35.046Z" },
 ]
 
 [[package]]

From 31f8eb03416aecf22e877814398e3b85cba388fb Mon Sep 17 00:00:00 2001
From: martyna-mindsdb <martyna@mindsdb.com>
Date: Thu, 23 Jul 2026 14:33:55 +0200
Subject: [PATCH 29/33] fix: npm packages vulnerability

---
 docs/package-lock.json | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/package-lock.json b/docs/package-lock.json
index ec8bc4aa..be6c4ae4 100644
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@@ -7137,9 +7137,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.15",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.15.tgz",
-      "integrity": "sha512-EwOCDEex4quD37XhqM3omwtMoJjr//isUZz1JopUNWms+4Z2ViyM/k1YIRePpoVNnQhENnxtFjLaxNHrT7xIUg==",
+      "version": "1.1.16",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
+      "integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0",
@@ -9967,9 +9967,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
-      "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==",
+      "version": "3.1.4",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz",
+      "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==",
       "funding": [
         {
           "type": "github",
@@ -10507,9 +10507,9 @@
       }
     },
     "node_modules/gray-matter/node_modules/js-yaml": {
-      "version": "3.14.2",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz",
-      "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==",
+      "version": "3.15.0",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz",
+      "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==",
       "license": "MIT",
       "dependencies": {
         "argparse": "^1.0.7",
@@ -11676,9 +11676,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.2.0.tgz",
-      "integrity": "sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==",
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
+      "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
       "funding": [
         {
           "type": "github",
@@ -18071,9 +18071,9 @@
       }
     },
     "node_modules/shell-quote": {
-      "version": "1.8.4",
-      "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.4.tgz",
-      "integrity": "sha512-VsC6n6vz1ihYYyZZwX7YZSF5l5x36ca17OC+a69h94YqB7X6XLwf+5MOgynYir2SLFUbl8gIYvBo8K8RoNQ6bQ==",
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.10.0.tgz",
+      "integrity": "sha512-w1aiOKwKuRgtwAReIIj89puqg+I7GvX4IbLrvmhXbzQsj1+Zwi4VO3+fa6ZF91TWSjIxoEkKnMeHcLEODK5ZXA==",
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -18570,9 +18570,9 @@
       "license": "MIT"
     },
     "node_modules/svgo": {
-      "version": "3.3.3",
-      "resolved": "https://registry.npmjs.org/svgo/-/svgo-3.3.3.tgz",
-      "integrity": "sha512-+wn7I4p7YgJhHs38k2TNjy1vCfPIfLIJWR5MnCStsN8WuuTcBnRKcMHQLMM2ijxGZmDoZwNv8ipl5aTTen62ng==",
+      "version": "3.3.4",
+      "resolved": "https://registry.npmjs.org/svgo/-/svgo-3.3.4.tgz",
+      "integrity": "sha512-GsNRis4e8jxn2Y9ENz/8lbJ93CstG8svtMnuRaHbiF2LTJ5tK0/q3t/URPq9Zc7zVWBJnNnJMIp6bevK7bSmNg==",
       "license": "MIT",
       "dependencies": {
         "commander": "^7.2.0",

From ecbbe11bd47699dc54ad56f3ad72f935e4eed4b4 Mon Sep 17 00:00:00 2001
From: Lucas Koontz <lucas.emanuel.koontz@gmail.com>
Date: Fri, 24 Jul 2026 18:25:59 -0700
Subject: [PATCH 30/33] ci(ENG-1008): merge-to-main + staging panic and
 recovery alerts (#274)

Add a terminal notify-failure job (if: failure(), needs every job so a
mid-graph failure still fires) to every push-to-main and push-to-staging
pipeline and to the freeze/unfreeze wrappers, plus a paired recovery job
on the pipelines. All route to the eng channel via the shared
notify-main-failure reusable.
---
 .github/workflows/docs.yml             | 23 +++++++++++++++++++++++
 .github/workflows/release.yml          | 24 ++++++++++++++++++++++++
 .github/workflows/staging-freeze.yml   | 11 +++++++++++
 .github/workflows/staging-unfreeze.yml | 11 +++++++++++
 .github/workflows/tests.yml            | 24 ++++++++++++++++++++++++
 5 files changed, 93 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ec83af76..87f97f2b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -47,3 +47,26 @@ jobs:
     steps:
       - id: deployment
         uses: actions/deploy-pages@v4
+
+  notify-failure:
+    # Alert the eng channel if the docs build or Pages deploy fails.
+    needs: [build, deploy]
+    if: failure()
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "docs deploy"
+      runs-on: ubuntu-latest
+    secrets: inherit
+
+
+  notify-recovery:
+    # Post a green "recovered" message when the pipeline goes green after a
+    # failing run (the reusable no-ops on a normal green run).
+    needs: [build, deploy]
+    if: success()
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "docs deploy"
+      status: recovered
+      runs-on: ubuntu-latest
+    secrets: inherit
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5053fef6..70f12356 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -93,3 +93,27 @@ jobs:
     with:
       tag: ${{ needs.auto-release.outputs.tag }}
     secrets: inherit
+
+  notify-failure:
+    # Alert the eng channel if ANY job in the release pipeline fails (tag, PyPI
+    # publish, or release e2e).
+    needs: [auto-release, publish, e2e]
+    if: failure()
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "release"
+      runs-on: ubuntu-latest
+    secrets: inherit
+
+
+  notify-recovery:
+    # Post a green "recovered" message when the pipeline goes green after a
+    # failing run (the reusable no-ops on a normal green run).
+    needs: [auto-release, publish, e2e]
+    if: success()
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "release"
+      status: recovered
+      runs-on: ubuntu-latest
+    secrets: inherit
diff --git a/.github/workflows/staging-freeze.yml b/.github/workflows/staging-freeze.yml
index 20c399c2..d04b08b3 100644
--- a/.github/workflows/staging-freeze.yml
+++ b/.github/workflows/staging-freeze.yml
@@ -13,3 +13,14 @@ jobs:
   freeze:
     uses: mindsdb/github-actions/.github/workflows/release-freeze.yml@75df118f3b003625052c4f14e7b90817fb8b2784 # v1
     secrets: inherit
+
+  notify-failure:
+    # Alert the eng channel if the freeze fails (e.g. missing ruleset) — otherwise
+    # a broken freeze is silent and the code-freeze window never opens.
+    needs: [freeze]
+    if: failure()
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "staging freeze"
+      runs-on: ubuntu-latest
+    secrets: inherit
diff --git a/.github/workflows/staging-unfreeze.yml b/.github/workflows/staging-unfreeze.yml
index 3874fe7f..eff430e6 100644
--- a/.github/workflows/staging-unfreeze.yml
+++ b/.github/workflows/staging-unfreeze.yml
@@ -17,3 +17,14 @@ jobs:
        github.event.pull_request.head.repo.full_name == github.repository)
     uses: mindsdb/github-actions/.github/workflows/release-unfreeze.yml@75df118f3b003625052c4f14e7b90817fb8b2784 # v1
     secrets: inherit
+
+  notify-failure:
+    # Alert the eng channel if the unfreeze or main->staging sync-back fails —
+    # otherwise staging stays frozen (or drifts from main) with no signal.
+    needs: [unfreeze]
+    if: failure()
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "staging unfreeze"
+      runs-on: ubuntu-latest
+    secrets: inherit
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 3b42e9c6..94afc5bb 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -26,3 +26,27 @@ jobs:
 
       - name: Run E2E tests (stub)
         run: uv run --extra dev pytest tests/e2e/ -v
+
+  notify-failure:
+    # Alert the eng channel if CI fails on a direct push to main/staging. PR runs
+    # are skipped — the author sees those directly.
+    needs: [run-tests]
+    if: failure() && github.event_name == 'push'
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "CI"
+      runs-on: ubuntu-latest
+    secrets: inherit
+
+
+  notify-recovery:
+    # Post a green "recovered" message when the pipeline goes green after a
+    # failing run (the reusable no-ops on a normal green run).
+    needs: [run-tests]
+    if: success() && github.event_name == 'push'
+    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
+    with:
+      env-name: "CI"
+      status: recovered
+      runs-on: ubuntu-latest
+    secrets: inherit

From 3b659c24846fd74a43e1edb2728b9e585ee41568 Mon Sep 17 00:00:00 2001
From: Lucas Koontz <lucas.emanuel.koontz@gmail.com>
Date: Fri, 24 Jul 2026 18:53:33 -0700
Subject: [PATCH 31/33] ci(ENG-1008): consolidate notify jobs for consistent
 pipeline alerts (#275)

Refactor CI workflows to utilize shared reusable workflows for failure and recovery notifications. Simplifies job definitions and ensures consistent alert behavior across build, release, and test pipelines.
---
 .github/workflows/cla.yml              | 16 ++----
 .github/workflows/docs.yml             | 24 ++++-----
 .github/workflows/release.yml          | 74 +++++---------------------
 .github/workflows/staging-freeze.yml   |  2 +-
 .github/workflows/staging-unfreeze.yml |  2 +-
 .github/workflows/tests.yml            | 24 ++++-----
 README.md                              |  5 ++
 7 files changed, 42 insertions(+), 105 deletions(-)

diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml
index 657003f1..ee428747 100644
--- a/.github/workflows/cla.yml
+++ b/.github/workflows/cla.yml
@@ -14,15 +14,7 @@ on:
 
 jobs:
   CLAssistant:
-    runs-on: ubuntu-latest
-    steps:
-      - name: "CLA Assistant"
-        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
-        uses: contributor-assistant/github-action@v2.6.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          path-to-signatures: 'assets/contributions-agreement/signatures/cla.json'
-          path-to-document: 'https://github.com/mindsdb/mindsdb/blob/main/assets/contributions-agreement/individual-contributor.md'
-          branch: 'cla'
-          allowlist: bot*, ZoranPandovski, torrmal, Stpmax, mindsdbadmin, ea-rus, hamishfagg, MinuraPunchihewa, martyna-mindsdb, tino097, lucas-koontz
\ No newline at end of file
+    uses: mindsdb/github-actions/.github/workflows/cla-assistant.yml@main
+    with:
+      path-to-document: 'https://github.com/mindsdb/mindsdb/blob/main/assets/contributions-agreement/individual-contributor.md'
+      allowlist: bot*, ZoranPandovski, torrmal, Stpmax, mindsdbadmin, ea-rus, hamishfagg, MinuraPunchihewa, martyna-mindsdb, tino097, lucas-koontz
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 87f97f2b..afadbabc 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -48,25 +48,19 @@ jobs:
       - id: deployment
         uses: actions/deploy-pages@v4
 
-  notify-failure:
+  notify:
     # Alert the eng channel if the docs build or Pages deploy fails.
+    # One job covers both outcomes: a `uses:` job cannot branch on status, so
+    # the aggregate result picks the failed or recovered message, and a
+    # cancelled run stays silent.
     needs: [build, deploy]
-    if: failure()
+    if: ${{ !cancelled() && !contains(needs.*.result, 'cancelled') }}
+    permissions:
+      contents: read
+      actions: read  # the prior-run lookup behind the recovery message
     uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
     with:
       env-name: "docs deploy"
-      runs-on: ubuntu-latest
-    secrets: inherit
-
-
-  notify-recovery:
-    # Post a green "recovered" message when the pipeline goes green after a
-    # failing run (the reusable no-ops on a normal green run).
-    needs: [build, deploy]
-    if: success()
-    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
-    with:
-      env-name: "docs deploy"
-      status: recovered
+      status: ${{ contains(needs.*.result, 'failure') && 'failed' || 'recovered' }}
       runs-on: ubuntu-latest
     secrets: inherit
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 70f12356..a4cb43b6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -12,54 +12,12 @@ concurrency:
   group: auto-release-${{ github.ref }}
   cancel-in-progress: false
 
-env:
-  CALVER_MAJOR: 2
-
 jobs:
   auto-release:
-    runs-on: ubuntu-latest
-    outputs:
-      tag: ${{ steps.version.outputs.tag }}
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # need tags for sequence calculation
-
-      - name: Compute CalVer version
-        id: version
-        run: |
-          set -euo pipefail
-
-          MAJOR=${{ env.CALVER_MAJOR }}
-          YY=$(date -u +%y)    # e.g. 26
-          M=$(date -u +%-m)    # e.g. 6 (no zero-pad)
-          DD=$(date -u +%-d)   # e.g. 23 (no zero-pad)
-
-          # Find the highest sequence for today's date
-          PREFIX="v${MAJOR}.${YY}.${M}.${DD}."
-          SEQ=0
-          for tag in $(git tag -l "${PREFIX}*" | sort -t. -k5 -n); do
-            N="${tag##*.}"
-            if [[ "$N" =~ ^[0-9]+$ ]] && [ "$N" -gt "$SEQ" ]; then
-              SEQ="$N"
-            fi
-          done
-          SEQ=$((SEQ + 1))
-
-          VERSION="${MAJOR}.${YY}.${M}.${DD}.${SEQ}"
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "Computed version: ${VERSION}"
-
-      - name: Create tag and GitHub Release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          git tag "${{ steps.version.outputs.tag }}"
-          git push origin "${{ steps.version.outputs.tag }}"
-          gh release create "${{ steps.version.outputs.tag }}" \
-            --generate-notes \
-            --title "${{ steps.version.outputs.tag }}"
+    uses: mindsdb/github-actions/.github/workflows/calver-release.yml@main
+    with:
+      calver-major: "2"
+      runs-on: ubuntu-latest
 
   publish:
     name: Publish to PyPI
@@ -94,26 +52,20 @@ jobs:
       tag: ${{ needs.auto-release.outputs.tag }}
     secrets: inherit
 
-  notify-failure:
+  notify:
     # Alert the eng channel if ANY job in the release pipeline fails (tag, PyPI
     # publish, or release e2e).
+    # One job covers both outcomes: a `uses:` job cannot branch on status, so
+    # the aggregate result picks the failed or recovered message, and a
+    # cancelled run stays silent.
     needs: [auto-release, publish, e2e]
-    if: failure()
-    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
-    with:
-      env-name: "release"
-      runs-on: ubuntu-latest
-    secrets: inherit
-
-
-  notify-recovery:
-    # Post a green "recovered" message when the pipeline goes green after a
-    # failing run (the reusable no-ops on a normal green run).
-    needs: [auto-release, publish, e2e]
-    if: success()
+    if: ${{ !cancelled() && !contains(needs.*.result, 'cancelled') }}
+    permissions:
+      contents: read
+      actions: read  # the prior-run lookup behind the recovery message
     uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
     with:
       env-name: "release"
-      status: recovered
+      status: ${{ contains(needs.*.result, 'failure') && 'failed' || 'recovered' }}
       runs-on: ubuntu-latest
     secrets: inherit
diff --git a/.github/workflows/staging-freeze.yml b/.github/workflows/staging-freeze.yml
index d04b08b3..aabe2c79 100644
--- a/.github/workflows/staging-freeze.yml
+++ b/.github/workflows/staging-freeze.yml
@@ -14,7 +14,7 @@ jobs:
     uses: mindsdb/github-actions/.github/workflows/release-freeze.yml@75df118f3b003625052c4f14e7b90817fb8b2784 # v1
     secrets: inherit
 
-  notify-failure:
+  notify:
     # Alert the eng channel if the freeze fails (e.g. missing ruleset) — otherwise
     # a broken freeze is silent and the code-freeze window never opens.
     needs: [freeze]
diff --git a/.github/workflows/staging-unfreeze.yml b/.github/workflows/staging-unfreeze.yml
index eff430e6..73cb63a5 100644
--- a/.github/workflows/staging-unfreeze.yml
+++ b/.github/workflows/staging-unfreeze.yml
@@ -18,7 +18,7 @@ jobs:
     uses: mindsdb/github-actions/.github/workflows/release-unfreeze.yml@75df118f3b003625052c4f14e7b90817fb8b2784 # v1
     secrets: inherit
 
-  notify-failure:
+  notify:
     # Alert the eng channel if the unfreeze or main->staging sync-back fails —
     # otherwise staging stays frozen (or drifts from main) with no signal.
     needs: [unfreeze]
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 94afc5bb..1b910d09 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -27,26 +27,20 @@ jobs:
       - name: Run E2E tests (stub)
         run: uv run --extra dev pytest tests/e2e/ -v
 
-  notify-failure:
+  notify:
     # Alert the eng channel if CI fails on a direct push to main/staging. PR runs
     # are skipped — the author sees those directly.
+    # One job covers both outcomes: a `uses:` job cannot branch on status, so
+    # the aggregate result picks the failed or recovered message, and a
+    # cancelled run stays silent.
     needs: [run-tests]
-    if: failure() && github.event_name == 'push'
+    if: ${{ !cancelled() && !contains(needs.*.result, 'cancelled') && github.event_name == 'push' }}
+    permissions:
+      contents: read
+      actions: read  # the prior-run lookup behind the recovery message
     uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
     with:
       env-name: "CI"
-      runs-on: ubuntu-latest
-    secrets: inherit
-
-
-  notify-recovery:
-    # Post a green "recovered" message when the pipeline goes green after a
-    # failing run (the reusable no-ops on a normal green run).
-    needs: [run-tests]
-    if: success() && github.event_name == 'push'
-    uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
-    with:
-      env-name: "CI"
-      status: recovered
+      status: ${{ contains(needs.*.result, 'failure') && 'failed' || 'recovered' }}
       runs-on: ubuntu-latest
     secrets: inherit
diff --git a/README.md b/README.md
index 309e60ff..ed98baba 100644
--- a/README.md
+++ b/README.md
@@ -317,6 +317,11 @@ Anton uses an automated release flow. The single source of truth for the package
    - Publishes a GitHub release with auto-generated notes.
    - Triggers [`tests_e2e_release.yml`](.github/workflows/tests_e2e_release.yml) to run live e2e tests against the released version.
 
+The version computation, tag push, and release creation are shared with the other
+service repos through the `calver-release.yml` reusable workflow in
+[mindsdb/github-actions](https://github.com/mindsdb/github-actions); this repo's
+workflow supplies the major component and consumes the resulting `tag` output.
+
 ### What you should NOT do
 
 - **Don't create GitHub releases manually.** The `v*` tag namespace is locked via a repo ruleset — only the release workflow can create them. Manual attempts will be rejected by GitHub.

From cc0fb7bf59715b29444a6bf20e41eab79edbcc3e Mon Sep 17 00:00:00 2001
From: Lucas Koontz <lucas.emanuel.koontz@gmail.com>
Date: Sun, 26 Jul 2026 16:46:01 -0700
Subject: [PATCH 32/33] chore(ENG-1053): introduce pipeline watchdog for
 startup failures alerting

Add a scheduled workflow to detect and alert on deploy pipeline startup failures that prevent branch deployments. Configure actionlint for organization-specific self-hosted runner labels to reduce noise in error reporting.
---
 .github/actionlint.yaml                 |  8 +++++
 .github/workflows/pipeline-watchdog.yml | 46 +++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 .github/actionlint.yaml
 create mode 100644 .github/workflows/pipeline-watchdog.yml

diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml
new file mode 100644
index 00000000..a2d0b713
--- /dev/null
+++ b/.github/actionlint.yaml
@@ -0,0 +1,8 @@
+# actionlint needs to be told about self-hosted runner labels, or every
+# `runs-on:` referring to one is an error and the real findings drown in noise.
+#
+#   mdb-dev, mdb-prod  the org's self-hosted runner pools
+self-hosted-runner:
+  labels:
+    - mdb-dev
+    - mdb-prod
diff --git a/.github/workflows/pipeline-watchdog.yml b/.github/workflows/pipeline-watchdog.yml
new file mode 100644
index 00000000..9242a0f0
--- /dev/null
+++ b/.github/workflows/pipeline-watchdog.yml
@@ -0,0 +1,46 @@
+# Alert when a deploy pipeline concluded WITHOUT EVER STARTING.
+#
+# The panic-alert job in each pipeline is a job inside that pipeline, so it covers
+# every failure where the run exists. It cannot cover
+# `conclusion: startup_failure` — GitHub rejecting the run at load time, with zero
+# jobs — because there is no job to put the alert in. The run appears in the
+# Actions tab and nowhere else, and the branch is not deployed.
+#
+# It is not hypothetical. In mindsdb/auth a caller job granted narrower
+# `permissions:` than a called workflow's jobs declared, two pushes to `staging`
+# were rejected before scheduling, and staging served the previous image for ten
+# hours with nothing said. The shared `workflow-lint.yml` gate stops that
+# particular cause reaching a deploy branch; this watchdog notices the next one,
+# whatever it is.
+#
+# Alerts repeat by design — roughly three per failing push at this cadence and
+# window, then silence. A stateless sweep cannot be exactly-once, and a missed
+# alert is the failure being fixed.
+#
+# Note it only runs once merged to `main`: GitHub runs `schedule` triggers from the
+# default branch alone. `workflow_dispatch` is how to prove it before then, and
+# widening the window on a dispatch replays a past incident.
+
+name: Pipeline watchdog
+
+on:
+  schedule:
+    - cron: "*/30 * * * *"
+  workflow_dispatch:
+    inputs:
+      lookback-minutes:
+        description: "Widen to replay a past incident"
+        type: number
+        default: 90
+
+jobs:
+  startup-failures:
+    permissions:
+      contents: read
+      actions: read # run + job history for the sweep
+    uses: mindsdb/github-actions/.github/workflows/notify-startup-failure.yml@main
+    with:
+      branches: "main staging"
+      lookback-minutes: ${{ inputs.lookback-minutes && fromJson(inputs.lookback-minutes) || 90 }}
+      runs-on: ubuntu-latest
+    secrets: inherit

From 5ca45bd3cdd96a383dc39455e66a2b2833593d34 Mon Sep 17 00:00:00 2001
From: Lucas Koontz <lucas.emanuel.koontz@gmail.com>
Date: Mon, 27 Jul 2026 03:31:23 -0700
Subject: [PATCH 33/33] ci: specify permissions for notify-main-failure
 workflow

Add explicit `contents: read` and `actions: read` permissions to `staging-freeze` and `staging-unfreeze` workflows. This ensures compatibility with reusable workflows and prevents loading failures due to insufficient permissions.
---
 .github/workflows/staging-freeze.yml   | 8 ++++++++
 .github/workflows/staging-unfreeze.yml | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/.github/workflows/staging-freeze.yml b/.github/workflows/staging-freeze.yml
index aabe2c79..3150e64a 100644
--- a/.github/workflows/staging-freeze.yml
+++ b/.github/workflows/staging-freeze.yml
@@ -19,6 +19,14 @@ jobs:
     # a broken freeze is silent and the code-freeze window never opens.
     needs: [freeze]
     if: failure()
+    permissions:
+      contents: read
+      # Declared even though this caller never runs the prior-run lookup: a
+      # reusable workflow's requested permissions are validated when the file
+      # is parsed, not when the step that needs them runs, so a caller that
+      # grants less than the reusable asks for is INVALID rather than merely
+      # degraded, and the whole workflow fails to load.
+      actions: read
     uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
     with:
       env-name: "staging freeze"
diff --git a/.github/workflows/staging-unfreeze.yml b/.github/workflows/staging-unfreeze.yml
index 73cb63a5..10b6f2b9 100644
--- a/.github/workflows/staging-unfreeze.yml
+++ b/.github/workflows/staging-unfreeze.yml
@@ -23,6 +23,14 @@ jobs:
     # otherwise staging stays frozen (or drifts from main) with no signal.
     needs: [unfreeze]
     if: failure()
+    permissions:
+      contents: read
+      # Declared even though this caller never runs the prior-run lookup: a
+      # reusable workflow's requested permissions are validated when the file
+      # is parsed, not when the step that needs them runs, so a caller that
+      # grants less than the reusable asks for is INVALID rather than merely
+      # degraded, and the whole workflow fails to load.
+      actions: read
     uses: mindsdb/github-actions/.github/workflows/notify-main-failure.yml@main
     with:
       env-name: "staging unfreeze"