@gamaze/hicortex 0.20.9 → 0.20.10

package/dist/calibration.d.ts

@@ -65,6 +65,16 @@ export declare const NOVELTY_FLOOR_SLOTS = 2;
 /** Turns an already-shown memory stays suppressed in the same session before
  *  it may reappear in the pushed index (#192 turn-based dedup). */
 export declare const RECALL_RESHOW_TURNS = 30;
+/** uses_per_showing below this reads Low on the console band.
+ *  PROVISIONAL (owner anchor 2026-09-13, #426). */
+export declare const RECALL_USES_LOW_MAX = 0.05;
+/** uses_per_showing below this (and ≥ RECALL_USES_LOW_MAX) reads Normal.
+ *  PROVISIONAL (owner anchor 2026-09-13, #426). */
+export declare const RECALL_USES_NORMAL_MAX = 0.25;
+/** Display-axis maximum for the console band (the marker clamps here).
+ *  PROVISIONAL (owner anchor 2026-09-13, #426) — chosen so Overfetching
+ *  keeps a visible span, not a measured bound. */
+export declare const RECALL_USES_AXIS_MAX = 0.3;
 /** Semantic-similarity share of the composite score. 0.50 (raised from 0.40
  *  in the 0.15.2 rebalance, #191 Phase B): on the production corpus effective
  *  strength (0.30) outweighed what similarity could recover — hardened old
@@ -106,9 +116,48 @@ export declare const RRF_FTS_WEIGHT = 0.5;
 /** #205 per-list RRF weight for the vector list (vec stays at 1.0 — the
  *  conservative nudge is on the FTS side only). */
 export declare const RRF_VECTOR_WEIGHT = 1;
+/**
+ * Additive boost for candidates the TWO retrieval channels AGREE on
+ * (vector KNN AND BM25 FTS both matched — computeScore option
+ * `bothChannel`). #425 (owner decision D3, 2026-09-13): the two-channel
+ * signal is the genuine-match signature and is immune to FTS-only token
+ * collisions, which is why the boost lives in the composite score, not in
+ * the RRF FTS weight (raising that re-opens the #205 cross-scope collision
+ * it fixed). D3's dominance property: a both-channel match outranks a
+ * single-channel rival unless the rival is >0.10 more similar — at the
+ * shipped simWeight 0.50, 0.10 gives that property 2x headroom (a rival
+ * needs >0.20 more similarity).
+ *
+ * SIZING (the #425 sweep, 2026-09-13, production snapshot copy: case-1
+ * planted fixture + a 30-query real battery vs the boost-0 baseline): every
+ * value in {0.05, 0.10, 0.15} passed the hard gates (exact-match rank-1,
+ * no-match byte-stability, zero both-channel exact-match losses, the
+ * Sirnäs flip) with IDENTICAL battery stability (96.7% top-1 ex-promotions
+ * — every raw change was a both-channel exact match displacing a
+ * single-channel row, the property firing); they differed only in case-1
+ * margin (0.021 / 0.061 / 0.101) and per-id top-3 churn. 0.10 chosen:
+ * 0.05's margin is within one embedder revision of flipping, 0.15 churns
+ * more for no gate benefit. Weight rebalances measured WORSE (sim .55/str
+ * .15 → 93.3%; sim .60/str .10 → 86.7%, fails the 90% gate) — the
+ * SCORE_*_WEIGHT values stay as shipped. ZERO-boost neutral (never a
+ * penalty): graph-only and single-channel candidates add nothing.
+ */
+export declare const BOTH_CHANNEL_BOOST = 0.1;
 export declare const BM25_WEIGHT_BODY = 1;
 export declare const BM25_WEIGHT_PROJECT = 2;
 export declare const BM25_WEIGHT_DOMAIN = 2;
+/**
+ * Write cap on base_strength / importance (#425, owner decision D2
+ * 2026-09-13: cap 0.95). The decay model's rate is `1 − BASE_DECAY·(1 −
+ * importance)` — at importance exactly 1.0 the rate is exactly 1.0 and the
+ * row NEVER decays (measured on the production snapshot: ~14% of live rows
+ * pegged at ≥0.999, 1838/17399 at exactly 1.0). The cap kills the
+ * immortality cliff at every write site (stageImportance, enrich, hub
+ * boost) while keeping a multi-year half-life for the top band (0.95 →
+ * ~13 years). effectiveStrength ALSO clamps the read side, so legacy
+ * base-1.0 rows decay again.
+ */
+export declare const IMPORTANCE_CEILING = 0.95;
 /** Deterministic merge ceiling of the unified resolution pass (#392): pairs
  *  at/above this cosine merge LLM-free; [CORRECTION_MIN_SIMILARITY, this)
  *  get the one verdict call. 0.92 — measured on the #191 mechanical audit
@@ -130,6 +179,76 @@ export declare const CORRECTION_REWRITE_MIN_CONFIDENCE = 0.8;
  *  memory to earn a WEAK primary instead of decaying (owner amendment
  *  07.07). Starting point for bge-small-en-v1.5. */
 export declare const WEAK_PRIMARY_FLOOR = 0.45;
