@pi-unipi/fusion 2.17.0

package/src/preset-editor.ts

@@ -0,0 +1,194 @@
+/**
+ * @pi-unipi/fusion — `/unipi:fusion-preset` curation component
+ *
+ * Two-column checklist over every available model:
+ *
+ *   Search: glm
+ *   ─────────────────────────────────────────────────────
+ *     L   S    model
+ *   › [x][ ]  anthropic/claude-opus-4-6
+ *     [ ][x]  omniroute/zai/glm-5.3-flash      ◆ active sidekick
+ *     [ ][ ]  omniroute/deepseek/v4-flash
+ *
+ *   ↑/↓ select · ←/→ column · space toggle lead · Enter save · esc cancel · type to filter
+ *
+ * Keys follow our overlay conventions (task-manager dock, pi's own model
+ * selector): arrows navigate, `Enter` is the primary action (save), `esc`
+ * cancels, `tab`/`←→` switch the L/S column, `space` toggles membership.
+ * Defaults are not edited here — confirming a Fusion pair in /unipi:model
+ * records it as the default.
+ */
+
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { frameOverlay } from "@pi-unipi/core";
+import type { ActiveSelection, FusionPreset, ModelKey } from "./preset.js";
+
+export interface PresetEditorModel {
+  key: ModelKey;
+  name: string;
+}
+
+export type PresetEditorResult =
+  | {
+      type: "saved";
+      target: "global" | "project";
+      curation: Pick<FusionPreset, "lead" | "sidekick" | "default">;
+    }
+  | { type: "cancelled" };
+
+export interface PresetEditorOptions {
+  models: readonly PresetEditorModel[];
+  initial: Pick<FusionPreset, "lead" | "sidekick" | "default">;
+  /** Current selection — its pair becomes the default when still curated. */
+  active: ActiveSelection | undefined;
+  initialTarget: "global" | "project";
+  theme: { fg: (color: string, text: string) => string; bold: (text: string) => string };
+  onDone: (result: PresetEditorResult) => void;
+  onRenderRequest?: (() => void) | undefined;
+  visibleRows?: number | undefined;
+}
+
+function printable(data: string): string | undefined {
+  if (data.length !== 1) return undefined;
+  const code = data.charCodeAt(0);
+  if (code < 32 || code === 127) return undefined;
+  return data;
+}
+
+export class PresetEditor {
+  private readonly opts: PresetEditorOptions;
+  private lead: Set<ModelKey>;
+  private sidekick: Set<ModelKey>;
+  private target: "global" | "project";
+  private search = "";
+  private selected = 0;
+  private column: "lead" | "sidekick" = "lead";
+  private done = false;
+
+  constructor(opts: PresetEditorOptions) {
+    this.opts = opts;
+    this.lead = new Set(opts.initial.lead);
+    this.sidekick = new Set(opts.initial.sidekick);
+    this.target = opts.initialTarget;
+  }
+
+  private filtered(): PresetEditorModel[] {
+    const q = this.search.toLowerCase();
+    const all = this.opts.models;
+    const list = q.length === 0 ? [...all] : all.filter((m) => `${m.key} ${m.name}`.toLowerCase().includes(q));
+    // Selected models float to the top so the curated set is visible at a glance.
+    list.sort((a, b) => {
+      const sa = this.lead.has(a.key) || this.sidekick.has(a.key) ? 0 : 1;
+      const sb = this.lead.has(b.key) || this.sidekick.has(b.key) ? 0 : 1;
+      if (sa !== sb) return sa - sb;
+      return a.key.localeCompare(b.key);
+    });
+    return list;
+  }
+
+  handleInput(data: string): void {
+    if (this.done) return;
+    const list = this.filtered();
+    const cur = list[this.selected];
+    if (matchesKey(data, Key.escape)) {
+      this.done = true;
+      this.opts.onDone({ type: "cancelled" });
+      return;
+    }
+    if (matchesKey(data, Key.enter) || data === "\r") {
+      // Enter = save & close, the primary action in every other overlay.
+      this.done = true;
+      const lead = [...this.lead];
+      const sidekick = [...this.sidekick];
+      const def: FusionPreset["default"] = {};
+      const active = this.opts.active;
+      const dl =
+        active?.kind === "fusion" && this.lead.has(active.lead)
+          ? active.lead
+          : this.opts.initial.default.lead !== undefined && this.lead.has(this.opts.initial.default.lead)
+            ? this.opts.initial.default.lead
+            : lead[0];
+      const ds =
+        active?.kind === "fusion" && this.sidekick.has(active.sidekick)
+          ? active.sidekick
+          : this.opts.initial.default.sidekick !== undefined && this.sidekick.has(this.opts.initial.default.sidekick)
+            ? this.opts.initial.default.sidekick
+            : sidekick[0];
+      if (dl !== undefined) def.lead = dl;
+      if (ds !== undefined) def.sidekick = ds;
+      this.opts.onDone({ type: "saved", target: this.target, curation: { lead, sidekick, default: def } });
+      return;
+    }
+    if (matchesKey(data, Key.up)) this.selected = Math.max(0, this.selected - 1);
+    else if (matchesKey(data, Key.down)) this.selected = Math.min(Math.max(0, list.length - 1), this.selected + 1);
+    else if (matchesKey(data, Key.left) || matchesKey(data, "shift+tab")) this.column = "lead";
+    else if (matchesKey(data, Key.right) || matchesKey(data, Key.tab)) this.column = "sidekick";
+    else if (data === " " && cur) this.toggle(this.column === "lead" ? this.lead : this.sidekick, cur.key);
+    else if (matchesKey(data, Key.backspace) || data === "\x7f") {
+      this.search = this.search.slice(0, -1);
+      this.selected = 0;
+    } else {
+      const ch = printable(data);
+      if (ch === undefined) return;
+      this.search += ch;
+      this.selected = 0;
+    }
+    this.opts.onRenderRequest?.();
+  }
+
+  private toggle(set: Set<ModelKey>, key: ModelKey): void {
+    if (set.has(key)) set.delete(key);
+    else set.add(key);
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    return frameOverlay(this.renderBody(Math.max(4, width - 2)), width, { title: "Fusion preset" });
+  }
+
+  private renderBody(width: number): string[] {
+    const t = this.opts.theme;
+    const list = this.filtered();
+    if (this.selected >= list.length) this.selected = Math.max(0, list.length - 1);
+    const active = this.opts.active;
+    const lines: string[] = [];
+    lines.push(`${t.fg("accent", t.bold("Fusion preset"))} ${t.fg("dim", `· ${String(this.lead.size)} lead · ${String(this.sidekick.size)} sidekick · writes to ${this.target}`)}`);
+    lines.push(`${t.fg("dim", "Search:")} ${this.search.length > 0 ? t.fg("text", this.search) : t.fg("dim", "(type to filter)")}`);
+    lines.push(t.fg("dim", "─".repeat(Math.max(1, width - 2))));
+    const colHead = (label: string, col: "lead" | "sidekick") =>
+      this.column === col ? t.fg("accent", t.bold(label)) : t.fg("dim", label);
+    lines.push(`    ${colHead("L", "lead")}   ${colHead("S", "sidekick")}    ${t.fg("dim", "model")}`);
+    const win = this.opts.visibleRows ?? 14;
+    const start = Math.max(0, Math.min(this.selected - Math.floor(win / 2), list.length - win));
+    const end = Math.min(list.length, start + win);
+    if (list.length === 0) lines.push(t.fg("warning", "  No models match."));
+    for (let i = start; i < end; i++) {
+      const m = list[i];
+      if (!m) continue;
+      const hl = i === this.selected;
+      const ptr = hl ? t.fg("accent", "›") : " ";
+      const box = (on: boolean, col: "lead" | "sidekick") => {
+        const focused = hl && this.column === col;
+        const glyph = on ? "[x]" : "[ ]";
+        return focused ? t.fg("accent", t.bold(glyph)) : on ? t.fg("success", glyph) : t.fg("dim", glyph);
+      };
+      const l = box(this.lead.has(m.key), "lead");
+      const s = box(this.sidekick.has(m.key), "sidekick");
+      const name = hl ? t.fg("accent", m.key) : t.fg("text", m.key);
+      const tags: string[] = [];
+      if (m.key === this.opts.initial.default.lead) tags.push("default lead");
+      if (m.key === this.opts.initial.default.sidekick) tags.push("default sidekick");
+      if (active?.kind === "fusion") {
+        if (m.key === active.lead) tags.push("active lead");
+        if (m.key === active.sidekick) tags.push("active sidekick");
+      }
+      const tag = tags.length > 0 ? ` ${t.fg("dim", `(${tags.join(", ")})`)}` : "";
+      lines.push(truncateToWidth(` ${ptr} ${l} ${s}  ${name}${tag}`, Math.max(1, width - 1)));
+    }
+    if (list.length > win) lines.push(t.fg("dim", `  ${String(start + 1)}-${String(end)} of ${String(list.length)}`));
+    lines.push("");
+    lines.push(t.fg("dim", `↑/↓ select · ←/→ column · space toggle ${this.column} · Enter save · esc cancel · type to filter`));
+    return lines;
+  }
+}

