import {
  appendFileSync,
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  unlinkSync,
  writeFileSync,
} from "node:fs";
import { basename, dirname, isAbsolute, join } from "node:path";
import { createHash } from "node:crypto";
import { frontmatterStatus, isPendingStatus, setFrontmatterStatus } from "./adr-source";
import { GOAL_SLUG_PROMPT_MARKER } from "../goal-slug";
import type { McpContext } from "../../mcp/context";

/**
 * A deterministic ACP peer for the interface's browser verification and tests.
 *
 * It answers the protocol handshake, streams a little activity, optionally
 * interviews the developer, writes `status: accepted` into the frontmatter of
 * the record named in the prompt, and ends the turn. With `--discover` it
 * instead stages the sheet, glossary, contribution document, and six Discover
 * skills named by the agent's `/discover-*` command.
 */

function argument(name: string): string | undefined {
  const prefix = `--${name}=`;
  return process.argv.slice(2).find((value) => value.startsWith(prefix))?.slice(prefix.length);
}

function argumentAll(name: string): string[] {
  const prefix = `--${name}=`;
  return process.argv
    .slice(2)
    .filter((value) => value.startsWith(prefix))
    .map((value) => value.slice(prefix.length));
}

/** Parses repeated `--mode=<id>:<value>` arguments into an id-keyed map. */
function idOptions(name: string): Map<string, string> {
  const options = new Map<string, string>();
  for (const entry of argumentAll(name)) {
    const split = entry.indexOf(":");
    if (split < 0) continue;
    options.set(entry.slice(0, split), entry.slice(split + 1));
  }
  return options;
}

/** Deterministic per-epic timing and one-line activity overrides. */
const laneDelays = idOptions("lane-delay");
const laneActivities = idOptions("lane-activity");
const blockerEpics = new Set(argumentAll("blocker-epic"));
const questionEpics = new Set(argumentAll("question-epic"));
/** JSON list of open epics the verification server's tracker reads. */
const fixtureTracker = argument("fixture-tracker");
/** Repository whose branches and `main` a fixture lane merges into. */
const fixtureRepo = argument("fixture-repo");
const noClose = process.argv.includes("--no-close");
const generatedEpics = argumentAll("generate-epic");
const generationBudget = Number(argument("generation-budget") ?? generatedEpics.length);
const laneDelayMs = Number(argument("lane-delay-ms") ?? 0);
const laneSettleMs = Number(argument("lane-settle-ms") ?? 0);
const logPath = argument("log");
/** Records the provider environment a peer received, without the keys. */
const providerEnvLog = argument("provider-env");
if (providerEnvLog !== undefined) {
  const fingerprint = (value: string | undefined): string | null =>
    value === undefined ? null : createHash("sha256").update(value).digest("hex").slice(0, 16);
  appendFileSync(
    providerEnvLog,
    `${JSON.stringify({
      pid: process.pid,
      argv: process.argv.slice(2),
      cwd: process.cwd(),
      agentDir: process.env.PI_CODING_AGENT_DIR ?? null,
      opencode: fingerprint(process.env.OPENCODE_API_KEY),
      openrouter: fingerprint(process.env.OPENROUTER_API_KEY),
    })}\n`,
  );
}
const delayMs = Number(argument("delay-ms") ?? 0);
const forcedQuestions = argument("questions");
/** Omits the schema default so the fixture question has no recommended option. */
const questionsUnrecommended = process.argv.includes("--questions-unrecommended");
const reviseGoal = process.argv.includes("--revise-goal");
const createGoal = process.argv.includes("--create-goal");
const createGoalWrite = !process.argv.includes("--no-create-goal-write");
const goalFile = argument("goal");
const prepareSkills = process.argv.includes("--prepare-skills");
const prepareSkillsInvalid = process.argv.includes("--prepare-skills-invalid");
const prepareSkillsEmpty = process.argv.includes("--prepare-skills-empty");
const prepareSkillsConflict = process.argv.includes("--prepare-skills-conflict");
const prepareSkillsCollision = process.argv.includes("--prepare-skills-collision");
const prepareSkillsUnmanagedWrite = process.argv.includes("--prepare-skills-unmanaged-write");
const prepareSkillsUnmanagedSkill = process.argv.includes("--prepare-skills-unmanaged-skill");
const prepareSkillsError = process.argv.includes("--prepare-skills-error");
const collisionName = argument("collision-name") ?? "custom-skill";
const resolveRecord = !process.argv.includes("--no-resolve");
const removeRecord = process.argv.includes("--remove-record");
const busyContinuations = Number(argument("busy-continuations") ?? 0);
let busyRemaining = busyContinuations;

/** Flow Mode: the goal, implementation, analyst, and widget-conversation turns. */
const flowGoal = process.argv.includes("--flow-goal");
const flowImplement = process.argv.includes("--flow-implement");
const flowChange = process.argv.includes("--flow-change");
const flowWidget = process.argv.includes("--flow-widget");
const flowGoalEmpty = process.argv.includes("--flow-goal-empty");
const flowGoalFail = process.argv.includes("--flow-goal-fail");
const flowGoalText =
  argument("flow-goal-text") ?? "# Flow goal\n\nMake the fixture behavior observable.";
/** Overrides the goal text while this file exists, so turns can differ. */
const flowGoalTextFile = argument("flow-goal-text-file");
/** Stalls this long after writing goal.md, before the turn ends. */
const flowGoalSettleMs = Number(argument("flow-goal-settle") ?? 0);
/** While this file exists the interview stalls; `partial` first writes a draft. */
const flowGoalHang = argument("flow-goal-hang");
const flowGoalPartial = argument("flow-goal-partial");
const flowGoalDraft = argument("flow-goal-draft") ?? "# Flow goal\n\nAn unfinished draft";
const flowCheckpoints = Math.max(1, Number(argument("flow-checkpoints") ?? 1));
const flowStepDelay = Number(argument("flow-step-delay") ?? 0);
const flowBlocked = process.argv.includes("--flow-blocked");
/** Successive `DEVBOARD-BLOCKED:` marker texts streamed by the implementation turn. */
const flowBlockerLines = argumentAll("flow-blocker-line");
/** Between successive markers the stub holds until this file exists. */
const flowBlockerWaitFile = argument("flow-blocker-wait-file");
const flowQuestion = process.argv.includes("--flow-question");
const flowVerification = argument("flow-verification") ?? "passed";
const flowAnalystPartial = process.argv.includes("--flow-analyst-partial");
const flowAnalystFail = process.argv.includes("--flow-analyst-fail");
const flowAnalystEmpty = process.argv.includes("--flow-analyst-empty");
const flowAnalystForeign = process.argv.includes("--flow-analyst-foreign");
const flowSilentCheckpoints = process.argv.includes("--flow-silent-checkpoints");
const flowPreCommitDelay = Number(argument("flow-pre-commit-delay") ?? 0);
/** File this stub waits for before its second and later checkpoints. */
const flowWaitFile = argument("flow-wait-file");
const flowNoVerification = process.argv.includes("--flow-no-verification");

/** Discover Mode: the crawl staging turn and its validation-failure variants. */
const discover = process.argv.includes("--discover");
const discoverQuestion = process.argv.includes("--discover-question");
const discoverProse =
  argument("discover-prose") ??
  "A fixture host with a small order domain used to verify the Discover crawl";
const discoverInvalidSheet = process.argv.includes("--discover-invalid-sheet");
const discoverSheetAbsolute = process.argv.includes("--discover-sheet-absolute");
/** Stages evidence that is an absolute host path with its leading slash stripped. */
const discoverSheetStrippedHome = process.argv.includes("--discover-sheet-stripped-home");
const discoverSheetNoEvidence = process.argv.includes("--discover-sheet-no-evidence");
const discoverSheetSecret = process.argv.includes("--discover-sheet-secret");
const discoverSheetTwoSentences = process.argv.includes("--discover-sheet-two-sentences");
/** Stages HTTP routes whose leading slash is part of the fact. */
const discoverSheetRoutes = process.argv.includes("--discover-sheet-routes");
/** Stages a stack and platform inventory the older prompt wrote, with versions. */
const discoverVersionedNames = process.argv.includes("--discover-versioned-names");
/** Stages a level without `happyPath`, the shape an older prompt wrote. */
const discoverSheetNoHappyPath = process.argv.includes("--discover-sheet-no-happy-path");
/** Stages a happy-path count larger than the level's test count. */
const discoverSheetHappyOverflow = process.argv.includes("--discover-sheet-happy-overflow");
const discoverGlossaryInvalid = process.argv.includes("--discover-glossary-invalid");
const discoverGlossaryGrounding = process.argv.includes("--discover-glossary-grounding");
/** Grounds a concept in a repository path whose directory is named `home`. */
const discoverGlossaryHomePath = process.argv.includes("--discover-glossary-home-path");
/** Omits a concept from the staged glossary, so a published one is preserved unscored. */
const discoverGlossaryDrop = process.argv.includes("--discover-glossary-drop");
/** The staged significance sidecar defect, or "" for a valid sidecar. */
const discoverSignificance = argument("discover-significance") ?? "";
const discoverMissingArtifact = process.argv.includes("--discover-missing-artifact");
const discoverExtraArtifact = process.argv.includes("--discover-extra-artifact");
const discoverWriteOutside = process.argv.includes("--discover-write-outside");
const discoverError = process.argv.includes("--discover-error");
const discoverNoExit = process.argv.includes("--discover-no-exit");
/** Holds a Discover turn active long enough for the UI to render its state. */
const discoverDelayMs = Number(argument("discover-delay-ms") ?? 0);
/** One agent id whose turn fails before staging, for the Run all halt drill. */
const discoverFailAgent = argument("discover-fail-agent");
/** Stages no forge corpus, the degraded shape a host without credentials produces. */
const discoverContributionNoForge = process.argv.includes("--discover-contribution-no-forge");
/** One staged contribution defect, for the validator refusal drills. */
const discoverContributionInvalid = argument("discover-contribution-invalid") ?? "";

/** Ask mode: a read-only answer, preceded by thought and tool noise. */
const ask = process.argv.includes("--ask");
const askDelayMs = Number(argument("ask-delay-ms") ?? 0);
const askFail = process.argv.includes("--ask-fail");
const askExit = process.argv.includes("--ask-exit");
/** Accepts the first Ask prompt and never answers it; later peers answer. */
const askStall = process.argv.includes("--ask-stall");
/** Refuses the ACP initialize of the first Ask peer; later peers succeed. */
const askRefuseInitialize = process.argv.includes("--ask-refuse-initialize");
/** Answers the first session/new without a session id; later peers succeed. */
const askNoSession = process.argv.includes("--ask-no-session");
if (ask) log(`ask-start ${process.pid}`);

