minima-cli 0.12.1__tar.gz → 0.12.2__tar.gz

{minima_cli-0.12.1 → minima_cli-0.12.2}/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.12.2] - 2026-07-20
+
+The memory spine: the SQLite ledger starts feeding decisions. Ten PRs across the
+harness and server (#175–#184) — curated cross-session memory, a background
+curator, recall track records on server memory, and the durable-execution +
+verification upgrades.
+
+### Added
+- **Memory ledger** (harness, default ON — `MINIMA_TUI_MEMORY=0` opts out; migration
+  v12): curated per-repo memories (`note`/`workflow`/`lesson`/`guardrail`) projected
+  into each turn's system prompt (hard-capped, pinned > gate-cited > recency; every
+  distinct injection audited so "what the model saw" is replayable). Managed via
+  `/memory` (list · add · dream · pin/confirm/reject/delete = bi-temporal invalidate).
+  The model has no memory-write tool (Letta split).
+- **Memory scribe**: the sole automated memory writer — signals mined from the ledger
+  (gate flips, verified failures, user corrections, judge/gate disagreements — never
+  the transcript), recurrence-gated, one extraction call routed through Minima
+  (`tags=["memory:extract"]`, spend booked like judge spend), mem0-style
+  reconciliation (rejected rows never resurrected), provenance activation (only
+  gate-cited candidates auto-activate). Runs as crash-safe persisted jobs.
+- **Memory dream** (`/memory dream`): deterministic offline consolidation — only
+  green-gated closed plans distill into `workflow` candidates (always pending, never
+  mutates existing rows). Confirmed workflows enable **replay-with-cheap**: matching
+  prompts route with `tags=["procedure:known"]` so Thompson learns the cheaper
+  frontier for known-procedure work organically.
+- **Recall track** (server, schema v5): every trusted-label feedback casts a vote on
+  the durable records recalled into that decision; bad-track records are down-weighted
+  (floor 0.25) and eventually tombstoned (`invalidated_at`, never deleted;
+  `recall_invalidated_skipped:<n>` recommend warning). `MINIMA_RECALL_VOTE_MIN_N` /
+  `MINIMA_RECALL_INVALIDATE_RATE`.
+- **Planning critic** (advisory, at `/plan` finalize) + **zero-context diff reviewer**
+  (at plan closure; an objection can yellow the plan tier, never green it).
+  `MINIMA_TUI_PLAN_CRITIC=0` / `MINIMA_TUI_DIFF_REVIEW=0` opt out.
+- **Auto-gates**: repo manifests mined for trusted-by-construction check commands at
+  `/plan` finalize — fast command (typecheck/lint) on verify-less steps, full test
+  suite on the final step. `MINIMA_TUI_AUTO_GATES=0` opts out.
+- **Version stamps + blob tier** (migration v13): decisions/gates record
+  `harness_version` + a toolset hash (resume warns on skew, never blocks); >16KB tool
+  results spill to content-addressed blob files.
+- **Resume re-verify**: resuming re-runs the in-progress step's verify against its
+  recorded baseline (consent-gated) — divergence re-baselines from reality with a 🟡
+  banner; the resumed run's provider session id is reused for prompt-cache continuity.
+- **Ladder v2**: named rung states (`retry_step`/`revise_step`/`replan`) on recovery
+  gates + feedback notes; repeated verified failures unlock full failing-check output
+  in the retry prompt.
+- **Honest meter**: KV-cache hit rate and cost-of-pass (labeled successes only, with
+  coverage disclosure) in `/cost`.
+
 ## [0.12.1] - 2026-07-20
 
 SDK integrity + a standalone TypeScript SDK. Server wire contract unchanged; all

{minima_cli-0.12.1 → minima_cli-0.12.2}/CLAUDE.md

@@ -88,6 +88,10 @@ Everything external is behind a Protocol so it can be faked in tests. The server
 
 **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.
 
