@uniqbit/mate-core 0.18.3-canary.1 → 0.18.4

package/src/opencode/session-prepare.ts

@@ -0,0 +1,139 @@
+import type { Cleanup, Context } from "@opencode/plugin/promise/plugin";
+
+import {
+  PREPARE_TIMEOUT_MS,
+  type PrepareRun,
+  type PrepareRunner,
+} from "../runtime/session-prepare-runner";
+import { recordSessionNotes, type SessionNotePhase } from "./session-notes";
+
+/**
+ * Plugin side of `mate session prepare`: a bare OpenCode session in a wrapped
+ * repo gets a managed launch's local prepare, then a background Git sync.
+ * Spawned, so a crash or stale module never reaches the shared service.
+ */
+
+export interface SessionPrepareOptions {
+  directory: string;
+  repoPath: string;
+  companionPath: string;
+  /** Mate-declared MCP servers; only these are held back until the local phase ends. */
+  mateServers: readonly string[];
+  run: PrepareRunner;
+  log?: (line: string) => void;
+  timeoutMs?: number;
+  debounceMs?: number;
+}
+
+const PREPARE_DEBOUNCE_MS = 5_000;
+
+/** Keyed by companion: several repositories, and several locations, share one companion. */
+const lastSynced = new Map<string, number>();
+
+/** Test seam: the debounce is process-wide. */
+export function resetPrepareDebounce(): void {
+  lastSynced.clear();
+}
+
+function logger(options: SessionPrepareOptions): (line: string) => void {
+  return options.log ?? ((line: string) => console.error(line));
+}
+
+/** Logs the notes and records them for the TUI's toast. */
+async function report(
+  options: SessionPrepareOptions,
+  run: PrepareRun,
+  phase: SessionNotePhase,
+): Promise<void> {
+  const log = logger(options);
+  const verdict = run.ok ? "warning" : "failed";
+  for (const note of run.notes) log(`mate: session ${phase} ${verdict}: ${note}`);
+  await recordSessionNotes(options.repoPath, phase, run.notes);
+}
+
+function failedRun(error: unknown): PrepareRun {
+  return { ok: false, notes: [error instanceof Error ? error.message : String(error)] };
+}
+
+/** No remote: OpenCode holds MCP servers and skills until `setup` returns. */
+async function prepareLocal(options: SessionPrepareOptions): Promise<void> {
+  const run = await options
+    .run({ sync: false, timeoutMs: options.timeoutMs ?? PREPARE_TIMEOUT_MS })
+    .catch(failedRun);
+  await report(options, run, "prepare");
+}
+
+/** Never awaited: the session runs on while the companion is fetched. */
+function startSync(api: Context, options: SessionPrepareOptions): void {
+  lastSynced.set(options.companionPath, Date.now());
+  void options
+    .run({ sync: true })
+    .catch(failedRun)
+    .then(async (run) => {
+      await report(options, run, "sync");
+      if (!run.changed) return;
+      await api.mcp.reload().catch(() => {});
+      logger(options)("mate: companion updated; MCP servers reloaded.");
+    });
+}
+
+function eventDirectory(event: unknown): string | undefined {
+  const record = event as {
+    location?: { directory?: string };
+    data?: { location?: { directory?: string } };
+  };
+  return record.location?.directory ?? record.data?.location?.directory;
+}
+
+/**
+ * Holds the Mate MCP servers back, runs the local phase before `setup`
+ * returns, releases them, then syncs the companion in the background; syncs
+ * again on new sessions of this location. Neither a failed nor a slow prepare
+ * keeps the session from starting, and none is ever terminated.
+ */
+export async function registerSessionPrepare(
+  api: Context,
+  options: SessionPrepareOptions,
+): Promise<Cleanup> {
+  const held = new Set(options.mateServers);
+  let gated = held.size > 0;
+  if (gated) {
+    await api.mcp.transform((editor) => {
+      if (!gated) return;
+      for (const name of held) {
+        if (editor.get(name)) {
+          editor.update(name, (config) => {
+            config.disabled = true;
+          });
+        }
+      }
+    });
+  }
+
+  try {
+    await prepareLocal(options);
+  } finally {
+    if (gated) {
+      gated = false;
+      await api.mcp.reload().catch(() => {});
+    }
+  }
+  startSync(api, options);
+
+  const controller = new AbortController();
+  const debounceMs = options.debounceMs ?? PREPARE_DEBOUNCE_MS;
+  void (async () => {
+    try {
+      for await (const event of api.event.subscribe({ signal: controller.signal })) {
+        if (event.type !== "session.created") continue;
+        if (eventDirectory(event) !== options.directory) continue;
+        const last = lastSynced.get(options.companionPath) ?? 0;
+        if (Date.now() - last < debounceMs) continue;
+        startSync(api, options);
+      }
+    } catch {
+      /* subscription closed: the location is shutting down */
+    }
+  })();
+  return () => controller.abort();
+}