/** True once per flag, so only the first peer fails that handshake step. */
function firstAskHandshake(flag: string): boolean {
  if (logPath === undefined) return false;
  const marker = `${logPath}.${flag}`;
  if (existsSync(marker)) return false;
  writeFileSync(marker, "");
  return true;
}

/** Draft elaboration mode: simulate the goal-draft command's observable work. */
const goalDraft = process.argv.includes("--goal-draft");
if (goalDraft) log(`goal-draft-start ${process.pid}`);
const goalDraftFinish = argument("goal-draft-finish");
/** Draft naming mode: answer a naming turn with this text, verbatim. */
const goalSlug = argument("goal-slug");
/**
 * A path the peer writes only after the client grants the request_permission
 * frame it sends on every read-only conversation turn. The turn logs the
 * client's answer so a test proves the cancelled outcome, not just the absence.
 */
const permissionProbe = argument("permission-probe");
const ASK_INSTRUCTION = "\nQuestion: ";
const ASK_ANSWER_ONE =
  "The issues indicator shows the lifecycle the detached worker published for this repository. " +
  "It turns amber while a run is working and shows failed when the last run failed. " +
  "It sits in the status bar and opens the Issues mode.";
const ASK_ANSWER_TWO =
  "The status bar renders that label in StatusBar.svelte from the issues snapshot the server sends. " +
  "The count is the open issues the tracker returned for the host repository. " +
  "No other status item opens a mode.";
let askTurns = 0;
const DISCOVER_SECRET = "ghp_0123456789abcdefghijklmnopqrstuvwxyz";
const CREATED_GOAL = "# Created goal\n\nThe agent wrote this.";
const SETTLE_DELAY_MS = 400;

function log(line: string) {
  if (logPath !== undefined) appendFileSync(logPath, `${line}\n`);
}

function write(message: unknown) {
  const line = `${JSON.stringify(message)}\n`;
  process.stdout.write(line);
}

const pending = new Map<string, (result: unknown) => void>();
let nextRequestId = 1;
/** One prompt turn at a time, so a queued message answers in order. */
let promptChain: Promise<void> = Promise.resolve();

function request(method: string, params: unknown): Promise<unknown> {
  const id = nextRequestId++;
  const { promise, resolve } = Promise.withResolvers<unknown>();
  pending.set(String(id), resolve);
  write({ jsonrpc: "2.0", id, method, params });
  return promise;
}

/**
 * A mutating action behind an ACP permission request. A read-only client must
 * answer cancelled; only an explicit allow selection performs the write.
 */
async function probePermission() {
  if (permissionProbe === undefined) return;
  const response = await request("session/request_permission", {
    sessionId: "stub-session",
    toolCall: {
      toolCallId: "permission-probe",
      title: "Write the permission probe",
      kind: "edit",
      status: "pending",
    },
    options: [
      { optionId: "reject", name: "Reject", kind: "reject_once" },
      { optionId: "allow", name: "Allow", kind: "allow_once" },
    ],
  });
  const result =
    typeof response === "object" && response !== null
      ? (response as Record<string, unknown>)
      : undefined;
  const outcomeRecord =
    typeof result?.outcome === "object" && result.outcome !== null
      ? (result.outcome as Record<string, unknown>)
      : undefined;
  const outcome = typeof outcomeRecord?.outcome === "string" ? outcomeRecord.outcome : "none";
  const optionId = typeof outcomeRecord?.optionId === "string" ? outcomeRecord.optionId : "";
  log(`permission ${outcome}${optionId.length > 0 ? ` ${optionId}` : ""}`);
  if (outcome === "selected" && optionId === "allow") {
    const target = isAbsolute(permissionProbe)
      ? permissionProbe
      : join(process.cwd(), permissionProbe);
    writeFileSync(target, "granted\n");
  }
}

function pendingCount(directory: string): number {
  try {
    return readdirSync(directory)
      .filter((file) => file.endsWith(".md"))
      .filter((file) => isPendingStatus(frontmatterStatus(readFileSync(join(directory, file), "utf8"))))
      .length;
  } catch {
    return 0;
  }
}

function markAccepted(file: string) {
  const source = readFileSync(file, "utf8");
  if (frontmatterStatus(source) === undefined) return;
  writeFileSync(file, setFrontmatterStatus(source, "accepted"));
}

interface FixtureEpic {
  number: number;
  title: string;
  url: string;
}

function readFixtureTracker(path: string): FixtureEpic[] {
  try {
    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
    if (!Array.isArray(parsed)) return [];
    return parsed.filter(
      (entry): entry is FixtureEpic =>
        typeof entry === "object" &&
        entry !== null &&
        "number" in entry &&
        typeof entry.number === "number",
    );
  } catch {
    return [];
  }
}

function writeFixtureTracker(path: string, list: FixtureEpic[]) {
  const temporary = `${path}.${process.pid}.tmp`;
  writeFileSync(temporary, `${JSON.stringify(list, null, 2)}\n`);
  renameSync(temporary, path);
}

/** Serializes the stub's own tracker and merge writes across lane processes. */
function withLock<T>(lockPath: string, action: () => T): T {
  const started = Date.now();
  for (;;) {
    try {
      mkdirSync(lockPath);
      break;
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
      if (Date.now() - started > 10_000) {
        rmSync(lockPath, { recursive: true, force: true });
        continue;
      }
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
    }
  }
  try {
    return action();
  } finally {
    rmSync(lockPath, { recursive: true, force: true });
  }
}

function closeFixtureEpic(id: string) {
  if (fixtureTracker === undefined) return;
  withLock(`${fixtureTracker}.lock`, () => {
    writeFixtureTracker(
      fixtureTracker,
      readFixtureTracker(fixtureTracker).filter((epic) => String(epic.number) !== id),
    );
  });
  log(`closed ${id}`);
}

function fileFixtureEpic(entry: string): boolean {
  if (fixtureTracker === undefined) return false;
  const split = entry.indexOf(":");
  if (split < 0) return false;
  const number = Number(entry.slice(0, split));
  const title = entry.slice(split + 1);
  if (!Number.isInteger(number)) return false;

  let filed = false;
  withLock(`${fixtureTracker}.lock`, () => {
    const counterPath = `${fixtureTracker}.generation-count`;
    let count = 0;
    try {
      count = Number(readFileSync(counterPath, "utf8").trim());
    } catch {
      count = 0;
    }
    if (Number.isFinite(count) && count >= generationBudget) return;
    const list = readFixtureTracker(fixtureTracker);
    if (list.some((epic) => epic.number === number)) return;
    list.push({ number, title, url: `https://fixture.test/issues/${number}` });
    writeFixtureTracker(fixtureTracker, list);
    writeFileSync(counterPath, `${count + 1}\n`);
    filed = true;
  });
  if (filed) log(`filed ${number}`);
  return filed;
}

function gitTeardown(repo: string, args: string[]): { code: number; stderr: string } {
  const result = Bun.spawnSync({
    cmd: ["git", "-C", repo, ...args],
    stdout: "pipe",
    stderr: "pipe",
  });
  return { code: result.exitCode ?? -1, stderr: result.stderr.toString() };
}

/** True when `repo` resolves to the harness's own source checkout. */
function isHarnessCheckout(repo: string): boolean {
  const top = Bun.spawnSync({
    cmd: ["git", "-C", repo, "rev-parse", "--show-toplevel"],
    stdout: "pipe",
    stderr: "ignore",
  })
    .stdout.toString()
    .trim();
  if (top.length === 0) return false;
  return existsSync(join(top, ".devboard", "server", "fixtures", "stub-agent.ts"));
}

/** Simulates the peer's own merge: branch, sentinel commit, merge, cleanup. */
function mergeFixtureLane(id: string) {
  if (fixtureRepo === undefined) return;
  if (isHarnessCheckout(fixtureRepo)) {
    log(`merge-refused-harness-root ${fixtureRepo}`);
    return;
  }
  const worktree = join(fixtureRepo, ".worktree", `stub-epic-${id}`);
  const branch = `devboard/stub-epic-${id}`;
  mkdirSync(join(fixtureRepo, ".worktree"), { recursive: true });
  gitTeardown(fixtureRepo, ["worktree", "remove", "--force", worktree]);
  gitTeardown(fixtureRepo, ["branch", "-D", branch]);
  const added = gitTeardown(fixtureRepo, ["worktree", "add", worktree, "-b", branch, "main"]);
  if (added.code !== 0) {
    log(`merge-failed ${id} worktree ${added.stderr.trim()}`);
    return;
  }
  writeFileSync(join(worktree, `epic-${id}.txt`), `epic ${id}\n`);
  gitTeardown(worktree, ["add", "-A"]);
  gitTeardown(worktree, ["commit", "-m", `feat: epic ${id}`]);

  withLock(join(fixtureRepo, ".git", "stub-merge.lock"), () => {
    for (let attempt = 0; attempt < 40; attempt += 1) {
      const merged = gitTeardown(fixtureRepo, [
        "merge",
        "--no-ff",
        branch,
        "-m",
        `merge epic ${id}`,
      ]);
      if (merged.code === 0) {
        log(`merged ${id}`);
        const pushed = gitTeardown(fixtureRepo, ["push", "origin", "main"]);
        if (pushed.code === 0) log(`pushed ${id}`);
        else log(`push-failed ${id}`);
        return;
      }
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
    }
    log(`merge-failed ${id}`);
  });

  gitTeardown(fixtureRepo, ["worktree", "remove", "--force", worktree]);
  gitTeardown(fixtureRepo, ["branch", "-D", branch]);
}

function implementationEpic(text: string): string | undefined {
  const match = /^\/implement-next-epic(?:\s+(\d+))?/.exec(text);
  if (match === null) return undefined;
  if (match[1] !== undefined) return match[1];
  const open = fixtureTracker === undefined ? [] : readFixtureTracker(fixtureTracker);
  return open.length === 1 && open[0] !== undefined ? String(open[0].number) : undefined;
}

async function runImplementationLane(id: string) {
  const activity = laneActivities.get(id) ?? `Working on epic ${id}`;
  write({
    jsonrpc: "2.0",
    method: "session/update",
    params: {
      sessionId: "stub-session",
      update: {
        sessionUpdate: "agent_message_chunk",
        content: { type: "text", text: activity },
      },
    },
  });

  const override = laneDelays.get(id);
  const delay = override !== undefined ? Number(override) : laneDelayMs > 0 ? laneDelayMs : delayMs;
  if (Number.isFinite(delay) && delay > 0) await Bun.sleep(delay);

  const questionCount = questionEpics.has(id)
    ? 1
    : forcedQuestions !== undefined
      ? Number(forcedQuestions)
      : 0;
  if (questionCount > 0) {
    await askQuestions(questionCount);
  }

  if (blockerEpics.has(id)) {
    const message = `DEVBOARD-BLOCKED: fixture blocker for epic ${id}`;
    log(`blocked ${id}`);
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: message },
        },
      },
    });
    return;
  }

  if (noClose) return;
  if (laneSettleMs > 0) await Bun.sleep(laneSettleMs);
  mergeFixtureLane(id);
  closeFixtureEpic(id);
}

