@zerwiz/ymir 0.1.16 → 0.1.18

package/.pi/extensions/lib/ro-working-ship.ts

@@ -0,0 +1,243 @@
+// Brokk's Ró-only animated working presentation.
+//
+// Ró replaces Pi's stock working row with a tiny SSHHIP-derived boat while one
+// logical agent run is active. This module owns only the sprite geometry, the bounce
+// track, the two animation cadences, the session-scoped freeze/resume state, and the
+// temporary TUI widget; `.pi/extensions/ro.ts` owns when the presentation is
+// installed and removed, and stays the sole caller of setWorkingVisible().
+// docs/ro.md owns the Allfather-facing contract.
+//
+// Cadence: one scheduler drives two logically independent clocks. Every tick advances
+// the water phase, and only every CALM_WORKING_SHIP_TICKS_PER_MOVE-th tick moves the
+// boat, so the water visibly ripples several times between boat steps and the boat
+// itself reads as ro. Both clocks stop together when the widget is disposed. Ticks,
+// not wall-clock timestamps, drive every state change, so tests can seek time exactly.
+//
+// Continuity: one extension-owned animation instance survives hide/show within the same
+// Pi process and Ró extension lifetime. Disposing the widget freezes column,
+// direction, water phase, and tick cadence without advancing them for hidden wall
+// time. The next working period resumes from that exact logical state. A fresh session
+// or new extension lifetime calls reset() and starts at the normal initial position.
+// State is never a module-level or process-global singleton.
+//
+// Verified against Pi 0.81.1 declarations and the Pi 0.82.0 CLI, which expose
+// ExtensionUIContext.setWidget() with a component smidja, per-widget dispose(), and
+// TUI.requestRender(). Pi renders a widget through Component.render(width), so this
+// module recomputes its track from that width on every frame instead of caching a
+// terminal size that a resize would invalidate. A resize while the boat is hidden is
+// applied on the first resumed frame through the same clamp path.
+import type { Component, TUI } from "@earendil-works/pi-tui";
+
+// The hull is symmetric and replaces waves on its row rather than adding a third row.
+const HULL = "\\__/";
+// A mainsail extends aft of the mast, so it trails behind the bow relative to travel.
+const SAIL_RIGHT = "<|";
+const SAIL_LEFT = "|>";
+// Centers the two-cell sail over the four-cell hull.
+const SAIL_OFFSET = 1;
+const HULL_WIDTH = HULL.length;
+const SAIL_WIDTH = SAIL_RIGHT.length;
+
+// Bounded deterministic fixed-cell water phases. Every entry is exactly one column, so
+// advancing the phase ripples the surface without changing visible width or row count.
+const WAVE_CYCLE = ["~", "~", "-", "~"] as const;
+
+// Standard ANSI foreground codes only: no theme lookup, bright variant, or 256/RGB.
+const BLUE = "\u001b[34m";
+const YELLOW = "\u001b[33m";
+// Restores the default foreground so color never bleeds into padding or later frames.
+const RESET = "\u001b[39m";
+
+export const RO_WORKING_SHIP_WIDGET_KEY = "brokk-ro-working-ship";
+/** Scheduler period. One tick advances the water by one phase. */
+export const CALM_WORKING_SHIP_TICK_MS = 220;
+/** Boat moves one column every Nth tick, so it travels at 220 * 4 = 880ms per column. */
+export const CALM_WORKING_SHIP_TICKS_PER_MOVE = 4;
+
+export type CalmWorkingShipAnimation = {
+  /** Render one frame that exactly fits `width`, clamping the track to it first. */
+  render(width: number): string[];
+  /** Advance one scheduler tick: water every tick, boat on its slower cadence. */
+  tick(): void;
+  restoreLastRendered(): void;
+  /** Restore the normal initial column, direction, water phase, and cadence. */
+  reset(): void;
+  /**
+   * Clamp the frozen column and direction to `width` without advancing time.
+   * Used when a terminal resize lands while the working presentation is hidden.
+   */
+  clampToWidth(width: number): void;
+  /** Current hull column, exposed for deterministic motion assertions. */
+  position(): number;
+  /** Current travel direction: 1 travelling right, -1 travelling left. */
+  direction(): number;
+  /** Current water phase, exposed for deterministic ripple assertions. */
+  waterPhase(): number;
+};
+
+/** Longest hull start column that still fits the sprite in `width` usable cells. */
+function trackSpan(width: number): number {
+  if (width >= HULL_WIDTH) return width - HULL_WIDTH;
+  if (width >= SAIL_WIDTH) return width - SAIL_WIDTH;
+  return 0;
+}
+
+export function createCalmWorkingShipAnimation(): CalmWorkingShipAnimation {
+  let position = 0;
+  let direction = 1;
+  let span = 0;
+  let phase = 0;
+  let ticks = 0;
+  let renderedPosition = position;
+  let renderedDirection = direction;
+  let renderedSpan = span;
+  let renderedPhase = phase;
+  let renderedTicks = ticks;
+
+  // Reversing the moment the boat lands on an endpoint means the endpoint frame itself
+  // already shows the new heading, so no frame at or after a bounce shows the old sail.
+  const settleDirectionAtEdges = (): void => {
+    if (span <= 0) return;
+    if (position >= span) direction = -1;
+    else if (position <= 0) direction = 1;
+  };
+
+  const applyWidth = (width: number): void => {
+    if (width <= 0) {
+      span = 0;
+      position = 0;
+      return;
+    }
+    span = trackSpan(width);
+    position = Math.min(position, span);
+    settleDirectionAtEdges();
+  };
+
+  const commitRenderedState = (): void => {
+    renderedPosition = position;
+    renderedDirection = direction;
+    renderedSpan = span;
+    renderedPhase = phase;
+    renderedTicks = ticks;
+  };
+
+  const restoreLastRenderedState = (): void => {
+    position = renderedPosition;
+    direction = renderedDirection;
+    span = renderedSpan;
+    phase = renderedPhase;
+    ticks = renderedTicks;
+  };
+
+  /** One colored run of water covering absolute columns [from, from + count). */
+  const water = (from: number, count: number): string => {
+    if (count <= 0) return "";
+    let cells = "";
+    for (let column = from; column < from + count; column += 1) {
+      cells += WAVE_CYCLE[(column + phase) % WAVE_CYCLE.length];
+    }
+    return `${BLUE}${cells}${RESET}`;
+  };
+
+  const boat = (text: string): string => `${YELLOW}${text}${RESET}`;
+
+  return {
+    position: () => position,
+    direction: () => direction,
+    waterPhase: () => phase,
+
+    restoreLastRendered: restoreLastRenderedState,
+
+    reset(): void {
+      position = 0;
+      direction = 1;
+      span = 0;
+      phase = 0;
+      ticks = 0;
+      commitRenderedState();
+    },
+
+    clampToWidth(width: number): void {
+      applyWidth(width);
+    },
+
+    tick(): void {
+      ticks += 1;
+      phase = (phase + 1) % WAVE_CYCLE.length;
+      if (ticks % CALM_WORKING_SHIP_TICKS_PER_MOVE !== 0) return;
+      if (span <= 0) {
+        position = 0;
+        return;
+      }
+      position = Math.min(span, Math.max(0, position + direction));
+      settleDirectionAtEdges();
+    },
+
+    render(width: number): string[] {
+      if (width <= 0) return [];
+
+      // A resize lands here before the next frame, so recompute and clamp the track
+      // immediately rather than trusting a position measured against the old width.
+      applyWidth(width);
+
+      const sail = direction >= 0 ? SAIL_RIGHT : SAIL_LEFT;
+
+      let frame: string[];
+      if (width < SAIL_WIDTH) {
+        // Too narrow for even the sail: a deterministic single row of water.
+        frame = [water(0, width)];
+      } else if (width < HULL_WIDTH) {
+        // Too narrow for the hull: the sail alone rides the water row.
+        frame = [
+          water(0, position) +
+            boat(sail) +
+            water(position + SAIL_WIDTH, width - position - SAIL_WIDTH),
+        ];
+      } else {
+        frame = [
+          " ".repeat(position + SAIL_OFFSET) + boat(sail),
+          water(0, position) +
+            boat(HULL) +
+            water(position + HULL_WIDTH, width - position - HULL_WIDTH),
+        ];
+      }
+
+      commitRenderedState();
+      return frame;
+    },
+  };
+}
+
+/**
+ * Build the temporary Ró working widget bound to one caller-owned animation.
+ * Pi disposes the previous component before installing a replacement under the same
+ * key and when it clears extension widgets, so the single scheduler driving both
+ * cadences cannot outlive the widget or duplicate. Disposing freezes the shared
+ * animation in place; the next widget bound to the same animation resumes without
+ * applying hidden wall time.
+ */
+export function createCalmWorkingShipWidget(
+  tui: TUI,
+  animation: CalmWorkingShipAnimation = createCalmWorkingShipAnimation(),
+): Component & { dispose(): void } {
+  let disposed = false;
+  const timer = setInterval(() => {
+    if (disposed) return;
+    animation.tick();
+    tui.requestRender();
+  }, CALM_WORKING_SHIP_TICK_MS);
+  // The animation must never keep Pi's process alive on its own.
+  timer.unref?.();
+
+  return {
+    render: (width) => (disposed ? [] : animation.render(width)),
+    // Every frame is rebuilt from fixed standard ANSI codes, so there is no cache.
+    invalidate: () => {},
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      clearInterval(timer);
+      animation.restoreLastRendered();
+    },
+  };
+}

