pi-continual-harness 0.13.0 → 0.15.0

package/README.md

@@ -70,11 +70,13 @@ Durable I/O (round-trip with pi-reflect):
 /harness drop <id>               # nudge importance down (−0.1)
 /harness move <id> global|project  # move an item between durable layers
 /harness split                   # steer the agent to classify every item's scope
+/harness adopt --from <provider/id> [--all]  # steer the agent to copy another model's items here
 /harness push-mem [--all|--kind <kind>|--model <provider/id|active>]  # persist active items to pi-mem (save_memory)
+/harness setup [--preset <quiet|recommended|power>] [--yes]  # guided config wizard
 ```
 
-Subcommands, flags, `--kind`/`--model` values, `move` scopes, and `keep`/
-`drop`/`move` item ids all autocomplete in the TUI as you type after
+Subcommands, flags, `--kind`/`--model`/`--from` values, `move` scopes, and
+`keep`/`drop`/`move` item ids all autocomplete in the TUI as you type after
 `/harness `.
 
 **Durable layers.** Every item carries its own durable scope: `global`
@@ -104,7 +106,10 @@ The model-facing tools:
 
 - `harness_list({ kind?, model? })` — read current state. `model` defaults to
   the active model's items (what gets injected this turn); `"*"` returns every
-  model.
+  model. Empty results are **diagnostic**: the message distinguishes a
+  genuinely empty store (with zero-state guidance) from items hidden by the
+  model or kind filter (with a tally and a `model: "*"` pointer), so an
+  empty list never reads as "broken".
 - `harness_mutate { deltas: [...] }` — apply a batch of `create` / `update` /
   `delete` deltas. Every `create` requires `evidence`. New items are stamped
   automatically with the active model (see [Model binding](#model-binding-per-model-isolation)).
@@ -136,15 +141,39 @@ unchanged by a push — pi-mem gets a separate copy.
 
 ## Configuration
 
+**First-run setup:** instead of hand-editing the JSON below, run
+`/harness setup`. It is a guided wizard:
+
+1. Shows the **current effective config** (your file merged over the shipped
+   defaults) plus the durable-layer paths.
+2. Offers three **presets**: `quiet` (pin every opt-in to the shipped
+   defaults), `recommended` (`autoImport` + import reminders on), `power`
+   (`recommended` + `autoRefine`). Each preset is shown as a declarative diff
+   before anything is applied.
+3. Confirms **each delta** with a one-line rationale. Autonomous switches
+   get their own explicit "this lets the agent mutate state on a cadence"
+   confirmation regardless of preset.
+4. Writes via one reviewed path: backs up the existing file
+   (`harness.json.bak-<timestamp>`), atomically writes the merged result,
+   then reloads and prints the effective config exactly as pi will read it.
+
+For scripted setups: `/harness setup --preset recommended --yes` (the `--yes`
+flag is the scripted form of the confirmations, so it enables autonomous
+features without prompts). Nothing is written on unknown input, a cancelled
+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):
 
 ```json
 {
   "autoImport": false,
+  "importRemind": { "enabled": true, "everyTurns": 25 },
   "proposer": "steering",
   "dedupe": { "threshold": 0.6, "merge": true },
   "injection": { "enabled": true, "maxTokens": 1500, "maxPerKind": 10, "charsPerToken": 4 },
-  "remindRefine": { "enabled": false, "everyTurns": 50 },
+  "remindRefine": { "enabled": true, "everyTurns": 25, "detailEvery": 4 },
   "autoRefine": { "enabled": false, "everyTurns": 100, "commit": false, "gate": false },
   "outcomeImportance": { "enabled": false, "bump": 0.03 },
   "classifier": { "model": "typesafe/jev-latest" },
@@ -160,7 +189,21 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   changed since the last export. This is what makes `/refine` output survive
   into **new** sessions without manual export/import ceremony. Both halves are
   visible (one notify line) and use the same persisted `harness-state` entries
-  as every other mutation (`/tree` rollback covers them).
+  as every other mutation (`/tree` rollback covers them). Enabling it
+  mid-session (e.g. via `/harness setup`) is safe: the first `turn_end`
+  imports the layers *before* any export, so a late enable can never
+  overwrite the durable files with a never-imported store.
+- **`importRemind`** — **awareness reminders** for that sync (effective only
+  when `autoImport` is on; default `{ "enabled": true, "everyTurns": 25 }`).
+  The session-start import doesn't just count — it **lists what arrived**
+  (item id, kind, first words of content), and every `everyTurns` turns a
+  one-line reminder re-surfaces the imported items so silently-injected
+  instructions never go unnoticed (full list via the agent's `harness_list`
+  tool — `/harness status` shows only counts). Bounded: at most 3 reminders
+  per imported batch, then quiet until the next session; aborted/error turns
+  are inert (completed-turn cadence). Kill-switch:
+  `{ "importRemind": { "enabled": false } }` (the start-of-session listing
+  still fires).
 - **`injection`** — the selection policy for WHAT gets surfaced in the system
   prompt each turn (see [Injection selection](#injection-selection-on-by-default)).
   ON by default: items are importance-ordered, capped at `maxPerKind` (default
@@ -181,9 +224,20 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   companion packages inject a richer comparator whose return may **abstain**
   per pair (`{ score, abstain }` — see [`SimilarityResult`](#proposers)); an
   abstaining pair is always kept, never merged or deleted.
-- **`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.
+- **`remindRefine`** — the `turn_end` **activation nudge**, ON by default
+  (informational only; it never mutates state). Every `everyTurns` completed
+  turns (default 25) a one-line reminder suggests `/refine`, garnished with
+  live data from the store (e.g. "12 active item(s), 4 never cited since
+  creation"; an empty store gets first-run guidance instead). Every
+  `detailEvery`-th reminder (default 4: at the default cadence, roughly
+  every 100 turns) escalates to a rotating educational guide: how the loop
+  works (with alternate descriptions so it never reads as boilerplate), the
+  `/refine` workflow, `keep`/`drop`/`prune --decay` hygiene, `push-mem`,
+  `split`, `export-corpus`, and a recommended starter config. Fresh installs
+  used to be silent; that was the bug, not the feature. Aborted/error turns
+  are skipped, so `everyTurns` counts completed turns of work. Silence it
+  with `{ "remindRefine": { "enabled": false } }`; `detailEvery: 1` makes
+  every reminder detailed.
 - **`autoRefine`** — opt-in autonomous self-improvement (**off by default**).
   When `enabled`, the agent runs `/refine` itself every `everyTurns` turns
   (default 100). It is one of the package's opt-in autonomous paths: it reuses
@@ -195,14 +249,21 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   signal, not just time (errors fall back to the plain cadence). The steering
   prompt is delivered via the pi ≥ 0.87 actionable `turn_end` boundary (a
   structural `harness.auto-refine-request` entry + `continue: true`), not a
-  synthetic user message.
+  synthetic user message. Aborted/error turns (pi `turn_end`
+  `BoundaryState.outcome`) are inert: they neither seed nor advance the
+  cadence window — a refine never fires over partial evidence.
 - **`classifier`** — opt-in classifier model (pi ≥ 0.99) for the cheap gated
   paths: `"provider/id"` or a bare id of a **classifier** catalog entry, e.g.
   `"typesafe/jev-latest"` or a local `llama-cpp` classifier (every chat model
-  listed for llama.cpp also appears as a classifier). When set and resolvable
-  it enables the classifier-confirmed dedupe (see `dedupe` above) and the
-  auto-refine `gate`. When unset or unresolvable, every classifier feature
-  degrades to its no-classifier behavior.
+  listed for llama.cpp also appears as one). With pi ≥ 1.1.0 the catalog also
+  offers OpenAI's GPT-6 Luna through the Decisions API (e.g.
+  `"openai/gpt-6-luna"`, needs `OPENAI_API_KEY`) and the native llama.cpp
+  decision models (Julia-1, Laya, Kev, lev, OpenJev through `/v1/systemone`,
+  llama.cpp ≥ 0.6.0 — listed *only* as classifiers, which is exactly our use:
+  a free local gate). When set and resolvable it enables the
+  classifier-confirmed dedupe (see `dedupe` above) and the auto-refine `gate`.
+  When unset or unresolvable, every classifier feature degrades to its
+  no-classifier behavior.
 - **`virtualBinding`** — how the per-model isolation key treats pi **virtual
   models** (router extensions, pi ≥ 0.99). Default `"virtual"`: the key is
   the selected model's own `provider/id` — a router starts a blank harness.
@@ -215,19 +276,23 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
 - **`outcomeImportance`** — opt-in autonomous **promotion** loop (**off by
   default**). When `enabled`, a `turn_end` hook bumps (+`bump`, default 0.03)
   the importance of any active item the agent cited by its `[h_xxxx]` tag in the
-  turn's output. Referenced items gain importance and get their `updatedAt`
+  turn's output. Citations are read from completed turns only — an aborted
+  turn's partial text is scanned by the next completed turn (the initial seed
+  turn itself is never scanned, as before). Referenced items
+  gain importance and get their `updatedAt`
   touched (so they survive time-based decay); ignored items keep decaying. This
   is the package's second opt-in autonomous path — promotion only, never
   deletes, persisted/branchable like `harness_mutate`. Autonomous demotion from
   outcomes is intentionally NOT done (high false-positive); use `/harness drop`,
   `prune --decay`, or the `dedupe` proposer for that.
 
-> **Deprecated:** `durableScope` (0.9.0). Items now carry their own scope
-> (`/harness move`), and durable I/O is always layered — the key no longer
-> switches anything but is still parsed so existing configs keep loading.
-> Migration from a `durableScope: "project"` setup: run `/harness import` once
-> in the project (its file's items adopt project scope), then move any strays
-> with `/harness move` (or classify the whole store with `/harness split`).
+> **Removed:** the store-wide `durableScope` config key (deprecated 0.9.0,
+> removed now). Items carry their own scope (`/harness move`), and durable I/O
+> is always layered. Config files that still set the key load fine — unknown
+> keys are ignored. Migration from a `durableScope: "project"` setup: run
+> `/harness import` once in the project (its file's items adopt project
+> scope), then move any strays with `/harness move` (or classify the whole
+> store with `/harness split`).
 
 ## How it works
 
@@ -276,6 +341,29 @@ How the binding is set and respected:
 - **Durable round-trip preserves owner.** `/harness export` tags each item with
   `model: provider/id`; `/harness import` restores it. An item whose tag
   pi-reflect stripped becomes an orphan and is adopted by the active model.
+- **Carrying owned items across models: `/harness adopt`.** Orphan adoption
+  only covers *unowned* items. `/harness adopt --from <provider/id>` is the
+  reviewable path for owned ones: it steers the agent to classify the source
+  model's active items **generalizes** (engineering practices, user
+  preferences, project facts) vs **stays** (that model's quirks, formatting
+  preferences, failure modes), then apply the adoption as ONE `harness_mutate`
+  batch of create deltas. It is **copy, not move**: the source model's harness
+  stays untouched, content is copied verbatim (importance is listed at full
+  precision so the copy keeps its exact ranking), and evidence is annotated
+  `adopted from <provider/id>`. Because `ownerModel` is never model-settable,
+  the creates stamp to the **active** model via the normal create-stamping
+  path — audited and `/tree`-rollback-able like every mutation. `--all` skips
+  the filter; overlaps afterwards clean up with `/refine --proposer dedupe`.
+  Two store-level filters keep the copy honest (review #25): items scoped to
+  a **different project** are skipped (a copy would re-stamp them into this
+  session's project — adopt them from a session in that project instead),
+  and content the adopter already owns is skipped **before** the batch cap,
+  so re-running against a >20-item source reaches new items instead of
+  re-selecting the same top ones. The self-adopt guard compares against the
+  **resolved binding key** (`virtualBinding`-aware — under `physical` a
+  router selection adopts as the routed model), the same key
+  create-stamping uses. Explicit and manual only — there is no automatic
+  cross-model adoption.
 
 Manual commands (`export`, `import`, `move`, `split`, `keep`, `drop`, `prune`,
 `push-mem`, `status`) operate on the **whole store** by design — they are
@@ -410,10 +498,10 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
   auto-import + turn_end layered auto-export when the store changed —
   `/refine` output survives into new sessions with zero ceremony. Off by
   default; every action visible and `/tree`-rollback-able.
-- Optional config (`~/.pi/agent/harness.json`): the durable-sync opt-in, an
-  opt-in `turn_end` reminder, opt-in `turn_end` auto-refine, and an opt-in
-  `turn_end` outcome-importance loop — the package's opt-in autonomous
-  paths (all off by default).
+- Optional config (`~/.pi/agent/harness.json`): the durable-sync opt-in, a
+  default-on `turn_end` reminder (notify-only; the activation nudge), and the
+  opt-in `turn_end` auto-refine and outcome-importance loops. The package's
+  autonomous paths stay opt-in and off by default.
 - **Pluggable delta proposers** with a registry: `steering` (default) and
   `dedupe` (rule-based) shipped; `registerProposer()` for custom ones.
 - **Per-model isolation**: every item is bound to a `provider/id` and injected
@@ -422,7 +510,9 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
   round-trip preserves the owner tag. With pi virtual models (routers), the
   `"virtualBinding": "physical"` policy keys items by the routed physical
   model instead of the router id, so a router selection does not silently
-  reset the harness.
+  reset the harness. Owned items can be carried across models explicitly with
+  `/harness adopt --from <provider/id> [--all]` (agent-filtered copy; see
+  [Model binding](#model-binding-per-model-isolation)).
 - **Bounded injection (on by default)**: the supplemental block is
   importance-ordered and capped per kind + by a total token budget, so a growing
   harness never balloons the system prompt. Tunable / opt-out via the `injection`

package/package.json

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

@@ -25,6 +25,12 @@
 //    sendUserMessage when the boundary cannot continue (event.context.
 //    canContinue false, e.g. after an error turn).
 //
+// Aborted/error turns are inert here: a turn_end whose BoundaryState.outcome
+// is "aborted" or "error" neither seeds nor advances the cadence window, so
+// "every N turns" counts completed turns of work and a refine never fires
+// over partial evidence. (Durable auto-export deliberately still exports on
+// such turns — committed entries must not be lost.)
+//
 // It stays visible: it notifies before firing, and the boundary draft (and the
 // gate decision) appear in the transcript. The decision logic is factored into
 // evaluateAutoRefine() so it is unit-testable without a live pi runtime.
@@ -34,29 +40,47 @@ import { DEFAULT_AUTO_EVERY_TURNS, type HarnessConfig, loadConfig } from "./conf
 import { runRefine, gatherEvidence, DEFAULT_LOOKBACK_TURNS } from "./refine.js";
 import { buildClassify, buildGateRequest, gateDecision } from "./classify.js";
 
-// turnIndex of the last auto-refine (or the seeded baseline). -1 = unseen.
-let lastTurn = -1;
+// 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;
 
 /** Test hook: reset internal counter. */
 export function resetAutoRefine(): void {
-  lastTurn = -1;
+  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";
 }
 
 /**
  * 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.
+ * completed turn seeds the baseline (no refine then); every completed turn
+ * after it advances the count, and each fired refine resets it (which also
+ * prevents the refine turn itself from immediately re-triggering).
+ * Aborted/error turns are inert: they neither seed nor advance the count —
+ * the cadence counts completed turns of work, never raw turn indices, so an
+ * aborted turn in between cannot shorten the window.
  */
-export function evaluateAutoRefine(config: HarnessConfig, turnIndex: number): 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 (lastTurn < 0) {
-    lastTurn = turnIndex;
+  if (completedTurns < 0) {
+    completedTurns = 0; // seed: the seed turn itself doesn't count
     return false;
   }
-  if (turnIndex - lastTurn >= every) {
-    lastTurn = turnIndex;
+  completedTurns += 1;
+  if (completedTurns >= every) {
+    completedTurns = 0;
     return true;
   }
   return false;
@@ -112,7 +136,7 @@ export function buildOmissionDrafts(projected: Iterable<ProjectedLike>): Omissio
 export function registerAutoRefine(pi: ExtensionAPI): void {
   pi.on("turn_end", async (event, ctx) => {
     const config = await loadConfig();
-    if (!evaluateAutoRefine(config, event.turnIndex)) return;
+    if (!evaluateAutoRefine(config, event.outcome)) return;
     const every = config.autoRefine?.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS;
 
     // Opt-in classifier gate: cheap yes/no before spending the refine.

package/src/config.ts

@@ -6,26 +6,31 @@
 //    current project's file) and turn_end layered auto-export whenever the
 //    live store changed since the last export. Off by default — importing is
 //    normally an explicit, reviewable /harness import.
-//  - durableScope: DEPRECATED (0.9.0). Items now carry their own scope
-//    (`/harness move <id> global|project`); durable I/O is layered on top of
-//    per-item scope and this key no longer switches anything. Still parsed so
-//    existing configs keep loading; will be removed in a future release.
-//  - remindRefine / autoRefine / outcomeImportance / injection / proposer:
-//    unchanged (see below).
+//  - remindRefine: the /refine activation nudge (issue #19), ON by default
+//    (notify-only, never mutates; `enabled: false` opts back
+//    out). autoRefine / outcomeImportance / injection / proposer: unchanged
+//    (see below).
 //
 // Robust by design: missing or malformed file → DEFAULT_CONFIG, never throws.
+// Unknown keys are ignored (e.g. the removed pre-0.9.0 `durableScope`).
 
-import { readFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { DEFAULT_DURABLE_PATH, PROJECT_DURABLE_DIR, type LayerFile, type ScopeInfo } from "./store.js";
 import { DEFAULT_INJECTION, normalizeInjection, type NormalizedInjection } from "./select.js";
 import { DEDUPE_THRESHOLD } from "./proposer.js";
 
-export const DEFAULT_EVERY_TURNS = 50;
+export const DEFAULT_EVERY_TURNS = 25;
 export const DEFAULT_AUTO_EVERY_TURNS = 100;
 /** Default per-reference importance bump for the opt-in outcome loop. */
 export const DEFAULT_REF_BUMP = 0.03;
+/** Default cadence (turns) for the auto-import awareness reminder. */
+export const DEFAULT_IMPORT_REMIND_TURNS = 25;
+/** Default escalation cadence for the /refine reminder: every Nth fired
+ *  reminder is the detailed guide instead of the one-line nudge. */
+export const DEFAULT_DETAIL_EVERY = 4;
 
 /** How the binding key treats virtual (router) models. "virtual" (default):
  * key = the selected model's own provider/id. "physical": when the selection
@@ -43,15 +48,27 @@ export interface NormalizedDedupe {
 }
 
 export interface HarnessConfig {
-  /** DEPRECATED (0.9.0): items carry their own scope now (see /harness move);
-   *  durable I/O is always layered. Parsed for compatibility, ignored. */
-  durableScope?: "global" | "project";
   /** Opt-in durable sync (issue #7): session_start layered auto-import +
    *  turn_end layered auto-export when the store changed. Default false. */
   autoImport?: boolean;
+  /** Awareness reminders for durable imports (only effective when `autoImport`
+   *  is on): the session-start import notifies WHAT arrived, and a bounded
+   *  cadence reminder re-surfaces those items so silently-imported instructions
+   *  never go unnoticed. `enabled` defaults true; `everyTurns` defaults 25. */
+  importRemind?: {
+    enabled?: boolean;
+    everyTurns?: number;
+  };
+  /** /refine cadence nudge (ON by default, issue #19 — activation nudge, notify-only):
+ *  every `everyTurns` completed turns a one-line reminder fires; every
+ *  `detailEvery`-th reminder escalates to a rotating educational guide
+ *  (see src/remind.ts). Never mutates state; `enabled: false` restores the
+ *  old silence. */
   remindRefine?: {
     enabled?: boolean;
     everyTurns?: number;
+    /** Every Nth fired reminder is the detailed guide (1 = every reminder). */
+    detailEvery?: number;
   };
   autoRefine?: {
     enabled?: boolean;
@@ -94,9 +111,9 @@ export interface HarnessConfig {
 }
 
 export const DEFAULT_CONFIG: HarnessConfig = {
-  durableScope: "global",
   autoImport: false,
-  remindRefine: { enabled: false, everyTurns: DEFAULT_EVERY_TURNS },
+  importRemind: { enabled: true, everyTurns: DEFAULT_IMPORT_REMIND_TURNS },
+  remindRefine: { enabled: true, everyTurns: DEFAULT_EVERY_TURNS, detailEvery: DEFAULT_DETAIL_EVERY },
   autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false, gate: false, omitStaleDrafts: true },
   classifier: { model: undefined },
   virtualBinding: "virtual",
@@ -119,11 +136,17 @@ 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",
     autoImport: over.autoImport === true,
+    importRemind: {
+      enabled: over.importRemind?.enabled !== false,
+      everyTurns: coerceMinTurns(over.importRemind?.everyTurns, DEFAULT_IMPORT_REMIND_TURNS),
+    },
     remindRefine: {
-      enabled: over.remindRefine?.enabled ?? false,
-      everyTurns: over.remindRefine?.everyTurns ?? DEFAULT_EVERY_TURNS,
+      // Default-on (issue #19): a notify-only nudge mutates nothing, so the
+      // activation lever is pulled unless explicitly declined.
+      enabled: over.remindRefine?.enabled !== false,
+      everyTurns: coerceMinTurns(over.remindRefine?.everyTurns, DEFAULT_EVERY_TURNS),
+      detailEvery: coerceMinTurns(over.remindRefine?.detailEvery, DEFAULT_DETAIL_EVERY),
     },
     autoRefine: {
       enabled: over.autoRefine?.enabled ?? false,
@@ -152,6 +175,14 @@ function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
   };
 }
 
+/** Coerce a user-provided turn count to a finite integer ≥ 1, else the
+ *  default. Cadence arithmetic divides/compares against it; 0 or a fraction
+ *  would fire every turn (spam) and NaN never fires. */
+function coerceMinTurns(raw: unknown, def: number): number {
+  if (typeof raw === "number" && Number.isFinite(raw) && Number.isInteger(raw) && raw >= 1) return raw;
+  return def;
+}
+
 /** Coerce a user-provided bump to a finite number, else the default. The bump
  *  is an ARITHMETIC operand (importance + bump), so a non-numeric value must not
  *  leak through: importance + "0.03" === "0.50.03" → NaN, which would then be
@@ -168,6 +199,120 @@ function coerceThreshold(raw: unknown): number {
   return typeof raw === "number" && Number.isFinite(raw) && raw > 0 && raw <= 1 ? raw : DEDUPE_THRESHOLD;
 }
 
+/** Result of a reviewed config write (see saveConfig). */
+export interface SaveConfigResult {
+  /** The file that was written (== `path`). */
+  written: string;
+  /** Backup of the previous file (`harness.json.bak-<timestamp>`), when one existed. */
+  backup: string | undefined;
+  /** The exact object serialized to disk (existing raw file ∪ `next`). */
+  merged: Record<string, unknown>;
+  /** Effective config re-read through loadConfig — what pi will actually load. */
+  effective: HarnessConfig;
+}
+
+/** True for a non-array plain object (a deep-merge candidate). */
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Two-level deep merge (the config shape is two levels deep at most):
+ *  plain-object keys merge key-by-key so sibling settings survive; everything
+ *  else is replaced by `next`. Unknown existing keys ride along untouched. */
+export function deepMergeConfig(
+  existing: Record<string, unknown>,
+  next: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...existing };
+  for (const [k, v] of Object.entries(next)) {
+    const cur = out[k];
+    out[k] = isPlainObject(cur) && isPlainObject(v) ? { ...cur, ...v } : v;
+  }
+  return out;
+}
+
+/** Parse the raw file when it is a JSON object; undefined for missing,
+ *  malformed, or non-object content. Unknown keys are preserved verbatim
+ *  (the loader ignores them, a rewrite must not drop them). */
+export async function readConfigRaw(path: string): Promise<Record<string, unknown> | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    return isPlainObject(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Filesystem-safe, sortable backup timestamp (colons/dots → dashes). */
+function backupStamp(d = new Date()): string {
+  return d.toISOString().replace(/[:.]/g, "-");
+}
+
+/** rename with a bounded retry. On Windows, replacing a file that was itself
+ *  JUST replaced (a concurrent save racing to the same target) can transiently
+ *  fail with EPERM/EACCES/ENOTEMPTY while the previous replacement settles
+ *  into the delete-pending state. A short backoff clears it; every other
+ *  error (and errors that persist) propagates. */
+async function renameRetry(tmp: string, path: string, tries = 3): Promise<void> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await rename(tmp, path);
+      return;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (attempt < tries && (code === "EPERM" || code === "EACCES" || code === "ENOTEMPTY")) {
+        await new Promise((resolve) => setTimeout(resolve, 10 * (attempt + 1)));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/** The ONE reviewed write path for harness.json (used by /harness setup):
+ *  merge `next` over the existing RAW file (two levels deep, unknown keys
+ *  preserved), back the previous file up as `harness.json.bak-<timestamp>`,
+ *  atomically write (same-dir tmp + rename), then drop the config cache and
+ *  reload — the returned `effective` round-trips through the same
+ *  loader/coercion path pi uses, so what the wizard displayed is what pi
+ *  reads. Throws BEFORE any write when the backup cannot be made: the
+ *  previous file is never destroyed without one. */
+export async function saveConfig(
+  next: Partial<HarnessConfig> | Record<string, unknown>,
+  path: string = CONFIG_PATH,
+): Promise<SaveConfigResult> {
+  const existing = await readConfigRaw(path);
+  const merged = deepMergeConfig(existing ?? {}, next as Record<string, unknown>);
+  const json = `${JSON.stringify(merged, null, 2)}\n`;
+  // Back up by FILE EXISTENCE, not parse success: a malformed file must be
+  // preserved too (it may hold recoverable content; the rewrite replaces it).
+  let backup: string | undefined;
+  try {
+    await stat(path);
+    backup = `${path}.bak-${backupStamp()}`;
+    await copyFile(path, backup);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err; // backup failure → abort, no write
+  }
+  await mkdir(dirname(path), { recursive: true }); // first run: ~/.pi/agent may not exist yet
+  // Unique + exclusive temp name: two concurrent saveConfig calls (two pi
+  // sessions, or two wizards) must never share a tmp file — the loser would
+  // truncate the winner's content or rename it away mid-write. "wx" fails
+  // loudly on collision instead of corrupting (a UUID collision is already
+  // theoretical; this makes it impossible).
+  const tmp = `${path}.tmp-${randomUUID().slice(0, 8)}`;
+  try {
+    await writeFile(tmp, json, { encoding: "utf8", flag: "wx" });
+    await renameRetry(tmp, path); // atomic on POSIX; REPLACE_EXISTING on Windows
+  } catch (err) {
+    await rm(tmp, { force: true }).catch(() => {}); // best-effort tmp cleanup
+    throw err;
+  }
+  resetConfigCache();
+  const effective = await loadConfig(path);
+  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). */
 export async function loadConfig(path: string = CONFIG_PATH): Promise<HarnessConfig> {
@@ -186,15 +331,6 @@ export function resetConfigCache(): void {
   cached = undefined;
 }
 
-/**
- * @deprecated Durable I/O is layered on per-item scope (0.9.0); this key no
- * longer switches the durable path. Kept so old configs keep loading.
- */
-export function resolveDurablePath(config: HarnessConfig, cwd?: string): string {
-  if (config.durableScope !== "project") return DEFAULT_DURABLE_PATH;
-  return projectDurablePath(cwd);
-}
-
 /** Path of a project's durable layer file: <projectDir>/<slug>.md. */
 export function projectDurablePath(cwd?: string): string {
   return join(PROJECT_DURABLE_DIR, `${projectSlug(cwd)}.md`);

package/src/corpus.ts

@@ -135,38 +135,58 @@ function durableLayer(i: HarnessItem): string {
 
 // ---- lifecycle ---------------------------------------------------------------
 
-/** Classify one snapshot → next-snapshot transition into lifecycle records.
+/** One classified lifecycle transition, with the item it happened to.
+ *  Exported so the status report (src/status.ts) can aggregate events with
+ *  owner-model attribution; `buildCorpus` maps these onto contract records. */
+export interface LifecycleTransition {
+  event: LifecycleEvent;
+  /** Post-transition item (for removals: the removed item as last seen). */
+  item: HarnessItem;
+}
+
+/** Classify one snapshot → next-snapshot transition into lifecycle events.
  *  `citeBump` is the CONFIGURED outcome-loop bump (see CorpusOptions). */
-function diffSnapshots(
+export function classifyTransition(
   prev: HarnessState,
   next: HarnessState,
   citeBump: number,
-  out: LifecycleRecord[],
-): void {
+): LifecycleTransition[] {
+  const out: LifecycleTransition[] = [];
   const prevById = new Map(prev.items.map((i) => [i.id, i]));
   const nextById = new Map(next.items.map((i) => [i.id, i]));
 
   for (const item of next.items) {
     const before = prevById.get(item.id);
     if (!before) {
-      out.push(lifecycle(item, "created", item.importance));
+      out.push({ event: "created", item });
       continue;
     }
     const d = item.importance - before.importance;
     if (Math.abs(d) < EPSILON) continue;
     // keep/drop FIRST: a configured citation bump of exactly ±0.1 collides and
     // keep/drop win (documented in CorpusOptions).
-    if (Math.abs(d - KEEP_DROP_BUMP) <= BUMP_TOL) out.push(lifecycle(item, "kept", item.importance));
-    else if (Math.abs(d + KEEP_DROP_BUMP) <= BUMP_TOL)
-      out.push(lifecycle(item, "dropped", item.importance));
+    if (Math.abs(d - KEEP_DROP_BUMP) <= BUMP_TOL) out.push({ event: "kept", item });
+    else if (Math.abs(d + KEEP_DROP_BUMP) <= BUMP_TOL) out.push({ event: "dropped", item });
     else if (citeBump > 0 && Math.abs(d - citeBump) <= BUMP_TOL)
-      out.push(lifecycle(item, "cited", item.importance));
+      out.push({ event: "cited", item });
     // else: explicit harness_mutate importance set — not a lifecycle signal.
   }
   for (const item of prev.items) {
     if (nextById.has(item.id)) continue;
     const event = item.importance < IMPORTANCE_FLOOR ? "pruned" : "deleted";
-    out.push(lifecycle(item, event, item.importance));
+    out.push({ event, item });
+  }
+  return out;
+}
+
+function diffSnapshots(
+  prev: HarnessState,
+  next: HarnessState,
+  citeBump: number,
+  out: LifecycleRecord[],
+): void {
+  for (const t of classifyTransition(prev, next, citeBump)) {
+    out.push(lifecycle(t.item, t.event, t.item.importance));
   }
 }