async function runGenerationLane() {
  write({
    jsonrpc: "2.0",
    method: "session/update",
    params: {
      sessionId: "stub-session",
      update: {
        sessionUpdate: "agent_message_chunk",
        content: { type: "text", text: "Choosing the next epics" },
      },
    },
  });
  if (delayMs > 0) await Bun.sleep(delayMs);
  for (const entry of generatedEpics) {
    if (fileFixtureEpic(entry)) {
      const number = entry.slice(0, entry.indexOf(":"));
      write({
        jsonrpc: "2.0",
        method: "session/update",
        params: {
          sessionId: "stub-session",
          update: {
            sessionUpdate: "agent_message_chunk",
            content: { type: "text", text: `Filed epic ${number}` },
          },
        },
      });
    }
  }
  if (laneSettleMs > 0) await Bun.sleep(laneSettleMs);
}

function writeSkill(
  name: string,
  description: string,
  body: string,
  header = `name: ${name}\ndescription: ${description}`,
) {
  const directory = join(process.cwd(), ".omp", "skills", name);
  mkdirSync(directory, { recursive: true });
  writeFileSync(
    join(directory, "SKILL.md"),
    `---\n${header}\nmetadata:\n  devboard-managed: "true"\n---\n\n${body}\n`,
  );
  log(`skill ${name}`);
}

function writePreparedSkills() {
  if (prepareSkillsEmpty) return;

  writeSkill(
    "dependency-direction",
    "Choose dependency direction and boundary ownership for any layered design.",
    "# Dependency direction\n\n- Always declare dependencies in one direction.\n- Keep policy separate from delivery and storage concerns.\n",
  );
  writeSkill(
    "cohesive-units",
    "Organize units of code so each owns one cohesive responsibility.",
    "# Cohesive units\n\n- Prefer small units with one responsibility.\n- Keep each public interface narrow and explicit.\n",
  );
  writeSkill(
    "behavior-first-testing",
    "Verify observable behavior with focused automated tests.",
    "# Behavior-first testing\n\n- Test observable behavior at the public boundary.\n- Prefer focused tests that fail for one reason.\n",
  );

  if (prepareSkillsConflict) {
    writeSkill(
      "dependency-direction",
      "Choose dependency direction and boundary ownership for any layered design.",
      "# Dependency direction\n\n- Always use dependency injection.\n- Keep policy separate from delivery and storage concerns.\n",
    );
  }

  if (prepareSkillsCollision) {
    writeSkill(
      collisionName,
      "A generated skill placed at an unmanaged skill's name.",
      "# Generated skill\n\n- Keep one writer for every installed skill.\n",
    );
  }

  if (prepareSkillsInvalid) {
    writeSkill(
      "invalid-skill",
      "",
      "# Invalid skill\n\n- Missing a description.\n",
      "name: Invalid Name\ndescription:",
    );
  }

  // The peer crosses the write boundary: a file inside a hand-authored skill,
  // and a whole new skill directory without the managed marker.
  if (prepareSkillsUnmanagedWrite) {
    const directory = join(process.cwd(), ".omp", "skills", "house-style");
    mkdirSync(directory, { recursive: true });
    writeFileSync(join(directory, "extra.md"), "# Extra\n\n- Added by the preparation peer.\n");
    log("unmanaged house-style/extra.md");
  }

  if (prepareSkillsUnmanagedSkill) {
    const directory = join(process.cwd(), ".omp", "skills", "stray-style");
    mkdirSync(directory, { recursive: true });
    writeFileSync(
      join(directory, "SKILL.md"),
      "---\nname: stray-style\ndescription: A hand-authored skill the peer invented.\n---\n\n# Stray style\n\n- Keep one writer.\n",
    );
    log("unmanaged stray-style/SKILL.md");
  }
}

async function askQuestions(count: number, options: { recommended?: boolean } = {}) {
  const hasDefault = options.recommended ?? !questionsUnrecommended;
  for (let index = 0; index < count; index += 1) {
    const response = await request("elicitation/create", {
      mode: "form",
      sessionId: "stub-session",
      message: index === 0 ? "Choose an answer" : `Choose an answer ${index + 1}`,
      requestedSchema: {
        type: "object",
        properties: {
          value: {
            type: "string",
            title: index === 0 ? "Choose an answer" : `Choose an answer ${index + 1}`,
            oneOf: [
              { const: "Alpha", title: "Alpha", description: "Alpha leads to the first outcome." },
              { const: "Beta", title: "Beta", description: "Beta leads to the second outcome." },
            ],
            ...(hasDefault ? { default: "Alpha" } : {}),
          },
        },
        required: ["value"],
      },
    });
    const content =
      typeof response === "object" && response !== null && "content" in response
        ? response.content
        : undefined;
    const value =
      typeof content === "object" && content !== null && "value" in content
        ? content.value
        : undefined;
    log(`answer ${String(value ?? "")}`);
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: `Answer received: ${String(value ?? "")}` },
        },
      },
    });
  }
}

/**
 * The `/goal-draft` turn. The draft's own bytes choose the scenario:
 * `STUB-QUESTION` asks one question first, `STUB-HANG` waits for Stop, and
 * `STUB-FAIL` reports a failed label verification. A successful turn writes
 * the five-section spec and removes the draft, exactly as the prompt requires.
 */
async function runGoalDraft(relativePath: string) {
  log(`goal-draft ${relativePath}`);
  const draftPath = join(process.cwd(), relativePath);
  let source = "";
  try {
    source = readFileSync(draftPath, "utf8");
  } catch {
    // A missing draft still produces a deterministic failure.
  }
  stream(`Reading the draft and researching the repository ${relativePath}`);

  if (source.includes("STUB-QUESTION")) {
    await askQuestions(1, { recommended: false });
  }
  if (source.includes("STUB-FAIL")) {
    throw new Error("goal label verification failed");
  }
  if (source.includes("STUB-HANG")) {
    while (goalDraftFinish === undefined || !existsSync(goalDraftFinish)) {
      await Bun.sleep(50);
    }
  }

  const name = basename(relativePath, ".md");
  const spec = join(process.cwd(), ".devboard", "goals", `${name}.md`);
  mkdirSync(dirname(spec), { recursive: true });
  writeFileSync(
    spec,
    [
      "## Objective",
      "",
      `Finalized ${name}.`,
      "",
      "## Success criteria",
      "",
      "- The stub wrote this spec.",
      "",
      "## Verification",
      "",
      "- Read this file.",
      "",
      "## Boundaries",
      "",
      "- The fixture only.",
      "",
      "## Stop conditions",
      "",
      "- Halt on a missing prerequisite.",
      "",
    ].join("\n"),
  );
  log(`goal-draft-verified ${relativePath}`);
  unlinkSync(draftPath);
  stream("Filed the goal issue and verified the goal label");
}

function promptText(params: unknown): string | undefined {
  if (typeof params !== "object" || params === null || !("prompt" in params)) return undefined;
  const blocks = Array.isArray(params.prompt) ? params.prompt : [];
  return blocks
    .map((block) => {
      if (typeof block !== "object" || block === null || !("text" in block)) return undefined;
      const value = block.text;
      return typeof value === "string" ? value : undefined;
    })
    .find((candidate): candidate is string => typeof candidate === "string");
}

/** JSON lines of a Flow session file, tolerant of an absent or partial file. */
function readLines(path: string): Record<string, unknown>[] {
  let source = "";
  try {
    source = readFileSync(path, "utf8");
  } catch {
    return [];
  }
  const entries: Record<string, unknown>[] = [];
  for (const line of source.split("\n")) {
    if (line.trim().length === 0) continue;
    try {
      const value: unknown = JSON.parse(line);
      if (typeof value === "object" && value !== null) entries.push(value as Record<string, unknown>);
    } catch {
      // A partial tail costs one entry.
    }
  }
  return entries;
}

function writeJsonFile(path: string, value: unknown) {
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
}

/** The exit status and piped output of one fixture git command. */
interface FlowGitOutput {
  exitCode: number | null;
  stdout: Buffer;
  stderr: Buffer;
}

function flowGit(repo: string, args: string[]): FlowGitOutput {
  return Bun.spawnSync({
    cmd: [
      "git",
      "-C",
      repo,
      "-c",
      "user.name=Flow Stub",
      "-c",
      "user.email=stub@example.test",
      "-c",
      "commit.gpgsign=false",
      ...args,
    ],
    stdout: "pipe",
    stderr: "pipe",
  });
}

function stream(text: string, append = false) {
  write({
    jsonrpc: "2.0",
    method: "session/update",
    params: {
      sessionId: "stub-session",
      update: {
        sessionUpdate: "agent_message_chunk",
        content: { type: "text", text },
        ...(append ? { messageId: "flow-stream" } : {}),
      },
    },
  });
}

/** Reads new steering notes and acknowledges each one before a checkpoint. */
function consumeSteering(directory: string): Record<string, unknown>[] {
  const notes = readLines(join(directory, "steering.jsonl"));
  const acked = new Set(
    readLines(join(directory, "steering-ack.jsonl")).map((entry) => String(entry.id ?? "")),
  );
  const fresh = notes.filter((note) => !acked.has(String(note.id ?? "")));
  for (const note of fresh) {
    mkdirSync(directory, { recursive: true });
    appendFileSync(join(directory, "steering-ack.jsonl"), `${JSON.stringify({ id: note.id })}\n`);
    log(`flow-ack ${String(note.id ?? "")}`);
    appendFileSync(join(process.cwd(), "steering-applied.txt"), `${String(note.text ?? "")}\n`);
  }
  log(`flow-steering-read ${fresh.length}`);
  return fresh;
}

