pi-continual-harness 0.8.1 → 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,26 +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)
 ```
 
-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:
@@ -117,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 },
@@ -126,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
@@ -157,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.
@@ -313,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.1",
+  "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");
+    }
+  });
+}

package/src/harness.ts

@@ -1,34 +1,51 @@
 // /harness — durable I/O. The two-way round-trip seam with pi-reflect.
 //
-//   /harness status [path]               counts + durable file presence/mtime
-//   /harness export [path]               write active items to a markdown file
-//   /harness import [--prune] [path]     parse it back and merge (durable wins)
+//   /harness status [path]               counts + durable layer presence/mtime
+//   /harness export [path]               layered export (or full snapshot to path)
+//   /harness import [--prune] [path]     layered import (or single file from path)
+//   /harness move <id> <global|project>  move an item between durable layers
+//   /harness split                       steer the agent to classify scopes
 //
 // The command registers getArgumentCompletions so the TUI offers a filtered
-// menu of subcommands (and, one level deeper, flags / item ids / kinds) as
+// menu of subcommands (and, one level deeper, flags / item ids / values) as
 // you type — see completions() below. The handler itself stays parsing-only.
 //
-// export writes the active items to ~/.pi/agent/harness-state.md (best-effort);
-// import parses that file and merges into the live store. Because pi-reflect
-// edits markdown files and git-commits, pointing it at the same file closes the
-// loop: offline refinement flows back into the online store.
+// Durable I/O is LAYERED on per-item scope (issue #7): every item belongs to
+// the global layer (~/.pi/agent/harness-state.md) or a project layer
+// (~/.pi/agent/harness-state/<slug>.md). Without an explicit path, export
+// writes each layer from the items' own scope and import merges global first,
+// then the current project's file (project wins id collisions; --prune drops
+// only items absent from EVERY layer). An explicit path keeps the classic
+// single-file semantics — untagged items default to the layer the path
+// represents (see defaultScopeForPath).
 //
-// Manual only (no session_start auto-import): importing is an explicit,
-// reviewable action, matching the package's "no autonomous mutation" stance.
+// Importing stays a manual, reviewable action by default; opt into the
+// session_start auto-import + turn_end auto-export bundle with
+// harness.json { "autoImport": true } (see durable.ts).
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { stat } from "node:fs/promises";
 import {
+  applyDeltas,
   bumpImportance,
   decayAndPrune,
+  DEFAULT_DURABLE_PATH,
   exportDurable,
+  exportDurableLayers,
   getState,
+  importDurableLayers,
   modelKey,
+  PROJECT_DURABLE_DIR,
   reconstructFromDurable,
 } from "./store.js";
-import { loadConfig, resolveDurablePath } from "./config.js";
+import {
+  defaultScopeForPath,
+  layerFilesFor,
+  projectDurablePath,
+  projectSlug,
+} from "./config.js";
 import { KIND_LABEL } from "./types.js";
-import type { ComponentKind, HarnessItem } from "./types.js";
+import type { ComponentKind, Delta, HarnessItem } from "./types.js";
 
 /** One row of the /harness subcommand menu (label = name, value = name). */
 interface CompletionEntry {
@@ -37,12 +54,14 @@ interface CompletionEntry {
 }
 
 const SUBCOMMANDS: CompletionEntry[] = [
-  { name: "import", description: "Import durable state (--prune to prune stale items)" },
-  { name: "export", description: "Export active items to durable file" },
-  { name: "status", description: "Show harness status (active/total, per-kind counts, durable file)" },
+  { name: "import", description: "Import durable state, layered (--prune to prune stale items)" },
+  { name: "export", description: "Export active items to durable layers (or one file with a path)" },
+  { name: "status", description: "Show harness status (active/total, per-kind counts, durable layers)" },
   { name: "prune", description: "Decay & prune inactive items (--decay <days>)" },
   { name: "keep", description: "Bump item importance (+0.1)" },
   { name: "drop", description: "Lower item importance (−0.1)" },
+  { name: "move", description: "Move an item between durable scopes (global | project)" },
+  { name: "split", description: "Steer the agent to classify every item global vs project" },
   { name: "push-mem", description: "Persist active items to pi-mem (--all, --kind, --model)" },
 ];
 
@@ -128,10 +147,25 @@ function completions(argumentPrefix: string) {
     return items.length > 0 ? items : null;
   }
 
-  // Positional id completion for keep/drop: the one argument they take.
-  if (sub === "keep" || sub === "drop") {
-    const idCommitted = before.slice(1).some((t) => !t.startsWith("--"));
-    if (idCommitted) return null; // id already chosen; nothing left to complete
+  // Positional id completion for keep/drop/move: the first argument they take.
+  if (sub === "keep" || sub === "drop" || sub === "move") {
+    const positionals = before.slice(1).filter((t) => !t.startsWith("--"));
+    // move takes a second positional: the target scope.
+    if (sub === "move") {
+      if (positionals.length >= 2) return null; // id + scope chosen; done
+      if (positionals.length === 1) {
+        return filterValues(
+          [
+            { value: "global", description: "The shared durable file (~/.pi/agent/harness-state.md)" },
+            { value: "project", description: "This project's durable file (harness-state/<slug>.md)" },
+          ],
+          last,
+          before,
+        );
+      }
+    } else if (positionals.length > 0) {
+      return null; // id already chosen; nothing left to complete
+    }
     const items = getState()
       .items.filter((i) => i.active && i.id.startsWith(last))
       .map((i: HarnessItem) => ({
@@ -193,12 +227,18 @@ export function registerHarness(pi: ExtensionAPI): void {
         case "drop":
           await handleBump(pi, ctx, rest, -0.1, "drop");
           return;
+        case "move":
+          await handleMove(pi, ctx, rest);
+          return;
+        case "split":
+          await handleSplit(pi, ctx);
+          return;
         case "push-mem":
           await handlePushMem(pi, ctx, rest);
           return;
         case "status":
         default:
-          await handleStatus(ctx, rest);
+          await handleStatus(ctx);
           return;
       }
     },
@@ -206,11 +246,9 @@ export function registerHarness(pi: ExtensionAPI): void {
   });
 }
 
-async function resolvePath(rest: string[], ctx: ExtensionCommandContext): Promise<string> {
-  const explicit = rest.find((a) => !a.startsWith("-"));
-  if (explicit) return explicit;
-  const config = await loadConfig();
-  return resolveDurablePath(config, ctx.cwd);
+/** Explicit path argument, if any (flags like --prune are skipped). */
+function explicitPath(rest: string[]): string | undefined {
+  return rest.find((a) => !a.startsWith("-"));
 }
 
 async function handleImport(
@@ -219,22 +257,38 @@ async function handleImport(
   rest: string[],
 ): Promise<void> {
   const prune = rest.includes("--prune");
-  const path = await resolvePath(rest, ctx);
+  const explicit = explicitPath(rest);
   ctx.ui.setStatus("harness", `Importing durable state${prune ? " (prune)" : ""}…`);
   try {
-    const res = await reconstructFromDurable(path, { prune }, (snapshot, ver) => {
-      pi.appendEntry("harness-state", { state: snapshot, version: ver });
-    });
-    if (res.missingFile) {
-      ctx.ui.notify(
-        `No durable file at ${path}. Run /refine --commit or /harness export first.`,
-        "warning",
-      );
-      return;
+    let res;
+    if (explicit) {
+      // Single-file semantics; untagged items adopt the layer the path
+      // represents (global file → global; project dir → that project).
+      const defaultScope = defaultScopeForPath(explicit);
+      res = await reconstructFromDurable(explicit, { prune }, (snapshot, ver) => {
+        pi.appendEntry("harness-state", { state: snapshot, version: ver });
+      }).then((r) => ({ ...r, path: explicit }));
+      if (res.missingFile) {
+        ctx.ui.notify(`No durable file at ${explicit}. Run /refine --commit or /harness export first.`, "warning");
+        return;
+      }
+    } else {
+      // Layered: global always + the current project's file, merged in one
+      // pass (project wins id collisions; --prune is union-scoped).
+      res = await importDurableLayers(layerFilesFor(ctx.cwd), { prune }, (snapshot, ver) => {
+        pi.appendEntry("harness-state", { state: snapshot, version: ver });
+      });
+      if (res.missingFile) {
+        ctx.ui.notify(
+          `No durable files at ${DEFAULT_DURABLE_PATH} (or ${projectDurablePath(ctx.cwd)}). Run /refine --commit or /harness export first.`,
+          "warning",
+        );
+        return;
+      }
     }
     const bits = [`${res.created} created`, `${res.updated} updated`];
     if (prune) bits.push(`${res.pruned} pruned`);
-    ctx.ui.notify(`Imported ${res.imported} item(s) from ${path} (${bits.join(", ")}).`, "info");
+    ctx.ui.notify(`Imported ${res.imported} item(s) (${bits.join(", ")}).`, "info");
   } catch (err) {
     ctx.ui.notify(`Harness import failed: ${(err as Error).message}`, "error");
   }
@@ -242,12 +296,24 @@ async function handleImport(
 }
 
 async function handleExport(ctx: ExtensionCommandContext, rest: string[]): Promise<void> {
-  const path = await resolvePath(rest, ctx);
   ctx.ui.setStatus("harness", "Exporting durable state…");
   try {
-    const written = await exportDurable(path);
-    const n = getState().items.filter((i) => i.active).length;
-    ctx.ui.notify(`Exported ${n} active item(s) to ${written}`, "info");
+    const explicit = explicitPath(rest);
+    if (explicit) {
+      // Full single-file snapshot (both scopes; project items tagged with a
+      // `scope:` sub-line so the file round-trips from anywhere).
+      const written = await exportDurable(explicit);
+      const n = getState().items.filter((i) => i.active).length;
+      ctx.ui.notify(`Exported ${n} active item(s) to ${written}`, "info");
+    } else {
+      // Layered: partition by each item's own scope.
+      const written = await exportDurableLayers(
+        { globalPath: DEFAULT_DURABLE_PATH, projectDir: PROJECT_DURABLE_DIR },
+        projectSlug(ctx.cwd),
+      );
+      const n = getState().items.filter((i) => i.active).length;
+      ctx.ui.notify(`Exported ${n} active item(s) to ${written.length} layer file(s): ${written.join(", ")}`, "info");
+    }
   } catch (err) {
     ctx.ui.notify(`Harness export failed: ${(err as Error).message}`, "error");
   }
@@ -307,6 +373,84 @@ async function handleBump(
   ctx.ui.notify(`${label}: "${preview}" → importance ${item.importance.toFixed(2)}`, "info");
 }
 
+/** /harness move <id> <global|project> — flip an item's durable layer.
+ *  Implemented as an audited update delta (no actor model: like keep/drop,
+ *  this is cross-model user maintenance). "project" is stamped with the
+ *  CURRENT session's slug so the item lands in this project's file. */
+async function handleMove(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  rest: string[],
+): Promise<void> {
+  const positionals = rest.filter((a) => a && !a.startsWith("-"));
+  const id = positionals[0];
+  const scope = positionals[1];
+  if (!id || (scope !== "global" && scope !== "project")) {
+    ctx.ui.notify(`/harness move requires: <id> <global|project> (ids via /harness status).`, "warning");
+    return;
+  }
+  const delta: Delta =
+    scope === "project"
+      ? { op: "update", id, scope, project: projectSlug(ctx.cwd) }
+      : { op: "update", id, scope };
+  try {
+    const [applied] = applyDeltas([delta], (snapshot, ver) => {
+      pi.appendEntry("harness-state", { state: snapshot, version: ver });
+    });
+    if (applied?.op === "update") {
+      const target =
+        scope === "project"
+          ? `project "${applied.after.project ?? ""}"`
+          : "global";
+      ctx.ui.notify(
+        `Moved ${id} → ${target}: "${preview(applied.after.content)}" (run /harness export to update the layer files).`,
+        "info",
+      );
+    }
+  } catch (err) {
+    ctx.ui.notify(`/harness move failed: ${(err as Error).message}`, "error");
+  }
+}
+
+/** Compose the /harness split steering message: the agent classifies every
+ *  active item global-vs-project and applies the classification as ONE
+ *  harness_mutate batch of scope-only update deltas — visible in the
+ *  transcript, audited, and /tree-rollback-able, exactly like push-mem. */
+function buildSplitPrompt(items: HarnessItem[], slug: string, cwd: string): string {
+  const lines = [
+    `/harness split — classify ${items.length} Continual Harness item(s) into durable scopes`,
+    "",
+    `Current project: ${cwd} (slug \"${slug}\").`,
+    "",
+    "For EACH item below, decide its durable scope:",
+    "- `project` — only useful when working in THIS project (deploy procedures, project architecture, local conventions, project-specific quirks).",
+    "- `global` — useful in every project (model quirks, owner preferences, general engineering practices).",
+    "",
+    "Then apply the whole classification in ONE harness_mutate call: one update delta per item, changing ONLY the scope field, e.g.",
+    '{ "op": "update", "id": "h_xxx", "scope": "project" }',
+    `(the "project" slug is stamped server-side to "${slug}"; content/evidence/importance stay untouched). Give every item an explicit decision — skip nothing. If an item is project-specific only in part, choose "project" and leave generalizing it for a later /refine.`,
+    "",
+    "Items:",
+  ];
+  items.forEach((i, n) => {
+    lines.push(
+      `${n + 1}. [${i.id}] (${i.kind}, importance ${i.importance.toFixed(2)}, ${i.scope === "project" ? `project \"${i.project ?? ""}\"` : "global"}) ${i.content}`,
+      `   evidence: ${i.evidence}`,
+    );
+  });
+  return lines.join("\n");
+}
+
+async function handleSplit(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  const items = getState().items.filter((i) => i.active);
+  if (items.length === 0) {
+    ctx.ui.notify("No active items to split (run /refine first).", "warning");
+    return;
+  }
+  pi.sendUserMessage(buildSplitPrompt(items, projectSlug(ctx.cwd), ctx.cwd));
+  ctx.ui.notify(`Steering agent to classify ${items.length} item(s) global vs project "${projectSlug(ctx.cwd)}".`, "info");
+}
+
 /** Compose a steering message that asks the agent to persist the given active
  *  items to long-term memory via a memory tool (pi-mem's save_memory).
  *  Tool-agnostic: if no memory tool is present the agent says so; we never
@@ -374,8 +518,7 @@ async function handlePushMem(
   ctx.ui.notify(`Steering agent to persist ${items.length} ${scope}${modelNote} to pi-mem.`, "info");
 }
 
-async function handleStatus(ctx: ExtensionCommandContext, rest: string[]): Promise<void> {
-  const path = await resolvePath(rest, ctx);
+async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
   const items = getState().items;
   const active = items.filter((i) => i.active);
   const key = modelKey(ctx.model);
@@ -385,19 +528,25 @@ async function handleStatus(ctx: ExtensionCommandContext, rest: string[]): Promi
   // the current model's share so the per-model picture is still visible.
   const counts: Record<ComponentKind, number> = { prompt: 0, memory: 0, skill: 0, subagent: 0 };
   for (const i of active) counts[i.kind] += 1;
-  let fileState: string;
-  try {
-    const st = await stat(path);
-    fileState = `${path} (modified ${st.mtime.toISOString()})`;
-  } catch {
-    fileState = `none at ${path}`;
+  const nProject = active.filter((i) => i.scope === "project").length;
+  async function layerState(path: string): Promise<string> {
+    try {
+      const st = await stat(path);
+      return `${path} (modified ${st.mtime.toISOString()})`;
+    } catch {
+      return `none at ${path}`;
+    }
   }
+  const durable =
+    ` Durable: global ${await layerState(DEFAULT_DURABLE_PATH)};` +
+    ` project ${await layerState(projectDurablePath(ctx.cwd))}.`;
   ctx.ui.setStatus("harness", undefined);
   ctx.ui.notify(
     `Harness: ${active.length} active / ${items.length} total — ` +
-      `prompt ${counts.prompt}, memory ${counts.memory}, skill ${counts.skill}, subagent ${counts.subagent}.` +
+      `prompt ${counts.prompt}, memory ${counts.memory}, skill ${counts.skill}, subagent ${counts.subagent}` +
+      ` — scope ${active.length - nProject} global / ${nProject} project.` +
       (key ? ` ${mine} active for [${key}] across ${models.length} model(s).` : "") +
-      ` Durable: ${fileState}.`,
+      durable,
     "info",
   );
 }

package/src/index.ts

@@ -14,7 +14,9 @@ import { registerTools } from "./tools.js";
 import { registerReminder, resetReminder } from "./remind.js";
 import { registerAutoRefine, resetAutoRefine } from "./auto-refine.js";
 import { registerOutcome, resetOutcome } from "./outcome.js";
-import { getState, reconstruct, setActiveModelKey, STATE_ENTRY } from "./store.js";
+import { registerAutoExport, resetDurableSync, syncDurableOnStart } from "./durable.js";
+import { getState, reconstruct, setActiveModelKey, setSessionProject, STATE_ENTRY } from "./store.js";
+import { projectSlug } from "./config.js";
 
 export default function continualHarness(pi: ExtensionAPI): void {
   // Rebuild in-memory state from the current branch on every session start /
@@ -26,14 +28,22 @@ export default function continualHarness(pi: ExtensionAPI): void {
     resetAutoRefine();
     resetReminder();
     resetOutcome();
+    resetDurableSync();
     // Drop any stale active-model key from the previous session: the next
     // before_agent_start re-caches it before any tool can run.
     setActiveModelKey(undefined);
+    // Cache the session's project slug BEFORE any tool delta can arrive: it is
+    // the server-side stamp for scope:"project" (harness_mutate has no ctx).
+    setSessionProject(projectSlug(ctx.cwd));
     reconstruct(ctx.sessionManager.getBranch() as Iterable<unknown>);
     const n = getState().items.length;
     if (n > 0) {
       ctx.ui.notify(`Continual Harness: ${n} item(s) restored`, "info");
     }
+    // Opt-in durable sync (issue #7): layered auto-import on top of the
+    // branch-restored state, so refinements made in OTHER sessions reach this
+    // one. No-op (and quiet) when autoImport is off or nothing changed.
+    await syncDurableOnStart(pi, ctx);
   });
 
   registerInjection(pi);
@@ -41,9 +51,9 @@ export default function continualHarness(pi: ExtensionAPI): void {
   registerRefine(pi);
   registerHarness(pi);
   registerReminder(pi);
-  // Register outcome BEFORE auto-refine: the test fake overwrites turn_end on
-  // each registration (Map.set), and the auto-refine integration tests assume
-  // auto-refine is the surviving handler. In production pi, all three run.
+  // Durable sync's turn_end export (opt-in via autoImport) registers before
+  // outcome/auto-refine; in production pi every turn_end handler runs.
+  registerAutoExport(pi);
   registerOutcome(pi);
   registerAutoRefine(pi);
 }

package/src/refine.ts

@@ -19,9 +19,10 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Context, Model, TextContent } from "@earendil-works/pi-ai";
-import { applyDeltas, exportDurable, modelKey, REFINE_ENTRY, snapshotState } from "./store.js";
+import { applyDeltas, DEFAULT_DURABLE_PATH, exportDurableLayers, modelKey, PROJECT_DURABLE_DIR, REFINE_ENTRY, snapshotState } from "./store.js";
 import { getProposer } from "./proposer.js";
 import type { CompleteOptions, CompleteResult } from "./proposer.js";
+import { projectSlug } from "./config.js";
 
 const DEFAULT_EVIDENCE_BYTES = 16000;
 export const DEFAULT_LOOKBACK_TURNS = 25;
@@ -151,11 +152,15 @@ export async function runRefine(
   });
 
   if (commit) {
-    // Flush current state to the durable file first so the agent refines
-    // against the same view pi-reflect / pi-mem would see.
+    // Flush current state to the durable layers first so the agent refines
+    // against the same view pi-reflect / pi-mem would see (layered: items land
+    // in the file their own scope selects).
     try {
-      const path = await exportDurable();
-      ctx.ui.notify(`Durable state exported to ${path}`, "info");
+      const written = await exportDurableLayers(
+        { globalPath: DEFAULT_DURABLE_PATH, projectDir: PROJECT_DURABLE_DIR },
+        projectSlug(ctx.cwd),
+      );
+      ctx.ui.notify(`Durable state exported to ${written.length} layer file(s)`, "info");
     } catch (err) {
       ctx.ui.notify(`Durable export failed: ${(err as Error).message}`, "warning");
     }

package/src/store.ts

@@ -10,15 +10,23 @@
 //     to a markdown file pi-reflect can read and refine offline, and pi-mem can
 //     ingest. Best-effort; the package works without it.
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type { AppliedDelta, ComponentKind, Delta, HarnessItem, HarnessState } from "./types.js";
 
+/** Resolved durable-layer scope for a parsed item. */
+export interface ScopeInfo {
+  scope: "global" | "project";
+  project?: string;
+}
+
 const STATE_ENTRY = "harness-state";
 const REFINE_ENTRY = "harness-refinement";
 
 export const DEFAULT_DURABLE_PATH = join(homedir(), ".pi", "agent", "harness-state.md");
