/**
 * pi-goal-list-loop-audit — v0.1.0
 * extensions/loops/goal.ts
 *
 * The goal loop. The agent continues working, and on complete_goal,
 * an isolated auditor verifies the work.
 *
 * Design: see docs/DESIGN.md.
 *
 * Command surface (v0.8.0 — four top-level commands):
 *   /goal "<objective>" | /goal (draft) | /goal status|pause|resume|cancel|tweak <text>|archive
 *   /list add|show|next|remove|clear
 *   /loop (draft) | /loop start|status|stop
 *   /gla (settings UI) | /gla key=value | /gla project key=value
 */

import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";

import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

import {
  type Goal,
  type State,
  type Status,
  appendLedger,
  archiveDir,
  archivedGoalPath,
  buildTaskList,
  buildTaskSummary,
  DEFAULT_TOKEN_LIMIT,
  mergeSettings,
  parseListImport,
  resolveImportFile,
  routeGoalArgs,
  sumNewAssistantTokens,
  takeAt,
  goalArgsNeedDrafting,
  buildSeedGrillMessage,
  draftProposalBlock,
  type TaskProposal,
  validateTaskProposal,
  cloneGoal,
  ensureDirs,
  findNextPendingTask,
  goalMdPath,
  newGoalId,
  nowIso,
  piGlaDir,
  readState,
  renderGoalMarkdown,
  statusLabel,
  writeGoalMd,
} from "../goal-loop-core.js";
import { runGoalCompletionAuditor } from "../goal-loop-auditor.js";
import { buildStatusText, buildWidgetLines, type AuditDisplayProgress } from "../goal-loop-display.js";
import {
  applyMeasurement,
  applyRefinement,
  loopBranchName,
  parseLoopStartArgs,
  parseMetric,
  type LoopState,
} from "../goal-loop-forever.js";
import {
  accountTurnForNudges,
  BACKOFF_HARD_CAP_MS,
  BACKOFF_IDLE_RETRY_MS,
  backoffMs,
  HEARTBEAT_INTERVAL_MS,
  HEARTBEAT_MAX_NUDGES,
  HEARTBEAT_STALL_MS,
  humanMs,
  shouldHeartbeatRefire,
  shouldPauseAfterBackoff,
} from "../goal-loop-backoff.js";

// =================================================================
// Constants
// =================================================================

const GOAL_EVENT_ENTRY = "goal-event";
const STATE_ENTRY = "goal-state";

// =================================================================
// Module-level state (one per session)
// =================================================================

// The ExtensionAPI captured in the factory. sendMessage lives on the API,
// not on ExtensionContext, so continuation sends need it at module scope.
let extensionApi: ExtensionAPI | null = null;

// The most recent ExtensionContext seen from any event or command handler.
// pi replaces sessions (newSession/fork/reload) and stale ctx throws on use,
// so timers must never capture a ctx — they read lastCtx at fire time.
let lastCtx: ExtensionContext | null = null;

function rememberCtx(ctx: ExtensionContext): void {
  lastCtx = ctx;
}

let state: State = { goal: null };

// Drafting mode: a no-arg loop command starts a clarification turn; the agent
// must call propose_goal_draft / propose_loop_draft, which opens the user's
// Confirm dialog. The target decides where the confirmed contract lands.
let draftingTarget: "goal" | "list" | "loop" | null = null;
// v0.14.0 drafting floor: user replies counted while drafting; the injected
// seed prompt itself arrives as a user message — skip exactly that one.
let draftingUserReplies = 0;
let draftingSeedInFlight = false;

// Dedup set for token accounting (agent_end may replay seen messages).
const countedTokenMessages = new Set<string>();
const countedLoopTokenMessages = new Set<string>();

// Heartbeat self-watchdog state: liveness is the loop's own job.
let lastActivityAt = Date.now();
let heartbeatNudges = 0;
let heartbeatTimer: NodeJS.Timeout | null = null;

function noteActivity(): void {
  lastActivityAt = Date.now();
}

function isSupervising(): boolean {
  return isLoopActive() || (!!state.goal && state.goal.status === "active" && state.goal.autoContinue);
}

// =================================================================
// Live TUI (v0.9.0): persistent status segment + above-editor widget.
// "Can't tell if it's on" is a bug, not a nice-to-have.
// =================================================================

let latestAuditProgress: AuditDisplayProgress | null = null;
let uiTicker: NodeJS.Timeout | null = null;

function refreshUI(ctx: ExtensionContext): void {
  if (!ctx.hasUI) return;
  try {
    ctx.ui.setStatus("pi-gla", buildStatusText(state, latestAuditProgress));
    ctx.ui.setWidget("pi-gla", buildWidgetLines(state, latestAuditProgress));
  } catch {
    // stale ctx — next event refreshes
  }
}

function startUITicker(): void {
  if (uiTicker) return;
  uiTicker = setInterval(() => {
    const ctx = freshCtx();
    if (ctx && isSupervising()) refreshUI(ctx);
  }, 5_000);
  uiTicker.unref?.();
}

function heartbeatTick(): void {
  const ctx = freshCtx();
  if (!ctx) return;
  let sessionIdle = false;
  try {
    sessionIdle = ctx.isIdle() && !ctx.hasPendingMessages();
  } catch {
    return;
  }
  const fire = shouldHeartbeatRefire({
    supervising: isSupervising(),
    sessionIdle,
    timerPending: continuationTimer !== null || loopTimer !== null,
    msSinceActivity: Date.now() - lastActivityAt,
    stallMs: HEARTBEAT_STALL_MS,
  });
  if (!fire) return;
  noteActivity();
  appendLedger(ctx.cwd, "heartbeat_refire", { nudgesSoFar: heartbeatNudges });
  ctx.ui.notify("Heartbeat: supervisor active but session stalled — re-firing continuation.", "info");
  if (isLoopActive()) {
    scheduleLoopTick(ctx);
  } else {
    scheduleContinuation(ctx, true);
  }
}

function startHeartbeat(): void {
  if (heartbeatTimer) return;
  heartbeatTimer = setInterval(heartbeatTick, HEARTBEAT_INTERVAL_MS);
  heartbeatTimer.unref?.();
}
let continuationTimer: NodeJS.Timeout | null = null;
let continuationScheduledFor: string | null = null;
let iterationCounter = 0;
let toolCallsThisTurn = 0;
let consecutiveStuckIterations = 0;
let consecutiveErrorIterations = 0;
let consecutiveNoToolIterations = 0;

// =================================================================
// Helpers
// =================================================================

function clearContinuationTimer(): void {
  if (continuationTimer) {
    clearTimeout(continuationTimer);
    continuationTimer = null;
  }
  continuationScheduledFor = null;
}

function isActionableGoal(): boolean {
  return !!state.goal && state.goal.status === "active" && state.goal.autoContinue;
}

function freshCtx(): ExtensionContext | null {
  // A captured ctx throws "stale" after session replacement. Probe cheaply;
  // on stale, drop it and wait for the next event to hand us a fresh one.
  if (!lastCtx) return null;
  try {
    lastCtx.isIdle();
    return lastCtx;
  } catch {
    lastCtx = null;
    return null;
  }
}

function scheduleContinuation(ctx: ExtensionContext, force = false): void {
  if (!isActionableGoal()) return;
  rememberCtx(ctx);
  const goalId = state.goal!.id;
  if (!force && continuationScheduledFor === goalId) return;
  clearContinuationTimer();
  let delay = 0;
  try {
    delay = ctx.isIdle() && !ctx.hasPendingMessages() ? 0 : BACKOFF_IDLE_RETRY_MS;
  } catch {
    return;
  }
  continuationScheduledFor = goalId;
  continuationTimer = setTimeout(() => sendContinuation(goalId), delay);
  continuationTimer.unref?.();
}

function sendContinuation(goalId: string): void {
  continuationTimer = null;
  continuationScheduledFor = null;
  if (!isActionableGoal()) return;
  const ctx = freshCtx();
  if (!ctx) {
    // No live ctx — retry shortly; the next session event will refresh it.
    continuationScheduledFor = goalId;
    continuationTimer = setTimeout(() => sendContinuation(goalId), BACKOFF_IDLE_RETRY_MS);
    continuationTimer.unref?.();
    return;
  }
  if (!ctx.isIdle() || ctx.hasPendingMessages()) {
    continuationScheduledFor = goalId;
    continuationTimer = setTimeout(() => sendContinuation(goalId), BACKOFF_IDLE_RETRY_MS);
    continuationTimer.unref?.();
    return;
  }
  if (!extensionApi) return;
  try {
    extensionApi.sendMessage({
      customType: GOAL_EVENT_ENTRY,
      content: continuationPrompt(state.goal!),
      display: false,
    }, { triggerTurn: true, deliverAs: "followUp" });
  } catch {
    // API went stale mid-flight; next agent_end/session_start will reschedule.
  }
}

function continuationPrompt(goal: Goal): string {
  // Read the .md file as the template, then substitute {{tokens}}.
  // For v0.1.0 we inline-substitute so we don't need fs at runtime.
  const next = findNextPendingTask(goal.taskList?.tasks ?? []);
  const nextBlock = next
    ? `**Next pending task**: \`${next.id}\` — ${next.title}`
    : "**Next pending task**: (none — only call complete_goal when the objective is satisfied)";
  const taskSummary = goal.taskList?.tasks.length
    ? buildTaskSummary(goal.taskList.tasks)
    : "(no task list)";
  const tmplPath = path.resolve(__dirname, "..", "..", "prompts", "goal-loop-continuation.md");
  let tmpl: string;
  try {
    tmpl = fs.readFileSync(tmplPath, "utf-8");
  } catch {
    tmpl = "[template-not-found]";
  }
  return tmpl
    .replace(/\$\{GOAL_ID\}/g, goal.id)
    .replace(/\$\{OBJECTIVE\}/g, goal.objective)
    .replace(/\$\{VERIFICATION_CONTRACT\}/g, goal.verificationContract || "(none — auditor will decide based on objective)")
    .replace(/\$\{TASK_LIST\}/g, taskSummary)
    .replace(/\$\{NEXT_PENDING_TASK_BLOCK\}/g, nextBlock);
}

// =================================================================
// Goal lifecycle
// =================================================================

function createGoal(objective: string, ctx: ExtensionContext, policy: "goal" | "list" = "goal"): Goal {
  ensureDirs(ctx.cwd);
  // Extract verification contract if present in objective.
  const { objective: cleanObj, verificationContract } = extractVerificationContract(objective);
  const id = newGoalId();
  const goal: Goal = {
    id,
    objective: cleanObj,
    status: "active",
    policy,
    autoContinue: true,
    verificationContract: verificationContract || "",
    usage: { tokensUsed: 0, tokensLimit: loadSettings(ctx.cwd).tokenLimit ?? DEFAULT_TOKEN_LIMIT },
    createdAt: nowIso(),
    updatedAt: nowIso(),
  };
  return goal;
}

function extractVerificationContract(raw: string): { objective: string; verificationContract: string } {
  // Line-based first: a marker at line start begins the contract block.
  const lines = raw.split("\n");
  let mode: "obj" | "verify" = "obj";
  const objParts: string[] = [];
  const verifyParts: string[] = [];
  for (const line of lines) {
    const lower = line.toLowerCase();
    if (lower.match(/^\s*(?:done when|verify|verified when|verification|done):/)) {
      mode = "verify";
    }
    if (mode === "obj") objParts.push(line);
    else verifyParts.push(line);
  }
  let objective = objParts.join("\n").trim();
  let verificationContract = verifyParts.join("\n").trim();

  // Inline fallback: users write one-liners like
  //   "Create x.txt. Done when: grep -q ok x.txt"
  // where the marker is mid-line. Split at the first inline marker.
  if (!verificationContract) {
    const m = raw.match(/^(.*?)(?:\.|;)??\s+(done when|verified when|verify|verification)\s*:\s*(.+)$/is);
    if (m) {
      objective = (m[1] ?? "").trim().replace(/[.;]\s*$/, "");
      verificationContract = (m[3] ?? "").trim();
    }
  }
  return { objective, verificationContract };
}

function persistState(ctx: ExtensionContext): void {
  appendLedger(ctx.cwd, "state", { goal: state.goal, list: state.list ?? [], loop: state.loop ?? null });
  refreshUI(ctx); // every state transition flows through here → the TUI is always current
}

function setGoal(goal: Goal, ctx: ExtensionContext): void {
  state = { goal, list: state.list ?? [] }; // preserve the queue!
  const file = writeGoalMd(ctx.cwd, goal);
  state.goal!.activePath = path.relative(ctx.cwd, file) || file;
  persistState(ctx);
  appendLedger(ctx.cwd, "goal_created", { goalId: goal.id, objective: goal.objective, policy: goal.policy });
}

function updateGoal(patch: Partial<Goal>, ctx: ExtensionContext): void {
  if (!state.goal) return;
  state.goal = { ...state.goal, ...patch, updatedAt: nowIso() };
  const file = writeGoalMd(ctx.cwd, state.goal);
  state.goal.activePath = path.relative(ctx.cwd, file) || file;
  persistState(ctx);
}