async function runFlowGoal(directory: string) {
  log(`flow-goal ${directory}`);
  stream("Interviewing the developer about the Flow goal");
  if (flowGoalHang !== undefined && existsSync(flowGoalHang)) {
    log(`flow-goal-hung ${directory}`);
    await new Promise<never>(() => {});
  }
  if (flowGoalPartial !== undefined && existsSync(flowGoalPartial)) {
    mkdirSync(directory, { recursive: true });
    writeFileSync(join(directory, "goal.md"), flowGoalDraft);
    log(`flow-goal-partial ${directory}`);
    await new Promise<never>(() => {});
  }
  if (delayMs > 0) await Bun.sleep(delayMs);
  await askQuestions(1);
  if (flowGoalFail) {
    log("flow-goal-failed");
    return;
  }
  mkdirSync(directory, { recursive: true });
  let text = flowGoalText;
  if (flowGoalTextFile !== undefined) {
    try {
      text = readFileSync(flowGoalTextFile, "utf8");
    } catch {
      // The file is a one-shot override; absent means keep the default.
    }
  }
  writeFileSync(join(directory, "goal.md"), flowGoalEmpty ? "" : text);
  log(`flow-goal-written ${directory}`);
  if (flowGoalSettleMs > 0) await Bun.sleep(flowGoalSettleMs);
  stream("Wrote the Flow goal");
}

async function runFlowImplementation(directory: string) {
  // A fixture whose worktree could not be created must never commit the
  // harness checkout itself: `git add -A` there would rewrite the repository.
  if (isHarnessCheckout(process.cwd())) {
    log(`flow-implementation-refused-harness-root ${process.cwd()}`);
    return;
  }
  log(`flow-implement ${directory} cwd=${process.cwd()}`);
  stream("Reading the plan");

  if (flowQuestion) await askQuestions(1);
  if (flowPreCommitDelay > 0) await Bun.sleep(flowPreCommitDelay);

  for (let index = 1; index <= flowCheckpoints; index += 1) {
    try {
      const decisions = readFileSync(join(directory, "decisions.md"), "utf8");
      log(`flow-decisions-read ${index} ${decisions.length}`);
    } catch {
      log(`flow-decisions-read ${index} 0`);
    }
    if (index > 1) {
      if (flowWaitFile !== undefined) {
        const deadline = Date.now() + 30_000;
        while (!existsSync(flowWaitFile) && Date.now() < deadline) await Bun.sleep(25);
        log(`flow-wait-done ${existsSync(flowWaitFile) ? "yes" : "timeout"}`);
      }
      consumeSteering(directory);
    }
    mkdirSync(join(process.cwd(), "src"), { recursive: true });
    writeFileSync(join(process.cwd(), "src", "app.txt"), `version ${index}\n`);
    writeFileSync(
      join(process.cwd(), "src", "config.json"),
      `${JSON.stringify({ version: index }, null, 2)}\n`,
    );
    if (index > 1) writeFileSync(join(process.cwd(), "src", `extra-${index}.txt`), `extra ${index}\n`);

    // The server runs its own git commands on this worktree while the peer
    // commits, so an occasional index.lock makes the pair fail. Retry instead
    // of ending the peer and stranding the checkpoint the tests wait for.
    let added: FlowGitOutput | undefined;
    let committed: FlowGitOutput | undefined;
    for (let attempt = 1; attempt <= 5; attempt += 1) {
      added = flowGit(process.cwd(), ["add", "-A"]);
      if ((added.exitCode ?? 1) === 0) {
        committed = flowGit(process.cwd(), [
          "commit",
          "-m",
          `checkpoint ${index}: fixture change`,
        ]);
        if ((committed.exitCode ?? 1) === 0) break;
      }
      await Bun.sleep(50 * attempt);
    }
    if (committed === undefined || (committed.exitCode ?? 1) !== 0) {
      log(
        `flow-commit-failed ${committed?.stderr.toString().trim() ?? ""} ` +
          `add=${JSON.stringify(added?.stderr.toString().trim() ?? "")}`,
      );
      return;
    }
    const revision = flowGit(process.cwd(), ["rev-parse", "--short=7", "HEAD"]);
    const commit = revision.stdout.toString().trim();
    const verifiedAt = new Date().toISOString();
    if (!flowNoVerification) {
      writeJsonFile(join(directory, "verification.json"), {
        command: "bun test",
        status: flowVerification,
        timestamp: verifiedAt,
        output:
          flowVerification === "failed"
            ? "1 failing test: fixture verification failed\n"
            : "0 failing tests: fixture verification passed\n",
      });
    }
    mkdirSync(directory, { recursive: true });
    if (!flowSilentCheckpoints) {
      appendFileSync(
        join(directory, "checkpoints.jsonl"),
        `${JSON.stringify({
          id: `cp-${index}`,
          timestamp: verifiedAt,
          summary: `checkpoint ${index} — fixture change`,
          files: index > 1 ? 3 : 2,
          commit,
          verification: flowVerification,
        })}\n`,
      );
    }
    log(`flow-checkpoint ${index} ${commit}`);
    stream(`Committed checkpoint ${index}`);
    if (index < flowCheckpoints && flowStepDelay > 0) await Bun.sleep(flowStepDelay);
  }

  if (flowBlocked) {
    const message = "DEVBOARD-BLOCKED: the fixture cannot continue past this checkpoint";
    log("flow-blocked");
    stream(message);
    mkdirSync(directory, { recursive: true });
    appendFileSync(
      join(directory, "blockers.jsonl"),
      `${JSON.stringify({ id: "blocker-fixture", timestamp: new Date().toISOString(), text: message.slice("DEVBOARD-BLOCKED: ".length) })}\n`,
    );
  }

  // The server alone records these markers; the stub only streams them, so a
  // dismissal between two markers observes exactly what the real peer emits.
  for (const [index, text] of flowBlockerLines.entries()) {
    if (index > 0 && flowBlockerWaitFile !== undefined) {
      const deadline = Date.now() + 30_000;
      while (!existsSync(flowBlockerWaitFile) && Date.now() < deadline) await Bun.sleep(25);
      log(`flow-blocker-wait-done ${existsSync(flowBlockerWaitFile) ? "yes" : "timeout"}`);
    }
    log(`flow-blocker ${index + 1} ${text}`);
    stream(`DEVBOARD-BLOCKED: ${text}`);
  }
}

async function runFlowChange(directory: string) {
  log(`flow-change ${directory}`);
  stream("Classifying the changed files");
  const request = JSON.parse(readFileSync(join(directory, "request.json"), "utf8")) as {
    files?: { path?: unknown }[];
  };
  const files = (request.files ?? [])
    .map((file) => file.path)
    .filter((path): path is string => typeof path === "string");
  if (flowAnalystFail) {
    writeFileSync(join(directory, "widgets.json"), "this is not widget json");
    log("flow-widgets-failed");
    return;
  }
  if (flowAnalystEmpty) {
    writeJsonFile(join(directory, "widgets.json"), { widgets: [] });
    log("flow-widgets 0");
    return;
  }
  const selected = flowAnalystPartial ? files.slice(0, 1) : files;
  const widgets: unknown[] = [];
  if (selected.length > 0) {
    widgets.push({
      category: "contract",
      concept: "Application contract",
      summary: "The application's observable contract changed.",
      rationale: "Callers observe a different result.",
      files: [selected[0]],
    });
  }
  if (selected.length > 1) {
    widgets.push({
      category: "data",
      concept: "Stored configuration",
      summary: "The stored configuration changed.",
      rationale: "Persisted values have a new shape.",
      files: selected.slice(1),
    });
  }
  if (flowAnalystForeign) {
    widgets.push({
      category: "entity",
      concept: "A file outside the diff",
      summary: "This widget invents a file.",
      rationale: "It must be rejected by the server's validation.",
      files: ["src/not-in-the-diff.txt"],
    });
  }
  writeJsonFile(join(directory, "widgets.json"), { widgets });
  log(`flow-widgets ${widgets.length}`);
}

async function runFlowWidget(rest: string) {
  const split = /^(\S+)\s+(\S+)/.exec(rest);
  log(`flow-widget ${split?.[1] ?? ""} ${split?.[2] ?? ""}`);
  stream("Reviewing the widget and its diff");
  await probePermission();
  await askQuestions(1);
  stream("The widget conversation is read-only");
}

type DiscoverConfidence = "observed" | "declared" | "inferred" | "unknown";

interface DiscoverLabel {
  language: "en" | "de";
  text: string;
}

interface DiscoverConcept {
  id: string;
  prefLabels: DiscoverLabel[];
  altLabels: DiscoverLabel[];
  hiddenLabels: Array<DiscoverLabel & { reason: string; rejectedOn: string }>;
  definitions: DiscoverLabel[];
  scopeNote: null;
  example: null;
  historyNote: null;
  status: "unconfirmed" | "proposed";
  origin: "owner" | "llm";
  standardRef: null;
  kind: "entity" | "value";
  grounding: string[];
  broader: null;
  related: string[];
}

const discoverEvidenceCandidates = [
  "README.md",
  "package.json",
  "src",
  "test",
  ".github/workflows",
];

/** Existing repo-relative evidence paths, in candidate order, plus a safe fallback. */
function discoverEvidencePaths() {
  const available = discoverEvidenceCandidates.filter((path) =>
    existsSync(join(process.cwd(), path)),
  );
  const fallback = available.length > 0 ? available : ["."];
  return {
    available,
    primary: fallback[0] ?? ".",
    manifest: existsSync(join(process.cwd(), "package.json")) ? "package.json" : fallback[0] ?? ".",
    source: existsSync(join(process.cwd(), "src")) ? "src" : fallback[0] ?? ".",
    tests: existsSync(join(process.cwd(), "test")) ? "test" : fallback[0] ?? ".",
    ci: existsSync(join(process.cwd(), ".github", "workflows")) ? ".github/workflows" : undefined,
    hasManifest: existsSync(join(process.cwd(), "package.json")),
    hasTests: existsSync(join(process.cwd(), "test")),
    hasSource: existsSync(join(process.cwd(), "src")),
  };
}

function discoverLeaf(
  value: unknown,
  evidence: string[],
  confidence: DiscoverConfidence = "observed",
): Record<string, unknown> {
  return { value, evidence: [...new Set(evidence)].sort(), confidence };
}

function discoverUnknown(reason: string): Record<string, unknown> {
  return { value: null, evidence: [], confidence: "unknown", reason };
}

/** One-line, one-sentence bounded prose no longer than `limit` characters. */
function discoverOneSentence(text: string, limit: number): string {
  const flat = text.replace(/\s+/g, " ").trim().replace(/[.!?]+$/g, "").replace(/[.!?]\s+/g, " ");
  if (flat.length > limit - 1) return `${flat.slice(0, limit - 1).trimEnd()}.`;
  return `${flat}.`;
}

