pi-continual-harness 0.8.0 → 0.9.0

package/README.md

@@ -13,10 +13,12 @@ with:
   → behavioral-file refinement (the "deep" path).
 - **pi-mem / pi-memory** — durable memory storage.
 
-The durable markdown file (`~/.pi/agent/harness-state.md`) is the composition seam,
-and it is **two-way**: `/refine --commit` and `/harness export` write it;
-`/harness import` parses it back and merges into the live store (offline edits
-win on conflict), so refinements pi-reflect makes flow back online. `/harness push-mem`
+The durable markdown layers are the composition seam — the shared
+`~/.pi/agent/harness-state.md` plus per-project files under
+`~/.pi/agent/harness-state/<slug>.md` — and they are **two-way**:
+`/refine --commit` and `/harness export` write them; `/harness import` parses
+them back and merges into the live store (offline edits win on conflict), so
+refinements pi-reflect makes flow back online. `/harness push-mem`
 pushes active items into pi-mem's semantic store (see
 [Composing with pi-mem](#composing-with-pi-mem)).
 
@@ -58,23 +60,42 @@ Or drop `src/index.ts` into `~/.pi/agent/extensions/`.
 Durable I/O (round-trip with pi-reflect):
 
 ```
-/harness status                  # counts + durable file presence/mtime
-/harness export [path]           # write active items to a markdown file
-/harness import [--prune] [path] # parse it back and merge (offline edits win)
+/harness status                  # counts + durable layer presence/mtime
+/harness export [path]           # layered export (or full snapshot to a path)
+/harness import [--prune] [path] # layered import (or single file from a path)
 /harness prune [--decay <days>]  # drop items below the importance floor
 /harness keep <id>               # nudge importance up (+0.1)
 /harness drop <id>               # nudge importance down (−0.1)
+/harness move <id> global|project  # move an item between durable layers
+/harness split                   # steer the agent to classify every item's scope
 /harness push-mem [--all|--kind <kind>|--model <provider/id|active>]  # persist active items to pi-mem (save_memory)
 ```
 
-`import` reconciles the file into the live store: items whose id matches an
+Subcommands, flags, `--kind`/`--model` 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`
+(the shared `~/.pi/agent/harness-state.md`) or `project`
+(`~/.pi/agent/harness-state/<slug>.md`, slug derived from the session `cwd`).
+`/harness export` without a path partitions items by their scope into the
+layer files; `/harness import` without a path merges the global file always,
+plus the current project's file (the project layer wins id collisions;
+`--prune` drops only items absent from **every** layer). An explicit path keeps
+the classic single-file semantics. Move items between layers with
+`/harness move`, or classify the whole store at once with `/harness split`
+(the agent proposes scope-only `harness_mutate` updates — visible in the
+transcript, `/tree`-rollback-able).
+
+`import` reconciles the file(s) into the live store: items whose id matches an
 existing entry are updated (offline edits win on content/evidence/importance),
 new entries are created. By default nothing is deleted — `--prune` also drops
-active items whose id is no longer in the file (inactive items are always
-preserved). Point pi-reflect at the same file to refine it offline:
+active items whose id is no longer in the file(s) (inactive items are always
+preserved). Point pi-reflect at either layer to refine it offline:
 
 ```
 /reflect ~/.pi/agent/harness-state.md
+/reflect ~/.pi/agent/harness-state/<project-slug>.md
 ```
 
 The model-facing tools:
@@ -114,7 +135,7 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
 
 ```json
 {
-  "durableScope": "global",
+  "autoImport": false,
   "proposer": "steering",
   "injection": { "enabled": true, "maxTokens": 1500, "maxPerKind": 10, "charsPerToken": 4 },
   "remindRefine": { "enabled": false, "everyTurns": 50 },
@@ -123,10 +144,15 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
 }
 ```
 
-- **`durableScope`** — `"global"` (default) writes the durable markdown to
-  `~/.pi/agent/harness-state.md`; `"project"` writes to
-  `~/.pi/agent/harness-state/<slug>.md` (slug derived from `cwd`) so each
-  project keeps separate state for pi-reflect.
+- **`autoImport`** — opt-in **durable sync** (off by default). `true` bundles
+  both directions: on `session_start` the durable layers are imported
+  automatically (global file always + the current project's file, with the same
+  loss-free merge as `/harness import` — an import that changes nothing stays
+  silent), and on `turn_end` the layers are re-exported whenever the live store
+  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).
 - **`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
@@ -154,6 +180,13 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   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`).
+
 ## How it works
 
 1. `/refine` gathers recent trajectory evidence from the current session branch.
@@ -310,19 +343,26 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 
 ## Status
 
-0.8.x. Implemented:
+0.9.x. Implemented:
 
 - Unified harness-state store with branch-local snapshots (`/tree` rollback).
 - Online `/refine` + `harness_mutate` / `harness_list` tools.
-- Two-way durable round-trip with pi-reflect (`/harness import|export|status`).
+- Two-way durable round-trip with pi-reflect (`/harness import|export|status`),
+  **layered on per-item scope**: every item is `global` or `project`
+  (`/harness move`, `/harness split`), and `/harness export|import` operate on
+  both layers.
 - Importance hygiene: `/harness prune [--decay <days>]` and `/harness keep|drop
   <id>`.
 - **pi-mem composition**: `/harness push-mem [--all|--kind|--model]` steers the agent
   to persist active items into pi-mem (soft-fail; no dependency).
-- Optional config (`~/.pi/agent/harness.json`): project-local durable scope, an
+- **Opt-in durable sync** (`"autoImport": true`): session_start layered
+  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 two opt-in autonomous
-  paths (both off by default).
+  `turn_end` outcome-importance loop — the package's opt-in autonomous
+  paths (all 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.8.0",
+  "version": "0.9.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/config.ts

@@ -1,19 +1,24 @@
 // User configuration for continual-harness: ~/.pi/agent/harness.json
 //
-// Phase 2 introduces this file (optional; missing → defaults) to configure:
-//  - durableScope: where the durable markdown lives. "global" (default,
-//    ~/.pi/agent/harness-state.md — backward compatible) or "project"
-//    (~/.pi/agent/harness-state/<slug>.md, slug derived from cwd) so different
-//    projects keep separate harness state for pi-reflect.
-//  - remindRefine: opt-in turn_end nudge to run /refine (Phase 2 = reminder
-//    only; Phase 3 adds opt-in auto-refine).
+// This file (optional; missing → defaults) configures:
+//  - autoImport: opt-in durable sync (issue #7). `true` bundles BOTH
+//    directions: session_start layered auto-import (global file always + the
+//    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).
 //
 // Robust by design: missing or malformed file → DEFAULT_CONFIG, never throws.
 
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { DEFAULT_DURABLE_PATH } from "./store.js";
+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";
 
 export const DEFAULT_EVERY_TURNS = 50;
@@ -22,7 +27,12 @@ export const DEFAULT_AUTO_EVERY_TURNS = 100;
 export const DEFAULT_REF_BUMP = 0.03;
 
 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;
   remindRefine?: {
     enabled?: boolean;
     everyTurns?: number;
@@ -47,6 +57,7 @@ export interface HarnessConfig {
 
 export const DEFAULT_CONFIG: HarnessConfig = {
   durableScope: "global",
+  autoImport: false,
   remindRefine: { enabled: false, everyTurns: DEFAULT_EVERY_TURNS },
   autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false },
   proposer: "steering",
@@ -65,6 +76,7 @@ let cached: HarnessConfig | undefined;
 function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
   return {
     durableScope: over.durableScope === "project" ? "project" : "global",
+    autoImport: over.autoImport === true,
     remindRefine: {
       enabled: over.remindRefine?.enabled ?? false,
       everyTurns: over.remindRefine?.everyTurns ?? DEFAULT_EVERY_TURNS,
@@ -113,13 +125,41 @@ export function resetConfigCache(): void {
 }
 
 /**
- * Resolve the durable markdown path for the configured scope.
- *  - global  → ~/.pi/agent/harness-state.md (the default, unchanged)
- *  - project → ~/.pi/agent/harness-state/<slug>.md (slug derived from cwd)
+ * @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 join(homedir(), ".pi", "agent", "harness-state", `${projectSlug(cwd)}.md`);
+  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`);
+}
+
+/** The two layers a layered import reads for a session in `cwd`: global first
+ *  (so the project layer wins id collisions), the project layer only when its
+ *  slug matches the session cwd. Scope defaults for untagged items ride along
+ *  (a layer file's items belong to that layer). */
+export function layerFilesFor(cwd?: string): LayerFile[] {
+  return [
+    { path: DEFAULT_DURABLE_PATH, defaultScope: { scope: "global" } },
+    { path: projectDurablePath(cwd), defaultScope: { scope: "project", project: projectSlug(cwd) } },
+  ];
+}
+
+/** Derive the layer scope a file at `path` represents — used when a user
+ *  imports a file by explicit path: the global file → global; anything under
+ *  the project dir → project + slug from the filename stem; other paths →
+ *  global. Pure path-layout knowledge. */
+export function defaultScopeForPath(path: string): ScopeInfo {
+  if (path === DEFAULT_DURABLE_PATH) return { scope: "global" };
+  if (dirname(path) === PROJECT_DURABLE_DIR) {
+    const stem = basename(path, ".md");
+    if (stem) return { scope: "project", project: stem };
+  }
+  return { scope: "global" };
 }
 
 /** Stable, filesystem-safe slug from a directory path. Falls back to "default". */

