infinity-harness 2.2.1 → 2.3.1

package/src/core/settings.ts

@@ -151,6 +151,62 @@ export const SETTINGS: SettingsGroup[] = [
       },
     ],
   },
+  {
+    id: "approvals",
+    label: "Your approvals",
+    help: "Which phases stop and wait for your signature. These are the three that decide WHAT gets built — after PLAN, a wrong turn fails a gate and retries.",
+    settings: [
+      {
+        path: "approvals.research",
+        file: "config",
+        label: "Sign off RESEARCH",
+        help: "You read harness/docs/RESEARCH.md and say whether it is looking at the right problem. Only applies when the RESEARCH phase is enabled.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "approvals.define",
+        file: "config",
+        label: "Sign off DEFINE",
+        help: "The highest-leverage signature: a wrong definition is a weekend building the wrong thing perfectly.",
+        type: { kind: "boolean" },
+      },
+      {
+        path: "approvals.plan",
+        file: "config",
+        label: "Sign off PLAN",
+        help: "You see the whole task list before a line of it is built, and can send it back with a note.",
+        type: { kind: "boolean" },
+      },
+    ],
+  },
+  {
+    id: "sessions",
+    label: "Sessions",
+    help: "How the run divides itself into pi sessions. A run that never starts a fresh one carries its whole history into every request.",
+    settings: [
+      {
+        path: "session.handoff",
+        file: "config",
+        label: "Fresh session",
+        help: "phase: each phase starts clean · task: cleanest context, best with small models · off: one session for the whole run.",
+        type: { kind: "choice", choices: ["off", "phase", "task"] },
+      },
+      {
+        path: "session.contextThreshold",
+        file: "config",
+        label: "Context handoff threshold",
+        help: "Hand off early once the context is this full, as a fraction of the window. 0 disables it. 0.7 keeps a long BUILD phase out of compaction.",
+        type: { kind: "number", min: 0, max: 0.95 },
+      },
+      {
+        path: "session.carryNotes",
+        file: "config",
+        label: "Carry a note across",
+        help: "Tell the replacement session, in one line, what the previous one got done.",
+        type: { kind: "boolean" },
+      },
+    ],
+  },
   {
     id: "commands",
     label: "Project commands",

package/src/core/types.ts

@@ -9,6 +9,7 @@
 
 export const PHASE_ORDER = [
   "init",
+  "research",
   "define",
   "plan",
   "build",
@@ -20,7 +21,7 @@ export const PHASE_ORDER = [
 
 export type Phase = (typeof PHASE_ORDER)[number];
 
-/** Phases enabled by default — SIMPLIFY is opt-in. */
+/** Phases enabled by default — RESEARCH and SIMPLIFY are opt-in. */
 export const DEFAULT_ENABLED_PHASES: Phase[] = [
   "define",
   "plan",
@@ -30,11 +31,23 @@ export const DEFAULT_ENABLED_PHASES: Phase[] = [
   "ship",
 ];
 
-export type Role = "planner" | "generator" | "evaluator" | "simplifier";
+/**
+ * Phases whose output a human may want to sign off before the run continues.
+ *
+ * These are the three that decide *what gets built*. Everything after them is
+ * execution: if the definition and the plan are right, an autonomous run that
+ * gets BUILD wrong fails a gate and retries, but an autonomous run that got
+ * DEFINE wrong spends a weekend building the wrong product perfectly.
+ */
+export const APPROVABLE_PHASES = ["research", "define", "plan"] as const;
+export type ApprovablePhase = (typeof APPROVABLE_PHASES)[number];
+
+export type Role = "researcher" | "planner" | "generator" | "evaluator" | "simplifier";
 
 /** Which role owns each phase. Drives the "put on this hat" brief line. */
 export const PHASE_ROLE: Record<Phase, Role> = {
   init: "planner",
+  research: "researcher",
   define: "planner",
   plan: "planner",
   build: "generator",
@@ -135,6 +148,51 @@ export type RetryBucket = {
   maxRetries: number | null;
 };
 
+/**
+ * How the run divides itself into pi sessions.
+ *
+ * A harness that never starts a new session is a harness whose context window
+ * only ever grows: by the tenth task the model is reading the whole history of
+ * the first nine to do the tenth, paying for it, and — on a small model —
+ * drowning in it. The plan, the phase and the gate all live on disk, so a
+ * session boundary costs nothing but the brief, and the brief is what the
+ * agent should be working from anyway.
+ */
+export type SessionPolicy = {
+  /**
+   * When to hand off to a fresh session.
+   *   off    never — one session for the whole run (the old behaviour)
+   *   phase  when the pipeline advances a phase
+   *   task   when the pipeline advances a phase or moves to a different task
+   */
+  handoff: "off" | "phase" | "task";
+  /**
+   * Hand off early once the context is this full, as a fraction of the
+   * window. 0 disables it. This is what keeps a long BUILD phase — which may
+   * never advance for hours — from riding a single session into compaction.
+   */
+  contextThreshold: number;
+  /** Carry a short "what the last session did" note into the new session. */
+  carryNotes: boolean;
+};
+
+/** Which phases stop and wait for a human signature before the run continues. */
+export type ApprovalPolicy = {
+  research: boolean;
+  define: boolean;
+  plan: boolean;
+};
+
+/** What the start-up wizard settled, so it is never asked twice. */
+export type IntakeState = {
+  /** True once the wizard has run to completion for this project. */
+  completed: boolean;
+  /** What the human said they want built, in their words. */
+  brief: string | null;
+  /** ISO timestamp of the wizard run. */
+  at: string | null;
+};
+
 export type HarnessConfig = {
   version: string;
   stack: string | null;
@@ -168,6 +226,11 @@ export type HarnessConfig = {
   };
   phases: { enabled: Phase[] };
   roles: { strict: boolean };
+  session: SessionPolicy;
+  approvals: ApprovalPolicy;
+  intake: IntakeState;
+  /** Set when a gate passed but the phase needs a human signature first. */
+  awaitingApproval: Phase | null;
   /** Budgets that bound an unattended continuous run. See src/loop.ts. */
   loop: {
     maxIterations: number;

package/src/handoff.ts

@@ -0,0 +1,197 @@
+/**
+ * infinity-harness — session handoff.
+ *
+ * A harness that never starts a new pi session is a harness whose context
+ * window only ever grows. By the tenth task the model is re-reading the whole
+ * history of the first nine in order to do the tenth: it pays for those tokens
+ * on every call, it compacts them into a lossy summary once the window fills,
+ * and on a small model it simply drowns. That is the failure mode this module
+ * exists to remove.
+ *
+ * The trick is that a handoff costs almost nothing here, because the harness
+ * never kept its state in the conversation to begin with. The plan, the phase,
+ * the gate history, the retry budgets and the escalation ladder are all files.
+ * A new session needs one thing to carry on: the brief — which is what the
+ * agent should have been working from anyway.
+ *
+ * What this module owns:
+ *   - deciding *whether* a handoff is due (`shouldHandoff`)
+ *   - writing down what the next session must be told (`requestHandoff`)
+ *   - handing that to whoever starts it, exactly once (`takeHandoff`)
+ *
+ * What it deliberately does not own: starting the session. Only pi can do
+ * that, only from a command handler, and the adapter is where pi lives.
+ */
+
+import type { HarnessConfig, Phase, SessionPolicy } from "./core/types.ts";
+import { pendingSessionPath } from "./core/paths.ts";
+import { readJsonSafe, writeJsonAtomic, removeFile, fileExists } from "./core/fsx.ts";
+
+/** Why a session is being replaced. Shown to the human and to the next agent. */
+export type HandoffReason = "phase" | "task" | "context" | "goal-pass" | "manual";
+
+export type PendingHandoff = {
+  reason: HandoffReason;
+  /** Human-readable one-liner: "BUILD → VERIFY", "context 78% full". */
+  detail: string;
+  /** The message the replacement session is started with. Usually the brief. */
+  kickoff: string;
+  /** A short note on what the session being replaced actually did. */
+  carry: string | null;
+  /** The run this handoff belongs to; a stale file from an old run is ignored. */
+  runId: string;
+  at: string;
+};
+
+export type HandoffSignals = {
+  config: HarnessConfig;
+  /** Phase before the loop's decision, and after it. */
+  fromPhase: Phase | null;
+  toPhase: Phase | null;
+  /** Composite key of the task in focus before and after. */
+  fromTask: string | null;
+  toTask: string | null;
+  /** Fraction of the context window in use, 0..1, or null when unknown. */
+  contextRatio: number | null;
+};
+
+export type HandoffDecision = { handoff: false } | { handoff: true; reason: HandoffReason; detail: string };
+
+export function defaultSessionPolicy(): SessionPolicy {
+  return { handoff: "phase", contextThreshold: 0.7, carryNotes: true };
+}
+
+function policyOf(config: HarnessConfig): SessionPolicy {
+  const p = (config.session ?? {}) as Partial<SessionPolicy>;
+  const handoff = p.handoff === "off" || p.handoff === "task" || p.handoff === "phase" ? p.handoff : "phase";
+  const raw = typeof p.contextThreshold === "number" ? p.contextThreshold : 0.7;
+  return {
+    handoff,
+    // A threshold of 1 or more can never fire and a negative one always would;
+    // both are configuration mistakes, and clamping is kinder than either.
+    contextThreshold: raw <= 0 ? 0 : Math.min(0.95, raw),
+    carryNotes: p.carryNotes !== false,
+  };
+}
+
+/**
+ * Should the run continue in a fresh session?
+ *
+ * Order matters. Context pressure wins over everything, because a handoff that
+ * arrives after compaction has already happened has arrived too late to be the
+ * thing that prevented it.
+ */
+export function shouldHandoff(signals: HandoffSignals): HandoffDecision {
+  const policy = policyOf(signals.config);
+  if (policy.handoff === "off") return { handoff: false };
+
+  const ratio = signals.contextRatio;
+  if (policy.contextThreshold > 0 && typeof ratio === "number" && ratio >= policy.contextThreshold) {
+    return {
+      handoff: true,
+      reason: "context",
+      detail: `context ${Math.round(ratio * 100)}% full (threshold ${Math.round(policy.contextThreshold * 100)}%)`,
+    };
+  }
+
+  if (signals.toPhase && signals.fromPhase !== signals.toPhase) {
+    return {
+      handoff: true,
+      reason: "phase",
+      detail: `${(signals.fromPhase ?? "start").toUpperCase()} → ${signals.toPhase.toUpperCase()}`,
+    };
+  }
+
+  if (policy.handoff === "task" && signals.toTask && signals.fromTask !== signals.toTask) {
+    return {
+      handoff: true,
+      reason: "task",
+      detail: `${signals.fromTask ?? "no task"} → ${signals.toTask}`,
+    };
+  }
+
+  return { handoff: false };
+}
+
+/**
+ * Record what the replacement session must be told.
+ *
+ * Written to disk rather than held in memory because the session that writes
+ * it is, by definition, about to stop existing.
+ */
+export function requestHandoff(
+  targetDir: string,
+  handoff: Omit<PendingHandoff, "at">,
+): PendingHandoff {
+  const pending: PendingHandoff = { ...handoff, at: new Date().toISOString() };
+  writeJsonAtomic(pendingSessionPath(targetDir), pending);
+  return pending;
+}
+
+export function peekHandoff(targetDir: string): PendingHandoff | null {
+  const raw = readJsonSafe<PendingHandoff | null>(pendingSessionPath(targetDir), null);
+  if (!raw || typeof raw.kickoff !== "string" || !raw.kickoff.trim()) return null;
+  return raw;
+}
+
+/**
+ * Claim the pending handoff, clearing it.
+ *
+ * Clearing before returning is deliberate: if the replacement session dies
+ * between claiming and sending, the run stalls where a human can see it,
+ * rather than looping through handoffs forever on a stale file.
+ */
+export function takeHandoff(targetDir: string): PendingHandoff | null {
+  const pending = peekHandoff(targetDir);
+  clearHandoff(targetDir);
+  return pending;
+}
+
+export function clearHandoff(targetDir: string): void {
+  removeFile(pendingSessionPath(targetDir));
+}
+
+export function hasPendingHandoff(targetDir: string): boolean {
+  return fileExists(pendingSessionPath(targetDir));
+}
+
+/**
+ * The message the replacement session opens with.
+ *
+ * It is the brief, plus one paragraph explaining why the previous session
+ * ended — because an agent that wakes up mid-run with no explanation tends to
+ * spend its first turn investigating the harness instead of doing the work.
+ */
+export function composeKickoff(
+  brief: string,
+  reason: HandoffReason,
+  detail: string,
+  carry: string | null,
+): string {
+  const why: Record<HandoffReason, string> = {
+    phase: "The pipeline advanced, so the run continues in a clean session.",
+    task: "The run moved to a different task, so it continues in a clean session.",
+    context: "The previous session's context was filling up, so the run continues in a clean one.",
+    "goal-pass": "A goal pass finished, so the next pass starts in a clean session.",
+    manual: "A human asked for a fresh session.",
+  };
+
+  const lines = [
+    `[infinity-harness] Continuing a run in a fresh session — ${detail}.`,
+    why[reason],
+    "",
+    "Nothing is lost: the plan, the phase, the gate history and every retry budget",
+    "live in `harness/` and are already loaded. Work from the brief below. Do not",
+    "go looking for the previous conversation.",
+  ];
+  if (carry && carry.trim()) {
+    lines.push("", "What the previous session did:", carry.trim());
+  }
+  lines.push("", brief);
+  return lines.join("\n");
+}
+
+/** One-line summary of a handoff, for a notification or the run journal. */
+export function describeHandoff(h: PendingHandoff): string {
+  return `new session — ${h.reason}: ${h.detail}`;
+}

package/src/intake.ts

@@ -0,0 +1,263 @@
+/**
+ * infinity-harness — the start-up wizard.
+ *
+ * The bug this module exists to kill: choosing "autopilot" used to start the
+ * run *immediately*, with no idea and no scope, so the first thing the harness
+ * did was invent a project and start building it. Autopilot was being read as
+ * "you decide everything, including what I want", which is not a mode anybody
+ * asked for.
+ *
+ * The fix is to separate two questions that were tangled together:
+ *
+ *   1. What are we building?      — always asked, in both modes
+ *   2. Who signs off on what?     — the mode's actual meaning
+ *
+ * copilot     the human is in the loop. DEFINE and PLAN are theirs to approve
+ *             (and RESEARCH too, when it is on). Not negotiable — that is what
+ *             the word means.
+ * autopilot   the human is *optionally* in the loop. They pick which of
+ *             RESEARCH / DEFINE / PLAN they want to sign and which they hand
+ *             to the model. Forfeiting all three is the "give it a goal and
+ *             walk away" mode; keeping DEFINE is the common middle.
+ *
+ * RESEARCH is a separate, optional phase that runs before DEFINE: the human
+ * gives an idea, the model goes and finds out what it actually has to be.
+ *
+ * Nothing here talks to pi. It takes answers and returns a plan of record, so
+ * the flow can be unit-tested without a terminal and driven from the adapter,
+ * from a test, or from a config file.
+ */
+
+import type { ApprovalPolicy, Phase, SessionPolicy } from "./core/types.ts";
+import { DEFAULT_ENABLED_PHASES, PHASE_ORDER } from "./core/types.ts";
+
+export type Mode = "copilot" | "autopilot";
+
+/** The wizard's questions, in the order they are asked. */
+export const INTAKE_STEPS = ["mode", "brief", "research", "approvals", "handoff"] as const;
+export type IntakeStep = (typeof INTAKE_STEPS)[number];
+
+export type IntakeAnswers = {
+  mode: Mode;
+  /** What the human wants built, in their words. Empty is allowed but warned about. */
+  brief: string;
+  /** Run the optional RESEARCH phase before DEFINE. */
+  research: boolean;
+  /**
+   * Which phases the human wants to sign, for autopilot only.
+   * Ignored in copilot, where all three are always signed.
+   */
+  approvals?: Partial<ApprovalPolicy>;
+  /** Session handoff policy. Defaults to a fresh session per phase. */
+  handoff?: SessionPolicy["handoff"];
+  /** Phases the human explicitly chose. Overrides the research toggle. */
+  phases?: Phase[];
+};
+
+export type IntakePlan = {
+  mode: Mode;
+  brief: string | null;
+  phases: Phase[];
+  approvals: ApprovalPolicy;
+  session: SessionPolicy;
+  /** What the human should be told about what they just chose. */
+  summary: string;
+  /** Things that will bite later if left as they are. */
+  warnings: string[];
+};
+
+/**
+ * In copilot the human is in the loop by definition, so every approvable
+ * phase that is enabled is theirs. Making this configurable would make
+ * "copilot" mean nothing.
+ */
+export function copilotApprovals(phases: Phase[]): ApprovalPolicy {
+  return {
+    research: phases.includes("research"),
+    define: true,
+    plan: true,
+  };
+}
+
+function normalizePhases(base: Phase[], research: boolean): Phase[] {
+  const wanted = new Set<Phase>(base.filter((p) => (PHASE_ORDER as readonly string[]).includes(p)));
+  wanted.delete("init");
+  if (research) wanted.add("research");
+  else wanted.delete("research");
+  const ordered = PHASE_ORDER.filter((p) => wanted.has(p));
+  return ordered.length ? [...ordered] : [...DEFAULT_ENABLED_PHASES];
+}
+
+/** Turn the wizard's answers into everything `initHarness` needs. */
+export function planIntake(answers: IntakeAnswers): IntakePlan {
+  const research = answers.research === true;
+  const phases = normalizePhases(answers.phases ?? [...DEFAULT_ENABLED_PHASES], research);
+
+  const approvals: ApprovalPolicy =
+    answers.mode === "copilot"
+      ? copilotApprovals(phases)
+      : {
+          research: phases.includes("research") && answers.approvals?.research === true,
+          define: answers.approvals?.define === true,
+          plan: answers.approvals?.plan === true,
+        };
+
+  const handoff = answers.handoff ?? "phase";
+  const session: SessionPolicy = {
+    handoff,
+    contextThreshold: handoff === "off" ? 0 : 0.7,
+    carryNotes: true,
+  };
+
+  const brief = answers.brief?.trim() ? answers.brief.trim() : null;
+
+  const warnings: string[] = [];
+  if (!brief) {
+    warnings.push(
+      "No goal was given, so the first thing the run does is ask you for one. " +
+        "It will not guess a project.",
+    );
+  }
+  if (answers.mode === "autopilot" && !approvals.define && !approvals.plan && !approvals.research) {
+    warnings.push(
+      "Nothing is being approved by you. The model decides what to build and how, " +
+        "and you see it when it is done. This is the right setting for a run you " +
+        "want to walk away from — and the wrong one if the goal is vague.",
+    );
+  }
+  if (handoff === "off") {
+    warnings.push(
+      "Session handoff is off, so the whole run shares one context window. " +
+        "Expect compaction on anything longer than a few tasks.",
+    );
+  }
+
+  return { mode: answers.mode, brief, phases, approvals, session, summary: summarize(answers.mode, phases, approvals, session, brief), warnings };
+}
+
+function summarize(
+  mode: Mode,
+  phases: Phase[],
+  approvals: ApprovalPolicy,
+  session: SessionPolicy,
+  brief: string | null,
+): string {
+  const signed = (["research", "define", "plan"] as const).filter((p) => approvals[p]);
+  const L: string[] = [];
+  L.push(`Mode      ${mode}`);
+  L.push(`Pipeline  ${phases.join(" → ")}`);
+  L.push(
+    `You sign  ${signed.length ? signed.map((s) => s.toUpperCase()).join(", ") : "nothing — the model decides and runs"}`,
+  );
+  L.push(
+    `Sessions  ${
+      session.handoff === "off"
+        ? "one session for the whole run"
+        : session.handoff === "task"
+          ? "fresh session per task and per phase"
+          : "fresh session per phase"
+    }`,
+  );
+  L.push(`Goal      ${brief ?? "(none yet — you will be asked first thing)"}`);
+  return L.join("\n");
+}
+
+// ── The questions, as data ──────────────────────────────────────────────────
+//
+// Declared here rather than written inline in the adapter so the wizard has
+// one wording, the tests read the same strings the human does, and a
+// non-interactive caller can answer them without a terminal.
+
+export type Question = {
+  id: IntakeStep;
+  title: string;
+  /** For choice questions. */
+  options?: { value: string; label: string; help: string }[];
+  /** For free-text questions. */
+  placeholder?: string;
+};
+
+export const MODE_QUESTION: Question = {
+  id: "mode",
+  title: "How much do you want to be involved?",
+  options: [
+    {
+      value: "copilot",
+      label: "copilot — I approve the definition and the plan",
+      help: "The run stops and shows you its work before it starts building. You can send any phase back with a note.",
+    },
+    {
+      value: "autopilot",
+      label: "autopilot — I choose what to approve, if anything",
+      help: "You pick which of research, definition and plan you sign. Approve none of them and the run is yours to walk away from.",
+    },
+  ],
+};
+
+export const BRIEF_QUESTION: Question = {
+  id: "brief",
+  title: "What are you building? One or two sentences is enough.",
+  placeholder: "e.g. a CLI that reconciles Stripe payouts against our ledger",
+};
+
+export const RESEARCH_QUESTION: Question = {
+  id: "research",
+  title: "Research the idea first?",
+  options: [
+    {
+      value: "no",
+      label: "no — go straight to defining it",
+      help: "Right when you already know what has to be built.",
+    },
+    {
+      value: "yes",
+      label: "yes — find out what it has to be first",
+      help: "Adds a RESEARCH phase before DEFINE: prior art, constraints, options with costs, a recommendation, and the questions only you can answer.",
+    },
+  ],
+};
+
+export const HANDOFF_QUESTION: Question = {
+  id: "handoff",
+  title: "When should the run start a fresh session?",
+  options: [
+    {
+      value: "phase",
+      label: "every phase (recommended)",
+      help: "Each phase starts clean, working from the brief. Keeps the context small on long runs.",
+    },
+    {
+      value: "task",
+      label: "every task",
+      help: "The cleanest context per unit of work. Best with small models; costs one extra brief per task.",
+    },
+    {
+      value: "off",
+      label: "never — one long session",
+      help: "The old behaviour. The context grows for the whole run and compaction takes over.",
+    },
+  ],
+};
+
+/** The approval checklist, offered only in autopilot. */
+export function approvalOptions(research: boolean): { value: keyof ApprovalPolicy; label: string; help: string }[] {
+  const out: { value: keyof ApprovalPolicy; label: string; help: string }[] = [];
+  if (research) {
+    out.push({
+      value: "research",
+      label: "RESEARCH — what it found before anything is specified",
+      help: "You read harness/docs/RESEARCH.md and say whether it is looking at the right problem.",
+    });
+  }
+  out.push({
+    value: "define",
+    label: "DEFINE — the scope and the acceptance criteria",
+    help: "The single highest-leverage signature: a wrong definition is a weekend building the wrong thing perfectly.",
+  });
+  out.push({
+    value: "plan",
+    label: "PLAN — the task list before any code is written",
+    help: "You see the whole decomposition and can send it back before it is built.",
+  });
+  return out;
+}