function archiveCurrentGoal(ctx: ExtensionContext, status: Status, stopReason?: string): void {
  if (!state.goal) return;
  const goal = state.goal;
  ensureDirs(ctx.cwd);
  const target = archivedGoalPath(ctx.cwd, goal.id);
  const md = renderGoalMarkdown({ ...goal, status, stopReason });
  fs.writeFileSync(target, md);
  // Remove active md file
  try { fs.unlinkSync(goalMdPath(ctx.cwd, goal.id)); } catch {}
  state = { goal: { ...goal, status, archivedPath: path.relative(ctx.cwd, target) || target, stopReason }, list: state.list ?? [] };
  appendLedger(ctx.cwd, "goal_archived", { goalId: goal.id, status, stopReason });
  persistState(ctx);
  // Loop 2: a list-sourced goal COMPLETED → auto-activate the next item.
  // Aborts are user actions (/list next, /goal cancel, list_activate) which
  // pick their own next step — auto-advancing on abort double-activates
  // (v0.2.0 bug: bare /list next silently consumed TWO items, found by the
  // pick-any-item verification in v0.10.0).
  if (goal.policy === "list" && status === "complete") {
    activateNextListItem(ctx);
  }
}

// =================================================================
// Loop 2: /list list
// =================================================================

function listQueue(): NonNullable<State["list"]> {
  return state.list ?? [];
}

function activateNextListItem(ctx: ExtensionContext, n = 1): boolean {
  const queue = listQueue();
  const taken = takeAt(queue, n);
  if (!taken) return false;
  const [next, rest] = taken;
  state = { ...state, list: rest };
  const goal = createGoal(next.objective, ctx, "list");
  if (next.verificationContract) goal.verificationContract = next.verificationContract;
  setGoal(goal, ctx);
  iterationCounter = 0;
  consecutiveStuckIterations = 0;
  consecutiveErrorIterations = 0;
  ctx.ui.notify(`List item #${n} activated (${rest.length} remaining): ${goal.objective.slice(0, 80)}`, "info");
  scheduleContinuation(ctx, true);
  return true;
}

// =================================================================
// Drafting: /goal with no args → clarify → Confirm dialog → activate
// =================================================================

async function startDrafting(ctx: ExtensionContext, target: "goal" | "list" | "loop", seed?: string): Promise<void> {
  draftingTarget = target;
  const prompts: Record<string, [string, string, string]> = {
    goal: ["goal-loop-draft.md", "Goal drafting", "propose_goal_draft"],
    list: ["goal-loop-draft.md", "Goal drafting (for the queue)", "propose_goal_draft"],
    loop: ["goal-loop-forever-draft.md", "Loop drafting", "propose_loop_draft"],
  };
  const [file, label, tool] = prompts[target]!;
  ctx.ui.notify(
    seed
      ? `${label}: the objective has no "Done when:" clause — the agent will grill you about it first (nothing activates until you confirm).`
      : `${label} started. The agent will grill until the contract is concrete, then ${tool} opens a Confirm dialog. No work begins before confirmation.`,
    "info",
  );
  const tmplPath = path.resolve(__dirname, "..", "..", "prompts", file);
  let tmpl: string;
  try {
    tmpl = fs.readFileSync(tmplPath, "utf-8");
    if (target === "list") {
      tmpl = tmpl.replace(
        "[GOAL DRAFTING]",
        "[GOAL DRAFTING — the confirmed goal goes into the /list LIST, it does not activate immediately. If the user wants MANY things queued (a plan, a checklist, 'these 50 tasks'), propose them ALL AT ONCE with the items[] parameter — one Confirm for the whole batch, never 50 separate proposals.]",
      );
    }
  } catch {
    tmpl = `[DRAFTING] Clarify the user's ${target}, then call ${tool}.`;
  }
  // v0.14.0: the LLM grills (its strength — v0.13.0's canned questionnaire
  // accepted non-answers), the plugin enforces the floor: propose_goal_draft
  // is blocked until the user has replied at least once (see message_start).
  if (seed) {
    tmpl = buildSeedGrillMessage(tmpl, seed, tool);
  }
  try {
    extensionApi?.sendUserMessage(tmpl, { deliverAs: ctx.isIdle() ? "followUp" : "steer" });
    draftingUserReplies = 0;
    draftingSeedInFlight = true; // our injected prompt also arrives as a user message — don't count it
  } catch {
    draftingTarget = null;
  }
}

// =================================================================
// /goal router (v0.8.0): subcommands route to their handlers; everything
// else is an objective (draft if empty, set+start otherwise).
// =================================================================

async function cmdGoal(args: string, ctx: ExtensionContext): Promise<void> {
  const route = routeGoalArgs(args);
  if (route.kind === "sub") {
    if (route.name === "status") return cmdStatus(ctx);
    if (route.name === "pause") return cmdPause(ctx);
    if (route.name === "resume") return cmdResume(ctx);
    if (route.name === "cancel") return cmdCancel(ctx);
    if (route.name === "tweak") return cmdTweak(route.rest, ctx);
    if (route.name === "archive") return cmdGoals(ctx);
  }
  return cmdSet(route.kind === "set" ? route.text : "", ctx);
}

// =================================================================
// /goal: bypass drafting, start now (the only entry in v0.1.0)
// =================================================================

async function cmdSet(args: string, ctx: ExtensionContext): Promise<void> {
  let raw = args.trim();
  // Users naturally quote the objective ("/goal \"do X\""); strip one layer of
  // surrounding matching quotes so they don't leak into the goal text.
  if (raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))) {
    raw = raw.slice(1, -1).trim();
  }
  if (!raw) {
    await startDrafting(ctx, "goal");
    return;
  }
  if (isLoopActive()) {
    ctx.ui.notify("A /loop is active — /loop stop it before setting a goal.", "warning");
    return;
  }
  // v0.11.0: a contract-less objective gets drafted, not activated raw —
  // the pi-goal-x lesson: arg + Enter is worse than a 5-minute draft.
  // Include an explicit "Done when: …" clause to activate instantly.
  if (goalArgsNeedDrafting(raw)) {
    await startDrafting(ctx, "goal", raw);
    return;
  }
  draftingTarget = null; // explicit objective cancels any drafting session
  const goal = createGoal(raw, ctx);
  setGoal(goal, ctx);
  // Reset counters
  iterationCounter = 0;
  consecutiveStuckIterations = 0;
  consecutiveErrorIterations = 0;
  consecutiveNoToolIterations = 0;
  ctx.ui.notify(`Goal ${goal.id} created — starting now. Auditor will verify on completion.`, "info");
  scheduleContinuation(ctx, true);
}

async function cmdStatus(ctx: ExtensionContext): Promise<void> {
  if (!state.goal) {
    ctx.ui.notify("No active goal. Use /goal <objective>.", "info");
    return;
  }
  const g = state.goal;
  const lines = [
    `[${g.id}] ${statusLabel(g.status)}`,
    `Objective: ${g.objective}`,
    `Auto-continue: ${g.autoContinue ? "on" : "off"}`,
    `Iteration: ${iterationCounter}`,
    `Tokens: ${(g.usage?.tokensUsed ?? 0).toLocaleString()}${(g.usage?.tokensLimit ?? 0) > 0 ? ` / ${(g.usage!.tokensLimit).toLocaleString()}` : " (no cap — /gla tokenlimit=<n> to set)"}`,
  ];
  if (g.auditHistory && g.auditHistory.length > 0) {
    lines.push(`Audits: ${g.auditHistory.length} (${g.auditHistory.filter((v) => v.approved).length} approved)`);
  }
  if (g.pauseReason) lines.push(`Paused: ${g.pauseReason}`);
  ctx.ui.notify(lines.join("\n"), "info");
}

async function cmdPause(ctx: ExtensionContext): Promise<void> {
  if (!state.goal) return;
  updateGoal({ status: "paused" }, ctx);
  ctx.ui.notify(`Goal ${state.goal.id} paused. /goal resume to continue.`, "info");
}

async function cmdResume(ctx: ExtensionContext): Promise<void> {
  if (!state.goal || state.goal.status !== "paused") return;
  // v0.12.0: refresh the token cap from CURRENT settings on resume — goals
  // snapshot the cap at creation, so a goal paused under an old default
  // (e.g. 10M) would re-pause instantly even after the default changed.
  const freshLimit = loadSettings(ctx.cwd).tokenLimit ?? DEFAULT_TOKEN_LIMIT;
  const usage = state.goal.usage
    ? { tokensUsed: state.goal.usage.tokensUsed, tokensLimit: freshLimit }
    : undefined;
  updateGoal({ status: "active", pauseReason: undefined, pauseSuggestedAction: undefined, ...(usage ? { usage } : {}) }, ctx);
  scheduleContinuation(ctx, true);
}

async function cmdCancel(ctx: ExtensionContext): Promise<void> {
  if (!state.goal) return;
  archiveCurrentGoal(ctx, "aborted", "user cancelled");
  ctx.abort();
  ctx.ui.notify("Goal aborted.", "info");
}

async function cmdGoals(ctx: ExtensionContext): Promise<void> {
  const dir = archiveDir(ctx.cwd);
  if (!fs.existsSync(dir)) {
    ctx.ui.notify("No archived goals yet.", "info");
    return;
  }
  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort().reverse();
  if (files.length === 0) {
    ctx.ui.notify("No archived goals yet.", "info");
    return;
  }
  const lines = files.slice(0, 20).map((f) => {
    let status = "?";
    let stop = "";
    let obj = "";
    try {
      const content = fs.readFileSync(path.join(dir, f), "utf-8");
      status = content.match(/\*\*Status\*\*:\s*(\w+)/)?.[1] ?? "?";
      stop = content.match(/\*\*Stop reason\*\*:\s*(.+)/)?.[1]?.trim() ?? "";
      obj = content.match(/## Objective\s+>\s*(.+)/)?.[1]?.trim() ?? "";
    } catch { /* unreadable file — show name only */ }
    return `${f.replace(/\.md$/, "")} [${status}] ${obj.slice(0, 60)}${stop ? ` — ${stop.slice(0, 40)}` : ""}`;
  });
  ctx.ui.notify(
    `Archived goals (${files.length}${files.length > 20 ? ", showing 20" : ""}):\n` + lines.join("\n"),
    "info",
  );
}

async function cmdTweak(args: string, ctx: ExtensionContext): Promise<void> {
  if (!state.goal || state.goal.status !== "active") {
    ctx.ui.notify("No active goal to tweak. /goal <objective> to start one.", "info");
    return;
  }
  let raw = args.trim();
  if (raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))) {
    raw = raw.slice(1, -1).trim();
  }
  if (!raw) {
    ctx.ui.notify("Usage: /goal tweak <replacement objective, optional 'Done when: ...' clause>", "info");
    return;
  }
  const current = state.goal;
  const proposed = extractVerificationContract(raw);
  const newObjective = proposed.objective;
  const newContract = proposed.verificationContract;
  let confirmed = false;
  try {
    confirmed = await ctx.ui.confirm(
      "Tweak goal?",
      `CURRENT:\n${current.objective.slice(0, 400)}\n\nNEW:\n${newObjective.slice(0, 400)}` +
      (newContract ? `\n\nNew contract:\n${newContract.slice(0, 200)}` : "\n\n(New text carries no contract; old contract is dropped.)"),
    );
  } catch {
    confirmed = false;
  }
  if (!confirmed) {
    ctx.ui.notify("Tweak cancelled; goal unchanged.", "info");
    return;
  }
  updateGoal({ objective: newObjective, verificationContract: newContract }, ctx);
  appendLedger(ctx.cwd, "goal_tweaked", { goalId: current.id, objective: newObjective });
  ctx.ui.notify("Goal tweaked. The loop continues against the new objective.", "info");
  scheduleContinuation(ctx, true);
}

// =================================================================
// /list commands (loop 2)
// =================================================================

/**
 * The ONE enqueue path (v0.8.4): bulk import, items[] drafting, and the
 * agent's list_add tool all funnel here. Texts → ListItems (with per-item
 * contract extraction) → appended to the queue → persisted → first item
 * activated when nothing is running. Returns the count enqueued.
 */
function enqueueItems(ctx: ExtensionContext, texts: string[], source: string): number {
  const items = texts.map((text) => {
    const extracted = extractVerificationContract(text);
    return { id: newGoalId(), objective: extracted.objective, verificationContract: extracted.verificationContract || undefined, addedAt: nowIso() };
  });
  state = { ...state, list: [...listQueue(), ...items] };
  persistState(ctx);
  appendLedger(ctx.cwd, "list_imported", { source, count: items.length });
  if (!state.goal || state.goal.status === "complete" || state.goal.status === "aborted") {
    activateNextListItem(ctx);
  }
  return items.length;
}

