pi-continual-harness 0.1.1 → 0.3.0

package/README.md

@@ -13,8 +13,11 @@ with:
   → behavioral-file refinement (the "deep" path).
 - **pi-mem / pi-memory** — durable memory storage.
 
-The durable markdown export (`.pi/harness-state.md`) is the composition seam:
-pi-reflect can read and refine it, pi-mem can ingest it.
+The durable markdown file (`.pi/harness-state.md`) is the composition seam,
+and it is **two-way**: `/refine --commit` and `/harness export` write it;
+`/harness import` parses it back and merges into the live store (offline edits
+win on conflict), so refinements pi-reflect makes flow back online. pi-mem
+ingestion is a future/manual step.
 
 ## Why
 
@@ -50,6 +53,27 @@ Or drop `src/index.ts` into `~/.pi/agent/extensions/`.
 /refine 25 --commit  # also export durable state to ~/.pi/agent/harness-state.md
 ```
 
+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
+existing entry are updated (offline edits win on content/evidence/importance),
+new entries are created. By default nothing is deleted — `--prune` also drops
+active items whose id is no longer in the file (inactive items are always
+preserved). Point pi-reflect at the same file to refine it offline:
+
+```
+/reflect ~/.pi/agent/harness-state.md
+```
+
 The model-facing tools:
 
 - `harness_list [kind]` — read current state (optionally filtered by kind).
@@ -59,6 +83,32 @@ 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",
+  "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.
+- **`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.
@@ -82,13 +132,22 @@ model-agnostic, and keeps every delta visible and reviewable in the transcript.
 
 ## Status
 
-Scaffold (0.1.0). Extension points to grow into:
+0.2.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).
+
+Open extension points (see `docs/ROADMAP.md`):
 
 - 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.
+- 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.1.1",
+  "version": "0.3.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,61 @@
+// 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 }, "auto");
+    } catch (err) {
+      ctx.ui.notify(`Auto-refine failed: ${(err as Error).message}`, "error");
+    }
+  });
+}

package/src/config.ts