package/src/durable.ts

@@ -0,0 +1,88 @@
+// Layered durable sync (issue #7), opt-in via harness.json { "autoImport": true }.
+//
+// One flag bundles BOTH directions so the durable seam never lags the live
+// store and /refine output survives into NEW sessions without manual
+// export/import ceremony:
+//
+//   session_start → syncDurableOnStart(): layered auto-import with the same
+//     loss-free merge semantics as /harness import — global file always, the
+//     current project's file when its slug matches the session cwd (global
+//     first, so the project layer wins id collisions). Idempotent: an import
+//     that changes nothing persists nothing and stays quiet.
+//
+//   turn_end → registerAutoExport(): layered export when the store version
+//     changed since the last export (bounded: the layer files are small).
+//     Materializes the session-restored store on the first turn of a session,
+//     so a missing/stale durable file self-heals.
+//
+// Both paths are visible (one notify line) and use the same persisted
+// harness-state entries as every other mutation (/tree rollback covers them).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_DURABLE_PATH, PROJECT_DURABLE_DIR } from "./store.js";
+import { exportDurableLayers, getVersion, importDurableLayers } from "./store.js";
+import type { LayerFile, LayerPaths } from "./store.js";
+import { layerFilesFor, loadConfig, projectSlug } from "./config.js";
+
+/** Real (homedir-based) layer paths. Tests inject their own. */
+function layerPaths(): LayerPaths {
+  return { globalPath: DEFAULT_DURABLE_PATH, projectDir: PROJECT_DURABLE_DIR };
+}
+
+// Version at the last auto-export. -1 = never exported this session.
+let lastExportedVersion = -1;
+
+/** Test hook / session reset: next turn_end re-exports once (materialize). */
+export function resetDurableSync(): void {
+  lastExportedVersion = -1;
+}
+
+/**
+ * session_start half of the durable sync: layered import (opt-in). `files`
+ * defaults to the real layers for ctx.cwd; tests inject temp paths.
+ */
+export async function syncDurableOnStart(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  files?: LayerFile[],
+): Promise<void> {
+  const config = await loadConfig();
+  if (!config.autoImport) return;
+  const layers = files ?? layerFilesFor(ctx.cwd);
+  const res = await importDurableLayers(layers, {}, (snapshot, ver) => {
+    pi.appendEntry("harness-state", { state: snapshot, version: ver });
+  });
+  if (res.missingFile) return; // nothing durable yet — stay quiet
+  const changed = res.created + res.updated + res.pruned;
+  if (changed === 0) return; // in sync — no noise
+  const bits = [`${res.created} created`, `${res.updated} updated`];
+  if (res.pruned > 0) bits.push(`${res.pruned} pruned`);
+  ctx.ui.notify(`Continual Harness: durable sync imported ${res.imported} item(s) (${bits.join(", ")}).`, "info");
+}
+
+/**
+ * turn_end half of the durable sync: layered export when the live store
+ * changed since the last export (opt-in, bundled with autoImport). `paths`
+ * defaults to the real layer dirs; tests inject temp dirs.
+ */
+export function registerAutoExport(pi: ExtensionAPI, paths?: LayerPaths): void {
+  pi.on("turn_end", async (_event, ctx) => {
+    const config = await loadConfig();
+    if (!config.autoImport) return;
+    if (getVersion() === lastExportedVersion) return;
+    try {
+      const written = await exportDurableLayers(
+        paths ?? layerPaths(),
+        projectSlug(ctx.cwd),
+      );
+      lastExportedVersion = getVersion();
+      ctx.ui.notify(
+        `Continual Harness: durable state exported (${written.length} file(s)).`,
+        "info",
+      );
+    } catch (err) {
+      // Soft-fail but leave lastExportedVersion stale → retried next turn.
+      ctx.ui.notify(`Durable auto-export failed: ${(err as Error).message}`, "warning");
+    }
+  });
+}