pi-continual-harness 0.16.0 → 0.17.0

package/README.md

@@ -165,7 +165,7 @@ preset menu, or a declined final write; declining an individual feature only
 skips that feature (the accepted deltas still apply). The wizard never
 touches harness state, only the config file.
 
-Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults):
+Optional config at `~/.pi/agent/harness.json` (missing → defaults; malformed → defaults plus a once-per-session warning, so a typo can't silently reset your settings):
 
 ```json
 {
@@ -473,6 +473,17 @@ registerProposer({
 Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 `"proposer": "my-proposer"` in the config.
 
+**Cross-instance registry (0.17+).** pi's extension loader isolates module
+instances between extensions, so before 0.17.0 a companion's `registerProposer`
+call wrote to a private module copy that `/refine` never read — the
+registration was silently invisible. The registry is now backed by a
+process-wide global (`Symbol.for("pi-continual-harness.proposers")`), so any
+copy's registrations are visible to every copy. Companions that want a
+zero-import startup entry can skip importing this package at runtime entirely
+and push a `DeltaProposer` (typically a lazy delegate that dynamic-imports its
+implementation on first `propose()`) directly into
+`globalThis[Symbol.for("pi-continual-harness.proposers")]`.
+
 ## Scope and non-goals
 
 - **In scope:** unified state store, online `/refine`, structured deltas,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.16.0",
+  "version": "0.17.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

@@ -39,25 +39,18 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AUTO_EVERY_TURNS, type HarnessConfig, loadConfig } from "./config.js";
 import { runRefine, gatherEvidence, DEFAULT_LOOKBACK_TURNS } from "./refine.js";
 import { buildClassify, buildGateRequest, gateDecision } from "./classify.js";
+import { makeTurnCadence } from "./cadence.js";
 
-// Completed turns observed since the last fire (or the seeded baseline).
-// -1 = unseen. Aborted/error turns never touch this count — the window is
-// completed turns of work, not raw turn indices.
-let completedTurns = -1;
+// 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. */
 export function resetAutoRefine(): void {
-  completedTurns = -1;
-}
-
-/**
- * True when a turn_end's outcome marks a turn that ended badly (pi's
- * BoundaryState.outcome: "aborted" | "error"). Undefined is treated as
- * completed — current pi always reports the field, but synthetic events and
- * the earliest 0.99.x may omit it.
- */
-export function turnEndedBadly(outcome?: string): boolean {
-  return outcome === "aborted" || outcome === "error";
+  cadence.reset();
 }
 
 /**
@@ -71,19 +64,8 @@ export function turnEndedBadly(outcome?: string): boolean {
  */
 export function evaluateAutoRefine(config: HarnessConfig, outcome?: string): boolean {
   if (!config.autoRefine?.enabled) return false;
-  if (turnEndedBadly(outcome)) return false;
   const every = config.autoRefine.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS;
-  if (every <= 0) return false;
-  if (completedTurns < 0) {
-    completedTurns = 0; // seed: the seed turn itself doesn't count
-    return false;
-  }
-  completedTurns += 1;
-  if (completedTurns >= every) {
-    completedTurns = 0;
-    return true;
-  }
-  return false;
+  return cadence.tick(every, outcome);
 }
 
 /** The boundary draft custom type for auto-refine steering messages. */

package/src/cadence.ts

@@ -0,0 +1,56 @@
+// Shared completed-turn cadence counter (review simplification #1).
+//
+// Three features — auto-refine, the /refine reminder, and the import-awareness
+// reminder — used to each re-implement the same side-effectful counter: seed
+// on the first observed COMPLETED turn, count completed turns, fire and reset
+// every N. They drifted once already (review #26's turnIndex → turn_end fix
+// had to touch several of them), so the counter now lives here exactly once.
+//
+// Semantics (identical for every consumer):
+//  - Aborted/error turns are inert: they neither seed nor advance the count,
+//    so an aborted turn in between can never shorten the window.
+//  - The seed turn itself does not count.
+//  - every <= 0 disables the cadence (tick never fires).
+//  - Firing resets the count, so the firing turn itself never re-triggers.
+
+/** True when a turn_end's outcome marks a turn that ended badly (pi's
+ *  BoundaryState.outcome: "aborted" | "error"). Undefined is treated as
+ *  completed — current pi always reports the field, but synthetic events and
+ *  the earliest 0.99.x may omit it. */
+export function turnEndedBadly(outcome?: string): boolean {
+  return outcome === "aborted" || outcome === "error";
+}
+
+export interface TurnCadence {
+  /** Observe a turn boundary; true when the cadence fires this turn.
+   *  Aborted/error outcomes and every <= 0 are inert (state untouched). */
+  tick(every: number, outcome?: string): boolean;
+  /** Back to the unseen baseline (session_start: a fork/resume opens a fresh window). */
+  reset(): void;
+}
+
+/** One independent cadence counter. Feature gates stay with the caller. */
+export function makeTurnCadence(): TurnCadence {
+  // Completed turns observed since the last fire (or the seeded baseline).
+  // -1 = unseen.
+  let completedTurns = -1;
+  return {
+    tick(every, outcome) {
+      if (turnEndedBadly(outcome)) return false;
+      if (every <= 0) return false;
+      if (completedTurns < 0) {
+        completedTurns = 0; // seed: the seed turn itself doesn't count
+        return false;
+      }
+      completedTurns += 1;
+      if (completedTurns >= every) {
+        completedTurns = 0;
+        return true;
+      }
+      return false;
+    },
+    reset() {
+      completedTurns = -1;
+    },
+  };
+}

package/src/config.ts

@@ -131,7 +131,12 @@ export const DEFAULT_CONFIG: HarnessConfig = {
 
 export const CONFIG_PATH = join(homedir(), ".pi", "agent", "harness.json");
 
+// Single process-lifetime cache (config is read once per session; tests warm
+// it with an injected path and every later caller shares it — by contract).
 let cached: HarnessConfig | undefined;
+// Path whose JSON existed but failed to parse on the last load — the
+// effective config silently fell back to defaults there (review finding #6).
+let malformedPath: string | undefined;
 
 /** Merge a (possibly partial) parsed file over the defaults. */
 function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
@@ -313,22 +318,44 @@ export async function saveConfig(
   return { written: path, backup, merged, effective };
 }
 
-/** Load the config, merged over defaults. Tolerant: missing/malformed → defaults.
- *  Cached for the process lifetime (config is read once per session). */
+/** Load the config, merged over defaults. Tolerant: a missing file → defaults
+ *  silently (expected for a fresh setup); a MALFORMED file → defaults too, but
+ *  flagged via configMalformed() so the session can warn instead of every
+ *  setting silently stopping (review finding #6). 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;
+  let raw: string | undefined;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    // Missing/unreadable file → defaults, by design.
+  }
+  if (raw === undefined) {
+    cached = { ...DEFAULT_CONFIG };
+    return cached;
+  }
   try {
-    const raw = await readFile(path, "utf8");
     cached = mergeConfig(JSON.parse(raw) as Partial<HarnessConfig>);
+    // Parse succeeded — clear the flag (a previous load may have failed).
+    malformedPath = undefined;
   } catch {
+    malformedPath = path;
     cached = { ...DEFAULT_CONFIG };
   }
   return cached;
 }
 
+/** True when the file at `path` existed but failed to parse on the last
+ *  loadConfig — the effective config silently fell back to defaults. */
+export function configMalformed(path: string = CONFIG_PATH): boolean {
+  return malformedPath === path;
+}
+
 /** Test hook: drop the in-process cache. */
 export function resetConfigCache(): void {
   cached = undefined;
+  malformedPath = undefined;
 }
 
 /** Path of a project's durable layer file: <projectDir>/<slug>.md. */

package/src/corpus.ts

@@ -31,7 +31,7 @@
 
 import { createHash } from "node:crypto";
 import { IMPORTANCE_FLOOR, REFINE_ENTRY, STATE_ENTRY } from "./store.js";
-import { DEDUPE_THRESHOLD, tokenOverlap } from "./proposer.js";
+import { DEDUPE_THRESHOLD, durableLayer, tokenOverlap } from "./proposer.js";
 import { DEFAULT_REF_BUMP } from "./config.js";
 import type { ComponentKind, HarnessItem, HarnessState } from "./types.js";
 
@@ -127,12 +127,6 @@ function hash(content: string): string {
   return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }
 
-/** Durable placement, mirroring planDedupe's private key: only items in the
- *  same layer were ever compared by the planner. */
-function durableLayer(i: HarnessItem): string {
-  return i.scope === "project" ? `project:${i.project ?? ""}` : "global";
-}
-
 // ---- lifecycle ---------------------------------------------------------------
 
 /** One classified lifecycle transition, with the item it happened to.
@@ -309,8 +303,14 @@ export function buildCorpus(entries: Iterable<unknown>, opts: CorpusOptions = {}
     const entry = raw as AnyEntry;
     if (entry.type === "custom" && entry.customType === STATE_ENTRY && entry.data?.state) {
       const next = entry.data.state;
-      const prev = snapshots.at(-1);
-      if (prev) diffSnapshots(prev, next, citeBump, lifecycle);
+      // Implicit EMPTY baseline before the branch's first snapshot (review
+      // #27 fixed this in status.ts; the corpus walk was missed — review
+      // finding #1): a fresh session persists no empty harness-state entry,
+      // so the first create batch / auto-import IS the first snapshot —
+      // without this its `created` events were silently dropped from
+      // lifecycle.jsonl.
+      const prev = snapshots.at(-1) ?? { items: [] };
+      diffSnapshots(prev, next, citeBump, lifecycle);
       snapshots.push(next);
       continue;
     }

package/src/durable.ts

@@ -28,7 +28,7 @@ import { exportDurableLayers, getVersion, importDurableLayers } from "./store.js
 import type { LayerFile, LayerPaths } from "./store.js";
 import type { HarnessItem } from "./types.js";
 import { DEFAULT_IMPORT_REMIND_TURNS, layerFilesFor, loadConfig, projectSlug, type HarnessConfig } from "./config.js";
-import { turnEndedBadly } from "./auto-refine.js";
+import { makeTurnCadence } from "./cadence.js";
 
 /** Real (homedir-based) layer paths. Tests inject their own. */
 function layerPaths(): LayerPaths {
@@ -44,12 +44,11 @@ let lastExportedVersion = -1;
 // BEFORE any export — never clobbering the durable layers (review #26).
 let startSyncRan = false;
 
-// Completed turns observed since the last import reminder (or the seeded
-// baseline). -1 = unseen. Aborted/error turns never touch this count — the
-// cadence counts completed turns of work (mirrors remind.ts / #18), never raw
-// turn indices: pi's `turnIndex` resets to 0 on every agent_start (each user
-// prompt), so index deltas would never accumulate across prompts (review #26).
-let completedTurns = -1;
+// The import-reminder cadence counter (shared implementation — see
+// cadence.ts): completed turns of work, never raw turn indices — pi's
+// `turnIndex` resets to 0 on every agent_start (each user prompt), so index
+// deltas would never accumulate across prompts (review #26).
+const importCadence = makeTurnCadence();
 
 /** A durable-imported item the user should stay aware of (id + what it says). */
 export interface ImportedRef {
@@ -75,7 +74,7 @@ export function resetDurableSync(): void {
   lastExportedVersion = -1;
   startSyncRan = false;
   importedThisSession = [];
-  completedTurns = -1;
+  importCadence.reset();
   remindersFired = 0;
 }
 
@@ -154,20 +153,11 @@ export function evaluateImportReminder(
   if (!config.autoImport) return false;
   if (config.importRemind?.enabled === false) return false;
   if (importedCount <= 0) return false;
-  if (turnEndedBadly(outcome)) return false;
   if (remindersFired >= MAX_IMPORT_REMINDERS) return false;
   const every = config.importRemind?.everyTurns ?? DEFAULT_IMPORT_REMIND_TURNS;
-  if (completedTurns < 0) {
-    completedTurns = 0; // seed: the seed turn itself doesn't count
-    return false;
-  }
-  completedTurns += 1;
-  if (completedTurns >= every) {
-    completedTurns = 0;
-    remindersFired += 1;
-    return true;
-  }
-  return false;
+  if (!importCadence.tick(every, outcome)) return false;
+  remindersFired += 1;
+  return true;
 }
 
 /** Keep importedThisSession truthful against the live store (review #27): an
@@ -188,8 +178,9 @@ function reconcileImported(): void {
 export function registerImportReminder(pi: ExtensionAPI): void {
   pi.on("turn_end", async (event, ctx) => {
     const config = await loadConfig();
-    // Completed-turn counting (see `completedTurns`): aborted/error outcomes
-    // are inert and pi's per-agent-start turnIndex resets never matter.
+    // Completed-turn counting (the shared cadence — see cadence.ts):
+    // aborted/error outcomes are inert and pi's per-agent-start turnIndex
+    // resets never matter.
     reconcileImported(); // deleted/deactivated imports stop being advertised (review #27)
     const outcome = (event as { outcome?: string }).outcome;
     if (!evaluateImportReminder(config, outcome, importedThisSession.length)) {

package/src/harness.ts

@@ -189,13 +189,18 @@ function completions(argumentPrefix: string) {
     );
   }
 
-  // Flag completion ("-…" prefix, or a fresh token for flag-taking subs —
+  // Flag completion ("-" prefix, or a fresh token for flag-taking subs —
   // the "-" prefix also matches short flags like list's -f). A fresh
   // --kind/--scope/--model value was already completed above (early
   // return), so a fresh token here means "offer the remaining flags".
-  if (last.startsWith("-") || (fresh && sub in FLAGS)) {
+  // Object.hasOwn guards BOTH the condition and the lookup (review finding
+  // #2): a bogus subcommand naming an inherited Object member ("constructor",
+  // "toString", …) otherwise resolves FLAGS[sub] to Function — the `?? []`
+  // does not catch it (Function is not nullish) and .filter throws. Same
+  // class as the expandPreset fix in review #26.
+  if (last.startsWith("-") || (fresh && Object.hasOwn(FLAGS, sub))) {
     const used = new Set(before.filter((t) => t.startsWith("-")));
-    const rows = (FLAGS[sub] ?? []).filter((f) => !used.has(f.name));
+    const rows = (Object.hasOwn(FLAGS, sub) ? FLAGS[sub]! : []).filter((f) => !used.has(f.name));
     const items = rows
       .filter((f) => f.name.startsWith(last))
       .map((f) => ({ value: [...before, f.name].join(" "), label: f.name, description: f.description }));
@@ -564,6 +569,17 @@ async function handleMove(
   }
 }
 
+/** Numbered item listing shared by the split/adopt steering prompts. The
+ *  format had already drifted once (adopt carries full-precision importance
+ *  because the agent copies it verbatim into create deltas — review #25;
+ *  split rounds to 2). One renderer keeps the layout in lockstep. */
+function formatItemLines(items: HarnessItem[], importance: "raw" | "fixed"): string[] {
+  return items.flatMap((i, n) => [
+    `${n + 1}. [${i.id}] (${i.kind}, importance ${importance === "fixed" ? i.importance.toFixed(2) : i.importance}, ${i.scope === "project" ? `project "${i.project ?? ""}"` : "global"}) ${i.content}`,
+    `   evidence: ${i.evidence}`,
+  ]);
+}
+
 /** Compose the /harness split steering message: the agent classifies every
  *  active item global-vs-project and applies the classification as ONE
  *  harness_mutate batch of scope-only update deltas — visible in the
@@ -572,7 +588,7 @@ function buildSplitPrompt(items: HarnessItem[], slug: string, cwd: string): stri
   const lines = [
     `/harness split — classify ${items.length} Continual Harness item(s) into durable scopes`,
     "",
-    `Current project: ${cwd} (slug \"${slug}\").`,
+    `Current project: ${cwd} (slug "${slug}").`,
     "",
     "For EACH item below, decide its durable scope:",
     "- `project` — only useful when working in THIS project (deploy procedures, project architecture, local conventions, project-specific quirks).",
@@ -583,13 +599,8 @@ function buildSplitPrompt(items: HarnessItem[], slug: string, cwd: string): stri
     `(the "project" slug is stamped server-side to "${slug}"; content/evidence/importance stay untouched). Give every item an explicit decision — skip nothing. If an item is project-specific only in part, choose "project" and leave generalizing it for a later /refine.`,
     "",
     "Items:",
+    ...formatItemLines(items, "fixed"),
   ];
-  items.forEach((i, n) => {
-    lines.push(
-      `${n + 1}. [${i.id}] (${i.kind}, importance ${i.importance.toFixed(2)}, ${i.scope === "project" ? `project \"${i.project ?? ""}\"` : "global"}) ${i.content}`,
-      `   evidence: ${i.evidence}`,
-    );
-  });
   return lines.join("\n");
 }
 