+/** Directory holding per-project durable files: <slug>.md (see projectSlug). */
+export const PROJECT_DURABLE_DIR = join(homedir(), ".pi", "agent", "harness-state");
 
 const IMPORTANCE_FLOOR = 0.3;
 
@@ -38,6 +46,12 @@ let version = 0;
 // "model unknown" — tools fall back gracefully (create orphans, list all).
 let activeModelKey: string | undefined;
 
+// Same pattern for the session's project slug: the durable-layer stamp for
+// scope:"project" deltas that arrive without an explicit slug (the
+// model-facing tools have no ctx). Cached once per session_start from ctx.cwd
+// so scope stamps are stable no matter where a delta originates.
+let sessionProject: string | undefined;
+
 /** Canonical owner key for a model: "provider/id". Accepts the structural
  *  shape of pi-ai's Model (provider + id) without importing the type. */
 export function modelKey(m?: { provider: string; id: string }): string | undefined {
@@ -54,6 +68,18 @@ export function getActiveModelKey(): string | undefined {
   return activeModelKey;
 }
 
+/** Cache the session's project slug (called from session_start). */
+export function setSessionProject(slug: string | undefined): void {
+  sessionProject = slug;
+}
+
+/** Current store version — bumped by every persisted mutation, reset by
+ *  reconstruct. The auto-export loop compares it to detect "store changed
+ *  since the last durable export". */
+export function getVersion(): number {
+  return version;
+}
+
 export function getState(): HarnessState {
   return state;
 }
@@ -93,9 +119,13 @@ function applyOne(delta: Delta, actorModel?: string): AppliedDelta {
       // Owner: explicit delta wins; else the actor model; else orphan (""),
       // adopted by the active model on first contact.
       ownerModel: delta.ownerModel ?? actorModel ?? "",
+      // Durable-layer scope: global unless the delta says project (which
+      // requires a slug — explicit or the cached session slug).
+      scope: "global",
       createdAt: now,
       updatedAt: now,
     };
+    applyDeltaScope(item, delta);
     state.items.push(item);
     return { op: "create", item };
   }
