pi-continual-harness 0.18.0 → 0.20.0

package/README.md

@@ -129,6 +129,11 @@ The model-facing tools:
   project slug is stamped server-side from the session cwd — used by
   `/harness split`; normally managed via `/harness move`).
 
+In **codemode** (pi ≥ 1.2), these tools' input constraints render as `@`
+tags on property comments — `importance` shows `@minimum 0 @maximum 1`, the
+batch cap shows `@maxItems 20` — because the tool schemas already declare
+them. Scripts see the limits without the descriptions repeating them.
+
 Active items are injected into the system prompt each turn as a structured
 block, appended to (never replacing) the base prompt.
 
@@ -180,19 +185,27 @@ Optional config at `~/.pi/agent/harness.json` (missing → defaults; malformed
 
 ```json
 {
+  "$schema": "https://raw.githubusercontent.com/pungggi/pi-continual-harness/main/harness.schema.json",
   "autoImport": false,
   "importRemind": { "enabled": true, "everyTurns": 25 },
   "proposer": "steering",
   "dedupe": { "threshold": 0.6, "merge": true },
   "injection": { "enabled": true, "maxTokens": 1500, "maxPerKind": 10, "charsPerToken": 4 },
   "remindRefine": { "enabled": true, "everyTurns": 25, "detailEvery": 4 },
-  "autoRefine": { "enabled": false, "everyTurns": 100, "commit": false, "gate": false },
+  "autoRefine": { "enabled": false, "everyTurns": 100, "commit": false, "gate": false, "refineNoOpSkip": 3 },
   "outcomeImportance": { "enabled": false, "bump": 0.03 },
   "classifier": { "model": "typesafe/jev-latest" },
   "virtualBinding": "virtual"
 }
 ```
 
+**Editor validation**: add `"$schema":
+"https://raw.githubusercontent.com/pungggi/pi-continual-harness/main/harness.schema.json"`
+to the file for completion and validation in editors that support JSON
+schemas (the same pattern pi ≥ 1.2 ships for its own `settings.json` /
+`models.json`). The loader ignores unknown keys — `$schema` included — and a
+`/harness setup` rewrite preserves it.
+
 - **`autoImport`** — opt-in **durable sync** (off by default). `true` bundles
   both directions: on `session_start` the durable layers are imported
   automatically (global file always + the current project's file, with the same
@@ -258,7 +271,14 @@ Optional config at `~/.pi/agent/harness.json` (missing → defaults; malformed
   also flushes durable state on each run. `gate: true` (needs `classifier.model`)
   asks the classifier first whether the recent trajectory contains a durable,
   reusable correction and skips the refine when it does not — cadence becomes
-  signal, not just time (errors fall back to the plain cadence). The steering
+  signal, not just time (errors fall back to the plain cadence).
+  `refineNoOpSkip` (default 3, `0` disables) is a free **history gate** that
+  runs first: when the last N refine runs (any source) all produced nothing
+  durable, the cadenced refine is skipped as a likely repeat no-op. It is
+  **bounded**: at most one consecutive cadence is skipped on history grounds,
+  so the gate can never latch shut — later trajectory evidence always gets a
+  refine within one cadence (and manual `/refine` never consults the gate).
+  The steering
   prompt is delivered via the pi ≥ 0.87 actionable `turn_end` boundary (a
   structural `harness.auto-refine-request` entry + `continue: true`), not a
   synthetic user message. Aborted/error turns (pi `turn_end`
@@ -306,6 +326,36 @@ Optional config at `~/.pi/agent/harness.json` (missing → defaults; malformed
 > scope), then move any strays with `/harness move` (or classify the whole
 > store with `/harness split`).
 
+## Lessons and support signals (harnessing-level recursion)
+
+Harness²'s second loop: the improvement process should learn from what past
+improvement actually yielded, and keep a lesson only when execution evidence
+supports it. Four pieces implement this without any extra model calls:
+
+- **Support counters.** Every item accumulates `support` signals: `citations`
+  (the outcome loop saw the agent cite the item's `[h_xxxx]` tag), `keeps` and
+  `drops` (`/harness keep|drop`). Dedupe merges carry the counters onto the
+  keeper, and durable export/import round-trips them (`support:` sub-line), so
+  feedback survives restarts. See them with `/harness list -f`.
+- **Lessons digest.** `/refine` steers with a compact, evidence-gated digest:
+  items proven useful (cited or kept), rejected signals (drops that strictly
+  outweigh any later use — a drop followed by re-citations is contested, not
+  rejected), and how productive recent refine runs were. Never-cited items are
+  NOT named: no signal is not a negative signal. The digest is **scoped to the
+  active model's items** — per-model isolation applies to what the improver is
+  told, not just what it is shown. `/harness lessons` prints the exact digest
+  the next `/refine` will use. Why: the improver starts from
+  what worked instead of re-deriving it, and stops re-creating rejected notes.
+- **Scoped proposals.** The `/refine` steering prompt classifies every create
+  as **invariant** (cross-domain agentic behavior → `scope: "global"`) or
+  **domain-specific** (this project's knowledge → `scope: "project"`).
+  Harness²'s ablation shows this scoping is load-bearing; here it also keeps
+  the global layer free of project noise.
+- **History gate.** Auto-refine skips a cadenced run when the last
+  `refineNoOpSkip` refine runs all produced nothing durable, **bounded to one
+  consecutive skip** so later evidence always gets a chance (see
+  `autoRefine` in [Configuration](#configuration)).
+
 ## How it works
 
 1. `/refine` gathers recent trajectory evidence from the current session branch.
@@ -505,7 +555,7 @@ implementation on first `propose()`) directly into
 
 ## Status
 
-0.12.x. Requires **pi ≥ 0.99.0**. Implemented:
+0.18.x. Requires **pi ≥ 1.2.0**. Implemented:
 
 - Unified harness-state store with branch-local snapshots (`/tree` rollback).
 - Online `/refine` + `harness_mutate` / `harness_list` tools.
@@ -535,7 +585,10 @@ implementation on first `propose()`) directly into
   model instead of the router id, so a router selection does not silently
   reset the harness. Owned items can be carried across models explicitly with
   `/harness adopt --from <provider/id> [--all]` (agent-filtered copy; see
-  [Model binding](#model-binding-per-model-isolation)).
+  [Model binding](#model-binding-per-model-isolation)). Since pi 1.2,
+  `before_agent_start` also fires for runs started by `pi.sendMessage(...,
+  { triggerTurn: true })`, so scheduled and extension-triggered runs get the
+  same binding, orphan adoption, and injection as interactive prompts.
 - **Bounded injection (on by default)**: the supplemental block is
   importance-ordered and capped per kind + by a total token budget, so a growing
   harness never balloons the system prompt. Tunable / opt-out via the `injection`

package/dist/auto-refine.d.ts

@@ -1,7 +1,15 @@
 import type { ExtensionAPI, ExtensionContext, TurnEndEvent, TurnEndEventResult } from "@earendil-works/pi-coding-agent";
 import { type HarnessConfig } from "./config.js";
 export { turnEndedBadly } from "./cadence.js";
-/** Test hook: reset internal counter. */
+/** History gate bound (review r4341960942): the gate's predicate only reads
+ *  REFINE entries on the branch, and a SKIPPED cadence adds none — without a
+ *  bound, three consecutive no-op runs would latch the gate shut until a
+ *  manual /refine, no matter what later turns contain. So at most ONE
+ *  consecutive cadence is skipped on history grounds: the next cadence runs
+ *  the refine regardless (its result re-evaluates the window afterwards),
+ *  giving later trajectory evidence a bounded path in. */
+export declare const HISTORY_GATE_MAX_CONSECUTIVE_SKIPS = 1;
+/** Test hook: reset internal counters. */
 export declare function resetAutoRefine(): void;
 /**
  * Decide whether to auto-refine this turn. Side-effectful: the first observed

package/dist/auto-refine.js

@@ -34,18 +34,31 @@
 // It stays visible: it notifies before firing, and the boundary draft (and the
 // gate decision) appear in the transcript. The decision logic is factored into
 // evaluateAutoRefine() so it is unit-testable without a live pi runtime.
-import { DEFAULT_AUTO_EVERY_TURNS, loadConfig } from "./config.js";
+import { DEFAULT_AUTO_EVERY_TURNS, DEFAULT_REFINE_NOOP_SKIP, loadConfig } from "./config.js";
 import { runRefine, gatherEvidence, DEFAULT_LOOKBACK_TURNS } from "./refine.js";
 import { buildClassify, buildGateRequest, gateDecision } from "./classify.js";
+import { recentIneffectiveRuns } from "./lessons.js";
 import { makeTurnCadence } from "./cadence.js";
 // turnEndedBadly's canonical home is cadence.ts (shared completed-turn
 // semantics); re-exported here so existing imports keep working.
 export { turnEndedBadly } from "./cadence.js";
 // The auto-refine cadence counter (shared implementation — see cadence.ts).
 const cadence = makeTurnCadence();
-/** Test hook: reset internal counter. */
+/** History gate bound (review r4341960942): the gate's predicate only reads
+ *  REFINE entries on the branch, and a SKIPPED cadence adds none — without a
+ *  bound, three consecutive no-op runs would latch the gate shut until a
+ *  manual /refine, no matter what later turns contain. So at most ONE
+ *  consecutive cadence is skipped on history grounds: the next cadence runs
+ *  the refine regardless (its result re-evaluates the window afterwards),
+ *  giving later trajectory evidence a bounded path in. */
+export const HISTORY_GATE_MAX_CONSECUTIVE_SKIPS = 1;
+/** Consecutive cadences the history gate has skipped this session (reset when
+ *  a refine actually runs, by resetAutoRefine, and at session_start). */
+let historyGateSkips = 0;
+/** Test hook: reset internal counters. */
 export function resetAutoRefine() {
     cadence.reset();
+    historyGateSkips = 0;
 }
 /**
  * Decide whether to auto-refine this turn. Side-effectful: the first observed
@@ -97,6 +110,19 @@ export async function handleAutoRefineTurnEnd(pi, event, ctx) {
     if (!evaluateAutoRefine(config, event.outcome))
         return;
     const every = config.autoRefine?.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS;
+    // History gate (harnessing-level recursion): free, runs before the classifier
+    // gate — when the last N refine runs were ALL ineffective, a cadenced refine
+    // over the same quiet trajectory would most likely be another no-op. Manual
+    // /refine never consults this gate. BOUNDED: at most
+    // HISTORY_GATE_MAX_CONSECUTIVE_SKIPS consecutive cadence is skipped, so the
+    // gate can never latch shut against later, richer trajectory evidence
+    // (review r4341960942) — the run after a skip always happens.
+    const noOpSkip = config.autoRefine?.refineNoOpSkip ?? DEFAULT_REFINE_NOOP_SKIP;
+    if (historyGateSkips < HISTORY_GATE_MAX_CONSECUTIVE_SKIPS && recentIneffectiveRuns(ctx.sessionManager.getBranch(), noOpSkip)) {
+        historyGateSkips += 1;
+        ctx.ui.notify(`Auto-refine: skipped — the last ${noOpSkip} refine run(s) produced nothing durable (history gate, ${historyGateSkips}/${HISTORY_GATE_MAX_CONSECUTIVE_SKIPS} consecutive skip; the next cadence runs regardless; refineNoOpSkip: 0 disables).`, "info");
+        return;
+    }
     // Opt-in classifier gate: cheap yes/no before spending the refine.
     if (config.autoRefine?.gate) {
         const classify = buildClassify(ctx, config.classifier?.model);
@@ -113,6 +139,9 @@ export async function handleAutoRefineTurnEnd(pi, event, ctx) {
         // No resolvable classifier → plain cadence behavior (documented soft-fail).
     }
     ctx.ui.notify(`Auto-refine: running /refine (every ${every} turns, opt-in).`, "info");
+    // A refine runs this cadence → the history gate's consecutive-skip budget
+    // is spent again (window re-evaluated from scratch next cadence).
+    historyGateSkips = 0;
     try {
         const result = await runRefine(pi, ctx, {
             commit: config.autoRefine?.commit ?? false,
@@ -124,7 +153,11 @@ export async function handleAutoRefineTurnEnd(pi, event, ctx) {
         // continue — otherwise fall back to the legacy steering send.
         if (result.steeringMessage) {
             if (event.context?.canContinue === false) {
-                pi.sendUserMessage(result.steeringMessage);
+                // deliverAs "followUp": queue after the in-flight run instead of
+                // throwing — pi 1.2 counts the session as busy from run start, so a
+                // bare sendUserMessage can fail here when another extension is
+                // starting a run at this turn_end.
+                pi.sendUserMessage(result.steeringMessage, { deliverAs: "followUp" });
                 return;
             }
             // Hygiene (pi ≥ 0.87 context edits): omit every LIVE prior auto-refine

package/dist/config.d.ts

@@ -4,6 +4,10 @@ export declare const DEFAULT_EVERY_TURNS = 25;
 export declare const DEFAULT_AUTO_EVERY_TURNS = 100;
 /** Default per-reference importance bump for the opt-in outcome loop. */
 export declare const DEFAULT_REF_BUMP = 0.03;
+/** History-gate default: a cadenced auto-refine is skipped when the last N
+ *  refine runs (any source) were ALL ineffective — no deltas applied and no
+ *  state mutation followed. 0 disables the gate (autoRefine.refineNoOpSkip). */
+export declare const DEFAULT_REFINE_NOOP_SKIP = 3;
 /** Default cadence (turns) for the auto-import awareness reminder. */
 export declare const DEFAULT_IMPORT_REMIND_TURNS = 25;
 /** Default escalation cadence for the /refine reminder: every Nth fired
@@ -59,6 +63,13 @@ export interface HarnessConfig {
          *  one (the newest) is ever model-visible. Raw history and /tree rollback
          *  are untouched; set false to keep every draft in context. */
         omitStaleDrafts?: boolean;
+        /** History gate (harnessing-level recursion): skip a cadenced refine when
+         *  the last N refine runs (any source) were ALL ineffective — no deltas
+         *  applied and no state mutation followed. Refines over an unchanged quiet
+         *  trajectory would most likely be no-ops again; the classifier gate (if
+         *  enabled) then never even runs. Manual /refine bypasses this. Default
+         *  DEFAULT_REFINE_NOOP_SKIP (3); 0 disables the history gate. */
+        refineNoOpSkip?: number;
     };
     /** Classifier model for the cheap gated paths (pi ≥ 0.99): "provider/id" or
      *  a bare id of a classifier catalog entry (e.g. "typesafe/jev-latest" or a

package/dist/config.js

@@ -24,6 +24,10 @@ export const DEFAULT_EVERY_TURNS = 25;
 export const DEFAULT_AUTO_EVERY_TURNS = 100;
 /** Default per-reference importance bump for the opt-in outcome loop. */
 export const DEFAULT_REF_BUMP = 0.03;
+/** History-gate default: a cadenced auto-refine is skipped when the last N
+ *  refine runs (any source) were ALL ineffective — no deltas applied and no
+ *  state mutation followed. 0 disables the gate (autoRefine.refineNoOpSkip). */
+export const DEFAULT_REFINE_NOOP_SKIP = 3;
 /** Default cadence (turns) for the auto-import awareness reminder. */
 export const DEFAULT_IMPORT_REMIND_TURNS = 25;
 /** Default escalation cadence for the /refine reminder: every Nth fired
@@ -33,7 +37,7 @@ export const DEFAULT_CONFIG = {
     autoImport: false,
     importRemind: { enabled: true, everyTurns: DEFAULT_IMPORT_REMIND_TURNS },
     remindRefine: { enabled: true, everyTurns: DEFAULT_EVERY_TURNS, detailEvery: DEFAULT_DETAIL_EVERY },
-    autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false, gate: false, omitStaleDrafts: true },
+    autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false, gate: false, omitStaleDrafts: true, refineNoOpSkip: DEFAULT_REFINE_NOOP_SKIP },
     classifier: { model: undefined },
     virtualBinding: "virtual",
     proposer: "steering",
@@ -75,6 +79,9 @@ function mergeConfig(over) {
             commit: over.autoRefine?.commit ?? false,
             gate: over.autoRefine?.gate === true,
             omitStaleDrafts: over.autoRefine?.omitStaleDrafts !== false,
+            refineNoOpSkip: typeof over.autoRefine?.refineNoOpSkip === "number" && Number.isFinite(over.autoRefine.refineNoOpSkip)
+                ? Math.max(0, Math.floor(over.autoRefine.refineNoOpSkip))
+                : DEFAULT_REFINE_NOOP_SKIP,
         },
         classifier: {
             model: typeof over.classifier?.model === "string" && over.classifier.model ? over.classifier.model : undefined,

package/dist/harness.js

@@ -40,6 +40,7 @@ import { buildStatusReport, renderStatusReport } from "./status.js";
 import { getInjectionStats } from "./inject.js";
 import { nextHint } from "./hints.js";
 import { preview, renderListReport } from "./list.js";
+import { buildLessonsDigest } from "./lessons.js";
 import { handleSetup, PRESET_COMPLETIONS } from "./setup.js";
 const SUBCOMMANDS = [
     { name: "import", description: "Import durable state, layered (--prune to prune stale items)" },
@@ -55,6 +56,7 @@ const SUBCOMMANDS = [
     { name: "adopt", description: "Steer the agent to adopt another model's items (--from <provider/id> [--all])" },
     { name: "push-mem", description: "Persist active items to pi-mem (--all, --kind, --model)" },
     { name: "setup", description: "Guided config wizard — presets: quiet | recommended | power (--yes for scripted)" },
+    { name: "lessons", description: "Evidence-gated lessons from past refines (the digest /refine steers with)" },
 ];
 const KINDS = ["prompt", "memory", "skill", "subagent"];
 /** `--scope` values /harness list offers (semantics in src/list.ts). */
@@ -243,6 +245,9 @@ export async function runHarnessCommand(pi, args, ctx) {
         case "setup":
             await handleSetup(ctx, rest);
             return;
+        case "lessons":
+            handleLessons(ctx);
+            return;
         case "list":
             await handleList(ctx, rest);
             return;
@@ -442,7 +447,9 @@ async function handleBump(pi, ctx, rest, delta, label) {
     }
     const item = bumpImportance(id, delta, (snapshot, ver) => {
         pi.appendEntry("harness-state", { state: snapshot, version: ver });
-    });
+    }, 
+    // Record the human signal in the support counters (keep/drop).
+    { support: label === "keep" ? "keep" : "drop" });
     if (!item) {
         ctx.ui.notify(`No harness item with id ${id}.`, "warning");
         return;
@@ -519,7 +526,9 @@ async function handleSplit(pi, ctx) {
         ctx.ui.notify("No active items to split (run /refine first).", "warning");
         return;
     }
-    pi.sendUserMessage(buildSplitPrompt(items, projectSlug(ctx.cwd), ctx.cwd));
+    // deliverAs "followUp": queue behind any in-flight run (pi ≥ 1.2 busy window
+    // starts at run start; a bare send would throw) rather than steering mid-task.
+    pi.sendUserMessage(buildSplitPrompt(items, projectSlug(ctx.cwd), ctx.cwd), { deliverAs: "followUp" });
     ctx.ui.notify(`Steering agent to classify ${items.length} item(s) global vs project "${projectSlug(ctx.cwd)}".`, "info");
 }
 /** Active items grouped by owning model key ("provider/id" → count). The
@@ -640,7 +649,7 @@ async function handleAdopt(pi, ctx, rest) {
     if (foreign > 0)
         bits.push(`${foreign} foreign-project skipped`);
     const suffix = bits.length > 0 ? ` (${bits.join("; ")})` : "";
-    pi.sendUserMessage(buildAdoptPrompt(items, from, { all: rest.includes("--all") }));
+    pi.sendUserMessage(buildAdoptPrompt(items, from, { all: rest.includes("--all") }), { deliverAs: "followUp" });
     ctx.ui.notify(`Steering agent to ${rest.includes("--all") ? "adopt" : "review for adoption"} ${items.length} item(s) from ${from}${suffix}.`, "info");
 }
 /** Compose a steering message that asks the agent to persist the given active
@@ -691,9 +700,20 @@ async function handlePushMem(pi, ctx, rest) {
     const scope = all ? "item(s)" : `${kind ?? "memory"} item(s)`;
     const modelNote = modelFilter !== undefined ? ` [model ${modelFilter || "(orphan)"}]` : "";
     const msg = buildPushMemPrompt(items, scope);
-    pi.sendUserMessage(msg);
+    pi.sendUserMessage(msg, { deliverAs: "followUp" });
     ctx.ui.notify(`Steering agent to persist ${items.length} ${scope}${modelNote} to pi-mem.`, "info");
 }
+/** `/harness lessons` — print the exact evidence-gated digest the next /refine
+ *  steers with (harnessing-level recursion, Harness² arXiv 2610.14224).
+ *  Read-only; distinct empty state when nothing supportable exists yet. */
+function handleLessons(ctx) {
+    const digest = buildLessonsDigest(getState(), ctx.sessionManager.getBranch());
+    if (!digest) {
+        ctx.ui.notify("No lessons yet — items need citations (outcome loop) or /harness keep|drop feedback, or past refine runs, before anything is evidence-gated.", "info");
+        return;
+    }
+    ctx.ui.notify(digest, "info");
+}
 async function handleStatus(ctx) {
     // Thin glue (issue #20): config + durable-layer stat() I/O here; every
     // derived band lives in the pure buildStatusReport (src/status.ts).

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export { default } from "./entry.js";
 export { STATE_ENTRY } from "./store.js";
-export { type AppliedDelta, type ComponentKind, type Delta, type HarnessItem, type HarnessState, } from "./types.js";
-export { DEFAULT_DEDUPE, DEDUPE_THRESHOLD, EVIDENCE_MERGE_CAP, listProposers, planDedupe, registerProposer, unionEvidence, type CompleteOptions, type CompleteResult, type DedupeOptions, type DeltaProposer, type ModelCallTelemetry, type ProposeInput, type ProposedDelta, type ProposeResult, type SimilarityResult, } from "./proposer.js";
+export { type AppliedDelta, type ComponentKind, type Delta, type HarnessItem, type HarnessState, type SupportInfo, } from "./types.js";
+export { DEFAULT_DEDUPE, DEDUPE_THRESHOLD, EVIDENCE_MERGE_CAP, buildSteeringPrompt, listProposers, planDedupe, registerProposer, unionEvidence, type CompleteOptions, type CompleteResult, type DedupeOptions, type DeltaProposer, type ModelCallTelemetry, type ProposeInput, type ProposedDelta, type ProposeResult, type SimilarityResult, } from "./proposer.js";
+export { buildLessonsDigest, classifyRuns, isEffectiveRun, recentIneffectiveRuns, type DigestOptions, type RefineRun, } from "./lessons.js";
+export { mergeSupport, renderSupport, parseSupport } from "./store.js";
+export { DEFAULT_REFINE_NOOP_SKIP } from "./config.js";
 export { buildCorpus, classifyTransition, NOT_DUP_FLOOR, parseDedupeDelete, type CorpusResult, type DedupePairRecord, type LifecycleEvent, type LifecycleRecord, type LifecycleTransition, } from "./corpus.js";
 export { buildStatusReport, renderStatusReport, type ImpactCounts, type StatusOptions, type StatusReport, } from "./status.js";
 export { nextHint, pickHint, resetHints, type StatusHint, } from "./hints.js";

package/dist/index.js

@@ -20,7 +20,13 @@ export {} from "./types.js";
 // Public extension API: other extensions can register their own delta proposer
 // (see src/proposer.ts) and it becomes selectable via /refine --proposer <name>
 // or the `proposer` config key.
-export { DEFAULT_DEDUPE, DEDUPE_THRESHOLD, EVIDENCE_MERGE_CAP, listProposers, planDedupe, registerProposer, unionEvidence, } from "./proposer.js";
+export { DEFAULT_DEDUPE, DEDUPE_THRESHOLD, EVIDENCE_MERGE_CAP, buildSteeringPrompt, listProposers, planDedupe, registerProposer, unionEvidence, } from "./proposer.js";
+// Harnessing-level recursion (Harness², arXiv 2610.14224): evidence-gated
+// lessons from past refines + the auto-refine history gate. Re-exported for
+// tests and companion packages.
+export { buildLessonsDigest, classifyRuns, isEffectiveRun, recentIneffectiveRuns, } from "./lessons.js";
+export { mergeSupport, renderSupport, parseSupport } from "./store.js";
+export { DEFAULT_REFINE_NOOP_SKIP } from "./config.js";
 // Calibration corpus exporter (pi-reflex contract §4, formerly pi-jev). Re-exported so companion
 // packages can build corpora from exported session branches without reaching
 // into internal paths.

package/dist/lessons.d.ts

@@ -0,0 +1,65 @@
+import type { HarnessState } from "./types.js";
+/** What a harness-refinement entry records (subset we consume). */
+export interface RefineRun {
+    /** Manual /refine vs. cadenced auto-refine. */
+    source?: string | undefined;
+    /** Which proposer ran. */
+    proposer?: string | undefined;
+    /** Deltas applied DIRECTLY by the proposer (0 for the steering path at
+     *  entry-creation time — effectiveness is then inferred from a following
+     *  harness-state entry, see classifyRuns). */
+    applied?: number | undefined;
+    /** ms epoch (entry data startedAt). */
+    at?: number | undefined;
+    /** True when a harness-state mutation landed AFTER this refine entry and
+     *  before the next one — the steering agent actually mutated. */
+    followedByStateChange?: boolean | undefined;
+}
+/** Annotate runs with followedByStateChange by co-walking state entries.
+ *
+ *  Attribution subtlety (review r4341960980): runRefine writes a direct-apply
+ *  run's harness-state snapshot BEFORE that run's own audit entry, so a state
+ *  entry sitting between run k and run k+1 may belong to EITHER. Disambiguate
+ *  by ownership: if run k+1 direct-applied (applied > 0), exactly one of those
+ *  state entries is its own snapshot and must NOT be credited to run k.
+ *  Leftover entries credit run k (its steering mutation — or a human keep/drop
+ *  in between, an acceptable false credit: it only ever LIFTS the gate, never
+ *  makes it skip). */
+export declare function classifyRuns(entries: Iterable<unknown>): RefineRun[];
+/** A run is EFFECTIVE when the proposer applied deltas directly, or the
+ *  steering agent mutated state right after. No-ops are everything else. */
+export declare function isEffectiveRun(r: RefineRun): boolean;
+/**
+ * History gate (auto-refine): true when the LAST `n` refine runs (fewer if
+ * the branch holds fewer) were ALL ineffective — a cadenced refine over the
+ * same quiet trajectory would most likely be another no-op. n <= 0 always
+ * returns false (gate off).
+ */
+export declare function recentIneffectiveRuns(entries: Iterable<unknown>, n: number): boolean;
+export interface DigestOptions {
+    /** Max supported items listed (default 5). */
+    maxSupported?: number;
+    /** Max struggling items listed (default 3). */
+    maxStruggling?: number;
+    /** Refine runs summarized (default 6). */
+    runsWindow?: number;
+    /** Hard character cap on the whole digest (default 1200). */
+    maxChars?: number;
+    /** Model-binding key (see vmodel.resolveBindingKey): only items OWNED by
+     *  this model are named (review r4341960955) — the digest must respect the
+     *  same per-model isolation as injection, otherwise a fresh model is fed
+     *  foreign notes and told to delete ids it cannot mutate
+     *  (assertOwnsItem rejects them). Undefined = no owner filter (callers that
+     *  know the actor — runRefine — always pass it, `""` for an unknown model). */
+    ownerKey?: string | undefined;
+}
+/**
+ * Build the lessons digest injected into the refine steering prompt. Every
+ * line is evidence-gated (Harness²'s retention rule): supported items must
+ * have organic citations or keeps, struggling items must show explicit
+ * negative signal (drops) — never-cited-but-never-dropped items are NOT
+ * named (no signal is not a negative signal). Returns "" when there is
+ * nothing supportable to say, so the prompt stays unchanged for fresh stores.
+ * Pure.
+ */
+export declare function buildLessonsDigest(state: HarnessState, entries: Iterable<unknown>, opts?: DigestOptions): string;

package/dist/lessons.js

@@ -0,0 +1,182 @@
+// lessons.ts — harnessing-level recursion (Harness², arXiv 2610.14224 §2.3).
+//
+// Harness² separates two loops: task-level recursion improves the harness for
+// the CURRENT task, while harnessing-level recursion lets the IMPROVEMENT
+// PROCESS ITSELF learn from what past refinements revealed. Its library rule:
+// "lessons are retained only when supported by execution contrasts" — never
+// from the mere fact that an edit was proposed.
+//
+// This module is our online-sized take on that rule, built entirely from
+// signals we already persist:
+//  - item support counters (citations from the outcome loop, keeps/drops from
+//    /harness keep|drop) — the "execution contrast" proxy: adoption followed
+//    by observed use (or by the human explicitly rejecting it);
+//  - harness-refinement audit entries on the branch — which refine runs
+//    produced durable deltas vs. no-ops.
+//
+// Two consumers:
+//  - buildLessonsDigest() → injected into the /refine steering prompt (and any
+//    other proposer via ProposeInput.lessons), so the improver starts from
+//    what past improvement actually yielded.
+//  - recentIneffectiveRuns() → the history gate for auto-refine (skip a
+//    cadenced refine when the last N runs were all no-ops).
+//
+// Everything here is PURE over (state, branch entries): no I/O, no config,
+// fully unit-testable, and silent when there is nothing supportable to say.
+import { preview } from "./list.js";
+import { REFINE_ENTRY, STATE_ENTRY } from "./store.js";
+/** One-line, whitespace-flattened preview (shared style with list rows). */
+function flat(text, max) {
+    return preview(text, max);
+}
+/** Annotate runs with followedByStateChange by co-walking state entries.
+ *
+ *  Attribution subtlety (review r4341960980): runRefine writes a direct-apply
+ *  run's harness-state snapshot BEFORE that run's own audit entry, so a state
+ *  entry sitting between run k and run k+1 may belong to EITHER. Disambiguate
+ *  by ownership: if run k+1 direct-applied (applied > 0), exactly one of those
+ *  state entries is its own snapshot and must NOT be credited to run k.
+ *  Leftover entries credit run k (its steering mutation — or a human keep/drop
+ *  in between, an acceptable false credit: it only ever LIFTS the gate, never
+ *  makes it skip). */
+export function classifyRuns(entries) {
+    const runs = [];
+    let pending;
+    // harness-state entries seen since `pending`'s audit entry.
+    let stateAfter = 0;
+    const flush = (nextApplied) => {
+        if (pending) {
+            const ownedByNext = (nextApplied ?? 0) > 0 ? 1 : 0;
+            pending.followedByStateChange = stateAfter - ownedByNext > 0;
+            runs.push(pending);
+        }
+        pending = undefined;
+        stateAfter = 0;
+    };
+    for (const raw of entries) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const e = raw;
+        if (e.type === "custom" && e.customType === STATE_ENTRY) {
+            if (pending)
+                stateAfter += 1;
+            continue;
+        }
+        if (e.type === "custom" && e.customType === REFINE_ENTRY) {
+            const next = {
+                source: e.data?.source,
+                proposer: e.data?.proposer,
+                applied: e.data?.applied,
+                at: e.data?.startedAt,
+            };
+            // Flush the previous run knowing whether the new one direct-applied.
+            flush(next.applied);
+            pending = next;
+        }
+    }
+    flush(); // last run: any state entry after its audit is attributable to it
+    return runs;
+}
+/** A run is EFFECTIVE when the proposer applied deltas directly, or the
+ *  steering agent mutated state right after. No-ops are everything else. */
+export function isEffectiveRun(r) {
+    return (r.applied ?? 0) > 0 || r.followedByStateChange === true;
+}
+/**
+ * History gate (auto-refine): true when the LAST `n` refine runs (fewer if
+ * the branch holds fewer) were ALL ineffective — a cadenced refine over the
+ * same quiet trajectory would most likely be another no-op. n <= 0 always
+ * returns false (gate off).
+ */
+export function recentIneffectiveRuns(entries, n) {
+    if (n <= 0)
+        return false;
+    const runs = classifyRuns(entries);
+    if (runs.length === 0)
+        return false;
+    const last = runs.slice(-n);
+    return last.length === n && last.every((r) => !isEffectiveRun(r));
+}
+// ---- the digest -----------------------------------------------------------
+/** Positive support score: citations weigh double keeps (organic use is a
+ *  stronger contrast than a human nudge), drops are negative. */
+function supportScore(i) {
+    const s = i.support;
+    if (!s)
+        return 0;
+    return 2 * (s.citations ?? 0) + (s.keeps ?? 0) - 2 * (s.drops ?? 0);
+}
+/** Cap an assembled digest: drop trailing sections until it fits. */
+function cap(sections, maxChars) {
+    const out = [];
+    let total = 0;
+    for (const s of sections) {
+        if (total + s.length > maxChars && out.length > 0)
+            break;
+        out.push(s);
+        total += s.length;
+    }
+    return out.join("\n");
+}
+/**
+ * Build the lessons digest injected into the refine steering prompt. Every
+ * line is evidence-gated (Harness²'s retention rule): supported items must
+ * have organic citations or keeps, struggling items must show explicit
+ * negative signal (drops) — never-cited-but-never-dropped items are NOT
+ * named (no signal is not a negative signal). Returns "" when there is
+ * nothing supportable to say, so the prompt stays unchanged for fresh stores.
+ * Pure.
+ */
+export function buildLessonsDigest(state, entries, opts = {}) {
+    const sections = [];
+    const active = state.items.filter((i) => i.active && (opts.ownerKey === undefined || i.ownerModel === opts.ownerKey));
+    // 1. Supported — proven useful since adoption.
+    const supported = active
+        .filter((i) => supportScore(i) > 0)
+        .sort((a, b) => supportScore(b) - supportScore(a))
+        .slice(0, opts.maxSupported ?? 5);
+    if (supported.length > 0) {
+        sections.push([
+            `Proven useful (do not duplicate; strengthen only with new evidence):`,
+            ...supported.map((i) => {
+                const s = i.support;
+                const bits = [
+                    s.citations ? `cited ${s.citations}×` : "",
+                    s.keeps ? `kept ${s.keeps}×` : "",
+                ].filter(Boolean);
+                return `- [${i.id}] (${bits.join(", ")}): ${flat(i.content, 90)}`;
+            }),
+        ].join("\n"));
+    }
+    // 2. Struggling — explicit NEGATIVE net signal only (drops strictly
+    //    outweigh any later use). An item dropped once and then cited again
+    //    (score 0) or cited more than dropped (score > 0) is contested, not
+    //    rejected — later execution evidence outranks the drop (review
+    //    r4341960962). Net-neutral items are never named (no signal ≠ negative).
+    const struggling = active
+        .filter((i) => (i.support?.drops ?? 0) > 0 && supportScore(i) < 0)
+        .sort((a, b) => (b.support.drops ?? 0) - (a.support.drops ?? 0))
+        .slice(0, opts.maxStruggling ?? 3);
+    if (struggling.length > 0) {
+        sections.push([
+            `Rejected signals (candidates to delete or rewrite — past drops, no use since):`,
+            ...struggling.map((i) => `- [${i.id}] (dropped ${i.support.drops}×): ${flat(i.content, 90)}`),
+        ].join("\n"));
+    }
+    // 3. Refine-run history — how productive past improvement was.
+    const runs = classifyRuns(entries);
+    const window = opts.runsWindow ?? 6;
+    const recent = runs.slice(-window);
+    if (recent.length > 0) {
+        const effective = recent.filter(isEffectiveRun).length;
+        const noOps = recent.length - effective;
+        const line = noOps === 0
+            ? `Refine history: all ${recent.length} recent run(s) produced durable deltas — keep proposing surgical, evidence-backed edits.`
+            : `Refine history: ${noOps} of the last ${recent.length} run(s) proposed nothing durable — only record a correction when the trajectory clearly supports it; say so and do nothing otherwise.`;
+        sections.push(line);
+    }
+    if (sections.length === 0)
+        return "";
+    const header = "## Lessons from past refines (evidence-gated — apply when relevant)";
+    return cap([header, ...sections], opts.maxChars ?? 1200);
+}

package/dist/list.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentKind, HarnessItem } from "./types.js";
+import type { ComponentKind, HarnessItem, SupportInfo } from "./types.js";
 /** `--scope` values for /harness list. `undefined` (no flag) = the session's
  *  layer set: global + the active project. */
 export type ListScope = "global" | "project" | "all";
@@ -21,6 +21,9 @@ export declare function preview(text: string, max?: number): string;
  *  desc with ties keeping store order — the same stable ranking policy as
  *  injection selection and /harness adopt. Pure. */
 export declare function selectListItems(items: HarnessItem[], opts: ListOptions): HarnessItem[];
+/** Compact support summary for one line: "cited 3, kept 1, dropped 0" —
+ *  only non-zero signals, so clean items add nothing. */
+export declare function supportSummary(s?: SupportInfo): string | undefined;
 /** Render the whole `/harness list` notify string: header (count + active
  *  filters), rows (compact by default, full text + evidence with `full`),
  *  and distinct empty-state guidance for an empty store vs an empty filter