function discoverSheet(): Record<string, unknown> {
  const paths = discoverEvidencePaths();
  const evidence = [paths.primary];
  const sheet: Record<string, unknown> = {
    schemaVersion: 1,
    definition: discoverLeaf(
      discoverSheetTwoSentences
        ? "First sentence describes the fixture project. Second sentence describes the crawl."
        : discoverOneSentence(discoverProse, 240),
      evidence,
      "declared",
    ),
    stack: discoverLeaf(
      discoverVersionedNames ? ["Bun 1.2.3", "TypeScript 5.6.2"] : ["Bun", "TypeScript"],
      [paths.manifest],
      paths.hasManifest ? "declared" : "inferred",
    ),
    deployment: {
      class: discoverLeaf(
        paths.hasManifest ? "package" : "none",
        [paths.manifest],
        "observed",
      ),
      artifact: discoverLeaf("fixture-host", [paths.manifest], "declared"),
      target: discoverUnknown("No publication target was found in the crawled files."),
      pipelineSources:
        paths.ci === undefined
          ? discoverUnknown("No CI configuration was found in the crawled files.")
          : discoverLeaf([paths.ci], [paths.ci], "observed"),
    },
    environments: discoverLeaf(
      [{ name: "production", purpose: "Changes reach production through a direct push." }],
      evidence,
      "inferred",
    ),
    commands: {
      install: paths.hasManifest
        ? discoverLeaf("bun install", [paths.manifest], "declared")
        : discoverUnknown("No install command was found in the crawled files."),
      build: paths.hasManifest
        ? discoverLeaf("bun run build", [paths.manifest], "declared")
        : discoverUnknown("No build command was found in the crawled files."),
      test: paths.hasManifest
        ? discoverLeaf("bun test", [paths.manifest], "declared")
        : discoverUnknown("No test command was found in the crawled files."),
      lint: discoverUnknown("No lint command was found in the crawled files."),
      typecheck: discoverUnknown("No typecheck command was found in the crawled files."),
      dev: paths.hasManifest
        ? discoverLeaf("bun run dev", [paths.manifest], "declared")
        : discoverUnknown("No dev command was found in the crawled files."),
      tryOut: discoverUnknown("No try-out command was found in the crawled files."),
      release: discoverUnknown("No release command was found in the crawled files."),
    },
    branching: {
      defaultBranch: discoverLeaf("main", ["git branch"], "observed"),
      mergeMethod: discoverLeaf("merge commit", ["git log"], "inferred"),
      releaseBranches: discoverLeaf([], ["git branch"], "observed"),
      model: discoverLeaf("pull-request", ["git log"], "inferred"),
    },
    testing: {
      levels: paths.hasTests
        ? discoverLeaf(
            [
              discoverSheetNoHappyPath
                ? {
                    level: "unit",
                    tests: "1",
                    paths: [paths.tests],
                    command: "npm test",
                    fixtures: [],
                  }
                : {
                    level: "unit",
                    tests: "1",
                    happyPath: discoverSheetHappyOverflow ? "2" : "1",
                    paths: [paths.tests],
                    command: "npm run test:unit",
                    fixtures: [],
                  },
            ],
            [paths.tests],
            "observed",
          )
        : discoverUnknown("No test files were found in the crawled files."),
      pyramid: paths.hasTests
        ? discoverLeaf("Unit tests are the only observed level.", [paths.tests], "inferred")
        : discoverUnknown("No test files were found in the crawled files."),
    },
    architecture: {
      contexts: paths.hasSource
        ? discoverLeaf(
            [
              {
                name: "Checkout",
                path: "src/checkout",
                responsibility: "Turns a cart into a placed order.",
                entryPoints: ["src/checkout/flow.ts"],
              },
              {
                name: "Orders",
                path: "src",
                responsibility: "Owns order records and order totals.",
                entryPoints: ["src"],
              },
            ],
            ["src"],
            "observed",
          )
        : discoverUnknown("No source directory was found in the crawled files."),
      dependencies: paths.hasSource
        ? discoverLeaf([{ from: "Checkout", to: "Orders" }], ["src"], "observed")
        : discoverUnknown("No source directory was found in the crawled files."),
      dependencyDirection: paths.hasSource
        ? discoverLeaf(
            "Dependencies point inward toward the Orders domain code.",
            ["src"],
            "inferred",
          )
        : discoverUnknown("No source directory was found in the crawled files."),
      externalBoundaries: paths.hasSource
        ? discoverLeaf(["PostgreSQL", "api.stripe.com"], ["src"], "observed")
        : discoverUnknown("No source directory was found in the crawled files."),
      sharedKernels: paths.hasSource
        ? discoverLeaf(["src/shared"], ["src"], "observed")
        : discoverUnknown("No source directory was found in the crawled files."),
    },
    ci: {
      provider:
        paths.ci === undefined
          ? discoverLeaf("none detected", evidence, "observed")
          : discoverLeaf("GitHub Actions", [paths.ci], "observed"),
      triggers:
        paths.ci === undefined
          ? discoverLeaf([], evidence, "observed")
          : discoverLeaf(["push"], [paths.ci], "observed"),
      jobs:
        paths.ci === undefined
          ? discoverLeaf([], evidence, "observed")
          : discoverLeaf(["test"], [paths.ci], "observed"),
      qualityGates:
        paths.ci === undefined
          ? discoverLeaf([], evidence, "observed")
          : discoverLeaf(
              [{ name: "bun test", checks: "Runs the whole fixture test suite in CI." }],
              [paths.ci],
              "declared",
            ),
      artifacts:
        paths.ci === undefined
          ? discoverLeaf([], evidence, "observed")
          : discoverLeaf([], [paths.ci], "observed"),
    },
    runtime: {
      languages: discoverLeaf(
        [discoverVersionedNames ? "TypeScript 5.6.2" : "TypeScript"],
        [paths.manifest],
        "declared",
      ),
      runtimes: discoverLeaf(
        [discoverVersionedNames ? "Bun 1.2.3" : "Bun"],
        [paths.manifest],
        "declared",
      ),
      packageManagers: discoverLeaf(["bun"], [paths.manifest], "declared"),
      versions: discoverLeaf([], [paths.manifest], "observed"),
      manifests: paths.hasManifest
        ? discoverLeaf(["package.json"], [paths.manifest], "observed")
        : discoverUnknown("No manifest was found in the crawled files."),
    },
    dependencyMap: {
      binaries: discoverLeaf([], [paths.manifest], "observed"),
      packages: discoverLeaf([], [paths.manifest], "observed"),
      routes: discoverLeaf(
        discoverSheetRoutes ? ["/api/orders", "/", "GET /api/orders/:id"] : [],
        [paths.manifest],
        "observed",
      ),
      jobs: discoverLeaf([], [paths.manifest], "observed"),
      externalServices: discoverLeaf([], [paths.manifest], "observed"),
      dataStores: discoverLeaf([], [paths.manifest], "observed"),
      keyDependencies: discoverLeaf([], [paths.manifest], "declared"),
    },
    delivery: {
      artifactTarget: discoverLeaf("package", [paths.manifest], "declared"),
      releaseChannels: discoverLeaf([], [paths.manifest], "declared"),
      versionScheme: discoverUnknown("No versioning scheme was found in the crawled files."),
      migrationPolicy: discoverUnknown("No migration policy was found in the crawled files."),
    },
  };

  // Both leaf shapes were constructed above; the casts only narrow the variant mutations.
  const stack = sheet.stack as { value: unknown; evidence: string[] };
  const deployment = sheet.deployment as { artifact: { value: unknown } };
  if (discoverInvalidSheet) stack.value = ["x".repeat(200)];
  if (discoverSheetAbsolute) stack.evidence = ["/etc/passwd"];
  if (discoverSheetStrippedHome) stack.evidence = ["home/ds/project/file.ts"];
  if (discoverSheetNoEvidence) stack.evidence = [];
  if (discoverSheetSecret) deployment.artifact.value = DISCOVER_SECRET;

  return sheet;
}

function discoverLabelLines(field: string, labels: DiscoverLabel[]): string[] {
  if (labels.length === 0) return [`    ${field}: []`];
  return [
    `    ${field}:`,
    ...labels.flatMap((label) => [
      `      - language: ${label.language}`,
      `        text: ${JSON.stringify(label.text)}`,
    ]),
  ];
}

function discoverConceptLines(concept: DiscoverConcept): string[] {
  const hidden =
    concept.hiddenLabels.length === 0
      ? ["    hiddenLabels: []"]
      : [
          "    hiddenLabels:",
          ...concept.hiddenLabels.flatMap((label) => [
            `      - language: ${label.language}`,
            `        text: ${JSON.stringify(label.text)}`,
            `        reason: ${JSON.stringify(label.reason)}`,
            `        rejectedOn: ${JSON.stringify(label.rejectedOn)}`,
          ]),
        ];
  return [
    `  - id: ${concept.id}`,
    ...discoverLabelLines("prefLabels", concept.prefLabels),
    ...discoverLabelLines("altLabels", concept.altLabels),
    ...hidden,
    ...discoverLabelLines("definitions", concept.definitions),
    "    scopeNote: null",
    "    example: null",
    "    historyNote: null",
    `    status: ${concept.status}`,
    `    origin: ${concept.origin}`,
    "    standardRef: null",
    `    kind: ${concept.kind}`,
    "    grounding:",
    ...concept.grounding.map((entry) => `      - ${JSON.stringify(entry)}`),
    "    broader: null",
    `    related: ${JSON.stringify(concept.related)}`,
  ];
}

function discoverGlossary(): { yaml: string; concepts: DiscoverConcept[] } {
  const paths = discoverEvidencePaths();
  const available = paths.available.length > 0 ? paths.available : ["."];
  const firstGrounding = `code:${available[0] ?? "."}`;
  const secondGrounding = `code:${available[1] ?? available[0] ?? "."}`;
  const seed = discoverOneSentence(discoverProse, 152).replace(/\.$/, "");
  const order: DiscoverConcept = {
    id: "order",
    prefLabels: [{ language: "en", text: "Order" }],
    altLabels: [],
    hiddenLabels: [],
    definitions: [
      { language: "en", text: discoverOneSentence(`${seed} names one customer order request`, 160) },
    ],
    scopeNote: null,
    example: null,
    historyNote: null,
    status: "unconfirmed",
    origin: "owner",
    standardRef: null,
    kind: "entity",
    grounding: [discoverGlossaryHomePath ? "code:app/home/page.tsx" : firstGrounding],
    broader: null,
    related: [],
  };
  const orderTotal: DiscoverConcept = {
    id: discoverGlossaryInvalid ? "order" : "order-total",
    prefLabels: [{ language: "en", text: "Order Total" }],
    altLabels: [],
    hiddenLabels: [],
    definitions: [
      {
        language: "en",
        text: discoverOneSentence(`${seed} sums the lines of one order`, 160),
      },
    ],
    scopeNote: null,
    example: null,
    historyNote: null,
    status: "proposed",
    origin: "llm",
    standardRef: null,
    kind: "value",
    grounding: [discoverGlossaryGrounding ? "code:src/does-not-exist.ts" : secondGrounding],
    broader: null,
    related: [],
  };
  const option: DiscoverConcept = {
    id: "option",
    prefLabels: [{ language: "en", text: "Option" }],
    altLabels: [],
    hiddenLabels: [],
    definitions: [
      {
        language: "en",
        text: discoverOneSentence(`${seed} names an entry of a choice list`, 160),
      },
    ],
    scopeNote: null,
    example: null,
    historyNote: null,
    status: "unconfirmed",
    origin: "owner",
    standardRef: null,
    kind: "entity",
    grounding: [secondGrounding],
    broader: null,
    related: [],
  };
  const concepts = discoverGlossaryDrop ? [order] : [order, option, orderTotal];
  const lines = [
    "boundedContext: orders",
    "titles:",
    "  - language: en",
    `    text: ${JSON.stringify("Orders")}`,
    "concepts:",
    ...concepts.flatMap(discoverConceptLines),
  ];
  return { yaml: `${lines.join("\n")}\n`, concepts };
}