+**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.
+
+**Verification extras** (E1): the **Planning Critic** (`src/minima/plan_critic.ts`, `MINIMA_TUI_PLAN_CRITIC=0` opts out) runs one cheap completion at `/plan` finalize over the approved steps + verifies — non-discriminative checks and hidden dependencies come back as advisory flags in the finalize note, never blockers. The **zero-context diff reviewer** (`src/minima/diff_review.ts`, `MINIMA_TUI_DIFF_REVIEW=0` opts out) fires when a plan closes fully completed: fresh-eyes review of the run's whole diff, no session context; an objection writes a yellow judge milestone gate (worst-tier resolution can yellow the plan, never green it; approval/skip writes nothing). Distinct from `/verify`'s refutation pass, which is ledger-briefed and re-runs checks.
+
 Design principles that constrain any work in this direction:
 
 - **State in the DB, projections in the context** — anything that must survive scroll/compaction/restart/a lying model lives in the ledger; the model sees only a compact re-injected projection.

{minima_cli-0.12.1 → minima_cli-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.12.1
+Version: 0.12.2
 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.12.1 → minima_cli-0.12.2}/docs/configuration.md

@@ -40,6 +40,8 @@ single-tenant mode). A complete annotated template ships as
 | `MINIMA_REFLECT_EVERY_N` | `25` | Trigger reflection every N feedbacks per lane. |
 | `MINIMA_USE_OBSERVED_COST` | `true` | Rank by realized cost (observed/rescaled tiers) instead of a flat token estimate. |
 | `MINIMA_OBSERVED_COST_MIN_N` | `3` | Min observations per candidate before the observed/rescaled tiers are trusted. |
