@opsee/cli 0.11.9

package/src/foreman/core/install.ts

@@ -0,0 +1,109 @@
+/**
+ * Dependency install as a Foreman setup step (story 20): run once per new Workspace, before the
+ * Worker, so Workers do not each spend turns discovering how to install. The command is the
+ * analyzer's `commands.install` from `.opsee/config` when the repo has one, else inferred from the
+ * lockfile at the Workspace root. A non-zero exit does not fail the dispatch; the loop logs it and
+ * records it in the attempt event, since the Worker may still be able to work (or to fix it).
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { commandsOf } from "../../init/run-recipe-config.js";
+import { readOpseeConfigFiles } from "../../opsee-config.js";
+
+export interface InstallCommand {
+  /** What decided it: `commands.install` or the lockfile's name. */
+  source: string;
+  argv: string[];
+}
+
+/** Lockfile to install command, most specific first; the first match wins. */
+const LOCKFILES: [string, string[]][] = [
+  ["bun.lock", ["bun", "install", "--frozen-lockfile"]],
+  ["bun.lockb", ["bun", "install", "--frozen-lockfile"]],
+  ["pnpm-lock.yaml", ["pnpm", "install", "--frozen-lockfile"]],
+  ["yarn.lock", ["yarn", "install", "--frozen-lockfile"]],
+  ["package-lock.json", ["npm", "ci"]],
+  ["go.mod", ["go", "mod", "download"]],
+];
+
+export function inferInstallCommand(dir: string): InstallCommand | undefined {
+  const recipe = commandsOf(readOpseeConfigFiles(dir)).install;
+  if (recipe && recipe.trim() !== "") return { source: "commands.install", argv: ["sh", "-c", recipe] };
+  for (const [lockfile, argv] of LOCKFILES) {
+    if (existsSync(join(dir, lockfile))) return { source: lockfile, argv };
+  }
+  return undefined;
+}
+
+export interface InstallResult {
+  command: string;
+  /** Null when the process was killed (a signal, the timeout) or could not be started. */
+  exitCode: number | null;
+  durationMs: number;
+  /** The last lines of combined output, for the attempt event. */
+  outputTail: string;
+}
+
+const OUTPUT_TAIL_LINES = 40;
+
+/**
+ * How much of an output tail reaches an attempt event, in bytes. Forty lines is a shape, not a
+ * size: forty lines of a vitest diff, a webpack build or a stack trace is tens of thousands of
+ * characters on its own, and `RunAttemptEvent.summary` takes 20000 (proto/api/v1/initiative.proto).
+ * A tail bounded only by lines is how a summary grows past that limit, and a summary past the limit
+ * is an `InvalidArgument` the outbox refuses to queue — the attempt event is then lost outright,
+ * which under ADR-0009 is the loss of the commit itself. So the tail is bounded by both.
+ */
+export const OUTPUT_TAIL_BYTES = 4 * 1024;
+
+/** The last `maxBytes` of `text` in UTF-8, cut on a character boundary. */
+export function byteTail(text: string, maxBytes: number): string {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.length <= maxBytes) return text;
+  let start = buffer.length - maxBytes;
+  // A continuation byte (10xxxxxx) is the middle of a character: move past it.
+  while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) start++;
+  return buffer.subarray(start).toString("utf8");
+}
+
+/** The last lines of `text`, and at most `maxBytes` of them: the failure is at the bottom, so what
+ * is dropped is dropped from the top, and the cut says so the way every other cut here does. */
+export function tail(text: string, lines = OUTPUT_TAIL_LINES, maxBytes = OUTPUT_TAIL_BYTES): string {
+  const all = text.trimEnd().split("\n");
+  const kept = all.slice(Math.max(0, all.length - lines)).join("\n").trim();
+  const cut = byteTail(kept, maxBytes);
+  return cut === kept ? kept : `... (earlier output not shown)\n${cut}`;
+}
+
+/** Runs `command` in `dir` and reports how it went; never throws for a failing install. */
+export function runInstall(command: InstallCommand, dir: string, options: { timeoutMs?: number } = {}): Promise<InstallResult> {
+  const started = Date.now();
+  const rendered = command.source === "commands.install" ? command.argv[2] : command.argv.join(" ");
+  return new Promise((resolvePromise) => {
+    let output = "";
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command.argv[0], command.argv.slice(1), { cwd: dir, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    } catch (error) {
+      resolvePromise({ command: rendered, exitCode: null, durationMs: Date.now() - started, outputTail: (error as Error).message });
+      return;
+    }
+    const timer = options.timeoutMs
+      ? setTimeout(() => {
+          output = `${output.trimEnd()}\ninstall killed after ${options.timeoutMs}ms`;
+          child.kill("SIGKILL");
+        }, options.timeoutMs)
+      : undefined;
+    child.stdout?.on("data", (chunk: Buffer) => (output += chunk.toString()));
+    child.stderr?.on("data", (chunk: Buffer) => (output += chunk.toString()));
+    child.once("error", (error) => {
+      if (timer) clearTimeout(timer);
+      resolvePromise({ command: rendered, exitCode: null, durationMs: Date.now() - started, outputTail: tail(output + "\n" + error.message) });
+    });
+    child.once("exit", (code) => {
+      if (timer) clearTimeout(timer);
+      resolvePromise({ command: rendered, exitCode: code, durationMs: Date.now() - started, outputTail: tail(output) });
+    });
+  });
+}