@@ -117,6 +147,7 @@ function applyOne(delta: Delta, actorModel?: string): AppliedDelta {
       ownerModel: delta.ownerModel ?? before.ownerModel,
       updatedAt: Date.now(),
     };
+    applyDeltaScope(after, delta);
     state.items[idx] = after;
     return { op: "update", before, after };
   }
@@ -129,6 +160,28 @@ function applyOne(delta: Delta, actorModel?: string): AppliedDelta {
   return { op: "delete", id: delta.id, reason: delta.reason };
 }
 
+/** Stamp a delta's scope onto an item. No-op when the delta is silent about
+ *  scope. "project" needs a slug: explicit delta.project (set by
+ *  /harness move) or the cached session slug (model-driven scope updates);
+ *  throws otherwise so the surrounding applyDeltas rolls the batch back. */
+function applyDeltaScope(
+  item: HarnessItem,
+  delta: { scope?: "global" | "project"; project?: string },
+): void {
+  if (delta.scope === undefined) return;
+  if (delta.scope === "global") {
+    item.scope = "global";
+    delete item.project;
+    return;
+  }
+  const slug = delta.project ?? sessionProject;
+  if (!slug) {
+    throw new Error('scope: "project" requires a project slug (no session cwd cached)');
+  }
+  item.scope = "project";
+  item.project = slug;
+}
+
 /** Enforce that `actorModel` owns `item`; no-op when the actor is unknown
  *  (manual / cross-model paths). Throws an audited, rollback-triggering error
  *  otherwise. */