/** Scores the fixture concepts; the generic `option` scores lowest on purpose. */
const DISCOVER_SIGNIFICANCE: Record<string, { score: number; reason: string }> = {
  order: { score: 80, reason: "Every fixture checkout creates one order record." },
  option: { score: 10, reason: "A framework option token, not a domain term." },
  "order-total": { score: 90, reason: "The order total is the domain's central summed value." },
};

function discoverSignificanceSidecar(
  concepts: DiscoverConcept[],
): Record<string, unknown> {
  const ids = [...new Set(concepts.map((concept) => concept.id))];
  const entries: Record<string, { score: number; reason: string }> = Object.fromEntries(
    ids.map((id) => [
      id,
      { ...(DISCOVER_SIGNIFICANCE[id] ?? { score: 50, reason: "Observed in the fixture host." }) },
    ]),
  );
  const first = ids[0];
  if (discoverSignificance === "unknown-concept") delete entries[ids[1] ?? first ?? ""];
  if (discoverSignificance === "extra-concept" && first !== undefined) {
    entries["ghost-term"] = { score: 50, reason: "A concept that is not staged." };
  }
  if (discoverSignificance === "score") entries.option = { score: 101, reason: "Out of range." };
  if (discoverSignificance === "reason-empty") entries.option = { score: 10, reason: "  " };
  if (discoverSignificance === "reason-multiline") {
    entries.option = { score: 10, reason: "One line.\nA second line." };
  }
  if (discoverSignificance === "reason-absolute") {
    entries.option = { score: 10, reason: "/home/operator/secret.ts defines it." };
  }
  if (discoverSignificance === "reason-secret") {
    entries.option = { score: 10, reason: `Pinned by ${DISCOVER_SECRET}` };
  }
  const contexts: Record<string, unknown> = { orders: entries };
  if (discoverSignificance === "unknown-context") {
    contexts["other-context"] = { "another-term": { score: 50, reason: "Not a staged context." } };
  }
  if (discoverSignificance === "extra-key") return { schemaVersion: 1, contexts, note: "extra" };
  if (discoverSignificance === "schema") return { schemaVersion: 2, contexts };
  if (discoverSignificance === "score-object") {
    return { schemaVersion: 1, contexts: { orders: { order: { score: "80", reason: "Text score." } } } };
  }
  return { schemaVersion: 1, contexts };
}

interface DiscoverSkill {
  name: string;
  /** The level-one heading the staged skill body opens with. */
  title: string;
  description: string;
  body: string[];
}

function discoverSkills(): DiscoverSkill[] {
  const glossaryPath = ".omp/discover/glossary/orders.glossary.yaml";
  return [
    {
      name: "discover-testing-strategy",
      title: "Testing strategy",
      description:
        "Apply the observed unit-test level and the project's recorded test command before requesting review.",
      body: [
        "- Run `bun test` from the repository root before review.",
        "- Treat the unit level as the only implemented test level; add new cases there.",
        "- Add a failing case first and keep one assertion focus per test file.",
        "- Report untested areas as unknown instead of inventing an integration or end-to-end suite.",
      ],
    },
    {
      name: "discover-naming-conventions",
      title: "Naming conventions",
      description:
        "Name code after the grounded glossary terms and keep the observed casing across the project.",
      body: [
        `- Name domain types and functions after the preferred labels in ${glossaryPath}.`,
        "- Keep file names kebab-case and exported types PascalCase.",
        "- Use camelCase for functions, variables, and flags.",
        `- Reject aliases the glossary does not define; propose new terms through the glossary process in ${glossaryPath}.`,
      ],
    },
    {
      name: "discover-coding-conventions",
      title: "Coding conventions",
      description:
        "Keep typed, explicit code that reuses the dependencies the manifest already records.",
      body: [
        "- Keep exported functions typed; never leave an implicit any boundary.",
        "- Handle recoverable errors at the caller; never swallow a failure silently.",
        "- Prefer an already-installed dependency over adding a new one.",
        "- Run `bun test` before claiming a change is complete.",
      ],
    },
    {
      name: "discover-architecture-boundaries",
      title: "Architecture and boundaries",
      description:
        "Keep domain behavior inside its bounded context and preserve the observed dependency direction.",
      body: [
        "- Keep domain behavior inside its bounded context.",
        "- Point imports inward toward domain modules; never import delivery code from the domain.",
        `- Do not add a cross-context import without recording the boundary in ${glossaryPath}.`,
        "- Treat an external service as absent until a manifest or source file declares one.",
      ],
    },
    {
      name: "discover-glossary",
      title: "Glossary",
      description:
        "Use the canonical glossary, honor human decisions, and propose new terms explicitly.",
      body: [
        `- Treat ${glossaryPath} as the canonical glossary for every naming decision.`,
        "- Never write a confirmed status into a generated glossary; only a human confirm decision may do that.",
        "- Reject a proposed term with a non-empty reason instead of deleting it.",
        "- Propose new terms through Discover with grounding and let a human confirm them.",
        "- Never label code with an invalidated preferred label; no concept is invalidated in this baseline.",
      ],
    },
  ];
}

/** Marker a closed-unmerged fixture body carries; no artifact may quote it. */
const CLOSED_UNMERGED_MARKER = "CLOSED-UNMERGED-DESCRIPTION-MUST-NOT-LEAK";

interface StubMergedPullRequest {
  number: number;
  title: string;
  body: string;
  mergedAt: string;
  additions: number;
  deletions: number;
  files: string[];
  testFiles: number;
  documentationFiles: number;
  labels: string[];
  draft: boolean;
  approvals: number;
  checks: string[];
  commits: Array<{ subject: string; body: string }>;
  branch: string;
  mergeMethod: "merge" | "squash" | "rebase";
  references: number[];
}

/** Four merged pull requests, newest first, and one closed-unmerged number. */
const DISCOVER_MERGED_PULL_REQUESTS: StubMergedPullRequest[] = [
  {
    number: 12,
    title: "feat(orders): keep empty order totals at zero",
    body: "## Summary\n- Return zero for an empty order.\n- Cover the empty case.\n\nCloses #40",
    mergedAt: "2026-05-04T10:00:00.000Z",
    additions: 12,
    deletions: 3,
    files: ["src/order.ts", "test/order.test.ts"],
    testFiles: 1,
    documentationFiles: 0,
    labels: ["area:orders"],
    draft: false,
    approvals: 1,
    checks: ["ci/test"],
    commits: [{ subject: "feat(orders): return zero for empty totals", body: "" }],
    branch: "feat/empty-order-total",
    mergeMethod: "squash",
    references: [40],
  },
  {
    number: 11,
    title: "fix(checkout): reuse the order total",
    body:
      "## Summary\n- Reuse the existing total.\n\n## Test plan\n- Run the suite.\n\nCloses #38",
    mergedAt: "2026-04-20T09:30:00.000Z",
    additions: 20,
    deletions: 5,
    files: ["src/checkout/flow.ts", "test/order.test.ts", "docs/orders.md"],
    testFiles: 1,
    documentationFiles: 1,
    labels: ["area:checkout"],
    draft: false,
    approvals: 1,
    checks: ["ci/lint", "ci/test"],
    commits: [{ subject: "fix(checkout): reuse the order total", body: "" }],
    branch: "fix/reuse-order-total",
    mergeMethod: "squash",
    references: [38],
  },
  {
    number: 9,
    title: "docs(orders): document the total",
    body: "## Summary\nUpdate the guide.\n\n## Checklist\n- [x] Docs updated",
    mergedAt: "2026-03-15T12:00:00.000Z",
    additions: 4,
    deletions: 0,
    files: ["CHANGELOG.md", "docs/orders.md"],
    testFiles: 0,
    documentationFiles: 2,
    labels: ["documentation"],
    draft: false,
    approvals: 1,
    checks: ["ci/test"],
    commits: [{ subject: "docs(orders): document the total", body: "Refs #30" }],
    branch: "docs/order-total",
    mergeMethod: "squash",
    references: [30],
  },
  {
    number: 7,
    title: "test(orders): cover the empty total",
    body: "## Summary\n- Add a regression test.",
    mergedAt: "2026-02-01T08:00:00.000Z",
    additions: 8,
    deletions: 1,
    files: ["test/order.test.ts"],
    testFiles: 1,
    documentationFiles: 0,
    labels: ["tests"],
    draft: true,
    approvals: 2,
    checks: ["ci/test"],
    commits: [{ subject: "test(orders): cover the empty total", body: "" }],
    branch: "test/empty-total",
    mergeMethod: "merge",
    references: [],
  },
];

function contributionSource(): Record<string, unknown> {
  if (discoverContributionNoForge) {
    return {
      forge: null,
      host: null,
      unavailable: "No forge credential or network was available for the target.",
      window: null,
      mergedPullRequests: [],
      closedUnmergedPullRequests: [],
    };
  }
  const merged = DISCOVER_MERGED_PULL_REQUESTS.map((pullRequest) => {
    const body =
      discoverContributionInvalid === "secret"
        ? `${pullRequest.body}\n\nToken: ${DISCOVER_SECRET}`
        : pullRequest.body;
    return {
      number: pullRequest.number,
      title: pullRequest.title,
      body,
      mergedAt: pullRequest.mergedAt,
      additions: pullRequest.additions,
      deletions: pullRequest.deletions,
      filesChanged: pullRequest.files.length,
      files: [...pullRequest.files].sort(),
      testFiles: pullRequest.testFiles,
      documentationFiles: pullRequest.documentationFiles,
      labels: [...pullRequest.labels].sort(),
      draft: pullRequest.draft,
      approvals: pullRequest.approvals,
      checks: [...pullRequest.checks].sort(),
      commits: pullRequest.commits,
      branch: pullRequest.branch,
      mergeMethod: pullRequest.mergeMethod,
      references: pullRequest.references,
    };
  });
  const times = DISCOVER_MERGED_PULL_REQUESTS.map((pullRequest) => pullRequest.mergedAt).sort();
  return {
    forge: "gitea",
    host: "localhost",
    unavailable: null,
    window: { from: times[0], to: times[times.length - 1] },
    mergedPullRequests: merged,
    closedUnmergedPullRequests: [10],
  };
}