+/**
+ * Console stage bands (#409/#421) — TWO #408-contract calibrations:
+ *
+ * (1) 2026-09-13 (PR #424 fix round) against the INFLATED distribution:
+ *     effectiveStrength p25 = 0.599, p50 = 0.788, p86 = 0.900, ~14%
+ *     saturated at exactly 1.000 → edges 0.40/0.60/0.90 targeting a rendered
+ *     split ≈ 10/15/61/14 (fading/forming/belief/truth).
+ *
+ * (2) This release (#425) against the POST-FIX distribution: the importance
+ *     recalibration (re-anchored prompt + 0.95 cap) plus the
+ *     rescore-importance backfill re-spread the same 17,399-row store to
+ *     base_strength median 0.40 / p90 0.60 / max 0.90 (zero rows ≥ 0.999);
+ *     measured effectiveStrength on the backfilled copy: p25 ≈ 0.296,
+ *     p50 ≈ 0.397, p75 ≈ 0.497, p86 ≈ 0.585, max ≈ 0.900. The stale 2026-09-13
+ *     edges rendered that store as 58.5/37.2/4.2/0 — no Truth left. These
+ *     edges (0.20/0.30/0.58) re-derive the same ≈ 10/15/61/14 split intent
+ *     against the honest distribution and render 11.8/25.6/47.7/14.9 (the
+ *     scorer emits one-decimal scores, so the mass clusters at exact atoms —
+ *     0.20/0.30/0.60 — and the 0.60 atom alone holds ~12% of the store; the
+ *     truth edge therefore sits at 0.58, just under the atom, rather than on
+ *     the round number that would strand it). Evidence: the #425
+ *     post-backfill band-stats photo (backfilled copy, deriveStage math via
+ *     the production effectiveStrength).
+ */
+/**
+ * Days without access after which a memory's derived stage is Fading
+ * (regardless of strength — the recency gate runs FIRST in deriveStage).
+ * 120 ≈ a season: long enough that a working memory is never mislabeled,
+ * short enough that the rim of the field turns over within a year.
+ */
+export declare const STAGE_FADING_DAYS = 120;
+/**
+ * Effective-strength ceiling of the living bands: below this the memory is
+ * Fading (the measured weak cluster + the recency-gated rim, together ~12% of
+ * the post-#425 store) even when recently touched.
+ */
+export declare const STAGE_FADING_STRENGTH = 0.2;
+/** The Forming/Belief edge: [FADING, this) → forming, ≥ this → belief. */
+export declare const STAGE_BELIEF_STRENGTH = 0.3;
+/** The Belief/Truth edge: ≥ this → truth — the hardened core (~15% post-#425;
+ *  just under the 0.60 score atom, see the block JSDoc above). */
+export declare const STAGE_TRUTH_STRENGTH = 0.58;
+/**
+ * One owner corroboration's bump to base_strength (#423 phase 3, POST
+ * /enrich — evidence about importance). Post-#425 the forming band
+ * [0.20,0.30) is 0.10 wide; +0.10 = a full band — one enrich visibly crosses
+ * an edge for a mid-band Forming memory. Repeated enriches cap at the
+ * IMPORTANCE_CEILING (0.95, the SQL MIN); for a young memory effStr ≈ base so
+ * the bump lands ~1:1 (the phase-3 verify "enrich a Forming memory → stage
+ * change" holds for a mid-band memory ≥0.25).
+ */
+export declare const ENRICH_STRENGTH_DELTA = 0.1;
+/**
+ * Days of session history a FIRST nightly run discovers (the first-run
+ * watermark is now − this many days, not the epoch).
+ *
+ * Owner ruling (2026-09-14, #436): full-history first-run ingestion is not
+ * feasible — "if everybody signing up ingests their full history, we will
+ * pay millions in tokens during the trial period before customers pay us
+ * anything." Cloud needs a very short window; the local/installable version
+ * uses the SAME default.
+ *
+ * Unlike every other constant in this module, this one KEEPS a config
+ * override (`firstRunLookbackDays`, read at the capture call sites): it
+ * describes an install's cost posture — the same family as
+ * `llmTokensPerMonth` / `captureCooldownHours`, which stayed config through
+ * #408 — not brain tuning. More history is a deliberate act:
+ * `hicortex nightly --recapture-window <days>`.
+ */
+export declare const DEFAULT_FIRST_RUN_LOOKBACK_DAYS = 7;
 /**
  * Context window for ollama (one value, all phases; #220/#228). 8192 is
  * where context stops being the binding constraint for a sub-8B model on

package/dist/calibration.js

@@ -24,7 +24,7 @@
  * the removal is never silent.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DIAGNOSTIC_ENV_TIER = exports.OLLAMA_FLUSH_WAIT_MS = exports.OLLAMA_FLUSH_EVERY = exports.NUM_CTX = exports.WEAK_PRIMARY_FLOOR = exports.CORRECTION_REWRITE_MIN_CONFIDENCE = exports.CORRECTION_MIN_SIMILARITY = exports.SUPERSESSION_MIN_SIMILARITY = exports.DEDUP_AUTO_MERGE_THRESHOLD = exports.BM25_WEIGHT_DOMAIN = exports.BM25_WEIGHT_PROJECT = exports.BM25_WEIGHT_BODY = exports.RRF_VECTOR_WEIGHT = exports.RRF_FTS_WEIGHT = exports.RRF_COMPOSITE_WEIGHT = exports.RRF_K = exports.DOMAIN_AFFINITY_WEIGHT = exports.PROJECT_AFFINITY_WEIGHT = exports.SUPERSEDED_DEMOTION = exports.FRESHNESS_BOOST_WEIGHT = exports.FRESHNESS_BOOST_DAYS = exports.SCORE_RECENCY_WEIGHT = exports.SCORE_CONNECTIONS_WEIGHT = exports.SCORE_STRENGTH_WEIGHT = exports.SCORE_SIMILARITY_WEIGHT = exports.RECALL_RESHOW_TURNS = exports.NOVELTY_FLOOR_SLOTS = exports.RECALL_TITLE_CHARS = exports.RECALL_MIN_PROMPT_CHARS = exports.RECALL_MAX_ITEMS = exports.RECALL_MIN_SIMILARITY = exports.SESSION_INTENT_WEIGHT = exports.COLD_EXPOSURE_SLOTS = exports.RECENT_WINDOW_DAYS = exports.RECENT_LIMIT = exports.SEARCH_LIMIT = exports.DECAY_HALF_LIFE_DAYS = void 0;
+exports.DIAGNOSTIC_ENV_TIER = exports.OLLAMA_FLUSH_WAIT_MS = exports.OLLAMA_FLUSH_EVERY = exports.NUM_CTX = exports.DEFAULT_FIRST_RUN_LOOKBACK_DAYS = exports.ENRICH_STRENGTH_DELTA = exports.STAGE_TRUTH_STRENGTH = exports.STAGE_BELIEF_STRENGTH = exports.STAGE_FADING_STRENGTH = exports.STAGE_FADING_DAYS = exports.WEAK_PRIMARY_FLOOR = exports.CORRECTION_REWRITE_MIN_CONFIDENCE = exports.CORRECTION_MIN_SIMILARITY = exports.SUPERSESSION_MIN_SIMILARITY = exports.DEDUP_AUTO_MERGE_THRESHOLD = exports.IMPORTANCE_CEILING = exports.BM25_WEIGHT_DOMAIN = exports.BM25_WEIGHT_PROJECT = exports.BM25_WEIGHT_BODY = exports.BOTH_CHANNEL_BOOST = exports.RRF_VECTOR_WEIGHT = exports.RRF_FTS_WEIGHT = exports.RRF_COMPOSITE_WEIGHT = exports.RRF_K = exports.DOMAIN_AFFINITY_WEIGHT = exports.PROJECT_AFFINITY_WEIGHT = exports.SUPERSEDED_DEMOTION = exports.FRESHNESS_BOOST_WEIGHT = exports.FRESHNESS_BOOST_DAYS = exports.SCORE_RECENCY_WEIGHT = exports.SCORE_CONNECTIONS_WEIGHT = exports.SCORE_STRENGTH_WEIGHT = exports.SCORE_SIMILARITY_WEIGHT = exports.RECALL_USES_AXIS_MAX = exports.RECALL_USES_NORMAL_MAX = exports.RECALL_USES_LOW_MAX = exports.RECALL_RESHOW_TURNS = exports.NOVELTY_FLOOR_SLOTS = exports.RECALL_TITLE_CHARS = exports.RECALL_MIN_PROMPT_CHARS = exports.RECALL_MAX_ITEMS = exports.RECALL_MIN_SIMILARITY = exports.SESSION_INTENT_WEIGHT = exports.COLD_EXPOSURE_SLOTS = exports.RECENT_WINDOW_DAYS = exports.RECENT_LIMIT = exports.SEARCH_LIMIT = exports.DECAY_HALF_LIFE_DAYS = void 0;
 exports.resolveNumCtx = resolveNumCtx;
 exports.resolveOllamaFlushEvery = resolveOllamaFlushEvery;
 exports.resolveOllamaFlushWaitMs = resolveOllamaFlushWaitMs;
@@ -76,6 +76,26 @@ exports.NOVELTY_FLOOR_SLOTS = 2;
 /** Turns an already-shown memory stays suppressed in the same session before
  *  it may reappear in the pushed index (#192 turn-based dedup). */
 exports.RECALL_RESHOW_TURNS = 30;