package/.pi/extensions/lib/rodd-operational-input.ts

@@ -0,0 +1,62 @@
+// Rödd operational-input bridge.
+//
+// Rödd ("voice") is the structured message wire between the Brokk primary and
+// Ymir's workers. This is the TypeScript half of the protocol; the shell CLI
+// (bin/rodd-operational-input.sh) is the single owner of construction/parsing.
+// Ported from the upstream agent-distro reference.
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const operationalInputScript =
+  process.env.RODD_OPERATIONAL_INPUT_SCRIPT ||
+  resolve(dirname(fileURLToPath(import.meta.url)), "../../../bin/rodd-operational-input.sh");
+
+export const RODD_CURRENT_OPERATIONAL_KINDS = [
+  "session-start",
+  "watcher",
+  "turn-end-guard",
+  "away-supervisor",
+  "from-brokk",
+  "launch-brief",
+  "branch-outcome",
+] as const;
+
+export type RoddCurrentOperationalKind =
+  (typeof RODD_CURRENT_OPERATIONAL_KINDS)[number];
+
+function runOperationalInputCommand(
+  command: "encode" | "classify" | "kind",
+  content: string,
+  kind?: RoddCurrentOperationalKind,
+): string | undefined {
+  const args = command === "encode" ? [command, kind ?? ""] : [command];
+  const result = spawnSync(operationalInputScript, args, {
+    encoding: "utf8",
+    input: content,
+    maxBuffer: 1024 * 1024,
+  });
+  if (result.status !== 0) return undefined;
+  return command === "classify" ? result.stdout.replace(/\n$/, "") : result.stdout;
+}
+
+export function encodeRoddOperationalInput(
+  kind: RoddCurrentOperationalKind,
+  content: string,
+): string {
+  const encoded = runOperationalInputCommand("encode", content, kind);
+  if (encoded === undefined) {
+    throw new Error(`could not encode Rödd operational input kind ${kind}`);
+  }
+  return encoded;
+}
+
+export function classifyRoddOperationalText(content: string): string | undefined {
+  return runOperationalInputCommand("classify", content);
+}
+
+export function classifyRoddCurrentOperationalText(
+  content: string,
+): string | undefined {
+  return runOperationalInputCommand("kind", content);
+}