package/src/opencode/tui.tsx

@@ -4,10 +4,10 @@
  * OpenCode V2 TUI plugin module (`{ id, setup }`), OpenCode 2.x only.
  * Solid JSX, not React: `key` is not a reconciliation prop here and `TextProps`
  * does not accept it, so the jsx-key rules cannot be satisfied — only suppressed.
- * Static arrays render through `.map`; a reactive one would need `<For>`.
+ * Arrays render through `.map`: Solid re-runs it whole on a store change, fine for a few lines.
  */
 import { mateVersion } from "../runtime/install";
-import { readContext } from "./companion-policy";
+import { readContext, readStalenessLines } from "./companion-policy";
 
 /** Minimal structural slice of the OpenCode V2 TUI API; the published SDK ships no V2 TUI types. */
 export type MateTuiApi = {
@@ -20,6 +20,14 @@ export type MateTuiApi = {
   };
   ui: {
     slot(claim: MateSlotClaim): () => void;
+    toast: { show(options: { title?: string; message: string; variant?: "warning" }): void };
+  };
+  storage: {
+    /** A host Solid store: reads inside a render are reactive. */
+    memory<Value extends object>(
+      key: string,
+      options: { readonly initial: Value },
+    ): readonly [Value, (mutation: (draft: Value) => void) => void];
   };
 };
 