+// Recall-uses band (console) — PROVISIONAL zone edges. Owner anchor
+// 2026-09-13 (#426 final ruling): the console renders uses-per-showing on a
+// red→green→red band with three zones (Low / Normal / Overfetching; owner
+// confirmed "3 bands is fine"). The owner's calibration state is explicit —
+// "we have no clue on how to calibrate yet" — so these edges are provisional
+// anchors from #426's owner-anchor record, NOT measured boundaries; fleet
+// telemetry is expected to move them (the console marks the band
+// "provisional" and renders no edge numerics). They position zone boundaries
+// on the console's gradient and classify the marker's zone word; they gate
+// nothing server-side.
+/** uses_per_showing below this reads Low on the console band.
+ *  PROVISIONAL (owner anchor 2026-09-13, #426). */
+exports.RECALL_USES_LOW_MAX = 0.05;
+/** uses_per_showing below this (and ≥ RECALL_USES_LOW_MAX) reads Normal.
+ *  PROVISIONAL (owner anchor 2026-09-13, #426). */
+exports.RECALL_USES_NORMAL_MAX = 0.25;
+/** Display-axis maximum for the console band (the marker clamps here).
+ *  PROVISIONAL (owner anchor 2026-09-13, #426) — chosen so Overfetching
+ *  keeps a visible span, not a measured bound. */
+exports.RECALL_USES_AXIS_MAX = 0.30;
 // ---------------------------------------------------------------------------
 // Composite ranking weights (was: score*Weight, freshnessBoost*,
 // supersededDemotion, *AffinityWeight, rrf*)
