pi-continual-harness 0.7.0 → 0.8.1

package/README.md

@@ -67,6 +67,9 @@ Durable I/O (round-trip with pi-reflect):
 /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
 existing entry are updated (offline edits win on content/evidence/importance),
 new entries are created. By default nothing is deleted — `--prune` also drops
@@ -116,6 +119,7 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
 {
   "durableScope": "global",
   "proposer": "steering",
+  "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 }
@@ -126,6 +130,11 @@ Optional config at `~/.pi/agent/harness.json` (missing or malformed → defaults
   `~/.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.
+- **`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
+  10) per kind and `maxTokens` (default 1500) total. Set `enabled: false` to
+  restore the legacy "inject all items, in store order" behaviour.
 - **`proposer`** — which delta proposer `/refine` and auto-refine use. Defaults
   to `steering` (the agent reasons via a steering message). `dedupe` applies a
   rule-based dedupe directly. See [Proposers](#proposers).
@@ -204,6 +213,47 @@ In particular, `/harness push-mem` pushes *every* model's active items into
 pi-mem by default (which can yield near-duplicate memories across models); pass
 `--model <provider/id|active>` to scope it to one model.
 
+## Injection selection (on by default)
+
+The harness ACCUMULATES notes (create / refine / auto-refine / outcome-promotion),
+but the system prompt is finite. So since 0.8 the block appended each turn is the
+result of a **selection policy**, not the whole store — and it is **on by
+default**. The store itself is never changed by selection (nothing is lost);
+only what is *surfaced* changes.
+
+The policy (pure, deterministic; `src/select.ts`):
+
+1. **Filter** — only active items bound to the active model (strict per-model
+   isolation, unchanged).
+2. **Order** — importance desc; ties keep store/insertion order (stable). The
+   highest-fitness notes lead each section.
+3. **Cap** — `maxPerKind` (default 10: balanced sections, no single kind drowns
+   the block), then `maxTokens` (default 1500: total budget). The budget is
+   filled **round-robin across kinds by importance rank**, so one kind cannot
+   starve the others; within that order an item that doesn't fit is **skipped**
+   (not a hard stop), so a large item never blocks smaller higher-priority ones.
+
+The defaults are deliberately generous — a **no-op for small stores** (nothing
+trimmed) and protective as the harness grows. When the policy drops items, the
+block ends with a one-line transparency note:
+
+```
+_(3 item(s) not shown — below the injection budget. Raise `injection.maxTokens`/`maxPerKind` in harness.json or run `/harness prune`.)_
+```
+
+Tune or disable it in `harness.json`:
+
+```json
+{ "injection": { "maxTokens": 3000, "maxPerKind": 20 } }   // raise the ceiling
+{ "injection": { "maxPerKind": 5 } }                        // trim harder, per kind
+{ "injection": { "enabled": false } }                       // opt out: legacy "all, in order"
+```
+
+Selection is factored into a pure function (`selectForInjection`) and
+re-exported from the package entry, so a companion package can layer richer
+policies (e.g. relevance to the current turn, via the shared `tokenize` /
+`tokenOverlap` helpers) without touching `inject.ts`.
+
 ## Proposers
 
 `/refine` is split into two stages: **propose** (given evidence + state, decide
@@ -263,7 +313,7 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 
 ## Status
 
-0.7.x. Implemented:
+0.8.x. Implemented:
 
 - Unified harness-state store with branch-local snapshots (`/tree` rollback).
 - Online `/refine` + `harness_mutate` / `harness_list` tools.
@@ -282,6 +332,10 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
   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.
+- **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.
 
 Open extension points (see `docs/ROADMAP.md`):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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

@@ -14,6 +14,7 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { DEFAULT_DURABLE_PATH } from "./store.js";
+import { DEFAULT_INJECTION, normalizeInjection, type NormalizedInjection } from "./select.js";
 
 export const DEFAULT_EVERY_TURNS = 50;
 export const DEFAULT_AUTO_EVERY_TURNS = 100;
@@ -39,6 +40,9 @@ export interface HarnessConfig {
     enabled?: boolean;
     bump?: number;
   };
+  /** Injection selection policy (on by default). Resolved by loadConfig, so the
+   *  value here is always fully-populated. See src/select.ts. */
+  injection?: NormalizedInjection;
 }
 
 export const DEFAULT_CONFIG: HarnessConfig = {
@@ -47,6 +51,10 @@ export const DEFAULT_CONFIG: HarnessConfig = {
   autoRefine: { enabled: false, everyTurns: DEFAULT_AUTO_EVERY_TURNS, commit: false },
   proposer: "steering",
   outcomeImportance: { enabled: false, bump: DEFAULT_REF_BUMP },
+  // ON by default: importance-ordered, maxPerKind 10, maxTokens 1500. A no-op
+  // for small stores; protective as the harness accumulates. Opt out with
+  // `injection.enabled: false`. See src/select.ts.
+  injection: DEFAULT_INJECTION,
 };
 
 export const CONFIG_PATH = join(homedir(), ".pi", "agent", "harness.json");
@@ -71,6 +79,10 @@ function mergeConfig(over: Partial<HarnessConfig>): HarnessConfig {
       enabled: over.outcomeImportance?.enabled ?? false,
       bump: coerceBump(over.outcomeImportance?.bump),
     },
+    // normalizeInjection is defensive (bad types → defaults), so a partial or
+    // malformed `injection` object degrades to the shipped defaults rather than
+    // corrupting the block sizing arithmetic.
+    injection: normalizeInjection(over.injection as Partial<{ enabled: boolean; maxTokens: number; maxPerKind: number; charsPerToken: number }> | undefined),
   };
 }
 

package/src/harness.ts

@@ -4,6 +4,10 @@
 //   /harness export [path]               write active items to a markdown file
 //   /harness import [--prune] [path]     parse it back and merge (durable wins)
 //
+// The command registers getArgumentCompletions so the TUI offers a filtered
+// menu of subcommands (and, one level deeper, flags / item ids / kinds) 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
@@ -23,15 +27,152 @@ import {
   reconstructFromDurable,
 } from "./store.js";
 import { loadConfig, resolveDurablePath } from "./config.js";
+import { KIND_LABEL } from "./types.js";
 import type { ComponentKind, HarnessItem } from "./types.js";
 
+/** One row of the /harness subcommand menu (label = name, value = name). */
+interface CompletionEntry {
+  name: string;
+  description: string;
+}
+
+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: "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: "push-mem", description: "Persist active items to pi-mem (--all, --kind, --model)" },
+];
+
+const KINDS: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
+
+/** Flags each subcommand accepts, in menu order. */
+const FLAGS: Record<string, CompletionEntry[]> = {
+  import: [{ name: "--prune", description: "Drop live items missing from the durable file" }],
+  prune: [{ name: "--decay", description: "Decay items not updated for <days> before pruning" }],
+  "push-mem": [
+    { name: "--all", description: "Push every active item, not just memories" },
+    { name: "--kind", description: `Limit to one kind (${KINDS.join("|")})` },
+    { name: "--model", description: "Limit to one owner model (provider/id or \"active\")" },
+  ],
+};
+
+function preview(text: string, max = 60): string {
+  // Single line + truncated so the menu row stays readable.
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+/**
+ * Argument autocomplete for /harness (pi calls this with the FULL text after
+ * the command name; a selected item's `value` REPLACES that whole text, so
+ * multi-token rows re-emit the tokens already typed). Two levels:
+ *
+ *   /harness <partial-subcommand>      → matching subcommands
+ *   /harness <sub> …<partial-token>    → flags / ids / kind+model values for sub
+ *
+ * Returns null where a menu would only get in the way (path arguments,
+ * numeric flag values, unknown subcommands) so the editor falls back to its
+ * own behavior.
+ */
+function completions(argumentPrefix: string) {
+  // Level 1 — still typing the first token: the subcommand menu.
+  if (!/\s/.test(argumentPrefix)) {
+    const q = argumentPrefix.toLowerCase();
+    return filterSubcommands(q);
+  }
+  const tokens = argumentPrefix.trim().split(/\s+/).filter(Boolean);
+  // Fresh token (trailing whitespace) → the token being completed is "";
+  // otherwise it is the last typed token. `before` are the committed ones.
+  const fresh = argumentPrefix !== argumentPrefix.trimEnd();
+  const last = fresh ? "" : (tokens.at(-1) ?? "");
+  const before = fresh ? tokens : tokens.slice(0, -1);
+
+  // A stray leading space ("/harness  imp") still means level 1, matching the
+  // handler's tolerant split.
+  if (before.length === 0) return filterSubcommands(last.toLowerCase());
+
+  const sub = before[0]!.toLowerCase();
+  // Flag-value completion: the token right before the one being typed.
+  const prev = before.at(-1)!;
+  if (prev === "--kind" && sub === "push-mem") {
+    return filterValues(
+      KINDS.map((k) => ({ value: k, description: KIND_LABEL[k] })),
+      last,
+      before,
+    );
+  }
+  if (prev === "--model" && sub === "push-mem") {
+    const owners = [...new Set(getState().items.filter((i) => i.active && i.ownerModel).map((i) => i.ownerModel))];
+    return filterValues(
+      [
+        { value: "active", description: "The model driving this command" },
+        ...owners.map((m) => ({ value: m, description: "Items owned by this model" })),
+      ],
+      last,
+      before,
+    );
+  }
+
+  // Flag completion ("--…" prefix, or a fresh token for flag-taking subs).
+  // A fresh --kind/--model value was already completed above (early return),
+  // so a fresh token here means "offer the remaining flags".
+  if (last.startsWith("--") || (fresh && sub in FLAGS)) {
+    const used = new Set(before.filter((t) => t.startsWith("--")));
+    const rows = (FLAGS[sub] ?? []).filter((f) => !used.has(f.name));
+    const items = rows
+      .filter((f) => f.name.startsWith(last))
+      .map((f) => ({ value: [...before, f.name].join(" "), label: f.name, description: f.description }));
+    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
+    const items = getState()
+      .items.filter((i) => i.active && i.id.startsWith(last))
+      .map((i: HarnessItem) => ({
+        value: [...before, i.id].join(" "),
+        label: i.id,
+        description: `${i.kind} · ${preview(i.content)}`,
+      }));
+    return items.length > 0 ? items : null;
+  }
+
+  // Everything else is a path/number/free-text argument — no menu.
+  return null;
+}
+
+function filterSubcommands(prefix: string) {
+  const items = SUBCOMMANDS.filter((s) => s.name.startsWith(prefix)).map((s) => ({
+    value: s.name,
+    label: s.name,
+    description: s.description,
+  }));
+  return items.length > 0 ? items : null;
+}
+
+/** Flag-value completion: `value` = committed tokens + the chosen value. */
+function filterValues(
+  rows: Array<{ value: string; description: string }>,
+  prefix: string,
+  before: string[],
+) {
+  const items = rows
+    .filter((r) => r.value.startsWith(prefix))
+    .map((r) => ({ value: [...before, r.value].join(" "), label: r.value, description: r.description }));
+  return items.length > 0 ? items : null;
+}
+
 export function registerHarness(pi: ExtensionAPI): void {
   pi.registerCommand("harness", {
     description:
-      "Durable harness-state I/O + importance hygiene. Subcommands: " +
-      "import [--prune] [path] · export [path] · status [path] · " +
-      "prune [--decay <days>] · keep <id> · drop <id> · " +
-      "push-mem [--all|--kind <kind>|--model <provider/id|active>] (persist active items to pi-mem).",
+      "Durable harness-state I/O + importance hygiene " +
+      "(import · export · status · prune · keep · drop · push-mem — " +
+      "subcommands autocomplete as you type)",
     handler: async (args, ctx) => {
       const parts = args.trim().split(/\s+/).filter(Boolean);
       const sub = (parts[0] ?? "status").toLowerCase();
@@ -61,6 +202,7 @@ export function registerHarness(pi: ExtensionAPI): void {
           return;
       }
     },
+    getArgumentCompletions: (argumentPrefix) => completions(argumentPrefix),
   });
 }
 

package/src/index.ts

@@ -74,3 +74,16 @@ export {
   type ProposedDelta,
   type ProposeResult,
 } from "./proposer.js";
+
+// Injection selection policy (on by default). Re-exported so companion packages
+// and tests can reuse the pure selection/normalization without reaching into
+// internal paths.
+export {
+  DEFAULT_INJECTION,
+  estimateTokens,
+  normalizeInjection,
+  selectForInjection,
+  type InjectionConfig,
+  type NormalizedInjection,
+  type SelectionResult,
+} from "./select.js";

package/src/inject.ts

@@ -8,13 +8,18 @@
 // 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.
+//
+// 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
+// the block stays bounded as the harness accumulates. Configurable / opt-out via
+// 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 { KIND_ORDER, selectForInjection, type InjectionConfig } from "./select.js";
+import { loadConfig } from "./config.js";
 import type { ComponentKind } from "./types.js";
 
-const ORDER: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
-
 const TITLES: Record<ComponentKind, string> = {
   prompt: "Self-improved prompt notes",
   memory: "Remembered facts",
@@ -23,34 +28,46 @@ const TITLES: Record<ComponentKind, string> = {
 };
 
 /**
- * Render the harness block for a single model. Only active items whose
- * ownerModel === ownerKey are included. An undefined ownerKey (no active model)
- * renders nothing — isolation is strict: unknown model → inject nothing.
+ * Render the harness block for a single model. Selection (`cfg`) defaults to the
+ * shipped policy when omitted — importance-ordered, capped per kind and by a
+ * total token budget (see select.ts). Only active items whose ownerModel ===
+ * ownerKey are ever considered. An undefined ownerKey (no active model) renders
+ * nothing — isolation is strict: unknown model → inject nothing.
  */
-export function renderHarnessBlock(ownerKey?: string): string {
+export function renderHarnessBlock(ownerKey?: string, cfg?: InjectionConfig): string {
   if (ownerKey === undefined) return "";
-  const state = getState();
-  if (state.items.length === 0) return "";
+  const items = getState().items;
+  if (items.length === 0) return "";
+
+  const { selected, omitted } = selectForInjection(items, ownerKey, cfg);
+  if (selected.length === 0) return "";
 
   const sections: string[] = [];
-  for (const kind of ORDER) {
-    const items = state.items.filter((i) => i.kind === kind && i.active && i.ownerModel === ownerKey);
-    if (items.length === 0) continue;
-    const bullets = items
-      .map((i) => `- [${i.id}] ${i.content}`)
-      .join("\n");
+  for (const kind of KIND_ORDER) {
+    const forKind = selected.filter((i) => i.kind === kind);
+    if (forKind.length === 0) continue;
+    const bullets = forKind.map((i) => `- [${i.id}] ${i.content}`).join("\n");
     sections.push(`### ${TITLES[kind]}\n${bullets}`);
   }
   if (sections.length === 0) return "";
 
-  return [
+  const lines = [
     "",
     "## Continual Harness state",
     "Self-improved notes accumulated from past trajectories via /refine.",
     "Treat these as durable working context. Update them with the harness_mutate tool when they are wrong or stale.",
     "",
     sections.join("\n\n"),
-  ].join("\n");
+  ];
+  // Transparency: when the selection policy dropped items, say so — the block is
+  // bounded on purpose, and the user should know the store has more than shows.
+  if (omitted > 0) {
+    lines.push(
+      "",
+      `_(${omitted} item(s) not shown — below the injection budget. Raise \`injection.maxTokens\`/\`maxPerKind\` in harness.json or run \`/harness prune\`.)_`,
+    );
+  }
+  return lines.join("\n");
 }
 
 export function registerInjection(pi: ExtensionAPI): void {
@@ -65,7 +82,11 @@ export function registerInjection(pi: ExtensionAPI): void {
         pi.appendEntry("harness-state", { state: snapshot, version: ver });
       });
     }
-    const block = renderHarnessBlock(key);
+    // 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();
+    const block = renderHarnessBlock(key, injection);
     if (!block) return;
     return { systemPrompt: event.systemPrompt + "\n" + block };
   });

package/src/select.ts

@@ -0,0 +1,184 @@
+// Injection selection policy: WHICH active items for the active model get
+// surfaced in the system-prompt block, and in what order.
+//
+// The harness ACCUMULATES notes (create / refine / auto-refine /
+// outcome-promotion), but the system prompt is a finite resource. Without
+// selection, every active item for the model is injected every turn, unbounded —
+// so a long-running session's prompt grows without limit and the most valuable
+// notes compete with the least for attention. Selection is ON BY DEFAULT with
+// conservative knobs that are a NO-OP for small stores (nothing trimmed) and
+// protective for large ones. Opt out entirely with `injection.enabled = false`
+// → legacy "all items, in store order".
+//
+// Policy (pure, deterministic, unit-tested in test/select.test.ts):
+//   1. FILTER — active items bound to the active model (strict per-model
+//      isolation, same rule inject.ts always enforced).
+//   2. ORDER  — importance desc; ties keep store/insertion order (stable), so
+//      the highest-fitness notes lead each section.
+//   3. CAP    — `maxPerKind` (balanced sections: no single kind drowns the
+//      block), then `maxTokens` (total budget). The budget is filled
+//      round-robin across kinds by importance rank, so one kind cannot starve
+//      the others; within that order an item that does not fit is *skipped*
+//      (not a hard stop), so a single large item never blocks smaller
+//      higher-priority ones after it.
+//
+// Kept pure + side-effect-free on purpose: inject.ts is thin glue over this, and
+// the decision is fully unit-testable without a live pi runtime (the same
+// factoring pattern remind.ts / auto-refine.ts / outcome.ts use).
+
+import type { ComponentKind, HarnessItem } from "./types.js";
+
+/** Canonical kind order (shared with inject.ts so there is one source of truth). */
+export const KIND_ORDER: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
+
+/** User-facing injection config (all optional; defaults applied on read). */
+export interface InjectionConfig {
+  /** Master switch. `false` → selection disabled (legacy: inject all, in store
+   *  order). Default `true`. */
+  enabled?: boolean;
+  /** Max total tokens (≈ chars / charsPerToken) for the rendered block,
+   *  including the intro + section headers + items. Default 1500. */
+  maxTokens?: number;
+  /** Max items surfaced per kind. Default 10. */
+  maxPerKind?: number;
+  /** Token estimate: characters per token. Default 4. */
+  charsPerToken?: number;
+}
+
+/** Fully-resolved injection config (post-defaults; what loadConfig returns). */
+export interface NormalizedInjection {
+  enabled: boolean;
+  maxTokens: number;
+  maxPerKind: number;
+  charsPerToken: number;
+}
+
+/** The shipped defaults — ON, but generous enough to never trim a small store. */
+export const DEFAULT_INJECTION: NormalizedInjection = {
+  enabled: true,
+  maxTokens: 1500,
+  maxPerKind: 10,
+  charsPerToken: 4,
+};
+
+// Token-overhead estimates for the parts of the rendered block that are not item
+// text, so the budget reflects the real appended size (see inject.ts). These are
+// deliberately rough heuristics; the goal is a meaningful ceiling, not exactness.
+const INTRO_TOKENS = 55; // "## Continual Harness state" + the two description lines
+const SECTION_HEADER_TOKENS = 8; // "### <title>" per present section
+const FOOTER_TOKENS = 18; // the omitted-count footer, when it renders
+
+/** Resolve a (possibly partial / absent / malformed) config against the defaults.
+ *  Defensive: bad types fall back to defaults, never throws. */
+export function normalizeInjection(cfg?: Partial<InjectionConfig>): NormalizedInjection {
+  const num = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v > 0;
+  return {
+    enabled: typeof cfg?.enabled === "boolean" ? cfg.enabled : DEFAULT_INJECTION.enabled,
+    maxTokens: num(cfg?.maxTokens) ? cfg.maxTokens : DEFAULT_INJECTION.maxTokens,
+    maxPerKind: num(cfg?.maxPerKind) ? cfg.maxPerKind : DEFAULT_INJECTION.maxPerKind,
+    charsPerToken: num(cfg?.charsPerToken) ? cfg.charsPerToken : DEFAULT_INJECTION.charsPerToken,
+  };
+}
+
+/** Rough token estimate for a string. Exported for tests/companions. */
+export function estimateTokens(text: string, charsPerToken = DEFAULT_INJECTION.charsPerToken): number {
+  return Math.ceil(text.length / charsPerToken);
+}
+
+export interface SelectionResult {
+  /** Chosen items, grouped by KIND_ORDER, importance-desc within each group. */
+  selected: HarnessItem[];
+  /** Active items for the model that did NOT make the cut (per-kind + budget). */
+  omitted: number;
+  /** True when any item was dropped (drives the transparency footer). */
+  truncated: boolean;
+}
+
+interface Ranked {
+  item: HarnessItem;
+  index: number; // store position, for a stable tie-break on equal importance
+}
+
+/** importance desc, then store index asc (stable). */
+function byImportance(a: Ranked, b: Ranked): number {
+  if (b.item.importance !== a.item.importance) return b.item.importance - a.item.importance;
+  return a.index - b.index;
+}
+
+/**
+ * Select the items to inject for `ownerKey`. Pure: takes a snapshot, returns a
+ * decision. See the module doc for the policy.
+ *
+ * `items` is read-only here — callers (inject.ts) pass `getState().items` plus
+ * the active model key; nothing is mutated.
+ */
+export function selectForInjection(
+  items: HarnessItem[],
+  ownerKey: string,
+  cfg?: Partial<InjectionConfig>,
+): SelectionResult {
+  const n = normalizeInjection(cfg);
+
+  // 1. FILTER: group active items bound to the active model, per kind, in
+  //    store order. (Importance ranking happens below, only when enabled.)
+  const groups = new Map<ComponentKind, Ranked[]>();
+  for (const kind of KIND_ORDER) groups.set(kind, []);
+  items.forEach((item, index) => {
+    if (item.active && item.ownerModel === ownerKey) {
+      groups.get(item.kind)!.push({ item, index });
+    }
+  });
+  if (!n.enabled) {
+    // Legacy opt-out: every active item for the model, grouped by kind, in
+    // STORE (insertion) order — deliberately NOT importance-sorted. Returning to
+    // the pre-selection behaviour is the whole point of `enabled: false`.
+    const selected = KIND_ORDER.flatMap((kind) => groups.get(kind)!.map((r) => r.item));
+    return { selected, omitted: 0, truncated: false };
+  }
+
+  // Importance desc, stable on store index (ties keep insertion order).
+  for (const arr of groups.values()) arr.sort(byImportance);
+
+  // 2a. CAP per kind (maxPerKind): drop the lowest-importance tail of each kind.
+  let omitted = 0;
+  const capped = new Map<ComponentKind, Ranked[]>();
+  for (const kind of KIND_ORDER) {
+    const arr = groups.get(kind)!;
+    const kept = arr.slice(0, n.maxPerKind);
+    omitted += arr.length - kept.length;
+    capped.set(kind, kept);
+  }
+
+  // 2b. CAP total (maxTokens): flatten round-robin (rank-major, kind order
+  // within a rank) so importance is prioritized across kinds fairly, then take
+  // greedily while the budget allows — skipping (not stopping on) an item that
+  // does not fit, so a large item never blocks smaller higher-priority ones.
+  const presentKinds = KIND_ORDER.filter((k) => capped.get(k)!.length > 0);
+  const maxRank = presentKinds.reduce((m, k) => Math.max(m, capped.get(k)!.length), 0);
+  const queue: Ranked[] = [];
+  for (let rank = 0; rank < maxRank; rank++) {
+    for (const kind of presentKinds) {
+      const r = capped.get(kind)![rank];
+      if (r) queue.push(r);
+    }
+  }
+
+  const overhead = INTRO_TOKENS + presentKinds.length * SECTION_HEADER_TOKENS + FOOTER_TOKENS;
+  let remaining = Math.max(0, n.maxTokens - overhead);
+  const taken: Ranked[] = [];
+  for (const r of queue) {
+    const cost = estimateTokens(`- [${r.item.id}] ${r.item.content}`, n.charsPerToken);
+    if (cost <= remaining) {
+      remaining -= cost;
+      taken.push(r);
+    }
+  }
+  omitted += queue.length - taken.length;
+
+  // Re-group the survivors into KIND_ORDER sections (importance-desc within each).
+  const selected = KIND_ORDER.flatMap((kind) =>
+    taken.filter((r) => r.item.kind === kind).map((r) => r.item),
+  );
+
+  return { selected, omitted, truncated: omitted > 0 };
+}