omp-conductor 0.20.2 → 0.20.3

package/src/fleet.ts

@@ -1120,7 +1120,7 @@ export interface WorkerPaneDeps {
   run?: HerdrRun;
   session?: string;
   /** The follower command the pane displays; the CLI by default. */
-  viewer?: (identity: WorkerPaneIdentity) => readonly string[];
+  viewer?: (identity: PaneCeremonyIdentity) => readonly string[];
   /** The durable ownership half of workspace discovery (#1035 review);
    *  production wires the conductor store, tests a recorder. */
   ownership?: WorkspaceOwnership;
@@ -1178,7 +1178,17 @@ export function workerWorkspaceLabel(project: string): string {
   return `${project}-workers`;
 }
 
-export function workerPaneLabel(identity: WorkerPaneIdentity): string {
+/** The identity fields a representation's ceremony actually reports (#1110).
+ *  The spawn pid rides on {@link WorkerPaneIdentity} for the record; naming,
+ *  attribution and the viewer command never read it, so the retile's
+ *  transplant can re-establish a representation without pretending to know a
+ *  pid it cannot prove. */
+type PaneCeremonyIdentity = Pick<WorkerPaneIdentity, "project" | "issue" | "attempt" | "runId"> & {
+  /** The spawn pid, when the caller holds one; the ceremony never reads it. */
+  pid?: number;
+  sessionFile?: string;
+};
+export function workerPaneLabel(identity: PaneCeremonyIdentity): string {
   return `worker-${identity.project}-${identity.issue}-a${identity.attempt}-${identity.runId.slice(0, 8)}`;
 }
 
@@ -1192,7 +1202,7 @@ const realHerdrRun: HerdrRun = (args) => {
 };
 
 /** `omp-conductor tail` — read-only by construction, and never parsed here. */
-function defaultViewer(identity: WorkerPaneIdentity): readonly string[] {
+function defaultViewer(identity: PaneCeremonyIdentity): readonly string[] {
   return ["omp-conductor", "tail", String(identity.issue), "--project", identity.project];
 }
 
@@ -1309,6 +1319,8 @@ export interface ListedPane {
   runId: string;
   agent?: string;
   workspaceId?: string;
+  /** The tab holding this pane, when Herdr reports one (#1110). */
+  tabId?: string;
 }
 
 /** The panes of a `pane list` answer, carrying whichever fields reconciliation reads. */
@@ -1332,11 +1344,73 @@ function parsePaneRecords(stdout: string): { panes: ListedPane[] } | undefined {
       runId: typeof value === "string" && source === WORKER_PANE_SOURCE ? value : "",
       ...(typeof p["agent"] === "string" ? { agent: p["agent"] } : {}),
       ...(typeof p["workspace_id"] === "string" ? { workspaceId: p["workspace_id"] } : {}),
+      ...(typeof p["tab_id"] === "string" ? { tabId: p["tab_id"] } : {}),
     });
   }
   return { panes };
 }
 