@@ -121,6 +141,33 @@ exports.RRF_FTS_WEIGHT = 0.5;
 /** #205 per-list RRF weight for the vector list (vec stays at 1.0 — the
  *  conservative nudge is on the FTS side only). */
 exports.RRF_VECTOR_WEIGHT = 1.0;
+/**
+ * Additive boost for candidates the TWO retrieval channels AGREE on
+ * (vector KNN AND BM25 FTS both matched — computeScore option
+ * `bothChannel`). #425 (owner decision D3, 2026-09-13): the two-channel
+ * signal is the genuine-match signature and is immune to FTS-only token
+ * collisions, which is why the boost lives in the composite score, not in
+ * the RRF FTS weight (raising that re-opens the #205 cross-scope collision
+ * it fixed). D3's dominance property: a both-channel match outranks a
+ * single-channel rival unless the rival is >0.10 more similar — at the
+ * shipped simWeight 0.50, 0.10 gives that property 2x headroom (a rival
+ * needs >0.20 more similarity).
+ *
+ * SIZING (the #425 sweep, 2026-09-13, production snapshot copy: case-1
+ * planted fixture + a 30-query real battery vs the boost-0 baseline): every
+ * value in {0.05, 0.10, 0.15} passed the hard gates (exact-match rank-1,
+ * no-match byte-stability, zero both-channel exact-match losses, the
+ * Sirnäs flip) with IDENTICAL battery stability (96.7% top-1 ex-promotions
+ * — every raw change was a both-channel exact match displacing a
+ * single-channel row, the property firing); they differed only in case-1
+ * margin (0.021 / 0.061 / 0.101) and per-id top-3 churn. 0.10 chosen:
+ * 0.05's margin is within one embedder revision of flipping, 0.15 churns
+ * more for no gate benefit. Weight rebalances measured WORSE (sim .55/str
+ * .15 → 93.3%; sim .60/str .10 → 86.7%, fails the 90% gate) — the
+ * SCORE_*_WEIGHT values stay as shipped. ZERO-boost neutral (never a
+ * penalty): graph-only and single-channel candidates add nothing.
+ */
+exports.BOTH_CHANNEL_BOOST = 0.10;
 // ---------------------------------------------------------------------------
 // BM25F field weights (was: bm25WeightBody/Project/Domain) — #205. Body is
 // down-weighted relative to the scope fields so a project/domain token match
@@ -134,6 +181,18 @@ exports.BM25_WEIGHT_DOMAIN = 2.0;
 // dedupMergeThreshold], supersessionMinSimilarity, correctionMinSimilarity,
 // correctionRewriteMinConfidence, weakPrimaryFloor)
 // ---------------------------------------------------------------------------
+/**
+ * Write cap on base_strength / importance (#425, owner decision D2
+ * 2026-09-13: cap 0.95). The decay model's rate is `1 − BASE_DECAY·(1 −
+ * importance)` — at importance exactly 1.0 the rate is exactly 1.0 and the
+ * row NEVER decays (measured on the production snapshot: ~14% of live rows
+ * pegged at ≥0.999, 1838/17399 at exactly 1.0). The cap kills the
+ * immortality cliff at every write site (stageImportance, enrich, hub
+ * boost) while keeping a multi-year half-life for the top band (0.95 →
+ * ~13 years). effectiveStrength ALSO clamps the read side, so legacy
+ * base-1.0 rows decay again.
+ */
+exports.IMPORTANCE_CEILING = 0.95;
 /** Deterministic merge ceiling of the unified resolution pass (#392): pairs
  *  at/above this cosine merge LLM-free; [CORRECTION_MIN_SIMILARITY, this)
  *  get the one verdict call. 0.92 — measured on the #191 mechanical audit
@@ -156,6 +215,95 @@ exports.CORRECTION_REWRITE_MIN_CONFIDENCE = 0.80;
  *  07.07). Starting point for bge-small-en-v1.5. */
 exports.WEAK_PRIMARY_FLOOR = 0.45;
 // ---------------------------------------------------------------------------