package/.pi/extensions/lib/skuld-branch-dispatch.ts

@@ -0,0 +1,252 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+
+// Shared wake-dispatch handshake between the Pi watcher extension (the
+// dispatcher) and the supervision-branch extension (the handler), carried over
+// pi.events so neither extension imports the other.
+//
+// Contract: the watcher builds one offer per actionable wake and emits it on
+// SKULD_BRANCH_DISPATCH_EVENT. A live, enabled branch extension calls accept()
+// SYNCHRONOUSLY inside its handler (the event bus invokes handlers
+// synchronously up to their first await), so after emit returns the watcher
+// reads `accepted`: true means the branch now owns delivering and handling the
+// wake (including its own fallback back to main on a later failure); false
+// means no branch took it and the watcher delivers to main exactly as it did
+// before the branch existed. Watcher-failure alarms are never offered - only
+// main can repair the watcher cycle (brokk_watch_arm_pi lives on main).
+
+export const SKULD_BRANCH_DISPATCH_EVENT = "skuld-branch-supervision:dispatch";
+
+export type UnreadWakeScopeStatus = "safe" | "empty" | "unsafe";
+
+export interface UnreadWakeScope {
+  status: UnreadWakeScopeStatus;
+  eligible: boolean;
+  /** Exact project values touched by the currently eligible rows (context only). */
+  projects: string[];
+  /**
+   * The exact durable-queue sequence numbers this scan proved safe for the
+   * branch to drain and acknowledge right now (docs/watcher-continuity.md
+   * "Per-actor acknowledgement" - the single owner of the consume contract
+   * bin/saga-wake-drain.sh implements against this list). Empty whenever
+   * `eligible` is false.
+   */
+  eligibleSeqs: string[];
+  /**
+   * True only when this scan itself is untrustworthy: the queue or its
+   * metadata could not be read, a line fails the structural tab-field check,
+   * or an unresolvable signal/stale row was found. False whenever the scan
+   * completed cleanly and simply found nothing (or nothing further) eligible
+   * for the branch right now: status "unsafe" with corrupted false is the
+   * ordinary "ordinary main-only content, nothing here for the branch" case,
+   * not a fault, and callers should treat it as ordinary absence rather than
+   * escalating. A main-owned check row is never a source of corruption in
+   * either mode.
+   */
+  corrupted: boolean;
+}
+
+const EMPTY_SCOPE: UnreadWakeScope = { status: "empty", eligible: false, projects: [], eligibleSeqs: [], corrupted: false };
+const UNSAFE_SCOPE: UnreadWakeScope = { status: "unsafe", eligible: false, projects: [], eligibleSeqs: [], corrupted: true };
+
+// scopeForSkuldWake is the single owner of branch-eligibility classification
+// (docs/pi-supervision-branch.md "Autonomy"; docs/watcher-continuity.md
+// "Per-actor acknowledgement"). bin/saga-wake-drain.sh never reclassifies a row
+// itself - it only consumes the exact sequence-number snapshot this function
+// (via writeEligibleRowsSnapshot) hands it.
+//
+// A check-kind row - merge-confirmation polls, Relay mentions, credential/auth
+// failures, and every other legitimately main-only class - never vetoes a scan
+// in either mode. It is simply excluded from eligibleSeqs and left queued for
+// main, which is woken for it on that check's own watcher cycle
+// (brokk-primary-pi-watch.ts forces every check-kind TRIGGER to main), so nothing
+// starves by being left behind.
+//
+// That applies to a heartbeat review too, and it is the whole point: a
+// heartbeat used to be deferred to main merely because some unrelated check
+// row happened to be sitting unread, which put a routine fleet review in the
+// Allfather's chat for a reason that had nothing to do with the fleet. A
+// permanently main-owned row is not fleet context the branch is missing, so it
+// no longer rides the heartbeat into main (docs/pi-supervision-branch.md
+// "Heartbeat routing").
+//
+// The heartbeat's all-or-nothing contract is unchanged in what it actually
+// guarantees: a heartbeat review takes EVERY branch-ownable unread row or none
+// of them. An unresolvable signal/stale row (unmapped project) still vetoes the
+// whole scan in both modes, because that is a data/metadata problem this
+// function cannot safely reason past, not an ordinary main-only event. A row
+// this repo's brokk_wake_append could never have produced (an unknown kind, or a
+// line that fails the structural tab-field check) also still vetoes the whole
+// scan - that is queue corruption, not an everyday mixed queue.
+export function scopeForSkuldWake(state: string, heartbeat: boolean): UnreadWakeScope {
+  let queue = "";
+  try {
+    queue = readFileSync(`${state}/.wake-queue`, "utf8");
+  } catch {
+    return UNSAFE_SCOPE;
+  }
+
+  const rows = queue.split(/\r?\n/).filter((line) => line.length > 0);
+  if (rows.length === 0) return EMPTY_SCOPE;
+
+  const projects = new Set<string>();
+  const metadata = new Map<string, string>();
+  try {
+    for (const name of readdirSync(state)) {
+      if (!name.endsWith(".meta")) continue;
+      const task = name.slice(0, -5);
+      const fields = readFileSync(`${state}/${name}`, "utf8").split(/\r?\n/);
+      const project = fields.find((line) => line.startsWith("project="))?.slice(8) ?? "";
+      const window = fields.find((line) => line.startsWith("window="))?.slice(7) ?? "";
+      if (project) {
+        metadata.set(task, project);
+        if (window) metadata.set(window, project);
+      }
+    }
+  } catch {
+    return UNSAFE_SCOPE;
+  }
+
+  const eligibleSeqs: string[] = [];
+  for (const line of rows) {
+    const fields = line.split("\t");
+    if (fields.length < 5 || !/^[0-9]+$/.test(fields[1])) return UNSAFE_SCOPE;
+    const seq = fields[1];
+    const kind = fields[2];
+    const key = fields[3];
+    if (kind === "heartbeat") {
+      if (heartbeat) eligibleSeqs.push(seq);
+      continue;
+    }
+    if (kind === "check") {
+      // Always main-owned, in every mode: excluded from what the branch may
+      // claim, never a reason to reject the rest of the queue and never a
+      // reason to send an otherwise-eligible heartbeat review to main.
+      continue;
+    }
+    let project = "";
+    if (kind === "signal") {
+      const task = key.replace(/\.(?:status|turn-ended)$/, "");
+      project = metadata.get(task) ?? "";
+    } else if (kind === "stale") {
+      project = metadata.get(key) ?? metadata.get(key.replace(/^brokk-/, "")) ?? "";
+    } else {
+      // A kind brokk_wake_append never emits: structural corruption, not an
+      // ordinary main-only row.
+      return UNSAFE_SCOPE;
+    }
+    if (!project) return UNSAFE_SCOPE;
+    projects.add(project);
+    eligibleSeqs.push(seq);
+  }
+  const eligible = eligibleSeqs.length > 0;
+  // Reached only after every row passed classification without a veto. A scan
+  // that ends up ineligible simply found nothing the branch may claim - a
+  // queue of purely main-only content, not a fault. (Before check rows stopped
+  // vetoing a heartbeat, this point was unreachable for a heartbeat with an
+  // empty eligible set, so reading eligibility off the claim set rather than
+  // off the heartbeat flag changes no pre-existing outcome and keeps a
+  // heartbeat from being offered with nothing to hand over.)
+  return { status: eligible ? "safe" : "unsafe", eligible, projects: [...projects], eligibleSeqs, corrupted: false };
+}
+
+// The exact state-relative filename bin/saga-wake-drain.sh reads for a
+// SKULD_ACTOR=branch drain or ack (its header is the single owner of
+// the consume-side contract). Written atomically, immediately before every
+// branch prompt, by writeEligibleRowsSnapshot below.
+export const BRANCH_ELIGIBLE_ROWS_FILE = ".branch-eligible-rows";
+
+// Atomically publish the exact row set a branch turn may drain and
+// acknowledge. One sequence number per line - an opaque handoff, never
+// reclassified by the consumer. A main-owned result means the competing main
+// turn won the queue-lock claim and already owns presentation; error means no
+// actor acquired the requested rows.
+export type EligibleRowsSnapshotResult = "published" | "main-owned" | "error";
+
+function runGrantScript(state: string, grantScript: string, args: readonly string[]): number | null {
+  try {
+    const result = spawnSync("bash", [grantScript, ...args], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        BROKK_STATE_OVERRIDE: state,
+        BROKK_WAKE_QUEUE: `${state}/.wake-queue`,
+        BROKK_WAKE_QUEUE_LOCK: `${state}/.wake-queue.lock`,
+      },
+    });
+    return result.status;
+  } catch {
+    return null;
+  }
+}
+
+export function activateEligibleRowsOwner(
+  state: string,
+  grantScript: string,
+  ownerPid: number,
+  generation: string,
+): boolean {
+  return runGrantScript(state, grantScript, ["activate", String(ownerPid), generation]) === 0;
+}
+
+export function writeEligibleRowsSnapshot(
+  state: string,
+  seqs: readonly string[],
+  grantScript: string,
+  generation: string,
+): EligibleRowsSnapshotResult {
+  if (seqs.length === 0 || seqs.some((seq) => !/^[0-9]+$/.test(seq))) return "error";
+  const status = runGrantScript(state, grantScript, ["publish", generation, ...seqs]);
+  if (status === 0) return "published";
+  if (status === 3) return "main-owned";
+  return "error";
+}
+
+export function releaseEligibleRowsSnapshot(state: string, grantScript: string, generation: string): boolean {
+  return runGrantScript(state, grantScript, ["release", generation]) === 0;
+}
+
+export function deactivateEligibleRowsOwner(
+  state: string,
+  grantScript: string,
+  ownerPid: number,
+  generation: string,
+): boolean {
+  return runGrantScript(state, grantScript, ["deactivate", String(ownerPid), generation]) === 0;
+}
+
+export interface SkuldDispatchOffer {
+  /** The watcher's actionable close message (the wake reason line(s)). */
+  message: string;
+  /**
+   * Exact project values from the unread task metadata this wake will drain.
+   * Empty means the wake is fleet-wide or could not be scoped safely.
+   */
+  projects: readonly string[];
+  /** True when the watcher classified this wake as a fleet-wide heartbeat scan. */
+  heartbeat: boolean;
+  /** True only when at least one currently unread row is safe for branch handling. */
+  eligible: boolean;
+  /** Set by accept(); read by the watcher after emit returns. */
+  accepted: boolean;
+  accept(): void;
+}
+
+export function createSkuldDispatchOffer(
+  message: string,
+  projects: readonly string[] = [],
+  heartbeat = false,
+  eligible = false,
+): SkuldDispatchOffer {
+  const offer: SkuldDispatchOffer = {
+    message,
+    projects: [...projects],
+    heartbeat,
+    eligible,
+    accepted: false,
+    accept() {
+      offer.accepted = true;
+    },
+  };
+  return offer;
+}

