@r1z4x/tezgah 1.0.0 → 1.2.0

package/docs/judge.md

@@ -1,8 +1,8 @@
 # Judge: the judgement seam, its five callers and its switches
 
-The judgement seam is `hooks/tezgah_judge.py`: one module that asks TypeSafe
-(Jev) for a batched structured judgement over a state tezgah would otherwise pay
-an agent to read. Read this page when you are about to call one of its four
+The judgement seam is `hooks/tezgah_judge.py`. It asks the session's own model,
+through the host's CLI, for a batched structured judgement over a state tezgah
+would otherwise pay an agent to read. Read this page when you are about to call one of its four
 callers, when you need to say what leaves the machine, or when you have to tell a
 user how to switch it off. It is an on-demand capability, not a rule: no paragraph
 of it is injected into a session, and a session that never asks pays one clause in
@@ -11,7 +11,7 @@ the kill-switch paragraph and nothing else (`CORE`,
 
 ## What it is
 
-One seam, five callers, one credential, one egress boundary, one price, one
+One seam, five callers, one provider order, one egress boundary, one price, one
 redirect guard. The module is stdlib only and total - a failure is a `None`, never
 an exception, because a hook imports it and a hook that raises takes a session
 down (`_request`, `hooks/tezgah_judge.py::_request`). One endpoint and one key path
@@ -21,31 +21,34 @@ are module constants (`URL`, `hooks/tezgah_judge.py::URL`; `KEY_FILE`,
 endpoint's host, so a `Location` cannot carry the bearer (`guarded_opener`,
 `hooks/tezgah_paths.py`, the one copy `bin/consult` and `bin/codegen` use too). A
 transient failure - a timeout, a connection error, a 5xx - gets exactly one more
-attempt; a 4xx and a malformed reply never do (`_transient`,
-`hooks/tezgah_judge.py::_transient`). A hook caller asks for one attempt and a
-wall-clock `deadline` instead (`ask`, `hooks/tezgah_judge.py::ask`).
-urllib's timeout bounds one socket operation, not the whole call.
-`TEZGAH_TYPESAFE_URL` repoints the endpoint and `TEZGAH_OPENROUTER_URL` the
-fallback's; both are test seams, not fallbacks.
-
-Every caller reads an answer through the same two accessors rather than reaching
+attempt. A 4xx, a session CLI's non-zero exit and a malformed reply never do
+(`_transient`, `hooks/tezgah_judge.py::_transient`). A hook caller asks for one
+attempt and a wall-clock `deadline` instead (`ask`, `hooks/tezgah_judge.py::ask`).
+A session CLI answers in 4-10 s (measured 2026-10-07), so the skill hint's
+4 s deadline usually ends first. `TEZGAH_TYPESAFE_URL`, `TEZGAH_OPENROUTER_URL`
+and `TEZGAH_OMP_BIN`/`TEZGAH_CLAUDE_BIN` are the test seams.
+
+Every caller reads an answer through the same accessors rather than reaching
 into the raw reply, so a Choice and a Noul are read one way for all five
 (`choice`, `hooks/tezgah_judge.py::choice`; `noul`,
-`hooks/tezgah_judge.py::noul`). Both are total: a missing or wrongly-typed
-answer is a `None`, never an exception.
+`hooks/tezgah_judge.py::noul`). A `text` question is the one shape that asks
+for prose. `bin/tezgah-taste` asks it for a learning's readable line, and only
+a generative provider answers one. TypeSafe is never sent one (`text`,
+`hooks/tezgah_judge.py::text`). All three are total: a missing or
+wrongly-typed answer is a `None`, never an exception.
 
 A judgement is an aid, never the claim. It ranks units or names a page; the agent
 still reads the selected refs and owns the finding, and the ledger's step kinds
 are untouched, so a model answer can never license a "done" (`STEP_KINDS`,
 `hooks/tezgah_integrity.py::STEP_KINDS`).
 
-The state leaves the machine. A judgement sends the state and the questions to
-`api.typesafe.ai` - for the triage that is the screen's own text, so a screen
-carrying personal data is read by a third party, and for the docs fallback it is
-the reader's query. When no TypeSafe key resolves, the same state goes to
-`openrouter.ai` instead (`OPENROUTER_URL`, `hooks/tezgah_judge.py::OPENROUTER_URL`), which is
-the price of a machine that has no Jev credential still having a judge at all:
-the destination changes, not what is sent. Nothing else goes: no session id, no
+The state leaves the machine. By default it goes to the session's own vendor,
+through the session's own CLI and credential ([below](#the-providers-and-their-order)).
+A third party - `api.typesafe.ai` or `openrouter.ai` (`OPENROUTER_URL`,
+`hooks/tezgah_judge.py::OPENROUTER_URL`) - reads it only as the `fallback`
+setting allows. For the triage the state is the screen's own text, so whoever
+answers reads any personal data on it. For the docs fallback it is the query.
+Nothing else goes: no session id, no
 workspace path, no environment. The seam does not rewrite the state, because
 sending it is the point. Two callers rewrite what they send. `bin/tezgah-route`
 sends its brief through the ledger's own redactor (`redact`,