+| `MINIMA_RECALL_VOTE_MIN_N` | `5` | Recall-track: votes required before a record's aggregation weight scales with its recall success rate (floor 0.25). `0` disables the whole recall track. |
+| `MINIMA_RECALL_INVALIDATE_RATE` | `0.2` | Recall success rate below which a record (with ≥ min-n votes) is stamped `invalidated_at` — out of ranking, still readable. |
 
 See [Cost-basis tiers](concepts.md#cost-basis-tiers-estimate--observed--rescaled) for what
 `MINIMA_USE_OBSERVED_COST` / `MIN_N` actually switch between.

{minima_cli-0.12.1 → minima_cli-0.12.2}/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mubit-ai/minima-sdk",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "TypeScript SDK for the Minima recommender service (api.minima.sh) — typed /v1/* client for the recommend → run → judge → feedback loop.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

{minima_cli-0.12.1 → minima_cli-0.12.2}/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minima-tui",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Minima harness + TUI — the `minima` CLI (TypeScript/Ink; successor to the removed Python harness). Talks to the Python FastAPI recommender service over the /v1/* contract.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

{minima_cli-0.12.1 → minima_cli-0.12.2}/packages/tui/src/cli/main.ts

@@ -17,11 +17,12 @@ import { providerKeyPresent } from "../ai/provider_catalog.ts";
 import { ensureProvidersRegistered } from "../ai/providers/index.ts";
 import { findModelById, registerModel } from "../ai/registry.ts";
 import type { Model } from "../ai/types.ts";
-import { MinimaDb, type RunRow } from "../db/minima_db.ts";
+import { MinimaDb, type RunRow, toolSchemaHash } from "../db/minima_db.ts";
 import { type RehydratedRun, applyRehydratedRun, rehydrateRun } from "../db/rehydrate.ts";
 import { type DbSinkHandle, attachDbSink } from "../db/sink.ts";
 import { errText } from "../errtext.ts";
 import { BudgetLedger } from "../minima/budget.ts";
+import { collectRunDiff, runDiffReview } from "../minima/diff_review.ts";
 import {
   type VerifyConsent,
   groundTruthHooks,
@@ -29,10 +30,12 @@ import {
 } from "../minima/ground_truth.ts";
 import { CostMeter, type HarnessConfig, MinimaAgent, configFromEnv } from "../minima/index.ts";
 import { ConstJudge, LLMJudge } from "../minima/index.ts";
+import { drainMemoryJobs, makeRoutedExtractor } from "../minima/memory_scribe.ts";
 import { createMubitMemory } from "../minima/mubit_memory_factory.ts";
 import { type ChildEvent, createSpawn } from "../minima/spawn.ts";
 import { runJson, runPrint } from "../run_modes.ts";
 import { detectRepo, makeCheckpointHook } from "../session/checkpoint.ts";
+import { reverifyNotice, reverifyOnResume } from "../session/resume_verify.ts";
 import { type AskUserRef, builtinTools, questionTool } from "../tools/index.ts";
 import { taskTool } from "../tools/task.ts";
 import type { TodoTask } from "../tools/todowrite.ts";
@@ -49,6 +52,7 @@ import { buildSystemPrompt } from "../tui/context.ts";
 import { installInputFilter } from "../tui/input-filter.ts";
 import { loadPersistedMode } from "../tui/mode_prefs.ts";
 import { getProject, repoIdentity, setProject } from "../tui/projects.ts";
+import { VERSION } from "../version.ts";
 
 // --- .env loading (cwd) — real env / --env-file wins; file only fills gaps ----------
 const ENV_FILES = [".env.harness", ".env"];
@@ -451,6 +455,13 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   let sink: DbSinkHandle | null = null;
   let initialResume: RehydratedRun | null = null;
   let gtGateBefore: BeforeToolCall | null = null;
+  // B2 memory scribe: drains queued curation jobs (built once db + agent exist; reads
+  // agent.budget at call time since --budget attaches it later).
+  let scribeDrain: (() => Promise<void>) | null = null;
+  // E1 diff reviewer: late-bound — the GT hooks are built before the plan meta model
+  // exists, so closure events route through this ref; the reviewer is armed further down.
+  const planClosedRef: { current: ((planId: string) => void) | null } = { current: null };
+  let pendingDiffReview: Promise<unknown> | null = null;
   const verifyConsentRef: { current: VerifyConsent } = { current: headlessVerifyConsent() };
   try {
     db = new MinimaDb();
@@ -489,6 +500,19 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
       initialResume = rehydrateRun(db, resumeFrom.run_id);
       applyRehydratedRun(agent, initialResume);
       db.setRunParent(runId, resumeFrom.run_id);
+      // D2: re-run the in-progress step's verify against its recorded baseline (the
+      // working tree may have moved while the session was away). Consent-gated like every
+      // verify (headless: MINIMA_TUI_ALLOW_VERIFY=1); warn-only, never blocks the resume.
+      if (config.groundTruth) {
+        const rv = await reverifyOnResume({
+          db,
+          planSessionId: resumeFrom.run_id,
+          eventRunId: runId,
+          consent: (cmd) => verifyConsentRef.current(cmd),
+        });
+        const note = reverifyNotice(rv);
+        if (note) process.stderr.write(`minima: ${note}\n`);
+      }
     }
     // Ground-Truth ledger (M1.1/M2.1/M2.2) + done-gate (M4.1–M4.3): after each tool call the
     // sink keeps the SQLite plan of record in step with what the agent actually did (plan
@@ -507,10 +531,38 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
       const { before, after } = groundTruthHooks(agent, {
         enforceAllowlist: config.toolAllowlist,
         verifyConsent: (cmd) => verifyConsentRef.current(cmd),
+        onPlanClosed: (planId) => planClosedRef.current?.(planId),
       });
       agent.addAfterToolCall(after);
       gtGateBefore = before;
     }
+    // B2 memory scribe: recover jobs a crashed process left `running`, build the drain
+    // (routed extraction, spend booked like judge spend), and clear prior sessions'
+    // leftovers shortly after startup — off the critical path, fail-open throughout.
+    if (config.memoryLedger) {
+      const scribeDb = db;
+      scribeDb.requeueRunningMemoryJobs();
+      scribeDrain = async () => {
+        try {
+          await drainMemoryJobs({
+            db: scribeDb,
+            extract: makeRoutedExtractor({
+              router: agent.router,
+              meter: agent.meter,
+              budget: agent.budget,
+            }),
+            budget: agent.budget,
+            modelExists: (id) => findModelById(id) !== undefined,
+            projectKeyFor: (job) =>
+              (job.session_id ? scribeDb.getRun(job.session_id)?.project_key : null) ?? projectKey,
+          });
+        } catch {
+          // curation must never break a run
+        }
+      };
+      const startupDrain = setTimeout(() => void scribeDrain?.(), 3000);
+      startupDrain.unref?.();
+    }
   } catch (exc) {
     if (args.resume) {
       process.stderr.write(`minima: cannot --resume: persistence unavailable: ${errText(exc)}\n`);
@@ -528,6 +580,27 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
       // shutdown must never fail on bookkeeping
     }
   };
+  // E1: an in-flight diff review gets a bounded window at exit to land its verdict gate;
+  // one that can't finish simply writes nothing (advisory — a skip never degrades a tier).
+  const settleDiffReview = async (): Promise<void> => {
+    if (!pendingDiffReview) return;
+    try {
+      await Promise.race([pendingDiffReview, new Promise<void>((r) => setTimeout(r, 8000))]);
+    } catch {
+      // advisory — never delay shutdown on an error
+    }
+  };
+  // B2: session end enqueues one reflect job and gives the drain a bounded window; a pass
+  // that can't finish here stays queued and the next session's startup drain runs it.
+  const endScribeSafely = async (): Promise<void> => {
+    if (!db || !agent.runId || !scribeDrain) return;
+    try {
+      db.enqueueMemoryJob({ kind: "reflect", sessionId: agent.runId });
+      await Promise.race([scribeDrain(), new Promise<void>((r) => setTimeout(r, 8000))]);
+    } catch {
+      // curation is optional — never delay shutdown on an error
+    }
+  };
 
   // Orchestration: the lead (depth 0) can delegate subtasks to cost-routed child agents.
   // Children get their own routed model, meter, confined tools, and budget slice; their
@@ -552,6 +625,35 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   // Fixed cheap model the plan-mode council uses for keeper/critic/synth completions.
   const planMetaModel = findModelById(agent.config.judgeModel) ?? agent.mapping.defaultModel();
 
+  // E1 zero-context diff reviewer: when a plan closes with every step completed, review
+  // the run's whole diff with fresh eyes (one cheap completion — no plan, no transcript).
+  // Fire-and-forget off the tool dispatch; the exits await it briefly so a one-shot run
+  // still lands its verdict gate. MINIMA_TUI_DIFF_REVIEW=0 opts out.
+  if (
+    process.env.MINIMA_TUI_DIFF_REVIEW !== "0" &&
+    config.groundTruth &&
+    db &&
+    providerKeyPresent(planMetaModel.provider)
+  ) {
+    const reviewDb = db;
+    const reviewTop = detectRepo(process.cwd());
+    planClosedRef.current = (planId) => {
+      if (!reviewTop || !agent.runId) return;
+      const run = reviewDb.getRun(agent.runId);
+      pendingDiffReview = runDiffReview({
+        db: reviewDb,
+        sessionId: agent.runId,
+        planId,
+        metaModel: planMetaModel,
+        diff: collectRunDiff(reviewTop, run?.git_base_sha ?? null),
+        onCostUsd: (usd) => {
+          agent.meter?.addOverhead(usd);
+          agent.budget?.bookSpend(usd, "diff-review");
+        },
+      }).catch(() => null);
+    };
+  }
+
   // The `question` tool lets the model ask the user a structured clarifying question mid-run.
   // The ask callback is late-bound: the TUI populates askUserRef.current once it mounts an
   // overlay; in headless/print modes it stays null and the tool tells the model to proceed.
@@ -561,6 +663,46 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   // same late-bound ask channel once its strikes are spent (null in headless → the run just ends).
   agent.askUser = askUserRef;
 
+  // D1 (v13): stamp every subsequent decision/gate with the running harness + toolset
+  // digest — set here, AFTER the toolset is final (task/question tools included). Resume
+  // compares a run's recorded stamp against this one (warn-only, never a block).
+  if (db) {
+    db.setVersionStamp({
+      harnessVersion: VERSION,
+      toolSchemaHash: toolSchemaHash(agent.agentState.tools),
+    });
+    if (initialResume) {
+      const recorded = db.lastRecordedStamp(initialResume.run.run_id);
+      const current = db.versionStamp;
+      if (
+        recorded.toolSchemaHash &&
+        current.toolSchemaHash &&
+        recorded.toolSchemaHash !== current.toolSchemaHash
+      ) {
+        process.stderr.write(
+          `minima: 🟡 resumed run was recorded under different tooling (harness ${recorded.harnessVersion ?? "?"} → ${current.harnessVersion ?? "?"}) — history may replay imperfectly\n`,
+        );
+        try {
+          if (agent.runId) {
+            db.appendEvent({
+              runId: agent.runId,
+              type: "tooling_mismatch",
+              payload: {
+                resumed_run: initialResume.run.run_id,
+                recorded_hash: recorded.toolSchemaHash,
+                current_hash: current.toolSchemaHash,
+                recorded_version: recorded.harnessVersion,
+                current_version: current.harnessVersion,
+              },
+            });
+          }
+        } catch {
+          // advisory bookkeeping
+        }
+      }
+    }
+  }
+
   // Budget following: --budget creates a session-scoped ledger (warn mode unless
   // --budget-enforce). Threshold events surface to stderr in non-interactive modes; the
   // TUI renders them as chat notices.
@@ -618,6 +760,8 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
       rc = 1;
     } finally {
       await endSessionSafely(agent); // distil the one-shot run into durable memory
+      await endScribeSafely(); // curate the run's ledger signals into the memory ledger
+      await settleDiffReview(); // let an in-flight closure review land its gate
       closeDb(rc === 0 ? "done" : "aborted");
     }
     return rc;
@@ -634,6 +778,26 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
     if (savedMode) setMode(savedMode);
   }
 
+  // B2 quiet-timer: ~90s of tool-call silence marks a natural pause — enqueue a reflect
+  // job and drain in the background. unref'd so the timer never keeps the process alive.
+  if (scribeDrain && db) {
+    const quietDb = db;
+    let quiet: ReturnType<typeof setTimeout> | null = null;
+    agent.addAfterToolCall(async () => {
+      if (quiet) clearTimeout(quiet);
+      quiet = setTimeout(() => {
+        try {
+          if (agent.runId) quietDb.enqueueMemoryJob({ kind: "reflect", sessionId: agent.runId });
+        } catch {
+          // fail-open
+        }
+        void scribeDrain?.();
+      }, 90_000);
+      quiet.unref?.();
+      return null;
+    });
+  }
+
   // One renderer — inline (like Claude Code's REPL): main buffer + Ink <Static> commits finished
   // output to the terminal's NATIVE scrollback, so wheel scroll + click-drag select + copy are
   // all the terminal's own — simultaneously, no mouse capture. installInputFilter strips stray
@@ -680,6 +844,8 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   process.stdout.write("\u001b[?2004l");
   process.stdout.write("\u001b[?25h");
   await endSessionSafely(agent); // reflect + checkpoint this session into durable memory
+  await endScribeSafely(); // curate the run's ledger signals into the memory ledger
+  await settleDiffReview(); // let an in-flight closure review land its gate
   closeDb("done");
   return 0;
 }