@@ -0,0 +1,100 @@
+// 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;
+  };
+}
+
+export const DEFAULT_CONFIG: HarnessConfig = {
+  durableScope: "global",
+  remindRefine: { enabled: false, everyTurns: DEFAULT_EVERY_TURNS },
+  autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false },
+};
+
+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,
+    },
+  };
+}
+
+/** 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

@@ -0,0 +1,183 @@
+// /harness — durable I/O. The two-way round-trip seam with pi-reflect.
+//
+//   /harness status [path]               counts + durable file presence/mtime
+//   /harness export [path]               write active items to a markdown file
+//   /harness import [--prune] [path]     parse it back and merge (durable wins)
+//
+// export writes the active items to ~/.pi/agent/harness-state.md (best-effort);
+// import parses that file and merges into the live store. Because pi-reflect
+// edits markdown files and git-commits, pointing it at the same file closes the
+// loop: offline refinement flows back into the online store.
+//
+// Manual only (no session_start auto-import): importing is an explicit,
+// reviewable action, matching the package's "no autonomous mutation" stance.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { stat } from "node:fs/promises";
+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 + 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();
+      const rest = parts.slice(1);
+      switch (sub) {
+        case "import":
+          await handleImport(pi, ctx, rest);
+          return;
+        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);
+          return;
+      }
+    },
+  });
+}
+
+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(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  rest: string[],
+): Promise<void> {
+  const prune = rest.includes("--prune");
+  const path = await resolvePath(rest, ctx);
+  ctx.ui.setStatus("harness", `Importing durable state${prune ? " (prune)" : ""}…`);
+  try {
+    const res = await reconstructFromDurable(path, { prune }, (snapshot, ver) => {
+      pi.appendEntry("harness-state", { state: snapshot, version: ver });
+    });
+    if (res.missingFile) {
+      ctx.ui.notify(
+        `No durable file at ${path}. Run /refine --commit or /harness export first.`,
+        "warning",
+      );
+      return;
+    }
+    const bits = [`${res.created} created`, `${res.updated} updated`];
+    if (prune) bits.push(`${res.pruned} pruned`);
+    ctx.ui.notify(`Imported ${res.imported} item(s) from ${path} (${bits.join(", ")}).`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Harness import failed: ${(err as Error).message}`, "error");
+  }
+  ctx.ui.setStatus("harness", undefined);
+}
+
+async function handleExport(ctx: ExtensionCommandContext, rest: string[]): Promise<void> {
+  const path = await resolvePath(rest, ctx);
+  ctx.ui.setStatus("harness", "Exporting durable state…");
+  try {
+    const written = await exportDurable(path);
+    const n = getState().items.filter((i) => i.active).length;
+    ctx.ui.notify(`Exported ${n} active item(s) to ${written}`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Harness export failed: ${(err as Error).message}`, "error");
+  }
+  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 = 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 };
+  for (const i of active) counts[i.kind] += 1;
+  let fileState: string;
+  try {
+    const st = await stat(path);
+    fileState = `${path} (modified ${st.mtime.toISOString()})`;
+  } catch {
+    fileState = `none at ${path}`;
+  }
+  ctx.ui.setStatus("harness", undefined);
+  ctx.ui.notify(
+    `Harness: ${active.length} active / ${items.length} total — ` +
+      `prompt ${counts.prompt}, memory ${counts.memory}, skill ${counts.skill}, subagent ${counts.subagent}. ` +
+      `Durable: ${fileState}.`,
+    "info",
+  );
+}

package/src/index.ts

@@ -7,9 +7,12 @@
 // See README for design rationale and the research it is grounded in.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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 {
@@ -27,6 +30,9 @@ export default function continualHarness(pi: ExtensionAPI): void {
   registerInjection(pi);
   registerTools(pi);
   registerRefine(pi);
+  registerHarness(pi);
+  registerReminder(pi);
+  registerAutoRefine(pi);
 }
 
 export { STATE_ENTRY };

package/src/refine.ts

@@ -12,11 +12,11 @@
 // agent loop, is model-agnostic, and keeps every delta visible and reviewable
 // in the transcript. No hidden model calls.
 
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { exportDurable, REFINE_ENTRY } from "./store.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.
@@ -35,29 +35,55 @@ export function registerRefine(pi: ExtensionAPI): void {
       "Online self-improvement: review recent trajectory and propose evidence-backed CRUD deltas to the harness state. Usage: /refine [lookback-turns] [--commit]",
     handler: async (args, ctx) => {
       const { lookback, commit } = parseArgs(args);
-      ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)…`);
-
-      const evidence = gatherEvidence(ctx, lookback);
-      const prompt = buildSteeringPrompt(evidence, lookback);
+      await runRefine(pi, ctx, { lookback, commit });
+    },
+  });
+}
 
-      // Record that a refinement was kicked off (audit trail; branchable).
-      pi.appendEntry(REFINE_ENTRY, { lookback, commit, startedAt: Date.now() });
+export interface RefineOptions {
+  lookback?: number;
+  commit?: boolean;
+}
 
-      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");
-        }
-      }
+export interface RefineResult {
+  evidenceBytes: number;
+  lookback: number;
+  commit: boolean;
+  source: "manual" | "auto";
+}
 
-      pi.sendUserMessage(prompt);
-      ctx.ui.setStatus("harness", undefined);
-    },
-  });
+/** Core refine routine shared by /refine (manual) and turn_end auto-refine.
+ *  Gathers trajectory evidence, records an audit entry, optionally flushes the
+ *  durable state, then sends the steering user message that drives the agent to
+ *  propose evidence-backed CRUD deltas. `source` tags the audit entry so
+ *  autonomous runs are distinguishable in the transcript. */
+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;
+  ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)…`);
+  const evidence = gatherEvidence(ctx, lookback);
+  const prompt = buildSteeringPrompt(evidence, lookback);
+  // Audit trail (branchable via /tree). `source` distinguishes manual /refine
+  // from opt-in auto-refine so autonomous runs are visible in the transcript.
+  pi.appendEntry(REFINE_ENTRY, { lookback, commit, startedAt: Date.now(), source });
+  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");
+    }
+  }
+  pi.sendUserMessage(prompt);
+  ctx.ui.setStatus("harness", undefined);
+  return { evidenceBytes: evidence.length, lookback, commit, source };
 }
 
 function parseArgs(args: string): { lookback: number; commit: boolean } {
@@ -71,7 +97,7 @@ function parseArgs(args: string): { lookback: number; commit: boolean } {
   return { lookback, commit };
 }
 
-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)

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

@@ -10,7 +10,7 @@
 //     to a markdown file pi-reflect can read and refine offline, and pi-mem can
 //     ingest. Best-effort; the package works without it.
 
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type { AppliedDelta, ComponentKind, Delta, HarnessItem, HarnessState } from "./types.js";
@@ -18,7 +18,7 @@ import type { AppliedDelta, ComponentKind, Delta, HarnessItem, HarnessState } fr
 const STATE_ENTRY = "harness-state";
 const REFINE_ENTRY = "harness-refinement";
 
-const DEFAULT_DURABLE_PATH = join(homedir(), ".pi", "agent", "harness-state.md");
+export const DEFAULT_DURABLE_PATH = join(homedir(), ".pi", "agent", "harness-state.md");
 
 const IMPORTANCE_FLOOR = 0.3;
 
@@ -120,15 +120,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 };
@@ -167,3 +201,190 @@ function titleFor(kind: ComponentKind): string {
       return "Sub-agent specs";
   }
 }
+
+// ---- Durable import (round-trip seam with pi-reflect) ---------------------
+//
+// exportDurable() is write-only by design. reconstructFromDurable() closes the
+// loop: it parses the markdown back into items and merges them into the live
+// store, so offline edits pi-reflect makes to harness-state.md flow back in.
+//
+// Merge semantics (predictable, loss-free by default):
+//   - parsed item whose id matches an existing item → UPDATE in place
+//     (durable wins on content/evidence/importance; reactivated; createdAt kept).
+//   - parsed item with a new/foreign id → CREATE.
+//   - items in the store but absent from the file → KEPT by default.
+//     Pass { prune: true } to also drop active items whose id is not in the
+//     file (inactive items are always preserved — the durable export never
+//     contains them, so they cannot have been "deleted" by pi-reflect).
+
+export interface DurableImportResult {
+  /** Items successfully parsed from the file. */
+  imported: number;
+  created: number;
+  updated: number;
+  /** Only non-zero when { prune: true }. */
+  pruned: number;
+  /** True if the file did not exist (no-op). */
+  missingFile: boolean;
+}
+
+interface ParsedItem {
+  id?: string;
+  kind: ComponentKind;
+  importance: number;
+  content: string;
+  evidence: string;
+}
+
+// Section title → kind. Exact export titles first, then tolerant keyword
+// fallbacks so pi-reflect's edits to headings still parse.
+const TITLE_TO_KIND: Array<[RegExp, ComponentKind]> = [
+  [/supplemental prompt notes/i, "prompt"],
+  [/memory facts/i, "memory"],
+  [/skill descriptions/i, "skill"],
+  [/sub-?agent specs/i, "subagent"],
+  [/\bprompt\b/i, "prompt"],
+  [/\bmemory\b/i, "memory"],
+  [/\bskills?\b/i, "skill"],
+  [/\bsub-?agents?\b/i, "subagent"],
+];
+
+function titleToKind(title: string): ComponentKind | undefined {
+  for (const [re, kind] of TITLE_TO_KIND) if (re.test(title)) return kind;
+  return undefined;
+}
+
+const RE_H2 = /^##\s+(.*)$/;
+const RE_ID_BULLET = /^-\s+\*\*\[([^\]]+)\]\*\*\s*\(importance\s+([\d.]+)\)\s*(.*)$/;
+const RE_PLAIN_BULLET = /^-\s+(.+)$/;
+const RE_EVIDENCE = /^\s+-\s+evidence:\s*(.*)$/i;
+
+/** Parse a durable markdown export into items. Tolerant of pi-reflect's edits. */
+export function parseDurable(text: string): ParsedItem[] {
+  const out: ParsedItem[] = [];
+  let kind: ComponentKind | undefined;
+  let pending: ParsedItem | null = null;
+  const flush = (): void => {
+    if (pending && pending.content) out.push(pending);
+    pending = null;
+  };
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/\s+$/, "");
+    const h2 = line.match(RE_H2);
+    if (h2) {
+      flush();
+      kind = titleToKind(h2[1]!.trim());
+      continue;
+    }
+    if (/^#/.test(line)) {
+      flush(); // any other header (h1, h3, …)
+      continue;
+    }
+    if (!kind) continue; // ignore bullets outside a known section
+
+    const ev = line.match(RE_EVIDENCE);
+    if (ev) {
+      if (pending) pending.evidence = ev[1]!.trim();
+      continue;
+    }
+
+    const idm = line.match(RE_ID_BULLET);
+    if (idm) {
+      flush();
+      const imp = Number(idm[2]!);
+      pending = {
+        id: idm[1]!.trim(),
+        kind,
+        importance: Number.isNaN(imp) ? 0.5 : imp,
+        content: idm[3]!.trim(),
+        evidence: "",
+      };
+      continue;
+    }
+
+    const pm = line.match(RE_PLAIN_BULLET);
+    if (pm) {
+      flush();
+      const body = pm[1]!.trim();
+      const idInBody = body.match(/^\*\*\[([^\]]+)\]\*\*/);
+      pending = {
+        kind,
+        importance: 0.5,
+        content: body.replace(/^\*\*\[([^\]]+)\]\*\*\s*/, "").trim(),
+        evidence: "",
+      };
+      if (idInBody) pending.id = idInBody[1]!.trim();
+      continue;
+    }
+  }
+  flush();
+  return out.filter((p) => p.content && !/^\(?no active items\)?$/i.test(p.content));
+}
+
+/**
+ * Parse the durable file and merge it into the live store, then persist a
+ * snapshot. See the file-level comment above for merge semantics.
+ */
+export async function reconstructFromDurable(
+  path: string,
+  options: { prune?: boolean },
+  persist: (snapshot: HarnessState, version: number) => void,
+): Promise<DurableImportResult> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return { imported: 0, created: 0, updated: 0, pruned: 0, missingFile: true };
+  }
+
+  const parsed = parseDurable(text);
+  const fileIds = new Set(parsed.map((p) => p.id).filter((id): id is string => Boolean(id)));
+  const existingById = new Map(state.items.map((i) => [i.id, i] as const));
+  const preActiveIds = new Set(state.items.filter((i) => i.active).map((i) => i.id));
+
+  let created = 0;
+  let updated = 0;
+  const now = Date.now();
+  for (const p of parsed) {
+    const existing = p.id ? existingById.get(p.id) : undefined;
+    if (existing) {
+      // Durable wins; reactivate; keep createdAt.
+      existing.content = p.content;
+      existing.evidence = p.evidence;
+      existing.importance = clamp(p.importance);
+      existing.active = true;
+      existing.updatedAt = now;
+      updated += 1;
+    } else {
+      const id = p.id && /^h_/.test(p.id) ? p.id : genId();
+      state.items.push({
+        id,
+        kind: p.kind,
+        content: p.content,
+        evidence: p.evidence,
+        importance: clamp(p.importance),
+        active: true,
+        createdAt: now,
+        updatedAt: now,
+      });
+      created += 1;
+    }
+  }
+
+  let pruned = 0;
+  if (options.prune) {
+    const before = state.items.length;
+    state.items = state.items.filter((i) => {
+      if (!i.active) return true; // inactive items are never touched by durable I/O
+      if (!preActiveIds.has(i.id)) return true; // created during this import
+      if (fileIds.has(i.id)) return true; // present in the file
+      return false; // was active before, absent from the file → drop
+    });
+    pruned = before - state.items.length;
+  }
+
+  version += 1;
+  persist(state, version);
+  return { imported: parsed.length, created, updated, pruned, missingFile: false };
+}