@@ -69,7 +72,7 @@ why its redaction is not optional. The switches below are the off buttons.
 | `bin/tezgah-docs` | the docs page fallback: only when the keyword index placed nothing, one Choice over the pages with `none` offered (`judge_pick`, `bin/tezgah-docs::judge_pick`; the question wording is `ASK`, `bin/tezgah-docs::ASK`) | reads as no judgement; with none (no credential, `judge-off`, `docs-judge-off`, or a call that failed or came back without one of its options) the pages are ranked by shared words instead (`ranked`, BM25 in `hooks/tezgah_rank.py` over each page's title and answers and their Turkish phrasings) and the top three printed; a query sharing no word with any page, or a judged `none`, exits 1. With the opt-in embedding feature on, the ranking is fused with a static embedding (`hooks/tezgah_embed.py`), which places every page, so only a judged `none` exits 1 |
 | `hooks/tezgah_skill_pick.py` | the prompt-path skill hint: a Choice over the roster skills plus one Noul (`judge`, `hooks/tezgah_skill_pick.py::judge`, with the criteria cut from each skill's own clauses, `clause`, `hooks/tezgah_skill_pick.py::clause`), behind a threshold (`GATE`, `hooks/tezgah_skill_pick.py::GATE`), one attempt and a 4 s wall-clock deadline (`ASK_DEADLINE`, `hooks/tezgah_skill_pick.py::ASK_DEADLINE`), the prompt redacted and cut at 2,000 characters | returns `""`; the turn loses the hint |
 | `bin/tezgah-route` | the tier router: after the deterministic overrides, one Choice over the three tiers for a delegation brief (`route`, `hooks/tezgah_models.py::route`; `TIER_QUESTION`, `hooks/tezgah_models.py::TIER_QUESTION`) - see [models](models.md) | the static phase table, else the middle tier |
-| `bin/tezgah-taste` | the coding-taste measurement: `measure` and `rate` label the prompts a user sent after a writing turn, one Choice per prompt batched into one request, each prompt redacted first (`classify`, `bin/tezgah-taste::classify`) | with no credential or `judge-off` it exits 2 before any request; a failed call leaves its prompts unlabelled |
+| `bin/tezgah-taste` | the coding-taste measurement and learning: `measure` and `rate` label the prompts a user sent after a writing turn, one Choice per prompt batched into one request, each prompt redacted first (`classify`, `bin/tezgah-taste::classify`). `learn` asks one typed decision per signal and requires TypeSafe (`decide`, `bin/tezgah-taste::decide`). For a learning that turns active it asks one `text` question of a generative provider (`write_line`, `bin/tezgah-taste::write_line`) | with no credential or `judge-off` it exits 2 before any request. A failed call leaves its prompts unlabelled. A decision another provider gave is recorded `unverified` and never applied. A missing line keeps the user's own words |
 
 The third caller is the one no shell row can see: it runs on the prompt path,
 caches one answer per `(session, prompt)` (`_remember`,
@@ -77,37 +80,48 @@ caches one answer per `(session, prompt)` (`_remember`,
 `hooks/tezgah_skill_pick.py::suggest`), and asks at all only when its own marker is
 armed. The other four are bin tools a session runs by name.
 
-## The credential's channels
-
-The credential resolves from `TYPESAFE_API_KEY`, else from the key file the module
-names (`KEY_FILE`, `hooks/tezgah_judge.py::KEY_FILE`). The environment variable is the
-channel an interactive shell has; the file is the channel that matters, because a
-hook or a bin tool a host starts runs in a non-interactive shell where a
-`~/.zshenv` export never ran, so the variable is absent exactly where a judgement
-runs. That is why the file is read rather than the environment trusted. The
-install report's health row reads its own pair of channels ([hosts](hosts.md)),
-which is a different question from the one the seam asks.
-
-When neither channel resolves, the same two channels are read again for the
-fallback provider - `OPENROUTER_API_KEY`, then `~/.config/openrouter/key`
-(`openrouter_key()`, `hooks/tezgah_judge.py::openrouter_key`) - and the request goes to an
-OpenAI-compatible chat endpoint instead (`OPENROUTER_URL`,
-`hooks/tezgah_judge.py::OPENROUTER_URL`). TypeSafe wins whenever it resolves, so the fallback
-cannot move a machine that already judges with Jev (`credential()`,
-`hooks/tezgah_judge.py::credential`). The chat model is asked for the same shapes in prose
-(`CHAT_SYSTEM`, `hooks/tezgah_judge.py::CHAT_SYSTEM`), at temperature 0
-(`_chat_body()`, `hooks/tezgah_judge.py::_chat_body`), and its reply is filtered to the ids
-that were asked for, dropping any answer whose type does not match its question
-(`_chat_answers()`, `hooks/tezgah_judge.py::_chat_answers`; `_clean_answer()`,
-`hooks/tezgah_judge.py::_clean_answer`) - so a dropped answer reads the same as no answer at
-all, which is what the callers already handled. The model is the table's cheap row
-(`cheap_model`, `hooks/tezgah_models.py`) unless `TEZGAH_JUDGE_MODEL` names
-another, and a table that cannot be read falls back to its own literal
-(`fallback_model()`, `hooks/tezgah_judge.py::fallback_model`). The result carries the provider
-that answered and the model the reply names. The requested model stands only
-when the reply names none, so a silent upgrade behind `jev-latest` shows. The
-skill hint's cost row and the router's `route` row print both as one
-`judge=<provider>/<model>` word.
+## The providers and their order
+
+`providers()` (`hooks/tezgah_judge.py::providers`) is the order `ask()` tries.
+The next one is asked only when the previous failed. First comes the session's own
+CLI (`tp.session_cli`, `hooks/tezgah_paths.py::session_cli`): `omp` when
+`OMPCODE` is set, else `claude` when `CLAUDECODE` is. It runs headless with no
+tools, rules, skills, extensions, MCP servers or settings (`SESSION_ARGV`,
+`hooks/tezgah_judge.py::SESSION_ARGV`). Measured 2026-10-07, a call cost $0.007
+on claude and $0.015 on omp. The session's own credential pays, OAuth subscription
+included. The model and usage are read from the CLI's JSON output
+(`_session_request`, `hooks/tezgah_judge.py::_session_request`). Then come the
+third parties. TypeSafe reads `TYPESAFE_API_KEY`, else `~/.config/typesafe/key`
+(`key`, `hooks/tezgah_judge.py::key`). OpenRouter reads `OPENROUTER_API_KEY`, else
+`~/.config/openrouter/key` (`openrouter_key`, `hooks/tezgah_judge.py::openrouter_key`).
+It asks the table's cheap row unless `TEZGAH_JUDGE_MODEL` names another
+(`fallback_model`, `hooks/tezgah_judge.py::fallback_model`). The key file is
+read because a hook runs where `~/.zshenv` never did. A chat answer is asked for in prose
+(`CHAT_SYSTEM`, `hooks/tezgah_judge.py::CHAT_SYSTEM`) and filtered to the ids
+asked, a wrongly typed answer dropped (`_chat_answers`,
+`hooks/tezgah_judge.py::_chat_answers`).
+
+`fallback` in `~/.config/tezgah/config.json` (`fallback_policy`,
+`hooks/tezgah_paths.py::fallback_policy`) decides who may stand in:
+
+| `fallback` | Session CLI present | No session CLI |
+|---|---|---|
+| `vendor` (default) | the session CLI only; when it fails, no judgement | TypeSafe, then OpenRouter |
+| `any` | the session CLI, then TypeSafe, then OpenRouter | TypeSafe, then OpenRouter |
+| `none` | the session CLI only | nobody: `available()` is false |
+
+Nothing that stands in is silent. A result carries `provider`, the `model`
+the reply named and `fallback` - None when the session answered, else why it did
+not. That answer, and a refusal with its failures, is said on stderr as one
+`tezgah-judge:` line. It is also kept as the last-use record (`_record`,
+`hooks/tezgah_judge.py::_record`), which `tezgah-status --judge` prints. The skill
+hint's cost row and the router's `route` row also carry `judge=<provider>/<model>`.
+
+A caller that needs one provider in particular passes `only` (`named`,
+`hooks/tezgah_judge.py::named`). `learn`'s decision has to come from a typed
+model, so it passes `only=("typesafe",)`. It gets `None` rather than another
+provider's answer. The caller named the provider, so the `vendor` order does not
+apply. `none` still keeps every third party out.
 
 ## The switches
 
@@ -152,11 +166,11 @@ known (`note`, `hooks/tezgah_integrity.py::note`), counted by the row's kind
 3. **No seam-level answer cache, and no caller cache beyond the prompt-keyed one
    that exists** (`_remember`, `hooks/tezgah_skill_pick.py::_remember`). A judgement
    costs a fraction of a cent, so a cache is not worth its state file, and a naive
-   one would make two runs of the same command disagree. The one state the seam
-   keeps is a failure marker (`DOWN_FOR`, 300 s, in `hooks/tezgah_judge.py`). A
-   call that ends on a 401, 402 or 5xx marks that provider, endpoint and
-   credential down for five minutes. Until the marker expires, every call returns
-   no judgement and sends no request. A dead key or an empty account then costs
+   one would make two runs of the same command disagree. Beside the last-use
+   record, the seam keeps a failure marker (`DOWN_FOR`, 300 s, in `hooks/tezgah_judge.py`). A
+   call that ends on a 401, 402, 5xx or a session CLI's non-zero exit marks that
+   provider, endpoint and credential down for five minutes. Until the marker
+   expires, that provider is skipped and sent no request. A dead key or an empty account then costs
    one refusal per five minutes, not one per prompt. A rotated key gets a new
    marker, so the seam asks it at once.
 4. **No SDK, no `requests`, no async, no local model.** Each would trade one of
@@ -185,8 +199,9 @@ known (`note`, `hooks/tezgah_integrity.py::note`), counted by the row's kind
 - `hooks/tezgah_skill_pick.py` — the prompt-path skill hint, its threshold, its
   per-prompt cache and its `skill-suggest-on` marker.
 - `hooks/tezgah_policy.py` — the `**Kill switches:**` paragraph the session
-  receives; `hooks/tezgah_paths.py` — where a switch file is read, and the
-  redirect guard (`guarded_opener`) the seam, consult and codegen share.
+  receives; `hooks/tezgah_paths.py` — where a switch file is read, the session CLI
+  and the `fallback` setting, and the redirect guard (`guarded_opener`) the seam,
+  consult and codegen share; `bin/tezgah-status --judge` — the last-use record.
 - `hooks/tezgah_integrity.py` — the ledger and the `judge` counter;
   `hooks/tezgah_context.py` — the status mark and the class carve-out.
 - `tests/test_judge.py`, `tests/test_triage.py`, `tests/test_docs_router.py` —

package/docs/models.md

@@ -20,7 +20,12 @@ and every slot a model per family (`SLOTS`, `hooks/tezgah_models.py::SLOTS`). Th
 three tier workers - `tezgah-cheap`, `tezgah-standard`, `tezgah-frontier` - are
 generated in every tezgah root because routing needs no capability (`ROLES`,
 `hooks/tezgah_agents.py::ROLES`; their brief, `_worker_body`,
-`hooks/tezgah_agents.py::_worker_body`). A cheaper worker that meets work above its tier
+`hooks/tezgah_agents.py::_worker_body`). So are the five specialists:
+`tezgah-tester`, `tezgah-docs`, `tezgah-security`, `tezgah-ui` and
+`tezgah-researcher` (`hooks/tezgah_agents.py::SPECIALISTS`). A specialist's
+description names its slot from `AGENT_SLOT`. The tier a host shows and the
+model line it runs therefore cannot disagree, and `tezgah-agents --list` prints
+both. A cheaper worker that meets work above its tier
 answers `ESCALATE: <why>`, and the router restarts the task on `tezgah-frontier`
 with the original brief rather than handing the failed trajectory up: continuing a
 cheap trajectory on a frontier model was the most expensive option measured
@@ -30,10 +35,10 @@ cheap trajectory on a frontier model was the most expensive option measured
 
 | slot | agents | anthropic | zai (omp's own provider) | openai | any (OpenRouter id) |
 |---|---|---|---|---|
-| cheap | tezgah-cheap | Opus 5.5 @low | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | GLM-5.3 Flash |
+| cheap | tezgah-cheap, tezgah-tester | Opus 5.5 @low | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | GLM-5.3 Flash |
 | explore | omp's bundled `scout` | Opus 5.5 @medium | `zai/glm-5.3-flash` | GPT-6.1 Sol @low | DeepSeek V4.1 Flash |
-| standard | tezgah-standard | Opus 5.5 @medium | `zai/glm-5.3` | GPT-6.1 Sol @high | GPT-6.1 Sol @high |
-| frontier | tezgah-frontier, tezgah-reviewer | Opus 5.5 @high | `zai/glm-5.3` | GPT-6 Astra @high | Opus 5.5 @high |
+| standard | tezgah-standard, tezgah-docs, tezgah-ui | Opus 5.5 @medium | `zai/glm-5.3` | GPT-6.1 Sol @high | GPT-6.1 Sol @high |
+| frontier | tezgah-frontier, tezgah-reviewer, tezgah-security, tezgah-researcher | Opus 5.5 @high | `zai/glm-5.3` | GPT-6 Astra @high | Opus 5.5 @high |
 
 Why these, briefly. Inside the Anthropic family the lever is effort, not model:
 Opus 5.5 and Sonnet 5.5 read cache at the same $0.20 per 1M tokens, and on
@@ -56,7 +61,7 @@ invoices).
 | Claude Code | anthropic | the agent file's alias and `effort:` (`_model_lines`): an alias follows the provider and keeps the main session's variant, where a full id breaks on Bedrock, Vertex and a gateway (code.claude.com/docs/en/sub-agents) |
 | Codex | openai | `model` and `model_reasoning_effort` in `.codex/agents/*.toml` |
 | opencode | any | a selector `--refresh` found in `opencode models` for the slot's model under any configured provider (`resolve_opencode`); none found, no model line, so the agent inherits. The slot's effort rides the JSON agent config as `reasoningEffort` (opencode.ai/docs/agents) |
-| omp | anthropic when the session default is an Anthropic model, any otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **cross-family fallback chain** (`omp_overrides`): the mode's family first, then every other family this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>`, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`) |
+| omp | anthropic when the session default is an Anthropic model, any otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **fallback chain** (`omp_overrides`, `_chain`): the mode's family first, then what `fallback` in `~/.config/tezgah/config.json` allows (`tp.fallback_policy`) over the families this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - `vendor`, the default, keeps only the session vendor's model (`openrouter/anthropic/claude-opus-5.5:<effort>` behind an Anthropic session, `OPENROUTER_ID`), so a 429 never moves an Opus session's subagent onto GPT or GLM; `any` adds every other funded family, rotated per agent; `none` writes the first entry alone - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>` under the same `fallback` rule, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`); a changed `fallback` reaches omp on the next `tezgah-route --refresh` or `tezgah-setup --install` |
 | dsh | - | none: no model setting was found to write |
 
 The orchestrator agent keeps `model: inherit`: it is the main thread's own agent.
@@ -88,11 +93,12 @@ fixed:
    undone on. A 12-brief fixture pins it: 8 high-stakes briefs route to
    frontier, 4 near-miss controls do not (`tests/test_models.py`).
 2. Otherwise the brief - redacted with the ledger's own reader
-   (`redact`, `hooks/tezgah_integrity.py::redact`) - goes to Jev as one Choice over three tiers (`TIER_QUESTION`,
-   `hooks/tezgah_models.py::TIER_QUESTION`). Measured on 40 English briefs labelled by
+   (`redact`, `hooks/tezgah_integrity.py::redact`) - goes to the judge as one Choice over three tiers (`TIER_QUESTION`,
+   `hooks/tezgah_models.py::TIER_QUESTION`). The judge asks the session's own model first ([judge](judge.md)).
+   Measured with Jev on 40 English briefs labelled by
    the same session that wrote the rubric (2026-09-30, twice): under-route 0.025,
    accuracy 0.925 and 0.900, 392 ms median, about 656 input tokens per call; a
-   keyword rule on the same set under-routed 0.100.
+   keyword rule on the same set under-routed 0.100. The session model was not measured on that set.
 3. With no judgement (`judge-off`, no key, a failed call) `--phase` picks the tier
    from the static table (`PHASE_TIER`, `hooks/tezgah_models.py::PHASE_TIER`), and
    with no phase the middle tier is used.

package/docs/operations.md

@@ -23,7 +23,7 @@ before an install is considered.
 | `--refresh` | Re-render every always-on contract artifact of the armed hosts - the managed blocks of `CLAUDE.md`, Codex's `AGENTS.md` and omp's `RULES.md`, opencode's contract and skill routers - after a policy edit or a kill switch; prints the paths it refreshed, else `contract is current`. Before the first install there is no hash record, so it changes nothing (`refresh_contract`, `bin/tezgah-setup::refresh_contract`). |
 | `--uninstall` | Remove everything tezgah installed — per host the wiring it wrote, plus (a full run) the Claude plugin copy with its registry rows, the generated config state, the kill switches, the caches and the versioned install tree — then verify the removal; nonzero exit while anything tezgah wrote survives (`bin/tezgah-setup::verify_uninstall`, `bin/tezgah-setup::uninstall`). |
 | `--adopt` | Move pre-tezgah wiring aside instead of deleting it; alone it stops there, with `--install` it runs first (`bin/tezgah-setup::main`, `bin/tezgah-setup::adopt`). |
-| `--sync` | Copy this checkout over every installed Claude plugin [copy](glossary.md#plugin-copy) (`bin/tezgah-setup::sync`). Each copy is built in a staging tree beside the plugin cache and swapped in with two renames, its `.git` carried over, so a failed or killed sync leaves the previous copy whole (`bin/tezgah-setup::_swap`). Every copied file is 0644, or 0755 when the tree marks it executable, whatever mode the source has (`bin/tezgah-setup::_copy_normalised`). |
+| `--sync` | Copy this checkout over the Claude plugin [copy](glossary.md#plugin-copy) `installed_plugins.json` names, or over every copy when it names none (`bin/tezgah-setup::sync`, `bin/tezgah-setup::live_plugin_copies`). An older version dir is Claude's cache to collect, so it is left alone. Each copy is built in a staging tree beside the plugin cache and swapped in with two renames, its `.git` carried over, so a failed or killed sync leaves the previous copy whole (`bin/tezgah-setup::_swap`). Every copied file is 0644, or 0755 when the tree marks it executable, whatever mode the source has (`bin/tezgah-setup::_copy_normalised`). |
 | `--hook-entries` | Print, as JSON, the tezgah-owned hook entries this tree arms per armed host - what `tezgah update` asks the new tree for (`bin/tezgah-setup::hook_entries`). |
 | `--status [PATH]` | Print the armed/used checklist for PATH (default cwd) and stop — the same line as `bin/tezgah-status` (`bin/tezgah-setup::main`, `hooks/tezgah_context.py::health_lines`). It also prints the report's `config.json hosts (...) match the hosts wired (...)` row when the recorded list and the wiring on disk disagree (`hosts_row`), and nothing when they agree: install health is checked here, not only in a full report. |
 | `--agents [PATH]` | Regenerate PATH's per-repo subagent set (default cwd); outside a [root](glossary.md#root) it prints `no agents generated` (`bin/tezgah-setup::main`). |
@@ -158,7 +158,7 @@ or `default`), a common block (config, the code-graph binary, the consult option
 `orx`, `npx`, the artifacts dir, `git`, the manifest, a stale-contract line), one
 block per host, then the budget (`bin/tezgah-setup::report`). Each block is
 `host_checks_<host>` (`bin/tezgah-setup::HOST_CHECKS`), and those rows are the source of truth for
-"is this host armed" (`AGENTS.md:136-137`) — not the presence of a directory, and
+"is this host armed" (`AGENTS.md:147-148`) — not the presence of a directory, and
 not the status line. A row can read ` MISS ` too: claude's `plugin copy current`
 row fails on a machine with no copy at all, because an absent copy is not a
 current one (`bin/tezgah-setup::host_checks_claude`).
@@ -284,8 +284,8 @@ A **full** run also takes everything the wiring was serving from:
   `bin/tezgah-setup` plus the `current` flip (`remove_install_tree()`,
   `bin/tezgah-setup::remove_install_tree`).
 
-Kept in every run: the user's own files, every `.tezgah-bak` backup
-outside the config dir (the timestamped ones too), `~/.config/tezgah/adopted/` (the only copy of the
+Kept in every run: the user's own files, every host-file backup under
+`~/.config/tezgah/backups/` (the timestamped ones too), `~/.config/tezgah/adopted/` (the only copy of the
 predecessor wiring adopt moved aside), and every repository's `.tezgah/`
 research state. A **partial** run also keeps config.json and the install tree,
 because the hosts still armed read both at runtime, and says so. It also leaves
@@ -372,6 +372,7 @@ does not hold.
 | `tezgah-doctor` | nothing: sizes, session and event counts, whether opencode is running, the two context-hygiene settings, the `.codegraph` bytes and index presence per repository, and the three host state dirs (`bin/tezgah-doctor::collect`, `bin/tezgah-doctor::report`) |
 | `tezgah-doctor --clean` | vacuums opencode's database, and only when opencode is not running (`bin/tezgah-doctor::vacuum_db`, `bin/tezgah-doctor::main`); and deletes tezgah's own hook state not modified for `--retention-days` (default 30) - the ledgers under `evidence/`, `turns/`, `sessions/`, `classify.log`, `context-drops.log` and `debug.log`, in the cache and its sandbox fallback - keeping the current session's (`$TEZGAH_SESSION`) files whatever their age (`sweep_state`) |
 | `tezgah-doctor --coverage` | every tracked file the codegraph index does not hold, in two classes — a supported extension the index is missing, and a shebang-only script with no `.py` twin — with the file counts it read, so an empty result cannot read as "everything is covered" |
+| `tezgah-doctor --stack` | per host: the context files in load order, the skill dirs and which copy wins, the hook rows per event with their owner, the MCP servers, and every conflict; exits 1 on one ([hosts](hosts.md#precedence-what-each-host-loads-and-in-which-order), `hooks/tezgah_stack.py::report`) |
 | `tezgah-doctor --prune-sessions DAYS` | deletes sessions idle longer than DAYS through `opencode session delete`, then vacuums; skipped when opencode is running or its CLI is missing (`bin/tezgah-doctor::prune_sessions`, `bin/tezgah-doctor::main`) |
 
 `VACUUM` alone cannot shrink that database — its pages are all live — so
@@ -384,15 +385,18 @@ extension the engine has no parser for and an extensionless script it cannot key
 on at all. The extensionless case is why `bin/*` carries `.py` twins, and the
 report counts a tracked `bin/x` as covered when the index holds `bin/x.py`.
 
-## Opt-in taste capture
+## Opt-in taste: capture, learn, apply
 
-Phase 1 of a coding-taste learner stores the signals tezgah already receives.
-It learns nothing and injects nothing yet. It stays off until the user arms it
-with a `taste-on` file in `~/.config/tezgah/` (`enabled`,
-`hooks/tezgah_taste.py::enabled`). The off path costs two stats. Armed, it writes
-only into a repository that already has a `.tezgah/` directory. A `.no-taste`
-mark turns it off for one repository (`hooks/tezgah_context.py::repo_marks`).
-A workspace of repo-provided data gets nothing.
+Taste learns the user's coding preferences from their own corrections. It is
+taste-1's architecture as Command Code documents it, ported to tezgah (research
+line taste-architecture, design T1P). An LLM-free structured signal goes to a
+typed decision step, then a symbolic ledger, then a meta loop. It stays off
+until the user arms it with a `taste-on` file in `~/.config/tezgah/` (`enabled`,
+`hooks/tezgah_taste.py::enabled`). The off path costs two stats. Armed, it
+writes only into a repository that already has a `.tezgah/` directory. A
+`.no-taste` mark turns it off for one repository
+(`hooks/tezgah_context.py::repo_marks`). A workspace of repo-provided data gets
+nothing.
 
 Rows go to `<repo>/.tezgah/taste/signals.jsonl` through the ledger's own writer
 (`_write`, `hooks/tezgah_taste.py::_write`). A user turn adds a `prompt` row,
@@ -408,22 +412,69 @@ ledger row. A rollback therefore never reads it as a pre-state (`capture_after`,
 `hooks/tezgah_snapshot.py::capture_after`). A file outside the repository gets no
 after blob.
 opencode reaches the same call through a process (`noteTaste`,
-`hosts/opencode/plugins/tezgah.js:2310-2319`).
+`hosts/opencode/plugins/tezgah.js:2380-2390`).
 
 ```sh
 touch ~/.config/tezgah/taste-on               # arm; rm it to disarm
+bin/tezgah-taste learn                        # decide the new capture signals, update the ledger
+bin/tezgah-taste learn --from-transcripts     # bootstrap from this repo's omp/Claude history
+bin/tezgah-taste list                         # learnings: state, rule/hint, confidence, scope
+bin/tezgah-taste accept|reject|show ID        # the user's call on one learning
+bin/tezgah-taste edit ID --text "..."         # reword it; an edited line is never rewritten
+bin/tezgah-taste export                       # accepted learnings into AGENTS.md
+bin/tezgah-taste label; bin/tezgah-taste label ID preference   # the calibration sample
+bin/tezgah-taste calibrate                    # the bound a rule needs
+bin/tezgah-taste gate                         # the pooled before/after test
 bin/tezgah-taste mine --host omp --stats      # sessions, writes, prompts after a writing turn
-bin/tezgah-taste mine --out mined.jsonl       # one row per such prompt, redacted
-bin/tezgah-taste measure --samples S --labels L   # judge precision/recall against labels
-bin/tezgah-taste rate --in mined.jsonl        # preference corrections per writing turn
+bin/tezgah-taste measure --samples S --labels L [--typed]   # judge precision/recall
 ```
 
-`mine` reads the host transcripts already on disk, so it needs no capture. It
-reads omp's top-level session files and Claude's top-level transcripts whose cwd
-is under `--root` (`cmd_mine`, `bin/tezgah-taste::cmd_mine`). `measure` and `rate`
-send the sample text to the judge seam's provider ([judge](judge.md)), redacted
-first (`classify`, `bin/tezgah-taste::classify`). They use a fixed labelling rule
-(`RULE`, `bin/tezgah-taste::RULE`). Without a credential they send nothing.
+`learn` turns each prompt that followed a writing turn into one signal, and code
+builds it (`capture_signals`, `bin/tezgah-taste::capture_signals`). A signal
+holds the prompt, the files written, the agent's edits, and the user's own edit
+between two agent writes. That last one compares the after blob with the next
+write's pre-state, or with the file on disk (`user_diff`,
+`bin/tezgah-taste::user_diff`). `learn` asks TypeSafe for one typed decision per
+signal (`decide`, `bin/tezgah-taste::decide`, [judge](judge.md)). The decision
+names preference, defect or none. It picks one of eleven fixed categories and a
+scope. It also says how the signal relates to each learning held: supports,
+contradicts, narrows or unrelated. When another provider answers, `learn` writes
+the decision to `decisions.jsonl` as `unverified` and never applies it. A defect
+goes to `defects.jsonl` and never into the ledger.
+
+The ledger is `<repo>/.tezgah/taste/ledger.json`, plus
+`~/.config/tezgah/taste/ledger.json` for user-scope learnings
+(`hooks/tezgah_taste_ledger.py`). Confidence is (r+1)/(r+s+2) over supporting
+and contradicting evidence. Each piece counts at its decision probability, and
+the ledger forgets it per day at its scope's rate (`confidence`,
+`hooks/tezgah_taste_ledger.py::confidence`). A learning turns active in its
+second session. A contradiction flags an active learning `conflicted` and stores
+the contrary claim `quarantined`. Neither overwrites the other. `narrows` adds a
+narrower learning beside the broader one. When the user corrects an injected
+learning's category in the same session, that learning loses confidence
+(`apply`, `hooks/tezgah_taste_ledger.py::apply`). The hooks only read the
+ledgers. `learn`, `accept`, `reject` and `edit` rewrite them one at a time on
+this machine, under a lock on `~/.config/tezgah/taste/ledger.lock` (`locked`,
+`hooks/tezgah_taste_ledger.py::locked`). The lock spans every repository,
+because each command also rewrites the user ledger. A second one exits 2 and
+names the holder. Every taste row goes through the evidence ledger's locked
+writer (`append`, `hooks/tezgah_taste_ledger.py::append`).
+
+Session start injects the active learnings (`block`,
+`hooks/tezgah_taste_ledger.py::block`). A rule needs confidence 0.8 and a
+Clopper-Pearson lower bound of 0.8 on preference precision, measured on the
+labelled sample (`calibration`, `hooks/tezgah_taste_ledger.py::calibration`). A
+hint needs 0.6. A learning whose evidence paths are all gone is withheld. A
+write also carries the in-scope learnings it has not yet shown in the session,
+on every host's post-tool channel (`write_note`, `hooks/tezgah_taste.py::write_note`).
+`gate` compares preference corrections per writing turn before and after the
+first injection, by when each turn happened. Once both arms hold 980 turns and
+the after-rate is not lower
+at one-sided p < 0.1, it writes `gate.json` and injection stops (`gate`,
+`hooks/tezgah_taste_ledger.py::gate`). `mine` reads omp's top-level session
+files and Claude's top-level transcripts whose cwd is under `--root`
+(`cmd_mine`, `bin/tezgah-taste::cmd_mine`). `measure` and `rate` use a fixed
+labelling rule (`RULE`, `bin/tezgah-taste::RULE`).
 
 ## Tidying the lessons ledger
 
@@ -541,7 +592,11 @@ with `embed-m2v`. The fusion found it for 0.75 and 0.74, BM25 for 0.68.
 
 Reversible and safe to repeat: every link and settings key it writes is
 idempotent and re-created by `--install`. A write that changes a file first
-copies it to `<file>.<timestamp>.tezgah-bak`. The oldest of those copies is
+copies it to `<file>.<timestamp>.tezgah-bak`. A host file's copy goes under
+`~/.config/tezgah/backups/` (`bin/tezgah-setup::backup_base`). A host lists the
+files in its own dirs. tezgah's own state dir
+keeps its copies beside the file. `--install` moves the copies an older release
+left in a host dir (`bin/tezgah-setup::sweep_backups`). The oldest of those copies is
 always kept, beside the newest four (`backup()`, `BACKUP_CAP`). The oldest is
 the file before tezgah's first timestamped write, which is tezgah's own content
 for a file tezgah created. On an upgraded install the pre-tezgah copy is the
@@ -575,8 +630,8 @@ question instead of paying an agent to read a page: the analyze-app loop's snaps
 triage (`bin/tezgah-triage`), `bin/tezgah-docs` for a query its keyword index
 cannot place, and the prompt-path skill hint (`hooks/tezgah_skill_pick.py`), the
 one caller no shell row sees, `bin/tezgah-route`, the tier router
-([models](models.md)), and `bin/tezgah-taste`'s `measure` and `rate`
-([above](#opt-in-taste-capture)). All five go through the same stdlib-only seam,
+([models](models.md)), and `bin/tezgah-taste`'s `measure`, `rate` and `learn`
+([above](#opt-in-taste-capture-learn-apply)). All five go through the same stdlib-only seam,
 which returns `None` rather than raising because a hook may import it
 (`available()`, `hooks/tezgah_judge.py::available`); the request is
 one batched call, and the credential resolves per call (`ask()`,

package/docs/orca.md

@@ -0,0 +1,126 @@
+# Orca: what it owns, what tezgah owns, where they meet
+
+Orca is an IDE that runs agent sessions in its own terminals and worktrees.
+This page is for a maintainer or an agent working inside Orca. Read it when a
+session asks how tezgah and Orca share a machine. It describes Orca 1.4.221 and
+1.4.222 as observed on 2026-10-07. Each Orca claim names the command or file
+behind it, so a reader can check it again after a later release.
+
+## How a process knows it runs in Orca
+
+Every terminal Orca starts exports its own markers. The table lists the ones
+tezgah reads, as `env` printed them inside an Orca terminal.
+
+| Variable | Value shape | Read by |
+|---|---|---|
+| `ORCA_WORKTREE_ID` | `<repoId>::<absolute path>` of the Orca worktree | `hooks/tezgah_orca.py::session` |
+| `ORCA_TERMINAL_HANDLE` | `term_<uuid>`, the handle `orca terminal` commands take | `hooks/tezgah_orca.py::session` |
+| `ORCA_PANE_KEY` | `<tab>:<pane>` | `hooks/tezgah_orca.py::session` |
+| `TERM_PROGRAM` | `Orca` | `hooks/tezgah_orca.py::session` |
+| `ORCA_APP_VERSION` | `1.4.221` | `hooks/tezgah_orca.py::session` |
+| `ORCA_CLI_COMMAND` | the wrapper Orca exports for WSL sessions (orca-cli skill) | `hooks/tezgah_orca.py::cli` |
+| `ORCA_CLI_BIN_DIR` | `/Applications/Orca.app/Contents/Resources/bin` | `hooks/tezgah_orca.py::cli` |
+| `CODEX_HOME`, `ORCA_CODEX_HOME` | `~/Library/Application Support/orca/codex-accounts/<id>/home` | `hooks/tezgah_paths.py::HOST_DIRS` (CODEX_HOME only) |
+
+Orca also exports `ORCA_AGENT_HOOK_*` for its hook endpoint, port and token.
+It exports `ORCA_OMP_*` for its omp status extension. tezgah reads none of
+them and writes no `ORCA_*` variable. The marker set in `MARKERS` is the whole
+contract.
+
+A shell started from an Orca terminal inherits the variables. A subagent whose
+working directory is a raw worktree still reports the parent's
+`ORCA_WORKTREE_ID`. So the marker says "inside Orca", not "inside this
+checkout".
+
+## What Orca owns
+
+| Surface | What Orca keeps | Evidence |
+|---|---|---|
+| Worktrees | a git worktree plus a card (status, comment, lineage, links), by default under `~/orca/workspaces/<repo>/<name>` | `orca worktree create --help`; `orca repo show` lists paths under `~/orca/workspaces/tezgah/` |
+| Terminals | live PTYs with handles, read/send/wait | `orca terminal list --json` |
+| Agent sessions | agent type and state per pane, shown in `orca worktree ps` | `agents[].agentType`, `agents[].state` in `orca worktree ps --json` |
+| Orchestration | runs, tasks, dispatch, supervised workers, decision gates | `orca --help`, section Orchestration |
+| Embedded browser | tabs per worktree, snapshot and element refs | `orca --help`, section Browser Automation |
+| Artifacts | public HTML or Markdown links, off until a human enables them in Settings | `orca skills get orca-cli`, section Artifacts |
+| Codex accounts | one codex home per account, marked by `.orca-managed-home` | the account home's directory listing |
+| Its hooks | `~/.orca/agent-hooks/`, plus entries tagged `orca-agent-hook-form=1` in each managed codex `hooks.json` | the account home's `hooks.json` |
+| omp extensions | `orca-agent-status.ts`, `orca-prefill.ts` and `orca-titlebar-spinner.ts` in `~/.omp/agent/extensions/` | that directory's listing |
+
+The `orca-cli` skill is a stub. The full guide comes from the binary itself:
+`orca skills get orca-cli`. Run it before any Orca command a session has not
+run before.
+
+## What tezgah owns
+
+tezgah owns the contract text, the gate, the evidence ledger and the status
+line. It also owns its own hook entries in each host config
+([architecture](architecture.md), [hosts](hosts.md)). It does not create
+worktrees or terminals in code. A parallel slice is an instruction to the
+session: the `Tier 1` paragraph of `hooks/tezgah_policy.py::ORCHESTRATE`,
+mirrored in `skills/tezgah-contract/SKILL.md`, and the orchestrator agent body
+`hooks/tezgah_agents.py::_orch_body`.
+
+## Where they meet
+
+| Point | Behaviour | Code |
+|---|---|---|
+| Session start inside Orca | one `Orca:` line names the worktree and tells the session to use `orca worktree create`, `orca terminal create` and `orca worktree ps`. It reads env only and starts no process. | `hooks/tezgah_orca.py::context_line`, called from `hooks/tezgah_context.py::context_for` |
+| Slice checkouts | inside Orca, `orca worktree create --name <slug> --parent-worktree active --json`, else `git worktree add` | `hooks/tezgah_policy.py::ORCHESTRATE`, `hooks/tezgah_agents.py::_orch_body` |
+| Tracking | `tezgah-status --orca` lists each checkout Orca tracks (card, state, live terminals, agent states) and each git worktree Orca does not list | `bin/tezgah-status::print_orca`, `hooks/tezgah_orca.py::checkouts` |
+| Install report | `tezgah-setup --status` prints one `orca:` line where Orca is present. The line names the runtime, the terminal and an Orca-managed CODEX_HOME. | `hooks/tezgah_orca.py::summary`, `bin/tezgah-setup::main` |
+| Codex hooks | tezgah drops only entries holding `tezgah` and appends its own groups, so Orca's entries stay | `bin/tezgah-setup::install_codex` |
+| Cursor hooks | the same merge | `bin/tezgah-setup::install_cursor` |
+| Claude status line | tezgah's wrapper runs Orca's `~/.orca/agent-hooks/claude-statusline.sh` first and appends its own segment | `statusline.py::ORCA`, `bin/tezgah-setup::wire_claude_statusline` |
+| Codex rules file | Orca links the account home's `AGENTS.md` to `~/.codex/AGENTS.md`. tezgah writes the managed block through that link with a plain `open`, so the link stays. | `bin/tezgah-setup::set_managed_md` |
+
+### The collision this fixes
+
+On 2026-10-07 the tezgah repository had eleven git checkouts and Orca listed
+one. `git worktree list` printed the main checkout and ten under
+`~/Projects/tezgah-wt/`, and `orca worktree list --repo path:<main> --json`
+returned `totalCount: 1`. The ten came from raw `git worktree add`, so Orca
+showed no card, terminal or agent state for them. `tezgah-status --orca` now
+prints that gap.
+
+A smoke run on the live runtime closed the loop. It ran `orca worktree create
+--name tezgah-orca-smoke --parent-worktree active --setup skip --json` from the
+main checkout. `tezgah-status --orca --json` then listed the new checkout as
+tracked, with one terminal. `orca worktree rm --force` removed it, its branch
+included.
+
+### CODEX_HOME inside Orca
+
+Inside Orca, CODEX_HOME names an Orca-managed account home. A `tezgah-setup
+--install` run from an Orca terminal arms that home, and a run from another
+terminal arms `~/.codex` (`hooks/tezgah_paths.py::HOST_DIRS`). On this machine
+both homes carry tezgah's seven hook events. The Orca home keeps
+Orca's own entries beside them. Orca also keeps
+`.orca-hook-trust-provenance.json` there, keyed by event and entry index.
+tezgah appends after Orca's entries, so Orca's index does not move. Whether
+Orca re-trusts a changed tezgah entry on its own is not verified.
+
+## What the Orca CLI does not offer
+
+- No command adopts an existing raw git worktree as an Orca worktree. The
+  `Worktrees` section of `orca --help` lists `list`, `show`, `current`,
+  `create`, `set`, `rm` and `ps` only. `orca repo set --repo <sel>
+  --external-worktree-visibility show` makes non-Orca worktrees visible in the
+  sidebar. It does not give them cards.
+- An agent cannot turn on artifact publishing. A human enables it in Settings
+  (the `Artifacts` section of `orca skills get orca-cli`).
+
+## Tests
+
+`tests/test_orca.py` runs with no real Orca. A fake `orca` on disk answers
+`worktree ps` and `status`, and every marker is a fixture. `tests/support.py`
+strips the developer's own `ORCA_*` markers and `TERM_PROGRAM=Orca`, and pins
+`TEZGAH_ORCA_BIN` to a missing path. Without that, a suite run inside Orca
+would reach the live runtime.
+
+## Source of truth
+
+- `hooks/tezgah_orca.py`: detection, CLI resolution, the listing and both report lines
+- `hooks/tezgah_context.py`: where the session line joins the session-start block
+- `hooks/tezgah_policy.py`, `skills/tezgah-contract/SKILL.md`, `hooks/tezgah_agents.py`: the slice rule
+- `bin/tezgah-status`, `bin/tezgah-setup`: the two report surfaces
+- `tests/test_orca.py`, `tests/support.py`