dsh-autotier 0.1.0

package/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md
+
+Standalone DeepSeek Harness plugin repository (`dsh-autotier`). Development
+follows the dsh-plugin-guide skill and the official plugin contract; this file
+records repo-local decisions.
+
+## Layout
+
+- `src/index.ts` — function-plugin contract (`name`/`inject`/`Config`/`apply`; NO
+  default export). Injects `settings`, `llm`, `tools`, `commands` and `sessions`
+  (plural — the host service is `ctx.sessions`); `agents`, `planMode`,
+  `sessionProjections` and `sandboxPolicy` are read with `ctx.get()` and degrade
+  when absent.
+- `src/schema.ts` — the Schemastery schema and the raw (partial) config
+  interfaces it resolves. Kept free of executable logic so a schema module never
+  mixes function values into its declarations (the plugin-doctor K4 rule).
+- `src/config.ts` — the explicit `resolveConfig` judge (no hidden `?? default`
+  in callers) and the resolved interfaces. Object defaults are COMPLETE objects;
+  the adapter-owned effort vocabulary is `off | low | high | max` (there is no
+  `medium`).
+- `src/service.ts` — `ctx.autotier` (`status()` and the live settings scope).
+- `src/types.ts` — shared vocabulary (tier ids, effort ids, routing modes,
+  scenarios, route/status shapes).
+- `tests/` — vitest over the REAL published `0.1.2-rc.1` host packages
+  (`Context`, `SessionStore`, `SystemPrompt`, `ToolRuntime`, `CommandRuntime`,
+  in-memory `SettingsProvider`) plus one real Loader composition.
+
+## Hard rules applied here
+
+- **Tier landing seam**: `agent/request` waterfall, registered at load time on
+  the root scope with `{ prepend: true }`; always `await next()` exactly once and
+  return a replacement `LlmCallConfig` (provider/model/effort), preserving the
+  sampling scalars (`temperature`, `maxTokens`, `stop`) the session already
+  chose. Never return `undefined` from the listener.
+- **`inject` names are verified against the checkout**, not guessed: `sessions`
+  (plural), `tools`, `commands`, `llm`, `settings`. A wrong name leaves the
+  plugin PENDING forever.
+- **No `agent.options` mutation**: agent options are readonly and read cyclically
+  by the loop; the request waterfall is the only supported landing.
+- **Guard is defence in depth**: it never weakens `dsh-defend`, the approval
+  service or the sandbox policy. A guard that throws escalates the call instead
+  of allowing it.
+- **Fail loud**: invalid configuration throws at mount or at the settings write,
+  never silently disables routing.
+- **Model-visible ⟺ logged**: the only model-visible content is the `/tier`
+  output and the guard's corrective denial. No custom session event is appended
+  (that vocabulary is fail-closed on `0.1.2-alpha.1` and later); the trail is the
+  plugin logger plus the live `autotier/tier-changed` bus event, and the sole
+  append is the `plan/mode` fallback when the plan-mode service is absent.
+- **Registration is an effect**: every listener, command, tool, service and
+  settings namespace rides the plugin fiber and disappears on dispose.
+
+## Config
+
+Schema in `src/schema.ts` (judged by `src/config.ts`); `cordis.patch.yml`
+documents the same keys inline; the five-language READMEs carry the user-facing
+table.
+`package.json#dshWorkshop` is the omdsh-workshop-package/v1 intake manifest
+(declarations only — evidence paths stay null until their adapter runs).
+
+## Build
+
+`typescript` + `tsdown` are regular `dependencies` (the git channel's `prepare`
+builds with production dependencies alone). `scripts/prepare.mjs` wipes `lib/`,
+emits tsc declarations into `lib/types`, then runs tsdown (tsdown `clean` stays
+OFF so the declarations survive). `pnpm-workspace.yaml` declares
+`allowBuilds: { esbuild: true }`.
+
+## Checks
+
+`pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build &&
+pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm pack`. The
+plain `typecheck` resolves the local harness checkout's type faces through
+tsconfig `paths` (four levels up to `D:\deepseek-harness`); `typecheck:ci`
+resolves the npm-published `0.1.2-rc.1` faces (no paths) and is what CI runs —
+keep both green.
+
+## Release
+
+`node scripts/release.mjs <x.y.z>` bumps `package.json`, stamps the CHANGELOG
+`[Unreleased]` section, re-runs the gate, commits, and tags `v<x.y.z>` locally —
+never pushes. Push with `git push origin main --follow-tags`; the release
+workflow then gates again, publishes npm with provenance (secret `NPM_TOKEN`),
+and creates the GitHub Release from the CHANGELOG section.
+
+## Docs
+
+- Five-language READMEs (`README.md`, `README.zh.md`, `README.es.md`,
+  `README.pt.md`, `README.hi.md`) — keep all five in sync; the English file is
+  the source of truth.
+- GitHub topics mirror `package.json` keywords.
+- `THIRD_PARTY_NOTICES.md` records the MIT-licensed guard-rule port from
+  `dsh-tier-router`.

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- **Automatic tier routing on the official seam.** A load-time `agent/request`
+  waterfall listener registered on the root scope with `{ prepend: true }`
+  replaces the provider/model/effort triple while preserving the sampling
+  scalars the session already chose (`temperature`, `maxTokens`, `stop`). It
+  always awaits `next()` exactly once and never returns `undefined`.
+- **Deterministic intent gate (zero tokens).** Declarative rule table
+  (`intent.rules`: patterns/tools/cwd, priority-ordered), explicit-intent
+  patterns, bilingual keyword scoring with word boundaries and a CJK
+  co-occurrence rule, structural signals (token bands, tool calls, code fences,
+  hard hints, turn depth), image and long-text short-circuits, and the
+  attempt-first middle band (shipped disabled).
+- **Low-confidence judge.** Only a turn below `intent.ruleThreshold` calls a
+  cheap model, never on cooldown, and abstains after
+  `intent.judge.unavailableSkip` consecutive failures.
+- **Fingerprint posteriors.** Per-shape `{cheap,strong}` win-rate counters with
+  a Wilson lower bound, ε-greedy exploration, half-life decay and an LRU cap.
+  Labels come from terminal turn outcomes only, never from the router's own
+  judge call.
+- **Decision state machine.** Precedence: session override → active escalation →
+  plan mode → fallback chain → declarative rule → posterior → classifier, with a
+  double-threshold hysteresis (`toStrong` / `toCheap`) that damps tier flapping.
+- **Plan-mode handoff.** A complex instruction opens plan mode through the
+  optional `planMode` service, falling back to an appended `plan/mode` event when
+  the service is not reachable; leaving plan mode returns the session to the
+  cheap tier.
+- **High-risk guard on `tools/pre-execute`.** A deterministic, tier-conditional
+  denial covering recursive-force deletes (including `sh -c` wrapper payloads the
+  upstream rule set misses), destructive commands, credential paths and the
+  configured `guard.protectedPaths` review surfaces. A guard that throws
+  escalates to the strong tier instead of allowing the call.
+- **Failure escalation and fallback chains.** Same-signature recurrence counting
+  within a window raises the tier for a TTL; the effort-first ladder raises the
+  current model's effort before paying for a model switch. Permanent route
+  failures switch the fallback chain immediately, transient failures wait for
+  `dsh-llm-retry` exhaustion (this listener is registered after it on purpose).
+- **Surfaces.** `/tier auto|strong|cheap|off|status`, the read-only `tier_status`
+  and `tier_route` tools, the `ctx.autotier` service (`status`, `catalog`), the
+  `autotier/route` serial veto event, the `autotier/tier-changed` emit event, and
+  a host+wire `autotier` session projection folding `request/header` and
+  `plan/mode`.
+- **Configuration.** A Schemastery settings namespace (`autotier`) with
+  save-time cross-field validation: tier landings, fallback chains, intent
+  thresholds, rules, judge, scenarios, cost mode, guard and escalation switches.
+  Reasoning effort accepts exactly the adapter vocabulary
+  `off | low | high | max`; the default strong model is `deepseek-v4-pro` and the
+  default cheap model is `deepseek-v4-flash`.
+- Five-language READMEs, `cordis.patch.yml` with every key documented inline,
+  Apache-2.0 license, security policy and third-party notices (including the
+  MIT-licensed guard-rule port and its deliberate deltas).
+- CI workflows: `ci.yml` (typecheck against the checkout faces, `typecheck:ci`
+  against the published `0.1.2-rc.1` faces, tests, coverage, lint, README sync,
+  build, artifact and self-containment verification), `compat.yml` (real profile
+  install, `--dump-config` activation assertion, keyless headless smoke,
+  uninstall rollback), `release.yml` (npm provenance + GitHub Release),
+  `scorecard.yml` and `plugin-doctor.yml`.
+- Test suites (153 cases): config schema and cross-field resolution, the
+  function-plugin contract, fiber-disposal lifecycle over the real host
+  services, a real Loader composition over a temporary `cordis.yml`, the guard
+  rule table with a 5,909-command upstream-equivalence harness (the port itself
+  carries 30 cases, 14 of them case-for-case upstream ports), the classifier
+  and posterior matrix, the decision state machine, and a real AgentLoop
+  integration suite covering simple/complex routing, the `/tier` override,
+  escalation after two same-signature failures, fallback-chain switching and the
+  tier projection.
+
+### Known limitations
+
+- No browser half yet: the Settings card and composer tier pill are planned for
+  v0.2; the host surface they need (`ctx.autotier.status()`/`catalog()`) ships.
+- Fingerprint posteriors are in-memory and reset on restart.
+- The attempt-first middle band ships disabled until the calibration corpus and
+  its metric gate land.
+- A model picked in the GUI is not detected automatically; use
+  `routingMode: delegated` or `/tier off`.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.es.md