@@ -677,16 +688,8 @@ export function buildAdoptPrompt(
       : "- Summarize at the end: adopted N, skipped M (stays) — with one short reason per skip.",
     "",
     "Items:",
+    ...formatItemLines(items, "raw"),
   );
-  items.forEach((i, n) => {
-    // Full precision (no toFixed): the agent copies the listed importance
-    // verbatim into the create delta, and a rounded value would change the
-    // copy's ranking against existing items in injection selection (review #25).
-    lines.push(
-      `${n + 1}. [${i.id}] (${i.kind}, importance ${i.importance}, ${i.scope === "project" ? `project \"${i.project ?? ""}\"` : "global"}) ${i.content}`,
-      `   evidence: ${i.evidence}`,
-    );
-  });
   return lines.join("\n");
 }
 

package/src/index.ts

@@ -17,7 +17,7 @@ import { registerOutcome, resetOutcome } from "./outcome.js";
 import { registerAutoExport, registerImportReminder, resetDurableSync, syncDurableOnStart } from "./durable.js";
 import { getState, reconstruct, setActiveModelKey, setSessionProject, STATE_ENTRY } from "./store.js";
 import { resetHints } from "./hints.js";
-import { projectSlug } from "./config.js";
+import { CONFIG_PATH, configMalformed, loadConfig, projectSlug } from "./config.js";
 
 export default function continualHarness(pi: ExtensionAPI): void {
   // Rebuild in-memory state from the current branch on every session start /
@@ -40,6 +40,16 @@ export default function continualHarness(pi: ExtensionAPI): void {
     // Cache the session's project slug BEFORE any tool delta can arrive: it is
     // the server-side stamp for scope:"project" (harness_mutate has no ctx).
     setSessionProject(projectSlug(ctx.cwd));
+    // Surface a malformed harness.json ONCE per session start: loadConfig
+    // falls back to defaults for it, so without this warning every configured
+    // setting would silently stop applying (review finding #6).
+    await loadConfig();
+    if (configMalformed()) {
+      ctx.ui.notify(
+        `Continual Harness: ${CONFIG_PATH} is not valid JSON — every setting is on its DEFAULT until the file parses.`,
+        "warning",
+      );
+    }
     reconstruct(ctx.sessionManager.getBranch() as Iterable<unknown>);
     const n = getState().items.length;
     if (n > 0) {

package/src/proposer.ts

@@ -204,8 +204,10 @@ function truncate(s: string, n = 48): string {
 
 /** Durable placement of an item: "global" or "project:<slug>". Only items in
  *  the SAME layer merge — a merge must never silently move an item between
- *  durable files or projects. */
-function durableLayer(i: HarnessItem): string {
+ *  durable files or projects. Exported: the corpus builder filters dedupe
+ *  pair candidates by the same layer key (review simplification #2 — the two
+ *  copies had to stay in sync by hand). */
+export function durableLayer(i: HarnessItem): string {
   return i.scope === "project" ? `project:${i.project ?? ""}` : "global";
 }
 
@@ -432,21 +434,55 @@ export const dedupeProposer: DeltaProposer = {
 
 // ---- registry -------------------------------------------------------------
 
-const registry = new Map<string, DeltaProposer>([
+// Cross-instance registry key (0.17.0). pi's extension loader isolates module
+// instances between extensions (a fresh jiti per extension load, module cache
+// off), so a companion package's `import { registerProposer } from
+// "pi-continual-harness"` resolves to a DIFFERENT copy of this module than the
+// one whose /refine reads the registry — a module-level Map made companion
+// registrations silently invisible. Backing the registry with a process-wide
+// global makes registration work no matter which copy each side holds.
+//
+// The string is the public contract: companions that avoid importing this
+// package at all (thin startup entries) can push a DeltaProposer straight into
+// `globalThis[Symbol.for("pi-continual-harness.proposers")]`.
+const REGISTRY_KEY = Symbol.for("pi-continual-harness.proposers");
+type ProposerRegistry = Map<string, DeltaProposer>;
+
+function globalRegistry(): ProposerRegistry {
+  const g = globalThis as Record<symbol, unknown>;
+  let r = g[REGISTRY_KEY] as ProposerRegistry | undefined;
+  if (!(r instanceof Map)) {
+    r = new Map<string, DeltaProposer>();
+    g[REGISTRY_KEY] = r;
+  }
+  return r;
+}
+
+// Built-ins stay module-local: they are pure functions of their input, and
+// keeping them off the shared map means two isolated harness copies never hand
+// each other's closures to /refine. External registrations live ONLY in the
+// shared map, so every copy can see them.
+const builtins = new Map<string, DeltaProposer>([
   ["steering", steeringProposer],
   ["dedupe", dedupeProposer],
 ]);
 
-/** Register (or replace) a named proposer. For external extensions. */
+/** Register (or replace) a named proposer. For external extensions. Writes to
+ *  the process-wide registry (Symbol.for("pi-continual-harness.proposers")),
+ *  so it takes effect across pi's per-extension module isolation. */
 export function registerProposer(p: DeltaProposer): void {
-  registry.set(p.name, p);
+  globalRegistry().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;
+  const key = name ?? "steering";
+  const custom = globalRegistry().get(key);
+  // Defensive: the shared map can be written by anyone in the process.
+  if (custom && typeof custom.propose === "function") return custom;
+  return builtins.get(key) ?? steeringProposer;
 }
 
 export function listProposers(): string[] {
-  return [...registry.keys()];
+  return [...new Set([...builtins.keys(), ...globalRegistry().keys()])];
 }

package/src/refine.ts

@@ -20,7 +20,7 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Context, Model, TextContent } from "@earendil-works/pi-ai";
 import { applyDeltas, DEFAULT_DURABLE_PATH, exportDurableLayers, PROJECT_DURABLE_DIR, REFINE_ENTRY, snapshotState } from "./store.js";
-import { getProposer, DEFAULT_DEDUPE } from "./proposer.js";
+import { getProposer, listProposers, DEFAULT_DEDUPE } from "./proposer.js";
 import type { CompleteOptions, CompleteResult } from "./proposer.js";
 import { buildClassify } from "./classify.js";
 import { resolveBindingKey, branchEntries } from "./vmodel.js";
@@ -58,10 +58,13 @@ export function registerRefine(pi: ExtensionAPI): void {
     description:
       "Online self-improvement: review recent trajectory and propose evidence-backed CRUD deltas to the harness state. Usage: /refine [lookback-turns] [--commit] [--proposer steering|dedupe] [--threshold 0.75]",
     handler: async (args, ctx) => {
-      const { lookback, commit, proposer, threshold, thresholdInvalid } = parseArgs(args);
+      const { lookback, commit, proposer, threshold, thresholdInvalid, unknownFlags } = parseArgs(args);
       if (thresholdInvalid) {
         ctx.ui.notify("Invalid --threshold ignored (expected 0 < t ≤ 1).", "warning");
       }
+      if (unknownFlags.length > 0) {
+        ctx.ui.notify(`Unknown /refine flag(s) ignored: ${unknownFlags.join(", ")}.`, "warning");
+      }
       await runRefine(pi, ctx, {
         lookback,
         commit,
@@ -120,6 +123,14 @@ export async function runRefine(
   const lookback = options.lookback ?? DEFAULT_LOOKBACK_TURNS;
   const commit = options.commit ?? false;
   const proposer = getProposer(options.proposer);
+  // An explicit but unknown --proposer must not silently run steering
+  // (review finding #7): name the fallback so a typo is visible.
+  if (options.proposer && proposer.name !== options.proposer) {
+    ctx.ui.notify(
+      `Unknown proposer "${options.proposer}" — falling back to steering. Registered: ${listProposers().join(", ")}.`,
+      "warning",
+    );
+  }
   ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)… [${proposer.name}]`);
 
   const evidence = gatherEvidence(ctx, lookback);
@@ -248,6 +259,7 @@ function parseArgs(args: string): {
   proposer: string | undefined;
   threshold: number | undefined;
   thresholdInvalid: boolean;
+  unknownFlags: string[];
 } {
   const parts = args.trim().split(/\s+/).filter(Boolean);
   let lookback = DEFAULT_LOOKBACK_TURNS;
@@ -255,6 +267,7 @@ function parseArgs(args: string): {
   let proposer: string | undefined;
   let threshold: number | undefined;
   let thresholdInvalid = false;
+  const unknownFlags: string[] = [];
   const readThreshold = (raw: string): void => {
     const v = Number(raw);
     if (Number.isFinite(v) && v > 0 && v <= 1) threshold = v;
@@ -268,8 +281,11 @@ function parseArgs(args: string): {
     else if (p === "--threshold" && i + 1 < parts.length) readThreshold(parts[++i]!);
     else if (p.startsWith("--threshold=")) readThreshold(p.slice("--threshold=".length));
     else if (/^\d+$/.test(p)) lookback = Math.max(1, Math.min(200, Number(p)));
+    // Unknown --flags are collected, not silently dropped: a typo like
+    // "--comit" used to vanish and run a plain refine (review finding #7).
+    else if (p.startsWith("--")) unknownFlags.push(p);
   }
-  return { lookback, commit, proposer, threshold, thresholdInvalid };
+  return { lookback, commit, proposer, threshold, thresholdInvalid, unknownFlags };
 }
 
 export function gatherEvidence(ctx: ExtensionContext, lookback: number): string {

package/src/remind.ts

@@ -28,18 +28,17 @@ import {
   type HarnessConfig,
   loadConfig,
 } from "./config.js";
-import { turnEndedBadly } from "./auto-refine.js";
+import { makeTurnCadence } from "./cadence.js";
 import { getState } from "./store.js";
 
-// Completed turns observed since the last reminder (or the seeded baseline).
-// -1 = unseen. Aborted/error turns never touch this count.
-let completedTurns = -1;
+// The reminder cadence counter (shared implementation — see cadence.ts).
+const cadence = makeTurnCadence();
 // Fired reminders this session — the rotation seed for the detailed tier.
 let fires = 0;
 
 /** Test hook: reset cadence baseline and rotation state. */
 export function resetReminder(): void {
-  completedTurns = -1;
+  cadence.reset();
   fires = 0;
 }
 
@@ -89,16 +88,8 @@ export interface ReminderDecision {
 export function evaluateReminder(config: HarnessConfig, outcome?: string): ReminderDecision {
   const idle: ReminderDecision = { fire: false, detail: false, fires, detailOrdinal: 0 };
   if (!config.remindRefine?.enabled) return idle;
-  if (turnEndedBadly(outcome)) return idle;
   const every = config.remindRefine.everyTurns ?? DEFAULT_EVERY_TURNS;
-  if (every <= 0) return idle;
-  if (completedTurns < 0) {
-    completedTurns = 0; // seed: the seed turn itself doesn't count
-    return idle;
-  }
-  completedTurns += 1;
-  if (completedTurns < every) return idle;
-  completedTurns = 0;
+  if (!cadence.tick(every, outcome)) return idle;
   fires += 1;
   const detailEvery = config.remindRefine.detailEvery ?? DEFAULT_DETAIL_EVERY;
   const detail = detailEvery > 0 && fires % detailEvery === 0;

package/src/select.ts

@@ -163,6 +163,11 @@ export function selectForInjection(
     }
   }
 
+  // FOOTER_TOKENS is reserved unconditionally: the footer renders whenever
+  // ANY pass omits an item (the token pass below can be the first to omit),
+  // and a test pins "rendered block never exceeds the budget". Paying 18
+  // tokens always keeps that guarantee exact (review simplification —
+  // reverted: the conditional reserve broke the budget invariant).
   const overhead = INTRO_TOKENS + presentKinds.length * SECTION_HEADER_TOKENS + FOOTER_TOKENS;
   let remaining = Math.max(0, n.maxTokens - overhead);
   const taken: Ranked[] = [];

package/src/status.ts

@@ -110,24 +110,36 @@ function aggregateImpact(
       for (const t of classifyTransition(prev, next, citeBump)) {
         const key = t.item.ownerModel || "(orphan)";
         const o = owner(key);
-        if (t.event === "created") {
-          whole.created += 1;
-          o.created += 1;
-        } else if (t.event === "kept") {
-          whole.kept += 1;
-          o.kept += 1;
-        } else if (t.event === "dropped") {
-          whole.dropped += 1;
-          o.dropped += 1;
-        } else if (t.event === "cited") {
-          whole.cited += 1;
-          o.cited += 1;
-        } else if (t.event === "pruned") {
-          whole.pruned += 1;
-          o.pruned += 1;
-        } else {
-          whole.deleted += 1;
-          o.deleted += 1;
+        // A switch (not if/else): a future LifecycleEvent falls to default
+        // and is NOT counted as a delete — the old trailing `else` would have
+        // silently mislabeled it (review simplification #5).
+        switch (t.event) {
+          case "created":
+            whole.created += 1;
+            o.created += 1;
+            break;
+          case "kept":
+            whole.kept += 1;
+            o.kept += 1;
+            break;
+          case "dropped":
+            whole.dropped += 1;
+            o.dropped += 1;
+            break;
+          case "cited":
+            whole.cited += 1;
+            o.cited += 1;
+            break;
+          case "pruned":
+            whole.pruned += 1;
+            o.pruned += 1;
+            break;
+          case "deleted":
+            whole.deleted += 1;
+            o.deleted += 1;
+            break;
+          default:
+            break; // unknown future event: ignore, never mislabel
         }
       }
       snapshots.push(next);

package/src/store.ts

@@ -235,9 +235,14 @@ export function reconstruct(entries: Iterable<unknown>): void {
   // the active model on first contact (see adoptOrphans); missing/corrupt
   // scope → "global" (a project item without a slug cannot be placed in a
   // layer, so it falls back to the global durable file).
-  state = last
+  state = last && Array.isArray(last.items)
     ? {
-        items: last.items.map((i): HarnessItem => {
+        // Guard both levels (review finding #5): one corrupt harness-state
+        // entry (state without an items array, or non-object items) must not
+        // crash the session_start handler — degrade to the salvageable part.
+        items: last.items
+          .filter((i): i is HarnessItem => Boolean(i) && typeof i === "object")
+          .map((i): HarnessItem => {
           const item: HarnessItem = { ...i, ownerModel: i.ownerModel ?? "", scope: "global" };
           if (i.scope === "project" && i.project) {
             item.scope = "project";
@@ -246,7 +251,7 @@ export function reconstruct(entries: Iterable<unknown>): void {
             delete item.project;
           }
           return item;
-        }),
+          }),
       }
     : { items: [] };
   version = 0;
@@ -277,9 +282,15 @@ export function decayAndPrune(
   }
   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, decayed };
+  const pruned = before - state.items.length;
+  // No-op idempotency (review finding #3): like mergeParsed and adoptOrphans,
+  // a prune that changed nothing persists nothing — otherwise every no-op
+  // /harness prune appends a harness-state entry of pure /tree noise.
+  if (decayed > 0 || pruned > 0) {
+    version += 1;
+    persist(state, version);
+  }
+  return { pruned, decayed };
 }
 
 /** Nudge an item's importance by delta (clamped to [0,1]) and touch updatedAt. */
@@ -587,6 +598,16 @@ function mergeParsed(
 ): DurableImportResult {
   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));
+  // Content fallback (review finding #4): id-less bullets and foreign
+  // (non-h_) ids never hit the id map, so import→import of the same file
+  // without an export in between used to duplicate the item every time.
+  // Matching kind+content folds the re-import into the item the first import
+  // created. Keyed with \x00 so content cannot collide across kinds.
+  const existingByContent = new Map(state.items.map((i) => [`${i.kind}${i.content}`, i] as const));
+  // Store ids any parsed line resolved to (id match, content match, or
+  // create): with --prune these count as "present in the file" even when the
+  // file never named the id (an id-less bullet carries no fileIds entry).
+  const touchedIds = new Set<string>();
   const preActiveIds = new Set(state.items.filter((i) => i.active).map((i) => i.id));
   // Distinct parsed items: an explicit id folding across layers (the normal
   // global-then-project collision) is ONE item, not one per copy; bullets
@@ -609,8 +630,10 @@ function mergeParsed(
   const updatedIds: string[] = [];
   const now = Date.now();
   for (const p of parsed) {
-    const existing = p.id ? existingById.get(p.id) : undefined;
+    const existing =
+      (p.id ? existingById.get(p.id) : undefined) ?? existingByContent.get(`${p.kind}${p.content}`);
     if (existing) {
+      touchedIds.add(existing.id);
       const importance = clamp(p.importance);
       const ownerModel = p.ownerModel ?? "";
       // Durable wins; reactivate; keep createdAt. Idempotent imports skip the
@@ -639,6 +662,10 @@ function mergeParsed(
       updated += 1;
       updatedIds.push(existing.id);
       dirty = true;
+      // A content-matched line that named a foreign id: register it so a
+      // second copy of that id later in the same import id-matches instead
+      // of content-matching again (same dedupe as the create branch below).
+      if (p.id) existingById.set(p.id, existing);
     } else {
       const id = p.id && /^h_/.test(p.id) ? p.id : genId();
       state.items.push({
@@ -656,10 +683,11 @@ function mergeParsed(
       created += 1;
       createdIds.push(id);
       dirty = true;
-      // Keep the lookup current so a later layer's copy of the same id
-      // UPDATES the item we just created instead of duplicating it (the same
-      // id in both layers is the normal collision case, not an anomaly).
+      // Keep the lookups current so a later copy of the same item (another
+      // layer's id collision, or a repeated id-less bullet) UPDATES the item
+      // we just created instead of duplicating it.
       if (p.id) existingById.set(p.id, state.items[state.items.length - 1]!);
+      existingByContent.set(`${p.kind}${p.content}`, state.items[state.items.length - 1]!);
     }
   }
 
@@ -670,6 +698,7 @@ function mergeParsed(
       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
+      if (touchedIds.has(i.id)) return true; // matched by content (id-less / foreign id)
       return false; // was active before, absent from the file → drop
     });
     pruned = before - state.items.length;

package/src/tools.ts

@@ -178,12 +178,16 @@ export function registerTools(pi: ExtensionAPI): void {
         },
         getActiveModelKey(),
       );
-      const summary = summarize(applied);
       const created = applied.filter((a) => a.op === "create").length;
       const updated = applied.filter((a) => a.op === "update").length;
       const deleted = applied.filter((a) => a.op === "delete").length;
       return {
-        content: [{ type: "text", text: summary }],
+        content: [
+          {
+            type: "text",
+            text: `Applied ${applied.length} delta(s): ${created} created, ${updated} updated, ${deleted} deleted.`,
+          },
+        ],
         details: { applied, version: getState().items.length },
         structuredContent: { applied: applied.length, created, updated, deleted },
       };
@@ -191,13 +195,6 @@ export function registerTools(pi: ExtensionAPI): void {
   });
 }
 
-function summarize(applied: AppliedDelta[]): string {
-  const created = applied.filter((a) => a.op === "create").length;
-  const updated = applied.filter((a) => a.op === "update").length;
-  const deleted = applied.filter((a) => a.op === "delete").length;
-  return `Applied ${applied.length} delta(s): ${created} created, ${updated} updated, ${deleted} deleted.`;
-}
-
 /** Tally `items` by a string key, rendered as "key (n), key (n)". */
 function tally<T>(items: T[], key: (i: T) => string): string {
   const counts = new Map<string, number>();