package/.pi/extensions/lib/skuld-branch-model-picker.ts

@@ -0,0 +1,77 @@
+// Ordering and filtering for /skuld-model's bounded, searchable model
+// picker. docs/configuration.md owns its operator-facing behavior.
+//
+// This file holds only the choices Brokk owns - which entries exist, in
+// which order, and which survive a search query - so they stay testable
+// without a terminal. The picker's rendering, scrolling, key handling, and
+// branch-only component-choice rationale live beside pickBranchModel in
+// skuld-branch-supervision.ts.
+
+/** One row of the supervision-branch picker. */
+export interface BranchPickerItem {
+  /** Stable identity of the choice, used to resolve the Allfather's pick. */
+  value: string;
+  /** What the row shows, and what a search query is matched against. */
+  label: string;
+  /** Optional trailing note, such as marking the current choice. */
+  description?: string;
+}
+
+/** Signature of Pi's own `fuzzyFilter`, injected so this file stays UI-free. */
+export type BranchPickerFuzzyFilter = <T>(items: T[], query: string, getText: (item: T) => string) => T[];
+
+/**
+ * Rows the picker shows at once. Pi's own model selector shows ten, and the
+ * bound is what keeps a long catalog scrolling inside the dialog instead of
+ * overflowing the terminal.
+ */
+export const BRANCH_PICKER_MAX_VISIBLE = 10;
+
+/** The stable identity of the "follow main" row, which is always first. */
+export const FOLLOW_MAIN_VALUE = "\0follow-main";
+
+/**
+ * Builds the picker's rows: "follow main" first, then the eligible models in
+ * the order the caller resolved them. The current choice is marked so the
+ * Allfather can see what is pinned without leaving the dialog.
+ */
+export function buildBranchModelItems(
+  followMainLabel: string,
+  modelLabels: readonly string[],
+  currentPin: string | null,
+): BranchPickerItem[] {
+  const followMain: BranchPickerItem = {
+    value: FOLLOW_MAIN_VALUE,
+    label: followMainLabel,
+    ...(currentPin === null ? { description: "current" } : {}),
+  };
+  return [
+    followMain,
+    ...modelLabels.map((label) => ({
+      value: label,
+      label,
+      ...(currentPin !== null && label === currentPin ? { description: "current" } : {}),
+    })),
+  ];
+}
+
+/**
+ * Applies a search query while keeping "follow main" first. Pi's fuzzy filter
+ * ranks by match quality, which would otherwise be free to sort the "follow
+ * main" row below a model, so it is filtered separately and prepended
+ * whenever it still matches. An empty query keeps the built order.
+ */
+export function filterBranchPickerItems(
+  items: readonly BranchPickerItem[],
+  query: string,
+  fuzzy: BranchPickerFuzzyFilter,
+): BranchPickerItem[] {
+  const trimmed = query.trim();
+  if (trimmed === "") return [...items];
+  const followMain = items.find((item) => item.value === FOLLOW_MAIN_VALUE);
+  const rest = items.filter((item) => item.value !== FOLLOW_MAIN_VALUE);
+  const matched = fuzzy([...rest], trimmed, (item) => item.label);
+  if (!followMain) return matched;
+  const followMainMatches = fuzzy([followMain], trimmed, (item) => item.label).length > 0;
+  return followMainMatches ? [followMain, ...matched] : matched;
+}

