pi-continual-harness 0.12.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`
@@ -440,7 +530,9 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 - **Boundary delivery for auto-refine**: the steering prompt is persisted as a
   structural entry with `{ entries, continue: true }` at `turn_end` (no
   synthetic user message, no follow-up-scheduling side effects); manual
-  `/refine` still steers via a user message.
+  `/refine` still steers via a user message. Each new boundary also omits
+  prior auto-refine request drafts from future provider context (pi ≥ 0.87
+  context edits; `autoRefine.omitStaleDrafts: false` to keep them).
 
 Open extension points (see `docs/ROADMAP.md`):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.12.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;
@@ -75,11 +99,44 @@ export function buildRefineDraft(steeringMessage: string): {
   return { type: "custom_message", customType: AUTO_REFINE_ENTRY, content: steeringMessage, display: true };
 }
 
+/** Structural slice of pi's ProjectedSessionEntry (sourceEntry + messages). */
+export interface ProjectedLike {
+  sourceEntry?: { type?: string; customType?: string; id?: string };
+  messages?: unknown[];
+}
+
+/** A context_edit boundary draft (pi ≥ 0.87): omit one entry from future
+ *  provider context — raw history, usage, and UI history stay untouched. */
+export interface OmissionDraft {
+  type: "context_edit";
+  targetId: string;
+  replacement: null;
+}
+
+/**
+ * Context-edit drafts omitting every LIVE prior auto-refine request from
+ * future provider context (pi ≥ 0.87 ContextEditEntry). Invariant: at most
+ * ONE auto-refine request is ever model-visible — the newest. Already-omitted
+ * drafts surface in the projection with empty `messages` and are skipped, so
+ * the operation is idempotent and never stacks redundant edits. Raw history
+ * (and the HTML export) keeps every draft: /tree rollback still applies.
+ */
+export function buildOmissionDrafts(projected: Iterable<ProjectedLike>): OmissionDraft[] {
+  const drafts: OmissionDraft[] = [];
+  for (const p of projected) {
+    const src = p.sourceEntry;
+    if (src?.type !== "custom_message" || src.customType !== AUTO_REFINE_ENTRY) continue;
+    if ((p.messages?.length ?? 0) === 0) continue; // already omitted → skip
+    if (typeof src.id === "string") drafts.push({ type: "context_edit", targetId: src.id, replacement: null });
+  }
+  return drafts;
+}
+
 /** 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;
+    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.
@@ -118,7 +175,19 @@ export function registerAutoRefine(pi: ExtensionAPI): void {
           pi.sendUserMessage(result.steeringMessage);
           return;
         }
-        return { entries: [...event.entries, buildRefineDraft(result.steeringMessage)], continue: true };
+        // Hygiene (pi ≥ 0.87 context edits): omit every LIVE prior auto-refine
+        // request from future provider context, so at most one draft (the new
+        // one) is ever model-visible. Already-omitted drafts are skipped by
+        // buildOmissionDrafts; raw history and /tree rollback are untouched.
+        // Kill-switch: autoRefine.omitStaleDrafts: false.
+        const omissions =
+          config.autoRefine?.omitStaleDrafts === false
+            ? []
+            : buildOmissionDrafts(event.context?.contextEntries ?? []);
+        return {
+          entries: [...event.entries, ...omissions, buildRefineDraft(result.steeringMessage)],
+          continue: true,
+        };
       }
     } catch (err) {
       ctx.ui.notify(`Auto-refine failed: ${(err as Error).message}`, "error");