function contributionDoc(): Record<string, unknown> {
  const installFact =
    discoverContributionInvalid === "no-value"
      ? { key: "install", evidence: ["package.json"], confidence: "declared" }
      : discoverContributionInvalid === "unknown-value"
        ? {
            key: "install",
            value: "bun install",
            evidence: [],
            confidence: "unknown",
            reason: "No command was found.",
          }
        : discoverContributionInvalid === "absolute"
          ? {
              key: "install",
              value: "/home/operator/bin/install",
              evidence: ["package.json"],
              confidence: "declared",
            }
          : {
              key: "install",
              value: "bun install",
              evidence: ["package.json"],
              confidence: "declared",
            };
  return {
    schemaVersion: 1,
    source: contributionSource(),
    workflow: [
      {
        key: "entryPoints",
        value: ["CONTRIBUTING.md", ".github/pull_request_template.md"],
        evidence: ["README.md"],
        confidence: "declared",
      },
      {
        key: "steps",
        value: [
          "Fork the repository and create a feature branch.",
          "Run the whole test suite before requesting review.",
          "Open a pull request that links the issue it closes.",
        ],
        evidence: ["CONTRIBUTING.md"],
        confidence: "declared",
      },
      {
        key: "prerequisites",
        value: ["Bun"],
        evidence: ["package.json"],
        confidence: "declared",
      },
      installFact,
      {
        key: "build",
        value: "bun run build",
        evidence: ["package.json"],
        confidence: "declared",
      },
      {
        key: "lint",
        value: "bun run lint",
        evidence: ["package.json"],
        confidence: "declared",
      },
      {
        key: "typecheck",
        value: "bunx tsc --noEmit",
        evidence: ["package.json"],
        confidence: "declared",
      },
      {
        key: "run",
        value: "bun run start",
        evidence: ["package.json"],
        confidence: "declared",
      },
    ],
    testing: [
      {
        key: "suite",
        value: "bun test",
        evidence: ["package.json"],
        confidence: "declared",
      },
      {
        key: "levels",
        value: [
          {
            level: "unit",
            command: "bun test",
            paths: ["test"],
            fixtures: [],
          },
        ],
        evidence: ["test/order.test.ts"],
        confidence: "observed",
      },
    ],
  };
}

function contributionSkill(): DiscoverSkill {
  const sample = discoverContributionNoForge ? [] : [...DISCOVER_MERGED_PULL_REQUESTS]
    .sort((left, right) => Date.parse(right.mergedAt) - Date.parse(left.mergedAt) || right.number - left.number)
    .slice(0, 3);
  const bullets = discoverContributionNoForge
    ? [
        "- Read `.omp/discover/contribution.json` before writing a pull request.",
        "- Treat every pull-request-derived rule and exemplar as unknown: " +
          "No forge credential or network was available for the target.",
        "- Run `bun test` and report the test evidence in the pull request.",
      ]
    : [
        "- Read `.omp/discover/contribution.json` before writing a pull request.",
        "- Keep one accepted change to a median of 2 files (range 1-3) and median 10 additions (range 4-20).",
        "- Lead with a summary bullet, then the Summary and Test plan sections in that order.",
        "- Write the description in the imperative voice with a short, specific vocabulary.",
        "- Run `bun test` and include the test evidence in the pull request.",
        "- Reference the issue the change closes with a closing keyword and its number.",
        "- Use `feat(scope): summary` or `fix(scope): summary` commit subjects and `feat/` or `fix/` branches.",
        "- Wait for one approval and the ci/test and ci/lint checks before merging.",
        "- Update the documentation and CHANGELOG.md in the same pull request.",
      ];
  const exemplars =
    sample.length === 0
      ? []
      : [
          "## Exemplars",
          ...sample.flatMap((pullRequest) => [
            `> PR #${pullRequest.number} — ${pullRequest.title}`,
            ...(discoverContributionInvalid === "unmerged-excerpt" && pullRequest.number === 12
              ? [
                  `> PR #10 — closed: never merged`,
                  `> ${CLOSED_UNMERGED_MARKER}`,
                ]
              : []),
            ...pullRequest.body.split("\n").map((line) => (line.length === 0 ? ">" : `> ${line}`)),
          ]),
        ];
  const body =
    discoverContributionInvalid === "bad-skill"
      ? ["# Contribution", "A paragraph instead of a bullet."]
      : ["# Author a pull request this repository accepts", ...bullets, ...exemplars];
  return {
    name: "discover-contribution",
    title: "Contribution",
    description:
      "Author a pull request that matches the merged pull requests this repository accepts.",
    body,
  };
}

/** One agent's slice: its skill, the sheet, or the glossary and its sidecars. */
function discoverSkillFor(agent: string): DiscoverSkill | undefined {
  if (agent === "discover-contribution") return contributionSkill();
  return discoverSkills().find((skill) => skill.name === agent);
}

/**
 * The context the peer's staging tools run under. The peer is spawned in the
 * crawl root, so that root is the repository the tools write into; the harness
 * and state roots only matter to tools this peer never calls.
 */
function discoverToolContext(): McpContext {
  const repoDir = process.cwd();
  return {
    repoDir,
    harnessDir: join(repoDir, ".devboard"),
    stateDir: process.env.STATE_DIR ?? join(repoDir, ".devboard", ".tmp"),
    environment: process.env,
  };
}

/** Calls one staging tool and fails the turn when it refuses the call. */
async function stageDiscoverFile(
  context: McpContext,
  tool: string,
  args: Record<string, unknown>,
): Promise<void> {
  // Loaded lazily on purpose: every non-Discover fixture spawns this peer many
  // times, and a static import would make each flow peer load the whole MCP
  // module graph before its handshake.
  const { callTool } = await import("../../mcp/tools");
  const result = await callTool(context, tool, args);
  if (result.error !== undefined) {
    process.stderr.write(`stub: ${tool} failed: ${result.error}\n`);
    process.exit(2);
  }
}

async function runDiscoverAgent(agent: string, staging: string) {
  stream(`Reading the host for ${agent}`);
  stream(`Staging ${agent}`);
  if (discoverDelayMs > 0) await Bun.sleep(discoverDelayMs);
  if (discoverQuestion) await askQuestions(1);

  if (discoverError || (discoverFailAgent !== undefined && discoverFailAgent === agent)) {
    stream(`${agent} failed while reading manifests`);
    process.exit(1);
  }

  const context = discoverToolContext();
  mkdirSync(staging, { recursive: true });
  if (agent === "sheet") {
    await stageDiscoverFile(context, "discover_sheet_stage", {
      stagingDir: staging,
      sheet: discoverSheet(),
    });
  } else if (agent === "discover-glossary") {
    const glossary = discoverGlossary();
    await stageDiscoverFile(context, "discover_glossary_stage", {
      stagingDir: staging,
      context: "orders",
      yaml: glossary.yaml,
    });
    if (discoverSignificance !== "missing") {
      if (discoverSignificance === "invalid" || discoverSignificance === "array") {
        // The tool refuses a non-object sidecar, so the malformed-document
        // drill writes its bytes directly and proves publication reports them.
        mkdirSync(join(staging, "glossary"), { recursive: true });
        writeFileSync(
          join(staging, "glossary", "significance.json"),
          discoverSignificance === "invalid" ? "{ not json" : "[]",
        );
      } else {
        await stageDiscoverFile(context, "discover_significance_stage", {
          stagingDir: staging,
          significance: discoverSignificanceSidecar(glossary.concepts),
        });
      }
    }
    const skill = discoverSkillFor("discover-glossary");
    if (skill !== undefined) {
      await stageDiscoverFile(context, "discover_skill_stage", {
        stagingDir: staging,
        name: skill.name,
        description: skill.description,
        body: (skill.body[0]?.startsWith("# ") ? skill.body : [`# ${skill.title}`, "", ...skill.body]).join("\n"),
      });
    }
  } else {
    const skill = discoverSkillFor(agent);
    if (skill === undefined) {
      process.stderr.write(`stub: unknown discover agent ${agent}\n`);
      process.exit(2);
    }
    if (agent === "discover-contribution" && discoverContributionInvalid !== "missing-file") {
      await stageDiscoverFile(context, "discover_contribution_stage", {
        stagingDir: staging,
        contribution: contributionDoc(),
      });
    }
    if (!discoverMissingArtifact) {
      await stageDiscoverFile(context, "discover_skill_stage", {
        stagingDir: staging,
        name: skill.name,
        description: skill.description,
        body: (skill.body[0]?.startsWith("# ") ? skill.body : [`# ${skill.title}`, "", ...skill.body]).join("\n"),
      });
    }
  }

  if (discoverExtraArtifact) {
    writeFileSync(join(staging, "notes.txt"), "Extra staged note.\n");
  }

  if (discoverWriteOutside) {
    const note = join(process.cwd(), ".omp", "discover", "staging-note.txt");
    mkdirSync(dirname(note), { recursive: true });
    writeFileSync(note, "Written outside staging by the stub.\n");
    writeFileSync(
      join(process.cwd(), "GOAL.md"),
      "# Discover stub goal\n\nThe stub wrote outside staging.\n",
    );
    // The host fingerprint ignores .omp/discover, and the failure drill must
    // leave the published Discover tree byte-identical; GOAL.md still proves
    // the outside write.
    unlinkSync(note);
  }

  if (discoverNoExit) await Bun.sleep(delayMs > 0 ? delayMs : 60_000);
}


/**
 * The peer is announced with the prompt that starts its first turn, so a test
 * that counts peers sees the announcement together with the turn it started.
 */
let announced = false;