@@ -0,0 +1,247 @@
+# dsh-autotier
+
+Enrutamiento automático por niveles de modelo para DeepSeek Harness: entra una
+instrucción del usuario y sale una decisión de nivel — sin cambiar de modelo a
+mano.
+
+La intención compleja (arquitectura, planificación, depuración, ingeniería de
+varios pasos) se planifica en el nivel **strong** y luego se implementa en el
+nivel **cheap**. La intención simple (preguntas, recuperación, tareas por lotes,
+trabajo diario) se diseña e implementa directamente en el nivel **cheap**.
+Mientras el nivel cheap ejecuta, las llamadas de herramienta de alto riesgo son
+denegadas por un guard determinista, y los fallos repetidos escalan al nivel
+strong con un TTL de retorno.
+
+- **Repositorio oficial**: <https://github.com/PerryLink/dsh-autotier>
+- **npm**: `dsh-autotier` (nombre simple, sin scope)
+
+## Compatibilidad
+
+| Harness | Estado |
+|---|---|
+| `@deepseek-ai/dsh` `0.1.2-rc.1` | compatible (es lo que CI verifica y lo que instala el flujo compat) |
+| `0.1.5-alpha.1` (la línea actual del checkout) | verificado por tipos contra sus caras publicadas; el smoke de extremo a extremo corre en `0.1.2-rc.1` |
+| `@deepseek-ai/cordis` `^4.0.2`, `@deepseek-ai/schemastery` `^3.18.2` | base de peers |
+
+El plugin vive solo en el plano host y no necesita un preset propio: la fila host
+se aplica a todas las sesiones. Una sección de prompt en *tu* preset es opcional
+y solo hace visibles las decisiones al modelo (véase [Instalación y desinstalación](#instalación-y-desinstalación)).
+
+## Qué obtienes
+
+- **Puerta de intención** — cada turno se clasifica con señales deterministas
+  (texto del mensaje, nombres de herramientas, presencia de imágenes, longitud de
+  la conversación). La capa de reglas decide sin gastar tokens cuando tiene
+  confianza; solo un turno de baja confianza llama al modelo juez barato, y
+  nunca dentro del cooldown.
+- **Aterrizaje en el seam oficial** — la decisión se aplica en la waterfall
+  `agent/request` devolviendo una terna provider/model/effort de reemplazo. Los
+  escalares de muestreo ya elegidos por la sesión (`temperature`, `maxTokens`,
+  `stop`) se conservan.
+- **Traspaso a modo plan** — una instrucción compleja entra en modo plan en el
+  nivel strong; al salir vuelve al nivel cheap para implementar.
+- **Guard de alto riesgo** — durante la ejecución cheap, los comandos
+  destructivos (`rm -rf`, `sudo`, `mkfs`, `git push --force`, escritura de
+  ficheros de credenciales, …) se deniegan con un mensaje correctivo que pide
+  escalar.
+- **Escalado por fallos** — los fallos repetidos (opcionalmente con la misma
+  firma) elevan el nivel durante un TTL; un fallo de modelo/ruta recorre la
+  cadena de fallback configurada.
+- **Válvulas manuales** — `/tier auto|strong|cheap|off` y las herramientas
+  `tier_status` / `tier_route`. Ajustar `routingMode: delegated` (o `/tier off`)
+  detiene el enrutamiento para una sesión que debe conservar su propio modelo.
+- **Servicio `ctx.autotier`** — una superficie de lectura (`status`) más la
+  waterfall de veto `autotier/route` y el evento `autotier/tier-changed`, para
+  que otros plugins observen o anulen una decisión.
+
+## Inicio rápido
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+Luego inicia (o reinicia) el harness. La fila se añade a tu
+`cordis.patch.yml`; el enrutamiento empieza en el siguiente turno.
+
+## Instalación y desinstalación
+
+**Canal npm**
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+**Canal git**
+
+```bash
+git clone https://github.com/PerryLink/dsh-autotier.git
+cd dsh-autotier && pnpm install && pnpm run build
+dsh plugin --profile web add .
+```
+
+**Sección de prompt opcional en el preset.** El router funciona sin ella. Para
+que el modelo sepa en qué nivel corre, añade una fila a *tu* preset
+(`docs/preset-row.md` tiene el bloque exacto):
+
+```yaml
+- insert:
+    - id: autotier-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      # sections: [...]  — véase docs/preset-row.md
+```
+
+**Desinstalación**
+
+```bash
+dsh plugin --profile web remove dsh-autotier
+```
+
+La fila, su namespace de settings, su comando, sus herramientas y sus listeners
+se eliminan con el plugin; no se escribe nada fuera del documento de settings.
+
+## Configuración
+
+Cada clave se valida al cargar; un valor inválido falla de forma ruidosa en vez
+de desactivar el enrutamiento en silencio. El `cordis.patch.yml` de este
+repositorio documenta las mismas claves en línea.
+
+| Clave | Por defecto | Significado |
+|---|---|---|
+| `tiers.strong.provider` | `deepseek-official` | Provider del nivel de planificación/revisión. |
+| `tiers.strong.model` | `deepseek-v4-pro` | Id de catálogo del modelo strong. |
+| `tiers.strong.effort` | `high` | Vocabulario del adaptador `off` \| `low` \| `high` \| `max`. |
+| `tiers.strong.followSession` | `false` | `false` = el effort de este nivel anula el de la sesión. |
+| `tiers.strong.fallback` | `[]` | Aterrizajes provider/model ordenados si el nivel no está disponible. |
+| `tiers.cheap.provider` | `deepseek-official` | Provider del nivel de implementación. |
+| `tiers.cheap.model` | `deepseek-v4-flash` | Id de catálogo del modelo cheap. |
+| `tiers.cheap.effort` | `low` | Vocabulario del adaptador `off` \| `low` \| `high` \| `max`. |
+| `tiers.cheap.followSession` | `true` | `true` = hereda el effort de la sesión y gana la elección explícita. |
+| `tiers.cheap.fallback` | `[]` | Aterrizajes provider/model ordenados si el nivel no está disponible. |
+| `tiers.vision.provider` | `deepseek-official` | Provider para turnos con imágenes. |
+| `tiers.vision.model` | `deepseek-v4-flash-vision-exp` | El único modelo del catálogo con modalidad de imagen. |
+| `intent.ruleThreshold` | `0.7` | Confianza a partir de la cual la capa de reglas decide sola. |
+| `intent.attemptBand.enabled` | `false` | Empezar la banda media en cheap y escalar ante una señal. |
+| `intent.attemptBand.tauLow` | `0.45` | Límite inferior de la banda attempt-first. |
+| `intent.hysteresis.toStrong` | `0.8` | Puntuación que cambia un turno cheap a strong. |
+| `intent.hysteresis.toCheap` | `0.6` | Puntuación por debajo de la cual un turno strong vuelve a cheap. |
+| `intent.rules` | `[]` | Tabla declarativa de reglas (`when.patterns` / `when.tools` / `when.cwd`, `tier`, `priority`). |
+| `intent.judge.enabled` | `true` | Permitir el juez de baja confianza. |
+| `intent.judge.model` | `''` | Id del modelo juez; vacío = primer modelo del catálogo que contenga `flash`. |
+| `intent.judge.temperature` | `0` | Temperatura de muestreo del juez. |
+| `intent.judge.maxTokens` | `16` | Límite de salida del juez (responde con una palabra). |
+| `intent.judge.cooldownMs` | `30000` | Separación mínima entre dos llamadas al juez. |
+| `intent.judge.timeoutMs` | `2000` | Tiempo límite de la llamada al juez. |
+| `intent.judge.unavailableSkip` | `2` | Fallos consecutivos tras los que el turno omite al juez. |
+| `intent.scenarios` | todos `true` | Interruptores por escenario: `coding`, `review`, `planning`, `retrieval`, `batch`, `daily`, `longText`, `multimodal`. |
+| `intent.costMode` | `balanced` | Arbitraje en la ambigüedad: `cost-first` \| `quality-first` \| `balanced`. |
+| `guard.enabled` | `true` | Activar el guard determinista de alto riesgo. |
+| `guard.tiers` | `[cheap]` | Niveles que el guard protege. |
+| `guard.whitelist` | `[]` | Comandos, herramientas o prefijos de ruta que nunca disparan el guard. |
+| `guard.protectedPaths` | `['.dsh','AGENTS.md','package.json','.github/workflows']` | Superficies de automodificación que fuerzan revisión strong. |
+| `guard.interopDefend` | `auto` | Relación con `dsh-defend`: `auto` audita la convivencia, `none` calla. |
+| `escalation.threshold` | `2` | Fallos dentro de la ventana que elevan el nivel. |
+| `escalation.windowMs` | `60000` | Ventana de conteo de fallos. |
+| `escalation.ttlMs` | `180000` | Cuánto dura un escalado. |
+| `escalation.fallbackTtlMs` | `300000` | TTL usado tras tomar un aterrizaje de fallback. |
+| `escalation.signature` | `true` | Contar recurrencias de la misma firma en vez de cada fallo. |
+| `routingMode` | `auto` | `auto` \| `strong` \| `cheap` \| `delegated` \| `off`. |
+
+Todas las claves se pueden editar en caliente desde el namespace de settings
+`autotier` (`$DSH_HOME/settings.yaml`); una escritura que viole un requisito
+cruzado se rechaza al guardar y la última política válida sigue vigente.
+
+## Herramientas y superficies
+
+| Superficie | Tipo | Propósito |
+|---|---|---|
+| `/tier` | comando | `auto` \| `strong` \| `cheap` \| `off` \| `status`; anulación por sesión. |
+| `tier_status` | herramienta | Nivel actual, modo, TTL de escalado y estado del guard. |
+| `tier_route` | herramienta | Enruta una intención en seco, sin enviar petición. |
+| `ctx.autotier` | servicio | Superficie `status()` para otros plugins. |
+| `autotier/route` | evento serial | Terceros pueden vetar el nivel propuesto. |
+| `autotier/tier-changed` | evento emit | Observabilidad cuando cambia el nivel efectivo. |
+
+## Permisos y datos
+
+- **Ficheros** — el plugin no lee ni escribe nada salvo a través del servicio
+  compartido de settings (el namespace `autotier`).
+- **Red** — el único tráfico saliente es la llamada al juez, que pasa por la ruta
+  normal de `ctx.llm` y el provider configurado.
+- **Registro de sesión** — el plugin no añade eventos de sesión propios. El rastro
+  de enrutamiento es el logger del plugin más el evento vivo
+  `autotier/tier-changed`; el único añadido es el `plan/mode` de reserva cuando el
+  servicio de modo plan no está disponible. Los tipos de evento propios son
+  fail-closed desde `0.1.2-alpha.1`, así que no se escribe ningún registro
+  duradero del plugin.
+- **Secretos** — este plugin no lee, registra ni almacena credenciales.
+
+## Límites de seguridad
+
+- El guard es **defensa en profundidad**, no una sandbox. Deniega los patrones que
+  conoce en el nivel cheap y nunca debilita `dsh-defend`, el servicio de
+  aprobación ni la política de sandbox. Mantenlos activos.
+- El guard solo protege los niveles de `guard.tiers` (cheap por defecto). Un turno
+  strong no se bloquea por diseño: el modelo strong es el revisor.
+- Si el guard mismo lanza, la llamada se escala a strong en lugar de permitirse —
+  un guard roto no debe convertirse en una puerta abierta.
+- `/tier off` desactiva el enrutamiento por completo; el harness se comporta
+  exactamente como antes de instalar el plugin.
+
+## Limitaciones conocidas
+
+- La capa de reglas es determinista y por tanto finita: una frase nueva para una
+  petición compleja puede empezar en cheap y escalar solo tras un fallo o una
+  denegación del guard. La llamada al juez cubre el medio de baja confianza.
+- El escalado es por agente y en memoria; un reinicio del harness vuelve a `auto`.
+- Cambiar de nivel reinicia la caché de prompt del provider para esa petición, así
+  que las sesiones muy activas pueden ver un pequeño coste de fallo de caché en el
+  turno de cambio; los umbrales de histéresis existen para que eso sea raro.
+- El plugin enruta peticiones de conversación. La compactación y la generación de
+  títulos son seams separados del host; alinea sus propios ajustes de modelo con
+  el nivel cheap si quieres el mismo perfil de coste (`docs/supporting-lanes.md`).
+- `followSession: true` en el nivel cheap significa que una elección explícita de
+  modelo en la sesión gana; en ese caso el nivel cheap no puede imponer el suyo.
+- **Aún no hay tarjeta de Settings ni píldora del compositor.** El enrutamiento es
+  totalmente automático y la superficie host (`ctx.autotier.status()` /
+  `catalog()`, `/tier`, `tier_status`, `tier_route`) está completa; la mitad de
+  navegador está prevista para v0.2.
+- **Un modelo elegido en la GUI no se detecta automáticamente.** Usa
+  `routingMode: delegated` o `/tier off` para detener el enrutamiento.
+- **Las posteriores por huella viven en memoria** y se reinician al reiniciar.
+- **La banda media attempt-first llega desactivada** hasta que exista el corpus
+  de calibración (v0.2).
+
+## Desarrollo
+
+```bash
+pnpm install
+pnpm run typecheck      # contra las caras de tipo del checkout local del harness
+pnpm run typecheck:ci   # contra las caras publicadas 0.1.2-rc.1 (lo que ejecuta CI)
+pnpm test
+pnpm run build
+pnpm run verify:self-contained
+pnpm run verify:artifacts
+pnpm pack
+```
+
+`pnpm run build` emite `lib/types` (declaraciones tsc) y `lib/index.js` (bundle
+tsdown). Las pruebas usan directamente los paquetes host publicados — `Context`
+real, servicios reales de session/tools/commands/settings — más una composición
+real del Loader sobre un `cordis.yml` temporal.
+
+## Temas
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `router`,
+`model-tier`, `cost`, `auto`.
+
+## Contribuidores
+
+PerryLink. Issues y pull requests en
+<https://github.com/PerryLink/dsh-autotier/issues>.
+
+## Licencia
+
+Apache-2.0. Véase [LICENSE](./LICENSE) y
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).