/** Bulk-enqueue parsed items: one Confirm for the whole batch, never drafts. */
async function bulkAddItems(ctx: ExtensionContext, parsed: string[], sourceName: string): Promise<void> {
  if (parsed.length === 0) {
    ctx.ui.notify("No items found (headings/blank lines don't count).", "warning");
    return;
  }
  const preview = parsed.slice(0, 5).map((t, i) => `  ${i + 1}. ${t.slice(0, 70)}`).join("\n");
  let confirmed = true;
  if (ctx.hasUI) {
    try {
      confirmed = await ctx.ui.confirm(
        "Import into queue?",
        `${parsed.length} items from ${sourceName}:\n${preview}${parsed.length > 5 ? `\n  … and ${parsed.length - 5} more` : ""}`,
      );
    } catch {
      confirmed = false;
    }
  }
  if (!confirmed) {
    ctx.ui.notify("Import cancelled.", "info");
    return;
  }
  const n = enqueueItems(ctx, parsed, sourceName);
  if (state.goal && state.goal.status === "active") {
    ctx.ui.notify(`Imported ${n} items (${listQueue().length} queued).`, "info");
  }
}

/** Bulk-enqueue from a file: read, parse, delegate to bulkAddItems. */
async function bulkAddFromFile(ctx: ExtensionContext, abs: string): Promise<void> {
  let content: string;
  try {
    content = fs.readFileSync(abs, "utf-8");
  } catch {
    ctx.ui.notify(`Cannot read: ${abs}`, "warning");
    return;
  }
  await bulkAddItems(ctx, parseListImport(content), path.basename(abs));
}

async function cmdList(args: string, ctx: ExtensionContext): Promise<void> {
  const parts = args.trim().split(/\s+/);
  const sub = (parts[0] ?? "").toLowerCase();
  const rest = args.trim().slice(sub.length).trim();

  if (!sub || sub === "show") {
    const queue = listQueue();
    const lines: string[] = [];
    if (state.goal) {
      lines.push(`Active: [${state.goal.policy}] ${state.goal.objective.slice(0, 80)} (${statusLabel(state.goal.status)})`);
    } else {
      lines.push("Active: (none)");
    }
    if (queue.length === 0) {
      lines.push("List: empty. /list add <objective> | /list add <file>");
    } else {
      lines.push(`Queue (${queue.length}):`);
      const PAGE = 15;
      queue.slice(0, PAGE).forEach((item, i) => lines.push(`  ${i + 1}. ${item.objective.slice(0, 90)}`));
      if (queue.length > PAGE) {
        lines.push(`  … and ${queue.length - PAGE} more. /list remove <n> to prune, /list clear to empty.`);
      }
    }
    ctx.ui.notify(lines.join("\n"), "info");
    return;
  }


  if (sub === "import") {
    // Backwards-compat alias (0.8.1 shipped it; 0.8.2 folded it into add).
    const abs = resolveImportFile(ctx.cwd, rest.replace(/^["']|["']$/g, ""));
    if (!abs) {
      ctx.ui.notify("Usage: /list add <path> — file detection is automatic now; 'import' is just an alias", "info");
      return;
    }
    await bulkAddFromFile(ctx, abs);
    return;
  }

  if (sub === "add") {
    let raw = rest;
    if (raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))) {
      raw = raw.slice(1, -1).trim();
    }
    if (!raw) {
      // /list add with no args → draft a confirmed contract INTO THE QUEUE.
      await startDrafting(ctx, "list");
      return;
    }
    // Flexible by detection, not by verb: an existing file path bulk-imports,
    // multi-line pasted text parses as a batch, anything else is one objective.
    const importFile = resolveImportFile(ctx.cwd, raw);
    if (importFile) {
      await bulkAddFromFile(ctx, importFile);
      return;
    }
    if (raw.includes("\n")) {
      const pasted = parseListImport(raw);
      if (pasted.length > 1) {
        await bulkAddItems(ctx, pasted, "pasted text");
        return;
      }
    }
    const { objective, verificationContract } = extractVerificationContract(raw);
    const item = { id: newGoalId(), objective, verificationContract: verificationContract || undefined, addedAt: nowIso() };
    state = { ...state, list: [...listQueue(), item] };
    persistState(ctx);
    appendLedger(ctx.cwd, "list_added", { id: item.id, objective: item.objective });
    // Nothing active → activate immediately.
    if (!state.goal || state.goal.status === "complete" || state.goal.status === "aborted") {
      activateNextListItem(ctx);
    } else {
      ctx.ui.notify(`Queued (${listQueue().length} waiting): ${objective.slice(0, 80)}`, "info");
    }
    return;
  }

  if (sub === "clear") {
    state = { ...state, list: [] };
    persistState(ctx);
    appendLedger(ctx.cwd, "list_cleared", {});
    ctx.ui.notify("List cleared. Active goal (if any) is untouched — /goal cancel for that.", "info");
    return;
  }

  if (sub === "next") {
    // Skip the current active goal (abort it) and activate a queued item.
    // Bare = the head (FIFO default); /list next <n> = item n (shopping-list
    // semantics: order is the default, not the law).
    const n = rest ? Number.parseInt(rest, 10) : 1;
    if (!Number.isInteger(n) || n < 1) {
      ctx.ui.notify(`Usage: /list next [1-${listQueue().length || 1}]`, "info");
      return;
    }
    if (state.goal && state.goal.status === "active") {
      archiveCurrentGoal(ctx, "aborted", `skipped via /list next ${n > 1 ? n : ""}`.trim());
    }
    if (!activateNextListItem(ctx, n)) {
      ctx.ui.notify(listQueue().length === 0 ? "List is empty — nothing to activate." : `No item #${n} (list has ${listQueue().length}).`, "info");
    }
    return;
  }

  if (sub === "remove" || sub === "rm") {
    const n = Number.parseInt(rest, 10);
    const queue = listQueue();
    if (!Number.isFinite(n) || n < 1 || n > queue.length) {
      ctx.ui.notify(`Usage: /list remove <1-${queue.length}>`, "info");
      return;
    }
    const removed = queue[n - 1]!;
    state = { ...state, list: queue.filter((_, i) => i !== n - 1) };
    persistState(ctx);
    appendLedger(ctx.cwd, "list_removed", { id: removed.id, objective: removed.objective });
    ctx.ui.notify(`Removed: ${removed.objective.slice(0, 80)}`, "info");
    return;
  }

  ctx.ui.notify("Usage: /list [show] | /list add <objective or file> | /list next | /list remove <n> | /list clear", "info");
}

/**
 * Config-gated push notification: if settings.notifyCmd is set, shell out
 * with the message as $1. Fire-and-forget — a broken notify command never
 * blocks the loop. /gla notify='<cmd>' to configure.
 */
function notifyExternal(ctx: ExtensionContext, message: string): void {
  try {
    const settings = loadSettings(ctx.cwd);
    const cmd = settings.notifyCmd;
    if (!cmd || !extensionApi) return;
    void extensionApi.exec("bash", ["-c", cmd, "pi-goal-list-loop-audit", message], { cwd: ctx.cwd }).catch(() => {});
  } catch {
    // non-fatal by design
  }
}

// =================================================================
// Loop 3: /loop — metric-driven forever loop
//
// The anti-doorknob law: the loop only believes a number. The orchestrator
// runs the user's measure command (via pi.exec) after every agent turn;
// the agent never self-reports progress. Termination: plateau, iteration
// cap, or /loop stop. There is NO auditor in loop 3 — the metric is the
// verdict.
// =================================================================

let loopTimer: NodeJS.Timeout | null = null;

function clearLoopTimer(): void {
  if (loopTimer) {
    clearTimeout(loopTimer);
    loopTimer = null;
  }
}

function isLoopActive(): boolean {
  return !!state.loop?.active;
}

/** Run the user's measure command. Orchestrator-side, never agent-side. */
async function runMeasure(ctx: ExtensionContext, cmd: string): Promise<number | null> {
  if (!extensionApi) return null;
  try {
    const result = await extensionApi.exec("bash", ["-c", cmd], { cwd: ctx.cwd });
    const stdout = (result as any)?.stdout ?? "";
    return parseMetric(String(stdout));
  } catch {
    return null;
  }
}

/** git wrapper for branch=1 mode. Returns {ok, stdout}; never throws. */
async function runGit(ctx: ExtensionContext, args: string[]): Promise<{ ok: boolean; stdout: string }> {
  if (!extensionApi) return { ok: false, stdout: "" };
  try {
    const result = await extensionApi.exec("git", args, { cwd: ctx.cwd });
    const r = result as any;
    const code = typeof r?.code === "number" ? r.code : (r?.exitCode ?? 1);
    return { ok: code === 0, stdout: String(r?.stdout ?? "").trim() };
  } catch {
    return { ok: false, stdout: "" };
  }
}

function loopPrompt(loop: LoopState, regressionNote: string, strategyNote: string, boundsNote: string): string {
  const tmplPath = path.resolve(__dirname, "..", "..", "prompts", "goal-loop-forever.md");
  let tmpl: string;
  try {
    tmpl = fs.readFileSync(tmplPath, "utf-8");
  } catch {
    tmpl = `[LOOP ITERATION ${loop.iteration + 1}] Target: ${loop.target}. Measure: ${loop.measureCmd} (${loop.direction}). Make ONE small change to improve the metric.`;
  }
  return tmpl
    .replace(/\$\{ITERATION\}/g, String(loop.iteration + 1))
    .replace(/\$\{TARGET\}/g, loop.target)
    .replace(/\$\{MEASURE_CMD\}/g, loop.measureCmd)
    .replace(/\$\{DIRECTION\}/g, loop.direction)
    .replace(/\$\{DIRECTION_WORD\}/g, loop.direction === "min" ? "lower is better" : "higher is better")
    .replace(/\$\{LAST_VALUE\}/g, loop.lastValue === null ? "(none yet)" : String(loop.lastValue))
    .replace(/\$\{BEST_VALUE\}/g, loop.bestValue === null ? "(none yet)" : String(loop.bestValue))
    .replace(/\$\{STALL_COUNT\}/g, String(loop.stallCount))
    .replace(/\$\{PLATEAU_WINDOW\}/g, String(loop.plateauWindow))
    .replace(/\$\{REGRESSION_NOTE\}/g, regressionNote)
    .replace(/\$\{STRATEGY_NOTE\}/g, strategyNote)
    .replace(/\$\{BOUNDS_NOTE\}/g, boundsNote);
}

function scheduleLoopTick(ctx: ExtensionContext): void {
  if (!isLoopActive()) return;
  rememberCtx(ctx);
  clearLoopTimer();
  let delay = 0;
  try {
    delay = ctx.isIdle() && !ctx.hasPendingMessages() ? 0 : BACKOFF_IDLE_RETRY_MS;
  } catch {
    return;
  }
  loopTimer = setTimeout(() => sendLoopTurn(), delay);
  loopTimer.unref?.();
}

function sendLoopTurn(): void {
  loopTimer = null;
  if (!isLoopActive() || !extensionApi) return;
  const ctx = freshCtx();
  if (!ctx || !ctx.isIdle() || ctx.hasPendingMessages()) {
    loopTimer = setTimeout(() => sendLoopTurn(), BACKOFF_IDLE_RETRY_MS);
    loopTimer.unref?.();
    return;
  }
  const loop = state.loop!;
  const regressedLast = loop.history.length > 0 && !loop.history[loop.history.length - 1]!.improved && loop.lastValue !== null;
  const regressionNote = regressedLast
    ? "**Your last change REGRESSED the metric. Undo it first, then try a different small change.**"
    : "";
  // Strategy rotation (from pi-loop-mode's one good idea): one stall before
  // the plateau window closes, stop polishing and change approach entirely.
  const strategyNote = loop.stallCount >= loop.plateauWindow - 1 && loop.stallCount > 0
    ? "**You are one stall from a plateau stop. Small tweaks are not working — try a FUNDAMENTALLY different approach: different file, different technique, or revert and rethink the angle of attack.**"
    : "";
  // v0.15.0: arbitrary bounds (never "completion") — surface what's armed.
  const bounds: string[] = [];
  if (loop.timeLimitHours !== undefined) bounds.push(`${loop.timeLimitHours}h`);
  if (loop.tokenBudget !== undefined) bounds.push(`${loop.tokenBudget.toLocaleString()} tokens (used ${(loop.tokensUsed ?? 0).toLocaleString()})`);
  const boundsNote = bounds.length ? `\n- Arbitrary bounds: the loop also stops after ${bounds.join(" or ")}` : "";
  try {
    extensionApi.sendMessage({
      customType: GOAL_EVENT_ENTRY,
      content: loopPrompt(loop, regressionNote, strategyNote, boundsNote),
      display: false,
    }, { triggerTurn: true, deliverAs: "followUp" });
  } catch {
    // stale API — next agent_end reschedules
  }
}

/** agent_end hook for loop 3: measure → judge → continue or stop. */
async function runLoopTick(ctx: ExtensionContext, event?: any): Promise<void> {
  const loop = state.loop!;
  // v0.15.0: token budget is an arbitrary bound; accumulate orchestrator-side.
  if (event?.messages) {
    loop.tokensUsed = (loop.tokensUsed ?? 0) + sumNewAssistantTokens(event.messages as unknown[], countedLoopTokenMessages);
  }
  const value = await runMeasure(ctx, loop.measureCmd);
  // Hypothesis line (pi-autoresearch's good idea): the agent's stated intent
  // for the turn goes into the ledger, making loop history auditable.
  let hypothesis: string | undefined;
  if (event) {
    const last = [...(event.messages as any[])].reverse().find((m) => m.role === "assistant");
    const text = last && Array.isArray(last.content) ? last.content.filter((p: any) => p.type === "text").map((p: any) => p.text).join("\n") : "";
    hypothesis = text.match(/^HYPOTHESIS:\s*(.+)$/m)?.[1]?.trim().slice(0, 200);
  }
  const outcome = applyMeasurement(loop, value, nowIso());
  persistState(ctx);
  appendLedger(ctx.cwd, "loop_measured", {
    iteration: loop.iteration,
    value,
    best: loop.bestValue,
    stall: loop.stallCount,
    hypothesis,
  });
  // branch=1 mode: commit improvements, hard-reset regressions — always and
  // only on the scratch branch.
  if (loop.branchName && outcome.kind === "continue") {
    if (outcome.improved) {
      await runGit(ctx, ["add", "-A"]);
      const committed = await runGit(ctx, ["commit", "-m", `pi-gla-loop: iteration ${loop.iteration} (${loop.direction}=${loop.bestValue})`]);
      appendLedger(ctx.cwd, "loop_git", { action: "commit", iteration: loop.iteration, ok: committed.ok });
    } else {
      const reset = await runGit(ctx, ["reset", "--hard", "HEAD"]);
      appendLedger(ctx.cwd, "loop_git", { action: "reset", iteration: loop.iteration, ok: reset.ok });
    }
    persistState(ctx);
  }
  if (outcome.kind === "stop") {
    await finishLoopGit(ctx, loop);
    ctx.ui.notify(`Loop stopped: ${outcome.reason}. ${loop.history.length} iterations recorded.`, "info");
    appendLedger(ctx.cwd, "loop_stopped", { reason: outcome.reason, iterations: loop.iteration, best: loop.bestValue });
    notifyExternal(ctx, `Loop stopped: ${outcome.reason}`);
    return;
  }
  scheduleLoopTick(ctx);
}

/** On loop stop (any reason): return to the original branch, tell the user
 * where the work lives and how to merge it. Scratch branch is never deleted. */
async function finishLoopGit(ctx: ExtensionContext, loop: LoopState): Promise<void> {
  if (!loop.branchName) return;
  // Uncommitted remnants (final stalled iterations were reset already, but be safe).
  await runGit(ctx, ["reset", "--hard", "HEAD"]);
  if (loop.originalBranch) {
    await runGit(ctx, ["checkout", loop.originalBranch]);
  }
  ctx.ui.notify(
    `Loop work is on branch ${loop.branchName} (${loop.iteration} iterations, best ${loop.bestValue ?? "n/a"}).\nMerge with: git merge ${loop.branchName} — or delete with: git branch -D ${loop.branchName}`,
    "info",
  );
  appendLedger(ctx.cwd, "loop_git", { action: "finish", branch: loop.branchName, returnedTo: loop.originalBranch });
}

interface LoopConfig {
  target: string;
  measureCmd: string;
  direction: "min" | "max";
  plateauWindow: number;
  maxIterations: number;
  branch: boolean;
  force?: boolean;
  timeLimitHours?: number;
  tokenBudget?: number;
}

/** Shared loop-start path: /loop start AND propose_loop_draft (after Confirm). */
async function startLoopFromConfig(ctx: ExtensionContext, cfg: LoopConfig): Promise<boolean> {
  // branch=1 mode: scratch branch ONLY. Refuse on non-git or dirty tree —
  // we never mix uncommitted user work into the loop's branch.
  let branchName: string | undefined;
  let originalBranch: string | undefined;
  if (cfg.branch) {
    const isRepo = await runGit(ctx, ["rev-parse", "--is-inside-work-tree"]);
    if (!isRepo.ok) {
      ctx.ui.notify("branch=1 requires a git repository.", "warning");
      return false;
    }
    const dirty = await runGit(ctx, ["status", "--porcelain"]);
    if (!dirty.ok || dirty.stdout.length > 0) {
      ctx.ui.notify("branch=1 requires a clean working tree — commit or stash your changes first.", "warning");
      return false;
    }
    const current = await runGit(ctx, ["rev-parse", "--abbrev-ref", "HEAD"]);
    originalBranch = current.ok ? current.stdout : undefined;
    branchName = loopBranchName(nowIso(), cfg.target);
    const created = await runGit(ctx, ["checkout", "-b", branchName]);
    if (!created.ok) {
      ctx.ui.notify(`Failed to create scratch branch ${branchName}.`, "warning");
      return false;
    }
  }
  // Baseline measurement before the first agent turn. A measure that
  // produces no number is a footgun: without a baseline the loop burns stall
  // iterations before plateau stops it. Refuse fast (force=1 overrides for
  // measures that only work after the agent builds something first).
  const baseline = await runMeasure(ctx, cfg.measureCmd);
  if (baseline === null && !(cfg as { force?: boolean }).force) {
    ctx.ui.notify(
      `/loop start refused: the measure produced no number.\nCommand: ${cfg.measureCmd}\nFix it so it prints exactly one number, or re-run with force=1 if it only works after the agent builds something first.\n(Non-numeric goal — research, docs, features? Use /goal: the independent auditor verifies semantically. /loop only believes a number.)`,
      "warning",
    );
    return false;
  }
  state = {
    ...state,
    loop: {
      target: cfg.target,
      measureCmd: cfg.measureCmd,
      direction: cfg.direction,
      iteration: 0,
      maxIterations: cfg.maxIterations,
      plateauWindow: cfg.plateauWindow,
      stallCount: 0,
      bestValue: baseline,
      lastValue: baseline,
      active: true,
      history: [],
      startedAt: nowIso(),
      timeLimitHours: cfg.timeLimitHours,
      tokenBudget: cfg.tokenBudget,
      tokensUsed: 0,
      branchName,
      originalBranch,
    },
  };
  persistState(ctx);
  appendLedger(ctx.cwd, "loop_started", { target: cfg.target, measureCmd: cfg.measureCmd, direction: cfg.direction, baseline, branch: branchName, timeLimitHours: cfg.timeLimitHours, tokenBudget: cfg.tokenBudget });
  ctx.ui.notify(
    `Loop started: ${cfg.target.slice(0, 60)}\nBaseline: ${baseline ?? "(forced without a number — first turn must produce one)"} · direction ${cfg.direction} · window ${cfg.plateauWindow} · max ${cfg.maxIterations}` +
    (branchName ? `\nbranch mode: committing improvements to ${branchName}` : ""),
    "info",
  );
  scheduleLoopTick(ctx);
  return true;
}

async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
  const parts = args.trim().split(/\s+/);
  const sub = (parts[0] ?? "").toLowerCase();
  const rest = args.trim().slice(sub.length).trim();

  if (!sub) {
    // /loop with no args → draft the loop config (metric design is the whole
    // game for a long-running loop; never start one blind).
    if (isLoopActive()) {
      ctx.ui.notify("A loop is already active — /loop status to inspect, /loop stop to end it.", "info");
      return;
    }
    await startDrafting(ctx, "loop");
    return;
  }

  if (sub === "status") {
    const loop = state.loop;
    if (!loop) {
      ctx.ui.notify("No loop. /loop to draft one, or /loop start \"<target>\" measure=\"<cmd>\" direction=min|max [window=5] [max=50] [time=<hours>] [tokens=<budget>]", "info");
      return;
    }
    const lines = [
      `Loop: ${loop.active ? "active" : "stopped"} — ${loop.target.slice(0, 80)}`,
      `Metric: ${loop.measureCmd} (${loop.direction})`,
      `Iteration ${loop.iteration}/${loop.maxIterations} · best ${loop.bestValue ?? "n/a"} · last ${loop.lastValue ?? "n/a"} · stall ${loop.stallCount}/${loop.plateauWindow}`,
    ];
    const bounds: string[] = [];
    if (loop.timeLimitHours !== undefined) bounds.push(`time ≤ ${loop.timeLimitHours}h`);
    if (loop.tokenBudget !== undefined) bounds.push(`tokens ${(loop.tokensUsed ?? 0).toLocaleString()}/${loop.tokenBudget.toLocaleString()}`);
    if (bounds.length) lines.push(`Bounds: ${bounds.join(" · ")}`);
    if (loop.refinements?.length) lines.push(`Spec refined ${loop.refinements.length}× (latest: iteration ${loop.refinements[loop.refinements.length - 1]!.iteration})`);
    if (loop.stopReason) lines.push(`Stopped: ${loop.stopReason}`);
    const tail = loop.history.slice(-5);
    if (tail.length > 0) {
      lines.push("Recent: " + tail.map((h) => `${h.value ?? "ERR"}${h.improved ? "↑" : ""}`).join(" "));
    }
    ctx.ui.notify(lines.join("\n"), "info");
    return;
  }

  if (sub === "start") {
    if (state.goal && state.goal.status === "active") {
      ctx.ui.notify("A goal is active — /goal cancel or /goal pause it before starting a loop.", "warning");
      return;
    }
    if (isLoopActive()) {
      ctx.ui.notify("A loop is already active. /loop stop first.", "warning");
      return;
    }
    let cfg;
    try {
      cfg = parseLoopStartArgs(rest);
    } catch (err) {
      ctx.ui.notify(
        `/loop start: ${err instanceof Error ? err.message : String(err)}\n(Non-numeric goal — research, docs, features? Use /goal: the auditor verifies semantically. /loop only believes a number. Or /loop with no args to draft.)`,
        "warning",
      );
      return;
    }
    await startLoopFromConfig(ctx, cfg);
    return;
  }

  if (sub === "stop") {
    if (!state.loop) {
      ctx.ui.notify("No loop to stop.", "info");
      return;
    }
    clearLoopTimer();
    state.loop = { ...state.loop, active: false, stopReason: state.loop.stopReason ?? "stopped by user (/loop stop)" };
    persistState(ctx);
    await finishLoopGit(ctx, state.loop);
    appendLedger(ctx.cwd, "loop_stopped", { reason: "user", iterations: state.loop.iteration, best: state.loop.bestValue });
    ctx.ui.notify(
      `Loop stopped after ${state.loop.iteration} iterations. Best: ${state.loop.bestValue ?? "n/a"}.`,
      "info",
    );
    notifyExternal(ctx, `Loop stopped by user after ${state.loop.iteration} iterations (best: ${state.loop.bestValue ?? "n/a"})`);
    return;
  }

  ctx.ui.notify("Usage: /loop [status] | /loop start \"<target>\" measure=\"<cmd>\" direction=min|max [done=<value>] [window=5] [max=50] | /loop stop", "info");
}