async function promptTurn(params: unknown) {
  if (!announced) {
    announced = true;
    log(`spawn ${process.pid}`);
    log(`argv ${process.argv.slice(2).join(" ")}`);
  }
  const text = promptText(params);
  const file = typeof text === "string" ? /(?:^|\s)(\S+\.md)(?:\s|$)/.exec(text)?.[1] : undefined;
  const firstLine = text?.split("\n")[0] ?? "";

  // A prompt-chat turn: the base prompt travels between the two markers, and
  // the reply proposes a complete replacement without writing anything.
  if (text !== undefined && text.includes("## Operator request") && text.includes("<<<PROMPT\n")) {
    log("prompt-chat");
    const start = text.indexOf("<<<PROMPT\n") + "<<<PROMPT\n".length;
    const end = text.indexOf("\nPROMPT>>>", start);
    const base = end < 0 ? "" : text.slice(start, end);
    stream("Here is the revision.");
    const proposal = `${base.trimEnd()}\n\n<!-- revised by the verification peer -->\n`;
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: `\n\n<prompt-file>\n${proposal}</prompt-file>\n` },
        },
      },
    });
    return;
  }

  if (goalSlug !== undefined && text !== undefined && text.includes(GOAL_SLUG_PROMPT_MARKER)) {
    log(`goal-slug ${firstLine}`);
    await probePermission();
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_thought_chunk",
          content: { type: "text", text: "Considering the report." },
          messageId: "goal-slug-thought",
        },
      },
    });
    stream(goalSlug);
    return;
  }

  if (ask && text !== undefined && text.includes(ASK_INSTRUCTION)) {
    askTurns += 1;
    const question = /(?:^|\n)Question: ([^\n]*)/.exec(text)?.[1] ?? "";
    log(`ask-prompt ${askTurns} ${question}`);
    log(`ask-text ${askTurns} ${JSON.stringify(text)}`);
    if (askStall && firstAskHandshake("stall")) {
      log("ask-stall");
      // Accept the prompt and never settle: the client's deadline must end the
      // turn and kill this process.
      await new Promise(() => {});
    }
    await probePermission();
    // Thoughts and tool activity precede the answer; the panel must drop them.
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_thought_chunk",
          content: { type: "text", text: "Considering the captured element before answering." },
          messageId: `ask-thought-${askTurns}`,
        },
      },
    });
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "tool_call",
          toolCallId: `ask-tool-${askTurns}`,
          title: "Reading the captured element",
          kind: "read",
          status: "pending",
        },
      },
    });
    if (askDelayMs > 0) await Bun.sleep(askDelayMs);
    // The first peer of a conversation exits; its replacement, which carries
    // the earlier turns, answers. A new process cannot see ask turns alone.
    const firstPeer = !text.includes("Earlier in this conversation:");
    if (askExit && firstPeer) {
      log("ask-exit");
      process.exit(0);
    }
    if (askFail && askTurns === 1) throw new Error("The ask agent failed.");
    const answer = askTurns === 1 ? ASK_ANSWER_ONE : ASK_ANSWER_TWO;
    const split = answer.indexOf(". ") + 2;
    stream(answer.slice(0, split).trim());
    if (askDelayMs > 0) await Bun.sleep(askDelayMs);
    stream(answer.slice(split).trim());
    return;
  }

  if (goalDraft && firstLine.startsWith("/goal-draft ")) {
    await runGoalDraft(firstLine.slice("/goal-draft ".length).trim());
    return;
  }
  if (flowGoal && firstLine.startsWith("/flow-goal ")) {
    log(`prompt ${firstLine}`);
    await runFlowGoal(firstLine.slice("/flow-goal ".length).trim());
    return;
  }
  if (flowImplement && firstLine.startsWith("/flow-implement ")) {
    log(`prompt ${firstLine}`);
    await runFlowImplementation(firstLine.slice("/flow-implement ".length).trim());
    return;
  }
  if (flowChange && firstLine.startsWith("/flow-change ")) {
    log(`prompt ${firstLine}`);
    await runFlowChange(firstLine.slice("/flow-change ".length).trim());
    return;
  }
  if (flowWidget && firstLine.startsWith("/flow-widget ")) {
    log(`prompt ${firstLine}`);
    await runFlowWidget(firstLine.slice("/flow-widget ".length).trim());
    return;
  }
  const revising = reviseGoal && text !== undefined && text.includes("Revise the goal");
  if (
    flowWidget &&
    text !== undefined &&
    !firstLine.startsWith("/") &&
    !revising
  ) {
    log(`flow-conversation ${firstLine}`);
    stream(`Developer: ${firstLine}`);
    return;
  }

  const discoverCommand = [
    "/discover-sheet",
    "/discover-contribution",
    "/discover-testing-strategy",
    "/discover-naming-conventions",
    "/discover-coding-conventions",
    "/discover-architecture-boundaries",
    "/discover-glossary",
  ].find((command) => firstLine.startsWith(`${command} `));
  if (discover && discoverCommand !== undefined) {
    log(`prompt ${firstLine}`);
    await runDiscoverAgent(
      discoverCommand === "/discover-sheet" ? "sheet" : discoverCommand.slice(1),
      firstLine.slice(discoverCommand.length).trim(),
    );
    return;
  }

  const creating = createGoal && firstLine === "/goal-outcome";
  log(`prompt ${firstLine}`);
  if (revising) log(`request ${text ?? ""}`);

  if (prepareSkills && firstLine === "/prepare-skills") {
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: {
            type: "text",
            text: "Researching public standards, architecture patterns, and testing practice",
          },
        },
      },
    });

    if (delayMs > 0) await Bun.sleep(delayMs);
    await askQuestions(forcedQuestions !== undefined ? Number(forcedQuestions) : 0);

    if (prepareSkillsError) process.exit(1);

    writePreparedSkills();
    log("prepared");
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: "Reviewed every installed skill; no contradictions" },
        },
      },
    });
    return;
  }

  const laneEpic =
    firstLine.startsWith("/implement-next-epic") && !creating && !revising
      ? implementationEpic(firstLine)
      : undefined;
  if (laneEpic !== undefined) {
    await runImplementationLane(laneEpic);
    return;
  }

  if (firstLine === "/epic-next" && !creating && !revising) {
    await runGenerationLane();
    return;
  }

  if (creating) {
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: "Creating the goal" },
        },
      },
    });
  } else if (revising) {
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: "Revising the goal" },
        },
      },
    });
  } else if (file === undefined) {
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: `Working on ${firstLine}` },
        },
      },
    });
  }

  if (delayMs > 0) await Bun.sleep(delayMs);

  if (file !== undefined && !revising) {
    write({
      jsonrpc: "2.0",
      method: "session/update",
      params: {
        sessionId: "stub-session",
        update: {
          sessionUpdate: "agent_message_chunk",
          content: { type: "text", text: `Inspecting ${basename(file)}` },
        },
      },
    });
  }

  const questionCount = creating || revising
    ? 1
    : forcedQuestions !== undefined
      ? Number(forcedQuestions)
      : file !== undefined && pendingCount(dirname(file)) === 1
        ? 1
        : 0;

  await askQuestions(questionCount);

  if (creating) {
    if (goalFile !== undefined && createGoalWrite) {
      writeFileSync(goalFile, CREATED_GOAL);
      log(`created ${goalFile}`);
      write({
        jsonrpc: "2.0",
        method: "session/update",
        params: {
          sessionId: "stub-session",
          update: {
            sessionUpdate: "agent_message_chunk",
            content: { type: "text", text: "Created the goal" },
          },
        },
      });
    }
    return;
  }

  if (revising) {
    if (goalFile !== undefined) {
      writeFileSync(goalFile, "# Revised goal\n\nThe agent rewrote this.");
      log(`revised ${goalFile}`);
      write({
        jsonrpc: "2.0",
        method: "session/update",
        params: {
          sessionId: "stub-session",
          update: {
            sessionUpdate: "agent_message_chunk",
            content: { type: "text", text: "Revised the goal" },
          },
        },
      });
    }
    return;
  }

  if (file !== undefined) {
    await Bun.sleep(SETTLE_DELAY_MS);
    if (removeRecord) {
      unlinkSync(file);
      log(`removed ${file}`);
    } else if (resolveRecord) {
      markAccepted(file);
      log(`resolved ${file}`);
      write({
        jsonrpc: "2.0",
        method: "session/update",
        params: {
          sessionId: "stub-session",
          update: {
            sessionUpdate: "agent_message_chunk",
            content: { type: "text", text: `Updated ${basename(file)}` },
          },
        },
      });
    }
  }
}

function handleMessage(message: Record<string, unknown>) {
  if (typeof message.method === "string" && message.id !== undefined) {
    if (message.method === "initialize") {
      if (askRefuseInitialize && firstAskHandshake("initialize")) {
        write({
          jsonrpc: "2.0",
          id: message.id,
          error: { code: -32603, message: "The Ask agent refused the handshake." },
        });
        return;
      }
      write({
        jsonrpc: "2.0",
        id: message.id,
        result: {
          protocolVersion: 1,
          agentInfo: { name: "stub-agent", version: "0.1.0" },
        },
      });
    } else if (message.method === "session/new") {
      if (askNoSession && firstAskHandshake("session")) {
        write({ jsonrpc: "2.0", id: message.id, result: {} });
        return;
      }
      log("session-new");
      write({ jsonrpc: "2.0", id: message.id, result: { sessionId: "stub-session" } });
    } else if (message.method === "session/prompt") {
      const text = promptText(message.params) ?? "";
      if (busyRemaining > 0 && text.startsWith("The implementation turn ended")) {
        busyRemaining -= 1;
        log("busy");
        write({
          jsonrpc: "2.0",
          id: message.id,
          error: {
            code: -32003,
            message: "Session is busy",
            data: { reason: "session_busy", hint: "steer|followUp|wait" },
          },
        });
        return;
      }
      promptChain = promptChain.then(async () => {
        try {
          await promptTurn(message.params);
          write({ jsonrpc: "2.0", id: message.id, result: { stopReason: "end_turn" } });
        } catch (error) {
          write({
            jsonrpc: "2.0",
            id: message.id,
            error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
          });
        }
      });
    } else if (message.method === "session/cancel") {
      // Nothing to do for the stub.
    } else {
      write({
        jsonrpc: "2.0",
        id: message.id,
        error: { code: -32601, message: `Method not found: ${message.method}` },
      });
    }
    return;
  }

  if (message.id === undefined) return;
  pending.get(String(message.id))?.(message.result);
  pending.delete(String(message.id));
}

// A killed peer records that it left exactly once, so a test can prove the close.
let loggedExit = false;
function logExit() {
  if (loggedExit) return;
  loggedExit = true;
  log(`exit ${process.pid}`);
}
process.on("exit", logExit);
process.on("SIGTERM", () => {
  logExit();
  process.exit(0);
});

const decoder = new TextDecoder();
let buffer = "";
for await (const chunk of Bun.stdin.stream()) {
  buffer += decoder.decode(chunk, { stream: true });
  let newline = buffer.indexOf("\n");
  while (newline >= 0) {
    const line = buffer.slice(0, newline).trim();
    buffer = buffer.slice(newline + 1);
    if (line.length > 0) {
      try {
        handleMessage(JSON.parse(line) as Record<string, unknown>);
      } catch {
        // Ignore malformed frames.
      }
    }
    newline = buffer.indexOf("\n");
  }
}