package/src/foreman/core/learnings.ts

@@ -0,0 +1,368 @@
+/**
+ * Proposed Learnings -> one pull request (see ../../../CONTEXT.md: Proposed Learning, Accepted
+ * Learning; spec story 45). A Worker's Completion Report may carry reusable observations about the
+ * repository. They reach sibling Workers at once through Context Assembly, marked as proposed, but
+ * they become Accepted Learnings only when a human merges them into the repository's learnings
+ * file. At the end of a Run the Foreman gathers every Proposed Learning of the Run's Completion
+ * Reports, appends them to that file, each attributed to its Task and Hand-off, on a branch of its
+ * own in its own Workspace, pushes it through the guarded git runner and opens one draft pull
+ * request against the default branch, or adds to the one still open for the Initiative from an
+ * earlier Run. A Run with no Proposed Learning opens nothing.
+ *
+ * Where the file lives is the repository's to say: `foreman.learnings_file` in `.opsee/config`,
+ * `docs/learnings.md` by default. The Foreman only ever appends to it; what a human keeps, edits or
+ * drops there is the review. Two things keep the review the human's (ADR-0003): the Foreman writes
+ * only a branch of its own naming, never the head of some other pull request that happens to carry
+ * the title, and before adding to an open one it aligns its Workspace to what origin has, so an edit
+ * the reviewer pushed there is kept, not overwritten or fought with a rejected push.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { parseOpseeJson, readOpseeConfigFiles, readYamlBlock } from "../../opsee-config.js";
+import type { RemoteApi, RemotePullRequest } from "../remote-api.js";
+import { RECIPE_KEY } from "../run-recipe.js";
+import type { TrackerTask } from "../tracker-adapter.js";
+import type { Dispatch } from "./run.js";
+import { count, oneLine } from "./text.js";
+import { defaultBranchOf, type GitRunner, type Workspace, type WorkspaceManager } from "./workspace.js";
+
+export const DEFAULT_LEARNINGS_FILE = "docs/learnings.md";
+
+/** The key under the `foreman` block of `.opsee/config` that names the learnings file. */
+export const LEARNINGS_FILE_KEY = "learnings_file";
+
+/** What a new learnings file starts with, so a reader knows what the entries are and where they
+ * come from before the first pull request lands. */
+export const LEARNINGS_FILE_HEADER = [
+  "# Learnings",
+  "",
+  "Accepted Learnings about this repository: reusable observations Workers proposed in their",
+  "Completion Reports, gathered by the Foreman into a pull request at the end of each Run and",
+  "accepted by a human merging it. Every Worker reads this file at launch.",
+  "",
+].join("\n");
+
+/** One Proposed Learning with the Task it came from and the Hand-off, when there was one. */
+export interface ProposedLearning {
+  body: string;
+  task: Pick<TrackerTask, "id" | "identifier" | "title" | "url">;
+  handOffUrl?: string;
+}
+
+/** Every Proposed Learning of a Run's Completion Reports, in dispatch order. A turn that ended
+ * without a report has none; a `blocked` or `failed` report keeps its learnings, which are
+ * observations about the repository whatever the Task's fate. */
+export function collectProposedLearnings(dispatches: Dispatch[]): ProposedLearning[] {
+  const learnings: ProposedLearning[] = [];
+  for (const d of dispatches) {
+    if (!d.report) continue;
+    const handOffUrl = d.handOff?.kind === "handed_off" ? d.handOff.pullRequest.url : d.report.handOff?.prUrl;
+    for (const body of d.report.proposedLearnings) {
+      const text = body.trim();
+      if (text) learnings.push({ body: text, task: d.task, handOffUrl });
+    }
+  }
+  return learnings;
+}
+
+/** The learnings file of the repository at `root`, relative to it: `foreman.learnings_file` in
+ * `.opsee/config` (the JSON copy first, then the YAML block), else the default. A repository with
+ * no config at all has the default; a value that leaves the repository is refused. */
+export function learningsFileOf(root: string): string {
+  const files = readOpseeConfigFiles(root);
+  let raw: unknown;
+  if (files.json !== null) {
+    const block = parseOpseeJson(files.json)?.[RECIPE_KEY];
+    if (block && typeof block === "object") raw = (block as Record<string, unknown>)[LEARNINGS_FILE_KEY];
+  } else if (files.yaml !== null) {
+    raw = readYamlBlock(files.yaml, RECIPE_KEY)?.[LEARNINGS_FILE_KEY];
+  }
+  if (typeof raw !== "string" || raw.trim() === "") return DEFAULT_LEARNINGS_FILE;
+  const file = raw.trim();
+  const rel = normalize(file);
+  if (isAbsolute(file) || rel === ".." || rel.startsWith("../")) {
+    throw new Error(`foreman.${LEARNINGS_FILE_KEY} must name a file inside the repository, not "${file}"`);
+  }
+  return rel;
+}
+
+/** `Foreman: Proposed Learnings for Initiative 17`: the title the pull request is found by again
+ * on a later Run, so one Initiative has one open learnings pull request at a time. */
+export function learningsTitle(initiativeId: number): string {
+  return `Foreman: Proposed Learnings for Initiative ${initiativeId}`;
+}
+
+/** Every branch the learnings step writes starts with this; `isLearningsBranch` is the check. */
+export const LEARNINGS_BRANCH_PREFIX = "foreman/learnings-";
+
+/** `foreman/learnings-17-20260907t101500z`: a branch per batch, never one that could be a Task's. */
+export function learningsBranch(initiativeId: number, at: Date): string {
+  return `${LEARNINGS_BRANCH_PREFIX}${initiativeId}-${at.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "z").toLowerCase()}`;
+}
+
+/** Whether `branch` is one the Foreman named for this Initiative's learnings. A pull request found
+ * by title is the Foreman's only when its head is: anyone able to open a pull request can give it
+ * the title, and its head could be `main` or any protected branch the Foreman would then commit to
+ * and push (ADR-0003). */
+export function isLearningsBranch(branch: string, initiativeId: number): boolean {
+  return branch.startsWith(`${LEARNINGS_BRANCH_PREFIX}${initiativeId}-`);
+}
+
+function attribution(l: ProposedLearning): string {
+  const task = l.task.url ? `[${l.task.identifier}](${l.task.url})` : l.task.identifier;
+  const title = l.task.title.trim();
+  return `${task}${title ? ` "${title}"` : ""}${l.handOffUrl ? `, ${l.handOffUrl}` : ""}`;
+}
+
+/** `2026-09-07 10:15 UTC`: when the batch was gathered, to the minute, so two Runs on one day
+ * (or a Run and a re-dispatch) get headings of their own. */
+export function batchLabel(at: Date): string {
+  return `${at.toISOString().slice(0, 10)} ${at.toISOString().slice(11, 16)} UTC`;
+}
+
+export function batchHeading(initiativeId: number, at: Date): string {
+  return `## Initiative ${initiativeId}, Run of ${batchLabel(at)}`;
+}
+
+/** The entries appended to the learnings file for one Run: one heading for the batch, one bullet
+ * per learning with the Task and its Hand-off after it, so a reader of the file alone can tell
+ * where each came from and a human reviewing the pull request can open the work it came out of. */
+export function renderLearnings(learnings: ProposedLearning[], initiativeId: number, at: Date): string {
+  const lines = learnings.map((l) => `- ${oneLine(l.body)} (${attribution(l)})`);
+  return `\n${batchHeading(initiativeId, at)}\n\n${lines.join("\n")}\n`;
+}
+
+/** How many batches and learnings the pull request's branch carries in the Foreman's own commits
+ * (`tallyOf`), so the body can say what the whole proposal is, not only the latest batch. */
+export interface LearningsTally {
+  batches: number;
+  total: number;
+}
+
+const COMMIT_SUBJECT = /^docs: (\d+) Proposed Learnings? from the Foreman's Run on Initiative (\d+)$/;
+
+function commitSubject(appended: number, initiativeId: number): string {
+  return `docs: ${count(appended, "Proposed Learning")} from the Foreman's Run on Initiative ${initiativeId}`;
+}
+
+/** Reads the Foreman's own commits out of the branch's subjects (`git log --format=%s`), the way
+ * `commitSubject` writes them; a human's commit on the branch is not a batch. */
+export function tallyOf(subjects: string[], initiativeId: number): LearningsTally {
+  const tally: LearningsTally = { batches: 0, total: 0 };
+  for (const subject of subjects) {
+    const m = COMMIT_SUBJECT.exec(subject.trim());
+    if (!m || Number(m[2]) !== initiativeId) continue;
+    tally.batches++;
+    tally.total += Number(m[1]);
+  }
+  return tally;
+}
+
+/** The pull request body: what the whole branch proposes so far, the latest batch in full, by
+ * which Task, and what merging means. Earlier batches are not repeated here, since the reviewer
+ * may have edited or dropped them on the branch already; the diff of the file is the proposal. */
+export function learningsPullRequestBody(learnings: ProposedLearning[], initiativeId: number, file: string, at: Date, tally: LearningsTally): string {
+  const lines = learnings.map((l) => `- ${oneLine(l.body)}\n  - from ${attribution(l)}`);
+  const sofar =
+    tally.batches > 1
+      ? `${count(tally.total, "Proposed Learning")} in ${count(tally.batches, "batch", "batches")} so far, one per Run; the diff of \`${file}\` on this branch is the whole proposal, and only the latest batch is listed below.`
+      : `${count(learnings.length, "Proposed Learning")} in one batch so far; a later Run of the Initiative adds its batch to this branch while the pull request is open.`;
+  return [
+    `Draft by the Foreman: Proposed Learnings from the Completion Reports of Runs on Initiative ${initiativeId}, appended to \`${file}\`. ${sofar}`,
+    "",
+    "A Worker proposed each of these; none is trusted until this merges. Keep what holds, edit what is imprecise, drop the rest, then merge: what is left becomes an Accepted Learning every Worker reads at launch. Edits pushed to this branch are kept when the next batch is added.",
+    "",
+    `## Latest batch: Run of ${batchLabel(at)} (${count(learnings.length, "Proposed Learning")})`,
+    "",
+    lines.join("\n"),
+  ].join("\n");
+}
+
+export type LearningsResult =
+  | { kind: "opened" | "updated"; pullRequest: RemotePullRequest; count: number; file: string; branch: string; headSha: string }
+  | { kind: "none" }
+  /** Every learning of the batch was in the file already (a re-dispatched Task, a Run served twice). */
+  | { kind: "repeated"; count: number; file: string }
+  | { kind: "failed"; count: number; reason: string };
+
+export interface LearningsInput {
+  initiativeId: number;
+  learnings: ProposedLearning[];
+}
+
+export type LearningsFn = (input: LearningsInput) => Promise<LearningsResult>;
+
+export interface LearningsDeps {
+  /** Must be the guarded runner (workspace.ts `guardedGit`): the push relies on it. */
+  git: GitRunner;
+  remote: RemoteApi;
+  repoRoot: string;
+  workspaces: Pick<WorkspaceManager, "create">;
+  /** The learnings file, relative to the repository root (`learningsFileOf`). */
+  file: string;
+  log?: (line: string) => void;
+  now?: () => Date;
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** A learnings step that submits nothing and says why: what the Run gets when the repository's
+ * `foreman.learnings_file` is unusable, so the Run itself goes on and its tally names the cause. */
+export function learningsRefusedWith(reason: string): LearningsFn {
+  return async ({ learnings }) => (learnings.length === 0 ? { kind: "none" } : { kind: "failed", count: learnings.length, reason });
+}
+
+function normalized(text: string): string {
+  return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Whether the file already carries this learning: a bullet with the same body (whitespace and
+ * case aside) attributed to the same Task. A re-dispatched Task, or a Run served twice, reports
+ * the same observation again; the file gets it once. */
+export function alreadyInLearningsFile(content: string, learning: ProposedLearning): boolean {
+  const body = normalized(learning.body);
+  const identifier = new RegExp(`(^|[^a-z0-9])${escapeRegExp(normalized(learning.task.identifier))}([^a-z0-9]|$)`);
+  return content
+    .split("\n")
+    .filter((line) => line.startsWith("- "))
+    .map(normalized)
+    .some((line) => line.includes(body) && identifier.test(line));
+}
+
+export interface AppendedLearnings {
+  /** The file's content after the append (unchanged when nothing was appended). */
+  content: string;
+  /** The learnings actually added, in order; the batch is dropped when this is empty. */
+  appended: ProposedLearning[];
+  /** The learnings already in the file, left alone. */
+  skipped: ProposedLearning[];
+}
+
+/** Appends the batch to the learnings file in the Workspace, creating it with the header when it
+ * is not there yet, skipping every learning the file already has and writing nothing when none is
+ * new. */
+export function appendToLearningsFile(workspace: Pick<Workspace, "path">, file: string, learnings: ProposedLearning[], initiativeId: number, at: Date): AppendedLearnings {
+  const path = join(workspace.path, file);
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : LEARNINGS_FILE_HEADER;
+  const appended: ProposedLearning[] = [];
+  const skipped: ProposedLearning[] = [];
+  for (const l of learnings) (alreadyInLearningsFile(existing, l) || appended.some((a) => sameLearning(a, l)) ? skipped : appended).push(l);
+  if (appended.length === 0) return { content: existing, appended, skipped };
+  const content = `${existing.replace(/\s*$/, "")}\n${renderLearnings(appended, initiativeId, at)}`;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  return { content, appended, skipped };
+}
+
+function sameLearning(a: ProposedLearning, b: ProposedLearning): boolean {
+  return normalized(a.body) === normalized(b.body) && normalized(a.task.identifier) === normalized(b.task.identifier);
+}
+
+/** The step the Run loop calls once, after its last dispatch (run.ts). */
+export function learningsWith(deps: LearningsDeps): LearningsFn {
+  const log = deps.log ?? (() => {});
+  const now = deps.now ?? (() => new Date());
+  return async ({ initiativeId, learnings }) => {
+    if (learnings.length === 0) {
+      log(`learnings: no Proposed Learning in this Run's Completion Reports; no pull request`);
+      return { kind: "none" };
+    }
+    const { git, remote, repoRoot, file } = deps;
+    const failed = (reason: string): LearningsResult => {
+      log(`learnings: ${reason}`);
+      return { kind: "failed", count: learnings.length, reason };
+    };
+    const at = now();
+    const title = learningsTitle(initiativeId);
+
+    const base = await defaultBranchOf(git, repoRoot);
+    if (!base) return failed("origin has no default branch the Foreman could target with a pull request");
+
+    // One open learnings pull request per Initiative: a later Run adds to it rather than opening a
+    // second one for the human to reconcile. Only one against the default branch, from a branch of
+    // the Foreman's own naming, is the Foreman's: the title is anyone's to give, the branch is not.
+    let existing: RemotePullRequest | undefined;
+    try {
+      existing = await remote.findPullRequestByTitle(title);
+    } catch (error) {
+      return failed(`could not look for an open learnings pull request: ${message(error)}`);
+    }
+    if (existing && existing.baseBranch !== base) {
+      log(`learnings: the open pull request ${existing.url} titled "${title}" targets "${existing.baseBranch}", not "${base}"; opening a new one`);
+      existing = undefined;
+    }
+    if (existing && !isLearningsBranch(existing.headBranch, initiativeId)) {
+      log(`learnings: the open pull request ${existing.url} titled "${title}" comes from "${existing.headBranch}", not a ${LEARNINGS_BRANCH_PREFIX}${initiativeId}-* branch of the Foreman's; leaving it alone and opening a new one (ADR-0003)`);
+      existing = undefined;
+    }
+    const branch = existing?.headBranch ?? learningsBranch(initiativeId, at);
+
+    let workspace: Workspace;
+    try {
+      workspace = await deps.workspaces.create(branch);
+    } catch (error) {
+      return failed(`could not create a Workspace on ${branch}: ${message(error)}`);
+    }
+    if (existing) {
+      // The branch is the reviewer's as much as the Foreman's: whatever was pushed to it since the
+      // Workspace was made (an entry edited or dropped) is what this batch goes after, or the push
+      // below would be rejected for good. A reset cannot reach origin; the guard allows it.
+      try {
+        await git(["fetch", "--quiet", "origin", branch], workspace.path);
+        await git(["reset", "--quiet", "--hard", `origin/${branch}`], workspace.path);
+      } catch (error) {
+        return failed(`could not align the Workspace on ${branch} with origin before adding to ${existing.url}: ${message(error)}`);
+      }
+    }
+
+    const { content, appended, skipped } = appendToLearningsFile(workspace, file, learnings, initiativeId, at);
+    if (skipped.length > 0) log(`learnings: ${count(skipped.length, "entry", "entries")} already in ${file} on ${branch}; not repeated`);
+    if (appended.length === 0) {
+      log(`learnings: every Proposed Learning of this Run is in ${file} on ${branch} already; nothing to submit`);
+      return { kind: "repeated", count: learnings.length, file };
+    }
+    log(`learnings: appended ${count(appended.length, "entry", "entries")} to ${file} in ${workspace.path} (${content.length} chars)`);
+
+    try {
+      await git(["add", "--", file], workspace.path);
+      // The Foreman's own commit: never signed interactively, which would hold an unattended Run,
+      // and past the repository's commit hooks, which are written for a person at a terminal.
+      await git(["-c", "commit.gpgsign=false", "commit", "--quiet", "--no-verify", "-m", commitSubject(appended.length, initiativeId)], workspace.path);
+    } catch (error) {
+      return failed(`could not commit ${file} on ${branch}: ${message(error)}`);
+    }
+    try {
+      await git(["push", "--set-upstream", "origin", `${branch}:${branch}`], workspace.path);
+    } catch (error) {
+      return failed(`push of ${branch} to origin failed: ${message(error)}`);
+    }
+    const headSha = await git(["rev-parse", branch], workspace.path);
+    log(`learnings: pushed ${branch} (${headSha.slice(0, 12)}) to origin`);
+
+    let tally: LearningsTally = { batches: 1, total: appended.length };
+    try {
+      tally = tallyOf((await git(["log", "--format=%s", `origin/${base}..HEAD`], workspace.path)).split("\n"), initiativeId);
+    } catch {
+      /* the body then speaks of this batch alone */
+    }
+    const body = learningsPullRequestBody(appended, initiativeId, file, at, tally);
+    try {
+      if (existing) {
+        const pullRequest = await remote.updatePullRequest(existing.number, { title, body });
+        log(`learnings: added to the open pull request ${pullRequest.url}`);
+        return { kind: "updated", pullRequest, count: appended.length, file, branch, headSha };
+      }
+      const pullRequest = await remote.openDraftPullRequest({ headBranch: branch, baseBranch: base, title, body });
+      log(`learnings: opened draft pull request ${pullRequest.url} against ${base} with ${count(appended.length, "Proposed Learning")}`);
+      return { kind: "opened", pullRequest, count: appended.length, file, branch, headSha };
+    } catch (error) {
+      return failed(`${branch} is pushed, but the pull request against ${base} failed: ${message(error)}`);
+    }
+  };
+}

package/src/foreman/core/outbox-tracker.ts

@@ -0,0 +1,192 @@
+/**
+ * The outbox-backed Tracker (story 50, ADR-0009): a Tracker Adapter that behaves like the one it
+ * wraps except that a Run Record write which cannot reach the backend is queued in the Process
+ * Table's outbox instead of failing the turn, and drained, in order, once the backend answers
+ * again. Every other operation passes straight through: the board moves and comments are not the
+ * commit, the Run Record write is, and that is the one that must never be lost.
+ *
+ * Order is kept two ways: a new append first drains what is already queued for the Initiative
+ * (and joins the queue itself when that fails), and `drain` stops at the first failure. What the
+ * loop reads back through `readRunRecord` includes the queued batches, so attempt numbering stays
+ * right while the backend is away. A queued batch the backend later refuses outright (the
+ * Initiative is gone, the payload is rejected) is dropped and logged rather than left to hold
+ * every batch behind it.
+ *
+ * Every operation that touches the outbox is taken one at a time (`serialize`). Slots
+ * (core/scheduler.ts) made dispatch concurrent, and `drain` is read-then-send-then-delete with
+ * nothing under it to serialise: two of them at once would read the same pending batch and both
+ * send it. A duplicated `dispatch` event is not a cosmetic repeat — `attempt = priorDispatches + 1`
+ * counts those events, so every later attempt on that Task takes a number that skips, and
+ * `finishSettlement` and the Verdict lookups, which match an attempt by number, then look at the
+ * wrong one.
+ *
+ * **Serialising is not enough on its own, which is what the idempotency key is for.** The codes this
+ * queues on include `DeadlineExceeded` and `Unknown` — the two where the backend may have committed
+ * the write and only the answer was lost. Nothing local can tell that apart from a write that never
+ * landed, so the batch is queued either way and re-sent, and without a key the re-send appends the
+ * same events a second time: exactly the duplicate above, arrived by a route no amount of
+ * in-process locking closes. Every event is therefore stamped with a key *before the first send*,
+ * and the backend refuses to store a key it already has under that Run. The key rides inside the
+ * event, so the outbox stores it with everything else and a re-send is the same events under the
+ * same keys, however many times it takes.
+ */
+import { randomUUID } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { RunEventSchema, type RunEvent, type RunEventInput } from "@opsee/mcp-server/gen/api/v1/initiative_pb.js";
+import type { RunRecord, RunRecordQuery, TrackerAdapter } from "../tracker-adapter.js";
+import type { DrainResult, ProcessTableApi } from "./process-table.js";
+import { errorMessage } from "../worker-process.js";
+
+/** Codes that mean the backend could not be reached or did not answer, so the write may succeed
+ * later. A non-Connect error is a transport failure. */
+const QUEUEABLE = new Set<Code>([Code.Unavailable, Code.DeadlineExceeded, Code.Unknown, Code.Internal, Code.Aborted, Code.ResourceExhausted]);
+
+/** Codes that mean the backend has looked at the batch and will never take it: the events are
+ * malformed, or what they point at is gone. Only these are dropped from the outbox. Everything
+ * else in between (a token that expired while the daemon idled, a permission pulled, a proxy
+ * answering 404 for a backend that is mid-deploy) keeps the batch waiting: dropping it there
+ * would lose the Run Record's own commit for an attempt whose row is already gone. */
+const REFUSED = new Set<Code>([Code.InvalidArgument, Code.NotFound, Code.FailedPrecondition, Code.OutOfRange]);
+
+export function isQueueable(error: unknown): boolean {
+  if (error instanceof ConnectError) return QUEUEABLE.has(error.code);
+  return true;
+}
+
+/** Whether a queued batch should be dropped rather than retried. */
+export function isRefused(error: unknown): boolean {
+  return error instanceof ConnectError && REFUSED.has(error.code);
+}
+
+type Outbox = Pick<ProcessTableApi, "enqueue" | "pending" | "drain">;
+
+export class OutboxTracker implements TrackerAdapter {
+  constructor(
+    private readonly inner: TrackerAdapter,
+    private readonly outbox: Outbox,
+    private readonly log: (line: string) => void,
+    /** How a key is minted. Injected for the tests alone, the way `now` and `sleep` are elsewhere:
+     * a key has to be unpredictable in life and fixed in a test, and nothing else about it matters. */
+    private readonly newKey: () => string = randomUUID,
+  ) {}
+
+  /** Outbox work in flight: every call that reads or writes the outbox links onto this chain, so
+   * only one of them is inside it at a time. In-process only, like the Workspace queue: it is the
+   * Slots of one Run that made this concurrent, and two Foreman processes sharing a Process Table
+   * would still need the database to keep them apart. */
+  private queue: Promise<unknown> = Promise.resolve();
+
+  /** Runs `work` once whatever outbox work is already going has finished, however it finished: a
+   * failed drain must not poison the calls behind it. */
+  private serialize<T>(work: () => Promise<T>): Promise<T> {
+    const mine = this.queue.then(work, work);
+    this.queue = mine.then(
+      () => undefined,
+      () => undefined,
+    );
+    return mine;
+  }
+
+  listReadyTasks: TrackerAdapter["listReadyTasks"] = (id) => this.inner.listReadyTasks(id);
+  getTask: TrackerAdapter["getTask"] = (id) => this.inner.getTask(id);
+  addComment: TrackerAdapter["addComment"] = (id, body) => this.inner.addComment(id, body);
+  addInitiativeComment: TrackerAdapter["addInitiativeComment"] = (id, body) => this.inner.addInitiativeComment(id, body);
+  moveTask: TrackerAdapter["moveTask"] = (id, lifecycle) => this.inner.moveTask(id, lifecycle);
+  attachLabel: TrackerAdapter["attachLabel"] = (id, label) => this.inner.attachLabel(id, label);
+  detachLabel: TrackerAdapter["detachLabel"] = (id, label) => this.inner.detachLabel(id, label);
+  ensureLabel: TrackerAdapter["ensureLabel"] = (id, label) => this.inner.ensureLabel(id, label);
+  createTask: TrackerAdapter["createTask"] = (input) => this.inner.createTask(input);
+  projectRepositories: TrackerAdapter["projectRepositories"] = (id) => this.inner.projectRepositories(id);
+  linkPullRequest: TrackerAdapter["linkPullRequest"] = (id, pr) => this.inner.linkPullRequest(id, pr);
+  addMemory: TrackerAdapter["addMemory"] = (id, entry) => this.inner.addMemory(id, entry);
+  listMemory: TrackerAdapter["listMemory"] = (id, query) => this.inner.listMemory(id, query);
+  getInitiativeContext: TrackerAdapter["getInitiativeContext"] = (id) => this.inner.getInitiativeContext(id);
+
+  /** Sends what is queued for the Initiative (or everything), oldest first, stopping at the first
+   * failure; the Run loop calls this at the top of each tick, while dispatches are in flight. */
+  drain(initiativeId?: number): Promise<DrainResult> {
+    return this.serialize(() => this.drainNow(initiativeId));
+  }
+
+  /** The drain itself. Only ever called with the queue held: from `serialize`, or from `appendNow`,
+   * which already holds it. */
+  private async drainNow(initiativeId?: number): Promise<DrainResult> {
+    const filter = initiativeId === undefined ? {} : { initiativeId };
+    if (this.outbox.pending(filter).length === 0) return { sent: 0, remaining: 0, discarded: [] };
+    const result = await this.outbox.drain((id, events) => this.inner.appendRunEvents(id, events), { ...filter, discard: isRefused });
+    for (const batch of result.discarded) {
+      const kinds = batch.events.map((e) => e.payload?.payload.case ?? "event").join(", ");
+      this.log(`outbox: batch ${batch.id} (${kinds}) for Initiative ${batch.initiativeId} dropped: the backend refused it, so it would never be taken`);
+    }
+    if (result.sent) this.log(`outbox: ${result.sent} queued Run Record ${result.sent === 1 ? "batch" : "batches"} delivered${result.remaining ? `, ${result.remaining} still waiting` : ""}`);
+    if (result.error) this.log(`outbox: ${result.remaining} ${result.remaining === 1 ? "batch" : "batches"} waiting; the backend did not take the next one: ${result.error.message}`);
+    return result;
+  }
+
+  appendRunEvents(initiativeId: number, events: RunEventInput[]): Promise<RunEvent[]> {
+    return this.serialize(() => this.appendNow(initiativeId, events));
+  }
+
+  /**
+   * Stamps an idempotency key on every event that has none, in place.
+   *
+   * Before the first send, not on the way into the outbox: the duplicate this exists to stop is the
+   * one where that first send *succeeded* and its answer was lost, and a key minted after the
+   * failure would be a different key from the one the backend already stored. The same objects go
+   * on to be queued, so the re-send carries the keys the first attempt used.
+   *
+   * An event that already has one keeps it, so a caller that mints its own is not overruled.
+   */
+  private keyed(events: RunEventInput[]): RunEventInput[] {
+    for (const event of events) if (!event.idempotencyKey) event.idempotencyKey = this.newKey();
+    return events;
+  }
+
+  private async appendNow(initiativeId: number, events: RunEventInput[]): Promise<RunEvent[]> {
+    this.keyed(events);
+    // What is already queued goes first, or this batch joins the queue behind it. `drainNow`, since
+    // this call holds the queue already and asking for it again would wait on itself.
+    if (this.outbox.pending({ initiativeId }).length > 0) {
+      const drained = await this.drainNow(initiativeId);
+      if (drained.error) return this.queueBatch(initiativeId, events, drained.error);
+    }
+    try {
+      return await this.inner.appendRunEvents(initiativeId, events);
+    } catch (error) {
+      if (!isQueueable(error)) throw error;
+      return this.queueBatch(initiativeId, events, error);
+    }
+  }
+
+  private queueBatch(initiativeId: number, events: RunEventInput[], error: unknown): RunEvent[] {
+    const id = this.outbox.enqueue(initiativeId, events);
+    const kinds = events.map((e) => e.payload?.payload.case ?? "event").join(", ");
+    this.log(`outbox: Run Record write queued as batch ${id} (${kinds}); the backend did not take it: ${errorMessage(error)}`);
+    return events.map((e) => placeholder(initiativeId, e));
+  }
+
+  /** The backend's Run Record followed by the queued batches that match, so a count of dispatches
+   * or a check for an attempt event sees what is committed locally and not yet delivered. Taken
+   * one at a time with the rest: a drain that delivered a batch between the read of the backend's
+   * record and the read of the outbox would leave that batch in neither, and the count of
+   * dispatches an attempt number is made of would be one short. */
+  readRunRecord(initiativeId: number, query: RunRecordQuery = {}): Promise<RunRecord> {
+    return this.serialize(() => this.readNow(initiativeId, query));
+  }
+
+  private async readNow(initiativeId: number, query: RunRecordQuery): Promise<RunRecord> {
+    const record = await this.inner.readRunRecord(initiativeId, query);
+    const queued = this.outbox
+      .pending({ initiativeId })
+      .flatMap((b) => b.events)
+      .filter((e) => (query.taskId === undefined || e.taskId === query.taskId) && (!query.kinds || query.kinds.includes(e.payload?.payload.case ?? "")))
+      .map((e) => placeholder(initiativeId, e));
+    return queued.length ? { run: record.run, events: [...record.events, ...queued] } : record;
+  }
+}
+
+/** A queued event as the loop sees it: id 0 says it has no server id yet. */
+function placeholder(initiativeId: number, input: RunEventInput): RunEvent {
+  return create(RunEventSchema, { id: 0, runId: 0, initiativeId, kind: input.payload?.payload.case ?? "", taskId: input.taskId, payload: input.payload, isAgent: true });
+}