package/.pi/extensions/lib/vordr-sessionstart-supervisor.mjs

@@ -0,0 +1,48 @@
+// Vörðr — session-start digest supervisor.
+//
+// Vörðr ("warden/guardian") is the thin process supervisor that runs the Sága
+// session-start digest as a detached child so Pi can stream and cap its output
+// without blocking the session open. Ported from the upstream agent-distro reference.
+import { spawn } from "node:child_process";
+
+const [runner, ...args] = process.argv.slice(2);
+let runnerCode;
+let outputBytes = 0;
+let pendingWrites = 0;
+let resultSent = false;
+
+const sendResult = () => {
+  if (resultSent || runnerCode === undefined || pendingWrites !== 0) return;
+  resultSent = true;
+  process.send?.({ type: "result", code: runnerCode, bytes: outputBytes });
+};
+
+process.on("SIGTERM", () => {});
+process.on("disconnect", () => {
+  try {
+    process.kill(-process.pid, "SIGKILL");
+  } catch {
+    process.exit(1);
+  }
+});
+
+const child = spawn(runner, args, {
+  env: { ...process.env, VORDR_SESSIONSTART_SUPERVISOR_PID: String(process.pid) },
+  stdio: ["ignore", "pipe", "ignore"],
+});
+child.stdout.on("data", (chunk) => {
+  outputBytes += chunk.length;
+  pendingWrites += 1;
+  process.stdout.write(chunk, () => {
+    pendingWrites -= 1;
+    sendResult();
+  });
+});
+child.on("error", () => {
+  runnerCode = null;
+  sendResult();
+});
+child.on("close", (code) => {
+  runnerCode = code;
+  sendResult();
+});