// =================================================================
// Tools exposed to the agent
// =================================================================

function registerAgentTools(pi: any, ctx: ExtensionContext): void {
  pi.registerTool(defineTool({
    name: "complete_goal",
    label: "Complete goal",
    description: "Mark the active goal as complete. Spawns an isolated auditor to verify. Use only when the objective is genuinely satisfied.",
    parameters: Type.Object({
      completionSummary: Type.Optional(Type.String({ description: "1-paragraph completion claim" })),
      verificationSummary: Type.Optional(Type.String({ description: "Per-item evidence for the verification contract" })),
    }),
    async execute(_id, params, signal) {
      if (!state.goal || state.goal.status !== "active") {
        return { content: [{ type: "text", text: "No active goal." }], details: {} };
      }
      const p = params as { completionSummary?: string; verificationSummary?: string };
      updateGoal({ status: "auditing" }, ctx);
      const settings = loadSettings(ctx.cwd);
      const { model: auditorModel, error: modelError, via } = resolveAuditorModel(ctx, settings.auditorModel);
      if (modelError) {
        ctx.ui.notify(`Auditor model issue: ${modelError}`, "warning");
      }
      ctx.ui.notify(`Auditor running (isolated session, model: ${via ?? "setting"})…`, "info");
      // Esc during the audit aborts this tool's signal → threaded into the
      // auditor session, which aborts cleanly and returns "Auditor aborted."
      latestAuditProgress = { label: "starting" };
      const result = await runGoalCompletionAuditor({
        ctx,
        goal: state.goal,
        completionSummary: p.completionSummary,
        verificationSummary: p.verificationSummary,
        model: auditorModel,
        thinkingLevel: settings.auditorThinkingLevel ?? getSessionThinkingLevel(),
        signal: signal ?? undefined,
        onProgress: (progress) => {
          latestAuditProgress = {
            currentTool: progress.currentTool,
            label: progress.label,
            elapsedMs: progress.elapsedMs,
          };
          refreshUI(ctx);
        },
      });
      latestAuditProgress = null;
      // Audit history: record REAL verdicts only — a non-empty report is the
      // evidence the auditor actually inspected something. Empty-report runs
      // (abort, auth failure, no model) are surfaced via pauseReason, not
      // logged as disapprovals.
      const auditorRan = result.output.trim().length > 0;
      const history = state.goal.auditHistory ?? [];
      if (auditorRan) {
        history.push({
          at: nowIso(),
          approved: result.approved,
          disapproved: result.disapproved,
          model: result.model,
          thinkingLevel: result.thinkingLevel,
          report: result.output,
          error: result.error,
          regressionShieldPassed: result.regressionShieldPassed,
        });
        // Cap history — 39 infra errors taught us unbounded growth is real.
        if (history.length > 20) history.splice(0, history.length - 20);
      }

      // Escape hatch: the user aborted the audit (Esc). Offer the explicit
      // choice — complete WITHOUT audit, or keep working. (pi-goal-x parity.)
      if (result.error === "Auditor aborted.") {
        updateGoal({ status: "active", auditHistory: history, pauseReason: "audit aborted by user (Esc)" }, ctx);
        let completeAnyway = false;
        try {
          completeAnyway = await ctx.ui.confirm(
            "Audit aborted",
            "You aborted the auditor (Escape).\n\nYes = mark the goal COMPLETE WITHOUT AUDIT (you take responsibility for verification).\nNo = continue working; the auditor will verify on the next complete_goal.",
          );
        } catch {
          completeAnyway = false;
        }
        if (completeAnyway) {
          updateGoal({ auditHistory: history }, ctx);
          archiveCurrentGoal(ctx, "complete", "completed without audit (user choice after Esc)");
          return { content: [{ type: "text", text: "Goal marked complete without audit (user choice)." }], details: {} };
        }
        scheduleContinuation(ctx, true);
        return {
          content: [{ type: "text", text: "Audit aborted; continuing. Call complete_goal again when ready — the auditor will re-run." }],
          details: {},
        };
      }

      if (result.approved) {
        updateGoal({ auditHistory: history }, ctx);
        const objective = state.goal.objective;
        archiveCurrentGoal(ctx, "complete", `auditor ${result.model} approved`);
        notifyExternal(ctx, `Goal complete (auditor approved): ${objective.slice(0, 120)}`);
        return { content: [{ type: "text", text: `Goal approved by auditor ${result.model}.` }], details: {} };
      }

      // THREE-WAY SPLIT (v0.9.9): infrastructure failure is NOT a verdict.
      // The wild-caught case: 6 silent "disapprovals" that were really a dead
      // auditor model. The agent must be able to tell the difference.
      if (result.error && !result.disapproved) {
        updateGoal({
          status: "active",
          auditHistory: history,
          pauseReason: `auditor infrastructure: ${result.error}`,
          pauseSuggestedAction: "Fix the auditor model (/gla model=provider/id) and call complete_goal again — your work was NOT judged",
        }, ctx);
        scheduleContinuation(ctx, true);
        return {
          content: [{
            type: "text",
            text: `The auditor could not run (infrastructure, NOT a verdict): ${result.error}\nYour completion claim was not evaluated. Fix the auditor model with /gla model=provider/id and call complete_goal again — do not change your deliverable for this.`,
          }],
          details: {},
        };
      }

      const noContractHint = state.goal.verificationContract?.trim()
        ? ""
        : "\n\nNote: this goal has no verification contract, so the auditor inferred done-criteria from the objective text. For sharper verdicts, /goal tweak the objective to add a 'Done when: ...' clause.";
      updateGoal({
        status: "active",
        auditHistory: history,
        pauseReason: "auditor disapproved",
        pauseSuggestedAction: "Inspect auditor feedback and fix the actual gap before calling complete_goal again",
      }, ctx);
      scheduleContinuation(ctx, true);
      return {
        content: [{
          type: "text",
          text: `Auditor disapproved. Report (first 800 chars):\n${result.output.slice(0, 800)}${noContractHint}`,
        }],
        details: {},
      };
    },
  }));

  pi.registerTool(defineTool({
    name: "pause_goal",
    label: "Pause goal",
    description: "Pause the active goal with a reason and suggested action. Use when blocked on user input or unable to make progress.",
    parameters: Type.Object({
      reason: Type.String({ description: "Why the work is paused" }),
      suggestedAction: Type.Optional(Type.String({ description: "What the user should do next" })),
    }),
    async execute(_id, params) {
      const p = params as { reason: string; suggestedAction?: string };
      if (!state.goal) return { content: [{ type: "text", text: "No active goal." }], details: {} };
      updateGoal({
        status: "paused",
        pauseReason: p.reason,
        pauseSuggestedAction: p.suggestedAction,
      }, ctx);
      ctx.ui.notify(`Goal paused: ${p.reason}`, "info");
      notifyExternal(ctx, `Goal paused: ${p.reason.slice(0, 120)}`);
      return { content: [{ type: "text", text: "Goal paused. /goal resume to continue." }], details: {} };
    },
  }));

  pi.registerTool(defineTool({
    name: "complete_task",
    label: "Complete task",
    description: "Mark a task in the active goal's task list as complete (does not stop the turn).",
    parameters: Type.Object({
      id: Type.String({ description: "Task id to complete" }),
    }),
    async execute(_id, params) {
      const p = params as { id: string };
      if (!state.goal || !state.goal.taskList) {
        return { content: [{ type: "text", text: "No task list in this goal." }], details: {} };
      }
      const tl = state.goal.taskList;
      const queue: any[] = [...tl.tasks];
      while (queue.length > 0) {
        const t = queue.shift();
        if (t.id === p.id && t.status !== "complete") {
          t.status = "complete";
          updateGoal({ taskList: tl }, ctx);
          return { content: [{ type: "text", text: `Task ${p.id} marked complete.` }], details: {} };
        }
        if (t.subtasks) queue.push(...t.subtasks);
      }
      return { content: [{ type: "text", text: `Task ${p.id} not found.` }], details: {} };
    },
  }));

  pi.registerTool(defineTool({
    name: "update_task_status",
    label: "Update task status",
    description: "Update a task's status (pending/in_progress/complete).",
    parameters: Type.Object({
      id: Type.String(),
      status: Type.Union([Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("complete")]),
    }),
    async execute(_id, params) {
      const p = params as { id: string; status: "pending" | "in_progress" | "complete" };
      if (!state.goal || !state.goal.taskList) {
        return { content: [{ type: "text", text: "No task list in this goal." }], details: {} };
      }
      const tl = state.goal.taskList;
      const queue: any[] = [...tl.tasks];
      while (queue.length > 0) {
        const t = queue.shift();
        if (t.id === p.id) {
          t.status = p.status;
          updateGoal({ taskList: tl }, ctx);
          return { content: [{ type: "text", text: `Task ${p.id} → ${p.status}` }], details: {} };
        }
        if (t.subtasks) queue.push(...t.subtasks);
      }
      return { content: [{ type: "text", text: `Task ${p.id} not found.` }], details: {} };
    },
  }));

  pi.registerTool(defineTool({
    name: "propose_goal_draft",
    label: "Propose goal draft",
    description: "During goal drafting (/goal with no args), propose the clarified goal contract. Opens the user's Confirm dialog — nothing activates until they confirm. BLOCKED until the user has replied to at least one of your interview questions.",
    parameters: Type.Object({
      objective: Type.String({ description: "The clarified, concrete objective (single item) or a summary when items[] is used" }),
      verificationContract: Type.Optional(Type.String({ description: "Checkable done-criteria (commands, file states, test outcomes)" })),
      items: Type.Optional(Type.Array(Type.String(), { description: "LIST drafting only: many objectives at once (e.g. 'queue these 50 things'). Each becomes a queue item; per-item 'Done when:' clauses are honored." })),
    }),
    async execute(_id, params, _signal, _onUpdate, execCtx) {
      const p = params as { objective: string; verificationContract?: string; items?: string[] };
      if (draftingTarget !== "goal" && draftingTarget !== "list") {
        return {
          content: [{ type: "text", text: "Not in goal drafting mode. The user starts drafting with /goal or /list add (no args), or activates directly with /goal <objective>." }],
          details: {},
        };
      }
      // v0.14.0: the interview floor — no Confirm until the user replied.
      const block = draftProposalBlock(draftingUserReplies);
      if (block) {
        return { content: [{ type: "text", text: block }], details: {} };
      }
      // Multi-item drafts are LIST-only: a goal is single by definition.
      if (p.items && p.items.length > 0 && draftingTarget !== "list") {
        return {
          content: [{ type: "text", text: "items[] is only valid in /list drafting — a goal is a single objective. Propose one objective, or ask the user to switch to /list." }],
          details: {},
        };
      }
      const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
      // Multi-item list draft: one Confirm for the whole batch.
      if (p.items && p.items.length > 0) {
        const preview = p.items.slice(0, 6).map((t, i) => `  ${i + 1}. ${t.slice(0, 60)}`).join("\n");
        let batchConfirmed = false;
        try {
          batchConfirmed = await liveCtx.ui.confirm(
            "Confirm queue batch",
            `${p.items.length} items:\n${preview}${p.items.length > 6 ? `\n  … and ${p.items.length - 6} more` : ""}`,
          );
        } catch {
          batchConfirmed = false;
        }
        if (!batchConfirmed) {
          return {
            content: [{ type: "text", text: "Batch rejected by the user. Ask what to change, refine the item list, and propose again." }],
            details: {},
          };
        }
        draftingTarget = null;
        const wasIdle = !state.goal || state.goal.status === "complete" || state.goal.status === "aborted";
        const n = enqueueItems(liveCtx, p.items, "drafted batch");
        if (wasIdle) {
          return { content: [{ type: "text", text: `${n} items confirmed; first activated (queue was empty). Begin work now.` }], details: {} };
        }
        return { content: [{ type: "text", text: `${n} items confirmed and queued (${listQueue().length} waiting).` }], details: {} };
      }
      const contractBlock = p.verificationContract?.trim()
        ? `\n\nDone when:\n${p.verificationContract.trim()}`
        : "\n\n(No verification contract — the auditor will infer done-criteria from the objective. Consider adding one.)";
      let confirmed = false;
      try {
        confirmed = await liveCtx.ui.confirm("Confirm goal", `${p.objective.trim()}${contractBlock}`);
      } catch {
        confirmed = false;
      }
      if (!confirmed) {
        return {
          content: [{ type: "text", text: "Draft rejected by the user. Ask what to change, refine, and propose again. Do not repeat the identical draft." }],
          details: {},
        };
      }
      const confirmedTarget = draftingTarget;
      draftingTarget = null;
      const full = p.objective.trim() + (p.verificationContract?.trim() ? `\nDone when:\n${p.verificationContract.trim()}` : "");
      // List drafting: the confirmed contract goes into the QUEUE, not active.
      if (confirmedTarget === "list") {
        const extracted = extractVerificationContract(full);
        const item = { id: newGoalId(), objective: extracted.objective, verificationContract: extracted.verificationContract || undefined, addedAt: nowIso() };
        state = { ...state, list: [...listQueue(), item] };
        persistState(liveCtx);
        appendLedger(liveCtx.cwd, "list_added", { id: item.id, objective: item.objective, drafted: true });
        if (!state.goal || state.goal.status === "complete" || state.goal.status === "aborted") {
          activateNextListItem(liveCtx);
          return { content: [{ type: "text", text: "Confirmed and activated (queue was empty). Begin work now." }], details: {} };
        }
        return { content: [{ type: "text", text: `Confirmed and queued (${listQueue().length} waiting). It activates when the current goal completes.` }], details: {} };
      }
      const goal = createGoal(full, liveCtx);
      setGoal(goal, liveCtx);
      iterationCounter = 0;
      consecutiveStuckIterations = 0;
      consecutiveErrorIterations = 0;
      scheduleContinuation(liveCtx, true);
      return {
        content: [{ type: "text", text: `Goal confirmed and activated (id ${goal.id}). Begin work now; call complete_goal only when the objective is genuinely satisfied.` }],
        details: {},
      };
    },
  }));

  pi.registerTool(defineTool({
    name: "propose_loop_draft",
    label: "Propose loop draft",
    description: "During loop drafting (/loop with no args), propose the loop configuration. The orchestrator test-runs the measure command ONCE and shows the user real output + parsed number in a Confirm dialog. A measure producing no number is auto-rejected.",
    parameters: Type.Object({
      target: Type.String({ description: "What to improve, concretely" }),
      measureCmd: Type.String({ description: "Shell command that prints ONE number representing progress" }),
      direction: Type.Union([Type.Literal("min"), Type.Literal("max")], { description: "min = lower is better, max = higher is better" }),
      window: Type.Optional(Type.Number({ description: "Plateau stop after N non-improving iterations (default 5)" })),
      max: Type.Optional(Type.Number({ description: "Iteration cap (default 50)" })),
      time: Type.Optional(Type.Number({ description: "Arbitrary bound: stop after this many hours" })),
      tokens: Type.Optional(Type.Number({ description: "Arbitrary bound: stop after this many tokens (input+output)" })),
      branch: Type.Optional(Type.Boolean({ description: "branch=true: scratch-branch mode (clean git tree required)" })),
    }),
    async execute(_id, params, _signal, _onUpdate, execCtx) {
      const p = params as { target: string; measureCmd: string; direction: "min" | "max"; window?: number; max?: number; time?: number; tokens?: number; branch?: boolean };
      if (draftingTarget !== "loop") {
        return {
          content: [{ type: "text", text: "Not in loop drafting mode. The user starts loop drafting with /loop (no args), or starts directly with /loop start." }],
          details: {},
        };
      }
      // v0.14.0: the interview floor — no Confirm until the user replied.
      const loopBlock = draftProposalBlock(draftingUserReplies);
      if (loopBlock) {
        return { content: [{ type: "text", text: loopBlock }], details: {} };
      }
      if (!p.target?.trim() || !p.measureCmd?.trim()) {
        return { content: [{ type: "text", text: "target and measureCmd are both required." }], details: {} };
      }
      const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
      // THE TEST-RUN: orchestrator runs the proposed measure once. The user
      // sees the real number before a single iteration burns tokens.
      let rawOutput = "";
      let parsed: number | null = null;
      if (extensionApi) {
        try {
          const result = await extensionApi.exec("bash", ["-c", p.measureCmd], { cwd: liveCtx.cwd });
          rawOutput = String((result as any)?.stdout ?? "").trim();
          parsed = parseMetric(rawOutput);
        } catch (err) {
          rawOutput = `(measure command failed: ${err instanceof Error ? err.message : String(err)})`;
        }
      }
      if (parsed === null) {
        return {
          content: [{
            type: "text",
            text: `Measure test-run produced NO number — proposal auto-rejected.\nCommand: ${p.measureCmd}\nOutput: ${rawOutput.slice(0, 300) || "(empty)"}\nFix the command so it prints exactly one number, sanity-check it against the repo, and propose again.`,
          }],
          details: {},
        };
      }
      const window = p.window && p.window > 0 ? Math.floor(p.window) : 5;
      const max = p.max && p.max > 0 ? Math.floor(p.max) : 50;
      let confirmed = false;
      try {
        confirmed = await liveCtx.ui.confirm(
          "Confirm loop",
          `Target: ${p.target.trim()}\n\nMeasure: ${p.measureCmd}\nTest-run output: ${rawOutput.slice(0, 200)}\nParsed number: ${parsed} (${p.direction === "min" ? "lower is better" : "higher is better"})\n\nPlateau stop: ${window} non-improving iterations · Cap: ${max} iterations${typeof p.time === "number" && p.time > 0 ? ` · Time bound: ${p.time}h` : ""}${typeof p.tokens === "number" && p.tokens > 0 ? ` · Token bound: ${p.tokens.toLocaleString()}` : ""}${p.branch ? "\nbranch mode: scratch branch (clean tree required)" : ""}\n\nThe loop never completes — it runs until one of these bounds, plateau, or /loop stop. Start it?`,
        );
      } catch {
        confirmed = false;
      }
      if (!confirmed) {
        return {
          content: [{ type: "text", text: "Loop draft rejected by the user. Ask what to change — target, metric, direction, or window/max — and propose again." }],
          details: {},
        };
      }
      draftingTarget = null;
      const started = await startLoopFromConfig(liveCtx, {
        target: p.target.trim(),
        measureCmd: p.measureCmd,
        direction: p.direction,
        plateauWindow: window,
        maxIterations: max,
        timeLimitHours: typeof p.time === "number" && Number.isFinite(p.time) && p.time > 0 ? p.time : undefined,
        tokenBudget: typeof p.tokens === "number" && Number.isFinite(p.tokens) && p.tokens > 0 ? Math.floor(p.tokens) : undefined,
        branch: p.branch === true,
      });
      if (!started) {
        return { content: [{ type: "text", text: "Loop could not start (see the warning above — likely a git/dirty-tree issue with branch mode)." }], details: {} };
      }
      return {
        content: [{ type: "text", text: `Loop confirmed and started. Baseline ${parsed}. Make ONE small change per turn to move the metric ${p.direction === "min" ? "down" : "up"}.` }],
        details: {},
      };
    },
  }));

  pi.registerTool(defineTool({
    name: "propose_loop_refine",
    label: "Propose loop spec refinement",
    description: "While a loop is ACTIVE, propose refining the loop's spec — sharpen the target and/or change the measure command — when the current spec no longer captures 'better'. The user confirms; on a measure change the orchestrator test-runs the new command and re-baselines. Never edit the measure command or its inputs directly — that is gaming the metric.",
    parameters: Type.Object({
      target: Type.Optional(Type.String({ description: "The sharpened target text (omit to keep the current target)" })),
      measureCmd: Type.Optional(Type.String({ description: "The new measure command printing ONE number (omit to keep the current metric)" })),
      rationale: Type.String({ description: "Why the current spec no longer captures 'better' — shown to the user in the Confirm dialog" }),
    }),
    async execute(_id, params, _signal, _onUpdate, execCtx) {
      const p = params as { target?: string; measureCmd?: string; rationale: string };
      const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
      const loop = state.loop;
      if (!loop?.active) {
        return { content: [{ type: "text", text: "No active loop to refine. propose_loop_refine is only valid while a loop is running." }], details: {} };
      }
      const newTarget = p.target?.trim() || loop.target;
      const newMeasure = p.measureCmd?.trim() || loop.measureCmd;
      if (newTarget === loop.target && newMeasure === loop.measureCmd) {
        return { content: [{ type: "text", text: "Refinement proposed no changes — provide a new target, a new measureCmd, or both." }], details: {} };
      }
      // Measure change → orchestrator test-runs the new command first.
      let newBaseline: number | null = null;
      let testOutput = "";
      if (newMeasure !== loop.measureCmd) {
        if (!extensionApi) return { content: [{ type: "text", text: "No extension API available." }], details: {} };
        try {
          const result = await extensionApi.exec("bash", ["-c", newMeasure], { cwd: liveCtx.cwd });
          testOutput = String((result as any)?.stdout ?? "");
        } catch (e) {
          return { content: [{ type: "text", text: `New measure command failed to run: ${String(e).slice(0, 200)}` }], details: {} };
        }
        newBaseline = parseMetric(testOutput);
        if (newBaseline === null) {
          return {
            content: [{ type: "text", text: `New measure produced NO number — refinement auto-rejected.\nCommand: ${newMeasure}\nOutput: ${testOutput.slice(0, 300) || "(empty)"}\nFix it and propose again.` }],
            details: {},
          };
        }
      }
      let confirmed = false;
      try {
        confirmed = await liveCtx.ui.confirm(
          "Confirm loop spec refinement",
          `Rationale: ${p.rationale}\n\nTarget:\n  old: ${loop.target.slice(0, 120)}\n  new: ${newTarget.slice(0, 120)}\n\nMeasure:\n  old: ${loop.measureCmd}\n  new: ${newMeasure}${newMeasure !== loop.measureCmd ? `\n  test-run: ${testOutput.slice(0, 120)} → ${newBaseline}` : ""}\n\nThe loop keeps running against the refined spec (iteration ${loop.iteration} so far). Apply?`,
        );
      } catch {
        confirmed = false;
      }
      if (!confirmed) {
        return { content: [{ type: "text", text: "Refinement rejected by the user. The loop continues against the current spec — keep improving the metric as defined." }], details: {} };
      }
      applyRefinement(loop, {
        at: nowIso(),
        iteration: loop.iteration,
        oldTarget: loop.target,
        newTarget,
        oldMeasureCmd: loop.measureCmd,
        newMeasureCmd: newMeasure,
      }, newBaseline);
      persistState(liveCtx);
      appendLedger(liveCtx.cwd, "loop_refined", { iteration: loop.iteration, newTarget, newMeasureCmd: newMeasure, newBaseline });
      liveCtx.ui.notify(`Loop spec refined at iteration ${loop.iteration}.${newBaseline !== null ? ` New baseline: ${newBaseline}.` : ""}`, "info");
      return { content: [{ type: "text", text: "Refinement confirmed and applied. Continue improving against the NEW spec — one small change per turn." }], details: {} };
    },
  }));

  pi.registerTool(defineTool({
    name: "list_add",
    label: "Add to queue",
    description: "Add one or many objectives to the /list list (loop 2). Use when the user asks to queue work — 'add these to my list', 'queue these 10 things', 'put this on the backlog'. Each item becomes an audited goal; per-item 'Done when:' clauses are honored. The first queued item activates automatically when nothing is running.",
    parameters: Type.Object({
      items: Type.Array(Type.String(), { description: "Objectives to enqueue (1-100). Each may include its own 'Done when:' clause." }),
    }),
    async execute(_id, params, _signal, _onUpdate, execCtx) {
      const p = params as { items: string[] };
      if (!Array.isArray(p.items) || p.items.length === 0) {
        return { content: [{ type: "text", text: "No items given." }], details: {} };
      }
      if (p.items.length > 100) {
        return { content: [{ type: "text", text: `Too many items at once (${p.items.length}); max 100 per call — batch larger plans across calls.` }], details: {} };
      }
      const clean = p.items.map((t) => t.trim()).filter((t) => t.length > 0);
      const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
      const wasIdle = !state.goal || state.goal.status === "complete" || state.goal.status === "aborted";
      const n = enqueueItems(liveCtx, clean, "agent list_add");
      return {
        content: [{
          type: "text",
          text: wasIdle
            ? `${n} item(s) queued; the first is now active. Work it normally and call complete_goal when done — the next item activates automatically.`
            : `${n} item(s) queued (${listQueue().length} waiting behind the active goal).`,
        }],
        details: {},
      };
    },
  }));

  pi.registerTool(defineTool({
    name: "list_activate",
    label: "Activate list item",
    description: "Activate a specific item from the /list queue by position (1-based). Order is the default, not the law: use this when a different item should be worked next (e.g. you want to research item 5 while item 1 waits). Aborts the currently active goal if one is running.",
    parameters: Type.Object({
      n: Type.Number({ description: "1-based position in the queue (1 = head)" }),
    }),
    async execute(_id, params, _signal, _onUpdate, execCtx) {
      const p = params as { n: number };
      const n = Math.floor(p.n);
      if (!Number.isInteger(n) || n < 1) {
        return { content: [{ type: "text", text: "n must be a positive integer (1-based position)." }], details: {} };
      }
      const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
      if (state.goal && state.goal.status === "active") {
        archiveCurrentGoal(liveCtx, "aborted", "skipped via list_activate");
      }
      if (!activateNextListItem(liveCtx, n)) {
        return { content: [{ type: "text", text: listQueue().length === 0 ? "List is empty." : `No item #${n} (list has ${listQueue().length} items).` }], details: {} };
      }
      return { content: [{ type: "text", text: `Item #${n} activated. Work it normally; call complete_goal when done.` }], details: {} };
    },
  }));

  pi.registerTool(defineTool({
    name: "list_status",
    label: "Queue status",
    description: "Show the active goal and the /list list (loop 2) as text: what's running, what's waiting.",
    parameters: Type.Object({}),
    async execute() {
      const lines: string[] = [];
      if (state.goal) {
        lines.push(`Active [${state.goal.policy}] (${statusLabel(state.goal.status)}): ${state.goal.objective}`);
      } else {
        lines.push("Active: (none)");
      }
      const queue = listQueue();
      if (queue.length === 0) {
        lines.push("List: empty.");
      } else {
        lines.push(`Queue (${queue.length}):`);
        queue.slice(0, 20).forEach((item, i) => lines.push(`${i + 1}. ${item.objective}`));
        if (queue.length > 20) lines.push(`… and ${queue.length - 20} more`);
      }
      if (state.loop) {
        lines.push(`Loop: ${state.loop.active ? "active" : "stopped"} — ${state.loop.target} (best ${state.loop.bestValue ?? "n/a"}, iteration ${state.loop.iteration})`);
      }
      return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
    },
  }));

  pi.registerTool(defineTool({
    name: "propose_task_list",
    label: "Propose task list",
    description: "Propose a task breakdown for the active goal. Opens the user's Confirm dialog. Limits: 20 top-level tasks, 5 subtasks per task.",
    parameters: Type.Object({
      tasks: Type.Array(Type.Object({
        title: Type.String(),
        subtasks: Type.Optional(Type.Array(Type.String())),
      })),
    }),
    async execute(_id, params, _signal, _onUpdate, execCtx) {
      if (!state.goal || state.goal.status !== "active") {
        return { content: [{ type: "text", text: "No active goal to break down." }], details: {} };
      }
      if (state.goal.taskList && state.goal.taskList.tasks.length > 0) {
        return { content: [{ type: "text", text: "A task list already exists. Use update_task_status / complete_task to work it." }], details: {} };
      }
      const p = params as { tasks: TaskProposal[] };
      const invalid = validateTaskProposal(p.tasks);
      if (invalid) {
        return { content: [{ type: "text", text: invalid }], details: {} };
      }
      const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
      const preview = p.tasks.map((t, i) => {
        const subs = (t.subtasks ?? []).map((s, j) => `   ${i + 1}.${j + 1} ${s}`).join("\n");
        return `${i + 1}. ${t.title}` + (subs ? `\n${subs}` : "");
      }).join("\n");
      let confirmed = false;
      try {
        confirmed = await liveCtx.ui.confirm("Confirm task list", preview);
      } catch {
        confirmed = false;
      }
      if (!confirmed) {
        return { content: [{ type: "text", text: "Task list rejected by the user. Adjust and propose again." }], details: {} };
      }
      const taskList = buildTaskList(p.tasks);
      updateGoal({ taskList }, liveCtx);
      const subCount = taskList.tasks.reduce((n, t) => n + (t.subtasks?.length ?? 0), 0);
      return {
        content: [{ type: "text", text: `Task list set: ${taskList.tasks.length} tasks, ${subCount} subtasks. Track progress with complete_task / update_task_status.` }],
        details: {},
      };
    },
  }));
}