@@ -178,10 +231,23 @@ export function reconstruct(entries: Iterable<unknown>): void {
       last = entry.data.state;
     }
   }
-  // Normalize legacy snapshots that predate ownerModel: missing → orphan (""),
-  // adopted by the active model on first contact (see adoptOrphans).
+  // Normalize legacy snapshots: missing ownerModel → orphan (""), adopted by
+  // the active model on first contact (see adoptOrphans); missing/corrupt
+  // scope → "global" (a project item without a slug cannot be placed in a
+  // layer, so it falls back to the global durable file).
   state = last
-    ? { items: last.items.map((i) => ({ ...i, ownerModel: i.ownerModel ?? "" })) }
+    ? {
+        items: last.items.map((i): HarnessItem => {
+          const item: HarnessItem = { ...i, ownerModel: i.ownerModel ?? "", scope: "global" };
+          if (i.scope === "project" && i.project) {
+            item.scope = "project";
+            item.project = i.project;
+          } else {
+            delete item.project;
+          }
+          return item;
+        }),
+      }
     : { items: [] };
   version = 0;
 }
@@ -256,28 +322,95 @@ export function adoptOrphans(
 export { STATE_ENTRY, REFINE_ENTRY, IMPORTANCE_FLOOR };
 
 // ---- Durable export (composition seam with pi-reflect / pi-mem) -------------
-
-export async function exportDurable(path = DEFAULT_DURABLE_PATH): Promise<string> {
+//
+// Two write modes:
+//  - exportDurable(path): a FULL single-file snapshot (every active item,
+//    both scopes, project items tagged with a `scope:` sub-line so any copy of
+//    the file round-trips). Used for explicit-path /harness export and
+//    /refine --commit's legacy single-file output.
+//  - exportDurableLayers(paths, currentSlug): the LAYERED mode — partitions
+//    active items by their own scope: global-scoped → paths.globalPath,
+//    project-scoped → paths.projectDir/<slug>.md (one file per slug).
+
+/** Render the durable markdown for a set of items (empty → placeholder). */
+function renderDurable(items: HarnessItem[]): string {
   const lines: string[] = ["# Continual Harness State", ""];
   const kinds: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
   for (const kind of kinds) {
-    const items = state.items.filter((i) => i.kind === kind && i.active);
-    if (items.length === 0) continue;
+    const forKind = items.filter((i) => i.kind === kind);
+    if (forKind.length === 0) continue;
     lines.push(`## ${titleFor(kind)}`, "");
-    for (const i of items) {
+    for (const i of forKind) {
       lines.push(`- **[${i.id}]** (importance ${i.importance.toFixed(2)}) ${i.content}`);
       lines.push(`  - evidence: ${i.evidence}`);
       if (i.ownerModel) lines.push(`  - model: ${i.ownerModel}`);
+      if (i.scope === "project") lines.push(`  - scope: project (${i.project ?? ""})`);
     }
     lines.push("");
   }
   if (lines.length <= 2) lines.push("_(no active items)_", "");
-  const body = lines.join("\n");
+  return lines.join("\n");
+}
+
+async function writeFileDur(path: string, body: string): Promise<void> {
   await mkdir(dirname(path), { recursive: true }).catch(() => {});
   await writeFile(path, body, "utf8");
+}
+
+export async function exportDurable(path = DEFAULT_DURABLE_PATH): Promise<string> {
+  await writeFileDur(path, renderDurable(state.items.filter((i) => i.active)));
   return path;
 }
 
+/** Where the layered export writes each project's items. */
+export interface LayerPaths {
+  globalPath: string;
+  projectDir: string;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Layered export: global file always; one file per project slug that has
+ * active items; the CURRENT session's project file is also rewritten when it
+ * already exists on disk (so deleting the last project item empties that
+ * layer instead of leaving a stale file that auto-import would resurrect).
+ * Project files the store has no items for are never created.
+ */
+export async function exportDurableLayers(paths: LayerPaths, currentSlug?: string): Promise<string[]> {
+  const active = state.items.filter((i) => i.active);
+  const globalItems = active.filter((i) => !(i.scope === "project" && i.project));
+  const bySlug = new Map<string, HarnessItem[]>();
+  for (const i of active) {
+    if (i.scope === "project" && i.project) {
+      const arr = bySlug.get(i.project) ?? [];
+      arr.push(i);
+      bySlug.set(i.project, arr);
+    }
+  }
+  const written: string[] = [];
+  await writeFileDur(paths.globalPath, renderDurable(globalItems));
+  written.push(paths.globalPath);
+  const slugs = new Set(bySlug.keys());
+  if (currentSlug) slugs.add(currentSlug);
+  for (const slug of slugs) {
+    const file = join(paths.projectDir, `${slug}.md`);
+    const items = bySlug.get(slug) ?? [];
+    // Don't create empty per-project files as a side effect of visiting.
+    if (items.length === 0 && !(await fileExists(file))) continue;
+    await writeFileDur(file, renderDurable(items));
+    written.push(file);
+  }
+  return written;
+}
+
 function titleFor(kind: ComponentKind): string {
   switch (kind) {
     case "prompt":
@@ -299,7 +432,10 @@ function titleFor(kind: ComponentKind): string {
 //
 // Merge semantics (predictable, loss-free by default):
 //   - parsed item whose id matches an existing item → UPDATE in place
-//     (durable wins on content/evidence/importance; reactivated; createdAt kept).
+//     (durable wins on content/evidence/importance/owner/scope; reactivated;
+//     createdAt kept). When nothing actually differs the update is a NO-OP —
+//     no version bump, no persist — so repeated imports (and the opt-in
+//     session_start auto-import) stay idempotent and don't spam the tree.
 //   - parsed item with a new/foreign id → CREATE.
 //   - items in the store but absent from the file → KEPT by default.
 //     Pass { prune: true } to also drop active items whose id is not in the
@@ -317,13 +453,16 @@ export interface DurableImportResult {
   missingFile: boolean;
 }
 
-interface ParsedItem {
+export interface ParsedItem {
   id?: string;
   kind: ComponentKind;
   importance: number;
   content: string;
   evidence: string;
   ownerModel?: string;
+  /** Only set when the file carries an explicit `scope:` sub-line. */
+  scope?: "global" | "project";
+  project?: string;
 }
 
 // Section title → kind. Exact export titles first, then tolerant keyword
@@ -349,6 +488,7 @@ const RE_ID_BULLET = /^-\s+\*\*\[([^\]]+)\]\*\*\s*\(importance\s+([\d.]+)\)\s*(.
 const RE_PLAIN_BULLET = /^-\s+(.+)$/;
 const RE_EVIDENCE = /^\s+-\s+evidence:\s*(.*)$/i;
 const RE_MODEL = /^\s+-\s+model:\s*(.*)$/i;
+const RE_SCOPE = /^\s+-\s+scope:\s*(global|project)\b\s*(?:\(([^)]*)\))?/i;
 
 /** Parse a durable markdown export into items. Tolerant of pi-reflect's edits. */
 export function parseDurable(text: string): ParsedItem[] {
@@ -386,6 +526,20 @@ export function parseDurable(text: string): ParsedItem[] {
       continue;
     }
 
+    const scp = line.match(RE_SCOPE);
+    if (scp) {
+      if (pending) {
+        if (scp[1]!.toLowerCase() === "project") {
+          pending.scope = "project";
+          const slug = (scp[2] ?? "").trim();
+          if (slug) pending.project = slug;
+        } else {
+          pending.scope = "global";
+        }
+      }
+      continue;
+    }
+
     const idm = line.match(RE_ID_BULLET);
     if (idm) {
       flush();
@@ -419,44 +573,51 @@ export function parseDurable(text: string): ParsedItem[] {
   return out.filter((p) => p.content && !/^\(?no active items\)?$/i.test(p.content));
 }
 
-/**
- * Parse the durable file and merge it into the live store, then persist a
- * snapshot. See the file-level comment above for merge semantics.
- */
-export async function reconstructFromDurable(
-  path: string,
+/** Merge parsed items (with fully-resolved scope) into the live store.
+ *  Shared by the single-file and layered import paths. */
+function mergeParsed(
+  parsed: Array<ParsedItem & ScopeInfo>,
   options: { prune?: boolean },
   persist: (snapshot: HarnessState, version: number) => void,
-): Promise<DurableImportResult> {
-  let text: string;
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    return { imported: 0, created: 0, updated: 0, pruned: 0, missingFile: true };
-  }
-
-  const parsed = parseDurable(text);
+): DurableImportResult {
   const fileIds = new Set(parsed.map((p) => p.id).filter((id): id is string => Boolean(id)));
   const existingById = new Map(state.items.map((i) => [i.id, i] as const));
   const preActiveIds = new Set(state.items.filter((i) => i.active).map((i) => i.id));
 
   let created = 0;
   let updated = 0;
+  let dirty = false;
   const now = Date.now();
   for (const p of parsed) {
     const existing = p.id ? existingById.get(p.id) : undefined;
     if (existing) {
-      // Durable wins; reactivate; keep createdAt.
+      const importance = clamp(p.importance);
+      const ownerModel = p.ownerModel ?? "";
+      // Durable wins; reactivate; keep createdAt. Idempotent imports skip the
+      // write (and the persist) when the live item already matches the file.
+      const unchanged =
+        existing.content === p.content &&
+        existing.evidence === p.evidence &&
+        existing.importance === importance &&
+        existing.active &&
+        existing.ownerModel === ownerModel &&
+        (existing.scope ?? "global") === p.scope &&
+        (existing.scope === "project" ? existing.project : undefined) === p.project;
+      if (unchanged) continue;
       existing.content = p.content;
       existing.evidence = p.evidence;
-      existing.importance = clamp(p.importance);
+      existing.importance = importance;
       existing.active = true;
       // Durable wins on owner too: a present tag sets the owner; an absent tag
       // (e.g. pi-reflect stripped it) orphans the item so it's adopted by the
       // active model on first contact — matching the documented round-trip.
-      existing.ownerModel = p.ownerModel ?? "";
+      existing.ownerModel = ownerModel;
+      existing.scope = p.scope;
+      if (p.scope === "project" && p.project) existing.project = p.project;
+      else delete existing.project;
       existing.updatedAt = now;
       updated += 1;
+      dirty = true;
     } else {
       const id = p.id && /^h_/.test(p.id) ? p.id : genId();
       state.items.push({
@@ -467,10 +628,16 @@ export async function reconstructFromDurable(
         importance: clamp(p.importance),
         active: true,
         ownerModel: p.ownerModel ?? "",
+        ...(p.scope === "project" && p.project ? { scope: "project" as const, project: p.project } : { scope: "global" as const }),
         createdAt: now,
         updatedAt: now,
       });
       created += 1;
+      dirty = true;
+      // Keep the lookup current so a later layer's copy of the same id
+      // UPDATES the item we just created instead of duplicating it (the same
+      // id in both layers is the normal collision case, not an anomaly).
+      if (p.id) existingById.set(p.id, state.items[state.items.length - 1]!);
     }
   }
 
@@ -484,9 +651,80 @@ export async function reconstructFromDurable(
       return false; // was active before, absent from the file → drop
     });
     pruned = before - state.items.length;
+    if (pruned > 0) dirty = true;
   }
 
+  if (!dirty) return { imported: parsed.length, created, updated, pruned, missingFile: false };
   version += 1;
   persist(state, version);
   return { imported: parsed.length, created, updated, pruned, missingFile: false };
 }
+
+/** Resolve a parsed item's scope against the layer default (for items without
+ *  an explicit `scope:` sub-line: the layer they were read from decides).
+ *  A `scope: project` tag without any resolvable slug degrades to global —
+ *  the invariant is scope==="project" ⟹ project (a slugless project item
+ *  could not be placed in any layer file). */
+function withDefaultScope(p: ParsedItem, def: ScopeInfo): ParsedItem & ScopeInfo {
+  if (p.scope === "project") {
+    const project = p.project ?? def.project;
+    return project ? { ...p, scope: "project", project } : { ...p, scope: "global" };
+  }
+  if (p.scope === "global") return { ...p, scope: "global" };
+  return { ...p, ...def };
+}
+
+/**
+ * Parse the durable file and merge it into the live store, then persist a
+ * snapshot. Untagged items default to global scope (single-file semantics).
+ * See the file-level comment above for merge semantics.
+ */
+export async function reconstructFromDurable(
+  path: string,
+  options: { prune?: boolean },
+  persist: (snapshot: HarnessState, version: number) => void,
+): Promise<DurableImportResult> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return { imported: 0, created: 0, updated: 0, pruned: 0, missingFile: true };
+  }
+  return mergeParsed(parseDurable(text).map((p) => withDefaultScope(p, { scope: "global" })), options, persist);
+}
+
+/** One layer of a layered import: items without an explicit `scope:` sub-line
+ *  adopt this layer's scope (the global file → global; a project file → that
+ *  project's slug). */
+export interface LayerFile {
+  path: string;
+  defaultScope: ScopeInfo;
+}
+
+/**
+ * Layered import (issue #7): read every layer file that exists, then merge
+ * ALL of them in one pass — so { prune: true } drops only items absent from
+ * EVERY layer (union semantics), not from each file in turn. Earlier layers
+ * lose id collisions to later ones; callers pass the global file first so the
+ * project layer wins on conflicts.
+ */
+export async function importDurableLayers(
+  files: LayerFile[],
+  options: { prune?: boolean },
+  persist: (snapshot: HarnessState, version: number) => void,
+): Promise<DurableImportResult> {
+  const all: Array<ParsedItem & ScopeInfo> = [];
+  let foundAny = false;
+  for (const f of files) {
+    let text: string;
+    try {
+      text = await readFile(f.path, "utf8");
+    } catch {
+      continue;
+    }
+    foundAny = true;
+    for (const p of parseDurable(text)) all.push(withDefaultScope(p, f.defaultScope));
+  }
+  if (!foundAny) return { imported: 0, created: 0, updated: 0, pruned: 0, missingFile: true };
+  return mergeParsed(all, options, persist);
+}

package/src/tools.ts

@@ -24,6 +24,12 @@ const CreateShape = Type.Object({
   // ownerModel is intentionally NOT exposed to the model: it is stamped
   // server-side from the active model so items bind to the model driving the
   // turn without the agent having to (or being able to) name it.
+  scope: Type.Optional(
+    StringEnum(["global", "project"], {
+      description:
+        "Durable-layer scope (default global). \"project\" binds the item to this session's project file (slug stamped server-side). Normally managed via /harness move or /harness split — set directly only when a new item is clearly project-specific.",
+    }),
+  ),
 });
 
 const UpdateShape = Type.Object({
@@ -33,6 +39,12 @@ const UpdateShape = Type.Object({
   evidence: Type.Optional(Type.String()),
   importance: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
   active: Type.Optional(Type.Boolean()),
+  scope: Type.Optional(
+    StringEnum(["global", "project"], {
+      description:
+        "Move the item between durable layers (global file vs this session's project file). Use during a /harness split classification; leave unchanged otherwise.",
+    }),
+  ),
 });
 
 const DeleteShape = Type.Object({

package/src/types.ts

@@ -33,6 +33,16 @@ export interface HarnessItem {
    * Orphans are adopted by the active model on first contact (see store.ts).
    */
   ownerModel: string;
+  /**
+   * Durable-layer scope: "global" (default) → the shared durable file
+   * (~/.pi/agent/harness-state.md); "project" → the per-project file
+   * (~/.pi/agent/harness-state/<slug>.md). Scope decides WHERE an item is
+   * exported / imported from — it does NOT affect per-turn injection.
+   * Undefined is treated as "global" (legacy snapshots / durable files).
+   */
+  scope?: "global" | "project";
+  /** Project slug (see projectSlug in config.ts); set iff scope === "project". */
+  project?: string;
   createdAt: number;
   updatedAt: number;
 }
@@ -52,6 +62,11 @@ export type Delta =
       /** Owner "provider/id". Stamped server-side from the active model when the
        *  agent omits it; set explicitly by direct-apply proposers. Absent → orphan. */
       ownerModel?: string;
+      /** Durable-layer scope (default "global"). "project" requires a slug:
+       *  taken from the session cwd (stamped at session_start) when omitted. */
+      scope?: "global" | "project";
+      /** Explicit project slug for scope:"project" (server-side use). */
+      project?: string;
     }
   | {
       op: "update";
@@ -62,6 +77,12 @@ export type Delta =
       active?: boolean;
       /** Reassign ownership (rare; used by migration/import). Absent → keep current. */
       ownerModel?: string;
+      /** Move the item between durable layers. Absent → keep current scope.
+       *  "project" requires `project` (set by /harness move) or a cached
+       *  session slug; "global" clears the project binding. */
+      scope?: "global" | "project";
+      /** Explicit project slug for scope:"project" (server-side use). */
+      project?: string;
     }
   | { op: "delete"; id: string; reason: string };