pi-continual-harness 0.8.1 → 0.10.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)).
 
@@ -51,33 +53,50 @@ Or drop `src/index.ts` into `~/.pi/agent/extensions/`.
 ```
 /refine              # review last 25 turns, propose deltas
 /refine 50           # review last 50 turns
-/refine 25 --commit  # also export durable state to ~/.pi/agent/harness-state.md
+/refine 25 --commit  # also export durable state (global + project layers)
 /refine --proposer dedupe  # run the rule-based dedupe proposer instead of steering
+/refine --proposer dedupe --threshold 0.75  # dedupe with a one-shot threshold
 ```
 
 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)
 ```
 
-Subcommands, flags, `--kind`/`--model` values, and `keep`/`drop` item ids all
-autocomplete in the TUI as you type after `/harness `.
-
-`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:
@@ -88,6 +107,9 @@ The model-facing tools:
 - `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)).
+  `create`/`update` deltas also accept `scope: "global" | "project"` (the
+  project slug is stamped server-side from the session cwd — used by
+  `/harness split`; normally managed via `/harness move`).
 
 Active items are injected into the system prompt each turn as a structured
 block, appended to (never replacing) the base prompt.
@@ -117,8 +139,9 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
 
 ```json
 {
-  "durableScope": "global",
+  "autoImport": false,
   "proposer": "steering",
+  "dedupe": { "threshold": 0.6, "merge": true },
   "injection": { "enabled": true, "maxTokens": 1500, "maxPerKind": 10, "charsPerToken": 4 },
   "remindRefine": { "enabled": false, "everyTurns": 50 },
   "autoRefine": { "enabled": false, "everyTurns": 100, "commit": false },
@@ -126,10 +149,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
@@ -137,7 +165,19 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   restore the legacy "inject all items, in store order" behaviour.
 - **`proposer`** — which delta proposer `/refine` and auto-refine use. Defaults
   to `steering` (the agent reasons via a steering message). `dedupe` applies a
-  rule-based dedupe directly. See [Proposers](#proposers).
+  rule-based merge directly. See [Proposers](#proposers).
+- **`dedupe`** — the rule-based dedupe proposer's policy. `threshold` (default
+  `0.6`, valid `(0,1]`) is the token-overlap level at which two items sharing
+  the key fields (kind, owner model, durable layer) count as duplicates;
+  `merge` (default `true`) **merges** each duplicate into its keeper — the
+  keeper keeps its content verbatim, its `evidence` becomes the line-wise union
+  of both, applied as one audited `update` + `delete` pair — while `false`
+  restores the pre-0.10 delete-only behavior. `/refine --proposer dedupe
+  --threshold 0.75` overrides the threshold for one run. A fourth key,
+  `similarity`, is API-only (functions cannot come from `harness.json`):
+  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.
@@ -157,6 +197,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.
@@ -205,9 +252,9 @@ How the binding is set and respected:
   `model: provider/id`; `/harness import` restores it. An item whose tag
   pi-reflect stripped becomes an orphan and is adopted by the active model.
 
-Manual commands (`export`, `import`, `keep`, `drop`, `prune`, `push-mem`,
-`status`) operate on the **whole store** by design — they are explicit human
-actions with full control. Isolation is enforced only where pollution would
+Manual commands (`export`, `import`, `move`, `split`, `keep`, `drop`, `prune`,
+`push-mem`, `status`) operate on the **whole store** by design — they are
+explicit human actions with full control. Isolation is enforced only where pollution would
 leak automatically: injection, listing, create-stamping, and the outcome loop.
 In particular, `/harness push-mem` pushes *every* model's active items into
 pi-mem by default (which can yield near-duplicate memories across models); pass
@@ -264,7 +311,16 @@ deltas directly). The propose stage is pluggable via a registry
 | Name | What it does |
 |---|---|
 | `steering` (default) | Delegates reasoning to the agent via a steering message — reuses the agent loop, model-agnostic, fully visible. |
-| `dedupe` | Rule-based: drops near-duplicate active items (token-overlap ≥ 0.6), keeping the higher-importance one. No model call. |
+| `dedupe` | Rule-based: **merges** near-duplicate active items (token-overlap ≥ the configured threshold, same kind / owner model / durable layer) into the higher-importance keeper — one evidence-union update per keeper, then deletes the duplicates. `"dedupe": { "merge": false }` restores delete-only. No model call. |
+
+The dedupe planner's `similarity` seam (`DedupeOptions.similarity`, re-exported
+from the package entry) is how a companion package upgrades the comparison —
+e.g. embedding cosine similarity, or a local decision engine such as pi-jev
+(a local-only project for now). A comparator may return
+`{ score, abstain }` instead of a plain number: **an abstaining pair is
+treated as not duplicates** — both items are kept — so an engine with
+conformal uncertainty guarantees can safely decline to merge. Plain numeric
+returns keep working (the default remains token Jaccard).
 
 Select a proposer per run with `/refine --proposer <name>`, or set the default
 for auto-refine via `proposer` in the [config](#configuration). Both paths are
@@ -313,19 +369,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.1",
+  "version": "0.10.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,28 +1,48 @@
 // 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";
+import { DEDUPE_THRESHOLD } from "./proposer.js";
 
 export const DEFAULT_EVERY_TURNS = 50;
 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;
 
+/** Resolved dedupe policy (merge-capable, 0.10.0). Populated by loadConfig. */
+export interface NormalizedDedupe {
+  /** Token-overlap threshold in (0,1]; pairs at/above it merge. Default 0.6. */
+  threshold: number;
+  /** Merge duplicates into the keeper (evidence union) instead of delete-only.
+   *  Default true; `false` restores the pre-0.10 delete-only behavior. */
+  merge: boolean;
+}
+
 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;
@@ -43,14 +63,22 @@ export interface HarnessConfig {
   /** Injection selection policy (on by default). Resolved by loadConfig, so the
    *  value here is always fully-populated. See src/select.ts. */
   injection?: NormalizedInjection;
+  /** Dedupe proposer policy (merge-capable). Resolved by loadConfig, so the
+   *  value here is always fully-populated. See src/proposer.ts. */
+  dedupe?: NormalizedDedupe;
 }
 
 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",
   outcomeImportance: { enabled: false, bump: DEFAULT_REF_BUMP },
+  // Dedupe (merge-capable): merge ON at the historical 0.6 threshold — a
+  // near-duplicate merges into its keeper (evidence unioned) instead of being
+  // deleted cold. `merge: false` restores delete-only.
+  dedupe: { threshold: DEDUPE_THRESHOLD, merge: true },
   // ON by default: importance-ordered, maxPerKind 10, maxTokens 1500. A no-op
   // for small stores; protective as the harness accumulates. Opt out with
   // `injection.enabled: false`. See src/select.ts.
@@ -65,6 +93,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,
@@ -83,6 +112,10 @@ function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
     // malformed `injection` object degrades to the shipped defaults rather than
     // corrupting the block sizing arithmetic.
     injection: normalizeInjection(over.injection as Partial<{ enabled: boolean; maxTokens: number; maxPerKind: number; charsPerToken: number }> | undefined),
+    dedupe: {
+      threshold: coerceThreshold(over.dedupe?.threshold),
+      merge: over.dedupe?.merge !== false,
+    },
   };
 }
 
@@ -94,6 +127,14 @@ function coerceBump(raw: unknown): number {
   return typeof raw === "number" && Number.isFinite(raw) ? raw : DEFAULT_REF_BUMP;
 }
 
+/** Coerce a user-provided dedupe threshold to a finite number in (0,1], else
+ *  the default. The threshold is a COMPARISON operand (similarity >= threshold);
+ *  out-of-range or non-numeric values must degrade to the default rather than
+ *  silently matching everything (0/-1) or nothing (>1). */
+function coerceThreshold(raw: unknown): number {
+  return typeof raw === "number" && Number.isFinite(raw) && raw > 0 && raw <= 1 ? raw : DEDUPE_THRESHOLD;
+}
+
 /** 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> {
@@ -113,13 +154,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");
+    }
+  });
+}