// =================================================================
// Settings (auditor model, thinking level)
// =================================================================

interface Settings {
  /** "provider/model-id" or bare "model-id". Unset → session model. */
  auditorModel?: string;
  auditorThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
  /** Shell command run on goal complete / goal pause / loop stop; message passed as $1. */
  notifyCmd?: string;
  /** Per-goal token budget; crossing it pauses the goal. Default 1,000,000. */
  tokenLimit?: number;
}

const DEFAULT_SETTINGS: Settings = {
  // Unset = follow the pi session thinking level (user selects thinking in
  // pi, auditor follows), floor "high" — the auditor is the verification
  // gate, depth is worth more there than speed. /gla thinking= overrides.
  auditorThinkingLevel: undefined,
};

// Two-tier config (v0.7.0): GLOBAL is the normal home — you set things once
// and rarely open this again. PROJECT is the rare local override.
// Resolution: project > global > defaults (per key).
function globalSettingsPath(): string {
  return path.join(os.homedir(), ".pi", "agent", "pi-goal-list-loop-audit.settings.json");
}

function projectSettingsPath(cwd: string): string {
  return path.join(piGlaDir(cwd), "settings.json");
}

function readSettingsFile(file: string): Partial<Settings> {
  try {
    if (!fs.existsSync(file)) return {};
    const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
    return typeof parsed === "object" && parsed !== null ? parsed as Partial<Settings> : {};
  } catch {
    return {};
  }
}