+// Console presentation family (#409/#421) — stage thresholds for the
+// /dashboard console. The STAGE BANDS are calibrated per release against the
+// MEASURED distribution (2026-09-13 against the inflated store; this release
+// re-derived against the post-#425 backfilled store — see the block JSDoc
+// immediately below). The recall-grade zones that used to
+// live here are REMOVED per the owner semantics ruling 2026-09-13 (#426):
+// recall depends only on the conversation — "if the index is good enough for
+// the context needed, it does not have to be fetched" — so a graded
+// Low/Medium/Good/Excellent scale is the wrong instrument (higher is not a
+// target that exists). The console shows the raw uses-per-showing ratio + a
+// trend; the reference expectations for reading that number live on #426,
+// not in shipped bands. The evolution contract still applies to the stage
+// bands: they move only in releases, with the eval / band-stats evidence
+// linked in the changelog line that moves them.
+// ---------------------------------------------------------------------------
+/**
+ * Console stage bands (#409/#421) — TWO #408-contract calibrations:
+ *
+ * (1) 2026-09-13 (PR #424 fix round) against the INFLATED distribution:
+ *     effectiveStrength p25 = 0.599, p50 = 0.788, p86 = 0.900, ~14%
+ *     saturated at exactly 1.000 → edges 0.40/0.60/0.90 targeting a rendered
+ *     split ≈ 10/15/61/14 (fading/forming/belief/truth).
+ *
+ * (2) This release (#425) against the POST-FIX distribution: the importance
+ *     recalibration (re-anchored prompt + 0.95 cap) plus the
+ *     rescore-importance backfill re-spread the same 17,399-row store to
+ *     base_strength median 0.40 / p90 0.60 / max 0.90 (zero rows ≥ 0.999);
+ *     measured effectiveStrength on the backfilled copy: p25 ≈ 0.296,
+ *     p50 ≈ 0.397, p75 ≈ 0.497, p86 ≈ 0.585, max ≈ 0.900. The stale 2026-09-13
+ *     edges rendered that store as 58.5/37.2/4.2/0 — no Truth left. These
+ *     edges (0.20/0.30/0.58) re-derive the same ≈ 10/15/61/14 split intent
+ *     against the honest distribution and render 11.8/25.6/47.7/14.9 (the
+ *     scorer emits one-decimal scores, so the mass clusters at exact atoms —
+ *     0.20/0.30/0.60 — and the 0.60 atom alone holds ~12% of the store; the
+ *     truth edge therefore sits at 0.58, just under the atom, rather than on
+ *     the round number that would strand it). Evidence: the #425
+ *     post-backfill band-stats photo (backfilled copy, deriveStage math via
+ *     the production effectiveStrength).
+ */
+/**
+ * Days without access after which a memory's derived stage is Fading
+ * (regardless of strength — the recency gate runs FIRST in deriveStage).
+ * 120 ≈ a season: long enough that a working memory is never mislabeled,
+ * short enough that the rim of the field turns over within a year.
+ */
+exports.STAGE_FADING_DAYS = 120;
+/**
+ * Effective-strength ceiling of the living bands: below this the memory is
+ * Fading (the measured weak cluster + the recency-gated rim, together ~12% of
+ * the post-#425 store) even when recently touched.
+ */
+exports.STAGE_FADING_STRENGTH = 0.20;
+/** The Forming/Belief edge: [FADING, this) → forming, ≥ this → belief. */
+exports.STAGE_BELIEF_STRENGTH = 0.30;
+/** The Belief/Truth edge: ≥ this → truth — the hardened core (~15% post-#425;
+ *  just under the 0.60 score atom, see the block JSDoc above). */
+exports.STAGE_TRUTH_STRENGTH = 0.58;
+/**
+ * One owner corroboration's bump to base_strength (#423 phase 3, POST
+ * /enrich — evidence about importance). Post-#425 the forming band
+ * [0.20,0.30) is 0.10 wide; +0.10 = a full band — one enrich visibly crosses
+ * an edge for a mid-band Forming memory. Repeated enriches cap at the
+ * IMPORTANCE_CEILING (0.95, the SQL MIN); for a young memory effStr ≈ base so
+ * the bump lands ~1:1 (the phase-3 verify "enrich a Forming memory → stage
+ * change" holds for a mid-band memory ≥0.25).
+ */
+exports.ENRICH_STRENGTH_DELTA = 0.10;
+// ---------------------------------------------------------------------------
+// Capture / first-run cost family (#436)
+// ---------------------------------------------------------------------------
+/**
+ * Days of session history a FIRST nightly run discovers (the first-run
+ * watermark is now − this many days, not the epoch).
+ *
+ * Owner ruling (2026-09-14, #436): full-history first-run ingestion is not
+ * feasible — "if everybody signing up ingests their full history, we will
+ * pay millions in tokens during the trial period before customers pay us
+ * anything." Cloud needs a very short window; the local/installable version
+ * uses the SAME default.
+ *
+ * Unlike every other constant in this module, this one KEEPS a config
+ * override (`firstRunLookbackDays`, read at the capture call sites): it
+ * describes an install's cost posture — the same family as
+ * `llmTokensPerMonth` / `captureCooldownHours`, which stayed config through
+ * #408 — not brain tuning. More history is a deliberate act:
+ * `hicortex nightly --recapture-window <days>`.
+ */
+exports.DEFAULT_FIRST_RUN_LOOKBACK_DAYS = 7;
+// ---------------------------------------------------------------------------
 // Diagnostic tier (env-overridable — #408). The ollama-operational family is
 // NOT user tuning: it exists so an operator of a constrained box can pin the
 // three values into a service unit's environment without a config-file

