pi-continual-harness 0.11.0 → 0.12.0

package/README.md

@@ -145,8 +145,10 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   "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 },
-  "outcomeImportance": { "enabled": false, "bump": 0.03 }
+  "autoRefine": { "enabled": false, "everyTurns": 100, "commit": false, "gate": false },
+  "outcomeImportance": { "enabled": false, "bump": 0.03 },
+  "classifier": { "model": "typesafe/jev-latest" },
+  "virtualBinding": "virtual"
 }
 ```
 
@@ -187,7 +189,29 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   (default 100). It is one of the package's opt-in autonomous paths: it reuses
   the exact `/refine` routine (audited `REFINE_ENTRY` tagged `source: "auto"`,
   branch-local, `/tree` rollback) and notifies before firing. `commit: true`
-  also flushes durable state on each run.
+  also flushes durable state on each run. `gate: true` (needs `classifier.model`)
+  asks the classifier first whether the recent trajectory contains a durable,
+  reusable correction and skips the refine when it does not — cadence becomes
+  signal, not just time (errors fall back to the plain cadence). The steering
+  prompt is delivered via the pi ≥ 0.87 actionable `turn_end` boundary (a
+  structural `harness.auto-refine-request` entry + `continue: true`), not a
+  synthetic user message.
+- **`classifier`** — opt-in classifier model (pi ≥ 0.99) for the cheap gated
+  paths: `"provider/id"` or a bare id of a **classifier** catalog entry, e.g.
+  `"typesafe/jev-latest"` or a local `llama-cpp` classifier (every chat model
+  listed for llama.cpp also appears as a classifier). When set and resolvable
+  it enables the classifier-confirmed dedupe (see `dedupe` above) and the
+  auto-refine `gate`. When unset or unresolvable, every classifier feature
+  degrades to its no-classifier behavior.
+- **`virtualBinding`** — how the per-model isolation key treats pi **virtual
+  models** (router extensions, pi ≥ 0.99). Default `"virtual"`: the key is
+  the selected model's own `provider/id` — a router starts a blank harness.
+  `"physical"`: when the selection is virtual, the key is the *physical*
+  model behind the latest successful response on the branch — notes
+  accumulated under that physical model keep injecting through the router, and
+  switching routed models re-scopes exactly like a manual model switch. Before
+  the first response the key is unknown: creates stay orphans and are adopted
+  on first contact.
 - **`outcomeImportance`** — opt-in autonomous **promotion** loop (**off by
   default**). When `enabled`, a `turn_end` hook bumps (+`bump`, default 0.03)
   the importance of any active item the agent cited by its `[h_xxxx]` tag in the
@@ -370,7 +394,7 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 
 ## Status
 
-0.9.x. Implemented:
+0.12.x. Requires **pi ≥ 0.99.0**. Implemented:
 
 - Unified harness-state store with branch-local snapshots (`/tree` rollback).
 - Online `/refine` + `harness_mutate` / `harness_list` tools.
@@ -395,11 +419,28 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 - **Per-model isolation**: every item is bound to a `provider/id` and injected
   only for that model; new items are stamped automatically and orphans adopted
   on first contact. A new model id starts from a blank harness, and the durable
-  round-trip preserves the owner tag.
+  round-trip preserves the owner tag. With pi virtual models (routers), the
+  `"virtualBinding": "physical"` policy keys items by the routed physical
+  model instead of the router id, so a router selection does not silently
+  reset the harness.
 - **Bounded injection (on by default)**: the supplemental block is
   importance-ordered and capped per kind + by a total token budget, so a growing
   harness never balloons the system prompt. Tunable / opt-out via the `injection`
-  config key; the store is never changed by selection.
+  config key; the store is never changed by selection. Rendered on **every
+  provider request** (`context_with_system`), so a mid-run `harness_mutate`
+  shows up on the very next request.
+- **Classifier features (pi ≥ 0.99, opt-in)**: `"classifier": { "model": … }`
+  enables (1) classifier-confirmed dedupe — candidate merge pairs confirmed by
+  one batched yes/no call (errors fall back to the rule-based plan) — and (2)
+  the auto-refine gate `"autoRefine": { "gate": true }`, which skips a cadenced
+  refine when the trajectory holds no durable correction.
+- **Structured tool results**: `harness_list` / `harness_mutate` return
+  `structuredContent` (with `outputSchema`), so codemode scripts and
+  `ctx.executeTool()` callers can consume harness state programmatically.
+- **Boundary delivery for auto-refine**: the steering prompt is persisted as a
+  structural entry with `{ entries, continue: true }` at `turn_end` (no
+  synthetic user message, no follow-up-scheduling side effects); manual
+  `/refine` still steers via a user message.
 
 Open extension points (see `docs/ROADMAP.md`):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -35,13 +35,13 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-ai": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=0.99.0",
     "typebox": ">=1.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-ai": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=0.99.0",
     "typebox": ">=1.0.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0",

package/src/auto-refine.ts

@@ -9,13 +9,30 @@
 // properties: structured evidence-backed deltas, an audited REFINE_ENTRY
 // (tagged source: "auto"), branch-local snapshots, and /tree rollback.
 //
-// It is also visible: it notifies before firing and the steering message
-// appears in the transcript. The decision logic is factored into
+// Two pi ≥ 0.87/0.99 upgrades (0.12.0):
+//
+//  - Classifier gate (opt-in via autoRefine.gate + classifier.model): before
+//    spending a refine, ask ONE cheap yes/no classifier question over the
+//    recent trajectory. "No durable correction" skips the refine entirely —
+//    cadence becomes signal, not just time. Soft-fails to the plain cadence on
+//    any classifier error (the gate can skip work, never block it).
+//
+//  - Boundary delivery: the steering message is no longer sent as a synthetic
+//    user message; runRefine returns it undelivered and this handler persists
+//    it as a structural custom-message entry with `{ entries, continue: true }`
+//    — the actionable turn_end boundary. One guaranteed next provider request,
+//    no steering queue and no follow-up scheduling side effects. Falls back to
+//    sendUserMessage when the boundary cannot continue (event.context.
+//    canContinue false, e.g. after an error turn).
+//
+// It stays visible: it notifies before firing, and the boundary draft (and the
+// gate decision) appear in the transcript. The decision logic is factored into
 // evaluateAutoRefine() so it is unit-testable without a live pi runtime.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AUTO_EVERY_TURNS, type HarnessConfig, loadConfig } from "./config.js";
-import { runRefine } from "./refine.js";
+import { runRefine, gatherEvidence, DEFAULT_LOOKBACK_TURNS } from "./refine.js";
+import { buildClassify, buildGateRequest, gateDecision } from "./classify.js";
 
 // turnIndex of the last auto-refine (or the seeded baseline). -1 = unseen.
 let lastTurn = -1;
@@ -45,20 +62,64 @@ export function evaluateAutoRefine(config: HarnessConfig, turnIndex: number): bo
   return false;
 }
 
+/** The boundary draft custom type for auto-refine steering messages. */
+export const AUTO_REFINE_ENTRY = "harness.auto-refine-request";
+
+/** Build the boundary draft carrying a steering message. Pure — testable. */
+export function buildRefineDraft(steeringMessage: string): {
+  type: "custom_message";
+  customType: string;
+  content: string;
+  display: boolean;
+} {
+  return { type: "custom_message", customType: AUTO_REFINE_ENTRY, content: steeringMessage, display: true };
+}
+
 /** Subscribe to turn_end and run /refine on the configured cadence. */
 export function registerAutoRefine(pi: ExtensionAPI): void {
   pi.on("turn_end", async (event, ctx) => {
     const config = await loadConfig();
     if (!evaluateAutoRefine(config, event.turnIndex)) return;
     const every = config.autoRefine?.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS;
+
+    // Opt-in classifier gate: cheap yes/no before spending the refine.
+    if (config.autoRefine?.gate) {
+      const classify = buildClassify(ctx, config.classifier?.model);
+      if (classify) {
+        const evidence = gatherEvidence(ctx, DEFAULT_LOOKBACK_TURNS);
+        const res = await classify(buildGateRequest(evidence));
+        const decision = gateDecision(res);
+        if (!decision.proceed) {
+          ctx.ui.notify(`Auto-refine: skipped — ${decision.because}.`, "info");
+          return;
+        }
+        ctx.ui.notify(`Auto-refine: gate passed (${decision.because}).`, "info");
+      }
+      // No resolvable classifier → plain cadence behavior (documented soft-fail).
+    }
+
     ctx.ui.notify(`Auto-refine: running /refine (every ${every} turns, opt-in).`, "info");
     try {
-      await runRefine(
+      const result = await runRefine(
         pi,
         ctx,
-        { commit: config.autoRefine?.commit ?? false, ...(config.proposer ? { proposer: config.proposer } : {}) },
+        {
+          commit: config.autoRefine?.commit ?? false,
+          ...(config.proposer ? { proposer: config.proposer } : {}),
+          delivery: "boundary",
+        },
         "auto",
       );
+      // Boundary delivery: persist the steering message as a structural entry
+      // and guarantee one next provider request. Only when the boundary CAN
+      // continue — otherwise fall back to the legacy steering send.
+      if (result.steeringMessage) {
+        if (event.context?.canContinue === false) {
+          pi.sendUserMessage(result.steeringMessage);
+          return;
+        }
+        return { entries: [...event.entries, buildRefineDraft(result.steeringMessage)], continue: true };
+      }
     } catch (err) {
       ctx.ui.notify(`Auto-refine failed: ${(err as Error).message}`, "error");
     }

package/src/classify.ts

@@ -0,0 +1,220 @@
+// Classifier adapter (pi ≥ 0.99). Wraps ctx.modelRegistry.classify() — cheap
+// typed yes/no or score questions answered from next-token label probabilities
+// (local llama.cpp) or a hosted Jev model — behind two package seams:
+//
+//  1. autoRefine gate (auto-refine.ts): when the cadence elapses, ask ONE bool
+//     question over the recent trajectory ("did it contain a durable, reusable
+//     correction?") and skip the refine when the answer is no. Soft-fails to the
+//     old cadence behavior on any classifier error, so a flaky classifier never
+//     blocks refinement.
+//  2. dedupe confirmation (proposer.ts): a precision filter on candidate merge
+//     pairs — see classifyConfirmPairs().
+//
+// The pi-ai classifier shapes (ClassifierContext/ClassifierQuestion/…) are kept
+// OUT of the public proposer interface: ClassifyFn below is a minimal structural
+// contract so proposers stay testable without pi runtime types.
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** One yes/no question in a ClassifyFn request. */
+export interface ClassifyBoolQuestion {
+  instructions: string;
+  /** Criteria text for the yes answer. */
+  trueCriteria: string;
+  /** Criteria text for the no answer. */
+  falseCriteria: string;
+}
+
+/** A parsed answer per question key. */
+export interface ClassifyBoolAnswer {
+  /** The classifier's decision. */
+  value: boolean;
+  /** [0,1] confidence when the engine reports one. */
+  confidence?: number;
+}
+
+/** Result of a ClassifyFn call: one answer per question key, or an error. */
+export interface ClassifyBoolResult {
+  ok: boolean;
+  answers: Record<string, ClassifyBoolAnswer>;
+  /** Resolved classifier label ("provider/id") for telemetry. */
+  model?: string;
+  /** Token usage when the engine reports it (for the audit trail). */
+  usage?: { input: number; output: number };
+  error?: string;
+}
+
+/**
+ * Batched yes/no classification seam injected into ProposeInput when a
+ * classifier model is configured AND resolvable. Structural on purpose —
+ * the adapter below is the only place that knows pi-ai's shapes.
+ */
+export type ClassifyFn = (input: {
+  state: Record<string, unknown>;
+  questions: Record<string, ClassifyBoolQuestion>;
+}) => Promise<ClassifyBoolResult>;
+
+/** Structural slice of ctx.modelRegistry used here. */
+interface RegistryLike {
+  classify?: (model: unknown, context: unknown, options?: unknown) => Promise<ClassifyRawResult>;
+  findOfType?: (type: "classifier", provider: string, id: string) => unknown | undefined;
+  getModelsOfType?: (type: "classifier") => readonly unknown[];
+}
+
+/** Raw pi-ai ClassifierResult slice (never rejects, but stopReason may be error). */
+interface ClassifyRawResult {
+  answers?: Record<string, { type?: string; choice?: unknown; score?: number; probability?: number; confidence?: number }>;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+/** Raw classifier-model slice (Model<ClassifierApi>). */
+interface ClassifierModelLike {
+  provider?: string;
+  id?: string;
+}
+
+/**
+ * Resolve a classifier model from a configured id ("provider/id" or bare id).
+ * Returns undefined when unconfigured or unresolvable — every feature keyed on
+ * it then degrades to its no-classifier behavior.
+ */
+export function resolveClassifierModel(
+  registry: RegistryLike | undefined,
+  configured?: string,
+): ClassifierModelLike | undefined {
+  if (!configured || !registry) return undefined;
+  const slash = configured.indexOf("/");
+  if (slash > 0 && typeof registry.findOfType === "function") {
+    const byPair = registry.findOfType("classifier", configured.slice(0, slash), configured.slice(slash + 1));
+    if (byPair) return byPair as ClassifierModelLike;
+  }
+  const all =
+    typeof registry.getModelsOfType === "function"
+      ? [...registry.getModelsOfType("classifier")]
+      : [];
+  return (all.find((m) => {
+    const cm = m as ClassifierModelLike;
+    return cm.id === configured || `${cm.provider}/${cm.id}` === configured;
+  }) ?? undefined) as ClassifierModelLike | undefined;
+}
+
+/** Build the ClassifyFn adapter over a resolved classifier model. */
+export function makeClassifyFn(
+  registry: RegistryLike,
+  model: ClassifierModelLike,
+  signal?: AbortSignal,
+): ClassifyFn {
+  const label = `${model.provider}/${model.id}`;
+  return async ({ state, questions }) => {
+    if (typeof registry.classify !== "function") {
+      return { ok: false, answers: {}, model: label, error: "modelRegistry.classify unavailable" };
+    }
+    // Map our minimal bool contract onto pi-ai's ClassifierBoolQuestion.
+    const piQuestions: Record<string, unknown> = {};
+    for (const [key, q] of Object.entries(questions)) {
+      piQuestions[key] = {
+        type: "bool",
+        instructions: q.instructions,
+        criteria: { true: q.trueCriteria, false: q.falseCriteria },
+      };
+    }
+    let raw: ClassifyRawResult;
+    try {
+      raw = (await registry.classify(model, { state, questions: piQuestions }, signal ? { signal } : undefined)) as ClassifyRawResult;
+    } catch (err) {
+      // classify "never rejects", but stay defensive around transport edges.
+      return { ok: false, answers: {}, model: label, error: (err as Error).message };
+    }
+    const usage =
+      typeof (raw as { usage?: { input?: number; output?: number } }).usage?.input === "number" &&
+      typeof (raw as { usage?: { input?: number; output?: number } }).usage?.output === "number"
+        ? {
+            input: (raw as { usage?: { input: number; output: number } }).usage!.input,
+            output: (raw as { usage?: { input: number; output: number } }).usage!.output,
+          }
+        : undefined;
+    if (raw.stopReason && raw.stopReason !== "stop") {
+      return {
+        ok: false,
+        answers: {},
+        model: label,
+        ...(usage ? { usage } : {}),
+        error: raw.errorMessage ?? `stopReason ${raw.stopReason}`,
+      };
+    }
+    const answers: Record<string, ClassifyBoolAnswer> = {};
+    for (const [key, a] of Object.entries(raw.answers ?? {})) {
+      let value: boolean | undefined;
+      let confidence: number | undefined;
+      if (a?.type === "bool") {
+        // Bool answers carry the probability of TRUE.
+        value = (a.probability ?? 0) >= 0.5;
+        confidence = a.probability;
+      } else if (a?.type === "choice") {
+        value = a.choice === true || a.choice === "true";
+        confidence = a.confidence;
+      } else if (a?.type === "score") {
+        value = (a.score ?? 0) >= 0.5;
+        confidence = a.confidence;
+      }
+      if (value !== undefined) {
+        answers[key] = { value, ...(typeof confidence === "number" ? { confidence } : {}) };
+      }
+    }
+    return { ok: true, answers, model: label, ...(usage ? { usage } : {}) };
+  };
+}
+
+/**
+ * Resolve the ClassifyFn for a session from config + ctx, or undefined.
+ * The single construction point shared by refine (ProposeInput.classify) and
+ * the auto-refine gate.
+ */
+export function buildClassify(
+  ctx: ExtensionContext,
+  configuredModel?: string,
+): ClassifyFn | undefined {
+  const registry = ctx.modelRegistry as RegistryLike | undefined;
+  const model = resolveClassifierModel(registry, configuredModel);
+  if (!registry || !model) return undefined;
+  return makeClassifyFn(registry, model, ctx.signal);
+}
+
+/**
+ * The auto-refine gate question: did the recent trajectory contain a durable,
+ * reusable correction worth a /refine pass? Pure builder — unit-testable.
+ * Keeps the state payload bounded (the caller already bounds evidence bytes).
+ */
+export function buildGateRequest(evidence: string): {
+  state: Record<string, unknown>;
+  questions: Record<string, ClassifyBoolQuestion>;
+} {
+  return {
+    state: { trajectory: evidence },
+    questions: {
+      gate: {
+        instructions:
+          "You are gating an online self-improvement pass for a coding agent. Does the recent trajectory below contain a durable, reusable correction — a mistake fixed, a preference learned, a convention discovered, or a fact worth remembering across sessions — that is NOT already routine work?",
+        trueCriteria:
+          "The trajectory contains at least one durable, reusable lesson or correction worth persisting into the agent's harness state.",
+        falseCriteria:
+          "The trajectory is routine work (ordinary edits, reads, test runs) with no reusable correction worth persisting.",
+      },
+    },
+  };
+}
+
+/**
+ * Gate decision from a classify result. Errors and missing answers fall back to
+ * `true` (proceed) so a flaky classifier never disables refinement — the gate
+ * can only SKIP work, never block it.
+ */
+export function gateDecision(result: ClassifyBoolResult): { proceed: boolean; because: string } {
+  if (!result.ok) return { proceed: true, because: `classifier error (${result.error ?? "unknown"}); falling back to cadence` };
+  const a = result.answers.gate;
+  if (!a) return { proceed: true, because: "no gate answer; falling back to cadence" };
+  return a.value
+    ? { proceed: true, because: `classifier: yes (confidence ${a.confidence ?? "?"})` }
+    : { proceed: false, because: `classifier: no durable correction (confidence ${a.confidence ?? "?"})` };
+}

package/src/config.ts

@@ -27,6 +27,12 @@ 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;
 
+/** How the binding key treats virtual (router) models. "virtual" (default):
+ * key = the selected model's own provider/id. "physical": when the selection
+ * is virtual, key = the physical model behind the latest successful response
+ * on the branch (see src/vmodel.ts). */
+export type VirtualBinding = "virtual" | "physical";
+
 /** 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. */
@@ -51,7 +57,21 @@ export interface HarnessConfig {
     enabled?: boolean;
     everyTurns?: number;
     commit?: boolean;
+    /** Opt-in classifier gate (pi ≥ 0.99, needs `classifier.model`): when the
+     *  cadence elapses, ask a cheap yes/no classifier whether the recent
+     *  trajectory contains a durable correction; skip the refine when it says
+     *  no. Soft-fails to the plain cadence on classifier errors. Default false. */
+    gate?: boolean;
+  };
+  /** Classifier model for the cheap gated paths (pi ≥ 0.99): "provider/id" or
+   *  a bare id of a classifier catalog entry (e.g. "typesafe/jev-latest" or a
+   *  local llama.cpp classifier). When unset or unresolvable, every classifier
+   *  feature degrades to its no-classifier behavior. */
+  classifier?: {
+    model?: string | undefined;
   };
+  /** Virtual-model binding policy (pi ≥ 0.99). Default "virtual". */
+  virtualBinding?: VirtualBinding;
   /** Delta proposer name (see proposer.ts registry). Defaults to "steering". */
   proposer?: string;
   /** Opt-in turn_end outcome loop: promote importance of items the agent
@@ -72,7 +92,9 @@ 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 },
+  autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false, gate: false },
+  classifier: { model: undefined },
+  virtualBinding: "virtual",
   proposer: "steering",
   outcomeImportance: { enabled: false, bump: DEFAULT_REF_BUMP },
   // Dedupe (merge-capable): merge ON at the historical 0.6 threshold — a
@@ -102,7 +124,12 @@ function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
       enabled: over.autoRefine?.enabled ?? false,
       everyTurns: over.autoRefine?.everyTurns ?? DEFAULT_AUTO_EVERY_TURNS,
       commit: over.autoRefine?.commit ?? false,
+      gate: over.autoRefine?.gate === true,
+    },
+    classifier: {
+      model: typeof over.classifier?.model === "string" && over.classifier.model ? over.classifier.model : undefined,
     },
+    virtualBinding: over.virtualBinding === "physical" ? "physical" : "virtual",
     proposer: over.proposer ?? "steering",
     outcomeImportance: {
       enabled: over.outcomeImportance?.enabled ?? false,

package/src/index.ts

@@ -117,3 +117,25 @@ export {
   type NormalizedInjection,
   type SelectionResult,
 } from "./select.js";
+
+// Virtual-model binding policy (pi ≥ 0.99, 0.12.0): strict per-model isolation
+// across router selections. Re-exported so companion packages and tests reuse
+// the pure resolution without reaching into internal paths.
+export {
+  branchEntries,
+  isVirtualModel,
+  physicalKeyFromBranch,
+  resolveBindingKey,
+  VIRTUAL_MODEL_API,
+} from "./vmodel.js";
+
+// Classifier seam (pi ≥ 0.99, 0.12.0): the minimal structural ClassifyFn
+// contract proposers see, plus the gate builders (pure, testable).
+export {
+  buildGateRequest,
+  gateDecision,
+  type ClassifyBoolAnswer,
+  type ClassifyBoolQuestion,
+  type ClassifyBoolResult,
+  type ClassifyFn,
+} from "./classify.js";

package/src/inject.ts

@@ -1,13 +1,19 @@
-// before_agent_start: inject the active harness state as a structured block
-// appended to the base system prompt. Never rewrites or replaces the base —
-// only appends, matching Continual Harness's "immutable base + supplemental".
+// Injection of the active harness state — two cooperating handlers (pi ≥ 0.99):
 //
-// This handler is also the model-binding bridge. The model-facing tools
-// (harness_list / harness_mutate) receive NO ctx, so they cannot read the
-// active model at execute time. before_agent_start always fires first in a turn
-// WITH ctx.model, so it: (1) caches the active model key for the tools,
-// (2) adopts any orphan items to the active model (the migration policy), and
-// (3) renders ONLY items bound to the active model — strict per-model isolation.
+//  before_agent_start: the model-binding bridge. The model-facing tools
+//  (harness_list / harness_mutate) receive no usable ctx, so this always-first
+//  handler (1) resolves the binding key under the configured virtual-model
+//  policy (see vmodel.ts) and caches it for the tools, and (2) adopts any
+//  orphan items to that key (the migration policy). It no longer bakes the
+//  harness block into the base system prompt.
+//
+//  context_with_system: the render. Fires before EVERY provider request on the
+//  full transcript (system message included), so the block always reflects the
+//  LIVE store — a harness_mutate that fixes a stale note mid-run shows up on
+//  the very next request instead of the next agent run. The handler owns the
+//  returned transcript (pi sends it verbatim), so it returns undefined — never
+//  an owned transcript — when there is nothing to inject, and otherwise keeps
+//  the system message at index 0 and appends the block to it.
 //
 // WHAT gets rendered is decided by the selection policy in select.ts (on by
 // default): importance-ordered, capped per kind and by a total token budget, so
@@ -15,9 +21,10 @@
 // harness.json `injection`; the legacy "all items, in order" mode is a toggle.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { adoptOrphans, getState, modelKey, setActiveModelKey } from "./store.js";
+import { adoptOrphans, getActiveModelKey, getState, setActiveModelKey } from "./store.js";
 import { KIND_ORDER, selectForInjection, type InjectionConfig } from "./select.js";
 import { loadConfig } from "./config.js";
+import { resolveBindingKey, branchEntries } from "./vmodel.js";
 import type { ComponentKind } from "./types.js";
 
 const TITLES: Record<ComponentKind, string> = {
@@ -70,24 +77,49 @@ export function renderHarnessBlock(ownerKey?: string, cfg?: InjectionConfig): st
   return lines.join("\n");
 }
 
+/** Append text to a system message's content (string or text blocks). */
+function appendToSystemContent(content: string | Array<{ type: string; text?: string }>, block: string): string | Array<{ type: string; text?: string }> {
+  if (typeof content === "string") return content + "\n" + block;
+  return [...content, { type: "text", text: block }];
+}
+
 export function registerInjection(pi: ExtensionAPI): void {
-  pi.on("before_agent_start", async (event, ctx) => {
-    const key = modelKey(ctx.model);
+  pi.on("before_agent_start", async (_event, ctx) => {
+    // Resolve the binding key under the configured policy. For a physical
+    // selection (or the default "virtual" policy) this is just provider/id;
+    // under "physical" with a virtual selection it is the routed model behind
+    // the latest successful response, undefined before the first response
+    // (creates then become orphans, adopted on the next contact).
+    const { virtualBinding } = await loadConfig();
+    const key = resolveBindingKey(ctx.model, branchEntries(ctx), virtualBinding);
     // Cache for the model-facing tools (they have no ctx of their own).
     setActiveModelKey(key);
-    // Adopt any orphans to the active model (legacy/import migration). No-op —
+    // Adopt any orphans to the resolved key (legacy/import migration). No-op —
     // and no persist — when there is nothing to adopt.
     if (key) {
       adoptOrphans(key, (snapshot, ver) => {
         pi.appendEntry("harness-state", { state: snapshot, version: ver });
       });
     }
-    // Read the injection policy from config (cached; tolerant). The default is
-    // ON — importance-ordered + bounded — so a growing harness never balloons
-    // the system prompt. Opt out via harness.json `injection.enabled: false`.
-    const { injection } = await loadConfig();
+  });
+
+  pi.on("context_with_system", async (event, ctx) => {
+    // NOTE: injection.enabled:false inside the config means LEGACY selection
+    // (all items, store order) — handled by selectForInjection, not an off
+    // switch here. There is no "no injection" render path once state exists.
+    const { injection, virtualBinding } = await loadConfig();
+    // Prefer the live resolution (mid-run responses can change the physical
+    // key under the "physical" policy); fall back to the cached agent-start
+    // key when the model is momentarily unknown.
+    const key =
+      resolveBindingKey(ctx.model, branchEntries(ctx), virtualBinding) ??
+      getActiveModelKey();
     const block = renderHarnessBlock(key, injection);
-    if (!block) return;
-    return { systemPrompt: event.systemPrompt + "\n" + block };
+    if (!block) return; // nothing to inject — do not own the transcript
+    const messages = [...event.messages];
+    const sys = messages[0] as { role?: string; content?: string | Array<{ type: string; text?: string }> } | undefined;
+    if (!sys || sys.role !== "system" || sys.content === undefined) return;
+    messages[0] = { ...sys, content: appendToSystemContent(sys.content, block) } as (typeof messages)[number];
+    return { messages };
   });
 }

package/src/proposer.ts

@@ -29,6 +29,7 @@
 
 import type { Delta, HarnessItem, HarnessState } from "./types.js";
 import type { HarnessConfig } from "./config.js";
+import type { ClassifyFn } from "./classify.js";
 
 /** Options for the one-shot model completion injected into ProposeInput. */
 export interface CompleteOptions {
@@ -81,6 +82,12 @@ export interface ProposeInput {
    *  and steering proposers ignore it. Undefined when no model is resolvable, so
    *  a model proposer can no-op (and record an audited failure) rather than throw. */
   complete?: (prompt: string, opts?: CompleteOptions) => Promise<CompleteResult>;
+  /** Batched yes/no classification (pi ≥ 0.99 classifier models), injected by
+   *  runRefine when `classifier.model` is configured and resolvable. The shipped
+   *  `dedupe` proposer uses it as a precision filter on candidate merge pairs;
+   *  other proposers may use it for cheap gating decisions. Undefined when no
+   *  classifier is available — consumers must degrade gracefully. */
+  classify?: ClassifyFn;
 }
 
 /** A single delta plus a human-readable reason for the audit trail. */
@@ -227,43 +234,33 @@ export function unionEvidence(sources: string[]): string {
 }
 
 /**
- * Pure dedupe planner: merges (or, with merge:false, drops) near-duplicate
- * ACTIVE items. Two items are duplicates iff they share the key fields —
- * kind, ownerModel, durable layer (scope+project) — and their content
- * similarity is >= opts.threshold. A similarity engine MAY abstain per pair
- * (see SimilarityResult): an abstaining pair is treated as NOT duplicates.
- *
- * Merge semantics (ACE-style deterministic merge, never a prose rewrite):
- * the higher-importance item is the KEEPER and keeps its content verbatim;
- * each keeper that absorbed duplicates gets ONE update whose evidence is the
- * line-wise union of its own and every absorbed duplicate's evidence (one
- * final union — applyOne replaces evidence wholesale, so per-duplicate
- * updates would clobber each other); each absorbed duplicate is deleted with
- * a reason naming its keeper. Updates are emitted before deletes.
- *
- * Greedy and contradiction-free: items are considered in importance-descending
- * order (ties keep store order); the first item is always a keeper, and each
- * later item is compared only against keepers, so a keeper is never
- * subsequently dropped. A duplicate matching several keepers joins the
- * best-overlap one.
+ * Pure dedupe grouping: the keeper/absorbed structure behind planDedupe.
+ * Exported (0.12.0) so the classifier-confirmed path can filter PAIRS before
+ * deltas are built — an async confirm cannot go through the sync `similarity`
+ * seam. See planDedupe for the matching semantics.
  */
-export function planDedupe(state: HarnessState, opts: DedupeOptions = DEFAULT_DEDUPE): ProposedDelta[] {
+export interface DedupeGroup {
+  keeper: HarnessItem;
+  absorbed: Array<{ dup: HarnessItem; overlap: number }>;
+}
+
+export function planDedupePairs(state: HarnessState, opts: DedupeOptions = DEFAULT_DEDUPE): DedupeGroup[] {
   const similarity = opts.similarity ?? tokenOverlap;
   const ordered = state.items
     .filter((i) => i.active)
     .sort((a, b) => b.importance - a.importance);
-  const keepers: Array<{ item: HarnessItem; absorbed: Array<{ dup: HarnessItem; overlap: number }> }> = [];
+  const keepers: DedupeGroup[] = [];
   for (const cand of ordered) {
-    let target: (typeof keepers)[number] | undefined;
+    let target: DedupeGroup | undefined;
     let best = 0;
     for (const k of keepers) {
-      if (k.item.kind !== cand.kind) continue;
+      if (k.keeper.kind !== cand.kind) continue;
       // Per-model isolation: each model keeps its own copy, so two near-
       // identical items bound to different models are NOT duplicates.
-      if (k.item.ownerModel !== cand.ownerModel) continue;
+      if (k.keeper.ownerModel !== cand.ownerModel) continue;
       // Same durable layer only (see durableLayer).
-      if (durableLayer(k.item) !== durableLayer(cand)) continue;
-      const { score: sim, abstain } = asSimilarity(similarity(k.item.content, cand.content));
+      if (durableLayer(k.keeper) !== durableLayer(cand)) continue;
+      const { score: sim, abstain } = asSimilarity(similarity(k.keeper.content, cand.content));
       // Abstain = keep both: an uncertain engine must never cause a merge.
       if (!abstain && sim >= opts.threshold && sim > best) {
         best = sim;
@@ -271,21 +268,25 @@ export function planDedupe(state: HarnessState, opts: DedupeOptions = DEFAULT_DE
       }
     }
     if (target) target.absorbed.push({ dup: cand, overlap: best });
-    else keepers.push({ item: cand, absorbed: [] });
+    else keepers.push({ keeper: cand, absorbed: [] });
   }
+  return keepers;
+}
 
+/** Build the update/delete deltas from keeper groups (see planDedupe). */
+export function deltasFromGroups(groups: DedupeGroup[], opts: DedupeOptions = DEFAULT_DEDUPE): ProposedDelta[] {
   const updates: ProposedDelta[] = [];
   const deletes: ProposedDelta[] = [];
-  for (const k of keepers) {
+  for (const k of groups) {
     if (k.absorbed.length === 0) continue;
     if (opts.merge) {
-      const merged = unionEvidence([k.item.evidence, ...k.absorbed.map((a) => a.dup.evidence)]);
+      const merged = unionEvidence([k.keeper.evidence, ...k.absorbed.map((a) => a.dup.evidence)]);
       // Skip the no-op: identical evidence → the merge degenerates to a plain
       // delete for this pair (no update delta).
-      if (merged !== k.item.evidence) {
+      if (merged !== k.keeper.evidence) {
         updates.push({
-          delta: { op: "update", id: k.item.id, evidence: merged },
-          rationale: `dedupe: merged ${k.absorbed.length} duplicate(s) (${k.absorbed.map((a) => a.dup.id).join(", ")}) into ${k.item.id}; evidence unioned (${k.absorbed.length + 1} sources).`,
+          delta: { op: "update", id: k.keeper.id, evidence: merged },
+          rationale: `dedupe: merged ${k.absorbed.length} duplicate(s) (${k.absorbed.map((a) => a.dup.id).join(", ")}) into ${k.keeper.id}; evidence unioned (${k.absorbed.length + 1} sources).`,
         });
       }
     }
@@ -295,23 +296,137 @@ export function planDedupe(state: HarnessState, opts: DedupeOptions = DEFAULT_DE
           op: "delete",
           id: dup.id,
           reason: opts.merge
-            ? `merged into ${k.item.id} (overlap ${overlap.toFixed(2)})`
-            : `near-duplicate of ${k.item.id} (overlap ${overlap.toFixed(2)})`,
+            ? `merged into ${k.keeper.id} (overlap ${overlap.toFixed(2)})`
+            : `near-duplicate of ${k.keeper.id} (overlap ${overlap.toFixed(2)})`,
         },
-        rationale: `dedupe: "${truncate(dup.content)}" ≈ keeper "${truncate(k.item.content)}" (Jaccard ${overlap.toFixed(2)}); ${opts.merge ? `merged into ${k.item.id}.` : `kept higher-importance ${k.item.id}.`}`,
+        rationale: `dedupe: "${truncate(dup.content)}" ≈ keeper "${truncate(k.keeper.content)}" (Jaccard ${overlap.toFixed(2)}); ${opts.merge ? `merged into ${k.keeper.id}.` : `kept higher-importance ${k.keeper.id}.`}`,
       });
     }
   }
   return [...updates, ...deletes];
 }
 
+/**
+ * Pure dedupe planner: merges (or, with merge:false, drops) near-duplicate
+ * ACTIVE items. Two items are duplicates iff they share the key fields —
+ * kind, ownerModel, durable layer (scope+project) — and their content
+ * similarity is >= opts.threshold. A similarity engine MAY abstain per pair
+ * (see SimilarityResult): an abstaining pair is treated as NOT duplicates.
+ *
+ * Merge semantics (ACE-style deterministic merge, never a prose rewrite):
+ * the higher-importance item is the KEEPER and keeps its content verbatim;
+ * each keeper that absorbed duplicates gets ONE update whose evidence is the
+ * line-wise union of its own and every absorbed duplicate's evidence (one
+ * final union — applyOne replaces evidence wholesale, so per-duplicate
+ * updates would clobber each other); each absorbed duplicate is deleted with
+ * a reason naming its keeper. Updates are emitted before deletes.
+ *
+ * Greedy and contradiction-free: items are considered in importance-descending
+ * order (ties keep store order); the first item is always a keeper, and each
+ * later item is compared only against keepers, so a keeper is never
+ * subsequently dropped. A duplicate matching several keepers joins the
+ * best-overlap one.
+ */
+export function planDedupe(state: HarnessState, opts: DedupeOptions = DEFAULT_DEDUPE): ProposedDelta[] {
+  return deltasFromGroups(planDedupePairs(state, opts), opts);
+}
+
+// ---- classifier confirmation (pi ≥ 0.99, opt-in via classifier.model) ------
+
+/** Recall widening for the classifier pass: candidates are gathered at
+ *  threshold - CLASSIFIER_RECALL_DROP (floored) so the cheap yes/no filter,
+ *  not the token overlap, is the precision gate. */
+export const CLASSIFIER_RECALL_DROP = 0.15;
+export const CLASSIFIER_RECALL_FLOOR = 0.35;
+/** Bound on pairs per classify call (question count), keeping the call cheap. */
+export const CLASSIFIER_MAX_PAIRS = 20;
+
+/** Build the batched pair-confirmation request. Pure — unit-testable. */
+export function buildPairQuestions(
+  pairs: Array<{ keeper: HarnessItem; dup: HarnessItem }>,
+): { state: Record<string, unknown>; questions: Record<string, { instructions: string; trueCriteria: string; falseCriteria: string }> } {
+  const questions: Record<string, { instructions: string; trueCriteria: string; falseCriteria: string }> = {};
+  const state = {
+    pairs: pairs.map((p, i) => ({ index: i, keeper: p.keeper.content, duplicate: p.dup.content })),
+  };
+  for (let i = 0; i < pairs.length; i++) {
+    questions[`p${i}`] = {
+      instructions:
+        "You are confirming dedupe candidates for a coding agent's self-improvement store. Each pair holds two items (a keeper and a candidate duplicate). Do the two items state the SAME durable lesson, fact, or instruction — such that keeping both is redundant?",
+      trueCriteria: "The two items express the same reusable information; one merged copy loses nothing.",
+      falseCriteria:
+        "The items differ in scope, condition, or meaning — both must be kept, or the token overlap is only superficial.",
+    };
+  }
+  return { state, questions };
+}
+
+/** Filter keeper groups down to classifier-confirmed pairs. Pairs beyond the
+ *  question cap and pairs with missing answers stay OUT (conservative: an
+ *  unanswered pair is never merged). Answers are keyed p0..pN in the same
+ *  groups.flatMap(absorbed) order buildPairQuestions enumerated. */
+export function confirmGroups(
+  groups: DedupeGroup[],
+  answers: Record<string, { value: boolean; confidence?: number }>,
+  cap: number = CLASSIFIER_MAX_PAIRS,
+): DedupeGroup[] {
+  let i = 0;
+  return groups
+    .map((g) => ({
+      keeper: g.keeper,
+      absorbed: g.absorbed.filter(() => i < cap && answers[`p${i++}`]?.value === true),
+    }))
+    .filter((g) => g.absorbed.length > 0);
+}
+
 /** Rule-based proposer wrapping planDedupe with the configured (or default)
- *  options — merges near-duplicates; `merge: false` restores delete-only. */
+ *  options — merges near-duplicates; `merge: false` restores delete-only.
+ *  When a classifier is injected (harness.json `classifier.model` resolved),
+ *  candidate pairs are recall-widened and then confirmed by ONE batched
+ *  yes/no classify call: only confirmed pairs merge. A classifier error falls
+ *  back to the pure rule-based plan — the classifier can narrow, never block. */
 export const dedupeProposer: DeltaProposer = {
   name: "dedupe",
-  async propose({ state, config }): Promise<ProposeResult> {
-    const deltas = planDedupe(state, config?.dedupe ?? DEFAULT_DEDUPE);
-    return deltas.length ? { deltas } : {};
+  async propose({ state, config, classify }): Promise<ProposeResult> {
+    const opts = config?.dedupe ?? DEFAULT_DEDUPE;
+    if (!classify) {
+      const deltas = planDedupe(state, opts);
+      return deltas.length ? { deltas } : {};
+    }
+    const started = Date.now();
+    const recall: DedupeOptions = {
+      ...opts,
+      threshold: Math.max(CLASSIFIER_RECALL_FLOOR, opts.threshold - CLASSIFIER_RECALL_DROP),
+    };
+    const groups = planDedupePairs(state, recall);
+    const pairs = groups.flatMap((g) => g.absorbed.map((a) => ({ keeper: g.keeper, dup: a.dup })));
+    if (pairs.length === 0) return {};
+    const capped = pairs.slice(0, CLASSIFIER_MAX_PAIRS);
+    const res = await classify(buildPairQuestions(capped));
+    if (!res.ok) {
+      // Classifier failed → plain rule-based pass at the configured threshold.
+      const deltas = planDedupe(state, opts);
+      return {
+        ...(deltas.length ? { deltas } : {}),
+        modelCall: {
+          ok: false,
+          latencyMs: Date.now() - started,
+          ...(res.error ? { error: res.error } : {}),
+          ...(res.model ? { model: res.model } : {}),
+        },
+      };
+    }
+    const confirmed = confirmGroups(groups, res.answers);
+    const deltas = deltasFromGroups(confirmed, opts);
+    return {
+      ...(deltas.length ? { deltas } : {}),
+      modelCall: {
+        ok: true,
+        latencyMs: Date.now() - started,
+        ...(res.model ? { model: res.model } : {}),
+        ...(res.usage ? { inputTokens: res.usage.input, outputTokens: res.usage.output } : {}),
+      },
+    };
   },
 };
 

package/src/refine.ts

@@ -19,9 +19,11 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Context, Model, TextContent } from "@earendil-works/pi-ai";
-import { applyDeltas, DEFAULT_DURABLE_PATH, exportDurableLayers, modelKey, PROJECT_DURABLE_DIR, REFINE_ENTRY, snapshotState } from "./store.js";
+import { applyDeltas, DEFAULT_DURABLE_PATH, exportDurableLayers, PROJECT_DURABLE_DIR, REFINE_ENTRY, snapshotState } from "./store.js";
 import { getProposer, DEFAULT_DEDUPE } from "./proposer.js";
 import type { CompleteOptions, CompleteResult } from "./proposer.js";
+import { buildClassify } from "./classify.js";
+import { resolveBindingKey, branchEntries } from "./vmodel.js";
 import type { AppliedDelta } from "./types.js";
 import { loadConfig, projectSlug } from "./config.js";
 
@@ -67,6 +69,13 @@ export interface RefineOptions {
    *  (overrides `dedupe.threshold` in harness.json). Affects the rule-based
    *  `dedupe` proposer; ignored by others. */
   threshold?: number;
+  /** How a steering message is delivered (pi ≥ 0.87 actionable boundaries).
+ *  "steer" (default): send it as a user message via sendUserMessage — the
+   *  manual /refine path. "boundary": do NOT send; return it in RefineResult
+   *  so a turn_end caller can persist it as a structural entry and guarantee
+   *  one next provider request with `{ entries, continue: true }` — no
+   *  steering queue, no follow-up scheduling side effects. */
+  delivery?: "steer" | "boundary";
 }
 
 export interface RefineResult {
@@ -78,6 +87,10 @@ export interface RefineResult {
   proposer: string;
   /** Deltas the proposer applied directly (0 for the steering path). */
   applied: number;
+  /** Set ONLY with delivery "boundary" when the proposer returned a steering
+   *  message: the message was NOT sent — the caller owns persisting it (e.g.
+   *  as a turn_end boundary draft) and ensuring the continuation. */
+  steeringMessage?: string;
 }
 
 /**
@@ -109,6 +122,9 @@ export async function runRefine(
   // Inject a one-shot model completion (built from ctx) so dedicated-model
   // proposers can make a hidden LLM call. Undefined when no model is resolvable.
   const complete = buildComplete(ctx);
+  // Inject the classifier adapter when `classifier.model` is configured and
+  // resolvable (pi ≥ 0.99) — the dedupe proposer uses it to confirm merges.
+  const classify = buildClassify(ctx, config.classifier?.model);
   // Pass a defensive copy: proposers are a public extension point and must not
   // be able to mutate the live store outside applyDeltas (no audit / no rollback).
   const result = await proposer.propose({
@@ -117,13 +133,14 @@ export async function runRefine(
     lookback,
     config: proposerConfig,
     ...(complete ? { complete } : {}),
+    ...(classify ? { classify } : {}),
   });
   const proposedDeltas = result.deltas ?? [];
   // Stamp direct-apply create deltas with the active model so proposer-authored
   // notes bind to the model driving the turn (the steering path is stamped in
   // the harness_mutate tool instead). Orphans result only when the model is
   // unknown; before_agent_start adopts them on the next turn.
-  const ownerKey = modelKey(ctx.model);
+  const ownerKey = resolveBindingKey(ctx.model, branchEntries(ctx), config.virtualBinding);
 
   let applied = 0;
   let appliedDeltas: AppliedDelta[] = [];
@@ -194,7 +211,12 @@ export async function runRefine(
   }
 
   if (result.steeringMessage) {
-    pi.sendUserMessage(result.steeringMessage);
+    if (options.delivery === "boundary") {
+      // Caller owns delivery: persist as a structural boundary entry and
+      // continue — see auto-refine.ts. Returned via RefineResult.
+    } else {
+      pi.sendUserMessage(result.steeringMessage);
+    }
   }
   ctx.ui.setStatus("harness", undefined);
   return {
@@ -204,6 +226,7 @@ export async function runRefine(
     source,
     proposer: proposer.name,
     applied,
+    ...(options.delivery === "boundary" && result.steeringMessage ? { steeringMessage: result.steeringMessage } : {}),
   };
 }
 
@@ -237,7 +260,7 @@ function parseArgs(args: string): {
   return { lookback, commit, proposer, threshold, thresholdInvalid };
 }
 
-function gatherEvidence(ctx: ExtensionContext, lookback: number): string {
+export function gatherEvidence(ctx: ExtensionContext, lookback: number): string {
   const entries = ctx.sessionManager.getBranch() as AnyEntry[];
   const messages = entries.filter((e) => e.type === "message" && e.message);
   const recent = messages.slice(-lookback * 2); // ~2 entries per turn (user+assistant)

package/src/tools.ts

@@ -55,6 +55,34 @@ const DeleteShape = Type.Object({
 
 const DeltaShape = Type.Union([CreateShape, UpdateShape, DeleteShape]);
 
+// outputSchema (pi ≥ 0.99): codemode scripts and ctx.executeTool() callers get
+// structuredContent instead of the text; the model still sees `content`.
+const ItemSchema = Type.Object({
+  id: Type.String(),
+  kind: StringEnum(KIND_VALUES),
+  content: Type.String(),
+  evidence: Type.String(),
+  importance: Type.Number(),
+  active: Type.Boolean(),
+  ownerModel: Type.String(),
+  scope: Type.Optional(StringEnum(["global", "project"])),
+  project: Type.Optional(Type.String()),
+  createdAt: Type.Number(),
+  updatedAt: Type.Number(),
+});
+
+const ListOutputSchema = Type.Object({
+  count: Type.Number(),
+  items: Type.Array(ItemSchema),
+});
+
+const MutateOutputSchema = Type.Object({
+  applied: Type.Number(),
+  created: Type.Number(),
+  updated: Type.Number(),
+  deleted: Type.Number(),
+});
+
 export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "harness_list",
@@ -74,6 +102,7 @@ export function registerTools(pi: ExtensionAPI): void {
         }),
       ),
     }),
+    outputSchema: ListOutputSchema,
     async execute(_toolCallId, params) {
       const kind = params.kind as ComponentKind | undefined;
       const modelFilter = params.model as string | undefined;
@@ -103,6 +132,22 @@ export function registerTools(pi: ExtensionAPI): void {
           },
         ],
         details: { count: items.length, items },
+        structuredContent: {
+          count: items.length,
+          items: items.map((i) => ({
+            id: i.id,
+            kind: i.kind,
+            content: i.content,
+            evidence: i.evidence,
+            importance: i.importance,
+            active: i.active,
+            ownerModel: i.ownerModel,
+            ...(i.scope ? { scope: i.scope } : {}),
+            ...(i.project ? { project: i.project } : {}),
+            createdAt: i.createdAt,
+            updatedAt: i.updatedAt,
+          })),
+        },
       };
     },
   });
@@ -119,6 +164,7 @@ export function registerTools(pi: ExtensionAPI): void {
     parameters: Type.Object({
       deltas: Type.Array(DeltaShape, { minItems: 1, maxItems: 20 }),
     }),
+    outputSchema: MutateOutputSchema,
     async execute(_toolCallId, params) {
       const incoming = params.deltas as Delta[];
       // The active model is the ACTOR: creates bind to it, and update/delete are
@@ -133,9 +179,13 @@ export function registerTools(pi: ExtensionAPI): void {
         getActiveModelKey(),
       );
       const summary = summarize(applied);
+      const created = applied.filter((a) => a.op === "create").length;
+      const updated = applied.filter((a) => a.op === "update").length;
+      const deleted = applied.filter((a) => a.op === "delete").length;
       return {
         content: [{ type: "text", text: summary }],
         details: { applied, version: getState().items.length },
+        structuredContent: { applied: applied.length, created, updated, deleted },
       };
     },
   });

package/src/vmodel.ts

@@ -0,0 +1,88 @@
+// Virtual-model binding policy (pi ≥ 0.99). A virtual model (pi.registerVirtualModel,
+// e.g. a Jev router) appears as its own catalog entry with api "pi-virtual"; ctx.model
+// names the VIRTUAL model, while each assistant response names the PHYSICAL model it
+// was routed to. Strict per-model isolation therefore has two defensible keys:
+//
+//   "virtual"  (default, pre-0.12 behavior): key = the selected model's provider/id,
+//              virtual or physical. One harness per selection; switching to a router
+//              starts a blank harness even if it always routes to the same model.
+//   "physical" (opt-in): when the selected model is virtual, key = the physical model
+//              of the latest successful response on the branch (pi's own
+//              findLatestResponse semantics: failed/aborted responses are skipped).
+//              Items accumulated under the physical model keep injecting through a
+//              router; when the router switches physical models mid-conversation the
+//              key changes and isolation applies exactly as after a manual switch.
+//              Before the first response on a branch there is no physical key yet:
+//              the binding resolves to undefined, so creates become orphans and are
+//              adopted by the resolved key on the next contact (the existing
+//              adoption machinery — no special-casing needed).
+//
+// Kept dependency-free and local: pi exports the virtual-model constants from its
+// package entry only partially, and these helpers are tiny (the api id is a stable
+// public constant, "pi-virtual").
+
+import type { VirtualBinding } from "./config.js";
+
+/** pi's public constant for virtual catalog entries (VIRTUAL_MODEL_API). */
+export const VIRTUAL_MODEL_API = "pi-virtual";
+
+/** Minimal structural shapes so tests can build fakes without pi types. */
+interface ModelLike {
+  provider?: string;
+  id?: string;
+  api?: string;
+}
+
+interface AssistantLike {
+  role?: string;
+  provider?: string;
+  model?: string;
+}
+
+/** Whether a model object names a virtual (router) catalog entry. */
+export function isVirtualModel(m?: ModelLike): boolean {
+  return m?.api === VIRTUAL_MODEL_API;
+}
+
+/**
+ * Key of the physical model behind the latest SUCCESSFUL response on a branch.
+ * Scans message entries backwards; failed/aborted responses do not produce
+ * assistant message entries that reach the branch tail, matching pi's
+ * findLatestResponse contract closely enough for binding purposes.
+ * Returns undefined when no assistant response exists yet.
+ */
+export function physicalKeyFromBranch(entries: Iterable<unknown>): string | undefined {
+  const msgs: AssistantLike[] = [];
+  for (const e of entries as Array<{ type?: string; message?: AssistantLike }>) {
+    if (e?.type === "message" && e.message?.role === "assistant") msgs.push(e.message);
+  }
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i]!;
+    if (m.provider && m.model) return `${m.provider}/${m.model}`;
+  }
+  return undefined;
+}
+
+/** Canonical owner key, mirroring store.modelKey with optional-field guards. */
+function plainKey(m?: ModelLike): string | undefined {
+  return m?.provider && m?.id ? `${m.provider}/${m.id}` : undefined;
+}
+
+/** Defensive branch access: test fakes build minimal ctx without a session
+ *  manager; production always has one. */
+export function branchEntries(ctx: { sessionManager?: { getBranch?: () => unknown[] } }): unknown[] {
+  return ctx.sessionManager?.getBranch?.() ?? [];
+}
+
+/**
+ * Resolve the harness binding key under the configured policy. `entries` is the
+ * session branch (used only for the "physical" policy); pass [] when unknown.
+ */
+export function resolveBindingKey(
+  model: ModelLike | undefined,
+  entries: Iterable<unknown>,
+  policy: VirtualBinding = "virtual",
+): string | undefined {
+  if (policy !== "physical" || !isVirtualModel(model)) return plainKey(model);
+  return physicalKeyFromBranch(entries);
+}