function loadSettings(cwd: string): Settings {
  return mergeSettings(
    DEFAULT_SETTINGS as unknown as Record<string, unknown>,
    readSettingsFile(globalSettingsPath()) as Record<string, unknown>,
    readSettingsFile(projectSettingsPath(cwd)) as Record<string, unknown>,
  ) as unknown as Settings;
}

/** Where each effective setting comes from (for the /gla display). */
function settingsProvenance(cwd: string): Record<keyof Settings, { value: unknown; source: "project" | "global" | "default" }> {
  const proj = readSettingsFile(projectSettingsPath(cwd));
  const glob = readSettingsFile(globalSettingsPath());
  const effective = loadSettings(cwd);
  const out: Record<string, { value: unknown; source: "project" | "global" | "default" }> = {};
  const keys: Array<keyof Settings> = ["auditorModel", "auditorThinkingLevel", "notifyCmd", "tokenLimit"];
  for (const k of keys) {
    if ((proj as Record<string, unknown>)[k] !== undefined) out[k] = { value: (proj as any)[k], source: "project" };
    else if ((glob as Record<string, unknown>)[k] !== undefined) out[k] = { value: (glob as any)[k], source: "global" };
    else out[k] = { value: (effective as any)[k], source: "default" };
  }
  return out as Record<keyof Settings, { value: unknown; source: "project" | "global" | "default" }>;
}

