minima-cli 0.13.0__tar.gz → 0.13.1__tar.gz

{minima_cli-0.13.0 → minima_cli-0.13.1}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Minima are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.13.1] - 2026-07-21
+
+### Fixed
+- **Plan-mode fallback pool** (TUI, #204): plan mode's premium model-pool
+  restriction only covered the council path — with `MINIMA_TUI_GROUND_TRUTH=0`
+  (or a failed council setup) plan-mode turns ran the normal loop over the full
+  candidate pool, so a cheap/small model could end up doing the planning. The
+  sessionless fallback now routes with the same premium hard pool +
+  `phase:plan` tag as the council's planner turn, with the same loud failure
+  when the policy is active but no premium model is runnable. The restriction
+  is now a property of the mode, not of the council.
+
 ## [0.13.0] - 2026-07-21
 
 The Mubit reinforcement train: mubit-sdk 0.13.0 adopted end to end, every free

{minima_cli-0.13.0 → minima_cli-0.13.1}/CLAUDE.md

@@ -87,7 +87,7 @@ Everything external is behind a Protocol so it can be faked in tests. The server
 
 `MinimaAgent.promptRouted(task)` = **route** (`src/minima/router.ts` → `POST /v1/recommend`) → **run** (agent loop in `src/agent/`, streams the model, executes tools, before/afterToolCall hook stacks, abort via AbortSignal) → **judge** (`src/minima/judge.ts`, abstains unless `MINIMA_LLM_JUDGE=1`) → **feed back** (`POST /v1/feedback` with realized cost). Layers: `src/ai/` (multi-provider LLM API + `faux` test provider) · `src/agent/` (loop, tools, hooks) · `src/minima/` (router, runtime, meter, budget, spawn/sub-agents, ground truth) · `src/tools/` (bash/edit/read/write/grep/todowrite/websearch…) · `src/tui/` (Ink app) · `src/db/` (SQLite spine).
 
-**Ground-Truth verification spine** (shipped 2026-07, `docs/ground-truth-build-guide.md`): **ON by default** since Phase 0b (opt out with `MINIMA_TUI_GROUND_TRUTH=0`). Plan steps carry `verify` shell commands, the harness runs them (baseline → done-gate red→green), verdicts land in the `gates` ledger (migrations v3–v5), a confidence tier drives the UI (🟢 glide / 🟡 flag / 🔴 stop), and grounded outcomes stamp `routing_decisions` for deterministic-over-judge feedback. Green-tier gate verdicts are the harness's honest label source (`evidence_source="gate"` — the only origin that may claim verified-in-production); a sampled LLM judge (`MINIMA_JUDGE_SAMPLE`, default 15% of ungated turns, `MINIMA_LLM_JUDGE=0` disables) labels the rest; everything else is cost/latency telemetry. `/plan` (planner persona + design council + `GROUND_TRUTH.md` output) is part of this spine. Anything gated on ground truth belongs behind `config.groundTruth`, never behind prompt text.
+**Ground-Truth verification spine** (shipped 2026-07, `docs/ground-truth-build-guide.md`): **ON by default** since Phase 0b (opt out with `MINIMA_TUI_GROUND_TRUTH=0`). Plan steps carry `verify` shell commands, the harness runs them (baseline → done-gate red→green), verdicts land in the `gates` ledger (migrations v3–v5), a confidence tier drives the UI (🟢 glide / 🟡 flag / 🔴 stop), and grounded outcomes stamp `routing_decisions` for deterministic-over-judge feedback. Green-tier gate verdicts are the harness's honest label source (`evidence_source="gate"` — the only origin that may claim verified-in-production); a sampled LLM judge (`MINIMA_JUDGE_SAMPLE`, default 15% of ungated turns; `MINIMA_JUDGE_SAMPLE=0` disables, `MINIMA_LLM_JUDGE=1` forces every turn) labels the rest; everything else is cost/latency telemetry. `/plan` (planner persona + design council + `GROUND_TRUTH.md` output) is part of this spine. Anything gated on ground truth belongs behind `config.groundTruth`, never behind prompt text.
 
 **Memory ledger** (Track B of the memory spine, default ON; opt out with `MINIMA_TUI_MEMORY=0`): curated cross-session memory in SQLite (`memories`/`memory_events`/`memory_jobs`, migration v12). Active + pinned rows project into each turn's system prompt for the lead agent only (hard char cap, ranked pinned > gate-cited > recency; every distinct injected set is audited as an `inject` memory_event so "what the model saw" is replayable). Managed via `/memory` (list · add · pin/confirm/reject · delete = bi-temporal invalidate, never DELETE). Only the harness/user writes memories — the model has **no memory-write tool** (Letta split); keep it that way. The **scribe** (`src/minima/memory_scribe.ts`) is the sole automated writer: a background curator fed by SQL over the ledger (gate flips, verified failures, user corrections, judge/gate disagreements — never the transcript), recurrence-gated (a pattern must recur before it earns the one LLM extraction call, which routes through Minima with `tags=["memory:extract"]` and books its spend like judge spend), reconciled mem0-style (ADD/UPDATE/NOOP; rejected rows never resurrected), and provenance-gated (only gate-cited candidates auto-activate; the rest await `/memory confirm`). Triggers (session end, 90s quiet timer, startup leftovers) only enqueue `memory_jobs` rows; a crash-safe drain runs them.
 

{minima_cli-0.13.0 → minima_cli-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.13.0
+Version: 0.13.1
 Summary: Minima CLI: cost-aware LLM model routing — recommend cheaper models, backed by Mubit memory.
 Project-URL: Homepage, https://docs.minima.sh
 Project-URL: Documentation, https://docs.minima.sh

{minima_cli-0.13.0 → minima_cli-0.13.1}/docs/README.md

@@ -22,6 +22,12 @@ your real LLM call.
   guidance.
 - **[Python Client SDK](client-sdk.md)** — the `minima_client` package: sync/async clients
   and the zero-code `autocapture` intake.
+- **[SDK Architecture](sdk-architecture.md)** — how both SDKs (TypeScript + Python) encode
+  the loop: wire-contract mirroring, retry/error discipline, label honesty, and the
+  known asymmetries between the two.
+- **[Harness Architecture](harness-architecture.md)** — the internal agentic structure of
+  the `minima` CLI (`packages/tui`): the turn lifecycle, hook stacks, sub-agent DAG,
+  budget ledger, recovery ladder, ground-truth spine, memory ledger, and DB spine.
 
 ## Guides
 

{minima_cli-0.13.0 → minima_cli-0.13.1}/docs/agent-core-architecture.md

@@ -13,6 +13,10 @@ poisoning stop (client hardcodes verified_in_production + null-quality successes
 
 # Minima Next-Gen Agent Core — Definitive Architecture
 
+> **Historical proposal (2026-07-02).** Much of this has since shipped, evolved, or been
+> superseded (ground-truth spine, memory ledger, recovery ladder). For the architecture
+> as actually implemented, see [harness-architecture.md](harness-architecture.md).
+
 Status: implementation-ready. Branch: `tui-rewrite`. All seams below verified against source at `/Users/shankhadutta/code/costit/packages/tui/src`. Every "already exists" claim that the adversarial reviews contradicted has been corrected in place; where a design asserted a no-op that is actually a real API change, it is flagged as **[API CHANGE]**.
 
 ---

{minima_cli-0.13.0 → minima_cli-0.13.1}/docs/api-reference.md

@@ -213,12 +213,18 @@ rescaled cost-basis tiers.
 | `recommendation_id` | string | required | From a prior `/recommend` (or a step). |
 | `chosen_model_id` | string | required | The model you **actually ran** (may differ from the recommendation; the right model's neighbors are credited). |
 | `outcome` | enum | required | `success` \| `partial` \| `failure`. |
-| `quality_score` | float `0–1` \| null | `null` | Caller-supplied; there is no LLM judge. Defaults applied per outcome if omitted (0.9 / 0.5 / 0.1). |
+| `quality_score` | float `0–1` \| null | `null` | Caller-supplied judge/eval score. Omitted stays `null` (no fabricated default). A score contradicting the outcome label is clamped with a `quality_outcome_mismatch` warning. |
+| `evidence_source` | enum \| null | `null` | Label provenance: `gate` (deterministic check — the only origin that may claim verified-in-production) \| `judge` \| `human` \| `none` (telemetry only; never teaches the success posterior). |
+| `error_cause` | enum \| null | `null` | For failures: `infra` (429/5xx/timeout — never learned as model quality) \| `quality`. |
 | `input_tokens` | int ≥ 0 \| null | `null` | Realized input tokens — **populate this** to enable the rescaled cost tier. |
 | `output_tokens` | int ≥ 0 \| null | `null` | Realized output tokens (captures reasoning/thinking) — **populate this** for the rescaled tier. |
 | `actual_cost_usd` | float ≥ 0 \| null | `null` | Realized $/call — enables the observed cost tier. |
 | `latency_ms` | int ≥ 0 \| null | `null` | |
-| `verified_in_production` | bool | `false` | Marks a real production outcome; gates lesson promotion. |
+| `iterations` | int ≥ 0 \| null | `null` | Agent-loop turns to resolution. |
+| `chosen_effort` | string \| null | `null` | Reasoning-effort level actually used, if varied. |
+| `step_outcomes` | `StepOutcome[]` | `[]` | Per-step verdicts for multi-step work (cap 32/call): `{step_id, step_name?, outcome, signal? [-1,1], rationale?, directive_hint?}`. |
+| `verified_in_production` | bool | `false` | DEPRECATED — send `evidence_source="gate"` instead. |
+| `judged` | bool \| null | `null` | DEPRECATED — send `evidence_source` instead. |
 | `notes` | string \| null | `null` | |
 | `idempotency_key` | string \| null | `null` | Dedupe key; derived from `recommendation_id + model` if omitted. |
 
@@ -232,7 +238,8 @@ rescaled cost-basis tiers.
 | `updated_confidence` | float \| null | Mubit's updated `knowledge_confidence` for the primary entry. |
 | `reflection_triggered` | bool | Whether reflection fired this call. |
 | `lesson_promoted` | bool | Whether a durable lesson was promoted. |
-| `warnings` | string[] | `unknown_recommendation`, `memory_write_failed`, `reinforcement_failed`, `lesson_promotion_failed`. |
+| `step_outcomes_recorded` | int | How many `step_outcomes` were relayed to memory. |
+| `warnings` | string[] | `unknown_recommendation`, `memory_write_failed`, `reinforcement_failed`, `lesson_promotion_failed`, `quality_outcome_mismatch`, `late_feedback_no_attribution`, `step_outcomes_capped:<n>`, `step_outcomes_partial`. |
 
 ### Example
 
@@ -242,8 +249,8 @@ curl -s http://localhost:8080/v1/feedback -H 'content-type: application/json' -d
   "chosen_model_id": "claude-haiku-4-5",
   "outcome": "success",
   "quality_score": 0.95,
-  "input_tokens": 180, "output_tokens": 640, "actual_cost_usd": 0.0034,
-  "verified_in_production": true
+  "evidence_source": "gate",
+  "input_tokens": 180, "output_tokens": 640, "actual_cost_usd": 0.0034
 }' | jq
 ```
 
@@ -309,6 +316,22 @@ dominant_lesson_type, dominant_scope, lesson_ids[]`.
 
 ---
 
+## `GET /v1/savings` · `GET /v1/calibration` · `GET /v1/policy-value`
+
+The measurement layer over your account's decision ledger:
+
+- **`/v1/savings`** (`namespace?`, `days=30`, `group_by=cluster|task_type|lane`) — estimated **and** realized savings against two explicit baselines: `vs premium` (most expensive scored candidate; generous) and `vs declared` (your `baseline_model_id`; honest). `health.feedback_coverage` tells you how much weight the realized figures can bear.
+- **`/v1/calibration`** (`namespace?`, `days=30`) — per-task-type expected calibration error (`ece`, `ece_shrunk`) of `predicted_success` vs realized outcomes, plus sustained drift flags per `(cluster, model)`.
+- **`/v1/policy-value`** (`namespace?`, `days=30`) — doubly-robust off-policy estimates (`RegretReport`): per-policy value, `regret_vs_oracle`, with `stochastic_share` and `n_trusted` surfaced so the number can't overclaim.
+
+---
+
+## `GET /v1/capabilities`
+
+Feature handshake (no auth): `{ plan, workflow, api_version, honored_constraints[] }`. Read once at startup and gate optional features on what the server actually supports.
+
+---
+
 ## `POST /v1/diagnose`
 
 Failure lessons matching an error — "here's how this failed before". The harness recovery

minima_cli-0.13.1/docs/harness-architecture.md

@@ -0,0 +1,318 @@
+# Harness Architecture — the internal agentic structure of `minima-tui`
+
+The `minima` CLI (`packages/tui/`) is a TypeScript/Ink agent runtime on Bun. It is the
+active harness: a coding agent whose every routed turn runs the Minima loop —
+
+```
+route  →  run  →  judge  →  feedback
+```
+
+— against the `/v1/*` contract, with its own SQLite persistence spine, a budget ledger,
+a ground-truth verification spine, and a curated memory ledger. This page documents the
+implemented architecture as of v0.13.0. (The 2026-07-02 design proposal it grew from is
+preserved in [agent-core-architecture.md](agent-core-architecture.md); where the two
+disagree, this page reflects the code.)
+
+## Design principles (these constrain everything below)
+
+- **State in the DB, projections in the context.** Anything that must survive scroll,
+  compaction, restart, or a lying model lives in the SQLite ledger; the model sees only
+  a compact re-injected projection.
+- **Enforcement in the dispatcher, guidance in the prompt.** Plan/permission/gate
+  guarantees are enforced by harness code at tool-dispatch or turn boundaries — never by
+  prompt text, which is bypassable.
+- **Feedback truth.** Realized usage only; no fabricated quality. A gate verdict maps to
+  an outcome label; judge abstention stays `null`; `verified_in_production` comes only
+  from user/repo/CI-origin gates, never agent-authored ones.
+- **Recommend-only server stands.** Plan state is never server-authoritative.
+- **Append-only migrations**, **`rec_id` discipline** (the sole local↔server↔Mubit join
+  key), and **propensity integrity** (no client-side re-ranking; pins are pre-request
+  candidate assembly, never post-hoc overrides).
+
+## Module layout
+
+| Directory | What it owns |
+|---|---|
+| `src/ai/` | LLM provider layer: `types.ts`, `stream.ts` (`stream()`/`complete()`), `registry.ts` (calling-side model catalog — distinct from Minima's routing catalog), `usage.ts` (tokens × price → USD), providers (`openai-compat`, `anthropic`, `google`, hermetic `faux`) |
+| `src/agent/` | The stateful agent core: `loop.ts` (`agentLoop`), `agent.ts` (`Agent`), `tools.ts` (hook types), `modes.ts` (permission modes), `policy.ts` |
+| `src/minima/` | The integration layer — this IS the harness (39 files): `runtime.ts` (`MinimaAgent`), `router.ts`/`client.ts`, `judge.ts`, `budget.ts`, `spawn.ts`, the ground-truth files (`ground_truth.ts`, `gt_contract.ts`, `confidence.ts`, `check.ts`, `stop_gate.ts`, `anti_spiral.ts`, `failure_kind.ts`), the memory files (`memory.ts`, `memory_ledger.ts`, `memory_scribe.ts`, `memory_dream.ts`), the plan files (`plan_turn.ts`, `plan_council.ts`, `plan_finalize.ts`, `plan_critic.ts`, `plan_refute.ts`), `diff_review.ts`, `meter.ts`, `schemas.ts` (wire mirror) |
+| `src/tools/` | The agent's callable tools + `builtin.ts` registry |
+| `src/db/` | Persistence spine: `minima_db.ts` (`MinimaDb`), `sink.ts` (event-stream → rows), `rehydrate.ts` (restore a run), `metrics.ts` (regret-vs-oracle) |
+| `src/tui/` | Ink/React UI: `app.tsx` (main component + slash commands) + overlays |
+| `src/session/` | Checkpoints (git-shadow worktree snapshots), `/undo` `/rewind`, resume re-verify, JSONL session store |
+| `src/cli/` | `main.ts` — the single entry point; builds config/DB/agent, wires hooks, spawn, budget, scribe |
+
+## The turn lifecycle — `MinimaAgent.promptRouted()`
+
+`MinimaAgent extends Agent` (`src/minima/runtime.ts`). One routed prompt runs this
+sequence:
+
+### 1. Context assembly (reverted in a `finally` after the turn)
+
+- **Mubit recall** — `memory.recall(content)` formats recalled evidence into a system
+  prompt block.
+- **Mode hint** — `modeSystemAppend(getMode())` for the current permission mode.
+- **Ground-truth projection** (when `config.groundTruth`, default on) — standing GT
+  guidance plus `planProjectionFor(db, runId)`: the numbered plan of record, re-injected
+  every turn so it survives compaction.
+- **Memory-ledger projection** (lead agent only) — `memoryProjectionFor(db, runId)`:
+  active + pinned curated memories under a hard char cap. Every *distinct* injected
+  id-set is audited as an `inject` memory-event, so "what the model saw" is replayable.
+
+### 2. The recovery-ladder loop (up to `1 + recoveryRungs` attempts, default 3)
+
+Each rung:
+
+1. **Budget gate** — in `enforce` mode, refuse before spend if `budget.exhausted()`.
+2. **Route** — `router.recommend()` → `POST /v1/recommend`. Candidates are filtered to
+   providers whose API key is present; a `/model`-pinned model bypasses Minima entirely;
+   a `beforeRouteHook` may veto/override. The winner becomes `agentState.model`. With
+   `autoEffort`, the server's classified difficulty picks the thinking-effort level.
+3. **Reserve** — `budget.reserve()` holds a padded estimate (est-high × 1.5, or point
+   estimate × 3) before any spend.
+4. **Arm the stop stack** — one composed `shouldStopAfterTurn` closure: budget cutoff
+   first, then the anti-spiral detector (doom-loop repeats / step-cap, fed by an
+   after-tool ring buffer), then the stop-gate (strike-based stall detection).
+5. **Run** — `super.prompt()` enters the base agent loop (§ Agent core). During dispatch
+   `currentRecId` is set so any gate rows minted this rung carry the routing identity.
+6. **Settle** — compute latency/turns/failure, read the **grounded verdict** for this
+   rung (`groundedOutcomeFor(db, recId)` — the deterministic gate outcome, if any),
+   classify transience, `budget.reconcile()` realized cost against the hold.
+7. **Judge + feedback** — `feedbackSafely()` (see § Feedback truth).
+8. **Persist** — `meter.record()` + `persistDecision()`: a `routing` event, a
+   `routing_decisions` row keyed by `rec_id`, and the grounded-outcome stamp.
+9. **Decide** — `stillFailing = hardError || judgeBelowThreshold || gateFailed`. If rungs
+   remain, the **failure matcher** picks the intervention (§ Recovery ladder); the
+   message list is rolled back to the pre-run index so the retry is clean. On
+   exhaustion, a terminal `recovery` gate is written.
+
+## Agent core (`src/agent/`)
+
+- **`agentLoop`** (`loop.ts`) is a re-entrant async generator: prepare messages → stream
+  the model → yield events → execute tool calls → append results → `turnEnd` → check
+  `shouldStopAfterTurn` → drain steering/follow-up queues, up to `maxTurns` (default 50).
+- **Tool dispatch** (`executeToolCalls`): validate params, then the **before-hook stack**
+  (ordered; first `block: true` wins — this is where enforcement lives), then
+  `tool.execute`, then the **after-hook stack** (folding — each hook sees the previous
+  hook's modified result). Tools run in parallel via `Promise.all` unless any requested
+  tool is sequential (the `task` tool is).
+- **Registered hook stacks** (wired in `cli/main.ts` / `tui/app.tsx`, in order):
+  1. **Permission hook** (TUI) — must run first.
+  2. **Ground-truth hooks** — the *done-gate* (before): refuses a `todowrite` that marks
+     a step complete unless its `verify` command actually passes (red→green), enforces
+     one-todowrite-per-message and the per-step tool allowlist; the after-sink keeps the
+     plan/file-changes/gates ledger current.
+  3. **Checkpoint hook** — pre-mutation git-shadow snapshot (powers `/undo`/`/rewind`).
+  4. **Anti-spiral ring feed** — per-rung after-hook feeding the doom-loop detector.
+- **Abort** is a first-class tree: `Agent.abort()` cancels the run controller,
+  `MinimaAgent.abort()` also cancels the in-flight routing request, and each stream read
+  races the abort signal so Esc interrupts mid-token. An aborted turn commits an
+  explicit `[aborted by user]` stub — never a half-written message.
+
+## Tools
+
+The registry is `builtinTools()` (`src/tools/builtin.ts`): `read`, `write`, `edit`,
+`apply_patch`, `bash`, `ls`, `glob`, `grep`, `todowrite` (GT-aware), `web_search`,
+`web_fetch` (Exa when `EXA_API_KEY` is set, else DuckDuckGo). Filesystem tools are
+confined to the configured workdir. Three tools are wired *outside* the registry: `task`
+(sub-agents; added by `cli/main.ts` with spawn depth 0), and `question` / `exit_plan`
+(plan-mode, wired by the TUI).
+
+## Sub-agents (`src/tools/task.ts` + `src/minima/spawn.ts`)
+
+The `task` tool takes a list of **delegations** — `{step_id, objective, output_format,
+boundaries}` are required; optional `depends_on` (DAG edges), `effort`
+(light/standard/deep → turn + wall-clock limits), `difficulty` (→ tier routing),
+`tool_allowlist`, `budget_usd`, `isolation`.
+
+- `validateDelegations` rejects missing fields, duplicate ids, dangling edges, and
+  cycles before anything runs.
+- `executeDag` runs independent frontier nodes **concurrently under a semaphore**
+  (default 4); dependents wait; a failed dependency marks its dependents `blocked`.
+- `createSpawn` builds each child as a **fresh `MinimaAgent`** sharing the parent's
+  router/judge/memory but with its own cost meter, tools scoped to the allowlist (minus
+  `task` at the depth cap — max depth 2), and `groundTruth: false` (the GT spine never
+  inherits into children). Each child routes through Minima independently — cost-aware
+  routing applies **per worker**, not just at the top level.
+- Per-node `budget_usd` becomes a running-cost stop; the parent's abort signal fans out
+  to `child.abort()`; effort scales a wall-clock timeout (120s/300s/600s).
+- `isolation: "workdir"` gives the child a temporary git worktree (with a dirty-tree
+  warning, cleanup on exit, and fallback to the parent workdir on failure).
+
+## Routing layer (`src/minima/router.ts`, `client.ts`)
+
+`MinimaClient` is the typed `/v1/*` client (recommend, workflow, feedback, diagnose,
+savings, calibration, strategies, memory-health, models, capabilities, health) with an
+injectable `fetch` for hermetic tests. `MinimaRouter` maps the server's `RankedModel`
+onto a callable harness `Model` and owns the fail-open discipline:
+
+- **Routing must stay bypassable.** `--offline` or an unreachable server sets
+  `offlineReason` and the run proceeds on the current model **with no feedback sent**
+  (`allowOffline` defaults to true). An Esc during routing is an abort, not a
+  degradation to offline.
+- A pinned model (`/model`) skips the recommender entirely; explicitly provided
+  candidate pools are hard constraints, never widened.
+- `capabilities()` is cached per session and fails open to all-false;
+  `diagnoseBrief()` fails open to null.
+
+## Budget (`src/minima/budget.ts`)
+
+`BudgetLedger` persists scopes in the `budgets` table with an append-only
+`budget_events` audit. The cycle is **reserve → run → reconcile**: reservations are
+guarded UPDATEs inside `BEGIN IMMEDIATE` (safe across processes), holds are padded
+estimates, reconcile swaps the hold for realized cost, and `bookSpend` books unreserved
+harness overhead (judge calls, scribe extraction) so *all* spend is on the ledger.
+Modes: `shadow` (track), `warn` (notify at 50/75/90/100% thresholds, each fired once),
+`enforce` (refuse new routed prompts when exhausted, stop a turn mid-run when realized
+spend crosses the remainder, and thread remaining headroom into `/v1/recommend` as
+`max_cost_per_call`).
+
+## Recovery ladder (`src/minima/failure_kind.ts`)
+
+After a failed rung, `makeFailureMatcher` classifies the failure and picks one of three
+named rungs:
+
+| Signal | Intervention |
+|---|---|
+| First grounded 🔴 gate verdict | **escalate** (`revise_step`) — exclude the failed model, re-route stronger |
+| Gate still 🔴 after 2 rungs | **replan** — keep the model, revise the plan |
+| Hard error classified transient (rate limit, 5xx) | **backoff** (`retry_step`) — same model, optional delay, **no feedback** (an infra fault must not read as model quality) |
+| Judge-miss or non-transient error | **escalate** |
+
+The **replan** branch is briefed before retrying: `collectFailureDiagnostics()` re-runs
+the failing verify command and captures full output, and `router.diagnoseBrief()`
+(→ `POST /v1/diagnose`) appends matching failure lessons from Mubit memory. Each retry
+rolls the transcript back to the pre-run index; exhaustion writes a terminal `recovery`
+gate.
+
+## Ground-truth spine
+
+On by default (`MINIMA_TUI_GROUND_TRUTH=0` opts out). The contract enums are frozen in
+`gt_contract.ts`: gate outcomes `verified | failed | unrunnable | unchecked`, confidence
+tiers `green | yellow | red`, verifiers `deterministic | judge | user`, gate kinds
+`step_check | milestone | stop | recovery`, check origins `pre_existing | agent_new |
+user`.
+
+- **Plan flow** — `/plan` runs a planner persona plus a deliberation council off the
+  routing loop (`plan_turn.ts`, `plan_council.ts`); `finalizePlan` (shared by
+  `/plan finalize` and the `exit_plan` tool) lints steps and auto-gates them. Each plan
+  step carries a `verify` shell command and a recorded `baseline` (the check must be
+  red *before* the work — a check that was already green proves nothing).
+- **Verification** — `runCheck` (`check.ts`) executes verify commands deterministically
+  (own process group, allowlisted env), consent-gated: the TUI injects a
+  permission-backed checker; headless runs are fail-closed unless
+  `MINIMA_TUI_ALLOW_VERIFY=1`.
+- **The done-gate** — the before-hook that makes plans *enforced*, not advisory: a step
+  cannot be marked complete unless its verify passes red→green. Verdicts land as rows in
+  the `gates` ledger with the minting rung's `rec_id`.
+- **Confidence tiering** (`confidence.ts`) — factors → tier: tampering → red; no
+  discriminative check → yellow; check failed → red; agent-authored check with coverage
+  gaps → red (the fabrication floor); a trusted check that passed → green. The tier
+  drives the UI (🟢 glide / 🟡 flag / 🔴 stop) and, critically, feedback labeling: only
+  **green-tier deterministic** verdicts may label an outcome as gate-verified.
+- **Verification extras** — the **planning critic** (`plan_critic.ts`) runs one cheap
+  completion at plan finalize flagging non-discriminative checks and hidden dependencies
+  (advisory, never blocking); the **zero-context diff reviewer** (`diff_review.ts`)
+  fires when a plan closes fully completed and reviews the run's whole diff with fresh
+  eyes — an objection writes a yellow judge milestone gate (it can yellow a plan, never
+  green it). `/verify` re-runs checks under a refutation brief; `/why` and `/gt` surface
+  gate reasoning.
+
+## Feedback truth (`feedbackSafely`)
+
+Label precedence is strict — **deterministic gate > judge > telemetry-only**:
+
+1. An infra failure sends outcome `failure` with `error_cause="infra"` and **no quality
+   signal**.
+2. A green-tier deterministic gate verdict labels the outcome with
+   `evidence_source="gate"` — the only origin that may claim verified-in-production.
+3. Otherwise a sampled LLM judge (`judgeEvery` × `judgeSampleRate`, default 15% of
+   ungated turns; `MINIMA_JUDGE_SAMPLE=0` disables, `MINIMA_LLM_JUDGE=1` forces every
+   turn) grades with
+   `evidence_source="judge"`; unjudged turns ride as cost/latency telemetry
+   (`evidence_source="none"`).
+4. Transient failures short-circuit with **no feedback at all**.
+
+Per-step process rewards ride the same request: `stepOutcomesFromGates` (`runtime.ts`)
+maps the rung's gate rows — **deterministic/user verdicts only** (never judge, which is
+model-adjacent self-assessment), last verdict per step wins, capped at 32 — into
+`step_outcomes[]`. Every feedback carries realized `input_tokens` / `output_tokens` /
+`actual_cost_usd` / `latency_ms` from the meter, never Minima's own estimate echoed
+back. Feedback failures are logged and swallowed — bookkeeping never breaks the hot
+path.
+
+## Memory
+
+Two distinct systems share the word "memory":
+
+**Mubit (server-side, cross-user learning)** — `memory.recall()` before the turn and
+`memory.recordOutcome()` after feedback are the harness's Mubit seams; harness trace
+writes are partitioned to `lane: "harness"`.
+
+**The memory ledger (local, curated, Track B)** — default on (`MINIMA_TUI_MEMORY=0`
+opts out). Three tables (migration v12): `memories` (durable, bi-temporal — delete is
+invalidation, never `DELETE`), `memory_events` (append-only audit), `memory_jobs`
+(curation queue). Managed via `/memory` (list · add · pin/confirm/reject · delete).
+Projection into the system prompt is lead-agent-only, ranked pinned > gate-cited >
+recency under a 4000-char cap.
+
+The model has **no memory-write tool** (the Letta split) — only the harness/user writes.
+The sole automated writer is the **scribe** (`memory_scribe.ts`): a background curator
+fed by SQL over the ledger (gate flips, verified failures, user corrections, judge/gate
+disagreements — never the transcript), recurrence-gated (a pattern must recur before it
+earns the one LLM extraction call, which routes through Minima tagged `memory:extract`
+with its spend booked like judge spend), reconciled mem0-style (ADD/UPDATE/NOOP;
+rejected rows never resurrect), and provenance-gated (only gate-cited candidates
+auto-activate; the rest await `/memory confirm`). Triggers — session end, quiet timer,
+startup leftovers — only *enqueue* `memory_jobs` rows; a crash-safe drain executes them
+and requeues jobs orphaned by a crash. `memory_dream.ts` adds offline consolidation
+gated on green-tier verified episodes.
+
+## DB spine (`src/db/minima_db.ts`)
+
+Event-sourced `bun:sqlite` (WAL), currently at **migration v13** — shipped batches are
+append-only and never edited. `events` is the append-only source of truth; derived
+tables key back to `event_id`/`rec_id`. `DbSink` subscribes to the agent event stream
+and flushes buffered rows in one transaction at turn/agent end; writes fail open (a
+degraded DB never breaks a turn); large tool results spill to blob storage.
+
+| Table | Purpose |
+|---|---|
+| `projects` / `runs` | project identity → namespace; one row per run with lineage (`parent_run_id`, fork point) |
+| `events` | append-only per-run event log (user/assistant/tool/system/routing) |
+| `routing_decisions` | one row per routed prompt, PK `rec_id` — the local replay buffer for regret-vs-oracle metrics |
+| `tool_calls` | every tool invocation (args + result, blob refs) |
+| `budgets` / `budget_events` | budget scopes + append-only audit |
+| `plans` / `plan_steps` | the GT plan of record: steps with `verify`, `baseline`, check origin, tool allowlist |
+| `file_changes` | every write/edit attributed to a step (`on_plan`/`off_plan` drift) |
+| `gates` | verification verdicts: outcome, confidence tier, verifier, factors, `rec_id` identity |
+| `user_signals` | user accept/reject/steer against a gate |
+| `checkpoints` | git-shadow snapshots powering `/undo`/`/rewind` |
+| `memories` / `memory_events` / `memory_jobs` | the memory ledger |
+
+`rehydrate.ts` reconstructs a live agent from persisted events; `resume_verify.ts`
+re-runs verifies on resume so a stale green never carries across sessions.
+
+## Key environment flags
+
+All default-on features follow the same rule: anything gated on ground truth lives
+behind `config.groundTruth` (code), never behind prompt text.
+
+| Variable | Effect | Default |
+|---|---|---|
+| `MINIMA_URL` / `MINIMA_API_KEY` (or `MUBIT_API_KEY`) | routing endpoint + auth | `https://api.minima.sh` |
+| `MINIMA_NAMESPACE` | memory lane | derived from the repo |
+| `MINIMA_TUI_GROUND_TRUTH` | GT spine | on |
+| `MINIMA_TUI_MEMORY` / `MINIMA_TUI_MEMORY_CAP` | memory ledger / projection cap | on / 4000 chars |
+| `MINIMA_JUDGE_SAMPLE` / `MINIMA_LLM_JUDGE=1` / `MINIMA_JUDGE_MODEL` | judge sample rate (0 disables) / force every turn / model | 0.15 / off / `claude-haiku-4-5` |
+| `MINIMA_TUI_STOP_STRIKES` / `MINIMA_TUI_SPIRAL_REPEATS` / `MINIMA_TUI_STEP_CAP` | stall + doom-loop detectors | 3 / 3 / 30 |
+| `MINIMA_TUI_FAILURE_MATCHER` / `MINIMA_TUI_BACKOFF_MS` | recovery-ladder matcher / backoff | on / 0 |
+| `MINIMA_TUI_PLAN_PREMIUM` / `MINIMA_PLAN_PREMIUM_MODELS` | premium pool for all plan-mode turns (council or not) | on |
+| `MINIMA_TUI_PLAN_CRITIC` / `MINIMA_TUI_DIFF_REVIEW` / `MINIMA_TUI_AUTO_GATES` | verification extras | on |
+| `MINIMA_TUI_ALLOW_VERIFY` | headless verify consent (fail-closed) | off |
+| `MINIMA_AUTO_EFFORT` | difficulty → thinking effort | off |
+| `MINIMA_DB_PATH` / `MINIMA_HARNESS_DIR` | persistence locations | `~/.minima-harness/` |
+
+See [configuration.md](configuration.md) for the server-side variables and
+[ground-truth-build-guide.md](ground-truth-build-guide.md) for the GT spine's build
+history.

{minima_cli-0.13.0 → minima_cli-0.13.1}/docs/harness.md

@@ -14,7 +14,9 @@ brew tap mubit-ai/minima
 brew install minima
 ```
 
-See [`packages/tui/README.md`](../packages/tui/README.md) for architecture and usage.
+See [Harness Architecture](harness-architecture.md) for the internal agentic structure
+(turn lifecycle, hooks, sub-agents, ground-truth spine, memory ledger, DB spine) and
+[`packages/tui/README.md`](../packages/tui/README.md) for usage.
 The `minima-cli` PyPI package now contains only the Minima server (`minima`) and the
 Python client SDK (`minima_client`).
 

minima_cli-0.13.1/docs/sdk-architecture.md

@@ -0,0 +1,165 @@
+# SDK Architecture — how the Minima loop is encoded in the clients
+
+Minima ships two SDKs that wrap the same `/v1/*` HTTP contract:
+
+- **`@mubit-ai/minima-sdk`** (`packages/sdk/`) — TypeScript, pure `fetch`, zero runtime
+  dependencies.
+- **`minima_client`** (`client_sdk/minima_client/`) — Python, sync + async, shipped inside
+  the `minima-cli` wheel alongside the server.
+
+Both encode the same workflow and the same honesty rules. This page documents their
+internal structure and the loop contract they enforce; for task-oriented usage see
+[Python Client SDK](client-sdk.md) and [`packages/sdk/README.md`](../packages/sdk/README.md).
+
+## One wire contract, three copies
+
+The server's Pydantic models (`src/minima/schemas/*.py`) are the **wire source of truth**.
+Every field lands in three places:
+
+| Copy | Where | Kept honest by |
+|------|-------|----------------|
+| Server (authoritative) | `src/minima/schemas/*.py` | — |
+| TS SDK mirror | `packages/sdk/src/schemas.ts` | `tests/unit/test_ts_mirror.py` (mechanical field-by-field pin) |
+| Harness mirror | `packages/tui/src/minima/schemas.ts` | same test |
+| Python SDK | *(no copy)* | imports the server's Pydantic models directly (`client.py`) |
+
+The Python client cannot drift because it has no mirror; the two TS mirrors are pinned by
+CI. All three version files (`pyproject.toml`, `packages/tui/package.json`,
+`packages/sdk/package.json`) move in lockstep on every release.
+
+## The workflow both SDKs encode
+
+```
+recommend  →  run the model yourself  →  judge quality  →  feedback
+```
+
+Minima is recommend-only: it never proxies, runs, or caches an LLM call. The SDK's job is
+to make the four steps of the loop hard to get wrong:
+
+1. **`recommend(task, …)`** — the caller reads `recommendation_id` (the join key for the
+   whole loop), `recommended_model.model_id`, `est_cost_usd`, `predicted_success`, and
+   `warnings`. `constraints.candidate_models` scopes the choice; `phase` rides as a
+   `phase:<value>` tag; `incumbent_model_id` lets the server price prompt-cache stickiness
+   honestly. **Recommend never retries** — it fails fast so the caller can fail *open*
+   (fall back to a default model rather than block the user's real LLM call).
+2. **Run the model yourself**, measuring what the provider actually billed.
+3. **Judge quality** — your own gate, judge, or human check. Score thresholds:
+   `success >= 0.8`, `partial >= 0.4`, else `failure`.
+4. **`feedback(recommendation_id, model_id, outcome, …)`** — carries the **realized**
+   `input_tokens` / `output_tokens` / `actual_cost_usd` / `latency_ms`. Never echo
+   Minima's own `est_cost_usd` back: real usage is what climbs the cost basis
+   `estimate → observed → rescaled`, the single biggest accuracy lever. **Feedback
+   retries transparently** (3 attempts) on transport faults and 502/503/504 — the server
+   dedupes — but 4xx (including 429) surfaces immediately.
+
+### Label honesty (enforced by field design)
+
+`evidence_source` declares where the outcome label came from, and the server treats each
+origin differently:
+
+| `evidence_source` | Meaning | Effect |
+|---|---|---|
+| `"none"` | no real label | cost/latency **telemetry only** — never touches the success posterior |
+| `"judge"` | an LLM judge scored it | teaches the posterior, judge-weighted |
+| `"human"` | a person asserted it | teaches the posterior |
+| `"gate"` | a deterministic check passed | the **only** origin allowed to claim verified-in-production |
+
+Provider/infra faults should carry `error_cause="infra"` so a rate-limit never reads as
+model quality. Per-step results ride as `FeedbackRequest.step_outcomes[]`
+(`StepOutcome`: `step_id`, `outcome`, optional `signal` in `[-1, 1]`, `rationale`,
+`directive_hint`) — in the harness these are derived exclusively from deterministic/user
+gate verdicts, never from model self-assessment.
+
+## Endpoint surface (identical in both SDKs)
+
+| Method (TS / Python) | Endpoint | Purpose |
+|---|---|---|
+| `recommend` | `POST /v1/recommend` | one-task model pick |
+| `recommendWorkflow` / `recommend_workflow` | `POST /v1/recommend/workflow` | per-step picks for a multi-step DAG (`total_est_cost_usd` vs `total_est_cost_if_all_premium`) |
+| `feedback` (+ TS `feedbackRaw`) | `POST /v1/feedback` | close the loop with realized usage |
+| `savings` | `GET /v1/savings` | realized savings report |
+| `calibration` | `GET /v1/calibration` | predicted-vs-realized quality calibration |
+| `policyValue` / `policy_value` | `GET /v1/policy-value` | doubly-robust regret-vs-oracle estimate |
+| `strategies` | `GET /v1/strategies` | promoted Mubit lessons (explainability) |
+| `diagnose` | `POST /v1/diagnose` | failure lessons matching an error text |
+| `memoryHealth` / `memory_health` | `GET /v1/memory/health` | per-org memory diagnostics (stale/contradictions/promotion candidates) |
+| `models` | `GET /v1/models` | model catalog (cost + capability priors) |
+| `capabilities` | `GET /v1/capabilities` | feature handshake (`plan`, `workflow`, `api_version`, `honored_constraints`) |
+| `health` | `GET /v1/health` | service/Mubit/catalog status |
+
+## TypeScript SDK internals (`packages/sdk/src/`)
+
+Five files, no runtime deps:
+
+- **`client.ts`** — `MinimaClient`. Constructor options: `baseUrl` (required),
+  `apiKey` (→ `Authorization: Bearer`), `feedbackRetryDelaysMs` (default `[500, 2000]`,
+  i.e. up to 3 feedback attempts), and an injectable `fetch` for hermetic tests. No
+  global timeout — cancellation is per-call via `signal: AbortSignal`. Every request
+  sends `x-minima-client` and `user-agent: minima-sdk-ts/<VERSION>`.
+  - `feedback()` is the ergonomic camelCase surface (`Usage{inputTokens, outputTokens,
+    costUsd, latencyMs}` — explicit `0` is a real measurement); it maps to snake_case
+    wire fields and drops undefined.
+  - `feedbackRaw(req)` accepts a full `FeedbackRequest` — the seam for advanced fields
+    like `step_outcomes` (this is what the harness uses).
+- **`schemas.ts`** — the wire mirror: `TaskInput`, `Constraints`, `RecommendRequest/
+  Response`, `RankedModel`, `FeedbackRequest/Response`, `StepOutcome`, `WorkflowStep/
+  Request/Response`, `SavingsResponse`, `CalibrationResponse`, `PolicyValueResponse`,
+  `StrategiesResponse`, `DiagnoseRequest/Response`, `MemoryHealthResponse`,
+  `CapabilitiesResponse`, plus the enums (`TASK_TYPES`, `DIFFICULTIES`,
+  `OUTCOME_LABELS`, `DECISION_BASES`).
+- **`errors.ts`** — typed error ladder: 429 → `MinimaRateLimited` (carries the parsed
+  `retry-after` seconds), 502/503/504 → `MinimaUnavailable`, any other non-2xx →
+  `MinimaError`; all carry `status` + raw `body`. The retry loop in `feedbackRaw`
+  retries **only** `MinimaUnavailable` and transport errors.
+- **`index.ts`** — the public surface: `MinimaClient`, the three errors, `VERSION`, and
+  `export type *` of the wire types.
+- **`version.ts`** — `VERSION` from `package.json`.
+
+## Python SDK internals (`client_sdk/minima_client/`)
+
+- **`client.py`** — `MinimaClient` (sync) and `AsyncMinimaClient` mirror the same
+  surface method-for-method; both are context managers. Constructor:
+  `(base_url, api_key=None, timeout=10.0)` over `httpx`. Feedback retry uses tenacity
+  (`stop_after_attempt(3)`, exponential 0.5s→4s) on `httpx.TransportError` /
+  `MinimaUnavailable` only. The typed `Usage` dataclass maps `cost_usd →
+  actual_cost_usd` on the wire. Notable defaults that differ from TS: `explain=True`,
+  `max_candidates=8`.
+- **`errors.py`** — same ladder as TS: `MinimaError` / `MinimaRateLimited` /
+  `MinimaUnavailable`.
+- **`autocapture.py`** — *not* the feedback loop: a wrapper over `mubit.learn` that pins
+  traces to Minima's memory lane (`minima:<namespace>`) by monkeypatching
+  OpenAI/Anthropic/LiteLLM/Google clients. Enriches recall; does not produce the
+  `kind="outcome"` records the aggregator scores.
+- **`integrations/`** — framework adapters (all fail-open, all lazy-import their
+  framework):
+  - `claude_code.py` — the `minima-route` CLI (`recommend` prints a model id or JSON;
+    `feedback` closes the loop from the shell; `--source gate|judge|human|none`).
+  - `litellm_router.py` — `MinimaRoutingStrategy` picks the deployment Minima
+    recommends (candidates constrained to the model group, in-band correlation via a
+    bounded LRU) + `MinimaFeedbackLogger` reports realized cost on success/failure
+    events; grader score → outcome via the 0.8/0.4 thresholds, no grader →
+    `evidence_source="none"`, failures → `error_cause="infra"`.
+  - `openhands_router.py` — `MinimaRouterLLM` routes each completion among
+    `llms_for_routing` and fires off-thread telemetry feedback.
+
+Neither client class reads environment variables — explicit `base_url`/`api_key` only.
+The one env-aware entry point is the `minima-route` CLI (`MINIMA_URL`,
+`MINIMA_API_KEY`/`MUBIT_API_KEY`).
+
+## Known asymmetries (TS vs Python)
+
+| Area | TypeScript | Python |
+|---|---|---|
+| Timeout | none (per-call `AbortSignal` only) | `timeout=10.0` constructor default |
+| `recommend` defaults | `explain`/`max_candidates` unset | `explain=True`, `max_candidates=8` |
+| Async | promise-based (inherently async) | separate `AsyncMinimaClient` |
+| `step_outcomes` | typed `StepOutcome` + `feedbackRaw` seam | untyped `**kwargs` passthrough only |
+| Wire types | hand-mirrored, CI-pinned | imports server Pydantic directly |
+| Integrations | none (client only) | litellm, OpenHands, `minima-route` CLI, `autocapture` |
+| Feedback retry | fixed delays `[500ms, 2000ms]` | tenacity exponential (0.5s→4s), 3 attempts |
+| User-Agent | `minima-sdk-ts/<v>` | `minima-cli/<v> (python-httpx)` |
+
+A note on `cost_basis`: the estimate → observed → rescaled climb is a server-side concept —
+there is no `cost_basis` wire field. The observable cousins on `RankedModel` are
+`est_cost_breakdown`, `est_cost_low`/`est_cost_high`, `cost_band_basis`, and
+`latency_basis`.