pi-continual-harness 0.2.0 → 0.4.0

package/README.md

@@ -51,6 +51,7 @@ Or drop `src/index.ts` into `~/.pi/agent/extensions/`.
 /refine              # review last 25 turns, propose deltas
 /refine 50           # review last 50 turns
 /refine 25 --commit  # also export durable state to ~/.pi/agent/harness-state.md
+/refine --proposer dedupe  # run the rule-based dedupe proposer instead of steering
 ```
 
 Durable I/O (round-trip with pi-reflect):
@@ -59,6 +60,9 @@ Durable I/O (round-trip with pi-reflect):
 /harness status                  # counts + durable file presence/mtime
 /harness export [path]           # write active items to a markdown file
 /harness import [--prune] [path] # parse it back and merge (offline edits win)
+/harness prune [--decay <days>]  # drop items below the importance floor
+/harness keep <id>               # nudge importance up (+0.1)
+/harness drop <id>               # nudge importance down (−0.1)
 ```
 
 `import` reconciles the file into the live store: items whose id matches an
@@ -80,19 +84,92 @@ The model-facing tools:
 Active items are injected into the system prompt each turn as a structured
 block, appended to (never replacing) the base prompt.
 
+## Configuration
+
+Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults):
+
+```json
+{
+  "durableScope": "global",
+  "proposer": "steering",
+  "remindRefine": { "enabled": false, "everyTurns": 50 },
+  "autoRefine": { "enabled": false, "everyTurns": 100, "commit": false }
+}
+```
+
+- **`durableScope`** — `"global"` (default) writes the durable markdown to
+  `~/.pi/agent/harness-state.md`; `"project"` writes to
+  `~/.pi/agent/harness-state/<slug>.md` (slug derived from `cwd`) so each
+  project keeps separate state for pi-reflect.
+- **`proposer`** — which delta proposer `/refine` and auto-refine use. Defaults
+  to `steering` (the agent reasons via a steering message). `dedupe` applies a
+  rule-based dedupe directly. See [Proposers](#proposers).
+- **`remindRefine`** — opt-in `turn_end` nudge. `{ "enabled": true,
+  "everyTurns": 50 }` notifies you to run `/refine` on a cadence. It is
+  informational only — it never mutates state.
+- **`autoRefine`** — opt-in autonomous self-improvement (**off by default**).
+  When `enabled`, the agent runs `/refine` itself every `everyTurns` turns
+  (default 100). This is the package's one autonomous-self-mutation path: it
+  reuses the exact `/refine` routine (audited `REFINE_ENTRY` tagged
+  `source: "auto"`, branch-local, `/tree` rollback) and notifies before firing.
+  `commit: true` also flushes durable state on each run.
+
 ## How it works
 
 1. `/refine` gathers recent trajectory evidence from the current session branch.
-2. It sends a steering user message asking the agent to propose evidence-backed
-   CRUD deltas via `harness_mutate`.
-3. The agent calls the tools; each accepted delta updates the in-memory state,
-   which is snapshotted to the session via `appendEntry("harness-state", ...)`.
+2. A **proposer** decides what to do. The default (`steering`) sends a steering
+   user message asking the agent to propose evidence-backed CRUD deltas via
+   `harness_mutate`; rule-based proposers (e.g. `dedupe`) return deltas the
+   harness applies directly. See [Proposers](#proposers).
+3. The agent calls the tools (steering path); each accepted delta updates the
+   in-memory state, which is snapshotted to the session via
+   `appendEntry("harness-state", ...)`. Direct-apply proposers snapshot the
+   same way.
 4. Because pi's session tree branches at any entry, `/tree` navigation gives
    rollback to any pre-refinement point for free — no bespoke snapshot system.
 
 This reuses the existing agent loop (no nested/hidden model calls), is
 model-agnostic, and keeps every delta visible and reviewable in the transcript.
 
+## Proposers
+
+`/refine` is split into two stages: **propose** (given evidence + state, decide
+what deltas to pursue) and **apply** (send a steering message, or apply returned
+deltas directly). The propose stage is pluggable via a registry
+(`src/proposer.ts`).
+
+| Name | What it does |
+|---|---|
+| `steering` (default) | Delegates reasoning to the agent via a steering message — reuses the agent loop, model-agnostic, fully visible. |
+| `dedupe` | Rule-based: drops near-duplicate active items (token-overlap ≥ 0.6), keeping the higher-importance one. No model call. |
+
+Select a proposer per run with `/refine --proposer <name>`, or set the default
+for auto-refine via `proposer` in the [config](#configuration). Both paths are
+audited: the `harness-refinement` entry records which proposer ran and how many
+deltas it applied directly.
+
+A dedicated-model proposer (a hidden LLM call) is the obvious next alternate
+the interface supports, but is intentionally not shipped — non-visible model
+spend is a tradeoff kept as a separate decision (see `docs/ROADMAP.md`).
+
+Register your own proposer from another extension (the registry is re-exported
+from the package entry):
+
+```ts
+import { registerProposer } from "pi-continual-harness";
+
+registerProposer({
+  name: "my-proposer",
+  async propose({ evidence, state }) {
+    /* inspect evidence + state, return deltas (and/or a steering message) */
+    return { deltas: [/* { delta, rationale } */] };
+  },
+});
+```
+
+Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
+`"proposer": "my-proposer"` in the config.
+
 ## Scope and non-goals
 
 - **In scope:** unified state store, online `/refine`, structured deltas,
@@ -103,15 +180,25 @@ model-agnostic, and keeps every delta visible and reviewable in the transcript.
 
 ## Status
 
-0.1.x. The durable round-trip with pi-reflect is implemented
-(`/harness import|export|status`). Open extension points:
-
-- A pluggable delta proposer (currently the agent itself, via steering).
-- Project-local vs global durable paths.
-- Optional `turn_end` auto-trigger behind a setting (intentionally off by
-  default — autonomous self-mutation is a sharp edge).
-- Importance decay/prune policy — `decayAndPrune()` exists but is not yet wired.
-- pi-mem ingestion of the durable export (manual/future).
+0.3.x. Implemented:
+
+- Unified harness-state store with branch-local snapshots (`/tree` rollback).
+- Online `/refine` + `harness_mutate` / `harness_list` tools.
+- Two-way durable round-trip with pi-reflect (`/harness import|export|status`).
+- Importance hygiene: `/harness prune [--decay <days>]` and `/harness keep|drop
+  <id>`.
+- Optional config (`~/.pi/agent/harness.json`): project-local durable scope, an
+  opt-in `turn_end` reminder, and opt-in `turn_end` auto-refine (the one
+  autonomous-self-mutation path; off by default).
+- **Pluggable delta proposers** with a registry: `steering` (default) and
+  `dedupe` (rule-based) shipped; `registerProposer()` for custom ones.
+
+Open extension points (see `docs/ROADMAP.md`):
+
+- A dedicated-model proposer (interface ready; the hidden-model-spend tradeoff
+  is a separate decision).
+- pi-mem ingestion of the durable export.
+- Outcome-driven importance (currently model-set + manual nudges).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Online self-improvement layer for pi. A unified, in-trajectory harness-state store (prompt notes, memory, skill descriptions, sub-agent specs) with a manual /refine that proposes evidence-backed structured CRUD deltas. Composes with pi-reflect (offline) and pi-mem (storage); owns only the online optimizer layer. Inspired by Continual Harness (arXiv 2605.09998) and ACE (arXiv 2510.04618).",
   "keywords": [
     "pi-package",

package/src/auto-refine.ts

@@ -0,0 +1,66 @@
+// turn_end auto-refine (Phase 3 of the roadmap). This is the package's ONE
+// autonomous-self-mutation path, so it is locked behind an explicit opt-in:
+//
+//   ~/.pi/agent/harness.json
+//   { "autoRefine": { "enabled": true, "everyTurns": 100, "commit": false } }
+//
+// When enabled and the cadence elapses, it runs the SAME runRefine() routine as
+// /refine — no parallel mutation logic — so it inherits all the safety
+// properties: structured evidence-backed deltas, an audited REFINE_ENTRY
+// (tagged source: "auto"), branch-local snapshots, and /tree rollback.
+//
+// It is also visible: it notifies before firing and the steering message
+// appears in the transcript. The decision logic is factored into
+// evaluateAutoRefine() so it is unit-testable without a live pi runtime.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_AUTO_EVERY_TURNS, type HarnessConfig, loadConfig } from "./config.js";
+import { runRefine } from "./refine.js";
+
+// turnIndex of the last auto-refine (or the seeded baseline). -1 = unseen.
+let lastTurn = -1;
+
+/** Test hook: reset internal counter. */
+export function resetAutoRefine(): void {
+  lastTurn = -1;
+}
+
+/**
+ * Decide whether to auto-refine this turn. Side-effectful: the first observed
+ * turn seeds the baseline (no refine then); each fired refine resets it, which
+ * also prevents the refine turn itself from immediately re-triggering.
+ */
+export function evaluateAutoRefine(config: HarnessConfig, turnIndex: number): boolean {
+  if (!config.autoRefine?.enabled) return false;
+  const every = config.autoRefine.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS;
+  if (every <= 0) return false;
+  if (lastTurn < 0) {
+    lastTurn = turnIndex;
+    return false;
+  }
+  if (turnIndex - lastTurn >= every) {
+    lastTurn = turnIndex;
+    return true;
+  }
+  return false;
+}
+
+/** Subscribe to turn_end and run /refine on the configured cadence. */
+export function registerAutoRefine(pi: ExtensionAPI): void {
+  pi.on("turn_end", async (event, ctx) => {
+    const config = await loadConfig();
+    if (!evaluateAutoRefine(config, event.turnIndex)) return;
+    const every = config.autoRefine?.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS;
+    ctx.ui.notify(`Auto-refine: running /refine (every ${every} turns, opt-in).`, "info");
+    try {
+      await runRefine(
+        pi,
+        ctx,
+        { commit: config.autoRefine?.commit ?? false, ...(config.proposer ? { proposer: config.proposer } : {}) },
+        "auto",
+      );
+    } catch (err) {
+      ctx.ui.notify(`Auto-refine failed: ${(err as Error).message}`, "error");
+    }
+  });
+}

package/src/config.ts

@@ -0,0 +1,104 @@
+// User configuration for continual-harness: ~/.pi/agent/harness.json
+//
+// Phase 2 introduces this file (optional; missing → defaults) to configure:
+//  - durableScope: where the durable markdown lives. "global" (default,
+//    ~/.pi/agent/harness-state.md — backward compatible) or "project"
+//    (~/.pi/agent/harness-state/<slug>.md, slug derived from cwd) so different
+//    projects keep separate harness state for pi-reflect.
+//  - remindRefine: opt-in turn_end nudge to run /refine (Phase 2 = reminder
+//    only; Phase 3 adds opt-in auto-refine).
+//
+// Robust by design: missing or malformed file → DEFAULT_CONFIG, never throws.
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_DURABLE_PATH } from "./store.js";
+
+export const DEFAULT_EVERY_TURNS = 50;
+export const DEFAULT_AUTO_EVERY_TURNS = 100;
+
+export interface HarnessConfig {
+  durableScope?: "global" | "project";
+  remindRefine?: {
+    enabled?: boolean;
+    everyTurns?: number;
+  };
+  autoRefine?: {
+    enabled?: boolean;
+    everyTurns?: number;
+    commit?: boolean;
+  };
+  /** Delta proposer name (see proposer.ts registry). Defaults to "steering". */
+  proposer?: string;
+}
+
+export const DEFAULT_CONFIG: HarnessConfig = {
+  durableScope: "global",
+  remindRefine: { enabled: false, everyTurns: DEFAULT_EVERY_TURNS },
+  autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false },
+  proposer: "steering",
+};
+
+export const CONFIG_PATH = join(homedir(), ".pi", "agent", "harness.json");
+
+let cached: HarnessConfig | undefined;
+
+/** Merge a (possibly partial) parsed file over the defaults. */
+function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
+  return {
+    durableScope: over.durableScope === "project" ? "project" : "global",
+    remindRefine: {
+      enabled: over.remindRefine?.enabled ?? false,
+      everyTurns: over.remindRefine?.everyTurns ?? DEFAULT_EVERY_TURNS,
+    },
+    autoRefine: {
+      enabled: over.autoRefine?.enabled ?? false,
+      everyTurns: over.autoRefine?.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS,
+      commit: over.autoRefine?.commit ?? false,
+    },
+    proposer: over.proposer ?? "steering",
+  };
+}
+
+/** Load the config, merged over defaults. Tolerant: missing/malformed → defaults.
+ *  Cached for the process lifetime (config is read once per session). */
+export async function loadConfig(path: string = CONFIG_PATH): Promise<HarnessConfig> {
+  if (cached) return cached;
+  try {
+    const raw = await readFile(path, "utf8");
+    cached = mergeConfig(JSON.parse(raw) as Partial<HarnessConfig>);
+  } catch {
+    cached = { ...DEFAULT_CONFIG };
+  }
+  return cached;
+}
+
+/** Test hook: drop the in-process cache. */
+export function resetConfigCache(): void {
+  cached = undefined;
+}
+
+/**
+ * Resolve the durable markdown path for the configured scope.
+ *  - global  → ~/.pi/agent/harness-state.md (the default, unchanged)
+ *  - project → ~/.pi/agent/harness-state/<slug>.md (slug derived from cwd)
+ */
+export function resolveDurablePath(config: HarnessConfig, cwd?: string): string {
+  if (config.durableScope !== "project") return DEFAULT_DURABLE_PATH;
+  return join(homedir(), ".pi", "agent", "harness-state", `${projectSlug(cwd)}.md`);
+}
+
+/** Stable, filesystem-safe slug from a directory path. Falls back to "default". */
+export function projectSlug(cwd?: string): string {
+  const base = (cwd ?? "").trim();
+  if (!base) return "default";
+  const slug = base
+    .replace(/[\\/]+/g, "-")
+    .replace(/[^a-z0-9-]+/gi, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase()
+    .slice(-80);
+  return slug || "default";
+}

package/src/harness.ts

@@ -14,14 +14,22 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { stat } from "node:fs/promises";
-import { DEFAULT_DURABLE_PATH, exportDurable, getState, reconstructFromDurable } from "./store.js";
+import {
+  bumpImportance,
+  decayAndPrune,
+  exportDurable,
+  getState,
+  reconstructFromDurable,
+} from "./store.js";
+import { loadConfig, resolveDurablePath } from "./config.js";
 import type { ComponentKind } from "./types.js";
 
 export function registerHarness(pi: ExtensionAPI): void {
   pi.registerCommand("harness", {
     description:
-      "Durable harness-state I/O (round-trip seam with pi-reflect). " +
-      "Subcommands: import [--prune] [path] · export [path] · status [path].",
+      "Durable harness-state I/O + importance hygiene. Subcommands: " +
+      "import [--prune] [path] · export [path] · status [path] · " +
+      "prune [--decay <days>] · keep <id> · drop <id>.",
     handler: async (args, ctx) => {
       const parts = args.trim().split(/\s+/).filter(Boolean);
       const sub = (parts[0] ?? "status").toLowerCase();
@@ -33,6 +41,15 @@ export function registerHarness(pi: ExtensionAPI): void {
         case "export":
           await handleExport(ctx, rest);
           return;
+        case "prune":
+          await handlePrune(pi, ctx, rest);
+          return;
+        case "keep":
+          await handleBump(pi, ctx, rest, 0.1, "keep");
+          return;
+        case "drop":
+          await handleBump(pi, ctx, rest, -0.1, "drop");
+          return;
         case "status":
         default:
           await handleStatus(ctx, rest);
@@ -42,8 +59,11 @@ export function registerHarness(pi: ExtensionAPI): void {
   });
 }
 
-function resolvePath(rest: string[]): string {
-  return rest.find((a) => !a.startsWith("-")) ?? DEFAULT_DURABLE_PATH;
+async function resolvePath(rest: string[], ctx: ExtensionCommandContext): Promise<string> {
+  const explicit = rest.find((a) => !a.startsWith("-"));
+  if (explicit) return explicit;
+  const config = await loadConfig();
+  return resolveDurablePath(config, ctx.cwd);
 }
 
 async function handleImport(
@@ -52,7 +72,7 @@ async function handleImport(
   rest: string[],
 ): Promise<void> {
   const prune = rest.includes("--prune");
-  const path = resolvePath(rest);
+  const path = await resolvePath(rest, ctx);
   ctx.ui.setStatus("harness", `Importing durable state${prune ? " (prune)" : ""}…`);
   try {
     const res = await reconstructFromDurable(path, { prune }, (snapshot, ver) => {
@@ -75,7 +95,7 @@ async function handleImport(
 }
 
 async function handleExport(ctx: ExtensionCommandContext, rest: string[]): Promise<void> {
-  const path = resolvePath(rest);
+  const path = await resolvePath(rest, ctx);
   ctx.ui.setStatus("harness", "Exporting durable state…");
   try {
     const written = await exportDurable(path);
@@ -87,8 +107,61 @@ async function handleExport(ctx: ExtensionCommandContext, rest: string[]): Promi
   ctx.ui.setStatus("harness", undefined);
 }
 
+async function handlePrune(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  rest: string[],
+): Promise<void> {
+  let decayAfterDays: number | undefined;
+  const idx = rest.indexOf("--decay");
+  if (idx >= 0) {
+    const n = Number(rest[idx + 1]);
+    decayAfterDays = Number.isFinite(n) && n > 0 ? n : undefined;
+  }
+  ctx.ui.setStatus("harness", "Pruning…");
+  try {
+    const options: { decayAfterDays?: number; decayStep?: number } = { decayStep: 0.1 };
+    if (decayAfterDays !== undefined) options.decayAfterDays = decayAfterDays;
+    const res = decayAndPrune(options, (snapshot, ver) => {
+      pi.appendEntry("harness-state", { state: snapshot, version: ver });
+    });
+    const bits = [`${res.pruned} pruned`];
+    if (decayAfterDays !== undefined) bits.push(`${res.decayed} decayed (>${decayAfterDays}d)`);
+    ctx.ui.notify(`Harness: ${bits.join(", ")}.`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Harness prune failed: ${(err as Error).message}`, "error");
+  }
+  ctx.ui.setStatus("harness", undefined);
+}
+
+async function handleBump(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  rest: string[],
+  delta: number,
+  label: string,
+): Promise<void> {
+  const id = rest.find((a) => a && !a.startsWith("-"));
+  if (!id) {
+    ctx.ui.notify(
+      `/harness ${label} requires an item id (see /harness status or harness_list).`,
+      "warning",
+    );
+    return;
+  }
+  const item = bumpImportance(id, delta, (snapshot, ver) => {
+    pi.appendEntry("harness-state", { state: snapshot, version: ver });
+  });
+  if (!item) {
+    ctx.ui.notify(`No harness item with id ${id}.`, "warning");
+    return;
+  }
+  const preview = item.content.length > 60 ? `${item.content.slice(0, 60)}…` : item.content;
+  ctx.ui.notify(`${label}: "${preview}" → importance ${item.importance.toFixed(2)}`, "info");
+}
+
 async function handleStatus(ctx: ExtensionCommandContext, rest: string[]): Promise<void> {
-  const path = resolvePath(rest);
+  const path = await resolvePath(rest, ctx);
   const items = getState().items;
   const active = items.filter((i) => i.active);
   const counts: Record<ComponentKind, number> = { prompt: 0, memory: 0, skill: 0, subagent: 0 };

package/src/index.ts

@@ -11,6 +11,8 @@ import { registerHarness } from "./harness.js";
 import { registerInjection } from "./inject.js";
 import { registerRefine } from "./refine.js";
 import { registerTools } from "./tools.js";
+import { registerReminder } from "./remind.js";
+import { registerAutoRefine } from "./auto-refine.js";
 import { getState, reconstruct, STATE_ENTRY } from "./store.js";
 
 export default function continualHarness(pi: ExtensionAPI): void {
@@ -29,6 +31,19 @@ export default function continualHarness(pi: ExtensionAPI): void {
   registerTools(pi);
   registerRefine(pi);
   registerHarness(pi);
+  registerReminder(pi);
+  registerAutoRefine(pi);
 }
 
 export { STATE_ENTRY };
+
+// 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 {
+  listProposers,
+  registerProposer,
+  type DeltaProposer,
+  type ProposeInput,
+  type ProposeResult,
+} from "./proposer.js";

package/src/proposer.ts

@@ -0,0 +1,174 @@
+// Pluggable delta proposers (Phase 4 of the roadmap).
+//
+// /refine is split into two stages:
+//   1. PROPOSE — given trajectory evidence + current state, decide what deltas
+//      to apply (or what to ask the agent to do).
+//   2. APPLY   — either send a steering message (the agent reasons + calls
+//      harness_mutate) or apply returned deltas directly.
+//
+// This file owns stage 1. The default `steeringProposer` preserves the
+// original behavior exactly (delegates to the agent via a steering message,
+// reusing the agent loop — model-agnostic, fully visible). Alternate proposers
+// produce deltas directly:
+//   - `dedupeProposer` (rule-based): drops near-duplicate active items by token
+//     overlap, keeping the higher-importance one. Pure function of state —
+//     deterministic, no model call, fully testable.
+//
+// A dedicated-model proposer (a hidden LLM call) is the obvious next alternate
+// the interface supports, but is intentionally NOT shipped here: it is the one
+// tradeoff (non-visible model spend) the roadmap flags as a separate decision.
+//
+// Extension is open: call registerProposer() from your own extension to add a
+// named proposer, then select it via /refine --proposer <name> or config.
+
+import type { Delta, HarnessItem, HarnessState } from "./types.js";
+
+/** Inputs to a proposer. */
+export interface ProposeInput {
+  /** Recent trajectory evidence (the same string /refine gathers). */
+  evidence: string;
+  /** Current harness state as a defensive copy; mutations are ignored — use
+   *  the returned deltas to change state. */
+  state: HarnessState;
+  /** Lookback window in turns. */
+  lookback: number;
+}
+
+/** A single delta plus a human-readable reason for the audit trail. */
+export interface ProposedDelta {
+  delta: Delta;
+  rationale: string;
+}
+
+export interface ProposeResult {
+  /** Deltas the proposer produced directly (rule-based / model proposers). */
+  deltas?: ProposedDelta[];
+  /**
+   * A steering message for the agent, when the proposer delegates reasoning to
+   * the agent loop (the default). runRefine sends this via sendUserMessage.
+   * A proposer MAY return both — deltas are applied first, then steering sent.
+   */
+  steeringMessage?: string;
+}
+
+/** A strategy for turning evidence + state into (or toward) harness deltas. */
+export interface DeltaProposer {
+  readonly name: string;
+  propose(input: ProposeInput): Promise<ProposeResult>;
+}
+
+// ---- default: steering (delegates reasoning to the agent) ------------------
+
+function buildSteeringPrompt(evidence: string, lookback: number): string {
+  return [
+    `/refine (online self-improvement, last ${lookback} turns as evidence)`,
+    "",
+    "Review the trajectory evidence below. Identify DURABLE, REUSABLE corrections — things that will help in future turns, not one-off fixes. Then update the Continual Harness state.",
+    "",
+    "Steps:",
+    "1. Call harness_list to see the current state.",
+    "2. Call harness_mutate with small, surgical CRUD deltas. Every create MUST include concrete evidence from the trajectory. Prefer updating existing items over creating duplicates; delete items that are wrong, stale, or contradicted.",
+    "3. Keep prompt notes terse and behavioral. Memory facts should be specific. Skill/sub-agent entries should describe reusable patterns, not one task.",
+    "",
+    "Constraints: never rewrite the whole store; ground every change in evidence; if nothing durable is worth recording, say so and do nothing.",
+    "",
+    "## Trajectory evidence",
+    evidence,
+  ].join("\n");
+}
+
+/** Default proposer: delegates reasoning to the agent via a steering message. */
+export const steeringProposer: DeltaProposer = {
+  name: "steering",
+  async propose({ evidence, lookback }): Promise<ProposeResult> {
+    return { steeringMessage: buildSteeringPrompt(evidence, lookback) };
+  },
+};
+
+// ---- rule-based alternate: dedupe -----------------------------------------
+
+export const DEDUPE_THRESHOLD = 0.6;
+
+/** Tokenize for overlap comparison: lowercase alnum tokens. */
+export function tokenize(text: string): string[] {
+  return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(Boolean);
+}
+
+/** Jaccard token overlap in [0,1]. 0 if either side has no tokens. */
+export function tokenOverlap(a: string, b: string): number {
+  const sa = new Set(tokenize(a));
+  const sb = new Set(tokenize(b));
+  if (sa.size === 0 || sb.size === 0) return 0;
+  let inter = 0;
+  for (const t of sa) if (sb.has(t)) inter++;
+  return inter / (sa.size + sb.size - inter);
+}
+
+function truncate(s: string, n = 48): string {
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+/**
+ * Rule-based proposer: drops near-duplicate ACTIVE items (same kind, Jaccard
+ * token overlap >= DEDUPE_THRESHOLD), keeping the higher-importance one.
+ *
+ * Greedy and contradiction-free: items are considered in importance-descending
+ * order; the first item is always a keeper, and each later item is compared
+ * only against keepers, so a keeper is never subsequently dropped.
+ */
+export const dedupeProposer: DeltaProposer = {
+  name: "dedupe",
+  async propose({ state }): Promise<ProposeResult> {
+    const ordered = state.items
+      .filter((i) => i.active)
+      .sort((a, b) => b.importance - a.importance);
+    const keepers: HarnessItem[] = [];
+    const proposals: ProposedDelta[] = [];
+    for (const cand of ordered) {
+      let dup: HarnessItem | undefined;
+      let best = 0;
+      for (const k of keepers) {
+        if (k.kind !== cand.kind) continue;
+        const sim = tokenOverlap(k.content, cand.content);
+        if (sim >= DEDUPE_THRESHOLD && sim > best) {
+          best = sim;
+          dup = k;
+        }
+      }
+      if (dup) {
+        proposals.push({
+          delta: {
+            op: "delete",
+            id: cand.id,
+            reason: `near-duplicate of ${dup.id} (overlap ${best.toFixed(2)})`,
+          },
+          rationale: `dedupe: "${truncate(cand.content)}" ≈ keeper "${truncate(dup.content)}" (Jaccard ${best.toFixed(2)}); kept higher-importance ${dup.id}.`,
+        });
+      } else {
+        keepers.push(cand);
+      }
+    }
+    return proposals.length ? { deltas: proposals } : {};
+  },
+};
+
+// ---- registry -------------------------------------------------------------
+
+const registry = new Map<string, DeltaProposer>([
+  ["steering", steeringProposer],
+  ["dedupe", dedupeProposer],
+]);
+
+/** Register (or replace) a named proposer. For external extensions. */
+export function registerProposer(p: DeltaProposer): void {
+  registry.set(p.name, p);
+}
+
+/** Look up a proposer by name; falls back to the steering default. */
+export function getProposer(name: string | undefined): DeltaProposer {
+  return registry.get(name ?? "steering") ?? steeringProposer;
+}
+
+export function listProposers(): string[] {
+  return [...registry.keys()];
+}

package/src/refine.ts

@@ -1,22 +1,28 @@
-// /refine — the online optimizer. Manual only (no turn_end auto-trigger).
+// /refine — the online optimizer. Manual by default; opt-in turn_end
+// auto-refine lives in auto-refine.ts and reuses runRefine().
 //
 // Flow:
 //  1. Gather recent trajectory evidence from the current branch.
-//  2. Send a steering user message that asks the agent to propose evidence-
-//     backed CRUD deltas via harness_mutate (and to inspect state with
-//     harness_list first).
-//  3. The agent does the reasoning and calls the tools. Each accepted delta is
-//     recorded as a session entry, so /tree gives rollback for free.
+//  2. Hand evidence + current state to a pluggable DeltaProposer (proposer.ts).
+//     The default `steering` proposer returns a steering user message; the
+//     agent then reasons and calls harness_mutate. Rule-based/model proposers
+//     return deltas directly, which runRefine applies itself.
+//  3. Every mutation — whether from the agent (harness_mutate) or a direct-apply
+//     proposer — is recorded as a session entry, so /tree gives rollback for
+//     free. Which proposer ran is captured in the audit entry.
 //
-// Why a steering message instead of a nested LLM call: it reuses the existing
-// agent loop, is model-agnostic, and keeps every delta visible and reviewable
-// in the transcript. No hidden model calls.
+// Why a steering message as the DEFAULT instead of a nested LLM call: it reuses
+// the existing agent loop, is model-agnostic, and keeps every delta visible and
+// reviewable in the transcript. Alternate proposers can opt out via the
+// registry; the dedicated-model variant is intentionally not shipped (hidden
+// model spend is a tradeoff the roadmap keeps as a separate decision).
 
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { exportDurable, REFINE_ENTRY } from "./store.js";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { applyDeltas, exportDurable, REFINE_ENTRY, snapshotState } from "./store.js";
+import { getProposer } from "./proposer.js";
 
-const DEFAULT_LOOKBACK_TURNS = 25;
 const DEFAULT_EVIDENCE_BYTES = 16000;
+export const DEFAULT_LOOKBACK_TURNS = 25;
 
 // Minimal entry shape for trajectory walking; kept loose to avoid coupling to
 // pi's internal session entry types.
@@ -32,46 +38,125 @@ type AnyEntry = {
 export function registerRefine(pi: ExtensionAPI): void {
   pi.registerCommand("refine", {
     description:
-      "Online self-improvement: review recent trajectory and propose evidence-backed CRUD deltas to the harness state. Usage: /refine [lookback-turns] [--commit]",
+      "Online self-improvement: review recent trajectory and propose evidence-backed CRUD deltas to the harness state. Usage: /refine [lookback-turns] [--commit] [--proposer steering|dedupe]",
     handler: async (args, ctx) => {
-      const { lookback, commit } = parseArgs(args);
-      ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)…`);
+      const { lookback, commit, proposer } = parseArgs(args);
+      await runRefine(pi, ctx, { lookback, commit, ...(proposer ? { proposer } : {}) });
+    },
+  });
+}
 
-      const evidence = gatherEvidence(ctx, lookback);
-      const prompt = buildSteeringPrompt(evidence, lookback);
+export interface RefineOptions {
+  lookback?: number;
+  commit?: boolean;
+  /** Proposer name (see proposer.ts registry). Defaults to "steering". */
+  proposer?: string;
+}
 
-      // Record that a refinement was kicked off (audit trail; branchable).
-      pi.appendEntry(REFINE_ENTRY, { lookback, commit, startedAt: Date.now() });
+export interface RefineResult {
+  evidenceBytes: number;
+  lookback: number;
+  commit: boolean;
+  source: "manual" | "auto";
+  /** Which proposer ran. */
+  proposer: string;
+  /** Deltas the proposer applied directly (0 for the steering path). */
+  applied: number;
+}
 
-      if (commit) {
-        // Flush current state to the durable file first so the agent refines
-        // against the same view pi-reflect / pi-mem would see.
-        try {
-          const path = await exportDurable();
-          ctx.ui.notify(`Durable state exported to ${path}`, "info");
-        } catch (err) {
-          ctx.ui.notify(`Durable export failed: ${(err as Error).message}`, "warning");
-        }
-      }
+/**
+ * Core refine routine shared by /refine (manual) and turn_end auto-refine.
+ * Resolves a proposer, gathers evidence, lets the proposer decide what to do,
+ * then either applies returned deltas directly or sends a steering message.
+ * `source` tags the audit entry so autonomous runs are distinguishable.
+ */
+export async function runRefine(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  options: RefineOptions = {},
+  source: "manual" | "auto" = "manual",
+): Promise<RefineResult> {
+  const lookback = options.lookback ?? DEFAULT_LOOKBACK_TURNS;
+  const commit = options.commit ?? false;
+  const proposer = getProposer(options.proposer);
+  ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)… [${proposer.name}]`);
 
-      pi.sendUserMessage(prompt);
-      ctx.ui.setStatus("harness", undefined);
-    },
+  const evidence = gatherEvidence(ctx, lookback);
+  // Pass a defensive copy: proposers are a public extension point and must not
+  // be able to mutate the live store outside applyDeltas (no audit / no rollback).
+  const result = await proposer.propose({ evidence, state: snapshotState(), lookback });
+  const proposedDeltas = result.deltas ?? [];
+
+  let applied = 0;
+  if (proposedDeltas.length > 0) {
+    // Direct-apply path (rule-based / model proposers): persist each batch the
+    // same way harness_mutate does, so /tree rollback covers these too.
+    const appliedDeltas = applyDeltas(
+      proposedDeltas.map((d) => d.delta),
+      (snapshot, ver) => pi.appendEntry("harness-state", { state: snapshot, version: ver }),
+    );
+    applied = appliedDeltas.length;
+    ctx.ui.notify(`Proposer "${proposer.name}" applied ${applied} delta(s) directly.`, "info");
+  }
+
+  // Audit trail (branchable via /tree). `source` distinguishes manual /refine
+  // from opt-in auto-refine; `proposer` records WHICH strategy ran; the
+  // rationales make rule-based decisions visible in the transcript.
+  pi.appendEntry(REFINE_ENTRY, {
+    lookback,
+    commit,
+    startedAt: Date.now(),
+    source,
+    proposer: proposer.name,
+    applied,
+    rationales: proposedDeltas.map((d) => d.rationale),
   });
+
+  if (commit) {
+    // Flush current state to the durable file first so the agent refines
+    // against the same view pi-reflect / pi-mem would see.
+    try {
+      const path = await exportDurable();
+      ctx.ui.notify(`Durable state exported to ${path}`, "info");
+    } catch (err) {
+      ctx.ui.notify(`Durable export failed: ${(err as Error).message}`, "warning");
+    }
+  }
+
+  if (result.steeringMessage) {
+    pi.sendUserMessage(result.steeringMessage);
+  }
+  ctx.ui.setStatus("harness", undefined);
+  return {
+    evidenceBytes: evidence.length,
+    lookback,
+    commit,
+    source,
+    proposer: proposer.name,
+    applied,
+  };
 }
 
-function parseArgs(args: string): { lookback: number; commit: boolean } {
+function parseArgs(args: string): {
+  lookback: number;
+  commit: boolean;
+  proposer: string | undefined;
+} {
   const parts = args.trim().split(/\s+/).filter(Boolean);
   let lookback = DEFAULT_LOOKBACK_TURNS;
   let commit = false;
-  for (const p of parts) {
+  let proposer: string | undefined;
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i]!;
     if (p === "--commit") commit = true;
+    else if (p === "--proposer" && i + 1 < parts.length) proposer = parts[++i];
+    else if (p.startsWith("--proposer=")) proposer = p.slice("--proposer=".length);
     else if (/^\d+$/.test(p)) lookback = Math.max(1, Math.min(200, Number(p)));
   }
-  return { lookback, commit };
+  return { lookback, commit, proposer };
 }
 
-function gatherEvidence(ctx: ExtensionCommandContext, lookback: number): string {
+function gatherEvidence(ctx: ExtensionContext, lookback: number): string {
   const entries = ctx.sessionManager.getBranch() as AnyEntry[];
   const messages = entries.filter((e) => e.type === "message" && e.message);
   const recent = messages.slice(-lookback * 2); // ~2 entries per turn (user+assistant)
@@ -95,21 +180,3 @@ function gatherEvidence(ctx: ExtensionCommandContext, lookback: number): string
   }
   return lines.join("\n") || "(no recent trajectory evidence found)";
 }
-
-function buildSteeringPrompt(evidence: string, lookback: number): string {
-  return [
-    `/refine (online self-improvement, last ${lookback} turns as evidence)`,
-    "",
-    "Review the trajectory evidence below. Identify DURABLE, REUSABLE corrections — things that will help in future turns, not one-off fixes. Then update the Continual Harness state.",
-    "",
-    "Steps:",
-    "1. Call harness_list to see the current state.",
-    "2. Call harness_mutate with small, surgical CRUD deltas. Every create MUST include concrete evidence from the trajectory. Prefer updating existing items over creating duplicates; delete items that are wrong, stale, or contradicted.",
-    "3. Keep prompt notes terse and behavioral. Memory facts should be specific. Skill/sub-agent entries should describe reusable patterns, not one task.",
-    "",
-    "Constraints: never rewrite the whole store; ground every change in evidence; if nothing durable is worth recording, say so and do nothing.",
-    "",
-    "## Trajectory evidence",
-    evidence,
-  ].join("\n");
-}

package/src/remind.ts

@@ -0,0 +1,50 @@
+// turn_end reminder (Phase 2 of the roadmap). Purely informational — it nudges
+// the user to run /refine on a cadence; it never mutates state. Opt-in via
+// harness.json { remindRefine: { enabled: true, everyTurns: 50 } }.
+//
+// The decision logic is factored into evaluateReminder() so it is unit-testable
+// without a live pi runtime; registerReminder() is thin glue over pi.on.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_EVERY_TURNS, type HarnessConfig, loadConfig } from "./config.js";
+
+// turnIndex of the last reminder (or the baseline we seeded from). -1 = unseen.
+let lastTurn = -1;
+
+/** Test hook: reset internal counter. */
+export function resetReminder(): void {
+  lastTurn = -1;
+}
+
+/**
+ * Decide whether to remind this turn. Side-effectful: the first observed turn
+ * seeds the baseline (no reminder then), and each fired reminder resets it.
+ * Returns true when it is time to nudge.
+ */
+export function evaluateReminder(config: HarnessConfig, turnIndex: number): boolean {
+  if (!config.remindRefine?.enabled) return false;
+  const every = config.remindRefine.everyTurns ?? DEFAULT_EVERY_TURNS;
+  if (every <= 0) return false;
+  if (lastTurn < 0) {
+    lastTurn = turnIndex;
+    return false;
+  }
+  if (turnIndex - lastTurn >= every) {
+    lastTurn = turnIndex;
+    return true;
+  }
+  return false;
+}
+
+/** Subscribe to turn_end and notify on the configured cadence. */
+export function registerReminder(pi: ExtensionAPI): void {
+  pi.on("turn_end", async (event, ctx) => {
+    const config = await loadConfig();
+    if (!evaluateReminder(config, event.turnIndex)) return;
+    const every = config.remindRefine?.everyTurns ?? DEFAULT_EVERY_TURNS;
+    ctx.ui.notify(
+      `${every} turns since the last check — consider running /refine to refine harness state.`,
+      "info",
+    );
+  });
+}

package/src/store.ts

@@ -32,6 +32,13 @@ export function getState(): HarnessState {
   return state;
 }
 
+/** A defensive deep-enough copy of current state (items are flat). Use when
+ *  handing state to untrusted/external code (e.g. a DeltaProposer) so it cannot
+ *  mutate the live store outside applyDeltas. */
+export function snapshotState(): HarnessState {
+  return { items: state.items.map((i) => ({ ...i })) };
+}
+
 export function listItems(kind?: ComponentKind): HarnessItem[] {
   return kind ? state.items.filter((i) => i.kind === kind) : state.items;
 }
@@ -120,15 +127,49 @@ export function reconstruct(entries: Iterable<unknown>): void {
   version = 0;
 }
 
-/** Decrement importance of inactive/low-signal items; prune below the floor. */
-export function decayAndPrune(persist: (snapshot: HarnessState, version: number) => void): {
-  pruned: number;
-} {
+/**
+ * Age importance of stale items, then prune below the floor.
+ *  - decayAfterDays: if set, items whose updatedAt is older than this get
+ *    importance -= decayStep (default 0.1) before pruning. Time-since-update
+ *    is a weak proxy for staleness; pair with /harness keep|drop for signal.
+ *  - Items below IMPORTANCE_FLOOR after decay are removed.
+ */
+export function decayAndPrune(
+  options: { decayAfterDays?: number; decayStep?: number } = {},
+  persist: (snapshot: HarnessState, version: number) => void,
+): { pruned: number; decayed: number } {
+  let decayed = 0;
+  const step = options.decayStep ?? 0.1;
+  const ms = options.decayAfterDays !== undefined ? options.decayAfterDays * 86_400_000 : undefined;
+  const now = Date.now();
+  if (ms !== undefined) {
+    for (const i of state.items) {
+      if (now - i.updatedAt > ms) {
+        i.importance = clamp(i.importance - step);
+        decayed += 1;
+      }
+    }
+  }
   const before = state.items.length;
   state.items = state.items.filter((i) => i.importance >= IMPORTANCE_FLOOR);
   version += 1;
   persist(state, version);
-  return { pruned: before - state.items.length };
+  return { pruned: before - state.items.length, decayed };
+}
+
+/** Nudge an item's importance by delta (clamped to [0,1]) and touch updatedAt. */
+export function bumpImportance(
+  id: string,
+  delta: number,
+  persist: (snapshot: HarnessState, version: number) => void,
+): HarnessItem | undefined {
+  const item = state.items.find((i) => i.id === id);
+  if (!item) return undefined;
+  item.importance = clamp(item.importance + delta);
+  item.updatedAt = Date.now();
+  version += 1;
+  persist(state, version);
+  return item;
 }
 
 export { STATE_ENTRY, REFINE_ENTRY, IMPORTANCE_FLOOR };