function saveSettings(scope: "global" | "project", cwd: string, patch: Partial<Settings>): void {
  const file = scope === "global" ? globalSettingsPath() : projectSettingsPath(cwd);
  const current = readSettingsFile(file);
  const next: Record<string, unknown> = { ...current };
  for (const [k, v] of Object.entries(patch)) {
    if (v === undefined) delete next[k]; // key=unset removes the key
    else next[k] = v;
  }
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(file, JSON.stringify(next, null, 2));
}

/**
 * Session thinking level with a "high" floor (v0.8.5): the auditor follows
 * the thinking level the user selected in pi; if none is set, audits run at
 * "high" — the auditor is the verification gate, depth beats speed there.
 */
function getSessionThinkingLevel(): "off" | "minimal" | "low" | "medium" | "high" | "xhigh" {
  try {
    const level = extensionApi?.getThinkingLevel?.();
    if (level && ["off", "minimal", "low", "medium", "high", "xhigh"].includes(level)) {
      return level as "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
    }
  } catch {
    // fall through to the floor
  }
  return "high";
}

/**
 * Resolve the auditor model (v0.6.2). The principle: **the user selects the
 * model in pi; the auditor uses it.** The plugin never picks a model itself.
 *
 * Chain:
 *   1. Explicit `/gla model=provider/id` override (rare).
 *   2. The pi session model (ctx.model) — whatever the user selected.
 *
 * If the session model's provider is extension-registered, the auditor's
 * extension-less session cannot auth it; that failure is surfaced with a
 * clear explanation (switch pi's model to a built-in provider, or set the
 * override) — we do NOT silently substitute a different model.
 */
function resolveAuditorModel(ctx: ExtensionContext, ref?: string): { model: any; error?: string; via?: string } {
  if (ref && ref.trim()) {
    const trimmed = ref.trim();
    const slash = trimmed.indexOf("/");
    if (slash > 0) {
      const provider = trimmed.slice(0, slash);
      const id = trimmed.slice(slash + 1);
      const model = ctx.modelRegistry.find(provider, id);
      return model ? { model, via: "setting" } : { model: undefined, error: `model not found: ${trimmed}` };
    }
    const matches = ctx.modelRegistry.getAvailable().filter((m: any) => m.id === trimmed || m.name === trimmed);
    return matches[0] ? { model: matches[0], via: "setting" } : { model: undefined, error: `no available model matching: ${trimmed}` };
  }
  const sessionModel = ctx.model as any;
  if (sessionModel) return { model: sessionModel, via: "session" };
  return { model: undefined, error: "no session model and no auditorModel configured — set one with /gla model=provider/id" };
}

// (v0.9.12) The auto-fallback apparatus was REMOVED: no tier ranking, no
// candidate chains, no dead-model caches. The plugin never picks a model —
// you select it in pi (session model) or in /gla (explicit override). When
// neither works, the failure surfaces plainly (see the three-way split in
// the complete_goal handler) with the exact fix; nothing is substituted
// silently.

/**
 * The /gla interactive settings UI (v0.8.0): a menu loop over pi's dialog
 * primitives. Pick a setting → edit it → saved to GLOBAL → back to the menu.
 * Done/Esc exits. Rarely opened by design; scriptable /gla key=value remains
 * for tmux/headless.
 */
async function openSettingsUI(ctx: ExtensionContext): Promise<void> {
  for (;;) {
    const prov = settingsProvenance(ctx.cwd);
    const show = (k: keyof Settings, fallback: string) => {
      const p = prov[k];
      const v = p.value === undefined ? fallback : String(p.value);
      return `${v}  [${p.source}]`;
    };
    let choice: string | undefined;
    try {
      choice = await ctx.ui.select(
        `pi-goal-list-loop-audit settings — global: ${globalSettingsPath()}`,
        [
          `Auditor model override — ${show("auditorModel", "(pi session model)")}`,
          `Auditor thinking — ${show("auditorThinkingLevel", "(session, floor high)")}`,
          `Notify command — ${show("notifyCmd", "(off)")}`,
          `Token limit per goal — ${show("tokenLimit", "(off)")}`,
          "Done",
        ],
      );
    } catch {
      return;
    }
    if (!choice || choice === "Done") return;
    try {
      if (choice.startsWith("Auditor model")) {
        const v = await ctx.ui.input("Auditor model override", "provider/model-id — empty keeps the pi session model");
        if (v !== undefined) saveSettings("global", ctx.cwd, { auditorModel: v.trim() || undefined });
      } else if (choice.startsWith("Auditor thinking")) {
        const v = await ctx.ui.select("Auditor thinking level", ["off", "minimal", "low", "medium", "high", "xhigh"]);
        if (v) saveSettings("global", ctx.cwd, { auditorThinkingLevel: v as Settings["auditorThinkingLevel"] });
      } else if (choice.startsWith("Notify command")) {
        const v = await ctx.ui.input("Notify command — the event message is passed as $1", "e.g. a desktop-notification or push command; empty = off");
        if (v !== undefined) saveSettings("global", ctx.cwd, { notifyCmd: v.trim() || undefined });
      } else if (choice.startsWith("Token limit")) {
        const v = await ctx.ui.input("Per-goal token budget", "non-negative integer; 0 or empty = off (no cap)");
        if (v !== undefined) {
          const n = Number.parseInt(v.trim(), 10);
          if (Number.isFinite(n) && n >= 0) saveSettings("global", ctx.cwd, { tokenLimit: n });
          else if (!v.trim()) saveSettings("global", ctx.cwd, { tokenLimit: undefined });
          else ctx.ui.notify(`Not a non-negative integer: ${v}`, "warning");
        }
      }
    } catch {
      return;
    }
  }
}