package/dist/capture-health.d.ts

@@ -0,0 +1,87 @@
+/**
+ * /distill capture-health accounting (#422 Phase 2).
+ *
+ * BOTH halves of the console's capture-health card live here (the same
+ * layering as recall-index.ts / identity-store.ts: pure logic, unit-testable
+ * without booting express — mcp-server.ts only wires the record calls into
+ * the /distill exits):
+ *
+ *  - recordDistillActivity(db, entry) — one row per /distill POST, whatever
+ *    the outcome ('ok' | 'skipped' | 'held'). Held rows are the point: they
+ *    are the failed posts the client will retry next run (its cursor is
+ *    held), so the card can show "2 held" instead of a silently missing
+ *    night. `retried` is computed at INSERT (an earlier row with the same
+ *    session_id + segment_id = this POST is the retry) and never updated.
+ *
+ *  - readCaptureHealth(db) — the aggregation /dashboard/data exposes as
+ *    `capture_health`: the most recent day with rows, grouped by machine ×
+ *    agent (posts / sessions / bytes / held / retried), bytes DESC.
+ *
+ * Retention: 7 days, pruned inside recordDistillActivity at most ONCE per
+ * process per UTC day (in-module memo) — the insert path must not pay a
+ * DELETE on every POST. Old rows exist to explain recent nights, nothing
+ * else; the durable record of WHAT was captured is the memories themselves.
+ */
+import type Database from "better-sqlite3";
+/** A /distill POST outcome. 'held' = the client will retry (cursor held):
+ *  no-LLM, dead-endpoint probe, budget 429, distill failure. 'skipped' = a
+ *  duplicate the dedup prechecks rejected (nothing owed). 'ok' = stored.
+ *  'paused' (#423 phase 3, D3) = deliberately skipped by the operator's
+ *  capture pause — the session is NOT captured and will not be backfilled
+ *  (the 200 advances the client's cursor by design). */
+export type DistillOutcome = "ok" | "skipped" | "held" | "paused";
+/** One /distill POST to record. The wire fields arrive as-is from the request
+ *  body (machine/agent/sessionId/segmentId may be absent or mistyped) —
+ *  normalization happens HERE so every handler call site is a one-liner. */
+export interface DistillActivityEntry {
+    /** ISO timestamp of the POST; defaults to now. */
+    ts?: string;
+    /** Raw source_machine wire value — sanitized via storage.sanitizeSourceMachine, '' when absent. */
+    machine: unknown;
+    /** Raw source_agent wire value — 'unknown' when absent/blank. */
+    agent: unknown;
+    /** Raw session_id wire value — stored when a non-empty string, else NULL. */
+    sessionId: unknown;
+    /** Raw segment_id wire value — stored when a non-empty string, else NULL. */
+    segmentId: unknown;
+    /** Resolved conversationText length (post-redaction), 0 when unresolved. */
+    bytes: number;
+    outcome: DistillOutcome;
+}
+/** One aggregated machine × agent row of readCaptureHealth(). */
+export interface CaptureHealthRow {
+    machine: string;
+    agent: string;
+    posts: number;
+    sessions: number;
+    bytes: number;
+    held: number;
+    retried: number;
+}
+/** The /dashboard/data capture_health block. day=null + rows=[] when nothing
+ *  is recorded (fresh install, or every row pruned). */
+export interface CaptureHealth {
+    day: string | null;
+    rows: CaptureHealthRow[];
+}
+/** Test-only: re-arm the once-per-day prune memo. The memo is deliberately
+ *  process-global (production must not DELETE per insert); the test suite
+ *  needs it fresh per case. Exported for testability, same precedent as
+ *  quarantineMalformedConfig. */
+export declare function resetDistillPruneMemoForTests(): void;
+/**
+ * Record one /distill POST outcome. Computes `retried` at insert: 1 when an
+ * EARLIER row exists with the same session_id AND same segment_id (matched on
+ * COALESCE(segment_id, '') so legacy whole-session POSTs — no segment_id —
+ * retry-match on the empty key). A NULL session_id never matches anything:
+ * without a session id the POST has no identity to be a retry OF. Also prunes
+ * rows older than 7 days, at most once per process per UTC day.
+ */
+export declare function recordDistillActivity(db: Database.Database, entry: DistillActivityEntry): void;
+/**
+ * Aggregate the most recent day with rows into per machine × agent bundles.
+ * day = today when today has rows, else the most recent day with rows, else
+ * null (empty shape). sessions = COUNT(DISTINCT session_id) — NULL session
+ * ids don't count (no identity). Sorted bytes DESC (the card's bar scale).
+ */
+export declare function readCaptureHealth(db: Database.Database): CaptureHealth;