package/src/preset.ts

@@ -0,0 +1,259 @@
+/**
+ * @pi-unipi/fusion — fusion preset store
+ *
+ * The preset is the user-curated, finite model list the `/unipi:model` picker
+ * shows (pi's full catalogue can be 400+ entries). It also remembers the
+ * per-model effort (thinking level), the default lead/sidekick pair, the
+ * currently active selection, and the MRU list.
+ *
+ * Layers (deep-merged, project on top; arrays replace, objects merge):
+ *   global  ~/.unipi/config/fusion/preset.json
+ *   project <cwd>/.unipi/fusion-preset.json
+ *
+ * Writes go to the layer the user chose (default global). The active
+ * selection + recent list are runtime state and always persist globally.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const PRESET_SCHEMA_VERSION = 1;
+
+/** pi thinking levels in ascending effort order (used by ←/→ in the picker). */
+export const EFFORT_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];
+
+export type FusionBadge = "new" | "promotion" | "beta";
+
+export const RECENT_LIMIT = 5;
+
+/** `provider/modelId` */
+export type ModelKey = string;
+
+export interface FusionPair {
+  lead: ModelKey;
+  sidekick: ModelKey;
+}
+
+export type ActiveSelection =
+  | { kind: "single"; model: ModelKey }
+  | {
+      kind: "fusion";
+      lead: ModelKey;
+      sidekick: ModelKey;
+      /** Fusion-row efforts are independent of per-model memory. */
+      leadEffort?: EffortLevel | undefined;
+      sidekickEffort?: EffortLevel | undefined;
+    };
+
+export interface FusionPreset {
+  schema_version: number;
+  /** Models offered as lead (also shown as plain single-model rows). */
+  lead: ModelKey[];
+  /** Models offered as sidekick. */
+  sidekick: ModelKey[];
+  /** Default pair used when the Fusion row is confirmed without editing. */
+  default: Partial<FusionPair>;
+  /** Remembered per-model effort. */
+  effort: Record<ModelKey, EffortLevel>;
+  /** MRU single models / leads, newest first, max RECENT_LIMIT. */
+  recent: ModelKey[];
+  /** Optional hand-curated model badge metadata. */
+  badges: Record<ModelKey, FusionBadge>;
+  /** What the user last confirmed in the picker. */
+  active?: ActiveSelection | undefined;
+}
+
+export function emptyPreset(): FusionPreset {
+  return {
+    schema_version: PRESET_SCHEMA_VERSION,
+    lead: [],
+    sidekick: [],
+    default: {},
+    effort: {},
+    recent: [],
+    badges: {},
+  };
+}
+
+export function globalPresetPath(home = homedir()): string {
+  return join(home, ".unipi", "config", "fusion", "preset.json");
+}
+
+export function projectPresetPath(cwd: string): string {
+  return join(cwd, ".unipi", "fusion-preset.json");
+}
+
+export function modelKey(model: { provider: string; id: string }): ModelKey {
+  return `${model.provider}/${model.id}`;
+}
+
+export function splitModelKey(key: ModelKey): { provider: string; id: string } | undefined {
+  const slash = key.indexOf("/");
+  if (slash <= 0 || slash === key.length - 1) return undefined;
+  return { provider: key.slice(0, slash), id: key.slice(slash + 1) };
+}
+
+export function isEffortLevel(value: unknown): value is EffortLevel {
+  return typeof value === "string" && (EFFORT_LEVELS as readonly string[]).includes(value);
+}
+
+function stringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string" && entry.includes("/") && !out.includes(entry)) out.push(entry);
+  }
+  return out;
+}
+
+/** Validate + normalise an arbitrary JSON value into a partial preset. */
+export function parsePreset(raw: unknown): Partial<FusionPreset> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
+  const r = raw as Record<string, unknown>;
+  const out: Partial<FusionPreset> = {};
+  if ("lead" in r) out.lead = stringArray(r["lead"]);
+  if ("sidekick" in r) out.sidekick = stringArray(r["sidekick"]);
+  if (typeof r["default"] === "object" && r["default"] !== null) {
+    const d = r["default"] as Record<string, unknown>;
+    out.default = {};
+    if (typeof d["lead"] === "string") out.default.lead = d["lead"];
+    if (typeof d["sidekick"] === "string") out.default.sidekick = d["sidekick"];
+  }
+  if (typeof r["effort"] === "object" && r["effort"] !== null) {
+    const effort: Record<string, EffortLevel> = {};
+    for (const [k, v] of Object.entries(r["effort"] as Record<string, unknown>)) {
+      if (isEffortLevel(v)) effort[k] = v;
+    }
+    out.effort = effort;
+  }
+  if ("recent" in r) out.recent = stringArray(r["recent"]).slice(0, RECENT_LIMIT);
+  if (typeof r["badges"] === "object" && r["badges"] !== null) {
+    const badges: Record<ModelKey, FusionBadge> = {};
+    for (const [k, v] of Object.entries(r["badges"] as Record<string, unknown>)) {
+      if (v === "new" || v === "promotion" || v === "beta") badges[k] = v;
+    }
+    out.badges = badges;
+  }
+  const active = r["active"];
+  if (typeof active === "object" && active !== null) {
+    const a = active as Record<string, unknown>;
+    if (a["kind"] === "single" && typeof a["model"] === "string") {
+      out.active = { kind: "single", model: a["model"] };
+    } else if (
+      a["kind"] === "fusion" &&
+      typeof a["lead"] === "string" &&
+      typeof a["sidekick"] === "string"
+    ) {
+      out.active = {
+        kind: "fusion",
+        lead: a["lead"],
+        sidekick: a["sidekick"],
+        ...(isEffortLevel(a["leadEffort"]) ? { leadEffort: a["leadEffort"] } : {}),
+        ...(isEffortLevel(a["sidekickEffort"]) ? { sidekickEffort: a["sidekickEffort"] } : {}),
+      };
+    }
+  }
+  return out;
+}
+
+export function mergePresets(base: FusionPreset, over: Partial<FusionPreset>): FusionPreset {
+  return {
+    schema_version: PRESET_SCHEMA_VERSION,
+    lead: over.lead ?? base.lead,
+    sidekick: over.sidekick ?? base.sidekick,
+    default: { ...base.default, ...(over.default ?? {}) },
+    effort: { ...base.effort, ...(over.effort ?? {}) },
+    recent: over.recent ?? base.recent,
+    badges: { ...base.badges, ...(over.badges ?? {}) },
+    active: over.active ?? base.active,
+  };
+}
+
+function readJson(path: string): unknown {
+  try {
+    if (!existsSync(path)) return undefined;
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface LoadedPreset {
+  preset: FusionPreset;
+  globalPath: string;
+  projectPath: string;
+  hasProjectLayer: boolean;
+}
+
+export function loadPreset(cwd: string, home = homedir()): LoadedPreset {
+  const globalPath = globalPresetPath(home);
+  const projectPath = projectPresetPath(cwd);
+  const globalRaw = readJson(globalPath);
+  const projectRaw = readJson(projectPath);
+  let preset = mergePresets(emptyPreset(), parsePreset(globalRaw));
+  const hasProjectLayer = projectRaw !== undefined;
+  if (hasProjectLayer) preset = mergePresets(preset, parsePreset(projectRaw));
+  return { preset, globalPath, projectPath, hasProjectLayer };
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${String(process.pid)}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  renameSync(tmp, path);
+}
+
+/** Persist the curated lists (lead/sidekick/default) to one layer. */
+export function saveCuration(
+  path: string,
+  curation: Pick<FusionPreset, "lead" | "sidekick" | "default">,
+): void {
+  const existing = parsePreset(readJson(path));
+  writeJsonAtomic(path, {
+    schema_version: PRESET_SCHEMA_VERSION,
+    ...existing,
+    lead: curation.lead,
+    sidekick: curation.sidekick,
+    default: curation.default,
+  });
+}
+
+/** Persist runtime state (effort / recent / active) — always to the global layer. */
+export function saveRuntimeState(
+  globalPath: string,
+  state: Pick<FusionPreset, "effort" | "recent"> & { active?: ActiveSelection | undefined },
+): void {
+  const existing = parsePreset(readJson(globalPath));
+  writeJsonAtomic(globalPath, {
+    schema_version: PRESET_SCHEMA_VERSION,
+    lead: existing.lead ?? [],
+    sidekick: existing.sidekick ?? [],
+    default: existing.default ?? {},
+    ...existing,
+    effort: state.effort,
+    recent: state.recent.slice(0, RECENT_LIMIT),
+    active: state.active,
+  });
+}
+
+// ── pure helpers used by the picker ────────────────────────────────────────
+
+export function pushRecent(recent: readonly ModelKey[], key: ModelKey): ModelKey[] {
+  return [key, ...recent.filter((k) => k !== key)].slice(0, RECENT_LIMIT);
+}
+
+export function stepEffort(current: EffortLevel, delta: -1 | 1): EffortLevel {
+  const index = EFFORT_LEVELS.indexOf(current);
+  const next = Math.min(EFFORT_LEVELS.length - 1, Math.max(0, index + delta));
+  return EFFORT_LEVELS[next] ?? current;
+}
+
+/** Devin-style label: off→None, xhigh→XHigh, max→Max, others capitalised. */
+export function effortLabel(level: EffortLevel): string {
+  if (level === "off") return "None";
+  if (level === "xhigh") return "XHigh";
+  if (level === "max") return "Max";
+  return level.charAt(0).toUpperCase() + level.slice(1);
+}

package/src/prompts.ts

@@ -0,0 +1,96 @@
+/**
+ * @pi-unipi/fusion — Local Fusion prompt text
+ *
+ * Two prompt fragments make Fusion behave like a lead + sidekick pair rather
+ * than two unrelated models:
+ *
+ *   - `leadPolicy()` is appended to the LEAD's system prompt on every turn
+ *     while Fusion is active (before_agent_start). It is the delegate-by-
+ *     default contract: what to hand off, what to keep, how to brief, how to
+ *     review.
+ *   - `sidekickSystemPrompt()` is appended to the SIDEKICK child's system
+ *     prompt once at spawn. It tells the child what it is, what it never
+ *     does, and how to report.
+ *
+ * Both are plain strings so they can be unit-tested and diffed. Keep them
+ * self-contained; the sidekick never sees the lead's conversation.
+ */
+
+export interface FusionIdentity {
+  leadName: string;
+  leadEffort: string;
+  sidekickName: string;
+  sidekickEffort: string;
+}
+
+function cap(s: string): string {
+  return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** One-line identity, e.g. `You are powered by Fusion (Claude Opus 4.6 Medium + GLM 5.3 Flash High).` */
+export function fusionIdentityLine(id: FusionIdentity): string {
+  const lead = id.leadEffort ? `${id.leadName} ${cap(id.leadEffort)}` : id.leadName;
+  const side = id.sidekickEffort ? `${id.sidekickName} ${cap(id.sidekickEffort)}` : id.sidekickName;
+  return `You are powered by Fusion (${lead} + ${side}).`;
+}
+
+export function leadPolicy(id: FusionIdentity): string {
+  return `${fusionIdentityLine(id)}
+
+## Sidekick
+You have a \`sidekick\` tool: a persistent subagent that works alongside you on the same machine (shared filesystem and repos; its shell sessions are separate from yours). You are the lead: you own the outcome and the user-facing and authority actions — talking to the user, planning, and directing the sidekick. The user interacts with one agent: you. Do not mention the sidekick or distinguish its work from yours unless the user explicitly asks; describe all work as your own, in the first person. The sidekick does the hands-on work you direct, such as implementing changes and verifying results. Your job is to give it context and done-criteria, then review, critique, and decide what to do with its report — decide and direct, don't re-derive what it already gave you or take over its work. When you write a todo list, mark the steps you'll hand off so you don't drift into doing them yourself.
+
+- **Delegate by default** the hands-on work — implementation and verification; keep judgment, design, and the user-facing and authority actions.
+  - **Implementation:** only implement a step yourself if it is trivially small (you can make the edit AND confirm it in 1-2 of your own turns, with nothing left to test afterwards, e.g. a stray import) or correctness-critical (below). Anything that needs a test written or run, touches more than one file, or that you would want to look over again afterwards is not trivial — brief it. The moment your investigation settles the design, your next action is a brief, not an edit.
+  - **Verification & environment:** delegate environment setup and repair — even when the failure blocks something you were doing yourself — and running builds, linters, type-checks, and test suites. Name the narrowest checks that cover the change; the sidekick treats your list as mandatory, so a "run everything" brief re-gates unchanged work on every handoff. Reserve a full-suite pass for at most one final gate.
+- **Keep for yourself:**
+  - Investigations (codebase exploration, root-cause tracing, git-history archaeology) when your reply will restate the findings as your own grounded answer.
+  - Planning and design decisions.
+  - **Correctness-critical work — where wrong output looks plausible instead of erroring.** Queries against shared or production data systems, data analysis and measurement (counts, metrics), eval/benchmark harnesses, prompt/rubric/grader text, and pipeline/threshold/sampling configuration. Author, run, and check that work yourself regardless of size; delegate only mechanical execution of a recipe you fully authored — never the authoring or the checking.
+  - Reviewing the sidekick's diff before it lands.
+  - Talking to the user, commits, pushes, pull requests, and code-review responses.
+- The sidekick remembers everything from previous handoffs (code it wrote, files it explored, your earlier instructions), so don't re-explain context it already has. Its runtime state also persists: background shells and processes it started (dev servers, DB connections, long-running commands) usually survive between handoffs. Every brief that involves servers or long-running processes must say what to do with them — e.g. "the server from the previous handoff may still be running; check and reuse it, restart only if it's gone or the code changed" — and, when a later handoff may need them, tell it to leave them running.
+- On each handoff give it: the goal, your plan, the constraints, the relevant files, and how to verify. Settle the consequential choices before handing off: the exact interface (signature, types, data shape, which existing helper to use) and the exact tests (cases, assertions, where to stub). Don't leave alternatives for it to pick; it will guess, and a wrong guess costs a whole extra round. A code snippet is fine when it is the clearest way to say it.
+- **Never make the sidekick redo work you already did.** Results you already derived go into the brief as settled inputs (the values, or the path to the file holding them), not as an invitation to recompute. Ask for re-derivation only when you have reason to doubt them.
+- Blocking dispatch is the default: a \`sidekick\` call waits and returns the report. Pass \`block: false\` only when you genuinely have parallel lead work to do meanwhile; don't start work redundant with what the sidekick is doing, and never poll \`read_subagent\` in a loop. When you have run out of parallel work and still need the report, wait with \`read_subagent\` (\`block: true\`) rather than ending your turn or guessing.
+- Calling \`sidekick\` again while a handoff is running injects the new message into that handoff as an interrupt — it never starts a second sidekick. Use it to redirect with a corrected brief, tell it to wrap up and report what it has, or send a purely informational update.
+- If the user sends a message while a handoff is in flight, act on it before going back to waiting: handle lead-only work yourself, and for anything that concerns the running handoff, send an interrupt. Resume waiting only once you have deliberately decided the message changes nothing for the sidekick.
+- Track the lead-only actions you have promised the user (messages, review replies, commit/PR updates) — the sidekick cannot do these, so a brief that includes one silently drops it. Do each one the moment the handoff returns, before dispatching a follow-up.
+- Review the evidence it reports back (diff, test output, files, screenshots, logs) instead of re-running it yourself. Its prose is a claim, the artifacts are the evidence: have it hand back their paths rather than clean them up. Do final verification yourself only when the user needs your own recorded proof, the sidekick cannot access the required surface, or its evidence is incomplete or suspicious.
+- **Review its code before it lands.** A report about code it wrote is a landing point: read the full diff and give a verdict before your next action — including before stopping or blocking on the user, and before you commit. Complete the whole review, then dispatch all findings in ONE consolidated rework brief — defects, incomplete items, and gaps together. Don't send multiple small rework handoffs, and don't take the work over after a single miss. Fix something yourself only if it is truly one or two of your own turns including verification.
+- Answer its questions concretely in one handoff — don't make it ask twice. A blocker is still a handoff: pick a direction and hand execution back. If it reports an environment blocker, prefer telling it how to get unblocked. Take over only when the blocker needs your authority, or after a couple of rounds it is still stuck on the same problem.
+- The sidekick never sees the user's messages or your conversation — it knows only your brief and what it discovers itself. Pass along relevant user requirements, decisions, and constraints explicitly. It can use credentials already in the environment, but cannot request new secrets from the user; when a task needs a lead-only action, it will stop and report to you.
+- **Never hand off implementation of an unsettled ask.** If any part still needs exploration, an audit, or the user's agreement, settle it first.
+- **User urgency:** when the user is waiting on a concrete deliverable, do the minimal action that unblocks them yourself immediately — even if it is normally delegated — and move slow validation (test gates, full check suites) off the critical path.
+
+### Known failure patterns when delegating
+- **Premature implementation briefing.** Working solo you would catch a wrong assumption as you go; when delegating, the sidekick executes what you wrote, and changing course afterwards is expensive. Hold your plan to a higher confidence bar than you would need to start yourself. Every claim your plan depends on must either be verified or explicitly marked as a hypothesis for the sidekick to verify; verification instructions must cover every surface you discovered.
+- **Promoting a delegated hypothesis to a confirmed conclusion.** When a report ranks candidate causes, the ranking is not a verdict. Present a cause as the root cause only if evidence shows its code path actually executes in the reported scenario; otherwise present it as the leading hypothesis and name the check that would settle it.`;
+}
+
+/** One-time reminder appended to the lead's first direct edit/write while Fusion is active. */
+export const FIRST_EDIT_NUDGE =
+  "<system_guidance>You made a direct edit yourself instead of delegating to the sidekick. That is fine for a trivially small change (one you can make and confirm in 1-2 turns with nothing left to test). For anything larger — multiple files, anything that needs a test run, anything you would want to look over again — write a brief and hand it to `sidekick` instead: you design and review, it implements and verifies. This reminder is shown once.</system_guidance>";
+
+export function sidekickSystemPrompt(id: FusionIdentity): string {
+  return `## Role: Fusion sidekick
+You are the sidekick half of a Fusion pair. A lead agent (${id.leadName}) plans, talks to the user, and reviews; you do the hands-on work it hands you. You run on the same machine and repository as the lead, with your own shell sessions. Your conversation persists across handoffs: remember what you did, what you learned, and which processes you left running.
+
+You never see the user or the lead's conversation — only the brief in front of you. Treat the brief as authoritative: execute it exactly, do not re-derive results it states as settled, and do not substitute your own design when it specifies an interface, a test, or a query shape. If the brief is ambiguous or something in the environment contradicts it, stop at that point and report the discrepancy with your evidence instead of guessing.
+
+What you do not do:
+- Talk to the user, ask the user questions, or request new secrets. The lead is the only voice the user hears.
+- Commit, push, open or update pull requests, respond to code review, or change repository security/compliance settings. Leave changes in the working tree for the lead to review.
+- Perform irreversible destructive operations (deleting files you did not create, \`rm -rf\`, force-pushes, dropping data) unless the brief explicitly names that exact action.
+- Widen the scope: fix only what the brief asks; note anything else you found.
+- Leave long-running processes in an unknown state: say what is still running and how to reach it.
+
+How you report (your final message is what the lead reads — make it the whole story):
+1. **Result** — done / partially done / blocked, in one line.
+2. **Changes** — files touched, one line each, plus \`git diff --stat\` style summary if code changed.
+3. **Verification** — the exact commands you ran and their outcomes (pass/fail counts, exit codes). Include paths to logs, screenshots, or other artifacts rather than deleting them. Never claim a check passed without having run it.
+4. **Open items** — anything the brief asked for that you did not finish, discrepancies, and questions for the lead, each stated so it can be answered in one reply.
+5. **Runtime state** — processes or servers still running (pid, port, how to reuse).
+
+Prefer compact, idiomatic code that follows the repository's existing conventions; do not add or remove comments unless asked; do not create documentation files unless asked.`;
+}

package/src/savings.ts

@@ -0,0 +1,22 @@
+import type { PickerModel } from "./picker.js";
+import type { SidekickUsage } from "./sidekick-runtime.js";
+
+export function estimateSavings(
+  usage: SidekickUsage,
+  lead: PickerModel["cost"],
+  side: PickerModel["cost"],
+): { sidekickUsd: number; atLeadUsd: number; savedUsd: number } {
+  const sidekickUsd = priceUsage(usage, side);
+  const atLeadUsd = priceUsage(usage, lead);
+  return { sidekickUsd, atLeadUsd, savedUsd: atLeadUsd - sidekickUsd };
+}
+
+function priceUsage(usage: SidekickUsage, cost: PickerModel["cost"]): number {
+  if (!cost) return usage.cost;
+  return (
+    usage.input * cost.input +
+    usage.cacheRead * cost.cachedInput +
+    usage.cacheWrite * cost.input +
+    usage.output * cost.output
+  ) / 1_000_000;
+}