@@ -31,13 +39,26 @@ export type MateSlotClaim = {
 
 export type MateTuiPluginModule = {
   id: string;
-  setup(api: MateTuiApi): void | Promise<void>;
+  setup(api: MateTuiApi): void | (() => void) | Promise<void | (() => void)>;
 };
 
+/** A background sync finishes after the first render; the lines must follow it. */
+export const STALENESS_POLL_MS = 5_000;
+
+type SessionNotes = { lines: string[] };
+
 const MIDNIGHT_PURPLE_BRIGHT = "#c084fc";
 const MATE_VERSION = process.env.MATE_VERSION ?? mateVersion();
 
-function SessionContext({ api, sidebar = false }: { api: MateTuiApi; sidebar?: boolean }) {
+function SessionContext({
+  api,
+  notes,
+  sidebar = false,
+}: {
+  api: MateTuiApi;
+  notes: SessionNotes;
+  sidebar?: boolean;
+}) {
   const context = readContext();
   const text = api.theme.text;
   const warning = text.feedback?.warning?.base ?? text.muted;
@@ -54,21 +75,47 @@ function SessionContext({ api, sidebar = false }: { api: MateTuiApi; sidebar?: b
       <text fg={MIDNIGHT_PURPLE_BRIGHT}>mate v{MATE_VERSION}</text>
       <text fg={text.muted}>repo: {context.repositoryPath}</text>
       <text fg={text.muted}>mate: {context.companionPath}</text>
-      {context.stalenessLines.map((note) => (
+      {notes.lines.map((note) => (
         <text fg={warning}>{note}</text>
       ))}
     </box>
   );
 }
 
-function setup(api: MateTuiApi): void {
+/** Polls the session lines; a line that appears after startup is also raised as a toast. */
+function setup(api: MateTuiApi): (() => void) | undefined {
   const context = readContext();
   if (!context.companionPath || !context.repositoryPath) {
-    return;
+    return undefined;
   }
 
-  api.ui.slot({ prepend: "home.footer", render: () => <SessionContext api={api} /> });
-  api.ui.slot({ append: "sidebar.content", render: () => <SessionContext api={api} sidebar /> });
+  const [notes, setNotes] = api.storage.memory<SessionNotes>("mate-session-notes", {
+    initial: { lines: context.stalenessLines },
+  });
+  setNotes((draft) => {
+    draft.lines = context.stalenessLines;
+  });
+  const timer = setInterval(() => {
+    const lines = readStalenessLines();
+    if (lines.join("\n") === notes.lines.join("\n")) return;
+    const shown = new Set(notes.lines);
+    const added = lines.filter((line) => !shown.has(line));
+    setNotes((draft) => {
+      draft.lines = lines;
+    });
+    for (const message of added) api.ui.toast.show({ title: "mate", message, variant: "warning" });
+  }, STALENESS_POLL_MS);
+  timer.unref?.();
+
+  api.ui.slot({
+    prepend: "home.footer",
+    render: () => <SessionContext api={api} notes={notes} />,
+  });
+  api.ui.slot({
+    append: "sidebar.content",
+    render: () => <SessionContext api={api} notes={notes} sidebar />,
+  });
+  return () => clearInterval(timer);
 }
 
 const plugin: MateTuiPluginModule = {

package/src/runtime/audience-layer.ts

@@ -0,0 +1,84 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+import { mateHome } from "./runtime-directory";
+
+/**
+ * Audience Layer locations. A layer holds one audience's plugin contributions
+ * for one companion, rendered for managed launches only. It lives under Mate's
+ * machine-local state, never inside a repository: a layer inside the companion
+ * would be readable by every session with companion access, and could carry
+ * values resolved from plugin configuration.
+ *
+ *   <state>/audience-layers/<companion-key>/<audience>/
+ *     <fingerprint>/   one complete render; never changed once renamed into place
+ *     current          symlink to the newest complete render
+ *
+ * A launch attaches the fingerprint directory itself, so a later re-render
+ * never changes what a running session reads.
+ */
+
+/** Mirrors `AUDIENCE_NAME_PATTERN`; repeated here because `runtime/` imports nothing from core. */
+const SAFE_AUDIENCE = /^[a-z][a-z0-9-]{0,63}$/;
+
+export const CURRENT_LAYER_LINK = "current";
+
+export function audienceLayersRoot(homeDir?: string): string {
+  return path.join(mateHome(homeDir), "state", "audience-layers");
+}
+
+/** A short, stable key for one companion checkout: a hash of its resolved path. */
+export function companionLayerKey(companionPath: string): string {
+  return crypto.createHash("sha256").update(path.resolve(companionPath)).digest("hex").slice(0, 16);
+}
+
+/** The directory holding one audience's layers for one companion. */
+export function audienceLayerDir(
+  companionPath: string,
+  audience: string,
+  homeDir?: string,
+): string {
+  if (!SAFE_AUDIENCE.test(audience)) {
+    throw new Error(`"${audience}" is not a valid audience name for a layer directory`);
+  }
+  return path.join(audienceLayersRoot(homeDir), companionLayerKey(companionPath), audience);
+}
+
+/** The newest complete layer of `audience`, or `null` when none was rendered on this machine. */
+export function currentAudienceLayer(
+  companionPath: string,
+  audience: string,
+  homeDir?: string,
+): string | null {
+  try {
+    const dir = audienceLayerDir(companionPath, audience, homeDir);
+    const layer = path.join(dir, fs.readlinkSync(path.join(dir, CURRENT_LAYER_LINK)));
+    return fs.existsSync(layer) ? layer : null;
+  } catch {
+    return null;
+  }
+}
+
+const MANAGED_MARKER = new RegExp(
+  `^<!-- ${FRAMEWORK_NAME}:managed:[^\\n]* (?:start|end) -->$`,
+  "gm",
+);
+
+/** A layer guidance document's text, managed-block markers removed; empty when absent. */
+export function layerGuidanceText(text: string): string {
+  return text
+    .replace(MANAGED_MARKER, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/** `file` (`CLAUDE.md`, `AGENTS.md`) of the layer at `root`, markers removed; empty when absent. */
+export function readLayerGuidanceSync(root: string, file: string): string {
+  try {
+    return layerGuidanceText(fs.readFileSync(path.join(root, file), "utf8"));
+  } catch {
+    return "";
+  }
+}

package/src/runtime/claude-delivery-plan.ts

@@ -0,0 +1,73 @@
+import type { ClaudeHookGroup } from "./claude-hook-group";
+import { NOT_WRAPPED, readWrapStateSync, type WrapState } from "./wrap-state";
+
+/**
+ * Claude Delivery Plan: the owner of each Claude contribution, as one pure
+ * function. Callers act on it and decide no ownership. In `runtime/` so hooks
+ * may import it.
+ */
+
+/**
+ * `managed-repo`: `mate claude` with a Working Repository; its prepare just
+ * reconciled the Claude wrap, which the launcher asserts. `managed-companion`:
+ * a companion-scoped launch. `unmanaged`: a session with no launch environment.
+ */
+export type SessionKind = "managed-repo" | "managed-companion" | "unmanaged";
+
+export interface ClaudeDeliveryPlan {
+  /** Capability hook groups; `launchSettingsExclude` is what `--settings` must not repeat. */
+  readonly hooks: {
+    readonly owner: "wrap" | "settings" | "none";
+    readonly launchSettingsExclude: readonly ClaudeHookGroup[];
+  };
+  /** Mate MCP servers. */
+  readonly mcp: "wrap" | "mcp-config" | "none";
+  /** Companion directory access. */
+  readonly dirAccess: "wrap" | "add-dir" | "none";
+  /** Wrap reconciliation. */
+  readonly reconcile: "attended-prepare" | "prepare-hook" | "none";
+  /** Companion Git synchronization. */
+  readonly gitSync: "launch-preflight" | "prepare-hook" | "banner";
+}
+
+export function planClaudeDelivery(kind: SessionKind, wrap: WrapState): ClaudeDeliveryPlan {
+  switch (kind) {
+    case "managed-repo":
+      return {
+        hooks: { owner: "wrap", launchSettingsExclude: wrap.carriedClaudeHookGroups },
+        mcp: "wrap",
+        dirAccess: "wrap",
+        reconcile: "attended-prepare",
+        gitSync: "launch-preflight",
+      };
+    case "managed-companion":
+      return {
+        hooks: { owner: "settings", launchSettingsExclude: [] },
+        mcp: "mcp-config",
+        dirAccess: "add-dir",
+        reconcile: "none",
+        gitSync: "launch-preflight",
+      };
+    case "unmanaged":
+      return wrap.runtimes.has("claude")
+        ? {
+            hooks: { owner: "wrap", launchSettingsExclude: [] },
+            mcp: "wrap",
+            dirAccess: "wrap",
+            reconcile: "prepare-hook",
+            gitSync: "prepare-hook",
+          }
+        : {
+            hooks: { owner: "none", launchSettingsExclude: [] },
+            mcp: "none",
+            dirAccess: "none",
+            reconcile: "none",
+            gitSync: "banner",
+          };
+  }
+}
+
+/** For session-start hooks: a plain session's plan from a lenient read; no root, not wrapped. */
+export function unmanagedClaudeDelivery(repoRoot: string | undefined): ClaudeDeliveryPlan {
+  return planClaudeDelivery("unmanaged", repoRoot ? readWrapStateSync(repoRoot) : NOT_WRAPPED);
+}

package/src/runtime/claude-hook-group.ts

@@ -0,0 +1,21 @@
+/**
+ * Claude hook-group shape and its one identity. A `runtime/` leaf so hooks and
+ * Wrap State can compare groups without loading setup code.
+ */
+
+export interface ClaudeHookCommand {
+  type?: string;
+  command?: string;
+  args?: string[];
+  timeout?: number;
+}
+
+export interface ClaudeHookGroup {
+  matcher?: string;
+  hooks?: ClaudeHookCommand[];
+}
+
+/** The one hook-group identity: structurally identical groups are the same group. */
+export function hookGroupKey(group: ClaudeHookGroup): string {
+  return JSON.stringify(group);
+}

package/src/runtime/companion-lock.ts

@@ -0,0 +1,121 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { mateHome } from "./runtime-directory";
+
+/**
+ * Per-companion lock under `<mate home>/locks/`, outside the companion's tree;
+ * repos share a companion, so a per-repo lock would race pulls. Re-entrant per
+ * async call chain, not per process.
+ */
+
+export interface CompanionLockOptions {
+  homeDir?: string;
+  /** `false` tries once and returns `acquired: false` at once when the lock is held. */
+  wait?: boolean;
+  /** How long to wait for another holder before giving up. */
+  timeoutMs?: number;
+  pollMs?: number;
+  /** Called once, when the lock is found held and the caller starts waiting. */
+  onWait?: () => void;
+}
+
+export type CompanionLockResult<T> = { acquired: true; value: T } | { acquired: false };
+
+function companionKey(companionPath: string): string {
+  let resolved = path.resolve(companionPath);
+  try {
+    resolved = fsSync.realpathSync(resolved);
+  } catch {
+    /* an unresolvable companion is still keyed by its spelling */
+  }
+  return crypto.createHash("sha256").update(resolved).digest("hex").slice(0, 32);
+}
+
+export function companionLockPath(companionPath: string, homeDir?: string): string {
+  return path.join(mateHome(homeDir), "locks", `${companionKey(companionPath)}.lock`);
+}
+
+const heldLocks = new AsyncLocalStorage<ReadonlySet<string>>();
+
+/** An unreadable holder id is only trusted this long, so a corrupt lock cannot block forever. */
+const UNREADABLE_LOCK_GRACE_MS = 10_000;
+
+async function holderAlive(lockPath: string, raw: string): Promise<boolean> {
+  const pid = Number.parseInt(raw.trim(), 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    const stat = await fs.stat(lockPath).catch(() => null);
+    return stat !== null && Date.now() - stat.mtimeMs < UNREADABLE_LOCK_GRACE_MS;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * The holder's pid is written to a private file first and hard-linked into
+ * place, so the lock never exists without its holder: a contender reading an
+ * empty file in between would otherwise take it as stale and remove it.
+ */
+async function tryAcquire(lockPath: string): Promise<boolean> {
+  const tempPath = `${lockPath}.${crypto.randomUUID()}.tmp`;
+  await fs.writeFile(tempPath, String(process.pid));
+  try {
+    await fs.link(tempPath, lockPath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  } finally {
+    await fs.rm(tempPath, { force: true });
+  }
+  const raw = await fs.readFile(lockPath, "utf8").catch(() => null);
+  if (raw === null || (await holderAlive(lockPath, raw))) return false;
+  /** A dead holder's lock is removed only if it is still the one just read. */
+  if ((await fs.readFile(lockPath, "utf8").catch(() => null)) === raw) {
+    await fs.rm(lockPath, { force: true });
+  }
+  return false;
+}
+
+/**
+ * Runs `task` while holding the companion's lock; `acquired: false` after the
+ * bounded wait, or at once with `wait: false`. A caller already holding it in
+ * this call chain runs `task` directly.
+ */
+export async function withCompanionLock<T>(
+  companionPath: string,
+  options: CompanionLockOptions,
+  task: () => Promise<T>,
+): Promise<CompanionLockResult<T>> {
+  const lockPath = companionLockPath(companionPath, options.homeDir);
+  const held = heldLocks.getStore() ?? new Set<string>();
+  if (held.has(lockPath)) return { acquired: true, value: await task() };
+
+  const timeoutMs = options.wait === false ? 0 : (options.timeoutMs ?? 30_000);
+  const pollMs = options.pollMs ?? 200;
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+
+  const deadline = Date.now() + timeoutMs;
+  let waiting = false;
+  // oxlint-disable-next-line no-await-in-loop -- polling is the point
+  while (!(await tryAcquire(lockPath))) {
+    if (Date.now() >= deadline) return { acquired: false };
+    if (!waiting) {
+      waiting = true;
+      options.onWait?.();
+    }
+    // oxlint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  try {
+    return { acquired: true, value: await heldLocks.run(new Set([...held, lockPath]), task) };
+  } finally {
+    await fs.rm(lockPath, { force: true });
+  }
+}

package/src/runtime/companion-sync.ts

@@ -30,6 +30,7 @@ import {
   type CompanionForkState,
   type CompanionGit,
 } from "./companion-git";
+import { withCompanionLock } from "./companion-lock";
 import { hasLaunchEnvironment } from "./env";
 import { FRAMEWORK_NAME } from "./framework";
 import { readCompanionPolicy } from "./policy";
@@ -37,10 +38,20 @@ import { readCompanionPolicy } from "./policy";
 /** The one command that finishes what the unattended half declines to do. */
 export const COMPANION_SYNC_COMMAND = `${FRAMEWORK_NAME} companion sync`;
 
+/** OpenCode's recovery is the managed launch: it runs the sync at a terminal that can answer Git. */
+export const OPENCODE_LAUNCH_COMMAND = `${FRAMEWORK_NAME} opencode`;
+
+/** A Claude-wrapped repository's equivalent: the attended launch reconciles the wrap. */
+export const CLAUDE_LAUNCH_COMMAND = `${FRAMEWORK_NAME} claude`;
+
+/** Which runtime's operator reads the note; it decides the recovery named. */
+export type StalenessAudience = "claude" | "opencode";
+
 /** A cold link costs this once; the recorded completion then suppresses retries. */
 export const COMPANION_SYNC_TIMEOUT_MS = 20_000;
 
-export type UnattendedSyncStatus = "not-applicable" | "fresh" | "complete" | "unfinished";
+/** `busy`: another operation held the companion lock; nothing ran and nothing is owed. */
+export type UnattendedSyncStatus = "not-applicable" | "fresh" | "busy" | "complete" | "unfinished";
 
 export interface UnattendedSyncOutcome {
   status: UnattendedSyncStatus;
@@ -58,6 +69,12 @@ export interface UnattendedSyncOptions {
   homeDir?: string;
   /** Environment Git runs with. */
   env?: Record<string, string | undefined>;
+  /**
+   * `wait` (the default) queues behind another holder of the companion lock,
+   * within the time budget; `try` skips at once, for a hook that must not
+   * stall a session start.
+   */
+  lock?: "wait" | "try";
 }
 
 const UNFINISHED_GIT_PATHS = [
@@ -115,6 +132,24 @@ export async function syncCompanionUnattended(
     return { status: "fresh", changed: false, companionPath };
   }
 
+  const locked = await withCompanionLock(
+    companionPath,
+    { homeDir, wait: options.lock !== "try", timeoutMs },
+    () => syncHoldingLock(companionPath, { timeoutMs, now, homeDir, env }),
+  );
+  return locked.acquired ? locked.value : { status: "busy", changed: false, companionPath };
+}
+
+async function syncHoldingLock(
+  companionPath: string,
+  options: {
+    timeoutMs: number;
+    now: Date;
+    homeDir?: string;
+    env?: Record<string, string | undefined>;
+  },
+): Promise<UnattendedSyncOutcome> {
+  const { timeoutMs, now, homeDir, env } = options;
   const git = companionGit(companionPath, {
     prompt: "never",
     budgetMs: timeoutMs,
@@ -191,13 +226,36 @@ export async function syncCompanionUnattended(
  * answer a credential prompt and no way to tell a fast-forward from a
  * conflicted rebase.
  */
-export function unattendedSyncStalenessLines(outcome: UnattendedSyncOutcome): string[] {
+export function unattendedSyncStalenessLines(
+  outcome: UnattendedSyncOutcome,
+  audience: StalenessAudience = "claude",
+): string[] {
   if (outcome.status !== "unfinished") return [];
+  const reason = outcome.reason ?? "unknown reason";
+  if (audience === "opencode") return launchRecoveryStalenessLines(outcome, ["opencode"]);
   return [
-    `companion Git synchronization unfinished: ${outcome.reason ?? "unknown reason"} — run \`${COMPANION_SYNC_COMMAND}\``,
+    `companion Git synchronization unfinished: ${reason} — run \`${COMPANION_SYNC_COMMAND}\``,
   ];
 }
 
+/**
+ * The note for a session prepare, naming the managed launch of each wrapped
+ * runtime as the recovery: it runs the sync at a terminal that can answer Git.
+ */
+export function launchRecoveryStalenessLines(
+  outcome: UnattendedSyncOutcome,
+  runtimes: readonly StalenessAudience[],
+): string[] {
+  if (outcome.status !== "unfinished") return [];
+  const reason = outcome.reason ?? "unknown reason";
+  const wrapped = new Set(runtimes);
+  const launches = [
+    ...(wrapped.has("claude") ? [CLAUDE_LAUNCH_COMMAND] : []),
+    ...(wrapped.has("opencode") || wrapped.size === 0 ? [OPENCODE_LAUNCH_COMMAND] : []),
+  ].map((command) => `\`${command}\``);
+  return [`Companion not updated: ${reason}. Restart with ${launches.join(" or ")} to fix it.`];
+}
+
 /**
  * The note a session-state reader surfaces, taken from the persisted record so
  * a render costs no Git. Operator-facing only, exactly as the live note is.
@@ -205,16 +263,15 @@ export function unattendedSyncStalenessLines(outcome: UnattendedSyncOutcome): st
 export function persistedCompanionGitStalenessLines(
   companionPath: string,
   homeDir?: string,
+  audience: StalenessAudience = "claude",
 ): string[] {
   if (!companionPath) return [];
   const reason = readCompanionGitRecord(companionPath, homeDir).unfinishedReason;
   if (!reason) return [];
-  return unattendedSyncStalenessLines({
-    status: "unfinished",
-    changed: false,
-    companionPath,
-    reason,
-  });
+  return unattendedSyncStalenessLines(
+    { status: "unfinished", changed: false, companionPath, reason },
+    audience,
+  );
 }
 
 export interface ForkGuardOptions {