package/dist/capture-health.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * /distill capture-health accounting (#422 Phase 2).
+ *
+ * BOTH halves of the console's capture-health card live here (the same
+ * layering as recall-index.ts / identity-store.ts: pure logic, unit-testable
+ * without booting express — mcp-server.ts only wires the record calls into
+ * the /distill exits):
+ *
+ *  - recordDistillActivity(db, entry) — one row per /distill POST, whatever
+ *    the outcome ('ok' | 'skipped' | 'held'). Held rows are the point: they
+ *    are the failed posts the client will retry next run (its cursor is
+ *    held), so the card can show "2 held" instead of a silently missing
+ *    night. `retried` is computed at INSERT (an earlier row with the same
+ *    session_id + segment_id = this POST is the retry) and never updated.
+ *
+ *  - readCaptureHealth(db) — the aggregation /dashboard/data exposes as
+ *    `capture_health`: the most recent day with rows, grouped by machine ×
+ *    agent (posts / sessions / bytes / held / retried), bytes DESC.
+ *
+ * Retention: 7 days, pruned inside recordDistillActivity at most ONCE per
+ * process per UTC day (in-module memo) — the insert path must not pay a
+ * DELETE on every POST. Old rows exist to explain recent nights, nothing
+ * else; the durable record of WHAT was captured is the memories themselves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetDistillPruneMemoForTests = resetDistillPruneMemoForTests;
+exports.recordDistillActivity = recordDistillActivity;
+exports.readCaptureHealth = readCaptureHealth;
+const storage_js_1 = require("./storage.js");
+/** Once-per-process-per-UTC-day prune memo (see module doc). The UTC day of
+ *  the last insert that ran the DELETE. Tests reset it because vitest runs
+ *  every suite in ONE process — see resetDistillPruneMemoForTests. */
+let lastPruneDay = null;
+/** Test-only: re-arm the once-per-day prune memo. The memo is deliberately
+ *  process-global (production must not DELETE per insert); the test suite
+ *  needs it fresh per case. Exported for testability, same precedent as
+ *  quarantineMalformedConfig. */
+function resetDistillPruneMemoForTests() {
+    lastPruneDay = null;
+}
+/** Normalize an optional wire string: non-empty trimmed string, else null. */
+function optString(v) {
+    if (typeof v !== "string")
+        return null;
+    const t = v.trim();
+    return t.length > 0 ? t : null;
+}
+/**
+ * Record one /distill POST outcome. Computes `retried` at insert: 1 when an
+ * EARLIER row exists with the same session_id AND same segment_id (matched on
+ * COALESCE(segment_id, '') so legacy whole-session POSTs — no segment_id —
+ * retry-match on the empty key). A NULL session_id never matches anything:
+ * without a session id the POST has no identity to be a retry OF. Also prunes
+ * rows older than 7 days, at most once per process per UTC day.
+ */
+function recordDistillActivity(db, entry) {
+    const ts = entry.ts ?? new Date().toISOString();
+    // UTC YYYY-MM-DD of ts — day buckets are UTC everywhere (dashboard
+    // conventions; SQLite date('now') is UTC too).
+    const day = ts.slice(0, 10);
+    const sessionId = optString(entry.sessionId);
+    const segmentId = optString(entry.segmentId);
+    // Retry detection BEFORE the insert (the new row must not match itself).
+    // `IS ?` binds NULL correctly for the session half.
+    const retried = sessionId !== null &&
+        (db
+            .prepare("SELECT 1 FROM distill_activity WHERE session_id IS ? AND COALESCE(segment_id, '') = ? LIMIT 1")
+            .get(sessionId, segmentId ?? "") !== undefined)
+        ? 1
+        : 0;
+    db.prepare(`INSERT INTO distill_activity (ts, day, machine, agent, session_id, segment_id, bytes, outcome, retried)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(ts, day, (0, storage_js_1.sanitizeSourceMachine)(entry.machine) ?? "", optString(entry.agent) ?? "unknown", sessionId, segmentId, entry.bytes, entry.outcome, retried);
+    // Prune, at most once per process per UTC day. Runs AFTER the insert so the
+    // triggering row is subject to the same window as everything else.
+    if (lastPruneDay !== day) {
+        db.prepare("DELETE FROM distill_activity WHERE day < date('now', '-7 days')").run();
+        lastPruneDay = day;
+    }
+}
+/**
+ * Aggregate the most recent day with rows into per machine × agent bundles.
+ * day = today when today has rows, else the most recent day with rows, else
+ * null (empty shape). sessions = COUNT(DISTINCT session_id) — NULL session
+ * ids don't count (no identity). Sorted bytes DESC (the card's bar scale).
+ */
+function readCaptureHealth(db) {
+    const dayRow = db
+        .prepare("SELECT MAX(day) AS day FROM distill_activity")
+        .get();
+    if (!dayRow.day)
+        return { day: null, rows: [] };
+    const rows = db
+        .prepare(`SELECT machine, agent,
+              COUNT(*) AS posts,
+              COUNT(DISTINCT session_id) AS sessions,
+              COALESCE(SUM(bytes), 0) AS bytes,
+              COALESCE(SUM(outcome = 'held'), 0) AS held,
+              COALESCE(SUM(retried), 0) AS retried
+         FROM distill_activity
+        WHERE day = ?
+        GROUP BY machine, agent
+        ORDER BY bytes DESC`)
+        .all(dayRow.day);
+    return { day: dayRow.day, rows };
+}

package/dist/capture-pause.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Operator capture pause (#423 phase 3, D3) — the server-side 200-skip.
+ *
+ * A pause is a row in `capture_pauses` (migration v18): machine × harness →
+ * paused_at. A row EXISTS = paused for that bundle; the /distill handler
+ * reads the table per POST, so a pause takes effect on the very next post —
+ * no restart — and answers 200 {skipped: true, paused: true}. The 200 is the
+ * whole point: capture.ts treats every 200 as confirmed and advances its
+ * cursor, so sessions that arrive while paused are deliberately NOT captured
+ * and are never re-sent or backfilled. Zero client changes.
+ *
+ * THE BUNDLE KEY. The pause's (machine, harness) must derive EXACTLY like
+ * the traffic it gates: machine via storage.sanitizeSourceMachine ('' when
+ * absent) and harness via harnessOfAgent below — the same normalization
+ * recordDistillActivity applies when it writes distill_activity, and the same
+ * "harness/profile" → "harness" split the console groups its bundles on. A
+ * key derived any other way would never match and the pause would silently
+ * not fire.
+ *
+ * LAST-SEEN (presence dots) derives ONLY from /distill activity — the one
+ * per-agent-identified traffic the server sees. Recall traffic (/search,
+ * /recall-index, /memory) carries no agent/machine identity on the wire, so
+ * attributing it would need new client fields — the heartbeats the spec
+ * forbids. Thresholds (green ≤36h — a nightly poster reads online through
+ * the following day; amber ≤7d — the distill_activity retention window; none
+ * beyond or with no rows) are page-side presentation; this module just
+ * reports the newest ts per bundle.
+ *
+ * Pure, unit-testable without express (the capture-health.ts layering):
+ * mcp-server.ts and dashboard.ts wire these functions to the live db.
+ */
+import type Database from "better-sqlite3";
+/** The bundle half of a pause key: "harness/profile" → "harness". */
+export interface CapturePauseKey {
+    /** Sanitized machine ('' when the post carried none) — matches distill_activity. */
+    machine: string;
+    /** The harness name (pre-slash part, 128-char cap; 'unknown' when absent/blank). */
+    harness: string;
+}
+/** One paused bundle as the dashboard fleet block serves it. */
+export interface CapturePause {
+    machine: string;
+    harness: string;
+    paused_at: string;
+}
+/** One bundle's newest /distill activity row (the presence signal). */
+export interface FleetLastSeen {
+    machine: string;
+    harness: string;
+    last_seen: string;
+    /** The outcome of that newest row ('ok' | 'skipped' | 'held' | 'paused'). */
+    last_outcome: string;
+}
+/**
+ * Derive the harness from a source_agent wire value — the bundle split the
+ * console already uses ("claude-code/main" → "claude-code"): the part before
+ * the first '/' when a slash is present at index > 0, else the whole trimmed
+ * string, capped at 128. Non-string/blank → "unknown" (mirrors how
+ * recordDistillActivity stores the agent when absent).
+ */
+export declare function harnessOfAgent(sourceAgent: unknown): string;
+/**
+ * Normalize the raw /distill wire fields into the pause key. MUST match the
+ * recordDistillActivity normalization (machine '' when absent, agent
+ * 'unknown' when absent) and the console's bundle grouping
+ * ((machine||'')+'|'+harness) — see the module doc.
+ */
+export declare function capturePauseKey(machine: unknown, sourceAgent: unknown): CapturePauseKey;
+/** True when a pause row exists for the (machine, harness) bundle. */
+export declare function isCapturePaused(db: Database.Database, machine: string, harness: string): boolean;
+/**
+ * Pause (upsert the row, timestamp now) or resume (delete it). Returns the
+ * persisted paused_at when pausing, null when resuming. No pruning, ever —
+ * see migration v18's provenance comment.
+ */
+export declare function setCapturePause(db: Database.Database, machine: string, harness: string, paused: boolean): string | null;
+/** Every paused bundle (newest first) — the dashboard fleet.pauses block. */
+export declare function listCapturePauses(db: Database.Database): CapturePause[];
+/**
+ * The newest /distill activity per bundle: for each (machine, agent) take
+ * MAX(ts) with that latest row's outcome, derive the harness per agent, then
+ * merge same-bundle agents keeping the newest ts (one dot per bundle, not
+ * per profile). Reads only distill_activity, which the recorder prunes to
+ * 7 days — older-than-window bundles simply have no rows and no dot.
+ */
+export declare function readFleetLastSeen(db: Database.Database): FleetLastSeen[];