+/** The new tab inside a `tab create` answer (`result.tab`, `result.root_pane`). */
+function parseCreatedTab(stdout: string): { tabId?: string; rootPaneId?: string } | undefined {
+  const result = envelopeOf(stdout);
+  if (result === undefined) return undefined;
+  const tab = result["tab"];
+  const root = result["root_pane"];
+  const tabId =
+    tab !== null && typeof tab === "object" ? (tab as Record<string, unknown>)["tab_id"] : undefined;
+  const rootPaneId =
+    root !== null && typeof root === "object" ? (root as Record<string, unknown>)["pane_id"] : undefined;
+  const id = typeof tabId === "string" && tabId.trim() !== "" ? tabId.trim() : undefined;
+  const rootId =
+    typeof rootPaneId === "string" && rootPaneId.trim() !== "" ? rootPaneId.trim() : undefined;
+  if (id === undefined && rootId === undefined) return undefined;
+  return {
+    ...(id === undefined ? {} : { tabId: id }),
+    ...(rootId === undefined ? {} : { rootPaneId: rootId }),
+  };
+}
+
+/** One pane's rectangle out of a `pane layout` answer. */
+interface PaneRect {
+  paneId: string;
+  /** Top row inside the tab; ascending top to bottom. */
+  y: number;
+  height: number;
+}
+
+/**
+ * Every pane rect of the tab a `pane layout --pane` answer describes (#1110) —
+ * one call measures the whole tab. An answer carrying no usable rects is
+ * unreadable, never an excuse to mutate blind.
+ */
+function parsePaneLayout(stdout: string): { tabId?: string; panes: PaneRect[] } | undefined {
+  const result = envelopeOf(stdout);
+  const layout = result?.["layout"];
+  if (layout === null || typeof layout !== "object") return undefined;
+  const record = layout as Record<string, unknown>;
+  const raw = record["panes"];
+  if (!Array.isArray(raw)) return undefined;
+  const panes: PaneRect[] = [];
+  for (const entry of raw) {
+    if (entry === null || typeof entry !== "object") continue;
+    const pane = entry as Record<string, unknown>;
+    const rect = pane["rect"];
+    if (typeof pane["pane_id"] !== "string" || pane["pane_id"].trim() === "") continue;
+    if (rect === null || typeof rect !== "object") continue;
+    const height = (rect as Record<string, unknown>)["height"];
+    const y = (rect as Record<string, unknown>)["y"];
+    if (typeof height !== "number" || !Number.isFinite(height)) continue;
+    if (typeof y !== "number" || !Number.isFinite(y)) continue;
+    panes.push({ paneId: pane["pane_id"].trim(), height, y });
+  }
+  if (panes.length === 0) return undefined;
+  const tabId = record["tab_id"];
+  return {
+    ...(typeof tabId === "string" && tabId.trim() !== "" ? { tabId: tabId.trim() } : {}),
+    panes,
+  };
+}
+
 /** One conductor-marked worker workspace, as discovery returns it. */
 export interface WorkerWorkspace {
   workspaceId: string;
@@ -1557,6 +1631,64 @@ export function ensureWorkerWorkspace(
   return { kind: "ready", workspaceId: parsed.workspaceId, anchorPaneId: parsed.rootPaneId, created: true };
 }
 
+/**
+ * Name a pane for its run, report the run's identity onto it, start the
+ * read-only follower, and report the working state — the ceremony every fresh
+ * representation goes through, shared verbatim by {@link openWorkerPane} and
+ * the #1110 retile's identity transplant. Reasons come back exactly as the
+ * inline steps worded them, because callers surface them unchanged.
+ */
+function establishWorkerPane(
+  paneId: string,
+  identity: PaneCeremonyIdentity,
+  deps: WorkerPaneDeps & { session: string },
+): { ok: true; label: string } | { ok: false; reason: string } {
+  const run = deps.run ?? realHerdrRun;
+  const base = ["--session", deps.session, "pane"];
+  const label = workerPaneLabel(identity);
+
+  const named = run([...base, "rename", paneId, label]);
+  if (!named.ok) {
+    return { ok: false, reason: `herdr pane rename failed: ${firstLine(named.stderr) || "no output"}` };
+  }
+
+  // Identity before display: the pane must be attributable to this exact run
+  // before it shows anything, so a pane that appears is never a pane nobody can
+  // trace back to a worker.
+  const identified = run([
+    ...base,
+    "report-agent-session",
+    paneId,
+    "--source",
+    WORKER_PANE_SOURCE,
+    "--agent",
+    label,
+    "--agent-session-id",
+    identity.runId,
+    ...(identity.sessionFile === undefined ? [] : ["--agent-session-path", identity.sessionFile]),
+    "--session-start-source",
+    WORKER_PANE_SOURCE,
+  ]);
+  if (!identified.ok) {
+    return {
+      ok: false,
+      reason: `herdr pane report-agent-session failed: ${firstLine(identified.stderr) || "no output"}`,
+    };
+  }
+
+  const started = run([...base, "run", paneId, ...(deps.viewer?.(identity) ?? defaultViewer(identity))]);
+  if (!started.ok) {
+    return { ok: false, reason: `herdr pane run failed: ${firstLine(started.stderr) || "no output"}` };
+  }
+
+  // A worker that has just spawned is working by definition. The ongoing
+  // projection of turn/pause/blocked transitions is #842's, from the same typed
+  // events — never from the pane's output.
+  const reported = reportWorkerPaneState(paneId, label, "working", { run, session: deps.session });
+  if (!reported.ok) return { ok: false, reason: reported.reason };
+  return { ok: true, label };
+}
+
 /**
  * Create the pane, run the follower in it, and report the child's identity and
  * initial state — or say exactly why it could not.
@@ -1618,49 +1750,38 @@ export function openWorkerPane(identity: WorkerPaneIdentity, deps: WorkerPaneDep
     return abandon("herdr pane split reported no pane id");
   }
 
-  const named = run([...base, "rename", paneId, label]);
-  if (!named.ok) {
-    return abandon(`herdr pane rename failed: ${firstLine(named.stderr) || "no output"}`, undefined, paneId);
-  }
-
-  // Identity before display: the pane must be attributable to this exact run
-  // before it shows anything, so a pane that appears is never a pane nobody can
-  // trace back to a worker.
-  const identified = run([
-    ...base,
-    "report-agent-session",
-    paneId,
-    "--source",
-    WORKER_PANE_SOURCE,
-    "--agent",
-    label,
-    "--agent-session-id",
-    identity.runId,
-    ...(identity.sessionFile === undefined ? [] : ["--agent-session-path", identity.sessionFile]),
-    "--session-start-source",
-    WORKER_PANE_SOURCE,
-  ]);
-  if (!identified.ok) {
-    return abandon(
-      `herdr pane report-agent-session failed: ${firstLine(identified.stderr) || "no output"}`,
-      undefined,
-      paneId,
-    );
-  }
-
-  const started = run([...base, "run", paneId, ...deps.viewer?.(identity) ?? defaultViewer(identity)]);
-  if (!started.ok) {
-    return abandon(`herdr pane run failed: ${firstLine(started.stderr) || "no output"}`, undefined, paneId);
-  }
+  const established = establishWorkerPane(paneId, identity, { ...deps, session });
+  if (!established.ok) {
+    return abandon(established.reason, undefined, paneId);
+  }
+
+  // Layout hygiene runs last, so a refused retile can never fail the launch
+  // it follows (#1110). A workspace this call itself created holds one worker
+  // beside its bare skeleton — nothing to rebalance yet; the junk sweep takes
+  // the skeleton and later passes keep the tab even. When a rebuilt tab's
+  // skeleton carries this run's identity, the tracked outcome names the pane
+  // that now represents it.
+  const retiled: WorkerTabRebalance =
+    ensured.created === true
+      ? { ok: true, rebuilt: false }
+      : rebalanceWorkerTabs(ensured.workspaceId, {
+          run,
+          session,
+          ...(deps.viewer === undefined ? {} : { viewer: deps.viewer }),
+          reidentify: (candidate) => (candidate === paneId ? identity : undefined),
+        });
+  const displayed =
+    retiled.ok && retiled.transplanted !== undefined && retiled.transplanted.fromPaneId === paneId
+      ? retiled.transplanted.toPaneId
+      : paneId;
 
-  // A worker that has just spawned is working by definition. The ongoing
-  // projection of turn/pause/blocked transitions is #842's, from the same typed
-  // events — never from the pane's output.
-  const reported = reportWorkerPaneState(paneId, label, "working", { run, session });
-  if (!reported.ok) {
-    return abandon(reported.reason, undefined, paneId);
-  }
-  return { kind: "tracked", paneId, label, pid: identity.pid, workspaceId: ensured.workspaceId };
+  return {
+    kind: "tracked",
+    paneId: displayed,
+    label: established.label,
+    pid: identity.pid,
+    workspaceId: ensured.workspaceId,
+  };
 }
 
 /** Report one lifecycle state for a tracked pane. Monotonic `seq` is the caller's. */
@@ -1762,6 +1883,211 @@ export function retireWorkerPane(
   return closeWorkerPane(paneId, deps);
 }
 
+/**
+ * How far the tallest pane may sit above the shortest before a tab counts as
+ * crooked (#1110). Five workers attached by repeated fixed-ratio splits of one
+ * anchor come out geometrically smaller — roughly 30%, 21%, 15%, 10%, 7% of
+ * the workspace — so the fifth lands far past this line; a freshly tiled tab
+ * sits at about 1.0.
+ */
+export const PANE_HEIGHT_TOLERANCE = 1.5;
+
+/**
+ * Split ratios that leave `slots` equal rows behind when every newcomer is
+ * anchored on the same shrinking skeleton (#1110).
+ *
+ * Measured on a live Herdr: a split or move with `--ratio r` leaves the ANCHOR
+ * an r share of itself and hands the newcomer the rest. Taking
+ * `r_j = (slots - j) / (slots - j + 1)` for move j therefore hands each
+ * newcomer exactly one slot of the whole — the arithmetic that turns the fifth
+ * attach from a fourteenth of the height into a fifth.
+ */
+export function evenTileRatios(slots: number): readonly number[] {
+  if (!Number.isInteger(slots) || slots < 2) return [];
+  const ratios: number[] = [];
+  for (let j = 1; j <= slots - 1; j++) ratios.push((slots - j) / (slots - j + 1));
+  return ratios;
+}
+
+export type WorkerTabRebalance =
+  | {
+      ok: true;
+      /** True when at least one crooked tab was rebuilt by this call. */
+      rebuilt: boolean;
+      /** The representation that rode the rebuilt tab's skeleton, when the old
+       *  tab could only be disposed of by re-establishing one run's visual. */
+      transplanted?: { fromPaneId: string; toPaneId: string; identity: PaneCeremonyIdentity };
+    }
+    | { ok: false; reason: string };
+
+/**
+ * Retile every crooked tab of one worker workspace into equal rows (#1110).
+ * Repeated fixed-ratio splits of a single anchor make each new worker
+ * geometrically smaller than the last, and a settling pane hands its space to
+ * a split sibling instead of sharing it out — attaches and detaches both
+ * drift. `pane resize` was probed live and rejected: it moves borders through
+ * the split tree proportionally, so nudges cascade across neighbours, invert
+ * under sign, and wedge into states where they no-op forever. The honest
+ * rebuild moves the standing panes — ids, followers and scrollback surviving
+ * the move — into a fresh tab whose sequential anchor ratios land them even,
+ * re-establishes one run's representation on the skeleton root so no bare
+ * shell remains (a closed skeleton dumps its whole share into one split
+ * sibling, which was measured skewing a six-pane tab back to 11:6), and
+ * closes the emptied tab.
+ *
+ * Only callers that already own the workspace invoke this: reconciliation
+ * scopes it to token-marked or store-recorded surfaces (#1035), and
+ * {@link openWorkerPane} calls it for the workspace it just found or created
+ * through the same discovery. No pane is created, written to, or given input:
+ * a move re-parents the terminal whole, and the one follower that restarts
+ * (the transplanted run's) restarts the same read-only `omp-conductor tail`.
+ *
+ * Best effort by design. Any refusal stops the tab's rebuild where it stands
+ * and is reported; partial rebuilds converge because already-moved panes
+ * measure even in their new tab, so each retry moves strictly fewer panes.
+ * Callers treat a failure as next pass's identical request, never as a launch
+ * or settlement problem: a crooked layout never outweighs the representation
+ * it hosts.
+ */
+export function rebalanceWorkerTabs(
+  workspaceId: string,
+  deps: {
+    run?: HerdrRun;
+    session?: string;
+    viewer?: (identity: PaneCeremonyIdentity) => readonly string[];
+    /** Whose representation a pane carries, as far as the caller knows. A pane
+     *  nobody can identify is never chosen to ride the skeleton. */
+    reidentify?: (paneId: string) => PaneCeremonyIdentity | undefined;
+  } = {},
+): WorkerTabRebalance {
+  const run = deps.run ?? realHerdrRun;
+  const session = deps.session ?? resolveHerdrSession();
+  const base = ["--session", session];
+
+  const res = run([...base, "pane", "list", "--workspace", workspaceId]);
+  if (!res.ok) {
+    return { ok: false, reason: `herdr pane list failed: ${firstLine(res.stderr) || "no output"}` };
+  }
+  const parsed = parsePaneRecords(res.stdout);
+  if (parsed === undefined) return { ok: false, reason: "herdr pane list was unreadable" };
+
+  /** Tab id → member pane ids, in listing order. */
+  const tabs = new Map<string, string[]>();
+  for (const pane of parsed.panes) {
+    const members = tabs.get(pane.tabId ?? "");
+    if (members === undefined) tabs.set(pane.tabId ?? "", [pane.paneId]);
+    else members.push(pane.paneId);
+  }
+
+  let rebuilt = false;
+  for (const [tabId, paneIds] of tabs) {
+    // A tab Herdr did not name cannot be torn down safely after the rebuild,
+    // so measuring it is where its story ends.
+    if (tabId === "" || paneIds.length < 2) continue;
+    const measured = run([...base, "pane", "layout", "--pane", paneIds[0]!]);
+    if (!measured.ok) {
+      return { ok: false, reason: `herdr pane layout failed: ${firstLine(measured.stderr) || "no output"}` };
+    }
+    const layout = parsePaneLayout(measured.stdout);
+    if (layout === undefined) return { ok: false, reason: "herdr pane layout was unreadable" };
+    const rectOf = new Map(layout.panes.map((rect) => [rect.paneId, rect]));
+    const rects = paneIds.map((id) => rectOf.get(id)).filter((rect): rect is PaneRect => rect !== undefined);
+    // A listed pane the layout does not describe is a tab changing under us:
+    // mutate nothing on half evidence.
+    if (rects.length !== paneIds.length) continue;
+    const heights = rects.map((rect) => rect.height);
+    const shortest = Math.min(...heights);
+    const tallest = Math.max(...heights);
+    // A zero-height pane is crooked beside anything alive; the tolerance is
+    // inclusive at exactly 1.5×, since the criterion reads "no more than".
+    // Below three average cells a pane is illegible whatever the ratio —
+    // tiling cannot help a terminal that small.
+    if (tallest <= shortest * PANE_HEIGHT_TOLERANCE) continue;
+    if (heights.reduce((sum, h) => sum + h, 0) / heights.length < 3) continue;
+
+    // The rider is the topmost pane the caller can identify; it re-founds its
+    // representation on the skeleton, which lands as the tab's top row, so the
+    // operator's reading order survives. The rest move bottom-to-top,
+    // reversing into their original order underneath it.
+    const ascending = [...rects].sort((a, b) => a.y - b.y);
+    const rider = ascending.find((rect) => deps.reidentify?.(rect.paneId) !== undefined);
+    if (rider === undefined) continue;
+    const identity = deps.reidentify!(rider.paneId)!;
+    const movers = ascending.filter((rect) => rect.paneId !== rider.paneId).reverse();
+
+    const made = run([...base, "tab", "create", "--workspace", workspaceId, "--no-focus"]);
+    if (!made.ok) {
+      return { ok: false, reason: `herdr tab create failed: ${firstLine(made.stderr) || "no output"}` };
+    }
+    const created = parseCreatedTab(made.stdout);
+    if (created?.tabId === undefined || created.rootPaneId === undefined) {
+      // Half an answer: the tab may exist and must not linger as an empty
+      // shell this attempt cannot account for.
+      if (created?.tabId !== undefined) run([...base, "tab", "close", created.tabId]);
+      return { ok: false, reason: "herdr tab create reported no root pane" };
+    }
+
+    const slots = movers.length + 1;
+    const ratios = evenTileRatios(slots);
+    let placed = 0;
+    for (; placed < movers.length; placed++) {
+      const moved = run([
+        ...base,
+        "pane",
+        "move",
+        movers[placed]!.paneId,
+        "--tab",
+        created.tabId,
+        "--split",
+        "down",
+        "--target-pane",
+        created.rootPaneId,
+        "--ratio",
+        String(ratios[placed]),
+      ]);
+      if (!moved.ok) {
+        return { ok: false, reason: `herdr pane move failed: ${firstLine(moved.stderr) || "no output"}` };
+      }
+    }
+
+    // The skeleton kept the top slot only by inheriting the rider's identity:
+    // the same name, the same session report, the same read-only tail. A bare
+    // shell up there would be junk, and junk closure is exactly what skews.
+    const founded = establishWorkerPane(created.rootPaneId, identity, {
+      run,
+      session,
+      ...(deps.viewer === undefined ? {} : { viewer: deps.viewer }),
+    });
+    if (!founded.ok) {
+      return { ok: false, reason: founded.reason };
+    }
+    const retiredRider = run([...base, "pane", "close", rider.paneId]);
+    if (!retiredRider.ok) {
+      return { ok: false, reason: `herdr pane close failed: ${firstLine(retiredRider.stderr) || "no output"}` };
+    }
+    // Herdr tears an emptied tab down by itself (probed live), so a refusal
+    // here is only fatal when panes still stand in the old tab — verified,
+    // never assumed.
+    const closed = run([...base, "tab", "close", tabId]);
+    if (!closed.ok) {
+      const verify = run([...base, "pane", "list", "--workspace", workspaceId]);
+      const leftover = verify.ok
+        ? (parsePaneRecords(verify.stdout)?.panes ?? []).filter((pane) => pane.tabId === tabId)
+        : null;
+      if (leftover === null || leftover.length > 0) {
+        return { ok: false, reason: `herdr tab close failed: ${firstLine(closed.stderr) || "no output"}` };
+      }
+    }
+    rebuilt = true;
+    return {
+      ok: true,
+      rebuilt: true,
+      transplanted: { fromPaneId: rider.paneId, toPaneId: created.rootPaneId, identity },
+    };
+  }
+  return { ok: true, rebuilt };
+}
+
 /**
  * Hand back the representation a dead worker left behind (#842), retired for
  * good by closing it (#1035) — but only once the recorded pane is PROVEN still
@@ -2281,6 +2607,37 @@ export function reconcileWorkerPanes(
     });
   }
 
+  // Attach and detach both leave geometry behind: repeated fixed-ratio splits
+  // shrink every new pane geometrically (#1110), and a settle hands its space
+  // to a split sibling instead of sharing it out. Every scoped workspace that
+  // still holds two or more panes gets measured now; a tab past the tolerance
+  // is rebuilt evenly — same panes, same ids, followers untouched. The one
+  // representation riding the skeleton keeps its reported identity, so the
+  // next pass attributes it through the session id exactly as #1035 already
+  // requires; this pass deliberately says nothing about layout, because a
+  // crooked tile is cosmetics and an outcome row would claim otherwise.
+  for (const entry of entries) {
+    let standingInWorkspace = 0;
+    for (const wsId of standingWs.values()) if (wsId === entry.ws.workspaceId) standingInWorkspace += 1;
+    if (standingInWorkspace < 2) continue;
+    rebalanceWorkerTabs(entry.ws.workspaceId, {
+      run,
+      session,
+      ...(deps.viewer === undefined ? {} : { viewer: deps.viewer }),
+      reidentify: (paneId) => {
+        const worker = live.find((candidate) => candidate.paneId === paneId);
+        if (worker === undefined) return undefined;
+        return {
+          project: worker.project,
+          issue: worker.issue,
+          attempt: worker.attempt,
+          runId: worker.runId,
+          ...(worker.sessionFile === undefined ? {} : { sessionFile: worker.sessionFile }),
+        };
+      },
+    });
+  }
+
   // Every scoped marked workspace whose panes the cleanup above emptied, and
   // that gained no representation this pass, is closed — however many marked
   // surfaces a project accumulated (#1035 review). A live project's primary

package/src/knowledge.ts

@@ -19,6 +19,10 @@
  * accumulated knowledge is worse than one fewer fact, because a worker cannot
  * tell a clipped warning from a complete one.
  *
+ * What the cap never drops is structure: an operator distillation's headings,
+ * paragraphs and blank separators survive every append verbatim and in place —
+ * the facts rotate, the shape of the knowledge stays.
+ *
  * Writes are best-effort. This is an optimisation, and a run must never fail
  * because the overlay could not be written: the callers are settlement paths.
  */
@@ -74,31 +78,69 @@ function encodeRepoKey(repo: string): string {
 }
 
 /**
- * The overlay's entry lines, oldest first, with blank lines and any hand-added
- * prose dropped.
+ * One line of the overlay document. An `entry` is a fleet-learned fact — the
+ * `- `-prefixed line the writer produces and attributes; anything else, a
+ * heading, a paragraph or a blank separator, is `structure`: hand-added
+ * scaffolding from an operator distillation. The distinction is the format:
+ * entries are appendable, deduplicated and evictable, structure is none of
+ * those things, and it survives every write verbatim and in place.
+ */
+type OverlayBlock = { kind: "entry" | "structure"; line: string };
+
+/**
+ * The overlay document parsed into blocks, in file order. Lossless: joining
+ * the lines back with "\n" reproduces the input, which is what makes keeping
+ * the structure through a write a property of the parse rather than a hope.
  *
  * One parse, shared by the writer and the brief renderer on purpose: they must
  * agree on what counts as an entry, or the cap one enforces is not the cap the
  * other renders and a "16 KB" section arrives at 20.
  */
-function entriesOf(text: string): string[] {
-  return text
-    .split("\n")
-    .map((line) => line.trimEnd())
-    .filter((line) => line.startsWith(ENTRY_PREFIX) && line.slice(ENTRY_PREFIX.length).trim() !== "");
+function blocksOf(text: string): OverlayBlock[] {
+  if (text === "") return [];
+  const lines = text.split("\n");
+  // The final newline is the file's terminator, not a blank last line: pop it
+  // here so appended entries join the document itself, and let renderDoc put
+  // exactly one back.
+  if (lines.at(-1) === "") lines.pop();
+  return lines.map((raw) => {
+    const line = raw.trimEnd();
+    return line.startsWith(ENTRY_PREFIX) && line.slice(ENTRY_PREFIX.length).trim() !== ""
+      ? { kind: "entry", line }
+      : { kind: "structure", line: raw };
+  });
+}
+
+/**
+ * The document text for a block list: a blank run at the EOF seam is
+ * whitespace, not content, so it is trimmed and exactly one newline terminates
+ * the document — the shape every writer of this format has always produced.
+ * Interior blanks pass through untouched.
+ */
+function renderDoc(blocks: readonly OverlayBlock[]): string {
+  const kept = [...blocks];
+  while (kept.at(-1)?.kind === "structure" && kept.at(-1)?.line.trim() === "") kept.pop();
+  return `${kept.map((b) => b.line).join("\n")}\n`;
 }
 
 /**
- * The newest entries that fit under {@link KNOWLEDGE_MAX_BYTES}, oldest dropped
- * first and only ever whole.
+ * The newest content that fits under {@link KNOWLEDGE_MAX_BYTES}, oldest
+ * entries dropped first and only ever whole.
+ *
+ * Only entries evict. A distilled file keeps its headings and paragraphs even
+ * when the facts beneath them have been rotated out, and when only non-entry
+ * text remains the document simply stays over the ceiling: operator prose is
+ * not ours to delete, and distilling it back under the cap is the remedy the
+ * format itself names.
  *
  * Byte lengths, not character counts: the cap is a context-budget promise, and
  * one accented identifier or box-drawing character is several bytes.
  */
-function withinCap(entries: readonly string[]): string[] {
-  const kept = [...entries];
-  while (kept.length > 0 && Buffer.byteLength(`${kept.join("\n")}\n`, "utf8") > KNOWLEDGE_MAX_BYTES) {
-    kept.shift();
+function withinCap(blocks: readonly OverlayBlock[]): OverlayBlock[] {
+  const kept = [...blocks];
+  const bytes = (): number => Buffer.byteLength(renderDoc(kept), "utf8");
+  while (kept.some((b) => b.kind === "entry") && bytes() > KNOWLEDGE_MAX_BYTES) {
+    kept.splice(kept.findIndex((b) => b.kind === "entry"), 1);
   }
   return kept;
 }
@@ -139,6 +181,10 @@ export function readKnowledge(repo: string): string | undefined {
  * `proofCommands` for every issue in a repo — cannot inflate the file until the
  * cap evicts something real.
  *
+ * The rewrite preserves every non-entry line the file carries — the headings,
+ * paragraphs and blank separators of an operator distillation — exactly where
+ * they were: entries rotate under the cap, structure does not.
+ *
  * Best-effort by contract: the callers are settlement paths, and a failed write
  * here must never turn a finished run into a failed one.
  */
@@ -157,25 +203,33 @@ export function appendKnowledge(
   if (rendered.length === 0) return;
   const path = knowledgePath(repo);
   try {
-    const existing = entriesOf(readKnowledge(repo) ?? "");
-    // Dynamic membership over the file's own lines, grown as this batch is
+    const existing = blocksOf(readKnowledge(repo) ?? "");
+    // Dynamic membership over the file's own entries, grown as this batch is
     // folded in, so one call cannot append the same fact twice either.
-    const seen = new Set(existing);
-    const added: string[] = [];
+    const seen = new Set(existing.filter((b) => b.kind === "entry").map((b) => b.line));
+    const added: OverlayBlock[] = [];
     for (const line of rendered) {
       if (seen.has(line)) continue;
       seen.add(line);
-      added.push(line);
+      added.push({ kind: "entry", line });
     }
     if (added.length === 0) return;
-    const kept = withinCap([...existing, ...added]);
+    // A batch appended under a distilled paragraph or heading takes one blank
+    // separator, so it never glues onto the prose above it; after an entry or
+    // a blank none is needed.
+    const tail = existing.at(-1);
+    const gap: OverlayBlock[] =
+      tail !== undefined && tail.kind === "structure" && tail.line.trim() !== ""
+        ? [{ kind: "structure", line: "" }]
+        : [];
+    const kept = withinCap([...existing, ...gap, ...added]);
     mkdirSync(dirname(path), { recursive: true });
     // Atomic like every other durable conductor state file: a brief renderer
     // reading while a settlement writes sees the old file or the new one, never
     // a half-written entry.
     const tmp = `${path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`;
     try {
-      writeFileSync(tmp, `${kept.join("\n")}\n`, "utf8");
+      writeFileSync(tmp, renderDoc(kept), "utf8");
       renameSync(tmp, path);
     } catch (err) {
       rmSync(tmp, { force: true });
@@ -209,7 +263,7 @@ export function appendKnowledge(
 export function knowledgeSection(repo: string): string {
   const text = readKnowledge(repo);
   if (text === undefined) return "";
-  const entries = withinCap(entriesOf(text));
+  const entries = withinCap(blocksOf(text)).filter((b) => b.kind === "entry").map((b) => b.line);
   if (entries.length === 0) return "";
   return [
     KNOWLEDGE_HEADING,