async function cmdSettings(args: string, ctx: ExtensionContext): Promise<void> {
  // The plugin's ONE config surface — global by default, rarely opened.
  //   /gla                      show effective values + where each comes from
  //   /gla model=provider/id    write to GLOBAL config
  //   /gla thinking=high        write to GLOBAL config
  //   /gla notify='cmd $1'      write to GLOBAL config
  //   /gla tokenlimit=2000000   write to GLOBAL config
  //   /gla project model=...    write to PROJECT override (rare)
  //   /gla model=unset          remove key (from global; project model=unset for project)
  const trimmed = args.trim();
  if (!trimmed) {
    if (ctx.hasUI) {
      await openSettingsUI(ctx);
      return;
    }
    // Headless fallback: text display with provenance.
    const prov = settingsProvenance(ctx.cwd);
    const fmt = (k: keyof Settings, label: string) => {
      const p = prov[k];
      const v = p.value === undefined ? "(unset)" : String(p.value);
      return `${label}: ${v}  [${p.source}]`;
    };
    ctx.ui.notify(
      [
        fmt("auditorModel", "auditorModel"),
        fmt("auditorThinkingLevel", "thinking"),
        fmt("notifyCmd", "notify"),
        fmt("tokenLimit", "tokenLimit"),
        `\nglobal:  ${globalSettingsPath()}`,
        `project: ${projectSettingsPath(ctx.cwd)}`,
        `Set with: /gla key=value (global) · /gla project key=value (project override)`,
      ].join("\n"),
      "info",
    );
    return;
  }
  // Optional scope prefix: "project" writes the project override; default is global.
  let scope: "global" | "project" = "global";
  let rest = trimmed;
  if (/^project\s+/i.test(rest)) {
    scope = "project";
    rest = rest.replace(/^project\s+/i, "");
  }
  const patch: Partial<Settings> = {};
  let changed = false;
  // Quote-aware key=value parsing: notify='echo $1 >> /tmp/log' must survive
  // with its spaces intact (naive whitespace splitting mangled it to "'echo").
  const kvRe = /(\w+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g;
  let m: RegExpExecArray | null;
  while ((m = kvRe.exec(rest)) !== null) {
    const key = m[1]!.toLowerCase();
    const value = m[2] ?? m[3] ?? m[4] ?? "";
    if (key === "model" || key === "auditormodel") {
      patch.auditorModel = value === "unset" ? undefined : value;
      changed = true;
    } else if (key === "notify" || key === "notifycmd") {
      patch.notifyCmd = value === "unset" ? undefined : value;
      changed = true;
    } else if (key === "tokenlimit") {
      const n = Number.parseInt(value, 10);
      if (Number.isFinite(n) && n > 0) {
        patch.tokenLimit = n;
        changed = true;
      } else {
        ctx.ui.notify(`tokenlimit must be a positive integer, got: ${value}`, "warning");
      }
    } else if (key === "thinking" || key === "auditorthinkinglevel") {
      if (["off", "minimal", "low", "medium", "high", "xhigh"].includes(value)) {
        patch.auditorThinkingLevel = value as Settings["auditorThinkingLevel"];
        changed = true;
      } else {
        ctx.ui.notify(`Unknown thinking level: ${value}`, "warning");
      }
    }
  }
  if (!changed) {
    ctx.ui.notify("Nothing changed. Use key=value (model, thinking, notify, tokenlimit), optionally prefixed with 'project'.", "info");
    return;
  }
  saveSettings(scope, ctx.cwd, patch);
  const effective = loadSettings(ctx.cwd);
  ctx.ui.notify(
    `Saved to ${scope} config. Effective now: model=${effective.auditorModel ?? "(session model)"} thinking=${effective.auditorThinkingLevel ?? "(session)"} notify=${effective.notifyCmd ?? "(off)"} tokenLimit=${effective.tokenLimit ?? 0}${(effective.tokenLimit ?? 0) > 0 ? "" : " (off)"}\n` +
    `Note: the auditor runs without extensions — it must be a built-in provider, not an extension-registered one.`,
    "info",
  );
}

// =================================================================
// Command-collision detector (PLAN.md D1)
//
// pi's runner.js resolveRegisteredCommands() never throws on duplicate
// command names: the first registrant keeps the bare name, later ones
// become "goal:2", "list:3", etc. So a collision degrades UX silently.
// We detect duplicates at session start and warn loudly once.
// =================================================================

const OUR_COMMANDS = ["goal", "gla", "list", "queue", "loop"];
let collisionWarned = false;

// Providers verified to exist in a bare (extension-less) session. The auditor
// spawns exactly such a session, so extension-registered providers (kilocode,
// zenmux on this rig) fail inside it. Unknown providers get a soft one-time
// notice — not an error, since the built-in set grows over time.
const KNOWN_BUILTIN_PROVIDERS = new Set([
  "anthropic", "google", "google-vertex", "google-gemini-cli", "openai", "openai-codex",
  "openrouter", "opencode", "azure-openai-responses", "groq", "cerebras", "xai", "zai",
  "minimax", "minimax-cn", "moonshotai", "kimi-coding", "github-copilot", "mistral", "huggingface",
]);
let providerWarned = false;

function warnIfAuditorProviderRisky(ctx: ExtensionContext): void {
  if (providerWarned) return;
  providerWarned = true;
  try {
    const settings = loadSettings(ctx.cwd);
    if (settings.auditorModel) return; // explicit auditor model — user's call
    const provider = (ctx.model as any)?.provider as string | undefined;
    if (!provider || KNOWN_BUILTIN_PROVIDERS.has(provider)) return;
    ctx.ui.notify(
      `pi-goal-list-loop-audit: session provider "${provider}" is extension-registered — the auditor (extension-less session) will fail auth with it. If audits error, set a built-in override once: /gla model=provider/id`,
      "info",
    );
  } catch {
    // non-fatal by design
  }
}

function warnOnCommandCollision(ctx: ExtensionContext): void {
  if (collisionWarned) return;
  collisionWarned = true;
  try {
    if (!extensionApi) return;
    const counts = new Map<string, number>();
    for (const cmd of extensionApi.getCommands() as any[]) {
      const name = String(cmd.invocationName ?? cmd.name ?? "").split(":")[0] ?? "";
      if (OUR_COMMANDS.includes(name)) {
        counts.set(name, (counts.get(name) ?? 0) + 1);
      }
    }
    const dupes = [...counts.entries()].filter(([, n]) => n > 1).map(([n]) => `/${n}`);
    if (dupes.length > 0) {
      const first = dupes[0] ?? "goal";
      ctx.ui.notify(
        `pi-goal-list-loop-audit: command collision on ${dupes.join(", ")}. Another extension registered the same name; ours may be reachable as /${first.slice(1)}:2. Consider disabling the other plugin.`,
        "warning",
      );
    }
  } catch {
    // getCommands unavailable or shape changed — stay silent, collision is non-fatal.
  }
}

// =================================================================
// Public extension entry
// =================================================================

export default function (pi: ExtensionAPI): void {
  extensionApi = pi;
  startHeartbeat();
  startUITicker();
  // Four top-level commands, that's all (v0.8.0 consolidation):
  //   /goal  — set/draft + status|pause|resume|cancel|tweak|archive subcommands
  //   /list — the list (add|show|next|remove|clear)
  //   /loop  — the metric loop (draft|start|status|stop)
  //   /gla   — the settings UI (+ scriptable key=value)
  pi.registerCommand("goal", {
    description: "Set/draft a goal, or /goal status|pause|resume|cancel|tweak <text>|archive. Objectives without a 'Done when:' clause are grilled into a contract first (nothing activates until you confirm); include the clause to start instantly.",
    handler: (args: string, ctx: ExtensionContext) => { rememberCtx(ctx); return cmdGoal(args, ctx); },
  });
  const settingsHandler = (args: string, ctx: ExtensionContext) => { rememberCtx(ctx); return cmdSettings(args, ctx); };
  pi.registerCommand("glla", {
    description: "Open the settings UI for goals, loops, lists, and the auditor. Scriptable form: /glla key=value · /glla project key=value",
    handler: settingsHandler,
  });
  // /gla kept as an alias (renamed package, v0.15.0) — muscle memory is real.
  pi.registerCommand("gla", {
    description: "Alias for /glla (package renamed to pi-goal-list-loop-audit in v0.15.0).",
    handler: settingsHandler,
  });
  pi.registerCommand("list", {
    description: "Loop 2: the list of audited goals — order is the default, not the law. /list add <obj or file or paste> | /list show | /list next [n] | /list remove <n> | /list clear",
    handler: (args: string, ctx: ExtensionContext) => { rememberCtx(ctx); return cmdList(args, ctx); },
  });
  // Alias for one release (renamed 0.10.0 back to /list — order isn't
  // mandatory with subagents; it's a shopping list, not a FIFO).
  pi.registerCommand("queue", {
    description: "Alias for /list (renamed in v0.10.0). Same subcommands.",
    handler: (args: string, ctx: ExtensionContext) => { rememberCtx(ctx); return cmdList(args, ctx); },
  });
  pi.registerCommand("loop", {
    description: "Loop 3: metric-driven forever loop. /loop start \"<target>\" measure=\"<cmd>\" direction=min|max [done=<value>] [window=5] [max=50] | /loop status | /loop stop",
    handler: (args: string, ctx: ExtensionContext) => { rememberCtx(ctx); return cmdLoop(args, ctx); },
  });

  // Tool registration is lazy: done on the first session event, when a
  // context exists. Tools show even without an active goal (and return
  // "no active goal" if called).
  let registeredCtx: ExtensionContext | null = null;

  pi.on("message_start", async (event: any, _ctx: ExtensionContext) => {
    // v0.14.0 drafting floor: count real user replies while drafting. Our
    // own injected draft prompt arrives as a user message — skip that one.
    if (draftingTarget === null) return;
    if (event?.message?.role !== "user") return;
    if (draftingSeedInFlight) {
      draftingSeedInFlight = false;
      return;
    }
    draftingUserReplies++;
  });

  pi.on("session_start", async (_event: any, ctx: ExtensionContext) => {
    rememberCtx(ctx);
    state = readState(ctx.cwd);
    if (!registeredCtx) {
      registerAgentTools(pi, ctx);
      registeredCtx = ctx;
    }
    warnOnCommandCollision(ctx);
    warnIfAuditorProviderRisky(ctx);
    // Resumption notice: make persisted supervisor state visible on startup.
    if (isLoopActive()) {
      const l = state.loop!;
      ctx.ui.notify(
        `Resuming loop (iteration ${l.iteration}/${l.maxIterations}, best ${l.bestValue ?? "n/a"}, stall ${l.stallCount}/${l.plateauWindow}): ${l.target.slice(0, 60)}`,
        "info",
      );
    } else if (state.goal && state.goal.status === "active") {
      ctx.ui.notify(
        `Resuming goal [${state.goal.id}]: ${state.goal.objective.slice(0, 70)}${listQueue().length > 0 ? ` (+${listQueue().length} queued)` : ""}`,
        "info",
      );
    }
    if (isLoopActive()) {
      // Session restarted mid-loop: resume measuring from persisted state.
      scheduleLoopTick(ctx);
    } else if (state.goal && state.goal.status === "active" && state.goal.autoContinue) {
      scheduleContinuation(ctx, true);
    } else if ((!state.goal || state.goal.status === "complete" || state.goal.status === "aborted") && listQueue().length > 0) {
      // Session restarted with a non-empty queue but no active goal.
      activateNextListItem(ctx);
    }
  });

  pi.on("agent_end", async (event: any, ctx: ExtensionContext) => {
    rememberCtx(ctx);
    noteActivity();
    if (!registeredCtx) {
      registerAgentTools(pi, ctx);
      registeredCtx = ctx;
    }
    // Nudge accounting: a supervising turn with zero tool calls is a nudge
    // (no real progress); 3 consecutive → pause. Tool-use turns reset it.
    if (isSupervising()) {
      heartbeatNudges = accountTurnForNudges(toolCallsThisTurn, heartbeatNudges);
      if (heartbeatNudges >= HEARTBEAT_MAX_NUDGES) {
        heartbeatNudges = 0;
        if (isLoopActive()) {
          clearLoopTimer();
          state.loop = { ...state.loop!, active: false, stopReason: `stalled: ${HEARTBEAT_MAX_NUDGES} consecutive turns with no tool calls` };
          persistState(ctx);
          ctx.ui.notify(`Loop stopped: stalled (${HEARTBEAT_MAX_NUDGES} turns, no tools). /loop start to begin a new one.`, "warning");
          notifyExternal(ctx, "Loop stopped: stalled (no tool calls).");
          return;
        }
        if (state.goal) {
          updateGoal({
            status: "paused",
            pauseReason: `stalled: ${HEARTBEAT_MAX_NUDGES} consecutive turns with no tool calls`,
            pauseSuggestedAction: "Inspect the goal — /goal resume to retry, /goal tweak to narrow it, /goal cancel to abort.",
          }, ctx);
          ctx.ui.notify(`Goal paused: stalled (${HEARTBEAT_MAX_NUDGES} turns, no tools).`, "warning");
          notifyExternal(ctx, "Goal paused: stalled (no tool calls).");
          return;
        }
      }
    }
    toolCallsThisTurn = 0;
    // Loop 3 runs on the same heartbeat: measure after every agent turn.
    if (isLoopActive()) {
      clearLoopTimer();
      await runLoopTick(ctx, event);
      return;
    }
    if (!state.goal) return;
    if (state.goal.status !== "active") return;
    clearContinuationTimer();

    const last = [...(event.messages as any[])].reverse().find((m) => m.role === "assistant");
    const text = last && Array.isArray(last.content) ? last.content.filter((p: any) => p.type === "text").map((p: any) => p.text).join("\n") : "";
    const stopReason = last?.stopReason;
    iterationCounter++;

    // Token accounting + cost guard: accumulate this turn's assistant tokens
    // (deduped — agent_end may replay seen messages). Crossing the goal's
    // token limit pauses it; /gla tokenlimit=<n> to raise.
    const newTokens = sumNewAssistantTokens(event.messages as unknown[], countedTokenMessages);
    if (newTokens > 0) {
      const used = (state.goal.usage?.tokensUsed ?? 0) + newTokens;
      const limit = state.goal.usage?.tokensLimit ?? DEFAULT_TOKEN_LIMIT;
      // v0.12.0: the guard is opt-in — limit 0/unset means never pause.
      if (limit > 0 && used > limit) {
        updateGoal({
          usage: { tokensUsed: used, tokensLimit: limit },
          status: "paused",
          pauseReason: `token limit exceeded (${used.toLocaleString()} > ${limit.toLocaleString()})`,
          pauseSuggestedAction: "/gla tokenlimit=<n> to raise the cap (or 0 to disable), then /goal resume",
        }, ctx);
        ctx.ui.notify(`Goal paused: token limit exceeded (${used.toLocaleString()} > ${limit.toLocaleString()}). /gla tokenlimit=<n> to raise, 0 to disable.`, "warning");
        notifyExternal(ctx, `Goal paused: token limit exceeded (${used} > ${limit}).`);
        return;
      }
      updateGoal({ usage: { tokensUsed: used, tokensLimit: limit } }, ctx);
    }

    if (stopReason === "error" || stopReason === "aborted") {
      consecutiveErrorIterations++;
      if (consecutiveErrorIterations >= 5) {
        updateGoal({
          status: "paused",
          pauseReason: `5 consecutive errors: ${stopReason}`,
          pauseSuggestedAction: "Use /goal resume to retry, or /goal cancel to abort.",
        }, ctx);
        ctx.ui.notify("Goal paused: 5 consecutive errors.", "warning");
        notifyExternal(ctx, "Goal paused: 5 consecutive errors.");
        return;
      }
    } else {
      consecutiveErrorIterations = 0;
    }

    // Hard 5-min cap: if no successful continue for >5 min, pause.
    // For v0.1.0 we only detect this on agent_end; a tighter watchdog lands in v0.2.0.
    // We schedule the next continuation; if it produces nothing useful in 5 min,
    // the next agent_end iteration of THIS branch will trigger the cap.

    scheduleContinuation(ctx, false);
  });

  pi.on("tool_call", () => {
    toolCallsThisTurn++;
    noteActivity();
  });
}